task-pipeline-skill 1.67.0 → 1.68.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## v1.68.0 — the worst body in the family, and the rule that was wrong about it
+
+**6685 tokens against a 5000 budget → 4735**, under the 4750 working limit, by
+splitting rather than trimming. This was the largest `SKILL.md` body in the
+ssheleg family and the furthest over — 34% — and the body loads on every turn of
+every session that resolves the skill.
+
+Most of the overrun sat in the **stage table's Gate column**, which restated
+`references/stages.md` under a heading that literally says *(detail in
+`references/stages.md`)*. The table is the index and the run order now; the
+reference is what you read while standing in the stage. Nothing was deleted:
+
+| Moved | To | Why there |
+|---|---|---|
+| Stage 10 in a project of several repositories | `references/acceptance.md` | it owns stage-10 close-out |
+| Step 5's cross-cutting rules | `references/gates.md` | they fire at any stage, not inside step 5 |
+
+and five *Prerequisites* paragraphs that restated a reference in full were cut to
+the rule plus the failure it prevents — which is what a body is for — with the
+procedure left in the file that owns it.
+
+**All 38 routed trigger phrases across both skills survive verbatim**
+(`node test/advertised_check.js`), and the stage list still matches across the
+three surfaces the validator compares mechanically.
+
+### The description rule was wrong, and this repository was already right
+
+The family's shared auditor demands a description **start** with `Use when …`.
+This repository's own validator refuses exactly that, and its comment says why:
+Anthropic's guidance asks for **both** halves — what the skill does and when to
+use it — and their own example leads with the capability (*"Extracts text and
+tables from PDF files… Use when working with PDF files."*). Demanding `Use when`
+at position 0 enforces the WHEN half and leaves the WHAT half optional.
+
+So the 2026-08-16 audit's finding that this description *"does not open with Use
+when, against the house rule its sibling obeys"* is **withdrawn — the house rule
+is the one that is wrong**, and this repository had corrected its own copy of it
+already. Applying the corrected rule to the family measures **22 of 24 skills**
+opening with the trigger, so flipping it rewrites 22 descriptions that carry live
+routing phrases. That is a family decision rather than a member's, and it is
+filed as umbrella `B-76` rather than taken here.
+
+### Fixed
+
+- A negative self-test was pinned to a literal containing a **line break**, so it
+  stopped landing the moment the paragraph reflowed — the guard then read green
+  while proving nothing. Matched by regex now. Same class as the two that refused
+  `seo-aeo-audit`'s release earlier the same day, and the reason the local gate
+  there learned to catch it before the tag.
+
+Guards: 351 → **351**. No guard was added or removed — one plant was repaired, and
+the suite that reports `all 351 guards provably reject their planted defect` was
+red until it was, which is the whole point of counting them.
+
+Found by the nine-repository audit of 2026-08-16 (umbrella `B-66`;
+`F-task-pipeline-01`, and `F-task-pipeline-02` withdrawn).
+
 ## v1.67.0 — a ledger records two different things, and most record only one
 
 **A ledger records two different things, and most record only one.** *What confirmed 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.67.0 |
+| **Version** | 1.68.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, and **one of two browser channels** — `playwright` (CLI or MCP) or `chrome-devtools` (MCP); either satisfies the browser step and neither is required. 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, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: task-pipeline
-description: "Runs a substantial task through a full delivery pipeline: an intake grill that locks the request into a brief, then docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy check, docs/wiki sync and acceptance. Use when work changes the repository — a feature, fix, refactor, migration, integration, rewrite, adoption or hardening; фича, фикс, рефактор, миграция, интеграция, доработать, починить, внедрить, перевести — or when the output is a finding that lands in it: audit/аудит, bug hunt/проверь ошибки, production check/проверь прод, PR review/ревью PR — or on 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline. Two modes need no task at all: 'checkup' / 'чекап' reports what shipped unconfirmed and what to look at first; 'setup' audits existing documentation. Not for: answering a question, explaining code, a typo or a one-line edit — say 'без пайплайна' / 'quick' to opt out."
+description: "Runs a substantial task through a full delivery pipeline: an intake grill that locks the request into a brief, then docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki sync and acceptance. Use when work changes the repository — a feature, fix, refactor, migration, integration, rewrite, adoption or hardening; фича, фикс, рефактор, миграция, интеграция, доработать, починить, внедрить, перевести — or when the output is a finding that lands in it: audit/аудит, bug hunt/проверь ошибки, production check/проверь прод, PR review/ревью PR — or on 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline. Two modes need no task at all: 'checkup' / 'чекап' reports what shipped unconfirmed and what to look at first; 'setup' audits existing documentation. Not for: answering a question, explaining code, a typo or a one-line edit — say 'без пайплайна' / 'quick' to opt out."
 license: MIT
 ---
 
@@ -79,76 +79,60 @@ gate stops until it is installed.
 | 6–10 · How the host project's CLAUDE.md is read | `references/conventions.md` |
 | preflight · Model map, ids and the override | `references/model-tiering.md` |
 
-**Optional bridge.** An equivalent skill set the operator already runs (e.g.
-`superpowers:brainstorming` / `writing-plans` / `subagent-driven-development` /
-`using-git-worktrees` / `test-driven-development`) can be mapped onto stages 2/4/5/6
-in `pipeline.json` → `skills[]`. That is a **substitution, never a requirement**: the
-built-in doctrine is normative, the gates in `references/stages.md` still govern, and
-nothing detects, recommends or waits for an external provider.
+**Optional bridge.** An equivalent skill set the operator already runs can be mapped
+onto stages 2/4/5/6 in `pipeline.json` → `skills[]`. That is a **substitution, never a
+requirement**: the built-in doctrine is normative, the gates in `references/stages.md`
+still govern, and nothing detects, recommends or waits for an external provider.
 
 **super-ux — recommended for ANY user-facing task**, and the one thing that can stop a
-gate. The moment a task implies an interface (web / mobile / CLI / TUI — the stage-0
-grill detects it early), the WHY→UI→scenario chain runs through `/ux`,
-`ux-foundation`, `ux-flows`, `ux-scenarios` and the `/ux-lint` linter, which belongs in
-the host's CI so UX drift cannot merge. **Not installed on a UI task? The stage-3 spec
-gate stops** — offer `/plugin marketplace add ssheleg/super-ux` and
-`/plugin install super-ux@super-ux` (or `npx skills add ssheleg/super-ux`) and wait.
-Details: `references/companion-skills.md`.
+gate. The moment a task implies an interface (web / mobile / CLI / TUI), the
+WHY→UI→scenario chain runs through `/ux` and its linter, which belongs in the host's
+CI so UX drift cannot merge. **Not installed on a UI task? The stage-3 spec gate
+stops** — offer the install and wait (`references/companion-skills.md`).
 
 **The grill is built in and mandatory** (`references/grill.md`). No "clear enough task"
-exemption, no stage 1 without a committed, operator-confirmed brief; the one sanctioned
-bypass is the entry-from-super-ux short-circuit, and even that demands a scope
-confirmation. It produces the **REQ spine** — the request as an addressable list, each
-row naming how it is verified. Stages 3–5 trace to those ids, stage 4's gate is a
-mechanical set-comparison against them, and **stage 10 accounts for every one**, which
-is what turns the pipeline from a funnel into a circle.
+exemption and no stage 1 without a committed, operator-confirmed brief. It produces the
+**REQ spine** — the request as an addressable list, each row naming how it is verified —
+which stages 3–5 trace to, stage 4 set-compares against, and **stage 10 accounts for
+every one of**, turning the pipeline from a funnel into a circle.
 
 **Harvest before you ask** (`references/knowledge-sources.md`). Stage 0 opens by
-pulling what the project already knows about *this* task — the code and its graph,
-`CLAUDE.md`, `CONTEXT.md`/ADRs, the decision register, `docs/` and `docs/ux/`, past
-briefs, the wiki, and whatever else the project names as its docs. **The retro is read
-two ways and the difference matters:** its standing instructions and run stamps are
-read **in full** because they bind this run and are bounded by construction; its recent
-log and archive are **queried** by the task's nouns, because nothing caps them
-(`references/retrospective.md`). Write the source ledger into the brief and interview
-*against* it: every answer touching a source is checked against it, and the operator
-outranks any document — **but only out loud**, so an override is a recorded decision
-rather than an undetected divergence. That ledger is also stage 9's work list.
+pulling what the project already knows about *this* task, writes the source ledger
+into the brief, and then interviews **against** it — so the operator outranks any
+document, **but only out loud**, and an override is a recorded decision rather than
+an undetected divergence. That ledger is also stage 9's work list. Which sources,
+and the two ways the retro is read — standing instructions in full because they
+bind this run, the log queried because nothing caps it — are in
+`references/knowledge-sources.md` and `references/retrospective.md`.
 
 **Three artifacts close a run, not two — and they are a convergence, not a sequence.**
-Stage 9 syncs the docs, the wiki **and the code graph** (`/graphify . --update`). None of
-the three consumes another; all three consume the same change, and the **graph↔docs
-divergence check is the gate over their convergence** rather than an extra nicety. That is
-why it is not optional where a graph exists: it is the only thing that compares two of the
-three outputs against each other. The graph is what the next run's harvest queries
-first, so a stale one is a false premise **carrying the authority of a machine** —
-a wrong doc gets argued with, a wrong graph gets believed. Refreshing it buys the
-graph↔docs divergence check; doc-side findings are fixed at stage 9, absences become
-REQ rows at stage 10 (`references/knowledge-graph.md`, `references/audit.md`).
+Stage 9 syncs the docs, the wiki **and the code graph**. None consumes another; all three
+consume the same change, and the **graph↔docs divergence check is the gate over their
+convergence** — the only thing that compares two of the three against each other, which
+is why it is not optional where a graph exists. A stale graph is a false premise
+**carrying the authority of a machine**: a wrong doc gets argued with, a wrong graph gets
+believed (`references/knowledge-graph.md`, `references/audit.md`).
 
 **Documentation is a deliverable, and it has a gate** (`references/documentation.md`).
-A second stage-0 phase asks the four questions that make docs a *system* — where
-settled things live, each fact's single home, what a change of type X obliges, what
-proves it — and writes them to `docs/DOCMAP.md`. From then the **Doc Loop** fires
-whenever anything is settled, at **any** stage rather than only at stage 9; the stage-9
-sweep walks the **propagation matrix** (the harvest ledger names what you *read*, the
-matrix names what you *owe*); and *"docs in sync"* becomes a command with an exit code.
+Stage 0 answers the four questions that make docs a *system* into `docs/DOCMAP.md`;
+from then the **Doc Loop** fires whenever anything is settled, at **any** stage rather
+than only at stage 9, the stage-9 sweep walks the **propagation matrix** — the harvest
+ledger names what you *read*, the matrix names what you *owe* — and *"docs in sync"*
+becomes a command with an exit code.
 
 **The run teaches the next run, and the list stays short**
 (`references/retrospective.md`). Every gate is good at *this* run and blind across
 runs, so one class of failure can be caught, fixed and forgotten five times with
-nothing noticing it is the same one. Stage 10's last act: **stamp the run first** — the
-only thing that makes the next step computable — **then prune** every standing
-instruction against its retirement triggers, hold the list to a hard cap of **ten**,
-log every deletion, and write an entry **only if the run diverged** (symptom, the stage
-that *owned* it, root cause, fix, and the check that catches it next time).
-
-Stage 0 reads those standing instructions in full, which is exactly why the prune is
-a gate criterion and not a good intention: a rule nobody reads to the end is worse
-than no rule, because everyone believes it is covered. **The order is load-bearing,
-not stylistic** — one retirement trigger counts firings across the last five run
-stamps, so a prune placed ahead of the stamp reads a counter its own stage writes
-afterwards and can never run on real data (`references/learned.md` rule 21).
+nothing noticing it is the same one. Stage 10's last act, **in this order and the
+order is load-bearing**: stamp the run, then prune, then write the entry — a
+retirement trigger counts firings across the last five stamps, so a prune placed
+ahead of the stamp reads a counter its own stage has not written yet. The cap, the
+triggers and what an entry must carry are in `references/retrospective.md`; why
+the order cannot be swapped is `references/learned.md` rule 21.
+
+Stage 0 reads those standing instructions in full, which is why the prune is a gate
+criterion and not a good intention: a rule nobody reads to the end is worse than no
+rule, because everyone believes it is covered.
 
 Three things the grill does beyond clarifying the request:
 - **Domain awareness.** It reads the project's own `CONTEXT.md` / `docs/adr/` and
@@ -210,40 +194,13 @@ Three things the grill does beyond clarifying the request:
    stop/return on fail; for `manual`, present the result and **wait for the
    operator's explicit "continue"/go** — an auto gate never substitutes for a
    required manual approval.
-5. Cross-cutting, every stage: **when anything is settled — scope, a contract, a
-   name, a policy, a vocabulary — run the Doc Loop
-   (`references/documentation.md`) before the run moves on**: reserve the id,
-   record it, resolve the question it answers, propagate by the matrix, commit
-   with the ids. A decision that lives only in the spec dies with the spec, and one
-   that lives only in the conversation was never made;
-   **answer from the brief's autonomy section rather
-   than asking again** — it was grilled precisely so you wouldn't have to;
-   **anything deferred, dropped or left half-done goes into the carry-over ledger
-   the moment it's said** — deferred out loud is forgotten; **never narrow the task
-   silently** — the REQ list is frozen, adding is free, removing needs the
-   operator's explicit agreement; **when a loop starts undoing an earlier pass —
-   the same file edited twice for the same reason, a closed finding coming back, a
-   third entry into one stage — stop and run the loop guard**
-   (`references/loop-guard.md`): name the two shapes, escalate to the layer that
-   owns the conflict, re-plan the check as an ordered list, then go through it one
-   item at a time; **when a pass is *searching* rather than editing and starts
-   finding mostly what the previous pass's own fixes broke, the axis is exhausted —
-   rotate it, don't look harder** (`references/audit.md`); **every gate
-   prints `holds: N` — what this run left running** across the eight classes
-   (background shells, monitors, scheduled loops, coordination leases, worktrees,
-   containers, scratch files, remote state), enumerated **by class and never by a
-   single tool**, and stage 10 does not close while this run's residue is live and
-   unaccounted (`references/residue.md`); and remember that a
-   green from a check nobody has watched fail is not evidence; task
-   tracker + conventional commits per host conventions; worktree isolation for the
-   build, integrated back per the brief's branch policy before stage 7; honest
-   degradation (never claim a failed/skipped step succeeded);
-   outward/irreversible actions (deploy, publish, repo create, opening a PR,
-   **editing a shared design file — frames are read by designers and stakeholders,
-   so drawing in one is publishing — and above all *creating* one, which needs a
-   named team and never happens while a recorded file resolves**) need explicit
-   operator go — or a **specific** standing authorization recorded in the brief
-   (named target + preconditions; a vague "do everything" is not one).
+5. **The cross-cutting rules fire at any stage**, not only here — the Doc Loop, the
+   loop guard, the audit's exit, the frozen REQ list, the carry-over ledger, and
+   what counts as evidence, and **every gate prints `holds: N`** — what this run left
+   running, across all eight classes, enumerated by class and never by a single
+   tool — and stage 10 does not close while this run's residue is live and
+   unaccounted (`references/residue.md`). The rest are in
+   [`references/gates.md`](references/gates.md) → *Cross-cutting, at every stage*.
 
 ## Stages (detail in `references/stages.md`)
 
@@ -252,44 +209,36 @@ capable available — see `references/model-tiering.md`).
 
 | # | Stage | Gate | Type |
 |---|---|---|---|
