task-pipeline-skill 1.42.0 → 1.44.0

package/CHANGELOG.md

@@ -1,5 +1,160 @@
 # Changelog
 
+## v1.44.0 — six lessons other projects paid for, carried home by the mechanism that exists for it
+
+`retro.publish` sends a skill-level lesson upstream as an issue. Six arrived in one day
+from projects that are not this one, and every one is a diagnosis: the class, why the
+existing doctrine did not catch it, and the fix by grade. This release is those six.
+
+| Issue | What it bought |
+|---|---|
+| #30 | a name in `verified by` **resolves**, or the row is `unknown` — never `verified` |
+| #31 | a probe that mutates a file asserts its plant landed **— now a guard** |
+| #32 | a seam is not a deliverable: an explicit REQ for the boundary, phrased as a journey |
+| #33 | the tests gate names **what each case consumes**; a timeout is unclassified, not slow |
+| #34 | stage 10 carries a `publish:` line — an unarmed path stops looking like silence |
+| #35 | a ratchet's matcher is itself a check: feed it a **near-miss it must reject** |
+
+### Two of them had already been found here, independently
+
+**#35 is the neighbour probe**, shipped in v1.42.0 after a reader defeated six guards whose
+evidence sat next to their subject. The reporting project reached it from a ratchet whose
+matcher credited every parent with its child's coverage. Same class, two routes, no
+contact — which is the strongest evidence either had.
+
+**#31 is R-001**, born here on 2026-08-03 and **retired in v1.38.0** on its own trigger:
+*"a probe harness exists that asserts the plant changed the parsed text"*. The harness does
+exist. The retirement was still premature, because the condition was *"a harness exists"*
+and the thing that mattered was *"the harness is used everywhere"*. It cost the reporting
+project three incidents in one day and this repository six in this session's own releases.
+**A retirement trigger phrased as the existence of a mechanism, rather than its reach, is
+a trigger that fires early.**
+
+### The number that took four attempts
+
+Enforcing #31 meant counting probes that mutate a file without asserting the plant landed:
+
+```
+hand-written classifier   206 of 206 already carry it   (wrong)
+the guard, first version   22 do not                    (wrong — one spelling)
+the sweep that followed    "fixed" 6 sound probes, corrupted 5
+the truth                  16
+```
+
+The guard corrected the hand count that motivated it. Then the guard was itself the class
+two sections above — keyed to one spelling, it reported as defective six probes that
+obeyed the rule in different words, and a sweep written from that verdict split five live
+statements. Found by `compile()` and a restore from git.
+
+**Every** mutating probe carries the assertion, and **no figure is written here** — the
+third attempt to put one beside it was wrong too. The count is a `grep` away and the
+guard computes it on every run; a number in prose next to a check that can count is
+restating instead of computing, which is the rule this very release imports and which
+this paragraph broke three times before it stopped trying.
+
+- Guards: 261 → **275**.
+
+## v1.43.0 — the rail said where, and nothing said what happened
+
+A fourteen-iteration session on this repository ended each return with the same question
+from the operator: *what did you actually do?* The rail answered **where** the run was —
+one line, computed, correct — and nothing answered the rest. Everything else was
+recoverable from artefacts; what a run learned by accident was recoverable from nothing.
+
+### The hand-back
+
+At both boundaries — an iteration's close and stage 10's — the run now writes four
+sections and two lists:
+
+```
+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 four registers, with ids
+```
+
+**TASK is quoted, never paraphrased** — a run that restates the request in its own words
+after eight iterations has rewritten it, and the operator cannot see that happen.
+**DECISIONS WAITING are asked, not parked**: a question in a report is answered days
+later, if at all. And **AMBIGUITIES are computed**, from four registers an earlier stage
+already wrote — open `OQ-####` rows, carry-over rows with no home, REQ rows whose check is
+`review` rather than a command, and source-ledger rows reading *none found*. An unbounded
+*"is anything unclear?"* becomes a ritual sentence within three runs.
+
+**It is a gate criterion, not a good intention.** `progress.md` already carried one
+instruction with no gate behind it — *"copy it, tick it"* — and the v1.37.0 audit found
+that no run had ever obeyed it.
+
+### The reader found that this release built what it had just condemned
+
+A gate criterion with **no artefact**. Every guard read the doctrine files, so all any of
+them could establish was that the instruction was still written down — none could
+establish that a run obeyed it. The reader then constructed a conforming hand-back
+concealing a weakened test and showed that **nothing in the repository would notice**,
+and that an audit a year later could reach no verdict either way, because there would be
+no run records to check. This file's own diagnosis of *"copy it, tick it"* — a rung-1
+rule read as rung 3 — reproduced one level up.
+
+**The hand-back now has an address:** a `hand:` line in the run ledger, declared as its
+fourth shape. `grep -c '^hand:'` against `grep -c '^iter:'` is what makes a missing one
+readable.
+
+Six more, all verified by planting and watching `PASS`:
+
+- **`"hand-back"` as a bare substring could not tell a requirement from a mention** — a
+  gate reading *"the hand-back is OPTIONAL and may be skipped"* passed, in the release
+  whose entire argument is that it must be a criterion. Both gate guards now require the
+  normative phrase;
+- **the gate span was unbounded below** — the GATE is the last bullet, so a paragraph
+  after it answered for it;
+- **the template was every fence joined**, so a worked example — the likeliest next edit
+  to that section — would have answered for the template;
+- **the two lists were left to prose** while the four sections were read from the fence,
+  which is the split this release wrote a guard to forbid;
+- **the AMBIGUITIES subsection could be replaced by explicit judgement** and pass, keeping
+  the four words as *examples*;
+- and a relocated section was reported as a deletion.
+
+**Four doctrinal defects, not guard defects:**
+
+- *"at both boundaries"* named a pair this file defines as something else three sections
+  above — a reader resolving it there writes a hand-back at task start, where TASK is the
+  only field with content;
+- **the four ambiguity sources had no commands**, though the section claimed *"each read
+  by a command"* — and one of them would have grepped for a string the source ledger's own
+  doctrine never writes, returning a false zero;
+- **one register is structurally zero at the gated boundary**: stage 10's own gate already
+  forbids an unresolved carry-over row, so that count is zero because a sibling clause
+  compelled it. The section now says to print *why*;
+- and **`acceptance.md` — the file stage 10 actually opens — never mentioned the
+  hand-back**, while carrying every other criterion. Two surfaces were updated where four
+  state this gate.
+
+**Still true and stated rather than fixed:** `SURFACED` has no register behind it, and the
+doctrine calls it the section that earns the hand-back. *"Nothing surfaced"* remains a
+quiet decision. The `hand:` line records that a hand-back happened, never that it was
+complete.
+
+### Six predicates answered by their neighbours, all caught by their own probes
+
+- the four section names were read from the whole section, and `SURFACED` appears in the
+  sentence explaining why SURFACED matters — so renaming the template row left the guard
+  green. It now reads the **fenced template**;
+- `asked` appears in `SURFACED`'s own description (*"nobody **asked** for"*), so the
+  decisions check was answered by a neighbour;
+- and the section span was narrowed to `#{2,3}` by reflex, which cut the guard off from
+  the `###` subsection holding four of the things it checks. **The span follows the
+  subject, not a house style** — v1.42.0 narrowed a different span for the opposite
+  reason.
+
+Not one of these needed a reader. The neighbour-probe habit shipped one release earlier
+caught all three, which is the first evidence it does what it was written for.
+
+- Guards: 253 → **261**.
+
 ## v1.42.0 — a probe proves the phrasing its author had in mind
 
 Six times in one session a guard was defeated by **text that was not its subject**, and

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.42.0 |
+| **Version** | 1.44.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.42.0",
+  "version": "1.44.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 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.42.0",
+  "version": "1.44.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -273,7 +273,7 @@ capable available — see `references/model-tiering.md`).
 | 7 | Lint + deploy | host lint → deploy per host convention | lint clean + suite green before deploy; deploy needs a go (or the brief's specific standing authorization) | manual |
 | 8 | Post-deploy | tail deploy logs / health-check | clean boot or honest degradation report; **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 | host module docs/runbook rules → `wiki-update` ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki), recommended) → `/graphify . --update` ([`references/knowledge-graph.md`](references/knowledge-graph.md), recommended) | 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** | built in: [`references/audit.md`](references/audit.md) (ladder walk) → [`references/acceptance.md`](references/acceptance.md) (coverage table) → [`references/retrospective.md`](references/retrospective.md) (retro: stamp, prune, entry) | 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); 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** | built in: [`references/audit.md`](references/audit.md) (ladder walk) → [`references/acceptance.md`](references/acceptance.md) (coverage table) → [`references/retrospective.md`](references/retrospective.md) (retro: stamp, prune, entry) | 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 |
 
 
 ### Stage 10 in a project of several repositories

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

