task-pipeline-skill 1.45.0 → 1.46.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## v1.46.0 — what a run leaves running, what "done" costs to say, and what a check is for
+
+Three rules this pipeline had been following by disposition rather than by doctrine,
+and one it had not been following at all.
+
+**`evidence-docs` can now be reached in Russian.** It shipped without Russian triggers
+while `task-pipeline`, beside it in the same plugin, had carried them since v0.14.0 — a
+navigator nobody can summon is a navigator nobody reads. Its description now opens with
+`Use when …`, names twelve triggers on both sides, and keeps the `без доков` opt-out the
+body always documented. `task-pipeline`'s own description is deliberately unchanged: the
+house auditor requires every description to open with `Use when …`, this repository's
+validator requires the opposite — capability first, trigger second — and fails the build
+on anything else. Measured in both directions; which of the two rules is wrong is a
+decision, not a fix to slip into a release.
+
+**A run is not only a diff — it is also everything it left running.** A background
+shell, a monitor polling an API, a scheduled loop, a coordination lease, a worktree,
+a container, scratch files, a draft PR. `references/residue.md` names eight classes
+and requires each to be enumerated **by class, never by one tool** — because the
+measured case that produced this file was a task inventory reporting *"No tasks
+found"* while `ps` showed the monitor alive and polling every thirty seconds. An
+inventory that does not contain the thing that leaks is a green light with no lamp
+behind it.
+
+Every gate now prints `holds: N` beside its verdict, the run ledger gains a fifth
+declared line shape, and stage 10 gains criterion 13: give the environment back.
+The asymmetry is the point — **end what this run started, report what it did not**.
+The inventory is machine-wide and the authority is not, so a stale-looking lease
+belonging to another agent is named, never released.
+
+The field is `holds:` rather than `residue:` because `gates.md` already prints
+`unmarked residue: 0` for documentation items, and `residue: 0` is a substring of
+it. A check written for the new field would have been answered by the old line — the
+class this repository has now met nine times, caught here before it shipped.
+
+**"Done" is a claim, and it names what makes it true.** Every disclosure in this
+bundle asks *what does it print when it did not look?* — of checks. `progress.md`
+now asks it of the run's own sentences, which reach the operator where the check
+does not. Three shapes, each requiring no intent to mislead: the plan reported as
+the outcome, the reply reported as the result, the part reported as the whole. And
+the honest negative is a result: *"not done, the fixture needs a credential I do not
+have"* is a complete report where *"done, with a small caveat"* is not.
+
+**The result is the goal; the check is how you know.** Every other line in
+`gates.md` pushes one way — prove more, assume less — and read alone it produces a
+run that spends an afternoon proving a one-character change. Verification now scales
+to what breaking costs, using the `sev × blast` the board already computes, with
+four named signals that you have crossed over. This never licenses skipping a gate:
+the floor is not proportionate to anything, and cutting it to go faster is the
+failure the file exists to prevent, arriving on schedule.
+
+**Publishing was half a loop.** `retrospective.md` closes it: an issue resolves when
+the **behaviour** changed and its closing comment names the file, the line and the
+guard; an issue nobody worked stays open rather than being triaged into silence;
+nothing is deleted, because the number is what the CHANGELOG points at. The queue a
+run pulls from when it finishes early is that pile, then the board, then the open
+questions.
+
+Guards: 275 → **291**, each still proven against a planted defect — including a
+neighbour probe that caught a defect in one of this release's own guards on its
+first use: the criterion-13 check scoped *to the next heading* rather than *to the
+item*, so a needle parked in between answered for the rule.
+
+## v1.45.1
+
+### Fixed
+
+- **The v1.45.0 entry had no `Guards: N → **M**` line**, so the negative
+  self-test that plants a stale count had nothing to plant into and failed with
+  `PLANT DID NOT LAND`. The count is a claim about *now* and every release
+  section is required to restate it — a release that omits it silently disarms
+  the check that keeps the number honest.
+
+### Counts
+
+- Guards: 275 → **275**.
+
 ## v1.45.0
 
 ### Changed
@@ -17,6 +94,11 @@
   from the 2026-08-03 design, and refused two rewordings before accepting one
   in text nothing had locked.
 
+### Counts
+
+- Guards: 275 → **275** — this release adds none; it removes duplication from
+  the body and touches no check.
+
 ### Known gap
 
 - **The body is still 6088 tokens against a 5000 cap.** What remains is a

package/HOW-IT-WORKS.md