-| 0 | Intake grill — **mandatory** | source ledger written **with its `Contradictions:` line** — the harvest converges on one brief and nothing else compares the sources with each other; **the documentation inventory answered into `docs/DOCMAP.md`** — registers, single homes, the propagation matrix, the gate command — and **intent reconciled against as-built**, every divergence resolved ([`references/documentation.md`](references/documentation.md)); the retro read in full and its archive queried; shared understanding reached; autonomy sweep covered; brief locked + confirmed | manual |
+| 0 | Intake grill — **mandatory** | source ledger written with its `Contradictions:` line; `docs/DOCMAP.md` answered and intent reconciled against as-built; the retro read in full; autonomy sweep covered; brief locked and confirmed | manual |
 | 1 | Docs study | contracts grounded on fetched docs | auto |
 | 2 | Brainstorm + decompose | design approved; UI verdict recorded; every REQ answered; platform: module map approved | manual |
-| 3 | Spec | committed + reviewed; UI: chain validated, linter green, scenarios/`SCR-` traced; **COPY and VISUAL are a parallel layer after UX, and where both ran their convergence check is recorded** — a label the layout has no room for is right in each track and wrong on the screen ([`references/stages.md`](references/stages.md)) | manual |
-| 4 | Plan | parallel-ready, DoD per task; **every edge names what it carries** — the fake-edge test run, its `Edges:` count computed, and no arrow left whose payload nobody can name ([`references/planning.md`](references/planning.md)) | auto |
-| 5 | Dev | tasks DONE, TDD green per task, branch integrated per the brief; **a fanned-out group gets one convergence check over all its diffs together before the first worktree lands** — a per-task review cannot see a contradiction that exists only between two of them ([`references/build.md`](references/build.md) §4.2a); **anything generated passes its own checks, and local infrastructure does not publish the host's default ports** ([`references/learned.md`](references/learned.md)) | auto |
-| 6 | Tests | full suite green; new/changed code covered; **every new check probed both ways and asserted on its exit code**, and the suite run once against a cold environment ; **on a web front end the surface is checked in a browser, not in the diff** — a green suite cannot see a component that renders under a fixed header, a request that 404s past its mock, or a console error — and a browser **test suite** is the other half of the pair, never a substitute for the look (`playwright` or `chrome-devtools`, either one — **how**: [`references/browser.md`](references/browser.md), which channel: [`references/companion-skills.md`](references/companion-skills.md); absent → say *verified by reading the diff* and record it as the weaker claim it is) | auto |
-| 7 | Lint + deploy | lint clean + suite green before deploy; deploy needs a go (or the brief's specific standing authorization) | manual |
-| 8 | Post-deploy | clean boot or honest degradation report; **a deployed web target is opened, not curled** — a `200` proves the server answered and says nothing about a 404'd bundle or a console full of errors on load (`playwright` or `chrome-devtools`, either one, [`references/browser.md`](references/browser.md); absent → call it an HTTP response, which is its honest name) | auto |
-| 9 | Docs + wiki | every stale row of the stage-0 source ledger updated; **the propagation matrix walked for every change type this run produced** — the ledger names what you read, the matrix names what you owe — every settled thing recorded with an id, every answered question resolved, and **the documentation gate green with its ratchet counts printed**; docs synced; wiki synced; **the code graph refreshed where one exists** and checked against the docs (a hub no doc names, a doc naming a node the graph lost); **every number computed rather than restated, every named command or file resolvable** ([`references/learned.md`](references/learned.md)); the carry-over count printed beside the verdict | auto |
-| 10 | **Acceptance** | ladder walk ran, its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; ledger has no unresolved row; **axis rotation recorded** (new findings vs self-inflicted, rule 1 of [`references/learned.md`](references/learned.md)), **every closure verified against the artefact rather than the document describing it**, **each correction swept across its class**, **every deferral a printed ratchet rather than a TODO**; **in a multi-repository project, every repository is clean, pushed and pointed at** (below); **the hand-back is written** — the request quoted as given, progress against it, what was solved, what surfaced unasked, waiting decisions asked here, and the ambiguity count computed ([`references/progress.md`](references/progress.md)); **the environment is given back** — all eight classes enumerated, what this run started ended and verified by re-enumerating rather than by the teardown's reply, an earlier run of this project ended only when **provably spent**, anything this project does not own reported rather than ended, written as a `holds:` line (`references/residue.md`); operator signs off; **every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, and its ratchet counts are printed beside the verdict**; **the retrospective written last, and in order — the run stamped with its commit FIRST (the cold-retirement trigger reads that stamp), then the prune with the list at or under its cap and every deletion logged, then the entry; every deletion and every entry carrying its commit, entries older than five stamps rotated into the archive, counts printed** ; **every disclosure printed beside the verdict** — `abstained` (what the run declined to claim) and `unlooked` (what a check never looked at), neither a ratchet, neither with a floor, neither ever a target ([`references/gates.md`](references/gates.md) → *Disclosures*) | manual |
-
-
-### Stage 10 in a project of several repositories
-
-**A submodule is finished when its parent says so.** A parent repository records each submodule as
-a pointer to one commit, and moving the submodule does not move the pointer. So the work is
-committed, pushed, its CI is green and its own roadmap says done — and anyone who clones the parent
-gets the commit **before** the change. Nothing looks wrong in either repository on its own; the
-disagreement exists only between them, which is why it survives every check that runs inside one.
-
-Stage 10 does not close until:
-
-```bash
-git submodule status          # no line begins with '+'  (a '+' is the missing bump)
-git -C <each repo> status --porcelain && git -C <each repo> log @{u}..HEAD --oneline
-```
-
-report nothing — for the parent as well as every submodule. Where
-[agent-sync](https://github.com/ssheleg/agent-sync) is installed, `/agent-sync finish` runs
-exactly this plus *no lease left held*, and `--gates` adds the project's own gate commands.
-
-The fix, when it fails, is two commands and the second is the one that gets forgotten:
-
-```bash
-git -C <submodule> push
-git add <submodule> && git commit -m "chore: bump <name> submodule — <why>"
-```
+| 3 | Spec | committed + reviewed; UI: chain validated, linter green, scenarios and `SCR-` traced; COPY and VISUAL are a parallel layer after UX, and where both ran their convergence check is recorded | manual |
+| 4 | Plan | parallel-ready, DoD per task; **every edge names what it carries** — the fake-edge test run and its `Edges:` count computed | auto |
+| 5 | Dev | tasks DONE, TDD green per task, branch integrated per the brief; a fanned-out group gets **one convergence check over all its diffs together** before the first worktree lands | auto |
+| 6 | Tests | full suite green, new and changed code covered, every new check probed both ways and asserted on its exit code; **a web surface is checked in a browser, not in the diff** | auto |
+| 7 | Lint + deploy | lint clean and suite green before deploy; deploy needs a go, or the brief's specific standing authorization | manual |
+| 8 | Post-deploy | clean boot or an honest degradation report; **a deployed web target is opened, not curled** — a `200` proves the server answered and nothing else | auto |
+| 9 | Docs + wiki | every stale row of the stage-0 source ledger updated; the propagation matrix walked for every change type this run produced; the documentation gate green with its ratchets printed; docs, wiki and the code graph synced and checked against each other | auto |
+| 10 | **Acceptance** | the ladder walk ran and its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; no unresolved ledger row; **every repository clean, pushed and pointed at**; the hand-back written and the environment given back; the retrospective written **last**, and in order | manual |
+
+**Every gate above is the short form**, and the long form is the point of
+[`references/stages.md`](references/stages.md) — one section per stage. What the
+ladder walk is, which eight environment classes stage 10 enumerates, what makes an
+edge fake, why a `200` is not a working page: all there, none here.
+
+That split is the budget rule this pack states for everyone else, applied to
+itself: the body was **6685 tokens against a 5000 budget**, the worst in the
+family, and most of the overrun sat in this table's Gate column restating files
+that already load on demand.
+
+
+
+**Several repositories?** A submodule is finished when its parent says so — the
+work can be committed, pushed and green while a clone of the parent still gets the
+commit before it, and neither repository looks wrong alone. The two commands that
+prove it, and the two-command fix whose second half gets forgotten, are in
+[`references/acceptance.md`](references/acceptance.md) → *A project of several
+repositories*.
 
 ## Model — ask once, at preflight
 
@@ -309,14 +258,12 @@ pinned to the confirmed model automatically. Detail: `references/model-tiering.m
 
 ## Bring your own skills
 
-The stages above (stage 0 intake + 1→10) are the **example** flow (this skill's
-built-in doctrine + a super-ux UX track for user-facing tasks + host conventions). A
-host project owns its pipeline: copy `pipeline.example.json` → `pipeline.json`,
-then define its **own** stages (any count), point each stage's `skills[]` at the
-skills/agents its environment resolves, set each `gate.type` (`auto`/`manual`) to
-fit its process, and configure/toggle its own `release` block. The framework ships
-no fixed stage count and no opinion on which gates are manual or whether release
-automation is on — `pipeline.schema.json` is the only contract.
+The stages above are the **example** flow. A host project owns its pipeline: copy
+`pipeline.example.json` → `pipeline.json`, define its **own** stages (any count),
+point each `skills[]` at what its environment resolves, set each `gate.type`
+(`auto`/`manual`) to fit its process, and toggle its own `release` block. The
+framework ships no fixed stage count and no opinion on which gates are manual —
+`pipeline.schema.json` is the only contract.
 
 ## References
 

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

@@ -22,6 +22,7 @@ requirement.** It is what turns the pipeline from a funnel into a circle.
 - A seam is not a deliverable, and REQ rows are written against deliverables
 - GATE (manual)
 - When the answer is "something's missing"
+- A project of several repositories
 
 ## Why a stage and not a gate
 
@@ -361,3 +362,35 @@ or a tracked follow-up. Both are legitimate outcomes of this stage. Closing the
 run with a known gap is fine **if the gap is written down** — closing it with the
 gap only in someone's memory is the failure mode this whole spine exists to
 prevent.
+
+---
+
+## A project of several repositories
+
+**A submodule is finished when its parent says so.** A parent repository records each submodule as
+a pointer to one commit, and moving the submodule does not move the pointer. So the work is
+committed, pushed, its CI is green and its own roadmap says done — and anyone who clones the parent
+gets the commit **before** the change. Nothing looks wrong in either repository on its own; the
+disagreement exists only between them, which is why it survives every check that runs inside one.
+
+Stage 10 does not close until:
+
+```bash
+git submodule status          # no line begins with '+'  (a '+' is the missing bump)
+git -C <each repo> status --porcelain && git -C <each repo> log @{u}..HEAD --oneline
+```
+
+report nothing — for the parent as well as every submodule. Where
+[agent-sync](https://github.com/ssheleg/agent-sync) is installed, `/agent-sync finish` runs
+exactly this plus *no lease left held*, and `--gates` adds the project's own gate commands.
+
+The fix, when it fails, is two commands and the second is the one that gets forgotten:
+
+```bash
+git -C <submodule> push
+git add <submodule> && git commit -m "chore: bump <name> submodule — <why>"
+```
+
+Moved out of `SKILL.md` on 2026-08-16: the body was 6685 tokens against a
+< 5000 budget, and stage-10 close-out is what this file is for.
+

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

@@ -40,6 +40,7 @@ elsewhere and is not restated here:
 - Where a gate runs
 - Adding a check to an existing gate
 - Rationalizations
+- Cross-cutting, at every stage
 
 ## Axis A — the stage gate type
 
@@ -589,3 +590,47 @@ of is deleted in the next refactor by someone who assumed it was dead.
 | "The gate would be red on day one, so I'll add it later" | Make the section dormant instead. Dormant is visible and green; "later" is neither. |
 | "I raised the floor to get the build green" | Then say so in the log, in the same commit. A floor raised silently is a ratchet running backwards. |
 | "A hook is overkill, CI catches it" | CI catches it after the edit, the commit and the push. If the point is to stop the edit, CI is the wrong rung — and if it is not, do not pay the latency. |
+
+---
+
+## Cross-cutting, at every stage
+
+5. Cross-cutting, every stage: **when anything is settled — scope, a contract, a
+   name, a policy, a vocabulary — run the Doc Loop
+   (`references/documentation.md`) before the run moves on**: reserve the id,
+   record it, resolve the question it answers, propagate by the matrix, commit
+   with the ids. A decision that lives only in the spec dies with the spec, and one
+   that lives only in the conversation was never made;
+   **answer from the brief's autonomy section rather
+   than asking again** — it was grilled precisely so you wouldn't have to;
+   **anything deferred, dropped or left half-done goes into the carry-over ledger
+   the moment it's said** — deferred out loud is forgotten; **never narrow the task
+   silently** — the REQ list is frozen, adding is free, removing needs the
+   operator's explicit agreement; **when a loop starts undoing an earlier pass —
+   the same file edited twice for the same reason, a closed finding coming back, a
+   third entry into one stage — stop and run the loop guard**
+   (`references/loop-guard.md`): name the two shapes, escalate to the layer that
+   owns the conflict, re-plan the check as an ordered list, then go through it one
+   item at a time; **when a pass is *searching* rather than editing and starts
+   finding mostly what the previous pass's own fixes broke, the axis is exhausted —
+   rotate it, don't look harder** (`references/audit.md`); **every gate
+   prints `holds: N` — what this run left running** across the eight classes
+   (background shells, monitors, scheduled loops, coordination leases, worktrees,
+   containers, scratch files, remote state), enumerated **by class and never by a
+   single tool**, and stage 10 does not close while this run's residue is live and
+   unaccounted (`references/residue.md`); and remember that a
+   green from a check nobody has watched fail is not evidence; task
+   tracker + conventional commits per host conventions; worktree isolation for the
+   build, integrated back per the brief's branch policy before stage 7; honest
+   degradation (never claim a failed/skipped step succeeded);
+   outward/irreversible actions (deploy, publish, repo create, opening a PR,
+   **editing a shared design file — frames are read by designers and stakeholders,
+   so drawing in one is publishing — and above all *creating* one, which needs a
+   named team and never happens while a recorded file resolves**) need explicit
+   operator go — or a **specific** standing authorization recorded in the brief
+   (named target + preconditions; a vague "do everything" is not one).
+
+Moved out of `SKILL.md` on 2026-08-16 for the same budget reason as the
+multi-repository block: these fire at any stage, so they belong with the gate
+doctrine rather than inside step 5 of the run order.
+