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

package/dist/chunk-SETWVXOJ.js

@@ -0,0 +1,2078 @@
+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 {
+  upgradeCommand
+} from "./chunk-72TXNLOC.js";
+import {
+  table
+} from "./chunk-VOGCSYOI.js";
+import {
+  generateAssistantFiles
+} from "./chunk-V5PKHHQQ.js";
+import {
+  changeStore
+} from "./chunk-56YQ6ROQ.js";
+import {
+  fileStepStore
+} from "./chunk-7JUKDRSZ.js";
+import {
+  readCatalog,
+  scanEstate,
+  writeCatalog
+} from "./chunk-OLWFG75W.js";
+import {
+  buildContextPack,
+  formatOf,
+  screenText
+} from "./chunk-CNUKCS2T.js";
+import {
+  AgentDefinition,
+  CORE_ROLES,
+  Finding,
+  LIFECYCLE_STATES,
+  LifecycleState,
+  RecordId,
+  catalogDirOf,
+  external_exports,
+  orgPackDirOf,
+  recordReferences,
+  require_dist,
+  stateDirOf,
+  toCanonicalYaml
+} from "./chunk-S2A7YC3Q.js";
+import {
+  __toESM
+} from "./chunk-TV45EUGM.js";
+
+// packages/learn/dist/lessons.js
+var import_yaml = __toESM(require_dist(), 1);
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var __atticus_import_meta_url = __atticusUrl("packages/learn/dist/lessons.js");
+var LESSON_SCHEMA_VERSION = 1;
+var Truth = external_exports.discriminatedUnion("from", [
+  /** Components that read a table (Table.readers). */
+  external_exports.strictObject({ from: external_exports.literal("table-readers"), id: RecordId }),
+  /** Components that call a component, optionally only through one route kind. */
+  external_exports.strictObject({
+    from: external_exports.literal("interface-callers"),
+    to: RecordId,
+    via: external_exports.string().optional()
+  }),
+  /** The owner of a system. */
+  external_exports.strictObject({ from: external_exports.literal("system-owner"), id: RecordId }),
+  /** Systems with no owner in the catalog. */
+  external_exports.strictObject({ from: external_exports.literal("systems-without-owner") }),
+  /** Files under a folder the ingested-content defences rate medium or high. */
+  external_exports.strictObject({ from: external_exports.literal("flagged-files"), path: external_exports.string().min(1) }),
+  /** A change's state. */
+  external_exports.strictObject({ from: external_exports.literal("change-state"), change: RecordId }),
+  /** The feature an entry point belongs to. */
+  external_exports.strictObject({ from: external_exports.literal("feature-of"), entryPoint: RecordId }),
+  /** The pattern code a change's interfaces.md names that the org pack doesn't know. */
+  external_exports.strictObject({ from: external_exports.literal("unknown-pattern"), change: RecordId }),
+  /** Stories of a change with no acceptance criteria. */
+  external_exports.strictObject({ from: external_exports.literal("stories-without-criteria"), change: RecordId }),
+  /** A fixed answer, for questions the files can't decide (yes/no, a name on a diagram). */
+  external_exports.strictObject({ from: external_exports.literal("fixed"), values: external_exports.array(external_exports.string().min(1)).min(1) })
+]);
+var Check = external_exports.lazy(() => external_exports.discriminatedUnion("type", [
+  external_exports.strictObject({
+    type: external_exports.literal("catalog-has"),
+    kind: external_exports.string().min(1),
+    id: external_exports.string().optional(),
+    min: external_exports.number().int().positive().optional()
+  }),
+  external_exports.strictObject({ type: external_exports.literal("index-built") }),
+  external_exports.strictObject({
+    type: external_exports.literal("file"),
+    path: external_exports.string().min(1),
+    contains: external_exports.array(external_exports.string()).optional(),
+    notContains: external_exports.array(external_exports.string()).optional()
+  }),
+  external_exports.strictObject({
+    type: external_exports.literal("files"),
+    dir: external_exports.string().min(1),
+    suffix: external_exports.string().optional(),
+    min: external_exports.number().int().positive().optional()
+  }),
+  external_exports.strictObject({
+    type: external_exports.literal("curated-decision"),
+    action: external_exports.string().min(1),
+    target: external_exports.string().min(1),
+    includes: external_exports.string().optional()
+  }),
+  external_exports.strictObject({
+    type: external_exports.literal("record"),
+    kind: external_exports.string().min(1),
+    id: external_exports.string().min(1),
+    where: external_exports.record(external_exports.string(), external_exports.string()).optional()
+  }),
+  external_exports.strictObject({ type: external_exports.literal("change-state"), change: RecordId, atLeast: LifecycleState }),
+  external_exports.strictObject({
+    type: external_exports.literal("findings"),
+    change: RecordId,
+    gate: external_exports.string().optional(),
+    rule: external_exports.string().optional(),
+    artifact: external_exports.string().optional(),
+    min: external_exports.number().int().min(0).optional(),
+    max: external_exports.number().int().min(0).optional(),
+    state: external_exports.string().optional(),
+    latest: external_exports.boolean().optional()
+  }),
+  external_exports.strictObject({ type: external_exports.literal("answer"), question: external_exports.string().min(1), truth: Truth }),
+  external_exports.strictObject({
+    type: external_exports.literal("steps"),
+    action: external_exports.string().optional(),
+    state: external_exports.enum(["open", "done"]).optional(),
+    min: external_exports.number().int().positive().optional()
+  }),
+  external_exports.strictObject({ type: external_exports.literal("all"), checks: external_exports.array(Check).min(1) })
+]));
+var LessonStep = external_exports.strictObject({
+  id: RecordId,
+  title: external_exports.string().min(1),
+  /** What to read and do, in Markdown. */
+  body: external_exports.string().min(1),
+  /** The commands to try, as arguments after `atticus` (the sandbox root is added). */
+  do: external_exports.array(external_exports.array(external_exports.string())).default([]),
+  /** Files to write for this step, when it asks the learner to write something (also the worked solution). */
+  solution: external_exports.strictObject({
+    answer: external_exports.string().optional(),
+    files: external_exports.array(external_exports.strictObject({ path: external_exports.string().min(1), content: external_exports.string() })).default([])
+  }).optional(),
+  check: Check,
+  /** Shown when the check fails. */
+  hint: external_exports.string().min(1)
+});
+var Lesson = external_exports.strictObject({
+  schemaVersion: external_exports.literal(LESSON_SCHEMA_VERSION),
+  id: RecordId,
+  /** A role id from roles.yaml (core or custom). */
+  role: RecordId,
+  title: external_exports.string().min(1),
+  summary: external_exports.string().min(1),
+  minutes: external_exports.number().int().positive(),
+  /** What the sandbox must have before the first step: "scan" scans it and builds the index. */
+  setup: external_exports.array(external_exports.enum(["scan"])).default([]),
+  intro: external_exports.string().min(1),
+  steps: external_exports.array(LessonStep).min(1),
+  outro: external_exports.string().min(1)
+}).superRefine((l, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const s of l.steps) {
+    if (seen.has(s.id))
+      ctx.addIssue({ code: "custom", path: ["steps"], message: `step ${s.id} appears twice` });
+    seen.add(s.id);
+  }
+});
+var LESSONS_DIR = join(dirname(fileURLToPath(__atticus_import_meta_url)), "..", "lessons");
+async function readDir(dir, label, out) {
+  let names;
+  try {
+    names = (await readdir(dir)).filter((n) => /\.ya?ml$/.test(n)).sort();
+  } catch {
+    return;
+  }
+  for (const n of names) {
+    try {
+      const r = Lesson.safeParse((0, import_yaml.parse)(await readFile(join(dir, n), "utf8")));
+      if (!r.success) {
+        out.problems.push(`${label}/${n}: ${r.error.issues.map((i) => `${i.path.join(".") || "(file)"} ${i.message}`).join("; ")}`);
+        continue;
+      }
+      const at = out.lessons.findIndex((l) => l.id === r.data.id);
+      const lesson = { ...r.data, source: `${label}/${n}` };
+      if (at >= 0)
+        out.lessons[at] = lesson;
+      else
+        out.lessons.push(lesson);
+    } catch (e) {
+      out.problems.push(`${label}/${n}: ${e.message.split("\n")[0]}`);
+    }
+  }
+}
+async function loadLessons(o = {}) {
+  const out = { lessons: [], problems: [] };
+  await readDir(o.dir ?? LESSONS_DIR, "lessons", out);
+  if (o.orgPackDir)
+    await readDir(join(o.orgPackDir, "learn", "lessons"), "org-pack/learn/lessons", out);
+  const order = (role) => {
+    if (role === "everyone")
+      return -1;
+    const i = CORE_ROLES.indexOf(role);
+    return i === -1 ? CORE_ROLES.length : i;
+  };
+  out.lessons.sort((a, b) => order(a.role) - order(b.role) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return out;
+}
+
+// packages/learn/dist/sandbox.js
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { appendFile, cp, mkdir, readdir as readdir2, readFile as readFile2, rm, stat, writeFile } from "node:fs/promises";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var __atticus_import_meta_url2 = __atticusUrl("packages/learn/dist/sandbox.js");
+var SANDBOX_MARKER = ".atticus-sandbox.json";
+var SEEDED_CHANGE = "add-transfer-limit";
+var SANDBOX_METAREPO = "forge/forge-metarepo";
+var SandboxError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SandboxError";
+  }
+};
+function findFixtures(start = dirname2(fileURLToPath2(__atticus_import_meta_url2))) {
+  let d = resolve(start);
+  for (; ; ) {
+    if (existsSync(join2(d, "fixtures", "forge", "README.md")))
+      return join2(d, "fixtures");
+    const up = dirname2(d);
+    if (up === d)
+      return void 0;
+    d = up;
+  }
+}
+var GIT_TIMEOUT_MS = 12e4;
+function git(cwd, args, timeoutMs, noHooks) {
+  return new Promise((done, fail2) => {
+    execFile("git", [
+      "-c",
+      "user.name=Atticus sandbox",
+      "-c",
+      "user.email=sandbox@example.com",
+      "-c",
+      "init.defaultBranch=main",
+      "-c",
+      "core.autocrlf=false",
+      "-c",
+      `core.hooksPath=${noHooks}`,
+      "-c",
+      "commit.gpgsign=false",
+      ...args
+    ], {
+      cwd,
+      timeout: timeoutMs,
+      windowsHide: true,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    }, (e, _out, err) => {
+      if (!e)
+        return done();
+      if (e.killed)
+        return fail2(new Error(`git took longer than ${timeoutMs / 1e3} s (git ${args[0]})`));
+      fail2(new Error(`${e.message.split("\n")[0]}${err ? `: ${err.trim()}` : ""}`));
+    }).stdin?.end();
+  });
+}
+var isEmptyDir = async (d) => {
+  try {
+    return (await readdir2(d)).length === 0;
+  } catch {
+    return true;
+  }
+};
+async function createSandbox(dir, o = {}) {
+  const fixtures = o.fixtures ?? findFixtures();
+  if (!fixtures || !existsSync(join2(fixtures, "forge")))
+    throw new SandboxError("The Forge fixture isn't here: the practice sandbox is built from fixtures/forge in the Atticus checkout.");
+  const target = resolve(dir);
+  if (existsSync(target) && !(await stat(target)).isDirectory())
+    throw new SandboxError(`${dir} is a file; give a new or empty folder.`);
+  if (!await isEmptyDir(target))
+    throw new SandboxError(`${dir} isn't empty; give a new or empty folder.`);
+  await mkdir(target, { recursive: true });
+  const forge = join2(fixtures, "forge");
+  const change = join2(fixtures, "forge-change");
+  await cp(join2(forge, "repos"), join2(target, "repos"), { recursive: true });
+  await cp(join2(forge, "inputs"), join2(target, "inputs"), { recursive: true });
+  const root = join2(target, "metarepo");
+  await cp(join2(forge, "metarepo"), root, { recursive: true });
+  await cp(join2(change, "org-pack"), join2(root, "org-pack"), { recursive: true });
+  await cp(join2(forge, "inputs"), join2(root, "inputs"), { recursive: true });
+  await cp(join2(change, "openspec", "changes", SEEDED_CHANGE), join2(root, "openspec", "changes", SEEDED_CHANGE), {
+    recursive: true
+  });
+  const runtime = join2(root, "org-pack", "runtime.yaml");
+  await writeFile(runtime, (await readFile2(runtime, "utf8")).replace(/^(\s*)gitHost:.*$/m, `$1gitHost: { type: manual, settings: { metarepo: ${SANDBOX_METAREPO} } }`), "utf8");
+  const repos = (await readdir2(join2(target, "repos"))).sort();
+  const timeout = o.gitTimeoutMs ?? GIT_TIMEOUT_MS;
+  const noHooks = join2(target, ".no-git-hooks").split("\\").join("/");
+  const run = (cwd, args) => git(cwd, args, timeout, noHooks);
+  for (const id of repos) {
+    const base = join2(root, "workspace", id);
+    await cp(join2(target, "repos", id), base, { recursive: true });
+    try {
+      await run(base, ["init", "-q"]);
+      await appendFile(join2(base, ".git", "config"), "[user]\n	name = Atticus sandbox\n	email = sandbox@example.com\n[commit]\n	gpgsign = false\n[tag]\n	gpgsign = false\n", "utf8");
+      await run(base, ["add", "-A"]);
+      await run(base, ["commit", "-q", "-m", "Forge fixture"]);
+      const remote = join2(target, "remotes", `${id}.git`);
+      await mkdir(dirname2(remote), { recursive: true });
+      await run(target, ["clone", "-q", "--bare", base, remote]);
+      await run(base, ["remote", "add", "origin", remote]);
+      await run(base, ["fetch", "-q", "origin"]);
+      await run(base, ["branch", "-q", "--set-upstream-to=origin/main", "main"]);
+    } catch (e) {
+      await rm(join2(base, ".git"), { recursive: true, force: true });
+      throw new SandboxError(`git couldn't set up the base clone of ${id}: ${e.message.split("\n")[0]}`);
+    }
+  }
+  await writeFile(join2(root, ".gitignore"), ["workspace/", ".index/", ".runs/", ".learn/", ".evals/", ""].join("\n"), "utf8");
+  await writeFile(join2(root, "README.md"), [
+    "# Atticus practice sandbox",
+    "",
+    "A throwaway metarepo built from the invented Forge ecosystem. Everything here is made up;",
+    "every adapter is a mock but the Git host, whose steps you record with `atticus todo done`.",
+    "Try anything, then delete the folder.",
+    "",
+    "Run commands from this folder, or add `--root " + root.replace(/\\/g, "/") + "`.",
+    ""
+  ].join("\n"), "utf8");
+  const info = { dir: target, root, repos, change: SEEDED_CHANGE };
+  await writeFile(join2(root, SANDBOX_MARKER), JSON.stringify({ sandbox: 1, createdAt: (o.now ?? /* @__PURE__ */ new Date()).toISOString(), repos, change: SEEDED_CHANGE }, null, 2) + "\n", "utf8");
+  return info;
+}
+async function isSandbox(root) {
+  try {
+    const m = JSON.parse(await readFile2(join2(root, SANDBOX_MARKER), "utf8"));
+    return m.sandbox === 1;
+  } catch {
+    return false;
+  }
+}
+
+// packages/learn/dist/checks.js
+var import_yaml2 = __toESM(require_dist(), 1);
+import { existsSync as existsSync2 } from "node:fs";
+import { readdir as readdir3, readFile as readFile3, stat as stat2 } from "node:fs/promises";
+import { join as join3, relative, sep } from "node:path";
+var ok = (message) => ({ pass: true, message });
+var no = (message) => ({ pass: false, message });
+async function catalog(root) {
+  const dir = catalogDirOf(root);
+  const g = await readCatalog(join3(dir, "generated"), { cacheRoot: root });
+  const c = await readCatalog(join3(dir, "curated"), { cacheRoot: root });
+  return [...g.records, ...c.records];
+}
+function answerSet(text) {
+  return [
+    ...new Set(text.toLowerCase().split(/[\s,;]+|\band\b/).map((w) => w.replace(/^["'`([{<]+|["'`)\]}>.:!?]+$/g, "")).filter(Boolean))
+  ].sort();
+}
+async function walk(dir) {
+  const out = [];
+  const go = async (d) => {
+    let entries;
+    try {
+      entries = await readdir3(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries.sort((a, b) => a.name < b.name ? -1 : 1)) {
+      const full = join3(d, e.name);
+      if (e.isDirectory())
+        await go(full);
+      else
+        out.push(full);
+    }
+  };
+  await go(dir);
+  return out;
+}
+async function truthOf(root, t) {
+  switch (t.from) {
+    case "fixed":
+      return answerSet(t.values.join(" "));
+    case "table-readers": {
+      const r = (await catalog(root)).find((x) => x.kind === "Table" && x.id === t.id);
+      return r && r.kind === "Table" ? [...r.readers].sort() : [];
+    }
+    case "interface-callers": {
+      const rs = (await catalog(root)).filter((x) => x.kind === "Interface" && x.to === t.to && (!t.via || x.via === t.via));
+      return [...new Set(rs.map((r) => r.from))].sort();
+    }
+    case "system-owner": {
+      const r = (await catalog(root)).find((x) => x.kind === "System" && x.id === t.id);
+      return r && r.kind === "System" && r.owner ? [r.owner] : [];
+    }
+    case "systems-without-owner":
+      return (await catalog(root)).filter((x) => x.kind === "System" && !x.owner).map((x) => x.id).sort();
+    case "flagged-files": {
+      const base = join3(root, t.path);
+      const out = [];
+      for (const f of await walk(base)) {
+        const text = await readFile3(f, "utf8").catch(() => "");
+        const rel = relative(root, f).split(sep).join("/");
+        const s = screenText(text, { format: formatOf("document", rel) });
+        if (s.risk === "medium" || s.risk === "high")
+          out.push(rel.split("/").pop().replace(/\.[a-z0-9]+$/i, "").toLowerCase());
+      }
+      return out.sort();
+    }
+    case "change-state": {
+      const c = await changeStore(root).tryRead(t.change);
+      return c ? [c.state] : [];
+    }
+    case "feature-of": {
+      const f = (await catalog(root)).find((x) => x.kind === "Capability" && x.entryPoints.includes(t.entryPoint));
+      return f ? [f.id] : [];
+    }
+    case "unknown-pattern": {
+      const text = await readFile3(join3(root, "openspec/changes", t.change, "interfaces.md"), "utf8").catch(() => "");
+      const known = new Set((await readdir3(join3(root, "org-pack", "patterns")).catch(() => [])).map((f) => f.replace(/\.ya?ml$/, "").toLowerCase()));
+      const codes = [...text.matchAll(/\b([A-Z]\.[A-Z]{2,5}(?:\.[A-Z]{2,5})*)\b/g)].map((m) => m[1].toLowerCase());
+      return [...new Set(codes.filter((c) => !known.has(c)))].sort();
+    }
+    case "stories-without-criteria": {
+      const dir = join3(root, "openspec/changes", t.change, "stories");
+      const out = [];
+      for (const f of (await readdir3(dir).catch(() => [])).filter((n) => n.endsWith(".md")).sort()) {
+        const text = await readFile3(join3(dir, f), "utf8");
+        const section = /## Acceptance criteria\s*\n([\s\S]*?)(\n## |$)/.exec(text)?.[1] ?? "";
+        if (!/^\s*-\s*Given\b/im.test(section))
+          out.push(f.replace(/\.md$/, ""));
+      }
+      return out;
+    }
+  }
+}
+var rank = (s) => s === "post-release-review" ? LIFECYCLE_STATES.indexOf("released") + 0.5 : LIFECYCLE_STATES.indexOf(s);
+async function findingFiles(root, change) {
+  const dir = join3(root, "openspec/changes", change, "review");
+  const out = [];
+  for (const f of await walk(dir)) {
+    if (!f.endsWith(".yaml") || f.endsWith("round.yaml"))
+      continue;
+    const rel = relative(dir, f).split(sep);
+    try {
+      const v = (0, import_yaml2.parse)(await readFile3(f, "utf8"));
+      if (v && typeof v === "object" && "rule" in v)
+        out.push({ ...v, _gate: rel[0], _round: rel[1] });
+    } catch {
+    }
+  }
+  return out;
+}
+async function runCheck(root, check, answer) {
+  switch (check.type) {
+    case "all": {
+      for (const c of check.checks) {
+        const r = await runCheck(root, c, answer);
+        if (!r.pass)
+          return r;
+      }
+      return ok("Done.");
+    }
+    case "catalog-has": {
+      const rs = (await catalog(root)).filter((r) => r.kind === check.kind && (!check.id || r.id === check.id));
+      const min = check.min ?? 1;
+      return rs.length >= min ? ok(`The catalog has ${rs.length} ${check.kind} record${rs.length === 1 ? "" : "s"}${check.id ? ` (${check.id})` : ""}.`) : no(`The catalog has ${rs.length} ${check.kind} record${rs.length === 1 ? "" : "s"}${check.id ? ` named ${check.id}` : ""}; it needs ${min}.`);
+    }
+    case "index-built":
+      return existsSync2(join3(stateDirOf(root), ".index", "catalog.sqlite")) ? ok("The index is built.") : no("There is no index yet.");
+    case "file": {
+      const p = join3(root, ...check.path.split("/"));
+      let text;
+      try {
+        if (!(await stat2(p)).isFile())
+          return no(`${check.path} isn't a file.`);
+        text = await readFile3(p, "utf8");
+      } catch {
+        return no(`${check.path} doesn't exist yet.`);
+      }
+      for (const c of check.contains ?? [])
+        if (!text.includes(c))
+          return no(`${check.path} doesn't say "${c}" yet.`);
+      for (const c of check.notContains ?? [])
+        if (text.includes(c))
+          return no(`${check.path} still says "${c}".`);
+      return ok(`${check.path} is there.`);
+    }
+    case "files": {
+      const fs = (await walk(join3(root, ...check.dir.split("/")))).filter((f) => !check.suffix || f.endsWith(check.suffix));
+      const min = check.min ?? 1;
+      return fs.length >= min ? ok(`${check.dir} has ${fs.length} file${fs.length === 1 ? "" : "s"}.`) : no(`${check.dir} has ${fs.length} file${fs.length === 1 ? "" : "s"}${check.suffix ? ` ending ${check.suffix}` : ""}; it needs ${min}.`);
+    }
+    case "curated-decision": {
+      const d = (await catalog(root)).find((r) => r.kind === "CuratedDecision" && r.action === check.action && r.target === check.target && (!check.includes || JSON.stringify(r.value ?? null).toLowerCase().includes(check.includes.toLowerCase())));
+      return d ? ok(`A ${check.action} decision on ${check.target} is recorded (${d.id}).`) : no(`No ${check.action} decision on ${check.target}${check.includes ? ` naming "${check.includes}"` : ""} is recorded yet.`);
+    }
+    case "record": {
+      const r = (await catalog(root)).find((x) => x.kind === check.kind && x.id === check.id);
+      if (!r)
+        return no(`There is no ${check.kind} ${check.id} yet.`);
+      for (const [k, v] of Object.entries(check.where ?? {}))
+        if (String(r[k] ?? "") !== v)
+          return no(`${check.kind} ${check.id} has ${k} ${String(r[k] ?? "unset")}, not ${v}.`);
+      return ok(`${check.kind} ${check.id} is there.`);
+    }
+    case "change-state": {
+      const c = await changeStore(root).tryRead(check.change).catch(() => void 0);
+      if (!c)
+        return no(`There is no change ${check.change} yet.`);
+      return c.state !== "returned" && rank(c.state) >= rank(check.atLeast) ? ok(`${check.change} is in ${c.state}.`) : no(`${check.change} is in ${c.state}; it needs to reach ${check.atLeast}.`);
+    }
+    case "findings": {
+      const all = await findingFiles(root, check.change);
+      const newest = /* @__PURE__ */ new Map();
+      for (const f of all)
+        newest.set(String(f._gate), Math.max(newest.get(String(f._gate)) ?? 0, Number(f._round)));
+      const fs = all.filter((f) => (!check.latest || Number(f._round) === newest.get(String(f._gate))) && (!check.gate || f._gate === check.gate) && (!check.rule || f.rule === check.rule) && (!check.artifact || f.artifact === check.artifact) && (!check.state || f.state === check.state));
+      const min = check.min ?? 1;
+      const what = `finding${fs.length === 1 ? "" : "s"}${check.rule ? ` for ${check.rule}` : ""}${check.gate ? ` at ${check.gate}` : ""}`;
+      if (fs.length < min)
+        return no(`${check.change} has ${fs.length} ${what}; run the critic first.`);
+      if (check.max !== void 0 && fs.length > check.max)
+        return no(`${check.change} still has ${fs.length} ${what}.`);
+      return ok(`${check.change} has ${fs.length} ${what}.`);
+    }
+    case "answer": {
+      if (answer === void 0 || !answer.trim())
+        return no(`Answer the question: ${check.question}`);
+      const want = await truthOf(root, check.truth);
+      if (!want.length)
+        return no("The sandbox can't answer this yet: do the steps before it first.");
+      const got = answerSet(answer);
+      const missing = want.filter((w) => !got.includes(w));
+      const extra = got.filter((g) => !want.includes(g));
+      if (!missing.length && !extra.length)
+        return ok("Right.");
+      return no(missing.length && extra.length ? "Not quite: some of that is wrong and something is missing." : missing.length ? `Not quite: there is more (${missing.length} missing).` : "Not quite: some of that isn't right.");
+    }
+    case "steps": {
+      const steps = await fileStepStore(root).list({
+        ...check.action ? { action: check.action } : {},
+        ...check.state ? { state: check.state } : {}
+      });
+      const min = check.min ?? 1;
+      return steps.length >= min ? ok(`${steps.length} manual step${steps.length === 1 ? "" : "s"} recorded.`) : no(`No manual step${check.action ? ` (${check.action})` : ""}${check.state ? ` ${check.state}` : ""} yet.`);
+    }
+  }
+}
+
+// packages/learn/dist/engine.js
+import { mkdir as mkdir2, readFile as readFile4, rename, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname3, join as join4 } from "node:path";
+var LearnError = class extends Error {
+  code;
+  constructor(message, code = "usage") {
+    super(message);
+    this.code = code;
+    this.name = "LearnError";
+  }
+};
+var progressPath = (root) => join4(stateDirOf(root), ".learn", "progress.json");
+async function readProgress(root) {
+  try {
+    const p = JSON.parse(await readFile4(progressPath(root), "utf8"));
+    if (p.schemaVersion === 1 && p.lessons)
+      return p;
+  } catch {
+  }
+  return { schemaVersion: 1, lessons: {} };
+}
+async function writeProgress(root, p) {
+  const f = progressPath(root);
+  await mkdir2(dirname3(f), { recursive: true });
+  await writeFile2(`${f}.tmp`, JSON.stringify(p, null, 2) + "\n", "utf8");
+  await rename(`${f}.tmp`, f);
+}
+var iso = (d) => d.toISOString().replace(/\.\d{3}Z$/, "Z");
+async function lessonsFor(root) {
+  return loadLessons(root ? { orgPackDir: orgPackDirOf(root) } : {});
+}
+async function findLesson(root, roleOrLesson) {
+  const { lessons } = await lessonsFor(root);
+  const l = lessons.find((x) => x.id === roleOrLesson) ?? lessons.find((x) => x.role === roleOrLesson);
+  if (!l) {
+    const roles = [...new Set(lessons.map((x) => x.role))].join(", ");
+    throw new LearnError(`No lesson or role ${roleOrLesson}. Roles with lessons: ${roles}.`, "not-found");
+  }
+  return l;
+}
+async function requireSandbox(root) {
+  if (!await isSandbox(root))
+    throw new LearnError(`${root} isn't a practice sandbox. Make one with atticus sandbox create <dir> and run lessons there.`, "not-sandbox");
+}
+async function startLesson(root, roleOrLesson, o = {}) {
+  await requireSandbox(root);
+  const lesson = await findLesson(root, roleOrLesson);
+  const p = await readProgress(root);
+  const resumed = !!p.lessons[lesson.id];
+  const setup = [];
+  if (!resumed) {
+    for (const s of lesson.setup) {
+      if (s === "scan") {
+        const scan = await scanEstate({ root });
+        await writeCatalog(join4(catalogDirOf(root), "generated"), scan.records);
+        setup.push(`Scanned the sandbox: ${scan.records.length} records in catalog/generated.`);
+      }
+    }
+    p.lessons[lesson.id] = { startedAt: iso(o.now ?? /* @__PURE__ */ new Date()), steps: {} };
+  }
+  p.current = lesson.id;
+  await writeProgress(root, p);
+  const done = p.lessons[lesson.id].steps;
+  const step = lesson.steps.find((s) => !done[s.id]);
+  return { lesson, ...step ? { step } : {}, setup, resumed };
+}
+async function checkStep(root, o = {}) {
+  await requireSandbox(root);
+  const p = await readProgress(root);
+  const id = o.lesson ?? p.current;
+  if (!id)
+    throw new LearnError("No lesson started. Start one with atticus learn start <role|lesson>.");
+  const lesson = await findLesson(root, id);
+  const lp = p.lessons[lesson.id] ??= { startedAt: iso(o.now ?? /* @__PURE__ */ new Date()), steps: {} };
+  const step = o.step ? lesson.steps.find((s) => s.id === o.step) : lesson.steps.find((s) => !lp.steps[s.id]) ?? lesson.steps.at(-1);
+  if (!step)
+    throw new LearnError(`Lesson ${lesson.id} has no step ${o.step}.`, "not-found");
+  const result = await runCheck(root, step.check, o.answer);
+  if (result.pass && !lp.steps[step.id])
+    lp.steps[step.id] = {
+      passedAt: iso(o.now ?? /* @__PURE__ */ new Date()),
+      ...o.answer ? { answer: o.answer } : {}
+    };
+  const next = lesson.steps.find((s) => !lp.steps[s.id]);
+  const completed = !next;
+  if (completed && !lp.completedAt)
+    lp.completedAt = iso(o.now ?? /* @__PURE__ */ new Date());
+  p.current = lesson.id;
+  await writeProgress(root, p);
+  return { lesson, step, result, ...next ? { next } : {}, completed };
+}
+
+// packages/learn/dist/commands.js
+var COMMANDS = [
+  {
+    name: "scan",
+    usage: "atticus scan [--repos a,b] [--full] [--dry-run] [--json]",
+    what: "Reads every repo's code and config (never runs it) and writes what it finds as catalog records: systems, components, endpoints, interfaces, tables, settings.",
+    who: ["developer", "architect", "platform-lead"],
+    changes: "catalog/generated (the records found in code)",
+    related: ["catalog diff", "index rebuild"]
+  },
+  {
+    name: "map",
+    usage: "atticus map <repo> [--estimate] [--handoff | --copy [--answer <file>] | --mode m] [--next] [--max-tokens n] [--force]",
+    what: "Has your assistant read a repo into facts, each citing its file and line: an agentic assistant follows /atticus-map; one without tools gets the repo in batches that fit its model, each answer checked before the next.",
+    who: ["developer", "architect"],
+    changes: "facts/<repo>.jsonl and the questions the reader raised",
+    related: ["verify", "map render"]
+  },
+  {
+    name: "map render",
+    usage: "atticus map render <repo> [--json]",
+    what: "Renders the repo's map from the catalog: map.md, a page per flow with its sequence diagram, and an OpenAPI file per component.",
+    who: ["developer", "architect"],
+    changes: "map/<repo>/ (the rendered pages)",
+    related: ["map", "verify"]
+  },
+  {
+    name: "join",
+    usage: "atticus join [--json]",
+    what: "Follows each repo's flows into the flows their calls reach in other repos, through the calls the repos' verified facts join (atticus verify <repo> --write makes those joins), and asks which repo answers a host nobody lists. The same command as atticus estate join.",
+    who: ["architect", "developer"],
+    changes: "specs/estate.yaml, and a question for each host no repo lists",
+    related: ["verify", "estate flow"]
+  },
+  {
+    name: "probe",
+    usage: "atticus probe [--assistant id] [--max-tokens n] [--json]",
+    what: "Measures what your assistant can do here, so the tier it reads a repo at is measured, not read off runtime.yaml: it writes a file holding a code and says to run /atticus-probe, which asks the assistant to open the file, write the code back and run atticus probe answer itself.",
+    who: ["developer", "architect", "platform-lead"],
+    changes: "the probe's files in the run folder (.runs/probe/), on this machine",
+    related: ["probe answer", "map"]
+  },
+  {
+    name: "probe answer",
+    usage: "atticus probe answer <code|none> [--pasted] [--max-tokens n] [--json]",
+    what: "Checks the assistant's answer to the probe: the right code means it opened the file, the code in answer.txt that it wrote one, and an answer not --pasted that it ran a command. A wrong code records nothing. The model's limit is what --max-tokens states; nothing guesses it.",
+    who: ["developer", "architect", "platform-lead"],
+    changes: ".atticus/probe/<assistant>.yaml, on this machine only (never committed); doctor, init, adopt and map --estimate use it",
+    related: ["probe", "map"]
+  },
+  {
+    name: "verify",
+    usage: "atticus verify <repo> [--write] [--dir path] [--commit sha] [--routed a,b] [--json]",
+    what: "Checks every fact in a repo's facts file against the line it cites, keeps the ones that hold, writes the rest with why to <repo>.rejected.jsonl, and says which source files no fact has read yet. With --write the kept facts become catalog records.",
+    who: ["developer", "architect"],
+    changes: "facts/ (the kept facts, the rejected ones, the coverage); catalog/generated with --write",
+    related: ["map", "map render"]
+  },
+  {
+    name: "catalog validate",
+    usage: "atticus catalog validate <dir> [--fix]",
+    what: "Checks record files against the catalog schema, their place and their canonical form.",
+    who: ["platform-lead"],
+    changes: "nothing, or the files' layout with --fix"
+  },
+  {
+    name: "catalog diff",
+    usage: "atticus catalog diff <a> <b>",
+    what: "Compares two catalog folders and lists what was added, removed or changed.",
+    who: ["architect", "platform-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "query",
+    usage: 'atticus query "<query>" [--limit n] [--json]',
+    what: 'Finds records with a short query such as "kind:interface via:gateway".',
+    who: ["developer", "architect", "business-analyst"],
+    changes: "nothing",
+    related: ["impact"]
+  },
+  {
+    name: "impact",
+    usage: "atticus impact <id> [--depth n] [--json]",
+    what: "Shows what a change to one record reaches: who calls it, who reads it, their owners and the open questions on the way.",
+    who: ["architect", "developer", "team-lead"],
+    changes: "nothing",
+    related: ["query"]
+  },
+  {
+    name: "index rebuild",
+    usage: "atticus index rebuild",
+    what: "Rebuilds the local search index from the catalog files. Queries rebuild it on their own when files change.",
+    who: ["developer"],
+    changes: "the local index (.index/), never committed"
+  },
+  {
+    name: "reconcile",
+    usage: "atticus reconcile [diagram...] [--json]",
+    what: "Compares the architects' diagrams with what the code says: missing edges, wrong routes, names that need an alias.",
+    who: ["architect"],
+    changes: "nothing",
+    related: ["alias", "triage"]
+  },
+  {
+    name: "alias",
+    usage: 'atticus alias "<name>" <id> [--reason text]',
+    what: "Records that a name used on diagrams or in documents means a catalog id, so they line up from now on.",
+    who: ["architect"],
+    changes: "a curated decision in catalog/curated"
+  },
+  {
+    name: "sources add",
+    usage: "atticus sources add <type> <location>",
+    what: "Prints the sources.yaml entry for a wiki; the org pack changes by pull request.",
+    who: ["platform-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "sources sync",
+    usage: "atticus sources sync [--json]",
+    what: "Reads the wikis: stale pages, pages that contradict code, facts only a document gives.",
+    who: ["architect", "platform-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "patterns scan",
+    usage: "atticus patterns scan [--json]",
+    what: "Finds integration patterns written in the wikis and compares them with the org pack.",
+    who: ["architect"],
+    changes: "nothing"
+  },
+  {
+    name: "coverage",
+    usage: "atticus coverage [--json]",
+    what: "What the catalog knows for each system and area: verified from code, only from documents, or unknown.",
+    who: ["platform-lead", "architect"],
+    changes: "nothing",
+    related: ["questions"]
+  },
+  {
+    name: "questions",
+    usage: "atticus questions [--json]",
+    what: "The knowledge gaps and the question to send each system's owner to close them.",
+    who: ["architect", "platform-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "intake add",
+    usage: "atticus intake add <files...>",
+    what: "Drops documents, specs, diagrams or replies into inputs/inbox; the next scan reads them as data.",
+    who: ["business-analyst", "architect", "product-owner"],
+    changes: "inputs/inbox"
+  },
+  {
+    name: "intake list",
+    usage: "atticus intake list [--json]",
+    what: "What intake read from inputs/: kinds, systems, duplicates and versions.",
+    who: ["business-analyst"],
+    changes: "nothing"
+  },
+  {
+    name: "triage",
+    usage: "atticus triage [--json]",
+    what: "What needs a person's decision: unknown names, documents that contradict code, edges read from images.",
+    who: ["architect"],
+    changes: "nothing",
+    related: ["triage decide"]
+  },
+  {
+    name: "triage decide",
+    usage: "atticus triage decide <item> <n> [--reason text]",
+    what: "Chooses an option for a triage item and records it as a curated decision.",
+    who: ["architect"],
+    changes: "a curated decision in catalog/curated"
+  },
+  {
+    name: "diagram render",
+    usage: "atticus diagram render <view|file> [--focus id] [--format mermaid|drawio] [--out file]",
+    what: "Draws a view of the catalog (context, container, data, event, sequence) as Mermaid or draw.io.",
+    who: ["architect", "designer"],
+    changes: "the file named with --out"
+  },
+  {
+    name: "diagram library",
+    usage: "atticus diagram library <file>",
+    what: "Writes the draw.io shape library.",
+    who: ["architect"],
+    changes: "the file named"
+  },
+  {
+    name: "stub serve",
+    usage: "atticus stub serve <spec|id>",
+    what: "Serves a fake of an API from its spec or the catalog, on this machine only.",
+    who: ["developer", "qa"],
+    changes: "nothing"
+  },
+  {
+    name: "stub check",
+    usage: "atticus stub check <spec>",
+    what: "Says which operations of a spec have examples a stub can answer with.",
+    who: ["developer", "qa"],
+    changes: "nothing"
+  },
+  {
+    name: "dialect new",
+    usage: "atticus dialect new <name> --from <repo>...",
+    what: "Starts a dialect (rules for an in-house framework) from sample repos.",
+    who: ["platform-lead", "developer"],
+    changes: "org-pack/dialects/<name>.yaml"
+  },
+  {
+    name: "dialect test",
+    usage: "atticus dialect test <name>",
+    what: "Runs a dialect's own tests.",
+    who: ["platform-lead", "developer"],
+    changes: "nothing"
+  },
+  {
+    name: "dialect run",
+    usage: "atticus dialect run <name> <repo> [--json]",
+    what: "Shows the records a dialect produces from one repo.",
+    who: ["platform-lead", "developer"],
+    changes: "nothing"
+  },
+  {
+    name: "dialect kit",
+    usage: "atticus dialect kit [dir]",
+    what: "Exports the dialect build kit for an assistant.",
+    who: ["platform-lead"],
+    changes: "the folder named"
+  },
+  {
+    name: "change new",
+    usage: 'atticus change new "<title>" --type <type>',
+    what: "Starts a change from its type's template; it begins in define with a brief to write.",
+    who: ["product-owner"],
+    changes: "openspec/changes/<id>/"
+  },
+  {
+    name: "next",
+    usage: "atticus next [--all] [--json]",
+    what: "The next step to take in the metarepo, with the slash command to type in your assistant and why it is next.",
+    who: ["product-owner", "architect", "developer", "team-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "guide",
+    usage: "atticus guide <system>",
+    what: "A system's guide, from the catalog: its parts, calls, data and owners, every fact citing code, and what it doesn't know yet.",
+    who: ["developer", "architect"],
+    changes: "nothing"
+  },
+  {
+    name: "watch",
+    usage: "atticus watch [<change>] [--off] [--json]",
+    what: "Follow a change without being on it; your digest says how it is doing. With no change, how each one you watch is doing.",
+    who: ["product-owner", "team-lead", "delivery-lead"],
+    changes: "your own .atticus/me.yaml (never committed)"
+  },
+  {
+    name: "change knowledge",
+    usage: "atticus change knowledge <id> [--confirm id] [--exclude id] [--json]",
+    what: "Lists the patterns, standards, decisions, processes, requests and wiki and document sections that apply to a change, picked by each of its stages from the feature stage on, with the near-misses; confirm one so later stages pick it, or exclude it so they leave it out.",
+    who: ["developer", "business-analyst", "architect"],
+    changes: "the change's knowledge.yaml",
+    related: ["change status"]
+  },
+  {
+    name: "change status",
+    usage: "atticus change status <id> [--json]",
+    what: "Where a change is, what it needs next, what blocks it, its risk, the hand-off PR to merge and the tests it needs.",
+    who: ["product-owner", "team-lead", "delivery-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "change handoff",
+    usage: "atticus change handoff <id> --approve",
+    what: "Opens the hand-off pull request for the phase (Send to architecture, Approve design, Plan ready, ...); merging it approves the gate. Without --approve it says what it would open. Refused while blocking findings are open.",
+    who: ["product-owner", "architect", "team-lead"],
+    changes: "a hand-off PR on the Git host and change.yaml",
+    approval: true
+  },
+  {
+    name: "change sync",
+    usage: "atticus change sync <id> [--approve]",
+    what: "Reads the hand-off PR; once it is merged the change moves to the next phase. With --approve it merges a PR that is approved and meets the Git host's rules.",
+    who: ["product-owner", "architect", "team-lead"],
+    changes: "the PR (merge) and change.yaml",
+    approval: true
+  },
+  {
+    name: "change return",
+    usage: 'atticus change return <id> --reason "<why>" --approve',
+    what: "Sends a change back to the product owner.",
+    who: ["architect", "team-lead"],
+    changes: "change.yaml and the hand-off PR",
+    approval: true
+  },
+  {
+    name: "change archive",
+    usage: "atticus change archive <id>",
+    what: "Archives a released change after the archive gate passes.",
+    who: ["delivery-lead"],
+    changes: "the change folder"
+  },
+  {
+    name: "change list",
+    usage: "atticus change list [--json]",
+    what: "Every change and its state.",
+    who: ["team-lead", "delivery-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "change conflicts",
+    usage: "atticus change conflicts [--json]",
+    what: "Open changes that touch the same systems, records or repos.",
+    who: ["team-lead", "architect"],
+    changes: "nothing"
+  },
+  {
+    name: "critic",
+    usage: "atticus critic <change> [--gate g] [--lens l] [--json]",
+    what: "Reviews a change at a gate: rule checks first (free, repeatable), then AI lenses on what passed. Findings come with evidence and a fix.",
+    who: ["architect", "business-analyst", "product-owner"],
+    changes: "review/<gate>/<round>/ finding files"
+  },
+  {
+    name: "critic stats",
+    usage: "atticus critic stats [--json]",
+    what: "How often each rule's findings are dismissed or waived, with a suggested checklist change.",
+    who: ["platform-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "findings",
+    usage: "atticus findings <change> [--json]",
+    what: "The change's findings by gate and round.",
+    who: ["architect", "business-analyst"],
+    changes: "nothing"
+  },
+  {
+    name: "finding",
+    usage: "atticus finding <change> <id> <action>",
+    what: "Acts on a finding: apply its fix, edit and apply, not relevant (with a reason), waive (blocking only, with a reason) or ask its owner. It is recorded with you and reaches main with the hand-off PR.",
+    who: ["architect", "business-analyst"],
+    changes: "the finding file and, for apply, the artifact"
+  },
+  {
+    name: "feature list",
+    usage: "atticus feature list [--json]",
+    what: "Features Atticus found in code, named by people or proposed by AI.",
+    who: ["product-owner", "designer", "business-analyst"],
+    changes: "nothing"
+  },
+  {
+    name: "feature show",
+    usage: "atticus feature show <id> [--json]",
+    what: "A feature's entry points, flow, owner, links and gaps.",
+    who: ["product-owner", "designer"],
+    changes: "nothing"
+  },
+  {
+    name: "feature name",
+    usage: 'atticus feature name <id> "<name>"',
+    what: "Confirms or corrects a feature's name in the words its users use.",
+    who: ["product-owner", "designer"],
+    changes: "a curated decision in catalog/curated"
+  },
+  {
+    name: "feature tag",
+    usage: "atticus feature tag <id> <tags...>",
+    what: "Tags a feature with business areas.",
+    who: ["product-owner"],
+    changes: "a curated decision"
+  },
+  {
+    name: "feature merge",
+    usage: "atticus feature merge <into> <from...>",
+    what: "Merges features that are really one.",
+    who: ["product-owner", "architect"],
+    changes: "a curated decision"
+  },
+  {
+    name: "feature split",
+    usage: "atticus feature split <id> <entry-points...>",
+    what: "Splits entry points into their own feature.",
+    who: ["product-owner", "architect"],
+    changes: "a curated decision"
+  },
+  {
+    name: "feature link",
+    usage: "atticus feature link <id> <ref>",
+    what: "Links a feature to a work item or page.",
+    who: ["product-owner"],
+    changes: "a curated decision"
+  },
+  {
+    name: "feature suggest-links",
+    usage: "atticus feature suggest-links [--json]",
+    what: "Suggests links between features and work items.",
+    who: ["product-owner"],
+    changes: "nothing"
+  },
+  {
+    name: "feature spec",
+    usage: "atticus feature spec <id>",
+    what: "Drafts an OpenSpec capability spec from a confirmed feature.",
+    who: ["product-owner", "business-analyst"],
+    changes: "a spec draft"
+  },
+  {
+    name: "feature suggest-names",
+    usage: "atticus feature suggest-names [--mode m]",
+    what: "Asks AI to propose names for detected features; they stay proposals until a person confirms them.",
+    who: ["product-owner"],
+    changes: "catalog/proposals"
+  },
+  {
+    name: "catalog migrate",
+    usage: "atticus catalog migrate [--dry-run]",
+    what: "Rewrites catalog files to the current schema version.",
+    who: ["platform-lead"],
+    changes: "catalog files"
+  },
+  {
+    name: "task run",
+    usage: "atticus task run <change> <task> [--level plan|draft|pr] [--approve]",
+    what: "Runs a task with AI: a plan only, a draft in the worktree, or a pull request. AI never pushes to protected branches or deploys.",
+    who: ["developer"],
+    changes: "the task's worktree or a task branch",
+    approval: true
+  },
+  {
+    name: "task",
+    usage: "atticus task <change> <task> [--level plan|draft|pr] [--approve]",
+    what: "Runs one task of a change with your assistant: a plan only, a draft in the worktree, or a pull request. The same command as atticus task run; atticus task context <change> <task> gives the task's context.",
+    who: ["developer"],
+    changes: "the task's worktree or a task branch",
+    approval: true,
+    related: ["task run", "stories"]
+  },
+  {
+    name: "spec hand-down",
+    usage: "atticus spec hand-down <change> <task>",
+    what: "Creates the task's Spec Kit feature in its repo from the approved design.",
+    who: ["developer"],
+    changes: "the repo's specs/ folder"
+  },
+  {
+    name: "spec hand-up",
+    usage: "atticus spec hand-up <change> <task>",
+    what: "Reads the Spec Kit feature back at the pull request and compares it with the design.",
+    who: ["developer", "architect"],
+    changes: "the change's drift record"
+  },
+  {
+    name: "drift",
+    usage: "atticus drift <change> [--json]",
+    what: "Compares the design, each repo's plan and the code.",
+    who: ["architect", "developer"],
+    changes: "nothing"
+  },
+  {
+    name: "assistant-files",
+    usage: "atticus assistant-files [--repo id] [--check]",
+    what: "Generates Copilot and Claude Code files from one source.",
+    who: ["platform-lead", "developer"],
+    changes: "assistant files in the repo"
+  },
+  {
+    name: "plan stories",
+    usage: "atticus plan stories <change>",
+    what: "Writes stories, the story index and tasks from the approved design.",
+    who: ["business-analyst", "team-lead"],
+    changes: "stories/, stories.md, tasks.md"
+  },
+  {
+    name: "stories",
+    usage: "atticus stories <change> [--draft] [--mode m]",
+    what: "The stories stage, one of the twelve commands atticus help shows: your assistant writes the change's stories with their acceptance criteria and tasks from the design, every one checked. It is the same command as atticus plan stories.",
+    who: ["business-analyst", "team-lead"],
+    changes: "stories/, stories.md, tasks.md",
+    related: ["plan stories", "task"]
+  },
+  {
+    name: "plan snow",
+    usage: "atticus plan snow <change>",
+    what: "Drafts the service-desk requests the change needs (firewall rules, gateway proxies).",
+    who: ["team-lead", "business-analyst"],
+    changes: "snow.md"
+  },
+  {
+    name: "plan bar",
+    usage: "atticus plan bar <change> [--eval file]",
+    what: "Measures the stories against the story bar: ready, gaps covered, nothing invented.",
+    who: ["business-analyst"],
+    changes: "nothing"
+  },
+  {
+    name: "plan submit",
+    usage: "atticus plan submit <change> [--approve]",
+    what: "Files the drafted service-desk requests.",
+    who: ["team-lead"],
+    changes: "the service desk (or manual steps)",
+    approval: true
+  },
+  {
+    name: "ado sync",
+    usage: "atticus ado sync <change> [--approve]",
+    what: "Creates or updates work items for the stories and tasks.",
+    who: ["team-lead", "business-analyst"],
+    changes: "the work tracker (or manual steps)",
+    approval: true
+  },
+  {
+    name: "templates draft",
+    usage: "atticus templates draft [--no-ai]",
+    what: "Drafts request and work-item templates from wikis, uploads and past tickets, as a proposal.",
+    who: ["platform-lead"],
+    changes: "proposals/templates"
+  },
+  {
+    name: "todo",
+    usage: "atticus todo [--change id] [--all]",
+    what: "Manual steps waiting for a person: things Atticus can't do in a system it can't reach.",
+    who: ["team-lead", "delivery-lead", "developer"],
+    changes: "nothing",
+    related: ["todo done"]
+  },
+  {
+    name: "todo show",
+    usage: "atticus todo show <step> [--export text|csv|import]",
+    what: "One manual step with every field ready to copy.",
+    who: ["team-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "todo done",
+    usage: "atticus todo done <step> [--result k=v]...",
+    what: "Records a manual step's result (the new id, the PR URL) so the workflow carries on.",
+    who: ["team-lead", "delivery-lead", "developer"],
+    changes: "the step file"
+  },
+  {
+    name: "todo run",
+    usage: "atticus todo run <step> --with <executor>",
+    what: "Runs a manual step with a team's own tool, after a person approves the exact inputs.",
+    who: ["platform-lead"],
+    changes: "the outside system, through the executor",
+    approval: true
+  },
+  {
+    name: "executors check",
+    usage: "atticus executors check",
+    what: "Pings configured executors and shows what each covers.",
+    who: ["platform-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "init",
+    usage: "atticus init <name> --platform <p>",
+    what: "Creates a new metarepo with the default org pack written out as files.",
+    who: ["platform-lead"],
+    changes: "a new folder"
+  },
+  {
+    name: "adopt",
+    usage: "atticus adopt <path>",
+    what: "Uses Atticus in an existing repo; writes only .atticus/ and changes nothing else.",
+    who: ["platform-lead", "developer"],
+    changes: ".atticus/ in the repo"
+  },
+  {
+    name: "unadopt",
+    usage: "atticus unadopt <path>",
+    what: "Removes Atticus from an adopted repo, leaving it as it was.",
+    who: ["platform-lead"],
+    changes: "removes .atticus/"
+  },
+  {
+    name: "repos discover",
+    usage: "atticus repos discover <folder>",
+    what: "Proposes repos.manifest.yaml entries for the repos in a folder.",
+    who: ["platform-lead"],
+    changes: "the manifest, or a proposal"
+  },
+  {
+    name: "absorb",
+    usage: "atticus absorb <git-url|path> --id <id>",
+    what: "Translates another team's prompts, agents, checklists or Spec Kit into an org-pack proposal; never applies it.",
+    who: ["platform-lead"],
+    changes: "a proposal folder"
+  },
+  {
+    name: "tests generate",
+    usage: "atticus tests generate <change> <story>",
+    what: "Generates tests from a story's acceptance criteria and the API spec.",
+    who: ["qa", "developer"],
+    changes: "test files"
+  },
+  {
+    name: "trace",
+    usage: "atticus trace <change> [--json] [--csv]",
+    what: "Links each requirement to its stories, tests, code, records and feature; the gaps are findings.",
+    who: ["qa", "delivery-lead"],
+    changes: "the trace matrix and trace gate findings"
+  },
+  {
+    name: "ci drift",
+    usage: "atticus ci drift [repo] --catalog <path>",
+    what: "In a repo's pipeline: compares the repo with the committed catalog; planned changes are not drift.",
+    who: ["platform-lead", "developer"],
+    changes: "nothing"
+  },
+  {
+    name: "ci snippet",
+    usage: "atticus ci snippet <github|azure|gitlab|jenkins>",
+    what: "Prints the pipeline template for the drift check.",
+    who: ["platform-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "ci archive-gate",
+    usage: "atticus ci archive-gate <change>",
+    what: "Says whether a change may be archived: released, no open blocking findings, PRs merged, no drift.",
+    who: ["delivery-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "glossary list",
+    usage: "atticus glossary list [--json]",
+    what: "Business terms from wikis, code and people.",
+    who: ["business-analyst", "product-owner"],
+    changes: "nothing"
+  },
+  {
+    name: "glossary define",
+    usage: 'atticus glossary define <term> "<definition>"',
+    what: "Defines a business term.",
+    who: ["business-analyst", "product-owner"],
+    changes: "a curated decision"
+  },
+  {
+    name: "orgpack validate",
+    usage: "atticus orgpack validate [dir]",
+    what: "Checks the org pack against its schemas.",
+    who: ["platform-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "openspec setup",
+    usage: "atticus openspec setup",
+    what: "Sets up OpenSpec with the org-flow schema in the metarepo.",
+    who: ["platform-lead"],
+    changes: "openspec/"
+  },
+  {
+    name: "handoff done",
+    usage: "atticus handoff done <run-id>",
+    what: "Tells Atticus the assistant has written a hand-off artifact; Atticus checks it.",
+    who: ["developer", "business-analyst"],
+    changes: "the run's state"
+  },
+  {
+    name: "workspace sync",
+    usage: "atticus workspace sync [--repos a,b]",
+    what: "Clones or updates the base clone of every repo.",
+    who: ["developer"],
+    changes: "workspace/"
+  },
+  {
+    name: "workspace open",
+    usage: "atticus workspace open <change> --repos a,b",
+    what: "Creates the change's worktrees and editor workspaces.",
+    who: ["developer"],
+    changes: "workspace/.worktrees"
+  },
+  {
+    name: "workspace prune",
+    usage: "atticus workspace prune <change>",
+    what: "Removes worktrees whose PRs merged or closed.",
+    who: ["developer"],
+    changes: "workspace/.worktrees"
+  },
+  {
+    name: "initiative new",
+    usage: 'atticus initiative new "<title>" --journey <journey>',
+    what: "Starts an initiative: changes across teams and vendors toward one outcome, on a guided journey.",
+    who: ["product-owner", "team-lead", "delivery-lead"],
+    changes: "an Initiative record in catalog/curated"
+  },
+  {
+    name: "initiative plan",
+    usage: "atticus initiative plan <id> --target <system> [--release YYYY-MM-DD]",
+    what: "Plans the journey back from the target release: the changes each system needs and the commitments of other teams and vendors, with dates from their lead times.",
+    who: ["team-lead", "delivery-lead"],
+    changes: "the plan and Commitment records"
+  },
+  {
+    name: "initiative status",
+    usage: "atticus initiative status <id> [--json]",
+    what: "The critical path and the commitments that slipped or are at risk, from dates and change states.",
+    who: ["team-lead", "delivery-lead", "product-owner"],
+    changes: "nothing"
+  },
+  {
+    name: "initiative request",
+    usage: "atticus initiative request <id> <party>",
+    what: "Sends a team or vendor a one-page system card to correct and answer; the reply goes into intake and is tracked as a commitment.",
+    who: ["team-lead", "architect"],
+    changes: "the card, a Commitment and a manual step to send it"
+  },
+  {
+    name: "learn",
+    usage: "atticus learn [list]",
+    what: "Lists the lessons for each role and your progress.",
+    who: ["everyone"],
+    changes: "nothing"
+  },
+  {
+    name: "learn start",
+    usage: "atticus learn start <role|lesson>",
+    what: "Starts a lesson in the practice sandbox.",
+    who: ["everyone"],
+    changes: "the sandbox's progress file"
+  },
+  {
+    name: "learn check",
+    usage: "atticus learn check [--answer text]",
+    what: "Checks the step you are on and moves to the next one when it passes.",
+    who: ["everyone"],
+    changes: "the sandbox's progress file"
+  },
+  {
+    name: "sandbox create",
+    usage: "atticus sandbox create <dir>",
+    what: "Makes a throwaway practice metarepo from the invented Forge ecosystem.",
+    who: ["everyone"],
+    changes: "the folder named"
+  },
+  {
+    name: "explain",
+    usage: "atticus explain <id|command>",
+    what: "Explains a record, finding, change or command in plain words.",
+    who: ["everyone"],
+    changes: "nothing"
+  },
+  {
+    name: "legacy",
+    usage: "atticus legacy [<command...>] [--all]",
+    what: "Lists every command outside the twelve atticus help shows, grouped by area. atticus legacy <command> runs one, exactly as atticus <command> does: the old names keep working.",
+    who: ["everyone"],
+    changes: "nothing (the command it runs may)"
+  },
+  {
+    name: "ui",
+    usage: "atticus ui [--port n] [--open] [--full]",
+    what: "Starts the app on this machine (127.0.0.1 only): Home, Map, Change, Questions, Knowledge and Set up. Ctrl+C stops it.",
+    who: ["everyone"],
+    changes: "nothing by itself; what you do in the app writes metarepo files, never Git"
+  },
+  {
+    name: "eval run",
+    usage: "atticus eval run [--agent a] [--mode mock|replay|live] [--runs n]",
+    what: "Runs the AI agents' evaluation cases and grades them; live mode needs a configured model and a person running it.",
+    who: ["platform-lead"],
+    changes: ".evals/ results"
+  },
+  {
+    name: "eval report",
+    usage: "atticus eval report [--json]",
+    what: "Pass rates per agent, the 4-of-5 live bar and regressions since the last run.",
+    who: ["platform-lead"],
+    changes: "nothing"
+  },
+  {
+    name: "defences scan",
+    usage: "atticus defences scan [path]",
+    what: "Scans files for text that tries to instruct an AI (hidden, encoded or plain) and says what Atticus would do with each.",
+    who: ["platform-lead", "architect"],
+    changes: "nothing"
+  }
+];
+function commandNamed(text) {
+  const words2 = text.trim().replace(/^atticus\s+/, "").split(/\s+/).filter((w) => w && !w.startsWith("-"));
+  for (let n = Math.min(words2.length, 3); n > 0; n--) {
+    const name = words2.slice(0, n).join(" ");
+    const hit = COMMANDS.find((c) => c.name === name);
+    if (hit)
+      return hit;
+  }
+  return void 0;
+}
+
+// packages/learn/dist/explain.js
+var import_yaml3 = __toESM(require_dist(), 1);
+import { readdir as readdir4, readFile as readFile5 } from "node:fs/promises";
+import { join as join5, relative as relative2, sep as sep2 } from "node:path";
+
+// packages/learn/dist/glossary.js
+var PRODUCT_TERMS = [
+  {
+    term: "metarepo",
+    aliases: ["meta repo", "meta-repo"],
+    says: "The Git repo Atticus keeps for your estate: the catalog read from your repos' code, the changes in flight, the knowledge and the org pack. Its pull requests are how things get approved."
+  },
+  {
+    term: "org pack",
+    aliases: ["org-pack", "orgpack"],
+    says: "Your organisation's settings for Atticus, in org-pack/: the repos and their types, the change types, the checklists and how AI runs here, changed through a pull request."
+  },
+  {
+    term: "catalog",
+    aliases: [],
+    says: "What Atticus read from your code: systems, components, endpoints, tables, settings and how they connect, each citing the file and line it came from."
+  },
+  {
+    term: "estate",
+    aliases: [],
+    says: "All your systems and the repos behind them, as the catalog describes them."
+  },
+  {
+    term: "flow",
+    aliases: [],
+    says: "One path through your code from a trigger (an endpoint, a job, a message) to what it reads, writes and returns, step by step, read from the code."
+  },
+  {
+    term: "change",
+    aliases: [],
+    says: "A piece of work from idea to release, kept in the metarepo with its brief, its design, its stories and its tasks."
+  },
+  {
+    term: "target flow",
+    aliases: ["target flows"],
+    says: "How a flow will run once a change is in: the steps it adds, changes or removes, with what each reads and writes."
+  },
+  {
+    term: "hand-off",
+    aliases: ["handoff", "hand-off pr", "handoff pr", "the pr"],
+    says: "The pull request in the metarepo that ends a phase of a change; merging it approves the phase's gate."
+  },
+  {
+    term: "gate",
+    aliases: [],
+    says: "The point between two phases of a change where its findings are checked and a person approves, by merging the hand-off pull request."
+  },
+  {
+    term: "finding",
+    aliases: ["findings"],
+    says: "Something the critic or a check raised about a change (blocking, a risk, a gap or an idea), citing where it is; a person decides what to do with it."
+  },
+  {
+    term: "critic",
+    aliases: [],
+    says: "The AI reviewer that reads a change at a gate, one lens at a time, and raises findings."
+  },
+  {
+    term: "lens",
+    aliases: ["lenses"],
+    says: "One way the critic reads a change, such as security, data or architecture, each with its own rules."
+  },
+  {
+    term: "checking round",
+    aliases: [],
+    says: "One more critic round after a gate's rounds are used, which reviews only what a person fixed."
+  },
+  {
+    term: "question",
+    aliases: ["questions"],
+    says: "Something Atticus asked a person because the code doesn't say, with options and the lines it read; the answer is kept in the metarepo for the steps that read it."
+  },
+  {
+    term: "knowledge item",
+    aliases: ["knowledge items", "knowledge"],
+    says: "A fact read from a wiki or a document you added (a process, a standard, a decision, a team), quoted with its page, until a person verifies it."
+  },
+  {
+    term: "need",
+    aliases: ["needs"],
+    says: "Something a change needs from the organisation, such as a firewall rule or an access request, with how to ask for it and who handles it."
+  },
+  {
+    term: "dialect",
+    aliases: ["dialects"],
+    says: "The rules that tell Atticus's scanner how to read one framework or language, your own house frameworks included."
+  },
+  {
+    term: "base clone",
+    aliases: ["base clones"],
+    says: "Atticus's own read-only copy of a repo, in the metarepo's workspace/, which the scans read; it never touches your working copy."
+  },
+  {
+    term: "slash command",
+    aliases: ["slash commands"],
+    says: "A command you type in your assistant's chat, such as /atticus-next, that runs one Atticus step with the assistant's model."
+  },
+  {
+    term: "service desk",
+    aliases: ["snow", "servicenow"],
+    says: "Your operations ticketing system, where a change's release and access requests are raised."
+  }
+];
+var fold = (s) => s.trim().toLowerCase().replace(/[-_\s]+/g, " ");
+function termNamed(word) {
+  const w = fold(word);
+  return PRODUCT_TERMS.find((t) => fold(t.term) === w || t.aliases.some((a) => fold(a) === w));
+}
+
+// packages/learn/dist/explain.js
+var KIND_TEXT = {
+  System: "a system: a product or service people know by name, made of components",
+  Component: "a component: one deployable part of a system, usually one repo or service",
+  Endpoint: "an endpoint: something a component offers (an API operation, a topic, a queue, a job)",
+  Interface: "an interface: one component calling or messaging another",
+  GatewayRoute: "a gateway route: a proxy on the API gateway that forwards calls to a component",
+  Schema: "a schema: the shape of a message or payload",
+  FieldMapping: "a field mapping: how a field on one side of an interface becomes a field on the other",
+  DataStore: "a data store: a database or other store a component owns",
+  Table: "a table: a table or collection in a data store",
+  Column: "a column: one field of a table",
+  Migration: "a migration: a script that changes a data store's structure",
+  Setting: "a setting: a configuration value of a component",
+  Deployment: "a deployment: where and how a component runs in one environment",
+  ObservabilityAsset: "an observability asset: an alert, dashboard or log query",
+  AccessGrant: "an access grant: who may call or read what",
+  Obligation: "an obligation: a promise such as a service level or a retention rule",
+  SourceDocument: "a source document: a document Atticus took in as data",
+  Party: "a party: an internal team or a vendor Atticus works with",
+  Initiative: "an initiative: several changes across teams and vendors toward one outcome",
+  Commitment: "a commitment: something a party promised to deliver by a date",
+  OwnerQuestion: "an owner question: a question to a system's owner that closes a knowledge gap",
+  ProcessArtifact: "a process artifact: a ticket, work item or change linked to the catalog",
+  Capability: "a feature: what a set of entry points adds up to for its users",
+  Unresolved: "a loose end: a call or access found on one side only, not yet matched",
+  CuratedDecision: "a curated decision: a person's decision replayed over the catalog on every scan",
+  GlossaryTerm: "a glossary term: a business word and what it means"
+};
+var CONFIDENCE = {
+  verified: "verified: read directly from code, config or a published spec",
+  inferred: "inferred: seen from one side only, or read from a diagram or document",
+  asserted: "asserted: stated or confirmed by a person"
+};
+var SEVERITY = {
+  blocking: "blocking: it stops the hand-off until it is fixed or, where allowed, waived with a reason",
+  gap: "a knowledge gap: a fact only a person can give; it needs an answer or a recorded reason",
+  risk: "a risk: worth knowing, never blocks",
+  idea: "an idea: a suggestion, never blocks"
+};
+var ACTIONS = {
+  issue: "apply the fix, edit and apply, mark not relevant with a reason, or (if blocking and waivable) waive it with a reason",
+  "knowledge-gap": "ask the owner the question, or edit and apply the answer"
+};
+var STATE_TEXT = {
+  draft: "being drafted",
+  define: "in Define: the product owner writes the brief, proposal and specs",
+  design: "in Design: the architect designs interfaces, data and the solution",
+  plan: "in Plan: stories, tasks and service-desk requests are written",
+  build: "in Build: the code is written in each repo",
+  qa: "in QA: testing before release",
+  "release-ready": "ready for the go/no-go decision",
+  released: "released",
+  "post-release-review": "released, with the skipped reviews to run after the fact",
+  returned: "returned to the product owner",
+  archived: "archived"
+};
+var words = (r, keys) => keys.filter((k) => r[k] !== void 0 && r[k] !== "" && !(Array.isArray(r[k]) && r[k].length === 0));
+function recordLines(r, all) {
+  const x = r;
+  const lines = [];
+  const seeAlso = [];
+  switch (r.kind) {
+    case "System":
+      lines.push(`${r.name} is a ${r.boundary} system${r.owner ? ` owned by ${r.owner}` : " with no known owner"}.`);
+      if (r.repos.length)
+        lines.push(`Its code is in ${r.repos.join(", ")}.`);
+      break;
+    case "Component":
+      lines.push(`${r.id} is a ${r.type} in system ${r.system}${r.repo ? `, in repo ${r.repo}` : ""}.`);
+      break;
+    case "Interface":
+      lines.push(`${r.from} calls ${r.to}${r.method ? ` with ${r.method}` : ""} ${r.normalizedPath}, ${r.via === "gateway" ? "through the gateway" : r.via === "direct" ? "directly" : `over ${r.via}`}, ${r.sync === "sync" ? "waiting for the answer" : "without waiting (async)"}.`);
+      if (r.pattern)
+        lines.push(`Its integration pattern is ${r.pattern.code} (${r.pattern.source}).`);
+      else
+        lines.push("No integration pattern is recorded for it.");
+      if (r.conflicts.length)
+        lines.push(`Sources disagree about ${r.conflicts.map((c) => c.field).join(", ")}.`);
+      break;
+    case "Endpoint":
+      lines.push(`${r.component} offers ${r.method ? `${r.method} ` : ""}${r.pathOrTopic} (${r.endpointType}).`);
+      break;
+    case "Table":
+      lines.push(`${r.name} is a ${r.tableKind} in ${r.dataStore}, owned by ${r.ownerComponent ?? "an unknown component"}.`);
+      if (r.writers.length)
+        lines.push(`Written by ${r.writers.join(", ")}.`);
+      if (r.readers.length)
+        lines.push(`Read by ${r.readers.join(", ")}.`);
+      break;
+    case "DataStore":
+      lines.push(`${r.id} is a ${r.storeType} store owned by ${r.ownerComponent ?? "an unknown component"}.`);
+      break;
+    case "Party":
+      lines.push(`${r.name} is ${r.partyKind === "vendor" ? "a vendor" : "an internal team"}${r.owner ? ` (${r.owner})` : ""}.`);
+      for (const [k, v] of Object.entries(r.typicalLeadTimes))
+        lines.push(`A ${k} usually takes ${v}.`);
+      break;
+    case "Initiative":
+      lines.push(`"${r.title}" follows the ${r.journey} journey${r.targetRelease ? `, aiming to release on ${r.targetRelease}` : ""}.`);
+      if (r.changes.length)
+        lines.push(`Its changes: ${r.changes.join(", ")}.`);
+      if (r.parties.length)
+        lines.push(`It depends on ${r.parties.join(", ")}.`);
+      break;
+    case "Commitment":
+      lines.push(`${r.party} committed to: ${r.what}, by ${r.neededBy} (${r.commitmentStatus}).`);
+      if (r.blocks.length)
+        lines.push(`Until then it blocks ${r.blocks.join(", ")}.`);
+      break;
+    case "OwnerQuestion":
+      lines.push(`${r.owner} was asked (${r.questionState}): ${r.question}`);
+      break;
+    case "Capability":
+      lines.push(`"${r.name}" starts at ${r.entryPoints.join(", ") || "no known entry point"} and reaches ${r.records.length} record${r.records.length === 1 ? "" : "s"}.`);
+      break;
+    case "CuratedDecision":
+      lines.push(`${r.by} decided to ${r.action} ${r.target} on ${r.at.slice(0, 10)}: ${r.reason}`);
+      break;
+    default: {
+      const keys = words(x, ["name", "title", "component", "system", "owner"]);
+      if (keys.length)
+        lines.push(keys.map((k) => `${k}: ${String(x[k])}`).join("; ") + ".");
+    }
+  }
+  const refs = recordReferences(r);
+  if (refs.length) {
+    const ids = [...new Set(refs.map((f) => f.id))];
+    lines.push(`It refers to ${ids.slice(0, 8).join(", ")}${ids.length > 8 ? ` and ${ids.length - 8} more` : ""}.`);
+    seeAlso.push(...ids.slice(0, 5));
+  }
+  const back = all.filter((o) => o !== r && recordReferences(o).some((f) => f.id === r.id));
+  if (back.length) {
+    const ids = [...new Set(back.map((o) => o.id))];
+    lines.push(`${ids.length} record${ids.length === 1 ? " refers" : "s refer"} to it, such as ${ids.slice(0, 5).join(", ")}.`);
+    seeAlso.push(`atticus impact ${r.id}`);
+  }
+  return { lines, seeAlso };
+}
+async function findFinding(root, id) {
+  const changes = join5(root, "openspec", "changes");
+  const walk2 = async (d) => {
+    let entries;
+    try {
+      entries = await readdir4(d, { withFileTypes: true });
+    } catch {
+      return void 0;
+    }
+    for (const e of entries.sort((a, b) => a.name < b.name ? 1 : -1)) {
+      const full = join5(d, e.name);
+      if (e.isDirectory()) {
+        const hit = await walk2(full);
+        if (hit)
+          return hit;
+      } else if (e.name === `${id}.yaml` && full.split(sep2).includes("review")) {
+        const r = Finding.safeParse((0, import_yaml3.parse)(await readFile5(full, "utf8")));
+        if (r.success)
+          return { path: relative2(root, full).split(sep2).join("/"), finding: r.data };
+      }
+    }
+    return void 0;
+  };
+  return walk2(changes);
+}
+var EXPLAINER = AgentDefinition.parse({
+  schemaVersion: 1,
+  id: "explainer",
+  role: "developer",
+  description: "Rewords an Atticus explanation in plain words for a newcomer, adding nothing that isn't in it.",
+  inputs: ["catalog-slice"],
+  outputArtifact: "proposal",
+  tokenBudget: 2e4,
+  allowedRuntimes: ["model", "mock", "replay", "hand-off"]
+});
+async function explain(root, subject, o = {}) {
+  const s = subject.trim();
+  let out;
+  const cmd = /\s/.test(s) || /^atticus\b/.test(s) ? commandNamed(s) : void 0;
+  if (cmd)
+    out = commandExplanation(s, cmd);
+  if (!out) {
+    const dir = catalogDirOf(root);
+    const records = [
+      ...(await readCatalog(join5(dir, "generated"), { cacheRoot: root })).records,
+      ...(await readCatalog(join5(dir, "curated"), { cacheRoot: root })).records
+    ];
+    const hits = records.filter((r) => r.id === s);
+    if (hits.length) {
+      const r = hits[0];
+      const { lines, seeAlso } = recordLines(r, records);
+      out = {
+        subject: s,
+        kind: "record",
+        title: `${s} is ${KIND_TEXT[r.kind] ?? `a ${r.kind} record`}.`,
+        lines: [
+          ...lines,
+          `Its confidence is ${CONFIDENCE[r.confidence] ?? r.confidence}.`,
+          `Evidence: ${[...new Set(r.evidence.map((e) => e.source === "manual" ? `stated by ${e.by ?? "a person"}` : `${e.source}${e.path ? ` ${e.repo ? `${e.repo}/` : ""}${e.path}${e.line ? `:${e.line}` : ""}` : ""}`))].slice(0, 4).join("; ")}.`,
+          ...hits.length > 1 ? [
+            `${hits.length - 1} other record${hits.length > 2 ? "s have" : " has"} the same id (${hits.slice(1).map((h) => h.kind).join(", ")}).`
+          ] : []
+        ],
+        seeAlso
+      };
+    }
+  }
+  if (!out) {
+    const c = await changeStore(root).tryRead(s).catch(() => void 0);
+    if (c)
+      out = {
+        subject: s,
+        kind: "change",
+        title: `${s} is a change: "${c.title}" (${c.type}).`,
+        lines: [
+          `It is ${STATE_TEXT[c.state] ?? c.state}.`,
+          ...c.systems.length ? [`It touches ${c.systems.join(", ")}.`] : [],
+          ...c.history.length ? [
+            `Last move: ${c.history.at(-1).from} to ${c.history.at(-1).to} by ${c.history.at(-1).by}.`
+          ] : []
+        ],
+        seeAlso: [`atticus change status ${s}`, `atticus findings ${s}`]
+      };
+  }
+  if (!out) {
+    const f = await findFinding(root, s);
+    if (f) {
+      const x = f.finding;
+      out = {
+        subject: s,
+        kind: "finding",
+        title: `${s} is a critic finding on change ${x.change} at the ${x.gate} gate (round ${x.round}).`,
+        lines: [
+          `It says: ${x.summary}`,
+          `Why it matters: ${x.why}`,
+          `It is ${SEVERITY[x.severity] ?? x.severity}.`,
+          `Rule ${x.rule} (${x.layer} layer, ${x.lens} lens) raised it about ${x.artifact}${x.locator.line ? ` line ${x.locator.line}` : ""}.`,
+          `Evidence: ${x.evidence.map((e) => e.quote ? `"${e.quote}"` : e.record ?? e.path ?? "").filter(Boolean).slice(0, 2).join("; ")}.`,
+          `Fix: ${x.fix.text}`,
+          ...x.question ? [`Question for ${x.question.owner}: ${x.question.text}`] : [],
+          x.state === "open" ? `It is open. You can ${ACTIONS[x.kind]}${x.waivable ? "" : "; it can't be waived"}.` : `It is ${x.state}${x.resolution ? ` (by ${x.resolution.by})` : ""}.`
+        ],
+        seeAlso: [`atticus finding ${x.change} ${x.id} <action>`, `atticus explain ${x.rule}`]
+      };
+    }
+  }
+  if (!out) {
+    const t = termNamed(s);
+    if (t)
+      out = {
+        subject: s,
+        kind: "term",
+        title: t.term,
+        lines: [t.says],
+        seeAlso: commandNamed(s) ? [`atticus explain "atticus ${s}"`] : []
+      };
+  }
+  if (!out) {
+    const c = commandNamed(s);
+    if (c)
+      out = commandExplanation(s, c);
+  }
+  out ??= {
+    subject: s,
+    kind: "unknown",
+    title: `Atticus knows nothing called ${s}.`,
+    lines: [
+      'Try a record id (atticus query to find one), a change id, a finding id, or a command such as "atticus explain scan".'
+    ],
+    seeAlso: ["atticus query", "atticus change list"]
+  };
+  if (o.runtime && out.kind !== "unknown")
+    out.reworded = await reword(out, o.runtime, o.now ?? /* @__PURE__ */ new Date());
+  return out;
+}
+function commandExplanation(s, c) {
+  return {
+    subject: s,
+    kind: "command",
+    title: `atticus ${c.name}: ${c.what}`,
+    lines: [
+      `Usage: ${c.usage}`,
+      `Usually run by: ${c.who.join(", ")}.`,
+      c.changes === "nothing" ? "It only reads; it changes nothing." : `It changes: ${c.changes}.`,
+      ...c.approval ? [
+        "It writes to a shared system, so it needs your approval each time (--approve; it shows what it would do first)."
+      ] : []
+    ],
+    seeAlso: (c.related ?? []).map((r) => `atticus explain ${r}`)
+  };
+}
+async function reword(e, runtime, now) {
+  const pack = buildContextPack({
+    change: "explain",
+    agent: EXPLAINER.id,
+    budget: EXPLAINER.tokenBudget,
+    levels: ["public", "internal", "confidential", "restricted"],
+    maxClassification: "internal",
+    now,
+    sources: [
+      {
+        id: "0-instructions",
+        kind: "instruction",
+        origin: "atticus/learn/explain",
+        text: "Reword the explanation below in plain, short sentences for someone new to Atticus. Keep every fact; add none. Write only the reworded text.",
+        classification: "public",
+        trusted: true
+      },
+      {
+        id: "explanation",
+        kind: "document",
+        origin: `explain/${e.subject}`,
+        text: toCanonicalYaml({ title: e.title, lines: e.lines }),
+        classification: "internal"
+      }
+    ]
+  });
+  try {
+    const run = await runtime.prepare({
+      change: "explain",
+      agent: EXPLAINER,
+      pack,
+      outputPath: "explain.md"
+    });
+    const done = await runtime.run(run.runId);
+    const text = done.output?.trim();
+    return done.state === "validated" && text ? text : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// packages/cli/dist/learn-commands.js
+function fail(io, e) {
+  if (e instanceof LearnError || e instanceof SandboxError) {
+    io.err(e.message);
+    return e instanceof LearnError && e.code === "usage" ? 2 : 1;
+  }
+  throw e;
+}
+var command = (argv) => `atticus ${argv.map((a) => /[\s"']/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a).join(" ")}`;
+function printStep(io, lesson, step) {
+  const n = lesson.steps.indexOf(step) + 1;
+  io.out(`Step ${n} of ${lesson.steps.length}: ${step.title}`);
+  io.out("");
+  for (const l of step.body.trimEnd().split("\n"))
+    io.out(l);
+  if (step.do.length) {
+    io.out("");
+    for (const argv of step.do)
+      io.out(`  ${command(argv)}`);
+  }
+  const ask = step.check.type === "answer" ? step.check : step.check.type === "all" ? step.check.checks.find((c) => c.type === "answer") : void 0;
+  if (ask) {
+    io.out("");
+    io.out(`Question: ${ask.question}`);
+    io.out('Answer with: atticus learn check --answer "<your answer>"');
+  } else {
+    io.out("");
+    io.out("When you have done it: atticus learn check");
+  }
+}
+async function learnList(root, o, io) {
+  const { lessons, problems } = await lessonsFor(root);
+  const sandbox = await isSandbox(root);
+  const progress = sandbox ? await readProgress(root) : void 0;
+  const state = (l) => {
+    const p = progress?.lessons[l.id];
+    if (!p)
+      return "not started";
+    if (p.completedAt)
+      return "done";
+    return `${Object.keys(p.steps).length} of ${l.steps.length} steps`;
+  };
+  if (o.json) {
+    io.out(JSON.stringify({
+      sandbox,
+      lessons: lessons.map((l) => ({
+        id: l.id,
+        role: l.role,
+        title: l.title,
+        minutes: l.minutes,
+        steps: l.steps.length,
+        state: state(l)
+      })),
+      problems
+    }, null, 2));
+    return problems.length ? 1 : 0;
+  }
+  for (const l of table(["ROLE", "LESSON", "MINUTES", "PROGRESS", "TITLE"], lessons.map((l2) => [l2.role, l2.id, String(l2.minutes), sandbox ? state(l2) : "-", l2.title])))
+    io.out(l);
+  for (const p of problems)
+    io.err(p);
+  io.out(sandbox ? "Start one with atticus learn start <role|lesson>." : "Lessons run in a practice sandbox: atticus sandbox create <dir>, then run atticus learn start <role> there.");
+  return problems.length ? 1 : 0;
+}
+async function learnStart(root, roleOrLesson, o, io, deps = {}) {
+  if (!roleOrLesson) {
+    io.err("Usage: atticus learn start <role|lesson>");
+    return 2;
+  }
+  try {
+    const r = await startLesson(root, roleOrLesson, deps.now ? { now: deps.now } : {});
+    if (o.json) {
+      io.out(JSON.stringify({ lesson: r.lesson.id, step: r.step?.id ?? null, setup: r.setup, resumed: r.resumed }, null, 2));
+      return 0;
+    }
+    io.out(`${r.lesson.title} (${r.lesson.role}, about ${r.lesson.minutes} minutes)${r.resumed ? ": resumed" : ""}`);
+    for (const s of r.setup)
+      io.out(s);
+    io.out("");
+    if (!r.resumed) {
+      for (const l of r.lesson.intro.trimEnd().split("\n"))
+        io.out(l);
+      io.out("");
+    }
+    if (r.step)
+      printStep(io, r.lesson, r.step);
+    else
+      io.out("You have finished this lesson. Pick another with atticus learn.");
+    return 0;
+  } catch (e) {
+    return fail(io, e);
+  }
+}
+async function learnCheck(root, o, io, deps = {}) {
+  try {
+    const r = await checkStep(root, {
+      ...o.answer !== void 0 ? { answer: o.answer } : {},
+      ...o.lesson ? { lesson: o.lesson } : {},
+      ...o.step ? { step: o.step } : {},
+      ...deps.now ? { now: deps.now } : {}
+    });
+    if (o.json) {
+      io.out(JSON.stringify({
+        lesson: r.lesson.id,
+        step: r.step.id,
+        pass: r.result.pass,
+        message: r.result.message,
+        next: r.next?.id ?? null,
+        completed: r.completed
+      }, null, 2));
+      return r.result.pass ? 0 : 1;
+    }
+    if (!r.result.pass) {
+      io.out(`Not yet: ${r.result.message}`);
+      io.out(`Hint: ${r.step.hint}`);
+      return 1;
+    }
+    io.out(`Passed: ${r.result.message}`);
+    if (r.next) {
+      io.out("");
+      printStep(io, r.lesson, r.next);
+    } else {
+      io.out("");
+      for (const l of r.lesson.outro.trimEnd().split("\n"))
+        io.out(l);
+    }
+    return 0;
+  } catch (e) {
+    return fail(io, e);
+  }
+}
+async function sandboxCreate(dir, o, io, deps = {}) {
+  if (!dir) {
+    io.err("Usage: atticus sandbox create <dir>");
+    return 2;
+  }
+  try {
+    const s = await createSandbox(dir, deps.now ? { now: deps.now } : {});
+    const silent = { out: () => void 0, err: () => void 0 };
+    await upgradeCommand(s.root, { by: "atticus-sandbox", ...deps.now ? { now: deps.now } : {} }, silent);
+    await generateAssistantFiles(s.root);
+    if (o.json) {
+      io.out(JSON.stringify(s, null, 2));
+      return 0;
+    }
+    io.out(`Made a practice sandbox in ${s.dir}: ${s.repos.length} Forge repos and the seeded change ${s.change}.`);
+    io.out(`Its metarepo is ${s.root}. Run commands there (or add --root), starting with atticus learn. Go there with:`);
+    io.out(`cd "${s.root}"`);
+    return 0;
+  } catch (e) {
+    return fail(io, e);
+  }
+}
+async function explainCommand(root, idOrCommand, o, io, deps = {}) {
+  if (!idOrCommand?.trim()) {
+    io.err("Usage: atticus explain <record id | finding id | change id | command>");
+    return 2;
+  }
+  const e = await explain(root, idOrCommand, {
+    ...deps.runtime ? { runtime: deps.runtime } : {},
+    ...deps.now ? { now: deps.now } : {}
+  });
+  if (o.json) {
+    io.out(JSON.stringify(e, null, 2));
+    return e.kind === "unknown" ? 1 : 0;
+  }
+  io.out(e.title);
+  for (const l of e.lines)
+    io.out(`  ${l}`);
+  if (e.reworded) {
+    io.out("");
+    io.out("In plain words (AI):");
+    for (const l of e.reworded.split("\n"))
+      io.out(`  ${l}`);
+  }
+  if (e.seeAlso.length)
+    io.out(`See also: ${e.seeAlso.join(", ")}`);
+  return e.kind === "unknown" ? 1 : 0;
+}
+
+export {
+  isSandbox,
+  readProgress,
+  lessonsFor,
+  learnList,
+  learnStart,
+  learnCheck,
+  sandboxCreate,
+  explainCommand
+};