task-pipeline-skill 1.6.0 → 1.7.0

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

@@ -0,0 +1,164 @@
+# Hooks — agent-time enforcement, and the limit first
+
+**One job: stop a bad edit before it lands, and never claim protection you do not
+have.** A hook is rung 5 of [`gates.md`](gates.md)'s ladder — the only mechanism
+that acts *while the agent is working* rather than after the commit.
+
+## The limit, before the capability
+
+**Hooks exist only in Claude Code.** On Cursor, Codex and the other agents a skill
+can be installed and read, but there is no `PreToolUse`, so nothing blocks anything.
+On those agents the same rules run as a self-check written into the skill body, and
+the run is recorded **`ungated`**.
+
+**Never describe a project as protected when its agents run outside Claude Code.**
+The gap between "the rule exists" and "the rule is enforced" is invisible from
+inside a transcript, and a false guarantee is worse than a stated absence: everyone
+downstream stops checking.
+
+## The events
+
+| Event | Fires | Used for |
+|---|---|---|
+| `SessionStart` | session opens (matcher `startup\|resume`) | register the run, print the board, name the one next action |
+| `PreToolUse` | before a tool call | **block** — the only event that can refuse |
+| `PostToolUse` | after every tool call | bookkeeping: renew a lease, stamp a marker |
+| `SessionEnd` | session closes | release leases, flush the journal |
+
+## The `PreToolUse` contract
+
+A hook blocks a call in **either** of two ways:
+
+- **exit 2**, with the reason on **stderr** (stdout is ignored); or
+- **exit 0** with this on stdout:
+
+```json
+{"hookSpecificOutput":{"hookEventName":"PreToolUse",
+ "permissionDecision":"deny",
+ "permissionDecisionReason":"docs gate failed: 2 undefined ids in docs/ARCHITECTURE.md"}}
+```
+
+**Any other exit code is a non-blocking error**: execution continues and stderr is
+shown in the transcript. So **a crashing guard fails open** — it stops guarding and
+nothing announces that it has. Write the guard to `exit 2` on its own internal
+errors, or accept that a typo in it silently removes the protection everyone
+believes is there.
+
+That asymmetry is the whole reason this file leads with the limit: a hook is the
+strongest rung and the one whose failure is quietest.
+
+## What the hook receives
+
+JSON on stdin: `session_id`, `prompt_id`, `transcript_path`, `cwd`,
+`permission_mode`, `hook_event_name`, `tool_name`, `tool_input`, `tool_use_id`.
+
+`tool_input` is where the target lives — `file_path` for an edit, `command` for a
+Bash call. Parse it; do not infer the target from anything else in the environment.
+
+## Where it lives
+
+| Placement | Scope | Use when |
+|---|---|---|
+| the project's `.claude/settings.json` | this repository | the rule is this project's |
+| a plugin's `hooks/hooks.json`, paths via `${CLAUDE_PLUGIN_ROOT}` | every project the plugin is installed in | the rule travels with a tool |
+
+**A globally installed plugin must exit 0 immediately when the project has no
+config for it.** Otherwise installing it once changes every other repository on the
+machine, and the first surprising denial is debugged in the wrong project.
+
+## Matchers
+
+```json
+{ "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+  "hooks": [{ "type": "command", "command": "…/guard.sh", "timeout": 20 }] }
+```
+
+- a tool-name pattern (`Edit|Write|…`), or `"*"` for every call;
+- for a specific shell command, add `"if": "Bash(git commit *)"` beside
+  `"matcher": "Bash"`.
+
+Match as **narrowly** as the rule allows. A `"*"` matcher on a blocking event puts
+your script in the path of every tool call the agent makes.
+
+## Performance
+
+A `PostToolUse` hook on `"*"` runs after **every** call, so it must be a no-op in
+the common case: read one timestamp file, return. Touch the network at most once
+per throttle interval. If it becomes slower than that, the throttle is broken —
+**fix the throttle, never remove the hook**, because a hook removed for latency is
+a protection removed permanently for a reason that had a fix.
+
+## What belongs in a hook, and what does not
+
+**Belongs:** cheap, deterministic, and about an edit happening *right now* — a
+guarded path, a staged file, a lease that is not held, a command with a shape the
+project forbids.
+
+**Does not belong:** the full test suite; anything needing the network on every
+call; anything whose answer requires a human. Those are rungs 3 and 4
+([`gates.md`](gates.md)) — CI is late, and late is the correct trade for slow.
+
+The test is one question: *if this fires, can the agent fix it in the next ten
+seconds without asking anybody?* If not, blocking here only converts a review
+comment into a dead end.
+
+## A worked example
+
+The one hook this skill ships — run the documentation gate before a commit, and
+refuse the commit if it fails. It is
+[`../templates/hooks.example.json`](../templates/hooks.example.json); copy it into
+the project's `.claude/settings.json`.
+
+```json
+{ "hooks": { "PreToolUse": [
+  { "matcher": "Bash", "if": "Bash(git commit *)",
+    "hooks": [{ "type": "command", "shell": "bash", "timeout": 60,
+      "command": "bash scripts/check-docs.sh >&2 || exit 2" }] } ] } }
+```
+
+`|| exit 2` is the contract, not a flourish: without it the gate's own `exit 1`
+lands in the "non-blocking error" branch and the commit proceeds.
+
+## Debugging
+
+| Symptom | Cause |
+|---|---|
+| Guarded edits go through | the guard crashed — any exit code other than 2 is non-blocking. Run it by hand |
+| Everything is denied | no config, or no lease. The tool's `status` says which |
+| Session start is slow | the backend is unreachable; it must time out and degrade, never hang |
+| The renew hook floods the log | the throttle file is not being written — check the path is writable |
+
+Run the guard directly and see what it decides:
+
+```bash
+echo '{"tool_name":"Edit","tool_input":{"file_path":"docs/DECISIONS.md"},"cwd":"'"$PWD"'"}' \
+  | bash .claude/hooks/guard.sh; echo "exit=$?"
+```
+
+## Removing them
+
+Delete the `hooks` block from the project's `.claude/settings.json`. Everything the
+hooks enforced is still available as a command and still stated in the doctrine —
+and the run is **`ungated`** from then on, which is a thing to say out loud rather
+than a detail to omit.
+
+## Leases are not reimplemented here
+
+Guarded registers and lease arbitration belong to a coordination tool
+([`companion-skills.md`](companion-skills.md) names the optional one). This skill
+ships the **doctrine** and the one example above.
+
+Two implementations of one lease will disagree, and the disagreement is invisible:
+each believes it holds the lock, both write, and the register ends up with two
+entries carrying one id — which is the exact failure the lease existed to prevent.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "The hook is installed, so the repo is protected" | Only in Claude Code, and only while the guard exits 2. Any other exit code fails open silently. |
+| "It's fine, the guard can't crash" | Then it costs one line to make crashing block instead of pass. Write the line. |
+| "I'll match `*` and filter inside the script" | Now every tool call pays your script's startup. Match narrowly; the matcher is free and the script is not. |
+| "The hook is slow, I'll disable it for now" | "For now" survives the session and the memory of why. Fix the throttle. |
+| "I'll put the test suite in the hook, it's the strongest gate" | It is the strongest and the most expensive. A rule that takes two minutes to answer belongs in CI. |
+| "Other agents will follow the doctrine anyway" | They might. What they will not do is *block*, and the run must say `ungated` so nobody mistakes intention for enforcement. |

