task-pipeline-skill 1.32.0 → 1.37.0

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

@@ -0,0 +1,190 @@
+# Progress — saying which pipeline this is, and where in it
+
+**One job: make the run's position a printed fact instead of something the operator
+reconstructs from the last thing that scrolled past.**
+
+A pipeline that never says where it is has one specific failure, and it is not
+confusion — it is that **a stage looks done because nothing printed**.
+[`stages.md`](stages.md) opens with a checklist for exactly that reason and then marks
+it *"copy it, tick it"*: an instruction with no gate behind it, which is rung 1
+behaving like rung 3 ([`gates.md`](gates.md) → *Axis B*). This file is that checklist
+promoted to something the run must emit.
+
+**Boundary.** This file decides **what is printed and when**. It decides nothing about
+what is true: every number on the block has a home somewhere else and is read from
+there. A progress line that computes its own counts is the fourth copy of the truth,
+and [`continuity.md`](continuity.md) already says what happens to those — nobody
+maintains them and the next run reads them as current.
+
+---
+
+## Contents
+
+- The two boundaries, and only those two
+- The header block
+- The iteration line
+- The rail is computed, never eleven
+- What each glyph means
+- Every number is borrowed
+- Absent is a word, never a zero
+- The run ledger this reads from
+- Rationalizations
+
+## The two boundaries, and only those two
+
+**Task start** and **iteration close**. Nothing else.
+
+An iteration is already defined — *one item taken to its gate*
+([`continuity.md`](continuity.md) → *What one iteration means*) — and that definition
+is what makes this cheap. Printing per agent turn would put a bar above every tool
+call, and a block that appears fifty times a run is a block nobody reads, including
+the one time it says something.
+
+Between the two boundaries the run prints whatever it normally prints. This file adds
+no narration.
+
+## The header block
+
+Emitted **once, before stage 0's first question**, and again whenever the module
+changes:
+
+```
+task-pipeline v1.34.0 · pipeline-audit · module P1 «the progress print» (1 of 4)
+  0 ✓  1 ✓  2 ✓  3 ▶  4 ·  5 ·  6 ·  7 ·  8 ·  9 · 10 ·
+  ███████░░░░░░░░░░░░░░░░░░░  gates 3/11 · now 3 Spec · manual
+  board B-028 · carry-over 0 rows · exposure 99 never · unlooked 0
+```
+
+Four lines, and each one answers a question an operator otherwise has to ask:
+
+| Line | Answers |
+|---|---|
+| 1 | *which skill, which version, which programme, which module of how many* |
+| 2 | *which stages are closed, which one is live* |
+| 3 | *how far along, what is running now, will it stop for me* |
+| 4 | *what is queued, what is deferred, what nobody has confirmed* |
+
+**The module segment is omitted when there is no module map.** A task that stage 2
+never decomposed has no module, and printing `(1 of 1)` turns an absence into a claim
+— the shape [`audit.md`](audit.md) is built around. Where stage 2 recorded `single
+module: <name>` ([`decomposition.md`](decomposition.md)), print that phrase instead.
+
+## The iteration line
+
+Emitted at the **close** of every iteration, one line:
+
+```
+▶ pipeline-audit · P1 (1/4) · 5 Dev auto · iter 3 · gates 5/11 · next B-025
+```
+
+**`next` cites a `B-NNN`, never a description.** That rule is
+[`continuity.md`](continuity.md)'s and it is the reason this line exists at all:
+*"next up is X"* was already the one sentence in a loop that no gate reads. A board id
+can be checked against `docs/superpowers/backlog.md`; *"next up: the export fix"*
+cannot.
+
+**Nothing queued is `next —`, printed.** A loop that reaches an empty board says so;
+omitting the field is indistinguishable from forgetting it.
+
+## The rail is computed, never eleven
+
+The stage ids on the rail come from the project's `pipeline.json` → `stages[]`. They
+are **not** the eleven in [`../pipeline.example.json`](../pipeline.example.json), which
+is this plugin's *example* flow — a host project replaces it with its own stages
+(`SKILL.md` → *Bring your own skills*).
+
+A bar reading `gates 5/11` in a project with six stages is a false success in the
+purest form the pipeline has: a summary that is confidently wrong about the thing it
+summarises, printed in the place designed to be trusted at a glance.
+
+So the rail carries **no stage count of its own**. Read the array, print what is in it.
+Six stages give six positions.
+
+## What each glyph means
+
+| Glyph | Means | Written when |
+|---|---|---|
+| `✓` | the stage's **gate passed** | the gate's own verdict was recorded |
+| `▶` | in flight | the stage was entered and its gate has not returned |
+| `·` | not entered | — |
+| `✗` | entered, gate returned a failure | the verdict said so |
+| `⊘` | skipped, **with the reason on the same run's record** | the short path, or a stage the brief excluded |
+
+**`✓` means the gate passed — not that the stage was walked.** This is the whole
+integrity of the block. A rail is a summary, and a summary is the easiest artefact in
+a run to write from memory rather than from the record; a glyph set by recollection is
+[`gates.md`](gates.md)'s *false success* with a nicer typeface. Derive each glyph from
+the verdict the gate wrote, in the run ledger, and from nothing else.
+
+**`⊘` may never be silent.** A skipped stage with no recorded reason is exactly what a
+`·` looks like from outside, and the two mean opposite things.
+
+## Every number is borrowed
+
+| Field | Its home |
+|---|---|
+| `board B-NNN` | `docs/superpowers/backlog.md` ([`backlog.md`](backlog.md)) |
+| `carry-over N rows` | the run's carry-over ledger, as printed beside every gate verdict |
+| `exposure N never` | `docs/superpowers/verification.md` ([`exposure.md`](exposure.md)) |
+| `unlooked N` | the gate's own disclosure ([`gates.md`](gates.md) → *Disclosures*) |
+| `gates N/M` | the run ledger's verdict rows, and `pipeline.json` → `stages[]` |
+
+**None of these is recomputed here.** If a number on the block disagrees with the
+number beside a gate verdict, the block is wrong — that direction, always, because the
+gate looked and the block quoted.
+
+This also settles what the block is *not*: it is neither a ratchet nor a disclosure of
+its own ([`gates.md`](gates.md) → *Ratchets*, *Disclosures*). It sets no floor and
+carries no target. It is a **restatement with a citation**, and the citation is the
+only reason a restatement is allowed here at all.
+
+## Absent is a word, never a zero
+
+Where a value does not exist, print the word:
+
+```
+board — · carry-over 0 rows · exposure — · unlooked 0
+```
+
+`exposure —` says *no verification ledger in this project*. `exposure 0` says *nothing
+is unconfirmed*, which is the opposite claim, and it is the same inversion
+[`exposure.md`](exposure.md) refuses when it prints `never checked` rather than
+`0 days`. A zero standing in for an absence is how a project learns it is safe.
+
+`carry-over 0 rows` **is** a real zero and prints as one: the ledger exists and holds
+nothing.
+
+## The run ledger this reads from
+
+`.task-pipeline/run.md`, seeded at stage 0 from
+[`../templates/run.md`](../templates/run.md), one file per run.
+
+It already had a second owner before this file existed:
+[`loop-guard.md`](loop-guard.md) names it as the record that makes churn detection
+**mechanical**, and calls it the only memory that survives compaction. It was never
+written by any run — the detector had no input, and the guard was doctrine wearing a
+script's clothes. One file serves both readers: the guard reads the `touch:` lines,
+this block reads the verdict rows and the iteration counter.
+
+Three kinds of line, appended, never rewritten:
+
+```
+stage: 3 Spec — gate manual — verdict pass — 2026-08-10T14:02Z
+iter:  3 — item B-025 — closed at gate 6
+touch: test/validate.py — pass 2 (stage 7) — reason: F-014
+```
+
+**The counter is a count of `iter:` lines, not a number the agent remembers.** After a
+compaction the agent's memory of "iteration 3" is gone and the file's is not, which is
+the entire argument for keeping it on disk rather than in the reply.
+
+## Rationalizations
+
+| The excuse | What is actually true |
+|---|---|
+| "The operator can see the stages scroll by" | They can see that *something* printed. A stage that ended silently and a stage that never started look identical in a transcript, which is the failure `stages.md`'s checklist was written for and never enforced. |
+| "A progress bar is decoration" | Then delete the numbers and keep the bar. The objection is really to the bar; the four borrowed counts are the payload, and they are the ones nobody prints today. |
+| "I know which stage I'm on, I'll write the rail from memory" | Then the rail is a claim about the run rather than a reading of it, and it will be right until the run it most matters on. Derive it from the verdicts. |
+| "There's no module map, I'll put (1 of 1)" | An undecomposed task has no module. `(1 of 1)` is an invented denominator, and a reader cannot tell it from a real one. |
+| "Printing it every iteration is noise" | One line. The block is four, and it appears at task start. If that is noise, the run is emitting far worse elsewhere. |
+| "The ledger is bureaucracy, I'll count iterations in my head" | Your head does not survive compaction. That is not a hypothetical here — it is why `loop-guard.md` asked for this file in the first place. |

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

