@maycombhq/atticus 0.0.0-stage → 2.0.0-beta.2

package/dist/chunk-HITVBIJS.js

@@ -0,0 +1,1247 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  generateTests,
+  matrixCsv,
+  matrixMarkdown,
+  traceMatrix,
+  writeTraceFindings
+} from "./chunk-2ANOROX3.js";
+import {
+  table
+} from "./chunk-VOGCSYOI.js";
+import {
+  readChangeFiles,
+  readDataChanges,
+  readHops,
+  reviewedGates
+} from "./chunk-3HI6Z55Y.js";
+import {
+  assess,
+  changeFolder,
+  changeStore,
+  checkFindings,
+  loadChangeContext
+} from "./chunk-XY3P7JW7.js";
+import {
+  GlossaryError,
+  aliasDecision,
+  completeGlossaryDefinitions,
+  defineDecision,
+  linkDecision,
+  loadGlossary,
+  readCatalog,
+  resolveTermId,
+  scanGlossary,
+  writeDecisions
+} from "./chunk-27NKUS3X.js";
+import {
+  BUILT_IN_EXTRACTORS,
+  SHIPPED_DIALECTS_DIR,
+  dialectExtractor,
+  loadShippedDialects,
+  runDialectTests
+} from "./chunk-MC3H7736.js";
+import {
+  baseClonePath,
+  checkoutState,
+  createGit,
+  readChangeRepos
+} from "./chunk-EFHQ3TWP.js";
+import {
+  DEFAULT_IGNORES,
+  fsRepo,
+  scanRepo
+} from "./chunk-GQ4N4WKF.js";
+import {
+  runtimeForCli
+} from "./chunk-CNUKCS2T.js";
+import {
+  catalogDirOf,
+  external_exports,
+  loadOrgPack,
+  mergeCatalog,
+  normalizePath,
+  orgPackDirOf,
+  require_dist
+} from "./chunk-S2A7YC3Q.js";
+import {
+  __toESM
+} from "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/quality-commands.js
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join as join4 } from "node:path";
+
+// packages/ci/dist/config.js
+var import_yaml = __toESM(require_dist(), 1);
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+var CiConfig = external_exports.strictObject({
+  schemaVersion: external_exports.literal(1),
+  drift: external_exports.strictObject({
+    mode: external_exports.enum(["block", "warn"]).default("block"),
+    ignore: external_exports.array(external_exports.string().min(1)).default([])
+  }).default({ mode: "block", ignore: [] }),
+  archive: external_exports.strictObject({ requireMergedPrs: external_exports.boolean().default(true) }).default({ requireMergedPrs: true })
+});
+var DEFAULT_CI_CONFIG = CiConfig.parse({ schemaVersion: 1 });
+async function loadCiConfig(orgPackDir) {
+  if (!orgPackDir)
+    return { config: DEFAULT_CI_CONFIG, problems: [] };
+  let text;
+  try {
+    text = await readFile(join(orgPackDir, "process", "ci.yaml"), "utf8");
+  } catch {
+    return { config: DEFAULT_CI_CONFIG, problems: [] };
+  }
+  let data;
+  try {
+    data = (0, import_yaml.parse)(text);
+  } catch (e) {
+    return {
+      config: DEFAULT_CI_CONFIG,
+      problems: [
+        `org-pack/process/ci.yaml: can't read YAML: ${e.message.split("\n")[0]}`
+      ]
+    };
+  }
+  const r = CiConfig.safeParse(data);
+  if (!r.success)
+    return {
+      config: DEFAULT_CI_CONFIG,
+      problems: r.error.issues.map((i) => `org-pack/process/ci.yaml: ${i.path.join(".") || "(file)"}: ${i.message}`)
+    };
+  return { config: r.data, problems: [] };
+}
+function ignored(id, patterns) {
+  return patterns.some((p) => p.endsWith("*") ? id.startsWith(p.slice(0, -1)) : id === p);
+}
+
+// packages/ci/dist/drift.js
+import { createHash } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { basename, isAbsolute, join as join2, relative, resolve } from "node:path";
+var DRIFT_SCHEMA_VERSION = 1;
+var DriftError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DriftError";
+  }
+};
+var isDir = (p) => {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+function resolveCatalog(p) {
+  const abs = resolve(p);
+  if (isDir(join2(abs, "org-pack")) || isDir(join2(abs, ".atticus", "org-pack")))
+    return { root: abs, generated: join2(catalogDirOf(abs), "generated") };
+  if (isDir(join2(abs, "generated")))
+    return { generated: join2(abs, "generated") };
+  return { generated: abs };
+}
+async function usableDialects(op, orgPackDir, problems) {
+  const own = new Set(op.dialects.map((d) => d.name));
+  const shipped = (await loadShippedDialects().catch(() => [])).filter((d) => !own.has(d.name));
+  const all = [
+    ...shipped.map((d) => ({ d, dir: SHIPPED_DIALECTS_DIR })),
+    ...op.dialects.map((d) => ({ d, dir: join2(orgPackDir ?? ".", "dialects") }))
+  ];
+  const byName = new Map(all.map(({ d }) => [d.name, d]));
+  const ok = [];
+  for (const { d, dir } of all) {
+    const failures = await runDialectTests(d, dir, byName).catch((e) => [
+      { test: "(load)", message: e.message }
+    ]);
+    if (failures.length) {
+      for (const f of failures)
+        problems.push(`dialect ${d.name}: test "${f.test}": ${f.message}`);
+      continue;
+    }
+    ok.push(d);
+  }
+  return ok;
+}
+var fromRepo = (r, repo, side) => r.evidence.some((e) => e.repo === repo && (!side || side(e.side)));
+var evOf = (r, repo) => r.evidence.filter((e) => e.repo === repo && e.path).slice(0, 3).map((e) => ({ path: e.path, ...e.line ? { line: e.line } : {} }));
+function surface(records, repo, components) {
+  const out = /* @__PURE__ */ new Map();
+  const add = (s) => out.set(`${s.subject}|${s.id}`, s);
+  for (const r of records) {
+    if (r.status === "retired")
+      continue;
+    if (r.kind === "Endpoint") {
+      const e = r;
+      if (!fromRepo(e, repo, (s) => s !== "caller"))
+        continue;
+      if (e.endpointType === "event-topic")
+        add({
+          subject: "topic",
+          id: e.id,
+          label: `topic ${e.pathOrTopic}`,
+          fields: { owner: e.component },
+          record: e
+        });
+      else
+        add({
+          subject: "endpoint",
+          id: e.id,
+          label: `${e.method ? `${e.method} ` : ""}${e.pathOrTopic} on ${e.component}`,
+          fields: {
+            method: e.method,
+            path: e.normalizedPath ?? normalizePath(e.pathOrTopic),
+            auth: e.auth
+          },
+          pair: `${e.component}|${e.method ?? ""}`,
+          record: e
+        });
+    } else if (r.kind === "Interface") {
+      const i = r;
+      if (fromRepo(i, repo, (s) => s === "caller"))
+        add({
+          subject: "call",
+          id: i.id,
+          label: i.sync === "async" ? `${i.from} publishes ${i.normalizedPath} to ${i.to}` : `${i.from} calls ${i.to} ${i.method ? `${i.method} ` : ""}${i.normalizedPath}`,
+          fields: {
+            to: i.to,
+            via: i.via,
+            route: i.route,
+            method: i.method,
+            path: i.normalizedPath,
+            auth: i.auth,
+            pattern: i.pattern?.code
+          },
+          pair: `${i.from}|${i.to}|${i.sync}`,
+          record: i
+        });
+      else if (i.sync === "async" && fromRepo(i, repo, (s) => s === "callee"))
+        add({
+          subject: "subscription",
+          id: i.id,
+          label: `${i.to} subscribes to ${i.normalizedPath} from ${i.from}`,
+          fields: { from: i.from, topic: i.normalizedPath },
+          record: i
+        });
+    } else if (r.kind === "Table") {
+      const t = r;
+      if (!fromRepo(t, repo))
+        continue;
+      const mine = (l) => l.filter((c) => components.has(c)).sort().join(",") || void 0;
+      add({
+        subject: "table",
+        id: t.id,
+        label: `table ${t.id}`,
+        fields: { readers: mine(t.readers), writers: mine(t.writers) },
+        record: t
+      });
+    } else if (r.kind === "Column") {
+      const c = r;
+      if (!fromRepo(c, repo))
+        continue;
+      add({
+        subject: "column",
+        id: c.id,
+        label: `column ${c.id}`,
+        fields: {
+          type: c.type.toLowerCase().replace(/\s+/g, ""),
+          nullable: c.nullable === void 0 ? void 0 : String(c.nullable)
+        },
+        record: c
+      });
+    } else if (r.kind === "Migration") {
+      const m = r;
+      if (!fromRepo(m, repo))
+        continue;
+      add({
+        subject: "migration",
+        id: m.id,
+        label: `migration ${m.file.split("/").pop()}`,
+        fields: { operations: m.operations.join("; ") || void 0 },
+        record: m
+      });
+    } else if (r.kind === "Unresolved") {
+      const u = r;
+      if (!fromRepo(u, repo) && !(u.owner && components.has(u.owner)))
+        continue;
+      add({
+        subject: "loose-end",
+        id: u.id,
+        label: `${u.unresolvedKind} ${u.raw}${u.owner ? ` from ${u.owner}` : ""}`,
+        fields: {},
+        record: u
+      });
+    }
+  }
+  return out;
+}
+var APPROVED = /* @__PURE__ */ new Set([
+  "plan",
+  "build",
+  "qa",
+  "release-ready",
+  "released",
+  "post-release-review"
+]);
+async function approvedDesigns(root) {
+  const hops = [];
+  const data = [];
+  const changes = [];
+  if (!root)
+    return { hops, data, changes };
+  let list;
+  try {
+    list = await changeStore(root).list();
+  } catch {
+    return { hops, data, changes };
+  }
+  for (const c of list.filter((x) => APPROVED.has(x.state))) {
+    changes.push(c.id);
+    const files = await readChangeFiles(changeFolder(root, c.id));
+    for (const h of readHops(files)) {
+      const topic = /^(publish|subscribe|send|receive)\s+(\S+)/i.exec(h.operation.trim())?.[2];
+      hops.push({
+        change: c.id,
+        caller: h.caller,
+        callee: h.callee,
+        ...h.method ? { method: h.method } : {},
+        ...h.path ? { path: normalizePath(h.path) } : {},
+        ...topic ? { topic } : {},
+        status: h.status
+      });
+    }
+    for (const d of readDataChanges(files))
+      data.push({
+        change: c.id,
+        table: d.tableId,
+        store: d.store,
+        columns: d.newColumns.map((x) => x.name.toLowerCase()),
+        newTable: d.newTable,
+        migration: d.migration.replace(/[`*]/g, "").trim()
+      });
+  }
+  return { hops, data, changes };
+}
+var NEW = /* @__PURE__ */ new Set(["planned-new", "planned-modify"]);
+function plannedBy(item, kind, d) {
+  const ok = (h) => kind === "removed" ? h.status === "planned-retire" : NEW.has(h.status);
+  const r = item.record;
+  switch (item.subject) {
+    case "call": {
+      const i = item.record;
+      return d.hops.find((h) => ok(h) && h.caller === i.from && h.callee === i.to && (i.sync === "async" ? h.topic === i.normalizedPath : h.method === i.method && h.path === normalizePath(i.normalizedPath)))?.change;
+    }
+    case "subscription": {
+      const i = item.record;
+      return d.hops.find((h) => ok(h) && h.topic === i.normalizedPath && (h.callee === i.to || h.caller === i.from))?.change;
+    }
+    case "endpoint": {
+      const e = item.record;
+      const path = e.normalizedPath ?? normalizePath(e.pathOrTopic);
+      return d.hops.find((h) => ok(h) && h.callee === e.component && h.method === e.method && h.path === path)?.change;
+    }
+    case "topic": {
+      const e = item.record;
+      return d.hops.find((h) => ok(h) && h.topic === e.pathOrTopic)?.change;
+    }
+    case "table":
+      return kind === "removed" ? void 0 : d.data.find((x) => x.table === item.id && (x.newTable || kind === "changed"))?.change;
+    case "column": {
+      const c = item.record;
+      return kind === "removed" ? void 0 : d.data.find((x) => x.table === c.table && x.columns.includes(c.name.toLowerCase()))?.change;
+    }
+    case "migration": {
+      if (kind === "removed")
+        return void 0;
+      const m = item.record;
+      const file = m.file.split("/").pop() ?? "";
+      return d.data.find((x) => x.migration && x.migration === file || x.store === m.dataStore && m.operations.some((op) => {
+        const t = /^(?:create|alter) table (\S+)/.exec(op)?.[1];
+        return !!t && x.table === `${m.dataStore}.${t.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+      }))?.change;
+    }
+    case "loose-end": {
+      const raw = String(r.raw ?? "");
+      const m = /^([A-Z]+)\s+(\S+)/.exec(raw);
+      const owner = String(r.owner ?? "");
+      return d.hops.find((h) => {
+        if (!ok(h) || owner && h.caller !== owner)
+          return false;
+        if (m && h.method && h.path) {
+          const url = normalizePath(m[2].replace(/^[a-z]+:\/\/[^/]+/i, ""));
+          return h.method === m[1] && (url === h.path || url.endsWith(h.path));
+        }
+        return !!h.topic && raw.trim() === h.topic;
+      })?.change;
+    }
+  }
+}
+function strip(r, repo, components) {
+  const evidence = r.evidence.filter((e) => e.repo !== repo);
+  if (!evidence.length)
+    return void 0;
+  if (r.kind === "Table")
+    return {
+      ...r,
+      evidence,
+      readers: r.readers.filter((c) => !components.has(c)),
+      writers: r.writers.filter((c) => !components.has(c))
+    };
+  return { ...r, evidence };
+}
+function otherEnds(records, repo, components) {
+  const out = [];
+  for (const r of records) {
+    if (r.kind !== "Interface" || r.sync !== "async")
+      continue;
+    const ends = [
+      { kind: "event-publish", owner: r.from, side: "caller" },
+      { kind: "event-subscribe", owner: r.to, side: "callee" }
+    ];
+    for (const e of ends) {
+      if (components.has(e.owner))
+        continue;
+      const evidence = r.evidence.filter((x) => x.side === e.side && x.repo !== repo && x.source === "code");
+      if (!evidence.length)
+        continue;
+      const hash = createHash("sha256").update(`${r.id}|${e.kind}`).digest("hex").slice(0, 10);
+      out.push({
+        kind: "Unresolved",
+        schemaVersion: 2,
+        id: `${e.owner}.${e.kind}.ctx-${hash}`.slice(0, 120),
+        status: "current",
+        confidence: "inferred",
+        unresolvedKind: e.kind,
+        raw: r.normalizedPath,
+        owner: e.owner,
+        evidence
+      });
+    }
+  }
+  return out;
+}
+var CONTEXT_SKIP = /* @__PURE__ */ new Set([
+  "Interface",
+  "Unresolved",
+  "Capability",
+  "GlossaryTerm",
+  "OwnerQuestion"
+]);
+async function repoDrift(o) {
+  const repoDir = resolve(o.repoDir);
+  if (!isDir(repoDir))
+    throw new DriftError(`There is no folder ${o.repoDir} to check.`);
+  const where2 = resolveCatalog(o.catalog);
+  if (!isDir(where2.generated))
+    throw new DriftError(`There is no catalog at ${o.catalog}. Give the metarepo checkout or its catalog folder with --catalog.`);
+  const problems = [];
+  const orgPackDir = where2.root ? orgPackDirOf(where2.root) : void 0;
+  const op = await loadOrgPack(orgPackDir ?? join2(where2.generated, "__no-org-pack__"));
+  if (orgPackDir)
+    for (const p of op.problems)
+      problems.push(`org-pack/${p.file}: ${p.path ? `${p.path}: ` : ""}${p.message}`);
+  const loaded = await loadCiConfig(orgPackDir);
+  problems.push(...loaded.problems);
+  const cfg = loaded.config;
+  const catalog = await readCatalog(where2.generated, where2.root ? { cacheRoot: where2.root } : {});
+  for (const p of catalog.problems)
+    problems.push(`catalog ${p.file}: ${p.message}`);
+  if (catalog.records.length === 0)
+    throw new DriftError(`The catalog at ${o.catalog} has no records; scan the estate first.`);
+  const manifest = op.profiles.flatMap((p) => p.repos?.repos ?? []);
+  const repoId = o.repo ?? basename(repoDir);
+  const listed = manifest.find((r) => r.id === repoId);
+  if (!listed && manifest.length && o.repo)
+    problems.push(`${repoId} isn't in the repos manifest; checking it without its type and dialects.`);
+  const fromCatalog = catalog.records.filter((r) => r.kind === "Component" && r.repo === repoId);
+  const entry = listed ?? (fromCatalog.length === 1 ? { component: fromCatalog[0].id, system: fromCatalog[0].system, dialects: [] } : void 0);
+  let commit = o.commit;
+  if (!commit) {
+    try {
+      commit = existsSync(join2(repoDir, ".git")) ? (await checkoutState(repoDir, o.git)).commit : "0".repeat(40);
+    } catch {
+      commit = "0".repeat(40);
+    }
+  }
+  if (!/^[0-9a-f]{7,64}$/.test(commit))
+    commit = "0".repeat(40);
+  const dialects = await usableDialects(op, orgPackDir, problems);
+  const byName = new Map(dialects.map((d) => [d.name, d]));
+  const extractors = [
+    ...BUILT_IN_EXTRACTORS,
+    ...dialects.filter((d) => (entry?.dialects ?? []).includes(d.name) || d.appliesTo.repoTypes.includes("*") || (entry?.type ? d.appliesTo.repoTypes.includes(entry.type) : false)).map((d) => dialectExtractor(d, byName))
+  ];
+  const inside = relative(repoDir, resolve(o.catalog)).split(/[\\/]/);
+  const skip = inside[0] && inside[0] !== ".." && !isAbsolute(inside.join("/")) ? [inside[0]] : [];
+  const scan = await scanRepo({
+    repo: fsRepo(repoId, repoDir, commit, { ignore: [...DEFAULT_IGNORES, ".atticus", ...skip] }),
+    extractors,
+    dialects: entry?.dialects ?? [],
+    scannedAt: o.scannedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    repoInfo: {
+      ...entry?.component ? { component: entry.component } : {},
+      ...entry?.system ? { system: entry.system } : {},
+      ...entry?.type ? { repoType: entry.type } : {}
+    }
+  });
+  for (const run of scan.runs.filter((x) => x.status === "failed"))
+    problems.push(`${run.extractor} failed on ${repoId}`);
+  const components = /* @__PURE__ */ new Set([
+    ...entry?.component ? [entry.component] : [],
+    ...scan.records.filter((r) => r.kind === "Component").map((r) => r.id),
+    ...catalog.records.filter((r) => r.kind === "Component" && r.repo === repoId).map((r) => r.id)
+  ]);
+  const context = catalog.records.filter((r) => !CONTEXT_SKIP.has(r.kind)).map((r) => strip(r, repoId, components)).filter((r) => !!r);
+  const merged = mergeCatalog({
+    // A fetched copy of the catalog has no manifest, so no declared hosts: route by basepath.
+    ...orgPackDir ? {} : { gatewayByBasepath: true },
+    records: [...context, ...otherEnds(catalog.records, repoId, components), ...scan.records],
+    repos: manifest.map((r) => ({
+      id: r.id,
+      type: r.type,
+      ...r.component ? { component: r.component } : {},
+      ...r.system ? { system: r.system } : {},
+      hosts: r.hosts
+    })),
+    // Without the org pack (a fetched copy of the catalog), the catalog's systems stand in for
+    // the profile's.
+    systems: orgPackDir ? op.profiles.flatMap((p) => p.profile?.systems ?? []) : catalog.records.filter((r) => r.kind === "System").map((x) => ({
+      id: x.id,
+      name: x.name,
+      boundary: x.boundary,
+      ...x.owner ? { owner: x.owner } : {},
+      aliases: []
+    })),
+    patterns: op.patterns
+  });
+  if (!orgPackDir)
+    problems.push("There is no org pack with this catalog, so patterns (inferred from the org pack) aren't compared.");
+  const before = surface(catalog.records, repoId, components);
+  const after = surface(merged.records, repoId, components);
+  if (!orgPackDir)
+    for (const m of [before, after])
+      for (const s of m.values())
+        delete s.fields.pattern;
+  const designs = await approvedDesigns(where2.root);
+  const items = [];
+  const push = (kind, s, summary, extra = {}) => {
+    if (ignored(s.id, cfg.drift.ignore))
+      return;
+    const planned = kind === "planned" ? void 0 : plannedBy(s, kind, designs);
+    items.push({
+      kind: planned ? "planned" : kind,
+      subject: s.subject,
+      id: s.id,
+      summary: planned ? `${summary} (planned by ${planned})` : summary,
+      ...extra,
+      ...planned ? { change: planned } : {},
+      evidence: evOf(s.record, repoId)
+    });
+  };
+  const diff = (a, b) => Object.keys({ ...a.fields, ...b.fields }).sort().filter((f) => (a.fields[f] ?? "") !== (b.fields[f] ?? "")).map((f) => ({
+    field: f,
+    ...a.fields[f] !== void 0 ? { catalog: a.fields[f] } : {},
+    ...b.fields[f] !== void 0 ? { code: b.fields[f] } : {}
+  }));
+  const describe = (ch) => ch.map((c) => `${c.field} ${c.catalog ?? "(none)"} \u2192 ${c.code ?? "(none)"}`).join(", ");
+  const gone = [];
+  const fresh = [];
+  for (const [k, a] of before) {
+    const b = after.get(k);
+    if (!b)
+      gone.push(a);
+    else {
+      const ch = diff(a, b);
+      if (ch.length)
+        push("changed", b, `${b.label} changed: ${describe(ch)}.`, { changes: ch });
+    }
+  }
+  for (const [k, b] of after)
+    if (!before.has(k))
+      fresh.push(b);
+  const pairs = (l) => {
+    const m = /* @__PURE__ */ new Map();
+    for (const s of l)
+      if (s.pair)
+        m.set(`${s.subject}|${s.pair}`, [...m.get(`${s.subject}|${s.pair}`) ?? [], s]);
+    return m;
+  };
+  const gp = pairs(gone);
+  const fp = pairs(fresh);
+  const paired = /* @__PURE__ */ new Set();
+  for (const [k, olds] of gp) {
+    const news = fp.get(k);
+    if (olds.length !== 1 || news?.length !== 1)
+      continue;
+    const ch = diff(olds[0], news[0]);
+    push("changed", news[0], `${olds[0].label} changed: ${describe(ch)}.`, { changes: ch });
+    paired.add(olds[0]).add(news[0]);
+  }
+  for (const a of gone.filter((x) => !paired.has(x)))
+    push("removed", a, `${a.label} is in the catalog but no longer in the code.`);
+  for (const b of fresh.filter((x) => !paired.has(x)))
+    push(b.subject === "loose-end" ? "unknown" : "added", b, b.subject === "loose-end" ? `${b.label}: Atticus can't tell where it goes.` : `${b.label} is in the code but not in the catalog.`);
+  const ORDER = ["added", "changed", "removed", "unknown", "planned"];
+  items.sort((a, b) => ORDER.indexOf(a.kind) - ORDER.indexOf(b.kind) || a.subject.localeCompare(b.subject) || a.id.localeCompare(b.id));
+  const counts = Object.fromEntries(ORDER.map((k) => [k, items.filter((i) => i.kind === k).length]));
+  return {
+    schemaVersion: DRIFT_SCHEMA_VERSION,
+    repo: repoId,
+    components: [...components].sort(),
+    mode: o.warnOnly ? "warn" : cfg.drift.mode,
+    drift: items.some((i) => i.kind !== "planned"),
+    counts,
+    items,
+    changes: designs.changes,
+    scanned: {
+      commit,
+      records: scan.records.length,
+      extractors: extractors.map((x) => x.id).sort()
+    },
+    problems
+  };
+}
+var driftExitCode = (r) => r.drift && r.mode === "block" ? 1 : 0;
+
+// packages/ci/dist/report.js
+var driftJson = (r) => `${JSON.stringify(r, null, 2)}
+`;
+var xml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+var where = (i) => i.evidence.map((e) => `${e.path ?? ""}${e.line ? `:${e.line}` : ""}`).filter(Boolean);
+function driftJUnit(r) {
+  const cases = r.items.map((i) => {
+    const name = `${i.kind} ${i.subject} ${i.id}`;
+    const open = `    <testcase classname="atticus.drift.${i.subject}" name="${xml(name)}">`;
+    const detail = [i.summary, ...where(i).map((w) => `at ${w}`)].join("\n");
+    if (i.kind === "planned")
+      return `${open}
+      <system-out>${xml(detail)}</system-out>
+    </testcase>`;
+    if (r.mode === "warn")
+      return `${open}
+      <skipped message="${xml(`warn-only: ${i.summary}`)}"/>
+    </testcase>`;
+    return `${open}
+      <failure message="${xml(i.summary)}" type="${i.kind}">${xml(detail)}</failure>
+    </testcase>`;
+  });
+  if (!cases.length)
+    cases.push(`    <testcase classname="atticus.drift" name="${xml(`${r.repo} matches the catalog`)}"/>`);
+  const failures = r.mode === "block" ? r.items.filter((i) => i.kind !== "planned").length : 0;
+  const skipped = r.mode === "warn" ? r.items.filter((i) => i.kind !== "planned").length : 0;
+  return [
+    `<?xml version="1.0" encoding="UTF-8"?>`,
+    `<testsuites name="atticus drift" tests="${cases.length}" failures="${failures}" skipped="${skipped}">`,
+    `  <testsuite name="${xml(`atticus drift ${r.repo}`)}" tests="${cases.length}" failures="${failures}" errors="0" skipped="${skipped}">`,
+    ...cases,
+    `  </testsuite>`,
+    `</testsuites>`,
+    ""
+  ].join("\n");
+}
+var KIND_WORD = {
+  added: "Not in the catalog",
+  changed: "Changed",
+  removed: "Gone from the code",
+  unknown: "Unknown loose end",
+  planned: "Planned"
+};
+var cell = (s) => s.replace(/\|/g, "\\|").replace(/\n/g, " ");
+function driftMarkdown(r) {
+  const n = r.items.filter((i) => i.kind !== "planned").length;
+  const planned = r.counts.planned;
+  const head = !r.drift ? `No drift: ${r.repo} matches the catalog${planned ? ` (${planned} planned by approved changes)` : ""}.` : `${n} drift ${n === 1 ? "finding" : "findings"} in ${r.repo}${r.mode === "warn" ? " (warn-only: the pipeline passes)" : ""}.`;
+  const lines2 = [`## Atticus drift check: ${r.repo}`, "", head];
+  if (r.items.length) {
+    lines2.push("", "| What | Kind | Id | Details |", "| --- | --- | --- | --- |");
+    for (const i of r.items)
+      lines2.push(`| ${KIND_WORD[i.kind]} | ${i.subject} | ${cell(i.id)} | ${cell(i.summary)}${where(i).length ? ` (${where(i).join(", ")})` : ""} |`);
+  }
+  if (r.drift && r.mode === "block")
+    lines2.push("", "Fix the code, or record the change in the catalog: plan it in an approved change's design, or rescan the estate once it is merged.");
+  if (r.problems.length)
+    lines2.push("", "Problems:", ...r.problems.map((p) => `- ${p}`));
+  return `${lines2.join("\n")}
+`;
+}
+
+// packages/ci/dist/snippets.js
+var SNIPPET_KINDS = ["github", "azure", "gitlab", "jenkins"];
+var CLI = "npx --yes @maycombhq/atticus@${ATTICUS_VERSION:-latest}";
+var ARGS = "--json atticus-drift.json --junit atticus-drift.xml";
+var GITHUB = `# Generated by Atticus (atticus ci snippet github): the catalog drift check.
+# Set the repository variable ATTICUS_METAREPO (owner/name of the metarepo) and, for a private
+# metarepo, the secret ATTICUS_METAREPO_TOKEN (read-only). ATTICUS_VERSION pins the CLI.
+name: atticus-drift
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  drift:
+    runs-on: ubuntu-latest
+    env:
+      ATTICUS_VERSION: \${{ vars.ATTICUS_VERSION || 'latest' }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: repo
+      - name: Check out the metarepo
+        uses: actions/checkout@v4
+        with:
+          repository: \${{ vars.ATTICUS_METAREPO }}
+          token: \${{ secrets.ATTICUS_METAREPO_TOKEN || github.token }}
+          path: atticus-metarepo
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Atticus drift check
+        run: ${CLI} ci drift repo --catalog atticus-metarepo --repo \${{ github.event.repository.name }} ${ARGS} --summary "$GITHUB_STEP_SUMMARY"
+      - name: Keep the drift report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: atticus-drift
+          path: |
+            atticus-drift.json
+            atticus-drift.xml
+`;
+var AZURE = `# Generated by Atticus (atticus ci snippet azure): the catalog drift check.
+# Declare the metarepo as a repository resource named atticus_metarepo; ATTICUS_VERSION pins the CLI.
+resources:
+  repositories:
+    - repository: atticus_metarepo
+      type: git
+      name: $(ATTICUS_METAREPO)
+
+trigger:
+  - main
+pr:
+  - "*"
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - checkout: self
+    path: s/repo
+  - checkout: atticus_metarepo
+    path: s/atticus-metarepo
+  - task: NodeTool@0
+    inputs:
+      versionSpec: "22.x"
+  - script: ${CLI} ci drift repo --catalog atticus-metarepo --repo $(Build.Repository.Name) ${ARGS} --summary atticus-drift.md
+    displayName: Atticus drift check
+    workingDirectory: $(Pipeline.Workspace)/s
+  - task: PublishTestResults@2
+    condition: always()
+    inputs:
+      testResultsFormat: JUnit
+      testResultsFiles: $(Pipeline.Workspace)/s/atticus-drift.xml
+      testRunTitle: Atticus drift
+  - task: PublishBuildArtifacts@1
+    condition: always()
+    inputs:
+      PathtoPublish: $(Pipeline.Workspace)/s/atticus-drift.json
+      ArtifactName: atticus-drift
+`;
+var GITLAB = `# Generated by Atticus (atticus ci snippet gitlab): the catalog drift check.
+# Set the CI/CD variable ATTICUS_METAREPO_URL (an https clone URL the job token can read);
+# ATTICUS_VERSION pins the CLI.
+atticus-drift:
+  image: node:22
+  stage: test
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  script:
+    - git clone --depth 1 "$ATTICUS_METAREPO_URL" ../atticus-metarepo
+    - ${CLI} ci drift . --catalog ../atticus-metarepo --repo "$CI_PROJECT_NAME" ${ARGS} --summary atticus-drift.md
+  artifacts:
+    when: always
+    paths:
+      - atticus-drift.json
+      - atticus-drift.md
+    reports:
+      junit: atticus-drift.xml
+`;
+var JENKINS = `// Generated by Atticus (atticus ci snippet jenkins): the catalog drift check.
+// Set ATTICUS_METAREPO_URL and, for a private metarepo, the credentials id
+// ATTICUS_METAREPO_CREDENTIALS; ATTICUS_VERSION pins the CLI.
+pipeline {
+  agent any
+  stages {
+    stage('Atticus drift check') {
+      steps {
+        dir('repo') {
+          checkout scm
+        }
+        dir('atticus-metarepo') {
+          git url: env.ATTICUS_METAREPO_URL, credentialsId: env.ATTICUS_METAREPO_CREDENTIALS
+        }
+        sh '${CLI} ci drift repo --catalog atticus-metarepo --repo "$(basename "$GIT_URL" .git)" ${ARGS} --summary atticus-drift.md'
+      }
+    }
+  }
+  post {
+    always {
+      junit allowEmptyResults: false, testResults: 'atticus-drift.xml'
+      archiveArtifacts artifacts: 'atticus-drift.json,atticus-drift.md', allowEmptyArchive: true
+    }
+  }
+}
+`;
+var SNIPPETS = {
+  github: { kind: "github", path: ".github/workflows/atticus-drift.yml", content: GITHUB },
+  azure: { kind: "azure", path: "azure-pipelines.atticus-drift.yml", content: AZURE },
+  gitlab: { kind: "gitlab", path: ".gitlab-ci.atticus-drift.yml", content: GITLAB },
+  jenkins: { kind: "jenkins", path: "Jenkinsfile.atticus-drift", content: JENKINS }
+};
+function pipelineSnippet(kind) {
+  const k = kind.toLowerCase().replace(/[-_ ]?(actions|pipelines|ci)$/, "");
+  return SNIPPETS[k];
+}
+
+// packages/ci/dist/archive.js
+import { existsSync as existsSync2 } from "node:fs";
+import { readFile as readFile2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+async function archiveGate(root, changeId, o = {}) {
+  const change = await changeStore(root).read(changeId);
+  const blockers = [];
+  const notes = [];
+  const { config } = await loadCiConfig(orgPackDirOf(root));
+  if (change.state === "post-release-review") {
+    const ctx = await loadChangeContext(root);
+    const a = await assess(ctx, change);
+    for (const r of a.blockers)
+      blockers.push({ code: "finding", message: r.message });
+  } else if (change.state !== "released") {
+    blockers.push({
+      code: "wrong-state",
+      message: change.state === "archived" ? `${change.id} is already archived.` : `${change.id} is ${change.state}; a change is archived once it is released (go/no-go merged).`
+    });
+  }
+  const gates = await reviewedGates(root, change.id);
+  for (const r of await checkFindings(root, change, gates))
+    blockers.push({ code: "finding", message: r.message });
+  const repos = (await readChangeRepos(root, change.id))?.repos ?? [];
+  for (const r of repos) {
+    if (r.pr && config.archive.requireMergedPrs && r.pr.state !== "merged" && r.pr.state !== "closed")
+      blockers.push({
+        code: "pr-open",
+        message: `${r.id}: PR #${r.pr.number} is ${r.pr.state}; merge it before archiving.`
+      });
+    if (r.build.status === "failed")
+      blockers.push({
+        code: "build-failed",
+        message: `${r.id}: the build failed${r.build.sha ? ` on ${r.build.sha.slice(0, 7)}` : ""}${r.build.log ? ` (log ${r.build.log})` : ""}.`
+      });
+    else if (r.build.status === "running")
+      blockers.push({ code: "build-running", message: `${r.id}: the build is still running.` });
+    else if (r.build.status === "not-run" && r.pr)
+      blockers.push({
+        code: "build-not-run",
+        message: `${r.id}: PR #${r.pr.number} changed code but no build has run.`
+      });
+  }
+  const drift = [];
+  if (o.driftReports?.length) {
+    for (const f of o.driftReports) {
+      try {
+        drift.push(JSON.parse(await readFile2(f, "utf8")));
+      } catch (e) {
+        blockers.push({
+          code: "drift-error",
+          message: `Can't read the drift report ${f}: ${e.message.split("\n")[0]}.`
+        });
+      }
+    }
+  } else {
+    for (const r of repos) {
+      const dir = o.repoDir?.(r.id) ?? [join3(root, r.worktree), baseClonePath(root, r.id)].find((d) => existsSync2(d));
+      if (!dir || !existsSync2(dir)) {
+        notes.push(`No checkout of ${r.id} here, so its drift wasn't checked; pass its pipeline's drift report.`);
+        continue;
+      }
+      try {
+        drift.push(await repoDrift({
+          repoDir: dir,
+          catalog: root,
+          repo: r.id,
+          ...o.commit ? { commit: o.commit } : {}
+        }));
+      } catch (e) {
+        if (!(e instanceof DriftError))
+          throw e;
+        blockers.push({ code: "drift-error", message: `${r.id}: ${e.message}` });
+      }
+    }
+    if (!repos.length)
+      notes.push("The change has no repos (repos.yaml), so there was no code to check for drift.");
+  }
+  for (const d of drift) {
+    const items = d.items.filter((i) => i.kind !== "planned");
+    if (!items.length)
+      continue;
+    blockers.push({
+      code: "drift",
+      message: `${d.repo}: ${items.length} catalog drift ${items.length === 1 ? "finding" : "findings"} (${items.slice(0, 3).map((i) => i.summary.replace(/\.$/, "")).join("; ")}${items.length > 3 ? "; ..." : ""}).`
+    });
+  }
+  const unique = [...new Map(blockers.map((b) => [b.message, b])).values()];
+  return {
+    change: change.id,
+    state: change.state,
+    pass: unique.length === 0,
+    blockers: unique,
+    notes,
+    drift
+  };
+}
+
+// packages/cli/dist/quality-commands.js
+var KNOWN = /* @__PURE__ */ new Set([
+  "TestgenError",
+  "PlannerError",
+  "ChangeError",
+  "ChangeFileError",
+  "GlossaryError",
+  "RuntimeConfigError"
+]);
+function fail(io, e) {
+  if (e instanceof Error && KNOWN.has(e.name)) {
+    io.err(e.message);
+    return e.code === "invalid" ? 2 : 1;
+  }
+  throw e;
+}
+var iso = (d) => d.toISOString().replace(/\.\d{3}Z$/, "Z");
+var lines = (io, text) => {
+  for (const l of text.trimEnd().split("\n"))
+    io.out(l);
+};
+var plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+async function runtimeOf(root, mode, deps) {
+  if (deps.runtime)
+    return deps.runtime;
+  if (!mode && !process.env.ATTICUS_RUNTIME)
+    return void 0;
+  return (await runtimeForCli(root, mode ? { mode } : {})).runtime;
+}
+async function testsGenerate(root, changeId, storyId, o, io, deps = {}) {
+  if (!changeId || !storyId) {
+    io.err("Usage: atticus tests generate <change> <story> [--framework <id>] [--force] [--check] [--mode <mode>] [--json]");
+    return 2;
+  }
+  try {
+    const runtime = await runtimeOf(root, o.mode, deps);
+    const r = await generateTests(root, changeId, storyId, {
+      ...o.framework ? { framework: o.framework } : {},
+      ...o.force ? { force: true } : {},
+      ...o.check ? { check: true } : {},
+      ...o.resume ? { resume: o.resume } : {},
+      ...runtime ? { runtime } : {},
+      now: deps.now?.() ?? /* @__PURE__ */ new Date()
+    });
+    const kept = r.files.filter((f) => f.action === "kept-edited" || f.action === "kept-not-generated");
+    if (o.json) {
+      io.out(JSON.stringify({
+        change: r.change,
+        story: r.story,
+        strategy: r.model.strategy,
+        kinds: r.model.kinds,
+        names: r.names.by,
+        ...r.names.waiting ? { waiting: r.names.waiting } : {},
+        files: r.files,
+        manifest: r.manifest,
+        notes: r.notes,
+        gaps: r.gaps
+      }, null, 2));
+      return kept.length ? 1 : 0;
+    }
+    const count = (a) => r.files.filter((f) => f.action === a).length;
+    const cases = r.model.repos.reduce((n, x) => n + x.cases.length, 0);
+    io.out(`${o.check ? "Would write" : "Generated"} ${plural(cases, "test case")} for ${r.story} in ${plural(r.files.length, "file")}: ${count("created")} new, ${count("updated")} updated, ${count("unchanged")} unchanged${kept.length ? `, ${kept.length} kept` : ""}.`);
+    for (const l of table(["ACTION", "REPO", "FRAMEWORK", "FILE"], r.files.map((f) => [f.action, f.repo || "-", f.generator, f.path])))
+      io.out(l);
+    for (const k of r.model.kinds.filter((x) => !x.generated))
+      io.out(`No ${k.type} tests: ${k.why}`);
+    for (const n of r.notes)
+      io.out(n);
+    for (const g of r.gaps)
+      io.out(`Gap: ${g}`);
+    if (r.names.waiting)
+      io.out(`The test writer is with your assistant (run ${r.names.waiting}); the files use plain names until you run: atticus tests generate ${changeId} ${storyId} --resume ${r.names.waiting}`);
+    if (!o.check)
+      io.out(`Manifest: ${r.manifest}`);
+    return kept.length ? 1 : 0;
+  } catch (e) {
+    return fail(io, e);
+  }
+}
+async function traceCommand(root, changeId, o, io, deps = {}) {
+  if (!changeId) {
+    io.err("Usage: atticus trace <change> [--json | --csv] [--no-write]");
+    return 2;
+  }
+  try {
+    const m = await traceMatrix(root, changeId, { git: deps.git ?? createGit() });
+    for (const p of m.problems)
+      io.err(p);
+    const w = o.write === false ? void 0 : await writeTraceFindings(root, m, iso(deps.now?.() ?? /* @__PURE__ */ new Date()));
+    if (o.json)
+      io.out(JSON.stringify({ ...m, ...w ? { round: w.round ?? null } : {} }, null, 2));
+    else if (o.csv)
+      lines(io, matrixCsv(m));
+    else {
+      lines(io, matrixMarkdown(m));
+      if (w)
+        io.out(w.unchanged ? `Findings on the trace gate are unchanged (round ${w.round ?? "none"}).` : `Wrote ${plural(w.findings.length, "finding")} to review/trace/${w.round}/.`);
+    }
+    return m.gaps.some((g) => g.kind !== "test-without-requirement") ? 1 : 0;
+  } catch (e) {
+    return fail(io, e);
+  }
+}
+async function ciDrift(repoDir, o, io, deps = {}) {
+  if (!o.catalog) {
+    io.err("Usage: atticus ci drift [repo-dir] --catalog <metarepo or catalog folder> [--repo <id>] [--json [file]] [--junit <file>] [--summary <file>] [--warn-only]");
+    return 2;
+  }
+  try {
+    const r = await repoDrift({
+      repoDir,
+      catalog: o.catalog,
+      ...o.repo ? { repo: o.repo } : {},
+      ...o.warnOnly ? { warnOnly: true } : {},
+      ...deps.commit ? { commit: deps.commit } : {},
+      ...deps.git ? { git: deps.git } : {}
+    });
+    const put = async (file, text) => {
+      await mkdir(dirname(file), { recursive: true });
+      await writeFile(file, text, "utf8");
+    };
+    if (typeof o.json === "string")
+      await put(o.json, driftJson(r));
+    if (o.junit)
+      await put(o.junit, driftJUnit(r));
+    if (o.summary) {
+      await mkdir(dirname(o.summary), { recursive: true });
+      await appendFile(o.summary, driftMarkdown(r), "utf8");
+    }
+    if (o.json === true)
+      io.out(driftJson(r).trimEnd());
+    else
+      lines(io, driftMarkdown(r));
+    return driftExitCode(r);
+  } catch (e) {
+    if (e instanceof DriftError) {
+      io.err(e.message);
+      return 2;
+    }
+    throw e;
+  }
+}
+async function ciSnippet(kind, io, o = {}) {
+  const s = kind ? pipelineSnippet(kind) : void 0;
+  if (!s) {
+    io.err(`Usage: atticus ci snippet <${SNIPPET_KINDS.join("|")}> [--write <repo-dir>]`);
+    return 2;
+  }
+  if (o.write) {
+    const file = join4(o.write, ...s.path.split("/"));
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, s.content, "utf8");
+    io.out(`Wrote ${s.path}. Set the variables its first lines name, then commit it.`);
+    return 0;
+  }
+  lines(io, s.content);
+  return 0;
+}
+async function ciArchiveGate(root, changeId, o, io, deps = {}) {
+  if (!changeId) {
+    io.err("Usage: atticus ci archive-gate <change> [--drift <report.json>...] [--json]");
+    return 2;
+  }
+  let r;
+  try {
+    r = await archiveGate(root, changeId, {
+      ...o.drift?.length ? { driftReports: o.drift } : {},
+      ...deps.commit ? { commit: deps.commit } : {}
+    });
+  } catch (e) {
+    if (e instanceof Error && e.name === "ChangeFileError") {
+      io.err(e.message);
+      return 2;
+    }
+    throw e;
+  }
+  if (o.json)
+    io.out(JSON.stringify(r, null, 2));
+  else {
+    io.out(r.pass ? `${changeId} may be archived: no blockers, builds passed and the catalog matches its repos.` : `${changeId} can't be archived yet (${plural(r.blockers.length, "blocker")}):`);
+    for (const b of r.blockers)
+      io.out(`- ${b.message}`);
+    for (const n of r.notes)
+      io.out(n);
+  }
+  return r.pass ? 0 : 1;
+}
+var short = (s, n = 70) => s.length <= n ? s : `${s.slice(0, n - 3)}...`;
+var sourceOf = (flags, confidence) => confidence === "asserted" ? "person" : flags?.includes("ai-proposed") ? "ai" : flags?.includes("undefined") ? "code" : "wiki";
+async function glossaryList(root, o, io) {
+  const g = await loadGlossary(root);
+  for (const p of g.problems)
+    io.err(p);
+  if (o.json) {
+    io.out(JSON.stringify({
+      terms: g.terms,
+      conflicts: g.build.conflicts,
+      hints: g.build.hints,
+      synonyms: Object.fromEntries(g.build.entries.filter((e) => e.aliases.length).map((e) => [e.id, e.aliases]))
+    }, null, 2));
+    return 0;
+  }
+  if (!g.terms.length) {
+    io.out("The glossary is empty: no wiki page defines a term and the catalog has no domain words yet.");
+    return 0;
+  }
+  for (const l of table(["TERM", "ID", "FROM", "FLAGS", "DEFINITION"], g.terms.map((t) => [
+    t.term,
+    t.id,
+    sourceOf(t.flags, t.confidence),
+    (t.flags ?? []).join(","),
+    short(t.definition)
+  ])))
+    io.out(l);
+  io.out(`${plural(g.terms.length, "term")}, ${plural(g.build.conflicts.filter((c) => !c.resolved).length, "conflict")}.`);
+  return 0;
+}
+async function glossaryScan(root, o, io, deps = {}) {
+  try {
+    const runtime = await runtimeOf(root, o.mode, deps);
+    const r = await scanGlossary(root, {
+      ...runtime ? { runtime } : {},
+      ...deps.now ? { now: deps.now() } : {}
+    });
+    if (o.json) {
+      for (const p of r.problems)
+        io.err(p);
+      io.out(JSON.stringify({
+        terms: r.terms.length,
+        written: r.written,
+        removed: r.removed,
+        conflicts: r.build.conflicts,
+        hints: r.build.hints,
+        ...r.propose ? { proposals: r.propose.proposals.length, discarded: r.propose.discarded } : {}
+      }, null, 2));
+      return 0;
+    }
+    printGlossaryScan(r, io);
+    return 0;
+  } catch (e) {
+    return fail(io, e);
+  }
+}
+function printGlossaryScan(r, io) {
+  for (const p of r.problems)
+    io.err(p);
+  const open = r.build.conflicts.filter((c) => !c.resolved);
+  io.out(`The glossary has ${plural(r.terms.length, "term")}; ${plural(r.written.length, "file")} written and ${plural(r.removed.length, "file")} removed in catalog/generated.`);
+  if (r.propose)
+    io.out(r.propose.waiting ? `The glossary definer is with your assistant (run ${r.propose.waiting}). When it is done, run: atticus handoff done ${r.propose.waiting}` : `The glossary definer proposed ${plural(r.propose.proposals.length, "definition")} (kept inferred until a person defines the term).`);
+  for (const d of r.propose?.discarded ?? [])
+    if (d.term && !r.propose?.waiting)
+      io.err(`Discarded ${d.term}: ${d.reason}`);
+  for (const c of open)
+    io.out(`Conflict: ${c.message}`);
+  for (const h of r.build.hints)
+    io.out(`Naming: ${h.message}`);
+}
+async function completeGlossaryScan(root, run, io, deps = {}) {
+  try {
+    const r = await completeGlossaryDefinitions(root, run, deps.now ? { now: deps.now } : {});
+    printGlossaryScan(r, io);
+    return 0;
+  } catch (e) {
+    return fail(io, e);
+  }
+}
+async function decide(root, io, make, said) {
+  try {
+    const g = await loadGlossary(root);
+    const ds = make(g);
+    const files = await writeDecisions(join4(g.catalogDir, "curated"), ds);
+    await scanGlossary(root);
+    io.out(`Wrote ${files.map((f) => `catalog/curated/${f}`).join(" and ")}: ${said}. Commit it so every scan keeps it.`);
+    return 0;
+  } catch (e) {
+    if (e instanceof GlossaryError) {
+      io.err(e.message);
+      return e.code === "invalid" ? 2 : 1;
+    }
+    throw e;
+  }
+}
+async function glossaryDefine(root, term, definition, o, io) {
+  if (!term || !definition || !o.by) {
+    io.err('Usage: atticus glossary define <term> "<definition>" [--by <handle>] [--owner <team>]');
+    return 2;
+  }
+  return decide(root, io, (g) => {
+    const existing = g.terms.find((t) => t.id === resolveTermId(term));
+    return [
+      defineDecision(term, definition, {
+        by: o.by,
+        ...o.owner ? { owner: o.owner } : {},
+        ...existing ? { existing } : {}
+      })
+    ];
+  }, `${resolveTermId(term)} is defined and asserted`);
+}
+async function glossaryLink(root, term, recordId, o, io) {
+  if (!term || !recordId || !o.by) {
+    io.err("Usage: atticus glossary link <term> <record-id | schema#field> [--by <handle>]");
+    return 2;
+  }
+  return decide(root, io, (g) => {
+    const id = resolveTermId(term);
+    const t = g.terms.find((x) => x.id === id);
+    if (!t)
+      throw new GlossaryError("not-found", `There is no term ${id}. Define it first: atticus glossary define`);
+    return [linkDecision(t, recordId, g.base, { by: o.by })];
+  }, `${recordId} is linked to ${resolveTermId(term)}`);
+}
+async function glossaryAlias(root, term, names, o, io) {
+  if (!term || !names.length || !o.by) {
+    io.err('Usage: atticus glossary alias <term> "<other name>"... [--by <handle>]');
+    return 2;
+  }
+  return decide(root, io, (g) => {
+    const id = resolveTermId(term);
+    const before = g.build.entries.find((e) => e.id === id)?.aliases ?? [];
+    return [aliasDecision(id, [...before, ...names], { by: o.by })];
+  }, `${names.join(", ")} ${names.length === 1 ? "is another name" : "are other names"} for ${resolveTermId(term)}`);
+}
+
+export {
+  archiveGate,
+  testsGenerate,
+  traceCommand,
+  ciDrift,
+  ciSnippet,
+  ciArchiveGate,
+  glossaryList,
+  glossaryScan,
+  completeGlossaryScan,
+  glossaryDefine,
+  glossaryLink,
+  glossaryAlias
+};