task-pipeline-skill 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 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
+
+`references/artifacts.md` mapped **stage → what it writes → who consumes it** and
+nothing the other way. What an agent actually needs at runtime is **what each stage
+reads, and from where** — and that direction had been absent since the file was
+written. It is `references/learned.md` rule 2 (*compute the mapping in both
+directions*) left unapplied to this file itself: the direction that feels redundant
+is the one that finds things.
+
+Two tables now sit above the old one:
+
+- **Stage → input map** — per stage, the exact inputs and their origin. Stage 9's row
+  is the one worth reading twice: it takes **two different lists**, the stage-0 source
+  ledger (what the run *read*) and the doc map's propagation matrix (what the run
+  *owes*), and the gap between them is where documentation rots.
+- **Project-saved rules, and where each one binds** — the eight files a host project
+  owns that change how a run behaves, each with where it is read and where it is
+  enforced: `CLAUDE.md`/`AGENTS.md`, `docs/DOCMAP.md`, the retro's standing
+  instructions, the brief's autonomy section, the carry-over ledger,
+  `docs/ux/scenarios.md`, `.claude/agent-sync.json`, and the operator's global config
+  that decides whether a task routes here at all. Plus the precedence rule: for *what
+  is*, code wins; for *what should be*, the register wins, and the gap is a finding
+  rather than a tie-break.
+
+A guard holds all three maps present, with a negative self-test watched failing.
+
 ## v1.9.0 — 2026-08-03
 
 ### Added — the adoption track, and default-on inside a stated boundary

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

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.0 |
+| **Version** | 1.10.0 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
 | **Evaluation status** | Suite authored (15 evals, 5 categories). **Never executed** — see [`evals/RESULTS.md`](evals/RESULTS.md) |
@@ -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` — 55 guards, each with a negative self-test that plants a
+3. Run `npm run test:all` — 59 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.** 55 structural guards prove
+- **Behavioural evidence is missing, not merely thin.** 59 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/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 55 structural guards that check the
+Everything else in this repository is proven by 59 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 "55 of 55 green" is never read as "the skill is
+not been run yet. Printed here so "59 of 59 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.0",
+  "version": "1.10.0",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"

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

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

@@ -8,6 +8,7 @@ shape.
 ## Contents
 
 - In the host project
+- Stage → input map — where each stage's information comes from
 - Stage → artifact map
 - This repo (task-pipeline itself), for reference
 
@@ -65,6 +66,52 @@ Stage 5 also creates a **git-ignored** scratch workspace per plan at
 review packages. It is deleted when the final review is clean; git history is the
 record (see `build.md`).
 
+## Stage → input map — where each stage's information comes from
+
+The map below this one answers *what a stage writes*. This one answers *what it
+reads, and from where* — the direction that was missing, which is
+[`learned.md`](learned.md) rule 2 (*compute the mapping in both directions*) applied
+to this file itself. A stage whose inputs are unnamed is a stage that will read
+whatever the context happens to hold.
+
+| Stage | Reads | From where |
+|---|---|---|
+| **0 Harvest** | the project's own knowledge about this task | code · the code graph (`graphify-out/`) · `CLAUDE.md`/`AGENTS.md` · `CONTEXT.md`/`docs/adr/` · `docs/` + `docs/ux/` · past briefs and carry-over ledgers · the retro's standing instructions **in full** · the wiki · any doc repo or hosted system the project names |
+| **0 Inventory (1b)** | the documentation regime | `docs/DOCMAP.md` — registers, single homes, propagation matrix, gate commands, ratchet floors. Absent ⇒ seeded ([`adoption.md`](adoption.md)) |
+| **0 Reconcile (1c)** | intent vs as-built | git (how it *should* be) against the run record (how it *turned out*) |
+| **0 Grill** | the operator | the interview — every answer checked against the harvest, which is what makes it checkable rather than confident |
+| **1 Docs study** | external library/API contracts | `context7:resolve-library-id` → `context7:query-docs`; web search where it cannot resolve. **Never from recall** |
+| **2 Brainstorm** | what is already settled | the brief (scope, constraints, done-criteria) + the codebase. Re-asking what the grill answered is this stage's most common waste |
+| **3 Spec** | the approved design + the UX chain | stage-2 design · `docs/ux/{foundation,flows,screens,scenarios}.md` (UI only) · the Figma canonical record in `docs/ux/foundation.md` → *Design tooling* · `DOCMAP.md` for where a settled contract is recorded |
+| **4 Plan** | the spec and the frozen list | the spec's locked contracts and **Global Constraints** · the brief's REQ ids (the gate is a set comparison against them) |
+| **5 Dev** | one task at a time | the plan task · the spec's Global Constraints, copied verbatim · host test/lint commands · the brief's branch policy. **A subagent reads only its own file-based brief** — that is the whole of its context |
+| **6 Tests** | the host's runner | `CLAUDE.md`/`AGENTS.md` → *Lint + test*, else detection ([`conventions.md`](conventions.md)) |
+| **7 Lint + deploy** | the host's lint and deploy path, and the authorization | host conventions · the brief's autonomy sweep, where a standing go must name target **and** preconditions |
+| **8 Post-deploy** | where health lives | the brief's autonomy sweep (app name, endpoint, workflow) |
+| **9 Docs + registers** | two different lists | the stage-0 **source ledger** (what this run *read*) **and** `DOCMAP.md`'s **propagation matrix** (what this run *owes*). They are not the same list, and the gap between them is where documentation rots |
+| **10 Acceptance** | everything the run produced | the brief's REQ table · the carry-over ledger **in full** · plan task statuses · `git log` · the final suite output · stage-8 notes · stage-9 changes · `docs/ux/scenarios.md` + `/ux-lint` for UI |
+
+### Project-saved rules, and where each one binds
+
+These are the files a **host project** owns that change how a run behaves. An agent
+that has not read them is running the pipeline's defaults, not this project's.
+
+| Rule file | What it binds | Read at | Enforced at |
+|---|---|---|---|
+| `CLAUDE.md` / `AGENTS.md` | commands, deploy path, house rules, which docs exist and where | 0 | 6–10 |
+| `docs/DOCMAP.md` | the decision home, each fact's single home, the propagation matrix, the gate and its ratchet floors | 0 (1b) | 9 |
+| `docs/superpowers/retro.md` | standing instructions — the rules no check can decide. Capped at ten, **read in full**, stamped the moment one fires | 0 | pruned at 10 |
+| `specs/<topic>-brief.md` → *Autonomy* | every pre-resolved decision; stages 1→10 **answer from it instead of asking** | 0 | 1–10 |
+| `specs/<topic>-carryover.md` | everything deferred, parked or half-done; appended the moment it is said | all | read in full at 10 |
+| `docs/ux/scenarios.md` | the source of truth for user-facing behaviour (super-ux) | 3 | 3, 7, 9, 10 |
+| `.claude/agent-sync.json` | which registers are guarded, and by whose lease | 0 | every guarded write |
+| the operator's global `CLAUDE.md` | whether a task routes here at all, and the opt-out phrase | before stage 0 | — |
+
+**Precedence when two of them disagree.** For *what is*: code, then host docs and
+ADRs, then the wiki, then memory. For *what should be*: the register outranks the
+code, because a decision not yet built is still the decision — and the gap between
+them is a finding, not a tie-break ([`knowledge-sources.md`](knowledge-sources.md)).
+
 ## Stage → artifact map
 
 | Stage | Writes | Consumed by |

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,115 @@
+# 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` |
+| 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

@@ -103,8 +103,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

@@ -78,6 +78,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.