task-pipeline-skill 1.33.0 → 1.38.0

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

@@ -1,8 +1,8 @@
 {
   "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.33.0",
+  "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 closes with evidence, a work board and a verification ledger that outlive a run, an exposure line naming what shipped unconfirmed, a progress rail computed from the project's own config, a loop guard whose review ceiling measures rather than stops, and stage-3 tracks for what a product does, how it sounds and how it looks. Two modes need no task: `checkup` (what is unverified) and `setup` (audit existing docs). Retro insights can publish upstream as issues, opt-in and redacted.",
+  "version": "1.38.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -1,62 +1,173 @@
 ---
-description: Run a task through task-pipeline — an intake grill that expands the request, then docs → brainstorm → spec → plan → build → tests → deploy → post-deploy → docs/wiki → acceptance.
-argument-hint: "<one-line task description>"
+description: "Run a task through task-pipeline's gated stages (intake grill → docs → brainstorm → spec → plan → build → tests → deploy → post-deploy → docs/wiki → acceptance). Also: `setup` — audit the docs you already have; `checkup` — what has shipped unverified, with no task running."
+argument-hint: "<one-line task> | setup | checkup"
 ---
-Use the `task-pipeline` skill to run the task below through all gated stages —
-**stage 0 intake grill** → docs study → brainstorm → spec → plan → subagent
-build → tests → lint/deploy → post-deploy → docs/wiki → **acceptance**. **Every stage's doctrine is
-built into the skill** (`references/{knowledge-sources,knowledge-graph,grill,brainstorm,decomposition,spec,planning,build,review,tdd,acceptance,retrospective,loop-guard}.md`)
-— no companion plugin is required for any of them. **Stage 0 opens with the
-knowledge harvest, before the first question** (`references/knowledge-sources.md`):
-pull what the project already knows about this task from the code, **the code graph**
-if one is built ([graphify](https://github.com/Graphify-Labs/graphify) —
-`references/knowledge-graph.md`; recommended, never required; detect
-`graphify-out/graph.json`; it answers *reach* — what calls this, what breaks if it
-moves — which grep cannot), `CLAUDE.md`,
-`CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs, **the retro's standing
-instructions** (`docs/superpowers/retro.md` — read in full, they bind this run;
-`references/retrospective.md`), the **knowledge wiki**
-if one is installed ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) —
-recommended, never required; detect `~/.obsidian-wiki/config`) and any **other repo
-or hosted doc system the project names as its docs**, then write the **source
-ledger** into the brief. The **intake grill is
-mandatory** (`references/grill.md`): interview the
-operator one question at a time (with a recommended answer each, exploring the
-codebase before asking) until every decision branch is resolved, **validating every
-answer against the harvested sources** — the operator outranks any document, but
-only out loud, and a doc the run proves stale is logged for the stage-9 update —
-applying the
-grill's **domain awareness** (challenge terms against `CONTEXT.md`, sharpen fuzzy
-language, ADRs for hard-to-reverse calls) and covering the **autonomy sweep** (what
-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, and **the board** (`docs/superpowers/backlog.md`, `references/backlog.md`) — the work-list between runs — is read at stage 0 with its open count quoted in the brief, or seeded when absent; **the verification ledger** (`docs/superpowers/verification.md`, `references/verification.md`) is read at stage 0 for how many rows sit at `never`, written at stage 8 with one row per shipped REQ, and required at stage 10 in both directions. 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 every ledger row still `open`, `unresolved` or homed `backlog` leaves stage 10 with a board id and the board's priorities are re-derived (`references/backlog.md`); 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, or in sixty days — the calendar is the unit that still moves when the stamp counter has stopped), 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.
+Run the task below through `task-pipeline`'s gated stages. **Every stage's doctrine
+ships inside the skill** — no companion plugin is required for any of it. The
+reference files are indexed in `SKILL.md`; this page is the run order, not the index.
 
 Task: $ARGUMENTS
 
-Idempotent entry — inspect state first, never restart blindly:
-- If a pipeline TaskList from a previous run already exists for this task,
-  **resume** from the first incomplete stage instead of starting over.
-- Otherwise, begin at stage 0 (intake grill). If no task is given above, the
-  grill's first question asks the operator for the task in one line.
-
-**`/task-pipeline checkup`** — **runs with no task in flight, and that is the point.**
-Accumulated unconfirmed work is invisible precisely because nobody is running a pipeline,
-so a check living only inside a run can never say *"stop, fourteen things are
-unconfirmed."* It takes no brief, opens no grill, and writes nothing on its own. Four
-sections, each read from a file this pipeline already keeps: the **exposure** line with
-its check-list oldest-first, the **board**'s open rows by computed priority, the
-carry-over ledgers' unresolved count, and the code graph's staleness where one exists.
+> **Two other modes.** `setup` audits the documentation this project already has;
+> `checkup` reports what has shipped without a person confirming it, with no task in
+> flight. Both are at the bottom of this page.
+
+**Idempotent entry — inspect state first, never restart blindly.** If a pipeline
+TaskList from a previous run exists for this task, **resume** from the first incomplete
+stage. Otherwise begin at stage 0. With no task given, the grill's first question asks
+for it in one line.
+
+---
+
+## Preflight — settle these once
+
+- **Model.** Recommend the most capable one the environment offers, never a hardcoded
+  id. Confirmed once, then the whole run uses it without re-asking.
+- **Companions.** Print the detection block once (`references/companion-skills.md`).
+  Absent ones state their fallback; none is a gate except the stage-3 UX track on a
+  user-facing task.
+
+## Stage 0 — the harvest, then the grill
+
+**The harvest runs before the first question** (`references/knowledge-sources.md`).
+Pull what the project already knows about *this task*:
+
+- the code, and **the code graph** where one is built — [graphify](https://github.com/Graphify-Labs/graphify),
+  `references/knowledge-graph.md`; recommended, never required; detect
+  `graphify-out/graph.json`. It answers **reach** — what calls this, what breaks if it
+  moves — which grep cannot.
+- `CLAUDE.md`, `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past briefs and carry-over ledgers.
+- **the retro's standing instructions and run stamps** — `docs/superpowers/retro.md`,
+  read in full; both are bounded and they bind this run. Its **Recent log** is
+  *queried* by the task's nouns, not read: nothing caps it, and an uncapped section
+  inside a binding source is what makes the capped part get skimmed
+  (`references/retrospective.md`).
+- the **knowledge wiki** if installed ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki);
+  detect `~/.obsidian-wiki/config`), and any other doc system the project names as its docs.
+- **the board** (`docs/superpowers/backlog.md`) — open count quoted in the brief, or
+  seeded when absent. **the verification ledger** (`docs/superpowers/verification.md`) —
+  how many rows sit at `never`.
+
+Write the **source ledger** into the brief: a row per source, or an explicit *none found*.
+
+**Then the grill, and it is mandatory** (`references/grill.md`). One question per turn,
+each with a recommended answer, exploring the codebase before asking, until every
+decision branch is resolved.
+
+- **Validate every answer against the harvested sources.** The operator outranks any
+  document — but only out loud, and a doc the run proves stale is logged for stage 9.
+- **Domain awareness:** challenge terms against `CONTEXT.md`, sharpen fuzzy language,
+  write an ADR for a hard-to-reverse call.
+- **The autonomy sweep** pre-resolves what would otherwise stop stages 1→10: doc
+  sources, wiki and graph, branch and tracker policy, test and lint commands, deploy
+  target and authorization, log locations.
+- **UI tasks add the design surface.** Is the design done visually in Figma or
+  text-only? Is the Figma MCP connected? If not — ship text-only, or stop and connect
+  it? The UX chain degrades on its own and never blocks, so this choice must be
+  recorded rather than discovered.
+- **With Figma on, the destination is named before the first frame:** which team/org,
+  which file — the recorded one, a URL the operator gives, or creation in that named
+  team explicitly authorized. 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 does not resolve, stop and ask — never create a
+  replacement.**
+
+**The brief closes on the REQ table** — the request as an addressable list where every
+row names how it is verified. Frozen: adding is free, removing needs the operator.
+Anything deferred enters the carry-over ledger the moment it is said.
+
+## Stages 1→10 — the flow
+
+| | Stage | The thing that must be true to leave it |
+|---|---|---|
+| 1 | Docs study | every contract the design will lock is grounded on fetched docs, not recall |
+| 2 | Brainstorm + decompose | the design is approved and every REQ is answered by it. **A platform is cut into modules** (`references/decomposition.md`) — map committed, walking skeleton first, every REQ in exactly one module; stages 3→10 then run per module |
+| 3 | Spec | contracts locked; user-facing work runs three tracks — what it **does** (super-ux), how it **sounds** (`copywriting`), how it **looks** (`sheleg-design`); a declined track is recorded, never silent |
+| 4 | Plan | the REQ set-comparison holds: brief REQs == union of `Implements:` |
+| 5 | Build | TDD per task, a review after each, findings fixed or parked with a ruling |
+| 6 | Tests | the **full** suite green; a web surface checked in a browser, not in the diff |
+| 7 | Lint + deploy | outward: the authorization is specific, and the CI verdict is **read** before any tag |
+| 8 | Post-deploy | the verification trio, not one of three; a verification row per shipped REQ |
+| 9 | Docs + wiki | **three artifacts, not two** — module docs, the wiki, **and the code graph** |
+| 10 | Acceptance | the ladder walk first, then the table, then the retrospective |
+
+**Honor every gate by its type**: `auto` — verify the check yourself; `manual` — wait
+for an explicit go.
+
+## Cross-cutting — the three that fire at any stage
+
+**The loop guard** (`references/loop-guard.md`). If a pass starts undoing an earlier one
+— the same file edited twice for the same reason, a closed finding returning, a third
+entry into one stage — stop editing. 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 review
+loop has its own ceiling, and at it the run **measures** rather than stops.
+
+**The audit's exit** (`references/audit.md`). If a searching pass starts finding mostly
+what the previous pass's own fixes broke, the axis is exhausted — rotate it, do not look
+harder.
+
+**Evidence.** A green from a check nobody has watched fail against a planted defect is
+not evidence. A finding class seen twice becomes a script, not a third ledger row.
+
+## Stage 9 — the graph is the third artifact
+
+Refresh it (`/graphify . --update` where `graphify-out/` exists), then **check it 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 here; absences
+become REQ rows at stage 10.
+
+A stale graph is a false premise **carrying the authority of a machine** — a wrong doc
+gets argued with, a wrong graph gets believed.
+
+## Stage 10 — the close-out, in order
+
+1. **The ladder walk, first.** The REQ table finds what was named and lost; it cannot
+   find what was never named, because a comparison needs two sides and an absence has
+   one. Walk each REQ bottom-up — decision → spec section → contract *and its failure
+   behavior* → task → change → executed test → surface/docs — check the seam at each
+   step, and order findings **by seam, not by file**. Every absence becomes a new REQ
+   row **before** the coverage table is written.
+2. **The table**, one row per REQ, each with evidence.
+3. **The ledgers close.** Every carry-over row still `open`, `unresolved` or homed
+   `backlog` leaves with a board id, and the board's priorities are re-derived. The
+   counts print beside every gate verdict, so *green* never reads as *verified*.
+4. **Several repositories? The parent closes too.** A parent records each submodule as a
+   pointer to one commit, and moving the submodule does not move the pointer — so work
+   can be committed, pushed and green while a clone of the parent still gets the commit
+   before it. Neither repo looks wrong alone. Require `git submodule status` with no
+   line starting `+`, and every repo clean and pushed. The fix is two commands and the
+   second gets forgotten: push the submodule, **then** `git add <submodule> && git commit`.
+5. **The retrospective is the run's last act** (`references/retrospective.md`), in this
+   order: **stamp the run first** (its commit makes the cold trigger computable) → **prune**
+   every standing instruction against its three retirement triggers, list held to ten,
+   every deletion logged → **write an entry only if the run diverged**: symptom with
+   evidence, the stage it surfaced at, the stage that *owned* it, the root cause, the
+   fix by grade, and the check that catches it next time.
+
+Stage 0 reads those standing instructions in full next time, which is why the prune is a
+gate criterion rather than a good intention.
+
+---
+
+## `/task-pipeline checkup`
+
+**Runs with no task in flight, and that is the point.** Accumulated unconfirmed work is
+invisible precisely because nobody is running a pipeline, so a check living only inside a
+run can never say *"stop, fourteen things are unconfirmed."*
+
+It takes no brief, opens no grill, and writes nothing on its own. Four sections, each
+read from a file this pipeline already keeps: the **exposure** line with its check-list
+oldest-first, the **board**'s open rows by computed priority, the carry-over ledgers'
+unresolved count, and the code graph's staleness where one exists.
+
 Where you ask it to file what it found, it appends board rows whose `Source` names the
