task-pipeline-skill 1.67.0 → 1.69.0

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
@@ -40,6 +41,7 @@ elsewhere and is not restated here:
 - Where a gate runs
 - Adding a check to an existing gate
 - Rationalizations
+- Cross-cutting, at every stage
 
 ## Axis A — the stage gate type
 
@@ -48,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
@@ -55,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.
@@ -447,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.
@@ -589,3 +635,47 @@ of is deleted in the next refactor by someone who assumed it was dead.
 | "The gate would be red on day one, so I'll add it later" | Make the section dormant instead. Dormant is visible and green; "later" is neither. |
 | "I raised the floor to get the build green" | Then say so in the log, in the same commit. A floor raised silently is a ratchet running backwards. |
 | "A hook is overkill, CI catches it" | CI catches it after the edit, the commit and the push. If the point is to stop the edit, CI is the wrong rung — and if it is not, do not pay the latency. |
+
+---
+
+## Cross-cutting, at every stage
+
+5. Cross-cutting, every stage: **when anything is settled — scope, a contract, a
+   name, a policy, a vocabulary — run the Doc Loop
+   (`references/documentation.md`) before the run moves on**: reserve the id,
+   record it, resolve the question it answers, propagate by the matrix, commit
+   with the ids. A decision that lives only in the spec dies with the spec, and one
+   that lives only in the conversation was never made;
+   **answer from the brief's autonomy section rather
+   than asking again** — it was grilled precisely so you wouldn't have to;
+   **anything deferred, dropped or left half-done goes into the carry-over ledger
+   the moment it's said** — deferred out loud is forgotten; **never narrow the task
+   silently** — the REQ list is frozen, adding is free, removing needs the
+   operator's explicit agreement; **when a loop starts undoing an earlier pass —
+   the same file edited twice for the same reason, a closed finding coming back, a
+   third entry into one stage — stop and run the loop guard**
+   (`references/loop-guard.md`): name the two shapes, escalate to the layer that
+   owns the conflict, re-plan the check as an ordered list, then go through it one
+   item at a time; **when a pass is *searching* rather than editing and starts
+   finding mostly what the previous pass's own fixes broke, the axis is exhausted —
+   rotate it, don't look harder** (`references/audit.md`); **every gate
+   prints `holds: N` — what this run left running** across the eight classes
+   (background shells, monitors, scheduled loops, coordination leases, worktrees,
+   containers, scratch files, remote state), enumerated **by class and never by a
+   single tool**, and stage 10 does not close while this run's residue is live and
+   unaccounted (`references/residue.md`); and remember that a
+   green from a check nobody has watched fail is not evidence; task
+   tracker + conventional commits per host conventions; worktree isolation for the
+   build, integrated back per the brief's branch policy before stage 7; honest
+   degradation (never claim a failed/skipped step succeeded);
+   outward/irreversible actions (deploy, publish, repo create, opening a PR,
+   **editing a shared design file — frames are read by designers and stakeholders,
+   so drawing in one is publishing — and above all *creating* one, which needs a
+   named team and never happens while a recorded file resolves**) need explicit
+   operator go — or a **specific** standing authorization recorded in the brief
+   (named target + preconditions; a vague "do everything" is not one).
+
+Moved out of `SKILL.md` on 2026-08-16 for the same budget reason as the
+multi-repository block: these fire at any stage, so they belong with the gate
+doctrine rather than inside step 5 of the run order.
+

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 |