task-pipeline-skill 1.9.1 → 1.10.1

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## v1.10.1 — 2026-08-03
+
+### Fixed — four surfaces that never heard about the last two releases
+
+A fourth audit pass, on a fourth axis: **the claims of the last three releases,
+checked against the tree.** All four findings are the same shape — a file shipped and
+the surfaces that tell a reader it exists were never walked. Reachability from
+`SKILL.md` was green throughout, because that check proves an agent can *find* a file,
+not that anybody was *told* about it.
+
+- **The Cursor rule was two releases behind** — and it is the surface that travels,
+  copied into foreign projects and required to be self-contained. It knew the
+  documentation track and nothing about adoption, the entry audit, portability, the
+  routing boundary or the opt-out phrase: an agent reading it in another repository
+  had no idea when the pipeline applies. Measured `0` for each. Now current.
+- **The README's documentation map** listed `adoption.md` and named neither
+  `setup.md` nor `portability.md` — and had never named `learned.md` at all.
+- **The portability manifest covered 14 of 26 references.** It claims *every workflow
+  decision*, and the twelve stage doctrines — spec, build, planning, review,
+  acceptance, brainstorm, decomposition, tdd, conventions, companion-skills,
+  knowledge-graph, model-tiering — had no row. The guard could not see it: it checked
+  that every listed path resolves, which is the direction that cannot find an absence.
+- **Two seeded templates over 100 lines had no `## Contents`** — the doc map (eight
+  sections) and the brief (nine). The rule was scoped to `references/` while the files
+  a host project actually reads were outside it.
+
+**Two new guards, and they are the point.** Every reference must appear in the README
+map *and* in the manifest; every seeded template over 100 lines carries its own
+Contents. Both check the direction that finds absences, and both were watched failing.
+
+## v1.10.0 — 2026-08-03
+
+### Added — the entry audit, and a boundary that keeps the workflow portable
+
+**`references/setup.md` — the audit that runs *before* the feature.** The ladder in
+`audit.md` runs at the end of a run, over the change; nothing ran at the start, over
+the documentation a project already has. Seven passes, cheapest first — one decision
+home, register integrity, propagation (ratcheted), the matrix's *Checked by* column,
+declared terms, the UX chain, and the gate itself proven against a planted defect.
+Findings carry `file:line`, the minimal fix and **the seam they belong to**, ordered
+by seam rather than by file, because a file-ordered list reads as noise and a
+seam-ordered one names the layer of the project's own process that is leaking. It
+ends in a fix plan, not a lecture, and it **fixes nothing while reading** — that is
+how a pass starts finding its own edits.
+
+**Offered once, never imposed.** Stage 0 asks when the doc map is absent or stale;
+the answer, including a refusal, is recorded in the brief and never asked again. A
+check that runs before every feature is a check people learn to dismiss.
+
+**`references/portability.md` — the boundary the whole bundle rests on.** A decision
+about *how the pipeline behaves* belongs in the bundle; a decision about *what this
+project decided* belongs in the project. Get it backwards and one of two quiet
+failures follows: an optimisation stranded in one repository, or a skill that has
+learned one project's answers and stopped being project-agnostic.
+
+It ships a **manifest** — every workflow decision with its home inside the bundle —
+and a guard that resolves every path. And it names both directions, because a
+comparison needs two sides: *outward*, does every workflow decision have a home here;
+*inward*, is this project holding a rule that would be true in a repository nobody
+has seen. The inward test is one line — **does the rule name a path, a command or a
+person?** If not, it is the bundle's, and keeping it local costs every future project.
+
+**The routing rule now travels.** It was hand-installed into an operator's config
+last release, which made it the one workflow decision living outside the bundle —
+neither installer touches any `CLAUDE.md`. It ships as `templates/routing-rule.md`,
+and `setup` **offers** to append it. Offers, never writes: it is the operator's
+configuration.
+
+### Added — three smaller things the same run asked for
+
+- **Self-currency.** Preflight compares the installed version with the released one
+  and recommends the **launcher** (`npx sshlg-skills update`), never the bare
+  per-skill form that re-creates the plain copy which shadows a plugin. Plus three
+  staleness signals that are not version numbers: a standing instruction that has not
+  fired in five stamps, a doc map older than the last release, a ratchet whose count
+  has not moved.
+- **The escalation boundary.** The autonomy sweep gains the rule that lets a run go
+  further without stopping: decide alone while the cost of being wrong stays inside
+  the repository and is reversible; escalate a price, a legal posture, a promise, money,
+  reputation, and any irreversible outward act. **The tell is the cost of being wrong,
+  not the size of the change.**
+- **User paths become a stage-2 output.** The contract layer was never the thin one —
+  the spec already locks error handling and a module dossier already has edge cases.
+  The thin layer was the *conversation*: `brainstorm.md` mentioned edge cases once and
+  scenarios not at all. Paths, states and error paths are now named where the design
+  is approved, and the gate says so. Scenario IDs stay the chain's job — two sources
+  for one scenario is worse than one.
+- **Declared terms.** The seeded doc map gains a *Terms* table, and only terms it
+  declares are checked. A heuristic over every capitalised word cries wolf, and a gate
+  that cries wolf is removed by the third person who hits it.
+
+Three new guards, each with a negative self-test watched failing.
+
 ## v1.9.1 — 2026-08-03
 
 ### Added — the direction of the artifact map that was missing