-checkup and its date — printing what it would add first, never silently. Doctrine:
-`references/exposure.md`.
-
-**`/task-pipeline setup`** — the entry audit instead of a feature. Runs seven passes
-over the documentation this project already has, reports findings as `file:line` + the
-minimal fix ordered by seam, and hands back a fix plan the pipeline can run. Offered
-once at stage 0 when the doc map is absent or stale; run it directly any time.
-Doctrine: `references/setup.md`.
+checkup and its date — printing what it would add first, never silently.
+Doctrine: `references/exposure.md`.
+
+## `/task-pipeline setup`
+
+**The entry audit instead of a feature.** Seven passes over the documentation this
+project already has, findings reported as `file:line` + the minimal fix ordered by seam,
+and a fix plan the pipeline can run. Offered once at stage 0 when the doc map is absent
+or stale; run it directly any time. Doctrine: `references/setup.md`.

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

@@ -1,6 +1,6 @@
 ---
 name: task-pipeline
-description: "Runs a substantial task through a full delivery pipeline: an intake grill that expands the request into a locked brief, then docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy check, docs/wiki sync and acceptance — gated stages whose doctrine ships inside this skill (no required companions). Use when work changes the repository — a feature, fix, refactor, migration, integration, rewrite, adoption or hardening; фича, фикс, рефактор, миграция, интеграция, доработать, починить, внедрить — or on 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline. Not for: answering a question, explaining or reading code, a typo or a one-line edit — say 'без пайплайна' / 'quick' to opt out. The grill is mandatory and front-loads every decision, so stages 1→10 run without mid-flight questions; documentation is a deliverable with its own gate; recommends super-ux for user-facing work; confirms one model up front, never a hardcoded id."
+description: "Runs a substantial task through a full delivery pipeline: an intake grill that expands the request into a locked brief, then docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy check, docs/wiki sync and acceptance — gated stages whose doctrine ships inside this skill (no required companions). Use when work changes the repository — a feature, fix, refactor, migration, integration, rewrite, adoption or hardening; фича, фикс, рефактор, миграция, интеграция, доработать, починить, внедрить — or on 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline. Two modes need no task at all: 'checkup' / 'чекап' reports what has shipped without a person confirming it and what to look at first; 'setup' audits the documentation a project already has. Not for: answering a question, explaining or reading code, a typo or a one-line edit — say 'без пайплайна' / 'quick' to opt out."
 license: MIT
 ---
 
