task-pipeline-skill 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## v1.8.0 — 2026-08-03
+
+### Added — the skill now meets Anthropic's own authoring guidance, measurably
+
+Audited against the four Agent Skills pages (overview, best practices, enterprise,
+API guide). Most of the spec already held — `name` 13/64 chars, `description` inside
+1024, `SKILL.md` 334/500 lines, all 23 references linked **directly** from SKILL.md,
+forward slashes only, 436 KB against a 30 MB ceiling, and the plan-validate-execute
+pattern the guidance describes is exactly the stage 3→4 set-equality check. Five
+things did not.
+
+**Every reference over 100 lines now carries a `## Contents` list — 21 files, from
+zero.** The guidance is explicit about why: *"This ensures Claude can see the full
+scope of available information even when previewing with partial reads."* That
+preview is real, and `references/stages.md` is 500 lines — an agent that previewed
+it saw stages 0 and 1 and could not learn stage 9 existed. The list is **compared
+against the file's own headings**, not merely required to be present, because a
+hand-maintained contents list is a second source that goes stale on the next
+heading.
+
+**A behavioural evaluation suite, where there was none.** 46 structural guards prove
+the skill is well-*formed*; nothing proved it *behaves*. `evals/` now carries 13
+evaluations across the five dimensions the enterprise page names — should-trigger,
+should-not-trigger, ambiguous, coexistence with super-ux, and instruction-following
+(does phase 1 really run before the first question; does stage 9 walk the matrix and
+print ratchets; does a stage-5 subagent refuse to write the register; does stage 10
+run the ladder walk before the table).
+
+`evals/run.py` validates the suite and prints the protocol. **It never reports a
+pass**, because Anthropic ships no runner and a script claiming to have executed a
+model would be the exact failure this repository is written against.
+`evals/RESULTS.md` records the honest state — *authored, zero models exercised, zero
+runs* — as a ratchet, so "46 of 46 green" is never read as "the skill is known to
+work".
+
+**A copyable run checklist and a stated degree of freedom per stage.** The guidance
+recommends a checklist Claude copies into its response for complex workflows, and
+matching specificity to fragility — high freedom in the open field, low on the
+narrow bridge. Every stage now declares which it is and why: stage 2 is high (many
+designs are valid), stages 5, 7 and 9 are low (TDD order, an irreversible deploy, a
+mechanical matrix walk).
+
+**`SKILL-CARD.md`** — the registry entry the enterprise guidance asks for (purpose,
+owner, version, dependencies, evaluation status) plus an honest pass over its
+risk-tier table. This skill scores **three High indicators** — shipped scripts, MCP
+references, tool invocations — and says so, along with the three things a consumer
+should know rather than discover: author and reviewer are the same person, commits
+are unsigned, and behavioural evidence is missing rather than thin.
+
+### Changed
+
+- **The description leads with what the skill does, then the trigger** — the shape
+  Anthropic's own examples use. The validator used to *require* the string start with
+  "Use when", which enforced the WHEN half and left the WHAT half optional; it now
+  checks for both, plus the third-person voice the guidance requires.
+- MCP tools are named fully qualified (`context7:resolve-library-id`), because
+  without the server prefix Claude may fail to locate the tool.
+
+Four new guards, each with a negative self-test watched failing.
+
+## v1.7.2 — 2026-08-03
+
+### Fixed — nine findings from a post-release investigation of v1.7.1
+
+The release was audited against the skill's own ladder, bottom-up, findings ordered
+by seam. Every one below was proven before it was fixed and again after.
+
+**The gate enforced one of the two register shapes it promises.** `documentation.md`
+permits two decision homes — `docs/DECISIONS.md` or `docs/adr/` — and says they owe
+the same six things; `docgate.sh` parsed only the first. Measured on a real ADR
+project: **eight of ten sections went `dormant`**, dormant is green by design, and a
+planted propagation violation was not caught. The gate now builds a **normalised
+entry index** from whichever home exists, so no section knows which shape it is
+reading, and holding both at once is itself an error. Seven planted defects on the
+ADR shape, all firing.
+
+Two of those probes exposed bugs in the checks rather than in the fixtures — the
+fixture is derived from `templates/adr.md`'s own fenced example, so it cannot drift
+from the documented format. HTML comments were not stripped, so a status line
+carrying `<!-- or: Superseded by ADR-0012 -->` made an entry read as retired *and*
+invented an undefined id; and the first fix dropped the line that **opened** the
+comment, throwing away the `Status:` before it. Duplicate ADR numbers were counted
+from the entry index, whose one-row-per-id dedupe swallowed exactly the second file
+this check exists to find — it counts filenames now, because the filename is the
+allocator.
+
+**Exit 0 was not proof that the gate had looked.** Every section can go `dormant`,
+so a gate blind to a shape passes identically to one that reads it. The validator
+now asserts the seeded run **reports which shape it found** and **ran at least N
+live checks** — the difference between "it did not fail" and "it looked".
+
+**The Doc Loop was declared cross-cutting and appeared in no stage doctrine.**
+`brainstorm.md`, `spec.md`, `build.md`, `review.md` and `acceptance.md` had zero
+mentions of it — so the flow as an agent *executes* it never ran the loop, because
+an agent opens the stage file, not the orchestrator's summary. All five now say
+where a settled decision goes, and it is a guard.
+
+Most of that gap was at stage 5, which settles more decisions than any other stage
+and runs in an isolated worktree with parallel implementers. The rule is now
+explicit and argued from the same physics as the existing parallel-fan-out rule:
+**a subagent never writes the register** — append-only shared state cannot be
+hand-merged across worktrees, and an id cannot be *reserved* from a branch that
+cannot see the other writers. Decisions ride the implementer report and the ledger;
+the orchestrator runs the loop after integration, as a single writer.
+
+**`hooks.md` stated an external contract from memory.** Re-fetched from the Claude
+Code hooks reference and corrected: `permissionDecision` has **four** values, not
+one; there are **35** events, not the four listed; `effort`, `agent_id` and
+`agent_type` were missing from the stdin fields; `if` is evaluated on five tool
+events and its Bash matching is best-effort. The reference also says outright that
+**exit 1 is non-blocking "even though 1 is the conventional Unix failure code"** —
+which is the sharpest possible argument for the `|| exit 2` this file already
+required. Provenance and fetch date are now in the file, because stage 1 of this
+pipeline exists for exactly this.
+
+**Smaller, and all real:** a "we don't document" escape hatch in `documentation.md`
+contradicted the seeding rule four lines above it and the stage-0 gate; the stage-9
+config gate carried both the retired criterion *"docs in sync with code"* and the
+sentence declaring it retired; a lost edit meant the grill never asked the
+documentation-regime question the brief had a field for — and the sweep-drift guard
+missed it because it compared **stage numbers**, which both files still matched, so
+it now compares topics per stage (measured: zero false positives, including the
+legitimate case where the brief splits one grill row into two); `acceptance.md`
+never mentioned the documentation gate it is supposed to prove; and nested bold in
+the stage-10 gate criterion inverted the emphasis of everything after "every
+deletion logged".
+
+Three new guards, each with a negative self-test watched failing.
+**46 of 46 guards provably reject their planted defect.**
+
 ## v1.7.1 — 2026-08-03
 
 ### Fixed — the tag-ancestry gate had been failing on every release since v1.6.1

