peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/workspace/init-context.d.ts

@@ -0,0 +1,58 @@
+import { type WorkspaceInitReport } from '../../../services/workspace/workspace-service.js';
+import { type BootstrapProjectScanEnvelope } from '../../../services/prd/project-scan-bootstrap-service.js';
+import type { WorkspaceInitOptions, WorkspaceInitRotation } from './init-options.js';
+/** Everything one `peaks workspace init` run carries into its envelope phase. */
+export type WorkspaceInitContext = {
+    options: WorkspaceInitOptions;
+    projectRoot: string;
+    sessionId: string;
+    rotation: WorkspaceInitRotation;
+    report: WorkspaceInitReport;
+    projectScanEnvelope: BootstrapProjectScanEnvelope | null;
+    projectScanError: string | null;
+};
+type InitTarget = {
+    projectRoot: string;
+    sessionId: string;
+    rotation: WorkspaceInitRotation;
+};
+/**
+ * Resolve the project root and 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.
+ */
+export declare function resolveInitTarget(options: WorkspaceInitOptions): Promise<InitTarget>;
+export declare function runInitWorkspace(options: WorkspaceInitOptions, projectRoot: string, sessionId: string): Promise<WorkspaceInitReport>;
+/**
+ * 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.
+ */
+export declare function bootstrapProjectScanForInit(options: WorkspaceInitOptions, projectRoot: string): Promise<{
+    envelope: BootstrapProjectScanEnvelope | null;
+    error: string | null;
+}>;
+export {};

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

@@ -0,0 +1,121 @@
+// Split out of `workspace/init-command.ts`:
+// project-root + session resolution, the `initWorkspace` call itself, and the
+// optional `.peaks/project-scan/` bootstrap.
+import { resolveWritableProjectRoot } from '../../../services/config/config-safety.js';
+import { initWorkspace } from '../../../services/workspace/workspace-service.js';
+import { ensureSessionWithRotation } from '../../../services/session/session-manager.js';
+import { bootstrapProjectScan } from '../../../services/prd/project-scan-bootstrap-service.js';
+import { getErrorMessage } from '../../cli-helpers.js';
+/**
+ * Resolve the project root and 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.
+ */
+export async function resolveInitTarget(options) {
+    const projectRoot = resolveWritableProjectRoot(options.project);
+    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
+        };
+    }
+    return { projectRoot, sessionId, rotation };
+}
+export async function runInitWorkspace(options, projectRoot, sessionId) {
+    return 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.
+ */
+export async function bootstrapProjectScanForInit(options, projectRoot) {
+    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".
+        return {
+            envelope: {
+                created: false,
+                skipped: true,
+                templatesBooted: 0,
+                templatesSkipped: 0,
+                projectScanPath: `${projectRoot}/.peaks/project-scan/project-scan.md`,
+                durationMs: 0
+            },
+            error: null
+        };
+    }
+    try {
+        const envelope = await bootstrapProjectScan({
+            projectRoot,
+            ...(options.forceProjectScanTemplates === true ? { forceTemplates: true } : {})
+        });
+        return { envelope, error: null };
+    }
+    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.
+        return { envelope: null, error: getErrorMessage(error) };
+    }
+}

package/dist/cli/commands/workspace/init-envelope.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspaceInitContext } from './init-context.js';
+import type { CodegraphAutoStakeOutcome, FirstTimeHooksInstallOutcome } from './init-options.js';
+export declare function buildInitEnvelopeData(ctx: WorkspaceInitContext, hooksOutcome: FirstTimeHooksInstallOutcome, codegraphAutoOutcome: CodegraphAutoStakeOutcome | null): Record<string, unknown>;

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

@@ -0,0 +1,34 @@
+export function buildInitEnvelopeData(ctx, hooksOutcome, codegraphAutoOutcome) {
+    const { report, rotation, projectScanEnvelope, projectScanError } = ctx;
+    return {
+        ...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 } : {})
+                }
+            }
+            : {})
+    };
+}

package/dist/cli/commands/workspace/init-failures.d.ts

@@ -0,0 +1,3 @@
+import { type ProgramIO } from '../../cli-helpers.js';
+import type { WorkspaceInitOptions } from './init-options.js';
+export declare function reportWorkspaceInitFailure(io: ProgramIO, error: unknown, options: WorkspaceInitOptions): void;

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

