task-pipeline-skill 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## v1.7.2 — 2026-08-03
+
+### Fixed — nine findings from a post-release investigation of v1.7.1
+
+The release was audited against the skill's own ladder, bottom-up, findings ordered
+by seam. Every one below was proven before it was fixed and again after.
+
+**The gate enforced one of the two register shapes it promises.** `documentation.md`
+permits two decision homes — `docs/DECISIONS.md` or `docs/adr/` — and says they owe
+the same six things; `docgate.sh` parsed only the first. Measured on a real ADR
+project: **eight of ten sections went `dormant`**, dormant is green by design, and a
+planted propagation violation was not caught. The gate now builds a **normalised
+entry index** from whichever home exists, so no section knows which shape it is
+reading, and holding both at once is itself an error. Seven planted defects on the
+ADR shape, all firing.
+
+Two of those probes exposed bugs in the checks rather than in the fixtures — the
+fixture is derived from `templates/adr.md`'s own fenced example, so it cannot drift
+from the documented format. HTML comments were not stripped, so a status line
+carrying `<!-- or: Superseded by ADR-0012 -->` made an entry read as retired *and*
+invented an undefined id; and the first fix dropped the line that **opened** the
+comment, throwing away the `Status:` before it. Duplicate ADR numbers were counted
+from the entry index, whose one-row-per-id dedupe swallowed exactly the second file
+this check exists to find — it counts filenames now, because the filename is the
+allocator.
+
+**Exit 0 was not proof that the gate had looked.** Every section can go `dormant`,
+so a gate blind to a shape passes identically to one that reads it. The validator
+now asserts the seeded run **reports which shape it found** and **ran at least N
+live checks** — the difference between "it did not fail" and "it looked".
+
+**The Doc Loop was declared cross-cutting and appeared in no stage doctrine.**
+`brainstorm.md`, `spec.md`, `build.md`, `review.md` and `acceptance.md` had zero
+mentions of it — so the flow as an agent *executes* it never ran the loop, because
+an agent opens the stage file, not the orchestrator's summary. All five now say
+where a settled decision goes, and it is a guard.
+
+Most of that gap was at stage 5, which settles more decisions than any other stage
+and runs in an isolated worktree with parallel implementers. The rule is now
+explicit and argued from the same physics as the existing parallel-fan-out rule:
+**a subagent never writes the register** — append-only shared state cannot be
+hand-merged across worktrees, and an id cannot be *reserved* from a branch that
+cannot see the other writers. Decisions ride the implementer report and the ledger;
+the orchestrator runs the loop after integration, as a single writer.
+
+**`hooks.md` stated an external contract from memory.** Re-fetched from the Claude
+Code hooks reference and corrected: `permissionDecision` has **four** values, not
+one; there are **35** events, not the four listed; `effort`, `agent_id` and
+`agent_type` were missing from the stdin fields; `if` is evaluated on five tool
+events and its Bash matching is best-effort. The reference also says outright that
+**exit 1 is non-blocking "even though 1 is the conventional Unix failure code"** —
+which is the sharpest possible argument for the `|| exit 2` this file already
+required. Provenance and fetch date are now in the file, because stage 1 of this
+pipeline exists for exactly this.
+
+**Smaller, and all real:** a "we don't document" escape hatch in `documentation.md`
+contradicted the seeding rule four lines above it and the stage-0 gate; the stage-9
+config gate carried both the retired criterion *"docs in sync with code"* and the
+sentence declaring it retired; a lost edit meant the grill never asked the
+documentation-regime question the brief had a field for — and the sweep-drift guard
+missed it because it compared **stage numbers**, which both files still matched, so
+it now compares topics per stage (measured: zero false positives, including the
+legitimate case where the brief splits one grill row into two); `acceptance.md`
+never mentioned the documentation gate it is supposed to prove; and nested bold in
+the stage-10 gate criterion inverted the emphasis of everything after "every
+deletion logged".
+
+Three new guards, each with a negative self-test watched failing.
+**46 of 46 guards provably reject their planted defect.**
+
+## v1.7.1 — 2026-08-03
+
+### Fixed — the tag-ancestry gate had been failing on every release since v1.6.1
+
+The step that exists so *"a release does not live only on a tag"* — added after the
+v1.4.4 incident — **failed on every tag from v1.6.1 onward**, and nobody saw it,
+because `release` ran green beside it and the failing log showed only the echoed
+script with no output of its own.
+
+`git fetch --tags` without `--force` aborts with *"would clobber existing tag"* when
+the checkout has already created `refs/tags/<tag>` locally and the tag is
+**annotated**. `set -eu` then killed the step before its first `echo` — which is why
+the log was blank and read as though the ancestry check itself had found something.
+v1.6.1 was the first tag cut with `git tag -a`; every one since inherited it.
+
+Two changes, and the second matters more than the first:
+
+- `--force` on the tag fetch, with a printed note if it still degrades.
+- **The step now says which failure it is.** If `refs/remotes/origin/main` cannot be
+  resolved, every tag looks like an orphan and the old wording reported a
+  catastrophe that was really a missing ref. It now fails with that sentence
+  instead, and on success prints the tag count and the `main` it checked against.
+
+This is the shape the repo's own doctrine names: a gate whose exit code nobody reads
+is a gate that has stopped guarding — `references/gates.md` → *A gate's exit code is
+part of its output*, and `references/learned.md` rule 11. It was found by watching
+the release this release shipped, which is the only reason it was found at all.
+
 ## v1.7.0 — 2026-08-03
 
 ### Added — documentation is a deliverable, and it has a gate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"

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

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

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

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

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

