Lane D: review deltas — spec lens, two-axis doctrine, discovery ladder, preflight, suppression rules, container close-out review

[kyle-sexton]

Parent

Refs #2933. Source: topic pocock-shipping-breakdown (PR backfilled when opened).

What to build

Two halves, adjudicating candidates C12–C16 (evidence: topic memory slice upstream-bringover-audit.md):

1. Originating-item/spec review axis. quality-gate has 8 modes but no spec-fidelity lens; the CI code-review lane has no originating-issue axis; "what was the goal" is a gather input, not a lens. Candidates: C12 spec lens (missing/partial requirements, unrequested behavior = scope creep, implemented-but-wrong — quoting the spec line per finding), C13 never-merge-never-rerank two-axis doctrine, C14 spec-source discovery ladder (issue refs in commits → user-passed path → topic docs → ask → skip-with-note), C15 fail-fast preflight before spawning reviewers (ref resolves, diff non-empty), C16 baseline-suppression rules (repo standard overrides conflicting baseline smell; skip what tooling already enforces — verify our Fowler baseline carries both).
2. Container close-out review. When the last sub-item of a spec container closes, one cumulative review of the whole (across multiple PRs) against the container spec — the piece that makes multi-session work verifiable as a whole. Design where it lives (review mode vs work-items ritual) and what diff basis it uses.

Keep our verify-delegated-findings discipline (upstream presents sub-agent findings unverified — excluded).

Acceptance criteria

• C12–C16 verdicts recorded in the SSOT; accepted ones landed
• Container close-out review exists as an invocable, documented flow
• Standards discovery still resolves via the standards contract (no fixed-filename regressions)

Blocked by

None — can start immediately.

[kyle-sexton]

Design resolved — after adversarial validation (interview 2026-08-19; recommendations auto-accepted, then audited by two independent fresh-context validators with the rationale withheld per /planning:audit-answers. Three of five initial answers were CHALLENGED on evidence and revised; what follows is the corrected design.)

Scope change: the container close-out review splits out

Acceptance criterion 2 ("container close-out review exists as an invocable, documented flow") moves to its own sub-issue of #2933. Reason (validated): its mechanism is broken four ways as originally specified and it is structurally larger than a mode addition — no seam verb returns a closing PR (the only closing-PR machinery is GitHub-only GraphQL in adapters/github/README.md, used by reclaim.sh, and its documented reduction filters MERGED out — the inverse of what close-out needs); "union of merge commits" resolves to the empty set under this repo's own squash-merge default (plugins/source-control/skills/pull-request/SKILL.md:39,77); the integration-branch execution shape has no per-item PRs at all (plugins/work-items/reference/execution-shape.md:63); and a container-scoped basis conflicts with quality-gate's singular review-diff-base contract (quality-gate/SKILL.md:25-27). This item's remaining scope is the spec lens + ladder + C13/C15/C16 verdicts.

1. spec mode in quality-gate — ADOPT, with three corrections

New 9th mode + context/spec.md, reporting missing/partial requirements, unrequested behavior (scope creep), implemented-but-wrong, quoting the originating spec's line per finding. Budget verified clear: check-skill.sh caps are 500 hard / 200 soft lines and 1536 description chars; quality-gate is at 97 lines / ~365 chars, and no mode cap exists anywhere in the repo.

The gap is real and already has a dangling consumer: decompose/SKILL.md:249-251 and ship/SKILL.md:108 both route container close-out to "the review plugin's spec-fidelity machinery when installed" — and grep -rn "spec-fidelity" plugins/review/ returns nothing. This mode is that machinery's home.

Corrections from the audit:

