peaks-loop 3.0.0

package/skills/peaks-qa/references/qa-perf-test-plan.md

@@ -0,0 +1,67 @@
+# Performance test plan (project-level, slice 025)
+
+> Body of `## Performance test plan`. Slice 025 introduces a
+> project-level performance baseline that is **stable across slices
+> within a session** and is refreshed only when a slice's diff matches
+> the trigger table. The per-slice
+> `qa/performance-findings-<rid>.md` references this baseline by path +
+> hash.
+
+## File location
+
+`.peaks/_runtime/<sessionId>/qa/perf-baseline.md`. The CLI is
+`peaks workflow plan read perf --project <repo> --json` /
+`peaks workflow plan refresh perf --project <repo> --apply` /
+`peaks workflow plan detect-trigger --project <repo> --rid <rid> --json`.
+
+## Perf generation workflow
+
+1. `peaks workflow plan read perf --project <repo> --json` — return the
+   existing baseline envelope. When missing, proceed to step 2.
+2. `peaks workflow plan detect-trigger --rid <rid> --project <repo> --json`
+   — return `{ triggered, reason }`. The perf baseline is refreshed on
+   the same triggers as the security plan: new dep, new route/hook
+   registration, or `--refresh`.
+3. If `triggered: true`, run
+   `peaks workflow plan refresh perf --project <repo> --apply --json`.
+4. The slice's `qa/performance-findings-<rid>.md` opens with the
+   `## Plan reference` block referencing the baseline hash + path.
+5. The slice result records the diff vs the baseline threshold
+   (lighthouse / k6 / autocannon output) — see peaks-rd's
+   `mandatory-perf-baseline.md` for the RD-side measurement workflow.
+
+## Perf content schema (deterministic)
+
+- `## CLI Command Inventory` — auto-enumerated from
+  `src/cli/commands/*-commands.ts`. Sorted alphabetically.
+- `## Routes / Hooks` — fixed narrative. CLI is a CLI tool, no HTTP.
+- `## Baseline Measurements` — placeholder table; the RD fills the
+  actual numbers (CLI does not call measurement tools).
+- `## Thresholds` — placeholder; RD fills per-route thresholds.
+
+## Perf refresh trigger table (shared with security plan)
+
+| Signal | Reason string | Re-generates the baseline? |
+|---|---|---|
+| New dep in `dependencies` / `optionalDependencies` | `new-dependency` | yes |
+| New file under `src/services/{auth,security,secrets,payments,filesystem}/` | `auth-surface-added` | yes |
+| New `*auth*.ts` file anywhere in `src/` | `auth-surface-added` | yes |
+| New route / command registration (`router.ts`, `commands/*-commands.ts`) | `hot-path-added` | yes |
+| `--refresh` on the slice workflow | `manual-override` | yes |
+| devDependencies change only | (none) | no — locked Q1 default |
+| Pure text edits to `rd/*` or `qa/test-cases/*` | (none) | no |
+
+## Perf back-compat (1 minor release)
+
+The pre-slice-025 non-suffixed `qa/performance-findings.md` is still
+accepted by `peaks workflow verify-pipeline` Gate C during the
+1-minor-release window. The path resolver
+(`src/services/workflow/artifact-paths.ts`) handles the fallback and
+emits a `legacy-redirect` warning.
+
+## Perf CLI surface recap
+
+| Command | Returns | JSON shape |
+|---|---|---|
+| `peaks workflow plan read perf --project <repo>` | `exists`, `path`, `hash`, `refreshedAt`, `source` | `{ ok, command, data: { ... } }` |
+| `peaks workflow plan refresh perf --project <repo> [--apply]` | `writtenFiles`, `wouldWrite`, `hash`, `refreshedAt`, `dryRun` | `{ ok, command, data: { ... } }` |

package/skills/peaks-qa/references/qa-refactor-role.md

