task-pipeline-skill 1.55.0 → 1.57.0

package/CHANGELOG.md

@@ -1,5 +1,220 @@
 # Changelog
 
+## 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
+browser, and v1.55.0 gave that requirement a second channel. Neither release said
+**how a look is taken**. An agent reading this bundle learned which plugin to install
+and nothing about what to do with it — which is precisely how a run reports *checked in
+a browser* and means *ran the unit tests*.
+
+`references/browser.md` is that mechanism, and stages 5, 6 and 8, `tdd.md` and both
+gate rows in `SKILL.md` now point at it.
+
+### Added
+
+- **The one model both channels share.** A snapshot returns the accessibility tree with
+  a **ref** per element, and you act on the ref — not on pixels, not on coordinates. Three
+  consequences the doctrine already rested on and had never stated: a look costs a page of
+  text and no vision model, a ref is deterministic where a coordinate is not, and **a ref
+  that stops resolving is a finding rather than an error to retry past**.
+- **The look as four runnable commands** — `open`, `snapshot`, `console`, `requests` —
+  with the MCP and `chrome-devtools` names beside them, because the look is the same look
+  and that is why the matrix ranks neither.
+- **Sessions and the daemon.** The browser lives between commands, which is the whole
+  reason the four compose; `-s=<session>` isolates, `list` is the evidence the environment
+  is clean, `kill-all` is for the zombie left by a crash.
+- **`--json` / `--raw`.** The difference between output a reader reads and output a check
+  can gate on. A gate that regexes prose breaks on the release that rewords it.
+- **"Tested in a browser" separated into the three claims it conflates** — the look, the
+  spec suite (`playwright test`, the runner) and the **library** (`class Playwright`),
+  which is an automation API and not a test framework at all. Choosing the library where a
+  runner was wanted is how a project grows a half-runner nobody trusts.
+- **Auth and mocking as solved steps rather than exemptions.** `state-save` / `state-load`
+  (`--storage-state` on the MCP) for a surface behind a login — the state file is a
+  credential and goes where credentials go; `route` / `route-list` / `unroute` for the
+  failure paths a mocked unit test can never show rendering.
+- **The loop that turns a look into a test that keeps it found:** `generate-locator` on
+  the element the look caught, then `pause-at` / `step-over` / `resume` to watch the new
+  spec see what you saw. A browser finding fixed with no test behind it is a finding
+  scheduled to return.
+- **What the channel can reach**, because recommending a real browser is the widest
+  capability in the matrix: the MCP confines file access to the workspace roots until
+  `--allow-unrestricted-file-access` says otherwise, `--isolated` keeps nothing,
+  `--secrets` exists so a password reaches the browser and not the transcript — and
+  `--allowed-origins` is **not** a security boundary, which is upstream's own wording.
+
+### Measured rather than restated
+
+- **The MCP's tool list is capability-gated: 24 tools by default, 42 with
+  `--caps vision,pdf,devtools`** — counted by starting the server and calling `tools/list`,
+  not read off a page. `browser_start_tracing`, `browser_start_video` and
+  `browser_pdf_save` are **absent** from a default server. A doctrine naming them without
+  `--caps` sends an agent to a tool that is not there, and the agent concludes the doctrine
+  is stale rather than the server narrow. The page current at the time also listed route,
+  cookie and localStorage tools this version does not ship at all — which is why the CLI is
+  what this file names for state and mocking.
+- Every CLI command and flag in the new file was checked against `playwright-cli --help`
+  before it shipped, `--persistent` included, which lives on `open` rather than at the top
+  level.
+
+### Corrected before merge, by the reader
+
+- **`npx playwright-cli --help` — this file's own re-derivation command — did not run.**
+  Outside a project that has already installed it, npm resolves the bare `playwright-cli`
+  to **somebody else's package**: Microsoft's, deprecated in favour of this one, latest
+  `0.262.0` against `@playwright/cli`'s `0.1.18`. The line sat inside the sentence that is
+  the whole file's evidentiary warrant. It now says `npx @playwright/cli@latest --help`
+  and explains the trap.
+- **`state-save .auth/state.json` fails on a directory that does not exist** — real exit 1,
+  `ENOENT`. The recipe gained the `mkdir -p` it always needed.
+- **The prescribed verdict quoted a filtered number as the page's request count.**
+  `requests` hides successful static resources by default and says so in its own footer.
+  Failures are listed either way, so *no status ≥ 400* survives and *"14 requests"* is
+  gone.
+
+### Guards
+
+Guards: 318 → **322**. Property checks: 9 → 9. Two checks: a stage that asks for a browser
+channel must **link** the mechanism, and the mechanism must keep the whole look in one
+runnable fence inside the section the stages point at.
+
+**Both shipped weaker first, and the independent reader `R-005` requires broke both.**
+The pointer check tested the substring `browser.md`, so `<!-- browser.md -->` — invisible
+once rendered — satisfied it while the stage named no reachable mechanism. The recipe
+check searched the whole file, so the four commands could be parked in a fence captioned
+*"the ones this file tells you never to run"*, every needle intact and the recipe deleted;
+it also accepted `open` off an incidental mention in the session table. An earlier draft
+had already been caught by a `\b` that let `console-messages` satisfy `console`, and
+`tdd.md` could drop both its pointers because only `stages.md` was read.
+
+**The scope is now written down rather than implied.** An anti-recipe *inside* the right
+section still passes: no text check separates *run these four* from *never run these four*,
+because the difference is the prose. Three drafts were spent proving that; the fourth
+stopped and filed `B-073`. `B-074` carries the other hole the reader found — a stage can
+demand the look while naming no channel, and nothing looks at it.
+
 ## v1.55.0 — the browser step gets a second channel, and the table that names it stops truncating itself
 
 The bundle has told every web project to check the rendered surface since v1.36.0, and

