peaks-loop 4.1.2 → 4.1.4

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

@@ -0,0 +1,10 @@
+import type { WorkspaceInitContext } from './init-context.js';
+import type { CodegraphAutoStakeOutcome, FirstTimeHooksInstallOutcome } from './init-options.js';
+export type InitEnvelopeParts = {
+    nextActions: string[];
+    warnings: string[];
+    hooksOutcome: FirstTimeHooksInstallOutcome;
+    codegraphAutoOutcome: CodegraphAutoStakeOutcome | null;
+};
+/** Collect the envelope's nextActions + warnings in the original push order. */
+export declare function collectInitEnvelope(ctx: WorkspaceInitContext): Promise<InitEnvelopeParts>;

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

@@ -0,0 +1,199 @@
+import { clearStalePresenceOnRotation } from '../../../services/skills/skill-presence-service.js';
+import { gcStalePresenceLeases } from '../../../services/skills/presence-lease-service.js';
+import { hasStandardsCheckedMarker, markStandardsChecked } from '../../../services/standards/missing-standards-detector.js';
+import { getErrorMessage } from '../../cli-helpers.js';
+import { stakeCodegraphForInit } from './init-codegraph-stake.js';
+import { resolveFirstTimeHooksInstall } from './init-hooks-decision.js';
+function pushBindingReplacedAction(nextActions, report) {
+    if (report.previousSessionId !== null && report.bound) {
+        nextActions.push(`Replaced prior session binding "${report.previousSessionId}" with "${report.sessionId}".`);
+    }
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+function pushRotationActions(nextActions, rotation, projectRoot, sessionId) {
+    if (rotation.previousSessionId === null || rotation.reason !== 'outer-session-mismatch')
+        return;
+    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.`);
+    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).');
+    }
+}
+function pushCreatedAction(nextActions, report) {
+    if (report.created.length === 0) {
+        nextActions.push('Workspace already initialized — proceed to project scan.');
+        return;
+    }
+    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.
+ *
+ * The `refreshed` offline-template 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.
+ */
+function pushSettingsActions(nextActions, report) {
+    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.');
+    }
+    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.');
+    }
+}
+function pushHooksActions(nextActions, hooksOutcome) {
+    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 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.
+ */
+async function collectLeaseSweepWarning(warnings, projectRoot) {
+    try {
+        const gcResult = await gcStalePresenceLeases({
+            projectRoot,
+            trigger: 'workspace-init'
+        });
+        if (gcResult.removed > 0) {
+            warnings.push(`Stale lease sweep removed ${gcResult.removed} lease(s) for the canonical project (retained ${gcResult.retained}).`);
+        }
+    }
+    catch (err) {
+        warnings.push(`lease sweep failed: ${getErrorMessage(err)}`);
+    }
+}
+/**
+ * When the consumer project's `.claude/rules/` is missing or empty, emit the
+ * copy-pasteable diagnostic into the JSON envelope's `warnings` array AND
+ * surface the structured descriptor. AC7: the diagnostic banner is skipped on
+ * subsequent invocations within the same session — the once-per-session marker
+ * `.peaks/_runtime/<sid>/.standards-checked` is written after the FIRST emit.
+ * AC3: when --init-standards was passed, `report.standardsApplied` lists the
+ * freshly-written files, surfaced as a nextAction.
+ */
+function pushStandardsActions(nextActions, warnings, ctx) {
+    const { report, projectRoot, sessionId } = ctx;
+    if (report.standardsMissing.missing && !hasStandardsCheckedMarker(projectRoot, sessionId)) {
+        warnings.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).`);
+    }
+}
+/**
+ * The project-scan 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.
+ */
+function pushProjectScanActions(nextActions, warnings, ctx) {
+    const { projectScanError, projectScanEnvelope, projectRoot } = ctx;
+    if (projectScanError !== null) {
+        warnings.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). */
+function markStandardsCheckedIfMissing(ctx) {
+    if (!ctx.report.standardsMissing.missing)
+        return;
+    markStandardsChecked(ctx.projectRoot, ctx.sessionId);
+}
+/** Collect the envelope's nextActions + warnings in the original push order. */
+export async function collectInitEnvelope(ctx) {
+    const nextActions = [];
+    const warnings = [];
+    pushBindingReplacedAction(nextActions, ctx.report);
+    pushRotationActions(nextActions, ctx.rotation, ctx.projectRoot, ctx.sessionId);
+    pushCreatedAction(nextActions, ctx.report);
+    pushSettingsActions(nextActions, ctx.report);
+    // 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: ctx.projectRoot,
+        ...(ctx.options.installHooks !== undefined ? { explicitMode: ctx.options.installHooks } : {}),
+        jsonMode: ctx.options.json === true
+    });
+    pushHooksActions(nextActions, hooksOutcome);
+    await collectLeaseSweepWarning(warnings, ctx.projectRoot);
+    pushStandardsActions(nextActions, warnings, ctx);
+    pushProjectScanActions(nextActions, warnings, ctx);
+    markStandardsCheckedIfMissing(ctx);
+    const codegraphAutoOutcome = await stakeCodegraphForInit(nextActions, warnings, ctx.projectRoot);
+    return { nextActions, warnings, hooksOutcome, codegraphAutoOutcome };
+}