package/README.md

@@ -490,6 +490,21 @@ now does:
   discover: author and reviewer are the same person, commits are unsigned, and the
   eval suite has not been executed.
 
+### The entry audit — before the feature, not after
+
+`/task-pipeline setup` runs seven passes over the documentation a project already
+has, and hands back a fix plan rather than a lecture: one decision home, register
+integrity, ratcheted propagation, the matrix's *Checked by* column, declared terms,
+the UX chain, and the gate itself proven against a planted defect. Findings carry
+`file:line`, the minimal fix and **the seam** — ordered by seam, because that names
+which layer of your process is leaking.
+
+Offered once when the doc map is absent or stale, and the refusal is recorded. It
+also runs the **inward check**: does this project hold a rule that would be true in a
+repository nobody has seen? If it names no path, no command and no person, it is the
+bundle's — and keeping it local costs every future project
+([`references/portability.md`](plugins/task-pipeline/skills/task-pipeline/references/portability.md)).
+
 ### Adopting it — a new project, and the one you actually have
 
 Greenfield is mechanical: stage 0 seeds `docs/DOCMAP.md`, the registers and the gate
@@ -762,6 +777,9 @@ recommendation, so you arm the whole run in one exchange. Detail:
 | [`references/model-tiering.md`](plugins/task-pipeline/skills/task-pipeline/references/model-tiering.md) | model policy, the `/model` reminder, overrides |
 | [`templates/`](plugins/task-pipeline/skills/task-pipeline/templates/README.md) | brief, carry-over ledger, `CONTEXT.md` and ADR skeletons, the doc map, both registers, the retro and its archive, the seeded `docgate.sh`, a worked hook |
 | [`references/adoption.md`](plugins/task-pipeline/skills/task-pipeline/references/adoption.md) | the first run in a project: greenfield seeding, and the brownfield walkthrough |
+| [`references/setup.md`](plugins/task-pipeline/skills/task-pipeline/references/setup.md) | the entry audit: seven passes over the docs a project already has, offered once, output as a fix plan |
+| [`references/portability.md`](plugins/task-pipeline/skills/task-pipeline/references/portability.md) | the manifest of workflow decisions and their homes in the bundle, and the boundary against a project's own answers |
+| [`references/learned.md`](plugins/task-pipeline/skills/task-pipeline/references/learned.md) | fifteen rules earned by failure on a real multi-repository build, each with its incident, its check and its exit criterion |
 | [`SKILL-CARD.md`](SKILL-CARD.md) | the registry entry and risk-tier disclosure a reviewer needs before deploying it |
 | [`evals/`](evals/RESULTS.md) | the behavioural evaluation suite, its protocol, and what has actually been observed |
 | [`CHANGELOG.md`](CHANGELOG.md) | every release, with the reasoning behind it |

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
 | **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
-| **Version** | 1.9.1 |
+| **Version** | 1.10.1 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
 | **Evaluation status** | Suite authored (15 evals, 5 categories). **Never executed** — see [`evals/RESULTS.md`](evals/RESULTS.md) |
@@ -34,11 +34,11 @@ apply.
 
 ## What to check before you trust it
 
-1. Read `SKILL.md` and the 24 files under `references/` — that is the whole
+1. Read `SKILL.md` and the 26 files under `references/` — that is the whole
    instruction surface, and every one is linked directly from `SKILL.md`.
 2. Read `templates/docgate.sh` before seeding it; it is the only shipped script a
    host project will run on its own repository.
-3. Run `npm run test:all` — 56 guards, each with a negative self-test that plants a
+3. Run `npm run test:all` — 61 guards, each with a negative self-test that plants a
    defect and requires rejection.
 4. Run `python3 evals/run.py` for the behavioural protocol, and read
    `evals/RESULTS.md` for what has actually been observed.
@@ -54,7 +54,7 @@ apply.
 - **Versions are pinned by git tag** and mirrored into `sshlg-skills`'s catalogue.
   Rollback is `git checkout v<previous>` or pinning the previous plugin version;
   the previous version is never deleted.
-- **Behavioural evidence is missing, not merely thin.** 56 structural guards prove
+- **Behavioural evidence is missing, not merely thin.** 61 structural guards prove
   the skill is well-formed. Until `evals/RESULTS.md` carries a dated run, nothing in
   this repository proves it *behaves* — triggers correctly, stays quiet on a
   question, or performs the steps it documents.

package/cursor/rules/task-pipeline.mdc

@@ -423,3 +423,45 @@ JTBD, customer journey maps, user stories) → flows + screens → scenarios (th
 source of truth) → run its linter. Otherwise still design that chain, get it
 approved, and trace every user-facing requirement to a scenario before building.
 Install (Cursor/Claude/others): `npx skills add ssheleg/super-ux`.
