task-pipeline-skill 1.23.1 → 1.25.0

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## v1.25.0
+
+### One check over one number, made into a registry over the class
+
+The "compute, never restate" guard has existed since v1.5.0 and covered exactly one
+number: the count of negative self-tests, added because two living documents claimed 46
+after the suite reached 50. It stayed one check while the same class went stale in five
+more places, each fixed as an instance and none of them gating the shape:
+
+- `README.md` and `SKILL.md` described `learned.md` as *"fifteen rules"* against a table
+  of twenty-one;
+- `evals/RESULTS.md` ratcheted zero dated runs directly above a dated run, and directly
+  on top of `evals/run.py`, which computes one and had been printing it for five releases;
+- `docs/DOCMAP.md` claimed two standing instructions against the retro's four;
+- the version invariant was **named** *four-way* on four surfaces while `test/validate.py`
+  enforced five;
+- `SKILL-CARD.md` counted "the 26 files under `references/`" against a directory of 28.
+
+`audit.md` says a class seen twice belongs in a script. Six instances later, the file that
+enforces that rule had not applied it to itself.
+
+**The check is now a registry.** One row per claim class, each naming the pattern that
+recognises the claim in prose, the command that computes the truth, and the incident that
+earned the row. Adding a class costs one line instead of one more bespoke block nobody
+generalises.
+
+Two limits are stated rather than implied, because both were learned the hard way this
+release:
+
+- **A quoted number is a citation, not a claim.** `evals/RESULTS.md` narrates its own
+  stale `"Dated runs recorded 0"` while explaining the incident, and the first version of
+  the registry rejected it. The exemption is a quoted span — deterministic, with no marker
+  vocabulary to grow per incident, which is the same drift this release is about.
+- **A count of an enumeration inside one sentence is not computable from outside it.**
+  `CLAUDE.md` said *"the stage list lives on nine surfaces"* above a list of ten. There is
+  no command that can check that, so it is **deleted** rather than gated, and the line now
+  says why.
+
+**Numbers are read as digits and as words.** The incident that named the second row was a
+word — `README.md` said *"fifteen rules"*, not *"15 rules"* — so a digit-only registry could
+not have caught the defect it is named after. Adding word forms immediately found **four
+live claims** the patterns had been skipping in silence: *"the ten canons"*, on four
+surfaces. All four are correct, and none of them was being checked.
+
+That correction matters more than the fix, because the first draft of this entry claimed
+every dormant class was dormant *because the number had been deleted*. For the canons class
+that was simply untrue: it was dormant because the check could not see the form the claim
+was written in. **A dormant state is a claim about the corpus, and it needs the same
+evidence as any other** — this one was plausible, unverified, and wrong.
+
+**Every class reports `ok` or `dormant` beside the verdict.** Four of six are dormant now,
+and that is measured rather than assumed: v1.23.1 and v1.24.0 deleted those numbers rather
+than correcting them, which git history confirms. A registry reporting green over classes
+it never looked at would be precisely the false success it exists to catch. It is a ratchet
+against re-introduction more than a finder of present drift, and the verdict line says so
+every run.
+
+One false positive was measured and removed before shipping: `CONTRIBUTING.md` narrates
+that its invariant list *"was eight guards behind"*, which is a **lag**, not a count of the
+suite. The pattern excludes it explicitly rather than tolerating a noisy check — a gate that
+cries wolf is switched off by the third person who hits it.
+
+## v1.24.0
+
+### A rule that reached one file, and the guard shape that let it
+
+`v1.23.0` added rule 21 — *a step that consumes what a later step produces is a deadlock*
+— and reordered the retrospective's three acts to **stamp → prune → entry**. It changed
+`references/retrospective.md`. It changed nothing else.
+
+Every other surface still taught the deadlocked *prune first* — the list is the count,
+and it was written down rather than tallied, because a tally of this fix would be the
+defect the fix is about: `SKILL.md` twice (including
+the stage-10 gate row), `references/acceptance.md` three times, `references/stages.md`
+three times, `references/companion-skills.md`, `references/knowledge-sources.md`,
+`templates/retro.md`, `templates/README.md`, `commands/task-pipeline.md`,
+`cursor/rules/task-pipeline.mdc`, `docs/DOCMAP.md`, `README.md` and this repository's own
+`CLAUDE.md`. **`SKILL.md` is what an agent loads first**, so the most-read surface of the
+shipped skill instructed the exact failure its newest rule defines.
+
+**Why every existing guard was green.** Rules 16–21 each have a bespoke check that names
+its consumer files and asserts a needle is present. That answers *"did a consumer drop its
+citation?"* — a real failure, and it catches it. It cannot answer *"does a consumer
+contradict what it cites?"*, because a contradicting consumer **keeps** its citation: the
+link resolves, the section exists, the needle is there. A pointer's validity says nothing
+about whether the two texts agree.
+
+**The new guard compares order, not presence** — and derives the expected order from
+`retrospective.md`'s own heading **at check time**, so it cannot drift from the doctrine it
+guards the way a hardcoded literal would.
+
+Four deterministic shapes, each arrived at by probing rather than by trusting a green:
+
+- an adjacent enumeration (`prune, stamp` / `prune → stamp`);
+- the `first … then` construction, with an aside allowed between;
+- a bare `… then …` sequence with no "first" at all (`prune before you add … then stamp`);
+- an **ordered list** whose items open with the acts — which needs no connector word, and
+  which the first two shapes both missed.
+
+Each of the four was found by running the check and reading the result, not by writing it
+and shipping. Two of them were blind spots in the guard's *own* first version, and one of
+those was blind to the exact wording this release introduced.
+
+**Measured before shipping** (rule 10). The obvious predicate — *both act words in one
+paragraph* — returns 32 hits on this corpus, of which 22 are false, including
+`retrospective.md`'s own correct prose. The shipped predicate returns 8, all true. A
+paragraph narrating the old order as a defect is exempt through an explicit marker list;
+`learned.md`'s rule-21 incident and `retrospective.md`'s own rationale both need it.
+
+Swept in the same change, because the class is *a claim that stopped being true*:
+`SKILL-CARD.md` still said the eval suite was **"Never executed"** and counted "the 26
+files under `references/`" against a directory holding 28.
+
 ## v1.23.1
 
 ### Four documents that had gone false, and the config this repository never wrote

