task-pipeline-skill 1.68.0 → 1.69.0

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

@@ -82,9 +82,10 @@
               "enum": [
                 "module-map",
                 "plan-tasks",
+                "work-graph",
                 "none"
               ],
-              "description": "What the loop walks. A loop with no queue is a timer: it says how often to continue and never what the next item is, so the run picks its next move by recollection. module-map = stage 2's decomposition (a platform); plan-tasks = stage 4's task list; none = the mode is armed for the stage boundaries only. Doctrine: references/continuity.md -> Part 1a."
+              "description": "What the loop walks. A loop with no queue is a timer: it says how often to continue and never what the next item is, so the run picks its next move by recollection. module-map = stage 2's decomposition (a platform); plan-tasks = stage 4's task list; none = the mode is armed for the stage boundaries only. Doctrine: references/continuity.md -> Part 1a. `work-graph` is `.task-pipeline/graph.json`, walked by `scripts/graph.py next`; doctrine: references/work-graph.md."
             },
             "arm": {
               "enum": [
@@ -145,6 +146,15 @@
             "minLength": 1
           },
           "description": "Post-release smoke checks that must pass after a release — this is the release's own post-deploy gate (stage 8 applied to shipping the package itself)."
+        },
+        "goal": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What this release is for, in one sentence. Printed beside the queue on every loop iteration so drift from it is visible rather than remembered, and a node serving neither it nor a REQ is parked WITH THAT AS THE REASON. Declared here because the guard that validates this config could not otherwise see the field: `additionalProperties` is true, so an undeclared `goal` could be renamed away and every gate would stay green (found by the wave-2 convergence check)."
+        },
+        "_goal_note": {
+          "type": "string",
+          "description": "Free prose beside `goal`."
         }
       }
     },
@@ -195,16 +205,49 @@
             "type": {
               "enum": [
                 "auto",
+                "judgment",
                 "manual"
               ],
-              "description": "auto = the orchestrator verifies `check` itself (pass/fail); manual = wait for the operator's explicit go."
+              "description": "auto = the orchestrator verifies `check` itself, pass/fail — a fact a MACHINE established. judgment = there is no complete deterministic check and someone rules on it; the ruling is recorded AS judgement and never as a measurement, and the gate must name its `judge`. manual = wait for the operator's explicit go. Two types were not enough: a reviewer's ruling, a check that scenarios are coherent and a verdict that a mockup is good all rode in `auto`, indistinguishable from an exit code — so a coverage table could not tell a measured row from an opinion."
             },
             "check": {
               "type": "string",
               "minLength": 1,
               "description": "The gate condition, in prose."
+            },
+            "judge": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "\\S",
+              "description": "Who or what renders the judgement — a role, an agent, a person. Required when `type` is `judgment`. Without it the ruling has no author, and a judgement whose author is unknown cannot be weighed against its independence: this pipeline's own `R-005` reader shares a model and a repository with the author it reviews, which is a different kind of evidence from a deterministic runner. Naming the judge is what makes that difference visible."
             }
-          }
+          },
+          "allOf": [
+            {
+              "if": {
+                "properties": {
+                  "type": {
+                    "const": "judgment"
+                  }
+                },
+                "required": [
+                  "type"
+                ]
+              },
+              "then": {
+                "required": [
+                  "judge"
+                ],
+                "properties": {
+                  "judge": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S"
+                  }
+                }
+              }
+            }
+          ]
         }
       }
     },

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

@@ -188,6 +188,42 @@ A REQ whose evidence lives in an unpushed commit, or in a submodule the parent
 doesn't point at yet, is `partial` — the evidence is not reachable by anyone but
 you.
 
