task-pipeline-skill 1.97.1 → 1.99.0

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

@@ -75,6 +75,22 @@ act. **Step 11 runs stage 8's verification trio** on what was released. Steps 12
 with stage 10. No gate in [`stages.md`](stages.md) is skipped. The cycle changes when each
 stage runs, and over what.
 
+**Before each cycle, check for parallel work on the same nodes.** In every target repository,
+list the open PRs and the recently merged ones by branch prefix. Include other CLIs' prefixes,
+such as `codex/`, `fix/` and `release/`, and do not stop at your own tool's live sessions:
+
+```bash
+gh pr list -R <owner>/<repo> --state open   --json number,headRefName,title
+gh pr list -R <owner>/<repo> --state merged -L 20 --json number,headRefName,mergedAt
+```
+
+Each node has one owner. When work has to be split, record the split on the PR you would
+otherwise collide with. *A lesson of release iteration 1 (2026-10-13): fix PRs from other
+tools' branches landed on nodes a fix cycle was rebuilding, and a later cycle was briefed on
+a PR that had already merged. Source: the iteration's run record, which is private, and
+[task-pipeline#125](https://github.com/ssheleg/task-pipeline/pull/125), which carries the
+rule.*
+
 ## Module dossiers
 
 **One dossier per cluster.** The inventory is grouped by the part of the system each item
@@ -159,28 +175,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.
 
@@ -262,13 +275,152 @@ private to its project and never leaves it.
 **Layer 1 — every install, no service.** The project retro and [`learned.md`](learned.md),
 as before, plus a **local index** of every project's lessons on this machine:
 `scripts/lessons.py`, one JSON line per class, a pure function of the retros
-(`lessons.py rebuild --roots <dir>` re-derives it). Rebuild replaces the projection for
-its explicitly selected roots and depth: choose the whole intended scope. A readable empty
-scope can produce an empty index; a missing or unreadable root, discovery error, malformed
-artifact configuration, missing explicitly configured artifact directory, dangling source
-link, nonregular retro input, or invalid/unresolved lesson refuses before changing the index
-or its migration state. An absent default artifact directory in a new repository remains
-a valid empty source. Repair the named source and retry; unknown is never measured zero.
+(`lessons.py rebuild --roots <dir>` re-derives it). **A rebuild never removes or moves
+anything on its own.** It derives every lesson from the retros it can read under the roots and
+depth given, and from every git worktree of each checkout it finds. Worktrees under
+`.worktrees/` or `.claude/worktrees/` are included, even though the walk skips
+dot-directories.
+
+An origin is one project's copy of a lesson, `(project, retro)`. It records its
+**provenance**: the checkouts it was derived from, by real path. That record stays in the
+local index; it is never emitted, and `show` omits it. Provenance decides only the reason an
+origin is carried, never a removal.
+
+**Every previous origin the run does not re-derive is carried.** Nothing is removed and nothing
+is moved: no origin is dropped because a checkout read its retro and no longer found the entry,
+and no memory id moves to another project's origin. **`rebuild --prune-carried` is the only way
+an origin leaves the index**. `--prune-carried-reason <reason>` narrows it to one reason. It
+needs `--prune-carried`, and it offers only the reasons listed below; anything else is a usage
+error, exit 2. A
+carried origin keeps everything recorded on it, including its memory id, and is marked
+`carried: <reason>`, named in the summary. It is re-derived and un-marked as soon as a checkout
+holding it reads again. One thing is re-keyed rather than carried, on positive evidence only:
+an origin written before provenance existed (v1.95.0 keyed a project on the smallest root
+commit of HEAD) whose `retro#anchor`, under the same class key, this run re-derives under
+exactly one other key, and in the checkout that re-derived it: its own commit resolves there,
+v1.95.0 would have computed exactly its key there, and the commit descends from the root the new
+key names (its own history, not a history the repository merged). It is the same repository, so
+it takes the new key and its memory id follows; `add` does the same for its own checkout. It is
+never re-keyed when it has provenance, when its project key is held by any checkout read this
+run or by any origin of the previous index that has provenance (so the verb and the roots
+given never decide who owns an id), when two keys could claim it, or when the copy under the new key holds a different memory
+id (then it stays carried, and that is named). A monorepo that merged another repository's
+history therefore never takes that repository's origin.
+
+A re-key can only judge the projects already seen, so ownership is made recoverable: the
+re-keyed origin records its source key as `rekeyedFrom`. The first time that project is read
+with an origin of the same class key (by `add` or `rebuild`), or records the id itself, it
+takes the id back; the other origin keeps its place without it, and a `reclaimed:` line says
+so. Read means an origin with provenance that is not carried: a v1.95.0 origin under that key
+that could not be re-keyed is not a read, so the run that re-keys never hands the id back to
+it. Whichever verb runs first, the final owner is the project whose key the legacy store used,
+once that project is read. If that project already holds its own id for the class, nothing
+moves, and that is named. An origin that loses its id to the one-project or the one-class rule
+loses `rekeyedFrom` with it, so does an origin `record --replace` gives another id, and a
+re-key records a source only for an id it moved from the legacy origin; and no verb writes an index line the loader would refuse: `save`
+refuses instead, the previous index intact. The reasons are:
+
+- `checkout not read`: the checkout was not discovered, or a problem is owned by it. That
+  problem may be an unreadable retro, a refused `git worktree list`, a shallow clone, a broken
+  configuration, or a retro that changed while the rebuild ran (an `add` landing mid-run).
+- `retro file not read`: the checkout read completely, but that file was not read, for
+  example because it lies outside the artifact root or was moved.
+- `no checkout read holds it`: the checkout read the file, holds the same project, and the
+  entry is no longer there.
+- `commit does not resolve`, `retro cites a commit that does not resolve` or
+  `lesson refused`: the entry is there but could not be derived. A dangling commit is routine
+  after a squash merge and a deleted branch.
+- `no provenance`: the origin was written before provenance existed, and no re-derived origin
+  proves it is the same repository's.
+- `checkout holds another project`: every checkout in its provenance now holds a different
+  project key, and the origin's own commit does not resolve there. A path is not an identity.
+  The same repository under another key still holds the commit, so it is not a stranger;
+  `add` applies the same rule to its own checkout's old-key origin.
+
+The project key is the repository's own: the first-parent root of its default branch
+(`origin/HEAD`, then `main`, then `master`, then the branch `init.defaultBranch` names).
+Without any of them it is the main worktree's HEAD, read in the common directory, so every
+worktree gets one answer; then this checkout's HEAD. It is computed once per git common directory. A worktree on a branch that merged an unrelated history, or a
+checkout sitting on an orphan `gh-pages` branch, is still its project.
+
+**Counting.** `seen`, `projects` and `status` count re-derived origins and every carried origin
+except `checkout holds another project`. Those are kept, with their memory ids, but not counted.
+So a temporarily unreadable root never demotes a lesson two projects hold, and a stranger at a
+path, or one checkout under a new root commit, never makes a phantom second project. Derived
+fields are recomputed from the origins whenever the index is read; they are never trusted from
+disk.
+
+**Shallow clones.** A shallow checkout is never a source. It is a problem owned by that
+checkout, nothing is derived from it under its unstable key, and its origins are carried as
+`checkout not read`. A shallow check that does not answer is refused the same way, and since
+it taught nothing, it does not count as something read. `add`, `emit-observatory` and
+`record` refuse in a shallow clone, exit 1 and write nothing, and say to deepen it with
+`git fetch --unshallow`.
+
+**Known limit.** A project whose root commit changes, through a re-init or an unshallow, starts
+new store records: its old origins are carried as `checkout holds another project` with their
+memory ids, and the new origins start without one. The operator re-attaches by running
+`record` with the old id on the new origin, from the same checkout. That is allowed, because
+the new origin is of the same class key and the origin holding the id is carried as `checkout
+holds another project` with this checkout in its provenance. From any other checkout it is
+refused.
+
+Another checkout of the same project, even one reading the same retro path, decides nothing
+for an origin it never held. Problems carry their owner, a checkout or none, and are never
+matched by path prefix.
+
+**Memory ids.** A memory id belongs to `(project, classKey)`, the store's own identity, and
+never to a retro anchor:
+
+- A rotated or retitled entry keeps its id on the re-derived origin. The old anchor is carried.
+- A class key changed inside one entry does not inherit another key's id.
+- One id is one `(project, classKey)`. `record` refuses each of the following, exits 1 and
+  writes nothing:
+  - an id that another class key holds;
+  - an id that another project's origin holds (the refusal names that project), unless that
+    origin is carried as `checkout holds another project` and this checkout is in its
+    provenance (the re-attach above);
+  - a revision older than the one held;
+  - without `--replace`, a different id over the one the origin already holds.
+
+  It also refuses an id the index cannot hold, such as `mem:`, a quote, a backslash or a
+  space: that exits 2.
+- One id is one project's store record. Two projects may hold it only while one of them is
+  carried as `checkout holds another project`. When a rebuild would leave it on two live
+  projects (that checkout came back), the id stays on the earlier holder: the project the
+  previous index carried as `checkout holds another project` with it, else the smaller project
+  key. The other origin keeps its place without the id, and the run names it. `add` applies the
+  same rule against the index as it read it, so an add from an old clone never leaves the id on
+  both projects either.
+- Merged duplicate lines name every id they drop. Of two copies of one origin the higher
+  revision wins; on equal revisions, the lexically smaller id.
+- Ids compare on the part before `@`, revisions start at 1, and the highest revision wins.
+
+`emit-observatory` and `record` both use the origin of the project that holds the id. The run
+refuses to write if a memory id would vanish other than through `--prune-carried`.
+
+Unreadable sources are named under `not read`, by name rather than by absolute path. Every
+root, checkout, repository top, file given and directory is shown by its name — the index files
+home-relative, such as `~/.sshlg-skills/lessons/index.jsonl` — in every verb's messages, on stdout
+and stderr alike (the session's notes and a refusal too). `path` alone prints the path: that is
+its answer. A git question about one commit in one checkout is asked once per run. Only absolute paths are replaced, and only as whole
+path components, so a root given as `.` changes no other text. The index is split on `\n` only, and
+lesson/1 text refuses every line separator, including U+2028, U+2029 and U+0085. So no value
+can make a good index read as corrupt. The run
+exits 0 whenever anything was read: a retro, a checkout discovered in full, or a shallow
+checkout found. A readable root that holds no checkout also exits 0: the index is written,
+and every origin is carried. The run exits 1 only when nothing could be read because every
+root was missing or unreadable; then no index, lock directory or migration is touched. A held
+lock or an unreadable index is its own refusal. On the default path the one-time merge of a
+standalone index runs first, as for every verb.
+
+So does setting a corrupt index aside:
+- The file is kept whole as `.corrupt-<date>`.
+- Every line that still parses is salvaged into the live index.
+- Two lines for one class key are merged.
+- A memory id that only a bad line held is named in the output.
+
+Unknown is never measured zero, and never measured gone.
 Two projects holding one class key make
 one lesson seen twice, status `candidate`. The index path is a parameter — `--index`, then
 `$TASK_PIPELINE_LESSONS`, then `~/.sshlg-skills/lessons/index.jsonl` **when
@@ -293,7 +445,8 @@ rule 2 (no host identifiers) for exactly two fields, and nothing else:
   repository's SHA names nothing to someone without the clone; **a public repository's SHA
   is searchable** and leads to the repository, so it stays in this field and never in text;
 - **`origin.project`, the pseudonymous project key** — `p-` and 12 hex digits of the
-  repository's root commit — stable across clones and never the repository's name, because
+  repository's root commit (the first-parent root of its default branch, so every worktree
+  and branch of one repository shares it) — stable across clones and never the repository's name, because
   lessons are read into *other* projects' briefs and a repository name can be a customer's
   or a product's. The shared store receives the same key, never a `project:<slug>` id.
 
@@ -301,7 +454,10 @@ Rules 1, 3, 4 and 5 still bind every text field, on the estate as off it: no pat
 no code or value, no person's, company's, customer's or product's name, and a title that
 states the class rather than the incident. Never, in either layer, a transcript or a URL.
 `lessons.py` refuses what a pattern can see (paths, URLs, addresses, credential shapes, long
-hex or base64 runs) and any field lesson/1 does not name; a name it cannot see stays the
+hex or base64 runs, line breaks) in every text field and in a stage id given as a string (at
+most 32 characters, never blank), and any field lesson/1 does not name. A stage id an older
+index holds that fails those checks is normalised when the index is read (one line, cut to 32
+characters, or `stage`), and said, so the line and its memory id are never set aside; a name it cannot see stays the
 writer's duty. Off the estate (`retro.publish`) the relaxation ends: the whole origin is
 stripped.
 