package/CONTRIBUTING.md

@@ -143,10 +143,11 @@ list is a second source that goes stale on the next heading.
 A citation of the form `file.md → *Section*` is checked against the target's headings. The
 link checker proves the file resolves; only this proves the pointer is not false.
 
-**13. Numbers stated in living documents are computed, not restated.** The guard
-count in `README.md`, `SKILL-CARD.md` and `evals/RESULTS.md` is compared against the
-negative self-tests the workflow defines. CHANGELOG entries are exempt — they record
-what a past release shipped.
+**13. Numbers stated in living documents are computed, not restated.** Superseded in
+substance by **invariant 35**, which turns this single guard-count comparison into a
+registry over the class. Kept as the entry point because it is the shorter statement of
+the law and the one people look for; the mechanism, the exemptions and the scope live in
+35, and this text names no surfaces of its own so the two cannot disagree.
 
 **14. Every relative link in `README.md` resolves inside the published package.**
 `package.json` → `files[]` must ship whatever the README points at, or the link
@@ -260,7 +261,43 @@ every relative link **from the navigator's directory** — it sits one level ove
 everything it names, which is canon 4 in the file that publishes canon 4.
 *(guard: `index that has drifted from its doctrine`)*
 
-**34. Every invariant above names the guard that enforces it, and that guard exists.**This list claims to be *what the validator enforces*; it was eight guards behind when
+**34. No surface enumerates the retrospective's acts in an order that contradicts
+`references/retrospective.md`.** Rule 21 changed the order to *stamp first* in that one
+file and reached **no other surface that states it** — `SKILL.md` included, which is what
+an agent loads first. (No count here on purpose: whether it is nine, twelve or fifteen
+depends on counting files or occurrences, and this repository produced three different
+answers while writing the fix. The guard is the count.) Every per-rule guard has the same
+blind spot: it
+proves a consumer still **cites** the doctrine, and a contradicting consumer keeps its
+citation. So this one compares the **order** against the order derived from
+`retrospective.md`'s own heading at check time rather than a literal — in the shapes
+listed in the guard's own `SCOPE` comment, which is where they are enumerated so this
+list cannot go stale against them. **What the guard does not cover is written there
+too**: inflected forms, lists whose items are separated by blank lines, and any
+statement of the order that names neither act. Those are stated blind spots, not
+unnoticed ones.
+A paragraph that narrates the old order as the defect is exempt by an explicit marker
+list, not by a heuristic.
+*(guard: `enumerates the retro's acts as`)*
+
+**35. A number a living document states is compared against the command that computes
+it — from a registry, not a bespoke check.** This began as one check over one number, and
+stayed one check while the same class went stale in five more places: `learned.md`
+described as *"fifteen rules"* against a table of twenty-one, `evals/RESULTS.md` ratcheting
+zero dated runs directly above a dated run and directly on top of a tool computing one,
+`docs/DOCMAP.md` claiming two standing instructions against four, and the version invariant
+**named** *four-way* while five surfaces were enforced. Each was fixed as an instance; the
+class was never gated — `audit.md`'s own rule, unapplied to the file that enforces it.
+Adding a class is now **a row**, naming the claim pattern, the computing command and the
+incident that earned it. Two things are stated rather than implied: a **quoted** number is a
+citation of what a document said and is exempt, so a register can narrate its own drift;
+and a count of an enumeration inside one sentence is not computable from outside it, so
+those are **deleted** instead — `CLAUDE.md`'s stage-list line says so where it used to carry
+one. Every class prints `ok`/`dormant` beside the verdict, because a registry reporting
+green over classes it never looked at is the false success it exists to catch.
+*(guard: `— derive the number or delete it. This class is registered `)*
+
+**36. Every invariant above names the guard that enforces it, and that guard exists.**This list claims to be *what the validator enforces*; it was eight guards behind when
 an audit measured it. A claim of enforcement is now checked like any other claim.
 *(guard: `whose message does not appear in`)* — and a cited literal must lie inside
 a **single** string in `test/validate.py`: the check reads that file as text, so a

