peaks-loop 4.1.2 → 4.1.3

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

@@ -1,636 +1,72 @@
 /**
+ * `peaks workspace init` — the registrar.
  *
  * Extracted from `src/cli/commands/workspace-commands.ts` (slice
- * 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
+ * 800-line Karpathy cap). Split further by responsibility.
+ * The option/outcome shapes, the first-time hooks
+ * decision, project-root + session resolution, the nextAction/warning
+ * collectors, the codegraph stake, the envelope builder and the typed failure
+ * arms each live in their own module under `./`. This file wires them up.
  *
  * Imports the shared hooks-decision marker helpers from `./helpers.ts`.
  */
-import { initWorkspace, InvalidSessionIdError, ConflictingSessionError, LegacyChangeIdSiblingError } from '../../../services/workspace/workspace-service.js';
-// 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 { resolveWritableProjectRoot, UnsafeProjectRootError } from '../../../services/config/config-safety.js';
-import { applyHookInstall, readHookStatus } from '../../../services/skills/hooks-settings-service.js';
-import { clearStalePresenceOnRotation } from '../../../services/skills/skill-presence-service.js';
-import { gcStalePresenceLeases } from '../../../services/skills/presence-lease-service.js';
-import { createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, writeCodegraphMarker } from '../../../services/codegraph/codegraph-service.js';
-import { mkdirSync } from 'node:fs';
-import { fail, ok } from 'peaks-loop-shared/result';
-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.
-            // `resolveWritableProjectRoot` = `resolveCanonicalProjectRoot` plus the
-            // home-directory refusal. It has to be this one, and it has to run here:
-            // `ensureSessionWithRotation` below WRITES (it mints/binds a session), so
-            // a guard placed after it would leave a `.peaks/_runtime/` tree in the
-            // user's home even though the init was refused.
-            const projectRoot = resolveWritableProjectRoot(options.project);
-            // 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,
-                // 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
-            });
-            // 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.`);
-                // 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.');
-            }
-            // 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.');
-            }
-            // 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.');
-            }
-            //   - 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 = [];
-            // Slice 4.0.8 (D3): after session binding, run the same
-            // canonical GC sweep `peaks skill presence:set` would
-            // perform. A `peaks workspace init` is a natural sweep
-            // trigger (the session id was just minted, all prior leases
-            // for the project are by definition same-project). Failures
-            // surface as warnings; the GC never blocks init.
-            try {
-                const gcResult = await gcStalePresenceLeases({
-                    projectRoot,
-                    trigger: 'workspace-init'
-                });
-                if (gcResult.removed > 0) {
-                    warningsForEnvelope.push(`Stale lease sweep removed ${gcResult.removed} lease(s) for the canonical project (retained ${gcResult.retained}).`);
-                }
-            }
-            catch (err) {
-                warningsForEnvelope.push(`lease sweep failed: ${getErrorMessage(err)}`);
-            }
-            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).`);
-            }
-            // 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);
-            }
-            // directory after a successful workspace init. Calls the conflict
-            // silently overwritten. We now run a REAL upstream `codegraph init`
-            // (not just mkdir + marker) so the schema actually has a
-            // `codegraph.db`, which is what post-slice auto-refresh and the
-            // pre-dispatch preflight gate on. `codegraph init` (WITHOUT
-            // `--index`) is fast (~1 s) and offline-safe — it only `Parser.init()`s
-            // WASM grammars that resolve from node_modules; the slow/offline
-            // concern applies to `index` (full build), not `init`.
-            let codegraphAutoOutcome = null;
-            try {
-                const guard = defaultCodegraphInitGuard(projectRoot);
-                if (guard.status === 'fresh') {
-                    // 'fresh' here also covers the dangling state (marker present but
-                    // no codegraph.db) — running init self-heals both.
-                    const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }));
-                    if (initResult.exitCode !== 0) {
-                        warningsForEnvelope.push(`codegraph auto-stake init failed (exit ${String(initResult.exitCode)}). ` +
-                            'Run `peaks codegraph init --project <path>` manually to enable codegraph.');
-                    }
-                    else {
-                        // Upstream init creates `.codegraph/`; mkdir is a no-op in the
-                        // real path and lets the marker write succeed. Best-effort.
-                        mkdirSync(guard.codegraphDir, { recursive: true });
-                        writeCodegraphMarker(guard.codegraphDir);
-                        codegraphAutoOutcome = { status: 'fresh' };
-                        nextActions.push(`Auto-staked a peaks-loop-managed ${guard.codegraphDir}/ (upstream init + marker). ` +
-                            'Run `peaks codegraph index --project <path>` next to build the SQLite-backed index.');
-                    }
-                }
-                else if (guard.status === 'noop-already-peaks-loop') {
-                    codegraphAutoOutcome = { status: 'noop' };
-                }
-                else {
-                    codegraphAutoOutcome = { status: 'conflict' };
-                    warningsForEnvelope.push(`${guard.codegraphDir} already exists with a non-peaks-loop schema; ` +
-                        'refusing to auto-init codegraph. Run `peaks codegraph init --project <path>` after moving the foreign directory.');
-                }
-            }
-            catch (err) {
-                warningsForEnvelope.push(`codegraph auto-stake failed: ${getErrorMessage(err)}`);
-            }
-            printResult(io, ok('workspace.init', {
-                ...report,
-                // 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 } : {})
-                },
-                ...(codegraphAutoOutcome !== null ? { codegraphAutoStake: codegraphAutoOutcome } : {}),
-                // 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 UnsafeProjectRootError) {
-                // A typed refusal, not a crash: "you are standing in your home
-                // directory, which is not a project" is a thing the caller can fix in
-                // one step, and the envelope has to say which directory was refused and
-                // what to pass instead. `WORKSPACE_INIT_FAILED` below would have buried
-                // it as an unexplained failure.
-                printResult(io, fail('workspace.init', 'UNSAFE_PROJECT_ROOT', error.message, {
-                    resolvedProjectRoot: error.projectRoot,
-                    projectOption: options.project ?? null
-                }, [
-                    'Pass --project <path-to-your-project> instead of a path that resolves to your home directory.',
-                    'This command creates .peaks/, .gitignore, .claude/settings.local.json and a codegraph index; none of those belong in $HOME.',
-                    'If you meant to initialize the current directory, cd into a project directory first — peaks will not write into the home directory itself.'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            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;
-            }
-            // `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'
-        };
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../../cli-helpers.js';
+import { bootstrapProjectScanForInit, resolveInitTarget, runInitWorkspace } from './init-context.js';
+import { collectInitEnvelope } from './init-actions.js';
+import { buildInitEnvelopeData } from './init-envelope.js';
+import { reportWorkspaceInitFailure } from './init-failures.js';
+// Published import paths preserved: `workspace-commands.ts` (and tests) import
+// the hooks-decision primitive and its two types from this module.
+export { resolveFirstTimeHooksInstall } from './init-hooks-decision.js';
+const 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).';
+const INIT_PROJECT_HELP = 'target project root';
+const INIT_SESSION_HELP = '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.';
+const INIT_REBIND_HELP = 'overwrite an existing session binding when the requested session id differs from the project current one';
+const INIT_NO_ROTATE_HELP = 'suppress the auto-rotation of the project session binding when the outer (Claude / harness) session id has changed. Default rotates on mismatch.';
+const INIT_INSTALL_HOOKS_HELP = '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)';
+const INIT_NO_CLAUDE_HOOKS_HELP = '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].';
+const INIT_INIT_STANDARDS_HELP = "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).";
+const INIT_NO_PROJECT_SCAN_HELP = '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).';
+const INIT_FORCE_TEMPLATES_HELP = '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).';
+function parseInstallHooks(value) {
+    if (value !== 'ask' && value !== 'auto' && value !== 'skip') {
+        throw new Error(`--install-hooks must be one of: ask, auto, skip (got "${value}")`);
     }
+    return value;
+}
+async function runWorkspaceInit(options, io) {
     try {
-        applyHookInstall('project', projectRoot);
-        writeDecisionMarker(projectRoot, 'installed');
-        return {
-            decision: 'installed',
-            action: 'first-decision',
-            scope: 'project',
-            reason: 'user-answered-yes'
+        const { projectRoot, sessionId, rotation } = await resolveInitTarget(options);
+        const report = await runInitWorkspace(options, projectRoot, sessionId);
+        const scan = await bootstrapProjectScanForInit(options, projectRoot);
+        const ctx = {
+            options,
+            projectRoot,
+            sessionId,
+            rotation,
+            report,
+            projectScanEnvelope: scan.envelope,
+            projectScanError: scan.error
         };
+        const parts = await collectInitEnvelope(ctx);
+        printResult(io, ok('workspace.init', buildInitEnvelopeData(ctx, parts.hooksOutcome, parts.codegraphAutoOutcome), parts.warnings, parts.nextActions), options.json);
     }
     catch (error) {
-        writeDecisionMarker(projectRoot, 'installed');
-        return {
-            decision: 'installed',
-            action: 'first-decision',
-            scope: 'project',
-            reason: `install-failed: ${getErrorMessage(error)}`
-        };
+        reportWorkspaceInitFailure(io, error, options);
     }
 }
+export function registerWorkspaceInitCommand(workspace, io) {
+    addJsonOption(workspace
+        .command('init')
+        .description(INIT_DESCRIPTION)
+        .requiredOption('--project <path>', INIT_PROJECT_HELP)
+        .option('--session-id <id>', INIT_SESSION_HELP)
+        .option('--allow-session-rebind', INIT_REBIND_HELP, false)
+        .option('--no-rotate-on-outer-mismatch', INIT_NO_ROTATE_HELP)
+        .option('--install-hooks <mode>', INIT_INSTALL_HOOKS_HELP, parseInstallHooks)
+        .option('--no-claude-hooks', INIT_NO_CLAUDE_HOOKS_HELP)
+        .option('--init-standards', INIT_INIT_STANDARDS_HELP)
+        .option('--no-project-scan-bootstrap', INIT_NO_PROJECT_SCAN_HELP)
+        .option('--force-project-scan-templates', INIT_FORCE_TEMPLATES_HELP, false)).action((options) => runWorkspaceInit(options, io));
+}