task-pipeline-skill 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # 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

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

package/README.md

@@ -776,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.11.0 |
+| **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` — 68 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.** 68 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

@@ -207,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 68 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.11.0",
+  "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.11.0",
+  "version": "1.12.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/portability.md

@@ -57,6 +57,7 @@ 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 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

@@ -296,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
@@ -311,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
@@ -381,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/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