task-pipeline-skill 1.33.0 → 1.37.0

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

@@ -4,18 +4,32 @@
   "title": "task-pipeline config",
   "description": "Generic contract for a pipeline config. An ordered list of stages; each stage is run by the host project's own skills/agents and guarded by a typed gate. The framework imposes no specific stages, skills, or gate assignments — those are entirely the host project's config. Copy pipeline.example.json and rewrite it to match your project.",
   "type": "object",
-  "required": ["stages"],
+  "required": [
+    "stages"
+  ],
   "additionalProperties": true,
   "properties": {
-    "version": { "type": "integer", "minimum": 1 },
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
     "stages": {
       "type": "array",
       "minItems": 1,
       "description": "The pipeline stages, in order. Any number, any names — your project's real stages.",
-      "items": { "$ref": "#/definitions/stage" }
+      "items": {
+        "$ref": "#/definitions/stage"
+      }
+    },
+    "release": {
+      "$ref": "#/definitions/release"
+    },
+    "run": {
+      "$ref": "#/definitions/run"
     },
-    "release": { "$ref": "#/definitions/release" },
-    "run": { "$ref": "#/definitions/run" }
+    "retro": {
+      "$ref": "#/definitions/retro"
+    }
   },
   "definitions": {
     "run": {
@@ -25,12 +39,17 @@
       "properties": {
         "loop": {
           "type": "object",
-          "required": ["mode"],
+          "required": [
+            "mode"
+          ],
           "additionalProperties": true,
           "description": "Whether the run advances item by item without a discretionary check-in. It NEVER collapses a manual gate or an outward action — a generic flag is not a specific authorization.",
           "properties": {
             "mode": {
-              "enum": ["off", "interval"],
+              "enum": [
+                "off",
+                "interval"
+              ],
               "description": "off (the default when absent) = the run pauses between items as it always did. interval = the run is armed with the harness's own loop primitive and advances one item per fire, stopping only at a manual gate, an unresolvable block, a genuine ambiguity, or completion."
             },
             "interval": {
@@ -43,6 +62,18 @@
               "description": "How this harness arms it, e.g. '/loop'. Harness-specific and therefore project-recorded rather than assumed: on a harness with no loop primitive, omit it — the mode then degrades to prose discipline plus the build ledger, and the run says so instead of implying it is armed."
             }
           }
+        },
+        "review": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "The review loop's ceiling. Absent, the default is 3 rounds per artifact. It is a DECISION POINT rather than a stop: at the cap the run prints new findings versus findings caused by its own fixes, per round, and either the pair ends the loop or the operator continues it out loud. A flat stop would be wrong — this repository's ten-round runs were still finding real defects on round nine. Doctrine: references/loop-guard.md.",
+          "properties": {
+            "maxRounds": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Rounds per artifact before the run stops reviewing and measures. Counted from the run ledger's `touch:` pass numbers, never from memory; a round that finds nothing ends the loop by definition and is not counted."
+            }
+          }
         }
       }
     },
@@ -50,48 +81,129 @@
       "type": "object",
       "additionalProperties": true,
       "description": "Optional release automation, entirely project-defined and INDIVIDUALLY TOGGLEABLE. Omit the whole object, or set enabled:false, to turn release automation off for this project. The framework ships an example workflow (.github/workflows/release.yml) whose job is gated on a repo variable so each project arms it on its own; this block is the declarative counterpart the orchestrator reads.",
