task-pipeline-skill 1.56.0 → 1.58.0

package/CHANGELOG.md

@@ -1,5 +1,198 @@
 # Changelog
 
+## v1.58.0 — a fan-out is not finished when its branches are
+
+The graph model this pipeline was audited against in v1.57.0 named one defect and fixed
+it in one place. Applying the same model to the rest of the skill found the same defect
+in **three more**, and they are the same sentence each time: work fans out, the branches
+each go green, and the node that consumes them trusts them because they arrived.
+
+### Added
+
+- **The harvest is a convergence, and now it has a check.** Stage 0 queries the code, the
+  graph, `CLAUDE.md`, the ADRs, the docs, past briefs, the wiki, the board — all
+  independently — and lands them in one brief the interview then treats as a single
+  answer. Phase 2 checks each *answer* against the harvest; **nothing compared the sources
+  with each other**, so a doc contradicting the code produced two rows that each looked
+  fine and the run followed whichever it read last. The ledger now carries a
+  `Contradictions:` line with four things to look for, and the stage-0 gate reads it.
+  `Contradictions: none` is the answer most runs write, and writing it is the point.
+
+- **Stage 3's COPY and VISUAL tracks are a parallel layer, and their convergence has a
+  check.** Neither consumes the other — copy is written from the scenarios and the brand
+  pack, the visual from the frame and the style pack — so the order they were written in
+  was a fake edge teaching a run to wait for a result that never arrives. What they do
+  share is the screen, which is where the real failure lives: **each track is right alone
+  and they disagree together.** A label the layout has no room for, a state one drew and
+  the other never wrote, two names for one component, a tone the motion contradicts.
+
+- **Stage 9's three artifacts are named as a convergence**, and the graph↔docs divergence
+  check as its gate rather than a nicety — it is the only thing that compares two of the
+  three outputs against each other.
+
+Guards: 339 → **344**. Property checks: 9 → 9. Five new plants, one per branch of the
+three new checks, each anchored on a heading and each asserting it changed something.
+Two of the five were broken on their first run and both failures were mine: a grep
+pattern one character short of the message it looked for — **the same class fixed hours
+earlier in this programme and not swept into the new plants**, which is R-003 — and an
+assertion looking for the doctrine in the file that does not hold it.
+
+### Changed
+
+- **The stage-4 gate reads both halves of what it requires**, and the id/version
+  allocation this repository actually uses is written down. `.claude/agent-sync.json`
+  declares three id registers over an `fs` backend whose `reserve` refuses by design —
+  correctly, since *pretending would hand two agents the same id* — and the declaration
+  read as a capability, so nobody wrote the manual procedure it was hiding. On 2026-08-15
+  two sessions filed a different `B-073` and two branches claimed one version number.
+  `CLAUDE.md` now carries the three-step allocation (lease first, compute from the
+  **committed** file, commit before releasing) and the version rule (`git ls-remote --tags`,
+  because a local checkout is not where the answer lives), the shipped doctrine in
+  `documentation.md` carries the generalisable half, and a guard requires both.
+
+### Fixed
+
+- **Two concurrent runs of `test/negatives.py` no longer corrupt each other** (`B-075`).
+  Every step copies the repo to a **fixed** `/tmp` name, which is right in CI — one runner
+  per job — and wrong on a machine where a second suite is already running. The runner now
+  serialises the runs instead: an exclusive lock for the duration of the suite, so a second
+  run **waits** rather than corrupting the first and says so instead of producing a number
+  nobody can trust. The 344 workflow steps are untouched — they are the CI contract, one
+  runner per job, and they were never the ones colliding.
+
+  **The first fix was wrong and is worth recording.** It rewrote every `/tmp/...` path in a
+  step's script to a per-run name, and it broke two plants whose payload **is the workflow
+  text** — they search the copied workflow for a literal path in order to duplicate it. A
+  mechanical rewrite cannot tell a path being *used* from a path being *discussed*, which is
+  the umbrella's standing instruction #7 met for the second time in two days, both times by
+  the same author. The suite caught it; reading did not.
+
+  **Watched both ways, under real overlap.** Before, two concurrent runs of one selector
+  returned `1 guard did not fire, 7 broken` and `8 guards did not fire` — two different
+  wrong answers about a tree that was not changing. After, both return `all 8 guards
+  provably reject their planted defect`, exit 0, with the second printing that it waited.
+
+## v1.57.0 — an arrow that carries nothing is not an arrow, and two green diffs can still contradict each other
+
+The pipeline has drawn a dependency graph at stage 4 since it had a stage 4, and grouped
+tasks topologically off it. What it never said was how to tell a **real** edge from one
+that only records the order somebody typed the tasks in. The self-review asked the right
+question in a checklist line — *does this `depends:` point at a task that really produces
+what's consumed* — and no gate read the answer, so a plan could serialise itself entirely
+and pass every check.
+
+Audited against *Graph Engineering with Claude*
+(`https://x.com/Mahaximus_/status/2082442856417956173`), findings and both rejections in
+`docs/evidence/specs/2026-08-15-graph-audit.md`. **Nine of the ten macro stage edges carry
+data**, which is the audit's first result and the reason nothing was reordered.
+
+### Added
+
+- **The fake-edge test, as a numbered procedure** (`references/planning.md`). Six steps
+  over the graph you just drew: for each arrow, does output from A actually enter B, and if
+  you cannot name what crosses it, delete it. Expect two or three per plan.
+
+- **A `Carries` column in the *Execution order* table**, and it is the whole mechanisation:
+  a cell you cannot fill **is** the finding. The fake-edge test stops being a thing an agent
+  remembers to do and becomes a column a reviewer can see is empty.
+
+- **`Edges: <n> declared, <n> carry data, <n> removed`** in the stage-4 self-review, and
+  the gate reads it. Computed, like every other line in that block.
+
+- **The group convergence check** (`references/build.md` §4.2a). A per-task review reads
+  **one diff**; a fanned-out group produces several, and the defect that exists only
+  *between* two of them passes both. One check over the group's reports and diffs together,
+  after the last task and **before the first worktree is integrated** — the only moment all
+  of them exist and none has landed. Five things it looks for, each a real defect invisible
+  in a single diff: an empty deliverable, two outputs that cannot both be true, off-brief
+  work, one REQ satisfied twice differently, a Global Constraint only one task applied.
+  **A clean group logs a line too**, because a check whose silence is indistinguishable from
+  not having run is not evidence.
+
+- **A statement that this pipeline is a static graph, and why** (`references/planning.md`).
+  Auditability: a graph that decides its own shape produces a shape nobody drew, and then
+  *"here is the pipeline"* and *"here is what this run did"* stop being the same document.
+  The two places the run **does** discover structure — the module map and the carry-over
+  ledger — are named, and both land in a committed artifact, which is what separates
+  discovery from a dynamic graph.
+
+- **A preference for a harness-native fan-out primitive**, on the same reasoning §1 already
+  applies to worktrees: the harness owns the concurrency cap, the isolation and the resume.
+  Stated **without naming a product** — the keyword for one host's fan-out was renamed six
+  weeks after the article documenting it, and doctrine pinned to a vendor's noun rots on
+  that schedule.
+
+### Fixed
+
+- **`test/negatives.py` could not restore `.git` in a submodule checkout, so two guards
+  silently never fired.** The restore was gated on `os.path.isdir(.git)`. In every checkout
+  of this repository **as a submodule** — which is how the `sshlg-skills` umbrella ships it,
+  and therefore how most work on it happens — `.git` is a 48-byte file holding a `gitdir:`
+  pointer, so the branch was skipped and both git-dependent guards reported `fatal: not a
+  git repository` and were counted as *did not fire*. CI clones normally and was green,
+  which is why it survived. Measured before: exit `1`, `2 guard(s) did not fire`. After:
+  exit `0`, **all 318 guards**, twice consecutively.
+
+  The copy resolves the `gitdir:` pointer and **copies** the directory rather than pointing
+  at it, for two reasons that both bite: a plant that commits would otherwise move the real
+  branch, and the module's config carries `core.worktree` aimed back at the live checkout,
+  which would make every git command inside the snapshot operate on the tree the snapshot
+  exists to protect. That one key is stripped from the copy.
+
+- **The fan-out rule was stated with three conditions in `build.md` and one in
+  `stages.md`.** The summary kept *own worktree* and dropped *same group* and *exclusive
+  file ownership*, so a reader who took the summary as the rule would fan out two tasks that
+  share a file, in separate worktrees, and meet the conflict at integration. Both surfaces
+  now state all three.
+
+- **A property check's plant had gone narrow one column over, and CI is what found it.**
+  *The Human column survives a header reorder* rewrites the ledger's header and then swaps
+  each row's two last cells — matching on `| <auto> | <human> | — |`, with the `—` a
+  literal. Seven rows added by this run carry a finding id in `Note` instead, went
+  unmatched, stayed in the old order under a reordered header, and the check reported the
+  **doctrine** broken when the **plant** was what had aged. It had already been widened once
+  for exactly this reason one column to the left, which is what makes it a class rather than
+  an incident: a plant anchored on the CONTENT of a cell describes the table it was written
+  against. It now matches any note.
+
+Guards: 322 → **339**. Property checks: 9 → 9. Seventeen new plants, because a rule a check
+can decide is written as the check and not as prose somebody remembers: the fake-edge test
+renamed away, the `Carries` column dropped, the stage-4 gate no longer reading it, §4.2a
+deleted outright, §4.2a losing its *before integration*, and `stages.md` dropping the
+convergence check from its stage-5 summary — which is the exact drift F-5 found, now
+guarded in the direction it drifted. The other eleven came from **an independent reviewer
+across five rounds on the PR**, which is the mechanism standing instruction R-005 exists to buy: it found four
+branches of the new guards with no plant behind them, a `_section()` site with no
+`is None` arm (the shape every other site in the file has), a stage-5 guard checking one
+of the three preconditions its own message claims, and an uncached read of a memoised
+document. It also found the two gaps that were not nits — see below. Every plant is
+anchored on a heading or a token, and every one asserts it changed something before the
+validator is asked.
+
+**Two of the reviewer's findings were defects, not nits, and both were fixed before
+merge.** First: the convergence check was written into narrative prose and into
+`SKILL.md`'s stage table, and **into neither GATE bullet** — so a fanned-out group could
+reach stage 6 having never run it. `build.md`'s and `stages.md`'s gates now require it,
+and a guard requires the gate to require it. Second: the `.git` restore resolved a
+`gitdir:` pointer by hand, which is right for a submodule and **wrong for a linked
+worktree** — the shape `build.md` itself tells every run to work in, where `objects`,
+`refs` and `config` live wherever `commondir` points. It now asks
+`git rev-parse --git-common-dir`, which answers correctly for all three shapes. A fix that
+covers one of two shapes of the same defect is half a fix.
+
+### Not changed, deliberately
+
+- **Stage 8 → 9.** The audit's F-4 asked whether docs depend on the post-deploy check or
+  only on the version stage 7 produced. Rejected with reasoning rather than left open: a
+  single agent session runs serially so removing the edge buys no wall-clock, and a
+  post-deploy check can change what stage 9 must write. Weak is not the same as fake.
+- **The stage list, the stage count and every gate type.** Gate *criteria* moved at stage 4
+  and stage 5; nothing was renumbered, reordered or retyped.
+
+**Released as 1.57.0, not 1.56.0.** This work was branched, reviewed over five rounds and tagged in its own tree while a concurrent session merged a different 1.56.0 — the
+browser-channel release below. Both branches claimed the number; the id register that would have prevented it is declared in `.claude/agent-sync.json` and cannot allocate
+against an `fs` backend, which is the umbrella's open row **B-45**. The same collision took a board id: `B-073` here was renumbered to **B-075**.
+
 ## v1.56.0 — the stages demanded a look and named no way to take one
 
 Since v1.36.0 three stages have required the rendered surface to be checked in a

