peaks-cli 1.0.17 → 1.0.19

package/skills/peaks-qa/SKILL.md

@@ -85,6 +85,16 @@ peaks openspec validate <change-id> --project <repo> --prefer-external --json
 peaks mcp list --json
 peaks mcp plan  --capability playwright-mcp.browser-validation --json
 peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
+# DEV-SERVER REQUIREMENT (BLOCKING): a running dev server is REQUIRED for browser E2E.
+# Start the dev server (npm run dev / pnpm dev / umi dev / etc) and capture the actual
+# advertised URL from its stdout (do NOT hard-code localhost:8000). If the dev server
+# fails to start, hangs, or times out (e.g. tailwindcss/plugin slowness, port conflict,
+# missing env), this is a BLOCKER — NOT a reason to skip browser E2E. You MUST:
+#   1. Record the failure and root cause in qa/test-reports/<rid>.md;
+#   2. Return verdict=blocked (or return-to-rd if the root cause is implementation-related);
+#   3. NEVER substitute a production build (`umi build` / `vite build` / `next build`) for
+#      browser E2E. A successful production build proves compilation, not runtime behavior,
+#      and does NOT satisfy Gate D. Treating prod build as a fallback is a workflow violation.
 # Playwright MCP MUST simulate real user operations — not just take static screenshots.
 # The minimum interaction sequence for every frontend page/flow:
 #   mcp__playwright__browser_navigate         → URL (after allow-list), launches headed browser
@@ -102,6 +112,12 @@ peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
 
 # 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 Gate E/F):
+peaks scan acceptance-coverage --rid <rid> --project <repo> --json
+# → ok=false → BLOCKED. Some PRD acceptance items have no linked test case
+#               (or some test cases reference non-existent acceptance ids). Fix the test-cases file.
+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
@@ -115,6 +131,17 @@ Verdict `pass` is blocked until every applicable validation gate has evidence in
 
 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 (NEW)**: the gates below are now ALSO 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 ...`:
+>
+> | Type | qa:running requires | qa:verdict-issued also requires |
+> |---|---|---|
+> | feature / refactor | `qa/test-cases/<rid>.md` | `qa/test-reports/<rid>.md` + `qa/security-findings.md` + `qa/performance-findings.md` |
+> | bugfix | `qa/test-cases/<rid>.md` (MUST include the regression test) | `qa/test-reports/<rid>.md` + `qa/security-findings.md` (perf optional unless the bug is performance-related) |
+> | config | (none) | `qa/security-findings.md` only |
+> | docs / chore | (none) | (none) |
+>
+> For feature / refactor, `security-findings.md` and `performance-findings.md` MUST exist — record `"no findings"` inside if truly clean rather than skipping the file. The escape hatch `--allow-incomplete --reason "<justification>"` is recorded in the artifact transition note.
+
 **Gate A — After test-case generation:**
 ```bash
 ls .peaks/<id>/qa/test-cases/<rid>.md
@@ -176,6 +203,26 @@ ls .peaks/<id>/qa/test-cases/<rid>.md \
 # An empty "N/A — skipped" file does NOT pass. Every file must contain findings.
 ```
 
+**Gate E — Acceptance coverage (every PRD acceptance item has a linked test case):**
+```bash
+peaks scan acceptance-coverage --rid <rid> --project <repo> --session-id <sid> --json
+# Expected: ok=true. exit 0.
+# uncovered[] non-empty → BLOCKED. List of acceptance items without test cases is in the output.
+#   Add `- **Acceptance:** A<N>` lines to the matching test cases in qa/test-cases/<rid>.md, then re-run.
+# invalidReferences[] non-empty → BLOCKED. A test case references an acceptance id that does not exist.
+#   Fix the typo or remove the reference.
+# unlinkedTestCases[] non-empty → WARNING (not blocking). These test cases have no Acceptance: field;
+#   either link them or add `- **Acceptance:** —` with rationale in the Evidence field.
+```
+
+**Gate F — QA artifact body has no unfilled placeholders:**
+```bash
+peaks request lint <rid> --role qa --project <repo> --session-id <sid> --json
+# Expected: ok=true. exit 0.
+# ok=false → BLOCKED. Lint output lists every <placeholder>, "- ..." stub, and TBD marker.
+#   Fill them in before issuing the verdict.
+```
+
 **Gate D — Frontend browser evidence (BLOCKING when frontend is in scope):**
 ```bash
 # Verify browser screenshots exist. Screenshots are the only acceptable evidence
