mandrel 2.40.0 → 2.41.0

package/.agents/skills/core/qa-coverage-mapping/SKILL.md

@@ -1,105 +0,0 @@
----
-name: qa-coverage-mapping
-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.
-allowed_tools:
-  - Read
-  - Bash
----
-
-# qa-coverage-mapping
-
-## Policy Capsule
-
-- The three-tier taxonomy (unit / contract / acceptance), tier-placement rules, and assertion-placement constraints live in `.agents/rules/testing-standards.md`; that rule is the SSOT and wins on any conflict — this skill only maps a finding onto those tiers.
-- Compute the verdict through the deterministic helper `coverageVerdict(...)` in `.agents/scripts/lib/qa/coverage-verdict.js`; never re-derive tier placement by hand in prose.
-- Build the `surface` input by gathering the finding's symbol and the colocated/contract/acceptance tests that exercise it — pass test paths (or `{path, tier}` descriptors) so the helper classifies each one.
-- Read the verdict as a `{unit, contract, acceptance}` object: each tier is `{status: 'present'|'absent', note}`. A surface with only a colocated unit test reports `unit: present` and `contract`/`acceptance`: `absent` with explanatory notes.
-- Route remediation by the absent tiers, honoring the assertion-placement rule: wire-shape and status-code gaps become **contract** tests, user-visible journey gaps become **acceptance** scenarios — never push those into unit tests or `.feature` files incorrectly.
-- Treat `absent` as a coverage gap to surface, not an automatic failure: some surfaces legitimately need only one tier (a pure formatter needs no acceptance scenario). Use the notes to justify, not to mandate, the missing tier.
-- This skill is read + classify only: it does not author tests, mutate tickets, or run the suite. Hand the verdict to the TDD cycle in `.agents/rules/testing-standards.md` to actually write the missing tier.
-
-## Role
-
-You are the coverage cartographer. Given a finding that names a code surface
-(a symbol — function, class, or module export — plus the tests around it), you
-produce a structured per-tier verdict that says, for each of the three test
-tiers in [`.agents/rules/testing-standards.md`](../../../rules/testing-standards.md),
-whether coverage is **present** or **absent**, and why. You do not write the
-missing tests; you tell the operator (or the next skill) exactly which tier is
-missing so remediation is aimed correctly.
-
-## When to use
-
-- A quality / audit finding points at a specific symbol and you need to know
-  whether it is already tested, and at which tier.
-- Before remediating a coverage gap, to decide whether the missing test is a
-  **unit**, **contract**, or **acceptance** test (the assertion-placement rule
-  makes this decision load-bearing — a status-code gap must become a contract
-  test, not a unit test).
-- During a test-pyramid audit, to roll up many surfaces into a tier-by-tier
-  gap report.
-
-**When NOT to use:** for authoring tests (use the TDD cycle in
-[`.agents/rules/testing-standards.md`](../../../rules/testing-standards.md#applying-the-standards)),
-for measuring line/branch coverage percentages (that is the unit-tier coverage
-config, not this skill), or for anything that requires running the suite.
-
-## The verdict shape
-
-`coverageVerdict(surface)` returns:
-
-```json
-{
-  "unit":       { "status": "present" | "absent", "note": "…" },
-  "contract":   { "status": "present" | "absent", "note": "…" },
-  "acceptance": { "status": "present" | "absent", "note": "…" }
-}
-```
-
-- `status` is `present` when at least one classified test exercises the surface
-  at that tier, `absent` otherwise.
-- `note` is always populated. For `present` tiers it summarizes the count; for
-  `absent` tiers it explains the gap and echoes the symbol so the report reads
-  cleanly.
-
-## How to apply
-
-1. **Identify the surface.** From the finding, capture the `symbol` and the
-   list of tests that touch it — colocated `*.test.*`, anything under
-   `tests/contract/**`, and any `.feature` scenario.
-2. **Classify and verdict.** Pass the surface to `coverageVerdict`. Each test
-   is classified by path (`.feature` → acceptance, `…/contract/…` or
-   `.contract.test.*` → contract, `.test.*` or `__tests__/` → unit) or by an
-   explicit `tier` field when you already know it.
-3. **Read the gaps.** Every `absent` tier is a candidate gap. Apply judgment
-   from the Policy Capsule: not every surface needs all three tiers.
-4. **Route remediation.** For real gaps, hand off to the TDD cycle in
-   `.agents/rules/testing-standards.md` with the missing tier named, honoring
-   the assertion-placement rule so each assertion lands in its correct tier.
-
-## Example
-
-```js
-import { coverageVerdict } from '../../../scripts/lib/qa/coverage-verdict.js';
-
-const verdict = coverageVerdict({
-  symbol: 'parseInvoice',
-  tests: ['src/invoice/parse-invoice.test.js'],
-});
-
-// verdict.unit.status       === 'present'
-// verdict.contract.status   === 'absent'   // wire-shape gap → contract test
-// verdict.acceptance.status === 'absent'   // no user journey covered here
-```
-
-A colocated-unit-only surface like `parseInvoice` reports `unit` present and
-both `contract` and `acceptance` absent with explanatory notes — exactly the
-signal you need to decide whether the boundary (`contract`) or a user-visible
-journey (`acceptance`) still needs a test, or whether a pure parser is
-legitimately unit-only.

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

@@ -1,152 +0,0 @@
----
-name: qa-explore-driving
-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.
----
-
-# Skill: qa-explore-driving
-
-## Policy Capsule
-
-- Drive the running app **by default** through the browser MCP, navigation-first: start at a root and reach each surface only via UI affordances — never URL-jump to a deep link.
-- Resolve the target **environment** at Plan time (via `resolveQaEnvironment`) and record its name in the ledger; each environment keys its own `baseUrl`, `signInSeam`, and `allowWrites`.
-- Treat **static driving** (reading source, routes, and rendered markup without a live runtime) as the **documented interim** method, chosen at Plan time **only where no seam resolves** for the target environment — never the silent fallback.
-- Hold the **read-only capture invariant** absolutely: the agent makes no source edits and no product mutations while driving; the only write is appending to the `temp/qa/<sessionId>` ledger.
-- Authenticated driving follows the resolved environment's **`signInSeam`**: sign in through a dev `url` seam (persona name substituted into the template) or a `skill` seam (a stored `credentialRef` read by the named sign-in skill), with **mandatory redaction** of all captured evidence. Never type real credentials inline or fabricate a session; where an environment resolves no seam, drive the unauthenticated surface or fall back to static and record the gap.
-- Pick the driving method explicitly in the Plan phase (drive vs. static) and record it in the ledger; do not switch methods mid-surface without a new Plan note.
-- Every phase transition and every GitHub write is HITL-gated; the agent drives and captures, but never files or promotes findings autonomously.
-- Broken navigation, a missing affordance, or a guard redirect loop is a **finding**, not a workaround — record it and move on; do not route around it with a direct URL.
-- Scrub captured evidence (tokens, session cookies, PII) at the boundary via the shared redaction path before any finding reaches disk or GitHub.
-
-Guidance for the **agent-driven** half of exploratory QA. `/qa-explore` is the
-agent-led front-end (the agent drives, the operator watches); its human-led
-sibling is `/qa-assist` (the human drives, the agent scribes). The exploration
-**procedure** — argument parsing, phase gates, contract resolution, ledger
-plumbing — is the SSOT in
-[`qa-explore.md`](../../../../workflows/qa-explore.md); this skill shows **how**
-to apply the driving conventions that procedure depends on. The
-navigation-first execution and per-surface capture discipline are shared with
-[`qa-harness`](../qa-harness/SKILL.md) (the known-scenario sweep); browser
-instrumentation lives in
-[`browser-testing-with-devtools`](../../../core/browser-testing-with-devtools/SKILL.md);
-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) — 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
-
-Static driving is the **explicitly documented interim** method for when **no
-seam resolves** for the target environment — the resolved environment carries
-no `signInSeam` the agent can drive through (§ 4). It walks the surface from
-source, route definitions, and rendered markup rather than a running browser.
-
-- **Choose it at Plan time, never silently.** Static is a deliberate Plan-phase
-  decision recorded in the ledger ("environment: preview, method: static,
-  reason: no seam resolves"), not an unannounced fallback the agent slips into
-  when the browser MCP hiccups.
-- **It is interim, not equivalent.** Static driving cannot exercise real
-  authorization, routing guards, or runtime console/network signal. Treat its
-  coverage as partial and say so in the ledger; a static pass does not close the
-  same coverage a driven pass would.
-- **Same read-only invariant.** Static driving reads source and routes; it makes
-  no edits. The read-only capture invariant (§ 3) applies identically.
-- **Promote to driving when a seam lands.** Static is the bridge until the
-  target environment resolves a `signInSeam` (§ 4) that makes driven
-  authenticated exploration possible. When that lands, re-run the surface
-  driven; do not leave a surface permanently static when it could be driven.
-
-## 3. The Read-Only Capture Invariant
-
-The agent-driven Capture phase is **strictly read-only**. This invariant is
-inviolable per [`security-baseline.md`](../../../../rules/security-baseline.md)
-and the Story's security considerations — it is not a soft preference.
-
-- **No source edits.** The agent does not modify application code, config, or
-  tests while driving. Exploration observes; it never repairs.
-- **No product mutations.** The agent does not create, update, or delete product
-  data, submit destructive forms, or trigger irreversible actions to "see what
-  happens". When a surface's only path forward is a mutating action, record the
-  boundary as the finding and stop — do not cross it.
-- **The only write is the ledger.** The single permitted side effect of Capture
-  is appending finding lines to the session ledger under
-  `temp/qa/<sessionId>`. Everything else is observation.
-- **Scrub before persisting.** Strip tokens, session cookies, Authorization
-  headers, and PII from captured console and network evidence via the shared
-  redaction path **before** any finding reaches disk or GitHub. Captured
-  evidence is untrusted until scrubbed.
-- **HITL gates every write outward.** Phase transitions and GitHub writes
-  (ticket creation, promotion) happen only behind an operator confirmation gate.
-  The agent never files or promotes findings autonomously.
-
-## 4. Authenticated Driving Follows the Per-Environment Seam
-
-Driving an **authenticated** surface requires signing in. The resolved target
-environment (via `resolveQaEnvironment`, § Policy Capsule) carries the
-`signInSeam` the agent drives through — the same discriminated-union shape
-`qa-harness` resolves via its contract. When a seam resolves, authenticated
-deployed surfaces are **driven**, not statically deferred.
-
-- **Drive the authenticated surface through the seam.** When the target
-  environment carries a `signInSeam`, sign in via that seam and then reach the
-  authenticated surface navigation-first — including authenticated **deployed**
-  hosts. The two seam kinds:
-  - **`kind: 'url'` (dev impersonation).** Substitute the persona **name** into
-    the seam's URL template and navigate there. The persona name is the sole
-    input; no per-persona auth material is read.
-  - **`kind: 'skill'` (procedural / credential).** Invoke the named consumer
-    sign-in skill, which reads a per-persona **`credentialRef`** — an indirect
-    handle to a stored credential, never an inline secret. Read the skill's
-    `SKILL.md` and follow it.
-- **Never enter real credentials inline.** The agent MUST NOT type real
-  usernames, passwords, or tokens to reach an authenticated surface, and MUST
-  NOT fabricate or forge a session. Sign-in flows only through the seam, which
-  consumes a persona name or a `credentialRef` indirection — never a
-  hand-typed secret. This is a hard security boundary, not a convenience to
-  work around.
-- **Redaction is mandatory.** Every captured evidence string — console,
-  network, headers — passes through the shared redaction path (§ 3) before it
-  reaches disk or GitHub; bearer tokens, session cookies, `Authorization`
-  headers, and PII are masked. Authenticated driving raises the stakes on
-  redaction, it does not relax it.
-- **Static only where no seam resolves.** When the target environment resolves
-  **no** `signInSeam`, drive only the unauthenticated surface or fall back to
-  static driving (§ 2), and record the gap in the ledger so the partial
-  coverage is visible. A surface that could not be driven because the
-  environment carries no seam is itself a coverage signal worth recording, not
-  a silent skip.
-
-## 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).
-- Assertion-tier rules: [`testing-standards.md`](../../../../rules/testing-standards.md).

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

@@ -1,22 +0,0 @@
----
-name: vitest
-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.
-vendor: vitest
----
-
-# Skill: Vitest
-
-## Policy Capsule
-
-- Keep each test independent — never share mutable state between tests; reset mocks in `afterEach`.
-- Mock external dependencies with `vi.mock()`; use `vi.spyOn()` only to observe call shape, not to replace logic.
-- Structure tests as Arrange / Act / Assert — do not interleave the three phases.
-- Use descriptive titles in the `describe('Component', () => { it('should [action] when [condition]') })` form.
-- Cover error paths, null/undefined inputs, and boundary conditions, not just the happy path.
-- 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.