@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/core/doctor/doctor.js

@@ -12,10 +12,11 @@ import { constants, existsSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { CONFIG_FILENAME, configPath } from "../envelope/config.js";
 import { LOAM_VERSION } from "../envelope/version.js";
-import { landscapePath } from "../repo/paths.js";
+import { landscapePath, LIKEC4_PROJECT_FILENAME } from "../repo/paths.js";
 import { docsRepoState } from "../repo/state.js";
 import { listFeatures, listServices } from "../repo/repo.js";
-import { LIKEC4_PROJECT_CONFIG, LIKEC4_PROJECT_FILENAME } from "../docs.js";
+import { introducingFeatures } from "../projection/introduced.js";
+import { LIKEC4_PROJECT_CONFIG } from "../docs.js";
 import { gherkinRoot } from "../gherkin/stamp.js";
 import { UnsafePathError } from "../kernel/path-safety.js";
 import { scanWritePathResidue } from "../staging/recovery/residue.js";
@@ -23,6 +24,7 @@ import {} from "./report.js";
 import { canAccess, inspectConfig, inspectLandscape } from "./config.js";
 import { inspectAgentSurface } from "./agents.js";
 import { gradeWritePathResidue } from "./residue.js";
+import { scanReports } from "./reports/scan.js";
 export async function diagnose(cwd = process.cwd()) {
     const inspected = await inspectConfig(cwd);
     const path = configPath(cwd);
@@ -124,19 +126,31 @@ export async function diagnose(cwd = process.cwd()) {
     // start` — the command loam's own brief recommends — refused to load at all.
     // `loam init --create` writes the project file that scopes the root project to
     // the landscape; a docs repo created before it exists has to be told, because
-    // nothing else will ever mention it. A warning, not a blocker: no loam check
-    // reads this file, and a repo without it is only unrenderable.
+    // nothing else will ever mention it. The root file is also the gate on the
+    // per-service ones: `loam subsystem sync` writes a create-only
+    // likec4.config.json beside every service model — the LikeC4 project that
+    // makes each model render from the same root, beside the fleet map — and it
+    // writes none of them until this file exists, so a tree missing it renders
+    // nothing from the docs root, not only the map. (Only a feature delta still renders from
+    // its own directory; an archived feature would otherwise keep a dead project
+    // forever.) The fix below says both, because this finding is the one place a
+    // repo that predates either file is ever told. A warning, not a blocker: no
+    // loam check reads this file, and a repo without it is only unrenderable.
     if (docsDir !== null && exists && readable && !existsSync(join(docsDir, LIKEC4_PROJECT_FILENAME))) {
         findings.push({
             severity: "warning",
             code: "doctor.likec4-config-missing",
             message: `${docsDir}/${LIKEC4_PROJECT_FILENAME} is missing, so this tree is not a loadable LikeC4 workspace — `
-                + "every service model and feature delta declares its own `specification` block, and pointing a "
-                + "renderer at the repo root merges them into one model and reports every declaration as a duplicate.",
+                + "a feature delta, and any service model that declares its own `specification` block, has to be "
+                + "excluded from the root project, and pointing a renderer at the repo root with nothing excluded "
+                + "merges them into one model and reports every declaration as a duplicate.",
             fix: `Write ${docsDir}/${LIKEC4_PROJECT_FILENAME} with:\n${LIKEC4_PROJECT_CONFIG.trimEnd()}\n`
-                + "That scopes the root project to architecture/, so `npx likec4 start` in the docs repo renders "
-                + "the fleet map. A service model or feature delta is rendered by pointing the renderer at its own "
-                + "directory (`npx likec4 start services/<id>`) — being readable alone is what those files are for.",
+                + "That makes the docs root one LikeC4 project holding the fleet map and every service model that "
+                + "extends it, so `npx likec4 start` in the docs repo renders both. Then run `loam subsystem sync`: "
+                + "it maintains the `exclude` list above — one `services/<tree>/**` entry per model that stands "
+                + "alone — and writes one create-only likec4.config.json beside each of those, so a standalone model "
+                + "renders from the same root as a project of its own. Only a feature delta still renders from its "
+                + "own directory (`npx likec4 start features/<FEAT>`) — being readable alone is what that file is for.",
         });
     }
     // What a killed writer left behind. Read from `scanWritePathResidue`, whose
@@ -171,8 +185,12 @@ export async function diagnose(cwd = process.cwd()) {
                 throw err;
         }
     }
+    const configuredService = inspected.config?.service ?? null;
     let services = [];
     let activeFeatures = [];
+    // The active features that introduce the bound service, when the living docs
+    // do not hold it — see the `doctor.service-unknown` finding below.
+    let introducedBy = [];
     // Whether the fleet was actually READ, which is a narrower question than
     // whether reading it was attempted — hence set inside the try and not from
     // the guard, so an enumeration that threw leaves this false alongside its own
@@ -184,6 +202,13 @@ export async function diagnose(cwd = process.cwd()) {
                 listServices(docsDir),
                 listFeatures(docsDir),
             ]);
+            // Through the shared resolver, not a filter over the two lists just read,
+            // so `doctor` and `status`/`show`/`context`/`steps` agree on what
+            // "introduced" means. Inside the try because it reads the same two
+            // directories: if they throw here, they threw for the inventory too.
+            if (configuredService !== null && !services.some((service) => service.id === configuredService)) {
+                introducedBy = (await introducingFeatures(docsDir, configuredService)).map((f) => f.id);
+            }
             inventoried = true;
         }
         catch (error) {
@@ -195,12 +220,13 @@ export async function diagnose(cwd = process.cwd()) {
             });
         }
     }
-    const configuredService = inspected.config?.service ?? null;
     const currentService = configuredService === null
         ? { configured: null, status: "unbound" }
         : services.some((service) => service.id === configuredService)
             ? { configured: configuredService, status: "matched" }
-            : { configured: configuredService, status: "unknown" };
+            : introducedBy.length > 0
+                ? { configured: configuredService, status: "unknown", introducedBy }
+                : { configured: configuredService, status: "unknown" };
     // Standing INSIDE the docs repo, an absent service binding is the correct
     // state, not a gap: the docs repo is the fleet, it is not any one service, and
     // the fix this finding prints — `loam init --service <id>` — would bind the
