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

package/dist/core/envelope/json.js

@@ -0,0 +1,209 @@
+/**
+ * The `--json` envelope — loam's machine contract.
+ *
+ * Every JSON response carries `ok`. Success spreads the payload alongside it;
+ * failure carries a stable `error.code` a caller can branch on without parsing
+ * prose. Errors go to stdout too: a consumer reads one stream and always gets
+ * valid JSON, whether the command succeeded or not. The exit code still tells
+ * the shell what happened.
+ *
+ * Three keys identify the envelope before its payload is read, and they answer
+ * three different questions: `contractVersion` is the SHAPE's version,
+ * `version` is the BINARY's, and `command` (on every success payload) says
+ * which verb produced it. The first two are stamped by the emitters below so
+ * no command can forget them; the third is the payload's own first key,
+ * because only the command knows its name.
+ *
+ * Key casing: camelCase, with one deliberate exception — a key that mirrors a
+ * frontmatter field verbatim keeps that field's snake_case spelling
+ * (`last_verified`, `sources_digest` in vouch's payload), so the envelope and
+ * the document it describes spell the same fact the same way. snake_case only
+ * where a key mirrors a frontmatter field verbatim; camelCase everywhere else.
+ */
+import { relative } from "node:path";
+import { loadConfig } from "./config.js";
+import { LOAM_VERSION } from "./version.js";
+/**
+ * Version of the top-level JSON envelope, independent of the CLI/package
+ * version. Additive payload fields do not require a bump; incompatible changes
+ * to `ok`, `error`, or their semantics do.
+ */
+export const JSON_CONTRACT_VERSION = "1.0";
+/**
+ * `version` is stamped HERE rather than by each command for the reason the
+ * `command` discriminator was not, and had to be retrofitted one call site at a
+ * time: a key every envelope owes is a key no command can be trusted to
+ * remember. Two lines in the two emitters give it to every command and every
+ * refusal at once, and a command added tomorrow cannot ship without it.
+ *
+ * Why a consumer needs it at all: `docs.binary-behind` exists to say that a
+ * green run from an old binary is worth less than it looks, and a caller
+ * holding only a `--json` payload could not tell which loam produced it — so it
+ * could not apply that caution, and could not see a mixed-version fleet in the
+ * contract. It sits beside `contractVersion`, never inside it: the envelope
+ * SHAPE and the binary that filled it version independently, and collapsing
+ * them would make every release look like a contract break.
+ */
+export function emitJson(payload) {
+    console.log(JSON.stringify({ contractVersion: JSON_CONTRACT_VERSION, version: LOAM_VERSION, ok: true, ...payload }, null, 2));
+}
+/** Paths in the contract are repo-relative, with forward slashes: diffable across machines. */
+export function repoPath(docsDir, abs) {
+    return relative(docsDir, abs).split(/[\\/]/).join("/");
+}
+/**
+ * Emit a failure envelope and set the exit code. Returns false, to `return`
+ * from a caller.
+ *
+ * `version` is on this path too, and deliberately: a refusal is the envelope a
+ * consumer is most likely to be holding at the moment it needs to know which
+ * binary answered — "this loam does not have that flag / that code" is a
+ * question about the build, and an unversioned refusal makes it unanswerable.
+ *
+ * There is no `command` here, and adding one is not a small change. The error
+ * emitter has no command in scope: `fail()` is called from deep inside core-ish
+ * helpers that never learn which verb the user typed, so threading it means
+ * either module-level mutable state — a hazard this codebase names outright,
+ * because a value cached at import time leaks across the forked test processes
+ * and across invocations in a long-running host — or one more argument threaded
+ * through `fail()`, `reportNoConfig()` and every deep helper that refuses, each
+ * of which would then carry a value it has no other use for. A consumer that
+ * needs to know which command refused already knows: it made the call.
+ */
+export function emitJsonError(code, message, details = {}) {
+    console.log(JSON.stringify({ contractVersion: JSON_CONTRACT_VERSION, version: LOAM_VERSION, ok: false, error: { code, message }, ...details }, null, 2));
+    process.exitCode = 1;
+    return false;
+}
+/**
+ * The refusals that print no `loam explain` pointer, each with the reason it is
+ * here. ONE named set rather than a condition per call site: "is this refusal
+ * worth looking up?" is a single question, and answering it in seven places is
+ * how two of them come to disagree.
+ *
+ * - `vouch-declined` — loam asked whether to stamp, and a person said no.
+ *   Nothing failed and there is nothing to fix, so a pointer would invite
+ *   somebody to go read the meaning of their own answer.
+ *
+ * `internal` was weighed and deliberately LEFT OUT. It is the one code with no
+ * stable meaning, which reads like a reason to stay silent — but its
+ * explanation carries the only instruction available to a person staring at an
+ * unexpected throw (a repeatable `internal` is a loam defect worth reporting),
+ * and that is worth more than the silence the old behaviour gave them.
+ *
+ * Exported so test/explain.test.ts can pin the membership: an entry added here
+ * silently removes a pointer nobody would notice was gone.
+ */
+export const NO_EXPLAIN_POINTER = new Set(["vouch-declined"]);
+/**
+ * The one-line pointer from a refusal to the command that explains it.
+ *
+ * Measured over eight wrong invocations a person makes in their first hour —
+ * no loam.json, an unknown service, an unknown feature, an unbound `gherkin`,
+ * a malformed feature id — every single one printed prose and no code, and
+ * only `loam validate` mentioned `loam explain` at all. `explain` is the best
+ * usability asset loam has and the message that most needs it could not reach
+ * it: to look a refusal up you first had to re-run the whole command with
+ * `--json` and read `error.code` out of the envelope, which is precisely the
+ * knowledge a first-hour user does not have. The code is printed as well as
+ * the invocation because the two are different needs: the bare code is what
+ * goes into a bug report, a grep or a CI branch, and the invocation is what
+ * answers it here.
+ *
+ * STDERR, never stdout, and that is the load-bearing half: a refusal's
+ * diagnostic must not pollute a piped payload. `loam show svc > out.json`
+ * already keeps its message off stdout, and a pointer that broke that rule
+ * would corrupt exactly the pipelines text mode was careful never to touch.
+ * (Findings do the opposite — their codes go to stdout with the report, in
+ * document order, for validate/report.ts's own reason. Same fact, two streams,
+ * because a finding is the answer and a refusal is the absence of one.)
+ *
+ * Nothing runs here under `--json`: the envelope already carries `error.code`
+ * as data, and a machine reader has no use for being told a second command
+ * exists — the same doctrine `EXPLAIN_FOOTER` follows in
+ * commands/policy/format.ts.
+ *
+ * No ANSI escape, though the line is meant to READ as dim. Nothing in this
+ * codebase emits escape sequences, the output is graded by tests that compare
+ * strings, and a colour that survives into a redirected file or a CI log is
+ * noise nobody asked for. The typography does the dimming: the code, a spaced
+ * middot, the command — an aside, not a sentence.
+ */
+export function sayExplain(code) {
+    if (NO_EXPLAIN_POINTER.has(code))
+        return;
+    console.error(`${code}  ·  loam explain ${code}`);
+}
+/**
+ * Report a failure in whichever mode the caller is in. Text mode goes to
+ * stderr as it always has — now with the code and its lookup on a second line;
+ * JSON mode goes into the envelope, whose stdout bytes are unchanged.
+ */
+export function fail(json, code, message) {
+    if (json) {
+        emitJsonError(code, message);
+        return;
+    }
+    console.error(message);
+    sayExplain(code);
+    process.exitCode = 1;
+}
+/**
+ * A refusal or failure with its stable `--json` code attached, for the commands
+ * whose refusals are THROWN — from a plan phase or a rollback path several
+ * calls below the one handler that prints — rather than returned. The handler
+ * `fail`s with `code`, so a merge that could not be computed reports as a merge
+ * failure rather than as `internal`. What anything ELSE that escapes means is
+ * each handler's to say. One class, because archive, unarchive and
+ * migrate-openspec had each written this same one.
+ */
+export class CodedFailure extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** The message every command prints when there is no loam.json. */
+const NO_CONFIG_MESSAGE = "No loam.json found. Run `loam init --docs <dir>` first.";
+/**
+ * The message the service-scoped commands print when neither `--service` nor
+ * loam.json names one. Four commands ask the same question and owe the same two
+ * answers, and a fifth would have been written by hand. `loam delta` keeps its
+ * own longer sentence on purpose — it can say which feature was being read.
+ */
+export const NO_SERVICE_MESSAGE = "No service. Pass --service <id> or set it in loam.json.";
+/**
+ * Report "no config" in whichever mode the caller is in — distinguishing a
+ * config that is absent from one that exists but would not load, because the
+ * two point at opposite fixes: a missing config wants `loam init`, a corrupt
+ * one wants repair, and `init` would silently rewrite the corrupt file. The
+ * distinction arrives as DATA on the load outcome rather than being re-derived
+ * from the filesystem here — the file could change between the load and a
+ * re-check, and the parse problem itself is worth showing.
+ */
+export function reportNoConfig(json, load) {
+    if (load.kind === "invalid") {
+        fail(json, "config-invalid", `Invalid loam.json: ${load.problem}. Fix it (or delete it and re-run \`loam init\`).`);
+        return;
+    }
+    fail(json, "no-config", NO_CONFIG_MESSAGE);
+}
+/**
+ * The config a command action stands on, or null once `reportNoConfig` has
+ * refused — the caller's whole answer to null is `return`. Every command that
+ * needs a wired repo opens with this question, and it was spelled as the same
+ * six lines in each of them; one spelling is what keeps the absent/invalid
+ * split above from being forgotten in a twenty-fourth. `init` and `doctor` do
+ * not come through here: a missing or broken config is their subject, not a
+ * reason to stop.
+ */
+export async function configOrRefuse(json) {
+    const loaded = await loadConfig();
+    if (loaded.kind !== "loaded") {
+        reportNoConfig(json, loaded);
+        return null;
+    }
+    return loaded.config;
+}
+//# sourceMappingURL=json.js.map

