peaks-cli 1.0.19 → 1.0.20

package/dist/src/services/artifacts/artifact-prerequisites.d.ts

@@ -8,6 +8,8 @@ export type ArtifactPrerequisite = {
     relativePath: string;
     /** Human-readable description of what this artifact represents. */
     description: string;
+    /** Optional content markers — when set, the file must contain ALL of these (case-insensitive substring). */
+    mustContain?: ReadonlyArray<string>;
 };
 export type PrerequisiteCheckResult = {
     ok: boolean;

package/dist/src/services/artifacts/artifact-prerequisites.js

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
 import { pathExists } from '../../shared/fs.js';
 export const VALID_REQUEST_TYPES = [
     'feature',
@@ -21,7 +22,16 @@ const TEST_CASES = { relativePath: 'qa/test-cases/<rid>.md', description: 'Gener
 const TEST_REPORT = { relativePath: 'qa/test-reports/<rid>.md', description: 'Test execution report with actual pass/fail/coverage results' };
 const SECURITY_FINDINGS = { relativePath: 'qa/security-findings.md', description: 'Security test findings (record "no findings" inside if truly clean)' };
 const PERFORMANCE_FINDINGS = { relativePath: 'qa/performance-findings.md', description: 'Performance test findings (record baseline/after numbers or explicit "not applicable" rationale)' };
+// PRD content prereq: ensures the PRD artifact has actual scope/acceptance content
+// before handoff to RD/UI/QA. The SKILL says "Handoff to RD/UI/QA is blocked while
+// the artifact is missing or in `draft` state" — this gives that claim a CLI gate.
+const PRD_CONTENT = {
+    relativePath: 'prd/requests/<rid>.md',
+    description: 'PRD artifact must contain Goal and Acceptance criteria sections before handoff',
+    mustContain: ['## Goals', '## Acceptance']
+};
 const FEATURE_TABLE = {
+    'prd:handed-off': [PRD_CONTENT],
     'rd:implemented': [TECH_DOC],
     'rd:qa-handoff': [TECH_DOC, CODE_REVIEW, SECURITY_REVIEW],
     'qa:running': [TEST_CASES],
@@ -30,6 +40,7 @@ const FEATURE_TABLE = {
 // Bugfix: lighter planning artifact (bug-analysis instead of tech-doc), still requires code review + security review + regression test.
 // Performance findings not mandatory for non-perf bugs (use --allow-incomplete --reason if a perf bug requires it).
 const BUGFIX_TABLE = {
+    'prd:handed-off': [PRD_CONTENT],
     'rd:implemented': [BUG_ANALYSIS],
     'rd:qa-handoff': [BUG_ANALYSIS, CODE_REVIEW, SECURITY_REVIEW],
     'qa:running': [TEST_CASES],
@@ -41,6 +52,7 @@ const REFACTOR_TABLE = FEATURE_TABLE;
 const NO_GATES = {};
 // Config: security review is the only mandatory check (config changes can break auth, CORS, CSP, secrets handling).
 const CONFIG_TABLE = {
+    'prd:handed-off': [PRD_CONTENT],
     'rd:qa-handoff': [SECURITY_REVIEW],
     'qa:verdict-issued': [SECURITY_FINDINGS]
 };
@@ -71,6 +83,18 @@ export async function checkPrerequisites(options) {
         const absolute = join(sessionRoot, relative);
         if (!(await pathExists(absolute))) {
             missing.push({ path: relative, description: prerequisite.description });
+            continue;
+        }
+        if (prerequisite.mustContain && prerequisite.mustContain.length > 0) {
+            const body = await readFile(absolute, 'utf8');
+            const lowered = body.toLowerCase();
+            const missingMarkers = prerequisite.mustContain.filter((marker) => !lowered.includes(marker.toLowerCase()));
+            if (missingMarkers.length > 0) {
+                missing.push({
+                    path: relative,
+                    description: `${prerequisite.description} — missing section(s): ${missingMarkers.join(', ')}`
+                });
+            }
         }
     }
     return { ok: missing.length === 0, missing };

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.0.19";
+export declare const CLI_VERSION = "1.0.20";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.0.19";
+export const CLI_VERSION = "1.0.20";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-qa/SKILL.md

@@ -34,9 +34,9 @@ Every QA invocation — feature, bug, refactor, clarification — must write **t
 
 | # | 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 |
+| 1 | Test cases | `.peaks/<session-id>/qa/test-cases/<request-id>.md` | RD (before impl), QA | Generated test scenarios with status |
+| 2 | Test report | `.peaks/<session-id>/qa/test-reports/<request-id>.md` | QA, SC, Solo | Summary, coverage%, security, perf, risks |
+| 3 | Request artifact | `.peaks/<session-id>/qa/requests/<request-id>.md` | Solo, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
 
 Concrete template and rules: `references/artifact-per-request.md`.
 

package/skills/peaks-rd/SKILL.md

@@ -442,11 +442,29 @@ Before RD work stops, finishes, blocks, or hands off to another role, emit a sho
 
 **Matt Pocock skills** (`diagnose`, `triage`, `tdd`, `improve-codebase-architecture`, `prototype`): Engineering references only. Inspect before applying; Peaks RD gates remain authoritative.
 
+## Matt Pocock skills integration
+
+Engineering methods from `mattpocock/skills` can inform RD work but never replace Peaks gates. Inspect upstream skill content before applying any method.
+
+- `diagnose` — root-cause investigation before fixing
+- `triage` — prioritize bug surface area
+- `tdd` — drive implementation from failing tests
+- `improve-codebase-architecture` — opportunistic refactor framing
+- `prototype` — throwaway exploration before committing to a slice
+
+These are references only; Peaks RD gates remain authoritative for handoff, acceptance, and slice closure.
+
 **Understand Anything**: Consume via `peaks understand status/show --json`. Fall back to `peaks codegraph context` or local project scan when absent.
 
 **Codegraph**: Optional local analysis via `peaks codegraph context/affected`. Output as untrusted supporting evidence; never commit `.codegraph/` artifacts.
 
-**Other external resources** (Context7, SearchCode, everything-claude-code, GitNexus, etc.): Use `peaks capabilities --source access-repo/mcp-server --json` before recommending. Reference-only, no execute/install/persist. Peaks RD gates remain authoritative.
+## Codegraph project analysis
+
+RD may use `peaks codegraph affected --project <path> <changed-files...> --json` as local project-analysis evidence to inform red-line scope boundaries before writing tech-doc or starting implementation. Treat the output as untrusted supporting evidence — verify against the actual code before relying on it.
+
+Do not run upstream installer flows, mutate agent settings, or commit `.codegraph/` artifacts. Peaks RD gates remain authoritative for handoff and acceptance.
+
+**Other external resources** (Context7, SearchCode, everything-claude-code, GitNexus, etc.): Use `peaks capabilities --source access-repo/mcp-server --json` for capability discovery before recommending. References only — do not execute upstream installers, do not install upstream resources, do not persist sensitive examples. Peaks RD gates remain authoritative.
 
 **OpenSpec and MCP CLI**: Route through Peaks CLI (`peaks openspec show/to-rd/render`, `peaks mcp list/plan/apply/call`). Do not hand-edit `openspec/changes/**` or `~/.claude/settings.json`. Recipes: `references/openspec-mcp-cli.md`.
 

package/skills/peaks-solo/SKILL.md

@@ -71,7 +71,7 @@ Use the Peaks CLI for runtime side effects.
 
 Map gstack stages to Peaks role artifacts; preserve Peaks confirmation gates. Do not delegate orchestration to gstack commands.
 
-For frontend workflows, RD and QA must use Playwright MCP for real browser E2E (`peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes`). Chrome DevTools MCP is a secondary CDP surface only. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). See `references/browser-workflow.md`.
+For frontend workflows, RD and QA must use Playwright MCP (`mcp__playwright__` tool namespace) for real browser E2E (`peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes`). Chrome DevTools MCP is a secondary CDP surface only. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). See `references/browser-workflow.md`.
 
 ## Local intermediate artifact workspace (MANDATORY)
 
@@ -731,7 +731,13 @@ Use Peaks TXT for the compact handoff capsule: mode, validated decisions, artifa
 
 **Codegraph**: Optional project-analysis before RD handoff. Use `peaks codegraph affected --project <path> <changed-files...> --json` for regression-surface hints. Output as untrusted supporting evidence only; never commit `.codegraph/` artifacts.
 
-**External skills**: All external skill references (`mattpocock/skills`, `awesome-design-md`, `taste-skill`, `shadcn/ui`, `Chrome DevTools MCP`, `Figma Context MCP`, `Context7`, etc.) follow the three-stage pattern: capability discovery before naming, reference-only (no execute/install/persist), Peaks CLI for all side effects. External skills inform, they do not approve.
+## Codegraph orchestration context
+
+Solo treats `peaks codegraph affected --project <path> <changed-files...> --json` as an optional project-analysis enhancement that informs the role handoff between PRD, RD, and QA. The output is untrusted supporting evidence — Solo must not treat codegraph output as approval for scope, design, or QA verdict.
+
+Do not run upstream installer flows, mutate agent settings, or commit `.codegraph/` artifacts into git. Peaks gates remain authoritative; codegraph context is a hint, never a substitute for role-skill output.
+
+**External skills**: All external skill references (`mattpocock/skills`, `awesome-design-md`, `taste-skill`, `shadcn/ui`, `Chrome DevTools MCP`, `Figma Context MCP`, `Context7`, etc.) follow the three-stage pattern: capability discovery via `peaks capabilities` before naming, references only (no execute/install/persist), Peaks CLI for all side effects. Do not execute upstream installers, do not install upstream resources, do not persist sensitive examples — Peaks gates remain authoritative. External skills inform, they do not approve.
 
 **OpenSpec lifecycle**: `render → validate → show → to-rd → validate → archive`. Solo's default runbook handles the exit gate (validate → archive after QA pass). Entry-gate validation (to-rd before slicing) is available when `openspec/` exists pre-workflow; Solo delegates it to `peaks-rd` during implementation.
 

package/skills/peaks-ui/SKILL.md

@@ -34,8 +34,8 @@ Every UI invocation that touches user-visible behavior — including bug fixes t
 
 | # | File | Purpose |
 |---|------|---------|
-| 1 | `.peaks/<id>/ui/design-draft.md` | Design direction, dials, component specs, anti-template checklist |
-| 2 | `.peaks/<id>/ui/requests/<rid>.md` | Links to #1, records visual direction decisions, regression seeds |
+| 1 | `.peaks/<session-id>/ui/design-draft.md` | Design direction, dials, component specs, anti-template checklist |
+| 2 | `.peaks/<session-id>/ui/requests/<request-id>.md` | Links to #1, records visual direction decisions, regression seeds |
 
 RD consumes the design-draft to implement; QA consumes it for visual regression checks.