mandrel 2.7.0 → 2.8.0

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

@@ -0,0 +1,157 @@
+# Gherkin Authoring — Reference (on-demand)
+
+**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).
+
+## Step-Definition Library Structure
+
+Authoring scenarios and maintaining steps are the same job split across two
+files. Keep that coupling visible:
+
+```text
+tests/
+  steps/
+    _common/          # actor, auth, navigation — reused across every domain
+      auth.steps.ts
+      navigation.steps.ts
+    billing/          # one directory per @domain-* tag
+      invoices.steps.ts
+    _deprecated/      # steps pending migration
+```
+
+- One directory per `@domain-*` tag; `_common/` holds cross-cutting steps.
+  Files are named by the noun the steps act on (`invoices.steps.ts`). Two levels
+  (`steps/<domain>/<noun>.steps.ts`) is the nesting ceiling.
+- 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.
+
+## Authoring Checklist
+
+Before opening a PR that adds or edits a `.feature` file:
+
+- [ ] Every Scenario/Outline carries exactly one `@domain-*` tag.
+- [ ] No forbidden patterns (SQL, status codes, selectors, URLs, payloads,
+      framework names, explicit waits) appear in prose.
+- [ ] Each scenario has exactly one `When`.
+- [ ] `Then` clauses assert user-visible outcomes, not implementation.
+- [ ] `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
+      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/SKILL.md

@@ -19,32 +19,3 @@ vendor: playwright
 - Write tests independent of one another so they run in parallel; clean up shared state in fixtures, not afterwards.
 - Enable `trace: 'on-first-retry'` (or `'retain-on-failure'`) so CI failures are debuggable in the Trace Viewer.
 - Use a unique data set per test run, or tear down state explicitly, to prevent cross-test contamination.
-
-Standard operating procedures for robust, end-to-end (E2E) browser testing.
-
-## 1. Core Principles
-
-- **End-to-End focus:** Test the application as a user would, through the
-  browser.
-- **Auto-waiting:** Leverage Playwright's built-in auto-waiting instead of
-  hardcoded `waitForTimeout` calls.
-- **Resilience:** Write tests that survive minor UI changes (e.g., color tweaks)
-  by using robust selectors.
-
-## 2. Technical Standards
-
-- **Locators:** Use user-visible locators (e.g., `getByRole`, `getByText`,
-  `getByLabel`) over brittle CSS selectors or XPath.
-- **State Management:** Use `storageState` to reuse authentication between
-  tests, avoiding repetitive login flows.
-- **Visual Testing:** Use `toHaveScreenshot()` for critical UI layouts to detect
-  visual regressions.
-
-## 3. Best Practices
-
-- **Parallelism:** Ensure tests are independent so they can run concurrently to
-  reduce CI time.
-- **Tracing:** Enable trace recording on failure to quickly debug CI issues with
-  the Playwright Trace Viewer.
-- **Test Data:** Use a unique data set per test run or clean up state to prevent
-  cross-contamination.

package/.agents/skills/stack/qa/qa-explore-driving/SKILL.md

@@ -41,29 +41,24 @@ the read-only and no-PII boundaries are inviolable per
 [`security-baseline.md`](../../../../rules/security-baseline.md). Read this
 skill before driving a live surface; read the workflow for the phase order.
 
-## 1. Navigation-First Driving (the default)
-
-The agent reaches every surface the way a real user would. This is the
-load-bearing convention — it is what makes findings reflect a user-reachable
-state rather than an artifact of a deep link.
-
-- **Drive the running app by default.** When a live runtime is reachable, drive
-  it through the browser MCP (the chrome-devtools MCP surface). This is the
-  primary method; static driving is the interim alternative (§ 2), not the
-  norm.
-- **Start at a root.** Begin each surface at the app's home or dashboard and
-  reach the surface under test by clicking nav links, menu items, and buttons —
-  the same affordances a user has.
-- **Never URL-jump.** Do not navigate directly to a deep link to establish a
-  starting state. URL-jumping bypasses the app's real authorization and routing
-  flows, which both masks access-control gaps and produces findings that no
-  user could actually trigger.
-- **Broken navigation is a finding, not a workaround.** When an affordance is
-  missing, a nav link 404s, or a guard redirect loops, that is the finding. Do
-  not route around it with a direct URL — record it and move on.
-- **Observe, do not fabricate.** Use app-provided UI affordances to reach and
-  observe a surface. Never script the runtime to manufacture an outcome the
-  exploration is meant to discover.
+## 1. Navigation-First Driving (the default) — one prose home
+
+Navigation-first driving is the default and load-bearing convention: reach every
+surface the way a real user would so findings reflect a user-reachable state,
+not an artifact of a deep link. Its full prose statement lives once in
+[`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md) (shared
+with the known-scenario sweep) — apply it from there rather than restating it.
+In capsule:
+
+- **Drive the running app by default** through the browser MCP; static (§ 2) is
+  the interim alternative, not the norm.
+- **Start at a root and never URL-jump** — reach the surface under test by
+  clicking the affordances a real user has, never by deep-linking a starting
+  state.
+- **Broken navigation is a finding, not a workaround** — a missing affordance, a
+  nav 404, or a guard redirect loop is recorded; do not route around it.
+- **Observe, do not fabricate** — never script the runtime to manufacture an
+  outcome the exploration is meant to discover.
 
 ## 2. Static Driving — the Documented Interim
 
