task-pipeline-skill 1.11.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## v1.13.0 — 2026-08-05
+
+### Added — the read-back: four rules that existed and were never handed over
+
+Stages 3 and 4 produced documents stating things nobody verified: that a named
+check exists, that the spec agrees with decisions already made, that the
+self-review happened at all, and that the change still costs what it was worth.
+
+Five defects, and **four of them are one shape.** The rule already lived in this
+bundle, in a stage that never handed it to the stage which had to obey it. The
+evidence-for-checks rule sits at stages 6 and 10; the rejected-alternatives rule
+sits at stage 2; `learned.md` rule 14 has sat at stage 9 since v1.4.0. Stage 3
+names checks, contradicts decisions and writes DoDs — and read none of them back.
+
+So the fix is one mechanism applied four times. `spec.md`'s self-review now asks
+whether every check it names is real, reads back the brief's `Decisions locked`
+table **and** the alternatives stage 2 rejected, and prints the cost.
+`planning.md` asks whether every command, path and file a DoD names resolves.
+`learned.md`'s stage map binds rule 14 at 3 and 4, not only at 9.
+
+**The fifth is a genuine absence, and it prints rather than decides.** Nothing
+anywhere asked whether a change had outgrown its worth. The new checkpoint counts
+surfaces, guards and REQ rows now versus at stage 2 and prints all three — the
+stage-3 gate is the operator's, and an agent that narrows the task on its own
+judgement breaks *never narrow the task silently*.
+
+**Both self-reviews now leave a committed trace.** A `## Self-review` section,
+identical in shape across the two files, every line a **computed number rather
+than a tick** — because a number nobody computed is visible as such and a
+checkbox never is. `planning.md` already demanded the REQ set difference be
+*printed*; this extends that principle to the rest of the checklist.
+
+Three guards prove the files carry the items, with four probes. What they cannot
+prove is that a run in someone else's repository performed a self-review — and
+that boundary is stated in the spec, in the guard's own comment and here, because
+a guard claiming otherwise would be the exact defect this release fixes.
+
+Negative self-tests: 76 → 80.
+
+## v1.12.0 — 2026-08-05
+
+### Added — a gate for the defects an agent leaves behind
+
+Every other check in this repository asks whether the work is *right*. None of
+them asked whether the text is *intact* — whether a merge was left half-resolved,
+a stub outlived its task, a generation stopped mid-fence, a file was "shortened"
+while being rewritten, a retried edit duplicated a block instead of replacing it,
+or a section was opened and abandoned. That class has an author, and the author is
+an agent.
+
+`templates/hygiene.sh` is the answer: a seeded, executable gate, sibling of
+`docgate.sh`, carrying the same contracts — a `SCOPE:` header that names its own
+false-positive surfaces, a VERDICT block that must be last, portability to macOS
+bash 3.2, progressive arming, and a final line of computed numbers. It runs in two
+modes: the run's diff at **zero tolerance**, and the whole tree behind per-check
+**ratchet floors**, so an existing repository can adopt it without starting red
+while nothing new is forgiven.
+
+**It never edits.** None of the six defects is safely machine-fixable — deleting a
+"duplicated block" sometimes deletes a legitimate repetition, and deleting a `TODO`
+erases a reminder instead of discharging it. `references/build.md` makes fixing the
+agent's obligation, at the point it is cheapest: after each task reports `DONE`,
+before the reviewer sees it. Found one task later, a defect costs a re-dispatch;
+found eight tasks later it is fixed by an agent that no longer remembers the code.
+
+**Two of the six definitions were wrong until they were measured**, which is the
+point of the rule that says measure a detector before shipping it. Matching the
+word `TODO` anywhere found 33 hits here, 28 of them ordinary English — this is a
+repository whose own doctrine is *"a ratchet, never a TODO"*. Anchored as a
+line-leading marker: 0. Flagging a heading followed by any heading found 62
+legitimate nestings; restricted to same-or-higher level it found 4, and the
+detector still had a bug — fenced lines were skipped entirely, so a section whose
+body is one code block looked empty. Counting fenced content as body: 2, both real.
+Check 4 then repeated check 2's mistake in its sibling and was caught the same way.
+
+Those last 2 were fixed rather than absorbed into a floor, so all six ship at 0.
+One of them was a shape mistake in the retro template every project copies: a
+one-line retirement record written as a heading, when a heading promises a section.
+
+### Fixed — a guard that had been decorative since it shipped
+
+Writing the first probe for the VERDICT-last contract revealed that the guard split
+each gate script on the *word* `VERDICT`, which also appears in the header sentence
+forbidding anything after it. Its "tail after the verdict" was therefore most of the
+script, exit lines included, and it passed on anything. It now splits on the
+`# ---------- VERDICT` marker and requires that marker to exist. A green from a
+check nobody has watched fail is not evidence; this one was green for nine releases.
+
+The template contract guards now iterate a `GATE_SCRIPTS` list instead of naming one
+file, so a third gate costs one line rather than a copied block that drifts.
+
+Negative self-tests: 68 → 75.
+
 ## v1.11.0 — 2026-08-04
 
 ### Added — run continuity: the pacing rules the operator was repeating by hand