package/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md

@@ -29,9 +29,11 @@ makes the grill's answers *checkable* instead of merely confident.
 | 2 | **The code graph** | `graphify-out/graph.json` — see below | *reach*: what calls this, what breaks if it moves, what every change passes through |
 | 3 | **Host agent docs** | `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/` | conventions, commands, deploy path, house rules |
 | 4 | **Domain docs** | `CONTEXT.md` / `CONTEXT-MAP.md`, `docs/adr/` | the glossary and the decisions with their reasons |
+| 4a | **The decision register and the doc map** | `docs/DECISIONS.md` **or** `docs/adr/` — `docs/DOCMAP.md` says which ([`documentation.md`](documentation.md)) | what is already settled, what it superseded, and which documents this run will owe |
 | 5 | **Product/UX docs** | `docs/ux/` (super-ux chain), `README`, runbooks | user-facing behavior that is already specified |
 | 6 | **Pipeline history** | `docs/superpowers/specs/`, `plans/`, past `-carryover.md` | what a previous run of this pipeline decided or deferred |
-| 7 | **The retro's standing instructions** | `docs/superpowers/retro.md` ([`retrospective.md`](retrospective.md)) | what previous runs got wrong here — **read in full**, they are capped at ten |
+| 7 | **The retro, in force** | `docs/superpowers/retro.md` ([`retrospective.md`](retrospective.md)) | what previous runs got wrong here — **read in full**: standing instructions (capped at ten), run stamps and the recent-log window, all bounded by construction |
+| 7a | **The retro archive** | `docs/superpowers/retro/YYYY-QN.md` | *have we been bitten by this class before?* — **queried** by the task's nouns, never read end to end |
 | 8 | **The knowledge wiki** | see below | distilled cross-project knowledge, prior sessions, why decisions were made |
 | 9 | **Other doc repos the project names** | a docs repo URL or submodule in `CLAUDE.md`/`README`, a sibling checkout, a `docs/` monorepo package | specs, contracts and runbooks that live outside this repo |
 | 10 | **Hosted doc systems the project names** | Notion / Confluence / Google Docs referenced in the project | the same, when the team keeps them there |