@@ -150,6 +145,7 @@ deployed surfaces are **driven**, not statically deferred.
 ## 5. Cross-References
 
 - Run procedure (SSOT): [`qa-explore.md`](../../../../workflows/qa-explore.md).
+- Driving rules (one prose home): [`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md).
 - Known-scenario sibling sweep: [`qa-harness`](../qa-harness/SKILL.md).
 - Browser instrumentation: [`browser-testing-with-devtools`](../../../core/browser-testing-with-devtools/SKILL.md).
 - Read-only / no-PII boundary: [`security-baseline.md`](../../../../rules/security-baseline.md).

package/.agents/skills/stack/qa/qa-harness/SKILL.md

@@ -14,13 +14,12 @@ description:
 
 ## Policy Capsule
 
-- Drive every scenario navigation-first: start at a root and reach the surface under test only via UI affordances — never URL-jump to a deep link to set up a `Given`.
-- Assert `Then` outcomes semantically against the accessibility snapshot (roles, accessible names, visible text); never via DOM/CSS/XPath selectors, HTTP status codes, response bodies, or DB rows.
+- Driving rules (navigation-first, semantic `Then`, mandatory redaction, sequential-only) live in one prose home — [`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md); apply them, do not restate them.
 - Capture console and network per surface; turn each non-allowlisted console error and each failed/error-status request into one structured `F#` finding.
 - Filter console through `qa.consoleAllowlist` via `filterConsoleMessages`; treat the allowlist as a benign-noise filter, never as a security control to silence genuine errors.
 - Spot-check surfaces against `qa.designTokens` when set; flag gross token violations (off-palette colors, off-scale spacing/typography) as findings.
 - Scrub captured console and network of tokens, session cookies, and PII before rendering any finding — findings are posted to GitHub at approval time.
