@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.1

package/dist/core/docs.js

@@ -11,8 +11,10 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { AGENTS_MD } from "./agent.js";
-import { AGENTS_FILENAME } from "./repo.js";
+import { AGENTS_MD } from "./agent/agents-md.js";
+import { LANDSCAPE_STUB } from "./scaffold/landscape.js";
+import { README_FILENAME, README_MD } from "./scaffold/readme.js";
+import { AGENTS_FILENAME } from "./repo/paths.js";
 /**
  * Top-level layout of the shared docs repo, and part of its identity rather
  * than a convenience: `services/` is what makes a directory a docs repo —
@@ -30,68 +32,6 @@ const EMPTY_SUBDIRS = [
     ["services", ".gitkeep"],
     ["features", ".gitkeep"],
 ];
-/**
- * The fleet map, empty but valid.
- *
- * Nobody writes this file automatically — `adopt` deliberately does not touch
- * it, because who calls whom is a human judgement and a generated landscape
- * would be a guess presented as the map. But "nobody writes it" used to mean
- * "it is simply absent", and an absent landscape is the one artifact whose
- * absence silences the fleet-wide checks entirely: every cross-service breach
- * `validate` exists to find is invisible on a repo with no landscape.
- *
- * So the scaffold lays down the empty map instead: the four element kinds a
- * fleet actually uses are declared, the model is empty, and the comments say
- * what to add and why. The first `loam adopt` then has somewhere to be drawn.
- *
- * No `views` block, deliberately. loam reads elements and relationships and
- * never a view, so the scaffolded `view index { include * }` was a diagram loam
- * planted on every repo and then never drew — and views are the expensive half
- * of LikeC4: computing them is superlinear in edge count (120 services / 300
- * calls does not finish in three minutes; parsing the same file takes 11 ms).
- * loam stopped computing views, so the block is free for loam itself now, but
- * scaffolding one still hands the user a fleet-sized bill for the first tool
- * that does compute it. Teams who want diagrams declare their own.
- */
-const LANDSCAPE_STUB = `// The fleet map: every service in services/ appears here, and every call
-// between two of them is an edge. This file is written by hand — loam never
-// guesses it, because "who calls whom" is the one fact no generator can read
-// off a repository.
-//
-// After \`loam adopt --service <id>\`, add the service here:
-//
-//   paymentService = softwareSystem 'payment-service' {
-//     description 'Owns payment authorization/capture'
-//     metadata { service 'payment-service' }   // binds the box to services/<id>/
-//   }
-//
-// and give each call the operationId it uses, so requirements, C4 and OpenAPI
-// can be cross-checked:
-//
-//   checkoutWeb -> paymentService 'Authorizes' {
-//     metadata { op 'authorizePayment' }
-//   }
-//
-// There is no \`views\` block, on purpose: loam reads the model and never a
-// view, so it would draw nothing. Add views here if you want diagrams, and
-// render them with LikeC4's own tooling — \`npx likec4 start\` from the docs
-// repo root, which likec4.config.json scopes to this directory. (A service
-// model or a feature delta renders from its OWN directory, e.g.
-// \`npx likec4 start services/<id>\`: each declares its own \`specification\`
-// block, so the renderer can only be given one of them at a time.) Scope your
-// views, because computing one is superlinear in the number of edges and an
-// \`include *\` over a whole fleet takes minutes.
-
-specification {
-  element person
-  element softwareSystem
-  element container
-  element database
-}
-
-model {
-}
-`;
 /**
  * The LikeC4 project file, and the one thing in the docs repo loam writes for a
  * tool other than itself.
@@ -183,6 +123,9 @@ export async function scaffoldDocs(docsDir) {
 export function docsRepoFiles(opts = {}) {
     const preamble = opts.landscapePreamble === undefined ? "" : `${opts.landscapePreamble.trimEnd()}\n//\n`;
     return [
+        // The one file addressed to a person, first because a forge renders it as
+        // the landing page and a reader meets it before anything else here.
+        [README_FILENAME, README_MD],
         // The process contract lives with the docs it describes, so an agent handed
         // only the docs repo still knows the cycle.
         [AGENTS_FILENAME, AGENTS_MD],

package/dist/core/docs.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/core/docs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Scaffolding for the shared docs repo.\n *\n * There is deliberately no manifest. `init` used to write a `loam.docs.json`\n * listing the repo's services; nothing ever read it — `repo.ts` enumerates from\n * the filesystem, because files are the source of truth — and nothing ever\n * updated it, so it named an empty fleet forever. A second list of services is\n * exactly the drift `loam validate` now cross-checks the landscape for; the\n * cheapest way to keep it honest is not to have it.\n */\nimport { mkdir, writeFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { AGENTS_MD } from \"./agent.js\";\nimport { AGENTS_FILENAME } from \"./repo.js\";\n\n/**\n * Top-level layout of the shared docs repo, and part of its identity rather\n * than a convenience: `services/` is what makes a directory a docs repo —\n * `init` will not join one without it, and every enumerating command refuses a\n * `docsDir` that has none. So it is laid down even when nothing is in it yet.\n */\nexport const DOCS_SUBDIRS = [\"architecture\", \"services\", \"features\"] as const;\n\n/**\n * The scaffolded directories that start out empty, and the file that keeps each\n * of them in version control. See {@link GITKEEP}. Spelled as pairs so the\n * marker's name is written once — `listServices` and `listFeatures` enumerate\n * subdirectories only, so a file here is invisible to both.\n */\nconst EMPTY_SUBDIRS = [\n  [\"services\", \".gitkeep\"],\n  [\"features\", \".gitkeep\"],\n] as const;\n\n/**\n * The fleet map, empty but valid.\n *\n * Nobody writes this file automatically — `adopt` deliberately does not touch\n * it, because who calls whom is a human judgement and a generated landscape\n * would be a guess presented as the map. But \"nobody writes it\" used to mean\n * \"it is simply absent\", and an absent landscape is the one artifact whose\n * absence silences the fleet-wide checks entirely: every cross-service breach\n * `validate` exists to find is invisible on a repo with no landscape.\n *\n * So the scaffold lays down the empty map instead: the four element kinds a\n * fleet actually uses are declared, the model is empty, and the comments say\n * what to add and why. The first `loam adopt` then has somewhere to be drawn.\n *\n * No `views` block, deliberately. loam reads elements and relationships and\n * never a view, so the scaffolded `view index { include * }` was a diagram loam\n * planted on every repo and then never drew — and views are the expensive half\n * of LikeC4: computing them is superlinear in edge count (120 services / 300\n * calls does not finish in three minutes; parsing the same file takes 11 ms).\n * loam stopped computing views, so the block is free for loam itself now, but\n * scaffolding one still hands the user a fleet-sized bill for the first tool\n * that does compute it. Teams who want diagrams declare their own.\n */\nconst LANDSCAPE_STUB = `// The fleet map: every service in services/ appears here, and every call\n// between two of them is an edge. This file is written by hand — loam never\n// guesses it, because \"who calls whom\" is the one fact no generator can read\n// off a repository.\n//\n// After \\`loam adopt --service <id>\\`, add the service here:\n//\n//   paymentService = softwareSystem 'payment-service' {\n//     description 'Owns payment authorization/capture'\n//     metadata { service 'payment-service' }   // binds the box to services/<id>/\n//   }\n//\n// and give each call the operationId it uses, so requirements, C4 and OpenAPI\n// can be cross-checked:\n//\n//   checkoutWeb -> paymentService 'Authorizes' {\n//     metadata { op 'authorizePayment' }\n//   }\n//\n// There is no \\`views\\` block, on purpose: loam reads the model and never a\n// view, so it would draw nothing. Add views here if you want diagrams, and\n// render them with LikeC4's own tooling — \\`npx likec4 start\\` from the docs\n// repo root, which likec4.config.json scopes to this directory. (A service\n// model or a feature delta renders from its OWN directory, e.g.\n// \\`npx likec4 start services/<id>\\`: each declares its own \\`specification\\`\n// block, so the renderer can only be given one of them at a time.) Scope your\n// views, because computing one is superlinear in the number of edges and an\n// \\`include *\\` over a whole fleet takes minutes.\n\nspecification {\n  element person\n  element softwareSystem\n  element container\n  element database\n}\n\nmodel {\n}\n`;\n\n/**\n * The LikeC4 project file, and the one thing in the docs repo loam writes for a\n * tool other than itself.\n *\n * LikeC4's workspace loader merges EVERY `.likec4` file under a directory tree\n * into one model. loam's layout is the opposite by design: the landscape,\n * each `services/<id>/model.likec4` and each `features/<FEAT>/delta.likec4` is\n * parsed in isolation (`loadSource`, one file, one throwaway workspace), so\n * every one of them legitimately declares its own `specification { … }` block\n * and re-declares the elements it needs to talk about. Point the real renderer\n * at the repository root and those declarations collide: on loam's own\n * `examples/docs` — four files — `npx likec4 start` reported 16 errors, sixteen\n * duplicate kinds and names, while `loam validate --all` reported none. Both\n * were right; only one of them was reading the tree as a workspace.\n *\n * So the root is declared as one LikeC4 project holding the landscape, and the\n * two directories whose files are meant to be read alone are excluded from it.\n * That makes `npx likec4 start` in the docs repo — the command loam's own docs\n * have always recommended — render the fleet map instead of failing. A service\n * model or a feature delta is still rendered by pointing the renderer at its own\n * directory, which is what parsing them in isolation meant all along.\n *\n * `**\\/node_modules/**` is repeated because naming `exclude` replaces LikeC4's\n * default rather than adding to it. loam reads none of this file: it is written\n * once, never re-read, and a team that wants a different project layout owns it\n * like every other scaffolded file.\n */\nexport const LIKEC4_PROJECT_FILENAME = \"likec4.config.json\";\n\nexport const LIKEC4_PROJECT_CONFIG = `${JSON.stringify(\n  {\n    name: \"fleet\",\n    title: \"Fleet landscape\",\n    exclude: [\"**/node_modules/**\", \"services/**\", \"features/**\"],\n  },\n  null,\n  2,\n)}\\n`;\n\n/**\n * The placeholder that makes an empty scaffolded directory survive a clone.\n *\n * git tracks files, not directories, so `services/` and `features/` — created\n * empty by `loam init --create` — were absent for everyone after the first push:\n * the person who ran init had a green repo, and the second person to clone it\n * got `doctor.services-missing`, a BLOCKER, on a repository nobody had touched.\n * A repo that cannot survive being cloned is not a shared docs repo.\n */\nconst GITKEEP = \"\";\n\n/**\n * The docs repo's own loam.json. It makes the docs repo self-describing: a\n * command run from inside it (or from any directory under it) finds this file\n * first and resolves the fleet to the repo it is standing in, instead of\n * walking out to whatever service repo happens to be above.\n *\n * `\".\"` and not an absolute path for the same reason every other docsDir is\n * stored as written: this file is committed and cloned to machines whose\n * directory layout nobody here can predict.\n */\nconst DOCS_SELF_CONFIG = `${JSON.stringify({ docsDir: \".\" }, null, 2)}\\n`;\n\nexport interface ScaffoldResult {\n  root: string;\n  created: string[];\n}\n\n/** Idempotently create the docs-repo skeleton. Existing files/dirs are left untouched. */\nexport async function scaffoldDocs(docsDir: string): Promise<ScaffoldResult> {\n  const root = resolve(docsDir);\n  const created: string[] = [];\n\n  await mkdir(root, { recursive: true });\n\n  for (const dir of DOCS_SUBDIRS) {\n    const p = join(root, dir);\n    if (!existsSync(p)) {\n      await mkdir(p, { recursive: true });\n      created.push(p);\n    }\n  }\n\n  // Never overwritten, all three of them — a team's own house rules, their own\n  // map and their own config outrank the template. The order here IS the order\n  // `init` probes for what it will skip; keep the two lists in step.\n  for (const [rel, content] of docsRepoFiles()) {\n    const path = join(root, rel);\n    if (!existsSync(path)) {\n      await writeFile(path, content, \"utf8\");\n      created.push(path);\n    }\n  }\n\n  return { root, created };\n}\n\nexport interface DocsRepoFileOptions {\n  /**\n   * Comment lines prepended to the landscape stub, for a scaffold with a reason\n   * of its own to hand over an empty map — `migrate-openspec` stages a docs repo\n   * out of a corpus that HAS no topology, and says so where the migrator reads.\n   *\n   * A parameter and not a second template on purpose. The rest of the stub —\n   * how to declare a service, how to bind an edge to an operationId, why there\n   * is no `views` block — is the same advice however the repo came to exist, and\n   * the migration used to carry its own shorter copy of it: two files that were\n   * both correct on the day they were written and could only diverge after.\n   */\n  landscapePreamble?: string;\n}\n\n/**\n * The files every docs repo starts with, relative to its root, in creation\n * order. `init` scaffolds them directly; `migrate-openspec` stages the same\n * bytes into its target, because the whole point of migrating into a docs repo\n * is that it be the docs repo `loam init` makes.\n *\n * Exported as paths only (via `plannedDocsFiles`) where `init` reports what it\n * will skip — a duplicate list is exactly the drift that made `created +\n * skipped` disagree with reality.\n */\nexport function docsRepoFiles(opts: DocsRepoFileOptions = {}): Array<[string, string]> {\n  const preamble = opts.landscapePreamble === undefined ? \"\" : `${opts.landscapePreamble.trimEnd()}\\n//\\n`;\n  return [\n    // The process contract lives with the docs it describes, so an agent handed\n    // only the docs repo still knows the cycle.\n    [AGENTS_FILENAME, AGENTS_MD],\n    [join(\"architecture\", \"landscape.likec4\"), `${preamble}${LANDSCAPE_STUB}`],\n    [\"loam.json\", DOCS_SELF_CONFIG],\n    [LIKEC4_PROJECT_FILENAME, LIKEC4_PROJECT_CONFIG],\n    // The two directories git would otherwise drop on the way to the next\n    // clone. `architecture/` needs none — the landscape above is in it.\n    ...EMPTY_SUBDIRS.map(([dir, keep]) => [join(dir, keep), GITKEEP] as [string, string]),\n  ];\n}\n\n/** Everything `scaffoldDocs(docsDir)` would create, in the order it creates it. */\nexport function plannedDocsFiles(docsDir: string): string[] {\n  const root = resolve(docsDir);\n  return [\n    ...DOCS_SUBDIRS.map((d) => join(root, d)),\n    ...docsRepoFiles().map(([rel]) => join(root, rel)),\n  ];\n}\n"]}
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/core/docs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Scaffolding for the shared docs repo.\n *\n * There is deliberately no manifest. `init` used to write a `loam.docs.json`\n * listing the repo's services; nothing ever read it — `repo.ts` enumerates from\n * the filesystem, because files are the source of truth — and nothing ever\n * updated it, so it named an empty fleet forever. A second list of services is\n * exactly the drift `loam validate` now cross-checks the landscape for; the\n * cheapest way to keep it honest is not to have it.\n */\nimport { mkdir, writeFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { AGENTS_MD } from \"./agent/agents-md.js\";\nimport { LANDSCAPE_STUB } from \"./scaffold/landscape.js\";\nimport { README_FILENAME, README_MD } from \"./scaffold/readme.js\";\nimport { AGENTS_FILENAME } from \"./repo/paths.js\";\n\n/**\n * Top-level layout of the shared docs repo, and part of its identity rather\n * than a convenience: `services/` is what makes a directory a docs repo —\n * `init` will not join one without it, and every enumerating command refuses a\n * `docsDir` that has none. So it is laid down even when nothing is in it yet.\n */\nexport const DOCS_SUBDIRS = [\"architecture\", \"services\", \"features\"] as const;\n\n/**\n * The scaffolded directories that start out empty, and the file that keeps each\n * of them in version control. See {@link GITKEEP}. Spelled as pairs so the\n * marker's name is written once — `listServices` and `listFeatures` enumerate\n * subdirectories only, so a file here is invisible to both.\n */\nconst EMPTY_SUBDIRS = [\n  [\"services\", \".gitkeep\"],\n  [\"features\", \".gitkeep\"],\n] as const;\n\n/**\n * The LikeC4 project file, and the one thing in the docs repo loam writes for a\n * tool other than itself.\n *\n * LikeC4's workspace loader merges EVERY `.likec4` file under a directory tree\n * into one model. loam's layout is the opposite by design: the landscape,\n * each `services/<id>/model.likec4` and each `features/<FEAT>/delta.likec4` is\n * parsed in isolation (`loadSource`, one file, one throwaway workspace), so\n * every one of them legitimately declares its own `specification { … }` block\n * and re-declares the elements it needs to talk about. Point the real renderer\n * at the repository root and those declarations collide: on loam's own\n * `examples/docs` — four files — `npx likec4 start` reported 16 errors, sixteen\n * duplicate kinds and names, while `loam validate --all` reported none. Both\n * were right; only one of them was reading the tree as a workspace.\n *\n * So the root is declared as one LikeC4 project holding the landscape, and the\n * two directories whose files are meant to be read alone are excluded from it.\n * That makes `npx likec4 start` in the docs repo — the command loam's own docs\n * have always recommended — render the fleet map instead of failing. A service\n * model or a feature delta is still rendered by pointing the renderer at its own\n * directory, which is what parsing them in isolation meant all along.\n *\n * `**\\/node_modules/**` is repeated because naming `exclude` replaces LikeC4's\n * default rather than adding to it. loam reads none of this file: it is written\n * once, never re-read, and a team that wants a different project layout owns it\n * like every other scaffolded file.\n */\nexport const LIKEC4_PROJECT_FILENAME = \"likec4.config.json\";\n\nexport const LIKEC4_PROJECT_CONFIG = `${JSON.stringify(\n  {\n    name: \"fleet\",\n    title: \"Fleet landscape\",\n    exclude: [\"**/node_modules/**\", \"services/**\", \"features/**\"],\n  },\n  null,\n  2,\n)}\\n`;\n\n/**\n * The placeholder that makes an empty scaffolded directory survive a clone.\n *\n * git tracks files, not directories, so `services/` and `features/` — created\n * empty by `loam init --create` — were absent for everyone after the first push:\n * the person who ran init had a green repo, and the second person to clone it\n * got `doctor.services-missing`, a BLOCKER, on a repository nobody had touched.\n * A repo that cannot survive being cloned is not a shared docs repo.\n */\nconst GITKEEP = \"\";\n\n/**\n * The docs repo's own loam.json. It makes the docs repo self-describing: a\n * command run from inside it (or from any directory under it) finds this file\n * first and resolves the fleet to the repo it is standing in, instead of\n * walking out to whatever service repo happens to be above.\n *\n * `\".\"` and not an absolute path for the same reason every other docsDir is\n * stored as written: this file is committed and cloned to machines whose\n * directory layout nobody here can predict.\n */\nconst DOCS_SELF_CONFIG = `${JSON.stringify({ docsDir: \".\" }, null, 2)}\\n`;\n\nexport interface ScaffoldResult {\n  root: string;\n  created: string[];\n}\n\n/** Idempotently create the docs-repo skeleton. Existing files/dirs are left untouched. */\nexport async function scaffoldDocs(docsDir: string): Promise<ScaffoldResult> {\n  const root = resolve(docsDir);\n  const created: string[] = [];\n\n  await mkdir(root, { recursive: true });\n\n  for (const dir of DOCS_SUBDIRS) {\n    const p = join(root, dir);\n    if (!existsSync(p)) {\n      await mkdir(p, { recursive: true });\n      created.push(p);\n    }\n  }\n\n  // Never overwritten, all three of them — a team's own house rules, their own\n  // map and their own config outrank the template. The order here IS the order\n  // `init` probes for what it will skip; keep the two lists in step.\n  for (const [rel, content] of docsRepoFiles()) {\n    const path = join(root, rel);\n    if (!existsSync(path)) {\n      await writeFile(path, content, \"utf8\");\n      created.push(path);\n    }\n  }\n\n  return { root, created };\n}\n\nexport interface DocsRepoFileOptions {\n  /**\n   * Comment lines prepended to the landscape stub, for a scaffold with a reason\n   * of its own to hand over an empty map — `migrate-openspec` stages a docs repo\n   * out of a corpus that HAS no topology, and says so where the migrator reads.\n   *\n   * A parameter and not a second template on purpose. The rest of the stub —\n   * how to declare a service, how to bind an edge to an operationId, why there\n   * is no `views` block — is the same advice however the repo came to exist, and\n   * the migration used to carry its own shorter copy of it: two files that were\n   * both correct on the day they were written and could only diverge after.\n   */\n  landscapePreamble?: string;\n}\n\n/**\n * The files every docs repo starts with, relative to its root, in creation\n * order. `init` scaffolds them directly; `migrate-openspec` stages the same\n * bytes into its target, because the whole point of migrating into a docs repo\n * is that it be the docs repo `loam init` makes.\n *\n * Exported as paths only (via `plannedDocsFiles`) where `init` reports what it\n * will skip — a duplicate list is exactly the drift that made `created +\n * skipped` disagree with reality.\n */\nexport function docsRepoFiles(opts: DocsRepoFileOptions = {}): Array<[string, string]> {\n  const preamble = opts.landscapePreamble === undefined ? \"\" : `${opts.landscapePreamble.trimEnd()}\\n//\\n`;\n  return [\n    // The one file addressed to a person, first because a forge renders it as\n    // the landing page and a reader meets it before anything else here.\n    [README_FILENAME, README_MD],\n    // The process contract lives with the docs it describes, so an agent handed\n    // only the docs repo still knows the cycle.\n    [AGENTS_FILENAME, AGENTS_MD],\n    [join(\"architecture\", \"landscape.likec4\"), `${preamble}${LANDSCAPE_STUB}`],\n    [\"loam.json\", DOCS_SELF_CONFIG],\n    [LIKEC4_PROJECT_FILENAME, LIKEC4_PROJECT_CONFIG],\n    // The two directories git would otherwise drop on the way to the next\n    // clone. `architecture/` needs none — the landscape above is in it.\n    ...EMPTY_SUBDIRS.map(([dir, keep]) => [join(dir, keep), GITKEEP] as [string, string]),\n  ];\n}\n\n/** Everything `scaffoldDocs(docsDir)` would create, in the order it creates it. */\nexport function plannedDocsFiles(docsDir: string): string[] {\n  const root = resolve(docsDir);\n  return [\n    ...DOCS_SUBDIRS.map((d) => join(root, d)),\n    ...docsRepoFiles().map(([rel]) => join(root, rel)),\n  ];\n}\n"]}