@@ -173,10 +175,22 @@ Three shapes and what to do with each:
 document; they may not do it by accident. The point of quoting the source is that
 the override becomes a recorded decision instead of an undetected divergence.
 
-**Precedence when two sources disagree with each other:** code > host docs and
-ADRs > the wiki > anyone's memory. The wiki is *distilled* knowledge and can lag
-the repo by months; the code is what runs. A disagreement between them is a grill
-question, never a silent pick — and it is usually a sign the doc is due an update.
+**Precedence — and it splits in two, because two different questions are being
+asked.**
+
+*For what **is**:* code, then host docs and ADRs, then the wiki, then anyone's
+memory. The wiki is *distilled* knowledge and can lag the repo by months; the code
+is what runs.
+
+*For what **should be**:* the **register outranks the code**
+([`documentation.md`](documentation.md)). A decision that is accepted and not yet
+built is still the decision, and code that contradicts it is a finding — a bug, or
+an unrecorded reversal — never a tie-break in the code's favour. Getting this
+backwards is how a run "discovers" that the system does not work the way the
+project decided, and quietly builds the version it found.
+
+Either way a disagreement is a grill question, never a silent pick, and it is
+usually a sign that something is due an update.
 
 ## Close the loop — stage 9 updates what stage 0 read
 
@@ -184,6 +198,13 @@ The ledger is the stage-9 work list. For each row:
 
 - **Host repo docs, ADRs, runbooks, `docs/ux/`** — updated in the **same change**,
   per the host's own rules ([`conventions.md`](conventions.md)).
+- **The register and the doc map** — every decision this run settled gets an entry
+  with an id; every question it answered is flipped; the doc map gains any new
+  document class or ratchet. Note that this list and the **propagation matrix** are
+  different lists on purpose: the ledger is what you *read*, the matrix is what you
+  *owe* ([`documentation.md`](documentation.md)), and stage 9 walks both.
+- **The retro** — prune, stamp, entry, and rotate what aged out into the archive
+  ([`retrospective.md`](retrospective.md)).
 - **Anything the run proved stale** — including a doc that was "wrong but nobody
   had time": that's why the conflict was logged in phase 2 instead of only being
   resolved verbally.

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

@@ -4,7 +4,7 @@
 it.** Every rule here names the incident that produced it. A rule with no incident behind it is
 somebody's preference, and it will be argued with at the worst moment.
 
-They come from one 229-decision, 72-document specification built across four repositories with
+They come from one 260-decision, 72-document specification built across four repositories with
 several agents working at once. Nothing here is hypothetical.
 
 **A rule belongs in the table only when it has a check.** Two of the lessons below could not be
@@ -31,6 +31,7 @@ to be enforced and is not is the same failure as a gate that prints `FAIL` and e
 | 12 | **Tests create what they assert on** | any test touching shared state | run the suite against a cold, empty environment | the cold run and the warm run agree |
 | 13 | **Local infrastructure does not fight the host** | any dev compose or service definition | assume the host already runs the defaults | services reachable with the host's own still running |
 | 14 | **A document may not send a reader to something absent** | any instruction naming a command, file or install | resolve it | the gate fails when the target does not exist |
+| 15 | **Identity before coordination** | any lease, lock, claim or run id | ask what two instances with the same identity would do, and make the tool answer it | two instances demonstrably get two identities |
 
 ---
 
@@ -94,6 +95,18 @@ the migration failed with a permission error that named nothing about the collis
 was not installed, with no install line anywhere and no statement of what a session without it
 actually is.
 
+**15 · Identity.** The coordination plugin derived one run id **per checkout**. A hook has the
+session id in its environment and a plain shell command does not, so the second session in a
+checkout adopted the first one's identity: **an entire day of work was performed holding another
+session's leases**, and the end-of-work check that had just been written offered to release
+*theirs*. It was invisible from inside — `whoami` reported a lease and a run id, both plausible,
+both somebody else's — and it surfaced only because a new command printed a lease nobody could
+account for. This is the same failure as *the one instruction* below, and it is in the table rather
+than only in that list because it **has** a check. Follow-on, from the first two attempted fixes:
+**do not infer identity from strings the environment is also free to contain** — matching `"claude"`
+in a process command line matched the throwaway shell of every tool call, and matching the binary
+path hit the same wall. Prefer a fact something authoritative wrote down.
+
 ---
 
 ## The two that are not in the table, and why
