task-pipeline-skill 1.6.1 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## v1.7.0 — 2026-08-03
+
+### Added — documentation is a deliverable, and it has a gate
+
+Stage 9's gate read *"docs in sync with code"*. That sentence names no artefact and
+no command, so nothing in the run could make it false — and the pipeline had no
+concept of a decision outliving the spec that recorded it. Three built-in doctrines
+close that, ported from a 260-decision, 72-document specification built across four
+repositories with several agents editing at once.
+
+**`references/documentation.md`** — the inventory (four questions, answered before
+the first interview question and written to `docs/DOCMAP.md`), registers and stable
+ids, single source of truth including its cross-repository form, **the Doc Loop as a
+cross-cutting protocol** that fires whenever anything is settled rather than only at
+stage 9, append-only history with three distinct edge markers, the propagation
+matrix and its ratchet, navigation, intent vs as-built, and registers as shared
+state.
+
+Two measurements decide two of those rules rather than taste. **204 of 275**
+refine/supersede edges pointed at an unannotated target — which was not 204
+violations, because most were additive; *that ambiguity was the defect*, and it is
+why `Refines:` / `Contradicts:` / `Supersedes:` are three markers with different
+obligations. And turning the propagation check on found **162** missing citations
+across **73** decisions, not the four an audit had reported — so it ships ratcheted,
+because failing on all of them makes a gate people switch off.
+
+**`references/gates.md`** — the two axes (a stage's `auto`/`manual` type versus the
+enforcement mechanism) and the promotion ladder: doctrine line → review question →
+script check → CI step → hook, with the trigger for each promotion. It owns
+*procedure* only; `audit.md` and `learned.md` already own probes, ratchets, exit
+codes and false positives as *law*, and a second statement of one law is the exact
+defect this release ports a rule against.
+
+**`references/hooks.md`** — the `PreToolUse` contract, led by the limit rather than
+the capability: hooks exist only in Claude Code, and **any exit code other than 2 is
+non-blocking, so a crashing guard fails open** and stops guarding without announcing
+it. Elsewhere the run is `ungated` and must say so.
+
+### Added — a documentation gate that travels, and seeds green
+
+**`templates/docgate.sh`** is a portable gate (bash 3.2; no `grep -P`, no in-place
+stream edits, no bash-4 builtins) with ten sections, ratchet floors as variables,
+printed register sizes, and **progressive arming**: a section whose input does not
+exist yet prints `dormant` and does not fail. That is what makes always-governed
+survivable on a three-file repository — the alternative was regime tiers, and a tier
+is a switch that gets set to "minimal" by whoever is in a hurry.
+
+Probe log — every section planted, run, restored, asserted on `$?`:
+
+```
+1 links · 2 ids · 3 next-free · 4 counts · 5 propagation · 6 supersede
+7 residue · 8 vocabulary · 9 commit SHAs (armed tree) · 10 doc map    10/10 fire
+```
+
+Two probes came back silent and they landed on opposite sides of the doctrine. One
+was a bad probe: section 9 correctly *skips* outside a git tree, so expecting a
+failure there was wrong. The other was a real bug in the gate — `$((0009))` is
+octal, `9` is not an octal digit, the expansion errored, the `if` took its else
+branch, and section 3 printed `ok` for **every id ending in 8 or 9**.
+
+Also seeded: `docmap.md`, `decisions.md`, `open-questions.md`, `retro-archive.md`
+and one worked `hooks.example.json`. Lease arbitration is **not** reimplemented —
+`agent-sync` owns it and is now in the companion matrix and the preflight, where it
+had been missing while four other files leaned on it.
+
+### Changed — the retrospective is traceable, and bounded
+
+Standing instructions carry `Born`/`Commit` and `Last fired`/`Fired at`; every log
+entry, retirement and run stamp carries a commit; and every SHA must resolve, which
+the seeded gate checks with `git rev-parse --verify` — rule 14 applied to history. A
+`file:line` rots at the next edit, while `git show <sha>` reconstructs the whole
+incident months later, which is exactly when a class returns.
+
+Entries older than the last five run stamps now **rotate** into
+`docs/superpowers/retro/YYYY-QN.md` — append-only, queried by the task's nouns,
+never read end to end. This also closes a contradiction the file had carried from
+the start: it was described as *read in full* while containing an unbounded log, so
+the cap that justified reading it protected one section while the rest grew.
+
+### Fixed — defects found while porting, in the files the port touched
+
+- **`SKILL.md` promised what it contradicted 42 lines later**: "no stage that can
+  fail because a dependency is missing", then "for UI tasks the spec gate
+  **requires** super-ux". `companion-skills.md` had the true rule all along.
+- **Source precedence was stated once for two different questions.** `code`, then
+  docs, then the wiki, then memory is right for what *is* and wrong for what
+  *should be*: a decision accepted and not yet built is still the decision.
+- **`learned.md` narrated its most expensive incident and never gave it a row** —
+  a full day of work performed under another session's identity. Now rule 15, with
+  its check, cross-referencing the narration rather than repeating it.
+- `conventions.md` never asked where decisions live; `audit.md`'s "put it in a
+  script" had nowhere to point; the carry-over ratchet was required by one gate and
+  specified for all of them; `templates/README.md` had no guard and would have gone
+  stale on the first new template.
+- `test/negatives.py`'s floor sat at **20** while the workflow carried **34** — it
+  would have caught a total collapse and not the loss of a third of the suite.
+
+Eleven new validator guards, each with a negative self-test watched failing. One of
+them **executes** the seeded gate over a scratch project and requires exit `0`.
+**43 of 43 guards provably reject their planted defect.**
+
 ## v1.6.1 — 2026-08-01
 
 ### Fixed — v1.6.0 shipped without `displayName`, because a release lived only on a tag