-      "required": ["enabled"],
+      "required": [
+        "enabled"
+      ],
       "properties": {
-        "enabled": { "type": "boolean", "description": "Master on/off toggle. false (or the object omitted) = no release automation for this project." },
-        "trigger": { "enum": ["tag", "manual", "push", "none"], "description": "What kicks off a release (e.g. a pushed vX.Y.Z tag, manual dispatch)." },
+        "enabled": {
+          "type": "boolean",
+          "description": "Master on/off toggle. false (or the object omitted) = no release automation for this project."
+        },
+        "trigger": {
+          "enum": [
+            "tag",
+            "manual",
+            "push",
+            "none"
+          ],
+          "description": "What kicks off a release (e.g. a pushed vX.Y.Z tag, manual dispatch)."
+        },
         "steps": {
           "type": "array",
-          "items": { "type": "string", "minLength": 1 },
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
           "description": "Ordered release actions, in prose — project-specific (e.g. create a GitHub release, npm publish). Human-only steps (2FA publish) are named as such."
         },
         "verify": {
           "type": "array",
-          "items": { "type": "string", "minLength": 1 },
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
           "description": "Post-release smoke checks that must pass after a release — this is the release's own post-deploy gate (stage 8 applied to shipping the package itself)."
         }
       }
     },
     "stage": {
       "type": "object",
-      "required": ["state", "skills", "gate"],
+      "required": [
+        "state",
+        "skills",
+        "gate"
+      ],
       "additionalProperties": true,
       "properties": {
-        "id": { "type": "integer", "description": "Optional ordinal." },
-        "state": { "type": "string", "minLength": 1, "description": "Unique stable key for the stage." },
-        "name": { "type": "string", "description": "Optional human label." },
-        "model": { "type": "string", "description": "Optional model for the stage. Prefer a provider-agnostic token over a vendor id, which goes stale as generations ship and may not exist on the operator's provider at all: 'default' = the model confirmed for this run (recommended: the most capable reasoning model the environment offers), 'inherit' = whatever the operator is currently on. A literal id is allowed but treated as an example, not a contract." },
+        "id": {
+          "type": "integer",
+          "description": "Optional ordinal."
+        },
+        "state": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Unique stable key for the stage."
+        },
+        "name": {
+          "type": "string",
+          "description": "Optional human label."
+        },
+        "model": {
+          "type": "string",
+          "description": "Optional model for the stage. Prefer a provider-agnostic token over a vendor id, which goes stale as generations ship and may not exist on the operator's provider at all: 'default' = the model confirmed for this run (recommended: the most capable reasoning model the environment offers), 'inherit' = whatever the operator is currently on. A literal id is allowed but treated as an example, not a contract."
+        },
         "skills": {
           "type": "array",
           "minItems": 1,
           "description": "The skill(s)/agent(s) that execute this stage. Any names your environment resolves — this is where you plug in your OWN skills.",
-          "items": { "type": "string", "minLength": 1 }
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
         },
         "gate": {
           "type": "object",
-          "required": ["type", "check"],
+          "required": [
+            "type",
+            "check"
+          ],
           "additionalProperties": true,
           "description": "Condition that must pass before advancing to the next stage.",
           "properties": {
             "type": {
-              "enum": ["auto", "manual"],
+              "enum": [
+                "auto",
+                "manual"
+              ],
               "description": "auto = the orchestrator verifies `check` itself (pass/fail); manual = wait for the operator's explicit go."
             },
-            "check": { "type": "string", "minLength": 1, "description": "The gate condition, in prose." }
+            "check": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The gate condition, in prose."
+            }
+          }
+        }
+      }
+    },
+    "retro": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional. Governs what the retrospective does BEYOND writing to the project's own docs/superpowers/retro.md, which always happens. Omit it and nothing leaves the repository: silence arms nothing, exactly as it authorises no deploy.",
+      "properties": {
+        "publish": {
+          "type": "object",
+          "required": [
+            "repo"
+          ],
+          "additionalProperties": true,
+          "description": "Publish skill-level insights as issues on the skill's own repository, so a defect in the pipeline is fixed once instead of rediscovered in every project. OFF unless this object is present — opening an issue in another repository is an outward act, and an outward act taken from a generic flag is one nobody authorized. The body is printed in full before it is sent, and the printed string and the sent string are the same string. Doctrine, including the five redaction rules: references/retrospective.md.",
+          "properties": {
+            "repo": {
+              "type": "string",
+              "pattern": "^[^/\\s]+/[^/\\s]+$",
+              "description": "owner/name of the SKILL's repository, never the host project's."
+            },
+            "label": {
+              "type": "string",
+              "description": "Applied to every issue opened this way, so the operator can read them as a stream rather than find them by accident."
+            },
+            "redact": {
+              "enum": [
+                "strict"
+              ],
+              "description": "Only 'strict' exists, and it is not a level among others: the five rules are the contract. A field with one legal value is here so a reader asking 'what redaction applies?' finds the answer in the config rather than assuming none does."
+            }
           }
         }
       }

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

@@ -59,9 +59,15 @@ at a glance.
 > external skill**. A host project may relocate the root via its `CLAUDE.md`; keep
 > the shape, keep the slugs.
 
