task-pipeline-skill 1.85.2 → 1.86.1

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

@@ -0,0 +1,645 @@
+# Gates — the three axes, and how to build one that cannot lie
+
+**One job: turn a rule into something that can say no.** [`audit.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/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`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/audit.md) *Exit criterion*, [`learned.md`](learned.md) 4–5 | the executable recipe |
+| Ratchet, never TODO | [`audit.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/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`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/audit.md) §1 | the six-step recipe |
+
+---
+
+## Contents
+
+- Axis A — the stage gate type
+- The judgment gate — a ruling is not a measurement
+- Axis B — the enforcement mechanism
+- Axis C — degrees of freedom
+- Progressive arming
+- Before you run a check
+- False success — when a mechanism reports a win it never checked
+- Anatomy of a project gate
+- Writing the check itself
+- A ratchet prices the rule, not the exception
+- Run the whole suite locally before you push the tag
+- A ratchet's matcher is itself a check, and it needs a near-miss
+- The false-positive budget
+- Ratchets
+- The result is the goal; the check is how you know
+- Disclosures — counted like a ratchet, and deliberately not monotone
+- Where a gate runs
+- Adding a check to an existing gate
+- Rationalizations
+- Cross-cutting, at every stage
+
+## Axis A — the stage gate type
+
+From [`../pipeline.schema.json`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/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 |
+| `judgment` | somebody **rules** on it, because no complete deterministic check exists; the gate names its `judge` | recording the ruling in the slot reserved for what a machine established |
+| `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.
+
+**That sentence is about the pipeline's SHAPE, and nothing else.** It says a project
+chooses how many stages it runs and which of them wait for a person. It does not say the
+criteria inside a gate are per-run negotiable: where a project keeps stage 10 manual, what
+that gate asks is [`acceptance.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/acceptance.md)'s policy **`AP-1`**, which is versioned
+and has an owner. The two rules stood side by side unscoped until 2026-08-20 (`B-091`), and
+a reader could take either as the whole rule — *the framework fixes nothing* and *the ladder
+is fixed* are both in the shipped doctrine, which is how an acceptance standard becomes
+something every run re-argues.
+
+## The judgment gate — a ruling is not a measurement
+
+Two types were not enough, and the gap was not cosmetic. A reviewer's ruling, a check that
+the scenarios are coherent, a verdict that a mockup is good — none has a complete
+deterministic check, and all three rode in `auto`, **indistinguishable from an exit code**.
+A coverage table then cannot tell a measured row from an opinion, and the role-agent
+programme multiplies the problem: `reviewer`, `ux`, `ui` and `market-analyst` produce
+judgement by design.
+
+`auto` now means only what a machine established.
+
+**The precedent already existed in miniature, and this generalises it rather than
+inventing it.** [`templates/verification.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/templates/verification.md) already turns a
+coverage verdict of `review` into `none` in the `Auto` column — because that column records
+what a machine established, and a review is not that. That rule, applied to one column, is
+the `judgment` type in one instance.
+
+Three obligations, and the third is the one that bites:
+
+1. **It names its `judge`** — a role, an agent, a person. The schema refuses the gate
+   without one. A ruling with no author cannot be weighed for independence, and
+   independence is not a property of *having* a reviewer: this pipeline's own `R-005` reader
+   shares a model, instructions and repository with the author it reviews, differing only in
+   context. That is a real second reading and it is **not** a deterministic runner, a
+   contract at another boundary, or an external system. Naming the judge is what makes the
+   difference visible instead of assumed.
+2. **The verdict is recorded as judgement**, in the artifact that quotes it — never
+   promoted to a pass in a column that means *a machine established this*.
+3. **It may not stand in for a `manual` gate.** A judgement can be rendered by an agent; an
+   *authorisation* cannot. Anything outward, irreversible, or costing money stays `manual`
+   however confident the judge.
+
+**Which of this pipeline's own gates are judgement is deliberately not decided here.**
+Gate assignment is the operator's call and the framework fixes none — so shipping a
+reclassified stage list would contradict the sentence above it. The type exists; the
+project chooses where it applies.
+
+**The rubric steers the builder before it judges the work.** A judgment gate's
+criteria are read twice — by the judge at the gate, and earlier by whoever builds
+toward it — and the second reading is absorbed as direction: Anthropic reports
+agents converging on one aesthetic because a rubric's adjective ("museum
+quality") was obeyed as a target rather than weighed as a bar (read 2026-08-30).
+So write criteria as the direction you want taken, not only as the bar to clear;
+the words will be obeyed either way, and a rubric written carelessly is an
+instruction issued accidentally.
+
+| Rationalization | Why it is wrong |
+|---|---|
+| *"The reviewer approved it, so the gate passed."* | It did — as a judgement. Type it as one, or the table claims a machine agreed |
+| *"A second agent checked it, so it is independent."* | Independence is a different **evidence path**, not a second reader. Name the judge and the difference is visible |
+| *"There is no check for this, so it has to be `manual`."* | `manual` waits for a person's authority. `judgment` records a ruling. Collapsing them puts a human in the loop for everything that is merely hard to measure, which is how an operator learns to route around the pipeline |
+
+## 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.
+
+---
+
+## Axis C — degrees of freedom
+
+Axis B says how hard a rule bites. This one says how much latitude the *instruction*
+leaves, and it is a separate choice: a low-freedom instruction guarded by nothing is
+a wish, and a high-freedom instruction behind a blocking hook is a bottleneck.
+
+Match the level to how **fragile** the step is, not to how important it feels:
+
+| Level | Shape | Use when | Example here |
+|---|---|---|---|
+| **high** | prose direction, no prescribed sequence | many routes reach a good answer and context decides | stage 2 — the design conversation |
+| **medium** | a named order with room inside each step | the sequence is fixed, the content is judgement | stage 0 — two phases, adaptive questions |
+| **low** | run exactly this, in this order, no variation | the operation is fragile, irreversible, or must be identical every time | stage 5's TDD order · stage 7's deploy · stage 9's matrix walk |
+
+The picture worth keeping is an **open field versus a narrow bridge**. In the field,
+say where to go and let the agent find the route. On the bridge there is one safe way
+across, and the guardrails are the instruction.
+
+**Over-constraining costs as much as under-constraining and is harder to see.** A
+high-freedom step written as low freedom produces an agent that follows the letter
+past the point where the letter stopped fitting — and reports success, because it did
+what it was told. Where a step is genuinely open, say so out loud; that sentence is
+what stops the next reader from hardening it.
+
+Every stage in [`stages.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/stages.md) declares its level and its reason, on the
+line under its heading.
+
+## Progressive arming
+
+A gate seeded into a young project has almost nothing to check yet, and a gate that
+starts red teaches everyone on day one that it is noise ([`learned.md`](learned.md)
+rule 9). So each section reports one of four states and only one of them fails:
+
+| State | Means | Fails? |
+|---|---|---|
+| `ok` | the check ran and passed | no |
+| `dormant: … — no <artefact> yet` | the input does not exist yet | no |
+| `skip: … — <why>` | the input exists, the check could not run here | no |
+| `ERR` | the check ran and found something | **yes** |
+
+`dormant` and `skip` are **printed, never silent** — that is the whole reason they do
+not quietly become permanent.
+
+They also force one more obligation on the verdict line: it must report **what the
+run actually looked at**. Every section dormant is indistinguishable from a gate
+blind to the shape in front of it, and exit 0 alone cannot tell those two apart.
+
+## 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. How to plant, what a probe owes, and every way one rots is
+   [`probing.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/probing.md) — the harness is `test/probe.py`
+   (`npm run test:probe`), and hand-rolling a fourth copy of its loop is how
+   three probes in one day proved the wrong guard.
+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.
+
+**And one rule for the moment after.** A new check that goes red on the day it is
+written invites one reflex — *the check must be wrong, relax it*. Sometimes the
+check **is** wrong, **and the red is still the finding.** A guard asserted two
+constants describing "the price of one unit per year" were equal; they belong to
+two different products, so the premise was wrong and the obvious move was to
+delete the assertion. Reading further showed the disagreement was **visible to
+customers**: both products still sell from one page, and the note under the volume
+table promised a discount computed from the header's price while the table's own
+numbers gave roughly half of it. Nothing miscalculated — only the claim on the page
+was false.
+
+So: **separate the premise from the observation before touching either.** Ask what
+the check *saw*, not whether it was entitled to look. Relax or delete the assertion
+only after the thing it surfaced has its own record — otherwise the finding leaves
+with the check that found it, and nothing remembers it was ever seen.
+
+---
+
+## False success — when a mechanism reports a win it never checked
+
+The four preconditions above protect a *check*. The same law binds an **action**:
+
+> **An actor's own reply is not evidence about the world. Confirm an effect by
+> re-reading the state it changed.**
+
+A failure is loud and gets fixed on the pass that finds it. A false success is
+silent and **removes the reason to look**, which is why every shape below survived
+at least one release in this repository:
+
+| Shape | What reported success | What was actually true |
+|---|---|---|
+| Fail-open hook | any exit code but `2` is non-blocking, so a **crashed** guard *allows* the action | the guard never ran |
+| Teardown by reply | a cancel accepted an id that was never scheduled and returned success | the job was still armed |
+| Presence instead of absence | a counter asserted the new number was present, not that the old one was gone | four surfaces still printed the old number, green for three releases |
+| Half-applied batch | a batch of edits reported done while one edit never applied (R-002) | the file was unchanged |
+| Silence read as a pass | a section with no input printed nothing, and the caller counted it as checked | nothing was looked at |
+| **Read through a pipe** | the caller read the **formatter's** exit code, not the gate's | `npm test 2>&1 \| tee ../test.log` under `bash -e` without `pipefail` concluded `success` over its own `# fail 55`; `check-docs.sh \| grep FAIL \| tail && git commit` committed over a `FAIL` printed to the author's screen |
+| **An absence with no subject** | an assertion that a thing is gone, about a thing that exists nowhere | a viewport test asserting a column leaves the tree at 1279px passed at **every** width — the column had been deleted from the product months earlier |
+
+**The test.** For any mechanism you are about to trust, ask:
+*what does it print when it did not look?* If that is indistinguishable from what
+it prints when it looked and found nothing wrong, it is not evidence — give it a distinct `dormant`
+or `skip` state (→ *Progressive arming*), or verify the effect independently.
+
+Four rules follow. Elsewhere in this bundle they are **cited, never restated**:
+
+1. **Verify by re-reading, not by the reply.** After a teardown, cancel, delete,
+   disable, publish or migrate: query the authoritative state and assert the item's
+   new condition.
+2. **Assert the absence of the old, not the presence of the new.** A check that only
+   proves the new value exists stays green while the old one is still shipping.
+3. **Read a gate's own exit code, never a pipeline's.** `set -o pipefail`, or
+   `${PIPESTATUS[0]}`, or do not pipe. GitHub Actions runs `run:` under `bash -e`
+   **without** `pipefail`, so `gate | tee` reports `tee`. This is the least visible
+   entry in the table because the command reads as diligence: `check.sh | grep FAIL`
+   looks like someone being careful, and it is the shape that reports success while
+   printing failure to the screen of the person who wrote it.
+4. **An absence assertion needs a subject that exists somewhere.** Before pinning
+   "X must not appear here", prove X appears *somewhere* — otherwise the assertion is
+   true for a reason unrelated to what it claims, and the complement of *watch the
+   green fail against a planted defect* is what catches it: that rule finds a check
+   that **cannot fail**, this one finds a check that **cannot succeed meaningfully**.
+   Both are invisible to every mechanical signal — the test is green, its name is
+   accurate, its code reads correctly.
+
+---
+
+## 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.
+- **Normalise the corpus's own formatting before you match, and say which unit you
+  chose.** A predicate written against the sentence you have in mind meets the sentence
+  as the file actually stores it: wrapped at some column, with emphasis, inside a table
+  cell. Three separate guards in this bundle were defeated that way and none of them by
+  its content —
+
+  | What defeated it | The guard | The fix |
+  |---|---|---|
+  | a citation wrapped across two lines | the section-citation check | normalise whitespace, match over the paragraph |
+  | a marker split by the ~80-column wrap | the distrust-marker check | same |
+  | `**five run stamps**` — bold inside the phrase | the cold-retirement check | strip emphasis too |
+
+  Each was silent, which is the expensive part: the guard reported green over a file it
+  had never read. Pick the unit deliberately — **line, paragraph, or whole file** — write
+  down which, and probe the shape the corpus actually contains rather than the shape you
+  typed into the regex. And plant the defect **in the file that defines the thing**, not
+  in the most convenient one: a probe against a surface with none of the formatting is a
+  probe that cannot fail for this reason.
+
+---
+
+## A ratchet prices the rule, not the exception
+
+A floor that counts assertions is a floor that can be lowered by improving the code, if
+the assertions are attached to the wrong things.
+
+Measured: a coverage check called `check()` once per *exception* — a silent value, a kept
+value, a promise — and simply `continue`d on the ordinary case. Collapsing four kept
+values, **the remediation the requirement names first**, therefore dropped the count by
+four against its floor and turned the suite red on the stricter answer. The only way
+through was lowering a ratchet whose own reason says a falling count is how a deleted
+requirement hides — so a legitimate lowering and the failure the floor exists to catch
+became indistinguishable.
+
+**One assertion per subject examined, whatever its verdict.** The ordinary case asserts
+too. Then the floor is a function of how large the corpus is, not of how many exceptions
+it happens to contain, and doing the right thing can never lower it.
+
+**And measure the floor after the last edit, not before it.** Read the count, keep
+editing, restate the count you read — every floor set that way sits below the true one,
+and a floor is a minimum, so nothing ever says so. Where the gate cannot enforce
+equality — it must not, or the ratchet stops allowing growth — it can still **print the
+gap**: `floor 4026, ran 4027: 1 check is not pinned` turns a silent difference into a
+visible one for the cost of one line.
+
+## Run the whole suite locally before you push the tag
+
+Not a preference: an arithmetic. A release workflow that runs the full suite takes
+twenty-five to forty minutes per round, and it reports one failure at a time. The same
+suite on the machine that wrote the change takes twelve and reports all of them at once.
+
+On 2026-08-22 one tag took **five CI rounds** — a stray key in a `run:` block, a missing
+run stamp, a stamp cap, and then four rotted probes — where a single local `test:all`
+before the first push would have found the last four together. Every refusal was correct.
+The cost was entirely in asking the wrong machine.
+
+**A green local suite is not evidence until you know which checks LOOKED.** This
+instruction failed on its own release: the local run was green, CI was not, and the
+difference was a precondition asking `os.path.isdir(".git")` — false in a submodule
+checkout, where `.git` is a *file* holding a gitdir pointer. One check switched itself
+off in the only checkout the family is developed in, silently, and had been doing so
+since it was written. The repository had recorded that class **twice** already, in two
+other files, and this instance was missed both times: knowing a class is not sweeping
+it. Two consequences, and the second is the general one:
+
+- ask `exists`, never `isdir`, of anything named `.git`;
+- **a precondition that fails must disclose, not skip.** Where a check cannot run, it
+  appends to the unlooked list and the run prints it. A check guarded by a bare `and`
+  evaporates without a line of output, which is the one thing this file's own canon
+  forbids — and it evaporates most reliably in the environment its authors use.
+
+The rule has a second half, and it is the one that makes it stick: **a tag is the only
+thing that runs some checks.** A branch push cannot see a tag that does not exist yet, so
+the tag-ancestry check, the version-sync check and the run-stamp check have no earlier
+opportunity to fire. Locally, run them the way the release does — against the tree you are
+about to tag, with the suite the release claims.
+
+## A ratchet's matcher is itself a check, and it needs a near-miss
+
+Reported from another project through `retro.publish`, and it is the neighbour
+probe's own class ([`probing.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/probing.md) → *The neighbour probe*) arrived at
+independently — which is the strongest evidence either has.
+
+A run built a ratchet to hold a coverage debt: a list of units with no test, a guard that
+fails when the list grows, a count printed at the gate. Exactly the shape
+[`audit.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/audit.md) asks for instead of a deferred TODO. The guard decided whether a
+unit was covered by asking whether its identifier appeared **anywhere** in the test
+corpus. The identifiers were path-like and many were prefixes of longer ones, so every
+unit that happened to be the parent of another was credited with its child's coverage.
+
+**A ratchet whose matcher is looser than its subject shrinks itself.** It reports progress
+for work nobody did, and because a ratchet is trusted precisely so that nobody re-derives
+it, the error compounds for as long as the ratchet exists.
+
+Both existing rules were satisfied. The ratchet was printed. The guard had been seen going
+red when the list grew. Neither asks whether the matcher can tell its subject from a near
+neighbour, and that is the only question that would have caught it.
+
+**So before a ratchet is kept, feed its matcher a near-miss it must reject** — the prefix,
+the parent, the same name in a comment or an import, the longer extension. Seeing a guard
+go red on a real change proves it **reacts**; seeing it stay green on a look-alike proves
+it **discriminates**. Only the second makes its number worth trusting.
+
+**And when a matcher is corrected, re-derive the whole ratchet and print both numbers with
+the reason.** In the reporting project the corrected count was *identical* to the old one
+and the composition was not: rows credited falsely came back in as rows genuinely paid off
+went out. A single number with no delta reads as a run where nothing happened.
+
+## 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
+  abstained: 0 · unlooked: 4 (3 dormant · 1 skip — no submodules in this repo) · holds: 0
+```
+
+A ratchet nobody prints is a TODO with a better name.
+
+## The result is the goal; the check is how you know
+
+Everything else in this file pushes one way: prove more, assume less. Read alone it
+has an obvious failure mode — a run that spends its afternoon proving a
+one-character change and never ships the thing it was asked for. **The deliverable
+is the working result, as described in the brief. A check is how the run knows it
+has one. A check that is not buying that knowledge is not diligence; it is the run
+optimising the wrong thing.**
+
+**Scale the check to what breaking costs, and the project already computes that.**
+The board ranks by `sev × blast` ([`backlog.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/backlog.md)). The same two inputs
+size the verification:
+
+| What breaking costs | What the check has to be |
+|---|---|
+| an outward, irreversible or shared-state effect — deploy, publish, a lease, another agent's file | proven: watched failing against a planted defect, and re-read rather than trusted from the reply |
+| a contract other code depends on | an executed test, named in the REQ row |
+| behaviour a person will see | observed on the surface — a browser, the actual output — not inferred from a diff |
+| a typo, a comment, a rename the compiler checks | the compiler, the suite already running, and nothing more |
+
+**Four things that mean you have crossed over**, and each has cost this project a
+run:
+
+- **A third pass over the same axis finds mostly what the last pass's fixes broke.**
+  The axis is exhausted — rotate it or stop ([`audit.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/audit.md)).
+- **The check is being widened after it went green**, with no failure in hand. A
+  check widened by imagination is a check whose scope nobody has measured.
+- **The evidence is being gathered for a claim nobody made.** If no REQ row and no
+  gate criterion asks for it, it is not evidence — it is browsing.
+- **The run is on its second measurement of the same number.** One measurement plus
+  what it does not cover, stated, beats two measurements and no decision.
+
+**This never licenses skipping a gate.** The gates are the floor, and the floor is
+not proportionate to anything — a `manual` gate waits, `unknown` fails stage 10, and
+a green nobody watched fail is not evidence at any blast radius. What is
+proportionate is the work *above* the floor: how many axes, how many passes, how
+much of the corpus. Cutting the floor to go faster is not speed; it is the failure
+this whole file exists to prevent, arriving on schedule.
+
+**Where it is recorded.** Stages 3 and 4 carry a `Cost:` line —
+`<surfaces>/<guards>/<REQ> now, <…> at stage 2 — <proportionate | grown, and why>`.
+*Grown, and why* is the honest answer often enough that it is written into the form.
+
+## Disclosures — counted like a ratchet, and deliberately not monotone
+
+A ratchet may only shrink. **Some numbers must not be**, and printing them under a
+ratchet's discipline inverts the thing they measure.
+
+**Abstention is the case that matters.** This bundle has eight vocabularies for declining
+to claim — `partial`, `unknown`, `cannot verify from diff`, `review`, `dormant`, `skip`,
+`recalled`, `ungated` — and until they were counted, none of them appeared beside a
+verdict. So `PASS` read as *verified* rather than as *"green, and here is what nobody
+claimed"*.
+
+The obvious fix is a ratchet, and it is wrong. A count of abstentions that may only shrink
+puts pressure on exactly one thing: **claiming more**. A run reaching `abstained: 0` is not
+more careful; it is a run that stopped saying *I don't know*, which is the cheapest way to
+make the number fall. Refusals and wrong answers are communicating vessels — squeeze one
+column and it reappears in the other, silently, because a wrong claim looks like a claim.
+
+So a **disclosure** is printed beside the verdict like a ratchet and carries the opposite
+rule: **no floor, no direction, and a movement in either direction wants one sentence.**
+
+The disclosures below are kept separate because they are different facts — the list is the count:
+
+| Disclosure | Counts | Reading it |
+|---|---|---|
+| `abstained: N` | claims the run **declined to make** — `partial`, `unknown`, `cannot verify from diff` | a *choice*. Rising can mean the work got harder or the run got honest; falling can mean either the reverse |
+| `unlooked: N` | checks that **did not look** — `dormant`, `skip` | a *state of the corpus*, not a decision. It falls as the project grows the inputs those checks need |
+| `holds: N` | what the run left **running or lying about** — the eight classes in `references/residue.md` | a *state of the environment*, not of the corpus or of the run's claims. A legitimate 2 during a build beats a manufactured 0; only stage 10 requires it to reach zero or name an owner per item |
+
+Three are deliberately **not** counted, and saying which is part of the disclosure:
+
+- **`review`** — *no check can decide this* — is an abstention, and it is the one this
+  section first listed and then forgot, which is exactly the failure it exists to catch.
+  It stays out of `abstained` because it is not a claim the run declined: it is a rule
+  that **declined to be mechanical**, recorded once at rung 2 with its reason (→ *Axis B*).
+  Counted per run it would report the same standing number every time and say nothing
+  about the run.
+- **`recalled`** — a property of one claim, already carried in the ledger beside the
+  command that would re-derive it.
+- **`ungated`** — a property of the whole run, said once, in words.
+
+A vocabulary that is named and then left out of every bucket is the one that goes
+uncounted forever. So each gets its line, including the one that got missed here.
+
+**What makes a disclosure honest rather than decorative** is the same thing that makes a
+ratchet honest: it is *computed*, and it is printed whether or not anyone likes the
+number. What makes it different is that **nobody may set a target for it.** A target on an
+abstention count is an instruction to guess.
+
+---
+
+## 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. |
+
+---
+
+## Cross-cutting, at every stage
+
+**When anything is settled — scope, a contract, a
+   name, a policy, a vocabulary — run the Doc Loop
+   (`references/documentation.md`) before the run moves on**: reserve the id,
+   record it, resolve the question it answers, propagate by the matrix, commit
+   with the ids. A decision that lives only in the spec dies with the spec, and one
+   that lives only in the conversation was never made;
+   **answer from the brief's autonomy section rather
+   than asking again** — it was grilled precisely so you wouldn't have to;
+   **anything deferred, dropped or left half-done goes into the carry-over ledger
+   the moment it's said** — deferred out loud is forgotten; **never narrow the task
+   silently** — the REQ list is frozen, adding is free, removing needs the
+   operator's explicit agreement; **when a loop starts undoing an earlier pass —
+   the same file edited twice for the same reason, a closed finding coming back, a
+   third entry into one stage — stop and run the loop guard**
+   (`references/loop-guard.md`): name the two shapes, escalate to the layer that
+   owns the conflict, re-plan the check as an ordered list, then go through it one
+   item at a time; **when a pass is *searching* rather than editing and starts
+   finding mostly what the previous pass's own fixes broke, the axis is exhausted —
+   rotate it, don't look harder** (`references/audit.md`); **every gate
+   prints `holds: N` — what this run left running** across the eight classes
+   (background shells, monitors, scheduled loops, coordination leases, worktrees,
+   containers, scratch files, remote state), enumerated **by class and never by a
+   single tool**, and stage 10 does not close while this run's residue is live and
+   unaccounted (`references/residue.md`); and remember that a
+   green from a check nobody has watched fail is not evidence; task
+   tracker + conventional commits per host conventions; worktree isolation for the
+   build, integrated back per the brief's branch policy before stage 7; honest
+   degradation (never claim a failed/skipped step succeeded);
+   outward/irreversible actions (deploy, publish, repo create, opening a PR,
+   **editing a shared design file — frames are read by designers and stakeholders,
+   so drawing in one is publishing — and above all *creating* one, which needs a
+   named team and never happens while a recorded file resolves**) need explicit
+   operator go — or a **specific** standing authorization recorded in the brief
+   (named target + preconditions; a vague "do everything" is not one).
+
+Moved out of `SKILL.md` on 2026-08-16 for the same budget reason as the
+multi-repository block: these fire at any stage, so they belong with the gate
+doctrine rather than inside step 5 of the run order.
+