@@ -37,6 +37,8 @@ file exists to stop.
 - The prune — mandatory, and it runs after the stamp
 - The loop closes at stage 0
 - Where a lesson goes when it is not about this project
+- Publishing the insight — the skill learns from every project that runs it
+- What may leave the project — the redaction list
 - Rationalizations
 
 ## Write the entry only for a divergence — and name the layer that owned it
@@ -227,9 +229,92 @@ rule that was retired for going cold is exactly the rule about to be re-learned.
 
 A lesson that would be true in any repository does not belong in one project's
 retro — it belongs in the pipeline's own doctrine
-([`learned.md`](learned.md), which is exactly that list, earned the same way). Open
-an issue upstream and say so in the entry. A local file that accumulates universal
-rules is a fork of the skill that nobody named.
+([`learned.md`](learned.md), which is exactly that list, earned the same way). A local
+file that accumulates universal rules is a fork of the skill that nobody named.
+
+**This said *"open an issue upstream"* for eight releases and named no repository, no
+trigger and no authorization** — an instruction on rung 1 that everybody read as done.
+The rest of this section is the mechanism.
+
+## Publishing the insight — the skill learns from every project that runs it
+
+**One job: stop a lesson dying in the repository that learned it.**
+
+A retro entry is written per project and read by that project's next stage 0. The
+pipeline itself never sees it. So a defect in the **skill** — a gate that loops, a
+doctrine promising what nothing enforces, a rule firing on the wrong shape — is
+rediscovered independently in every project and fixed in none of them.
+
+**Opt-in, per project, off by default** — `pipeline.json` → `retro.publish`:
+
+```json
+"retro": {
+  "publish": {
+    "repo": "ssheleg/task-pipeline",
+    "label": "retro-insight",
+    "redact": "strict"
+  }
+}
+```
+
+Absent, nothing is published, and nothing is asked. **Silence arms nothing** — the same
+floor deploy authorization uses, and for the same reason: this is an **outward act**,
+and an outward act taken from a generic flag is an outward act nobody authorized
+([`continuity.md`](continuity.md) → *The limit, before the capability*).
+
+**The body is printed in full before the issue is opened, every time.** Not a summary
+of it, not its title — the string that will be sent. The operator standing at stage
+10's manual gate is already reading; showing them what leaves the machine costs one
+block and is the only moment anyone can stop it.
+
+```
+── would open issue ──────────────────────────────────────────
+repo:  ssheleg/task-pipeline
+label: retro-insight
+title: [retro] a queue is not a diagnosis
+<the whole body, verbatim>
+──────────────────────────────────────────────────────────────
+opening…  → #24
+```
+
+**No `gh`, no network, no permission?** Print the body, say the issue was **not**
+opened, and carry the exact text in the carry-over ledger. That is the honest
+degradation; a second transport is not.
+
+## What may leave the project — the redaction list
+
+An issue is a **public artefact in someone else's repository**. What travels is the
+*class*; what stays is everything that identifies where it happened.
+
+| Goes | Stays |
+|---|---|
+| the class of failure, stated in the abstract | the file, the function, the line it happened in |
+| which stage owned it and which stage surfaced it | the repository, organisation, branch or commit |
+| the doctrine or guard that missed it, by its name **in this skill** | any host path, absolute or relative |
+| the fix by grade, and the check that would catch it | the code, the config values, the data |
+| whether an existing standing instruction fired | any person, company, customer or product name |
+
+Five rules, numbered so a reader can point at one:
+
+1. **No host paths.** Only paths inside task-pipeline itself — `references/…`,
+   `templates/…`, `test/validate.py`. An absolute path names a machine.
+2. **No host identifiers**: repository, organisation, branch, commit, tag, issue or PR
+   number belonging to the project the run happened in.
+3. **No code, no configuration values, no data** — not a snippet, not a redacted
+   snippet. A shape can be described in a sentence.
+4. **No names**: person, company, customer, employer, product.
+5. **The title states the class, not the incident** — *"a queue is not a diagnosis"*,
+   never *"our export job looped"*.
+
+**The printed text and the sent text are one string.** Redacting after the print, or
+printing a cleaned-up version of what is actually sent, is the false-success shape this
+bundle names outright ([`gates.md`](gates.md) → *False success*): a mechanism reporting
+on itself rather than on what it did.
+
+**When in doubt the rule is subtraction, not judgement.** An insight that survives
+losing a detail is still an insight; a detail that leaks cannot be recalled from an
+index. If removing it makes the entry incomprehensible, the entry was about the project
+and not about the skill — keep it local.
 
 ## Rationalizations
 

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