@@ -213,6 +239,7 @@ export async function diagnose(cwd = process.cwd()) {
     // filename, is the test.
     const inDocsRepo = configRoot !== undefined && docsDir !== null
         && resolve(configRoot) === resolve(docsDir);
+    const [lead, ...others] = introducedBy;
     if (currentService.status === "unbound" && !inDocsRepo) {
         findings.push({
             severity: "warning",
@@ -221,6 +248,33 @@ export async function diagnose(cwd = process.cwd()) {
             fix: `Run \`loam init --docs ${inspected.config?.docsDirAsWritten ?? "<dir>"} --service <id>\` here.`,
         });
     }
+    else if (currentService.status === "unknown" && inventoried && lead !== undefined) {
+        // A service a feature in flight INTRODUCES: its only documents are that
+        // feature's `specs/<service>/` until it archives, and `services/` learns
+        // the name at the merge. The finding used to send this repository's first
+        // developer to `loam adopt` — to describe code the feature has not built
+        // yet, and to write a `services/<service>/` that would make the service
+        // living ahead of the merge, so the feature no longer introduced it. The
+        // same code and severity: the binding still names nothing under services/,
+        // so a check that reads the living docs for it has nothing to read, which
+        // is worth knowing before trusting one. Only the advice was wrong.
+        const several = others.length > 0;
+        const alsoBy = several ? ` (so does ${others.join(", ")})` : "";
+        const until = several ? "one of them" : lead;
+        const documents = several
+            ? `the specs/${configuredService}/ of ${introducedBy.join(", ")} are`
+            : `${lead}'s specs/${configuredService}/ are`;
+        const likewise = several ? `, and likewise for ${others.join(", ")},` : "";
+        findings.push({
+            severity: "warning",
+            code: "doctor.service-unknown",
+            message: `Configured service '${configuredService}' is not under services/ yet: ${lead} introduces it${alsoBy}, `
+                + `and it is not in the living docs until ${until} archives.`,
+            fix: `Nothing to adopt — until ${until} archives, ${documents} this service's documents, and that archive `
+                + `is what clears this warning. Run \`loam status ${lead}\`${likewise} to see what this repository owes `
+                + `${several ? "each" : lead}. If this repository is a different service, fix "service" in ${path}.`,
+        });
+    }
     else if (currentService.status === "unknown" && inventoried) {
         // Only when there was an inventory to be absent from. This finding is a
         // claim about a fleet that was read; with no docsDir, an unreadable one, or
@@ -246,6 +300,31 @@ export async function diagnose(cwd = process.cwd()) {
     // to the repo `init` ran in — the directory holding loam.json, which is not
     // the cwd now that config discovery walks upward.
     const agents = await inspectAgentSurface(dirname(path), inspected.config, docsDir, findings);
+    // The problem reports, read beside the config that RESOLVED — `config.root`,
+    // the directory the loam.json was found in — because the `loam-report`
+    // protocol says "at the current repository root", and config discovery walks
+    // upward, so the cwd is not that root.
+    //
+    // Where nothing PARSED, the directory of the file loam FOUND, which is what
+    // `dirname(path)` is: `configPath` returns the discovered loam.json, or the
+    // cwd's own spelling of it when there is none, so this is the found root when
+    // there is one and the cwd when there is not — the same root the agent surface
+    // above is inspected against. Falling back to the raw cwd instead meant that
+    // from a subdirectory of a repo whose loam.json is unparseable, `doctor`
+    // reported `total 0, next 001` while five reports sat beside the config it had
+    // just named in the same envelope, and handed out an ordinal already taken
+    // (verification 2026-09-04, second pass). A report corpus in a repo whose
+    // loam.json is broken is still worth counting — this is precisely the preflight
+    // that runs when the config does not resolve — and the blocker above already
+    // names the real problem.
+    //
+    // No findings come back, and that is the design: this is the one directory
+    // loam reads that loam never writes, its contents are the team's, and an open
+    // report is not a defect in the repository holding it. `doctor` reports it as
+    // state — like `docs`, `counts` and the write path — so the corpus is
+    // countable by the protocol that asks for it (`reports.next` is the ordinal
+    // the next report takes) without ever becoming a complaint.
+    const reports = await scanReports(inspected.config?.root ?? dirname(path));
     return {
         healthy: !findings.some((finding) => finding.severity === "blocker"),
         runtime: {
@@ -267,6 +346,7 @@ export async function diagnose(cwd = process.cwd()) {
         counts: { services: services.length, activeFeatures: activeFeatures.length },
         currentService,
         agents,
+        reports,
         writePath,
         serviceWritePath,
         findings,

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/core/doctor/doctor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The preflight: can loam run here at all, and can its answers be trusted?\n *\n * The walk only. Each question it asks lives in its own module — `./config.ts`\n * for the config and the fleet map, `./agents.ts` for the agent surface,\n * `./residue.ts` for what a killed writer left — and every one of them returns\n * findings rather than printing. That is the whole contract this module keeps:\n * `doctor` is the command that must be able to describe a broken repository\n * without becoming the next thing that breaks in it.\n */\nimport { constants, existsSync } from \"node:fs\";\nimport { dirname, isAbsolute, join, resolve } from \"node:path\";\nimport { CONFIG_FILENAME, configPath } from \"../envelope/config.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\nimport { landscapePath } from \"../repo/paths.js\";\nimport { docsRepoState } from \"../repo/state.js\";\nimport { listFeatures, listServices } from \"../repo/repo.js\";\nimport { LIKEC4_PROJECT_CONFIG, LIKEC4_PROJECT_FILENAME } from \"../docs.js\";\nimport { gherkinRoot } from \"../gherkin/stamp.js\";\nimport { UnsafePathError } from \"../kernel/path-safety.js\";\nimport { scanWritePathResidue } from \"../staging/recovery/residue.js\";\nimport { type DoctorFinding, type DoctorReport } from \"./report.js\";\nimport { canAccess, inspectConfig, inspectLandscape } from \"./config.js\";\nimport { inspectAgentSurface } from \"./agents.js\";\nimport { gradeWritePathResidue } from \"./residue.js\";\n\nexport async function diagnose(cwd = process.cwd()): Promise<DoctorReport> {\n  const inspected = await inspectConfig(cwd);\n  const path = configPath(cwd);\n  const findings: DoctorFinding[] = [];\n  if (inspected.status === \"missing\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.config-missing\",\n      message: `No ${CONFIG_FILENAME} found at or above ${cwd}.`,\n      fix: \"Run `loam init --docs <path-to-docs-repo>` here (add `--create` to make a new docs repo).\",\n    });\n  } else if (inspected.status === \"invalid\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.config-invalid\",\n      message: `Invalid ${CONFIG_FILENAME}: ${inspected.error ?? \"unknown error\"}`,\n      fix: `Repair ${path} — or delete it and re-run \\`loam init\\`.`,\n    });\n  }\n\n  const docsDir = inspected.config?.docsDir ?? null;\n  const state = docsDir === null ? null : docsRepoState(docsDir);\n  const exists = state !== null && state.kind !== \"missing\";\n  const readable = exists && docsDir !== null ? await canAccess(docsDir, constants.R_OK) : false;\n  const writable = exists && docsDir !== null ? await canAccess(docsDir, constants.W_OK) : false;\n  const servicesDir = state?.kind === \"ok\";\n  const landscapeFile = docsDir === null ? null : landscapePath(docsDir);\n  const landscape = landscapeFile === null ? false : await canAccess(landscapeFile, constants.F_OK);\n\n  // The docs-repo verdict comes from `docsRepoState`, the same function\n  // `listServices` refuses on, so doctor cannot call a repo healthy that the\n  // enumeration will not read.\n  if (state?.kind === \"missing\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.docs-missing\",\n      message: `Configured docsDir is missing or is not a directory: ${docsDir}`,\n      fix: `Fix \"docsDir\" in ${path}, clone the docs repo to ${docsDir}, or run \\`loam init --docs <dir> --create\\`.`,\n    });\n  } else if (state?.kind === \"no-services\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.services-missing\",\n      message: `Required services/ directory is missing under ${docsDir} — that path is not a docs repo.`,\n      fix: `Point \"docsDir\" in ${path} at the shared docs repo, or run \\`loam init --docs ${docsDir} --create\\`.`,\n    });\n  }\n\n  // An absolute docsDir in a committed config names a directory that exists on\n  // exactly one machine. It is a warning and not a blocker because it works\n  // perfectly — for the person who ran `loam init`, and for nobody who clones\n  // the repo afterwards.\n  const asWritten = inspected.config?.docsDirAsWritten;\n  const configRoot = inspected.config?.root;\n  if (\n    asWritten !== undefined\n    && configRoot !== undefined\n    && isAbsolute(asWritten)\n    && resolve(asWritten) !== resolve(configRoot)\n  ) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.docs-absolute\",\n      message:\n        `\"docsDir\" is stored as an absolute path (${asWritten}); ` +\n        `${CONFIG_FILENAME} is committed, so it will not resolve on anyone else's machine.`,\n      fix: `Rewrite \"docsDir\" in ${path} as a path relative to that file (e.g. \"../docs\").`,\n    });\n  }\n\n  if (exists && !readable) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.docs-unreadable\",\n      message: `docsDir is not readable by this process: ${docsDir}`,\n      fix: `Grant read access to ${docsDir} (check ownership and mode).`,\n    });\n  }\n  if (exists && !writable) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.docs-readonly\",\n      message: `docsDir is not writable; read-only commands work, archive/init do not: ${docsDir}`,\n      fix: `Grant write access to ${docsDir} if you need \\`loam new\\`, \\`loam adopt\\` or \\`loam archive\\`.`,\n    });\n  }\n  if (exists && !landscape) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.landscape-missing\",\n      message: `${landscapeFile} is missing — nothing cross-service can be checked without it.`,\n      fix: \"Create architecture/landscape.likec4 with one element per service and an edge per call (`loam init --create` writes the empty map).\",\n    });\n  } else if (exists && landscapeFile !== null && readable) {\n    await inspectLandscape(landscapeFile, findings);\n  }\n\n  // The renderer's view of the repo, which is not loam's. loam parses every\n  // `.likec4` file ALONE, so each one declares its own `specification` block and\n  // re-declares whatever elements it names; LikeC4's own workspace loader merges\n  // the whole tree into one model, and those declarations then collide. The\n  // result was two tools disagreeing in the most confusing possible direction:\n  // `loam validate --all` reported zero errors on a tree where `npx likec4\n  // start` — the command loam's own brief recommends — refused to load at all.\n  // `loam init --create` writes the project file that scopes the root project to\n  // the landscape; a docs repo created before it exists has to be told, because\n  // nothing else will ever mention it. A warning, not a blocker: no loam check\n  // reads this file, and a repo without it is only unrenderable.\n  if (docsDir !== null && exists && readable && !existsSync(join(docsDir, LIKEC4_PROJECT_FILENAME))) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.likec4-config-missing\",\n      message:\n        `${docsDir}/${LIKEC4_PROJECT_FILENAME} is missing, so this tree is not a loadable LikeC4 workspace — `\n        + \"every service model and feature delta declares its own `specification` block, and pointing a \"\n        + \"renderer at the repo root merges them into one model and reports every declaration as a duplicate.\",\n      fix:\n        `Write ${docsDir}/${LIKEC4_PROJECT_FILENAME} with:\\n${LIKEC4_PROJECT_CONFIG.trimEnd()}\\n`\n        + \"That scopes the root project to architecture/, so `npx likec4 start` in the docs repo renders \"\n        + \"the fleet map. A service model or feature delta is rendered by pointing the renderer at its own \"\n        + \"directory (`npx likec4 start services/<id>`) — being readable alone is what those files are for.\",\n    });\n  }\n\n  // What a killed writer left behind. Read from `scanWritePathResidue`, whose\n  // spellings of `.loam-lock` / `.loam-commit` / the temp-file pattern are\n  // staging's own — doctor grades, it does not re-spell. This is the surface\n  // that used to report `healthy: true` over half-merged docs.\n  const writePath = docsDir !== null && exists && readable\n    ? await scanWritePathResidue(docsDir)\n    : null;\n  if (docsDir !== null && writePath !== null) gradeWritePathResidue(docsDir, writePath, findings);\n\n  // The one writer whose journal is NOT in the docs repo: `loam gherkin`\n  // commits into the service repo's owned `<gherkinDir>/loam/` root, with the\n  // same lock and journal files. When this repo IS a service repo, that root\n  // gets the same scan and the same grades — the codes are the contract, the\n  // prose says where — because \"doctor reports an interrupted commit until\n  // recovery succeeds\" has to hold for every writer, not only the docs-repo\n  // ones. Scanning it is cheap: the root is loam's own flat directory.\n  let serviceWritePath = null;\n  if (inspected.config?.service !== undefined && inspected.config.root !== undefined) {\n    try {\n      const emissionRoot = gherkinRoot(inspected.config.root, inspected.config.gherkinDir);\n      if (existsSync(emissionRoot)) {\n        serviceWritePath = await scanWritePathResidue(emissionRoot);\n        gradeWritePathResidue(emissionRoot, serviceWritePath, findings);\n      }\n    } catch (err) {\n      // An unsafe gherkinDir is `loam gherkin`'s refusal to make, with its own\n      // sentence; doctor only declines to scan what it cannot trust.\n      if (!(err instanceof UnsafePathError)) throw err;\n    }\n  }\n\n  let services: Awaited<ReturnType<typeof listServices>> = [];\n  let activeFeatures: Awaited<ReturnType<typeof listFeatures>> = [];\n  // Whether the fleet was actually READ, which is a narrower question than\n  // whether reading it was attempted — hence set inside the try and not from\n  // the guard, so an enumeration that threw leaves this false alongside its own\n  // `doctor.inventory-unreadable`.\n  let inventoried = false;\n  if (docsDir !== null && readable && servicesDir) {\n    try {\n      [services, activeFeatures] = await Promise.all([\n        listServices(docsDir),\n        listFeatures(docsDir),\n      ]);\n      inventoried = true;\n    } catch (error) {\n      findings.push({\n        severity: \"warning\",\n        code: \"doctor.inventory-unreadable\",\n        message: `Could not inventory the docs repo: ${error instanceof Error ? error.message : String(error)}`,\n        fix: `Check that ${docsDir}/services and ${docsDir}/features are readable directories.`,\n      });\n    }\n  }\n\n  const configuredService = inspected.config?.service ?? null;\n  const currentService: DoctorReport[\"currentService\"] = configuredService === null\n    ? { configured: null, status: \"unbound\" }\n    : services.some((service) => service.id === configuredService)\n      ? { configured: configuredService, status: \"matched\" }\n      : { configured: configuredService, status: \"unknown\" };\n  // Standing INSIDE the docs repo, an absent service binding is the correct\n  // state, not a gap: the docs repo is the fleet, it is not any one service, and\n  // the fix this finding prints — `loam init --service <id>` — would bind the\n  // shared repo to one of the services it holds, which is not a thing loam has\n  // a meaning for. doctor already knew where it was standing (it prints the\n  // fleet count two lines up) and reported the warning anyway, so the first\n  // preflight anyone ran in a freshly created docs repo came back yellow with\n  // advice that made it worse. The docs repo's own loam.json is the one that\n  // resolves `docsDir` to the directory holding it — that identity, not a\n  // filename, is the test.\n  const inDocsRepo = configRoot !== undefined && docsDir !== null\n    && resolve(configRoot) === resolve(docsDir);\n  if (currentService.status === \"unbound\" && !inDocsRepo) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.service-unbound\",\n      message: \"loam.json has no service binding; service-repo checks need `service`.\",\n      fix: `Run \\`loam init --docs ${inspected.config?.docsDirAsWritten ?? \"<dir>\"} --service <id>\\` here.`,\n    });\n  } else if (currentService.status === \"unknown\" && inventoried) {\n    // Only when there was an inventory to be absent from. This finding is a\n    // claim about a fleet that was read; with no docsDir, an unreadable one, or\n    // an enumeration that threw, `services` is empty for a reason that has\n    // nothing to do with `service`, and doctor pointed the reader at the one\n    // config field that was fine while the blocker it had already filed named\n    // the real one. `currentService.status` still reports `unknown` — the\n    // envelope describes what loam could and could not match, and an unread\n    // fleet matches nothing.\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.service-unknown\",\n      message: `Configured service '${configuredService}' is not present under services/.`,\n      // `--service <id>`, not a positional: `loam adopt` takes no argument, so\n      // the spelling this finding used to print was refused by commander with\n      // \"too many arguments\" — as the FIRST instruction a freshly bound service\n      // repo ever receives. test/agent-commands-runnable.test.ts parses every\n      // `loam …` loam prints against the real program so it cannot recur.\n      fix: `Run \\`loam adopt --service ${configuredService}\\` to onboard it, or fix \"service\" in ${path}.`,\n    });\n  }\n\n  // The slash commands (and everything else `init` lays down for a tool) belong\n  // to the repo `init` ran in — the directory holding loam.json, which is not\n  // the cwd now that config discovery walks upward.\n  const agents = await inspectAgentSurface(dirname(path), inspected.config, docsDir, findings);\n\n  return {\n    healthy: !findings.some((finding) => finding.severity === \"blocker\"),\n    runtime: {\n      package: \"@ybotok/loam\",\n      version: LOAM_VERSION,\n      node: process.version,\n      platform: process.platform,\n      arch: process.arch,\n    },\n    config: { path, status: inspected.status, error: inspected.error },\n    docs: {\n      path: docsDir,\n      exists,\n      readable,\n      writable,\n      servicesDir,\n      landscape,\n    },\n    counts: { services: services.length, activeFeatures: activeFeatures.length },\n    currentService,\n    agents,\n    writePath,\n    serviceWritePath,\n    findings,\n  };\n}\n"]}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/core/doctor/doctor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The preflight: can loam run here at all, and can its answers be trusted?\n *\n * The walk only. Each question it asks lives in its own module — `./config.ts`\n * for the config and the fleet map, `./agents.ts` for the agent surface,\n * `./residue.ts` for what a killed writer left — and every one of them returns\n * findings rather than printing. That is the whole contract this module keeps:\n * `doctor` is the command that must be able to describe a broken repository\n * without becoming the next thing that breaks in it.\n */\nimport { constants, existsSync } from \"node:fs\";\nimport { dirname, isAbsolute, join, resolve } from \"node:path\";\nimport { CONFIG_FILENAME, configPath } from \"../envelope/config.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\nimport { landscapePath, LIKEC4_PROJECT_FILENAME } from \"../repo/paths.js\";\nimport { docsRepoState } from \"../repo/state.js\";\nimport { listFeatures, listServices } from \"../repo/repo.js\";\nimport { introducingFeatures } from \"../projection/introduced.js\";\nimport { LIKEC4_PROJECT_CONFIG } from \"../docs.js\";\nimport { gherkinRoot } from \"../gherkin/stamp.js\";\nimport { UnsafePathError } from \"../kernel/path-safety.js\";\nimport { scanWritePathResidue } from \"../staging/recovery/residue.js\";\nimport { type DoctorFinding, type DoctorReport } from \"./report.js\";\nimport { canAccess, inspectConfig, inspectLandscape } from \"./config.js\";\nimport { inspectAgentSurface } from \"./agents.js\";\nimport { gradeWritePathResidue } from \"./residue.js\";\nimport { scanReports } from \"./reports/scan.js\";\n\nexport async function diagnose(cwd = process.cwd()): Promise<DoctorReport> {\n  const inspected = await inspectConfig(cwd);\n  const path = configPath(cwd);\n  const findings: DoctorFinding[] = [];\n  if (inspected.status === \"missing\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.config-missing\",\n      message: `No ${CONFIG_FILENAME} found at or above ${cwd}.`,\n      fix: \"Run `loam init --docs <path-to-docs-repo>` here (add `--create` to make a new docs repo).\",\n    });\n  } else if (inspected.status === \"invalid\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.config-invalid\",\n      message: `Invalid ${CONFIG_FILENAME}: ${inspected.error ?? \"unknown error\"}`,\n      fix: `Repair ${path} — or delete it and re-run \\`loam init\\`.`,\n    });\n  }\n\n  const docsDir = inspected.config?.docsDir ?? null;\n  const state = docsDir === null ? null : docsRepoState(docsDir);\n  const exists = state !== null && state.kind !== \"missing\";\n  const readable = exists && docsDir !== null ? await canAccess(docsDir, constants.R_OK) : false;\n  const writable = exists && docsDir !== null ? await canAccess(docsDir, constants.W_OK) : false;\n  const servicesDir = state?.kind === \"ok\";\n  const landscapeFile = docsDir === null ? null : landscapePath(docsDir);\n  const landscape = landscapeFile === null ? false : await canAccess(landscapeFile, constants.F_OK);\n\n  // The docs-repo verdict comes from `docsRepoState`, the same function\n  // `listServices` refuses on, so doctor cannot call a repo healthy that the\n  // enumeration will not read.\n  if (state?.kind === \"missing\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.docs-missing\",\n      message: `Configured docsDir is missing or is not a directory: ${docsDir}`,\n      fix: `Fix \"docsDir\" in ${path}, clone the docs repo to ${docsDir}, or run \\`loam init --docs <dir> --create\\`.`,\n    });\n  } else if (state?.kind === \"no-services\") {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.services-missing\",\n      message: `Required services/ directory is missing under ${docsDir} — that path is not a docs repo.`,\n      fix: `Point \"docsDir\" in ${path} at the shared docs repo, or run \\`loam init --docs ${docsDir} --create\\`.`,\n    });\n  }\n\n  // An absolute docsDir in a committed config names a directory that exists on\n  // exactly one machine. It is a warning and not a blocker because it works\n  // perfectly — for the person who ran `loam init`, and for nobody who clones\n  // the repo afterwards.\n  const asWritten = inspected.config?.docsDirAsWritten;\n  const configRoot = inspected.config?.root;\n  if (\n    asWritten !== undefined\n    && configRoot !== undefined\n    && isAbsolute(asWritten)\n    && resolve(asWritten) !== resolve(configRoot)\n  ) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.docs-absolute\",\n      message:\n        `\"docsDir\" is stored as an absolute path (${asWritten}); ` +\n        `${CONFIG_FILENAME} is committed, so it will not resolve on anyone else's machine.`,\n      fix: `Rewrite \"docsDir\" in ${path} as a path relative to that file (e.g. \"../docs\").`,\n    });\n  }\n\n  if (exists && !readable) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.docs-unreadable\",\n      message: `docsDir is not readable by this process: ${docsDir}`,\n      fix: `Grant read access to ${docsDir} (check ownership and mode).`,\n    });\n  }\n  if (exists && !writable) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.docs-readonly\",\n      message: `docsDir is not writable; read-only commands work, archive/init do not: ${docsDir}`,\n      fix: `Grant write access to ${docsDir} if you need \\`loam new\\`, \\`loam adopt\\` or \\`loam archive\\`.`,\n    });\n  }\n  if (exists && !landscape) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.landscape-missing\",\n      message: `${landscapeFile} is missing — nothing cross-service can be checked without it.`,\n      fix: \"Create architecture/landscape.likec4 with one element per service and an edge per call (`loam init --create` writes the empty map).\",\n    });\n  } else if (exists && landscapeFile !== null && readable) {\n    await inspectLandscape(landscapeFile, findings);\n  }\n\n  // The renderer's view of the repo, which is not loam's. loam parses every\n  // `.likec4` file ALONE, so each one declares its own `specification` block and\n  // re-declares whatever elements it names; LikeC4's own workspace loader merges\n  // the whole tree into one model, and those declarations then collide. The\n  // result was two tools disagreeing in the most confusing possible direction:\n  // `loam validate --all` reported zero errors on a tree where `npx likec4\n  // start` — the command loam's own brief recommends — refused to load at all.\n  // `loam init --create` writes the project file that scopes the root project to\n  // the landscape; a docs repo created before it exists has to be told, because\n  // nothing else will ever mention it. The root file is also the gate on the\n  // per-service ones: `loam subsystem sync` writes a create-only\n  // likec4.config.json beside every service model — the LikeC4 project that\n  // makes each model render from the same root, beside the fleet map — and it\n  // writes none of them until this file exists, so a tree missing it renders\n  // nothing from the docs root, not only the map. (Only a feature delta still renders from\n  // its own directory; an archived feature would otherwise keep a dead project\n  // forever.) The fix below says both, because this finding is the one place a\n  // repo that predates either file is ever told. A warning, not a blocker: no\n  // loam check reads this file, and a repo without it is only unrenderable.\n  if (docsDir !== null && exists && readable && !existsSync(join(docsDir, LIKEC4_PROJECT_FILENAME))) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.likec4-config-missing\",\n      message:\n        `${docsDir}/${LIKEC4_PROJECT_FILENAME} is missing, so this tree is not a loadable LikeC4 workspace — `\n        + \"a feature delta, and any service model that declares its own `specification` block, has to be \"\n        + \"excluded from the root project, and pointing a renderer at the repo root with nothing excluded \"\n        + \"merges them into one model and reports every declaration as a duplicate.\",\n      fix:\n        `Write ${docsDir}/${LIKEC4_PROJECT_FILENAME} with:\\n${LIKEC4_PROJECT_CONFIG.trimEnd()}\\n`\n        + \"That makes the docs root one LikeC4 project holding the fleet map and every service model that \"\n        + \"extends it, so `npx likec4 start` in the docs repo renders both. Then run `loam subsystem sync`: \"\n        + \"it maintains the `exclude` list above — one `services/<tree>/**` entry per model that stands \"\n        + \"alone — and writes one create-only likec4.config.json beside each of those, so a standalone model \"\n        + \"renders from the same root as a project of its own. Only a feature delta still renders from its \"\n        + \"own directory (`npx likec4 start features/<FEAT>`) — being readable alone is what that file is for.\",\n    });\n  }\n\n  // What a killed writer left behind. Read from `scanWritePathResidue`, whose\n  // spellings of `.loam-lock` / `.loam-commit` / the temp-file pattern are\n  // staging's own — doctor grades, it does not re-spell. This is the surface\n  // that used to report `healthy: true` over half-merged docs.\n  const writePath = docsDir !== null && exists && readable\n    ? await scanWritePathResidue(docsDir)\n    : null;\n  if (docsDir !== null && writePath !== null) gradeWritePathResidue(docsDir, writePath, findings);\n\n  // The one writer whose journal is NOT in the docs repo: `loam gherkin`\n  // commits into the service repo's owned `<gherkinDir>/loam/` root, with the\n  // same lock and journal files. When this repo IS a service repo, that root\n  // gets the same scan and the same grades — the codes are the contract, the\n  // prose says where — because \"doctor reports an interrupted commit until\n  // recovery succeeds\" has to hold for every writer, not only the docs-repo\n  // ones. Scanning it is cheap: the root is loam's own flat directory.\n  let serviceWritePath = null;\n  if (inspected.config?.service !== undefined && inspected.config.root !== undefined) {\n    try {\n      const emissionRoot = gherkinRoot(inspected.config.root, inspected.config.gherkinDir);\n      if (existsSync(emissionRoot)) {\n        serviceWritePath = await scanWritePathResidue(emissionRoot);\n        gradeWritePathResidue(emissionRoot, serviceWritePath, findings);\n      }\n    } catch (err) {\n      // An unsafe gherkinDir is `loam gherkin`'s refusal to make, with its own\n      // sentence; doctor only declines to scan what it cannot trust.\n      if (!(err instanceof UnsafePathError)) throw err;\n    }\n  }\n\n  const configuredService = inspected.config?.service ?? null;\n  let services: Awaited<ReturnType<typeof listServices>> = [];\n  let activeFeatures: Awaited<ReturnType<typeof listFeatures>> = [];\n  // The active features that introduce the bound service, when the living docs\n  // do not hold it — see the `doctor.service-unknown` finding below.\n  let introducedBy: string[] = [];\n  // Whether the fleet was actually READ, which is a narrower question than\n  // whether reading it was attempted — hence set inside the try and not from\n  // the guard, so an enumeration that threw leaves this false alongside its own\n  // `doctor.inventory-unreadable`.\n  let inventoried = false;\n  if (docsDir !== null && readable && servicesDir) {\n    try {\n      [services, activeFeatures] = await Promise.all([\n        listServices(docsDir),\n        listFeatures(docsDir),\n      ]);\n      // Through the shared resolver, not a filter over the two lists just read,\n      // so `doctor` and `status`/`show`/`context`/`steps` agree on what\n      // \"introduced\" means. Inside the try because it reads the same two\n      // directories: if they throw here, they threw for the inventory too.\n      if (configuredService !== null && !services.some((service) => service.id === configuredService)) {\n        introducedBy = (await introducingFeatures(docsDir, configuredService)).map((f) => f.id);\n      }\n      inventoried = true;\n    } catch (error) {\n      findings.push({\n        severity: \"warning\",\n        code: \"doctor.inventory-unreadable\",\n        message: `Could not inventory the docs repo: ${error instanceof Error ? error.message : String(error)}`,\n        fix: `Check that ${docsDir}/services and ${docsDir}/features are readable directories.`,\n      });\n    }\n  }\n\n  const currentService: DoctorReport[\"currentService\"] = configuredService === null\n    ? { configured: null, status: \"unbound\" }\n    : services.some((service) => service.id === configuredService)\n      ? { configured: configuredService, status: \"matched\" }\n      : introducedBy.length > 0\n        ? { configured: configuredService, status: \"unknown\", introducedBy }\n        : { configured: configuredService, status: \"unknown\" };\n  // Standing INSIDE the docs repo, an absent service binding is the correct\n  // state, not a gap: the docs repo is the fleet, it is not any one service, and\n  // the fix this finding prints — `loam init --service <id>` — would bind the\n  // shared repo to one of the services it holds, which is not a thing loam has\n  // a meaning for. doctor already knew where it was standing (it prints the\n  // fleet count two lines up) and reported the warning anyway, so the first\n  // preflight anyone ran in a freshly created docs repo came back yellow with\n  // advice that made it worse. The docs repo's own loam.json is the one that\n  // resolves `docsDir` to the directory holding it — that identity, not a\n  // filename, is the test.\n  const inDocsRepo = configRoot !== undefined && docsDir !== null\n    && resolve(configRoot) === resolve(docsDir);\n  const [lead, ...others] = introducedBy;\n  if (currentService.status === \"unbound\" && !inDocsRepo) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.service-unbound\",\n      message: \"loam.json has no service binding; service-repo checks need `service`.\",\n      fix: `Run \\`loam init --docs ${inspected.config?.docsDirAsWritten ?? \"<dir>\"} --service <id>\\` here.`,\n    });\n  } else if (currentService.status === \"unknown\" && inventoried && lead !== undefined) {\n    // A service a feature in flight INTRODUCES: its only documents are that\n    // feature's `specs/<service>/` until it archives, and `services/` learns\n    // the name at the merge. The finding used to send this repository's first\n    // developer to `loam adopt` — to describe code the feature has not built\n    // yet, and to write a `services/<service>/` that would make the service\n    // living ahead of the merge, so the feature no longer introduced it. The\n    // same code and severity: the binding still names nothing under services/,\n    // so a check that reads the living docs for it has nothing to read, which\n    // is worth knowing before trusting one. Only the advice was wrong.\n    const several = others.length > 0;\n    const alsoBy = several ? ` (so does ${others.join(\", \")})` : \"\";\n    const until = several ? \"one of them\" : lead;\n    const documents = several\n      ? `the specs/${configuredService}/ of ${introducedBy.join(\", \")} are`\n      : `${lead}'s specs/${configuredService}/ are`;\n    const likewise = several ? `, and likewise for ${others.join(\", \")},` : \"\";\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.service-unknown\",\n      message:\n        `Configured service '${configuredService}' is not under services/ yet: ${lead} introduces it${alsoBy}, `\n        + `and it is not in the living docs until ${until} archives.`,\n      fix:\n        `Nothing to adopt — until ${until} archives, ${documents} this service's documents, and that archive `\n        + `is what clears this warning. Run \\`loam status ${lead}\\`${likewise} to see what this repository owes `\n        + `${several ? \"each\" : lead}. If this repository is a different service, fix \"service\" in ${path}.`,\n    });\n  } else if (currentService.status === \"unknown\" && inventoried) {\n    // Only when there was an inventory to be absent from. This finding is a\n    // claim about a fleet that was read; with no docsDir, an unreadable one, or\n    // an enumeration that threw, `services` is empty for a reason that has\n    // nothing to do with `service`, and doctor pointed the reader at the one\n    // config field that was fine while the blocker it had already filed named\n    // the real one. `currentService.status` still reports `unknown` — the\n    // envelope describes what loam could and could not match, and an unread\n    // fleet matches nothing.\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.service-unknown\",\n      message: `Configured service '${configuredService}' is not present under services/.`,\n      // `--service <id>`, not a positional: `loam adopt` takes no argument, so\n      // the spelling this finding used to print was refused by commander with\n      // \"too many arguments\" — as the FIRST instruction a freshly bound service\n      // repo ever receives. test/agent-commands-runnable.test.ts parses every\n      // `loam …` loam prints against the real program so it cannot recur.\n      fix: `Run \\`loam adopt --service ${configuredService}\\` to onboard it, or fix \"service\" in ${path}.`,\n    });\n  }\n\n  // The slash commands (and everything else `init` lays down for a tool) belong\n  // to the repo `init` ran in — the directory holding loam.json, which is not\n  // the cwd now that config discovery walks upward.\n  const agents = await inspectAgentSurface(dirname(path), inspected.config, docsDir, findings);\n\n  // The problem reports, read beside the config that RESOLVED — `config.root`,\n  // the directory the loam.json was found in — because the `loam-report`\n  // protocol says \"at the current repository root\", and config discovery walks\n  // upward, so the cwd is not that root.\n  //\n  // Where nothing PARSED, the directory of the file loam FOUND, which is what\n  // `dirname(path)` is: `configPath` returns the discovered loam.json, or the\n  // cwd's own spelling of it when there is none, so this is the found root when\n  // there is one and the cwd when there is not — the same root the agent surface\n  // above is inspected against. Falling back to the raw cwd instead meant that\n  // from a subdirectory of a repo whose loam.json is unparseable, `doctor`\n  // reported `total 0, next 001` while five reports sat beside the config it had\n  // just named in the same envelope, and handed out an ordinal already taken\n  // (verification 2026-09-04, second pass). A report corpus in a repo whose\n  // loam.json is broken is still worth counting — this is precisely the preflight\n  // that runs when the config does not resolve — and the blocker above already\n  // names the real problem.\n  //\n  // No findings come back, and that is the design: this is the one directory\n  // loam reads that loam never writes, its contents are the team's, and an open\n  // report is not a defect in the repository holding it. `doctor` reports it as\n  // state — like `docs`, `counts` and the write path — so the corpus is\n  // countable by the protocol that asks for it (`reports.next` is the ordinal\n  // the next report takes) without ever becoming a complaint.\n  const reports = await scanReports(inspected.config?.root ?? dirname(path));\n\n  return {\n    healthy: !findings.some((finding) => finding.severity === \"blocker\"),\n    runtime: {\n      package: \"@ybotok/loam\",\n      version: LOAM_VERSION,\n      node: process.version,\n      platform: process.platform,\n      arch: process.arch,\n    },\n    config: { path, status: inspected.status, error: inspected.error },\n    docs: {\n      path: docsDir,\n      exists,\n      readable,\n      writable,\n      servicesDir,\n      landscape,\n    },\n    counts: { services: services.length, activeFeatures: activeFeatures.length },\n    currentService,\n    agents,\n    reports,\n    writePath,\n    serviceWritePath,\n    findings,\n  };\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/core/doctor/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAyB,MAAM,gCAAgC,CAAC","sourcesContent":["/**\n * What a diagnosis IS: the finding shape, the report shape, and the agent\n * surface inside it.\n *\n * A module of its own because five checks fill this in and the command prints\n * it, so every one of them agrees about what a blocker means here — something\n * that stops loam running at all, as against a warning, which is something a\n * person should know before trusting an answer. That distinction is the whole\n * value of `doctor`, and it lives in the type rather than in five checks'\n * judgement.\n */\nimport { type WritePathResidue } from \"../staging/recovery/residue.js\";\n\nexport type DoctorSeverity = \"blocker\" | \"warning\";\n\nexport interface DoctorFinding {\n  severity: DoctorSeverity;\n  code: string;\n  message: string;\n  /**\n   * The next command or edit that clears this finding. Mandatory, not optional:\n   * a diagnostic that names a problem without naming its fix is a diagnostic\n   * the reader has to research, and `doctor` is what someone runs precisely\n   * because they do not yet know what loam wants from them.\n   */\n  fix: string;\n}\n\nexport interface DoctorReport {\n  healthy: boolean;\n  runtime: {\n    package: \"@ybotok/loam\";\n    version: string;\n    node: string;\n    platform: NodeJS.Platform;\n    arch: string;\n  };\n  config: {\n    path: string;\n    status: \"missing\" | \"invalid\" | \"valid\";\n    error: string | null;\n  };\n  docs: {\n    path: string | null;\n    exists: boolean;\n    readable: boolean;\n    writable: boolean;\n    servicesDir: boolean;\n    landscape: boolean;\n  };\n  counts: { services: number; activeFeatures: number };\n  currentService: {\n    configured: string | null;\n    status: \"unbound\" | \"matched\" | \"unknown\";\n  };\n  /** The agent surface of this repo — see `inspectAgentSurface`. */\n  agents: AgentSurface;\n  /**\n   * What a write that did not finish left in the docs repo, or null when\n   * `docsDir` never resolved. Reported as state, like `docs` and `counts`: a\n   * lock somebody is legitimately holding right now is a fact, not a complaint.\n   */\n  writePath: WritePathResidue | null;\n  /**\n   * The same scan over the service repo's owned `<gherkinDir>/loam/` root —\n   * the one writer whose journal is not in the docs repo. Null when this repo\n   * is not a service repo, or the root does not exist. Additive: a consumer\n   * of the original envelope never sees a key it did not ask about removed.\n   */\n  serviceWritePath: WritePathResidue | null;\n  findings: DoctorFinding[];\n}\n\nexport interface AgentSurface {\n  /** Tool ids this repo has an agent surface for. Empty is legal (`init --no-commands`). */\n  tools: string[];\n  /** Workflow subset managed for those tools. */\n  profile: \"full\" | \"service\" | \"docs\";\n  /** Whether `tools` came from loam.json's own record or from what is on disk. */\n  toolsSource: \"config\" | \"disk\";\n  /** How many files the running binary would lay down for `tools`. */\n  plannedFiles: number;\n  /** Repo-relative paths of those files that are not there. */\n  missingFiles: string[];\n  /**\n   * Repo-relative paths of the ones that ARE there carrying no version stamp,\n   * or one older than this binary — see `staleAgentFiles`.\n   */\n  staleFiles: string[];\n  stamp: {\n    /** Where the docs repo's AGENTS.md is, or null when `docsDir` did not resolve. */\n    path: string | null;\n    /** Whether it could be read at all — absent and unstamped are different facts. */\n    present: boolean;\n    /** The version the stamp names, null when there is none (or an unparseable one). */\n    version: string | null;\n    /** Whether `agents.stale` fired: the stamp is missing or trails this binary. */\n    stale: boolean;\n  };\n}\n"]}
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/core/doctor/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAyB,MAAM,gCAAgC,CAAC","sourcesContent":["/**\n * What a diagnosis IS: the finding shape, the report shape, and the agent\n * surface inside it.\n *\n * A module of its own because five checks fill this in and the command prints\n * it, so every one of them agrees about what a blocker means here — something\n * that stops loam running at all, as against a warning, which is something a\n * person should know before trusting an answer. That distinction is the whole\n * value of `doctor`, and it lives in the type rather than in five checks'\n * judgement.\n */\nimport { type WritePathResidue } from \"../staging/recovery/residue.js\";\n\nexport type DoctorSeverity = \"blocker\" | \"warning\";\n\nexport interface DoctorFinding {\n  severity: DoctorSeverity;\n  code: string;\n  message: string;\n  /**\n   * The next command or edit that clears this finding. Mandatory, not optional:\n   * a diagnostic that names a problem without naming its fix is a diagnostic\n   * the reader has to research, and `doctor` is what someone runs precisely\n   * because they do not yet know what loam wants from them.\n   */\n  fix: string;\n}\n\nexport interface DoctorReport {\n  healthy: boolean;\n  runtime: {\n    package: \"@ybotok/loam\";\n    version: string;\n    node: string;\n    platform: NodeJS.Platform;\n    arch: string;\n  };\n  config: {\n    path: string;\n    status: \"missing\" | \"invalid\" | \"valid\";\n    error: string | null;\n  };\n  docs: {\n    path: string | null;\n    exists: boolean;\n    readable: boolean;\n    writable: boolean;\n    servicesDir: boolean;\n    landscape: boolean;\n  };\n  counts: { services: number; activeFeatures: number };\n  currentService: {\n    configured: string | null;\n    status: \"unbound\" | \"matched\" | \"unknown\";\n    /**\n     * The active features whose `specs/` introduce the configured service\n     * (`introducingFeatures`), ordered by id — present only when `status` is\n     * `unknown` and at least one does. `status` stays `unknown` then, because\n     * it says what loam could match under `services/`, and that is still\n     * nothing; this key says why that is not a gap anybody should adopt into.\n     * Additive: absent everywhere it would be empty, as `show`'s is on a\n     * living service.\n     */\n    introducedBy?: string[];\n  };\n  /** The agent surface of this repo — see `inspectAgentSurface`. */\n  agents: AgentSurface;\n  /**\n   * The problem reports this repo has collected — see `scanReports`. State,\n   * like `docs` and `counts`, and never a finding: a repository with eleven\n   * open reports is not a broken repository, it is one that has been paying\n   * attention. `healthy` does not move for anything in here.\n   */\n  reports: ProblemReports;\n  /**\n   * What a write that did not finish left in the docs repo, or null when\n   * `docsDir` never resolved. Reported as state, like `docs` and `counts`: a\n   * lock somebody is legitimately holding right now is a fact, not a complaint.\n   */\n  writePath: WritePathResidue | null;\n  /**\n   * The same scan over the service repo's owned `<gherkinDir>/loam/` root —\n   * the one writer whose journal is not in the docs repo. Null when this repo\n   * is not a service repo, or the root does not exist. Additive: a consumer\n   * of the original envelope never sees a key it did not ask about removed.\n   */\n  serviceWritePath: WritePathResidue | null;\n  findings: DoctorFinding[];\n}\n\n/**\n * Where one problem report got to, as its own `Status:` line says.\n *\n * `fixed` and `superseded` are the FIRST WORD of a longer line (`fixed in\n * 0.2.0-alpha.5`, `superseded by 010`), because the rest of that line is prose\n * an author writes for a reader and loam has no business parsing. `unstated`\n * covers both a report written before the field existed and one whose value is\n * a word this vocabulary does not know — loam counts what it can read and says\n * so, rather than inventing a sixth bucket for every synonym somebody types.\n */\nexport type ProblemReportStatus = \"open\" | \"sent\" | \"fixed\" | \"superseded\" | \"unstated\";\n\nexport interface ProblemReportEntry {\n  /** The file's own name inside the reports directory — `012-2026-09-03-slug.md`. */\n  file: string;\n  /**\n   * The leading zero-padded ordinal the protocol now asks for, or null for a\n   * name written before it did (`2026-09-03-slug.md`). A report with no ordinal\n   * is still a report: this directory predates the numbering.\n   */\n  ordinal: string | null;\n  status: ProblemReportStatus;\n}\n\n/** The report corpus a repository has collected — see `scanReports`. */\nexport interface ProblemReports {\n  /**\n   * The ABSOLUTE path of the directory — `loam-reports/` beside the `loam.json`\n   * that resolved, else beside the directory `doctor` ran in. Absolute because\n   * the protocol tells an agent to write there, and a repo-relative spelling\n   * left it to guess which repository \"relative\" meant: `doctor` is the\n   * preflight that runs precisely when the config may not resolve, and in a\n   * service repository the config's root is that repository, not the docs one.\n   */\n  dir: string;\n  /** Whether that directory exists at all. A repo with no reports is normal. */\n  present: boolean;\n  total: number;\n  /**\n   * The ordinal the next report takes: one more than the highest present,\n   * padded to at least three digits, `001` over an empty or absent directory —\n   * it WIDENS past three rather than reusing a number once a corpus gets\n   * there, which is what every page saying \"at least three digits\" describes.\n   * This is the field the `loam-report` protocol tells an agent to read.\n   */\n  next: string;\n  entries: ProblemReportEntry[];\n}\n\nexport interface AgentSurface {\n  /** Tool ids this repo has an agent surface for. Empty is legal (`init --no-commands`). */\n  tools: string[];\n  /** Workflow subset managed for those tools. */\n  profile: \"full\" | \"service\" | \"docs\";\n  /** Whether `tools` came from loam.json's own record or from what is on disk. */\n  toolsSource: \"config\" | \"disk\";\n  /** How many files the running binary would lay down for `tools`. */\n  plannedFiles: number;\n  /** Repo-relative paths of those files that are not there. */\n  missingFiles: string[];\n  /**\n   * Repo-relative paths of the ones that ARE there whose body differs from the\n   * one this binary writes AND whose version stamp is missing or older than\n   * this binary — see `staleAgentFiles`. A file differing only in its stamp is\n   * not listed.\n   */\n  staleFiles: string[];\n  stamp: {\n    /** Where the docs repo's AGENTS.md is, or null when `docsDir` did not resolve. */\n    path: string | null;\n    /** Whether it could be read at all — absent and unstamped are different facts. */\n    present: boolean;\n    /** The version the stamp names, null when there is none (or an unparseable one). */\n    version: string | null;\n    /** Whether `agents.stale` fired: the stamp is missing or trails this binary. */\n    stale: boolean;\n  };\n}\n"]}

package/dist/core/doctor/reports/scan.js

@@ -0,0 +1,242 @@
+/**
+ * The problem reports a repository has collected: how many there are, what
+ * state each one is in, and which ordinal the next one takes.
+ *
+ * A sub-package because `doctor/` is at its five-file limit, and a scan of its
+ * own because this is the one directory loam reads that loam never writes. The
+ * `loam-report` protocol has always asked a repository to accumulate a corpus
+ * under `loam-reports/` and then never looked at it — eleven reports landed in
+ * this repository in two days, three of them already closed, and every bit of
+ * that state lived outside the files, in whoever remembered. The directory is
+ * loam's own convention and its contents are loam's own format, so counting
+ * them is a fact loam can read as cheaply as it reads `agentFiles`. Reading is
+ * the whole of it: nothing here transmits anything, which is the constraint the
+ * protocol is built around.
+ *
+ * Everything below is best-effort on purpose. A report is a hand-written
+ * Markdown file, so an absent directory, an unreadable one, a name written
+ * before the numbering existed and a file with no `Status:` line are all
+ * ordinary states of a healthy repository. None of them is a finding, and
+ * `doctor`'s `healthy` does not move for anything in here — a repo with eleven
+ * open reports is not broken, it is one that has been paying attention.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import {} from "../report.js";
+/**
+ * The conventional NAME of the directory the `loam-report` protocol asks a
+ * repository to accumulate, spelled once — the segment `scanReports` joins onto
+ * the resolved root to reach it.
+ *
+ * A name rather than a path, because two readers want different things out of
+ * it and both are right: `ProblemReports.dir` carries the joined ABSOLUTE
+ * location, because the protocol tells an agent to write there and a relative
+ * spelling leaves it guessing which repository "relative" meant (`../report.ts`
+ * records that), while `commands/doctor.ts`'s human row prints this constant, so
+ * a person standing in the repository reads `loam-reports/` — what the protocol,
+ * the reports themselves and every page that mentions them say.
+ */
+export const REPORTS_DIR = "loam-reports";
+/**
+ * The leading ordinal of `012-2026-09-03-slug.md`. Three digits or more, so the
+ * thousandth report widens the field instead of losing its number.
+ */
+const ORDINAL = /^(\d{3,})-/;
+/**
+ * A name written before the numbering existed: `2026-09-03-slug.md`, the shape
+ * eleven reports in this repository already carry.
+ *
+ * Checked FIRST, and this is the whole reason it exists as its own pattern: a
+ * four-digit year satisfies `ORDINAL` perfectly, so a legacy name read as an
+ * ordinal is report number 2026 — and the next report loam hands out is then
+ * 2027, in a directory whose highest real ordinal is 3. A legacy name is still
+ * a report; it just has no number, and contributes none.
+ */
+const LEGACY_DATE_NAME = /^\d{4}-\d{2}-\d{2}-/;
+/** The ordinal a report's file name claims, or null when the name predates numbering. */
+function ordinalOf(file) {
+    if (LEGACY_DATE_NAME.test(file))
+        return null;
+    return ORDINAL.exec(file)?.[1] ?? null;
+}
+/**
+ * The template's `- Status:` line, matched in the header FIELD BLOCK alone (see
+ * `headerFields`). Only the first word is captured: the vocabulary's two
+ * composite values carry prose after it (`fixed in 0.2.0-alpha.5`,
+ * `superseded by 010`) that an author writes for a reader, and parsing further
+ * would make loam an authority on a sentence it does not own.
+ */
+const STATUS_LINE = /^[ \t]*-[ \t]*Status:[ \t]*(\S+)/m;
+/** A fenced block's delimiter line, either spelling. */
+const FENCE = /^[ \t]*(`{3,}|~{3,})/;
+/**
+ * An indented code block's line — the OTHER way markdown quotes code, and the
+ * way `loam instructions loam-report` prints its own template (the four-space
+ * block in ../../agent/support/report.ts). A fence-only reader counted such a
+ * report open off the template's `- Status: open`.
+ */
+const INDENTED = /^(?: {4}|\t)/;
+/** A section heading — the line that ends the header field block. */
+const SECTION = /^##[ \t]/;
+/**
+ * The report's header field block: every line above the first `## ` heading,
+ * with quoted code — fenced or indented — dropped.
+ *
+ * Matched anywhere in the file, `- Status:` convicted the wrong reports twice
+ * over. A report that QUOTES the protocol template — which several do, because
+ * an agent reporting that the protocol is wrong pastes the protocol — carries a
+ * `- Status: open` inside a fence and was counted open however its own header
+ * read; and a report whose body discusses a status line later on was read the
+ * same way. The status a report claims is a header FIELD, written beside
+ * `- Classification:` above the first section, so that is the only place it is
+ * read from. An unterminated fence swallows the rest of the file rather than
+ * flipping back — the safe direction, since the alternative is reading code as
+ * a field.
+ *
+ * Two shapes defeated the first version of that, and both are the same quoting
+ * case: a NESTED fence, where the outer ```` opens and the inner ``` was taken
+ * for its close, leaving the quoted block read as fields; and an INDENTED
+ * block, which the protocol itself uses and whose indented `## Summary` never
+ * ends the header either. So a fence is closed only by a run of the same
+ * character at least as long as the one that opened it, and an indented block
+ * (four spaces after a blank line, through the blank lines inside it) is
+ * dropped whole.
+ */
+function headerFields(text) {
+    const kept = [];
+    let fence = null;
+    let indented = false;
+    let afterBlank = true;
+    for (const line of text.split(/\r?\n/)) {
+        if (fence !== null) {
+            const close = FENCE.exec(line)?.[1];
+            if (close !== undefined && close[0] === fence[0] && close.length >= fence.length)
+                fence = null;
+            continue;
+        }
+        const blank = line.trim() === "";
+        if (indented) {
+            if (blank || INDENTED.test(line))
+                continue;
+            indented = false;
+        }
+        const open = FENCE.exec(line)?.[1];
+        if (open !== undefined) {
+            fence = open;
+            afterBlank = false;
+            continue;
+        }
+        if (afterBlank && INDENTED.test(line)) {
+            indented = true;
+            continue;
+        }
+        if (SECTION.test(line))
+            break;
+        kept.push(line);
+        afterBlank = blank;
+    }
+    return kept.join("\n");
+}
+/** The words a `Status:` line may say that loam can count. */
+const STATED = ["open", "sent", "fixed", "superseded"];
+/**
+ * The ordinal the next report takes: one past the highest present, never one
+ * past the count.
+ *
+ * Those two differ exactly when the directory has a gap or a legacy name in it
+ * — which this directory does, since the numbering arrived after eleven
+ * reports had already been written — and counting instead of maximising is how
+ * a next ordinal starts handing out numbers that are already taken.
+ */
+function nextOrdinal(entries) {
+    let highest = 0;
+    for (const entry of entries) {
+        if (entry.ordinal === null)
+            continue;
+        const value = Number.parseInt(entry.ordinal, 10);
+        if (value > highest)
+            highest = value;
+    }
+    return String(highest + 1).padStart(3, "0");
+}
+/**
+ * What one report's own `Status:` line says, or `unstated`.
+ *
+ * Unreadable reads as unstated rather than throwing: a report saved as UTF-16,
+ * a file the process cannot open, or a directory somebody named `notes.md` are
+ * all things a diagnostic must survive. `doctor` is the command that has to be
+ * able to describe a broken repository without becoming the next thing that
+ * breaks in it.
+ */
+async function statusOf(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        // Unreadable is not a state the file claims — it is a state of the read.
+        return "unstated";
+    }
+    const word = STATUS_LINE.exec(headerFields(text))?.[1]?.toLowerCase();
+    return STATED.find((known) => known === word) ?? "unstated";
+}
+/**
+ * Read `<root>/loam-reports/`, where `root` is the directory holding the
+ * `loam.json` that resolved — the repository the reports were written at the
+ * root of — falling back, when nothing parsed, to the directory of the
+ * `loam.json` loam FOUND (`doctor.ts` says why that and not the cwd), and to the
+ * run directory only when there is no config file anywhere above it.
+ *
+ * Every `*.md` in the directory is an entry, including a hand-written index
+ * page: which files in there are "really" reports is a second naming
+ * convention, and inventing one would make loam disagree with a directory
+ * listing about what the directory holds. An unnumbered entry contributes
+ * nothing to `next`, so an index costs the corpus nothing either.
+ */
+export async function scanReports(root) {
+    const dir = join(root, REPORTS_DIR);
+    let names;
+    try {
+        names = (await readdir(dir)).filter((name) => name.toLowerCase().endsWith(".md"));
+    }
+    catch (error) {
+        // Absent is the state of every repository that has never had to write a
+        // report, and it is the common one — `present: false`, nothing to say. Any
+        // other errno means the directory IS there and this process could not list
+        // it, which is a different sentence: the corpus exists and loam cannot see
+        // into it, so `present` stays true and the counts stay honestly empty.
+        const code = error.code;
+        const present = code !== "ENOENT" && code !== "ENOTDIR";
+        return { dir, present, total: 0, next: "001", entries: [] };
+    }
+    // Sorted here rather than left in readdir order, which is the filesystem's and
+    // differs between one machine and another — and sorted by the ORDINAL the name
+    // claims, numerically, because report order is what a reader scanning the list
+    // expects and byte order stops being it at exactly the point the widening rule
+    // was written for: `1000-…` sorts before `998-…`, so a directory that has
+    // passed its thousandth report reads 1000, 1001, 998, 999 (verification
+    // 2026-09-04, second pass). Unnumbered names — the shape reports carried before
+    // the numbering existed — contribute no ordinal, so they sort last among
+    // themselves by name, where a reader looking for "the next one" is not looking.
+    const rank = (file) => {
+        const ordinal = ordinalOf(file);
+        return ordinal === null ? Number.POSITIVE_INFINITY : Number.parseInt(ordinal, 10);
+    };
+    names.sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : a > b ? 1 : 0));
+    // Read together, like `staleAgentFiles` does: a report corpus is a flat
+    // directory of small hand-written files, so there is nothing here worth a
+    // concurrency cap, and `Promise.all` preserves the order just established.
+    const entries = await Promise.all(names.map(async (file) => ({
+        file,
+        ordinal: ordinalOf(file),
+        status: await statusOf(join(dir, file)),
+    })));
+    return {
+        dir,
+        present: true,
+        total: entries.length,
+        next: nextOrdinal(entries),
+        entries,
+    };
+}
+//# sourceMappingURL=scan.js.map