@@ -128,13 +141,15 @@ answer would have exposed it in a minute.
 
 | Stage | Rules that apply |
 |---|---|
+| 0 Inventory · 9 Docs · any register write | 8 (compute), 14 (targets resolve — including every commit SHA in the retro), 15 (identity before a lease) — see [`documentation.md`](documentation.md) |
+| any check you write | 4, 5, 7, 10, 11 — the procedure is [`gates.md`](gates.md) |
 | 3 Spec · 4 Plan | 2 (both directions), 8 (compute, never restate) |
 | 5 Dev | 9 (generators seed green), 12 (tests create their own state), 13 (local infra) |
 | 6 Tests | 4, 5, 10, 11 — every new check probed both ways, measured, and asserted on its exit code |
 | 9 Docs | 8, 14 — every number computed, every target resolvable |
 | 10 Acceptance | 1, 3, 6, 7 — axis rotation recorded, closure verified against artefacts, classes swept, ratchets printed |
 
-**This file is the shipped list; a project keeps its own.** These fourteen were
+**This file is the shipped list; a project keeps its own.** These fifteen were
 earned on someone else's build and travel with the skill. The lessons *your*
 project buys go in its retro ([`retrospective.md`](retrospective.md) →
 `docs/superpowers/retro.md`), where they are capped, pruned and retired — and a

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

@@ -5,14 +5,16 @@ done. It exists because the pipeline's gates are good at *this* run and blind
 across runs: the same class of failure can be caught, fixed and forgotten five
 times, and nothing in the flow notices it is the same one.
 
-**Artifact:** `docs/superpowers/retro.md` — **one per project, not per run**,
-committed. It has three parts and a hard size limit:
+**Two artifacts, and the split is the point.** A file that is read *in full* every
+run may not contain anything that grows without limit — otherwise the cap that
+justifies reading it protects one section while the file below it doubles.
 
-| Part | What's in it | Read by |
+| Artifact | Parts | How it is read |
 |---|---|---|
-| **Standing instructions** | the rules currently in force — max **10** | stage 0, in full, every run |
-| **Log** | problem → cause → fix → check, newest first, plus every retirement | a human, and stage 0 when the terms match |
-| **Run stamps** | one line per run: date, topic, verdict | the prune (this is what makes "five runs" countable) |
+| `docs/superpowers/retro.md` — **one per project** | **Standing instructions** (max **10**) · **Recent log** (entries from the last five run stamps) · **Run stamps** | stage 0, **in full** — all three are bounded by construction |
+| `docs/superpowers/retro/YYYY-QN.md` — the archive | every entry and every retirement ever written, append-only | **queried** by the task's nouns; never read end to end |
+
+Seed the archive from [`../templates/retro-archive.md`](../templates/retro-archive.md).
 
 Every run writes a **stamp** and runs the **prune**. Only a run that *diverged*
 writes an entry. A retro that is empty after a messy run is the exact failure this
@@ -34,6 +36,38 @@ Required fields, and none of them is optional:
 | **Root cause** | why the pipeline permitted it. "The agent was careless" is not a cause — it is the absence of one, and it produces no fix |
 | **Fix** | one of the three grades below |
 | **The check** | what would have caught this the first time. If the honest answer is "nothing yet", that is the fix, and it is grade 1 |
