coherence-check

Purpose

Authors .docs/coherence/<plan-stem>.md: a single committed artifact mapping every intake outcome bullet, every PRD FR (product track), every non-deleted ADR file in the current spec change set when the coherence gate engages, every story, and every plan task to its counterpart ids with a per-row verdict. This artifact is the auditable traceability record the operator (and the land-time coherence validator) reads instead of trusting self-reported "everything's covered" prose in a spec PR.

Any current-change-set .docs/decisions/adr-* path, including a deletion, engages the ADR layer. That engagement is distinct from the ADR row pool: deleted ADRs produce no row, so a deletion-only change has no ADR row to author.

Correctness gate: a row's verdict (covered / gap / fail) is a judgment call, not a mechanical grep. Mapping and achievability are separate questions: a counterpart can exist while a criterion still cannot be delivered (§4g). Per the /verify-claims protocol, ground every verdict in the actual cited text — do not mark a row covered on the assumption that a plausible-looking counterpart id exists; confirm it against the real artifact file.

1. Tier Rule (M/L only)

Read the spec's tier from .docs/complexity/.

• Tier S: this skill does NOT run. Skip it entirely — same treatment as architecture-diagram/architecture-review/conflict-check for S tier. No .docs/coherence/ artifact is authored, and the land-time validator does not engage for S-tier specs (Story 13). Do not author a stub file "to be safe" — its mere presence is not required and produces work the S-tier exemption exists to avoid.
• Tier M: this skill runs, using the session's default model (no override).
• Tier L: this skill runs, pinned to opus for the dispatch (see Section 2).

2. Model Rule (M = session default, L = pinned opus)

This skill is tier-varying, the same pattern as conflict-check and plan:

• M tier: inherit whatever model the invoking session/step is already running — no pin.
• L tier: pin to opus for this dispatch. Large-tier specs have the widest fan-out of outcomes/FRs/stories/tasks and the highest cost of a missed transitive gap, so the semantic-judging pass needs the deepest reasoning tier.

The autonomous/daemon path applies this through each provider policy's stepTierOverrides.coherence_check.L in src/conductor/src/engine/provider-model-policy-defaults.ts (Claude: opus; Codex: gpt-5.6-sol); this SKILL.md documents the same rule for interactive/phone-driven runs, where the operator's active session may not be opus and must be told to escalate.

3. Inputs

Load, in order:

1. Staged/committed intake outcomes — .pipeline/ staged outcomes file if present, or the committed .docs/intake/<plan-stem>.md marker if land has already run once. If neither exists (chat-origin idea), the outcome row class is not required.
2. The approved PRD (product track only) — .docs/specs/<plan-stem>.md, for its enumerated FR-N requirements.
3. The stories file — .docs/stories/<plan-stem>.md, for **Requirement:** and story ids.
4. The plan — .docs/plans/<plan-stem>.md, for **Story:** lines, task ids, the plan's own ## Coverage Check table if present, and its ## Architecture Obligation Coverage table when the changed ADR pool contains citable decisions.
5. The ADR files in the current spec change set — each non-deleted .docs/decisions/adr-*.md file. This is the row set when the coherence gate engages; do not expand it to every decision that conceptually constrains the stories.

4. Mapping-Artifact Format

Write .docs/coherence/<plan-stem>.md. The plan-stem in the filename MUST match the plan's own filename stem exactly — the land validator rejects a stem mismatch as missing-coherence-artifact even when a coherence file exists under a different name.

The artifact is a Markdown table (or one table per row class) with these columns:

Row class	Cited id(s)	Counterpart id(s)	Verdict	Notes

4a. Row Classes (six)