package/README.md

@@ -68,8 +68,8 @@ Every gate is **typed**: `auto` — the orchestrator verifies it itself, pass/fa
 | 1 | Docs study | contracts grounded on current docs | auto |
 | 2 | Brainstorm + decompose | design approved; UI verdict recorded; every REQ answered; platform: module map approved | manual |
 | 3 | Spec | committed + reviewed; UI: super-ux chain validated, linter green | manual |
-| 4 | Plan | parallel-ready, DoD per task | auto |
-| 5 | Dev | tasks DONE (three review verdicts each), TDD green per task | auto |
+| 4 | Plan | parallel-ready, DoD per task; **every edge names what it carries** — an arrow whose payload nobody can fill is a fake edge | auto |
+| 5 | Dev | tasks DONE (three review verdicts each), TDD green per task; **a fanned-out group gets one convergence check over all its diffs together before the first worktree lands** | auto |
 | 6 | Tests | full suite green, new code covered; **on a web front end the surface is checked in a browser, not in the diff** | auto |
 | 7 | Lint + deploy | lint clean + suite green before deploy | manual |
 | 8 | Post-deploy | clean boot / honest degradation, **and the CI verdict read rather than assumed**, and **a deployed web page is opened rather than curled** — a `200` is not a rendered page | auto |

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.56.0 |
+| **Version** | 1.58.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.56.0",
+  "version": "1.58.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"

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

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