@@ -0,0 +1,346 @@
+# How task-pipeline works
+
+**The living high-level view.** This file is rewritten with every release. It
+explains the machine — what routes a request into it, what each stage refuses to
+let past, and what makes any claim it prints believable. The README sells it and
+tells you how to install it; this file tells you how it thinks.
+
+> **Version 1.45.0.** The "What changed" section at the bottom carries the last
+> few releases. Everything above it describes the pipeline as it is *now*, not as
+> it was designed.
+
+---
+
+## The one-sentence version
+
+A coding agent takes a substantial task, interrogates it into a complete brief,
+then walks it through **ten gated stages** and refuses to advance until each
+gate passes — closing by accounting for every requirement from a list rather than
+from memory.
+
+The reason it exists: agents write code well and judge *when to stop asking you
+things* badly. Left alone, a substantial task becomes twenty interruptions, or a
+confident build that skipped the tests and quietly delivered two thirds of what
+you asked for.
+
+---
+
+## 1. How a request finds the pipeline
+
+An agent choosing skills sees exactly one thing: the `description` field in
+`SKILL.md`. It is capped at **1024 characters** and currently uses **1008** — that
+headroom is the budget every future addition pays from, which is why it is
+tracked as a board row rather than left to be discovered.
+
+It is written in three parts, and the middle one was learned the hard way:
+
+- **Work that changes the repository** — a feature, fix, refactor, migration,
+  integration, rewrite, adoption or hardening, in English and Russian both.
+- **Work whose *output* lands in the repository** — `audit`, `bug hunt`,
+  `production check`, `PR review`. Before this clause existed, agents facing
+  "проверь, нет ли ошибок" **quoted this skill's own exclusion line as their
+  reason to refuse**. The measurement is in `evals/routing/RESULTS.md`.
+- **What it is not for** — answering a question, explaining code, a typo, a
+  one-line edit. The boundary runs in both directions on purpose: running ten
+  stages for one character is the fastest way to teach an agent to route around
+  the pipeline entirely.
+
+Two modes need no task at all. `checkup` reports what has shipped without anyone
+confirming it. `setup` audits the documentation a project already has.
+
+**Honest limit:** this measures the *description's* discriminating power, not the
+host's selection machinery. Three measured runs scored 7/10, 9/10 and 8/10 — and
+one sample per query cannot separate an effect from noise, which the measurement
+discovered about itself by being run twice.
+
+---
+
+## 2. Preflight — two things settled once
+
+**Model.** The most capable tier the environment offers, named as a *tier*, never
+as a vendor id. A hardcoded model id in shipped doctrine is a validator failure,
+because it rots the moment the vendor ships a new one.
+
+**Companions.** `super-ux`, `copywriting`, `sheleg-design`, `graphify`, the wiki.
+The detection block prints once. A missing companion states its fallback and
+**does not block** — the single exception being the stage-3 UX track on
+user-facing work, where shipping without it is a decision someone has to make out
+loud.
+
+---
+
+## 3. Stage 0 — where the run is won or lost
+
+This is the heaviest stage and that is deliberate. Everything downstream is an
+attempt to execute a brief; a bad brief cannot be rescued by good execution.
+
+### The harvest runs before the first question
+
+Pull what the project already knows about *this task*:
+
+| Source | What it uniquely answers |
+|---|---|
+| the code | what is there |
+| **the code graph** (`graphify-out/graph.json`) | **reach** — what calls this, what breaks if it moves. `grep` cannot answer this |
+| `CLAUDE.md`, ADRs, `docs/`, `docs/ux/` | what was decided and why |
+| **the retro, read in full** | the standing instructions that *bind this run* |
+| the knowledge wiki | what past runs distilled |
+| the board and the verification ledger | what is open, and what shipped unverified |
+
+The output is a **source ledger** — a row per source, or an explicit *none found*.
+An absent source that is never named looks identical to a source that was read.
+
+### Then the grill, and it is mandatory
+
+One question per turn, each with a recommended answer, exploring the codebase
+before asking, until every decision branch is resolved.
+
+- **Every answer is validated against the harvested sources.** The operator
+  outranks any document — but only *out loud*, and a document the run proves stale
+  is logged for stage 9 rather than silently ignored.
+- **The autonomy sweep** pre-resolves what would otherwise stop stages 1→10: test
+  and lint commands, branch and tracker policy, deploy target and authorization,
+  where the logs live. Every question asked here is an interruption that does not
+  happen later.
+- **UI work adds the design surface** — Figma connected or text-only, and *which
+  file*, named before the first frame. A destination decided at drawing time is
+  how a project ends up with three design files and no way to tell which is real.
+
+### The brief closes on the REQ table
+
+The request as an **addressable list**, where every row names how it will be
+verified. Frozen from here: adding is free, removing needs the operator. Anything
+deferred enters the carry-over ledger the moment it is said, not at the end when
+it has been forgotten.
+
+---
+
+## 4. Stages 1→10
+
+| | Stage | What must be true to leave it | Gate |
+|---|---|---|---|
+| 1 | Docs study | every contract the design will lock is grounded on **fetched** docs, not recall | auto |
+| 2 | Brainstorm + decompose | design approved, every REQ answered by it. A platform is cut into modules, **walking skeleton first**, every REQ in exactly one module | manual |
+| 3 | Spec | contracts locked. User-facing work runs three tracks — what it **does**, how it **sounds**, how it **looks**. A declined track is recorded, never silent | manual |
+| 4 | Plan | the REQ set-comparison holds: brief REQs == union of `Implements:` | auto |
+| 5 | Build | TDD per task, a review after each, findings fixed or parked **with a ruling** | auto |
+| 6 | Tests | the **full** suite green; a web surface checked in a browser, not in the diff | auto |
+| 7 | Lint + deploy | the authorization is specific, and the CI verdict is **read** before any tag | manual |
+| 8 | Post-deploy | the verification trio, not one of three; a verification row per shipped REQ | auto |
+| 9 | Docs + wiki | **three** artifacts — module docs, the wiki, and the code graph | auto |
+| 10 | Acceptance | the ladder walk first, then the table, then the retrospective | manual |
+
+### Why the manual gates are where they are
+
+`auto` means the agent verifies the check itself and proceeds. `manual` means it
+waits for an explicit go. The four manual gates sit at the four places where a
+wrong turn is expensive and hard to reverse: **what we are building** (2), **the
+contracts** (3), **the outside world** (7), and **whether it is done** (10).
+Everywhere else, stopping to ask costs more than it saves.
+
+---
+
+## 5. The three rules that fire at any stage
+
+**The loop guard.** If a pass starts undoing an earlier one — the same file edited
+twice for the same reason, a closed finding returning, a third entry into one
+stage — editing stops. Name both shapes, escalate to the layer that owns the
+conflict, re-plan as an ordered list, then go item by item. "Cleanup" and "polish"
+are explicitly *not* valid reasons for an edit; every change needs one traceable
+cause.
+
+**The audit's exit.** If a searching pass starts finding mostly what the previous
+pass's own fixes broke, the axis is exhausted. **Rotate the axis — do not look
+harder.**
+
+**Evidence.** A green from a check nobody has watched fail against a planted
+defect is not evidence. A finding class seen twice becomes a script, not a third
+ledger row.
+
+---
+
+## 6. The loop — walking a queue without asking permission
+
+Recorded in `pipeline.json` → `run.loop`:
+
+```
+loop:
+  mode:  off | interval | dynamic
+  queue: module-map | plan-tasks | none
+  arm:   preflight | after-decomposition
+```
+
+**A loop with no queue is a timer.** The queue belongs to stage 2 — the module map
+or the plan's task list. Nothing third is invented. The loop arms at the *close of
+stage 2*, when the mode is recorded and the queue holds more than one item.
+Between items the goal is re-read, so tasks can be re-prioritised or moved to the
+board as the run learns.
+
+The rule that keeps this safe: **arming is the execution of a recorded decision,
+not a fresh request. Where nothing is recorded, nothing arms.** Default off.
+Silence arms nothing.
+
+---
+
+## 7. The hand-back — what a run says when it stops
+
+Long iterations lose context. So at the end of every iteration, and at stage 10,
+the run reports in a fixed shape:
+
+```
+TASK               the request AS IT WAS GIVEN, quoted from the brief
+PROGRESS           where the run stands against that request
+DONE               what was solved, each with its evidence
+SURFACED           what came up that nobody asked for
+DECISIONS WAITING  <n>   each as a question with options, asked HERE
+AMBIGUITIES        <n>   computed from the registers, below
+```
+
+Three details carry the weight:
+
+- `TASK` is **quoted, not paraphrased** — the paraphrase is exactly what drifts.
+- `DECISIONS WAITING` are asked **here**, not deferred. A missing decision, a
+  missing document or an ambiguity left standing is what turns into a large
+  consequence three stages later.
+- `AMBIGUITIES` is **computed from four registers that already exist** — not a
+  fifth document nobody maintains.
+
+It is traced by a `hand:` line in `.task-pipeline/run.md`, beside `stage:`,
+`iter:`, `touch:` and `holds:`. That is what makes it a check rather than an intention.
+
+---
+
+## 8. Stage 10 — the close-out, in order
+
+1. **The ladder walk, first.** The REQ table finds what was named and lost; it
+   **cannot** find what was never named, because a comparison needs two sides and
+   an absence has one. So every REQ is walked bottom-up — decision → spec section
+   → contract *and its failure behaviour* → task → change → executed test →
+   surface and docs — checking the seam at each step. Findings are ordered **by
+   seam, not by file**. Every absence becomes a new REQ row *before* the table.
+2. **The coverage table** — one row per REQ, each with evidence. Four statuses
+   only: verified, partial, deferred, dropped. `unknown` fails the gate.
+3. **The ledgers close.** Every carry-over row still open leaves with a board id,
+   and priorities are re-derived. The counts print beside every gate verdict, so
+   *green* never reads as *verified*.
+4. **Several repositories? The parent closes too.** A submodule can be committed,
+   pushed and green while a clone of the parent still gets the commit before it,
+   and neither repo looks wrong alone.
+5. **The retrospective is the run's last act**, in this order: stamp the run →
+   prune every standing instruction against its retirement triggers (list held to
+   ten, every deletion logged) → write an entry **only if the run diverged**.
+
+---
+
+## 9. Why you should believe anything it prints
+
+This is the part most pipelines skip, and it is the reason this one is trustworthy
+rather than merely tidy.
+
+**Every guard is proven against a planted defect.** `npm run test:all` breaks the
+thing each of the **291** checks is about, and requires that check to reject it. A
+guard that has never been watched failing is not a guard; it is a comment.
+
+**The neighbour probe.** A check has a *subject* — the rule it is about — and
+*evidence* — the text it actually reads. When those differ, it goes green for
+reasons unrelated to the rule and no ordinary probe can tell. So: break the
+subject, plant the guard's **current** needle next door, and require it to still
+fail. Six guards in one session were defeated this way — none of them by their own
+probes, all of them by a reader.
+
+**Disclosures are not ratchets.** Alongside every verdict the suite prints what it
+*could not* look at — `unlooked: N`, listed by name; `abstained` where a check's
+precondition was absent. No floor, no direction, **never a target**. A number that
+becomes a target stops being a measurement.
+
+**Corpora are discovered, not listed.** Three hand-written lists each missed a
+shipped surface, and none of the misses was found by the guard holding the list. A
+new surface joins a check by *existing*.
+
+**The scaffold's own gate runs.** One guard executes `templates/docgate.sh` over a
+scratch project seeded from the templates and requires exit `0`. A scaffold whose
+gate rejects its own seeds teaches every new project that the gate is noise.
+
+---
+
+## 10. The improvement iteration
+
+The pipeline improves itself on a loop, and the loop is mechanical rather than
+aspirational:
+
+```
+a run diverges  →  retro entry  →  retro.publish  →  upstream issue
+                                                          ↓
+   board row  ←  measured against the tree  ←  triaged next cycle
+       ↓
+   doctrine change + a guard that proves it  →  release  →  the run reads it
+```
+
+- **`retro.publish`** turns a lesson that is bigger than one project into a GitHub
+  issue on the skill itself. Six such insights arrived in a single day.
+- **Issues are resolved, never deleted.** Ones we have worked through are closed
+  with a comment naming what they changed. Ones we have not accumulate visibly and
+  are picked up in the next cycle. The pile is the queue, and a deleted issue takes
+  its number — the one the CHANGELOG points at — with it.
+- **A finding closes when behaviour changes**, not when it is understood.
+- **A board row is measured against the tree, not read.** Rows have been found
+  already closed for two days, and rows whose text was true while the thing they
+  described had moved.
+
+---
+
+## What changed, by version
+
+### v1.45.0 — what a run leaves running, what "done" costs to say, what a check is for
+Four rules the pipeline had been following by disposition rather than by doctrine.
+**Residue**: eight classes of thing a run leaves running or leaves behind, enumerated
+by class and never by one tool — the case that produced it was a task inventory
+reporting *"No tasks found"* over a live, polling monitor. `holds: N` beside every
+gate verdict, a fifth run-ledger line shape, and stage-10 criterion 13: end what this
+run started, **report** what it did not. **Completion honesty**: *"done"* names what
+makes it true, and the honest negative is a result. **Proportionate verification**:
+the deliverable is the working result and the check is how you know — scaled to
+`sev × blast`, never by cutting the floor. **The improvement iteration**: a published
+issue resolves when behaviour changed and its close names the address; unworked ones
+accumulate visibly rather than being triaged into silence. Guards: 275 → 291.
+
+### v1.44.0 — six lessons from other projects, and the guards that hold them
+Six issues published by runs in other repositories were worked into doctrine:
+seam testing at stage 6, `verified by` names that must resolve, a probe's green
+being evidence only when the mutation is known to have landed, what a test case
+consumes and why a timeout is unclassified, `publish:` as a line in the verdict
+rather than a silence, and a ratchet's matcher being itself a check. Twelve new
+guards; the suite reached 275. An independent review found eight further defects
+in the implementation, all closed before merge.
+
+### v1.43.0 — the hand-back
+Long iterations lose the original request. Stage 10 and every iteration boundary
+now report TASK / PROGRESS / DONE / SURFACED with decisions and ambiguities
+counted, traced by a `hand:` line in the run ledger.
+
+### v1.42.0 — the neighbour probe
+Four consecutive releases had guards defeated by independent readers 15, 6, 6 and
+8 times, and the trend did not decline. The class: a check answered by text that
+is not its subject. The mechanism, with its honest limit stated as a number.
+
+### v1.40.0 — the loop got a queue
+`run.loop` previously said *how often* without ever naming *what* the loop walks.
+The queue is stage 2's, and the loop arms on it.
+
+### v1.39.0 — findings-shaped work got an entry
+Audits, bug hunts, production checks and PR reviews produce output that lands in
+the repository, but the routing surface pointed away from them — agents quoted the
+exclusion clause as their reason to refuse.
+
+---
+
+## Where to read further
+
+| You want | Read |
+|---|---|
+| install it, use it | [`README.md`](README.md) |
+| change it | [`CONTRIBUTING.md`](CONTRIBUTING.md) — the invariants live there |
+| why a release happened | [`CHANGELOG.md`](CHANGELOG.md) |
+| the stage doctrine itself | `plugins/task-pipeline/skills/task-pipeline/references/` |
+| what is open | [`docs/superpowers/backlog.md`](docs/superpowers/backlog.md) |
+| what is genuinely unresolved | [`docs/OPEN_QUESTIONS.md`](docs/OPEN_QUESTIONS.md) |

