task-pipeline-skill 1.67.0 → 1.69.0

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."
+        }
+      }
+    }
+  }
+}

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

@@ -22,6 +22,7 @@ requirement.** It is what turns the pipeline from a funnel into a circle.
 - A seam is not a deliverable, and REQ rows are written against deliverables
 - GATE (manual)
 - When the answer is "something's missing"
+- A project of several repositories
 
 ## Why a stage and not a gate
 
@@ -187,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
@@ -361,3 +398,35 @@ or a tracked follow-up. Both are legitimate outcomes of this stage. Closing the
 run with a known gap is fine **if the gap is written down** — closing it with the
 gap only in someone's memory is the failure mode this whole spine exists to
 prevent.
+
+---
+
+## A project of several repositories
+
+**A submodule is finished when its parent says so.** A parent repository records each submodule as
+a pointer to one commit, and moving the submodule does not move the pointer. So the work is
+committed, pushed, its CI is green and its own roadmap says done — and anyone who clones the parent
+gets the commit **before** the change. Nothing looks wrong in either repository on its own; the
+disagreement exists only between them, which is why it survives every check that runs inside one.
+
+Stage 10 does not close until:
+
+```bash
+git submodule status          # no line begins with '+'  (a '+' is the missing bump)
+git -C <each repo> status --porcelain && git -C <each repo> log @{u}..HEAD --oneline
+```
+
+report nothing — for the parent as well as every submodule. Where
+[agent-sync](https://github.com/ssheleg/agent-sync) is installed, `/agent-sync finish` runs
+exactly this plus *no lease left held*, and `--gates` adds the project's own gate commands.
+
+The fix, when it fails, is two commands and the second is the one that gets forgotten:
+
+```bash
+git -C <submodule> push
+git add <submodule> && git commit -m "chore: bump <name> submodule — <why>"
+```
+
+Moved out of `SKILL.md` on 2026-08-16: the body was 6685 tokens against a
+< 5000 budget, and stage-10 close-out is what this file is for.
+

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