@@ -8,12 +8,27 @@ operator's explicit go). These stages (0 intake + 1→10) are the plugin's
 `pipeline.schema.json`; a host project replaces it with its own
 stages/agents/types (see SKILL.md → *Bring your own skills*).
 
-## The run checklist — copy it, tick it
+## The run checklist — printed, not remembered
 
-Complex workflows lose steps silently. Copy this into your response at the start of
-a run and check items off as they close; it is the cheapest guard against the one
-failure this pipeline keeps paying for — a stage that *looks* done because nothing
-printed.
+Complex workflows lose steps silently. **The run says where it is**, at two boundaries
+and only two — task start and iteration close ([`progress.md`](progress.md)):
+
+```
+task-pipeline vX.Y.Z · <topic> · module <id> «<name>» (N of M)
+  0 ✓  1 ✓  2 ✓  3 ▶  4 ·  5 ·  6 ·  7 ·  8 ·  9 · 10 ·
+  ███████░░░░░░░░░░░░░░░░░░░  gates 3/11 · now 3 Spec · manual
+  board B-NNN · carry-over N rows · exposure N never · unlooked N
+```
+
+The rail's positions come from the project's own `pipeline.json`, never from the count
+below — those eleven are this plugin's example flow. Each glyph is read from the
+verdict its gate wrote to `.task-pipeline/run.md`, and from nothing else: a rail
+written from memory is a summary that is confidently wrong exactly where it is trusted
+at a glance.
+
+The checklist below is what that rail summarises. This section said *"copy it, tick
+it"* until 2026-08-10 — an instruction with no gate behind it, which is the same
+failure it was written to prevent, one level up.
 
 ```
 Pipeline progress
@@ -35,7 +50,7 @@ never that the work was skipped quietly.
 
 ## Contents
 
-- The run checklist — copy it, tick it
+- The run checklist — printed, not remembered
 - 0 — Intake grill — MANDATORY
 - 1 — Docs study
 - 2 — Brainstorm + decompose
@@ -123,6 +138,27 @@ never that the work was skipped quietly.
   or they genuinely disagree and that is a decision. There is no fourth option, and
   starting on an unresolved divergence means building against a system that does
   not exist.
+- **Phase 1d — the short-path triage: printed, proposed, never taken silently.** This
+  pipeline's own boundary exempts a typo, a one-line fix and a mechanical rename — and
+  nothing measured that until 2026-08-10, so the exemption depended on an agent
+  remembering it while eleven stages and four manual gates stood in front of a
+  one-paragraph edit. Three questions, each with something behind it:
+
+  ```
+  1. files the request names, resolved        git ls-files -- <paths>       -> N
+  2. any of them a public contract            the version-synced surfaces,
+                                              pipeline.schema.json, the
+                                              command, the README           -> yes/no
+  3. behaviour a user or a caller observes changes                          -> yes/no
+  ```
+
+  Few files, no contract, no observable change ⇒ **propose** the short path: stages 1,
+  2, 3 and 4 marked `⊘` with the triage answer as the reason, and 5→10 running
+  unchanged. **Propose, never take.** The answer goes in the brief's autonomy sweep and
+  silence takes the full flow — the same floor deploy authorization uses. The glyph is
+  what makes it safe: a skipped stage is printed on the rail **with its reason**
+  ([`progress.md`](progress.md)), and a skip nobody can see is indistinguishable from a
+  stage that was never entered.
 - **How it runs: [`grill.md`](grill.md)** — the full doctrine, built into this
   skill (nothing to install). In short: one question per turn, a recommended
   answer with each, explore the codebase before asking, depth-first through the
@@ -170,12 +206,22 @@ never that the work was skipped quietly.
   is now stale), no open contradictions, **every
   autonomy-sweep row is answered or explicitly marked "stop and ask here"**, the
   **REQ table is written and every row names its check**, the carry-over ledger is
-  seeded, the model decision is recorded, and the operator confirms the brief. Stop when a
+  seeded, **`.task-pipeline/run.md` exists and the header block has been printed**
+  ([`progress.md`](progress.md)), the model decision is recorded, and the operator
+  confirms the brief. Stop when a
   re-scan surfaces no new branches (don't grill past diminishing returns;
   reversible calls can be deferred with a note). Only then start stage 1.
 - **The verification ledger is read.** `docs/superpowers/verification.md` — the harvest
   quotes **how many rows sit at `never`**, because that is the project's standing
   exposure and stage 0 is where it is cheapest to look ([`verification.md`](verification.md)).
+- **The run ledger is seeded and the header block is printed** — in that order, before
+  the first grill question. `.task-pipeline/run.md` from
+  [`../templates/run.md`](../templates/run.md) is the record **two** mechanisms already
+  depended on and no run had ever written: [`loop-guard.md`](loop-guard.md) calls its
+  own churn detection mechanical and reads the `touch:` lines, and
+  [`progress.md`](progress.md) derives the rail and the iteration counter from the
+  `stage:` and `iter:` lines. The header goes out before the interview because a run
+  that announces its position only at the end announced it to nobody.
 - **The board is read, or seeded.** `docs/superpowers/backlog.md` ([`backlog.md`](backlog.md)) — its **open count is quoted in the brief**, measured by a command at the top of the run rather than inherited from the last run's report. Absent ⇒ seeded from the template and said so; an empty board and no board are the same thing to work on, and only one of them can be appended to.
 
 ## 1 — Docs study
@@ -256,6 +302,32 @@ never that the work was skipped quietly.
   never rebuild from scratch. If the chain already exists and is validated (e.g.
   the task entered from super-ux), just verify (linter green) and embed it into
   the spec; only build the parts that are missing.
+- **COPY track — how it sounds.** Every string a product's user will read is written
+  through super-ux's `copywriting`, against the brand pack (`docs/brand/voice.md`,
+  `terminology.md`, `facts.md`). No pack ⇒ `/brand-init` **before** the first string,
+  not after: a voice reverse-engineered from copy already written is a description of
+  what happened, not a decision. In scope: interface strings, errors, empty states,
+  the landing, pricing, the user-facing changelog. **Out of scope, and saying so is
+  what keeps the track honest:** commit messages, PR descriptions, code comments, a
+  developer README, internal docs. Running a brand pack over a line in a contributors'
+  changelog is the fastest way to teach an agent to route around the track.
+- **VISUAL track — how it looks.** Where the task has a visual surface, the visual
+  layer goes through `sheleg-design` ([`companion-skills.md`](companion-skills.md)):
+  tokens and themes, typography and rhythm, motion and how it degrades to rest, the
+  boundary with Figma (tokens as variables, never raw values carried across). Not
+  through it: a purely structural change — what sits where is the UX track's — text,
+  a backend, an internal script.
+- **Each track's refusal is a sentence, never a silence.** *"Без дизайна" / "as is"*
+  ends the visual track; *"без бренда" / "draft"* ends the copy track. Either one is
+  the operator's to make and costs nothing — but it is **recorded in the brief and
+  said out loud in the close-out**, because a track skipped silently and a track that
+  ran are the same thing in a transcript. This is the `⊘` rule one layer up: a skip
+  nobody can see is indistinguishable from work that happened.
+- **Three tracks, three questions, and they do not substitute for each other.** super-ux
+  decides what the interface must **do**; `copywriting` how it **sounds**;
+  `sheleg-design` how it **looks**. Until 2026-08-10 this stage named only the first,
+  so a run designed a flow, then wrote its strings by taste and picked its values at the
+  keyboard — and every gate in the pipeline reported green over both.
 - **Spec:** write the approved design to
   `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit it. Lock all
   shared contracts (types, schemas, signatures, file layout). For UI tasks the
