peaks-cli 1.0.21 → 1.0.22

package/dist/src/services/mode/mode-enforcement.js

@@ -0,0 +1,81 @@
+import * as readline from 'node:readline';
+import { getSkillPresence } from '../skills/skill-presence-service.js';
+const ASSISTED_CONFIRM_TRANSITIONS = new Set([
+    'prd:confirmed-by-user',
+    'rd:qa-handoff',
+    'qa:verdict-issued'
+]);
+export function requiresConfirmation(mode, transitionKey) {
+    if (mode === 'full-auto' || mode === 'swarm') {
+        return false;
+    }
+    if (mode === 'strict') {
+        return true;
+    }
+    // assisted: only specific transitions
+    return ASSISTED_CONFIRM_TRANSITIONS.has(transitionKey);
+}
+function describeTransition(transitionKey) {
+    const parts = transitionKey.split(':');
+    const role = parts[0] ?? 'unknown';
+    const state = parts[1] ?? 'unknown';
+    return `Transition ${role.toUpperCase()} → ${state}`;
+}
+export class ConfirmationRequiredError extends Error {
+    constructor(transitionKey) {
+        const description = describeTransition(transitionKey);
+        super(`Confirmation required for: ${description}\n` +
+            'Add --confirm to proceed non-interactively, or run in an interactive terminal.\n' +
+            'In assisted/strict mode, major workflow boundaries require explicit user approval.');
+        this.name = 'ConfirmationRequiredError';
+    }
+}
+export async function requireUserConfirmation(options) {
+    const presence = getSkillPresence();
+    if (!presence?.mode) {
+        return;
+    }
+    const mode = presence.mode;
+    if (!requiresConfirmation(mode, options.transitionKey)) {
+        return;
+    }
+    // --confirm flag bypasses interactive prompt
+    if (options.confirmed) {
+        return;
+    }
+    // PEAKS_AUTO_CONFIRM=1 only works for full-auto/swarm (already returned above)
+    // For assisted/strict, env var is ignored unless --force-confirm is also set
+    if (process.env.PEAKS_AUTO_CONFIRM === '1') {
+        if (options.forceConfirm) {
+            console.error(`[WARNING] --force-confirm used in ${mode} mode. ` +
+                'This bypasses user confirmation. Use with caution.');
+            return;
+        }
+        throw new ConfirmationRequiredError(options.transitionKey);
+    }
+    // --force-confirm without env var
+    if (options.forceConfirm) {
+        console.error(`[WARNING] --force-confirm used in ${mode} mode. ` +
+            'This bypasses user confirmation. Use with caution.');
+        return;
+    }
+    // Interactive prompt
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr
+    });
+    return new Promise((resolve, reject) => {
+        const description = describeTransition(options.transitionKey);
+        const prompt = `\n[CONFIRM] ${description}\nProceed? (y/N) `;
+        rl.question(prompt, (answer) => {
+            rl.close();
+            const normalized = answer.trim().toLowerCase();
+            if (normalized === 'y' || normalized === 'yes') {
+                resolve();
+            }
+            else {
+                reject(new ConfirmationRequiredError(options.transitionKey));
+            }
+        });
+    });
+}

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

@@ -2,7 +2,7 @@ import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { basename, relative, resolve } from 'node:path';
 import { isInsidePath } from '../../shared/path-utils.js';
