Pipeline Verify

The second tier of the pipeline's verification design. Tier 1 is built into every stage skill — each verifies its own contract at delivery. Tier 2 is this skill: the seams between documents that no single stage can see — a citation written correctly by one skill against a document another skill later amended, an FR that every stage individually handled but no stage ever covered, a manifest locator that rotted when a heading moved.

Three principles govern it:

1. Mechanical only. Every check here is decidable by reading and computing — IDs resolve or don't, sets cover or don't, values match or don't. Judgment quality (is the architecture good, are the tests meaningful) belongs to the stage skills and their auditors; a check that needs taste doesn't belong in this skill.
2. Read-only, derived-output-only. This skill writes nothing into any pipeline artifact — no RTM column, no document fix, no "helpful" correction. Its single output is the report, an explicitly derived view: safe to overwrite, safe to delete, regenerable at any time. Findings route to their owning skills; fixing is theirs.
3. Fresh eyes, actual commands. Run it cold — it needs no session context, only the repo. And extract mechanically: grep/parse the IDs, diff the sets, resolve the locators with real commands — never eyeball a 700-row matrix. The checks are specified so a script could run them; run them like a script would.

When to run

After any system-level phase completes (catch seam breaks while the phase's author-skill session is still warm); before handing the loop to the orchestrator for a long run; after amendment chains (the highest-risk moment for dangling references); periodically on mature projects. Full sweep by default; targeted scope on request ("check the RTM", "check FEAT-007's seams").

Inputs

Everything, read-only: docs/srs.md, use-cases.md, rtm.md, architecture.md, ux-foundations.md, design.md, tokens.json, implementation-plan.md, design-manifest.json, docs/features/**, docs/defects.md, scaffold/deploy notes where present. Absent documents scope their checks out (source-gating applies to verification too — a missing use-cases.md means UC checks are skipped and reported as skipped, never failed).

Workflow

Phase 1 — Inventory the namespaces

Parse every defining document for the IDs it mints: SRS → FR/NFR; use-cases → UC; ux-foundations → SCR (+ surface codes); architecture → ADR (+ CON constraints if present); plan → FEAT; defects ledger → DEF. Record each ID's status (active/tombstoned). This inventory is the ground truth every later check diffs against. Then parse every document for the IDs it cites.

Phase 2 — Run the seam checks

Read references/checks-guide.md and execute the catalog: resolution (every citation lands on a defined, correctly-namespaced ID), tombstone discipline (no active work cites a removed item), coverage/orphans (the bidirectional set diffs), RTM integrity (rows, ownership, computed verification), manifest and folder conventions (locators resolve, names match), decision → realization conformance (the architecture's named test frameworks and coverage stance actually realized in CI and the repo), and value authority (tokens agreement). Classify every finding: error (a broken seam — something downstream will trip on), warning (suspicious but survivable — e.g., an FR designed but unplanned on a young project), info (notable, no action implied).

Phase 3 — Compute the dashboard

The read-only status view, computed fresh (see references/report-guide.md): per-FR lifecycle (planned → designed → verified, honoring partial markers and the Plan-ref⨝Test-ref completeness rule), per-feature stage (the same artifact table the orchestrator uses), coverage counts, open blocks/escalations/defects. Stored nowhere — the report is the rendering.

Phase 4 — Report and route

Write docs/pipeline-verify-report.md (overwriting the previous — it's derived) and summarize in chat: the verdict line (clean / N errors, M warnings), findings grouped by owning skill (an unresolved SCR citation in the plan routes to implementation-planning's amendment; a stale manifest locator to ui-design; an RTM row mismatch to requirements-engineering) — each finding specific enough to fix without re-deriving, each naming its owner. This skill fixes nothing.

Scope boundaries

Does not: fix anything (findings route to owners); judge quality (stage skills and auditors); write any pipeline artifact (the derived report only); replace the stage skills' tier-1 verification (both tiers run; neither substitutes).

What good looks like

• Zero eyeballing: every set comparison was computed; the report shows the counts (IDs defined, cited, diffed) so the sweep itself is auditable.
• Findings are actionable verbatim: ID, location, what's broken, who owns it.
• Skipped checks are reported as skipped with their missing input — absence of evidence is never reported as cleanliness.
• The dashboard agrees with what the orchestrator would compute — same artifacts, same rules, independently derived.
• Running it twice in a row without changes yields the identical report.