package/CONTRIBUTING.md

@@ -479,6 +479,32 @@ The two checks share one compiled pattern for that reason — two copies would d
 the drift is silent in precisely the direction that hurts.
 *(guard: `pipes where the header has` and `names no stage its second cell`)*
 
+**55. A stage that demands a look at the rendered surface LINKS the mechanism, and the
+mechanism keeps the whole look in one runnable block.** From v1.36.0 to v1.55.0 stages 5,
+6 and 8 required the browser and pointed only at which companion to install, so the
+requirement had no *how* anywhere in the bundle — the shape that lets a run report
+*checked in a browser* while meaning *ran the unit tests*. Every stage naming a browser
+channel, and `tdd.md` too, must **link** `references/browser.md`, and that file must keep
+one fenced block showing `open`, `snapshot`, `console` and `requests` together.
+
+Both halves are stated that precisely because the first draft of each was weaker and an
+independent reader broke both. The stage check tested the substring `browser.md`, and
+`<!-- browser.md -->` — invisible once rendered — satisfied it. The mechanism check
+searched the whole file, so the four commands could be parked in a fence captioned *"the
+ones this file tells you never to run"* with every needle intact and the recipe deleted;
+it also accepted `open` off an incidental mention in the session table. Requiring *one
+fence with all four* was the second draft and fell to the same reader: a fence captioned
+*"never run these"* holds all four. No text check separates a recipe from an anti-recipe,
+so the check is **scoped to the section** — the recipe must live under *The look, as
+commands you can run*, and renaming that heading fails the build, which is correct: the
+section is the contract. **What it does not claim:** an anti-recipe written inside that
+same section still passes. Three drafts were spent trying to close that with a pattern;
+the fourth wrote the limit down instead (`B-073`), because the difference between *run
+these* and *never run these* is prose, and prose is R-005's job. The move needle allows the `--json`, `--raw` and `-s=` prefixes,
+because this same file recommends them and a check that fails its own advice gets edited
+out rather than satisfied.
+*(guard: `does not LINK references/browser.md` and `has no single fenced block showing the whole`)*
+
 **53. Publishing a retro insight is opt-in, enumerated, and its own example obeys its
 own rules.** `retro.publish` is off when absent — opening an issue in another repository
 is an outward act, and a generic flag is not a specific authorization. The redaction

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 |
@@ -131,6 +131,7 @@ until it is installed.
 | 4 Plan | [`planning.md`](plugins/task-pipeline/skills/task-pipeline/references/planning.md) — zero-context tasks, parallel groups, no placeholders |
 | 5 Build | [`build.md`](plugins/task-pipeline/skills/task-pipeline/references/build.md) + [`review.md`](plugins/task-pipeline/skills/task-pipeline/references/review.md) — isolation, ledger, subagent loop, review rubric, fix loop |
 | 5–6 TDD | [`tdd.md`](plugins/task-pipeline/skills/task-pipeline/references/tdd.md) — the iron law, red/green/refactor, the suite gate |