@@ -0,0 +1,3 @@
+# Refactor role (QA)
+
+> Body of `## Refactor role`. For refactors, QA must be involved before implementation. It defines the regression and acceptance surface, then verifies the same surface after implementation.

package/skills/peaks-qa/references/qa-runbook.md

@@ -0,0 +1,72 @@
+## Default runbook (QA)
+
+> Body of `## Default runbook` + numbered runbook steps #0–#9. The default sequence the QA skill should execute. Do not skip the boundary check, the unit test gate, the validation report, or — when frontend is in scope — the Playwright MCP browser gate.
+
+```bash
+# 0. confirm QA's own runbook integrity before validating anything
+peaks skill runbook peaks-qa --json
+peaks skill presence:set peaks-qa --project <repo>  # show persistent skill presence every turn
+
+# 1. capture the QA request artifact and read upstream scope
+peaks request init --role qa --id <request-id> --project <repo> --apply --json
+peaks request show <request-id> --role prd --project <repo> --json
+peaks request show <request-id> --role rd  --project <repo> --json
+peaks request show <request-id> --role ui  --project <repo> --json   # if UI involved
+
+# 2. standards preflight and red-line boundary check against the diff
+peaks standards init   --project <repo> --dry-run --json
+peaks standards update --project <repo> --dry-run --json
+peaks codegraph affected --project <repo> <changed-files...> --json   # regression-surface hint
+
+# 3. OpenSpec exit gate when openspec/ exists
+peaks openspec validate <change-id> --project <repo> --json
+peaks openspec validate <change-id> --project <repo> --prefer-external --json   # optional
+
+# 4. generate test cases — MANDATORY, write to .peaks/_runtime/<sessionId>/qa/test-cases/<request-id>.md
+#    categories: unit, integration, UI regression (frontend only)
+#
+#    Optimization (slice 004): peaks-rd's parallel fan-out now includes a 4th
+#    sub-agent (`qa-test-cases-writer`) that pre-drafts this file at the
+#    end of RD implementation. If `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md`
+#    already exists when QA's main loop reaches this step, **QA does NOT
+#    re-draft it** — it just verifies the file is present and the
+#    per-criterion `ts` snippets are syntactically valid, then proceeds
+#    to step 5 (EXECUTE). Fallback: if the file is missing, QA drafts it inline.
+
+# 5. EXECUTE tests against the actual implementation — Peaks-Cli Gate A2
+#    Run the project test command. Record output. Tests on paper are worthless.
+#    NOTE (v2.11.0 D1/D4): Security review + performance check are NOT run by peaks-qa.
+#    They are owned by peaks-rd's audit fan-out and surface as rd/security-review.md and
+#    rd/perf-baseline.md under .peaks/_runtime/<sessionId>/rd/. Read them by reference;
+#    do NOT re-do them or create qa/security-findings.md / qa/performance-findings.md.
+
+# 6. write test-report — MANDATORY, write to .peaks/_runtime/<sessionId>/qa/test-reports/<request-id>.md
+#    MUST contain actual execution results (pass/fail counts, coverage %, findings).
+
+# 7. frontend browser validation (when frontend is in scope)
+# Slice #016: peaks-cli no longer manages MCP install/dispatch. The LLM
+# checks its own tool list for any Playwright MCP entry. If absent,
+# QA reports the missing tool and tells the user the install command
+# (`claude mcp add playwright -- npx @playwright/mcp@latest`).
+# DEV-SERVER REQUIREMENT (BLOCKING): a running dev server is REQUIRED for browser E2E.
+# The same lifecycle applies to ANY service QA starts: capture PID on startup, validate, then kill.
+# NEVER substitute a production build for browser E2E. After browser validation completes, KILL the dev server.
+# Playwright MCP MUST simulate real user operations — not just take static screenshots.
+# The LLM invokes the tools by name from its own tool list.
+
+# 8. write per-criterion acceptance results, regression matrix, security/performance findings,
+#    and the final verdict into the QA request artifact. Mark state=verdict-issued.
+#    BEFORE the transition, run the QA quality-gate CLI checks (see Peaks-Cli Gate E/F):
+peaks scan acceptance-coverage --rid <rid> --project <repo> --json
+# → ok=false → BLOCKED. Some PRD acceptance items have no linked test case.
+peaks request lint <rid> --role qa --project <repo> --json
+# → ok=false → BLOCKED. The QA artifact body has unfilled <placeholders> or "..." stubs.
+
+# 9. on verdict=return-to-rd, route findings back through the request id; otherwise close.
+peaks request show <request-id> --role qa --project <repo> --json
+peaks openspec archive <change-id> --project <repo> --json   # preview, then --apply on full pass
+peaks project memories:extract --session-id <session-id> --project <repo> --json  # extract durable memories
+peaks skill presence:clear --project <repo>                      # QA complete, remove presence indicator
+```
+
+Verdict `pass` is blocked until every applicable validation gate has evidence in the artifact.

