@maycombhq/atticus 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/{chunk-UBBC2XSG.js → chunk-26Z7OGQW.js}

@@ -3,57 +3,88 @@ 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 {
+  componentTypeIds,
+  componentTypesAt
+} from "./chunk-L4CESDPB.js";
+import {
+  modelsData,
+  modelsLine,
+  reachHeadOf,
+  reachPlanOf,
+  readPathsOf
+} from "./chunk-455SYIIE.js";
+import {
+  houseUntaughtLines,
+  houseUntaughtOf
+} from "./chunk-3J5I7ZOU.js";
+import {
+  effectiveRules,
+  notesAt,
+  readingRulesText,
+  ruleIds
+} from "./chunk-GIFMBCTW.js";
 import {
   loadReadPlan,
+  modelsModeOf,
   partOfWords,
   readPlanProgress,
   readPlanRelOf,
+  recordNotReached,
+  saveReadPlan,
   writeReadPlan
-} from "./chunk-FQXYPF7E.js";
+} from "./chunk-MD7KUEJ3.js";
 import {
   carryOf,
   checkoutOf,
+  conventionsAt,
+  estateComponentsOf,
   excludesOf,
   headOf,
   raiseReadQuestions,
   readCorrections,
   readReviewed,
   reviewedProblemsOf,
+  slipNoteLines,
   writeVerifyFiles
-} from "./chunk-CR3MTH32.js";
-import "./chunk-O3WI5KWW.js";
+} from "./chunk-Q46QDDMF.js";
 import {
   ABOUT_RULE,
+  MODELS_RULE,
+  RULE_SETS,
   assistantTier,
   mapBatchInstructions,
   readProbes,
+  rulesNow,
+  taughtFrameworksText,
   tierSource,
   tierWords
-} from "./chunk-IPKHE5D6.js";
+} from "./chunk-3AQ2R5NL.js";
 import {
   FILE_KINDS,
-  SESSION_TOKENS,
   SHOWN_PROPOSALS,
   dirSource,
   exclusionYaml,
   frameworkTopics,
   frameworkTopicsOfType,
   kindsOf,
+  lineRangeOf,
   numberedSlice,
   onlyFiles,
   planBatches,
   planParts,
   proposeExclusions,
+  repairFormSlips,
   rereadPlan,
   sameCommit,
+  sessionTokensFor,
   sliceText,
   staleMessage,
   verifyFacts
-} from "./chunk-PAMPPUR6.js";
+} from "./chunk-JYMIB5XY.js";
 import {
   loadRepos
-} from "./chunk-EFHQ3TWP.js";
-import "./chunk-GQ4N4WKF.js";
+} from "./chunk-XOL3GFW2.js";
 import {
   DATA_RULE,
   HandoffRuntime,
@@ -63,32 +94,36 @@ import {
   estimateTokens,
   promptBudget,
   wrapData
-} from "./chunk-CNUKCS2T.js";
+} from "./chunk-QHJJMZLX.js";
 import {
   AgentDefinition,
   Fact,
   REPO_DESCRIPTION_MAX,
   citedFiles,
+  componentTypesText,
+  conventionsOf,
   descriptionNote,
   descriptionTrust,
   factsDirOf,
   factsRelOf,
   listQuestions,
   loadOrgPack,
+  normalizeFactPaths,
+  notesText,
   orgPackDirOf,
   parseFacts,
   runsDirOf,
-  saysNotProduct
-} from "./chunk-S2A7YC3Q.js";
+  saysNotProduct,
+  stackHelpersOff
+} from "./chunk-PAINMSID.js";
 import {
   writeFileAtomic
-} from "./chunk-D3PO4DOZ.js";
-import "./chunk-TV45EUGM.js";
+} from "./chunk-ODMBPDDV.js";
 
 // packages/cli/dist/map-commands.js
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join, relative } from "node:path";
+import { dirname, join, relative, sep } from "node:path";
 var REPO_READER = "repo-reader";
 var OUTPUT = "facts.jsonl";
 var KEPT_RESERVE = 1500;
@@ -115,6 +150,9 @@ var plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
 var batches = (n) => `${n} ${n === 1 ? "batch" : "batches"}`;
 var changeOf = (repo) => `map-${repo}`;
 var stateFile = (root, repo) => join(runsDirOf(root), changeOf(repo), "state.json");