-Loop-bearing runs also keep a **git-ignored** run ledger at `.task-pipeline/run.md` —
-stage-level and program-level repeat touches, one line each, so the loop guard can
-detect churn after a lost context (see [`loop-guard.md`](loop-guard.md)).
+**Every** run keeps a **git-ignored** run ledger at `.task-pipeline/run.md`, seeded at
+stage 0 from [`../templates/run.md`](../templates/run.md). Three line shapes: a
+`stage:` verdict when a gate returns, an `iter:` line when an iteration closes, and a
+`touch:` line per file per repeating pass. Two readers depend on it —
+[`loop-guard.md`](loop-guard.md) detects churn from the `touch:` lines after a lost
+context, and [`progress.md`](progress.md) derives the stage rail and the iteration
+counter from the other two. It was described as loop-only until 2026-08-10 and, in
+practice, written by no run at all: the guard that calls its own detection *mechanical*
+had no input in any run to date.
 
 Stage 5 also creates a **git-ignored** scratch workspace per plan at
 `.task-pipeline/build/<plan-basename>/` — ledger, task briefs, implementer reports,
@@ -158,12 +164,13 @@ plugins/task-pipeline/
       acceptance.md retrospective.md          #   stage 10 (close-out, then the retro)
       audit.md                                #   cross-cutting: the ladder + seams
       loop-guard.md                           #   cross-cutting: churn detection
+      progress.md                             #   cross-cutting: what the run prints about itself
       stages.md model-tiering.md              #   gates, model policy
       conventions.md artifacts.md             #   host conventions, this layout
       companion-skills.md                     #   optional companions + preflight
     templates/                                # skeletons seeded into a host project
-      hygiene.sh                            # -> scripts/check-hygiene.sh (stages 5, 6, 9)
-      README.md brief.md carryover.md context.md adr.md retro.md
+      hygiene.sh docgate.sh                 # -> scripts/check-hygiene.sh, check-docs.sh
+      README.md                             # the index — and it is the list, not a copy of it
 cursor/rules/task-pipeline.mdc                # Cursor channel (self-contained rule)
 bin/task-pipeline.js                          # npx installer (package task-pipeline-skill)
 install.sh                                    # POSIX installer

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

@@ -43,7 +43,8 @@ better, plus one that is required only for user-facing work.
 
 | Skill / tool | Needed for | Required? | Install |
 |---|---|---|---|
