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

package/dist/core/explain/families.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"families.js","sourceRoot":"","sources":["../../../src/core/explain/families.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The family registry: `loam explain`'s content for the four code families no\n * fix table anywhere grades — `doctor.*`, `next.*`, `diff.*` and `gate.*`.\n *\n * WHY THIS IS NOT THE DUPLICATION fix-tables.ts FORBIDS. That module's header\n * argues against a second hand-maintained copy of the /loam-check prose, and\n * the argument is right: the tables ship in the binary, test/codes-drift.test.ts\n * holds every emitted finding code against them, and a registry restating them\n * would be free to trail the bytes `loam instructions loam-check` prints. None\n * of that applies here. These 67 codes have no fix-table row in any workflow\n * body — /loam-check grades DOCUMENTS, and these four families grade a\n * repository's wiring (`doctor`), a recommendation (`next`), a change between\n * two refs (`diff`) and a deploy question (`gate`). There is nothing to trail:\n * this registry is not a second copy, it is the only copy. The precedent is the\n * sibling module refusals.ts, a hand-written map that is the sole source for\n * the `ErrorCode` meanings for exactly the same reason — their prose lives in\n * doc comments, which are erased, so there is no runtime constant to read.\n *\n * What that costs, stated rather than hidden: nothing mechanical proves an\n * entry below still matches the message its emitter prints. Every meaning and\n * every fix here was written FROM the emitter — `doctor` findings carry a `fix`\n * field of their own (core/doctor/), a `next` step carries a `statement` and a\n * literal `command` (core/status/), the `DiffCode` union carries a doc comment\n * per member (core/diff/semantic.ts) — and the wording is theirs, not a\n * paraphrase invented here. Two guards catch the two failures that CAN be\n * caught: test/explain.test.ts asserts no code below is also answered by a fix\n * table (the two sources must never be able to disagree), and\n * test/agent-commands-runnable.test.ts parses every backticked `loam …` in this\n * file against the real program, so a fix naming a command loam does not have —\n * or a flag it does not declare — fails at gate time. A two-token span is a\n * NAME rather than an invocation there and is only checked for the command\n * existing, so a fix that means an invocation must carry its arguments.\n *\n * `severityNote` is the EMITTER's own word, not a fix table's parenthetical:\n * `doctor` grades blocker/warning, `diff` and `gate` grade ok/warn/error, and a\n * `next` step is graded not at all — it is a recommendation, so its note is\n * `step`. Where a code's severity depends on what was found (`doctor.docs-locked`,\n * `gate.partners-unknown`) the note says so in prose, the way the tables' own\n * long notes do (`warn here; error at archive plan time`).\n *\n * `openspec.*` and `mapping.*` — 49 codes — are deliberately NOT here, and the\n * reason is in test/explain.test.ts beside their backlog entries: they are the\n * only codes in the vocabulary whose subject is not a loam document at all.\n */\n\n/**\n * One code's answer. Structurally a `FindingEntry` (lookup.ts) minus `scope`,\n * which the family supplies — declared here rather than imported so this module\n * imports nothing at all and the package's file-level graph stays a tree.\n *\n * Every entry below is written on ONE line, however long that line runs, and\n * that is a deliberate concession to a counted limit rather than a style: 65\n * codes at four lines each is 260 lines of punctuation before a word of prose,\n * which does not fit the 400-line file limit — and src/core/explain/ is at its\n * five-file cap, so there is no second file to put the overflow in. The fields\n * stay named for the same reason a tuple was refused: `severityNote`, `meaning`\n * and `fix` say which column is which without counting commas.\n */\nexport interface FamilyEntry {\n  /** The emitter's own severity word, or the prose a conditional one needs. */\n  readonly severityNote: string;\n  /** What the code is about, in the words the emitter already prints. */\n  readonly meaning: string;\n  /** What to do — for `next.*`, that the step's own `command` IS the action. */\n  readonly fix: string;\n}\n\n/** One family: the invocation that emits it, and its codes. */\ninterface Family {\n  /** The scope label, spelled as the fix tables spell theirs — the invocation that grades it. */\n  readonly scope: string;\n  readonly codes: Readonly<Record<string, FamilyEntry>>;\n}\n\n/**\n * `loam doctor` — the preflight. Every finding here already carries a `fix`\n * field in doctor's own report (core/doctor/doctor.ts, config.ts, agents.ts,\n * residue.ts); these rows say the same thing without a repository in front of\n * them, which is the whole difference between a report and a lookup.\n */\nconst DOCTOR: Family = {\n  scope: \"loam doctor\",\n  codes: {\n    \"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.\" },\n    \"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`.\" },\n    \"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`.\" },\n    \"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.\" },\n    \"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`.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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`.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n  },\n};\n\n/**\n * `loam status` — both forms print `next[]`, and each entry carries a `code` to\n * branch on, one sentence, and the literal `command` to run. So the \"what to\n * do\" column is genuinely empty for this whole family: the step IS the action,\n * and each `fix` below names the step's own command rather than inventing a\n * second instruction beside it.\n */\nconst NEXT_STEPS: Family = {\n  scope: \"loam status\",\n  codes: {\n    \"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`.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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`.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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`.\" },\n    \"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.\" },\n    \"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`.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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`.\" },\n    \"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`.\" },\n    \"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>`.\" },\n    \"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`.\" },\n    \"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`.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n  },\n};\n\n/**\n * `loam diff` — what CHANGED between a base git ref of the docs repo and the\n * working tree, not what is WRONG with either. That is why most rows below have\n * no repair: the meanings are the `DiffCode` union's own doc comments\n * (core/diff/semantic.ts), and the two error rows are the only ones naming a\n * repair. The two `-modified` rows name work too, but not loam's: whether a\n * changed schema breaks its readers is the specialist diff's answer.\n */\nconst DIFF: Family = {\n  scope: \"loam diff --base <ref>\",\n  codes: {\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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).\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n  },\n};\n\n/**\n * `loam gate` — the can-i-deploy question, a pure query over evidence other\n * commands already recorded. Nothing here re-derives a coherence plan, so every\n * repair below is somebody else's command.\n */\nconst GATE: Family = {\n  scope: \"loam gate\",\n  codes: {\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n    \"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.\" },\n  },\n};\n\n/** In listing order, though every consumer sorts by code — the order is documentation, not contract. */\nconst FAMILIES: readonly Family[] = [DOCTOR, NEXT_STEPS, DIFF, GATE];\n\n/** One family row, in the shape `FindingEntry` (lookup.ts) takes. */\nexport interface FamilyFinding extends FamilyEntry {\n  readonly scope: string;\n}\n\n/**\n * The registry's answer for one subject, or null.\n *\n * Built per call over constants already in memory, never cached at module\n * level, for the reason lookup.ts's header gives: tests fork and chdir, and the\n * MCP server outlives many calls.\n */\nexport function familyFinding(subject: string): FamilyFinding | null {\n  for (const family of FAMILIES) {\n    const entry = family.codes[subject];\n    if (entry !== undefined) return { scope: family.scope, ...entry };\n  }\n  return null;\n}\n\n/** Every code the registry answers, sorted — the same plain sort the code inventory uses. */\nexport function familyCodes(): string[] {\n  return FAMILIES.flatMap((family) => Object.keys(family.codes)).sort();\n}\n"]}