package/README.md

@@ -20,6 +20,12 @@ Built for **Claude Code**, and installable into any agent that reads skills
 no companion plugin, nothing to resolve, nothing that breaks when a dependency is
 missing.
 
+> **Want the machine rather than the pitch?**
+> [**`HOW-IT-WORKS.md`**](HOW-IT-WORKS.md) is the living high-level view
+> — what routes a request in, what each gate refuses to let past, why the manual
+> gates sit where they do, and what makes any claim this pipeline prints
+> believable. Rewritten every release.
+
 ---
 
 ## The flow
@@ -128,6 +134,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 |
+| every gate + stage 10 | [`residue.md`](plugins/task-pipeline/skills/task-pipeline/references/residue.md) — what the run leaves **running** and leaves **behind**: eight classes enumerated by class rather than by one tool, `holds: N` beside every verdict, and a teardown that ends what this run started and only reports what it did not |
 | run-wide reporting | [`progress.md`](plugins/task-pipeline/skills/task-pipeline/references/progress.md) — the header block at task start and the one-line iteration close: the stage rail computed from the project's own `pipeline.json`, every number borrowed from the gate that measured it |
 | 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) |
 | the board between runs | [`backlog.md`](plugins/task-pipeline/skills/task-pipeline/references/backlog.md) — the work-list that outlives a run: seeded at stage 0 or picked up, priority **computed** from three stated inputs rather than assigned, and the seam where the carry-over ledger's `backlog` pointer finally resolves |

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.45.0 |
+| **Version** | 1.46.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, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.45.0",
+  "version": "1.46.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"
@@ -17,6 +17,7 @@
     "cursor",
     "evals",
     "README.md",