+### The pointer is not the path — and the pointer check alone was the whole gate
+
+Everything above proves **commits**: the parent points at the child's newest one, every
+repository is clean, nothing is unpushed. None of it proves anything *works* at those two
+versions together. A parent can point at a green submodule whose contract the parent's own
+code calls with the previous signature, and every check in this pipeline passes — the
+child's suite ran against the child, the parent's against the parent, and **no check ran
+across the pointer**. Neither repository looks wrong alone, which is why this survived
+being written down twice.
+
+So the criterion has a second half, and it fires **only where a component pointer moved in
+the range being accepted**. A range that crossed no component boundary has no seam to
+prove, and demanding a record for it is how a gate becomes noise.
+
+Where one moved, the acceptance owes three things:
+
+1. **One named cross-component path** — a command, a test, a request, a scenario that
+   traverses both sides. Not each side's suite.
+2. **The exact versions it observed**, one per component: the commit the *parent pins*,
+   not whatever happens to be checked out. Those are the same fact only while they agree,
+   and they disagree in precisely the case this exists for.
+3. **The observation, to the same standard a single REQ meets** — the command and what it
+   printed, in `docs/evidence/convergence.md`.
+
+`templates/convergence.sh` mechanises the pointer half and requires the record for the
+seam half. It also checks the one thing `git submodule status` cannot see: **whether the
+pinned commit is published at all.** Measured here on 2026-08-16 — a release tag failed CI
+at checkout because the parent pinned a commit that existed only on one machine, and
+`git submodule status` showed no `+` because the pointer matched the *local* head.
+
+| Rationalization | Why it is wrong |
+|---|---|
+| *"Both suites are green, so the release is green."* | Each suite ran against one side. The defect lives in the seam, and no suite has an opinion about it |
+| *"The pointer is at the newest commit, so it is current."* | Current and *published* are different facts. A clone gets what the remote has |
+| *"I ran the cross-component check, it passed."* | Then say which versions it observed. A record citing no version cannot say which composition it proved |
+
 ## The closing question
 
 The table is preparation. The stage exists for the question that follows it, asked

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

@@ -329,7 +329,7 @@ beside the verdict**:
 ```
 GATE 6 tests: PASS — full suite green (247 tests)
   carry-over: 4 open (was 6) · unresolved: 0 · audit findings deferred: 2
-  abstained: 1 (1 cannot-verify) · unlooked: 2 dormant
+  abstained: 1 (1 cannot-verify) · unlooked: 2 dormant · holds: 1 (container: pg-test, this run)
 ```
 
 The difference from a TODO is not bookkeeping. A TODO is invisible until somebody

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

@@ -70,7 +70,15 @@ often* to continue and never said *what the next item is*, so the mode could be
 and still leave the run picking its next move by recollection — which is the failure
 [`learned.md`](learned.md) rule 16 is about, running once per fire.
 
-**The queue is the module map** ([`decomposition.md`](decomposition.md)) when the brief
+**Where a work graph exists it is the queue** ([`work-graph.md`](work-graph.md)):
+`.task-pipeline/graph.json`, walked by `scripts/graph.py next`, which prints the runnable
+nodes and nothing else. It is preferred over the two below for one measured reason — 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. `run.loop.queue: work-graph` records it, and
+`next`'s exit codes are what the loop branches on: `3` is *every node is done*, `4` is
+*what remains is blocked or parked*, and those are different endings.
+
+**Otherwise the queue is the module map** ([`decomposition.md`](decomposition.md)) when the brief
 was a platform, and the plan's task list otherwise. Both already exist and both are
 already ordered; neither was ever named as the thing the loop walks.
 

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

@@ -89,6 +89,23 @@ side, so it never surfaces by comparison. Carry it as a named, counted set next
 verdict — a ratchet, never a TODO — so `PASS` reads as *"green, and here is what nobody
 looked at"*. → [`learned.md`](learned.md) rule 7; [`gates.md`](gates.md) → *Ratchets*.
 