package/dist/core/doctor/agents.js

@@ -0,0 +1,222 @@
+/**
+ * The agent surface: which tool files this repo should hold, which it does, and
+ * whether they still describe this binary.
+ *
+ * The registry filter lives here rather than in the config loader because a
+ * config written by a newer binary may name a tool this one has never heard of,
+ * and refusing to load it would break every command rather than just this
+ * check. A tool loam cannot plan files for is a tool it has nothing to say
+ * about — so the preflight stays read-only instead of crashing on a config from
+ * the future.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import {} from "../envelope/config.js";
+import { LOAM_VERSION } from "../envelope/version.js";
+import { agentsPath } from "../repo/paths.js";
+import { DELIVERIES, plannedCommandFiles, } from "../agent/scaffold.js";
+import { AGENT_TOOLS } from "../agent/tools/registry.js";
+import { agentsStaleFinding, binaryBehindFinding, agentsStampLine, agentsStampVersion, versionTrails, } from "../agent/agents-stamp.js";
+import {} from "./report.js";
+export function recordedTools(config) {
+    const ids = (config?.agentTools ?? []).filter((t) => t in AGENT_TOOLS);
+    return ids.length === 0 ? null : ids;
+}
+/**
+ * Which tools this repo has agent files for, asked of the layout itself: a tool
+ * counts when any file it would be given is already there.
+ *
+ * The fallback for a loam.json written before `agentTools` existed, and the
+ * only answer a hand-written one can have — so its absence must never be the
+ * thing that reports a problem. This asks a narrower question than `init`'s
+ * own scan, and on purpose: init scans for a tool's dot-directory to decide
+ * what a repo would LIKE, while doctor grades what loam has already put there.
+ * A repo that runs Claude Code and took `--no-commands --no-skills` has chosen
+ * to have no loam files, and is not behind the binary for it.
+ */
+export function detectedTools(repoRoot) {
+    return Object.keys(AGENT_TOOLS).filter((id) => plannedCommandFiles(repoRoot, [id]).some((f) => existsSync(f.path)));
+}
+/**
+ * Which deliveries this repo actually HOLDS for one tool — a delivery counts
+ * when at least one of its files is on disk.
+ *
+ * `loam init --no-skills` (or `--no-commands`) records the tool in `agentTools`
+ * and writes one delivery, so planning both and subtracting what exists reported
+ * every skill file as missing on a brand-new repo — under a message saying it
+ * "was initialized by an older loam" and a `fix` that re-runs init without the
+ * flag that was the whole point. Which deliveries a repo asked for is written
+ * down nowhere, and must not be: the files ARE the record (there is no state
+ * file loam can disagree with). So the question is asked of them.
+ *
+ * A tool with NO files at all is the other story — recorded, then deleted — and
+ * the caller falls back to the full plan there, which is what the finding's
+ * "or they were deleted" already says.
+ */
+export function heldDeliveries(repoRoot, tool, profile = "full") {
+    const held = DELIVERIES.filter((d) => plannedCommandFiles(repoRoot, [tool], [d], profile).some((f) => existsSync(f.path)));
+    return held.length > 0 ? held : DELIVERIES;
+}
+/**
+ * Of the planned files that ARE here, the ones whose stamp is missing or older
+ * than this binary.
+ *
+ * The STALENESS check reads only the stamp, never the body. Safe refresh is a
+ * separate decision made by `init`: the current bytes must match the digest
+ * recorded when loam wrote them. That proof lets an unchanged pointer refresh
+ * without turning a differing body into an offer to overwrite it. A stamp is a
+ * different claim — it says which loam wrote these instructions — and it can
+ * be false while every edit around it is legitimate. Same doctrine as
+ * AGENTS.md (agents-stamp.ts); a customized file is repaired only when a human
+ * reviews it and bumps the stamp or deletes it for `loam init` to recreate.
+ *
+ * Absence of a stamp counts, because that is what every file written before
+ * stamping existed looks like — precisely the "initialized by an older loam"
+ * population this check is for.
+ */
+export async function staleAgentFiles(repoRoot, planned) {
+    // Read them together rather than one after another. `planned` is bounded by
+    // the tool registry — every delivery of every tool loam knows, a couple of
+    // hundred small files — so there is nothing here worth a concurrency cap, and
+    // `Promise.all` preserves input order, which is the only property the caller
+    // asks of the list it gets back.
+    const graded = await Promise.all(planned.map(async (file) => {
+        let text;
+        try {
+            text = await readFile(file.path, "utf8");
+        }
+        catch {
+            // Unreadable is not stale: it is either the missing-file finding above or
+            // a permissions problem, and neither is answered by editing a stamp.
+            return null;
+        }
+        const stamp = agentsStampVersion(text);
+        if (stamp === null || versionTrails(stamp, LOAM_VERSION)) {
+            return relative(repoRoot, file.path).split(/[\\/]/).join("/");
+        }
+        return null;
+    }));
+    return graded.filter((p) => p !== null);
+}
+/**
+ * What the running binary would write for this repo's tools that is not here,
+ * and what is here under an older loam's name.
+ *
+ * Presence is `existsSync`, the same probe `init` uses to compute its `skipped`
+ * list, so doctor cannot disagree with init about which files init would write.
+ */
+export async function inspectAgentSurface(repoRoot, config, docsDir, findings) {
+    const recorded = recordedTools(config);
+    const tools = recorded ?? detectedTools(repoRoot);
+    const profile = config?.agentProfile ?? "full";
+    const planned = tools.flatMap((id) => plannedCommandFiles(repoRoot, [id], heldDeliveries(repoRoot, id, profile), profile));
+    const present = planned.filter((f) => existsSync(f.path));
+    const missingFiles = planned
+        .filter((f) => !existsSync(f.path))
+        .map((f) => relative(repoRoot, f.path).split(/[\\/]/).join("/"));
+    const staleFiles = await staleAgentFiles(repoRoot, present);
+    if (missingFiles.length > 0) {
+        // A warning, never a blocker: an out-of-date command set is a repo whose
+        // agents have fewer entry points than they could, not one where anything
+        // refuses to run. doctor's blockers are for the second kind.
+        //
+        // The fix spells `--docs` and `--tools` and deliberately NOT `--service`:
+        // `init` spreads the committed config forward, and a `--docs`-less re-run
+        // keeps the pointer the repo already commits, so the binding survives
+        // untouched. Every interpolation here stands for exactly one argument —
+        // test/agent-commands-runnable.test.ts parses this string, and a `${flags}`
+        // holding three of them is a command it cannot check.
+        findings.push({
+            severity: "warning",
+            code: "doctor.agent-files-missing",
+            message: `${missingFiles.length} of the ${planned.length} command and skill files loam v${LOAM_VERSION} `
+                + `lays down for ${tools.join(", ")} are not in this repo — it was initialized by an older loam, `
+                + `or they were deleted: ${missingFiles.join(", ")}`,
+            fix: `Re-run \`loam init --docs ${config?.docsDirAsWritten ?? "<dir>"} --tools ${tools.join(",")}\` `
+                + "here — it creates files that are absent and keeps this repo's service binding. Files unchanged "
+                + "since loam wrote them refresh safely; customized files stay untouched.",
+        });
+    }
+    if (staleFiles.length > 0) {
+        // Also a warning, and for a stronger reason than the one above: these files
+        // are the team's now. Only a person can say whether their edits still mean
+        // what the current binary's tables say, so loam reports and stops.
+        findings.push({
+            severity: "warning",
+            code: "doctor.agent-files-stale",
+            message: `${staleFiles.length} of the ${planned.length} command and skill files here carry no `
+                + `\`${agentsStampLine(LOAM_VERSION)}\` stamp, or one older than this loam — the protocol and `
+                + `code tables they instruct an agent with may describe a loam that no longer exists: `
+                + `${staleFiles.join(", ")}`,
+            fix: "Read each against the body this loam writes, then set its stamp line to "
+                + `\`${agentsStampLine(LOAM_VERSION)}\`; or re-run \`loam init\`. A file whose recorded digest `
+                + "still matches is refreshed; a customized file is preserved and remains yours to review.",
+        });
+    }
+    // AGENTS.md lives in the DOCS repo, not here: it travels with the thing it
+    // describes. The comparison is `agentsStaleFinding`'s, not a second copy of
+    // it — doctor only adds the `fix` column its own findings owe the reader.
+    const agentsFile = docsDir === null ? null : agentsPath(docsDir);
+    let agentsText = null;
+    if (agentsFile !== null) {
+        try {
+            agentsText = await readFile(agentsFile, "utf8");
+        }
+        catch {
+            // Unreadable reads as absent, exactly as `validate --all` treats it: no
+            // file, no contract to have drifted. An unreadable docs repo is already
+            // its own finding.
+        }
+    }
+    const stale = agentsStaleFinding(agentsText, LOAM_VERSION);
+    if (stale !== null) {
+        findings.push({
+            severity: "warning",
+            code: stale.code,
+            message: stale.message,
+            fix: `Review ${agentsFile} against the current \`loam --help\`, then set its stamp line to `
+                + `\`${agentsStampLine(LOAM_VERSION)}\`. loam never rewrites that file — bumping the stamp IS `
+                + "the record that somebody looked.",
+        });
+    }
+    // The mirror, and a different fix: nothing is wrong with the documents, the
+    // reader is behind them — so this one never points at AGENTS.md.
+    const behind = binaryBehindFinding(agentsText, LOAM_VERSION);
+    if (behind !== null) {
+        findings.push({
+            severity: "warning",
+            code: behind.code,
+            message: behind.message,
+            fix: "Upgrade loam (`npm i -g @ybotok/loam`), then re-run. Do not edit AGENTS.md: its stamp is correct and this binary is the older half.",
+        });
+    }
+    return {
+        tools,
+        profile,
+        toolsSource: recorded === null ? "disk" : "config",
+        plannedFiles: planned.length,
+        missingFiles,
+        staleFiles,
+        stamp: {
+            path: agentsFile,
+            present: agentsText !== null,
+            version: agentsText === null ? null : agentsStampVersion(agentsText),
+            stale: stale !== null,
+        },
+    };
+}
+/**
+ * Grade what a write that did not finish left in the docs repo.
+ *
+ * Three of the four are blockers, which is unusual for doctor and deliberate:
+ * they are not "you have fewer entry points than you could", they are "the
+ * living docs may be half-written and the next reader cannot tell". Before this
+ * existed, a SIGKILL between two of archive's renames left `doctor: healthy:
+ * true` over merged spec.md + openapi.yaml and an unmerged landscape, and the
+ * next `loam archive` reported loam's own half-merge as the author's bug.
+ *
+ * The temp files are the exception: a `.loam-*.tmp` was never linked into place,
+ * so nothing reads it and nothing depends on it. It is litter, not damage.
+ */
+//# sourceMappingURL=agents.js.map