@@ -115,8 +115,12 @@ log and archive are **queried** by the task's nouns, because nothing caps them
 outranks any document — **but only out loud**, so an override is a recorded decision
 rather than an undetected divergence. That ledger is also stage 9's work list.
 
-**Three artifacts close a run, not two.** Stage 9 syncs the docs, the wiki **and the
-code graph** (`/graphify . --update`). The graph is what the next run's harvest queries
+**Three artifacts close a run, not two — and they are a convergence, not a sequence.**
+Stage 9 syncs the docs, the wiki **and the code graph** (`/graphify . --update`). None of
+the three consumes another; all three consume the same change, and the **graph↔docs
+divergence check is the gate over their convergence** rather than an extra nicety. That is
+why it is not optional where a graph exists: it is the only thing that compares two of the
+three outputs against each other. The graph is what the next run's harvest queries
 first, so a stale one is a false premise **carrying the authority of a machine** —
 a wrong doc gets argued with, a wrong graph gets believed. Refreshing it buys the
 graph↔docs divergence check; doc-side findings are fixed at stage 9, absences become
@@ -248,12 +252,12 @@ capable available — see `references/model-tiering.md`).
 
 | # | Stage | Gate | Type |
 |---|---|---|---|
-| 0 | Intake grill — **mandatory** | source ledger written; **the documentation inventory answered into `docs/DOCMAP.md`** — registers, single homes, the propagation matrix, the gate command — and **intent reconciled against as-built**, every divergence resolved ([`references/documentation.md`](references/documentation.md)); the retro read in full and its archive queried; shared understanding reached; autonomy sweep covered; brief locked + confirmed | manual |
+| 0 | Intake grill — **mandatory** | source ledger written **with its `Contradictions:` line** — the harvest converges on one brief and nothing else compares the sources with each other; **the documentation inventory answered into `docs/DOCMAP.md`** — registers, single homes, the propagation matrix, the gate command — and **intent reconciled against as-built**, every divergence resolved ([`references/documentation.md`](references/documentation.md)); the retro read in full and its archive queried; shared understanding reached; autonomy sweep covered; brief locked + 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 |
-| 3 | Spec | committed + reviewed; UI: chain validated, linter green, scenarios/`SCR-` traced | manual |
-| 4 | Plan | parallel-ready, DoD per task | auto |
-| 5 | Dev | tasks DONE, TDD green per task, branch integrated per the brief; **anything generated passes its own checks, and local infrastructure does not publish the host's default ports** ([`references/learned.md`](references/learned.md)) | auto |
+| 3 | Spec | committed + reviewed; UI: chain validated, linter green, scenarios/`SCR-` traced; **COPY and VISUAL are a parallel layer after UX, and where both ran their convergence check is recorded** — a label the layout has no room for is right in each track and wrong on the screen ([`references/stages.md`](references/stages.md)) | manual |
+| 4 | Plan | parallel-ready, DoD per task; **every edge names what it carries** — the fake-edge test run, its `Edges:` count computed, and no arrow left whose payload nobody can name ([`references/planning.md`](references/planning.md)) | 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** — a per-task review cannot see a contradiction that exists only between two of them ([`references/build.md`](references/build.md) §4.2a); **anything generated passes its own checks, and local infrastructure does not publish the host's default ports** ([`references/learned.md`](references/learned.md)) | auto |
 | 6 | Tests | full suite green; new/changed code covered; **every new check probed both ways and asserted on its exit code**, and the suite run once against a cold environment ; **on a web front end the surface is checked in a browser, not in the diff** — a green suite cannot see a component that renders under a fixed header, a request that 404s past its mock, or a console error — and a browser **test suite** is the other half of the pair, never a substitute for the look (`playwright` or `chrome-devtools`, either one — **how**: [`references/browser.md`](references/browser.md), which channel: [`references/companion-skills.md`](references/companion-skills.md); absent → say *verified by reading the diff* and record it as the weaker claim it is) | auto |
 | 7 | Lint + deploy | lint clean + suite green before deploy; deploy needs a go (or the brief's specific standing authorization) | manual |
 | 8 | Post-deploy | clean boot or honest degradation report; **a deployed web target is opened, not curled** — a `200` proves the server answered and says nothing about a 404'd bundle or a console full of errors on load (`playwright` or `chrome-devtools`, either one, [`references/browser.md`](references/browser.md); absent → call it an HTTP response, which is its honest name) | auto |

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

@@ -78,7 +78,7 @@
       ],
       "gate": {
         "type": "auto",
-        "check": "SET EQUALITY: the REQ ids in the brief equal the union of Implements: across plan tasks — a non-empty difference fails the gate and is reported as the explicit list of dropped requirements. Plus: every spec requirement maps to a task; no placeholders; names and types consistent across tasks; every task carries a verifiable DoD; parallel-group tasks share no files; UI tasks name the scenario ID(s) and SCR- screen(s) they implement in their DoD"
+        "check": "SET EQUALITY: the REQ ids in the brief equal the union of Implements: across plan tasks — a non-empty difference fails the gate and is reported as the explicit list of dropped requirements. Plus: every spec requirement maps to a task; no placeholders; names and types consistent across tasks; every task carries a verifiable DoD; parallel-group tasks share no files; UI tasks name the scenario ID(s) and SCR- screen(s) they implement in their DoD. Every edge in the plan's Execution order table carries a non-empty Carries cell and the self-review's Edges: line is computed — an arrow whose payload nobody can name is a fake edge and the wait behind it is free to give away."
       }
     },
     {
@@ -92,7 +92,7 @@
       ],
       "gate": {
         "type": "auto",
-        "check": "all plan tasks DONE — the per-task review returns three verdicts (spec compliance, REQ satisfied, code quality); every finding fixed or parked with a written ruling; no task left BLOCKED; full test suite green; the branch integrated per the brief's branch policy (base synced, suite green on the result, worktree removed) — or the operator's explicit 'leave it unmerged' recorded. Every parked finding and implementer concern is harvested into the carry-over ledger before the scratch workspace is deleted."
+        "check": "all plan tasks DONE — the per-task review returns three verdicts (spec compliance, REQ satisfied, code quality); every finding fixed or parked with a written ruling; no task left BLOCKED; full test suite green; the branch integrated per the brief's branch policy (base synced, suite green on the result, worktree removed) — or the operator's explicit 'leave it unmerged' recorded. Every parked finding and implementer concern is harvested into the carry-over ledger before the scratch workspace is deleted. Every group that actually fanned out ran its convergence check over all its diffs together BEFORE its first worktree was integrated, and logged a line either way (findings with their ruling, or 'convergence check clean')."
       }
     },
     {

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

@@ -275,10 +275,52 @@ physical: **two implementers writing one working tree corrupt each other's state
   **each implementer gets its own isolated worktree**. Then dispatch them together,
   review each one against its own diff, and integrate the worktrees back to the
   build branch one at a time, running the suite after each merge.
+- **Prefer a native fan-out primitive where the harness has one**, for the same
+  reason `git worktree` defers to a native worktree tool in §1: the harness owns the
+  concurrency cap, the per-agent isolation and the resume, and hand-rolling those
+  creates state it cannot see or clean up. Where there is none, dispatch by hand
+  under the three conditions above. **Never name a specific product here** — the
+  keyword for one host's fan-out was renamed six weeks after the article that
+  documented it, and doctrine pinned to a vendor's noun rots on that schedule.
 - **Any conflict on integration** means the plan's file ownership was wrong: stop
   fanning out, finish the group sequentially, and record it in the ledger.
 - Never fan out the fix loop — a task under repair belongs to one implementer.
 
+### 4.2a The group convergence check — after the group, before integration
+
+A per-task review reads **one diff**. A fanned-out group produces several, and the
+defect this stage cannot otherwise see is the one that exists only *between* them:
+each task passes its own review and the group is still incoherent.
+
+So after the last task in a fanned-out group reports, and **before** the first
+worktree is integrated, run one check over the group's reports and diffs together.
+It is the only moment all of them exist and none of them has landed.
+
+Five things it looks for. Each has been a real defect, and none is visible in a
+single diff:
+
+1. **An empty deliverable** — a task that reported DONE and changed nothing that
+   satisfies its REQ.
+2. **Two outputs that cannot both be true** — the same helper renamed by one task
+   and called by its old name in another; two tasks adding the same config key with
+   different defaults; two migrations claiming the same version.
+3. **Off-brief work** — a task that solved a neighbouring problem instead of the one
+   its brief named. Its own review passes, because its own diff is coherent.
+4. **A REQ satisfied twice, differently** — two tasks each implementing the same
+   requirement in incompatible ways, which the per-task REQ verdict cannot see
+   because each is looking at one task.
+5. **A shared assumption that only one task acted on** — a Global Constraint one
+   implementer applied and another did not.
+
+**A finding here is not a per-task fix loop.** It is a group-level decision: pick
+which task is right, send the other back with the ruling, or park both and escalate.
+Log it once, on the group:
+`Group <G>: convergence check — <n> findings (<one-liners>); ruling: <what governs>`.
+
+**A clean group logs a line too** — `Group <G>: convergence check clean (<n> tasks)`.
+A check whose silence is indistinguishable from not having run is not evidence, and
+this is the check most likely to be skipped because every task already went green.
+
 ### 4.3 Handle the report
 
 | Status | Action |
@@ -520,8 +562,10 @@ stages 7–9 run against an unintegrated branch.
 ## GATE (auto)
 
 All plan tasks DONE with all three review verdicts (spec compliance, REQ satisfied,
-code quality); the full test suite green; every open finding either fixed or parked
-with a ruling; **every parked finding and implementer concern harvested into the
+code quality); **every group that actually fanned out has run its convergence check
+(§4.2a) before its first worktree was integrated, and logged a line either way** —
+findings with their ruling, or `convergence check clean`; the full test suite green;
+every open finding either fixed or parked with a ruling; **every parked finding and implementer concern harvested into the
 carry-over ledger** — the workspace is deleted, so nothing may stay only there;
 no task left BLOCKED; the branch integrated per the brief's policy — or the
 operator explicitly told you to leave it, and that is recorded. **Every decision a