package/README.md

@@ -464,6 +464,32 @@ Code, and **any exit code other than 2 is non-blocking, so a crashing guard fail
 open** and stops guarding without announcing it. Elsewhere the run is `ungated` and
 must say so.
 
+### Held to Anthropic's own Skill authoring guidance
+
+Audited against the four Agent Skills pages. Most of it already held — `name`
+13/64 chars, `description` inside 1024, `SKILL.md` 334/500 lines, all 23 references
+linked **directly** from `SKILL.md`, 436 KB against a 30 MB ceiling. What did not,
+now does:
+
+- **Every reference over 100 lines carries a `## Contents` list**, and the list is
+  *compared against the file's own headings* rather than trusted. The guidance is
+  explicit about why: a long file gets previewed with a partial read, and
+  `stages.md` is 500 lines.
+- **A behavioural evaluation suite** (`evals/`) — 13 evaluations across the five
+  dimensions the enterprise guidance names: should-trigger, should-not-trigger,
+  ambiguous, coexistence, instruction-following. `evals/run.py` validates the suite
+  and prints the protocol; it **never reports a pass**, because no runner exists
+  upstream and a script claiming to have run a model would be the exact failure this
+  skill is written against. `evals/RESULTS.md` carries the honest state.
+- **A copyable run checklist** and a **stated degree of freedom per stage** — high
+  in the open field (brainstorm), low on the narrow bridge (TDD order, deploy, the
+  matrix walk).
+- **[`SKILL-CARD.md`](SKILL-CARD.md)** — the registry entry an enterprise reviewer
+  needs, with an honest pass over the risk-tier table. This skill scores three
+  *High* indicators and says so, along with what a consumer should know rather than
+  discover: author and reviewer are the same person, commits are unsigned, and the
+  eval suite has not been executed.
+
 ### The retrospective — the run teaches the next run, and the list stays short
 
 Every gate in this flow is good at *this* run and blind across runs. So the same
