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

package/dist/core/status/fleet/fleet.js

@@ -0,0 +1,187 @@
+/**
+ * The whole repository — why the fleet form is cheaper than the feature form.
+ *
+ * `loam status` with no feature runs over every active feature, and deriving a
+ * coherence report or a verification checklist per feature means spinning a
+ * fresh LikeC4 workspace per feature. On a fleet-sized repository that is the
+ * cost that gets a command switched off — `list` made the same call about its
+ * verification column. So the fleet form grades nothing: it reports artifact
+ * PRESENCE, the dependency order, and a verification record only where one
+ * already exists, and its `next[]` hands off to `loam status <FEAT>`, which is
+ * where the checks actually run.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { analyzeDependencies } from "../../dependencies/dependencies.js";
+import {} from "../../dependencies/facts.js";
+import { isLandscapeStub } from "../../scaffold/landscape.js";
+import { repoPath } from "../../envelope/json.js";
+import { FleetContext } from "../../fleet-context.js";
+import { compareIds } from "../../repo/entries.js";
+import { featurePaths, featureSpecPaths, landscapePath } from "../../repo/paths.js";
+import { listFeatures, listServices } from "../../repo/repo.js";
+import { contractOwners, contractsHeldElsewhere, owesContract } from "../contracts.js";
+import { readInterruptedCommit } from "../interrupted.js";
+import { undocumented, vouched, } from "../report.js";
+import { governedServices, scanDeltas } from "../scan.js";
+import { fullyVerified, verificationState } from "../verification.js";
+import { fleetNext } from "./next.js";
+/**
+ * The fleet view: how much of `services/` anyone has written down, every
+ * feature in flight with the stage it has reached, and the order they have to
+ * land in. Nothing here is graded — the module header says why — so the stages
+ * are drawn from artifact presence and from a record that already exists, and
+ * `next[]` hands off to `loam status <FEAT>` for everything else.
+ */
+export async function fleetStatus(docsDir, opts = {}) {
+    const context = opts.context ?? new FleetContext();
+    const interrupted = await readInterruptedCommit(docsDir);
+    const narrowed = opts.service;
+    const all = await listServices(docsDir, context);
+    const services = narrowed === undefined ? all : all.filter((s) => s.id === narrowed);
+    // The service this repository says it IS, and whether the fleet has heard of
+    // it. Asked against the UNNARROWED list, because "is it adopted" is a question
+    // about the fleet and not about the view.
+    //
+    // Both facts travel, where only the unadopted case used to. This value was a
+    // `string | null` that went null exactly when the service directory EXISTED,
+    // so the walk could see the repository it stands in only while that
+    // repository was undocumented — and a developer in an adopted service repo
+    // got the whole fleet's worklist with their own boundary buried in it.
+    const binding = opts.bound === undefined ? null : { id: opts.bound, adopted: all.some((s) => s.id === opts.bound) };
+    const graph = await analyzeDependencies(docsDir, undefined, context);
+    const entries = await listFeatures(docsDir, {}, context);
+    const inScope = narrowed === undefined ? entries : entries.filter((f) => f.services.some((s) => s === narrowed));
+    // Once for the fleet, not once per feature: which features hold a contract
+    // for which service is one fact about the repository, and every feature below
+    // reads its own row out of it. Built over the UNNARROWED list on purpose — a
+    // `--service` view still has to know that a feature outside it discharges the
+    // contract, or the narrowing would invent an obligation.
+    const owners = await contractOwners(docsDir, context);
+    const features = await Promise.all(inScope.map((f) => fleetFeature(docsDir, f, {
+        graph,
+        contracted: contractsHeldElsewhere(owners, f.id),
+        living: new Map(all.map((s) => [s.id, s])),
+        context,
+        interrupted,
+    })));
+    features.sort((a, b) => compareIds(a.id, b.id));
+    // The first-hour ladder's fact, computed exactly when the ladder can apply
+    // — an unnarrowed run over a fleet with zero services and zero features —
+    // so the read disappears from every repository that has anything in it.
+    // Withheld on narrowed runs for the same reason the binding is withheld
+    // below: `--service X` is an explicit question about X, and the
+    // repository's onboarding ladder would be a different question's answer.
+    const teaching = narrowed === undefined && services.length === 0 && features.length === 0
+        ? { landscape: await landscapeTeaching(docsDir) }
+        : null;
+    return {
+        interrupted,
+        services: {
+            total: services.length,
+            undocumented: services.filter(undocumented).length,
+            draft: services.filter((s) => !undocumented(s) && !vouched(s)).length,
+            vouched: services.filter(vouched).length,
+            // A subset of `vouched`, never a fourth bucket: those services ARE
+            // vouched, and the three counts still sum to `total`. It rides beside
+            // the count it qualifies because this line is the fleet's trust
+            // headline, and "118 vouched" over a fleet where 90 of them were read
+            // from a sample is the misreading the scope exists to prevent.
+            sampledVouched: services.filter((s) => vouched(s) && s.vouchScope === "sampled").length,
+        },
+        features,
+        order: graph.order.filter((id) => features.some((f) => f.id === id)),
+        service: narrowed ?? null,
+        // The binding is passed only when this run was NOT narrowed, and that guard
+        // is unchanged now that the binding also decides ORDER. `--service X` is an
+        // explicit question about X, and answering it with a step about whichever
+        // service loam.json happens to name would be a different question's answer
+        // at the top of the list — which is as true of a rung promoted to the front
+        // as it was of `next.adopt-bound` emitted out of nowhere. A narrowed run
+        // sees at most the one service it asked about anyway, so withholding the
+        // binding here costs the reader nothing and keeps `--service X` answering
+        // only about X.
+        next: fleetNext({ services, features, graph, interrupted, teaching }, narrowed === undefined ? binding : null),
+    };
+}
+/**
+ * Which first-hour state the fleet map is in: absent, still the scaffold's own
+ * untouched bytes, or authored. One file read and a byte comparison — the
+ * module header's cost rule stands, no LikeC4 workspace is spun here.
+ */
+async function landscapeTeaching(docsDir) {
+    const lp = landscapePath(docsDir);
+    if (!existsSync(lp))
+        return "missing";
+    try {
+        return isLandscapeStub(await readFile(lp, "utf8")) ? "stub" : "authored";
+    }
+    catch {
+        // Unreadable is not untouched. A map that cannot be read — a directory in
+        // the file's place, a permission — must not be called the scaffold's stub
+        // ("missing" and "stub" would each put a false statement in next[]), so it
+        // reads as "authored", which only drops the one teaching step: the gate
+        // entry still names `loam validate --all`, where an unreadable landscape
+        // is actually graded, and letting this read throw would hand the whole
+        // orientation surface — a command that reports and never gates — to the
+        // repository-unavailable refusal over a file status does not even parse.
+        return "authored";
+    }
+}
+async function fleetFeature(docsDir, feature, view) {
+    const { graph, contracted, living, context, interrupted } = view;
+    const paths = featurePaths(feature.dir);
+    const missing = [];
+    if (!existsSync(paths.intent))
+        missing.push("intent");
+    if (feature.services.length === 0)
+        missing.push("spec");
+    // Requirement text, not a coherence run: `Operations:` lines are read off the
+    // same cached parse `list` already pays for, and the contract question needs
+    // them (owesContract). No LikeC4 workspace is spun here, which is the cost
+    // this form actually refuses.
+    const governs = governedServices(await scanDeltas(docsDir, feature, feature.services, context));
+    for (const svc of feature.services) {
+        const p = featureSpecPaths(feature.dir, svc);
+        if (!existsSync(p.spec))
+            missing.push(`${svc}/spec`);
+        // The same question featureArtifacts asks, through the same function: the
+        // two forms must never disagree about whether a feature owes a contract.
+        if (owesContract(living.get(svc), contracted.has(svc), governs.has(svc)) && !existsSync(p.openapi)) {
+            missing.push(`${svc}/openapi`);
+        }
+    }
+    const verification = (await verificationState(docsDir, feature)).state;
+    const blockedBy = graph.nodes.find((n) => n.id === feature.id)?.dependsOn ?? [];
+    // No `draft` here, ever: that verdict needs the coherence run this form
+    // refuses to pay for, and inferring it from presence alone would be a second
+    // opinion about validity — the one thing status must never invent.
+    //
+    // The interrupted commit leads, exactly as it does in the feature form: every
+    // presence test below is a question about files a killed `archive` may have
+    // half-written, so answering `done` from them is a claim about bytes nobody
+    // has established. Without this the two forms contradicted each other over
+    // one repository — `loam status --json` said `done` and offered "ship it"
+    // while `loam status <FEAT>` said `blocked` — and the rule in report.ts's
+    // header is that this projection is never greener than the gates.
+    const stage = interrupted !== null
+        ? "blocked"
+        : missing.length > 0
+            ? "missing"
+            : blockedBy.length > 0
+                ? "blocked"
+                : fullyVerified(verification)
+                    ? "done"
+                    : "ready";
+    return {
+        id: feature.id,
+        dirName: feature.dirName,
+        path: repoPath(docsDir, feature.dir),
+        stage,
+        services: feature.services,
+        blockedBy,
+        missing,
+        verification,
+    };
+}
+//# sourceMappingURL=fleet.js.map