+**9a. A measured zero and an unmeasured quantity may not print the same.** Canon 9 says
+carry the absence; this says **refuse the number** when nothing measured it. `0 of 34
+files read` and *the recorder was never installed* are opposite facts, and a `0` claims
+the first while meaning the second — the most reassuring answer available, derived from
+an instrument nobody switched on. So the unmeasured case prints a word, and the word says
+why it cannot be a number.
+
+The rule is written down because it arrived three times under three names before anyone
+named it: `references/knowledge-graph.md` → *State zero out loud* (a fresh graph must
+still print `current, 0 commits behind`, or freshness is indistinguishable from a harvest
+that never looked); `references/verification.md` → *Staleness* (`unanchored` and
+`unresolvable` are states, not zeroes); and `scripts/graph.py` → `doctrine`, which prints
+`unmeasured` and its reason rather than `0 of 34`, and `next`, which reports how many
+runnable nodes declared no `touches` so that no collision is not read as no collision
+found. Three sites, one rule, and the fourth will be written from this line rather than
+from the same mistake.
+
 **10. The document ships in the change that made it true.** Not in the next ticket —
 documentation deferred is documentation that describes a system nobody is running. A
 correction is **appended**, never edited over: a register that is rewritten loses the

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

@@ -22,6 +22,7 @@ elsewhere and is not restated here:
 ## Contents
 
 - Axis A — the stage gate type
+- The judgment gate — a ruling is not a measurement
 - Axis B — the enforcement mechanism
 - Axis C — degrees of freedom
 - Progressive arming
@@ -49,6 +50,7 @@ From [`../pipeline.schema.json`](../pipeline.schema.json), one per stage:
 | Type | Meaning | Failure to respect it |
 |---|---|---|
 | `auto` | the orchestrator verifies the `check` itself, pass/fail, and stops on fail | advancing on an unverified check |
+| `judgment` | somebody **rules** on it, because no complete deterministic check exists; the gate names its `judge` | recording the ruling in the slot reserved for what a machine established |
 | `manual` | wait for the operator's **explicit** go | treating an auto verification as the approval |
 
 **An auto gate never substitutes for a required manual approval.** A green table is
@@ -56,6 +58,49 @@ not the operator confirming it is what they asked for, and no amount of checking
 makes it one. Which stages are manual is the **operator's** decision, recorded in
 their `pipeline.json`; the framework fixes no stage count and no gate assignment.
 
+## The judgment gate — a ruling is not a measurement
+
+Two types were not enough, and the gap was not cosmetic. A reviewer's ruling, a check that
+the scenarios are coherent, a verdict that a mockup is good — none has a complete
+deterministic check, and all three rode in `auto`, **indistinguishable from an exit code**.
+A coverage table then cannot tell a measured row from an opinion, and the role-agent
+programme multiplies the problem: `reviewer`, `ux`, `ui` and `market-analyst` produce
+judgement by design.
+
+`auto` now means only what a machine established.
+
+**The precedent already existed in miniature, and this generalises it rather than
+inventing it.** [`templates/verification.md`](../templates/verification.md) already turns a
+coverage verdict of `review` into `none` in the `Auto` column — because that column records
+what a machine established, and a review is not that. That rule, applied to one column, is
+the `judgment` type in one instance.
+
+Three obligations, and the third is the one that bites:
+
+1. **It names its `judge`** — a role, an agent, a person. The schema refuses the gate
+   without one. A ruling with no author cannot be weighed for independence, and
+   independence is not a property of *having* a reviewer: this pipeline's own `R-005` reader
+   shares a model, instructions and repository with the author it reviews, differing only in
+   context. That is a real second reading and it is **not** a deterministic runner, a
+   contract at another boundary, or an external system. Naming the judge is what makes the
+   difference visible instead of assumed.
+2. **The verdict is recorded as judgement**, in the artifact that quotes it — never
+   promoted to a pass in a column that means *a machine established this*.
+3. **It may not stand in for a `manual` gate.** A judgement can be rendered by an agent; an
+   *authorisation* cannot. Anything outward, irreversible, or costing money stays `manual`
+   however confident the judge.
+
+**Which of this pipeline's own gates are judgement is deliberately not decided here.**
+Gate assignment is the operator's call and the framework fixes none — so shipping a
+reclassified stage list would contradict the sentence above it. The type exists; the
+project chooses where it applies.
+
+| Rationalization | Why it is wrong |
+|---|---|
+| *"The reviewer approved it, so the gate passed."* | It did — as a judgement. Type it as one, or the table claims a machine agreed |
+| *"A second agent checked it, so it is independent."* | Independence is a different **evidence path**, not a second reader. Name the judge and the difference is visible |
+| *"There is no check for this, so it has to be `manual`."* | `manual` waits for a person's authority. `judgment` records a ruling. Collapsing them puts a human in the loop for everything that is merely hard to measure, which is how an operator learns to route around the pipeline |
+
 ## Axis B — the enforcement mechanism
 
 Where a rule actually lives. A rule climbs this ladder; it does not start at the top.
