peaks-loop 3.1.1 → 4.0.0-beta

package/dist/src/services/solo/emit-handoff.d.ts

@@ -0,0 +1,49 @@
+/**
+ * v3.1.2 Step 11 / final handoff — Size-fear ban.
+ *
+ * Refuses to emit a final handoff while a Job has remaining slices.
+ * Closes the v3.1.0 incident pattern: LLM writes a fake-completion
+ * message at high context-fill before Job mode kicks in.
+ *
+ * Decision tree:
+ *   - job-shape.json missing OR isJob === false  → ALLOW (normal handoff)
+ *   - isJob === true, no state.json              → JOB_NOT_INITIALIZED (LLM
+ *     skipped `peaks job init`)
+ *   - isJob === true, state.json, remaining > 0,
+ *     no --force-under-job                        → JOB_REMAINING_BLOCKED
+ *   - isJob === true, state.json, remaining === 0 → ALLOW (Job done)
+ *   - isJob === true, state.json, remaining > 0,
+ *     --force-under-job                            → ALLOW (override path)
+ *
+ * Karpathy §2 (Simplicity First): ~70 lines, no LLM call, no regex.
+ * Pure read + arithmetic. The CLI wrapper in solo-commands.ts
+ * translates the verdict into exit code + JSON envelope.
+ */
+export declare const JOB_NOT_INITIALIZED: "JOB_NOT_INITIALIZED";
+export declare const JOB_REMAINING_BLOCKED: "JOB_REMAINING_BLOCKED";
+export type EmitHandoffVerdict = {
+    readonly kind: 'allow-not-job';
+} | {
+    readonly kind: 'allow-done';
+    readonly remaining: number;
+} | {
+    readonly kind: 'allow-force-override';
+    readonly remaining: number;
+} | {
+    readonly kind: 'block-not-initialized';
+    readonly code: typeof JOB_NOT_INITIALIZED;
+    readonly jobId: string;
+} | {
+    readonly kind: 'block-remaining';
+    readonly code: typeof JOB_REMAINING_BLOCKED;
+    readonly jobId: string;
+    readonly remaining: number;
+};
+export interface EvaluateEmitHandoffInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /** Suggested job id — read from job-shape.json when omitted. */
+    readonly jobId?: string;
+    readonly forceUnderJob?: boolean;
+}
+export declare function evaluateEmitHandoff(input: EvaluateEmitHandoffInput): EmitHandoffVerdict;

package/dist/src/services/solo/emit-handoff.js

