peaks-cli 1.0.14 → 1.0.16

package/skills/peaks-prd/SKILL.md

@@ -7,6 +7,16 @@ description: Product and requirement skill for Peaks. Use when a workflow needs
 
 Peaks PRD turns user intent into verifiable product artifacts.
 
+## Skill presence (MANDATORY first action)
+
+Before any analysis or tool call, immediately run:
+
+```bash
+peaks skill presence:set peaks-prd --mode <mode> --gate startup
+```
+
+Then display: `Peaks Skill: peaks-prd | Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-prd --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear`.
+
 ## Responsibilities
 
 - clarify goals and non-goals;
@@ -23,6 +33,16 @@ Every PRD invocation — feature, bug, refactor, clarification — must write a
 
 Use `<request-id>` of the form `YYYY-MM-DD-<kebab-slug>` (or whatever id the user assigned) so PRD/UI/RD/QA/SC can cross-link the same request.
 
+**Minimum PRD artifact sections:**
+
+1. **Goals** — what this request must achieve, in verifiable terms
+2. **Non-goals** — explicitly out of scope for this request
+3. **Preserved behavior** — existing behavior that must not change
+4. **Acceptance criteria** — per-criterion pass/fail conditions QA can execute
+5. **Frontend delta** (when applicable) — pages, routes, components, states affected
+6. **Unresolved questions** — items blocking implementation or QA
+7. **User confirmation record** — date, method (explicit confirm / auto-confirm), scope confirmed
+
 Concrete template and rules: `references/artifact-per-request.md`.
 
 ## Default runbook
@@ -69,6 +89,24 @@ peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
 
 Handoff is blocked until the request artifact's `state` reaches `confirmed-by-user` or `handed-off`. Update the state field in the artifact body before invoking RD/UI/QA.
 
+### Transition verification gates (MANDATORY — run the command, see the output)
+
+You cannot declare PRD complete from memory. Each gate below is a `ls` command you **MUST run** and whose output you **MUST see** before proceeding.
+
+**Gate A — After PRD artifact write (before handoff to RD/UI/QA):**
+```bash
+ls .peaks/<id>/prd/requests/<rid>.md
+# Expected output: .peaks/<id>/prd/requests/<rid>.md
+# "No such file" → STOP, write the PRD artifact first. Do not hand off.
+```
+
+**Gate B — Before clearing PRD presence (verify user confirmation):**
+```bash
+grep -E "state:.*(confirmed-by-user|handed-off)" .peaks/<id>/prd/requests/<rid>.md
+# Expected: a line containing state: confirmed-by-user or state: handed-off
+# No match → STOP, the PRD has not been confirmed. Ask the user to confirm.
+```
+
 ## Refactor role
 
 For refactor workflows, avoid writing a full product PRD unless needed. Produce a focused refactor product package:
@@ -144,7 +182,24 @@ Inspect upstream skill content before applying any method. Treat examples and in
 
 ## Local intermediate artifacts
 
-PRD artifacts should be written to the workflow-local `.peaks/<session-id>/prd/` workspace by default, unless the active Peaks CLI profile supplies a different local artifact workspace. This workspace is the handoff surface between `peaks-prd`, `peaks-rd`, `peaks-qa`, `peaks-ui`, `peaks-sc`, and `peaks-txt`.
+PRD artifacts must be written to the workflow-local `.peaks/<session-id>/prd/` workspace by default, unless the active Peaks CLI profile supplies a different local artifact workspace. This workspace is the handoff surface between `peaks-prd`, `peaks-rd`, `peaks-qa`, `peaks-ui`, `peaks-sc`, and `peaks-txt`.
+
+### Document snapshot placement (BLOCKING)
+
+**When PRD captures content from an external document (Feishu/Lark/wiki/web page), ALL intermediate snapshots MUST go into `.peaks/<session-id>/prd/source/` — NEVER to the project root directory.**
+
+Specifically:
+- `mcp__playwright__browser_snapshot` output → save to `.peaks/<session-id>/prd/source/<doc-name>-snapshot.md`
+- `mcp__playwright__browser_take_screenshot` output → save to `.peaks/<session-id>/prd/source/<doc-name>-screenshot.png`
+- Any exported `.md` or `.pdf` the user provides → save to `.peaks/<session-id>/prd/source/`
+
+**Prohibited paths** (BLOCKING — do not write to these):
+- `./feishu-doc-snapshot.md` (project root)
+- `./feishu-doc-snapshot-2.md` (project root)
+- `./<anything>-snapshot.md` (project root)
+- `./screenshots/` (project root — use `.peaks/<id>/qa/screenshots/`)
+
+The canonical PRD request artifact at `.peaks/<session-id>/prd/requests/<request-id>.md` should link to the source files in `prd/source/` for traceability.
 
 Do not default to a git-backed artifact repository or commit intermediate artifacts automatically. Git commits, artifact sync, or external repository storage require explicit user confirmation or an active profile that clearly authorizes them.
 