package/dist/core/doctor/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../../src/core/doctor/agents.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The agent surface: which tool files this repo should hold, which it does, and\n * whether they still describe this binary.\n *\n * The registry filter lives here rather than in the config loader because a\n * config written by a newer binary may name a tool this one has never heard of,\n * and refusing to load it would break every command rather than just this\n * check. A tool loam cannot plan files for is a tool it has nothing to say\n * about — so the preflight stays read-only instead of crashing on a config from\n * the future.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { type LoamConfig } from \"../envelope/config.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\nimport { agentsPath } from \"../repo/paths.js\";\nimport {\n  DELIVERIES,\n  plannedCommandFiles,\n  type AgentProfile,\n  type Delivery,\n} from \"../agent/scaffold.js\";\nimport { AGENT_TOOLS } from \"../agent/tools/registry.js\";\nimport {\n  agentsStaleFinding,\n  binaryBehindFinding,\n  agentsStampLine,\n  agentsStampVersion,\n  versionTrails,\n} from \"../agent/agents-stamp.js\";\nimport { type AgentSurface, type DoctorFinding } from \"./report.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\nexport function recordedTools(config: LoamConfig | null): string[] | null {\n  const ids = (config?.agentTools ?? []).filter((t) => t in AGENT_TOOLS);\n  return ids.length === 0 ? null : ids;\n}\n\n/**\n * Which tools this repo has agent files for, asked of the layout itself: a tool\n * counts when any file it would be given is already there.\n *\n * The fallback for a loam.json written before `agentTools` existed, and the\n * only answer a hand-written one can have — so its absence must never be the\n * thing that reports a problem. This asks a narrower question than `init`'s\n * own scan, and on purpose: init scans for a tool's dot-directory to decide\n * what a repo would LIKE, while doctor grades what loam has already put there.\n * A repo that runs Claude Code and took `--no-commands --no-skills` has chosen\n * to have no loam files, and is not behind the binary for it.\n */\nexport function detectedTools(repoRoot: string): string[] {\n  return Object.keys(AGENT_TOOLS).filter((id) =>\n    plannedCommandFiles(repoRoot, [id]).some((f) => existsSync(f.path)));\n}\n\n/**\n * Which deliveries this repo actually HOLDS for one tool — a delivery counts\n * when at least one of its files is on disk.\n *\n * `loam init --no-skills` (or `--no-commands`) records the tool in `agentTools`\n * and writes one delivery, so planning both and subtracting what exists reported\n * every skill file as missing on a brand-new repo — under a message saying it\n * \"was initialized by an older loam\" and a `fix` that re-runs init without the\n * flag that was the whole point. Which deliveries a repo asked for is written\n * down nowhere, and must not be: the files ARE the record (there is no state\n * file loam can disagree with). So the question is asked of them.\n *\n * A tool with NO files at all is the other story — recorded, then deleted — and\n * the caller falls back to the full plan there, which is what the finding's\n * \"or they were deleted\" already says.\n */\nexport function heldDeliveries(\n  repoRoot: string,\n  tool: string,\n  profile: AgentProfile = \"full\",\n): readonly Delivery[] {\n  const held = DELIVERIES.filter((d) =>\n    plannedCommandFiles(repoRoot, [tool], [d], profile).some((f) => existsSync(f.path)));\n  return held.length > 0 ? held : DELIVERIES;\n}\n\n/**\n * Of the planned files that ARE here, the ones whose stamp is missing or older\n * than this binary.\n *\n * The STALENESS check reads only the stamp, never the body. Safe refresh is a\n * separate decision made by `init`: the current bytes must match the digest\n * recorded when loam wrote them. That proof lets an unchanged pointer refresh\n * without turning a differing body into an offer to overwrite it. A stamp is a\n * different claim — it says which loam wrote these instructions — and it can\n * be false while every edit around it is legitimate. Same doctrine as\n * AGENTS.md (agents-stamp.ts); a customized file is repaired only when a human\n * reviews it and bumps the stamp or deletes it for `loam init` to recreate.\n *\n * Absence of a stamp counts, because that is what every file written before\n * stamping existed looks like — precisely the \"initialized by an older loam\"\n * population this check is for.\n */\nexport async function staleAgentFiles(\n  repoRoot: string,\n  planned: Array<{ path: string }>,\n): Promise<string[]> {\n  // Read them together rather than one after another. `planned` is bounded by\n  // the tool registry — every delivery of every tool loam knows, a couple of\n  // hundred small files — so there is nothing here worth a concurrency cap, and\n  // `Promise.all` preserves input order, which is the only property the caller\n  // asks of the list it gets back.\n  const graded = await Promise.all(planned.map(async (file): Promise<string | null> => {\n    let text: string;\n    try {\n      text = await readFile(file.path, \"utf8\");\n    } catch {\n      // Unreadable is not stale: it is either the missing-file finding above or\n      // a permissions problem, and neither is answered by editing a stamp.\n      return null;\n    }\n    const stamp = agentsStampVersion(text);\n    if (stamp === null || versionTrails(stamp, LOAM_VERSION)) {\n      return relative(repoRoot, file.path).split(/[\\\\/]/).join(\"/\");\n    }\n    return null;\n  }));\n  return graded.filter((p) => p !== null);\n}\n\n/**\n * What the running binary would write for this repo's tools that is not here,\n * and what is here under an older loam's name.\n *\n * Presence is `existsSync`, the same probe `init` uses to compute its `skipped`\n * list, so doctor cannot disagree with init about which files init would write.\n */\nexport async function inspectAgentSurface(\n  repoRoot: string,\n  config: LoamConfig | null,\n  docsDir: DocsDir | null,\n  findings: DoctorFinding[],\n): Promise<AgentSurface> {\n  const recorded = recordedTools(config);\n  const tools = recorded ?? detectedTools(repoRoot);\n  const profile = config?.agentProfile ?? \"full\";\n  const planned = tools.flatMap((id) =>\n    plannedCommandFiles(repoRoot, [id], heldDeliveries(repoRoot, id, profile), profile));\n  const present = planned.filter((f) => existsSync(f.path));\n  const missingFiles = planned\n    .filter((f) => !existsSync(f.path))\n    .map((f) => relative(repoRoot, f.path).split(/[\\\\/]/).join(\"/\"));\n  const staleFiles = await staleAgentFiles(repoRoot, present);\n\n  if (missingFiles.length > 0) {\n    // A warning, never a blocker: an out-of-date command set is a repo whose\n    // agents have fewer entry points than they could, not one where anything\n    // refuses to run. doctor's blockers are for the second kind.\n    //\n    // The fix spells `--docs` and `--tools` and deliberately NOT `--service`:\n    // `init` spreads the committed config forward, and a `--docs`-less re-run\n    // keeps the pointer the repo already commits, so the binding survives\n    // untouched. Every interpolation here stands for exactly one argument —\n    // test/agent-commands-runnable.test.ts parses this string, and a `${flags}`\n    // holding three of them is a command it cannot check.\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.agent-files-missing\",\n      message:\n        `${missingFiles.length} of the ${planned.length} command and skill files loam v${LOAM_VERSION} `\n        + `lays down for ${tools.join(\", \")} are not in this repo — it was initialized by an older loam, `\n        + `or they were deleted: ${missingFiles.join(\", \")}`,\n      fix:\n        `Re-run \\`loam init --docs ${config?.docsDirAsWritten ?? \"<dir>\"} --tools ${tools.join(\",\")}\\` `\n        + \"here — it creates files that are absent and keeps this repo's service binding. Files unchanged \"\n        + \"since loam wrote them refresh safely; customized files stay untouched.\",\n    });\n  }\n\n  if (staleFiles.length > 0) {\n    // Also a warning, and for a stronger reason than the one above: these files\n    // are the team's now. Only a person can say whether their edits still mean\n    // what the current binary's tables say, so loam reports and stops.\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.agent-files-stale\",\n      message:\n        `${staleFiles.length} of the ${planned.length} command and skill files here carry no `\n        + `\\`${agentsStampLine(LOAM_VERSION)}\\` stamp, or one older than this loam — the protocol and `\n        + `code tables they instruct an agent with may describe a loam that no longer exists: `\n        + `${staleFiles.join(\", \")}`,\n      fix:\n        \"Read each against the body this loam writes, then set its stamp line to \"\n        + `\\`${agentsStampLine(LOAM_VERSION)}\\`; or re-run \\`loam init\\`. A file whose recorded digest `\n        + \"still matches is refreshed; a customized file is preserved and remains yours to review.\",\n    });\n  }\n\n  // AGENTS.md lives in the DOCS repo, not here: it travels with the thing it\n  // describes. The comparison is `agentsStaleFinding`'s, not a second copy of\n  // it — doctor only adds the `fix` column its own findings owe the reader.\n  const agentsFile = docsDir === null ? null : agentsPath(docsDir);\n  let agentsText: string | null = null;\n  if (agentsFile !== null) {\n    try {\n      agentsText = await readFile(agentsFile, \"utf8\");\n    } catch {\n      // Unreadable reads as absent, exactly as `validate --all` treats it: no\n      // file, no contract to have drifted. An unreadable docs repo is already\n      // its own finding.\n    }\n  }\n  const stale = agentsStaleFinding(agentsText, LOAM_VERSION);\n  if (stale !== null) {\n    findings.push({\n      severity: \"warning\",\n      code: stale.code,\n      message: stale.message,\n      fix:\n        `Review ${agentsFile} against the current \\`loam --help\\`, then set its stamp line to `\n        + `\\`${agentsStampLine(LOAM_VERSION)}\\`. loam never rewrites that file — bumping the stamp IS `\n        + \"the record that somebody looked.\",\n    });\n  }\n  // The mirror, and a different fix: nothing is wrong with the documents, the\n  // reader is behind them — so this one never points at AGENTS.md.\n  const behind = binaryBehindFinding(agentsText, LOAM_VERSION);\n  if (behind !== null) {\n    findings.push({\n      severity: \"warning\",\n      code: behind.code,\n      message: behind.message,\n      fix: \"Upgrade loam (`npm i -g @ybotok/loam`), then re-run. Do not edit AGENTS.md: its stamp is correct and this binary is the older half.\",\n    });\n  }\n\n  return {\n    tools,\n    profile,\n    toolsSource: recorded === null ? \"disk\" : \"config\",\n    plannedFiles: planned.length,\n    missingFiles,\n    staleFiles,\n    stamp: {\n      path: agentsFile,\n      present: agentsText !== null,\n      version: agentsText === null ? null : agentsStampVersion(agentsText),\n      stale: stale !== null,\n    },\n  };\n}\n\n/**\n * Grade what a write that did not finish left in the docs repo.\n *\n * Three of the four are blockers, which is unusual for doctor and deliberate:\n * they are not \"you have fewer entry points than you could\", they are \"the\n * living docs may be half-written and the next reader cannot tell\". Before this\n * existed, a SIGKILL between two of archive's renames left `doctor: healthy:\n * true` over merged spec.md + openapi.yaml and an unmerged landscape, and the\n * next `loam archive` reported loam's own half-merge as the author's bug.\n *\n * The temp files are the exception: a `.loam-*.tmp` was never linked into place,\n * so nothing reads it and nothing depends on it. It is litter, not damage.\n */\n"]}