package/CONTRIBUTING.md

@@ -117,6 +117,20 @@ found**, and run a minimum of live checks — because every section can go `dorm
 and a gate blind to a shape passes exactly like one that reads it. Change a template
 → run `npm test`, not just your eyes.
 
+**The same law now covers `templates/hygiene.sh`.** It is run over a clean scratch
+project, must exit `0`, and must report all six of its check counts — exit `0` alone
+proves nothing, because every check can go `dormant` and dormant is green. Both gate
+scripts are validated by one iterated block, not two copies, and both must keep a
+`# ---------- VERDICT` marker with nothing after it.
+*(guard: `the VERDICT block must be last and must `)*
+
+**Stages 3 and 4 must keep reading their rules back.** `spec.md`'s self-review asks
+whether every check it names is real, reads back the brief's decisions and stage 2's
+rejected options, and prints the cost; `planning.md` asks whether every command a DoD
+names resolves; `learned.md` binds rule 14 at both stages. Both files carry a
+committed `## Self-review` section of computed numbers rather than ticks.
+*(guard: `the self-review no longer asks `)*
+
 **11. Every reference over 100 lines carries a `## Contents` list**, and the list is
 compared against that file's own `##` headings. The guidance asks for it because a
 long file gets previewed with a partial read; the comparison is because a hand-kept

package/README.md

@@ -129,6 +129,7 @@ until it is installed.
 | any loop | [`loop-guard.md`](plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md) — churn detection, caps, the break protocol |
 | run-wide pacing | [`continuity.md`](plugins/task-pipeline/skills/task-pipeline/references/continuity.md) — the loop mode (`run.loop`, default off, never collapses a manual gate) and the context budget (fires on a harness signal, never on an estimate) |
 | 0 + 9 + any settled decision | [`documentation.md`](plugins/task-pipeline/skills/task-pipeline/references/documentation.md) — the inventory, registers and ids, SSOT, the Doc Loop, supersede semantics, the propagation matrix, intent vs as-built |
+| 3 + 4 · every spec and plan | the self-review reads its rules back — is every named check real, does anything contradict a locked decision or a rejected option, and what does this cost now versus at design time. Answers land as a committed `## Self-review` of computed numbers |
 | 6–10 + any check you write | [`gates.md`](plugins/task-pipeline/skills/task-pipeline/references/gates.md) — the two axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors |
 | any agent-time enforcement | [`hooks.md`](plugins/task-pipeline/skills/task-pipeline/references/hooks.md) — the `PreToolUse` contract, the fail-open hazard, the Claude-Code-only limit |
 
@@ -776,7 +777,7 @@ recommendation, so you arm the whole run in one exchange. Detail:
 | [`references/knowledge-graph.md`](plugins/task-pipeline/skills/task-pipeline/references/knowledge-graph.md) | the code graph: install line, stage-0 reach queries, the stage-9 refresh, the graph↔docs divergence check |
 | [`references/retrospective.md`](plugins/task-pipeline/skills/task-pipeline/references/retrospective.md) | the project retro: the three grades of fix, the mandatory prune, the cap of ten |
 | [`references/model-tiering.md`](plugins/task-pipeline/skills/task-pipeline/references/model-tiering.md) | model policy, the `/model` reminder, overrides |
-| [`templates/`](plugins/task-pipeline/skills/task-pipeline/templates/README.md) | brief, carry-over ledger, `CONTEXT.md` and ADR skeletons, the doc map, both registers, the retro and its archive, the seeded `docgate.sh`, a worked hook |
+| [`templates/`](plugins/task-pipeline/skills/task-pipeline/templates/README.md) | brief, carry-over ledger, `CONTEXT.md` and ADR skeletons, the doc map, both registers, the retro and its archive, the seeded `docgate.sh` and `hygiene.sh`, a worked hook |
 | [`references/adoption.md`](plugins/task-pipeline/skills/task-pipeline/references/adoption.md) | the first run in a project: greenfield seeding, and the brownfield walkthrough |
 | [`references/setup.md`](plugins/task-pipeline/skills/task-pipeline/references/setup.md) | the entry audit: seven passes over the docs a project already has, offered once, output as a fix plan |
 | [`references/portability.md`](plugins/task-pipeline/skills/task-pipeline/references/portability.md) | the manifest of workflow decisions and their homes in the bundle, and the boundary against a project's own answers |

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
 | **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
-| **Version** | 1.11.0 |
+| **Version** | 1.13.0 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
 | **Evaluation status** | Suite authored (15 evals, 5 categories). **Never executed** — see [`evals/RESULTS.md`](evals/RESULTS.md) |
@@ -38,7 +38,7 @@ apply.
    instruction surface, and every one is linked directly from `SKILL.md`.
 2. Read `templates/docgate.sh` before seeding it; it is the only shipped script a
    host project will run on its own repository.