+| **Commit** | the short SHA of the change that fixed it |
+
+## Every lesson carries its commit
+
+A standing instruction carries **two** SHAs — `Commit` (the change that introduced
+it) and `Fired at` (the last run in which it fired) — and every log entry and every
+retirement carries one.
+
+**Why a SHA and not a `file:line`.** A line number rots at the next edit, and then
+the evidence points at something that has moved or gone; the reader is left with a
+claim and no way to check it. A commit is immutable and carries the diff, the
+message and the parent, so `git show <sha>` reconstructs the entire incident two
+months later — which is exactly when the same class comes back and somebody needs
+to know whether this was already understood.
+
+**Every SHA must resolve.** This is [`learned.md`](learned.md) rule 14 — *a
+document may not send a reader to something absent* — applied to history, and it is
+mechanical: the project's documentation gate runs `git rev-parse --verify --quiet
+<sha>^{commit}` over every backticked SHA in the retro and its archive
+([`gates.md`](gates.md)).
+
+## Rotation — the archive is how pruning stops losing things
+
+At the prune, entries older than the last five run stamps **move** to
+`docs/superpowers/retro/YYYY-QN.md`. Moving is not deleting.
+
+- The archive is **append-only**, and a retirement writes its line **there**, with
+  the trigger that retired it and the commit.
+- A retired rule that comes back as a real failure is a grade-1 fix — **with its
+  history attached**, which is the whole return on having archived it.
+- Nothing is ever removed from the archive to keep it tidy. It is not read in full,
+  so its size costs nothing; its completeness is what it is for.
 
 ## Three grades of fix — take the highest one that can work
 
@@ -60,7 +94,9 @@ rule that could have been a check gets read twice and obeyed once.
 Prune first, then write. A lesson that lands in a cluttered file is a lesson nobody
 will reach.
 
-Check **every** standing instruction against three retirement triggers:
+Every row carries its own trigger in a **`Retire when`** column, written at birth —
+a rule whose retirement condition is decided later is a rule the prune can only
+argue about. Check **every** standing instruction against three triggers:
 
 | Trigger | Test | Then |
 |---|---|---|
@@ -73,10 +109,9 @@ them all — the oldest never-fired one goes. "But all of them matter" is precis
 the state in which the list stopped being read, and the ninth stale rule is what
 discredits the two that are load-bearing.
 
-**Every deletion writes one line in the Log** — id, date, which trigger fired.
-Silent deletion is forbidden: the record is what survives, the instruction is what
-leaves. A retired rule that comes back as a real failure is a grade-1 fix, and now
-you have its history.
+**Every deletion writes one line in the archive** — id, date, which trigger fired,
+and the commit. Silent deletion is forbidden: the record is what survives, the
+instruction is what leaves.
 
 **Print the counts beside the gate verdict**, the same way the carry-over ledger
 does ([`audit.md`](audit.md) → *ratchet, never TODO*):
@@ -93,9 +128,15 @@ A pruned list that nobody prints is a list that quietly grows back.
 The standing instructions are an **instruction source**, not background reading:
 [`knowledge-sources.md`](knowledge-sources.md) reads them in full at the harvest —
 they are short by construction — and records the file as a ledger row. Every
-instruction that actually *fires* during the run gets its **last-fired date
-stamped** as it fires. That stamp is the only thing that makes the cold-rule honest;
-without it "five runs without firing" is a guess, and the prune becomes a mood.
+instruction that actually *fires* during the run gets its **last-fired date and
+commit stamped** as it fires. That stamp is the only thing that makes the cold-rule
+honest; without it "five runs without firing" is a guess, and the prune becomes a
+mood.
+
+**The archive is queried at the same moment**, by the task's own nouns. It is the
+one source that answers *"have we been bitten by this class before?"* — and that
+question is worth asking precisely when the in-force list says nothing, because a
+rule that was retired for going cold is exactly the rule about to be re-learned.
 
 ## Where a lesson goes when it is not about this project
 

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

@@ -51,6 +51,23 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   explicit "none found"; the graph's row carries its build date). It is retrieval
   scoped by the task's own nouns, not a read of everything — and it is what makes
   phase 2's answers checkable instead of merely confident.
+- **Phase 1b — the documentation inventory**
+  ([`documentation.md`](documentation.md)). Four questions, answered before the
+  interview and written to `docs/DOCMAP.md` (seeded from
+  [`../templates/docmap.md`](../templates/docmap.md), **only when absent**): where
+  do settled things live, what is each fact's single home, what does a change of
+  type X oblige, and what proves it. A project with no answers gets them seeded —
+  registers, the matrix and `scripts/check-docs.sh` — and the seeding is itself
+  recorded as the register's first entry. **One decision home per project:** an
+  existing `docs/adr/` *is* the register and is recorded as such, never duplicated.
+  The gate is seeded so that it exits `0` on its own seeds; a project that starts
+  red learns on day one that the gate is noise.
+- **Phase 1c — reconcile intent against as-built.** Git says how it *should* be;
+  the run record says how it *turned out*. Read both for the area you are about to
+  touch and resolve every divergence — the document is stale, the record is wrong,
+  or they genuinely disagree and that is a decision. There is no fourth option, and
+  starting on an unresolved divergence means building against a system that does
+  not exist.
 - **How it runs: [`grill.md`](grill.md)** — the full doctrine, built into this
   skill (nothing to install). In short: one question per turn, a recommended
   answer with each, explore the codebase before asking, depth-first through the
@@ -77,7 +94,11 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   an updated `CONTEXT.md` (terms written as they resolved) and any ADRs under
   `docs/adr/` — see `grill.md` → *Domain awareness*.
 - **GATE (manual):** shared understanding reached — **the source ledger is written
-  (every source consulted, or an explicit "none found")**, every detected branch has
+  (every source consulted, or an explicit "none found")**, **the documentation
+  inventory is answered into `docs/DOCMAP.md`** with its registers, single homes,
+  a non-empty propagation matrix and the gate command, **the regime is recorded**,
+  **intent and as-built are reconciled with every divergence resolved**, the retro's
+  in-force sections are read in full and its archive queried, every detected branch has
   a recorded answer or an explicit deferral, **every answer that contradicted a
   harvested source has a recorded resolution** (which governs, and whether the doc
   is now stale), no open contradictions, **every
@@ -228,7 +249,9 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   same as stage 5.
 - **GATE (auto):** the **full** suite is green (not just the new tests); new/changed code
   is covered; no `skip`/`xfail` smuggling a red suite past the gate. Never advance
-  to deploy on a red or partial run.
+  to deploy on a red or partial run. **The carry-over count is printed beside this
+  verdict** — a ratchet nobody prints is a TODO with a better name
+  ([`audit.md`](audit.md)).
 
 ## 7 — Lint + deploy
 - Read host conventions (`conventions.md`): run the linter; fix failures. The suite
@@ -240,7 +263,8 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
 - **GATE (manual):** lint clean (host linter **and**, for UI projects, the super-ux
   linter) **and** suite green **before** deploy, **and no REQ is still `open`** — a
   `partial` ships only with the operator's explicit acceptance. A gap is cheapest to
-  close before it ships, and the operator is already present at this gate. Deploy is outward → explicit
+  close before it ships, and the operator is already present at this gate. **The
+  carry-over count is printed beside this verdict.** Deploy is outward → explicit
   operator go. Respect deploy-from-main rules if the project mandates them.
 
 ## 8 — Post-deploy
@@ -250,6 +274,18 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   steps — never silent success.
 
 ## 9 — Docs + wiki
+- **The propagation sweep runs first** ([`documentation.md`](documentation.md)).
+  The ledger below names the documents you **read**; the matrix in `docs/DOCMAP.md`
+  names the documents you **owe**. They are not the same list, and the gap between
+  them is where documentation rots — the document nobody read is exactly the
+  document nobody updated. Walk the matrix row for **every** change type this run
+  produced. Every settled thing gets an id in the register, every answered question
+  is flipped to `Resolved→<id>`, and every document named in a
+  `Consequences / affects:` line cites its decision.
+- **Then run the documentation gate** (`bash scripts/check-docs.sh`, or whatever
+  `docs/DOCMAP.md` → *Gates* names) and print its **ratchet counts** beside the
+  verdict, so "green" reads as *"green, and here is exactly what was not looked
+  at"* ([`gates.md`](gates.md)). A check that skipped says so.
 - **The stage-0 source ledger is the work list** ([`knowledge-sources.md`](knowledge-sources.md)
   → *Close the loop*): every source the harvest read gets updated if this run
   changed or disproved it. What was worth reading at stage 0 and is wrong now is
@@ -278,11 +314,17 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
 - **Docs living in another repository** are outward: propose the edit, get an
   explicit go, then open a PR there. No go → the exact edit goes in the carry-over
   ledger.
-- **GATE (auto):** docs in sync with code; every stale row in the source ledger
-  either updated or carried over with its edit; UI: super-ux layers current +
-  linter green; wiki synced (or absent and recommended once); **the code graph
+- **GATE (auto):** **the propagation matrix walked for every change type this run
+  produced**, with every settled thing recorded under an id and every answered
+  question resolved; **the documentation gate green, its ratchet counts printed and
+  any skip stated** — this is what replaced the unfalsifiable *"docs in sync with
+  code"*, which named no artefact and no command; every stale row in the source
+  ledger either updated or carried over with its edit; the **as-built record
+  written and reconciled**; UI: super-ux layers current + linter green; wiki synced
+  (or absent and recommended once); **the code graph
   refreshed where one exists, or the reason it wasn't written into the carry-over
-  ledger** (absent and recommended once is fine); dangling links fixed.
+  ledger** (absent and recommended once is fine); dangling links fixed; **the
+  carry-over count printed beside this verdict**.
 
 ## 10 — Acceptance
 - **What:** the closing stage — go back to the brief and account for **every**
@@ -348,8 +390,12 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   instructions in full next time, which is why the cap is not negotiable.
 - **GATE (manual):** the ladder walk ran and its absences became REQ rows before
   the table was written; **the retrospective is written — prune before entry, the
-  list at or under its cap with every deletion logged, the run stamped, and the
-  counts printed beside this verdict**; **every repository is closed — the parent included:
+  list at or under its cap, every deletion logged **in the archive with its commit**,
+  entries older than five run stamps rotated into `docs/superpowers/retro/`, the run
+  stamped **with its commit**, every SHA in either file resolvable, and the
+  counts printed beside this verdict**; **the documentation gate has been seen
+  failing once against a planted defect and its ratchet counts are printed**
+  ([`gates.md`](gates.md)); **every repository is closed — the parent included:
   `git submodule status` shows no `+`, each repo clean and pushed**; **every check this gate leans on has been seen failing
   once against a planted defect** (an unproven check's green is not evidence);
   every REQ has a status (none `unknown`); every `verified`
@@ -387,6 +433,22 @@ module N → 3 spec (dossier) → 4 plan → 5 build → 6 tests → 7 lint+depl
   cross-module contracts are covered by tests that cross the seam, and a final
   acceptance covers the platform's whole REQ table — not module by module.
 
+## Cross-cutting — the Doc Loop
+
+A decision is not made at stage 9. It is made the moment something is settled —
+in the grill, in the brainstorm's approved design, in the spec's locked contract,
+in a ruling on a review finding at stage 5 — and every one of those is a stage that
+can lose it.
+
+- **It fires at any stage**, and the seven steps live in
+  [`documentation.md`](documentation.md): orient and reconcile → reserve the id and
+  record → resolve the question it answers → propagate by the matrix → adjust scope
+  → record as-built → commit with the ids.
+- **Step 7 is part of the loop, not after it.** A decision recorded and uncommitted
+  is a decision that survives exactly as long as the working tree.
+- **Reserve before you mint.** Reading *"Next free ID"* is not reserving it, and a
+  second agent reading it in the same minute gets the same number.
+
 ## Cross-cutting — the loop guard
 
 Any stage can be re-entered and any loop can churn: a pass undoing what an earlier

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

@@ -13,7 +13,20 @@ from `super-ux`.
 | `carryover.md` | `docs/superpowers/specs/YYYY-MM-DD-<topic>-carryover.md` | 0 seeds, all stages append, 10 reads |
 | `context.md` | `CONTEXT.md` at the repo root (or per context) | 0 — grill, domain awareness |
 | `adr.md` | `docs/adr/NNNN-<slug>.md` | 0 — grill, hard-to-reverse decisions |
-| `retro.md` | `docs/superpowers/retro.md` — **one per project, not per run** | 10 writes (prune → stamp → entry), 0 reads the standing instructions in full |
+| `docmap.md` | `docs/DOCMAP.md` — **one per project** | 0 — the documentation inventory |
+| `decisions.md` | `docs/DECISIONS.md` — the decision register | 0 seeds it, the Doc Loop appends |
+| `open-questions.md` | `docs/OPEN_QUESTIONS.md` | 0 seeds it, the Doc Loop resolves rows |
+| `docgate.sh` | `scripts/check-docs.sh` | 0 seeds it · 9 runs it · 10 proves it |
+| `hooks.example.json` | the project's `.claude/settings.json` | 0 — offered, never installed silently |
+| `retro.md` | `docs/superpowers/retro.md` — **one per project, not per run** | 10 writes (prune → stamp → entry), 0 reads it in full |
+| `retro-archive.md` | `docs/superpowers/retro/YYYY-QN.md` | 10 rotates into it, 0 **queries** it |
+
+The documentation-track templates (`docmap.md`, `decisions.md`,
+`open-questions.md`, `docgate.sh`) are seeded **together**, and they are useful at
+three entries: the register opens with the decision that established it, and the
+gate exits `0` on exactly those seeds. A scaffold that seeds red teaches everyone on
+day one that the gate is noise, so this repo's own validator runs the seeded gate
+over a scratch project on every `npm test` and fails if it is not green.
 
 `context.md` and `adr.md` are **format references**, not files to copy wholesale:
 the grill writes `CONTEXT.md` entries and ADRs in their shape, lazily — only once

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

@@ -18,15 +18,40 @@ increment. Create the directory **lazily** — only when the first ADR is needed
 That's it. An ADR can be a single paragraph. The value is recording *that* a
 decision was made and *why* — not filling out sections.
 
+## When this directory IS the register
+
+An ADR set and `docs/DECISIONS.md` are **two shapes of one decision home**, and a
+project has exactly one ([`../references/documentation.md`](../references/documentation.md)).
+If `docs/adr/` already holds an `NNNN-*.md`, that is the register — record it in
+`docs/DOCMAP.md` and never seed a second home beside it.
+
+In that role an ADR owes the same six things the register does, so these stop being
+optional and become the format:
+
+```md
+# {Short title of the decision}
+
+- **Status:** Accepted            <!-- or: Superseded by ADR-0012 · Reversed ·
+                                       Accepted · **Partially superseded by ADR-0012** — <clause> -->
+- **Consequences / affects:** `docs/SECURITY.md`, `docs/DATA_MODEL.md`
+- **Source:** run `2026-08-03-<topic>` · commit `<sha>`
+- **Supersedes:** ADR-0004        <!-- or Refines: / Contradicts: -->
+
+{1–3 sentences: what the context was, what was decided, and why.}
+```
+
+`Refines:` is additive and needs no annotation on the target; `Contradicts:` and
+`Supersedes:` both **oblige the target's status line to say so**. Never renumber,
+never delete — add a new ADR and edit only the old one's status line.
+
 ## Optional sections
 
 Only when they add genuine value; most ADRs need none.
 
-- **Status** frontmatter (`proposed | accepted | deprecated | superseded by
-  ADR-NNNN`) — useful once decisions start getting revisited.
 - **Considered options** — only when the rejected alternatives are worth
   remembering.
-- **Consequences** — only when non-obvious downstream effects need calling out.
+- **Consequences** (prose) — only when non-obvious downstream effects need calling
+  out beyond the `Consequences / affects:` file list.
 
 ## When to write one
 

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

@@ -23,18 +23,35 @@ premise if the run leaves it wrong.
 | wiki: `projects/…/concepts/…` | … | YYYY-MM | context | **yes — update at stage 9** |
 | `CLAUDE.md` | test/lint/deploy commands, house rules | current | convention | no |
 
-Precedence when two disagree, in one direction: **code first, then host docs and
-ADRs, then the code graph, then the wiki, then memory.** The graph points; the code
-decides. The operator outranks every document — but only **out loud**: an override
-quoted against its source is a recorded decision, an unquoted one is an undetected
-divergence.
+Precedence splits by the question being asked. **For what *is*:** code first, then
+host docs and ADRs, then the code graph, then the wiki, then memory — the graph
+points, the code decides. **For what *should be*:** the decision register outranks
+the code, because a decision accepted and not yet built is still the decision, and
+code that contradicts it is a finding rather than a tie-break. The operator
+outranks every document — but only **out loud**: an override quoted against its
+source is a recorded decision, an unquoted one is an undetected divergence.
+
+## Documentation (the phase-1b inventory — the four questions)
+
+| Question | Answer |
+|---|---|
+| **Regime** | governed — seeded this run / already in place since … |
+| **Decision home** (exactly one) | `docs/DECISIONS.md` (`DEC-####`) / `docs/adr/` (`ADR-NNNN`) — never both |
+| **Open questions** | `docs/OPEN_QUESTIONS.md` (`OQ-####`) |
+| **Doc map** | `docs/DOCMAP.md` — single homes + the propagation matrix (non-empty; every row names its check or the word `review` with a reason) |
+| **Gate** | `bash scripts/check-docs.sh` — seeded / already present; ratchet floors: … |
+| **Shared state** | lease mechanism present / **`ungated`** (say so out loud in the run) |
+| **Intent vs as-built** | reconciled on … ; divergences found: … ; each resolved how |
 
 - **Doc repos / hosted doc systems this project names:** … (or `none`)
 - **Knowledge wiki:** installed / not installed
   ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki); recommended, never a gate)