package/skills/peaks-qa/SKILL.md

@@ -7,6 +7,16 @@ description: QA and verification skill for Peaks. Use when a workflow needs unit
 
 Peaks QA proves that planned changes are protected and accepted.
 
+## Skill presence (MANDATORY first action)
+
+Before any analysis or tool call, immediately run:
+
+```bash
+peaks skill presence:set peaks-qa --mode <mode> --gate startup
+```
+
+Then display: `Peaks Skill: peaks-qa | Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-qa --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear`.
+
 ## Responsibilities
 
 - inspect unit-test coverage evidence;
@@ -20,9 +30,13 @@ Peaks QA proves that planned changes are protected and accepted.
 
 ## Mandatory per-request artifact
 
-Every QA invocation — feature, bug, refactor, clarification — must write a durable artifact at `.peaks/<session-id>/qa/requests/<request-id>.md`. This is the canonical verification record; the verdict in the artifact is authoritative over any chat conclusion. Solo's RD↔QA repair loop reads this artifact to decide whether to return work to RD or close the request.
+Every QA invocation — feature, bug, refactor, clarification — must write **three separate files**. Do not merge them into one. Each serves a different reader:
 
-Use the `<request-id>` PRD assigned, so PRD/UI/RD/QA/SC all reference the same request. QA companion artifacts (regression matrix, browser evidence directory, coverage report, security report, performance report) live alongside under the same `qa/` workspace and are linked from this file.
+| # | File | Path | Reader | Content |
+|---|------|------|--------|---------|
+| 1 | Test cases | `.peaks/<id>/qa/test-cases/<rid>.md` | RD (before impl), QA | Generated test scenarios with status |
+| 2 | Test report | `.peaks/<id>/qa/test-reports/<rid>.md` | QA, SC, Solo | Summary, coverage%, security, perf, risks |
+| 3 | Request artifact | `.peaks/<id>/qa/requests/<rid>.md` | Solo, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
 
 Concrete template and rules: `references/artifact-per-request.md`.
 
@@ -50,24 +64,46 @@ peaks codegraph affected --project <repo> <changed-files...> --json   # regressi
 peaks openspec validate <change-id> --project <repo> --json
 peaks openspec validate <change-id> --project <repo> --prefer-external --json   # optional
 
-# 4. unit tests + coverage (project test commands here, recorded in the artifact)
+# 4. generate test cases — MANDATORY, write to .peaks/<session-id>/qa/test-cases/<request-id>.md
+#    categories: unit, integration, UI regression (frontend only)
 
-# 5. frontend browser validation (when frontend is in scope)
+# 5. EXECUTE tests against the actual implementation — Gate A2
+#    Run the project test command. Record output. Tests on paper are worthless.
+#    Gate A3: Run security review → .peaks/<id>/qa/security-findings.md
+#    Gate A4: Run performance check → .peaks/<id>/qa/performance-findings.md
+#    CRITICAL: Gates A3 and A4 are NON-NEGOTIABLE. You MUST run actual security
+#    and performance checks — not just write a checklist item. These gates exist
+#    because code review alone does not catch: hardcoded secrets, XSS vectors,
+#    bundle size regressions, render-performance issues, or missing CSP headers.
+#    If you skip A3 or A4, Gate C will block the verdict.
+
+# 6. write test-report — MANDATORY, write to .peaks/<session-id>/qa/test-reports/<request-id>.md
+#    MUST contain actual execution results (pass/fail counts, coverage %, findings).
+#    A template with placeholder text does not pass Gate B.
+
+# 7. frontend browser validation (when frontend is in scope)
 peaks mcp list --json
 peaks mcp plan  --capability playwright-mcp.browser-validation --json
 peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
-# then drive the running app through Claude Code MCP tools:
+# 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
-#   mcp__playwright__browser_take_screenshot  → visible-browser confirmation
 #   mcp__playwright__browser_snapshot         → accessibility tree per regression seed
+#   mcp__playwright__browser_click            → click buttons, tabs, links, modals
+#   mcp__playwright__browser_type             → type into form fields, search inputs
+#   mcp__playwright__browser_select_option    → select dropdown values
+#   mcp__playwright__browser_fill_form        → fill complete forms as a user would
+#   mcp__playwright__browser_take_screenshot  → capture each state AFTER interaction
 #   mcp__playwright__browser_console_messages + browser_network_requests → error feedback loop