package/dist/core/envelope/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../../src/core/envelope/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,UAAU,EAAmB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AA0H3C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAgC;IACvD,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CAAC,EAAE,eAAe,EAAE,qBAAqB,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CACjH,CAAC;AACJ,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,GAAW;IACnD,OAAO,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAe,EACf,OAAe,EACf,OAAO,GAA4B,EAAE;IAErC,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CACZ,EAAE,eAAe,EAAE,qBAAqB,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,EAClH,IAAI,EACJ,CAAC,CACF,CACF,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACrB,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2B,IAAI,GAAG,CAAY,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,UAAU,CAAC,IAAe;IACxC,IAAI,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO;IACzC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,qBAAqB,IAAI,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,IAAa,EAAE,IAAe,EAAE,OAAe;IAClE,IAAI,IAAI,EAAE,CAAC;QACT,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC7B,OAAO;IACT,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvB,UAAU,CAAC,IAAI,CAAC,CAAC;IACjB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAE1B,IAAI;IADf,YACW,IAAe,EACxB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;oBAHN,IAAI;IAIf,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,iBAAiB,GAAG,yDAAyD,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,yDAAyD,CAAC;AAE5F;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAa,EAAE,IAA6E;IACzH,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CACF,IAAI,EACJ,gBAAgB,EAChB,sBAAsB,IAAI,CAAC,OAAO,mDAAmD,CACtF,CAAC;QACF,OAAO;IACT,CAAC;IACD,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAa;IAChD,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC","sourcesContent":["/**\n * The `--json` envelope — loam's machine contract.\n *\n * Every JSON response carries `ok`. Success spreads the payload alongside it;\n * failure carries a stable `error.code` a caller can branch on without parsing\n * prose. Errors go to stdout too: a consumer reads one stream and always gets\n * valid JSON, whether the command succeeded or not. The exit code still tells\n * the shell what happened.\n *\n * Three keys identify the envelope before its payload is read, and they answer\n * three different questions: `contractVersion` is the SHAPE's version,\n * `version` is the BINARY's, and `command` (on every success payload) says\n * which verb produced it. The first two are stamped by the emitters below so\n * no command can forget them; the third is the payload's own first key,\n * because only the command knows its name.\n *\n * Key casing: camelCase, with one deliberate exception — a key that mirrors a\n * frontmatter field verbatim keeps that field's snake_case spelling\n * (`last_verified`, `sources_digest` in vouch's payload), so the envelope and\n * the document it describes spell the same fact the same way. snake_case only\n * where a key mirrors a frontmatter field verbatim; camelCase everywhere else.\n */\nimport { relative } from \"node:path\";\nimport { loadConfig, type LoamConfig } from \"./config.js\";\nimport { LOAM_VERSION } from \"./version.js\";\n\n/**\n * Version of the top-level JSON envelope, independent of the CLI/package\n * version. Additive payload fields do not require a bump; incompatible changes\n * to `ok`, `error`, or their semantics do.\n */\nexport const JSON_CONTRACT_VERSION = \"1.0\";\n\n/**\n * Stable failure codes. Prose may change; these may not.\n *\n * The `sources-*` pair mirrors the `sources.*` finding codes on purpose: the\n * same breach is recognisable whether it arrives as a refusal from `vouch` or\n * as a finding from `validate`.\n *\n * The `feature-active` / `snapshot-*` group is `unarchive` refusing to guess:\n * each names a different reason the undo is not one, and a caller has to tell\n * them apart to know whether re-running could ever work. Its commit failures\n * split the same way archive's do: `restore-failed` means nothing was restored\n * or everything was rolled back — the living docs are unchanged and re-running\n * can work; `rollback-incomplete` (shared with archive, same meaning) means\n * some files could not be put back, and the message lists them.\n *\n * The `answers-*` group is `loam verify --record` refusing an answer set that\n * does not answer the current checklist. They are separated for the same reason:\n * an unreadable file is a bug in whatever wrote it, a mismatch means the feature\n * moved and the claims have to be answered again, and an unevidenced\n * confirmation is the one an agent can fix on the spot.\n *\n * The archive group is `loam archive` refusing or failing, and each code is a\n * different answer to \"what do I fix, and can I trust the repo?\": `not-coherent`\n * is the gate — issues in the FEATURE, carried in `issues[]`. Most yield to\n * `--approve`; the ones that do not name an illegal service id — a\n * `specs/<svc>/` directory name (`delta.service-id-invalid`) or a\n * `metadata { service }` binding (`c4.service-binding-invalid`) — because the\n * name IS the path the merge would write, and the fix is a rename, never a\n * flag. A consumer branches on data, not prose: coherence issues carry the\n * additive `overridable` key resolved per issue, and a refusal `--approve`\n * cannot move says \"--approve does not override this\" in `error.message`;\n * `living-outside-requirements` is the refusal whose fault is not the\n * feature's — the LIVING spec holds requirements outside `## Requirements`,\n * and the merge would duplicate them, so the fix is in the living docs, and\n * `--approve` does not move it either; `archive-exists` is a\n * destination collision under `features/archive/`; `merge-failed` is a merge\n * that could not be computed or was rolled back — either way the living docs\n * are unchanged; `rollback-incomplete` is the one that demands a human: the\n * merge failed AND some files could not be restored.\n *\n * `config-invalid` is distinct from `no-config` because the fixes point in\n * opposite directions: a missing config wants `loam init`, a corrupt one wants\n * repair — and an agent that ran `init` on a corrupt file would silently\n * rewrite it.\n *\n * `internal` is the one code with no stable meaning: an unexpected throw. It\n * exists so a `--json` consumer still receives an envelope instead of a stack\n * trace on stdout's sibling stream.\n */\nexport type ErrorCode =\n  | \"no-config\"\n  | \"config-invalid\"\n  | \"unknown-target\"\n  | \"invalid-option\"\n  | \"already-exists\"\n  | \"sources-absent\"\n  | \"sources-path-missing\"\n  | \"not-coherent\"\n  | \"living-outside-requirements\"\n  | \"archive-exists\"\n  | \"merge-failed\"\n  | \"rollback-incomplete\"\n  | \"feature-active\"\n  | \"snapshot-missing\"\n  | \"snapshot-stale\"\n  /** A snapshot pre-image whose bytes no longer match the digest archive recorded for them: `unarchive` will not restore text nobody wrote. */\n  | \"snapshot-corrupt\"\n  /** A `loam archive`/`unarchive` was killed mid-commit: the living docs are half-written, and this run refuses rather than writing over the evidence. */\n  | \"commit-interrupted\"\n  | \"restore-failed\"\n  | \"answers-unreadable\"\n  | \"answers-mismatch\"\n  | \"answers-unevidenced\"\n  | \"service-mismatch\"\n  | \"unknown-service\"\n  | \"repository-unavailable\"\n  /** `loam verify --record` without `--service` over a federated (schema 2) record: it would erase other repositories' attestations. */\n  | \"record-federated\"\n  /** A file of the verification record (`verification.yaml` or a `verification/<svc>.yaml`) that exists but cannot be read — never overwritten, never reported as absent. */\n  | \"record-unreadable\"\n  /** `loam verify --record` found the record changed between its locked read and the swap — an editor or a lock-ignoring writer landed first. Nothing was written; re-running merges over the record as it now stands. */\n  | \"record-raced\"\n  /** `loam gherkin <FEAT>` refusing to overwrite a `.feature` file owned by another feature still in flight. */\n  | \"gherkin-conflict\"\n  /** `loam vouch` found the spec changed under it between reading and stamping — another vouch or an edit landed first, and nothing was written. */\n  | \"vouch-raced\"\n  /** `loam vouch` with nothing on the other end of stdin and no `--yes`: the stamp is a person's claim, and nobody was asked. */\n  | \"vouch-unattended\"\n  /** `loam vouch` could not learn who is vouching — git names no `user.email` here, so the stamp would record a claim with nobody behind it. */\n  | \"vouch-unattributable\"\n  /** `loam vouch` was asked to confirm and the answer was no. Nothing was stamped; this is a successful refusal, not a failure. */\n  | \"vouch-declined\"\n  /** `docsDir` in loam.json points at nothing: the docs repo was never cloned, or the path is wrong. A read command refuses rather than reporting an empty fleet. */\n  | \"docs-missing\"\n  /** `docsDir` is a directory but has no `services/`: it is some other directory, most often the service repo itself after a typo. */\n  | \"services-missing\"\n  /** Another loam writer holds the docs repo's advisory lock: nothing was read or written, and re-running once it finishes works. `verify --record` waits out a short holder before giving this answer. */\n  | \"docs-busy\"\n  /** `loam subsystem rm` refusing a subsystem that still holds members — services or child subsystems, named in the message. A destructive command never picks targets the caller did not name: move them out (or remove the children) first, then re-run. */\n  | \"subsystem-not-empty\"\n  /** `loam subsystem move`/`rename` refusing because git reports uncommitted or untracked paths under a directory being moved, or in a document outside it whose links the move would rewrite — the ONLY move-specific refusal: the move would sweep them into a change nobody reviewed. Commit them, `git stash -u` (plain `stash` leaves untracked files behind), or remove them, then re-run. When git cannot answer at all the move proceeds — refusal needs positive evidence. */\n  | \"move-uncommitted\"\n  /** A subsystem move/rename failed and was rolled back cleanly: every rename undone, the generated views file restored, the docs unchanged — re-running can work. Distinct from `merge-failed` because no merge was computed; a failure that could NOT be fully undone is `rollback-incomplete`, exactly as for archive. */\n  | \"move-failed\"\n  /** `loam open` found no service checkout bound to this docs repo under any scanned root — the workspace would hold only the docs repo. Re-running can succeed once a bound checkout exists beside it, or with `--root` pointing where the checkouts live. */\n  | \"no-members\"\n  /** Two discovered repositories' committed loam.json files declare the same `service` for this docs repo — two checkouts of one service, or a copied config. loam will not guess which checkout speaks for the service; narrow the scan with `--root` or fix the stray binding, then re-run. */\n  | \"binding-duplicate\"\n  /** `loam list --owners` could not use the user-named CODEOWNERS file: the path cannot be read, or a line in it cannot be parsed as `pattern owner…` (the message names the line). Fail-closed like `answers-unreadable` for the other user-named file — a half-read ownership file must never file a service under the wrong team. Re-running succeeds once the path or the line is fixed. */\n  | \"owners-unreadable\"\n  /** `loam seed`'s fleet file is missing, unreadable, not YAML, the wrong shape, carries an illegal id or name, or no longer names every existing `services/<id>/` (that arm carries the additive `missingServices` payload key). The message names the file and, where one exists, the line; editing the file and re-running succeeds. */\n  | \"seed-file-invalid\"\n  /** fleet.yaml declares one name twice — as two services, or as both a service and an external/subsystem. Service ids, subsystem names and externals share one flat namespace (a call endpoint must name exactly one thing); the message names both declaration lines. Rename one and re-run. */\n  | \"seed-duplicate-service\"\n  /** A service's `subsystem:` in fleet.yaml names nothing `subsystems:` declares; the message carries a did-you-mean hint over the names the file really declares. Fix the spelling (or add the subsystem) and re-run. */\n  | \"seed-unknown-subsystem\"\n  /** architecture/landscape.likec4 carries hand edits (the line-1 stamp's digest no longer matches) or was authored some other way (no stamp, and not the scaffold's untouched stub). Seed never overwrites human work and nothing was written; re-running cannot succeed until the file is deleted, which loses nothing only while every edit is something fleet.yaml can say. Once an edge carries an op (which fleet.yaml cannot), the map grows through `loam adopt` and feature C4 deltas instead, never through seed again. */\n  | \"seed-landscape-edited\"\n  | \"internal\";\n\n/**\n * `version` is stamped HERE rather than by each command for the reason the\n * `command` discriminator was not, and had to be retrofitted one call site at a\n * time: a key every envelope owes is a key no command can be trusted to\n * remember. Two lines in the two emitters give it to every command and every\n * refusal at once, and a command added tomorrow cannot ship without it.\n *\n * Why a consumer needs it at all: `docs.binary-behind` exists to say that a\n * green run from an old binary is worth less than it looks, and a caller\n * holding only a `--json` payload could not tell which loam produced it — so it\n * could not apply that caution, and could not see a mixed-version fleet in the\n * contract. It sits beside `contractVersion`, never inside it: the envelope\n * SHAPE and the binary that filled it version independently, and collapsing\n * them would make every release look like a contract break.\n */\nexport function emitJson(payload: Record<string, unknown>): void {\n  console.log(\n    JSON.stringify({ contractVersion: JSON_CONTRACT_VERSION, version: LOAM_VERSION, ok: true, ...payload }, null, 2),\n  );\n}\n\n/** Paths in the contract are repo-relative, with forward slashes: diffable across machines. */\nexport function repoPath(docsDir: string, abs: string): string {\n  return relative(docsDir, abs).split(/[\\\\/]/).join(\"/\");\n}\n\n/**\n * Emit a failure envelope and set the exit code. Returns false, to `return`\n * from a caller.\n *\n * `version` is on this path too, and deliberately: a refusal is the envelope a\n * consumer is most likely to be holding at the moment it needs to know which\n * binary answered — \"this loam does not have that flag / that code\" is a\n * question about the build, and an unversioned refusal makes it unanswerable.\n *\n * There is no `command` here, and adding one is not a small change. The error\n * emitter has no command in scope: `fail()` is called from deep inside core-ish\n * helpers that never learn which verb the user typed, so threading it means\n * either module-level mutable state — a hazard this codebase names outright,\n * because a value cached at import time leaks across the forked test processes\n * and across invocations in a long-running host — or one more argument threaded\n * through `fail()`, `reportNoConfig()` and every deep helper that refuses, each\n * of which would then carry a value it has no other use for. A consumer that\n * needs to know which command refused already knows: it made the call.\n */\nexport function emitJsonError(\n  code: ErrorCode,\n  message: string,\n  details: Record<string, unknown> = {},\n): false {\n  console.log(\n    JSON.stringify(\n      { contractVersion: JSON_CONTRACT_VERSION, version: LOAM_VERSION, ok: false, error: { code, message }, ...details },\n      null,\n      2,\n    ),\n  );\n  process.exitCode = 1;\n  return false;\n}\n\n/**\n * The refusals that print no `loam explain` pointer, each with the reason it is\n * here. ONE named set rather than a condition per call site: \"is this refusal\n * worth looking up?\" is a single question, and answering it in seven places is\n * how two of them come to disagree.\n *\n * - `vouch-declined` — loam asked whether to stamp, and a person said no.\n *   Nothing failed and there is nothing to fix, so a pointer would invite\n *   somebody to go read the meaning of their own answer.\n *\n * `internal` was weighed and deliberately LEFT OUT. It is the one code with no\n * stable meaning, which reads like a reason to stay silent — but its\n * explanation carries the only instruction available to a person staring at an\n * unexpected throw (a repeatable `internal` is a loam defect worth reporting),\n * and that is worth more than the silence the old behaviour gave them.\n *\n * Exported so test/explain.test.ts can pin the membership: an entry added here\n * silently removes a pointer nobody would notice was gone.\n */\nexport const NO_EXPLAIN_POINTER: ReadonlySet<ErrorCode> = new Set<ErrorCode>([\"vouch-declined\"]);\n\n/**\n * The one-line pointer from a refusal to the command that explains it.\n *\n * Measured over eight wrong invocations a person makes in their first hour —\n * no loam.json, an unknown service, an unknown feature, an unbound `gherkin`,\n * a malformed feature id — every single one printed prose and no code, and\n * only `loam validate` mentioned `loam explain` at all. `explain` is the best\n * usability asset loam has and the message that most needs it could not reach\n * it: to look a refusal up you first had to re-run the whole command with\n * `--json` and read `error.code` out of the envelope, which is precisely the\n * knowledge a first-hour user does not have. The code is printed as well as\n * the invocation because the two are different needs: the bare code is what\n * goes into a bug report, a grep or a CI branch, and the invocation is what\n * answers it here.\n *\n * STDERR, never stdout, and that is the load-bearing half: a refusal's\n * diagnostic must not pollute a piped payload. `loam show svc > out.json`\n * already keeps its message off stdout, and a pointer that broke that rule\n * would corrupt exactly the pipelines text mode was careful never to touch.\n * (Findings do the opposite — their codes go to stdout with the report, in\n * document order, for validate/report.ts's own reason. Same fact, two streams,\n * because a finding is the answer and a refusal is the absence of one.)\n *\n * Nothing runs here under `--json`: the envelope already carries `error.code`\n * as data, and a machine reader has no use for being told a second command\n * exists — the same doctrine `EXPLAIN_FOOTER` follows in\n * commands/policy/format.ts.\n *\n * No ANSI escape, though the line is meant to READ as dim. Nothing in this\n * codebase emits escape sequences, the output is graded by tests that compare\n * strings, and a colour that survives into a redirected file or a CI log is\n * noise nobody asked for. The typography does the dimming: the code, a spaced\n * middot, the command — an aside, not a sentence.\n */\nexport function sayExplain(code: ErrorCode): void {\n  if (NO_EXPLAIN_POINTER.has(code)) return;\n  console.error(`${code}  ·  loam explain ${code}`);\n}\n\n/**\n * Report a failure in whichever mode the caller is in. Text mode goes to\n * stderr as it always has — now with the code and its lookup on a second line;\n * JSON mode goes into the envelope, whose stdout bytes are unchanged.\n */\nexport function fail(json: boolean, code: ErrorCode, message: string): void {\n  if (json) {\n    emitJsonError(code, message);\n    return;\n  }\n  console.error(message);\n  sayExplain(code);\n  process.exitCode = 1;\n}\n\n/**\n * A refusal or failure with its stable `--json` code attached, for the commands\n * whose refusals are THROWN — from a plan phase or a rollback path several\n * calls below the one handler that prints — rather than returned. The handler\n * `fail`s with `code`, so a merge that could not be computed reports as a merge\n * failure rather than as `internal`. What anything ELSE that escapes means is\n * each handler's to say. One class, because archive, unarchive and\n * migrate-openspec had each written this same one.\n */\nexport class CodedFailure extends Error {\n  constructor(\n    readonly code: ErrorCode,\n    message: string,\n  ) {\n    super(message);\n  }\n}\n\n/** The message every command prints when there is no loam.json. */\nconst NO_CONFIG_MESSAGE = \"No loam.json found. Run `loam init --docs <dir>` first.\";\n\n/**\n * The message the service-scoped commands print when neither `--service` nor\n * loam.json names one. Four commands ask the same question and owe the same two\n * answers, and a fifth would have been written by hand. `loam delta` keeps its\n * own longer sentence on purpose — it can say which feature was being read.\n */\nexport const NO_SERVICE_MESSAGE = \"No service. Pass --service <id> or set it in loam.json.\";\n\n/**\n * Report \"no config\" in whichever mode the caller is in — distinguishing a\n * config that is absent from one that exists but would not load, because the\n * two point at opposite fixes: a missing config wants `loam init`, a corrupt\n * one wants repair, and `init` would silently rewrite the corrupt file. The\n * distinction arrives as DATA on the load outcome rather than being re-derived\n * from the filesystem here — the file could change between the load and a\n * re-check, and the parse problem itself is worth showing.\n */\nexport function reportNoConfig(json: boolean, load: { kind: \"absent\" } | { kind: \"invalid\"; path: string; problem: string }): void {\n  if (load.kind === \"invalid\") {\n    fail(\n      json,\n      \"config-invalid\",\n      `Invalid loam.json: ${load.problem}. Fix it (or delete it and re-run \\`loam init\\`).`,\n    );\n    return;\n  }\n  fail(json, \"no-config\", NO_CONFIG_MESSAGE);\n}\n\n/**\n * The config a command action stands on, or null once `reportNoConfig` has\n * refused — the caller's whole answer to null is `return`. Every command that\n * needs a wired repo opens with this question, and it was spelled as the same\n * six lines in each of them; one spelling is what keeps the absent/invalid\n * split above from being forgotten in a twenty-fourth. `init` and `doctor` do\n * not come through here: a missing or broken config is their subject, not a\n * reason to stop.\n */\nexport async function configOrRefuse(json: boolean): Promise<LoamConfig | null> {\n  const loaded = await loadConfig();\n  if (loaded.kind !== \"loaded\") {\n    reportNoConfig(json, loaded);\n    return null;\n  }\n  return loaded.config;\n}\n"]}

