peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/understand/understand-hybrid-service.js

@@ -0,0 +1,100 @@
+import { createCodegraphInvocation, executeCodegraphInvocation } from '../codegraph/codegraph-service.js';
+import { scanUnderstandAnything, summarizeKnowledgeGraph } from './understand-scan-service.js';
+import { getErrorMessage } from '../../shared/result.js';
+const DEFAULT_FILES = ['src/index.ts', 'package.json', 'README.md'];
+function resolveFiles(files) {
+    if (files !== undefined && files.length > 0) {
+        return [...files];
+    }
+    return [...DEFAULT_FILES];
+}
+async function safeSummarize(options) {
+    try {
+        return { summary: await summarizeKnowledgeGraph(options) };
+    }
+    catch (error) {
+        return { warning: `UA summary failed: ${getErrorMessage(error)}` };
+    }
+}
+async function runCodegraph(projectRoot, files, runner) {
+    try {
+        const invocation = createCodegraphInvocation({
+            subcommand: 'affected',
+            project: projectRoot,
+            files,
+            json: true
+        });
+        const execution = await executeCodegraphInvocation(invocation, runner);
+        if (execution.exitCode !== 0) {
+            return { warning: `codegraph affected exited with code ${execution.exitCode}: ${execution.stderr.slice(0, 200)}` };
+        }
+        let payload = null;
+        let parseError;
+        try {
+            payload = JSON.parse(execution.stdout);
+        }
+        catch (error) {
+            parseError = getErrorMessage(error);
+        }
+        return {
+            block: {
+                invocation: { subcommand: 'affected', files },
+                execution,
+                payload,
+                ...(parseError !== undefined ? { parseError } : {})
+            }
+        };
+    }
+    catch (error) {
+        return { warning: `codegraph affected failed: ${getErrorMessage(error)}` };
+    }
+}
+function decideSource(uaScan, hasCodegraph) {
+    const uaPresent = uaScan.exists && uaScan.graph.exists && uaScan.graph.parseError === undefined;
+    if (uaPresent && hasCodegraph)
+        return 'ua-and-codegraph-hybrid';
+    if (uaPresent)
+        return 'ua-only';
+    if (hasCodegraph)
+        return 'ua-missing-fallback-codegraph';
+    return 'both-missing';
+}
+export async function buildUnderstandContext(options) {
+    const startedAt = Date.now();
+    const files = resolveFiles(options.files);
+    const sampleSize = options.sampleSize ?? 5;
+    const warnings = [];
+    const scanOptions = { projectRoot: options.projectRoot };
+    if (options.artifactDir !== undefined) {
+        scanOptions.artifactDir = options.artifactDir;
+    }
+    const uaScan = await scanUnderstandAnything(scanOptions);
+    const uaSummaryPromise = uaScan.exists && uaScan.graph.exists
+        ? safeSummarize({ projectRoot: options.projectRoot, sampleSize, ...(options.artifactDir !== undefined ? { artifactDir: options.artifactDir } : {}) })
+        : Promise.resolve({});
+    const [uaSummary, codegraphResult] = await Promise.all([
+        uaSummaryPromise,
+        runCodegraph(options.projectRoot, files, options.codegraphRunner)
+    ]);
+    if (uaSummary.warning)
+        warnings.push(uaSummary.warning);
+    if (codegraphResult.warning)
+        warnings.push(codegraphResult.warning);
+    const source = decideSource(uaScan, codegraphResult.block !== undefined);
+    const result = {
+        projectRoot: options.projectRoot,
+        source,
+        durationMs: Date.now() - startedAt,
+        warnings
+    };
+    if (source === 'ua-only' || source === 'ua-and-codegraph-hybrid') {
+        result.ua = {
+            scan: uaScan,
+            ...(uaSummary.summary !== undefined ? { summary: uaSummary.summary } : {})
+        };
+    }
+    if (codegraphResult.block) {
+        result.codegraph = codegraphResult.block;
+    }
+    return result;
+}

package/dist/services/understand/understand-scan-service.d.ts