@@ -87,6 +87,12 @@ Run: <branch/commit range> · Date: YYYY-MM-DD
 | `deferred` | agreed not to do it now | the operator's agreement **and** a tracker entry |
 | `dropped` | agreed it isn't wanted | the operator's agreement + the reason |
 
+**A `dropped` is a scope decision, and it outlives this run.** The operator's
+agreement closes the row here; the **Doc Loop**
+([`documentation.md`](documentation.md)) is what stops the same requirement being
+re-proposed next quarter by someone who never saw this table. A `deferred` needs its
+tracker entry, not an entry in the register — it is a schedule, not a decision.
+
 Those four are the only ways a requirement may close. Anything that fits none of
 them is `unknown`, and **`unknown` fails the gate** — that is the whole mechanism:
 the run cannot end while a requirement is still unclassified.
@@ -187,8 +193,13 @@ All of:
    bottom-up, findings ordered by seam, absences turned into REQ rows **before**
    the table was written, and the two pass counts recorded.
 2. **Every check this gate leans on has been seen failing** at least once against a
-   planted defect (`audit.md` → *Exit criterion*). An unproven check's green is not
-   evidence.
+   planted defect (`audit.md` → *Exit criterion*; the procedure, with the commands,
+   is [`gates.md`](gates.md) → *Probing*). An unproven check's green is not
+   evidence. That includes **the documentation gate** the project's doc map names
+   ([`documentation.md`](documentation.md)) — stage 9 ran it, this stage is where it
+   is *proven*, and its **ratchet counts are printed beside this verdict**. A
+   documentation gate is the easiest one in a run to inherit unproven, because it
+   was green the first time anyone looked at it.
 3. **Every REQ has a status** — none `unknown`, none blank.
 4. **Every `verified` carries evidence** of the kind above.
 5. **Every `partial` names what's missing** and where it's tracked.

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

@@ -88,6 +88,18 @@ it arms the stage-3 UX track ([`spec.md`](spec.md) → *UX track*). When it's
 genuinely borderline, record "yes": a false positive costs one extra chain, a false
 negative ships an unspecified interface.
 
+## The approved design is a set of decisions — record them
+
+An approved approach is a decision, and so is each alternative rejected for a reason
+worth remembering. Run the **Doc Loop** ([`documentation.md`](documentation.md)) on
+the ones that will outlive this run: the shape chosen, the boundary drawn, the option
+deliberately not taken. Not every preference — the ones a future reader would
+otherwise re-litigate from scratch, which is the same test an ADR applies.
+
+The cost of skipping it is specific: a design approved in conversation and recorded
+only in the spec dies with that spec, and the next run re-opens a question the
+operator already answered.
+
 ## GATE (manual)
 
 The operator approves the design **and** the UI verdict is recorded **and every REQ

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

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

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

@@ -31,8 +31,12 @@ A project with no answers gets them seeded. The seeding is itself recorded as th
 first entry in the register, which is the cheapest possible demonstration that the
 register works.
 
-**A project that answers "we don't document" has still answered.** Write that down,
-with the date, and the next agent stops re-deciding it every run.
+**There is no "we don't document" answer.** The four questions have answers in every
+repository — the smallest one still decides *somewhere* that a thing is true — and
+the only choice is whether that answer is written down or re-derived by each new
+reader. What scales down is **volume**, never the rules: a register with three
+entries is a register, and the seeded gate is green on exactly those three
+([`gates.md`](gates.md) → *progressive arming*).
 
 ---
 

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

@@ -131,6 +131,7 @@ explicit "stop and ask me here":
 |---|---|
 | run-wide | the model decision ([`model-tiering.md`](model-tiering.md)); what to decide autonomously vs escalate |
 | 0 Harvest | doc sources beyond this repo — other repos, hosted doc systems, the knowledge wiki, **the code graph** ([`knowledge-graph.md`](knowledge-graph.md): built / installed-not-built / absent) — and whether stage 9 may write to them (another repo is outward: propose + PR, never a direct push) |
+| 0 Docs regime | where settled things live (the decision home — **one** per project, and an existing `docs/adr/` **is** it), who may write it, whether a lease mechanism is present or the run is `ungated`, the gate command and its ratchet floors, and whether this run may raise a floor ([`documentation.md`](documentation.md)) |
 | 1 Docs | external libs/APIs/SDKs in play; any private ones context7 can't resolve → where their docs live |
 | 2 Decompose | is this a platform (several capabilities/surfaces) or one module? if platform: deploy cadence — per module or once at the end |
 | 2–3 Spec | UI verdict (arms super-ux); any scenario-tracing waiver |

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

@@ -16,13 +16,29 @@ 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.
 
+> **Provenance.** Every contract below is quoted from the Claude Code hooks
+> reference (`code.claude.com/docs/en/hooks`), fetched **2026-08-03**. Re-fetch
+> before relying on it: this is an external API, and stage 1 of this very pipeline
+> exists because a contract recalled from memory is a contract that has already
+> moved. Where the reference and this file disagree, the reference wins and this
+> file is the bug.
+
 ## The events
 
+There are **35** hook events. These are the ones this pipeline reaches for; the
+reference has the rest, grouped as session lifecycle, per-turn, tool execution,
+subagents and tasks, file and config changes, compaction, worktrees, display, and
+MCP elicitation.
+
 | 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 |