package/dist/core/status/fleet/fleet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet.js","sourceRoot":"","sources":["../../../../src/core/status/fleet/fleet.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The whole repository — why the fleet form is cheaper than the feature form.\n *\n * `loam status` with no feature runs over every active feature, and deriving a\n * coherence report or a verification checklist per feature means spinning a\n * fresh LikeC4 workspace per feature. On a fleet-sized repository that is the\n * cost that gets a command switched off — `list` made the same call about its\n * verification column. So the fleet form grades nothing: it reports artifact\n * PRESENCE, the dependency order, and a verification record only where one\n * already exists, and its `next[]` hands off to `loam status <FEAT>`, which is\n * where the checks actually run.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { analyzeDependencies } from \"../../dependencies/dependencies.js\";\nimport { type DependencyGraph } from \"../../dependencies/facts.js\";\nimport { isLandscapeStub } from \"../../scaffold/landscape.js\";\nimport { repoPath } from \"../../envelope/json.js\";\nimport { FleetContext } from \"../../fleet-context.js\";\nimport { compareIds, type FeatureEntry, type ServiceEntry } from \"../../repo/entries.js\";\nimport { featurePaths, featureSpecPaths, landscapePath } from \"../../repo/paths.js\";\nimport { listFeatures, listServices } from \"../../repo/repo.js\";\nimport { contractOwners, contractsHeldElsewhere, owesContract } from \"../contracts.js\";\nimport { readInterruptedCommit } from \"../interrupted.js\";\nimport {\n  undocumented,\n  vouched,\n  type ArtifactStatus,\n  type FleetFeatureState,\n  type FleetStatusReport,\n  type InterruptedCommit,\n} from \"../report.js\";\nimport { governedServices, scanDeltas } from \"../scan.js\";\nimport { fullyVerified, verificationState } from \"../verification.js\";\nimport { fleetNext, type Binding } from \"./next.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\n\n/**\n * The fleet view: how much of `services/` anyone has written down, every\n * feature in flight with the stage it has reached, and the order they have to\n * land in. Nothing here is graded — the module header says why — so the stages\n * are drawn from artifact presence and from a record that already exists, and\n * `next[]` hands off to `loam status <FEAT>` for everything else.\n */\nexport async function fleetStatus(\n  docsDir: DocsDir,\n  opts: { service?: string; bound?: string; context?: FleetContext } = {},\n): Promise<FleetStatusReport> {\n  const context = opts.context ?? new FleetContext();\n  const interrupted = await readInterruptedCommit(docsDir);\n  const narrowed = opts.service;\n  const all = await listServices(docsDir, context);\n  const services = narrowed === undefined ? all : all.filter((s) => s.id === narrowed);\n  // The service this repository says it IS, and whether the fleet has heard of\n  // it. Asked against the UNNARROWED list, because \"is it adopted\" is a question\n  // about the fleet and not about the view.\n  //\n  // Both facts travel, where only the unadopted case used to. This value was a\n  // `string | null` that went null exactly when the service directory EXISTED,\n  // so the walk could see the repository it stands in only while that\n  // repository was undocumented — and a developer in an adopted service repo\n  // got the whole fleet's worklist with their own boundary buried in it.\n  const binding: Binding | null =\n    opts.bound === undefined ? null : { id: opts.bound, adopted: all.some((s) => s.id === opts.bound) };\n  const graph = await analyzeDependencies(docsDir, undefined, context);\n  const entries = await listFeatures(docsDir, {}, context);\n  const inScope = narrowed === undefined ? entries : entries.filter((f) => f.services.some((s) => s === narrowed));\n  // Once for the fleet, not once per feature: which features hold a contract\n  // for which service is one fact about the repository, and every feature below\n  // reads its own row out of it. Built over the UNNARROWED list on purpose — a\n  // `--service` view still has to know that a feature outside it discharges the\n  // contract, or the narrowing would invent an obligation.\n  const owners = await contractOwners(docsDir, context);\n\n  const features = await Promise.all(\n    inScope.map((f) =>\n      fleetFeature(docsDir, f, {\n        graph,\n        contracted: contractsHeldElsewhere(owners, f.id),\n        living: new Map(all.map((s) => [s.id, s])),\n        context,\n        interrupted,\n      }),\n    ),\n  );\n  features.sort((a, b) => compareIds(a.id, b.id));\n\n  // The first-hour ladder's fact, computed exactly when the ladder can apply\n  // — an unnarrowed run over a fleet with zero services and zero features —\n  // so the read disappears from every repository that has anything in it.\n  // Withheld on narrowed runs for the same reason the binding is withheld\n  // below: `--service X` is an explicit question about X, and the\n  // repository's onboarding ladder would be a different question's answer.\n  const teaching =\n    narrowed === undefined && services.length === 0 && features.length === 0\n      ? { landscape: await landscapeTeaching(docsDir) }\n      : null;\n\n  return {\n    interrupted,\n    services: {\n      total: services.length,\n      undocumented: services.filter(undocumented).length,\n      draft: services.filter((s) => !undocumented(s) && !vouched(s)).length,\n      vouched: services.filter(vouched).length,\n      // A subset of `vouched`, never a fourth bucket: those services ARE\n      // vouched, and the three counts still sum to `total`. It rides beside\n      // the count it qualifies because this line is the fleet's trust\n      // headline, and \"118 vouched\" over a fleet where 90 of them were read\n      // from a sample is the misreading the scope exists to prevent.\n      sampledVouched: services.filter((s) => vouched(s) && s.vouchScope === \"sampled\").length,\n    },\n    features,\n    order: graph.order.filter((id) => features.some((f) => f.id === id)),\n    service: narrowed ?? null,\n    // The binding is passed only when this run was NOT narrowed, and that guard\n    // is unchanged now that the binding also decides ORDER. `--service X` is an\n    // explicit question about X, and answering it with a step about whichever\n    // service loam.json happens to name would be a different question's answer\n    // at the top of the list — which is as true of a rung promoted to the front\n    // as it was of `next.adopt-bound` emitted out of nowhere. A narrowed run\n    // sees at most the one service it asked about anyway, so withholding the\n    // binding here costs the reader nothing and keeps `--service X` answering\n    // only about X.\n    next: fleetNext(\n      { services, features, graph, interrupted, teaching },\n      narrowed === undefined ? binding : null,\n    ),\n  };\n}\n\n/**\n * Which first-hour state the fleet map is in: absent, still the scaffold's own\n * untouched bytes, or authored. One file read and a byte comparison — the\n * module header's cost rule stands, no LikeC4 workspace is spun here.\n */\nasync function landscapeTeaching(docsDir: DocsDir): Promise<\"missing\" | \"stub\" | \"authored\"> {\n  const lp = landscapePath(docsDir);\n  if (!existsSync(lp)) return \"missing\";\n  try {\n    return isLandscapeStub(await readFile(lp, \"utf8\")) ? \"stub\" : \"authored\";\n  } catch {\n    // Unreadable is not untouched. A map that cannot be read — a directory in\n    // the file's place, a permission — must not be called the scaffold's stub\n    // (\"missing\" and \"stub\" would each put a false statement in next[]), so it\n    // reads as \"authored\", which only drops the one teaching step: the gate\n    // entry still names `loam validate --all`, where an unreadable landscape\n    // is actually graded, and letting this read throw would hand the whole\n    // orientation surface — a command that reports and never gates — to the\n    // repository-unavailable refusal over a file status does not even parse.\n    return \"authored\";\n  }\n}\n\n/** What a feature's fleet row needs about the fleet AROUND it. */\ninterface FleetView {\n  graph: DependencyGraph;\n  /** Operations some other feature's contract already holds. */\n  contracted: ReadonlySet<string>;\n  /** The enumeration's entries by id — where each living service is and what it has (owesContract reads both). */\n  living: ReadonlyMap<string, ServiceEntry>;\n  context: FleetContext;\n  interrupted: InterruptedCommit | null;\n}\n\nasync function fleetFeature(\n  docsDir: DocsDir,\n  feature: FeatureEntry,\n  view: FleetView,\n): Promise<FleetFeatureState> {\n  const { graph, contracted, living, context, interrupted } = view;\n  const paths = featurePaths(feature.dir);\n  const missing: string[] = [];\n  if (!existsSync(paths.intent)) missing.push(\"intent\");\n  if (feature.services.length === 0) missing.push(\"spec\");\n  // Requirement text, not a coherence run: `Operations:` lines are read off the\n  // same cached parse `list` already pays for, and the contract question needs\n  // them (owesContract). No LikeC4 workspace is spun here, which is the cost\n  // this form actually refuses.\n  const governs = governedServices(await scanDeltas(docsDir, feature, feature.services, context));\n  for (const svc of feature.services) {\n    const p = featureSpecPaths(feature.dir, svc);\n    if (!existsSync(p.spec)) missing.push(`${svc}/spec`);\n    // The same question featureArtifacts asks, through the same function: the\n    // two forms must never disagree about whether a feature owes a contract.\n    if (owesContract(living.get(svc), contracted.has(svc), governs.has(svc)) && !existsSync(p.openapi)) {\n      missing.push(`${svc}/openapi`);\n    }\n  }\n  const verification = (await verificationState(docsDir, feature)).state;\n  const blockedBy = graph.nodes.find((n) => n.id === feature.id)?.dependsOn ?? [];\n\n  // No `draft` here, ever: that verdict needs the coherence run this form\n  // refuses to pay for, and inferring it from presence alone would be a second\n  // opinion about validity — the one thing status must never invent.\n  //\n  // The interrupted commit leads, exactly as it does in the feature form: every\n  // presence test below is a question about files a killed `archive` may have\n  // half-written, so answering `done` from them is a claim about bytes nobody\n  // has established. Without this the two forms contradicted each other over\n  // one repository — `loam status --json` said `done` and offered \"ship it\"\n  // while `loam status <FEAT>` said `blocked` — and the rule in report.ts's\n  // header is that this projection is never greener than the gates.\n  const stage: ArtifactStatus =\n    interrupted !== null\n      ? \"blocked\"\n      : missing.length > 0\n        ? \"missing\"\n        : blockedBy.length > 0\n          ? \"blocked\"\n          : fullyVerified(verification)\n            ? \"done\"\n            : \"ready\";\n\n  return {\n    id: feature.id,\n    dirName: feature.dirName,\n    path: repoPath(docsDir, feature.dir),\n    stage,\n    services: feature.services,\n    blockedBy,\n    missing,\n    verification,\n  };\n}\n"]}

