task-pipeline-skill 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## v1.1.0 — 2026-07-29
+
+**The pipeline could find a requirement that was named and lost. It could not find
+one that was never named.** Every gate compares two things — and a contradiction has
+two sides while **an absence has one**. Nothing in a diff between spec and plan
+reveals the error path nobody specified, the entity nobody gave an owner, the
+failure mode nobody thought of. This release adds the pass that can.
+
+### Added
+- **`references/audit.md` — the audit ladder, cross-cutting.** Eight rungs of one
+  deliverable (requirement → decision → spec section → contract **and its failure
+  behavior** → plan task → change → **executed** test → surface/docs) and, more
+  importantly, the **seam between each pair**, each with its own question: did the
+  decision reach the spec; does the section say what happens when the contract
+  fails; does every contract have a task (stage 4's set-equality covers REQ→task and
+  nothing covers contract→task); did the DoD land in the diff; would this test still
+  pass with the production code deleted; can a user reach it and does a doc say so;
+  and finally — does what shipped satisfy the requirement's own *statement* rather
+  than the task's instructions.
+- **Stage 10 now opens with the ladder walk, before the coverage table.** An absence
+  found there becomes a **new REQ row with its check**, and *then* the table is
+  written. Appending after the table is exactly how acceptance goes green over a
+  gap. Findings that belong to a lower layer go back to that layer (spec → stage 3,
+  plan → stage 4) instead of being patched in place at the last stage.
+- **Findings are ordered by seam, never by file.** A file-ordered list reads as
+  noise; a seam-ordered one names *which layer of your own process is leaking*,
+  which is the part worth knowing.
+- **Bottom-up, and that is not taste.** A missing artefact low on the ladder makes
+  everything above it meaningless — top-down you spend the pass polishing a surface
+  for a contract that does not exist. Bottom-up, the absence is finding #1 and the
+  six findings above it collapse into it.
+
+### Added — three rules that stop the audit becoming another loop
+- **Every pass changes the axis, not the effort.** A searching loop does not
+  oscillate the way an editing loop does — it **converges**, because each pass edits
+  the corpus the next pass reads, so the newest edits are always the
+  least-reviewed text present and are what the next pass finds. Measured over seven
+  passes on a production repository: by pass six, ten of thirteen findings were
+  caused by pass five's own fixes, while the raw count still looked healthy. So the
+  doctrine requires **two counts per pass** — new findings, and self-inflicted ones —
+  and names the crossover as the signal to **rotate the axis**: seams down one
+  deliverable, then invariants across deliverables, then one class swept end to end.
+- **A class that repeats twice becomes a gate, not a note.** Once is an incident;
+  twice is a category, and a category belongs in the host's lint or CI where nobody
+  has to remember it. Writing the third instance into the ledger is how a
+  mechanical defect class becomes permanent. Wired into the stage-5 fix loop too.
+- **What can't be fixed now becomes a ratchet, never a TODO.** The carry-over ledger
+  is now defined as a *named, counted set that may only shrink, printed beside every
+  gate verdict* — `carry-over: 4 open (was 6) · unresolved: 0`. A TODO is invisible
+  until somebody opens the file; a ratchet sits next to the word `PASS` on every
+  run, so **"green" never reads as "verified"** — it reads as *"green, and here is
+  exactly what was not looked at"*. A ratchet that grew needs one sentence saying
+  why.
+
+### Added — the exit criterion that is usually skipped
+- **A green result from an unproven check is worth nothing.** A deliverable is not
+  audited when somebody has read it; it is audited when every rung has its artefact
+  **and every check being relied on has fired at least once against a planted
+  defect.** This is `tdd.md`'s iron law — *if you didn't watch it fail, you don't
+  know it tests the right thing* — raised from one test to every gate, linter and
+  script in the run, and it is now part of the stage-10 gate. Checks written under
+  pressure lie in ways that read as success: a predicate that inspects the wrong
+  shape, a probe that reads its own over-deletion as a pass, a regex that misses the
+  word it searches for. All three pass loudly.
+
+### Changed
+- `loop-guard.md` and `audit.md` now state their seam explicitly in both files: the
+  loop guard governs loops that **change** things and trips on oscillation; the
+  audit governs loops that **look** for things and trips on convergence. Different
+  failure, different exit, and an agent reading either one now learns when the other
+  applies.
+- `tdd.md` names the generalisation of its own iron law; `build.md`'s fix loop gains
+  the repeats-twice rule; `templates/carryover.md` documents the ratchet contract.
+
+### Validator
+- `references/audit.md` joins the built-in-doctrine set (must exist, must not be a
+  stub, must be reachable from `SKILL.md`).
+- The shipped acceptance gate must require the ladder walk **and** say that an
+  absence becomes a new REQ row — a config where stage 10 only compares the REQ list
+  now fails.
+- Both guards ship with CI negative self-tests, and both were proven the way this
+  release demands: defect planted, check watched failing, defect removed.
+
 ## v1.0.0 — 2026-07-28
 
 **1.0.** Eighteen releases in ten days added a stage, a requirement spine, a

package/README.md

@@ -78,7 +78,8 @@ Every gate is **typed**: `auto` — the orchestrator verifies it itself, pass/fa
 - **Every stage has a gate.** No code before a spec. No deploy before tests. No
   "done" before the post-deploy logs have been read.
 - **Nothing falls out the back.** The request becomes a frozen, addressable list of
-  requirements, and the last stage accounts for every one of them with evidence.
+  requirements, and the last stage accounts for every one with evidence — then
+  walks the ladder for what should have been on the list and never was.
 - **Team discipline without a team.** ADRs, a written plan, a real test suite, a
   wiki entry — produced as part of the work, not promised for later.
 - **It adapts to your repo, not the reverse.** Deploy, docs and wiki conventions
