peaks-loop 4.0.29 → 4.0.31

package/dist/services/standards/standards-render.js

@@ -0,0 +1,238 @@
+/**
+ * Pure render / template functions extracted from
+ * `project-standards-service.ts` (slice 2026-09-06-split-batch-b) so the
+ * service stays under the 800-line cap. Behaviour-preserving verbatim move;
+ * `export` keywords were added to the symbols the service still imports.
+ */
+import { buildToolLabel, componentLibraryLabel, cssFrameworkLabel } from './project-context.js';
+function renderHeader(title) {
+    return [
+        `# ${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-code workflow preflight.',
+        ''
+    ].join('\n');
+}
+function renderProjectStackSection(ctx) {
+    if (!ctx.hasPackageJson)
+        return '';
+    const lines = ['## Detected project stack', ''];
+    lines.push(`- Build tool: ${buildToolLabel(ctx.buildTool)}${ctx.buildConfigPath !== undefined ? ` (\`${ctx.buildConfigPath}\`)` : ''}`);
+    lines.push(`- Component library: ${componentLibraryLabel(ctx.componentLibrary)}`);
+    if (ctx.cssFrameworks.length > 0) {
+        lines.push(`- CSS: ${ctx.cssFrameworks.map(cssFrameworkLabel).join(', ')}`);
+    }
+    if (ctx.stateManagement.length > 0)
+        lines.push(`- State management: ${ctx.stateManagement.join(', ')}`);
+    if (ctx.routing.length > 0)
+        lines.push(`- Routing: ${ctx.routing.join(', ')}`);
+    if (ctx.dataFetching.length > 0)
+        lines.push(`- Data fetching: ${ctx.dataFetching.join(', ')}`);
+    if (ctx.notableDeps.length > 0)
+        lines.push(`- Notable deps: ${ctx.notableDeps.join(', ')}`);
+    lines.push('');
+    if (ctx.cssConflicts.length > 0) {
+        lines.push('## CSS framework conflicts', '');
+        for (const conflict of ctx.cssConflicts)
+            lines.push(`- ${conflict}`);
+        lines.push('');
+    }
+    if (ctx.legacySignals.length > 0) {
+        lines.push('## Legacy constraints (preserve for new code in the same modules)', '');
+        for (const signal of ctx.legacySignals)
+            lines.push(`- ${signal}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function renderClaudeMd(language, ctx) {
+    const head = [
+        '# Project Instructions',
+        '',
+        '> 🤖 AI 生成，请审阅',
+        '',
+        'This repository uses project-local Peaks standards. Existing repository conventions override generic generated guidance.',
+        '',
+        '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-code summarizes RD and QA standards preflight before end-to-end code workflows.',
+        '',
+        'Rules:',
+        '- Read `.peaks/standards/common/coding-style.md` before editing code.',
+        '- Read `.peaks/standards/common/code-review.md` before reviewing changes.',
+        '- Read `.peaks/standards/common/security.md` before touching filesystem, user input, external calls, auth, or secrets.',
+        `- Read .peaks/standards/${language}/coding-style.md for language-specific standards when applicable.`,
+        '',
+        'Active Peaks-Loop skill presence: at the start of every response, run `peaks skill presence --json` to read the active skill marker. The CLI handles canonical-path resolution (`.peaks/_runtime/active-skill.json` with back-compat fallback to `.peaks/.active-skill.json`); do not read those files directly. When the response includes a valid skill name, display the compact status header: `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`. Display the header on every turn while the CLI returns an active skill; omit when the CLI returns no active skill.'
+    ].join('\n');
+    const stack = renderProjectStackSection(ctx);
+    return stack === '' ? head : `${head}\n${stack}`;
+}
+export function renderCommonCodingStyle(ctx) {
+    const baseRules = [
+        '- Prefer simple, readable code over clever abstractions.',
+        '- Keep functions focused and files cohesive.',
+        '- Use immutable updates unless a language-specific convention explicitly favors mutation.',
+        '- Validate user input, external data, file paths, and configuration at system boundaries.',
+        '- Preserve existing project conventions when they are stricter than this baseline.'
+    ];
+    const stackRules = [];
+    const lib = ctx.componentLibrary.name;
+    if (lib === 'antd' || lib === 'antd-pro') {
+        const major = ctx.componentLibrary.majorVersion ?? '5';
+        stackRules.push(`- Use existing antd v${major} components (\`Button\`, \`Form\`, \`Table\`, \`Modal\`, \`Select\`). Never mix antd v3/v4/v5 APIs.`);
+        stackRules.push(`- Customize antd via \`theme.token\` / \`ConfigProvider\` / \`className\` / \`styles\`. Do NOT apply TailwindCSS utility classes directly to antd components.`);
+        if (ctx.componentLibrary.hasProSuite === true) {
+            stackRules.push('- Use `@ant-design/pro-components` (`ProTable`, `ProForm`, `ProLayout`) where the page is already pro-based — do not introduce a parallel non-pro table/form.');
+        }
+    }
+    if (lib === 'mui')
+        stackRules.push('- Style MUI via `sx`, `styled()`, and `theme`. Do NOT apply TailwindCSS utility classes directly to MUI components.');
+    if (ctx.cssFrameworks.includes('tailwind') && (lib === 'antd' || lib === 'antd-pro' || lib === 'mui')) {
+        stackRules.push('- TailwindCSS is for layout/utility only; component-library tokens own component styling.');
+    }
+    if (ctx.cssFrameworks.includes('less'))
+        stackRules.push('- Less variables in `src/theme/*.less` (or equivalent) are the canonical design tokens — extend them, do not hardcode colors/spacing.');
+    if (ctx.stateManagement.length > 0)
+        stackRules.push(`- Follow the existing state library (${ctx.stateManagement.join(', ')}); do not introduce a competing state library.`);
+    if (ctx.dataFetching.length > 0)
+        stackRules.push(`- Reuse the existing data-fetching pattern (${ctx.dataFetching.join(', ')}) for new API calls.`);
+    for (const signal of ctx.legacySignals)
+        stackRules.push(`- ${signal}`);
+    const rules = stackRules.length > 0 ? [...baseRules, '', '## Project-specific rules', ...stackRules] : baseRules;
+    return `${renderHeader('Common Coding Standards')}${rules.join('\n')}\n`;
+}
+export function renderCodeReview(ctx) {
+    const baseRules = [
+        '- Review diffs for correctness, maintainability, test coverage, and regression risk.',
+        '- Treat missing tests for changed behavior as a blocker unless the change is documentation-only.',
+        '- Verify code paths that handle filesystem, external APIs, credentials, user input, or generated artifacts.',
+        '- peaks-qa must use this guidance as part of code workflow preflight and final verification.'
+    ];
+    const extra = [];
+    const lib = ctx.componentLibrary.name;
+    if (lib === 'antd' || lib === 'antd-pro') {
+        extra.push('- Block PRs that introduce a second component library (MUI/Chakra) alongside antd.');
+        extra.push('- Block PRs that import antd v3/v4 APIs in this v5 project, or vice versa.');
+    }
+    if (ctx.cssFrameworks.includes('tailwind') && (lib === 'antd' || lib === 'antd-pro' || lib === 'mui')) {
+        extra.push('- Flag Tailwind utility classes applied directly to component-library primitives; require component-library APIs instead.');
+    }
+    if (ctx.legacySignals.length > 0) {
+        extra.push('- Verify new code in legacy modules preserves the existing patterns (see `.claude/rules/common/coding-style.md` "Project-specific rules").');
+    }
+    const rules = extra.length > 0 ? [...baseRules, '', '## Project-specific review focus', ...extra] : baseRules;
+    return `${renderHeader('Code Review Standards')}${rules.join('\n')}\n`;
+}
+export function renderSecurity(ctx) {
+    const baseRules = [
+        '- Never hardcode secrets, API keys, passwords, tokens, or credentials.',
+        '- Do not send private code or secrets to external services without explicit user authorization.',
+        '- Guard filesystem writes against path traversal, symlink, and junction escapes.',
+        '- Require explicit confirmation for destructive actions, external state changes, and credential use.'
+    ];
+    const extra = [];
+    if (ctx.buildTool === 'next')
+        extra.push('- Validate request body / query / params at every API route boundary (`pages/api/**` or `app/api/**`).');
+    if (ctx.dataFetching.length > 0)
+        extra.push(`- Sanitize and validate API responses before rendering or persisting (current fetchers: ${ctx.dataFetching.join(', ')}).`);
+    if (ctx.notableDeps.includes('monaco-editor') || ctx.notableDeps.includes('@monaco-editor/react')) {
+        extra.push('- Monaco editor content is untrusted; never `eval` or `Function`-construct user-authored code without an explicit, reviewed sandbox.');
+    }
+    const rules = extra.length > 0 ? [...baseRules, '', '## Project-specific security focus', ...extra] : baseRules;
+    return `${renderHeader('Security Review Standards')}${rules.join('\n')}\n`;
+}
+/**
+ * UI library priority rule (effective 2026-08-01). Public so unit tests
+ * can pin the contract without reaching through the plan builder.
+ *
+ * Returns the rule line, or `null` when the project has no detected
+ * component library (in which case the rule is intentionally silent).
+ */
+export function renderUiLibraryPriorityRule(ctx) {
+    const lib = ctx.componentLibrary.name;
+    const UI_LIB_NAMES = [
+        'antd', 'antd-pro', 'mui', 'shadcn',
+        'chakra', 'element-plus', 'element-ui',
+        'arco', 'tdesign', 'semi', 'nextui'
+    ];
+    if (!UI_LIB_NAMES.includes(lib)) {
+        return null;
+    }
+    return `- UI library priority (peaks-loop, effective 2026-08-01): this project uses \`${lib}\`. Prefer the library's exported components over hand-rolled native DOM / HTML primitives. Native DOM is acceptable only for primitives the library does not ship; leave a one-line comment naming the library primitive that was unavailable. Library themes and tokens are the source of truth; do NOT introduce a parallel CSS framework or inline styles that fight the library.`;
+}
+export function renderLanguageCodingStyle(language, ctx) {
+    const languageName = language === 'generic' ? 'Generic' : language[0].toUpperCase() + language.slice(1);
+    const typeSafetyRule = language === 'typescript' || language === 'javascript'
+        ? '- Do not add new `any` types; use explicit domain types, generics, or `unknown` with narrowing.\n'
+        : '';
+    const baseRules = [
+        `- Apply project-local conventions before generic ${language} guidance.`,
+        `- Keep public APIs typed or documented according to ${language} ecosystem norms.`,
+        typeSafetyRule.trim() !== '' ? typeSafetyRule.trim() : null,
+        '- Prefer standard tooling and existing project scripts for formatting, linting, tests, and coverage.',
+        `- peaks-rd must check this file before planning code changes in ${language} projects.`
+    ].filter((line) => line !== null);
+    const extra = [];
+    if ((language === 'typescript' || language === 'javascript') && (ctx.componentLibrary.name === 'antd' || ctx.componentLibrary.name === 'antd-pro')) {
+        extra.push('- Type form values, table records, and API responses with named interfaces; do not rely on `Form.useForm()` inference for shared shapes.');
+    }
+    if ((language === 'typescript' || language === 'javascript') && ctx.dataFetching.includes('@tanstack/react-query')) {
+        extra.push('- Declare query/mutation generics (`useQuery<TData, TError>`) so consumers get typed data.');
+    }
+    if ((language === 'typescript' || language === 'javascript') && ctx.buildTool === 'umi') {
+        extra.push('- Use the project\'s existing service-layer pattern (`src/services/**`) for API calls; do not hand-roll `fetch` in components.');
+    }
+    // UI library priority (effective 2026-08-01). Applies to any project whose
+    // scan identified one of the supported component libraries; the rule
+    // is generated by the standards update so it ships to every downstream
+    // project through `peaks standards init/update`.
+    const uiRule = renderUiLibraryPriorityRule(ctx);
+    if (uiRule !== null)
+        extra.push(uiRule);
+    const rules = extra.length > 0 ? [...baseRules, '', '## Project-specific rules', ...extra] : baseRules;
+    return `${renderHeader(`${languageName} Coding Standards`)}${rules.join('\n')}\n`;
+}
+export function renderManagedClaudeMdIndex(language) {
+    return [
+        '<!-- peaks-standards:index:start -->',
+        '## Peaks Standards Index',
+        '- Constitution: `CLAUDE.md` is the repository-wide constitution.',
+        '- Local laws: `.peaks/standards/**` are project-local laws and are created only when missing.',
+        '- Managed by: `peaks standards update`.',
+        '- Managed files:',
+        '  - `.peaks/standards/common/code-review.md`',
+        '  - `.peaks/standards/common/coding-style.md`',
+        '  - `.peaks/standards/common/security.md`',
+        `  - .peaks/standards/${language}/coding-style.md`,
+        '- Conflict note: keep the existing body unchanged and resolve any disagreement manually before the next standards update.',
+        '<!-- peaks-standards:index:end -->',
+        ''
+    ].join('\n');
+}
+export function renderClaudeMdOneX(language, ctx) {
+    const head = [
+        '# Project Instructions',
+        '',
+        '> 🤖 AI 生成，请审阅',
+        '',
+        'This repository uses project-local Peaks standards. Existing repository conventions override generic generated guidance.',
+        '',
+        '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-code summarizes RD and QA standards preflight before end-to-end code workflows.',
+        '',
+        'Rules:',
+        '- Read `.claude/rules/common/coding-style.md` before editing code.',
+        '- Read `.claude/rules/common/code-review.md` before reviewing changes.',
+        '- Read `.claude/rules/common/security.md` before touching filesystem, user input, external calls, auth, or secrets.',
+        `- Read .claude/rules/${language}/coding-style.md for language-specific standards when applicable.`,
+        '',
+        'Active Peaks-Loop skill presence: at the start of every response, run `peaks skill presence --json` to read the active skill marker. The CLI handles canonical-path resolution (`.peaks/_runtime/active-skill.json` with back-compat fallback to `.peaks/.active-skill.json`); do not read those files directly. When the response includes a valid skill name, display the compact status header: `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`. Display the header on every turn while the CLI returns an active skill; omit when the CLI returns no active skill.'
+    ].join('\n');
+    const stack = renderProjectStackSection(ctx);
+    return stack === '' ? head : `${head}\n${stack}`;
+}

package/dist/services/standards/ui-library-dispatch-block.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Slice 2026-09-06-ui-lib-dispatch-priority: render a `## Project stack`
+ * markdown block for the RD/UI sub-agent dispatch system prompt, and the
+ * dispatch-site convenience wrapper that computes it from a project root.
+ *
+ * Kept in its own small module so the block rendering does NOT grow
+ * `project-standards-service.ts` past the 800-line cap (the slice only
+ * surfaces the existing standards rule in a second surface — it does not
+ * add to the standards service itself).
+ */
+import { type ProjectContext } from './project-context.js';
+/**
+ * Render the block. The library-first directive reuses
+ * `renderUiLibraryPriorityRule` (the single source of truth for that prose —
+ * no second copy to drift). Returns `null` when the project has no detected
+ * component library (or a library the rule does not cover), so the dispatch
+ * prompt degrades byte-identically to the legacy shape (no empty or dangling
+ * "Project stack" heading).
+ */
+export declare function renderUiLibraryPriorityDispatchBlock(ctx: ProjectContext): string | null;
+/**
+ * Dispatch-site convenience wrapper: detect the project context and render
+ * the block. Fail-soft — any detection error degrades to `null` (no block)
+ * so a bad package.json or unreadable source sample never hard-blocks the
+ * dispatch.
+ */
+export declare function computeUiLibraryDispatchBlock(projectRoot: string): string | null;

package/dist/services/standards/ui-library-dispatch-block.js

@@ -0,0 +1,48 @@
+/**
+ * Slice 2026-09-06-ui-lib-dispatch-priority: render a `## Project stack`
+ * markdown block for the RD/UI sub-agent dispatch system prompt, and the
+ * dispatch-site convenience wrapper that computes it from a project root.
+ *
+ * Kept in its own small module so the block rendering does NOT grow
+ * `project-standards-service.ts` past the 800-line cap (the slice only
+ * surfaces the existing standards rule in a second surface — it does not
+ * add to the standards service itself).
+ */
+import { buildToolLabel, componentLibraryLabel, cssFrameworkLabel, detectProjectContext, } from './project-context.js';
+import { renderUiLibraryPriorityRule } from './project-standards-service.js';
+/**
+ * Render the block. The library-first directive reuses
+ * `renderUiLibraryPriorityRule` (the single source of truth for that prose —
+ * no second copy to drift). Returns `null` when the project has no detected
+ * component library (or a library the rule does not cover), so the dispatch
+ * prompt degrades byte-identically to the legacy shape (no empty or dangling
+ * "Project stack" heading).
+ */
+export function renderUiLibraryPriorityDispatchBlock(ctx) {
+    const rule = renderUiLibraryPriorityRule(ctx);
+    if (rule === null)
+        return null;
+    const lines = ['## Project stack', ''];
+    lines.push(`- Component library: ${componentLibraryLabel(ctx.componentLibrary)}`);
+    lines.push(`- Build tool: ${buildToolLabel(ctx.buildTool)}`);
+    if (ctx.cssFrameworks.length > 0) {
+        lines.push(`- CSS: ${ctx.cssFrameworks.map(cssFrameworkLabel).join(', ')}`);
+    }
+    lines.push('');
+    lines.push(rule);
+    return lines.join('\n');
+}
+/**
+ * Dispatch-site convenience wrapper: detect the project context and render
+ * the block. Fail-soft — any detection error degrades to `null` (no block)
+ * so a bad package.json or unreadable source sample never hard-blocks the
+ * dispatch.
+ */
+export function computeUiLibraryDispatchBlock(projectRoot) {
+    try {
+        return renderUiLibraryPriorityDispatchBlock(detectProjectContext(projectRoot));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/services/workspace/reconcile-migrate.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Migration helpers extracted from `reconcile-service.ts`
+ * (slice 2026-09-06-split-batch-b) so the service stays under the
+ * 800-line cap. Behaviour-preserving verbatim move.
+ */
+/**
+ * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
+ *
+ * Move the legacy runtime files at:
+ *   - `.peaks/.session.json`
+ *   - `.peaks/.active-skill.json`
+ *   - `.peaks/sop-state/`
+ * into their new canonical home at:
+ *   - `.peaks/_runtime/session.json`
+ *   - `.peaks/_runtime/active-skill.json`
+ *   - `.peaks/_runtime/sop-state/`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new
+ *     layout produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` (atomic on POSIX, best-effort
+ *     on Windows) and falls back to `copyFileSync` + `unlinkSync` if
+ *     rename throws (e.g. cross-device move on Windows). Errors are
+ *     collected per file and returned in the `errors` array so the
+ *     reconcile envelope can surface them without blocking the rest of
+ *     the migration.
+ *   - Creates `.peaks/_runtime/` on demand if any of the old paths
+ *     are present.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the
+ *   *old* relative paths (e.g. `.peaks/.session.json`) that were
+ *   successfully moved, in move order. `errors` lists per-file
+ *   failures with the old path and a human-readable message.
+ */
+export declare function migrateOldRuntimeState(projectRoot: string): {
+    migratedFiles: string[];
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+/**
+ * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+ *
+ * Move the legacy per-session sub-agent state files at:
+ *   - `.peaks/_runtime/<sid>/system/subagent-progress.json`
+ *   - `.peaks/_runtime/<sid>/system/progress-spawn.json`
+ * into the new canonical home at:
+ *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
+ *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new layout
+ *     produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
+ *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
+ *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
+ *     subdir is only removed when it has zero other files, so a tree where
+ *     the user had unrelated content in `system/` is left untouched.
+ *   - New-path-wins: when both old and new files exist, the old file is
+ *     removed (the new path is authoritative).
+ *
+ * Walks every discovered session — not just the canonical one — so a user
+ * with 6 pre-migration sessions gets all of them migrated in one reconcile
+ * pass.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
+ *   relative paths (e.g. `.peaks/_runtime/<sid>/system/subagent-progress.json`) that
+ *   were successfully moved. `errors` lists per-file failures.
+ */
+export declare function migrateSubAgentState(projectRoot: string): {
+    migratedFiles: string[];
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+};

package/dist/services/workspace/reconcile-migrate.js

@@ -0,0 +1,230 @@
+/**
+ * Migration helpers extracted from `reconcile-service.ts`
+ * (slice 2026-09-06-split-batch-b) so the service stays under the
+ * 800-line cap. Behaviour-preserving verbatim move.
+ */
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, rmdirSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+// Call-time-only dependency on the sibling service: `migrateSubAgentState`
+// walks every discovered session via `discoverSessions`, which is invoked
+// only at call time (after both modules have fully evaluated), so the
+// value-level circular import is safe under ESM live bindings.
+import { discoverSessions } from './reconcile-service.js';
+// Sub-agent state file basenames (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+// The legacy location was `.peaks/_runtime/<sid>/system/<filename>`; the canonical new
+// location is `.peaks/_sub_agents/<sid>/<filename>`. `migrateSubAgentState`
+// moves the two files between these homes on every `reconcileWorkspace` run.
+const SUB_AGENT_MIGRATION_FILES = [
+    'subagent-progress.json',
+    'progress-spawn.json'
+];
+const SUB_AGENTS_DIR = '_sub_agents';
+// As of slice 2026-06-05-peaks-runtime-layer these old paths are the
+// back-compat read-only fallbacks; the canonical new home is
+// `.peaks/_runtime/`. `migrateOldRuntimeState` moves them to the new
+// location on disk. The leading dot is dropped when computing the
+// new basename (e.g. `.session.json` → `session.json`), so the new
+// layout is `.peaks/_runtime/{session.json,active-skill.json,sop-state/}`.
+const RUNTIME_OLD_PATHS = [
+    '.session.json',
+    '.active-skill.json',
+    'sop-state'
+];
+const RUNTIME_DIR = join('.peaks', '_runtime');
+/**
+ * Map a legacy path basename (e.g. `.session.json`) to its canonical
+ * new basename (e.g. `session.json`). The dot is dropped so the new
+ * layer reads naturally. Directories pass through unchanged.
+ */
+function runtimeNewBasename(oldBasename) {
+    if (oldBasename.startsWith('.') && oldBasename.length > 1) {
+        return oldBasename.slice(1);
+    }
+    return oldBasename;
+}
+/**
+ * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
+ *
+ * Move the legacy runtime files at:
+ *   - `.peaks/.session.json`
+ *   - `.peaks/.active-skill.json`
+ *   - `.peaks/sop-state/`
+ * into their new canonical home at:
+ *   - `.peaks/_runtime/session.json`
+ *   - `.peaks/_runtime/active-skill.json`
+ *   - `.peaks/_runtime/sop-state/`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new
+ *     layout produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` (atomic on POSIX, best-effort
+ *     on Windows) and falls back to `copyFileSync` + `unlinkSync` if
+ *     rename throws (e.g. cross-device move on Windows). Errors are
+ *     collected per file and returned in the `errors` array so the
+ *     reconcile envelope can surface them without blocking the rest of
+ *     the migration.
+ *   - Creates `.peaks/_runtime/` on demand if any of the old paths
+ *     are present.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the
+ *   *old* relative paths (e.g. `.peaks/.session.json`) that were
+ *   successfully moved, in move order. `errors` lists per-file
+ *   failures with the old path and a human-readable message.
+ */
+export function migrateOldRuntimeState(projectRoot) {
+    const root = resolve(projectRoot);
+    const peaksRoot = join(root, '.peaks');
+    const newDir = join(root, RUNTIME_DIR);
+    const migratedFiles = [];
+    const errors = [];
+    for (const rel of RUNTIME_OLD_PATHS) {
+        const oldPath = join(peaksRoot, rel);
+        if (!existsSync(oldPath))
+            continue;
+        // Skip if the corresponding new path already exists — we treat the
+        // new path as authoritative when both exist, so the old file would
+        // only be stale data.
+        const newPath = join(newDir, runtimeNewBasename(rel));
+        if (existsSync(newPath)) {
+            // Best-effort cleanup of the stale old file so a re-run stays
+            // idempotent and the tree converges on the new layout.
+            try {
+                rmSync(oldPath, { recursive: true, force: true });
+            }
+            catch (error) {
+                errors.push({
+                    path: rel,
+                    message: `Could not remove stale legacy file after migration: ${error instanceof Error ? error.message : String(error)}`
+                });
+            }
+            continue;
+        }
+        try {
+            // Ensure the new parent dir exists. `mkdirSync(dirname(newPath), { recursive: true })`
+            // covers both the file case (`.peaks/_runtime`) and the
+            // directory case (`.peaks/_runtime/sop-state`).
+            mkdirSync(dirname(newPath), { recursive: true });
+            try {
+                renameSync(oldPath, newPath);
+            }
+            catch (renameError) {
+                // Cross-device or locked-file fallback: copy + unlink.
+                const stat = lstatSync(oldPath);
+                if (stat.isDirectory()) {
+                    // Recursive copy for the sop-state dir.
+                    copyDirRecursiveSync(oldPath, newPath);
+                    rmSync(oldPath, { recursive: true, force: true });
+                }
+                else {
+                    copyFileSync(oldPath, newPath);
+                    unlinkSync(oldPath);
+                }
+            }
+            migratedFiles.push(join('.peaks', rel));
+        }
+        catch (error) {
+            errors.push({
+                path: rel,
+                message: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return { migratedFiles, errors };
+}
+function copyDirRecursiveSync(src, dest) {
+    mkdirSync(dest, { recursive: true });
+    for (const name of readdirSync(src)) {
+        const childSrc = join(src, name);
+        const childDest = join(dest, name);
+        const stat = lstatSync(childSrc);
+        if (stat.isDirectory()) {
+            copyDirRecursiveSync(childSrc, childDest);
+        }
+        else {
+            copyFileSync(childSrc, childDest);
+        }
+    }
+}
+/**
+ * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+ *
+ * Move the legacy per-session sub-agent state files at:
+ *   - `.peaks/_runtime/<sid>/system/subagent-progress.json`
+ *   - `.peaks/_runtime/<sid>/system/progress-spawn.json`
+ * into the new canonical home at:
+ *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
+ *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new layout
+ *     produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
+ *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
+ *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
+ *     subdir is only removed when it has zero other files, so a tree where
+ *     the user had unrelated content in `system/` is left untouched.
+ *   - New-path-wins: when both old and new files exist, the old file is
+ *     removed (the new path is authoritative).
+ *
+ * Walks every discovered session — not just the canonical one — so a user
+ * with 6 pre-migration sessions gets all of them migrated in one reconcile
+ * pass.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
+ *   relative paths (e.g. `.peaks/_runtime/<sid>/system/subagent-progress.json`) that
+ *   were successfully moved. `errors` lists per-file failures.
+ */
+export function migrateSubAgentState(projectRoot) {
+    const root = resolve(projectRoot);
+    const newDir = join(root, '.peaks', SUB_AGENTS_DIR);
+    const migratedFiles = [];
+    const errors = [];
+    for (const session of discoverSessions(projectRoot)) {
+        const oldSystemDir = join(session.path, 'system');
+        if (!existsSync(oldSystemDir))
+            continue;
+        const newSessionDir = join(newDir, session.sessionId);
+        mkdirSync(newSessionDir, { recursive: true });
+        for (const fname of SUB_AGENT_MIGRATION_FILES) {
+            const oldPath = join(oldSystemDir, fname);
+            const newPath = join(newSessionDir, fname);
+            if (!existsSync(oldPath))
+                continue;
+            if (existsSync(newPath)) {
+                // New path is authoritative; remove stale old file.
+                try {
+                    rmSync(oldPath, { force: true });
+                }
+                catch { /* best effort */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                continue;
+            }
+            try {
+                try {
+                    renameSync(oldPath, newPath);
+                }
+                catch (renameError) {
+                    // Cross-device or locked-file fallback: copy + unlink.
+                    copyFileSync(oldPath, newPath);
+                    unlinkSync(oldPath);
+                }
+                migratedFiles.push(join('.peaks', session.sessionId, 'system', fname));
+            }
+            catch (error) {
+                errors.push({
+                    path: oldPath,
+                    message: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        // R-2 guard: only remove the legacy system/ dir when it has zero
+        // remaining files (the user might have unrelated content there).
+        try {
+            const remaining = readdirSync(oldSystemDir);
+            if (remaining.length === 0) {
+                rmdirSync(oldSystemDir);
+            }
+        }
+        catch { /* best effort */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    }
+    return { migratedFiles, errors };
+}