package/dist/core/status/fleet/next.js

@@ -0,0 +1,207 @@
+import { serviceTreePath } from "../../kernel/ids/dirs.js";
+import { compareIds } from "../../repo/entries.js";
+import { recoverStep } from "../interrupted.js";
+import { undocumented, } from "../report.js";
+/** How urgent a stage is at fleet level. See {@link fleetNext}. */
+const STAGE_RANK = {
+    done: 0,
+    ready: 1,
+    draft: 2,
+    missing: 3,
+    blocked: 4,
+};
+/**
+ * How many per-service and per-feature steps the fleet form will print before
+ * it stops and says how many it left out. A fleet mid-adoption produced 135
+ * entries under the heading "the next thing to do" — a list nobody reads is a
+ * list that is not navigation, and the first ten are the ten that matter
+ * because the ordering below is already most-unblocking-first.
+ *
+ * Exported so the test asserts the cap through the constant: a literal 10 in a
+ * fixture is a second declaration of the limit, free to disagree the day this
+ * one moves.
+ */
+export const FLEET_NEXT_LIMIT = 10;
+export function fleetNext(fleet, binding) {
+    const { services, features, graph, interrupted, teaching } = fleet;
+    const steps = [];
+    // The two arms of the binding, each named for the question it answers. The
+    // first reproduces the old parameter exactly, so everything reading it below
+    // is unchanged; the second is the fact that used to be thrown away.
+    const unadoptedBinding = binding !== null && !binding.adopted ? binding.id : null;
+    const adoptedBinding = binding !== null && binding.adopted ? binding.id : null;
+    // The repository this command is standing in names a service the fleet has no
+    // directory for. First, ahead of every other service's partial adoption,
+    // because it is the only step that is about HERE.
+    //
+    // This form used to count the fleet and ignore the binding entirely, so in a
+    // service repo bound to an unadopted service — a freshly wired one, the most
+    // common repo there is — an empty fleet made "every service is written down"
+    // vacuously true and `next.fleet-clean` came out top. `loam doctor` had the
+    // right answer (`doctor.service-unknown`) at the same moment, and the
+    // documented agent loop reads `status`: an agent following it was sent to
+    // start a feature instead of adopting the service under its feet.
+    if (unadoptedBinding !== null) {
+        steps.push({
+            code: "next.adopt-bound",
+            statement: `This repository's loam.json says it is '${unadoptedBinding}', and the fleet has no ` +
+                `services/${unadoptedBinding}/ — nothing about the service you are standing in is written down yet.`,
+            command: `loam adopt --service ${unadoptedBinding} --json`,
+            service: unadoptedBinding,
+        });
+    }
+    // The first hour of a docs repo, in order. Zero services and zero features
+    // used to fall through every loop below into `next.fleet-clean` — the header
+    // says why that answer was vacuous — so the emptiest repository loam serves
+    // got the least from the command whose whole purpose is "what do I do next".
+    // These are ordinary steps on purpose: the gate entry still closes the list,
+    // and the tail ternary is untouched. The bind/adopt rungs are suppressed when
+    // `next.adopt-bound` above already names the exact adopt to run, and the
+    // whole ladder is withheld on narrowed runs (`teaching === null`).
+    if (teaching !== null && services.length === 0 && features.length === 0) {
+        if (teaching.landscape !== "authored") {
+            steps.push({
+                code: "next.author-landscape",
+                statement: teaching.landscape === "missing"
+                    ? "architecture/landscape.likec4 does not exist — the fleet map is the one artifact every " +
+                        "cross-service check reads. Run `loam init --create` to scaffold it, then draw the first service."
+                    : "architecture/landscape.likec4 is still the scaffold's untouched map — no service is drawn. " +
+                        "State the facts in a fleet.yaml (service ids, `a -> b` calls) and run " +
+                        "`loam seed --from fleet.yaml` to template the map mechanically — or open the file " +
+                        "and follow its own comments. Either way loam never guesses who calls whom.",
+                // The command each arm's own prose already names, and for a while it
+                // was neither: both arms carried the gate. WORKFLOW.md documents the
+                // agent loop as "read next[0], run the command it names, repeat" and
+                // every generated skill says to branch on the code rather than the
+                // prose — so an agent on the first rung of the first hour ran
+                // `validate --all` against a repository with no services in it, which
+                // answers ok:true with `landscape.matched` and changes nothing, and
+                // came back to the identical next[0] forever. A livelock on day zero,
+                // on the one command built to answer "what now". The gate is still
+                // named: `next.fleet-gate` closes this same list.
+                command: teaching.landscape === "missing" ? "loam init --create" : "loam seed --from fleet.yaml",
+                path: "architecture/landscape.likec4",
+            });
+        }
+        if (unadoptedBinding === null) {
+            steps.push({
+                code: "next.bind-service",
+                statement: "No service repository is bound to this fleet yet. From a service's own repo, point --docs " +
+                    "here and --service at its canonical id, then commit the loam.json it writes.",
+                command: "loam init --docs <path-to-this-docs-repo> --service <service-id>",
+            });
+            steps.push({
+                code: "next.adopt-first",
+                statement: "services/ is empty — nothing about any service is written down yet. Adopt the first one: " +
+                    "the brief walks an agent through writing its baseline docs as draft.",
+                command: "loam adopt --service <service-id> --json",
+            });
+        }
+    }
+    // The per-service rungs are collected into their own list rather than pushed
+    // straight onto `steps`, because the partition below acts on them as a group
+    // — and only on them. Nothing here may float above `next.adopt-bound` or the
+    // first-hour ladder, both of which are about the repository rather than about
+    // any one service in the fleet.
+    const perService = [];
+    for (const s of services.filter(undocumented)) {
+        perService.push({
+            code: "next.adopt",
+            statement: `${serviceTreePath(s)}/ has no spec.md — nothing about ${s.id} is written down, so no feature can be graded against it.`,
+            command: `loam adopt --service ${s.id} --json`,
+            service: s.id,
+        });
+    }
+    // Adoption does not end at spec.md. A service with a living spec and no
+    // model.likec4 is the state archive itself warns about (`service.no-model`)
+    // and the fleet gate reports — invisible here until now, because this form
+    // looked at exactly one bit of each service's artifact set.
+    for (const s of services.filter((x) => !undocumented(x) && !x.has.model)) {
+        perService.push({
+            code: "next.complete-service",
+            statement: `${serviceTreePath(s)}/ has a spec.md but no model.likec4 — the fleet gate reports the service incomplete until something models it.`,
+            command: `loam validate --service ${s.id} --json`,
+            service: s.id,
+        });
+    }
+    // The boundary this repository IS comes first among the boundaries it merely
+    // shares a fleet with. A stable PARTITION and deliberately not a sort: the
+    // bound service's rungs move to the front and every other service keeps the
+    // alphabetical order it already had, so the list an unbound reader sees — a
+    // docs repo, CI, `loam validate --all`'s scorecard — is byte-for-byte the one
+    // it saw before.
+    //
+    // The cap is why this is ordering and not cosmetics. Ten rungs print, and in
+    // the ten-repo case WORKFLOW.md describes every developer's `loam status`
+    // opened with nine other services' adoption work; past ten services the one
+    // rung this developer can actually act on was elided entirely, leaving a list
+    // of nothing but other people's boundaries under the heading "next". No new
+    // code is emitted for any of this — `next[]` has always been documented as
+    // most-unblocking first, and this is the line that makes the claim true from
+    // where the reader is standing.
+    steps.push(...(adoptedBinding === null
+        ? perService
+        : [
+            ...perService.filter((s) => s.service === adoptedBinding),
+            ...perService.filter((s) => s.service !== adoptedBinding),
+        ]));
+    const ordered = [...features].sort((a, b) => STAGE_RANK[a.stage] - STAGE_RANK[b.stage] ||
+        graph.order.indexOf(a.id) - graph.order.indexOf(b.id) ||
+        compareIds(a.id, b.id));
+    for (const f of ordered) {
+        if (f.stage === "done") {
+            steps.push({
+                code: "next.archive",
+                statement: `${f.id} is authored and verified — ship it, and everything waiting on it is released.`,
+                command: `loam archive ${f.id} --dry-run --json`,
+            });
+            continue;
+        }
+        steps.push({
+            code: "next.feature",
+            statement: 
+            // The list, not the stage, is what this sentence names. `blocked` has
+            // two causes now — another feature in flight, and an interrupted commit
+            // that stalls the whole repository — and the second one names no
+            // feature, so keying off the stage alone printed "FEAT-1 is waiting
+            // on ." The recover step above already says what the repository is
+            // waiting on.
+            f.stage === "blocked" && f.blockedBy.length > 0
+                ? `${f.id} is waiting on ${f.blockedBy.join(", ")}.`
+                : `${f.id} is at '${f.stage}'${f.missing.length > 0 ? ` — missing ${f.missing.join(", ")}` : ""}.`,
+            command: `loam status ${f.id} --json`,
+        });
+    }
+    const elided = Math.max(0, steps.length - FLEET_NEXT_LIMIT);
+    // Outside the cap, not merely first inside it: the one step that must never
+    // be the one this list left out.
+    const out = [...(interrupted === null ? [] : [recoverStep(interrupted)]), ...steps.slice(0, FLEET_NEXT_LIMIT)];
+    if (elided > 0) {
+        out.push({
+            code: "next.elided",
+            statement: `${elided} more step(s) of the same kinds were left out — this list is ordered most-unblocking first, so work down it and run status again.`,
+            command: "loam list --json",
+        });
+    }
+    out.push(steps.length === 0
+        ? {
+            code: "next.fleet-clean",
+            statement: "Nothing is in flight and every service is written down — keep the fleet green, then start the next feature.",
+            command: "loam validate --all --json",
+        }
+        : {
+            code: "next.fleet-gate",
+            // `loam validate --all` inside the backticks, not the bare
+            // `validate --all` this sentence carried for a year: a span without
+            // the binary name is invisible to every check that reads a
+            // backticked `loam <verb>` as an instruction — the parse check in
+            // test/agent-commands-runnable.test.ts, and the statement/command
+            // invariant in test/status.test.ts. A prefix is cheaper than an
+            // exemption, and the exemption is what lets a wrong command through.
+            statement: `${features.length} feature(s) in flight over ${services.length} service(s) — ` +
+                "status grades none of them; `loam validate --all` is the gate this repository has to pass, and it is what CI runs.",
+            command: "loam validate --all --json",
+        });
+    return out;
+}
+//# sourceMappingURL=next.js.map

