task-pipeline-skill 1.54.0 → 1.56.0

package/CHANGELOG.md

@@ -1,5 +1,178 @@
 # Changelog
 
+## 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
+it named exactly one way to do it: the `chrome-devtools` MCP, behind a plugin install.
+One channel is a single point of failure for a step the pipeline asks for at three
+stages, and the operator's report was the ordinary one — it lags.
+
+Playwright now sits beside it, and **neither is ranked**. They do the same look; the
+difference is stated as capability rather than quality, so a run picks by need instead of
+by taste. `playwright` costs the least per look — its own upstream sells the CLI on not
+loading large tool schemas and verbose accessibility trees into the model context, and
+both of its channels snapshot the accessibility tree rather than pixels.
+`chrome-devtools` is the one that reaches past the page: `lighthouse_audit`, performance
+traces and heap snapshots have no Playwright equivalent, and `seo-aeo-audit` builds on
+the first of them.
+
+### Added
+
+- **`playwright` as a companion**, with two install paths that need no plugin:
+  `npm install -D @playwright/cli@latest` (then `npx playwright-cli`) and
+  `claude mcp add playwright npx @playwright/mcp@latest`. Verified against the registry
+  at release time: `@playwright/cli` 0.1.18, `@playwright/mcp` 0.0.79.
+- **One detection rule for both channels instead of two that drift**, with the
+  tie-breaker written down: `playwright` where the project already runs it or context
+  budget is tight, `chrome-devtools` where the question is Lighthouse, a trace or a
+  heap snapshot. A run that ranks them has invented a fact the matrix does not carry.
+- **Stop at the first channel that answers.** Both open the page and read the console
+  and the network log; running the look twice is a cost with no second fact.
+- **A browser test suite is the other half of the gate, never a substitute for the
+  look** (stages 6, `tdd.md`, `SKILL.md`). `playwright test` in CI is a suite whose
+  runner happens to be a browser: it proves what someone thought to assert, and cannot
+  report the console error nobody asserted on or the element that moved under a header.
+  The suite is counted as coverage; the look is still a page opened and read. This
+  closes `OQ-0003` as `DEC-0004`.
+- **What the look finds is fixed in the stage that found it** (stages 5 and 6). A
+  browser finding parked for later is the diff-review verdict wearing a screenshot.
+
+### Fixed
+
+- **Three claims this release shipped as facts, corrected against the tool's own
+  `--help`.** The independent reader measured them. *"Costs the least per look"* was
+  upstream's CLI-against-MCP comparison restated as this repo's CLI-against-`chrome-devtools`
+  fact — now attributed and scoped. *"Both channels snapshot the accessibility tree rather
+  than pixels"* was true of the default and denied a `screenshot` both channels ship —
+  now says which is the default and what the other costs. *"`chrome-devtools` alone
+  reaches performance traces"* was simply false: `playwright-cli tracing-start` records
+  one. Only the Lighthouse and heap-snapshot legs are exclusive, and the honest
+  difference on traces is that one channel **analyses** what the other only records.
+- **The look was called a half of the gate in the same file that calls it never a gate.**
+  Stage 6's new paragraph made the browser look sound like gate membership while the
+  GATE bullet above it, both matrix rows and `SKILL.md` all keep it recommended and
+  degradable. Stage 5 had the mirror defect: *fixed in this task, not filed* against a
+  GATE bullet that explicitly permits parking with a ruling. Both now say the thing the
+  gate actually enforces.
+
+- **A pipe inside a matrix cell silently disabled the guard that reads it.** Both
+  readers of `companion-skills.md`'s table split cells on `|` and do not decode `\|`,
+  so an escaped pipe ends its cell early and hands the next check a different column.
+  The `graphify` row had carried `graphify query\|affected\|god-nodes` since it was
+  added: the matrix→stages check has been reading that row's second cell as `affected`,
+  parsing no stage numbers out of it, and passing **without comparing anything** — a
+  guard quiet because its input was truncated, which reads exactly like a guard that
+  looked and agreed. Found while planting a defect into the new `playwright` row and
+  watching the check stay silent. There is now a guard for the class, probed both ways,
+  and the `graphify` row is comma-separated. The umbrella hit the same class from the
+  other side in `B-40` (an *un*escaped pipe adding a column), which is the second
+  sighting that makes it a check rather than a third ledger row.
+
+### Guards
+
+Guards: 315 → **318**. Property checks: 9 → 9. Two new checks over the companion matrix,
+each watched failing against a plant: the row's cell count against the header (which
+catches a bare pipe and an escaped one alike), and a row that derives no stage at all.
+The first draft of the first check tested `\|` only, and the independent reader `R-005`
+requires broke it with a bare pipe in one move — with a control proving the hole masked
+real matrix→stages drift. The second check exists because the same reader measured every
+row and found `agent-sync` deriving nothing from `stage-10`, one row below the `graphify`
+row this release set out to fix.
+
 ## v1.54.0 — a run cannot reach acceptance with a stage it never stamped
 
 The 2026-08-13 artifact-root run closed at stage 10 with `0,1,2,5,6,7,8,9,10` recorded