@@ -274,7 +346,11 @@ never that the work was skipped quietly.
   (or an explicit v1-mode/tiny-project waiver by the operator). **With Figma on:
   the canonical record names one file, and every `screens.md` frame link carries
   that same `:fileKey`** — a string match, not a judgement; a differing key means
-  the run drew in a second file nobody will open. No plan (stage 4)
+  the run drew in a second file nobody will open. **Every user-facing string went
+  through the COPY track or the refusal is recorded**, and **the visual layer went
+  through the VISUAL track or the refusal is recorded** — a recorded refusal passes
+  this gate and an unmentioned one does not, which is the only difference that matters.
+  No plan (stage 4)
   starts before this — the chain comes BEFORE interface.
 
 ## 4 — Plan
@@ -308,6 +384,16 @@ never that the work was skipped quietly.
   watch it fail → minimal impl → watch it pass → commit. Pin subagents to the
   run's confirmed model (`model-tiering.md`). The plan's parallel groups fan out
   **only** when each implementer gets its own worktree; otherwise sequential.
+- **Web front end? The task's own surface is checked in a browser, not in the diff.**
+  Where `chrome-devtools` is connected ([`companion-skills.md`](companion-skills.md)):
+  after a task that changes a rendered surface, load it, take a snapshot and read the
+  console and the network log **before the task is marked DONE** — a component can be
+  correct and land under a fixed header, and a review of the diff cannot see that.
+  Absent, say the surface was verified by reading the diff and treat it as the weaker
+  claim it is. Stage 6 repeats this over the whole tree; this one catches it while the
+  implementer that wrote it is still dispatched. The matrix pointed this companion at
+  stages 5–6 from the day it was added and **this stage had never named it** — found by
+  the guard comparing the two, not by a reader.
 - **Integration closes the stage:** sync with the base branch, re-run the full suite
   on the result, land it the project's way (merge, or a PR — outward, so it needs a
   go), remove the worktree. Stages 7–9 act on the integrated result, so a branch the