+
+## Routing — when this applies at all
+
+**Work that CHANGES THE REPOSITORY goes through the pipeline** — a feature, fix,
+refactor, migration, integration, rewrite, adoption or hardening pass, in any
+phrasing. **Not** for a question, an explanation, reading code, a typo or a one-line
+edit. The operator opts out of a qualifying task by saying "без пайплайна" or
+"quick"; when they do, say out loud that the cycle was skipped at their request.
+
+A borderline case is named, not silently chosen: state which route you are taking and
+why, in one line.
+
+**Escalation while running.** Decide alone while the cost of being wrong stays inside
+the repository and is reversible. Escalate a price, a legal posture, a promise to
+somebody outside the team, anything spending money or reputation, and any irreversible
+outward act. The tell is the cost of being wrong, not the size of the change.
+
+## The first run in a project
+
+Two entry conditions, and they are different problems.
+
+**A new project:** stage 0 seeds the doc map, the registers and the documentation
+gate before the first interview question. The gate is green on day one because
+sections with nothing to check yet print `dormant`.
+
+**An existing project:** offer the **entry audit** once — seven passes over the
+documentation that already exists, *before* building on it: one decision home,
+register integrity, propagation, the matrix's checked-by column, declared terms, the
+UX chain, and the gate itself proven against a planted defect. Findings carry
+`file:line`, the minimal fix and the **seam**, ordered by seam rather than by file.
+It ends in a fix plan and **fixes nothing while reading**.
+
+The step that decides whether adoption survives is **baselining the ratchets at
+today**: the propagation floor to the next free id, the residue floor to the measured
+count. A gate that is red on adoption day is switched off on day two. History is
+**not** back-filled — an old decision enters the register the day somebody is about to
+contradict it.
+
+**Portability.** A decision about how the pipeline behaves belongs in the skill; a
+decision about what this project decided belongs in the project. The test for a rule
+you are about to write down: does it name a path, a command or a person? If not, it is
+the pipeline's, and leaving it in one repository is a fork nobody named.

package/evals/RESULTS.md

@@ -37,9 +37,9 @@ or it belongs in a check.
 | Dated runs recorded | **0** | 2026-08-03 |
 
 The bottom two numbers are the honest state of this skill's behavioural evidence.
-Everything else in this repository is proven by 56 structural guards that check the
+Everything else in this repository is proven by 61 structural guards that check the
 *form*; these are the only checks that would speak to the *behaviour*, and they have
-not been run yet. Printed here so "56 of 56 green" is never read as "the skill is
+not been run yet. Printed here so "61 of 61 green" is never read as "the skill is
 known to work".
 
 ## Runs

package/package.json

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

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

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

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