1. outcome — one row per intake Desired-outcome bullet (skip this class entirely if no outcomes were staged/committed — an empty outcome layer is "not required," never a gap). Cited id: outcome-<n> (1-based, in bullet order). Counterpart: the story id(s) that cover the bullet. The Quote cell must be the staged bullet itself — the sanitized projection under .pipeline/intake-outcomes.md, not the tracker's raw text and not a paraphrase. Only presentation is normalized away (a leading list marker, surrounding quotation marks, collapsed whitespace), so any other difference is an unmatched outcome (adr-2026-09-06-inbound-intake-trust-boundary D10).
2. fr — one row per enumerated PRD FR-N (product track only; skip this class on the technical track). Cited id: fr-<N>. Counterpart: the story id(s) whose **Requirement:** line cites that FR.
3. story — one row per story id declared in the stories file. Cited id: story-<id>. Counterpart: the task id(s) whose **Story:** line cites that story.
4. task — one row per task in the plan's task tree. Cited id: task-<id>. Counterpart: the story id it serves, OR — for infrastructure/refactor-typed tasks — a non-empty supporting-purpose statement from the task's **Story:** line in place of a story id.
5. adr — when the coherence gate engages, one row per non-deleted .docs/decisions/adr-*.md file in the current spec change set. Cited id: adr-<stem>. Counterpart: the story id(s) that implement or are constrained by the decision. Its verdict also covers the decision-by-decision plan mapping required by Section 4f; any incorrect mapping makes this ADR row fail.
6. criterion — one row per exact happy or negative Given/When/Then criterion extracted from the stories file. Its cells are the exact criterion text, cited task id(s), verdict, a verbatim quote from one cited task's Done when block, and a diff-locality disposition. The quote is matched as an exact substring after whitespace normalization; a paraphrase does not ground coverage. Do not quote Steps or Files prose: those describe work but do not require its completion, so they can ground a claim the builder is not obliged to satisfy. The disposition is exactly diff-local or outside-diff; only diff-local is non-negative and lands without a coherence waiver. A seventh optional correction cell is allowed only when the verdict is fail: use plan, or architecture:adr-<stem>#D<n> for a decision enumerated from a non-deleted ADR in the current change set. A corrected failure records a waivable criterion:cannot-deliver-<layer>:<n> gap; an unknown architecture decision also reports criterion:correction-unknown-decision:<n>. Do not use the correction cell on covered or gap rows.

Layer ownership. Story↔story pairs belong to /conflict-check. Cross-layer and task versus task pairs belong to plan review at Medium and Large tier, and to the plan's §7b at Small tier. /conflict-check runs before /plan, so it cannot see tasks.

4b. Verdict Vocabulary

Use exactly these three verdict values — this is the same vocabulary the land-time validator parses and the same vocabulary the coherence-waiver mechanism consumes:

