task-pipeline-skill 1.97.1 → 1.98.0

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

@@ -160,13 +160,20 @@
         "finish": {
           "type": "object",
           "additionalProperties": false,
-          "description": "The iteration's budget at its finish line. Absent, the defaults hold: 3 rounds and 2 releases. A round is every exit check once plus one independent reading over the scope; only new blocking findings count. Reaching either budget before done — a blocker open, or the second clean round still owed — stops the iteration and hands it back; no round runs past it without the operator's go, given with the numbers. Doctrine: references/finish-line.md; verdict: scripts/waves.py finish.",
+          "description": "The iteration's budget at its finish line. Absent, the defaults hold: 3 rounds and 2 releases. A round is every exit check once plus one independent reading over the scope; only new blocking findings count. Reaching either budget before done — a blocker open, or a clean round still owed — stops the iteration and hands it back; no round runs past it without the operator's go, given with the numbers. Doctrine: references/finish-line.md; verdict: scripts/waves.py finish.",
           "properties": {
             "maxRounds": {
               "type": "integer",
-              "minimum": 2,
+              "minimum": 1,
               "default": 3,
-              "description": "Finish-line rounds per iteration, at least 2: done needs two consecutive rounds with no new blocking finding. Rotating the audit axis happens inside this budget and never adds a round."
+              "description": "Finish-line rounds per iteration, at least cleanRounds: done needs that many consecutive rounds with no new blocking finding. Rotating the audit axis happens inside this budget and never adds a round."
+            },
+            "cleanRounds": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 2,
+              "default": 1,
+              "description": "Consecutive rounds with no new blocking finding that end the iteration: 1, or 2 when it carries an R3 or flagship node (since 1.98.0; two for every iteration was the default before). Passed to waves.py finish as --clean-rounds."
             },
             "maxReleases": {
               "type": "integer",

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

@@ -20,7 +20,7 @@ requirement.** It is what turns the pipeline from a funnel into a circle.
 - 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)
+- GATE (auto)
 - When the answer is "something's missing"
 - A project of several repositories
 
@@ -329,7 +329,7 @@ client write on the other — the table says so under `unlooked` rather than sho
 green rows. Two green halves reporting a working whole is exactly the shape this file
 spends its length refusing.
 
-## GATE (manual)
+## GATE (auto)
 
 > **Acceptance policy `AP-1` · owner: the operator of the project running this pipeline ·
 > in force since 2026-08-20 · supersedes: the unversioned ladder that stood before it.**

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

@@ -22,7 +22,7 @@ approved design — not at code.
 - UI detection — a required output
 - The approved design is a set of decisions — record them
 - User paths are a design output, not a spec detail
-- GATE (manual)
+- GATE (auto)
 - Rationalizations
 
 ## The hard gate
@@ -139,9 +139,9 @@ Feed them into [`spec.md`](spec.md)'s UX track — super-ux turns them into flow
 screens and traced scenarios. **Do not draft scenario IDs here**; that is the
 chain's job, and two sources for one scenario is worse than one.
 
-## GATE (manual)
+## GATE (auto)
 
-The operator approves the design, **the UI verdict is recorded**, and — where that verdict is *yes* — **the paths, the states and the error paths are named** (above) rather than deferred to the spec. **Every REQ in the brief is answered by the design** — a requirement the design doesn't address
+The design is approved (the operator's go, or the standing authorization recorded in the brief; `auto` by default since 1.98.0), **the UI verdict is recorded**, and — where that verdict is *yes* — **the paths, the states and the error paths are named** (above) rather than deferred to the spec. **Every REQ in the brief is answered by the design** — a requirement the design doesn't address
 is either covered now or explicitly dropped by the operator, with the drop written
 into the carry-over ledger. For a platform, the module map
 ([`decomposition.md`](decomposition.md)) is committed and approved as part of this

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

@@ -176,7 +176,7 @@ overall.
 - **The final whole-branch review.** If the run is on a tier below the most capable
   one available, say so and offer to run this one review there; if the operator
   declines or the tier doesn't exist, run it on the confirmed model and note it.
-- **Fix-loop rounds 4–5.** One tier above the implementer that got stuck, when the
+- **Fix-loop round 3.** One tier above the implementer that got stuck, when the
   environment has one and the override map or the operator allows it; otherwise
   say so and rely on fresh eyes alone.
 
@@ -407,7 +407,7 @@ may say what the reviewer actually saw, and a syntax lint recorded as a blind
 review is refused by `certify` by name.
 
 **The boundary with certification:** this review closes a **prose-plan task** —
-one reviewer, the five-round cap of §4.5. A **work-graph node** is closed by the
+one reviewer, the three-round cap of §4.5. A **work-graph node** is closed by the
 three blind tiers and `graph.py certify` instead
 ([`certification.md`](certification.md), ceiling 3); the artifact the queue is —
 plan or graph — decides which protocol closes the work, never whichever is
@@ -444,7 +444,7 @@ Two routes leave before the loop starts:
   without asking.
 
 Everything else loops. One round = one fix dispatch + one scoped re-review.
-**Five rounds maximum per task.**
+**Three rounds maximum per task**, then the open findings become blocker rows and the run moves on.
 
 **The loop guard runs alongside the counter** ([`loop-guard.md`](loop-guard.md)):
 log every repeat touch (`touch: <file> — round N — reason: <finding id>`) and trip
@@ -453,13 +453,13 @@ the same reason, or when a finding already ADDRESSED reappears. A tripped guard
 not another round: stop, name the two shapes, escalate to the layer that owns the
 conflict, then re-check in a planned order.
 
-- **Rounds 1–3:** resume the original implementer with the open findings verbatim —
+- **Rounds 1–2:** resume the original implementer with the open findings verbatim —
   its context is intact. If the harness can't message a live subagent, dispatch a
   fresh one with the brief path, the report path and the findings; the report file
   is the persistent memory either way.
-- **Rounds 4–5:** fresh implementer, one tier up if available, framed as: "a prior
+- **Round 3:** fresh implementer, one tier up if available, framed as: "a prior
   implementer attempted this task N times; you own it now — read the report file
-  for what was tried." A loop that survives three resumes usually means the
+  for what was tried." A loop that survives two resumes usually means the
   implementer can't see its own problem.
 - **Every round:** the implementer fixes, re-runs the tests covering the amended
   code, appends its fix report to the same report file, returns the short contract.
@@ -471,7 +471,7 @@ conflict, then re-check in a planned order.
   breakage joins the open list; out-of-scope observations go to the ledger as
   deferred minors — they never extend the loop.
 - **Ledger, every round:**
-  `Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <one-liners>; commits <a7>..<b7>)`
+  `Task <N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a7>..<b7>)`
 
 **In a subagent run, never fix findings yourself in the controller session** —
 controller fixes skip review and pollute the context you need for coordination. In a

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

@@ -2,12 +2,15 @@
 
 A node is not closed by one agent's opinion. It is closed by **three independent
 readings at escalating visibility**, and the run may not advance until all three
-pass.
+pass. **The cost follows the risk** (since 1.98.0): an **R1** node certifies with **one**
+blind tier (`unit` by default; `graph.py certify` accepts any one of the three), and a
+clean round ends a node unless it is **R3 or a flagship surface** (*Rounds owed by risk
+class*, below).
 
 **The boundary: this closes a node of the work graph.** Where the queue is a
 prose plan rather than a graph, a task closes through the per-task review instead
 ([`build.md`](build.md) §4.4 and [`review.md`](review.md) — one reviewer, a
-five-round fix loop with an explicit breaker). Two closure protocols with no
+three-round fix loop with an explicit breaker). Two closure protocols with no
 boundary sentence were how a run picked whichever was cheaper; the artifact the
 queue is — graph or plan — is what decides, not the mood of the closer.
 
@@ -208,14 +211,18 @@ erase the only evidence that a node is churning.
 
 The cycle is: `certify` → fail → the `breaks` findings become nodes (each already
 carrying its `check`) → fix → `certify` again, round `N+1`. Same three tiers, same
-blind dispatch. A tier that passed in an earlier round is **re-run**, because the
-fix is a new change and the level it passed on is not the level it now faces.
-
-**At the ceiling the gate measures rather than stops** —
-[`loop-guard.md`](loop-guard.md). `--ceiling` defaults to 3. At or over it, `certify`
-still runs and still reports the tiers; what it adds is the name of the tier that
-has failed **every** round. A run spinning on one level needs the operator to see
-*which* level:
+blind dispatch. A tier that passed in an earlier round is **re-run** after a fix,
+because the fix is a new change. **It is never re-run on unchanged input:** `certify`
+records the tree each round read and refuses a round of the same kind on the same
+tree, before writing anything. A tier's second answer about a tree it already read is
+its first answer again, and asking twice is the loop.
+
+**At the ceiling the gate STOPS** ([`loop-guard.md`](loop-guard.md), since 1.98.0).
+`--ceiling` defaults to 3 failing rounds. The round that reaches it still reports the
+tiers, names the tier that has failed **every** round, and then **parks the node** with
+the evidence (failing tiers, the first break and its check) as its reason, exit `7`.
+The run records a blocker row with that evidence and moves on to the next node. It
+used to measure only, and a loop that is measured is still a loop:
 
 - the same tier every round → the level is being misread, or the node is the wrong
   shape. Not one fix away. Re-plan the node, do not attempt another failing round. (An R3
@@ -227,30 +234,29 @@ has failed **every** round. A run spinning on one level needs the operator to se
 
 In a release iteration a node carries `risk` (R1–R3, [`work-graph.md`](work-graph.md);
 [`iteration.md`](iteration.md) → *Verification starts when a node lands*), and the class
-decides how many **passing** rounds the node owes before `close` accepts it: **R1 one, R2
-two, R3 three, of which one is adversarial.** A round is the three blind tiers (four on a
-flagship or product surface) plus one fix cycle. `graph.py certify` prints `round N: k of M
-owed passing rounds — not closable yet` until the count is met (`k of M owed passing rounds —
-closable` once it is), and `graph.py close` refuses
-the verdict until then. **Only passing rounds count** — a round passes when every tier
-passes, read from `certification.history` — and, for R3, one of the passing rounds must be
-one recorded with `--kind adversarial`
-(`certification.kinds`, one entry per round). A node with a `risk` and no certification at
-all is refused by `close` too: its class owes at least one round.
+decides how many **passing** rounds the node owes before `close` accepts it: **R1 one
+(with one blind tier), R2 one, R3 two, of which one is adversarial.** A node on a
+**flagship** surface owes two as well, one of them adversarial, whatever its class. A
+round is the blind tiers the class owes (three; four on a flagship or product surface;
+one on R1) plus one fix cycle. `graph.py certify` prints `round N: k of M owed passing
+rounds — not closable yet` until the count is met (`k of M owed passing rounds —
+closable` once it is), and `graph.py close` refuses the verdict until then. **Only
+passing rounds count**, read from `certification.history`, and for R3 or a flagship one
+of them must be recorded with `--kind adversarial` (`certification.kinds`). A node with
+a `risk` and no certification at all is refused by `close` too. R2 owed two blind
+rounds until 1.98.0, and a clean round did not cancel the next: the second reading of
+an unchanged diff found nothing it had not already been asked.
 
 **What a round after a clean round reads.** The node's **whole diff at the new HEAD** — not
-the fix diff alone, and not the previous round's reports. A clean round proves the tree it
-read; the next owed round asks the same three distances again of the whole change as it
-stands, so a defect the first reading accepted has a second chance to be seen from a fresh
-context.
-
-**Owed rounds and the ceiling are different counts.** `--ceiling` measures churn: how many
-rounds a node has *failed*, and which tier keeps failing. An R3 node that owes three rounds
-and passes them is not "at round four" of anything; its owed rounds are the plan, and the
-ceiling's warning is about failing rounds beyond what the class owes. Read the ceiling's
-output only when rounds fail.
-
-**The adversarial round** (one of R3's three, on another model where one is available):
+the fix diff alone, and not the previous round's reports. On an unchanged tree the only
+round that may follow a clean one is the other kind: the adversarial round asks a
+different question of the same change.
+
+**Owed rounds and the ceiling are different counts.** `--ceiling` counts *failing*
+rounds and stops the node at the limit; owed rounds count *passing* ones. An R3 node
+that passes its two is not near any ceiling.
+
+**The adversarial round** (one of R3's two, on another model where one is available):
 1. **Plant defects in the change** — off-by-one in a limit, an inverted check, a dropped
    error path — and require the node's own checks to fail on each. A plant that passes is a
    finding against the check, not against the plant.
@@ -261,19 +267,18 @@ output only when rounds fail.
 3. **Try the abuse cases** a caller outside the trust boundary would: inputs at and past
    every bound, replays, a revoked identity, an out-of-order sequence.
 
-It is a different question, not a stricter reading: on 2026-10-12 one iteration's third
-round on a spend-limits node found three breaks of a money invariant that two blind rounds
-had passed. Record it with `certify --kind adversarial`.
+It is a different question, not a stricter reading: on 2026-10-12 one iteration's
+adversarial round on a spend-limits node found three breaks of a money invariant that two
+blind rounds had passed. That is why R3 keeps it and drops the second blind round. Record it with `certify --kind adversarial`.
 
 ## What this costs, said out loud
 
-Three agents per node instead of one — four on a flagship or product surface. That is
-the price of the visibility, and it is paid per node rather than per run. The three are dispatched in parallel, so the
-wall-clock cost is roughly one reading; the token cost is three. A node whose
-`check` is mechanical and whose blast radius is genuinely nil still pays it — and a
-tier with nothing to find says so in `scope` and `not_examined` rather than being
-skipped, because **a skipped level and a clean level are indistinguishable
-afterwards**, and only one of them is evidence.
+Three agents per node instead of one, four on a flagship or product surface, one on R1.
+The tiers are dispatched in parallel, so the wall-clock cost is roughly one reading and
+the token cost is the tier count. Where a tier runs and finds nothing it says so in
+`scope` and `not_examined`, because **a skipped level and a clean level are
+indistinguishable afterwards**. What the class does not owe is not run: an R1 node's
+second and third tiers are not skipped levels, they are levels its risk never reached.
 
 ## Rationalizations
 
@@ -281,5 +286,5 @@ afterwards**, and only one of them is evidence.
 |---|---|
 | «All three would say the same thing» | Then all three say it, at a cost you already know, and the run has three signatures instead of one guess about what the other two would have found |
 | «The seam tier can read the unit report first — it saves tokens» | It saves tokens by removing the second opinion. The reports are cheap; the independence is the product |
-| «Tier 3 passed last round, skip it» | The fix is a new change. A tier's pass is about the tree it read, and that tree moved |
-| «Round 4 will get it» | Read the ceiling's output. The same tier failing three times is a planning defect wearing a verification failure's clothes |
+| «Tier 3 passed last round, skip it» | The fix is a new change. A tier's pass is about the tree it read, and that tree moved. On an unchanged tree the round is refused instead |
+| «Round 4 will get it» | There is no round 4: the ceiling parks the node with its evidence. The same tier failing three times is a planning defect wearing a verification failure's clothes |

package/plugins/task-pipeline/skills/task-pipeline/references/doctrine-map.md

@@ -49,7 +49,7 @@ Custom profiles use their own declared stages and doctrine, with the kernel inta
 | 3 Spec | `references/spec.md` |
 | 4 Plan | `references/planning.md` |
 | the queue the loop walks | `references/work-graph.md` |
-| 5–8 · how a **work-graph node** is CLOSED — three blind readings at three distances, all three required, plus a fourth `visual` reading on a flagship or product surface (ceiling 3); a **prose-plan task** closes through `review.md` instead — one reviewer, five-round cap | `references/certification.md` |
+| 5–8 · how a **work-graph node** is CLOSED — three blind readings at three distances, all three required, plus a fourth `visual` reading on a flagship or product surface (ceiling 3); a **prose-plan task** closes through `review.md` instead — one reviewer, three-round cap | `references/certification.md` |
 | 5 Build (worktree, subagents, fix loop) | `references/build.md` + `references/review.md` |
 | 5–6 TDD + suite gate | `references/tdd.md` |
 | 5, 6, 8 The browser — the look, the spec suite, and the difference | `references/browser.md` |

package/plugins/task-pipeline/skills/task-pipeline/references/finish-line.md

@@ -25,7 +25,8 @@ fields, written at stage 0 and confirmed with the brief:
   released, installed or deployed. A branch is not that artefact.
 - **Scope** — the modules, paths and REQ ids this iteration may change, as a list.
 - **Budget** — `run.finish.maxRounds` (default 3) and `run.finish.maxReleases` (default 2),
-  from `pipeline.json` ([`../pipeline.schema.json`](../pipeline.schema.json)).
+  from `pipeline.json` ([`../pipeline.schema.json`](../pipeline.schema.json)), and
+  `run.finish.cleanRounds`: 1, or 2 when the iteration carries an R3 or flagship node.
 - **Base** — the commit the iteration started from.
 
 Widening the scope is a recorded revision of the brief, with the operator's go. A finding is
@@ -71,12 +72,15 @@ A **round** is every exit check run once, plus one independent reading over the
 audit axis, an observer, or the post-release readback. Rotating the axis
 ([`audit.md`](audit.md)) never adds a round. Only new blocking findings count.
 
-- **Done** — every exit check green on the artefact, and two consecutive rounds with no new
-  blocking finding. The second of them may read only the last fix's diff.
+- **Done** — every exit check green on the artefact, and one round with no new blocking
+  finding; two consecutive ones when the iteration carries an R3 or flagship node, the
+  second of which may read only the last fix's diff. Two for every iteration was the
+  default until 1.98.0, and a clean round that changed nothing bought a second reading
+  of the same tree.
 - **Diverging** — new blocking findings did not fall from one round to the next, or
   self-inflicted ≥ new. Run [`loop-guard.md`](loop-guard.md)'s break protocol.
 - **Budget spent** — `maxRounds` or `maxReleases` reached before done: a blocker open, or the
-  second clean round still owed. Stop and hand the iteration back: each open blocker becomes a
+  clean round still owed. Stop and hand the iteration back: each open blocker becomes a
   top board row marked `needs-operator`. No round runs past the budget without the operator's
   go, given with the numbers; a done reached past it without that go is still `budget`.
 
@@ -94,15 +98,16 @@ round: <N> — <reading> — new blocking <k>
 
 ```
 python3 scripts/waves.py finish --inventory <inventory.json> --ledger .task-pipeline/run.md \
-  --max-rounds 3 --max-releases 2 --releases <n> --checks <k>/<m> --artefact <name>@<sha>
+  --max-rounds 3 --max-releases 2 --releases <n> --checks <k>/<m> --artefact <name>@<sha> \
+  [--clean-rounds 2]
 ```
 
 `--rounds N` may stand in for `--ledger`; with neither the count is unknown and the script
 refuses. Exit codes:
 
-- `0` — done: the last two rounds found no new blocking item, none is open, and every exit
-  check is green on the artefact.
-- `3` — continue: a blocker open, a second clean round owed, or no `--checks` given.
+- `0` — done: the last `--clean-rounds` rounds (1 by default) found no new blocking item,
+  none is open, and every exit check is green on the artefact.
+- `3` — continue: a blocker open, a clean round owed, or no `--checks` given.
 - `5` — budget: reached before done, or done past it without `--operator-go`.
 - `6` — blocked: diverging; run the loop guard's break protocol.
 - `1` — malformed: the inventory, the ledger or the arguments, each reason named.

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

@@ -159,28 +159,25 @@ its slowest node before checking its fastest.
 
 **The number of rounds follows the node's risk class.** The class is recorded on the node
 as `risk` (R1–R3, [`work-graph.md`](work-graph.md)), computed from what the node touches.
-It is never lowered to save time. **A round is the three blind tiers of
-[`certification.md`](certification.md) plus one fix cycle**, and the first round is always
-the full three tiers — there is no lighter first reading. The class sets how many rounds
-the node owes:
-
-| Class | Touches | Rounds |
-|---|---|---|
-| R1 | docs, config, a mechanical change, one isolated file | 1: that first round |
-| R2 | an ordinary feature or fix inside one module | 2: the first round, then a second over the fix diff with its regression tests |
-| R3 | security, cryptography, money, a data migration, a public contract, a seam across repositories, concurrency | 3, one of them recorded adversarial — a round that plants defects and tries abuse cases, on another model where one is available |
-
-- Each round's fix cycle stays inside [`loop-guard.md`](loop-guard.md)'s caps. A finding
-  that cannot be fixed in the node is parked with a board row.
-- `graph.py close` refuses a node until its owed rounds have passed, and an R3 node until
-  one of them was recorded adversarial ([`certification.md`](certification.md) → *Rounds
-  owed by risk class*, which also says what a round after a clean one reads and how the
-  adversarial round is run).
-- Every owed round runs, and every round re-runs all three tiers: a tier that passed in an
-  earlier round read a tree the fix has since moved ([`certification.md`](certification.md)
-  → a passing tier is re-run). A clean round does not cancel the next one, and only passing
-  rounds count. R3's adversarial round asks a different question — it hunts for a planted
-  defect — and always runs; it counts only when it passes.
+It is never lowered to save time. **A round is the blind tiers the class owes, plus one
+fix cycle** ([`certification.md`](certification.md)), and a clean round ends the node
+unless the class is R3 or the surface is flagship:
+
+| Class | Touches | Tiers | Rounds |
+|---|---|---|---|
+| R1 | docs, config, a mechanical change, one isolated file | one | 1 |
+| R2 | an ordinary feature or fix inside one module | three | 1 |
+| R3 | security, cryptography, money, a data migration, a public contract, a seam across repositories, concurrency | three | 2: one blind, one adversarial (plants defects, tries abuse cases, on another model where one is available) |
+
+A flagship surface owes four tiers and two rounds, one adversarial, whatever its class.
+
+- Each round's fix cycle stays inside [`loop-guard.md`](loop-guard.md)'s caps, and the
+  certification ceiling stops the node: it is parked with its evidence and a board row.
+- `graph.py close` refuses a node until its owed rounds have passed, and an R3 or
+  flagship node until one of them was recorded adversarial
+  ([`certification.md`](certification.md) → *Rounds owed by risk class*).
+- A round after a fix re-runs every tier the class owes; a round on an unchanged tree is
+  refused unless it is the other kind. Only passing rounds count.
 - Readers stay blind ([`certification.md`](certification.md) → *Blind*). Each reads the
   diff, the packet and the contract, never the builder's reasoning.
 
@@ -384,7 +381,7 @@ release run performs, not unrelated deployments, messages or human-only actions.
 |---|---|
 | "This bug is tiny, fix it now" | Tiny fixes are what move a seam twice. It joins the inventory, or it is one of the hotfix lane's five entries |
 | "Wait for the whole wave, then verify" | A barrier idles every finished node. Each node is certified when it lands |
-| "R3 found nothing in round 2, skip the adversarial round" | The adversarial round, in any position, asks a different question: it hunts for a planted defect. A clean blind round does not answer it |
+| "R3 found nothing in its blind round, skip the adversarial round" | The adversarial round, in any position, asks a different question: it hunts for a planted defect. A clean blind round does not answer it |
 | "Ask the operator now, it is quick" | Each question is a human round. Queue it and take another node |
 | "The agent hit a rate limit, start it again" | Resume it with its context. Relaunching pays for the same reading twice |
 | "No Observatory here, so no learning loop" | The project retro and learned.md are the loop's first layer, and every install has them |

package/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md

@@ -51,7 +51,7 @@ makes the grill's answers *checkable* instead of merely confident.
 | 4b | **The task register, for its *state*** | `docs/ROADMAP.md`, a board, a backlog, the tracker `CLAUDE.md` names | **what is open right now** — read with a command, never from memory; see *Carried-in claims* |
 | 5 | **Product/UX docs** | `docs/ux/` (super-ux chain), `README`, runbooks | user-facing behavior that is already specified |
 | 6 | **Pipeline history** | `<artifacts>/specs/`, `plans/`, past `-carryover.md` | what a previous run of this pipeline decided or deferred |
-| 7 | **The retro, in force** | `<artifacts>/retro.md` ([`retrospective.md`](retrospective.md)) | what previous runs got wrong here — **read in full**: standing instructions (capped at ten) and run stamps (one line each), both bounded by construction; the *Recent log* is **queried** by the task's nouns, like the archive — nothing caps it |
+| 7 | **The retro, in force** | `<artifacts>/retro.md` ([`retrospective.md`](retrospective.md)) | what previous runs got wrong here — **read in full**: standing instructions (capped at ten) and run stamps (one line each), both under the floor's 12 000-byte budget, whose bytes and bytes/4 tokens `scripts/retro_budget.py check` prints into this row; the *Recent log* is **queried** by the task's nouns, like the archive — nothing caps it |
 | 7a | **The retro archive** | `<artifacts>/retro/YYYY-QN.md` | *have we been bitten by this class before?* — **queried** by the task's nouns, never read end to end |
 | 7b | **Lessons from other projects** | the local index every install has (`scripts/lessons.py query`), and a shared lesson store only where the session lists one — an Observatory — detected by its tools, never by a path ([`iteration.md`](iteration.md) → *The learning loop*, the read recipe) | *what did other projects' agents learn about this class?* — **queried** by the task's 3–6 nouns, at most ten lines from both; a lesson that fires is cited `[lesson L-…]` or `[lesson mem:…]`. The ledger names each layer's state: `local lessons: N match | absent | unavailable (no python3)`; `shared lessons: N match | 0 match (filter unknown) | unfilterable | absent`, where the first `observatory_search` call is the probe — and nothing else changes |
 | 8 | **The knowledge wiki** | see below | distilled cross-project knowledge, prior sessions, why decisions were made |
@@ -79,8 +79,10 @@ Rules for the list:
 
 `<artifacts>/retro.md` ([`retrospective.md`](retrospective.md)) is the one
 harvested source whose binding part is **read in full rather than queried**: the
-standing instructions are capped at ten precisely so that this is cheap, and the run
-stamps are one line each. Its narrative log is queried, not read — an uncapped section
+standing instructions are capped at ten rows of at most 600 characters, the run stamps
+at ten lines of at most 300, and the two together at 12 000 bytes
+([`retrospective.md`](retrospective.md) → *The floor has a byte budget*), precisely so
+that this is cheap. Its narrative log is queried, not read — an uncapped section
 inside a source that binds is how the capped part stops being read. They are what
 previous runs of this pipeline got wrong *in this project* — the rules no check
 could decide — and they bind this run.

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

@@ -58,6 +58,13 @@ to be enforced and is not is the same failure as a gate that prints `FAIL` and e
 | 30 | **A gate scoped by exclusion judges every newcomer silently** | any lint, format or check configured with an ignore list rather than an include list | scope by what it COVERS; where the tool has no such switch, assert the covered set and fail on additions, deriving the allowlist by measuring the tool's own reach | the failure message names the intruder and the remedy, because the operator meets it mid-release |
 | 31 | **A gate needs a third verdict — could not measure** | any check that can time out, lose a dependency, or run on a contended machine | distinguish *failed* from *could not measure* with different exit codes, and say which; neither is a verdict about the code | the refusal names its remedy, and a test that waits for a DURATION rather than an event is treated as a defect in the test |
 | 32 | **A test whose assertion is implied by compilation is not a test** | any test whose name promises a behaviour | delete the subject: if that is a type or import error rather than a red test, the test is decoration | removing one asks what the name PROMISED and whether anything checks it — four of five such cases here were covered elsewhere and the fifth was a real gap only visible because the name was read as a claim |
+| 33 | **Snapshot before you undo** | any `git checkout`, `git restore`, `git stash` or `reset` in a tree that may hold uncommitted work you did not write | copy the affected files first (to a dated folder, or `git diff > <file>.patch`) and restore from that copy, never from git | the run names the copy it took before the first destructive command |
+| 34 | **One answer for inputs that should differ is a broken instrument** | any shell measurement, zsh above all | quote every expansion (`"$var"`, `'*.py'`), read data from files rather than inline literals, and feed it two inputs that should answer differently | the two answers differ, or the instrument is rewritten before its answer is used |
+| 35 | **Release the tree you tested** | any tag or release | run the release workflow's own suite on the exact commit the tag will name, and select the CI run by that tag, never by branch | the run the tag triggered is green and its head SHA is the tagged commit |
+| 36 | **A fix after a passing review is unreviewed** | any change made after a review or verifier passed | re-read the delta (`git diff <reviewed>..HEAD`) before merge | the merge names the reviewed SHA and who read the delta |
+| 37 | **Call the real service once before writing its fake** | any mock, stub or fixture of an external API, CLI or service | make one real call, or read a recorded real response, and shape the fake from it | the fake cites the response it was shaped from |
+| 38 | **Close blockers yourself; park only human gates** | any blocker about to be handed back | try every route the run holds (an API, a CLI, a credential door) first; park only a sign-in, consent, payment, typed secret or recorded operator decision | every handed-back item is a human gate, listed in one block with the route that failed |
+| 39 | **Never retry an unchanged failing action** | any failed command, check or approach | change the input or the approach before trying again; after two failed approaches, change approach or record a blocker | no identical retry in the run ledger, and a third attempt names what changed |
 
 ---
 
@@ -163,6 +170,17 @@ that document is checked. This one governs a fact that crossed a **session bound
 reported as current — the case where there is no document to check, only a memory that reads like
 one.
 
+**33 to 39 · The 2026-10-20 retro audit.** Read across ~54 retrospectives from ~50
+projects, the same lessons recurred under different words, each in at least the number
+of runs given: uncommitted work overwritten by a checkout, restore or stash with no copy
+taken (17); a zsh glob or `=` left unquoted, so a command failed or a loop printed one
+count for every file (8; this release's own run hit both); a tag cut from a tree the
+release suite never ran on, or a CI run picked by branch rather than by tag (24, with
+immutable tags burned); a fix landed after the review passed and merged unread; a fake
+shaped from documentation that the real service contradicted (11); a hand-back listing
+steps the agent could have done itself (12); and the same failing action retried
+unchanged, round after round. None of them was new to the project that hit it again.
+
 ---
 
 ## The two that are not in the table, and why
@@ -214,6 +232,11 @@ answer would have exposed it in a minute.
 | any command run to establish a fact — 6 Tests · 9 Docs · 10 Acceptance · 5 review | 19 — the output asserted non-empty and shaped as expected, and **quoted** rather than concluded from, [`audit.md`](audit.md) → *Silence is not a reading*; the reviewer's half is in [`review.md`](review.md) |
 | 0 Harvest · 10 Acceptance | 20 — the **consumer** read to learn which copy ships, never the copies compared against each other, [`audit.md`](audit.md) → *Two copies, and which one wins*; asked as row `0 Duplicates` of [`grill.md`](grill.md) → *The autonomy sweep* |
 | 10 Retro · **any gate or check you order** | 21 — each input traced to the step that writes it, and that step proven upstream, [`retrospective.md`](retrospective.md) → *Stamp first, then prune, then write* |
+| any stage · a destructive git command · a shell measurement | 33, 34 |
+| 7 Release · 5 Dev after review | 35, 36 |
+| 5 Dev · 6 Tests · a fake of an external service | 37 |
+| 10 Acceptance · the hand-back | 38 |
+| every stage · any retry | 39, [`loop-guard.md`](loop-guard.md) |
 
 **This file is the shipped list; a project keeps its own.** Every rule in the table
 above was earned on someone else's build and travels with the skill. The lessons *your*
@@ -276,7 +299,7 @@ evidence that something left, and the log below says what.
 
 ### Retired
 
-**Numbers issued so far: 32.** This is the high-water mark, and it is the only number
+**Numbers issued so far: 39.** This is the high-water mark, and it is the only number
 this file states about itself — deliberately, because the gap that proves a rule left
 cannot be computed from the table alone: **deleting the highest-numbered rule shrinks
 the maximum with it, and no gap ever opens.** That false negative shipped in the first

package/plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md

@@ -22,7 +22,7 @@ searches.
 
 - Bookkeeping — the thing that makes detection mechanical
 - Detection — any one of these trips the guard
-- The review loop — a cap that measures rather than stops
+- The review loop: a cap that stops, and says why
 - The re-render loop — a budget of one, two at most
 - The break protocol
 - When to stop and hand back
@@ -66,12 +66,20 @@ stage's gate — which is the whole difference between a rule and a rule that ru
    loop (another task, another module) already closed in this run — two owners for
    one file.
 
-Caps that trip the guard by themselves: **5 fix rounds** per task
+Caps that trip the guard by themselves: **3 fix rounds** per task
 ([`build.md`](build.md)), **2 re-entries** per stage per artifact, **3 passes** per
-module in the program loop, and **3 review rounds** per artifact — which is not a stop
-but a measurement, below.
+module in the program loop, **3 review rounds** per artifact, and **3 failing
+certification rounds** per node ([`certification.md`](certification.md)). Each one
+**stops**: the remaining findings become blocker rows with their evidence and the run
+moves on (since 1.98.0; the review cap used to measure only).
 
-## The review loop — a cap that measures rather than stops
+**Two rules hold under every cap.** Never retry an unchanged failing action: the same
+command on the same input gives the same answer, so a retry is a loop with no
+information in it. After two failed approaches to one problem, change the approach or
+record a blocker; a third attempt of the same shape is the loop this file exists to
+end ([`learned.md`](learned.md) rule 39).
+
+## The review loop: a cap that stops, and says why
 
 The caps above govern loops that **edit**. A review loop does both: the reader finds,
 the run fixes, the reader reads again. It had no cap at all until 2026-08-10, and this
@@ -98,8 +106,10 @@ review cap reached — 3 rounds — artifact: test/validate.py
 - **Self-inflicted ≥ new** — the axis is exhausted ([`audit.md`](audit.md) → *Every
   pass changes the axis*). Stop. Every remaining finding becomes a board row with its
   evidence ([`backlog.md`](backlog.md)); none is dropped.
-- **New > self-inflicted** — the reader is still paying. Continuing is then the
-  operator's call, made with the numbers in hand rather than out of fatigue.
+- **New > self-inflicted** — the reader is still paying, and the loop still stops: the
+  open findings become board rows with the numbers beside them. A further round runs
+  only on the operator's explicit request, which is read when given and never waited
+  for.
 
 At the level of a whole iteration only new **blocking** findings argue for continuing; a
 deferred or noise finding is paid for on the board, not with another round

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

@@ -18,7 +18,7 @@ justifies reading it protects one section while the file below it doubles.
 
 | Artifact | Parts | How it is read |
 |---|---|---|
-| `docs/evidence/retro.md` — **one per project** | **Standing instructions** (max **10**) · **Run stamps** (max **10**, oldest rotate out) | stage 0, **in full** — both are bounded by a **cap**, which *one line each* never was |
+| `docs/evidence/retro.md` — **one per project** | **Standing instructions** (max **10**) · **Run stamps** (max **10**, oldest rotate out) | stage 0, **in full**: both are bounded by a **cap** and, since 1.98.0, by a **byte budget** (*The floor has a byte budget*) |
 | the same file's **Recent log** | narrative entries, **uncapped by design** — the heading said *entries from the last five run stamps* until 2026-08-20 while the section held 25 going back nine days, a bound in a heading that nothing enforced | stage 0, **queried** by the task's nouns. It said *in full* until 2026-08-10, when it measured **74%** of the file: an uncapped section inside a binding source is what makes the capped part get skimmed |
 | `docs/evidence/retro/YYYY-QN.md` — the archive | every entry and every retirement ever written, append-only | **queried** by the task's nouns; never read end to end |
 
@@ -35,6 +35,8 @@ file exists to stop.
 - Never amend a commit a record already names
 - A release stamp names the TAG, and the merge commit — never the branch's own SHA
 - The stamp table is capped at ten, and *one line per run* was never a cap
+- The floor has a byte budget
+- Before a standing row: search, cite, send upstream
 - `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
@@ -66,8 +68,16 @@ Required fields, and none of them is optional:
 | **Root cause** | why the pipeline permitted it. "The agent was careless" is not a cause — it is the absence of one, and it produces no fix |
 | **Fix** | one of the three grades below |
 | **The check** | what would have caught this the first time. If the honest answer is "nothing yet", that is the fix, and it is grade 1 |
+| **Class** | one of: `exit-code`, `unwatched-check`, `release`, `collision`, `destructive-undo`, `claim-by-say-so`, `stale-doc`, `wrong-copy`, `sibling`, `truncated-output`, `shell-instrument`, `handback`, `loop`. **Recurrence is counted by class**, so a class seen before is named as such |
+| **Cost** | what it cost: rounds, burned tags, time. An entry with no cost cannot be weighed against the check that would prevent it |
 | **Commit** | the short SHA of the change that fixed it |
 
+The classes come from the 2026-10-20 audit of ~54 retrospectives across ~50 projects,
+where the same lessons recurred under different words: a gate's exit code read through
+a pipe (≥26 runs), a check trusted before it was seen failing (≥26), a tag cut from a
+tree the release suite never ran on (≥24), a shared checkout (≥20), uncommitted work
+overwritten (≥17). Words hid the recurrence; a class key makes it a count.
+
 ## Every lesson carries its commit
 
 A standing instruction carries **two** SHAs — `Commit` (the change that introduced
@@ -177,6 +187,38 @@ 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.
 
+## The floor has a byte budget
+
+A cap of ten rows never bounded their **size**. Measured 2026-10-20 across ~50
+projects, the floor stage 0 reads in full (standing instructions plus run stamps) ran
+from ~3k to **~76k tokens**; one floor was 304 KB, and this repository's own was
+27 620 bytes. A row that carries its incident and a stamp that carries its release
+narrative are how a capped list grows anyway.
+
+- **Budget:** the floor stays under **12 000 bytes**. A standing row is at most **600
+  characters**: the rule, why (one clause), the retire-when trigger and the id; the
+  story lives in the archive. A run stamp is **one line of at most 300 characters**.
+- **Stage 0 prints it:** `python3 scripts/retro_budget.py check` gives the floor's bytes
+  and bytes/4 tokens, beside the source ledger's retro row.
+- **Gate 10 fails over budget.** Before the new entry is written, `retro_budget.py
+  migrate --write` moves the narrative (an over-long stamp's verdict, a standing row's
+  `Because`) **verbatim** into the quarter's archive, each block carrying the sha256 of
+  its text, and leaves a pointer; `retro_budget.py verify` proves every pointer. An
+  instruction still over 600 characters after its story moved is rewritten by hand.
+- **A prune that retires nothing writes its count into the stamp row**, as
+  `prune: 0 retired`, and no paragraph. Repeated "nothing to prune" notes were a
+  measured share of the floor.
+
+## Before a standing row: search, cite, send upstream
+
+- **Search first:** `references/learned.md` and the lesson index
+  (`scripts/lessons.py query`, by the class key and the nouns). A rule already there is
+  **cited by its number** (`learned.md` rule 22), never restated in a row.
+- **A lesson standing in two projects goes upstream in the same run:** the entry gets
+  its `**Lesson:**` line and `scripts/lessons.py add`, and a universal rule is proposed
+  for `learned.md` (*Publishing the insight*, below). Two projects holding one rule is
+  a fork nobody named.
+
 ## `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
@@ -265,6 +307,10 @@ computable, which is why it goes first:
 printf '%s · %s\n' "$(date +%F)" "$(git rev-parse --short HEAD)" >> docs/evidence/retro.md
 ```
 
+**The budget runs between the prune and the entry:** stamp, prune, `retro_budget.py
+check` (and `migrate --write` when it fails), then write. An entry written onto a floor
+already over budget is the growth the budget exists to stop.
+
 ## The prune — mandatory, and it runs after the stamp
 
 A lesson that lands in a cluttered file is a lesson nobody will reach — so the prune still runs