peaks-cli 1.2.4 → 1.2.6

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,51 @@
-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 { resolveCanonicalProjectRoot } from '../../services/config/config-service.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.
+            //
+            // Before that: canonicalise the project root. If the user (or the
+            // LLM via "$(pwd)") passed a sub-directory of a real git repo
+            // (e.g. prompt-project/prompt-project/ inside the outer
+            // prompt-project/.git), promote the path to the git root. Without
+            // this, peaks would build a parallel .peaks/ tree under the
+            // nested sub-folder and silently break the project-binding model
+            // (the same regression that produced prompt-project/.peaks/ in
+            // the 5/27-5/29 sessions). When startPath is not inside any
+            // git repo, the helper falls through to the cwd verbatim.
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            let sessionId;
+            if (options.sessionId !== undefined && options.sessionId.length > 0) {
+                sessionId = options.sessionId;
+            }
+            else {
+                sessionId = await ensureSession(projectRoot);
+            }
+            const report = await initWorkspace({
+                projectRoot,
+                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 +60,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/config/config-safety.d.ts

@@ -2,6 +2,32 @@ export declare function getUserConfigPath(): string;
 export declare function isInsidePath(childPath: string, parentPath: string): boolean;
 export declare function findProjectRoot(startPath: string): string | null;
 export declare function resolveProjectRootForConfig(startPath: string): string;
+/**
+ * Canonicalise a user-supplied project root path against git's view of the
+ * repository root. This is the fix for the nested-directory regression
+ * where peaks-cli would write `.peaks/` under a nested sub-folder
+ * (e.g. `prompt-project/prompt-project/.peaks/`) because the LLM passed
+ * `$(pwd)` from inside a sub-directory of a real git repo. Without
+ * canonicalisation, peaks accepted the cwd as-is, built the .peaks/
+ * tree there, and left the team with two parallel state stores.
+ *
+ * Strategy:
+ *   1. If `startPath` (or any ancestor) is inside a git repo, return
+ *      `git rev-parse --show-toplevel` from `startPath`. The git root
+ *      is the *only* correct answer for "where does the .peaks/ tree
+ *      belong?" — sub-folders of a git repo are not their own projects.
+ *   2. If `startPath` is not inside a git repo, fall back to
+ *      `findProjectRoot` (the existing heuristic) so the CLI still
+ *      works for non-git projects.
+ *   3. If both fail, return `startPath` unchanged — better to write
+ *      to the cwd than to refuse the command.
+ *
+ * This is intentionally fail-open: it only *promotes* a path towards
+ * the git root, it never demotes one. A non-git user is unaffected.
+ * The function does NOT throw on a missing git binary or a non-zero
+ * `git rev-parse` exit; both fall through to the heuristic.
+ */
+export declare function resolveCanonicalProjectRoot(startPath: string): string;
 export declare function getProjectConfigPath(projectRoot: string | null): string | null;
 export declare function getProjectBootstrapConfigPath(projectRoot: string): string;
 export declare function validateProjectBootstrapConfigPathForWrite(projectRoot: string, configPath: string): void;

package/dist/src/services/config/config-safety.js

@@ -1,4 +1,5 @@
 import { closeSync, constants, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
@@ -89,6 +90,81 @@ export function resolveProjectRootForConfig(startPath) {
     }
     return pkgRoot ?? start;
 }
+/**
+ * Canonicalise a user-supplied project root path against git's view of the
+ * repository root. This is the fix for the nested-directory regression
+ * where peaks-cli would write `.peaks/` under a nested sub-folder
+ * (e.g. `prompt-project/prompt-project/.peaks/`) because the LLM passed
+ * `$(pwd)` from inside a sub-directory of a real git repo. Without
+ * canonicalisation, peaks accepted the cwd as-is, built the .peaks/
+ * tree there, and left the team with two parallel state stores.
+ *
+ * Strategy:
+ *   1. If `startPath` (or any ancestor) is inside a git repo, return
+ *      `git rev-parse --show-toplevel` from `startPath`. The git root
+ *      is the *only* correct answer for "where does the .peaks/ tree
+ *      belong?" — sub-folders of a git repo are not their own projects.
+ *   2. If `startPath` is not inside a git repo, fall back to
+ *      `findProjectRoot` (the existing heuristic) so the CLI still
+ *      works for non-git projects.
+ *   3. If both fail, return `startPath` unchanged — better to write
+ *      to the cwd than to refuse the command.
+ *
+ * This is intentionally fail-open: it only *promotes* a path towards
+ * the git root, it never demotes one. A non-git user is unaffected.
+ * The function does NOT throw on a missing git binary or a non-zero
+ * `git rev-parse` exit; both fall through to the heuristic.
+ */
+export function resolveCanonicalProjectRoot(startPath) {
+    const start = resolve(startPath);
+    const gitRoot = resolveProjectRootFromGit(start);
+    if (gitRoot !== null) {
+        return gitRoot;
+    }
+    // Non-git fallback: walk the heuristic up to the home boundary.
+    // We do NOT call realpathSync on the heuristic result because the
+    // heuristic may legitimately return a path through a symlink that
+    // the caller passed in (no canonicalisation needed in that case).
+    const heuristicRoot = findProjectRoot(start);
+    if (heuristicRoot !== null) {
+        return heuristicRoot;
+    }
+    return start;
+}
+function resolveProjectRootFromGit(startPath) {
+    // execFileSync (not execSync) so a malicious `startPath` cannot
+    // inject argv into the spawned git invocation. The child only
+    // receives `startPath` as the cwd, never as a flag.
+    let rawRoot;
+    try {
+        const stdout = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: startPath,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        const trimmed = stdout.trim();
+        if (trimmed.length === 0)
+            return null;
+        rawRoot = resolve(trimmed);
+    }
+    catch {
+        // git not on PATH, startPath is not in a repo, or some other
+        // benign failure — fall through to the heuristic.
+        return null;
+    }
+    // On macOS, /tmp is a symlink to /private/tmp; git returns the
+    // realpath. If the caller passed a path through the symlink, the
+    // two strings won't match byte-for-byte even though they refer
+    // to the same directory. realpathSync the git root and the
+    // startPath through the same lens so callers get a canonical
+    // answer that compares equal to the path they passed in.
+    try {
+        return realpathSync(rawRoot);
+    }
+    catch {
+        return rawRoot;
+    }
+}
 export function getProjectConfigPath(projectRoot) {
     if (!projectRoot)
         return null;

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

@@ -1,5 +1,5 @@
 import type { ConfigGetOptions, ConfigLayer, ConfigSetOptions, MiniMaxProviderConfig, PeaksConfig, TokenRef, WorkspaceConfig } from './config-types.js';
-export { resolveProjectRootForConfig } from './config-safety.js';
+export { resolveProjectRootForConfig, resolveCanonicalProjectRoot } from './config-safety.js';
 export declare function isConfigLayer(value: string): value is ConfigLayer;
 export declare function isSensitiveConfigPath(path: string): boolean;
 export declare function containsSensitiveConfigValue(value: unknown): boolean;

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

@@ -3,8 +3,8 @@ import { dirname, isAbsolute, resolve } from 'node:path';
 import { DEFAULT_CONFIG } from './config-types.js';
 import { stablePath } from '../../shared/path-utils.js';
 import { findProjectRoot, getProjectBootstrapConfigPath, getProjectConfigPath, getUserConfigPath, isInsidePath, readConfigFileSafely, resolveProjectRootForConfig, validateArtifactWorkspaceMarkerPath, validateArtifactWorkspaceRoot, validateProjectBootstrapConfigPathForWrite, validateUserConfigPathForWrite, writeConfigFileSafely, writeProjectConfigFile, writeUserConfigFile } from './config-safety.js';
-// Re-export resolveProjectRootForConfig for external consumers
-export { resolveProjectRootForConfig } from './config-safety.js';
+// Re-export resolveProjectRootForConfig and resolveCanonicalProjectRoot for external consumers
+export { resolveProjectRootForConfig, resolveCanonicalProjectRoot } from './config-safety.js';
 function readJsonFile(path, validateBeforeRead, errorMessage = 'Config path must stay inside the config root') {
     if (!path || !existsSync(path))
         return null;

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.