+| `PreToolUse` | before a tool call | **block** — the event that can refuse |
+| `PostToolUse` | after a tool call | bookkeeping: renew a lease, stamp a marker |
+| `Stop` | the turn ends | a last-word check — the run's own gate, not the repo's |
+| `SubagentStart` · `SubagentStop` | a subagent starts or finishes | stage 5 runs implementers as subagents; this is where a per-agent identity or ledger line belongs |
+| `WorktreeCreate` · `WorktreeRemove` | a worktree appears or goes | stage 5 isolates in worktrees; a guard that must not fire inside one can key off these |
+| `PreCompact` · `PostCompact` | context is compacted | flush anything that only lives in context — the ledger exists because this happens |
 | `SessionEnd` | session closes | release leases, flush the journal |
 
 ## The `PreToolUse` contract
@@ -38,22 +54,44 @@ A hook blocks a call in **either** of two ways:
  "permissionDecisionReason":"docs gate failed: 2 undefined ids in docs/ARCHITECTURE.md"}}
 ```
 
+`permissionDecision` takes **four** values, not one: `allow` (permit it), `deny`
+(block it), `ask` (escalate to the user), `defer` (fall through to the normal
+permission flow). Exit 0 with empty stdout means `defer` by omission. A hook may
+also rewrite the call instead of judging it, by returning `updatedInput` in the
+same block — which is a different power from blocking and worth knowing before you
+reach for it.
+
 **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.
+shown in the transcript. The reference is explicit that **exit 1 is treated as
+non-blocking, "even though 1 is the conventional Unix failure code"** — so the
+single most likely way to write a guard, `command || exit 1`, is the one that does
+not guard. And on exit 2 Claude Code **ignores stdout and any JSON in it**; only
+stderr is read back.
+
+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`.
+JSON on stdin. Common to every event: `session_id`, `transcript_path`, `cwd`,
+`permission_mode` (`default` · `plan` · `acceptEdits` · `auto` · `dontAsk` ·
+`bypassPermissions`), `effort` (an object with `level`), `hook_event_name`, and —
+inside a subagent — `agent_id` and `agent_type`. `prompt_id` is present from a
+recent version onward, so treat it as optional unless you pin one.
 
-`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.
+Tool events add `tool_name`, `tool_input` and `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
+([`learned.md`](learned.md) rule 15: a heuristic over strings the environment also
+produces matched the throwaway shell of every tool call).
+
+`agent_id` matters more here than it looks: stage 5 runs implementers as subagents
+in worktrees, and a guard that must behave differently for the orchestrator and for
+an implementer has exactly one honest way to tell them apart.
 
 ## Where it lives
 
@@ -77,6 +115,17 @@ machine, and the first surprising denial is debugged in the wrong project.
 - for a specific shell command, add `"if": "Bash(git commit *)"` beside
   `"matcher": "Bash"`.
 
+`if` uses **permission-rule syntax** (`Bash(git *)`, `Edit(*.ts)`) and is evaluated
+**only on tool events** — `PreToolUse`, `PostToolUse`, `PostToolUseFailure`,
+`PermissionRequest`, `PermissionDenied`. Anywhere else it is inert, which is a
+silent way to write a guard that never fires.
+
+**For Bash the match is best-effort — the reference's own word.** It inspects
+subcommands, `$()` expansions and backticks, and strips leading `FOO=bar`
+assignments before matching. So `if` is a good **filter** and a bad **boundary**:
+narrow with it to keep the hook cheap, then re-check the real target inside the
+script before refusing anything.
+
 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.
 

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

@@ -182,6 +182,19 @@ A checklist you run yourself, inline. No subagent:
    `depends:` points at a task that really produces what's consumed.
 6. **DoD present and verifiable** on every task.
 
+## This stage settles nothing — and that is a rule, not an omission
+
+Planning **translates** decisions; it does not make them. So unlike stages 2, 3, 5
+and 10 there is no Doc Loop trigger here ([`documentation.md`](documentation.md)),
+and the reason is worth stating, because an unstated exclusion is indistinguishable
+from a gap.
+
+The consequence is the working rule: **if writing the plan forces a choice, the
+choice belongs to a lower layer.** A contract that turns out underspecified goes
+back to stage 3 and is recorded there; a scope question goes back to the operator.
+A decision first made while sequencing tasks is a decision nothing downstream will
+ever find, because nobody reads a plan after the build.
+
 ## GATE (auto)
 
 **Set equality first:** the REQ ids in the brief equal the union of `Implements:`

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

@@ -167,6 +167,13 @@ finding either.
 > which can stand and why. Findings only, with severity and a concrete failure
 > scenario each. Return the findings as your final message.
 
+**A ruling that parks a finding is a decision.** *"This stands, and here is why"* is
+exactly the sentence a future reader will hit in the code and re-litigate, so a
+ruling that outlives the run goes through the **Doc Loop**
+([`documentation.md`](documentation.md)) — via the report and the ledger, written by
+the orchestrator after integration, never by a subagent
+([`build.md`](build.md) → *§4.1a*).
+
 Run the final review on the **run's confirmed model** like everything else
 ([`model-tiering.md`](model-tiering.md)). It is the one review that sees the whole
 change, so if the run is on a tier below the most capable one available, say so and

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

@@ -134,6 +134,18 @@ Read what you wrote with fresh eyes and fix inline. No subagent, no second pass:
 5. **Ambiguity:** can any requirement be read two ways? Pick one and say it.
 6. **Traceability (UI):** does every user-facing requirement name its scenario ID?
 
+## Locked contracts are decisions — the register, not only the spec
+
+This stage settles more than any other: a schema, a signature, a status vocabulary,
+an error shape. Each has a life longer than the document it is written into, so run
+the **Doc Loop** ([`documentation.md`](documentation.md)) for the ones that bind
+future work — record the entry, propagate by the matrix, and cite the id from the
+spec section instead of restating the reasoning there.
+
+**A spec states a contract; the register makes it addressable.** A spec is per-run
+and the next one supersedes it; an id survives. If this stage settled something and
+no entry names it, the run has agreed to decide it again later.
+
 ## GATE (manual)
 
 > "Spec written and committed to `<path>`. Review it and tell me if anything should

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

