peaks-cli 1.3.0 → 1.3.2

package/dist/src/services/workspace/migrate-types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Type envelope for the `peaks workspace migrate` CLI command.
+ *
+ * The migrate command is the downstream-project counterpart to the
+ * one-time Phase 5 migration script that ran on the peaks-cli self-host
+ * for slice 2026-06-05-change-id-as-unit-of-work. Where
+ * `peaks workspace reconcile` only handles the top-level runtime state
+ * files (`.peaks/.session.json`, `.peaks/.active-skill.json`,
+ * `.peaks/sop-state/` → `.peaks/_runtime/`), `peaks workspace migrate`
+ * handles the much bigger case: legacy reviewable content under
+ * `.peaks/<session-id>/<role>/<file>` → `.peaks/retrospective/<change-id>/<role>/<file>`.
+ *
+ * Each legacy session dir typically contains multiple change-ids worth
+ * of work (the old layout allowed one session to host several slices).
+ * Change-id resolution uses a 4-tier per-file heuristic (filename
+ * regex → content H1 → body frontmatter → per-session fallback to the
+ * most-recent `<change-id>` in `rd/requests/`).
+ *
+ * Types are hand-rolled, no new top-level dependencies.
+ */
+export type MigrateFilePlan = {
+    /** Absolute source path (under `.peaks/<session-id>/...`). */
+    from: string;
+    /** Absolute target path (under `.peaks/retrospective/<change-id>/...`). */
+    to: string;
+    /** The session dir this file came from. */
+    sessionId: string;
+    /** The change-id the file is being routed to. */
+    changeId: string;
+    /** The role inferred from the file's path (rd/qa/prd/ui/sc). */
+    role: 'prd' | 'ui' | 'rd' | 'qa' | 'sc' | 'system' | 'unknown';
+    /** Path of the file relative to the session dir, e.g. `rd/tech-doc.md`. */
+    relativePath: string;
+    /**
+     * Which tier of the 4-tier heuristic produced the change-id. Null
+     * when the file is not a per-slice artifact (e.g. cross-cutting
+     * `rd/project-scan.md` or `qa/.initiated`).
+     */
+    source: 'filename-regex' | 'content-h1' | 'content-frontmatter' | 'session-fallback' | 'cross-cutting' | null;
+    /** True if the file was skipped (e.g. `session.json`, cross-cutting, conflict). */
+    skipped?: boolean;
+    /** Why the file was skipped (only set when `skipped === true`). */
+    skipReason?: 'transient-runtime' | 'conflict' | 'no-change-id' | 'unsupported-role';
+};
+export type MigrateSessionPlan = {
+    sessionId: string;
+    /** Absolute path to the session dir. */
+    path: string;
+    /** True if the dir is empty / only has `session.json`. */
+    empty: boolean;
+    /** All files in the dir, planned. */
+    files: MigrateFilePlan[];
+    /** The fallback change-id derived from the session's most recent `rd/requests/` entry. Null if no requests exist. */
+    fallbackChangeId: string | null;
+};
+export type MigrateOptions = {
+    projectRoot: string;
+    /** When true, actually `git mv` the files + `rm -rf` the emptied session dirs. */
+    apply: boolean;
+    /**
+     * Slice 003 (2026-06-06-session-layout-canonicalize): when true, the
+     * command performs the **session-dir consolidation** — moves every
+     * top-level `.peaks/<sid>/` to `.peaks/_runtime/<sid>/`. Idempotent;
+     * conflicts (target exists with different content) are logged but
+     * never overwrite. With `apply: false` (the default), the response
+     * lists what WOULD move + the conflicts.
+     *
+     * Mutually exclusive with the reviewable-content migration: the
+     * `--to-runtime` step is the data side of slice 003, while the
+     * default `migrate` step is the cross-cutting content side
+     * (reviewable files → retrospective). Both run when both flags are
+     * set; the order is `--to-runtime` first (so the cross-cutting
+     * step sees the canonical tree) and then the reviewable-content
+     * step.
+     */
+    toRuntime?: boolean;
+};
+export type MigrateToRuntimeFilePlan = {
+    /** Absolute source path (top-level `.peaks/<sid>/`). */
+    from: string;
+    /** Absolute target path (`.peaks/_runtime/<sid>/`). */
+    to: string;
+    /** The session id the dir belongs to. */
+    sessionId: string;
+    /** 'moved' or 'skipped-already-canonical' or 'conflict'. */
+    action: 'moved' | 'skipped-already-canonical' | 'conflict-target-exists-with-different-content' | 'f15-conflict-project-scan';
+    /** Human-readable reason for the action (for the conflicts list). */
+    reason: string;
+};
+export type MigrateResult = {
+    /** Absolute project root the command operated on. */
+    projectRoot: string;
+    /** All discovered legacy session dirs, sorted by name. */
+    sessions: MigrateSessionPlan[];
+    /** All moves the apply step WOULD perform (only populated when `apply: false` as well, for symmetry). */
+    wouldMove: MigrateFilePlan[];
+    /** All moves actually performed (only populated when `apply: true`). */
+    moved: MigrateFilePlan[];
+    /** Sessions that became empty after the move and were/will be removed. */
+    deletedSessions: string[];
+    /** Sessions that WOULD become empty (dry-run only). */
+    wouldDeleteSessions: string[];
+    /** Files that already exist at the target (collision). Dry-run reports; apply skips + warns. */
+    conflicts: Array<{
+        from: string;
+        to: string;
+        reason: string;
+    }>;
+    /** Whether `--apply` was set. */
+    apply: boolean;
+    /** Total files moved or scheduled to move. */
+    totalFilesMoved: number;
+    /**
+     * Slice 003: per-session-dir move plans for the `--to-runtime` step.
+     * Empty when `toRuntime` was not set. Conflicts include both the
+     * top-level/<sid>/ → _runtime/<sid>/ collisions AND the F15 carve-out
+     * for `rd/project-scan.md`.
+     */
+    toRuntimePlans?: MigrateToRuntimeFilePlan[];
+    toRuntimeMoved?: string[];
+    toRuntimeSkipped?: string[];
+    toRuntimeConflicts?: Array<{
+        from: string;
+        to: string;
+        reason: string;
+    }>;
+};