package/dist/core/status/fleet/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../../../../src/core/status/fleet/next.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `next[]` — the whole repository: adoption gaps first, then every feature in\n * flight, most-unblocking first, capped so the list stays navigation rather\n * than inventory.\n */\nimport type { DependencyGraph } from \"../../dependencies/facts.js\";\nimport { serviceTreePath } from \"../../kernel/ids/dirs.js\";\nimport { compareIds, type ServiceEntry } from \"../../repo/entries.js\";\nimport { recoverStep } from \"../interrupted.js\";\nimport {\n  undocumented,\n  type ArtifactStatus,\n  type FleetFeatureState,\n  type InterruptedCommit,\n  type NextStep,\n} from \"../report.js\";\n\n/** How urgent a stage is at fleet level. See {@link fleetNext}. */\nconst STAGE_RANK: Record<ArtifactStatus, number> = {\n  done: 0,\n  ready: 1,\n  draft: 2,\n  missing: 3,\n  blocked: 4,\n};\n\n/**\n * How many per-service and per-feature steps the fleet form will print before\n * it stops and says how many it left out. A fleet mid-adoption produced 135\n * entries under the heading \"the next thing to do\" — a list nobody reads is a\n * list that is not navigation, and the first ten are the ten that matter\n * because the ordering below is already most-unblocking-first.\n *\n * Exported so the test asserts the cap through the constant: a literal 10 in a\n * fixture is a second declaration of the limit, free to disagree the day this\n * one moves.\n */\nexport const FLEET_NEXT_LIMIT = 10;\n\n/**\n * Fleet-level steps, most-unblocking first. A feature ready to ship comes\n * before one that still needs authoring, because archiving it is what releases\n * everything queued behind it; a blocked feature comes last, because there is\n * nothing to do about it from here — its prerequisite is already higher up the\n * list under its own entry.\n *\n * The gate is the LAST entry and it is always there. `next.fleet-clean` used to\n * be the only route to `loam validate --all`, and it was emitted only when\n * nothing was in flight — so a repository that FAILS the fleet gate, which is\n * every repository with work in it, was handed a green-looking list that never\n * once named the command CI runs. This form grades nothing; the least it can do\n * is say where grading happens. `next.fleet-clean` is also no longer the\n * empty-repo answer: over zero services, \"every service is written down\" is\n * vacuously true, and the first hour of a docs repo used to get that green\n * sentence instead of its first three steps. The teaching ladder below owns\n * that case now, and the clean entry survives only for its truthful one —\n * services exist, and nothing is owed.\n */\n/** The whole fleet as the next-step walk reads it. */\nexport interface Fleet {\n  services: ServiceEntry[];\n  features: FleetFeatureState[];\n  graph: DependencyGraph;\n  interrupted: InterruptedCommit | null;\n  /**\n   * The ladder's fact, present exactly when the ladder can apply — an\n   * unnarrowed run over an empty fleet. `null` otherwise: on a narrowed run\n   * (withheld for the reason fleet.ts records beside the binding) and on any\n   * fleet with services or features, where fleet.ts skips the read entirely.\n   */\n  teaching: { landscape: \"missing\" | \"stub\" | \"authored\" } | null;\n}\n\n/**\n * What this repository says it IS, as the walk needs it — and it needs BOTH\n * facts, which is why this is a record and not the bare id it used to be.\n *\n * `adopted: false` is the case the walk always handled: the fleet has no\n * `services/<id>/`, and `next.adopt-bound` leads. `adopted: true` was invisible\n * — the parameter was `string | null` and went null exactly when the directory\n * existed — so a repository bound to a service the fleet DOES know got the\n * whole system's worklist in alphabetical order, with its own boundary\n * somewhere in the middle of it or, past ten services, not on the list at all.\n */\nexport interface Binding {\n  id: string;\n  /** Whether the fleet has a `services/<id>/` for it. */\n  adopted: boolean;\n}\n\nexport function fleetNext(fleet: Fleet, binding: Binding | null): NextStep[] {\n  const { services, features, graph, interrupted, teaching } = fleet;\n  const steps: NextStep[] = [];\n  // The two arms of the binding, each named for the question it answers. The\n  // first reproduces the old parameter exactly, so everything reading it below\n  // is unchanged; the second is the fact that used to be thrown away.\n  const unadoptedBinding = binding !== null && !binding.adopted ? binding.id : null;\n  const adoptedBinding = binding !== null && binding.adopted ? binding.id : null;\n\n  // The repository this command is standing in names a service the fleet has no\n  // directory for. First, ahead of every other service's partial adoption,\n  // because it is the only step that is about HERE.\n  //\n  // This form used to count the fleet and ignore the binding entirely, so in a\n  // service repo bound to an unadopted service — a freshly wired one, the most\n  // common repo there is — an empty fleet made \"every service is written down\"\n  // vacuously true and `next.fleet-clean` came out top. `loam doctor` had the\n  // right answer (`doctor.service-unknown`) at the same moment, and the\n  // documented agent loop reads `status`: an agent following it was sent to\n  // start a feature instead of adopting the service under its feet.\n  if (unadoptedBinding !== null) {\n    steps.push({\n      code: \"next.adopt-bound\",\n      statement:\n        `This repository's loam.json says it is '${unadoptedBinding}', and the fleet has no ` +\n        `services/${unadoptedBinding}/ — nothing about the service you are standing in is written down yet.`,\n      command: `loam adopt --service ${unadoptedBinding} --json`,\n      service: unadoptedBinding,\n    });\n  }\n\n  // The first hour of a docs repo, in order. Zero services and zero features\n  // used to fall through every loop below into `next.fleet-clean` — the header\n  // says why that answer was vacuous — so the emptiest repository loam serves\n  // got the least from the command whose whole purpose is \"what do I do next\".\n  // These are ordinary steps on purpose: the gate entry still closes the list,\n  // and the tail ternary is untouched. The bind/adopt rungs are suppressed when\n  // `next.adopt-bound` above already names the exact adopt to run, and the\n  // whole ladder is withheld on narrowed runs (`teaching === null`).\n  if (teaching !== null && services.length === 0 && features.length === 0) {\n    if (teaching.landscape !== \"authored\") {\n      steps.push({\n        code: \"next.author-landscape\",\n        statement:\n          teaching.landscape === \"missing\"\n            ? \"architecture/landscape.likec4 does not exist — the fleet map is the one artifact every \" +\n              \"cross-service check reads. Run `loam init --create` to scaffold it, then draw the first service.\"\n            : \"architecture/landscape.likec4 is still the scaffold's untouched map — no service is drawn. \" +\n              \"State the facts in a fleet.yaml (service ids, `a -> b` calls) and run \" +\n              \"`loam seed --from fleet.yaml` to template the map mechanically — or open the file \" +\n              \"and follow its own comments. Either way loam never guesses who calls whom.\",\n        // The command each arm's own prose already names, and for a while it\n        // was neither: both arms carried the gate. WORKFLOW.md documents the\n        // agent loop as \"read next[0], run the command it names, repeat\" and\n        // every generated skill says to branch on the code rather than the\n        // prose — so an agent on the first rung of the first hour ran\n        // `validate --all` against a repository with no services in it, which\n        // answers ok:true with `landscape.matched` and changes nothing, and\n        // came back to the identical next[0] forever. A livelock on day zero,\n        // on the one command built to answer \"what now\". The gate is still\n        // named: `next.fleet-gate` closes this same list.\n        command: teaching.landscape === \"missing\" ? \"loam init --create\" : \"loam seed --from fleet.yaml\",\n        path: \"architecture/landscape.likec4\",\n      });\n    }\n    if (unadoptedBinding === null) {\n      steps.push({\n        code: \"next.bind-service\",\n        statement:\n          \"No service repository is bound to this fleet yet. From a service's own repo, point --docs \" +\n          \"here and --service at its canonical id, then commit the loam.json it writes.\",\n        command: \"loam init --docs <path-to-this-docs-repo> --service <service-id>\",\n      });\n      steps.push({\n        code: \"next.adopt-first\",\n        statement:\n          \"services/ is empty — nothing about any service is written down yet. Adopt the first one: \" +\n          \"the brief walks an agent through writing its baseline docs as draft.\",\n        command: \"loam adopt --service <service-id> --json\",\n      });\n    }\n  }\n\n  // The per-service rungs are collected into their own list rather than pushed\n  // straight onto `steps`, because the partition below acts on them as a group\n  // — and only on them. Nothing here may float above `next.adopt-bound` or the\n  // first-hour ladder, both of which are about the repository rather than about\n  // any one service in the fleet.\n  const perService: NextStep[] = [];\n  for (const s of services.filter(undocumented)) {\n    perService.push({\n      code: \"next.adopt\",\n      statement: `${serviceTreePath(s)}/ has no spec.md — nothing about ${s.id} is written down, so no feature can be graded against it.`,\n      command: `loam adopt --service ${s.id} --json`,\n      service: s.id,\n    });\n  }\n\n  // Adoption does not end at spec.md. A service with a living spec and no\n  // model.likec4 is the state archive itself warns about (`service.no-model`)\n  // and the fleet gate reports — invisible here until now, because this form\n  // looked at exactly one bit of each service's artifact set.\n  for (const s of services.filter((x) => !undocumented(x) && !x.has.model)) {\n    perService.push({\n      code: \"next.complete-service\",\n      statement: `${serviceTreePath(s)}/ has a spec.md but no model.likec4 — the fleet gate reports the service incomplete until something models it.`,\n      command: `loam validate --service ${s.id} --json`,\n      service: s.id,\n    });\n  }\n\n  // The boundary this repository IS comes first among the boundaries it merely\n  // shares a fleet with. A stable PARTITION and deliberately not a sort: the\n  // bound service's rungs move to the front and every other service keeps the\n  // alphabetical order it already had, so the list an unbound reader sees — a\n  // docs repo, CI, `loam validate --all`'s scorecard — is byte-for-byte the one\n  // it saw before.\n  //\n  // The cap is why this is ordering and not cosmetics. Ten rungs print, and in\n  // the ten-repo case WORKFLOW.md describes every developer's `loam status`\n  // opened with nine other services' adoption work; past ten services the one\n  // rung this developer can actually act on was elided entirely, leaving a list\n  // of nothing but other people's boundaries under the heading \"next\". No new\n  // code is emitted for any of this — `next[]` has always been documented as\n  // most-unblocking first, and this is the line that makes the claim true from\n  // where the reader is standing.\n  steps.push(\n    ...(adoptedBinding === null\n      ? perService\n      : [\n          ...perService.filter((s) => s.service === adoptedBinding),\n          ...perService.filter((s) => s.service !== adoptedBinding),\n        ]),\n  );\n\n  const ordered = [...features].sort(\n    (a, b) =>\n      STAGE_RANK[a.stage] - STAGE_RANK[b.stage] ||\n      graph.order.indexOf(a.id) - graph.order.indexOf(b.id) ||\n      compareIds(a.id, b.id),\n  );\n  for (const f of ordered) {\n    if (f.stage === \"done\") {\n      steps.push({\n        code: \"next.archive\",\n        statement: `${f.id} is authored and verified — ship it, and everything waiting on it is released.`,\n        command: `loam archive ${f.id} --dry-run --json`,\n      });\n      continue;\n    }\n    steps.push({\n      code: \"next.feature\",\n      statement:\n        // The list, not the stage, is what this sentence names. `blocked` has\n        // two causes now — another feature in flight, and an interrupted commit\n        // that stalls the whole repository — and the second one names no\n        // feature, so keying off the stage alone printed \"FEAT-1 is waiting\n        // on .\" The recover step above already says what the repository is\n        // waiting on.\n        f.stage === \"blocked\" && f.blockedBy.length > 0\n          ? `${f.id} is waiting on ${f.blockedBy.join(\", \")}.`\n          : `${f.id} is at '${f.stage}'${f.missing.length > 0 ? ` — missing ${f.missing.join(\", \")}` : \"\"}.`,\n      command: `loam status ${f.id} --json`,\n    });\n  }\n\n  const elided = Math.max(0, steps.length - FLEET_NEXT_LIMIT);\n  // Outside the cap, not merely first inside it: the one step that must never\n  // be the one this list left out.\n  const out = [...(interrupted === null ? [] : [recoverStep(interrupted)]), ...steps.slice(0, FLEET_NEXT_LIMIT)];\n  if (elided > 0) {\n    out.push({\n      code: \"next.elided\",\n      statement: `${elided} more step(s) of the same kinds were left out — this list is ordered most-unblocking first, so work down it and run status again.`,\n      command: \"loam list --json\",\n    });\n  }\n\n  out.push(\n    steps.length === 0\n      ? {\n          code: \"next.fleet-clean\",\n          statement:\n            \"Nothing is in flight and every service is written down — keep the fleet green, then start the next feature.\",\n          command: \"loam validate --all --json\",\n        }\n      : {\n          code: \"next.fleet-gate\",\n          // `loam validate --all` inside the backticks, not the bare\n          // `validate --all` this sentence carried for a year: a span without\n          // the binary name is invisible to every check that reads a\n          // backticked `loam <verb>` as an instruction — the parse check in\n          // test/agent-commands-runnable.test.ts, and the statement/command\n          // invariant in test/status.test.ts. A prefix is cheaper than an\n          // exemption, and the exemption is what lets a wrong command through.\n          statement:\n            `${features.length} feature(s) in flight over ${services.length} service(s) — ` +\n            \"status grades none of them; `loam validate --all` is the gate this repository has to pass, and it is what CI runs.\",\n          command: \"loam validate --all --json\",\n        },\n  );\n  return out;\n}\n"]}

