peaks-loop 3.1.2 → 4.0.0-beta.2

package/dist/src/services/{solo → code}/mode-gate.js

@@ -19,7 +19,7 @@
  * Re-uses `SkillPresenceMode` from `skill-presence-service.ts` so the
  * 4 mode values stay in lockstep with the rest of the runtime.
  */
-export const SOLO_MODES = [
+export const CODE_MODES = [
     'full-auto',
     'assisted',
     'swarm',
@@ -47,8 +47,8 @@ export const GATED_STEPS = [
     'step-0.75-checkpoint-resume',
     'standards-preflight'
 ];
-export function isSoloMode(value) {
-    return SOLO_MODES.includes(value);
+export function isCodeMode(value) {
+    return CODE_MODES.includes(value);
 }
 export function isHardFloorCategory(value) {
     return HARD_FLOOR_CATEGORIES.includes(value);
@@ -75,7 +75,7 @@ export function isCommitBoundaryAction(value) {
  * Hard-pause steps: these pause regardless of mode. They are the gates
  * whose decision *creates* or *recreates* the mode/state under which
  * later gates run. Auto-proceeding on them would silently fix the mode
- * without user consent (defect #1: new Solo session skipped Step 1
+ * without user consent (defect #1: new Code session skipped Step 1
  * AskUserQuestion because `full-auto` mode triggered `shouldAutoProceed`
  * on `step-1-mode-select` itself).
  *
@@ -115,7 +115,7 @@ export function shouldPauseAtGate(opts) {
             gateKind: 'hard-floor'
         };
     }
-    // Slice 2026-06-28-solo-mode-bypass-fix: hard-pause steps that
+    // Slice 2026-06-28-code-mode-bypass-fix: hard-pause steps that
     // determine the active mode or session context MUST prompt the
     // user. Otherwise full-auto silently locks in `mode=full-auto` on
     // the first tool call, skipping the AskUserQuestion Step 1 mandates.

package/dist/src/services/{solo → code}/post-compact-detector.d.ts

@@ -7,7 +7,7 @@
  *   1. `.peaks/_runtime/<sessionId>/` is bound
  *   2. Latest checkpoint mtime is from today (UTC date)
  *   3. Latest checkpoint has a parseable `mode` field
- *   4. The peak-solo skill is the active skill
+ *   4. The peak-code skill is the active skill
  *   5. Exactly one session has a today's checkpoint (no ambiguity)
  *
  * On a hit, the LLM MUST auto-resume (D7.b override of "never silently
@@ -22,13 +22,13 @@
  * No writes (caller logs the decision via the auto-decisions channel).
  */
 import type { SkillPresenceMode } from '../skills/skill-presence-service.js';
-import { type SoloMode } from './mode-gate.js';
+import { type CodeMode } from './mode-gate.js';
 export type PostCompactResumeReason = 'post-compact-match' | 'sid-unbound' | 'runtime-dir-missing' | 'no-checkpoint-today' | 'no-mode-field' | 'stale-checkpoint' | 'multiple-checkpoints-ambiguous' | 'active-skill-mismatch' | 'checkpoint-read-failed';
 export declare const POST_COMPACT_RESUME_REASONS: readonly PostCompactResumeReason[];
 export interface PostCompactResumeProbe {
     readonly shouldAutoResume: boolean;
     readonly reason: PostCompactResumeReason;
-    readonly mode?: SoloMode;
+    readonly mode?: CodeMode;
     readonly checkpointPath?: string;
     readonly checkpointMtime?: string;
     readonly task?: string;

package/dist/src/services/{solo → code}/post-compact-detector.js

@@ -7,7 +7,7 @@
  *   1. `.peaks/_runtime/<sessionId>/` is bound
  *   2. Latest checkpoint mtime is from today (UTC date)
  *   3. Latest checkpoint has a parseable `mode` field
- *   4. The peak-solo skill is the active skill
+ *   4. The peak-code skill is the active skill
  *   5. Exactly one session has a today's checkpoint (no ambiguity)
  *
  * On a hit, the LLM MUST auto-resume (D7.b override of "never silently
@@ -25,7 +25,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { getSkillPresence } from '../skills/skill-presence-service.js';
 import { emitObservabilityEvent } from '../observability/observability-service.js';
-import { isSoloMode } from './mode-gate.js';
+import { isCodeMode } from './mode-gate.js';
 export const POST_COMPACT_RESUME_REASONS = [
     'post-compact-match',
     'sid-unbound',
@@ -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,13 +154,13 @@ 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
     // (test seam) or to a fresh skill-presence read.
     let mode;
-    if (isSoloMode(checkpointMode)) {
+    if (isCodeMode(checkpointMode)) {
         mode = checkpointMode;
     }
     else if (opts.presenceModeOverride !== undefined) {
@@ -170,7 +170,7 @@ export async function detectPostCompactResume(opts) {
         try {
             const presence = getSkillPresence(opts.projectRoot);
             const presenceMode = presence?.mode;
-            if (presenceMode !== undefined && isSoloMode(presenceMode)) {
+            if (presenceMode !== undefined && isCodeMode(presenceMode)) {
                 mode = presenceMode;
             }
         }

package/dist/src/services/{solo → code}/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 → code}/step-08-gate.d.ts

@@ -3,7 +3,7 @@
  *
  * 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
+ * bypass). The hook runs `peaks code 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)
@@ -29,7 +29,7 @@
  * 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
+ * `peaks code 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";
@@ -38,7 +38,7 @@ 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.
+ * having skipped `peaks code detect-job` and the gate blocks.
  *
  * The list mirrors the v3.1.0 / v3.1.1 incident triggers verbatim:
  *   继续执行下个 slice (until next slice) → until / 直到
@@ -84,7 +84,7 @@ export interface EvaluateStep08Result {
 }
 /**
  * Pure evaluator — does NOT write, does NOT exit. CLI wrapper in
- * `src/cli/commands/solo-commands.ts` reads `allow` to set the process
+ * `src/cli/commands/code-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 → code}/step-08-gate.js

@@ -3,7 +3,7 @@
  *
  * 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
+ * bypass). The hook runs `peaks code 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)
@@ -29,7 +29,7 @@
  * 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
+ * `peaks code 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';
@@ -41,7 +41,7 @@ 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.
+ * having skipped `peaks code detect-job` and the gate blocks.
  *
  * The list mirrors the v3.1.0 / v3.1.1 incident triggers verbatim:
  *   继续执行下个 slice (until next slice) → until / 直到
@@ -102,7 +102,7 @@ function readPromptFromLastPromptFile(projectRoot, sessionId) {
 }
 /**
  * Pure evaluator — does NOT write, does NOT exit. CLI wrapper in
- * `src/cli/commands/solo-commands.ts` reads `allow` to set the process
+ * `src/cli/commands/code-commands.ts` reads `allow` to set the process
  * exit code (0 allow / 2 block) and prints the structured envelope.
  */
 export function evaluateStep08(input) {

package/dist/src/services/{solo → code}/user-touchpoint-classifier.d.ts

@@ -2,7 +2,7 @@
  * v2.15.0 follow-up — G4: user touchpoint classifier.
  *
  * 12 Gaps positioning memory: "user 介入 = 业务/产品审阅,不是技术决策".
- * This service classifies every Solo gate by the kind of decision it
+ * This service classifies every Code gate by the kind of decision it
  * represents, so the CLI / status line can show user which gates
  * actually need their attention vs which are technical defaults
  * (AI auto-decides in full-auto).

package/dist/src/services/{solo → code}/user-touchpoint-classifier.js

@@ -2,7 +2,7 @@
  * v2.15.0 follow-up — G4: user touchpoint classifier.
  *
  * 12 Gaps positioning memory: "user 介入 = 业务/产品审阅,不是技术决策".
- * This service classifies every Solo gate by the kind of decision it
+ * This service classifies every Code gate by the kind of decision it
  * represents, so the CLI / status line can show user which gates
  * actually need their attention vs which are technical defaults
  * (AI auto-decides in full-auto).

package/dist/src/services/context/auto-compact-dispatcher.d.ts

@@ -7,11 +7,11 @@ export interface DispatchIdeCompactInput {
     /** Spawn timeout (ms). Default 30s — Claude Code `/compact` is sync. */
     readonly timeoutMs?: number | undefined;
     /**
-     * Slice 2026-06-28-solo-mode-bypass-fix (defect #4): which session
+     * Slice 2026-06-28-code-mode-bypass-fix (defect #4): which session
      * the compact should target. Default `'main'` — the orchestrator
-     * (peaks-solo body) runs in the main-session Claude Code window and
+     * (peaks-code body) runs in the main-session Claude Code window and
      * wants to compress *its* context, not a sub-agent's. Sub-agent
-     * shells that spawn their own `peaks solo auto-compact` flow pass
+     * shells that spawn their own `peaks code auto-compact` flow pass
      * `'sub-agent'` to preserve the legacy shell-spawn behaviour.
      *
      * Behaviour matrix (claude-code MVP):

package/dist/src/services/context/auto-compact-dispatcher.js

@@ -47,7 +47,7 @@ export async function dispatchIdeCompact(input) {
     // See auto-compact-reader.ts for the IdeKind→IdeId cast rationale.
     const ideId = (detected === 'unknown' ? 'claude-code' : detected);
     const adapter = getAdapter(ideId);
-    // Slice 2026-06-28-solo-mode-bypass-fix (defect #4): default to
+    // Slice 2026-06-28-code-mode-bypass-fix (defect #4): default to
     // `'main'` so the orchestrator's auto-compact actually compresses
     // the main-session context. The orchestrator passes `'sub-agent'`
     // explicitly when a sub-agent shell dispatches the call.
@@ -123,7 +123,7 @@ export async function dispatchIdeCompact(input) {
                 });
             }
             // Lazy install: we only get here when the caller explicitly
-            // invokes `peaks solo auto-compact --execute`, so the user has
+            // invokes `peaks code auto-compact --execute`, so the user has
             // already opted in. No zero-touch surprise on workspace init.
             return await dispatchIdeNativeHook({
                 projectRoot: input.projectRoot,

package/dist/src/services/context/auto-compact-types.d.ts

@@ -107,7 +107,7 @@ export type AutoCompactResult = {
         readonly convergencePlan?: ConvergencePlan;
         readonly dispatch?: CompactDispatchResult;
         /**
-         * Slice 2026-06-28-solo-mode-bypass-fix (defect #4): which
+         * Slice 2026-06-28-code-mode-bypass-fix (defect #4): which
          * session the compact targeted. `'main'` (default) means the
          * main-session Claude Code window will fire `/compact` on its
          * next turn; `'sub-agent'` means the dispatcher shell-spawned

package/dist/src/services/dispatch/batch-counter.js

@@ -3,7 +3,7 @@
  *
  * Empirical upper bound for one Dispatcher × one batch: 6 sub-agents.
  * Above 6, the LLM / human is encouraged to split into multiple
- * batches with an explicit reducer step in between. peaks-solo's
+ * batches with an explicit reducer step in between. peaks-code's
  * swarm phase dispatches 3; peaks-rd's 4-way fan-out dispatches 4;
  * peaks-qa's 3-way fan-out dispatches 3. The 6 limit leaves headroom
  * for "qa-business-api" / "qa-business-frontend" / "qa-business-regression"

package/dist/src/services/dispatch/leak-detector.js

@@ -1,7 +1,7 @@
 /**
  * Slice #009 / G5 RL-7 — dispatch record leak detector.
  *
- * After peaks-solo's reducer consumes a batch, any dispatch record that
+ * After peaks-code's reducer consumes a batch, any dispatch record that
  * is still `disposed === false` AND was created more than `thresholdMs`
  * ago is a **leak**. This helper scans the on-disk records under
  * `.peaks/_sub_agents/<sid>/` and returns the leaked ones. The CLI or

package/dist/src/services/dispatch/slice-dag.d.ts

@@ -1,6 +1,6 @@
 /**
  * Slice complexity tier (v2.15.0 follow-up, G2 in 12 Gaps).
- * Used by Solo to schedule complex slices during user-attended hours
+ * Used by Code to schedule complex slices during user-attended hours
  * and trivial / simple slices overnight.
  */
 export type SliceComplexity = 'trivial' | 'simple' | 'complex';
@@ -27,7 +27,7 @@ export interface SliceNode {
      */
     readonly upstreamSync?: boolean;
     /**
-     * v2.15.0 follow-up — G2: complexity tier. Drives Solo's scheduling
+     * v2.15.0 follow-up — G2: complexity tier. Drives Code's scheduling
      * (complex = user-attended, simple/trivial = overnight). Optional.
      */
     readonly complexity?: SliceComplexity;

package/dist/src/services/dispatch/test-tool-detection.d.ts

@@ -4,7 +4,7 @@
  * The Test Tool Detection block is prepended to every sub-agent prompt
  * dispatched by peaks-loop (both the single-dispatch chokepoint in
  * `src/cli/commands/dispatch-commands.ts` and the DAG-dispatch chokepoint
- * in `src/services/solo/dag-orchestrator.ts`). It tells the sub-agent
+ * in `src/services/code/dag-orchestrator.ts`). It tells the sub-agent
  * to read `package.json#scripts.test` first and use the project-local
  * runner — never `npx <runner>` — so it cannot bypass the lockfile or
  * spawn a network-bound tool call.

package/dist/src/services/dispatch/test-tool-detection.js

@@ -4,7 +4,7 @@
  * The Test Tool Detection block is prepended to every sub-agent prompt
  * dispatched by peaks-loop (both the single-dispatch chokepoint in
  * `src/cli/commands/dispatch-commands.ts` and the DAG-dispatch chokepoint
- * in `src/services/solo/dag-orchestrator.ts`). It tells the sub-agent
+ * in `src/services/code/dag-orchestrator.ts`). It tells the sub-agent
  * to read `package.json#scripts.test` first and use the project-local
  * runner — never `npx <runner>` — so it cannot bypass the lockfile or
  * spawn a network-bound tool call.

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

@@ -538,7 +538,7 @@ export async function runDoctor(options = {}) {
             }
         }
     }
-    // Workspace guard: an active workflow presence (peaks-solo) with no workspace
+    // Workspace guard: an active workflow presence (peaks-code) with no workspace
     // session means the skill was anchored but `peaks workspace init` never ran —
     // the #1 reported failure where .peaks/ artifacts are never created. This
     // turns the SKILL.md "MUST create the workspace" prose into an executable check.
@@ -554,7 +554,7 @@ export async function runDoctor(options = {}) {
         checks.push({
             id: 'skill-presence:workspace',
             ok: false,
-            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/_runtime/session.json missing); run \`peaks workspace init --project <repo>\` — peaks-solo Step 0 must anchor the workspace before any work`
+            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/_runtime/session.json missing); run \`peaks workspace init --project <repo>\` — peaks-code Step 0 must anchor the workspace before any work`
         });
     }
     else {

package/dist/src/services/feedback/feedback-promotion-service.js

@@ -223,8 +223,8 @@ export function generatePromotionStub(opts) {
     }
     // layer === 'C'
     return {
-        snippet: `// src/services/solo/mode-gate.ts\n// 1. Add to HardFloorCategory union: '${feedbackName}-rule'\n// 2. Add to HARD_FLOOR_CATEGORIES\n// 3. Wire shouldPauseAtGate to recognise the new category\n// Tests: tests/unit/services/solo/<name>-hard-floor.test.ts (≥6 cases per AC-4)`,
-        targetFiles: ['src/services/solo/mode-gate.ts', `tests/unit/services/solo/${feedbackName}-hard-floor.test.ts`]
+        snippet: `// src/services/code/mode-gate.ts\n// 1. Add to HardFloorCategory union: '${feedbackName}-rule'\n// 2. Add to HARD_FLOOR_CATEGORIES\n// 3. Wire shouldPauseAtGate to recognise the new category\n// Tests: tests/unit/services/code/<name>-hard-floor.test.ts (≥6 cases per AC-4)`,
+        targetFiles: ['src/services/code/mode-gate.ts', `tests/unit/services/code/${feedbackName}-hard-floor.test.ts`]
     };
 }
 /**

package/dist/src/services/job/job-progress-store.d.ts

@@ -10,7 +10,7 @@
  *     jobId, done, total, currentSlice, lastCommitSha, updatedAt
  *   }
  *
- * The `peaks solo gate-step-08` hook reads this file in its case-1 path
+ * The `peaks code gate-step-08` hook reads this file in its case-1 path
  * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
  * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
  * next-slice context is mechanically injected on every Bash call.

package/dist/src/services/job/job-progress-store.js

@@ -10,7 +10,7 @@
  *     jobId, done, total, currentSlice, lastCommitSha, updatedAt
  *   }
  *
- * The `peaks solo gate-step-08` hook reads this file in its case-1 path
+ * The `peaks code gate-step-08` hook reads this file in its case-1 path
  * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
  * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
  * next-slice context is mechanically injected on every Bash call.

package/dist/src/services/job/job-resource-snapshot.js

@@ -26,10 +26,37 @@ export function collectResourceSnapshot(jobDir) {
         contextRatio,
     };
 }
-function dirSizeMb(dir) {
+// Non-enumerable internal attachment for test-time access via
+// `collectResourceSnapshot.dirSizeMb`. NOT a public export — keeps
+// the prod module surface clean per PRD while still allowing
+// targeted AC-1/AC-2/AC-3 unit tests to drive `dirSizeMb` directly.
+Object.defineProperty(collectResourceSnapshot, 'dirSizeMb', {
+    value: dirSizeMb,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+});
+/**
+ * Best-effort, non-recursive size of one directory level, in rounded megabytes.
+ *
+ * - Missing directory → 0.
+ * - Per-entry stat failures (race with deletion, EBUSY on Windows) → silently skipped.
+ * - When `opts.maxEntries` > 0 and the directory has more entries than the cap,
+ *   the returned value is a partial sum (a lower bound), and no further `stat`
+ *   calls are issued past the cap. Callers must treat the value as a lower bound.
+ * - `opts.maxEntries` defaults to 0 (unbounded, legacy behaviour).
+ *
+ * NOTE: when maxEntries > 0 and the directory contains more entries than the
+ * cap, this is a partial sum. Callers must treat the value as a lower bound.
+ */
+function dirSizeMb(dir, opts) {
+    const cap = opts?.maxEntries ?? 0;
     let total = 0;
+    let index = 0;
     try {
         for (const name of readdirSync(dir)) {
+            if (cap > 0 && index >= cap)
+                break;
             try {
                 total += statSync(join(dir, name)).size;
             }
@@ -37,6 +64,7 @@ function dirSizeMb(dir) {
                 // best-effort: missing entries (race with deletion) are silently skipped
                 void e;
             }
+            index++;
         }
     }
     catch (e) {

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

@@ -600,7 +600,7 @@ export function executeProjectMemoryExtract(options) {
         const safeMemoryDir = assertSafeProjectMemoryDir(plan.projectRoot);
         // Idempotency: skip writes for memories whose slug already lives in
         // .peaks/memory/. Re-running `peaks memory extract --apply` on the
-        // same handoff is a normal peaks-solo / peaks-txt retry pattern (the
+        // same handoff is a normal peaks-code / peaks-txt retry pattern (the
         // skill prompt may invoke extract more than once when a handoff is
         // edited and re-extracted). Without this, writeNewFile's O_EXCL
         // throws EEXIST and aborts the whole batch. Symmetric with

package/dist/src/services/migrate-skill-name/migrate.d.ts

@@ -0,0 +1,17 @@
+import type { MigrateResult } from './schema.js';
+export interface MigrateOpts {
+    projectRoot: string;
+    from: string;
+    to: string;
+    /** false = dry-run (default); true = write through. */
+    apply: boolean;
+}
+/** True iff `absPath` falls under any skip-path (substring match). */
+export declare function shouldSkip(projectRoot: string, absPath: string): boolean;
+/**
+ * Recursively walk a directory and return every `.json` / `.md`
+ * path. Missing root → empty list (the CLI reports scannedFiles:0,
+ * which is the truthful "nothing to look at" signal).
+ */
+export declare function walkRuntimeFiles(root: string): string[];
+export declare function migrateSkillName(opts: MigrateOpts): MigrateResult;

package/dist/src/services/migrate-skill-name/migrate.js

@@ -0,0 +1,152 @@
+/**
+ * `peaks session migrate-skill-name` core service (slice 2 of the
+ * peaks-code → peaks-code rename plan).
+ *
+ * Walks `.peaks/_runtime/**` and rewrites two patterns:
+ *   1. Key-value:   `"skill": "<old>"`  →  `"skill": "<new>"`
+ *   2. Slash-trig:  `/<old>`            →  `/<new>`
+ *
+ * Files under known skip-paths (`.peaks/memory/**`,
+ * `.peaks/skills/.system/bees/<old>/manifest.json`) are recorded in
+ * `skipped` but never opened. The operation is idempotent: re-running
+ * with the same `--from` on a tree already migrated reports 0
+ * modifications.
+ *
+ * Dry-run (`apply: false`) counts what WOULD change without writing;
+ * apply (`apply: true`) validates each `.json` payload with
+ * `JSON.parse` before writing so a broken mid-edit never lands on
+ * disk. Errors are pushed into `result.errors` (never swallowed).
+ */
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+/**
+ * Skip-paths are matched against the path relative to `projectRoot`,
+ * forward-slashed (Windows-friendly). Each entry is a SUBSTRING —
+ * the brief pins two specific exclusions: the memory dir, and the
+ * .system bee manifest for the old skill (which the renamer must
+ * leave alone until the bee itself is moved in a later slice).
+ */
+const SKIP_DIRS = ['.peaks/memory', '.peaks/skills/.system/bees'];
+const TARGET_ROOT = '.peaks/_runtime';
+const KEY_VALUE_PATTERN = (from, to) => new RegExp(`"skill"\\s*:\\s*"${escapeRe(from)}"`, 'g');
+const STRING_PATTERN = (from, to) => new RegExp(`/${escapeRe(from)}`, 'g');
+/**
+ * Escape regex metachars so an aggressive `--from` value (e.g.
+ * `peaks.code`) doesn't blow up the regex compiler. The two regexes
+ * above use `from` inside both body and character-class territory,
+ * so escaping is the safe path regardless of input.
+ */
+function escapeRe(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** True iff `absPath` falls under any skip-path (substring match). */
+export function shouldSkip(projectRoot, absPath) {
+    const rel = relative(projectRoot, absPath).replace(/\\/g, '/');
+    return SKIP_DIRS.some((skip) => rel.includes(skip));
+}
+/**
+ * Recursively walk a directory and return every `.json` / `.md`
+ * path. Missing root → empty list (the CLI reports scannedFiles:0,
+ * which is the truthful "nothing to look at" signal).
+ */
+export function walkRuntimeFiles(root) {
+    const out = [];
+    if (!existsSync(root))
+        return out;
+    const visit = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            const full = join(dir, entry);
+            const stat = statSync(full);
+            if (stat.isDirectory()) {
+                visit(full);
+            }
+            else if (entry.endsWith('.json') || entry.endsWith('.md')) {
+                out.push(full);
+            }
+        }
+    };
+    visit(root);
+    return out;
+}
+export function migrateSkillName(opts) {
+    const runtimeRoot = join(opts.projectRoot, TARGET_ROOT);
+    const files = walkRuntimeFiles(runtimeRoot);
+    const result = {
+        ok: true,
+        scannedFiles: files.length,
+        modifiedFiles: 0,
+        keyValueReplacements: 0,
+        stringReplacements: 0,
+        skipped: [...SKIP_DIRS],
+        errors: [],
+    };
+    for (const file of files) {
+        if (shouldSkip(opts.projectRoot, file))
+            continue;
+        let original;
+        try {
+            original = readFileSync(file, 'utf-8');
+        }
+        catch (e) {
+            // Unreadable file: surface the error and keep going (other
+            // files may be fine). `ok` flips to false; reporting stops
+            // hiding the failure from the operator.
+            result.errors.push(`${file}: read failed: ${e.message}`);
+            result.ok = false;
+            continue;
+        }
+        // Pin the broken-JSON test: any .json runtime file that fails
+        // to parse MUST be surfaced as an error, EVEN when it does not
+        // contain the from-name (the operator still needs to know the
+        // file is unparseable so they can fix it before re-running).
+        // Per Karpathy §4 honesty, silent skip is the worst kind of
+        // fake-green.
+        if (file.endsWith('.json')) {
+            try {
+                JSON.parse(original);
+            }
+            catch (e) {
+                result.errors.push(`${file}: invalid JSON: ${e.message}`);
+                result.ok = false;
+                continue;
+            }
+        }
+        let mutated = original;
+        const kvPattern = KEY_VALUE_PATTERN(opts.from, opts.to);
+        const kvMatches = mutated.match(kvPattern);
+        if (kvMatches) {
+            mutated = mutated.replace(kvPattern, `"skill": "${opts.to}"`);
+            result.keyValueReplacements += kvMatches.length;
+        }
+        const strPattern = STRING_PATTERN(opts.from, opts.to);
+        const strMatches = mutated.match(strPattern);
+        if (strMatches) {
+            mutated = mutated.replace(strPattern, `/${opts.to}`);
+            result.stringReplacements += strMatches.length;
+        }
+        if (mutated === original)
+            continue;
+        if (opts.apply) {
+            try {
+                if (file.endsWith('.json')) {
+                    // Validate the post-edit JSON before touching the disk —
+                    // catches accidents (e.g., stray quotes in the renamed
+                    // from/to values) without leaving a corrupted runtime file
+                    // behind.
+                    JSON.parse(mutated);
+                }
+                writeFileSync(file, mutated, 'utf-8');
+                result.modifiedFiles += 1;
+            }
+            catch (e) {
+                result.errors.push(`${file}: ${e.message}`);
+                result.ok = false;
+            }
+        }
+        // Dry-run path intentionally does not bump `modifiedFiles` —
+        // pin: `expect(result.modifiedFiles).toBe(0)` in the dry-run
+        // test. The would-be count lives implicitly in the *Replacement
+        // counters, which both dry-run and apply share.
+    }
+    return result;
+}