package/README.md

@@ -58,7 +58,7 @@ Every gate is **typed**: `auto` — the orchestrator verifies it itself, pass/fa
 
 | # | Stage | Gate | Type |
 |---|---|---|---|
-| 0 | Harvest + intake grill — **mandatory** | source ledger written; shared understanding + autonomy sweep; brief locked | manual |
+| 0 | Harvest + intake grill — **mandatory** | source ledger written; the documentation inventory answered into `docs/DOCMAP.md`; intent reconciled against as-built; shared understanding + autonomy sweep; brief locked | manual |
 | 1 | Docs study | contracts grounded on current docs | auto |
 | 2 | Brainstorm + decompose | design approved; UI verdict recorded; every REQ answered; platform: module map approved | manual |
 | 3 | Spec | committed + reviewed; UI: super-ux chain validated, linter green | manual |
@@ -67,8 +67,8 @@ Every gate is **typed**: `auto` — the orchestrator verifies it itself, pass/fa
 | 6 | Tests | full suite green, new code covered | auto |
 | 7 | Lint + deploy | lint clean + suite green before deploy | manual |
 | 8 | Post-deploy | clean boot / honest degradation | auto |
-| 9 | Docs + wiki | every stale source-ledger row updated; docs + wiki synced; the code graph refreshed and checked against the docs | auto |
-| 10 | **Acceptance** | every REQ accounted for with evidence; operator signs off; the retro written — pruned before anything was added | manual |
+| 9 | Docs + wiki | the propagation matrix walked and the documentation gate green with its ratchets printed; every stale source-ledger row updated; docs + wiki synced; the code graph refreshed and checked against the docs | auto |
+| 10 | **Acceptance** | every REQ accounted for with evidence; every check leaned on seen failing once; operator signs off; the retro written — pruned before anything was added, every lesson carrying its commit | manual |
 
 ## What you get
 