package/dist/core/status/interrupted.js

@@ -0,0 +1,97 @@
+/**
+ * The one state that outranks everything else: a journaled writer — archive,
+ * unarchive, rebase, vouch, new, or a record — killed mid-commit, read off
+ * the intent journal `.loam-commit` leaves in the docs repo. The shape both report forms carry it in is `InterruptedCommit`
+ * (report.ts); this module is the cheap read behind it, and the recovery step
+ * that leads every `next[]` while the journal exists.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { COMMIT_INTENT } from "../staging/interrupted.js";
+import { readCommitIntent } from "../staging/recovery/intent.js";
+import { readTxnIntent } from "../staging/txn/journal.js";
+/**
+ * The intent journal, if a commit left one behind. Null on every healthy repo,
+ * which is every repo except one whose last write was killed.
+ *
+ * Cheap on purpose: an `existsSync` and, at most, one small JSON read. `doctor`
+ * pays for the whole `scanWritePathResidue` walk because it is a diagnosis;
+ * `status` is run before every step of the loop and asks the one question whose
+ * answer invalidates all its others.
+ */
+export async function readInterruptedCommit(docsDir) {
+    const intent = await readCommitIntent(docsDir);
+    if (intent === null) {
+        if (!existsSync(join(docsDir, COMMIT_INTENT)))
+            return null;
+        // Version 2 — the smaller journaled transaction. Its `rerun` field IS the
+        // recovering command: recovery runs at the start of that command's next
+        // invocation, exactly as archive's does under its own lock.
+        const txn = await readTxnIntent(docsDir);
+        if (txn !== null) {
+            return {
+                command: txn.command,
+                feature: txn.target,
+                host: txn.host,
+                pid: txn.pid,
+                at: txn.at,
+                files: txn.files.map((f) => f.path),
+                unreadable: false,
+                recover: txn.rerun,
+            };
+        }
+        return {
+            command: null,
+            feature: null,
+            host: null,
+            pid: null,
+            at: null,
+            files: [],
+            unreadable: true,
+            recover: null,
+        };
+    }
+    return {
+        command: intent.command,
+        feature: intent.feature,
+        // Coerced here rather than trusted. `readCommitIntent` validates exactly the
+        // fields a REPAIR needs — the version, the command, the restore direction,
+        // the feature, the two move paths and the file digests — so `host`, `pid`
+        // and `at` arrive as whatever the journal happened to hold, `undefined`
+        // included. That is worse than null in both renderings: `JSON.stringify`
+        // drops an undefined value's key entirely, so `--json` loses the field
+        // instead of reporting it empty, and the two human lines print
+        // "(undefined, pid undefined, undefined)". These three are the label a
+        // person places the crash against and nothing branches on them, so the
+        // coercion belongs at this boundary — widening the validator would change
+        // which journals `archive` and `unarchive` agree to repair, which is a
+        // decision about somebody's half-written docs, not about a label.
+        host: typeof intent.host === "string" ? intent.host : null,
+        pid: typeof intent.pid === "number" ? intent.pid : null,
+        at: typeof intent.at === "string" ? intent.at : null,
+        files: intent.files.map((f) => f.path),
+        unreadable: false,
+        // The recovering command is the interrupted one re-run: it repairs first,
+        // under the lock, from the snapshot it took before the commit. Spelled per
+        // branch rather than interpolated, like doctor's own repair line, so
+        // test/agent-commands-runnable.test.ts can parse it against the real program.
+        recover: intent.command === "archive" ? `loam archive ${intent.feature}` : `loam unarchive ${intent.feature}`,
+    };
+}
+/**
+ * The step that has to come before every other one. Always first, and never
+ * elided by the fleet form's cap: nothing else in the list can be done until
+ * somebody knows whether the living docs are the docs.
+ */
+export function recoverStep(i) {
+    return {
+        code: "next.recover-commit",
+        statement: i.unreadable
+            ? `${COMMIT_INTENT} in this docs repo cannot be read — a commit was interrupted and the one record of which files it had already written is unreadable. Nothing below can be trusted until a human compares the living docs against version control.`
+            : `A \`${i.recover}\` was killed mid-commit (${i.host}, pid ${i.pid}, ${i.at}) — ${i.files.length} file(s) may be half-written: ${i.files.join(", ")}. Everything below is derived from those files.`,
+        // No command loam offers repairs an unreadable journal — saying otherwise
+        // would send an agent to run something that refuses.
+        command: i.recover ?? "loam doctor --json",
+    };
+}
+//# sourceMappingURL=interrupted.js.map

