task-pipeline-skill 1.6.0 → 1.7.0

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

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

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

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

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

@@ -13,6 +13,9 @@ better, plus one that is required only for user-facing work.
 | Stage | Doctrine |
 |---|---|
 | 0 Knowledge harvest (pre-grill) | `references/knowledge-sources.md` |
+| 0 + 9 + any settled decision — the documentation system | `references/documentation.md` |
+| 6–10 + any check you write — gates | `references/gates.md` |
+| any agent-time enforcement — hooks | `references/hooks.md` |
 | 0 + 9 The code graph (the tool is optional; the doctrine ships) | `references/knowledge-graph.md` |
 | 0 Intake grill | `references/grill.md` |
 | 2 Brainstorm | `references/brainstorm.md` |
@@ -35,6 +38,7 @@ better, plus one that is required only for user-facing work.
 | **Figma** (MCP) | stage 3 UX track, when the project designs visually — super-ux mirrors each `SCR-` screen/state into a frame | Optional, **UI + Figma-on only**. Absent → super-ux degrades to text-only *by itself and never blocks*, so shipping a UI feature with no mockups becomes a silent scope call — which is why the stage-0 sweep decides it | connect the Figma MCP server (`/mcp`, or your claude.ai connectors) |
 | **[obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (`wiki-query`, `wiki-update`) | **stage 0 harvest** (query what's already known) **+ stage 9 sync** | **Recommended** — never a gate; absent → harvest runs on repo docs alone | `pip install obsidian-wiki` → `obsidian-wiki setup --vault /path/to/your/vault` |
 | **[graphify](https://github.com/Graphify-Labs/graphify)** (`/graphify`, `graphify query\|affected\|god-nodes`) | **stage 0 harvest** (reach: what calls this, what breaks if it moves) **+ stage 9 refresh + the graph↔docs divergence check** ([`knowledge-graph.md`](knowledge-graph.md)) | **Recommended** — never a gate; absent → the harvest greps instead, and the divergence axis is unavailable | `uv tool install graphifyy` → `graphify install` → `/graphify .` |
+| **[agent-sync](https://github.com/ssheleg/agent-sync)** (`/agent-sync`) | **guarded registers** — a lease before writing one, `reserve` before minting an id, `reconcile`/`record` for intent vs as-built, and `finish` for the stage-10 multi-repository close-out ([`documentation.md`](documentation.md)) | **Recommended** — never a gate. Absent → the run is **`ungated`** and must say so out loud; the discipline still applies, only the arbitration is missing | `npx sshlg-skills install` |
 | ~~superpowers~~ | — | **Not a dependency.** Stages 2/4/5/6 run on the built-in doctrine above. See *Optional bridge* | — |
 | ~~grill-me / grilling~~ | — | **Not a dependency.** The stage-0 grill is built in (`references/grill.md`) | — |
 
@@ -76,6 +80,12 @@ Pipeline companions (stage doctrine is built in — nothing to install for it):
                            pip install obsidian-wiki
                            obsidian-wiki setup --vault /path/to/your/vault
                          (running without it — the harvest uses repo docs only)
+  ✗ agent-sync         — recommended: guarded registers, id reservation before
+                         minting, intent-vs-as-built reconcile, and the stage-10
+                         multi-repository close-out:
+                           npx sshlg-skills install
+                         (running without it — the doc track still applies, the
+                          run is recorded `ungated`, and that is said out loud)
   ✗ graphify           — recommended: stage 0 asks it what reaches what,
                          stage 9 refreshes it beside the docs and the wiki:
                            uv tool install graphifyy
@@ -114,6 +124,11 @@ Rules:
   the MCP and then *continues text-only on its own*, so without a recorded answer
   the run silently narrows from "designed" to "described". The sweep row is
   `3 Design surface` ([`grill.md`](grill.md) → *The autonomy sweep*).
+- **agent-sync**: detect via a resolving `/agent-sync` or a `.claude/agent-sync.json`
+  in the project. Present → take a lease before writing a guarded register and
+  reserve ids before minting them. Absent → print the line **once**, continue, and
+  **record the run as `ungated`** — never describe the project as protected
+  ([`documentation.md`](documentation.md) → *Registers are shared state*).
 - **Never gate any stage on an install** except the stage-3 UX track on a UI task.
 - Optional tools missing → state the fallback, don't block.
 - Re-detect after the operator installs; don't assume.

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

@@ -60,6 +60,25 @@ found, surface it and **ask** rather than guessing.
   project names): updating it is **outward** — propose the change, get an explicit
   operator go, open a PR there. Never push to a repo the task didn't name.
 
+## Documentation regime (stage 0, then 9 and 10)
+
+The host's `CLAUDE.md`/`AGENTS.md` wins over anything detected — read it first.
+Then detect, in this order ([`documentation.md`](documentation.md)):
+
+| Look for | Means |
+|---|---|
+| `docs/DOCMAP.md` | the inventory has been done; read it, extend it, do not re-seed |
+| `docs/adr/` with at least one `NNNN-*.md` | **that is the register.** Record it in the doc map; never seed a second decision home beside it |
+| `docs/DECISIONS.md` | the register shape; note its id scheme and its "Next free ID" line |
+| a decisions/ADR section inside `AGENTS.md` or `CONTRIBUTING.md` | the rules live there; the doc map holds a **pointer**, not a copy |
+| a `check-docs`, `lint:docs`, `docs` target in `package.json`/`Makefile`/CI | the documentation gate already exists — use it, and read its scope header |
+| none of the above | **seed the set**: `docmap.md`, `decisions.md`, `open-questions.md` and `docgate.sh` from [`../templates/`](../templates/README.md), and record the seeding as the register's first entry |
+
+Two rules that are not negotiable when seeding: the gate must exit `0` on the seeds
+themselves, and the registers must be useful at three entries. A project whose gate
+is red on day one has learned that the gate is noise, and nothing later un-teaches
+that.
+
 ## Issue tracker (stage 10)
 
 Acceptance parks what wasn't delivered: every `deferred` REQ and every unresolved

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

@@ -0,0 +1,285 @@
+# Documentation — the system, not the by-product
+
+**One job: make documentation a deliverable with an address, an obligation and a
+gate.** Not "write docs at the end" — a *system*: every settled thing has an id,
+every fact has one home, every kind of change names the documents it owes, and a
+script can say no.
+
+This file is the **what and why**. [`gates.md`](gates.md) is how the script that
+enforces it gets written; [`stages.md`](stages.md) says where each piece binds.
+
+**Governance is a by-product here, never a separate step.** The run already
+produces decisions — the brief's *Decisions locked*, the spec's locked contracts,
+the ADRs the grill writes. Recording one is **transcription plus a stable id**, not
+new thinking. Anything below that feels like ceremony is a sign the register is
+being written twice; write it once, here.
+
+---
+
+## The inventory — four questions, answered before the first line of work
+
+Stage 0 answers these before the interview, and writes the answers to
+`docs/DOCMAP.md` (seeded from [`../templates/docmap.md`](../templates/docmap.md),
+**only when absent** — never overwritten):
+
+1. **Where do settled things live?** The decision home, and its id scheme.
+2. **What is each fact's single home?** One place per fact; everything else links.
+3. **What does a change of type X oblige?** The propagation matrix.
+4. **What proves it?** The gate command, and what it does *not* cover.
+
+A project with no answers gets them seeded. The seeding is itself recorded as the
+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.
+
+---
+
+## Registers and ids
+
+**One decision home per project. The doc map names it. Never create a second.**
+
+Two shapes satisfy the contract; the difference is physical, not semantic:
+
+| Shape | Home | Id | Use when |
+|---|---|---|---|
+| **Register** | `docs/DECISIONS.md`, append-only | `DEC-####` | default; many small decisions, read as a list |
+| **ADR set** | `docs/adr/NNNN-<slug>.md` | `ADR-NNNN` | the project already has `docs/adr/`; decisions are long and each wants a page |
+
+**Detect, don't assume:** `docs/adr/` holds at least one `NNNN-*.md` → that is the
+register, record it in the doc map and use it. Otherwise seed
+[`../templates/decisions.md`](../templates/decisions.md). An existing ADR set is
+**never migrated** as a side effect of some other task — migrating is its own
+decision, with its own entry.
+
+Both shapes owe the same six things: a **stable id**, an **append-only** history, a
+**status line** with the supersede semantics below, a **`Consequences / affects:`**
+line, a **`Source:`** line carrying the run and the **commit**, and the **edge
+markers**.
+
+Open questions get their own register (`docs/OPEN_QUESTIONS.md`, `OQ-####`) with a
+closed status vocabulary: `Open` · `Resolved→DEC-####` · `Dropped (<why>)`.
+
+**Two rules that look like formatting and are not:**
+
+- **Reference facts by id, never by copying the text.** A copy is a second source
+  that nobody will update, and the reader cannot tell which one is current.
+- **Ids are never renumbered and resolved questions are never deleted.** The
+  question is the history of the answer; without it the next reader re-litigates a
+  settled thing from scratch.
+
+---
+
+## Single source of truth
+
+**Every fact has exactly one home. Everything else links to it.**
+
+If the same fact is stated in two places, that is a **bug** — collapse it to one
+home and link from the other. Not because duplication is untidy: because the two
+copies will disagree, and at that moment both become unusable, since nobody can
+tell which one moved.
+
+- The *decision* lives in the register. Topic docs describe the *current design*
+  and cite the id.
+- Each topic (architecture, data model, security, …) has one canonical document.
+- Indexes and summaries **link**; they never restate a rule.
+
+### Across repositories
+
+**The owning repository decides; a consumer repository describes.** Where a
+consumer document disagrees with the owner, the consumer is wrong — stated rather
+than adjudicated case by case, because case-by-case is how a consumer repo starts
+legislating.
+
+The boundary is worth writing out, because an unqualified "the owner always wins"
+is false in one direction: **build state and task status belong to the repository
+doing the work**. A submodule is cloned alone, and a status update must not require
+two repositories.
+
+Changing a consumer repo's documentation: compare against the owner's canonical
+doc → look for a contradiction with it *and* with any accepted decision → if the
+consumer document is wrong, fix it in place; if the **owner** is wrong or stale, it
+is corrected there, by a decision entry, through a pull request — and the consumer
+document stays divergent and marked until that lands. Quietly aligning a consumer
+doc to its own view is the failure this paragraph exists to prevent.
+
+---
+
+## The Doc Loop
+
+**Fires whenever something is settled — at any stage.** Scope, a contract, a name,
+a policy, a status vocabulary, a price, a retention window. Not only at stage 9.
+
+1. **Orient and reconcile.** Read the register and the topic doc. Run the
+   intent/as-built reconcile (below). Do not contradict an accepted decision
+   without superseding it. *Skipping this is how a run spends a day building
+   against a system that does not exist.*
+2. **Reserve the id, then record.** Reading "Next free ID" is **not** reserving it
+   (see *Registers are shared state*). Then write the entry: date, status, context,
+   decision, consequences, source with the commit.
+3. **Resolve.** Flip every answered question to `Resolved→<id>`. Never delete it.
+4. **Propagate.** Walk the matrix row for this change type and update every
+   document it names, **in the same change**. Keep SSOT: the detail in one home,
+   links from the rest.
+5. **Adjust scope.** Roadmap, MVP, module map — if scope moved.
+6. **Record as-built.** What was actually built, with the ids and the files. Then
+   reconcile again.
+7. **Commit.** One focused commit, conventional message, **the ids in the subject**.
+
+**Finishing the chat answer is not finishing the task.** Closing the loop is. A
+decision that lives only in a spec dies with that spec; one that lives only in the
+conversation was never made.
+
+---
+
+## Changing your mind
+
+The register is **append-only**. To reverse or replace:
+
+- add a **new** entry stating the new decision and naming what it replaces;
+- edit **only the status line** of the old entry;
+- leave the old body intact as history.
+
+**A partial supersede annotates both sides.** Most reversals are partial — a later
+decision replaces one clause and leaves the rest standing. If the old entry keeps a
+bare `Accepted`, a reader who opens only that entry gets an answer that is no longer
+true. So the new entry names which clause it replaces, and the old entry's status
+line gains `· **Partially superseded by <id>** — <one line>`.
+
+**Three markers, and they mean different things:**
+
+| Marker | Meaning | Target's status line annotated? |
+|---|---|---|
+| `Refines:` | **additive only** — every clause of the target still holds | no |
+| `Contradicts:` | a **named clause** of the target no longer holds | **yes** |
+| `Supersedes:` | the whole target is retired | **yes** |
+
+One word for "adds to" and "replaces a clause of" is unenforceable. Measured on the
+project this practice comes from: across **275** refine/supersede edges, **204**
+pointed at a target with no annotation — which is not 204 violations, because most
+were additive. *That ambiguity is the defect*: neither a reader nor a script could
+tell which of the 204 should have been annotated, so the rule could not be gated at
+all.
+
+**Existing edges are not retro-classified.** Each needs a judgement about what its
+author meant, and a bulk pass would guess. An edge is reclassified when someone
+touches it for another reason.
+
+---
+
+## The propagation matrix
+
+The harvest ledger ([`knowledge-sources.md`](knowledge-sources.md)) names the
+documents you **read**. The matrix 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.
+
+**Build it in five steps** (stage 0; extend it whenever a new doc class appears):
+
+1. List the project's doc classes — one line each: what is this the home of?
+2. For each **change type** the project can undergo, name every document that must
+   move.
+3. For each row, name the **check** that would notice if it did not — or write
+   `review` *with a one-line reason why no check can decide it*.
+4. Write the rows into `docs/DOCMAP.md` → *Propagation matrix*.
+5. Arm the mechanical half in the gate: **a document named in an entry's
+   `Consequences / affects:` line must cite that entry.**
+
+A row with an empty third column is a **finding**, not a blank. Either a check
+exists, or somebody has said out loud that none can.
+
+**The backlog is ratcheted, and that is the design.** Turning this check on in an
+existing repository finds a lot: **162** missing propagations across **73**
+decisions, on the project this comes from — not the four the audit had reported.
+Failing on all of them makes the gate something people switch off, and bulk-fixing
+them blind adds 162 citations nobody verified. So: entries from a **floor** id
+onward fail; everything older is a counted backlog that may only shrink, printed on
+every run. Raising the floor is a decision, and it belongs in the register.
+
+---
+
+## Navigation
+
+**One definition per entity, and a mention links to the definition.**
+
+- Every definition carries an explicit anchor.
+- A mention links to the **anchor**, not the file. A file link makes the reader
+  search; a deep link that rots is caught by the gate.
+- **Indexes never restate a rule.** They fall behind and then they lie with
+  authority — a navigation aid that omits an entry is worse than none, because a
+  reader concludes the entry does not exist.
+
+A deep link is worth more than a file link *and* fails harder, so it only pays with
+a check behind it. Land the anchor check with the first rewritten link, not after
+the sweep.
+
+---
+
+## Intent and as-built
+
+Two records, deliberately not merged:
+
+| Record | Says | Written by |
+|---|---|---|
+| **Intent** — the registers, the spec, the plan | how it *should* be | the Doc Loop |
+| **As-built** — the run record | how it *turned out* | step 6, at the end |
+
+**Reconcile both before starting and after finishing.** Every divergence has one of
+three resolutions: the document is stale, the record is wrong, or they genuinely
+disagree and that is a decision to make. There is no fourth, and "I'll keep it in
+mind" is not one of them.
+
+Where a coordination tool is installed it does this for you. Where it is not, the
+as-built record is a section of the carry-over ledger and the reconcile is a read
+of it — **the tool is optional, the discipline is not**.
+
+---
+
+## Registers are shared state
+
+A register is the one file two agents will write in the same minute.
+
+- **Reserve the id before minting it.** "Next free ID" is a *reading*; a second
+  agent reading it in the same minute gets the same answer, and now two entries
+  carry one number.
+- **Take a lease before writing a guarded register**, where a lease mechanism
+  exists. [`hooks.md`](hooks.md) is how such a guard blocks the edit;
+  [`companion-skills.md`](companion-skills.md) names the optional companion that
+  implements one.
+- **Ask what two instances with the same identity would do**, and make the tool
+  answer it. This is [`learned.md`](learned.md) rule 15, and it is in that table
+  because it cost an entire day of work performed under another session's identity.
+- **When nothing can arbitrate, the run is `ungated` — say so out loud.** That is
+  a real state, not a formality. Describing a project as protected while nothing
+  enforces it is worse than having no protection, because everyone downstream
+  believes the guarantee.
+
+---
+
+## Where this binds in the pipeline
+
+| Point | What happens | Gate |
+|---|---|---|
+| **Stage 0**, phase 1b | the inventory — the four questions, into `docs/DOCMAP.md`; the regime recorded | manual |
+| **Stage 0**, phase 1c | intent vs as-built reconciled; every divergence resolved | manual |
+| **Any stage** | something is settled → the Doc Loop, all seven steps | the stage's own |
+| **Stage 9** | the propagation sweep, the registers, the gate green with its ratchets printed | auto |
+| **Stage 10** | the gate itself proven — every check seen failing once against a planted defect | manual |
+
+---
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "It's a small project, a register is overkill" | A register with three entries costs three minutes and is the only reason the fourth decision can be found. What people mean by overhead is *ceremony*, and none is required here — the entries are transcribed from artefacts the run already produced. |
+| "I'll write the decision up at the end" | At the end you remember the outcome and not the alternatives you rejected, which is the only part with any value later. |
+| "The spec already says it" | A spec is per-run and the next one supersedes it. A decision outlives every artefact that mentions it. |
+| "I updated the docs I touched" | The matrix names the documents you did **not** touch. That is the entire reason it exists. |
+| "Two docs saying the same thing is harmless" | Until they disagree — and then both are unusable, because nobody can tell which one moved. |
+| "I'll just fix the old decision's text" | Then the reason someone chose it is gone and the next person re-litigates it from scratch. Supersede; never edit the body. |
+| "It's obviously additive, no need to mark it" | 204 of 275 edges were left unmarked on exactly that reasoning, and afterwards nobody could tell which of them should have been. The marker costs one word. |
+| "Nobody else is working in this repo right now" | You cannot know that from inside your session, and being wrong means two entries with one id. |
+| "The gate is green, so the docs are fine" | The gate proves what it checks. Read its scope header before quoting it as evidence. |
+| "The doc is stale but that's not this task" | Then it is a row in the carry-over ledger with the exact edit, right now. A staleness noticed and unrecorded is the next run's false premise. |

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

@@ -0,0 +1,236 @@
+# Gates — the two axes, and how to build one that cannot lie
+
+**One job: turn a rule into something that can say no.** [`audit.md`](audit.md)
+says a class seen twice *belongs in a script*; this file is where that script comes
+from — how it is written, where it runs, how it is armed, how it is proven, and
+what you must know **before** you quote its green as evidence.
+
+**Boundary, so this file does not become a second source.** The *law* lives
+elsewhere and is not restated here:
+
+| The law | Lives in | This file adds |
+|---|---|---|
+| A check must be watched failing before it is trusted | [`audit.md`](audit.md) *Exit criterion*, [`learned.md`](learned.md) 4–5 | the executable recipe |
+| Ratchet, never TODO | [`audit.md`](audit.md) §3, [`learned.md`](learned.md) 7 | floor variables, and where the count is printed |
+| A gate's exit code is part of its output | [`learned.md`](learned.md) 11 | where the verdict block goes |
+| A checker with false positives is worse than none | [`learned.md`](learned.md) 10 | how to measure before shipping |
+| A generator seeds green | [`learned.md`](learned.md) 9 | progressive arming |
+| A class that repeats twice becomes a gate | [`audit.md`](audit.md) §1 | the six-step recipe |
+
+---
+
+## Axis A — the stage gate type
+
+From [`../pipeline.schema.json`](../pipeline.schema.json), one per stage:
+
+| Type | Meaning | Failure to respect it |
+|---|---|---|
+| `auto` | the orchestrator verifies the `check` itself, pass/fail, and stops on fail | advancing on an unverified check |
+| `manual` | wait for the operator's **explicit** go | treating an auto verification as the approval |
+
+**An auto gate never substitutes for a required manual approval.** A green table is
+not the operator confirming it is what they asked for, and no amount of checking
+makes it one. Which stages are manual is the **operator's** decision, recorded in
+their `pipeline.json`; the framework fixes no stage count and no gate assignment.
+
+## Axis B — the enforcement mechanism
+
+Where a rule actually lives. A rule climbs this ladder; it does not start at the top.
+
+| Rung | Mechanism | Costs | Promote when |
+|---|---|---|---|
+| 1 | **Doctrine line** in a reference file | reading attention | it was violated once |
+| 2 | **Review question** at a named gate | a person's time, every run | no check can decide it — and say *why*, in one line |
+| 3 | **Script check** in the project's gate | writing it once | the class has occurred **twice** |
+| 4 | **CI step** | minutes per push | it must hold for people who never run it locally |
+| 5 | **Hook** ([`hooks.md`](hooks.md)) | latency on every tool call | the failure is cheaper to prevent than to detect, and the target is an edit an agent is making now |
+
+A rule may sit on several rungs. What it may never do is **pretend** to be on a
+higher one: a doctrine line that reads as if it were enforced is the same failure as
+a gate that prints `FAIL` and exits `0` — both report a world they are not looking
+at.
+
+**Rung 2 is where honesty is bought.** "No check can decide this" is a legitimate,
+common answer. Written down with its reason, it is a finding somebody can later
+disprove. Left unwritten, it is indistinguishable from an omission.
+
+---
+
+## Before you run a check
+
+Four preconditions. Skipping any of them turns a run into a claim.
+
+1. **The base is green** — or its known-red baseline is *recorded*. A new guard
+   added to an already-red base passes for the wrong reason and proves nothing.
+2. **The check has been probed.** Green from a check nobody has watched fail is
+   worth nothing. If you did not plant the defect, you do not know what the green
+   means.
+3. **You have read its scope header** and know what it does **not** cover. A gate
+   is evidence for exactly the surface it walks; quoting it beyond that is how
+   "the gate is green" becomes a false statement made in good faith.
+4. **You have read the ratchet floors.** A pass with a floor that was quietly
+   raised is a pass over the thing the floor was hiding.
+
+---
+
+## Anatomy of a project gate
+
+Ten properties. Each one is here because its absence has shipped.
+
+| Property | Rule | The failure it prevents |
+|---|---|---|
+| **Exit code** | non-zero on **any** failure | a gate that appended a check *after* its verdict block printed `FAIL` and returned `0`; CI was green over it for an unknown period |
+| **Verdict last** | nothing may run after the verdict block | the same failure, from the other end |
+| **Scope header** | states what the gate does **not** cover | a green quoted as proof of a surface nobody walked |
+| **Portability** | POSIX + bash 3.2: no `grep -P`, no `sed -i`, no `readarray` | BSD `sed -i` needs an argument GNU refuses, and `0,/re/` does not exist there — it silently edits nothing and the check reads as a guard that failed to fire |
+| **Ratchet floors** | `<NAME>_FLOOR` variables at the top; counts printed beside `OK` | a backlog that grows back without anyone explaining why |
+| **Skips are printed** | a check that could not run says so | a submodule not checked out silently removing coverage |
+| **Progressive arming** | a section with no input artefact prints `dormant: … — no <artefact> yet` and does **not** fail | a freshly seeded project starting red, which teaches everyone on day one that the gate is noise |
+| **Computed, never restated** | derive every count at check time | two documents quoting a total that went stale |
+| **Both directions** | any two-layer mapping is checked each way | four fully-specified entities with no schema anywhere — found only by the direction that felt redundant |
+| **Named location** | every error prints file **and** line | a finding nobody can act on |
+
+Shape:
+
+```bash
+#!/usr/bin/env bash
+# check-docs.sh — the documentation gate for <project>.
+# SCOPE: walks <what>. Does NOT check <what>.
+# Portable to macOS bash 3.2: no grep -P, no sed -i, no readarray.
+set -u
+FAIL=0
+PROP_FLOOR=${PROP_FLOOR:-1}          # ratchet: raising it is a decision
+
+# ---------- 1. <name> ----------
+...                                   # ok: / ERR: / skip: / dormant:
+
+# ---------- VERDICT — nothing runs after this block ----------
+if [ "$FAIL" -ne 0 ]; then echo "FAIL: <gate>"; exit 1; fi
+echo "OK: <gate> — backlog: $BACKLOG (floor $PROP_FLOOR) · registers: $DECS decisions · $OQS open"
+exit 0
+```
+
+---
+
+## Writing the check itself
+
+- **Pick the unit and say what it costs.** A check that scopes to a table *row*
+  will let one marker in that row exempt everything else in it. That is a real
+  blind spot; measured and accepted beats unmeasured and denied, so write it in the
+  comment.
+- **Prefer a deterministic rule to a heuristic.** A parity-based check for
+  unbalanced markup produced six false positives out of six on a real corpus and
+  was discarded. If the rule cannot be stated exactly, that is information.
+- **Never infer from strings the environment also produces.** Matching `"claude"`
+  in a process command line matched the throwaway shell of every tool call.
+- **Compute the count you print.** A number restated in prose is a number that will
+  be wrong; derive it from the source at check time so the two cannot disagree.
+
+---
+
+## Probing — plant, run, restore
+
+The law is [`audit.md`](audit.md)'s exit criterion. The procedure is this, and it is
+not optional for a check you intend to trust:
+
+```bash
+cp -R . /tmp/probe && cd /tmp/probe
+python3 - <<'PY'                       # plant IN PYTHON, never sed -i
+p = "docs/DECISIONS.md"
+s = open(p).read().replace("DEC-0001", "DEC-9999", 1)
+open(p, "w").write(s)
+PY
+bash scripts/check-docs.sh; echo "planted -> exit=$?"   # MUST be non-zero
+cd - && bash scripts/check-docs.sh; echo "clean -> exit=$?"  # MUST be 0
+```
+
+**Assert on `$?`, not on a `FAIL` line in the output.** A line on stdout is a
+decoration; the exit code is what CI reads.
+
+**Doubt the probe before you doubt the check.** On the project this comes from,
+**four of five** silent probes were the probe's fault: one added a *definition*
+where the check looks for an unresolved *reference*; one edited a string whose
+whitespace did not match; one hit the first prose mention instead of the table row;
+one flipped a row whose cell was already empty, so nothing was planted. A silent
+check is a claim about two things, and the probe is the one to doubt first — prove
+your edit landed in the text the check actually parses.
+
+**Record the probe.** One line per section, in the change that ships the check.
+Otherwise the next reader has to redo it to know whether it was ever done.
+
+---
+
+## The false-positive budget
+
+Run a new heuristic over the **real corpus** before shipping it and count the false
+positives. Zero, or replace the heuristic with a deterministic rule.
+
+The budget is not perfectionism. A gate that cries wolf is switched off by the
+third person who hits it, and after that it protects nothing while still appearing
+in the pipeline as a control. A noisy check is worse than no check, because it also
+consumes the credibility of the checks beside it.
+
+---
+
+## Ratchets
+
+A **ratchet** is a named, counted set that may only shrink, printed on every run.
+
+- Its floor is a **variable at the top of the script**, so raising it is a visible
+  edit and a decision.
+- Its count is printed **beside the verdict**, so `PASS` never reads as *verified*
+  — it reads as *"green, and here is exactly what was not looked at"*.
+- A ratchet that grew needs a sentence in the run log saying why.
+
+```
+GATE 9 docs: PASS — propagation backlog: 121 (was 162) · unmarked residue: 0
+```
+
+A ratchet nobody prints is a TODO with a better name.
+
+---
+
+## Where a gate runs
+
+| Place | Good at | Limit |
+|---|---|---|
+| **Local pre-commit** | fast feedback for the author | skippable, and skipped exactly when someone is in a hurry |
+| **CI** | authoritative; holds for people who never run it locally | minutes late, and it checks out the repo in a shape the author's machine never has — rehearse that shape |
+| **Hook** ([`hooks.md`](hooks.md)) | stops the edit *before* it happens | Claude Code only; a crashing hook **fails open** |
+| **Stage gate** (this pipeline) | judgement, and the things only a person can answer | it is the run's own memory, not the repository's |
+
+The four are not alternatives. The same rule can be a hook for the agent, a
+pre-commit for the human and a CI step for the record — what it must never be is
+*declared* in one place and *enforced* in none.
+
+---
+
+## Adding a check to an existing gate
+
+1. **Name the class** — the shape, not the instance. "This id is undefined" is an
+   instance; "an id referenced and never defined" is a class.
+2. **Find the unit** the check will parse: a line, a table row, a paragraph, a
+   file. Write down what that unit will miss.
+3. **Write the predicate deterministically**, with the file and line in the error.
+4. **Measure it** over the real corpus; zero false positives or rewrite it.
+5. **Plant, run, restore** — both directions observed, and recorded.
+6. **Wire its count into the verdict line**, with a floor if it cannot be zero yet.
+
+Step 6 is the one that gets skipped, and it is the one that makes the check
+survive: a number beside `OK` is read every run, and a check nobody sees the output
+of is deleted in the next refactor by someone who assumed it was dead.
+
+---
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "The check is green, that's evidence" | Only if you have seen it red. An unproven check is a decoration that reports success. |
+| "It printed FAIL, so it failed" | CI reads `$?`. A gate has shipped that printed `FAIL` and exited `0`, and nobody noticed for an unknown number of runs. |
+| "I'll write the check later, the rule is documented" | Then it is on rung 1 and behaves like rung 3 in everyone's head. That gap is the whole failure. |
+| "It's one occurrence, a note is enough" | It is. On the second, the note becomes a script — that is the rule, and the third occurrence is proof it was ignored. |
+| "The heuristic mostly works" | Measure it. Six false positives out of six on a real corpus is what "mostly" felt like from inside. |
+| "The gate would be red on day one, so I'll add it later" | Make the section dormant instead. Dormant is visible and green; "later" is neither. |
+| "I raised the floor to get the build green" | Then say so in the log, in the same commit. A floor raised silently is a ratchet running backwards. |
+| "A hook is overkill, CI catches it" | CI catches it after the edit, the commit and the push. If the point is to stop the edit, CI is the wrong rung — and if it is not, do not pay the latency. |