-3. Run `npm run test:all` — 68 guards, each with a negative self-test that plants a
+3. Run `npm run test:all` — 80 guards, each with a negative self-test that plants a
    defect and requires rejection.
 4. Run `python3 evals/run.py` for the behavioural protocol, and read
    `evals/RESULTS.md` for what has actually been observed.
@@ -54,7 +54,7 @@ apply.
 - **Versions are pinned by git tag** and mirrored into `sshlg-skills`'s catalogue.
   Rollback is `git checkout v<previous>` or pinning the previous plugin version;
   the previous version is never deleted.
-- **Behavioural evidence is missing, not merely thin.** 68 structural guards prove
+- **Behavioural evidence is missing, not merely thin.** 80 structural guards prove
   the skill is well-formed. Until `evals/RESULTS.md` carries a dated run, nothing in
   this repository proves it *behaves* — triggers correctly, stays quiet on a
   question, or performs the steps it documents.

package/cursor/rules/task-pipeline.mdc

@@ -197,6 +197,13 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
    exact values every later task inherits. Self-review it for placeholders,
    contradictions, ambiguity and scope before showing it. For UI tasks, run the UX
    chain FIRST (see super-ux below) and embed it.
+   **Before handing a spec or a plan over, read your rules back:** does every
+   check you named actually exist (or say `review`)? does anything here
+   contradict a decision already locked, including an option deliberately
+   rejected? how many surfaces, guards and requirements is this now versus
+   when the design was approved — print all three and let the operator
+   decide. Leave the answers as a committed `Self-review` section of
+   computed numbers, not ticks.
 4. **Plan** (auto) — every task names the REQ ids it `Implements:`, and the set of those ids must **equal** the brief's REQ set — a difference is scope lost, print it and fix it. Zero-context tasks: exact paths, complete code in every step,
    the exact command and its expected output, TDD steps, DoD each, dependency graph
    + parallel groups, non-overlapping file ownership. **No placeholders** — no TBD,
@@ -207,7 +214,15 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
    commit), then a review with **all three** verdicts — spec compliance, **REQ
    satisfied** (judged against the requirement's own statement, not the task's
    instructions), and code quality. Findings loop back to the implementer (max 5
-   rounds, then adjudicate in writing); minor findings are recorded, never blocking. Keep a progress ledger in
+   rounds, then adjudicate in writing); minor findings are recorded, never blocking.
+   **After each task reports done, before the review, scan what that task changed
+   for the defects an agent leaves behind** — a half-resolved merge, a stub that
+   outlived the task, a code fence left open, a file "shortened" while being
+   rewritten, a block duplicated by a retried edit, a section opened and abandoned.
+   Zero tolerance on a diff: that task wrote it, that task fixes it. A subagent's own
+   report is not evidence about the text it left behind, and a duplicated block eight
+   tasks later is repaired by an agent that no longer remembers the code.
+   Keep a progress ledger in
    a file so a lost context can resume instead of redoing finished work. Tasks in
    the same parallel group run concurrently **only** if each worker has its own
    worktree — otherwise sequential. Close the stage by integrating: sync with the

package/evals/RESULTS.md

@@ -37,13 +37,16 @@ or it belongs in a check.
 | Dated runs recorded | **0** | 2026-08-03 |
 
 The bottom two numbers are the honest state of this skill's behavioural evidence.
-Everything else in this repository is proven by 68 structural guards that check the
+Everything else in this repository is proven by 80 structural guards that check the
 *form*; these are the only checks that would speak to the *behaviour*, and they have
 not been run yet. Printed here so "63 of 63 green" is never read as "the skill is
 known to work".
 
 ## Runs
 
+Newest first. Each entry states the model, the task, and how the evidence was
+obtained — a self-observed run and a blind one are not the same claim.
+
 ## 2026-08-03 · opus · self-observed, not a blind run
 
 **Scope of this evidence.** The author ran the skill on a real task

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.11.0",
+  "version": "1.13.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

@@ -2,7 +2,7 @@
   "name": "task-pipeline",
   "displayName": "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.11.0",
+  "version": "1.13.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -156,6 +156,7 @@ plugins/task-pipeline/
       conventions.md artifacts.md             #   host conventions, this layout
       companion-skills.md                     #   optional companions + preflight
     templates/                                # skeletons seeded into a host project
+      hygiene.sh                            # -> scripts/check-hygiene.sh (stages 5, 6, 9)
       README.md brief.md carryover.md context.md adr.md retro.md
 cursor/rules/task-pipeline.mdc                # Cursor channel (self-contained rule)
 bin/task-pipeline.js                          # npx installer (package task-pipeline-skill)

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

@@ -247,11 +247,35 @@ physical: **two implementers writing one working tree corrupt each other's state
 
 | Status | Action |
 |---|---|
