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

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

@@ -0,0 +1,302 @@
+import { serviceTreePath } from "../../kernel/ids/dirs.js";
+import { compareIds } from "../../repo/entries.js";
+import { recoverStep } from "../interrupted.js";
+import { featureLabel, fleetStageWords } from "../feature/words.js";
+import { undocumented, vouched, } 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 features that bring the bound service into being, when any in flight
+    // do. Their steps lead and the feature loop below skips them, so a feature
+    // this repository exists for is named once, first — EVERY one of them, since
+    // whichever archives first is the one that makes the service living.
+    const introducing = unadoptedBinding === null ? [] : features.filter((f) => binding.introducedBy.includes(f.id));
+    // 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.
+    //
+    // Unless a feature in flight INTRODUCES the service. Then there is no code
+    // yet for `loam adopt` to read — the feature's own specs/ ARE its documents
+    // until it archives — and telling its first developer to adopt it sent them
+    // to describe an empty repository. The step is the feature's, under the code
+    // the feature loop already emits, so nothing new needs branching on.
+    for (const f of introducing) {
+        const others = introducing.filter((o) => o !== f).map((o) => o.id);
+        steps.push({
+            code: "next.feature",
+            statement: `This repository's loam.json says it is '${unadoptedBinding}', which ${f.id} introduces` +
+                (others.length > 0 ? ` (so does ${others.join(", ")})` : "") +
+                ` — it is not in the living docs until ${others.length > 0 ? "one of them" : f.id} archives, so there is ` +
+                `nothing to adopt; ${f.id}'s own status says what this repository owes it.`,
+            command: `loam status ${f.id} --json`,
+        });
+    }
+    if (unadoptedBinding !== null && introducing.length === 0) {
+        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 with the service agent profile, then commit the " +
+                    "loam.json it writes.",
+                // `--agent-profile service`, because the default is `full`, and `full`
+                // writes loam-feature and loam-ship into the service checkout — the two
+                // workflows this docs repo keeps, which README tells every service
+                // repo to leave out. An agent runs this literal, not the README.
+                command: "loam init --docs <path-to-this-docs-repo> --service <service-id> --agent-profile service",
+            });
+            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",
+            });
+        }
+    }
+    // Features BEFORE the per-service rungs. The rungs used to lead, on the
+    // reading that an adoption gap blocks grading — and on a fleet mid-adoption
+    // that put a page of `next.adopt` lines ahead of the one feature anybody was
+    // working on, and the cap below elided that feature as "more step(s) of the
+    // same kinds": the only change in flight, invisible under the heading
+    // "next". A feature is work somebody started; an undocumented service is
+    // backlog. The rungs still follow, and still in full where it matters —
+    // `serviceSteps` beside this list carries every one of them uncapped.
+    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 (introducing.includes(f))
+            continue;
+        const label = featureLabel(f);
+        if (f.stage === "done") {
+            steps.push({
+                code: "next.archive",
+                statement: `${label} is authored and verified — archive it to fold its deltas into the living docs, 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.
+            //
+            // And never the bare stage word: "FEAT-1 is at 'ready'" over a feature
+            // with nothing built read as ready to ship. `stageWords` is the one
+            // place the human sentence for a stage lives (../feature/words.ts).
+            f.stage === "blocked" && interrupted === null && f.blockedBy.length > 0
+                ? `${label} is waiting on ${f.blockedBy.join(", ")}.`
+                : `${label}: ${fleetStageWords(f, interrupted !== null)}.`,
+            command: `loam status ${f.id} --json`,
+        });
+    }
+    steps.push(...perServiceSteps(services, adoptedBinding));
+    const left = steps.slice(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 (left.length > 0) {
+        // Which kinds, counted: "of the same kinds" told a reader nothing about
+        // whether the feature they came for was among the missing.
+        const kinds = [...new Set(left.map((s) => s.code))].map((code) => `${left.filter((s) => s.code === code).length} ${code}`);
+        out.push({
+            code: "next.elided",
+            statement: `${left.length} more step(s) were left out (${kinds.join(", ")}) — 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;
+}
+/**
+ * Every per-service rung, in the order the list prints them: the bound
+ * service's own first, then the rest alphabetically. Exported because the
+ * same list, uncapped and grouped (`groupServiceSteps`), rides beside `next[]`
+ * as `serviceSteps` — one derivation, so the two can never disagree about
+ * what a service owes.
+ */
+export function perServiceSteps(services, adoptedBinding) {
+    // The per-service rungs are collected as one list because the partition
+    // below acts on them as a group — and only on them. Where the list goes is
+    // the caller's: `fleetNext` puts it after every feature, and 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 = [];
+    // `adoption: partial` is one feature's slice archived into a service never
+    // adopted (SCHEMA.md); the file's presence used to discharge this rung.
+    for (const s of services.filter((x) => undocumented(x) || x.adoption !== null)) {
+        perService.push({
+            code: "next.adopt",
+            statement: undocumented(s)
+                ? `${serviceTreePath(s)}/ has no spec.md — nothing about ${s.id} is written down, so no feature can be graded against it.`
+                : `${serviceTreePath(s)}/spec.md is adoption: partial — it holds what an archived feature added, nothing of what ${s.id} already did.`,
+            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.adoption === null && !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,
+        });
+    }
+    // A vouch the document has moved out from under. `content.stale` needs
+    // nothing but the document, so unlike `sources.stale` this form CAN see it —
+    // and before it looked, a fleet whose specs were edited after the person read
+    // them got `next.fleet-clean`: "nothing is owed" over words nobody had
+    // re-read, while `loam validate` warned about each one. The re-vouch is a
+    // person's act from that service's own repository (`loam vouch` restamps the
+    // code side too), so the step names the documents and that repository, and
+    // its execution contract is a human review rather than a command to run.
+    for (const s of services.filter((x) => vouched(x) && x.contentStale.length > 0)) {
+        const files = s.contentStale.map((file) => `${serviceTreePath(s)}/${file}`);
+        perService.push({
+            code: "next.revouch",
+            statement: `${files.join(" and ")} changed since ${s.id} was vouched — \`status: verified\` stands over words nobody has re-read (content.stale). ` +
+                `A person re-reads what moved (\`loam vouch --pack --service ${s.id}\` lists it) and re-vouches from ${s.id}'s own repository.`,
+            command: `loam vouch --service ${s.id}`,
+            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 steps print, and in
+    // the ten-repo case WORKFLOW.md describes every developer's `loam status`
+    // listed nine other services' adoption work ahead of their own; 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.
+    return adoptedBinding === null
+        ? perService
+        : [
+            ...perService.filter((s) => s.service === adoptedBinding),
+            ...perService.filter((s) => s.service !== adoptedBinding),
+        ];
+}
+/**
+ * `perServiceSteps` grouped by code, in first-appearance order — the
+ * `serviceSteps` payload. `command` is the FIRST service's step command, so a
+ * reader folding forty rungs into one line still gets a literal to run rather
+ * than a second spelling of it.
+ */
+export function groupServiceSteps(steps) {
+    const groups = new Map();
+    for (const step of steps) {
+        if (step.service === undefined)
+            continue;
+        const group = groups.get(step.code) ?? { code: step.code, services: [], command: step.command };
+        group.services.push(step.service);
+        groups.set(step.code, group);
+    }
+    return [...groups.values()];
+}
+//# 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: the steps about the repository itself\n * first, then every feature in flight, then each service's adoption gaps,\n * most-unblocking first, capped so the list stays navigation rather than\n * 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 { featureLabel, fleetStageWords } from \"../feature/words.js\";\nimport {\n  undocumented,\n  vouched,\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 verified feature, ready to\n * archive, comes before one that still needs authoring, because archiving it\n * 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   * The active features whose `specs/` introduce it (`introducingFeatures`) —\n   * empty unless `adopted` is false. A service a feature in flight introduces\n   * has no code to adopt yet: the work in its repository IS that feature.\n   */\n  introducedBy: string[];\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  // The features that bring the bound service into being, when any in flight\n  // do. Their steps lead and the feature loop below skips them, so a feature\n  // this repository exists for is named once, first — EVERY one of them, since\n  // whichever archives first is the one that makes the service living.\n  const introducing = unadoptedBinding === null ? [] : features.filter((f) => binding!.introducedBy.includes(f.id));\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  //\n  // Unless a feature in flight INTRODUCES the service. Then there is no code\n  // yet for `loam adopt` to read — the feature's own specs/ ARE its documents\n  // until it archives — and telling its first developer to adopt it sent them\n  // to describe an empty repository. The step is the feature's, under the code\n  // the feature loop already emits, so nothing new needs branching on.\n  for (const f of introducing) {\n    const others = introducing.filter((o) => o !== f).map((o) => o.id);\n    steps.push({\n      code: \"next.feature\",\n      statement:\n        `This repository's loam.json says it is '${unadoptedBinding}', which ${f.id} introduces` +\n        (others.length > 0 ? ` (so does ${others.join(\", \")})` : \"\") +\n        ` — it is not in the living docs until ${others.length > 0 ? \"one of them\" : f.id} archives, so there is ` +\n        `nothing to adopt; ${f.id}'s own status says what this repository owes it.`,\n      command: `loam status ${f.id} --json`,\n    });\n  }\n  if (unadoptedBinding !== null && introducing.length === 0) {\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 with the service agent profile, then commit the \" +\n          \"loam.json it writes.\",\n        // `--agent-profile service`, because the default is `full`, and `full`\n        // writes loam-feature and loam-ship into the service checkout — the two\n        // workflows this docs repo keeps, which README tells every service\n        // repo to leave out. An agent runs this literal, not the README.\n        command: \"loam init --docs <path-to-this-docs-repo> --service <service-id> --agent-profile service\",\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  // Features BEFORE the per-service rungs. The rungs used to lead, on the\n  // reading that an adoption gap blocks grading — and on a fleet mid-adoption\n  // that put a page of `next.adopt` lines ahead of the one feature anybody was\n  // working on, and the cap below elided that feature as \"more step(s) of the\n  // same kinds\": the only change in flight, invisible under the heading\n  // \"next\". A feature is work somebody started; an undocumented service is\n  // backlog. The rungs still follow, and still in full where it matters —\n  // `serviceSteps` beside this list carries every one of them uncapped.\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 (introducing.includes(f)) continue;\n    const label = featureLabel(f);\n    if (f.stage === \"done\") {\n      steps.push({\n        code: \"next.archive\",\n        statement: `${label} is authored and verified — archive it to fold its deltas into the living docs, 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        //\n        // And never the bare stage word: \"FEAT-1 is at 'ready'\" over a feature\n        // with nothing built read as ready to ship. `stageWords` is the one\n        // place the human sentence for a stage lives (../feature/words.ts).\n        f.stage === \"blocked\" && interrupted === null && f.blockedBy.length > 0\n          ? `${label} is waiting on ${f.blockedBy.join(\", \")}.`\n          : `${label}: ${fleetStageWords(f, interrupted !== null)}.`,\n      command: `loam status ${f.id} --json`,\n    });\n  }\n\n  steps.push(...perServiceSteps(services, adoptedBinding));\n\n  const left = steps.slice(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 (left.length > 0) {\n    // Which kinds, counted: \"of the same kinds\" told a reader nothing about\n    // whether the feature they came for was among the missing.\n    const kinds = [...new Set(left.map((s) => s.code))].map((code) => `${left.filter((s) => s.code === code).length} ${code}`);\n    out.push({\n      code: \"next.elided\",\n      statement: `${left.length} more step(s) were left out (${kinds.join(\", \")}) — 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\n/**\n * Every per-service rung, in the order the list prints them: the bound\n * service's own first, then the rest alphabetically. Exported because the\n * same list, uncapped and grouped (`groupServiceSteps`), rides beside `next[]`\n * as `serviceSteps` — one derivation, so the two can never disagree about\n * what a service owes.\n */\nexport function perServiceSteps(services: ServiceEntry[], adoptedBinding: string | null): NextStep[] {\n  // The per-service rungs are collected as one list because the partition\n  // below acts on them as a group — and only on them. Where the list goes is\n  // the caller's: `fleetNext` puts it after every feature, and nothing here may\n  // float above `next.adopt-bound` or the first-hour ladder, both of which are\n  // about the repository rather than about any one service in the fleet.\n  const perService: NextStep[] = [];\n  // `adoption: partial` is one feature's slice archived into a service never\n  // adopted (SCHEMA.md); the file's presence used to discharge this rung.\n  for (const s of services.filter((x) => undocumented(x) || x.adoption !== null)) {\n    perService.push({\n      code: \"next.adopt\",\n      statement: undocumented(s)\n        ? `${serviceTreePath(s)}/ has no spec.md — nothing about ${s.id} is written down, so no feature can be graded against it.`\n        : `${serviceTreePath(s)}/spec.md is adoption: partial — it holds what an archived feature added, nothing of what ${s.id} already did.`,\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.adoption === null && !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  // A vouch the document has moved out from under. `content.stale` needs\n  // nothing but the document, so unlike `sources.stale` this form CAN see it —\n  // and before it looked, a fleet whose specs were edited after the person read\n  // them got `next.fleet-clean`: \"nothing is owed\" over words nobody had\n  // re-read, while `loam validate` warned about each one. The re-vouch is a\n  // person's act from that service's own repository (`loam vouch` restamps the\n  // code side too), so the step names the documents and that repository, and\n  // its execution contract is a human review rather than a command to run.\n  for (const s of services.filter((x) => vouched(x) && x.contentStale.length > 0)) {\n    const files = s.contentStale.map((file) => `${serviceTreePath(s)}/${file}`);\n    perService.push({\n      code: \"next.revouch\",\n      statement:\n        `${files.join(\" and \")} changed since ${s.id} was vouched — \\`status: verified\\` stands over words nobody has re-read (content.stale). ` +\n        `A person re-reads what moved (\\`loam vouch --pack --service ${s.id}\\` lists it) and re-vouches from ${s.id}'s own repository.`,\n      command: `loam vouch --service ${s.id}`,\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 steps print, and in\n  // the ten-repo case WORKFLOW.md describes every developer's `loam status`\n  // listed nine other services' adoption work ahead of their own; past ten\n  // services the one rung this developer can actually act on was elided\n  // entirely, leaving a list of nothing but other people's boundaries under\n  // the heading \"next\". No new code is emitted for any of this — `next[]` has\n  // always been documented as most-unblocking first, and this is the line that\n  // makes the claim true from where the reader is standing.\n  return adoptedBinding === null\n    ? perService\n    : [\n        ...perService.filter((s) => s.service === adoptedBinding),\n        ...perService.filter((s) => s.service !== adoptedBinding),\n      ];\n}\n\n/**\n * `perServiceSteps` grouped by code, in first-appearance order — the\n * `serviceSteps` payload. `command` is the FIRST service's step command, so a\n * reader folding forty rungs into one line still gets a literal to run rather\n * than a second spelling of it.\n */\nexport function groupServiceSteps(steps: NextStep[]): Array<{ code: string; services: string[]; command: string }> {\n  const groups = new Map<string, { code: string; services: string[]; command: string }>();\n  for (const step of steps) {\n    if (step.service === undefined) continue;\n    const group = groups.get(step.code) ?? { code: step.code, services: [], command: step.command };\n    group.services.push(step.service);\n    groups.set(step.code, group);\n  }\n  return [...groups.values()];\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

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/core/status/report.ts"],"names":[],"mappings":"AAqFA,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAG3F;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,OAAO;IACP,cAAc;IACd,MAAM;IACN,WAAW;IACX,SAAS;IACT,UAAU;IACV,cAAc;CACN,CAAC;AA0RX,+FAA+F;AAC/F,MAAM,UAAU,YAAY,CAAC,CAAe;IAC1C,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,OAAO,CAAC,CAAe;IACrC,OAAO,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;AACtD,CAAC","sourcesContent":["/**\n * Where does this work stand, and what is the next thing to do?\n *\n * Every other command answers a question you already know how to ask: validate\n * grades a target you name, delta briefs a service you name, verify checks a\n * feature you name. The one thing loam could not answer was the question an\n * agent asks FIRST — the one it has when it joins a repository halfway, or\n * comes back after losing its session. That knowledge existed, but only as\n * prose inside the slash commands (\"1. scaffold, 2. author, 3. validate\"),\n * which is to say it existed for whoever had read them recently and for nobody\n * else.\n *\n * The obvious implementation is a state file — a `.loam/state.json` recording\n * which step each feature reached. It is rejected here for the reason core/verify/\n * refuses a second mutable database: the moment a second record of the truth\n * exists, an author who edits a file by hand, a merge, a rebase or a\n * `git checkout` desynchronises it, and the state file's answer is confidently\n * wrong exactly when somebody trusts it. So `status` stores nothing and caches\n * nothing. It is a projection: every invocation re-derives the whole answer\n * from the files, and a file edited in another window is visible on the next\n * run with no invalidation step for anyone to forget.\n *\n * It also grades nothing itself. Every verdict here is somebody else's\n * function: `featureCoherence` (what `loam archive` refuses on) plus\n * `featureProvenance` and `requirementsMissingScenarios` (`loam validate\n * --feature`'s other error sources, as far as they exist as shared functions),\n * and `readVerificationState` + `featureChecklist`, the pair `loam verify`\n * uses. A second opinion about whether a feature holds together would be a\n * second answer to grade a pull request against, and the one a reader consults\n * is never the one the gate obeys (doctor.ts learnt this with its own config\n * validator). A check that lives inline inside `validate` cannot be inherited\n * at all, which is why `stage` never rests on `checks.coherent` alone.\n *\n * Which is why the rule this module is held to is one-directional: **status may\n * be more pessimistic than the gates, never greener.** `validate` and `archive`\n * answer two different questions — is the DOCUMENT valid, is the MERGE safe\n * (issue.ts) — and a projection that reported only one of them told an author\n * \"ship it\" about a feature the other one refuses. So `stage` and `next[]` take\n * the UNION: an error `validate` grades and a warning `archive` gates on both\n * make a feature `draft`, and test/status-agrees-with-gate.test.ts holds the\n * direction on a matrix of deliberately-damaged trees.\n *\n * ## The status vocabulary\n *\n * Five values, closed, and an agent is expected to branch on them:\n *\n *   `missing`  the artifact is owed and is not on disk; nothing stands in the\n *              way of writing it now.\n *   `blocked`  the work is stalled on something that is NOT this artifact — an\n *              artifact it is derived from is absent, or another feature in\n *              flight has to archive first.\n *   `draft`    it is on disk and the shared checks report an error against it:\n *              what exists is wrong.\n *   `ready`    it is on disk and clean, but its obligation is not discharged —\n *              something outside the documents (code, a test run, a recording)\n *              still has to answer it.\n *   `done`     nothing is owed here — and for an ARCHIVED feature, only that:\n *              archive checks documents, never code or evidence, so whether\n *              it was verified is `verification`'s answer, not this one.\n *\n * These are branching values, not sentences: the human view prints them in\n * words with the counts beside them (`feature/words.ts`), because a bare\n * `ready` over a feature with nothing built read as \"ready to ship\".\n *\n * The two pairs that look alike are the point of the set. `missing` and\n * `blocked` both mean \"not written\", and they are different instructions: one\n * says write it now, the other says you cannot yet and names what comes first —\n * an agent that cannot tell them apart authors a verification record against a\n * checklist that does not exist. `draft` and `ready` both mean \"on disk\", and\n * they are different instructions too: `draft` says the document is wrong and\n * the fix is in this repository, `ready` says the document is right and the\n * world has not caught up — the code is not built, or the claims are not\n * answered. Collapsing those two would send an agent to re-edit a spec that is\n * already correct.\n *\n * A value unreachable in a scope is simply never emitted there, deliberately:\n * the fleet form never says `draft`, because grading is a per-feature cost it\n * refuses to pay.\n */\nimport type { ServiceEntry } from \"../repo/entries.js\";\nimport type { UseCaseBlastRadius } from \"../usecases/touch.js\";\nimport type { AnsweredBy } from \"../verify/answers.js\";\nimport type { VerificationVerdict } from \"../verify/record.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\n\n/** The closed set. The module header says what each value instructs. */\nexport const ARTIFACT_STATUSES = [\"missing\", \"blocked\", \"draft\", \"ready\", \"done\"] as const;\nexport type ArtifactStatus = (typeof ARTIFACT_STATUSES)[number];\n\n/**\n * The artifact kinds a feature can owe, in the order the cycle authors them.\n * `spec`, `arch-spec`, `openapi` and `asyncapi` are per-service and repeat\n * once per service the feature touches; `capabilities` repeats once per\n * capability document the feature's delta carries; the rest are feature-wide.\n *\n * `capabilities` sits where an analyst writes it — the business promise comes\n * before the services that keep it, and a capability-only feature is a real and\n * ordinary first commit.\n */\nexport const ARTIFACT_IDS = [\n  \"intent\",\n  \"delta\",\n  \"capabilities\",\n  \"spec\",\n  \"arch-spec\",\n  \"openapi\",\n  \"asyncapi\",\n  \"verification\",\n] as const;\nexport type ArtifactId = (typeof ARTIFACT_IDS)[number];\n\nexport interface ArtifactState {\n  id: ArtifactId;\n  /** The service this artifact belongs to, or null for the feature-wide ones. */\n  service: string | null;\n  /**\n   * The capability this artifact belongs to, on `capabilities` rows only.\n   *\n   * A field of its own rather than a capability id put in `service`: the two\n   * are different namespaces — a fleet may hold a service and a capability of\n   * one name — and bending a published field to carry the other kind is how a\n   * consumer grouping by service silently acquires a row that is not one. Absent\n   * on every other row, so nothing that reads `service` today changes.\n   */\n  capability?: string;\n  /** Repo-relative with forward slashes — diffable across machines, like every path in the contract. */\n  path: string;\n  exists: boolean;\n  /**\n   * Whether ABSENCE is a defect. False for the artifacts a feature may\n   * legitimately not have: `delta.likec4` (a requirements-only change deletes\n   * it), `arch.spec.md` and `asyncapi.yaml` (optional everywhere), and\n   * `openapi.yaml` for a service\n   * the living docs already carry. An absent optional artifact is `done` —\n   * nothing is owed — and `exists: false` beside it is how a reader tells that\n   * from a file that is present and fine.\n   */\n  required: boolean;\n  status: ArtifactStatus;\n  /** Artifact ids that must come first. Non-empty only when `status` is `blocked`. */\n  blockedBy: string[];\n}\n\nexport interface NextStep {\n  /** Stable — prose may change, this may not. */\n  code: string;\n  /** One sentence, actionable without reading any other field. */\n  statement: string;\n  /** The literal command to run. */\n  command: string;\n  artifact?: ArtifactId;\n  service?: string;\n  /** The repo-relative file the step is about, when it names one. */\n  path?: string;\n}\n\nexport type NextActionKind = \"command\" | \"edit\" | \"external-repo\" | \"human-review\";\nexport type NextActionCwd = \"configured-repo\" | \"docs-repo\" | \"service-repo\";\n\n/**\n * The machine contract beside the legacy `NextStep.command` string.\n *\n * `command` exists only when every argument is concrete. An edit names the\n * file and puts the old command in `after`, because that command grades the\n * authored work rather than performing it. `needs` is data the caller must\n * obtain; it is never smuggled into a shell-looking placeholder.\n */\nexport interface NextExecution {\n  kind: NextActionKind;\n  runnable: boolean;\n  cwd: NextActionCwd;\n  command?: string;\n  after?: string;\n  needs?: string[];\n}\n\nexport type ExecutableNextStep = NextStep & { execution: NextExecution };\n\n/**\n * What the record beside the feature says, without asking whether anyone should\n * believe the code. `stale` is its own state and not merely \"recorded\": the\n * feature moved after the answers were written, so the record answers questions\n * that are no longer the ones being asked — which is exactly why `loam verify\n * --record` refuses to merge into it.\n */\nexport interface VerificationState {\n  state: \"absent\" | \"unreadable\" | \"stale\" | \"recorded\";\n  /** The day the record was written, when there is a readable one. */\n  recorded: string | null;\n  /**\n   * `verify --json`'s own three-valued verdict, through `verificationVerdict` —\n   * not a fourth opinion computed here. `attested` is the one that matters to a\n   * reader of this command: complete, and resting on somebody's word about a\n   * test rather than on a run.\n   */\n  verdict: VerificationVerdict;\n  /** Every count below is `tallyRecord` — the record's `claims:` array, never its `summary:` block. */\n  claims: number;\n  confirmed: number;\n  unconfirmed: number;\n  /** Federated records only: claims nobody has answered yet. */\n  unanswered: number;\n  /** Of the confirmed, the scenario claims on an agent's word (`attestedClaims`). */\n  attested: number;\n  /**\n   * Of the confirmed, one count per `answered_by` value (`confirmedProvenance`),\n   * every key present — `list --json`'s `answered`, under the same name. A\n   * different question from `attested`: that one asks only about the scenario\n   * claims the verdict turns on, this one who answered EVERY kind, so a record\n   * `verified` on its scenarios can still say six of its answers were an\n   * agent's word about a permission or an edge.\n   */\n  answered: Record<AnsweredBy, number>;\n}\n\n/**\n * A `loam archive`/`unarchive` that was killed mid-commit, read off the intent\n * journal `.loam-commit` leaves in the docs repo.\n *\n * It belongs in a projection that grades nothing because it is not a grade: it\n * is the one repository state where every OTHER answer this command gives is\n * about files that may be half-written. `doctor` blocks on it; `status` is what\n * an agent runs first, and it reported `done` over a half-merged repo — so it\n * says so too, from the same journal, and leads its steps with the repair.\n *\n * Read, never repaired: recovery happens under the docs lock inside `archive`\n * and `unarchive`, and `status` writes nothing and takes no lock.\n */\nexport interface InterruptedCommit {\n  /**\n   * Which command was committing, or null when the journal cannot be read at\n   * all. A sentence for a human, never a branch: version-2 journals carry any\n   * writer's name (rebase, vouch, new, gherkin), so an enum here would be a\n   * list this type has to chase.\n   */\n  command: string | null;\n  feature: string | null;\n  /** Who and when, so a human can place it against their own shell history. */\n  host: string | null;\n  pid: number | null;\n  at: string | null;\n  /** Docs-repo-relative paths that may hold half-written bytes. */\n  files: string[];\n  /** `.loam-commit` exists but does not parse — the worst case, because nothing can grade it. */\n  unreadable: boolean;\n  /** The command that recovers, or null when only a human can. */\n  recover: string | null;\n}\n\nexport interface FeatureStatusReport {\n  /**\n   * A killed commit in this docs repo, or null. Present on both forms: it is a\n   * fact about the repository, and every artifact row below it is a fact about\n   * files that repository may have half-written.\n   */\n  interrupted: InterruptedCommit | null;\n  feature: {\n    id: string;\n    /** intent.md's title, for a person (`featureTitle`); null when it names none. Additive. */\n    title: string | null;\n    dirName: string;\n    path: string;\n    archived: boolean;\n    /** The feature's own rollup, from the same vocabulary as its artifacts. */\n    stage: ArtifactStatus;\n    /** Every service the feature touches, whatever `--service` narrowed the view to. */\n    services: string[];\n    /** Active features that must archive before this one, from the dependency index. */\n    blockedBy: string[];\n  };\n  /** The `--service` narrowing, or null when the whole feature is in view. */\n  service: string | null;\n  artifacts: ArtifactState[];\n  /**\n   * The grade, from the same calls the two gates make: `featureCoherence`\n   * (archive), plus `featureProvenance` and the scenario-coverage check — the\n   * error sources `validate --feature` shares as functions. `ran` is false for\n   * an archived feature: its delta is already merged into the living docs, so\n   * re-grading it would compare a change against a world that has absorbed it.\n   */\n  checks: {\n    ran: boolean;\n    /**\n     * No error among the findings above — `loam validate --feature`'s verdict\n     * for every error source that is a shared function. It is not on its own\n     * what makes a feature shippable: `stage` and `next[]` take the union with\n     * archive's gating set, because a warning that gates is a warning this\n     * field reports as coherent.\n     */\n    coherent: boolean;\n    errors: number;\n    warnings: number;\n    /**\n     * Findings carrying `gates: true` — archive's judgement calls, which `--approve` overrides. Not\n     * every refusal: its pre-plan ones (unknown service, bad specs/ name, conflict markers) are errors.\n     */\n    gating: number;\n    /**\n     * Findings, not Issues: the set is wider than coherence now, and `gates` is\n     * resolved on every coherence finding so a consumer never re-implements the\n     * severity default. One breach reported by `validate` and by `status` has\n     * to arrive in one shape.\n     */\n    issues: Finding[];\n  };\n  verification: VerificationState;\n  /**\n   * How many claims the feature's checklist asks NOW, or null for an archived\n   * feature (frozen history: nothing is re-derived). Additive. With no record\n   * every count in `verification` is zero, and \"0 of 0\" is not what an\n   * unverified feature with nineteen promises is.\n   */\n  checklist: { claims: number } | null;\n  /**\n   * The declared business flows the services IN VIEW are hops of — blast\n   * radius, and the only field here that is a fact about the fleet rather than\n   * about the feature.\n   *\n   * It narrows with `--service` exactly as `artifacts` and `next` do, because\n   * `--service` is a lens on what the reader is being asked to do next. What it\n   * must never do is go silently empty: `unreadable` is how it says that\n   * `architecture/` could not be read, which is a different fact from a fleet\n   * that draws no use cases and produces the identical empty list.\n   *\n   * The FLEET form has no equivalent, deliberately. That form grades nothing and\n   * is coarse by design, and a per-feature flow join over every feature in flight\n   * is exactly the per-feature cost it refuses to pay.\n   */\n  useCases: UseCaseBlastRadius;\n  next: NextStep[];\n}\n\nexport interface FleetFeatureState {\n  id: string;\n  /** See {@link FeatureStatusReport.feature}'s `title`. */\n  title: string | null;\n  dirName: string;\n  path: string;\n  stage: ArtifactStatus;\n  services: string[];\n  blockedBy: string[];\n  /** Artifacts the feature owes and has not written. Presence only — the fleet form grades nothing. */\n  missing: string[];\n  verification: VerificationState;\n}\n\nexport interface FleetStatusReport {\n  /** See {@link FeatureStatusReport.interrupted}. */\n  interrupted: InterruptedCommit | null;\n  /**\n   * Three disjoint buckets over `services/`, summing to `total`. Deliberately\n   * coarser than `list`'s maturity ladder, and deliberately not the same words:\n   * that ladder grades an adoption campaign rung by rung, this asks only\n   * whether there is anything here to build a feature on.\n   */\n  services: {\n    total: number;\n    /** No `spec.md` — nothing about this service is written down. */\n    undocumented: number;\n    /** Documented, with no vouch stamp behind it. */\n    draft: number;\n    /** `status: verified` with a `sources_digest` — a person stood behind it. */\n    vouched: number;\n    /**\n     * Of `vouched`, the ones read from a recorded SAMPLE rather than in full\n     * (`vouch_scope`, either axis) — a SUBSET: the three above still sum to `total`.\n     */\n    sampledVouched: number;\n    /**\n     * Of `vouched`, the ones with a stamped document whose words moved after\n     * the vouch (`content.stale`, either axis) — a SUBSET like\n     * `sampledVouched`, and each one is a `next.revouch` step below.\n     */\n    contentStale: number;\n  };\n  features: FleetFeatureState[];\n  /** Dependencies before consumers — which feature has to archive first. */\n  order: string[];\n  service: string | null;\n  next: NextStep[];\n  /**\n   * Every per-service rung (`next.adopt`, `next.complete-service`,\n   * `next.revouch`), UNCAPPED and grouped by code, services in `next[]` order.\n   * Additive. `next[]` stops at ten, so mid-adoption it cannot say how much\n   * adoption work there is; this can, and the human view folds it into one\n   * counted line under the features.\n   */\n  serviceSteps: Array<{ code: string; services: string[]; command: string }>;\n}\n\n/** Nothing is written down: no living spec at all. Every other absence is partial adoption. */\nexport function undocumented(s: ServiceEntry): boolean {\n  return !s.has.spec;\n}\n\n/** A person stamped it — `loam vouch`'s exact postcondition, read back off the frontmatter. */\nexport function vouched(s: ServiceEntry): boolean {\n  return s.status === \"verified\" && s.sources.stamped;\n}\n"]}

package/dist/core/status/scan.js

@@ -0,0 +1,41 @@
+/**
+ * Reading a feature's per-service deltas without grading them. Both status
+ * forms draw on this one scan: it is how the artifact table and the fleet form
+ * decide which services owe a contract, and where the scenario steps come from.
+ */
+import { existsSync } from "node:fs";
+import { requirementsMissingScenarios } from "../document/scenarios.js";
+import {} from "../document/spec.js";
+import { repoPath } from "../envelope/json.js";
+import { featureSpecPaths, SPEC_AXES } from "../repo/paths.js";
+export async function scanDeltas(docsDir, feature, services, context) {
+    const out = [];
+    for (const svc of services) {
+        const p = featureSpecPaths(feature.dir, svc);
+        // SPEC_AXES already carries the prose name of each axis — "requirements"
+        // and "arch requirements" are its `label`s verbatim — so the pair is read
+        // from there rather than spelled again, and a service's status can never
+        // walk a different set of spec files than its validation does.
+        for (const [file, label] of SPEC_AXES.map((axis) => [p[axis.key], `${svc}: ${axis.label}`])) {
+            if (!existsSync(file))
+                continue;
+            const reqs = await context.readRequirements(file);
+            out.push({
+                service: svc,
+                path: repoPath(docsDir, file),
+                label,
+                bare: requirementsMissingScenarios(reqs),
+                scenarios: reqs.reduce((n, r) => n + r.scenarios.length, 0),
+                operations: file === p.spec
+                    ? reqs.filter((r) => r.kind !== "REMOVED").reduce((n, r) => n + r.operations.length, 0)
+                    : 0,
+            });
+        }
+    }
+    return out;
+}
+/** Services this feature sends at least one operation to — see contracts.ts's `owesContract`. */
+export function governedServices(scans) {
+    return new Set(scans.filter((s) => s.operations > 0).map((s) => s.service));
+}
+//# sourceMappingURL=scan.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../../src/core/status/scan.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAoB,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAyB/D,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAgB,EAChB,OAAqB,EACrB,QAA2B,EAC3B,OAAqB;IAErB,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC7C,yEAAyE;QACzE,0EAA0E;QAC1E,yEAAyE;QACzE,+DAA+D;QAC/D,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,SAAS,CAAC,GAAG,CACvC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,IAAI,CAAC,KAAK,EAAE,CAAU,CAC1D,EAAE,CAAC;YACF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,SAAS;YAChC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAClD,GAAG,CAAC,IAAI,CAAC;gBACP,OAAO,EAAE,GAAG;gBACZ,IAAI,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;gBAC7B,KAAK;gBACL,IAAI,EAAE,4BAA4B,CAAC,IAAI,CAAC;gBACxC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC3D,UAAU,EACR,IAAI,KAAK,CAAC,CAAC,IAAI;oBACb,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;oBACvF,CAAC,CAAC,CAAC;aACR,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,gBAAgB,CAAC,KAA2B;IAC1D,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9E,CAAC","sourcesContent":["/**\n * Reading a feature's per-service deltas without grading them. Both status\n * forms draw on this one scan: it is how the artifact table and the fleet form\n * decide which services owe a contract, and where the scenario steps come from.\n */\nimport { existsSync } from \"node:fs\";\nimport { requirementsMissingScenarios } from \"../document/scenarios.js\";\nimport { type Requirement } from \"../document/spec.js\";\nimport { repoPath } from \"../envelope/json.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { FeatureEntry } from \"../repo/entries.js\";\nimport { featureSpecPaths, SPEC_AXES } from \"../repo/paths.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\n\n/**\n * One read of each per-service delta, answering the three questions the two\n * status forms ask of it: which requirements carry no scenario (via the same\n * `requirementsMissingScenarios` every coverage check calls — REMOVED\n * requirements are exempt there and stay exempt here, content on its way out\n * owes no acceptance criteria), how many scenarios there are to generate a\n * suite from, and whether the delta governs any operation at all — which is\n * what decides whether the service is owed a contract.\n */\nexport interface DeltaScan {\n  service: string;\n  /** Repo-relative, and the file the steps point at. */\n  path: string;\n  /** validate's own label for this axis: `<svc>: requirements` / `<svc>: arch requirements`. */\n  label: string;\n  bare: Requirement[];\n  scenarios: number;\n  /** Operations the non-REMOVED requirements govern. `spec.md` only, like coherence's own `reqOps`. */\n  operations: number;\n}\n\nexport async function scanDeltas(\n  docsDir: DocsDir,\n  feature: FeatureEntry,\n  services: PathableService[],\n  context: FleetContext,\n): Promise<DeltaScan[]> {\n  const out: DeltaScan[] = [];\n  for (const svc of services) {\n    const p = featureSpecPaths(feature.dir, svc);\n    // SPEC_AXES already carries the prose name of each axis — \"requirements\"\n    // and \"arch requirements\" are its `label`s verbatim — so the pair is read\n    // from there rather than spelled again, and a service's status can never\n    // walk a different set of spec files than its validation does.\n    for (const [file, label] of SPEC_AXES.map(\n      (axis) => [p[axis.key], `${svc}: ${axis.label}`] as const,\n    )) {\n      if (!existsSync(file)) continue;\n      const reqs = await context.readRequirements(file);\n      out.push({\n        service: svc,\n        path: repoPath(docsDir, file),\n        label,\n        bare: requirementsMissingScenarios(reqs),\n        scenarios: reqs.reduce((n, r) => n + r.scenarios.length, 0),\n        operations:\n          file === p.spec\n            ? reqs.filter((r) => r.kind !== \"REMOVED\").reduce((n, r) => n + r.operations.length, 0)\n            : 0,\n      });\n    }\n  }\n  return out;\n}\n\n/** Services this feature sends at least one operation to — see contracts.ts's `owesContract`. */\nexport function governedServices(scans: readonly DeltaScan[]): ReadonlySet<string> {\n  return new Set(scans.filter((s) => s.operations > 0).map((s) => s.service));\n}\n"]}