task-pipeline-skill 1.10.3 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## 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
+
+Two rules that had to be said out loud at the start of every run. One of them was
+already written down, which is the interesting half.
+
+**The loop mode is now config, not a request.** `references/build.md` has carried
+*"Continuous execution: don't check in between tasks"* since early on, and it did
+not work — for two compounding reasons. It lived inside stage 5, so an agent
+running any other stage never saw it; and on a harness where a turn ends, prose
+cannot carry a run across the boundary at all. Only a scheduled re-invocation
+can. So the decision moved to `pipeline.json` → `run.loop`, read at preflight in
+the same block as the model: recorded means armed and never re-asked, absent means
+**off**. `build.md`'s rule keeps its full force and gains one sentence naming its
+scope, because the two govern different things and a reader was going to take one
+for the other.
+
+**The context rule fires on evidence or not at all.** The opposite failure was
+live: runs announcing that context was nearly exhausted against a mostly-empty
+window, because an estimate from transcript length was being presented as a
+measurement. Nothing returns the remaining percentage, so the rule now admits
+exactly two signals — the harness saying so, or the operator saying so — and
+forbids the announcement without one. When it does fire: finish the item in
+flight, start no new one, make the ledgers true, continue. Not stop.
+
+There is deliberately **no config field** for the context half. The one number
+anyone would put in it is the one that can never be honoured, and the schema's own
+`description` says so — a blank space in a contract gets filled back in by the
+next contributor as an oversight.
+
+Both halves live in one new file, `references/continuity.md`, because they are one
+mechanism: the loop is what makes the context rule necessary. Without a loop a run
+stops at the turn boundary anyway; with one, it will start an item it cannot
+finish.
+
+### Fixed — three templates whose links were broken everywhere they are read
+
+`templates/adr.md`, `carryover.md` and `routing-rule.md` carried relative links
+that resolved from `templates/` — where the files are stored — and from nowhere
+they are ever actually seeded. `carryover.md` had shipped one since v1.1.0 and the
+link checker was green the whole time, because it resolves from the file's home.
+No run had seeded the template verbatim, so nobody hit it until one did.
+
+The rule is now the one the Cursor rule already follows: a document that travels
+is self-contained, and names files in code spans rather than linking to them.
+
+### Guards — 63 → 68
+
+`run.loop.mode` must be set explicitly in the shipped example; five surfaces must
+name `continuity.md`; the two load-bearing clauses in `continuity.md` must survive
+an edit (matched after whitespace normalisation, since both wrap at 80 columns and
+a line-oriented search would reject correct prose); and no seeded template may
+carry a relative link. Four invariants added to `CONTRIBUTING.md`, each citing the
+guard that enforces it.
+
+`CLAUDE.md`'s claim of *sixteen* invariants — the list held twenty-four — was
+deleted rather than corrected. A hand-written count drifts; that is what the rule
+about computing numbers is for, and this file was breaking it.
+
 ## v1.10.3 — 2026-08-03
 
 ### Fixed — the cause behind five audits, rather than a sixth symptom

package/CONTRIBUTING.md

