task-pipeline-skill 1.72.0 → 1.74.0

package/CHANGELOG.md

@@ -1,5 +1,181 @@
 # Changelog
 
+## 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
+
+
+**The claim registry had the class for this exact incident and it fired on nothing.** Three
+shipped surfaces said *34 reference files* over a directory of 35 — `scripts/graph.py`'s
+`doctrine` docstring and `templates/run.md` twice — and `npm test` printed
+`reference files: dormant (truth 35)`. Two holes, either of which was enough: the pattern
+knew only the word order ``N files under `references/` ``, and the corpus was eight named
+files plus `references/**`, so `templates/` and `scripts/` were never opened. The class now
+reads any phrasing of the count, the corpus reads the templates and the shipped script, and
+the class is armed at three agreeing sites instead of dormant.
+
+**And it never read this repository's own registers.** `docs/DOCMAP.md` names decisions,
+open questions, the board, the ledger and the retro as the registers, and its propagation
+matrix sends *a number stated in a living document* to this registry — which could not see
+any of them. `docs/OPEN_QUESTIONS.md` said *the 250 guards* against a workflow defining 390,
+in a phrasing the guard class already knew. Bringing them in refused 26 statements and every
+one was narration, so a number inside a **dated item** is a record and exempt; on the board
+the discriminator is the State cell rather than the date, because every row names the day it
+was filed and B-001 — open — was stating its description budget and its reference-file count
+as facts about now.
+
+**Fourteen consecutive releases carry no run stamp**, `v1.60.1` through `v1.72.0`, and the
+retro's honest-gap section named only `v1.16.0`–`v1.23.0`. Its *Measured, not recalled*
+receipt could not produce the measurement: it grepped `docs/superpowers/retro.md`, removed at
+v1.53.0, and grepped for a tag's own commit when a stamp names the commit the *run* ended on.
+Rewritten as a tag-range walk that reads the archive too, and a guard now requires every
+release after the newest stamp to be named in that section.
+
+Also: `## Unreleased` is where the guard count lives between a tag and the next bump (B-104);
+`Environment` is a required cell on every verification row with the vocabulary read out of
+the shipped template (B-099's other half); the graph schema states its three node rules
+behind `$ref`s and the checker follows them (B-079, proved by moving them, not by a fixture);
+an open board row's `file:N-M` must quote the phrase it points at, which caught five stale
+citations and then caught this change's own edits four more times; the acceptance ladder is
+policy **`AP-1`** with an owner and an in-force date, and `gates.md`'s *the framework fixes
+no stage count* is scoped to the pipeline's shape; `read:` and `gate:` are reported
+**unattested** instead of claimed *never agent-written*, because the ledger is the file the
+agent appends to at every stage; `validate.yml` no longer re-validates a SHA on its own tag
+push; and every documented `npm` equation is compared against `package.json` — `CLAUDE.md`
+had `npm test` as `validate.py` alone, dropping 129 graph cases.
+
+**What the suite found that no reading did.** This change broke **thirteen** existing
+plants and `npm run test:all` named every one: the two verification-header probes spell
+the whole header and it gained a column; two CHANGELOG probes scoped themselves to
+`^## v` and the count now lives in `## Unreleased`; **seven** graph-schema probes walk
+`node.allOf` inline and the rules moved behind `$ref`. All thirteen were repaired by
+deriving the guard's own scope rather than restating it, which is what `learned.md`'s
+*sweep the class* asks for — and the sweep needed two rounds: six schema probes were
+repaired together and the seventh surfaced on the next full run, having died on
+`KeyError: 'if'` where the others had died on their own asserts. A class fixed in six of
+seven places is the shape standing instruction R-003 exists for.
+
+One of the twelve was sharper than the rest, and it was self-inflicted twice over: the
+honesty note explaining that `OQ-0002` no longer restates a total put an ISO date in the
+row, which made the row a dated record and **disarmed the register plant** — green over
+exactly the stale total it had been written to catch. `OQ-####` now uses its `Status`
+cell, the discriminator the board already uses, and the register plant sits on an open
+board row where no prose edit beside it can turn it off.
+
+Guards: 390 → **412** · property checks 9 → **14**
+
+
 ## v1.72.0 — a node says how it will be closed
 
 **B-080 closed, and with it the last of four requirements this pack's own manifesto named

package/CONTRIBUTING.md

@@ -531,6 +531,67 @@ the two homes are compared directly: whatever the verifier is told to read off t
 must be a property the schema declares.
 *(guard: `node declares no` and `rule that can fire` and `off the node, and`)*
 
+**57. The claim registry reads every surface that states a number, including the ones this
+repository writes about itself.** Its corpus was eight named files plus `references/**`, so
+`templates/` and `scripts/` were invisible — three shipped surfaces said "34 reference files"
+over a directory of 35 while the class printed `dormant` — and so were the registers
+`docs/DOCMAP.md` names, where `docs/OPEN_QUESTIONS.md` said "the 250 guards" against a
+workflow defining 390. The corpus now covers both, and a class recognises every phrasing of
+its count rather than one word order. A number inside a **dated item** in a register is a
+record and exempt; on the board the discriminator is the **State** cell, because every row
+names the day it was filed and an open row is a claim about now.
+*(guard: `reference files` and `— derive the number or delete it`)*
+
+**58. Every documented `npm` command means what `package.json` runs.** `CLAUDE.md` glossed
+`npm test` as `python3 test/validate.py`, dropping `graph_test.py` and its 129 cases — the
+suite-outside-the-run class stated the other way round — and called `npm run test:all` "both"
+where it runs eight scripts. An equation is compared against the script body after one level
+of `npm run` resolution, and a bare `npm run X` in a document about this repository must be a
+script that exists. Portable doctrine under `plugins/` and `cursor/` is out of scope: it names
+a host project's commands.
+*(guard: `is glossed as` and `declares no such script`)*
+
+**59. A release either carries a run stamp or is recorded as a gap, and the guard-count claim
+has a home before the bump.** Fourteen consecutive releases had no stamp while the retro named
+only `v1.16.0`–`v1.23.0`, and the receipt that was supposed to prove it grepped a path removed
+at v1.53.0 for a tag's own commit — a stamp names the commit the *run* ended on. Scoped to the
+trailing stretch: 84 of 117 tags predate the register and backfilling is forbidden. Separately,
+the count guard reads the topmost `## ` section, so `## Unreleased` is where the number lives
+between a tag and the next bump, and it must sit above every version heading.
+*(guard: `release(s) after the newest run stamp` and `section sits below a released version`)*
+
+**60. A `file:line` range in an open board row quotes the phrase it points at.** Five
+citations resolved to real lines and pointed at other text; a line number is the most fragile
+address a document carries, because every edit above it moves it and nothing notices. Closed
+rows are records and are left alone; single-line citations cannot be quoted and are disclosed
+as unanchored rather than failed.
+*(guard: `quotes no phrase from it`)*
+
+**61. Every evidence row records the environment it ran in, and a claim of provenance the
+format cannot check is marked unattested instead.** `Observed at` said which tree a check saw
+and nothing said where it ran, so a preview smoke test and a production one entered the record
+in the same shape — in a pack whose own `learned.md` records a suite green on every author's
+machine and 1039 failures on a clean runner. And `read:`/`gate:` were declared *hook-written,
+never agent-written* while both land in the file the agent appends to at every stage: no writer
+field, no provenance check, so the count is reported `unattested` and the claim is not made.
+*(guard: `has no `Environment` cell` and `prints a count and never says`)*
+
+**62. The acceptance ladder is a versioned policy with an owner, and `gates.md`'s
+fixes-nothing sentence is scoped to the pipeline's shape.** Both rules stood unscoped side by
+side for seventy releases — *the framework fixes no stage count and no gate assignment* beside
+twelve fixed criteria — so a reader could take either as the whole rule, and a table accepted
+under v1.20 doctrine was indistinguishable from one accepted under v1.70. The block carries
+`AP-1`, an owner and an in-force date; an amendment moves the version and lands with a decision
+row.
+*(guard: `the acceptance policy carries no` and `stands unscoped beside`)*
+
+**63. A heading may not declare a bound nothing enforces.** The retro's *Recent log* read
+*entries from the last five run stamps* over 25 entries reaching back nine days, borrowing the
+stamp section's wording without its cap — filed twice as B-060 and B-069 and disclosed by the
+file about itself. Checked in the live retro and in `templates/retro.md`, which seeded the
+false bound into every host project.
+*(guard: `declares the bound` and `and nothing enforces it`)*
+
 ## Adding or changing doctrine
 
 - **Change one idea per PR.** These files are read by agents under load; a PR that

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.72.0 |
+| **Version** | 1.74.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.72.0",
+  "version": "1.74.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.72.0",
+  "version": "1.74.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` |