@@ -0,0 +1,79 @@
+/**
+ * v3.1.2 Step 11 / final handoff — Size-fear ban.
+ *
+ * Refuses to emit a final handoff while a Job has remaining slices.
+ * Closes the v3.1.0 incident pattern: LLM writes a fake-completion
+ * message at high context-fill before Job mode kicks in.
+ *
+ * Decision tree:
+ *   - job-shape.json missing OR isJob === false  → ALLOW (normal handoff)
+ *   - isJob === true, no state.json              → JOB_NOT_INITIALIZED (LLM
+ *     skipped `peaks job init`)
+ *   - isJob === true, state.json, remaining > 0,
+ *     no --force-under-job                        → JOB_REMAINING_BLOCKED
+ *   - isJob === true, state.json, remaining === 0 → ALLOW (Job done)
+ *   - isJob === true, state.json, remaining > 0,
+ *     --force-under-job                            → ALLOW (override path)
+ *
+ * Karpathy §2 (Simplicity First): ~70 lines, no LLM call, no regex.
+ * Pure read + arithmetic. The CLI wrapper in solo-commands.ts
+ * translates the verdict into exit code + JSON envelope.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJobShapeDecision, JobShapeDecisionError, JOB_SHAPE_NOT_DECIDED } from './job-shape-decision.js';
+export const JOB_NOT_INITIALIZED = 'JOB_NOT_INITIALIZED';
+export const JOB_REMAINING_BLOCKED = 'JOB_REMAINING_BLOCKED';
+function countRemaining(statePath) {
+    let raw;
+    try {
+        raw = readFileSync(statePath, 'utf8');
+    }
+    catch {
+        return Number.NaN;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return Number.NaN;
+    }
+    if (!Array.isArray(parsed.slices))
+        return Number.NaN;
+    return parsed.slices.filter((sl) => sl.status !== 'done' && sl.status !== 'skipped').length;
+}
+function statePath(projectRoot, sessionId, jobId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'state.json');
+}
+export function evaluateEmitHandoff(input) {
+    let decision = null;
+    try {
+        const record = readJobShapeDecision(input.projectRoot, input.sessionId);
+        decision = record.decision;
+    }
+    catch (err) {
+        if (err instanceof JobShapeDecisionError && err.code === JOB_SHAPE_NOT_DECIDED) {
+            return { kind: 'allow-not-job' };
+        }
+        throw err;
+    }
+    if (!decision.isJob)
+        return { kind: 'allow-not-job' };
+    const jobId = input.jobId ?? decision.suggestedJobId;
+    const path = statePath(input.projectRoot, input.sessionId, jobId);
+    if (!existsSync(path)) {
+        return { kind: 'block-not-initialized', code: JOB_NOT_INITIALIZED, jobId };
+    }
+    const remaining = countRemaining(path);
+    if (!Number.isFinite(remaining)) {
+        return { kind: 'block-not-initialized', code: JOB_NOT_INITIALIZED, jobId };
+    }
+    if (remaining === 0) {
+        return { kind: 'allow-done', remaining };
+    }
+    if (input.forceUnderJob === true) {
+        return { kind: 'allow-force-override', remaining };
+    }
+    return { kind: 'block-remaining', code: JOB_REMAINING_BLOCKED, jobId, remaining };
+}

package/dist/src/services/solo/mode-gate.d.ts

@@ -43,7 +43,7 @@ export type GatedStepId = 'step-0.5-openspec-opt-in' | 'step-0.6-audit-goal' | '
 export declare const GATED_STEPS: readonly GatedStepId[];
 /**
  * Slice 2026-06-28-solo-mode-bypass-fix: the kind of gate that
- * produced this decision. The LLM-side caller (peaks-solo body) reads
+ * produced this decision. The LLM-side caller (peaks-code body) reads
  * this to distinguish "you paused because the user must choose the
  * mode" (`mode-selection-itself`) from "you paused because the mode
  * you already chose is assisted/strict" (`mode-driven`) from "you
@@ -98,7 +98,7 @@ export declare function shouldAutoProceed(mode: SoloMode): boolean;
 /**
  * v2.15.0 slice 002 AC-4: the 5 action identifiers that qualify as
  * commit-boundary side effects. Matched by the LLM-side caller
- * (peaks-solo body / peaks-rd fork agent) when it is about to run a
+ * (peaks-code body / peaks-rd fork agent) when it is about to run a
  * Bash command that maps to one of these. Set `commitBoundaryAction:
  * true` on the `shouldPauseAtGate` call to trigger the hard-floor
  * override.

package/dist/src/services/solo/post-compact-detector.js

@@ -146,7 +146,7 @@ export async function detectPostCompactResume(opts) {
         };
     }
     // Active skill check (D7.a.4). Defaults to reading from skill presence.
-    const expectedActiveSkill = 'peaks-solo';
+    const expectedActiveSkill = 'peaks-code';
     const observedActiveSkill = opts.activeSkill ?? readActiveSkillName(opts.projectRoot);
     if (observedActiveSkill !== expectedActiveSkill) {
         return {
@@ -154,7 +154,7 @@ export async function detectPostCompactResume(opts) {
             reason: 'active-skill-mismatch',
             checkpointPath: file.path,
             checkpointMtime: file.mtime.toISOString(),
-            warnings: [`active skill "${observedActiveSkill ?? 'unset'}" is not peaks-solo`]
+            warnings: [`active skill "${observedActiveSkill ?? 'unset'}" is not peaks-code`]
         };
     }
     // Mode: prefer the checkpoint's mode; fall back to the presence override

package/dist/src/services/solo/status-line-renderer.d.ts

@@ -1,13 +1,13 @@
 /**
- * G6.5 — status line renderer for the peaks-solo batch-sync wait period.
+ * G6.5 — status line renderer for the peaks-code batch-sync wait period.
  *
  * Single line, 80-120 chars, status-line-friendly. The shape is
  * documented in PRD §G6.5:
  *
- *   [peaks-solo] swarm 3/3 running | rd-planning 45% (12s ago) | qa-test-cases 30% (5s ago) | ui-design 20% (2s ago)
- *   [peaks-solo] swarm 3/3 running | rd-planning 70% (8s ago) | qa-test-cases 50% (3s ago) | ui-design 30% (6s ago)
+ *   [peaks-code] swarm 3/3 running | rd-planning 45% (12s ago) | qa-test-cases 30% (5s ago) | ui-design 20% (2s ago)
+ *   [peaks-code] swarm 3/3 running | rd-planning 70% (8s ago) | qa-test-cases 50% (3s ago) | ui-design 30% (6s ago)
  *   ...
- *   [peaks-solo] swarm 3/3 done in 47.3s
+ *   [peaks-code] swarm 3/3 done in 47.3s
  *
  * Pure helper; the poller calls it once per tick. No IO.
  */