@@ -117,6 +117,13 @@ 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 `)*
+
 **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
@@ -169,7 +176,34 @@ with the bundle instead of being hand-installed into an operator's config.
 reads those files, and a partial read shows whichever sections come first.
 *(guard: `needs the same partial-read protection references get`)*
 
-**24. Every invariant above names the guard that enforces it, and that guard exists.**
+**24. Run-wide pacing is config, and the example demonstrates its default.** The
+`run` block in `pipeline.schema.json` carries the loop mode; the shipped example
+sets `run.loop.mode` explicitly rather than omitting it, because the example is
+what gets copied and an absent field reads as an oversight instead of a decision.
+*(guard: `no explicit run.loop.mode`)*
+
+**25. The run-wide mode is named by every stage that could be misled by it.**
+`SKILL.md`, `references/grill.md`, `references/build.md`, `references/stages.md`
+and `templates/brief.md` each name `continuity.md`. The continuous-execution rule
+sat inside `build.md` for nine releases and did not work, because an agent running
+one stage never re-reads the orchestrator to discover a run-wide rule exists.
+*(guard: `a run-wide rule no stage has heard of`)*
+
+**26. `references/continuity.md` keeps its two load-bearing clauses.** One forbids
+announcing that context is nearly spent without a harness signal; the other names
+the harness limit on the loop primitive. Both are one edit away from softening into
+nothing. The guard normalises whitespace first — the clauses wrap at 80 columns,
+and a line-oriented search would reject correctly formatted prose.
+*(guard: `missing the contractual clause`)*
+
+**27. A seeded template carries no relative markdown links.** A template is copied
+somewhere else by definition, so a link that resolves from `templates/` is broken
+everywhere the file is actually read. `carryover.md` shipped one for nine minor
+releases and the link checker stayed green throughout, because it resolves from the
+file's home. Name the file in a code span instead — the same rule the Cursor rule
+follows, for the same reason. *(guard: `resolves only from`)*
+
+**28. Every invariant above names the guard that enforces it, and that guard exists.**
 This list claims to be *what the validator enforces*; it was eight guards behind when
 an audit measured it. A claim of enforcement is now checked like any other claim.
 *(guard: `whose message does not appear in`)* — and a cited literal must lie inside

package/README.md

@@ -127,6 +127,7 @@ until it is installed.
 | 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 |
+| 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 |
 | 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 |
@@ -775,7 +776,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.10.3 |
+| **Version** | 1.12.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` — 63 guards, each with a negative self-test that plants a
+3. Run `npm run test:all` — 76 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.** 63 structural guards prove
+- **Behavioural evidence is missing, not merely thin.** 76 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

@@ -24,6 +24,47 @@ you recommend and what they're on, let them confirm or override (per-stage
 overrides welcome), record the answer — then **stop asking at every stage**. If the
 recommended tier isn't available, say which one you're using and continue.
 
+## Pacing — the run mode, and the context budget
+
+Two rules about how a run keeps going. Settle the first at stage 0, in the same
+block as the model; the second is unconditional and needs no setting.
+
+**The run mode.** On, the run advances one item per iteration and does not ask
+between items — the plan's tasks, the boundary between stages whose gate is
+automatic, the per-module loop, the acceptance tail. It stops for exactly four
+things: a manual gate, a block it can't resolve, a genuine ambiguity, completion.
+
+- **Off unless recorded.** Read the project's pipeline config → `run.loop`. A
+  recorded mode is the answer and is never re-asked; absent, the mode is **off**.
+  Silence arms nothing, the same floor deploy authorization uses.
+- **It buys pacing, never authorization.** It never collapses a manual gate, and
+  never a deploy, publish, PR or shared-design-file write. A generic flag is not a
+  specific authorization.
+- **Prose does not survive a turn boundary.** Where the harness offers a loop
+  primitive, arm it and say the interval, the job id and how to cancel; where it
+  does not, the mode degrades to discipline plus the build ledger — and you say
+  which of the two you are actually running rather than implying the stronger one.
+- **Pick an interval longer than a typical item**, and one that divides its unit
+  cleanly. If the job auto-expires, say when: a loop that quietly stops is worse
+  than one never armed.
+- **Parked at a manual gate, cancel the loop** and print the re-arm command beside
+  the gate. A loop firing into a gate every few minutes is a nag, and a nagged
+  operator stops reading.
+
+**The context budget.** Near the end of the window: finish the item in flight,
+**start no new one**, make the ledgers true, then continue. Compaction is a normal
+event, not the end of the run — what loses work is crossing it mid-item.
+
+- **It fires on evidence only:** a harness signal (a compaction warning, a
+  pre-compaction hook) or the user saying so. Nothing returns the remaining
+  percentage, so an estimate from transcript length is a guess — and announcing
+  that context is nearly spent without a signal is presenting a guess as a
+  measurement. A run that keeps volunteering it against a mostly-empty window
+  trains the user to disregard the one time it is true.
+- **Flushing updates what already exists** — the build ledger, the carry-over
+  ledger, requirement statuses, the task list. Not a summary written for the
+  compactor: that is a fourth copy of the truth that nobody maintains.
+
 ## Stage 0 — intake grill (MANDATORY, do this FIRST)
 
 Never skipped, and nothing to install — the grill is part of this rule. No "the
