akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/improve/memory/derived-ref.js

@@ -1,61 +1,22 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * The single, keyed-on-ref implementation of "is this a derived memory?" and
- * "which parent does it derive from?" (R12).
- *
- * Two divergent copies previously lived side by side — the CONSUMER
- * (`memory-improve.ts`, keyed on the memory name) and the PRODUCER
- * (`memory-contradiction-detect.ts`, keyed on the file path). The producer's
- * copy was strictly narrower: it ignored `derivedFrom` entirely and matched
- * `source:` through a separate parser. That let the producer and consumer
- * disagree on a memory's parent — the exact defect plan §6 calls out
- * ("producer/consumer cannot disagree").
- *
- * Both sides now share this one impl, keyed on the memory NAME (the stash-
- * relative path without the `.md` extension, e.g. `nested/foo.derived`). The
- * producer converts its file path to a name via `toMemoryRef` before calling
- * in. Adopting it on the producer side is an INTENTIONAL widening, pinned by
- * `tests/commands/improve/derived-ref.test.ts`:
- *   - `derivedFrom`-keyed families now resolve a parent (and so participate in
- *     contradiction detection); and
- *   - `source:` is parsed through `parseRefInput` so current bundle-qualified
- *     refs resolve consistently.
- *
- * Resolution order (source → derivedFrom → `.derived` suffix) matches the
- * consumer's prior behaviour exactly, so the consumer side is a pure move.
- */
+/** The one implementation of "is this a derived memory, and what is its parent?" (R12), keyed on the memory name. */
 import { conceptIdFromTypeName, parseRefInput } from "../../../core/asset/resolve-ref.js";
 import { asNonEmptyString } from "../../../core/common.js";
 import { DERIVED_SUFFIX } from "../../../core/recognition-util.js";
 /**
- * Parse a belief edge (`supersededBy` / `contradictedBy` / `currentBeliefRefs`)
- * to the bare memory name the identity channel keys on.
- *
- * Accepts BOTH spellings, because both reach this function:
- *   - `memory:<name>` — the internal identity spelling, and what belief edges
- *     written before 0.9.0 carry on disk;
- *   - `memories/<name>` / `<bundle>//memories/<name>` — the conceptId grammar
- *     the current writers emit (`akm remember --supersedes` and `akm import
- *     --supersedes` go through `writeSupersededEdge` with the write result's
- *     `ref`, which is fully qualified).
- *
- * Accepting only the first spelling silently reduced every edge written by the
- * current code path to nothing, so a superseded memory read back as active.
- * Both normalize to the bare name; the caller re-mints the internal
- * `memory:<name>` form via {@link memoryIdentityRef}, so there is still exactly
- * one identity spelling downstream.
+ * A belief edge (`supersededBy` / `contradictedBy` / `currentBeliefRefs`) as a
+ * bare memory name. Both spellings occur: `memory:<name>` (pre-0.9 edges) and
+ * `[bundle//]memories/<name>` (what `--supersedes` writes today); accepting only
+ * the first once read every superseded memory back as active.
  */
 export function parseMemoryName(value) {
     if (!value)
         return undefined;
     const trimmed = value.trim();
-    const MEMORY_PREFIX = "memory:";
-    if (trimmed.startsWith(MEMORY_PREFIX)) {
-        const name = trimmed.slice(MEMORY_PREFIX.length);
-        return name.length > 0 ? name : undefined;
-    }
+    if (trimmed.startsWith("memory:"))
+        return trimmed.slice("memory:".length) || undefined;
     try {
         const parsed = parseRefInput(trimmed);
         return parsed.type === "memory" && parsed.name.length > 0 ? parsed.name : undefined;
@@ -64,10 +25,7 @@ export function parseMemoryName(value) {
         return undefined;
     }
 }
-/**
- * Parse a current `source:` backref and return its canonical memory conceptId,
- * or `undefined` when it is empty, invalid, or not a memory ref.
- */
+/** A `source:` backref as a memory conceptId, or `undefined` when it is not a memory ref. */
 export function parseMemoryRef(value) {
     if (!value)
         return undefined;
@@ -79,37 +37,15 @@ export function parseMemoryRef(value) {
         return undefined;
     }
 }
-/**
- * Format a bare memory name into the belief-edge IDENTITY channel ref
- * `memory:<name>` — the ONE implementation of that spelling.
- *
- * Belief-edge / identity
- * channel (`contradictedBy` / `supersededBy` / `currentBeliefRefs`, and a derived
- * memory's own `record.ref`) uses `memory:<name>` and is compared against a
- * derived memory's identity ref. This channel is separate from `source:` asset
- * refs, which use `memories/<name>`. Both `memory-improve.ts` (`refArray`) and
- * `memory-contradiction-detect.ts` (`toMemoryRef`) emit through here so the
- * identity spelling has one implementation.
- */
+/** The belief-edge identity spelling, `memory:<name>` (separate from `source:` asset refs). */
 export function memoryIdentityRef(name) {
     return `memory:${name}`;
 }
-/**
- * True when the named memory is a derived/inferred child — either it carries
- * `inferred: true` in its frontmatter or its name ends with the structural
- * `.derived` suffix.
- */
+/** Inferred (`inferred: true`) or named with the `.derived` suffix. */
 export function isDerivedMemory(name, frontmatter) {
     return frontmatter.inferred === true || name.endsWith(DERIVED_SUFFIX);
 }
-/**
- * Resolve the parent (source) memory ref for a derived memory as a canonical
- * `memories/<name>` conceptId, or `undefined` when none
- * can be determined. Precedence:
- *   1. `frontmatter.source` (normalised through {@link parseMemoryRef});
- *   2. `frontmatter.derivedFrom` (a bare memory name → `memories/<name>`);
- *   3. the `.derived` name suffix, stripped → `memories/<name>`.
- */
+/** A derived memory's parent conceptId: from `source`, else `derivedFrom`, else the name minus `.derived`. */
 export function resolveParentRef(name, frontmatter) {
     const fromSource = parseMemoryRef(asNonEmptyString(frontmatter.source));
     if (fromSource)
@@ -117,8 +53,7 @@ export function resolveParentRef(name, frontmatter) {
     const derivedFrom = asNonEmptyString(frontmatter.derivedFrom);
     if (derivedFrom)
         return conceptIdFromTypeName("memory", derivedFrom);
-    if (name.endsWith(DERIVED_SUFFIX)) {
+    if (name.endsWith(DERIVED_SUFFIX))
         return conceptIdFromTypeName("memory", name.slice(0, -DERIVED_SUFFIX.length));
-    }
     return undefined;
 }

package/dist/commands/improve/memory/memory-belief.js

@@ -2,141 +2,39 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Shared memory belief-state machinery (C-3 / #382).
- *
- * Extracted from `memory-improve.ts` so both `akmConsolidate` and
- * `analyzeMemoryCleanup` can emit `MemoryBeliefTransitionLogRecord` entries
- * through a unified state-transition model.
- *
- * # Design
- *
- * The 4-state belief lifecycle (active → superseded | contradicted → archived)
- * was previously encoded only in `memory-improve.ts`. `akmConsolidate` used a
- * flat merge/delete/promote model with no belief states, causing the two engines
- * to diverge. This module:
- *
- *   1. Re-exports the belief-state types from `memory-improve.ts` so callers
- *      can import from one canonical location.
- *   2. Provides `writeContradictEdge` — a shared primitive that both engines
- *      use when an LLM (or heuristic) identifies a contradiction between two
- *      memories. This is the bridge between `akmConsolidate`'s LLM-detected
- *      contradictions and `resolveFamilyContradictions`' SCC resolver.
- *
- * # References
- *
- * - Zep / Graphiti (arXiv:2501.13956 §3) — unified belief-revision pipeline
- * - MemOS (arXiv:2507.03724) — formal archive/merge/transition with shared state model
+ * Belief-state edge writer (#382): append a `supersededBy` edge to an asset's
+ * frontmatter and demote its `beliefState`, metadata only. Idempotent (a
+ * present edge AND demotion is a no-op; an edge without its demotion is
+ * repaired) and never weakens a stronger demotion — severity is
+ * superseded > contradicted > archived. (alpha.4 removed belief weights from
+ * ranking: search no longer reads `beliefState` at all, and `--belief
+ * current|historical` is the only reader, opt-in.)
+ * The SCC resolver in memory-improve.ts is a state-transition writer (it
+ * replaces and clears edges) and deliberately does not use this (#885).
  */
 import { mutateFrontmatter } from "../../../core/asset/frontmatter.js";
-// ── Shared edge-list reader ───────────────────────────────────────────────────
 /**
- * Read a frontmatter edge value (`supersededBy` / `contradictedBy`) as a
- * string list, promoting a scalar string to a one-element list.
- *
- * Scalar edges are LIVE data: the indexer's `normalizeNonEmptyStringList`
- * accepts them and lint deliberately never flags them. An Array.isArray-only
- * read treats a scalar as "no existing edges" and silently destroys the edge
- * on the next merge — mirror `mergeXrefsIntoContent`'s scalar promotion
- * instead.
+ * An edge value as a list. A scalar string is live data (the indexer accepts
+ * it), so it is promoted rather than dropped on the next write.
  */
 function readEdgeList(value) {
-    if (Array.isArray(value)) {
+    if (Array.isArray(value))
         return value.filter((v) => typeof v === "string" && v.trim().length > 0);
-    }
     if (typeof value === "string" && value.trim())
         return [value.trim()];
     return [];
 }
-// ── Contradiction edge writer ─────────────────────────────────────────────────
-/**
- * Write `contradictedBy` and `beliefState: contradicted` edges to a memory
- * file's frontmatter (C-3 / #382).
- *
- * The shared primitive for APPENDING one contradiction edge. Used by
- * `memory-contradiction-detect.ts`'s automated contradiction pass.
- *
- * NOT used by `persistBeliefStateTransition` in `memory-improve.ts`, and that
- * is deliberate (#885): the SCC resolver is a state-TRANSITION writer, not an
- * edge appender. It replaces `contradictedBy` wholesale from recomputed
- * `currentBeliefRefs`, deletes the key when a memory transitions away from
- * `contradicted`, and moves a memory to any target state including back to
- * active. An append-only primitive that never weakens a demotion cannot
- * express those, and routing it through this would break the resolver's
- * ability to clear an edge.
- *
- * Idempotent: if the `contradictedByRef` is already in `contradictedBy` AND
- * the file already carries the demotion state, the file is not rewritten. The
- * guard is state-aware like its sibling {@link writeSupersededEdge}: an edge
- * present WITHOUT the demotion (e.g. a hand-written `contradictedBy:` line,
- * or a beliefState lost to a partial edit) is repaired, not skipped — an
- * edge-only guard would make such a file a permanent no-op while
- * contradiction writers report the contradiction as applied.
- *
- * Never weakens a stronger demotion: `archived` ranks BELOW `contradicted`
- * (see `BELIEF_STATE_SCORE_CEILINGS` in
- * src/indexer/search/ranking-contributors.ts), so contradicting an archived
- * memory keeps `archived` and only appends the edge.
- *
- * @param filePath          - Absolute path to the memory markdown file.
- * @param contradictedByRef - The ref that contradicts this memory.
- * @returns `true` when the file was rewritten, `false` when the edge and the
- *          demotion were already present (the idempotent no-op). Callers count
- *          edges written from this.
- */
-export function writeContradictEdge(filePath, contradictedByRef) {
-    return mutateFrontmatter(filePath, (parsed) => {
-        const existing = readEdgeList(parsed.data.contradictedBy);
-        const currentState = parsed.data.beliefState;
-        const nextState = currentState === "archived" ? currentState : "contradicted";
-        if (existing.includes(contradictedByRef) && currentState === nextState) {
-            return null; // Already written — idempotent.
-        }
-        const nextContradictedBy = [...new Set([...existing, contradictedByRef])].sort();
-        return {
-            ...parsed.data,
-            contradictedBy: nextContradictedBy,
-            beliefState: nextState,
-        };
-    });
-}
-// ── Supersession edge writer ─────────────────────────────────────────────────
-/**
- * Write `supersededBy` and `beliefState: superseded` edges to an asset file's
- * frontmatter (SPEC-5, stash-conventions-code-spec.md).
- *
- * Sibling of {@link writeContradictEdge}: the shared primitive for the
- * conventions' corrections pattern — when a new asset supersedes an old one,
- * the old asset gets a METADATA-ONLY demotion edit (every other frontmatter
- * key and the body are preserved) so the ranker's beliefStateBoost demotes the
- * stale incumbent and `--belief current` hides it. Used by
- * `akm remember --supersedes` / `akm import --supersedes`.
- *
- * Idempotent: if `supersededByRef` is already in `supersededBy` and the file
- * is already demoted, the file is not rewritten. Multiple corrections
- * sorted-set-append their refs.
- *
- * Never WEAKENS an existing demotion: `contradicted` and `archived` rank
- * BELOW `superseded` (severity order deprecated > superseded > contradicted >
- * archived — see `BELIEF_STATE_SCORE_CEILINGS` in
- * src/indexer/search/ranking-contributors.ts), so superseding an already
- * contradicted/archived asset keeps the stronger state and only appends the
- * `supersededBy` edge.
- *
- * @param filePath        - Absolute path to the asset markdown file.
- * @param supersededByRef - The ref of the correction that supersedes this asset.
- */
+/** Mark an asset superseded by a correction (`akm remember|import --supersedes`). */
 export function writeSupersededEdge(filePath, supersededByRef) {
     mutateFrontmatter(filePath, (parsed) => {
         const existing = readEdgeList(parsed.data.supersededBy);
         const currentState = parsed.data.beliefState;
         const nextState = currentState === "contradicted" || currentState === "archived" ? currentState : "superseded";
-        if (existing.includes(supersededByRef) && currentState === nextState) {
-            return null; // Already written — idempotent.
-        }
-        const nextSupersededBy = [...new Set([...existing, supersededByRef])].sort();
+        if (existing.includes(supersededByRef) && currentState === nextState)
+            return null;
         return {
             ...parsed.data,
-            supersededBy: nextSupersededBy,
+            supersededBy: [...new Set([...existing, supersededByRef])].sort(),
             beliefState: nextState,
         };
     });

package/dist/commands/improve/memory/memory-improve.js

@@ -7,11 +7,13 @@ import { assembleAsset } from "../../../core/asset/asset-serialize.js";
 import { mutateFrontmatter, parseFrontmatter } from "../../../core/asset/frontmatter.js";
 import { MEMORY_ARCHIVE_REL } from "../../../core/asset/memory-archive.js";
 import { conceptIdFromTypeName } from "../../../core/asset/resolve-ref.js";
-import { asNonEmptyString, groupBy, stringArray } from "../../../core/common.js";
+import { asNonEmptyString, groupBy, stringArray, toPosix } from "../../../core/common.js";
 import { DERIVED_SUFFIX } from "../../../core/recognition-util.js";
 import { warn } from "../../../core/warn.js";
 import { recordWrittenPath } from "../../../core/write-provenance.js";
 import { walkMarkdownFiles } from "../../../indexer/walk/walker.js";
+import { checkGitPathSafety, isGitBackedStash } from "../../../sources/providers/git-stash.js";
+import { contentHash } from "../content-hash.js";
 import { isDerivedMemory, memoryIdentityRef, parseMemoryName, resolveParentRef } from "./derived-ref.js";
 export function analyzeMemoryCleanup(stashDir, options = {}) {
     const records = collectDerivedMemories(stashDir, options.parentRef);
@@ -462,17 +464,80 @@ function stronglyConnectedComponents(refs, edges) {
     }
     return { components, componentIndexByRef };
 }
-function archiveCleanupCandidate(stashDir, candidate, filePath) {
+/**
+ * The `.derived` twin of a non-derived memory file, if one exists on disk:
+ * `<name>.derived.md` beside it, the naming convention
+ * `indexer/passes/memory-inference.ts`'s `derivedChildPath` writes.
+ * `undefined` for a knowledge or lesson ref (no such twin exists), or for a
+ * memory that is already itself `.derived` (it has no further twin).
+ *
+ * Used by `akm proposal accept` (alpha.9) to take a retired or promoted
+ * memory's derived child along when it archives the memory.
+ */
+export function derivedTwinPath(filePath, refType) {
+    if (refType !== "memory" || filePath.endsWith(`${DERIVED_SUFFIX}.md`))
+        return undefined;
+    const twin = `${filePath.slice(0, -3)}${DERIVED_SUFFIX}.md`;
+    return fs.existsSync(twin) ? twin : undefined;
+}
+/**
+ * True for a retire-proposal-caused archive (alpha.9: the consolidate pair
+ * pass, or O1's promotion retirement) — distinguished from a memory-cleanup
+ * family-prune candidate by carrying a `proposalId`. The two paths differ in
+ * how `previousBeliefState` is derived (below) and in which extra tombstone
+ * fields apply.
+ */
+function isRetireCandidate(candidate) {
+    return candidate.proposalId !== undefined;
+}
+/**
+ * The tombstone's `previousBeliefState`. Memory cleanup's own family-prune
+ * candidates keep their original reason-based inference (unchanged, so
+ * existing behavior is not disturbed by this generalization). A
+ * retire-proposal candidate has no such reason vocabulary to infer from, so
+ * it reads the asset's ACTUAL frontmatter `beliefState` instead — more
+ * correct, and available because every retire path already has the file on
+ * disk right before the move.
+ */
+function resolvePreviousBeliefState(candidate, filePath) {
+    if (!isRetireCandidate(candidate))
+        return priorBeliefStateForArchive(candidate);
+    try {
+        return resolveBeliefState(parseFrontmatter(fs.readFileSync(filePath, "utf8")).data);
+    }
+    catch {
+        return "active";
+    }
+}
+/**
+ * Move `filePath` into the recoverable cleanup archive
+ * (`.akm/memory-cleanup/archive/<stamp>-<ref>/`) with a `cleanup.md`
+ * tombstone, journaling both ends (`recordWrittenPath`) so a LATER sync
+ * commits the move — `akm sync`, or the batched auto-sync an `akm improve`
+ * run does at its own end (`docs/architecture/improvement.md`, "Auto-sync").
+ * This call does not itself commit anything: a standalone `akm proposal
+ * accept` (the only way a retire proposal is ever accepted — triage never
+ * auto-accepts one) leaves the move journaled but uncommitted until
+ * something later reads that journal, unless the write target's `kind` is
+ * `"git"`, in which case the caller's own `commitWriteTargetBoundary` commits
+ * (and maybe pushes) immediately as part of the SAME accept.
+ *
+ * Generalized in alpha.9 to cover any memory, knowledge or lesson file in a
+ * writable bundle — not only `.derived` memories — so `akm proposal accept`
+ * can archive a consolidate pair-pass `retire` proposal's target, or (O1) an
+ * accepted promotion's source memory, through the same one encoding memory
+ * cleanup already used (D27: never two coexisting encodings). A
+ * retire-proposal candidate (one carrying `proposalId`) additionally stamps
+ * `proposalId`, `successorRefs` and `retiredAt` on the tombstone.
+ */
+export function archiveCleanupCandidate(stashDir, candidate, filePath) {
     const archivedAt = new Date().toISOString();
+    const previousBeliefState = resolvePreviousBeliefState(candidate, filePath);
     const originalPath = path.relative(stashDir, filePath).replace(/\\/g, "/");
     const archiveDir = createArchiveDir(stashDir, candidate.ref, archivedAt);
     const archivedPath = path.join(archiveDir, originalPath);
     fs.mkdirSync(path.dirname(archivedPath), { recursive: true });
-    fs.renameSync(filePath, archivedPath);
-    // #652: an archive is a delete + a create. BOTH ends are journaled so the
-    // sync stages the removal of the original alongside the archived copy.
-    recordWrittenPath(filePath);
-    recordWrittenPath(archivedPath);
+    const retiring = isRetireCandidate(candidate);
     const archiveRef = path.relative(stashDir, archivedPath).replace(/\\/g, "/");
     const auditPath = path.join(archiveDir, "cleanup.md");
     const auditRef = path.relative(stashDir, auditPath).replace(/\\/g, "/");
@@ -481,29 +546,216 @@ function archiveCleanupCandidate(stashDir, candidate, filePath) {
         kind: "memory-cleanup-archive",
         archivedAt,
         beliefState: "archived",
-        previousBeliefState: priorBeliefStateForArchive(candidate),
+        previousBeliefState,
         ref: candidate.ref,
-        parentRef: candidate.parentRef,
+        ...(candidate.parentRef ? { parentRef: candidate.parentRef } : {}),
         reason: candidate.reason,
         ...(candidate.survivorRef ? { survivorRef: candidate.survivorRef } : {}),
         originalPath,
         archivedPath: archiveRef,
+        ...(retiring ? { proposalId: candidate.proposalId, retiredAt: archivedAt } : {}),
+        ...(retiring && candidate.successorRefs && candidate.successorRefs.length > 0
+            ? { successorRefs: candidate.successorRefs }
+            : {}),
     }, "Archived derived memory for recoverable cleanup.\n");
+    // 4c (third review round): write the tombstone BEFORE moving the file — a
+    // crash in between used to leave a file already at archivedPath with no
+    // cleanup.md to explain it (unrecoverable: revert refuses on a missing
+    // tombstone, and nothing else knows this archive dir exists). Reordered,
+    // a crash here instead leaves, at worst, a tombstone describing a move
+    // that has not happened yet, with the file still at its original
+    // location — the ordinary "nothing archived yet" state every caller
+    // already handles.
     fs.writeFileSync(auditPath, auditAsset, "utf8");
     recordWrittenPath(auditPath);
+    fs.renameSync(filePath, archivedPath);
+    // #652: an archive is a delete + a create. BOTH ends are journaled so the
+    // sync stages the removal of the original alongside the archived copy.
+    recordWrittenPath(filePath);
+    recordWrittenPath(archivedPath);
     return {
         ref: candidate.ref,
-        parentRef: candidate.parentRef,
+        ...(candidate.parentRef ? { parentRef: candidate.parentRef } : {}),
         reason: candidate.reason,
         beliefState: "archived",
-        previousBeliefState: priorBeliefStateForArchive(candidate),
+        previousBeliefState,
         ...(candidate.survivorRef ? { survivorRef: candidate.survivorRef } : {}),
         originalPath,
         archivedPath: archiveRef,
         auditPath: auditRef,
         archivedAt,
+        ...(retiring ? { proposalId: candidate.proposalId, retiredAt: archivedAt } : {}),
+        ...(retiring && candidate.successorRefs && candidate.successorRefs.length > 0
+            ? { successorRefs: candidate.successorRefs }
+            : {}),
     };
 }
+/**
+ * How long a retirement's archived bytes stay on disk after `retiredAt`
+ * before the purge sweep deletes them. Git history keeps the bytes (D27;
+ * plan §5.4 "Purge").
+ */
+export const RETIRE_GRACE_DAYS = 30;
+const RETIRE_GRACE_MS = RETIRE_GRACE_DAYS * 24 * 60 * 60 * 1000;
+/** The one file every archive dir keeps forever — never deleted by the purge sweep. */
+const TOMBSTONE_FILENAME = "cleanup.md";
+const EMPTY_ARCHIVE_PURGE_RESULT = { purgedDirs: 0, purgedFiles: 0 };
+/**
+ * The purge sweep (0.9.17-alpha.9 plan §5.4, §8 step 8): deterministic, no
+ * LLM, run once at improve-run start. Deletes the archived asset bytes —
+ * never `cleanup.md` — of every retirement whose tombstone `retiredAt` is
+ * more than {@link RETIRE_GRACE_DAYS} old AND whose archived files are all
+ * git-tracked and clean at the time of the sweep (see below). Git history
+ * keeps the bytes (D27); the tombstone, and ref resolution through it
+ * (`core/asset/memory-archive.ts`), are unaffected — only the tombstone's
+ * own `originalPath` file(s) are removed.
+ *
+ * Git-backed bundles only: a bundle with no `.git` of its own has no history
+ * to fall back on, so its archive is left untouched (`akm health` reports
+ * its size instead — see `health/archive-usage.ts`). Every deleted path is
+ * journaled (`recordWrittenPath`) so the end-of-run sync commits the
+ * removal, the same way it commits the archive move itself (#652).
+ *
+ * `.git` presence is necessary but NOT sufficient: `proposal accept` only
+ * commits for a `kind: "git"` write target (`core/write-source.ts`
+ * `commitWriteTargetBoundary`), and improve's own auto-sync stages only the
+ * paths its own run wrote. A filesystem-kind bundle that merely happens to
+ * have a `.git` directory (e.g. the owner committing by hand, or an old
+ * repo that was never configured as a git source) can carry retirements
+ * that were archived but never committed — deleting those would lose the
+ * only surviving copy. So every archived file under a directory past grace
+ * is checked against `git ls-files` (tracked), `git status --porcelain
+ * -uall` (clean), and `git ls-files -v` (verifiable — an assume-unchanged
+ * or skip-worktree file hides its own edits from `git status`, so it is
+ * never trusted as clean either) — each computed ONCE per sweep, not per
+ * directory; a directory with even one untracked, modified, or
+ * unverifiable file (tombstone included) is left whole for a later sweep.
+ * If any of those three git calls itself fails (a broken submodule can fail
+ * `git status` while `git ls-files` still succeeds, or git can be missing
+ * from `PATH` entirely), the whole sweep purges nothing and warns once —
+ * an empty result from a FAILED check is never treated the same as a
+ * verified-empty one.
+ *
+ * A memory-cleanup family-prune archive (not a retire proposal's) carries no
+ * `retiredAt` in its tombstone at all, so it is never a candidate here —
+ * this sweep only ever touches retirements, never that older archive class.
+ */
+export function purgeGracedArchive(stashDir, now = new Date()) {
+    if (!isGitBackedStash(stashDir))
+        return EMPTY_ARCHIVE_PURGE_RESULT;
+    const archiveRoot = path.join(stashDir, MEMORY_ARCHIVE_REL);
+    let entries;
+    try {
+        entries = fs.readdirSync(archiveRoot, { withFileTypes: true });
+    }
+    catch {
+        return EMPTY_ARCHIVE_PURGE_RESULT; // no archive yet
+    }
+    const cutoffMs = now.getTime() - RETIRE_GRACE_MS;
+    // One git inspection per sweep, not per directory. All three sets are
+    // repo-relative POSIX paths, matched below against each archived file's
+    // own repo-relative path — a file is safe to delete only if it is in
+    // `tracked`, NOT in `dirty`, and NOT in `unverifiable`.
+    //
+    // Each of the three git calls can itself fail independently — a broken
+    // submodule can make `git status` exit nonzero while `git ls-files`
+    // succeeds, or vice versa (round-3 review, probes G8/G9). `[]` from a
+    // failed call is indistinguishable from a genuinely empty result once it
+    // is in a Set, so this checks `ok` FIRST: any failure purges nothing this
+    // sweep rather than silently trusting whichever check happened to
+    // succeed — a `dirty`/`unverifiable` set that came back empty ONLY
+    // because the call failed must never read as "nothing to protect".
+    // G10: assume-unchanged / skip-worktree files never show up as dirty even
+    // when genuinely modified — `checkGitPathSafety` treats them the same as
+    // "not tracked" below, so such a file (and its whole retirement) is left
+    // for a later sweep.
+    const gitSafety = checkGitPathSafety(stashDir, MEMORY_ARCHIVE_REL);
+    if (!gitSafety.ok) {
+        warn(`[improve] archive purge: skipped this sweep — could not determine the archive's git state at ${stashDir} ` +
+            "(git status/ls-files failed); nothing was purged.");
+        return EMPTY_ARCHIVE_PURGE_RESULT;
+    }
+    let purgedDirs = 0;
+    let purgedFiles = 0;
+    for (const entry of entries) {
+        // `Dirent.isDirectory()` reflects `lstat`, so it is false for a symlink
+        // even when the symlink points at a directory — a symlinked
+        // `archive/<name>` is skipped here, never followed (N1). Everything
+        // below only ever joins path components onto `archiveRoot` through
+        // `entry.name`/`readdirSync` results, so a purge can never reach
+        // outside `.akm/memory-cleanup/archive/`.
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(archiveRoot, entry.name);
+        let data;
+        try {
+            data = parseFrontmatter(fs.readFileSync(path.join(dir, TOMBSTONE_FILENAME), "utf8")).data;
+        }
+        catch {
+            continue; // not a tombstone dir, or unreadable — never guess
+        }
+        const retiredAt = data.retiredAt;
+        if (typeof retiredAt !== "string")
+            continue; // family-prune archive, not a retirement — out of scope
+        const retiredMs = Date.parse(retiredAt);
+        if (!Number.isFinite(retiredMs) || retiredMs >= cutoffMs)
+            continue; // "more than" the grace period — exactly at it is not enough
+        const allFiles = listFilesRecursive(dir); // tombstone included — the whole entry must be a clean, committed unit
+        const isSafeToPurge = allFiles.every((filePath) => gitSafety.isSafe(toPosix(path.relative(stashDir, filePath))));
+        if (!isSafeToPurge)
+            continue; // untracked, modified, or unverifiable entry — skip the whole directory this sweep (B1, G10)
+        let children;
+        try {
+            children = fs.readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        let purgedAnyInThisDir = false;
+        for (const child of children) {
+            if (child === TOMBSTONE_FILENAME)
+                continue;
+            const childPath = path.join(dir, child);
+            // The archived original path may be nested (e.g. `memories/sub/foo.md`
+            // under this dir) — the journal (like git) tracks FILES, so every leaf
+            // under childPath is recorded individually, not the directory itself.
+            const filesUnderChild = listFilesRecursive(childPath);
+            try {
+                fs.rmSync(childPath, { recursive: true, force: true });
+                for (const filePath of filesUnderChild)
+                    recordWrittenPath(filePath);
+                purgedFiles += filesUnderChild.length;
+                purgedAnyInThisDir = purgedAnyInThisDir || filesUnderChild.length > 0;
+            }
+            catch {
+                // Best-effort: a locked or already-gone entry is skipped, not fatal to the run.
+            }
+        }
+        if (purgedAnyInThisDir)
+            purgedDirs++;
+    }
+    return { purgedDirs, purgedFiles };
+}
+/** Every file under `target` (itself included if it's a file), for individual journaling before a recursive delete. */
+function listFilesRecursive(target) {
+    let stat;
+    try {
+        stat = fs.lstatSync(target);
+    }
+    catch {
+        return [];
+    }
+    if (!stat.isDirectory())
+        return stat.isFile() ? [target] : [];
+    let children;
+    try {
+        children = fs.readdirSync(target);
+    }
+    catch {
+        return [];
+    }
+    return children.flatMap((child) => listFilesRecursive(path.join(target, child)));
+}
 function persistBeliefStateTransition(filePath, transition) {
     mutateFrontmatter(filePath, (parsed) => {
         const nextFrontmatter = {
@@ -676,7 +928,7 @@ function resolveBeliefState(frontmatter) {
 // firstExistingRef's byRef map), so they are NORMALIZED to `memory:<name>` here.
 // On disk they arrive in either spelling — `memory:<name>` from pre-0.9.0
 // writes, or the `[<bundle>//]memories/<name>` conceptId that
-// `writeSupersededEdge`/`writeContradictEdge` persist today — and
+// `writeSupersededEdge` persists today — and
 // `parseMemoryName` accepts both. Reading only the first spelling silently
 // dropped every edge the current write path produces.
 function refArray(value) {
@@ -697,13 +949,13 @@ function refArray(value) {
     return [...refs].sort();
 }
 function buildFingerprint(title, description, tags, searchHints, body) {
-    return JSON.stringify({
+    return contentHash(JSON.stringify({
         title: normalizeSignal(title),
         description: normalizeSignal(description),
         tags: normalizeList(tags),
         searchHints: normalizeList(searchHints),
         body: normalizeBody(body),
-    });
+    }));
 }
 function normalizeBody(value) {
     return value