package/skills/peaks-qa/references/qa-security-test-plan.md

@@ -0,0 +1,73 @@
+# Security test plan (project-level, slice 025)
+
+> Body of `## Security test plan`. Slice 025 introduces a project-level
+> security test plan that is **stable across slices within a session**
+> and is refreshed only when a slice's diff matches the trigger table.
+> The per-slice `qa/security-findings-<rid>.md` references this plan by
+> path + hash; the plan itself is NOT regenerated per slice.
+
+## Location
+
+`.peaks/_runtime/<sessionId>/qa/security-test-plan.md`. The CLI is
+`peaks workflow plan read security --project <repo> --json` /
+`peaks workflow plan refresh security --project <repo> --apply` /
+`peaks workflow plan detect-trigger --project <repo> --rid <rid> --json`.
+
+## Generation workflow
+
+1. `peaks workflow plan read security --project <repo> --json` — return
+   the existing plan envelope (exists, path, hash, refreshedAt). When
+   the plan does not exist, the slice workflow proceeds to step 2.
+2. `peaks workflow plan detect-trigger --rid <rid> --project <repo> --json`
+   — return `{ triggered, reason }` based on the trigger table below.
+3. If `triggered: true`, run
+   `peaks workflow plan refresh security --project <repo> --apply --json`
+   — atomic write; the response carries the new hash + refreshedAt.
+4. The slice's `qa/security-findings-<rid>.md` opens with the
+   `## Plan reference` block: `plan-hash: <hash>`, `plan-path: <path>`,
+   `unchanged-since: <prev-rid> | new`.
+5. Re-read with `peaks workflow plan read security` to confirm the
+   post-write envelope matches the value embedded in the slice result.
+
+## Content schema (deterministic — body is normalized before hashing)
+
+- `## Threat Model` — fixed narrative. Auth boundary, secret storage,
+  external API surface, file system writes.
+- `## Sensitive Service Files` — auto-enumerated from
+  `src/services/{auth,security,secrets,payments,filesystem}/`. Empty
+  buckets render as `- (none)`. Files sorted alphabetically.
+- `## Auth Surface (*auth*.ts files repo-wide)` — auto-enumerated.
+- `## Runtime Dependencies` — split into `dependencies` and
+  `optionalDependencies` (per locked decision 1, `devDependencies` are
+  **excluded** from the trigger scan and from the plan body).
+- `## Test Matrix` — fixed narrative. Points the slice workflow at
+  peaks-qa's per-slice diff scan.
+
+## Refresh trigger table (locked decision 1)
+
+| Signal | Reason string | Re-generates the plan? |
+|---|---|---|
+| New dep in `dependencies` / `optionalDependencies` | `new-dependency` | yes |
+| New file under `src/services/{auth,security,secrets,payments,filesystem}/` | `auth-surface-added` | yes |
+| New `*auth*.ts` file anywhere in `src/` | `auth-surface-added` | yes |
+| New route / command registration (`router.ts`, `commands/*-commands.ts`) | `hot-path-added` | yes |
+| `--refresh` on the slice workflow | `manual-override` | yes |
+| devDependencies change only | (none) | no — locked Q1 default |
+| Pure text edits to `rd/*` or `qa/test-cases/*` | (none) | no |
+
+## Back-compat (1 minor release)
+
+The pre-slice-025 non-suffixed `qa/security-findings.md` is still
+accepted by `peaks workflow verify-pipeline` Gate C during the
+1-minor-release window. The path resolver
+(`src/services/workflow/artifact-paths.ts`) handles the fallback and
+emits a `legacy-redirect` warning in the gate's violation list. The
+form is rejected after the next minor bump.
+
+## CLI surface recap
+
+| Command | Returns | JSON shape |
+|---|---|---|
+| `peaks workflow plan read security --project <repo>` | `exists`, `path`, `hash`, `refreshedAt`, `source` | `{ ok, command, data: { ... } }` |
+| `peaks workflow plan refresh security --project <repo> [--apply]` | `writtenFiles`, `wouldWrite`, `hash`, `refreshedAt`, `dryRun` | `{ ok, command, data: { ... } }` |
+| `peaks workflow plan detect-trigger --project <repo> --rid <rid> [--refresh]` | `triggered`, `reason` | `{ ok, command, data: { ... } }` |