@@ -382,7 +382,8 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   notices it is the same one. So, in this order: **prune first** (every standing
   instruction against its three retirement triggers — it became a check, its
   surface is gone, it hasn't fired in five run stamps — and the list held to its cap
-  of ten, every deletion logged), **stamp the run**, then **write an entry only if
+  of ten, every deletion logged **in the archive, with the commit that retired it**),
+  **stamp the run**, then **write an entry only if
   the run diverged** (symptom · the stage it surfaced at · the stage that *owned* it
   · root cause · fix, mechanical before instruction before expiring note · the check
   that catches it next time). Every run prunes and stamps; a retro left empty after
@@ -390,9 +391,9 @@ 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, every deletion logged **in the archive with its commit**,
+  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
+  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:

package/plugins/task-pipeline/skills/task-pipeline/templates/docgate.sh

@@ -18,12 +18,20 @@
 # PROGRESSIVE ARMING: a section whose input does not exist yet prints
 #   "dormant: … — no <artefact> yet" and does NOT fail. Dormant is visible so it is
 #   not forgotten, and green so a freshly seeded project does not start red.
+#
+# TWO REGISTER SHAPES, ONE CONTRACT: the project's decision home is either
+#   docs/DECISIONS.md (ids DEC-####) or docs/adr/NNNN-slug.md (ids ADR-NNNN). Every
+#   section below reads a NORMALISED INDEX built from whichever exists, so neither
+#   shape is a second-class citizen. Having both is itself an error: one home per
+#   project. Reading only one shape is how a fully populated ADR register sat behind
+#   eight green "dormant" lines while a planted violation went uncaught.
 
 set -u
 
 FAIL=0
 DOCS_DIR=${DOCS_DIR:-docs}
 DEC_FILE=${DEC_FILE:-$DOCS_DIR/DECISIONS.md}
+ADR_DIR=${ADR_DIR:-$DOCS_DIR/adr}
 OQ_FILE=${OQ_FILE:-$DOCS_DIR/OPEN_QUESTIONS.md}
 MAP_FILE=${MAP_FILE:-$DOCS_DIR/DOCMAP.md}
 RETRO_GLOB=${RETRO_GLOB:-$DOCS_DIR/superpowers}
@@ -40,12 +48,31 @@ ok()      { echo "ok:      $*"; }
 skipmsg() { echo "skip:    $*"; }
 dormant() { echo "dormant: $*"; }
 
-# Strip fenced code blocks: sample content is not a claim about this repository.
+# Strip what a reader never sees: fenced code blocks AND html comments. Sample
+# content is not a claim about this repository. The comment half is not fussiness —
+# a status line carrying `<!-- or: Superseded by ADR-0012 -->` made an entry read as
+# retired and invented an undefined id, from one aside nobody renders.
 # awk, because sed -i is not portable and this must run identically everywhere.