+| 5, 6, 8 The browser | [`browser.md`](plugins/task-pipeline/skills/task-pipeline/references/browser.md) — the ref model both channels share, the four commands the look is made of, sessions, and the three different things *"tested in a browser"* means |
 | 10 Acceptance | [`acceptance.md`](plugins/task-pipeline/skills/task-pipeline/references/acceptance.md) — REQ coverage table, evidence rules, the closing question |
 | 10 + any audit | [`audit.md`](plugins/task-pipeline/skills/task-pipeline/references/audit.md) — the L0→L7 ladder and its seams, axis rotation, ratchets, proven checks |
 | any loop | [`loop-guard.md`](plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md) — churn detection, caps, the break protocol |

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.55.0 |
+| **Version** | 1.57.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.55.0",
+  "version": "1.57.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.55.0",
+  "version": "1.57.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -60,6 +60,7 @@ gate stops until it is installed.
 | 4 Plan | `references/planning.md` |
 | 5 Build (worktree, subagents, fix loop) | `references/build.md` + `references/review.md` |
 | 5–6 TDD + suite gate | `references/tdd.md` |
+| 5, 6, 8 The browser — the look, the spec suite, and the difference | `references/browser.md` |
 | 10 Acceptance (REQ close-out) | `references/acceptance.md` |
 | 10 Retrospective (the run's last act) | `references/retrospective.md` |
 | 10 + any audit (what's *missing*) | `references/audit.md` |
@@ -251,11 +252,11 @@ capable available — see `references/model-tiering.md`).
 | 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 |
-| 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, [`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 |
+| 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; absent → call it an HTTP response, which is its honest name) | auto |
+| 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 |
 | 9 | Docs + wiki | every stale row of the stage-0 source ledger updated; **the propagation matrix walked for every change type this run produced** — the ledger names what you read, the matrix names what you owe — every settled thing recorded with an id, every answered question resolved, and **the documentation gate green with its ratchet counts printed**; docs synced; wiki synced; **the code graph refreshed where one exists** and checked against the docs (a hub no doc names, a doc naming a node the graph lost); **every number computed rather than restated, every named command or file resolvable** ([`references/learned.md`](references/learned.md)); the carry-over count printed beside the verdict | auto |
 | 10 | **Acceptance** | ladder walk ran, its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; ledger has no unresolved row; **axis rotation recorded** (new findings vs self-inflicted, rule 1 of [`references/learned.md`](references/learned.md)), **every closure verified against the artefact rather than the document describing it**, **each correction swept across its class**, **every deferral a printed ratchet rather than a TODO**; **in a multi-repository project, every repository is clean, pushed and pointed at** (below); **the hand-back is written** — the request quoted as given, progress against it, what was solved, what surfaced unasked, waiting decisions asked here, and the ambiguity count computed ([`references/progress.md`](references/progress.md)); **the environment is given back** — all eight classes enumerated, what this run started ended and verified by re-enumerating rather than by the teardown's reply, an earlier run of this project ended only when **provably spent**, anything this project does not own reported rather than ended, written as a `holds:` line (`references/residue.md`); operator signs off; **every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, and its ratchet counts are printed beside the verdict**; **the retrospective written last, and in order — the run stamped with its commit FIRST (the cold-retirement trigger reads that stamp), then the prune with the list at or under its cap and every deletion logged, then the entry; every deletion and every entry carrying its commit, entries older than five stamps rotated into the archive, counts printed** ; **every disclosure printed beside the verdict** — `abstained` (what the run declined to claim) and `unlooked` (what a check never looked at), neither a ratchet, neither with a floor, neither ever a target ([`references/gates.md`](references/gates.md) → *Disclosures*) | manual |
 

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/browser.md

@@ -0,0 +1,278 @@
+# The browser — how the look is actually taken, and how a suite is run beside it
+
+[`companion-skills.md`](companion-skills.md) decides **which** channel a project has
+and how to install it. This file is **how to use one**: the model both channels share,
+the commands the look is made of, and the three different things people mean when they
+say *"tested in a browser"*.
+
+Stages 5, 6 and 8 ([`stages.md`](stages.md)) and [`tdd.md`](tdd.md) demand a look at the
+rendered surface. Until this file existed, they demanded it and named no mechanism —
+which is how a run says *I checked the browser* and means *I ran the unit tests*.
+
+> **Every command and flag below was read from the tool's own `--help`**, not from a
+> vendor page. Where the two disagreed, `--help` won and the page was wrong — see
+> *Rationalizations*. Re-derive before quoting:
+> `npx @playwright/cli@latest --help` and `npx @playwright/mcp@latest --help`.
+>
+> **Use the scoped name with `npx`.** `npx playwright-cli --help` fails outside a project
+> that has already installed it (`could not determine executable to run`), and the bare
+> `playwright-cli` on npm is **somebody else's package** — Microsoft's, deprecated in
+> favour of this one. The binary is called `playwright-cli`; the package is
+> `@playwright/cli`. Every `playwright-cli …` line below assumes it is installed and on
+> PATH, which is what the matrix's install line does.
+
+## Contents
+
+- The one model: a tree, and a ref
+- The look, as commands you can run
+- Sessions, and why an agent needs them
+- Reading a look vs gating on one
+- "Tested in a browser" is three different claims
+- Getting past a login, and past a backend
+- When the look finds something: debugging the spec that missed it
+- Evidence a reader can open
+- What the channel can reach — the part a recommendation owes you
+- Rationalizations
+
+## The one model: a tree, and a ref
+
+**Both channels drive the page through its accessibility tree, not its pixels.** You ask
+for a snapshot, you get structured text — roles, names, and a **ref** per interactive
+element (`e5`, `e12`) — and you act on the ref.
+
+```
+snapshot  ->  button "Checkout" [ref=e12]  ->  click e12
+```
+
+Three consequences the doctrine rests on:
+
+- **A look costs a page of text and no vision model.** This is why the pipeline can ask
+  for one at three stages without the cost being an argument. A `screenshot` exists in
+  both channels and *is* pixels — take one for a human to look at, not for you to read.
+- **The ref is a fact about the page as rendered**, so `click e12` after a snapshot is
+  deterministic in a way a coordinate never is.
+- **A ref that no longer resolves is a finding, not an error to retry past.** The element
+  moved, or never rendered. That is exactly the class stage 6 says a green suite cannot
+  see. Re-snapshot, read what changed, and report it — do not hunt for a selector that
+  makes the command succeed.
+
+Refs come from the **latest** snapshot. Act, then snapshot again before using a ref from
+before the act.
+
+## The look, as commands you can run
+
+The pipeline asks for the same four things every time: **open it, snapshot it, read the
+console, read the network.** In the CLI that is literally four commands:
+
+```bash
+playwright-cli open http://localhost:3000/checkout
+playwright-cli snapshot
+playwright-cli console warning     # min-level: only warnings and errors
+playwright-cli requests            # then: request <n> for headers, body, response
+```
+
+The MCP is the same four moves under different names: `browser_navigate`,
+`browser_snapshot`, `browser_console_messages`, `browser_network_requests`.
+
+**Quote what you read, not that you looked.** *"Console clean, all requests fine"* is a
+claim. *"`console warning` → empty; `requests` → no status ≥ 400"* is the same claim with
+its command attached, and it is the one that belongs in a gate verdict.
+
+**Do not quote the request count as the page's count.** `requests` hides successful static
+resources by default and says so in its own footer (*"N static request(s) not shown"*);
+`requests --static` includes them. Failures are listed either way — a 404'd stylesheet
+appears without the flag — so *no status ≥ 400* is a safe claim and *14 requests* is not.
+
+`chrome-devtools` takes the identical four moves — `navigate_page`, `take_snapshot`,
+`list_console_messages`, `list_network_requests` — which is why the matrix ranks neither:
+the look is the same look.
+
+## Sessions, and why an agent needs them
+
+**The CLI keeps a browser alive between commands.** That is the whole reason the four
+commands above compose: `snapshot` sees the page `open` navigated to, and `click e12`
+acts on the element that snapshot named. A tool that launched a browser per invocation
+would lose the page, and every ref with it.
+
+| Need | Command |
+|---|---|
+| Two surfaces at once without shared cookies | `playwright-cli -s=checkout open …` and `-s=admin open …` |
+| See what is still running | `playwright-cli list` |
+| Tidy up at the end of a stage | `playwright-cli close-all` |
+| A stale or zombie process after a crash | `playwright-cli kill-all` |
+
+**A run that opened a browser closes it**, the same rule the pipeline applies to every
+other resource it starts ([`residue.md`](residue.md)). `list` before you claim the
+environment is clean — the reply is the evidence, not the `close-all` you typed.
+
+## Reading a look vs gating on one
+
+Two global flags change what the output is for:
+
+- **`--json`** — the full response as JSON. This is what a script parses, and therefore
+  what a *check* can be built on.
+- **`--raw`** — the result value alone, no status wrapper. For one value in a shell
+  variable.
+
+Default output is for a reader. If you find yourself regexing the default output in a
+gate, you wanted `--json`; a check that parses prose breaks on the release that reworded
+it ([`gates.md`](gates.md)).
+
+## "Tested in a browser" is three different claims
+
+Keeping these apart is the entire point of the stage-6 pair, and conflating them is the
+commonest way a run reports a green it does not have.
+
+| | What it is | What it proves | Where it counts |
+|---|---|---|---|
+| **The look** | an agent driving a page: open, snapshot, console, network | that this surface renders, right now, and what the browser said while it did | the **look**, stage 6 — recommended, never a gate |
+| **The spec suite** | `playwright test` — the **test runner** | that the assertions someone wrote still hold, on the paths someone thought to write | the **suite** half of the stage-6 gate, counted with every other test |
+| **The library** | `require('playwright')` — `chromium`/`firefox`/`webkit`, `devices`, `request`, `selectors` | whatever your own script asserts; it is an automation API, not a test framework | wherever the project already runs it |
+
+The library and the runner are **separate APIs** — a script built on `chromium.launch()`
+has no `expect`, no fixtures, no reporter, and no retry. Choosing the library where a
+runner was wanted is how a project ends up with a bespoke half-runner nobody trusts.
+
+The minimal library shape, for reading a script that already exists:
+
+```js
+const { chromium } = require('playwright');
+const browser = await chromium.launch();
+const page = await browser.newPage();
+await page.goto('http://example.com');
+await browser.close();
+```
+
+**A green spec suite never discharges the look.** It asserts what was written down; the
+console error nobody asserted on is precisely what the look is for. This is `DEC-0004`
+and it is the reason both halves exist.
+
+## Getting past a login, and past a backend
+
+A surface behind auth is the usual reason a run skips the look. Both channels solve it,
+and neither needs a password in a transcript.
+
+**Storage state — log in once, replay it.**
+
+```bash
+mkdir -p .auth                                  # state-save does not create it
+playwright-cli open https://app.example.com/login
+#  … sign in by hand, or drive the form …
+playwright-cli state-save .auth/state.json      # cookies + localStorage
+playwright-cli state-load .auth/state.json      # every later look starts signed in
+```
+
+The MCP takes the same file at startup: `--storage-state <path>`. Point the spec suite
+at it too and the suite and the look agree about who is signed in.
+**The state file is a credential.** It goes where credentials go, never into the
+repository.
+
+**Routes — make the backend say what you need it to.**
+
+```bash
+playwright-cli route '**/api/quote' --status 500   # then look at the error state
+playwright-cli route-list
+playwright-cli unroute '**/api/quote'
+```
+
+This is how a failure path gets a look at all. `route` is also the honest way to check
+that a 404'd bundle or a 500'd call *renders* as something a user can act on — which no
+unit test with a mocked fetch will ever tell you.
+
+Storage families exist per layer when you need to reach past the whole state file:
+`cookie-list|get|set|delete|clear`, and the same verbs for `localstorage-` and
+`sessionstorage-`.
+
+## When the look finds something: debugging the spec that missed it
+
+The look found a defect the suite did not. Stage 6 says fix it here — and the fix has two
+halves: the code, and the assertion that should have caught it.
+
+```bash
+playwright-cli generate-locator e12     # a locator for the element the look found
+playwright-cli highlight e12            # show it on the page (--hide to clear)
+```
+
+Drop that locator into a new spec, then drive the spec itself:
+
+```bash
+playwright-cli pause-at src/checkout.spec.ts:42   # run up to this line and stop
+playwright-cli snapshot                            # the page as the test sees it there
+playwright-cli step-over
+playwright-cli resume
+```
+
+That loop is what turns *"the look caught it"* into *"the suite catches it next time"* —
+which is the only reason the look's finding stops recurring. `run-code` and `eval` are
+there for the case a question is faster answered in the page than through a command.
+
+## Evidence a reader can open
+
+A verdict that says *the surface renders* is worth what its attachment is worth.
+
+| Artefact | Command | Use it for |
+|---|---|---|
+| Screenshot | `screenshot [ref]` | one state, for a human |
+| Trace | `tracing-start` … `tracing-stop` | a failure someone else has to reproduce |
+| Video | `video-start [file]`, `video-chapter <title>`, `video-stop` | a flow, or a regression that only appears in motion |
+| PDF | `pdf` | a printable surface that is itself the deliverable |
+
+`video-show-actions` annotates each action on the page with a callout naming it, which is
+what makes a recording readable by someone who did not run it.
+
+The MCP's equivalents are `browser_take_screenshot`, `browser_start_tracing` /
+`browser_stop_tracing`, `browser_start_video` / `browser_stop_video`, `browser_pdf_save`,
+written under `--output-dir` — **and all but the screenshot are behind `--caps`.** See
+below: the tool list you read about is not the tool list you get.
+
+**Attach the artefact or drop the claim.** A trace nobody can open is prose.
+
+## What the channel can reach — the part a recommendation owes you
+
+This bundle recommends handing an agent a real browser. That is a wider capability than
+anything else in the matrix, and the boundary is worth stating rather than discovering.
+
+- **The MCP restricts file access to the workspace roots** (cwd when no roots are
+  configured) and blocks navigation to `file://` by default. `--allow-unrestricted-file-access`
+  removes both. Read that flag as what it says.
+- **`--allowed-origins` / `--blocked-origins` are not a security boundary**, and upstream
+  says so in its own help: they do not survive redirects. Do not use them as one.
+- **`--isolated` keeps the profile in memory**, so nothing persists past the session —
+  the right default for a look at someone else's site. The opposite is deliberate and
+  spelled differently per channel: `--user-data-dir <path>` on the MCP,
+  `open --persistent` (or `open --profile <path>`) on the CLI.
+- **`--secrets <path>`** exists so a credential reaches the browser without reaching the
+  transcript. Use it rather than typing the password into a `fill`.
+- **`--extension` / `attach`** connect to a browser **you are already using**, with your
+  sessions in it. That is occasionally exactly what you want and is never the default
+  for an unattended run.
+
+**The MCP's tool list is capability-gated, and the default is the small one.** Asking
+the running server rather than a page: **24 tools by default, 42 with
+`--caps vision,pdf,devtools`.** Tracing, video and PDF — `browser_start_tracing`,
+`browser_start_video`, `browser_video_chapter`, `browser_pdf_save` — are **not present**
+until `--caps` names them, and neither are the coordinate-mouse tools. A doctrine that
+sends an agent to `browser_start_tracing` on a default server sends it to a tool that is
+not there, and the agent concludes the doctrine is stale rather than the server narrow.
+Re-derive rather than trust this paragraph: start the server and call `tools/list`.
+
+Both counts above were measured on `@playwright/mcp` 0.0.79 by listing the server's own
+tools. The vendor page current at the time listed tool groups this version does not ship
+at all — routes, cookies and localStorage among them — which is why the CLI is what this
+file names for state and mocking.
+
+The MCP runs **headed** by default; the CLI is headless unless you pass `open --headed`.
+On a CI box, headed is the failure you will spend an hour on.
+
+## Rationalizations
+
+| The excuse | Why it fails |
+|---|---|
+| *"`playwright test` is green, the surface is checked."* | The suite asserts what someone wrote down. `DEC-0004`: it is the coverage half, never the look. |
+| *"I took a screenshot, so I looked."* | A screenshot is pixels you did not read. The look is `snapshot` + `console` + `requests`, and the verdict quotes them. |
+| *"The click failed, I'll find a better selector."* | A ref that stopped resolving **is the finding**. Re-snapshot and report what moved. |
+| *"The docs say the CLI has no `tracing`."* | A vendor page is a claim; `--help` is the tool. This file was written against `--help` **because** a page-derived claim shipped here and was wrong. |
+| *"The tool list is in the docs."* | The page listed tools this version does not ship, and omitted that tracing, video and PDF need `--caps`. Ask the server: 24 tools default, 42 with all caps. |
+| *"It's behind a login, so the look isn't possible."* | `state-save` / `state-load`, or `--storage-state`. Auth is a solved step, not an exemption. |
+| *"No browser channel is installed, so the step doesn't apply."* | The step still applies; the claim weakens. Say *verified by reading the diff* and let the close-out record it as the weaker claim it is. |
+| *"I closed the browser."* | `list` is the evidence. The command you typed is not the state you left ([`residue.md`](residue.md)). |

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/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/portability.md

@@ -76,6 +76,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | **The canons** — what makes a claim documentation, and the index that routes to each | `references/documentation.md`, `../evidence-docs/SKILL.md` |
 | **Effect verification** — the `verified-by:` contract and the rubric item that blocks | `references/build.md`, `references/review.md` |
 | The TDD iron law and the suite gate | `references/tdd.md` |
+| How the browser look is taken, and how a spec suite sits beside it | `references/browser.md` |
 | The REQ coverage table, evidence rules, the closing question | `references/acceptance.md` |
 | How the host project's own conventions are read | `references/conventions.md` |
 | Which companions exist, what is required, self-currency | `references/companion-skills.md` |

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

@@ -378,7 +378,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,10 +397,16 @@ 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 ([`companion-skills.md`](companion-skills.md)): after a
+  one, whichever answers first (**how**: [`browser.md`](browser.md); which:
+  [`companion-skills.md`](companion-skills.md)): after a
   task that changes a rendered surface, load it, take a snapshot and read the
   console and the network log **before the task is marked DONE** — a component can be
   correct and land under a fixed header, and a review of the diff cannot see that.
@@ -415,7 +425,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
@@ -443,7 +455,8 @@ never that the work was skipped quietly.
   page rendered — a component can be correct and land under a fixed header, a request
   can 404 while every unit test mocks it, and a console error costs nothing at test
   time. Where a browser channel is connected — `playwright` **or** `chrome-devtools`,
-  either one ([`companion-skills.md`](companion-skills.md)):
+  either one ([`browser.md`](browser.md) is the four commands this sentence means;
+  [`companion-skills.md`](companion-skills.md) is which channel):
   load the surface, take a snapshot, and read **the console and the network log**
   before calling it green. Absent, say the surface was verified **by reading the
   diff** — that is a weaker claim and the close-out records it as one, rather than
@@ -518,7 +531,7 @@ never that the work was skipped quietly.
   answered; it says nothing about whether the page rendered, whether a bundle 404'd,
   or whether the console filled with errors on load — all three ship green past a
   health check. Where a browser channel is connected — `playwright` **or**
-  `chrome-devtools`, either one — load the deployed URL and read
+  `chrome-devtools`, either one ([`browser.md`](browser.md)) — load the deployed URL and read
   the console and the network log; quote what you read, not that you looked
   ([`companion-skills.md`](companion-skills.md)). Absent → say the check was an HTTP
   response only, which is the honest name for it.

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

@@ -113,7 +113,13 @@ database created ten seconds ago" are different claims, and only the second one
   suite whose runner happens to be a browser: it still asserts only what someone wrote
   down. It belongs to the coverage half of the gate, and the sentence above still needs
   a page that was opened and read. The two fail differently, which is the entire reason
-  to keep both.
+  to keep both — and [`browser.md`](browser.md) separates them from a third thing they
+  are both confused with, the Playwright **library**, which is an automation API and not
+  a test framework at all.
+- **The look that found it writes the assertion that keeps it found.** `generate-locator`
+  on the element the look caught, then a spec around it, then `pause-at` to watch the
+  new spec see what you saw ([`browser.md`](browser.md)). A browser finding fixed with
+  no test behind it is a finding scheduled to return.
 
 ## Stage 6 — consolidation and the suite gate