package/skills/peaks-qa/references/qa-skill-presence.md

@@ -0,0 +1,22 @@
+# Skill presence (QA)
+
+> Body of `## Skill presence (MANDATORY first action — main-loop context only)`. When this skill is running in the main Claude session (not as a sub-agent), before any analysis or tool call, immediately run:
+
+```bash
+peaks skill presence:set peaks-qa --project <repo> --mode <mode> --gate startup
+```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
+Read persistent project memory via CLI (durable, LLM-authored memories):
+
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Cli Skill: peaks-qa | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-qa --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.

package/skills/peaks-qa/references/qa-standards-preflight.md

@@ -0,0 +1,8 @@
+# Project standards preflight (QA)
+
+> Body of `## Project standards preflight`. Before QA verification in a code repository, call the Peaks-Cli CLI:
+
+- `peaks standards init --project <path> --dry-run`
+- `peaks standards update --project <path> --dry-run`
+
+If the repo needs a first-time standards bundle, treat `standards init` as the creation path. If `CLAUDE.md` already exists, use `standards update` to decide whether Peaks-Cli can append a managed block or should only return review suggestions. Apply only when write authorization exists; otherwise keep the CLI output as a preflight next action. Do not hand-write standards file mutations inside the skill.

package/skills/peaks-qa/references/qa-sub-agent-dispatch.md

