mandrel 2.40.0 → 2.41.0

package/.agents/skills/skills.index.json

@@ -1,24 +1,14 @@
 {
-  "generatedAt": "2026-08-06T10:26:18.702Z",
+  "generatedAt": "2026-09-06T12:59:23.069Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
-    {
-      "name": "api-and-interface-design",
-      "tier": "core",
-      "category": "core",
-      "path": ".agents/skills/core/api-and-interface-design/SKILL.md",
-      "description": "Designs stable, well-documented APIs and module interfaces. Use when creating REST/GraphQL endpoints, defining contracts between modules, or changing public interfaces. The wire-format SSOT — response envelope, HTTP status codes, validation taxonomy, payload naming — lives in `.agents/rules/api-conventions.md`; this skill shows authors how to apply it.",
-      "policyCapsuleBullets": 9,
-      "allowedTools": null,
-      "vendor": null
-    },
     {
       "name": "browser-testing-with-devtools",
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/browser-testing-with-devtools/SKILL.md",
       "description": "Tests in real browsers. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data via Chrome DevTools MCP.",
-      "policyCapsuleBullets": 9,
+      "policyCapsuleBullets": 8,
       "allowedTools": null,
       "vendor": null
     },
@@ -28,17 +18,7 @@
       "category": "core",
       "path": ".agents/skills/core/code-review-and-quality/SKILL.md",
       "description": "Conducts multi-axis code review and runs the disciplined post-green refactor pass. Use before merging any change, when reviewing code written by yourself, another agent, or a human, or when the opt-in `delivery.refactorStage` checkpoint asks for a behaviour-preserving CRAP/duplication pass after the suite is green.",
-      "policyCapsuleBullets": 12,
-      "allowedTools": null,
-      "vendor": null
-    },
-    {
-      "name": "debugging-and-error-recovery",
-      "tier": "core",
-      "category": "core",
-      "path": ".agents/skills/core/debugging-and-error-recovery/SKILL.md",
-      "description": "Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing.",
-      "policyCapsuleBullets": 9,
+      "policyCapsuleBullets": 7,
       "allowedTools": null,
       "vendor": null
     },
@@ -48,7 +28,7 @@
       "category": "core",
       "path": ".agents/skills/core/documentation-and-adrs/SKILL.md",
       "description": "Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.",
-      "policyCapsuleBullets": 9,
+      "policyCapsuleBullets": 6,
       "allowedTools": null,
       "vendor": null
     },
@@ -57,21 +37,11 @@
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/gates-and-baselines/SKILL.md",
-      "description": "Governs quality gates and the unified-baseline snapshots. Use when authoring a baseline refresh commit (CRAP, maintainability, dead-exports, lighthouse), when setting up or modifying CI quality gates, or when introducing a new gate that asserts on pre-existing state without turning the integration branch red.",
-      "policyCapsuleBullets": 9,
+      "description": "Governs quality gates and the unified-baseline snapshots. Use when authoring a baseline refresh commit (coverage, CRAP, maintainability, duplication, dead-exports), when setting up or modifying CI quality gates, or when introducing a new gate that asserts on pre-existing state without turning the base branch red.",
+      "policyCapsuleBullets": 10,
       "allowedTools": ["Read", "Write", "Bash"],
       "vendor": null
     },
-    {
-      "name": "git-workflow-and-versioning",
-      "tier": "core",
-      "category": "core",
-      "path": ".agents/skills/core/git-workflow-and-versioning/SKILL.md",
-      "description": "Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work across multiple parallel streams.",
-      "policyCapsuleBullets": 6,
-      "allowedTools": null,
-      "vendor": null
-    },
     {
       "name": "idea-refinement",
       "tier": "core",
@@ -82,16 +52,6 @@
       "allowedTools": null,
       "vendor": null
     },
