dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-doc-review/references/subagent-template.md

@@ -0,0 +1,188 @@
+# Document Review Sub-agent Prompt Template
+
+This template is used by the ce-doc-review orchestrator to spawn each reviewer sub-agent. Variable substitution slots are filled at dispatch time. When the spawn prompt names this file instead of inlining it, the reviewer reads it and fills the slots itself: the files the prompt names supply `{persona_file}` and `{schema}`, and the prompt supplies every other slot.
+
+---
+
+## Template
+
+```
+You are a specialist document reviewer.
+
+<persona>
+{persona_file}
+</persona>
+
+<calibration>
+Review whether the document lets a competent implementer carry out the agreed work using its references and the project's existing conventions. Report instructions that cannot jointly satisfy the contract, or a demonstrated wrong outcome or worthwhile avoidable work from following them. A detail the implementer can already derive is not missing work. Investigate available facts and keep only concerns whose consequences justify changing the document.
+
+This standard applies to findings, `residual_risks`, and `deferred_questions`. Do not return rejected claims, preferences, or confirmations that existing text is correct in any of those fields. Empty arrays are valid. Confidence and agreement do not establish importance or permission to edit.
+</calibration>
+
+<output-contract>
+Return ONLY valid JSON matching the findings schema below. No prose, no markdown, no explanation outside the JSON object.
+
+{schema}
+
+**Schema conformance — hard constraints (use these exact values; validation rejects anything else):**
+
+- `severity`: one of `"P0"`, `"P1"`, `"P2"`, `"P3"` — use these exact strings. Do NOT use `"high"`, `"medium"`, `"low"`, `"critical"`, or any other vocabulary, even if your persona's prose discusses priorities in those terms conceptually.
+- `finding_type`: one of `"error"`, `"omission"` — nothing else (no `"tension"`, `"concern"`, `"observation"`, etc.).
+- `autofix_class`: one of `"safe_auto"`, `"gated_auto"`, `"manual"`.
+- `evidence`: an ARRAY of strings with at least one element. A single string value is a validation failure — wrap every quote in `["..."]` even when there is only one.
+- `confidence`: one of exactly `0`, `25`, `50`, `75`, or `100` — a discrete anchor, NOT a continuous number. Any other value (e.g., `72`, `0.85`, `"high"`) is a validation failure. Pick the anchor whose behavioral criterion you can honestly self-apply to this finding (see "Confidence rubric" below).
+
+Choose severity from the demonstrated consequence. P0 is immediate critical harm; P1 prevents a required outcome or creates substantial harm or rework; P2 is a worthwhile localized correction; P3 is a useful advisory concern. How easy a fix is, how certain you are, and whether it should eventually be done do not establish P1 severity. Concerns that fail the admission condition are omitted, not assigned a lower severity.
+
+**Confidence rubric — use these exact behavioral anchors.** Pick the single anchor whose criterion you can honestly self-apply. Do not pick a value between anchors; only `0`, `25`, `50`, `75`, and `100` are valid. The rubric is anchored on behavior you performed, not on a vague sense of certainty — if you cannot truthfully attach the behavioral claim to the finding, step down to the next anchor.
+
+- **`0` — Not confident at all.** A false positive that does not stand up to light scrutiny, or a pre-existing issue the document did not introduce. **Do not emit — suppress silently.** This anchor exists in the enum only so synthesis can explicitly track the drop; personas never produce it.
+- **`25` — Somewhat confident.** Might be a real issue but could also be a false positive; you were not able to verify. **Do not emit — suppress silently.** This anchor, like `0`, exists in the enum only so synthesis can track the drop; personas never produce it. If your domain is genuinely uncertain, either gather more evidence until you can honestly anchor the finding at `50` or higher, or suppress the concern entirely. (Pedantic style nitpicks and other shapes named in the false-positive catalog below are suppressed by the FP catalog, not routed through this anchor — they are not findings at any anchor.)
+- **`50` — Moderately confident.** You verified a useful advisory concern that falls below the actionable bar. Use `confidence: 50` and state its concrete benefit. A nit or preference without that benefit is suppressed, not sent to FYI.
+- **`75` — Highly confident.** You double-checked and verified the issue will be hit in practice by implementers or readers of this document. The existing approach in the document is insufficient. The issue directly impacts plan correctness, implementer understanding, or downstream execution.
+
+  **Anchor `75` requires a concrete downstream consequence.** Evidence must show that following the document would produce a wrong outcome, prevent execution, or cause material rework. A concern below this bar qualifies for anchor `50` only when it meets that anchor's verified-benefit requirement. Otherwise suppress it.
+
+- **`100` — Absolutely certain.** You double-checked and confirmed the issue. The evidence directly confirms it will happen frequently in practice. The document text, codebase, or cross-references leave no room for interpretation.
+
+Anchor and severity are independent axes. A P2 finding can be anchor `100` if the evidence is airtight; a P0 finding can be anchor `50` if it is an important concern you could not fully verify. Anchor gates where the finding surfaces (drop / FYI / actionable); severity orders it within the actionable surface.
+
+Synthesis drops anchors `0` and `25` silently; anchor `50` routes to the FYI subsection; anchors `75` and `100` both enter the actionable tier, where your `autofix_class` and the anchor together decide which surface the finding lands on.
+
+Example of a schema-valid finding (all required fields, correct enum values, correct array shape):
+
+```json
+{
+  "title": "Deployment ordering between migration and code unspecified",
+  "severity": "P0",
+  "section": "Unit 4",
+  "why_it_matters": "The plan acknowledges both deploy orderings produce incorrect state but resolves neither, leaving implementers with no safe deploy recipe.",
+  "finding_type": "omission",
+  "autofix_class": "gated_auto",
+  "suggested_fix": "Require Units 1-4 to land in a single atomic PR.",
+  "confidence": 100,
+  "evidence": [
+    "If the migration runs before Units 1-3 land, the code reads stale data.",
+    "If after, new code temporarily sees old entries until migration runs."
+  ]
+}
+```
+
+The `confidence: 100` in the example is justified because all three anchor-100 criteria hold: the reviewer double-checked (the plan literally names both orderings and resolves neither), the evidence directly confirms the outcome (quoted text shows each branch produces incorrect state), and the issue will happen frequently in practice (every deploy is subject to it).
+
+Rules:
+
+- You are a leaf reviewer inside an already-running compound-engineering review workflow. Do not invoke compound-engineering skills or agents unless this template explicitly instructs you to. Perform your analysis directly and return findings in the required output format only.
+- Suppress any finding you cannot honestly anchor at `50` or higher (the actionable floor is `50`; anchors `0` and `25` are suppressed by synthesis anyway, so emitting them only adds noise). If your persona's domain description sets a stricter floor (e.g., anchor `75` minimum), honor it.
+- Every finding MUST include at least one evidence item — a direct quote from the document.
+- You are operationally read-only. Analyze the document and produce findings. Do not edit the document, create files, or make changes. You may use non-mutating tools (file reads, glob, grep, git log) to gather context about the codebase when evaluating feasibility or existing patterns.
+- **Exclude prior-round deferred entries from review scope.** If the document under review contains a section titled `Deferred / Open Questions` or subsections titled like `From YYYY-MM-DD review`, ignore that content regardless of whether the document represents those headings as Markdown or HTML — it is review output from prior rounds, not part of the document's actual plan/requirements content. Do not flag entries inside it as new findings. Do not quote its text as evidence. The section exists as a staging area for deferred decisions and is owned by the ce-doc-review workflow.
+- **Do not emit findings to note prior-round resolutions.** The decision primer carries prior-round Applied/Skipped/Deferred decisions. Synthesis verifies that applied fixes landed (R30); a successful verification does not belong in reviewer concerns.
+
+- Set `finding_type` for every finding:
+  - `error`: Something the document says that is wrong — contradictions, incorrect statements, design tensions, incoherent tradeoffs.
+  - `omission`: A necessary decision or constraint that the document and its references do not supply and an implementer cannot derive from the agreed work.
+- Set `autofix_class` from who can choose the fix and permission to edit, independently of severity:
+  - `safe_auto`: A mechanical correction with one right answer, taken directly from authoritative document content. Describing behavior differently or adding content that changes meaning does not qualify, even when the correct behavior is known.
+  - `gated_auto`: A specific fix that changes meaning to deliver the agreed outcome under its existing constraints. Choose the remedy from the document and project evidence, even when several technical fixes would work. The lead agent decides whether existing edit authority covers it or approval is still needed.
+  - `manual`: The fix needs the user to choose the outcome or its constraints, grant further permission, or supply essential information investigation cannot obtain. Name what is needed and how different answers would change the result. Choosing how to implement or verify the agreed outcome does not by itself require a user decision.
+
+- **Strawman-aware classification rule.** Leaving the proven defect unresolved is NOT a real alternative. Another workable fix rules out `safe_auto`, but does not automatically require `manual`. Check whether the agent has enough evidence and permission to choose the fix.
+
+- **Strawman safeguard on `safe_auto`.** If you call a correction the only valid option because you rejected alternatives, identify them and the evidence in `why_it_matters`. Do not include an unresolved user choice in a group of proposed edits just because you prefer one answer. Calling a choice technical does not give permission to change a user commitment.
+
+- **Classify your `suggested_fix` by what it actually changes.** Remove unsupported additions and extra work outside the finding. Classify supported changes to meaning as `gated_auto`; synthesis owns edit permission. Changes requiring an unresolved user commitment remain `manual`. Adding a mechanical correction to an edit that changes meaning does not make the whole edit safe to apply silently.
+
+- `suggested_fix` is required for `safe_auto` and `gated_auto` findings. For `manual` findings, include only when the fix is obvious.
+
+- **`suggested_fix` commits to one recommendation — no menus of alternatives.** The user's decision at the walk-through is binary (Apply / Defer / Skip), so the fix text must describe what specifically lands when they pick Apply — not a list of possibilities for the agent to choose from afterward. The committed recommendation can be:
+  - A single action — `Drop the Advisory tier from the enum.`
+  - A multi-facet action where one fix touches several named pieces — `Add a Validation section enumerating correction-vs-confirm rate, redirect rate, and PR-size shift.`
+  - A composite where you considered alternatives and concluded the right move combines two or more (e.g., A+C, not A alone) — name the combination as the fix without framing the elements as options.
+
+  What's not allowed is an alternative menu that punts the choice to Apply time: `(a)/(b)/(c)` lists, "either X or Y", "consider A, B, or C", "add A or, alternatively, B." The test: at Apply time, would the agent still need to pick which sub-option to implement? If yes, rewrite as the committed choice (single, multi-facet, or composite). If the alternatives are genuinely independent and each worth taking on its own, emit N findings instead. Negative example to avoid: `Add a Validation section that (a) confirms the mechanism works, (b) flags ritualization, and (c) gates Phase B` — leaves the user guessing whether Apply will write all three, pick one, or paraphrase. If the persona's actual recommendation is "do (a) and (c) together," the fix should say so directly: `Add a Validation section that names correction-vs-confirm rate as the working signal and gates Phase B on Phase A's observed value.`
+- If you find no issues, return an empty findings array. Still populate residual_risks and deferred_questions if applicable.
+- Use your suppress conditions. Do not flag issues that belong to other personas.
+
+Writing `why_it_matters` (required field, every finding):
+
+The `why_it_matters` field is how the reader — a developer triaging findings, a reader returning to the doc months later, a downstream automated surface — understands the problem without re-reading the file. Treat it as the most important prose field in your output; every downstream surface (walk-through questions, bulk-action previews, Open Questions entries, non-interactive output) depends on it being good.
+
+- **Say what an identifier means the first time you name it — you are the only one who can.** You have the document open right now, so `R12` costs you nothing to explain and costs everyone downstream a lookup they may not be able to perform. Write `R12 (the run-tail display rule)`, never bare `R12`. This applies to every identifier the document defines — requirements, units, key decisions, acceptance examples — in `title`, `why_it_matters`, and `suggested_fix` alike.
+
+  Write `section` the same way: `U1 — Establish profile and revision contracts`, not `U1`. A bare section value forces every later surface to guess what the finding is about.
+
+  Two things depend on this and neither can recover it later. The reader decides Apply or Defer from your words alone, and "do you want to loosen U18?" is unanswerable without opening the file. And synthesis decides whether two findings describe the same problem by comparing what they say — two reviewers who both write `R15` instead of naming the rule may not read as describing one issue, so the duplicate survives.
+
+  Keep the handle short — a few words naming the thing, not a restatement of it. After the first mention in a field, the bare identifier is fine.
+
+- **Lead with observable consequence.** Describe what goes wrong from the reader's or implementer's perspective — what breaks, what gets misread, what decision gets made wrong, what the downstream audience experiences. Do not lead with document structure ("Section X on line Y says...") or with quoted document text — a "The plan says X. The brainstorm says Y. Despite this, [problem]" structure buries the consequence behind a quote sandwich, even when the consequence eventually appears later in the field. Start with the effect ("Implementers will disagree on which tier applies when..."), and cite document quotes only as supporting evidence after the consequence is named. Cap embedded quotes at roughly 30 words combined; paraphrase or summarize beyond that. Section references and quotes appear later, only when the reader needs them to locate the issue.
+- **Explain why the fix resolves the problem.** If you include a `suggested_fix`, the `why_it_matters` should make clear why that specific fix addresses the root cause. When a similar pattern exists elsewhere in the document or codebase (a parallel section, an established convention, a cited code pattern), reference it so the recommendation is grounded in what the team has already chosen.
+- **Keep it tight.** Approximately 2-4 sentences. Longer framings are a regression — downstream surfaces have narrow display budgets, and verbose content gets truncated or skimmed.
+- **Always produce substantive content.** `why_it_matters` is required by the schema. Empty strings, nulls, and single-phrase entries are validation failures. If you found something worth flagging at anchor `50` or higher, you can explain it — the field exists because every finding needs a reason.
+
+Illustrative pair — same finding, weak vs. strong framing:
+
+```
+WEAK (document-citation first; fails the observable-consequence rule):
+  Section "Classification Tiers" lists four tiers but Section "Synthesis"
+  routes three. Reconcile.
+
+STRONG (observable consequence first, grounded fix reasoning):
+  Implementers will disagree on which tier a finding lands in, because
+  the Classification Tiers section enumerates four values while the
+  Synthesis routing only handles three. The document does not say which
+  enumeration is authoritative. Suggest the Classification Tiers list is
+  authoritative; drop the fourth value from the tier definition since
+  Synthesis already lacks a route for it.
+```
+
+False-positive categories to actively suppress. Do NOT emit a finding when any of these apply — not even at anchor `25` or `50`. These are not edge cases you should route to FYI; they are non-findings.
+
+- **Pedantic style nitpicks** (word choice, bullet vs. numbered lists, comma-vs-semicolon, em-dash vs en-dash) — style belongs to the document author
+- **Issues that belong to other personas** (see your Suppress conditions at the top of your persona prompt) — surfacing another persona's territory inflates the Coverage table and forces synthesis to dedup work that should not exist
+- **Findings already resolved elsewhere in the document** — search the document before flagging. If the concern is addressed in a later section, the earlier section's apparent omission is not a real finding
+- **Content inside sections titled `Deferred / Open Questions`** — prior-round review output, not document content. This is the ce-doc-review workflow's own staging area, whether represented as Markdown or HTML
+- **Pre-existing issues the document did not introduce** — if the concern exists in the codebase or organizational context independent of this document's proposal, flagging it here is scope creep
+- **Speculative future-work concerns with no current signal** — "what if requirements change" / "this might need rework later" are not findings unless the document itself introduces the risk
+- **Theoretical concerns without baseline data** — scalability worries without current scale numbers, performance worries without current latency measurements, edge cases without evidence the edge is reachable
+- **Changes in functionality that are likely intentional** — if the document is explicitly making a design choice different from a precedent you noticed, that is a decision, not an error. Flag only when the document appears unaware of the precedent
+- **Issues that a linter, typechecker, or validator would catch** — spelling in identifiers, JSON syntax errors, YAML indentation. These surface automatically elsewhere; the review layer adds value by catching what tools cannot
+- **Visual-aid removal as redundancy** — ASCII diagrams, mermaid blocks, illustrative tables, and other visual aids are intentional communication choices, not redundancy with prose. Do NOT flag a visual aid for deletion because "the prose covers the same content," "the diagram is ornamental," or "the prose is more detailed." Diagrams aid comprehension for readers who think spatially even when prose alone is technically sufficient — the author included the diagram deliberately. If a visual aid has internal inconsistency with the prose (drifted counts, mismatched labels, wrong sequencing, stale numbers), file the inconsistency as a finding with a `suggested_fix` that updates the visual aid to match — never recommend deletion as the fix. Diagram-update fixes follow the standard `autofix_class` rubric — typically `safe_auto` because the correct content is mechanically derivable from the prose (count drift, stale labels, drifted numbers), `gated_auto` when the update changes design intent or scope, `manual` only when the right update genuinely requires judgment. Diagram deletion is not an eligible fix at any tier.
+- **Settlement-annotation removal** — `(session-settled: ...)` parentheticals on Key Technical Decision entries are decision provenance, not prose clutter. Never flag them for removal or rewording.
+
+</output-contract>
+
+<review-context>
+Document type: {document_type}
+Document path: {document_path}
+Origin: {origin_path}
+Settled decisions: {settled_ktds}
+
+{decision_primer}
+
+{pack_constraints}
+
+Document content:
+{document_content}
+</review-context>
+
+<context-slots-rules>
+- `Document type:` is the orchestrator's authoritative classification (`requirements`, `plan`, `unified-requirements`, or `unified-plan`). Trust it; do not re-classify by inspecting content shape. The orchestrator already inspected the document contents and section structure to decide.
+- **Where your persona below adapts on `Document type: requirements` vs `Document type: plan`, apply the `requirements` branch for `unified-requirements` and the `plan` branch for `unified-plan`.** The `unified-*` values carry the same review lens as their base type — they differ only in living in one readiness-staged artifact, which the slice rules above already account for. Without this, a persona keyed on the bare `requirements`/`plan` value would skip its adaptation entirely on a unified artifact.
+- For `unified-requirements`, review the Product Contract slice as product requirements. Do not flag missing Planning Contract, Implementation Units, Verification Contract, or Definition of Done; those are added by `ce-plan`.
+- For `unified-plan`, treat Product Contract as the what-to-build authority and Planning Contract / Implementation Units / Verification Contract / Definition of Done as the how-to-build and completion contract. Findings should name which contract is affected.
+- `Origin:` carries upstream Product Contract provenance prepared by the orchestrator. It is a legacy `origin:` path when one is present, otherwise `product_contract_source:<value>` when the unified plan declares `product_contract_source`, otherwise the literal token `none`. Treat `product_contract_source:ce-brainstorm`, `product_contract_source:legacy-requirements`, and legacy brainstorm `origin:` paths as validated upstream premise signals. Treat `product_contract_source:ce-plan-bootstrap` and `none` as greenfield unless the document itself proves otherwise. Read this line directly — do not parse the document's frontmatter yourself for this signal.
+- `Settled decisions:` lists the document's `session-settled:`-labeled Key Technical Decisions or Product Contract Key Decisions (name, class, rejected alternative), or the literal token `none`. Entries listed here are decisions the document's author and user already settled in conversation. Treat the annotation itself as protected content — never propose stripping or rewording it away. Apply the infeasibility-versus-preference distinction: report evidence that the decision cannot achieve the agreed outcome under its constraints, with normal severity. A preference for another alternative is not a finding. Read this line directly — do not re-parse the document for these entries.
+</context-slots-rules>
+
+<decision-primer-rules>
+When the `<prior-decisions>` block above lists entries (round 2+), honor them:
+
+- Do not re-raise a finding whose title and evidence pattern-match a prior-round rejected (Skipped or Deferred) entry, unless the current document state makes the concern materially different. "Materially different" means the section was substantively edited and your evidence quote no longer appears in the current text — a light-touch edit doesn't count.
+- Prior-round Applied findings are informational: the orchestrator verifies those landed via its own matching predicate. You do not need to re-surface them. If the applied fix did not actually land (you find the same issue at the same location), flag it — synthesis will recognize it via the R30 fix-landed predicate.
+- Round 1 (no prior decisions) runs with no primer constraints.
+
+This is a soft instruction; the orchestrator enforces the rule authoritatively via synthesis-level suppression (R29) regardless of persona behavior. Following the primer here reduces noisy re-raises and keeps the Coverage section clean.
+</decision-primer-rules>
+```

package/skills/ce-doc-review/references/synthesis-and-presentation.md

@@ -0,0 +1,350 @@
+# Phases 3-5: Synthesis, Presentation, and Next Action
+
+## Phase 3: Synthesize Findings
+
+Process findings from all agents through these steps in order. Each step depends on the previous one. Together they move every finding through the same lifecycle: **Raised → (Confidence Gate | FYI-eligible | Dropped) → Deduplicated → Classified → SafeAuto | GatedAuto | Manual | FYI**. Re-evaluate each finding's state at every step; do not carry an assumption from an earlier step forward as a shortcut.
+
+### 3.1 Validate
+
+Check each agent's returned JSON against the findings schema:
+
+- Drop findings missing any required field defined in the schema
+- Drop findings with invalid enum values (including the pre-rename `auto` / `present` values from older personas — treat those as malformed until all persona output has been regenerated)
+- Note the agent name for any malformed output in the Coverage section
+
+**Do not narrate remap / validation diagnostics to the user.** Schema-drift notes ("persona X returned unknown enum Y, remapped to Z"), persona-prompt-drift commentary, and other validator-internal diagnostics are maintainer-facing information. They do not belong in the Phase 4 output the user reads. If a persona's output is malformed, the only user-visible consequence is a Coverage-row annotation (e.g., the persona shows fewer findings or a `malformed` marker). Everything else stays internal.
+
+### 3.1b Admit Findings by Consequence
+
+Establish what, if anything, prevents the document from guiding the agreed work. Retain a concern when its instructions cannot jointly satisfy the agreed contract, or when following the document, its references, and active project conventions would cause a demonstrated wrong outcome or worthwhile avoidable work. Judge an omission against what a competent implementer can already derive. A missing restatement, finer threshold, or additional procedure is not a defect when the existing instructions suffice.
+
+Investigate available facts before accepting a reviewer's claim. Establish the problem independently of its suggested fix: a useful-looking addition does not prove anything is missing. Keep the smallest supported correction that addresses the actual consequence. Verification changes must test the required outcome, not merely produce a passing check.
+
+Only concerns that meet this condition enter confidence scoring, recommendations, or output. This includes FYIs and deferred questions. Drop rejected claims from the working set; they require neither a user decision nor an automatic edit. Zero findings is valid.
+
+### 3.2 Confidence Gate (Anchor-Based)
+
+Route each finding by its `confidence` anchor value. Anchors are discrete integers (`0`, `25`, `50`, `75`, `100`). Their behavioral definitions are documented in `references/findings-schema.json` and embedded in the persona rubric (`references/subagent-template.md`). Anchors replaced the earlier continuous 0.0-1.0 scale with per-severity thresholds: document review does not warrant a different threshold per severity, and coarse anchors stop reviewers from gaming the score with false precision.
+
+| Anchor | Meaning | Route |
+|--------|---------|-------|
+| `0`    | False positive or pre-existing issue | Drop silently |
+| `25`   | Might be real but could not verify | Drop silently |
+| `50`   | Verified, useful advisory concern below the actionable bar | Show in FYI subsection |
+| `75`   | Double-checked, will hit in practice, directly impacts correctness | Enter actionable tier (classify by `autofix_class`) |
+| `100`  | Evidence directly confirms; will happen frequently | Enter actionable tier (classify by `autofix_class`) |
+
+- **Dropped silently** (anchors `0` and `25`): these do not appear in any output bucket — not as findings, not as FYI observations, not as residual concerns. Record the total drop count as a Coverage footnote line when non-zero: `Dropped: N (anchors 0/25 suppressed)`. The footnote appears below the Coverage table. This is the canonical location for drop-count reporting — not the summary line and not a per-persona Coverage column. Omit the footnote when N is zero.
+- **FYI-subsection** (anchor `50`): show in the FYI subsection of the presentation regardless of `autofix_class`. These do not enter the walk-through or any bulk action; they are observations and force no decision. Only useful advisory observations that passed 3.1b (admission by consequence) land here; FYI is not a destination for rejected nits.
+- **Actionable** (anchors `75` and `100`): enter classification. Route by `autofix_class` (see 3.7, Route by Autofix Class).
+
+
+### 3.3 Merge Duplicate Findings
+
+Two findings are duplicates when **one fix would resolve both**. Decide that by reading them — `title`, `section`, `why_it_matters`, `evidence`, and `suggested_fix` — not by comparing strings. Reviewers describe the same problem in different words as a matter of course, so wording similarity is not the test and matching titles are not required.
+
+Apply the test across personas and across sections:
+
+- **A shared section is evidence, never a requirement.** Two reviewers commonly attach the same problem to different sections, and just as commonly attach different problems to the same one. Neither settles it — the fix does.
+- **When unsure, do not merge.** When you cannot tell whether one fix resolves both, keep them separate. A surviving duplicate costs the user one extra line. A wrong merge buries a real concern inside an unrelated finding, where nothing signals that it went missing.
+- **Opposing recommendations never merge.** If one finding says cut and the other says keep, preserve both for contradiction resolution in 3.5 (Resolve Contradictions). That is a disagreement, not a duplicate.
+
+When findings merge:
+
+- Keep the highest severity and the highest confidence anchor. If anchors tie, keep the finding appearing first in document order — deterministic, not probabilistic.
+- Union the evidence arrays and note every contributing reviewer (e.g., "coherence, feasibility").
+- **Retain each constituent finding as a record**, with its own `section`, `title`, and `evidence` intact. Round-to-round memory (R29, R30, the decision primer, and the open-questions dedup key) matches on a single finding's section, title, and evidence overlap. A merged group has none of those, so collapsing the constituents away would make every finding the user already settled come back on the next round.
+- **Coverage attribution:** attribute the merged finding to the persona with the highest confidence anchor; on a tie, to the persona appearing first in document order. Decrement the losing persona's Findings count and its route bucket so totals stay exact.
+
+**Merging never drops.** A merge regroups findings; it never removes one from the review. Every finding that survives the lead agent's review reaches the user, either as its own entry or inside the merged finding that carries its concern. Rejected claims are recorded internally, not lost through merging.
+
+**Cross-model returns.** A `<reviewer-name>-<provider>` return merges with its in-process twin under the same one-fix test. Whether that merge counts as *independent corroboration* is decided in 3.4 (Cross-Persona Agreement Promotion) by the return's `independence_verified` flag, not here.
+
+**The merged set is the record.** The merged finding set produced by this step is the single source of truth for both Coverage counts and rendered output. Each finding appears in exactly one place in the output — counted once in its route bucket, rendered once at its own position.
+
+### 3.4 Cross-Persona Agreement Promotion
+
+Agreement can strengthen the evidence but does not make an issue important. Raise confidence by at most **one anchor step** only when the combined evidence meets the next level's definition. Several reviewers noticing a nit does not make it worth fixing. A significant defect needs no second vote to be retained.
+
+For local personas, independence requires separate dispatched contexts; an inline fallback cannot trigger anchor promotion. Cross-model corroboration requires `independence_verified: true`, at least one in-process contributor, and an independence-verified peer. A missing or false flag cannot trigger anchor promotion. Cursor default/Auto is not verified independence unless the run recorded which model actually answered. Peer-only agreement never promotes, and additional peers never stack the promotion.
+
+Record any justified promotion in the Reviewer column as `(+1 anchor)`, naming the cross-model reviewer and its verified model or route legibly. Keep the stored reviewer identities. Findings dropped at anchors 0/25 do not return through agreement. Corroboration never grants permission to apply fixes: the limits on peer-only findings in 3.6 (Resolve Who Can Choose the Fix) and 3.7 (Route by Autofix Class) still apply.
+
+### 3.5 Resolve Contradictions
+
+Check conflicting claims against the document, project evidence, and requested outcome before asking the user to decide. Drop a disproven claim or a preference with no significant benefit. Disagreement alone does not prove a defect. Record the reason internally so the rejected claim does not return when findings are combined or actions are chosen.
+
+If several fixes remain possible and choosing one needs an unresolved user preference or scope decision, keep one combined `manual` finding. Include both views and the decision needed. Set `finding_type` from the document's actual defect, not the disagreement. Keep opposing fixes together even when they affect different sections; never schedule both as separate edits.
+
+### 3.5b Lead Recommended Action
+
+Remove rejected claims from the retained review set and record why internally. A rejection is a completed judgment, not a recommendation for the user to confirm. Only surviving problems receive a `recommended_action` for presentation.
+
+Choose that action from the verified problem, benefit of the correction, agreed scope, and existing decisions. Recommend Apply when the correction is justified and concrete. Recommend Defer when a worthwhile problem cannot yet be resolved. A recommendation to Skip a proposed remedy belongs in the user-facing review only when a consequential unresolved choice still requires the user; explain that choice rather than asking them to ratify your rejection.
+
+When reviewers recommended different actions, keep one line explaining the lead agent's choice and its evidence. The walk-through and bulk preview use that `recommended_action` without recalculating it. Recommendations do not grant edit permission. After 3.6 and 3.7, check that each Apply still has a specific edit in `suggested_fix`; otherwise recommend Defer.
+
+### 3.6 Resolve Who Can Choose the Fix
+
+Each retained problem leaves this step with a correction the agent can choose or a specific unanswered question only the user can settle. Determine that from the current document, evidence, and user decisions. A reviewer's classification or a previous review's section heading is not a user decision and does not carry forward as the answer.
+
+Use `manual` only when you can state the missing input or consequential choice, why the agreed outcome and constraints leave it unresolved, and how the user's answer changes the work. A description of a technical fix does not establish such a question. When the document already determines the outcome, choose the smallest supported correction within its constraints; the existence of other workable methods does not transfer that choice to the user.
+
+Use `safe_auto` for a mechanical correction with one right answer and `gated_auto` for a chosen correction that changes meaning. Step 3.7 (Route by Autofix Class) determines whether the correction may be applied. Keep prior user decisions and actual applied changes; reclassify the remaining reviewer proposals from their evidence.
+
+**Fixes found only by another model.** These never qualify for `safe_auto`. The lead may choose a supported `gated_auto` correction within the agreed outcome and constraints, but its own investigation is not independent review. When missing local corroboration is the only obstacle to an otherwise authorized, worthwhile correction, obtain the limited independent check described in `references/document-intake.md` before returning it for approval. Keep the original attribution and record any new review separately. Silent application requires that local reviewer to independently identify the same issue (R18), plus the confidence and edit-authority requirements in 3.7. Missing, failed, or disagreeing local evidence leaves the peer-only restriction in place.
+
+### 3.7 Route by Autofix Class
+
+**Severity and autofix_class are independent.** A P1 finding can be `safe_auto` if the correct fix is obvious. Importance does not establish who can choose the fix or permission to edit.
+
+**Anchor and autofix_class are also independent.** The anchor decides where the finding goes (FYI or actionable); `autofix_class` decides what happens to an actionable finding. Both are consulted in this step.
+
+Findings reaching 3.7 already have anchor `50`, `75`, or `100`; 3.2 (Confidence Gate) dropped anchors `0` and `25`.
+
+**Check obligations before autofix routing.** An **obligation** is a retained defect whose remedy follows from a decision the document already made. This classifies findings that passed 3.1b (admission by consequence); it does not create findings because a unit is less detailed than the contract it follows.
+
+A finding is **not** an obligation merely because its fix would improve the document. Project evidence may justify a technical correction without making it an existing requirement. Step 3.6 decides who can choose the correction; grouping it here does not reopen that judgment.
+
+An obligation that changes meaning uses `gated_auto` and must include a specific `suggested_fix`. A mechanical `safe_auto` correction keeps its class, subject to the restriction on findings raised only by another model. If investigation still leaves no specific edit to apply, exclude it from the group and return the missing information to the calling agent.
+
+This is a per-finding test against one document. It needs no comparison to other findings and is independent of the merging in 3.3 (Merge Duplicate Findings).
+
+Group obligations still needing approval under the implementation unit or the section they affect. They belong in one approval batch, not the per-finding decision walk-through. **Render the group in full before asking the confirmation question.**
+
+Obligation grouping governs presentation, not edit authority. Route authorized corrections to Apply before constructing the approval batch.
+
+**Evidence, choosing a fix, and permission to edit are separate checks.** Confidence describes support for the finding. Step 3.6 decides whether the agent can choose the fix. This step decides whether and how the reader must approve the edit.
+
+**Establish edit authority from the request and the document's settled decisions.** Explicit read-only, report-only, or narrower edit restrictions take precedence. By default, this review may correct a proven defect in the reviewed document when the correction is necessary to implement a concrete decision already made there. Name that decision and how the defect prevents it from being carried out. Broad goals such as quality, safety, or clarity do not establish a particular correction. The correction must preserve user commitments and require no unresolved user input; choosing among equivalent technical methods does not itself create a user decision.
+
+Apply such a correction at anchor `100` when a local reviewer supports the finding and a specific `suggested_fix` is ready. This may be `safe_auto` or `gated_auto`: changing wording or meaning to fulfill an existing decision is different from making a new decision. Findings raised only by another model retain the R18 restriction, and session-settled annotations remain protected.
+
+An explicit user or caller grant may cover additional technical corrections at anchor `75` or `100` within its named scope and established contract. It does not authorize changing product outcomes, constraints, or user-reserved choices unless the grant expressly includes them. Confidence, reviewer agreement, and non-interactive mode never supply edit authority.
+
+For findings not covered by the authority above, use the routes below. Show the chosen fixes together for one approval. Ask separate questions only for essential information or choices the user still needs to supply. Another reasonable implementation does not, by itself, create a user decision.
+
+| Anchor | Autofix Class | Route |
+|--------|---------------|-------|
+| `100`  | `safe_auto`   | Apply when the request permits default editing. Report in the change list. Mechanical corrections only — evidence directly confirms and there is one right answer. Requires `suggested_fix`; demote to `gated_auto` if missing. |
+| `100`  | `gated_auto`  | Grouped confirmation. A concrete fix that touches meaning, so the reader sees it before it lands — but batched, not asked one at a time. Requires `suggested_fix`; demote to `manual` if missing. |
+| `100`  | `manual`      | A decision: the reader chooses. Never a question about whether to proceed with something already settled. Ask **which remedy** only when the finding carries competing ones; see below. |
+| `75`   | `safe_auto`   | Grouped confirmation. Unattended apply stays reserved for anchor `100`, where the evidence directly confirms the fix. Requires `suggested_fix`; demote to `manual` if missing. |
+| `75`   | `gated_auto`  | Grouped confirmation. Requires `suggested_fix`; demote to `manual` if missing. |
+| `75`   | `manual`      | A decision. Same treatment. |
+| `50`   | any           | Show in the FYI subsection regardless of `autofix_class`. Do not enter the Decisions list or any batch action. These are observations. |
+
+**A useful improvement is not automatically an entailed correction.** When no concrete settled decision requires the change and no edit grant covers it, retain a worthwhile, chosen remedy in the grouped confirmation. Keep choices the user must still make in Decisions.
+
+Earlier blanket application of `gated_auto` corrections selected genuine product forks (#1373). The boundary above therefore requires a concrete prior decision or an explicit edit grant; classifying a fix as technical or inevitable cannot establish either.
+
+Present three groups: **applied** corrections, **proposed fixes** still needing approval, and **decisions** that the user must still make. Proposed fixes include entailed corrections that still lack sufficient confidence or independent reviewer support, and worthwhile improvements outside current edit authority. Follow the shared rendering rules so the reader can distinguish these groups.
+
+**Present the unresolved choice, when one remains.** Step 3.6 decides whether the user must choose; the number of proposed remedies does not. The reviewer contract supplies one recommendation, so use the regular walk-through question for a genuine decision with one remedy. When contradiction resolution in 3.5 (Resolve Contradictions) preserves competing remedies, present both views and ask which remedy. Do not invent alternatives to create a choice.
+
+**No silent fixes from another model alone.** Findings raised only by another model never go directly to Apply, regardless of confidence or class (R18). Show a verified, chosen fix for approval with the others. Keep `manual` when a user decision or essential information is still missing. The source of a finding limits silent application, not the lead agent's ability to investigate and recommend.
+
+**Check the correction against the problem.** Before applying or recommending an edit, establish that it resolves the retained problem and preserves the agreed outcome with no unnecessary new requirements. Verify prescribed mechanisms against the actual project interfaces and behavior; where implementation can choose the mechanism, state the result it must achieve. A fix that merely looks more explicit is not ready to apply.
+
+Check edit authority separately. A concrete `suggested_fix` does not grant permission, and a choice reserved for the user remains `manual`. A `safe_auto` fix that changes meaning or has more than one correct answer can become `gated_auto` only after the agent has resolved the choice. Mechanical corrections must follow directly from the document's authoritative content. A visual aid may be updated to fix an inconsistency, but not deleted merely because it repeats prose.
+
+### 3.8 Sort
+
+Sort findings for presentation: P0 → P1 → P2 → P3, then by finding type (errors before omissions), then by confidence anchor (descending: `100` first, then `75`, then `50`), then by document order (section position) as the deterministic final tiebreak.
+
+### 3.9 Suppress Restatements in Residual Concerns and Deferred Questions
+
+Apply 3.1b to each reviewer's `residual_risks` and `deferred_questions`, not just its findings. Keep an uncertain concern only when project evidence shows why it matters to the requested outcome. Rejected preferences and unsupported possibilities do not return through another output field.
+
+Compare the remaining risks and questions with the final findings, including FYI items. Omit any that repeat a concern already covered by a finding or its recommended fix. Keep distinct, relevant uncertainty; similar wording alone does not prove duplication.
+
+Run this pass on the merged set across all personas. Record the count suppressed as duplicates as a Coverage footnote line when non-zero: `Restated: N (residual/deferred items suppressed as duplicates of actionable findings)`. Ordering: footnotes appear in the sequence `Dropped:`, `Restated:` below the Coverage table, each on its own line. Omit any footnote whose count is zero.
+
+## Phase 4: Apply and Present
+
+**Rendering floor (applies to every finding, every mode — read before rendering anything).** Read
+`references/rendering-floor.md` now. It is the single source of truth for the decision-first field
+order (Recommendation → Consequence-if-unchanged → Change → Basis → Trace-on-request), the rule for
+identifiers the reader cannot understand without opening the document, the tracker, or the code
+(document IDs, ticket and PR references, code symbols; at most two per block), and the code-span
+budget. Every place findings are shown below — the structured non-interactive result, the interactive
+template, and the bulk preview — maps its own layout onto that floor. Do not restate a weaker rule for
+one of them; the floor is authoritative.
+
+**User-facing vocabulary rule (applies to ALL user-visible output in Phase 4, not just the rendered template).** Internal enum values — `safe_auto`, `gated_auto`, `manual`, `FYI` — stay inside the schema and synthesis prose. Every word the user sees in Phase 4 output, including free-text narration between sections, transition preambles, status lines, and confirmation messages, MUST use user-facing vocabulary, named by where 3.7 routed the finding: "applied changes" or "fixes" (what 3.7 routed to Apply), "proposed fixes" (the grouped confirmation), "decisions" (the Decisions list), "FYI observations" (anchor `50`). The only exception is the `Tier` column in rendered tables, which is explicitly documented as showing the internal enum for transparency. Do NOT emit narration like "safe_auto fixes applied" or "N gated_auto findings" — write "fixes applied" or "N proposed fixes" instead.
+
+### Apply the findings 3.7 routed to Apply
+
+Apply, in a single pass, every finding 3.7 routed to Apply. Verify that each edit resolves its finding and preserves the governing contract. Report what changed and which settled decision or supplied edit scope authorized it. Findings outside Apply remain unapplied.
+
+Apply each edit in the document's native format and preserve its existing structure. Never insert markdown syntax into HTML, and for an ID-bearing HTML item mirror the nearest sibling's structure, preserving both its anchor convention and its visible ID text.
+
+- Edit the document inline using the platform's edit tool
+- Track what was changed for the "Applied changes" section in the rendered output
+- Do not ask for approval; 3.7 already established there is no choice to offer
+- Do **not** apply anything 3.7 routed elsewhere. Obligations and peer-only findings diverted out of Apply join the grouped confirmation; anchor `50` goes to FYI; `manual` at any anchor is a decision. If a finding reaches this step from any of those routes, 3.7 was not applied correctly. Re-run it for that finding before continuing.
+- Do **not** apply a finding whose only reviewers are cross-model peers, at any anchor or class. 3.7 diverts those to the grouped confirmation when the table would have applied them, and keeps choices that only the user can make in the separate Decisions section after the check in 3.6 of who can choose the fix.
+- An applied fix must never remove or reword a `session-settled:` annotation. If a `suggested_fix`'s text would touch one, do not apply it. Send the finding to the grouped confirmation so the user answers before the annotation changes.
+
+List every applied fix in the output summary so the user can see what changed. Use enough detail to convey the substance of each fix (section, what was changed, reviewer attribution). This is especially important for fixes that add content — the user should not have to diff the document to understand what the review did.
+
+### Route Remaining Findings
+
+After the applied changes land, the rest split by the route 3.7 assigned, not by `autofix_class`:
+
+- **Grouped confirmation** — every finding 3.7 sent there, obligations and Apply-diverted peer-only findings among them. One confirmation covering the batch, rendered in full first. In interactive mode this is asked as its own step before the routing question (see `references/walkthrough.md`). It is never folded into the routing question, and a run that reaches routing without asking it leaves the batch unapplied. In non-interactive mode the batch is returned unapplied for the caller to confirm.
+- **Decisions** — `manual` findings at anchor `75` or `100`. These enter the routing question and the walk-through (see `references/walkthrough.md`). They carry a which-remedy sub-question only when the finding holds competing remedies, which in practice means a contradiction preserved in 3.5, per the note under the routing table.
+- **FYI** — anchor `50`, presentation only, no routing.
+- **No remaining user decisions** → skip the routing question. In Interactive mode, still get approval for any proposed fixes, then emit the completion report and return through Phase 5 (Return to the Caller). Applied fixes and answered approvals belong in that report. In Non-interactive mode, return only the structured result described below; an extra interactive report would break the caller's expected format. No remaining decisions does not waive approval for proposed edits or mean those edits are complete.
+
+**Self-contained rendered lines (both modes, including the Applied-fixes list).** Every rendered line —
+an applied fix, proposed fix, decision, FYI observation, residual concern, or deferred question —
+follows the shared rendering floor (`references/rendering-floor.md`) for every identifier the reader
+cannot understand without opening the document, the tracker, or the code, not document IDs alone. A
+requirement or unit ID (`R6`, `U3`) keeps its ID and gets a short handle at first mention. A ticket or
+PR number (`ESP-3373`, `PR #1776`) is named only when that event changes the decision; otherwise it
+moves to the detail offered on request. A function, file, variable, or line reference the document
+names (`clearMuxStatus`, `codebookTranscriptMode.ts:46`) is described by the role it plays in the
+decision; keep the exact symbol only when precise scope drives the decision. At most two such
+identifiers per finding — counted across all its rendered lines, matching the floor's per-block limit —
+each resolved at render time against the document in context so it stays accurate after an Apply
+renumbers the item. The floor's full decision-first field order
+(Recommendation → Consequence → Change → Basis) applies to **actionable findings** — proposed fixes and
+decisions. FYI observations, residual concerns, deferred questions, and obligations carry no
+recommendation, so each renders as a single line under the identifier rule, not the full field order: a
+consequence, concern, or question, and for an obligation the consequence plus its change as intent. A
+line whose only description of a referenced item is a bare identifier — of any kind — is not acceptable
+rendered output.
+
+**Non-interactive mode:** Do not use interactive question tools. Output all findings as the structured text block below, which the caller parses; that block is the non-interactive result. Internal enum values (`safe_auto`, `gated_auto`, `manual`, `FYI`) stay in the schema and synthesis prose; the non-interactive result uses user-facing vocabulary ("fixes", "Proposed fixes", "Decisions", "FYI observations") so non-interactive output reads the same way interactive output does. `peer.outcome` is a machine field in that block, not narration: callers read it to tell a review whose different-provider peer folded an artifact from one whose peer did not.
+
+Two things about the template that follows. First, **nothing left in the batch has been confirmed here.** These edits were not covered by existing authority and this mode asks no questions, so they are returned *awaiting* confirmation. Already-authorized corrections that landed belong only in Applied. Wording that reports them as already confirmed invites a caller, or a user reading over its shoulder, to treat unapplied and unapproved changes as accepted. Second, **the text inside the code fence is the whole output.** On a document with no implementation units, title the obligations section "Entailed corrections" and use the section name as each group heading. Do not emit that instruction, or any other bracketed note, into the result the caller parses.
+
+```
+Document review complete (non-interactive mode).
+
+Applied N fixes:
+- <section>: <what was changed> (<reviewer>)
+- <section>: <what was changed> (<reviewer>)
+
+Implementation obligations (already entailed by the document; awaiting one grouped confirmation):
+
+<unit or section name>
+  - <consequence, no opaque identifier> — <change as intent language>
+  - <consequence, no opaque identifier> — <change as intent language>
+
+<unit or section name>
+  - <consequence, no opaque identifier> — <change as intent language>
+
+Proposed fixes (nothing here has landed; awaiting the same grouped confirmation):
+
+[P0] Section: <section> — <consequence-first title> (<reviewer>, confidence <anchor>)
+  Recommendation: <Apply | Defer | Skip>
+  Consequence if unchanged: <one sentence, no opaque identifier>
+  Change: <suggested_fix as intent language>
+  Basis: <at most two sentences of mechanism, opaque tokens glossed, at most two anchors>
+
+Decisions (requires user judgment):
+
+[P1] Section: <section> — <consequence-first title> (<reviewer>, confidence <anchor>)
+  Recommendation: <Apply | Defer | Skip>
+  Consequence if unchanged: <one sentence, no opaque identifier>
+  Change: <suggested_fix as intent language, or "none">
+  Basis: <at most two sentences of mechanism, opaque tokens glossed, at most two anchors>
+
+FYI observations (anchor 50, no decision required):
+
+[P3] Section: <section> — <consequence-first title> (<reviewer>, confidence <anchor>)
+  Consequence if unchanged: <one sentence, no opaque identifier>
+
+Residual concerns:
+- <concern> (<source>)
+
+Deferred questions:
+- <question> (<source>)
+
+Dropped: N (anchors 0/25 suppressed)
+Restated: N (residual/deferred items suppressed as duplicates of actionable findings)
+
+peer.outcome: <folded | in-process-fallback>
+cross-model <lens> peer: <what happened to the peer's result>
+<lens>: in-process fallback (cross-model peer not run: <reason>)
+whole-doc: not run (cross-model peer not run: <reason>)
+
+Review complete
+```
+
+Omit any section with zero items. The bucket names are the user-facing vocabulary for the routes 3.7 assigned. "Applied N fixes" reports what already changed. The obligations block and "Proposed fixes" together render the grouped confirmation: obligations first, then the rest of the batch, each shaped by the floor's "Presenting a batch" rule. The caller re-narrates this result to a reader who has seen none of it, so a flat list here becomes a flat list there. "Decisions" carries the decisions the user must still make, and "FYI observations" carries anchor `50`. End with "Review complete" as the final line so callers can detect completion.
+
+When a trio lens was activated, keep `peer.outcome` even though empty sections are omitted; omit it and its lens lines when none was. The owed lenses are each activated trio lens plus the whole-doc sweep. Write `peer.outcome: folded` only when every owed lens folded a different-provider peer artifact. Any other result, including a peer that started and then failed or timed out, is `peer.outcome: in-process-fallback`. Under it, give each owed lens that did not fold exactly one line, chosen by whether there is positive evidence that its peer did not run: it never started, the script skipped it, or the worker reported the transport unavailable before egress. With that evidence, use the not-run line with the observed reason: `<lens>: in-process fallback (cross-model peer not run: <reason>)` for a trio lens, and `whole-doc: not run (cross-model peer not run: <reason>)` for the whole-doc sweep, which has no in-process reviewer. Without it, the peer ran or may have run, so use `cross-model <lens> peer: <what happened to the peer's result>`: the job's terminal state (`failed`, `timeout`, `died-without-result`), or what kept a finished result from folding, such as no usable output or a read the runner could not verify.
+
+**Count findings by their final route.** Obligations still awaiting grouped confirmation count as proposed fixes; grouping changes presentation, not the count. Obligations already applied count only as applied fixes. Do not export a separate obligation count: the caller uses the proposed-fixes count to detect pending approval, so it must include every pending edit and exclude edits that already landed.
+
+**Compact rendering for FYI observations, residual concerns, and deferred questions (high-count mode).** When the combined count of these three buckets is 5 or more, collapse each to a one-line count followed by a tight bullet list, with no per-item elaboration. FYI observations use their consequence line; residual concerns and deferred questions use their concern or question text. Actionable buckets (Proposed fixes / Decisions) remain fully rendered regardless. This mirrors the interactive-mode rule in `references/review-output-template.md` so both modes produce the same shape.
+
+**Interactive mode:**
+
+Present findings using the review output template (read `references/review-output-template.md`). This presentation must appear as user-visible assistant text in the same turn immediately before the routing question in `references/walkthrough.md` is asked. A non-interactive result printed in an earlier turn, or a one-line count, does not satisfy that requirement. Within each severity level, separate findings by type:
+
+- Errors (design tensions, contradictions, incorrect statements) first — these need resolution
+- Omissions (missing steps, absent details, forgotten entries) second — these need additions
+
+Put a brief summary at the top, in the shape the template's summary-line rule defines: changes made and choices requested counted separately, never merged into one "needs attention" number.
+
+Include the Coverage table, applied fixes, FYI observations (as a distinct subsection), residual concerns, and deferred questions.
+
+**All tables MUST be pipe-delimited markdown (`| col | col |`). Do NOT use ASCII box-drawing characters (`┌ ┬ ┐ ├ ┼ ┤ └ ┴ ┘ │ ─`) under any circumstances, including for the Coverage table.** This rule restates the template's formatting requirement at the point of rendering so it cannot drift. Pipe-delimited tables render correctly across all target harnesses; box-drawing characters break rendering in some and violate the repo convention documented in root `AGENTS.md`.
+
+### R29 Rejected-Finding Suppression (Round 2+)
+
+When the orchestrator is running round 2+ on the same document in the same session, the decision primer (see `references/dispatch.md` — Decision primer) carries forward every prior-round Skipped, Deferred, Acknowledged, and user-settled Withdrawn finding. Synthesis suppresses re-raised rejected findings rather than showing them to the user again. Acknowledged is treated as a rejected-class decision here: the user saw the finding, chose not to act on it (no Apply, no Defer append), and wants it on record, which is equivalent to Skip for suppression purposes. Only user-settled withdrawals (retired by a Skip/Defer premise or a user-asserted fact) reach this primer. An Apply-triggered withdrawal is provisional and never carried here, so a staged fix that failed or landed ineffectively is re-checked by fresh synthesis rather than suppressed by R29.
+
+For each current-round finding, compare against the primer's rejected list:
+
+- **Matching test:** same as R30. A finding matches when its `normalize(section) + normalize(title)` fingerprint matches and its evidence substrings overlap the prior finding's by more than 50%. Suppress a matching finding only when the evidence and assumptions supporting the prior rejection remain current.
+- **Changed evidence:** reassess the finding when material changes to the document, relevant source, constraints, or newly available facts undermine the prior rejection. An unchanged document quote does not establish unchanged evidence. Retain the prior decision as history; a newly supported problem goes through ordinary admission and authority checks without treating reassessment as permission to reverse a user commitment.
+- **On suppression:** record the drop in Coverage with a "previously rejected, re-raised this round" note so the user can see what was suppressed. The user can explicitly escalate by invoking the review again on a different context if they believe the suppression was wrong.
+
+This rule runs at synthesis time, not at the persona level. Personas have a soft instruction via the subagent template's `{decision_primer}` variable to avoid re-raising rejected findings, but the orchestrator makes the final call: synthesis checks whether the prior rejection still applies before suppressing a re-raised finding.
+
+### R30 Fix-Landed Matching Predicate
+
+When the orchestrator is running round 2+ on the same document, synthesis verifies that prior-round Applied findings actually landed. For each current-round finding whose `normalize(section) + normalize(title)` fingerprint matches a prior-round Applied finding, branch by evidence overlap. This fingerprint is round-to-round memory's own key; 3.3 merges by reasoning and has no fingerprint to share. It works here because both rounds' findings are stored records with stable section and title fields:
+
+- **Strong match — evidence overlap >50% with the prior-round evidence: fix-landed regression.** The current-round finding is quoting the same problematic text the prior-round fix was supposed to remove. Flag it as "fix did not land" in the report rather than showing it as a new finding. Include the prior-round finding's title and the current-round persona's evidence so the user can see why the verification flagged it.
+
+- **Weak match — evidence overlap ≤50%: not a fix-landed regression.** Low evidence overlap means the prior problematic text is no longer being quoted, so do not flag "fix did not land." Do not suppress solely on fingerprint match. If the current-round item is explicitly a non-actionable verification observation (for example, its title or `why_it_matters` says the prior finding landed correctly and asks for no change), suppress it and record `Verified: round-{N} '{title}' landed correctly` in Coverage. Otherwise, treat the finding as new and let it flow through dedup and routing normally.
+
+  **Materially-different exception.** If the current-round finding's `why_it_matters` describes a substantively different concern than the prior-round finding — even though the section/title fingerprint matches — treat it as a new finding rather than a fix-verified suppression. The section may have been edited for an unrelated reason and the new edit introduced a different issue. The persona's substance, not just the fingerprint, is the signal.
+
+- **Section renames count as different locations.** If the section name has changed between rounds (an edit renamed the heading), treat the new section as a different location and the current-round finding as new. Neither branch above applies.
+
+- **No fingerprint match:** not a verification candidate; the finding flows through normally to 3.3 (Merge Duplicate Findings) and onward routing.
+
+This rule prevents two failure modes: (1) regressions where a fix didn't actually land, and (2) persona over-emission where a round-{N+1} reviewer correctly observes a prior-round resolution and emits a non-actionable "already addressed" finding. The persona-side guidance in `subagent-template.md` ("Do not emit findings to note prior-round resolutions") is the primary defense; this rule catches what the personas miss.
+
+### Protected Artifacts
+
+During synthesis, discard any finding that recommends deleting or removing a CE pipeline artifact: any file **under** a `plans/`, `solutions/`, `ideation/`, `explainers/`, `pulse-reports/`, `dogfood-reports/`, `feedback-sweep/`, or `personas/` directory (or the legacy `brainstorms/` one) **whose immediate parent is the artifact root**. The artifact root is a directory named `docs` — the default, and where unmigrated legacy artifacts stay even after a project sets `docs_root` — or the configured `docs_root` when this run resolved it. Matching by that parent covers nested category files (`solutions/<category>/foo.md`) while leaving a same-named directory elsewhere — a skill's own `references/personas/` prompt assets, whose parent is `references` — as ordinary code whose deletion finding stands. A review that never resolved a configured root still protects the `docs`-parented tree (default and legacy). An artifact under a configured root seen by such a run is the one case this rule does not cover.
+
+## Phase 5: Return to the Caller
+
+Return "Review complete" with the completion report or the non-interactive result. A finished review does not need a terminal question. When nested, "Review complete" ends this skill, not the turn: the caller runs in this same session, and its next step follows the report. Do not start a nested planning or execution workflow merely because the review is complete.
+
+For standalone use, a useful next step may be named without a blocking menu. A requirements-only unified plan or legacy standalone requirements doc routes to `ce-plan`; an implementation-ready unified plan or legacy implementation plan routes to `ce-work`. Invoke that next skill only when the user's existing request authorizes it. Review completion alone does not authorize new work.
+
+### Iteration limit
+
+After 2 refinement passes, recommend completion. An explicit request for another pass is honored with prior decisions preserved. Handling unchanged findings uses the intake reuse condition rather than starting a new pass.
+
+## What NOT to Do
+
+- Do not rewrite the entire document
+- Do not add new sections or requirements the user didn't discuss
+- Do not over-engineer or add complexity
+- Do not create separate review files or add metadata sections
+- Do not modify caller skills (ce-brainstorm, ce-plan, or external plugin skills that invoke ce-doc-review)
+
+## Iteration Guidance
+
+On genuinely new review passes, re-dispatch personas with the multi-round decision primer (`references/decision-primer.md`) and re-synthesize. Fixed findings drop out on their own because their evidence is gone from the current doc; rejected findings are handled by the R29 suppression rule; applied-fix verification uses the R30 matching test above. If findings repeat across passes after these rules run, recommend completion.