@@ -0,0 +1,84 @@
+// Split out of `workspace/init-command.ts`: the
+// typed failure arms of `peaks workspace init`. Each arm is a printer +
+// exit-code pair; the dispatcher preserves the original branch order.
+import { InvalidSessionIdError, ConflictingSessionError, LegacyChangeIdSiblingError } from '../../../services/workspace/workspace-service.js';
+import { UnsafeProjectRootError } from '../../../services/config/config-safety.js';
+import { fail } from 'peaks-loop-shared/result';
+import { getErrorMessage, printResult } from '../../cli-helpers.js';
+/**
+ * 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.
+ */
+function reportUnsafeProjectRoot(io, error, options) {
+    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;
+}
+function reportInvalidSessionId(io, error, options) {
+    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;
+}
+function reportConflictingSession(io, error, options) {
+    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;
+}
+/**
+ * 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.
+ */
+function reportLegacyChangeIdSibling(io, error, options) {
+    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;
+}
+function reportGenericInitFailure(io, error, options) {
+    // 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;
+}
+export function reportWorkspaceInitFailure(io, error, options) {
+    if (error instanceof UnsafeProjectRootError) {
+        reportUnsafeProjectRoot(io, error, options);
+        return;
+    }
+    if (error instanceof InvalidSessionIdError) {
+        reportInvalidSessionId(io, error, options);
+        return;
+    }
+    if (error instanceof ConflictingSessionError) {
+        reportConflictingSession(io, error, options);
+        return;
+    }
+    if (error instanceof LegacyChangeIdSiblingError) {
+        reportLegacyChangeIdSibling(io, error, options);
+        return;
+    }
+    reportGenericInitFailure(io, error, options);
+}

package/dist/cli/commands/workspace/init-hooks-decision.d.ts

@@ -0,0 +1,24 @@
+import type { FirstTimeHooksInstallOutcome, ResolveFirstTimeHooksInstallOptions } from './init-options.js';
+/**
+ * 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 declare function resolveFirstTimeHooksInstall(options: ResolveFirstTimeHooksInstallOptions): Promise<FirstTimeHooksInstallOutcome>;

package/dist/cli/commands/workspace/init-hooks-decision.js

@@ -0,0 +1,189 @@
+// Split out of `workspace/init-command.ts`:
+// the first-time "install peaks hooks" decision. The original function was 127
+// code lines with a complexity of 19; the marker / auto / prompt paths are now
+// one function each so every branch stays inside the 50-code-line cap.
+import { applyHookInstall, readHookStatus } from '../../../services/skills/hooks-settings-service.js';
+import { getErrorMessage } from '../../cli-helpers.js';
+import { readDecisionMarker, writeDecisionMarker, promptYesNo } from './helpers.js';
+const PROMPT_TEXT = '\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]: ';
+/**
+ * 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.
+ */
+function readHookStatusOrUnknown(projectRoot) {
+    try {
+        return readHookStatus('project', projectRoot);
+    }
+    catch (error) {
+        // Fall through to the install path; the failure will be captured below.
+        void error;
+        return { installed: false };
+    }
+}
+function resolveWithExistingMarker(projectRoot, existingMarker, hookStatus) {
+    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
+    };
+}
+/**
+ * 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
+ */
+function autoInstallHooks(projectRoot, explicitMode, jsonMode) {
+    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)}`
+        };
+    }
+}
+/** `ask` mode in a TTY: prompt once and record the answer sticky. */
+async function promptForHooksInstall(projectRoot) {
+    process.stderr.write(PROMPT_TEXT);
+    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)}`
+        };
+    }
+}
+/**
+ * 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);
+    const hookStatus = readHookStatusOrUnknown(projectRoot);
+    if (existingMarker !== null) {
+        return resolveWithExistingMarker(projectRoot, existingMarker, hookStatus);
+    }
+    // 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) {
+        return autoInstallHooks(projectRoot, explicitMode, jsonMode);
+    }
+    return promptForHooksInstall(projectRoot);
+}

package/dist/cli/commands/workspace/init-options.d.ts

@@ -0,0 +1,102 @@
+import type { HooksDecision } from './helpers.js';
+export type WorkspaceInitOptions = {
+    project: string;
+    sessionId?: string;
+    json?: boolean;
+    allowSessionRebind?: boolean;
+    /**
+     * flag is `--no-rotate-on-outer-mismatch`; commander strips the
+     * `--no-` prefix and assigns the boolean to this property (default
+     * `true`, set to `false` when the flag is passed). The wrapper
+     * reads this as `=== false` to opt out. The presence file still
+     * records `outerSessionMismatch` regardless of the flag's value.
+     */
+    rotateOnOuterMismatch?: boolean;
+    /**
+     * How to handle the first-time "install peaks hooks" prompt.
+     *   - ask  (default in TTY): prompt the user once, sticky-marker the answer
+     *   - auto (default in --json / non-TTY): install silently, sticky-marker installed
+     *   - skip: write sticky-marker skipped, do not install
+     * After the first decision the sticky marker wins, regardless of --install-hooks
+     * (re-runs respect the recorded decision; only re-install when the marker says
+     * installed but the hooks have been removed out from under us).
+     */
+    installHooks?: 'ask' | 'auto' | 'skip';
+    /**
+     * Slice 2.0.1-bug3-fact-forcing-bypass: opt out of writing the
+     * consumer-project `.claude/settings.local.json` file. Default
+     * (commander `--no-` prefix) is `true`; pass `--no-claude-hooks` to
+     * set this to `false`. The wrapper reads this as `=== false` to
+     * skip the materialization. The bypass is documented in
+     * `peaks-code/references/anchoring-and-session-info.md`.
+     */
+    claudeHooks?: boolean;
+    /**
+     * auto-scaffold `.claude/rules/{common,<language>}/` when missing.
+     * Default `false` — the diagnostic fires but no write happens.
+     * Set to `true` (via `--init-standards`) to also run
+     * `executeProjectStandardsInit({ projectRoot, apply: true })`.
+     */
+    initStandards?: boolean;
+    /**
+     * commander-style `--no-project-scan-bootstrap` opt-out. Default
+     * (no flag) leaves this `undefined` (treated as `true`). Pass the
+     * flag to set `options.projectScanBootstrap === false`, which the
+     * caller reads as `=== false` to skip the bootstrap call.
+     */
+    projectScanBootstrap?: boolean;
+    /**
+     * `--force-project-scan-templates` flag. Default (no flag)
+     * leaves this `undefined`. Pass the flag to set
+     * `options.forceProjectScanTemplates === true`, which forces the
+     * bootstrap service to overwrite the 4 bundled audit/business
+     * templates even when they already exist (sediment is preserved
+     * otherwise).
+     */
+    forceProjectScanTemplates?: boolean;
+};
+/**
+ * Outcome of the first-time "install peaks hooks" decision attached to
+ * `peaks workspace init`. Reported in the response data so the LLM and
+ * the human both see what happened.
+ */
+export type FirstTimeHooksInstallOutcome = {
+    /** The decision recorded (or already on file) in the sticky marker. */
+    decision: HooksDecision;
+    /**
+     * What the install path actually did this call.
+     *   - first-decision: we recorded a brand-new sticky marker (and may have installed)
+     *   - reinstalled:    the marker said installed but the hooks were missing — we re-applied
+     *   - marker-honored: the marker already existed; we did not touch the hooks
+     *   - already-installed: the hooks were already present and the marker does not exist yet
+     *                          (we write a fresh marker to lock in the answer for next time)
+     */
+    action: 'first-decision' | 'reinstalled' | 'marker-honored' | 'already-installed';
+    scope: 'project' | 'global';
+    /**
+     * Why the action was the way it was (e.g. "stdin-not-tty", "user-answered-no",
+     * "marker-installed-hooks-missing"). Surfaced for forensics.
+     */
+    reason?: string;
+};
+export type ResolveFirstTimeHooksInstallOptions = {
+    projectRoot: string;
+    /**
+     * Explicit mode from the --install-hooks flag. When omitted, the default
+     * is "ask" in TTY mode and "auto" otherwise (see `defaultMode` logic).
+     */
+    explicitMode?: 'ask' | 'auto' | 'skip' | undefined;
+    /**
+     * Whether the caller is in --json mode. In --json mode we never prompt
+     * (the LLM cannot answer an interactive question) — we silently treat
+     * "ask" as "auto" and proceed.
+     */
+    jsonMode: boolean;
+};
+export type WorkspaceInitRotation = {
+    previousSessionId: string | null;
+    reason: 'outer-session-mismatch' | null;
+};
+export type CodegraphAutoStakeOutcome = {
+    status: 'fresh' | 'noop' | 'conflict';
+};

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