package/CONTRIBUTING.md

@@ -464,6 +464,47 @@ VISUAL — each with its owning skill, because the first reads matrix **row name
 the copy half lives inside super-ux's own cell, exactly where it was invisible.
 *(guard: `has not heard of it` and `names no owner`)*
 
+**54. The companion matrix's own cells must be readable, and every row must derive a
+stage.** Every check that reads that table splits a cell on `|`, and none of them decodes
+the escaped form. So one extra pipe anywhere in a row — `\|` or bare — ends its cell early
+and hands the next check a different column, which is how the `graphify` row spent every
+release since it was added with its stage pointers **never compared**: the check derived
+an empty set and reported agreement. The cell count is now compared against the header,
+because that is blind to how the pipe was written, and the first draft of this guard was
+not — it tested `\|` only and an independent reader broke it with a bare one in a single
+move. Separately, the outcome is asserted directly: a row whose *"needed for"* cell
+derives **no** stage fails, because a pipe is only one road to an empty set and
+`agent-sync` took another, writing `stage-10` where the stage pattern wanted `stage 10`.
+The two checks share one compiled pattern for that reason — two copies would drift, and
+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

@@ -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 |
@@ -210,14 +211,24 @@ run proved stale is already in the ledger with what's wrong, so "docs updated" m
 the sources the next run will trust — not just the files this change happened to
 touch.
 
-**A web front end gets a browser, not a diff.** Where `chrome-devtools` is connected,
+**A web front end gets a browser, not a diff.** Where a browser channel is connected,
 stages 5–6 load the surface and read the console and the network log before calling it
 green, and stage 8 opens the deployed page instead of trusting a `200`. A green suite
 cannot see a component that renders correctly and lands under a fixed header, a request