-strip_fences() {
+strip_asides() {
   awk '
     /^[ \t]*(```|~~~)/ { infence = !infence; print ""; next }
-    { if (infence) print ""; else print }
+    infence { print ""; next }
+    {
+      line = $0
+      # A comment carried over from an earlier line.
+      if (incomment) {
+        if (match(line, /-->/)) { line = substr(line, RSTART + RLENGTH); incomment = 0 }
+        else { print ""; next }
+      }
+      # Comments that open and close on this line.
+      while (match(line, /<!--.*-->/)) sub(/<!--.*-->/, "", line)
+      # An opener with no closer: KEEP THE PREFIX. Dropping the whole line threw
+      # away the "- **Status:** Accepted" that preceded the comment, and the entry
+      # then had no status at all — the id vanished from the index and every
+      # document citing it was reported as citing something undefined.
+      if (match(line, /<!--/)) { line = substr(line, 1, RSTART - 1); incomment = 1 }
+      print line
+    }
   ' "$1"
 }
 
@@ -63,17 +90,82 @@ fi
 while IFS= read -r f; do
   [ -f "$f" ] || continue
   flat=$(echo "$f" | tr '/' '_')
-  strip_fences "$f" > "$TMP/s_$flat"
+  strip_asides "$f" > "$TMP/s_$flat"
 done < "$TMP/files"
 
 flat_of() { echo "$TMP/s_$(echo "$1" | tr '/' '_')"; }
 
+# ---------- 0. the decision home — exactly one, and which shape ----------
+# entries: ID <TAB> FILE <TAB> STATUS-LINE      edges: SRC <TAB> MARKER <TAB> TARGET
+# conseq:  ID <TAB> DOC
+: > "$TMP/entries"; : > "$TMP/edges"; : > "$TMP/conseq"
+SHAPE="none"; ID_PREFIX=""
+
+have_reg=0; [ -f "$DEC_FILE" ] && have_reg=1
+have_adr=0
+if [ -d "$ADR_DIR" ]; then
+  find "$ADR_DIR" -type f -name '[0-9][0-9][0-9][0-9]-*.md' 2>/dev/null | sort > "$TMP/adrfiles"
+  [ -s "$TMP/adrfiles" ] && have_adr=1
+fi
+
+if [ "$have_reg" = "1" ] && [ "$have_adr" = "1" ]; then
+  err "two decision homes: $DEC_FILE and $ADR_DIR both hold entries — one project, one register (references/documentation.md)"
+fi
+
+# Pull the six owed fields out of one entry body on stdin, for id $1 in file $2.
+harvest_entry() {  # id file  (body on stdin)
+  _id=$1; _file=$2
+  while IFS= read -r line; do
+    case "$line" in
+      *'Status:'*)
+        grep -q "^$_id	" "$TMP/entries" 2>/dev/null || \
+          printf '%s\t%s\t%s\n' "$_id" "$_file" "$line" >> "$TMP/entries" ;;
+      *'Consequences / affects:'*)
+        echo "$line" | grep -o '`[^`]*`' | tr -d '`' | while IFS= read -r doc; do
+          case "$doc" in *.md) printf '%s\t%s\n' "$_id" "$doc" >> "$TMP/conseq" ;; esac
+        done ;;
+      *'Supersedes:'*|*'Contradicts:'*|*'Refines:'*)
+        _mk=$(echo "$line" | grep -o 'Supersedes\|Contradicts\|Refines' | head -1)
+        echo "$line" | grep -o '\(DEC\|ADR\)-[0-9][0-9]*' | while IFS= read -r tgt; do
+          [ "$tgt" = "$_id" ] || printf '%s\t%s\t%s\n' "$_id" "$_mk" "$tgt" >> "$TMP/edges"
+        done ;;
+    esac
+  done
+}
+
+if [ "$have_reg" = "1" ]; then
+  SHAPE="register"; ID_PREFIX="DEC"
+  # Split the fence-stripped register into one body per "### DEC-####" heading.
+  awk -v out="$TMP" '
+    /^### DEC-[0-9]+/ { id=$2; sub(/[^A-Za-z0-9-].*/,"",id); n++; f=out "/e_" n; ids[n]=id }
+    n { print > f }
+    END { for (i=1;i<=n;i++) print ids[i] > (out "/e_ids") }
+  ' "$(flat_of "$DEC_FILE")"
+  if [ -f "$TMP/e_ids" ]; then
+    _n=0
+    while IFS= read -r _id; do
+      _n=$((_n + 1))
+      harvest_entry "$_id" "$DEC_FILE" < "$TMP/e_$_n"
+    done < "$TMP/e_ids"
+  fi
+elif [ "$have_adr" = "1" ]; then
+  SHAPE="adr"; ID_PREFIX="ADR"
+  while IFS= read -r af; do
+    _num=$(basename "$af" | sed 's/^\([0-9][0-9]*\)-.*/\1/')
+    harvest_entry "ADR-$_num" "$af" < "$(flat_of "$af")"
+  done < "$TMP/adrfiles"
+fi
+
+DECS=$(wc -l < "$TMP/entries" | tr -d ' ')
+case "$SHAPE" in
+  none) dormant "decision home — neither $DEC_FILE nor $ADR_DIR/NNNN-*.md yet" ;;
+  *)    ok "decision home: $SHAPE ($DECS entr$([ "$DECS" = "1" ] && echo y || echo ies), ids $ID_PREFIX-####)" ;;
+esac
+
 # ---------- 1. relative links resolve ----------
-_bad=0
 while IFS= read -r f; do
   [ -f "$f" ] || continue
   dir=$(dirname "$f")
-  # grep -o on the link target; keep the line number for the message.
   grep -n -o '](\([^) ]*\))' "$(flat_of "$f")" 2>/dev/null |
   sed 's/](\(.*\))/\1/' |
   while IFS=: read -r ln target; do
@@ -82,28 +174,22 @@ while IFS= read -r f; do
     esac
     base=${target%%#*}
     [ -n "$base" ] || continue
-    if [ ! -e "$dir/$base" ]; then
-      echo "$f:$ln: dangling link -> $target" >> "$TMP/badlinks"
-    fi
+    [ -e "$dir/$base" ] || echo "$f:$ln: dangling link -> $target" >> "$TMP/badlinks"
   done
 done < "$TMP/files"
 if [ -s "$TMP/badlinks" ] 2>/dev/null; then
-  _bad=$(wc -l < "$TMP/badlinks" | tr -d ' ')
-  err "$_bad dangling relative link(s):"; sed 's/^/         /' "$TMP/badlinks"
+  err "$(wc -l < "$TMP/badlinks" | tr -d ' ') dangling relative link(s):"
+  sed 's/^/         /' "$TMP/badlinks"
 else
   ok "relative links resolve ($FILE_COUNT files)"
 fi
 
 # ---------- 2. every id referenced is defined ----------
-if [ ! -f "$DEC_FILE" ]; then
-  dormant "id integrity — no $DEC_FILE yet"
-  DECS=0; OQS=0
+if [ "$SHAPE" = "none" ]; then
+  dormant "id integrity — no decision home yet"
+  OQS=0
 else
-  # Read the FENCE-STRIPPED copy: a heading inside a ``` block is sample content,
-  # not a definition. Reading the raw file here counts the format example as an
-  # entry, and then "Next free ID" is wrong against a decision that never existed.
-  grep -o '^### DEC-[0-9][0-9]*' "$(flat_of "$DEC_FILE")" | sed 's/^### //' | sort -u > "$TMP/dec_def"
-  DECS=$(wc -l < "$TMP/dec_def" | tr -d ' ')
+  cut -f1 "$TMP/entries" | sort -u > "$TMP/dec_def"
   : > "$TMP/oq_def"
   [ -f "$OQ_FILE" ] && grep -o '^| *OQ-[0-9][0-9]*' "$(flat_of "$OQ_FILE")" | sed 's/^| *//' | sort -u > "$TMP/oq_def"
   OQS=$(wc -l < "$TMP/oq_def" | tr -d ' ')
@@ -113,7 +199,7 @@ else
   while IFS= read -r f; do
     [ -f "$f" ] || continue
     grep -v 'Next free ID' "$(flat_of "$f")" 2>/dev/null |
-      grep -o '\(DEC\|OQ\)-[0-9][0-9]*' | sed "s|^|$f |" >> "$TMP/refs"
+      grep -o "\($ID_PREFIX\|OQ\)-[0-9][0-9]*" | sed "s|^|$f |" >> "$TMP/refs"
   done < "$TMP/files"
 
   : > "$TMP/undef"
@@ -127,7 +213,10 @@ else
   fi
 fi
 
-# ---------- 3. "Next free ID" == max defined + 1 ----------
+# ---------- 3. the id allocator is sound ----------
+# Register shape: a stated "Next free ID" must equal max defined + 1.
+# ADR shape: there is no such line — the filename IS the allocator, so the sound
+# check is that no two files claim one number.
 check_next_free() {
   _file=$1; _prefix=$2; _deffile=$3
   [ -f "$_file" ] || { dormant "next-free-$_prefix — no $_file yet"; return; }
@@ -141,27 +230,46 @@ check_next_free() {
   # an octal digit, the expansion errors, the `if` takes its else branch and the
   # check prints ok. It passed for every id ending 0-7 and was silent for 8 and 9.
   # Found by the probe; the check was wrong, not the probe.
+  _claim_raw=$_claim
   _claim=$(echo "$_claim" | sed 's/^0*//'); [ -n "$_claim" ] || _claim=0
   if [ ! -s "$_deffile" ]; then _max=0; else
     _max=$(sed "s/^$_prefix-//" "$_deffile" | sed 's/^0*//' | sort -n | tail -1)
     [ -n "${_max:-}" ] || _max=0
   fi
   _want=$((_max + 1))
-  if [ "$((_claim))" -ne "$_want" ]; then
+  if [ "$_claim" -ne "$_want" ]; then
     err "$_file: 'Next free ID' claims $_prefix-$_claim, highest defined is $_max (expected $_want)"
   else
-    ok "next free $_prefix id is correct ($_prefix-$_claim)"
+    ok "next free $_prefix id is correct ($_prefix-$_claim_raw)"
   fi
 }
-check_next_free "$DEC_FILE" DEC "$TMP/dec_def"
-check_next_free "$OQ_FILE"  OQ  "$TMP/oq_def"
+case "$SHAPE" in
+  register) check_next_free "$DEC_FILE" DEC "$TMP/dec_def" ;;
+  adr)
+    # Count from the FILENAMES, not from the entry index. The index keeps one row
+    # per id on purpose (an entry has one status line), and that dedupe silently
+    # swallowed the very thing this check looks for: a second file claiming a
+    # number already taken. The filename is the allocator, so the filename is what
+    # gets counted. The check was wrong, not the probe.
+    _dupes=$(sed 's|.*/||; s|^\([0-9][0-9]*\)-.*|\1|' "$TMP/adrfiles" | sort | uniq -d | tr '\n' ' ')
+    _adr_n=$(wc -l < "$TMP/adrfiles" | tr -d ' ')
+    if [ -n "$(echo "$_dupes" | tr -d ' ')" ]; then
+      err "duplicate ADR number(s) — two files claim one id: $_dupes"
+    else
+      ok "ADR numbers are unique ($_adr_n files)"
+    fi ;;
+  *) dormant "id allocator — no decision home yet" ;;
+esac
+check_next_free "$OQ_FILE" OQ "$TMP/oq_def"
 
 # ---------- 4. a stated register size equals the computed one ----------
 # Compute, never restate: a number written in prose is a number that goes stale.
-if [ -f "$DEC_FILE" ] && grep -q 'Register size:' "$DEC_FILE" 2>/dev/null; then
-  _stated=$(grep -o 'Register size:\** *\**[0-9][0-9]*' "$DEC_FILE" | head -1 | grep -o '[0-9][0-9]*')
+_size_src=""
+[ "$SHAPE" = "register" ] && _size_src=$DEC_FILE
+if [ -n "$_size_src" ] && grep -q 'Register size:' "$_size_src" 2>/dev/null; then
+  _stated=$(grep -o 'Register size:\** *\**[0-9][0-9]*' "$_size_src" | head -1 | grep -o '[0-9][0-9]*')
   if [ "${_stated:-x}" != "$DECS" ]; then
-    err "$DEC_FILE: states 'Register size: $_stated', computed $DECS"
+    err "$_size_src: states 'Register size: $_stated', computed $DECS"
   else
     ok "stated register size matches the computed one ($DECS)"
   fi
@@ -173,35 +281,27 @@ fi
 # A document named in an entry's "Consequences / affects:" line must cite that
 # entry. Writing down where a decision must propagate and then not propagating is
 # the exact failure the loop exists to prevent.
-if [ ! -f "$DEC_FILE" ]; then
-  dormant "propagation — no $DEC_FILE yet"
-  PROP_MISSING=0
+PROP_MISSING=0
+if [ "$SHAPE" = "none" ]; then
+  dormant "propagation — no decision home yet"
 else
   : > "$TMP/prop"
-  _cur=""
-  while IFS= read -r line; do
-    case "$line" in
-      '### DEC-'*) _cur=$(echo "$line" | grep -o 'DEC-[0-9][0-9]*') ;;
-      *'Consequences / affects:'*)
-        [ -n "$_cur" ] || continue
-        echo "$line" | grep -o '`[^`]*`' | tr -d '`' | while IFS= read -r doc; do
-          case "$doc" in *.md) ;; *) continue ;; esac
-          [ -f "$doc" ] || { echo "$_cur $doc MISSINGFILE" >> "$TMP/prop"; continue; }
-          if grep -q "$_cur" "$doc"; then :; else echo "$_cur $doc NOCITE" >> "$TMP/prop"; fi
-        done ;;
-    esac
-  done < "$(flat_of "$DEC_FILE")"
-  PROP_MISSING=0
+  while IFS="$(printf '\t')" read -r id doc; do
+    [ -n "${doc:-}" ] || continue
+    if [ ! -f "$doc" ]; then echo "$id -> $doc (MISSINGFILE)" >> "$TMP/prop"
+    elif grep -q "$id" "$doc"; then :
+    else echo "$id -> $doc (NOCITE)" >> "$TMP/prop"; fi
+  done < "$TMP/conseq"
   [ -f "$TMP/prop" ] && PROP_MISSING=$(wc -l < "$TMP/prop" | tr -d ' ')
   : > "$TMP/prop_new"
   if [ "$PROP_MISSING" -gt 0 ]; then
