peaks-cli 1.2.4 → 1.2.5

package/dist/src/cli/commands/openspec-commands.js

@@ -4,6 +4,7 @@ import { projectOpenSpecToRdInput } from '../../services/openspec/openspec-bridg
 import { renderOpenSpecChange } from '../../services/openspec/openspec-render-service.js';
 import { validateOpenSpecChange } from '../../services/openspec/openspec-validate-service.js';
 import { archiveOpenSpecChange } from '../../services/openspec/openspec-archive-service.js';
+import { executeOpenSpecInit } from '../../services/openspec/openspec-init-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function resolveScanOptions(project) {
@@ -166,4 +167,34 @@ export function registerOpenSpecCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(openspec
+        .command('init')
+        .description('Scaffold the openspec/ directory in the target project (changes/, archive/, README.md, CHANGES.md). Idempotent — refuses to overwrite an existing openspec/')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'write files to disk (default: dry-run preview)', false)).action(async (options) => {
+        try {
+            const result = await executeOpenSpecInit({
+                projectRoot: options.project,
+                apply: options.apply === true
+            });
+            const nextActions = [];
+            if (result.alreadyInitialized) {
+                nextActions.push('openspec/ already exists; no files were created or modified.');
+                if (result.existingFiles.length > 0) {
+                    nextActions.push(`Existing files preserved: ${result.existingFiles.join(', ')}`);
+                }
+            }
+            else if (!result.apply) {
+                nextActions.push('Re-run with --apply to write the planned files to disk.');
+            }
+            else {
+                nextActions.push('Run `peaks openspec render --request <path> --apply` to scaffold a first change proposal.');
+            }
+            printResult(io, ok('openspec.init', result, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.init', 'OPENSPEC_INIT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

package/dist/src/cli/commands/workspace-commands.js

@@ -1,16 +1,39 @@
-import { initWorkspace, InvalidSessionIdError } from '../../services/workspace/workspace-service.js';
+import { initWorkspace, InvalidSessionIdError, ConflictingSessionError } from '../../services/workspace/workspace-service.js';
+import { ensureSession } from '../../services/session/session-manager.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerWorkspaceCommands(program, io) {
     const workspace = program.command('workspace').description('Manage the Peaks per-session artifact workspace (.peaks/<session-id>/)');
     addJsonOption(workspace
         .command('init')
-        .description('Create the .peaks/<session-id>/ directory structure (prd, ui, rd, qa, sc, txt, system) — validates the session id format')
+        .description('Create the .peaks/<session-id>/ directory structure (prd, ui, rd, qa, sc, txt, system) and bind the session as the project current one. Pass --session-id to use a specific id, or omit it to auto-generate one (and adopt an existing binding if present).')
         .requiredOption('--project <path>', 'target project root')
-        .requiredOption('--session-id <id>', 'session id in YYYY-MM-DD-<kebab-slug> format')).action(async (options) => {
+        .option('--session-id <id>', 'optional session id in YYYY-MM-DD-<kebab-slug> format. When omitted, the CLI is the single source of truth: an existing binding is reused, otherwise a fresh id is auto-generated.')
+        .option('--allow-session-rebind', 'overwrite an existing session binding when the requested session id differs from the project current one', false)).action(async (options) => {
         try {
-            const report = await initWorkspace({ projectRoot: options.project, sessionId: options.sessionId });
+            // Resolve the session id. Two paths:
+            //   - explicit --session-id: use it as the requested binding target
+            //     (ConflictingSessionError fires if it conflicts with an in-flight
+            //     session, unless --allow-session-rebind is set)
+            //   - omitted: defer to ensureSession(), which reuses an existing
+            //     binding or auto-generates a fresh one. The init then writes
+            //     .session.json so the binding sticks.
+            let sessionId;
+            if (options.sessionId !== undefined && options.sessionId.length > 0) {
+                sessionId = options.sessionId;
+            }
+            else {
+                sessionId = await ensureSession(options.project);
+            }
+            const report = await initWorkspace({
+                projectRoot: options.project,
+                sessionId,
+                allowSessionRebind: options.allowSessionRebind === true
+            });
             const nextActions = [];
+            if (report.previousSessionId !== null && report.bound) {
+                nextActions.push(`Replaced prior session binding "${report.previousSessionId}" with "${report.sessionId}".`);
+            }
             if (report.created.length === 0) {
                 nextActions.push('Workspace already initialized — proceed to project scan.');
             }
@@ -25,6 +48,17 @@ export function registerWorkspaceCommands(program, io) {
                 process.exitCode = 1;
                 return;
             }
+            if (error instanceof ConflictingSessionError) {
+                printResult(io, fail('workspace.init', error.code, error.message, {
+                    existingSessionId: error.existingSessionId,
+                    requestedSessionId: error.requestedSessionId
+                }, [
+                    `Finish or abandon session "${error.existingSessionId}" first, then re-run workspace init.`,
+                    'Or pass --allow-session-rebind to override the binding (overwrites the prior binding).'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
             printResult(io, fail('workspace.init', 'WORKSPACE_INIT_FAILED', getErrorMessage(error), { projectRoot: options.project, sessionId: options.sessionId }, ['Verify the project path exists and is writable']), options.json);
             process.exitCode = 1;
         }

package/dist/src/services/memory/project-memory-service.d.ts

@@ -123,5 +123,23 @@ export declare function createProjectMemoryBackupPlan(options: BackupPlanOptions
 export declare function executeProjectMemoryBackup(options: BackupPlanOptions): ProjectMemoryBackupResult;
 export declare function summarizeProjectMemoryExtractResult(result: ProjectMemoryExtractResult): ProjectMemoryExtractSummary;
 export declare function summarizeProjectMemoryBackupResult(result: ProjectMemoryBackupResult): ProjectMemoryBackupSummary;
+/**
+ * Ensure `.peaks/memory/` and its `index.json` exist for a project, with
+ * the same full-shape empty index the generator emits when there are zero
+ * memories. Idempotent — safe to call on every skill activation.
+ *
+ * Why this exists: before this helper, `.peaks/memory/` was only created
+ * by `extractSessionMemories` when at least one memory markdown was being
+ * written, and `index.json` was only emitted by the generator when at
+ * least one markdown was on disk. Stock projects therefore had no
+ * `.peaks/memory/` directory and no index, even after `peaks project
+ * memories` was read. Bootstrap closes that cold-start gap.
+ *
+ * This function is fail-open for the same reason the rest of the
+ * presence layer is fail-open: a failure here must NOT block skill
+ * activation. Any error is swallowed and surfaced only via the returned
+ * boolean. Callers that need the truth should check the result.
+ */
+export declare function ensureMemoryBootstrap(projectRoot: string): boolean;
 export declare function readProjectMemories(projectRoot: string): ProjectMemoryReadResult;
 export {};

package/dist/src/services/memory/project-memory-service.js

@@ -1,5 +1,5 @@
 import { closeSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { dirname, basename, isAbsolute, join, relative, resolve } from 'node:path';
 import { isInsidePath, isWindowsAbsolutePath, normalizePath, resolveInputPath, stablePath, stableRealPath } from '../../shared/path-utils.js';
 import { containsSensitiveConfigValue, isSensitiveConfigPath } from '../config/config-service.js';
 // Hot kinds: full body kept in index for always-available context
@@ -270,11 +270,26 @@ function readMemoryFileMtime(filePath) {
     }
 }
 function readStoredMemoryNames(memoryDir) {
+    // Two source-of-truth fallbacks for the slug-collision check:
+    //   1. Parse frontmatter (the canonical form rendered by
+    //      renderMemoryFile / written by both extract paths).
+    //   2. Fall back to the bare filename stem, so user-dropped files
+    //      without frontmatter (e.g. hand-written memories, legacy
+    //      content) still count as a collision and are not overwritten
+    //      by an idempotent re-extract.
     const names = new Set();
     for (const filePath of listMarkdownFiles(memoryDir)) {
-        const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
-        if (parsed)
-            names.add(parsed.name);
+        const stem = basename(filePath, '.md');
+        if (stem.length > 0 && stem !== 'index')
+            names.add(stem);
+        try {
+            const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
+            if (parsed)
+                names.add(parsed.name);
+        }
+        catch {
+            // ignore unreadable files
+        }
     }
     return names;
 }
@@ -339,15 +354,30 @@ export function readMemoryIndex(projectRoot) {
     const normalizedRoot = normalizeRoot(projectRoot);
     const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
     const indexPath = join(memoryDir, 'index.json');
-    if (existsSync(memoryDir)) {
-        const files = listMarkdownFiles(memoryDir);
-        if (files.length > 0) {
-            try {
-                generateMemoryIndexFile(normalizedRoot, memoryDir, indexPath);
-            }
-            catch {
-                // fall through to read existing
-            }
+    // Read-side bootstrap: if the memory dir is missing entirely, build a full
+    // empty index so downstream readers always see a well-formed result. We
+    // also fall through if the dir is present but the index is missing — the
+    // user may have nuked the index file, or never had one because no
+    // memory has ever been extracted in this project.
+    if (!existsSync(memoryDir)) {
+        ensureMemoryBootstrap(normalizedRoot);
+        return readExistingIndex(indexPath);
+    }
+    if (!existsSync(indexPath)) {
+        try {
+            writeFileSync(indexPath, renderEmptyIndex(), { mode: 0o644 });
+        }
+        catch {
+            // fall through — readExistingIndex will return null
+        }
+    }
+    const files = listMarkdownFiles(memoryDir);
+    if (files.length > 0) {
+        try {
+            generateMemoryIndexFile(normalizedRoot, memoryDir, indexPath);
+        }
+        catch {
+            // fall through to read existing
         }
     }
     return readExistingIndex(indexPath);
@@ -537,7 +567,18 @@ export function executeProjectMemoryExtract(options) {
     if (plan.apply) {
         mkdirSync(plan.primaryMemoryDir, { recursive: true });
         const safeMemoryDir = assertSafeProjectMemoryDir(plan.projectRoot);
+        // Idempotency: skip writes for memories whose slug already lives in
+        // .peaks/memory/. Re-running `peaks memory extract --apply` on the
+        // same handoff is a normal peaks-solo / peaks-txt retry pattern (the
+        // skill prompt may invoke extract more than once when a handoff is
+        // edited and re-extracted). Without this, writeNewFile's O_EXCL
+        // throws EEXIST and aborts the whole batch. Symmetric with
+        // extractSessionMemories (line ~614) which does the same skip.
+        const existingNames = readStoredMemoryNames(plan.primaryMemoryDir);
         for (const write of plan.plannedWrites) {
+            const slug = slugify(write.memory.title);
+            if (existingNames.has(slug))
+                continue;
             const targetPath = resolveInputPath(write.filePath);
             const stableTargetPath = stablePath(targetPath);
             if (!isInsidePath(stableTargetPath, stableRealPath(safeMemoryDir))) {
@@ -546,6 +587,18 @@ export function executeProjectMemoryExtract(options) {
             writeNewFile(targetPath, write.content);
             writtenFiles.push(targetPath);
         }
+        // After writing any markdown, regenerate the index so downstream
+        // readers (peaks project memory-index, peaks-txt re-runs, the next
+        // session's presence-set bootstrap) see the new memory. Without
+        // this, `peaks memory extract --apply` would leave the index stale
+        // and `readMemoryIndex` would either return the empty bootstrap or
+        // — pre-bootstrap-fix — return null. Symmetric with
+        // extractSessionMemories, which already regenerates the index on
+        // apply (see line ~626). We regen whenever --apply is set, even
+        // if every write was skipped by idempotency, so the index is
+        // always rebuilt against the current .peaks/memory/ directory.
+        const indexPath = join(plan.primaryMemoryDir, 'index.json');
+        generateMemoryIndexFile(plan.projectRoot, plan.primaryMemoryDir, indexPath);
     }
     return { ...plan, writtenFiles };
 }
@@ -609,9 +662,74 @@ function emptyByKind() {
         module: []
     };
 }
+function emptyIndex() {
+    // Cast through unknown: we *intend* the two halves to together cover the
+    // union `ProjectMemoryKind`, but TS does not know that. The `MemoryIndex`
+    // type's `hot` / `warm` fields together cover the union; we split the
+    // construction so the JSON output mirrors the hot/warm layout the reader
+    // expects.
+    return {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        hot: {
+            feedback: [],
+            decision: [],
+            rule: [],
+            convention: [],
+            module: []
+        },
+        warm: {
+            project: [],
+            reference: []
+        }
+    };
+}
+function renderEmptyIndex() {
+    return JSON.stringify(emptyIndex(), null, 2) + '\n';
+}
+/**
+ * Ensure `.peaks/memory/` and its `index.json` exist for a project, with
+ * the same full-shape empty index the generator emits when there are zero
+ * memories. Idempotent — safe to call on every skill activation.
+ *
+ * Why this exists: before this helper, `.peaks/memory/` was only created
+ * by `extractSessionMemories` when at least one memory markdown was being
+ * written, and `index.json` was only emitted by the generator when at
+ * least one markdown was on disk. Stock projects therefore had no
+ * `.peaks/memory/` directory and no index, even after `peaks project
+ * memories` was read. Bootstrap closes that cold-start gap.
+ *
+ * This function is fail-open for the same reason the rest of the
+ * presence layer is fail-open: a failure here must NOT block skill
+ * activation. Any error is swallowed and surfaced only via the returned
+ * boolean. Callers that need the truth should check the result.
+ */
+export function ensureMemoryBootstrap(projectRoot) {
+    try {
+        const normalizedRoot = normalizeRoot(projectRoot);
+        const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+        const indexPath = join(memoryDir, 'index.json');
+        mkdirSync(memoryDir, { recursive: true });
+        if (!existsSync(indexPath)) {
+            writeFileSync(indexPath, renderEmptyIndex(), { mode: 0o644 });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export function readProjectMemories(projectRoot) {
     const normalizedRoot = normalizeRoot(projectRoot);
     const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+    // Read-side bootstrap: on a stock project the directory does not exist
+    // yet. Reading must not return an error, but we also want the directory
+    // to materialise (along with a full-shape empty index) so subsequent
+    // `peaks project memories` invocations, `readMemoryIndex`, and any
+    // extraction call find a stable target. The helper is fail-open.
+    if (!existsSync(memoryDir)) {
+        ensureMemoryBootstrap(normalizedRoot);
+    }
     const memories = [];
     for (const filePath of listMarkdownFiles(memoryDir)) {
         const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);

package/dist/src/services/openspec/openspec-init-service.d.ts

@@ -0,0 +1,23 @@
+export type OpenSpecInitOptions = {
+    projectRoot: string;
+    apply?: boolean;
+};
+export type OpenSpecInitPlan = {
+    apply: boolean;
+    projectRoot: string;
+    openspecRoot: string;
+    plannedWrites: Array<{
+        path: string;
+        kind: 'directory' | 'file';
+        bytes: number;
+        content: string;
+    }>;
+    alreadyInitialized: boolean;
+    existingFiles: string[];
+};
+export type OpenSpecInitResult = OpenSpecInitPlan & {
+    writtenFiles: string[];
+    createdDirectories: string[];
+};
+export declare function planOpenSpecInit(options: OpenSpecInitOptions): Promise<OpenSpecInitPlan>;
+export declare function executeOpenSpecInit(options: OpenSpecInitOptions): Promise<OpenSpecInitResult>;

package/dist/src/services/openspec/openspec-init-service.js

@@ -0,0 +1,122 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDirectory, pathExists } from '../../shared/fs.js';
+const README_BODY = `# OpenSpec — change proposals for this project
+
+This directory hosts the \`peaks openspec\` change proposal lifecycle:
+
+  render → validate → show → to-rd → ... → archive
+
+Each in-flight proposal lives in \`changes/<id>/\` and contains:
+
+- \`proposal.md\`  — why, what, non-goals, impact
+- \`tasks.md\`     — concrete slices and commit boundaries (consumed by peaks-sc)
+- \`design.md\`   — optional, for non-trivial designs
+- \`specs/\`       — optional, delta-style spec changes (## ADDED / ## MODIFIED / ## REMOVED)
+- \`*.md\`         — any additional narrative the change needs
+
+When a change ships, \`peaks openspec archive <id> --apply\` moves it into
+\`changes/archive/<id>/\`. The archive is the historical record of what
+landed and why.
+
+To scaffold a fresh change in this project:
+
+  peaks openspec render --request <path-to-render-request.json> --apply
+
+For the full lifecycle see \`peaks openspec --help\` and the
+peaks-clause-code skill family.
+`;
+const CHANGES_INDEX_HEADER = `# OpenSpec — change log
+
+This file is the human-readable index of every change that has shipped in
+this project. New entries are added by \`peaks openspec archive\` (when
+\`.apply\` is used); do not hand-edit.
+
+| Date | Change | Status |
+|------|--------|--------|
+`;
+function renderReadme() {
+    return README_BODY;
+}
+function renderChangesIndex() {
+    return CHANGES_INDEX_HEADER;
+}
+function buildPlan(projectRoot, apply) {
+    const openspecRoot = join(projectRoot, 'openspec');
+    const changesRoot = join(openspecRoot, 'changes');
+    const archiveRoot = join(changesRoot, 'archive');
+    const plannedWrites = [
+        { path: openspecRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: changesRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: archiveRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: join(openspecRoot, 'README.md'), kind: 'file', bytes: 0, content: renderReadme() },
+        { path: join(openspecRoot, 'CHANGES.md'), kind: 'file', bytes: 0, content: renderChangesIndex() }
+    ];
+    // Stamp byte counts now that content is finalised.
+    for (const write of plannedWrites) {
+        if (write.kind === 'file') {
+            write.bytes = Buffer.byteLength(write.content, 'utf8');
+        }
+    }
+    return {
+        apply,
+        projectRoot,
+        openspecRoot,
+        plannedWrites,
+        alreadyInitialized: false,
+        existingFiles: []
+    };
+}
+export async function planOpenSpecInit(options) {
+    const openspecRoot = join(options.projectRoot, 'openspec');
+    const plan = buildPlan(options.projectRoot, options.apply ?? false);
+    if (await isDirectory(openspecRoot)) {
+        // Already initialised. Report the existing files so the user can audit
+        // before re-running with --apply. We never overwrite an existing
+        // openspec/ — that is a destructive action and out of scope for init.
+        const existing = [];
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'file' && (await pathExists(write.path))) {
+                existing.push(write.path);
+            }
+        }
+        // Pre-compute which directory writes to keep (those whose target does
+        // not exist yet). .filter cannot be async, so resolve the boolean
+        // set up front.
+        const directoryKeep = new Set();
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'directory' && !(await isDirectory(write.path))) {
+                directoryKeep.add(write.path);
+            }
+        }
+        plan.plannedWrites = plan.plannedWrites.filter((write) => {
+            if (write.kind === 'directory')
+                return directoryKeep.has(write.path);
+            return !existing.includes(write.path);
+        });
+        plan.alreadyInitialized = existing.length > 0 || (await isDirectory(join(openspecRoot, 'changes')));
+        plan.existingFiles = existing;
+    }
+    return plan;
+}
+export async function executeOpenSpecInit(options) {
+    const plan = await planOpenSpecInit(options);
+    const writtenFiles = [];
+    const createdDirectories = [];
+    if (plan.apply && !plan.alreadyInitialized) {
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'directory') {
+                if (!(await isDirectory(write.path))) {
+                    await mkdir(write.path, { recursive: true });
+                    createdDirectories.push(write.path);
+                }
+                continue;
+            }
+            if (write.content.length === 0)
+                continue;
+            await writeFile(write.path, write.content, 'utf8');
+            writtenFiles.push(write.path);
+        }
+    }
+    return { ...plan, writtenFiles, createdDirectories };
+}

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

@@ -1 +1 @@
-export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, type SessionInfo, type SessionMeta } from './session-manager.js';
+export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, type SessionInfo, type SessionMeta } from './session-manager.js';

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

@@ -1 +1 @@
-export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan } from './session-manager.js';
+export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding } from './session-manager.js';

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

@@ -20,6 +20,17 @@ export type SessionMeta = {
     lastActivity?: string;
     projectRoot: string;
 };
+/**
+ * Bind the project's current session to the given session id by writing
+ * `.peaks/.session.json`. The single-session binding is the source of truth
+ * for `ensureSession()` and any other path that needs to discover the
+ * active session without an explicit --session-id flag.
+ *
+ * This does NOT touch the per-session `session.json` inside `.peaks/<id>/`;
+ * that file is owned by `setSessionMeta` and records session-scoped
+ * metadata (title, skill, mode, gate, etc.).
+ */
+export declare function setCurrentSessionBinding(projectRoot: string, sessionId: string): SessionInfo;
 /**
  * Read metadata for a specific session directory.
  * Returns null if the session directory or its session.json does not exist.

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

@@ -61,6 +61,25 @@ function writeSessionFile(projectRoot, info) {
     }
     writeFileSync(sessionFile, JSON.stringify(info, null, 2), 'utf8');
 }
+/**
+ * Bind the project's current session to the given session id by writing
+ * `.peaks/.session.json`. The single-session binding is the source of truth
+ * for `ensureSession()` and any other path that needs to discover the
+ * active session without an explicit --session-id flag.
+ *
+ * This does NOT touch the per-session `session.json` inside `.peaks/<id>/`;
+ * that file is owned by `setSessionMeta` and records session-scoped
+ * metadata (title, skill, mode, gate, etc.).
+ */
+export function setCurrentSessionBinding(projectRoot, sessionId) {
+    const info = {
+        sessionId,
+        createdAt: new Date().toISOString(),
+        projectRoot
+    };
+    writeSessionFile(projectRoot, info);
+    return info;
+}
 function getMetaFilePath(projectRoot, sessionId) {
     return join(projectRoot, '.peaks', sessionId, META_FILE);
 }

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

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
+import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
 export const VALID_SKILL_PRESENCE_MODES = [
     'full-auto',
     'assisted',
@@ -67,6 +68,16 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
         mkdirSync(presenceDir, { recursive: true });
     }
     writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    // Skill-activation side effect: ensure `.peaks/memory/` and a full-shape
+    // empty `index.json` exist for the project. This is the user-facing fix
+    // for "stock projects never get a memory directory or index". Every peaks
+    // skill starts with `peaks skill presence:set peaks-<role>`, so doing the
+    // bootstrap here means the very first skill invocation in a fresh project
+    // (or in a stock project that pre-dates the memory layer) brings the
+    // memory store into existence. The helper is fail-open, so a failure here
+    // does not block presence from being written.
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    ensureMemoryBootstrap(projectRoot);
     return presence;
 }
 export function getSkillPresence(projectRootOverride) {

package/dist/src/services/workspace/workspace-service.d.ts

@@ -1,16 +1,31 @@
 export type WorkspaceInitOptions = {
     projectRoot: string;
     sessionId: string;
+    /**
+     * When true, the conflict check is skipped and the new session id is
+     * written to .peaks/.session.json even if the project is already bound
+     * to a different (real) session. Use only with explicit user authorization
+     * — the CLI surfaces this as `--allow-session-rebind`.
+     */
+    allowSessionRebind?: boolean;
 };
 export type WorkspaceInitReport = {
     sessionId: string;
     sessionRoot: string;
     created: string[];
     alreadyExisted: string[];
+    bound: boolean;
+    previousSessionId: string | null;
 };
 export declare class InvalidSessionIdError extends Error {
     readonly code = "INVALID_SESSION_ID";
     constructor(message: string);
 }
+export declare class ConflictingSessionError extends Error {
+    readonly existingSessionId: string;
+    readonly requestedSessionId: string;
+    readonly code = "CONFLICTING_SESSION";
+    constructor(message: string, existingSessionId: string, requestedSessionId: string);
+}
 export declare function validateSessionId(sessionId: string): void;
 export declare function initWorkspace(options: WorkspaceInitOptions): Promise<WorkspaceInitReport>;