@@ -117,6 +118,7 @@ stage that can fail because a plugin is missing:
 | 5 Build | [`build.md`](plugins/task-pipeline/skills/task-pipeline/references/build.md) + [`review.md`](plugins/task-pipeline/skills/task-pipeline/references/review.md) — isolation, ledger, subagent loop, review rubric, fix loop |
 | 5–6 TDD | [`tdd.md`](plugins/task-pipeline/skills/task-pipeline/references/tdd.md) — the iron law, red/green/refactor, the suite gate |
 | 10 Acceptance | [`acceptance.md`](plugins/task-pipeline/skills/task-pipeline/references/acceptance.md) — REQ coverage table, evidence rules, the closing question |
+| 10 + any audit | [`audit.md`](plugins/task-pipeline/skills/task-pipeline/references/audit.md) — the L0→L7 ladder and its seams, axis rotation, ratchets, proven checks |
 | any loop | [`loop-guard.md`](plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md) — churn detection, caps, the break protocol |
 
 **Ported, not depended on.** Stage 0 is adapted from
@@ -271,6 +273,57 @@ module map), re-plans the check as an ordered checklist with one verification
 command per item, and goes through it one at a time. A higher-layer conflict is
 never settled inside a lower loop.
 
+### The audit ladder — finding what was never written
+
+The REQ spine catches a requirement that was **named and lost**. It cannot catch
+one that was never named — because **a comparison needs two sides, and an absence
+has one.** Nothing in a diff between spec and plan reveals the error path nobody
+specified, the entity nobody gave an owner, the failure mode nobody thought of.
+
+So stage 10 opens with a **ladder walk**
+([`audit.md`](plugins/task-pipeline/skills/task-pipeline/references/audit.md)), not
+with the coverage table. Each requirement is walked **bottom-up** through its rungs
+— recorded decision → spec section → contract *and its failure behavior* → plan
+task → the change in the tree → an **executed** named assertion → the surface a
+user reaches and its docs — and the work is the **seam between each pair**: did the
+decision reach the spec, does every contract have a task, did the DoD land in the
+diff, would that test still pass with the production code deleted, does what
+shipped satisfy the requirement's own *statement* rather than the task's
+instructions. Findings are ordered **by seam, never by file** — the seam names
+which layer of your process leaks. Every absence becomes a new REQ row with its
+check *before* the table is written.
+
+Bottom-up is not taste: a missing artefact low on the ladder makes everything above
+it meaningless, so top-down you spend the pass polishing a surface for a contract
+that does not exist.
+
+Three rules keep the audit from becoming another loop:
+
+- **Every pass changes the axis, not the effort.** A searching pass doesn't
+  oscillate, it *converges*: each pass edits the corpus the next one reads, so the
+  newest edits are always the least-reviewed text and are what the next pass finds.
+  Measured over seven passes on a production repository, by pass six the audit was
+  mostly repairing its own previous pass — while the finding count still looked
+  healthy. So count both numbers every pass (new findings vs. self-inflicted ones);
+  when the second overtakes the first, **rotate the axis** — seams down one
+  deliverable, then invariants across deliverables, then one class swept end to end.
+- **A class that repeats twice becomes a gate, not a note.** Once is an incident;
+  twice is a category, and a category belongs in lint or CI where nobody has to
+  remember it. The third instance in a ledger is how a mechanical defect becomes
+  permanent.
+- **What can't be fixed now becomes a ratchet, never a TODO** — a named, counted
+  set that may only shrink, printed *beside every gate verdict*
+  (`carry-over: 4 open (was 6) · unresolved: 0`). A TODO is invisible until someone
+  opens the file; a ratchet makes **"green" never read as "verified"** — it reads
+  as *"green, and here is exactly what was not looked at"*.
+
+And the exit criterion that is usually skipped: a deliverable is audited when every
+rung has its artefact **and every check you are relying on has been seen failing
+once against a planted defect.** That is the TDD iron law — *if you didn't watch it
+fail, you don't know it tests the right thing* — raised from one test to every
+gate, linter and script in the run. **A green result from an unproven check is
+worth nothing.**
+
 ### UX track (user-facing tasks) — super-ux recommended
 
 The moment a task touches any user-facing surface (web / mobile / CLI / TUI — a

package/cursor/rules/task-pipeline.mdc

@@ -161,14 +161,31 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
     propose the edit and get an explicit go, or carry it over with the exact change
     written down. A doc that was worth reading at stage 0 and is wrong now is the
     next run's false premise.
-10. **Acceptance** (manual) — the closing stage: go back to the brief and account
-    for **every** REQ. One row each, status `verified` / `partial` / `deferred` /
-    `dropped`, and every `verified` carries **evidence** — a passing test name, a
-    `file:line`, a command and its output. "Done" without evidence is downgraded to
-    `partial`, never upgraded. Then ask out loud, list in hand: *here's what you
-    asked for, here's what shipped, here's what's deferred and where it lives —
-    what's missing?* Ask it even when the table is green. Gate: no REQ `unknown`,
-    no ledger row without a home, user signs off.
+10. **Acceptance** (manual) — the closing stage, in two halves.
+    **First the ladder walk**, because the REQ table only finds what was named and
+    lost: a comparison needs two sides and **an absence has one**. Walk each REQ
+    bottom-up through its rungs — recorded decision → spec section → contract *and
+    its failure behavior* → plan task with a satisfiable DoD → the change in the
+    tree → an **executed** named assertion → the surface a user reaches, and its
+    docs — checking the seam between each pair: does the decision reach the spec;
+    does the section say what happens when the contract fails; does every contract
+    have a task; did the DoD land in the diff; would that test still pass with the
+    production code deleted; can a user reach this and does a doc say so; and
+    finally, does what shipped satisfy the requirement's own *statement* rather
+    than the task's instructions. Order findings **by seam, not by file** — the
+    seam tells you which layer of your process leaks. Every absence becomes a new
+    REQ row with its check **before** the table is written; appending afterwards is
+    how acceptance goes green over a gap. Findings owned by a lower layer go back
+    there (spec → stage 3, plan → stage 4).
+    **Then the table:** one row per REQ, status `verified` / `partial` /
+    `deferred` / `dropped`, and every `verified` carries **evidence** — a passing
+    test name, a `file:line`, a command and its output. "Done" without evidence is
+    downgraded to `partial`, never upgraded, and **a green from a check nobody has
+    watched fail against a planted defect is not evidence at all**. Then ask out
+    loud, list in hand: *here's what you asked for, here's what shipped, here's
+    what's deferred and where it lives — what's missing?* Ask it even when the
+    table is green. Gate: ladder walk ran, no REQ `unknown`, no ledger row without
+    a home, user signs off.
 
 Cross-cutting: answer from the brief's autonomy section rather than re-asking, log every deferral in the ledger, never narrow the task silently, track
 tasks, conventional commits, honest degradation (never claim a failed/skipped step
@@ -193,6 +210,32 @@ no opportunistic edits. Re-check the list once in the same order at the end. If
 trips again after a re-planned pass, stop and hand back with both shapes, the
 evidence and your recommendation.
 
+**Audit rules — for loops that *look* rather than edit.** A searching pass doesn't
+oscillate, it **converges**: each pass edits the corpus the next pass reads, so the
+newest edits are the least-reviewed text and are what the next pass finds. Measured
+over seven passes on a real repository, by pass six the audit was mostly repairing
+its own previous pass while the finding count still looked healthy. So:
+- **Count two numbers every pass** — new findings, and findings caused by the last
+  pass's own fixes. When the second overtakes the first, the axis is exhausted:
+  **rotate the axis, don't look harder.** The axes are orthogonal by construction —
+  seams down one deliverable (the ladder above), then invariants *across*
+  deliverables (one name, one enum, one owner everywhere), then one class swept end
+  to end (every error path, every count, every status vocabulary).
+- **Audit bottom-up.** A missing artefact at a low rung makes everything above it
+  meaningless; top-down you polish a surface for a contract that doesn't exist.
+- **A class that repeats twice becomes a check, not a note.** Once is an incident;
+  twice is a category, and a category belongs in lint or CI where nobody has to
+  remember it. The third instance in a ledger is how a mechanical defect becomes
+  permanent.
+- **What can't be fixed now becomes a ratchet, never a TODO** — a named, counted
+  set that may only shrink, **printed beside every gate verdict**
+  (`carry-over: 4 open (was 6) · unresolved: 0`). A TODO is invisible until someone
+  opens the file; a ratchet makes "green" read as *"green, and here is exactly what
+  was not looked at"*. If it grew, one sentence says why.
+- **Never trust an unproven check.** Plant the defect, watch the check fail, remove
+  it, then trust the green — same law as the failing test, applied to every gate,
+  linter and script the run leans on.
+
 ## super-ux for user-facing tasks (recommended)
 
 If the task touches any UI (web/mobile/CLI/TUI), the WHY→UI→scenario chain comes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"

package/plugins/task-pipeline/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "task-pipeline",
   "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/manual gates, a frozen requirement spine that must close with evidence, a loop guard that breaks churn, one provider-agnostic model confirmed up front, and an optional super-ux UX track for user-facing work.",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": {
     "name": "ssheleg"
   },

package/plugins/task-pipeline/commands/task-pipeline.md

@@ -25,7 +25,7 @@ language, ADRs for hard-to-reverse calls) and covering the **autonomy sweep** (w
 would otherwise stop stages 1→10: docs sources incl. doc repos and the wiki, branch/tracker
 policy, test and lint commands, deploy target and authorization, log locations, docs/wiki targets) —
 until the brief is locked — including the **REQ table**, the request as an addressable list where every row names how it is verified — so the rest runs autonomously and the final stage can account for all of it. The list is frozen: adding is free, removing needs the operator's agreement. Anything deferred goes into the carry-over ledger the moment it's said. For any user-facing task, recommend/use