@@ -370,6 +456,14 @@ never that the work was skipped quietly.
   tagging, the CI verdict for what was just pushed is READ, not assumed**
   ([`conventions.md`](conventions.md) → *The CI verdict*) — a tag on a commit whose
   run nobody read is how a red `main` ships.
+- **The review loop that lives here has a cap, and the cap is a measurement**
+  ([`loop-guard.md`](loop-guard.md) → *The review loop*). **3 rounds** per artifact by
+  default (`pipeline.json` → `run.review.maxRounds`); at the cap the run stops reviewing
+  and prints new-versus-self-inflicted per round, and either the numbers end it or the
+  operator continues it out loud. This stage's loop was capped by nothing until
+  2026-08-10 and ran ten rounds twice in one programme, against a stated ceiling of two
+  re-entries per stage — the ceiling simply did not name a review round. Every finding
+  left open at the cap leaves as a board row with its evidence, never as a shrug.
 
 ## 8 — Post-deploy
 - **Freedom: medium** — where the logs live varies; 'clean boot or an honest degradation report' does not ([`gates.md`](gates.md) → *Axis C*).
@@ -545,7 +639,13 @@ never that the work was skipped quietly.
   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
-  counts printed beside this verdict**; **the documentation gate has been seen
+  counts printed beside this verdict**; **where `pipeline.json` → `retro.publish` is
+  set, the skill-level insight is published as an issue on the skill's repository —
+  its body printed in full first, the printed string and the sent string being one
+  string, and the five redaction rules applied
+  ([`retrospective.md`](retrospective.md) → *What may leave the project*). Absent, the
+  step does not exist and is not asked about: publishing to another repository is an
+  outward act and silence authorizes none**; **the documentation gate has been seen
   failing once against a planted defect and its ratchet counts are printed**
   ([`gates.md`](gates.md)); **every repository is closed — the parent included:
   `git submodule status` shows no `+`, each repo clean and pushed**; **every check this gate leans on has been seen failing

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