package/dist/src/services/solo/step-08-gate.d.ts

@@ -0,0 +1,90 @@
+/**
+ * v3.1.2 Step 0.8 — Mechanical PreToolUse gate.
+ *
+ * Wire-installed by `peaks workspace init` (extends the existing hook
+ * installer; does NOT replace the Write|Edit|MultiEdit fact-forcing
+ * bypass). The hook runs `peaks solo gate-step-08 --project .` before
+ * every Bash tool call. Exit code is the load-bearing contract:
+ *
+ *   exit 0 → allow (with structured stdout describing the decision)
+ *   exit 2 → block (stderr contains the BLOCKED: ... reason)
+ *
+ * Three decision paths:
+ *
+ *   1. `job-shape.json` exists with `decision.isJob === true`.
+ *      → allow, print `{ ok, allow, mode: 'job', decision }`. When a
+ *        matching `job/<jid>/progress.json` exists, also print
+ *        `Next: slice #<N+1> of <M> (<currentSlice>)` so the LLM sees
+ *        its resume context BEFORE any Bash call lands.
+ *   2. `job-shape.json` exists with `decision.isJob === false`.
+ *      → allow, print `{ ok, allow, mode: 'single' }`.
+ *   3. `job-shape.json` is MISSING — fail-closed guard. The LLM is the
+ *      source of truth, but if it never recorded a decision we run a
+ *      lightweight backup regex against the user's prompt:
+ *        /until|全部|until all done|disavow cost|不用考虑费用|all of them/i
+ *      match → block (exit 2) with the BLOCKED: stderr message.
+ *      no match → allow (exit 0) — most prompts are not Job-shaped.
+ *
+ * Karpathy §2 (Simplicity First): ~120 lines, no LLM call inside. The
+ * regex is the FIRST time peaks-loop accepts hardcoded keywords —
+ * explicitly scoped as a *fail-closed backup* (case 3), NOT a primary
+ * judgement. The LLM still owns the semantic call via
+ * `peaks solo detect-job`. The regex is a safety net for the v3.1.1
+ * incident class (LLM under load never records the decision at all).
+ */
+export declare const STEP_08_GATE_FILE_NAME: "job-shape.json";
+export declare const STEP_08_PROGRESS_FILE_NAME: "progress.json";
+/**
+ * Fail-closed backup regex — see module docstring case 3 for why this
+ * exists. Kept short and explicit; if the prompt mentions any of these
+ * triggers and `job-shape.json` is missing, the LLM is treated as
+ * having skipped `peaks solo detect-job` and the gate blocks.
+ *
+ * The list mirrors the v3.1.0 / v3.1.1 incident triggers verbatim:
+ *   继续执行下个 slice (until next slice) → until / 直到
+ *   全部添加完 / all of them            → 全部 / all of them
+ *   不用考虑费用                        → 不用考虑费用 / disavow cost
+ *   until all done                      → until all done
+ */
+export declare const STEP_08_BACKUP_REGEX: RegExp;
+export interface Step08Progress {
+    readonly jobId: string;
+    readonly done: number;
+    readonly total: number;
+    readonly currentSlice: string;
+    readonly lastCommitSha: string | null;
+    readonly updatedAt: string;
+}
+export type Step08Verdict = {
+    readonly kind: 'allow-job';
+    readonly decision: import('./job-shape-decision.js').JobShapeDecision;
+    readonly progress: Step08Progress | null;
+} | {
+    readonly kind: 'allow-single';
+} | {
+    readonly kind: 'block-missing-decision';
+    readonly promptHit: boolean;
+    readonly promptSource: 'flag' | 'last-prompt-file' | 'stdin-empty';
+};
+export declare function runtimeSessionDir(projectRoot: string, sessionId: string): string;
+export interface EvaluateStep08Input {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /**
+     * Explicit prompt text. When omitted, falls back to
+     * `.peaks/_runtime/<sid>/txt/last-prompt.txt`, then to stdin (the
+     * caller passes stdin verbatim — usually empty in tests).
+     */
+    readonly prompt?: string;
+}
+export interface EvaluateStep08Result {
+    readonly allow: boolean;
+    readonly verdict: Step08Verdict;
+    readonly nextSliceLine: string | null;
+}
+/**
+ * Pure evaluator — does NOT write, does NOT exit. CLI wrapper in
+ * `src/cli/commands/solo-commands.ts` reads `allow` to set the process
+ * exit code (0 allow / 2 block) and prints the structured envelope.
+ */
+export declare function evaluateStep08(input: EvaluateStep08Input): EvaluateStep08Result;