-| `DONE` | Build the review package, dispatch the task review ([`review.md`](review.md)). |
+| `DONE` | **Run the hygiene gate in diff mode first** (below), then build the review package and dispatch the task review ([`review.md`](review.md)). |
 | `DONE_WITH_CONCERNS` | Read the concerns first. Correctness or scope → resolve before review. Observations ("this file is getting large") → **append to the carry-over ledger**, then proceed. A concern that stays only in the report dies with the workspace. |
 | `NEEDS_CONTEXT` | Supply exactly what's missing, re-dispatch. |
 | `BLOCKED` | Diagnose: missing context → re-dispatch with it; needs more reasoning → a more capable model; too large → split the task; the plan itself is wrong → escalate to the operator. |
 
+### The hygiene gate — after every task, before the review
+
+A subagent's own report is not evidence about the text it left behind. Run the
+seeded gate over **what this task changed**, before the reviewer sees it:
+
+```bash
+HYGIENE_BASE=<the commit recorded before dispatching> bash scripts/check-hygiene.sh
+```
+
+Diff mode has **no floor**: this task wrote it, this task fixes it. Six checks — a
+half-resolved merge, a stub that outlived the task, a fence left open, a file
+"shortened" while being rewritten, a **block duplicated by a retried edit**, and a
+section opened and abandoned.
+
+The fifth is why the gate runs here rather than only at stage 6. A batch of edits
+where one applied twice, or never applied at all, is the incident behind standing
+instruction R-002 — and it is invisible in a status report. Found one task later it
+costs a re-dispatch; found eight tasks later it is fixed by an agent that no longer
+remembers the code.
+
+**The gate never edits. Fixing is yours.** A finding is repaired inside the same
+task, or it becomes a carry-over row with a reason — never a silent pass. A gate
+whose findings nobody acts on is a slower way of ignoring them.
+
 **Never** ignore an escalation, and never re-dispatch the same model with the same
 prompt after a BLOCKED. If the implementer says it's stuck, something must change.
 If the implementer asks a question — before or mid-task — answer it completely; do

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

@@ -154,6 +154,8 @@ answer would have exposed it in a minute.
 | 3 Spec · 4 Plan | 2 (both directions), 8 (compute, never restate) |
 | 5 Dev | 9 (generators seed green), 12 (tests create their own state), 13 (local infra) |
 | 6 Tests | 4, 5, 10, 11 — every new check probed both ways, measured, and asserted on its exit code |
+| 3 Spec | 14 — every check the spec **names** must resolve at the moment it is named, or be marked `review` |
+| 4 Plan | 14 — every command, path and file a DoD names must resolve |
 | 9 Docs | 8, 14 — every number computed, every target resolvable |
 | 10 Acceptance | 1, 3, 6, 7 — axis rotation recorded, closure verified against artefacts, classes swept, ratchets printed |
 

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

@@ -193,6 +193,34 @@ A checklist you run yourself, inline. No subagent:
 5. **Parallel safety:** no two tasks in the same group write the same file; every
    `depends:` points at a task that really produces what's consumed.
 6. **DoD present and verifiable** on every task.
+7. **Every command, path and file a DoD names resolves.** Walk each task's
+   *Definition of done* and its steps and check the targets exist — a DoD that says
+   `npm run lint:paths` when no such script exists is an instruction the implementer
+   cannot follow and a check the acceptance cannot run.
+   [`learned.md`](learned.md) rule 14 has said *every target resolvable* since
+   v1.4.0 and fired only at stage 9 — four stages after the target is written here.
+8. **Run the hygiene gate** over what this stage wrote and record its counts below.
+
+**R-003 asked of this file, and answered:** `spec.md`'s items 8 and 9 — reading
+decisions back, and printing the cost — deliberately do **not** appear here. This
+stage settles nothing (see below), so it has no decisions to contradict and no scope
+of its own to grow. Its sibling's item 7 does belong, reworded for DoDs.
+
+### The `## Self-review` section — committed, not asserted
+
+Identical in shape to `spec.md`'s, so one habit covers both stages. Last section
+before the gate; every line a **computed number, not a tick**.
+
+```markdown
+## Self-review
+
+- REQ coverage: <n> in brief, <n> covered, difference <set or ∅>
+- Named checks: <n> named, <n> resolve, <n> marked `review`
+- Decisions: checked against <the brief's D-table> and <stage 2's rejected options> — <verdict>
+- Cost: <surfaces>/<guards>/<REQ> now, <…> at stage 2 — <proportionate | grown, and why>
+- Hygiene: <n> checks, <n> findings, <n> open
+- Placeholders: <n> · Ambiguity: <n> found, <n> resolved inline
+```
 
 ## This stage settles nothing — and that is a rule, not an omission
 

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

@@ -57,6 +57,8 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | Rules earned by failure | `references/learned.md` |
 | **The routing default and its boundary** | `templates/routing-rule.md` |
 | The seeded doc map, registers and gate | `templates/docmap.md`, `templates/decisions.md`, `templates/open-questions.md`, `templates/docgate.sh` |
+| Which agent-introduced defects are found, and that the agent fixes them rather than the script | `templates/hygiene.sh`, `references/build.md` |
+| What a stage-3/4 self-review must read back, and that its trace is computed numbers | `references/spec.md`, `references/planning.md`, `references/learned.md` |
 | What a stage reads, and which host files bind it | `references/artifacts.md` |
 | The design conversation, its hard gate, UI detection, user paths | `references/brainstorm.md` |
 | Cutting a platform into modules, brick criteria, build order | `references/decomposition.md` |

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