@@ -43,3 +43,9 @@ Idempotent entry — inspect state first, never restart blindly:
   **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 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`.

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

@@ -62,6 +62,8 @@ gate stops until it is installed.
 | 10 Retrospective (the run's last act) | [`references/retrospective.md`](references/retrospective.md) |
 | 10 + any audit (what's *missing*) | [`references/audit.md`](references/audit.md) |
 | **first run in a project** (new or existing) | [`references/adoption.md`](references/adoption.md) |
+| **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) |
 
 **Optional bridge.** If the operator already runs an equivalent skill set (e.g.
@@ -332,6 +334,11 @@ automation is on — `pipeline.schema.json` is the only contract.
 - `references/tdd.md` — stages 5–6: the iron law, red/green/refactor, the suite gate
 - `references/stages.md` — per-stage detail + exact gate criteria + gate types
 - `references/model-tiering.md` — model map, ids, the `/model` reminder mechanic, override
+- `references/setup.md` — the entry audit: seven passes over the docs you already
+  have, offered once, output as a fix plan; plus the inward check for rules that
+  belong upstream
+- `references/portability.md` — the manifest of workflow decisions and their homes
+  inside the bundle, and the boundary against a project's own answers
 - `references/adoption.md` — the first run in a project: greenfield seeding, and the
   brownfield walkthrough whose third step baselines the ratchets at today
 - `references/conventions.md` — how stages 6–10 read the host project's CLAUDE.md

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

@@ -21,6 +21,7 @@ approved design — not at code.
 - Working in an existing codebase
 - UI detection — a required output
 - The approved design is a set of decisions — record them
+- User paths are a design output, not a spec detail
 - GATE (manual)
 - Rationalizations
 
@@ -112,10 +113,32 @@ The cost of skipping it is specific: a design approved in conversation and recor
 only in the spec dies with that spec, and the next run re-opens a question the
 operator already answered.
 
+## User paths are a design output, not a spec detail
+
+For anything with a user-facing surface, the design is not done when the components
+are named. Three things come out of **this** stage and feed the stage-3 chain:
+
+1. **The paths** — how a user actually reaches this, start to finish, including the
+   route they take when they arrive from somewhere unexpected.
+2. **The states** — every screen or command has more than the happy one: loading,
+   empty, partial, denied, expired, offline. Name them here; naming them in the spec
+   means the design was approved without them.
+3. **The error paths** — what the user sees when it fails, what they can do next, and
+   what the system says out loud versus logs quietly.
+
+**Why here and not at stage 3.** The spec already locks *Error handling and
+degradation*, and a module dossier already has *Edge and failure cases* — the
+contract layer is not the thin one. What was thin is the conversation: a design
+approved without its error paths is a design whose hardest third is invented later by
+whoever implements it, alone, at stage 5.
+
+Feed them into [`spec.md`](spec.md)'s UX track — super-ux turns them into flows,
+screens and traced scenarios. **Do not draft scenario IDs here**; that is the
+chain's job, and two sources for one scenario is worse than one.
+
 ## GATE (manual)
 
-The operator approves the design **and** the UI verdict is recorded **and every REQ
-in the brief is answered by the design** — a requirement the design doesn't address
+The operator approves the design, **the UI verdict is recorded**, and — where that verdict is *yes* — **the paths, the states and the error paths are named** (above) rather than deferred to the spec. **Every REQ in the brief is answered by the design** — a requirement the design doesn't address
 is either covered now or explicitly dropped by the operator, with the drop written
 into the carry-over ledger. For a platform, the module map
 ([`decomposition.md`](decomposition.md)) is committed and approved as part of this

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

@@ -14,6 +14,7 @@ better, plus one that is required only for user-facing work.
 - The matrix
 - Optional bridge — substituting an external skill set
 - Preflight (emit before stage 0)
+- Is this skill itself current?
 - Credit
 - Hand-off the other direction
 
@@ -144,6 +145,39 @@ Rules:
 - The model answer goes into the brief. Don't ask again per stage
   (`model-tiering.md` → *Mechanic*).
 
+## Is this skill itself current?
+
+Preflight's other question, asked once beside the companion block. A pipeline running
+on a stale copy of its own doctrine repeats a class of failure that was already fixed
+upstream — and nothing in a run would ever reveal it.
+
+```bash
+npx --yes sshlg-skills@latest list      # what the current release of each member is
+```
+
+Compare it with what is installed. Behind → offer the **launcher**, never the bare
+per-skill form:
+
+```bash
+npx --yes sshlg-skills@latest update
+```
+
+The launcher moves the whole family, updates plugins and agent copies together, and
+prunes the plain `~/.claude/skills/<name>/` copies that otherwise shadow a plugin and
+serve the version they were copied from, forever. A bare `npx skills update <name>`
+re-creates exactly that shadow.
+
+**Three staleness signals worth naming**, because none of them is a version number:
+
+| Signal | What it means |
+|---|---|
+| A standing instruction that has not fired in five run stamps | the rule was situational; the prune retires it ([`retrospective.md`](retrospective.md)) |
+| A doc map older than the project's last release | the regime was decided for a project that has since changed shape — `setup` offers the entry audit ([`setup.md`](setup.md)) |
+| A ratchet whose count has not moved in months | either the backlog is genuinely frozen, or nobody is looking at the number printed beside every verdict |
+
+Recommend once, then continue. **Never a gate** — a run blocked on its own updater is
+a run that cannot ship a fix to the updater.
+
 ## Credit
 
 The built-in doctrine is **ported, not depended on**:

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

@@ -141,6 +141,8 @@ explicit "stop and ask me here":
 |---|---|
 | run-wide | the model decision ([`model-tiering.md`](model-tiering.md)); what to decide autonomously vs escalate |
 | 0 Harvest | doc sources beyond this repo — other repos, hosted doc systems, the knowledge wiki, **the code graph** ([`knowledge-graph.md`](knowledge-graph.md): built / installed-not-built / absent) — and whether stage 9 may write to them (another repo is outward: propose + PR, never a direct push) |
+| 0 Setup audit | doc map absent or stale: run the entry audit over the existing documentation before building on it ([`setup.md`](setup.md))? Asked once; a refusal is recorded and never re-asked |
+| run-wide Escalation | cost of being wrong: decide alone while it stays inside the repository and reversible; escalate price, legal posture, promise, money, reputation, irreversible outward acts. Project exceptions? |
 | 0 Docs regime | where settled things live (the decision home — **one** per project, and an existing `docs/adr/` **is** it), who may write it, whether a lease mechanism is present or the run is `ungated`, the gate command and its ratchet floors, and whether this run may raise a floor ([`documentation.md`](documentation.md)) |
 | 1 Docs | external libs/APIs/SDKs in play; any private ones context7 can't resolve → where their docs live |
 | 2 Decompose | is this a platform (several capabilities/surfaces) or one module? if platform: deploy cadence — per module or once at the end |

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

@@ -0,0 +1,127 @@
+# Portability — what travels with the bundle, and what must not
+
+**One job: keep every decision about *how the pipeline behaves* inside the bundle, and
+every decision about *what a project decided* inside that project.** Get this backwards
+in either direction and something breaks quietly: a workflow optimisation stranded in
+one repository, or a skill that has quietly learned one project's answers.
+
+## Contents
+
+- The boundary
+- The manifest — every workflow decision and its home
+- The two checks, in both directions
+- What a host project is allowed to hold
+- Rationalizations
+
+## The boundary
+
+| Kind of decision | Example | Lives in | Travels? |
+|---|---|---|---|
+| **Workflow** — how the pipeline behaves anywhere | the gate types, the loop-guard caps, the Doc Loop's seven steps, the escalation rule, the routing boundary | `references/*.md`, `templates/*`, `pipeline.example.json` | **yes — this is the bundle** |
+| **Project answer** — what *this* repository decided | which register it uses, its propagation matrix, its ratchet floors, its standing instructions | `docs/DOCMAP.md`, the register, `docs/superpowers/retro.md`, the brief | **no — and correctly so** |
+
+Two failures follow from confusing them, and they look nothing alike:
+
+- **A workflow decision left in a project** is a fork of the doctrine that nobody
+  named. The next project starts without it and nobody notices, because the first
+  project still works.
+- **A project answer absorbed into the skill** ends project-agnosticism. The bundle
+  starts asserting things that are true in one repository and false in the next.
+
+**The tell is the question it answers.** *"How does the pipeline behave?"* → bundle.
+*"What did we decide here?"* → project. A rule that would be true in a repository you
+have never seen belongs in the bundle even if you learned it in one.
+
+## The manifest — every workflow decision and its home
+
+Every row's home is a path **inside this skill**. A guard checks each one resolves;
+a row pointing outside the bundle is the defect this file exists to catch.
+
+| Workflow decision | Home |
+|---|---|
+| The stage list, ids, names, gate types | `pipeline.example.json` |
+| Per-stage criteria, freedom levels, the run checklist | `references/stages.md` |
+| What the intake grill asks, and the autonomy sweep | `references/grill.md` |
+| **The escalation boundary** — what an agent may settle alone | `references/grill.md` |
+| The knowledge harvest and its source ledger | `references/knowledge-sources.md` |
+| The documentation system, the Doc Loop, supersede semantics | `references/documentation.md` |
+| Gate types, the enforcement ladder, degrees of freedom, probing | `references/gates.md` |
+| The Claude Code hook contract | `references/hooks.md` |
+| First run in a project: greenfield and brownfield | `references/adoption.md` |
+| 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` |
+| The retro: prune, cap, commits, archive | `references/retrospective.md` |
+| Rules earned by failure | `references/learned.md` |
+| **The routing default and its boundary** | `templates/routing-rule.md` |
+| The seeded doc map, registers and gate | `templates/docmap.md`, `templates/decisions.md`, `templates/open-questions.md`, `templates/docgate.sh` |
+| What a stage reads, and which host files bind it | `references/artifacts.md` |
+| The design conversation, its hard gate, UI detection, user paths | `references/brainstorm.md` |
+| Cutting a platform into modules, brick criteria, build order | `references/decomposition.md` |
+| What a spec must lock, the UX-track order, the module dossier | `references/spec.md` |
+| The zero-context plan format, parallel groups, set equality | `references/planning.md` |
+| Workspace isolation, the subagent loop, who may write the register | `references/build.md` |
+| The review rubric, diff packages, the three verdicts | `references/review.md` |
+| The TDD iron law and the suite gate | `references/tdd.md` |
+| The REQ coverage table, evidence rules, the closing question | `references/acceptance.md` |
+| How the host project's own conventions are read | `references/conventions.md` |
+| Which companions exist, what is required, self-currency | `references/companion-skills.md` |
+| The code graph: queries, refresh, the graph↔docs divergence | `references/knowledge-graph.md` |
+| Model policy — tier not id, ask once at preflight | `references/model-tiering.md` |
+| This boundary | `references/portability.md` |
+
+**The routing rule is the row worth watching.** A skill's `description` raises the
+odds it is selected and cannot make selection mandatory — only an instruction in a
+`CLAUDE.md` can. That instruction is therefore *installed*, not shipped, which is
+exactly how a workflow decision ends up living outside the bundle. The template above
+is the fix: the rule travels as a file, and [`setup.md`](setup.md) **offers** to
+append it. Offers, not writes — it is the operator's configuration.
+
+## The two checks, in both directions
+
+One direction is not enough, for the same reason
+[`learned.md`](learned.md) rule 2 gives: a comparison needs two sides and an absence
+has one.
+
+**Outward — does every workflow decision have a home here?** Mechanical: every path
+in the manifest resolves inside the bundle, and no row names a path outside it. Run
+by the validator on every commit. This catches *"we decided it and forgot to put it
+anywhere portable"*.
+
+**Inward — is this project holding something universal?** Judgemental, and it is
+[`setup.md`](setup.md)'s job: read the host's `CLAUDE.md`/`AGENTS.md`, its doc map
+and its standing instructions, and ask of each rule — *would this be true in a
+repository I have never seen?* If yes, it is a workflow decision wearing a project's
+clothes, and it should be proposed upstream rather than copied to the next project by
+hand. This catches *"the optimisation lives in one repo and dies there"*.
+
+Neither check can be skipped in favour of the other. The outward one is cheap and
+constant; the inward one runs when a project is audited, and it is the only one that
+can find a rule nobody ever wrote down as portable.
+
+## What a host project is allowed to hold
+
+Not a restriction — a list of what *should* stay local, so the inward check does not
+flag it:
+
+- the answers in `docs/DOCMAP.md`: which register, which homes, which matrix rows;
+- the ratchet **values** — floors are measurements of one repository's history;
+- standing instructions that name this project's paths, commands or people;
+- the deploy target, the test command, the branch policy;
+- everything in `docs/ux/` — this project's users, flows and scenarios.
+
+A standing instruction that names **no** path, command or person is a candidate for
+the bundle. That is the cheapest inward test there is, and
+[`retrospective.md`](retrospective.md) already states the rule it serves: a lesson
+true in any repository belongs in the pipeline's own doctrine, not in one project's
+retro.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "It's in our CLAUDE.md, that's good enough" | Good enough for this repository on this machine. The next project starts without it, and nobody notices because this one still works. |
+| "I'll copy the rule into the next project when I get there" | That is the fork, performed by hand, once per project, until two of them disagree and neither is wrong. |
+| "The skill should just learn our conventions" | Then it stops working for anyone else, including you on the next repository. Conventions are answers; the bundle carries questions and procedures. |
+| "This rule is obviously universal, it doesn't need a home" | Every rule is obvious to the person who just learned it. The manifest is one line; the fork is permanent. |
+| "The manifest will go stale" | It is checked, not trusted: every path resolves or the build fails. A stale row is a red build, not a quiet lie. |

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

@@ -0,0 +1,124 @@
+# Setup — the entry audit, before the first feature
+
+**One job: find out what is already wrong with this project's documentation before
+building on top of it.** [`audit.md`](audit.md)'s ladder runs at the *end* of a run,
+over the change. This runs at the *start*, over what is already there — and until
+this file existed, nothing did.
+
+**Offered, never imposed.** Stage 0 asks once, when `docs/DOCMAP.md` is absent or its
+regime line is older than the project's last release. The answer — including "no" —
+is recorded in the brief's autonomy sweep and never asked again.
+
+## Contents
+
+- When it runs
+- What it inspects
+- The finding shape
+- The output is a fix plan, not a lecture
+- The inward check — what this project holds that belongs upstream
+- The offer to install the routing rule
+- Rationalizations
+
+## When it runs
+
+| Situation | What happens |
+|---|---|
+| First run in a repository, no `docs/DOCMAP.md` | [`adoption.md`](adoption.md) seeds; this audit runs against what the seeding found |
+| Existing project, doc map present but stale | offered once at stage 0 |
+| The operator asks for it — `/task-pipeline setup` | runs as the whole task; stages 3–5 produce findings and fixes rather than a feature |
+| Every subsequent run | **not offered again.** The recorded answer stands until the doc map changes |
+
+**Never as a recurring tax.** A check that runs before every feature is a check people
+learn to dismiss. Once per project state, then it is the gate's job.
+
+## What it inspects
+
+Seven passes, cheapest first. Each either reports `ok`, a finding, or **`skipped —
+<why>`**; a silent pass is indistinguishable from a clean one.
+
+1. **The decision home.** Exactly one, and the doc map names it. Two homes is a fork;
+   zero is a project whose decisions live only in commit messages.
+2. **Register integrity.** Ids unique and never renumbered · status vocabulary closed
+   · supersede/contradict targets annotated · no resolved question deleted.
+3. **Propagation.** Every document named in an entry's `Consequences / affects:` line
+   cites that entry — ratcheted, so history is a printed number and not a wall of
+   failures ([`adoption.md`](adoption.md) → *Baseline the ratchets*).
+4. **The matrix.** Every row has a *Checked by* cell — a check, or `review` **with the
+   reason no check can decide it**. An empty cell is a finding, not a blank.
+5. **Terms.** Every term the doc map declares resolves to exactly one definition, and
+   the definition's home actually contains it. **Only declared terms are checked** —
+   a heuristic over every capitalised word cries wolf, and a gate that cries wolf is
+   removed by the third person who hits it ([`gates.md`](gates.md) → *The
+   false-positive budget*).
+6. **The UX chain**, when the project has a user-facing surface: scenarios exist,
+   trace to stories and flows, and the linter passes. A project with screens and no
+   scenarios is building interface before behaviour.
+7. **The gate itself.** It exists, it runs, it exits non-zero on a planted defect, and
+   its verdict prints its ratchets. **An unproven gate's green is worth nothing** —
+   plant one defect and watch it fail before quoting it as evidence.
+
+## The finding shape
+
+Every finding carries three things and nothing else:
+
+```
+docs/ARCHITECTURE.md:214  cites DEC-0081 (retired, superseded twice) without saying so
+   → add the marker beside the citation, or replace it with the live decision
+   seam: L1→L2 (the decision reached the doc and then stopped being true)
+```
+
+`file:line` · the minimal fix · the seam it belongs to. **Ordered by seam, never by
+file** — a file-ordered list reads as noise; a seam-ordered one tells you which layer
+of the project's own process is leaking.
+
+## The output is a fix plan, not a lecture
+
+The audit ends with `docs/superpowers/plans/YYYY-MM-DD-doc-audit.md` — the findings
+turned into tasks the pipeline can run, in the order that makes them terminate:
+
+1. everything the gate can enforce **after** the fix, so the class stops recurring;
+2. the ratchet floors, baselined at today;
+3. the rest, largest seam first.
+
+An audit that hands over a list and no plan is a list somebody will read once.
+
+**Nothing is fixed during the audit.** Reading and repairing in one pass is how a
+pass starts finding its own edits ([`audit.md`](audit.md) → *Every pass changes the axis, not the effort*).
+
+## The inward check — what this project holds that belongs upstream
+
+The other direction, and the one nobody runs by themselves
+([`portability.md`](portability.md) → *The two checks*).
+
+Read the host's `CLAUDE.md`/`AGENTS.md`, its doc map and its standing instructions,
+and ask of each rule: **would this be true in a repository I have never seen?**
+
+- **Names a path, a command, a person, a service** → it is this project's answer.
+  Leave it.
+- **Names none of those** → it is a workflow decision wearing a project's clothes.
+  Report it, and propose it upstream to the bundle rather than copying it by hand
+  into the next project.
+
+That hand-copy is the fork: performed once per project, until two of them disagree and
+neither is wrong.
+
+## The offer to install the routing rule
+
+If the operator's configuration carries no routing rule, offer to append
+[`../templates/routing-rule.md`](../templates/routing-rule.md) — the version that
+travels with the bundle.
+
+**Offer, never write.** It is the operator's configuration, and appending to it
+without asking is the same class of act as pushing to a repository nobody asked you
+to touch. Print the diff, ask once, record the answer.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "The docs are fine, we'd know" | You would know about the contradictions. Absences have one side, and nobody notices a decision that was never written. |
+| "Let's audit after we ship this feature" | Then the feature is built on the part that was wrong, and the audit's first finding is the feature. |
+| "This will take a week" | Seven passes, most of them mechanical, and the ratchet step means you fix nothing today. What takes a week is the fix plan — and that is work you were going to do blind otherwise. |
+| "We'll fix things as we find them" | Then the pass starts finding its own edits and never terminates. Read, then plan, then fix. |
+| "The gate is green, so the docs are good" | The gate proves what it checks. Read its scope header, and plant a defect before quoting its green. |
+| "Our conventions are ours, upstream doesn't need them" | Some of them are, and the inward check leaves those alone. The ones naming no path and no command are the pipeline's, and keeping them local costs you every future project. |

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

@@ -107,6 +107,12 @@ never that the work was skipped quietly.
   existing `docs/adr/` *is* the register and is recorded as such, never duplicated.
   The gate is seeded so that it exits `0` on its own seeds; a project that starts
   red learns on day one that the gate is noise.
+- **Phase 1b+ — offer the entry audit, once** ([`setup.md`](setup.md)). When
+  `docs/DOCMAP.md` is absent or its regime line predates the project's last release,
+  ask whether to audit the documentation that already exists **before** building on
+  it. Record the answer — including a refusal — in the brief's autonomy sweep and
+  never ask again. `audit.md`'s ladder runs at the *end* over the change; this runs
+  at the *start* over what is already there.
 - **Phase 1c — reconcile intent against as-built.** Git says how it *should* be;
   the run record says how it *turned out*. Read both for the area you are about to
   touch and resolve every divergence — the document is stale, the record is wrong,

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

@@ -18,6 +18,7 @@ from `super-ux`.
 | `open-questions.md` | `docs/OPEN_QUESTIONS.md` | 0 seeds it, the Doc Loop resolves rows |
 | `docgate.sh` | `scripts/check-docs.sh` | 0 seeds it · 9 runs it · 10 proves it |
 | `hooks.example.json` | the project's `.claude/settings.json` | 0 — offered, never installed silently |
+| `routing-rule.md` | the operator's `CLAUDE.md` — **offered by `setup`, never written silently** | 0 / `setup` |
 | `retro.md` | `docs/superpowers/retro.md` — **one per project, not per run** | 10 writes (prune → stamp → entry), 0 reads it in full |
 | `retro-archive.md` | `docs/superpowers/retro/YYYY-QN.md` | 10 rotates into it, 0 **queries** it |
 

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

@@ -9,6 +9,18 @@
 - **UI verdict:** yes / no — does this touch a user-facing surface (web/mobile/CLI/TUI)?
   If yes, the stage-3 super-ux UX track is armed.
 
+## Contents
+
+- Knowledge sources (the phase-1 harvest — written BEFORE the first question)
+- Documentation (the phase-1b inventory — the four questions)
+- Scope
+- Requirements (the REQ spine — every later stage traces to these IDs)
+- Users & context
+- Decisions locked (the grill's output)
+- Autonomy (the sweep — stages 1→10 read this instead of asking)
+- Done-criteria
+- Open assumptions / risks
+
 ## Knowledge sources (the phase-1 harvest — written BEFORE the first question)
 
 What the project already knew about this task, and where it said so. One row per
@@ -103,8 +115,10 @@ is not neutral — it is a scheduled interruption.
 | Stage | Question | Answer |
 |---|---|---|
 | run-wide | Model for this run | … (most capable available unless overridden; per-stage overrides here) |
+| run-wide Escalation | … | cost of being wrong: decide alone while it stays inside the repository and reversible; escalate price, legal posture, promise, money, reputation, irreversible outward acts. Project exceptions? |
 | run-wide | Decide autonomously vs escalate to me | … |
 | 0 Harvest | Doc sources beyond this repo — other repos, hosted docs, the knowledge wiki, the code graph; and may stage 9 write to them? | … (another repo is outward: propose + PR, never a direct push; graph built / not built) |
+| 0 Setup audit | … (yes / no — recorded either way) | doc map absent or stale: run the entry audit over the existing documentation before building on it (the skill's `references/setup.md`)? Asked once; a refusal is recorded and never re-asked |
 | 0 Docs regime | Where settled things live (register or ADR set — one home, never both); who may write it; lease mechanism present, or is this run `ungated`? Gate command + ratchet floors; may this run raise a floor? | … |
 | 1 Docs | External libs/APIs/SDKs in play; any context7 can't resolve → where their docs live | … |
 | 2 Decompose | Platform (several capabilities/surfaces) or one module? If platform — deploy cadence: per module, or once at the end | … |

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

@@ -10,6 +10,17 @@ elsewhere — where another file already says it, this one holds a **pointer lin
 not a copy. A doc map that duplicates `AGENTS.md` is the first violation of the
 rule it publishes.
 
+## Contents
+
+- Regime
+- Registers
+- Single source of truth
+- Propagation matrix
+- Gates
+- Ratchets
+- Terms
+- Navigation
+
 ## Regime
 
 `governed` — established <YYYY-MM-DD> by run `<topic>`, recorded as `DEC-0001`.
@@ -78,6 +89,21 @@ Raising a floor is a decision and belongs in the register.
 | Propagation backlog | `PROP_FLOOR` | 0 | <YYYY-MM-DD> |
 | `<fill me>` | … | … | … |
 
+## Terms
+
+Only terms **declared here** are checked. A heuristic over every capitalised word
+cries wolf, and a gate that cries wolf is removed by the third person who hits it —
+so this table is the project's own list, and it may start with three rows.
+
+| Term | Definition lives in | Anchor |
+|---|---|---|
+| `<Entity>` | `docs/DATA_MODEL.md` | `#entity` |
+| `<fill me>` | `<the one document that defines it>` | `#anchor` |
+
+Rules: **one definition per term**, the anchor resolves, and a document that uses the
+term links to that anchor rather than restating it. A term with two definitions is
+the same defect as a fact with two homes.
+
 ## Navigation
 
 - One definition per entity, with an explicit anchor.

package/plugins/task-pipeline/skills/task-pipeline/templates/routing-rule.md

@@ -0,0 +1,50 @@
+# Routing rule — the portable version
+
+**Copy this into the operator's `CLAUDE.md`** (global `~/.claude/CLAUDE.md`, or a
+project's, or both). `setup` **offers** to append it; it never writes to an
+operator's configuration silently.
+
+**Why it is a file and not just the skill's description.** A skill's `description`
+raises the odds the model selects it and cannot make selection mandatory — the choice
+stays with the model, case by case. Only an instruction makes routing binding. That
+instruction therefore has to be *installed*, which is exactly how a workflow decision
+ends up living outside the bundle ([`../references/portability.md`](../references/portability.md)).
+Shipping it as a template is what lets it travel.
+
+**Keep the exclusions identical** to the skill's `description` and to the
+`should_not_trigger` evaluations. Three copies of one boundary that drift are worse
+than no boundary.
+
+---
+
+## Routing — repo-changing work goes through the pipeline
+
+**When `task-pipeline` is installed, any work that CHANGES THE REPOSITORY goes
+through it** — without being asked for. A feature, a fix, a refactor, a migration, an
+integration, a rewrite, an adoption, a hardening pass; in any language and any
+phrasing. Saying *"run this through the pipeline"* is an accelerator, not a
+precondition.
+
+**The boundary is "changes the repository", and it cuts both ways.** Not through the
+pipeline:
+
+- a question and its answer, an explanation, reading or mapping code;
+- a typo, a one-line edit, a mechanical rename;
+- reconnaissance or measurement that commits nothing.
+
+Running ten gated stages for one character is the fastest way to teach an agent to
+route around the pipeline entirely.
+
+**The opt-out is "без пайплайна" or "quick".** It applies to a task that *would*
+qualify: do it directly, and **say out loud** that the cycle was skipped at the
+operator's request — never silently.
+
+**A borderline case is named, not silently chosen.** *"Clean up the error handling"*
+can be a two-line fix or a day's refactor. State which route you are taking and why,
+in one line.
+
+**Escalation while running.** Decide alone while the cost of being wrong stays inside
+the repository and is reversible. Escalate a price, a legal posture, a promise made to
+somebody outside the team, anything that spends money or reputation, any change to
+what a customer's data is used for, and any irreversible outward act. The tell is the
+**cost of being wrong**, not the size of the change.