-**super-ux**. **If the brief describes a platform rather than a change**, stage 2 also cuts it into modules (`references/decomposition.md`) — module map committed, walking skeleton first, every REQ in exactly one module — and stages 3→10 then run per module, one brick at a time. **If any loop starts undoing an earlier pass** (same file edited twice for the same reason, a closed finding returning, a third entry into one stage), stop and run the loop guard (`references/loop-guard.md`): name both shapes, escalate to the layer that owns the conflict, re-plan the check as an ordered list, then go item by item. Honor every stage gate by its type (`auto` = verify yourself;
+**super-ux**. **If the brief describes a platform rather than a change**, stage 2 also cuts it into modules (`references/decomposition.md`) — module map committed, walking skeleton first, every REQ in exactly one module — and stages 3→10 then run per module, one brick at a time. **If any loop starts undoing an earlier pass** (same file edited twice for the same reason, a closed finding returning, a third entry into one stage), stop and run the loop guard (`references/loop-guard.md`): name both shapes, escalate to the layer that owns the conflict, re-plan the check as an ordered list, then go item by item. **The closing stage opens with the ladder walk** (`references/audit.md`): the REQ table finds what was named and lost, but a comparison needs two sides and an absence has one — so walk each REQ bottom-up through its rungs (decision → spec section → contract *and its failure behavior* → task → change → executed test → surface/docs), check the seam at each step, order findings by seam rather than by file, and turn every absence into a new REQ row **before** the coverage table is written. A green from a check nobody has watched fail against a planted defect is not evidence; a finding class seen twice becomes a script rather than a third ledger row; and the carry-over ledger's counts are printed beside every gate verdict, so "green" never reads as "verified". If a searching pass starts finding mostly what the previous pass's own fixes broke, the axis is exhausted — rotate it, don't look harder. Honor every stage gate by its type (`auto` = verify yourself;
 `manual` = wait for explicit go). Confirm the **model once at preflight** —
 recommend the most capable one the environment offers, never a hardcoded id — then
 run the whole pipeline on it without re-asking.