+#   mcp__playwright__browser_wait_for         → wait for async data to render
 #   mcp__playwright__browser_close            → end the session cleanly
+# Static screenshots without user-interaction simulation do NOT pass this gate.
 # Block QA pass if Playwright MCP is unavailable.
 
-# 6. write per-criterion acceptance results, regression matrix, security/performance findings,
+# 8. write per-criterion acceptance results, regression matrix, security/performance findings,
 #    and the final verdict into the QA request artifact. Mark state=verdict-issued.
 
-# 7. on verdict=return-to-rd, route findings back through the request id; otherwise close.
+# 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 skill presence:clear                      # QA complete, remove presence indicator
@@ -75,6 +111,88 @@ peaks skill presence:clear                      # QA complete, remove presence i
 
 Verdict `pass` is blocked until every applicable validation gate has evidence in the artifact.
 
+### Transition verification gates (MANDATORY — run the command, see the output)
+
+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.
+
+**Gate A — After test-case generation:**
+```bash
+ls .peaks/<id>/qa/test-cases/<rid>.md
+# Expected output: .peaks/<id>/qa/test-cases/<rid>.md
+# "No such file" → STOP, generate test cases first. Do not proceed to validation.
+```
+
+**Gate A2 — After test execution: tests actually ran and produced output (CRITICAL):**
+```bash
+# Run the project's test command. Do NOT skip this. Writing test cases is not enough.
+# Example (adapt to project):
+npx vitest run --reporter=verbose 2>&1 | tail -30
+# Expected: exit code 0, actual test output with pass/fail counts
+# "0 tests executed" or "no test files found" → BLOCKED. Tests were written but not run.
+# Record the raw test output and link it in the test report.
+```
+
+**Gate A3 — Security test executed (NOT just a checklist item):**
+```bash
+# Run security review against the changed surface. Record findings.
+ls .peaks/<id>/qa/security-findings.md 2>&1
+# Expected: .peaks/<id>/qa/security-findings.md
+# "No such file" → BLOCKED. Run security review against changed files,
+# record every finding with severity, then re-check.
+```
+
+**Gate A4 — Performance test executed:**
+```bash
+# Run available performance check against the changed surface. Record findings.
+ls .peaks/<id>/qa/performance-findings.md 2>&1
+# Expected: .peaks/<id>/qa/performance-findings.md
+# "No such file" → BLOCKED. Run performance check (build-size, Lighthouse,
+# bundle analysis, or project equivalent), record baseline vs. after, then re-check.
+```
+
+**Gate B — After test-report write (MUST contain execution results, not just planned cases):**
+```bash
+ls .peaks/<id>/qa/test-reports/<rid>.md
+# Expected output: .peaks/<id>/qa/test-reports/<rid>.md
+# "No such file" → STOP, write the test report first. Do not issue a verdict.
+# Additionally verify the report is not a placeholder:
+grep -c "pass\|fail\|blocked" .peaks/<id>/qa/test-reports/<rid>.md
+# Expected: non-zero count (report contains actual pass/fail/blocked results)
+# Zero → the report is empty/template-only. Tests were not executed.
+```
+
+**Gate C — Before issuing verdict:**
+```bash
+ls .peaks/<id>/qa/test-cases/<rid>.md \
+   .peaks/<id>/qa/test-reports/<rid>.md \
+   .peaks/<id>/qa/security-findings.md \
+   .peaks/<id>/qa/performance-findings.md \
+   .peaks/<id>/qa/requests/<rid>.md
+# All five must exist. Missing any → QA incomplete, verdict blocked.
+# NOTE: security-findings.md and performance-findings.md are NOT optional.
+# If you can't run a full security scan, run at minimum: grep for secrets,
+# check for XSS vectors, verify no hardcoded credentials.
+# If you can't run Lighthouse, run at minimum: build-size check, bundle analysis.
+# An empty "N/A — skipped" file does NOT pass. Every file must contain findings.
+```
+
+**Gate D — Frontend browser evidence (BLOCKING when frontend is in scope):**
+```bash
+# Verify browser screenshots exist. Screenshots are the only acceptable evidence
+# that Playwright MCP actually launched and interacted with the running app.
+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.
+# Re-run frontend browser validation (step 7 in runbook) and save screenshots.
+```
+```bash
+# Verify console and network checks were actually performed
+grep -c "browser_console_messages\|browser_network_requests" .peaks/<id>/qa/test-reports/<rid>.md
+# Expected: non-zero count (means console/network were checked)
+# Zero → BLOCKED. Browser error feedback loop was not executed.
+```
+
 ## Project standards preflight
 
 Before QA verification in a code repository, call the Peaks CLI:
