task-pipeline-skill 1.73.0 → 1.75.0

package/plugins/task-pipeline/skills/task-pipeline/graph.schema.json

@@ -117,7 +117,7 @@
           "not": {
             "pattern": "[\\n\\r]"
           },
-          "description": "**How this node will be closed** \u2014 the command a verifier runs, or the named judgement that stands in where no command can (`references/gates.md`'s third gate type: name the judge, record the verdict AS judgement). Its output becomes the node's `evidence` row.\n\nRequired on every node except a `parked` one, and that is the whole point of the field: `agents/verifier.md` tells the verifier to run *the check this node names*, so a node with none leaves it the two options that same paragraph forbids \u2014 invent a check, or run everything. Shipped doctrine read a field the schema did not have (B-080); the field the doctrine reads now exists.\n\nOne string, never a list, because the requirement it serves is singular throughout \u2014 one input, one job, one output, one owner, **one** completion test. A node needing two unrelated checks is a node doing two jobs, and the answer is to split it rather than to widen this field. One gate made of two commands is `a && b`, which is still one gate.\n\nA `parked` node is exempt because it is the one node nobody will close, and a placeholder there \u2014 *n/a, parked* \u2014 is the confidence-without-correctness this schema refuses everywhere else. The field survives a park: `park` sets the status and never removes what the node said it would run."
+          "description": "**How this node will be closed** — the command a verifier runs, or the named judgement that stands in where no command can (`references/gates.md`'s third gate type: name the judge, record the verdict AS judgement). Its output becomes the node's `evidence` row.\n\nRequired on every node except a `parked` one, and that is the whole point of the field: `agents/verifier.md` tells the verifier to run *the check this node names*, so a node with none leaves it the two options that same paragraph forbids — invent a check, or run everything. Shipped doctrine read a field the schema did not have (B-080); the field the doctrine reads now exists.\n\nOne string, never a list, because the requirement it serves is singular throughout — one input, one job, one output, one owner, **one** completion test. A node needing two unrelated checks is a node doing two jobs, and the answer is to split it rather than to widen this field. One gate made of two commands is `a && b`, which is still one gate.\n\nA `parked` node is exempt because it is the one node nobody will close, and a placeholder there — *n/a, parked* — is the confidence-without-correctness this schema refuses everywhere else. The field survives a park: `park` sets the status and never removes what the node said it would run."
         },
         "evidence": {
           "type": [
@@ -145,6 +145,89 @@
             "pattern": "\\S"
           },
           "description": "What this node MUTATES — paths, register names, remote resource ids. `references/planning.md` states the rule the frontier needs: *distinct is not the same as independent, and the check is what they touch, never what they are called.* That rule lived in the markdown plan, and the graph replaced the plan as the thing deciding what runs next — so `next` could hand two agents two runnable nodes that write the same file, with nothing able to report it.\\n\\nOptional, and its absence is DISCLOSED rather than treated as «touches nothing»: `next` prints how many frontier nodes declared no targets, because a quiet run and a checked one must not look alike."
+        },
+        "certification": {
+          "type": "object",
+          "description": "What the three-tier certification recorded for this node. Written by `graph.py certify` on every round, pass or fail: a failing round that wrote nothing would erase the only evidence that a node is churning, which is the number the loop-guard ceiling reads.",
+          "additionalProperties": false,
+          "required": [
+            "round",
+            "tiers",
+            "at",
+            "history"
+          ],
+          "properties": {
+            "round": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "tiers": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "unit",
+                "seam",
+                "product"
+              ],
+              "properties": {
+                "unit": {
+                  "enum": [
+                    "pass",
+                    "fail"
+                  ]
+                },
+                "seam": {
+                  "enum": [
+                    "pass",
+                    "fail"
+                  ]
+                },
+                "product": {
+                  "enum": [
+                    "pass",
+                    "fail"
+                  ]
+                }
+              }
+            },
+            "at": {
+              "type": "string",
+              "minLength": 1
+            },
+            "history": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "unit",
+                  "seam",
+                  "product"
+                ],
+                "properties": {
+                  "unit": {
+                    "enum": [
+                      "pass",
+                      "fail"
+                    ]
+                  },
+                  "seam": {
+                    "enum": [
+                      "pass",
+                      "fail"
+                    ]
+                  },
+                  "product": {
+                    "enum": [
+                      "pass",
+                      "fail"
+                    ]
+                  }
+                }
+              }
+            }
+          }
         }
       },
       "allOf": [

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

@@ -0,0 +1,146 @@
+# Certification — three readings at three distances, and all three must pass
+
+A node is not closed by one agent's opinion. It is closed by **three independent
+readings at escalating visibility**, and the run may not advance until all three
+pass.
+
+## Contents
+
+- Why one verifier is not enough, stated as the failure it produces
+- The three tiers
+- Blind, and it is the whole design
+- A pass has to mean something, so two rules have teeth
+- The report, and where each field lands
+- The commands
+- The fix cycle, and its ceiling
+- What this costs, said out loud
+- Rationalizations
+
+## Why one verifier is not enough, stated as the failure it produces
+
+A verifier reads the diff it was handed. That is not a shortcoming of the agent; it
+is the definition of its context. And it means a whole 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 these is a bug in the changed lines. All of them ship. Each is found by
+looking one level further out than the change — which is a different reading, not a
+longer one, because the context that finds it is the context that excludes the diff.
+
+## The three tiers
+
+| 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, and the neighbouring features that share this path | a documented behaviour that is now false; an interaction nobody listed |
+
+Agents: [`../../../agents/verifier-unit.md`](../../../agents/verifier-unit.md),
+[`verifier-seam.md`](../../../agents/verifier-seam.md),
+[`verifier-product.md`](../../../agents/verifier-product.md).
+
+## Blind, and it is the whole design
+
+**The three run in parallel and no tier reads another's report.** Three readings
+that inform each other are one opinion with three signatures — and the failure mode
+is specific: an agent that has just read a convincing account of the implementation
+will paraphrase it back as product truth. The disagreement between blind readings is
+the instrument, so `graph.py certify` refuses a report whose prose cites another
+tier's verdict.
+
+Dispatch all three in one message so they run concurrently. Give each the node id,
+its `serves`, and the diff — nothing else, and never another tier's output.
+
+## A pass has to mean something, so two rules have teeth
+
+**A tier cannot pass on an empty `scope`.** `scope` is what the tier actually
+opened, with `file:line`. A report that names nothing it read is a rubber stamp, and
+three rubber stamps cost three times one verifier while reading as three times the
+assurance — strictly worse than the single verdict it replaced. `certify` refuses it
+by name.
+
+**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:
+
+- **`breaks`** — the node is not done. Carries a `check`: the command or judgement
+  that will prove the fix, for the same reason `replan.add` does. The finding
+  becomes a node the next round has to close, and handing that node the absence is
+  how the defect returns one round later.
+- **`risk`** — found, judged survivable, and named. It ships, and it reaches the
+  closing verdict as a blocker with `can_continue_around: true`, which is exactly
+  what a named survivable finding is.
+
+## The report, and where each field lands
+
+Eight keys, all required, `[]` a valid answer and silence not one. On a pass
+`certify` assembles the canonical seven-key verdict that
+[`work-graph.md`](work-graph.md) already specifies, and no field is used for
+something it does not mean:
+
+| Tier field | Becomes | Because |
+|---|---|---|
+| `confirms` | `done` | asked for, and now true |
+| `not_examined` | `not_verified` | present, and no check touched it |
+| `findings` at `risk` | `blockers`, `can_continue_around: true` | found, judged survivable, named |
+| `evidence` | `evidence`, prefixed with the tier | the command and what it printed |
+
+`certify` runs the assembled verdict through the same `verdict_violations` gate
+`close` will apply, so a certification cannot hand the run a verdict its own
+consumer refuses.
+
+## The commands
+
+```bash
+# three reports in, one verdict out — exits 1 if any tier failed
+graph.py certify --node N-007 \
+    --tier unit.json --tier seam.json --tier product.json
+
+# unchanged, and still the only thing that moves the graph
+graph.py close --verdict .task-pipeline/verdict-N-007.json
+```
+
+## The fix cycle, and its ceiling
+
+A failing round **records itself and leaves the node open.** `certification` on the
+node carries the round number, this round's three verdicts and the history of every
+round — written on failure too, because a failing round that wrote nothing would
+erase the only evidence that a node is churning.
+
+The cycle is: `certify` → fail → the `breaks` findings become nodes (each already
+carrying its `check`) → fix → `certify` again, round `N+1`. Same three tiers, same
+blind dispatch. A tier that passed in an earlier round is **re-run**, because the
+fix is a new change and the level it passed on is not the level it now faces.
+
+**At the ceiling the gate measures rather than stops** —
+[`loop-guard.md`](loop-guard.md). `--ceiling` defaults to 3. At or over it, `certify`
+still runs and still reports the tiers; what it adds is the name of the tier that
+has failed **every** round. A run spinning on one level needs the operator to see
+*which* level:
+
+- the same tier every round → the level is being misread, or the node is the wrong
+  shape. Not one fix away. Re-plan the node, do not attempt round four.
+- different tiers each round → churn across levels. Usually one requirement that
+  was never decided, surfacing at whichever distance looks at it.
+
+## What this costs, said out loud
+
+Three agents per node instead of one. That is the price of the visibility, and it is
+paid per node rather than per run. The three are dispatched in parallel, so the
+wall-clock cost is roughly one reading; the token cost is three. A node whose
+`check` is mechanical and whose blast radius is genuinely nil still pays it — and a
+tier with nothing to find says so in `scope` and `not_examined` rather than being
+skipped, because **a skipped level and a clean level are indistinguishable
+afterwards**, and only one of them is evidence.
+
+## Rationalizations
+
+| Temptation | Why it is wrong |
+|---|---|
+| «All three would say the same thing» | Then all three say it, at a cost you already know, and the run has three signatures instead of one guess about what the other two would have found |
+| «The seam tier can read the unit report first — it saves tokens» | It saves tokens by removing the second opinion. The reports are cheap; the independence is the product |
+| «Tier 3 passed last round, skip it» | The fix is a new change. A tier's pass is about the tree it read, and that tree moved |
+| «Round 4 will get it» | Read the ceiling's output. The same tier failing three times is a planning defect wearing a verification failure's clothes |

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

@@ -49,9 +49,23 @@ the same run and a description of the behaviour is not the behaviour. → the re
 SHA-resolution guard; the finding shape in [`setup.md`](setup.md); [`tdd.md`](tdd.md) →
 *When the thing under test is an agent*.
 
-**2. Numbers are computed, never restated.** A count in prose is a number that was true
-once. Derive it at check time and compare the stated one against the computed one as the
-same object. → [`learned.md`](learned.md) rule 8.
+**2. Numbers are computed, never restated — and an example that instantiates a number
+IS one.** A count in prose is a number that was true once. Derive it at check time and
+compare the stated one against the computed one as the same object. → [`learned.md`](learned.md)
+rule 8.
+
+The half that costs more, because it is written by the person who understands the rule:
+**a document quoting a form as an example is indistinguishable from the form.** A release
+note explaining *"the count was written wrongly as `Guards: 412 → 412`"* has just placed a
+second readable count in a section whose count a gate reads — so when the probe removes the
+real one, the narrative still matches and the guard reports green over a section that states
+nothing. Measured three times in one hour on 2026-08-22, each time inside prose *about* this
+very failure: the release note, the board row filed against it, and the repair to the probe.
+
+The rule the umbrella already states for commands — **name a dead command, never claim it**
+— holds for a number, a version and a shape. Describe the wrong form; do not write it.
+*"the bold sat around the whole phrase instead of around the second number"* is checkable by
+a reader and invisible to a pattern; the same sentence with the digits in it is a live claim.
 
 **3. Every fact has exactly one home.** Other documents link to it; they never restate
 it. Two homes do not disagree on the day they are written — they disagree on the day one

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

@@ -31,6 +31,9 @@ elsewhere and is not restated here:
 - Anatomy of a project gate
 - Writing the check itself
 - Probing — plant, run, restore
+- A probe rots, and every way it rots reports green
+- A ratchet prices the rule, not the exception
+- Run the whole suite locally before you push the tag
 - The neighbour probe — plant the evidence outside the subject
 - A ratchet's matcher is itself a check, and it needs a near-miss
 - A green probe is evidence only if the mutation is known to have landed
@@ -385,6 +388,95 @@ Otherwise the next reader has to redo it to know whether it was ever done.
 
 ---
 
+## A probe rots, and every way it rots reports green
+
+The three assertions above prove a probe works **today**. They say nothing about the
+day after, and a probe is uniquely exposed: the thing it guards is the thing that moves
+it. Four rotted in one release on 2026-08-22, and none of them failed loudly — two
+reported `caught`, two reported nothing at all.
+
+**1. The anchor is a literal the guarded thing moves.** A probe pinned to *"the bundle
+is N reference files"* stops landing the day a reference file is added — on the release
+that changes the very number it guards. Same for a version, a count word, a phrase a
+release rewrites. **Derive the anchor**: read whatever the text currently says and make
+*that* wrong. A probe that computes `wrong = stated - 1` never needs maintaining.
+
+**2. The precondition is inherited from the tree rather than created.** This is the
+subtle one, because it is triggered by the system working correctly. A probe that
+narrows a declared gap to expose *releases after the newest run stamp* has nothing to
+expose the moment a release writes an honest stamp — the newest release is now the
+newest stamp. A probe requiring an `## Unreleased` section has none the moment a release
+absorbs it. **Both landed. Both proved nothing.** A probe must construct the state it
+needs: remove the stamp, write the section, then plant the defect.
+
+**3. The document quotes the form the probe removes.** Covered as
+[`documentation.md`](documentation.md) canon 2's second half, and it belongs here too
+because the probe is where it surfaces: prose describing the wrong shape *with real
+values in it* is a second instance of the shape. The probe deletes the real one, the
+narrative still matches, the guard is silent.
+
+**How to see it before CI does.** Ask one question per probe: *what does this probe
+LOOK FOR, and who is allowed to change it?* Where the answer is "the thing it guards",
+it is rotting already. A repository-wide sweep is one grep — a two-digit literal inside
+a needle, an `assert` or a `replace` — and the triage is: the number a probe **writes**
+is correct, the number it **looks for** is the defect.
+
+## 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.
+
 ## The neighbour probe — plant the evidence outside the subject
 
 A probe proves a guard rejects **the phrasing its author had in mind**. That is less than

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

@@ -71,6 +71,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | What a spec must lock, the UX-track order, the module dossier | `references/spec.md` |
 | The zero-context plan format, parallel groups, set equality | `references/planning.md` |
 | The work graph: its fields, the verbs and their exit codes, and the three invariants a schema cannot state | `references/work-graph.md`, `scripts/graph.py`, `graph.schema.json` |
+| How a node is CLOSED: three blind readings at escalating visibility, all three required, and the round ledger the ceiling reads | `references/certification.md`, `agents/verifier-{unit,seam,product}.md`, `scripts/graph.py certify` |
 | Workspace isolation, the subagent loop, who may write the register | `references/build.md` |
 | The review rubric, diff packages, the three verdicts | `references/review.md` |
 | **False success** — the class, its known shapes and its two rules | `references/gates.md` |

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

@@ -273,6 +273,12 @@ never that the work was skipped quietly.
   `next` refuses to walk one. The reason to prefer it over a prose plan is measured, not
   aesthetic: a 400-node graph and a 4-node graph produce the same 27-byte frontier, so the
   cost of knowing what is next does not grow with the programme.
+- **And the check is what THREE readings will run, not one**
+  ([`certification.md`](certification.md)). A node is closed by `unit`, `seam` and `product`
+  reports, dispatched blind and in parallel, and `certify` refuses the close until all three
+  pass. That is a planning fact, not only a verification one: a node whose blast radius nobody
+  can name is a node the seam and product tiers cannot scope, so `touches` and `serves` are
+  what make the two outer readings possible at all.
 - **The queue exists here, so the loop arms here** ([`continuity.md`](continuity.md) →
   *Part 1a*). Where `run.loop.arm` is `after-decomposition` and the map holds more than
   one module, arm the mode at the close of this stage and print one line: the mode, and

package/plugins/task-pipeline/skills/task-pipeline/references/work-graph.md

@@ -59,6 +59,7 @@ conditional on the code, never merely sequenced after it.**
 | `goal` | the release goal | `0` · `3` unstated |
 | `add` | the id it allocated | `0` · `1` refused |
 | `park` | the id and the reason | `0` · `1` refused |
+| `certify` | the round, and on a failure every `breaks` finding with its fix and its check | `0` all three tiers passed · `1` a tier failed, or a report is malformed |
 | `close` | the goal, the new frontier count, and what was not verified | `0` · `1` refused **or the verdict stops the run** |
 | `producer` | what produced this proof — actor, model, runtime, skill, config, commit, trace | `0` |
 | `doctrine` | how many of the bundle's reference files this run opened | `0` |
@@ -77,6 +78,8 @@ A **`parked`** node is the single exemption: it is the one node nobody will clos
 *n/a — parked* in that field is confidence without correctness. `park` never removes what
 the node said it would run.
 
+**A node is closed by three readings, not one.** `certify` takes one tier report from each of `unit`, `seam` and `product` — dispatched blind and in parallel — requires all three to pass, and assembles the seven-key verdict `close` consumes. `close`'s contract is unchanged; what changed is that the verdict is now built from three readings at different distances instead of written from one, because a change can be correct where it was made and wrong one level out. A failing round records itself and leaves the node open. Doctrine: [`certification.md`](certification.md).
+
 **`close` stamps the commit; the verifier never supplies it.** A verdict written after the
 tree moved is evidence about a different tree, and an agent cannot name the wrong commit if
 it is never the one naming one.