@@ -166,7 +166,7 @@
       ],
       "gate": {
         "type": "manual",
-        "check": "Close the circle. FIRST the LADDER WALK (references/audit.md), because the REQ table can only find what was named and lost — a comparison needs two sides and an absence has one: walk each REQ bottom-up through its rungs (decision -> spec section -> contract AND its failure behavior -> plan task -> change -> executed test -> surface/docs), check the seam at each step, order findings BY SEAM not by file, and turn every absence into a new REQ row with its check BEFORE the table is written; findings belonging to a lower layer go back to that layer (spec -> stage 3, plan -> stage 4); record the pass's two counts (new findings vs findings caused by this run's own fixes) so the next pass can tell whether the axis is exhausted. THEN the coverage table: every REQ has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded, and a green from a check nobody has watched fail against a planted defect is not evidence at all; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved and the ledger's counts are printed beside this verdict, so 'green' never reads as 'verified'; EVERY REPOSITORY IS CLOSED, THE PARENT INCLUDED — a submodule is finished only when its parent points at it, so 'git submodule status' shows no line starting with '+' and every repo is clean and pushed ('git -C <repo> status --porcelain' and 'git -C <repo> log @{u}..HEAD' both empty), because a parent records a submodule as a pointer to one commit and moving the submodule does not move the pointer: neither repo looks wrong alone and the disagreement survives every check that runs inside one; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off. LAST ACT, THE RETROSPECTIVE (references/retrospective.md, written to docs/superpowers/retro.md — one file per project, not per run, because every gate in this flow is good at THIS run and blind across runs): PRUNE BEFORE YOU ADD — every standing instruction checked against its three retirement triggers (it became a check; every path/command/stage it names is gone; it has not fired in the last five run stamps), the list held to its hard cap of ten (at eleven the oldest never-fired row goes — 'they all matter' is the state in which the list stopped being read), and EVERY DELETION LOGGED as one line, never silent; THEN stamp the run (date, topic, verdict, counts); THEN, only if the run diverged, write the entry — symptom with evidence, the stage it surfaced at, the stage that OWNED it, the root cause ('the agent was careless' is not one), the fix by grade (mechanical check > standing instruction with its retire-when written at birth > a note that expires in two runs), and the check that catches it the first time from now on. A retro left empty after a messy run is the failure this file exists to stop, and the retro counts are printed beside this gate's verdict like the carry-over ledger's, so a list that quietly grew back is visible where it happened. EVERY LESSON CARRIES ITS COMMIT: each standing instruction has the SHA that introduced it and the SHA of the run in which it last fired, each log entry and each retirement carries one, the run stamp carries the run's own — a file:line rots at the next edit while 'git show <sha>' reconstructs the whole incident two months later — and every SHA must resolve, which the documentation gate checks with 'git rev-parse --verify'. ROTATION: entries older than the last five run stamps MOVE into docs/superpowers/retro/YYYY-QN.md, which is append-only and QUERIED rather than read, so the in-force file stays short enough to be read in full and pruning costs no knowledge. AND THE GATE ITSELF IS PROVEN: every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, with the probe recorded, and its ratchet counts are printed beside this verdict (references/gates.md)."
+        "check": "Close the circle. FIRST the LADDER WALK (references/audit.md), because the REQ table can only find what was named and lost — a comparison needs two sides and an absence has one: walk each REQ bottom-up through its rungs (decision -> spec section -> contract AND its failure behavior -> plan task -> change -> executed test -> surface/docs), check the seam at each step, order findings BY SEAM not by file, and turn every absence into a new REQ row with its check BEFORE the table is written; findings belonging to a lower layer go back to that layer (spec -> stage 3, plan -> stage 4); record the pass's two counts (new findings vs findings caused by this run's own fixes) so the next pass can tell whether the axis is exhausted. THEN the coverage table: every REQ has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded, and a green from a check nobody has watched fail against a planted defect is not evidence at all; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved and the ledger's counts are printed beside this verdict, so 'green' never reads as 'verified'; EVERY REPOSITORY IS CLOSED, THE PARENT INCLUDED — a submodule is finished only when its parent points at it, so 'git submodule status' shows no line starting with '+' and every repo is clean and pushed ('git -C <repo> status --porcelain' and 'git -C <repo> log @{u}..HEAD' both empty), because a parent records a submodule as a pointer to one commit and moving the submodule does not move the pointer: neither repo looks wrong alone and the disagreement survives every check that runs inside one; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off. LAST ACT, THE RETROSPECTIVE (references/retrospective.md, written to docs/superpowers/retro.md — one file per project, not per run, because every gate in this flow is good at THIS run and blind across runs): PRUNE BEFORE YOU ADD — every standing instruction checked against its three retirement triggers (it became a check; every path/command/stage it names is gone; it has not fired in the last five run stamps), the list held to its hard cap of ten (at eleven the oldest never-fired row goes — 'they all matter' is the state in which the list stopped being read), and EVERY DELETION LOGGED as one line, never silent; THEN stamp the run (date, topic, verdict, counts); THEN, only if the run diverged, write the entry — symptom with evidence, the stage it surfaced at, the stage that OWNED it, the root cause ('the agent was careless' is not one), the fix by grade (mechanical check > standing instruction with its retire-when written at birth > a note that expires in two runs), and the check that catches it the first time from now on. A retro left empty after a messy run is the failure this file exists to stop, and the retro counts are printed beside this gate's verdict like the carry-over ledger's, so a list that quietly grew back is visible where it happened. EVERY LESSON CARRIES ITS COMMIT: each standing instruction has the SHA that introduced it and the SHA of the run in which it last fired, each log entry and each retirement carries one, the run stamp carries the run's own — a file:line rots at the next edit while 'git show <sha>' reconstructs the whole incident two months later — and every SHA must resolve, which the documentation gate checks with 'git rev-parse --verify'. ROTATION: entries older than the last five run stamps MOVE into docs/superpowers/retro/YYYY-QN.md, which is append-only and QUERIED rather than read, so the in-force file stays short enough to be read in full and pruning costs no knowledge. AND THE GATE ITSELF IS PROVEN: every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, with the probe recorded, and its ratchet counts are printed beside this verdict (references/gates.md). THE HAND-BACK IS WRITTEN — the request quoted as GIVEN, progress against it, what was solved with evidence, what surfaced unasked, every waiting decision ASKED here with options, and the ambiguity count computed from the four registers; zero prints as zero."
       }
     }
   ],

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