@@ -0,0 +1 @@
+export {};

package/dist/cli/commands/worktree-lease-commands.d.ts

@@ -9,13 +9,17 @@
  * list / gc / lease-status read and mutate the same on-disk lease store.
  * They coexist with `peaks worktree auth grant|revoke|status` (the L2 hook
  * gate surface) on the shared `peaks worktree` parent command.
+ *
+ * Each sub-command now lives in its own `worktree-lease-<name>-command.ts`
+ * sibling (registrar + runner + helpers), with the shared pieces in
+ * `worktree-lease-session.ts` (session / project-root resolution),
+ * `worktree-lease-load.ts` (single-lease loader), `worktree-lease-store.ts`
+ * (lease-store reader) and `worktree-lease-git.ts` (best-effort git
+ * helpers). This module keeps the registration entry point and re-exports
+ * the two resolvers the rest of the CLI imports from this path. Command
+ * names, options, envelopes, error codes and exit codes are unchanged.
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-export declare function resolveSessionId(options: {
-    session?: string;
-}, projectRoot: string): string;
-export declare function resolveProjectRoot(options: {
-    project?: string;
-}): string;
+export { resolveProjectRoot, resolveSessionId } from './worktree-lease-session.js';
 export declare function registerWorktreeLeaseCommands(auth: Command, io: ProgramIO): void;