+    "HOW-IT-WORKS.md",
     "SKILL-CARD.md",
     "LICENSE",
     "CHANGELOG.md",

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 closes with evidence, a work board and a verification ledger that outlive a run, an exposure line naming what shipped unconfirmed, a progress rail computed from the project's own config, a loop guard whose review ceiling measures rather than stops, and stage-3 tracks for what a product does, how it sounds and how it looks. Two modes need no task: `checkup` (what is unverified) and `setup` (audit existing docs). Retro insights can publish upstream as issues, opt-in and redacted.",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -1,6 +1,6 @@
 ---
 name: evidence-docs
-description: Applies the ten canons of evidence-backed documentation — what makes a claim documentation rather than an assertion — and routes to the doctrine that enforces each one. Use when writing or reviewing anything that will be read as true — a decision record, a README, an acceptance report, a runbook, a changelog entry, an audit finding, or any claim that something was verified. Also use when a project needs a documentation gate, a decision register, a propagation matrix, or a retrospective that outlives its author. Not for drafts, chat answers, commit messages or code comments.
+description: "Use when writing or reviewing anything that will be read as true — a decision record, a README, an acceptance report, a runbook, a changelog entry, an audit finding, or any claim that something was verified. Applies the ten canons of evidence-backed documentation — what makes a claim documentation rather than an assertion — and routes to the doctrine that enforces each one. Also use when a project needs a documentation gate, a decision register, a propagation matrix, or a retrospective that outlives its author. Triggers - 'documentation gate', 'decision record', 'ADR', 'acceptance report', 'runbook', 'is this verified', 'доказательная документация', 'записать решение', 'отчёт о приёмке', 'раннбук', 'чем это подтверждено', 'доки в синхроне'. Not for: drafts, chat answers, commit messages or code comments — say 'без доков' to opt out."
 ---
 
 # Evidence-backed documentation

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

@@ -67,6 +67,7 @@ gate stops until it is installed.
 | **first run · the entry audit** (offered once) | `references/setup.md` |
 | **what travels with the bundle vs stays in a project** | `references/portability.md` |
 | any repeating loop | `references/loop-guard.md` |
+| run-wide · what the run **leaves running and leaves behind** — every gate, and stage 10 | `references/residue.md` |
 | run-wide · what the run **prints about itself** — the rail, the iteration line | `references/progress.md` |
 | run-wide · how a run keeps going (the loop mode + the context budget) | `references/continuity.md` |
 | run-wide · the work-list **between** runs, and how its priority is computed | `references/backlog.md` |
@@ -248,7 +249,12 @@ Three things the grill does beyond clarifying the request:
    owns the conflict, re-plan the check as an ordered list, then go through it one
    item at a time; **when a pass is *searching* rather than editing and starts
    finding mostly what the previous pass's own fixes broke, the axis is exhausted —
-   rotate it, don't look harder** (`references/audit.md`), and remember that a
+   rotate it, don't look harder** (`references/audit.md`); **every gate
+   prints `holds: N` — what this run left running** across the eight classes
+   (background shells, monitors, scheduled loops, coordination leases, worktrees,
+   containers, scratch files, remote state), enumerated **by class and never by a
+   single tool**, and stage 10 does not close while this run's residue is live and
+   unaccounted (`references/residue.md`); and remember that a
    green from a check nobody has watched fail is not evidence; task
    tracker + conventional commits per host conventions; worktree isolation for the
    build, integrated back per the brief's branch policy before stage 7; honest