@@ -17,6 +17,8 @@ requirement.** It is what turns the pipeline from a funnel into a circle.
 - Several repositories — a submodule is finished when its parent says so
 - The closing question
 - The retrospective — the run's last act
+- A `verified by` name is a claim until it resolves
+- A seam is not a deliverable, and REQ rows are written against deliverables
 - GATE (manual)
 - When the answer is "something's missing"
 
@@ -201,6 +203,56 @@ GATE 10 acceptance: PASS — 14/14 REQ verified
   abstained: 2 (1 partial · 1 cannot-verify) · unlooked: 3 dormant
 ```
 
+## A `verified by` name is a claim until it resolves
+
+Reported from another project. Two rows in one run named checks that did not exist — a
+locale-parity test for a project with ten locales and no such test, an index-resolution
+test that had never been written. Both rows carried a status, an owner and an evidence
+cell. **Nothing in the artefact distinguishes *"this check exists and passed"* from *"this
+is the name a check would have if someone wrote it"*.**
+
+This file already requires the evidence to come from a check seen failing once. That
+requirement is about the **check**; nothing walks back from the **name** to ask whether a
+check by that name is on disk. The ladder walk found both, because it re-derives coverage
+from the artefact instead of reading the table — which also means the table was wrong for
+the whole run until its last gate.
+
+**So every name in a `verified by` cell resolves before the table is accepted** — to a
+file, a test name a runner will select, or a command that exits. A cell naming nothing is
+a REQ with status **`unknown`**, never `verified`.
+
+The coverage table is this pipeline's own record of what was proven. When it can carry an
+unresolvable name it stops measuring the run and starts recording the author's intent,
+which is [`gates.md`](gates.md)'s false success living inside the pipeline's own artefact.
+
+## A seam is not a deliverable, and REQ rows are written against deliverables
+
+Also reported. Two halves of a feature shipped in one run, each correct alone, each with a
+passing unit test. Together they formed a closed loop: a guard turned away users who had
+not reached a state, and the new flow that would put them into that state sat behind the
+guard. **The defect was in the seam, and a seam has no file.** The coverage table had a
+row per artefact and both rows were green.
+
+The blindness one layer down is already named — a handler test proves the handler, not the
+request path. This is that shape one layer up.
+
+**So when a run replaces a component that another component branches on, stage 2 writes an
+explicit REQ for the boundary** —
+not *"A works"* and *"B works"* but **"a user in state X reaches Y"**. Phrased as a
+journey it is testable; phrased as two artefacts it is not.
+
+**This does not contradict [`decomposition.md`](decomposition.md), and the wording matters
+because a first draft did.** That file says a REQ appearing in two modules means the seam
+runs *through* a requirement, and tells you to re-cut. A boundary REQ is not that: it is a
+single requirement about the transition, owned by **one** module — the one that consumes
+the boundary — and it maps to exactly one module like every other. Cite it as a journey
+owned by the downstream module, and both rules hold.
+
+**And where no check can span the seam** — a server-rendered redirect on one side, a
+client write on the other — the table says so under `unlooked` rather than showing two
+green rows. Two green halves reporting a working whole is exactly the shape this file
+spends its length refusing.
+
 ## GATE (manual)
 
 All of:
@@ -251,6 +303,14 @@ All of:
 Manual by design. An automated check can prove the table is *well-formed*; only
 the person who asked can confirm it is *what they asked for*. Do not let a green
 table substitute for that answer.
+12. **The hand-back is written** ([`progress.md`](progress.md) → *The hand-back*) —
+   the request quoted as it was GIVEN, where the run stands against it, what was solved
+   with its evidence, what surfaced that nobody asked for, every decision still waiting
+   **asked here with options rather than listed**, and the ambiguity count computed from
+   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.
+
 
 ## When the answer is "something's missing"
 

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

@@ -31,6 +31,8 @@ elsewhere and is not restated here:
 - Writing the check itself
 - Probing — plant, run, restore
 - The neighbour probe — plant the evidence outside the subject
+- A ratchet's matcher is itself a check, and it needs a near-miss
+- A green probe is evidence only if the mutation is known to have landed
 - The false-positive budget
 - Ratchets
 - Disclosures — counted like a ratchet, and deliberately not monotone
@@ -347,6 +349,79 @@ the item, then match on flattened text so an emphasis marker cannot hide the bou
 where that ends*. It costs nothing and it is the only part of a check a later reader can
 disagree with before the defect arrives.
 
+## A ratchet's matcher is itself a check, and it needs a near-miss
+
+Reported from another project through `retro.publish`, and it is the neighbour probe's
+own class arrived at independently — which is the strongest evidence either has.
+
+A run built a ratchet to hold a coverage debt: a list of units with no test, a guard that
+fails when the list grows, a count printed at the gate. Exactly the shape
+[`audit.md`](audit.md) asks for instead of a deferred TODO. The guard decided whether a
+unit was covered by asking whether its identifier appeared **anywhere** in the test
+corpus. The identifiers were path-like and many were prefixes of longer ones, so every
+unit that happened to be the parent of another was credited with its child's coverage.
+
+**A ratchet whose matcher is looser than its subject shrinks itself.** It reports progress
+for work nobody did, and because a ratchet is trusted precisely so that nobody re-derives
+it, the error compounds for as long as the ratchet exists.
+
+Both existing rules were satisfied. The ratchet was printed. The guard had been seen going
+red when the list grew. Neither asks whether the matcher can tell its subject from a near
+neighbour, and that is the only question that would have caught it.
+
+**So before a ratchet is kept, feed its matcher a near-miss it must reject** — the prefix,
+the parent, the same name in a comment or an import, the longer extension. Seeing a guard
+go red on a real change proves it **reacts**; seeing it stay green on a look-alike proves
+it **discriminates**. Only the second makes its number worth trusting.
+
+**And when a matcher is corrected, re-derive the whole ratchet and print both numbers with
+the reason.** In the reporting project the corrected count was *identical* to the old one
+and the composition was not: rows credited falsely came back in as rows genuinely paid off
+went out. A single number with no delta reads as a run where nothing happened.
+
+## A green probe is evidence only if the mutation is known to have landed
+
+Also reported from another project, three times in one day, each caught only because the
+result was too good:
+
+1. a scripted substitution missed on indentation — the file was unchanged and the probe
+   measured nothing;
+2. an assertion written against a bare identifier kept matching the **import line** after
+   the field it guarded was deleted;
+3. a file-extension alternation matched the longer extension as though it were the
+   shorter, reporting nine live files as missing.
+
+In all three the observable was identical to success. *"See it fail once"* has an unstated
+precondition — **that the thing you changed is the thing the check reads** — and a planted
+defect that did not land produces the same green as a check that cannot fail.
+
+**So a probe that mutates an existing file asserts its plant landed, in the same breath as
+planting it.** A probe that writes a whole file has no such question: the file exists or
+the command failed. This repository measured itself while writing this section and got the
+number wrong three times. A hand-rolled classifier said *206 of 206 already carry it*.
+The guard written from the rule said **22 did not** — and was itself too narrow, matching
+one spelling of the assertion, so six probes that already had it in lower case were
+called defective. A sweep then "fixed" those six and **corrupted five**, splitting live
+statements. The true figure was **16**, and it took the guard, a compile check and a
+restore from git to find it.
+
+Two things are worth keeping from that. **The check corrected the measurement that
+motivated it** — which is the argument for writing checks rather than counting by hand.
+And **a check keyed to one spelling of a rule is the class two sections above**: it
+reported as defective the probes that obeyed the rule in different words. **Every**
+mutating probe carries the assertion now — the figure is deliberately not
+written here. A first draft said *201*, which was true of the branch point and false in
+the same commit, because the twelve probes added for this release are themselves mutating
+probes. The guard computes it; a number in prose beside a check that can count is the
+class this bundle calls restating instead of computing. Probes that write a whole file
+need none: the file exists or the command
+failed.
+
+**Prefer an assertion that names the construct over one that names a substring of it.** A
+guard written against a bare identifier survives the deletion of everything it guarded,
+because the identifier still appears in an import. That is case 2 above and it is the same
+class as the section before this one, one level down.
+
 ## The false-positive budget
 
 Run a new heuristic over the **real corpus** before shipping it and count the false

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

@@ -25,6 +25,7 @@ maintains them and the next run reads them as current.
 - The iteration line
 - The rail is computed, never eleven
 - What each glyph means
+- The hand-back — what the operator reads when you stop
 - Every number is borrowed
 - Absent is a word, never a zero
 - The run ledger this reads from
@@ -119,6 +120,101 @@ the verdict the gate wrote, in the run ledger, and from nothing else.
 **`⊘` may never be silent.** A skipped stage with no recorded reason is exactly what a
 `·` looks like from outside, and the two mean opposite things.
 
+## The hand-back — what the operator reads when you stop
+
+The rail says **where** the run is. It does not say what happened, and a reader who was
+away cannot reconstruct that from a glyph. Measured on this project: a fourteen-iteration
+session where the operator returned to a one-line rail each time and had to ask.
+
+**At the close of an iteration, and again at stage 10.** This is *not* the pair named
+three sections above: *The two boundaries, and only those two* governs the **rail**, and
+its pair is task start and iteration close. The hand-back shares one and adds the run's
+end — a rail at task start has nothing to report, and a run that ends without a hand-back
+is the case this section exists for. A reader resolving *"both boundaries"* against the
+other section wrote one at task start, where TASK is the only field with content. The run
+writes a hand-back with **four sections and two lists**. It is a gate criterion **at stage
+10**, not a good intention: this file already carried one instruction with no gate behind
+it (*"copy it, tick it"*), and the v1.37.0 audit found no run had ever obeyed it.
+
+**The iteration-close instance has no gate, and that is a weakness rather than an
+oversight** — an iteration boundary has no verdict to hang a criterion on. It is
+therefore the very shape the sentence above indicts, written inside it. What keeps it
+from being *"copy it, tick it"* is the run ledger: the iteration line already lands there,
+and the hand-back lands beside it, so a later audit has something to read. Where a project
+keeps no ledger, the iteration hand-back is prose discipline, and the run says which of
+the two it is running.
+
+```
+── hand-back · <topic> · iteration <n> ───────────────────────────
+TASK        the request as it was GIVEN, quoted from the brief — not
+            as it looks now that you understand it
+PROGRESS    where the run stands against that request: gates passed,
+            what remains, and the board id it is heading for
+DONE        what was solved this iteration, each with its evidence
+SURFACED    what came up that nobody asked for — findings, corrections,
+            things that turned out to be other than assumed
+
+DECISIONS WAITING  <n>   each as a question with options, asked HERE
+AMBIGUITIES        <n>   computed, below
+```
+
+**Where there is no brief** — `checkup`, `setup`, a short path — TASK quotes the
+operator's own sentence instead, marked as such. An unquotable TASK is a run that cannot
+say what it was asked, which is worth its own line.
+
+**Where it lands.** The narrative goes to the operator; the trace goes to the run
+ledger as a `hand:` line ([`../templates/run.md`](../templates/run.md)). Without it the
+hand-back is a gate criterion with no artefact — a reader proved that of v1.43.0's
+first draft: every guard could check the instruction was still written, none could
+check a run obeyed it, and an audit a year later could reach no verdict either way.
+`grep -c '^hand:'` against `grep -c '^iter:'` is what makes the difference readable.
+
+**TASK is quoted, never paraphrased.** A run that restates the request in its own words
+after eight iterations has rewritten it, and the operator cannot see that happen. The
+quote is the one line the drift shows against.
+
+**SURFACED is the section that earns the hand-back.** Everything else is recoverable from
+the artefacts; what a run *learned by accident* is recoverable from nothing. A run that
+found a stale claim, corrected a number, or discovered a rule was never enforced puts it
+here even when it was fixed in passing — especially then.
+
+**DECISIONS WAITING are asked, not listed.** A question parked in a report is a question
+the operator answers days later, if at all. Ask it at the boundary, with options and a
+recommendation, in the same breath as the report. If there are none, the field prints
+`0` — [`gates.md`](gates.md)'s rule about absence applies here too.
+
+### AMBIGUITIES are computed from four registers the run already keeps
+
+Not judgement, and not a prompt to think harder — an unbounded *"is anything unclear?"*
+becomes a ritual sentence within three runs. Four sources, each read by a command:
+
+| Source | What it means | Read by |
+|---|---|---|
+| open `OQ-####` rows ([`documentation.md`](documentation.md)) | a question raised and never answered | `grep -cE '^\| OQ-[0-9]+' docs/OPEN_QUESTIONS.md` — **no file prints `— no register`, never `0`** |
+| carry-over rows whose home is unsettled | deferred into nothing ([`../templates/carryover.md`](../templates/carryover.md): `open`, `unresolved`, or a bare `backlog`) | `grep -cEi '\\|[[:space:]]*(open\\|unresolved\\|backlog)[[:space:]]*\\|' <ledger>` |
+| REQ rows whose check is `review` rather than a command | shipped on judgement, unverifiable by a machine | the brief's REQ table, *Verified by* column. The count `spec.md` prints is **checks**, not REQ rows — different units, and quoting one for the other is a borrowed number that does not fit |
+| source-ledger rows with **no source** | the run built on the absence of a document | the brief's ledger, rows whose *Source* cell is empty or parenthesised. `knowledge-sources.md` writes them `(none for X)` while `templates/brief.md` writes `none found`, so **a grep for either string alone returns a false zero** |
+
+The `Read by` column is the point of the table. Without it, *"each read by a command"* is a
+claim the section makes about itself and cannot keep — and one of the four greps would
+have returned zero for searching a string the source ledger's own doctrine never writes.
+
+Each prints its count **and its ids**. A count with no ids is a number nobody can act on,
+and **zero prints as zero** — silence and "I looked and found none" are the two states
+this file exists to keep apart.
+
+**One of the four is structurally zero at the gated boundary.** Stage 10's own gate
+already requires that no carry-over row is left unresolved, so there that count is zero
+**because a sibling clause compelled it**, not because the run looked. At an iteration
+close it is a real measurement. Print it either way, and at stage 10 print *why* it is
+zero — a number that had no choice is not evidence.
+
+**Why these four and not a fifth.** Every one is already written down by an earlier stage,
+so the hand-back reports rather than re-derives, and a run cannot quietly decide that
+nothing was unclear. Where a project keeps no open-questions register, that row prints
+`— no register` rather than `0`: an absent register and an empty one are different facts,
+and the second is the one worth acting on.
+
 ## Every number is borrowed
 
 | Field | Its home |

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