@@ -106,17 +224,59 @@ Before QA passes or returns work to RD, it must independently recheck the implem
 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.
 
+## Mandatory test-case generation
+
+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/<session-id>/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>
+- **Preconditions:** <state-before>
+- **Steps:** 1. ... 2. ...
+- **Expected result:** <what-should-happen>
+- **Status:** pass | fail | blocked | skipped
+- **Evidence:** <link-or-observation>
+```
+
+**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
+
+Every QA invocation must produce a test-report artifact at `.peaks/<session-id>/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
+
 ## Mandatory validation gates
 
 QA cannot pass a change until the report contains evidence for every applicable gate:
 
-1. **Unit tests** — run the project test command or a focused test command that covers new/changed code. For legacy projects below the target coverage, require coverage for the new or changed code rather than failing on pre-existing uncovered code.
-2. **API validation** — when the change touches API contracts, data loading, request handling, auth, or integrations, exercise the relevant API path and record request/response evidence or a justified local substitute.
-3. **Frontend browser validation** — when the repository has a frontend or the change affects UI, launch the app and use Playwright MCP for real browser end-to-end validation. Confirm Playwright MCP is installed via `peaks mcp list --json`; install through `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` if missing. Open the page with `mcp__playwright__browser_navigate` (which launches a headed browser on demand), verify the visible window with `mcp__playwright__browser_take_screenshot`. If login, CAPTCHA, SSO, or MFA appears, the visible browser is already open; wait for the user to complete login and explicitly confirm completion before continuing. Capture sanitized route/actions, sanitized screenshots or observations, sanitized console (`browser_console_messages`) and network (`browser_network_requests`) failures, and acceptance result. Close with `mcp__playwright__browser_close` when done. (Chrome DevTools MCP is an optional secondary surface for CDP inspection of an already-running Chrome on `:9222`; it does NOT launch a browser.)
-4. **Browser-error feedback loop** — if Playwright MCP observation surfaces a page error, console exception, broken network request, hydration/render failure, or visible regression, return the work to RD/development with the exact evidence. Do not pass QA until the fixed build is retested in the browser.
-5. **Security check** — run security review for the changed surface and dependency/config changes. Record findings, fixes, and unresolved risks.
-6. **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.
-7. **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.
+0. **Test-case generation** — enforced by Gate A.
+1. **Test-report** — enforced by Gate B.
+2. **Unit tests** — run the project test command or a focused test command that covers new/changed code. For legacy projects below the target coverage, require coverage for the new or changed code rather than failing on pre-existing uncovered code.
+3. **API validation** — when the change touches API contracts, data loading, request handling, auth, or integrations, exercise the relevant API path and record request/response evidence or a justified local substitute.
+4. **Frontend browser validation** — when the repository has a frontend or the change affects UI, launch the app and use Playwright MCP for real browser end-to-end validation. This means **simulating real user operations**: clicking buttons, filling forms, selecting dropdowns, navigating between pages, waiting for async data to render, and verifying each resulting state. Static screenshots without interaction are insufficient. Confirm Playwright MCP is installed via `peaks mcp list --json`; install through `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` if missing. Use `mcp__playwright__browser_navigate` (launches headed browser), `mcp__playwright__browser_click` (simulate clicks on tabs/buttons/links), `mcp__playwright__browser_type` (type into inputs), `mcp__playwright__browser_select_option` (select dropdowns), `mcp__playwright__browser_fill_form` (fill complete forms), `mcp__playwright__browser_wait_for` (wait for async rendering), and `mcp__playwright__browser_take_screenshot` (capture state after each interaction). If login, CAPTCHA, SSO, or MFA appears, the visible browser is already open; wait for the user to complete login and explicitly confirm completion before continuing. Capture sanitized interaction sequences, sanitized screenshots per state, sanitized console (`browser_console_messages`) and network (`browser_network_requests`) failures. Close with `mcp__playwright__browser_close` when done. (Chrome DevTools MCP is an optional secondary surface for CDP inspection of an already-running Chrome on `:9222`; it does NOT launch a browser and cannot simulate user interaction.)
+5. **Browser-error feedback loop** — if Playwright MCP observation surfaces a page error, console exception, broken network request, hydration/render failure, or visible regression, return the work to RD/development with the exact evidence. Do not pass QA until the fixed build is retested in the browser.
+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.
 
 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.