@@ -541,5 +585,7 @@ a red suite or an unresolved BLOCKED does not advance to stage 6.
 | "This finding is obviously wrong, drop it" | You adjudicate at the cap, in writing. Silent discards are forbidden. |
 | "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Without one, controllers re-run entire completed task sequences. |
 | "Two implementers in parallel will be faster" | One working tree, two writers = corrupted state. Parallel needs one worktree each. |
+| "Every task in the group passed its review, so the group is fine" | A per-task review reads one diff. The defect between two diffs — a rename one task made and another calls by its old name — passes both and lands at integration. §4.2a. |
+| "The convergence check found nothing, no need to log it" | A check whose silence looks identical to not having run is not evidence. The clean line is the record that it ran. |
 | "I'll paste the earlier tasks so it has context" | A fresh subagent needs its task, its interfaces and the constraints. Pasted history is pure cost. |
 | "Stage 7 can merge the branch" | Stage 7 lints and deploys what is integrated. An unmerged branch means lint, deploy and docs all ran against something that is not what ships. |

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

@@ -353,6 +353,23 @@ A register is the one file two agents will write in the same minute.
   a real state, not a formality. Describing a project as protected while nothing
   enforces it is worse than having no protection, because everyone downstream
   believes the guarantee.
+- **A register declared against a backend that cannot reserve is a register in name
+  only, and its presence is what stops the manual procedure being written.** Measured
+  2026-08-15: a project declared three id registers over a local-filesystem backend
+  whose `reserve` correctly refuses — *pretending would hand two agents the same id* —
+  and two sessions filed a different `B-073` on the same afternoon. The tool was honest;
+  the *declaration* was the problem, because a capability that appears to exist is one
+  nobody replaces. Where reservation is not available, write the three-step manual
+  allocation down where an agent reads it, and make it follow the lease:
+  1. take the lease on the register's file **first**;
+  2. compute the next id from the **committed** file — `git show HEAD:<file>` — never
+     from a working copy, which holds your own unpushed row and hides somebody else's;
+  3. write and **commit** before releasing the lease. An id held only in an uncommitted
+     file is an id nobody else can see you took.
+- **A version number is the same class with no register at all.** Two branches both
+  claimed one version on that same afternoon because each incremented from what its own
+  checkout knew. Read the remote — `git ls-remote --tags` — because that list is the only
+  place the answer lives.
 
 ---
 

