recall-os 0.2.0 → 0.3.0

package/dist/cli.js

@@ -134,8 +134,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}`;
       })
     );
   }
@@ -800,6 +800,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());
 }
@@ -890,8 +938,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",
@@ -1043,7 +1231,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,
@@ -1051,7 +1239,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)
   }));
 }
@@ -1060,7 +1248,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);
@@ -1093,7 +1281,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") {
@@ -1132,7 +1320,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({
@@ -1191,7 +1379,7 @@ function createFeatureSlug(name) {
     throw error;
   }
 }
-async function loadRequiredConfig3(rootDir) {
+async function loadRequiredConfig4(rootDir) {
   try {
     return await loadConfig(rootDir);
   } catch (error) {
@@ -1230,113 +1418,33 @@ function createDefaultConfig(overrides = {}) {
   });
 }
 
-// src/core/adopt/generate-adoption.ts
-var ADOPTION_REPORT_PATH = "docs/adopt/ADOPTION_REPORT.md";
-function generateAdoptionFiles(options) {
-  const files = [
-    {
-      path: ADOPTION_REPORT_PATH,
-      content: renderReport(options.adrDir, options.signals)
-    }
-  ];
-  for (const framework of options.signals.frameworks) {
-    files.push({
-      path: `${options.adrDir}/proposed/ADR-PROPOSED-adopt-${frameworkSlug(framework)}.md`,
-      content: renderProposedAdr(framework)
-    });
-  }
-  return files;
-}
-function renderReport(adrDir, signals) {
-  return `# Adoption Report
-
-## Status
-
-Proposed. Everything below is inferred from this repository and requires human review. Nothing here
-is accepted repository memory until you accept it.
-
-## Detected Signals
-
-- Languages: ${formatList(signals.languages)}
-- Package manager: ${signals.packageManager ?? "none detected"}
-- Frameworks: ${formatList(signals.frameworks)}
-- Tests present: ${formatBool(signals.hasTests)}
-- README present: ${formatBool(signals.hasReadme)}
-- Docs folder present: ${formatBool(signals.hasDocs)}
-
-## Proposed Decisions
-
-${renderProposedDecisions(adrDir, signals)}
-
-## Review Checklist
-
-- [ ] Confirm the detected languages and package manager.
-- [ ] Accept or reject each proposed framework ADR under \`${adrDir}/proposed/\`.
-- [ ] Run \`recall init\` to establish neutral repository memory if it does not exist yet.
-- [ ] Record any decision you accept with \`recall adr create\` or by accepting the proposed ADR.
-
-## Notes
-
-This report was produced by \`recall adopt\` through read-only inspection of manifest and marker
-files. No repository code was executed and no decision was accepted automatically.
-`;
-}
-function renderProposedDecisions(adrDir, signals) {
-  if (signals.frameworks.length === 0) {
-    return "- No framework decisions were inferred. Add decisions with `recall adr create` as needed.";
-  }
-  return signals.frameworks.map(
-    (framework) => `- Proposed: record **${framework}** as an architecture decision (see \`${adrDir}/proposed/ADR-PROPOSED-adopt-${frameworkSlug(framework)}.md\`). Requires review.`
-  ).join("\n");
-}
-function renderProposedAdr(framework) {
-  return `# Proposed ADR: Use ${framework}
-
-## Status
-
-Proposed
-
-## Context
-
-\`recall adopt\` detected ${framework} in this repository through read-only inspection.
-
-## Decision
-
-Consider recording ${framework} as an accepted architecture decision. This is proposed by adoption
-and is not accepted until a human reviews and accepts it.
-
-## Alternatives Considered
-
-- Record a different framework.
-- Leave the decision unrecorded for now.
-
-## Consequences
-
-- Captures a framework already in use as reviewable repository memory.
-- Requires explicit human acceptance before it becomes repository truth.
-
-## Related Documents
-
-- \`docs/10-architecture/ARCHITECTURE.md\` \u2014 record the accepted architecture here once promoted.
-- The adoption report generated alongside this proposal.
-`;
-}
-function frameworkSlug(framework) {
-  return framework.toLowerCase().replace(/\./gu, "").replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");
-}
-function formatList(values) {
-  return values.length > 0 ? values.join(", ") : "none detected";
-}
-function formatBool(value) {
-  return value ? "yes" : "no";
-}
-
 // src/core/adopt/inspect-repo.ts
 import { existsSync as existsSync3 } from "fs";