@@ -108,8 +108,11 @@ stage and walks the gates. See [Install](#install) for the other channels.
 ### Everything is built in — zero required dependencies
 
 The doctrine each stage runs on ships inside the skill. Nothing to install for it,
-nothing to resolve at preflight, no version skew with someone else's repo, and no
-stage that can fail because a plugin is missing:
+nothing to resolve at preflight, no version skew with someone else's repo, and
+**no stage blocks on an install** — stage 1 falls back to web search, the wiki and
+the code graph are recommendations. The one exception is deliberate and named: on a
+user-facing task the stage-3 UX track requires super-ux, and the spec gate stops
+until it is installed.
 
 | Stage | Built-in doctrine |
 |---|---|
@@ -124,6 +127,9 @@ stage that can fail because a plugin is missing:
 | 10 Acceptance | [`acceptance.md`](plugins/task-pipeline/skills/task-pipeline/references/acceptance.md) — REQ coverage table, evidence rules, the closing question |
 | 10 + any audit | [`audit.md`](plugins/task-pipeline/skills/task-pipeline/references/audit.md) — the L0→L7 ladder and its seams, axis rotation, ratchets, proven checks |
 | any loop | [`loop-guard.md`](plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md) — churn detection, caps, the break protocol |
+| 0 + 9 + any settled decision | [`documentation.md`](plugins/task-pipeline/skills/task-pipeline/references/documentation.md) — the inventory, registers and ids, SSOT, the Doc Loop, supersede semantics, the propagation matrix, intent vs as-built |
+| 6–10 + any check you write | [`gates.md`](plugins/task-pipeline/skills/task-pipeline/references/gates.md) — the two axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors |
+| any agent-time enforcement | [`hooks.md`](plugins/task-pipeline/skills/task-pipeline/references/hooks.md) — the `PreToolUse` contract, the fail-open hazard, the Claude-Code-only limit |
 
 **Ported, not depended on.** Stage 0 is adapted from
 [Matt Pocock's `grilling` / `grill-with-docs`](https://github.com/mattpocock/skills)
@@ -407,6 +413,57 @@ fail, you don't know it tests the right thing* — raised from one test to every
 gate, linter and script in the run. **A green result from an unproven check is
 worth nothing.**
 
+### Documentation is a deliverable, and it has a gate
+
+Stage 9 used to say *"docs in sync with code"*. That sentence names no artefact and
+no command, so nothing could make it false. The pipeline now carries the system that
+can.
+
+**Stage 0 answers four questions** and writes them to `docs/DOCMAP.md`: where
+settled things live, what each fact's single home is, what a change of type X
+obliges, and what proves it. A project with no answers gets them seeded — a decision
+register, an open-questions register and a portable documentation gate — and the
+seeding is itself the register's first entry. One decision home per project: an
+existing `docs/adr/` **is** the register and is never duplicated.
+
+**The Doc Loop fires whenever anything is settled, at any stage.** Reserve the id,
+record it, resolve the question it answers, propagate, commit with the ids. A
+decision that lives only in the spec dies with the spec; one that lives only in the
+conversation was never made.
+
+**The propagation matrix is not the harvest ledger.** The ledger names the documents
+the run *read*; the matrix names the documents it *owes*. They are different lists,
+and the gap between them is where documentation rots — the document nobody read is
+exactly the document nobody updated.
+
+**Governance is a by-product, not a second job.** The run already produces decisions
+(the brief's *Decisions locked*, the spec's contracts, the ADRs), so recording one is
+transcription plus a stable id. And the seeded gate **arms progressively**: a section
+whose input does not exist yet prints `dormant` and stays green, so a three-file
+repository is governed from day one without starting red — a scaffold that seeds red
+teaches everyone on day one that the gate is noise.
+
+### Gates and hooks — how a rule becomes something that can say no
+
+Two axes, deliberately not conflated. **The stage gate type** (`auto` = verify it
+yourself; `manual` = wait for an explicit go) is about this pipeline. **The
+enforcement mechanism** is a ladder a rule climbs: a doctrine line → a review
+question → a script check (promote here once the class has occurred *twice*) → a CI
+step → a hook. A rule may sit on several rungs; what it may never do is *pretend* to
+be on a higher one.
+
+The skill ships the anatomy of a gate that cannot lie — non-zero exit on any
+failure, the verdict block last with nothing after it, a scope header saying what it
+does **not** cover, ratchet floors as variables with the counts printed beside `OK`,
+skips printed rather than silent, and every count computed rather than restated —
+plus the probe recipe, because a green from a check nobody has watched fail is worth
+nothing, and **the probe is the thing to doubt first**.
+
+Hooks get their own file, and it leads with the limit: they exist only in Claude
+Code, and **any exit code other than 2 is non-blocking, so a crashing guard fails
+open** and stops guarding without announcing it. Elsewhere the run is `ungated` and
+must say so.
+
 ### 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
@@ -652,11 +709,14 @@ recommendation, so you arm the whole run in one exchange. Detail:
 | [`SKILL.md`](plugins/task-pipeline/skills/task-pipeline/SKILL.md) | the orchestrator: how to run, the stage table, the model decision |
 | [`references/stages.md`](plugins/task-pipeline/skills/task-pipeline/references/stages.md) | per-stage detail and the exact gate criteria |
 | [`references/artifacts.md`](plugins/task-pipeline/skills/task-pipeline/references/artifacts.md) | the canonical document layout each stage writes to |
-| [`references/conventions.md`](plugins/task-pipeline/skills/task-pipeline/references/conventions.md) | how stages 6–10 read the host project's `CLAUDE.md` |
+| [`references/conventions.md`](plugins/task-pipeline/skills/task-pipeline/references/conventions.md) | how stages 6–10 read the host project's `CLAUDE.md`, and how the documentation regime is detected |
+| [`references/documentation.md`](plugins/task-pipeline/skills/task-pipeline/references/documentation.md) | the doc system: the inventory, registers and ids, SSOT, the Doc Loop, supersede semantics, the propagation matrix, intent vs as-built |
+| [`references/gates.md`](plugins/task-pipeline/skills/task-pipeline/references/gates.md) | the two axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors, where a gate runs |
+| [`references/hooks.md`](plugins/task-pipeline/skills/task-pipeline/references/hooks.md) | the `PreToolUse` contract, the fail-open hazard, placement, and the Claude-Code-only limit |
 | [`references/knowledge-graph.md`](plugins/task-pipeline/skills/task-pipeline/references/knowledge-graph.md) | the code graph: install line, stage-0 reach queries, the stage-9 refresh, the graph↔docs divergence check |
 | [`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 |
+| [`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 |
 | [`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 |
 
@@ -676,7 +736,7 @@ npm test        # python3 test/validate.py — the structural validator
 
 Built by ssheleg — [sshlg.me](https://sshlg.me)
 
-- X / Twitter — [@fuck_this_year](https://x.com/fuck_this_year)
+- X / Twitter — [@sshlg93](https://x.com/sshlg93)
 - Telegram — [@sshlg](https://t.me/sshlg)
 
 Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills):

package/cursor/rules/task-pipeline.mdc

@@ -333,6 +333,88 @@ its own previous pass while the finding count still looked healthy. So:
   it, then trust the green — same law as the failing test, applied to every gate,
   linter and script the run leans on.
 
+## Documentation is a deliverable, and it has a gate
+
+**Before the first question (stage 0), answer four things and write them to
+`docs/DOCMAP.md`:** where settled things live, what each fact's single home is,
+what a change of type X obliges, and what proves it. A project with no answers gets
+them seeded — a decision register, an open-questions register and a documentation
+gate — and the seeding is recorded as the register's first entry. **One decision
+home per project:** an existing `docs/adr/` *is* the register; never create a second
+beside it. Then **reconcile intent against as-built** — git says how it should be,
+the run record says how it turned out — and resolve every divergence before you
+start: the document is stale, the record is wrong, or they genuinely disagree and
+that is a decision. There is no fourth option, and starting on an unresolved one
+means building against a system that does not exist.
+
+**The Doc Loop fires whenever anything is settled, at any stage — not at the end.**
+Seven steps: orient and reconcile → reserve the id, then record → resolve the
+question it answers → propagate → adjust scope → record as-built → commit with the
+ids in the subject. Reading a "Next free ID" line is **not** reserving it: a second
+agent reading it in the same minute gets the same number. Finishing the chat answer
+is not finishing the task.
+
+**Registers are append-only.** To reverse: add a new entry, edit **only the status
+line** of the old one, leave its body intact. Three distinct markers, because one
+word for "adds to" and "replaces a clause of" cannot be enforced: `Refines:` is
+additive and the target needs no annotation; `Contradicts:` names a clause that
+falls and the target **must** say so; `Supersedes:` retires the whole target and the
+target **must** say so.
+
+**The propagation matrix is not the harvest ledger.** The ledger names the documents
+you *read*; the matrix names the documents you *owe*. The document nobody read is
+exactly the document nobody updated. At stage 9, walk the matrix for every change
+type the run produced, then run the documentation gate and print its ratchet counts.
+
+## Gates: two axes, and how to build one that cannot lie
+
+**Axis A — the stage gate type.** `auto` = verify the check yourself and stop on
+fail; `manual` = wait for an explicit operator go. An auto gate never substitutes
+for a required manual approval.
+
+**Axis B — where the rule is actually enforced**, and a rule climbs this ladder
+rather than starting at the top: doctrine line → review question at a named gate →
+script check (promote here once the class has occurred **twice**) → CI step → hook.
+A rule may sit on several rungs; what it may never do is *pretend* to be on a higher
+one — that is the same failure as a gate that prints `FAIL` and exits `0`.
+
+**Before you run any check:** the base is green (or its known-red baseline is
+recorded); the check has been probed; you have read its scope header and know what
+it does **not** cover; you have read its ratchet floors.
+
+**Anatomy of a gate script:** non-zero exit on any failure; the verdict block last
+and **nothing after it**; a SCOPE header; portable (no `grep -P`, no in-place stream
+edits, no bash-4 builtins); ratchet floors as variables with the counts printed
+beside `OK`; skips printed, never silent; a section with no input yet prints
+`dormant` and stays green so a fresh project never starts red; every count computed,
+never restated; two-layer mappings checked in **both** directions.
+
+**Probing:** copy the tree, plant the defect **in python** (an in-place stream edit
+is not portable and silently edits nothing on BSD), run, assert `$?` is non-zero,
+restore, assert zero. **Doubt the probe before the check** — four of five silent
+probes on a real project were the probe's fault. Record the probe.
+
+## Hooks — the limit first
+
+Hooks exist **only in Claude Code**. Elsewhere the same rules run as a self-check
+and the run is recorded **`ungated`** — never describe a project as protected when
+its agents run somewhere else. A `PreToolUse` hook blocks by **exit 2** with the
+reason on stderr, or exit 0 with a `permissionDecision: deny` payload on stdout.
+**Any other exit code is non-blocking, so a crashing guard fails open** and stops
+guarding without announcing it — write the guard to exit 2 on its own errors. Keep
+hooks cheap and narrowly matched; the full suite belongs in CI, which is late, and
+late is the right trade for slow.
+
+## The retro carries commits
+
+Standing instructions (max ten) carry the commit that introduced them and the commit
+of the run in which they last fired; every log entry, every retirement and every run
+stamp carries one; and every SHA must resolve. A `file:line` rots at the next edit,
+while `git show <sha>` reconstructs the whole incident months later. Entries older
+than the last five run stamps **move** to an append-only archive that is *queried*
+by the task's nouns rather than read — which keeps the in-force file short enough to
+read in full, and makes pruning cost no knowledge.
+
 ## super-ux for user-facing tasks (recommended)
 
 If the task touches any UI (web/mobile/CLI/TUI), the WHY→UI→scenario chain comes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.6.1",
+  "version": "1.7.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"
@@ -22,7 +22,10 @@
   "homepage": "https://github.com/ssheleg/task-pipeline#readme",
   "bugs": "https://github.com/ssheleg/task-pipeline/issues",
   "license": "MIT",
-  "author": "ssheleg",
+  "author": {
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
+  },
   "engines": {
     "node": ">=16"
   },

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

@@ -2,9 +2,10 @@
   "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.6.1",
+  "version": "1.7.0",
   "author": {
-    "name": "ssheleg"
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
   },
   "homepage": "https://github.com/ssheleg/task-pipeline",
   "repository": "https://github.com/ssheleg/task-pipeline",

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

@@ -37,11 +37,18 @@ the environment resolves.
 ## Prerequisites — none required
 
 **Every stage's doctrine ships inside this skill.** There is no required companion
-plugin, nothing to resolve at preflight, no version skew with someone else's repo,
-and no stage that can fail because a dependency is missing:
+plugin, nothing to resolve at preflight and no version skew with someone else's
+repo. Stages 1 and 6–9 additionally run the *host's own* commands and optional
+tools, and **no stage blocks on an install** — stage 1 falls back to web search, the
+wiki and the code graph are recommendations. The **one** exception is deliberate and
+named: on a user-facing task the stage-3 UX track requires super-ux, and the spec
+gate stops until it is installed.
 
 | Stage | Built-in doctrine |
 |---|---|
+| 0 + 9 + any settled decision · The documentation system | [`references/documentation.md`](references/documentation.md) |
+| 6–10 + any check you write · Gates | [`references/gates.md`](references/gates.md) |
+| any agent-time enforcement · Hooks | [`references/hooks.md`](references/hooks.md) |
 | 0 Knowledge harvest (pre-grill) | [`references/knowledge-sources.md`](references/knowledge-sources.md) |
 | 0 + 9 The code graph (graphify — recommended, never required) | [`references/knowledge-graph.md`](references/knowledge-graph.md) |
 | 0 Intake grill | [`references/grill.md`](references/grill.md) |
@@ -101,9 +108,12 @@ question: pull what the project already knows about this task from the code, the
 **code graph** if one is built
 ([`references/knowledge-graph.md`](references/knowledge-graph.md) — graphify;
 recommended, never required),
-`CLAUDE.md`, `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs, **the
-retro's standing instructions** — `docs/superpowers/retro.md`, read in full because
-they *bind* this run ([`references/retrospective.md`](references/retrospective.md)) —
+`CLAUDE.md`, `CONTEXT.md`/ADRs, **the decision register**, `docs/` + `docs/ux/`,
+past pipeline briefs, **the retro's standing instructions, run stamps and recent
+log** — `docs/superpowers/retro.md`, read in full because they *bind* this run and
+are bounded by construction, while the archive under `docs/superpowers/retro/` is
+**queried** by the task's nouns
+([`references/retrospective.md`](references/retrospective.md)) —
 the **knowledge wiki** if one is installed
 ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) — recommended, never
 required) and any **other repo or hosted doc system the project names as its
@@ -121,6 +131,18 @@ has. Doc-side findings are fixed at stage 9; absences become REQ rows at stage 1
 ([`references/knowledge-graph.md`](references/knowledge-graph.md),
 [`references/audit.md`](references/audit.md)).
 
+**Documentation is a deliverable, and it has a gate**
+([`references/documentation.md`](references/documentation.md)). Stage 0's harvest
+reads what the project knows; a second phase asks the four questions that make it a
+*system* — where settled things live, what each fact's single home is, what a change
+of type X obliges, and what proves it — and writes them to `docs/DOCMAP.md`. From
+then on the **Doc Loop** fires whenever anything is settled, at **any** stage, not
+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"*
+stops being an assertion and becomes a command with an exit code. Governance is a
+by-product: the run already produces decisions, so recording one is transcription
+plus a stable id, never a second act of thinking.
+
 **The run teaches the next run — and the list stays short.** Every gate is good at
 *this* run and blind across runs, so the same class of failure can be caught, fixed
 and forgotten five times with nothing noticing it is the same one. The last act of
@@ -184,7 +206,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: **answer from the brief's autonomy section rather
+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
@@ -215,7 +243,7 @@ capable available — see `references/model-tiering.md`).
 
 | # | Stage | Invoke | Gate | Type |
 |---|---|---|---|---|
-| 0 | Intake grill — **mandatory** | built in: [`references/knowledge-sources.md`](references/knowledge-sources.md) (harvest) → [`references/grill.md`](references/grill.md) (interview) | source ledger written; shared understanding reached; autonomy sweep covered; brief locked + confirmed | manual |
+| 0 | Intake grill — **mandatory** | built in: [`references/knowledge-sources.md`](references/knowledge-sources.md) (harvest) → [`references/grill.md`](references/grill.md) (interview) | source ledger written; **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 |
 | 1 | Docs study | `context7` (resolve-library-id → get-library-docs) / `context7-docs` | contracts grounded on fetched docs | auto |
 | 2 | Brainstorm + decompose | built in: [`references/brainstorm.md`](references/brainstorm.md) + **UI detection** + [`references/decomposition.md`](references/decomposition.md) for platforms | design approved; UI verdict recorded; every REQ answered; platform: module map approved | manual |
 | 3 | Spec | built in: [`references/spec.md`](references/spec.md) — **UI → super-ux chain first** (`/ux` → `ux-foundation` CJM → `ux-flows` screens → `ux-scenarios` → `/ux-lint`), then spec `docs/superpowers/specs/…-design.md` | committed + reviewed; UI: chain validated, linter green, scenarios/`SCR-` traced | manual |
@@ -224,8 +252,8 @@ capable available — see `references/model-tiering.md`).
 | 6 | Tests | host test runner + built-in [`references/tdd.md`](references/tdd.md) + [`references/learned.md`](references/learned.md) | 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 | auto |
 | 7 | Lint + deploy | host lint → deploy per host convention | lint clean + suite green before deploy; deploy needs a go (or the brief's specific standing authorization) | manual |
 | 8 | Post-deploy | tail deploy logs / health-check | clean boot or honest degradation report | auto |
-| 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki), recommended) → `/graphify . --update` ([`references/knowledge-graph.md`](references/knowledge-graph.md), recommended) | every stale row of the stage-0 source ledger updated; 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)) | auto |
-| 10 | **Acceptance** | built in: [`references/audit.md`](references/audit.md) (ladder walk) → [`references/acceptance.md`](references/acceptance.md) (coverage table) → [`references/retrospective.md`](references/retrospective.md) (retro: prune, stamp, entry) | 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); operator signs off; **the retrospective written last — prune before entry, list at or under its cap, deletions logged, run stamped, counts printed** | manual |
+| 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki), recommended) → `/graphify . --update` ([`references/knowledge-graph.md`](references/knowledge-graph.md), recommended) | 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** | built in: [`references/audit.md`](references/audit.md) (ladder walk) → [`references/acceptance.md`](references/acceptance.md) (coverage table) → [`references/retrospective.md`](references/retrospective.md) (retro: prune, stamp, entry) | 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); 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 — prune before entry, list at or under its cap, every deletion and every entry carrying its commit, entries older than five stamps rotated into the archive, run stamped with its commit, counts printed** | manual |
 
 
 ### Stage 10 in a project of several repositories