@@ -143,6 +143,42 @@ Read what you wrote with fresh eyes and fix inline. No subagent, no second pass:
 4. **Scope:** is this one implementable plan, or does it need decomposition?
 5. **Ambiguity:** can any requirement be read two ways? Pick one and say it.
 6. **Traceability (UI):** does every user-facing requirement name its scenario ID?
+7. **Every check this spec names resolves.** Walk the verification claims — the
+   table, and every sentence that says how something is proven. For each: does that
+   check exist today, or is this plan building it? A check that is neither is **not**
+   a verification: mark it `review` and say so, or build it. This repository's whole
+   doctrine is that a green from a check nobody watched fail is not evidence — and
+   this stage is where checks are first *named*, which is one step earlier than
+   anyone was looking.
+8. **Read the decisions back.** Open the brief's `## Decisions locked` table **and**
+   the register entries stage 2 recorded for the alternatives it *rejected*
+   (`references/brainstorm.md` → *The approved design is a set of decisions*). Does
+   any contract here contradict one? Resolve it **out loud** — amend the spec, or
+   reverse the decision and record the reversal. A spec that quietly contradicts a
+   settled decision re-opens a question the operator already answered.
+9. **Print the cost.** Count the surfaces this spec touches, the guards it adds and
+   the REQ rows, now versus at stage 2. **Print all three and decide nothing.**
+   Growth is information for the operator, whose gate this is; an agent that narrows
+   the task on its own judgement breaks *never narrow the task silently*.
+10. **Run the hygiene gate** over what this stage wrote and record its counts below.
+
+### The `## Self-review` section — committed, not asserted
+
+The checklist above leaves a **committed trace**, last section before the gate.
+Every line carries a **computed number, not a tick**: a number nobody computed is
+visible as such, and a checkbox never is. `planning.md` uses the identical shape, so
+one habit covers both stages.
+
+```markdown
+## Self-review
+
+- REQ coverage: <n> in brief, <n> covered, difference <set or ∅>
+- Named checks: <n> named, <n> resolve, <n> marked `review`
+- Decisions: checked against <the brief's D-table> and <stage 2's rejected options> — <verdict>
+- Cost: <surfaces>/<guards>/<REQ> now, <…> at stage 2 — <proportionate | grown, and why>
+- Hygiene: <n> checks, <n> findings, <n> open
+- Placeholders: <n> · Ambiguity: <n> found, <n> resolved inline
+```
 
 ## Locked contracts are decisions — the register, not only the spec
 

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

@@ -251,7 +251,10 @@ never that the work was skipped quietly.
   `SCR-` screens, the CJM stages the feature serves, and the UX
   patterns/principles from super-ux that apply (`best-practices.md`,
   `ux-design-principles.md`, `component-guidelines.md`).
-- **GATE (manual):** spec committed **and** user-reviewed; **every section carries
+- **GATE (manual):** the **`## Self-review` section written and committed with
+  computed values** — every check the spec names resolving or marked `review`, the
+  brief's decisions and stage 2's rejected options read back with no unresolved
+  contradiction, and the cost delta printed; spec committed **and** user-reviewed; **every section carries
   `covers: REQ-…` and every REQ appears in at least one section**; for UI tasks
   additionally: the super-ux chain (foundation → flows → screens → scenarios) is
   designed, validated and approved; scenarios validated in `docs/ux/scenarios.md`;
@@ -270,7 +273,8 @@ never that the work was skipped quietly.
   paths, complete code in every step, TDD steps with expected output, DoD each,
   dependency graph + parallel groups, non-overlapping file ownership, and the
   Global Constraints block copied verbatim from the spec.
-- **GATE (auto):** **set equality — the REQ ids in the brief equal the union of
+- **GATE (auto):** the **`## Self-review` section written with computed values**,
+  every command, path and file a DoD names resolving; **set equality — the REQ ids in the brief equal the union of
   `Implements:` across plan tasks.** A non-empty difference fails the gate and is
   reported as the explicit list of dropped requirements; this is the seam where
   scope leaks silently, so the check is mechanical, not a judgement call. Plus:
@@ -296,7 +300,9 @@ never that the work was skipped quietly.
   on the result, land it the project's way (merge, or a PR — outward, so it needs a
   go), remove the worktree. Stages 7–9 act on the integrated result, so a branch the
   operator chose to leave unmerged is recorded as such.
