@cleocode/core 2026.4.7 → 2026.4.11

package/src/system/__tests__/backup.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Tests for the system backup module.
+ *
+ * Focus areas (T5158):
+ * - createBackup uses VACUUM INTO via the live SQLite handle and falls back
+ *   gracefully when the handle is unavailable (non-fatal).
+ * - createBackup uses atomic tmp-then-rename for JSON files.
+ * - createBackup writes a .meta.json sidecar enumerating captured files.
+ * - listSystemBackups reads back the sidecars.
+ * - restoreBackup materializes files back into .cleo/.
+ *
+ * These tests rely on filesystem-level state in a temporary directory —
+ * they do NOT open a real CLEO database. SQLite handles are provided via
+ * vi.doMock to exercise the VACUUM INTO code path.
+ *
+ * @task T5158
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+describe('system/backup', () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    testDir = await mkdtemp(join(tmpdir(), 'cleo-system-backup-'));
+    mkdirSync(join(testDir, '.cleo'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  it('createBackup snapshots SQLite files via VACUUM INTO and JSON via atomic write', async () => {
+    const tasksExec = vi.fn((sql: string) => {
+      // Simulate VACUUM INTO by creating the destination file.
+      const match = sql.match(/VACUUM INTO '(.+)'/);
+      if (match) writeFileSync(match[1]!, 'vacuumed-tasks');
+    });
+    const brainExec = vi.fn((sql: string) => {
+      const match = sql.match(/VACUUM INTO '(.+)'/);
+      if (match) writeFileSync(match[1]!, 'vacuumed-brain');
+    });
+
+    // createBackup dynamically imports sqlite.js / brain-sqlite.js to
+    // ensure the DBs are open before snapshotting; mocks must cover both
+    // the `getDb`/`getBrainDb` open entry points AND the
+    // `getNativeDb`/`getBrainNativeDb` handle accessors.
+    vi.doMock('../../store/sqlite.js', () => ({
+      getDb: vi.fn().mockResolvedValue({}),
+      getNativeDb: () => ({ exec: tasksExec }),
+    }));
+    vi.doMock('../../store/brain-sqlite.js', () => ({
+      getBrainDb: vi.fn().mockResolvedValue({}),
+      getBrainNativeDb: () => ({ exec: brainExec }),
+    }));
+
+    // Seed source files so existsSync checks pass in createBackup.
+    writeFileSync(join(testDir, '.cleo', 'tasks.db'), 'live-tasks');
+    writeFileSync(join(testDir, '.cleo', 'brain.db'), 'live-brain');
+    writeFileSync(join(testDir, '.cleo', 'config.json'), '{"version":"test"}');
+    writeFileSync(join(testDir, '.cleo', 'project-info.json'), '{"projectId":"test"}');
+
+    const { createBackup } = await import('../backup.js');
+    const result = await createBackup(testDir, { type: 'snapshot', note: 't5158-test' });
+
+    expect(result.files).toEqual(
+      expect.arrayContaining(['tasks.db', 'brain.db', 'config.json', 'project-info.json']),
+    );
+
+    // VACUUM INTO was invoked with wal_checkpoint preceding it.
+    const tasksCalls = tasksExec.mock.calls.map((c) => c[0]);
+    const brainCalls = brainExec.mock.calls.map((c) => c[0]);
+    const tasksWal = tasksCalls.findIndex((c) => c.includes('wal_checkpoint'));
+    const tasksVacuum = tasksCalls.findIndex((c) => c.includes('VACUUM INTO'));
+    expect(tasksWal).toBeGreaterThanOrEqual(0);
+    expect(tasksVacuum).toBeGreaterThan(tasksWal);
+    const brainWal = brainCalls.findIndex((c) => c.includes('wal_checkpoint'));
+    const brainVacuum = brainCalls.findIndex((c) => c.includes('VACUUM INTO'));
+    expect(brainWal).toBeGreaterThanOrEqual(0);
+    expect(brainVacuum).toBeGreaterThan(brainWal);
+
+    // Snapshot files materialized in the backup dir.
+    const snapshotDir = join(testDir, '.cleo', 'backups', 'snapshot');
+    const files = readdirSync(snapshotDir);
+    expect(files.some((f) => f.startsWith('tasks.db.'))).toBe(true);
+    expect(files.some((f) => f.startsWith('brain.db.'))).toBe(true);
+    expect(files.some((f) => f.startsWith('config.json.'))).toBe(true);
+    expect(files.some((f) => f.startsWith('project-info.json.'))).toBe(true);
+
+    // Metadata sidecar.
+    const metaFile = files.find((f) => f.endsWith('.meta.json'));
+    expect(metaFile).toBeDefined();
+    const meta = JSON.parse(readFileSync(join(snapshotDir, metaFile!), 'utf-8'));
+    expect(meta.note).toBe('t5158-test');
+    expect(meta.files).toEqual(
+      expect.arrayContaining(['tasks.db', 'brain.db', 'config.json', 'project-info.json']),
+    );
+  });
+
+  it('createBackup skips SQLite files when the native handle is null (non-fatal)', async () => {
+    vi.doMock('../../store/sqlite.js', () => ({
+      getDb: vi.fn().mockResolvedValue({}),
+      getNativeDb: () => null,
+    }));
+    vi.doMock('../../store/brain-sqlite.js', () => ({
+      getBrainDb: vi.fn().mockResolvedValue({}),
+      getBrainNativeDb: () => null,
+    }));
+
+    writeFileSync(join(testDir, '.cleo', 'tasks.db'), 'live-tasks');
+    writeFileSync(join(testDir, '.cleo', 'brain.db'), 'live-brain');
+    writeFileSync(join(testDir, '.cleo', 'config.json'), '{"v":1}');
+
+    const { createBackup } = await import('../backup.js');
+    const result = await createBackup(testDir);
+
+    // JSON file captured, SQLite files skipped because no handle available.
+    expect(result.files).toContain('config.json');
+    expect(result.files).not.toContain('tasks.db');
+    expect(result.files).not.toContain('brain.db');
+  });
+
+  it('listSystemBackups reads sidecars from all known backup type dirs', async () => {
+    const snapshotDir = join(testDir, '.cleo', 'backups', 'snapshot');
+    const safetyDir = join(testDir, '.cleo', 'backups', 'safety');
+    mkdirSync(snapshotDir, { recursive: true });
+    mkdirSync(safetyDir, { recursive: true });
+
+    writeFileSync(
+      join(snapshotDir, 'snapshot-A.meta.json'),
+      JSON.stringify({
+        backupId: 'snapshot-A',
+        type: 'snapshot',
+        timestamp: '2026-04-07T12:00:00.000Z',
+        files: ['config.json'],
+      }),
+    );
+    writeFileSync(
+      join(safetyDir, 'safety-B.meta.json'),
+      JSON.stringify({
+        backupId: 'safety-B',
+        type: 'safety',
+        timestamp: '2026-04-07T13:00:00.000Z',
+        files: ['tasks.db'],
+      }),
+    );
+
+    const { listSystemBackups } = await import('../backup.js');
+    const entries = listSystemBackups(testDir);
+
+    expect(entries.length).toBe(2);
+    // Newest first.
+    expect(entries[0]?.backupId).toBe('safety-B');
+    expect(entries[1]?.backupId).toBe('snapshot-A');
+  });
+
+  it('restoreBackup materializes captured files back into .cleo/', async () => {
+    const snapshotDir = join(testDir, '.cleo', 'backups', 'snapshot');
+    mkdirSync(snapshotDir, { recursive: true });
+    const backupId = 'snapshot-restore-test';
+
+    writeFileSync(join(snapshotDir, `tasks.db.${backupId}`), 'restored-tasks');
+    writeFileSync(join(snapshotDir, `config.json.${backupId}`), '{"restored":true}');
+    writeFileSync(
+      join(snapshotDir, `${backupId}.meta.json`),
+      JSON.stringify({
+        backupId,
+        type: 'snapshot',
+        timestamp: '2026-04-07T14:00:00.000Z',
+        files: ['tasks.db', 'config.json'],
+      }),
+    );
+
+    // Pre-existing live copies the restore will overwrite.
+    writeFileSync(join(testDir, '.cleo', 'tasks.db'), 'stale-tasks');
+    writeFileSync(join(testDir, '.cleo', 'config.json'), '{"stale":true}');
+
+    const { restoreBackup } = await import('../backup.js');
+    const result = restoreBackup(testDir, { backupId });
+
+    expect(result.restored).toBe(true);
+    expect(result.filesRestored).toEqual(expect.arrayContaining(['tasks.db', 'config.json']));
+    expect(readFileSync(join(testDir, '.cleo', 'tasks.db'), 'utf-8')).toBe('restored-tasks');
+    expect(readFileSync(join(testDir, '.cleo', 'config.json'), 'utf-8')).toBe('{"restored":true}');
+  });
+
+  it('restoreBackup throws NOT_FOUND for a missing backupId', async () => {
+    const { restoreBackup } = await import('../backup.js');
+    expect(() => restoreBackup(testDir, { backupId: 'nonexistent' })).toThrowError(
+      /Backup not found/,
+    );
+  });
+});
+
+// Sanity: ensure the safety snapshot produced by the vacuumed blob is readable
+// as a normal file (we treat .db files as opaque blobs during restore).
+describe('system/backup — restored .db files are byte-identical', () => {
+  let testDir: string;
+  beforeEach(async () => {
+    vi.resetModules();
+    testDir = await mkdtemp(join(tmpdir(), 'cleo-system-backup-restore-'));
+    mkdirSync(join(testDir, '.cleo'), { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  it('restoreBackup copies .db files without re-vacuuming', async () => {
+    const snapshotDir = join(testDir, '.cleo', 'backups', 'snapshot');
+    mkdirSync(snapshotDir, { recursive: true });
+    const backupId = 'snapshot-byte-identity';
+    const payload = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+    writeFileSync(join(snapshotDir, `tasks.db.${backupId}`), payload);
+    writeFileSync(
+      join(snapshotDir, `${backupId}.meta.json`),
+      JSON.stringify({
+        backupId,
+        type: 'snapshot',
+        timestamp: '2026-04-07T15:00:00.000Z',
+        files: ['tasks.db'],
+      }),
+    );
+
+    const { restoreBackup } = await import('../backup.js');
+    const result = restoreBackup(testDir, { backupId });
+    expect(result.restored).toBe(true);
+
+    const liveBytes = readFileSync(join(testDir, '.cleo', 'tasks.db'));
+    expect(Buffer.compare(liveBytes, payload)).toBe(0);
+    expect(existsSync(join(testDir, '.cleo', 'tasks.db'))).toBe(true);
+  });
+});

package/src/system/backup.ts

@@ -1,33 +1,153 @@
 /**
  * Backup and restore core module.
+ *
+ * Produces full-`.cleo/` snapshots containing tasks.db, brain.db, config.json
+ * and project-info.json using the safest available method for each file type:
+ *
+ *   - SQLite databases: `VACUUM INTO` via the live native handle (see
+ *     {@link ../store/sqlite-backup.ts}). This is the ONLY safe way to
+ *     snapshot a WAL-mode SQLite database while it is open — raw filesystem
+ *     copies can capture torn writes or stale WAL frames.
+ *
+ *   - JSON files: atomic tmp-then-rename via {@link atomicWrite} so a partial
+ *     write can never corrupt the backup target.
+ *
+ * Snapshots are recorded under `.cleo/backups/{type}/` with a JSON sidecar
+ * (`{backupId}.meta.json`) enumerating which files were captured and how.
+ * Restores read the same sidecars and materialize each file back into the
+ * live `.cleo/` directory.
+ *
+ * This is the backing store for the `cleo backup` and `cleo restore backup`
+ * CLI verbs (see packages/cleo/src/cli/commands/backup.ts and restore.ts).
+ *
  * @task T4783
+ * @task T5158 — extended to use VACUUM INTO for .db files and atomicWrite for JSON
+ * @task T306  — extended to support global-tier scope (nexus.db; epic T299)
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
+import { getBrainNativeDb } from '../store/brain-sqlite.js';
+import { getNativeDb } from '../store/sqlite.js';
 
+/** Safe wrapper around VACUUM INTO: flushes WAL then clones the DB. */
+function safeSqliteSnapshot(db: { exec: (sql: string) => void } | null, destPath: string): boolean {
+  if (!db) return false;
+  db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+  const safeDest = destPath.replace(/'/g, "''");
+  db.exec(`VACUUM INTO '${safeDest}'`);
+  return true;
+}
+
+/**
+ * Synchronous atomic write: writes to a sibling `.tmp` file and renames on
+ * success. Mirrors the behavior of `write-file-atomic` but in a sync flavor
+ * suitable for `createBackup()` which has a sync contract throughout its
+ * call chain.
+ *
+ * On rename failure the tmp file is best-effort cleaned up. Throws on the
+ * originating error so callers can decide how to handle the backup partial.
+ */
+function atomicWriteSync(destPath: string, data: Buffer | string): void {
+  mkdirSync(dirname(destPath), { recursive: true });
+  const tmp = `${destPath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(tmp, data);
+    renameSync(tmp, destPath);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* ignore cleanup failure */
+    }
+    throw err;
+  }
+}
+
+/** Result shape returned by {@link createBackup}. */
 export interface BackupResult {
+  /** Unique backup identifier (timestamped). */
   backupId: string;
+  /** Absolute path to the directory containing the snapshot files. */
   path: string;
+  /** ISO-8601 timestamp when the backup was created. */
   timestamp: string;
+  /** Backup category (`snapshot`, `safety`, `migration`). */
   type: string;
+  /** Files that were successfully captured into this backup. */
   files: string[];
+  /**
+   * Global-tier snapshot results, populated when `opts.includeGlobal` is true.
+   * Key is the DB name (e.g. `'nexus'`), value is the snapshot path or an
+   * empty string when the DB was not initialized.
+   *
+   * @task T306
+   * @epic T299
+   */
+  global?: Record<string, string>;
 }
 
+/** Result shape returned by {@link restoreBackup}. */
 export interface RestoreResult {
+  /** Whether any files were actually restored (false if none matched). */
   restored: boolean;
+  /** The backup identifier that was restored. */
   backupId: string;
+  /** ISO-8601 timestamp of the original backup. */
   timestamp: string;
+  /** File names that were successfully restored back into `.cleo/`. */
   filesRestored: string[];
 }
 
-/** Create a backup of CLEO data files. */
-export function createBackup(
+/**
+ * Create a backup of the canonical CLEO data files.
+ *
+ * Produces safe copies via VACUUM INTO (for SQLite) and atomicWrite
+ * (for JSON) into `.cleo/backups/{type}/`. Writes a `{backupId}.meta.json`
+ * sidecar describing the snapshot.
+ *
+ * Opens both `tasks.db` and `brain.db` through their canonical drizzle
+ * accessors before snapshotting so that the native DB handles are live
+ * when `safeSqliteSnapshot` asks for them. This makes the function
+ * self-contained — callers do not need to pre-open the DBs.
+ *
+ * When `opts.includeGlobal` is true, also snapshots global-tier databases
+ * (currently `nexus.db`) via {@link vacuumIntoGlobalBackup}. Global snapshots
+ * are written to `$XDG_DATA_HOME/cleo/backups/sqlite/` and returned in
+ * `result.global`.
+ *
+ * Async because opening the database engines requires async migration
+ * reconciliation (ADR-012). The CLI dispatch layer awaits this result.
+ *
+ * @task T306
+ * @epic T299
+ */
+export async function createBackup(
   projectRoot: string,
-  opts?: { type?: string; note?: string },
-): BackupResult {
+  opts?: {
+    type?: string;
+    note?: string;
+    /**
+     * When true, also snapshot global-tier databases (nexus.db).
+     * Defaults to false for backwards compatibility.
+     *
+     * @task T306
+     * @epic T299
+     */
+    includeGlobal?: boolean;
+  },
+): Promise<BackupResult> {
   const cleoDir = join(projectRoot, '.cleo');
   const btype = opts?.type || 'snapshot';
   const timestamp = new Date().toISOString();
@@ -38,27 +158,72 @@ export function createBackup(
     mkdirSync(backupDir, { recursive: true });
   }
 
-  const filesToBackup = ['tasks.db', 'brain.db', 'config.json', 'project-info.json'];
+  // Ensure both SQLite engines are initialized so getNativeDb/
+  // getBrainNativeDb return live handles when we call them below. Both
+  // opens are best-effort — if one fails we still snapshot whatever we
+  // can reach (plus the JSON files). Dynamic imports avoid pulling
+  // drizzle into test suites that mock the store layer.
+  try {
+    const { getDb } = await import('../store/sqlite.js');
+    await getDb(projectRoot);
+  } catch {
+    // tasks.db open failed — will be skipped by the sqlite target below
+  }
+  try {
+    const { getBrainDb } = await import('../store/brain-sqlite.js');
+    await getBrainDb(projectRoot);
+  } catch {
+    // brain.db open failed — will be skipped by the sqlite target below
+  }
+
+  /**
+   * Per-file backup strategy. SQLite files go through `safeSqliteSnapshot`
+   * (VACUUM INTO), JSON files through `atomicWrite`. Anything not in this
+   * table is skipped.
+   */
+  const sqliteTargets: Array<{
+    file: string;
+    getDb: () => { exec: (sql: string) => void } | null;
+  }> = [
+    { file: 'tasks.db', getDb: getNativeDb },
+    { file: 'brain.db', getDb: getBrainNativeDb },
+  ];
+  const jsonTargets: string[] = ['config.json', 'project-info.json'];
   const backedUp: string[] = [];
 
-  for (const file of filesToBackup) {
-    const src = join(cleoDir, file);
-    if (existsSync(src)) {
-      const dest = join(backupDir, `${file}.${backupId}`);
-      try {
-        const content = readFileSync(src);
-        writeFileSync(dest, content);
-        backedUp.push(file);
-      } catch {
-        // skip files that fail to copy
+  // SQLite via VACUUM INTO.
+  for (const target of sqliteTargets) {
+    const src = join(cleoDir, target.file);
+    if (!existsSync(src)) continue;
+    const dest = join(backupDir, `${target.file}.${backupId}`);
+    try {
+      const ok = safeSqliteSnapshot(target.getDb(), dest);
+      if (ok) {
+        backedUp.push(target.file);
       }
+    } catch {
+      // skip files that fail to snapshot — backup remains partial but usable
     }
   }
 
-  // Write metadata
+  // JSON via atomic write.
+  for (const file of jsonTargets) {
+    const src = join(cleoDir, file);
+    if (!existsSync(src)) continue;
+    const dest = join(backupDir, `${file}.${backupId}`);
+    try {
+      const content = readFileSync(src);
+      atomicWriteSync(dest, content);
+      backedUp.push(file);
+    } catch {
+      // skip files that fail to copy
+    }
+  }
+
+  // Write metadata sidecar.
   const metaPath = join(backupDir, `${backupId}.meta.json`);
   try {
-    writeFileSync(
+    atomicWriteSync(
       metaPath,
       JSON.stringify(
         {
@@ -71,21 +236,56 @@ export function createBackup(
         null,
         2,
       ),
-      'utf-8',
     );
   } catch {
     // non-fatal
   }
 
-  return { backupId, path: backupDir, timestamp, type: btype, files: backedUp };
+  // Global-tier backup (nexus.db) — only when explicitly requested.
+  // @task T306 @epic T299
+  const globalResults: Record<string, string> = {};
+  if (opts?.includeGlobal) {
+    // Ensure nexus.db is initialized so its native handle is available.
+    try {
+      const { getNexusDb } = await import('../store/nexus-sqlite.js');
+      await getNexusDb();
+    } catch {
+      // nexus.db open failed — vacuumIntoGlobalBackup will return empty path
+    }
+    try {
+      const { vacuumIntoGlobalBackup } = await import('../store/sqlite-backup.js');
+      const nexusResult = await vacuumIntoGlobalBackup('nexus');
+      globalResults['nexus'] = nexusResult.snapshotPath;
+    } catch {
+      // non-fatal — global backup failure must not block project backup
+      globalResults['nexus'] = '';
+    }
+  }
+
+  const result: BackupResult = {
+    backupId,
+    path: backupDir,
+    timestamp,
+    type: btype,
+    files: backedUp,
+  };
+  if (opts?.includeGlobal) {
+    result.global = globalResults;
+  }
+  return result;
 }
 
 /** A single backup entry returned by listSystemBackups. */
 export interface BackupEntry {
+  /** Unique backup identifier (timestamped). */
   backupId: string;
+  /** Backup category (`snapshot`, `safety`, `migration`). */
   type: string;
+  /** ISO-8601 timestamp when the backup was created. */
   timestamp: string;
+  /** Optional human-readable note attached at creation time. */
   note?: string;
+  /** File names captured in this backup. */
   files: string[];
 }
 
@@ -131,7 +331,18 @@ export function listSystemBackups(projectRoot: string): BackupEntry[] {
   return entries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
 }
 
-/** Restore from a backup. */
+/**
+ * Restore a backup into the live `.cleo/` directory.
+ *
+ * This operation overwrites the in-place copies of the files recorded in
+ * the backup's sidecar. SQLite files are restored via a plain `copyFileSync`
+ * because restore runs BEFORE the next CLEO process opens the database — no
+ * WAL is active at that point — so a filesystem copy is safe. Callers must
+ * ensure no CLEO process is concurrently writing to the target database.
+ *
+ * JSON files are restored via `atomicWrite` (tmp-then-rename) so a crash
+ * mid-restore cannot produce a truncated config.
+ */
 export function restoreBackup(
   projectRoot: string,
   params: { backupId: string; force?: boolean },
@@ -168,14 +379,23 @@ export function restoreBackup(
   const restored: string[] = [];
   for (const file of meta.files ?? []) {
     const backupFile = join(backupDir, `${file}.${params.backupId}`);
-    if (existsSync(backupFile)) {
-      try {
+    if (!existsSync(backupFile)) continue;
+    const destPath = join(cleoDir, file);
+    try {
+      if (file.endsWith('.db')) {
+        // Atomic filesystem copy — target DB must not be in use (caller's
+        // responsibility). Raw copy is safe here because no VACUUM INTO is
+        // applicable (we are writing to the final location, not into a
+        // snapshot).
+        copyFileSync(backupFile, destPath);
+      } else {
+        // JSON via atomic tmp-then-rename.
         const content = readFileSync(backupFile);
-        writeFileSync(join(cleoDir, file), content);
-        restored.push(file);
-      } catch {
-        // skip files that fail to restore
+        atomicWriteSync(destPath, content);
       }
+      restored.push(file);
+    } catch {
+      // skip files that fail to restore
     }
   }
 

package/templates/cleo-gitignore

@@ -7,6 +7,18 @@
 #
 # Canonical audit: .cleo/agent-outputs/T5159-cleo-file-audit.md
 # ADR: ADR-013-data-integrity-checkpoint-architecture.md
+#
+# ADR-013 §9 (2026-04-07, T5158) — IMPORTANT:
+#   tasks.db / brain.db / config.json / project-info.json are NOT tracked
+#   in EITHER the project git repo OR the isolated .cleo/.git checkpoint
+#   repo. They are regenerated deterministically by `cleo init` and are
+#   backed up via VACUUM INTO snapshots (SQLite) + atomic copies (JSON)
+#   stored under .cleo/backups/. See the ADR for the full recovery story.
+#
+#   Because git treats nested .gitignore allow rules (`!foo`) as overriding
+#   parent-repo ignore rules, this file must NOT re-include those four
+#   files — doing so would unignore them at the project repository level
+#   and re-open the T5158 data-loss vector.
 # =============================================================================
 
 # Step 1: Ignore everything in .cleo/
@@ -19,10 +31,9 @@
 # Step 2: Allow this .gitignore itself
 !.gitignore
 
-# Step 3: Allow project configuration files
-!config.json
+# Step 3: Allow project configuration files that are SAFE to track
+# (detected project facts and bootstrap scripts — not runtime state).
 !project-context.json
-!project-info.json
 !setup-otel.sh
 !DATA-SAFETY-IMPLEMENTATION-SUMMARY.md
 
@@ -49,6 +60,11 @@
 *.db-wal
 *.db-journal
 
+# Runtime config snapshots — regenerated by `cleo init`, backed up via
+# `cleo backup add`. NEVER track (ADR-013 §9).
+config.json
+project-info.json
+
 # Logs — NEVER track (append-only runtime data)
 log.json
 tasks-log.jsonl