peaks-cli 1.0.21 → 1.0.23

package/dist/src/services/workflow/pipeline-verify-service.js

@@ -0,0 +1,180 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { isRequestType } from '../artifacts/artifact-prerequisites.js';
+async function readFileContent(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function extractState(markdown) {
+    for (const rawLine of markdown.split(/\r?\n/)) {
+        const match = /^-\s*state:\s*(.+?)\s*$/.exec(rawLine.trim());
+        if (match?.[1])
+            return match[1];
+    }
+    return 'unknown';
+}
+async function findRequestFile(projectRoot, sessionId, role, rid) {
+    const dir = join(projectRoot, '.peaks', sessionId, role, 'requests');
+    if (!existsSync(dir))
+        return null;
+    const { readdir } = await import('node:fs/promises');
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        if (entry.name === `${rid}.md` || (/^\d+-/.test(entry.name) && entry.name.endsWith(`-${rid}.md`))) {
+            const path = join(dir, entry.name);
+            const content = await readFileContent(path);
+            if (content)
+                return { path, content };
+        }
+    }
+    return null;
+}
+function rdGatesForType(requestType) {
+    const gates = [
+        { name: 'rd-request-exists', description: 'RD request artifact created', passed: false, detail: '' }
+    ];
+    if (requestType === 'feature' || requestType === 'refactor') {
+        gates.push({ name: 'tech-doc', description: 'Technical design doc', passed: false, detail: '' });
+    }
+    if (requestType === 'bugfix') {
+        gates.push({ name: 'bug-analysis', description: 'Bug root-cause analysis', passed: false, detail: '' });
+    }
+    if (requestType !== 'docs' && requestType !== 'chore' && requestType !== 'config') {
+        gates.push({ name: 'code-review', description: 'Code review evidence', passed: false, detail: '' });
+    }
+    if (requestType === 'feature' || requestType === 'refactor' || requestType === 'bugfix' || requestType === 'config') {
+        gates.push({ name: 'security-review', description: 'Security review evidence', passed: false, detail: '' });
+    }
+    return gates;
+}
+function qaGatesForType(requestType) {
+    const gates = [
+        { name: 'qa-request-exists', description: 'QA request artifact created', passed: false, detail: '' }
+    ];
+    if (requestType === 'feature' || requestType === 'refactor' || requestType === 'bugfix') {
+        gates.push({ name: 'test-cases', description: 'QA test cases', passed: false, detail: '' });
+        gates.push({ name: 'test-report', description: 'QA test report with execution results', passed: false, detail: '' });
+    }
+    if (requestType === 'feature' || requestType === 'refactor' || requestType === 'bugfix' || requestType === 'config') {
+        gates.push({ name: 'security-findings', description: 'QA security findings', passed: false, detail: '' });
+    }
+    if (requestType === 'feature' || requestType === 'refactor') {
+        gates.push({ name: 'performance-findings', description: 'QA performance findings', passed: false, detail: '' });
+    }
+    return gates;
+}
+const RD_QA_HANDOFF_STATES = new Set(['qa-handoff', 'handed-off', 'implemented']);
+const QA_COMPLETE_STATES = new Set(['verdict-issued']);
+export async function verifyPipeline(options) {
+    const requestType = isRequestType(options.requestType ?? '') ? options.requestType : 'feature';
+    const violations = [];
+    const nextActions = [];
+    const rdGates = rdGatesForType(requestType);
+    const qaGates = qaGatesForType(requestType);
+    // Check RD phase
+    const rdFile = await findRequestFile(options.projectRoot, options.sessionId, 'rd', options.rid);
+    let rdInvoked = false;
+    let rdState = 'missing';
+    if (rdFile) {
+        rdInvoked = true;
+        rdState = extractState(rdFile.content);
+        rdGates[0].passed = true;
+        rdGates[0].detail = `found at ${rdFile.path}`;
+    }
+    else {
+        violations.push('RD phase skipped: peaks-rd was never invoked for this request (no RD request artifact found)');
+        nextActions.push('Invoke Skill(skill="peaks-rd") with the request-id, then run unit tests + code review + security review');
+        rdGates[0].detail = 'not found';
+    }
+    // Check RD evidence files
+    const RD_EVIDENCE_FILE = {
+        'tech-doc': 'tech-doc.md',
+        'bug-analysis': 'bug-analysis.md',
+        'code-review': 'code-review.md',
+        'security-review': 'security-review.md'
+    };
+    for (const gate of rdGates.slice(1)) {
+        const fileName = RD_EVIDENCE_FILE[gate.name];
+        const evidencePath = join(options.projectRoot, '.peaks', options.sessionId, 'rd', fileName);
+        if (existsSync(evidencePath)) {
+            gate.passed = true;
+            gate.detail = evidencePath;
+        }
+        else {
+            gate.detail = `missing: ${evidencePath}`;
+            violations.push(`RD evidence missing: ${gate.description} (${fileName})`);
+            nextActions.push(`Create .peaks/${options.sessionId}/rd/${fileName}`);
+        }
+    }
+    // Check if RD reached qa-handoff
+    if (rdInvoked && !RD_QA_HANDOFF_STATES.has(rdState)) {
+        violations.push(`RD not ready for QA: state is "${rdState}" — must reach "qa-handoff" (unit tests, karpathy standards, code review, security review complete)`);
+        nextActions.push(`Complete RD gates → peaks request transition ${options.rid} --role rd --state qa-handoff`);
+    }
+    // Check QA phase
+    const qaFile = await findRequestFile(options.projectRoot, options.sessionId, 'qa', options.rid);
+    let qaInvoked = false;
+    let qaState = 'missing';
+    if (qaFile) {
+        qaInvoked = true;
+        qaState = extractState(qaFile.content);
+        qaGates[0].passed = true;
+        qaGates[0].detail = `found at ${qaFile.path}`;
+    }
+    else {
+        violations.push('QA phase skipped: peaks-qa was never invoked for this request (no QA request artifact found)');
+        nextActions.push('Invoke Skill(skill="peaks-qa") with the request-id for functional/performance/security testing');
+        qaGates[0].detail = 'not found';
+    }
+    // Check QA evidence files
+    const QA_EVIDENCE_FILE = {
+        'test-cases': `test-cases/${options.rid}.md`,
+        'test-report': `test-reports/${options.rid}.md`,
+        'security-findings': 'security-findings.md',
+        'performance-findings': 'performance-findings.md'
+    };
+    for (const gate of qaGates.slice(1)) {
+        const fileName = QA_EVIDENCE_FILE[gate.name];
+        const evidencePath = join(options.projectRoot, '.peaks', options.sessionId, 'qa', fileName);
+        if (existsSync(evidencePath)) {
+            gate.passed = true;
+            gate.detail = evidencePath;
+        }
+        else {
+            gate.detail = `missing: ${evidencePath}`;
+            violations.push(`QA evidence missing: ${gate.description} (${fileName})`);
+            nextActions.push(`Create .peaks/${options.sessionId}/qa/${fileName}`);
+        }
+    }
+    // Check if QA reached verdict-issued
+    if (qaInvoked && !QA_COMPLETE_STATES.has(qaState)) {
+        violations.push(`QA not complete: state is "${qaState}" — must reach "verdict-issued" (functional + performance + security checks done)`);
+        nextActions.push(`Complete QA gates → peaks request transition ${options.rid} --role qa --state verdict-issued`);
+    }
+    // RD invoked without QA
+    if (rdInvoked && !qaInvoked) {
+        violations.push('CRITICAL: peaks-rd was invoked but peaks-qa was NOT — QA functional/performance/security testing is mandatory after all RD work');
+        nextActions.push('MUST invoke Skill(skill="peaks-qa") before declaring workflow complete');
+    }
+    const allRdGatesPassed = rdGates.every((g) => g.passed);
+    const allQaGatesPassed = qaGates.every((g) => g.passed);
+    const complete = rdInvoked && qaInvoked && allRdGatesPassed && allQaGatesPassed
+        && RD_QA_HANDOFF_STATES.has(rdState) && QA_COMPLETE_STATES.has(qaState);
+    return {
+        rid: options.rid,
+        sessionId: options.sessionId,
+        requestType,
+        complete,
+        rdPhase: { invoked: rdInvoked, state: rdState, gates: rdGates },
+        qaPhase: { invoked: qaInvoked, state: qaState, gates: qaGates },
+        violations,
+        nextActions
+    };
+}