-- **GATE (auto):** all plan tasks DONE (three review verdicts per task: spec
+- **GATE (auto):** **the hygiene gate green in diff mode after every task**
+  (`references/build.md`) — six checks over what that task changed, no floor, and a
+  finding fixed in-task or carried over with a reason; all plan tasks DONE (three review verdicts per task: spec
   compliance, **REQ satisfied**, code quality); every finding fixed or parked with a
   ruling; **every parked finding and implementer concern harvested into the
   carry-over ledger** — nothing stays only in the scratch workspace, which is
@@ -311,7 +317,8 @@ never that the work was skipped quietly.
 - **Invoke:** the host test runner (see `conventions.md` → *Lint + test*); the
   built-in [`tdd.md`](tdd.md) cycle for any uncovered gap — failing test first,
   same as stage 5.
-- **GATE (auto):** the **full** suite is green (not just the new tests); new/changed code
+- **GATE (auto):** **the hygiene gate green over the whole tree**, its six counts
+  printed beside their floors; the **full** suite is green (not just the new tests); new/changed code
   is covered; no `skip`/`xfail` smuggling a red suite past the gate. Never advance
   to deploy on a red or partial run. **The carry-over count is printed beside this
   verdict** — a ratchet nobody prints is a TODO with a better name
@@ -381,7 +388,7 @@ never that the work was skipped quietly.
 - **Docs living in another repository** are outward: propose the edit, get an
   explicit go, then open a PR there. No go → the exact edit goes in the carry-over
   ledger.
-- **GATE (auto):** **the propagation matrix walked for every change type this run
+- **GATE (auto):** **the hygiene gate green**, counts printed; **the propagation matrix walked for every change type this run
   produced**, with every settled thing recorded under an id and every answered
   question resolved; **the documentation gate green, its ratchet counts printed and
   any skip stated** — this is what replaced the unfalsifiable *"docs in sync with

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

@@ -17,6 +17,7 @@ from `super-ux`.
 | `decisions.md` | `docs/DECISIONS.md` — the decision register | 0 seeds it, the Doc Loop appends |
 | `open-questions.md` | `docs/OPEN_QUESTIONS.md` | 0 seeds it, the Doc Loop resolves rows |
 | `docgate.sh` | `scripts/check-docs.sh` | 0 seeds it · 9 runs it · 10 proves it |
+| `hygiene.sh` | `scripts/check-hygiene.sh` | 0 seeds it · **5 runs it after every task** · 6 and 9 run it · 10 proves it |
 | `hooks.example.json` | the project's `.claude/settings.json` | 0 — offered, never installed silently |
 | `routing-rule.md` | the operator's `CLAUDE.md` — **offered by `setup`, never written silently** | 0 / `setup` |
 | `retro.md` | `docs/superpowers/retro.md` — **one per project, not per run** | 10 writes (prune → stamp → entry), 0 reads it in full |

package/plugins/task-pipeline/skills/task-pipeline/templates/hygiene.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# hygiene.sh — the artifact hygiene gate for <project>.
+#
+# Seeded by task-pipeline (references/gates.md). IT IS YOURS NOW: extend it here,
+# section by section. Each section is independent and removable.
+#
+# WHAT IT IS FOR: the defect class an AGENT produces and no other check looks for —
+#   a half-resolved merge, a stub that outlived its task, a generation cut off in the
+#   middle, a file "shortened" while being rewritten, a batch of edits where one
+#   applied twice, a section opened and abandoned.
+#
+# SCOPE: walks tracked files. In diff mode it walks only what this run changed; in
+#   tree mode it walks everything, behind per-check floors.
+#   It does NOT check: prose meaning, code correctness, style, formatting, spelling,
+#   another repository, or generated output. It is not a linter — your language has
+#   one, and this is not it.
+#   KNOWN FALSE-POSITIVE SURFACES, one per check, because a gate that hides them
+#   gets disabled the first time it is wrong:
+#     1 conflict markers   — a document explaining merge conflicts
+#     2 placeholders       — only a LINE-LEADING marker counts. The word TODO in the
+#                            middle of a sentence is prose, not a stub. This
+#                            distinction is the whole check: measured on the project
+#                            that ships it, 28 of 33 hits were ordinary English.
+#     3 unterminated fence — a fence deliberately shown unclosed as an example
+#     4 truncation stubs   — a document quoting one as an example of what not to do
+#     5 duplicated block   — a legitimately repeated stanza 3+ lines long
+#     6 empty section      — a heading used as a one-line record. If you have those,
+#                            they want to be list items: a heading promises a section.
+#   Read this header before quoting a green from here as evidence.
+#
+# IT NEVER EDITS. It reports file:line and exits non-zero. None of the six is safely
+#   machine-fixable: deleting a "duplicated block" sometimes deletes a legitimate
+#   repetition, and deleting a TODO erases a reminder instead of discharging it.
+#   Fixing is the agent's job, and task-pipeline's references/build.md makes it one.
+#
+# EXIT CODE IS THE OUTPUT: non-zero on any failure. Nothing may run after the
+#   VERDICT block at the bottom — a gate that appended a check after its verdict
+#   printed FAIL and returned 0, and CI was green over it for an unknown period.
+#
+# PORTABLE to macOS bash 3.2: no grep -P, no sed -i, no readarray, no mapfile.
+#
+# PROGRESSIVE ARMING: a check whose input does not exist prints
+#   "dormant: … — no <input>" and does NOT fail. Dormant is visible so it is not
+#   forgotten, and green so a freshly seeded project does not start red.
+#
+# TWO MODES, AND THE DIFFERENCE IS THE POINT:
+#   diff mode (HYGIENE_BASE set) — ZERO tolerance. This run wrote it, this run fixes
+#     it. There is no floor, because a floor for work you just did is a licence.
+#   tree mode (default)          — per-check RATCHET FLOORS. A count at or below its
+#     floor passes; above it fails. A floor may only fall. This is what lets an
+#     existing repository adopt the gate without starting red, while forgiving
+#     nothing new.
+
+set -u
+
+FAIL=0
+HYGIENE_BASE=${HYGIENE_BASE:-}
+HYGIENE_EXCLUDE=${HYGIENE_EXCLUDE:-graphify-out/}
+HYGIENE_FLOOR_1=${HYGIENE_FLOOR_1:-0}
+HYGIENE_FLOOR_2=${HYGIENE_FLOOR_2:-0}
+HYGIENE_FLOOR_3=${HYGIENE_FLOOR_3:-0}
+HYGIENE_FLOOR_4=${HYGIENE_FLOOR_4:-0}
+HYGIENE_FLOOR_5=${HYGIENE_FLOOR_5:-0}
+HYGIENE_FLOOR_6=${HYGIENE_FLOOR_6:-0}
+
+TMP=${TMPDIR:-/tmp}/hygiene.$$
+mkdir -p "$TMP" || exit 2
+trap 'rm -rf "$TMP"' EXIT
+
+err() { echo "  FAIL: $*"; FAIL=1; }
+ok() { echo "  ok:   $*"; }
+dormant() { echo "  dormant: $*"; }
+
+# ---------- the file list ----------
+# git is the source of truth for "authored": generated and ignored files are not
+# this gate's business, and scanning them is how a gate becomes noise.
+if git rev-parse --git-dir >/dev/null 2>&1; then
+  if [ -n "$HYGIENE_BASE" ]; then
+    MODE=diff
+    { git diff --name-only "$HYGIENE_BASE" 2>/dev/null
+      git diff --name-only 2>/dev/null
+      git diff --name-only --cached 2>/dev/null
+    } | sort -u > "$TMP/all"
+  else
+    MODE=tree
+    git ls-files > "$TMP/all"
+  fi
+else
+  MODE=tree
+  find . -type f -not -path './.git/*' | sed 's|^\./||' > "$TMP/all"
+fi
+
+: > "$TMP/files"
+while read -r f; do
+  [ -n "$f" ] || continue
+  [ -f "$f" ] || continue
+  case "$f" in
+    $HYGIENE_EXCLUDE*) continue ;;
+  esac
+  echo "$f" >> "$TMP/files"
+done < "$TMP/all"
+
+NFILES=$(wc -l < "$TMP/files" | tr -d ' ')
+: > "$TMP/md"
+while read -r f; do
+  case "$f" in *.md) echo "$f" >> "$TMP/md" ;; esac
+done < "$TMP/files"
+NMD=$(wc -l < "$TMP/md" | tr -d ' ')
+
+echo "hygiene gate — mode $MODE · $NFILES file(s), $NMD markdown"
+
+# The floor a check is judged against. Diff mode has none: zero tolerance.
+floor_for() {
+  if [ "$MODE" = diff ]; then echo 0; return; fi
+  eval "echo \${HYGIENE_FLOOR_$1}"
+}
+
+judge() { # judge <n> <count> <label>
+  _f=$(floor_for "$1")
+  if [ "$2" -gt "$_f" ]; then
+    err "check $1 — $3: $2 finding(s), floor $_f"
+    sed 's/^/         /' "$TMP/hits$1"
+  else
+    ok "check $1 — $3: $2 (floor $_f)"
+  fi
+}
+
+if [ "$NFILES" -eq 0 ]; then
+  dormant "every check — no files in scope"
+  C1=0; C2=0; C3=0; C4=0; C5=0; C6=0
+else
+
+# ---------- 1. conflict markers ----------
+: > "$TMP/hits1"
+while read -r f; do
+  grep -n -E '^(<<<<<<< |=======$|>>>>>>> )' "$f" 2>/dev/null |
+    sed "s|^|$f:|" >> "$TMP/hits1"
+done < "$TMP/files"
+C1=$(wc -l < "$TMP/hits1" | tr -d ' ')
+judge 1 "$C1" "conflict markers"
+
+# ---------- 2. surviving placeholders ----------
+# A LINE-LEADING marker, optionally behind a comment introducer. Not the word.
+: > "$TMP/hits2"
+while read -r f; do
+  grep -n -E '^[[:space:]]*([#/*<!-]+[[:space:]]*)*(TODO|TBD|FIXME|XXX)\b' "$f" 2>/dev/null |
+    sed "s|^|$f:|" >> "$TMP/hits2"
+done < "$TMP/files"
+C2=$(wc -l < "$TMP/hits2" | tr -d ' ')
+judge 2 "$C2" "surviving placeholders"
+
+# ---------- 3. unterminated code fence ----------
+: > "$TMP/hits3"
+if [ "$NMD" -eq 0 ]; then
+  dormant "check 3 — unterminated fence: no markdown in scope"
+  C3=0
+else
+  while read -r f; do
+    # grep -c exits 1 on zero matches, so a `|| echo 0` would append a SECOND zero
+    # and make the test below see "0\n0". Swallow the status instead.
+    n=$(grep -c '^[[:space:]]*```' "$f" 2>/dev/null) || n=0
+    [ -z "$n" ] && n=0
+    if [ "$n" -gt 0 ] && [ "$(expr "$n" % 2)" -ne 0 ]; then
+      echo "$f:1: odd fence count ($n) — a code block is not closed" >> "$TMP/hits3"
+    fi
+  done < "$TMP/md"
+  C3=$(wc -l < "$TMP/hits3" | tr -d ' ')
+  judge 3 "$C3" "unterminated fence"
+fi
+
+# ---------- 4. truncation stubs ----------
+# LINE-LEADING, exactly like check 2, and for exactly the same reason: the first
+# version matched the phrase anywhere and fired three times on the very documents
+# that DEFINE these patterns. A stub is a line standing in for content; a phrase in
+# the middle of a sentence is prose about stubs.
+: > "$TMP/hits4"
+while read -r f; do
+  grep -n -E '^[[:space:]]*([#/*<!-]+[[:space:]]*)*(\.\.\. existing code|\[TRUNC|rest of (the )?file unchanged|unchanged\.\.\.)' "$f" 2>/dev/null |
+    sed "s|^|$f:|" >> "$TMP/hits4"
+done < "$TMP/files"
+C4=$(wc -l < "$TMP/hits4" | tr -d ' ')
+judge 4 "$C4" "truncation stubs"
+
+# ---------- 5. duplicated adjacent block ----------
+# The mechanical form of "re-verify every edit in a batch": a retry that duplicated
+# instead of replacing leaves two identical blocks back to back. Three lines is the
+# floor because two-line repeats occur legitimately (table rows, list pairs).
+: > "$TMP/hits5"
+while read -r f; do
+  awk -v F="$f" '
+    NF { blk = blk "\n" $0; n++; next }
+    {
+      if (n >= 3) { if (blk == prev) print F ":" NR ": duplicated " n "-line block"; prev = blk }
+      else prev = ""
+      blk = ""; n = 0
+    }
+    END { if (n >= 3 && blk == prev) print F ":" NR ": duplicated " n "-line block at end of file" }
+  ' "$f" >> "$TMP/hits5" 2>/dev/null
+done < "$TMP/files"
+C5=$(wc -l < "$TMP/hits5" | tr -d ' ')
+judge 5 "$C5" "duplicated adjacent block"
+
+# ---------- 6. empty section ----------
+# A heading of level N followed by a heading of level <= N with no body between.
+# FENCED CONTENT COUNTS AS BODY — the first version of this check skipped fenced
+# lines entirely and so reported every section whose body is one code block.
+: > "$TMP/hits6"
+if [ "$NMD" -eq 0 ]; then
+  dormant "check 6 — empty section: no markdown in scope"
+  C6=0
+else
+  while read -r f; do
+    awk -v F="$f" '
+      /^[[:space:]]*(```|~~~)/ { fence = !fence; prev = 0; next }
+      fence { prev = 0; next }
+      /^#{1,6} / {
+        match($0, /^#+/); lvl = RLENGTH
+        if (prev && lvl <= prev) print F ":" NR ": empty section — h" prev " then h" lvl " with no body"
+        prev = lvl; next
+      }
+      NF { prev = 0 }
+    ' "$f" >> "$TMP/hits6" 2>/dev/null
+  done < "$TMP/md"
+  C6=$(wc -l < "$TMP/hits6" | tr -d ' ')
+  judge 6 "$C6" "empty section"
+fi
+
+fi
+
+# ---------- VERDICT — nothing may run after this block ----------
+if [ "$FAIL" -ne 0 ]; then
+  echo "FAIL: hygiene gate — mode $MODE · conflict ${C1} · placeholder ${C2} · fence ${C3} · truncation ${C4} · duplicate ${C5} · empty-section ${C6}"
+  exit 1
+fi
+echo "OK: hygiene gate — mode $MODE · $NFILES file(s) · conflict ${C1} · placeholder ${C2} · fence ${C3} · truncation ${C4} · duplicate ${C5} · empty-section ${C6}"
+exit 0

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

@@ -48,7 +48,13 @@ stays short precisely so that reading it in full at stage 0 stays cheap.
 - **Upstream?** … (a lesson true in any repo belongs in the skill's own
   `references/learned.md` — open an issue and say so here)
 
-### 2026-05-04 · retired R-000 — became a check (`npm run lint:paths`) · `<sha>`
+### Retirements
+
+One line each, newest first. A retirement is a record, not a section — so it is a
+list item. A heading promises a body, and a heading with nothing under it is the
+shape the hygiene gate's check 6 exists to find.
+
+- 2026-05-04 · retired R-000 — became a check (`npm run lint:paths`) · `<sha>`
 
 ## Run stamps