package/dist/core/status/interrupted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupted.js","sourceRoot":"","sources":["../../../src/core/status/interrupted.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The one state that outranks everything else: a journaled writer — archive,\n * unarchive, rebase, vouch, new, or a record — killed mid-commit, read off\n * the intent journal `.loam-commit` leaves in the docs repo. The shape both report forms carry it in is `InterruptedCommit`\n * (report.ts); this module is the cheap read behind it, and the recovery step\n * that leads every `next[]` while the journal exists.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { COMMIT_INTENT } from \"../staging/interrupted.js\";\nimport { readCommitIntent } from \"../staging/recovery/intent.js\";\nimport { readTxnIntent } from \"../staging/txn/journal.js\";\nimport type { InterruptedCommit, NextStep } from \"./report.js\";\n\n/**\n * The intent journal, if a commit left one behind. Null on every healthy repo,\n * which is every repo except one whose last write was killed.\n *\n * Cheap on purpose: an `existsSync` and, at most, one small JSON read. `doctor`\n * pays for the whole `scanWritePathResidue` walk because it is a diagnosis;\n * `status` is run before every step of the loop and asks the one question whose\n * answer invalidates all its others.\n */\nexport async function readInterruptedCommit(docsDir: string): Promise<InterruptedCommit | null> {\n  const intent = await readCommitIntent(docsDir);\n  if (intent === null) {\n    if (!existsSync(join(docsDir, COMMIT_INTENT))) return null;\n    // Version 2 — the smaller journaled transaction. Its `rerun` field IS the\n    // recovering command: recovery runs at the start of that command's next\n    // invocation, exactly as archive's does under its own lock.\n    const txn = await readTxnIntent(docsDir);\n    if (txn !== null) {\n      return {\n        command: txn.command,\n        feature: txn.target,\n        host: txn.host,\n        pid: txn.pid,\n        at: txn.at,\n        files: txn.files.map((f) => f.path),\n        unreadable: false,\n        recover: txn.rerun,\n      };\n    }\n    return {\n      command: null,\n      feature: null,\n      host: null,\n      pid: null,\n      at: null,\n      files: [],\n      unreadable: true,\n      recover: null,\n    };\n  }\n  return {\n    command: intent.command,\n    feature: intent.feature,\n    // Coerced here rather than trusted. `readCommitIntent` validates exactly the\n    // fields a REPAIR needs — the version, the command, the restore direction,\n    // the feature, the two move paths and the file digests — so `host`, `pid`\n    // and `at` arrive as whatever the journal happened to hold, `undefined`\n    // included. That is worse than null in both renderings: `JSON.stringify`\n    // drops an undefined value's key entirely, so `--json` loses the field\n    // instead of reporting it empty, and the two human lines print\n    // \"(undefined, pid undefined, undefined)\". These three are the label a\n    // person places the crash against and nothing branches on them, so the\n    // coercion belongs at this boundary — widening the validator would change\n    // which journals `archive` and `unarchive` agree to repair, which is a\n    // decision about somebody's half-written docs, not about a label.\n    host: typeof intent.host === \"string\" ? intent.host : null,\n    pid: typeof intent.pid === \"number\" ? intent.pid : null,\n    at: typeof intent.at === \"string\" ? intent.at : null,\n    files: intent.files.map((f) => f.path),\n    unreadable: false,\n    // The recovering command is the interrupted one re-run: it repairs first,\n    // under the lock, from the snapshot it took before the commit. Spelled per\n    // branch rather than interpolated, like doctor's own repair line, so\n    // test/agent-commands-runnable.test.ts can parse it against the real program.\n    recover: intent.command === \"archive\" ? `loam archive ${intent.feature}` : `loam unarchive ${intent.feature}`,\n  };\n}\n\n/**\n * The step that has to come before every other one. Always first, and never\n * elided by the fleet form's cap: nothing else in the list can be done until\n * somebody knows whether the living docs are the docs.\n */\nexport function recoverStep(i: InterruptedCommit): NextStep {\n  return {\n    code: \"next.recover-commit\",\n    statement: i.unreadable\n      ? `${COMMIT_INTENT} in this docs repo cannot be read — a commit was interrupted and the one record of which files it had already written is unreadable. Nothing below can be trusted until a human compares the living docs against version control.`\n      : `A \\`${i.recover}\\` was killed mid-commit (${i.host}, pid ${i.pid}, ${i.at}) — ${i.files.length} file(s) may be half-written: ${i.files.join(\", \")}. Everything below is derived from those files.`,\n    // No command loam offers repairs an unreadable journal — saying otherwise\n    // would send an agent to run something that refuses.\n    command: i.recover ?? \"loam doctor --json\",\n  };\n}\n"]}