package/dist/src/services/workspace/migrate-types.js

@@ -0,0 +1,21 @@
+/**
+ * Type envelope for the `peaks workspace migrate` CLI command.
+ *
+ * The migrate command is the downstream-project counterpart to the
+ * one-time Phase 5 migration script that ran on the peaks-cli self-host
+ * for slice 2026-06-05-change-id-as-unit-of-work. Where
+ * `peaks workspace reconcile` only handles the top-level runtime state
+ * files (`.peaks/.session.json`, `.peaks/.active-skill.json`,
+ * `.peaks/sop-state/` → `.peaks/_runtime/`), `peaks workspace migrate`
+ * handles the much bigger case: legacy reviewable content under
+ * `.peaks/<session-id>/<role>/<file>` → `.peaks/retrospective/<change-id>/<role>/<file>`.
+ *
+ * Each legacy session dir typically contains multiple change-ids worth
+ * of work (the old layout allowed one session to host several slices).
+ * Change-id resolution uses a 4-tier per-file heuristic (filename
+ * regex → content H1 → body frontmatter → per-session fallback to the
+ * most-recent `<change-id>` in `rd/requests/`).
+ *
+ * Types are hand-rolled, no new top-level dependencies.
+ */
+export {};

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

@@ -75,6 +75,39 @@ export declare function applyDeletions(candidates: SessionEntry[], apply: boolea
         message: string;
     }>;
 };