package/dist/core/explain/fix-tables.js

@@ -0,0 +1,178 @@
+/**
+ * The fix-table parser: `loam explain`'s finding-code content, read at runtime
+ * out of the workflow bodies the binary ships. Every protocol body in
+ * `COMMANDS` is walked, so a table added to any workflow is picked up without
+ * touching this parser — today the tables live in the /loam-check body
+ * (src/core/agent/workflows/check.ts) and the /loam-verify body's notice
+ * table (src/core/agent/workflows/closing.ts).
+ *
+ * A PARSER rather than a table of its own, deliberately: the /loam-check fix
+ * tables are already the documentation corpus test/codes-drift.test.ts holds
+ * every emitted finding code against, so they are the one place the
+ * meaning-and-fix prose is guaranteed to exist and to stay current. A second
+ * copy inside an `explain` registry would be exactly the hand-maintained map
+ * that silently trails the binary — worse than no command. Reading the shipped
+ * constant instead means `loam explain spine.op-undefined` and the /loam-check
+ * page cannot disagree, because they are the same bytes.
+ *
+ * The same walk also STRIPS those tables (`withoutFixTables`), which is what
+ * `loam instructions <workflow> --no-fix-tables` prints. One walk and not two,
+ * deliberately: a stripper carrying a regex of its own would be free to
+ * disagree with the parser about where a table begins and ends, and the failure
+ * that produces is both silent and precisely the wrong one — a narrowed
+ * protocol whose omitted rows `loam explain` cannot answer, telling an agent to
+ * look up a code nothing explains. Sharing the block detection makes "what was
+ * dropped" and "what can be explained" the same computation rather than two
+ * that agree today.
+ *
+ * The row grammar this depends on (test/explain.test.ts pins it with probes
+ * and a count floor, so a table reformat fails loudly instead of leaving the
+ * lookup silently empty):
+ *
+ *   | `a.code` / `b.code` (severity note) | what it means | what to do |
+ *
+ * - the first cell holds one or more backticked codes and an optional trailing
+ *   parenthetical severity note, printed verbatim (`(warn)`, `(error, or
+ *   warn)`, `(warn, gates archive; one per service)`, `(ok)`); a row with no
+ *   note is an error, the tables' own default;
+ * - cells never contain the ` | ` separator today; if a meaning cell ever
+ *   grows one, the probes convict the mis-split rather than letting it ship;
+ * - the paragraph introducing each table (`` `--service <id>` — one service's
+ *   own axes… ``) names the scope its rows are graded in, so a code that
+ *   appears in two tables (`spec.merge-conflict`) explains both contexts.
+ */
+const CODE_SPAN = /`([a-z][a-z0-9.-]*)`/g;
+const SEVERITY_NOTE = /\(([^)]+)\)\s*$/;
+/**
+ * The scope label: the introducing paragraph's first line up to its ` — `
+ * dash, backticks stripped — "`--feature <FEAT-id>` — a change's three axes…"
+ * labels its rows `--feature <FEAT-id>`. A paragraph with no dash (none exist
+ * today) falls back to its whole first line minus the trailing colon.
+ */
+function scopeLabel(firstLine) {
+    const head = firstLine.split(" — ")[0] ?? firstLine;
+    return head.replace(/`/g, "").replace(/:$/, "").trim();
+}
+/**
+ * Split one table row into its cells, or null for a line that is not a
+ * three-cell row (the `|---|---|---|` separator has no ` | ` and yields one
+ * cell). More than three cells re-joins the tail into the fix column — the
+ * meaning cell is the split's second field either way, and the probe tests
+ * are what convict a cell that ever grows a ` | ` of its own.
+ */
+function splitRow(line) {
+    if (!line.startsWith("|") || !line.endsWith("|"))
+        return null;
+    const cells = line.slice(1, -1).split(" | ").map((cell) => cell.trim());
+    return cells.length >= 3 ? cells : null;
+}
+/**
+ * Every fix table of one workflow body, in document order, each with its rows.
+ *
+ * The scope tracking is why this walks lines rather than matching rows
+ * globally: each table's introducing paragraph ends one blank line above the
+ * header row, so the label is the most recently COMPLETED paragraph when a
+ * table opens (or the one still being built, for a table glued directly under
+ * its intro).
+ *
+ * A run of consecutive `|` lines is one block, and the first line that is not
+ * one closes it. That is the whole grammar — markdown gives a table no other
+ * terminator — and it is why the blank line after a table belongs to what
+ * follows rather than to the block.
+ */
+function fixTableBlocks(body) {
+    const lines = body.split("\n");
+    const blocks = [];
+    let paragraph = [];
+    let lastParagraph = [];
+    let scope = "";
+    let open = null;
+    for (const [index, raw] of lines.entries()) {
+        const line = raw.trimEnd();
+        if (!line.startsWith("|")) {
+            if (open !== null) {
+                blocks.push({ start: open.start, end: index, rows: open.rows });
+                open = null;
+            }
+            if (line === "") {
+                if (paragraph.length > 0)
+                    lastParagraph = paragraph;
+                paragraph = [];
+            }
+            else {
+                paragraph.push(line);
+            }
+            continue;
+        }
+        const intro = paragraph.length > 0 ? paragraph : lastParagraph;
+        if (intro.length > 0) {
+            scope = scopeLabel(intro[0]);
+            // Consumed: the next table needs its own intro, not this one again.
+            lastParagraph = [];
+            paragraph = [];
+        }
+        if (open === null)
+            open = { start: index, rows: [] };
+        const cells = splitRow(line);
+        if (cells === null)
+            continue;
+        const codeCell = cells[0];
+        const codes = [...codeCell.matchAll(CODE_SPAN)].map((m) => m[1]);
+        // The `| code | what it means | …` header row has no backticked code.
+        if (codes.length === 0)
+            continue;
+        open.rows.push({
+            codes,
+            severityNote: SEVERITY_NOTE.exec(codeCell)?.[1] ?? "error",
+            meaning: cells[1],
+            fix: cells.slice(2).join(" | "),
+            scope,
+        });
+    }
+    // A body ending mid-table has no closing line to end the block; today every
+    // body ends in prose, and a table that is the last thing in one must still
+    // be seen rather than silently dropped from the lookup.
+    if (open !== null)
+        blocks.push({ start: open.start, end: lines.length, rows: open.rows });
+    return blocks;
+}
+/** Every fix-table row of one workflow body, in document order. */
+export function parseFixRows(body) {
+    return fixTableBlocks(body).flatMap((block) => [...block.rows]);
+}
+/**
+ * The same body with every fix table collapsed to one line naming what was
+ * dropped and how to get it back.
+ *
+ * What this is FOR: /loam-check's body is 83 KB, about a fifth of a 100k-token
+ * window, and every generated command and skill file opens by telling an agent
+ * to run it. The rows are the whole of that weight and almost none of them are
+ * about the run in hand — `loam explain <code>` answers one row in 473 bytes,
+ * which is the lazy path this makes payable.
+ *
+ * The introducing PARAGRAPH stays, and that is not a formatting nicety. It is
+ * the sentence that says which scope a code was graded in (`--service <id>`,
+ * `--feature <FEAT-id>`, `loam archive`), and the same code means different
+ * things in two of them — `spec.merge-conflict` is graded on a living document
+ * and on a delta of it. Drop the intro and the remaining prose stops saying
+ * which run it is describing.
+ */
+export function withoutFixTables(body) {
+    const lines = body.split("\n");
+    const out = [];
+    let at = 0;
+    for (const { start, end, rows } of fixTableBlocks(body)) {
+        // A block with no parsed rows is not a fix table — a two-column table, or
+        // a row grammar that has moved. Left standing rather than replaced by a
+        // line claiming rows nobody can look up.
+        if (rows.length === 0)
+            continue;
+        out.push(...lines.slice(at, start));
+        out.push(`(${rows.length} row${rows.length === 1 ? "" : "s"} omitted — ` +
+            `run \`loam explain <code>\` on any code this run reports.)`);
+        at = end;
+    }
+    out.push(...lines.slice(at));
+    return out.join("\n");
+}
+//# sourceMappingURL=fix-tables.js.map

