@paths.design/caws-cli 11.1.7 → 11.1.8

package/dist/store/specs-writer.js

@@ -6,6 +6,7 @@
 // operations:
 //
 //   createSpec  — write a new .caws/specs/<id>.yaml (active) + spec_created
+//   activateSpec — raw-byte patch lifecycle_state draft→active + spec_activated
 //   closeSpec   — raw-byte patch lifecycle_state/resolution/closure_notes
 //                  /updated_at on existing spec + spec_closed
 //   archiveSpec — move .caws/specs/<id>.yaml → .caws/specs/.archive/<id>.yaml,
@@ -57,25 +58,50 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSpec = createSpec;
+exports.activateSpec = activateSpec;
 exports.closeSpec = closeSpec;
 exports.archiveSpec = archiveSpec;
+exports.retireDraftSpec = retireDraftSpec;
 exports.listSpecs = listSpecs;
 exports.showSpec = showSpec;
+exports.recoverArchivedSpec = recoverArchivedSpec;
+exports.pruneArchive = pruneArchive;
+const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const caws_kernel_1 = require("@paths.design/caws-kernel");
 const events_store_1 = require("./events-store");
+const specs_store_1 = require("./specs-store");
+const git_autocommit_1 = require("./git-autocommit");
 const lifecycle_transaction_1 = require("./lifecycle-transaction");
 const lifecycle_lock_1 = require("./lifecycle-lock");
 const repo_root_1 = require("./repo-root");
 const rules_1 = require("./rules");
-const specs_store_1 = require("./specs-store");
 const yaml_patch_1 = require("./yaml-patch");
 const yaml_store_1 = require("./yaml-store");
 // ─── Path helpers ────────────────────────────────────────────────────────
 function specPath(cawsDir, id) {
     return path.join(cawsDir, 'specs', `${id}.yaml`);
 }
+function repoRootFromCawsDir(cawsDir) {
+    return path.dirname(cawsDir);
+}
+function specRelPath(cawsDir, id, repoRoot) {
+    return path.relative(repoRoot, specPath(cawsDir, id));
+}
+function hasComplexTopLevelValue(source, key) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = source.match(new RegExp(`^${escapedKey}:(.*)$`, 'm'));
+    if (match === null)
+        return false;
+    const rest = (match[1] ?? '').trim();
+    return (rest === '' ||
+        rest.startsWith('#') ||
+        rest.startsWith('|') ||
+        rest.startsWith('>') ||
+        rest.startsWith('{') ||
+        rest.startsWith('['));
+}
 function archivedSpecPath(cawsDir, id) {
     return path.join(cawsDir, 'specs', '.archive', `${id}.yaml`);
 }
@@ -89,6 +115,139 @@ function findSpecPath(cawsDir, id) {
         return archived;
     return null;
 }