@@ -33,6 +33,7 @@ file exists to stop.
 - Write the entry only for a divergence — and name the layer that owned it
 - Every lesson carries its commit
 - The stamp table is capped at ten, and *one line per run* was never a cap
+- `publish:` is a line in the verdict, not a silence
 - Rotation — the archive is how pruning stops losing things
 - Three grades of fix — take the highest one that can work
 - Stamp first, then prune, then write
@@ -100,6 +101,42 @@ like every other rotation. **The count is printed at the prune**, beside the sta
 instructions' own count, so a table that stops rotating is visible rather than merely
 large.
 
+## `publish:` is a line in the verdict, not a silence
+
+Reported from another project, and the report is about this file: an operator asked, after
+many runs, why nothing had ever been published.
+
+The floor is right and does not move — publishing is opt-in per project, off by default,
+because an outward act taken from a generic flag is an outward act nobody authorized. The
+gap is what happens next. A project with no configuration produces, run after run,
+retrospective entries carrying lessons about **the skill**, and the mechanism reports
+nothing, because it was never armed. **An unarmed mechanism and a mechanism with nothing
+to say are indistinguishable from the outside** — [`gates.md`](gates.md)'s false success,
+applied to this bundle's own learning path. In the reporting project several runs had
+produced skill-level lessons over months; the count of published insights was zero and no
+gate had ever mentioned it.
+
+Stage 10 prints ratchets and two disclosures — what the run declined to claim, and what a
+check never looked at. Publishing is neither, so its absence is not observable at the only
+moment anyone is reading.
+
+**So stage 10's block carries one line for publication:**
+
+```
+publish: <issue url>                       — opened this run
+publish: 0 (configured, nothing insight-grade)
+publish: not configured (N insight-grade entries stayed local)
+```
+
+It arms nothing and authorizes nothing; it makes the silence legible. A count of zero
+beside *configured* is a fine answer. A **blank** where configuration is absent is how an
+instruction went unread for eight releases.
+
+**The failure mode survived its own fix, in a quieter form.** This section once said
+*"open an issue upstream"* while naming no repository, no trigger and no authorization,
+and every reader took it as done. The mechanism that replaced it is correct — and until
+this line existed it still had no way to say it never ran.
+
 ## Rotation — the archive is how pruning stops losing things
 
 At the prune, entries older than the last five run stamps **move** to

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