package/dist/cli/commands/workspace/init-codegraph-stake.d.ts

@@ -0,0 +1,10 @@
+import type { CodegraphAutoStakeOutcome } from './init-options.js';
+/**
+ * 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`.
+ */
+export declare function stakeCodegraphForInit(nextActions: string[], warnings: string[], projectRoot: string): Promise<CodegraphAutoStakeOutcome | null>;

package/dist/cli/commands/workspace/init-codegraph-stake.js

@@ -0,0 +1,54 @@
+// Split out of `workspace/init-command.ts`: the
+// best-effort `codegraph init` stake that runs after a successful workspace
+// init. Never fails the init — every failure lands in the envelope's warnings.
+import { mkdirSync } from 'node:fs';
+import { createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, writeCodegraphMarker } from '../../../services/codegraph/codegraph-service.js';
+import { getErrorMessage } from '../../cli-helpers.js';
+/**
+ * Upstream `codegraph init` creates `.codegraph/`; mkdir is a no-op in the real
+ * path and lets the marker write succeed. Best-effort.
+ */
+async function stakeFreshCodegraph(nextActions, warnings, projectRoot, codegraphDir) {
+    const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }));
+    if (initResult.exitCode !== 0) {
+        warnings.push(`codegraph auto-stake init failed (exit ${String(initResult.exitCode)}). ` +
+            'Run `peaks codegraph init --project <path>` manually to enable codegraph.');
+        return null;
+    }
+    mkdirSync(codegraphDir, { recursive: true });
+    writeCodegraphMarker(codegraphDir);
+    nextActions.push(`Auto-staked a peaks-loop-managed ${codegraphDir}/ (upstream init + marker). ` +
+        'Run `peaks codegraph index --project <path>` next to build the SQLite-backed index.');
+    return { status: 'fresh' };
+}
+/**
+ * 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`.
+ */
+export async function stakeCodegraphForInit(nextActions, warnings, projectRoot) {
+    let outcome = 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.
+            outcome = await stakeFreshCodegraph(nextActions, warnings, projectRoot, guard.codegraphDir);
+        }
+        else if (guard.status === 'noop-already-peaks-loop') {
+            outcome = { status: 'noop' };
+        }
+        else {
+            outcome = { status: 'conflict' };
+            warnings.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) {
+        warnings.push(`codegraph auto-stake failed: ${getErrorMessage(err)}`);
+    }
+    return outcome;
+}

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

@@ -1,133 +1,17 @@
 /**
+ * `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 type { Command } from 'commander';
 import { type ProgramIO } from '../../cli-helpers.js';
-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 { resolveFirstTimeHooksInstall } from './init-hooks-decision.js';
+export type { FirstTimeHooksInstallOutcome, ResolveFirstTimeHooksInstallOptions, WorkspaceInitOptions } from './init-options.js';
 export declare function registerWorkspaceInitCommand(workspace: Command, io: ProgramIO): void;
-/**
- * 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>;