fix(#2526): remove gsd-ui-auditor's uncallable Playwright-MCP block (#2594)

* fix(#2526): drop gsd-ui-auditor's uncallable Playwright-MCP block

The agent declares `tools: Read, Write, Bash, Grep, Glob, Skill` — no
`mcp__*` grant of any kind — while its body presented a
`<playwright_mcp_approach>` block as the *preferred* capture path. That
branch was unreachable by construction: the availability check had a
fixed answer, the three `mcp__playwright__*` calls could never dispatch,
and the "when Playwright-MCP is NOT available" fallback was the only
branch that ever ran — 39 lines of instruction loaded on every
/gsd-ui-review spawn that also invited the model to claim a capture path
it could not take.

Remove the dead block, leaving the CLI screenshot path as the sole
documented approach.

Guard the class in tests/mcp-tool-inheritance.test.cjs, which already
owns agent MCP-grant parity: the new block generalizes the #1284
researcher check from two agents and one dispatch table to every
agents/*.md and its whole body — no agent may document an
`mcp__<server>__*` namespace absent from its own `tools:` declaration.

Frontmatter is read through the canonical parser
(gsd-core/bin/lib/frontmatter.cjs) rather than a hand-rolled scan, so
inline CSV, block sequences, flow arrays, quoted scalars and full-line
comments are handled by construction; inline comments inside a scalar
survive that parser, so they are stripped explicitly. The check is
server-level by design, ignores prose metavariables like `mcp__X__*`,
matches hyphenated server ids, and carries a discovery guard plus
negative controls for every documented boundary so it cannot decay into
a vacuous pass.

The session-level Playwright-MCP pass in gsd-core/workflows/ui-review.md
is deliberately untouched — workflow files carry no fixed allowlist, so
their availability check is genuinely runtime-detected and honest.

Fixes #2526

* chore(#2526): set changeset fragment pr to 2594

The fragment shipped with the documented `pr: 0` placeholder because the
PR number does not exist until the PR is opened, and
scripts/changeset/parse.cjs rejects `pr <= 0`. Now that the PR is open,
set the real number so changeset-lint passes.

* test(#2526): cover the two-char server-id boundary of the metavariable exclusion

The length-1 "prose metavariable" exclusion was tested at length=1 and at
real ids (>=3 chars), but never at length=2 — the limit+1 boundary where a
server id starts being recognized. Review finding on #2594: `mcp__ab__foo`
in a body with no grant must flag `['ab']`.

* fix(#2526): treat a bare mcp__* grant as covering every server

`grantedServers()` stripped `mcp__*` to the empty string and dropped it via
`if (server)`, so an allowlist that grants every MCP server read as granting
none — and the guard then fired against a body the grant plainly covered.
That is the one input shape that inverts the check, turning it against a
correct agent rather than merely missing a bad one.

A `/^mcp__\*+$/` token now sets a GRANT_ALL sentinel that short-circuits
`ungrantedServers()`. The sentinel `*` is outside REFERENCE_RE's character
class, so no body reference can collide with it. A bare `mcp__` with no
wildcard stays a typo rather than a grant and keeps failing closed.

No agent uses the `mcp__*` spelling today, so this was latent rather than
live. Two negative controls pin both halves.

* fix(#2526): scan the frontmatter description for MCP references too

`ungrantedServers()` scanned `stripFrontmatter(content)` only, so an
`mcp__foo__bar` reference in the `description` field escaped the check. That
field ships with the agent and the dispatcher reads it, which makes a dead
reference there exactly as dead as one in the body.

Only `description` is added to the scanned surface, never the whole
frontmatter: `tools:` is the grant list itself, so scanning it would let every
allowlist satisfy itself and turn the guard vacuous. A negative control pins
that boundary alongside the new positive case.

All 34 per-agent tests still pass with the wider surface, so no live agent
verdict changes — this was latent.

* test(#2526): give multi-character placeholders a convention the checker knows

The metavariable exclusion is `length === 1`, so the natural placeholders
`mcp__SRV__*` and `mcp__SERVER__*` were flagged as real references — and the
failure message then offered an author two remedies ("grant the namespace or
drop the block") that both misread what they wrote.

Adopts the angle-bracket half of the suggested fix: `mcp__<SERVER>__*` is the
sanctioned multi-character placeholder, exempt by construction because `<` is
outside the reference pattern's character class. This pins an existing
property rather than adding a special case.

Declines the all-caps half. An all-caps exemption would be a false NEGATIVE
for any real server spelled in caps, and a guard that misses a dead reference
fails in exactly the direction this check exists to prevent. The bare-caps
form keeps firing; the message now names the convention as a third remedy.

Also corrects "grants neither" in that message, which was wrong for any count
other than two.

* test(#2526): pin the zero-length server id, completing the boundary triple

`mcp____foo` yields `[]`, but for a different reason than the length-1 case:
it is unrepresentable by `/mcp__([A-Za-z0-9_-]+?)__/g` since `+?` requires at
least one character, so the pattern skips it before the metavariable
exclusion is ever consulted. Pinning limit-1 completes the 0/1/2 boundary
rule on its own terms and records which mechanism owns the case.

* docs(#2526): correct every drifted AGENTS.md Tools row, not just the one

The review asked for the one-line `gsd-ui-auditor` correction (missing
`Skill`). Sweeping the defect class first — every `**Tools**` row in
docs/AGENTS.md against its agent's `tools:` frontmatter — found it was 26 of
34 rows, so the one-line framing was the reviewer's premise rather than the
population.

Breakdown of the 26:
  * 21 omitted `Skill`, 6 omitted `Edit` (overlapping) — under-promises, the
    same drift class as #2526 but in the harmless direction.
  * 8 wrote `mcp (context7)` as shorthand while frontmatter granted up to 8
    servers (firecrawl, exa, tavily, ref, jina, perplexity, both context7s).
  * 1 was actively wrong: gsd-debug-session-manager documented `Task`, a tool
    name that no longer exists — the #2526 shape at the doc layer, naming a
    capability that cannot dispatch.

Every row is now the frontmatter `tools:` value verbatim, which is also what
makes the parity guard in the following commit non-brittle. The diff is
26 insertions / 26 deletions, all Tools rows.

* test(#2526): guard AGENTS.md Tools rows against agent frontmatter

The 26 corrected rows in the previous commit were free to drift because
nothing asserted the role card and the frontmatter agreed — the same reason
the #2526 block itself survived. Correcting them without an invariant just
resets the clock.

Lands in agent-classification-parity.test.cjs rather than a new file: that
suite already owns docs/AGENTS.md as a contract surface, already carries the
`allow-test-rule` exemption for treating the doc as the product, and file
count is the unit of CI overhead (docs/TESTING-SUITES.md).

Compares the row to the frontmatter value VERBATIM, not as a set — a set
comparison would keep accepting the "mcp (context7)" shorthand that hid eight
grants behind one, which is the under-documentation half of the drift.

Carries the same discovery guard #2526's own check uses: a section with a
granted `tools:` but no **Tools** row fails loudly, so deleting a row cannot
silently retire its assertion. Both halves are negative-controlled — against
the pre-fix doc it fails naming 26 rows (gsd-ui-auditor:339 among them), and
with a row deleted it fails on the missing-row assertion.

* chore(#2526): note the AGENTS.md drift correction in the changeset

The role cards are user-visible, and 26 of them documented a tool set the
agent did not have. Type, `pr: 2594`, and the trailing `(#2526)` are
unchanged.

* fix(#2526): use a CRLF-safe split in the AGENTS.md Tools-row guard

`lint-tests` (npm run lint:ci) rejected `rawAgentsMd.split('\n')` under the
repo's local/no-crlf-fragile-split rule: Windows autocrlf yields CRLF, so a
trailing \r rides into the parsed line. Switched to `/\r?\n/`.

Caught by CI on the round-3 push before the response comment went out.

* docs(#2526): correct the drift tallies stated in c5a9607e

Re-derived the census programmatically from the pre-fix doc instead of by eye.
The 26-of-34 headline was right; the breakdown was not.

  Skill omitted   21 -> 22
  Edit omitted     6 ->  7
  "mcp (context7)" shorthand   8 rows -> 7 rows

The 8 was conflating two things: 8 rows omitted MCP grants entirely, but only
7 of them used the "mcp (context7)" shorthand — gsd-executor listed no MCP at
all. Also names the one `Agent` omission (gsd-debug-session-manager, the row
that still read `Task`).

c5a9607e's message keeps the wrong numbers rather than rewriting a pushed
branch mid-review; the test comment and changeset are the durable statements
and both are corrected here.

---------

Co-authored-by: Tom Boucher <trekkie@nomorestars.com>

docs/AGENTS.md

@@ -40,7 +40,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-new-project`, `/gsd-new-milestone` |
 | **Parallelism** | 4 instances (stack, features, architecture, pitfalls) |
-| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
+| **Tools** | Read, Write, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__* |
 | **Model (balanced)** | Sonnet |
 | **Color** | Cyan |
 | **Produces** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` |
@@ -60,7 +60,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-plan-phase` |
 | **Parallelism** | 4 instances (same focus areas as project researcher) |
-| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
+| **Tools** | Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__* |
 | **Model (balanced)** | Sonnet |
 | **Color** | Cyan |
 | **Produces** | `{phase}-RESEARCH.md` |
@@ -80,7 +80,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-ui-phase` |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
+| **Tools** | Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__* |
 | **Model (balanced)** | Sonnet |
 | **Color** | Purple |
 | **Produces** | `{phase}-UI-SPEC.md` |
@@ -101,7 +101,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `discuss-phase-assumptions` workflow (when `workflow.discuss_mode = 'assumptions'`) |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Bash, Grep, Glob |
+| **Tools** | Read, Bash, Grep, Glob, Skill |
 | **Model (balanced)** | Sonnet |
 | **Color** | Cyan |
 | **Produces** | Structured assumptions with decision statements, evidence file paths, confidence levels |
@@ -124,7 +124,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `discuss-phase` workflow (when ADVISOR_MODE = true) |
 | **Parallelism** | Multiple instances (one per gray area) |
-| **Tools** | Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
+| **Tools** | Read, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__* |
 | **Model (balanced)** | Sonnet |
 | **Color** | Cyan |
 | **Produces** | 5-column comparison table (Option / Pros / Cons / Complexity / Recommendation) with rationale paragraph |
@@ -146,7 +146,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-new-project` (after 4 researchers complete) |
 | **Parallelism** | Single instance (sequential after researchers) |
-| **Tools** | Read, Write, Bash |
+| **Tools** | Read, Write, Bash, Skill |
 | **Model (balanced)** | Sonnet |
 | **Color** | Purple |
 | **Produces** | `.planning/research/SUMMARY.md` |
@@ -161,7 +161,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-plan-phase`, `/gsd-quick` |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Write, Edit, Bash, Glob, Grep, WebFetch, mcp (context7) |
+| **Tools** | Read, Write, Edit, Bash, Glob, Grep, Skill, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__* |
 | **Model (balanced)** | Opus |
 | **Color** | Green |
 | **Produces** | `{phase}-{N}-PLAN.md` files |
@@ -185,7 +185,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-new-project` |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Write, Bash, Glob, Grep |
+| **Tools** | Read, Write, Bash, Glob, Grep, Skill |
 | **Model (balanced)** | Sonnet |
 | **Color** | Purple |
 | **Produces** | `ROADMAP.md` |
@@ -206,7 +206,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-execute-phase`, `/gsd-quick` |
 | **Parallelism** | Multiple (parallel within waves, sequential across waves) |
-| **Tools** | Read, Write, Edit, Bash, Grep, Glob |
+| **Tools** | Read, Write, Edit, Bash, Grep, Glob, Skill, mcp__context7__*, mcp__plugin_context7_context7__* |
 | **Model (balanced)** | Sonnet |
 | **Color** | Yellow |
 | **Produces** | Code changes, git commits, `{phase}-{N}-SUMMARY.md` |
@@ -230,7 +230,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-plan-phase` (verification loop, max 3 iterations) |
 | **Parallelism** | Single instance (iterative) |
-| **Tools** | Read, Bash, Glob, Grep |
+| **Tools** | Read, Bash, Glob, Grep, Skill |
 | **Disallowed Tools** | Write, Edit, MultiEdit |
 | **Model (balanced)** | Sonnet |
 | **Color** | Green |
@@ -256,7 +256,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-audit-milestone` |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Bash, Grep, Glob |
+| **Tools** | Read, Bash, Grep, Glob, Skill |
 | **Disallowed Tools** | Write, Edit, MultiEdit |
 | **Model (balanced)** | Sonnet |
 | **Color** | Blue |
@@ -272,7 +272,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-ui-phase` (validation loop, max 2 iterations) |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Bash, Glob, Grep |
+| **Tools** | Read, Bash, Glob, Grep, Skill |
 | **Disallowed Tools** | Write, Edit, MultiEdit |
 | **Model (balanced)** | Sonnet |
 | **Color** | Cyan |
@@ -291,7 +291,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-execute-phase` (after all executors complete) |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Write, Bash, Grep, Glob |
+| **Tools** | Read, Write, Bash, Grep, Glob, Skill |
 | **Disallowed Tools** | Edit, MultiEdit |
 | **Model (balanced)** | Sonnet |
 | **Color** | Green |
@@ -316,7 +316,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-validate-phase` |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Write, Edit, Bash, Grep, Glob |
+| **Tools** | Read, Write, Edit, Bash, Glob, Grep, Skill |
 | **Model (balanced)** | Sonnet |
 | **Color** | Purple |
 | **Produces** | Test files, updated `VALIDATION.md` |
@@ -336,7 +336,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-ui-review` |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Write, Bash, Grep, Glob |
+| **Tools** | Read, Write, Bash, Grep, Glob, Skill |
 | **Disallowed Tools** | Edit, MultiEdit |
 | **Model (balanced)** | Sonnet |
 | **Color** | Pink |
@@ -360,7 +360,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-map-codebase`, post-execute drift gate in `/gsd-execute-phase` |
 | **Parallelism** | 4 instances (tech, architecture, quality, concerns) |
-| **Tools** | Read, Bash, Grep, Glob, Write |
+| **Tools** | Read, Bash, Grep, Glob, Write, Skill |
 | **Model (balanced)** | Haiku |
 | **Color** | Cyan |
 | **Produces** | `.planning/codebase/*.md` (7 documents, with `last_mapped_commit` frontmatter) |
@@ -388,7 +388,7 @@ runs its default whole-repo scan.
 |----------|-------|
 | **Spawned by** | `/gsd-debug`, `/gsd-verify-work` (for failures) |
 | **Parallelism** | Single instance (interactive) |
-| **Tools** | Read, Write, Edit, Bash, Grep, Glob, WebSearch |
+| **Tools** | Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch |
 | **Model (balanced)** | Sonnet |
 | **Color** | Orange |
 | **Produces** | `.planning/debug/*.md`, knowledge-base updates |
@@ -443,7 +443,7 @@ Communication style, decision patterns, debugging approach, UX preferences, vend
 |----------|-------|
 | **Spawned by** | `/gsd-docs-update` |
 | **Parallelism** | Multiple instances (one per doc type) |
-| **Tools** | Read, Write, Bash, Grep, Glob |
+| **Tools** | Read, Bash, Grep, Glob, Write, Edit, Skill |
 | **Model (balanced)** | Sonnet |
 | **Color** | Purple |
 | **Produces** | Project documentation files (README, architecture, API docs, etc.) |
@@ -487,7 +487,7 @@ Communication style, decision patterns, debugging approach, UX preferences, vend
 |----------|-------|
 | **Spawned by** | `/gsd-secure-phase` |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Bash, Glob, Grep |
+| **Tools** | Read, Bash, Glob, Grep, Skill |
 | **Model (balanced)** | Sonnet |
 | **Color** | Red |
 | **Produces** | Structured verdict (SECURED / OPEN_THREATS / ESCALATE) — orchestrator writes `{phase}-SECURITY.md` (#2119) |
@@ -533,7 +533,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 |----------|-------|
 | **Spawned by** | `/gsd-debug` |
 | **Parallelism** | Single instance (interactive, stateful) |
-| **Tools** | Read, Write, Bash, Grep, Glob, Task, AskUserQuestion |
+| **Tools** | Read, Write, Edit, Bash, Grep, Glob, Agent, AskUserQuestion |
 | **Model (balanced)** | Sonnet |
 | **Color** | Orange |
 | **Produces** | Compact summary returned to main context; evolves the `.planning/debug/{slug}.md` session file |
@@ -553,7 +553,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 |----------|-------|
 | **Spawned by** | `/gsd-code-review` |
 | **Parallelism** | Typically single instance per review scope |
-| **Tools** | Read, Write, Bash, Grep, Glob |
+| **Tools** | Read, Write, Bash, Grep, Glob, Skill |
 | **Model (balanced)** | Sonnet |
 | **Color** | Orange |
 | **Produces** | `REVIEW.md` in the phase directory |
@@ -573,7 +573,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 |----------|-------|
 | **Spawned by** | `/gsd-code-review --fix` |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Edit, Write, Bash, Grep, Glob |
+| **Tools** | Read, Edit, Write, Bash, Grep, Glob, Skill |
 | **Model (balanced)** | Sonnet |
 | **Color** | Green |
 | **Produces** | `REVIEW-FIX.md`; one atomic git commit per applied fix |
@@ -593,7 +593,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 |----------|-------|
 | **Spawned by** | `/gsd-ai-integration-phase` |
 | **Parallelism** | Single instance (sequential with domain-researcher / eval-planner) |
-| **Tools** | Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp (context7) |
+| **Tools** | Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*, mcp__plugin_context7_context7__* |
 | **Model (balanced)** | Sonnet |
 | **Color** | Green |
 | **Produces** | Sections 3–4b of `AI-SPEC.md` (framework quick reference + implementation guidance) |
@@ -612,7 +612,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 |----------|-------|
 | **Spawned by** | `/gsd-ai-integration-phase` |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) |
+| **Tools** | Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__* |
 | **Model (balanced)** | Sonnet |
 | **Color** | Purple |
 | **Produces** | Section 1b of `AI-SPEC.md` |
@@ -631,7 +631,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 |----------|-------|
 | **Spawned by** | `/gsd-ai-integration-phase` |
 | **Parallelism** | Single instance (sequential after domain-researcher) |
-| **Tools** | Read, Write, Bash, Grep, Glob, AskUserQuestion |
+| **Tools** | Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion |
 | **Model (balanced)** | Sonnet |
 | **Color** | Orange |
 | **Produces** | Sections 5–7 of `AI-SPEC.md` (Evaluation Strategy, Guardrails, Production Monitoring) |
@@ -652,7 +652,7 @@ Twelve additional agents ship under `agents/gsd-*.md` and are used by specialty
 |----------|-------|
 | **Spawned by** | `/gsd-eval-review` |
 | **Parallelism** | Single instance |
-| **Tools** | Read, Write, Bash, Grep, Glob |
+| **Tools** | Read, Write, Bash, Grep, Glob, Skill |
 | **Disallowed Tools** | Edit, MultiEdit |
 | **Model (balanced)** | Sonnet |
 | **Color** | Red |