@@ -448,7 +493,7 @@ A **ratchet** is a named, counted set that may only shrink, printed on every run
 
 ```
 GATE 9 docs: PASS — propagation backlog: 121 (was 162) · unmarked residue: 0
-  abstained: 0 · unlooked: 4 (3 dormant · 1 skip — no submodules in this repo)
+  abstained: 0 · unlooked: 4 (3 dormant · 1 skip — no submodules in this repo) · holds: 0
 ```
 
 A ratchet nobody prints is a TODO with a better name.

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

@@ -70,6 +70,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | Cutting a platform into modules, brick criteria, build order | `references/decomposition.md` |
 | 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` |
 | 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/progress.md

@@ -163,11 +163,31 @@ PROGRESS    where the run stands against that request: gates passed,
 DONE        what was solved this iteration, each with its evidence
 SURFACED    what came up that nobody asked for — findings, corrections,
             things that turned out to be other than assumed
+SCOPE       what this claim covers: the commit, the environment, the REQ
+            ids, the surfaces — the validity domain, not the ambition
+NOT VERIFIED what was built and NOT checked, or could not be. The literal
+            `none within the stated scope` is a valid answer; an empty
+            field is not
 
 DECISIONS WAITING  <n>   each as a question with options, asked HERE
 AMBIGUITIES        <n>   computed, below
 ```
 
+**`SCOPE` and `NOT VERIFIED` are the two the block lacked, and their absence had a
+shape.** Every gate already computes exactly what `NOT VERIFIED` needs — `abstained` for
+claims the run declined to make, `unlooked` for checks that did not look — and none of it
+reached the artifact an operator actually reads. So a run could hand back a report honest
+sentence by sentence and still be **indistinguishable from a run whose checks never
+looked**, which is the failure this file names three separate times.
+
+`NOT VERIFIED` is **populated from those disclosures rather than composed**: it is the
+`abstained` and `unlooked` sets in words, plus anything built this iteration that no check
+touched. Composing it by hand is how it becomes a summary of the parts somebody remembered.
+
+And `none within the stated scope` is a claim with a subject — it says *nothing inside
+what SCOPE names is unverified*. Leaving the field empty says nothing at all, which reads
+as the same thing and is not: canon 9a, one artifact over.
+
 **Where there is no brief** — `checkup`, `setup`, a short path — TASK quotes the
 operator's own sentence instead, marked as such. An unquotable TASK is a run that cannot
 say what it was asked, which is worth its own line.
@@ -338,6 +358,27 @@ of the command the project declared in `pipeline.json` → the tests stage's
 `gate.command`. The rail does not read it — a glyph still comes from the verdict —
 but the stage-7 release gate requires the claim and the observation to agree.
 
+**The same shape, one axis over — `read:`.** Since v1.69.0 a `PostToolUse` hook on `Read`
+appends
+
+```
+read:  references/<file>.md
+```
+
+deduplicated, and always exiting 0 — a hook that can fail a `Read` breaks every turn in
+every session. `scripts/graph.py doctrine` reports how many of the bundle's reference files
+a run opened and lists the rest.
+
+Why it is hook-written is the same reason as above: a claim about what somebody read,
+written by the party the claim is about, is not evidence. And why the verb prints
+`unmeasured` rather than `0` when there are no such lines is the same reason again — the
+hook being absent and the run reading nothing are **opposite facts** the ledger cannot
+separate, so it claims neither. A `0` there would be the reassuring answer to a question
+nobody asked, over 34 files nobody checked.
+
+It is a disclosure: no floor, no direction, never a target. The moment the number becomes
+something to raise, a run will open files to raise it.
+
 The reason is the one this whole file is about, arriving one level down. A rail
 written from memory is a summary that is confidently wrong exactly when it matters;
 a gate that reads a verdict typed by the agent it constrains is the same shape

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