package/dist/core/{version.js → envelope/version.js}

@@ -1,7 +1,7 @@
 /**
  * One version string, owned by package.json — read once, imported everywhere a
- * version is spoken. `../../package.json` resolves from src/core/ in dev and
- * from dist/core/ in the published layout alike.
+ * version is spoken. `../../../package.json` resolves from src/core/envelope/ in
+ * dev and from dist/core/envelope/ in the published layout alike.
  */
 import { createRequire } from "node:module";
 /**
@@ -20,5 +20,5 @@ function readVersion(pkg) {
     }
     return version;
 }
-export const LOAM_VERSION = readVersion(createRequire(import.meta.url)("../../package.json"));
+export const LOAM_VERSION = readVersion(createRequire(import.meta.url)("../../../package.json"));
 //# sourceMappingURL=version.js.map

package/dist/core/envelope/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../src/core/envelope/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,GAAY;IAC/B,MAAM,OAAO,GAAG,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACtG,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,gGAAgG,CACjG,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC","sourcesContent":["/**\n * One version string, owned by package.json — read once, imported everywhere a\n * version is spoken. `../../../package.json` resolves from src/core/envelope/ in\n * dev and from dist/core/envelope/ in the published layout alike.\n */\nimport { createRequire } from \"node:module\";\n\n/**\n * The read is checked rather than asserted because the failure it would let\n * through is silent, permanent, and invisible on the machine that caused it: an\n * absent or empty `version` stamps `vundefined` into every file loam generates,\n * `agentsStampVersion` then cannot parse that stamp back, and every repository\n * built by that build reports its agent files stale forever with nothing to\n * point at. A build that cannot say what it is has nothing useful to do, so it\n * says so once, loudly, while its own module is being evaluated.\n */\nfunction readVersion(pkg: unknown): string {\n  const version = pkg !== null && typeof pkg === \"object\" && \"version\" in pkg ? pkg.version : undefined;\n  if (typeof version !== \"string\" || version === \"\") {\n    throw new Error(\n      \"readVersion: package.json declares no non-empty 'version', so this build cannot say what it is\",\n    );\n  }\n  return version;\n}\n\nexport const LOAM_VERSION = readVersion(createRequire(import.meta.url)(\"../../../package.json\"));\n"]}

