brainclaw 0.29.2 → 1.5.4

package/dist/core/upgrades/backup.js

@@ -0,0 +1,232 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { getInstalledBrainclawVersion } from '../brainclaw-version.js';
+export const BACKUP_DIR_PREFIX = '.brainclaw.bak-';
+export const BACKUP_MANIFEST_FILENAME = 'backup.json';
+export const ROLLBACK_PARKED_PREFIX = '.brainclaw.rollback-';
+export const ROLLBACK_STAGING_PREFIX = '.brainclaw.restoring-';
+export const BackupManifestSchema = z.object({
+    schema_version: z.literal(1),
+    created_at: z.string().datetime(),
+    source_path: z.string(),
+    brainclaw_version: z.string(),
+    store_schema_version: z.string().nullable(),
+    note: z.string().optional(),
+});
+export class BackupError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BackupError';
+    }
+}
+function isoTimestamp(d) {
+    return d.toISOString().replace(/[:.]/g, '-');
+}
+function parentOf(storePath) {
+    return path.dirname(storePath);
+}
+/**
+ * Atomically copy a `.brainclaw/` tree to a sibling backup directory.
+ * Copy happens into a `.partial-*` staging path first, then renamed
+ * into place so an interrupted copy never produces a backup that
+ * pretends to be complete.
+ */
+export function createBackup(options) {
+    const { storePath } = options;
+    if (!fs.existsSync(storePath)) {
+        throw new BackupError('source_missing', `Source store not found: ${storePath}`);
+    }
+    const stat = fs.statSync(storePath);
+    if (!stat.isDirectory()) {
+        throw new BackupError('source_not_dir', `Source is not a directory: ${storePath}`);
+    }
+    const now = (options.now ?? (() => new Date()))();
+    const stamp = isoTimestamp(now);
+    const parent = parentOf(storePath);
+    const finalPath = path.join(parent, `${BACKUP_DIR_PREFIX}${stamp}`);
+    const stagingPath = path.join(parent, `${BACKUP_DIR_PREFIX}${stamp}.partial-${process.pid}`);
+    if (fs.existsSync(finalPath)) {
+        throw new BackupError('backup_exists', `Backup already exists for this timestamp: ${finalPath}`);
+    }
+    if (fs.existsSync(stagingPath)) {
+        fs.rmSync(stagingPath, { recursive: true, force: true });
+    }
+    try {
+        fs.cpSync(storePath, stagingPath, { recursive: true, errorOnExist: false, force: true });
+    }
+    catch (error) {
+        try {
+            fs.rmSync(stagingPath, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+        throw new BackupError('copy_failed', `Backup copy failed: ${error.message}`);
+    }
+    const manifest = {
+        schema_version: 1,
+        created_at: now.toISOString(),
+        source_path: path.resolve(storePath),
+        brainclaw_version: getInstalledBrainclawVersion(),
+        store_schema_version: options.storeSchemaVersion ?? null,
+        note: options.note,
+    };
+    fs.writeFileSync(path.join(stagingPath, BACKUP_MANIFEST_FILENAME), JSON.stringify(manifest, null, 2), 'utf-8');
+    try {
+        fs.renameSync(stagingPath, finalPath);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(stagingPath, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+        throw new BackupError('rename_failed', `Could not finalise backup: ${error.message}`);
+    }
+    return { backupPath: finalPath, manifest };
+}
+/**
+ * List sibling backups for a given `.brainclaw/` path, newest first.
+ * Backups without a parseable manifest are skipped silently — callers
+ * that care can re-read the raw directory listing.
+ */
+export function listBackups(storePath) {
+    const parent = parentOf(storePath);
+    if (!fs.existsSync(parent))
+        return [];
+    const entries = fs.readdirSync(parent, { withFileTypes: true });
+    const backups = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (!entry.name.startsWith(BACKUP_DIR_PREFIX))
+            continue;
+        if (entry.name.includes('.partial-'))
+            continue;
+        const dir = path.join(parent, entry.name);
+        const manifest = readManifest(dir);
+        if (!manifest)
+            continue;
+        backups.push({ backupPath: dir, manifest });
+    }
+    backups.sort((a, b) => b.manifest.created_at.localeCompare(a.manifest.created_at));
+    return backups;
+}
+export function readManifest(backupPath) {
+    const manifestPath = path.join(backupPath, BACKUP_MANIFEST_FILENAME);
+    if (!fs.existsSync(manifestPath))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        return BackupManifestSchema.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function cleanupRestoreStaging(stagingPath) {
+    try {
+        fs.rmSync(stagingPath, { recursive: true, force: true });
+    }
+    catch {
+        // Best effort only.
+    }
+}
+/**
+ * Restore a backup by staging the new live contents into a sibling
+ * directory, then doing a single rename swap. Failure-atomic:
+ *
+ *   1. Copy backup → staging (slow phase, can be interrupted safely —
+ *      the live store is still untouched).
+ *   2. Strip the manifest from the staging dir (so the restored store
+ *      does not masquerade as a backup).
+ *   3. Park live → parked (atomic rename).
+ *   4. Swap staging → live (atomic rename).
+ *
+ * If step 4 fails after step 3, we un-park so the store is never left
+ * missing, and we wipe the staging dir to avoid orphans. If any step
+ * before 3 fails, the live store is unchanged.
+ */
+export function restoreBackup(options) {
+    const { storePath, backupPath } = options;
+    if (!fs.existsSync(backupPath)) {
+        throw new BackupError('backup_missing', `Backup not found: ${backupPath}`);
+    }
+    const manifest = readManifest(backupPath);
+    if (!manifest) {
+        throw new BackupError('manifest_invalid', `Backup has no readable manifest: ${backupPath}`);
+    }
+    if (options.acceptSchemaVersions && options.acceptSchemaVersions.length > 0) {
+        const stored = manifest.store_schema_version;
+        if (!stored || !options.acceptSchemaVersions.includes(stored)) {
+            throw new BackupError('schema_mismatch', `Backup schema ${stored ?? 'unknown'} is not in the accepted set [${options.acceptSchemaVersions.join(', ')}]`);
+        }
+    }
+    const now = (options.now ?? (() => new Date()))();
+    const stamp = isoTimestamp(now);
+    const parent = parentOf(storePath);
+    const stagingPath = path.join(parent, `${ROLLBACK_STAGING_PREFIX}${stamp}.pid-${process.pid}`);
+    const parkedPath = path.join(parent, `${ROLLBACK_PARKED_PREFIX}${stamp}`);
+    if (fs.existsSync(stagingPath)) {
+        fs.rmSync(stagingPath, { recursive: true, force: true });
+    }
+    // Step 1: populate staging. Live store untouched on failure.
+    try {
+        fs.cpSync(backupPath, stagingPath, { recursive: true, errorOnExist: true });
+    }
+    catch (error) {
+        try {
+            fs.rmSync(stagingPath, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+        throw new BackupError('restore_copy_failed', `Could not stage backup for restore: ${error.message}`);
+    }
+    // Step 2: remove manifest from the staged copy so the restored live
+    // store does not look like a backup.
+    const stagedManifest = path.join(stagingPath, BACKUP_MANIFEST_FILENAME);
+    if (fs.existsSync(stagedManifest)) {
+        try {
+            fs.unlinkSync(stagedManifest);
+        }
+        catch (error) {
+            cleanupRestoreStaging(stagingPath);
+            throw new BackupError('restore_manifest_strip_failed', `Could not strip backup manifest from staged restore: ${error.message}`);
+        }
+    }
+    // Step 3: park the current live store (if any). From here on we
+    // MUST end with a live store in place, either via swap or un-park.
+    let parked = false;
+    if (fs.existsSync(storePath)) {
+        try {
+            fs.renameSync(storePath, parkedPath);
+            parked = true;
+        }
+        catch (error) {
+            cleanupRestoreStaging(stagingPath);
+            throw new BackupError('park_failed', `Could not park live store: ${error.message}`);
+        }
+    }
+    // Step 4: swap staging → live. On failure, un-park so the store
+    // is never left missing; staging dir is cleaned.
+    try {
+        fs.renameSync(stagingPath, storePath);
+    }
+    catch (error) {
+        const swapMessage = error.message;
+        if (!parked) {
+            cleanupRestoreStaging(stagingPath);
+            throw new BackupError('restore_swap_failed', `Could not swap staging into live path: ${swapMessage}`);
+        }
+        try {
+            fs.renameSync(parkedPath, storePath);
+        }
+        catch (unparkError) {
+            throw new BackupError('restore_catastrophic', `Could not swap staging into live path: ${swapMessage}; also failed to restore parked live store: ${unparkError.message}. ` +
+                `Recovery paths preserved at parked=${parkedPath} staged=${stagingPath}`);
+        }
+        cleanupRestoreStaging(stagingPath);
+        throw new BackupError('restore_swap_failed', `Could not swap staging into live path: ${swapMessage}`);
+    }
+    return { parkedPath: parked ? parkedPath : '', restoredFrom: backupPath, manifest };
+}
+//# sourceMappingURL=backup.js.map

package/dist/core/upgrades/health-check.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { PROVENANCE_ENTITY_LAYOUTS } from './patches/provenance-rollout.js';
+import { PENDING_INBOX_SUBPATH } from './patches/candidate-archive.js';
+import { HANDOFFS_SUBPATH } from './patches/handoff-review-strip.js';
+import { V1_TARGET_SCHEMA_VERSION, readSchemaVersion, } from './schema-version.js';
+/**
+ * Post-migration health check — invoked via `brainclaw doctor --after-migration`.
+ * Verifies the four invariants that `brainclaw upgrade --to=1.0` is meant to
+ * leave behind:
+ *
+ *   1. Every memory record carries a `provenance` field (legacy or v1 kind).
+ *   2. No handoff still carries a `review` sub-object.
+ *   3. No stray candidate JSON files at the `coordination/inbox/` root
+ *      (pending candidates must have been archived).
+ *   4. `.brainclaw/schema-version.json` exists and `current == V1_TARGET_SCHEMA_VERSION`.
+ *
+ * Designed to be pure: no mutation, no side effects. Returns a structured
+ * report; the CLI decides exit code.
+ */
+const V1_PROVENANCE_KINDS = new Set([
+    'agent', 'auto_reflect', 'user', 'loop_artifact', 'federation', 'correction', 'legacy',
+]);
+export function runPostMigrationHealthCheck(options) {
+    const { storePath } = options;
+    const findings = [];
+    // ---- 1. provenance coverage ----
+    let recordsScanned = 0;
+    const missingProvenance = [];
+    for (const layout of PROVENANCE_ENTITY_LAYOUTS) {
+        const dir = path.join(storePath, layout.dir);
+        for (const file of listJsonFiles(dir, layout.recursive)) {
+            recordsScanned += 1;
+            let raw;
+            try {
+                raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            }
+            catch {
+                missingProvenance.push(relFromStore(storePath, file));
+                continue;
+            }
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+                missingProvenance.push(relFromStore(storePath, file));
+                continue;
+            }
+            const provenance = raw.provenance;
+            if (!isValidProvenance(provenance)) {
+                missingProvenance.push(relFromStore(storePath, file));
+            }
+        }
+    }
+    findings.push(missingProvenance.length === 0
+        ? { check: 'provenance', status: 'ok', message: `All ${recordsScanned} memory record(s) carry a valid provenance field.` }
+        : {
+            check: 'provenance',
+            status: 'error',
+            message: `${missingProvenance.length} of ${recordsScanned} memory record(s) are missing a valid provenance field.`,
+            details: { sample: missingProvenance.slice(0, 10), total: missingProvenance.length },
+        });
+    // ---- 2. handoff review sub-object ----
+    const handoffsDir = path.join(storePath, HANDOFFS_SUBPATH);
+    const handoffFiles = listJsonFiles(handoffsDir, false);
+    const handoffsWithReview = [];
+    for (const file of handoffFiles) {
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch {
+            continue; // malformed; handled by provenance check or migration test
+        }
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        if (raw.review !== undefined) {
+            handoffsWithReview.push(relFromStore(storePath, file));
+        }
+    }
+    findings.push(handoffsWithReview.length === 0
+        ? { check: 'handoff_review', status: 'ok', message: `No handoff carries a \`review\` sub-object (${handoffFiles.length} scanned).` }
+        : {
+            check: 'handoff_review',
+            status: 'error',
+            message: `${handoffsWithReview.length} handoff(s) still carry a \`review\` sub-object.`,
+            details: { sample: handoffsWithReview.slice(0, 10), total: handoffsWithReview.length },
+        });
+    // ---- 3. candidate archive — inbox/ root must be empty of JSON files ----
+    const inboxRoot = path.join(storePath, PENDING_INBOX_SUBPATH);
+    const pendingCandidates = [];
+    if (fs.existsSync(inboxRoot)) {
+        for (const entry of fs.readdirSync(inboxRoot, { withFileTypes: true })) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.json'))
+                continue;
+            pendingCandidates.push(entry.name);
+        }
+    }
+    findings.push(pendingCandidates.length === 0
+        ? { check: 'candidate_archive', status: 'ok', message: 'No pending candidates remain at coordination/inbox/ root.' }
+        : {
+            check: 'candidate_archive',
+            status: 'error',
+            message: `${pendingCandidates.length} pending candidate file(s) remain at the inbox root — candidate-archive patch did not complete.`,
+            details: { sample: pendingCandidates.slice(0, 10), total: pendingCandidates.length },
+        });
+    // ---- 4. schema version marker ----
+    const schemaState = readSchemaVersion(storePath);
+    if (!schemaState.present) {
+        findings.push({
+            check: 'schema_version',
+            status: 'error',
+            message: `schema-version.json is missing — upgrade did not reach the version-bump step.`,
+        });
+    }
+    else if (schemaState.current !== V1_TARGET_SCHEMA_VERSION) {
+        findings.push({
+            check: 'schema_version',
+            status: 'error',
+            message: `Store is at schema ${schemaState.current}, expected ${V1_TARGET_SCHEMA_VERSION}.`,
+        });
+    }
+    else {
+        findings.push({
+            check: 'schema_version',
+            status: 'ok',
+            message: `Store is at schema ${schemaState.current} (history: ${schemaState.history.length} transition(s)).`,
+        });
+    }
+    const ok = findings.every((f) => f.status === 'ok');
+    return {
+        ok,
+        store_path: storePath,
+        findings,
+        stats: {
+            records_scanned: recordsScanned,
+            records_missing_provenance: missingProvenance.length,
+            handoffs_with_review: handoffsWithReview.length,
+            pending_candidates_in_root: pendingCandidates.length,
+            current_schema_version: schemaState.present ? schemaState.current : null,
+            target_schema_version: V1_TARGET_SCHEMA_VERSION,
+        },
+    };
+}
+function isValidProvenance(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const kind = value.kind;
+    return typeof kind === 'string' && V1_PROVENANCE_KINDS.has(kind);
+}
+function listJsonFiles(dir, recursive) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isFile() && entry.name.endsWith('.json')) {
+            out.push(full);
+            continue;
+        }
+        if (recursive && entry.isDirectory()) {
+            out.push(...listJsonFiles(full, true));
+        }
+    }
+    return out;
+}
+function relFromStore(storePath, file) {
+    return path.relative(storePath, file).split(path.sep).join('/');
+}
+//# sourceMappingURL=health-check.js.map