package/dist/core/explain/fix-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-tables.js","sourceRoot":"","sources":["../../../src/core/explain/fix-tables.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fix-table parser: `loam explain`'s finding-code content, read at runtime\n * out of the workflow bodies the binary ships. Every protocol body in\n * `COMMANDS` is walked, so a table added to any workflow is picked up without\n * touching this parser — today the tables live in the /loam-check body\n * (src/core/agent/workflows/check.ts) and the /loam-verify body's notice\n * table (src/core/agent/workflows/closing.ts).\n *\n * A PARSER rather than a table of its own, deliberately: the /loam-check fix\n * tables are already the documentation corpus test/codes-drift.test.ts holds\n * every emitted finding code against, so they are the one place the\n * meaning-and-fix prose is guaranteed to exist and to stay current. A second\n * copy inside an `explain` registry would be exactly the hand-maintained map\n * that silently trails the binary — worse than no command. Reading the shipped\n * constant instead means `loam explain spine.op-undefined` and the /loam-check\n * page cannot disagree, because they are the same bytes.\n *\n * The same walk also STRIPS those tables (`withoutFixTables`), which is what\n * `loam instructions <workflow> --no-fix-tables` prints. One walk and not two,\n * deliberately: a stripper carrying a regex of its own would be free to\n * disagree with the parser about where a table begins and ends, and the failure\n * that produces is both silent and precisely the wrong one — a narrowed\n * protocol whose omitted rows `loam explain` cannot answer, telling an agent to\n * look up a code nothing explains. Sharing the block detection makes \"what was\n * dropped\" and \"what can be explained\" the same computation rather than two\n * that agree today.\n *\n * The row grammar this depends on (test/explain.test.ts pins it with probes\n * and a count floor, so a table reformat fails loudly instead of leaving the\n * lookup silently empty):\n *\n *   | `a.code` / `b.code` (severity note) | what it means | what to do |\n *\n * - the first cell holds one or more backticked codes and an optional trailing\n *   parenthetical severity note, printed verbatim (`(warn)`, `(error, or\n *   warn)`, `(warn, gates archive; one per service)`, `(ok)`); a row with no\n *   note is an error, the tables' own default;\n * - cells never contain the ` | ` separator today; if a meaning cell ever\n *   grows one, the probes convict the mis-split rather than letting it ship;\n * - the paragraph introducing each table (`` `--service <id>` — one service's\n *   own axes… ``) names the scope its rows are graded in, so a code that\n *   appears in two tables (`spec.merge-conflict`) explains both contexts.\n */\n\nexport interface FixRow {\n  /** The backticked code(s) of the row's first cell — multi-code rows share one meaning. */\n  readonly codes: readonly string[];\n  /** The verbatim parenthetical from the first cell, or \"error\" — the tables' default. */\n  readonly severityNote: string;\n  /** The \"what it means\" cell, verbatim. */\n  readonly meaning: string;\n  /** The \"what to do\" cell, verbatim. */\n  readonly fix: string;\n  /** The short label of the table's introducing paragraph (`--service <id>`, `loam archive`, …). */\n  readonly scope: string;\n}\n\nconst CODE_SPAN = /`([a-z][a-z0-9.-]*)`/g;\nconst SEVERITY_NOTE = /\\(([^)]+)\\)\\s*$/;\n\n/**\n * The scope label: the introducing paragraph's first line up to its ` — `\n * dash, backticks stripped — \"`--feature <FEAT-id>` — a change's three axes…\"\n * labels its rows `--feature <FEAT-id>`. A paragraph with no dash (none exist\n * today) falls back to its whole first line minus the trailing colon.\n */\nfunction scopeLabel(firstLine: string): string {\n  const head = firstLine.split(\" — \")[0] ?? firstLine;\n  return head.replace(/`/g, \"\").replace(/:$/, \"\").trim();\n}\n\n/**\n * Split one table row into its cells, or null for a line that is not a\n * three-cell row (the `|---|---|---|` separator has no ` | ` and yields one\n * cell). More than three cells re-joins the tail into the fix column — the\n * meaning cell is the split's second field either way, and the probe tests\n * are what convict a cell that ever grows a ` | ` of its own.\n */\nfunction splitRow(line: string): string[] | null {\n  if (!line.startsWith(\"|\") || !line.endsWith(\"|\")) return null;\n  const cells = line.slice(1, -1).split(\" | \").map((cell) => cell.trim());\n  return cells.length >= 3 ? cells : null;\n}\n\n/**\n * One fix table as it sits in a body: which lines it occupies, and the rows\n * read out of them.\n *\n * The line span is what makes the stripper possible without a second notion of\n * where a table is. `start` is the header row (`| code | what it means | …`)\n * and `end` is one PAST the last table line, so `lines.slice(start, end)` is\n * exactly the block and `lines.slice(end)` is exactly what follows it — the\n * blank line and the next paragraph included, which is why the introducing\n * paragraph survives a strip.\n */\ninterface TableBlock {\n  readonly start: number;\n  readonly end: number;\n  readonly rows: readonly FixRow[];\n}\n\n/**\n * Every fix table of one workflow body, in document order, each with its rows.\n *\n * The scope tracking is why this walks lines rather than matching rows\n * globally: each table's introducing paragraph ends one blank line above the\n * header row, so the label is the most recently COMPLETED paragraph when a\n * table opens (or the one still being built, for a table glued directly under\n * its intro).\n *\n * A run of consecutive `|` lines is one block, and the first line that is not\n * one closes it. That is the whole grammar — markdown gives a table no other\n * terminator — and it is why the blank line after a table belongs to what\n * follows rather than to the block.\n */\nfunction fixTableBlocks(body: string): TableBlock[] {\n  const lines = body.split(\"\\n\");\n  const blocks: TableBlock[] = [];\n  let paragraph: string[] = [];\n  let lastParagraph: string[] = [];\n  let scope = \"\";\n  let open: { start: number; rows: FixRow[] } | null = null;\n  for (const [index, raw] of lines.entries()) {\n    const line = raw.trimEnd();\n    if (!line.startsWith(\"|\")) {\n      if (open !== null) {\n        blocks.push({ start: open.start, end: index, rows: open.rows });\n        open = null;\n      }\n      if (line === \"\") {\n        if (paragraph.length > 0) lastParagraph = paragraph;\n        paragraph = [];\n      } else {\n        paragraph.push(line);\n      }\n      continue;\n    }\n    const intro = paragraph.length > 0 ? paragraph : lastParagraph;\n    if (intro.length > 0) {\n      scope = scopeLabel(intro[0]!);\n      // Consumed: the next table needs its own intro, not this one again.\n      lastParagraph = [];\n      paragraph = [];\n    }\n    if (open === null) open = { start: index, rows: [] };\n    const cells = splitRow(line);\n    if (cells === null) continue;\n    const codeCell = cells[0]!;\n    const codes = [...codeCell.matchAll(CODE_SPAN)].map((m) => m[1]!);\n    // The `| code | what it means | …` header row has no backticked code.\n    if (codes.length === 0) continue;\n    open.rows.push({\n      codes,\n      severityNote: SEVERITY_NOTE.exec(codeCell)?.[1] ?? \"error\",\n      meaning: cells[1]!,\n      fix: cells.slice(2).join(\" | \"),\n      scope,\n    });\n  }\n  // A body ending mid-table has no closing line to end the block; today every\n  // body ends in prose, and a table that is the last thing in one must still\n  // be seen rather than silently dropped from the lookup.\n  if (open !== null) blocks.push({ start: open.start, end: lines.length, rows: open.rows });\n  return blocks;\n}\n\n/** Every fix-table row of one workflow body, in document order. */\nexport function parseFixRows(body: string): FixRow[] {\n  return fixTableBlocks(body).flatMap((block) => [...block.rows]);\n}\n\n/**\n * The same body with every fix table collapsed to one line naming what was\n * dropped and how to get it back.\n *\n * What this is FOR: /loam-check's body is 83 KB, about a fifth of a 100k-token\n * window, and every generated command and skill file opens by telling an agent\n * to run it. The rows are the whole of that weight and almost none of them are\n * about the run in hand — `loam explain <code>` answers one row in 473 bytes,\n * which is the lazy path this makes payable.\n *\n * The introducing PARAGRAPH stays, and that is not a formatting nicety. It is\n * the sentence that says which scope a code was graded in (`--service <id>`,\n * `--feature <FEAT-id>`, `loam archive`), and the same code means different\n * things in two of them — `spec.merge-conflict` is graded on a living document\n * and on a delta of it. Drop the intro and the remaining prose stops saying\n * which run it is describing.\n */\nexport function withoutFixTables(body: string): string {\n  const lines = body.split(\"\\n\");\n  const out: string[] = [];\n  let at = 0;\n  for (const { start, end, rows } of fixTableBlocks(body)) {\n    // A block with no parsed rows is not a fix table — a two-column table, or\n    // a row grammar that has moved. Left standing rather than replaced by a\n    // line claiming rows nobody can look up.\n    if (rows.length === 0) continue;\n    out.push(...lines.slice(at, start));\n    out.push(\n      `(${rows.length} row${rows.length === 1 ? \"\" : \"s\"} omitted — ` +\n        `run \\`loam explain <code>\\` on any code this run reports.)`,\n    );\n    at = end;\n  }\n  out.push(...lines.slice(at));\n  return out.join(\"\\n\");\n}\n"]}