-    {
-      "name": "qa-coverage-mapping",
-      "tier": "core",
-      "category": "core",
-      "path": ".agents/skills/core/qa-coverage-mapping/SKILL.md",
-      "description": "Map a quality finding to a per-tier coverage verdict (unit / contract / acceptance) aligned to `.agents/rules/testing-standards.md`. Use when a finding points at a symbol or surface and you need to know which test tiers already cover it and which are missing, so remediation lands the right tier. Delegates the verdict to the deterministic `lib/qa/coverage-verdict.js#coverageVerdict` helper.",
-      "policyCapsuleBullets": 7,
-      "allowedTools": ["Read", "Bash"],
-      "vendor": null
-    },
     {
       "name": "scope-triage",
       "tier": "core",
@@ -107,7 +67,7 @@
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/security-and-hardening/SKILL.md",
-      "description": "Hardens code against vulnerabilities. Use when handling user input, authentication, data storage, or external integrations. The non-negotiable security MUSTs live in `.agents/rules/security-baseline.md`; this skill shows how to apply them with process guidance, an audit-triage tree, and a review checklist.",
+      "description": "Hardens code against vulnerabilities. Use when handling user input, authentication, data storage, or external integrations. The non-negotiable security MUSTs live in `.agents/rules/security-baseline.md`; this skill shows how to apply them, with the project's surfacing and validation-response process.",
       "policyCapsuleBullets": 6,
       "allowedTools": null,
       "vendor": null
@@ -128,7 +88,7 @@
       "category": "qa",
       "path": ".agents/skills/stack/qa/playwright-bdd/SKILL.md",
       "description": "Wires Gherkin `.feature` files to Playwright via the `playwright-bdd` library. Use when running BDD scenarios on a Playwright runtime — pairs with the `gherkin-authoring` skill (scenario prose) and the `playwright` skill (browser conventions). Drives execution by tag expression with trace-first debugging and Playwright-native sharding.",
-      "policyCapsuleBullets": 8,
+      "policyCapsuleBullets": 9,
       "allowedTools": null,
       "vendor": "playwright"
     },
@@ -142,35 +102,15 @@
       "allowedTools": null,
       "vendor": "playwright"
     },
-    {
-      "name": "qa-explore-driving",
-      "tier": "stack",
-      "category": "qa",
-      "path": ".agents/skills/stack/qa/qa-explore-driving/SKILL.md",
-      "description": "Conventions for agent-driven exploratory QA driving — how the agent itself drives a surface during `/qa-explore` (agent-led), as opposed to the human-led `/qa-assist`. Use when the agent explores a running app via the browser MCP (navigation-first, the default) — including authenticated deployed surfaces reached through the resolved environment's sign-in seam — or walks a static surface (the documented interim where no seam resolves), under a strictly read-only capture invariant. The exploration procedure lives in `.agents/workflows/qa-explore.md`; this skill is the driving-conventions reference it leans on.",
-      "policyCapsuleBullets": 9,
-      "allowedTools": null,
-      "vendor": null
-    },
     {
       "name": "qa-harness",
       "tier": "stack",
       "category": "qa",
       "path": ".agents/skills/stack/qa/qa-harness/SKILL.md",
-      "description": "Conventions for the agent-driven QA harness that drives Gherkin scenarios through a real browser. Use when executing `/qa-run` or instrumenting a live surface — covers navigation-first execution, per-surface console and network capture, design-token visual checks, and the framework-generic heuristic cards for turning signal into findings. The harness procedure lives in `.agents/workflows/qa-run.md`; this skill is the conventions reference it leans on.",
-      "policyCapsuleBullets": 7,
+      "description": "Conventions for agent-driven QA driving — the one driving-conventions reference behind both `/qa-run` (the known-scenario sweep through a real browser) and `/qa-explore` (agent-led exploratory driving). Use when instrumenting a live surface — covers navigation-first execution, per-surface console and network capture, design-token visual checks, the `F#` finding shape, per-environment resolution, and static driving as the documented interim. The run procedures live in `.agents/workflows/qa-run.md` and `.agents/workflows/qa-explore.md`; this skill is the conventions reference they lean on.",
+      "policyCapsuleBullets": 11,
       "allowedTools": null,
       "vendor": null
-    },
-    {
-      "name": "vitest",
-      "tier": "stack",
-      "category": "qa",
-      "path": ".agents/skills/stack/qa/vitest/SKILL.md",
-      "description": "Writes fast, isolated unit and integration tests with Vitest. Use when each test must run on file-save without shared state — `vi.mock()` for external deps, `vi.spyOn()` for call monitoring, AAA structure, and edge-case coverage for null/undefined/boundary inputs.",
-      "policyCapsuleBullets": 8,
-      "allowedTools": null,
-      "vendor": "vitest"
     }
   ]
 }

