docs: sync review directive dimensions from distillery proof-2 (comment contract, minimal touch, contract conformance, verification honesty, least privilege) #482

New issue

Closed

opened 2026-08-09 05:05:04 +00:00 by igor · 0 comments

igor commented

2026-08-09 05:05:04 +00:00

Collaborator

Distillery (the context brain, joshtronic/distillery) has dialed in the shadow reviewer's dimensions at proof-2; igor's live copy must match. One exact replacement in bin/lib/review-directive.md. The new dimensions come from operator direction plus review-pattern mining: doc comments legitimized, minimal-touch enforcement, contracts checked not vibed, verification honesty, least privilege.

Deliverables

In bin/lib/review-directive.md, replace the entire "Comment bloat." bullet (begins - **Comment bloat.** Comments earn their place only and ends -- don't wave it through as a style nit.) with the following five bullets:

- **Comment contract.** Exactly two comment kinds are legal: standard
  API doc comments in the language's convention (JSDoc, godoc,
  docstrings) on public surfaces, and short *why* comments (a
  constraint, an invariant, a workaround). Everything else is a
  finding with the same standing as any other: comments narrating
  *what* the next line does, changelog-style comments ("added X for
  Y"), restated names in prose, review residue ("addressed
  feedback"), and comments that duplicate the diff or belong in the
  PR description instead of the code. Doc comments are NOT bloat --
  don't flag a conventional JSDoc block for existing. If what-comment
  noise is pervasive across the diff, that's grounds for
  REQUEST_CHANGES on it alone -- don't wave it through as a style nit.
- **Minimal touch.** The diff should contain nothing the task doesn't
  require. Reformatting of lines the change doesn't own, drive-by
  renames, cleanup for its own sake, and "while I was here" fixes are
  findings even when each individual change is an improvement -- the
  place for noticing unrelated problems is the PR body, not the diff.
- **Contract conformance is checked, never vibed.** When the repo or
  the harness defines a checkable contract -- the AGENTS.md dossier
  spec, the PR_BODY.md shape, the ticket skeleton, the comment
  contract above -- verify the artifact against the contract's actual
  rules and cite the rule when flagging. A defined contract reviewed
  on general impressions is a review that didn't happen.
- **Verification honesty.** Every verification claim states its
  method, and the method must support the claim: "tests pass" names
  which tests; a claim verified only by code inspection says so
  rather than presenting as tested; anything the author could not
  verify is an unchecked box with a reason, not a checked one. Flag
  claims whose stated method couldn't actually demonstrate the claim,
  and name what you yourself could not verify from the diff rather
  than silently assuming it.
- **Least privilege.** A change that widens what anything can do --
  permission profiles, token scopes, workflow triggers, allowlists,
  network access -- gets scrutiny proportional to the widening, and
  the narrowest scope that serves the task is the bar. "It needs
  write" is a claim to verify against the code path, not accept.

Out of scope

Any other part of the directive (verdict contract, sentinel format, escalation rules), any code, any other file. One-hunk prose sync.

Verification

make test passes.
git diff shows exactly one hunk in exactly one file.

Notes

This is a prompt surface: treat the merge like a deploy (it goes live on the next tick after merge).

Distillery (the context brain, joshtronic/distillery) has dialed in the shadow reviewer's dimensions at proof-2; igor's live copy must match. One exact replacement in `bin/lib/review-directive.md`. The new dimensions come from operator direction plus review-pattern mining: doc comments legitimized, minimal-touch enforcement, contracts checked not vibed, verification honesty, least privilege. ## Deliverables 1. In `bin/lib/review-directive.md`, replace the entire "**Comment bloat.**" bullet (begins `- **Comment bloat.** Comments earn their place only` and ends `-- don't wave it through as a style nit.`) with the following five bullets: ``` - **Comment contract.** Exactly two comment kinds are legal: standard API doc comments in the language's convention (JSDoc, godoc, docstrings) on public surfaces, and short *why* comments (a constraint, an invariant, a workaround). Everything else is a finding with the same standing as any other: comments narrating *what* the next line does, changelog-style comments ("added X for Y"), restated names in prose, review residue ("addressed feedback"), and comments that duplicate the diff or belong in the PR description instead of the code. Doc comments are NOT bloat -- don't flag a conventional JSDoc block for existing. If what-comment noise is pervasive across the diff, that's grounds for REQUEST_CHANGES on it alone -- don't wave it through as a style nit. - **Minimal touch.** The diff should contain nothing the task doesn't require. Reformatting of lines the change doesn't own, drive-by renames, cleanup for its own sake, and "while I was here" fixes are findings even when each individual change is an improvement -- the place for noticing unrelated problems is the PR body, not the diff. - **Contract conformance is checked, never vibed.** When the repo or the harness defines a checkable contract -- the AGENTS.md dossier spec, the PR_BODY.md shape, the ticket skeleton, the comment contract above -- verify the artifact against the contract's actual rules and cite the rule when flagging. A defined contract reviewed on general impressions is a review that didn't happen. - **Verification honesty.** Every verification claim states its method, and the method must support the claim: "tests pass" names which tests; a claim verified only by code inspection says so rather than presenting as tested; anything the author could not verify is an unchecked box with a reason, not a checked one. Flag claims whose stated method couldn't actually demonstrate the claim, and name what you yourself could not verify from the diff rather than silently assuming it. - **Least privilege.** A change that widens what anything can do -- permission profiles, token scopes, workflow triggers, allowlists, network access -- gets scrutiny proportional to the widening, and the narrowest scope that serves the task is the bar. "It needs write" is a claim to verify against the code path, not accept. ``` ## Out of scope - Any other part of the directive (verdict contract, sentinel format, escalation rules), any code, any other file. One-hunk prose sync. ## Verification - `make test` passes. - `git diff` shows exactly one hunk in exactly one file. ## Notes - This is a prompt surface: treat the merge like a deploy (it goes live on the next tick after merge).

igor added the

Agent

label

2026-08-09 05:05:04 +00:00

igor self-assigned this

2026-08-09 05:12:49 +00:00

igor referenced this issue from a pull request that will close it,

2026-08-09 05:15:19 +00:00

docs: sync review directive comment/scope dimensions from distillery proof-2 #484

igor added spent time

2026-08-09 05:15:20 +00:00

2 minutes 15 seconds