@@ -184,6 +231,10 @@ ls .peaks/<id>/qa/screenshots/*.png 2>&1
 # Expected: one or more .png files
 # "No such file" → BLOCKED. Playwright MCP was not used or screenshots not saved.
 # Screenshots, logs, manual steps, or other tools must NOT substitute for this gate.
+# A successful production build (`umi build` / `vite build` / `next build` exit 0) does
+# NOT substitute for this gate. Compilation success ≠ runtime behavior.
+# If the dev server cannot start, verdict MUST be `blocked` (or `return-to-rd`),
+# NOT `pass`. Record the dev-server failure root cause in the test report.
 # Re-run frontend browser validation (step 7 in runbook) and save screenshots.
 ```
 ```bash
@@ -240,6 +291,7 @@ QA must generate test cases, not merely inspect existing ones. Every QA invocati
 ## 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>
@@ -247,6 +299,8 @@ QA must generate test cases, not merely inspect existing ones. Every QA invocati
 - **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 --coverage`. Record the coverage percentage for changed files in the test report.
 
 ## Mandatory test-report output
@@ -277,6 +331,8 @@ QA cannot pass a change until the report contains evidence for every applicable
 6. **Security check** — run security review for the changed surface and dependency/config changes. Record findings, fixes, and unresolved risks.
 7. **Performance check** — run the project’s available performance check, build-size check, Lighthouse-equivalent check, or browser performance inspection appropriate to the change. Record baseline/after numbers when available.
 8. **Validation report** — write or link a report containing scope, environment, commands, sanitized browser evidence, security/performance results, pass/fail summary, residual risks, and next action.
+9. **Acceptance coverage** — every PRD acceptance item has at least one linked QA test case (`peaks scan acceptance-coverage --rid <rid>`). **→ verified by Gate E**. This is the deterministic check that no requirement was forgotten between PRD and verdict.
+10. **QA artifact lint** — the QA request artifact body has no unfilled placeholders (`peaks request lint <rid> --role qa`). **→ verified by Gate F**. Catches the "wrote the template, forgot to fill it" failure mode that template-style reports invite.
 
 If Playwright MCP is unavailable (not installed and the user has not authorized installation), mark the gate blocked with the missing capability. Screenshots, logs, manual steps, or other tools must not substitute for the mandatory frontend browser gate. Do not silently downgrade frontend validation to API-only testing.
 

package/skills/peaks-rd/SKILL.md

@@ -119,6 +119,15 @@ peaks mcp call --capability context7.docs-lookup --tool <name> --args-json '{...
 #    Gate B2: unit tests exist and pass → npx vitest run (or project equivalent)
 #    Gate B3: code review evidence → .peaks/<id>/rd/code-review.md
 #    Gate B4: security review evidence → .peaks/<id>/rd/security-review.md
+#    Gate B5 (NEW): RD artifact body has no unfilled placeholders.
+peaks request lint <rid> --role rd --project <repo> --session-id <sid> --json
+#    Gate B6 (NEW): declared --type still matches the actual diff after implementation.
+peaks scan request-type-sanity --project <repo> --type <type> --json
+#    Gate B7 (NEW, repair cycles only): we have not exceeded the 3-cycle cap.
+peaks request repair-status <rid> --project <repo> --session-id <sid> --json
+#    Gate B8 (NEW): every changed file matches the RD red-line scope (no out-of-bounds writes).
+peaks scan diff-vs-scope --rid <rid> --project <repo> --session-id <sid> --json
+#    All six non-zero → BLOCKED. Fix and re-check before attempting the qa-handoff transition.
 
 # 7. self-validate before QA handoff
 peaks openspec validate <change-id> --project <repo> --json    # exit gate (re-run)
@@ -135,6 +144,17 @@ For refactor work, the coverage ≥ 95% gate in `Refactor hard gates` still appl
 
 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 (NEW)**: the gates below are now ALSO 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. The exact required files depend on the request type chosen at `peaks request init --type <feature|bugfix|refactor|docs|config|chore>` (default `feature`):
+>
+> | Type | rd:implemented requires | rd:qa-handoff also requires |
+> |---|---|---|
+> | feature / refactor | `rd/tech-doc.md` | `rd/code-review.md` + `rd/security-review.md` |
+> | bugfix | `rd/bug-analysis.md` (lighter than tech-doc; root cause + fix + regression test plan) | `rd/code-review.md` + `rd/security-review.md` |
+> | config | (none) | `rd/security-review.md` only |
+> | docs / chore | (none) | (none) |
+>
+> The escape hatch `--allow-incomplete --reason "<text>"` still exists for one-off exceptions; the bypass is recorded in the artifact transition note.
+
 **Gate A — After project-scan read (before any implementation):**
 ```bash
 ls .peaks/<id>/rd/project-scan.md
@@ -195,6 +215,45 @@ ls .peaks/<id>/rd/security-review.md 2>&1
 # fix CRITICAL/HIGH issues, record findings, then re-check.
 ```
 
+**Gate B5 — RD artifact body has no unfilled placeholders:**
+```bash
+peaks request lint <rid> --role rd --project <repo> --session-id <sid> --json
+# Expected: ok=true. exit 0.
+# ok=false → BLOCKED. The lint output lists every <placeholder>, "- ..." stub,
+# and TBD/TODO marker with line numbers. Fill them in before attempting handoff.
+```
+
+**Gate B6 — Declared --type matches the actual diff:**
+```bash
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# Expected: consistent=true. exit 0.
+# consistent=false → BLOCKED. Either the implementation scope-creeped beyond what
+# the declared type covers, or the type was mis-classified at PRD time. Re-classify
+# (`peaks request init` with the corrected --type) or trim the scope.
+```
+
+**Gate B7 — Repair cycle cap (only relevant during RD↔QA repair loop):**
+```bash
+peaks request repair-status <rid> --project <repo> --session-id <sid> --json
+# Expected: atCap=false. exit 0.
+# atCap=true → BLOCKED. Three repair cycles already attempted; emit a blocked TXT
+# handoff via Solo rather than entering a fourth cycle.
+```
+
+**Gate B8 — Diff stays inside the declared red-line scope:**
+```bash
+peaks scan diff-vs-scope --rid <rid> --project <repo> --session-id <sid> --json
+# Expected: ok=true. exit 0.
+# violations[] non-empty → BLOCKED. A changed file matches an explicit out-of-scope
+#   pattern. Revert it, or — only with PRD approval — expand the RD red-line scope.
+# unclassified[] non-empty → BLOCKED. A changed file does not match any declared
+#   in-scope pattern. Either add it to the in-scope list (intentional widening, requires
+#   PRD approval) or revert the change.
+# patternsDeclared=false → BLOCKED. The RD artifact's `## Red-line scope` section has
+#   no concrete path or glob patterns. Fill it in with paths like `src/services/login/**`
+#   before re-running. Auto-allowed paths (test files, .peaks/, __mocks__/) never need a pattern.
+```
+
 ## Project standards preflight
 
 Before RD planning or implementation work in a code repository, call the Peaks CLI:
@@ -225,11 +284,11 @@ When Peaks RD produces or changes code, dry-run repeatedly instead of only durin
 
 Before every code or mock change, RD must write and then enforce a red-line scope check in the RD artifact:
 
-1. name the exact product requirement, route, UI surface, API path, data model, and files that are in scope;
+1. name the exact product requirement, route, UI surface, API path, data model, and **path/glob patterns** that are in scope. Write them under the RD artifact's `## Red-line scope` section as bullets. Use `In-scope:` / `Out-of-scope:` subheaders when both lists are non-trivial, or wrap paths in backticks for clarity (e.g. `` `src/services/login/**` ``);
 2. name adjacent surfaces that are explicitly out of scope, especially list pages, delete/update flows, unrelated API endpoints, existing data records, authentication, permissions, and shared runtime configuration;
 3. reject any implementation that modifies, deletes, mocks, or replaces out-of-scope behavior just to make validation pass;
 4. for API/mock work, mock only the exact request path and method required by the approved slice, and do not override broader collection/list endpoints unless the requirement explicitly includes them;
-5. before handoff, inspect the diff against the red-line checklist and record pass/fail evidence. Any unexplained out-of-scope file, endpoint, deletion, or behavior change blocks RD completion.
+5. before handoff, run `peaks scan diff-vs-scope --rid <rid> --project <repo>` to deterministically verify the diff against the declared patterns (this is **Gate B8**). The CLI auto-allows test files and `.peaks/` artifacts; any other unclassified or out-of-scope file blocks RD completion until the diff is trimmed OR the scope is widened with PRD approval.
 
 ## Mandatory tech-doc output
 
@@ -265,6 +324,10 @@ RD cannot mark a development slice complete until all of these are true. Each ga
 6. security review has been performed for the changed surface, with CRITICAL/HIGH issues fixed before progression and particular attention to user input, file system access, external calls, auth, secrets, and dependency changes; **→ verified by Gate B4** — evidence file must exist at `.peaks/<id>/rd/security-review.md`
 7. the post-check dry-run has passed and is linked in the handoff;
 8. the tech-doc artifact (`.peaks/<session-id>/rd/tech-doc.md`) is written and linked from the request artifact. **→ verified by Gate B**
+9. the RD request artifact body has no unfilled placeholders, TBD markers, or bare-bullet stubs (`peaks request lint <rid> --role rd`). **→ verified by Gate B5**
+10. the declared `--type` is still consistent with the actual git diff (`peaks scan request-type-sanity --type <type>`). **→ verified by Gate B6**
+11. the repair-cycle counter is below the cap before a repeat handoff (`peaks request repair-status <rid>`). **→ verified by Gate B7**
+12. every changed file matches the RD red-line scope (no out-of-bounds writes); auto-allowed files (tests, .peaks artifacts) don't need an explicit pattern (`peaks scan diff-vs-scope --rid <rid>`). **→ verified by Gate B8**
 
 If any gate fails, return to development for fixes or hand off as blocked. Do not describe the work as done, shippable, or ready for QA.