* test(#3806): add parity tests for the Review Dispositions Ledger contract Failing-first: asserts references/planner-reviews.md, workflows/plan-phase.md, and agents/gsd-plan-checker.md agree on a single canonical "Review Dispositions Ledger" heading, its round-scoping, L##@{sha} anchor format, and append-only supersession rule. These fail until the canon and its two references are added. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * feat(#3806): canonize the Review Dispositions Ledger contract Promote the existing planner-reviews.md Step 4 return-payload tables (Review Feedback Addressed/Deferred) into a canonical `## Review Dispositions Ledger` PLAN.md section, stated once in planner-reviews.md and referenced (not restated) from plan-phase.md's <review_incorporation_contract> and gsd-plan-checker.md's Review Incorporation dimension. Adds round-scoping (`### Round {N} — {REVIEWS_sha}`), a `L##@{sha}` line-anchor format so a REVIEWS.md reference survives the file being rewritten each round, and an append-only supersession rule. Scoped to part 1 only per the maintainer's approved-feature verdict — the deterministic lint/check verb (part 2) is explicitly deferred to a follow-up. Also: ADR-3806 recording the decision, a docs/features/ fragment (FEATURES.md is generated), and a changeset fragment. Closes #3806 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#3806): fenced-example count bug and lint findings from review - tests/plan-review-convergence.test.cjs: the "heading exactly once" test counted the canonical heading text globally, so it also matched the illustrative fenced-code example in planner-reviews.md that shows the same heading as sample content, always failing 2 !== 1. Rewritten as a bounded line scanner that skips fenced blocks (found by an isolated adversarial review pass). Also bounded an unbounded regex quantifier over readFileSync content flagged by local/no-unbounded-quantifier. - docs/features/review-dispositions-ledger.md: match house fragment style (bold-lead paragraphs, not #### headings) per the Standards-axis review; regenerated docs/FEATURES.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#3806): fit reference-cite fix within size hard caps; ack growth Trims the plan-phase.md / gsd-plan-checker.md reference-cite text to a single short clause pointing at gsd-core/references/planner-reviews.md (also fixes the bare `references/planner-reviews.md` cite the #3576 shipped-reference-cites gate rejects), bringing both files back under their SIZE hard caps and the plan-phase.md phase6 shrink-only baseline. Both files still grow slightly versus origin/next, acknowledged below per ADR-2719's emitted-drift-ack contract. Emitted-Drift-Ack-Growth: gsd-plan-checker.md — adds a short pointer (in the existing Review Incorporation bullet) to the canonical Review Dispositions Ledger location (#3806); stays within the LARGE hard cap. Emitted-Drift-Ack-Growth: plan-phase.md — adds a short pointer (in the existing review_incorporation_contract bullet) to the canonical Review Dispositions Ledger location (#3806); stays under the XL hard cap and the phase6 shrink-only baseline. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#3806): correct malformed Emitted-Drift-Ack-Growth trailer block The previous commit's two Emitted-Drift-Ack-Growth trailers were separated from the Co-Authored-By trailer by a blank line, so git's own trailer parser (which tests/helpers/emitted-runtime.cjs reads via `%(trailers:key=...)`) only recognized the last contiguous block (Co-Authored-By) and treated the Ack-Growth lines as ordinary body text — invisible to the emitted-attribution gate, not malformed data. Restating them here as one contiguous trailer block, git log over the PR range aggregates trailers from every commit, so this is additive. Emitted-Drift-Ack-Growth: gsd-plan-checker.md — adds a short pointer (in the existing Review Incorporation bullet) to the canonical Review Dispositions Ledger location (#3806); stays within the LARGE hard cap. Emitted-Drift-Ack-Growth: plan-phase.md — adds a short pointer (in the existing review_incorporation_contract bullet) to the canonical Review Dispositions Ledger location (#3806); stays under the XL hard cap and the phase6 shrink-only baseline. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#3806): isolate the ack-trailer paragraph as its own trailer block Git's trailer parser requires the trailer paragraph to be the message's final paragraph, preceded by a blank line, and to contain nothing but trailer-shaped lines. The prior commit's blank line before the trailer lines was missing, which folded the leading Emitted-Drift-Ack-Growth lines into an ordinary prose paragraph. Emitted-Drift-Ack-Growth: gsd-plan-checker.md — adds a short pointer (in the existing Review Incorporation bullet) to the canonical Review Dispositions Ledger location (#3806); stays within the LARGE hard cap. Emitted-Drift-Ack-Growth: plan-phase.md — adds a short pointer (in the existing review_incorporation_contract bullet) to the canonical Review Dispositions Ledger location (#3806); stays under the XL hard cap and the phase6 shrink-only baseline. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(#3806): backfill PR #4345 into changeset and ADR Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -40,3 +40,50 @@ Use standard PLANNING COMPLETE return format, adding a reviews section:
|
||||
|---------|--------|
|
||||
| {concern} | {why — out of scope, disagree, etc.} |
|
||||
```
|
||||
|
||||
### Step 5: Write the ledger into PLAN.md (#3806)
|
||||
|
||||
The two tables above are not only the planner's return payload — they are also the **canonical
|
||||
Review Dispositions Ledger**, and they belong in the affected PLAN.md itself, in this exact shape.
|
||||
`gsd-core/workflows/plan-phase.md` (`<review_incorporation_contract>`) and
|
||||
`agents/gsd-plan-checker.md` (Review Incorporation dimension) both point back to this section for
|
||||
the ledger's shape rather than restating it — this is the one place it is defined.
|
||||
|
||||
## Review Dispositions Ledger
|
||||
|
||||
Add or extend a `## Review Dispositions Ledger` section in the affected PLAN.md, containing one
|
||||
`### Round {N} — {REVIEWS_sha}` subsection per reviews-mode round that touched this plan, where
|
||||
`{REVIEWS_sha}` is the commit that wrote the REVIEWS.md snapshot being ruled on (the short sha from
|
||||
`git log -1 --format=%h -- <phase_dir>/<NN>-REVIEWS.md`, after `workflows/review.md`'s REVIEWS.md
|
||||
commit step). Under each round heading, use the two tables from Step 4 above, unchanged in shape:
|
||||
|
||||
```markdown
|
||||
## Review Dispositions Ledger
|
||||
|
||||
### Round 1 — a1b2c3d
|
||||
|
||||
### Review Feedback Addressed
|
||||
| Concern | Severity | How Addressed |
|
||||
|---------|----------|---------------|
|
||||
| {concern} | HIGH | Plan {N}, Task {M}: {how} |
|
||||
|
||||
### Review Feedback Deferred
|
||||
| Concern | Reason |
|
||||
|---------|--------|
|
||||
| {concern} | {why — out of scope, disagree, etc.} |
|
||||
```
|
||||
|
||||
**Anchoring.** Any reference to a specific REVIEWS.md line cites `L##@{REVIEWS_sha}` (e.g.
|
||||
`L32@a1b2c3d`) — a bare line number is meaningless once the next round rewrites REVIEWS.md
|
||||
wholesale. `{Concern}` and `{Reason}` stay free text; do not invent a reviewer/severity enum — the
|
||||
reviewer roster is capability-owned and open to third-party additions (see each capability's
|
||||
`reviewer.reviewsSection`).
|
||||
|
||||
**Append-only.** A later round never edits or deletes a prior round's tables. To overturn a prior
|
||||
round's verdict, add a new row in the current round's table whose Reason/How Addressed names the
|
||||
round and concern it supersedes (e.g. "Supersedes Round 1 Deferred: {concern} — now addressed in
|
||||
Plan 3").
|
||||
|
||||
**Out of scope for this contract.** A deterministic lint/check verb that mechanically enforces this
|
||||
shape is a separate, later addition (#3806 part 2) — this section defines the format only. Legacy
|
||||
PLAN.md content written before this convention existed is not migrated or flagged by it.
|
||||
|
||||
@@ -785,7 +785,7 @@ ${AGENT_SKILLS_PLANNER}
|
||||
|
||||
For each current actionable finding in REVIEWS.md, the planner MUST either:
|
||||
- incorporate it into a PLAN.md task, `<action>`, `<acceptance_criteria>`, `<verify>`, `must_haves`, threat model, or artifact list; or
|
||||
- explicitly document a deferral/rejection rationale in the relevant PLAN.md so the executor and reviewer can see the decision.
|
||||
- explicitly document a deferral/rejection rationale in the relevant PLAN.md, using the Review Dispositions Ledger in `gsd-core/references/planner-reviews.md`.
|
||||
|
||||
Historical findings already incorporated, explicitly deferred/rejected in PLAN.md, or marked fully resolved do not require new plan changes.
|
||||
</review_incorporation_contract>
|
||||
|
||||
Reference in New Issue
Block a user