@@ -384,7 +540,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
@@ -430,7 +476,8 @@ private to this project.
 **A lesson is not a publication, but the redaction list below binds it too — with one
 relaxation.** On this machine or estate (the local index, a shared store), rule 2 is relaxed
 for exactly two fields: the evidence commit and the pseudonymous project key (`p-` and 12 hex
-of the root commit, the same key in the store, never the repository's name or a
+of the root commit — the first-parent root of the default branch — the same key in the store,
+never the repository's name or a
 `project:<slug>` id). A private repository's SHA names nothing; a public repository's SHA is
 searchable, so it stays in its field and never in text. Rules 1, 3, 4 and 5 still bind every
 text field: no path at all, no code or value, no person's, company's, customer's or

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

@@ -18,7 +18,7 @@ Writing the approved design down so a zero-context implementer — human or suba
 - Module dossier — when the run is one brick of a platform
 - Self-review — before showing it
 - Locked contracts are decisions — the register, not only the spec
-- GATE (manual)
+- GATE (auto)
 
 ## Order of operations
 
@@ -280,13 +280,14 @@ spec section instead of restating the reasoning there.
 and the next one supersedes it; an id survives. If this stage settled something and
 no entry names it, the run has agreed to decide it again later.
 
-## GATE (manual)
+## GATE (auto)
 
 > "Spec written and committed to `<path>`. Review it and tell me if anything should
 > change before I write the implementation plan."
 
-Wait for the operator. Changes requested → apply, re-run the self-review, ask
-again.
+Where the brief records a standing authorization (the default gate is `auto` since
+1.98.0), an independent reader reviews the spec and the run continues; otherwise wait
+for the operator. Changes requested → apply, re-run the self-review, and review again.
 
 The gate is not only the operator's word: **every section carries `covers: REQ-…`
 and every REQ in the brief appears in at least one section.** For UI tasks it