@@ -67,6 +67,7 @@ gate stops until it is installed.
 | **first run · the entry audit** (offered once) | [`references/setup.md`](references/setup.md) |
 | **what travels with the bundle vs stays in a project** | [`references/portability.md`](references/portability.md) |
 | any repeating loop | [`references/loop-guard.md`](references/loop-guard.md) |
+| run-wide · what the run **prints about itself** — the rail, the iteration line | [`references/progress.md`](references/progress.md) |
 | run-wide · how a run keeps going (the loop mode + the context budget) | [`references/continuity.md`](references/continuity.md) |
 | run-wide · the work-list **between** runs, and how its priority is computed | [`references/backlog.md`](references/backlog.md) |
 | run-wide · whether a **human** ever confirmed what shipped, and when | [`references/verification.md`](references/verification.md) |
@@ -118,10 +119,10 @@ question: pull what the project already knows about this task from the code, the
 ([`references/knowledge-graph.md`](references/knowledge-graph.md) — graphify;
 recommended, never required),
 `CLAUDE.md`, `CONTEXT.md`/ADRs, **the decision register**, `docs/` + `docs/ux/`,
-past pipeline briefs, **the retro's standing instructions, run stamps and recent
-log** — `docs/superpowers/retro.md`, read in full because they *bind* this run and
-are bounded by construction, while the archive under `docs/superpowers/retro/` is
-**queried** by the task's nouns
+past pipeline briefs, **the retro's standing instructions and run stamps** —
+`docs/superpowers/retro.md`, read in full because they *bind* this run and are
+bounded by construction (ten rows; one line per run), while its **recent log** and the
+archive under `docs/superpowers/retro/` are **queried** by the task's nouns
 ([`references/retrospective.md`](references/retrospective.md)) —
 the **knowledge wiki** if one is installed
 ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) — recommended, never

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
@@ -114,13 +122,27 @@ Pipeline companions (stage doctrine is built in — nothing to install for it):
 🧠 Model for this run: recommended <top tier available>. You're on <current>.
    /model <id> to switch, or "keep current", or name per-stage overrides.
 
+⚠  This skill's own behaviour is unverified: evals/RESULTS.md records <N> blind
+   run(s) on <M> model(s). Its triggering and its stage compliance are authored,
+   not measured. Nothing here is blocked by that — you are told because a skill
+   that never says so is one you would assume had been tested.
+
 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
@@ -153,6 +175,13 @@ Rules:
   reserve ids before minting them. Absent → print the line **once**, continue, and
   **record the run as `ungated`** — never describe the project as protected
   ([`documentation.md`](documentation.md) → *Registers are shared state*).
+- **The behaviour line prints whenever `evals/RESULTS.md` records no blind run**, and
+  disappears the moment one is recorded — it is a state of the evidence, not a warning
+  and not a ratchet. This bundle asks every project it touches for evidence rather than
+  assertion, and until 2026-08-10 it made the opposite claim about itself by saying
+  nothing: **one self-observed run by the author, zero blind runs on zero models**, with
+  a preflight that reported companion availability in detail and its own confidence not
+  at all. A skill silent about its own evidence is read as tested.
 - **Never gate any stage on an install** except the stage-3 UX track on a UI task.
 - Optional tools missing → state the fallback, don't block.
 - Re-detect after the operator installs; don't assume.