package/plugins/task-pipeline/skills/task-pipeline/SKILL.md

@@ -50,6 +50,7 @@ and no stage that can fail because a dependency is missing:
 | 5 Build (worktree, subagents, fix loop) | [`references/build.md`](references/build.md) + [`references/review.md`](references/review.md) |
 | 5–6 TDD + suite gate | [`references/tdd.md`](references/tdd.md) |
 | 10 Acceptance (REQ close-out) | [`references/acceptance.md`](references/acceptance.md) |
+| 10 + any audit (what's *missing*) | [`references/audit.md`](references/audit.md) |
 | any repeating loop | [`references/loop-guard.md`](references/loop-guard.md) |
 
 **Optional bridge.** If the operator already runs an equivalent skill set (e.g.
@@ -162,7 +163,10 @@ Three things the grill does beyond clarifying the request:
    third entry into one stage — stop and run the loop guard**
    (`references/loop-guard.md`): name the two shapes, escalate to the layer that
    owns the conflict, re-plan the check as an ordered list, then go through it one
-   item at a time; task
+   item at a time; **when a pass is *searching* rather than editing and starts
+   finding mostly what the previous pass's own fixes broke, the axis is exhausted —
+   rotate it, don't look harder** (`references/audit.md`), and remember that a
+   green from a check nobody has watched fail is not evidence; task
    tracker + conventional commits per host conventions; worktree isolation for the
    build, integrated back per the brief's branch policy before stage 7; honest
    degradation (never claim a failed/skipped step succeeded);
@@ -187,7 +191,7 @@ capable available — see `references/model-tiering.md`).
 | 7 | Lint + deploy | host lint → deploy per host convention | lint clean + suite green before deploy; deploy needs a go (or the brief's specific standing authorization) | manual |
 | 8 | Post-deploy | tail deploy logs / health-check | clean boot or honest degradation report | auto |
 | 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki), recommended) | every stale row of the stage-0 source ledger updated; docs synced; wiki synced | auto |
-| 10 | **Acceptance** | built in: [`references/acceptance.md`](references/acceptance.md) | every REQ accounted for with evidence; ledger has no unresolved row; operator signs off | manual |
+| 10 | **Acceptance** | built in: [`references/audit.md`](references/audit.md) (ladder walk) → [`references/acceptance.md`](references/acceptance.md) (coverage table) | ladder walk ran, its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; ledger has no unresolved row; operator signs off | manual |
 
 ## Model — ask once, at preflight
 
@@ -223,6 +227,7 @@ automation is on — `pipeline.schema.json` is the only contract.
 - `references/knowledge-sources.md` — stage-0 phase 1: the source list, the wiki, the ledger, the stage-9 loop-back
 - `references/grill.md` — the built-in stage-0 grill: loop, domain awareness, autonomy sweep
 - `references/acceptance.md` — the built-in stage-10 close-out: REQ coverage, evidence, sign-off
+- `references/audit.md` — cross-cutting: the L0→L7 ladder and its seams (what was never written), axis rotation, ratchets, proven checks
 - `references/brainstorm.md` — stage 2: design dialogue, approaches, UI detection, hard gate
 - `references/spec.md` — stage 3: UX track order, the spec contract, self-review, review gate
 - `references/planning.md` — stage 4: zero-context plan format, parallel groups, no placeholders

package/plugins/task-pipeline/skills/task-pipeline/pipeline.example.json

@@ -152,11 +152,12 @@
       "name": "Acceptance",
       "model": "default",
       "skills": [
+        "task-pipeline:audit",
         "task-pipeline:acceptance"
       ],
       "gate": {
         "type": "manual",
-        "check": "Close the circle: every REQ in the brief has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off"
+        "check": "Close the circle. FIRST the LADDER WALK (references/audit.md), because the REQ table can only find what was named and lost — a comparison needs two sides and an absence has one: walk each REQ bottom-up through its rungs (decision -> spec section -> contract AND its failure behavior -> plan task -> change -> executed test -> surface/docs), check the seam at each step, order findings BY SEAM not by file, and turn every absence into a new REQ row with its check BEFORE the table is written; findings belonging to a lower layer go back to that layer (spec -> stage 3, plan -> stage 4); record the pass's two counts (new findings vs findings caused by this run's own fixes) so the next pass can tell whether the axis is exhausted. THEN the coverage table: every REQ has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded, and a green from a check nobody has watched fail against a planted defect is not evidence at all; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved and the ledger's counts are printed beside this verdict, so 'green' never reads as 'verified'; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off"
       }
     }
   ],

package/plugins/task-pipeline/skills/task-pipeline/references/acceptance.md

@@ -18,10 +18,34 @@ run itself decided, deferred, or quietly dropped along the way.
 It runs **last** — after docs and wiki (stage 9), because those are deliverables
 too and a requirement may name them.
 
