peaks-cli 1.0.20 → 1.0.22

package/dist/src/services/session/session-manager.js

@@ -0,0 +1,150 @@
+/**
+ * Session management service for Peaks artifact storage.
+ * Manages session lifecycle: creation, retrieval, and directory initialization.
+ *
+ * Sessions are automatically created when any skill is invoked.
+ * Each session gets a unique directory under .peaks/ with incrementing numbered files.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { initWorkspace } from '../workspace/workspace-service.js';
+const SESSION_FILE = '.session.json';
+/**
+ * Generate a new session ID.
+ * Format: YYYY-MM-DD-session-<6位hex>
+ * Example: 2026-05-26-session-a3f8b1
+ */
+function generateSessionId() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    const date = `${year}-${month}-${day}`;
+    const random = randomBytes(3).toString('hex'); // 6位hex
+    return `${date}-session-${random}`;
+}
+/**
+ * Get the path to the session file for a project.
+ */
+function getSessionFilePath(projectRoot) {
+    return join(projectRoot, '.peaks', SESSION_FILE);
+}
+/**
+ * Read existing session info from disk.
+ * Returns null if no session file exists or if it's invalid.
+ */
+function readSessionFile(projectRoot) {
+    const sessionFile = getSessionFilePath(projectRoot);
+    if (!existsSync(sessionFile))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(sessionFile, 'utf8'));
+        if (data.sessionId && data.projectRoot === projectRoot) {
+            return data;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write session info to disk.
+ */
+function writeSessionFile(projectRoot, info) {
+    const sessionFile = getSessionFilePath(projectRoot);
+    const dir = join(projectRoot, '.peaks');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(sessionFile, JSON.stringify(info, null, 2), 'utf8');
+}
+/**
+ * Get or create the current session for a project.
+ * If a valid session already exists, returns it.
+ * Otherwise, creates a new session with auto-generated ID.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Session ID (e.g., "2026-05-26-session-a3f8b1")
+ */
+export async function ensureSession(projectRoot) {
+    const existing = readSessionFile(projectRoot);
+    if (existing) {
+        return existing.sessionId;
+    }
+    const sessionId = generateSessionId();
+    const info = {
+        sessionId,
+        createdAt: new Date().toISOString(),
+        projectRoot
+    };
+    writeSessionFile(projectRoot, info);
+    await initWorkspace({ projectRoot, sessionId });
+    return sessionId;
+}
+/**
+ * Get the current session ID without creating a new one.
+ * Returns null if no session exists.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Session ID or null
+ */
+export function getSessionId(projectRoot) {
+    const info = readSessionFile(projectRoot);
+    return info?.sessionId ?? null;
+}
+/**
+ * Get the absolute path to the current session directory.
+ * Creates the session if it doesn't exist.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path to session directory (e.g., "/path/to/project/.peaks/2026-05-26-session-a3f8b1")
+ */
+export async function getCurrentSessionDir(projectRoot) {
+    const sessionId = await ensureSession(projectRoot);
+    return join(projectRoot, '.peaks', sessionId);
+}
+/**
+ * List all session directories in the .peaks folder.
+ * Returns session IDs (directory names) sorted by date.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Array of session IDs
+ */
+export function listSessions(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    const { readdirSync } = require('node:fs');
+    const entries = readdirSync(peaksRoot, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isDirectory() && /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(entry.name))
+        .map((entry) => entry.name)
+        .sort()
+        .reverse(); // Most recent first
+}
+/**
+ * Get the path to project-scan.md for the current session.
+ * Creates the session if it doesn't exist.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path to project-scan.md
+ */
+export async function getProjectScanPath(projectRoot) {
+    const sessionId = await ensureSession(projectRoot);
+    return join(projectRoot, '.peaks', sessionId, 'rd', 'project-scan.md');
+}
+/**
+ * Check if project-scan.md exists for the current session.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns true if project-scan.md exists
+ */
+export function hasProjectScan(projectRoot) {
+    const info = readSessionFile(projectRoot);
+    if (!info)
+        return false;
+    const scanPath = join(projectRoot, '.peaks', info.sessionId, 'rd', 'project-scan.md');
+    return existsSync(scanPath);
+}

package/dist/src/services/skills/skill-presence-service.d.ts

@@ -1,6 +1,9 @@
+export type SkillPresenceMode = 'full-auto' | 'assisted' | 'swarm' | 'strict';
+export declare const VALID_SKILL_PRESENCE_MODES: ReadonlyArray<SkillPresenceMode>;
+export declare function isSkillPresenceMode(value: string): value is SkillPresenceMode;
 export type SkillPresence = {
     skill: string;
-    mode?: string;
+    mode?: SkillPresenceMode;
     gate?: string;
     setAt: string;
 };

package/dist/src/services/skills/skill-presence-service.js

@@ -1,5 +1,14 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+export const VALID_SKILL_PRESENCE_MODES = [
+    'full-auto',
+    'assisted',
+    'swarm',
+    'strict'
+];
+export function isSkillPresenceMode(value) {
+    return VALID_SKILL_PRESENCE_MODES.includes(value);
+}
 const PRESENCE_FILE = '.peaks/.active-skill.json';
 function resolvePresencePath() {
     return resolve(process.cwd(), PRESENCE_FILE);
@@ -8,9 +17,10 @@ export function exportSkillPresence() {
     return resolvePresencePath();
 }
 export function setSkillPresence(skill, mode, gate) {
+    const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
     const presence = {
         skill,
-        ...(mode ? { mode } : {}),
+        ...(validatedMode ? { mode: validatedMode } : {}),
         ...(gate ? { gate } : {}),
         setAt: new Date().toISOString()
     };

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,37 @@ 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}`;
+        if (isUnsafeArtifactPath(candidatePath)) {
+            throw new ChangeIdValidationError(changeId);
+        }
+        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.20";
+export declare const CLI_VERSION = "1.0.22";

package/dist/src/shared/version.js

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

package/package.json

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

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

@@ -77,27 +77,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 +135,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 +385,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 +569,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.