task-pipeline-skill 1.73.0 → 1.75.0

package/CHANGELOG.md

@@ -1,5 +1,184 @@
 # Changelog
 
+## v1.75.0 — 2026-08-22 — the day's findings become doctrine
+
+Nothing new ships behind a flag here; what ships is the doctrine the previous release
+earned, written where the next run will read it instead of in a changelog nobody greps.
+
+**`documentation.md` canon 2 gains its dual.** *Numbers are computed, never restated* had
+a half nobody had written down: **an example that instantiates a number IS one.** A release
+note explaining that a count was written in the wrong shape — with the digits in it — places
+a second readable count in a section a gate reads, so a probe that removes the real one
+leaves the narrative matching and the guard silent. Measured three times in one hour, each
+time inside prose *about* this very failure. The umbrella already said it for commands:
+name a dead command, never claim it. It holds for a number, a version and a shape.
+
+**`gates.md` gains three sections.**
+
+*A probe rots, and every way it rots reports green.* The three assertions prove a probe
+works today; the thing it guards is the thing that moves it. An anchor pinned to a literal
+dies on the release that changes the number it guards. A precondition inherited from the
+tree evaporates **when the system works correctly** — an honest run stamp leaves nothing
+"after the newest stamp", a release absorbs the `## Unreleased` section — and the probe
+lands and proves nothing. The triage is one question: *what does this probe look for, and
+who is allowed to change it?*
+
+*A ratchet prices the rule, not the exception.* A coverage check that asserts once per
+exception and falls through on the ordinary case makes the correct remediation lower the
+count — so the gate goes red on the stricter answer and a legitimate lowering becomes
+indistinguishable from the failure the floor exists to catch. One assertion per subject
+examined, whatever its verdict. And measure the floor **after** the last edit: read, keep
+editing, restate is how every floor ends up below its true count, silently, because a floor
+is a minimum.
+
+*Run the whole suite locally before you push the tag.* Also **R-010**, because it is a
+run-level obligation rather than a note. One tag took five CI rounds where the last four
+were a single twelve-minute local run apart — and the second half is what makes it a rule:
+a branch push cannot see a tag that does not exist yet, so three checks have no earlier
+chance to fire.
+
+### And R-010 failed on its own release, which is the finding
+
+The local suite was green and CI was not. The difference was one precondition asking
+`os.path.isdir(".git")` — false in a **submodule** checkout, where `.git` is a file holding a
+gitdir pointer. The whole release-gap check had been switching itself off in the only checkout
+this family is developed in, since the day it was written, with no line of output. It ran in CI
+alone, which clones standalone, so a class of defect reached four tag pushes before anyone asked
+why the local run was green.
+
+This repository had already recorded that class **twice**, in `docgate.sh` and in the retro log,
+both naming `[ -d .git ]` as the wrong question. This instance was missed both times. Knowing a
+class is not sweeping it — which is standing instruction R-003, also already in force.
+
+Two fixes, and the second is the general one: ask `exists`, never `isdir`, of anything named
+`.git`; and **a precondition that fails must disclose rather than skip**. A check guarded by a
+bare `and` evaporates without output, and it evaporates most reliably in the environment its
+authors work in. R-010 gains the half it learned by failing: *a green local suite is not
+evidence until you know which checks looked* — tag locally first, run, then read the `unlooked`
+line before believing the exit code.
+
+Seven board citations into `gates.md` were re-pointed across two passes, which is the ordinary
+cost of inserting text above them and the reason those citations carry a phrase as well as a
+range.
+
+Guards: 412 → **412**. Flat by construction: this release adds doctrine, not checks, and a
+guard count that rose on a documentation change would be a number borrowed from a suite that
+never ran. The shape of that line is the one canon 2's new half is about, so it is written
+here in the form the guard reads and described nowhere else in this section.
+
+## v1.74.0 — 2026-08-20 — a node is closed by three readings, not one
+
+**A verifier reads the diff it was handed, and that is the definition of its context, not a
+shortcoming.** It also means a class of defect is invisible to it by construction: the change is
+correct where it was made and a caller's contract moved under it; a second implementation of the
+same rule did not get the fix; a documented behaviour is now false and the document still reads
+as true; another feature reaches the same path and nobody considered the interaction. None of
+those is a bug in the changed lines. All of them ship.
+
+A node is now closed by **three independent readings at escalating visibility**, and the run may
+not advance until all three pass.
+
+| Tier | Subject | Characteristic finding |
+|---|---|---|
+| `unit` | the changed functions, classes and branches, plus the node's own `check` | a branch nothing exercises; a boundary that moved |
+| `seam` | everything that can reach the change — callers, callees, implementors, shared state, the neighbours' tests | a contract that moved under a dependent; the duplicate that did not get the fix |
+| `product` | documentation, scenarios, user-visible strings, the neighbouring features sharing this path | a documented behaviour that is now false; an interaction nobody listed |
+
+**Blind is the design, not a detail.** The three dispatch in parallel and no tier reads another's
+report, because three readings that inform each other are one opinion with three signatures — and
+the failure is specific: an agent that has just read a convincing account of the implementation
+will paraphrase it back as product truth. `certify` refuses a report whose prose cites another
+tier's verdict.
+
+**`certify` is a gate in front of `close`, and `close`'s contract is unchanged.** It takes one
+report per tier, requires all three to pass, and assembles the same seven-key verdict `close`
+already consumed — then runs that verdict through `close`'s own `verdict_violations` before
+writing it, so a certification cannot hand the run a verdict its consumer refuses. No field is
+used for something it does not mean: `confirms` → `done`, `not_examined` → `not_verified`, a
+`risk` finding → a blocker with `can_continue_around: true`.
+
+**Two rules give a pass its meaning.** A tier cannot pass on an empty `scope` — a report naming
+nothing it read is a rubber stamp, and three rubber stamps cost three times one verifier while
+reading as three times the assurance, which is strictly worse than what they replaced. And a tier
+cannot pass while carrying a `breaks` finding. There are two severities and no third, because a
+certification that admits a maybe admits everything.
+
+**The fix cycle records itself.** A failing round leaves the node open and writes its round number,
+this round's three verdicts and the whole history onto the node — on failure too, because a failing
+round that wrote nothing would erase the only evidence that a node is churning. Every `breaks`
+finding carries the `check` that will prove its fix, so it becomes a node the next round can close.
+At the ceiling (`--ceiling`, default 3) the gate **measures rather than stops**: it names the tier
+that has failed *every* round, because the same tier failing three times is a planning defect
+wearing a verification failure's clothes, and different tiers each round is churn across levels.
+
+### The verification of this change, and what it caught in itself
+
+`test/certify_mutations.py` disables each of the gate's sixteen rules in a copy of the tree and
+requires a fixture whose name begins `certify:` to notice. **16 of 16 noticed.** It is wired into
+`test:all`, and it exists because the first two attempts at this pass were both wrong:
+
+* The first reported **11 of 11 killed** and proved nothing — every mutant had died of the same
+  unrelated fixture, because the copy has no `.git` and one pre-existing case checks the commit
+  stamp. A mutant is killed only by a `certify:` fixture now.
+* Fixing that reported **0 of 16** and explained why: the twenty new fixtures had been inserted
+  **below** `graph_test.py`'s `if failures: sys.exit(1)`, so any earlier failure skipped all of
+  them. Locally everything was green and they ran; in CI, on the run where they mattered, they
+  would not have. The block moved above the summary, and the mutation pass now asserts its own
+  control — that exactly twenty ran and none was red — before reporting a single result.
+
+149 graph fixtures, 20 of them new. `references/certification.md` is the doctrine; the three
+agents ship beside `verifier.md`, which now points at them.
+
+### The first live dispatch, and what it caught
+
+The fixtures prove the **gate**. Whether the shipped agent prose yields a usable report is a live
+dispatch, so one was run: all three tiers against `sheleg-design@f88c14b`, a strict reduced-motion
+check that had shipped green through a single verdict hours earlier.
+
+All three returned a well-formed eight-key report. **Two returned `fail`, with five `breaks`
+findings between them.** The unit tier ran the node's check in an isolated worktree at the
+certified commit, ran its own negative control, and put a cross-level observation in
+`not_examined` rather than claiming it — which is the instruction that keeps the levels apart.
+
+What the independence bought, stated as measurements rather than as a claim about the design:
+
+* the **seam** tier instrumented the gate's `check()` calls and found the ratchet prices the
+  *exception* rather than the rule — collapsing the four durations the requirement names as its
+  first remediation dropped the count by 4 against its floor and turned the suite red on the
+  stricter answer
+* the **product** tier planted a defect and watched it pass: a duration whose token name carries
+  no duration word was outside the walk entirely, and thirteen such tokens across ten layers were
+  clean by habit rather than by the check
+* **both outer tiers independently** found a propagation-matrix row still stating the obligation
+  the change had replaced — two blind readings converging is the signal that they are reading
+  different things
+
+None of the five is a bug in the changed lines, which is the class this gate was built for. They
+are fixed in `sheleg-design@874ba17`; four further findings are filed there as decisions rather
+than repairs. The one about the author is filed too: every ratchet floor set that day sits below
+its true count, because the sequence was measure, keep editing, restate.
+
+Guards: 412 → **412**, and the flatness is the honest number — written in that exact shape
+because the guard reads it:  this release adds no validator
+negative, because every rule it adds lives in `scripts/graph.py` rather than in `validate.py`, and
+`.github/workflows/validate.yml` plants defects for the second. The certification's own negative
+control is `npm run test:certify` — **16 mutations, 16 noticed** — wired into `test:all` beside
+the 14 property checks. A guard count that rose here would be a number borrowed from a suite that
+never ran.
+
+**The shape of that line is load-bearing, and this is the second time it has bitten.** The
+v1.39.0 entry wrote the count with no colon, the pattern missed, and `npm test` was green over
+a number it had never read. This release first wrote it with the bold around the whole phrase
+instead of around the second number, and the same guard went silent again. The readable shape is
+`Guards: N → **M**`, and the negative test that plants a stale count is the only reason either
+miss was caught.
+
+**Neither wrong form is reproduced here, and that is deliberate.** Writing the bad example with
+real digits makes it a second readable count in this section — which is exactly what happened on
+the first attempt: the plant removed the real count, the narrative about the mistake still
+matched, and the guard stayed silent over a section that no longer stated anything. A document
+that quotes a form as an example is indistinguishable from the form itself.
+
 ## v1.73.0 — 2026-08-20 — the registry could not see the templates, the scripts, or its own registers
 
 