-    while read -r id doc why; do
-      _n=$(echo "$id" | sed 's/^DEC-//' | sed 's/^0*//'); [ -n "$_n" ] || _n=0
-      [ "$_n" -ge "$PROP_FLOOR" ] && echo "$id -> $doc ($why)" >> "$TMP/prop_new"
+    while IFS= read -r row; do
+      _n=$(echo "$row" | grep -o '[0-9][0-9]*' | head -1 | sed 's/^0*//'); [ -n "$_n" ] || _n=0
+      [ "$_n" -ge "$PROP_FLOOR" ] && echo "$row" >> "$TMP/prop_new"
     done < "$TMP/prop"
   fi
   if [ -s "$TMP/prop_new" ] 2>/dev/null; then
-    err "decision(s) naming a document that does not cite them (floor DEC-$PROP_FLOOR):"
+    err "entr(y|ies) naming a document that does not cite them (floor $ID_PREFIX-$PROP_FLOOR):"
     sed 's/^/         /' "$TMP/prop_new"
   else
     ok "consequences propagate (backlog below the floor: $PROP_MISSING)"
@@ -211,30 +311,23 @@ fi
 # ---------- 6. supersede / contradict annotates the target ----------
 # One word for "adds to" and "replaces a clause of" is unenforceable, so the
 # markers are distinct and only two of them oblige the target to say so.