+## First, the ladder walk — what the list itself is missing
+
+The REQ table answers *"did everything on the list ship?"*. It cannot answer
+*"should something else have been on the list?"* — a comparison needs two sides,
+and an absence has one.
+
+So **before writing the coverage table**, walk the ladder in
+[`audit.md`](audit.md): each REQ bottom-up through its rungs (decision → spec
+section → contract **and its failure behavior** → task → change → executed test →
+surface and docs), checking the seam at each step. It is one pass, scoped to this
+run's deliverables, and it is the only part of the pipeline that can find a gap
+that was never a row.
+
+- **An absence found here becomes a new REQ row with its check**, then the table is
+  written. The list is frozen against *narrowing*, never against additions
+  ([`grill.md`](grill.md) → *The REQ spine*). Writing the table first and appending
+  afterwards is how acceptance goes green over a gap.
+- **A finding that belongs to a lower layer goes back to that layer** — spec gaps to
+  stage 3, plan gaps to stage 4 — rather than being patched in place at stage 10.
+- **Report the audit's two counts** (new findings; findings caused by this run's own
+  fixes) in the ledger. They are what tells the next pass whether the axis is
+  exhausted (`audit.md` → *Every pass changes the axis*).
+
 ## Inputs
 
 Read all of them before writing anything:
 
+- the ladder walk's findings (above) — they may have added REQ rows
 - the brief's **REQ table** (`docs/superpowers/specs/<topic>-brief.md`)
 - the **carry-over ledger** (`…-carryover.md`) — in full, every row
 - the plan and its task statuses
@@ -97,13 +121,20 @@ whether the run was finished.
 
 All of:
 
-1. **Every REQ has a status** — none `unknown`, none blank.
-2. **Every `verified` carries evidence** of the kind above.
-3. **Every `partial` names what's missing** and where it's tracked.
-4. **Every `deferred` / `dropped` has the operator's agreement** recorded (in the
+1. **The ladder walk ran** ([`audit.md`](audit.md)) — every REQ's rungs checked
+   bottom-up, findings ordered by seam, absences turned into REQ rows **before**
+   the table was written, and the two pass counts recorded.
+2. **Every check this gate leans on has been seen failing** at least once against a
+   planted defect (`audit.md` → *Exit criterion*). An unproven check's green is not
+   evidence.
+3. **Every REQ has a status** — none `unknown`, none blank.
+4. **Every `verified` carries evidence** of the kind above.
+5. **Every `partial` names what's missing** and where it's tracked.
+6. **Every `deferred` / `dropped` has the operator's agreement** recorded (in the
    ledger or here) and, for `deferred`, a tracker entry.
-5. **No carry-over row is left `unresolved`** — every one has a home.
-6. **The operator answers the closing question** and signs off.
+7. **No carry-over row is left `unresolved`** — every one has a home, and the
+   ledger's counts are printed with this verdict, not just filed.
+8. **The operator answers the closing question** and signs off.
 
 Manual by design. An automated check can prove the table is *well-formed*; only
 the person who asked can confirm it is *what they asked for*. Do not let a green

package/plugins/task-pipeline/skills/task-pipeline/references/artifacts.md

@@ -82,6 +82,7 @@ plugins/task-pipeline/
       spec.md planning.md                     #   stages 3-4
       build.md review.md tdd.md               #   stages 5-6
       acceptance.md                           #   stage 10
+      audit.md                                #   cross-cutting: the ladder + seams
       loop-guard.md                           #   cross-cutting: churn detection
       stages.md model-tiering.md              #   gates, model policy
       conventions.md artifacts.md             #   host conventions, this layout

package/plugins/task-pipeline/skills/task-pipeline/references/audit.md