-that 404s while every unit test mocks it, or an error that costs nothing at test time.
-Absent, the run says *"verified by reading the diff"* — a weaker claim, recorded as one.
-Install: `/plugin install chrome-devtools-mcp@claude-plugins-official`. It is never a
-gate, and a CLI, a library or a backend service is never offered it.
+that 404s while every unit test mocks it, or an error that costs nothing at test time —
+and neither can a **browser test suite**, which asserts what someone wrote down and is
+counted as coverage rather than as the look. Absent, the run says *"verified by reading
+the diff"* — a weaker claim, recorded as one.
+
+There are **two channels and either is enough**, ranked by nothing: `playwright`
+(`npm install -D @playwright/cli@latest`, or
+`claude mcp add playwright npx @playwright/mcp@latest`) needs no plugin and is already
+there on a project that runs Playwright, and its CLI half puts no tool schema in the
+context window; `chrome-devtools`
+(`/plugin install chrome-devtools-mcp@claude-plugins-official`) is the one that reaches
+past the page to Lighthouse and heap snapshots, and analyses a performance trace rather
+than only recording one. Neither is a gate,
+and a CLI, a library or a backend service is never offered either.
 
 **The wiki is [obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (Karpathy's
 LLM-wiki pattern), and it's the one source that carries *why* across projects and

package/SKILL-CARD.md

@@ -12,9 +12,9 @@ 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.54.0 |
+| **Version** | 1.56.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. 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 |
+| **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` |
 
 ## Risk-tier disclosure
@@ -25,7 +25,7 @@ apply.
 | Indicator | Applies? | What exactly |
 |---|---|---|
 | **Code execution** | **Yes — High** | Ships `templates/docgate.sh` (seeded into the host project as its documentation gate), `bin/task-pipeline.js` and `install.sh` (installers), `test/*.py` and `evals/run.py` (repo checks). None run automatically; the gate is seeded and run by the host project |
-| **MCP server references** | **Yes — High** | Instructions name `context7`, `figma`, `graphify`, `wiki-query`, `wiki-update` and **`chrome-devtools`** — the last one **drives a real browser**: it opens pages, runs scripts in them and reads their console and network traffic, which is a wider capability than the others and is recommended only for projects that have a web front end. All optional; absence degrades a stage, never blocks one, except super-ux on a UI task |
+| **MCP server references** | **Yes — High** | Instructions name `context7`, `figma`, `graphify`, `wiki-query`, `wiki-update` and **two browser channels — `playwright` (CLI `@playwright/cli` or MCP `@playwright/mcp`) and `chrome-devtools`** — the last two **drive a real browser**: they open pages, run scripts in them and read their console and network traffic, which is a wider capability than the others and is recommended only for projects that have a web front end. Either one satisfies the browser step; neither is required. All optional; absence degrades a stage, never blocks one, except super-ux on a UI task |
 | **Tool invocations** | **Yes — Medium** | Instructs bash (git, test runners, the host's lint/deploy commands), file reads and writes, and a `PreToolUse` hook example that runs the docs gate before a commit |
 | **Filesystem access scope** | **Yes — Medium** | Reads and writes inside the host project: `docs/`, `scripts/check-docs.sh`, `.task-pipeline/` scratch, `CONTEXT.md`. Stage 5 creates and removes git worktrees. Writing to **another repository** is treated as outward and requires an explicit go |
 | **Instruction manipulation** | No | Nothing instructs Claude to bypass safety rules, hide actions, or behave conditionally on hidden inputs. Outward and irreversible actions (deploy, publish, PR, editing a shared design file) explicitly require operator authorization |

package/cursor/rules/task-pipeline.mdc

@@ -253,12 +253,19 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
    behavior, never mock behavior. **Web front end? Check the surface in a browser,
    not in the diff.** A green suite cannot see a component that renders correctly and
    lands under a fixed header, a request that 404s while every unit test mocks it, or
-   a console error that costs nothing at test time. With the chrome-devtools MCP
-   connected: load the surface, snapshot it, read the console and the network log,
-   and quote what you read. Without it, say "verified by reading the diff" and treat
-   that as the weaker claim it is. Install once, never a gate:
-   `/plugin install chrome-devtools-mcp@claude-plugins-official`. A CLI, a library or
-   a backend service is never offered it.
+   a console error that costs nothing at test time — and neither can a browser test
+   suite, which asserts what someone wrote down and counts as coverage, not as the
+   look. With a browser channel connected: load the surface, snapshot it, read the
+   console and the network log, and quote what you read. Fix what the look finds
+   before calling the stage green. Without one, say "verified by reading the diff" and
+   treat that as the weaker claim it is. Two channels, either is enough, ranked by
+   nothing: `npm install -D @playwright/cli@latest` (or
+   `claude mcp add playwright npx @playwright/mcp@latest`) needs no plugin, and its CLI
+   half puts no tool schema in the context window;
+   `/plugin install chrome-devtools-mcp@claude-plugins-official` is the one that
+   reaches Lighthouse and heap snapshots, and analyses a trace rather than only
+   recording one. Never a gate. A CLI, a
+   library or a backend service is never offered either.
 7. **Lint + deploy** (manual) — lint clean AND suite green before deploy; deploy is
    outward → explicit user go, or the specific standing authorization recorded in
    the stage-0 brief.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.54.0",
+  "version": "1.56.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.54.0",
+  "version": "1.56.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` |
@@ -253,9 +254,9 @@ capable available — see `references/model-tiering.md`).
 | 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 (`chrome-devtools`, [`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 |
+| 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 (`chrome-devtools`; 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/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/companion-skills.md

@@ -48,8 +48,9 @@ better, plus one that is required only for user-facing work.
 | **context7** (MCP — call tools fully qualified: `context7:resolve-library-id`, `context7:query-docs`) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
 | **Figma** (MCP) | stage 3 UX track, when the project designs visually — super-ux mirrors each `SCR-` screen/state into a frame | Optional, **UI + Figma-on only**. Absent → super-ux degrades to text-only *by itself and never blocks*, so shipping a UI feature with no mockups becomes a silent scope call — which is why the stage-0 sweep decides it | connect the Figma MCP server (`/mcp`, or your claude.ai connectors) |
 | **[obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (`wiki-query`, `wiki-update`) | **stage 0 harvest** (query what's already known) **+ stage 9 sync** | **Recommended** — never a gate; absent → harvest runs on repo docs alone | `pip install obsidian-wiki` → `obsidian-wiki setup --vault /path/to/your/vault` |
-| **[graphify](https://github.com/Graphify-Labs/graphify)** (`/graphify`, `graphify query\|affected\|god-nodes`) | **stage 0 harvest** (reach: what calls this, what breaks if it moves) **+ stage 9 refresh + the graph↔docs divergence check** ([`knowledge-graph.md`](knowledge-graph.md)) | **Recommended** — never a gate; absent → the harvest greps instead, and the divergence axis is unavailable | `uv tool install graphifyy` → `graphify install` → `/graphify .` |
-| **chrome-devtools** (MCP — `list_pages`, `navigate_page`, `take_snapshot`, `take_screenshot`, `evaluate_script`, `list_console_messages`, `list_network_requests`, `lighthouse_audit`) | **stages 5–6 on any project with a web front end** — verify the **rendered** surface rather than the diff: computed layout, console errors, failed requests. **Stage 8** on a deployed web target: load the page and read what the browser did, not what the deploy said | **Recommended** — never a gate; absent → say the surface was verified **by reading the diff** and treat that as the weaker claim it is | `/plugin install chrome-devtools-mcp@claude-plugins-official` (or connect the MCP server directly) |
+| **[graphify](https://github.com/Graphify-Labs/graphify)** (`/graphify`, `graphify query`, `graphify affected`, `graphify god-nodes`) | **stage 0 harvest** (reach: what calls this, what breaks if it moves) **+ stage 9 refresh + the graph↔docs divergence check** ([`knowledge-graph.md`](knowledge-graph.md)) | **Recommended** — never a gate; absent → the harvest greps instead, and the divergence axis is unavailable | `uv tool install graphifyy` → `graphify install` → `/graphify .` |
+| **playwright** (CLI — `playwright-cli open`, `snapshot`, `click`, `type`, and the two this pipeline actually asks for: `console` and `requests`; or MCP — `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_console_messages`, `browser_network_requests`) | **stages 5–6 on any project with a web front end**, and **stage 8** on a deployed target — the same job as the row below: open the surface, snapshot it, read the console and the network log. Its own difference is **the channel a look arrives on**: the CLI is a shell command, so it does not put a tool schema in the context window the way an MCP channel does — that is upstream's own comparison and it is *CLI against MCP*, which makes it a claim about this row's own two halves before it is a claim about the row below. Both channels default to an **accessibility-tree snapshot rather than pixels**, so the ordinary look costs a page of text and no vision model; `screenshot` exists in both and costs one when you ask for it | **Recommended** — never a gate; absent → say the surface was verified **by reading the diff** and treat that as the weaker claim it is | CLI: `npm install -D @playwright/cli@latest` → `npx playwright-cli --help` (or `npm i -g` for the global binary; `playwright-cli install --skills` adds its agent skills, `--global` to the home directory). MCP: `claude mcp add playwright npx @playwright/mcp@latest` |
+| **chrome-devtools** (MCP — `list_pages`, `navigate_page`, `take_snapshot`, `take_screenshot`, `evaluate_script`, `list_console_messages`, `list_network_requests`, `lighthouse_audit`, `performance_start_trace`, `take_heapsnapshot`) | **stages 5–6 on any project with a web front end** — verify the **rendered** surface rather than the diff: computed layout, console errors, failed requests. **Stage 8** on a deployed web target: load the page and read what the browser did, not what the deploy said. Its own difference is **reach past the page**: a Lighthouse category (`lighthouse_audit`, which `seo-aeo-audit` builds on) and a heap snapshot have no equivalent in the row above. A performance trace has one — `playwright-cli tracing-start` records one — but only this row's arrives with `performance_analyze_insight` over it | **Recommended** — never a gate; absent → say the surface was verified **by reading the diff** and treat that as the weaker claim it is | `/plugin install chrome-devtools-mcp@claude-plugins-official` (or connect the MCP server directly) |
 | **[agent-sync](https://github.com/ssheleg/agent-sync)** (`/agent-sync`, **≥ 1.3.0** — `finish` did not exist before it, so an older install turns the stage-10 close-out into a command that is not there) | **guarded registers** — a lease before writing one, `reserve` before minting an id, `reconcile`/`record` for intent vs as-built, and `finish` for the stage-10 multi-repository close-out ([`documentation.md`](documentation.md)) | **Recommended** — never a gate. Absent → the run is **`ungated`** and must say so out loud; the discipline still applies, only the arbitration is missing | `npx sshlg-skills install` |
 | ~~superpowers~~ | — | **Not a dependency.** Stages 2/4/5/6 run on the built-in doctrine above. See *Optional bridge* | — |
 | ~~grill-me / grilling~~ | — | **Not a dependency.** The stage-0 grill is built in (`references/grill.md`) | — |
@@ -112,9 +113,20 @@ Pipeline companions (stage doctrine is built in — nothing to install for it):
                            /graphify .        (once, in this project)
                          (running without it — no reach queries, no graph↔docs
                           divergence check)
+  ✗ playwright         — recommended when this project has a web front end.
+                         One of TWO channels that do the same look; either is
+                         enough, and a project that already runs Playwright has
+                         this one for free:
+                           npm install -D @playwright/cli@latest   (then npx playwright-cli)
+                           claude mcp add playwright npx @playwright/mcp@latest
+                         (running without it — see the line below; without BOTH,
+                          the surface is verified by reading the diff)
   ✗ chrome-devtools    — recommended when this project has a web front end:
                          stages 5-6 check the RENDERED surface instead of the
-                         diff, stage 8 reads what the browser did after a deploy:
+                         diff, stage 8 reads what the browser did after a deploy.
+                         The other channel; it alone reaches lighthouse_audit
+                         and heap snapshots, and analyses a trace rather than
+                         only recording one:
                            /plugin install chrome-devtools-mcp@claude-plugins-official
                          (running without it — the surface is verified by reading
                           the diff, and the close-out says so in those words)
@@ -147,13 +159,29 @@ Rules:
   `wiki-query`/`wiki-update`. Present → say `✓ ready` and use it in the harvest.
   Absent → print the two install lines **once** and continue; never ask twice in a
   run and never block a stage on it ([`knowledge-sources.md`](knowledge-sources.md)).
-- **chrome-devtools**: flag it only when the project **has a web front end** — an
-  `index.html`, a `package.json` naming a browser framework, a `docs/ux/screens.md`, or
-  a deploy target that serves pages. Detect via a resolving
-  `mcp__chrome-devtools__list_pages` (or the plugin's tools under any prefix the host
-  uses). Present → `✓ ready`. Absent → print the install line **once** and continue; it
-  is never a gate. **A CLI, a library or a backend service does not flag it** — offering
-  a browser to a project with no browser is how a recommendation is taught to be noise.
+- **The browser channels — `playwright` and `chrome-devtools`, one rule for both.**
+  Flag them only when the project **has a web front end** — an `index.html`, a
+  `package.json` naming a browser framework, a `docs/ux/screens.md`, or a deploy target
+  that serves pages. **A CLI, a library or a backend service does not flag either** —
+  offering a browser to a project with no browser is how a recommendation is taught to
+  be noise. Detect `playwright` via a resolving `playwright-cli` binary, a
+  `@playwright/cli` or `@playwright/mcp` dependency, a `playwright.config.*`, or
+  `mcp__playwright__browser_navigate`; detect `chrome-devtools` via a resolving
+  `mcp__chrome-devtools__list_pages` (either one under whatever prefix the host uses).
+  Present → `✓ ready`. Absent → print its install lines **once** and continue; neither
+  is a gate.
+- **They are two channels for one look, and the run needs one of them, not both.**
+  Both open the page, snapshot it and read the console and the network log, so **stop
+  at the first one that answers** — running the same look twice is a cost with no
+  second fact. Where neither is present, say the surface was verified **by reading the
+  diff**; where both are, the tie-breakers are stated rather than left to taste:
+  **`playwright` when the project already runs it**, or when context budget is tight —
+  its own upstream sells the CLI on not loading large tool schemas and verbose
+  accessibility trees into the model context. **`chrome-devtools` when the question is
+  past the page** — a Lighthouse category or a heap snapshot, neither of which the
+  Playwright channel has, or a performance trace you want *analysed* rather than only
+  recorded. Neither is *the better
+  browser*, and a run that ranks them has invented a fact this matrix does not carry.
 - **graphify**: detect via `graphify-out/graph.json` (built → `✓ ready`, query it in
   the harvest) or a resolving `graphify` binary with no `graphify-out/` (installed,
   not built → offer the one-line `/graphify .`). Absent → print the install lines

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

@@ -395,12 +395,17 @@ never that the work was skipped quietly.
   run's confirmed model (`model-tiering.md`). The plan's parallel groups fan out
   **only** when each implementer gets its own worktree; otherwise sequential.
 - **Web front end? The task's own surface is checked in a browser, not in the diff.**
-  Where `chrome-devtools` is connected ([`companion-skills.md`](companion-skills.md)):
-  after a task that changes a rendered surface, load it, take a snapshot and read the
+  Where a browser channel is connected — `playwright` **or** `chrome-devtools`, either
+  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.
-  Absent, say the surface was verified by reading the diff and treat it as the weaker
-  claim it is. Stage 6 repeats this over the whole tree; this one catches it while the
+  **What the look finds is fixed in this task, or parked with the ruling the GATE below
+  requires — never parked silently** — a browser finding filed without a ruling is the
+  diff-review verdict wearing a screenshot; the look was worth taking only if it can
+  still change the code or is on record as deliberately not doing so. Absent, say the surface was verified by reading
+  the diff and treat it as the weaker claim it is. Stage 6 repeats this over the whole tree; this one catches it while the
   implementer that wrote it is still dispatched. The matrix pointed this companion at
   stages 5–6 from the day it was added and **this stage had never named it** — found by
   the guard comparing the two, not by a reader.
@@ -438,12 +443,30 @@ never that the work was skipped quietly.
   A passing suite proves the code does what its assertions say. It does not prove the
   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 `chrome-devtools` is connected ([`companion-skills.md`](companion-skills.md)):
+  time. Where a browser channel is connected — `playwright` **or** `chrome-devtools`,
+  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
   letting "tests pass" stand in for "it renders". This is the `L6→L7` seam of
   [`audit.md`](audit.md)'s ladder: *is there an executed observable a user reaches?*
+- **A browser test suite does not discharge the look, and does not become it.** A
+  project whose CI runs `playwright test` has an *asserted* browser — it proves what
+  someone thought to assert, on the paths someone thought to write. It cannot report
+  the console error nobody asserted on, the bundle that 404s past a route nobody
+  visits, or the element that moved four pixels under a header. So a green spec suite
+  counts where every other test counts, inside **the suite half of the GATE above**;
+  the look stays what it already is here — **recommended, never a gate**, and reported
+  in the words the gate gives it. What the pair buys is that they fail differently: a
+  run that answers *the surface was checked* by pointing at its spec suite has answered
+  a different question. Where the suite is the thing that changed, the look is what
+  proves it runs against a page that renders.
+- **What the look finds is fixed here.** A rendering defect found at stage 6 is a
+  stage-6 finding: fix it, look again, then call the stage green. Filing it to the
+  board and advancing is how a run reports *checked in a browser* for a page it has
+  seen to be broken — so if it does leave unfixed, the reason is on record and the
+  close-out carries it, exactly as a parked finding does.
 
 ## 7 — Lint + deploy
 - **Freedom: low** — outward and irreversible — the authorization floor is exact or the stage stops ([`gates.md`](gates.md) → *Axis C*).
@@ -496,7 +519,8 @@ never that the work was skipped quietly.
 - **A deployed web target is opened, not curled.** A `200` proves the server
   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 `chrome-devtools` is connected, load the deployed URL and read
+  health check. Where a browser channel is connected — `playwright` **or**
+  `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

@@ -101,13 +101,25 @@ database created ten seconds ago" are different claims, and only the second one
 - **A green suite is not a rendered page.** On a web front end the suite proves the
   code does what its assertions say; it cannot see a component that renders correctly
   and lands under a fixed header, a request that 404s while every unit test mocks it,
-  or a console error that costs nothing at test time. Where `chrome-devtools` is
-  connected ([`companion-skills.md`](companion-skills.md)), open the surface and read
+  or a console error that costs nothing at test time. Where a browser channel is
+  connected — `playwright` **or** `chrome-devtools`, either one
+  ([`companion-skills.md`](companion-skills.md)) — open the surface and read
   the console and the network log before calling it done — and **quote what you read**,
   not that you looked. Absent, the honest sentence is *"verified by reading the diff"*,
   which is a weaker claim and is recorded as one. Same family as a test that passes
   regardless of the production code: the assertion is real and it is pointed at
   something other than what a user reaches.
+- **A browser test suite does not close this, either.** `playwright test` in CI is a
+  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 — 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