@@ -277,7 +283,7 @@ capable available — see `references/model-tiering.md`).
 | 7 | Lint + deploy | lint clean + suite green before deploy; deploy needs a go (or the brief's specific standing authorization) | manual |
 | 8 | Post-deploy | clean boot or honest degradation report; **a deployed web target is opened, not curled** — a `200` proves the server answered and says nothing about a 404'd bundle or a console full of errors on load (`chrome-devtools`; absent → call it an HTTP response, which is its honest name) | auto |
 | 9 | Docs + wiki | every stale row of the stage-0 source ledger updated; **the propagation matrix walked for every change type this run produced** — the ledger names what you read, the matrix names what you owe — every settled thing recorded with an id, every answered question resolved, and **the documentation gate green with its ratchet counts printed**; docs synced; wiki synced; **the code graph refreshed where one exists** and checked against the docs (a hub no doc names, a doc naming a node the graph lost); **every number computed rather than restated, every named command or file resolvable** ([`references/learned.md`](references/learned.md)); the carry-over count printed beside the verdict | auto |
-| 10 | **Acceptance** | ladder walk ran, its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; ledger has no unresolved row; **axis rotation recorded** (new findings vs self-inflicted, rule 1 of [`references/learned.md`](references/learned.md)), **every closure verified against the artefact rather than the document describing it**, **each correction swept across its class**, **every deferral a printed ratchet rather than a TODO**; **in a multi-repository project, every repository is clean, pushed and pointed at** (below); **the hand-back is written** — the request quoted as given, progress against it, what was solved, what surfaced unasked, waiting decisions asked here, and the ambiguity count computed ([`references/progress.md`](references/progress.md)); operator signs off; **every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, and its ratchet counts are printed beside the verdict**; **the retrospective written last, and in order — the run stamped with its commit FIRST (the cold-retirement trigger reads that stamp), then the prune with the list at or under its cap and every deletion logged, then the entry; every deletion and every entry carrying its commit, entries older than five stamps rotated into the archive, counts printed** ; **both disclosures printed beside the verdict** — `abstained` (what the run declined to claim) and `unlooked` (what a check never looked at), neither a ratchet, neither with a floor, neither ever a target ([`references/gates.md`](references/gates.md) → *Disclosures*) | manual |
+| 10 | **Acceptance** | ladder walk ran, its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; ledger has no unresolved row; **axis rotation recorded** (new findings vs self-inflicted, rule 1 of [`references/learned.md`](references/learned.md)), **every closure verified against the artefact rather than the document describing it**, **each correction swept across its class**, **every deferral a printed ratchet rather than a TODO**; **in a multi-repository project, every repository is clean, pushed and pointed at** (below); **the hand-back is written** — the request quoted as given, progress against it, what was solved, what surfaced unasked, waiting decisions asked here, and the ambiguity count computed ([`references/progress.md`](references/progress.md)); **the environment is given back** — all eight classes enumerated, what this run started ended and verified by re-enumerating rather than by the teardown's reply, an earlier run of this project ended only when **provably spent**, anything this project does not own reported rather than ended, written as a `holds:` line (`references/residue.md`); operator signs off; **every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, and its ratchet counts are printed beside the verdict**; **the retrospective written last, and in order — the run stamped with its commit FIRST (the cold-retirement trigger reads that stamp), then the prune with the list at or under its cap and every deletion logged, then the entry; every deletion and every entry carrying its commit, entries older than five stamps rotated into the archive, counts printed** ; **every disclosure printed beside the verdict** — `abstained` (what the run declined to claim) and `unlooked` (what a check never looked at), neither a ratchet, neither with a floor, neither ever a target ([`references/gates.md`](references/gates.md) → *Disclosures*) | manual |
 
 
 ### Stage 10 in a project of several repositories

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

@@ -201,6 +201,7 @@ ledger's, so a list that quietly grew back is visible at the moment it happened:
 GATE 10 acceptance: PASS — 14/14 REQ verified
   carry-over: 0 unresolved · retro: 7 standing (was 9) · retired 3 · added 1
   abstained: 2 (1 partial · 1 cannot-verify) · unlooked: 3 dormant
+  holds: 10 — none — enumerated 8/8 classes
 ```
 
 ## A `verified by` name is a claim until it resolves
@@ -280,7 +281,7 @@ All of:
    ledger or here) and, for `deferred`, a tracker entry.
 8. **No carry-over row is left `unresolved`** — every one has a home, and the
    ledger's counts are printed with this verdict, not just filed.
-7a. **Both disclosures are printed** ([`gates.md`](gates.md) → *Disclosures*):
+7a. **Every disclosure is printed** ([`gates.md`](gates.md) → *Disclosures*):
    `abstained` — every REQ closing `partial`, every `unknown`, every ⚠️ *cannot verify
    from diff* the controller could not resolve — and `unlooked`, every check that
    reported `dormant` or `skip`. They are **not** ratchets: no floor, no direction, and
@@ -310,6 +311,15 @@ table substitute for that answer.
    its four registers with their ids. A run that cannot say what happened has not
    finished; it has stopped. This file is the one stage 10 opens, and it carried every
    other criterion while omitting this one for a release.
+13. **The run has given the environment back** ([`residue.md`](residue.md)) — all
+   eight classes enumerated **by class, never by one tool**, everything this run
+   started ended in dependency order, each teardown verified by **re-enumerating
+   rather than by the teardown's own reply**, and the result written as a `holds:`
+   line. `holds:` reaching zero is required here and **only** here. An item left
+   standing on purpose passes with its owner and reason named; an item **this project
+   does not own** is **reported, never ended** — the inventory is machine-wide and
+   the authority is not. An earlier run of *this* project is a third case, ended only
+   when provably spent ([`residue.md`](residue.md) → *Three owners*).
 
 
 ## When the answer is "something's missing"

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

@@ -35,6 +35,7 @@ elsewhere and is not restated here:
 - A green probe is evidence only if the mutation is known to have landed
 - The false-positive budget
 - Ratchets
+- The result is the goal; the check is how you know
 - Disclosures — counted like a ratchet, and deliberately not monotone
 - Where a gate runs
 - Adding a check to an existing gate
@@ -451,6 +452,49 @@ GATE 9 docs: PASS — propagation backlog: 121 (was 162) · unmarked residue: 0
 
 A ratchet nobody prints is a TODO with a better name.
 
+## The result is the goal; the check is how you know
+
+Everything else in this file pushes one way: prove more, assume less. Read alone it
+has an obvious failure mode — a run that spends its afternoon proving a
+one-character change and never ships the thing it was asked for. **The deliverable
+is the working result, as described in the brief. A check is how the run knows it
+has one. A check that is not buying that knowledge is not diligence; it is the run
+optimising the wrong thing.**
+
+**Scale the check to what breaking costs, and the project already computes that.**
+The board ranks by `sev × blast` ([`backlog.md`](backlog.md)). The same two inputs
+size the verification:
+
+| What breaking costs | What the check has to be |
+|---|---|
+| an outward, irreversible or shared-state effect — deploy, publish, a lease, another agent's file | proven: watched failing against a planted defect, and re-read rather than trusted from the reply |
+| a contract other code depends on | an executed test, named in the REQ row |
+| behaviour a person will see | observed on the surface — a browser, the actual output — not inferred from a diff |
+| a typo, a comment, a rename the compiler checks | the compiler, the suite already running, and nothing more |
+
+**Four things that mean you have crossed over**, and each has cost this project a
+run:
+
+- **A third pass over the same axis finds mostly what the last pass's fixes broke.**
+  The axis is exhausted — rotate it or stop ([`audit.md`](audit.md)).
+- **The check is being widened after it went green**, with no failure in hand. A
+  check widened by imagination is a check whose scope nobody has measured.
+- **The evidence is being gathered for a claim nobody made.** If no REQ row and no
+  gate criterion asks for it, it is not evidence — it is browsing.
+- **The run is on its second measurement of the same number.** One measurement plus
+  what it does not cover, stated, beats two measurements and no decision.
+
+**This never licenses skipping a gate.** The gates are the floor, and the floor is
+not proportionate to anything — a `manual` gate waits, `unknown` fails stage 10, and
+a green nobody watched fail is not evidence at any blast radius. What is
+proportionate is the work *above* the floor: how many axes, how many passes, how
+much of the corpus. Cutting the floor to go faster is not speed; it is the failure
+this whole file exists to prevent, arriving on schedule.
+
+**Where it is recorded.** Stages 3 and 4 carry a `Cost:` line —
+`<surfaces>/<guards>/<REQ> now, <…> at stage 2 — <proportionate | grown, and why>`.
+*Grown, and why* is the honest answer often enough that it is written into the form.
+
 ## Disclosures — counted like a ratchet, and deliberately not monotone
 
 A ratchet may only shrink. **Some numbers must not be**, and printing them under a
@@ -471,12 +515,13 @@ column and it reappears in the other, silently, because a wrong claim looks like
 So a **disclosure** is printed beside the verdict like a ratchet and carries the opposite
 rule: **no floor, no direction, and a movement in either direction wants one sentence.**
 
-Two disclosures, kept separate because they are different facts:
+The disclosures below are kept separate because they are different facts — the list is the count:
 
 | Disclosure | Counts | Reading it |
 |---|---|---|
 | `abstained: N` | claims the run **declined to make** — `partial`, `unknown`, `cannot verify from diff` | a *choice*. Rising can mean the work got harder or the run got honest; falling can mean either the reverse |
 | `unlooked: N` | checks that **did not look** — `dormant`, `skip` | a *state of the corpus*, not a decision. It falls as the project grows the inputs those checks need |
+| `holds: N` | what the run left **running or lying about** — the eight classes in `references/residue.md` | a *state of the environment*, not of the corpus or of the run's claims. A legitimate 2 during a build beats a manufactured 0; only stage 10 requires it to reach zero or name an owner per item |
 
 Three are deliberately **not** counted, and saying which is part of the disclosure:
 

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

@@ -53,6 +53,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | The ladder, seams, axis rotation, ratchets | `references/audit.md` |
 | Loop detection and its caps | `references/loop-guard.md` |
 | **What the run prints about itself** — the header block, the rail, the iteration line | `references/progress.md` |
+| **What the run leaves running and leaves behind** — the eight classes, the `holds:` field, the teardown | `references/residue.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 board** — the work-list between runs, its computed priority, and the ledger seam it resolves | `references/backlog.md` |

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

@@ -26,8 +26,10 @@ maintains them and the next run reads them as current.
 - The rail is computed, never eleven
 - What each glyph means
 - The hand-back — what the operator reads when you stop
+- "Done" is a claim, and it names what makes it true
 - Every number is borrowed
 - Absent is a word, never a zero
+- The `holds:` line — what the run is still holding
 - The run ledger this reads from
 - Rationalizations
 
@@ -215,6 +217,38 @@ nothing was unclear. Where a project keeps no open-questions register, that row
 `— no register` rather than `0`: an absent register and an empty one are different facts,
 and the second is the one worth acting on.
 
+## "Done" is a claim, and it names what makes it true
+
+Every disclosure in this bundle answers *what does it print when it did not look?*
+That question is asked of **checks**. It has to be asked of the run's own sentences
+too, because the sentence reaches the operator and the check does not.
+
+**A completion claim names what makes it true, or it is not a completion claim.**
+`done: the export writes UTF-8` is a claim. `done: the export writes UTF-8 —
+`test_export_encoding` green at 5f21ac3` is a report. The difference is not
+politeness; it is whether anyone can disagree with you.
+
+Three ways a run reports something it did not do, none of them requiring an
+intention to mislead:
+
+| The shape | What was actually true | What to write instead |
+|---|---|---|
+| **The plan reported as the outcome** — "added the retry" after writing the code and before running anything | the edit landed | `done` names the executed test, or the item is not `done` |
+| **The reply reported as the result** — a deploy, a teardown, a cancel, an API call that returned success | the call was accepted | re-read the state; the second look is the evidence, the reply is not |
+| **The part reported as the whole** — "tests pass" after running the file you touched | that file's tests pass | say which suite, or run the full one |
+
+**And the honest negative is a result.** *"Not done — the fixture needs a
+credential I do not have"* is a complete, useful report. *"Done (with a small
+caveat)"* for the same situation is not. A run that cannot finish something says
+so at the boundary it reached, names what would unblock it, and moves to the next
+item — `deferred` and `partial` exist as statuses precisely so that stopping does
+not have to be dressed up as finishing.
+
+**The status vocabulary is closed for the same reason.** Stage 10 takes
+`verified`, `partial`, `deferred`, `dropped` — and `unknown` fails the gate
+([`acceptance.md`](acceptance.md)). A fifth word invented at write-time is how a
+run reports a state nobody agreed to read.
+
 ## Every number is borrowed
 
 | Field | Its home |
@@ -250,6 +284,33 @@ is unconfirmed*, which is the opposite claim, and it is the same inversion
 `carry-over 0 rows` **is** a real zero and prints as one: the ledger exists and holds
 nothing.
 
+## The `holds:` line — what the run is still holding
+
+Beside every gate verdict the run prints `holds: N` — the environment it has not
+given back. It lands in the ledger as a `holds:` line
+([`../templates/run.md`](../templates/run.md)), one per gate that found anything,
+and one at stage 10 whatever the count.
+
+```
+holds: 5 — 2 (worktree: build-csv-export, this run; container: pg-test, this run) — enumerated 8/8 classes
+holds: 10 — none — enumerated 7/8 classes, unlooked: containers (no docker on this host)
+```
+
+Three things make the line worth writing rather than a habit:
+
+- **It names the class and the owner, not just a number.** *"2"* tells the next
+  run nothing; *"worktree, this run"* tells it what to end and what to leave.
+- **It records how many classes were enumerated.** `8/8` and `7/8, unlooked:
+  containers` are different facts, and a run without container tooling must print
+  the second rather than a clean zero it did not earn.
+- **It is a disclosure, never a ratchet.** No floor, no direction, no target. A
+  build stage legitimately holding a worktree and a database prints `2` and
+  passes; a run that tears its database down to make the number tidy and brings
+  it back up next stage has spent time making a measurement lie.
+
+Doctrine, including the eight classes and what must **not** be torn down:
+[`residue.md`](residue.md).
+
 ## The run ledger this reads from
 
 `.task-pipeline/run.md`, seeded at stage 0 from

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

@@ -0,0 +1,219 @@
+# Residue — what a run leaves running, and what it leaves behind
+
+A run does not only produce a diff. It starts background processes, arms
+monitors, schedules wake-ups, takes leases, creates worktrees, brings up
+containers and writes scratch files. Every one of those outlives the stage that
+created it unless something ends it.
+
+**Two shapes, one class.** *Residue in flight* is what is still running while the
+run continues — it corrupts the work, because a stale monitor fires into a run
+that has moved on and a lease held by a finished stage blocks the next one.
+*Residue at rest* is what is still there when the run ends — it corrupts the next
+run, which inherits a dirty environment it did not create and cannot explain.
+
+Both are checked the same way and this file covers both.
+
+## Contents
+
+- The measured reason this file exists
+- The inventory — eight classes
+- Where the check fires: every gate
+- The teardown, at the end of the run
+- What must **not** be torn down
+- Three owners, not two — and the third is where cleanup actually happens
+- Rationalizations
+
+---
+
+## The measured reason this file exists
+
+On 2026-08-11, mid-run, a monitor was armed to watch CI. One minute later the
+harness task inventory was queried:
+
+```
+TaskList              →  "No tasks found"
+ps -eo pid,etime,cmd  →  52693  03:12  /bin/zsh -c … gh pr checks …
+```
+
+The monitor was **alive and polling**, and the inventory tool reported nothing.
+
+This is the class this whole doctrine exists to catch: **a check answered by
+something that is not its subject.** An inventory that does not enumerate the
+thing that leaks is not an inventory — it is a green light with no lamp behind
+it. A residue check that calls one tool and trusts its silence will report clean
+over a process that is still making network calls.
+
+**So: enumerate by class, never by tool.** Each class below names its own
+enumeration. Silence from one tool is evidence about that tool, not about the
+environment.
+
+---
+
+## The inventory — eight classes
+
+Run the enumeration for every class that the run could have created. A class the
+run provably never touched is skipped **by name**, not by omission.
+
+| Class | What leaks | How to enumerate |
+|---|---|---|
+| **Background shells** | a task started detached and never exited | the harness's background-task list **and** `ps -eo pid,ppid,etime,command` filtered to this session's shell |
+| **Monitors / watchers** | a poll loop still hitting a remote API | `ps` for the poll command; the harness list may not contain it — see above |
+| **Scheduled wake-ups / loops** | a loop that fires into a finished run | the harness's schedule list; a dynamic loop ends by an explicit stop, never by falling silent |
+| **Coordination leases** | a lease held on a shared register blocks every other agent | `agent-sync status` where `.claude/agent-sync.json` exists |
+| **Worktrees / branches** | an isolated build workspace, and the branch under it | `git worktree list`, `git branch --merged` |
+| **Containers / services** | a database or app brought up for a test | `docker ps`, `docker compose ls`, plus whatever the project's own runbook started |
+| **Scratch files** | temp output, planted-defect copies, generated fixtures | `git status --porcelain` for the tree; the scratch directory for the rest |
+| **Remote state** | a draft PR, a test tag, an uploaded artifact, a feature flag flipped for a check | the tracker and forge; the deploy target's own listing |
+
+Two of these bite hardest and are worth naming separately.
+
+**A lease is the one that blocks someone else.** Every other class costs this run
+or the next one. A held lease costs a *different agent*, right now, and it looks
+to them like the register is permanently unavailable rather than briefly held.
+Release it at the stage that took it — not at the end.
+
+**A container is the one that is invisible and expensive.** Nothing in the diff
+mentions it, no test fails because of it, and it will still be running tomorrow.
+
+---
+
+## Where the check fires: every gate
+
+**The residue check is a criterion of every gate, not a stage of its own.** A
+cleanup stage at the end is the design that fails, because the damage from
+residue in flight has already happened by the time the end arrives.
+
+Every gate verdict carries the count, in the same line as the rest:
+
+```
+GATE 5 build: PASS — reviews 3 · findings 0 open · holds: 2 (worktree, container)
+  abstained: 0 · unlooked: 0
+GATE 6 tests: PASS — suite green · holds: 1 (container: pg-test, this run)
+  abstained: 0 · unlooked: 0
+```
+
+Read the line the way the other disclosures on it are read:
+
+- **`holds: 0`** — every class enumerated, nothing found.
+- **`holds: N (…)`** — N things are live, each named. This is a **disclosure,
+  not a failure**. A build stage that legitimately holds a worktree and a database
+  reports `holds: 2` and passes; the count exists so nobody has to remember.
+- **`holds: unlooked (…)`** — a class could not be enumerated, named. A run
+  without container tooling says so rather than printing `0`.
+
+**Why the field is `holds:` and not `residue:`.** `gates.md` already prints
+`unmarked residue: 0` for a different thing — documentation items left unmarked
+— and `residue: 0` is a substring of it. A check written for this field would
+have been answered by that line. The word stays in the prose because it is the
+right word; the **field** is `holds:`, which is free and joins `stage:`,
+`iter:`, `hand:` and `touch:` in the run ledger.
+
+**Its sibling, one file over.** `tdd.md`'s *The green from residue* is the same
+class on the test axis — state left over from an earlier run making a case pass
+that would fail fresh. That rule is about residue **faking a result**; this one
+is about residue **outliving the run**. Neither overrides the other.
+
+**`holds: 0` is never a target.** A run that tears down its database to make a
+number look tidy, and then brings it back up next stage, has spent time to make a
+measurement lie. The number describes; it does not instruct.
+
+**Only stage 10 requires the count to reach zero** — or every remaining item to
+carry a named owner and a reason, in writing.
+
+---
+
+## The teardown, at the end of the run
+
+Stage 10 does not close while this run's residue is live. Walk the inventory once
+more, and for each item either end it or account for it:
+
+1. **Enumerate every class.** Not the ones you remember using — all eight, because
+   the one you forgot is the one still running.
+2. **End what this run started**, in dependency order: remote state first (a draft
+   PR or a flipped flag is visible to other people), then services, then
+   worktrees, then leases, then scratch files.
+3. **Verify each teardown by re-reading, not by the reply.** A cancel, delete or
+   teardown call will happily accept an id that was never scheduled and return
+   success. Enumerate again after tearing down; the second enumeration is the
+   evidence, the first reply is not.
+4. **Write what remains into the run ledger**, with its owner:
+
+```
+holds: 10 — none — enumerated 8/8 classes
+holds: 10 — 1 (container: pg-test, operator asked for it to stay) — enumerated 8/8 classes
+```
+
+An item left standing on purpose is fine. An item left standing silently is how
+the next run starts against a database somebody else's test seeded.
+
+---
+
+## What must **not** be torn down
+
+**Tear down what this run started. Report what it did not.**
+
+The inventory is machine-wide; the authority is not. Another session's monitor,
+another agent's lease, a container that was up before this run began — killing
+any of those is a run reaching outside its own boundary to make its own number
+look better, and it will break work that is going fine.
+
+- **If the run did not start it, it does not end it.** Name it in the ledger as
+  *foreign*, with whatever identifies its owner.
+- **A lease held by another agent is never released by this run**, no matter how
+  stale it looks. Stale is a judgment; the holder is a fact.
+- **Ambiguous ownership is reported, not resolved.** A worktree with no obvious
+  creator is `holds: 1 (worktree, owner unknown)` — which is honest — rather
+  than deleted, which is irreversible.
+
+The asymmetry is deliberate: leaving something running costs a little, and killing
+something someone else owns costs a lot.
+
+---
+
+## Three owners, not two — and the third is where cleanup actually happens
+
+The rule above splits the world in two: what this run started, and what it did not.
+**Dry-running this doctrine on its own project found the state it has no slot for.**
+
+Measured 2026-08-11, enumerating the eight classes on a live run:
+
+```
+worktrees/branches : 3 feature branches, all merged into main, from earlier runs
+containers         : 18 running, none started by this run, oldest 3 days,
+                     across four unrelated projects
+```
+
+The branches are not this run's, so *end what you started* does not reach them. They
+are not foreign either — the project owns them, and reporting them every run forever
+is how a report becomes wallpaper. So:
+
+| Owner | What to do | Why |
+|---|---|---|
+| **this run** | end it, in dependency order | it exists because of work that is now finished |
+| **an earlier run of this project** | end it **when it is provably spent**, and say you did — a branch merged into the default branch, a worktree with no diff, a scratch file from a completed run. Otherwise report it | this is the accumulation nobody is otherwise responsible for, and *provably spent* is a fact rather than a judgement |
+| **anything else** | **report, never end** | see the section above; the asymmetry is not negotiable |
+
+**"Provably spent" is the whole load-bearing phrase.** A branch merged into the
+default branch is spent — `git merge-base --is-ancestor` says so, and nothing is lost
+by removing it. A branch that merely *looks* abandoned is not spent, and the run that
+deletes it is guessing about someone's work in progress. **If the proof needs a
+judgement, the item is reported, not ended** — which puts it back under the rule
+above rather than creating an exception to it.
+
+**A foreign item never becomes spent.** The 18 containers above belong to other
+projects; that they have been up for three days is information for whoever owns them,
+not permission. The third owner state widens what a run may clean **inside its own
+project** and widens nothing at all outside it.
+
+## Rationalizations
+
+| The excuse | What it actually means |
+|---|---|
+| "The task list is empty, so nothing is running." | The measured case above: the list was empty and the process was polling. Silence from one tool is evidence about that tool. |
+| "It will exit on its own." | Some do. The ones that leak are exactly the ones that do not, and you cannot tell which is which without enumerating. |
+| "I will clean up at the end." | Residue in flight has already corrupted the run by then. That is why this is a gate criterion, not a final stage. |
+| "The container is tiny." | Its cost is not its size. It is invisible, it holds state, and it will still be there tomorrow. |
+| "I did not start any background work this stage." | Then the enumeration takes ten seconds and prints `holds: 0`. The cheap case is not the reason to skip the check. |
+| "The lease is obviously stale." | Stale is your judgment about someone else's work. Report it; do not release it. |
+| "Tearing it down returned success." | So does tearing down an id that never existed. Verify by re-enumerating. |
+| "`holds: 0` looks better in the ledger." | Then the number has become a target and has stopped being a measurement. A legitimate 2 is worth more than a manufactured 0. |

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

@@ -41,6 +41,7 @@ file exists to stop.
 - The loop closes at stage 0
 - Where a lesson goes when it is not about this project
 - Publishing the insight — the skill learns from every project that runs it
+- The improvement iteration — what happens to a published insight next
 - What may leave the project — the redaction list
 - Rationalizations
 
@@ -265,6 +266,7 @@ does ([`audit.md`](audit.md) → *What can't be fixed now becomes a ratchet, nev
 GATE 10 acceptance: PASS — 14/14 REQ verified
   carry-over: 0 unresolved · retro: 7 standing (was 9) · retired 3 · added 1
   abstained: 2 · unlooked: 3
+  holds: 10 — none — enumerated 8/8 classes
 ```
 
 A pruned list that nobody prints is a list that quietly grows back.
@@ -340,6 +342,49 @@ opening…  → #24
 opened, and carry the exact text in the carry-over ledger. That is the honest
 degradation; a second transport is not.
 
+## The improvement iteration — what happens to a published insight next
+
+Publishing is half a loop. An issue that is opened and never triaged is a lesson
+that cost a run and bought nothing, and a tracker full of those teaches everyone
+that publishing is where findings go to be filed.
+
+**The loop, and every arrow in it is somebody's obligation:**
+
+```
+a run diverges → a retro entry → retro.publish → an issue on the skill
+                                                        ↓
+   a board row ← measured against the tree ← triaged in a later cycle
+        ↓
+   doctrine + the guard that proves it → a release → the next run reads it
+```
+
+**Resolve what you worked, let the rest accumulate — visibly.** At the close of a
+cycle that consumed published issues:
+
+- **An issue closes when the behaviour changed**, not when the lesson was
+  understood (that is R-006, and it applies to issues exactly as it applies to
+  findings). The closing comment names **where** it landed — a file and a line —
+  and the guard that now holds it. A close with no address is a close nobody can
+  audit.
+- **An issue nobody worked stays open.** It is not triaged into silence, not
+  relabelled, not closed as stale. The pile is the queue, and its depth is the
+  honest measure of how far behind the doctrine is.
+- **Nothing is deleted.** A closed issue keeps its number, and the number is what
+  the CHANGELOG and the retro entry point at. Deleting one severs both, and the
+  cost lands on whoever next asks *why is this rule here*.
+
+**Where the queue comes from at the start of a cycle**, in this order: open issues
+published by any project running this skill, then the board's open rows by computed
+priority, then the open-questions register. A run that finishes its brief early
+takes the top of that list rather than inventing work — and a run that *cannot*
+take it says so, which is a fuller queue rather than a quiet one.
+
+**The measurement that keeps this honest.** Print, at the close: issues consumed,
+issues resolved with an address, issues left open. Three numbers, no floor, no
+target, and the third one rising is information rather than a failure — it means
+the projects running this skill are finding more than one cycle can absorb, which
+is what you want them to do.
+
 ## What may leave the project — the redaction list
 
 An issue is a **public artefact in someone else's repository**. What travels is the

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

@@ -430,7 +430,7 @@ never that the work was skipped quietly.
   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
-  ([`audit.md`](audit.md)) — **and so are the two disclosures**, `abstained` and
+  ([`audit.md`](audit.md)) — **and so are the disclosures**, `abstained` and
   `unlooked` ([`gates.md`](gates.md) → *Disclosures*): what the run declined to claim,
   and what a check never looked at. Neither has a floor and neither may be targeted; a
   target on an abstention count is an instruction to guess.
@@ -656,7 +656,12 @@ never that the work was skipped quietly.
   surfaced that nobody asked for, every decision still waiting **asked here with
   options rather than listed**, and the ambiguity count computed from the four
   registers with its ids ([`progress.md`](progress.md) → *The hand-back*) — a run
-  that cannot say what happened has not finished, it has stopped; **both disclosures printed beside the verdict** — `abstained` (what the run declined
+  that cannot say what happened has not finished, it has stopped; **the environment is
+  given back** — all eight classes enumerated, everything this run started ended and
+  verified by re-enumerating rather than by the teardown's reply, an earlier run of
+  this project ended only when **provably spent**, an item this project does not own
+  reported rather than ended, and the result written as a `holds:` line
+  ([`residue.md`](residue.md)); **every disclosure printed beside the verdict** — `abstained` (what the run declined
   to claim) and `unlooked` (what a check never looked at), neither a ratchet, neither
   with a floor, neither ever a target ([`gates.md`](gates.md) → *Disclosures*); **the
   retrospective is written — stamped first, then pruned, then the entry; the

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

@@ -20,6 +20,7 @@ stage: <id> <name> — gate <auto|manual> — verdict <pass|fail|skip> — <ISO-
 iter:  <N> — item <B-NNN or task id> — closed at gate <stage id>
 touch: <file> — pass <N> (<stage|round|module>) — reason: <finding id / gate item>
 hand:  <N|10> — task "<quoted>" — done <n> — surfaced <n> — decisions <n> — amb <n> (<ids or "— no register">)
+holds: <stage id> — <n> (<class: what, owner>; … or "none") — enumerated <n>/8 classes, <unlooked: classes not enumerable>
 ```
 
 - **`stage:`** — written when a gate **returns**, not when the stage is entered. The
@@ -53,6 +54,8 @@ touch: src/export.ts — pass 1 (stage 5) — reason: TASK-3
 touch: src/export.ts — pass 2 (stage 5) — reason: F-014
 touch: src/export.ts — pass 3 (stage 5) — reason: F-014
 hand:  3 — task "add CSV export to the orders table" — done 2 — surfaced 1 — decisions 1 — amb 2 (OQ-0007, ledger row 4)
+holds: 5 — 2 (worktree: build-csv-export, this run; container: pg-test, this run) — enumerated 8/8 classes
+holds: 10 — none — enumerated 7/8 classes, unlooked: containers (no docker on this host)
 ```
 
 The last two lines are a **trip**: the same file, two consecutive passes, the same