package/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md

@@ -17,6 +17,7 @@ that goes stale when the answer changes.
 - The knowledge wiki — recommended
 - How to harvest — retrieval, not reading
 - Record it — the source ledger
+- The harvest is a convergence, so it needs a check across its sources
 - The source is not the copy you have
 - Carried-in claims — measured or recalled
 - Phase 2 — validate the answers against the harvest
@@ -177,6 +178,38 @@ source nobody will update.
 **"No sources found" is a valid, recorded outcome.** Write the row. An empty ledger
 tells the next run that the search happened and came back empty — silence doesn't.
 
+## The harvest is a convergence, so it needs a check across its sources
+
+Every row above was produced independently — the code does not know what the ADR says,
+the wiki does not know what the graph found. Then all of them arrive at one place, the
+brief, and the interview treats that place as a single answer. **That is a fan-out with
+a convergence, and a convergence trusts its inputs because they arrived**
+(`agent-stack` → `agent-orchestrator/references/graph-engineering.md`, the checker node).
+
+Phase 2 below checks each *answer* against the harvest. Nothing checks the **sources
+against each other**, and that is the gap: a doc that contradicts the code produces two
+rows that each look fine, and the run picks whichever it read last.
+
+So before the first question, walk the ledger once more and write a **`Contradictions:`**
+line under it. Four things to look for, and they are the checker's five catches with the
+one that cannot apply here dropped:
+
+1. **Empty** — a source that was consulted and said nothing about this task. Already a
+   valid row; the point is that it must be *written*, not omitted.
+2. **Mutually contradictory** — two sources that cannot both be true. Name both rows and
+   which one this run will follow, **out loud**, because the operator outranks a document
+   only when the override is recorded.
+3. **Off-topic** — a row that answers a neighbouring question. It inflates the ledger and
+   makes the next reader trust a source that was never about this.
+4. **Stale against a fresher neighbour** — the graph built a week before the code it
+   describes, an ADR superseded by a decision nobody linked. This is the one the `Fresh?`
+   column exists for and nobody compares.
+
+`Contradictions: none` is the answer most runs will write, and writing it is the point:
+a check whose silence is indistinguishable from not having run is not evidence. Anything
+found here is a stage-9 obligation — the ledger's row is what stage 9 goes back and
+fixes.
+
 ## The source is not the copy you have
 
 `learned.md` rule 17. The harvest reads the project's own files, and one property of them is

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