-import { readFile as readFile3 } 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",
+  NestJS: "package.json",
+  Express: "package.json",
+  FastAPI: "pyproject.toml / requirements.txt",
+  Flask: "pyproject.toml / requirements.txt",
+  Django: "pyproject.toml / requirements.txt",
+  Gin: "go.mod",
+  Echo: "go.mod",
+  Fiber: "go.mod",
+  Chi: "go.mod",
+  "Spring Boot": "pom.xml / build.gradle",
+  "Actix Web": "Cargo.toml",
+  Axum: "Cargo.toml",
+  Rocket: "Cargo.toml",
+  Laravel: "composer.json",
+  Symfony: "composer.json",
+  "Ruby on Rails": "Gemfile",
+  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;
@@ -1368,6 +1476,22 @@ async function inspectRepo(rootDir) {
     languages.add("Dart");
     frameworks.add("Flutter");
   }
+  if (has("composer.json")) {
+    languages.add("PHP");
+    const composer = (await readText(rootDir, "composer.json")).toLowerCase();
+    if (composer.includes("laravel/framework")) {
+      frameworks.add("Laravel");
+    } else if (composer.includes("symfony/")) {
+      frameworks.add("Symfony");
+    }
+  }
+  if (has("Gemfile")) {
+    languages.add("Ruby");
+    const gemfile = (await readText(rootDir, "Gemfile")).toLowerCase();
+    if (gemfile.includes("rails")) {
+      frameworks.add("Ruby on Rails");
+    }
+  }
   const deps = collectDependencies(pkg);
   if ("next" in deps) {
     frameworks.add("Next.js");
@@ -1413,25 +1537,147 @@ async function inspectRepo(rootDir) {
       frameworks.add("Rocket");
     }
   }
-  let packageManager = null;
-  if (has("pnpm-lock.yaml")) {
-    packageManager = "pnpm";
-  } else if (has("yarn.lock")) {
-    packageManager = "yarn";
-  } else if (has("package-lock.json")) {
-    packageManager = "npm";
-  }
+  const [packageManager, packageManagerSource] = detectPackageManager(has);
   const scripts = pkg !== null && isRecord(pkg.scripts) ? pkg.scripts : {};
-  const hasTests = "test" in scripts || has("test") || has("tests") || has("__tests__") || has("pytest.ini") || python.includes("pytest");
+  const testsEvidence = await detectTestsEvidence(rootDir, has, "test" in scripts, python);
   return {
     languages: [...languages],
     packageManager,
+    packageManagerSource,
     frameworks: [...frameworks],
-    hasTests,
+    hasTests: testsEvidence !== null,
+    testsEvidence,
     hasReadme: has("README.md") || has("README"),
     hasDocs: has("docs")
   };
 }
