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

package/dist/core/doctor/doctor.js

@@ -0,0 +1,355 @@
+/**
+ * The preflight: can loam run here at all, and can its answers be trusted?
+ *
+ * The walk only. Each question it asks lives in its own module — `./config.ts`
+ * for the config and the fleet map, `./agents.ts` for the agent surface,
+ * `./residue.ts` for what a killed writer left — and every one of them returns
+ * findings rather than printing. That is the whole contract this module keeps:
+ * `doctor` is the command that must be able to describe a broken repository
+ * without becoming the next thing that breaks in it.
+ */
+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, LIKEC4_PROJECT_FILENAME } from "../repo/paths.js";
+import { docsRepoState } from "../repo/state.js";
+import { listFeatures, listServices } from "../repo/repo.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";
+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);
+    const findings = [];
+    if (inspected.status === "missing") {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.config-missing",
+            message: `No ${CONFIG_FILENAME} found at or above ${cwd}.`,
+            fix: "Run `loam init --docs <path-to-docs-repo>` here (add `--create` to make a new docs repo).",
+        });
+    }
+    else if (inspected.status === "invalid") {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.config-invalid",
+            message: `Invalid ${CONFIG_FILENAME}: ${inspected.error ?? "unknown error"}`,
+            fix: `Repair ${path} — or delete it and re-run \`loam init\`.`,
+        });
+    }
+    const docsDir = inspected.config?.docsDir ?? null;
+    const state = docsDir === null ? null : docsRepoState(docsDir);
+    const exists = state !== null && state.kind !== "missing";
+    const readable = exists && docsDir !== null ? await canAccess(docsDir, constants.R_OK) : false;
+    const writable = exists && docsDir !== null ? await canAccess(docsDir, constants.W_OK) : false;
+    const servicesDir = state?.kind === "ok";
+    const landscapeFile = docsDir === null ? null : landscapePath(docsDir);
+    const landscape = landscapeFile === null ? false : await canAccess(landscapeFile, constants.F_OK);
+    // The docs-repo verdict comes from `docsRepoState`, the same function
+    // `listServices` refuses on, so doctor cannot call a repo healthy that the
+    // enumeration will not read.
+    if (state?.kind === "missing") {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.docs-missing",
+            message: `Configured docsDir is missing or is not a directory: ${docsDir}`,
+            fix: `Fix "docsDir" in ${path}, clone the docs repo to ${docsDir}, or run \`loam init --docs <dir> --create\`.`,
+        });
+    }
+    else if (state?.kind === "no-services") {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.services-missing",
+            message: `Required services/ directory is missing under ${docsDir} — that path is not a docs repo.`,
+            fix: `Point "docsDir" in ${path} at the shared docs repo, or run \`loam init --docs ${docsDir} --create\`.`,
+        });
+    }
+    // An absolute docsDir in a committed config names a directory that exists on
+    // exactly one machine. It is a warning and not a blocker because it works
+    // perfectly — for the person who ran `loam init`, and for nobody who clones
+    // the repo afterwards.
+    const asWritten = inspected.config?.docsDirAsWritten;
+    const configRoot = inspected.config?.root;
+    if (asWritten !== undefined
+        && configRoot !== undefined
+        && isAbsolute(asWritten)
+        && resolve(asWritten) !== resolve(configRoot)) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.docs-absolute",
+            message: `"docsDir" is stored as an absolute path (${asWritten}); ` +
+                `${CONFIG_FILENAME} is committed, so it will not resolve on anyone else's machine.`,
+            fix: `Rewrite "docsDir" in ${path} as a path relative to that file (e.g. "../docs").`,
+        });
+    }
+    if (exists && !readable) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.docs-unreadable",
+            message: `docsDir is not readable by this process: ${docsDir}`,
+            fix: `Grant read access to ${docsDir} (check ownership and mode).`,
+        });
+    }
+    if (exists && !writable) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.docs-readonly",
+            message: `docsDir is not writable; read-only commands work, archive/init do not: ${docsDir}`,
+            fix: `Grant write access to ${docsDir} if you need \`loam new\`, \`loam adopt\` or \`loam archive\`.`,
+        });
+    }
+    if (exists && !landscape) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.landscape-missing",
+            message: `${landscapeFile} is missing — nothing cross-service can be checked without it.`,
+            fix: "Create architecture/landscape.likec4 with one element per service and an edge per call (`loam init --create` writes the empty map).",
+        });
+    }
+    else if (exists && landscapeFile !== null && readable) {
+        await inspectLandscape(landscapeFile, findings);
+    }
+    // The renderer's view of the repo, which is not loam's. loam parses every
+    // `.likec4` file ALONE, so each one declares its own `specification` block and
+    // re-declares whatever elements it names; LikeC4's own workspace loader merges
+    // the whole tree into one model, and those declarations then collide. The
+    // result was two tools disagreeing in the most confusing possible direction:
+    // `loam validate --all` reported zero errors on a tree where `npx likec4
+    // 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. 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 — `
+                + "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 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
+    // spellings of `.loam-lock` / `.loam-commit` / the temp-file pattern are
+    // staging's own — doctor grades, it does not re-spell. This is the surface
+    // that used to report `healthy: true` over half-merged docs.
+    const writePath = docsDir !== null && exists && readable
+        ? await scanWritePathResidue(docsDir)
+        : null;
+    if (docsDir !== null && writePath !== null)
+        gradeWritePathResidue(docsDir, writePath, findings);
+    // The one writer whose journal is NOT in the docs repo: `loam gherkin`
+    // commits into the service repo's owned `<gherkinDir>/loam/` root, with the
+    // same lock and journal files. When this repo IS a service repo, that root
+    // gets the same scan and the same grades — the codes are the contract, the
+    // prose says where — because "doctor reports an interrupted commit until
+    // recovery succeeds" has to hold for every writer, not only the docs-repo
+    // ones. Scanning it is cheap: the root is loam's own flat directory.
+    let serviceWritePath = null;
+    if (inspected.config?.service !== undefined && inspected.config.root !== undefined) {
+        try {
+            const emissionRoot = gherkinRoot(inspected.config.root, inspected.config.gherkinDir);
+            if (existsSync(emissionRoot)) {
+                serviceWritePath = await scanWritePathResidue(emissionRoot);
+                gradeWritePathResidue(emissionRoot, serviceWritePath, findings);
+            }
+        }
+        catch (err) {
+            // An unsafe gherkinDir is `loam gherkin`'s refusal to make, with its own
+            // sentence; doctor only declines to scan what it cannot trust.
+            if (!(err instanceof UnsafePathError))
+                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
+    // `doctor.inventory-unreadable`.
+    let inventoried = false;
+    if (docsDir !== null && readable && servicesDir) {
+        try {
+            [services, activeFeatures] = await Promise.all([
+                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) {
+            findings.push({
+                severity: "warning",
+                code: "doctor.inventory-unreadable",
+                message: `Could not inventory the docs repo: ${error instanceof Error ? error.message : String(error)}`,
+                fix: `Check that ${docsDir}/services and ${docsDir}/features are readable directories.`,
+            });
+        }
+    }
+    const currentService = configuredService === null
+        ? { configured: null, status: "unbound" }
+        : services.some((service) => service.id === configuredService)
+            ? { configured: configuredService, status: "matched" }
+            : 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
+    // shared repo to one of the services it holds, which is not a thing loam has
+    // a meaning for. doctor already knew where it was standing (it prints the
+    // fleet count two lines up) and reported the warning anyway, so the first
+    // preflight anyone ran in a freshly created docs repo came back yellow with
+    // advice that made it worse. The docs repo's own loam.json is the one that
+    // resolves `docsDir` to the directory holding it — that identity, not a
+    // 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",
+            code: "doctor.service-unbound",
+            message: "loam.json has no service binding; service-repo checks need `service`.",
+            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
+        // an enumeration that threw, `services` is empty for a reason that has
+        // nothing to do with `service`, and doctor pointed the reader at the one
+        // config field that was fine while the blocker it had already filed named
+        // the real one. `currentService.status` still reports `unknown` — the
+        // envelope describes what loam could and could not match, and an unread
+        // fleet matches nothing.
+        findings.push({
+            severity: "warning",
+            code: "doctor.service-unknown",
+            message: `Configured service '${configuredService}' is not present under services/.`,
+            // `--service <id>`, not a positional: `loam adopt` takes no argument, so
+            // the spelling this finding used to print was refused by commander with
+            // "too many arguments" — as the FIRST instruction a freshly bound service
+            // repo ever receives. test/agent-commands-runnable.test.ts parses every
+            // `loam …` loam prints against the real program so it cannot recur.
+            fix: `Run \`loam adopt --service ${configuredService}\` to onboard it, or fix "service" in ${path}.`,
+        });
+    }
+    // The slash commands (and everything else `init` lays down for a tool) belong
+    // 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: {
+            package: "@ybotok/loam",
+            version: LOAM_VERSION,
+            node: process.version,
+            platform: process.platform,
+            arch: process.arch,
+        },
+        config: { path, status: inspected.status, error: inspected.error },
+        docs: {
+            path: docsDir,
+            exists,
+            readable,
+            writable,
+            servicesDir,
+            landscape,
+        },
+        counts: { services: services.length, activeFeatures: activeFeatures.length },
+        currentService,
+        agents,
+        reports,
+        writePath,
+        serviceWritePath,
+        findings,
+    };
+}
+//# sourceMappingURL=doctor.js.map

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

@@ -0,0 +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, 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

@@ -0,0 +1,13 @@
+/**
+ * What a diagnosis IS: the finding shape, the report shape, and the agent
+ * surface inside it.
+ *
+ * A module of its own because five checks fill this in and the command prints
+ * it, so every one of them agrees about what a blocker means here — something
+ * that stops loam running at all, as against a warning, which is something a
+ * person should know before trusting an answer. That distinction is the whole
+ * value of `doctor`, and it lives in the type rather than in five checks'
+ * judgement.
+ */
+import {} from "../staging/recovery/residue.js";
+//# sourceMappingURL=report.js.map

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

@@ -0,0 +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 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"]}