-if [ ! -f "$DEC_FILE" ]; then
-  dormant "supersede annotations — no $DEC_FILE yet"
+if [ "$SHAPE" = "none" ]; then
+  dormant "supersede annotations — no decision home yet"
 else
   : > "$TMP/ann"
-  _cur=""
-  while IFS= read -r line; do
-    case "$line" in
-      '### DEC-'*) _cur=$(echo "$line" | grep -o 'DEC-[0-9][0-9]*') ;;
-      *'Supersedes:'*|*'Contradicts:'*)
-        [ -n "$_cur" ] || continue
-        echo "$line" | grep -o 'DEC-[0-9][0-9]*' | while IFS= read -r target; do
-          [ "$target" = "$_cur" ] && continue
-          _status=$(awk -v t="### $target " '
-            index($0, t) == 1 { found = 1; next }
-            found && /^### DEC-/ { exit }
-            found && /Status:/ { print; exit }
-          ' "$(flat_of "$DEC_FILE")")
-          case "$_status" in
-            *"$_cur"*) ;;
-            *) echo "$target: status line does not record that $_cur retires or contradicts it" >> "$TMP/ann" ;;
-          esac
-        done ;;
-    esac
-  done < "$(flat_of "$DEC_FILE")"
+  while IFS="$(printf '\t')" read -r src marker target; do
+    [ -n "${target:-}" ] || continue
+    [ "$marker" = "Refines" ] && continue          # additive: no annotation owed
+    _status=$(grep "^$target	" "$TMP/entries" | head -1 | cut -f3)
+    if [ -z "$_status" ]; then
+      echo "$src $marker $target: target is not a defined entry" >> "$TMP/ann"
+    else
+      case "$_status" in
+        *"$src"*) ;;
+        *) echo "$target: status line does not record that $src ${marker}s it" >> "$TMP/ann" ;;
+      esac
+    fi
+  done < "$TMP/edges"
   if [ -s "$TMP/ann" ] 2>/dev/null; then
     err "unannotated supersede/contradict target(s):"; sed 's/^/         /' "$TMP/ann"
   else
@@ -247,29 +340,22 @@ fi
 # is a line: one marker on it exempts every id on it. That is a real blind spot,
 # measured and accepted — a tighter window produced mostly noise, and a gate that
 # is mostly noise is a gate people switch off.
-if [ ! -f "$DEC_FILE" ]; then
-  dormant "retired residue — no $DEC_FILE yet"
-  RESIDUE=0
+RESIDUE=0
+if [ "$SHAPE" = "none" ]; then
+  dormant "retired residue — no decision home yet"
 else
   : > "$TMP/retired"
-  _cur=""
-  while IFS= read -r line; do
-    case "$line" in
-      '### DEC-'*) _cur=$(echo "$line" | grep -o 'DEC-[0-9][0-9]*') ;;
-      *'Status:'*)
-        [ -n "$_cur" ] || continue
-        case "$line" in
-          *Superseded\ by*|*Reversed*) echo "$_cur" >> "$TMP/retired" ;;
-        esac
-        _cur="" ;;
+  while IFS="$(printf '\t')" read -r id file status; do
+    case "$status" in
+      *Superseded\ by*|*Reversed*) echo "$id" >> "$TMP/retired" ;;
     esac