@@ -52,10 +52,53 @@ what each one owns. This is where decomposition gets locked in:
 into **parallel groups** in topological order, and tag each task
 `depends: [task ids]`.
 
+**Then run the fake-edge test over what you just drew.** An edge is a dependency
+that carries data — not two tasks that happen to be written one after the other.
+Six steps, five minutes, and it is the difference between a graph and a list:
+
+1. Write every task as a box.
+2. Draw an arrow between each pair you were about to order.
+3. For each arrow ask: **does output from A actually enter B?** Not *"does B come
+   after A"* — does B consume a file, a signature, a decision or a value that A
+   produced?
+4. Yes → keep it, and **write the payload in the `Carries` cell**.
+5. No → delete it. That wait was free to give away, and you were paying for it.
+6. Everything left with no incoming arrow is group A and starts at once.
+
+**The payload is the test, not the answer to it.** An arrow whose `Carries` cell
+you cannot fill is a fake edge, and the empty cell is what makes that visible to
+a reviewer instead of leaving an arrow in place because it looked orderly. Expect
+two or three per plan; the classic is *"review file A, then review file B"*,
+which reads as a sequence and never once passes anything between them.
+
 **File ownership is exclusive within a group.** No two tasks in the same parallel
 group write the same file — that is the rule that makes stage-5 fan-out safe.
 Sequential integration/glue tasks sit *between* groups.
 
