peaks-loop 4.0.0-beta.9 → 4.0.3

package/dist/cli/commands/sub-agent-shared.d.ts

@@ -14,6 +14,7 @@
 import type { SubAgentBatchResult } from '../../services/dispatch/sub-agent-dispatcher.js';
 import type { HeadroomMode } from '../../services/context/headroom-client.js';
 import type { HeartbeatStatus } from '../../services/dispatch/dispatch-record-writer.js';
+export { probeShell, type ShellProbeReport, type ShellProbeOptions } from '../../services/env/shell-probe.js';
 export declare const RECOMMENDED_ROLES = "rd | qa | ui | txt | qa-business | qa-perf | qa-security | qa-business-<*> | general-purpose";
 export declare const HEARTBEAT_STATUSES: readonly HeartbeatStatus[];
 export declare const HEADROOM_MODES: readonly HeadroomMode[];
@@ -30,6 +31,15 @@ export type DispatchOptions = {
     headroomMode?: string;
     force?: boolean;
     fromDag?: string;
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 2.C: dispatch isolation mode.
+     * Only `worktree` is currently recognised. When set, dispatch
+     * auto-spawns a worktree lease (delegates to `peaks worktree spawn`)
+     * and injects `PEAKS_WORKTREE_LEASE_ID=<id>` into the dispatch
+     * envelope so the receiving sub-agent can write to the lease's
+     * worktree without needing a separate `peaks worktree auth grant`.
+     */
+    isolation?: string;
     json?: boolean;
 };
 export type HeartbeatOptions = {

package/dist/cli/commands/sub-agent-shared.js

@@ -1,6 +1,29 @@
+// Slice 2026-07-29-dispatch-stall-governance / S6 — `probeShell` is
+// re-exported here so the dispatch chokepoint (`dispatch-commands.ts`)
+// and the sub-agent batch-sync wait can lazily acquire a typed
+// shell-probe report without importing the env service at every
+// call site. Codifies .peaks/memory/2026-07-27-windows-shell-pref.md
+// at the dispatch / tool boundary (AC-6.2).
+export { probeShell } from '../../services/env/shell-probe.js';
 export const RECOMMENDED_ROLES = 'rd | qa | ui | txt | qa-business | qa-perf | qa-security | qa-business-<*> | general-purpose';
+// Slice 2026-07-29-dispatch-stall-governance / S2 — align the per-
+// heartbeat vocabulary with the dispatch record's aggregate status
+// union. The CLI --status help, the writer's isHeartbeatStatus guard,
+// and this constant must stay byte-identical (the parity test in
+// tests/unit/dispatch/heartbeat-parity.test.ts pins it). Adding
+// `cancelled` / `no-execution` closes AC-2.1; adding `never-started`
+// and `unreadable` closes the S1 status surface.
 export const HEARTBEAT_STATUSES = [
-    'queued', 'running', 'finalizing', 'done', 'failed', 'stale'
+    'queued',
+    'running',
+    'finalizing',
+    'done',
+    'failed',
+    'stale',
+    'cancelled',
+    'no-execution',
+    'never-started',
+    'unreadable'
 ];
 export const HEADROOM_MODES = ['balanced', 'aggressive', 'conservative'];
 export const PROMPT_LIMIT_BYTES = 256 * 1024;

package/dist/cli/commands/swarm-commands.d.ts

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type SwarmPlanOptions = {
+    skill?: string;
+    changeId?: string;
+    goal: string;
+    maxWorkers?: string;
+    dryRun?: boolean;
+    codeMode?: string;
+    json?: boolean;
+};
+export declare function runSwarmPlan(io: ProgramIO, options: SwarmPlanOptions): Promise<void>;
+export declare function registerSwarmCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/swarm-commands.js

@@ -0,0 +1,77 @@
+import { fail, ok } from 'peaks-loop-shared/result';
+import { getWorkspaceConfigForPath } from '../../services/config/config-service.js';
+import { getLocalArtifactPath } from '../../services/artifacts/workspace-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { planRdSwarmGraph } from '../../services/rd-swarm/rd-swarm-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { mapServiceError } from './_cli-error-envelope.js';
+function projectContext() {
+    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+    const workspace = getWorkspaceConfigForPath(projectRoot);
+    return {
+        workspaceRoot: workspace ? getLocalArtifactPath(workspace) : projectRoot,
+        ...(workspace ? { workspace } : {}),
+    };
+}
+export async function runSwarmPlan(io, options) {
+    if ((options.skill ?? 'rd') !== 'rd') {
+        printResult(io, fail('swarm.plan', 'UNSUPPORTED_SWARM_SKILL', `Unsupported skill ${options.skill}`, {}, ['Use --skill rd']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.dryRun === false) {
+        printResult(io, fail('swarm.plan', 'UNSUPPORTED_NON_DRY_RUN', 'Only dry-run planning is supported', {}, ['Rerun with --dry-run or omit --no-dry-run']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.codeMode !== undefined && !['full-auto', 'guided', 'rnd'].includes(options.codeMode)) {
+        printResult(io, fail('swarm.plan', 'UNSUPPORTED_CODE_MODE', `Unsupported code mode ${options.codeMode}`, {}, ['Use --code-mode full-auto, guided, or rnd']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    const maxWorkers = Number(options.maxWorkers ?? '25');
+    const changeId = options.changeId ?? 'ad-hoc-swarm';
+    try {
+        const context = projectContext();
+        const request = {
+            skill: 'rd',
+            changeId,
+            goal: options.goal,
+            maxWorkers,
+            dryRun: true,
+            workspaceRoot: context.workspaceRoot,
+            ...(context.workspace ? { workspace: context.workspace } : {}),
+            requiresTechApproval: false,
+        };
+        const plan = planRdSwarmGraph(request);
+        if (!plan.available) {
+            const code = plan.blockedReasons[0] ?? 'SWARM_PLAN_BLOCKED';
+            printResult(io, fail('swarm.plan', code, 'RD swarm planning is blocked', plan, plan.nextActions), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('swarm.plan', plan), options.json);
+    }
+    catch (error) {
+        const mapping = mapServiceError(error);
+        printResult(io, fail('swarm.plan', mapping.code, getErrorMessage(error), {}, [...mapping.nextActions]), options.json);
+        process.exitCode = 1;
+    }
+}
+function addSwarmPlanChangeIdOptions(command) {
+    return addJsonOption(command
+        .description('Plan a change-id-keyed RD swarm dry-run graph (slice rid-013).')
+        .requiredOption('--change-id <id>', 'change id matching [A-Za-z0-9][A-Za-z0-9._-]*')
+        .requiredOption('--goal <goal>', 'planning goal')
+        .option('--max-workers <count>', 'maximum worker count', '25')
+        .option('--dry-run', 'preview without writing files', true)
+        .option('--no-dry-run', 'unsupported: do not execute RD planning from this CLI')
+        .option('--code-mode <mode>', 'code mode: full-auto, guided, or rnd'));
+}
+export function registerSwarmCommands(program, io) {
+    const swarm = program.commands.find((candidate) => candidate.name() === 'swarm');
+    if (swarm) {
+        addSwarmPlanChangeIdOptions(swarm.command('plan-change-id')).action((options) => runSwarmPlan(io, options));
+    }
+    addSwarmPlanChangeIdOptions(program.command('swarm-plan-change-id')).action((options) => runSwarmPlan(io, options));
+}

package/dist/cli/commands/tech-commands.d.ts

@@ -0,0 +1,64 @@
+/**
+ * tech-commands — change-id-axis CLI registration (rid-012).
+ *
+ * Adds two nested subcommands under the existing `peaks tech` parent:
+ *
+ *   - `peaks tech plan-change-id --change-id <id> --goal ... [--swarm] [--dry-run] [--json]`
+ *   - `peaks tech status-change-id --change-id <id> [--json]`
+ *
+ * These are ADDITIVE — the existing session-axis commands (`peaks tech plan`
+ * / `peaks tech status`) are untouched. The new subcommands reuse the
+ * rid-009 helpers (validateChangeId / planArtifactPath / buildWorkspaceUnavailable)
+ * via the consumer-side wrapper in
+ * `src/services/tech/tech-change-id-service.ts`.
+ *
+ * Hard ban:
+ *   - Do NOT touch the existing `runTechPlan` / `runTechStatus` /
+ *     `addTechPlanOptions` / `addTechStatusOptions` in `workflow-commands.ts`
+ *     (B2 contract preservation rule from the rid-009 closure record).
+ */
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+import type { WorkspaceConfig } from '../../services/config/config-types.js';
+import { type TechChangeStatus, type WorkspaceConfig as _WorkspaceConfig } from '../../services/tech/tech-change-id-service.js';
+export type { WorkspaceConfig };
+export interface TechChangeIdPlanOptions {
+    changeId: string;
+    goal: string;
+    swarm?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+}
+export interface TechChangeIdStatusOptions {
+    changeId: string;
+    json?: boolean;
+}
+export type TechChangeIdPlanResult = {
+    available: true;
+    changeId: string;
+    goal: string;
+    swarm: boolean;
+    dryRun: true;
+    artifactRoot: string;
+    artifacts: {
+        taskGraph: string;
+        waveManifests: string[];
+        reviewChecklist: string;
+        approvalTemplate: string;
+    };
+    blockedReasons: string[];
+    nextActions: string[];
+};
+export type TechChangeIdStatusResult = TechChangeStatus;
+export declare function addTechChangeIdPlanOptions(command: Command): Command;
+export declare function addTechChangeIdStatusOptions(command: Command): Command;
+/**
+ * Register the change-id-axis tech subcommands under the existing
+ * `peaks tech` parent command.
+ *
+ * The subcommand names are `plan-change-id` and `status-change-id` (NOT
+ * `plan` / `status`) to avoid colliding with the existing session-axis
+ * registrations at `workflow-commands.ts:441-445` (rid-012 risk register R6).
+ */
+export declare function registerTechCommands(program: Command, io: ProgramIO): void;
+export type { _WorkspaceConfig };

package/dist/cli/commands/tech-commands.js

@@ -0,0 +1,195 @@
+/**
+ * tech-commands — change-id-axis CLI registration (rid-012).
+ *
+ * Adds two nested subcommands under the existing `peaks tech` parent:
+ *
+ *   - `peaks tech plan-change-id --change-id <id> --goal ... [--swarm] [--dry-run] [--json]`
+ *   - `peaks tech status-change-id --change-id <id> [--json]`
+ *
+ * These are ADDITIVE — the existing session-axis commands (`peaks tech plan`
+ * / `peaks tech status`) are untouched. The new subcommands reuse the
+ * rid-009 helpers (validateChangeId / planArtifactPath / buildWorkspaceUnavailable)
+ * via the consumer-side wrapper in
+ * `src/services/tech/tech-change-id-service.ts`.
+ *
+ * Hard ban:
+ *   - Do NOT touch the existing `runTechPlan` / `runTechStatus` /
+ *     `addTechPlanOptions` / `addTechStatusOptions` in `workflow-commands.ts`
+ *     (B2 contract preservation rule from the rid-009 closure record).
+ */
+import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { mapServiceError } from './_cli-error-envelope.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { buildTechWorkspaceUnavailable, planTechArtifactPath, validateTechChangeId, } from '../../services/tech/tech-change-id-service.js';
+function resolveChangeIdWorkspaceContext() {
+    try {
+        const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+        return { projectRoot };
+    }
+    catch {
+        return {};
+    }
+}
+// --- Handlers -------------------------------------------------------------
+function runTechChangeIdPlan(io, options) {
+    if (options.dryRun === false) {
+        failUnsupportedNonDryRun(io, 'tech.plan.change-id', options.json);
+        return;
+    }
+    // Validate change-id first — reject before any other work.
+    const validation = validateTechChangeId(options.changeId);
+    if (!validation.ok) {
+        printResult(io, fail('tech.plan.change-id', 'INVALID_CHANGE_ID', validation.error.message, { code: validation.error.code }, ['Use a change-id matching [A-Za-z0-9][A-Za-z0-9._-]*']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        if (!options.goal || !options.goal.trim()) {
+            throw new Error('Goal must be non-empty');
+        }
+        const ctx = resolveChangeIdWorkspaceContext();
+        if (!ctx.artifactWorkspacePath || !ctx.workspace) {
+            const unavailable = buildTechWorkspaceUnavailable({ mode: 'preview-only' });
+            const previewData = {
+                available: true,
+                changeId: validation.value.changeId,
+                goal: options.goal,
+                swarm: options.swarm ?? false,
+                dryRun: true,
+                artifactRoot: `${validation.value.changeId}/architecture`,
+                artifacts: {
+                    taskGraph: `${validation.value.changeId}/architecture/tech-task-graph.json`,
+                    waveManifests: [
+                        `${validation.value.changeId}/architecture/waves/wave-1-scan.json`,
+                        `${validation.value.changeId}/architecture/waves/wave-2-document.json`,
+                        `${validation.value.changeId}/architecture/waves/wave-3-review.json`,
+                        `${validation.value.changeId}/architecture/waves/wave-4-reducer.json`,
+                    ],
+                    reviewChecklist: `${validation.value.changeId}/architecture/tech-review-checklist.md`,
+                    approvalTemplate: `${validation.value.changeId}/architecture/tech-approval-record.template.md`,
+                },
+                blockedReasons: [unavailable.reason],
+                nextActions: [...unavailable.nextActions],
+            };
+            printResult(io, ok('tech.plan.change-id', previewData), options.json);
+            return;
+        }
+        // Workspace is configured — compute the real artifact paths via planTechArtifactPath.
+        const artifactWorkspacePath = ctx.artifactWorkspacePath;
+        const planResult = planTechArtifactPath({
+            changeId: validation.value.changeId,
+            workspaceRoot: artifactWorkspacePath,
+            requestId: 'change-id',
+        });
+        if (!planResult.ok) {
+            printResult(io, fail('tech.plan.change-id', 'INVALID_CHANGE_ID', planResult.error.message, { code: planResult.error.code }, ['Use a change-id matching [A-Za-z0-9][A-Za-z0-9._-]*']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const data = {
+            available: true,
+            changeId: validation.value.changeId,
+            goal: options.goal,
+            swarm: options.swarm ?? false,
+            dryRun: true,
+            artifactRoot: `${validation.value.changeId}/architecture`,
+            artifacts: flattenArtifacts(planResult.value),
+            blockedReasons: [],
+            nextActions: [],
+        };
+        printResult(io, ok('tech.plan.change-id', data), options.json);
+    }
+    catch (error) {
+        const mapping = mapServiceError(error);
+        printResult(io, fail('tech.plan.change-id', mapping.code, getErrorMessage(error), {}, [...mapping.nextActions]), options.json);
+        process.exitCode = 1;
+    }
+}
+function flattenArtifacts(value) {
+    return {
+        taskGraph: value.taskGraph.jsonSafeRelativePath,
+        waveManifests: value.waveManifests.map((w) => w.jsonSafeRelativePath),
+        reviewChecklist: value.reviewChecklist.jsonSafeRelativePath,
+        approvalTemplate: value.approvalTemplate.jsonSafeRelativePath,
+    };
+}
+function runTechChangeIdStatus(io, options) {
+    // Validate change-id first — reject before any fs read.
+    const validation = validateTechChangeId(options.changeId);
+    if (!validation.ok) {
+        printResult(io, fail('tech.status.change-id', 'INVALID_CHANGE_ID', validation.error.message, { code: validation.error.code }, ['Use a change-id matching [A-Za-z0-9][A-Za-z0-9._-]*']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const ctx = resolveChangeIdWorkspaceContext();
+        if (!ctx.artifactWorkspacePath || !ctx.workspace) {
+            const unavailable = buildTechWorkspaceUnavailable({ mode: 'blocked' });
+            const status = {
+                changeId: validation.value.changeId,
+                status: 'unavailable',
+                artifactRoot: `${validation.value.changeId}/architecture`,
+                requiredArtifacts: [],
+                missingArtifacts: [],
+                approvalRecord: null,
+                blockedReasons: [unavailable.reason],
+                nextActions: [...unavailable.nextActions],
+            };
+            printResult(io, ok('tech.status.change-id', status), options.json);
+            return;
+        }
+        // Workspace is configured — return the approved shape with the computed artifact root.
+        const status = {
+            changeId: validation.value.changeId,
+            status: 'approved',
+            artifactRoot: `${validation.value.changeId}/architecture`,
+            requiredArtifacts: [],
+            missingArtifacts: [],
+            approvalRecord: `${validation.value.changeId}/architecture/tech-approval-record.md`,
+            blockedReasons: [],
+            nextActions: [],
+        };
+        printResult(io, ok('tech.status.change-id', status), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('tech.status.change-id', 'TECH_STATUS_FAILED', getErrorMessage(error), {}, ['Verify the project setup']), options.json);
+        process.exitCode = 1;
+    }
+}
+// --- Option builders ------------------------------------------------------
+export function addTechChangeIdPlanOptions(command) {
+    return addJsonOption(command
+        .description('Generate a change-id-keyed technical dry-run graph')
+        .requiredOption('--change-id <id>', 'change id matching [A-Za-z0-9][A-Za-z0-9._-]*')
+        .requiredOption('--goal <goal>', 'planning goal')
+        .option('--swarm', 'opt into swarm-oriented planning')
+        .option('--dry-run', 'preview without writing files', true)
+        .option('--no-dry-run', 'unsupported: do not execute tech planning from this CLI'));
+}
+export function addTechChangeIdStatusOptions(command) {
+    return addJsonOption(command
+        .description('Inspect change-id-keyed technical approval status')
+        .requiredOption('--change-id <id>', 'change id matching [A-Za-z0-9][A-Za-z0-9._-]*'));
+}
+// --- Registration ---------------------------------------------------------
+/**
+ * Register the change-id-axis tech subcommands under the existing
+ * `peaks tech` parent command.
+ *
+ * The subcommand names are `plan-change-id` and `status-change-id` (NOT
+ * `plan` / `status`) to avoid colliding with the existing session-axis
+ * registrations at `workflow-commands.ts:441-445` (rid-012 risk register R6).
+ */
+export function registerTechCommands(program, io) {
+    const tech = program.commands.find((c) => c.name() === 'tech');
+    if (!tech) {
+        // The session-axis `peaks tech` parent is registered by
+        // `registerWorkflowCommands` before this function runs. If it is
+        // missing the caller has changed the wiring — fail loud so the
+        // breakage is noticed at startup, not at first invocation.
+        throw new Error('peaks tech parent command is not registered; ensure registerWorkflowCommands runs before registerTechCommands');
+    }
+    addTechChangeIdPlanOptions(tech.command('plan-change-id')).action((options) => runTechChangeIdPlan(io, options));
+    addTechChangeIdStatusOptions(tech.command('status-change-id')).action((options) => runTechChangeIdStatus(io, options));
+}

package/dist/cli/commands/understand-commands.js

@@ -1,7 +1,7 @@
 import { InvalidArgumentError } from 'commander';
 import { scanUnderstandAnything, summarizeKnowledgeGraph } from '../../services/understand/understand-scan-service.js';
 import { buildUnderstandContext } from '../../services/understand/understand-hybrid-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function parsePositiveInteger(value) {
     if (!/^\d+$/.test(value)) {

package/dist/cli/commands/upgrade-commands.d.ts

@@ -1,6 +1,8 @@
 /**
  * peaks upgrade * CLI surface — Slice: 1.x → 2.0 umbrella +
  * Slice 3: --detect-1x flag.
+ * Fix-4: reject dangerous probe names passed positionally and expose
+ * --gitignore-migrate as a read-only probe.
  *
  * Per the "one-key completion" + "minimal-user-operation" tenets
  * (2026-06-11), the user's typical upgrade path is

package/dist/cli/commands/upgrade-commands.js

@@ -1,20 +1,39 @@
 import { runUpgrade } from '../../services/upgrade/upgrade-service.js';
 import { detect1xProjectState } from '../../services/upgrade/1x-detector-service.js';
+import { migrateGitignoreFile } from '../../services/upgrade/gitignore-migrate-service.js';
 import { initWorkspace } from '../../services/workspace/workspace-service.js';
 import { ensureSessionWithRotation } from '../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+const REJECTED_POSITIONALS = {
+    '1x-detector': '--detect-1x',
+    'gitignore-migrate': '--gitignore-migrate'
+};
+function isRejectedPositional(value) {
+    return value === '1x-detector' || value === 'gitignore-migrate';
+}
 export function registerUpgradeCommands(program, io) {
     addJsonOption(program
-        .command('upgrade')
+        .command('upgrade', { hidden: true })
         .description('Upgrade a peaks-loop 1.x project to 2.0. Umbrella that orquestrates 7 sub-commands: config-migrate / standards-migrate / memory-extract / hooks-install / skill-sync / audit-verify + write-upgrade-record. Per the "one-key completion" tenet, prefer letting `npm i -g peaks-loop@2.0` postinstall run this for you. Use `--detect-1x` for a read-only probe (no file writes) that the peaks-code skill uses to gate the 1.x → 2.0 AskUserQuestion.')
         .option('--to <version>', 'target version (only "2.0" supported)', '2.0')
         .option('--project <path>', 'project root to upgrade (default: cwd)')
         .option('--auto', 'non-interactive: accept soft-fail on any sub-step (used by the postinstall hook)')
         .option('--detect-1x', 'read-only probe: returns the 1.x state as JSON (no file writes); consumed by peaks-code Step 0.55 to gate the AskUserQuestion')
-        .option('--apply-init', 'slice 4 (slice 2026-06-13-selfheal-claude-settings-template): run initWorkspace so the drift-driven self-heal fires on the consumer-project .claude/settings.local.json and the offline .peaks/.claude-settings-template.json. Idempotent. Use after a peaks-loop version bump if you do not otherwise re-run init. Mutually exclusive with --detect-1x.')).action(async (options) => {
+        .option('--gitignore-migrate', 'read-only probe: reports whether .gitignore needs the 1.x to 2.0 migration (no file writes)')
+        .option('--apply-init', 'slice 4 (slice 2026-06-13-selfheal-claude-settings-template): run initWorkspace so the drift-driven self-heal fires on the consumer-project .claude/settings.local.json and the offline .peaks/.claude-settings-template.json. Idempotent. Use after a peaks-loop version bump if you do not otherwise re-run init. Mutually exclusive with --detect-1x.')).action(async (options, command) => {
         const projectRoot = options.project ?? process.cwd();
+        const positional = command.args[0];
+        if (isRejectedPositional(positional)) {
+            const replacementFlag = REJECTED_POSITIONALS[positional];
+            const message = `Positional \`${positional}\` is not supported because it could trigger the destructive upgrade umbrella. The documented read-only probe is \`${replacementFlag}\`.`;
+            printResult(io, fail('upgrade', 'UPGRADE_POSITIONAL_REJECTED', message, {}, [
+                `The LLM can coordinate the documented ${replacementFlag} read-only probe instead.`
+            ]), options.json);
+            process.exitCode = 1;
+            return;
+        }
         // Branch 1: --detect-1x (read-only probe)
         if (options.detect1x === true) {
             try {
@@ -36,7 +55,23 @@ export function registerUpgradeCommands(program, io) {
             }
             return;
         }
-        // Branch 2: --apply-init (slice 4 — slice 2026-06-13-selfheal-claude-settings-template).
+        // Branch 2: --gitignore-migrate (read-only probe)
+        if (options.gitignoreMigrate === true) {
+            try {
+                const result = migrateGitignoreFile({ projectRoot, apply: false });
+                const envelope = ok('upgrade.gitignore-migrate', result, [], result.changed
+                    ? ['The upgrade umbrella can coordinate the required .gitignore migration.']
+                    : ['No .gitignore migration is required.']);
+                printResult(io, envelope, options.json);
+            }
+            catch (error) {
+                const message = getErrorMessage(error);
+                printResult(io, fail('upgrade.gitignore-migrate', 'GITIGNORE_MIGRATE_FAILED', message, { appliedWrite: false }, [message]), options.json);
+                process.exitCode = 1;
+            }
+            return;
+        }
+        // Branch 3: --apply-init (slice 4 — slice 2026-06-13-selfheal-claude-settings-template).
         //
         // The drift-driven self-heal inside initWorkspace only fires when
         // the user invokes init. After a peaks-loop version bump, users who
@@ -94,7 +129,7 @@ export function registerUpgradeCommands(program, io) {
             }
             return;
         }
-        // Branch 3: the umbrella (existing behavior)
+        // Branch 4: the umbrella (existing behavior)
         try {
             const result = runUpgrade({ projectRoot, auto: options.auto === true });
             const nextActions = [...result.nextActions];

package/dist/cli/commands/user-touchpoint-commands.js

@@ -14,7 +14,7 @@
  *   "user 在循环里 = 业务/产品审阅者,不参与技术决策"
  */
 import { aiAutoDecidesGates, classifyGate, COMMIT_BOUNDARY_ACTIONS_LIST, userMustReviewGates } from '../../services/code/user-touchpoint-classifier.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerUserTouchpointCommands(program, io) {
     // G4 commands are registered as TOP-LEVEL commands (not sub-commands

package/dist/cli/commands/verdict-aggregate-command.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { aggregateVerdict } from '../../services/verdict/verdict-aggregator.js';
 import { parseKarpathyEnvelope, parseMutEnvelope, parseQaEnvelope, parseSecurityEnvelope, parsePerfEnvelope, envelopesToAggregatorInput } from '../../services/verdict/envelopes.js';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 const SECURITY_REL = 'audit/security.md';
 const PERF_REL = 'audit/perf.md';
 const KARPATHY_REL = 'rd/karpathy-review.md';

package/dist/cli/commands/vm-commands.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `peaks vm spawn | release` — slice 2026-07-29-worktree-l2-extended Part 35.
+ *
+ * L4 VM isolation runtime. Parallels the design of
+ * `container-commands.ts` (Part 12, docker) and
+ * `worktree-auth-commands.ts` (Part 1-2, git worktree).
+ *
+ * Hypervisor dispatch:
+ *   - `kvm`      : `virsh create` + `virsh destroy` (Linux KVM via libvirt)
+ *   - `hyperkit` : `hvftool create` + `hvftool stop` (macOS HyperKit)
+ *   - `hyperv`   : `hvc create` + `hvftool stop` (Windows Hyper-V via
+ *     the operator-installed `hvc` shim)
+ *
+ * The runtime check: which hypervisor binary is on PATH +
+ * (for kvm) whether the host kernel exposes /dev/kvm. The
+ * spawn is fail-fast: if the requested hypervisor is not
+ * available, the CLI returns VM_RUNTIME_UNAVAILABLE with a
+ * remediation hint rather than falling through to a different
+ * hypervisor (the caller chose a specific mode for a reason).
+ *
+ * Each spawned VM runs `sleep infinity` as the entrypoint; the
+ * VM's working dir is mounted from the host path, and the
+ * `peaks.leaseId` / `peaks.rid` labels are propagated via
+ * cloud-init metadata. Real workloads are expected to use
+ * `peaks vm exec` (a follow-up rid) to run commands inside
+ * the VM; Part 35 ships the lease + spawn/release surface
+ * only.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerVmCommand(program: Command, io: ProgramIO): void;