@@ -290,8 +318,11 @@ automation is on — `pipeline.schema.json` is the only contract.
 - `references/grill.md` — the built-in stage-0 grill: loop, domain awareness, autonomy sweep
 - `references/acceptance.md` — the built-in stage-10 close-out: REQ coverage, evidence, sign-off
 - `references/retrospective.md` — stage 10's last act: the project retro (`docs/superpowers/retro.md`), the three grades of fix, the mandatory prune and its cap of ten
+- `references/documentation.md` — cross-cutting: the doc inventory, registers and ids, SSOT, the Doc Loop, supersede semantics, the propagation matrix, intent vs as-built
+- `references/gates.md` — cross-cutting: the two axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors, where a gate runs
+- `references/hooks.md` — agent-time enforcement: the PreToolUse contract, the fail-open hazard, placement, and the Claude-Code-only limit
 - `references/audit.md` — cross-cutting: the L0→L7 ladder and its seams (what was never written), axis rotation, ratchets, proven checks
-- `references/learned.md` — cross-cutting: fourteen rules earned by failure on a real multi-repository build, each with the incident behind it, its check and its exit criterion; plus the two that no check can decide
+- `references/learned.md` — cross-cutting: fifteen rules earned by failure on a real multi-repository build, each with the incident behind it, its check and its exit criterion; plus the two that no check can decide
 - `references/brainstorm.md` — stage 2: design dialogue, approaches, UI detection, hard gate
 - `references/spec.md` — stage 3: UX track order, the spec contract, self-review, review gate
 - `references/planning.md` — stage 4: zero-context plan format, parallel groups, no placeholders

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