package/dist/core/explain/families.js

@@ -0,0 +1,180 @@
+/**
+ * The family registry: `loam explain`'s content for the four code families no
+ * fix table anywhere grades — `doctor.*`, `next.*`, `diff.*` and `gate.*`.
+ *
+ * WHY THIS IS NOT THE DUPLICATION fix-tables.ts FORBIDS. That module's header
+ * argues against a second hand-maintained copy of the /loam-check prose, and
+ * the argument is right: the tables ship in the binary, test/codes-drift.test.ts
+ * holds every emitted finding code against them, and a registry restating them
+ * would be free to trail the bytes `loam instructions loam-check` prints. None
+ * of that applies here. These 67 codes have no fix-table row in any workflow
+ * body — /loam-check grades DOCUMENTS, and these four families grade a
+ * repository's wiring (`doctor`), a recommendation (`next`), a change between
+ * two refs (`diff`) and a deploy question (`gate`). There is nothing to trail:
+ * this registry is not a second copy, it is the only copy. The precedent is the
+ * sibling module refusals.ts, a hand-written map that is the sole source for
+ * the `ErrorCode` meanings for exactly the same reason — their prose lives in
+ * doc comments, which are erased, so there is no runtime constant to read.
+ *
+ * What that costs, stated rather than hidden: nothing mechanical proves an
+ * entry below still matches the message its emitter prints. Every meaning and
+ * every fix here was written FROM the emitter — `doctor` findings carry a `fix`
+ * field of their own (core/doctor/), a `next` step carries a `statement` and a
+ * literal `command` (core/status/), the `DiffCode` union carries a doc comment
+ * per member (core/diff/semantic.ts) — and the wording is theirs, not a
+ * paraphrase invented here. Two guards catch the two failures that CAN be
+ * caught: test/explain.test.ts asserts no code below is also answered by a fix
+ * table (the two sources must never be able to disagree), and
+ * test/agent-commands-runnable.test.ts parses every backticked `loam …` in this
+ * file against the real program, so a fix naming a command loam does not have —
+ * or a flag it does not declare — fails at gate time. A two-token span is a
+ * NAME rather than an invocation there and is only checked for the command
+ * existing, so a fix that means an invocation must carry its arguments.
+ *
+ * `severityNote` is the EMITTER's own word, not a fix table's parenthetical:
+ * `doctor` grades blocker/warning, `diff` and `gate` grade ok/warn/error, and a
+ * `next` step is graded not at all — it is a recommendation, so its note is
+ * `step`. Where a code's severity depends on what was found (`doctor.docs-locked`,
+ * `gate.partners-unknown`) the note says so in prose, the way the tables' own
+ * long notes do (`warn here; error at archive plan time`).
+ *
+ * `openspec.*` and `mapping.*` — 49 codes — are deliberately NOT here, and the
+ * reason is in test/explain.test.ts beside their backlog entries: they are the
+ * only codes in the vocabulary whose subject is not a loam document at all.
+ */
+/**
+ * `loam doctor` — the preflight. Every finding here already carries a `fix`
+ * field in doctor's own report (core/doctor/doctor.ts, config.ts, agents.ts,
+ * residue.ts); these rows say the same thing without a repository in front of
+ * them, which is the whole difference between a report and a lookup.
+ */
+const DOCTOR = {
+    scope: "loam doctor",
+    codes: {
+        "doctor.config-missing": { severityNote: "blocker", meaning: "No loam.json at or above the working directory, so nothing says which docs repo this checkout belongs to — every other command refuses with `no-config` until there is one.", fix: "Run `loam init --docs <dir>` in this repository; add `--create` when the docs repo does not exist yet." },
+        "doctor.config-invalid": { severityNote: "blocker", meaning: "A loam.json is there and `parseConfig` — the same loader every command uses — refuses it; the finding carries the parser's own words. doctor deliberately has no second validator: the one it used to carry accepted a config the commands rejected, and reported a healthy repo in which nothing could run.", fix: "Repair the file the finding names, or delete it and re-run `loam init`." },
+        "doctor.docs-missing": { severityNote: "blocker", meaning: "`docsDir` resolves to something that is missing or is not a directory — the docs repo was never cloned, or the path is wrong.", fix: "Fix `docsDir` in the loam.json the finding names, clone the docs repo to that path, or run `loam init --docs <dir> --create`." },
+        "doctor.services-missing": { severityNote: "blocker", meaning: "`docsDir` is a directory and holds no `services/`, so it is some other directory — most often the service repo itself, after a typo in the pointer.", fix: "Point `docsDir` at the shared docs repo, or run `loam init --docs <dir> --create` to scaffold one. Do not scaffold a second source of truth beside the real one." },
+        "doctor.docs-absolute": { severityNote: "warning", meaning: "`docsDir` is stored as an absolute path and loam.json is committed, so the pointer names a directory that exists on exactly one machine: it works for whoever ran `loam init` and for nobody who clones the repo afterwards.", fix: "Rewrite `docsDir` as a path relative to the loam.json holding it, such as `../docs`." },
+        "doctor.docs-unreadable": { severityNote: "warning", meaning: "The docs repo exists and this process cannot read it, so every command that reads the fleet will fail or report an empty one.", fix: "Grant read access to the directory the finding names — check ownership and mode." },
+        "doctor.docs-readonly": { severityNote: "warning", meaning: "The docs repo is readable and not writable: read-only commands work and the writing ones do not.", fix: "Grant write access if you need `loam new`, `loam adopt` or `loam archive`. A read-only checkout is a legitimate state for a reviewer, which is why this is a warning." },
+        "doctor.landscape-missing": { severityNote: "warning", meaning: "architecture/landscape.likec4 is missing, and it is the one artifact every cross-service check reads — nothing about who calls whom can be checked without it.", fix: "Create it with one element per service and an edge per call: `loam init --create` writes the empty map, and `loam seed --from fleet.yaml` templates one from stated facts." },
+        "doctor.landscape-unreadable": { severityNote: "blocker", meaning: "The landscape file exists and the read itself failed — permissions or an I/O error, carried verbatim in the message.", fix: "Check permissions on the path the finding names." },
+        "doctor.landscape-merge-conflict": { severityNote: "blocker", meaning: "The landscape still contains merge conflict markers, named by line. Checked BEFORE the parser on purpose: both sides of a conflict can be syntactically valid LikeC4, so the file sometimes parses and is still two halves of two different maps.", fix: "Resolve the conflict keeping BOTH services' elements and edges — the usual cause is several services adopted into one map in the same week — then re-run `loam doctor`." },
+        "doctor.landscape-invalid": { severityNote: "blocker", meaning: "The landscape exists, carries no conflict markers, and does not parse; the message quotes the first parser error with its line and counts the rest.", fix: "Fix the file — every fleet-wide check is blind until it parses." },
+        "doctor.likec4-config-missing": { severityNote: "warning", meaning: "The docs repo has no likec4.config.json, so the tree is not a loadable LikeC4 workspace: every service model and feature delta declares its own `specification` block, and a renderer pointed at the repo root merges them and reports every declaration as a duplicate. No loam check reads this file — the repo is only unrenderable, which is why it is a warning.", fix: "Write the project file the finding prints; it scopes the root project to architecture/, so `npx likec4 start` in the docs repo renders the fleet map. Then run `loam subsystem sync`: it writes one create-only likec4.config.json beside every service model, so each model renders from that same root as a project of its own — only a feature delta still renders from its own directory." },
+        "doctor.docs-locked": { severityNote: "warning while a live process holds it; blocker when its holder is dead or it names none", meaning: "A `.loam-lock` is present. Held by a running process it is a fact about right now. Held by a process that no longer exists on this host — or unreadable, so no holder can be named at all — nothing is ever going to release it, and every writing command refuses with `docs-busy` forever.", fix: "Wait and re-run while the holder is alive; nothing is read or written while it is held. Delete the lock file the finding names when its holder is dead or unnameable, then run `loam doctor` again for an interrupted commit underneath it." },
+        "doctor.commit-unreadable": { severityNote: "blocker", meaning: "A `.loam-commit` journal is present and cannot be read: a commit was interrupted and the one record of which files it had already written is unreadable.", fix: "Hand this to a human — compare the root's files against version control before running any loam command that writes there. Every journaled writer refuses with `commit-interrupted` while it is present." },
+        "doctor.commit-interrupted": { severityNote: "blocker", meaning: "A journaled writer — archive, unarchive, rebase, vouch, new, gherkin, or a recording verify — was killed mid-commit. The message names the host, pid and time, and every file or directory move that may be half-done. This is the surface that used to report a healthy repo over half-merged living docs.", fix: "Re-run the command the finding names: it recovers first, under the lock, rolling the staged bytes forward, and refuses rather than guessing if a file has been edited since. An interrupted `loam unarchive` is FINISHED, never undone — the merged text it was replacing is written down nowhere." },
+        "doctor.staging-temps": { severityNote: "warning", meaning: "Orphaned `.loam-*.tmp` scratch files from a killed writer, never linked into place — so nothing reads them and nothing depends on them. A journal's own recorded temps are excluded, because those are the durable copy its roll-forward recovery renames in. Litter, not damage.", fix: "The next journaled writer through that root removes its own; delete any that remain. They cost disk and nothing else." },
+        "doctor.inventory-unreadable": { severityNote: "warning", meaning: "The config and the docs repo are both fine and enumerating `services/` or `features/` threw, so doctor's fleet counts — and its verdict on the service binding — are about a fleet nobody could read.", fix: "Check that services/ and features/ under the docs repo are readable directories." },
+        "doctor.service-unbound": { severityNote: "warning", meaning: "loam.json declares no `service`, so nothing binds this checkout to one governed boundary and the service-repo checks have nothing to run against — `sources.stale`, a recording `loam verify`, `loam gherkin`. Deliberately not emitted inside the docs repo itself, where having no binding is the correct state rather than a gap.", fix: "Run `loam init --docs <dir> --service <id>` here." },
+        "doctor.service-unknown": { severityNote: "warning", meaning: "loam.json names a `service` the fleet has no services/<id>/ for — and the fleet WAS read, so this is a claim about a real inventory rather than one nobody could take. Two states raise it: nobody has adopted that service yet, or an active feature INTRODUCES it — its only documents are that feature's specs/<id>/ until the feature archives. doctor's binding line and `currentService.introducedBy` say which; the message names the feature.", fix: "When a feature introduces it there is nothing to adopt — adopting would write services/<id>/ ahead of the merge. Run `loam status <FEAT-id>` for what this repository owes that feature; the warning clears when it archives. Otherwise run `loam adopt --service <id>` to onboard it. Either way, fix `service` in loam.json if it names the wrong service." },
+        "doctor.agent-files-missing": { severityNote: "warning", meaning: "Some of the command and skill files this loam lays down for the repo's recorded tools and profile are not here: the repo was initialized by an older loam, or they were deleted. An out-of-date command set costs entry points, never a refusal, which is why it is a warning.", fix: "Re-run `loam init --docs <dir> --tools <ids>` here. It creates absent files, refreshes only pointers whose current bytes still match their recorded digest, preserves every customized file, and keeps this repo's service binding." },
+        "doctor.agent-files-stale": { severityNote: "warning", meaning: "Command or skill files that ARE here differ from the body this binary writes and carry no loam stamp, or one older than this binary, so what they instruct an agent with may describe a loam that no longer exists. A file whose only difference is an older stamp is current and not reported; a customized body under a current stamp is not reported either, because the stamp records that somebody reviewed it. Safe refresh is a separate digest check performed by init.", fix: "Re-run `loam init` to refresh a pointer only when its recorded digest still matches. Review a customized file against the current body yourself and update its stamp, or delete it so init can recreate it; your edits always outrank the template." },
+    },
+};
+/**
+ * `loam status` — both forms print `next[]`, and each entry carries a `code` to
+ * branch on, one sentence, and the literal `command` to run. So the "what to
+ * do" column is genuinely empty for this whole family: the step IS the action,
+ * and each `fix` below names the step's own command rather than inventing a
+ * second instruction beside it.
+ */
+const NEXT_STEPS = {
+    scope: "loam status",
+    codes: {
+        "next.adopt-bound": { severityNote: "step", meaning: "The fleet form's first entry: this repository's loam.json says it is a service the fleet has no services/<id>/ for, so nothing about the boundary you are standing in is written down yet. Ahead of every other service's adoption work, because it is the only step that is about HERE. When a feature in flight INTRODUCES that service, this step is not emitted: there is no code to adopt yet, and that feature's `next.feature` leads instead.", fix: "The step IS the action: run its `command`, `loam adopt --service <id> --json`." },
+        "next.author-landscape": { severityNote: "step", meaning: "The first rung of the first-hour ladder, over a fleet with no services and no features: architecture/landscape.likec4 does not exist, or is still the scaffold's untouched map with no service drawn on it.", fix: "The step IS the action: run its `command` — `loam init --create` when the file is absent, `loam seed --from fleet.yaml` when it is the untouched scaffold. loam never guesses who calls whom." },
+        "next.bind-service": { severityNote: "step", meaning: "First-hour ladder: no service repository is bound to this fleet yet, so no command can ever run from a service's own checkout.", fix: "The step IS the action: run its `command`, `loam init --docs <path-to-this-docs-repo> --service <service-id> --agent-profile service`, from a service's own repo, and commit the loam.json it writes. The service profile leaves loam-feature and loam-ship, which this docs repo keeps, out of the service checkout." },
+        "next.adopt-first": { severityNote: "step", meaning: "First-hour ladder: services/ is empty, so nothing about any service is written down and nothing can be graded against anything.", fix: "The step IS the action: run its `command`, `loam adopt --service <service-id> --json`; the brief it prints walks an agent through writing the baseline docs as draft." },
+        "next.adopt": { severityNote: "step", meaning: "One service in the fleet has no spec.md — nothing about it is written down, so no feature can be graded against it — or has one marked `adoption: partial`: `loam archive` wrote it from one feature's slice into a service nobody had adopted, so what the service already did is still unwritten. One entry per such service.", fix: "The step IS the action: run its `command`, `loam adopt --service <id> --json`. For a partial adoption the brief shows spec.md as present — write the baseline around the slice, never replace it — and then delete the `adoption: partial` line, which is the only thing that retires the step." },
+        "next.complete-service": { severityNote: "step", meaning: "Adoption does not end at spec.md: a service has one and no model.likec4, the state archive warns about and the fleet gate reports incomplete until something models it.", fix: "The step IS the action: run its `command`, `loam validate --service <id> --json`." },
+        "next.revouch": { severityNote: "step", meaning: "A vouched service's spec.md or arch.spec.md changed after the person read it — `content.stale`, computable from the docs repo because it needs nothing but the document. `status: verified` still stands, so every fleet readout says vouched (stale) and this step keeps `next.fleet-clean` from saying nothing is owed. One entry per service, naming the documents that moved.", fix: "Not an agent's step: its `execution` is a human review. Prepare the reading list with `loam vouch --pack --service <id>`, then a person re-reads what moved and runs the step's `command`, `loam vouch --service <id>`, from that service's own repository. Never revert the document or touch `content_digest` to silence it." },
+        "next.feature": { severityNote: "step", meaning: "One feature in flight that is not verified yet, with where it stands said in words — docs being written, docs ready with N of M claims answered, blocked — or, when it is blocked by another feature, the features it is waiting on. The fleet form lists every feature before any service's adoption rung. In a service repository whose bound service a feature introduces, the first entry is that feature's, saying so.", fix: "The step IS the action: run its `command`, `loam status <FEAT-id> --json`, for that feature's own next list." },
+        "next.archive": { severityNote: "step", meaning: "In the fleet form, a feature that is authored and verified: archive it, and everything queued behind it is released. In a feature's own list it is always the last entry. Archive merges the deltas into the living docs and checks the documents only — never the code or the verification record — so it will not stop you archiving work nobody built; finish the steps above it first.", fix: "The step IS the action: run its `command`, `loam archive <FEAT-id> --dry-run --json`; the dry run writes nothing and lists every file the merge would touch." },
+        "next.elided": { severityNote: "step", meaning: "The fleet list is capped, and this says how many steps it left out, counted by code. The list is ordered most-unblocking first, so what was elided is the least urgent — a list nobody reads is not navigation.", fix: "The step IS the action: run its `command`, `loam list --json`, or work down the printed list and run status again." },
+        "next.fleet-clean": { severityNote: "step", meaning: "Services exist, nothing is in flight, and nothing is owed. Only that truthful case: over an EMPTY fleet the same sentence was vacuously true, and the first-hour ladder owns that repository now.", fix: "The step IS the action: run its `command`, `loam validate --all --json`, then start the next feature." },
+        "next.fleet-gate": { severityNote: "step", meaning: "The last entry of every fleet list, and always present: `status` grades nothing, so the least it can do is say where grading happens — `loam validate --all` is the gate this repository has to pass and the one CI runs.", fix: "The step IS the action: run its `command`, `loam validate --all --json`." },
+        "next.recover-commit": { severityNote: "step", meaning: "Always first, and never elided by the fleet form's cap: a journaled writer was killed mid-commit, so everything below this step is derived from files that may be half-written. Where the journal itself cannot be read, nothing below can be trusted until a human compares the living docs against version control.", fix: "The step IS the action: run its `command` — the interrupted command re-run, which recovers first under the lock, or `loam doctor --json` when the journal is unreadable and no loam command can repair it." },
+        "next.archived": { severityNote: "step", meaning: "The whole `next[]` for an archived feature: its delta is folded into the living docs. Archiving checks documents, not code, so the step also says whether the feature was ever verified.", fix: "The step IS the action: run its `command`, `loam show <FEAT-id> --json`." },
+        "next.author-intent": { severityNote: "step", meaning: "The feature has no intent document — what it is for, in prose, before anything is derived from it.", fix: "The step IS the action: write the file the step names, then run its `command`, `loam validate <FEAT-id> --json`. The command never writes the artifact: loam does not author." },
+        "next.touch-service": { severityNote: "step", meaning: "The feature carries no per-service delta at all, so nothing says which governed boundaries it changes.", fix: "The step IS the action: run its `command`, `loam list services --json`, then add specs/<service>/spec.md for every service the feature changes." },
+        "next.author-spec": { severityNote: "step", meaning: "One service the feature touches has no requirement delta — the ADDED / MODIFIED / REMOVED requirements the feature makes to that service, each with a scenario.", fix: "The step IS the action: write the file the step names, then run its `command`, `loam delta <FEAT-id> --service <id> --json`, which projects the delta onto the living document." },
+        "next.author-openapi": { severityNote: "step", meaning: "Nothing gives one of the feature's services a living openapi.yaml, so this feature is the only thing that can write down its API surface. Deliberately not phrased as the service being absent from the living docs: a service adopted without a contract is the commoner case, and that wording sent readers looking for a directory that was right there.", fix: "The step IS the action: write the file the step names, then run its `command`, `loam delta <FEAT-id> --service <id> --json`." },
+        "next.author-scenarios": { severityNote: "step", meaning: "Requirements in one service's delta carry no `#### Scenario:`, so they generate no test and no verify claim — a promise that reaches neither the suite nor the done-check. One entry per service and never per requirement, because a delta with forty bare requirements would otherwise BE the payload.", fix: "The step IS the action: write a scenario under each bare requirement, then run its `command`, `loam delta <FEAT-id> --service <id> --json`." },
+        "next.rebase": { severityNote: "step", meaning: "The feature carries requirements or operations with no baseline pin, on any of the three axes; until they have one the merge cannot tell what it EDITS from what it merely quotes.", fix: "The step IS the action: run its `command`, `loam rebase <FEAT-id>`." },
+        "next.archive-first": { severityNote: "step", meaning: "The feature builds on other features still in flight, which have to archive before it can.", fix: "The step IS the action: run its `command`, `loam dependencies <FEAT-id> --json`." },
+        "next.fix-coherence": { severityNote: "step", meaning: "The feature has findings that stop it, named starting with the first. Everything EITHER gate refuses on is counted, so a warning marked as gating archive is in the tally even though `validate` grades the feature valid — which is why its exit code alone will not show you why archive refuses.", fix: "The step IS the action: run its `command`, `loam validate <FEAT-id> --json`." },
+        "next.generate-tests": { severityNote: "step", meaning: "The feature's delta for a service carries scenarios no test run has answered yet. `loam gherkin` writes the .feature files whose green run is the only thing that may answer a `scenario.tested` claim, and it writes into the service's own repository — so the step names which repo to run it in when that is not this one.", fix: "The step IS the action: run its `command`, `loam gherkin <FEAT-id> --service <id>`, from that service's own checkout." },
+        "next.verify": { severityNote: "step", meaning: "The done-check has not been started, or its record cannot be used. Five situations share this code because they share the work — nothing recorded, a record file that does not read as a record, a record the feature has moved out from under, a record that answers no claims at all, and a feature with nothing to derive a checklist from yet — and the step's own statement says which.", fix: "The step IS the action: run its `command`, `loam verify <FEAT-id> --json`, which derives the checklist and prints what it asks. A record file nothing can read is repaired by hand or, when it is one service's own `verification/<svc>.yaml`, deleted and recorded again by that service; the one-file `verification.yaml` may hold other services' attestations and is restored from version control, never deleted. Nothing overwrites it while it is unreadable." },
+        "next.verify-unconfirmed": { severityNote: "step", meaning: "Claims on the feature are open — unconfirmed or unanswered — and this repository is not one of the services that owes an answer, so the recording form is not a step anyone can take from here.", fix: "The step IS the action: run its `command`, `loam verify <FEAT-id> --json`. The open claims are closed from each affected service's own repository." },
+        "next.attest-service": { severityNote: "step", meaning: "Claims are open AND this repository is one of the services that owes an answer, so the recording form is nameable here: `--record --service` binds the answers to this repo's HEAD and refuses anywhere else.", fix: "The step IS the action: run its `command`, `loam verify <FEAT-id> --record answers.json --service <id>`, answering the claims filed under this service; the rest belong to their own repositories." },
+        "next.verify-attested": { severityNote: "step", meaning: "Every claim is answered and some scenario claims are confirmed on an agent's word rather than on a test run (`verify.scenario-attested`) — complete work resting on an assertion, which is what `ready` has always meant here.", fix: "The step IS the action: run its `command`, `loam verify <FEAT-id> --results <report.json>` — a cucumber JSON report, or loam's runner-neutral `loamScenarioReport` shape for any other runner — and the record stops resting on an assertion." },
+    },
+};
+/**
+ * `loam diff` — what CHANGED between a base git ref of the docs repo and the
+ * working tree, not what is WRONG with either. That is why most rows below have
+ * no repair: the meanings are the `DiffCode` union's own doc comments
+ * (core/diff/semantic.ts), and the two error rows are the only ones naming a
+ * repair. The two `-modified` rows name work too, but not loam's: whether a
+ * changed schema breaks its readers is the specialist diff's answer.
+ */
+const DIFF = {
+    scope: "loam diff --base <ref>",
+    codes: {
+        "diff.service-added": { severityNote: "ok", meaning: "A services/<id>/ directory exists now that did not exist at the base ref.", fix: "Nothing to fix: `loam diff` says what changed between two points of the living docs, never what is wrong with them. This is the class of the change, for a reviewer to read." },
+        "diff.service-removed": { severityNote: "warn", meaning: "A service present at the base ref is gone from the working tree; the finding names the directory it occupied.", fix: "A review question rather than a defect: nothing in the working tree describes that boundary any more. `loam validate --all` is what grades the fleet that is left." },
+        "diff.requirement-added": { severityNote: "ok", meaning: "A living requirement not present at base — by `Requirement-ID:` where one is authored, by heading otherwise, the same join `loam rebase` pins against.", fix: "Nothing to fix: this is the class of the change, for a reviewer to read." },
+        "diff.requirement-removed": { severityNote: "warn", meaning: "A requirement present at the base ref is no longer in the living spec under the same identity.", fix: "A review question. A requirement that CHANGED identity — a new `Requirement-ID:`, a renamed heading — reads here as a removal plus an addition, which is the join being honest about what it can see rather than guessing a rename." },
+        "diff.requirement-modified": { severityNote: "ok", meaning: "The same requirement identity is on both sides and its digest moved. A rebase pin never moves that digest, so this is a real edit to the requirement's text.", fix: "Nothing to fix: this is the class of the change, for a reviewer to read." },
+        "diff.op-added": { severityNote: "ok", meaning: "An operationId in the living contract that was absent at the base ref; the message names its method and path.", fix: "Nothing to fix: this is the class of the change, for a reviewer to read." },
+        "diff.op-removed": { severityNote: "warn", meaning: "A base operationId is gone from the living contract and no current edge of the `architecture/` project, requirement or use-case hop names it — or, in the second wording this code also carries, whether one does could NOT be fully answered, and the details name the possible consumers nobody could check: a consumer document that was not scannable, or a landscape edge into this service drawn with no `metadata { op }`.", fix: "Read which of the two sentences it is. Nobody could be checked is never nobody names it: an unreadable document carries the run to exit 1 on its own, and an edge with no op is answered by putting the operation it calls on the edge (`spine.op-link-missing` names the same edge)." },
+        "diff.op-removed-consumed": { severityNote: "error", meaning: "An operation was removed since the base ref and the current fleet still names it — an edge of the `architecture/` project, another service's requirement in spec.md or arch.spec.md (not one naming its own service's operation of the same id), or a use-case hop attributed to it: the consumers the archive gate refuses on too. The details list the victims, and the finding sets `breaking`.", fix: "These joins break. Either restore the operation, or land the consumers' own deltas in the same change so nothing in the fleet is left calling something that is gone." },
+        "diff.op-deprecated": { severityNote: "warn", meaning: "`deprecated: true` was introduced on an operation since the base ref. The details name the current consumers, under one of three deliberately honest phrasings: some still name it, none does, or whether any does could not be fully answered.", fix: "Deprecation is a promise to the consumers the details name, and nothing is broken yet. Read which phrasing it is before treating a silent list as an empty one." },
+        "diff.op-modified": { severityNote: "warn", meaning: "The same operationId is on both sides and the operation changed: its own definition, its method or path, or anything its internal `$ref`s reach — a field renamed in a shared `components` schema counts. The details name the authored consumers, the same scan `diff.op-deprecated` runs. loam does not read what a schema says, so it never grades whether the change is breaking.", fix: "Run `oasdiff breaking` on the two states of this contract to learn whether it breaks anyone; the details are who to tell. A warning on purpose: a new optional field and a renamed required one look identical from here." },
+        "diff.message-added": { severityNote: "ok", meaning: "An AsyncAPI message name absent at the base ref.", fix: "Nothing to fix: this is the class of the change, for a reviewer to read." },
+        "diff.message-removed": { severityNote: "warn", meaning: "A base message is gone. The finding says which of three cases it is: another current service still sends it (an `action: send` operation — a service that only receives it is a consumer) or an `#external` element still publishes it (a `publishes` edge from it in the `architecture/` project, the outside producer `spine.message-unproduced` accepts), nothing currently consumes it, or whether anything does could not be fully answered because some consumer documents were not scannable.", fix: "Read which case it is. A name another service still sends, or an `#external` element still publishes, is not orphaned, and an unanswerable scan is not an empty one — only positive evidence vouches here." },
+        "diff.message-removed-consumed": { severityNote: "error", meaning: "A message was removed since the base ref and the current fleet still consumes it — a `Consumes:` line in either spec file, a consumes edge of the `architecture/` project, or a use-case hop it backs. The details list the victims, and the finding sets `breaking`.", fix: "These joins break. Either restore the message, or land the consumers' own deltas in the same change." },
+        "diff.message-modified": { severityNote: "warn", meaning: "The same AsyncAPI message name is on both sides and its declaration, or anything its internal `$ref`s reach, changed — a payload field renamed counts. The details name the authored consumers: consumes-edges, `Consumes:` lines and the use-case hops they back. Content equality only: nothing inside the payload is ever joined on, and whether the change breaks a consumer is not graded.", fix: "Run `asyncapi diff` on the two states of this contract to learn whether it breaks anyone; the details are who to tell." },
+        "diff.consumer-added": { severityNote: "ok", meaning: "A cross-service join appeared since base: another service's living requirements — spec.md or arch.spec.md — now name this service's operation or message. A line naming an operation the consumer's own contract defines names its own, and is no join. Filed on the PROVIDER — the service whose surface the join lands on.", fix: "Nothing to fix, and the change class most worth reading: a new consumer is a new obligation on this service's contract, and removing that operation later is what `diff.op-removed-consumed` will be about." },
+        "diff.consumer-removed": { severityNote: "ok", meaning: "A cross-service join present at the base ref is gone: a consumer's living requirements no longer name this service's operation or message.", fix: "Nothing to fix: this is the class of the change, for a reviewer to read." },
+    },
+};
+/**
+ * `loam gate` — the can-i-deploy question, a pure query over evidence other
+ * commands already recorded. Nothing here re-derives a coherence plan, so every
+ * repair below is somebody else's command.
+ */
+const GATE = {
+    scope: "loam gate",
+    codes: {
+        "gate.partners-unknown": { severityNote: "warn when the map is absent; error when it exists and cannot be used", meaning: "The partner set for the gated service could not be derived from architecture/landscape.likec4 — it is absent, or it exists and does not parse. That means nobody could look, never that nothing joins this service. Absent is a warning because a repo before its first adopt legitimately has no map yet; a broken map is an error because `loam validate --all` fails that repo for the same file, and a deploy gate passing where the fleet gate fails would be the quieter of two contradictory verdicts.", fix: "Fix the landscape and re-run. `loam validate --all` diagnoses the file itself; this check only refuses the false silence." },
+        "gate.service-undocumented": { severityNote: "error", meaning: "The service being deployed sits below `documented` on the adoption ladder, so the docs cannot say what its joins even are and no recorded evidence can answer the deploy question. That includes a spec.md marked `adoption: partial` — one archived feature's slice, written into a service nobody had adopted. The details list what the next rung wants.", fix: "Author the baseline — `loam adopt --service <id>` briefs exactly what is missing — and this check passes once the required artifact set exists; for a partial adoption, write the rest of spec.md from the code and then delete its `adoption: partial` line." },
+        "gate.partner-undocumented": { severityNote: "warn", meaning: "A service that joins the gated one has no services/<id>/ directory at all, or has one sitting below `documented`: its side of the join is not recorded, so the gate cannot see what that partner promises. An `#external` partner is exempt on purpose — somebody else's system is unrecorded by design.", fix: "Adopt the partner (`loam adopt --service <id>` briefs it), bind its landscape element to the right service with `metadata { service '<id>' }`, or tag it `#external` if it is not ours." },
+        "gate.feature-unverified": { severityNote: "warn", meaning: "An active feature touching the gated service — or, under `--since <ref>`, one archived after that docs-repo ref (its `features/archive/` directory absent at the ref, or changed since: a feature unarchived and archived again ships again) — is not verified: no record at all, a record file that does not read as a record, a record the feature moved out from under (for an archived feature, one that no longer answered the checklist `loam archive` captured as it merged), a record answering no claims, or open claims counted in the message. A record that is merely `attested` is NOT reported under this code — it carries `verify.scenario-attested` instead, because complete work resting on an assertion is a different fact from work nobody checked. Without `--since` an archived feature is never read, so archiving one takes it out of this check.", fix: "Derive the checklist and answer every claim with evidence: `loam verify <FEAT-id> --json`. A record file nothing can read is repaired by hand or, when it is one service's own `verification/<svc>.yaml`, deleted and recorded again by that service; the one-file `verification.yaml` may hold other services' attestations and is restored from version control, never deleted. Nothing overwrites it while it is unreadable. An archived feature's record is frozen: `loam unarchive <FEAT-id>` re-opens it if its claims must be answered before the deploy." },
+    },
+};
+/** In listing order, though every consumer sorts by code — the order is documentation, not contract. */
+const FAMILIES = [DOCTOR, NEXT_STEPS, DIFF, GATE];
+/**
+ * The registry's answer for one subject, or null.
+ *
+ * Built per call over constants already in memory, never cached at module
+ * level, for the reason lookup.ts's header gives: tests fork and chdir, and the
+ * MCP server outlives many calls.
+ */
+export function familyFinding(subject) {
+    for (const family of FAMILIES) {
+        const entry = family.codes[subject];
+        if (entry !== undefined)
+            return { scope: family.scope, ...entry };
+    }
+    return null;
+}
+/** Every code the registry answers, sorted — the same plain sort the code inventory uses. */
+export function familyCodes() {
+    return FAMILIES.flatMap((family) => Object.keys(family.codes)).sort();
+}
+//# sourceMappingURL=families.js.map