recall-os 0.2.1 → 0.3.1

package/dist/index.js

@@ -132,8 +132,8 @@ function parseConfig(value) {
   if (!result.success) {
     throw new ConfigValidationError(
       result.error.issues.map((issue) => {
-        const path17 = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
-        return `${path17}${issue.message}`;
+        const path19 = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+        return `${path19}${issue.message}`;
       })
     );
   }
@@ -798,6 +798,54 @@ function generateAdrFile(options) {
     }
   ];
 }
+var supersedingAdrTemplate = `# {{adrId}}: {{title}}
+
+## Status
+
+Accepted
+
+## Supersedes
+
+- {{supersedesRef}}
+
+## Context
+
+What changed, and why the previous decision no longer holds?
+
+## Decision
+
+What is the new decision?
+
+## Alternatives Considered
+
+What other options were considered?
+
+## Consequences
+
+What improves, what worsens, and what risks remain?
+
+## Related Documents
+
+- PRD:
+- Architecture:
+- Security:
+- Feature:
+`;
+function generateSupersedingAdr(options) {
+  const slug = slugify(options.title);
+  const title = titleizeAdrTitle(options.title);
+  const context = createTemplateContext({
+    adrId: options.adrId,
+    slug,
+    title,
+    supersedesRef: options.supersedesRef
+  });
+  return {
+    path: path4.posix.join(options.adrDir, `${options.adrId}-${slug}.md`),
+    content: renderTemplate(supersedingAdrTemplate, context),
+    slug
+  };
+}
 function titleizeAdrTitle(title) {
   return title.trim().replace(/[-_]+/gu, " ").replace(/\s+/gu, " ").replace(/\b\w/gu, (character) => character.toUpperCase());
 }
@@ -888,8 +936,148 @@ async function loadRequiredConfig2(rootDir) {
   }
 }
 
-// src/core/generator/generate-feature.ts
+// src/commands/adr/supersede.ts
+import { readFile as readFile3, readdir as readdir3 } from "fs/promises";
 import path5 from "path";