package/dist/src/services/workspace/workspace-service.js

@@ -15,6 +15,8 @@ const SUBDIRECTORIES = [
 ];
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
 const PROHIBITED_SUFFIXES = ['session', 'work', 'task', 'test', 'temp', 'tmp'];
+// Auto-generated session ID pattern: YYYY-MM-DD-session-<6位hex>
+const AUTO_SESSION_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]{6}$/;
 export class InvalidSessionIdError extends Error {
     code = 'INVALID_SESSION_ID';
     constructor(message) {
@@ -23,6 +25,10 @@ export class InvalidSessionIdError extends Error {
     }
 }
 export function validateSessionId(sessionId) {
+    // Auto-generated session IDs (YYYY-MM-DD-session-<hex>) bypass manual validation
+    if (AUTO_SESSION_PATTERN.test(sessionId)) {
+        return;
+    }
     if (/^\d+$/.test(sessionId)) {
         throw new InvalidSessionIdError(`Session id "${sessionId}" is numeric-only. Use the format YYYY-MM-DD-<kebab-slug> with a 2-5 word topic description.`);
     }

package/dist/src/shared/change-id.d.ts

@@ -11,5 +11,18 @@ export declare class ChangeIdValidationError extends Error {
     constructor(changeId: string);
 }
 export declare function isUnsafeArtifactPath(path: string): boolean;
+/**
+ * Build an artifact-relative path using session-based storage.
+ *
+ * If a session exists, files are stored in:
+ *   .peaks/<sessionId>/<role>/<number>-<changeId>.md
+ *
+ * If no session exists, falls back to legacy behavior:
+ *   .peaks/<changeId>/<segments>
+ *
+ * @param changeId - Used as file description/slug (e.g., "auth-system", "add-user-auth")
+ * @param segments - Optional path segments (first segment is typically the role: 'prd', 'rd', 'qa', etc.)
+ * @returns Relative path to the artifact file
+ */
 export declare function buildArtifactRelativePath(changeId: string, ...segments: string[]): string;
 export declare function isPathInsideArtifactRoot(path: string, artifactRoot: string): boolean;

package/dist/src/shared/change-id.js

@@ -3,7 +3,9 @@
  * All Peaks planner commands must use these to prevent path traversal
  * and keep artifacts inside the Peaks artifact workspace.
  */
-import { posix } from 'node:path';
+import { posix, join } from 'node:path';
+import { getNextNumber, buildNumberedFilename } from './incrementing-number.js';
+import { getSessionId } from '../services/session/session-manager.js';
 const CHANGE_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
 function normalizeForwardSlashes(input) {
     return input.replace(/\\/g, '/');
@@ -58,8 +60,34 @@ export class ChangeIdValidationError extends Error {
 export function isUnsafeArtifactPath(path) {
     return isUnsafePathInput(path);
 }
+/**
+ * Build an artifact-relative path using session-based storage.
+ *
+ * If a session exists, files are stored in:
+ *   .peaks/<sessionId>/<role>/<number>-<changeId>.md
+ *
+ * If no session exists, falls back to legacy behavior:
+ *   .peaks/<changeId>/<segments>
+ *
+ * @param changeId - Used as file description/slug (e.g., "auth-system", "add-user-auth")
+ * @param segments - Optional path segments (first segment is typically the role: 'prd', 'rd', 'qa', etc.)
+ * @returns Relative path to the artifact file
+ */
 export function buildArtifactRelativePath(changeId, ...segments) {
     validateChangeIdOrThrow(changeId);
+    const sessionId = getSessionId(process.cwd());
+    if (sessionId && segments.length > 0 && segments[0]) {
+        const role = normalizeForwardSlashes(segments[0]);
+        const dirPath = join(process.cwd(), '.peaks', sessionId, role);
+        if (isUnsafeArtifactPath(role) || isUnsafeArtifactPath(sessionId)) {
+            throw new ChangeIdValidationError(changeId);
+        }
+        const number = getNextNumber(dirPath);
+        const filename = buildNumberedFilename(number, changeId);
+        const candidatePath = `.peaks/${sessionId}/${role}/${filename}`;
+        return normalizeArtifactPath(candidatePath);
+    }
+    // Fallback: no session or no segments - use legacy behavior
     const joined = segments.map((segment) => normalizeForwardSlashes(segment)).join('/');
     const candidatePath = `.peaks/${changeId}/${joined}`;
     if (isUnsafeArtifactPath(joined) || isUnsafeArtifactPath(candidatePath)) {

package/dist/src/shared/incrementing-number.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Utilities for generating incrementing numbered filenames.
+ * Used by session-based artifact storage to create files like 001-feature.md.
+ */
+/**
+ * Get the next available number in a directory.
+ * Scans existing .md files and finds the highest numeric prefix.
+ * Returns 1 if directory is empty or doesn't exist.
+ *
+ * @param dirPath - Directory to scan for numbered files
+ * @returns Next available number (1, 2, 3, ...)
+ */
+export declare function getNextNumber(dirPath: string): number;
+/**
+ * Build a numbered filename from a number and description.
+ * Format: 001-description-slug.md
+ *
+ * @param number - The file number (will be zero-padded to 3 digits)
+ * @param description - Human-readable description (converted to kebab-case slug)
+ * @returns Formatted filename like "001-feature-name.md"
+ */
+export declare function buildNumberedFilename(number: number, description: string): string;
+/**
+ * Get the next numbered file path in a directory.
+ * Combines getNextNumber() and buildNumberedFilename().
+ *
+ * @param dirPath - Directory to scan
+ * @param description - Description for the filename
+ * @returns Full path to the new numbered file
+ */
+export declare function getNextNumberedFilePath(dirPath: string, description: string): string;

package/dist/src/shared/incrementing-number.js

@@ -0,0 +1,58 @@
+/**
+ * Utilities for generating incrementing numbered filenames.
+ * Used by session-based artifact storage to create files like 001-feature.md.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Get the next available number in a directory.
+ * Scans existing .md files and finds the highest numeric prefix.
+ * Returns 1 if directory is empty or doesn't exist.
+ *
+ * @param dirPath - Directory to scan for numbered files
+ * @returns Next available number (1, 2, 3, ...)
+ */
+export function getNextNumber(dirPath) {
+    if (!existsSync(dirPath))
+        return 1;
+    const files = readdirSync(dirPath).filter(f => f.endsWith('.md'));
+    if (files.length === 0)
+        return 1;
+    const numbers = files
+        .map(f => {
+        const match = /^(\d+)-/.exec(f);
+        return match && match[1] ? parseInt(match[1], 10) : NaN;
+    })
+        .filter(n => !isNaN(n));
+    return numbers.length > 0 ? Math.max(...numbers) + 1 : 1;
+}
+/**
+ * Build a numbered filename from a number and description.
+ * Format: 001-description-slug.md
+ *
+ * @param number - The file number (will be zero-padded to 3 digits)
+ * @param description - Human-readable description (converted to kebab-case slug)
+ * @returns Formatted filename like "001-feature-name.md"
+ */
+export function buildNumberedFilename(number, description) {
+    const padded = String(number).padStart(3, '0');
+    const slug = description
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 50); // Limit slug length
+    return `${padded}-${slug}.md`;
+}
+/**
+ * Get the next numbered file path in a directory.
+ * Combines getNextNumber() and buildNumberedFilename().
+ *
+ * @param dirPath - Directory to scan
+ * @param description - Description for the filename
+ * @returns Full path to the new numbered file
+ */
+export function getNextNumberedFilePath(dirPath, description) {
+    const number = getNextNumber(dirPath);
+    const filename = buildNumberedFilename(number, description);
+    return join(dirPath, filename);
+}

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.0.21";
+export declare const CLI_VERSION = "1.0.23";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.0.21";
+export const CLI_VERSION = "1.0.23";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -35,6 +35,7 @@
     "dev:watch": "node ./scripts/watch.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "pretest:coverage": "pkill -f vitest 2>/dev/null; rm -rf coverage; exit 0",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "engines": {

package/skills/peaks-rd/SKILL.md

@@ -68,6 +68,9 @@ peaks codegraph affected --project <repo> <changed-files...> --json
 # **STOP if .peaks/<session-id>/rd/project-scan.md does not exist.**
 # **Do not write any code, do not plan any implementation, do not pass go.**
 # **Create the project-scan first, then proceed.**
+# NOTE: project-scan.md is a session-scoped singleton. Check if it already exists
+# before regenerating (e.g. via `ls .peaks/<id>/rd/project-scan.md`). If it exists
+# and is complete (has `## Archetype` and `## Project mode` sections), reuse it.
 # Required sections in project-scan:
 #   - build tool and framework
 #   - component library (antd, MUI, shadcn, etc.) and version

package/skills/peaks-solo/SKILL.md

@@ -9,6 +9,39 @@ Peaks Solo is the orchestration facade for the Peaks short skill family.
 
 Use this skill to identify the user scenario, recommend an execution mode, coordinate role skills, and produce the final handoff report. Do not collapse role responsibilities into this skill.
 
+## Code-Change Red Line (BLOCKING — read before ANY tool call)
+
+**Peaks Solo is an orchestrator, NOT an implementer. You MUST NOT write, edit, or modify any application source code directly.**
+
+Every code change — bugfix, feature, refactor, or config — MUST go through the full pipeline:
+
+```
+peaks-solo (orchestrate only)
+  → Skill(skill="peaks-rd")  ← ALL code changes happen HERE
+    → Unit tests written + pass (Gate B2)
+    → Karpathy standards enforced (file-size ≤800 lines, TypeScript rules)
+    → Code review evidence (Gate B3)
+    → Security review evidence (Gate B4)
+  → Skill(skill="peaks-qa")  ← ALL validation happens HERE
+    → Functional test execution (Gate A2)
+    → Performance check (Gate A4)
+    → Security test (Gate A3)
+    → Browser E2E (when frontend; Gate D)
+    → Verdict: pass | return-to-rd | blocked
+```
+
+**Violations (BLOCKING — Solo must refuse to proceed):**
+
+1. Writing implementation code directly instead of calling `Skill(skill="peaks-rd")`
+2. Declaring work "done" without invoking `Skill(skill="peaks-qa")` after RD
+3. Skipping unit tests ("it's a small change")
+4. Skipping code review or security review
+5. Skipping QA functional/performance/security validation
+
+**If you catch yourself about to write code in this skill, STOP. Call `Skill(skill="peaks-rd")` instead.**
+
+**Before declaring workflow complete, run:** `peaks workflow verify-pipeline --rid <rid> --project <repo> --json`
+
 ## Startup sequence (MANDATORY — execute in order)
 
 ### Step 1: Mode selection (MUST run before presence:set)
@@ -77,27 +110,24 @@ For frontend workflows, RD and QA must use Playwright MCP (`mcp__playwright__` t
 
 ### Workspace initialization gate
 
-Before ANY role handoff or artifact write, Peaks Solo MUST create the workspace. The session-id uses the format `YYYY-MM-DD-<kebab-slug>` where `<kebab-slug>` is the **request-id or a 2-5 word topic description** (e.g. `2026-05-25-v3-indicator-model`, `2026-05-25-add-user-auth`).
+Before ANY role handoff or artifact write, Peaks Solo MUST create the workspace. Session IDs are now **auto-generated** with the format `YYYY-MM-DD-session-<6位hex>` (e.g. `2026-05-26-session-a3f8b1`). The user does not provide a session ID — the system creates and persists it in `.peaks/.session.json`.
 
-**PROHIBITED session-id patterns** — block the workflow if any of these appear:
-- Numeric-only: `1779674289`, `1779672642`
-- Generic suffixes: `session`, `work`, `task`, `test`, `temp`, `tmp`
-- Bare dates without topic: `2026-05-25`
-- Timestamps: `20260525T093000`
+When `peaks workspace init` is run without `--session-id`, it automatically generates a new session ID using today's date and a random hex suffix. If `.peaks/.session.json` already exists with a valid session, the existing session is reused.
 
-**Existing old-session cleanup**: If `.peaks/` contains numeric-only or generic session directories from prior runs, create the new correctly-named session, migrate any reusable artifacts into it, and note the migration in the TXT handoff. Delete empty old-session directories.
+**Existing old-session cleanup**: If `.peaks/` contains numeric-only or generic session directories from prior runs (e.g. `2026-05-25-auth-system`), create the new correctly-named session, migrate any reusable artifacts into it, and note the migration in the TXT handoff. Delete empty old-session directories.
 
 ```bash
-peaks workspace init --project <repo> --session-id <YYYY-MM-DD-<slug>> --json
+peaks workspace init --project <repo> --json
 ```
 
-The workspace initialization creates this structure under `.peaks/<session-id>/`:
+The workspace initialization creates this structure under `.peaks/<session-id>/` (where `<session-id>` is auto-generated as `YYYY-MM-DD-session-<6位hex>`):
 
 ```
 prd/source/      # PRD source documents (Feishu exports, pasted content)
 prd/requests/    # PRD request artifacts (goals, non-goals, acceptance, frontend delta)
 ui/requests/     # UI request artifacts (visual direction, taste reports)
 rd/requests/     # RD request artifacts (slice specs, coverage, CR findings)
+rd/project-scan.md  # Project scan (session-scoped singleton, generated once per session)
 qa/test-cases/   # QA test cases
 qa/test-reports/ # QA test reports (regression matrices, browser evidence)
 qa/requests/     # QA request artifacts
@@ -138,7 +168,7 @@ Do not default to git-backed storage or automatic commits for intermediate artif
 
 ## Pre-RD project scan checklist (MANDATORY)
 
-Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/<session-id>/rd/project-scan.md`. RD and UI roles read this before starting work.
+Before handing off to `peaks-rd`, scan the project and record findings to `.peaks/<session-id>/rd/project-scan.md`. RD and UI roles read this before starting work. **project-scan.md is a session-scoped singleton** — check if it already exists before regenerating (e.g. via `ls .peaks/<session-id>/rd/project-scan.md`). If it exists and is complete (has `## Archetype` and `## Project mode` sections), reuse it. Only regenerate if missing or incomplete.
 
 ### 0. Project archetype detection (MANDATORY — run FIRST, deterministic CLI)
 
@@ -388,6 +418,7 @@ ls .peaks/<id>/rd/project-scan.md
 # Expected output: .peaks/<id>/rd/project-scan.md
 # "No such file" → STOP, run project scan first
 # File present but missing `## Archetype` or `## Project mode` sections → INCOMPLETE, rerun scan
+# File present and complete → reuse (project-scan is a session-scoped singleton)
 ```
 
 **Gate A.5 — Existing-system extraction (legacy projects only):**
@@ -571,7 +602,7 @@ The end-to-end CLI sequence for the `full-auto` profile. `assisted` and `strict`
 peaks doctor --json
 peaks project dashboard --project <repo> --json
 peaks skill runbook peaks-solo --json
-peaks workspace init --project <repo> --session-id <YYYY-MM-DD-<slug>> --json
+peaks workspace init --project <repo> --json
 peaks scan archetype --project <repo> --json
 # → copy archetype, frontendOnly, signals into .peaks/<session-id>/rd/project-scan.md (Gate A)
 # → if archetype != greenfield AND archetype != unknown:

package/skills/peaks-ui/SKILL.md

@@ -67,6 +67,9 @@ peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
 
 # 3. read project-scan for component library and CSS framework context
 #    check .peaks/<session-id>/rd/project-scan.md (blocking if missing for existing projects)
+#    NOTE: project-scan.md is a session-scoped singleton — check if it already exists before
+#    regenerating. If it exists and is complete (has `## Archetype` and `## Project mode`
+#    sections), reuse it.
 
 # 4. PROTOTYPE FIDELITY CHECK (MANDATORY before any design work):
 #    Check if a Figma file, PRD screenshots, or explicit PRD visuals exist.