+async function mapStateOf(root, repo) {
+  return readState(root, repo).catch(() => void 0);
+}
 async function readState(root, repo) {
   const text = await readFile(stateFile(root, repo), "utf8").catch(() => void 0);
   return text ? JSON.parse(text) : void 0;
@@ -151,7 +189,7 @@ var overheadOf = (repo, commit, frameworks) => {
   return (kinds) => instructionTokens(repo, commit, kinds, frameworks) - core;
 };
 async function frameworksFor(root, repo, facts) {
-  const fromFacts = frameworkTopics(facts);
+  const fromFacts = frameworkTopics(facts, (await conventionsAt(root)).frameworks);
   if (fromFacts)
     return fromFacts;
   const type = (await loadRepos(root).catch(() => [])).find((r) => r.id === repo)?.type;
@@ -175,12 +213,17 @@ function claimOf(f) {
       return `${f.name}${f.version ? ` ${f.version}` : ""}`;
     case "flow":
       return f.name;
+    case "term":
+      return `${f.term} ${f.value} (${f.role})`;
+    case "component":
+      return `${f.component ?? f.repo} is a ${f.type}`;
   }
 }
-function readAnswer(text, repo, commit) {
+function readAnswer(text, repo, commit, onFile = []) {
   const facts = /* @__PURE__ */ new Map();
   const questions = [];
   const problems = [];
+  const refused = [];
   let about;
   text.split(/\r?\n/).forEach((raw, i) => {
     const line = raw.trim();
@@ -190,14 +233,17 @@ function readAnswer(text, repo, commit) {
     try {
       json = JSON.parse(line);
     } catch {
-      problems.push(`line ${i + 1} is not one JSON object: ${line.slice(0, 80)}`);
+      problems.push({
+        line: i + 1,
+        message: `line ${i + 1} is not one JSON object: ${line.slice(0, 80)}`
+      });
       return;
     }
     if (!json || typeof json !== "object" || Array.isArray(json)) {
-      problems.push(`line ${i + 1} is not one JSON object`);
+      problems.push({ line: i + 1, message: `line ${i + 1} is not one JSON object` });
       return;
     }
-    const o = json;
+    const o = normalizeFactPaths(json);
     if ("question" in o && !("kind" in o)) {
       questions.push(o);
       return;
@@ -205,7 +251,10 @@ function readAnswer(text, repo, commit) {
     if ("about" in o && !("kind" in o)) {
       const text2 = typeof o.about === "string" ? o.about.trim() : "";
       if (!text2) {
-        problems.push(`line ${i + 1}: "about" needs one line saying what the repo is`);
+        problems.push({
+          line: i + 1,
+          message: `line ${i + 1}: "about" needs one line saying what the repo is`
+        });
         return;
       }
       const cites = (Array.isArray(o.cites) ? o.cites : []).flatMap((c) => {
@@ -213,19 +262,43 @@ function readAnswer(text, repo, commit) {
         return typeof x.file === "string" && Number.isInteger(x.line) && Number(x.line) > 0 ? [{ file: x.file, line: Number(x.line) }] : [];
       }).slice(0, 6);
       if (!cites.length) {
-        problems.push(`line ${i + 1}: "about" needs "cites": the file and line it was read from, as a fact cites its line`);
+        problems.push({
+          line: i + 1,
+          message: `line ${i + 1}: "about" needs "cites": the file and line it was read from, as a fact cites its line`
+        });
         return;
       }
       about ??= { text: text2.slice(0, REPO_DESCRIPTION_MAX), cites };
       return;
     }
-    const r = Fact.safeParse({ repo, commit, ...o, verified: "none", by: "assistant" });
+    const marked = { repo, commit, ...o, verified: "none", by: "assistant" };
+    const r = Fact.safeParse(marked);
     if (r.success)
       facts.set(r.data.id, r.data);
     else
-      problems.push(`line ${i + 1}${typeof o.id === "string" ? ` (${o.id})` : ""}: ${r.error.issues.map((x) => `${x.path.join(".") || "(fact)"}: ${x.message}`).join("; ")}`);
+      refused.push({
+        line: i + 1,
+        raw: JSON.stringify(marked),
+        issues: [
+          {
+            line: i + 1,
+            code: "schema",
+            message: `line ${i + 1}${typeof o.id === "string" ? ` (${o.id})` : ""}: ${r.error.issues.map((x) => `${x.path.join(".") || "(fact)"}: ${x.message}`).join("; ")}`
+          }
+        ]
+      });
   });
-  return { facts: [...facts.values()], questions, problems, ...about ? { about } : {} };
+  const repaired = repairFormSlips([...facts.values()], refused, onFile);
+  for (const b of repaired.bad)
+    problems.push({ line: b.line, message: b.issues.map((x) => x.message).join("; ") });
+  problems.sort((x, y) => x.line - y.line);
+  return {
+    facts: repaired.facts,
+    questions,
+    problems: problems.map((x) => x.message),
+    slips: repaired.slips,
+    ...about ? { about } : {}
+  };
 }
 function rejectedText(r, source) {
   const text = source.read(r.fact.cite.file);
@@ -241,10 +314,26 @@ function rejectedText(r, source) {
     ] : []
   ].join("\n");
 }
-function questionsText(qs) {
+async function rulesCovering(root, repo, op) {
+  const type = op.profiles.flatMap((p) => p.repos?.repos ?? []).find((r) => r.id === repo)?.type;
+  const all = (await listQuestions(root, { state: "answered" }).catch(() => ({ questions: [] }))).questions;
+  return all.filter((q) => q.repo !== repo && !!q.answer?.match && (q.answer.scope.level === "repo" ? q.answer.scope.id === repo : !!type && q.answer.scope.id === type)).map((q) => ({
+    id: q.id,
+    from: q.repo,
+    match: q.answer.match,
+    answer: q.answer.text ?? q.options[(q.answer.option ?? 1) - 1]?.label ?? "",
+    scope: q.answer.scope.level === "repo" ? repo : `every ${q.answer.scope.id} repo`
+  })).sort((a, b) => a.id.localeCompare(b.id));
+}
+var ruleLineOf = (r) => `Rule ${r.id} (answered for ${r.from}, covers ${r.scope}): the calls matching ${r.match} go to ${r.answer}.`;
+function questionsText(qs, rules = []) {
   return [
     "Questions already on file for this repo. Don't ask them again; follow each answer a person gave.",
-    ...qs.map((q) => `- ${q.question} (${q.evidence.join(", ")}): ${q.state === "answered" ? `answered: ${q.answer?.text ?? q.options[(q.answer?.option ?? 1) - 1]?.label ?? ""}` : "waiting for a person"}`)
+    ...qs.map((q) => `- ${q.question} (${q.evidence.join(", ")}): ${q.state === "answered" ? `answered: ${q.answer?.text ?? q.options[(q.answer?.option ?? 1) - 1]?.label ?? ""}` : "waiting for a person"}`),
+    ...rules.length ? [
+      "Answers by rule that cover this repo, from other repos' questions. A call one matches goes where it says: don't ask about it.",
+      ...rules.map((r) => `- ${ruleLineOf(r)}`)
+    ] : []
   ].join("\n");
 }
 function keptText(facts, budgetTokens) {
@@ -282,15 +371,44 @@ function rereadInstructions(s) {
     "Write a fact for anything new in the changed files, as in a first read."
   ].join("\n");
 }
-async function rereadOf(dir, facts, commit, source, exclude, git) {
+async function rereadOf(dir, facts, commit, source, exclude, git, conventions) {
   if (!facts.some((f) => !sameCommit(f.commit, commit)))
     return { missing: [] };
   const { carry, missing } = await carryOf(dir, facts, commit, git);
   if (!Object.keys(carry).length)
     return { missing };
-  return { plan: rereadPlan({ facts, commit, carry, source, exclude }), missing };
+  return {
+    plan: rereadPlan({
+      facts,
+      commit,
+      carry,
+      source,
+      exclude,
+      ...conventions ? { conventions } : {}
+    }),
+    missing
+  };
+}
+var taughtOption = (models) => {
+  const taught = taughtFrameworksText(models);
+  return taught ? { taught } : {};
+};
+var BUILD_FILE = /(^|\/)(pom\.xml|build\.gradle(\.kts)?|package\.json|[^/]+\.csproj|requirements[^/]*\.txt|pyproject\.toml|go\.mod)$/;
+function taughtIn(source, op) {
+  if (stackHelpersOff().has("framework-models"))
+    return [];
+  const models = op.frameworks.filter((m) => m.artifacts.length);
+  if (!models.length)
+    return [];
+  const texts = source.list().filter((p) => BUILD_FILE.test(p)).map((p) => source.read(p) ?? "");
+  const esc = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return models.filter((m) => m.artifacts.some((a) => {
+    const artifact = a.split(":")[1] ?? a;
+    const declared = new RegExp(`<artifactId>\\s*${esc(artifact)}\\s*</artifactId>|["':]${esc(artifact)}["':@]`);
+    return texts.some((t) => declared.test(t));
+  }));
 }
-async function packFor(root, s, batch, source, op, now) {
+async function packFor(root, s, batch, source, op, now, notes) {
   const agent = repoReaderAgent(op);
   const budget = op.runtime.budgets.perAgent[agent.id] ?? agent.tokenBudget;
   const fix = batch >= s.batches.length;
@@ -299,7 +417,14 @@ async function packFor(root, s, batch, source, op, now) {
   const kept = await readFactsFile(root, s.repo);
   const facts = typeof kept === "string" ? [] : kept;
   const onFile = (await listQuestions(root, { repo: s.repo })).questions.filter((q) => q.state !== "retired");
+  const rules = await rulesCovering(root, s.repo, op);
   const slices = fix ? [] : s.batches[batch];
+  const inBatch = new Set(slices.map((x) => x.path));
+  const reachedHere = (s.reached ?? []).filter((r) => inBatch.has(r.path));
+  const models = reachedHere.length ? [
+    "Model classes in this batch the entry points and calls reach (read these, and write their fields):",
+    ...reachedHere.map((r) => `- ${r.path} (${r.types.join(", ")}), from ${r.from}`)
+  ].join("\n") : void 0;
   const rejected = s.rejected.map((r) => rejectedText(r, source));
   const own = kindsOf(slices.map((x) => x.path));
   const theirs = kindsOf(s.rejected.flatMap((r) => citedFiles(r.fact)));
@@ -322,11 +447,31 @@ async function packFor(root, s, batch, source, op, now) {
         // build files are read first, so from the second batch on this is what the code says.
         frameworks: await frameworksFor(root, s.repo, facts),
         // Nothing says what this repo is: ask for one line, cited, for a person to confirm.
-        ...about ? {} : { askAbout: true }
+        ...about || s.sets ? {} : { askAbout: true },
+        // ADR 0167: a top-up carries only the rule sets the read lacked.
+        ...s.sets ? {
+          sets: s.sets.filter((x) => RULE_SETS.includes(x))
+        } : {},
+        // A-taught: how to read the wrapper calls and annotations of the frameworks it is built on.
+        ...taughtOption(taughtIn(source, op)),
+        // ADR 0163: what the organisation's terms mean here and what must hold, as data.
+        ...notes ? { notes } : {},
+        // ADR 0169: the model classes of this batch the read reaches, listed beside it.
+        ...models ? { models: true } : {}
       }),
       classification: "public",
       trusted: true
     },
+    ...models ? [
+      {
+        id: "1-models",
+        kind: "document",
+        origin: "atticus/reachable",
+        text: models,
+        classification: "internal",
+        priority: 9
+      }
+    ] : [],
     ...s.reread ? [
       {
         id: "0-reread",
@@ -366,12 +511,12 @@ ${s.problems.map((p) => `- ${p}`).join("\n")}`,
         priority: 5
       }
     ] : [],
-    ...onFile.length ? [
+    ...onFile.length || rules.length ? [
       {
         id: "4-questions",
         kind: "document",
         origin: "questions/",
-        text: questionsText(onFile),
+        text: questionsText(onFile, rules),
         classification: "internal",
         priority: 4
       }
@@ -443,9 +588,60 @@ async function mapCommand(root, repo, o, io, deps = {}) {
     return 2;
   }
   const op = await loadOrgPack(orgPackDirOf(root));
+  const conventions = conventionsOf(op);
   const source = dirSource(dir);
   const exclude = await excludesOf(root, repo);
   const factsFile = `${factsRelOf(root)}/${repo}.jsonl`;
+  const repoNotes = await notesAt(root, repo, dir, op);
+  const orgRules = await effectiveRules(root, repo, { dir, op });
+  const notesPrompt = [
+    notesText(repoNotes.notes, repoNotes.type),
+    readingRulesText(orgRules),
+    // ADR 0180: the component types, the same for every batch.
+    componentTypesText(await componentTypesAt(root, op))
+  ].filter(Boolean).join("\n\n");
+  if (o.gaps) {
+    const { mapGaps } = await import("./chunk-Q26LDIUV.js");
+    const tier = await tierHere(root, op);
+    let part;
+    if (o.part !== void 0) {
+      const p = (await readPlanProgress(root, repo))?.parts.find((x) => x.part === o.part);
+      if (!p) {
+        io.err(`${repo}'s read plan has no part ${o.part} (${readPlanRelOf(root, repo)}): atticus map ${repo} --estimate plans it.`);
+        return 2;
+      }
+      part = {
+        n: p.part,
+        left: [...p.paths.filter((g) => !lineRangeOf(g)), ...p.left.filter((g) => lineRangeOf(g))]
+      };
+    }
+    return mapGaps(root, repo, {
+      commit,
+      source,
+      session: sessionTokensFor(limitOf(o, op, tier).limit),
+      checkout: relative(root, dir).split(sep).join("/") || ".",
+      ...o.json ? { json: true } : {},
+      ...part ? { part } : {},
+      ...o.models ? { models: o.models } : {},
+      exclude,
+      conventions
+    }, io);
+  }
+  if (o.rules && !deps.runtime) {
+    const { mapRules } = await import("./chunk-TJH2EUAZ.js");
+    const tier = await tierHere(root, op);
+    return mapRules(root, repo, {
+      commit,
+      source,
+      exclude,
+      conventions,
+      session: sessionTokensFor(limitOf(o, op, tier).limit),
+      notes: notesPrompt,
+      checkout: relative(root, dir).split(sep).join("/") || ".",
+      ...o.json ? { json: true } : {},
+      ...o.models ? { models: o.models } : {}
+    }, io);
+  }
   if (o.estimate)
     return estimate(root, repo, { o, op, dir, commit, source, exclude, factsFile, ...deps.git ? { git: deps.git } : {} }, io);
   const runtime = deps.runtime;
@@ -518,44 +714,133 @@ async function mapCommand(root, repo, o, io, deps = {}) {
     if (room < MIN_ROOM)
       return tooSmall(0);
     const frameworks = await frameworksFor(root, repo, existing);
-    const re = await rereadOf(dir, existing, commit, source, exclude, deps.git);
-    const reread = re.plan && !re.plan.unknown.length ? re.plan : void 0;
-    const since = reread?.from.map((x) => x.commit.slice(0, 12)).join(", ");
-    if (reread && !reread.files.length && !reread.reread.length) {
-      io.out(`Nothing ${repo}'s facts cite changed since ${since}, and no source file did: atticus verify ${repo} carries its ${plural(reread.carried, "fact")} to ${commit.slice(0, 12)}.`);
-      return 0;
-    }
-    const plan = planBatches(reread ? onlyFiles(source, reread.files.map((f) => f.path)) : source, { room, exclude, overhead: overheadOf(repo, commit, frameworks) });
-    if (plan.leastRoom < MIN_ROOM)
-      return tooSmall(room - plan.leastRoom);
-    if (!plan.batches.length && !reread) {
-      io.out(`${repo} has no source files to read${plan.excluded.length ? ` (${plural(plan.excluded.length, "file")} excluded)` : ""}.`);
-      return 0;
+    if (o.rules) {
+      const { topUpOf, recordRulesNow, ruleSetsOfFiles } = await import("./chunk-TJH2EUAZ.js");
+      const t = await topUpOf(root, repo, {
+        commit,
+        facts: existing,
+        source,
+        exclude,
+        conventions,
+        ...o.models ? { models: o.models } : {}
+      });
+      if ("error" in t) {
+        io.err(t.error);
+        return 2;
+      }
+      if (!t.lacking.length) {
+        io.out(`${repo} was read under the reading rules there are now: nothing to top up.`);
+        return 0;
+      }
+      if (!t.files.length) {
+        await recordRulesNow(root, repo, commit, t.lacking);
+        io.out(`No file of ${repo} is one the reading rules added since it was read apply to (${t.lacking.join(", ")}): its read is recorded as under the rules there are now.`);
+        return 0;
+      }
+      const sets = ruleSetsOfFiles(t.files);
+      const plan = planBatches(onlyFiles(source, t.files.map((f) => f.path)), { room, exclude, overhead: overheadOf(repo, commit, frameworks), conventions });
+      if (plan.leastRoom < MIN_ROOM)
+        return tooSmall(room - plan.leastRoom);
+      s = {
+        schemaVersion: 1,
+        repo,
+        commit,
+        ...limit ? { maxTokens: limit } : {},
+        room,
+        batches: plan.batches,
+        next: 0,
+        rejected: [],
+        problems: [],
+        sets,
+        // ADR 0169: the reached model classes, listed in the prompts of the batches holding them.
+        ...t.reach?.reach.rooted && t.reach.reach.reached.length ? {
+          reached: t.reach.reach.reached.map((r) => ({
+            path: r.path,
+            types: r.types,
+            from: r.from
+          }))
+        } : {}
+      };
+      if (t.reach)
+        await recordNotReached(root, repo, {
+          commit,
+          session: sessionTokensFor(limit),
+          models: t.reach.mode,
+          ...t.reach.notReached ? { notReached: t.reach.notReached } : {}
+        });
+      await saveState(root, s);
+      io.out(`Topping up ${repo} at ${commit.slice(0, 12)} for the reading rules added since it was read (${sets.join(", ")}): ${plural(plan.files, "source file")} in ${batches(plan.batches.length)}; facts go to ${factsFile}.`);
+    } else {
+      const re = await rereadOf(dir, existing, commit, source, exclude, deps.git, conventions);
+      const reread = re.plan && !re.plan.unknown.length ? re.plan : void 0;
+      const since = reread?.from.map((x) => x.commit.slice(0, 12)).join(", ");
+      if (reread && !reread.files.length && !reread.reread.length) {
+        io.out(`Nothing ${repo}'s facts cite changed since ${since}, and no source file did: atticus verify ${repo} carries its ${plural(reread.carried, "fact")} to ${commit.slice(0, 12)}.`);
+        return 0;
+      }
+      const mode = await modelsModeOf(root, repo, o.models);
+      const rp = reread ? void 0 : reachPlanOf({
+        paths: readPathsOf(source, exclude, conventions),
+        source,
+        facts: existing,
+        mode
+      });
+      const plan = planBatches(reread ? onlyFiles(source, reread.files.map((f) => f.path)) : source, {
+        room,
+        exclude,
+        overhead: overheadOf(repo, commit, frameworks),
+        conventions,
+        ...rp?.reach.rooted && rp.reach.models ? { reach: { first: rp.first, leaveOut: rp.leaveOut } } : {}
+      });
+      if (plan.leastRoom < MIN_ROOM)
+        return tooSmall(room - plan.leastRoom);
+      if (!plan.batches.length && !reread) {
+        io.out(`${repo} has no source files to read${plan.excluded.length ? ` (${plural(plan.excluded.length, "file")} excluded)` : ""}.`);
+        return 0;
+      }
+      const byId = new Map(existing.map((f) => [f.id, f]));
+      s = {
+        schemaVersion: 1,
+        repo,
+        commit,
+        ...limit ? { maxTokens: limit } : {},
+        room,
+        batches: plan.batches,
+        next: 0,
+        rejected: (reread?.reread ?? []).map((r) => {
+          const fact = byId.get(r.id);
+          return { id: r.id, code: "cite-changed", message: staleMessage(fact, r, commit), fact };
+        }),
+        problems: [],
+        ...rp?.reach.rooted && rp.reach.reached.length ? {
+          reached: rp.reach.reached.map((r) => ({
+            path: r.path,
+            types: r.types,
+            from: r.from
+          }))
+        } : {},
+        ...reread ? {
+          reread: {
+            from: reread.from.map((x) => x.commit),
+            carried: reread.carried,
+            facts: reread.reread.length
+          }
+        } : {}
+      };
+      await saveState(root, s);
+      if (rp)
+        await recordNotReached(root, repo, {
+          commit,
+          session: sessionTokensFor(limit),
+          models: mode,
+          ...rp.notReached ? { notReached: rp.notReached } : {}
+        });
+      if (rp?.clientOnly.length)
+        io.out(`${rp.clientOnly.length} model ${rp.clientOnly.length === 1 ? "class" : "classes"} only an outbound client reaches are left out (ADR 0170, --models entries; recorded in ${readPlanRelOf(root, repo)}): atticus map ${repo} --models reachable reads them.`);
+      if (rp && rp.leaveOut.length > rp.clientOnly.length)
+        io.out(`${rp.leaveOut.length - rp.clientOnly.length} model ${rp.leaveOut.length - rp.clientOnly.length === 1 ? "class" : "classes"} no entry or call reaches are left out (ADR 0169; recorded in ${readPlanRelOf(root, repo)}): atticus map ${repo} --models all reads them.`);
+      io.out(reread ? `Re-reading ${repo} at ${commit.slice(0, 12)}: ${plural(plan.files, "source file")} changed since ${since}, in ${batches(plan.batches.length)}${plan.batches.length ? ` (about ${plan.tokens} tokens${limit ? `, each prompt within ${limit} tokens` : ""})` : ""}; ${plural(reread.reread.length, "fact")} to rewrite, ${reread.carried} carried as they are; facts go to ${factsFile}.` : `Reading ${repo} at ${commit.slice(0, 12)} in ${batches(plan.batches.length)} (${plural(plan.files, "source file")}, about ${plan.tokens} tokens${limit ? `, each prompt within ${limit} tokens` : ""}); facts go to ${factsFile}.`);
     }
-    const byId = new Map(existing.map((f) => [f.id, f]));
-    s = {
-      schemaVersion: 1,
-      repo,
-      commit,
-      ...limit ? { maxTokens: limit } : {},
-      room,
-      batches: plan.batches,
-      next: 0,
-      rejected: (reread?.reread ?? []).map((r) => {
-        const fact = byId.get(r.id);
-        return { id: r.id, code: "cite-changed", message: staleMessage(fact, r, commit), fact };
-      }),
-      problems: [],
-      ...reread ? {
-        reread: {
-          from: reread.from.map((x) => x.commit),
-          carried: reread.carried,
-          facts: reread.reread.length
-        }
-      } : {}
-    };
-    await saveState(root, s);
-    io.out(reread ? `Re-reading ${repo} at ${commit.slice(0, 12)}: ${plural(plan.files, "source file")} changed since ${since}, in ${batches(plan.batches.length)}${plan.batches.length ? ` (about ${plan.tokens} tokens${limit ? `, each prompt within ${limit} tokens` : ""})` : ""}; ${plural(reread.reread.length, "fact")} to rewrite, ${reread.carried} carried as they are; facts go to ${factsFile}.` : `Reading ${repo} at ${commit.slice(0, 12)} in ${batches(plan.batches.length)} (${plural(plan.files, "source file")}, about ${plan.tokens} tokens${limit ? `, each prompt within ${limit} tokens` : ""}); facts go to ${factsFile}.`);
   }
   if (!s)
     return 2;
@@ -565,7 +850,7 @@ async function mapCommand(root, repo, o, io, deps = {}) {
       break;
     if (fixRound)
       s.fixRound = true;
-    const { agent, pack } = await packFor(root, s, s.next, source, op, now());
+    const { agent, pack } = await packFor(root, s, s.next, source, op, now(), notesPrompt);
     const prepared = await runtime.prepare({
       change: changeOf(repo),
       agent,
@@ -617,36 +902,50 @@ async function takeAnswer(root, s, run, batch, source, exclude, now, io, at) {
     await saveState(root, { ...rest2, next: batch });
     return 1;
   }
-  const answer = readAnswer(run.output ?? "", s.repo, s.commit);
   const existing = await readFactsFile(root, s.repo);
   if (typeof existing === "string") {
     io.err(existing);
     return 2;
   }
+  const answer = readAnswer(run.output ?? "", s.repo, s.commit, existing);
   const merged = new Map(existing.map((f) => [f.id, f]));
   for (const f of answer.facts)
     merged.set(f.id, f);
   const { carry } = await carryOf(at.dir, [...merged.values()], s.commit, at.git);
   const reviewed = await readReviewed(root, s.repo);
+  const estate = await estateComponentsOf(root);
+  const off = stackHelpersOff();
   const report = await verifyFacts({
     facts: [...merged.values()],
     source,
     commit: s.commit,
+    // G4: the stack helpers this run switched off (ATTICUS_HELPERS_OFF).
+    ...off.has("derived-names") ? { derivedNames: false } : {},
+    ...off.has("readers") ? { readers: false } : {},
     carry,
     exclude,
     // ADR 0124 addendum D-app: a person's corrections hold through every batch of a read.
     corrections: (await readCorrections(root, s.repo)).corrections,
     // ADR 0124 addendum A-read: files the reader read and found nothing in, if it wrote any.
-    reviewed: reviewed.entries
+    reviewed: reviewed.entries,
+    // J1 (ADR 0143): an exposure names a component the manifest lists.
+    ...estate ? { estate } : {},
+    conventions: await conventionsAt(root),
+    // ADR 0163: a term's note is one of those the batch was handed.
+    notes: (await notesAt(root, s.repo, at.dir)).notes,
+    // ADR 0180: a component's type is one of the organisation's.
+    componentTypes: componentTypeIds(await componentTypesAt(root)),
+    // ADR 0169: the model files the read leaves out, counted apart.
+    notReached: (await loadReadPlan(root, s.repo))?.notReached?.files ?? []
   });
   const q = await raiseReadQuestions(root, s.repo, answer.questions, source, {
     command: `atticus map ${s.repo}`,
     run: run.runId,
     at: now().toISOString()
   });
-  const summary = await writeVerifyFiles(root, s.repo, report, s.commit, q.problems, [], reviewedProblemsOf(reviewed.bad, report));
+  const summary = await writeVerifyFiles(root, s.repo, report, s.commit, q.problems, [], reviewedProblemsOf(reviewed.bad, report), answer.slips);
   if (answer.about) {
-    const { keepDraftedDescription } = await import("./chunk-DPZHZQKE.js");
+    const { keepDraftedDescription } = await import("./chunk-TW3KOSQK.js");
     const d = await keepDraftedDescription(root, s.repo, answer.about, now());
     if (d.kept)
       io.out(`Your assistant says ${s.repo} is: "${answer.about.text}" \u2014 written to the manifest as a draft, unconfirmed. Confirm it (atticus repo describe ${s.repo} --accept), change it (--description "...") or drop it (--reject).`);
@@ -656,6 +955,8 @@ async function takeAnswer(root, s, run, batch, source, exclude, now, io, at) {
   const fresh = new Set(answer.facts.map((f) => f.id));
   const kept = report.accepted.filter((f) => fresh.has(f.id)).length;
   io.out(`${label}: ${plural(kept, "fact")} kept (${report.accepted.length} in all${report.carried.length ? `, ${report.carried.length} carried from an earlier commit` : ""}), ${report.rejected.length} rejected${q.raised.length ? `, ${plural(q.raised.length, "question")} raised for a person` : ""}${answer.problems.length ? `, ${plural(answer.problems.length, "line")} not read` : ""}.`);
+  for (const l of slipNoteLines(answer.slips, `${factsRelOf(root)}/${s.repo}.verify.yaml`))
+    io.out(l);
   const { waiting: _w, ...rest } = s;
   const rejected = report.rejected.map((r) => ({
     id: r.fact.id,
@@ -677,6 +978,10 @@ async function finish(root, s, io, o) {
   s.done = true;
   await saveState(root, s);
   const last = s.last;
+  if (last && !last.rejected && !s.reread) {
+    const { recordRulesNow } = await import("./chunk-TJH2EUAZ.js");
+    await recordRulesNow(root, s.repo, s.commit, s.sets);
+  }
   const rel = factsRelOf(root);
   if (o.json) {
     io.out(JSON.stringify({ state: "done", repo: s.repo, batches: s.batches.length, ...last }, null, 2));
@@ -686,7 +991,7 @@ async function finish(root, s, io, o) {
     io.out(`Read ${s.repo}: nothing was kept.`);
     return 0;
   }
-  io.out(`Read ${s.repo} in ${batches(s.batches.length)}: ${plural(last.accepted, "fact")} kept in ${rel}/${s.repo}.jsonl, ${last.rejected} still rejected; coverage ${Math.round(last.coverage.ratio * 100)}% (${last.coverage.read} read, ${last.coverage.reviewed ? `${last.coverage.reviewed} reviewed with nothing to record, ` : ""}${last.coverage.unknown.length} unknown).`);
+  io.out(`Read ${s.repo} in ${batches(s.batches.length)}: ${plural(last.accepted, "fact")} kept in ${rel}/${s.repo}.jsonl, ${last.rejected} still rejected; coverage ${Math.round(last.coverage.ratio * 100)}% (${last.coverage.read} read, ${last.coverage.reviewed ? `${last.coverage.reviewed} reviewed with nothing to record, ` : ""}${last.coverage.unknown.length} unknown${last.coverage.notReached?.length ? `, ${last.coverage.notReached.length} model files no entry or call reaches` : ""}).`);
   if (last.rejected)
     io.out(`The rejected facts are in ${rel}/${s.repo}.rejected.jsonl; fix them by hand or with your assistant, then atticus verify ${s.repo}.`);
   if (last.coverage.unknown.length)
@@ -718,37 +1023,103 @@ function rereadLines(repo, r) {
 }
 async function estimate(root, repo, c, io) {
   const tier = await tierHere(root, c.op);
+  const conventions = conventionsOf(c.op);
   const { limit: given, from } = limitOf(c.o, c.op, tier);
   const limit = given ?? EXAMPLE_LIMIT;
   const about = await aboutOf(root, repo);
   const room = roomFor(limit, c.op, repo, c.commit);
   const existing = await readFactsFile(root, repo);
-  const re = typeof existing === "string" ? { missing: [] } : await rereadOf(c.dir, existing, c.commit, c.source, c.exclude, c.git);
+  const re = typeof existing === "string" ? { missing: [] } : await rereadOf(c.dir, existing, c.commit, c.source, c.exclude, c.git, conventions);
   const reread = re.plan && !re.plan.unknown.length ? re.plan : void 0;
   const readSource = reread ? onlyFiles(c.source, reread.files.map((f) => f.path)) : c.source;
-  const repoWhole = reread ? planBatches(c.source, { room: Number.MAX_SAFE_INTEGER, exclude: c.exclude }) : void 0;
-  const whole = planBatches(readSource, { room: Number.MAX_SAFE_INTEGER, exclude: c.exclude });
-  const planned = room >= MIN_ROOM ? planBatches(readSource, {
-    room,
+  const repoWhole = reread ? planBatches(c.source, { room: Number.MAX_SAFE_INTEGER, exclude: c.exclude, conventions }) : void 0;
+  const whole = planBatches(readSource, {
+    room: Number.MAX_SAFE_INTEGER,
     exclude: c.exclude,
-    overhead: overheadOf(repo, c.commit, await frameworksFor(root, repo, typeof existing === "string" ? [] : existing))
-  }) : void 0;
-  const plan = planned && planned.leastRoom >= MIN_ROOM ? planned : void 0;
+    conventions
+  });
   const files = whole.batches.flat().map((s) => ({ path: s.path, tokens: s.tokens }));
   const proposed = reread ? { proposals: [], before: whole.tokens, after: whole.tokens } : proposeExclusions(files, c.source.list(), (p) => c.source.read(p), {
     // What the person's description plainly says this repo holds (ADR 0128).
     saysNotProduct: saysNotProduct(about)
   });
   const left = proposed.proposals.map((p) => p.path.slice(0, -2));
-  const session = Math.max(SESSION_TOKENS, Math.floor(0.75 * (given ?? 0)));
-  const product = files.filter((f) => !left.some((d) => f.path.startsWith(d)));
-  const parts = planParts(product, session);
+  const session = sessionTokensFor(given);
+  const product = files.filter((f) => !left.some((d) => f.path.startsWith(d))).map((f) => {
+    if (f.tokens <= session)
+      return f;
+    const text = c.source.read(f.path);
+    return text === void 0 ? f : { ...f, lines: text.split(/\r?\n/).length };
+  });
+  const mode = await modelsModeOf(root, repo, c.o.models);
+  const facts0 = typeof existing === "string" ? [] : existing;
+  const rp = reread ? void 0 : reachPlanOf({ paths: product.map((f) => f.path), source: c.source, facts: facts0, mode });
+  const leave = new Set(rp?.leaveOut ?? []);
+  const kept = product.filter((f) => !leave.has(f.path));
+  const ordered = rp && rp.reach.rooted && rp.reach.models > 0;
+  const parts = planParts(kept, session, ordered ? {
+    head: reachHeadOf(kept.map((f) => f.path), rp),
+    models: rp.reach.reached.map((r) => r.path),
+    leftOut: rp.leaveOut
+  } : void 0);
+  const planned = room >= MIN_ROOM ? planBatches(readSource, {
+    room,
+    exclude: c.exclude,
+    conventions,
+    overhead: overheadOf(repo, c.commit, await frameworksFor(root, repo, facts0)),
+    ...rp && ordered ? { reach: { first: rp.first, leaveOut: rp.leaveOut } } : {}
+  }) : void 0;
+  const plan = planned && planned.leastRoom >= MIN_ROOM ? planned : void 0;
   const plan0 = await loadReadPlan(root, repo);
   const same = plan0 !== void 0 && plan0.commit === c.commit && plan0.session === session && plan0.parts.length === parts.length && plan0.parts.every((p, i) => p.paths.length === parts[i].paths.length && p.paths.every((x, j) => x === parts[i].paths[j]));
-  if (parts.length && !same)
-    await writeReadPlan(root, repo, { commit: c.commit, session, parts });
+  const estimate2 = {
+    files: kept.length,
+    tokens: kept.reduce((n, f) => n + f.tokens, 0),
+    sessions: parts.length || 1,
+    ...reread ? { reread: true } : {}
+  };
+  const sameEstimate = plan0?.estimate !== void 0 && plan0.estimate.files === estimate2.files && plan0.estimate.tokens === estimate2.tokens && plan0.estimate.sessions === estimate2.sessions && plan0.estimate.reread === estimate2.reread;
+  const firstRead = typeof existing !== "string" && existing.length === 0 && !reread;
+  const orgRuleIds = ruleIds(await effectiveRules(root, repo, { dir: c.dir, op: c.op }));
+  const readRules = firstRead ? { hash: rulesNow().hash, sets: [...rulesNow().sets, ...orgRuleIds] } : plan0?.rules;
+  const notReached = rp ? rp.notReached : plan0?.notReached;
+  const sameModels = plan0 !== void 0 && (plan0.models ?? "reachable") === mode && JSON.stringify(plan0.notReached ?? null) === JSON.stringify(notReached ?? null);
+  if (!same)
+    await writeReadPlan(root, repo, {
+      commit: c.commit,
+      session,
+      parts,
+      estimate: estimate2,
+      // What the reader reported of an earlier plan stays, under the commit it was of.
+      ...plan0?.reported ? { reported: plan0.reported } : {},
+      ...readRules ? { rules: readRules } : {},
+      models: mode,
+      ...notReached ? { notReached } : {}
+    });
+  else if (!sameEstimate || !sameModels || firstRead && plan0.rules?.hash !== readRules?.hash) {
+    const { notReached: _n, models: _m, ...rest0 } = plan0;
+    await saveReadPlan(root, {
+      ...rest0,
+      estimate: estimate2,
+      ...readRules ? { rules: readRules } : {},
+      ...mode !== "reachable" ? { models: mode } : {},
+      ...notReached ? { notReached } : {}
+    });
+  }
   const progress = parts.length ? await readPlanProgress(root, repo, { commit: c.commit }) : void 0;
   const questions = (await listQuestions(root, { repo })).questions.filter((q) => q.state !== "retired");
+  const notes = await notesAt(root, repo, c.dir, c.op);
+  const rules = await rulesCovering(root, repo, c.op);
+  const house = await houseUntaughtOf(root, repo, {
+    dir: c.dir,
+    source: c.source,
+    op: c.op,
+    exclude: c.exclude
+  });
+  if (c.o.part !== void 0 && !parts[c.o.part - 1]) {
+    io.err(`${repo} is read in ${parts.length ? `parts 1 to ${parts.length}` : "one session (no parts)"} at this limit: there is no part ${c.o.part}.`);
+    return 2;
+  }
   if (c.o.json) {
     io.out(JSON.stringify({
       repo,
@@ -763,6 +1134,8 @@ async function estimate(root, repo, c, io) {
       maxTokensGiven: given !== void 0,
       maxTokensFrom: from ?? "example",
       batches: plan?.batches.length ?? null,
+      // ADR 0169: what the read plans to read (the model classes it leaves out, out).
+      read: { files: estimate2.files, tokens: estimate2.tokens },
       order: whole.batches.flat().map((x) => x.path),
       // ADR 0128: what a person says the repo is, and whether that eased the proposals.
       about: about ? { text: about.text, trust: about.trust, eased: saysNotProduct(about) } : null,
@@ -786,13 +1159,29 @@ async function estimate(root, repo, c, io) {
           }
         } : {}
       },
+      // ADR 0169: the model classes reached from the entry points and calls, and those left out.
+      models: rp ? {
+        mode,
+        roots: rp.reach.roots,
+        reached: rp.reach.reached,
+        notReached: rp.leaveOut
+      } : null,
       tier,
+      // A-taught: the frameworks of the organisation it is built on, as taught to Atticus.
+      taughtFrameworks: taughtIn(c.source, c.op).map((m) => m.name),
+      // R3: the house packages to teach before the first read.
+      houseUntaught: house,
+      // ADR 0163: the org notes the reader is handed, numbered, and the repo type they are of.
+      notes: { ...notes.type ? { repoType: notes.type } : {}, notes: notes.notes },
+      // G4 (ADR 0176): the organisation's reading rules for this repo, as the reader follows them.
+      readingRules: readingRulesText(await effectiveRules(root, repo, { dir: c.dir, op: c.op })),
       questions: questions.map((q) => ({
         id: q.id,
         question: q.question,
         state: q.state,
         ...q.answer ? { answer: q.answer } : {}
       })),
+      rules,
       // A re-read: what the files and batches above are, and the facts to revisit.
       reread: reread ? {
         ...reread,
@@ -809,6 +1198,23 @@ async function estimate(root, repo, c, io) {
   io.out(`${repo} at ${c.commit} in ${c.dir}`);
   io.out(about ? `What it is (${descriptionTrust(about)}${about.by ? `, ${about.by}` : ""}): ${about.text} \u2014 a person's note from the manifest, not read from the code: where the code says otherwise, the code is right.` : `What it is: nothing says yet. A person writes one line (atticus repo describe ${repo} --description "..."); if the files say plainly, hand yours over with atticus repo describe ${repo} --drafted "..." --cites <file>:<line>, and it waits for a person.`);
   io.out(`Facts file: ${c.factsFile}`);
+  const taught = taughtFrameworksText(taughtIn(c.source, c.op));
+  if (taught)
+    for (const l of taught.split("\n"))
+      io.out(l);
+  const notesLines = notesText(notes.notes, notes.type);
+  if (notesLines)
+    for (const l of notesLines.split("\n"))
+      io.out(l);
+  for (const l of componentTypesText(await componentTypesAt(root, c.op)).split("\n"))
+    if (l)
+      io.out(l);
+  const orgRulesLines = readingRulesText(await effectiveRules(root, repo, { dir: c.dir, op: c.op }));
+  if (orgRulesLines)
+    for (const l of orgRulesLines.split("\n"))
+      io.out(l);
+  for (const l of houseUntaughtLines(repo, house))
+    io.out(l);
   if (reread)
     for (const l of rereadLines(repo, reread))
       io.out(l);
@@ -839,13 +1245,25 @@ repo: ${repo}`);
     const stateOf = (i) => progress?.parts[i]?.state;
     const words = (s) => s === "done" ? "done" : s === "in-progress" ? "part-read" : "to read";
     parts.forEach((p, i) => io.out(`  part ${i + 1} (${words(stateOf(i))}, about ${p.tokens} tokens, ${plural(p.files, "file")}): ${p.paths.join(", ")}`));
-    if (progress) {
+    const asked = c.o.part !== void 0 ? parts[c.o.part - 1] : void 0;
+    if (asked)
+      io.out(`This session reads part ${c.o.part} of ${parts.length} (--part ${c.o.part}): ${asked.paths.join(", ")}. The facts on file stay, as already kept: name one by its id and don't write it again.`);
+    if (progress && !asked) {
       io.out(`Read plan: ${readPlanRelOf(root, repo)}. ${progress.next ? `${partOfWords({ part: progress.next.part, total: progress.total })} is next (${progress.done ? `${progress.done} of ${progress.total} read` : `none of ${progress.total} read yet`}): ${progress.next.paths.join(", ")}.` : `All ${progress.total} parts are read.`} A part counts as read when every folder it covers is in the facts (a fact citing a file, or a line of ${factsRelOf(root)}/${repo}.reviewed.jsonl); atticus next says which comes next.`);
       for (const p of progress.parts)
         if (p.state === "in-progress")
           io.out(`  part ${p.part} is part-read: nothing in the facts yet for ${p.left.join(", ")}.`);
     }
   }
+  const line = rp ? modelsLine(repo, rp) : void 0;
+  if (rp && line) {
+    io.out(line);
+    const data = modelsData(repo, rp);
+    if (data) {
+      io.out(MODELS_RULE);
+      io.out(data);
+    }
+  }
   io.out(`Your assistant: ${tierWords(tier)}, ${tierSource(tier)}. ${tier.how}`);
   io.out(`Another agentic assistant (Claude Code, Cursor, Gemini CLI) reads it the same way: /atticus-map ${repo}; one without file tools gets batches with atticus map ${repo} --handoff --max-tokens <its limit>.`);
   if (tier.fallback)
@@ -861,13 +1279,20 @@ repo: ${repo}`);
   io.out(plan ? `In batches at ${limit} tokens a prompt${given === void 0 ? " (GPT-4o mini through Copilot; --max-tokens n for your model's limit)" : from === "probe" ? ` (the limit stated when your assistant was measured on ${tier.measured?.at})` : ""}: ${plural(plan.batches.length, "prompt")}, one more if facts are rejected in the last.` : `A model of ${limit} tokens leaves too little room for the files beside the instructions: use a model with a bigger limit.`);
   for (const q of questions)
     io.out(`Question ${q.id}: ${q.question} (${q.state === "answered" ? `answered: ${q.answer?.text ?? q.options[(q.answer?.option ?? 1) - 1]?.label ?? ""}` : "open"})`);
-  if (questions.length)
-    io.out("Follow each answer; don't ask these again.");
+  for (const r of rules)
+    io.out(ruleLineOf(r));
+  if (questions.length || rules.length)
+    io.out("Follow each answer and each rule; don't ask what they settle again.");
   return 0;
 }
+
 export {
   REPO_READER,
-  mapCommand,
+  repoReaderAgent,
+  mapStateOf,
   readAnswer,
-  repoReaderAgent
+  rulesCovering,
+  ruleLineOf,
+  taughtIn,
+  mapCommand
 };