+**Distinct is not the same as independent.** Two tasks with different names, in
+different directories, that both write one shared registry — or both take the
+same fixed scratch path — are one task with a race in it. The check is what they
+*touch*, never what they are called.
+
+### This pipeline is a static graph, and that is a decision
+
+The stage list is fixed before the run starts, and stays fixed. It could have
+been otherwise: a run that reads its own findings and invents its next stage is
+a real design, and it is the one this pipeline refuses.
+
+**The reason is auditability.** A graph that decides its own shape while running
+produces a shape nobody drew, so *"here is the pipeline"* and *"here is what this
+run did"* stop being the same document — and every claim stage 10 makes becomes
+unfalsifiable from the outside. That is the same failure the evidence canons name
+when a number is restated rather than computed.
+
+Two places the run *does* discover structure, both bounded and both recorded:
+the **module map** cut at stage 2 ([`decomposition.md`](decomposition.md)), which
+is committed as a file before any module is built, and the **carry-over ledger**,
+which grows but never reorders a stage. Discovery that lands in a committed
+artifact is not a dynamic graph; discovery that changes what runs next, silently,
+is.
+
 ## Task right-sizing
 
 A task is the smallest unit that carries its own test cycle and is worth a fresh
@@ -94,14 +137,19 @@ verbatim from the spec. Every task's requirements implicitly include this sectio
 
 ## Execution order
 
-| Group | Tasks | Runs after |
-|---|---|---|
-| A | 1, 2 | — |
-| B | 3 | A |
+| Group | Tasks | Runs after | Carries |
+|---|---|---|---|
+| A | 1, 2 | — | — |
+| B | 3 | A | <what crosses this edge: the file, signature, decision or value B consumes> |
 
 ---
 ```
 
+**The `Carries` cell is required on every edge and empty only on group A.** A cell
+you cannot fill means the arrow carries nothing, which means it is a fake edge:
+delete it and let the task start in the earlier group. This is the fake-edge test
+made a column, so its result is committed rather than remembered.
+
 ## Task structure — required
 
 ````markdown
@@ -190,8 +238,11 @@ A checklist you run yourself, inline. No subagent:
 4. **Name and type consistency:** signatures, property names and types used in
    later tasks match what earlier tasks defined. `clearLayers()` in Task 3 and
    `clearFullLayers()` in Task 7 is a bug, not a style difference.
-5. **Parallel safety:** no two tasks in the same group write the same file; every
-   `depends:` points at a task that really produces what's consumed.
+5. **Parallel safety and the fake-edge test:** no two tasks in the same group write
+   the same file **or share any other mutable target**; every `depends:` points at a
+   task that really produces what's consumed, and every edge's `Carries` cell is
+   filled. Count the edges you deleted — that number is the line below, and a plan
+   that deletes none on its first pass has almost certainly not run the test.
 6. **DoD present and verifiable** on every task.
 7. **Every command, path and file a DoD names resolves.** Walk each task's
    *Definition of done* and its steps and check the targets exist — a DoD that says
@@ -219,6 +270,7 @@ before the gate; every line a **computed number, not a tick**.
 - Decisions: checked against <the brief's D-table> and <stage 2's rejected options> — <verdict>
 - Cost: <surfaces>/<guards>/<REQ> now, <…> at stage 2 — <proportionate | grown, and why>
 - Hygiene: <n> checks, <n> findings, <n> open
+- Edges: <n> declared, <n> carry data, <n> removed
 - Placeholders: <n> · Ambiguity: <n> found, <n> resolved inline
 ```
 
@@ -243,6 +295,9 @@ the explicit list of dropped (or invented) requirements — this seam is where s
 leaks, so the check is mechanical, never a judgement call.
 
 Then: every spec requirement maps to a task; no placeholders; names and types
-consistent across tasks; parallel-group tasks share no files; each task has a
-verifiable DoD. UI tasks carry their scenario IDs and `SCR-` screens. Verify all of
-it yourself and stop on failure — this gate has no operator in it.
+consistent across tasks; parallel-group tasks share no files **or other mutable
+target**; each task has a verifiable DoD. **Every edge in the *Execution order*
+table has a non-empty `Carries` cell, and the `Edges:` line of the self-review is
+computed** — an unfillable cell is a fake edge and the gate does not pass with one
+left in the table. UI tasks carry their scenario IDs and `SCR-` screens. Verify all
+of it yourself and stop on failure — this gate has no operator in it.

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

@@ -194,7 +194,11 @@ never that the work was skipped quietly.
   an updated `CONTEXT.md` (terms written as they resolved) and any ADRs under
   `docs/adr/` — see `grill.md` → *Domain awareness*.
 - **GATE (manual):** shared understanding reached — **the source ledger is written