• context/spec.md OWNS the (a)/(b)/(c) enum; self.md:60-61 degrades to a citation. Keeping both copies creates two SSOTs for one definition — exactly what this plugin's own restatement mode flags (context/restatement.md:11: "When a canonical home exists, the fix is cite-by-reference rather than restating inline").
• The cross-reference does NOT go at self.md:60 — that line sits inside the fenced subagent prompt template (fence opens :21, closes :74), addressed to a fresh-context read-only worker that cannot invoke skills. It belongs in orchestrator-facing text (e.g. self.md's escalation section, ~:77-81).
• Collateral the mode addition must also touch: plugins/review/README.md:29-31 (enumerates the 8 modes), the frontmatter description and argument-hint (both enumerate modes), and quality-gate/evals/evals.json (skill-quality gates on evals presence).

2. CI code-review lane — stays quality-only (reasoned rejection, not a phantom decision)

The original "deliberately excluded" clause was a no-op: grep -rn "quality-gate" plugins/review/skills/code-review/ returns nothing — there is no coupling to exclude. Recorded instead as a decision with reasons: the CI lane is org-owned (code-review/SKILL.md:12-19, ci-workflows#258), already declares lane-splitting doctrine (:47-49), and its scope rules (:51-53, :65) foreclose absence-of-code findings. #2937's body names the missing originating-issue axis as a gap; this is the recorded answer to it, revisitable on demand rather than silently narrowed.

3. C13 two-axis doctrine — MOSTLY ALREADY-PRESENT; one targeted edit + a vocabulary decision

The originally proposed rule was withdrawn — both validators independently showed it contradicts or duplicates existing behavior:

• In fanout, "axis" already means severity/confidence (fanout/SKILL.md:24, context/findings-normalization.md:5, context/severity.md:17), and merging/ranking across them is the skill's stated purpose (findings-normalization.md:70 cross-surface merge takes MAX severity + MAX confidence; :72 ranking). A bare "never merge or rerank across axes" line negates the pipeline fanout exists to run.
• C13's actual intent is already implemented at findings-normalization.md:73 — "Two-axis presentation: the merged ranked queue is the primary view; the report ALSO regroups the same findings by review dimension… a merged rank can mask one dimension failing badly while the others pass."
• The proposed second scope ("invocations pairing spec with a quality mode") is unimplementable: quality-gate/SKILL.md:23 mandates one lens per invocation.

Adopted instead: (a) one targeted edit — quality-gate/context/self.md:17 today dispatches a standards-axis vs spec-conformance-axis worker split and says "merge only after verification"; tighten it to keep-separate presentation, since that is the one live site with the weaker rule. (b) Record the vocabulary once — "axis" in plugins/review/ means severity/confidence; the standards-vs-spec split is a lens. Three incompatible senses are live today; a rule written on that ambiguity gets applied wrongly.

4. C14 spec-source discovery ladder — ADOPT, rungs 2 and 3 corrected

--spec <path|id> → issue/closing-keyword refs from branch commits or PR body → topic-docs contract slice → ask → skip-with-note. Corrections:

• Rung 2 is NOT "resolved through the seam's get-item" for spec text. The seam's normalized item object is schema_version, id, title, state, assignees, labels, type, blocked_by_count, parent_id, url (CONTRACT.md "JSON output contract"; github adapter's WIT_ITEM_JQ) — there is no body field; --body exists only as a write parameter on create-item. Correct formulation: get-item for identity and parent_id (it IS authoritative for parent linkage), then the provider-mechanic read for body text (gh issue view --json body / Jira REST), documented as such per reference/tracker-seam.md:47-49,57-59. Also required and previously unspecified: how a bare #123 harvested from a commit/PR body is promoted to a qualified <provider>:<owner>/<repo>#<n> id (CONTRACT.md forbids the bare form in durable artifacts), and a documented presence-gated path for review → work-items (no plugin in this repo calls another's seam CLI today — this would be the first, so the gate and the absent-plugin degradation must be explicit).
• Rung 3 keys on the TOPIC slug, not the branch slug. plugins/review/reference/topic-docs.md:58-61 states the branch axis is "deliberately distinct from the convention's topic-slug form: the mapping is lossy"; PLAN.md/PRD.md live at <contract_dir>/<topic-slug>/. Also record the limit: the contract slice is pruned before merge (docs/conventions/topic-docs/README.md:475-495), so post-merge this rung finds nothing and recovery is explicitly best-effort — which is precisely why the tracker container is the durable spec home.

5. C15 / C16 verdicts — CONFIRMED by both validators

• C16 ALREADY-PRESENT, no change. plugins/review/agents/code-reviewer.md:43 carries both halves in one sentence ("The project's documented standards override the baseline wherever they endorse a flagged pattern, and skip anything tooling already enforces"), corroborated at quality-gate/context/criteria.md and code-review/SKILL.md:64.
• C15 PARTIAL — port fanout's preflight (fanout/SKILL.md:71-80) into quality-gate, which today has no preflight at all (zero matches for STOP/rev-parse/empty-diff across its SKILL.md and all eight context files). Two costs the original answer omitted: the gate must be mode-scoped (criteria mode is a reference mode that legitimately runs on a clean tree), and quality-gate's narrow allowed-tools allowlist lacks git rev-parse/merge-base/diff — porting requires widening it or the gate stalls headless.

Acceptance criteria (revised)

• spec mode lands with context/spec.md owning the finding-class enum; self.md cites rather than restates; README/description/argument-hint/evals updated
• C14 ladder documented with the provider-mechanic body read, bare-ref promotion, presence gate, and topic-slug keying — including the post-prune limitation
• self.md:17 axis-split tightened to keep-separate; review-plugin "axis" vocabulary recorded once
• Mode-scoped preflight ported into quality-gate with the allowed-tools widening
• C12–C16 verdicts recorded in docs/upstream/aihero-shipping-course.md (C12 ADOPTED-corrected, C13 ALREADY-PRESENT + targeted edit, C14 ADOPTED-corrected, C15 PARTIAL, C16 ALREADY-PRESENT)
• Standards discovery still resolves via the standards contract (no fixed-filename regressions)

Audit provenance: two fresh-context validators, rationale withheld; every claim above cites a verified file/line. Implementation in a fresh worker session per the container's execution contract.

---

Generated by Claude Code