@@ -166,7 +207,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 63 structural guards that check the
+Everything else in this repository is proven by 76 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.10.3",
+  "version": "1.12.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.10.3",
+  "version": "1.12.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -65,6 +65,7 @@ gate stops until it is installed.
 | **first run · the entry audit** (offered once) | [`references/setup.md`](references/setup.md) |
 | **what travels with the bundle vs stays in a project** | [`references/portability.md`](references/portability.md) |
 | any repeating loop | [`references/loop-guard.md`](references/loop-guard.md) |
+| run-wide · how a run keeps going (the loop mode + the context budget) | [`references/continuity.md`](references/continuity.md) |
 
 **Optional bridge.** If the operator already runs an equivalent skill set (e.g.
 `superpowers:brainstorming` / `writing-plans` / `subagent-driven-development` /
@@ -181,7 +182,12 @@ Three things the grill does beyond clarifying the request:
    tasks, context7, wiki-update, graphify) and emits ONE block covering them
    **and the model decision** (`references/model-tiering.md`): recommend
    the most capable model available, let the operator confirm or override, record
-   it. Ask once, here.
+   it. Ask once, here. **The same block carries the run mode**
+   (`references/continuity.md`): read `pipeline.json` → `run.loop`; where it is
+   recorded, arm it and print the job id and the cancel command — the config is
+   the authorization, so re-asking rebuilds the habit it exists to retire. Where
+   it is **absent, the mode is off**; recommend it in one line and move on.
+   Silence arms nothing, and the mode never collapses a `manual` gate.
 2. **Run stage 0 — always, no exceptions.** It opens with the **knowledge harvest**
    (`references/knowledge-sources.md`): query the project's own sources — repo docs,
    ADRs, `docs/ux/`, past briefs, the wiki if installed, any doc repo the project
@@ -341,6 +347,10 @@ automation is on — `pipeline.schema.json` is the only contract.
   inside the bundle, and the boundary against a project's own answers
 - `references/adoption.md` — the first run in a project: greenfield seeding, and the
   brownfield walkthrough whose third step baselines the ratchets at today
+- `references/continuity.md` — run-wide pacing: the loop mode (`run.loop`, default
+  off, and it never collapses a manual gate), how it is armed on Claude Code and
+  what that costs, and the context budget — which fires on a harness signal, never
+  on an estimate
 - `references/conventions.md` — how stages 6–10 read the host project's CLAUDE.md
 - `references/companion-skills.md` — companion skills, install lines, preflight recommendation
 - `references/artifacts.md` — the canonical document/artifact layout per stage

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

@@ -170,6 +170,10 @@
       }
     }
   ],
+  "_run_note": "Run-wide pacing. Shipped explicitly OFF so this example DEMONSTRATES the default rather than relying on its absence — see references/continuity.md. Set mode to 'interval' and a project stops being asked whether to run item-by-item; it still stops at every manual gate. There is no context-budget field here on purpose: the threshold is not measurable, so it is unconditional doctrine, not config.",
+  "run": {
+    "loop": { "mode": "off", "interval": "5m", "command": "/loop" }
+  },
   "release": {
     "enabled": true,
     "trigger": "tag",

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

@@ -14,9 +14,38 @@
       "description": "The pipeline stages, in order. Any number, any names — your project's real stages.",
       "items": { "$ref": "#/definitions/stage" }
     },