-  (every source consulted, or an explicit "none found")**, **where a code graph
+  (every source consulted, or an explicit "none found")** and **its `Contradictions:`
+  line is written under it** — the harvest is a fan-out that converges on one brief, and
+  nothing else compares the sources *with each other*; `Contradictions: none` is the
+  answer most runs give and writing it is the point
+  ([`knowledge-sources.md`](knowledge-sources.md)), **where a code graph
   exists its row carries the measured lag and the signal it was measured with — a
   bare build date does not satisfy this, because it is the graph's own reply rather
   than a measurement of it** ([`knowledge-graph.md`](knowledge-graph.md) →
@@ -338,6 +342,29 @@ never that the work was skipped quietly.
   `sheleg-design` how it **looks**. Until 2026-08-10 this stage named only the first,
   so a run designed a flow, then wrote its strings by taste and picked its values at the
   keyboard — and every gate in the pipeline reported green over both.
+- **Two of the three are a parallel layer, and the third is their only real dependency.**
+  COPY and VISUAL both consume the UX track's scenarios; **neither consumes the other**.
+  Copy is written against the brand pack and the scenarios, not against tokens; the visual
+  is built from the frame and the style pack, not from strings. Writing them in a line —
+  which this file did until 2026-08-15 — teaches a run to wait for a result that never
+  arrives. The order is `UX → { COPY ∥ VISUAL }`, and the only thing crossing each of
+  those two arrows is **the scenario set**.
+- **Their convergence needs a check, and it has a real contradiction to catch.** Both land
+  on the same screen, so the failure is not that one is wrong: it is that each is right
+  alone and they disagree together. Before the spec is committed, compare the two outputs
+  and record the answer:
+  1. **A string the layout has no room for** — a label, an error or an empty state longer
+     than the frame's element, at the frame's own width.
+  2. **A state one track has and the other does not** — copy for an empty state the design
+     never drew, or a loading state drawn with no string.
+  3. **Two names for one thing** — the design system's component name against the
+     terminology file's noun, where a user reads both.
+  4. **A tone the visual contradicts** — a calm, plain register on a screen whose motion
+     and colour say urgency.
+  `Tracks converge: clean` is the answer most runs write, and writing it is the point —
+  a check whose silence is indistinguishable from not having run is not evidence. This is
+  the same rule the harvest applies at stage 0 and the build applies to a fanned-out group
+  at stage 5 ([`build.md`](build.md) §4.2a); one shape, three places.
 - **Spec:** write the approved design to
   `<artifacts>/specs/YYYY-MM-DD-<topic>-design.md` and commit it. Lock all
   shared contracts (types, schemas, signatures, file layout). For UI tasks the
@@ -360,6 +387,9 @@ never that the work was skipped quietly.
   through the COPY track or the refusal is recorded**, and **the visual layer went
   through the VISUAL track or the refusal is recorded** — a recorded refusal passes
   this gate and an unmentioned one does not, which is the only difference that matters.
+  **Where both tracks ran, their convergence check is recorded** — findings with the
+  ruling, or `Tracks converge: clean`; a screen where each track is right alone and they
+  disagree together is the defect neither track's own review can see.
   No plan (stage 4)
   starts before this — the chain comes BEFORE interface.
 
@@ -378,7 +408,11 @@ never that the work was skipped quietly.
   scope leaks silently, so the check is mechanical, not a judgement call. Plus:
   every spec requirement maps to a task; no placeholders; names and
   types consistent across tasks; every task carries a verifiable DoD; parallel-group
-  tasks share no files. For UI tasks: every task building user-facing behavior
+  tasks share no files **or other mutable target**; **every edge in the *Execution
+  order* table carries a non-empty `Carries` cell and the self-review's `Edges:`
+  line is computed** — an arrow whose payload nobody can name is a fake edge and
+  the wait behind it is free to give away ([`planning.md`](planning.md)).
+  For UI tasks: every task building user-facing behavior
   names the scenario ID(s) and `SCR-` screen(s) it implements, and its DoD
   includes satisfying them **and** updating the affected super-ux layers in the
   same change (super-ux *same-change* rule).
@@ -393,7 +427,12 @@ never that the work was skipped quietly.
   with an explicit breaker. TDD per task ([`tdd.md`](tdd.md)): failing test →
   watch it fail → minimal impl → watch it pass → commit. Pin subagents to the
   run's confirmed model (`model-tiering.md`). The plan's parallel groups fan out
-  **only** when each implementer gets its own worktree; otherwise sequential.
+  **only when all three hold** — the tasks share no `depends:`, their file ownership
+  is exclusive per the plan, and each implementer gets its own worktree; otherwise
+  sequential. A group that did fan out gets **one convergence check over all its
+  reports and diffs together, before the first worktree is integrated**
+  ([`build.md`](build.md) §4.2a) — a per-task review reads one diff and cannot see a
+  contradiction that exists only between two of them.
 - **Web front end? The task's own surface is checked in a browser, not in the diff.**
   Where a browser channel is connected — `playwright` **or** `chrome-devtools`, either
   one, whichever answers first (**how**: [`browser.md`](browser.md); which:
@@ -416,7 +455,9 @@ never that the work was skipped quietly.
 - **GATE (auto):** **the hygiene gate green in diff mode after every task**
   (`references/build.md`) — six checks over what that task changed, no floor, and a
   finding fixed in-task or carried over with a reason; all plan tasks DONE (three review verdicts per task: spec
-  compliance, **REQ satisfied**, code quality); every finding fixed or parked with a
+  compliance, **REQ satisfied**, code quality); **every group that fanned out ran its
+  convergence check before its first worktree was integrated, and logged a line either
+  way** ([`build.md`](build.md) §4.2a); every finding fixed or parked with a
   ruling; **every parked finding and implementer concern harvested into the
   carry-over ledger** — nothing stays only in the scratch workspace, which is
   deleted; no task left BLOCKED; full test suite green; branch integrated per the brief's policy (or the operator's