package/.agents/skills/stack/qa/gherkin-authoring/SKILL.md

@@ -17,7 +17,7 @@ description:
 - Never assert on HTTP status codes, SQL state, DOM selectors, URLs, or JSON payloads inside `.feature` prose — push those to contract tests.
 - Tag every Scenario or Outline with exactly one canonical `@domain-*` tag and the appropriate risk/platform tags from the gherkin-standards taxonomy.
 - Use `Background` only when every scenario in the file genuinely shares the precondition with no per-scenario variation.
-- Reuse existing step definitions: grep the steps tree for the verb stem before authoring a new step.
+- Complete the step-reuse sequence in [`gherkin-standards.md` § Step Reuse](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write) before authoring any scenario text; that rule is the only home for it.
 - Author one scenario per PRD acceptance criterion; for bounded matrices, use a Scenario Outline with ≤12 Examples rows.
 - Use third-person present-tense, role-qualified actors (`the billing-admin`), never first person.
 
@@ -29,16 +29,10 @@ the rule for the **what**.
 
 ## Long-form reference — read on demand
 
-The worked authoring material — canonical Given/When/Then phrasing, the
-one-AC-to-one-scenario translation walkthrough, Background-vs-Given and
-Outline-vs-multi-scenario decisions, the step-definition library layout and
-reuse/deprecation workflow, and the pre-PR authoring checklist — lives in the
-on-demand sibling [`reference.md`](reference.md). Open a section only when the
-task engages it.
+The step-definition library layout and the pre-PR authoring checklist live in
+the on-demand sibling [`reference.md`](reference.md). Open a section only when
+the task engages it.
 
