@adrkit/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1768 @@
+// src/schema/adr.schema.ts
+import { z } from "zod";
+var SCHEMA_VERSION = "0.1.0";
+var Identity = z.string().regex(/^(@[A-Za-z0-9-]+|team:[a-z0-9-]+|[^@\s]+@[^@\s]+\.[^@\s]+)$/, "Expected @handle, team:slug, or an email address");
+var AdrRef = z.string().regex(/^(([a-z0-9][a-z0-9-]*):)?([0-9]{4,}|[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26})$/, "Expected an ADR id, optionally prefixed with a log name");
+var IsoDate = z.string().date();
+var IsoDateTime = z.string().datetime({ offset: true });
+var Slug = z.string().regex(/^[a-z0-9][a-z0-9-]*$/);
+var strictObject = (shape) => z.strictObject(shape);
+var uniqueArray = (item) => z.array(item).refine((xs) => new Set(xs.map((x) => JSON.stringify(x))).size === xs.length, {
+  message: "Items must be unique"
+}).meta({ uniqueItems: true });
+var Status = z.enum([
+  "draft",
+  "proposed",
+  "accepted",
+  "rejected",
+  "superseded",
+  "deprecated"
+]);
+var Scope = z.enum(["component", "domain", "org"]);
+var Reversibility = z.enum(["two-way-door", "one-way-door", "unknown"]);
+var BlastRadius = z.enum(["component", "team", "cross-team", "org"]);
+var ReviewTier = z.enum(["auto", "async", "arb"]);
+var Severity = z.enum(["error", "warn", "info"]);
+var EscalationReason = z.enum([
+  "one-way-door",
+  "cost-threshold",
+  "security-surface",
+  "data-residency",
+  "regulatory",
+  "contradicts-accepted-adr",
+  "low-confidence",
+  "pass-disagreement",
+  "agent-authored-production",
+  "novel-no-precedent",
+  "human-requested"
+]);
+var AffectsType = z.enum([
+  "path",
+  "entity",
+  "package",
+  "resource",
+  "api",
+  "data"
+]);
+var AffectsMatcher = strictObject({
+  type: AffectsType,
+  pattern: z.string().min(1),
+  repo: z.string().optional(),
+  negate: z.boolean().default(false),
+  note: z.string().optional()
+});
+var Assertion = strictObject({
+  id: Slug,
+  description: z.string().optional(),
+  engine: z.enum(["rego", "jsonpath", "grep", "custom"]),
+  expression: z.string().optional(),
+  expressionFile: z.string().optional(),
+  input: z.enum(["source", "iac-plan", "sbom", "openapi", "catalog", "custom"]).default("source"),
+  severity: Severity
+});
+var Provenance = strictObject({
+  authoredBy: z.enum(["human", "agent", "agent-drafted"]).default("human"),
+  agent: strictObject({
+    name: z.string().optional(),
+    model: z.string().optional(),
+    harness: z.string().optional(),
+    runId: z.string().optional()
+  }).optional(),
+  ratifiedBy: Identity.optional(),
+  sourceArtifact: z.string().optional(),
+  importedFrom: strictObject({
+    sourceKind: z.enum(["madr", "agent-log", "plan-artifact", "other"]),
+    sourceRef: z.string(),
+    fingerprint: z.string(),
+    importedAt: IsoDateTime.optional()
+  }).optional()
+});
+var Objection = strictObject({
+  by: Identity,
+  summary: z.string().optional(),
+  resolved: z.boolean().default(false)
+});
+var Review = strictObject({
+  tier: ReviewTier.optional(),
+  tierReason: z.string().optional(),
+  queuedAt: IsoDateTime.optional(),
+  slaDays: z.number().int().min(0).optional(),
+  escalatedAt: IsoDateTime.optional(),
+  decidedAt: IsoDateTime.optional(),
+  quorum: z.number().int().min(1).optional(),
+  approvals: z.array(Identity).default([]),
+  objections: z.array(Objection).default([])
+});
+var DeterministicFinding = strictObject({
+  rule: z.string(),
+  severity: Severity,
+  message: z.string().optional(),
+  adr: AdrRef.optional()
+});
+var Evaluation = strictObject({
+  ranAt: IsoDateTime.optional(),
+  evaluatorVersion: z.string().optional(),
+  rubricVersion: z.string().optional(),
+  scores: z.record(z.string(), z.number().min(0).max(4)).optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  escalate: z.boolean().optional(),
+  escalationReasons: z.array(EscalationReason).default([]),
+  deterministicFindings: z.array(DeterministicFinding).default([])
+});
+var ExternalRef = strictObject({
+  type: z.enum(["issue", "pr", "rfc", "incident", "doc", "meeting", "control", "other"]),
+  id: z.string().optional(),
+  url: z.string().url(),
+  label: z.string().optional()
+});
+var AdrFrontmatter = strictObject({
+  schemaVersion: z.string().regex(/^\d+\.\d+\.\d+$/).default(SCHEMA_VERSION),
+  id: z.string().regex(/^([0-9]{4,}|[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26})$/),
+  title: z.string().min(3).max(120),
+  status: Status,
+  date: IsoDate,
+  created: IsoDate.optional(),
+  deciders: z.array(Identity).default([]),
+  consulted: z.array(Identity).default([]),
+  informed: z.array(Identity).default([]),
+  tags: uniqueArray(Slug).default([]),
+  scope: Scope.default("component"),
+  domain: z.string().optional(),
+  reversibility: Reversibility.default("unknown"),
+  blastRadius: BlastRadius.default("component"),
+  supersedes: uniqueArray(AdrRef).default([]),
+  supersededBy: AdrRef.optional(),
+  relatesTo: uniqueArray(AdrRef).default([]),
+  conflictsWith: z.array(AdrRef).default([]),
+  affects: z.array(AffectsMatcher).default([]),
+  assertions: z.array(Assertion).default([]),
+  provenance: Provenance.optional(),
+  review: Review.optional(),
+  evaluation: Evaluation.optional(),
+  externalRefs: z.array(ExternalRef).default([]),
+  complianceControls: uniqueArray(z.string()).default([]),
+  reviewBy: IsoDate.optional()
+}).refine((a) => a.status === "superseded" ? Boolean(a.supersededBy) : true, {
+  message: 'status "superseded" requires supersededBy',
+  path: ["supersededBy"]
+}).refine((a) => a.supersededBy ? a.status === "superseded" : true, {
+  message: 'supersededBy is set but status is not "superseded"',
+  path: ["status"]
+}).refine((a) => a.status !== "accepted" || a.deciders.length > 0 || Boolean(a.provenance?.importedFrom), {
+  message: "an accepted decision must name at least one decider, unless it was imported",
+  path: ["deciders"]
+}).refine((a) => a.status !== "accepted" || a.provenance?.authoredBy !== "agent" || Boolean(a.provenance?.ratifiedBy), {
+  message: 'an agent-authored record cannot reach "accepted" without a named human ratifier',
+  path: ["provenance", "ratifiedBy"]
+}).refine((a) => !(a.reversibility === "one-way-door" && a.review?.tier === "auto"), {
+  message: "one-way-door decisions may not take the auto-approve fast path",
+  path: ["review", "tier"]
+});
+
+// src/schema/emit.ts
+import { z as z2 } from "zod";
+var ADR_SCHEMA_ID = `https://adrkit.dev/schema/adr/v${SCHEMA_VERSION}/adr.schema.json`;
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJson(item));
+  }
+  if (value && typeof value === "object") {
+    const input = value;
+    const output = {};
+    for (const key of Object.keys(input).sort()) {
+      output[key] = sortJson(input[key]);
+    }
+    return output;
+  }
+  if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+    return value;
+  }
+  throw new TypeError(`Cannot serialize JSON schema value of type ${typeof value}`);
+}
+function emitJsonSchema() {
+  const schema = z2.toJSONSchema(AdrFrontmatter, { io: "input" });
+  const withMetadata = {
+    ...schema,
+    $id: ADR_SCHEMA_ID,
+    title: "Architecture Decision Record",
+    description: "Typed frontmatter for a decision record. A superset of MADR: every MADR field is present or derivable, plus governance, routing, provenance, and enforcement metadata. The markdown body below the frontmatter carries the prose."
+  };
+  return sortJson(withMetadata);
+}
+function stringifyJsonSchema(schema = emitJsonSchema()) {
+  return `${JSON.stringify(schema, null, 2)}
+`;
+}
+// src/parse/frontmatter.ts
+import { parseDocument } from "yaml";
+
+class FrontmatterError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "FrontmatterError";
+    this.code = code;
+  }
+}
+function lineContent(source, start, end) {
+  const raw = source.slice(start, end);
+  return raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+}
+function parseFrontmatter(source) {
+  const firstLineEnd = source.indexOf(`
+`);
+  const firstLine = firstLineEnd === -1 ? source : source.slice(0, firstLineEnd);
+  if ((firstLine.endsWith("\r") ? firstLine.slice(0, -1) : firstLine) !== "---") {
+    throw new FrontmatterError("missing-frontmatter", "ADR files must start with a leading --- YAML frontmatter fence");
+  }
+  if (firstLineEnd === -1) {
+    throw new FrontmatterError("unterminated-frontmatter", "ADR frontmatter is missing its closing --- fence");
+  }
+  let lineStart = firstLineEnd + 1;
+  while (lineStart <= source.length) {
+    const nextNewline = source.indexOf(`
+`, lineStart);
+    const lineEnd = nextNewline === -1 ? source.length : nextNewline;
+    if (lineContent(source, lineStart, lineEnd) === "---") {
+      const yamlSource = source.slice(firstLineEnd + 1, lineStart);
+      const bodyStart = nextNewline === -1 ? source.length : nextNewline + 1;
+      const document = parseDocument(yamlSource, { strict: true, prettyErrors: false });
+      if (document.errors.length > 0) {
+        throw new FrontmatterError("invalid-yaml", document.errors.map((error) => error.message).join("; "));
+      }
+      return { data: document.toJS(), body: source.slice(bodyStart) };
+    }
+    if (nextNewline === -1) {
+      break;
+    }
+    lineStart = nextNewline + 1;
+  }
+  throw new FrontmatterError("unterminated-frontmatter", "ADR frontmatter is missing its closing --- fence");
+}
+// src/load/corpus.ts
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+var RECORD_FILE_PATTERN = /^[0-9]{4,}-.+\.md$/;
+var TEMPLATE_FILE_NAME = "0000-template.md";
+function isRecordFileName(fileName) {
+  return fileName !== TEMPLATE_FILE_NAME && RECORD_FILE_PATTERN.test(fileName);
+}
+function normalizeDisplayPath(path, cwd = process.cwd()) {
+  const absolutePath = isAbsolute(path) ? path : resolve(cwd, path);
+  const displayPath = relative(cwd, absolutePath) || basename(absolutePath);
+  return displayPath.split(sep).join("/");
+}
+function toAbsolutePath(path, cwd = process.cwd()) {
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}
+async function discoverAdrFiles(dir = "docs/adr", cwd = process.cwd()) {
+  const absoluteDir = toAbsolutePath(dir, cwd);
+  const entries = await readdir(absoluteDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && isRecordFileName(entry.name)).map((entry) => join(absoluteDir, entry.name)).sort((a, b) => normalizeDisplayPath(a, cwd).localeCompare(normalizeDisplayPath(b, cwd)));
+}
+async function expandRecordInputs(paths, dir = "docs/adr", cwd = process.cwd()) {
+  if (!paths || paths.length === 0) {
+    return discoverAdrFiles(dir, cwd);
+  }
+  const expanded = [];
+  for (const inputPath of paths) {
+    const absolutePath = toAbsolutePath(inputPath, cwd);
+    try {
+      const inputStat = await stat(absolutePath);
+      if (inputStat.isDirectory()) {
+        expanded.push(...await discoverAdrFiles(absolutePath, cwd));
+      } else if (inputStat.isFile()) {
+        expanded.push(absolutePath);
+      }
+    } catch {
+      expanded.push(absolutePath);
+    }
+  }
+  return Array.from(new Set(expanded)).sort((a, b) => normalizeDisplayPath(a, cwd).localeCompare(normalizeDisplayPath(b, cwd)));
+}
+async function parseAdrFile(path, cwd = process.cwd()) {
+  const absolutePath = toAbsolutePath(path, cwd);
+  const source = await readFile(absolutePath, "utf8");
+  const parsed = parseFrontmatter(source);
+  return {
+    ...parsed,
+    absolutePath,
+    path: normalizeDisplayPath(absolutePath, cwd)
+  };
+}
+async function loadAdrFile(path, cwd = process.cwd()) {
+  const parsed = await parseAdrFile(path, cwd);
+  return {
+    frontmatter: AdrFrontmatter.parse(parsed.data),
+    body: parsed.body,
+    path: parsed.path
+  };
+}
+async function loadCorpus(dir = "docs/adr", cwd = process.cwd()) {
+  const files = await discoverAdrFiles(dir, cwd);
+  const records = await Promise.all(files.map((file) => loadAdrFile(file, cwd)));
+  const byId = new Map;
+  for (const record of records) {
+    byId.set(record.frontmatter.id, record);
+  }
+  return { records, byId };
+}
+// src/validate/findings.ts
+var IMPORT_FINDING_RULES = [
+  "import-incomplete",
+  "import-status-unrecognized",
+  "import-not-madr"
+];
+function compareOptional(a, b) {
+  return (a ?? "").localeCompare(b ?? "");
+}
+function sortFindings(findings) {
+  return [...findings].sort((a, b) => a.rule.localeCompare(b.rule) || compareOptional(a.id, b.id) || compareOptional(a.pattern, b.pattern) || compareOptional(a.path, b.path) || compareOptional(a.field, b.field) || a.message.localeCompare(b.message));
+}
+function countFindings(findings) {
+  let errors = 0;
+  let warnings = 0;
+  let infos = 0;
+  for (const finding of findings) {
+    if (finding.severity === "error")
+      errors += 1;
+    if (finding.severity === "warn")
+      warnings += 1;
+    if (finding.severity === "info")
+      infos += 1;
+  }
+  return { errors, warnings, infos };
+}
+function exitCodeForFindings(findings) {
+  return findings.some((finding) => finding.severity === "error") ? 1 : 0;
+}
+// src/validate/contract.ts
+function fieldPath(path) {
+  return path.length === 0 ? undefined : path.map(String).join(".");
+}
+function rawId(data) {
+  if (data && typeof data === "object" && "id" in data) {
+    const id = data.id;
+    return typeof id === "string" ? id : undefined;
+  }
+  return;
+}
+function ruleForIssue(issue) {
+  if (issue.code === "unrecognized_keys") {
+    return "strict-unknown-key";
+  }
+  if (issue.code === "custom") {
+    if (issue.message === 'status "superseded" requires supersededBy') {
+      return "superseded-requires-supersededBy";
+    }
+    if (issue.message === 'supersededBy is set but status is not "superseded"') {
+      return "supersededBy-requires-superseded-status";
+    }
+    if (issue.message === "an accepted decision must name at least one decider, unless it was imported") {
+      return "accepted-requires-decider-unless-imported";
+    }
+    if (issue.message === 'an agent-authored record cannot reach "accepted" without a named human ratifier') {
+      return "agent-accepted-requires-ratifier";
+    }
+    if (issue.message === "one-way-door decisions may not take the auto-approve fast path") {
+      return "one-way-door-disallows-auto";
+    }
+    if (issue.message === "Items must be unique") {
+      return "unique-items";
+    }
+    return "contract-refinement";
+  }
+  if (issue.code === "invalid_type") {
+    return issue.message.includes("undefined") ? "required-field" : "invalid-type";
+  }
+  if (issue.code === "invalid_value") {
+    return "invalid-enum-value";
+  }
+  if (issue.code === "invalid_format") {
+    return "invalid-format";
+  }
+  if (issue.code === "too_small" || issue.code === "too_big") {
+    return "invalid-size";
+  }
+  return `contract-${issue.code}`;
+}
+function issueFindings(issue, path, id) {
+  if (issue.code === "unrecognized_keys") {
+    return issue.keys.map((key) => {
+      const field = fieldPath([...issue.path, key]) ?? key;
+      return {
+        rule: "strict-unknown-key",
+        severity: "error",
+        message: `Unknown frontmatter field "${field}" is not allowed`,
+        path,
+        id,
+        field
+      };
+    });
+  }
+  return [
+    {
+      rule: ruleForIssue(issue),
+      severity: "error",
+      message: issue.message,
+      path,
+      id,
+      field: fieldPath(issue.path)
+    }
+  ];
+}
+function validateParsedAdr(parsed) {
+  const result = AdrFrontmatter.safeParse(parsed.data);
+  if (result.success) {
+    return {
+      findings: [],
+      record: {
+        frontmatter: result.data,
+        body: parsed.body,
+        path: parsed.path
+      }
+    };
+  }
+  const id = rawId(parsed.data);
+  return {
+    findings: result.error.issues.flatMap((issue) => issueFindings(issue, parsed.path, id))
+  };
+}
+function validateAdrFrontmatter(data, path) {
+  return validateParsedAdr({ data, body: "", path, absolutePath: path });
+}
+// src/validate/corpus-invariants.ts
+function addReferenceFinding(findings, record, field, ref, severity) {
+  findings.push({
+    rule: `dangling-${field}`,
+    severity,
+    message: `Reference "${ref}" in ${field} does not resolve to a record in the corpus`,
+    path: record.path,
+    id: record.frontmatter.id,
+    field
+  });
+}
+function validateCorpusInvariants(records) {
+  const findings = [];
+  const byId = new Map;
+  for (const record of records) {
+    const recordsForId = byId.get(record.frontmatter.id) ?? [];
+    recordsForId.push(record);
+    byId.set(record.frontmatter.id, recordsForId);
+  }
+  for (const [id, duplicates] of byId) {
+    if (duplicates.length <= 1)
+      continue;
+    const paths = duplicates.map((record) => record.path).sort();
+    for (const record of duplicates) {
+      findings.push({
+        rule: "unique-id",
+        severity: "error",
+        message: `ADR id "${id}" is used by multiple records: ${paths.join(", ")}`,
+        path: record.path,
+        id,
+        field: "id"
+      });
+    }
+  }
+  const ids = new Set(byId.keys());
+  for (const record of records) {
+    for (const ref of record.frontmatter.supersedes) {
+      if (!ids.has(ref))
+        addReferenceFinding(findings, record, "supersedes", ref, "error");
+    }
+    if (record.frontmatter.supersededBy && !ids.has(record.frontmatter.supersededBy)) {
+      addReferenceFinding(findings, record, "supersededBy", record.frontmatter.supersededBy, "error");
+    }
+    for (const ref of record.frontmatter.relatesTo) {
+      if (!ids.has(ref))
+        addReferenceFinding(findings, record, "relatesTo", ref, "error");
+    }
+    for (const ref of record.frontmatter.conflictsWith) {
+      if (!ids.has(ref)) {
+        addReferenceFinding(findings, record, "conflictsWith", ref, "warn");
+      } else if (record.frontmatter.status === "accepted") {
+        findings.push({
+          rule: "accepted-conflictsWith",
+          severity: "warn",
+          message: `Accepted ADR declares a known conflict with "${ref}"`,
+          path: record.path,
+          id: record.frontmatter.id,
+          field: "conflictsWith"
+        });
+      }
+    }
+  }
+  return findings;
+}
+// src/validate/import-incomplete.ts
+function validateImportIncomplete(records) {
+  const findings = [];
+  for (const record of records) {
+    if (!record.frontmatter.provenance?.importedFrom)
+      continue;
+    if (record.frontmatter.status === "accepted" && record.frontmatter.deciders.length === 0) {
+      findings.push({
+        rule: "import-incomplete",
+        severity: "info",
+        message: "Imported accepted decision has no deciders; provenance explains the gap, but it should be backfilled when known",
+        path: record.path,
+        id: record.frontmatter.id,
+        field: "deciders"
+      });
+    }
+  }
+  return findings;
+}
+// src/validate/index.ts
+function parseErrorFinding(error, path) {
+  if (error instanceof FrontmatterError) {
+    return {
+      rule: error.code === "invalid-yaml" ? "frontmatter-parse" : "frontmatter-fence",
+      severity: "error",
+      message: error.message,
+      path,
+      field: "frontmatter"
+    };
+  }
+  return {
+    rule: "file-read",
+    severity: "error",
+    message: error instanceof Error ? error.message : String(error),
+    path
+  };
+}
+async function lintCorpus(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const files = await expandRecordInputs(options.paths, options.dir ?? "docs/adr", cwd);
+  const records = [];
+  const findings = [];
+  for (const file of files) {
+    const displayPath = normalizeDisplayPath(file, cwd);
+    try {
+      const parsed = await parseAdrFile(file, cwd);
+      const result = validateParsedAdr(parsed);
+      findings.push(...result.findings);
+      if (result.record) {
+        records.push(result.record);
+      }
+    } catch (error) {
+      findings.push(parseErrorFinding(error, displayPath));
+    }
+  }
+  findings.push(...validateImportIncomplete(records));
+  findings.push(...validateCorpusInvariants(records));
+  return {
+    checked: files.length,
+    findings: sortFindings(findings),
+    records: [...records].sort((a, b) => a.frontmatter.id.localeCompare(b.frontmatter.id))
+  };
+}
+// src/scaffold/new.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename as basename2, dirname, resolve as resolve2 } from "node:path";
+class ScaffoldError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ScaffoldError";
+    this.code = code;
+  }
+}
+function todayIsoDate() {
+  return new Date().toISOString().slice(0, 10);
+}
+function slugifyTitle(title) {
+  const slug = title.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-");
+  if (!slug) {
+    throw new ScaffoldError("usage", "Title must contain at least one ASCII letter or digit");
+  }
+  return slug.slice(0, 80).replace(/-+$/g, "");
+}
+function statusForInput(input) {
+  const status = input ?? "draft";
+  const parsed = Status.safeParse(status);
+  if (!parsed.success) {
+    throw new ScaffoldError("usage", `Invalid status "${status}"`);
+  }
+  if (status === "accepted" || status === "superseded") {
+    throw new ScaffoldError("usage", `adr new cannot scaffold status "${status}" without additional required fields`);
+  }
+  return status;
+}
+async function nextSequentialId(dir, cwd) {
+  const files = await discoverAdrFiles(dir, cwd).catch(() => []);
+  let max = 0;
+  for (const file of files) {
+    const match = /^([0-9]+)-/.exec(basename2(file));
+    if (match?.[1]) {
+      max = Math.max(max, Number(match[1]));
+    }
+  }
+  return String(max + 1).padStart(4, "0");
+}
+function renderAdrRecord(options) {
+  const frontmatter = {
+    schemaVersion: SCHEMA_VERSION,
+    id: options.id,
+    title: options.title,
+    status: options.status,
+    date: options.date,
+    deciders: [],
+    tags: [],
+    scope: "component",
+    reversibility: "unknown",
+    blastRadius: "component",
+    relatesTo: [],
+    affects: [],
+    provenance: {
+      authoredBy: "human"
+    }
+  };
+  const validation = AdrFrontmatter.safeParse(frontmatter);
+  if (!validation.success) {
+    throw new ScaffoldError("usage", validation.error.issues.map((issue) => issue.message).join("; "));
+  }
+  return `---
+schemaVersion: ${frontmatter.schemaVersion}
+id: "${frontmatter.id}"
+title: ${JSON.stringify(frontmatter.title)}
+status: ${frontmatter.status}
+date: ${frontmatter.date}
+deciders: []
+tags: []
+scope: ${frontmatter.scope}
+reversibility: ${frontmatter.reversibility}
+blastRadius: ${frontmatter.blastRadius}
+relatesTo: []
+affects: []
+provenance:
+  authoredBy: human
+---
+
+# ADR-${frontmatter.id}: ${frontmatter.title}
+
+## Context
+
+What forces are at play? What makes this a decision rather than a preference?
+Why now — what changed?
+
+State the problem, not the solution. If this section is a restatement of the
+option you already picked, the record scores 2 at best on D1.
+
+## Decision
+
+What we are doing, in the active voice. "We will…"
+
+## Options considered
+
+At least two genuine alternatives, including doing nothing. An option no
+competent engineer would choose is a straw man and scores zero.
+
+### Option A: <chosen>
+
+| Dimension | Assessment |
+|---|---|
+| | |
+
+### Option B: <alternative>
+
+**Pros:**
+**Cons:**
+
+### Option C: Do nothing
+
+## Trade-offs
+
+What the chosen option costs. State the downsides as plainly as the benefits —
+a decision whose chosen option has no listed downsides is not a decision.
+
+## Consequences
+
+- Easier:
+- Harder:
+- **How we would know this was wrong:** a metric, a threshold, an exit
+  condition, or a review date. This is the field that most separates records
+  that stay alive from records that rot.
+- Revisit if:
+
+## Action items
+
+1. [ ]
+`;
+}
+async function createAdr(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const dir = options.dir ?? "docs/adr";
+  const title = options.title.trim();
+  const status = statusForInput(options.status);
+  if (title.length < 3 || title.length > 120) {
+    throw new ScaffoldError("usage", "Title must be between 3 and 120 characters");
+  }
+  if (/[\r\n]/.test(title)) {
+    throw new ScaffoldError("usage", "Title must fit on a single line");
+  }
+  const id = await nextSequentialId(dir, cwd);
+  const fileName = `${id}-${slugifyTitle(title)}.md`;
+  const path = resolve2(cwd, dir, fileName);
+  const displayPath = normalizeDisplayPath(path, cwd);
+  const content = renderAdrRecord({ id, title, status, date: options.date ?? todayIsoDate() });
+  if (options.write !== false) {
+    await mkdir(dirname(path), { recursive: true });
+    try {
+      await writeFile(path, content, { encoding: "utf8", flag: "wx" });
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+        throw new ScaffoldError("exists", `Refusing to overwrite existing ADR file ${displayPath}`);
+      }
+      throw error;
+    }
+  }
+  return { id, path: displayPath, content };
+}
+// src/graph/build.ts
+function edgeKey(edge) {
+  return `${edge.from}\x00${edge.to}\x00${edge.kind}`;
+}
+function pushEdge(edges, ids, edge) {
+  if (!ids.has(edge.from) || !ids.has(edge.to))
+    return;
+  edges.set(edgeKey(edge), edge);
+}
+function buildAdrGraph(records) {
+  const sortedRecords = [...records].sort((a, b) => a.frontmatter.id.localeCompare(b.frontmatter.id));
+  const ids = new Set(sortedRecords.map((record) => record.frontmatter.id));
+  const edges = new Map;
+  for (const record of sortedRecords) {
+    for (const superseded of record.frontmatter.supersedes) {
+      pushEdge(edges, ids, { from: record.frontmatter.id, to: superseded, kind: "supersedes" });
+    }
+    if (record.frontmatter.supersededBy) {
+      pushEdge(edges, ids, {
+        from: record.frontmatter.supersededBy,
+        to: record.frontmatter.id,
+        kind: "supersedes"
+      });
+    }
+    for (const related of record.frontmatter.relatesTo) {
+      pushEdge(edges, ids, { from: record.frontmatter.id, to: related, kind: "relatesTo" });
+    }
+    for (const conflict of record.frontmatter.conflictsWith) {
+      pushEdge(edges, ids, { from: record.frontmatter.id, to: conflict, kind: "conflictsWith" });
+    }
+  }
+  return {
+    nodes: sortedRecords.map((record) => ({
+      id: record.frontmatter.id,
+      title: record.frontmatter.title,
+      status: record.frontmatter.status
+    })),
+    edges: [...edges.values()].sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.kind.localeCompare(b.kind))
+  };
+}
+function dotString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/\r/g, "\\n").replace(/\n/g, "\\n").replace(/"/g, "\\\"")}"`;
+}
+function renderDotGraph(graph) {
+  const lines = ["digraph adr {", "  rankdir=LR;"];
+  for (const node of graph.nodes) {
+    lines.push(`  ${dotString(node.id)} [label=${dotString(`${node.id}: ${node.title}`)}, status=${dotString(node.status)}];`);
+  }
+  for (const edge of graph.edges) {
+    lines.push(`  ${dotString(edge.from)} -> ${dotString(edge.to)} [label=${dotString(edge.kind)}];`);
+  }
+  lines.push("}");
+  return `${lines.join(`
+`)}
+`;
+}
+function renderJsonGraph(graph) {
+  return `${JSON.stringify(graph, null, 2)}
+`;
+}
+// src/affects/inert.ts
+import picomatch from "picomatch";
+function compilePattern(pattern) {
+  return picomatch(pattern, { dot: false, nocase: false, nonegate: true });
+}
+function resolveEntityIds(pattern, catalog) {
+  const ids = new Set;
+  const isMatch = compilePattern(pattern);
+  for (const entity of catalog.entities) {
+    const refs = [entity.id, ...entity.refs ?? []];
+    if (refs.some((ref) => isMatch(ref))) {
+      ids.add(entity.id);
+    }
+  }
+  return ids;
+}
+function entitiesForPaths(changedFiles, catalog) {
+  const ids = new Set;
+  for (const entity of catalog.entities) {
+    for (const entityPath of entity.paths ?? []) {
+      const isMatch = compilePattern(entityPath);
+      if (changedFiles.some((path) => isMatch(path))) {
+        ids.add(entity.id);
+        break;
+      }
+    }
+  }
+  return ids;
+}
+function matchEntityPattern(pattern, changedFiles, catalog) {
+  if (!catalog) {
+    return { matched: false, unresolvable: true };
+  }
+  const entityIds = resolveEntityIds(pattern, catalog);
+  if (entityIds.size === 0) {
+    return { matched: false };
+  }
+  const changedEntityIds = entitiesForPaths(changedFiles, catalog);
+  return {
+    matched: [...entityIds].some((id) => changedEntityIds.has(id))
+  };
+}
+function isAlwaysInertType(type) {
+  return type === "resource" || type === "api" || type === "data";
+}
+
+// src/affects/matchers/package.ts
+import semver from "semver";
+function parsePackagePattern(pattern) {
+  const splitAt = pattern.lastIndexOf("@");
+  const hasRange = splitAt > 0;
+  const name = hasRange ? pattern.slice(0, splitAt) : pattern;
+  const range = hasRange ? pattern.slice(splitAt + 1).trim() : undefined;
+  if (!name.trim() || hasRange && !range) {
+    return;
+  }
+  if (range && !semver.validRange(range)) {
+    return;
+  }
+  return range ? { name, range } : { name };
+}
+function matchPackagePattern(pattern, changedDependencies) {
+  const parsed = parsePackagePattern(pattern);
+  if (!parsed) {
+    return { matched: false, badPattern: true };
+  }
+  if (!changedDependencies) {
+    return { matched: false, unresolvable: true };
+  }
+  return {
+    matched: changedDependencies.some((dependency) => dependency.name === parsed.name && (!parsed.range || semver.satisfies(dependency.version, parsed.range)))
+  };
+}
+function parseBunLockPackageLine(line) {
+  const match = line.match(/^\s*"([^"]+)":\s*\["([^"]+)"/);
+  if (!match)
+    return;
+  const [, name, descriptor] = match;
+  if (!name || !descriptor?.startsWith(`${name}@`))
+    return;
+  const version = descriptor.slice(name.length + 1);
+  if (!semver.valid(version))
+    return;
+  return { name, version };
+}
+function deriveChangedDependenciesFromBunLockDiff(diff) {
+  const added = new Map;
+  const removed = new Map;
+  for (const line of diff.split(/\r?\n/)) {
+    if (line.startsWith("+++") || line.startsWith("---"))
+      continue;
+    const bucket = line.startsWith("+") ? added : line.startsWith("-") ? removed : undefined;
+    if (!bucket)
+      continue;
+    const dependency = parseBunLockPackageLine(line.slice(1));
+    if (!dependency)
+      continue;
+    let versions = bucket.get(dependency.name);
+    if (!versions) {
+      versions = new Set;
+      bucket.set(dependency.name, versions);
+    }
+    versions.add(dependency.version);
+  }
+  const changedNames = new Set([...added.keys(), ...removed.keys()]);
+  return [...changedNames].flatMap((name) => {
+    const versions = new Set([...added.get(name) ?? [], ...removed.get(name) ?? []]);
+    return [...versions].map((version) => ({ name, version }));
+  }).sort((a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version));
+}
+
+// src/affects/matchers/path.ts
+import picomatch2 from "picomatch";
+function normalizeCandidate(path) {
+  return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function hasDotSegment(path) {
+  return path.split("/").some((segment) => segment.startsWith(".") && segment !== "." && segment !== "..");
+}
+function patternAllowsDotSegment(pattern) {
+  return pattern.split("/").some((segment) => segment.startsWith(".") && segment !== "." && segment !== "..");
+}
+function matchPathPattern(pattern, changedFiles) {
+  if (pattern.startsWith("/")) {
+    return { matched: false, badPattern: "leading-slash" };
+  }
+  try {
+    const isMatch = picomatch2(pattern, { dot: false, nocase: false, nonegate: true });
+    const allowsDot = patternAllowsDotSegment(pattern);
+    return {
+      matched: changedFiles.some((path) => {
+        const candidate = normalizeCandidate(path);
+        return (!hasDotSegment(candidate) || allowsDot) && isMatch(candidate);
+      })
+    };
+  } catch {
+    return { matched: false, badPattern: "invalid-glob" };
+  }
+}
+
+// src/affects/index.ts
+function compareFiredMatcher(a, b) {
+  return a.type.localeCompare(b.type) || a.pattern.localeCompare(b.pattern);
+}
+function uniqueSortedFiredMatchers(matchers) {
+  const byKey = new Map;
+  for (const matcher of matchers) {
+    byKey.set(`${matcher.type}\x00${matcher.pattern}`, matcher);
+  }
+  return [...byKey.values()].sort(compareFiredMatcher);
+}
+function affectsFinding(record, matcher, rule, severity, message) {
+  return {
+    rule,
+    severity,
+    message,
+    id: record.frontmatter.id,
+    path: record.path,
+    field: `affects.${matcher.type}`,
+    pattern: matcher.pattern
+  };
+}
+function matcherAppliesToLog(matcher, log) {
+  return !matcher.repo || matcher.repo === log;
+}
+function evaluateMatcher(record, matcher, changedFiles, snapshots) {
+  if (matcher.type === "path") {
+    const result = matchPathPattern(matcher.pattern, changedFiles);
+    if (result.badPattern) {
+      return {
+        matched: false,
+        findings: [
+          affectsFinding(record, matcher, "affects-bad-pattern", "warn", result.badPattern === "leading-slash" ? `Path matcher "${matcher.pattern}" must be repo-relative and must not start with "/".` : `Path matcher "${matcher.pattern}" is not a valid glob pattern.`)
+        ]
+      };
+    }
+    return { matched: result.matched, findings: [] };
+  }
+  if (matcher.type === "package") {
+    const result = matchPackagePattern(matcher.pattern, snapshots?.changedDependencies);
+    if (result.unresolvable) {
+      return {
+        matched: false,
+        findings: [
+          affectsFinding(record, matcher, "affects-unresolvable", "info", `Package matcher "${matcher.pattern}" requires a changed-dependency snapshot and is inert.`)
+        ]
+      };
+    }
+    if (result.badPattern) {
+      return {
+        matched: false,
+        findings: [
+          affectsFinding(record, matcher, "affects-bad-pattern", "warn", `Package matcher "${matcher.pattern}" must be "name" or "name@<valid semver range>".`)
+        ]
+      };
+    }
+    return { matched: result.matched, findings: [] };
+  }
+  if (matcher.type === "entity") {
+    const result = matchEntityPattern(matcher.pattern, changedFiles, snapshots?.catalog);
+    if (result.unresolvable) {
+      return {
+        matched: false,
+        findings: [
+          affectsFinding(record, matcher, "affects-unresolvable", "info", `Entity matcher "${matcher.pattern}" has no catalog snapshot and is inert.`)
+        ]
+      };
+    }
+    return { matched: result.matched, findings: [] };
+  }
+  if (isAlwaysInertType(matcher.type)) {
+    return {
+      matched: false,
+      findings: [
+        affectsFinding(record, matcher, "affects-unresolvable", "info", `${matcher.type} matcher "${matcher.pattern}" has no backing snapshot in this phase and is inert.`)
+      ]
+    };
+  }
+  return {
+    matched: false,
+    findings: [
+      affectsFinding(record, matcher, "affects-unknown-type", "warn", `Affects matcher type "${matcher.type}" is not recognized by this adrkit version and was ignored.`)
+    ]
+  };
+}
+function resolveAffects(input) {
+  const matches = [];
+  const findings = [];
+  for (const record of input.records) {
+    const firedMatchers = [];
+    let suppressed = false;
+    for (const matcher of record.frontmatter.affects ?? []) {
+      if (!matcherAppliesToLog(matcher, input.log))
+        continue;
+      const result = evaluateMatcher(record, matcher, input.changedFiles, input.snapshots);
+      findings.push(...result.findings);
+      if (!result.matched)
+        continue;
+      if (matcher.negate) {
+        suppressed = true;
+      } else {
+        firedMatchers.push({ type: matcher.type, pattern: matcher.pattern });
+      }
+    }
+    if (!suppressed && firedMatchers.length > 0) {
+      matches.push({
+        recordId: record.frontmatter.id,
+        firedMatchers: uniqueSortedFiredMatchers(firedMatchers)
+      });
+    }
+  }
+  return {
+    matches: matches.sort((a, b) => a.recordId.localeCompare(b.recordId)),
+    findings: sortFindings(findings)
+  };
+}
+// src/check/index.ts
+var RECORD_BASENAME = /^\d{4,}-.+\.md$/;
+var TEMPLATE_BASENAME = "0000-template.md";
+function normalizeDir(dir) {
+  const forward = (dir ?? "docs/adr").replace(/\\/g, "/");
+  let end = forward.length;
+  while (end > 0 && forward.charCodeAt(end - 1) === 47)
+    end -= 1;
+  const stripped = forward.slice(0, end);
+  return stripped === "." ? "" : stripped;
+}
+function toForwardSlash(path) {
+  return path.replace(/\\/g, "/");
+}
+function isCorpusRecordPath(file, dir) {
+  const prefix = dir ? `${dir}/` : "";
+  if (!file.startsWith(prefix))
+    return false;
+  const rest = file.slice(prefix.length);
+  if (rest.length === 0 || rest.includes("/"))
+    return false;
+  return rest !== TEMPLATE_BASENAME && RECORD_BASENAME.test(rest);
+}
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}
+function checkChanges(input) {
+  const dir = normalizeDir(input.dir);
+  const changedFiles = uniqueSorted(input.changedFiles.map(toForwardSlash));
+  const changedRecords = changedFiles.filter((file) => isCorpusRecordPath(file, dir));
+  const changedRecordSet = new Set(changedRecords);
+  const resolution = resolveAffects({
+    records: input.lint.records,
+    changedFiles,
+    snapshots: input.snapshots,
+    log: input.log
+  });
+  const titleById = new Map(input.lint.records.map((record) => [record.frontmatter.id, record.frontmatter.title]));
+  const governedBy = resolution.matches.map((match) => ({
+    recordId: match.recordId,
+    title: titleById.get(match.recordId) ?? "",
+    firedMatchers: match.firedMatchers
+  }));
+  const changedRecordFindings = input.lint.findings.filter((finding) => finding.path !== undefined && changedRecordSet.has(finding.path));
+  const findings = sortFindings([...resolution.findings, ...changedRecordFindings]);
+  const ok = !changedRecordFindings.some((finding) => finding.severity === "error");
+  return { changedFiles, governedBy, changedRecords, findings, ok };
+}
+// src/import/index.ts
+import { readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
+import { isAbsolute as isAbsolute3, resolve as resolve4 } from "node:path";
+
+// src/import/classify.ts
+function importedMadrSourceRef(record) {
+  const importedFrom = record.frontmatter.provenance?.importedFrom;
+  if (importedFrom?.sourceKind !== "madr")
+    return;
+  return importedFrom.sourceRef;
+}
+function classifyReimport(sourceEntries, existingRecords, recordEdited = () => false) {
+  const recordsBySourceRef = new Map;
+  for (const record of [...existingRecords].sort((a, b) => a.frontmatter.id.localeCompare(b.frontmatter.id))) {
+    const sourceRef = importedMadrSourceRef(record);
+    if (sourceRef && !recordsBySourceRef.has(sourceRef)) {
+      recordsBySourceRef.set(sourceRef, record);
+    }
+  }
+  return [...sourceEntries].sort((a, b) => a.sourceRef.localeCompare(b.sourceRef)).map((entry) => {
+    const record = recordsBySourceRef.get(entry.sourceRef);
+    if (!record)
+      return { sourceRef: entry.sourceRef, bucket: "new" };
+    const storedFingerprint = record.frontmatter.provenance?.importedFrom?.fingerprint;
+    if (storedFingerprint === entry.fingerprint) {
+      return { sourceRef: entry.sourceRef, bucket: "unchanged", recordId: record.frontmatter.id };
+    }
+    return {
+      sourceRef: entry.sourceRef,
+      bucket: recordEdited(record.frontmatter.id) ? "diverged" : "updated",
+      recordId: record.frontmatter.id
+    };
+  });
+}
+
+// src/import/fingerprint.ts
+import { createHash } from "node:crypto";
+function normalizeSourceBody(sourceBody) {
+  const normalizedLines = sourceBody.replace(/\r\n/g, `
+`).replace(/\r/g, `
+`);
+  return `${normalizedLines.replace(/\n*$/g, "")}
+`;
+}
+function fingerprintSourceBody(sourceBody) {
+  return createHash("sha256").update(normalizeSourceBody(sourceBody), "utf8").digest("hex");
+}
+
+// src/import/madr.ts
+import { readdir as readdir2, readFile as readFile2 } from "node:fs/promises";
+import { basename as basename3, isAbsolute as isAbsolute2, join as join2, resolve as resolve3 } from "node:path";
+function isPlainRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function firstLine(source) {
+  const lineEnd = source.indexOf(`
+`);
+  const line = lineEnd === -1 ? source : source.slice(0, lineEnd);
+  return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+function extractMadrTitle(frontmatter, body) {
+  const frontmatterTitle = frontmatter.title;
+  if (typeof frontmatterTitle === "string" && frontmatterTitle.trim().length > 0) {
+    return frontmatterTitle.trim();
+  }
+  const heading = /^#\s+(.+?)\s*#*\s*$/m.exec(body);
+  const title = heading?.[1]?.trim();
+  return title && title.length > 0 ? title : undefined;
+}
+function notMadr(path, absolutePath, reason) {
+  return { kind: "not-madr", path, absolutePath, reason };
+}
+async function readMadrFile(path, cwd = process.cwd()) {
+  const absolutePath = isAbsolute2(path) ? path : resolve3(cwd, path);
+  const displayPath = normalizeDisplayPath(absolutePath, cwd);
+  const source = await readFile2(absolutePath, "utf8");
+  const hasLeadingFence = firstLine(source) === "---";
+  if (hasLeadingFence) {
+    try {
+      const parsed = parseFrontmatter(source);
+      const frontmatter = isPlainRecord(parsed.data) ? parsed.data : {};
+      return {
+        kind: "madr",
+        path: displayPath,
+        absolutePath,
+        frontmatter,
+        body: parsed.body,
+        source,
+        title: extractMadrTitle(frontmatter, parsed.body)
+      };
+    } catch (error) {
+      const reason = error instanceof FrontmatterError ? error.message : String(error);
+      return notMadr(displayPath, absolutePath, reason);
+    }
+  }
+  const title = extractMadrTitle({}, source);
+  if (!title) {
+    return notMadr(displayPath, absolutePath, "File has no leading YAML frontmatter or top-level title");
+  }
+  return {
+    kind: "madr",
+    path: displayPath,
+    absolutePath,
+    frontmatter: {},
+    body: source,
+    source,
+    title
+  };
+}
+async function discoverMarkdownFilesInDir(dir) {
+  const entries = await readdir2(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const path = join2(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await discoverMarkdownFilesInDir(path));
+    } else if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "0000-template.md") {
+      files.push(path);
+    }
+  }
+  return files;
+}
+async function discoverMadrCandidateFiles(dir = "docs/adr", cwd = process.cwd()) {
+  const absoluteDir = isAbsolute2(dir) ? dir : resolve3(cwd, dir);
+  const files = await discoverMarkdownFilesInDir(absoluteDir).catch(() => []);
+  return files.sort((a, b) => normalizeDisplayPath(a, cwd).localeCompare(normalizeDisplayPath(b, cwd)));
+}
+function fileNameId(path) {
+  return /^([0-9]{4,})-/.exec(basename3(path))?.[1];
+}
+
+// src/import/merge.ts
+import { stringify } from "yaml";
+
+// src/import/status.ts
+var MADR_RECOGNIZED_STATUSES = [
+  "draft",
+  "proposed",
+  "accepted",
+  "rejected",
+  "superseded",
+  "deprecated"
+];
+var STATUS_SET = new Set(MADR_RECOGNIZED_STATUSES);
+function rawStatusText(status) {
+  if (typeof status !== "string")
+    return;
+  const trimmed = status.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+function mapMadrStatus(status, context) {
+  const raw = rawStatusText(status);
+  const normalized = raw?.toLowerCase();
+  if (normalized && STATUS_SET.has(normalized)) {
+    return { status: normalized, findings: [] };
+  }
+  return {
+    status: "proposed",
+    findings: [
+      {
+        rule: "import-status-unrecognized",
+        severity: "warn",
+        message: raw ? `MADR status "${raw}" is not recognized; using "proposed"` : 'MADR status is missing; using "proposed"',
+        path: context.path,
+        id: context.id,
+        field: "status"
+      }
+    ]
+  };
+}
+
+// src/import/merge.ts
+class MadrMergeError extends Error {
+  findings;
+  constructor(message, findings) {
+    super(message);
+    this.name = "MadrMergeError";
+    this.findings = findings;
+  }
+}
+var FALLBACKS = {
+  deciders: [],
+  consulted: [],
+  informed: [],
+  tags: [],
+  scope: "component",
+  reversibility: "unknown",
+  blastRadius: "component",
+  supersedes: [],
+  relatesTo: [],
+  conflictsWith: [],
+  affects: [],
+  assertions: [],
+  externalRefs: [],
+  complianceControls: []
+};
+var OPTIONAL_COPY_KEYS = [
+  "created",
+  "deciders",
+  "consulted",
+  "informed",
+  "tags",
+  "scope",
+  "domain",
+  "reversibility",
+  "blastRadius",
+  "supersedes",
+  "supersededBy",
+  "relatesTo",
+  "conflictsWith",
+  "affects",
+  "assertions",
+  "review",
+  "evaluation",
+  "externalRefs",
+  "complianceControls",
+  "reviewBy"
+];
+var OPTIONAL_REMOVE_KEYS = new Set([
+  "created",
+  "domain",
+  "supersededBy",
+  "review",
+  "evaluation",
+  "reviewBy"
+]);
+var FRONTMATTER_ORDER = [
+  "schemaVersion",
+  "id",
+  "title",
+  "status",
+  "date",
+  "created",
+  "deciders",
+  "consulted",
+  "informed",
+  "tags",
+  "scope",
+  "domain",
+  "reversibility",
+  "blastRadius",
+  "supersedes",
+  "supersededBy",
+  "relatesTo",
+  "conflictsWith",
+  "affects",
+  "assertions",
+  "provenance",
+  "review",
+  "evaluation",
+  "externalRefs",
+  "complianceControls",
+  "reviewBy"
+];
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isValidId(value) {
+  return typeof value === "string" && /^([0-9]{4,}|[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26})$/.test(value);
+}
+function isValidSchemaVersion(value) {
+  return typeof value === "string" && /^\d+\.\d+\.\d+$/.test(value);
+}
+function dateFrom(value) {
+  if (value instanceof Date && !Number.isNaN(value.valueOf())) {
+    return value.toISOString().slice(0, 10);
+  }
+  if (typeof value !== "string")
+    return;
+  const trimmed = value.trim();
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(trimmed))
+    return;
+  const parsed = new Date(`${trimmed}T00:00:00.000Z`);
+  return parsed.toISOString().slice(0, 10) === trimmed ? trimmed : undefined;
+}
+function titleFinding(path, id) {
+  return {
+    rule: "import-not-madr",
+    severity: "warn",
+    message: "MADR source is missing a usable title",
+    path,
+    id,
+    field: "title"
+  };
+}
+function importedAtFrom(value) {
+  if (!isRecord(value))
+    return;
+  const importedFrom = value.importedFrom;
+  if (!isRecord(importedFrom))
+    return;
+  return typeof importedFrom.importedAt === "string" ? importedFrom.importedAt : undefined;
+}
+function provenanceFrom(raw, sourceRef, fingerprint) {
+  const sourceProvenance = isRecord(raw.provenance) ? { ...raw.provenance } : {};
+  const authoredBy = sourceProvenance.authoredBy;
+  if (authoredBy !== "human" && authoredBy !== "agent" && authoredBy !== "agent-drafted") {
+    sourceProvenance.authoredBy = "human";
+  }
+  const importedFrom = {
+    sourceKind: "madr",
+    sourceRef,
+    fingerprint
+  };
+  const importedAt = importedAtFrom(sourceProvenance);
+  if (importedAt)
+    importedFrom.importedAt = importedAt;
+  return {
+    ...sourceProvenance,
+    importedFrom
+  };
+}
+function initialCandidate(options, findings) {
+  const raw = options.source.frontmatter;
+  const id = isValidId(raw.id) ? raw.id : options.id;
+  const title = options.source.title;
+  if (!title || title.length < 3 || title.length > 120) {
+    throw new MadrMergeError("MADR source is missing a usable title", [titleFinding(options.source.path, id)]);
+  }
+  const status = mapMadrStatus(raw.status, { path: options.source.path, id });
+  findings.push(...status.findings);
+  const candidate = {};
+  for (const key of OPTIONAL_COPY_KEYS) {
+    if (key in raw)
+      candidate[key] = raw[key];
+  }
+  candidate.schemaVersion = isValidSchemaVersion(raw.schemaVersion) ? raw.schemaVersion : SCHEMA_VERSION;
+  candidate.id = id;
+  candidate.title = title;
+  candidate.status = status.status;
+  candidate.date = dateFrom(raw.date) ?? dateFrom(raw.created) ?? "1970-01-01";
+  for (const [key, value] of Object.entries(FALLBACKS)) {
+    if (!(key in candidate) || candidate[key] === undefined || candidate[key] === null) {
+      candidate[key] = Array.isArray(value) ? [...value] : value;
+    }
+  }
+  candidate.provenance = provenanceFrom(raw, options.sourceRef, options.fingerprint);
+  return candidate;
+}
+function safeParseCandidate(candidate, sourcePath) {
+  const working = { ...candidate };
+  for (let attempt = 0;attempt < 20; attempt += 1) {
+    const parsed = AdrFrontmatter.safeParse(working);
+    if (parsed.success)
+      return parsed.data;
+    let changed = false;
+    for (const issue of parsed.error.issues) {
+      const top = issue.path[0];
+      if (typeof top !== "string")
+        continue;
+      if (top in FALLBACKS) {
+        const fallback = FALLBACKS[top];
+        working[top] = Array.isArray(fallback) ? [...fallback] : fallback;
+        changed = true;
+        continue;
+      }
+      if (OPTIONAL_REMOVE_KEYS.has(top)) {
+        delete working[top];
+        changed = true;
+        continue;
+      }
+      if (top === "provenance") {
+        working.provenance = candidate.provenance;
+        changed = true;
+      }
+    }
+    if (!changed) {
+      throw new MadrMergeError(`Migrated frontmatter for ${sourcePath} would not satisfy the adrkit schema`, parsed.error.issues.map((issue) => ({
+        rule: "import-not-madr",
+        severity: "warn",
+        message: issue.message,
+        path: sourcePath,
+        id: typeof working.id === "string" ? working.id : undefined,
+        field: issue.path.length > 0 ? issue.path.map(String).join(".") : "frontmatter"
+      })));
+    }
+  }
+  throw new MadrMergeError(`Unable to produce valid frontmatter for ${sourcePath}`, [
+    {
+      rule: "import-not-madr",
+      severity: "warn",
+      message: "Unable to produce valid frontmatter after removing invalid optional fields",
+      path: sourcePath,
+      id: typeof working.id === "string" ? working.id : undefined,
+      field: "frontmatter"
+    }
+  ]);
+}
+function orderedObject(value, order) {
+  const output = {};
+  for (const key of order) {
+    if (value[key] !== undefined)
+      output[key] = value[key];
+  }
+  for (const key of Object.keys(value).sort()) {
+    if (!(key in output) && value[key] !== undefined)
+      output[key] = value[key];
+  }
+  return output;
+}
+function orderProvenance(provenance) {
+  const output = {};
+  for (const key of ["authoredBy", "agent", "ratifiedBy", "sourceArtifact"]) {
+    if (provenance[key] !== undefined)
+      output[key] = provenance[key];
+  }
+  if (provenance.importedFrom) {
+    const importedFrom = {
+      sourceKind: provenance.importedFrom.sourceKind,
+      sourceRef: provenance.importedFrom.sourceRef,
+      fingerprint: provenance.importedFrom.fingerprint
+    };
+    if (provenance.importedFrom.importedAt)
+      importedFrom.importedAt = provenance.importedFrom.importedAt;
+    output.importedFrom = importedFrom;
+  }
+  return output;
+}
+function orderedFrontmatter(frontmatter) {
+  const raw = frontmatter;
+  const output = orderedObject(raw, FRONTMATTER_ORDER);
+  if (frontmatter.provenance)
+    output.provenance = orderProvenance(frontmatter.provenance);
+  return output;
+}
+function renderMigratedContent(frontmatter, body) {
+  const yaml = stringify(orderedFrontmatter(frontmatter), {
+    lineWidth: 0,
+    sortMapEntries: false
+  }).trimEnd();
+  return `---
+${yaml}
+---
+${body}`;
+}
+function mergeMadr(options) {
+  const findings = [];
+  const candidate = initialCandidate(options, findings);
+  const frontmatter = safeParseCandidate(candidate, options.source.path);
+  return {
+    frontmatter,
+    content: renderMigratedContent(frontmatter, options.source.body),
+    findings
+  };
+}
+function recordFromMerge(result, source) {
+  return {
+    frontmatter: result.frontmatter,
+    body: source.body,
+    path: source.path
+  };
+}
+
+// src/import/index.ts
+function toAbsolutePath2(path, cwd) {
+  return isAbsolute3(path) ? path : resolve4(cwd, path);
+}
+function notMadrFinding(path, reason) {
+  return {
+    rule: "import-not-madr",
+    severity: "warn",
+    message: reason,
+    path
+  };
+}
+async function existingRecordsFromFiles(files, cwd) {
+  const records = [];
+  for (const file of files) {
+    const absolutePath = toAbsolutePath2(file, cwd);
+    try {
+      const source = await readFile3(absolutePath, "utf8");
+      const parsed = parseFrontmatter(source);
+      const frontmatter = AdrFrontmatter.safeParse(parsed.data);
+      if (frontmatter.success) {
+        records.push({
+          frontmatter: frontmatter.data,
+          body: parsed.body,
+          path: normalizeDisplayPath(absolutePath, cwd)
+        });
+      }
+    } catch {}
+  }
+  return records.sort((a, b) => a.frontmatter.id.localeCompare(b.frontmatter.id));
+}
+function recordById(records) {
+  return new Map(records.map((record) => [record.frontmatter.id, record]));
+}
+function classifyBySourceRef(classifications) {
+  return new Map(classifications.map((classification) => [classification.sourceRef, classification]));
+}
+function numericId(id) {
+  return /^\d+$/.test(id) ? Number(id) : undefined;
+}
+function rawId2(source) {
+  const id = source.frontmatter.id;
+  return typeof id === "string" && /^([0-9]{4,}|[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26})$/.test(id) ? id : undefined;
+}
+function createIdAllocator(seed, usedIds) {
+  const used = new Set(usedIds);
+  let next = numericId(seed) ?? 1;
+  return (source, classification) => {
+    const existing = classification?.recordId;
+    if (existing)
+      return existing;
+    const sourceId = rawId2(source);
+    if (sourceId) {
+      used.add(sourceId);
+      return sourceId;
+    }
+    const fileId = fileNameId(source.absolutePath);
+    if (fileId && !used.has(fileId)) {
+      used.add(fileId);
+      return fileId;
+    }
+    for (;; ) {
+      const id = String(next).padStart(4, "0");
+      next += 1;
+      if (!used.has(id)) {
+        used.add(id);
+        return id;
+      }
+    }
+  };
+}
+function importIncompleteRecords(records) {
+  const seen = new Set;
+  const unique = [];
+  for (const record of records) {
+    const key = `${record.frontmatter.id}\x00${record.path}`;
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    unique.push(record);
+  }
+  return unique;
+}
+async function migrateMadr(input) {
+  const cwd = input.cwd ?? process.cwd();
+  const dir = input.dir ?? "docs/adr";
+  const write = input.write !== false;
+  const files = input.files ? input.files.map((file) => toAbsolutePath2(file, cwd)).sort((a, b) => normalizeDisplayPath(a, cwd).localeCompare(normalizeDisplayPath(b, cwd))) : await discoverMadrCandidateFiles(dir, cwd);
+  const findings = [];
+  const results = [];
+  const divergence = [];
+  const prepared = [];
+  for (const file of files) {
+    const read = await readMadrFile(file, cwd);
+    if (read.kind === "not-madr") {
+      results.push({ path: read.path, outcome: "skipped" });
+      findings.push(notMadrFinding(read.path, read.reason));
+      continue;
+    }
+    const sourceRef = read.path;
+    prepared.push({ source: read, sourceRef, fingerprint: fingerprintSourceBody(read.body) });
+  }
+  const existingRecords = input.existingRecords ?? await existingRecordsFromFiles(files, cwd);
+  const classifications = classifyReimport(prepared.map((entry) => ({ sourceRef: entry.sourceRef, fingerprint: entry.fingerprint, path: entry.source.path })), existingRecords, input.recordEdited ?? (() => false));
+  const classificationForSource = classifyBySourceRef(classifications);
+  const existingById = recordById(existingRecords);
+  const seed = await nextSequentialId(dir, cwd).catch(() => "0001");
+  const allocateId = createIdAllocator(seed, [
+    ...existingRecords.map((record) => record.frontmatter.id),
+    ...prepared.map((entry) => rawId2(entry.source)).filter((id) => Boolean(id))
+  ]);
+  const recordsForIncomplete = [];
+  for (const entry of prepared.sort((a, b) => a.source.path.localeCompare(b.source.path))) {
+    const classification = classificationForSource.get(entry.sourceRef);
+    const bucket = classification?.bucket ?? "new";
+    if (bucket === "diverged") {
+      results.push({ path: entry.source.path, outcome: "diverged" });
+      divergence.push({ path: entry.source.path, sourceRef: entry.sourceRef });
+      const existing = classification?.recordId ? existingById.get(classification.recordId) : undefined;
+      if (existing)
+        recordsForIncomplete.push(existing);
+      continue;
+    }
+    if (bucket === "unchanged") {
+      results.push({ path: entry.source.path, outcome: "unchanged" });
+      const existing = classification?.recordId ? existingById.get(classification.recordId) : undefined;
+      if (existing)
+        recordsForIncomplete.push(existing);
+      continue;
+    }
+    try {
+      const id = allocateId(entry.source, classification);
+      const merged = mergeMadr({
+        source: entry.source,
+        id,
+        sourceRef: entry.sourceRef,
+        fingerprint: entry.fingerprint
+      });
+      findings.push(...merged.findings);
+      const outcome = bucket === "updated" ? "updated" : "migrated";
+      if (write && merged.content !== entry.source.source) {
+        await writeFile2(entry.source.absolutePath, merged.content, "utf8");
+      }
+      results.push({ path: entry.source.path, outcome, frontmatter: merged.frontmatter });
+      recordsForIncomplete.push(recordFromMerge(merged, entry.source));
+    } catch (error) {
+      if (error instanceof MadrMergeError) {
+        results.push({ path: entry.source.path, outcome: "skipped" });
+        findings.push(...error.findings);
+        continue;
+      }
+      throw error;
+    }
+  }
+  findings.push(...validateImportIncomplete(importIncompleteRecords(recordsForIncomplete)));
+  return {
+    results: results.sort((a, b) => a.path.localeCompare(b.path)),
+    divergence: divergence.sort((a, b) => a.path.localeCompare(b.path) || a.sourceRef.localeCompare(b.sourceRef)),
+    findings: sortFindings(findings)
+  };
+}
+export {
+  validateParsedAdr,
+  validateImportIncomplete,
+  validateCorpusInvariants,
+  validateAdrFrontmatter,
+  stringifyJsonSchema,
+  sortFindings,
+  slugifyTitle,
+  resolveAffects,
+  renderMigratedContent,
+  renderJsonGraph,
+  renderDotGraph,
+  renderAdrRecord,
+  readMadrFile,
+  parsePackagePattern,
+  parseFrontmatter,
+  parseAdrFile,
+  normalizeSourceBody,
+  normalizeDisplayPath,
+  nextSequentialId,
+  migrateMadr,
+  mergeMadr,
+  matchPathPattern,
+  matchPackagePattern,
+  mapMadrStatus,
+  loadCorpus,
+  loadAdrFile,
+  lintCorpus,
+  isRecordFileName,
+  fingerprintSourceBody,
+  expandRecordInputs,
+  exitCodeForFindings,
+  emitJsonSchema,
+  discoverMadrCandidateFiles,
+  discoverAdrFiles,
+  deriveChangedDependenciesFromBunLockDiff,
+  createAdr,
+  countFindings,
+  classifyReimport,
+  checkChanges,
+  buildAdrGraph,
+  TEMPLATE_FILE_NAME,
+  Status,
+  Severity,
+  Scope,
+  ScaffoldError,
+  SCHEMA_VERSION,
+  ReviewTier,
+  Review,
+  Reversibility,
+  RECORD_FILE_PATTERN,
+  Provenance,
+  Objection,
+  Identity,
+  IMPORT_FINDING_RULES,
+  FrontmatterError,
+  ExternalRef,
+  Evaluation,
+  EscalationReason,
+  DeterministicFinding,
+  BlastRadius,
+  Assertion,
+  AffectsType,
+  AffectsMatcher,
+  AdrRef,
+  AdrFrontmatter,
+  ADR_SCHEMA_ID
+};