peaks-loop 4.0.0-beta.3 → 4.0.0-beta.31

package/dist/services/prd/project-scan-bootstrap-service.js

@@ -0,0 +1,445 @@
+/**
+ * project-scan bootstrap service — slice 2026-07-15-project-scan-bootstrap
+ * (PRD G1 + G2 + G4b / AC1-AC10 / R1-R4).
+ *
+ * Owns the "first time a project enters Peaks-Loop" bootstrap flow:
+ *   - 0-1 detection (no package.json OR no source files)
+ *   - writes `.peaks/project-scan/project-scan.md` with empty placeholders
+ *     for 0-1 projects, or with archetype + libraryVersions for existing
+ *     projects (calling `scanArchetype` + `scanLibraries` directly, not
+ *     forking a CLI process)
+ *   - boots the 4 audit/business templates (bundled in repo at
+ *     `src/services/workspace/templates/project-scan/`) into
+ *     `.peaks/project-scan/` (AC9)
+ *   - idempotent: skips re-writes when the existing file is at
+ *     schemaVersion:1 (AC3); --force / --force-templates override
+ *
+ * Called by:
+ *   - `peaks project context` (via `generateProjectContext`)
+ *   - `peaks workspace init` (main path)
+ *
+ * The "5 templates" count: 4 bundled audit/business files + the
+ * dynamically-generated `project-scan.md` produced by this service.
+ * `templatesBooted` reflects the count of files actually written;
+ * `templatesSkipped` reflects files already present (sediment-protected).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { scanArchetype } from '../scan/archetype-service.js';
+import { scanLibraries } from '../scan/libraries-service.js';
+import { TEMPLATE_FILES, readTemplateStrict } from '../workspace/templates/project-scan/index.js';
+const PROJECT_SCAN_DIR = join('.peaks', 'project-scan');
+const PROJECT_SCAN_FILENAME = 'project-scan.md';
+const PROJECT_SCAN_PATH = join(PROJECT_SCAN_DIR, PROJECT_SCAN_FILENAME);
+const SOURCE_FILE_EXTENSIONS = /\.(tsx?|jsx?|vue|svelte)$/;
+/**
+ * Monorepo layout sentinels. A project is monorepo-shaped if it carries
+ * one of these config files at its root, even when `src/` is absent.
+ * Slice 2026-07-15 hot-fix (ice-cola real-world test, 2026-07-15):
+ *   `pnpm-workspace.yaml` is the most common signal; `turbo.json`
+ *   (Turborepo) and `nx.json` (Nx) are the others the ecosystem
+ *   reaches for. lerna.json is legacy-only and intentionally omitted
+ *   here — those projects should be detected via `package.json`
+ *   workspaces[] field below.
+ */
+const MONOREPO_ROOT_CONFIGS = [
+    'pnpm-workspace.yaml',
+    'turbo.json',
+    'nx.json'
+];
+/** True iff the project root declares pnpm / yarn / npm workspaces. */
+function projectHasWorkspacesInPackageJson(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return false;
+    let raw;
+    try {
+        raw = readFileSync(pkgPath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (Array.isArray(pkg.workspaces))
+        return pkg.workspaces.length > 0;
+    if (pkg.workspaces && typeof pkg.workspaces === 'object') {
+        // Yarn classic shape: { packages: ['packages/*'] }
+        const obj = pkg.workspaces;
+        if (Array.isArray(obj.packages))
+            return obj.packages.length > 0;
+    }
+    return false;
+}
+/** True iff the project root is a monorepo by any of the 3 root-config signals. */
+function projectIsMonorepo(projectRoot) {
+    for (const cfg of MONOREPO_ROOT_CONFIGS) {
+        if (existsSync(join(projectRoot, cfg)))
+            return true;
+    }
+    return projectHasWorkspacesInPackageJson(projectRoot);
+}
+/**
+ * Recursive file-existence check for a single root dir, capped at MAX_DEPTH.
+ * Returns true the first time it encounters a file matching
+ * SOURCE_FILE_EXTENSIONS. Skips dot-dirs and node_modules.
+ */
+function directoryContainsSourceFiles(rootDir) {
+    if (!existsSync(rootDir))
+        return false;
+    const queue = [rootDir];
+    const MAX_DEPTH = 6;
+    let depth = 0;
+    while (queue.length > 0 && depth <= MAX_DEPTH) {
+        const current = queue.shift();
+        if (current === undefined)
+            break;
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(full);
+            }
+            else if (entry.isFile() && SOURCE_FILE_EXTENSIONS.test(entry.name)) {
+                return true;
+            }
+        }
+        depth += 1;
+    }
+    return false;
+}
+/**
+ * Heuristic for "this directory holds source code".
+ *
+ * 1. `src/` at the root (single-package layout).
+ * 2. Any of the monorepo source roots: `packages/`, `apps/`, `libs/`,
+ *    `services/`, `workspaces/` — each is checked recursively for at
+ *    least one matching source file. Slice 2026-07-15 hot-fix (ice-cola
+ *    test, 2026-07-15): the original implementation only looked at
+ *    `src/` and mis-classified monorepos as 0-1 (pnpm-workspace layout
+ *    puts source under `packages/<pkg>/src/`, not `<root>/src/`).
+ *
+ * Returns true on the first hit. False when none of the candidate
+ * roots contain source files (genuine 0-1).
+ */
+function projectHasSourceFiles(projectRoot) {
+    if (directoryContainsSourceFiles(join(projectRoot, 'src')))
+        return true;
+    const monorepoSourceRoots = ['packages', 'apps', 'libs', 'services', 'workspaces'];
+    for (const candidate of monorepoSourceRoots) {
+        const dir = join(projectRoot, candidate);
+        if (!existsSync(dir))
+            continue;
+        if (directoryContainsSourceFiles(dir))
+            return true;
+    }
+    return false;
+}
+/** Detect 0-1: no package.json OR no source files.
+ *  Slice 2026-07-15 hot-fix (ice-cola test, 2026-07-15): monorepos with
+ *  source under packages/<pkg>/ are no longer mis-classified as 0-1. */
+function isZeroToOneProject(projectRoot) {
+    const hasPackageJson = existsSync(join(projectRoot, 'package.json'));
+    if (!hasPackageJson)
+        return true;
+    if (projectIsMonorepo(projectRoot)) {
+        // Monorepo: a package.json at root + workspace config is enough
+        // signal that this is NOT a 0-1 project — even if we couldn't find
+        // source files at the expected roots (workspace packages may be
+        // missing locally, behind a sparse-checkout, etc.). Trust the
+        // workspace layout and let `scanArchetype` decide the real shape.
+        return false;
+    }
+    return !projectHasSourceFiles(projectRoot);
+}
+/**
+ * Parse the frontmatter `schemaVersion` from an existing project-scan.md.
+ * Returns `null` when the file is absent, malformed, or has no version.
+ * The reader in `services/prd/project-scan-reader.ts` is the canonical
+ * parser; we re-implement the minimum here to avoid coupling the
+ * bootstrap path to that reader's strict shape validation.
+ */
+function readExistingSchemaVersion(absPath) {
+    if (!existsSync(absPath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(absPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const match = /^---\n([\s\S]*?)\n---/.exec(raw);
+    if (!match)
+        return null;
+    const frontmatter = match[1] ?? '';
+    const versionMatch = /^\s*schemaVersion:\s*(\d+)/m.exec(frontmatter);
+    if (!versionMatch)
+        return null;
+    const parsed = Number(versionMatch[1]);
+    return Number.isSafeInteger(parsed) ? parsed : null;
+}
+/** Build the project-scan.md content for a 0-1 project (empty placeholders). */
+function buildZeroToOneProjectScan() {
+    const now = new Date().toISOString();
+    return [
+        '---',
+        'schemaVersion: 1',
+        `capturedAt: ${now}`,
+        'archetype: unknown',
+        'confidence: low',
+        'techStack: {}',
+        'libraryVersions: {}',
+        'architecture: ""',
+        'karpathySelfCheck: {}',
+        '---',
+        '',
+        '# Project Scan (0-1 bootstrap)',
+        '',
+        `> Auto-generated by \`peaks workspace init\` / \`peaks project context\` on ${now}. ` +
+            'Refresh with `peaks project context --project <repo>` once the project has a `package.json` + source files.',
+        '',
+        '## Archetype',
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        '| Type | `unknown` |',
+        '| Confidence | `low` |',
+        '| Reason | 0-1 project, no package.json or source files |',
+        '| Frontend-only | `false` |',
+        '',
+        '## Project mode',
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        '| Mode | unknown |',
+        '| Reason | 0-1 bootstrap — refresh after the first source file lands |',
+        '',
+        '## Tech stack',
+        '',
+        '| Concern | Value |',
+        '|---|---|',
+        '| Language | (empty) |',
+        '| Package manager | (empty) |',
+        '| Node runtime | (empty) |',
+        '| Build | (empty) |',
+        '| Tests | (empty) |',
+        '',
+        '## Library versions',
+        '',
+        '| Package | Pinned range | Major | Scope | Ecosystem |',
+        '|---|---|---|---|---|',
+        '| (empty) | — | — | — | — |',
+        '',
+        '## Architecture',
+        '',
+        '_No architecture recorded yet — refresh with `peaks project context --project <repo>` once the project has source files._',
+        '',
+        '## Karpathy self-check',
+        '',
+        '| Guideline | Where enforced |',
+        '|---|---|',
+        '| §1 Think Before Coding | (empty) |',
+        '| §2 Simplicity First | (empty) |',
+        '| §3 Surgical Changes | (empty) |',
+        '| §4 Goal-Driven Execution | (empty) |',
+        '',
+        '## Refresh procedure',
+        '',
+        '1. Add a `package.json` (with `pnpm init` or equivalent).',
+        '2. Add at least one TypeScript/JavaScript/Vue/Svelte source file under `src/`.',
+        '3. Re-run `peaks project context --project <repo>` — the empty placeholders are replaced with real archetype + libraryVersions.',
+        ''
+    ].join('\n');
+}
+/** Render a LibraryReport as a markdown table body (header row included). */
+function renderLibraryTable(libraryReport) {
+    const header = '| Package | Pinned range | Major | Scope | Ecosystem |';
+    const sep = '|---|---|---|---|---|';
+    if (libraryReport.libraries.length === 0) {
+        return [header, sep, '| (empty) | — | — | — | — |'].join('\n');
+    }
+    const rows = libraryReport.libraries.map((entry) => {
+        const major = entry.major === null ? '—' : String(entry.major);
+        return `| \`${entry.name}\` | \`${entry.version}\` | ${major} | ${entry.scope} | ${entry.ecosystem} |`;
+    });
+    return [header, sep, ...rows].join('\n');
+}
+/** Build the project-scan.md content for an existing project. */
+async function buildExistingProjectScan(args) {
+    const { archetypeReport, libraryReport } = args;
+    const now = new Date().toISOString();
+    const runtime = (process.versions.node ?? 'unknown').trim();
+    // Library versions snapshot: a flat {name: version} map. Mirrors the
+    // shape consumed by `services/prd/project-scan-types.ts`
+    // `ProjectScanLibraryVersions`.
+    const libraryVersionsMap = {};
+    for (const entry of libraryReport.libraries) {
+        libraryVersionsMap[entry.name] = entry.version;
+    }
+    const lines = [
+        '---',
+        'schemaVersion: 1',
+        `capturedAt: ${now}`,
+        `archetype: ${archetypeReport.archetype}`,
+        `confidence: ${archetypeReport.confidence}`,
+        'techStack: {}',
+        `libraryVersions: ${JSON.stringify(libraryVersionsMap, null, 2)
+            .split('\n')
+            .map((line, idx) => (idx === 0 ? line : '  ' + line))
+            .join('\n')}`,
+        'architecture: ""',
+        'karpathySelfCheck: {}',
+        '---',
+        '',
+        `# Project Scan (refreshed ${now})`,
+        '',
+        '> Auto-generated by `peaks workspace init` / `peaks project context`.',
+        '',
+        '## Archetype',
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        `| Type | \`${archetypeReport.archetype}\` |`,
+        `| Confidence | \`${archetypeReport.confidence}\` |`,
+        `| Frontend-only | \`${String(archetypeReport.frontendOnly)}\` |`,
+        `| Reason | ${archetypeReport.frontendOnlyReason} |`,
+        '',
+        '## Project mode',
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        `| Mode | ${archetypeReport.frontendOnly ? 'frontend-only' : 'full-stack-or-unknown'} |`,
+        `| Reason | ${archetypeReport.frontendOnlyReason} |`,
+        '',
+        '## Tech stack',
+        '',
+        '| Concern | Value |',
+        '|---|---|',
+        '| Language | TypeScript (best-effort — re-confirm via package.json devDeps) |',
+        '| Package manager | pnpm (best-effort) |',
+        `| Node runtime | node ${runtime} |`,
+        '| Build | tsc / package.json `build` script |',
+        '| Tests | vitest (best-effort) |',
+        '',
+        '## Library versions',
+        '',
+        renderLibraryTable(libraryReport),
+        '',
+        '## Architecture',
+        '',
+        `_Auto-generated from \`scanArchetype\` signals — see archetypeReport.backendFrameworks / .backendDirsPresent / .swaggerPaths in \`.peaks/_runtime/<sid>/rd/project-scan.md\` (legacy) or \`.peaks/project-scan/project-scan.md\` (this file) for the raw facts._`,
+        '',
+        '## Karpathy self-check',
+        '',
+        '| Guideline | Where enforced |',
+        '|---|---|',
+        '| §1 Think Before Coding | (refresh with LLM review) |',
+        '| §2 Simplicity First | (refresh with LLM review) |',
+        '| §3 Surgical Changes | (refresh with LLM review) |',
+        '| §4 Goal-Driven Execution | (refresh with LLM review) |',
+        '',
+        '## Refresh procedure',
+        '',
+        '1. Re-run `peaks scan archetype --project <repo> --json` and `peaks scan libraries --project <repo> --json` after any dependency / archetype change.',
+        '2. Re-run `peaks project context --project <repo>` to refresh this file.',
+        '3. Commit the regenerated project-scan.md alongside the dependency bump.',
+        ''
+    ];
+    return lines.join('\n');
+}
+/**
+ * Ensure `.peaks/project-scan/` exists. Idempotent.
+ */
+function ensureProjectScanDir(projectRoot) {
+    const dir = join(projectRoot, PROJECT_SCAN_DIR);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Copy one bundled template into the project. Returns `true` when
+ * the file was written, `false` when it was skipped (already present
+ * without `--force-templates`).
+ */
+async function bootTemplate(args) {
+    const destPath = join(args.projectRoot, PROJECT_SCAN_DIR, args.name);
+    if (existsSync(destPath) && !args.force) {
+        return false;
+    }
+    const content = await readTemplateStrict(args.name);
+    writeFileSync(destPath, content, 'utf8');
+    return true;
+}
+/**
+ * Public entry point. See the file header for the full contract.
+ */
+export async function bootstrapProjectScan(options) {
+    const startedAt = Date.now();
+    ensureProjectScanDir(options.projectRoot);
+    const projectScanAbsPath = join(options.projectRoot, PROJECT_SCAN_PATH);
+    const existingVersion = readExistingSchemaVersion(projectScanAbsPath);
+    // Decide whether project-scan.md is created or skipped. Idempotency:
+    // when an existing file already declares schemaVersion:1 we honor
+    // sediment unless `force=true`.
+    let created = false;
+    let skipped = false;
+    let archetype;
+    if (existingVersion === 1 && options.force !== true) {
+        skipped = true;
+    }
+    else {
+        const zeroToOne = isZeroToOneProject(options.projectRoot);
+        if (zeroToOne) {
+            archetype = 'unknown';
+            writeFileSync(projectScanAbsPath, buildZeroToOneProjectScan(), 'utf8');
+        }
+        else {
+            const archetypeReport = await scanArchetype({ projectRoot: options.projectRoot });
+            const libraryReport = await scanLibraries({ projectRoot: options.projectRoot });
+            archetype = archetypeReport.archetype;
+            const content = await buildExistingProjectScan({ archetypeReport, libraryReport });
+            writeFileSync(projectScanAbsPath, content, 'utf8');
+        }
+        created = true;
+    }
+    // Boot the 4 bundled templates (AC9). The project-scan.md we just
+    // wrote (or preserved) is also counted as 1 template.
+    let templatesBooted = created ? 1 : 0;
+    let templatesSkipped = created ? 0 : 1;
+    for (const name of TEMPLATE_FILES) {
+        const wrote = await bootTemplate({
+            projectRoot: options.projectRoot,
+            name,
+            force: options.forceTemplates === true
+        });
+        if (wrote) {
+            templatesBooted += 1;
+        }
+        else {
+            templatesSkipped += 1;
+        }
+    }
+    return {
+        created,
+        skipped,
+        templatesBooted,
+        templatesSkipped,
+        projectScanPath: projectScanAbsPath,
+        ...(archetype !== undefined ? { archetype } : {}),
+        durationMs: Date.now() - startedAt
+    };
+}

package/dist/services/preferences/preferences-service.js

@@ -0,0 +1,208 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DEFAULT_PREFERENCES, FANOUT_MODES, isFanoutMode, PREFERENCES_SCHEMA_VERSION, } from './preferences-types.js';
+const PREFS_REL_PATH = '.peaks/preferences.json';
+export { DEFAULT_PREFERENCES, PREFERENCES_SCHEMA_VERSION };
+export function preferencesPath(projectRoot) {
+    return join(projectRoot, PREFS_REL_PATH);
+}
+export function loadPreferences(projectRoot) {
+    const filePath = preferencesPath(projectRoot);
+    if (!existsSync(filePath)) {
+        // Slice 2026-07-22-orchestrator-memory-preflight: when
+        // .peaks/preferences.json is missing, this returns a clone of
+        // DEFAULT_PREFERENCES, which now carries the `memoryPreflight`
+        // block (see preferences-types.ts). Partial overlays fall through
+        // to mergePreferences below, where the new `memoryPreflight` block
+        // shallow-replaces the default block — `mergePreferences` does not
+        // deep-merge `memoryPreflight` (only `fanout` is deep-merged), so a
+        // partial overlay will replace the whole block. Resolution still
+        // works because `resolveMemoryPreflightConfig` applies field-level
+        // defaults over the partial input (see memory-preflight-config.ts).
+        return structuredClone(DEFAULT_PREFERENCES);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`PREFERENCES_JSON_INVALID: failed to parse ${filePath}: ${err.message}`);
+    }
+    if (typeof raw !== 'object' ||
+        raw === null ||
+        raw.schema_version !== PREFERENCES_SCHEMA_VERSION) {
+        throw new Error(`PREFERENCES_SCHEMA_MISMATCH: expected schema_version=${PREFERENCES_SCHEMA_VERSION} in ${filePath}, got ${raw?.schema_version}`);
+    }
+    // Slice 2026-06-24-audit-5th-p2: fail fast on any fanout mode value
+    // outside the closed set `['fan-out']`. The previous 'serial' opt-out
+    // was removed by user direction — a saved `defaultMode = 'serial'`
+    // (or a hand-edited unknown value) now throws at load rather than
+    // being silently coerced, so callers see the break loudly and can
+    // remove the block from preferences.json. Migration of legacy v2
+    // preferences.json files with `fanout = {defaultMode: 'serial'}` is
+    // handled by `migratePreferences` further down — that path rewrites
+    // to `defaultMode: 'fan-out'` before `loadPreferences` re-reads.
+    const rawObj = raw;
+    if (typeof rawObj.fanout === 'object' &&
+        rawObj.fanout !== null &&
+        !Array.isArray(rawObj.fanout)) {
+        const fanoutObj = rawObj.fanout;
+        if ('defaultMode' in fanoutObj && !isFanoutMode(fanoutObj.defaultMode)) {
+            const known = FANOUT_MODES.join(' | ');
+            throw new Error(`PREFERENCES_FANOUT_INVALID: fanout.defaultMode must be one of ${known} (got ${JSON.stringify(fanoutObj.defaultMode)}) in ${filePath}. The 'serial' opt-out was removed in 2.8.4 — remove the fanout block to use the fan-out default.`);
+        }
+    }
+    return mergePreferences(DEFAULT_PREFERENCES, raw);
+}
+export function savePreferences(projectRoot, overrides) {
+    const filePath = preferencesPath(projectRoot);
+    const current = loadPreferences(projectRoot);
+    const merged = mergePreferences(current, overrides);
+    // Slice 2026-06-23-audit-4th #A2: use tmp + rename so a crash
+    // mid-write cannot leave a zero-byte or half-written preferences
+    // file. Before the fix, a power-cut or OOM-kill between
+    // writeFileSync's open and the final byte would leave
+    // .peaks/preferences.json unreadable, and the next loadPreferences
+    // would throw PREFERENCES_JSON_INVALID with no recovery path.
+    // The tmp+rename pattern matches dispatch-record-writer.ts:409-420
+    // and shared-channel.ts:336-349.
+    writeAtomic(filePath, merged);
+    return merged;
+}
+/**
+ * Atomic write helper for preferences.json. Writes to `<path>.tmp-<pid>-<ts>`
+ * and renames over the target. On Windows, `rename` is atomic for files
+ * on the same volume; on POSIX, `rename(2)` is atomic by spec.
+ */
+export function writeAtomic(filePath, prefs) {
+    const dir = dirname(filePath);
+    mkdirSync(dir, { recursive: true });
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(prefs, null, 2) + '\n', 'utf8');
+    renameSync(tmp, filePath);
+}
+function mergePreferences(base, overrides) {
+    const definedEntries = Object.entries(overrides).filter(([, value]) => value !== undefined);
+    // Shallow merge at the top level, BUT merge the `fanout` object
+    // deeply so a partial override like `{"fanout": {"perTouchpoint": {...}}}`
+    // does not silently drop `defaultMode`. Slice
+    // 2026-06-23-audit-p0-cleanup: today the fanout schema is 1 level
+    // deep, so shallow merge happens to be safe — but the field is
+    // likely to grow (perTouchpoint / perRole are obvious next additions),
+    // and a future bug fix should not silently regress opt-out callers
+    // that already specified `defaultMode` in their preferences.json.
+    const shallow = {
+        ...base,
+        ...Object.fromEntries(definedEntries),
+    };
+    const overrideFanout = overrides.fanout;
+    if (overrideFanout !== undefined &&
+        typeof overrideFanout === 'object' &&
+        overrideFanout !== null &&
+        !Array.isArray(overrideFanout)) {
+        shallow.fanout = {
+            ...base.fanout,
+            ...overrideFanout
+        };
+    }
+    return {
+        ...shallow,
+        schema_version: PREFERENCES_SCHEMA_VERSION,
+    };
+}
+export function migratePreferences(projectRoot, opts = {}) {
+    const filePath = preferencesPath(projectRoot);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`PREFERENCES_JSON_INVALID: failed to parse ${filePath}: ${err.message}`);
+    }
+    const fromVersion = typeof raw.schema_version === 'string'
+        ? raw.schema_version
+        : 'unknown';
+    if (fromVersion === PREFERENCES_SCHEMA_VERSION) {
+        return {
+            fromVersion,
+            toVersion: PREFERENCES_SCHEMA_VERSION,
+            migrated: mergePreferences(DEFAULT_PREFERENCES, raw),
+            changes: [],
+            written: false
+        };
+    }
+    const changes = [];
+    // v1 → v2: headroom.perTouchpoint fill-in (v1 only had defaultMode).
+    const headroomRaw = (raw.headroom ?? {});
+    const defaultMode = isHeadroomModeString(headroomRaw.defaultMode)
+        ? headroomRaw.defaultMode
+        : 'balanced';
+    const perTouchpoint = {
+        subAgentDispatch: defaultMode,
+        memorySearch: defaultMode,
+        retrospectiveSearch: defaultMode,
+        doctorScan: defaultMode,
+        doctorRoute: 'conservative'
+    };
+    changes.push(`headroom.perTouchpoint filled in with defaultMode='${defaultMode}' (v1 lacked per-touchpoint overrides)`);
+    if (typeof headroomRaw.compressMinBytes === 'number') {
+        changes.push(`headroom.compressMinBytes preserved at ${headroomRaw.compressMinBytes}`);
+    }
+    else {
+        changes.push(`headroom.compressMinBytes defaulted to 4096`);
+    }
+    // v1 → v2: fanout block was absent; v2 needs it. Default to the
+    // pre-v2 behavior (fan-out when ≥ 2 leaves).
+    if (raw.fanout === undefined) {
+        changes.push(`fanout.defaultMode set to 'fan-out' (matches pre-v2 default behavior)`);
+    }
+    else if (typeof raw.fanout === 'object' &&
+        raw.fanout !== null &&
+        !Array.isArray(raw.fanout) &&
+        raw.fanout.defaultMode === 'serial') {
+        // Slice 2026-06-24-audit-5th-p2: 2.8.3-era preferences.json files
+        // that opted into serial dispatch must be migrated to fan-out on
+        // load. The user's directive ("禁止单 sub-agent") makes the serial
+        // opt-out a breaking change for any project that used it.
+        changes.push(`fanout.defaultMode rewrote 'serial' → 'fan-out' (the 'serial' opt-out was removed in 2.8.4; single-sub-agent dispatch is no longer permitted when DAG has >= 2 leaves)`);
+    }
+    else {
+        changes.push(`fanout block preserved from v1`);
+    }
+    // Apply the migration through mergePreferences so the result is a
+    // fully-valid v2 ProjectPreferences.
+    const migrated = mergePreferences(DEFAULT_PREFERENCES, {
+        ...raw,
+        headroom: {
+            enabled: typeof headroomRaw.enabled === 'boolean' ? headroomRaw.enabled : true,
+            defaultMode,
+            perTouchpoint,
+            compressMinBytes: typeof headroomRaw.compressMinBytes === 'number'
+                ? headroomRaw.compressMinBytes
+                : 4096
+        },
+        fanout: typeof raw.fanout === 'object' && raw.fanout !== null && !Array.isArray(raw.fanout)
+            ? (raw.fanout.defaultMode === 'serial'
+                ? { defaultMode: 'fan-out' }
+                : raw.fanout)
+            : { defaultMode: 'fan-out' }
+    });
+    let written = false;
+    if (opts.write === true) {
+        writeAtomic(filePath, migrated);
+        written = true;
+    }
+    return {
+        fromVersion,
+        toVersion: PREFERENCES_SCHEMA_VERSION,
+        migrated,
+        changes,
+        written
+    };
+}
+function isHeadroomModeString(value) {
+    return value === 'balanced' || value === 'aggressive' || value === 'conservative';
+}