@@ -11,13 +11,14 @@
       "skills": [
         "task-pipeline:knowledge-sources",
         "task-pipeline:knowledge-graph",
+        "task-pipeline:documentation",
         "wiki-query",
         "graphify",
         "task-pipeline:grill"
       ],
       "gate": {
         "type": "manual",
-        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, THE CODE GRAPH when one is built (references/knowledge-graph.md: graphify query/affected/god-nodes answer reach, which grep cannot; detect graphify-out/graph.json — recommended, never required), CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, THE RETRO'S STANDING INSTRUCTIONS (docs/superpowers/retro.md — read IN FULL, not queried: they are capped at ten and they BIND this run; stamp each one the moment it fires, since that date is the only evidence behind stage 10's cold-retirement rule — references/retrospective.md), the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'; the graph's row carries its build date, because a graph goes stale like any other source). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets, and for UI tasks the design surface: Figma on or text-only, is the Figma MCP connected, and if it is not — ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; plus, with Figma on, the DESIGN DESTINATION — which team/org by name and which file (the recorded one, a URL the operator gives, or creation in that named team with the creation explicitly authorized), written into the project's canonical record before the first frame, and never created while a recorded file resolves — an unreachable recorded file means stop and ask, never make a replacement) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded."
+        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, THE CODE GRAPH when one is built (references/knowledge-graph.md: graphify query/affected/god-nodes answer reach, which grep cannot; detect graphify-out/graph.json — recommended, never required), CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, THE RETRO'S STANDING INSTRUCTIONS (docs/superpowers/retro.md — read IN FULL, not queried: they are capped at ten and they BIND this run; stamp each one the moment it fires, since that date is the only evidence behind stage 10's cold-retirement rule — references/retrospective.md), the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'; the graph's row carries its build date, because a graph goes stale like any other source). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets, and for UI tasks the design surface: Figma on or text-only, is the Figma MCP connected, and if it is not — ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; plus, with Figma on, the DESIGN DESTINATION — which team/org by name and which file (the recorded one, a URL the operator gives, or creation in that named team with the creation explicitly authorized), written into the project's canonical record before the first frame, and never created while a recorded file resolves — an unreachable recorded file means stop and ask, never make a replacement) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded. PHASE 1b, THE DOCUMENTATION INVENTORY (references/documentation.md): four questions answered into docs/DOCMAP.md before the interview — where settled things live (the DECISION HOME, and there is exactly one per project: an existing docs/adr/ IS the register and is recorded as such, never duplicated), what each fact's single home is, what a change of type X obliges (THE PROPAGATION MATRIX, non-empty, every row naming the check that enforces it or the word 'review' with a one-line reason), and what proves it (the gate command). A project with no answers gets them seeded — registers, matrix and scripts/check-docs.sh from the skill's templates — and the seeding is recorded as the register's first entry; the seeded gate must exit 0 on its own seeds, because a project that starts red teaches everyone on day one that the gate is noise. The regime is recorded. PHASE 1c, RECONCILE: git says how it should be, the run record says how it turned out — read both for the area about to be touched and resolve every divergence (the document is stale, the record is wrong, or they genuinely disagree and that is a decision), because starting on an unresolved divergence means building against a system that does not exist. The retro's in-force sections are read IN FULL and its archive is QUERIED by the task's nouns."
       }
     },
     {
@@ -142,13 +143,15 @@
       "model": "default",
       "skills": [
         "host:module-docs",
+        "task-pipeline:documentation",
+        "task-pipeline:gates",
         "wiki-update",
         "task-pipeline:knowledge-graph",
         "graphify"
       ],
       "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"
+        "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"
       }
     },
     {
@@ -163,7 +166,7 @@
       ],
       "gate": {
         "type": "manual",
-        "check": "Close the circle. FIRST the LADDER WALK (references/audit.md), because the REQ table can only find what was named and lost — a comparison needs two sides and an absence has one: walk each REQ bottom-up through its rungs (decision -> spec section -> contract AND its failure behavior -> plan task -> change -> executed test -> surface/docs), check the seam at each step, order findings BY SEAM not by file, and turn every absence into a new REQ row with its check BEFORE the table is written; findings belonging to a lower layer go back to that layer (spec -> stage 3, plan -> stage 4); record the pass's two counts (new findings vs findings caused by this run's own fixes) so the next pass can tell whether the axis is exhausted. THEN the coverage table: every REQ has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded, and a green from a check nobody has watched fail against a planted defect is not evidence at all; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved and the ledger's counts are printed beside this verdict, so 'green' never reads as 'verified'; EVERY REPOSITORY IS CLOSED, THE PARENT INCLUDED — a submodule is finished only when its parent points at it, so 'git submodule status' shows no line starting with '+' and every repo is clean and pushed ('git -C <repo> status --porcelain' and 'git -C <repo> log @{u}..HEAD' both empty), because a parent records a submodule as a pointer to one commit and moving the submodule does not move the pointer: neither repo looks wrong alone and the disagreement survives every check that runs inside one; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off. LAST ACT, THE RETROSPECTIVE (references/retrospective.md, written to docs/superpowers/retro.md — one file per project, not per run, because every gate in this flow is good at THIS run and blind across runs): PRUNE BEFORE YOU ADD — every standing instruction checked against its three retirement triggers (it became a check; every path/command/stage it names is gone; it has not fired in the last five run stamps), the list held to its hard cap of ten (at eleven the oldest never-fired row goes — 'they all matter' is the state in which the list stopped being read), and EVERY DELETION LOGGED as one line, never silent; THEN stamp the run (date, topic, verdict, counts); THEN, only if the run diverged, write the entry — symptom with evidence, the stage it surfaced at, the stage that OWNED it, the root cause ('the agent was careless' is not one), the fix by grade (mechanical check > standing instruction with its retire-when written at birth > a note that expires in two runs), and the check that catches it the first time from now on. A retro left empty after a messy run is the failure this file exists to stop, and the retro counts are printed beside this gate's verdict like the carry-over ledger's, so a list that quietly grew back is visible where it happened."
+        "check": "Close the circle. FIRST the LADDER WALK (references/audit.md), because the REQ table can only find what was named and lost — a comparison needs two sides and an absence has one: walk each REQ bottom-up through its rungs (decision -> spec section -> contract AND its failure behavior -> plan task -> change -> executed test -> surface/docs), check the seam at each step, order findings BY SEAM not by file, and turn every absence into a new REQ row with its check BEFORE the table is written; findings belonging to a lower layer go back to that layer (spec -> stage 3, plan -> stage 4); record the pass's two counts (new findings vs findings caused by this run's own fixes) so the next pass can tell whether the axis is exhausted. THEN the coverage table: every REQ has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded, and a green from a check nobody has watched fail against a planted defect is not evidence at all; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved and the ledger's counts are printed beside this verdict, so 'green' never reads as 'verified'; EVERY REPOSITORY IS CLOSED, THE PARENT INCLUDED — a submodule is finished only when its parent points at it, so 'git submodule status' shows no line starting with '+' and every repo is clean and pushed ('git -C <repo> status --porcelain' and 'git -C <repo> log @{u}..HEAD' both empty), because a parent records a submodule as a pointer to one commit and moving the submodule does not move the pointer: neither repo looks wrong alone and the disagreement survives every check that runs inside one; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off. LAST ACT, THE RETROSPECTIVE (references/retrospective.md, written to docs/superpowers/retro.md — one file per project, not per run, because every gate in this flow is good at THIS run and blind across runs): PRUNE BEFORE YOU ADD — every standing instruction checked against its three retirement triggers (it became a check; every path/command/stage it names is gone; it has not fired in the last five run stamps), the list held to its hard cap of ten (at eleven the oldest never-fired row goes — 'they all matter' is the state in which the list stopped being read), and EVERY DELETION LOGGED as one line, never silent; THEN stamp the run (date, topic, verdict, counts); THEN, only if the run diverged, write the entry — symptom with evidence, the stage it surfaced at, the stage that OWNED it, the root cause ('the agent was careless' is not one), the fix by grade (mechanical check > standing instruction with its retire-when written at birth > a note that expires in two runs), and the check that catches it the first time from now on. A retro left empty after a messy run is the failure this file exists to stop, and the retro counts are printed beside this gate's verdict like the carry-over ledger's, so a list that quietly grew back is visible where it happened. EVERY LESSON CARRIES ITS COMMIT: each standing instruction has the SHA that introduced it and the SHA of the run in which it last fired, each log entry and each retirement carries one, the run stamp carries the run's own — a file:line rots at the next edit while 'git show <sha>' reconstructs the whole incident two months later — and every SHA must resolve, which the documentation gate checks with 'git rev-parse --verify'. ROTATION: entries older than the last five run stamps MOVE into docs/superpowers/retro/YYYY-QN.md, which is append-only and QUERIED rather than read, so the in-force file stays short enough to be read in full and pruning costs no knowledge. AND THE GATE ITSELF IS PROVEN: every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, with the probe recorded, and its ratchet counts are printed beside this verdict (references/gates.md)."
       }
     }
   ],

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