package/dist/src/services/solo/step-08-gate.js

@@ -0,0 +1,136 @@
+/**
+ * v3.1.2 Step 0.8 — Mechanical PreToolUse gate.
+ *
+ * Wire-installed by `peaks workspace init` (extends the existing hook
+ * installer; does NOT replace the Write|Edit|MultiEdit fact-forcing
+ * bypass). The hook runs `peaks solo gate-step-08 --project .` before
+ * every Bash tool call. Exit code is the load-bearing contract:
+ *
+ *   exit 0 → allow (with structured stdout describing the decision)
+ *   exit 2 → block (stderr contains the BLOCKED: ... reason)
+ *
+ * Three decision paths:
+ *
+ *   1. `job-shape.json` exists with `decision.isJob === true`.
+ *      → allow, print `{ ok, allow, mode: 'job', decision }`. When a
+ *        matching `job/<jid>/progress.json` exists, also print
+ *        `Next: slice #<N+1> of <M> (<currentSlice>)` so the LLM sees
+ *        its resume context BEFORE any Bash call lands.
+ *   2. `job-shape.json` exists with `decision.isJob === false`.
+ *      → allow, print `{ ok, allow, mode: 'single' }`.
+ *   3. `job-shape.json` is MISSING — fail-closed guard. The LLM is the
+ *      source of truth, but if it never recorded a decision we run a
+ *      lightweight backup regex against the user's prompt:
+ *        /until|全部|until all done|disavow cost|不用考虑费用|all of them/i
+ *      match → block (exit 2) with the BLOCKED: stderr message.
+ *      no match → allow (exit 0) — most prompts are not Job-shaped.
+ *
+ * Karpathy §2 (Simplicity First): ~120 lines, no LLM call inside. The
+ * regex is the FIRST time peaks-loop accepts hardcoded keywords —
+ * explicitly scoped as a *fail-closed backup* (case 3), NOT a primary
+ * judgement. The LLM still owns the semantic call via
+ * `peaks solo detect-job`. The regex is a safety net for the v3.1.1
+ * incident class (LLM under load never records the decision at all).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJobShapeDecision, JobShapeDecisionError, JOB_SHAPE_NOT_DECIDED } from './job-shape-decision.js';
+export const STEP_08_GATE_FILE_NAME = 'job-shape.json';
+export const STEP_08_PROGRESS_FILE_NAME = 'progress.json';
+/**
+ * Fail-closed backup regex — see module docstring case 3 for why this
+ * exists. Kept short and explicit; if the prompt mentions any of these
+ * triggers and `job-shape.json` is missing, the LLM is treated as
+ * having skipped `peaks solo detect-job` and the gate blocks.
+ *
+ * The list mirrors the v3.1.0 / v3.1.1 incident triggers verbatim:
+ *   继续执行下个 slice (until next slice) → until / 直到
+ *   全部添加完 / all of them            → 全部 / all of them
+ *   不用考虑费用                        → 不用考虑费用 / disavow cost
+ *   until all done                      → until all done
+ */
+export const STEP_08_BACKUP_REGEX = /直到|全部|until all done|disavow cost|不用考虑费用|all of them/i;
+export function runtimeSessionDir(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId);
+}
+function progressPath(projectRoot, sessionId, jid) {
+    // The progress file lives under job/<jid>/progress.json. The jid
+    // comes from job-shape.json (decision.suggestedJobId) — there is
+    // exactly one canonical jid per session under Job mode, so we read
+    // the matching path directly rather than enumerating the job/ dir.
+    // (Rotating mode spawns new jids but only one is "active" at a time;
+    // the active jid is the latest write to job-shape.json.)
+    return join(runtimeSessionDir(projectRoot, sessionId), 'job', jid, STEP_08_PROGRESS_FILE_NAME);
+}
+function readProgressIfAny(projectRoot, sessionId, jid) {
+    const path = progressPath(projectRoot, sessionId, jid);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.jobId === 'string' &&
+            typeof parsed.done === 'number' &&
+            typeof parsed.total === 'number' &&
+            typeof parsed.currentSlice === 'string' &&
+            typeof parsed.updatedAt === 'string') {
+            return {
+                jobId: parsed.jobId,
+                done: parsed.done,
+                total: parsed.total,
+                currentSlice: parsed.currentSlice,
+                lastCommitSha: typeof parsed.lastCommitSha === 'string' ? parsed.lastCommitSha : null,
+                updatedAt: parsed.updatedAt
+            };
+        }
+        return null;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function readPromptFromLastPromptFile(projectRoot, sessionId) {
+    const path = join(runtimeSessionDir(projectRoot, sessionId), 'txt', 'last-prompt.txt');
+    if (!existsSync(path))
+        return '';
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Pure evaluator — does NOT write, does NOT exit. CLI wrapper in
+ * `src/cli/commands/solo-commands.ts` reads `allow` to set the process
+ * exit code (0 allow / 2 block) and prints the structured envelope.
+ */
+export function evaluateStep08(input) {
+    try {
+        const record = readJobShapeDecision(input.projectRoot, input.sessionId);
+        if (record.decision.isJob) {
+            const progress = readProgressIfAny(input.projectRoot, input.sessionId, record.decision.suggestedJobId);
+            const nextSliceLine = progress !== null
+                ? `Next: slice #${progress.done + 1} of ${progress.total} (${progress.currentSlice})`
+                : null;
+            return {
+                allow: true,
+                verdict: { kind: 'allow-job', decision: record.decision, progress },
+                nextSliceLine
+            };
+        }
+        return { allow: true, verdict: { kind: 'allow-single' }, nextSliceLine: null };
+    }
+    catch (err) {
+        if (err instanceof JobShapeDecisionError && err.code === JOB_SHAPE_NOT_DECIDED) {
+            const promptText = input.prompt ?? readPromptFromLastPromptFile(input.projectRoot, input.sessionId);
+            const hit = promptText.length > 0 && STEP_08_BACKUP_REGEX.test(promptText);
+            const source = input.prompt !== undefined ? 'flag' : promptText.length > 0 ? 'last-prompt-file' : 'stdin-empty';
+            if (hit) {
+                return { allow: false, verdict: { kind: 'block-missing-decision', promptHit: true, promptSource: source }, nextSliceLine: null };
+            }
+            return { allow: true, verdict: { kind: 'block-missing-decision', promptHit: false, promptSource: source }, nextSliceLine: null };
+        }
+        throw err;
+    }
+}

package/dist/src/services/standards/missing-standards-detector.d.ts

@@ -1,5 +1,5 @@
 /**
- * Slice 2026-06-16-peaks-solo-auto-scaffold (RD#7) — missing-standards-detector.
+ * Slice 2026-06-16-peaks-code-auto-scaffold (RD#7) — missing-standards-detector.
  *
  * Read-side companion to the `peaks standards init` / `peaks standards update`
  * writers in `./project-standards-service.ts`. The writer KNOWS how to scaffold

package/dist/src/services/standards/missing-standards-detector.js

@@ -1,5 +1,5 @@
 /**
- * Slice 2026-06-16-peaks-solo-auto-scaffold (RD#7) — missing-standards-detector.
+ * Slice 2026-06-16-peaks-code-auto-scaffold (RD#7) — missing-standards-detector.
  *
  * Read-side companion to the `peaks standards init` / `peaks standards update`
  * writers in `./project-standards-service.ts`. The writer KNOWS how to scaffold

package/dist/src/services/standards/project-standards-service.d.ts

@@ -30,7 +30,7 @@ export type ProjectStandardsSource = {
     readonly usage: 'curated-baseline-reference';
 };
 export type StandardsSkillPreflight = {
-    readonly appliesTo: readonly ['peaks-rd', 'peaks-qa', 'peaks-solo'];
+    readonly appliesTo: readonly ['peaks-rd', 'peaks-qa', 'peaks-code'];
     readonly summary: string;
 };
 export type ProjectStandardsInitPlan = {

package/dist/src/services/standards/project-standards-service.js

@@ -23,8 +23,8 @@ const SOURCE = {
     usage: 'curated-baseline-reference'
 };
 const SKILL_PREFLIGHT = {
-    appliesTo: ['peaks-rd', 'peaks-qa', 'peaks-solo'],
-    summary: 'peaks-rd、peaks-qa、peaks-solo 进入代码仓工作流时自动 preflight 项目规范。'
+    appliesTo: ['peaks-rd', 'peaks-qa', 'peaks-code'],
+    summary: 'peaks-rd、peaks-qa、peaks-code 进入代码仓工作流时自动 preflight 项目规范。'
 };
 const SUPPORTED_LANGUAGES = new Set(['generic', 'typescript', 'javascript', 'python', 'go', 'rust']);
 function normalizeRoot(path) {
@@ -104,7 +104,7 @@ function renderHeader(title) {
         `# ${title}`,
         '',
         'Source: Peaks curated baseline; everything-claude-code reference: https://github.com/affaan-m/everything-claude-code',
-        'Scope: project-local standards for peaks-rd, peaks-qa, and peaks-solo workflow preflight.',
+        'Scope: project-local standards for peaks-rd, peaks-qa, and peaks-code workflow preflight.',
         ''
     ].join('\n');
 }
@@ -151,7 +151,7 @@ function renderClaudeMd(language, ctx) {
         'Peaks workflow automation:',
         '- peaks-rd checks these standards before RD planning or implementation work.',
         '- peaks-qa checks code review and security guidance before verification work.',
-        '- peaks-solo summarizes RD and QA standards preflight before end-to-end code workflows.',
+        '- peaks-code summarizes RD and QA standards preflight before end-to-end code workflows.',
         '',
         'Rules:',
         '- Read `.claude/rules/common/coding-style.md` before editing code.',

package/dist/src/services/understand/understand-types.d.ts

@@ -33,7 +33,7 @@ export type UnderstandScanReport = {
 };
 /**
  * Slice L3.1 — opt-in prompt payload. When uaPrompt === 'unset' and UA is
- * absent, the peaks-solo / peaks-ide layer surfaces this to the user via
+ * absent, the peaks-code / peaks-ide layer surfaces this to the user via
  * AskUserQuestion. The CLI does not prompt directly; it returns this
  * payload so the LLM-side UX layer can decide.
  */

package/dist/src/services/upgrade/1x-detector-service.js

@@ -6,7 +6,7 @@
  *
  * The canonical implementation lives in the .mjs postinstall
  * (because the postinstall runs before any TS compile step).
- * This TS mirror exists so the peaks-solo skill can call
+ * This TS mirror exists so the peaks-code skill can call
  * `peaks upgrade --detect-1x --project <root> --json` and
  * read a structured JSON envelope to gate the
  * AskUserQuestion that prompts the 1.x → 2.0 upgrade.

package/dist/src/services/upgrade/upgrade-service.d.ts

@@ -1,3 +1,30 @@
+/**
+ * Pluggable executor for sub-step command spawns. Production
+ * callers omit `executor` on `UpgradeInput`; the default
+ * (`defaultSubstepExecutor`) wraps `node:child_process` `spawnSync`.
+ * Tests pass a synchronous fake executor to avoid the spawn cost.
+ *
+ * Contract:
+ *  - Return `status: 0` for success, non-zero for failure, `null`
+ *    for synchronous spawn errors (binary not found, EACCES, …).
+ *  - `stdout` / `stderr` are captured as UTF-8 strings.
+ *  - `durationMs` is the wall-clock duration of the spawn
+ *    (caller-facing field on `SubStepResult`).
+ */
+export type SubstepExecutor = (command: string, args: readonly string[], timeoutMs: number) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+};
+/**
+ * Default substep executor — wraps `spawnSync` with the same
+ * stdio / encoding / timeout config the umbrella has used since
+ * v1. Exported for test coverage: the seam-preservation test
+ * imports this directly to verify the normalized return shape
+ * on a spawn failure (e.g. a non-existent command).
+ */
+export declare const defaultSubstepExecutor: SubstepExecutor;
 export interface UpgradeInput {
     readonly projectRoot: string;
     /**
@@ -14,6 +41,13 @@ export interface UpgradeInput {
      * install hint in `nextActions` instead.
      */
     readonly peaksBin?: string;
+    /**
+     * Optional injectable executor for sub-step command execution.
+     * When omitted, the umbrella uses `defaultSubstepExecutor`
+     * (real `spawnSync`). Tests pass a synchronous fake to avoid
+     * the per-sub-step `node peaks.js …` spawn cost.
+     */
+    readonly executor?: SubstepExecutor;
 }
 export interface SubStepResult {
     readonly name: string;

package/dist/src/services/upgrade/upgrade-service.js

@@ -33,6 +33,38 @@ import { fileURLToPath } from 'node:url';
 import { runRedLinesAudit } from '../audit/red-lines-service.js';
 import { savePreferences } from '../preferences/preferences-service.js';
 import { migrateGitignoreFile } from './gitignore-migrate-service.js';
+/**
+ * Default substep executor — wraps `spawnSync` with the same
+ * stdio / encoding / timeout config the umbrella has used since
+ * v1. Exported for test coverage: the seam-preservation test
+ * imports this directly to verify the normalized return shape
+ * on a spawn failure (e.g. a non-existent command).
+ */
+export const defaultSubstepExecutor = (command, args, timeoutMs) => {
+    const start = Date.now();
+    try {
+        const result = spawnSync(command, args, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: timeoutMs,
+        });
+        return {
+            status: result.status,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? '',
+            durationMs: Date.now() - start,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            status: null,
+            stdout: '',
+            stderr: message,
+            durationMs: Date.now() - start,
+        };
+    }
+};
 const STEPS = [
     { name: 'config-migrate', args: (p) => ['config', 'migrate', '--project', p, '--apply', '--json'] },
     { name: 'standards-migrate', args: (p) => ['standards', 'migrate', '--from-claude-rules', '--project', p, '--apply', '--json'] },
@@ -145,8 +177,7 @@ function read1xVersion(cwd) {
     }
     return null;
 }