+var AdrSupersedeError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details = []) {
+    super(message);
+    this.name = "AdrSupersedeError";
+    this.code = code;
+    this.details = details;
+  }
+};
+async function supersedeAdr(options) {
+  const oldSlug = createSlug2(options.oldName, "oldName");
+  createSlug2(options.newTitle, "newTitle");
+  const config = await loadRequiredConfig3(options.rootDir);
+  const adrDirAbsolute = resolveSafePath(options.rootDir, config.adrDir).absolutePath;
+  const old = await findAcceptedAdr(adrDirAbsolute, oldSlug);
+  const next = await getNextAdrNumber(adrDirAbsolute);
+  const oldRef = old.fileName.replace(/\.md$/u, "");
+  const superseding = generateSupersedingAdr({
+    adrDir: config.adrDir,
+    adrId: next.id,
+    title: options.newTitle,
+    supersedesRef: oldRef
+  });
+  const newRef = `${next.id}-${superseding.slug}`;
+  const markedOld = old.content.replace(
+    /(##\s+Status\r?\n\r?\n)Accepted[^\n]*/u,
+    `$1Accepted \u2014 superseded by ${newRef}`
+  );
+  const writeNew = await write2(options, superseding.path, superseding.content, options.force);
+  const oldRelative = `${config.adrDir}/${old.fileName}`;
+  const writeOld = await write2(options, oldRelative, markedOld, true);
+  return {
+    oldRef,
+    oldPath: oldRelative,
+    newRef,
+    newPath: superseding.path,
+    dryRun: options.dryRun ?? false,
+    writeResult: {
+      created: [...writeNew.created, ...writeOld.created],
+      overwritten: [...writeNew.overwritten, ...writeOld.overwritten],
+      skipped: [...writeNew.skipped, ...writeOld.skipped],
+      dryRun: options.dryRun ?? false
+    }
+  };
+}
+async function findAcceptedAdr(adrDirAbsolute, slug) {
+  const pattern = new RegExp(`^ADR-\\d{4,}-${escapeRegExp2(slug)}\\.md$`, "u");
+  let entries;
+  try {
+    entries = await readdir3(adrDirAbsolute, { withFileTypes: true });
+  } catch (error) {
+    const nodeError = error;
+    if (nodeError.code === "ENOENT") {
+      throw new AdrSupersedeError("NOT_FOUND", `No accepted ADR found for "${slug}".`);
+    }
+    throw error;
+  }
+  const match = entries.find((entry) => entry.isFile() && pattern.test(entry.name));
+  if (match === void 0) {
+    throw new AdrSupersedeError("NOT_FOUND", `No accepted ADR found for "${slug}".`, [
+      `Looked for an ADR-####-${slug}.md in the ADR directory.`
+    ]);
+  }
+  const content = await readFile3(path5.join(adrDirAbsolute, match.name), "utf8");
+  if (!/(##\s+Status\r?\n\r?\n)Accepted\b/u.test(content)) {
+    throw new AdrSupersedeError(
+      "NOT_ACCEPTED",
+      `ADR ${match.name} is not Accepted, so there is nothing to supersede.`,
+      ["Only an accepted decision can be superseded. Accept it first with `recall adr accept`."]
+    );
+  }
+  return { fileName: match.name, content };
+}
+async function write2(options, relativePath, content, force) {
+  const plan = createWritePlan({
+    rootDir: options.rootDir,
+    files: [{ path: relativePath, content }],
+    force
+  });
+  if (plan.hasErrors) {
+    throw new AdrSupersedeError(
+      "WRITE_PLAN_ERROR",
+      "ADR supersede write plan contains errors.",
+      plan.entries.filter(
+        (entry) => entry.action === "error"
+      ).map((entry) => `${entry.path}: ${entry.reason}`)
+    );
+  }
+  return executeWritePlan(plan, { dryRun: options.dryRun });
+}
+function formatAdrSupersedeResult(result) {
+  const lines = [
+    result.dryRun ? "Recall OS ADR supersede dry run complete." : "Recall OS ADR supersede complete.",
+    `Superseded: ${result.oldPath} (now marked superseded by ${result.newRef})`,
+    `New decision: ${result.newPath}`
+  ];
+  appendWriteSummary(lines, { dryRun: result.dryRun, writeResult: result.writeResult });
+  if (!result.dryRun) {
+    appendNextSteps(lines, [
+      `Fill ${result.newPath}: Context (what changed), Decision, Alternatives, Consequences.`,
+      `${result.oldRef} stays in history as superseded; update any memory that still relies on it.`,
+      "Run `recall doctor` \u2014 it flags memory that still references the superseded decision."
+    ]);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function createSlug2(name, field) {
+  const withoutPrefix = name.replace(/^ADR-(?:PROPOSED-|\d{4,}-)/iu, "");
+  try {
+    return slugify(withoutPrefix);
+  } catch (error) {
+    if (error instanceof SlugifyError) {
+      throw new AdrSupersedeError("INVALID_ADR_NAME", `Invalid ${field}: ${error.message}`);
+    }
+    throw error;
+  }
+}
+function escapeRegExp2(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+async function loadRequiredConfig3(rootDir) {
+  try {
+    return await loadConfig(rootDir);
+  } catch (error) {
+    if (error instanceof ConfigLoadError || error instanceof ConfigValidationError) {
+      throw new AdrSupersedeError(
+        "CONFIG_REQUIRED",
+        "Recall OS config not found or invalid. Run `recall init` first.",
+        [error.message]
+      );
+    }
+    throw error;
+  }
+}
+
+// src/core/generator/generate-feature.ts
+import path6 from "path";
 var featureTemplates = [
   {
     fileName: "PRD.md",
@@ -1041,7 +1229,7 @@ Pending.
 ];
 function generateFeatureFiles(options) {
   const slug = slugify(options.featureName);
-  const featureDir = path5.posix.join(options.featuresDir, `${options.featureId}-${slug}`);
+  const featureDir = path6.posix.join(options.featuresDir, `${options.featureId}-${slug}`);
   const title = titleizeFeatureName(options.featureName);
   const context = createTemplateContext({
     featureId: options.featureId,
@@ -1049,7 +1237,7 @@ function generateFeatureFiles(options) {
     title
   });
   return featureTemplates.map((template) => ({
-    path: path5.posix.join(featureDir, template.fileName),
+    path: path6.posix.join(featureDir, template.fileName),
     content: renderTemplate(template.content, context)
   }));
 }
@@ -1058,7 +1246,7 @@ function titleizeFeatureName(featureName) {
 }
 
 // src/core/naming/feature-number.ts
-import { readdir as readdir3 } from "fs/promises";
+import { readdir as readdir4 } from "fs/promises";
 var FEATURE_FOLDER_PATTERN = /^F-(\d{3,})-([a-z0-9]+(?:-[a-z0-9]+)*)$/u;
 async function getFeatureFolderForSlug(featuresDirAbsolutePath, slug) {
   const existingFolders = await readExistingFeatureFolders(featuresDirAbsolutePath);
@@ -1091,7 +1279,7 @@ function formatFeatureNumber(featureNumber) {
 async function readExistingFeatureFolders(featuresDirAbsolutePath) {
   let entries;
   try {
-    entries = await readdir3(featuresDirAbsolutePath, { withFileTypes: true });
+    entries = await readdir4(featuresDirAbsolutePath, { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -1130,7 +1318,7 @@ var FeatureCreateError = class extends Error {
 };
 async function createFeature(options) {
   const slug = createFeatureSlug(options.name);
-  const config = await loadRequiredConfig3(options.rootDir);
+  const config = await loadRequiredConfig4(options.rootDir);
   const featuresDirPath = resolveSafePath(options.rootDir, config.featuresDir);
   const featureFolder = await getFeatureFolderForSlug(featuresDirPath.absolutePath, slug);
   const files = generateFeatureFiles({
@@ -1189,7 +1377,7 @@ function createFeatureSlug(name) {
     throw error;
   }
 }
-async function loadRequiredConfig3(rootDir) {
+async function loadRequiredConfig4(rootDir) {
   try {
     return await loadConfig(rootDir);
   } catch (error) {
@@ -1230,8 +1418,8 @@ function createDefaultConfig(overrides = {}) {
 
 // src/core/adopt/inspect-repo.ts
 import { existsSync as existsSync3 } from "fs";
-import { readFile as readFile3, readdir as readdir4 } from "fs/promises";
-import path6 from "path";
+import { readFile as readFile4, readdir as readdir5 } from "fs/promises";
+import path7 from "path";
 var FRAMEWORK_SOURCES = {
   "Next.js": "package.json",
   React: "package.json",
@@ -1254,7 +1442,7 @@ var FRAMEWORK_SOURCES = {
   Flutter: "pubspec.yaml"
 };
 async function inspectRepo(rootDir) {
-  const has = (relativePath) => existsSync3(path6.join(rootDir, relativePath));
+  const has = (relativePath) => existsSync3(path7.join(rootDir, relativePath));
   const languages = /* @__PURE__ */ new Set();
   const frameworks = /* @__PURE__ */ new Set();
   const pkg = has("package.json") ? await readJson(rootDir, "package.json") : null;
@@ -1468,7 +1656,7 @@ async function findTestFile(rootDir) {
     }
     let entries;
     try {
-      entries = await readdir4(dir, { withFileTypes: true });
+      entries = await readdir5(dir, { withFileTypes: true });
     } catch {
       continue;
     }
@@ -1479,10 +1667,10 @@ async function findTestFile(rootDir) {
       }
       if (entry.isDirectory()) {
         if (!TEST_WALK_SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
-          stack.push(path6.join(dir, entry.name));
+          stack.push(path7.join(dir, entry.name));
         }
       } else if (TEST_FILE_PATTERNS.some((pattern) => pattern.test(entry.name))) {
-        return path6.relative(rootDir, path6.join(dir, entry.name));
+        return path7.relative(rootDir, path7.join(dir, entry.name));
       }
     }
   }
@@ -1506,7 +1694,7 @@ async function readJson(rootDir, relativePath) {
 }
 async function readText(rootDir, relativePath) {
   try {
-    return await readFile3(path6.join(rootDir, relativePath), "utf8");
+    return await readFile4(path7.join(rootDir, relativePath), "utf8");
   } catch {
     return "";
   }
@@ -1682,8 +1870,8 @@ function formatList2(values) {
 
 // src/core/doctor/checks/code-reference-check.ts
 import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile4, readdir as readdir5 } from "fs/promises";
-import path7 from "path";
+import { readFile as readFile5, readdir as readdir6 } from "fs/promises";
+import path8 from "path";
 var featureFolderPattern = /^F-\d{3,}-[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 var FEATURE_DOCS = ["PRD.md", "ARCHITECTURE_IMPACT.md"];
 var MODULE_DOCS = ["MODULE.md", "DECISIONS.md"];
@@ -1700,7 +1888,7 @@ async function checkCodeReferences(context) {
       continue;
     }
     for (const doc of FEATURE_DOCS) {
-      const relativePath = path7.posix.join(context.config.featuresDir, folder.name, doc);
+      const relativePath = path8.posix.join(context.config.featuresDir, folder.name, doc);
       findings.push(...await checkDoc(context.rootDir, relativePath));
     }
   }
@@ -1710,7 +1898,7 @@ async function checkCodeReferences(context) {
       continue;
     }
     for (const doc of MODULE_DOCS) {
-      const relativePath = path7.posix.join(context.config.modulesDir, folder.name, doc);
+      const relativePath = path8.posix.join(context.config.modulesDir, folder.name, doc);
       findings.push(...await checkDoc(context.rootDir, relativePath));
     }
   }
@@ -1729,7 +1917,7 @@ async function checkDoc(rootDir, relativePath) {
       continue;
     }
     seen.add(reference);
-    if (!existsSync4(path7.join(rootDir, reference))) {
+    if (!existsSync4(path8.join(rootDir, reference))) {
       findings.push({
         severity: "warning",
         check: "drift-code-reference",
@@ -1742,7 +1930,7 @@ async function checkDoc(rootDir, relativePath) {
 }
 async function readDirIfExists(rootDir, relativePath) {
   try {
-    return await readdir5(path7.join(rootDir, relativePath), { withFileTypes: true });
+    return await readdir6(path8.join(rootDir, relativePath), { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -1753,7 +1941,7 @@ async function readDirIfExists(rootDir, relativePath) {
 }
 async function readFileIfExists(rootDir, relativePath) {
   try {
-    return await readFile4(path7.join(rootDir, relativePath), "utf8");
+    return await readFile5(path8.join(rootDir, relativePath), "utf8");
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -1764,12 +1952,12 @@ async function readFileIfExists(rootDir, relativePath) {
 }
 
 // src/core/doctor/checks/config-check.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 async function checkConfig(rootDir) {
   const configPath = resolveSafePath(rootDir, CONFIG_PATH);
   let rawConfig;
   try {
-    rawConfig = await readFile5(configPath.absolutePath, "utf8");
+    rawConfig = await readFile6(configPath.absolutePath, "utf8");
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -1832,8 +2020,8 @@ async function checkConfig(rootDir) {
 }
 
 // src/core/doctor/checks/content-check.ts
-import { readFile as readFile6, readdir as readdir6 } from "fs/promises";
-import path8 from "path";
+import { readFile as readFile7, readdir as readdir7 } from "fs/promises";
+import path9 from "path";
 var featureFolderPattern2 = /^F-\d{3,}-[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 var acceptedAdrPattern = /^ADR-\d{4,}-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/u;
 var SECURITY_MODEL_PATH = "docs/20-security/SECURITY_MODEL.md";
@@ -1848,7 +2036,7 @@ async function checkContent(context) {
     (entry) => entry.isDirectory() && featureFolderPattern2.test(entry.name)
   );
   for (const folder of featureFolders) {
-    const prdPath = path8.posix.join(context.config.featuresDir, folder.name, "PRD.md");
+    const prdPath = path9.posix.join(context.config.featuresDir, folder.name, "PRD.md");
     const prd = await readFileIfExists2(context.rootDir, prdPath);
     if (prd === void 0) {
       continue;
@@ -1881,7 +2069,7 @@ async function checkContent(context) {
     findings.push(...await checkSecurityDoc(context.rootDir));
   }
   for (const folder of moduleFolders) {
-    const modulePath = path8.posix.join(context.config.modulesDir, folder.name, "MODULE.md");
+    const modulePath = path9.posix.join(context.config.modulesDir, folder.name, "MODULE.md");
     const moduleDoc = await readFileIfExists2(context.rootDir, modulePath);
     if (moduleDoc === void 0) {
       continue;
@@ -1959,7 +2147,7 @@ function getSection(content, heading) {
 }
 async function readDirIfExists2(rootDir, relativePath) {
   try {
-    return await readdir6(path8.join(rootDir, relativePath), { withFileTypes: true });
+    return await readdir7(path9.join(rootDir, relativePath), { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -1970,7 +2158,7 @@ async function readDirIfExists2(rootDir, relativePath) {
 }
 async function readFileIfExists2(rootDir, relativePath) {
   try {
-    return await readFile6(path8.join(rootDir, relativePath), "utf8");
+    return await readFile7(path9.join(rootDir, relativePath), "utf8");
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -1981,8 +2169,8 @@ async function readFileIfExists2(rootDir, relativePath) {
 }
 
 // src/core/doctor/checks/drift-check.ts
-import { readFile as readFile7, readdir as readdir7 } from "fs/promises";
-import path9 from "path";
+import { readFile as readFile8, readdir as readdir8 } from "fs/promises";
+import path10 from "path";
 var adrFilePattern = /^ADR-(\d{4,})-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/iu;
 var adrReferencePattern = /ADR-\d{4,}/giu;
 async function checkDrift(context) {
@@ -1999,12 +2187,12 @@ async function loadKnownAdrs(rootDir, adrDir) {
   const known = /* @__PURE__ */ new Map();
   const files = await readMarkdownFiles(rootDir, adrDir);
   for (const file of files) {
-    const match = adrFilePattern.exec(path9.basename(file));
+    const match = adrFilePattern.exec(path10.basename(file));
     if (match === null) {
       continue;
     }
     const id = `ADR-${match[1]}`;
-    const content = await readFile7(path9.join(rootDir, file), "utf8");
+    const content = await readFile8(path10.join(rootDir, file), "utf8");
     const accepted = sectionContains(content, "Status", /\baccepted\b/iu);
     const existing = known.get(id);
     if (existing === void 0 || !existing.accepted && accepted) {
@@ -2017,7 +2205,7 @@ async function checkReferences(rootDir, referenceDir, knownAdrs) {
   const findings = [];
   const files = await readMarkdownFiles(rootDir, referenceDir);
   for (const file of files) {
-    const content = await readFile7(path9.join(rootDir, file), "utf8");
+    const content = await readFile8(path10.join(rootDir, file), "utf8");
     const referenced = /* @__PURE__ */ new Set();
     for (const match of stripCode(content).matchAll(adrReferencePattern)) {
       referenced.add(match[0].toUpperCase());
@@ -2052,7 +2240,7 @@ async function readMarkdownFiles(rootDir, relativeDir) {
   const entries = await readDirIfExists3(rootDir, relativeDir);
   const files = [];
   for (const entry of entries) {
-    const childRelative = path9.posix.join(relativeDir, entry.name);
+    const childRelative = path10.posix.join(relativeDir, entry.name);
     if (entry.isDirectory()) {
       files.push(...await readMarkdownFiles(rootDir, childRelative));
       continue;
@@ -2085,7 +2273,7 @@ function getSection2(content, heading) {
 }
 async function readDirIfExists3(rootDir, relativePath) {
   try {
-    return await readdir7(path9.join(rootDir, relativePath), { withFileTypes: true });
+    return await readdir8(path10.join(rootDir, relativePath), { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -2096,8 +2284,8 @@ async function readDirIfExists3(rootDir, relativePath) {
 }
 
 // src/core/doctor/checks/memory-integrity-check.ts
-import { lstat as lstat2, readFile as readFile8, readdir as readdir8 } from "fs/promises";
-import path10 from "path";
+import { lstat as lstat2, readFile as readFile9, readdir as readdir9 } from "fs/promises";
+import path11 from "path";
 
 // src/core/adr/adr-sections.ts
 var REQUIRED_ADR_SECTIONS = [
@@ -2161,7 +2349,7 @@ async function checkFeatureFolders(rootDir, featuresDir) {
   );
   for (const featureFolder of featureFolders) {
     for (const requiredDoc of requiredFeatureDocs) {
-      const filePath = path10.posix.join(featuresDir, featureFolder.name, requiredDoc);
+      const filePath = path11.posix.join(featuresDir, featureFolder.name, requiredDoc);
       if (!await isFile(rootDir, filePath)) {
         findings.push({
           severity: "error",
@@ -2185,7 +2373,7 @@ async function checkModuleFolders(rootDir, modulesDir) {
   const moduleFolders = entries.filter((entry) => entry.isDirectory());
   for (const moduleFolder of moduleFolders) {
     for (const requiredDoc of requiredModuleDocs) {
-      const filePath = path10.posix.join(modulesDir, moduleFolder.name, requiredDoc);
+      const filePath = path11.posix.join(modulesDir, moduleFolder.name, requiredDoc);
       if (!await isFile(rootDir, filePath)) {
         findings.push({
           severity: "error",
@@ -2208,8 +2396,8 @@ async function checkAdrFiles(rootDir, adrDir) {
   const entries = await readDirIfExists4(rootDir, adrDir);
   const adrFiles = entries.filter((entry) => entry.isFile() && adrFilePattern2.test(entry.name));
   for (const adrFile of adrFiles) {
-    const filePath = path10.posix.join(adrDir, adrFile.name);
-    const content = await readFile8(path10.join(rootDir, filePath), "utf8");
+    const filePath = path11.posix.join(adrDir, adrFile.name);
+    const content = await readFile9(path11.join(rootDir, filePath), "utf8");
     for (const requiredSection of requiredAdrSections) {
       if (!content.includes(requiredSection)) {
         findings.push({
@@ -2230,7 +2418,7 @@ async function checkAdrFiles(rootDir, adrDir) {
 }
 async function readDirIfExists4(rootDir, relativePath) {
   try {
-    return await readdir8(path10.join(rootDir, relativePath), { withFileTypes: true });
+    return await readdir9(path11.join(rootDir, relativePath), { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -2241,7 +2429,7 @@ async function readDirIfExists4(rootDir, relativePath) {
 }
 async function isFile(rootDir, relativePath) {
   try {
-    return (await lstat2(path10.join(rootDir, relativePath))).isFile();
+    return (await lstat2(path11.join(rootDir, relativePath))).isFile();
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -2253,7 +2441,7 @@ async function isFile(rootDir, relativePath) {
 
 // src/core/doctor/checks/required-files-check.ts
 import { lstat as lstat3 } from "fs/promises";
-import path11 from "path";
+import path12 from "path";
 var rootFiles = ["AGENTS.md", "CLAUDE.md"];
 var requiredDocs = [
   "00-product/PRD.md",
@@ -2280,12 +2468,12 @@ async function checkRequiredFiles(context) {
     }
   }
   for (const relativeDocPath of requiredDocs) {
-    const filePath = path11.posix.join(docsDir, relativeDocPath);
+    const filePath = path12.posix.join(docsDir, relativeDocPath);
     if (!await isFile2(context.rootDir, filePath)) {
       findings.push(missingFile(filePath, "required-docs"));
     }
   }
-  const adrIndexPath = path11.posix.join(context.config?.adrDir ?? "docs/adrs", "README.md");
+  const adrIndexPath = path12.posix.join(context.config?.adrDir ?? "docs/adrs", "README.md");
   if (!await isFile2(context.rootDir, adrIndexPath)) {
     findings.push(missingFile(adrIndexPath, "required-docs"));
   }
@@ -2311,7 +2499,7 @@ async function checkRequiredFiles(context) {
 }
 async function isFile2(rootDir, relativePath) {
   try {
-    return (await lstat3(path11.join(rootDir, relativePath))).isFile();
+    return (await lstat3(path12.join(rootDir, relativePath))).isFile();
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -2322,7 +2510,7 @@ async function isFile2(rootDir, relativePath) {
 }
 async function isDirectory(rootDir, relativePath) {
   try {
-    return (await lstat3(path11.join(rootDir, relativePath))).isDirectory();
+    return (await lstat3(path12.join(rootDir, relativePath))).isDirectory();
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -2341,8 +2529,8 @@ function missingFile(pathValue, check) {
 }
 
 // src/core/doctor/checks/standards-check.ts
-import { lstat as lstat4, readFile as readFile9, readdir as readdir9 } from "fs/promises";
-import path12 from "path";
+import { lstat as lstat4, readFile as readFile10, readdir as readdir10 } from "fs/promises";
+import path13 from "path";
 var featureFolderPattern4 = /^F-\d{3,}-[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 var adrFilePattern3 = /^ADR-\d{4,}-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/u;
 var securitySensitivePattern = /\b(auth|authentication|authorization|secrets?|storage|networking?|telemetry|file writes?|write policy|dependencies?|mcp|ai api|cloud|runtime)\b/iu;
@@ -2362,10 +2550,10 @@ async function checkFeatureStandards(rootDir, featuresDir) {
     (entry) => entry.isDirectory() && featureFolderPattern4.test(entry.name)
   );
   for (const featureFolder of featureFolders) {
-    const featureDir = path12.posix.join(featuresDir, featureFolder.name);
-    const completionReportPath = path12.posix.join(featureDir, "COMPLETION_REPORT.md");
-    const reviewPath = path12.posix.join(featureDir, "REVIEW.md");
-    const architectureImpactPath = path12.posix.join(featureDir, "ARCHITECTURE_IMPACT.md");
+    const featureDir = path13.posix.join(featuresDir, featureFolder.name);
+    const completionReportPath = path13.posix.join(featureDir, "COMPLETION_REPORT.md");
+    const reviewPath = path13.posix.join(featureDir, "REVIEW.md");
+    const architectureImpactPath = path13.posix.join(featureDir, "ARCHITECTURE_IMPACT.md");
     const completionReport = await readFileIfExists3(rootDir, completionReportPath);
     const review = await readFileIfExists3(rootDir, reviewPath);
     const architectureImpact = await readFileIfExists3(rootDir, architectureImpactPath);
@@ -2415,8 +2603,8 @@ async function checkAdrStandards(rootDir, adrDir) {
   const entries = await readDirIfExists5(rootDir, adrDir);
   const adrFiles = entries.filter((entry) => entry.isFile() && adrFilePattern3.test(entry.name));
   for (const adrFile of adrFiles) {
-    const adrPath = path12.posix.join(adrDir, adrFile.name);
-    const content = await readFile9(path12.join(rootDir, adrPath), "utf8");
+    const adrPath = path13.posix.join(adrDir, adrFile.name);
+    const content = await readFile10(path13.join(rootDir, adrPath), "utf8");
     const isAccepted = sectionContains2(content, "Status", /\baccepted\b/iu);
     if (!hasMeaningfulSection(content, "Consequences")) {
       findings.push({
@@ -2500,7 +2688,7 @@ function isPlaceholder(value) {
 }
 async function readDirIfExists5(rootDir, relativePath) {
   try {
-    return await readdir9(path12.join(rootDir, relativePath), { withFileTypes: true });
+    return await readdir10(path13.join(rootDir, relativePath), { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -2514,7 +2702,7 @@ async function readFileIfExists3(rootDir, relativePath) {
     if (!await isFile3(rootDir, relativePath)) {
       return void 0;
     }
-    return await readFile9(path12.join(rootDir, relativePath), "utf8");
+    return await readFile10(path13.join(rootDir, relativePath), "utf8");
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -2525,7 +2713,7 @@ async function readFileIfExists3(rootDir, relativePath) {
 }
 async function isFile3(rootDir, relativePath) {
   try {
-    return (await lstat4(path12.join(rootDir, relativePath))).isFile();
+    return (await lstat4(path13.join(rootDir, relativePath))).isFile();
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -2535,6 +2723,110 @@ async function isFile3(rootDir, relativePath) {
   }
 }
 
+// src/core/doctor/checks/superseded-check.ts
+import { readFile as readFile11, readdir as readdir11 } from "fs/promises";
+import path14 from "path";
+var adrFilePattern4 = /^ADR-(\d{4,})-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/iu;
+var adrReferencePattern2 = /ADR-\d{4,}/giu;
+async function checkSuperseded(context) {
+  if (context.config === void 0) {
+    return [];
+  }
+  const supersededIds = await loadSupersededAdrIds(context.rootDir, context.config.adrDir);
+  if (supersededIds.size === 0) {
+    return [];
+  }
+  const findings = [];
+  findings.push(
+    ...await checkReferences2(context.rootDir, context.config.featuresDir, supersededIds)
+  );
+  findings.push(
+    ...await checkReferences2(context.rootDir, context.config.modulesDir, supersededIds)
+  );
+  return findings;
+}
+async function loadSupersededAdrIds(rootDir, adrDir) {
+  const superseded = /* @__PURE__ */ new Set();
+  const files = await readMarkdownFiles2(rootDir, adrDir);
+  for (const file of files) {
+    const match = adrFilePattern4.exec(path14.basename(file));
+    if (match === null) {
+      continue;
+    }
+    const content = await readFile11(path14.join(rootDir, file), "utf8");
+    if (statusContains(content, /superseded\s+by/iu)) {
+      superseded.add(`ADR-${match[1]}`.toUpperCase());
+    }
+  }
+  return superseded;
+}
+async function checkReferences2(rootDir, referenceDir, supersededIds) {
+  const findings = [];
+  const files = await readMarkdownFiles2(rootDir, referenceDir);
+  for (const file of files) {
+    const content = await readFile11(path14.join(rootDir, file), "utf8");
+    const referenced = /* @__PURE__ */ new Set();
+    for (const match of stripCode2(content).matchAll(adrReferencePattern2)) {
+      referenced.add(match[0].toUpperCase());
+    }
+    for (const id of referenced) {
+      if (supersededIds.has(id)) {
+        findings.push({
+          severity: "warning",
+          check: "superseded-reference",
+          message: `Repository memory references ${id}, which has been superseded \u2014 update it to the current decision.`,
+          path: file
+        });
+      }
+    }
+  }
+  return findings;
+}
+function statusContains(content, pattern) {
+  const lines = content.split(/\r?\n/u);
+  const startIndex = lines.findIndex((line) => line.trim().toLowerCase() === "## status");
+  if (startIndex === -1) {
+    return false;
+  }
+  const body = [];
+  for (let index = startIndex + 1; index < lines.length; index += 1) {
+    if (/^##\s+/u.test(lines[index])) {
+      break;
+    }
+    body.push(lines[index]);
+  }
+  return pattern.test(body.join("\n"));
+}
+function stripCode2(content) {
+  return content.replace(/```[\s\S]*?```/gu, " ").replace(/~~~[\s\S]*?~~~/gu, " ").replace(/`[^`]*`/gu, " ");
+}
+async function readMarkdownFiles2(rootDir, relativeDir) {
+  const entries = await readDirIfExists6(rootDir, relativeDir);
+  const files = [];
+  for (const entry of entries) {
+    const childRelative = path14.posix.join(relativeDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await readMarkdownFiles2(rootDir, childRelative));
+      continue;
+    }
+    if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+      files.push(childRelative);
+    }
+  }
+  return files;
+}
+async function readDirIfExists6(rootDir, relativePath) {
+  try {
+    return await readdir11(path14.join(rootDir, relativePath), { withFileTypes: true });
+  } catch (error) {
+    const nodeError = error;
+    if (nodeError.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+
 // src/core/doctor/doctor-check.ts
 async function runDoctor(rootDir) {
   const findings = [];
@@ -2551,6 +2843,7 @@ async function runDoctor(rootDir) {
     findings.push(...await checkDrift(context));
     findings.push(...await checkContent(context));
     findings.push(...await checkCodeReferences(context));
+    findings.push(...await checkSuperseded(context));
   }
   return createDoctorReport(findings);
 }
@@ -2628,10 +2921,10 @@ function formatDoctorResult(result) {
 
 // src/commands/init.ts
 import { existsSync as existsSync6 } from "fs";
-import path15 from "path";
+import path17 from "path";
 
 // src/core/generator/generate-init.ts
-import path13 from "path";
+import path15 from "path";
 var neutralTemplates = [
   {
     path: "AGENTS.md",
@@ -2650,6 +2943,32 @@ Required reading:
 - \`docs/60-engineering/ENGINEERING_STANDARDS.md\`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## Recall OS commands
+
+This repository is maintained with the Recall OS CLI. Use these commands yourself as you work \u2014 do not
+ask the human to run them, and do not search the web for them (this is a project-local tool):
+
+- \`recall doctor\` \u2014 validate repository memory; run it before claiming any work is complete.
+- \`recall feature create <name>\` \u2014 scaffold feature memory before non-trivial feature work.
+- \`recall adr create <title>\` \u2014 propose a decision; \`recall adr accept <name>\` accepts it.
+- \`recall adr supersede <old> <new-title>\` \u2014 record a changed decision (never overwrite an accepted ADR).
+- \`recall module create <name>\` \u2014 scaffold module memory for a new responsibility boundary.
+- \`recall mcp add <server>\` \u2014 capture an MCP tool's context into memory, offline.
+
+Full command reference: \`docs/ai/RECALL_COMMANDS.md\`.
+
+## Changing an accepted decision
+
+Before changing anything an accepted ADR governs (framework, database, auth, API shape, and similar):
+
+1. Check \`docs/adrs/\` for an accepted ADR that covers it.
+2. If your change contradicts one, stop and confirm with a human first \u2014 do not silently change the
+   code and leave the ADR saying the opposite.
+3. Record the change as a new decision with \`recall adr supersede <old> <new-title>\`. That supersedes
+   the old ADR instead of overwriting history, so the reasoning stays auditable.
+
+Repository memory is only trustworthy if decisions change through this trail, not silently.
 `
   },
   {
@@ -2686,10 +3005,17 @@ Before non-trivial work:
 - Read \`AGENTS.md\` and the docs it routes to.
 - Accepted decisions live in \`docs/adrs/\`; module memory lives in \`docs/30-modules/\`.
 - If an instruction conflicts with accepted repository memory, stop and report the conflict.
+- Before changing what an accepted ADR governs, confirm with a human and record it with
+  \`recall adr supersede <old> <new-title>\` \u2014 never silently contradict an accepted decision.
 
 Source-of-truth order: accepted ADRs and repository decisions, then architecture docs, engineering
 standards, the current PRD, security and testing docs, module docs, feature plans, then chat history.
 
+Recall OS commands \u2014 use these yourself (do not web-search this project-local CLI): \`recall doctor\`,
+\`recall feature create <name>\`, \`recall adr create <title>\` then \`recall adr accept <name>\`,
+\`recall adr supersede <old> <new-title>\`, \`recall module create <name>\`, \`recall mcp add <server>\`.
+Full reference: \`docs/ai/RECALL_COMMANDS.md\`.
+
 Before claiming work is complete, run \`recall doctor\` and fix reported errors.
 `
   },
@@ -2894,6 +3220,15 @@ Baseline rules:
 AI agents must follow repository memory over model preference.
 
 If a request conflicts with accepted repository memory or engineering standards, stop and report the conflict.
+
+## Changing an accepted decision
+
+When work would change something an accepted ADR governs:
+
+1. Find the accepted ADR in \`docs/adrs/\` that covers it.
+2. If the change contradicts it, stop and confirm with a human before changing the code.
+3. Record the new decision with \`recall adr supersede <old> <new-title>\` so the old ADR is marked
+   superseded and the reasoning is preserved, instead of silently editing or contradicting it.
 `
   },
   {
@@ -3027,6 +3362,17 @@ Options:
 - \`--dry-run\`: show planned writes without writing files.
 - \`--force\`: overwrite existing files explicitly.
 
+### \`recall adr supersede <old> <new-title>\`
+
+Record a changed decision. Marks an accepted ADR as \`Accepted \u2014 superseded by ADR-####\` and creates a
+new accepted ADR that declares what it supersedes, so the reasoning trail stays auditable instead of
+being overwritten. Doctor then warns about any memory still referencing the superseded decision.
+
+Options:
+
+- \`--dry-run\`: show planned writes without writing files.
+- \`--force\`: overwrite existing files explicitly.
+
 ### \`recall module create <name>\`
 
 Create module memory docs under the configured modules directory.
@@ -3042,7 +3388,8 @@ Check whether repository memory is structurally healthy enough for AI-assisted w
 engineering evidence is present, and whether memory references decisions that exist and are accepted.
 
 Doctor also runs deterministic drift checks: feature or module memory that references a missing ADR
-is an error, and memory that references a not-yet-accepted ADR is a warning.
+is an error, memory that references a not-yet-accepted ADR is a warning, and memory that still
+references a superseded decision is a warning.
 
 Exit codes:
 
@@ -3129,7 +3476,7 @@ jobs:
   }
 ];
 function generateInitFiles(options) {
-  const repositoryName = path13.basename(path13.resolve(options.rootDir)) || "repository";
+  const repositoryName = path15.basename(path15.resolve(options.rootDir)) || "repository";
   const context = createTemplateContext({ repositoryName });
   const files = neutralTemplates.map((template) => ({
     path: template.path,
@@ -3156,17 +3503,17 @@ function generatePresetFiles(preset) {
 
 // src/core/hooks/detect-gates.ts
 import { existsSync as existsSync5 } from "fs";
-import { readFile as readFile10 } from "fs/promises";
-import path14 from "path";
+import { readFile as readFile12 } from "fs/promises";
+import path16 from "path";
 var KNOWN_SCRIPTS = ["test", "typecheck", "lint"];
 async function detectPreCommitGates(rootDir) {
-  const packageJsonPath = path14.join(rootDir, "package.json");
+  const packageJsonPath = path16.join(rootDir, "package.json");
   if (!existsSync5(packageJsonPath)) {
     return [];
   }
   let scripts;
   try {
-    const raw = await readFile10(packageJsonPath, "utf8");
+    const raw = await readFile12(packageJsonPath, "utf8");
     const parsed = JSON.parse(raw);
     scripts = parsed.scripts ?? {};
   } catch {
@@ -3181,10 +3528,10 @@ async function detectPreCommitGates(rootDir) {
   );
 }
 function detectPackageManager2(rootDir) {
-  if (existsSync5(path14.join(rootDir, "pnpm-lock.yaml"))) {
+  if (existsSync5(path16.join(rootDir, "pnpm-lock.yaml"))) {
     return "pnpm";
   }
-  if (existsSync5(path14.join(rootDir, "yarn.lock"))) {
+  if (existsSync5(path16.join(rootDir, "yarn.lock"))) {
     return "yarn";
   }
   return "npm";
@@ -3204,7 +3551,7 @@ function renderSessionStartHook() {
 adrs=$(ls docs/adrs/ADR-*.md 2>/dev/null | sed 's|.*/||;s|\\.md$||' | tr '\\n' ' ')
 modules=$(ls -d docs/30-modules/*/ 2>/dev/null | sed 's|docs/30-modules/||;s|/$||' | tr '\\n' ' ')
 
-context="Recall OS repository memory is the source of truth over chat history. Before non-trivial work, read AGENTS.md and the docs it routes to; repository rules override model preference. Accepted ADRs (docs/adrs/): \${adrs:-none yet}. Modules (docs/30-modules/): \${modules:-none yet}. Run 'recall doctor' before claiming work complete."
+context="Recall OS repository memory is the source of truth over chat history. Before non-trivial work, read AGENTS.md and the docs it routes to; repository rules override model preference. Accepted ADRs (docs/adrs/): \${adrs:-none yet}. Modules (docs/30-modules/): \${modules:-none yet}. Use the Recall OS CLI commands listed in AGENTS.md (recall feature/adr/module create, recall adr accept and supersede, recall doctor) yourself; do not web-search them. Run 'recall doctor' before claiming work complete."
 
 printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\\n' "$context"
 `;
@@ -4689,8 +5036,8 @@ function parsePreset(value) {
   if (!result.success) {
     throw new PresetValidationError(
       result.error.issues.map((issue) => {
-        const path17 = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
-        return `${path17}${issue.message}`;
+        const path19 = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+        return `${path19}${issue.message}`;
       })
     );
   }
@@ -5379,7 +5726,7 @@ var InitError = class extends Error {
   }
 };
 async function initProject(options) {
-  if (options.force === true && options.reinit !== true && existsSync6(path15.join(options.rootDir, CONFIG_PATH))) {
+  if (options.force === true && options.reinit !== true && existsSync6(path17.join(options.rootDir, CONFIG_PATH))) {
     throw new InitError(
       "EXISTING_INSTALLATION",
       "Refusing to re-initialize an existing Recall OS installation.",
@@ -5743,7 +6090,7 @@ async function loadConfigOrDefault2(rootDir) {
 }
 
 // src/core/generator/generate-module.ts
-import path16 from "path";
+import path18 from "path";
 var moduleTemplates = [
   {
     fileName: "MODULE.md",
@@ -5816,14 +6163,14 @@ Record durable module decisions here.
 ];
 function generateModuleFiles(options) {
   const slug = slugify(options.moduleName);
-  const moduleDir = path16.posix.join(options.modulesDir, slug);
+  const moduleDir = path18.posix.join(options.modulesDir, slug);
   const title = titleizeModuleName(options.moduleName);
   const context = createTemplateContext({
     slug,
     title
   });
   return moduleTemplates.map((template) => ({
-    path: path16.posix.join(moduleDir, template.fileName),
+    path: path18.posix.join(moduleDir, template.fileName),
     content: renderTemplate(template.content, context)
   }));
 }
@@ -5844,7 +6191,7 @@ var ModuleCreateError = class extends Error {
 };
 async function createModule(options) {
   const slug = createModuleSlug(options.name);
-  const config = await loadRequiredConfig4(options.rootDir);
+  const config = await loadRequiredConfig5(options.rootDir);
   const files = generateModuleFiles({
     modulesDir: config.modulesDir,
     moduleName: options.name
@@ -5898,7 +6245,7 @@ function createModuleSlug(name) {
     throw error;
   }
 }
-async function loadRequiredConfig4(rootDir) {
+async function loadRequiredConfig5(rootDir) {
   try {
     return await loadConfig(rootDir);
   } catch (error) {
@@ -6072,6 +6419,20 @@ function createCliProgram(io = {}, state = { exitCode: 0 }) {
     });
     stdout.write(formatAdrAcceptResult(result));
   });
+  adrCommand.command("supersede").description(
+    "Record a changed decision: mark an accepted ADR superseded by a new accepted ADR."
+  ).argument("<old>", "Accepted ADR name or slug being superseded, e.g. database-postgres.").argument("<new-title>", "Title of the new decision that replaces it.").option("--dry-run", "Show planned writes without writing files.").option("--force", "Overwrite existing files explicitly.").action(
+    async (oldName, newTitle, options) => {
+      const result = await supersedeAdr({
+        rootDir: cwd,
+        oldName,
+        newTitle,
+        dryRun: options.dryRun,
+        force: options.force
+      });
+      stdout.write(formatAdrSupersedeResult(result));
+    }
+  );
   const moduleCommand = program.command("module").description("Manage Recall OS module memory.");
   moduleCommand.command("create").description("Create module memory docs.").argument("<name>", "Module name.").option("--dry-run", "Show planned writes without writing files.").option("--force", "Overwrite existing files explicitly.").action(async (name, options) => {
     const result = await createModule({
@@ -6165,6 +6526,15 @@ async function main(argv = process.argv.slice(2), io = {}) {
 `);
       for (const detail of error.details) {
         stderr.write(`- ${detail}
+`);
+      }
+      return 1;
+    }
+    if (error instanceof AdrSupersedeError) {
+      stderr.write(`${error.message}
+`);
+      for (const detail of error.details) {
+        stderr.write(`- ${detail}
 `);
       }
       return 1;