task-pipeline-skill 1.68.0 → 1.69.0

package/README.md

@@ -109,6 +109,30 @@ stage and walks the gates. See [Install](#install) for the other channels.
 
 ---
 
+## What this implements
+
+`task-pipeline` is the reference implementation of **Proof of Done: The Agentic
+Software Development Manifesto** by Sergey Sheleg — *a foundation for building
+software when agents write the code*. The manifesto has its own home:
+<https://github.com/ssheleg/pod-manifesto>.
+
+Its central claim is that the unit of progress is not generated code but an
+**evidence-carrying change**: one carrying the intent it implements, the evidence that
+verifies it, the **limits** of that evidence, and the decision that accepts it. This
+repository is where that stops being an argument — the ladder walk in
+[`references/acceptance.md`](plugins/task-pipeline/skills/task-pipeline/references/acceptance.md),
+the eight residue classes in
+[`references/residue.md`](plugins/task-pipeline/skills/task-pipeline/references/residue.md),
+the axis rotation in
+[`references/audit.md`](plugins/task-pipeline/skills/task-pipeline/references/audit.md),
+and a guard suite in which **every** check has been watched rejecting a planted defect
+(`npm run test:negatives`).
+
+What the manifesto names and this repository has **not** built yet is filed open in this repository's evidence backlog
+(<https://github.com/ssheleg/task-pipeline/blob/main/docs/evidence/backlog.md>)
+rather than described as shipped — `package.json` ships the skill, not the
+ledgers, so the link is the repository's rather than the package's.
+
 ## What makes it different
 
 ### Everything is built in — zero required dependencies
@@ -129,6 +153,7 @@ until it is installed.
 | 2 Decompose | [`decomposition.md`](plugins/task-pipeline/skills/task-pipeline/references/decomposition.md) — platforms only: brick criteria, module map, build order |
 | 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 |
 | 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.68.0 |
+| **Version** | 1.69.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/bin/task-pipeline.js

@@ -79,6 +79,35 @@ function installOne(label, src, dest, isDir, force) {
  * failing: an installer that ends in an error because an OPTIONAL follow-up is
  * missing reads as a failed install.
  */
+/**
+ * Say what this path does NOT install, and what runs instead.
+ *
+ * `agents/` is a Claude Code plugin capability; `install()` copies the skill directory
+ * and the command and nothing else. That is the design — the brief chose plugin agents
+ * with honest degradation — and it was silent, which is the part that is not. An
+ * operator reading doctrine that names `task-pipeline:verifier` finds a name that
+ * resolves to nothing and no explanation anywhere in what they ran.
+ */
+function discloseAgents() {
+  const dir = path.join(ROOT, 'plugins', 'task-pipeline', 'agents');
+  let files = [];
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+  } catch (e) {
+    return;               // no agents shipped: nothing to disclose
+  }
+  if (!files.length) return;
+  console.log(
+    `\nNot installed: plugins/task-pipeline/agents/ (${files.length} file(s)).\n` +
+    '  Role agents are a Claude Code plugin capability; this path installs the skill\n' +
+    '  and the command only. Every role still runs — on the main thread instead of in\n' +
+    '  its own context, which costs context and speed, not doctrine.\n' +
+    '  For the agent-backed version, install the plugin:\n' +
+    `    claude plugin marketplace add ${REPO}\n` +
+    '    claude plugin install task-pipeline@task-pipeline'
+  );
+}
+
 function offerRouters() {
   const { spawnSync } = require('child_process');
   const r = spawnSync(
@@ -206,6 +235,7 @@ Rerun with --force if you deliberately want the plain copy instead.`);
     false,
     force
   );
+  discloseAgents();
   offerRouters();
   return 0;
 }

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.68.0",
+  "version": "1.69.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",
+    "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:negatives": "python3 test/negatives.py",
+    "test:exposure": "python3 test/exposure_test.py",
     "test:probe": "python3 test/probe.py --self-test",
-    "test:all": "python3 test/validate.py && python3 test/negatives.py && npm run test:probe && npm run test:hooks && npm run test:artifacts && npm run test:docs",
     "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"

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.68.0",
+  "version": "1.69.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -0,0 +1,88 @@
+---
+name: verifier
+description: Closes one node of the work graph. Reads the diff, the node's REQ and the gate output, and returns a seven-key verdict — what is done with the evidence for each claim, what is not, the blockers and whether the run can continue around them, and a re-plan. Use when a task in a task-pipeline run has finished and the graph needs to advance. Not for reviewing code quality — that is the reviewer.
+model: inherit
+tools: Read, Grep, Glob, Bash
+---
+
+# Verifier — accept the work, or say precisely what is missing
+
+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.
+
+## Why you are a separate context
+
+The diff, the test output and the node's requirement are voluminous; the verdict is
+small. The main thread needs the **verdict**, not the diff — that is the entire
+reason you exist as an agent rather than as a paragraph the dispatcher reads. Keep
+your reading here and return the summary.
+
+## What you cannot do, and it matters
+
+**You cannot ask the operator anything.** Your report reaches the dispatcher, never
+the human. So a verdict that means *«I need a decision»* must say so **in the
+verdict** — `replan.possible: false` with the `why` written for a person — rather
+than ending in a question nobody will see.
+
+## The verdict, and all seven keys are required
+
+```json
+{
+  "node": "N-007",
+  "done":         ["what was asked and is now true"],
+  "not_done":     ["what was asked and is not"],
+  "not_verified": ["what was BUILT and no check touched"],
+  "blockers":     [{ "what": "…", "blocks": ["N-009"], "can_continue_around": true }],
+  "replan":       { "possible": true, "add": [], "park": ["N-009"], "why": "…" },
+  "evidence":     ["the command and the output that proves each `done` row"]
+}
+```
+
+**`not_verified` is the one people collapse into `not_done`, and they are different
+facts.** `not_done` is *asked for and absent*; `not_verified` is *present and unchecked* —
+the second ships and the first does not. An empty list is a valid answer and silence is
+not.
+
+**You do not supply the commit.** `close` reads `git rev-parse HEAD` itself and appends it
+to the evidence, because a verdict written after the tree moved is evidence about a
+different tree, and an agent cannot name the wrong one if it never names one.
+
+`scripts/graph.py close --verdict <path>` refuses it otherwise, and the refusal names the
+key. The rule with teeth is the smallest one: **a `done` claim with an empty `evidence` is
+rejected.** Not as bookkeeping — it is the difference between a node that was
+verified and a node that was asserted, and the assertion is the failure this whole
+ledger exists to catch.
+
+## How to reach each field
+
+1. **Read the node's `serves`** — the REQ or the goal clause. That is the standard.
+   Not what the diff does; what was asked.
+2. **Run the checks the task named.** Not a check you invented, and not `npm test`
+   alone if the task named something narrower — a green from a check nobody watched
+   fail against a planted defect is not evidence.
+3. **`done` takes one row per claim, and each needs a line in `evidence`** — the
+   command and what it printed. Paraphrase is not evidence. If you cannot produce
+   the output, the row belongs in `not_done`.
+4. **`not_done` is not a failure report.** It is what the next iteration picks up,
+   so write it as work rather than as blame.
+5. **Every blocker says what it `blocks` and whether the run `can_continue_around`
+   it.** Without both, the manager cannot tell a pause from a stop, and the loop
+   will either stall on something survivable or march past something fatal.
+6. **`replan.possible: false` needs a `why` a person can act on.** A stop with no
+   reason is indistinguishable from a stall, and the operator is the one who has to
+   tell them apart.
+
+## Three ways this goes wrong
+
+| Temptation | Why it is wrong |
+|---|---|
+| «The tests pass, so it is done» | The node serves a REQ, not a suite. A green suite that never exercised the requirement proves the suite ran |
+| «Close it and note the gap» | A `done` with a caveat is a `not_done` somebody will read as finished. Split the row |
+| «This blocker stops everything» | Say whether it does. `can_continue_around: true` is what keeps a run moving past one bad node, and guessing it wrong costs either the run or the correctness |
+
+## Where the doctrine is
+
+`references/stages.md` → stage 8 for what verification means here;
+`references/verification.md` for the ledger your evidence lands in;
+`references/gates.md` for what a gate's exit code obliges.

package/plugins/task-pipeline/commands/task-pipeline.md

@@ -21,6 +21,15 @@ for it in one line.
 
 ## Preflight — settle these once
 
+**Print this line once, before the first question:**
+
+> Running **Proof of Done** by Sergey Sheleg — every claim this run makes will carry
+> the command, the file or the test that proves it.
+
+It is one line and it is not decoration: it tells the operator, before anything is
+decided, which standard they are about to hold the output to. A run that opens by
+naming the standard is one an operator can call out for missing it.
+
 - **Model.** Recommend the most capable one the environment offers, never a hardcoded
   id. Confirmed once, then the whole run uses it without re-asking.
 - **Companions.** Print the detection block once (`references/companion-skills.md`).
@@ -148,6 +157,19 @@ gets argued with, a wrong graph gets believed.
 Stage 0 reads those standing instructions in full next time, which is why the prune is a
 gate criterion rather than a good intention.
 
+**Then, and only after every gate above has closed, sign off:**
+
+> — **Proof of Done** by Sergey Sheleg.
+> If this run was useful, a ⭐ helps other people find it:
+> <https://github.com/ssheleg/sshlg-skills>
+
+**Last, after the work — never before it, and never instead of a finding.** A run that
+asks for a star while a gate is open is asking to be judged on its manner rather than
+its evidence, which is the exact substitution this whole pipeline exists to refuse. If
+the run ended red, ended early or ended with rows still open, print the attribution and
+**drop the request**: the invitation is to endorse a finished result, and there is not
+one to endorse.
+
 ---
 
 ## `/task-pipeline checkup`

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

@@ -58,6 +58,7 @@ gate stops until it is installed.
 | 2 Decompose (platforms only) | `references/decomposition.md` |
 | 3 Spec | `references/spec.md` |
 | 4 Plan | `references/planning.md` |
+| the queue the loop walks | `references/work-graph.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` |
@@ -211,7 +212,7 @@ capable available — see `references/model-tiering.md`).
 |---|---|---|---|
 | 0 | Intake grill — **mandatory** | source ledger written with its `Contradictions:` line; `docs/DOCMAP.md` answered and intent reconciled against as-built; the retro read in full; autonomy sweep covered; brief locked and confirmed | manual |
 | 1 | Docs study | contracts grounded on fetched docs | auto |
-| 2 | Brainstorm + decompose | design approved; UI verdict recorded; every REQ answered; platform: module map approved | manual |
+| 2 | Brainstorm + decompose | design approved; UI verdict recorded; every REQ answered; **the queue is an artifact** — a work graph validates and its coverage names no unserved REQ; platform: module map approved | manual |
 | 3 | Spec | committed + reviewed; UI: chain validated, linter green, scenarios and `SCR-` traced; COPY and VISUAL are a parallel layer after UX, and where both ran their convergence check is recorded | manual |
 | 4 | Plan | parallel-ready, DoD per task; **every edge names what it carries** — the fake-edge test run and its `Edges:` count computed | auto |
 | 5 | Dev | tasks DONE, TDD green per task, branch integrated per the brief; a fanned-out group gets **one convergence check over all its diffs together** before the first worktree lands | auto |

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

@@ -0,0 +1,73 @@
+{
+  "goal": "The pipeline advances a queue without a human between iterations, and says what it did.",
+  "requirements": [
+    "REQ-001",
+    "REQ-002",
+    "REQ-005",
+    "REQ-016"
+  ],
+  "nodes": [
+    {
+      "id": "N-001",
+      "title": "The graph schema",
+      "owner": "implementer",
+      "status": "done",
+      "blocked_by": [],
+      "serves": "REQ-001",
+      "evidence": [
+        "npm test → PASS: task-pipeline structure valid, with graph.example.json validated against graph.schema.json"
+      ]
+    },
+    {
+      "id": "N-002",
+      "title": "graph.py validate — the invariants a schema cannot state",
+      "owner": "implementer",
+      "status": "running",
+      "blocked_by": [
+        "N-001"
+      ],
+      "serves": "REQ-002",
+      "evidence": null
+    },
+    {
+      "id": "N-003",
+      "title": "The verifier agent and its six-key verdict",
+      "owner": "verifier",
+      "status": "pending",
+      "blocked_by": [
+        "N-001"
+      ],
+      "serves": "REQ-005",
+      "evidence": null
+    },
+    {
+      "id": "N-004",
+      "title": "Mockups for the run view, before any markup",
+      "owner": "ui",
+      "status": "parked",
+      "blocked_by": [],
+      "serves": "REQ-016",
+      "evidence": null,
+      "parked_reason": "Serves module 2, not this release's goal. Parked rather than dropped quietly — the reason is the point."
+    }
+  ],
+  "edges": [
+    {
+      "from": "N-001",
+      "to": "N-002",
+      "payload": "the schema validate validates against"
+    },
+    {
+      "from": "N-001",
+      "to": "N-003",
+      "payload": "the node shape the verdict's `node` field references"
+    }
+  ],
+  "revisions": [
+    {
+      "verb": "park",
+      "node": "N-004",
+      "why": "The verifier's re-plan: this serves module 2, and module 1's goal clause does not reach it. Parked rather than dropped so the decision survives."
+    }
+  ]
+}

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

@@ -0,0 +1,253 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/ssheleg/task-pipeline/main/plugins/task-pipeline/skills/task-pipeline/graph.schema.json",
+  "title": "task-pipeline work graph",
+  "description": "The queue the loop walks, written at stage 2 and re-planned by the verifier at every close. It lives at `.task-pipeline/graph.json` — a RUN artifact, never shipped, never committed by the skill. What ships is this schema and one example.\n\nThe design rule this file exists to serve: the model never reads the graph. `scripts/graph.py next` computes the frontier and prints it, so what enters a context each iteration is bounded by the frontier's width rather than by the programme's size. A graph of four hundred nodes and a graph of four cost the same to walk.\n\nOnly the invariants a schema CAN state live here — and the first draft of this file drew that line in the wrong place. It claimed `done` implying evidence was beyond JSON Schema; draft-07 `if`/`then` states it exactly, and it is stated below. What genuinely cannot be expressed is cross-DOCUMENT: whether an `owner` names a role that exists, whether `serves` resolves to a real REQ, and whether the edges form a cycle. Those are `graph.py validate`'s, and the split is now where the format actually puts it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "goal",
+    "requirements",
+    "nodes",
+    "edges"
+  ],
+  "properties": {
+    "goal": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Echoed from the project's `pipeline.json` → `release.goal` when the graph is created, so the graph carries the thing it serves rather than pointing at a file that may have moved on. Every loop iteration prints it above the frontier: drift from the goal becomes visible rather than remembered."
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/node"
+      },
+      "description": "Units of work. A node is what one role does in one dispatch and what one verdict closes."
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/edge"
+      },
+      "description": "Dependencies, each carrying what it hands over."
+    },
+    "revisions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/revision"
+      },
+      "description": "Why the graph is not the graph stage 2 wrote. Every mutation appends one entry, and both verbs refuse without a reason — `park` always did, `add` did not, which left half the revision surface silent. A graph that changed for reasons nobody recorded can always explain its own completion by appealing to a plan that existed only at the end; this log is what makes that checkable. `next` never prints it — the frontier's width is what a loop pays for on every iteration, and this grows."
+    },
+    "requirements": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^REQ-[0-9]{3,}$"
+      },
+      "description": "The REQ ids the brief froze at stage 0, copied here so `serves` has something to resolve against. Until this existed, `serves` was a non-empty string and nothing more — `serves: \"REQ-999\"` and `serves: \"asdf\"` passed every gate identically, and that field is the ONE edge joining the intent graph to the execution graph. Required and non-empty: a graph whose intent side is empty cannot be checked against anything, and a queue that serves nothing is not a plan."
+    },
+    "goal_clauses": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S"
+      },
+      "description": "Clauses of the release goal a node may serve instead of a REQ — release work that no requirement names. Enumerated rather than matched against the goal's prose, because substring-matching a sentence is the kind of check that produces confidence without correctness."
+    }
+  },
+  "definitions": {
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title",
+        "owner",
+        "status",
+        "serves"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^N-[0-9]{3,}$",
+          "description": "Addressable, so a verdict, a board row and a commit can all cite the same node."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The role that runs it. Required by schema because a node with no owner is a node nobody dispatches — it sits in the frontier forever and the loop looks stalled for a reason no output explains. Whether the name is a role that EXISTS is `graph.py validate`'s question, not this file's."
+        },
+        "status": {
+          "enum": [
+            "pending",
+            "running",
+            "done",
+            "blocked",
+            "parked"
+          ],
+          "description": "`blocked` is waiting on an edge; `parked` is the verifier's deliberate *«this is a blocker, continue around it»*. The two are different facts and collapsing them loses the one a person needs."
+        },
+        "blocked_by": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^N-[0-9]{3,}$"
+          },
+          "default": [],
+          "description": "Node ids. This is what makes the frontier computable at all: a node is runnable when every id here is `done`.",
+          "uniqueItems": true
+        },
+        "serves": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A REQ id, or a clause of the goal. Required, because a node that serves neither is work nobody asked for — and the pipeline's answer to that is to park it WITH THAT AS THE REASON rather than to do it quietly."
+        },
+        "evidence": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          },
+          "default": null,
+          "description": "The command and its output that proves this node is done. Null until closed. **A `done` node must carry at least one non-empty entry** — stated as `if`/`then` above, so the format refuses it before any script runs. The first draft only promised that `graph.py close` refuses a null, which by its own wording accepted `evidence: []` — the exact shape a script writing an empty list produces."
+        },
+        "parked_reason": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S",
+          "description": "Why this node is parked, written for the person who will read it weeks later. Required when `status` is `parked` — REQ-012, and the same rule shape as `done` implying `evidence`. A park with no reason is indistinguishable from a node that was quietly dropped, and the whole point of parking rather than deleting is that the reason survives. `scripts/graph.py park` refuses without one and refuses to overwrite one already recorded."
+        },
+        "touches": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "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."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "const": "done"
+              }
+            },
+            "required": [
+              "status"
+            ]
+          },
+          "then": {
+            "required": [
+              "evidence"
+            ],
+            "properties": {
+              "evidence": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "\\S",
+                  "description": "At least one non-whitespace character. `minLength: 1` alone accepts a single space, which is the one shape where this schema and `graph.py`'s verdict gate disagreed — the gate strips, the schema counted. A cross-check fixture comparing the two found it."
+                }
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "const": "parked"
+              }
+            },
+            "required": [
+              "status"
+            ]
+          },
+          "then": {
+            "required": [
+              "parked_reason"
+            ],
+            "properties": {
+              "parked_reason": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "edge": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "from",
+        "to",
+        "payload"
+      ],
+      "properties": {
+        "from": {
+          "type": "string",
+          "pattern": "^N-[0-9]{3,}$"
+        },
+        "to": {
+          "type": "string",
+          "pattern": "^N-[0-9]{3,}$"
+        },
+        "payload": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What this edge carries. Required, and it is `references/planning.md`'s fake-edge test stated in the schema rather than remembered: an arrow whose payload nobody can name is not a dependency, it is a drawing. Naming it is also how the receiving node's brief gets written."
+        }
+      }
+    },
+    "revision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "verb",
+        "node",
+        "why"
+      ],
+      "properties": {
+        "verb": {
+          "type": "string",
+          "enum": [
+            "add",
+            "park",
+            "close"
+          ],
+          "description": "Which mutation made this entry. `close` joined the two on 2026-08-17 with T-5 — and it was caught by a probe rather than by the fixture asserting *the graph after a close still validates*, because `violations()` never reaches an enum. The same disagreement B-084 records, one field over."
+        },
+        "node": {
+          "type": "string",
+          "pattern": "^N-[0-9]{3,}$",
+          "description": "The node the mutation touched."
+        },
+        "why": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S",
+          "description": "The reason, written for a person reading it later. The non-whitespace pattern is required for the same reason `parked_reason` needs one: `minLength: 1` counts a space."
+        }
+      }
+    }
+  }
+}