package/dist/core/explain/lookup.js

@@ -0,0 +1,194 @@
+/**
+ * The explain lookup: one subject in — a finding code, an envelope refusal
+ * code, or a concept term — one discriminated explanation out. It also answers
+ * the two listings the command prints with no subject: `listTerms` for the
+ * concept vocabulary and `listCodes` for the code vocabulary, the latter built
+ * from the same `findingIn` the per-code answer uses so the inventory cannot
+ * describe a code differently from the page about it.
+ *
+ * Assembled ON DEMAND, never cached at module level: tests run in forked
+ * processes that chdir per invocation, and a long-running host (the MCP
+ * server) outlives many calls — a table built at import time is exactly the
+ * module-level mutable state AGENTS.md names as a hazard. The build is a walk
+ * over constants already in memory, so there is nothing worth caching anyway.
+ *
+ * Resolution order — finding tables first, then the family registry, then
+ * refusal codes, then terms — IS the tie-break: a subject in two families
+ * would silently take the earlier family's answer (a refusal named like a term
+ * alias would win over the term). No naming convention keeps them apart —
+ * `based-on` is a dashed term alias, exactly the shape a refusal code takes —
+ * so test/explain.test.ts asserts the key sets are pairwise disjoint, and the
+ * order never actually decides anything.
+ *
+ * The one place that order is load-bearing anyway is the fix tables against
+ * ./families.ts: the tables are PARSED from the bytes the binary ships and the
+ * registry is written by hand, so where both could answer, the parsed prose has
+ * to win and the hand-written row must never silently shadow it. It is written
+ * first here and asserted disjoint there, which makes the precedence a fact
+ * about the code as well as a fact about the data.
+ */
+import { COMMANDS } from "../agent/protocol.js";
+import { VALIDATE_CHECKS } from "../brief/checks.js";
+import { familyCodes, familyFinding } from "./families.js";
+import { parseFixRows } from "./fix-tables.js";
+import { REFUSAL_MEANINGS } from "./refusals.js";
+import { TERM_GROUPS, TERMS } from "./terms.js";
+/** Every fix-table row shipped in the workflow bodies, in protocol order. */
+function allRows() {
+    return COMMANDS.flatMap((command) => parseFixRows(command.body));
+}
+function briefFor(subject) {
+    return VALIDATE_CHECKS.find((check) => check.code === subject);
+}
+/** Terms match case-insensitively, by name or alias — codes stay exact, they are already lowercase by grammar. */
+function termFor(subject) {
+    const wanted = subject.toLowerCase();
+    return TERMS.find((entry) => entry.term === wanted || entry.aliases.includes(wanted));
+}
+/**
+ * The finding answer for one subject out of rows ALREADY parsed, or null when
+ * no table grades it.
+ *
+ * Split out of `explainSubject` so `listCodes` builds its rows through the
+ * very same function rather than a parallel one: the inventory's per-code
+ * payload is then the per-code answer by construction, not by two pieces of
+ * code agreeing. It also keeps the inventory's cost linear — `explainSubject`
+ * re-parses every workflow body on each call, and calling it 270 times to
+ * enumerate the vocabulary would re-walk the whole corpus 270 times.
+ */
+function findingIn(rows, subject) {
+    const brief = briefFor(subject);
+    // VALIDATE_CHECKS contributes `via` ONLY, never a fallback entry. An
+    // earlier draft synthesized a row from the brief when the tables had none,
+    // and that fallback was both unreachable (every brief check has a table
+    // row, pinned by test/explain.test.ts) and wrong if ever reached: its
+    // scope would have been the brief's invocation string, a spelling no
+    // parsed row uses. A brief check that LOSES its table row should fail
+    // loudly there — explain refusing is the tripwire — not render a
+    // one-of-a-kind page nobody else prints.
+    const entries = rows
+        .filter((row) => row.codes.includes(subject))
+        .map(({ scope, severityNote, meaning, fix }) => ({ scope, severityNote, meaning, fix }));
+    if (entries.length === 0)
+        return null;
+    return { kind: "finding", entries, ...(brief === undefined ? {} : { via: brief.via }) };
+}
+/**
+ * The finding answer from EITHER source, tables first.
+ *
+ * One function rather than two call sites choosing an order, because the order
+ * is the precedence rule: a code a fix table grades is answered from the bytes
+ * the binary ships, and ./families.ts only ever answers codes no table reaches.
+ * `via` is a fix-table-only fact — it comes from a `VALIDATE_CHECKS` entry, and
+ * no brief check names a `doctor.*`, `next.*`, `diff.*` or `gate.*` code — so a
+ * registry answer carries a single entry and nothing else, which is the same
+ * shape a one-table code already returns.
+ */
+function findingFor(rows, subject) {
+    const table = findingIn(rows, subject);
+    if (table !== null)
+        return table;
+    const family = familyFinding(subject);
+    return family === null ? null : { kind: "finding", entries: [family] };
+}
+export function explainSubject(subject) {
+    const finding = findingFor(allRows(), subject);
+    if (finding !== null)
+        return finding;
+    // Through Object.entries rather than an indexed read: the record's keys are
+    // `ErrorCode`, `subject` is an arbitrary string, and the Map lookup needs
+    // neither a key cast nor a hasOwn pre-check.
+    const refusal = new Map(Object.entries(REFUSAL_MEANINGS)).get(subject);
+    if (refusal !== undefined)
+        return { kind: "refusal", meaning: refusal };
+    const term = termFor(subject);
+    if (term !== undefined)
+        return { kind: "term", term: term.term, paragraph: term.paragraph };
+    return null;
+}
+/**
+ * Every subject `explainSubject` can answer — for the unknown-subject
+ * refusal's close-match suggestions. Sorted, so suggestion ties break the
+ * same way on every machine.
+ */
+export function knownSubjects() {
+    const known = new Set();
+    for (const row of allRows())
+        for (const rowCode of row.codes)
+            known.add(rowCode);
+    for (const familyCode of familyCodes())
+        known.add(familyCode);
+    for (const check of VALIDATE_CHECKS)
+        known.add(check.code);
+    for (const key of Object.keys(REFUSAL_MEANINGS))
+        known.add(key);
+    for (const entry of TERMS) {
+        known.add(entry.term);
+        for (const alias of entry.aliases)
+            known.add(alias);
+    }
+    return [...known].sort();
+}
+/**
+ * A paragraph's first sentence — the one-line summary form both listings
+ * print. One definition rather than two: the term listing and the code
+ * listing must cut prose the same way, or the same sentence reads as two
+ * different summaries depending on which command printed it.
+ */
+export function firstSentence(text) {
+    const cut = text.indexOf(". ");
+    return cut === -1 ? text : text.slice(0, cut + 1);
+}
+/** The no-argument listing: each term with its paragraph's first sentence as the one-line summary. */
+export function listTerms() {
+    return TERMS.map(({ term, paragraph }) => ({ term, summary: firstSentence(paragraph) }));
+}
+/**
+ * The same listing under the headings the text view prints — the subject
+ * groups of ./terms/, in order. A second function rather than a `heading` key
+ * on `listTerms`' rows: those rows are the `--json` listing's `terms[]`, whose
+ * shape is contract, and a group is typography for a reader scanning twenty
+ * terms, not a fact a caller branches on.
+ */
+export function listTermGroups() {
+    return TERM_GROUPS.map(({ heading, terms }) => ({
+        heading,
+        terms: terms.map(({ term, paragraph }) => ({ term, summary: firstSentence(paragraph) })),
+    }));
+}
+/**
+ * Every code `explainSubject` can answer — the machine-readable inventory of
+ * the vocabulary, which is otherwise discoverable only by parsing the 83 KB
+ * prose body of `loam instructions loam-check` or by reading TypeScript
+ * unions that are erased at runtime.
+ *
+ * Sorted within each kind rather than left in document order: the fix tables
+ * are ordered by scope for somebody working through one table, but an
+ * inventory is read by name and diffed between binaries, and document order
+ * would reshuffle on an unrelated table edit.
+ */
+export function listCodes() {
+    const rows = allRows();
+    // One sorted finding group over BOTH sources rather than a third listing
+    // heading. A caller building a code-to-fix cache asks "what does this binary
+    // explain", and a `doctor.*` row that arrived from ./families.ts rather than
+    // from a parsed table is the same answer to that question — the row it gets
+    // is `explain <code> --json`'s payload either way. Splitting them would put
+    // the provenance of the prose into the machine contract, where nothing
+    // branches on it.
+    const findings = [...new Set([...rows.flatMap((row) => row.codes), ...familyCodes()])]
+        .sort()
+        // Non-null: the code came out of `rows` or out of the registry, and
+        // `findingFor` reads exactly those two.
+        .map((code) => ({ code, ...findingFor(rows, code) }));
+    // Through a Map for the same reason `explainSubject` reads one: the record's
+    // keys are `ErrorCode` and this listing's are plain strings. Plain `.sort()`
+    // throughout, never `localeCompare` — the order is part of the machine
+    // contract and must not depend on the host's ICU locale.
+    const meanings = new Map(Object.entries(REFUSAL_MEANINGS));
+    const refusals = [...meanings.keys()]
+        .sort()
+        .map((code) => ({ code, kind: "refusal", meaning: meanings.get(code) }));
+    return [...findings, ...refusals];
+}
+//# sourceMappingURL=lookup.js.map