@@ -13,6 +13,7 @@ from `super-ux`.
 | `carryover.md` | `docs/superpowers/specs/YYYY-MM-DD-<topic>-carryover.md` | 0 seeds, all stages append, 10 reads |
 | `verification.md` | `docs/superpowers/verification.md` | 8 writes a row per shipped REQ, 10 requires it, a human fills `Human` |
 | `backlog.md` | `docs/superpowers/backlog.md` | 0 seeds when absent, any stage appends, 10 resolves and re-derives |
+| `run.md` | `.task-pipeline/run.md` — **git-ignored**, one per run | 0 seeds it, every gate appends a verdict, every repeating pass a `touch:` line |
 | `context.md` | `CONTEXT.md` at the repo root (or per context) | 0 — grill, domain awareness |
 | `adr.md` | `docs/adr/NNNN-<slug>.md` | 0 — grill, hard-to-reverse decisions |
 | `docmap.md` | `docs/DOCMAP.md` — **one per project** | 0 — the documentation inventory |

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

@@ -0,0 +1,77 @@
+# Run ledger — `.task-pipeline/run.md`
+
+> **One file per run.** Seeded at stage 0, appended by every stage, never rewritten.
+> Two readers depend on it and neither can work from the agent's memory: the skill's
+> `references/loop-guard.md` reads the `touch:` lines to detect churn mechanically, and
+> its `references/progress.md` reads the `stage:` verdicts and the `iter:` count to
+> print the rail.
+>
+> **This file is the run's memory after a compaction.** Everything else about the
+> run's position lives in a context window that will not survive one.
+
+Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
+
+## Lines
+
+Append-only. Three shapes, and nothing else belongs here:
+
+```
+stage: <id> <name> — gate <auto|manual> — verdict <pass|fail|skip> — <ISO-8601>
+iter:  <N> — item <B-NNN or task id> — closed at gate <stage id>
+touch: <file> — pass <N> (<stage|round|module>) — reason: <finding id / gate item>
+```
+
+- **`stage:`** — written when a gate **returns**, not when the stage is entered. The
+  rail's `✓` is derived from this line and from nothing else; a glyph set from memory
+  is a summary that is confidently wrong exactly when it matters.
+- **`iter:`** — one line per iteration closed. The progress line's counter is
+  `grep -c '^iter:'`, never a number anyone remembers.
+- **`touch:`** — one line per file per pass, and the reason names **what forced the
+  edit**: a finding id, a failed gate item, an operator instruction. *"Cleanup"*,
+  *"polish"* and *"while I was there"* are not reasons; they are churn with better
+  manners.
+
+A `skip` verdict carries its reason on the same line — a skipped stage and a stage
+never entered look identical from outside, and they mean opposite things.
+
+## Log
+
+```
+stage: 0 Intake — gate manual — verdict pass — 2026-08-10T11:14Z
+iter:  1 — item B-025 — closed at gate 0
+stage: 1 Docs study — gate auto — verdict pass — 2026-08-10T11:31Z
+touch: src/export.ts — pass 1 (stage 5) — reason: TASK-3
+touch: src/export.ts — pass 2 (stage 5) — reason: F-014
+touch: src/export.ts — pass 3 (stage 5) — reason: F-014
+```
+
+The last two lines are a **trip**: the same file, two consecutive passes, the same
+reason. `references/loop-guard.md` → *Detection* item 2 — the fix did not fix it, or
+the two passes disagree about what *fixed* means. Stop editing and run the break
+protocol; do not dispatch a fourth pass.
+
+## Why it is not the build ledger
+
+`.task-pipeline/build/<plan>/progress.md` covers **one stage** — stage 5's tasks, and
+whether a task was already dispatched (`references/build.md`). This file
+covers **the run**: stage verdicts, iterations, and every repeating pass anywhere in
+the pipeline, including the loops between stages that the build ledger cannot see.
+
+Keeping them separate is deliberate. A run that has no stage-5 work still loops, still
+re-enters stages and still needs a rail — and it would have no ledger at all if the
+run's memory lived inside the build directory that stage 5 deletes.
+
+## What closes it, and what survives it
+
+**This file is git-ignored** — `.task-pipeline/` is, and this lives inside it. It is
+the run's working memory, not its record: it exists to survive a **compaction**, which
+is a different problem from surviving the run.
+
+So stage 10 **reads it and copies out what outlives the run** — the pass counts and
+any loop-guard ruling go into the acceptance file and the retro stamp, which are
+committed. What is not carried out is gone when the directory is cleared, and that is
+the correct outcome for a `touch:` line whose finding has been closed.
+
+Never treat it as evidence in a later run. A file that is not in git cannot be quoted
+at a commit, and a claim nobody can navigate to is the thing this repository's
+documentation canon exists to refuse.