package/dist/core/status/report.js

@@ -0,0 +1,31 @@
+/** The closed set. The module header says what each value instructs. */
+export const ARTIFACT_STATUSES = ["missing", "blocked", "draft", "ready", "done"];
+/**
+ * The artifact kinds a feature can owe, in the order the cycle authors them.
+ * `spec`, `arch-spec`, `openapi` and `asyncapi` are per-service and repeat
+ * once per service the feature touches; `capabilities` repeats once per
+ * capability document the feature's delta carries; the rest are feature-wide.
+ *
+ * `capabilities` sits where an analyst writes it — the business promise comes
+ * before the services that keep it, and a capability-only feature is a real and
+ * ordinary first commit.
+ */
+export const ARTIFACT_IDS = [
+    "intent",
+    "delta",
+    "capabilities",
+    "spec",
+    "arch-spec",
+    "openapi",
+    "asyncapi",
+    "verification",
+];
+/** Nothing is written down: no living spec at all. Every other absence is partial adoption. */
+export function undocumented(s) {
+    return !s.has.spec;
+}
+/** A person stamped it — `loam vouch`'s exact postcondition, read back off the frontmatter. */
+export function vouched(s) {
+    return s.status === "verified" && s.sources.stamped;
+}
+//# sourceMappingURL=report.js.map