-| **super-ux** (`ux-foundation`, `ux-flows`, `ux-scenarios`, `ux-audit`, `/ux`, `/ux-lint`) | stage 3 UX track | **Required for any user-facing task** | `/plugin marketplace add ssheleg/super-ux` → `/plugin install super-ux@super-ux` (or `npx skills add ssheleg/super-ux`) |
+| **super-ux** (`ux-foundation`, `ux-flows`, `ux-scenarios`, `ux-audit`, `/ux`, `/ux-lint` — **and the copy half**: `copywriting`, `brand-voice`, `/brand-init`, `/copy`, `/brand-lint`, plus `/vision`) | stage 3 — the **UX track** *and* the **COPY track**. This row named six surfaces until 2026-08-10 while super-ux shipped eight skills and fifteen commands: the whole brand-and-copy half was invisible to this pipeline, so a run built scenarios and screens and then wrote the interface strings by taste | **Required for any user-facing task** | `/plugin marketplace add ssheleg/super-ux` → `/plugin install super-ux@super-ux` (or `npx skills add ssheleg/super-ux`) |
+| **sheleg-design** (`/sheleg-design`) | stage 3 — the **VISUAL track**: tokens and themes, typography and rhythm, motion and how it degrades to rest, the visual language a brand is recognised by. It answers *how it looks*, which no other companion here answers — `super-ux` decides what the interface must do, `copywriting` how it sounds. Before 2026-08-10 this skill appeared once in the whole bundle, as a name in a list | **Recommended** on any task with a visual surface; never a gate. Absent → the run says the visual layer shipped **undesigned**, which is the honest name for picking values at the keyboard | `/plugin marketplace add ssheleg/sheleg-design` → `/plugin install sheleg-design@sheleg-design-skill` |
 | **context7** (MCP — call tools fully qualified: `context7:resolve-library-id`, `context7:query-docs`) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
 | **Figma** (MCP) | stage 3 UX track, when the project designs visually — super-ux mirrors each `SCR-` screen/state into a frame | Optional, **UI + Figma-on only**. Absent → super-ux degrades to text-only *by itself and never blocks*, so shipping a UI feature with no mockups becomes a silent scope call — which is why the stage-0 sweep decides it | connect the Figma MCP server (`/mcp`, or your claude.ai connectors) |
 | **[obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (`wiki-query`, `wiki-update`) | **stage 0 harvest** (query what's already known) **+ stage 9 sync** | **Recommended** — never a gate; absent → harvest runs on repo docs alone | `pip install obsidian-wiki` → `obsidian-wiki setup --vault /path/to/your/vault` |
@@ -77,9 +78,16 @@ exchange:
 
 ```
 Pipeline companions (stage doctrine is built in — nothing to install for it):
-  ✗ super-ux           — this task looks user-facing; required for the UX track:
+  ✗ super-ux           — this task looks user-facing; required for the UX track,
+                         and it also owns the COPY track (copywriting, brand-voice):
                            /plugin marketplace add ssheleg/super-ux
                            /plugin install super-ux@super-ux
+  ✗ sheleg-design      — this task has a visual surface; it owns the VISUAL track:
+                         tokens, themes, typography, rhythm, motion and its rest state:
+                           /plugin marketplace add ssheleg/sheleg-design
+                           /plugin install sheleg-design@sheleg-design-skill
+                         (running without it — the visual layer ships undesigned,
+                          and the close-out says so in those words)
   ✓ context7           — ready
   ✗ Figma MCP          — this task is user-facing and the project designs in Figma
                          (docs/ux/foundation.md → Design tooling). Without it the
@@ -120,7 +128,16 @@ Install the ✗ items you want, answer the model line, then say "continue".
 Rules:
 
 - Only flag **super-ux** when the task implies a UI (the stage-0 grill decides;
-  when unsure, flag it — a false positive costs one install).
+  when unsure, flag it — a false positive costs one install). It arms **two** tracks,
+  not one: the UX chain and the copy layer.
+- **sheleg-design**: flag it when the task has a **visual** surface — a page, a screen,
+  a themed component, a landing, a dashboard. Detect via a resolving `/sheleg-design`.
+  **A CLI, a library, a backend service or an internal script does not flag it**, and
+  neither does a purely structural change to an existing screen: choosing a palette for
+  a log parser is how a recommendation is taught to be noise, and this bundle already
+  spent a rule learning that about the browser. Absent → the run continues and says the
+  visual layer shipped **undesigned**; that is a weaker claim and the close-out records
+  it as one, exactly as it does for a surface verified by reading the diff.
 - **obsidian-wiki**: detect via `~/.obsidian-wiki/config` or a resolving
   `wiki-query`/`wiki-update`. Present → say `✓ ready` and use it in the harvest.
   Absent → print the two install lines **once** and continue; never ask twice in a

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

@@ -140,6 +140,16 @@ whole cycle that no gate reads. It cites the measurement or it is not written
 `B-NNN`, not a description**: *"next up: B-014"* can be checked against the file,
 *"next up: the export fix"* cannot.
 
+**And it is printed, in one fixed shape** ([`progress.md`](progress.md)):
+
+```
+▶ <topic> · <module> (N/M) · <id> <stage> <gate> · iter <N> · gates <N/M> · next B-NNN
+```
+
+The iteration number is a count of `iter:` lines in `.task-pipeline/run.md`, not a
+number the agent is carrying. After a compaction the agent's count is gone and the
+file's is not — which is the argument the build ledger already won one stage down.
+
 ## Parked at a manual gate
 
 A fixed interval firing into a `manual` gate is a nag. Five minutes later it fires

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

@@ -37,9 +37,16 @@ defect. Until then it is named honestly.
 ## The components, each named
 
 ```
-exposure: 99 unverified · never checked · 31 releases since the last human confirmation
+exposure: N unverified · never checked · N releases carry one
 ```
 
+**The example carries no numbers, deliberately.** It said `99 unverified` and
+`31 releases since the last human confirmation` until 2026-08-10 — one figure lifted
+from this repository's live count, which drifts, and one wording the code has never
+printed. A worked example that disagrees with its own output teaches the wrong format
+to every reader who trusts the doctrine over the terminal, and this one disagreed in
+both directions at once.
+
 - **unverified** — rows whose `Human` reads `never`.
 - **since** — days since the newest `Human` date. When **no** row has ever been
   confirmed, this prints the literal **`never checked`**, not `0 days`: zero would read

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

@@ -22,6 +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 break protocol
 - When to stop and hand back
 - Rationalizations
@@ -30,7 +31,8 @@ searches.
 
 You cannot detect churn from memory, especially after compaction. Every repeating
 pass appends one line to the run's ledger (`.task-pipeline/build/<plan>/progress.md`
-for stage 5; `.task-pipeline/run.md` for stage-level and program-level loops):
+for stage 5; `.task-pipeline/run.md` for stage-level and program-level loops —
+**seeded at stage 0** from [`../templates/run.md`](../templates/run.md)):
 
 ```
 touch: <file> — pass <N> (<stage|round|module>) — reason: <finding id / gate item>
@@ -40,6 +42,12 @@ One line per file per pass. The reason must name **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.
 
+**This ledger was required here from the day the file shipped and written by no run
+until 2026-08-10.** The detection below calls itself mechanical; with no ledger it had
+no input at all, so the guard sat on rung 1 while every reader took it for rung 3
+([`gates.md`](gates.md) → *Axis B*). It is now seeded at stage 0 and named in that
+stage's gate — which is the whole difference between a rule and a rule that runs.
+
 ## Detection — any one of these trips the guard
 
 1. **Revert-oscillation.** An edit restores something an earlier pass in this run
@@ -59,7 +67,48 @@ finding id, a failed gate item, an operator instruction. "Cleanup", "polish" and
 
 Caps that trip the guard by themselves: **5 fix rounds** per task
 ([`build.md`](build.md)), **2 re-entries** per stage per artifact, **3 passes** per
-module in the program loop.
+module in the program loop, and **3 review rounds** per artifact — which is not a stop
+but a measurement, below.
+
+## The review loop — a cap that measures rather than stops
+
+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
+repository's own run stamps say what that cost — **ten rounds, ten, eight, four,
+three** — against a stated ceiling of two re-entries per stage. Nothing tripped,
+because a review round was named in no cap.
+
+**A flat cap would have been the wrong fix.** Every one of those runs recorded *"none
+from my probes"* beside its count: the reader was still finding real defects on round
+nine. Stopping at two would have shipped them.
+
+So the cap is a **decision point**. Default **3 rounds** per artifact, recorded in
+`pipeline.json` → `run.review.maxRounds`. On reaching it, stop reviewing and print the
+pair [`audit.md`](audit.md) already defines — new findings, and findings caused by this
+run's own fixes — per round:
+
+```
+review cap reached — 3 rounds — artifact: test/validate.py
+  round 1: 12 new · 0 self-inflicted
+  round 2:  5 new · 1 self-inflicted
+  round 3:  1 new · 3 self-inflicted
+```
+
+- **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.
+
+**The pair is the whole point.** A round count alone says how tired everyone is; the
+pair says whether the loop still produces anything. Measured on one file once, the
+guard's shapes and the run's own prose disagreed — one still paying, one exhausted —
+so a single number would have stopped the half that was working and continued the half
+that was not.
+
+**Rounds are counted from the ledger, never from memory**: distinct `pass N` values on
+`touch:` lines at the review stage. A round that finds nothing ends the loop by
+definition and needs no counting.
 
 ## The break protocol
 
@@ -109,6 +158,7 @@ far cheaper than a third round of the same argument.
 | Excuse | Reality |
 |---|---|
 | "One more pass and it converges" | Two passes with the same reason already proved it doesn't. The disagreement is above the code. |
+| "The reviewer is still finding things, so keep going" | Then say so with the pair: new versus self-inflicted, per round. If new still leads, that is an argument. Ten rounds with nobody counting is not. |
 | "I'll just revert to what worked" | That is the oscillation, not the exit. Name A and B first. |
 | "The reviewer keeps changing its mind" | Different findings on the same lines mean the requirement is ambiguous. That's a spec question. |
 | "Tidying while I'm in the file" | Untracked edits are what make churn invisible. One reason per change, in the ledger. |

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

@@ -52,6 +52,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | The entry audit and what it inspects | `references/setup.md` |
 | The ladder, seams, axis rotation, ratchets | `references/audit.md` |
 | Loop detection and its caps | `references/loop-guard.md` |
+| **What the run prints about itself** — the header block, the rail, the iteration line | `references/progress.md` |
 | **The run mode** — item-by-item pacing, default off, what it never collapses | `references/continuity.md` |
 | **The context budget** — the evidence rule and what a flush actually updates | `references/continuity.md` |
 | **The board** — the work-list between runs, its computed priority, and the ledger seam it resolves | `references/backlog.md` |

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. |