@remnic/core 9.65.2 → 9.65.4

package/src/connectors/codex-materialize-skills.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Skill-bundle section of the Codex materializer (issue #2369).
+ *
+ * Synthetic fixtures only — never real user data.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  ensureSentinel,
+  materializeForNamespace,
+  SENTINEL_FILE,
+} from "./codex-materialize.js";
+import { parseProcedureStepsFromBody } from "../procedural/procedure-types.js";
+import { parseSkillBundle, projectProceduresToSkills } from "../procedural/skill-projection.js";
+import type { MemoryFile } from "../types.js";
+
+function makeProcedure(id: string, title: string, updated = "2026-08-18T00:00:00Z"): MemoryFile {
+  return {
+    path: `/tmp/remnic-test/procedures/${id}.md`,
+    frontmatter: {
+      id,
+      category: "procedure",
+      created: "2026-08-18T00:00:00Z",
+      updated,
+      source: "procedure-miner",
+      confidence: 0.8,
+      confidenceTier: "implied",
+      tags: [],
+    } as MemoryFile["frontmatter"],
+    content: [title, "", "## Step 1", "", "Read the plan.", "", "## Step 2", "", "Apply the change.", ""].join("\n"),
+  };
+}
+
+function makeTempCodexHome(): { root: string; memoriesDir: string } {
+  const root = mkdtempSync(path.join(os.tmpdir(), "codex-materialize-skills-"));
+  const memoriesDir = path.join(root, "memories");
+  mkdirSync(memoriesDir, { recursive: true });
+  return { root, memoriesDir };
+}
+
+test("writes skills/<slug>/SKILL.md whose body round-trips to the same steps", () => {
+  const { root, memoriesDir } = makeTempCodexHome();
+  try {
+    ensureSentinel(memoriesDir, "synthetic-ns", new Date("2026-08-18T00:00:00Z"));
+    const memories = [makeProcedure("procedure-1", "Ship a focused change")];
+    const skills = projectProceduresToSkills(memories);
+
+    const result = materializeForNamespace("synthetic-ns", { memories, codexHome: root, skills });
+    assert.equal(result.wrote, true);
+    assert.ok(result.filesWritten.includes(path.join("skills", "ship-a-focused-change", "SKILL.md")));
+
+    const skillPath = path.join(memoriesDir, "skills", "ship-a-focused-change", "SKILL.md");
+    const parsed = parseSkillBundle(readFileSync(skillPath, "utf-8"), "ship-a-focused-change");
+    assert.ok(parsed);
+    assert.deepEqual(parsed.steps, parseProcedureStepsFromBody(memories[0].content));
+    assert.equal(parsed.provenance.memoryId, "procedure-1");
+
+    const sentinel = JSON.parse(readFileSync(path.join(memoriesDir, SENTINEL_FILE), "utf-8")) as {
+      projected_skills?: string[];
+    };
+    assert.deepEqual(sentinel.projected_skills, ["ship-a-focused-change"]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("re-running with unchanged procedures is a hash no-op", () => {
+  const { root, memoriesDir } = makeTempCodexHome();
+  try {
+    ensureSentinel(memoriesDir, "synthetic-ns", new Date("2026-08-18T00:00:00Z"));
+    const memories = [makeProcedure("procedure-1", "Ship a focused change")];
+    const skills = projectProceduresToSkills(memories);
+
+    const first = materializeForNamespace("synthetic-ns", { memories, codexHome: root, skills });
+    assert.equal(first.wrote, true);
+    const second = materializeForNamespace("synthetic-ns", { memories, codexHome: root, skills });
+    assert.equal(second.wrote, false);
+    assert.equal(second.skippedIdempotent, true);
+    assert.deepEqual(second.filesWritten, []);
+    assert.ok(existsSync(path.join(memoriesDir, "skills", "ship-a-focused-change", "SKILL.md")));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("retiring a procedure removes its projected folder and leaves hand-created folders alone", () => {
+  const { root, memoriesDir } = makeTempCodexHome();
+  try {
+    ensureSentinel(memoriesDir, "synthetic-ns", new Date("2026-08-18T00:00:00Z"));
+    const kept = makeProcedure("procedure-1", "Ship a focused change", "2026-08-18T02:00:00Z");
+    const retired = makeProcedure("procedure-2", "Rotate the token", "2026-08-18T01:00:00Z");
+
+    materializeForNamespace("synthetic-ns", {
+      memories: [kept, retired],
+      codexHome: root,
+      skills: projectProceduresToSkills([kept, retired]),
+    });
+    assert.ok(existsSync(path.join(memoriesDir, "skills", "rotate-the-token", "SKILL.md")));
+
+    // A skill folder the user curated by hand — never in projected_skills.
+    const handMade = path.join(memoriesDir, "skills", "hand-authored");
+    mkdirSync(handMade, { recursive: true });
+    writeFileSync(path.join(handMade, "SKILL.md"), "---\nname: hand-authored\n---\n\nMine.\n");
+
+    materializeForNamespace("synthetic-ns", {
+      memories: [kept],
+      codexHome: root,
+      skills: projectProceduresToSkills([kept]),
+    });
+    assert.equal(existsSync(path.join(memoriesDir, "skills", "rotate-the-token")), false);
+    assert.ok(existsSync(path.join(memoriesDir, "skills", "ship-a-focused-change", "SKILL.md")));
+    assert.ok(existsSync(path.join(handMade, "SKILL.md")));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("omitting the skills option leaves an existing skills/ directory untouched", () => {
+  const { root, memoriesDir } = makeTempCodexHome();
+  try {
+    ensureSentinel(memoriesDir, "synthetic-ns", new Date("2026-08-18T00:00:00Z"));
+    const kept = makeProcedure("procedure-1", "Ship a focused change");
+    materializeForNamespace("synthetic-ns", {
+      memories: [kept],
+      codexHome: root,
+      skills: projectProceduresToSkills([kept]),
+    });
+
+    // Gate turned off on a later run: `skills` omitted entirely.
+    const later = makeProcedure("procedure-1", "Ship a focused change", "2026-08-19T00:00:00Z");
+    materializeForNamespace("synthetic-ns", { memories: [later], codexHome: root });
+    assert.ok(existsSync(path.join(memoriesDir, "skills", "ship-a-focused-change", "SKILL.md")));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/connectors/codex-materialize.ts

@@ -48,7 +48,18 @@ import { log } from "../logger.js";
 import { readEnvVar, resolveHomeDir } from "../runtime/env.js";
 import type { MemoryFile } from "../types.js";
 import { estimateTokenCount } from "../token-estimate.js";
+import type { SkillBundle } from "../procedural/skill-projection.js";
 import { expandTildePath } from "../utils/path.js";
+import { ensureSafeManagedSubdir } from "./materialize-paths.js";
+import {
+  commitSkillFiles,
+  planSkillFiles,
+  retiredSkillsAlreadyRemoved,
+  skillFilePath,
+  skillFileRelPath,
+  stageSkillFiles,
+  type SkillFile,
+} from "./materialize-skills.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -67,6 +78,13 @@ export interface MaterializeOptions {
   rolloutRetentionDays?: number;
   /** Per-session rollout summaries to render. */
   rolloutSummaries?: RolloutSummaryInput[];
+  /**
+   * Projected procedural skill bundles (issue #2369). `undefined` leaves
+   * `skills/` untouched; an array — even an empty one — is authoritative for
+   * the slugs Remnic projected, so retired procedures get their folder
+   * removed. Folders this materializer never projected are never touched.
+   */
+  skills?: SkillBundle[];
   /** Current time, injected for deterministic tests. */
   now?: Date;
   /** Optional logger override for tests. */
@@ -115,6 +133,12 @@ interface SentinelFile {
   namespace: string;
   updated_at: string;
   content_hash: string;
+  /**
+   * Slugs under `skills/` that THIS materializer projected (issue #2369).
+   * Absent on sentinels written before skill projection existed, which reads
+   * as "we have projected nothing", so hand-created folders stay untouched.
+   */
+  projected_skills?: string[];
 }
 
 // ─── Constants ─────────────────────────────────────────────────────────────
@@ -297,6 +321,10 @@ export function materializeForNamespace(
   const destRolloutsDir = path.join(memoriesDir, ROLLOUT_SUBDIR);
   const retainedRolloutNames = new Set(rolloutFiles.map((r) => r.name));
 
+  // Skill bundles (issue #2369) — planning, ownership, and disk layout live in
+  // materialize-skills.ts.
+  const skillPlan = planSkillFiles(options.skills, existingSentinel.projected_skills ?? []);
+
   // ── Idempotence check ──────────────────────────────────────────────────
   const hash = computeContentHash({
     namespace,
@@ -304,6 +332,7 @@ export function materializeForNamespace(
     memoryMd,
     rawMemories,
     rolloutFiles,
+    skillFiles: skillPlan.files,
   });
 
   if (existingSentinel.content_hash === hash) {
@@ -318,15 +347,17 @@ export function materializeForNamespace(
       path.join(memoriesDir, "MEMORY.md"),
       path.join(memoriesDir, "raw_memories.md"),
       ...rolloutFiles.map((r) => path.join(memoriesDir, ROLLOUT_SUBDIR, r.name)),
+      ...skillPlan.files.map((s) => skillFilePath(memoriesDir, s.slug)),
     ];
     const allPresent = requiredFiles.every((f) => fs.existsSync(f));
     const rolloutsClean =
       !rolloutsSupplied ||
       rolloutDirectoryMatchesRetainedSet(
-        ensureSafeRolloutsDir(memoriesDir, destRolloutsDir),
+        ensureSafeManagedSubdir(memoriesDir, destRolloutsDir, ROLLOUT_SUBDIR),
         retainedRolloutNames,
       );
-    if (allPresent && rolloutsClean) {
+    const skillsClean = retiredSkillsAlreadyRemoved(memoriesDir, skillPlan.retiredSlugs);
+    if (allPresent && rolloutsClean && skillsClean) {
       logger.debug?.(`no-op materialization for namespace=${namespace} (hash unchanged)`);
       return {
         namespace,
@@ -403,6 +434,11 @@ export function materializeForNamespace(
     filesWritten.push(path.join(ROLLOUT_SUBDIR, rollout.name));
   }
 
+  stageSkillFiles(tmpDir, skillPlan.files);
+  for (const skill of skillPlan.files) {
+    filesWritten.push(skillFileRelPath(skill.slug));
+  }
+
   // Rename into place. Atomic per-file is sufficient — Codex reads each file
   // independently and tolerates an inconsistent in-between snapshot across
   // files for the duration of the rename loop (milliseconds).
@@ -412,7 +448,7 @@ export function materializeForNamespace(
     fs.renameSync(src, dest);
   }
 
-  const safeDestRolloutsDir = ensureSafeRolloutsDir(memoriesDir, destRolloutsDir);
+  const safeDestRolloutsDir = ensureSafeManagedSubdir(memoriesDir, destRolloutsDir, ROLLOUT_SUBDIR);
   // Only garbage-collect rollout files when the caller actually supplied a
   // `rolloutSummaries` array — otherwise we'd wipe legitimately
   // user/Codex-created recap files on every session-end run, since those
@@ -447,12 +483,17 @@ export function materializeForNamespace(
     fs.renameSync(src, dest);
   }
 
+  commitSkillFiles(memoriesDir, tmpDir, skillPlan);
+
   // Update sentinel last so a crash leaves hash mismatched → next run rewrites.
   const sentinel: SentinelFile = {
     version: MATERIALIZE_VERSION,
     namespace,
     updated_at: now.toISOString(),
     content_hash: hash,
+    projected_skills: skillPlan.supplied
+      ? skillPlan.files.map((s) => s.slug)
+      : (existingSentinel.projected_skills ?? []),
   };
   writeSentinelAtomically(sentinelPath, sentinel);
 
@@ -805,43 +846,6 @@ function rolloutDirectoryMatchesRetainedSet(
   return true;
 }
 
-function isPathInside(parent: string, child: string): boolean {
-  const relative = path.relative(parent, child);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
-function ensureSafeRolloutsDir(memoriesDir: string, rolloutsDir: string): string {
-  const memoriesReal = fs.realpathSync(memoriesDir);
-
-  try {
-    const stat = fs.lstatSync(rolloutsDir);
-    if (stat.isSymbolicLink()) {
-      throw new Error("is a symbolic link");
-    }
-    if (!stat.isDirectory()) {
-      throw new Error("is not a directory");
-    }
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
-      throw new Error(
-        `codex-materialize: unsafe ${ROLLOUT_SUBDIR} directory at ${rolloutsDir}: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    }
-    fs.mkdirSync(rolloutsDir, { recursive: true });
-  }
-
-  const rolloutsReal = fs.realpathSync(rolloutsDir);
-  if (!isPathInside(memoriesReal, rolloutsReal)) {
-    throw new Error(
-      `codex-materialize: unsafe ${ROLLOUT_SUBDIR} directory at ${rolloutsDir}: resolves outside ${memoriesDir}`,
-    );
-  }
-
-  return rolloutsDir;
-}
-
 function readSentinel(sentinelPath: string): SentinelFile | null {
   if (!fs.existsSync(sentinelPath)) return null;
   try {
@@ -857,11 +861,18 @@ function readSentinel(sentinelPath: string): SentinelFile | null {
     ) {
       throw new Error("invalid sentinel schema");
     }
+    // A sentinel written before issue #2369 has no `projected_skills`, which
+    // reads as "nothing projected" — so an unrelated skills/ folder written by
+    // a user or another tool is never treated as ours.
+    const projected = Array.isArray(parsed.projected_skills)
+      ? parsed.projected_skills.filter((slug): slug is string => typeof slug === "string")
+      : [];
     return {
       version: parsed.version,
       namespace: parsed.namespace,
       updated_at: parsed.updated_at,
       content_hash: parsed.content_hash,
+      projected_skills: projected,
     };
   } catch (err) {
     throw new Error(
@@ -1040,6 +1051,7 @@ function computeContentHash(input: {
   memoryMd: string;
   rawMemories: string;
   rolloutFiles: Array<{ name: string; body: string }>;
+  skillFiles: Array<{ slug: string; body: string }>;
 }): string {
   const hash = createHash("sha256");
   hash.update(`v${MATERIALIZE_VERSION}\n`);
@@ -1055,6 +1067,12 @@ function computeContentHash(input: {
     hash.update(`\n---rollout:${r.name}---\n`);
     hash.update(r.body);
   }
+  // Sorted by slug so call order cannot flip the hash (§26).
+  const sortedSkills = [...input.skillFiles].sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
+  for (const s of sortedSkills) {
+    hash.update(`\n---skill:${s.slug}---\n`);
+    hash.update(s.body);
+  }
   return hash.digest("hex");
 }
 

package/src/connectors/materialize-paths.ts

@@ -0,0 +1,50 @@
+/**
+ * materialize-paths.ts — containment guard for the materializer's managed
+ * sub-directories (`rollout_summaries/`, `skills/`).
+ *
+ * Extracted from codex-materialize.ts so the skills section (issue #2369) and
+ * the rollout section share ONE containment implementation instead of forking
+ * the check (rule 22).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { pathIsInside } from "../utils/path-containment.js";
+
+/**
+ * Resolve a managed sub-directory of `memoriesDir`, creating it when absent,
+ * and refuse a symlinked or escaping target. Returns the (unchanged) path so
+ * callers can use it directly.
+ */
+export function ensureSafeManagedSubdir(memoriesDir: string, subdir: string, label: string): string {
+  const memoriesReal = fs.realpathSync(memoriesDir);
+
+  try {
+    const stat = fs.lstatSync(subdir);
+    if (stat.isSymbolicLink()) {
+      throw new Error("is a symbolic link");
+    }
+    if (!stat.isDirectory()) {
+      throw new Error("is not a directory");
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw new Error(
+        `codex-materialize: unsafe ${label} directory at ${subdir}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+    fs.mkdirSync(subdir, { recursive: true });
+  }
+
+  const subdirReal = fs.realpathSync(subdir);
+  if (!pathIsInside(memoriesReal, subdirReal)) {
+    throw new Error(
+      `codex-materialize: unsafe ${label} directory at ${subdir}: resolves outside ${memoriesDir}`,
+    );
+  }
+
+  return path.normalize(subdir);
+}

package/src/connectors/materialize-skills.ts

@@ -0,0 +1,127 @@
+/**
+ * materialize-skills.ts — the `skills/` section of the Codex materializer
+ * (issue #2369).
+ *
+ * Extracted from codex-materialize.ts (which sits at its structural LOC cap)
+ * so the skill staging / commit / prune rules live in one small module. Format
+ * and slug rules stay in the host-agnostic `procedural/skill-projection.ts`;
+ * this module only decides what lands on disk.
+ *
+ * Ownership rule: Remnic removes ONLY the slugs a previous run recorded in the
+ * sentinel's `projected_skills`. A skill folder a user (or another tool)
+ * created is never in that list, so it is never a removal candidate.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { renderSkillBundle, SKILL_FILE_NAME, type SkillBundle } from "../procedural/skill-projection.js";
+import { isValidSkillSlug } from "../skills-registry.js";
+import { ensureSafeManagedSubdir } from "./materialize-paths.js";
+
+/** Sub-directory for projected procedural skill bundles. */
+export const SKILLS_SUBDIR = "skills";
+
+export interface SkillFile {
+  slug: string;
+  body: string;
+}
+
+export interface SkillPlan {
+  /** False when the caller omitted `skills` — leave `skills/` untouched. */
+  supplied: boolean;
+  /** Bundles to write, deduplicated on slug. */
+  files: SkillFile[];
+  /** Previously projected slugs this run no longer projects. */
+  retiredSlugs: string[];
+}
+
+/**
+ * Decide what this run writes and removes. `undefined` bundles mean "not our
+ * business this run"; an empty array is authoritative and retires everything
+ * previously projected.
+ */
+export function planSkillFiles(
+  bundles: SkillBundle[] | undefined,
+  previouslyProjectedSlugs: readonly string[],
+): SkillPlan {
+  const files: SkillFile[] = [];
+  const seen = new Set<string>();
+  for (const bundle of bundles ?? []) {
+    // Invalid or duplicate slugs are dropped so two bundles can never target
+    // one folder and leave the second rename with no source (§37).
+    if (!isValidSkillSlug(bundle.slug) || seen.has(bundle.slug)) continue;
+    seen.add(bundle.slug);
+    files.push({ slug: bundle.slug, body: renderSkillBundle(bundle) });
+  }
+  const previous = previouslyProjectedSlugs.filter((slug) => isValidSkillSlug(slug));
+  return {
+    supplied: bundles !== undefined,
+    files,
+    retiredSlugs: bundles === undefined ? [] : previous.filter((slug) => !seen.has(slug)),
+  };
+}
+
+/** Absolute path of a projected bundle's SKILL.md under `memoriesDir`. */
+export function skillFilePath(memoriesDir: string, slug: string): string {
+  return path.join(memoriesDir, SKILLS_SUBDIR, slug, SKILL_FILE_NAME);
+}
+
+/** Relative path recorded in `MaterializeResult.filesWritten`. */
+export function skillFileRelPath(slug: string): string {
+  return path.join(SKILLS_SUBDIR, slug, SKILL_FILE_NAME);
+}
+
+/**
+ * True when no retired folder is still on disk. Guards the idempotent
+ * early-return: a hash match is only a safe no-op if the removals also landed.
+ */
+export function retiredSkillsAlreadyRemoved(memoriesDir: string, retiredSlugs: readonly string[]): boolean {
+  return retiredSlugs.every((slug) => !fs.existsSync(path.join(memoriesDir, SKILLS_SUBDIR, slug)));
+}
+
+/** Render bundles into the per-run staging directory. */
+export function stageSkillFiles(tmpDir: string, files: readonly SkillFile[]): void {
+  for (const file of files) {
+    const stagedDir = path.join(tmpDir, SKILLS_SUBDIR, file.slug);
+    fs.mkdirSync(stagedDir, { recursive: true });
+    fs.writeFileSync(path.join(stagedDir, SKILL_FILE_NAME), file.body);
+  }
+}
+
+/**
+ * Remove retired folders, then rename each staged SKILL.md into place. Per-file
+ * renames (never directory renames) so an existing folder cannot cause
+ * ENOTEMPTY and so Codex never observes a half-written file.
+ */
+export function commitSkillFiles(memoriesDir: string, tmpDir: string, plan: SkillPlan): void {
+  if (!plan.supplied) return;
+  if (plan.files.length === 0 && plan.retiredSlugs.length === 0) return;
+
+  const skillsDir = ensureSafeManagedSubdir(memoriesDir, path.join(memoriesDir, SKILLS_SUBDIR), SKILLS_SUBDIR);
+  for (const slug of plan.retiredSlugs) {
+    const retiredDir = path.join(skillsDir, slug);
+    try {
+      // Never follow a symlink out of the managed tree while pruning.
+      if (fs.lstatSync(retiredDir).isSymbolicLink()) continue;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw err;
+    }
+    try {
+      fs.rmSync(retiredDir, { recursive: true, force: true });
+    } catch (err) {
+      throw new Error(
+        `codex-materialize: failed to remove retired skill ${slug}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+  for (const file of plan.files) {
+    const destDir = path.join(skillsDir, file.slug);
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.renameSync(
+      path.join(tmpDir, SKILLS_SUBDIR, file.slug, SKILL_FILE_NAME),
+      path.join(destDir, SKILL_FILE_NAME),
+    );
+  }
+}

package/src/contradiction/contradiction-review.ts

@@ -17,9 +17,31 @@ import type { ContradictionVerdict } from "./contradiction-judge.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
-export type ResolutionVerb = "keep-a" | "keep-b" | "merge" | "both-valid" | "needs-more-context";
-
-const VALID_RESOLUTION_VERBS: readonly ResolutionVerb[] = [
+/**
+ * Resolution verbs. The first five are contradiction-pair verbs; the last
+ * three resolve a `kind: "preference-drift"` item (issue #2371). Verb validity
+ * is per-kind — `executeResolution` rejects a cross-kind verb — but the stored
+ * union is shared so one review queue, one `review_resolve` surface, and one
+ * resolution record serve both item kinds.
+ */
+export type ResolutionVerb =
+  | "keep-a"
+  | "keep-b"
+  | "merge"
+  | "both-valid"
+  | "needs-more-context"
+  | "keep"
+  | "supersede"
+  | "archive";
+
+/** Review-item kind. Absent on every pair written before issue #2371. */
+export type ReviewItemKind = "contradiction" | "preference-drift";
+
+/** Verbs valid for a `kind: "preference-drift"` item. */
+export const PREFERENCE_DRIFT_VERBS: readonly ResolutionVerb[] = ["keep", "supersede", "archive"];
+
+/** Verbs valid for a contradiction pair. */
+export const CONTRADICTION_VERBS: readonly ResolutionVerb[] = [
   "keep-a",
   "keep-b",
   "merge",
@@ -27,11 +49,23 @@ const VALID_RESOLUTION_VERBS: readonly ResolutionVerb[] = [
   "needs-more-context",
 ];
 
+const VALID_RESOLUTION_VERBS: readonly ResolutionVerb[] = [
+  ...CONTRADICTION_VERBS,
+  ...PREFERENCE_DRIFT_VERBS,
+];
+
 export interface ContradictionPair {
   /** Deterministic pair ID: sha256(sorted(memoryIdA, memoryIdB) plus namespace when scoped). */
   pairId: string;
   /** Memory IDs (sorted). */
   memoryIds: [string, string];
+  /**
+   * Item kind (issue #2371). Absent on every pair written before drift
+   * detection existed, which reads as `"contradiction"`. A
+   * `"preference-drift"` item pairs the aging preference (first id) with the
+   * recent evidence that pointed away from it (second id).
+   */
+  kind?: ReviewItemKind;
   /** Judge verdict. */
   verdict: ContradictionVerdict;
   /** Judge rationale. */
@@ -85,8 +119,20 @@ export function isDefaultReviewNamespace(
   return !requested || requested === defaultNamespace || resolvedNamespace === defaultNamespace;
 }
 
+const TERMINAL_RESOLUTIONS: Partial<Record<ResolutionVerb, true>> = {
+  "keep-a": true,
+  "keep-b": true,
+  merge: true,
+  // Every preference-drift verb is terminal: the user has answered the "is
+  // this preference still true?" question, so the item must leave the
+  // unresolved queue and never be re-proposed by a later scan (issue #2371).
+  keep: true,
+  supersede: true,
+  archive: true,
+};
+
 function isTerminalResolution(resolution: ResolutionVerb | undefined): boolean {
-  return resolution === "keep-a" || resolution === "keep-b" || resolution === "merge";
+  return resolution !== undefined && TERMINAL_RESOLUTIONS[resolution] === true;
 }
 
 function preservesDirectResolution(resolution: ResolutionVerb | undefined): boolean {

package/src/contradiction/contradiction-scan.ts

@@ -380,8 +380,16 @@ function normalizeScanNamespace(namespace: string | undefined): string | undefin
   return trimmed ? trimmed : undefined;
 }
 
-async function resolveScanStorage(
-  deps: ScanDependencies,
+/**
+ * Resolve the namespace-scoped storage a scan must read and write through.
+ *
+ * Exported and narrowed to the fields it actually reads so sibling scans
+ * (preference drift, issue #2371) share ONE namespace resolver rather than
+ * re-deriving the read/write namespace independently — the divergence the
+ * namespace/ACL scenario matrix in AGENTS.md exists to prevent.
+ */
+export async function resolveScanStorage(
+  deps: Pick<ScanDependencies, "config" | "storage" | "storageForNamespace">,
   namespace: string | undefined,
 ): Promise<ScanStorageResolution> {
   if (!resolveNamespaceCapabilities(deps.config).namespaces) {
@@ -427,7 +435,10 @@ function isStorageManagerLike(value: unknown): value is StorageManager {
   return typeof candidate.readAllMemories === "function";
 }
 
-function fallbackResolvedNamespace(deps: ScanDependencies, namespace: string | undefined): string | undefined {
+function fallbackResolvedNamespace(
+  deps: Pick<ScanDependencies, "config">,
+  namespace: string | undefined,
+): string | undefined {
   if (namespace) return namespace;
   return resolveNamespaceCapabilities(deps.config).namespaces ? deps.config.defaultNamespace : undefined;
 }