-function runStep(peaksBin, name, args, timeoutMs = 60_000) {
-    const start = Date.now();
+function runStep(peaksBin, name, args, timeoutMs = 60_000, executor = defaultSubstepExecutor) {
     // The global `peaks` shim is a `/bin/sh` symlink script (the
     // npm install postinstall creates `peaks` → `peaks.sh` on
     // Windows). cmd.exe (the default Windows shell) cannot run
@@ -168,32 +199,18 @@ function runStep(peaksBin, name, args, timeoutMs = 60_000) {
         command = peaksBin;
         spawnArgs = args;
     }
-    try {
-        const result = spawnSync(command, spawnArgs, {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'pipe'],
-            timeout: timeoutMs,
-        });
-        return {
-            name,
-            status: result.status === 0 ? 'pass' : 'fail',
-            exitCode: result.status,
-            stdout: result.stdout ?? '',
-            stderr: result.stderr ?? '',
-            durationMs: Date.now() - start,
-        };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-            name,
-            status: 'fail',
-            exitCode: null,
-            stdout: '',
-            stderr: message,
-            durationMs: Date.now() - start,
-        };
-    }
+    // The executor normalizes spawn errors to { status: null, stderr: ... }
+    // so no try/catch wrapper is needed here — the call always returns
+    // a shaped record. See defaultSubstepExecutor for the reference impl.
+    const result = executor(command, spawnArgs, timeoutMs);
+    return {
+        name,
+        status: result.status === 0 ? 'pass' : 'fail',
+        exitCode: result.status,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        durationMs: result.durationMs,
+    };
 }
 function writeUpgradeRecord(projectRoot, result) {
     try {
@@ -260,6 +277,11 @@ export function runUpgrade(input) {
         resolve(here, '..', '..', '..', '..', 'bin', 'peaks.js');
     const fallbackPeaks = 'peaks';
     const resolvedPeaksBin = existsSync(peaksBin) ? peaksBin : fallbackPeaks;
+    // Resolve the executor once at the top of runUpgrade so every
+    // sub-step call shares the same instance. Tests pass a fake
+    // executor via UpgradeInput.executor; production callers omit
+    // it and get the default spawnSync wrapper.
+    const executor = input.executor ?? defaultSubstepExecutor;
     const fromVersion = read1xVersion(input.projectRoot);
     const steps = [];
     const warnings = [];
@@ -325,7 +347,7 @@ export function runUpgrade(input) {
                 continue;
             }
             const args = ['memory', 'extract', '--project', input.projectRoot, '--artifact', ...artifacts, '--apply', '--json'];
-            const r = runStep(resolvedPeaksBin, 'memory-extract', args);
+            const r = runStep(resolvedPeaksBin, 'memory-extract', args, 60_000, executor);
             steps.push(r);
             if (r.status === 'fail') {
                 warnings.push(`memory-extract failed: ${r.stderr.slice(0, 200)}`);
@@ -333,7 +355,7 @@ export function runUpgrade(input) {
             continue;
         }
         const args = step.args(input.projectRoot);
-        const r = runStep(resolvedPeaksBin, step.name, args);
+        const r = runStep(resolvedPeaksBin, step.name, args, 60_000, executor);
         steps.push(r);
         if (r.status === 'fail') {
             warnings.push(`${step.name} failed: ${r.stderr.slice(0, 200)}`);

package/dist/src/services/verdict/verdict-aggregator.d.ts

@@ -1,5 +1,5 @@
 /**
- * peaks-solo multi-signal verdict aggregator (v2.13.1 Group A).
+ * peaks-code multi-signal verdict aggregator (v2.13.1 Group A).
  *
  * Implements the 4 aggregation rules documented in
  * `.peaks/project-scan/audit-output-schema.md:66-78` plus 3rd-party