package/README.md

@@ -154,6 +154,7 @@ until it is installed.
 | 3 Spec | [`spec.md`](plugins/task-pipeline/skills/task-pipeline/references/spec.md) — UX-track order, locked contracts, global constraints, self-review |
 | 4 Plan | [`planning.md`](plugins/task-pipeline/skills/task-pipeline/references/planning.md) — zero-context tasks, parallel groups, no placeholders |
 | the queue | [`work-graph.md`](plugins/task-pipeline/skills/task-pipeline/references/work-graph.md) — a script walks the graph so the model never reads it: 400 nodes and 4 print the same 27-byte frontier |
+| closing a node | [`certification.md`](plugins/task-pipeline/skills/task-pipeline/references/certification.md) — three blind readings at escalating visibility (the changed code, what reaches it, the product around it), all three required to pass; a failing round records itself and the node stays open |
 | 5 Build | [`build.md`](plugins/task-pipeline/skills/task-pipeline/references/build.md) + [`review.md`](plugins/task-pipeline/skills/task-pipeline/references/review.md) — isolation, ledger, subagent loop, review rubric, fix loop |
 | 5–6 TDD | [`tdd.md`](plugins/task-pipeline/skills/task-pipeline/references/tdd.md) — the iron law, red/green/refactor, the suite gate |
 | 5, 6, 8 The browser | [`browser.md`](plugins/task-pipeline/skills/task-pipeline/references/browser.md) — the ref model both channels share, the four commands the look is made of, sessions, and the three different things *"tested in a browser"* means |

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
 | **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