• covered — the cited id has ≥1 real counterpart id (confirmed to exist in the counterpart's own artifact file, not merely referenced); a criterion row must also establish achievability (§4g).
• gap — the cited id has zero counterparts, or its only counterpart is itself transitively uncovered (e.g. a story maps to a task, but that task cites no story back, or the coverage table claims a task id that does not exist in the task tree).
• fail — the cited id has a real counterpart, but the cited task checks cannot deliver the criterion under the approved architecture (§4g), or a required ADR decision mapping is semantically wrong (§4f). Coverage is satisfied here; achievability or architecture alignment is not. Recording it as gap would misdescribe it and send the reader hunting for a missing artifact that is in fact present and wrong.

The exact strings matter more than they look. The land-time validator treats gap, missing, uncovered, and fail as blocking for legacy rows, and every other string as affirmative. Criterion rows instead reject any verdict outside covered, gap, and fail. An invented verdict — "partial", "contradiction", "n/a", "pending" — can therefore silently pass the legacy gate or make a criterion row malformed. That is why a achievability or architecture-alignment failure is recorded as fail rather than as a new word that reads more precisely: fail is already in the blocking set and already flows into the gap list a waiver can cite. A row that is genuinely not applicable (e.g. the FR row class on a technical-track spec) is omitted entirely, never given a placeholder verdict.

4c. Gap-ID Scheme

Every gap row's Notes column MUST restate its gap id in one of these canonical forms — this is the vocabulary a .docs/coherence-waivers/<plan-stem>.md waiver names to be recognized (waivers are validated by a separate mechanism; this skill only needs to emit the ids in the correct form so a later waiver can cite them):

For the adr row class, the cited id form and the canonical gap-id form are both adr-<stem>, where <stem> is the ADR filename stem.

• outcome-<n> — unmapped or negative-verdict outcome bullet, or one whose row quotes something other than the staged sanitized bullet
• fr-<N> — FR cited by no story, or only by a story that itself maps to no task
• story-<id> — story cited by no task, or a story that does not tie out to the PRD (cites an FR-N the PRD never declares, or cites no FR at all — §4e)
• task-<id> — task with no valid story citation and no supporting-purpose exemption
• adr-<stem> — non-deleted ADR file in the current spec change set cited by no story, or only by a story that does not implement or honor the decision
• claim-<row> — the plan's own ## Coverage Check table cites a phantom id or contradicts the parsed task tree (row number within that table)
• criterion:quote-not-done-when:<n> — a criterion quote occurs in the cited task body but not in any cited task's Done when block
• duplicate:<ref> — a second spec claiming an already-claimed Source-Ref (emitted by the land-time duplicate-claim scan, not authored here — documented for vocabulary completeness only)

Gap ids are opaque strings to downstream consumers (the validator, the waiver parser) — do not paraphrase or abbreviate them; use the exact forms above so cross-checking against the real artifact files (Section 5) is possible.

Before marking a criterion row covered, read every cited task's Done when block and verify that the quoted text comes from one of those checks.

A fail row uses the same id form as its row class (outcome-<n>, fr-<N>, story-<id>, task-<id>, adr-<stem>) — the id identifies which row, and the verdict says what is wrong with it. Name the supporting evidence in Notes so a reader can adjudicate without re-deriving the finding.

Use CANNOT-DELIVER: for an achievability failure (§4g). Criterion rows have six required cells and no Notes cell; a fail row may add the optional seventh correction cell described in §4a. Keep the exact criterion text, task ids, verdict, verbatim Done when quote, and disposition intact. Put the explanation in a prose paragraph directly below the table, naming the criterion, cited task id, quoted check, and any binding ADR decision. Do not append commentary to the quote or create another table for these notes. This prefix is explanatory prose, not a verdict, disposition, gap id, or correction-layer routing signal. Do not invent an achievability-specific gap-id form.

4e. PRD ↔ Stories Tie-Out

The fr and story row classes are the two halves of one question: do the PRD and the stories tie out? Both directions must hold, and they fail differently:

• Forward (PRD → stories). Every enumerated FR-N is cited by ≥1 story's **Requirement:** line, and ≥1 of those stories is itself covered by a plan task. An FR nothing implements is gap on its fr row (fr-<N>).
• Reverse (stories → PRD). Every story cites ≥1 FR-N, and every FR-N it cites is one the PRD actually declares. A story citing FR-9 when the PRD stops at FR-4 is a phantom requirement; a story citing no FR at all is untraced — it asserts behavior the product spec never asked for. Either is gap on that story's story row (story-<id>).

Both directions are enforced mechanically by the land-time gate over parsed ids — it re-derives them from the real PRD and stories files regardless of what this artifact claims, and reports every offending id, not the first. Do not spend judgement re-deriving set membership by hand: read the ids, record the rows, and let the gate be the authority on coverage. Plan review at Medium and Large tier, and the plan's §7b at Small tier, own whether cross-layer artifacts conflict; this tie-out does not repeat that judgment.

4f. Architecture-Decision ↔ Plan Tie-Out

For every citable decision in each non-deleted ADR in the current spec change set, independently judge the plan's ## Architecture Obligation Coverage row. A task disposition is covered only when the cited task's Done when: semantically asserts the decision—not merely because the task id and quoted text exist. An existing disposition is covered only with verified implementation evidence; a no-change disposition is covered only when the decision genuinely imposes no implementation change on this feature. If any decision mapping is semantically wrong, mark the parent adr row fail and identify the decision id plus opposing evidence in Notes.

The land-time gate owns the mechanical checks: complete and unique decision ids, the closed disposition vocabulary, real task citations, and exact Done-when evidence. Do not duplicate those string/set checks. This skill owns the judgement the engine cannot compute: whether that real evidence actually fulfills the architecture obligation.

4g. Achievability Pass

For every criterion row, ask: given only what the cited task's Done when checks actually assert, and the approved architecture that constrains it, would satisfying them produce the criterion's Then-clause? Related work and compatible wording do not establish delivery. When multiple tasks are cited, judge their checks together; do not require each task to deliver the whole criterion independently, or assume an unstated connection between them.

A task whose checks require only logging a warning, allowing an unsigned artifact through, is a §4g failure: all its checks can pass without rejection.

A cited task that cannot deliver the criterion is fail, not covered or gap. The counterpart exists and coverage is satisfied; what is wrong is that its promised behavior does not work. Use the existing verdict so the validator blocks it, and explain the failure with CANNOT-DELIVER: prose below the table per §4c.

Apply these detection heuristics:

• Mechanism-vs-restatement. If the cited check merely paraphrases the Then-clause instead of naming the code path, state change, or check that produces it, achievability is unestablished: the task asserts the outcome without establishing how it delivers it. Surface this uncertainty per §5 rather than crediting it. A named mechanism still needs to yield the criterion; its name alone is not proof. Do not fill missing obligations from Steps prose or presumed BUILD work.
• Constraint sweep. Re-read the criterion against each approved ADR in the current change set. If the task could deliver it only by violating an approved decision, mark the criterion row fail. The explanation must name the adr-<stem>, decision id, and binding decision text. Preserve §4f's separate architecture-obligation judgement and its existing row pool.
• Representable outcomes. When the approved design uses a closed set of states, result values, or reasons, walk each required happy and negative scenario through the cited checks and identify the legal value that represents its actual outcome. Include required absence, skip, and no-change cases: reporting that an operation ran cannot deliver a criterion saying it did not run. A set whose permitted values cannot express a required outcome is fail, even if the producer and consumer agree on the same incomplete set. Quote the scenario and binding set; do not demand a distinct value per scenario when an existing value represents it truthfully, or invent scenarios outside the accepted criteria. Unspecified value meanings remain an assumption under §5.
• Input-boundary proof. If checks operate on a prepared input, normalized status, or exported subset, trace the required scenario to the check that produces that input from the actual source. A helper that correctly handles invalid does not establish that malformed source data becomes invalid; matching a registry to an exported subset does not establish that the subset includes everything the criterion quantifies over. Identify the decoding/validation or enumeration boundary and its owning task check. Consider required error exits too: a later reporter cannot supply a promised result if the planned earlier refusal never reaches it. Credit existing evidence and sibling tasks, and distinguish a demonstrated bypass (fail) from an unspecified connection (§5).

Ground each finding in the exact criterion and cited Done when text, with the binding ADR decision where applicable. "This task feels thin" is not a finding. If the artifacts do not settle achievability, surface the uncertainty as an assumption under §5: interactive runs wait for operator confirmation; autonomous runs record gap. Never turn an unconfirmed assumption into a pass.

5. Semantic-Judging Instructions (verify-claims protocol)

Per /verify-claims, this skill is a verifier/judge role: it renders a verdict per row and must never assert "covered" that it has not actually confirmed.

• Calibrate claims. Before marking a row covered, Read/grep the counterpart artifact file and confirm the cited id is real and the coverage is genuine (not just a plausible-sounding phrase match). Prefer the cheap read over an inferred guess every time it would settle the question.
• Surface every assumption. If a row's coverage is ambiguous (e.g. a story vaguely gestures at an outcome without an explicit citation), do not silently resolve it in either direction — surface it as an assumption with confidence, impact-if-wrong, and how to confirm, per the repository's correctness and assumption gate.
• Hard-block on unconfirmed load-bearing assumptions. A verdict on this artifact is load-bearing — it gates land. Never mark a row "covered" on an unconfirmed assumption about what a story or task "probably" means. Interactive runs: present the ambiguous row and wait for operator confirmation before finalizing the artifact. Autonomous/daemon runs: mark the row gap and let the fail-closed land gate surface it — never silently resolve ambiguity as a pass.
• Fabricated citations are never coverage. A cited counterpart id that does not exist in its source file is not "covered with a typo" — it is a gap, and the land-time validator independently cross-checks every cited id against the real artifact files regardless of what this skill wrote.

6. Output

1. Write .docs/coherence/<plan-stem>.md with the table(s) described in Section 4.
2. Ensure the file renders as valid Markdown (a real table, not fenced prose) — it must be readable directly in the spec PR diff (Story 2).
3. Do not stage or commit a coherence artifact for a technical-track spec's fr row class, a chat-origin spec's outcome row class, or an adr row class when the current spec change set has no non-deleted .docs/decisions/adr-*.md file — omission is correct there, not a gap. A deleted ADR path still engages the ADR layer, but it does not enter that row pool.

Verification

• [ ] Tier read from .docs/complexity/; skill does not run at all for tier S
• [ ] Tier L dispatch is pinned to opus; tier M inherits the session/step default
• [ ] .docs/coherence/<plan-stem>.md filename stem matches the plan's filename stem exactly
• [ ] All five row classes present where applicable (outcome/fr/adr omitted only when genuinely not required)
• [ ] Every verdict is exactly covered, gap, or fail — no invented verdict strings (legacy rows can silently pass them; criterion rows reject them as malformed)
• [ ] §4e PRD↔stories tie-out checked in BOTH directions — no FR without a story, and no story citing a phantom FR or citing no FR at all
• [ ] §4f architecture-decision mappings judged semantically; every task, existing, or no-change disposition actually satisfies its cited ADR decision
• [ ] §4g achievability judged for every criterion from cited Done when checks and approved architecture; mechanism-vs-restatement, ADR constraints, representable outcomes, and input boundaries checked
• [ ] Established inability to deliver recorded as fail; unsettled achievability handled under §5
• [ ] Each achievability failure has CANNOT-DELIVER: prose below the table naming the criterion, task id, quoted check, and any binding ADR and decision id; six-cell rows and quotes stay intact
• [ ] Story↔story pairs left to /conflict-check; plan review at Medium and Large tier and plan §7b at Small tier own cross-layer and task-versus-task checks
• [ ] Every gap row's Notes column restates its gap id in the canonical form (Section 4c)
• [ ] Every covered verdict was confirmed against the real counterpart artifact file, not inferred
• [ ] Ambiguous rows surfaced as assumptions (interactive: wait for confirmation; autonomous: mark gap, never silently pass)
• [ ] Output renders as a valid Markdown table in the spec PR diff