+/**
+ * Sync the single `change/<canonicalSessionId>/` live marker under
+ * `.peaks/_runtime/change/`. The marker is an EMPTY directory (no
+ * symlinks, no manifest, no content). Slice 006 collapses the F3
+ * per-change-id symlink layer to a single live marker so the
+ * `change/` layer is a single sentinel — easy for the LLM to
+ * navigate, easy for tests to assert on.
+ *
+ * Steps:
+ *   1. Ensure `.peaks/_runtime/change/` exists.
+ *   2. List its entries.
+ *   3. Remove every entry whose name is NOT `<canonicalSessionId>/`
+ *      (no-op for those whose name matches).
+ *   4. If `<canonicalSessionId>/` is missing, create it (empty).
+ *   5. Return the diff for telemetry.
+ *
+ * Path-traversal guards: the canonical session id is validated by
+ * the caller (`SESSION_ID_PATTERN` in the session-manager helper).
+ * The function only ever operates under the project-root-resolved
+ * `.peaks/_runtime/change/` dir, so the resolved paths cannot
+ * escape the project tree.
+ *
+ * @returns `{ removed, created, error }`:
+ *   - `removed`: list of entry names that were deleted (e.g. `['<oldSid>/']`).
+ *   - `created`: name of the new marker (e.g. `'<newSid>/'`) or null
+ *     when the canonical marker already existed (no-op).
+ *   - `error`: error message string or null.
+ */
+export declare function syncChangeMarker(projectRoot: string, canonicalSessionId: string): {
+    removed: string[];
+    created: string | null;
+    error: string | null;
+};
 /**
  * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
  *

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

@@ -55,59 +55,75 @@ function runtimeNewBasename(oldBasename) {
  * of files under the dir excluding `session.json` itself.
  */
 export function discoverSessions(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
     const peaksRoot = join(projectRoot, '.peaks');
-    if (!existsSync(peaksRoot))
-        return [];
-    let names;
-    try {
-        names = readdirSync(peaksRoot);
-    }
-    catch {
-        return [];
-    }
+    // As of slice 003, the canonical home for session dirs is
+    // `.peaks/_runtime/<sid>/`. The legacy top-level layout is
+    // read for back-compat (one minor release) so pre-migration
+    // trees keep working. Both are scanned; duplicates (same sid
+    // in both homes) are de-duplicated with the canonical home
+    // winning.
+    const seen = new Set();
     const entries = [];
-    for (const name of names) {
-        if (!SESSION_ID_PATTERN.test(name))
-            continue;
-        const dir = join(peaksRoot, name);
-        let stat;
+    const collect = (root) => {
+        if (!existsSync(root))
+            return;
+        let names;
         try {
-            // lstatSync: false for symlinks (prevents rm -rf from following a
-            // malicious symlink that points outside the project root).
-            stat = lstatSync(dir);
+            names = readdirSync(root);
         }
         catch {
-            continue;
+            return;
         }
-        if (!stat.isDirectory())
-            continue;
-        const metaPath = join(dir, META_FILE);
-        let lastActivity = null;
-        if (existsSync(metaPath)) {
-            try {
-                lastActivity = statSync(metaPath).mtimeMs;
-            }
-            catch {
-                lastActivity = null;
-            }
+        for (const name of names) {
+            if (!SESSION_ID_PATTERN.test(name))
+                continue;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            scanSessionDir(root, name, entries);
         }
-        let childNames;
+    };
+    collect(runtimeRoot);
+    collect(peaksRoot);
+    entries.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+    return entries;
+}
+function scanSessionDir(peaksRoot, name, entries) {
+    const dir = join(peaksRoot, name);
+    let stat;
+    try {
+        stat = lstatSync(dir);
+    }
+    catch {
+        return;
+    }
+    if (!stat.isDirectory())
+        return;
+    const metaPath = join(dir, META_FILE);
+    let lastActivity = null;
+    if (existsSync(metaPath)) {
         try {
-            childNames = readdirSync(dir);
+            lastActivity = statSync(metaPath).mtimeMs;
         }
         catch {
-            childNames = [];
+            lastActivity = null;
         }
-        let artifactCount = 0;
-        for (const child of childNames) {
-            if (child === META_FILE)
-                continue;
-            artifactCount += 1;
-        }
-        entries.push({ sessionId: name, path: dir, lastActivity, artifactCount });
     }
-    entries.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
-    return entries;
+    let childNames;
+    try {
+        childNames = readdirSync(dir);
+    }
+    catch {
+        childNames = [];
+    }
+    let artifactCount = 0;
+    for (const child of childNames) {
+        if (child === META_FILE)
+            continue;
+        artifactCount += 1;
+    }
+    entries.push({ sessionId: name, path: dir, lastActivity, artifactCount });
 }
 /**
  * 4-tier canonical selection. Tiers evaluated in order; first one that
@@ -299,6 +315,76 @@ function readActiveSkillSessionId(projectRoot) {
     }
     return null;
 }
+/**
+ * Sync the single `change/<canonicalSessionId>/` live marker under
+ * `.peaks/_runtime/change/`. The marker is an EMPTY directory (no
+ * symlinks, no manifest, no content). Slice 006 collapses the F3
+ * per-change-id symlink layer to a single live marker so the
+ * `change/` layer is a single sentinel — easy for the LLM to
+ * navigate, easy for tests to assert on.
+ *
+ * Steps:
+ *   1. Ensure `.peaks/_runtime/change/` exists.
+ *   2. List its entries.
+ *   3. Remove every entry whose name is NOT `<canonicalSessionId>/`
+ *      (no-op for those whose name matches).
+ *   4. If `<canonicalSessionId>/` is missing, create it (empty).
+ *   5. Return the diff for telemetry.
+ *
+ * Path-traversal guards: the canonical session id is validated by
+ * the caller (`SESSION_ID_PATTERN` in the session-manager helper).
+ * The function only ever operates under the project-root-resolved
+ * `.peaks/_runtime/change/` dir, so the resolved paths cannot
+ * escape the project tree.
+ *
+ * @returns `{ removed, created, error }`:
+ *   - `removed`: list of entry names that were deleted (e.g. `['<oldSid>/']`).
+ *   - `created`: name of the new marker (e.g. `'<newSid>/'`) or null
+ *     when the canonical marker already existed (no-op).
+ *   - `error`: error message string or null.
+ */
+export function syncChangeMarker(projectRoot, canonicalSessionId) {
+    const root = resolve(projectRoot);
+    const changeDir = join(root, '.peaks', '_runtime', 'change');
+    const removed = [];
+    let created = null;
+    let error = null;
+    try {
+        if (!existsSync(changeDir)) {
+            mkdirSync(changeDir, { recursive: true });
+        }
+        const markerPath = join(changeDir, canonicalSessionId);
+        let existingNames = [];
+        try {
+            existingNames = readdirSync(changeDir);
+        }
+        catch {
+            existingNames = [];
+        }
+        for (const name of existingNames) {
+            if (name === canonicalSessionId)
+                continue;
+            const stale = join(changeDir, name);
+            try {
+                rmSync(stale, { recursive: true, force: true });
+                removed.push(name);
+            }
+            catch (e) {
+                // Best-effort: a single un-deletable entry must not abort the
+                // sync (the caller gets the rest of the diff).
+                error = e instanceof Error ? e.message : String(e);
+            }
+        }
+        if (!existsSync(markerPath)) {
+            mkdirSync(markerPath, { recursive: true });
+            created = canonicalSessionId;
+        }
+    }
+    catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+    }
+    return { removed, created, error };
+}
 /**
  * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
  *
@@ -445,6 +531,36 @@ export function reconcileWorkspace(options) {
     }
     const deletionCandidates = findDeletionCandidates(sessions, ageThresholdMs);
     const deletionResult = applyDeletions(deletionCandidates, apply);
+    // Slice 006: sync the single `change/<canonicalSessionId>/` live
+    // marker (replaces the F3 per-change-id symlink layer). The marker
+    // is an empty dir; the function removes every other entry under
+    // `.peaks/_runtime/change/`. Idempotent. This step is independent
+    // of the apply flag — syncing the marker is a derived-state write,
+    // not a destructive side effect.
+    const changeMarker = canonical === null
+        ? { removed: [], created: null, error: 'no canonical session' }
+        : syncChangeMarker(projectRoot, canonical.sessionId);
+    // Slice 006: clean up the F3-introduced `.peaks/_runtime/<sid>/system/`
+    // subdir under EVERY session dir (not just the canonical one). The
+    // subdir was created eagerly by `initWorkspace` (F3) but was never
+    // used. The cleanup is idempotent: re-running on a tree without the
+    // subdir is a no-op. We walk every discovered session, not just the
+    // canonical one, because the user has 6 F3 sessions with the cruft
+    // and the spec says all of them must be removed. Logged in the
+    // systemCleaned array.
+    const systemCleaned = [];
+    for (const session of sessions) {
+        const systemDir = join(session.path, 'system');
+        if (existsSync(systemDir)) {
+            try {
+                rmSync(systemDir, { recursive: true, force: true });
+                systemCleaned.push(systemDir);
+            }
+            catch {
+                // Best-effort: a locked subdir does not block the rest of reconcile.
+            }
+        }
+    }
     return {
         projectRoot,
         sessions,
@@ -459,6 +575,8 @@ export function reconcileWorkspace(options) {
         apply,
         repointed,
         migratedFiles: migration.migratedFiles,
-        errors: [...migrateErrors, ...deletionResult.errors]
+        errors: [...migrateErrors, ...deletionResult.errors],
+        changeMarker,
+        systemCleaned
     };
 }

package/dist/src/services/workspace/reconcile-types.d.ts

@@ -78,6 +78,31 @@ export type ReconcileResult = {
         path: string;
         message: string;
     }>;
+    /**
+     * Slice 006 (2026-06-06-change-folder-simplify-and-lazy-role-subdirs):
+     * result of syncing the single `change/<canonicalSessionId>/` live
+     * marker under `.peaks/_runtime/change/`. The marker is an empty
+     * directory; every other entry under `change/` is removed. The
+     * `removed` array lists entry names that were deleted (e.g.
+     * `['<oldSid>/']`); `created` is the name of the new marker (or
+     * `null` when the canonical marker already existed — no-op);
+     * `error` is the first error message (if any) encountered during
+     * the sync. Additive — older consumers can ignore this field.
+     * Replaces the F3 `changeLinks` field.
+     */
+    changeMarker: {
+        removed: string[];
+        created: string | null;
+        error: string | null;
+    };
+    /**
+     * Slice 006: list of absolute paths to `.peaks/_runtime/<sid>/system/`
+     * subdirs that were removed by this reconcile run. The F3
+     * `initWorkspace` eagerly created the `system/` subdir; slice 006
+     * deletes it during reconcile. Empty when the canonical session
+     * had no `system/` subdir. Additive.
+     */
+    systemCleaned: string[];
 };
 export type ReconcileOptions = {
     projectRoot: string;

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

@@ -8,6 +8,15 @@ export type WorkspaceInitOptions = {
      * — the CLI surfaces this as `--allow-session-rebind`.
      */
     allowSessionRebind?: boolean;
+    /**
+     * Optional change-id to bind as the active unit of work. When set,
+     * `peaks workspace init` also writes a `.peaks/_runtime/current-change`
+     * symlink pointing at `.peaks/<changeId>/`, so RD/QA/PRD services
+     * know which `<change-id>` directory to write reviewable artifacts
+     * into. The session id is still the binding for ephemeral state
+     * (live sub-agent progress, spawn records).
+     */
+    changeId?: string;
 };
 export type WorkspaceInitReport = {
     sessionId: string;
@@ -16,6 +25,8 @@ export type WorkspaceInitReport = {
     alreadyExisted: string[];
     bound: boolean;
     previousSessionId: string | null;
+    changeId: string | null;
+    changeIdAction: 'bound' | 'preserved' | 'none';
 };
 export declare class InvalidSessionIdError extends Error {
     readonly code = "INVALID_SESSION_ID";

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

@@ -1,20 +1,8 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isDirectory } from '../../shared/fs.js';
-import { getSessionId, setCurrentSessionBinding } from '../session/session-manager.js';
-const SUBDIRECTORIES = [
-    'prd/source',
-    'prd/requests',
-    'ui/requests',
-    'rd/requests',
-    'qa/test-cases',
-    'qa/test-reports',
-    'qa/requests',
-    'qa/screenshots',
-    'sc',
-    'txt',
-    'system'
-];
+import { getSessionId, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
+import { setCurrentChangeId } from '../../shared/change-id.js';
 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>
@@ -61,9 +49,33 @@ export function validateSessionId(sessionId) {
 }
 export async function initWorkspace(options) {
     validateSessionId(options.sessionId);
-    const sessionRoot = join(options.projectRoot, '.peaks', options.sessionId);
+    // Phase 6 refactor (slice 2026-06-05-change-id-as-unit-of-work) +
+    // slice 006 (2026-06-06-change-folder-simplify-and-lazy-role-subdirs):
+    //   - Reviewable artifacts (rd/, qa/, prd/, txt/) live at
+    //     `.peaks/<change-id>/<role>/` (tracked in git) when a change-id
+    //     is given. The role subdirs are NOT pre-created — the writer
+    //     (e.g. `peaks request init`, `peaks rd`) creates the parent
+    //     dirs on demand via `mkdirSync(..., { recursive: true })`.
+    //   - The session dir `.peaks/_runtime/<session-id>/` (gitignored)
+    //     now holds ONLY the canonical `session.json` metadata. The
+    //     F3-introduced `system/` subdir is gone — slice 006 removes
+    //     it via `peaks workspace reconcile`; new init calls do not
+    //     pre-create it.
+    //   - The change-id dir is created when `--change-id` is given,
+    //     but its role subdirs (prd/, qa/, rd/, sc/, txt/) are NOT
+    //     pre-created either — same lazy-mkdir rule.
+    //
+    // The CLI accepts `--change-id <id>` to bind the change. The legacy
+    // session-scoped layout (`.peaks/<session-id>/<role>/<file>`) is
+    // no longer used by writes; pre-1.3.1 trees get their session
+    // files migrated to the change-id dir by `peaks workspace reconcile`.
+    const runtimeRoot = join(options.projectRoot, '.peaks', '_runtime');
+    const sessionRoot = join(runtimeRoot, options.sessionId);
     const created = [];
     const alreadyExisted = [];
+    // 1. Create the session dir (canonical location `.peaks/_runtime/<sid>/`)
+    //    with NO subdirs. The session dir is gitignored; the role
+    //    subdirs and the `system/` subdir are gone entirely (slice 006).
     if (await isDirectory(sessionRoot)) {
         alreadyExisted.push('.');
     }
@@ -71,17 +83,43 @@ export async function initWorkspace(options) {
         await mkdir(sessionRoot, { recursive: true });
         created.push('.');
     }
-    for (const sub of SUBDIRECTORIES) {
-        const full = join(sessionRoot, sub);
-        if (await isDirectory(full)) {
-            alreadyExisted.push(sub);
+    // 1a. Write the per-session metadata file. Slice 006 makes
+    //     `.peaks/_runtime/<sid>/session.json` the durable session
+    //     metadata (the body's source of truth, the `peaks workspace
+    //     reconcile` discovery source). The file is created on first
+    //     init and refreshed on every subsequent init. Idempotent.
+    setSessionMeta(options.projectRoot, options.sessionId, {});
+    // 2. If a change-id is given, also create the change-id dir at
+    //    `.peaks/<change-id>/` (tracked) with NO role subdirs. The
+    //    role subdirs (prd/, qa/, rd/, sc/, txt/) are created on demand
+    //    by the writer at the write site. When the caller did NOT
+    //    specify a change-id, this step is skipped — reviewable writes
+    //    for this session are then blocked until a change-id is bound
+    //    (or the user re-runs init with `--change-id`). Surfaces in
+    //    `changeIdAction: 'none'`.
+    let resolvedChangeId = null;
+    let changeIdAction = 'none';
+    if (options.changeId !== undefined && options.changeId.length > 0) {
+        resolvedChangeId = options.changeId;
+        const changeDir = join(options.projectRoot, '.peaks', resolvedChangeId);
+        if (await isDirectory(changeDir)) {
+            alreadyExisted.push(resolvedChangeId);
         }
         else {
-            await mkdir(full, { recursive: true });
-            created.push(sub);
+            await mkdir(changeDir, { recursive: true });
+            created.push(resolvedChangeId);
         }
+        // 3. Bind the change-id so RD/QA/PRD services know where to write
+        //    reviewable artifacts. The binding is a symlink at
+        //    `.peaks/_runtime/current-change` pointing at the change-id dir.
+        setCurrentChangeId(options.projectRoot, resolvedChangeId);
+        changeIdAction = 'bound';
+    }
+    else if (options.changeId !== undefined && options.changeId.length === 0) {
+        // Empty string — same as undefined; treat as no change-id.
+        changeIdAction = 'none';
     }
-    // Bind this session as the project's current one.
+    // 4. Bind this session as the project's current one.
     //
     // Single source of truth: `peaks workspace init` is the only CLI entry point
     // that takes an explicit --session-id, so it owns the binding to .session.json.
@@ -112,7 +150,7 @@ export async function initWorkspace(options) {
         // etc.) regardless of whether the per-session metadata file is present.
         // Refuse to rebind without explicit authorization.
         previousSessionId = existingSessionId;
-        const existingSessionDir = join(options.projectRoot, '.peaks', existingSessionId);
+        const existingSessionDir = join(runtimeRoot, existingSessionId);
         if (await isDirectory(existingSessionDir) && !options.allowSessionRebind) {
             const { readdirSync } = await import('node:fs');
             const entries = readdirSync(existingSessionDir);
@@ -127,5 +165,14 @@ export async function initWorkspace(options) {
         setCurrentSessionBinding(options.projectRoot, options.sessionId);
         bound = true;
     }
-    return { sessionId: options.sessionId, sessionRoot, created, alreadyExisted, bound, previousSessionId };
+    return {
+        sessionId: options.sessionId,
+        sessionRoot,
+        created,
+        alreadyExisted,
+        bound,
+        previousSessionId,
+        changeId: resolvedChangeId,
+        changeIdAction
+    };
 }