package/README.md

@@ -560,7 +560,9 @@ pipeline notices it is the same one.
 The last act of stage 10 is therefore a **retrospective**, written to
 `docs/superpowers/retro.md` — **one file per project, not per run**
 ([`retrospective.md`](plugins/task-pipeline/skills/task-pipeline/references/retrospective.md)).
-Every run **prunes and stamps**; only a run that *diverged* writes an entry:
+Every run **stamps and prunes** — in that order, because one retirement trigger
+counts firings across the last five run stamps and a prune ahead of the stamp reads a
+counter its own stage writes afterwards. Only a run that *diverged* writes an entry:
 symptom with evidence, the stage it surfaced at, the stage that **owned** it, the
 root cause, the fix, and the check that catches it the first time from now on.
 
@@ -572,7 +574,8 @@ root cause, the fix, and the check that catches it the first time from now on.
 | 2 — standing instruction | a rule agents read, for what no check can decide | one of ten slots, and its retirement trigger must be written at birth |
 | 3 — a note | something still being understood | expires in two runs, then it is promoted or deleted |
 
-**The prune is mandatory and runs before anything is added.** Every standing
+**The prune is mandatory, and it runs after the stamp and before anything is added.**
+Every standing
 instruction is checked against three retirement triggers — *it became a check* ·
 *every path or command it names is gone* · *it has not fired in the last five run
 stamps* — and the list is held to a **hard cap of ten**. At eleven, the oldest

package/SKILL-CARD.md