@@ -717,6 +743,8 @@ recommendation, so you arm the whole run in one exchange. Detail:
 | [`references/retrospective.md`](plugins/task-pipeline/skills/task-pipeline/references/retrospective.md) | the project retro: the three grades of fix, the mandatory prune, the cap of ten |
 | [`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 |
+| [`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 |
 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | dev setup, the validator, the version-sync rule, release flow |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.7.1",
+  "version": "1.8.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.7.1",
+  "version": "1.8.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: "Use when running a substantial task through the full end-to-end delivery pipeline — an up-front intake grill that expands the request into a complete brief, then docs study, brainstorm, spec, plan, subagent-driven build, tests, lint/deploy, post-deploy log check, docs/wiki sync and acceptance — as gated stages whose doctrine is built entirely into this skill (no required companion skills). Triggers - 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline, or any substantial feature, fix, or build that should follow the disciplined cycle rather than ad-hoc coding. The intake grill is mandatory - it front-loads every decision, including the per-stage autonomy sweep, so stages 1→10 run without mid-flight questions; recommends super-ux for user-facing work; confirms one model up front (most capable available, never a hardcoded id); reads host-project conventions for deploy/docs/wiki so it stays project-agnostic."
+description: "Runs a substantial task through a full delivery pipeline: an intake grill that expands the request into a locked brief, then docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy check, docs/wiki sync and acceptance — gated stages whose doctrine ships inside this skill (no required companions). Use when any substantial feature, fix or build should follow the disciplined cycle rather than ad-hoc coding, or on 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline. The grill is mandatory and front-loads every decision, so stages 1→10 run without mid-flight questions; documentation is a deliverable with its own gate; recommends super-ux for user-facing work; confirms one model up front (most capable available, never a hardcoded id); reads host conventions so it stays project-agnostic."
 license: MIT
 ---
 

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

@@ -151,7 +151,7 @@
       ],
       "gate": {
         "type": "auto",
-        "check": "the stage-0 source ledger is the work list — every source the harvest read is updated if this run changed or disproved it; docs in sync with code in the same change; wiki synced via wiki-update when obsidian-wiki is installed (absent → recommended once, never a blocker); THE CODE GRAPH REFRESHED — '/graphify . --update' where graphify-out/ exists (references/knowledge-graph.md), or the reason it was skipped written into the carry-over ledger; absent → recommended once, never a blocker. The close-out has three artifacts, not two: 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. Then the cheap half of the GRAPH-VS-DOCS DIVERGENCE CHECK: a hub 'graphify god-nodes' reports that no document names is an undocumented seam, an edge the docs deny is either a leak in the code or a lie in the docs, and a doc naming a module the graph has no node for describes something that no longer exists — doc-side findings fixed here, absences handed to stage 10's ladder walk as REQ rows. Docs living in another repository are outward — proposed with an explicit go, or carried over with the exact edit; dangling links fixed. THE PROPAGATION SWEEP RUNS FIRST (references/documentation.md): the source ledger names the documents this run READ, the matrix in docs/DOCMAP.md names the documents it OWES, and they are not the same list — the document nobody read is exactly the document nobody updated. Walk the matrix row for every change type this run produced; every settled thing carries an id in the register; every answered question is flipped to Resolved-> that id; every document named in a 'Consequences / affects:' line cites its decision. THEN THE DOCUMENTATION GATE IS GREEN — the command docs/DOCMAP.md names (bash scripts/check-docs.sh by default) — with its RATCHET COUNTS PRINTED beside the verdict and any skipped check stating that it skipped (references/gates.md), so 'green' reads as 'green, and here is exactly what was not looked at'. This replaced the unfalsifiable 'docs in sync with code', which named no artefact and no command. The as-built record is written and reconciled, and the carry-over count is printed beside this verdict"
+        "check": "the stage-0 source ledger is the work list — every source the harvest read is updated if this run changed or disproved it; host module docs and runbooks updated in the same change; wiki synced via wiki-update when obsidian-wiki is installed (absent → recommended once, never a blocker); THE CODE GRAPH REFRESHED — '/graphify . --update' where graphify-out/ exists (references/knowledge-graph.md), or the reason it was skipped written into the carry-over ledger; absent → recommended once, never a blocker. The close-out has three artifacts, not two: 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. Then the cheap half of the GRAPH-VS-DOCS DIVERGENCE CHECK: a hub 'graphify god-nodes' reports that no document names is an undocumented seam, an edge the docs deny is either a leak in the code or a lie in the docs, and a doc naming a module the graph has no node for describes something that no longer exists — doc-side findings fixed here, absences handed to stage 10's ladder walk as REQ rows. Docs living in another repository are outward — proposed with an explicit go, or carried over with the exact edit; dangling links fixed. THE PROPAGATION SWEEP RUNS FIRST (references/documentation.md): the source ledger names the documents this run READ, the matrix in docs/DOCMAP.md names the documents it OWES, and they are not the same list — the document nobody read is exactly the document nobody updated. Walk the matrix row for every change type this run produced; every settled thing carries an id in the register; every answered question is flipped to Resolved-> that id; every document named in a 'Consequences / affects:' line cites its decision. THEN THE DOCUMENTATION GATE IS GREEN — the command docs/DOCMAP.md names (bash scripts/check-docs.sh by default) — with its RATCHET COUNTS PRINTED beside the verdict and any skipped check stating that it skipped (references/gates.md), so 'green' reads as 'green, and here is exactly what was not looked at'. This replaced the unfalsifiable 'docs in sync with code', which named no artefact and no command. The as-built record is written and reconciled, and the carry-over count is printed beside this verdict"
       }
     },
     {

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

@@ -7,6 +7,19 @@ None of them asks *"does this still contain everything that was asked for?"*
 That is this stage's only job: **go back to the brief and account for every
 requirement.** It is what turns the pipeline from a funnel into a circle.
 
+## Contents
+
+- Why a stage and not a gate
+- First, the ladder walk — what the list itself is missing
+- Inputs
+- Output — the coverage table
+- Evidence, not assertion
+- Several repositories — a submodule is finished when its parent says so
+- The closing question
+- The retrospective — the run's last act
+- GATE (manual)
+- When the answer is "something's missing"
+
 ## Why a stage and not a gate
 
 The loss this catches doesn't happen inside a stage — it happens **on the seams**.
@@ -87,6 +100,12 @@ Run: <branch/commit range> · Date: YYYY-MM-DD
 | `deferred` | agreed not to do it now | the operator's agreement **and** a tracker entry |
 | `dropped` | agreed it isn't wanted | the operator's agreement + the reason |
 
+**A `dropped` is a scope decision, and it outlives this run.** The operator's
+agreement closes the row here; the **Doc Loop**
+([`documentation.md`](documentation.md)) is what stops the same requirement being
+re-proposed next quarter by someone who never saw this table. A `deferred` needs its
+tracker entry, not an entry in the register — it is a schedule, not a decision.
+
 Those four are the only ways a requirement may close. Anything that fits none of
 them is `unknown`, and **`unknown` fails the gate** — that is the whole mechanism:
 the run cannot end while a requirement is still unclassified.
@@ -187,8 +206,13 @@ All of:
    bottom-up, findings ordered by seam, absences turned into REQ rows **before**
    the table was written, and the two pass counts recorded.
 2. **Every check this gate leans on has been seen failing** at least once against a
-   planted defect (`audit.md` → *Exit criterion*). An unproven check's green is not
-   evidence.
+   planted defect (`audit.md` → *Exit criterion*; the procedure, with the commands,
+   is [`gates.md`](gates.md) → *Probing*). An unproven check's green is not
+   evidence. That includes **the documentation gate** the project's doc map names
+   ([`documentation.md`](documentation.md)) — stage 9 ran it, this stage is where it
+   is *proven*, and its **ratchet counts are printed beside this verdict**. A
+   documentation gate is the easiest one in a run to inherit unproven, because it
+   was green the first time anyone looked at it.
 3. **Every REQ has a status** — none `unknown`, none blank.
 4. **Every `verified` carries evidence** of the kind above.
 5. **Every `partial` names what's missing** and where it's tracked.

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

@@ -5,6 +5,12 @@ a resumed or handed-off run always knows where to look. This is the recommended
 structure; a host project may relocate roots via its `CLAUDE.md`, but keep the
 shape.
 
+## Contents
+
+- In the host project
+- Stage → artifact map
+- This repo (task-pipeline itself), for reference
+
 ## In the host project
 
 ```

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

@@ -14,6 +14,17 @@ This file is the method that finds those. It is **cross-cutting**: stage 10 runs
 before writing the coverage table, the program loop runs it per module, and a task
 whose whole job is "audit X" runs nothing else.
 
+## Contents
+
+- Three things that are easy to confuse
+- Why "look again, more carefully" stops working
+- The ladder
+- How one audit pass runs
+- Exit criterion — the part usually skipped
+- The three rules that stop this becoming another loop
+- When this runs
+- Rationalizations
+
 ## Three things that are easy to confuse
 
 | File | Runs when | Answers |

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

@@ -12,6 +12,18 @@ approved design — not at code.
 > the UI verdict is a required output, and the spec write-up moved to stage 3
 > ([`spec.md`](spec.md)).
 
+## Contents
+
+- The hard gate
+- Input: the brief, not a blank page
+- The loop
+- Design for isolation and clarity
+- Working in an existing codebase
+- UI detection — a required output
+- The approved design is a set of decisions — record them
+- GATE (manual)
+- Rationalizations
+
 ## The hard gate
 
 **No implementation action before the operator approves a design.** No code, no
@@ -88,6 +100,18 @@ it arms the stage-3 UX track ([`spec.md`](spec.md) → *UX track*). When it's
 genuinely borderline, record "yes": a false positive costs one extra chain, a false
 negative ships an unspecified interface.
 
+## The approved design is a set of decisions — record them
+
+An approved approach is a decision, and so is each alternative rejected for a reason
+worth remembering. Run the **Doc Loop** ([`documentation.md`](documentation.md)) on
+the ones that will outlive this run: the shape chosen, the boundary drawn, the option
+deliberately not taken. Not every preference — the ones a future reader would
+otherwise re-litigate from scratch, which is the same test an ADR applies.
+
+The cost of skipping it is specific: a design approved in conversation and recorded
+only in the spec dies with that spec, and the next run re-opens a question the
+operator already answered.
+
 ## GATE (manual)
 
 The operator approves the design **and** the UI verdict is recorded **and every REQ

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

@@ -29,6 +29,17 @@ the work; the gates, the artifacts and the review discipline do not. Say plainly
 that the run is inline, since a self-review is weaker evidence than a fresh
 reviewer's.
 
+## Contents
+
+- 1. Isolation
+- 2. Workspace and ledger
+- 3. Models
+- 4. The task loop
+- 5. Final whole-branch review
+- 6. Integrate, then finish
+- GATE (auto)
+- Rationalizations
+
 ## 1. Isolation
 
 Work never starts on `main`/`master` without the operator's explicit consent
@@ -177,6 +188,35 @@ Record the implementer's agent identity: fix rounds 1–3 resume it.
 > commit range, a one-line test summary, and your concerns. Ask before starting
 > if anything in the brief is ambiguous — questions are cheaper than rework.
 
+### 4.1a Decisions settled inside a task — and who may write them down
+
+The report above already asks for *"decisions you made"*, and stage 5 settles more
+of them than any other stage: an interface picked between two tasks, a ruling on a
+review finding, a constraint discovered in the code. Every one is a Doc Loop trigger
+([`documentation.md`](documentation.md)) — and this is the one stage where running
+that loop naively breaks something.
+
+**A subagent never writes the register.** Not a style rule; the same physical
+argument as §4.2 below, one level up:
+
+- The register is **append-only shared state**. Two implementers appending in two
+  worktrees conflict on the one file a project cannot afford to hand-merge, and the
+  loser's entry is the one that quietly disappears.
+- An **id cannot be reserved from inside an isolated branch.** Reserving *is* an
+  arbitration between concurrent writers, and a worktree is by construction unable
+  to see the other writers ([`documentation.md`](documentation.md) → *Registers are
+  shared state*).
+
+So the route is fixed: a decision settled in a task goes into the **implementer
+report**, and into the **carry-over ledger** if it outlives the task — and the
+**orchestrator runs the Doc Loop after integration**, on the base branch, as a
+single writer. Nothing is lost and nothing collides.
+
+**What that costs, said out loud:** between the ruling and the entry there is a
+window in which the decision exists only in a report. That is exactly why the gate
+below harvests every report and parked finding into the ledger **before the scratch
+workspace is deleted** — the ledger is what survives the window.
+
 ### 4.2 Parallel groups — when fan-out is allowed
 
 The plan's parallel groups ([`planning.md`](planning.md)) describe what *may* run
@@ -353,7 +393,10 @@ code quality); the full test suite green; every open finding either fixed or par
 with a ruling; **every parked finding and implementer concern harvested into the
 carry-over ledger** — the workspace is deleted, so nothing may stay only there;
 no task left BLOCKED; the branch integrated per the brief's policy — or the
-operator explicitly told you to leave it, and that is recorded. Verify it yourself;
+operator explicitly told you to leave it, and that is recorded. **Every decision a
+task settled has run the Doc Loop after integration, written by the orchestrator on
+the base branch** (§4.1a — a subagent never writes the register), or is sitting in
+the ledger with its entry still owed. Verify it yourself;
 a red suite or an unresolved BLOCKED does not advance to stage 6.
 
 ## Rationalizations

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

@@ -8,6 +8,15 @@ something isn't installed.
 What remains is a short list of **optional** companions that make individual stages
 better, plus one that is required only for user-facing work.
 
+## Contents
+
+- Built in — nothing to install
+- The matrix
+- Optional bridge — substituting an external skill set
+- Preflight (emit before stage 0)
+- Credit
+- Hand-off the other direction
+
 ## Built in — nothing to install
 
 | Stage | Doctrine |
@@ -34,7 +43,7 @@ better, plus one that is required only for user-facing work.
 | Skill / tool | Needed for | Required? | Install |
 |---|---|---|---|
 | **super-ux** (`ux-foundation`, `ux-flows`, `ux-scenarios`, `ux-audit`, `/ux`, `/ux-lint`) | stage 3 UX track | **Required for any user-facing task** | `/plugin marketplace add ssheleg/super-ux` → `/plugin install super-ux@super-ux` (or `npx skills add ssheleg/super-ux`) |
-| **context7** (MCP) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
+| **context7** (MCP — call tools fully qualified: `context7:resolve-library-id`, `context7:query-docs`) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
 | **Figma** (MCP) | stage 3 UX track, when the project designs visually — super-ux mirrors each `SCR-` screen/state into a frame | Optional, **UI + Figma-on only**. Absent → super-ux degrades to text-only *by itself and never blocks*, so shipping a UI feature with no mockups becomes a silent scope call — which is why the stage-0 sweep decides it | connect the Figma MCP server (`/mcp`, or your claude.ai connectors) |
 | **[obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (`wiki-query`, `wiki-update`) | **stage 0 harvest** (query what's already known) **+ stage 9 sync** | **Recommended** — never a gate; absent → harvest runs on repo docs alone | `pip install obsidian-wiki` → `obsidian-wiki setup --vault /path/to/your/vault` |
 | **[graphify](https://github.com/Graphify-Labs/graphify)** (`/graphify`, `graphify query\|affected\|god-nodes`) | **stage 0 harvest** (reach: what calls this, what breaks if it moves) **+ stage 9 refresh + the graph↔docs divergence check** ([`knowledge-graph.md`](knowledge-graph.md)) | **Recommended** — never a gate; absent → the harvest greps instead, and the divergence axis is unavailable | `uv tool install graphifyy` → `graphify install` → `/graphify .` |

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

@@ -8,6 +8,15 @@ a time, each brick carrying its own documentation, spec, plan, build and gates.
 This runs at the end of **stage 2**, on the approved design, before any spec is
 written. It is skipped — explicitly, in writing — when the work is a single module.
 
+## Contents
+
+- When it applies
+- How to cut
+- The module map — the artifact
+- GATE (part of stage 2, manual)
+- The program loop — one brick at a time
+- Program done
+
 ## When it applies
 
 Decompose when any of these is true:

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

@@ -16,6 +16,20 @@ being written twice; write it once, here.
 
 ---
 
+## Contents
+
+- The inventory — four questions, answered before the first line of work
+- Registers and ids
+- Single source of truth
+- The Doc Loop
+- Changing your mind
+- The propagation matrix
+- Navigation
+- Intent and as-built
+- Registers are shared state
+- Where this binds in the pipeline
+- Rationalizations
+
 ## The inventory — four questions, answered before the first line of work
 
 Stage 0 answers these before the interview, and writes the answers to
@@ -31,8 +45,12 @@ A project with no answers gets them seeded. The seeding is itself recorded as th
 first entry in the register, which is the cheapest possible demonstration that the
 register works.
 
-**A project that answers "we don't document" has still answered.** Write that down,
-with the date, and the next agent stops re-deciding it every run.
+**There is no "we don't document" answer.** The four questions have answers in every
+repository — the smallest one still decides *somewhere* that a thing is true — and
+the only choice is whether that answer is written down or re-derived by each new
+reader. What scales down is **volume**, never the rules: a register with three
+entries is a register, and the seeded gate is green on exactly those three
+([`gates.md`](gates.md) → *progressive arming*).
 
 ---
 

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

@@ -19,6 +19,20 @@ elsewhere and is not restated here:
 
 ---
 
+## Contents
+
+- Axis A — the stage gate type
+- Axis B — the enforcement mechanism
+- Before you run a check
+- Anatomy of a project gate
+- Writing the check itself
+- Probing — plant, run, restore
+- The false-positive budget
+- Ratchets
+- Where a gate runs
+- Adding a check to an existing gate
+- Rationalizations
+
 ## Axis A — the stage gate type
 
 From [`../pipeline.schema.json`](../pipeline.schema.json), one per stage:

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

@@ -12,6 +12,16 @@ coming back to the operator.
 > half — glossary challenges, `CONTEXT.md`, ADR discipline — comes from there; the
 > autonomy sweep and the brief are this pipeline's.
 
+## Contents
+
+- Phase 1 — harvest before you ask
+- Phase 2 — the loop
+- Domain awareness
+- The autonomy sweep
+- The design destination — one file, decided here, never invented later
+- The REQ spine — the grill's other hard output
+- Output
+
 ## Phase 1 — harvest before you ask
 
 **Do not open the interview cold.** Stage 0 begins by finding what the project
@@ -131,6 +141,7 @@ 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 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 |
 | 2–3 Spec | UI verdict (arms super-ux); any scenario-tracing waiver |