@@ -0,0 +1,224 @@
+# Audit — finding what is missing, cross-cutting
+
+Every gate in this pipeline asks *"is this artifact good?"*. Stage 10 asks *"is
+anything from the list lost?"* ([`acceptance.md`](acceptance.md)). **Neither asks
+what should have been on the list and never was.**
+
+That gap is not an oversight in the gates. It is structural: a gate compares two
+things, and **a contradiction has two sides while an absence has one.** Comparing
+the spec against the plan finds a requirement that was dropped. It cannot find the
+error path nobody specified, the entity nobody gave an owner, the failure mode
+nobody named — because on both sides of every comparison, it simply isn't there.
+
+This file is the method that finds those. It is **cross-cutting**: stage 10 runs it
+before writing the coverage table, the program loop runs it per module, and a task
+whose whole job is "audit X" runs nothing else.
+
+## Three things that are easy to confuse
+
+| File | Runs when | Answers |
+|---|---|---|
+| [`acceptance.md`](acceptance.md) | stage 10 | did everything **on the list** ship, with evidence? |
+| [`loop-guard.md`](loop-guard.md) | any **editing** loop churns | is this pass undoing the last one? |
+| **this file** | any **audit** pass | what is broken or missing that nobody has compared? |
+
+`loop-guard.md` governs loops that *change* things — the fix loop, a re-entered
+stage. Its trip means a decision is being re-litigated at the wrong altitude. This
+file governs loops that *look* for things. Its trip means the axis is exhausted,
+which is a different failure with a different exit. Both can bind one run; they do
+not overlap.
+
+## Why "look again, more carefully" stops working
+
+The method most audits use is **horizontal**: compare the documents against each
+other, then do it again. It works, and then it fails in a way that is invisible
+from inside it. Measured over seven passes on a production repository:
+
+| Pass | Findings | …of which the previous pass's own fixes caused |
+|---|---|---|
+| 4 | 12 | 5 |
+| 5 | 17 | 9 |
+| 6 | 13 | 10 |
+| 7 | 19 | 4 |
+
+By pass six the audit was **mostly repairing itself**. Not fatigue — arithmetic.
+Each pass edits the corpus the next pass reads, so the newest edits are always the
+least-reviewed text present, and they are what the next pass finds. The count stays
+healthy while the yield goes to zero.
+
+A single **vertical** pass over the same repository — one capability walked down
+through its layers — found nine defect classes those seven passes had been
+structurally **unable** to see. Not missed: unable. Two of them:
+
+- **A component that encrypts every object in the system had no key store
+  anywhere.** Its sibling's key table had been modelled for weeks. A comparison
+  needs two sides; this had one.
+- **An edit appended a new version while the derived index still pointed at the
+  old text.** The archive is correct. The index is correct. The answer is correct —
+  *against a version nobody is looking at.* Compare archive to archive and index to
+  index: both pass. **The defect lives in the seam.**
+
+## The ladder
+
+The rungs are **layers of one deliverable**; the work is the **seams between
+them**. Each rung's artefact either exists or it does not — that is what makes
+absence findable.
+
+| Rung | Layer | The artefact that must exist |
+|---|---|---|
+| **L0** | Requirement | a `REQ-###` row in the brief **with a named check** |
+| **L1** | Decision | the locked decision, ADR or `CONTEXT.md` term this REQ rests on |
+| **L2** | Design | a spec section carrying `covers: REQ-…` |
+| **L3** | Contract | an exact signature or schema · **and its failure behavior** |
+| **L4** | Task | a plan task with `Implements:` and a DoD satisfiable **as written** |
+| **L5** | Change | the commits — the thing actually in the tree |
+| **L6** | Test | an **executed** assertion, by name — never "the tests pass" |
+| **L7** | Surface | what a user reaches: scenario, screen state, CLI output, runbook |
+
+**Audit the seams, not the artifacts.** Each rung is internally consistent most of
+the time — that is exactly what the horizontal pass is good at, and it has already
+done it. What survives lives between rungs:
+
+| Seam | The question | What absence looks like here |
+|---|---|---|
+| L0→L1 | does the requirement rest on a **recorded** decision? | a REQ whose check implies a choice nobody ever made or wrote down |
+| L1→L2 | did the decision reach the spec? | an ADR or glossary term agreed at the grill that no spec section cites |
+| L2→L3 | does the section name its contract **and what happens when it fails**? | "handles errors" — no code, no shape, no caller-visible reason |
+| L3→L4 | does every contract have a task that builds it? | stage 4's set-equality covers REQ→task; **nothing** covers contract→task |
+| L4→L5 | did the DoD land in the tree? | a DoD line nothing in the diff satisfies, marked done anyway |
+| L5→L6 | is there an executed observable? | "tests pass"; a test that still passes with the production code deleted |
+| L6→L7 | can a user reach it, and does a doc say so? | shipped behavior with no scenario, no `--help` line, no runbook entry |
+| L7→L0 | does the shipped surface satisfy the requirement's **statement**? | it does what the task said and not what the requirement meant |
+
+The last seam is stage 10's question, expressed as a seam. When it fails, the run
+did every instruction correctly and delivered the wrong thing.
+
+## How one audit pass runs
+
+**Scope: one deliverable, all rungs.** One REQ, one module, one capability. Not
+"audit the docs" and not "audit the change" — an unscoped instruction is what
+produces seven converging passes.
+
+**Input** is the artifact that already names every rung: the brief's REQ row plus
+the module map row ([`decomposition.md`](decomposition.md)) when there is one. **If
+the input can't supply the rungs, that is the first finding** — do not go looking
+for the layers by hand; record that the spine is missing and fix that first.
+
+**Procedure: bottom-up, L0 → L7, running the seam check at each step.**
+
+The direction is not taste. A missing artefact at L1 makes everything above it
+meaningless, so top-down you spend the pass polishing a surface for a contract that
+does not exist. Bottom-up, the absence surfaces first and the six findings above it
+collapse into one.
+
+**Output: findings ordered by seam, never by file.** A file-ordered list reads as
+noise; a seam-ordered one tells you **which layer of your own process is leaking**,
+which is the thing worth knowing. Each finding carries `file:line`, the artefact
+that is missing, and the minimal fix.
+
+**Close through the pipeline, not around it.** A finding that is a genuine gap
+becomes a **new REQ row** (with its check) or a carry-over row — the list is frozen
+against *narrowing*, never against additions ([`grill.md`](grill.md) → *The REQ
+spine*). A finding that contradicts the spec goes back to stage 3; one that
+contradicts the plan goes back to stage 4. Auditing is not a licence to edit
+across layers in place.
+
+## Exit criterion — the part usually skipped
+
+A deliverable is **not** audited when somebody has read it. It is audited when:
+
+1. every rung has its artefact, **and**
+2. **every check you are relying on has fired at least once against a planted
+   defect.**
+
+**A green result from an unproven check is worth nothing.** This is the iron law of
+[`tdd.md`](tdd.md) — *if you didn't watch it fail, you don't know it tests the
+right thing* — raised from one test to every gate in the run. It applies to the
+stage-4 set-equality check, the host's lint and test commands, the super-ux linter,
+any script the host added, and every check you write during the audit itself.
+
+Checks written under time pressure lie in ways that read as success: a predicate
+that inspects the wrong shape and finds nothing; a probe that removes more than it
+adds and reads the shrinkage as a pass; a regex that misses the very word it
+searches for. All three pass loudly. **Plant the defect. Watch the check fail.
+Remove it. Then trust the green.** Record in the ledger that you did.
+
+## The three rules that stop this becoming another loop
+
+### 1. A class that repeats twice becomes a gate, not a note
+
+Once is an incident. **Twice is a category, and a category belongs in a script** —
+the host's lint, its CI, its check runner — where nobody has to remember it.
+
+Writing the third instance into the carry-over ledger is how a known, mechanical
+defect class becomes permanent. If the class genuinely cannot be checked
+mechanically, say so in one line and *say why*; that sentence is itself a finding
+worth having.
+
+### 2. Every pass changes the axis, not the effort
+
+"Look again, more carefully" is what converges. Passes must be **orthogonal by
+construction**:
+
+1. **Seams** — one deliverable walked L0→L7 (this file's ladder).
+2. **Invariants across deliverables** — one name, one enum, one owner, one spelling,
+   everywhere. This is the horizontal pass, and it is where it belongs.
+3. **One class swept end to end** — every error path, every count, every status
+   vocabulary, every timeout, across the whole change at once.
+
+**The crossover is measurable, so measure it.** Every pass, count two numbers: new
+findings, and findings caused by the previous pass's own fixes. When the second
+overtakes the first, the axis is exhausted — **rotate it, don't push harder.** Both
+counts go in the ledger; an audit that reports only "found N" cannot see its own
+exhaustion.
+
+### 3. What can't be fixed now becomes a ratchet, never a TODO
+
+A **ratchet** is a *named, counted set that may only shrink, printed on every
+run*.
+
+The carry-over ledger ([`templates/carryover.md`](../templates/carryover.md)) is
+the pipeline's ratchet, and it only works if its count is **printed at every gate
+beside the verdict**:
+
+```
+GATE 6 tests: PASS — full suite green (247 tests)
+  carry-over: 4 open (was 6) · unresolved: 0 · audit findings deferred: 2
+```
+
+The difference from a TODO is not bookkeeping. A TODO is invisible until somebody
+opens the file. A ratchet sits next to the word `PASS` on every single run, so
+**"green" never reads as "verified"** — it reads as *"green, and here is exactly
+what was not looked at."* A ratchet that grew needs a sentence in the run log
+explaining why; a ratchet nobody prints is a TODO with a better name.
+
+## When this runs
+
+- **Stage 10, before the coverage table.** Acceptance reads the REQ list; the
+  ladder walk is what can add to it. Absences found here become new REQ rows with
+  their checks, and *then* the table is written — otherwise acceptance closes green
+  over a gap that was never a row.
+- **Per module in the program loop** ([`decomposition.md`](decomposition.md)) — one
+  brick's ladder, at that brick's acceptance. Cross-module contracts are audited at
+  the seam that owns them, not twice.
+- **As the whole task**, when the operator's request *is* an audit. Then stages 3–5
+  produce findings and fixes rather than a feature, and the exit criterion above is
+  the stage-10 gate.
+- **Never as an eighth "look again" pass.** If the last two passes found mostly
+  self-inflicted findings, the answer is rule 2, not another pass.
+
+Once both axes are exhausted, the next finding of a known class should be caught by
+a script — and if it cannot be, **that is the finding: write the check.**
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "The gates all passed, so it's complete" | Gates compare. Nothing that was never written appears on either side of a comparison. |
+| "One more careful pass will catch it" | Measured: by pass six the passes were mostly fixing their own last pass. Rotate the axis. |
+| "I'll audit top-down, the surface is where users are" | A surface built on an absent contract wastes the whole pass. Bottom-up, that absence is finding #1. |
+| "The check is green, that's evidence" | Only if you have seen it red. An unproven check is a decoration that reports success. |
+| "It's a small gap, I'll note it in the ledger" | Second occurrence of a class → it goes in a script. The ledger is for what cannot be automated, not what nobody automated. |
+| "Findings grouped by file are easier to fix" | And impossible to learn from. Group by seam; the seam names which layer of your process leaks. |
+| "The ledger has it, we won't forget" | Only if it is printed beside every verdict. Unprinted, it is a TODO, and TODOs are invisible by construction. |
+| "This is out of scope for the audit" | Then it is a carry-over row with a home, right now. An audit that silently declines findings is worse than none. |

package/plugins/task-pipeline/skills/task-pipeline/references/build.md

@@ -234,6 +234,12 @@ Two routes leave before the loop starts:
 - **Minor findings** never enter it. Record each in the ledger
   (`Task <N>: minor (deferred): <one-liner>`) and point the final review at that
   list. A roll-up nobody reads is a silent discard.
+- **A finding class that shows up a second time stops being a finding and becomes a
+  check.** Two tasks flagged for the same mechanical defect — the same missing
+  failure path, the same magic value, the same naming slip — means every later task
+  will produce it too. Add it to the host's lint or check script now, in its own
+  commit, instead of writing the third instance into the ledger
+  ([`audit.md`](audit.md) → *A class that repeats twice becomes a gate*).
 - **A finding that conflicts with what the plan mandates** is the operator's
   call: present the finding beside the plan text and ask which governs. Don't
   dismiss the finding because the plan mandated it; don't fix against the plan

package/plugins/task-pipeline/skills/task-pipeline/references/companion-skills.md

@@ -21,6 +21,7 @@ better, plus one that is required only for user-facing work.
 | 5 Build (isolation, subagents, fix loop) | `references/build.md` + `references/review.md` |
 | 5–6 TDD + suite gate | `references/tdd.md` |
 | 10 Acceptance (REQ close-out) | `references/acceptance.md` |
+| 10 + any audit (finding what's missing) | `references/audit.md` |
 | any repeating loop | `references/loop-guard.md` |
 
 ## The matrix

package/plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md

@@ -10,6 +10,14 @@ the pipeline: the stage-5 fix loop, a stage re-entered after a failed gate, the
 per-module program loop ([`decomposition.md`](decomposition.md)), and any
 audit → fix → audit cycle.
 
+**This file governs loops that *change* things.** A loop that *looks* for things —
+pass after pass over one corpus — fails differently: it does not oscillate, it
+**converges**, quietly spending each pass on the previous pass's own edits while the
+finding count stays healthy. That has its own detector and its own exit (rotate the
+axis, don't push harder): [`audit.md`](audit.md) → *Every pass changes the axis*.
+Both can bind one run. Use this file's trips for edits, that file's crossover for
+searches.
+
 ## Bookkeeping — the thing that makes detection mechanical
 
 You cannot detect churn from memory, especially after compaction. Every repeating

package/plugins/task-pipeline/skills/task-pipeline/references/stages.md

@@ -262,6 +262,17 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   surfaces.
 - **Runs last**, after docs and wiki — those are deliverables too, and a REQ may
   name them.
+- **The ladder walk runs FIRST** ([`audit.md`](audit.md)). The REQ table can only
+  find what was named and lost; it cannot find what was never named, because a
+  comparison needs two sides and an absence has one. So before the table: walk each
+  REQ bottom-up through its rungs (decision → spec section → contract **and its
+  failure behavior** → task → change → executed test → surface/docs), check the
+  seam at each step, and order the findings **by seam, not by file**. An absence
+  becomes a **new REQ row with its check** and *then* the table is written;
+  appending after the table is how acceptance goes green over a gap. Findings that
+  belong to a lower layer go back to that layer (spec → stage 3, plan → stage 4).
+  Record the pass's two counts — new findings, and findings caused by this run's
+  own fixes — so the next pass can tell whether the axis is exhausted.
 - **How it runs:** built in. Read the brief's REQ table, the carry-over ledger in
   full, the plan's task statuses, git log, the final suite output, stage-8 notes and
   stage-9 doc changes (plus `docs/ux/scenarios.md` + `/ux-lint` for UI tasks). Write
@@ -274,10 +285,14 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   you asked for, here's what shipped, here's what's deferred and where it lives —
   what's missing?* Ask it even when the table is green; the operator holds context
   the brief never captured, and this is the cheapest moment in the run to hear it.
-- **GATE (manual):** every REQ has a status (none `unknown`); every `verified`
+- **GATE (manual):** the ladder walk ran and its absences became REQ rows before
+  the table was written; **every check this gate leans on has been seen failing
+  once against a planted defect** (an unproven check's green is not evidence);
+  every REQ has a status (none `unknown`); every `verified`
   carries evidence; every `partial` names what's missing and where it's tracked;
   every `deferred`/`dropped` has the operator's agreement and, for `deferred`, a
-  tracker entry; no carry-over row left `unresolved`; the operator answers the
+  tracker entry; no carry-over row left `unresolved`, and the ledger's counts are
+  printed with the verdict; the operator answers the
   closing question and signs off. Manual by design — an automated check can prove
   the table is well-formed, only the person who asked can confirm it is what they
   asked for.
@@ -329,3 +344,20 @@ cycle.
   re-plan the check as an ordered one-item-per-line checklist, then go through it in
   order, one commit per item. Never settle a higher-layer conflict inside a lower
   loop, and never adjudicate before the cap.
+
+## Cross-cutting — the audit
+
+The loop guard governs loops that **change** things. A loop that **looks** for
+things fails the other way: it converges, spending pass after pass on its own last
+pass's edits while the finding count stays healthy. [`audit.md`](audit.md) is that
+method and that exit — the L0→L7 ladder, the seam questions, the axis-rotation
+crossover, and the rule that a green from a check nobody has watched fail is worth
+nothing.
+
+- It runs **at stage 10 before the coverage table** (the only place that can find a
+  requirement nobody ever wrote), **per module** in the program loop, and as the
+  whole task when the request is itself an audit.
+- **A finding class seen twice becomes a script**, not a third ledger row.
+- **Whatever can't be fixed now becomes a ratchet** — a named, counted set that may
+  only shrink, printed beside every gate verdict, so "green" never reads as
+  "verified".

package/plugins/task-pipeline/skills/task-pipeline/references/tdd.md

@@ -15,6 +15,11 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 
 **If you didn't watch the test fail, you don't know it tests the right thing.**
 
+The same law governs every other check in the run — a gate's `check`, a lint rule,
+a host script, a detector written during an audit. A check nobody has seen fail is
+a decoration that reports success. [`audit.md`](audit.md) → *Exit criterion* is
+this rule raised from one test to the whole pipeline.
+
 Wrote code before the test? Delete it and start from the test. Not "keep it as
 reference", not "adapt it while writing tests", not "look at it once more". Delete
 means delete — code you kept is code the test was written to fit.

package/plugins/task-pipeline/skills/task-pipeline/templates/carryover.md

@@ -28,6 +28,29 @@
   with no home is exactly the thing that gets forgotten, so acceptance refuses to
   close on it.
 
+## This ledger is a ratchet, not a TODO list
+
+A TODO is invisible until somebody opens the file. **A ratchet is a named, counted
+set that may only shrink, and it is printed beside every gate verdict:**
+
+```
+GATE 6 tests: PASS — full suite green (247 tests)
+  carry-over: 4 open (was 6) · unresolved: 0 · audit findings deferred: 2
+```
+
+That one line is the whole mechanism. Without it, `PASS` reads as *verified*; with
+it, `PASS` reads as *"green, and here is exactly what was not looked at"* — which
+is the true statement.
+
+- **Print the counts at every gate**, not only at stage 10. A number nobody sees
+  until the end is a number nobody acts on.
+- **The set may only shrink.** If it grew, the run log gets one sentence saying why.
+  A ratchet that grows silently is a TODO with a better name.
+- **A finding class that appears twice stops belonging here** and becomes a check in
+  the host's lint or CI ([`audit.md`](../references/audit.md) → *A class that
+  repeats twice becomes a gate*). This ledger is for what cannot be automated, not
+  for what nobody automated.
+
 ## Notes
 
 - Adding a row costs one line and never blocks a stage — that is the point. The