+function summarizeSignals(signals) {
+  const lines = [];
+  lines.push(`- Languages: ${formatList(signals.languages)}`);
+  lines.push(
+    signals.packageManager === null ? "- Package manager: none detected" : `- Package manager: ${signals.packageManager}${signals.packageManagerSource === null ? "" : ` (from \`${signals.packageManagerSource}\`)`}`
+  );
+  if (signals.frameworks.length === 0) {
+    lines.push("- Frameworks: none detected");
+  } else {
+    const withSource = signals.frameworks.map((framework) => {
+      const source = FRAMEWORK_SOURCES[framework];
+      return source === void 0 ? framework : `${framework} (from \`${source}\`)`;
+    });
+    lines.push(`- Frameworks: ${withSource.join(", ")}`);
+  }
+  lines.push(
+    signals.testsEvidence === null ? "- Tests: none detected \u2014 if tests exist, point Recall at them by correcting this report" : `- Tests: detected via ${signals.testsEvidence}`
+  );
+  lines.push(`- README present: ${signals.hasReadme ? "yes" : "no"}`);
+  lines.push(`- Docs folder present: ${signals.hasDocs ? "yes" : "no"}`);
+  return lines;
+}
+function formatList(values) {
+  return values.length === 0 ? "none detected" : values.join(", ");
+}
+function detectPackageManager(has) {
+  const candidates = [
+    [has("go.mod"), "Go modules", "go.mod"],
+    [has("Cargo.toml"), "Cargo", "Cargo.toml"],
+    [has("pom.xml"), "Maven", "pom.xml"],
+    [has("build.gradle"), "Gradle", "build.gradle"],
+    [has("build.gradle.kts"), "Gradle", "build.gradle.kts"],
+    [has("composer.json"), "Composer", "composer.json"],
+    [has("Gemfile"), "Bundler", "Gemfile"],
+    [has("Package.swift"), "Swift Package Manager", "Package.swift"],
+    [has("pubspec.yaml"), "pub", "pubspec.yaml"],
+    [has("uv.lock"), "uv", "uv.lock"],
+    [has("poetry.lock"), "Poetry", "poetry.lock"],
+    [has("requirements.txt"), "pip", "requirements.txt"],
+    [has("pyproject.toml"), "pip", "pyproject.toml"],
+    [has("pnpm-lock.yaml"), "pnpm", "pnpm-lock.yaml"],
+    [has("yarn.lock"), "yarn", "yarn.lock"],
+    [has("package-lock.json"), "npm", "package-lock.json"],
+    [has("package.json"), "npm", "package.json"]
+  ];
+  for (const [present, name, source] of candidates) {
+    if (present) {
+      return [name, source];
+    }
+  }
+  return [null, null];
+}
+async function detectTestsEvidence(rootDir, has, hasTestScript, pythonText) {
+  if (has("tests")) {
+    return "`tests/` directory";
+  }
+  if (has("test")) {
+    return "`test/` directory";
+  }
+  if (has("__tests__")) {
+    return "`__tests__/` directory";
+  }
+  if (has("pytest.ini") || pythonText.includes("pytest")) {
+    return "pytest configuration";
+  }
+  if (has("phpunit.xml") || has("phpunit.xml.dist")) {
+    return "PHPUnit configuration";
+  }
+  if (hasTestScript) {
+    return '`"test"` script in package.json';
+  }
+  const testFile = await findTestFile(rootDir);
+  if (testFile !== null) {
+    return `\`${testFile}\``;
+  }
+  return null;
+}
+var TEST_FILE_PATTERNS = [
+  /_test\.go$/u,
+  /\.(test|spec)\.[cm]?[jt]sx?$/u,
+  /^test_.+\.py$/u,
+  /_test\.py$/u,
+  /.+Tests?\.(java|kt)$/u,
+  /.+Test\.php$/u,
+  /_spec\.rb$/u,
+  /_test\.rb$/u
+];
+var TEST_WALK_SKIP_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  "vendor",
+  "dist",
+  "build",
+  "target",
+  "coverage",
+  "Pods",
+  "__pycache__"
+]);
+async function findTestFile(rootDir) {
+  let budget = 4e3;
+  const stack = [rootDir];
+  while (stack.length > 0 && budget > 0) {
+    const dir = stack.pop();
+    if (dir === void 0) {
+      break;
+    }
+    let entries;
+    try {
+      entries = await readdir5(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      budget -= 1;
+      if (budget <= 0) {
+        break;
+      }
+      if (entry.isDirectory()) {
+        if (!TEST_WALK_SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+          stack.push(path7.join(dir, entry.name));
+        }
+      } else if (TEST_FILE_PATTERNS.some((pattern) => pattern.test(entry.name))) {
+        return path7.relative(rootDir, path7.join(dir, entry.name));
+      }
+    }
+  }
+  return null;
+}
 function collectDependencies(pkg) {
   if (pkg === null) {
     return {};
@@ -1450,7 +1696,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 "";
   }
@@ -1459,6 +1705,100 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// src/core/adopt/generate-adoption.ts
+var ADOPTION_REPORT_PATH = "docs/adopt/ADOPTION_REPORT.md";
+function generateAdoptionFiles(options) {
+  const files = [
+    {
+      path: ADOPTION_REPORT_PATH,
+      content: renderReport(options.adrDir, options.signals)
+    }
+  ];
+  for (const framework of options.signals.frameworks) {
+    files.push({
+      path: `${options.adrDir}/proposed/ADR-PROPOSED-adopt-${frameworkSlug(framework)}.md`,
+      content: renderProposedAdr(framework)
+    });
+  }
+  return files;
+}
+function renderReport(adrDir, signals) {
+  return `# Adoption Report
+
+## Status
+
+Proposed. Everything below is inferred from this repository and requires human review. Nothing here
+is accepted repository memory until you accept it.
+
+## Detected Signals
+
+Each signal notes the file it was inferred from. If one is wrong, correct the source or edit this
+report \u2014 nothing here is accepted.
+
+${summarizeSignals(signals).join("\n")}
+
+## Proposed Decisions
+
+${renderProposedDecisions(adrDir, signals)}
+
+## Review Checklist
+
+- [ ] Confirm the detected languages and package manager (and the source each was read from).
+- [ ] Confirm where tests were detected, or point Recall at the right location if it is wrong.
+- [ ] Accept or reject each proposed framework ADR under \`${adrDir}/proposed/\`.
+- [ ] Run \`recall init\` to establish neutral repository memory if it does not exist yet.
+- [ ] Record any decision you accept with \`recall adr create\` or by accepting the proposed ADR.
+
+## Notes
+
+This report was produced by \`recall adopt\` through read-only inspection of manifest and marker
+files. No repository code was executed and no decision was accepted automatically.
+`;
+}
+function renderProposedDecisions(adrDir, signals) {
+  if (signals.frameworks.length === 0) {
+    return "- No framework decisions were inferred. Add decisions with `recall adr create` as needed.";
+  }
+  return signals.frameworks.map(
+    (framework) => `- Proposed: record **${framework}** as an architecture decision (see \`${adrDir}/proposed/ADR-PROPOSED-adopt-${frameworkSlug(framework)}.md\`). Requires review.`
+  ).join("\n");
+}
+function renderProposedAdr(framework) {
+  return `# Proposed ADR: Use ${framework}
+
+## Status
+
+Proposed
+
+## Context
+
+\`recall adopt\` detected ${framework} in this repository through read-only inspection.
+
+## Decision
+
+Consider recording ${framework} as an accepted architecture decision. This is proposed by adoption
+and is not accepted until a human reviews and accepts it.
+
+## Alternatives Considered
+
+- Record a different framework.
+- Leave the decision unrecorded for now.
+
+## Consequences
+
+- Captures a framework already in use as reviewable repository memory.
+- Requires explicit human acceptance before it becomes repository truth.
+
+## Related Documents
+
+- \`docs/10-architecture/ARCHITECTURE.md\` \u2014 record the accepted architecture here once promoted.
+- The adoption report generated alongside this proposal.
+`;
+}
+function frameworkSlug(framework) {
+  return framework.toLowerCase().replace(/\./gu, "").replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");
+}
+
 // src/commands/adopt.ts
 var AdoptError = class extends Error {
   code;
@@ -1532,8 +1872,8 @@ function formatList2(values) {
 
 // src/core/doctor/checks/code-reference-check.ts
 import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile4, readdir as readdir4 } 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"];
@@ -1550,7 +1890,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));
     }
   }