-- Bundle findings by likely root cause into a draft for operator sign-off; the harness never files tickets autonomously.
+- Record findings as `QaLedgerItem`s and route them through the shared classify/route/promote core ([`qa-core.md`](../../../../workflows/helpers/qa-core.md)); the harness never files tickets autonomously.
 - Resolve the `qa` contract first and fail loudly when it is absent or malformed; there is no auto-detection fallback and no headless degrade.
 
 Guidance for executing the agent-driven QA harness through a real browser (the
@@ -35,45 +34,21 @@ live in [`testing-standards.md`](../../../../rules/testing-standards.md)
 discipline is shared with [`playwright`](../playwright/SKILL.md). Read this
 skill before instrumenting a live surface; read the workflow for the run order.
 
-## 1. Navigation-First Execution
-
-The harness reaches every surface the way a real user would. This is the
-load-bearing convention — it is what makes findings reflect a user-reachable
-state rather than an artifact of a deep link.
-
-- **Start at a root.** After sign-in, begin each scenario at the app's home or
-  dashboard. Reach the surface under test by clicking nav links, menu items,
-  and buttons — the same affordances a user has.
-- **Never URL-jump.** Do not `navigate_page` directly to a deep link to
-  establish a `Given`. URL-jumping bypasses the app's real authorization and
-  routing flows, which both masks access-control gaps and produces findings
-  that no user could actually trigger.
-- **Broken navigation is a finding, not a workaround.** When an affordance is
-  missing, a nav link 404s, or a guard redirect loops, that is the finding.
-  Do not route around it with a direct URL — record it and move on.
-- **Map Gherkin to browser actions.** `Given` establishes state by navigating
-  from the root (sign in as the persona, walk to the starting surface, seed via
-  UI where the manifest does not pre-seed). `When` performs the single user
-  action (`click`, `fill_form`, then `wait_for` the transition). Use
-  `evaluate_script` only for app-provided hooks — never to fabricate the
-  outcome a `Then` is meant to observe.
-
-### Semantic `Then` assertion
-
-Assert every `Then` against the accessibility snapshot from `take_snapshot`,
-matching on **roles, accessible names, labels, and visible text** that express
-the user-visible outcome — "a banner with text _Invoice sent_ is visible", "a
-row for _ACME Corp_ appears in the invoices table".
-
-- **Never** assert against brittle DOM/CSS/XPath selectors.
-- **Never** assert on HTTP status codes, response bodies, or DB rows inside a
-  scenario — those are contract-tier concerns (see
-  [`testing-standards.md` § Assertion Placement](../../../../rules/testing-standards.md#assertion-placement)).
-- A `Then` that can only be expressed as a wire-shape or DB check is a signal
-  the scenario is **mis-tiered**, not a license to break the semantic rule.
-
-Record each scenario's result (pass / fail / blocked), the surface it ended on,
-and a one-line user-visible symptom for any failure.
+## 1. Driving Rules Live in One Prose Home
+
+The driving rules the harness depends on — **navigation-first / never URL-jump**,
+**semantic `Then` assertion** against the accessibility snapshot, the Gherkin →
+browser-action mapping, the per-`When` write guard, mandatory evidence
+redaction, and the **sequential-only** browser rule — are stated once in
+[`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md), the
+single-scenario driver `/qa-run` delegates to. Apply them from there; this skill
+does not restate them. In short: reach every surface the way a real user would
+(start at a root, click affordances, never deep-link a `Given`), assert `Then`
+semantically (roles, accessible names, visible text — never DOM/CSS/XPath
+selectors, HTTP status, response bodies, or DB rows), and record each scenario's
+result (pass / fail / blocked), the surface it ended on, and a one-line symptom
+for any failure. Assertion-tier rules are in
+[`testing-standards.md` § Assertion Placement](../../../../rules/testing-standards.md#assertion-placement).
 
 ## 2. Per-Surface Console & Network Capture
 
@@ -126,7 +101,9 @@ skip this check entirely — do not invent a token source.
 ## 3. Findings — the `F#` Shape
 
 Every captured problem is normalized into the structured `F#` finding shape so
-the draft bundle stays diffable and the schema validates:
+the sweep can record it onto the shared ledger (each `F#` finding becomes one
+`QaLedgerItem` — see [`qa-core.md`](../../../../workflows/helpers/qa-core.md))
+and the schema validates:
 
 ```jsonc
 {
@@ -137,7 +114,6 @@ the draft bundle stays diffable and the schema validates:
   "likelyRootCause": null,          // heuristic card output (§4); null until enriched
   "disposition": "follow-up",       // blocker | follow-up
   "acceptance": null,               // AC this folds into, when known
-  "foldsInto": "F2",                // optional: another finding this is a duplicate facet of
   "evidence": {
     "console": [{ "level": "error", "text": "..." }],
     "network": []
@@ -172,12 +148,14 @@ and let the operator triage from the symptom.
 | `Failed to fetch` / `NetworkError` / CORS-rejected request | Misconfigured CORS allowlist, wrong origin, or a downed dependency | follow-up |
 | Hydration / mismatch warning escalated to error | Server/client render divergence | follow-up |
 | Off-palette color, off-scale spacing/typography | Design-token drift — hard-coded value bypassing the token | follow-up |
-| Repeated identical console error across many surfaces | A shared component or global bootstrap fault | fold the duplicates into one finding via `foldsInto` |
+| Repeated identical console error across many surfaces | A shared component or global bootstrap fault | record once; the shared route/dedup core collapses duplicates at triage |
 
 Heuristics for working the cards:
 
-- **Fold duplicates.** When the same error fires on many surfaces, emit one
-  finding and point the rest at it with `foldsInto` rather than filing N copies.
+- **Record once, let dedup collapse.** When the same error fires on many
+  surfaces, record it once rather than filing N copies; the shared
+  classify/route/dedup core ([`qa-core.md`](../../../../workflows/helpers/qa-core.md))
+  collapses duplicates at triage against the fingerprint footer.
 - **Blocker vs. follow-up.** A finding is a **blocker** when it breaks the
   scenario's user-visible outcome or exposes an authorization gap. Everything
   else (noise that does not break the journey, cosmetic token drift) is a
@@ -186,13 +164,15 @@ Heuristics for working the cards:
   symptom and leave `likelyRootCause: null`. A wrong guess is worse than an
   honest "unknown" the operator can triage.
 
-## 5. Draft & Sign-Off (Never File Autonomously)
+## 5. Record onto the Ledger & Triage (Never File Autonomously)
 
-Bundle findings **by likely root cause** into proposed follow-up tickets with
-`Depends-on` / `Blocks` relationships, then present the draft for operator
-approval. The harness **MUST NOT** create tickets autonomously — it stops at a
-draft. The operator-approval gate is the safety boundary against spurious
-filing.
+Record each `F#` finding as a `QaLedgerItem` on the shared session ledger under
+`temp/qa/`, then route the ledger through the shared classify → route →
+disposition → promote core — both stated once in
+[`qa-core.md`](../../../../workflows/helpers/qa-core.md). The harness **MUST
+NOT** create tickets autonomously: findings are promoted through `/plan` only
+after the operator confirms each disposition at the HITL write gate. That gate
+is the safety boundary against spurious filing.
 
 ## 6. Sign-In & Contract Discipline
 
@@ -211,6 +191,8 @@ filing.
 ## 7. Cross-References
 
 - Run procedure (SSOT): [`qa-run.md`](../../../../workflows/qa-run.md).
+- Driving rules (one prose home): [`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md).
+- Shared QA core (contract/session/redaction/ledger/triage/HITL): [`qa-core.md`](../../../../workflows/helpers/qa-core.md).
 - Console filter module: [`console-allowlist.js`](../../../../scripts/lib/qa/console-allowlist.js).
 - Assertion-tier rules: [`testing-standards.md`](../../../../rules/testing-standards.md).
 - Scenario prose: [`gherkin-authoring`](../gherkin-authoring/SKILL.md).

package/.agents/skills/stack/qa/vitest/SKILL.md

@@ -20,32 +20,3 @@ vendor: vitest
 - Use snapshots only for large, stable data structures; avoid them for frequently changing UI to prevent snapshot fatigue.
 - Aim for 80%+ coverage on business logic and edge cases; audit with `vitest --coverage`.
 - Test observable behavior, not internal implementation details; refactors should not require rewriting passing tests.
-
-Guidelines for writing fast, reliable unit and integration tests.
-
-## 1. Core Principles
-
-- **Speed:** Tests should be fast enough to run on every file save.
-- **Isolation:** Each test must be independent. Avoid shared state between
-  tests.
-- **Confidence:** Tests should verify behavior, not implementation details.
-
-## 2. Technical Standards
-
-- **Mocking:** Use `vi.mock()` for external dependencies (APIs, network calls)
-  and `vi.spyOn()` for monitoring function calls.
-- **Snapshot Testing:** Use snapshots for large, stable data structures, but
-  avoid them for frequently changing UI components to prevent "snapshot
-  fatigue."
-- **Coverage:** Aim for 80%+ coverage on business logic and edge cases. Use
-  `vitest --coverage` for auditing.
-
-## 3. Best Practices
-
-- **Descriptive Titles:** Use the
-  `describe('Component/Utility', () => { it('should [action] when [condition]') })`
-  pattern.
-- **Arrange-Act-Assert (AAA):** Structure tests clearly into setup (Arrange),
-  execution (Act), and verification (Assert) phases.
-- **Edge Cases:** Always include tests for error states, null/undefined inputs,
-  and boundary conditions.

package/.agents/workflows/audit-accessibility.md

@@ -4,6 +4,25 @@ description: Audit WCAG accessibility conformance (static-first) with an optiona
 
 # Accessibility (WCAG) Audit
 
+You are a Senior Accessibility Engineer holding the frontend to **WCAG 2.x
+conformance** — semantic structure, ARIA correctness, keyboard operability, form
+labelling, media alternatives, and contrast — grounding every finding in a
+concrete element and the success criterion it violates. Default to **static**
+detection over source; escalate to a **runtime** pass only when a live target is
+configured. The shared lens machinery — read-only constraint, scope
+interpretation, report envelope + finding-block skeleton, severity scale,
+self-cross-check, and execution strategy — lives in
+[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
+`{{auditOutputDir}}/audit-accessibility-results.md`. Extra finding fields:
+**WCAG:** (the violated success criterion, e.g. `1.1.1 Non-text Content (A)`)
+and **Evidence:** (`measured | static` + the observable; single-run runtime
+numbers are tagged `provisional`). The report adds a **Runtime Verification**
+section.
+
+> **No conformance certification.** The lens reports findings against WCAG
+> success criteria; it does **not** assert a conformance level (A / AA / AAA)
+> for the product. "No findings in scope" is not "certified conformant".
+
 ## Applicability
 
 **Web targets only.** Registered with `target: "web"` in
@@ -12,28 +31,6 @@ on a project with no rendered frontend, since there are no components, templates
 or routes to hold to WCAG. See the `target` key's schema description for how
 applicability is probed from the consumer's checkout.
 
-## Role
-
-Senior Accessibility Engineer. You hold the frontend to **WCAG 2.x
-conformance** — semantic structure, ARIA correctness, keyboard operability,
-form labelling, media alternatives, and contrast — grounding every finding in a
-concrete element and the success criterion it violates. You default to
-**static** detection over the source, and escalate to a **runtime** pass only
-when a live target is configured.
-
-## Context & Objective
-
-This is a **read-only** audit. Detect WCAG violations statically from the
-component/template/route source, optionally corroborate them against a running
-build, and emit a structured Markdown report at
-`{{auditOutputDir}}/audit-accessibility-results.md`. Do not modify application
-code — surfacing the violations (each keyed to a WCAG success criterion) is the
-deliverable; fixing them is a separate pass.
-
-> **No conformance certification.** The lens reports findings against WCAG
-> success criteria; it does **not** assert a conformance level (A / AA / AAA)
-> for the product. "No findings in scope" is not "certified conformant".
-
 ## Boundary with `audit-ux-ui`
 
 These two web lenses share a border and must not double-report:
@@ -43,35 +40,26 @@ These two web lenses share a border and must not double-report:
   understand the surface? Semantic HTML, ARIA, keyboard/focus, labelled
   controls, text alternatives, and contrast against the WCAG ratio thresholds.
 - **`audit-ux-ui`** owns **design-system adherence** — the consistency
-  question: do components and tokens match the project's own design system
-  (hardcoded values that bypass a token, raw elements that should defer to a
-  design-system component, interaction/loading/error states, premium feel)?
+  question: do components and tokens match the project's own design system?
 
 Contrast is the one axis both can touch: **accessibility owns the WCAG ratio
 verdict** (4.5:1 body / 3:1 large text / 3:1 non-text), while ux-ui owns whether
 the colour came from a sanctioned token. When a contrast defect is in scope for
 both, report the WCAG failure here and leave the token-adherence note to ux-ui.
 
-## Scope (Story / plan-run mode)
+## Scope
 
-When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
-following block is populated with the Story (or plan-run) change-set file list.
-Otherwise — for any manual `/audit-<dimension>` invocation — the block
-renders the literal substitution token and you MUST treat it as **no
-scope filter — run the lens codebase-wide** exactly as you would have
-before this section existed.
+Interpret this lens's change-set fence per the core's Scope interpretation:
 
 ```text
 {{changedFiles}}
 ```
 
-- If the block above contains a newline-delimited list of file paths,
-  restrict your analysis to those files (and their direct dependencies
-  when the lens explicitly calls for cross-file reasoning).
-- If the block above renders as the literal string `{{changedFiles}}`
-  (i.e. no substitution was supplied), ignore this section entirely and
-  proceed with the full codebase-wide scan defined in the remaining
-  steps.
+## Execution strategy
+
+Run this lens as a single `subagent_type: auditor` dispatch returning the report
+path + Executive Summary; sequential inline execution is the fallback (see the
+core's Execution strategy).
 
 ## Step 0: Discover the frontend surface and config (run first)
 
@@ -98,8 +86,6 @@ exists in scope, say so and emit an empty report rather than inventing findings.
 
 ## Step 1: Static WCAG detection, then triage
 
-> Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
-
 Run the **mechanical detectors first** (cheap, deterministic greps and the
 static a11y linters discovered in Step 0), then apply **LLM triage** to each
 candidate — a mechanical hit is a _candidate_, not automatically a finding.
@@ -173,71 +159,11 @@ Corroborate static findings against the runtime results (a statically-flagged
 contrast defect confirmed by the engine graduates from provisional to
 confirmed), and surface runtime-only violations the static pass could not see.
 
-## Step 3: Output Requirements
-
-Generate and save a structured Markdown report to
-`{{auditOutputDir}}/audit-accessibility-results.md`, using the exact template
-below. The report MUST include all sections, even if empty (write
-"_No findings._" rather than omitting a section).
-
-> Grade every finding's severity on the shared
-> [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md), and
-> key every finding to the WCAG success criterion it violates.
-
-```markdown
-# Accessibility (WCAG) Audit report
-
-## Executive Summary
-
-[Overview of WCAG conformance health across the scope, the runtime mode's
-status (ran against `<env>` / skipped — no target configured), and the
-self-cross-check line.]
-
-## Detailed Findings
-
-[For every WCAG violation identified, use the following strict structure. Lead
-each title with the primary file the finding lives in:]
-
-### `path/to/primary-file.ext` — [Short title of the issue]
-
-- **Dimension:** [e.g., Semantic Structure | ARIA | Keyboard & Focus | Forms & Labels | Media Alternatives | Contrast]
-- **Severity:** [Critical | High | Medium | Low]
-- **WCAG:** [success criterion — e.g. `1.1.1 Non-text Content (A)`]
-- **Location:** `path/to/primary-file.ext:line`
-- **Evidence:** [measured | static] [the observable — a quoted element, the
-  computed contrast ratio, the failing axe/Lighthouse audit id + median score.
-  Runtime numbers from a single run are tagged `provisional`.]
-- **Current State:** [what is implemented and why it fails the criterion]
-- **Recommendation & Rationale:** [the specific change — attribute to add,
-  element to swap, token to adjust — and the assistive-technology behaviour it
-  restores]
-- **Acceptance signal:** [the command or observable that proves this finding is
-  remediated — e.g. the axe rule now passing on the route, or a re-run of this
-  lens]
-- **Agent Prompt:**
-  `[A copy-pasteable, highly specific prompt to execute this a11y fix independently]`
-
-## Runtime Verification
-
-[Per-route median-of-3 accessibility scores when the runtime mode ran, or
-"_Runtime corroboration unavailable — no `qa.environments` target configured._"]
-```
-
-## Constraint
-
-This is a **read-only** audit. Provide the critique and implementation
-suggestions, but do not modify components, styles, or configuration. The
-runtime mode runs **non-mutating** measurements only and starts no arbitrary
-dev server.
-
-## Self-cross-check (mandatory — filter false positives before you finalize)
+## Report additions
 
-Before you write the report artifact from the previous step, run the shared
-adversarial self-cross-check over your Detailed Findings — see
-[`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
-per-finding evidence bar, the exclusion list, and the final re-open-and-drop
-pass whose `kept <k> / dropped <d>` counts you record in the Executive
-Summary, so the sequential single-pass path filters unverified findings just as
-the orchestrated path's adversarial reviewer does. Drop every claimed
-violation that names no concrete element and no specific WCAG success
-criterion.
+Beyond the shared skeleton, the Executive Summary states the runtime mode's
+status (ran against `<env>` / skipped — no target configured), and the report
+ends with a **Runtime Verification** section: per-route median-of-3
+accessibility scores when the runtime mode ran, or "_Runtime corroboration
+unavailable — no `qa.environments` target configured._" Drop every claimed
+violation that names no concrete element and no specific WCAG success criterion.