peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/cli/commands/workspace/init-command.js

@@ -0,0 +1,505 @@
+/**
+ * `peaks workspace init` — slice 006 + 007 + 014 + 018 + 2026-06-16-peaks-code-auto-scaffold.
+ *
+ * Extracted from `src/cli/commands/workspace-commands.ts` (slice
+ * 2026-06-16-workspace-commands-split) to keep that entry file under the
+ * 800-line Karpathy cap. Owns:
+ *   - commander option wiring (`--project`, `--session-id`, `--change-id`, etc.)
+ *   - canonical project-root resolution
+ *   - session id resolution (with slice-018 rotation)
+ *   - first-time hooks install prompt + sticky marker
+ *   - missing-standards diagnostic surface (AC1-AC7) and `--init-standards` apply
+ *
+ * Imports the shared hooks-decision marker helpers from `./helpers.ts`.
+ */
+import { initWorkspace, InvalidSessionIdError, ConflictingSessionError, LegacyChangeIdSiblingError } from '../../../services/workspace/workspace-service.js';
+// Slice 2026-06-29-change-id-root-removal: `LegacyChangeIdBindingError`
+// was removed with the change-id axis. The legacy symlink-detection
+// branch below no longer fires — the binding file at
+// `.peaks/_runtime/current-change` is no longer written by init
+// either. The sibling-dir guard (`LegacyChangeIdSiblingError`) is
+// preserved because the 2.8.3 hard-ban still applies to date-stamped
+// session-id-shaped directories at the `.peaks/_runtime/` sibling
+// level.
+import { ensureSessionWithRotation } from '../../../services/session/session-manager.js';
+import { resolveCanonicalProjectRoot } from '../../../services/config/config-service.js';
+import { applyHookInstall, readHookStatus } from '../../../services/skills/hooks-settings-service.js';
+import { clearStalePresenceOnRotation } from '../../../services/skills/skill-presence-service.js';
+import { fail, ok } from '../../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+import { hasStandardsCheckedMarker, markStandardsChecked } from '../../../services/standards/missing-standards-detector.js';
+import { bootstrapProjectScan } from '../../../services/prd/project-scan-bootstrap-service.js';
+import { readDecisionMarker, writeDecisionMarker, promptYesNo } from './helpers.js';
+export function registerWorkspaceInitCommand(workspace, io) {
+    addJsonOption(workspace
+        .command('init')
+        .description('Create the .peaks/_runtime/<session-id>/ directory with ONLY the session.json metadata file (slice 006: role subdirs prd/ui/rd/qa/sc/txt and the system/ subdir are created lazily by writers, not pre-created at init). Pass --session-id to use a specific id, or omit it to auto-generate one (and adopt an existing binding if present). On the first call for a project, also handles the one-time "install peaks hooks" decision (sticky-marker stored in .peaks/.peaks-init-hooks-decision.json).')
+        .requiredOption('--project <path>', 'target project root')
+        .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)
+        .option('--no-rotate-on-outer-mismatch', 'suppress the auto-rotation of the project session binding when the outer (Claude / harness) session id has changed. Default rotates on mismatch.')
+        .option('--install-hooks <mode>', 'first-time hooks install behaviour: ask (default in TTY, prompt once + sticky-marker), auto (default in --json / non-TTY, install silently + sticky-marker), skip (sticky-marker skipped, do not install)', (value) => {
+        if (value !== 'ask' && value !== 'auto' && value !== 'skip') {
+            throw new Error(`--install-hooks must be one of: ask, auto, skip (got "${value}")`);
+        }
+        return value;
+    })
+        .option('--no-claude-hooks', 'do NOT materialize .claude/settings.local.json (slice 2.0.1-bug3 fact-forcing bypass). Default: hooks installed so tool calls inside .peaks/** are not blocked by the [Fact-Forcing Gate].')
+        .option('--init-standards', 'slice 2026-06-16-peaks-code-auto-scaffold: when the consumer project\'s .claude/rules/ is missing or empty, auto-apply `peaks standards init --project <path> --apply` after emitting the diagnostic. Default: diagnostic only (no write).')
+        .option('--no-project-scan-bootstrap', 'slice 2026-07-15-project-scan-bootstrap: skip the bootstrap of .peaks/project-scan/{project-scan.md + 4 audit/business templates} that runs after init succeeds. Default: bootstrap runs (idempotent: existing files are kept unless --force-project-scan-templates is also passed).')
+        .option('--force-project-scan-templates', 'slice 2026-07-15-project-scan-bootstrap (AC10): overwrite the 4 audit/business templates under .peaks/project-scan/ (business-knowledge.md, security-template.md, perf-template.md, audit-output-schema.md) even when they already exist. Default: skip existing files (sediment-preserved).', false)).action(async (options) => {
+        try {
+            // 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
+            //     .peaks/_runtime/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);
+            // Slice 018: outer-session-mismatch auto-rotation. When the
+            // user did NOT pass --session-id explicitly, run
+            // `ensureSessionWithRotation` so the binding is rotated on
+            // outer-mismatch before `initWorkspace` is called. The
+            // rotation result is surfaced in the JSON envelope via
+            // `data.rotation`. When --session-id IS passed, the user has
+            // explicitly told us which session to bind — we honor that
+            // verbatim and do NOT rotate (rotation only fires for the
+            // auto-detect path).
+            let sessionId;
+            let rotation = {
+                previousSessionId: null,
+                reason: null
+            };
+            if (options.sessionId !== undefined && options.sessionId.length > 0) {
+                sessionId = options.sessionId;
+            }
+            else {
+                const result = await ensureSessionWithRotation(projectRoot, {
+                    // Commander translates `--no-rotate-on-outer-mismatch` into
+                    // `options.rotateOnOuterMismatch = false` (the `--no-` prefix
+                    // is consumed and the remainder becomes the JS property name,
+                    // with the boolean value flipped). The pre-slice-014 anti-
+                    // pattern (reading `options.<flag-with-no-prefix> === true`)
+                    // is NOT used here. The default (no flag) leaves
+                    // `options.rotateOnOuterMismatch` undefined, which is not
+                    // equal to `false`, so the default is "rotate on mismatch"
+                    // (the new auto-roll).
+                    skipRotateOnOuterMismatch: options.rotateOnOuterMismatch === false
+                });
+                sessionId = result.sessionId;
+                rotation = {
+                    previousSessionId: result.previousSessionId,
+                    reason: result.rotationReason
+                };
+            }
+            const report = await initWorkspace({
+                projectRoot,
+                sessionId,
+                allowSessionRebind: options.allowSessionRebind === true,
+                // Commander translates `--no-claude-hooks` into
+                // `options.claudeHooks = false`. The default (no flag) leaves
+                // `options.claudeHooks` undefined, which is not equal to
+                // `false`, so the default is "install hooks" (the bypass is
+                // on). Pass `--no-claude-hooks` to opt out.
+                noClaudeHooks: options.claudeHooks === false,
+                // Slice 2026-06-16-peaks-code-auto-scaffold (RD#7): opt-in
+                // auto-apply for the missing-standards scaffold. Default false
+                // — only the diagnostic is emitted. Pass --init-standards to
+                // also run `executeProjectStandardsInit({ apply: true })`.
+                initStandards: options.initStandards === true
+            });
+            // Slice 2026-07-15-project-scan-bootstrap (G2 / G4b / AC9):
+            // After the workspace dir is initialized, also bootstrap the
+            // `.peaks/project-scan/` artifact tree (project-scan.md + 4
+            // bundled audit/business templates). Idempotent — when the user
+            // re-runs `workspace init`, the existing files are kept (their
+            // sediment is user-authored). Pass `--no-project-scan-bootstrap`
+            // to skip, or `--force-project-scan-templates` to overwrite the
+            // 4 bundled templates anyway.
+            let projectScanEnvelope = null;
+            let projectScanError = null;
+            if (options.projectScanBootstrap === false) {
+                // Explicit opt-out. The envelope stays null; the JSON
+                // response carries `projectScan: { skipped: true, ... }` so
+                // callers can distinguish "skipped by flag" from "skipped by
+                // idempotency".
+                projectScanEnvelope = {
+                    created: false,
+                    skipped: true,
+                    templatesBooted: 0,
+                    templatesSkipped: 0,
+                    projectScanPath: `${projectRoot}/.peaks/project-scan/project-scan.md`,
+                    durationMs: 0
+                };
+            }
+            else {
+                try {
+                    projectScanEnvelope = await bootstrapProjectScan({
+                        projectRoot,
+                        ...(options.forceProjectScanTemplates === true ? { forceTemplates: true } : {})
+                    });
+                }
+                catch (error) {
+                    // Don't fail init over a project-scan issue — the workspace
+                    // is already initialized and the user has the JSON envelope.
+                    // Surface the failure as a warning so the LLM can decide.
+                    projectScanError = getErrorMessage(error);
+                }
+            }
+            const nextActions = [];
+            if (report.previousSessionId !== null && report.bound) {
+                nextActions.push(`Replaced prior session binding "${report.previousSessionId}" with "${report.sessionId}".`);
+            }
+            if (rotation.previousSessionId !== null && rotation.reason === 'outer-session-mismatch') {
+                // Outer-session-mismatch rotation: the previous Claude / harness
+                // session is no longer the LLM driver. The new binding is fresh,
+                // the old session dir is preserved on disk.
+                nextActions.push(`Auto-rotated session binding: outer session id changed (was "${rotation.previousSessionId}"). ` +
+                    `New binding is "${sessionId}". The previous session dir is preserved at .peaks/_runtime/${rotation.previousSessionId}/. ` +
+                    `Re-run with --no-rotate-on-outer-mismatch to suppress this rotation.`);
+                // Slice 002 (v2.15.0) AC-1: a presence marker stamped by the
+                // OLD outer session is now stale (defect A from the PRD).
+                // peaks-code Step 1 would otherwise pick up the old `mode`
+                // field and silently lock the new session into a mode the
+                // user never explicitly chose. Clear it here so Step 1's
+                // presence:check-stale reports `reason: 'no-presence'` and
+                // the re-ask fires.
+                const presenceClearOutcome = clearStalePresenceOnRotation({
+                    projectRootOverride: projectRoot,
+                    currentOuterSessionId: process.env.PEAKS_OUTER_SESSION_ID
+                        ?? process.env.CLAUDE_CODE_SESSION_ID,
+                    rotatedOutSessionId: rotation.previousSessionId
+                });
+                if (presenceClearOutcome.cleared) {
+                    nextActions.push(`Auto-cleared stale skill presence (recorded outer id "${presenceClearOutcome.recordedOuter ?? '?'}" did not match the new outer session). ` +
+                        'peaks-code Step 1 will now AskUserQuestion to confirm the mode.');
+                }
+                else if (presenceClearOutcome.reason === 'recorded-by-different-outer') {
+                    nextActions.push(`Kept skill presence: it was recorded by a different live outer session (id "${presenceClearOutcome.recordedOuter ?? '?'}"). ` +
+                        'The new outer session will not auto-clear it.');
+                }
+                else if (presenceClearOutcome.reason === 'not-stale') {
+                    nextActions.push('Kept skill presence: it was re-stamped by the new outer session during the rotation window (not stale).');
+                }
+            }
+            if (report.created.length === 0) {
+                nextActions.push('Workspace already initialized — proceed to project scan.');
+            }
+            else {
+                nextActions.push('Run `peaks scan archetype --project <path> --json` next to populate rd/project-scan.md.');
+            }
+            // Slice 2.0.1-bug3-fact-forcing-bypass: surface the consumer-
+            // project .claude/settings.local.json materialization outcome.
+            // When the bypass is in effect, the LLM knows subsequent Writes
+            // and Bash calls targeting .peaks/** will not be blocked by the
+            // [Fact-Forcing Gate]. When the user opted out, we surface a
+            // nextAction so the manual recovery is documented.
+            if (report.claudeSettings.action === 'written' || report.claudeSettings.action === 'refreshed') {
+                nextActions.push(`Materialized .claude/settings.local.json (action: ${report.claudeSettings.action}) — ` +
+                    `the [Fact-Forcing Gate] is bypassed for tool calls inside .peaks/**. ` +
+                    'Restart Claude Code so the hooks take effect.');
+            }
+            else if (report.claudeSettings.action === 'already-current') {
+                // No-op: the bypass is already in effect and matches the
+                // current release. Do not spam the nextAction list on every
+                // init.
+            }
+            else if (report.claudeSettings.action === 'skipped') {
+                nextActions.push('Skipped .claude/settings.local.json materialization (--no-claude-hooks). ' +
+                    'If the [Fact-Forcing Gate] blocks subsequent Writes, run `peaks workspace init` ' +
+                    'again without --no-claude-hooks, or drop the contents of ' +
+                    '`.peaks/.claude-settings-template.json` into `.claude/settings.local.json` manually.');
+            }
+            // Slice 2026-06-13-selfheal-claude-settings-template: surface
+            // the self-heal outcome for the offline
+            // `.peaks/.claude-settings-template.json` copy. When the offline
+            // file was refreshed (i.e. the previous peaks-loop release left
+            // a stale version without the `node -e "..."` wrapper), the user
+            // benefits from seeing that the manual-recovery anchor now
+            // points at the corrected template. We surface `written` and
+            // `refreshed` as the actionable events; `already-current` is
+            // silent (same rationale as the consumer-project no-op above).
+            //
+            // The `refreshed` nextAction also carries a loud warning that any
+            // MANUAL EDITS the user made to the offline template have been
+            // overwritten — drift detection cannot tell stale-from-prior-release
+            // apart from user-customised, so we surface the warning unconditionally
+            // to make sure anyone who customised sees the prompt.
+            if (report.claudeSettings.offlineTemplate.action === 'refreshed') {
+                nextActions.push(`Self-healed .peaks/.claude-settings-template.json (action: refreshed) — ` +
+                    'the offline recovery anchor now matches the current peaks-loop template. ' +
+                    'No action required; future manual recoveries will copy the corrected wrapper.');
+                nextActions.push('⚠️  If you had manually edited .peaks/.claude-settings-template.json, ' +
+                    'those edits have been overwritten by the self-heal. ' +
+                    'Re-apply your custom matchers / commands on top of the freshly-written template, ' +
+                    'or open an issue if your customisation is a recurring need (the team may promote it to the canonical template).');
+            }
+            else if (report.claudeSettings.offlineTemplate.action === 'written') {
+                nextActions.push(`Wrote .peaks/.claude-settings-template.json (action: written) — ` +
+                    'the offline recovery anchor is now in place for future manual recoveries.');
+            }
+            // Slice 2026-07-15-project-scan-bootstrap (G2): surface the
+            // bootstrap outcome. The envelope carries the write counts and
+            // duration so the LLM (and the human) see what landed. The
+            // nextAction only fires when the project-scan tree is fresh —
+            // idempotent re-runs are silent to keep the nextAction list
+            // scannable.
+            // (deferred until after warningsForEnvelope is declared below)
+            // First-time hooks install decision. Sticky-marker at
+            // .peaks/.peaks-init-hooks-decision.json records the user's answer
+            // (or the auto-decision) so subsequent inits for new sessions in the
+            // same project do not re-prompt. The marker is the only state that
+            // survives across sessions — without it, every new session would
+            // re-trigger the question.
+            const hooksOutcome = await resolveFirstTimeHooksInstall({
+                projectRoot,
+                ...(options.installHooks !== undefined ? { explicitMode: options.installHooks } : {}),
+                jsonMode: options.json === true
+            });
+            if (hooksOutcome.decision === 'installed') {
+                nextActions.push(hooksOutcome.action === 'reinstalled'
+                    ? 'Re-installed the peaks-managed PreToolUse hooks (Bash→gate enforce, Task→progress start) — the marker said installed but the hooks were missing.'
+                    : 'Installed the peaks-managed PreToolUse hooks (Bash→gate enforce, Task→progress start). Restart Claude Code so the hooks take effect.');
+            }
+            else if (hooksOutcome.action === 'first-decision' && hooksOutcome.decision === 'skipped') {
+                nextActions.push('Skipped peaks-managed hook install for this project. Re-run with --install-hooks=auto (or peaks hooks install) to install later.');
+            }
+            // Slice 2026-06-16-peaks-code-auto-scaffold (RD#7):
+            //   - When the consumer project's `.claude/rules/` is missing or
+            //     empty, emit the copy-pasteable diagnostic to stderr (via
+            //     the JSON envelope `warnings` array) AND surface the
+            //     structured descriptor in `data.standardsMissing`.
+            //   - AC7: skip the diagnostic banner on subsequent invocations
+            //     within the same session — the once-per-session marker
+            //     `.peaks/_runtime/<sid>/.standards-checked` is written after
+            //     the FIRST diagnostic emit.
+            //   - AC3: when --init-standards was passed and the detector
+            //     reported missing, `report.standardsApplied` already lists the
+            //     freshly-written files. Surface that as a nextAction so the
+            //     human sees what was written.
+            const warningsForEnvelope = [];
+            if (report.standardsMissing.missing && !hasStandardsCheckedMarker(projectRoot, sessionId)) {
+                warningsForEnvelope.push(report.standardsMissing.remediation);
+                nextActions.push(`Run \`peaks workspace init --init-standards --project ${projectRoot}\` to auto-apply the scaffold, or \`peaks standards init --project ${projectRoot} --apply\` manually.`);
+            }
+            if (report.standardsApplied !== undefined) {
+                nextActions.push(`Auto-applied .claude/rules/${report.standardsApplied.language}/ scaffold (slice 2026-06-16-peaks-code-auto-scaffold): ` +
+                    `wrote ${report.standardsApplied.writtenFiles.length} file(s), ` +
+                    `kept ${report.standardsApplied.skippedFiles.length} existing file(s).`);
+            }
+            // Slice 2026-07-15-project-scan-bootstrap (G2): surface the
+            // bootstrap outcome. The envelope carries the write counts and
+            // duration so the LLM (and the human) see what landed. The
+            // nextAction only fires when the project-scan tree is fresh —
+            // idempotent re-runs are silent to keep the nextAction list
+            // scannable.
+            if (projectScanError !== null) {
+                warningsForEnvelope.push(`project-scan bootstrap failed: ${projectScanError}`);
+            }
+            else if (projectScanEnvelope !== null && projectScanEnvelope.created) {
+                nextActions.push(`Bootstrapped .peaks/project-scan/ (project-scan.md + 4 audit/business templates) — ` +
+                    `${projectScanEnvelope.templatesBooted} file(s) written, ${projectScanEnvelope.templatesSkipped} preserved. ` +
+                    `Run \`peaks scan archetype --project ${projectRoot}\` and \`peaks scan libraries --project ${projectRoot}\` next to refresh the scan.`);
+            }
+            // Write the once-per-session marker AFTER the envelope is built
+            // (so subsequent inits skip the warning even on rapid back-to-back
+            // calls).
+            if (report.standardsMissing.missing) {
+                markStandardsChecked(projectRoot, sessionId);
+            }
+            printResult(io, ok('workspace.init', {
+                ...report,
+                // Slice 018: surface outer-session-mismatch rotation in the
+                // JSON envelope so the LLM and the human both see the swap.
+                // Field is omitted (not null) when no rotation fired.
+                ...(rotation.previousSessionId !== null && rotation.reason !== null
+                    ? { rotation: { previousSessionId: rotation.previousSessionId, reason: rotation.reason } }
+                    : {}),
+                hooksInstall: {
+                    decision: hooksOutcome.decision,
+                    action: hooksOutcome.action,
+                    scope: hooksOutcome.scope,
+                    ...(hooksOutcome.reason !== undefined ? { reason: hooksOutcome.reason } : {})
+                },
+                // Slice 2026-07-15-project-scan-bootstrap (G2): envelope
+                // for the .peaks/project-scan/ bootstrap. Always present
+                // (even when skipped / errored) so downstream readers can
+                // rely on the shape.
+                ...(projectScanEnvelope !== null
+                    ? { projectScan: { ...projectScanEnvelope, ...(projectScanError !== null ? { error: projectScanError } : {}) } }
+                    : {})
+            }, warningsForEnvelope, nextActions), options.json);
+        }
+        catch (error) {
+            if (error instanceof InvalidSessionIdError) {
+                printResult(io, fail('workspace.init', error.code, error.message, { sessionId: options.sessionId }, ['Use a date-prefixed kebab slug like 2026-05-25-add-user-auth']), options.json);
+                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;
+            }
+            if (error instanceof LegacyChangeIdSiblingError) {
+                // Slice 2.8.3: a 2.8.0-era orphan `.peaks/_runtime/<change-id>/` was
+                // found at top level. The CLI surfaces the migration steps
+                // verbatim from the error message plus three concrete
+                // nextActions so the user (or LLM driver) has an unambiguous
+                // recovery path. We do NOT auto-migrate because the legacy
+                // sibling dir may contain user-authored content.
+                printResult(io, fail('workspace.init', error.code, error.message, {
+                    sessionId: error.sessionId,
+                    legacyPath: error.legacyPath
+                }, [
+                    `Inspect ${error.legacyPath} for any user-authored content you want to keep.`,
+                    `Move any desired files into .peaks/_runtime/<sessionId>/<role>/ (gitignored), then delete ${error.legacyPath}.`,
+                    `Re-run \`peaks workspace init --project <path>\` to bind a fresh session.`
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            // Slice 2026-06-29-change-id-root-removal: the
+            // `LegacyChangeIdBindingError` catch branch is gone — the change-id
+            // binding file at `.peaks/_runtime/current-change` is no longer
+            // written by init, so there is no legacy binding to detect.
+            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;
+        }
+    });
+}
+/**
+ * Resolve the first-time "install peaks hooks" decision for this project.
+ * Decision tree:
+ *
+ *   1. Read the sticky marker.
+ *      - Marker present:
+ *        - marker.decision === 'installed' AND hooks are present → action: marker-honored, no side effects
+ *        - marker.decision === 'installed' AND hooks are MISSING   → re-install, action: reinstalled
+ *        - marker.decision === 'skipped'                            → action: marker-honored, no install
+ *      - Marker absent:
+ *        - hooks already present → write a fresh 'installed' marker, action: already-installed
+ *        - otherwise:
+ *          - explicit --install-hooks=auto  → install + marker, action: first-decision
+ *          - explicit --install-hooks=skip  → marker only, action: first-decision
+ *          - explicit --install-hooks=ask OR default in TTY:
+ *              - jsonMode → silently auto-install (LLM cannot answer), action: first-decision
+ *              - TTY      → prompt; on yes install + marker, on no marker-only
+ *          - default in non-TTY → auto-install, action: first-decision
+ *
+ * Project scope is the only supported scope here; global scope is reserved
+ * for explicit `peaks hooks install --global` invocations.
+ */
+export async function resolveFirstTimeHooksInstall(options) {
+    const { projectRoot, jsonMode } = options;
+    const existingMarker = readDecisionMarker(projectRoot);
+    // readHookStatus can throw (e.g. .claude is a symlink → safety check rejects).
+    // Treat any throw as "hooks status unknown → treat as not-installed" so the
+    // function still reaches the install path; the install will surface the same
+    // error in a more specific reason field.
+    let hookStatus;
+    try {
+        hookStatus = readHookStatus('project', projectRoot);
+    }
+    catch (error) {
+        hookStatus = { installed: false };
+        // Fall through to the install path; the failure will be captured below.
+        void error;
+    }
+    if (existingMarker !== null) {
+        if (existingMarker.decision === 'installed' && !hookStatus.installed) {
+            try {
+                applyHookInstall('project', projectRoot);
+                return { decision: 'installed', action: 'reinstalled', scope: 'project', reason: 'marker-said-installed-hooks-missing' };
+            }
+            catch (error) {
+                return { decision: existingMarker.decision, action: 'marker-honored', scope: 'project', reason: `reinstall-failed: ${getErrorMessage(error)}` };
+            }
+        }
+        return { decision: existingMarker.decision, action: 'marker-honored', scope: existingMarker.scope };
+    }
+    // No marker yet — first decision.
+    if (hookStatus.installed) {
+        writeDecisionMarker(projectRoot, 'installed');
+        return { decision: 'installed', action: 'already-installed', scope: 'project' };
+    }
+    // Determine effective mode (explicit flag wins; default depends on TTY + jsonMode).
+    const explicitMode = options.explicitMode;
+    const effectiveMode = explicitMode ??
+        (jsonMode ? 'auto' : (process.stdin.isTTY === true ? 'ask' : 'auto'));
+    if (effectiveMode === 'skip') {
+        writeDecisionMarker(projectRoot, 'skipped');
+        return { decision: 'skipped', action: 'first-decision', scope: 'project', reason: 'explicit-skip' };
+    }
+    if (effectiveMode === 'auto' || jsonMode) {
+        // The reason code distinguishes the path the user took to reach auto-install:
+        //   - explicit-auto:  user passed --install-hooks=auto
+        //   - json-mode:      no --install-hooks flag, but --json was set
+        //   - non-tty-default: no flag, no --json, stdin is not a TTY
+        let autoReason;
+        if (explicitMode === 'auto') {
+            autoReason = 'explicit-auto';
+        }
+        else if (jsonMode) {
+            autoReason = 'json-mode';
+        }
+        else {
+            autoReason = 'non-tty-default';
+        }
+        try {
+            applyHookInstall('project', projectRoot);
+            writeDecisionMarker(projectRoot, 'installed');
+            return { decision: 'installed', action: 'first-decision', scope: 'project', reason: autoReason };
+        }
+        catch (error) {
+            // Auto-install failed: still record the decision so we do not keep retrying
+            // every workspace init. The user can fix the underlying problem and run
+            // `peaks hooks install` manually.
+            writeDecisionMarker(projectRoot, 'installed');
+            return { decision: 'installed', action: 'first-decision', scope: 'project', reason: `install-failed: ${getErrorMessage(error)}` };
+        }
+    }
+    // effectiveMode === 'ask' AND TTY: prompt once.
+    process.stderr.write('\nPeaks-Cli: install the PreToolUse hooks for this project now?\n' +
+        '  → Bash matcher: `peaks gate enforce` (SOP gate enforcement)\n' +
+        'The gate-enforce hook runs on every Claude Code tool call without further prompting. The decision is sticky\n' +
+        '(recorded in .peaks/.peaks-init-hooks-decision.json) and re-runs of `workspace init` will\n' +
+        'honour it. Re-run with --install-hooks=skip or --install-hooks=auto to override.\n\n' +
+        'Install now? [Y/n]: ');
+    const answer = await promptYesNo('');
+    if (answer === null) {
+        // TTY disappeared mid-prompt (rare): treat as skip + write marker.
+        writeDecisionMarker(projectRoot, 'skipped');
+        return { decision: 'skipped', action: 'first-decision', scope: 'project', reason: 'tty-prompt-aborted' };
+    }
+    if (!answer) {
+        writeDecisionMarker(projectRoot, 'skipped');
+        return { decision: 'skipped', action: 'first-decision', scope: 'project', reason: 'user-answered-no' };
+    }
+    try {
+        applyHookInstall('project', projectRoot);
+        writeDecisionMarker(projectRoot, 'installed');
+        return { decision: 'installed', action: 'first-decision', scope: 'project', reason: 'user-answered-yes' };
+    }
+    catch (error) {
+        writeDecisionMarker(projectRoot, 'installed');
+        return { decision: 'installed', action: 'first-decision', scope: 'project', reason: `install-failed: ${getErrorMessage(error)}` };
+    }
+}

package/dist/cli/commands/workspace/migrate-command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `peaks workspace migrate` — slice 003 (--to-runtime).
+ *
+ * Extracted from `src/cli/commands/workspace-commands.ts` (slice
+ * 2026-06-16-workspace-commands-split) to keep that entry file under the
+ * 800-line Karpathy cap. Migrates legacy `.peaks/_runtime/<sid>/<role>/<file>`
+ * into the new `.peaks/retrospective/<change-id>/<role>/<file>` layout.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export declare function registerWorkspaceMigrateCommand(workspace: Command, io: ProgramIO): void;

package/dist/cli/commands/workspace/migrate-command.js

@@ -0,0 +1,91 @@
+/**
+ * `peaks workspace migrate` — slice 003 (--to-runtime).
+ *
+ * Extracted from `src/cli/commands/workspace-commands.ts` (slice
+ * 2026-06-16-workspace-commands-split) to keep that entry file under the
+ * 800-line Karpathy cap. Migrates legacy `.peaks/_runtime/<sid>/<role>/<file>`
+ * into the new `.peaks/retrospective/<change-id>/<role>/<file>` layout.
+ */
+import { migrateWorkspace } from '../../../services/workspace/migrate-service.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 registerWorkspaceMigrateCommand(workspace, io) {
+    addJsonOption(workspace
+        .command('migrate')
+        .description('Migrate legacy `.peaks/_runtime/<session-id>/<role>/<file>` content into the new layout: ' +
+        '`.peaks/retrospective/<change-id>/<role>/<file>`. Each file is routed by a 4-tier ' +
+        'change-id resolver (filename regex → content H1 → body frontmatter → per-session fallback ' +
+        'to the most recent rd/requests entry). Cross-cutting files (project-scan, perf-baseline) ' +
+        'and transient runtime files (session.json, system/) are skipped with reasons in the ' +
+        'response. By default the command is a dry-run: it reports the planned moves + conflicts ' +
+        'and the session dirs that WOULD be deleted. Pass --apply to actually `git mv` the files ' +
+        'and `rm -rf` the emptied session dirs. Idempotent: re-running on an already-migrated tree ' +
+        'is a no-op (all files report conflicts with identical content).' +
+        '\n\nSlice 003 (--to-runtime): moves every top-level `.peaks/_runtime/<sid>/` to `.peaks/_runtime/<sid>/` ' +
+        'for projects still on the pre-runtime-layer layout. Idempotent: re-running on a tree ' +
+        'that is already canonical is a no-op. F15 carve-out: top-level `rd/project-scan.md` is ' +
+        'never overwritten when the runtime copy already exists with different content.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'actually `git mv` the files and delete the emptied session dirs (destructive); without it, dry-run only', false)
+        .option('--to-runtime', 'slice 003: also consolidate every top-level .peaks/_runtime/<sid>/ dir into .peaks/_runtime/<sid>/. Idempotent; conflicts are logged but never overwrite.', false)).action(async (options) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            const apply = options.apply === true;
+            const toRuntime = options.toRuntime === true;
+            const result = await migrateWorkspace({ projectRoot, apply, toRuntime });
+            const warnings = [];
+            if (result.sessions.length === 0 && (result.toRuntimePlans?.length ?? 0) === 0) {
+                warnings.push('No legacy session directories found under .peaks/. Nothing to migrate.');
+            }
+            else if (result.wouldMove.length === 0 && (result.toRuntimePlans?.length ?? 0) === 0) {
+                warnings.push('Legacy session dirs found but no reviewable content to migrate (all files were cross-cutting or transient).');
+            }
+            const nextActions = [];
+            if (!apply && result.wouldMove.length > 0) {
+                nextActions.push(`Re-run with --apply to perform ${result.wouldMove.length} move(s) and delete ${result.wouldDeleteSessions.length} session dir(s).`);
+            }
+            if (result.conflicts.length > 0) {
+                nextActions.push(`${result.conflicts.length} file(s) already exist at the target path; review before --apply (or re-run after a partial migrate).`);
+            }
+            if (toRuntime) {
+                const plans = result.toRuntimePlans ?? [];
+                if (apply) {
+                    if ((result.toRuntimeMoved?.length ?? 0) > 0) {
+                        nextActions.push(`Moved ${result.toRuntimeMoved?.length} top-level session dir(s) to .peaks/_runtime/ (slice 003 --to-runtime).`);
+                    }
+                    if ((result.toRuntimeConflicts?.length ?? 0) > 0) {
+                        nextActions.push(`${result.toRuntimeConflicts?.length} --to-runtime conflict(s) — see response. ${plans.filter((p) => p.action === 'f15-conflict-project-scan').length} are F15 carve-outs (deferred to a separate slice).`);
+                    }
+                }
+                else {
+                    const wouldMoveCount = plans.filter((p) => p.action === 'moved').length;
+                    const wouldSkipCount = plans.filter((p) => p.action === 'skipped-already-canonical').length;
+                    if (wouldMoveCount > 0) {
+                        nextActions.push(`Re-run with --apply to move ${wouldMoveCount} top-level session dir(s) to .peaks/_runtime/; ${wouldSkipCount} already canonical.`);
+                    }
+                    else if (wouldSkipCount > 0) {
+                        nextActions.push(`All ${wouldSkipCount} top-level session dir(s) are already canonical — no moves needed.`);
+                    }
+                    const f15Count = plans.filter((p) => p.action === 'f15-conflict-project-scan').length;
+                    if (f15Count > 0) {
+                        nextActions.push(`${f15Count} F15 carve-out conflict(s) (rd/project-scan.md differs from runtime copy) — see response.`);
+                    }
+                }
+            }
+            if (apply) {
+                if (result.moved.length > 0) {
+                    nextActions.push(`Migrated ${result.moved.length} file(s) into .peaks/retrospective/.`);
+                }
+                if (result.deletedSessions.length > 0) {
+                    nextActions.push(`Deleted ${result.deletedSessions.length} emptied session dir(s).`);
+                }
+            }
+            printResult(io, ok('workspace.migrate', result, warnings, nextActions), options.json ?? false);
+        }
+        catch (error) {
+            printResult(io, fail('workspace.migrate', 'WORKSPACE_MIGRATE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json ?? false);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/workspace/reconcile-command.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `peaks workspace reconcile` — slice 006 + slice 0.5.
+ *
+ * Extracted from `src/cli/commands/workspace-commands.ts` (slice
+ * 2026-06-16-workspace-commands-split) to keep that entry file under the
+ * 800-line Karpathy cap. Scans the legacy 2026-MM-DD-session dirs and
+ * consolidates the runtime state.
+ *
+ * Migration (1), repoint (2), and marker sync (3) always run regardless
+ * of `--apply`. Deletion of old session dirs is dry-run by default.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export declare function registerWorkspaceReconcileCommand(workspace: Command, io: ProgramIO): void;