@@ -651,7 +651,12 @@ never that the work was skipped quietly.
   a messy run is the failure the file exists to stop. Stage 0 reads the standing
   instructions in full next time, which is why the cap is not negotiable.
 - **GATE (manual):** the ladder walk ran and its absences became REQ rows before
-  the table was written; **both disclosures printed beside the verdict** — `abstained` (what the run declined
+  the table was written; **the hand-back is written** — the request quoted as it was
+  GIVEN, where the run stands against it, what was solved with its evidence, what
+  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
   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
@@ -667,7 +672,12 @@ never that the work was skipped quietly.
   string, and the five redaction rules applied
   ([`retrospective.md`](retrospective.md) → *What may leave the project*). Absent, the
   step does not exist and is not asked about: publishing to another repository is an
-  outward act and silence authorizes none**; **the documentation gate has been seen
+  outward act and silence authorizes none. **Either way the verdict carries a `publish:`
+  line** — the issue url, `0 (configured, nothing insight-grade)`, or `not configured
+  (N insight-grade entries stayed local)`: an unarmed path and one with nothing to say
+  are otherwise indistinguishable, which is how this instruction went unread for eight
+  releases** ([`retrospective.md`](retrospective.md) → *`publish:` is a line in the
+  verdict*)**; **the documentation gate has been seen
   failing once against a planted defect and its ratchet counts are printed**
   ([`gates.md`](gates.md)); **every repository is closed — the parent included:
   `git submodule status` shows no `+`, each repo clean and pushed**; **every check this gate leans on has been seen failing

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

@@ -15,6 +15,7 @@ into this skill; nothing to install.
 - Tests that stay honest
 - Stage 6 — consolidation and the suite gate
 - When stuck
+- What a case consumes, and why a timeout is unclassified
 - Rationalizations
 - Red flags — stop and start over
 
@@ -134,6 +135,52 @@ honestly instead.
 | Setup is enormous | Extract helpers; if it's still huge, the design is the problem. |
 | Fixing a bug | Write the failing test that reproduces it first. The test proves the fix and prevents the regression. |
 
+## What a case consumes, and why a timeout is unclassified
+
+Reported from another project after hours spent reading environmental noise as product
+defects. An end-to-end suite registered a fresh account in every case. The product
+rate-limits registration to a handful per minute per address. **A suite of twenty-odd
+cases cannot avoid tripping its own product's limiter.**
+
+A throttled registration does not fail loudly. The form never advances, the case sits
+until its own timeout, and it reports **as a timeout** — which reads exactly like
+slowness. Cold compilation, hydration and a stale cache were each investigated and each
+was independently true; none was the cause.
+
+**A check that cannot run to completion in its own environment reports noise, and noise
+costs more than silence, because it looks like data.** Silence gets investigated. Noise
+gets interpreted.
+
+The neighbouring rule this bundle already has — *a check counts only where it runs* — is
+about **availability**: does the guard execute on the gate. This is about **capacity**:
+the harness is part of the system under test, and a suite that exhausts a production limit
+is measuring the limit.
+
+**So at the tests gate, name what each case consumes from the product** — accounts,
+rate-limited endpoints, external quota, seats, tokens — and confirm the suite's total
+stays under the product's own bound. Where it cannot, the suite **shares** the resource
+across cases instead of acquiring it per case.
+
+**Where the bound comes from, and what to do when it does not exist.** In order: the
+product's own configuration or code; the provider's documented limit; the operator. Write
+the answer into the brief's source ledger like any other fetched fact — a limit an agent
+remembered is a limit nobody can check. **Where none of the three answers, the row reads
+`bound: unknown` and the count goes to `unlooked`** rather than to a guess: this file's
+whole argument is that an unmeasured resource reports as a timeout, and an unmeasured
+*bound* does the same one level up.
+
+**And it does not override *The green from residue*.** That rule is about state a case
+inherits — a database, a volume, a clone — and it still says acquire fresh. This rule is
+about a resource **the product itself meters**. Where the two meet, the product's bound
+wins and the suite shares that one resource while everything else stays fresh; say which
+resource is shared and why.
+
+**And a timeout in an end-to-end suite is an unclassified result, not a slow one.** Before
+it is read as a performance signal the resource question above must have an answer, or the
+run is interpreting its own harness. In the reporting project this was also the most
+likely reason that suite had never once finished inside its CI time cap — so the cost was
+not only the hours, it was every defect the suite never got far enough to find.
+
 ## Rationalizations
 
 | Excuse | Reality |

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

@@ -13,12 +13,13 @@ Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
 
 ## Lines
 
-Append-only. Three shapes, and nothing else belongs here:
+Append-only. Four shapes, and nothing else belongs here:
 
 ```
 stage: <id> <name> — gate <auto|manual> — verdict <pass|fail|skip> — <ISO-8601>
 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">)
 ```
 
 - **`stage:`** — written when a gate **returns**, not when the stage is entered. The
@@ -26,6 +27,14 @@ touch: <file> — pass <N> (<stage|round|module>) — reason: <finding id / gate
   is a summary that is confidently wrong exactly when it matters.
 - **`iter:`** — one line per iteration closed. The progress line's counter is
   `grep -c '^iter:'`, never a number anyone remembers.
+- **`hand:`** — one per hand-back, at an iteration's close and at stage 10
+  (`references/progress.md` → *The hand-back*, inside the skill). The
+  narrative goes to the operator; **this line is the trace it leaves**, and it exists
+  because v1.43.0 shipped a gate criterion with no artefact behind it: every guard could
+  check that the instruction was still written, and none could check that a run obeyed
+  it. A later audit reads `grep -c '^hand:'` against `grep -c '^iter:'` and the two
+  should agree, plus one for stage 10.
+  **`amb` prints its ids or `— no register`, never a bare `0` with nothing beside it.**
 - **`touch:`** — one line per file per pass, and the reason names **what forced the
   edit**: a finding id, a failed gate item, an operator instruction. *"Cleanup"*,
   *"polish"* and *"while I was there"* are not reasons; they are churn with better
@@ -43,6 +52,7 @@ stage: 1 Docs study — gate auto — verdict pass — 2026-08-10T11:31Z
 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)
 ```
 
 The last two lines are a **trip**: the same file, two consecutive passes, the same