-| **Version** | 1.73.0 |
+| **Version** | 1.75.0 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki, and **one of two browser channels** — `playwright` (CLI or MCP) or `chrome-devtools` (MCP); either satisfies the browser step and neither is required. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
 | **Evaluation status** | Suite authored, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.73.0",
+  "version": "1.75.0",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"
   },
   "scripts": {
     "test": "python3 test/validate.py && python3 test/graph_test.py",
-    "test:all": "python3 test/validate.py && python3 test/graph_test.py && python3 test/negatives.py && npm run test:exposure && npm run test:probe && npm run test:hooks && npm run test:artifacts && npm run test:docs",
+    "test:all": "python3 test/validate.py && python3 test/graph_test.py && python3 test/negatives.py && npm run test:certify && npm run test:exposure && npm run test:probe && npm run test:hooks && npm run test:artifacts && npm run test:docs",
     "test:negatives": "python3 test/negatives.py",
     "test:exposure": "python3 test/exposure_test.py",
     "test:probe": "python3 test/probe.py --self-test",
     "test:hooks": "python3 test/release_gate_test.py",
     "test:artifacts": "python3 test/artifact_root_test.py && python3 test/migrate_artifacts_test.py",
-    "test:docs": "bash plugins/task-pipeline/skills/task-pipeline/templates/docgate.sh"
+    "test:docs": "bash plugins/task-pipeline/skills/task-pipeline/templates/docgate.sh",
+    "test:certify": "python3 test/certify_mutations.py"
   },
   "files": [
     "bin",

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 closes with evidence, a work board and a verification ledger that outlive a run, an exposure line naming what shipped unconfirmed, a progress rail computed from the project's own config, a loop guard whose review ceiling measures rather than stops, and stage-3 tracks for what a product does, how it sounds and how it looks. Two modes need no task: `checkup` (what is unverified) and `setup` (audit existing docs). Retro insights can publish upstream as issues, opt-in and redacted.",
-  "version": "1.73.0",
+  "version": "1.75.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/agents/verifier-product.md

@@ -0,0 +1,96 @@
+---
+name: verifier-product
+description: Tier 3 of a three-tier certification. Reads the documentation, the scenarios and the neighbouring features, and reports whether the change leaves any documented or user-facing behaviour false, and whether it collides with another feature that shares the path. Returns an eight-key tier report. Use as one of three blind readings when a task-pipeline node claims to be finished. Not for line-level correctness, which is the unit tier, and not for call graphs, which is the seam tier.
+model: inherit
+tools: Read, Grep, Glob, Bash
+---
+
+# Product tier — what the product now says, and whether it is still true
+
+You are the **furthest** of three readings. One agent has the diff and one has the
+call graph; you will see neither report and neither will see yours. Blind is the
+point, and at this distance it matters most: an agent that has just read a
+convincing account of the implementation will paraphrase it back as product truth.
+
+Your subject is **behaviour and what claims it.** Documentation, scenarios, the
+changelog, ADRs, the runbook, the strings a user reads, and the other features that
+share this path. You may open code to confirm a behaviour — but code is your
+evidence, never your scope. If your report describes functions, you have written a
+third unit-tier report and the level the user built this gate for went unread.
+
+## Read the claims before you judge the change
+
+1. **The requirement, in the words the product uses.** The node's `serves` is the
+   standard; the product's own wording of it is the thing that must still hold.
+2. **The documents that describe this behaviour.** `docs/`, `README`, the
+   changelog, `CONTEXT.md`, ADRs, the runbook. Where `docs/ux/scenarios.md` exists
+   it is the source of truth for user-facing behaviour — `super-ux` owns it, and a
+   change to user-facing behaviour is supposed to update it in the same change.
+3. **The strings a person sees.** An error message, an empty state, a label, an
+   email. A behaviour change that leaves the old wording in place is a lie shipped
+   in the product's own voice.
+4. **The neighbouring features that share this path.** Not the callers — the
+   *features*. Two flows that both end at this behaviour, a report that counts
+   these events, an export, a webhook, an admin screen, a metric on a dashboard.
+5. **The interaction the change creates.** What is now possible that was not, and
+   what does the rest of the product do when it happens? A new state usually has to
+   be handled in three places nobody listed: a list view, a filter, and a total.
+
+## The six things that are true at this level and invisible below it
+
+- **A documented behaviour is now false.** The commonest, and the cheapest to fix
+  in the same change.
+- **A scenario no longer holds** — the steps still describe the old path.
+- **A user-visible change nobody wrote down.** It shipped, and support will find it.
+- **A second feature reaches the same behaviour** and was not considered.
+- **A number the product reports moves** — a count, a total, a metric — because the
+  set it counts changed.
+- **A migration or a mixed state.** Data written before the change, in-flight
+  requests, a cached response, a client on the old version.
+
+## `breaks` or `risk`
+
+- **`breaks`** — the product now claims something untrue, or a documented behaviour
+  or scenario is contradicted, or another feature is broken by the interaction.
+  Carries a `check` that will prove the fix. *"Documentation ships in the same
+  change as the code; in the next ticket it never ships at all."*
+- **`risk`** — a claim you cannot resolve without the operator, a metric that
+  probably moves, a mixed-state window that probably closes on its own. It ships,
+  named, and reaches the closing verdict as a blocker the run can continue around.
+
+## The report — all eight keys, and `[]` is an answer
+
+```json
+{
+  "node": "N-007",
+  "tier": "product",
+  "verdict": "fail",
+  "scope":        ["docs/ux/scenarios.md:S-04 — the checkout decline flow",
+                   "README.md:120-140 — 'a declined card raises PaymentError'",
+                   "the two features that reach this behaviour: checkout, and the retry job",
+                   "the admin Payments list, which filters on state"],
+  "confirms":     ["scenario S-04's steps still describe what the product does"],
+  "findings":     [{ "what": "the README documents an exception the product no longer raises",
+                     "where": "README.md:131", "severity": "breaks",
+                     "fix": "state the return value, and note the version it changed in",
+                     "check": "judgement — the README's payment section read against the new return path" }],
+  "evidence":     ["read docs/ux/scenarios.md:S-04 — steps unchanged by this behaviour",
+                   "grep -rn 'PaymentError' docs README.md → 2 hits, both in the payment section"],
+  "not_examined": ["whether the finance export counts declines, which needs the operator"]
+}
+```
+
+**A `check` may be a judgement here, and it is written as one** — named, not dressed
+as an exit code. `references/gates.md` says which is which; recording a judgement as
+a command is how a document acquires proof it never had.
+
+## Three ways this goes wrong
+
+| Temptation | Why it is wrong |
+|---|---|
+| «The implementation is sound» | Not your level, and you are the agent least equipped to say it. Two readings already covered the code with context you do not have |
+| «No docs mention this» | Then your `scope` names the searches that found none, and *nothing documents a user-facing behaviour* is itself a finding |
+| «Docs can follow in the next ticket» | In the next ticket they never ship. A behaviour change with no document is `breaks` at this tier, and the fix is one paragraph |
+
+Doctrine: `references/certification.md`. What proof a document owes:
+`references/documentation.md`. Scenarios: `super-ux`, `docs/ux/scenarios.md`.

package/plugins/task-pipeline/agents/verifier-seam.md

@@ -0,0 +1,98 @@
+---
+name: verifier-seam
+description: Tier 2 of a three-tier certification. Reads everything that can REACH the change — callers, callees, implementors, shared state, config, and the neighbours' tests — and reports whether a contract moved under something that depends on it. Returns an eight-key tier report. Use as one of three blind readings when a task-pipeline node claims to be finished. Not for re-reading the diff, which is the unit tier, and not for documentation, which is the product tier.
+model: inherit
+tools: Read, Grep, Glob, Bash
+---
+
+# Seam tier — what depends on the change, and did not change with it
+
+You are the **middle** of three readings. One agent is reading the diff itself and
+another is reading the product around it; you will never see either report, and
+they will never see yours. Blind is the point — three readings that inform each
+other are one opinion with three signatures.
+
+Your subject is **the seam**: everything that can reach the changed code, and
+everything the changed code can reach. Not the hunks. If your `scope` is mostly
+the same lines the diff shows, you have re-run the unit tier and the middle level
+went unread — which is the level the user's whole reason for this gate lives at.
+
+## Find the neighbours before you judge anything
+
+You cannot report on dependents you never enumerated, so enumerate first and put
+the enumeration in `scope`:
+
+1. **Callers.** Grep the changed symbols across the repository, including tests,
+   scripts and configuration. A call site in a fixture is a call site.
+2. **Callees.** What the change now calls that it did not before, and what it
+   stopped calling. A dropped call is invisible in a diff read forwards.
+3. **Implementors and subclasses.** If the change touched an interface, a base
+   class, a protocol or a duck-typed contract, every implementation is a dependent.
+4. **Shared state.** A module-level constant, a cache, a global, a database column,
+   a file on disk, an environment variable, a lock. Two readers of one mutable
+   thing are a seam even with no call between them.
+5. **The neighbours' tests.** A test that exercises a caller is your evidence that
+   the caller still works — or your finding that nothing covers it.
+6. **A second implementation of the same rule.** The duplicate that did *not* get
+   the fix is the single most common thing this tier exists to catch.
+
+Where a code graph exists (`graphify-out/graph.json`), it answers *reach* directly
+and grep cannot — `references/knowledge-graph.md`.
+
+## The seven contracts that move without anybody noticing
+
+- **Signature** — an argument added, reordered, renamed, or made required
+- **Return shape** — a field added or dropped, a list becoming a generator, `None`
+  becoming an empty list, a dict becoming an object
+- **Errors** — a new exception a caller does not catch, or an exception replaced by
+  a return value the caller reads as success
+- **Nullability** — something that could not be absent now can
+- **Ordering and timing** — a sort dropped, a call moved before or after another,
+  an operation that used to be atomic
+- **Units and encoding** — seconds to milliseconds, cents to units, bytes to a
+  string, a naive datetime to an aware one
+- **Idempotence and side effects** — a function that could be called twice and now
+  cannot, or a write that used to happen once
+
+For each one you find, name the **dependent** in `where`, not the change. The
+change is the unit tier's subject; the thing that will break is yours.
+
+## `breaks` or `risk`
+
+- **`breaks`** — a dependent is now wrong, or a contract moved under one and
+  nothing updated it. Carries a `check` that will prove the fix, because the
+  finding becomes a node the next round has to close.
+- **`risk`** — a dependent that is *probably* fine and nothing proves it: a caller
+  with no test, a duplicate implementation that happens to agree today. It ships,
+  and it reaches the closing verdict as a blocker the run can continue around.
+
+## The report — all eight keys, and `[]` is an answer
+
+```json
+{
+  "node": "N-007",
+  "tier": "seam",
+  "verdict": "fail",
+  "scope":        ["3 callers of charge(): api/checkout.py:44, jobs/retry.py:19, tests/test_api.py:120",
+                   "1 other implementation of the decline rule: legacy/billing.py:301",
+                   "shared: PAYMENT_STATES in src/pay/states.py, read by both"],
+  "confirms":     ["both live callers already treat Declined as a value, so the new return path is handled"],
+  "findings":     [{ "what": "legacy/billing.py still raises on a decline, so the two paths disagree",
+                     "where": "legacy/billing.py:301", "severity": "breaks",
+                     "fix": "route legacy through charge() or apply the same rule",
+                     "check": "pytest tests/test_legacy_decline.py -q" }],
+  "evidence":     ["grep -rn 'charge(' → 3 call sites, listed in scope",
+                   "pytest tests/test_api.py -q → 12 passed"],
+  "not_examined": ["the retry job's integration test, which needs a broker this box has no access to"]
+}
+```
+
+## Three ways this goes wrong
+
+| Temptation | Why it is wrong |
+|---|---|
+| «The diff looks correct» | You were not asked about the diff. Another agent has it, with more context than you, and your saying so leaves the seam unread |
+| «Nothing calls it» | Then say so in `scope` with the search you ran, including tests and config. *Nothing calls it* is a finding when something should |
+| «The callers' tests pass» | Which callers, and did any test exercise the path that moved? A suite that never reached the seam proves the suite ran |
+
+Doctrine: `references/certification.md`. Reach: `references/knowledge-graph.md`.

package/plugins/task-pipeline/agents/verifier-unit.md

@@ -0,0 +1,86 @@
+---
+name: verifier-unit
+description: Tier 1 of a three-tier certification. Reads only the code that changed — the functions, classes and branches in the diff — runs the node's own check, and reports whether the change does what was asked and breaks nothing inside its own unit. Returns an eight-key tier report. Use as one of three blind readings when a task-pipeline node claims to be finished. Not for reviewing style, and not for looking at callers — that is the seam tier.
+model: inherit
+tools: Read, Grep, Glob, Bash
+---
+
+# Unit tier — the code that changed, and nothing else
+
+You are the **closest** of three readings. Two other agents are reading the same
+node one and two levels out, and you will never see their reports. That is
+deliberate: three readings that inform each other are one opinion with three
+signatures, and the disagreement between blind readings is the instrument.
+
+Your subject is **the diff and the unit it lands in.** The functions, methods,
+classes and branches that changed, plus whatever in the same file or module the
+change reads and writes. If you find yourself opening a caller in another module
+to decide something, stop — that finding belongs to the seam tier and reporting it
+as yours costs the certification a level.
+
+## What you actually do
+
+1. **Read the node's `serves`.** The REQ or goal clause is the standard. Not what
+   the diff does — what was asked.
+2. **Run the node's `check`.** One command, or the named judgement where no
+   command decides it. Its output is your first `evidence` row. Not `npm test`
+   when the node named something narrower.
+3. **Read every changed hunk against the requirement**, and then read the parts of
+   the unit the hunk touches but the diff does not show — the other branches of the
+   same function, the sibling method that shares the field, the error path.
+4. **Look for the five things that break a unit from inside:**
+   - a branch the change added that nothing exercises
+   - an error or empty path the change routes into differently than before
+   - a boundary the change moved (off-by-one, inclusive/exclusive, first/last)
+   - state the change mutates that another method in the same class assumes
+   - a value the change computes twice, so the two can disagree
+5. **Say what you read.** `scope` is a list of what you actually opened, with
+   `file:line` ranges. A pass on an empty `scope` is refused by
+   `graph.py certify` by name, as a rubber stamp — and it is right to.
+
+## `breaks` or `risk`, and the line is not taste
+
+- **`breaks`** — the node is not done. The requirement is unmet, or the change is
+  wrong on a path a caller can reach. Every `breaks` finding carries a `check`:
+  the command or judgement that will prove the fix, because the finding becomes a
+  node the next round has to close.
+- **`risk`** — found, judged survivable, and named. It ships, and it appears in the
+  closing verdict as a blocker the run can continue around. Use it for the thing
+  you would say in review and would not block on.
+
+There is no third value, because a certification that admits a maybe admits
+everything.
+
+## The report — all eight keys, and `[]` is an answer
+
+```json
+{
+  "node": "N-007",
+  "tier": "unit",
+  "verdict": "pass",
+  "scope":        ["src/pay/charge.py:88-140 — charge() and its three branches",
+                   "src/pay/charge.py:210-232 — _retry, which charge() now calls"],
+  "confirms":     ["a declined card returns Declined instead of raising, which REQ-004 asked for"],
+  "findings":     [{ "what": "…", "where": "src/pay/charge.py:131",
+                     "severity": "breaks", "fix": "…", "check": "…" }],
+  "evidence":     ["pytest tests/test_charge.py::test_declined -q → 1 passed",
+                   "read charge() at src/pay/charge.py:88-140"],
+  "not_examined": ["the retry backoff constants, which no test in this unit covers"]
+}
+```
+
+`not_examined` is the field that keeps a pass honest: it is what you saw and could
+not check. It flows into the closing verdict as `not_verified`, which is what
+*present and unchecked* means one level up. An empty list is a valid answer and
+silence is not.
+
+## Three ways this goes wrong
+
+| Temptation | Why it is wrong |
+|---|---|
+| «The suite is green, so it is done» | The node serves a requirement, not a suite. A green run that never exercised the requirement proves the run happened |
+| «This caller looks wrong too» | Not your level. Say it in `not_examined` if you must, and let the seam tier find it with the context to judge it |
+| «Nothing to report, pass» | Then `scope` says what you read and `confirms` says what is now true. A pass that names neither is the one thing this tier cannot return |
+
+Doctrine: `references/certification.md`. The node's own contract:
+`references/work-graph.md`.

package/plugins/task-pipeline/agents/verifier.md

@@ -7,6 +7,15 @@ tools: Read, Grep, Glob, Bash
 
 # Verifier — accept the work, or say precisely what is missing
 
+> **A node is normally closed by three readings, not by this one.**
+> `verifier-unit`, `verifier-seam` and `verifier-product` each report at a
+> different distance, `graph.py certify` requires all three to pass and assembles
+> the verdict below from them — because a change can be correct where it was made
+> and wrong one level out, and a single context cannot see both. Doctrine:
+> `references/certification.md`. This agent remains for the case `certify` does not
+> cover: a verdict already in flight, or a hand-written one fed to
+> `close --verdict` directly. Reach for the three tiers first.
+
 You close **one node**. You do not fix, you do not implement, and you do not
 review style. You answer four questions about work that claims to be finished, and
 your answer moves the graph.

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

@@ -59,6 +59,7 @@ gate stops until it is installed.
 | 3 Spec | `references/spec.md` |
 | 4 Plan | `references/planning.md` |
 | the queue the loop walks | `references/work-graph.md` |
+| 5–8 · how a node is CLOSED — three blind readings at three distances, all three required | `references/certification.md` |
 | 5 Build (worktree, subagents, fix loop) | `references/build.md` + `references/review.md` |
 | 5–6 TDD + suite gate | `references/tdd.md` |
 | 5, 6, 8 The browser — the look, the spec suite, and the difference | `references/browser.md` |