-- **Retro standing instructions:** `docs/superpowers/retro.md` — none / N in force
-  (read **in full**; list which ones bind this run, and stamp each as it fires —
-  that date is the only evidence behind stage 10's cold-retirement rule)
+- **Retro, in force:** `docs/superpowers/retro.md` — none / N standing instructions
+  (read **in full**, together with the run stamps and the recent-log window; list
+  which ones bind this run, and stamp each as it fires **with the commit** — that
+  stamp is the only evidence behind stage 10's cold-retirement rule)
+- **Retro archive:** `docs/superpowers/retro/` — **queried** by this task's nouns;
+  what it returned: … (or `nothing`)
 - **Code graph:** built / installed-not-built / not installed
   ([graphify](https://github.com/Graphify-Labs/graphify); recommended, never a gate —
   built → its row above carries the build date and stage 9 refreshes it)
@@ -88,6 +105,7 @@ is not neutral — it is a scheduled interruption.
 | run-wide | Model for this run | … (most capable available unless overridden; per-stage overrides here) |
 | run-wide | Decide autonomously vs escalate to me | … |
 | 0 Harvest | Doc sources beyond this repo — other repos, hosted docs, the knowledge wiki, the code graph; and may stage 9 write to them? | … (another repo is outward: propose + PR, never a direct push; graph built / not built) |
+| 0 Docs regime | Where settled things live (register or ADR set — one home, never both); who may write it; lease mechanism present, or is this run `ungated`? Gate command + ratchet floors; may this run raise a floor? | … |
 | 1 Docs | External libs/APIs/SDKs in play; any context7 can't resolve → where their docs live | … |
 | 2 Decompose | Platform (several capabilities/surfaces) or one module? If platform — deploy cadence: per module, or once at the end | … |
 | 2–3 Spec | UI verdict (arms super-ux); scenario-tracing waiver, if any | … |