package/dist/core/doctor/config.js

@@ -0,0 +1,135 @@
+/**
+ * The config and the fleet map, read the way every other command reads them.
+ *
+ * `doctor` used to carry its own config validator. It agreed with `loadConfig`
+ * on the fields both happened to check and disagreed everywhere else — it
+ * accepted a `gherkinDir` of `"../shared"` that `loadConfig` refused outright,
+ * so `doctor` reported a healthy repo in which no command could run. Two
+ * validators are two opinions about one file, and the one the user reads is
+ * never the one the commands obey.
+ *
+ * The landscape is READ, not stat'ed, for the same reason: `doctor` once
+ * reported `landscape: yes` for a file full of conflict markers, which answers
+ * "is there a file" — not the question anyone runs doctor to ask.
+ */
+import { access, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { configPath, parseConfig } from "../envelope/config.js";
+import { loadFile } from "../c4/likec4.js";
+import { conflictMarkerLines } from "../conflict-markers.js";
+import {} from "./report.js";
+/**
+ * Read and validate the config the way every other command does — through
+ * `parseConfig`, never through a second implementation.
+ *
+ * doctor used to carry its own validator. It agreed with `loadConfig` on the
+ * fields both happened to check and disagreed everywhere else: doctor accepted
+ * a `gherkinDir` of `"../shared"` that `loadConfig` refused outright, so
+ * `doctor` reported a healthy repo in which no command could run. Two
+ * validators are two opinions about the same file, and the one the user reads
+ * is never the one the commands obey.
+ */
+export async function inspectConfig(cwd) {
+    const path = configPath(cwd);
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return { status: "missing", config: null, error: null };
+        return {
+            status: "invalid",
+            config: null,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        return { status: "valid", error: null, config: parseConfig(raw, dirname(path)) };
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            config: null,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function canAccess(path, mode) {
+    try {
+        await access(path, mode);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the landscape, don't just stat it. `doctor` reported `landscape: yes`
+ * for a file full of conflict markers — the check answered "is there a file",
+ * which is not the question anyone runs doctor to ask.
+ */
+export async function inspectLandscape(path, findings) {
+    let source;
+    try {
+        source = await readFile(path, "utf8");
+    }
+    catch (error) {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.landscape-unreadable",
+            message: `${path} exists but could not be read: ${error instanceof Error ? error.message : String(error)}`,
+            fix: `Check permissions on ${path}.`,
+        });
+        return;
+    }
+    // The three-way merge left its markers in the file. Checked BEFORE the
+    // parser, because a conflicted landscape does parse sometimes — both sides of
+    // a conflict can be syntactically valid LikeC4 — and "your map contains two
+    // halves of two different maps" is a more useful sentence than any parser
+    // error. This is the failure mode of onboarding a fleet: ten people adopt ten
+    // services into one landscape.likec4 in the same week.
+    //
+    // The scan itself is conflict-markers's, which is where the same rule already
+    // grades every other document loam reads. doctor kept a second copy of it,
+    // and a second copy of a rule is a second chance to spell it differently;
+    // what doctor owns is what a conflicted landscape COSTS, which is the finding
+    // below and not the search.
+    const conflicted = conflictMarkerLines(source);
+    if (conflicted.length > 0) {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.landscape-merge-conflict",
+            message: `architecture/landscape.likec4 still contains merge conflict markers ` +
+                `(line${conflicted.length === 1 ? "" : "s"} ${conflicted.join(", ")}).`,
+            fix: `Resolve the conflict in ${path} — keep BOTH services' elements and edges, then re-run \`loam doctor\`.`,
+        });
+        return;
+    }
+    const doc = await loadFile(path);
+    if (doc.errors.length > 0) {
+        const first = doc.errors[0];
+        findings.push({
+            severity: "blocker",
+            code: "doctor.landscape-invalid",
+            message: `architecture/landscape.likec4 does not parse: ${first.message}` +
+                (first.line === undefined ? "" : ` (line ${first.line})`) +
+                (doc.errors.length > 1 ? ` — and ${doc.errors.length - 1} more` : ""),
+            fix: `Fix ${path}; every fleet-wide check is blind until it parses.`,
+        });
+    }
+}
+/**
+ * The tool ids loam.json records `init` as having written files for, or null
+ * when it records none we can plan for.
+ *
+ * `parseConfig` checks `agentTools`' SHAPE and deliberately not its contents —
+ * a config written by a newer binary may name a tool this one has never heard
+ * of, and refusing to load it would break every command, not just this check.
+ * So the registry filter belongs here: `plannedCommandFiles` throws on an id it
+ * does not know, and a config from the future must not turn the read-only
+ * preflight into a crash. A tool we cannot plan files for is a tool we have
+ * nothing to say about.
+ */
+//# sourceMappingURL=config.js.map

package/dist/core/doctor/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/doctor/config.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The config and the fleet map, read the way every other command reads them.\n *\n * `doctor` used to carry its own config validator. It agreed with `loadConfig`\n * on the fields both happened to check and disagreed everywhere else — it\n * accepted a `gherkinDir` of `\"../shared\"` that `loadConfig` refused outright,\n * so `doctor` reported a healthy repo in which no command could run. Two\n * validators are two opinions about one file, and the one the user reads is\n * never the one the commands obey.\n *\n * The landscape is READ, not stat'ed, for the same reason: `doctor` once\n * reported `landscape: yes` for a file full of conflict markers, which answers\n * \"is there a file\" — not the question anyone runs doctor to ask.\n */\nimport { access, readFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { configPath, parseConfig, type LoamConfig } from \"../envelope/config.js\";\nimport { loadFile } from \"../c4/likec4.js\";\nimport { conflictMarkerLines } from \"../conflict-markers.js\";\nimport { type DoctorFinding, type DoctorReport } from \"./report.js\";\n\nexport interface ConfigInspection {\n  status: DoctorReport[\"config\"][\"status\"];\n  config: LoamConfig | null;\n  error: string | null;\n}\n\n/**\n * Read and validate the config the way every other command does — through\n * `parseConfig`, never through a second implementation.\n *\n * doctor used to carry its own validator. It agreed with `loadConfig` on the\n * fields both happened to check and disagreed everywhere else: doctor accepted\n * a `gherkinDir` of `\"../shared\"` that `loadConfig` refused outright, so\n * `doctor` reported a healthy repo in which no command could run. Two\n * validators are two opinions about the same file, and the one the user reads\n * is never the one the commands obey.\n */\nexport async function inspectConfig(cwd: string): Promise<ConfigInspection> {\n  const path = configPath(cwd);\n  let raw: string;\n  try {\n    raw = await readFile(path, \"utf8\");\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === \"ENOENT\") return { status: \"missing\", config: null, error: null };\n    return {\n      status: \"invalid\",\n      config: null,\n      error: error instanceof Error ? error.message : String(error),\n    };\n  }\n\n  try {\n    return { status: \"valid\", error: null, config: parseConfig(raw, dirname(path)) };\n  } catch (error) {\n    return {\n      status: \"invalid\",\n      config: null,\n      error: error instanceof Error ? error.message : String(error),\n    };\n  }\n}\n\nexport async function canAccess(path: string, mode: number): Promise<boolean> {\n  try {\n    await access(path, mode);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Read the landscape, don't just stat it. `doctor` reported `landscape: yes`\n * for a file full of conflict markers — the check answered \"is there a file\",\n * which is not the question anyone runs doctor to ask.\n */\nexport async function inspectLandscape(path: string, findings: DoctorFinding[]): Promise<void> {\n  let source: string;\n  try {\n    source = await readFile(path, \"utf8\");\n  } catch (error) {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.landscape-unreadable\",\n      message: `${path} exists but could not be read: ${error instanceof Error ? error.message : String(error)}`,\n      fix: `Check permissions on ${path}.`,\n    });\n    return;\n  }\n\n  // The three-way merge left its markers in the file. Checked BEFORE the\n  // parser, because a conflicted landscape does parse sometimes — both sides of\n  // a conflict can be syntactically valid LikeC4 — and \"your map contains two\n  // halves of two different maps\" is a more useful sentence than any parser\n  // error. This is the failure mode of onboarding a fleet: ten people adopt ten\n  // services into one landscape.likec4 in the same week.\n  //\n  // The scan itself is conflict-markers's, which is where the same rule already\n  // grades every other document loam reads. doctor kept a second copy of it,\n  // and a second copy of a rule is a second chance to spell it differently;\n  // what doctor owns is what a conflicted landscape COSTS, which is the finding\n  // below and not the search.\n  const conflicted = conflictMarkerLines(source);\n  if (conflicted.length > 0) {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.landscape-merge-conflict\",\n      message:\n        `architecture/landscape.likec4 still contains merge conflict markers ` +\n        `(line${conflicted.length === 1 ? \"\" : \"s\"} ${conflicted.join(\", \")}).`,\n      fix: `Resolve the conflict in ${path} — keep BOTH services' elements and edges, then re-run \\`loam doctor\\`.`,\n    });\n    return;\n  }\n\n  const doc = await loadFile(path);\n  if (doc.errors.length > 0) {\n    const first = doc.errors[0]!;\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.landscape-invalid\",\n      message:\n        `architecture/landscape.likec4 does not parse: ${first.message}` +\n        (first.line === undefined ? \"\" : ` (line ${first.line})`) +\n        (doc.errors.length > 1 ? ` — and ${doc.errors.length - 1} more` : \"\"),\n      fix: `Fix ${path}; every fleet-wide check is blind until it parses.`,\n    });\n  }\n}\n\n/**\n * The tool ids loam.json records `init` as having written files for, or null\n * when it records none we can plan for.\n *\n * `parseConfig` checks `agentTools`' SHAPE and deliberately not its contents —\n * a config written by a newer binary may name a tool this one has never heard\n * of, and refusing to load it would break every command, not just this check.\n * So the registry filter belongs here: `plannedCommandFiles` throws on an id it\n * does not know, and a config from the future must not turn the read-only\n * preflight into a crash. A tool we cannot plan files for is a tool we have\n * nothing to say about.\n */\n"]}