-  done < "$(flat_of "$DEC_FILE")"
-  RESIDUE=0
+  done < "$TMP/entries"
   if [ -s "$TMP/retired" ] 2>/dev/null; then
     : > "$TMP/res"
     while IFS= read -r f; do
       [ -f "$f" ] || continue
       [ "$f" = "$DEC_FILE" ] && continue
+      case "$f" in "$ADR_DIR"/*) continue ;; esac
       while IFS= read -r rid; do
         grep -n "$rid" "$(flat_of "$f")" 2>/dev/null | while IFS=: read -r ln text; do
           case "$text" in
@@ -294,28 +380,28 @@ fi
 # ---------- 8. status vocabularies are closed ----------
 # An unrecognised status is worse than a missing one: it looks answered, and every
 # check on that row skips in silence.
-if [ -f "$DEC_FILE" ]; then
+if [ "$SHAPE" = "none" ]; then
+  dormant "decision status vocabulary — no decision home yet"
+else
   : > "$TMP/vocab"
-  grep -n 'Status:' "$(flat_of "$DEC_FILE")" 2>/dev/null | while IFS= read -r hit; do
-    case "$hit" in
-      *Accepted*|*Superseded\ by*|*Reversed*|*'`Status`'*) ;;
-      *) echo "$DEC_FILE:${hit%%:*}: unknown decision status -> ${hit#*Status:}" >> "$TMP/vocab" ;;
+  while IFS="$(printf '\t')" read -r id file status; do
+    case "$status" in
+      *Accepted*|*Superseded\ by*|*Reversed*) ;;
+      *) echo "$file: $id has an unknown status ->${status#*Status:}" >> "$TMP/vocab" ;;
     esac
-  done
+  done < "$TMP/entries"
   if [ -s "$TMP/vocab" ] 2>/dev/null; then
     err "decision status vocabulary:"; sed 's/^/         /' "$TMP/vocab"
   else
     ok "decision statuses are inside the closed vocabulary"
   fi
-else
-  dormant "decision status vocabulary — no $DEC_FILE yet"
 fi
 
 if [ -f "$OQ_FILE" ]; then
   : > "$TMP/oqvocab"
   grep -n '^| *OQ-[0-9]' "$(flat_of "$OQ_FILE")" 2>/dev/null | while IFS= read -r row; do
     case "$row" in
-      *'| Open '*|*'| Open|'*|*Open\ \|*|*Resolved→DEC-*|*Dropped*) ;;
+      *'| Open '*|*'| Open|'*|*Open\ \|*|*Resolved→*|*Dropped*) ;;
       *) echo "$OQ_FILE:${row%%:*}: unknown question status" >> "$TMP/oqvocab" ;;
     esac
   done
@@ -362,19 +448,28 @@ else
   # Forward direction is scoped to the "## Registers" table: that table is a CLAIM
   # about what exists. The SSOT table below it legitimately names documents a young
   # project has not written yet, and failing on those would make the gate seed red.
+  # TABLE ROWS ONLY. Reading every backtick in the section swept up the prose note
+  # under the table ("an existing docs/adr/ IS the register") and reported it as a
+  # missing file — a claim the note never made. A row is a claim; a sentence is not.
   : > "$TMP/map"
-  awk '/^## Registers/ { on = 1; next } on && /^## / { exit } on { print }' \
-    "$(flat_of "$MAP_FILE")" | grep -o '`[^`]*\.md`' | tr -d '`' | sort -u > "$TMP/map"
+  awk '/^## Registers/ { on = 1; next } on && /^## / { exit } on && /^\|/ { print }' \
+    "$(flat_of "$MAP_FILE")" | grep -o '`[^`]*`' | tr -d '`' | sort -u > "$TMP/map"
   : > "$TMP/mapmiss"
   while IFS= read -r doc; do
     case "$doc" in *'<'*|*'>'*) continue ;; esac
-    [ -e "$doc" ] || echo "$MAP_FILE names $doc, which does not exist" >> "$TMP/mapmiss"
+    case "$doc" in *.md|*/) ;; *) continue ;; esac
+    [ -e "$doc" ] || [ -e "${doc%/}" ] ||
+      echo "$MAP_FILE names $doc, which does not exist" >> "$TMP/mapmiss"
   done < "$TMP/map"
   for reg in "$DEC_FILE" "$OQ_FILE"; do
     [ -f "$reg" ] || continue
     grep -q "$(basename "$reg")" "$TMP/map" ||
       echo "$reg exists but $MAP_FILE never names it" >> "$TMP/mapmiss"
   done
+  if [ "$SHAPE" = "adr" ]; then
+    grep -q "adr" "$TMP/map" ||
+      echo "$ADR_DIR is this project's decision home but $MAP_FILE never names it" >> "$TMP/mapmiss"
+  fi
   if [ -s "$TMP/mapmiss" ] 2>/dev/null; then
     err "doc map / register disagreement:"; sed 's/^/         /' "$TMP/mapmiss"
   else
@@ -387,5 +482,5 @@ if [ "$FAIL" -ne 0 ]; then
   echo "FAIL: documentation gate"
   exit 1
 fi
-echo "OK: documentation gate — ${DECS:-0} decisions · ${OQS:-0} open questions · propagation backlog ${PROP_MISSING:-0} (floor $PROP_FLOOR) · retired residue ${RESIDUE:-0} (floor $RESIDUE_FLOOR)"
+echo "OK: documentation gate — shape $SHAPE · ${DECS:-0} decisions · ${OQS:-0} open questions · propagation backlog ${PROP_MISSING:-0} (floor $PROP_FLOOR) · retired residue ${RESIDUE:-0} (floor $RESIDUE_FLOOR)"
 exit 0