-    "release": { "$ref": "#/definitions/release" }
+    "release": { "$ref": "#/definitions/release" },
+    "run": { "$ref": "#/definitions/run" }
   },
   "definitions": {
+    "run": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional run-wide pacing. Omit the object and every field defaults OFF: silence arms nothing and authorises nothing — the same floor deploy authorization uses. There is deliberately NO context-budget field: the remaining context is not measurable from inside a run, so a field accepting a percentage would validate a number that can never be honoured. That rule is unconditional doctrine in references/continuity.md instead.",
+      "properties": {
+        "loop": {
+          "type": "object",
+          "required": ["mode"],
+          "additionalProperties": true,
+          "description": "Whether the run advances item by item without a discretionary check-in. It NEVER collapses a manual gate or an outward action — a generic flag is not a specific authorization.",
+          "properties": {
+            "mode": {
+              "enum": ["off", "interval"],
+              "description": "off (the default when absent) = the run pauses between items as it always did. interval = the run is armed with the harness's own loop primitive and advances one item per fire, stopping only at a manual gate, an unresolvable block, a genuine ambiguity, or completion."
+            },
+            "interval": {
+              "type": "string",
+              "pattern": "^[0-9]+[smhd]$",
+              "description": "Required when mode is 'interval'. Must divide its unit cleanly (5m, 10m, 2h — not 7m or 90m); a value that does not is rounded to the nearest that does, and the rounding is stated out loud. Pick the shortest interval that is longer than a typical item."
+            },
+            "command": {
+              "type": "string",
+              "description": "How this harness arms it, e.g. '/loop'. Harness-specific and therefore project-recorded rather than assumed: on a harness with no loop primitive, omit it — the mode then degrades to prose discipline plus the build ledger, and the run says so instead of implying it is armed."
+            }
+          }
+        }
+      }
+    },
     "release": {
       "type": "object",
       "additionalProperties": true,

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

@@ -18,6 +18,15 @@ session's history, so it stays focused; your context stays free for coordination
 plan to be executed — execute it. Stop only for BLOCKED you can't resolve, a
 genuine ambiguity, or completion. "Should I continue?" between tasks is noise.
 
+**Scope, so this is not mistaken for the run-wide mode:** the rule above governs
+the *inside* of this stage and is unconditional — it holds whether or not a loop
+is armed. What it cannot do is reach the other nine stages, or survive the
+boundary between one agent turn and the next; on a harness where prose does not
+carry across that boundary, only a scheduled re-invocation does.
+[`continuity.md`](continuity.md) owns that half, is recorded in `pipeline.json` →
+`run.loop`, and is **off unless recorded**. The two never disagree: one is a
+stage's internal discipline, the other is the run's pacing.
+
 **Narration:** at most one short line between tool calls. The ledger and the tool
 results are the record.
 
@@ -238,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/continuity.md

@@ -0,0 +1,214 @@
+# Continuity — how a run keeps going
+
+Two rules about pacing, in one file because they are two halves of one mechanism.
+The loop is what lets a run walk a task list without asking permission between
+items. The context budget is what stops that loop from starting an item it cannot
+finish. **Neither is useful without the other**, and a run that has the first
+without the second fails in a specific, expensive way: it begins task nine with
+almost no window left, loses the middle of it, and re-derives what it already did.
+
+## Contents
+
+- The limit, before the capability
+- Part 1 — the loop
+- Arming it on Claude Code
+- Other harnesses, and honest degradation
+- What one iteration means
+- Parked at a manual gate
+- Part 2 — the context budget
+- The evidence rule
+- What happens at the signal
+- The flush is not a new document
+- Rationalizations
+
+## The limit, before the capability
+
+**The loop mode collapses discretionary check-ins. It collapses nothing else.**
+
+- A `manual` gate still waits for an explicit operator go. Always.
+- An outward or irreversible act — deploy, publish, opening a PR, creating or
+  editing a shared design file — still needs its own authorization. A recorded
+  loop mode is a **generic** flag, and a generic flag is not a specific
+  authorization; that floor is set in [`grill.md`](grill.md) and this file does
+  not lower it.
+- **Default off.** Absent config and absent instruction, the mode is off. Silence
+  arms nothing, exactly as silence authorizes no deploy.
+
+The mode's whole content is the removal of *"should I continue?"* between items
+the operator already asked for. Anything beyond that is a different decision,
+taken separately.
+
+## Part 1 — the loop
+
+**On, the run advances one item per iteration and does not ask between items.**
+This spans the whole run, not one stage:
+
+- the plan's tasks at stage 5;
+- the boundary between stages whose gate is `auto`;
+- the per-module program loop when the brief was a platform;
+- the acceptance → retro tail, which is where runs most often stall one step from
+  finished.
+
+It stops for exactly four things: a `manual` gate, a block it cannot resolve, a
+genuine ambiguity the brief does not answer, and completion.
+
+**This extends [`build.md`](build.md); it does not replace it.** That file's
+*Continuous execution* rule governs the inside of a stage-5 execution — do not
+check in between the tasks of a plan you were told to execute. It is unconditional
+and stays that way. What it cannot do is reach the other nine stages, or survive
+the boundary between one agent turn and the next. This file is that reach.
+
+**Where it is recorded:** `pipeline.json` → `run.loop`. A project sets it once and
+is never asked again — which is the entire point. A mode that has to be requested
+every run is not a mode, it is a habit the operator maintains by hand.
+
+## Arming it on Claude Code
+
+```
+/loop <interval> <the invocation that continues the run>
+```
+
+The interval **must divide its unit cleanly** — `5m`, `10m`, `2h` are fine; `7m`
+gives uneven gaps and `90m` cannot be expressed at all. A value that does not
+divide cleanly is rounded to the nearest one that does, **and the rounding is said
+out loud** before it is used.
+
+Pick **the shortest interval that is longer than a typical item.** Shorter buys
+nothing: the scheduler cannot deliver faster than the item finishes.
+
+Two properties of the armed job must be stated when arming it, because both are
+silent failures otherwise:
+
+- **The job is session-only.** It is not written to disk and it dies with the
+  session.
+- **It auto-expires after seven days**, firing one last time. A loop that quietly
+  stops on day eight is worse than one that was never armed, because the operator
+  believes work is still moving.
+
+Where `run.loop.mode` is `interval`, the **preflight arms it** and prints the job
+id and the cancel command. Arming is not a new decision at that point — the config
+is the recorded authorization, and re-asking would rebuild the habit the config
+exists to retire.
+
+## Other harnesses, and honest degradation
+
+`/loop` is **Claude Code only**, in the same way the `PreToolUse` contract in
+[`hooks.md`](hooks.md) is. This file names the limit rather than pretending the
+mechanism is universal.
+
+On a harness with no loop primitive, the mode degrades to what prose can do: the
+discipline in [`build.md`](build.md) plus the build ledger, which is genuinely
+useful and genuinely weaker. **Say which one you are running.** A run that reports
+itself as looping while nothing is scheduled is claiming a capability it does not
+have, and the operator finds out by discovering that nothing happened.
+
+## What one iteration means
+
+One item, taken to its gate.
+
+**A fixed interval cannot interrupt an unfinished item.** The scheduler enqueues
+only while the harness is idle — never mid-query. This is the reason the interval
+form is safe, and it is worth stating precisely, because the plausible-sounding
+alternative explanation is wrong.
+
+**The build ledger is the second line, not the first.** It covers a different
+case: a fire that lands after a context loss, where the controller no longer
+remembers what it finished. There, `Task <N>: complete` in
+`.task-pipeline/build/<plan>/progress.md` is the only DONE marker that counts, and
+a task carrying one is never re-dispatched ([`build.md`](build.md)).
+
+Do not write, and do not believe, that the ledger is what makes the interval safe.
+Someone will eventually remove the ledger on the strength of that sentence, and
+the protection they think they are keeping is in the scheduler.
+
+## Parked at a manual gate
+
+A fixed interval firing into a `manual` gate is a nag. Five minutes later it fires
+again, and again, and the operator — who is reading the thing the gate asked them
+to read — learns to ignore the loop. That is the same failure as a rule nobody
+reads to the end: everyone believes it is covered.
+
+**So the run cancels its own loop job when it parks**, and prints the re-arm
+command beside the gate. The go and the re-arm are then one act. This is also the
+honest accounting: while the run waits for a person, nothing is looping, and the
+job list should agree with that.
+
+**Verify the cancel by listing the jobs, never by the cancel's own reply.** A
+teardown call will happily accept an id that was never scheduled and report
+success, which leaves the real job running while the transcript says it stopped.
+List afterwards and read the list. This is the same law the rest of this pipeline
+applies to every gate — a green nobody watched is not evidence — and a loop is
+exactly where breaking it goes unnoticed, because the symptom is a message
+arriving on time.
+
+## Part 2 — the context budget
+
+Near the end of the context window, the run does **not** stop and it does not
+start anything new:
+
+1. **Finish the item in flight.** A half-finished item is the expensive state.
+2. **Start no new item.** An item begun in this window loses its own middle.
+3. **Make the ledgers true** (below).
+4. **Continue.** Compaction is a normal event, not the end of the run.
+
+The failure this prevents is not running out of room — that is survivable. It is
+crossing the boundary *in the middle of something*, so the work either vanishes or
+gets done twice.
+
+## The evidence rule
+
+**The rule fires only on evidence**, and there are exactly two admissible kinds:
+
+- **A signal from the harness** — a warning that compaction is near, a `PreCompact`
+  hook firing, an explicit low-context notice.
+- **The operator saying so.**
+
+Absent both, the threshold has not been observed, and you **never announce that
+the context is nearly spent without one of those signals**. No tool returns the
+remaining percentage. An estimate from transcript length or how much has been read
+is a guess, and presenting a guess as a measurement is precisely the failure
+[`learned.md`](learned.md) names — compute, never restate.
+
+This cuts both ways, and the second direction is the one that actually goes wrong:
+a run that keeps volunteering *"context is nearly exhausted, start a new session"*
+against a mostly-empty window trains the operator to disregard the one time it is
+true.
+
+## What happens at the signal
+
+The four acts above, in order, and one prohibition: **do not begin an item you
+cannot finish inside what is left.** When the next item is plainly too large,
+say so and take the smaller thing that fits — closing a ledger, writing a decision
+that is already settled, updating a REQ status.
+
+If the project has recorded that it must not cross a compaction mid-stage, stop at
+the stage boundary instead and hand off. That is a project answer, not a default:
+the default is to continue.
+
+## The flush is not a new document
+
+Flushing means **making the artifacts that already exist true**:
+
+- the build ledger — every completed task carrying its `complete` line;
+- the carry-over ledger — everything deferred, dropped or half-done;
+- the brief's REQ statuses;
+- the task list.
+
+It does **not** mean writing a summary for the compactor. A summary is a fourth
+copy of the truth, it is written once, nobody updates it, and the next run reads
+it as current. The artifacts above are read by later stages anyway; making them
+right costs nothing extra and pays twice.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "The operator obviously wants it to keep going, I'll just loop" | Default off. Silence arms nothing — the same floor deploy authorization uses. Ask once at preflight, or read `run.loop`. |
+| "The mode is on, so I can push the deploy through" | The mode collapses check-ins, never gates or outward acts. A generic flag is not a specific authorization. |
+| "I'll tell it to keep going and it will" | On Claude Code, prose does not survive the turn boundary. Either a job is scheduled or the run stops; say which. |
+| "A one-minute interval is closest to no pause" | The interval must be longer than a typical item, or every fire lands on work already in progress and buys nothing. |
+| "The ledger protects me from mid-task fires" | The scheduler not firing mid-query protects you. The ledger covers context loss. Confusing them is how the real protection gets deleted. |
+| "It's still looping while we wait for approval" | A loop firing into a manual gate is a nag, and a nagged operator stops reading. Cancel on parking, re-arm with the go. |
+| "Context feels tight, I should warn them" | Feels is not evidence. Without a harness signal or the operator's word, the warning is a guess wearing the clothes of a measurement. |
+| "I'll write a handoff summary before compaction" | Update the ledgers instead. A summary is a copy of the truth that nobody maintains. |
+| "One more task will fit" | If it does not fit, its middle is what you lose — and half a task is the most expensive state there is. |

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

@@ -140,6 +140,7 @@ explicit "stop and ask me here":
 | Stage | What to settle up front |
 |---|---|
 | run-wide | the model decision ([`model-tiering.md`](model-tiering.md)); what to decide autonomously vs escalate |
+| run-wide Pacing | the **run mode** ([`continuity.md`](continuity.md)): does the run advance item-by-item with no check-in between items, and on what interval? Read `pipeline.json` → `run.loop` first — a recorded mode is the answer and is not re-asked. **Absent, it is off**: recommend it, take the answer, record it. It never collapses a `manual` gate or an outward act, so this row buys pacing, not authorization |
 | 0 Harvest | doc sources beyond this repo — other repos, hosted doc systems, the knowledge wiki, **the code graph** ([`knowledge-graph.md`](knowledge-graph.md): built / installed-not-built / absent) — and whether stage 9 may write to them (another repo is outward: propose + PR, never a direct push) |
 | 0 Setup audit | doc map absent or stale: run the entry audit over the existing documentation before building on it ([`setup.md`](setup.md))? Asked once; a refusal is recorded and never re-asked |
 | run-wide Escalation | cost of being wrong: decide alone while it stays inside the repository and reversible; escalate price, legal posture, promise, money, reputation, irreversible outward acts. Project exceptions? |

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

@@ -51,10 +51,13 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | The entry audit and what it inspects | `references/setup.md` |
 | The ladder, seams, axis rotation, ratchets | `references/audit.md` |
 | Loop detection and its caps | `references/loop-guard.md` |
+| **The run mode** — item-by-item pacing, default off, what it never collapses | `references/continuity.md` |
+| **The context budget** — the evidence rule and what a flush actually updates | `references/continuity.md` |
 | The retro: prune, cap, commits, archive | `references/retrospective.md` |
 | 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 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/stages.md

@@ -131,6 +131,13 @@ never that the work was skipped quietly.
   calls) and the **autonomy sweep** that pre-resolves every stage-1→10 blocker.
   Deploy authorization has a hard floor there: a standing go counts only when it
   names the target and the preconditions.