-import { getCurrentWorkspaceConfig } from '../config/config-service.js';
+import { getWorkspaceConfigForPath } from '../config/config-service.js';
 import { getArtifactRemoteRepo, getArtifactWorkspaceStatus, getLocalArtifactPath } from '../artifacts/workspace-service.js';
 const REQUIRED_ARTIFACTS = [
     { name: 'retention-boundary.md', path: ['sc', 'retention-boundary.md'] },
@@ -109,7 +109,7 @@ function isRetainedArtifactFile(filePath, artifactWorkspacePath, changesRoot, ch
     }
 }
 export function getChangeTraceabilityStatus() {
-    const workspace = getCurrentWorkspaceConfig();
+    const workspace = getWorkspaceConfigForPath(process.cwd());
     const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
     if (!workspace) {
         return {
@@ -155,7 +155,7 @@ export function getChangeTraceabilityStatus() {
     };
 }
 export function createChangeImpact(options) {
-    const workspace = getCurrentWorkspaceConfig();
+    const workspace = getWorkspaceConfigForPath(process.cwd());
     const artifactRepo = workspace ? getArtifactRemoteRepo(workspace) : null;
     return {
         changeId: options.changeId,
@@ -193,7 +193,7 @@ export function createArtifactRetentionReport(options) {
     };
 }
 export function recordCommitBoundary(options) {
-    const workspace = getCurrentWorkspaceConfig();
+    const workspace = getWorkspaceConfigForPath(process.cwd());
     const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
     const commitHash = getCurrentCommitHash(workspace?.rootPath);
     return {
@@ -207,7 +207,7 @@ export function recordCommitBoundary(options) {
     };
 }
 export function validateArtifactRetention(sliceId) {
-    const workspace = getCurrentWorkspaceConfig();
+    const workspace = getWorkspaceConfigForPath(process.cwd());
     if (!workspace) {
         return {
             valid: false,

package/dist/src/services/scan/file-size-scan.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_FILE_SIZE_THRESHOLD = 800;
+export type FileSizeViolation = {
+    file: string;
+    lines: number;
+};
+export type FileSizeScanResult = {
+    ok: boolean;
+    threshold: number;
+    checkedFiles: number;
+    violations: FileSizeViolation[];
+};
+export type FileSizeScanOptions = {
+    projectRoot: string;
+    /** Compare working tree against this ref. Default 'HEAD'. */
+    baseRef?: string;
+    /** Line count threshold. Default 800. */
+    threshold?: number;
+};
+export declare function scanFileSize(options: FileSizeScanOptions): FileSizeScanResult;

package/dist/src/services/scan/file-size-scan.js

@@ -0,0 +1,44 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const DEFAULT_FILE_SIZE_THRESHOLD = 800;
+function getChangedFiles(projectRoot, baseRef) {
+    try {
+        const trackedRaw = execFileSync('git', ['-C', projectRoot, 'diff', '--name-only', baseRef], { encoding: 'utf8' });
+        const tracked = trackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        const untrackedRaw = execFileSync('git', ['-C', projectRoot, 'ls-files', '--others', '--exclude-standard'], { encoding: 'utf8' });
+        const untracked = untrackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        return Array.from(new Set([...tracked, ...untracked]));
+    }
+    catch {
+        return [];
+    }
+}
+function countLines(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf8');
+        return content.split(/\r?\n/).length;
+    }
+    catch {
+        return 0;
+    }
+}
+export function scanFileSize(options) {
+    const baseRef = options.baseRef ?? 'HEAD';
+    const threshold = options.threshold ?? DEFAULT_FILE_SIZE_THRESHOLD;
+    const files = getChangedFiles(options.projectRoot, baseRef);
+    const violations = [];
+    for (const file of files) {
+        const absolute = join(options.projectRoot, file);
+        const lines = countLines(absolute);
+        if (lines > threshold) {
+            violations.push({ file, lines });
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        threshold,
+        checkedFiles: files.length,
+        violations
+    };
+}

package/dist/src/services/session/index.d.ts

@@ -0,0 +1 @@
+export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getProjectScanPath, hasProjectScan, type SessionInfo } from './session-manager.js';

package/dist/src/services/session/index.js

@@ -0,0 +1 @@
+export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getProjectScanPath, hasProjectScan } from './session-manager.js';

package/dist/src/services/session/session-manager.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+export type SessionInfo = {
+    sessionId: string;
+    createdAt: string;
+    projectRoot: string;
+};
+/**
+ * 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 declare function ensureSession(projectRoot: string): Promise<string>;
+/**
+ * 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 declare function getSessionId(projectRoot: string): string | 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 declare function getCurrentSessionDir(projectRoot: string): Promise<string>;
+/**
+ * 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 declare function listSessions(projectRoot: string): string[];
+/**
+ * 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 declare function getProjectScanPath(projectRoot: string): Promise<string>;
+/**
+ * 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 declare function hasProjectScan(projectRoot: string): boolean;

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.21";
+export declare const CLI_VERSION = "1.0.22";

package/dist/src/shared/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.21",
+  "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