@@ -262,6 +262,14 @@ never that the work was skipped quietly.
   its status, in build order with the walking skeleton first. Single-module work
   records `single module: <name>` in the design and moves on — a skipped
   decomposition is a decision, never an omission.
+- **Where the queue is a work graph, it is WRITTEN here**
+  ([`work-graph.md`](work-graph.md)): `.task-pipeline/graph.json`, carrying the frozen REQ
+  ids so `serves` resolves, one node per unit of work with its owner and what it touches,
+  and an edge per dependency **naming what it hands over**. Then
+  `python3 scripts/graph.py validate` — a graph that does not validate is not a queue, and
+  `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.
 - **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
@@ -269,7 +277,9 @@ never that the work was skipped quietly.
   (`dynamic`). Arming collapses no gate and authorizes no outward act; it decides only
   that the run does not stop to ask *"shall I take the next one?"*. Single-module work
   arms nothing and says so — a loop with one item is a timer.
-- **GATE (manual):** the user approves the design, the UI verdict is recorded,
+- **GATE (manual):** the user approves the design, the UI verdict is recorded, **the
+  queue is an artifact rather than a recollection** — where it is a work graph,
+  `graph.py validate` exits 0 and `graph.py coverage` names any requirement no node serves,
   **every REQ is answered by the design** — a requirement the design doesn't
   address is either covered now or explicitly dropped by the operator, with the
   drop recorded in the carry-over ledger — **and, for a platform, the module map is

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

@@ -22,6 +22,7 @@ the run*. Three things it does not say, and each is why this file exists:
 
 - Why it keys to the brief, not to the coverage table
 - `never` is a fact
+- Staleness — the other end of `never`
 - A ledger records two different things, and most record only one
 - What stage 8 writes and what stage 10 refuses
 - Rationalizations
@@ -54,6 +55,57 @@ So the count has **no floor, no direction, and may never be given a target**, ex
 like the disclosures in [`gates.md`](gates.md). A project with forty `never` rows is not
 failing; it is a project that now knows something it could not previously ask.
 
+## Staleness — the other end of `never`
+
+This file tracked rows nobody had ever confirmed and had **no notion of a row whose
+confirmation the tree has overtaken.** A row verified at commit A read `verified` after
+commit B, forever. Those are the same failure from two ends, and only one end was
+instrumented — which is why a ledger could read fully green over a tree where every check
+ran against code that has since moved.
+
+`Observed at` is the commit the check ran against. `scripts/exposure.sh` reports four
+states from it, and the whole thing is a **port**: `references/knowledge-graph.md` already
+gives the code graph a stamp, a distance and three states, and every non-current one ends
+in a marker. The same contract, applied to the ledger.
+
+| State | Condition | Reads |
+|---|---|---|
+| **current** | 0 commits behind `HEAD` | still speaks about this tree |
+| **behind** | N commits / M days behind | *not trusted for the current tree until re-observed* |
+| **unresolvable** | the commit does not resolve here | rebase, squash, shallow clone — same marker |
+| **unanchored** | no commit recorded | nothing can say what it saw |
+
+**It is a disclosure: no floor, no direction, never a target** — the same contract the
+`Human` column has, and for the same reason. A threshold on staleness teaches a run to
+re-observe rows for the counter rather than for the question.
+
+**`behind` means unproven for this tree, never wrong.** The section knows the distance and
+does not know whether the commits in between touched anything the row covers. Claiming
+more than that would be the estimate-printed-as-measurement this pipeline refuses
+elsewhere.
+
+**State zero prints out loud.** `current 12 · behind 0 · unresolvable 0 · unanchored 0` is
+a measurement; printing nothing when everything is fresh makes freshness indistinguishable
+from a check that never looked.
+
+**Invalidation is not deletion.** An overtaken row is not wrong — it is true about the tree
+it observed, and it stays. Re-observing **appends** a row; it never edits the old one. Four
+things overtake a row, and the note says which applies: a **code** change in what it
+covers, a **dependency** change, an **environment** change, and a **policy** change — the
+rule under which the evidence was accepted.
+
+**Where the section prints matters as much as what it prints.** It runs *before* the
+check-list, because `exposure.sh` exits early when nothing is unverified — and that is
+exactly the state where these counts matter most. `0 unverified` is the sentence most
+likely to be read as *nothing to look at*, and a staleness section invisible behind it
+would have been dormant precisely when it was needed.
+
+| Rationalization | Why it is wrong |
+|---|---|
+| *"The row says `pass`, so it passes."* | It passed against a tree. Name which one, or the claim has no subject |
+| *"Everything is behind, so the number is noise."* | Then it is a large honest number. A threshold would make it a small dishonest one |
+| *"I re-ran the check, so I will update the row."* | Append. The old row is true about what it saw, and overwriting it destroys the only record of when the claim was earned |
+
 ## A ledger records two different things, and most record only one
 
 **What confirmed it** and **whether a person looked** are separate facts. The first is

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

@@ -0,0 +1,121 @@
+# The work graph — the queue a script walks so the model never reads it
+
+**One job: hold what is left to do, in a form whose cost does not grow with the
+programme.**
+
+A plan is prose. A prose plan for a real release is hundreds of lines, and a model that
+re-reads it every iteration spends its context on ground it has already walked — so the
+cost of knowing *what is next* rises with the size of the work, which is exactly backwards.
+
+`.task-pipeline/graph.json` is the same information as a typed graph, and
+[`scripts/graph.py`](../scripts/graph.py) answers one question against it: **which nodes are
+runnable right now.** What enters a context each iteration is then bounded by the
+**frontier's width**, not by the graph's size.
+
+Measured on this build: a 400-node graph (51 KB) and a 4-node graph produce the same
+**27-byte** frontier. That property is the whole reason the file exists, and it is why
+`next` prints the frontier and nothing else — anything else printed there is paid on every
+turn of every loop.
+
+---
+
+## Contents
+
+- What is in it, and what each field is for
+- The verbs, and their exit codes
+- The three things a schema cannot state
+- What it deliberately does NOT do
+- Rationalizations
+
+## What is in it, and what each field is for
+
+`graph.schema.json` is the contract; this is why each part is there.
+
+| Field | Why |
+|---|---|
+| `goal` | echoed from `pipeline.json` → `release.goal`, so the graph carries the thing it serves rather than pointing at a file that may have moved on |
+| `requirements` | the REQ ids the brief froze. **`serves` resolves against these** — without them it was a non-empty string and nothing more, and that field is the one edge joining the intent graph to this one |
+| `goal_clauses` | release work no requirement names. Enumerated, never matched against the goal's prose: substring-matching a sentence produces confidence without correctness |
+| `nodes[].owner` | which role does it. A node nobody can dispatch never leaves the frontier and nothing says why |
+| `nodes[].serves` | the REQ or goal clause it exists for. A node serving neither is **parked with that as the reason** |
+| `nodes[].blocked_by` | what must close first. This is what the frontier obeys |
+| `nodes[].touches` | what it **mutates**. Two runnable nodes writing one file is the false parallelism [`planning.md`](planning.md) refuses — *distinct is not the same as independent, and the check is what they touch, never what they are called* |
+| `nodes[].evidence` | required when `status` is `done`. A node called done by assertion is what evidence exists to prevent |
+| `nodes[].parked_reason` | required when `status` is `parked`. A park with no reason is indistinguishable, a week later, from work quietly dropped |
+| `edges[].payload` | what the dependency hands over. **An edge carrying no named artifact is chronology drawn as architecture** |
+| `revisions` | why the graph is not the graph stage 2 wrote. A graph that changed for reasons nobody recorded can explain its own completion by appealing to a plan that existed only at the end |
+
+## The verbs, and their exit codes
+
+Exit codes are the contract, per standing instruction `R-004`: **the next command is
+conditional on the code, never merely sequenced after it.**
+
+| Verb | Prints | Codes |
+|---|---|---|
+| `validate` | every violation, in a stable order | `0` clean · `1` any |
+| `next` | the frontier, ordered by how much each node unblocks — **and nothing else** | `0` printed · `3` all done · `4` nothing runnable |
+| `coverage` | each requirement with the nodes serving it | `0` covered · `1` a gap, named |
+| `goal` | the release goal | `0` · `3` unstated |
+| `add` | the id it allocated | `0` · `1` refused |
+| `park` | the id and the reason | `0` · `1` refused |
+| `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` |
+
+**`next` is ordered by what each node unblocks, transitively, and the number is computed.**
+A `priority` field is something somebody typed once and nobody revisits; this one moves when
+the graph does. Ties break on declaration order, so the frontier is stable between runs —
+an unstable one costs more than it looks, because an agent calling `next` twice starts the
+other node.
+
+**`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.
+
+**A stop closes its node and refuses the next step.** `replan.possible: false` says the run
+cannot continue *around* what it found — not that the work just verified did not happen.
+
+## The three things a schema cannot state
+
+The split is where the format actually puts it, which is not where the first draft drew it.
+`graph.schema.json` states everything JSON Schema can, including `done → evidence` and
+`parked → parked_reason` — the first version claimed those were beyond it and was wrong.
+
+What genuinely cannot be expressed is cross-document and cross-node, and lives in
+`violations()`:
+
+1. **Whether `owner` names a role that exists** — with a near-miss hint, because an agent
+   told only *no* will try a synonym.
+2. **Whether `serves` resolves**, and whether every `blocked_by` and edge end is in the
+   graph at all.
+3. **Whether the edges cycle** — the one failure of this design that looks exactly like slow
+   progress: a frontier can be non-empty forever while nothing is runnable.
+
+And one more that is not about expressiveness: **the schema is never applied to a live
+graph.** `graph.py` is stdlib-only by design, so `violations()` also enforces the rules the
+format states — because a rule checked only against the shipped example is a rule the run
+does not have.
+
+## What it deliberately does NOT do
+
+- **It is not committed.** `.task-pipeline/graph.json` is a run artifact. That is a live
+  tension, not a settled question: a graph deleted with its run cannot be inspected
+  afterwards, and `docs/evidence/backlog.md` carries it rather than this file pretending it
+  is resolved.
+- **It does not decide the module map.** Stage 2 does ([`decomposition.md`](decomposition.md));
+  the graph is where that decision becomes walkable.
+- **It does not schedule.** `next` says what *may* run. Whether two runnable nodes are
+  dispatched together is the dispatcher's call, and the collision warning on stderr is what
+  that call is made against.
+- **It does not read like a plan.** If you want to know why the work is shaped this way, the
+  brief and the spec say so. The graph says what is left.
+
+## Rationalizations
+
+| The excuse | Why it is wrong |
+|---|---|
+| *"I'll just read the graph, it's only forty nodes."* | Forty is the number today. The property being protected is that four hundred costs the same, and it stops being true the first time the model reads the file |
+| *"The frontier is short; one extra line won't matter."* | It is paid on every iteration of every loop. That is what *the frontier and nothing else* means |
+| *"`blocked_by` already says the dependency, the edge is bookkeeping."* | The edge carries the **payload**. A dependency handing over nothing named is the fake edge with a field around it |
+| *"I'll add the node now and record why later."* | Later is the run that cannot say why its plan changed, which is the run whose completion claim cannot be falsified |
+| *"The graph validates, so the mutation was fine."* | `validate` is stdlib and the format is richer. Both were made to agree once, and the disagreement returned within a day — check the two against each other, not the result against one |