-- [Canonical Given / When / Then Phrasing](reference.md#canonical-given--when--then-phrasing)
-- [Translating PRD Acceptance Criteria to Scenarios](reference.md#translating-prd-acceptance-criteria-to-scenarios)
-- [Background vs. Given, Outline vs. Multi-Scenario](reference.md#background-vs-given-outline-vs-multi-scenario)
 - [Step-Definition Library Structure](reference.md#step-definition-library-structure)
 - [Authoring Checklist](reference.md#authoring-checklist)
 

package/.agents/skills/stack/qa/gherkin-authoring/reference.md

@@ -3,102 +3,9 @@
 **Read this when** a task engages one of the sections below and the Policy
 Capsule in [`SKILL.md`](SKILL.md) does not settle it on its own. The capsule is
 the contract; this file is the reference material behind it. The enforcement
-rules (tag taxonomy, forbidden patterns, Outline conventions) are owned by the
-SSOT rule, [`gherkin-standards.md`](../../../../rules/gherkin-standards.md).
-
-## Canonical Given / When / Then Phrasing
-
-`.feature` prose is written for a product-minded reader, not a test harness.
-Each clause has exactly one job:
-
-- **Given** — a precondition that is *already true* when the scenario starts.
-  Stative, past or present tense. No actions.
-  - Good: `Given a signed-in account-owner with an unpaid invoice`.
-  - Bad: `Given the user clicks the login button` (that's a When).
-- **When** — the single business action under test. One verb, one actor, one
-  event. Splitting a When into multiple clauses is almost always wrong — move
-  the extra clauses into Given.
-  - Good: `When they issue the invoice`.
-  - Bad: `When they log in and issue the invoice and download the PDF`.
-- **Then** — an observable, user-visible outcome. Assert what the *user* sees or
-  what the *business* records, not what the system emits internally.
-  - Good: `Then the invoice appears in the issued invoices list`.
-  - Bad: `Then a 201 is returned` (forbidden; see
-    [gherkin-standards § Forbidden Patterns](../../../../rules/gherkin-standards.md#forbidden-patterns)).
-- **And / But** — continuation clauses. They inherit the mood of the most recent
-  Given/When/Then. Never start a scenario with And/But.
-
-Voice and tense: third-person, present tense, role-qualified noun actors
-(`the user`, `a billing-admin`, not "I" or "we"). One clause, one fact —
-comma-chained facts hide compound assertions. Numbers and identifiers go in
-`Examples` tables or fixtures, not inline prose.
-
-## Translating PRD Acceptance Criteria to Scenarios
-
-PRD ACs are the raw material. The authoring move is **one AC → one scenario**
-unless the AC encodes a matrix (then it becomes a Scenario Outline — see below).
-
-Walkthrough — a PRD AC from a billing feature:
-
-> **AC-3:** When a billing-admin issues an invoice for a customer with a
-> negative balance, the system rejects the issue and shows an error naming the
-> outstanding amount.
-
-Translation steps:
-
-1. **Identify the domain.** Billing → tag the scenario `@domain-billing`.
-2. **Identify the actor and precondition.** "billing-admin", "customer with a
-   negative balance" → two Givens.
-3. **Identify the single action.** "issues an invoice" → one When.
-4. **Identify the observable outcome.** "rejects the issue and shows an error
-   naming the outstanding amount" → two Thens (business outcome, then
-   user-visible detail).
-5. **Pick the risk tag.** If the originating ticket was `risk::high`, add
-   `@risk-high`.
-
-Resulting scenario:
-
-```gherkin
-@domain-billing @risk-high
-Scenario: Issuing an invoice is rejected when the customer has a negative balance
-  Given a signed-in billing-admin
-  And a customer with a negative account balance
-  When the billing-admin issues an invoice for that customer
-  Then the issue is rejected
-  And the rejection message names the outstanding amount
-```
-
-Heuristics:
-
-- If a single AC needs more than **one When**, it is really two ACs. Split
-  before you write.
-- If a Then starts with "and the database has…" or "and the API returned…", you
-  have crossed into step-definition or contract-test territory. Rewrite it as
-  user-visible language or move the assertion to a contract test.
-- If an AC says "the system logs X", that's an engineering non-functional
-  requirement — cover it with a focused unit or integration test, not a
-  `.feature` file.
-
-## Background vs. Given, Outline vs. Multi-Scenario
-
-Two authoring decisions authors routinely get wrong.
-
-**Background vs. Given.** `Background` runs before **every** scenario in the
-file. Use it only when every scenario genuinely shares the precondition **and**
-it has no per-scenario variation (no `<placeholders>`, no per-scenario data).
-Prefer a per-scenario Given when only some scenarios need the precondition, when
-it varies by role/plan/fixture, or when a reader cannot understand the scenario
-without scrolling up. Rule of thumb: if you find yourself writing *"except in
-the admin scenario, where the Background step is actually…"*, delete the
-Background.
-
-**Scenario Outline vs. multiple Scenarios.** Use `Scenario Outline` when the
-**same behavior** is exercised across a **bounded matrix** (roles, plan tiers,
-locales) — the Givens/When/Thens are identical and only the data varies. Use
-multiple `Scenario` blocks when the Givens differ structurally, the When verb
-differs, or the Then outcomes differ in kind, not just value. Keep `Examples`
-tables under ~12 rows, and split them by tag when rows need different tags
-(e.g. `@risk-high` on admin rows only).
+rules (tag taxonomy, forbidden patterns, Outline conventions, step reuse) are
+owned by the SSOT rule,
+[`gherkin-standards.md`](../../../../rules/gherkin-standards.md).
 
 ## Step-Definition Library Structure
 
@@ -122,22 +29,11 @@ tests/
 - Step text follows the scenario text verbatim — divergence between scenario
   prose and step text is a bug. Parameterize only over values that actually
   vary; keep implementations ≤20 lines (a longer one signals a missing helper).
-
-**Reuse before authoring** — the non-negotiable workflow is in
-[gherkin-standards § Step Reuse](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write):
-
-1. Search for the verb: `rg -n "issues? an invoice" tests/steps`.
-2. If the phrase exists, **change your scenario** to use it — do not fork a
-   near-duplicate step.
-3. If a near-match exists, extend the existing step and update every call site
-   in the same PR.
-4. Only when no reasonable match exists, add a new step in the correct domain
-   directory.
-
-**Deprecation.** When a step is superseded, move the old definition into
-`steps/_deprecated/` with a comment naming the replacement, migrate every call
-site in the same PR, and delete the `_deprecated/` entry when the migration
-lands. Never leave two live step definitions that mean the same thing.
+- **Reuse before authoring, and deprecate cleanly.** Both are the SSOT rule's:
+  [gherkin-standards § Step Reuse](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write).
+  A superseded definition moves into `steps/_deprecated/` with a comment naming
+  its replacement, every call site migrates in the same PR, and the
+  `_deprecated/` entry is deleted when the migration lands.
 
 ## Authoring Checklist
 
@@ -151,7 +47,7 @@ Before opening a PR that adds or edits a `.feature` file:
 - [ ] `Background` is justified (applies to every scenario in the file).
 - [ ] If a Scenario Outline is used, the matrix is bounded (≤12 rows) and the
       shape is truly identical across rows.
-- [ ] Every step phrase grep-matches an existing step definition **or** is
+- [ ] Every step phrase matches an existing step definition **or** is
       accompanied by a new step definition in the right domain directory.
 - [ ] Reads standalone — a product reader who has never seen the codebase can
       understand the intent without opening a step file.

package/.agents/skills/stack/qa/playwright-bdd/SKILL.md

@@ -13,14 +13,15 @@ vendor: playwright
 
 ## Policy Capsule
 
-- Complete the pre-authoring grep-for-existing-steps checklist before writing any new scenario text; record the matches in your output.
+- Complete the step-reuse sequence in [`gherkin-standards.md` § Step Reuse](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write) before any scenario text is written, and report its results; that rule is the only home for it.
 - Keep `.feature` files free of Playwright API calls — scenarios describe intent, step definitions translate to browser actions.
-- Generate step bindings into a dedicated directory (e.g. `.features-gen/`) and add it to `.gitignore`; never commit generated specs.
-- Drive runs by tag expression (`--grep "@smoke and not @flaky"`), not filename globs; use the canonical `@smoke`/`@risk-high`/`@platform-*`/`@domain-*` taxonomy.
+- Generate step bindings into a dedicated directory (e.g. `.features-gen/`) and add it to `.gitignore`; never commit generated specs, and point `testDir` at that directory.
+- Drive runs by tag expression (`npx bddgen && npx playwright test --grep "@smoke and not @flaky"`), not filename globs; fail the run when generation matches zero scenarios.
 - Inject fixtures via `createBdd` rather than pulling singletons from module scope; reset persistent state through fixture teardown, not stray `After` hooks.
 - Reuse `storageState` for authenticated scenarios — create a logged-in user fixture instead of repeating login steps in `Background`.
-- Keep `trace: 'on-first-retry'` (or `'retain-on-failure'`) enabled; reproduce failures by `@scenario-id` tag, not by title.
+- Keep `trace: 'on-first-retry'` (or `'retain-on-failure'`) enabled; reproduce failures by `@scenario-id` tag, not by title, and use `PWDEBUG=1` rather than `page.pause()` in step files.
 - Shard with Playwright's native `--shard=i/N`; never partition by tag expression across CI jobs.
+- Use Playwright projects (not Cucumber profiles) for browser matrix fan-out, so sharding, retries, and trace config stay in one place.
 
 Guidance for running Gherkin `.feature` files against Playwright via
 `playwright-bdd`. Pairs with the `gherkin-authoring` skill (scenario prose) and
@@ -30,157 +31,31 @@ between them.
 > **Version:** consumers pick their own `playwright-bdd` version. This skill
 > documents behavioral constraints, not a pinned release.
 
-## Pre-authoring checklist (mandatory)
-
-The agent MUST complete every item below AND MUST include the results in its
-output report BEFORE any scenario text is written. See
-[§ Step Reuse — Grep Before You Write](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write)
-for rationale.
-
-1. Run `rg` against the project's steps directory and list every step signature
-   you will reuse. Format: one `Given/When/Then "…"` per line.
-2. For each scenario line you plan to author, identify the matching existing
-   step. For any line with no match, either rephrase to reuse an existing step
-   or record it as a gap. Do NOT author new step definitions during scenario
-   authoring.
-3. State the canonical domain tag and platform tag you will apply (or note
-   "Cross-Platform → no platform tag" per `gherkin-standards.md`).
-4. Confirm the AC's `data-testid`, URL, and payload hints will be stripped from
-   scenario prose.
-
-If you cannot complete every item, stop and report — do not proceed to scenario
-authoring.
-
-## 1. Core Principles
-
-- **One source of truth per scenario:** `.feature` files describe intent; step
-  definitions translate intent into Playwright calls. Never author browser
-  actions in `.feature` prose.
-- **Deterministic tag filtering:** every scenario carries enough tags that any
-  CI shard can be selected by a tag expression without inspecting file paths.
-- **Fixture-per-scenario isolation:** scenarios must not share mutable state.
-  Treat each scenario as a fresh browser context.
-- **Trace-first debugging:** keep the Playwright Trace Viewer workflow intact —
-  `playwright-bdd` wraps Playwright, it does not replace its diagnostics.
-
-## 2. Config Patterns
-
-- Generate step-definition bindings into a dedicated output directory (commonly
-  `.features-gen/`) and add it to `.gitignore`. Do not commit generated specs.
-- Point `playwright.config.ts` at the generated directory via `testDir`; keep a
-  single `defineBddConfig` block that lists `features` and `steps` paths.
-- Register the Cucumber HTML/JSON reporter alongside the Playwright HTML
-  reporter so a headless CI invocation emits machine-readable evidence
-  alongside the agent-driven `/qa-run` sweep.
-- Use Playwright projects (not Cucumber profiles) for browser matrix fan-out —
-  keeps sharding, retries, and trace config in one place.
-
-## 3. Fixture Composition
-
-- Extend Playwright's `test` via `playwright-bdd`'s `createBdd` so fixtures
-  (auth state, API clients, seeded data) are injected into `Given`/`When`/
-  `Then` callbacks by name, not pulled from module-level singletons.
-- Layer fixtures: base Playwright fixtures → domain fixtures (authenticated
-  user, seeded tenant) → scenario-scoped helpers. Each layer depends only on the
-  layer below.
-- Reset persistent state with fixture teardown, not with `After` hooks buried in
-  step files — teardown order is then deterministic and visible in the fixture
-  graph.
-- Reuse `storageState` for authenticated scenarios; create a "logged-in user"
-  fixture rather than repeating login steps in `Background`.
-
-## 4. Tag-Filtered Execution
-
-- Drive runs via tag expressions, not filename globs:
-  `npx bddgen && npx playwright test --grep "@smoke and not @flaky"`.
-- Use the canonical tag taxonomy defined in
-  [`.agents/rules/gherkin-standards.md`](../../../../rules/gherkin-standards.md#tag-taxonomy)
-  (`@smoke`, `@risk-high`, `@platform-*`, `@domain-*`). Do not invent parallel
-  tag vocabularies in the runner config; extend via `@domain-*` only.
-- Wire tag-filtered headless runs to a single npm script so operators never
-  reconstruct the generate-then-run sequence by hand; the agent-driven
-  `/qa-run` selector mirrors the same tag expressions for browser sweeps.
-- Fail the run if generation produces zero matching scenarios — a silent empty
-  suite is worse than a red build.
-
-## 5. Debug & Trace Workflow
-
-- Keep `trace: 'on-first-retry'` (or `'retain-on-failure'`) in the Playwright
-  config. `playwright-bdd` preserves the trace attachment because each scenario
-  maps to a Playwright test.
-- Reproduce a single failing scenario with `--grep "@scenario-id"` rather than
-  the scenario title — titles change, tags are stable.
-- Open traces with `npx playwright show-trace` against the artifact produced
-  under `test-results/`; the trace timeline annotates each `Given`/`When`/
-  `Then` step, which is the primary debug affordance.
-- For step-definition bugs, run with `PWDEBUG=1` to drop into the inspector at
-  the failing step — do not add `page.pause()` calls inside step files.
-
-## 6. Sharding & CI Notes
-
-- Shard with Playwright's native `--shard=i/N`; do not partition by tag
-  expression across jobs — tag-sharding makes flake triage non-deterministic.
-- Run `bddgen` once per job before `playwright test`; cache the generated
-  directory only if the cache key includes every `.feature` and step file.
-- Publish the Cucumber HTML/JSON report as the evidence artifact, alongside
-  the Playwright HTML report and any trace zips.
-- Quarantine `@flaky` scenarios with a dedicated job that does not gate the
-  merge queue; do not silently retry flakes in the main suite.
-
-## Recommended invocation template
-
-Use this template when invoking a subagent to author a `.feature` file from an
-Acceptance Criterion.
-
-```text
-You are an AI coding agent. Your sole task is to invoke the
-**stack/qa/playwright-bdd** skill (defined in this repo) to author one new
-acceptance scenario from a single Acceptance Criterion. You receive nothing
-about this codebase except the AC text and the skill itself — you must
-discover everything else (existing step library, naming conventions, etc.)
-through the skill's prescribed workflow.
-
-Follow the skill's guidance precisely. Your output will be evaluated
-against `.agents/rules/gherkin-standards.md`.
-
-**Skill to invoke.** Read `.agents/skills/stack/qa/playwright-bdd/SKILL.md`
-and follow it. Also read `.agents/rules/gherkin-standards.md` (which the
-skill references).
-
-**The Acceptance Criterion (your sole input).** {{AC_TEXT}}
-
-**Your task.**
-1. Read the skill and the gherkin rule.
-2. Per the skill's "Step Reuse — Grep Before You Write" section, grep
-   {{STEPS_DIR}} to discover the existing step vocabulary BEFORE
-   authoring. List the matches you found.
-3. Author a NEW `.feature` file at {{OUTPUT_PATH}} that covers this AC.
-4. You are FORBIDDEN from editing any file under {{STEPS_DIR}}. This
-   task tests scenario authorship and step REUSE. If a step you need does
-   not exist, you must either rephrase the scenario to reuse what exists,
-   or report that as a gap (do not silently invent).
-5. Tag the feature/scenario per the canonical taxonomy in
-   `gherkin-standards.md`.
-6. Honor every "Forbidden Patterns" rule. `data-testid` hints in the AC
-   parentheses are for the step-definition layer; they MUST NOT appear in
-   your scenario text.
-
-**Report back.** Sections A–E: discovered steps, exact `.feature` content,
-step-coverage analysis, forbidden-patterns self-audit, uncertainty/gaps.
-```
-
-This template encodes the invocation prompt used in the Epic C pilot of
-dsj1984/athlete-portal, where a general-purpose subagent — given only an AC and
-a pointer to this skill — produced a publishable scenario on the first attempt
-with **zero Forbidden-Patterns violations**, reused **4 of 5** needed steps from
-the existing library, and surfaced the single remaining step as a clean, named
-gap rather than inventing one. Future maintainers: resist the urge to "simplify"
-this template. Its explicit grep-before-author step, the hard prohibition on
-editing the steps directory, and the mandated gap-report section are what forced
-those outcomes.
-
-## 7. Cross-References
+## Project-Specific Wiring
+
+The capsule above is the contract. Three points bind this runtime to the rest
+of the framework:
+
+- **Tags come from one taxonomy.** Selection uses the canonical set defined in
+  [`.agents/rules/gherkin-standards.md` § Tag Taxonomy](../../../../rules/gherkin-standards.md#tag-taxonomy)
+  (`@smoke`, `@risk-high`, `@platform-*`, `@domain-*`, `@flaky`, `@skip`). Do
+  not invent parallel tag vocabularies in the runner config; extend via
+  `@domain-*` only. The agent-driven `/qa-run` selector mirrors the same tag
+  expressions, so a scenario set is addressable identically from both surfaces.
+- **`@flaky` runs in its own non-gating job.** Quarantine `@flaky` scenarios in
+  a dedicated CI job that does not gate the merge queue, and never silently
+  retry flakes inside the gating suite. `@flaky` is a debt marker with an owner,
+  not a permanent label.
+- **The Cucumber JSON report is the headless evidence artifact.** Register the
+  Cucumber HTML/JSON reporter alongside the Playwright HTML reporter and publish
+  it (with the trace zips) so a headless CI invocation emits machine-readable
+  evidence next to the agent-driven [`/qa-run`](../../../../workflows/qa-run.md)
+  sweep. Wire the generate-then-run sequence to a single npm script so operators
+  never reconstruct it by hand.
+
+## Cross-References
 
 - Scenario authoring rules: `.agents/rules/gherkin-standards.md`.
+- Scenario authoring skill: `.agents/skills/stack/qa/gherkin-authoring/SKILL.md`.
 - Browser-level conventions: `.agents/skills/stack/qa/playwright/SKILL.md`.
 - Operator entry point: `.agents/workflows/qa-run.md`.