@@ -0,0 +1,46 @@
+# Sub-agent dispatch (QA)
+
+> Body of `## Sub-agent dispatch`. When this skill is launched as a sub-agent via `peaks sub-agent dispatch <role>` (then the LLM executes the returned toolCall) from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
+
+- **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
+- **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-qa`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Solo loop owns that file. If you need to mark your own state, write a marker file at `.peaks/_runtime/<sessionId>/system/sub-agent-qa.json` and only that.
+- **Workspace initialization** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
+- **Mode selection** — Solo has already chosen the mode.
+- **Statusline install** — already done by Solo at session startup.
+
+What the sub-agent **MUST** still do:
+
+0. **Do NOT call `peaks request init`** — Solo has already initialised the request artefact slot in the main loop before fan-out. The sub-agent reads it via `peaks request show <rid> --role qa --project <repo> --json` if it needs to.
+2. `peaks request show <rid> --role prd --project <repo> --json` (and `--role rd`, `--role ui` if UI is in the swarm plan).
+3. Standards preflight (dry-run only).
+4. Write `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md` with test cases that link to PRD acceptance items.
+5. Return only a compact JSON envelope:
+
+```json
+{
+  "role": "qa-test-cases",
+  "rid": "<rid>",
+  "status": "ok" | "blocked" | "skipped",
+  "artefacts": [".peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md"],
+  "warnings": [],
+  "blockedReason": null
+}
+```
+
+**Hard prohibitions** (sub-agent context):
+
+- Do NOT call `Skill(skill="...")`.
+- Do NOT call `peaks skill presence:set` — Solo owns the active-skill file.
+- Do NOT run the actual test suite, do NOT execute security/perf tools, do NOT open a browser — those are the **QA validation** phase, not the Swarm planning phase.
+- Do NOT commit, push, install hooks, or apply settings.json mutations.
+- Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}`.
+
+If `--type` is `docs` or `chore`, return `{"status":"skipped","reason":"type=<type>"}` and exit — there is no acceptance surface to plan tests for.
+
+## Test Tool Detection (mandatory)
+
+The dispatch CLI (`peaks sub-agent dispatch`) automatically prepends a Test Tool Detection block to every sub-agent prompt — telling the sub-agent to read `package.json#scripts.test` first and use the project-local runner (`./node_modules/.bin/<runner>` or `pnpm test -- <file>`). NEVER use `npx <runner>`. This rule is machine-injected, not a prompt ritual — every sub-agent gets it including rd/qa/ui/txt/sc.
+
+If the framework is not obvious from `package.json#scripts.test`, the sub-agent should run `peaks test --json` to introspect the resolved framework + argv before picking a runner.
+
+See the block constant at `src/services/dispatch/test-tool-detection.ts` for the verbatim text.

package/skills/peaks-qa/references/qa-transition-gates.md