@@ -0,0 +1,28 @@
+import type { UnderstandScanReport } from './understand-types.js';
+export type UnderstandScanOptions = {
+    projectRoot: string;
+    artifactDir?: string;
+};
+export declare function scanUnderstandAnything(options: UnderstandScanOptions): Promise<UnderstandScanReport>;
+export type UnderstandGraphSummary = {
+    exists: boolean;
+    path: string;
+    generatedAt: string | null;
+    topLevelFields: string[];
+    counts: {
+        nodes: number;
+        edges: number;
+        layers: number;
+        tours: number;
+    };
+    layerNames: string[];
+    tourNames: string[];
+    sampleNodes: string[];
+    parseError?: string;
+};
+export type SummarizeKnowledgeGraphOptions = {
+    projectRoot: string;
+    artifactDir?: string;
+    sampleSize?: number;
+};
+export declare function summarizeKnowledgeGraph(options: SummarizeKnowledgeGraphOptions): Promise<UnderstandGraphSummary>;

package/dist/services/understand/understand-scan-service.js

@@ -0,0 +1,170 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDirectory, pathExists, readText } from '../../shared/fs.js';
+import { getErrorMessage } from '../../shared/result.js';
+import { loadPreferences } from '../preferences/preferences-service.js';
+function defaultArtifactDir(projectRoot) {
+    return join(projectRoot, '.understand-anything');
+}
+function countArrayField(record, key) {
+    const value = record[key];
+    return Array.isArray(value) ? value.length : 0;
+}
+async function readFlag(path) {
+    return { exists: await pathExists(path), path };
+}
+async function readGraph(graphPath) {
+    if (!(await pathExists(graphPath))) {
+        return { exists: false, path: graphPath };
+    }
+    const stats = await stat(graphPath);
+    const raw = await readText(graphPath);
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {
+                exists: true,
+                path: graphPath,
+                sizeBytes: stats.size,
+                parseError: 'knowledge-graph.json must be a JSON object'
+            };
+        }
+        const record = parsed;
+        return {
+            exists: true,
+            path: graphPath,
+            sizeBytes: stats.size,
+            topLevelFields: Object.keys(record).sort(),
+            counts: {
+                nodes: countArrayField(record, 'nodes'),
+                edges: countArrayField(record, 'edges'),
+                layers: countArrayField(record, 'layers'),
+                tours: countArrayField(record, 'tours')
+            }
+        };
+    }
+    catch (error) {
+        return {
+            exists: true,
+            path: graphPath,
+            sizeBytes: stats.size,
+            parseError: getErrorMessage(error)
+        };
+    }
+}
+export async function scanUnderstandAnything(options) {
+    const artifactDir = options.artifactDir ?? defaultArtifactDir(options.projectRoot);
+    const exists = await isDirectory(artifactDir);
+    // L3.1: read uaPrompt from preferences.json (graceful — returns 'unset' if missing/broken)
+    const uaPrompt = await readUaPrompt(options.projectRoot);
+    if (!exists) {
+        return {
+            exists: false,
+            artifactDir,
+            graph: { exists: false, path: join(artifactDir, 'knowledge-graph.json') },
+            intermediate: { exists: false, path: join(artifactDir, 'intermediate') },
+            diffOverlay: { exists: false, path: join(artifactDir, 'diff-overlay.json') },
+            uaPrompt
+        };
+    }
+    const graph = await readGraph(join(artifactDir, 'knowledge-graph.json'));
+    const intermediate = await readFlag(join(artifactDir, 'intermediate'));
+    const diffOverlay = await readFlag(join(artifactDir, 'diff-overlay.json'));
+    return { exists: true, artifactDir, graph, intermediate, diffOverlay, uaPrompt };
+}
+async function readUaPrompt(projectRoot) {
+    try {
+        const prefs = await loadPreferences(projectRoot);
+        return prefs.uaPrompt;
+    }
+    catch {
+        return 'unset';
+    }
+}
+function pickStringId(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    for (const key of ['id', 'path', 'name', 'label']) {
+        const candidate = record[key];
+        if (typeof candidate === 'string' && candidate.length > 0) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function pickStringField(record, key) {
+    const value = record[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function pickNameArray(record, key) {
+    const value = record[key];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((entry) => {
+        if (typeof entry === 'string') {
+            return entry;
+        }
+        return pickStringId(entry);
+    })
+        .filter((entry) => entry !== null);
+}
+export async function summarizeKnowledgeGraph(options) {
+    const scanOptions = { projectRoot: options.projectRoot };
+    if (options.artifactDir !== undefined) {
+        scanOptions.artifactDir = options.artifactDir;
+    }
+    const scan = await scanUnderstandAnything(scanOptions);
+    const sampleSize = options.sampleSize ?? 5;
+    if (!scan.graph.exists) {
+        return {
+            exists: false,
+            path: scan.graph.path,
+            generatedAt: null,
+            topLevelFields: [],
+            counts: { nodes: 0, edges: 0, layers: 0, tours: 0 },
+            layerNames: [],
+            tourNames: [],
+            sampleNodes: []
+        };
+    }
+    if (scan.graph.parseError !== undefined) {
+        return {
+            exists: true,
+            path: scan.graph.path,
+            generatedAt: null,
+            topLevelFields: [],
+            counts: { nodes: 0, edges: 0, layers: 0, tours: 0 },
+            layerNames: [],
+            tourNames: [],
+            sampleNodes: [],
+            parseError: scan.graph.parseError
+        };
+    }
+    const raw = await readText(scan.graph.path);
+    const parsed = JSON.parse(raw);
+    const record = parsed;
+    const generatedAt = pickStringField(record, 'generatedAt');
+    const nodes = Array.isArray(record.nodes) ? record.nodes : [];
+    const sampleNodes = nodes.slice(0, sampleSize)
+        .map((entry) => pickStringId(entry))
+        .filter((entry) => entry !== null);
+    return {
+        exists: true,
+        path: scan.graph.path,
+        generatedAt,
+        topLevelFields: Object.keys(record).sort(),
+        counts: {
+            nodes: countArrayField(record, 'nodes'),
+            edges: countArrayField(record, 'edges'),
+            layers: countArrayField(record, 'layers'),
+            tours: countArrayField(record, 'tours')
+        },
+        layerNames: pickNameArray(record, 'layers'),
+        tourNames: pickNameArray(record, 'tours'),
+        sampleNodes
+    };
+}

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

@@ -0,0 +1,50 @@
+export type UnderstandGraphReport = {
+    exists: boolean;
+    path: string;
+    sizeBytes?: number;
+    topLevelFields?: string[];
+    counts?: {
+        nodes: number;
+        edges: number;
+        layers: number;
+        tours: number;
+    };
+    parseError?: string;
+};
+export type UnderstandFlagReport = {
+    exists: boolean;
+    path: string;
+};
+/**
+ * Slice L3.1 — UA opt-in UX state. 'unset' triggers an opt-in prompt on
+ * first scan; 'skip-this-session' suppresses the prompt for the current
+ * session; 'skip-forever' writes to .peaks/preferences.json to suppress
+ * all future prompts. Mirrors preferences.json:uaPrompt.
+ */
+export type UaPromptDecision = 'unset' | 'skip-this-session' | 'skip-forever';
+export type UnderstandScanReport = {
+    exists: boolean;
+    artifactDir: string;
+    graph: UnderstandGraphReport;
+    intermediate: UnderstandFlagReport;
+    diffOverlay: UnderstandFlagReport;
+    /** Slice L3.1: opt-in UX state from preferences.json:uaPrompt. */
+    readonly uaPrompt?: UaPromptDecision;
+};
+/**
+ * Slice L3.1 — opt-in prompt payload. When uaPrompt === 'unset' and UA is
+ * 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.
+ */
+export interface UaOptInPrompt {
+    readonly version: 1;
+    readonly tool: 'ua-opt-in';
+    readonly artifactDir: string;
+    readonly reason: 'ua-artifact-missing';
+    readonly options: readonly {
+        readonly id: 'install' | 'fallback-this-session' | 'fallback-forever';
+        readonly label: string;
+        readonly description: string;
+    }[];
+}

package/dist/services/understand/understand-types.js

@@ -0,0 +1 @@
+export {};

package/dist/services/upgrade/1x-detector-service.d.ts

@@ -0,0 +1,7 @@
+export interface OneXState {
+    readonly isOneX: boolean;
+    readonly signals: readonly string[];
+    readonly projectRoot: string | null;
+    readonly configPath: string | null;
+}
+export declare function detect1xProjectState(cwd?: string): OneXState;

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

@@ -0,0 +1,94 @@
+/**
+ * 1.x → 2.0 detection service — TypeScript mirror of
+ * `scripts/install-skills.mjs:detect1xProjectState`.
+ *
+ * Slice: 2026-06-12-code-step-0-55-1x-detection.
+ *
+ * The canonical implementation lives in the .mjs postinstall
+ * (because the postinstall runs before any TS compile step).
+ * 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.
+ *
+ * The two implementations MUST stay in parity. The
+ * `tests/integration/upgrade/1x-detector-parity.test.ts`
+ * test exercises both on the same fixture and asserts
+ * their outputs match.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const MAX_WALK_UP = 8;
+export function detect1xProjectState(cwd = process.cwd()) {
+    const home = homedir();
+    const signals = [];
+    let projectRoot = null;
+    let configPath = null;
+    // Walk up from cwd looking for .peaks/_runtime (signals
+    // we're inside a peaks project).
+    let dir = cwd;
+    for (let i = 0; i < MAX_WALK_UP; i += 1) {
+        const peaksRuntime = join(dir, '.peaks', '_runtime');
+        if (existsSync(peaksRuntime)) {
+            projectRoot = dir;
+            break;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Signal 1: ~/.peaks/config.json with 1.x version
+    const globalConfig = join(home, '.peaks', 'config.json');
+    if (existsSync(globalConfig)) {
+        try {
+            const raw = JSON.parse(readFileSync(globalConfig, 'utf8'));
+            if (typeof raw['version'] === 'string' && /^1\./.test(raw['version'])) {
+                signals.push(`global config at ${globalConfig} is 1.x (${raw['version']})`);
+                if (configPath === null)
+                    configPath = globalConfig;
+            }
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // ignore parse error — the 1.x detection is best-effort
+        }
+    }
+    // Signal 2: .claude/rules/common/dev-preference.md with peaks progress
+    if (projectRoot !== null) {
+        const devPref = join(projectRoot, '.claude', 'rules', 'common', 'dev-preference.md');
+        if (existsSync(devPref)) {
+            try {
+                const body = readFileSync(devPref, 'utf8');
+                if (/peaks progress/i.test(body)) {
+                    signals.push(`${devPref} references "peaks progress" (1.x CLI surface, removed in slice #014)`);
+                }
+            }
+            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                // ignore
+            }
+        }
+        // Signal 3: project preferences.json missing or 1.x
+        const prefs = join(projectRoot, '.peaks', 'preferences.json');
+        if (!existsSync(prefs)) {
+            signals.push(`${prefs} does not exist (1.x project never migrated)`);
+        }
+        else {
+            try {
+                const raw = JSON.parse(readFileSync(prefs, 'utf8'));
+                if (raw['schema_version'] !== '2.0.0') {
+                    signals.push(`${prefs} has schema_version ${JSON.stringify(raw['schema_version'])}, expected '2.0.0'`);
+                }
+            }
+            catch {
+                signals.push(`${prefs} exists but is not valid JSON`);
+            }
+        }
+    }
+    return {
+        isOneX: signals.length > 0,
+        signals,
+        projectRoot,
+        configPath,
+    };
+}

package/dist/services/upgrade/gitignore-migrate-service.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The 2.0 canonical ignore block. Mirrors the same paths
+ * peaks-loop's own .gitignore uses; kept in lockstep manually
+ * (the peaks-loop root .gitignore is the source of truth).
+ *
+ * Sentinel: every emitted line carries the marker comment so
+ * the migration can detect "already-migrated" and stay
+ * idempotent.
+ */
+export declare const PEAKS_2_0_BLOCK_SENTINEL = "# peaks-loop 2.0 canonical ignore block \u2014 managed by `peaks upgrade --to 2.0`";
+export declare const CANONICAL_2_0_PEAKS_BLOCK: string;
+/**
+ * Returns true when `line` is a wholesale ignore of the entire
+ * `.peaks/` tree (the 1.x pattern that breaks 2.0 tracking).
+ *
+ * Examples that match:    `.peaks`  `.peaks/`  `/.peaks`  `/.peaks/`  `  .peaks/  `
+ * Examples that DON'T:    `.peaks/_runtime/`  `# .peaks/ comment`  `.peaks_other`
+ */
+export declare function isStaleWholesalePeaksRule(line: string): boolean;
+export interface MigrateGitignoreContentResult {
+    /** True if at least one stale wholesale .peaks rule was removed OR the canonical block was appended. */
+    readonly changed: boolean;
+    /** The exact lines that were removed (verbatim, with original whitespace). */
+    readonly removedRules: readonly string[];
+    /** The migrated content (always ends with a newline). */
+    readonly content: string;
+}
+/**
+ * Pure function: takes the .gitignore content, returns the
+ * migrated content + diff summary. No I/O.
+ */
+export declare function migrateGitignoreContent(input: string): MigrateGitignoreContentResult;
+export interface MigrateGitignoreFileInput {
+    readonly projectRoot: string;
+    readonly apply?: boolean;
+}
+export interface MigrateGitignoreFileResult {
+    /** True if .gitignore is absent (nothing to migrate). */
+    readonly missing: boolean;
+    /** True if the migration would change the file. */
+    readonly changed: boolean;
+    /** True only if `apply: true` AND `changed: true`. */
+    readonly appliedWrite: boolean;
+    /** Absolute path to the timestamped backup file, or null. */
+    readonly backupPath: string | null;
+    /** Removed lines (verbatim). */
+    readonly removedRules: readonly string[];
+}
+/**
+ * FS variant: reads .gitignore, runs migration, optionally
+ * writes the result + a timestamped backup of the original.
+ *
+ * Date.now() is used for the backup suffix; in test environments
+ * where determinism matters, the caller can stub Date via vi.
+ */
+export declare function migrateGitignoreFile(input: MigrateGitignoreFileInput): MigrateGitignoreFileResult;

package/dist/services/upgrade/gitignore-migrate-service.js

@@ -0,0 +1,170 @@
+/**
+ * .gitignore 1.x → 2.0 migration service.
+ *
+ * Real bug surfaced by ice-cola dogfood 2026-06-12:
+ *   - 1.x consumer projects often have a wholesale `/.peaks/` (or
+ *     `.peaks/` / `.peaks`) entry in their .gitignore — the 1.x
+ *     install treated .peaks/ as the tool's ephemeral working
+ *     directory.
+ *   - In 2.0 the .peaks/ tree is split: most subdirectories
+ *     remain ignored (_runtime, _sub_agents, audit, etc.) but
+ *     several MUST be tracked: .peaks/standards/,
+ *     .peaks/memory/*.md (durable LLM-authored memories),
+ *     .peaks/PROJECT.md, and the user opt-in dotfiles.
+ *   - A wholesale `.peaks/` ignore silently hides every 2.0
+ *     tracked artifact, violating the "one-key completion" tenet
+ *     because the user runs upgrade, sees 6/6 pass, then git
+ *     status shows no new tracked files — the upgrade looks
+ *     "done" but nothing landed in git.
+ *
+ * The service:
+ *   1. Reads the project's .gitignore (string in / string out;
+ *      no I/O in the pure function).
+ *   2. Detects every line that is a wholesale-ignore of .peaks/
+ *      (with or without leading slash, with or without trailing
+ *      slash, ignoring surrounding whitespace).
+ *   3. Removes those lines and appends the canonical 2.0 block
+ *      (granular subpaths) if not already present.
+ *   4. The FS variant `migrateGitignoreFile` adds backup +
+ *      atomic write on top.
+ *
+ * Idempotent: re-running on a migrated .gitignore is a no-op.
+ *
+ * Spec reference: docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §8.4
+ * (per-project state in .peaks/preferences.json, durable
+ * memories in .peaks/memory/*.md).
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The 2.0 canonical ignore block. Mirrors the same paths
+ * peaks-loop's own .gitignore uses; kept in lockstep manually
+ * (the peaks-loop root .gitignore is the source of truth).
+ *
+ * Sentinel: every emitted line carries the marker comment so
+ * the migration can detect "already-migrated" and stay
+ * idempotent.
+ */
+export const PEAKS_2_0_BLOCK_SENTINEL = '# peaks-loop 2.0 canonical ignore block — managed by `peaks upgrade --to 2.0`';
+export const CANONICAL_2_0_PEAKS_BLOCK = [
+    PEAKS_2_0_BLOCK_SENTINEL,
+    '.peaks/_runtime/',
+    '.peaks/_dogfood/',
+    '.peaks/_sub_agents/',
+    '.peaks/audit/',
+    '.peaks/system/',
+    '.peaks/runtime/',
+    '.peaks/preferences.json',
+    '.peaks/memory/upgrade-2.0-*.md',
+].join('\n');
+/**
+ * Returns true when `line` is a wholesale ignore of the entire
+ * `.peaks/` tree (the 1.x pattern that breaks 2.0 tracking).
+ *
+ * Examples that match:    `.peaks`  `.peaks/`  `/.peaks`  `/.peaks/`  `  .peaks/  `
+ * Examples that DON'T:    `.peaks/_runtime/`  `# .peaks/ comment`  `.peaks_other`
+ */
+export function isStaleWholesalePeaksRule(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0)
+        return false;
+    if (trimmed.startsWith('#'))
+        return false;
+    // Strip leading slash (relative-to-repo-root convention) and
+    // trailing slash (directory marker); both equivalent in
+    // .gitignore semantics for wholesale ignore.
+    const normalized = trimmed.replace(/^\//, '').replace(/\/$/, '');
+    return normalized === '.peaks';
+}
+/**
+ * Pure function: takes the .gitignore content, returns the
+ * migrated content + diff summary. No I/O.
+ */
+export function migrateGitignoreContent(input) {
+    const lines = input.split('\n');
+    const removed = [];
+    const kept = [];
+    for (const line of lines) {
+        if (isStaleWholesalePeaksRule(line)) {
+            removed.push(line.trim());
+        }
+        else {
+            kept.push(line);
+        }
+    }
+    // Already-migrated detection: if the canonical block is
+    // already present AND nothing was removed, this is a no-op.
+    const hasCanonicalBlock = input.includes(PEAKS_2_0_BLOCK_SENTINEL);
+    if (removed.length === 0 && hasCanonicalBlock) {
+        return { changed: false, removedRules: [], content: input };
+    }
+    // Already-migrated AND nothing stale: no-op, return original
+    // verbatim so byte-equality holds for idempotency.
+    if (removed.length === 0 && !hasCanonicalBlock) {
+        // Check whether there's anything peaks-related at all; if
+        // not, treat as no-op (the user explicitly chose not to
+        // ignore .peaks/ — respect that).
+        return { changed: false, removedRules: [], content: input };
+    }
+    // Removed at least one stale rule. Append canonical block
+    // if not already present.
+    let body = kept.join('\n');
+    if (!body.endsWith('\n') && body.length > 0) {
+        body += '\n';
+    }
+    if (!hasCanonicalBlock) {
+        body += CANONICAL_2_0_PEAKS_BLOCK + '\n';
+    }
+    return { changed: true, removedRules: removed, content: body };
+}
+/**
+ * FS variant: reads .gitignore, runs migration, optionally
+ * writes the result + a timestamped backup of the original.
+ *
+ * Date.now() is used for the backup suffix; in test environments
+ * where determinism matters, the caller can stub Date via vi.
+ */
+export function migrateGitignoreFile(input) {
+    const path = join(input.projectRoot, '.gitignore');
+    if (!existsSync(path)) {
+        return {
+            missing: true,
+            changed: false,
+            appliedWrite: false,
+            backupPath: null,
+            removedRules: [],
+        };
+    }
+    const before = readFileSync(path, 'utf8');
+    const result = migrateGitignoreContent(before);
+    if (!result.changed) {
+        return {
+            missing: false,
+            changed: false,
+            appliedWrite: false,
+            backupPath: null,
+            removedRules: [],
+        };
+    }
+    if (input.apply !== true) {
+        return {
+            missing: false,
+            changed: true,
+            appliedWrite: false,
+            backupPath: null,
+            removedRules: result.removedRules,
+        };
+    }
+    // Apply: write backup first, then atomic-overwrite the original.
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = join(input.projectRoot, `.gitignore.peaks-2.0-backup-${ts}`);
+    writeFileSync(backupPath, before, 'utf8');
+    writeFileSync(path, result.content, 'utf8');
+    return {
+        missing: false,
+        changed: true,
+        appliedWrite: true,
+        backupPath,
+        removedRules: result.removedRules,
+    };
+}