package/dist/core/upgrades/patches/candidate-archive.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { CandidateSchema } from '../../schema.js';
+/**
+ * Candidate archive (P6.6) — v1.0 schema migration patch.
+ *
+ * Pending candidates accumulate because the review queue is rarely
+ * used as designed. v1.0 archives them out of the live inbox into
+ * `.brainclaw/archive/candidates/<YYYY-MM-DD>/` with a manifest
+ * listing what moved and why. Accepted and rejected candidates
+ * (already properly triaged) stay put.
+ *
+ * Live inbox path: `.brainclaw/coordination/inbox/`
+ * Archive path:    `.brainclaw/archive/candidates/<YYYY-MM-DD>/`
+ */
+export const PENDING_INBOX_SUBPATH = path.join('coordination', 'inbox');
+export const ARCHIVE_CANDIDATES_SUBPATH = path.join('archive', 'candidates');
+export const CANDIDATE_ARCHIVE_MANIFEST = 'manifest.json';
+export const CandidateArchiveEntrySchema = z.object({
+    id: z.string(),
+    short_label: z.string().nullable(),
+    type: z.string(),
+    status: z.string(),
+    created_at: z.string(),
+    original_path: z.string(),
+    archived_path: z.string(),
+    /** Present when the source candidate did not parse cleanly against the
+     *  current Zod schema. The file is still archived; the manifest records
+     *  the first Zod error so an operator can inspect the archive later. */
+    parse_error: z.string().optional(),
+});
+export const CandidateArchiveManifestSchema = z.object({
+    schema_version: z.literal(1),
+    archived_at: z.string().datetime(),
+    reason: z.string(),
+    count: z.number().int().nonnegative(),
+    entries: z.array(CandidateArchiveEntrySchema),
+});
+/**
+ * Archive pending candidates sitting directly in `coordination/inbox/`.
+ * Idempotent — re-running after a successful archive is a no-op.
+ */
+export function archivePendingCandidates(options) {
+    const pendingDir = path.join(options.storePath, PENDING_INBOX_SUBPATH);
+    const now = (options.now ?? (() => new Date()))();
+    const dateStamp = now.toISOString().slice(0, 10);
+    const archiveDir = path.join(options.storePath, ARCHIVE_CANDIDATES_SUBPATH, dateStamp);
+    const files = listPendingCandidateFiles(pendingDir);
+    if (files.length === 0) {
+        return {
+            status: 'noop',
+            pendingDir,
+            archiveDir: null,
+            moved: [],
+            manifestPath: null,
+        };
+    }
+    const reason = options.reason ?? 'v1.0 schema migration (P6.6): pending candidate review queue retired';
+    const entries = [];
+    // First pass: parse + plan. Candidates that do not pass the current Zod
+    // schema are still archived — they may be legacy shapes (e.g. status
+    // "proposed" from an older enum). We capture the parse failure in the
+    // manifest so the archive is self-describing.
+    const planned = [];
+    for (const file of files) {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new Error(`candidate-archive: ${file} is not a JSON object`);
+        }
+        const rawObj = raw;
+        const parsed = CandidateSchema.safeParse(rawObj);
+        planned.push({
+            source: file,
+            target: path.join(archiveDir, path.basename(file)),
+            raw: rawObj,
+            candidate: parsed.success ? parsed.data : null,
+            parseError: parsed.success ? null : parsed.error.issues[0]?.message ?? 'zod parse failed',
+            baseName: path.basename(file),
+        });
+    }
+    if (options.dryRun) {
+        for (const p of planned) {
+            entries.push(makeEntry(p.candidate, p.raw, p.source, p.target, options.storePath, p.parseError));
+        }
+        return {
+            status: 'planned',
+            pendingDir,
+            archiveDir,
+            moved: entries,
+            manifestPath: path.join(archiveDir, CANDIDATE_ARCHIVE_MANIFEST),
+        };
+    }
+    fs.mkdirSync(archiveDir, { recursive: true });
+    for (const p of planned) {
+        fs.renameSync(p.source, p.target);
+        entries.push(makeEntry(p.candidate, p.raw, p.source, p.target, options.storePath, p.parseError));
+    }
+    const manifest = {
+        schema_version: 1,
+        archived_at: now.toISOString(),
+        reason,
+        count: entries.length,
+        entries,
+    };
+    const manifestPath = path.join(archiveDir, CANDIDATE_ARCHIVE_MANIFEST);
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
+    return {
+        status: 'archived',
+        pendingDir,
+        archiveDir,
+        moved: entries,
+        manifestPath,
+    };
+}
+function listPendingCandidateFiles(pendingDir) {
+    if (!fs.existsSync(pendingDir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(pendingDir, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.json'))
+            continue;
+        out.push(path.join(pendingDir, entry.name));
+    }
+    return out;
+}
+function makeEntry(candidate, raw, sourcePath, archivedPath, storePath, parseError) {
+    const fallback = (key, dflt) => {
+        const v = raw[key];
+        return typeof v === 'string' ? v : dflt;
+    };
+    return {
+        id: candidate?.id ?? fallback('id', path.basename(sourcePath, '.json')),
+        short_label: candidate?.short_label ?? (typeof raw.short_label === 'string' ? raw.short_label : null),
+        type: candidate?.type ?? fallback('type', 'unknown'),
+        status: candidate?.status ?? fallback('status', 'unknown'),
+        created_at: candidate?.created_at ?? fallback('created_at', '1970-01-01T00:00:00.000Z'),
+        original_path: path.relative(storePath, sourcePath).split(path.sep).join('/'),
+        archived_path: path.relative(storePath, archivedPath).split(path.sep).join('/'),
+        ...(parseError ? { parse_error: parseError } : {}),
+    };
+}
+//# sourceMappingURL=candidate-archive.js.map

package/dist/core/upgrades/patches/handoff-review-strip.js

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+/**
+ * Handoff review-strip (P6.1 groundwork) — v1.0 schema migration patch.
+ *
+ * Existing handoffs may carry a `review` sub-object (requester,
+ * reviewer, verdict, blocking_issues, …). The v1.0 model drops the
+ * review sub-flow entirely: handoffs become immutable session-end
+ * artefacts and corrections use the tombstone pattern (P6.1) via
+ * `bclaw_correct_handoff` (to land in Phase 3, slice 3e).
+ *
+ * This patch removes the `review` field from every handoff file that
+ * still carries one, writes a log listing what was stripped, and is
+ * idempotent.
+ *
+ * Implementation note: handoffs are read/written as raw JSON instead
+ * of parsed through Zod. Round-tripping Zod would drop any field not
+ * declared in the schema (e.g., fields added by a future branch).
+ * The patch's contract is "strip `review`, touch nothing else".
+ */
+export const HANDOFFS_SUBPATH = path.join('coordination', 'handoffs');
+export const MIGRATIONS_ARCHIVE_SUBPATH = path.join('archive', 'migrations');
+export const HANDOFF_REVIEW_STRIP_LOG = 'handoff-review-strip.json';
+export const HandoffReviewStripEntrySchema = z.object({
+    handoff_id: z.string(),
+    short_label: z.string().nullable(),
+    handoff_path: z.string(),
+    review_fields: z.array(z.string()),
+    stripped_at: z.string().datetime(),
+});
+export const HandoffReviewStripLogSchema = z.object({
+    schema_version: z.literal(1),
+    stripped_at: z.string().datetime(),
+    reason: z.string(),
+    count: z.number().int().nonnegative(),
+    entries: z.array(HandoffReviewStripEntrySchema),
+});
+/**
+ * Strip the `review` sub-object from every handoff file that still
+ * carries one. Handoffs without `review` are scanned but not
+ * rewritten. Idempotent.
+ */
+export function stripHandoffReview(options) {
+    const { storePath } = options;
+    const handoffsDir = path.join(storePath, HANDOFFS_SUBPATH);
+    const now = (options.now ?? (() => new Date()))();
+    const dateStamp = now.toISOString().slice(0, 10);
+    const logDir = path.join(storePath, MIGRATIONS_ARCHIVE_SUBPATH, dateStamp);
+    const logPath = path.join(logDir, HANDOFF_REVIEW_STRIP_LOG);
+    const reason = options.reason ?? 'v1.0 schema migration (P6.1 groundwork): handoffs become immutable, corrections use tombstones';
+    const files = listHandoffFiles(handoffsDir);
+    const stripped = [];
+    for (const file of files) {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new Error(`handoff-review-strip: ${file} is not a JSON object`);
+        }
+        const obj = raw;
+        const review = obj.review;
+        if (review === undefined)
+            continue;
+        const reviewFields = review && typeof review === 'object' && !Array.isArray(review)
+            ? Object.keys(review)
+            : [];
+        const entry = {
+            handoff_id: typeof obj.id === 'string' ? obj.id : path.basename(file, '.json'),
+            short_label: typeof obj.short_label === 'string' ? obj.short_label : null,
+            handoff_path: path.relative(storePath, file).split(path.sep).join('/'),
+            review_fields: reviewFields,
+            stripped_at: now.toISOString(),
+        };
+        stripped.push(entry);
+        if (!options.dryRun) {
+            const next = { ...obj };
+            delete next.review;
+            fs.writeFileSync(file, JSON.stringify(next, null, 2), 'utf-8');
+        }
+    }
+    if (stripped.length === 0) {
+        return {
+            status: 'noop',
+            handoffsDir,
+            logPath: null,
+            stripped: [],
+            scanned: files.length,
+        };
+    }
+    if (options.dryRun) {
+        return {
+            status: 'planned',
+            handoffsDir,
+            logPath,
+            stripped,
+            scanned: files.length,
+        };
+    }
+    fs.mkdirSync(logDir, { recursive: true });
+    const log = {
+        schema_version: 1,
+        stripped_at: now.toISOString(),
+        reason,
+        count: stripped.length,
+        entries: stripped,
+    };
+    fs.writeFileSync(logPath, JSON.stringify(log, null, 2), 'utf-8');
+    return {
+        status: 'stripped',
+        handoffsDir,
+        logPath,
+        stripped,
+        scanned: files.length,
+    };
+}
+function listHandoffFiles(handoffsDir) {
+    if (!fs.existsSync(handoffsDir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(handoffsDir, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.json'))
+            continue;
+        out.push(path.join(handoffsDir, entry.name));
+    }
+    return out;
+}
+//# sourceMappingURL=handoff-review-strip.js.map