@@ -1560,7 +1900,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));
     }
   }
@@ -1579,7 +1919,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",
@@ -1592,7 +1932,7 @@ async function checkDoc(rootDir, relativePath) {
 }
 async function readDirIfExists(rootDir, relativePath) {
   try {
-    return await readdir4(path7.join(rootDir, relativePath), { withFileTypes: true });
+    return await readdir6(path8.join(rootDir, relativePath), { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -1603,7 +1943,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") {
@@ -1614,12 +1954,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") {
@@ -1682,9 +2022,12 @@ async function checkConfig(rootDir) {
 }
 
 // src/core/doctor/checks/content-check.ts
-import { readFile as readFile6, readdir as readdir5 } 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";
+var THREAT_MODEL_PATH = "docs/20-security/THREAT_MODEL.md";
 async function checkContent(context) {
   if (context.config === void 0) {
     return [];
@@ -1695,7 +2038,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;
@@ -1719,8 +2062,16 @@ async function checkContent(context) {
   }
   const moduleEntries = await readDirIfExists2(context.rootDir, context.config.modulesDir);
   const moduleFolders = moduleEntries.filter((entry) => entry.isDirectory());
+  const adrEntries = await readDirIfExists2(context.rootDir, context.config.adrDir);
+  const acceptedAdrs = adrEntries.filter(
+    (entry) => entry.isFile() && acceptedAdrPattern.test(entry.name)
+  );
+  const hasWork = featureFolders.length > 0 || moduleFolders.length > 0 || acceptedAdrs.length > 0;
+  if (hasWork) {
+    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;
@@ -1744,6 +2095,28 @@ async function checkContent(context) {
   }
   return findings;
 }
+async function checkSecurityDoc(rootDir) {
+  const findings = [];
+  const security = await readFileIfExists2(rootDir, SECURITY_MODEL_PATH);
+  if (security !== void 0 && sectionIsUnfilled(security, "Authentication And Authorization")) {
+    findings.push({
+      severity: "warning",
+      check: "content-security",
+      message: "Security model authentication and authorization section is still an unfilled template.",
+      path: SECURITY_MODEL_PATH
+    });
+  }
+  const threat = await readFileIfExists2(rootDir, THREAT_MODEL_PATH);
+  if (threat !== void 0 && sectionIsUnfilled(threat, "Assets")) {
+    findings.push({
+      severity: "warning",
+      check: "content-threat-model",
+      message: "Threat model assets section is still an unfilled template.",
+      path: THREAT_MODEL_PATH
+    });
+  }
+  return findings;
+}
 function sectionIsUnfilled(content, heading) {
   const section = getSection(content, heading);
   return section !== void 0 && isUnfilled(section);
@@ -1756,7 +2129,7 @@ function isUnfilled(value) {
   if (normalized === "tbd" || normalized === "todo" || normalized === "pending" || normalized === "none" || normalized === "n/a") {
     return true;
   }
-  return normalized.includes("describe why this feature exists") || normalized.includes("describe what this module owns");
+  return normalized.includes("describe why this feature exists") || normalized.includes("describe what this module owns") || normalized.includes("describe how this repository authenticates") || normalized.includes("describe what this repository must protect");
 }
 function getSection(content, heading) {
   const lines = content.split(/\r?\n/u);
@@ -1776,7 +2149,7 @@ function getSection(content, heading) {
 }
 async function readDirIfExists2(rootDir, relativePath) {
   try {
-    return await readdir5(path8.join(rootDir, relativePath), { withFileTypes: true });
+    return await readdir7(path9.join(rootDir, relativePath), { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -1787,7 +2160,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") {
@@ -1798,8 +2171,8 @@ async function readFileIfExists2(rootDir, relativePath) {
 }
 
 // src/core/doctor/checks/drift-check.ts
-import { readFile as readFile7, readdir as readdir6 } 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) {
@@ -1816,12 +2189,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) {
@@ -1834,7 +2207,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());
@@ -1869,7 +2242,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;
@@ -1902,7 +2275,7 @@ function getSection2(content, heading) {
 }
 async function readDirIfExists3(rootDir, relativePath) {
   try {
-    return await readdir6(path9.join(rootDir, relativePath), { withFileTypes: true });
+    return await readdir8(path10.join(rootDir, relativePath), { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -1913,8 +2286,8 @@ async function readDirIfExists3(rootDir, relativePath) {
 }
 
 // src/core/doctor/checks/memory-integrity-check.ts
-import { lstat as lstat2, readFile as readFile8, readdir as readdir7 } 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 = [
@@ -1978,7 +2351,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",
@@ -2002,7 +2375,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",
@@ -2025,8 +2398,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({
@@ -2047,7 +2420,7 @@ async function checkAdrFiles(rootDir, adrDir) {
 }
 async function readDirIfExists4(rootDir, relativePath) {
   try {
-    return await readdir7(path10.join(rootDir, relativePath), { withFileTypes: true });
+    return await readdir9(path11.join(rootDir, relativePath), { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -2058,7 +2431,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") {
@@ -2070,7 +2443,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",
@@ -2097,12 +2470,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"));
   }
@@ -2128,7 +2501,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") {
@@ -2139,7 +2512,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") {
@@ -2158,8 +2531,8 @@ function missingFile(pathValue, check) {
 }
 
 // src/core/doctor/checks/standards-check.ts
-import { lstat as lstat4, readFile as readFile9, readdir as readdir8 } 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;
@@ -2179,10 +2552,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);
@@ -2232,8 +2605,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({
@@ -2317,7 +2690,7 @@ function isPlaceholder(value) {
 }
 async function readDirIfExists5(rootDir, relativePath) {
   try {
-    return await readdir8(path12.join(rootDir, relativePath), { withFileTypes: true });
+    return await readdir10(path13.join(rootDir, relativePath), { withFileTypes: true });
   } catch (error) {
     const nodeError = error;
     if (nodeError.code === "ENOENT") {
@@ -2331,7 +2704,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") {
@@ -2342,7 +2715,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") {
@@ -2352,6 +2725,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 = [];
@@ -2368,6 +2845,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);
 }
@@ -2445,10 +2923,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",
@@ -2467,6 +2945,18 @@ Required reading:
 - \`docs/60-engineering/ENGINEERING_STANDARDS.md\`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## 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.
 `
   },
   {
@@ -2503,6 +2993,8 @@ 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.
@@ -2591,26 +3083,78 @@ Default behavior:
     path: "docs/20-security/SECURITY_MODEL.md",
     content: `# Security Model
 
-## Current Status
+## Status
 
-Draft.
+Draft \u2014 fill the prompted sections below with this repository's real model as it grows. \`recall doctor\`
+flags these as warnings once the repository has real work (a feature, module, or accepted decision).
 
 ## Baseline Rules
 
-- Do not commit secrets.
-- Do not read or copy \`.env\` files into docs.
+- Never commit secrets or credentials, and never read or copy \`.env\` files into docs.
+- Validate and authorize untrusted input at every trust boundary.
 - Do not add network, telemetry, cloud, MCP runtime, or AI API behavior without explicit review.
+
+## Authentication And Authorization
+
+Describe how this repository authenticates users or clients and how it authorizes actions, including
+where those checks live.
+
+## Secrets And Configuration
+
+Describe where secrets live, how they are injected, and how configuration is kept out of version
+control.
+
+## Sensitive Data
+
+Describe the sensitive or personal data this repository handles, and how it is protected at rest and
+in transit.
+
+## Dependencies And Supply Chain
+
+Describe how third-party dependencies are vetted, pinned, and updated.
 `
   },
   {
     path: "docs/20-security/THREAT_MODEL.md",
     content: `# Threat Model
 
-## Current Status
+## Status
 
-Draft.
+Draft \u2014 replace the prompts below with this repository's real analysis as it grows. \`recall doctor\`
+flags these as warnings once the repository has real work (a feature, module, or accepted decision).
+
+## Assets
 
-Track repository-specific risks here as the project evolves.
+Describe what this repository must protect: user data, credentials, money, availability, or
+reputation.
+
+## Entry Points
+
+Describe where untrusted input enters: HTTP endpoints, webhooks, file uploads, queues, CLI input, or
+third-party callbacks.
+
+## Trust Boundaries
+
+Describe where trust changes: client to server, service to database, your code to third-party APIs.
+
+## Threats
+
+Describe the concrete threats that apply to this repository, by category:
+
+- Spoofing \u2014 how identities are faked or sessions stolen.
+- Tampering \u2014 how requests, data, or builds are altered (injection, mass assignment).
+- Repudiation \u2014 actions that must remain auditable.
+- Information disclosure \u2014 how sensitive data or secrets could leak.
+- Denial of service \u2014 how the system can be overwhelmed or abused.
+- Elevation of privilege \u2014 how a user could gain access they should not have.
+
+## Mitigations
+
+Describe the control in place or planned for each threat above.
+
+## Open Risks
+
+Describe accepted or unresolved risks and who owns them.
 `
   },
   {
@@ -2659,6 +3203,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.
 `
   },
   {
@@ -2792,6 +3345,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.
@@ -2807,7 +3371,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:
 
@@ -2894,7 +3459,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,
@@ -2921,17 +3486,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 {
@@ -2940,16 +3505,16 @@ async function detectPreCommitGates(rootDir) {
   if (typeof scripts !== "object" || scripts === null) {
     return [];
   }
-  const packageManager = detectPackageManager(rootDir);
+  const packageManager = detectPackageManager2(rootDir);
   return KNOWN_SCRIPTS.filter((script) => typeof scripts[script] === "string").map(
     (script) => `${packageManager} run ${script}`
   );
 }
-function detectPackageManager(rootDir) {
-  if (existsSync5(path14.join(rootDir, "pnpm-lock.yaml"))) {
+function detectPackageManager2(rootDir) {
+  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";
@@ -4454,8 +5019,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}`;
       })
     );
   }
@@ -5144,7 +5709,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.",
@@ -5156,6 +5721,7 @@ async function initProject(options) {
     );
   }
   const preset = resolvePreset(options.preset);
+  const detected = await inspectRepo(options.rootDir);
   const preCommitGates = await detectPreCommitGates(options.rootDir);
   const config = createDefaultConfig({ preset: preset?.id ?? null, preCommitGates });
   const files = createInitWriteFiles(options.rootDir, config, preset);
@@ -5176,7 +5742,8 @@ async function initProject(options) {
     preset: preset?.id ?? null,
     dryRun: options.dryRun ?? false,
     plan,
-    writeResult
+    writeResult,
+    detected
   };
 }
 function formatInitResult(result) {
@@ -5193,6 +5760,7 @@ function formatInitResult(result) {
     dryRun: result.dryRun,
     writeResult: result.writeResult
   });
+  appendDetectedStack(lines, result.detected);
   const hookWritten = result.writeResult.created.includes(PRE_COMMIT_HOOK_PATH) || result.writeResult.overwritten.includes(PRE_COMMIT_HOOK_PATH);
   if (hookWritten) {
     lines.push("");
@@ -5215,6 +5783,21 @@ function formatInitResult(result) {
   return `${lines.join("\n")}
 `;
 }
+function appendDetectedStack(lines, detected) {
+  const hasSignal = detected.languages.length > 0 || detected.frameworks.length > 0 || detected.packageManager !== null || detected.testsEvidence !== null;
+  if (!hasSignal) {
+    return;
+  }
+  const stack = summarizeSignals(detected).filter(
+    (line) => !line.startsWith("- README") && !line.startsWith("- Docs")
+  );
+  lines.push("");
+  lines.push("Detected in this repository (proposed \u2014 review, nothing was accepted):");
+  lines.push(...stack);
+  lines.push(
+    "If any signal is wrong, correct the source file noted. Run `recall adopt` to record this as proposed memory."
+  );
+}
 function resolvePreset(presetId) {
   if (presetId === void 0) {
     return null;
@@ -5490,7 +6073,7 @@ async function loadConfigOrDefault2(rootDir) {
 }
 
 // src/core/generator/generate-module.ts
-import path16 from "path";
+import path18 from "path";
 var moduleTemplates = [
   {
     fileName: "MODULE.md",
@@ -5563,14 +6146,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)
   }));
 }
@@ -5591,7 +6174,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
@@ -5645,7 +6228,7 @@ function createModuleSlug(name) {
     throw error;
   }
 }
-async function loadRequiredConfig4(rootDir) {
+async function loadRequiredConfig5(rootDir) {
   try {
     return await loadConfig(rootDir);
   } catch (error) {
@@ -5819,6 +6402,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({
@@ -5912,6 +6509,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;