+- **The run mode is settled here too** ([`continuity.md`](continuity.md)): does
+  the run advance item-by-item with no check-in between items, and on what
+  interval? Read `pipeline.json` → `run.loop` first — a recorded mode is the
+  answer and is not re-asked; **absent, it is off**. It buys pacing, never
+  authorization: no loop mode collapses a `manual` gate or an outward act. The
+  same file carries the other half of pacing — the context budget, which fires
+  only on a harness signal or the operator's word, never on an estimate.
 - **UI early-detect:** one branch of the grill is always "does this touch a
   user-facing surface (web/mobile/CLI/TUI)?". If yes → surface **super-ux**
   now (use it if installed; otherwise give the install line — see SKILL.md
@@ -289,7 +296,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
@@ -304,7 +313,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
@@ -374,7 +384,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/adr.md

@@ -21,7 +21,7 @@ decision was made and *why* — not filling out sections.
 ## When this directory IS the register
 
 An ADR set and `docs/DECISIONS.md` are **two shapes of one decision home**, and a
-project has exactly one ([`../references/documentation.md`](../references/documentation.md)).
+project has exactly one (the skill's own `references/documentation.md`).
 If `docs/adr/` already holds an `NNNN-*.md`, that is the register — record it in
 `docs/DOCMAP.md` and never seed a second home beside it.
 

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

@@ -117,6 +117,7 @@ is not neutral — it is a scheduled interruption.
 | run-wide | Model for this run | … (most capable available unless overridden; per-stage overrides here) |
 | run-wide Escalation | … | cost of being wrong: decide alone while it stays inside the repository and reversible; escalate price, legal posture, promise, money, reputation, irreversible outward acts. Project exceptions? |
 | run-wide | Decide autonomously vs escalate to me | … |
+| run-wide Pacing | Run mode: item-by-item with no check-in between items, and on what interval? (the skill's `references/continuity.md`; read `pipeline.json` → `run.loop` first) | … (**absent ⇒ off**; it never collapses a manual gate or an outward act) |
 | 0 Harvest | Doc sources beyond this repo — other repos, hosted docs, the knowledge wiki, the code graph; and may stage 9 write to them? | … (another repo is outward: propose + PR, never a direct push; graph built / not built) |
 | 0 Setup audit | … (yes / no — recorded either way) | doc map absent or stale: run the entry audit over the existing documentation before building on it (the skill's `references/setup.md`)? Asked once; a refusal is recorded and never re-asked |
 | 0 Docs regime | Where settled things live (register or ADR set — one home, never both); who may write it; lease mechanism present, or is this run `ungated`? Gate command + ratchet floors; may this run raise a floor? | … |

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

@@ -47,7 +47,7 @@ is the true statement.
 - **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
+  the host's lint or CI (the skill's own `references/audit.md` → *A class that
   repeats twice becomes a gate*). This ledger is for what cannot be automated, not
   for what nobody automated.
 

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
 

package/plugins/task-pipeline/skills/task-pipeline/templates/routing-rule.md

@@ -8,7 +8,7 @@ operator's configuration silently.
 raises the odds the model selects it and cannot make selection mandatory — the choice
 stays with the model, case by case. Only an instruction makes routing binding. That
 instruction therefore has to be *installed*, which is exactly how a workflow decision
-ends up living outside the bundle ([`../references/portability.md`](../references/portability.md)).
+ends up living outside the bundle (the skill's own `references/portability.md`).
 Shipping it as a template is what lets it travel.
 
 **Keep the exclusions identical** to the skill's `description` and to the