@@ -0,0 +1,86 @@
+# Transition verification gates (QA)
+
+> Body of `### Transition verification gates`. You cannot declare a phase complete from memory. Each gate below is a `ls` or `grep` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file" or any command returns empty, the phase is incomplete.
+
+> **CLI enforcement (v2.11.0 D1/D4 trim)**: the gates below are enforced by `peaks request transition`. The CLI checks the same files before allowing the transition and fails with `code: PREREQUISITES_MISSING` if any are absent. Required files depend on the request type recorded at `peaks request init --type ...`. **As of v2.11.0:** peaks-qa does NOT own security-findings or performance-findings — those are produced by peaks-rd's audit fan-out as `rd/security-review.md` and `rd/perf-baseline.md` and are referenced from the QA test report rather than required as separate files.
+
+| Type | qa:running requires | qa:verdict-issued also requires |
+|---|---|---|
+| feature / refactor | `qa/test-cases/<rid>.md` | `qa/test-reports/<rid>.md` |
+| bugfix | `qa/test-cases/<rid>.md` (MUST include the regression test) | `qa/test-reports/<rid>.md` |
+| config | (none) | `qa/test-reports/<rid>.md` |
+| docs / chore | (none) | (none) |
+
+Security and performance evidence surface under `rd/security-review.md` and `rd/perf-baseline.md` (peaks-rd's audit fan-out) and are referenced by reference from the QA test report body. The pre-v2.11.0 `qa/security-findings.md` / `qa/performance-findings.md` files are no longer required; existing ones are kept for auditability but ignored by the gate.
+
+**Peaks-Cli Gate A — After test-case generation:**
+```bash
+ls .peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md
+# Expected: .peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md
+# "No such file" → STOP, generate test cases first.
+```
+
+**Peaks-Cli Gate A2 — After test execution: tests actually ran (CRITICAL):**
+```bash
+npx vitest run --changed --reporter=verbose 2>&1 | tail -30
+# Expected: exit code 0, actual test output
+# "0 tests executed" or "no test files found" → BLOCKED.
+```
+
+**Peaks-Cli Gate A3 — Security review referenced (v2.11.0 D1/D4: read-only reference, NOT a separate QA file):**
+```bash
+# peaks-qa does NOT own a qa/security-findings.md. peaks-rd's audit fan-out
+# produces rd/security-review.md; QA references it by path in the test report body.
+grep -E "rd/security-review\\.md|security-review" .peaks/_runtime/<sessionId>/qa/test-reports/<rid>.md 2>&1
+# Expected: at least one reference to the rd-side security review.
+# Empty → BLOCKED: the test report must cite where security evidence lives.
+```
+
+**Peaks-Cli Gate A4 — Performance baseline referenced (v2.11.0 D1/D4: read-only reference, NOT a separate QA file):**
+```bash
+# peaks-qa does NOT own a qa/performance-findings.md. peaks-rd's audit fan-out
+# produces rd/perf-baseline.md; QA references it by path in the test report body.
+grep -E "rd/perf-baseline\\.md|perf-baseline" .peaks/_runtime/<sessionId>/qa/test-reports/<rid>.md 2>&1
+# Expected: at least one reference to the rd-side perf baseline.
+# Empty → BLOCKED: the test report must cite where perf evidence lives.
+```
+
+**Peaks-Cli Gate B — After test-report write (MUST contain execution results):**
+```bash
+ls .peaks/_runtime/<sessionId>/qa/test-reports/<rid>.md
+grep -c "pass\|fail\|blocked" .peaks/_runtime/<sessionId>/qa/test-reports/<rid>.md
+# Zero → the report is empty/template-only. Tests were not executed.
+```
+
+**Peaks-Cli Gate C — Before issuing verdict:**
+```bash
+ls .peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md \
+   .peaks/_runtime/<sessionId>/qa/test-reports/<rid>.md \
+   .peaks/_runtime/<sessionId>/qa/requests/<rid>.md
+# All three must exist. Missing any → QA incomplete, verdict blocked.
+# Security + perf evidence live under rd/ (peaks-rd's audit fan-out);
+# QA cites them by reference from the test-report body (see Gates A3/A4).
+```
+
+**Peaks-Cli Gate E — Acceptance coverage:**
+```bash
+peaks scan acceptance-coverage --rid <rid> --project <repo> --session-id <session-id> --json
+# Expected: ok=true. exit 0.
+# uncovered[] non-empty → BLOCKED. Add `- **Acceptance:** A<N>` lines to test cases.
+# invalidReferences[] non-empty → BLOCKED.
+```
+
+**Peaks-Cli Gate F — QA artifact body has no unfilled placeholders:**
+```bash
+peaks request lint <rid> --role qa --project <repo> --session-id <session-id> --json
+# Expected: ok=true. exit 0.
+```
+
+**Peaks-Cli Gate D — Frontend browser evidence (BLOCKING when frontend is in scope):**
+```bash
+ls .peaks/_runtime/<sessionId>/qa/screenshots/*.png 2>&1
+# Expected: one or more .png files
+# "No such file" → BLOCKED.
+grep -c "browser_console_messages\|browser_network_requests" .peaks/_runtime/<sessionId>/qa/test-reports/<rid>.md
+# Expected: non-zero count
+```

package/skills/peaks-qa/references/reading-handoff-frontmatter.md

@@ -0,0 +1,30 @@
+# Reading handoff frontmatter (peaks-rd → peaks-qa)
+
+QA reads the RD handoff's YAML frontmatter **before** reading the body prose. The frontmatter is the mechanical contract; the body is narrative. Cross-check fields mechanically; flag mismatches as Gate C failures.
+
+## Required frontmatter fields (mirror RD writer)
+
+`requestId`, `scope`, `files`, `decisions[]`, `risks[]`, `nextActions[]`, `gateEvidence`, `schemaVersion: '1.0'`. Field schema: `../peaks-rd/references/writing-handoff-frontmatter.md`.
+
+## Mechanical cross-checks (run before body read)
+
+1. **Decisions ↔ tests** — every `decisions[].id` (e.g. `D1`) implies a test under `tests/unit/`. Grep `tests/unit/` for the decision id (or its summary keywords). Missing test → Gate B2 partial.
+2. **Risks ↔ security tests** — every `risks[].id` with `description` mentioning auth / input / boundary / path / external / crypto / payment MUST have a matching case under `tests/unit/security/`. Missing → Gate A3 partial.
+3. **Files ↔ diff** — `files[]` must equal `git diff --name-only` against the parent commit. Any file in the diff not in `files[]` (or vice versa) → Gate B8 fail (out-of-scope or missing scope).
+4. **`gateEvidence` ↔ on-disk** — every path in `gateEvidence` MUST `ls` successfully. Missing → Gate C fail (the gate table is enforced by `peaks request transition`).
+5. **`nextActions` ↔ this skill** — first `nextActions[]` entry should match what peaks-qa is about to do. Mismatch (e.g. "RD to fix" still queued) → loop back to RD, do not run QA.
+
+## Test plan derivation (body prose)
+
+After the frontmatter passes, read the body prose to derive the test plan:
+
+- Walk `## Red-line scope` to know what NOT to test.
+- Walk the implementation narrative for new code paths → one test case per path.
+- Cross-link each test case back to a PRD acceptance ID via `**Acceptance:**`.
+- Honor `nextActions[]` ordering.
+
+## Verifiable success
+
+- All 5 mechanical cross-checks above pass (or are explicitly waived via `--allow-incomplete --confirm`).
+- Test plan covers every new code path mentioned in body prose.
+- Frontmatter YAML parses cleanly (vitest guard: `tests/unit/artifacts/handoff-frontmatter-shape.test.ts`).

package/skills/peaks-qa/references/regression-gates.md

@@ -0,0 +1,24 @@
+# Peaks QA Regression Gates
+
+QA must be involved before refactor implementation.
+
+## Required evidence
+
+- coverage report or reason for blocking;
+- regression matrix;
+- baseline report;
+- acceptance checks;
+- API validation evidence when API behavior is in scope;
+- Playwright MCP browser E2E evidence when a frontend exists or UI is in scope (the LLM checks its tool list for `mcp__playwright__*`; if absent, the user installs via `claude mcp add playwright -- npx @playwright/mcp@latest` for Claude Code, or the IDE-native install command otherwise — peaks-cli no longer auto-installs as of slice #016; capture with `browser_snapshot`, `browser_take_screenshot`, `browser_console_messages`, `browser_network_requests`), with mandatory visible-browser confirmation;
+- security check evidence;
+- performance check evidence;
+- validation report;
+- residual risk report.
+
+## Refactor threshold
+
+UT coverage below 95%, missing coverage, or unverifiable coverage blocks refactor implementation. For non-refactor work in legacy projects whose total coverage is already below the project target, QA may accept the legacy baseline only when new or changed code has focused unit-test coverage evidence.
+
+## Frontend failure rule
+
+If browser validation shows page errors, console exceptions, failed critical network requests, or visible regressions, QA returns the change to RD with evidence and reruns the browser path after the fix.

package/skills/peaks-qa/references/requirement-boundary-recheck.md

@@ -0,0 +1,9 @@
+# Requirement boundary recheck (QA)
+
+> Body of `## Requirement boundary recheck`. Before QA passes or returns work to RD, it must independently recheck the implementation against the approved requirement boundary:
+
+1. compare the PRD/RD scope artifact, OpenSpec tasks, and current diff to identify every changed file, route, API path, mock handler, data fixture, and user-visible behavior;
+2. strictly fail QA if the change modifies, deletes, mocks, or replaces content outside the approved boundary, including unrelated list/query endpoints, existing records, delete/update flows, auth, permissions, shared configuration, or request plumbing;
+3. API and mock validation must exercise only the approved request paths unless the spec explicitly includes broader API coverage. Do not create, update, delete, or overwrite unrelated server/client state during QA;
+4. browser E2E must avoid destructive interactions unless the requirement explicitly includes them and the user confirms the action;
+5. record a "red-line boundary check" section in the validation report with pass/fail, evidence, and any out-of-scope findings.

package/skills/peaks-qa/references/test-case-generation.md

@@ -0,0 +1,27 @@
+# Mandatory test-case generation (QA)
+
+> Body of `## Mandatory test-case generation` + `## Test Case: <title>` template. QA must generate test cases, not merely inspect existing ones. Every QA invocation that validates code changes must produce a test-case artifact at `.peaks/_runtime/<sessionId>/qa/test-cases/<request-id>.md`.
+
+**Minimum test-case categories:**
+
+1. **Unit test cases** — verify that RD's unit tests cover: happy path, edge cases (null/undefined/empty), error states, boundary values, and async behavior for each changed function/component/hook
+2. **Integration test cases** — API contract verification, data flow through changed components, mock alignment with real API shapes
+3. **UI regression test cases** (frontend only) — page load, component render states (loading, empty, error, populated), modal open/close, form submit/validation, table sort/filter/pagination, navigation flow, keyboard accessibility
+
+**Test-case format:**
+
+```markdown
+## Test Case: <title>
+- **Category:** unit | integration | ui-regression
+- **Target:** <file-or-route>
+- **Acceptance:** A1, A2  (comma-separated IDs from PRD `## Acceptance criteria`; see "Acceptance linkage" below)
+- **Preconditions:** <state-before>
+- **Steps:** 1. ... 2. ...
+- **Expected result:** <what-should-happen>
+- **Status:** pass | fail | blocked | skipped
+- **Evidence:** <link-or-observation>
+```
+
+**Acceptance linkage (MANDATORY)** — every test case MUST have an `**Acceptance:**` field that references one or more acceptance items from the PRD by their position-based IDs (A1 = first bullet, A2 = second, …). The `peaks scan acceptance-coverage --rid <rid> --project <repo>` command parses both the PRD and this file, builds the coverage map, and fails the QA `verdict-issued` gate if any acceptance item has zero linked test cases. Test cases that genuinely have no acceptance owner (e.g. defense-in-depth regressions) should still include `- **Acceptance:** —` and explain in the **Evidence** field; the coverage report flags these as `unlinkedTestCases` for review without auto-blocking.
+
+**Test-case execution**: Run the project's test command and record results against each generated test case. If the project uses Jest, run `npx jest --coverage` and link the coverage report. If the project uses Vitest, run `npx vitest run --changed --coverage` by default; use the full suite `npx vitest run --coverage` only when the slice warrants a deeper regression check. Record the coverage percentage for changed files in the test report.

package/skills/peaks-qa/references/test-report-output.md

@@ -0,0 +1,14 @@
+# Mandatory test-report output (QA)
+
+> Body of `## Mandatory test-report output`. Every QA invocation must produce a test-report artifact at `.peaks/_runtime/<sessionId>/qa/test-reports/<request-id>.md`. This is separate from both the test-case file and the request artifact — do not merge.
+
+**Minimum test-report sections:**
+
+1. **Summary** — pass/fail count, coverage %, verdict (pass / return-to-rd / blocked)
+2. **Test execution results** — number of test cases executed, passed, failed, skipped
+3. **Coverage evidence** — changed-files coverage %, overall project coverage %, link to coverage report
+4. **Browser validation results** (frontend only) — pages validated, screenshots path, console errors found, network errors found
+5. **Security findings** — issues found, severity, resolution status
+6. **Performance findings** — baseline vs after numbers (build size, Lighthouse, etc. as applicable)
+7. **Residual risks** — known issues not fixed, why, mitigation
+8. **Red-line boundary check** — pass/fail against the approved scope