package/dist/core/explain/lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../../src/core/explain/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAmB,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAe,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAiBhD,6EAA6E;AAC7E,SAAS,OAAO;IACd,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,QAAQ,CAAC,OAAe;IAC/B,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;AACjE,CAAC;AAED,kHAAkH;AAClH,SAAS,OAAO,CAAC,OAAe;IAC9B,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACrC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACxF,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,SAAS,CAAC,IAAuB,EAAE,OAAe;IACzD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChC,qEAAqE;IACrE,2EAA2E;IAC3E,wEAAwE;IACxE,sEAAsE;IACtE,qEAAqE;IACrE,sEAAsE;IACtE,iEAAiE;IACjE,yCAAyC;IACzC,MAAM,OAAO,GAAmB,IAAI;SACjC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC3F,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;AAC1F,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,UAAU,CAAC,IAAuB,EAAE,OAAe;IAC1D,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACjC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;IAC/C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC;IACrC,4EAA4E;IAC5E,0EAA0E;IAC1E,6CAA6C;IAC7C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAiB,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACvF,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACxE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;IAC5F,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE;QAAE,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK;YAAE,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACjF,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE;QAAE,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC9D,KAAK,MAAM,KAAK,IAAI,eAAe;QAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3D,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChE,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtB,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO;YAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,SAAS;IACvB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QAC9C,OAAO;QACP,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;KACzF,CAAC,CAAC,CAAC;AACN,CAAC;AAuBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,yEAAyE;IACzE,6EAA6E;IAC7E,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,uEAAuE;IACvE,kBAAkB;IAClB,MAAM,QAAQ,GAAkB,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,WAAW,EAAE,CAAC,CAAC,CAAC;SAClG,IAAI,EAAE;QACP,oEAAoE;QACpE,wCAAwC;SACvC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAE,EAAE,CAAC,CAAC,CAAC;IACzD,6EAA6E;IAC7E,6EAA6E;IAC7E,uEAAuE;IACvE,yDAAyD;IACzD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAiB,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC3E,MAAM,QAAQ,GAAkB,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;SACjD,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,SAAkB,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAE,EAAE,CAAC,CAAC,CAAC;IACrF,OAAO,CAAC,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC;AACpC,CAAC","sourcesContent":["/**\n * The explain lookup: one subject in — a finding code, an envelope refusal\n * code, or a concept term — one discriminated explanation out. It also answers\n * the two listings the command prints with no subject: `listTerms` for the\n * concept vocabulary and `listCodes` for the code vocabulary, the latter built\n * from the same `findingIn` the per-code answer uses so the inventory cannot\n * describe a code differently from the page about it.\n *\n * Assembled ON DEMAND, never cached at module level: tests run in forked\n * processes that chdir per invocation, and a long-running host (the MCP\n * server) outlives many calls — a table built at import time is exactly the\n * module-level mutable state AGENTS.md names as a hazard. The build is a walk\n * over constants already in memory, so there is nothing worth caching anyway.\n *\n * Resolution order — finding tables first, then the family registry, then\n * refusal codes, then terms — IS the tie-break: a subject in two families\n * would silently take the earlier family's answer (a refusal named like a term\n * alias would win over the term). No naming convention keeps them apart —\n * `based-on` is a dashed term alias, exactly the shape a refusal code takes —\n * so test/explain.test.ts asserts the key sets are pairwise disjoint, and the\n * order never actually decides anything.\n *\n * The one place that order is load-bearing anyway is the fix tables against\n * ./families.ts: the tables are PARSED from the bytes the binary ships and the\n * registry is written by hand, so where both could answer, the parsed prose has\n * to win and the hand-written row must never silently shadow it. It is written\n * first here and asserted disjoint there, which makes the precedence a fact\n * about the code as well as a fact about the data.\n */\nimport { COMMANDS } from \"../agent/protocol.js\";\nimport { VALIDATE_CHECKS, type BriefCheck } from \"../brief/checks.js\";\nimport { familyCodes, familyFinding } from \"./families.js\";\nimport { parseFixRows, type FixRow } from \"./fix-tables.js\";\nimport { REFUSAL_MEANINGS } from \"./refusals.js\";\nimport { TERM_GROUPS, TERMS } from \"./terms.js\";\nimport type { TermEntry } from \"./terms/entry.js\";\n\nexport interface FindingEntry {\n  /** Which table graded it — `--service <id>`, `--feature <FEAT-id>`, `--all`, `loam archive`, … */\n  readonly scope: string;\n  /** The table's verbatim parenthetical, or \"error\" — its default. */\n  readonly severityNote: string;\n  readonly meaning: string;\n  readonly fix: string;\n}\n\nexport type Explanation =\n  | { readonly kind: \"finding\"; readonly entries: readonly FindingEntry[]; readonly via?: string }\n  | { readonly kind: \"refusal\"; readonly meaning: string }\n  | { readonly kind: \"term\"; readonly term: string; readonly paragraph: string };\n\n/** Every fix-table row shipped in the workflow bodies, in protocol order. */\nfunction allRows(): FixRow[] {\n  return COMMANDS.flatMap((command) => parseFixRows(command.body));\n}\n\nfunction briefFor(subject: string): BriefCheck | undefined {\n  return VALIDATE_CHECKS.find((check) => check.code === subject);\n}\n\n/** Terms match case-insensitively, by name or alias — codes stay exact, they are already lowercase by grammar. */\nfunction termFor(subject: string): TermEntry | undefined {\n  const wanted = subject.toLowerCase();\n  return TERMS.find((entry) => entry.term === wanted || entry.aliases.includes(wanted));\n}\n\n/**\n * The finding answer for one subject out of rows ALREADY parsed, or null when\n * no table grades it.\n *\n * Split out of `explainSubject` so `listCodes` builds its rows through the\n * very same function rather than a parallel one: the inventory's per-code\n * payload is then the per-code answer by construction, not by two pieces of\n * code agreeing. It also keeps the inventory's cost linear — `explainSubject`\n * re-parses every workflow body on each call, and calling it 270 times to\n * enumerate the vocabulary would re-walk the whole corpus 270 times.\n */\nfunction findingIn(rows: readonly FixRow[], subject: string): Extract<Explanation, { kind: \"finding\" }> | null {\n  const brief = briefFor(subject);\n  // VALIDATE_CHECKS contributes `via` ONLY, never a fallback entry. An\n  // earlier draft synthesized a row from the brief when the tables had none,\n  // and that fallback was both unreachable (every brief check has a table\n  // row, pinned by test/explain.test.ts) and wrong if ever reached: its\n  // scope would have been the brief's invocation string, a spelling no\n  // parsed row uses. A brief check that LOSES its table row should fail\n  // loudly there — explain refusing is the tripwire — not render a\n  // one-of-a-kind page nobody else prints.\n  const entries: FindingEntry[] = rows\n    .filter((row) => row.codes.includes(subject))\n    .map(({ scope, severityNote, meaning, fix }) => ({ scope, severityNote, meaning, fix }));\n  if (entries.length === 0) return null;\n  return { kind: \"finding\", entries, ...(brief === undefined ? {} : { via: brief.via }) };\n}\n\n/**\n * The finding answer from EITHER source, tables first.\n *\n * One function rather than two call sites choosing an order, because the order\n * is the precedence rule: a code a fix table grades is answered from the bytes\n * the binary ships, and ./families.ts only ever answers codes no table reaches.\n * `via` is a fix-table-only fact — it comes from a `VALIDATE_CHECKS` entry, and\n * no brief check names a `doctor.*`, `next.*`, `diff.*` or `gate.*` code — so a\n * registry answer carries a single entry and nothing else, which is the same\n * shape a one-table code already returns.\n */\nfunction findingFor(rows: readonly FixRow[], subject: string): Extract<Explanation, { kind: \"finding\" }> | null {\n  const table = findingIn(rows, subject);\n  if (table !== null) return table;\n  const family = familyFinding(subject);\n  return family === null ? null : { kind: \"finding\", entries: [family] };\n}\n\nexport function explainSubject(subject: string): Explanation | null {\n  const finding = findingFor(allRows(), subject);\n  if (finding !== null) return finding;\n  // Through Object.entries rather than an indexed read: the record's keys are\n  // `ErrorCode`, `subject` is an arbitrary string, and the Map lookup needs\n  // neither a key cast nor a hasOwn pre-check.\n  const refusal = new Map<string, string>(Object.entries(REFUSAL_MEANINGS)).get(subject);\n  if (refusal !== undefined) return { kind: \"refusal\", meaning: refusal };\n  const term = termFor(subject);\n  if (term !== undefined) return { kind: \"term\", term: term.term, paragraph: term.paragraph };\n  return null;\n}\n\n/**\n * Every subject `explainSubject` can answer — for the unknown-subject\n * refusal's close-match suggestions. Sorted, so suggestion ties break the\n * same way on every machine.\n */\nexport function knownSubjects(): string[] {\n  const known = new Set<string>();\n  for (const row of allRows()) for (const rowCode of row.codes) known.add(rowCode);\n  for (const familyCode of familyCodes()) known.add(familyCode);\n  for (const check of VALIDATE_CHECKS) known.add(check.code);\n  for (const key of Object.keys(REFUSAL_MEANINGS)) known.add(key);\n  for (const entry of TERMS) {\n    known.add(entry.term);\n    for (const alias of entry.aliases) known.add(alias);\n  }\n  return [...known].sort();\n}\n\n/**\n * A paragraph's first sentence — the one-line summary form both listings\n * print. One definition rather than two: the term listing and the code\n * listing must cut prose the same way, or the same sentence reads as two\n * different summaries depending on which command printed it.\n */\nexport function firstSentence(text: string): string {\n  const cut = text.indexOf(\". \");\n  return cut === -1 ? text : text.slice(0, cut + 1);\n}\n\n/** The no-argument listing: each term with its paragraph's first sentence as the one-line summary. */\nexport function listTerms(): Array<{ term: string; summary: string }> {\n  return TERMS.map(({ term, paragraph }) => ({ term, summary: firstSentence(paragraph) }));\n}\n\n/**\n * The same listing under the headings the text view prints — the subject\n * groups of ./terms/, in order. A second function rather than a `heading` key\n * on `listTerms`' rows: those rows are the `--json` listing's `terms[]`, whose\n * shape is contract, and a group is typography for a reader scanning twenty\n * terms, not a fact a caller branches on.\n */\nexport function listTermGroups(): Array<{ heading: string; terms: Array<{ term: string; summary: string }> }> {\n  return TERM_GROUPS.map(({ heading, terms }) => ({\n    heading,\n    terms: terms.map(({ term, paragraph }) => ({ term, summary: firstSentence(paragraph) })),\n  }));\n}\n\n/**\n * One row of the code inventory: the per-code answer with its code attached.\n *\n * DERIVED from `Explanation` rather than restated, so `loam explain <code>\n * --json` and `loam explain --codes --json` cannot describe the same code with\n * two different key sets — a caching consumer reads one and looks up the other.\n * The `term` arm is excluded on purpose: a concept term is a different kind of\n * subject, and the bare `loam explain` listing keeps them.\n *\n * There is deliberately NO `severity` or `gates` key here, and adding one\n * would be a defect rather than an improvement. A fix table carries only the\n * verbatim parenthetical its author wrote (`warn, gates archive; one per\n * service`), which is prose about a scope, while the answer a caller would\n * actually branch on is computed per ISSUE at runtime by `gatesArchive()` and\n * `approveOverrides()` in core/vocabulary/issue.ts — from `severity`, an\n * optional per-issue `gates`, and a never-overridable code set. A severity\n * derived from the parenthetical here would be a second answer to a question\n * that already has one, free to disagree with the binary's own gate.\n */\nexport type CodeListing = { readonly code: string } & Exclude<Explanation, { kind: \"term\" }>;\n\n/**\n * Every code `explainSubject` can answer — the machine-readable inventory of\n * the vocabulary, which is otherwise discoverable only by parsing the 83 KB\n * prose body of `loam instructions loam-check` or by reading TypeScript\n * unions that are erased at runtime.\n *\n * Sorted within each kind rather than left in document order: the fix tables\n * are ordered by scope for somebody working through one table, but an\n * inventory is read by name and diffed between binaries, and document order\n * would reshuffle on an unrelated table edit.\n */\nexport function listCodes(): CodeListing[] {\n  const rows = allRows();\n  // One sorted finding group over BOTH sources rather than a third listing\n  // heading. A caller building a code-to-fix cache asks \"what does this binary\n  // explain\", and a `doctor.*` row that arrived from ./families.ts rather than\n  // from a parsed table is the same answer to that question — the row it gets\n  // is `explain <code> --json`'s payload either way. Splitting them would put\n  // the provenance of the prose into the machine contract, where nothing\n  // branches on it.\n  const findings: CodeListing[] = [...new Set([...rows.flatMap((row) => row.codes), ...familyCodes()])]\n    .sort()\n    // Non-null: the code came out of `rows` or out of the registry, and\n    // `findingFor` reads exactly those two.\n    .map((code) => ({ code, ...findingFor(rows, code)! }));\n  // Through a Map for the same reason `explainSubject` reads one: the record's\n  // keys are `ErrorCode` and this listing's are plain strings. Plain `.sort()`\n  // throughout, never `localeCompare` — the order is part of the machine\n  // contract and must not depend on the host's ICU locale.\n  const meanings = new Map<string, string>(Object.entries(REFUSAL_MEANINGS));\n  const refusals: CodeListing[] = [...meanings.keys()]\n    .sort()\n    .map((code) => ({ code, kind: \"refusal\" as const, meaning: meanings.get(code)! }));\n  return [...findings, ...refusals];\n}\n"]}