@@ -12,10 +12,10 @@ 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.23.1 |
+| **Version** | 1.25.0 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
-| **Evaluation status** | Suite authored (15 evals, 5 categories). **Never executed** — see [`evals/RESULTS.md`](evals/RESULTS.md) |
+| **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` |
 
 ## Risk-tier disclosure
 
@@ -34,8 +34,9 @@ apply.
 
 ## What to check before you trust it
 
-1. Read `SKILL.md` and the 26 files under `references/` — that is the whole
-   instruction surface, and every one is linked directly from `SKILL.md`.
+1. Read `SKILL.md` and every file under `references/` — that is the whole
+   instruction surface, and each one is linked directly from `SKILL.md`, so the
+   directory listing is the count.
 2. Read `templates/docgate.sh` before seeding it; it is the only shipped script a
    host project will run on its own repository.
 3. Run `npm run test:all` — every guard has a negative self-test that plants a
@@ -54,7 +55,9 @@ apply.
 - **Versions are pinned by git tag** and mirrored into `sshlg-skills`'s catalogue.
   Rollback is `git checkout v<previous>` or pinning the previous plugin version;
   the previous version is never deleted.
-- **Behavioural evidence is missing, not merely thin.** The structural guards prove
-  the skill is well-formed. Until `evals/RESULTS.md` carries a dated run, nothing in
-  this repository proves it *behaves* — triggers correctly, stays quiet on a
-  question, or performs the steps it documents.
+- **Behavioural evidence is thin to the point of absent.** The structural guards prove
+  the skill is well-formed. `evals/RESULTS.md` carries **one** dated run, and it was
+  self-observed by the author — an observation of instruction-following, not an
+  evaluation. **No blind run has been made on any model.** Nothing in this repository
+  yet proves the skill *behaves* — triggers correctly, stays quiet on a question, or
+  performs the steps it documents.

package/cursor/rules/task-pipeline.mdc

@@ -324,7 +324,12 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
     per project, not per run**. Every gate above is good at *this* run and blind
     across runs: the same class of failure gets caught, fixed and forgotten five
     times and nothing notices it is the same one. So, in this order —
-    **1. Prune before you add.** Check every standing instruction against three
+    **1. Stamp the run first** — date, topic, commit, verdict, counts. It costs one
+    line and it is the only thing that makes the next step computable: one retirement
+    trigger counts firings across the last five run stamps, so a prune placed ahead of
+    the stamp reads a counter its own stage writes afterwards and can never run on real
+    data.
+    **2. Then prune.** Check every standing instruction against three
     retirement triggers: it became a check (a test, a lint rule, a gate, a hook →
     delete it; the check is the memory, and keeping both means it is read twice and
     obeyed once); every path, command or stage it names is gone (→ delete, it
@@ -334,8 +339,6 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
     because "they all matter" is exactly the state in which the list stopped being
     read. **Every deletion writes one line in the log; silent deletion is
     forbidden** — the record stays, the instruction leaves.
-    **2. Stamp the run** — date, topic, verdict, counts. That stamp is what makes
-    "five runs" countable.
     **3. Write an entry, only if the run diverged** — symptom with evidence, the
     stage it *surfaced at*, the stage that **owned** it (usually earlier — a finding
     recorded against the stage that tripped over it comes back), the root cause
@@ -349,8 +352,8 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
     cap is not negotiable and the prune is a gate item, not a good intention.
     Gate: ladder walk ran, no REQ `unknown`, no ledger row without
     a home, every repository clean/pushed/pointed-at, user signs off, **and the
-    retro is written — pruned before anything was added, at or under its cap, every
-    deletion logged, the run stamped, and the counts printed beside this verdict**.
+    retro is written — stamped first, then pruned before anything was added, at or
+    under its cap, every deletion logged, and the counts printed beside this verdict**.
 
 Cross-cutting: answer from the brief's autonomy section rather than re-asking, log every deferral in the ledger, never narrow the task silently, track
 tasks, conventional commits, honest degradation (never claim a failed/skipped step

package/evals/RESULTS.md

@@ -50,6 +50,13 @@ the split matters more than the total: a run the author watched, knowing the exp
 behaviour, is an observation of instruction-following and not an evaluation. Collapsing
 the two into one "runs recorded" number is how a self-check gets quoted as a result.
 
+That split is **canon 5 applied to evaluation** — *green nobody watched turn red is not
+evidence* ([`documentation.md`](../plugins/task-pipeline/skills/task-pipeline/references/documentation.md)
+→ *The canons*). A self-observed run is a green the author was steering; a blind run is
+the only one that could have come back red for a reason nobody arranged. The code graph
+surfaced this link before any document stated it, which is the divergence check earning
+its keep.
+
 Everything else in this repository is proven by structural guards — the count is
 whatever `npm run test:all` prints, deliberately not restated here — and those check
 the *form*. These are the only checks that speak to the *behaviour*. Printed here so a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.23.1",
+  "version": "1.25.0",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"

package/plugins/task-pipeline/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "task-pipeline",
   "displayName": "Task Pipeline",
   "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/manual gates, a frozen requirement spine that must close with evidence, a loop guard that breaks churn, one provider-agnostic model confirmed up front, and an optional super-ux UX track for user-facing work.",
-  "version": "1.23.1",
+  "version": "1.25.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/commands/task-pipeline.md

@@ -31,7 +31,7 @@ language, ADRs for hard-to-reverse calls) and covering the **autonomy sweep** (w
 would otherwise stop stages 1→10: docs sources incl. doc repos, the wiki and the code graph, branch/tracker
 policy, test and lint commands, deploy target and authorization, log locations, docs/wiki/graph targets, and for UI tasks whether the design is done visually in Figma or text-only, whether the Figma MCP is connected, and — if it isn't — whether to ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; **and with Figma on, the design destination: which team/org by name and which file** — the recorded one, a URL the operator gives, or creation in that named team explicitly authorized, written into the project's canonical record before the first frame, because a destination decided at drawing time is how a project ends up with three design files and no way to tell which is real. **Never create while a recorded file resolves; if it doesn't resolve, stop and ask — never create a replacement**) —
 until the brief is locked — including the **REQ table**, the request as an addressable list where every row names how it is verified — so the rest runs autonomously and the final stage can account for all of it. The list is frozen: adding is free, removing needs the operator's agreement. Anything deferred goes into the carry-over ledger the moment it's said. For any user-facing task, recommend/use
-**super-ux**. **If the brief describes a platform rather than a change**, stage 2 also cuts it into modules (`references/decomposition.md`) — module map committed, walking skeleton first, every REQ in exactly one module — and stages 3→10 then run per module, one brick at a time. **If any loop starts undoing an earlier pass** (same file edited twice for the same reason, a closed finding returning, a third entry into one stage), stop and run the loop guard (`references/loop-guard.md`): name both shapes, escalate to the layer that owns the conflict, re-plan the check as an ordered list, then go item by item. **The closing stage opens with the ladder walk** (`references/audit.md`): the REQ table finds what was named and lost, but a comparison needs two sides and an absence has one — so walk each REQ bottom-up through its rungs (decision → spec section → contract *and its failure behavior* → task → change → executed test → surface/docs), check the seam at each step, order findings by seam rather than by file, and turn every absence into a new REQ row **before** the coverage table is written. A green from a check nobody has watched fail against a planted defect is not evidence; a finding class seen twice becomes a script rather than a third ledger row; and the carry-over ledger's counts are printed beside every gate verdict, so "green" never reads as "verified". If a searching pass starts finding mostly what the previous pass's own fixes broke, the axis is exhausted — rotate it, don't look harder. **The docs stage closes three artifacts, not two:** module docs, the wiki, **and the code graph** (`/graphify . --update` where `graphify-out/` exists — `references/knowledge-graph.md`), because the graph is what the next run's harvest queries first and a stale one is a false premise carrying the authority of a machine. Then check the graph against the docs: a hub `graphify god-nodes` reports that no document names is an undocumented seam; an edge the docs deny is a leak in the code or a lie in the docs; a doc naming a module the graph no longer has is stale. Doc-side findings are fixed there, absences become REQ rows in the closing stage. **In a project of several repositories, stage 10 closes on the parent too:** a parent records each submodule as a pointer to one commit, and moving the submodule does not move the pointer — so the work can be committed, pushed and green while a clone of the parent still gets the commit before it. Neither repo looks wrong alone, which is why it survives every check that runs inside one. Require `git submodule status` with no line starting `+`, and every repo clean and pushed (`git -C <repo> status --porcelain`, `git -C <repo> log @{u}..HEAD`). The fix is two commands and the second gets forgotten: push the submodule, then `git add <submodule> && git commit`. **The run's last act is the retrospective** (`references/retrospective.md` → `docs/superpowers/retro.md`, one file per project): **prune before you add** — every standing instruction against its three retirement triggers (it became a check; the paths/commands it names are gone; it hasn't fired in five run stamps), the list held to a hard cap of ten, every deletion logged as one line and never silent — then stamp the run, 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 fix by grade (mechanical check > standing instruction > note that expires in two runs), and the check that catches it next time. Stage 0 reads those standing instructions in full, so the prune is a gate criterion, not a good intention: a rule nobody reads to the end is worse than no rule, because everyone believes it is covered. Honor every stage gate by its type (`auto` = verify yourself;
+**super-ux**. **If the brief describes a platform rather than a change**, stage 2 also cuts it into modules (`references/decomposition.md`) — module map committed, walking skeleton first, every REQ in exactly one module — and stages 3→10 then run per module, one brick at a time. **If any loop starts undoing an earlier pass** (same file edited twice for the same reason, a closed finding returning, a third entry into one stage), stop and run the loop guard (`references/loop-guard.md`): name both shapes, escalate to the layer that owns the conflict, re-plan the check as an ordered list, then go item by item. **The closing stage opens with the ladder walk** (`references/audit.md`): the REQ table finds what was named and lost, but a comparison needs two sides and an absence has one — so walk each REQ bottom-up through its rungs (decision → spec section → contract *and its failure behavior* → task → change → executed test → surface/docs), check the seam at each step, order findings by seam rather than by file, and turn every absence into a new REQ row **before** the coverage table is written. A green from a check nobody has watched fail against a planted defect is not evidence; a finding class seen twice becomes a script rather than a third ledger row; and the carry-over ledger's counts are printed beside every gate verdict, so "green" never reads as "verified". If a searching pass starts finding mostly what the previous pass's own fixes broke, the axis is exhausted — rotate it, don't look harder. **The docs stage closes three artifacts, not two:** module docs, the wiki, **and the code graph** (`/graphify . --update` where `graphify-out/` exists — `references/knowledge-graph.md`), because the graph is what the next run's harvest queries first and a stale one is a false premise carrying the authority of a machine. Then check the graph against the docs: a hub `graphify god-nodes` reports that no document names is an undocumented seam; an edge the docs deny is a leak in the code or a lie in the docs; a doc naming a module the graph no longer has is stale. Doc-side findings are fixed there, absences become REQ rows in the closing stage. **In a project of several repositories, stage 10 closes on the parent too:** a parent records each submodule as a pointer to one commit, and moving the submodule does not move the pointer — so the work can be committed, pushed and green while a clone of the parent still gets the commit before it. Neither repo looks wrong alone, which is why it survives every check that runs inside one. Require `git submodule status` with no line starting `+`, and every repo clean and pushed (`git -C <repo> status --porcelain`, `git -C <repo> log @{u}..HEAD`). The fix is two commands and the second gets forgotten: push the submodule, then `git add <submodule> && git commit`. **The run's last act is the retrospective** (`references/retrospective.md` → `docs/superpowers/retro.md`, one file per project): **stamp the run first** (its commit is what makes the cold-retirement trigger computable), **then prune** — every standing instruction against its three retirement triggers (it became a check; the paths/commands it names are gone; it hasn't fired in five run stamps), the list held to a hard cap of ten, every deletion logged as one line and never silent — 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 fix by grade (mechanical check > standing instruction > note that expires in two runs), and the check that catches it next time. Stage 0 reads those standing instructions in full, so the prune is a gate criterion, not a good intention: a rule nobody reads to the end is worse than no rule, because everyone believes it is covered. Honor every stage gate by its type (`auto` = verify yourself;
 `manual` = wait for explicit go). Confirm the **model once at preflight** —
 recommend the most capable one the environment offers, never a hardcoded id — then
 run the whole pipeline on it without re-asking.

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

@@ -43,7 +43,7 @@ thing, the canon is the *why* and the rule is the *how*.
 | trust a mechanism that reports success | [`gates.md`](../task-pipeline/references/gates.md) → *False success* | the failure that removes the reason to look |
 | wire a check into the agent's own tooling | [`hooks.md`](../task-pipeline/references/hooks.md) | the hook contract, and why a crashed guard **allows** the action |
 | audit documentation a project already has | [`setup.md`](../task-pipeline/references/setup.md) | seven passes, cheapest first, output is a fix plan |
-| carry a lesson to the next run | [`retrospective.md`](../task-pipeline/references/retrospective.md) | prune first, cap of ten, every lesson names its commit |
+| carry a lesson to the next run | [`retrospective.md`](../task-pipeline/references/retrospective.md) | stamp first (the cold trigger reads it), then prune to a cap of ten; every lesson names its commit |
 | seed a gate into a host project | [`templates/docgate.sh`](../task-pipeline/templates/docgate.sh) | it seeds **green**: dormant where there is no input yet |
 | take a whole change through to acceptance | [`task-pipeline`](../task-pipeline/SKILL.md) | this skill is the standard; that one is how a change reaches the repository |
 

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

@@ -154,14 +154,18 @@ plus a stable id, never a second act of thinking.
 and forgotten five times with nothing noticing it is the same one. The last act of
 stage 10 is therefore the **retrospective**
 ([`references/retrospective.md`](references/retrospective.md), written to
-`docs/superpowers/retro.md`): **prune first** — every standing instruction checked
-against its retirement triggers (it became a check · its surface is gone · it hasn't
-fired in five runs), the list held to a hard cap of **ten**, every deletion logged —
-then stamp the run, then write an entry **only if the run diverged** (symptom, the
+`docs/superpowers/retro.md`): **stamp the run first** — one line, and the only thing
+that makes the next step computable — **then prune**, every standing instruction
+checked against its retirement triggers (it became a check · its surface is gone · it
+hasn't fired in five run stamps), the list held to a hard cap of **ten**, every
+deletion logged, then write an entry **only if the run diverged** (symptom, the
 stage that *owned* it, root cause, fix, and the check that catches it next time).
 Stage 0 reads those standing instructions in full, which is exactly why the prune is
 a gate criterion and not a good intention: a rule nobody reads to the end is worse
-than no rule, because everyone believes it is covered.
+than no rule, because everyone believes it is covered. **The order is load-bearing,
+not stylistic** — one retirement trigger counts firings across the last five run
+stamps, so a prune placed ahead of the stamp reads a counter its own stage writes
+afterwards and can never run on real data ([`references/learned.md`](references/learned.md) rule 21).
 
 Three things the grill does beyond clarifying the request:
 - **Domain awareness.** It reads the project's own `CONTEXT.md` / `docs/adr/` and
@@ -264,7 +268,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 | 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: prune, stamp, 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 — prune before entry, list at or under its cap, every deletion and every entry carrying its commit, entries older than five stamps rotated into the archive, run stamped with its commit, counts printed** | 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); 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** | manual |
 
 
 ### Stage 10 in a project of several repositories

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

@@ -176,16 +176,17 @@ whether the run was finished.
 
 After the closing question, before the run is called done:
 [`retrospective.md`](retrospective.md), written to `docs/superpowers/retro.md`.
-Every run **prunes and stamps**; only a run that *diverged* writes an entry.
+Every run **stamps and prunes**; only a run that *diverged* writes an entry.
 
-The order is fixed, because a lesson that lands in a cluttered file is a lesson
-nobody reaches:
+The order is fixed, and it is a **dependency, not a preference** — step 2 reads the
+counter step 1 writes ([`learned.md`](learned.md) rule 21):
 
-1. **Prune first.** Every standing instruction is checked against its three
+1. **Stamp the run first** — one line: date, topic, commit, verdict, retro counts. It
+   costs nothing and it is the only thing that makes the next step computable.
+2. **Then prune.** Every standing instruction is checked against its three
    retirement triggers — it became a check, its surface is gone, or it has not
    fired in the last five run stamps — and the list is held to its cap of **ten**.
    Every deletion writes one line in the log; silent deletion is forbidden.
-2. **Stamp the run** — one line: date, topic, verdict, retro counts.
 3. **Write the entry, if the run diverged** — symptom, the stage it surfaced at,
    the stage that *owned* it, the root cause, the fix (mechanical > standing
    instruction > note with an expiry), and the check that catches it next time.
@@ -224,11 +225,14 @@ All of:
    shows no `+`, and each repo is clean and pushed. A submodule is finished when
    its parent points at it.
 9. **The operator answers the closing question** and signs off.
-10. **The retrospective is written** ([`retrospective.md`](retrospective.md)) — the
-    prune ran **before** anything was added (standing instructions checked against
-    their retirement triggers, the list at or under its cap of ten, every deletion
-    logged), the run is stamped, and a run that diverged has its entry with a root
-    cause and a named check. The counts are printed beside this verdict, not filed.
+10. **The retrospective is written** ([`retrospective.md`](retrospective.md)) — **in
+    order**: the run is stamped with its commit first, **then** the prune runs before
+    anything is added (standing instructions checked against their retirement triggers,
+    the list at or under its cap of ten, every deletion logged), **then** a run that
+    diverged gets its entry with a root cause and a named check. The stamp precedes the
+    prune because a retirement trigger counts firings across the last five run stamps
+    ([`learned.md`](learned.md) rule 21). The counts are printed beside this verdict,
+    not filed.
 
 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

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

@@ -35,7 +35,7 @@ better, plus one that is required only for user-facing work.
 | 5 Build (isolation, subagents, fix loop) | `references/build.md` + `references/review.md` |
 | 5–6 TDD + suite gate | `references/tdd.md` |
 | 10 Acceptance (REQ close-out) | `references/acceptance.md` |
-| 10 Retrospective (the run's last act: prune, stamp, entry) | `references/retrospective.md` |
+| 10 Retrospective (the run's last act: stamp, prune, entry) | `references/retrospective.md` |
 | 10 + any audit (finding what's missing) | `references/audit.md` |
 | any repeating loop | `references/loop-guard.md` |
 

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

@@ -286,7 +286,7 @@ The ledger is the stage-9 work list. For each row:
   document class or ratchet. Note that this list and the **propagation matrix** are
   different lists on purpose: the ledger is what you *read*, the matrix is what you
   *owe* ([`documentation.md`](documentation.md)), and stage 9 walks both.
-- **The retro** — prune, stamp, entry, and rotate what aged out into the archive
+- **The retro** — stamp, prune, entry, and rotate what aged out into the archive
   ([`retrospective.md`](retrospective.md)).
 - **Anything the run proved stale** — including a doc that was "wrong but nobody
   had time": that's why the conflict was logged in phase 2 instead of only being

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

@@ -484,18 +484,19 @@ never that the work was skipped quietly.
   written to `docs/superpowers/retro.md` — one file per project, not per run. The
   pipeline's gates are good at *this* run and blind across runs: the same class of
   failure can be caught, fixed and forgotten five times and nothing in the flow
-  notices it is the same one. So, in this order: **prune first** (every standing
-  instruction against its three retirement triggers — it became a check, its
-  surface is gone, it hasn't fired in five run stamps — and the list held to its cap
-  of ten, every deletion logged **in the archive, with the commit that retired it**),
-  **stamp the run**, then **write an entry only if
+  notices it is the same one. So, in this order: **stamp the run first** (one line,
+  with its commit — and the only thing that makes the next step computable), **then
+  prune** (every standing instruction against its three retirement triggers — it
+  became a check, its surface is gone, it hasn't fired in five run stamps — and the
+  list held to its cap of ten, every deletion logged **in the archive, with the
+  commit that retired it**), then **write an entry only if
   the run diverged** (symptom · the stage it surfaced at · the stage that *owned* it
   · root cause · fix, mechanical before instruction before expiring note · the check
-  that catches it next time). Every run prunes and stamps; a retro left empty after
+  that catches it next time). Every run stamps and prunes; a retro left empty after
   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; **the retrospective is written — prune before entry, the
+  the table was written; **the retrospective is written — stamped first, then pruned, then the entry; the
   list at or under its cap, every deletion logged in the archive with its commit,
   entries older than five run stamps rotated into `docs/superpowers/retro/`, the run
   stamped with its commit, every SHA in either file resolvable, and the

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

@@ -20,7 +20,7 @@ from `super-ux`.
 | `hygiene.sh` | `scripts/check-hygiene.sh` | 0 seeds it · **5 runs it after every task** · 6 and 9 run it · 10 proves it |
 | `hooks.example.json` | the project's `.claude/settings.json` | 0 — offered, never installed silently |
 | `routing-rule.md` | the operator's `CLAUDE.md` — **offered by `setup`, never written silently** | 0 / `setup` |
-| `retro.md` | `docs/superpowers/retro.md` — **one per project, not per run** | 10 writes (prune → stamp → entry), 0 reads it in full |
+| `retro.md` | `docs/superpowers/retro.md` — **one per project, not per run** | 10 writes (stamp → prune → entry), 0 reads it in full |
 | `retro-archive.md` | `docs/superpowers/retro/YYYY-QN.md` | 10 rotates into it, 0 **queries** it |
 
 The documentation-track templates (`docmap.md`, `decisions.md`,

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

@@ -1,7 +1,9 @@
 # Pipeline retrospective — <project>
 
 One file per project, not per run. Written as the **last act of stage 10**:
-prune first, then stamp, then write an entry **only if the run diverged**.
+**stamp first, then prune**, then write an entry **only if the run diverged**.
+The order is load-bearing: the cold-retirement trigger reads the stamp this stage
+writes, so a prune ahead of it can never run on real data (`learned.md` rule 21).
 Doctrine: `references/retrospective.md`.
 
 **What stage 0 reads in full:** *Standing instructions*, *Run stamps* and *Recent