+/**
+ * TOMBSTONE-SHELL-TEST-RECONCILIATION-001: detect whether a spec id
+ * has been archived via the tombstone path (spec_archived event in
+ * the event log). CAWS-ARCHIVE-AS-TOMBSTONE-001 removed the
+ * `.caws/specs/.archive/<id>.yaml` body write; the spec_archived
+ * event is now the authoritative archive signal.
+ *
+ * Cold-path predicate used only when both `specs/<id>.yaml` AND
+ * `specs/.archive/<id>.yaml` are absent. Scans the event log
+ * sequentially for a matching `spec_archived` event. Returns true on
+ * any match. Returns false if the event log is unreadable or empty
+ * (no events means no archive can have happened in this repo).
+ *
+ * CAWS-SPECS-ARCHIVE-COLLISION-REFUSAL-001: this predicate is now
+ * enforcement-grade, not diagnostic-only. createSpec consults it to
+ * refuse re-creation of an archived id (tombstone identity). closeSpec
+ * still uses it to choose between "archived; cannot close" vs
+ * "not found" diagnostics. recover/show/list continue to depend on
+ * the event log directly for archived-body retrieval.
+ */
+function isArchivedViaTombstone(cawsDir, id) {
+    const result = (0, events_store_1.loadEvents)(cawsDir);
+    if (!result.ok)
+        return false;
+    for (const event of result.value.events) {
+        const body = event;
+        if (body.event === 'spec_archived' && body.spec_id === id) {
+            return true;
+        }
+    }
+    return false;
+}
+// ─── Git query helpers (CAWS-ARCHIVE-AS-TOMBSTONE-001) ─────────────────
+//
+// archiveSpec needs to capture the spec yaml's blob_sha + optional
+// source_commit_sha BEFORE removing the file. These helpers wrap
+// execFileSync with the CAWS shell discipline (array args, never raw
+// shell strings) and return null on failure rather than throwing.
+// Failure-tolerant by design: a missing blob means "not in HEAD," not
+// "system is broken."
+function runGitQuery(args, repoRoot, opts = {}) {
+    const trim = opts.trim !== false; // default true
+    try {
+        const output = (0, child_process_1.execFileSync)('git', [...args], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).toString();
+        return trim ? output.trim() : output;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Return the git blob_sha of a path at HEAD, or null if the path is
+ * not tracked at HEAD. Output is a 40-hex string when present.
+ *
+ * The blob_sha is content-addressed and topology-independent: once
+ * recorded in a spec_archived event, `git show <blob_sha>` recovers
+ * the body regardless of subsequent commit graph rewrites.
+ */
+function gitBlobShaAtHead(repoRoot, relPath) {
+    const output = runGitQuery(['ls-tree', 'HEAD', '--', relPath], repoRoot);
+    if (output === null || output.length === 0)
+        return null;
+    // Output shape: "<mode> <type> <sha>\t<path>"
+    const parts = output.split(/\s+/);
+    if (parts.length < 3)
+        return null;
+    const sha = parts[2];
+    return /^[0-9a-f]{40}$/.test(sha ?? '') ? sha : null;
+}
+/**
+ * Return the sha of the commit that last modified the given path, or
+ * null if no such commit exists (file never tracked). Recorded for
+ * human audit on spec_archived events; NOT used by recover.
+ */
+function gitLastCommitForPath(repoRoot, relPath) {
+    const output = runGitQuery(['log', '-1', '--format=%H', '--', relPath], repoRoot);
+    if (output === null || output.length === 0)
+        return null;
+    return /^[0-9a-f]{40}$/.test(output) ? output : null;
+}
+// ─── Auto-commit helper (CAWS-SPECS-WRITER-AUTOCOMMIT-001) ──────────────
+//
+// Every successful spec-writer lifecycle transaction commits its yaml
+// change as the final step. Parity with worktrees-writer's
+// autoCommitTransition (worktrees-writer.ts:209). The shared
+// git-autocommit utility handles the three observable states
+// (committed / refused_dirty / skipped_no_git); this helper computes
+// the right inputs and never throws.
+//
+// Pre-write dirty state must be captured by the CALLER, before any
+// writer mutation lands. The utility cannot rederive it after the
+// fact.
+//
+// Root cause this addresses (observed 2026-05-27 during
+// CAWS-WORKTREE-DESTROY-SESSION-RESOLUTION-001 close): without this
+// autocommit, `caws specs close` leaves the spec yaml dirty in the
+// working tree, which then causes a subsequent
+// `caws worktree destroy` to refuse its own audit commit because
+// the dirty spec yaml fails its capturePreWriteState check.
+function autoCommitSpecWrite(cawsDir, specId, action, wasDirtyBeforeWrite, extraPaths = []) {
+    const repoRoot = repoRootFromCawsDir(cawsDir);
+    const primaryPath = specRelPath(cawsDir, specId, repoRoot);
+    const paths = [primaryPath, ...extraPaths];
+    const message = `chore(caws): ${action} ${specId}`;
+    return (0, git_autocommit_1.autoCommit)({
+        repoRoot,
+        paths,
+        message,
+        wasDirtyBeforeWrite,
+    });
+}
+/**
+ * Wrap a Result<SpecWriterOutcome> with an autoCommit attempt, mirroring
+ * the worktrees-writer post-transaction commit pattern. Only attaches
+ * data.audit_commit when the inner outcome is `kind: 'success'`.
+ * Partial failure or err results pass through unchanged — there is
+ * nothing valid to commit when the transaction rolled back.
+ */
+function attachAutoCommit(outcome, cawsDir, specId, action, wasDirtyBeforeWrite, extraPaths = []) {
+    if (!(0, caws_kernel_1.isOk)(outcome))
+        return outcome;
+    if (outcome.value.kind !== 'success')
+        return outcome;
+    const audit = autoCommitSpecWrite(cawsDir, specId, action, wasDirtyBeforeWrite, extraPaths);
+    return (0, caws_kernel_1.ok)({
+        ...outcome.value,
+        data: { audit_commit: audit },
+    });
+}
 // ─── ID validation (mirrors kernel regex) ────────────────────────────────
 const SPEC_ID_PATTERN = /^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\d+[a-z]*$/;
 function validateSpecId(id) {
@@ -148,6 +307,18 @@ function createSpec(cawsDir, input) {
     if (existing !== null) {
         return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" already exists at ${existing}.`, { subject: input.id, data: { existing_path: existing } }));
     }
+    // CAWS-SPECS-ARCHIVE-COLLISION-REFUSAL-001: tombstone identity.
+    // findSpecPath above checks both active and pre-tombstone archive
+    // locations on disk. Post-CAWS-ARCHIVE-AS-TOMBSTONE-001 the active
+    // file is deleted and no archive body is written, so an
+    // archived-then-erased spec leaves no on-disk trace; only the
+    // spec_archived event remains. Without this second check, a
+    // re-created spec would silently reuse a tombstoned id, breaking
+    // the audit narrative on .caws/events.jsonl (recover/show by id
+    // would become ambiguous between archived and current bodies).
+    if (isArchivedViaTombstone(cawsDir, input.id)) {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" has a prior spec_archived event in .caws/events.jsonl; archived spec ids are tombstoned identities and cannot be re-created. Use \`caws specs recover ${input.id}\` to retrieve the archived body, or choose a different id.`, { subject: input.id, data: { reason: 'archived_tombstone' } }));
+    }
     const targetPath = specPath(cawsDir, input.id);
     const newBytes = renderInitialSpecYaml(input);
     // Validate the planned YAML through the kernel BEFORE we write or
@@ -172,6 +343,16 @@ function createSpec(cawsDir, input) {
             lifecycle_state: input.initialState ?? 'active',
         },
     };
+    // CAWS-SPECS-WRITER-AUTOCOMMIT-001: capture pre-write dirty state
+    // BEFORE the transaction runs. For createSpec on a fresh id, the
+    // target path does not yet exist, so isPathDirty returns false —
+    // the autocommit will succeed cleanly. We still call it because
+    // (a) a stale conflict marker or hand-authored draft at the target
+    // path could exist (we already refused that case above via
+    // findSpecPath, but defense-in-depth), and (b) the contract is
+    // that callers always observe data.audit_commit on success.
+    const repoRoot = repoRootFromCawsDir(cawsDir);
+    const wasDirtyBeforeWrite = (0, git_autocommit_1.isPathDirty)(repoRoot, specRelPath(cawsDir, input.id, repoRoot));
     const txnResult = (0, lifecycle_lock_1.withLifecycleLock)(cawsDir, () => (0, lifecycle_transaction_1.runLifecycleTransaction)({
         cawsDir,
         plannedWrites: [{ path: targetPath, contents: newBytes }],
@@ -180,7 +361,87 @@ function createSpec(cawsDir, input) {
     if (!txnResult.ok) {
         return (0, caws_kernel_1.err)(txnResult.errors);
     }
-    return mapTxnToOutcome(txnResult.value, input.id, targetPath);
+    const outcome = mapTxnToOutcome(txnResult.value, input.id, targetPath);
+    return attachAutoCommit(outcome, cawsDir, input.id, 'create', wasDirtyBeforeWrite);
+}
+// ─── activateSpec ────────────────────────────────────────────────────────
+function activateSpec(cawsDir, input) {
+    const idValidation = validateSpecId(input.id);
+    if (!idValidation.ok)
+        return idValidation;
+    const targetPath = specPath(cawsDir, input.id);
+    if (!fs.existsSync(targetPath)) {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" not found at ${targetPath}.`, { subject: input.id }));
+    }
+    const sourceResult = (0, yaml_store_1.readYamlSource)(targetPath);
+    if (!(0, caws_kernel_1.isOk)(sourceResult))
+        return (0, caws_kernel_1.err)(sourceResult.errors);
+    const originalBytes = sourceResult.value;
+    const parsed = (0, caws_kernel_1.parseAndValidateSpec)(originalBytes);
+    if (!(0, caws_kernel_1.isOk)(parsed)) {
+        return (0, caws_kernel_1.err)(parsed.errors.map((d) => (0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, d.message, {
+            subject: d.subject ?? input.id,
+            data: { source_rule: d.rule },
+        })));
+    }
+    const spec = parsed.value;
+    if (spec.lifecycle_state !== 'draft') {
+        const alternative = spec.lifecycle_state === 'active'
+            ? `Spec "${input.id}" is already active.`
+            : spec.lifecycle_state === 'closed'
+                ? `Use \`caws specs archive ${input.id}\` to archive a closed spec.`
+                : `Archived specs cannot be activated. Use \`caws specs recover ${input.id}\` to inspect the archived body.`;
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" is in lifecycle_state "${spec.lifecycle_state}"; activate only activates drafts. ${alternative}`, { subject: input.id, data: { current_state: spec.lifecycle_state } }));
+    }
+    const now = (input.now ?? (() => new Date()))().toISOString();
+    let patched = originalBytes;
+    const step1 = (0, yaml_patch_1.setTopLevelScalar)(patched, 'lifecycle_state', 'active');
+    if (!step1.ok)
+        return (0, caws_kernel_1.err)(step1.errors);
+    patched = step1.value;
+    const hasUpdatedAt = /^updated_at:/m.test(patched);
+    if (hasUpdatedAt) {
+        const step2 = (0, yaml_patch_1.setTopLevelScalar)(patched, 'updated_at', `'${now}'`);
+        if (!step2.ok)
+            return (0, caws_kernel_1.err)(step2.errors);
+        patched = step2.value;
+    }
+    else {
+        const anchor = /^created_at:/m.test(patched) ? 'created_at' : 'lifecycle_state';
+        const step2 = (0, yaml_patch_1.insertTopLevelScalarAfter)(patched, anchor, 'updated_at', `'${now}'`);
+        if (!step2.ok)
+            return (0, caws_kernel_1.err)(step2.errors);
+        patched = step2.value;
+    }
+    const reparsed = (0, caws_kernel_1.parseAndValidateSpec)(patched);
+    if (!(0, caws_kernel_1.isOk)(reparsed)) {
+        return (0, caws_kernel_1.err)(reparsed.errors.map((d) => (0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, d.message, {
+            subject: d.subject ?? input.id,
+            data: { source_rule: d.rule, hint: 'planned-bytes validation failed' },
+        })));
+    }
+    const event = {
+        event: 'spec_activated',
+        ts: now,
+        actor: input.actor,
+        spec_id: input.id,
+        data: {
+            previous_lifecycle_state: 'draft',
+            lifecycle_state: 'active',
+        },
+    };
+    const repoRoot = repoRootFromCawsDir(cawsDir);
+    const wasDirtyBeforeWrite = (0, git_autocommit_1.isPathDirty)(repoRoot, specRelPath(cawsDir, input.id, repoRoot));
+    const txnResult = (0, lifecycle_lock_1.withLifecycleLock)(cawsDir, () => (0, lifecycle_transaction_1.runLifecycleTransaction)({
+        cawsDir,
+        plannedWrites: [{ path: targetPath, contents: patched }],
+        events: [event],
+    }));
+    if (!txnResult.ok) {
+        return (0, caws_kernel_1.err)(txnResult.errors);
+    }
+    const outcome = mapTxnToOutcome(txnResult.value, input.id, targetPath);
+    return attachAutoCommit(outcome, cawsDir, input.id, 'activate', wasDirtyBeforeWrite);
 }
 // ─── closeSpec ───────────────────────────────────────────────────────────
 function closeSpec(cawsDir, input) {
@@ -189,10 +450,22 @@ function closeSpec(cawsDir, input) {
         return idValidation;
     const targetPath = specPath(cawsDir, input.id);
     if (!fs.existsSync(targetPath)) {
-        // Check archive too — if it's already archived, this is a different
-        // kind of error than "not found."
+        // TOMBSTONE-SHELL-TEST-RECONCILIATION-001: archived-id detection
+        // moved from `.caws/specs/.archive/<id>.yaml` file existence to
+        // the event log. CAWS-ARCHIVE-AS-TOMBSTONE-001 made archive a
+        // deletion + spec_archived event (no body written under .archive/),
+        // so the legacy file check always returned false post-tombstone
+        // and the diagnostic fell through to generic "not found at <path>".
+        //
+        // The legacy check is preserved as a first pass (pre-tombstone
+        // archives may still exist as on-disk bodies; legitimate
+        // backward-compat). If the legacy file is absent, scan the event
+        // log for a `spec_archived` event matching this id — the
+        // authoritative tombstone signal. The scan is O(events) and only
+        // happens on the cold path (active file absent), not on every
+        // close.
         const archived = archivedSpecPath(cawsDir, input.id);
-        if (fs.existsSync(archived)) {
+        if (fs.existsSync(archived) || isArchivedViaTombstone(cawsDir, input.id)) {
             return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" is archived; cannot close (legal transitions: active → closed → archived).`, { subject: input.id }));
         }
         return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" not found at ${targetPath}.`, { subject: input.id }));
@@ -243,10 +516,12 @@ function closeSpec(cawsDir, input) {
         const escaped = `'${input.reason.replace(/'/g, "''")}'`;
         const hasNotes = /^closure_notes:/m.test(patched);
         if (hasNotes) {
-            const step3 = (0, yaml_patch_1.setTopLevelScalar)(patched, 'closure_notes', escaped);
-            if (!step3.ok)
-                return (0, caws_kernel_1.err)(step3.errors);
-            patched = step3.value;
+            if (!hasComplexTopLevelValue(patched, 'closure_notes')) {
+                const step3 = (0, yaml_patch_1.setTopLevelScalar)(patched, 'closure_notes', escaped);
+                if (!step3.ok)
+                    return (0, caws_kernel_1.err)(step3.errors);
+                patched = step3.value;
+            }
         }
         else {
             const step3 = (0, yaml_patch_1.insertTopLevelScalarAfter)(patched, 'resolution', 'closure_notes', escaped);
@@ -255,10 +530,35 @@ function closeSpec(cawsDir, input) {
             patched = step3.value;
         }
     }
-    const step4 = (0, yaml_patch_1.setTopLevelScalar)(patched, 'updated_at', `'${now}'`);
-    if (!step4.ok)
-        return (0, caws_kernel_1.err)(step4.errors);
-    patched = step4.value;
+    // CAWS-MERGE-CLOSE-MISSING-UPDATED-AT-001: insert-or-update fallback
+    // for updated_at. Legacy / v10-migrated / hand-authored specs may lack
+    // this optional field (it's not in spec.v1.json required[]). Without
+    // the fallback, setTopLevelScalar returns YAML_PATCH_KEY_NOT_FOUND
+    // here and the close transaction rolls back; the composed
+    // mergeWorktree → closeSpec path then reports
+    // partial_failure_unrecovered with the underlying patch-key error
+    // buried in close_errors. Mirror the has*-check +
+    // insertTopLevelScalarAfter pattern used for resolution and
+    // closure_notes above. Inline rather than extracted to a helper per
+    // the spec's out-of-scope note (the parallel pattern is intentional;
+    // helper extraction is a hygiene concern, not a closure blocker).
+    const hasUpdatedAt = /^updated_at:/m.test(patched);
+    if (hasUpdatedAt) {
+        const step4 = (0, yaml_patch_1.setTopLevelScalar)(patched, 'updated_at', `'${now}'`);
+        if (!step4.ok)
+            return (0, caws_kernel_1.err)(step4.errors);
+        patched = step4.value;
+    }
+    else {
+        // Anchor preference: after created_at (natural timestamp pairing)
+        // when present, otherwise after lifecycle_state. createSpec always
+        // writes created_at so this fallback fires only for legacy specs.
+        const anchor = /^created_at:/m.test(patched) ? 'created_at' : 'lifecycle_state';
+        const step4 = (0, yaml_patch_1.insertTopLevelScalarAfter)(patched, anchor, 'updated_at', `'${now}'`);
+        if (!step4.ok)
+            return (0, caws_kernel_1.err)(step4.errors);
+        patched = step4.value;
+    }
     // Step 5 (WORKTREE-MERGE-CLEARS-SPEC-BINDING-001):
     // Clear any top-level `worktree:` binding. A closed spec cannot have
     // a live worktree binding by definition; leaving the field is what
@@ -303,6 +603,15 @@ function closeSpec(cawsDir, input) {
         spec_id: input.id,
         data: eventData,
     };
+    // CAWS-SPECS-WRITER-AUTOCOMMIT-001: capture pre-write dirty state
+    // BEFORE the transaction. closeSpec patches an existing yaml, so
+    // the path almost always pre-exists; dirty means the user
+    // hand-edited it before the close call. autoCommit refuses to
+    // overwrite uncommitted user work (data.audit_commit.kind ===
+    // 'refused_dirty'); the close itself still applies to the working
+    // tree.
+    const repoRoot = repoRootFromCawsDir(cawsDir);
+    const wasDirtyBeforeWrite = (0, git_autocommit_1.isPathDirty)(repoRoot, specRelPath(cawsDir, input.id, repoRoot));
     const txnResult = (0, lifecycle_lock_1.withLifecycleLock)(cawsDir, () => (0, lifecycle_transaction_1.runLifecycleTransaction)({
         cawsDir,
         plannedWrites: [{ path: targetPath, contents: patched }],
@@ -311,7 +620,8 @@ function closeSpec(cawsDir, input) {
     if (!txnResult.ok) {
         return (0, caws_kernel_1.err)(txnResult.errors);
     }
-    return mapTxnToOutcome(txnResult.value, input.id, targetPath);
+    const outcome = mapTxnToOutcome(txnResult.value, input.id, targetPath);
+    return attachAutoCommit(outcome, cawsDir, input.id, 'close', wasDirtyBeforeWrite);
 }
 // ─── archiveSpec ─────────────────────────────────────────────────────────
 function archiveSpec(cawsDir, input) {
@@ -343,67 +653,84 @@ function archiveSpec(cawsDir, input) {
         return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" is in lifecycle_state "${spec.lifecycle_state}"; only closed specs can be archived.`, { subject: input.id, data: { current_state: spec.lifecycle_state } }));
     }
     const now = (input.now ?? (() => new Date()))().toISOString();
-    const toPath = archivedSpecPath(cawsDir, input.id);
-    // Patch lifecycle_state → archived and bump updated_at on a copy.
-    let patched = originalBytes;
-    const s1 = (0, yaml_patch_1.setTopLevelScalar)(patched, 'lifecycle_state', 'archived');
-    if (!s1.ok)
-        return (0, caws_kernel_1.err)(s1.errors);
-    patched = s1.value;
-    const s2 = (0, yaml_patch_1.setTopLevelScalar)(patched, 'updated_at', `'${now}'`);
-    if (!s2.ok)
-        return (0, caws_kernel_1.err)(s2.errors);
-    patched = s2.value;
-    // Validate.
-    const reparsed = (0, caws_kernel_1.parseAndValidateSpec)(patched);
-    if (!(0, caws_kernel_1.isOk)(reparsed)) {
-        return (0, caws_kernel_1.err)(reparsed.errors.map((d) => (0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, d.message, {
-            subject: d.subject ?? input.id,
-            data: { source_rule: d.rule, hint: 'planned-bytes validation failed' },
-        })));
+    // CAWS-ARCHIVE-AS-TOMBSTONE-001 invariant: archive does NOT write
+    // a body to .caws/specs/.archive/<id>.yaml. The body is recoverable
+    // via git history; the only on-disk mutation is the deletion of the
+    // active path.
+    //
+    // Step ordering (locked inside the lifecycle txn):
+    //   1. Capture blob_sha + source_commit_sha BEFORE any mutation
+    //      (so even if the txn fails, no state has been written).
+    //   2. unlink fromPath inside the txn's plannedWrites (modelled as
+    //      a delete via the new lifecycle-transaction shape, OR
+    //      executed inside the txn callback for v1).
+    //   3. Append the spec_archived event carrying blob_sha (new
+    //      tombstone shape) — NOT to_path.
+    //   4. Post-txn, autoCommit stages the deletion via `git add` (which
+    //      stages deletions when the file is gone).
+    //
+    // v1 ordering note: lifecycle-transaction.plannedWrites expects
+    // {path, contents} pairs (creates/overwrites). It does not model
+    // deletions natively. For v1 we execute the unlink inside the
+    // txn callback AFTER the event write succeeds; if the unlink
+    // fails post-event, we surface partial_failure_unrecovered
+    // (same shape as the legacy code did).
+    //
+    // void input.reason: archive accepts --reason for parity with
+    // close but the spec_archived schema does not carry it.
+    //
+    // CAWS-MERGE-CLOSE-MISSING-UPDATED-AT-001 reconciliation: the
+    // archiveSpec absent-`updated_at` patch from this slice was
+    // superseded by CAWS-ARCHIVE-AS-TOMBSTONE-001 (merge 2a4cc30).
+    // Tombstone eliminates archiveSpec's YAML patch step entirely —
+    // there is no `updated_at` to insert into a body that no longer
+    // gets written. The closeSpec absent-`updated_at` fix at line ~540
+    // remains in force; the archiveSpec branch is now dead code in
+    // tombstone-world and has been removed from this slice on merge.
+    const repoRoot = repoRootFromCawsDir(cawsDir);
+    const fromRel = path.relative(repoRoot, fromPath);
+    // Capture BEFORE any mutation. blob_sha is the authoritative
+    // recovery target. source_commit_sha is optional human audit.
+    const blobSha = gitBlobShaAtHead(repoRoot, fromRel);
+    if (blobSha === null) {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" is not tracked at HEAD. Cannot archive: blob_sha is the authoritative recovery target, and without it the archive event would have no recovery path. Commit the spec first (or run \`caws specs close <id>\` which auto-commits per CAWS-SPECS-WRITER-AUTOCOMMIT-001), then re-run archive.`, { subject: input.id, data: { from_path: fromRel } }));
     }
-    // Ensure the archive dir exists. fs.renameSync requires it.
-    try {
-        fs.mkdirSync(path.dirname(toPath), { recursive: true });
+    const sourceCommitSha = gitLastCommitForPath(repoRoot, fromRel);
+    // Build the event payload in tombstone shape.
+    const eventData = {
+        from_path: fromRel,
+        blob_sha: blobSha,
+    };
+    if (sourceCommitSha !== null) {
+        eventData.source_commit_sha = sourceCommitSha;
     }
-    catch (e) {
-        const cause = e;
-        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_WRITE_FAILED, `Failed to create archive directory: ${cause.message ?? 'unknown'}.`, { subject: path.dirname(toPath) }));
-    }
-    // Filesystem-move pattern: we write the patched bytes to the new
-    // path via the transaction, then delete the source. The transaction
-    // doesn't model moves natively, so we do this in two phases inside
-    // the same lock:
-    //   1. lifecycle-transaction: write toPath + append spec_archived
-    //   2. AFTER transaction success: unlink fromPath
-    //
-    // If step 2 fails, we surface the partial-failure but the audit log
-    // already records the move intent. The next doctor pass will see
-    // the spec in BOTH locations and surface that as a doctor finding.
-    const fromRel = path.relative(path.join(cawsDir, '..'), fromPath);
-    const toRel = path.relative(path.join(cawsDir, '..'), toPath);
     const event = {
         event: 'spec_archived',
         ts: now,
         actor: input.actor,
         spec_id: input.id,
-        data: { from_path: fromRel, to_path: toRel },
+        data: eventData,
     };
-    // Capture original bytes so we can roll back the unlink in
-    // emergencies (rare but worth tracking).
+    // Pre-write dirty state on the path being deleted.
+    const wasDirtyBeforeWrite = (0, git_autocommit_1.isPathDirty)(repoRoot, fromRel);
+    // The "fake plannedWrite" pattern: lifecycle-transaction's contract
+    // is "write these files atomically and append these events." We have
+    // no file to write, so we feed it an empty plannedWrites and append
+    // the event only. The unlink happens AFTER txn success but BEFORE
+    // autocommit, so the autocommit's `git add` stages the deletion.
     let unlinkOk = false;
     let unlinkError = null;
     const txnResult = (0, lifecycle_lock_1.withLifecycleLock)(cawsDir, () => {
         const r = (0, lifecycle_transaction_1.runLifecycleTransaction)({
             cawsDir,
-            plannedWrites: [{ path: toPath, contents: patched }],
+            plannedWrites: [],
             events: [event],
         });
         if (!r.ok)
             return r;
         if (r.value.kind !== 'success')
             return r;
-        // Transaction wrote toPath + appended event. Now remove fromPath.
+        // Event appended. Now unlink the active path.
         try {
             fs.unlinkSync(fromPath);
             unlinkOk = true;
@@ -414,11 +741,6 @@ function archiveSpec(cawsDir, input) {
         }
         return r;
     });
-    // Reason flows into closure_notes ONLY if the user passed one; archive
-    // event schema does NOT take closure_notes, but we attach the reason
-    // to a follow-up evidence record path in future versions. For v11.1
-    // archive, we accept the --reason for parity with close but the
-    // schema does not carry it.
     void input.reason;
     if (!txnResult.ok) {
         return (0, caws_kernel_1.err)(txnResult.errors);
@@ -430,16 +752,150 @@ function archiveSpec(cawsDir, input) {
         });
     }
     if (!unlinkOk) {
-        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED, `Archive write succeeded and spec_archived event appended, but original file unlink failed (${unlinkError}). Spec now exists in BOTH active and archived locations.`, {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED, `spec_archived event appended (blob_sha=${blobSha}) but unlink of ${fromPath} failed (${unlinkError}). The body is recoverable via \`git show ${blobSha}\` but the active file still exists on disk.`, {
             subject: input.id,
             data: {
                 from_path: fromPath,
-                to_path: toPath,
-                recovery_instruction: `Manually remove ${fromPath} once you've confirmed ${toPath} is intact.`,
+                blob_sha: blobSha,
+                recovery_instruction: `Manually remove ${fromPath}; the body is in git history at blob ${blobSha}.`,
             },
         }));
     }
-    return (0, caws_kernel_1.ok)({ kind: 'success', id: input.id, path: toPath });
+    // CAWS-SPECS-WRITER-AUTOCOMMIT-001: autoCommit the deletion. `git
+    // add -- <fromRel>` stages a deletion when the file is gone, so the
+    // resulting commit records the removal.
+    const audit = (0, git_autocommit_1.autoCommit)({
+        repoRoot,
+        paths: [fromRel],
+        message: `chore(caws): archive ${input.id}`,
+        wasDirtyBeforeWrite,
+    });
+    return (0, caws_kernel_1.ok)({
+        kind: 'success',
+        id: input.id,
+        path: fromPath,
+        data: { audit_commit: audit },
+    });
+}
+// ─── retireDraftSpec ─────────────────────────────────────────────────────
+//
+// CAWS-SPECS-RETIRE-DRAFT-001. Governed retirement of a never-activated
+// DRAFT spec. Mirrors archiveSpec's tombstone flow exactly, with two
+// differences: the precondition is lifecycle_state === 'draft' (not
+// 'closed'), and the event is spec_retired (which DOES carry an optional
+// reason, unlike spec_archived). No new lifecycle_state value — the
+// spec_retired event is the durable signal, and the body is deleted +
+// recoverable via `git show <blob_sha>`.
+function retireDraftSpec(cawsDir, input) {
+    const idValidation = validateSpecId(input.id);
+    if (!idValidation.ok)
+        return idValidation;
+    const fromPath = specPath(cawsDir, input.id);
+    if (!fs.existsSync(fromPath)) {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" not found at ${fromPath}.`, { subject: input.id }));
+    }
+    // Validate current state: must be draft. Active → close; closed → archive.
+    const sourceResult = (0, yaml_store_1.readYamlSource)(fromPath);
+    if (!(0, caws_kernel_1.isOk)(sourceResult))
+        return (0, caws_kernel_1.err)(sourceResult.errors);
+    const parsed = (0, caws_kernel_1.parseAndValidateSpec)(sourceResult.value);
+    if (!(0, caws_kernel_1.isOk)(parsed)) {
+        return (0, caws_kernel_1.err)(parsed.errors.map((d) => (0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, d.message, {
+            subject: d.subject ?? input.id,
+            data: { source_rule: d.rule },
+        })));
+    }
+    const spec = parsed.value;
+    if (spec.lifecycle_state !== 'draft') {
+        const alternative = spec.lifecycle_state === 'active'
+            ? `Use \`caws specs close ${input.id}\` to close an active spec.`
+            : spec.lifecycle_state === 'closed'
+                ? `Use \`caws specs archive ${input.id}\` to archive a closed spec.`
+                : `Only draft specs can be retired.`;
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" is in lifecycle_state "${spec.lifecycle_state}"; retire-draft only retires drafts. ${alternative}`, { subject: input.id, data: { current_state: spec.lifecycle_state } }));
+    }
+    const now = (input.now ?? (() => new Date()))().toISOString();
+    const repoRoot = repoRootFromCawsDir(cawsDir);
+    const fromRel = path.relative(repoRoot, fromPath);
+    // Capture blob_sha BEFORE any mutation — the authoritative recovery
+    // target. Refuse if the draft is not tracked at HEAD (no recovery path),
+    // mirroring archiveSpec's null-blob refusal.
+    const blobSha = gitBlobShaAtHead(repoRoot, fromRel);
+    if (blobSha === null) {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${input.id}" is not tracked at HEAD. Cannot retire: blob_sha is the authoritative recovery target, and without it the retirement event would have no recovery path. Commit the draft first, then re-run retire-draft.`, { subject: input.id, data: { from_path: fromRel } }));
+    }
+    const sourceCommitSha = gitLastCommitForPath(repoRoot, fromRel);
+    const eventData = {
+        from_path: fromRel,
+        blob_sha: blobSha,
+    };
+    if (sourceCommitSha !== null) {
+        eventData.source_commit_sha = sourceCommitSha;
+    }
+    if (input.reason !== undefined && input.reason.length > 0) {
+        eventData.reason = input.reason;
+    }
+    const event = {
+        event: 'spec_retired',
+        ts: now,
+        actor: input.actor,
+        spec_id: input.id,
+        data: eventData,
+    };
+    const wasDirtyBeforeWrite = (0, git_autocommit_1.isPathDirty)(repoRoot, fromRel);
+    let unlinkOk = false;
+    let unlinkError = null;
+    const txnResult = (0, lifecycle_lock_1.withLifecycleLock)(cawsDir, () => {
+        const r = (0, lifecycle_transaction_1.runLifecycleTransaction)({
+            cawsDir,
+            plannedWrites: [],
+            events: [event],
+        });
+        if (!r.ok)
+            return r;
+        if (r.value.kind !== 'success')
+            return r;
+        try {
+            fs.unlinkSync(fromPath);
+            unlinkOk = true;
+        }
+        catch (e) {
+            const cause = e;
+            unlinkError = cause.message ?? 'unknown unlink error';
+        }
+        return r;
+    });
+    if (!txnResult.ok) {
+        return (0, caws_kernel_1.err)(txnResult.errors);
+    }
+    if (txnResult.value.kind !== 'success') {
+        return (0, caws_kernel_1.ok)({
+            kind: 'partial_failure_recovered',
+            cause: txnResult.value.cause,
+        });
+    }
+    if (!unlinkOk) {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED, `spec_retired event appended (blob_sha=${blobSha}) but unlink of ${fromPath} failed (${unlinkError}). The body is recoverable via \`git show ${blobSha}\` but the draft file still exists on disk.`, {
+            subject: input.id,
+            data: {
+                from_path: fromPath,
+                blob_sha: blobSha,
+                recovery_instruction: `Manually remove ${fromPath}; the body is in git history at blob ${blobSha}.`,
+            },
+        }));
+    }
+    const audit = (0, git_autocommit_1.autoCommit)({
+        repoRoot,
+        paths: [fromRel],
+        message: `chore(caws): retire-draft ${input.id}`,
+        wasDirtyBeforeWrite,
+    });
+    return (0, caws_kernel_1.ok)({
+        kind: 'success',
+        id: input.id,
+        path: fromPath,
+        data: { audit_commit: audit },
+    });
 }
 // ─── Outcome mapper ──────────────────────────────────────────────────────
 function mapTxnToOutcome(result, id, targetPath) {
@@ -461,7 +917,24 @@ function mapTxnToOutcome(result, id, targetPath) {
         },
     }));
 }
-/** List specs by lifecycle state, optionally including archived ones. */
+/**
+ * List specs by lifecycle state, optionally including archived ones.
+ *
+ * CAWS-ARCHIVE-AS-TOMBSTONE-001: the `--include-archived` path now
+ * reads from `.caws/events.jsonl` (most recent spec_archived event
+ * per spec_id), NOT from `.caws/specs/.archive/`. Post-tombstone the
+ * .archive/ directory is not populated; reading it would either
+ * surface nothing (steady state) or surface legacy bodies the
+ * doctor warning already flags for migration.
+ *
+ * Includes legacy events (with only from_path + to_path, no
+ * blob_sha) → blob_sha is reported as null; recover falls back to
+ * git log --follow.
+ *
+ * Latest-write-wins per spec_id: if a spec was archived, recovered,
+ * recreated, and re-archived, only the most recent spec_archived
+ * event surfaces.
+ */
 function listSpecs(cawsDir, options = {}) {
     const activeResult = (0, specs_store_1.loadSpecs)(cawsDir);
     const active = activeResult.specs.map((spec) => ({
@@ -470,56 +943,422 @@ function listSpecs(cawsDir, options = {}) {
         lifecycle_state: spec.lifecycle_state,
         path: specPath(cawsDir, spec.id),
     }));
-    const archived = [];
+    const activeIds = new Set(active.map((s) => s.id));
+    let archived = [];
     if (options.includeArchived === true) {
-        const archiveDir = path.join(cawsDir, 'specs', '.archive');
-        if (fs.existsSync(archiveDir)) {
-            try {
-                const entries = fs.readdirSync(archiveDir, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (!entry.isFile())
-                        continue;
-                    if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
-                        continue;
-                    const fullPath = path.join(archiveDir, entry.name);
-                    const src = (0, yaml_store_1.readYamlSource)(fullPath);
-                    if (!(0, caws_kernel_1.isOk)(src))
-                        continue;
-                    const parsed = (0, caws_kernel_1.parseAndValidateSpec)(src.value);
-                    if (!(0, caws_kernel_1.isOk)(parsed))
-                        continue;
-                    const spec = parsed.value;
-                    archived.push({
-                        id: spec.id,
-                        title: spec.title,
-                        lifecycle_state: spec.lifecycle_state,
-                        path: fullPath,
-                    });
-                }
-            }
-            catch {
-                // Best-effort archive listing.
-            }
-        }
+        archived = readArchivedFromEventLog(cawsDir, activeIds);
     }
     return (0, caws_kernel_1.ok)({ active, archived });
 }
-/** Find a spec by id under active or archive locations. */
+/**
+ * Walk events.jsonl for spec_archived events; collect the most recent
+ * one per spec_id; emit entries. Excludes any spec_id that has been
+ * re-created since (presence in activeIds wins — that means the
+ * archive was undone by a subsequent createSpec).
+ */
+function readArchivedFromEventLog(cawsDir, activeIds) {
+    const eventsPath = path.join(cawsDir, 'events.jsonl');
+    if (!fs.existsSync(eventsPath))
+        return [];
+    let raw;
+    try {
+        raw = fs.readFileSync(eventsPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    // Map: spec_id → most recent spec_archived event payload+ts.
+    const latest = new Map();
+    for (const line of raw.split('\n')) {
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            parsed.event !== 'spec_archived') {
+            continue;
+        }
+        const evt = parsed;
+        if (typeof evt.ts !== 'string' ||
+            typeof evt.spec_id !== 'string' ||
+            typeof evt.data !== 'object' ||
+            evt.data === null ||
+            typeof evt.data.from_path !== 'string') {
+            continue;
+        }
+        latest.set(evt.spec_id, {
+            ts: evt.ts,
+            from_path: evt.data.from_path,
+            blob_sha: typeof evt.data.blob_sha === 'string' ? evt.data.blob_sha : null,
+        });
+    }
+    const out = [];
+    for (const [specId, info] of latest) {
+        if (activeIds.has(specId))
+            continue; // re-created after archive — active wins
+        out.push({
+            id: specId,
+            path: info.from_path,
+            archived_at: info.ts,
+            blob_sha: info.blob_sha,
+        });
+    }
+    // Stable sort: by id ascending.
+    out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return out;
+}
+/**
+ * Find a spec by id in the ACTIVE location only
+ * (.caws/specs/<id>.yaml). CAWS-ARCHIVE-AS-TOMBSTONE-001 invariant:
+ * `caws specs show` defaults to active specs only. Archived specs
+ * require explicit opt-in via `--archived` (which routes through
+ * `recoverArchivedSpec` below).
+ *
+ * Pre-tombstone: showSpec searched both active AND .caws/specs/.archive/
+ * transparently. That transparent fallback was a context-rot vector
+ * (agents grep'd and cited stale specs as authority); it is removed
+ * by design.
+ */
 function showSpec(cawsDir, id) {
     const idValidation = validateSpecId(id);
     if (!idValidation.ok)
         return idValidation;
-    const fullPath = findSpecPath(cawsDir, id);
-    if (fullPath === null) {
-        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${id}" not found in .caws/specs/ or .caws/specs/.archive/.`, { subject: id }));
+    const activePath = specPath(cawsDir, id);
+    if (!fs.existsSync(activePath)) {
+        // Distinguish "never existed" from "exists but archived". The
+        // event log tells us if there's a spec_archived event; if yes,
+        // surface a typed diagnostic pointing the user at --archived /
+        // recover. If no, the spec is genuinely unknown.
+        const archived = findArchivedSpecEvent(cawsDir, id);
+        if (archived !== null) {
+            return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${id}" is not in active specs. It was archived; to view its body, use \`caws specs show ${id} --archived\` or \`caws specs recover ${id}\`.`, {
+                subject: id,
+                data: {
+                    archived_at: archived.ts,
+                    blob_sha: archived.blob_sha,
+                    from_path: archived.from_path,
+                },
+            }));
+        }
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${id}" not found in .caws/specs/.`, { subject: id }));
     }
-    const sourceResult = (0, yaml_store_1.readYamlSource)(fullPath);
+    const sourceResult = (0, yaml_store_1.readYamlSource)(activePath);
     if (!(0, caws_kernel_1.isOk)(sourceResult))
         return (0, caws_kernel_1.err)(sourceResult.errors);
     const parsed = (0, caws_kernel_1.parseAndValidateSpec)(sourceResult.value);
     if (!(0, caws_kernel_1.isOk)(parsed))
         return (0, caws_kernel_1.err)(parsed.errors);
-    return (0, caws_kernel_1.ok)({ spec: parsed.value, path: fullPath, source: sourceResult.value });
+    return (0, caws_kernel_1.ok)({ spec: parsed.value, path: activePath, source: sourceResult.value });
+}
+/**
+ * Walk .caws/events.jsonl, return the most recent spec_archived
+ * event for the given spec_id, or null if none exists. Handles both
+ * legacy (from_path + to_path) and tombstone (from_path + blob_sha)
+ * shapes.
+ *
+ * "Most recent" semantics: events.jsonl is append-only; the LAST
+ * matching event wins. If a spec was archived, recovered, recreated,
+ * and re-archived, only the latest spec_archived is relevant for
+ * recovery.
+ */
+function findArchivedSpecEvent(cawsDir, specId) {
+    const eventsPath = path.join(cawsDir, 'events.jsonl');
+    if (!fs.existsSync(eventsPath))
+        return null;
+    let raw;
+    try {
+        raw = fs.readFileSync(eventsPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let latest = null;
+    for (const line of raw.split('\n')) {
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        // CAWS-SPECS-RETIRE-DRAFT-001 A5: recovery also resolves a retired
+        // draft. spec_retired shares the identical {from_path, blob_sha}
+        // tombstone shape as spec_archived, so the same git-show recovery
+        // path reconstructs it. Accept either event type.
+        const evtType = parsed.event;
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            (evtType !== 'spec_archived' && evtType !== 'spec_retired') ||
+            parsed.spec_id !== specId) {
+            continue;
+        }
+        const evt = parsed;
+        if (typeof evt.ts !== 'string' ||
+            typeof evt.data !== 'object' ||
+            evt.data === null ||
+            typeof evt.data.from_path !== 'string') {
+            continue;
+        }
+        latest = {
+            ts: evt.ts,
+            from_path: evt.data.from_path,
+            blob_sha: typeof evt.data.blob_sha === 'string' ? evt.data.blob_sha : null,
+            ...(typeof evt.data.to_path === 'string' ? { to_path: evt.data.to_path } : {}),
+        };
+    }
+    return latest;
+}
+/**
+ * Recover an archived spec's body from git history.
+ *
+ * Resolution order:
+ *   1. New-shape event with blob_sha → `git show <blob_sha>`.
+ *   2. Legacy event with to_path only → `git log --all --follow --
+ *      <from_path>` to find a containing commit, then
+ *      `git show <commit>:<from_path>`. If zero commits, Err.
+ *
+ * NEVER mutates .caws/specs/. Returns the raw yaml bytes.
+ */
+function recoverArchivedSpec(cawsDir, id) {
+    const idValidation = validateSpecId(id);
+    if (!idValidation.ok)
+        return idValidation;
+    const evt = findArchivedSpecEvent(cawsDir, id);
+    if (evt === null) {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${id}" was never archived (no spec_archived event in .caws/events.jsonl).`, { subject: id }));
+    }
+    const repoRoot = repoRootFromCawsDir(cawsDir);
+    // Tombstone shape: recover via blob_sha (topology-independent).
+    if (evt.blob_sha !== null) {
+        if (!/^[0-9a-f]{40}$/.test(evt.blob_sha)) {
+            return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `spec_archived event for "${id}" has malformed blob_sha "${evt.blob_sha}" (expected 40-hex).`, { subject: id }));
+        }
+        // trim:false preserves the spec yaml's trailing newline so the
+        // recovered body is byte-identical to the pre-archive content.
+        const body = runGitQuery(['show', evt.blob_sha], repoRoot, { trim: false });
+        if (body === null) {
+            return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Blob ${evt.blob_sha} for spec "${id}" is not in the local git object store. Try \`git fetch --unshallow\` or \`git fetch --all\` if this is a shallow clone.`, { subject: id, data: { blob_sha: evt.blob_sha, from_path: evt.from_path } }));
+        }
+        return (0, caws_kernel_1.ok)({ source: body, blob_sha: evt.blob_sha, from_path: evt.from_path });
+    }
+    // Legacy shape: fall back to git log --follow on from_path. Walk
+    // commits in newest-first order and pick the first one where the
+    // file exists at from_path (skip deletion commits). The `git log
+    // --follow` output includes BOTH commits where the file existed
+    // and the commit that removed it; we want the first one before
+    // the deletion.
+    const commitListing = runGitQuery(['log', '--all', '--follow', '--format=%H', '--', evt.from_path], repoRoot);
+    if (commitListing === null || commitListing.length === 0) {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${id}" is a legacy archive (event has no blob_sha) and no commit on the current branch contains "${evt.from_path}". The body is unrecoverable from this clone.`, { subject: id, data: { from_path: evt.from_path } }));
+    }
+    const commits = commitListing
+        .split('\n')
+        .map((c) => c.trim())
+        .filter((c) => /^[0-9a-f]{40}$/.test(c));
+    if (commits.length === 0) {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `git log returned no valid commit shas for "${evt.from_path}".`, { subject: id }));
+    }
+    // Walk newest-first; pick the first commit where the file blob
+    // exists at from_path. trim:false preserves trailing newlines.
+    for (const commit of commits) {
+        const body = runGitQuery(['show', `${commit}:${evt.from_path}`], repoRoot, { trim: false });
+        if (body !== null) {
+            return (0, caws_kernel_1.ok)({ source: body, blob_sha: null, from_path: evt.from_path });
+        }
+    }
+    return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Spec "${id}" is a legacy archive; git log --follow returned ${commits.length} commits referencing "${evt.from_path}" but none contained the file body (all were deletion commits or renames). Body unrecoverable from this clone.`, { subject: id, data: { from_path: evt.from_path, candidates: commits.length } }));
+}
+/**
+ * Scan .caws/specs/.archive/ for legacy bodies. Returns per-id status
+ * (dry-run) or executes the migration (--apply).
+ *
+ * Recoverability check: `git log --all --follow -- <fromPath>`. If
+ * any commit contains the file, the body is recoverable from git
+ * history; we extract the blob_sha + most-recent containing commit
+ * and that becomes the recovery target. If zero commits, the body
+ * is local-only and gets quarantined.
+ */
+function pruneArchive(cawsDir, input) {
+    const archiveDir = path.join(cawsDir, 'specs', '.archive');
+    if (!fs.existsSync(archiveDir)) {
+        // No legacy archive to prune; succeed with empty plan.
+        return (0, caws_kernel_1.ok)({ plans: [], applied: input.apply === true, events_appended: 0 });
+    }
+    const repoRoot = repoRootFromCawsDir(cawsDir);
+    const apply = input.apply === true;
+    const now = (input.now ?? (() => new Date()))().toISOString();
+    // Enumerate yaml files at the top of .archive/, excluding the
+    // .unrecoverable/ subdir (which is the destination, not a source).
+    let entries;
+    try {
+        entries = fs.readdirSync(archiveDir, { withFileTypes: true });
+    }
+    catch (e) {
+        return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PLAN_REJECTED, `Failed to read ${archiveDir}: ${e.message}`, { subject: archiveDir }));
+    }
+    const plans = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
+            continue;
+        const id = entry.name.replace(/\.ya?ml$/, '');
+        const fromPath = path.join(archiveDir, entry.name);
+        // The legacy archive bodies' from_path (where the spec was BEFORE
+        // archiving) is .caws/specs/<id>.yaml — that's what git log
+        // --follow searches.
+        const activeRel = path.relative(repoRoot, specPath(cawsDir, id));
+        // Find any commit that contained the file at activeRel.
+        const commitListing = runGitQuery(['log', '--all', '--follow', '--format=%H', '--', activeRel], repoRoot);
+        if (commitListing === null || commitListing.length === 0) {
+            plans.push({
+                id,
+                fromPath,
+                fromRel: path.relative(repoRoot, fromPath),
+                status: 'unrecoverable',
+                reason: `git log --all --follow -- ${activeRel} returned no commits`,
+            });
+            continue;
+        }
+        // Walk commits newest-first; pick the first one where the blob
+        // actually exists at activeRel (skip deletion commits).
+        let recovered = null;
+        for (const commit of commitListing.split('\n')) {
+            const c = commit.trim();
+            if (!/^[0-9a-f]{40}$/.test(c))
+                continue;
+            const lsTree = runGitQuery(['ls-tree', c, '--', activeRel], repoRoot);
+            if (lsTree === null || lsTree.length === 0)
+                continue;
+            const blobParts = lsTree.split(/\s+/);
+            if (blobParts.length < 3)
+                continue;
+            const sha = blobParts[2];
+            if (sha !== undefined && /^[0-9a-f]{40}$/.test(sha)) {
+                recovered = { commit: c, blob: sha };
+                break;
+            }
+        }
+        if (recovered === null) {
+            plans.push({
+                id,
+                fromPath,
+                fromRel: path.relative(repoRoot, fromPath),
+                status: 'unrecoverable',
+                reason: `git log returned commits but none contained the blob at ${activeRel}`,
+            });
+        }
+        else {
+            plans.push({
+                id,
+                fromPath,
+                fromRel: path.relative(repoRoot, fromPath),
+                status: 'recoverable',
+                blob_sha: recovered.blob,
+                commit_sha: recovered.commit,
+            });
+        }
+    }
+    if (!apply) {
+        return (0, caws_kernel_1.ok)({ plans, applied: false, events_appended: 0 });
+    }
+    // --apply: execute the migration. For each plan:
+    //   recoverable   → fs.unlinkSync(fromPath) + emit removed event
+    //   unrecoverable → fs.renameSync to .unrecoverable/<id>.yaml + emit
+    //                   quarantined event
+    // Quarantine dir is created lazily on first unrecoverable.
+    const unrecoverableDir = path.join(archiveDir, '.unrecoverable');
+    let eventsAppended = 0;
+    for (const plan of plans) {
+        if (plan.status === 'recoverable') {
+            try {
+                fs.unlinkSync(plan.fromPath);
+            }
+            catch (e) {
+                // Best-effort: surface as Err but allow event-append to skip.
+                // The plan reported the intent; the operator can inspect.
+                return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED, `Failed to unlink ${plan.fromPath}: ${e.message}`, { subject: plan.id }));
+            }
+            const event = {
+                event: 'spec_archive_pruned',
+                ts: now,
+                actor: input.actor,
+                spec_id: plan.id,
+                data: {
+                    from_path: plan.fromRel,
+                    action: 'removed',
+                    blob_sha: plan.blob_sha,
+                    from_commit_sha: plan.commit_sha,
+                },
+            };
+            const txn = (0, lifecycle_lock_1.withLifecycleLock)(cawsDir, () => (0, lifecycle_transaction_1.runLifecycleTransaction)({
+                cawsDir,
+                plannedWrites: [],
+                events: [event],
+            }));
+            if (!txn.ok)
+                return (0, caws_kernel_1.err)(txn.errors);
+            if (txn.value.kind !== 'success') {
+                return (0, caws_kernel_1.ok)({
+                    plans,
+                    applied: true,
+                    events_appended: eventsAppended,
+                });
+            }
+            eventsAppended++;
+        }
+        else {
+            try {
+                fs.mkdirSync(unrecoverableDir, { recursive: true });
+            }
+            catch (e) {
+                return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_WRITE_FAILED, `Failed to create quarantine dir ${unrecoverableDir}: ${e.message}`, { subject: unrecoverableDir }));
+            }
+            const toPath = path.join(unrecoverableDir, path.basename(plan.fromPath));
+            const toRel = path.relative(repoRoot, toPath);
+            try {
+                fs.renameSync(plan.fromPath, toPath);
+            }
+            catch (e) {
+                return (0, caws_kernel_1.err)((0, repo_root_1.storeDiagnostic)(rules_1.STORE_RULES.LIFECYCLE_PARTIAL_FAILURE_UNRECOVERED, `Failed to quarantine ${plan.fromPath} → ${toPath}: ${e.message}`, { subject: plan.id }));
+            }
+            const event = {
+                event: 'spec_archive_pruned',
+                ts: now,
+                actor: input.actor,
+                spec_id: plan.id,
+                data: {
+                    from_path: plan.fromRel,
+                    action: 'quarantined',
+                    to_path: toRel,
+                },
+            };
+            const txn = (0, lifecycle_lock_1.withLifecycleLock)(cawsDir, () => (0, lifecycle_transaction_1.runLifecycleTransaction)({
+                cawsDir,
+                plannedWrites: [],
+                events: [event],
+            }));
+            if (!txn.ok)
+                return (0, caws_kernel_1.err)(txn.errors);
+            if (txn.value.kind !== 'success') {
+                return (0, caws_kernel_1.ok)({
+                    plans,
+                    applied: true,
+                    events_appended: eventsAppended,
+                });
+            }
+            eventsAppended++;
+        }
+    }
+    return (0, caws_kernel_1.ok)({ plans, applied: true, events_appended: eventsAppended });
 }
 // Unused import elimination: surface appendEvent so future direct-event
 // flows (if any) compile against the same surface as evidence/waiver.