@@ -9,11 +9,16 @@ shape.
 
 ```
 CONTEXT.md                            # stage 0 — domain glossary, written inline as terms resolve
+scripts/check-docs.sh                 # stage 0 seeds it, 9 runs it, 10 proves it — the docs gate
 docs/
+  DOCMAP.md                           # stage 0 — the inventory: registers, homes, matrix, gates
+  DECISIONS.md                        # the decision register (DEC-####), append-only …
+  OPEN_QUESTIONS.md                   #   … and its questions (OQ-####) — never delete a resolved row
   adr/
-    NNNN-<slug>.md                    # stage 0 — ADRs for hard-to-reverse decisions
+    NNNN-<slug>.md                    # the OTHER permitted decision home — one project uses ONE
   superpowers/
     retro.md                          # stage 10's last act — ONE per project, not per run
+    retro/YYYY-QN.md                  # the archive: rotated entries + retirements, queried not read
     specs/
       YYYY-MM-DD-<topic>-brief.md     # stage 0 — locked intake brief (grill output)
       YYYY-MM-DD-<topic>-carryover.md # stage 0 seeds it; EVERY stage appends; stage 10 reads it
@@ -63,7 +68,10 @@ record (see `build.md`).
 | 0→10 all | `specs/<topic>-carryover.md` — append-only ledger (seed from `templates/carryover.md`) | stage 10, in full |
 | 10 Acceptance | `specs/<topic>-acceptance.md` — every REQ with a status and evidence | the operator |
 | 10 Retro | `superpowers/retro.md` — standing instructions (max 10), the problem→cause→fix log, run stamps. Pruned **before** anything is added (`retrospective.md`) | **stage 0 of the next run**, in full |
-| 0 Grill (domain) | `CONTEXT.md`, `docs/adr/NNNN-<slug>.md` — created **lazily**, only when a term resolves or a decision qualifies | stages 2–4 + the repo |
+| 0 Inventory | `docs/DOCMAP.md` + the registers + `scripts/check-docs.sh` — seeded **only when absent**, and the seeding is the register's first entry ([`documentation.md`](documentation.md)) | every later stage; **stage 9** walks the matrix, **stage 10** proves the gate |
+| 0 Grill (domain) | `CONTEXT.md`, `docs/adr/NNNN-<slug>.md` — created **lazily**, only when a term resolves or a decision qualifies. Where `docs/adr/` **is** the register, entries carry the register's field set | stages 2–4 + the repo |
+| any stage | a register entry per settled thing, via the **Doc Loop** — recorded, resolved, propagated, committed with its id | the next run's harvest |
+| 10 Retro rotation | `docs/superpowers/retro/YYYY-QN.md` — entries older than five stamps, plus every retirement, each with its commit | queried by a later run's harvest |
 | 2 Decompose | `specs/<topic>-modules.md` — module map, build order, contracts, per-module status (platforms only) | stages 3–10, every module's run |
 | 3 Spec | `specs/<topic>-design.md` — module dossier for a decomposed platform (+ links `docs/ux/*` for UI) | stage 4 |
 | 4 Plan | `plans/<topic>.md` | stage 5 |

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

@@ -67,7 +67,7 @@ absence findable.
 | Rung | Layer | The artefact that must exist |
 |---|---|---|
 | **L0** | Requirement | a `REQ-###` row in the brief **with a named check** |
-| **L1** | Decision | the locked decision, ADR or `CONTEXT.md` term this REQ rests on |
+| **L1** | Decision | the locked decision this REQ rests on — **an entry in the register** (`DEC-####` or an ADR), or a `CONTEXT.md` term ([`documentation.md`](documentation.md)) |
 | **L2** | Design | a spec section carrying `covers: REQ-…` |
 | **L3** | Contract | an exact signature or schema · **and its failure behavior** |
 | **L4** | Task | a plan task with `Implements:` and a DoD satisfiable **as written** |
@@ -195,6 +195,10 @@ defect class becomes permanent. If the class genuinely cannot be checked
 mechanically, say so in one line and *say why*; that sentence is itself a finding
 worth having.
 
+**How to write, place, arm, probe and own that script is
+[`gates.md`](gates.md).** "Put it in a script" with no place to put it is how the
+third instance ends up in the ledger too.
+
 ### 2. Every pass changes the axis, not the effort
 
 "Look again, more carefully" is what converges. Passes must be **orthogonal by