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

package/dist/core/agent/workflows/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../../../src/core/agent/workflows/check.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,YAAY;IAClB,WAAW,EAAE,qDAAqD;IAClE,YAAY,EAAE,iCAAiC;IAC/C,OAAO,EACL,uMAAuM;IACzM,4EAA4E;IAC5E,uEAAuE;IACvE,2EAA2E;IAC3E,+DAA+D;IAC/D,4EAA4E;IAC5E,uEAAuE;IACvE,0EAA0E;IAC1E,qEAAqE;IACrE,2EAA2E;IAC3E,4EAA4E;IAC5E,SAAS;IACT,UAAU,EAAE,8CAA8C;IAC1D,2EAA2E;IAC3E,2EAA2E;IAC3E,gDAAgD;IAChD,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE;QACL,8GAA8G;QAC9G,2DAA2D;QAC3D,wEAAwE;QACxE,6CAA6C;KAC9C;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0SP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * The fix tables: run loam's checks and repair what they find, code by code.\n * The largest body on purpose — it is the other half of the codes-drift\n * documentation corpus (with ../agents-md/), so a new finding code gets its\n * row here.\n */\nexport const LOAM_CHECK: CommandContent = {\n  name: \"loam-check\",\n  description: \"Validate the loam docs repo and fix what it reports\",\n  argumentHint: \"[--all | <FEAT-id> | <service>]\",\n  purpose:\n    \"Run loam's checks and fix what they find. Branch on `findings[].code`, never on the prose — and remember that a coherence finding marked `gates` stops `loam archive` even when it is only a warning.\",\n  // No `$1`, unlike the other five. This body carries no placeholder at all —\n  // `loam-check`'s argument is a target you pass to `loam validate`, not\n  // something the protocol interpolates — and the argument hint's FIRST form\n  // is `--all`, so `loam instructions loam-check $1` expanded to\n  // `loam instructions loam-check --all`, which commander reads as an unknown\n  // option and refuses with exit 1. A pointer file whose one instruction\n  // fails leaves an agent with no protocol at all, which is a state the fat\n  // body could never reach. The command still tolerates a leading-dash\n  // argument (see `allowUnknownOption` in commands/instructions.ts); this is\n  // the half of the fix that stops loam printing the broken line in the first\n  // place.\n  invocation: \"loam instructions loam-check --no-fix-tables\",\n  // The one protocol whose body names no placeholder: its target (`--all`, a\n  // feature id, a service id) is spelled inside the `loam validate` line the\n  // agent chooses, not substituted into the page.\n  placeholders: [],\n  spine: [\n    \"`loam validate --all` in the docs repo for the fleet, or `loam validate <target>` for one feature or service\",\n    \"fix every error, and every finding that gates the archive\",\n    \"leave an advisory warning standing only if you can say why, and say it\",\n    \"re-run until the grade is the one you meant\",\n  ],\n  body: `Run loam's checks and fix what they find.\n\n- whole fleet: \\`loam validate --all --json\\` (run in the docs repo)\n- one target: \\`loam validate <FEAT-id | service-id> --json\\` — the feature reading is\n  tried first; \\`--feature <id>\\` / \\`--service <id>\\` force one when a name could be both,\n  and \\`target.ambiguous\\` (warn) says when a name really was both and which reading was taken\n- \\`--strict\\` (any mode) exits 1 on any warning too. Exit code only: \\`valid\\` and the\n  payload do not change, so the stricter grade lives in the CI invocation, not the repo\n- \\`--errors-only\\` drops the \\`ok\\` confirmations from the text view; the \\`--json\\`\n  payload is byte-identical either way\n- under \\`--all\\`, warn codes tied to a contract axis (\\`service.no-spec\\`,\n  \\`spec.no-requirements\\`, \\`service.no-openapi\\`'s warn form,\n  \\`spine.op-link-missing\\`, \\`permissions.unenforced\\`, \\`capability.unrealized\\`)\n  collapse in the TEXT view to one \"axis not started\" banner per axis when that\n  axis has zero participating services fleet-wide (\\`scorecard.adoption\\`) —\n  expected during staged adoption; \\`--json\\` carries every finding unchanged\n- refusals before any grading: \\`docs-missing\\` / \\`services-missing\\` (\\`docsDir\\` in\n  ./loam.json points at nothing, or at a directory with no \\`services/\\`) — run\n  \\`loam doctor\\` and fix the wiring, do not read an empty report as a clean fleet\n\nBranch on \\`findings[].code\\`, not the prose. Errors fail validate; a coherence finding\nwith \\`gates: true\\` will stop \\`loam archive\\` even when it is a warning. Fix every\nerror and every gating finding. Leave an advisory warning only if you can say why,\nand say it.\n\n\\`--service <id>\\` — one service's own axes (\\`--all\\` runs these for every service):\n\n| code | what it means | what to do |\n|---|---|---|\n| \\`service.unknown\\` | no \\`services/<id>/\\` at all — the id is a typo until proven otherwise | use one of the ids the message offers, or \\`loam list services\\`; never \\`loam adopt\\` a misspelling |\n| \\`service.no-model\\` | the directory is real but there is no model.likec4 | run \\`loam adopt\\` for it — without the C4 center nothing else has anywhere to hang |\n| \\`c4.invalid\\` | model.likec4 does not parse | fix this first — an unreadable axis makes every other check meaningless |\n| \\`c4.no-relationships\\` (warn) | the model parses, declares elements, and no relationship joins anything — while its own evidence says it should reach something: more than one nested element, or dependencies declared in this service's health.yaml. A model that reaches nothing is almost never true; without this check, a 2-element model with 0 relationships and a 19-element model with 19 relationships could receive the same green verdict | draw the edges the service actually has — what its containers call, what reads and writes its stores, what it depends on at runtime. A bare root-plus-one-container baseline with no other evidence stays silent on purpose: nothing proves it thin |\n| \\`requirements.missing-scenarios\\` | a requirement with no scenario | add the acceptance criteria; do not delete the requirement |\n| \\`requirements.stepless-scenario\\` | a scenario with a heading and no recognizable steps — it satisfies the coverage rule and tests nothing: cucumber runs it vacuously green and \\`loam verify --results\\` can never confirm it. Graded on spec.md and arch.spec.md alike, in \\`--service\\` and \\`--feature\\` scope both, because a stepless scenario in a delta merges into the living spec and is called covered forever after | write the body as \\`- **Given/When/Then**\\` bullets |\n| \\`requirements.assertionless-scenario\\` | a scenario with steps and no \\`Then\\` anywhere in its body — it arranges and acts and asserts nothing, so the run confirms only that the setup did not throw and the \\`scenario.tested\\` claim is answered on that. Disjoint from \\`stepless\\` by construction (that one has no steps at all), graded in the same four places | add the \\`- **Then**\\` the scenario was written for. \\`And\\`/\\`But\\` are continuations: with no \\`Then\\` above them they continue the setup |\n| \\`requirements.examples-unbound\\` (error) | a scenario with an \\`Examples\\` table uses a \\`<placeholder>\\` no column supplies — cucumber substitutes nothing, so the step definition receives the literal angle-bracket text. Steps, docstrings and data-table cells all count as uses, because cucumber substitutes into all three | add the column, or correct the placeholder to one the header names |\n| \\`requirements.examples-unreferenced\\` (warn) | an \\`Examples\\` column no step, docstring or data-table cell refers to — usually the fossil of a rename, and the outline then runs its rows as identical passes that read as cases of coverage | reference the column from a step, or drop it |\n| \\`spec.merge-conflict\\` | a requirement document still holds \\`<<<<<<<\\` / \\`=======\\` / \\`>>>>>>>\\` markers — nobody wrote what it now says. Graded on living spec.md/arch.spec.md and on a feature's deltas of them, in both scopes | resolve the conflict in the file the finding names. \\`loam archive\\` refuses (\\`merge-failed\\`) on a conflicted living document it would rewrite, and \\`--approve\\` does not override it: the merge rewrites the requirements section and takes whichever marker lines fall inside it, so a conflict anyone can see would become a document nobody can tell is wrong |\n| \\`spec.duplicate-requirement\\` | one \\`### Requirement:\\` name defined twice in one living spec.md or arch.spec.md — a merge edits only the first, the rest live on as stale copies | keep exactly one block per name (merge the bodies); the two files are separate namespaces, so a name in both is fine |\n| \\`spec.requirement-id-invalid\\` | a \\`Requirement-ID\\` violates \\`[A-Za-z][A-Za-z0-9._-]{0,127}\\` | replace it with a portable stable ID; do not remove an established ID merely to silence the check |\n| \\`spec.requirement-id-repeated\\` | one requirement declares \\`Requirement-ID\\` more than once | keep exactly one identity line |\n| \\`spec.requirement-id-duplicate\\` | one ID identifies multiple requirements in the same file | give each requirement its own stable ID |\n| \\`openapi.generated-stale\\` (warn) | \\`loam.json\\` names \\`contracts.openapi\\` — where this repo's BUILD writes its contract — and that document differs from the committed \\`services/<id>/openapi.yaml\\`. The docs-repo copy is what every operation join is graded against, so the fleet is being checked against a contract the service no longer serves. Compared by a digest over canonical JSON, so key order and formatting never fire it. Service-repo only; silent with no \\`contracts\\` block | review the difference and copy the generated document across — loam never writes it for you, because the committed contract is one somebody agreed to, not a cache of the build |\n| \\`contracts.source-missing\\` (error) | \\`contracts.openapi\\` names a path and nothing is there — usually CI validating before it builds | run the build first, or correct the path |\n| \\`contracts.source-invalid\\` (error) | \\`contracts.openapi\\` resolves outside the repository, or names a file that does not parse as YAML or JSON | correct the path, or fix the document the build emitted |\n| \\`spec.unknown-directive\\` (warn) | a requirement body line whose key is one or two edits from a directive and is not one — \\`Realises:\\`, \\`Capabilties:\\`, \\`Opertaions:\\`. This is the one case where the corpus is quieter than it looks: an unrecognised key is prose, so the join it resembles simply does not exist and every check over it stays green for want of anything to fail. Measured by edit distance, not by prefix, so ordinary prose keys (\\`Note:\\`, \\`Context:\\`, \\`Owner:\\`) do not fire it; fenced blocks and table cells are skipped, because a directive spelling inside an example is a sample value | correct the spelling, or reword the line so it does not read as a directive |\n| \\`spec.repeated-operations\\` (warn) | a second \\`Operations:\\` line in one requirement body — the last line REPLACES the earlier ones, whose list is silently lost (living specs and feature deltas alike) | merge them into one comma-separated \\`Operations:\\` line |\n| \\`spec.repeated-covers\\` (warn) | same for \\`Covers:\\` — the last line wins, the earlier list is silently lost | merge them into one comma-separated \\`Covers:\\` line |\n| \\`spec.no-requirements\\` (warn) | a LIVING spec.md with no \\`### Requirement:\\` block at all — every requirement-driven check below it is vacuous, not passing | write the requirements, or say in the file why the service has none yet |\n| \\`service.unreadable\\` | an artifact of this service could not be read (permissions, a dangling symlink) — nothing about the service was checked, and the rest of the fleet still was | fix the file the finding names; a service silently skipped would have read as a clean one |\n| \\`service.no-spec\\` (warn) | no living spec.md — a part-adopted service, legal but unchecked | write it; until it exists, requirement coverage and API governance are vacuous |\n| \\`service.no-openapi\\` (error, or warn) | no openapi.yaml — deleted, renamed, or never written. ERROR when something already written down joins into the absent file: a LIVING non-REMOVED requirement's \\`Operations:\\` line, or a landscape edge carrying \\`metadata { op }\\` into this service. The finding's \\`details\\` list the stranded operationIds. WARN when nothing joins into it but the landscape cannot prove nobody calls this service (it is absent, or it does not parse). Silent when the landscape parses and no edge calls an operation here — a worker, a cron or a UI owes no contract | error: put the file back — every link the \\`details\\` name resolves to nothing until it is there. If the operations are genuinely gone, retire them through a feature delta (REMOVED requirement + \\`x-loam-remove\\` marker) instead of deleting the contract out from under them. warn: write the contract, or model the service in the fleet map so it shows no one expects an API |\n| \\`openapi.invalid\\` | openapi.yaml exists but does not parse — an unreadable contract proves nothing, so no \\`api.*\\` or spine finding is graded against it (before this code, the empty parse graded every inbound edge \\`spine.op-undefined\\`). The same code fires for a FEATURE's own openapi.yaml under \\`--feature\\`, where it gates the archive and suspends the service's contract-axis checks the same way | fix the YAML first — the API axis is unchecked until it reads |\n| \\`openapi.remove-marker-living\\` | a living openapi.yaml contains feature-only \\`x-loam-remove: true\\` | remove the marker from living; retire the operation through a feature delta with a matching REMOVED requirement |\n| \\`openapi.duplicate-operationid\\` (warn) | one operationId occupies two (path, method) slots in a living contract — every join on the id (a requirement's \\`Operations:\\` line, an edge's \\`metadata { op }\\`, a removal marker) then picks one of them arbitrarily | give each slot its own id; the identity of an operation is its path and method, and the id is how the other axes name it |\n| \\`openapi.response-undescribed\\` (warn) | operation(s) whose responses declare no schema at all (204/304 excepted) — the contract names the operation and says nothing about what it returns, so a reader still needs the code. A presence probe: what a declared schema SAYS is still never checked | declare \\`content\\` with a \\`schema\\` on at least one response of each named operation |\n| \\`openapi.ref-unresolved\\` (warn here; error at archive plan time) | internal \\`$ref\\`(s) in the living contract that resolve to nothing in the document — the operation validates while its schema is silently absent. External refs (not starting \\`#/\\`) are never checked | define the missing component or fix the pointer the \\`details\\` name |\n| \\`openapi.baseline-stale\\` | the living operation — or a pinned path-level key or component — changed after this delta edited it | somebody landed a change to it in between. Re-read the living value, fold in what you still mean, then \\`loam rebase <FEAT>\\` |\n| \\`openapi.baseline-missing\\` (warn, gates archive; one per service) | operations, path-level keys or components in this feature's openapi.yaml carry no baseline (\\`x-loam-based-on\\` / \\`x-loam-baselines\\`) | run \\`loam rebase <FEAT>\\`. Until you do, archive refuses: the merge cannot tell the surfaces you EDITED from the ones you merely restated, so it would upsert all of them — and every restated one reverts whatever landed on it. \\`--approve\\` merges unpinned deliberately |\n| \\`openapi.baseline-invalid\\` | an \\`x-loam-based-on\\` that is not a digest, one on an operation the living contract has no slot for, a malformed \\`x-loam-baselines\\` record, or a record entry naming a surface the delta does not restate (or whose living value is gone) | \\`loam rebase\\` writes both; a new value has no living version to be based on, so it carries no entry |\n| \\`spec-api.op-undefined\\` | a LIVING requirement's \\`Operations:\\` line names an operationId this service's openapi.yaml does not define (the same code fires inside a feature delta) | define the endpoint, or correct the \\`Operations:\\` line — the two axes disagree about what the service exposes |\n| \\`api.ungoverned\\` (warn) | operation(s) no requirement's \\`Operations:\\` line names | write the requirement, or link an existing one |\n| \\`api.ops-unlinked\\` (warn) | operations AND requirements exist but zero \\`Operations:\\` lines join them — the API axis is vacuously green | link each requirement to the operations it governs |\n| \\`api.requirement-deprecated\\` (warn) | a requirement's \\`Operations:\\` list resolves only to operations the OpenAPI marks \\`deprecated: true\\` — the behaviour it governs is on its way out | migrate the requirement to the replacement operation, or retire it with the ops it governs |\n| \\`spine.landscape-invalid\\` | the living landscape does not parse, so the C4↔API spine cannot be checked | fix architecture/landscape.likec4 first |\n| \\`spine.op-undefined\\` | a landscape edge calls an operation this service's OpenAPI does not define | a broken contract between services — fix the edge or add the endpoint |\n| \\`spine.op-link-missing\\` (warn) | a landscape \"Calls\" edge into this service with no \\`metadata { op }\\` | link it to the operationId |\n| \\`spine.op-deprecated\\` (warn) | a landscape edge calls an operation this service's OpenAPI marks \\`deprecated: true\\` — the consumer is standing on a contract being retired | migrate the consumer to the replacement operation; deprecation is the first step of retiring an op, and the op stays defined until a human removes it |\n| \\`service.no-asyncapi\\` | no asyncapi.yaml, and message link(s) already point into it — a landscape edge's \\`metadata { publishes }\\` / \\`metadata { consumes }\\`, or a LIVING requirement's \\`Publishes:\\` / \\`Consumes:\\` line. The \\`details\\` list the stranded message names. Silent when nothing joins into it: an async contract is optional, and most services touch no topic | put the file back — every link the \\`details\\` name resolves to nothing until it is there |\n| \\`asyncapi.invalid\\` | asyncapi.yaml exists but does not parse — an unreadable contract proves nothing, so no \\`event.*\\` or message-spine finding is graded against it. The same code fires for a FEATURE's own asyncapi.yaml under \\`--feature\\`, where it gates the archive and suspends the service's event-axis checks the same way | fix the YAML first — the event axis is unchecked until it reads |\n| \\`asyncapi.remove-marker-living\\` | a living asyncapi.yaml carries feature-only \\`x-loam-remove: true\\` — at a \\`channels.<key>\\` / \\`operations.<key>\\` / \\`components.messages.<key>\\` slot, or nested on an inline channel message | remove the marker from the living contract; retire a slot through a feature delta's asyncapi.yaml instead |\n| \\`asyncapi.duplicate-message\\` (warn) | one message name is declared in two slots — every join on the name (an edge's \\`metadata { publishes }\\`, a requirement's \\`Publishes:\\` line) then picks one of them arbitrarily | give each declaration its own name, or factor the second into a \\`$ref\\` at the first |\n| \\`asyncapi.payload-undescribed\\` (warn) | message(s) whose payload declares no shape at all — absent, or bare \\`type: object\\` with not one property. The name joins the spine while nothing defines what a consumer would read. A presence probe: a payload declaring a non-JSON \\`schemaFormat\\` (Avro) is never judged | declare \\`properties\\` on the payload, or the \\`schemaFormat\\` of its non-JSON schema |\n| \\`asyncapi.ref-unresolved\\` (warn) | internal \\`$ref\\`(s) that resolve to nothing in the document — the target used to vanish silently: an operation's message-list entry contributed no name, and a dangling channel alias left a phantom key | fix or define the pointers the \\`details\\` name |\n| \\`spine.message-undefined\\` | a landscape edge \\`publishes\\`/\\`consumes\\` a message this service's asyncapi.yaml declares no \\`action: send\\`/\\`receive\\` operation for | declare the operation, or correct the edge — the fleet map and the contract disagree about what this service puts on the wire |\n| \\`spec-event.message-undefined\\` | a LIVING requirement's \\`Publishes:\\` / \\`Consumes:\\` line names a message this service's asyncapi.yaml does not declare in that direction | declare it, or correct the line |\n| \\`spine.message-unproduced\\` | this service consumes a message that NO service in the fleet and NO \\`#external\\` element declares is sent — no producer anywhere. The inverse of \\`spine.op-undefined\\`, and it has no HTTP analog: on the API axis the provider owns the contract and the check is local, while an event's schema lives in the producer's repo | find the producer and have it declare the message (an outside-the-fleet producer is declared on its \\`#external\\` element: an edge with \\`metadata { publishes '<msg>' }\\`), or correct the name — a consumer joined to nothing reads a payload nothing defines |\n| \\`spine.message-external\\` (warn) | this service consumes a message whose only declared producer is an \\`#external\\` element — produced outside the fleet, so no contract will ever appear in a \\`services/<id>/\\`, and this service's own asyncapi.yaml currently defines no shape for it. Fires on positive evidence (the \\`publishes\\` edge), so unreadable contracts elsewhere do not suspend it | declare the message in THIS service's asyncapi.yaml with its payload — the consumer's copy is the only contract the fleet can hold; once it declares a shape, the finding stops |\n| \\`asyncapi.message-contested\\` (warn) | two or more services declare they send one message name — every consumer's join picks one of them arbitrarily | namespace the message by its owning domain; one message has one producer, and which contract a consumer reads must not be a coin flip |\n| \\`event.messages-unlinked\\` (warn) | messages AND requirements exist but zero \\`Publishes:\\`/\\`Consumes:\\` lines join them — the event axis is vacuously green | link each requirement to the messages it governs |\n| \\`event.ungoverned\\` (warn) | message(s) declared in asyncapi.yaml that no requirement's \\`Publishes:\\`/\\`Consumes:\\` line names — \\`api.ungoverned\\`'s event twin, and the per-message half \\`event.messages-unlinked\\` cannot see: that code stays silent once even one message is linked | write the requirement that governs each named message, or drop the declaration |\n| \\`covers.unknown\\` (warn) | a \\`Covers:\\` entry in arch.spec.md resolves to no element, edge, alert or SLI — living and feature deltas alike | fix the id (the message offers close ones); a mistyped entry silently costs the coverage it was written for |\n| \\`api.response-ungoverned\\` (warn) | an operation declares a 4xx/5xx response that no scenario of any requirement governing it reaches. \\`api.ungoverned\\` grades whole OPERATIONS, so an endpoint with one happy-path requirement and twelve declared failure codes was fully governed by every other check — and the refusals are where the decision layer lives | write the refusal as a scenario, or as a row in an existing one. A scenario reaches a code when the number appears in its body, \\`Examples\\` rows included |\n| \\`obligation.unknown\\` | a \\`#obl-<name>\\` tag on the LIVING fleet map that \\`architecture/obligations.yaml\\` does not declare. An ERROR, and the asymmetry with its sibling below is the point: a tag that resolves to nothing reads exactly like a rule the fleet keeps, in review and in every derived view. \\`details\\` names every object carrying it | fix the tag (the message offers close names), or declare the obligation |\n| \\`obligation.unapplied\\` (warn) | a declared obligation that no \\`#obl-\\` tag applies anywhere on the map — the mirror of \\`permissions.unenforced\\`, and it earns its place for the same reason: a vocabulary is worth what cites it. Either a decision that was reversed and left its word behind, or one nobody has placed yet | tag the elements and edges it governs, or drop the declaration |\n| \\`obligation.uncovered\\` (warn) | a tagged element or edge that no LIVING requirement's \\`Covers:\\` line names — the obligation is placed and nothing says it is met. \\`c4.uncovered\\`'s question asked of the map the fleet actually runs on, rather than of a feature's \\`delta.likec4\\`. One finding per tagged object, \\`subject\\` = the service that owns it, so a fleet report reads as a worklist per team. Only a tag that RESOLVES is asked: an undeclared one has earned its error already | write the requirement in that service's \\`arch.spec.md\\` with the \\`Covers:\\` entry the message spells out, and a scenario that proves it — or drop the tag if the decision no longer applies there |\n| \\`obligation.adr-missing\\` | an obligation's \\`adr:\\` field names no file. The ADR is where the decision itself is written, so a pointer at nothing leaves every tag citing a rule nobody can read | fix the path (relative to the docs repo root), write the record, or drop the field |\n| \\`obligation.invalid\\` | \\`architecture/obligations.yaml\\` exists but does not read as a vocabulary. Reported ALONE and the family suspended behind it: every \\`#obl-\\` tag resolves against this file, so grading them on top would be a cascade, not a diagnosis. An id that a LikeC4 tag name cannot carry refuses the file here too — the id IS the tag suffix, and a rejected character truncates the tag rather than failing it | fix the YAML — the shape is \\`obligations: {<id>: {description, adr}}\\`, ids spelled with letters, digits, \\`_\\` and \\`-\\` only |\n| \\`permissions.unknown\\` | a \\`Requires:\\` entry in spec.md or arch.spec.md names a \\`<subject>/<permission>\\` that \\`architecture/permissions.yaml\\` does not declare. An ERROR where its \\`Covers:\\` sibling is a warning: an invented permission reads exactly like a real one in the requirement, in the generated scenario, and in the test somebody then writes against it | fix the spelling (the message offers close ones), or declare the permission in the fleet vocabulary |\n| \\`permissions.invalid\\` | \\`architecture/permissions.yaml\\` exists but does not read as a vocabulary. Reported alone: every \\`Requires:\\` line in the fleet resolves against it, so grading them on top would be a cascade, not a diagnosis | fix the YAML — the shape is \\`subjects: {<kind>: …}\\` then \\`permissions: {<kind>: {<name>: …}}\\`, and a permission under an undeclared subject kind is refused |\n| \\`permissions.unenforced\\` (warn) | a declared permission no requirement's \\`Requires:\\` line names, anywhere in the fleet — the mirror of \\`api.ungoverned\\`. Either a rule that was removed and left its word behind, or a word nobody adopted | write the requirement that gates on it, or drop the declaration; a vocabulary is worth what cites it |\n| \\`capability.unknown\\` | a \\`Capability:\\` entry in spec.md or arch.spec.md — living at the service target, or a feature's delta of either, where it gates \\`loam archive\\` (\\`--approve\\` overrides) — that NEITHER \\`architecture/capabilities.yaml\\` nor \\`capabilities/<id>/spec.md\\` declares. Silent when the fleet has neither (those FILES are this axis's opt-in, unlike \\`Requires:\\`) or the YAML is invalid | fix the spelling (the message offers close ones), or declare the capability — a name alone goes in the YAML, a name with prose gets the document |\n| \\`capability.invalid\\` | \\`architecture/capabilities.yaml\\` exists but does not read as a vocabulary. Reported exactly once per \\`--all\\` run, and the whole family is suspended behind it — including the archive gate, so an unknown name CAN merge while the file is broken; fix the YAML before trusting the axis | fix the YAML — the shape is \\`capabilities: {<id>: {description, owner}}\\`, ids flat keys with \\`/\\` allowed for nesting |\n| \\`capability.unrealized\\` (warn) | a declared capability that no living non-REMOVED requirement's \\`Capability:\\` line names — one warning PER capability, subject = the id, and the message names which side declared it. Either a promise nobody implemented or a word nobody adopted, and invisible from inside the file | write the requirement that realizes it (\\`loam list capabilities\\` shows the whole rollup), or drop the declaration |\n| \\`capability.doc-missing\\` (warn) | a directory in EITHER capability tree that holds no \\`spec.md\\` and has no capability beneath it — what \\`mkdir\\` leaves behind halfway through creating one. Under living \\`capabilities/\\` it declares nothing, so a \\`Capability:\\` line naming it still reports \\`capability.unknown\\` while a reader browsing the tree counts it as a capability. Under \\`features/<FEAT>/capabilities/\\` it is quieter: an empty directory is not a delta, so the merge carries nothing and the business change ships as zero. \\`subject\\` is the directory as it sits on disk, so it says which tree | living: write \\`capabilities/<id>/spec.md\\` (the narrative, then \\`## Requirements\\`). In a feature: write \\`features/<FEAT>/capabilities/<id>/spec.md\\` (a \\`## ADDED Requirements\\` section, ids and all). Either way, or remove the directory |\n| \\`capability.requirement-unidentified\\` | a requirement in \\`capabilities/<id>/spec.md\\` — living, or a feature's \\`features/<FEAT>/capabilities/<id>/spec.md\\` delta of it, where it gates \\`loam archive\\` (\\`--approve\\` overrides) — with no \\`Requirement-ID:\\` line. Optional in a service spec for OpenSpec compatibility, REQUIRED here: a capability document outlives every service that realizes it, so rewording a heading would be a removal and an addition, and every join made to it would break silently. Graded on what the delta would MERGE, so a REMOVED requirement is exempt | add \\`Requirement-ID: <id>\\` as the first body line |\n| \\`capability.requirement-service-scoped\\` | a requirement in \\`capabilities/<id>/spec.md\\` — living, or a feature's delta of it, where it gates \\`loam archive\\` (\\`--approve\\` overrides) — carrying \\`Operations:\\`, \\`Covers:\\`, \\`Publishes:\\` or \\`Consumes:\\` — each resolves against one service's own contract or model, so the requirement is a service requirement filed at the wrong altitude. This is the checkable half of \"a capability requirement is observable outside the fleet\"; the naming-no-service half is an authoring rule PR review holds, because matching service names in prose is a heuristic loam will not run | move it into that service's spec.md, where the line resolves — what belongs in the capability document is the promise, not the mechanism |\n| \\`capability.requirement-inert-join\\` | a requirement in \\`capabilities/<id>/spec.md\\` — living, or a feature's delta of it, where it gates \\`loam archive\\` (\\`--approve\\` overrides) — carrying \\`Capability:\\` or \\`Realizes:\\`: the axis's own two joins, which point INTO the tree and so do nothing written inside it. The rollup joins SERVICE requirements to capabilities, so a \\`Capability:\\` line here claims the document it is already in, and a \\`Realizes:\\` line here points at a promise loam will never see anybody keep. Refused rather than ignored because both parse and both read exactly like the working joins one directory over | delete the line; the join that matters is written on the service requirement, as \\`Realizes: <capability-id>#<Requirement-ID>\\` |\n| \\`capability.realizes-unknown\\` | a \\`Realizes:\\` entry in spec.md or arch.spec.md — living at the service target, or a feature's delta of either, where it gates \\`loam archive\\` (\\`--approve\\` overrides) — that names no capability requirement. Five distinct failures, each with its own fix in the message: the entry is not spelled \\`<capability-id>#<Requirement-ID>\\`; the capability is undeclared; it is declared but has no document; the document declares no requirements yet; or it declares requirements but not this id. Silent under the same ladder as \\`capability.unknown\\` | follow the message — it names which of the five happened, and offers close names where there are any |\n| \\`capability.realizes-stale\\` (warn) | a PINNED \\`Realizes:\\` entry whose capability requirement has been rewritten since the pin was stamped. The join still resolves — the address is fine and the promise behind it moved, which no existence check can see. Only pinned entries are graded, so a corpus that has never run \\`loam rebase --living\\` produces none of these, ever | re-read \\`capabilities/<id>/spec.md\\` and decide which side is now wrong: change this requirement, change the promise, or — when this requirement is still right as it stands — \\`loam rebase --living\\` to record the re-read |\n| \\`capability.requirement-unrealized\\` (warn) | a requirement in a capability document that no living service requirement's \\`Realizes:\\` line names, one warning PER requirement, subject = the \\`<capability>#<id>\\` entry an author would type to fix it. The sharper sibling of \\`capability.unrealized\\`, and the one that survives a healthy-looking row: a capability with four requirements and three realized reports nothing at all through the other code | add the line to each service requirement that carries part of the promise — or leave it, if the promise is genuinely not implemented yet: writing the business document ahead of the fleet is the intended use, which is why this warns and never gates |\n| \\`capability.uncovered\\` (warn, GATES archive) | a requirement a feature's \\`features/<FEAT>/capabilities/<id>/spec.md\\` ADDS that no ADDED or MODIFIED requirement in the same feature's \\`specs/\\` deltas names with \\`Realizes: <capability-id>#<Requirement-ID>\\`, subject = the capability id. A WARNING because the document is legal — writing a promise ahead of the fleet is the intended use — that GATES because the merge is what is unsafe: once it lands, the only thing that will ever mention the promise again is \\`capability.requirement-unrealized\\`, a fleet-scope warning nobody reads. MODIFIED is exempt (the promise may already be realized by living text), and a requirement with no \\`Requirement-ID:\\` is left to \\`capability.requirement-unidentified\\` alone | add the \\`Realizes:\\` line to the service requirement that carries part of the promise; or, if the promise CROSSES services, write the flow that keeps it as \\`features/<FEAT>/usecases/<name>.likec4\\` — a views-only document holding one \\`dynamic view\\` tagged \\`#cap-<capability>\\` and \\`#req-<requirement>\\`, which \\`loam archive\\` merges into \\`architecture/usecases/\\` and \\`loam unarchive\\` takes back; or \\`loam archive <FEAT> --approve\\` to land the promise ahead of the fleet and let \\`capability.requirement-unrealized\\` carry it |\n| \\`usecase.flow-invalid\\` | a \\`features/<FEAT>/usecases/*.likec4\\` loam could not read against the map this feature's own merge would leave behind — a parse error, a hop naming an element the merge does not land, or a landscape merge that itself refuses. The flows were NOT graded, and the archive would copy them into \\`architecture/\\` for the next reader's \\`loam validate --all\\` to fail on. \\`--approve\\` does NOT move it (\\`overridable: false\\`): that flag overrides loam's judgment about coherence, never its ability to read an axis | fix what the message names. A hop into an element the feature adds is legal — the flow is graded against the POST-MERGE map — so the usual cause is a spelling that matches neither the living landscape nor \\`delta.likec4\\` |\n| \\`capability.remove-requirement-realized\\` | the same join in the removal direction: a feature's capability delta REMOVES a requirement that something the merge leaves behind still names with \\`Realizes:\\` — a living service requirement this feature does not also change, or one of its own ADDED/MODIFIED requirements. Without it the archive succeeded and the very next \\`loam validate --all\\` failed with \\`capability.realizes-unknown\\` against a service document nobody in the feature had touched. An ERROR, exactly as \\`openapi.remove-op-consumed\\` is for the identical shape one axis over; \\`--approve\\` overrides | retire the realizing requirement in the same feature, or drop its \\`Realizes:\\` line (a MODIFIED does that by restating the requirement without it), or \\`loam archive <FEAT> --approve\\` to break the join deliberately |\n| \\`glossary.term-exists\\` | a \\`features/<FEAT>/glossary/<term>.md\\` whose term the LIVING glossary already defines. The merge is a whole-file copy, so it would replace an authored definition wholesale — and \\`--approve\\` does NOT move this one (\\`overridable: false\\` in the \\`--json\\` refusal), because approving it is approving a deletion nobody described. A feature-local glossary document INTRODUCES a term; it does not rewrite one | delete the feature's copy and edit \\`glossary/<term>.md\\` directly in the same change, where git produces an ordinary conflict if somebody else is editing it too |\n| \\`usecase.flow-exists\\` | a \\`features/<FEAT>/usecases/<name>.likec4\\` whose flow the LIVING \\`architecture/usecases/\\` already holds. The merge is a whole-file copy, so it would replace an authored hop sequence wholesale — and \\`--approve\\` does NOT move this one (\\`overridable: false\\` in the \\`--json\\` refusal), because a \\`dynamic view\\`'s ordered steps are written down in no other document the fleet keeps. A feature-local flow INTRODUCES a use case; it does not rewrite one | delete the feature's copy and edit \\`architecture/usecases/<name>.likec4\\` directly in the same change, where git produces an ordinary conflict if somebody else is editing it too |\n| \\`glossary.unlinked\\` (warn) | a term defined in \\`glossary/<term>.md\\` that no document OUTSIDE \\`glossary/\\` links to — the mirror of \\`permissions.unenforced\\` and \\`capability.unrealized\\`, and it earns its place for their reason: a vocabulary is worth what cites it. A term cited only by OTHER TERMS is still unlinked and the citing terms are listed in \\`details\\` — a glossary is a network of definitions, so \\`order-line\\` linking to \\`order\\` says the glossary is consistent, not that the fleet uses the word. When NOTHING outside cites anything it is one finding for the whole glossary rather than one per term, because that is one afternoon's work and not N breaches. Warn and never a gate: writing the vocabulary ahead of the fleet is the intended use | cite the term from the requirement, capability or intent that uses it — \\`[Order](../../glossary/order.md)\\` — or delete the definition. \\`loam list glossary\\` shows every term with the documents that cite it |\n| \\`link.unresolved\\` | a markdown link in an authored document whose relative target names nothing. ONE finding per document, listing every broken link with its line, because a rotted set of links is one editing session rather than ten separate breaches. The corpus is every authored markdown document: both spec axes living and delta, \\`runbook.md\\`, every \\`adrs/\\` file at all three altitudes, \\`intent.md\\`, and each capability document — the fleet's own ADRs and living capability tree are graded once, on the \\`landscape\\` target, and never repeated per service. Three things are deliberately NOT graded, each of them a question loam has no answer to: a target outside the docs repo (that tree may not be checked out beside these documents), a bare \\`#section\\` anchor, and anything inside a fenced block or an inline code span. CASE **is** graded — a link resolves only when each path segment is spelled the way the directory stores it, and when only the case is wrong the finding names the stored spelling, so a link that works on a Windows laptop and 404s on GitHub is caught here rather than in review | fix the path, or write the document it points at. A link here is a join of the same kind as \\`Operations:\\` and \\`Covers:\\` — write it as a relative path, which is the only form that can resolve |\n| \\`link.unreadable\\` | a document in that corpus could not be decoded — almost always UTF-16, which PowerShell's \\`>\\` and \\`Out-File\\` write unasked. Its links were not checked; everything else about the service or feature still was, which is exactly why this is not \\`service.unreadable\\` | re-save the file as UTF-8 (\\`Out-File -Encoding utf8\\`) |\n| \\`docs.commit-interrupted\\` | a \\`.loam-commit\\` journal sits in the docs repo: a writer's commit never finished, so the living docs may be half-merged — nothing graded in the same run can be trusted to describe one state, and a green here would certify bytes no run produced | run the command the finding names (it recovers first), or \\`loam doctor\\` for the file-by-file account; the finding leads every validate mode until the journal is gone |\n| \\`health.invalid\\` (warn) | health.yaml exists but does not parse — alert/SLI ids are unreadable, so \\`Covers: alert:/sli:\\` entries and health coverage are unchecked (a missing health.yaml is legal and silent; an unreadable one used to masquerade as \\`covers.unknown\\` typos) | fix the YAML — the health axis resumes once it reads |\n| \\`health.uncovered\\` (warn) | health.yaml declares an alert or SLI no arch.spec.md requirement covers | write the arch requirement with \\`Covers: alert:<id>\\` / \\`Covers: sli:<id>\\` — a signal nothing tests is dashboard decoration |\n| \\`health.dependency-unmodelled\\` (warn) | a \\`dependencies:\\` id in health.yaml that nothing in this service's OWN model.likec4 answers to — by element id, \\`metadata { service }\\` binding, or title. Resolved against the service model, never the landscape: the model carries everything the service touches (private stores included, as nested containers), and the on-call file must name the same world. Either a dependency nobody modelled, or one that no longer exists — for example, a disabled optional service registry left as \\`critical: startup\\` under a green validator | model it (an external system as its own element with the real edge; a private store as a nested container), correct the id to one of the element's three names, or delete the entry |\n| \\`gherkin.missing\\` (warn) | a living scenario no generated .feature scenario carries a digest for — the suite has no test for these words. Fires only in the service's repo, once \\`<gherkinDir>/loam/\\` exists | \\`loam gherkin --service <id>\\` regenerates the suite |\n| \\`gherkin.stale\\` (warn) | a generated scenario's digest matches no living scenario while its requirement still exists — the spec moved under the file (a reworded scenario reports stale + missing together) | regenerate; never edit a generated file to catch it up |\n| \\`gherkin.orphaned\\` (warn) | a generated file whose requirement no longer exists in the living spec (a file for a feature still in flight is exempt — it answers to its feature until it archives) | regenerate; the orphaned file is deleted and reported |\n| \\`gherkin.path-outside\\` | this repo's \\`gherkinDir\\` resolves outside the repository — a \\`..\\` segment, an absolute path, or a symlink pointing away — so generating would write where nothing here can review it. Refused before any file is read, not repaired | point \\`gherkinDir\\` in loam.json at a directory INSIDE this repository; it is the suite's own home, and a path outside it is a write nobody's diff would show |\n| \\`evidence.checked\\` (ok) | every evidence pin on the federated verification records this service attested re-resolved clean against this working tree. Fires only in the service's own repo, like \\`sources.*\\` — from the docs repo the whole \\`evidence\\` family is silent | nothing — it is the confirmation |\n| \\`evidence.unpinned\\` (ok) | agent-confirmed citations recorded before evidence pins existed, so nothing can grade their drift | the next \\`loam verify <FEAT> --service <id> --record\\` stamps pins; not work on its own |\n| \\`evidence.unresolved\\` (warn) | a pinned citation cannot be re-checked: the cited file is gone, unreadable, unsafe, not a regular file, or the cited line is past its end | re-read the evidence in this tree, re-answer, and re-record from this repo — a pin lint never moves the verdict by itself |\n| \\`evidence.moved\\` (warn) | a cited file's normalized sha256 differs from the pin while the cited line's text survives — the mildest drift: the file changed around the citation | re-read the cited file; re-record once the answers are re-checked |\n| \\`evidence.line-changed\\` (warn) | the cited line no longer says what the pin recorded — the citation no longer shows what it showed | re-read the evidence and re-answer; the claim may still be true, but this line no longer backs it |\n| \\`evidence.token-missing\\` (warn) | the cited file contained the literal the claim asserts (the operationId, message name or edge op the pin carries as \\`token\\`) at the attested commit, and no longer does — a token the commit never contained is warned once at record time and never stamped, so this grade always convicts a disappearance | check whether the code moved or the claim stopped being true; re-answer and re-record from this repo |\n| \\`evidence.record-unreadable\\` (warn) | a feature's verification.yaml exists but cannot be read as a record (broken YAML, a malformed \\`evidence_pins\\` block, a summary contradicting its claims) — none of its evidence was checked, and a silent skip would read as clean | repair the YAML by hand, or re-record from this repo; loam never overwrites a record it could not read |\n\n\\`--feature <FEAT-id>\\` — a change's three axes against each other. The SAME checks\ngate \\`loam archive\\` (errors block it; warnings never do), so a clean run here is\nwhat lets a feature ship:\n\n| code | what it means | what to do |\n|---|---|---|\n| \\`delta.invalid\\` | delta.likec4 does not parse | fix this first — an unreadable axis makes every other check meaningless |\n| \\`delta.nothing-tagged\\` | the delta declares elements/relationships but none carry \\`#<FEAT>\\` | tag what IS the change — untagged parts are context, and archive merges only tags |\n| \\`delta.service-unknown\\` | a \\`specs/<svc>/\\` directory addresses a service that neither exists as \\`services/<svc>/\\` nor is introduced by this feature's own tagged delta.likec4 — a typo in \\`--touches\\`, which archive would otherwise materialise as a phantom service directory | fix the id (the message offers close ones); suspended while \\`delta.invalid\\` stands, because an unparseable delta cannot be asked what it introduces |\n| \\`delta.service-id-invalid\\` | a \\`specs/<svc>/\\` DIRECTORY NAME that is not a legal service id (a space, a \\`..\\`, a Windows-reserved stem like \\`NUL\\`, a trailing dot) — archive would materialise \\`services/<svc>/\\` from it, a directory every authoring command then refuses to address (\\`service.id-invalid\\`). Never suspended: the name is illegal whatever the delta says | rename the specs/ directory to a legal id; \\`--approve\\` does not override this one — the breakage is mechanical, not a judgment call |\n| \\`spec.merge-conflict\\` | a spec delta (\\`specs/<svc>/spec.md\\` or \\`arch.spec.md\\`) still holds \\`<<<<<<<\\` / \\`=======\\` / \\`>>>>>>>\\` markers — the same code and the same sentence as service scope, because the markers merge into the living document as prose under somebody's requirement | resolve the conflict before archive; the merge rewrites the requirements section and the marker lines inside it disappear with it |\n| \\`requirements.stepless-scenario\\` | a scenario in a spec delta with a heading and no steps — same code as service scope, and it merges into the living spec as a requirement the coverage rule calls covered from then on | write the body as \\`- **Given/When/Then**\\` bullets |\n| \\`requirements.assertionless-scenario\\` | a scenario in a spec delta with steps and no \\`Then\\` — same code as service scope, and it merges into the living spec as acceptance criteria that assert nothing | add the \\`- **Then**\\` the scenario was written for |\n| \\`requirements.examples-unbound\\` / \\`requirements.examples-unreferenced\\` | a delta scenario whose \\`Examples\\` header and \\`<placeholders>\\` disagree — same codes and same sentences as service scope | add or correct the column; reference it, or drop it |\n| \\`spec-api.op-undefined\\` | a requirement governs an operation its provider's OpenAPI does not define | define the endpoint, or correct the \\`Operations:\\` line |\n| \\`spec-api.op-pending\\` (warn) | the governed operation is defined by another feature in flight | archive that feature first |\n| \\`c4-api.op-undefined\\` | an edge calls an operation the target does not expose | a broken contract between services — fix the caller or add the endpoint |\n| \\`c4-api.op-pending\\` (warn) | the called operation is defined by another feature in flight | archive that feature first |\n| \\`c4-api.op-deprecated\\` (warn) | a NEW tagged edge consumes an operation the living provider's OpenAPI marks \\`deprecated: true\\` — building new consumption on a dying op (quiet when this feature's own openapi delta drops the flag: that IS the un-deprecation) | point the edge at the replacement operation, or say why the deprecated one is right; never gates archive |\n| \\`c4-api.op-removing\\` | a NEW tagged edge consumes an operation this feature removes | remove or redirect the new edge; one feature cannot retire and add consumption of the same operation |\n| \\`openapi.remove-target-missing\\` | an \\`x-loam-remove: true\\` marker's exact path+method does not exist in living OpenAPI | update the stale marker to the current slot, or drop it if the operation is already gone |\n| \\`openapi.remove-target-mismatch\\` | the marker's operationId differs from the living operation at that path+method | name the living operation exactly; loam never deletes the different operation occupying the slot |\n| \\`openapi.remove-marker-missing\\` | a REMOVED requirement governs an operation but the feature has no removal marker | add the exact path/method operation with its operationId and \\`x-loam-remove: true\\` to the feature openapi.yaml |\n| \\`openapi.remove-marker-unjustified\\` | a removal marker is not named by any REMOVED requirement's \\`Operations:\\` line | remove the marker or retire the governing requirement in the same feature |\n| \\`openapi.remove-marker-anonymous\\` | an \\`x-loam-remove: true\\` marker with no \\`operationId\\` — loam cannot tell which operation it retires, and the marker itself would be written into the living contract | name the operation the marker retires, exactly as the living contract spells it |\n| \\`openapi.remove-op-consumed\\` | the feature retires an operation the LIVING fleet still consumes — a landscape edge's \\`metadata { op }\\`, or another service's living requirement naming it | fix the consumer in the same feature (redirect the edge, retire its requirement), or archive with \\`--approve\\` if the consumer is already gone in code |\n| \\`c4-event.message-undefined\\` | a tagged edge \\`publishes\\`/\\`consumes\\` a message its bound service's asyncapi contract — as this feature's merge would leave it; feature ∪ living where no delta exists — declares no matching \\`action: send\\`/\\`receive\\` operation for | declare the operation in the feature's asyncapi.yaml, or correct the edge |\n| \\`c4-event.message-pending\\` (warn) | the named message is introduced by another feature in flight | archive that feature first |\n| \\`spec-event.message-undefined\\` | a delta requirement's \\`Publishes:\\`/\\`Consumes:\\` line names a message the service's asyncapi contract — as this feature's merge would leave it, so a retired declaration stops answering and a leftover line on a surviving requirement is caught before it breaks the post-archive fleet — does not declare in that direction; the same code validate gives the living-side breach | declare it in the feature's asyncapi.yaml, retire the line with its requirement, or correct it |\n| \\`spec-event.message-pending\\` (warn) | the named message is introduced by another feature in flight | archive that feature first |\n| \\`asyncapi.baseline-missing\\` (warn, gates archive; one per service) | slots or component surfaces in this feature's asyncapi.yaml carry no baseline pin (\\`x-loam-based-on\\` / \\`x-loam-baselines\\`) | run \\`loam rebase <FEAT>\\` — until then the merge cannot tell the slots and surfaces you EDITED from the ones you merely restated, and every restated one would revert whatever landed on it. \\`--approve\\` merges unpinned deliberately |\n| \\`asyncapi.baseline-stale\\` | the living slot, or the living component surface, changed after this delta pinned it | somebody landed a change in between. Re-read the living value, fold in what you still mean, then \\`loam rebase <FEAT>\\` |\n| \\`asyncapi.baseline-invalid\\` | an \\`x-loam-based-on\\` that is not a digest or one on a slot the living contract has no counterpart for; a malformed \\`x-loam-baselines\\` record, or an entry of it naming a component surface the delta does not declare (or whose living value is gone) | \\`loam rebase\\` writes both; a new channel, operation, message or component has no living version to be based on, so it carries no pin |\n| \\`asyncapi.remove-target-missing\\` | an \\`x-loam-remove: true\\` marker addresses a slot the living asyncapi does not have | update the stale marker to the current key, or drop it if the slot is already gone |\n| \\`asyncapi.remove-target-mismatch\\` | the marker's message name differs from the living declaration at that key | name the living message exactly; loam never deletes a different message occupying the slot |\n| \\`asyncapi.remove-marker-missing\\` | a REMOVED requirement's \\`Publishes:\\`/\\`Consumes:\\` line names a message the living contract still declares, with no matching marker in the feature's asyncapi.yaml | add the \\`components.messages\\` entry with the message's name and \\`x-loam-remove: true\\`; a message the living contract declares only INLINE under a channel is retired by that channel's own removal marker (\\`channels.<key>: {x-loam-remove: true}\\`) instead |\n| \\`asyncapi.remove-marker-unjustified\\` | a message-removal marker no REMOVED requirement's \\`Publishes:\\`/\\`Consumes:\\` line justifies (channel and operation slots need exactness only — requirements never join on their keys) | remove the marker, or retire the governing requirement in the same feature |\n| \\`asyncapi.remove-message-consumed\\` | the feature retires a message the LIVING fleet still consumes — a landscape \\`consumes\\` edge, or another service's living \\`Consumes:\\` requirement | fix the consumer in the same feature (drop the edge, retire its requirement), or archive with \\`--approve\\` if it is already gone in code |\n| \\`asyncapi.message-conflict\\` (warn) | two features in flight add or edit the same (service, message) | whichever archives second replaces the other's declaration wholesale — coordinate before either ships |\n| \\`c4.op-ungoverned\\` (warn) | an operation is called but no requirement governs it | write the requirement |\n| \\`c4.op-link-missing\\` (warn) | a \"Calls\" edge in the delta with no \\`metadata { op }\\` | link it to the operationId |\n| \\`c4.service-binding-invalid\\` | an explicit \\`metadata { service }\\` binding — a tagged element's, or an untagged child's anywhere inside its block, since the merge splices the whole authored block verbatim — is not a legal \\`services/<id>/\\` name (a space, a \\`../\\`, a Windows-reserved stem); archive would write the name into the living landscape, and a \\`../\\` collapses its \\`services/\\` probe out of the docs repo | fix the binding to the directory the element means; \\`--approve\\` does not override this one — the path the name becomes is mechanical, not a judgment call |\n| \\`api.op-unconsumed\\` (warn) | an added operation no edge consumes | model the caller, or say why it is provider-only |\n| \\`service.no-requirement-delta\\` (warn) | a new service with no spec delta | write \\`specs/<svc>/spec.md\\` |\n| \\`scaffold.placeholder\\` (warn, gates archive) | a feature document still carries \\`loam new\\`'s exact placeholder text — a \\`TODO — name the behaviour\\` requirement, a \\`TODO — name the case\\` scenario, an \\`<angle-bracket>\\` fill-in, or a \\`TODO — what this service owns\\` description | write the real content; the merge would otherwise publish a requirement or description nobody authored. \\`--approve\\` overrides |\n| \\`intent.empty\\` (warn, gates archive) | intent.md is missing, or its Why/Scope hold nothing outside the scaffold's own comments | write why the feature exists — it is the first thing a reviewer reads. \\`--approve\\` overrides |\n| \\`archedge.uncovered\\` (warn) | no scenario names a tagged edge (a heuristic) | write the scenario, or say why the edge needs none |\n| \\`c4.uncovered\\` (warn) | a NEW tagged element or edge in delta.likec4 that no arch requirement covers via \\`Covers:\\` — the mechanical check, not the heuristic above | add the requirement to \\`specs/<svc>/arch.spec.md\\` (outbox? retries? alerts?), or the architectural obligations ship unchecked |\n| \\`delta.unknown-section\\` | a heading that nearly matches the delta grammar | fix it — everything under it merges as NOTHING today, silently |\n| \\`delta.no-delta-sections\\` | requirements, but no \\`## ADDED/MODIFIED/REMOVED Requirements\\` section anywhere — the whole delta would merge nothing | put every changed requirement under its delta section |\n| \\`delta.requirement-not-merged\\` (warn, gates archive) | a requirement under a prose heading (\\`## Behavior\\`) instead of a delta section | move it under \\`## ADDED\\`/\\`## MODIFIED\\`/\\`## REMOVED Requirements\\` — as written, archive drops it. If it really is documentation, quote it under \\`## Requirements\\`, which is exempt |\n| \\`delta.requirement-id-invalid\\` / \\`delta.requirement-id-repeated\\` / \\`delta.requirement-id-duplicate\\` | a stable ID is malformed or ambiguous inside the delta | repair it before archive; identity is never inferred from an invalid declaration |\n| \\`delta.living-requirement-id-invalid\\` | the living file's IDs are malformed or ambiguous | repair the living spec first; the delta cannot select it safely |\n| \\`delta.requirement-identity-collision\\` | the delta's ID and heading point at different living requirements | fix the ID or heading; archive will not guess which identity should win |\n| \\`delta.modified-unknown\\` | MODIFIED a requirement the living spec does not have | use ADDED, or fix the name (a spelling slip reads as a different requirement) |\n| \\`delta.removed-unknown\\` | REMOVED one that does not exist | drop the section, or fix the name |\n| \\`delta.added-duplicate\\` | ADDED a name the living spec already has | use MODIFIED — as written, the merge REPLACES the living requirement |\n| \\`delta.added-near-duplicate\\` (warn) | ADDED a name that differs only in case from a living requirement — the merge matches exactly, so both would coexist | match the living spelling and use MODIFIED, or pick a distinct name |\n| \\`delta.living-duplicate-requirement\\` | two requirements in the LIVING document share one heading — MODIFIED rewrites only the first and REMOVED deletes both, so no delta applies to it predictably | fix the living spec first (merge the bodies, or give each a distinct heading and a \\`Requirement-ID\\`); the delta cannot select safely until you do |\n| \\`delta.modified-pending\\` (warn) | the requirement is introduced by another feature in flight | archive that feature first — \\`loam dependencies --json\\` computes the whole ordering (\\`order\\`), so you do not have to work it out per finding |\n| \\`delta.removed-pending\\` (warn) | REMOVED something another feature in flight introduces | archive that feature first; \\`loam dependencies --json\\` says in which order |\n| \\`delta.added-conflict\\` (warn) | two features in flight add the same requirement | whichever archives first lands it; the other's ADDED then collides with the living spec (\\`delta.added-duplicate\\`, error) and its archive is refused — coordinate now, or rework the later one as MODIFIED after the first ships. No ordering fixes it, which is why \\`loam dependencies\\` reports it under \\`conflicts\\` rather than in \\`order\\` |\n| \\`delta.modified-conflict\\` (warn) | another feature in flight MODIFIES or REMOVES the same living requirement | both deltas apply cleanly, so whichever archives second replaces the other's text wholesale — \\`loam dependencies\\` lists it under \\`conflicts\\`; merge the two intentions before either ships |\n| \\`delta.baseline-stale\\` | the living requirement changed after this delta was written against it | someone landed a change in between and this MODIFIED would replace it outright. Re-read the living requirement, fold in what you still mean, then \\`loam rebase <FEAT>\\`. Re-pinning without re-reading is how you overwrite them on purpose |\n| \\`delta.baseline-missing\\` (warn, gates archive) | a MODIFIED/REMOVED requirement with no \\`Based-On:\\` | run \\`loam rebase <FEAT>\\` — until then nothing can say whether the living text moved under this delta, and archive refuses to merge it. Expected on deltas adopted from OpenSpec, which never carried the line: one rebase pins the whole feature, and \\`--approve\\` merges unpinned deliberately |\n| \\`delta.baseline-invalid\\` | a \\`Based-On:\\` that is not a digest, declared twice, or sitting on an ADDED requirement | \\`loam rebase\\` writes the value; an ADDED requirement has no living version to be based on, so drop the line or make it MODIFIED |\n\n\\`--all\\` — everything above for every target, plus the fleet cross-check:\n\n| code | what it means | what to do |\n|---|---|---|\n| \\`landscape.missing\\` | \\`architecture/landscape.likec4\\` does not exist — an ERROR as soon as \\`services/\\` holds one service, a warning only in an empty docs repo | create it: a \\`specification { ... }\\` block declaring the kinds, then a \\`model { ... }\\` block with one bound element per service (\\`metadata { service '<id>' }\\`) and one edge per cross-service call carrying \\`metadata { op '<operationId>' }\\`. With no fleet map every cross-service check is blind, not passing |\n| \\`landscape.invalid\\` | the living landscape does not parse | fix it first — the fleet cross-check cannot run against a document nobody can read |\n| \\`service.id-invalid\\` | a \\`services/<id>/\\` directory whose name is not a legal service id — every authoring command refuses it, so nothing in that directory can be changed through loam. Fleet scope only: the SET of service directories is what makes the id a question, and a \\`--service\\` run is already refused by its own guard before it gets this far (the guard refuses only a name that neither exists as a directory nor is a legal id — a badly-named directory that DOES exist resolves through the enumeration and grades as an ordinary target, still without this finding). Graded before the map is opened, so it stands even when the landscape is missing or unreadable | rename the directory, then update its \\`service:\\` frontmatter, its \\`metadata { service }\\` binding in the landscape, and any \\`features/<FEAT>/specs/<id>/\\` naming it |\n| \\`subsystem.unmarked\\` | a directory under \\`services/\\` that is neither a subsystem (no \\`subsystem.yaml\\`) nor a service (no service artifact), with directories beneath it — the shape an ordinary merge produces when one branch deletes an emptied subsystem's marker while another moves a service in. The services beneath STAY enumerated and the finding names every one of them: the fleet is never reported smaller than it is | restore \\`subsystem.yaml\\` in that directory (an empty file is a valid marker), or move the directories out |\n| \\`subsystem.marker-misplaced\\` | \\`subsystem.yaml\\` sitting BESIDE service artifacts (spec.md, model.likec4, …) — a directory is a subsystem or a service, never both; it stays classified as a service | delete the marker, or move the artifacts into a service directory of their own inside the group |\n| \\`subsystem.name-collision\\` | one name claimed by two or more directories in the \\`services/\\` tree — service ids and subsystem names share one flat namespace, unique at any depth, because a service's identity is its leaf directory name alone and placement never disambiguates it. The message names every claimant | rename all but one, then update whichever frontmatter, landscape bindings and \\`features/<FEAT>/specs/<id>/\\` name the renamed service |\n| \\`subsystem.name-invalid\\` | a subsystem directory name that breaks the id grammar (a space, a \\`..\\`, a Windows-reserved stem, a trailing dot) — subsystem names take the service-id grammar because both become directory names in one shared tree. Its services stay enumerated meanwhile | rename the directory to a legal name |\n| \\`subsystem.invalid\\` | a \\`subsystem.yaml\\` that exists but cannot be read as subsystem metadata — presence still classifies the directory as a subsystem (content is metadata, never identity), and exactly one finding is emitted per file | fix the file: a YAML mapping with optional \\`title\\`, \\`description\\` and \\`owner\\`; never \\`members\\` — the directory itself is the membership record. An empty file is also a valid marker |\n| \\`subsystem.views-stale\\` | \\`architecture/subsystems.likec4\\` — the GENERATED file holding one LikeC4 view per subsystem — does not match the tree: it drifted after a move, it is absent while subsystems exist, or it lingers after the last subsystem was removed. One error on one file, graded by byte comparison against the deterministic re-render (no check ever reads the file's content) | run \\`loam subsystem sync\\` — the single regenerator. Never edit the file by hand; authored views belong in the landscape or a file of your own |\n| \\`subsystem.view-id-collision\\` | \\`architecture/landscape.likec4\\` declares a view whose id is one loam GENERATES into \\`architecture/subsystems.likec4\\`. LikeC4 merges every file in \\`architecture/\\` into one project and view ids are a flat namespace there, so the renderer refuses the WHOLE project and draws nothing — while every other check here stays green. Only a real collision is reported: a \\`subsystem_\\`-looking id matching no current subsystem breaks nothing yet, and fires on the run after somebody creates that subsystem | rename the view in \\`architecture/landscape.likec4\\`. Ids beginning \\`subsystem_\\` are loam's to mint; \\`architecture/subsystems.likec4\\` is generated (\\`loam subsystem sync\\`) and is never hand-edited |\n| \\`landscape.merge-conflict\\` | the fleet map still holds conflict markers — it is two halves of two different maps, and every cross-service check reads it. Checked BEFORE the parse and returns like \\`landscape.invalid\\`: nothing is concluded from the file, so no \\`landscape.service-unmodelled\\` fires behind it | resolve it keeping BOTH sides' elements and edges; ten people adopting ten services into one landscape.likec4 in the same week is how it happens. \\`loam archive\\` refuses on it too (\\`merge-failed\\`, not overridable with \\`--approve\\`) |\n| \\`landscape.service-unmodelled\\` | a \\`services/<svc>/\\` no element in the landscape resolves to | draw it, or bind an existing element with \\`metadata { service '<svc>' }\\` — the fleet map is incomplete until you do |\n| \\`landscape.service-undocumented\\` (warn) | a landscape element with no \\`services/<id>/\\` | document the service, bind the element to the directory it means, or tag it \\`#external\\` if it is not ours |\n| \\`landscape.binding-unknown\\` | an element's \\`metadata { service }\\` names a directory that does not exist | fix the id or create the service — a binding is a claim, and this one is false |\n| \\`landscape.binding-duplicate\\` (warn) | two elements resolve to the same \\`services/<id>/\\` | every element→service join picks one of them arbitrarily, so the other's edges are filed under a service that does not own them — bind each element to the directory it actually is, or tag the stray one \\`#external\\` |\n| \\`landscape.kind-tag-graded\\` | the \\`specification\\` block declares \\`#external\\` or \\`#platform\\` on an element KIND, and at least one element of that kind stands for a real \\`services/<id>/\\` — bound with \\`metadata { service }\\`, or titled like one. Since LikeC4 1.59.0 a kind's tags land on every element of it, and loam reads both tags as \"not ours, stop grading\", so the exemption is silencing the checks for a service of yours; the run would otherwise end on \\`landscape.matched\\` over a map nothing checked | remove the tag from the kind and write \\`#external\\` / \\`#platform\\` on the individual elements that really are foreign — or stop drawing your own services as that kind. A graded tag on a kind whose elements stand for no directory of yours (the \\`element topic { #external }\\` idiom for the topics inside a broker) is correct and stays silent, and any OTHER tag is safe on any kind — loam does not read it |\n| \\`landscape.platform-candidate\\` (warn) | an \\`#external\\` element consumed by three or more services and not tagged \\`#platform\\` — a hub on its way to making the fleet view unreadable | declare \\`tag platform\\` in the \\`specification\\` block and tag the element (LikeC4 refuses an undeclared tag, so both steps are needed): the fleet view then excludes it, and a platform view over \\`include * -> element.tag = #platform\\` keeps \"who depends on it\" answerable |\n| \\`landscape.datastore-private\\` (warn) | a datastore element with exactly one consumer service at fleet level — drawn as a peer, it reads as a system in its own right | it is that service's internals: move it into \\`services/<id>/model.likec4\\` as a nested container and delete it from the landscape, or add the second consumer's edge if another service really reaches the same data |\n| \\`landscape.datastore-shared\\` (warn) | a datastore element consumed by two or more services — the strongest coupling in the fleet, stated rather than inferred | shared means the same DATA: if they read the same tables or keys, keep it drawn and let the warning state the coupling; if they only share a host or cluster (two schemas, two lock paths), model one private store per service and put the blast radius in the runbook |\n| \\`usecase.capability-unresolved\\` | a \\`dynamic view\\` tagged \\`#cap-<slug>\\` whose slug matches no declared capability id, or more than one. The tag spells the id with every character outside \\`[A-Za-z0-9_-]\\` flattened to \\`-\\` (that is all a LikeC4 tag name accepts) and that flattening is not injective, so \\`payments/refunds\\` and \\`payments-refunds\\` both answer to one tag. Silent while \\`architecture/capabilities.yaml\\` is absent or invalid, like the rest of that family — the FILE is the capability axis's opt-in | zero matches: fix the tag, or declare the capability in the fleet vocabulary (the message offers close ids, each already spelled as the tag you would write). More than one: rename one of the colliding ids — nothing in the tag can say which the flow realizes, and a guess files every hop of it under an owner who never claimed it |\n| \\`usecase.requirement-unresolved\\` | a \\`dynamic view\\` tagged \\`#req-<slug>\\` whose slug names no requirement of the capability that view is about. Six failures with six fixes, and the message says which: the view resolves no \\`#cap-\\` tag (a \\`Requirement-ID\\` is unique only inside its own document, so the id has no scope), it resolves two (nothing says which document), the capability has no \\`capabilities/<id>/spec.md\\`, that document declares no requirements yet, it declares none flattening to this slug, or two of its ids flatten to one slug. It suppresses NOTHING: only a RESOLVED claim counts as a promise kept, so a broken tag leaves \\`capability.requirement-unrealized\\` firing beside it | follow the message. Several \\`#req-\\` tags on one view are legal and normal — a flow commonly keeps two of a capability's promises |\n| \\`usecase.step-unbacked\\` | a hop of a capability-tagged \\`dynamic view\\` that NO relationship in the model backs, on either tier. LikeC4 reports no error for it — a dynamic view is allowed to show a call the model never declared — so the diagram renders, the project parses, and every other check stays green. The finding names the file the view was written in, the step's ordinal and title, and the oriented pair | draw the edge in \\`model { }\\` (with \\`metadata { op '<operationId>' }\\` where it is a call), or, if the hop is a return step, write it as \\`<target> <- <source>\\`: a reply is attributed to the CALL it answers, so the \\`<-\\` spelling looks the hop up under the reversed pair instead |\n| \\`usecase.step-contested\\` (warn) | two or more relationships back one hop and they name DIFFERENT operations — an absent \\`metadata { op }\\` counts as a value there, not as a gap — so nothing can say which one the hop exercises. \\`details\\` lists every candidate as \\`<source> -> <target> \"<title>\" (op: <id>)\\` | give the candidates one operation, or draw the hop between the elements that name exactly one. loam names them rather than picking, because a guessed operation reads exactly like a right one in every rollup built over the flow. It suppresses \\`usecase.step-unlinked\\` on the same hop: one breach, one finding |\n| \\`usecase.step-unlinked\\` (warn) | the relationship backing a hop carries no \\`metadata { op }\\` and no \\`publishes\\`/\\`consumes\\`, while the hop's CALLER is not a person and its target resolves to a real \\`services/<id>/\\` — the flow reaches the fleet map and stops short of the contract it drives. \\`spine.op-link-missing\\` at use-case altitude. A hop FROM a person never fires it — the first hop of almost every sequence diagram is somebody using the app, and an app owes no operationId for a click — and neither does a hop INTO an \\`#external\\` system, an actor, a database, a cache or a queue: none of those owns a contract to name. A \\`publishes\\`/\\`consumes\\` edge already reaches an API — an AsyncAPI one | add \\`metadata { op '<operationId>' }\\` to the edge in \\`model { }\\`, or \\`metadata { publishes '<message>' }\\` / \\`consumes\\` where the hop is an event |\n| \\`feature.unreadable\\` | an artifact of a feature in flight could not be read — nothing about that feature was graded, and the rest of the fleet still was | fix the file the finding names; a feature silently skipped would have read as a clean one |\n| \\`sources.unverifiable-from-here\\` (ok) | one finding PER SERVICE whose \\`sources\\` only its own repo can check — a confirmation, not work, so it never trips \\`--strict\\`, and it is present in \\`--service\\` runs from the docs repo too | run \\`loam validate --service <id>\\` from inside that service's repo to actually grade its provenance; the fleet rollup line is derived from these findings |\n| \\`docs.binary-behind\\` (warn) | the docs repo's AGENTS.md stamp names a loam NEWER than the one running. This is the one finding that changes what a PASS means: a binary predating a grammar addition does not fail on the newer directive, it reads it as prose, has no join to fail, and reports green — so the corpus was checked less than the run implies. Warn rather than error because a mixed-version fleet is ordinary; \\`--strict\\` is the lever if it should gate | upgrade loam and re-run. Do NOT edit AGENTS.md — its stamp is correct and this binary is the older half |\n| \\`agents.stale\\` (warn) | the docs repo's AGENTS.md has no version stamp, or one older than the running binary — its flag and code tables may describe a loam that no longer exists | review AGENTS.md against the current \\`loam --help\\`, then update the \\`<!-- generated by loam vX.Y.Z -->\\` line; a hand-curated file silences it by bumping the stamp itself. Never regenerate the file — the team's edits outrank the template |\n\nfrontmatter and provenance — services' spec.md and arch.spec.md, and features'\nintent.md, both modes:\n\n| code | what it means | what to do |\n|---|---|---|\n| \\`frontmatter.missing\\` (warn) | no frontmatter at all | add owner, status and sources |\n| \\`frontmatter.malformed\\` | the frontmatter block does not parse as YAML — owner, status and sources are unreadable, which is not the same fact as absent | fix the header; the field checks and the sources chain resume once it parses — never add fields to a block YAML refuses |\n| \\`frontmatter.field-mismatch\\` | the doc names a different service/feature than the one it lives under | fix the frontmatter, or move the file |\n| \\`frontmatter.status-unknown\\` | a status nobody defined (\\`verifed\\`) | use the documented vocabulary — a typo here reads as unverified forever |\n| \\`frontmatter.field-missing\\` (warn) | owner, status or the identity field is absent | fill them in |\n| \\`sources.absent\\` (warn) | the doc names no sources | nothing ties it to the code, so nothing can tell you when it goes stale |\n| \\`sources.path-missing\\` | a listed source no longer exists, or is a glob pattern (no longer supported) | the code moved — re-read it and update the doc, do not just fix the path. For a pattern, name files or directories instead |\n| \\`sources.path-outside\\` | a listed source resolves OUTSIDE the service's repository — an absolute path, a \\`..\\` escape, or a path that only exists on one machine. loam will not hash bytes beyond the repo boundary, so the tie the entry claims cannot be checked | name the path repo-relative, inside the repository; if the document was really written from another repo's files, it belongs to that repo |\n| \\`sources.stale\\` (warn) | the source files changed since the doc was vouched for — the finding names which paths were added, changed or removed, from the \\`sources_files\\` index the stamp carries | re-read the code at exactly those paths, correct the doc, then ask a human to \\`loam vouch --service <id>\\` |\n| \\`sources.empty\\` (warn) | the declared \\`sources\\` exist but expand to no files at all — an empty directory, or a tree the repository ignores. A digest over nothing reads as current forever | point \\`sources\\` at the files the document was actually written from; \\`loam vouch\\` refuses to stamp this state with the same sentence |\n| \\`sources.skipped\\` (warn) | a path under a listed source was found but NOT hashed: a symlink loam will not follow (its target is outside the repository, dangling, or not a file or directory) — the digest cannot go stale over bytes it never read | not yours to close by editing the document: either the symlink should not be under a listed source, or \\`sources\\` should name the real path. Report it |\n| \\`sources.unvouched\\` (warn) | \\`sources\\` with no \\`sources_digest\\` — nobody ever stamped it | leave it: vouching is a human's reading, not yours |\n| \\`sources.unwalked\\` (warn) | \\`sources\\` leaves whole top-level paths of the service repo untouched — the \\`details\\` name them, measured against the files git tracks. The one completeness signal loam can compute: every other check compares the documents with each other, and a corpus agrees with itself perfectly while describing a third of a service. Silent where git cannot answer (not a repository, not installed) | open them. Each one is either a part of the service nobody read — go back to the walk \\`loam adopt\\` printed — or something this document legitimately does not owe, and then say which and why in the hand-back. Do NOT add paths to \\`sources\\` that you did not read: the list is a record of what was opened, and padding it destroys the only tie the document has to the code |\n| \\`content.stale\\` (warn) | the spec's body changed since it was vouched — \\`status: verified\\` is standing over words nobody has read. Unlike \\`sources.*\\` it needs no service repo, so it fires from the docs repo too | if you edited the doc, that is the point: report it and ask a human to re-vouch. Never revert the doc or touch the digest just to silence it |\n| \\`sources.sampled-vouch\\` (warn) | a person vouched after reading a recorded SAMPLE of the document — the stamp carries \\`vouch_scope: sampled k/n seed=…\\`, so \\`status: verified\\` stands over sections nobody read. The status and the \\`vouched\\` rung are unchanged and correct; this is what says the reading behind them was partial. A \\`vouch_scope\\` that does not decode fires it too, deliberately: an unreadable scope must never read as a full vouch. Doc-side, so it fires from the docs repo as well | not yours to clear. NEVER edit the document, and never touch or delete the \\`vouch_scope\\` field, to silence it — deleting it would forge a full vouch out of a partial one. A human runs a full \\`loam vouch --service <id>\\` (no \\`--sample\\`) once they have read the rest, which removes the field; \\`loam vouch --pack --service <id>\\` lists exactly what that sample left unread |\n| \\`sources.resolved\\` (ok) | every listed source still exists in the service repo | nothing — it is the confirmation |\n| \\`sources.current\\` (ok) | the stamped \\`sources_digest\\` still matches the code — nothing moved since a human vouched | nothing — it is the confirmation |\n| \\`sources.walked\\` (ok) | no whole top-level path of the service repo is left untouched by \\`sources\\` | nothing — it is the confirmation |\n\n\\`loam archive\\` — breaches the merge computation sees, reported at plan time.\nMost never appear in \\`validate\\`; the ones that do are graded harder here,\nbecause the merge is about to WRITE the breach into the living contract\n(\\`openapi.ref-unresolved\\` and \\`asyncapi.ref-unresolved\\` are validate warns but\nplan errors; \\`openapi.remove-marker-path-level\\` fires in validate on a living\ncontract too):\n\n| code | what it means | what to do |\n|---|---|---|\n| \\`living.requirement-outside-requirements\\` | the LIVING spec holds a requirement outside \\`## Requirements\\`, and the merge rewrites only that section — it would land in the file twice | re-home the requirement under \\`## Requirements\\`, then re-run; \\`--approve\\` does not override this |\n| \\`openapi.op-modified\\` (warn) | the feature redefines an operation the living OpenAPI already has — the merge overwrites the living definition wholesale | make sure the redefinition is intended; if not, align the feature's openapi.yaml with the living one |\n| \\`openapi.path-item-modified\\` (warn) | the delta redefines a PATH-level key (\\`parameters\\`, \\`servers\\`, \\`summary\\`, an \\`x-\\`) the living OpenAPI already has — the overwrite applies to EVERY operation on that path, including ones this feature never mentions | keep path-level keys out of the delta unless changing them for every operation on the path is the intent |\n| \\`service.no-model\\` (warn) | the archive creates \\`services/<id>/\\` but nothing writes its \\`model.likec4\\` | run \\`loam adopt --service <id>\\` after the archive lands, or the new service ships without a C4 center and \\`validate --all\\` grades it incomplete |\n| \\`openapi.component-modified\\` (warn) | a component this delta declares — whether the merged operations reference it or the components ARE the delta — already exists in the living OpenAPI with different content, and the merge copies the feature's version over it wholesale | make sure the redefinition is intended; if not, align the feature's component with the living one |\n| \\`openapi.ref-unresolved\\` | a \\`$ref\\` reachable from the merged operations or a merged component resolves in neither the feature's OpenAPI nor the living one — the merge would write a dangling reference | define the missing component or fix the ref; \\`--approve\\` merges the dangling reference anyway. External refs (not starting \\`#/\\`) are never checked |\n| \\`openapi.remove-marker-path-level\\` | an \\`x-loam-remove: true\\` written at PATH level, beside the methods instead of inside the operation being retired — it names no operation, so it retires nothing, and it is not a contract key either | move the marker inside the operation (with its \\`operationId\\`), or delete it. The merge is safe either way — a feature-only key is never published into the living contract — but the removal you asked for will not happen |\n| \\`asyncapi.message-modified\\` (warn) | the delta redefines a \\`components.messages\\` slot the living AsyncAPI already has — the merge overwrites the living message wholesale | make sure the redefinition is intended; if not, align the feature's asyncapi.yaml with the living one, then \\`loam rebase\\` so the restatement classifies as a quote |\n| \\`asyncapi.channel-modified\\` (warn) | the delta redefines a \\`channels\\` slot the living AsyncAPI already has — the merge overwrites it wholesale, inline channel messages included (they are channel interior, never slots of their own) | make sure the redefinition is intended; if not, align the feature's channel with the living one |\n| \\`asyncapi.operation-modified\\` (warn) | the delta redefines an \\`operations\\` slot the living AsyncAPI already has — the merge overwrites it wholesale | make sure the redefinition is intended; if not, align the feature's operation with the living one |\n| \\`asyncapi.component-modified\\` (warn) | the delta declares a component SURFACE outside \\`components.messages\\` — a \\`components.schemas\\` entry, a security scheme — that the living AsyncAPI already has with different content, and the merge copies the feature's version over it wholesale | make sure the redefinition is intended; if not, align the feature's component with the living one, then \\`loam rebase\\` so the restatement classifies as a quote |\n| \\`asyncapi.ref-unresolved\\` | a \\`$ref\\` the MERGED asyncapi.yaml would carry resolves in neither the feature's document nor the living one — including a removal that deletes a slot the living document still references. A target the feature's own document DECLARES no longer fires: the merge now copies component surfaces too, so the pointer resolves in the document it lands in | define the missing target, fix the pointer, or retire the referrer in the same delta; \\`--approve\\` merges the dangling reference anyway. External refs (not starting \\`#/\\`) are never checked |\n| \\`asyncapi.remove-marker-inline\\` | an \\`x-loam-remove: true\\` nested on an INLINE channel message (\\`channels.<ck>.messages.<mk>\\`) — inline messages are channel interior, never slots, so the marker retires nothing; when the channel is otherwise unchanged it does not even surface as an edit | retire the whole channel (\\`x-loam-remove: true\\` at \\`channels.<ck>\\`), or declare the message under \\`components.messages\\` (the channel aliasing it by \\`$ref\\`) and put the marker there. The merge is safe either way — the deep strip keeps the key out of living — but the removal you asked for will not happen |\n\n\\`loam validate <target>\\` — the positional form's own finding, both modes:\n\n| code | what it means | what to do |\n|---|---|---|\n| \\`target.ambiguous\\` (warn) | the positional name resolves to a service AND a feature — the run validated the feature (the tie-break that has always held) and this warning says so, with \\`resolvedKind\\` in \\`--json\\` | pass \\`--service <id>\\` or \\`--feature <id>\\` to force the reading you meant; a silent precedence rule would be a report about a target nobody asked for |\n\nconfirmations — the \\`ok\\`-severity findings a clean axis reports, so silence is\nnever the signal (\\`--errors-only\\` hides them from the text view; \\`--json\\`\nalways carries them):\n\n| code | what it means | what to do |\n|---|---|---|\n| \\`c4.valid\\` (ok) | the service's model.likec4 parses and the C4 axis was actually graded | nothing — it is the confirmation |\n| \\`delta.valid\\` (ok) | the feature's delta.likec4 parses and its tagged change is well-formed | nothing — it is the confirmation |\n| \\`coherence.ok\\` (ok) | the feature's axes agree with each other and with the fleet in flight — nothing gates its archive | nothing — it is the confirmation |\n| \\`requirements.covered\\` (ok) | every requirement carries at least one scenario | nothing — it is the confirmation |\n| \\`api.covered\\` (ok) | every operation in openapi.yaml is governed by some requirement's \\`Operations:\\` line | nothing — it is the confirmation |\n| \\`event.covered\\` (ok) | the event axis joins clean — every declared message is linked and governed | nothing — it is the confirmation |\n| \\`spine.resolved\\` (ok) | every inbound landscape call into this service resolves to an operation its OpenAPI defines | nothing — it is the confirmation |\n| \\`landscape.matched\\` (ok) | every \\`services/<id>/\\` resolves to a landscape element and every binding holds | nothing — it is the confirmation |\n\n\\`sources.stale\\`, \\`content.stale\\` and \\`sources.sampled-vouch\\` are the warnings you\ncannot close by yourself. Fix what the code now says, then hand it back — the stamp\nis a person's claim to have read it, and the last of the three says how much of it\nthey read.\n`,\n};\n"]}

package/dist/core/agent/workflows/closing.js

@@ -0,0 +1,262 @@
+/**
+ * The two post-build workflows, paired: the done-check (`loam-verify`) and the
+ * merge it precedes (`loam-ship`). One file for two commands because six
+ * workflows meet the five-file package cap somewhere, and this is the seam the
+ * cycle already has — both describe what happens after the code is built, and
+ * each body names the other's refusals (`record-federated`, `not-coherent`).
+ */
+export const LOAM_VERIFY = {
+    name: "loam-verify",
+    description: "Verify a built loam feature against its own promises, claim by claim, with evidence",
+    argumentHint: "<FEAT-id>",
+    purpose: "Check that the code somebody built is the feature that was designed. loam derives the questions; a test runner and you answer them. loam never reads the service, so a verdict is worth exactly what its evidence is worth.",
+    invocation: "loam instructions loam-verify $1",
+    placeholders: ["feature"],
+    spine: [
+        "`loam verify` — the checklist, derived from the feature's own artifacts",
+        "run the generated suite with a JSON report: the scenario claims are the runner's to answer, not yours",
+        "answer the remaining claims yourself, every one carrying a `file:line` that resolves",
+        "record from each affected service's own repository, bound to that service",
+        "read the verdict honestly — a scenario confirmed on your word is `attested`, not `verified`",
+    ],
+    body: `Check that the code somebody just built is the feature that was designed.
+
+loam derives the questions; the test runner and you answer them. loam never
+reads the service, so a verdict is worth exactly what its evidence is worth.
+
+1. \`loam verify $1 --json\`. \`claims[]\` is the checklist, derived from the feature's
+   own artifacts — one claim per new service, per operation its openapi delta adds,
+   per (direction, message) its asyncapi delta newly declares against the living
+   contract's send/receive sets (quotes and removals are never questions),
+   per tagged edge that names an operation, and per scenario of every changed
+   requirement, arch.spec.md deltas included. Each has a stable \`id\` and a
+   \`subject\` (the service whose code answers it); a claim that says arch.spec.md
+   wants an integration/ops test, not an acceptance test. An ARCHIVED feature returns its record as frozen history instead
+   (\`frozen: true\`) and \`--record\` / \`--results\` / \`--contract-results\` /
+   \`--diff-answers\` refuse it — \`loam unarchive\` first if the answers really
+   must change.
+2. The \`scenario.tested\` claims are the runner's to answer, not yours. In the
+   service's repo, run the generated suite with a JSON report —
+   \`npx cucumber-js --format json:report.json\` (cucumber-jvm, behave and
+   SpecFlow emit the same format). The generated scenarios carry
+   \`@loam-digest-…\` tags that ride into the report; that digest is the match,
+   so never retitle or hand-edit a generated scenario to make one pass.
+   If there is no runnable suite yet you MAY answer them yourself, and the record
+   will say so: \`answered_by: agent\` makes the feature **attested**, not verified
+   (\`verified: false\`, \`verdict: "attested"\`, the \`verify.scenario-attested\`
+   notice, and a \`next.verify-attested\` step in \`loam status\`). Nothing gates on
+   it — a legacy service with no suite must still be able to ship — but say so
+   when you hand back, and close it with \`--results\` the moment a suite runs.
+   \`verify.digest-contested\` (warn) is the case where two services word a
+   scenario identically: they share one digest, so no single report can say whose
+   suite ran it, and each service must record its own with \`--service\`.
+   The \`api.exposes\` claims have a mechanical channel too, when an API
+   contract-test suite exists: emit loam's contract-results shape from its
+   report — \`{"loamContractReport": 1, "results": [{"operationId": "…",
+   "status": "passed"}]}\`, a one-line transform for Specmatic, Pact, Dredd or a
+   property harness — and pass \`--contract-results contract.json\` alongside.
+   Only a status of exactly \`passed\` confirms the named operation
+   (\`answered_by: external-runner\`); anything else, and an operation the report
+   never exercised, stays \`unconfirmed\` with the reason, and under the flag the
+   report owns every api.exposes claim, so take those out of the answers file.
+3. Answer every OTHER claim by finding it in the code. Not by reasoning that it
+   must be there — by opening the file:
+   - \`service.exists\` — the service is deployable: its build, its entry point.
+   - \`api.exposes\` — the route handler serving that operationId, not the spec that
+     declares it — unless a contract-test report already answered it in step 2.
+   - \`event.declares\` — the code that puts the message on the wire (sends) or
+     handles it off the wire (receives), not the contract that names it.
+   - \`c4.calls\` — the call site in the CALLER.
+4. Write those answers as JSON — evidence is \`file:line\`, one entry per place it can
+   be seen:
+   \`\`\`json
+   { "answers": [
+     { "id": "<claim id>", "verdict": "confirmed", "evidence": ["src/split/Api.ts:42"] },
+     { "id": "<claim id>", "verdict": "unconfirmed", "note": "the split service has no entry point yet" }
+   ] }
+   \`\`\`
+5. Optional, before recording: cross-examine. Have a SECOND agent answer the
+   same checklist blind — a fresh context, given only \`loam verify $1 --json\`
+   and the code, never your answers file — then compare the two sets:
+
+   \`\`\`sh
+   loam verify $1 --diff-answers yours.json theirs.json --json
+   \`\`\`
+
+   Both files must answer EVERY claim in the compared scope,
+   \`scenario.tested\` included: the diff consults no test report, so this is a
+   DIFFERENT file from the one step 6 records under \`--results\` (that one
+   must omit the runner's claims; a step-6-shaped file here refuses
+   \`answers-mismatch\`). Narrowing with \`--service <id>\` compares one
+   service's claims — give the second agent the same lens, or its file will
+   not match the compared scope. An archived feature refuses the diff too:
+   frozen history has no current checklist. It writes nothing and changes no
+   verdict: \`cross.agree-confirmed\` / \`cross.agree-unconfirmed\` rows are the
+   cheap-to-skip queue, \`disagreements[]\` (\`cross.disagree\`) is what a human
+   reads first, and the \`cross.evidence-disjoint\` notice flags agreements
+   citing non-overlapping files — read those second. Agreement between two
+   same-model agents is correlated, so it ranks review; it never upgrades
+   \`attested\` to \`verified\`. Record only the answer set you stand behind, in
+   a separate run.
+6. Record, **in each affected service's own repository**, one service at a time:
+
+   \`\`\`sh
+   loam verify $1 --service <id> --results report.json [--contract-results contract.json] --record answers.json --json
+   \`\`\`
+
+   \`--service <id>\` narrows the checklist to that service's claims and binds the
+   answers to this repository's commit, writing ONE attestation into a shared
+   \`schema: 2\` \`verification.yaml\`. Running it in the next repo adds that repo's
+   attestation and leaves the others standing. In a repo whose ./loam.json
+   declares a \`service\`, \`--service\` may be omitted — it is substituted, and the
+   run still federates. \`--results report.json\` alone is legal when the
+   checklist is all scenarios.
+
+   ⚠ **Never run \`loam verify $1 --record answers.json\` without \`--service\`.**
+   That is the legacy all-at-once form: it writes the WHOLE record from one place,
+   and over a record that already carries other services' attestations it is
+   refused (\`record-federated\`, naming them) precisely because it would erase
+   them. If you meet that refusal, re-run with \`--service\`; do not work around it.
+
+   The other refusals: \`answers-mismatch\` (an id
+   nobody asked about, a claim you left out — re-run step 1, the feature moved —
+   or an answers entry for a \`scenario.tested\` claim: the runner owns those),
+   \`answers-unevidenced\` (a \`confirmed\` with nothing behind it),
+   \`answers-unreadable\` (a report or answers file it cannot read),
+   \`record-unreadable\` (a \`verification.yaml\` that exists but cannot be read as a
+   record — it is never overwritten; a human repairs it, and
+   \`verify.record-miscounted\` is the reason when its \`summary\` block contradicts
+   its own \`claims[]\`: neither half can be believed, so re-record rather than
+   editing the counts),
+   \`service-mismatch\` (\`--service\` names a service this repo does not declare) and
+   \`repository-unavailable\` (\`--service\` from a repo that declares none, or whose
+   commit cannot be read — an attestation must be bound to the code it is about).
+7. Report every \`unconfirmed\` claim and what it would take to close it, and read
+   \`discarded\` in the payload: it names every previous answer the new record does
+   not carry, and each one is either evidence that went stale or evidence that was
+   just dropped. A scenario claim the report failed or missed closes by fixing the
+   code and re-running the suite — never by editing the generated .feature. While
+   any claim stays unconfirmed or unanswered, \`notices[]\` carries
+   \`verify.claims-open\` (warn, gating nothing): the one-line "not a clean
+   result" summary with all four counts, so a partial record can never read as a
+   finished one from the notice lines alone.
+8. Reading is safe from anywhere: \`loam verify $1 --service <id> --json\` without
+   \`--record\` writes nothing and works from the docs repo too. \`services\` lists
+   every subject of the checklist, so it is how you find out which repos still
+   owe an attestation, and \`loam status $1 --json\` says the same thing in the
+   shape of a next step.
+
+Anything you cannot show is \`unconfirmed\` with a note. That is a successful record,
+and it is the useful one: nothing gates on this file, so the only thing it is for is
+telling the next reader the truth. \`loam archive\` will ship the feature either way —
+which is exactly why a \`confirmed\` you cannot back up costs nothing now and misleads
+everyone later.
+
+\`loam verify\` — the notice and record codes its reports carry in \`notices[]\`,
+gathered from the steps above; branch on the code, never the prose:
+
+| code | what it means | what to do |
+|---|---|---|
+| \`verify.claims-open\` (warn) | a recorded feature still has unconfirmed or unanswered claims — the one-line "not a clean result" summary with all four counts, so a partial record can never read as finished from the notice lines alone; a feature with no record at all never carries it | close each open claim: fix the code and re-run the suite for a failed scenario, re-answer the rest with evidence, then re-record |
+| \`verify.scenario-attested\` (warn) | scenario claims were answered on an agent's word (\`answered_by: agent\`), so the verdict is **attested**, not verified — nothing gates on it, but say so when you hand back | run the generated suite with a JSON report and re-record with \`--results report.json\` the moment a suite exists |
+| \`verify.digest-contested\` (warn) | two or more services word a scenario identically, so they share one \`@loam-digest-…\` tag and no single cucumber report can say whose suite ran it — those scenario claims stay unconfirmed | each service records its own claims from its own repository with \`--service <id>\` |
+| \`verify.operation-contested\` (warn) | two services on the checklist expose the same operationId, so a contract report — which names no service — cannot say whose suite exercised it; those claims stay unconfirmed | each service records its own with \`--service <id>\`, passing its own contract report |
+| \`verify.checklist-forked\` (warn) | one or more services answered a DIFFERENT version of the feature's question set than the one it now asks — each attestation carries the \`checklist\` digest it answered, and the notice names the ones that do not match the current checklist. Measured against the present, not pairwise: services that all attested against a since-rewritten delta agree with each other perfectly and are all stale. Normal mid-rollout, since services attest as they finish. Attestations written before the field existed carry no digest and are never called stale | re-record the services on the older version from their own repositories (\`loam verify <FEAT> --service <id> --record\`), or accept the split knowingly — nothing gates on it |
+| \`verify.record-miscounted\` (error) | a verification.yaml whose \`summary\` block contradicts its own \`claims[]\` — neither half can be believed, so the record is refused as unreadable rather than trusted in either direction | re-record from the service's repo; never edit the counts by hand |
+| \`verify.evidence-token-missing\` (warn) | a just-confirmed citation's file at the attested commit does not contain the claim's own token (the operationId, message name or edge op) — the evidence may not show what the answer says | re-read that evidence while the answer can still be corrected; verdict-neutral, it gates nothing |
+| \`cross.agree-confirmed\` / \`cross.agree-unconfirmed\` (ok) | a \`--diff-answers\` row where both blind answer sets reach the same verdict — the cheap-to-skip review queue, though same-model agreement is correlated and proves nothing | nothing on its own; record only the answer set you stand behind, in a separate run |
+| \`cross.disagree\` (the rows a human reads first) | a \`--diff-answers\` row where the two blind answer sets contradict each other — one of them is wrong about the code | read both cited evidences and decide; the diff writes nothing and never moves a verdict |
+| \`cross.evidence-disjoint\` (warn) | a \`--diff-answers\` notice: claims BOTH sets confirm while citing non-overlapping files — two yeses that looked at different evidence | read those agreements second, after the disagreements; agreement over disjoint evidence is two guesses, not one proof |
+`,
+};
+export const LOAM_SHIP = {
+    name: "loam-ship",
+    description: "Archive a finished loam feature — merge its deltas into the living docs",
+    argumentHint: "<FEAT-id>",
+    purpose: "Merge a shipped feature into the living specs, API and landscape. This is the one command that rewrites the source of truth, so every step before it exists to make the merge reviewable before it runs.",
+    invocation: "loam instructions loam-ship $1",
+    placeholders: ["feature"],
+    spine: [
+        "confirm the code is actually built and merged — archiving early makes the docs claim something that does not exist",
+        "`loam validate --feature $1` must come back valid; if it says nothing pinned the delta, rebase and re-validate first",
+        "`loam archive $1 --dry-run` — read the whole plan and every warning before the merge touches anything",
+        "`loam archive $1` for real, and read what it reports it did",
+        "`loam unarchive $1` is the undo if the plan turns out to have been wrong",
+    ],
+    body: `Archive a shipped feature.
+
+1. Confirm the code is actually built and merged. Archiving folds the delta into the
+   living docs; doing it early makes the docs claim something that does not exist.
+   \`loam status $1 --json\` answers "is this actually finished" in one call, and its
+   \`next[]\` names what is outstanding if it is not.
+2. \`loam validate --feature $1 --json\` — must come back \`valid: true\`.
+   If it reports \`delta.baseline-missing\` or \`openapi.baseline-missing\`, run
+   \`loam rebase $1\` and re-validate BEFORE going on: those two say nothing has
+   pinned what this delta was written against, so the merge cannot tell the text
+   you EDITED from the text you merely restated. Both gate the archive — the
+   dry run in step 3 refuses on them too — and the only way past without the
+   pins is a human's \`--approve\`.
+3. \`loam archive $1 --dry-run --json\` first. \`plan[]\` is every file the merge would
+   write (\`create\` / \`update\`, then the final \`move\` into \`features/archive/\`), and
+   none of them are written — read it before letting the merge touch the source of
+   truth, and stop if a file you did not expect is on it. \`warnings[]\` is what the
+   merge will do that is legal but lossy — advisory warnings never block, which is
+   exactly why you read them now: \`openapi.op-modified\` means an operation the living
+   contract already defines gets overwritten wholesale (\`openapi.component-modified\`
+   is the same story for a component the merged operations carry),
+   \`service.no-model\` means a service arrives with no C4 centre behind it, and
+   \`delta.added-conflict\`
+   means another feature in flight adds the same requirement — the first to archive
+   lands it, and the other's archive is then refused (\`delta.added-duplicate\`: its
+   ADDED now collides with the living spec) unless a human \`--approve\`s the
+   replacement.
+4. \`loam archive $1 --json\`. It merges three axes into the living state — requirements
+   into \`services/<svc>/spec.md\`, endpoints into \`services/<svc>/openapi.yaml\`,
+   elements and edges into \`architecture/landscape.likec4\` — then moves the feature
+   under \`features/archive/\`. Success is \`ok: true\`; on \`ok: false\`, branch on
+   \`error.code\`:
+   - \`not-coherent\` — gating coherence issues; \`issues[]\` in the envelope lists them,
+     each with \`gates\` and \`overridable\` resolved (advisory warnings do not block).
+     Fix the breaches. \`--approve\` overrides the gating issues and is a human's
+     call to make, not yours: report the breach and stop. Two codes it does not
+     override even then — \`delta.service-id-invalid\` (a \`specs/<svc>/\` name the
+     id grammar refuses) and \`c4.service-binding-invalid\` (a \`metadata { service }\`
+     binding it refuses, anywhere inside a tagged element's block): each names a
+     path the merge would write mechanically, they arrive with
+     \`overridable: false\`, and the fix is a rename, never the flag.
+     \`openapi.remove-marker-path-level\` arrives
+     here too: an \`x-loam-remove\` written beside the methods instead of inside the
+     operation retires nothing.
+   - \`living-outside-requirements\` — the LIVING spec holds a requirement outside
+     \`## Requirements\`, and the merge would duplicate it. Re-home it, then re-run.
+     \`--approve\` does not move this one.
+   - \`archive-exists\` — \`features/archive/\` already has that directory; a human
+     decides what it is.
+   - \`merge-failed\` — the merge could not be computed, or failed and was rolled
+     back. Either way the living docs are unchanged; fix the reported cause, re-run.
+     A file loam cannot decode as UTF-8 refuses here by name rather than being
+     rewritten with replacement characters. So does a living document that still
+     holds git conflict markers — the \`spec.merge-conflict\` /
+     \`landscape.merge-conflict\` findings ride in \`findings[]\`, and \`--approve\`
+     does not override them: the loss is mechanical, not a judgment call.
+   - \`docs-busy\` — another \`loam archive\` or \`loam unarchive\` holds the docs
+     repo's lock. Nothing was read or written; wait for it and re-run once.
+   - \`commit-interrupted\` — a previous archive or unarchive was killed mid-commit
+     and this run cannot repair it on its own: a half-written file was edited
+     since, its pre-image is gone or altered, or \`.loam-commit\` cannot be read.
+     Run \`loam doctor\` (\`doctor.commit-interrupted\` / \`doctor.commit-unreadable\`
+     name the same state) and hand it to a human — re-running does not help.
+   - \`rollback-incomplete\` — the merge failed AND some files could not be restored.
+     Stop and hand it to a human; the message lists the files to check.
+
+Archived by mistake? \`loam unarchive $1\` restores the living docs from the snapshot
+archive left in \`features/archive/$1*/.loam-before/\` and re-opens the feature. Do not
+hand-edit the living docs back instead: the previous text of a \`MODIFIED\` requirement
+is in that snapshot and nowhere else, so anything you write by hand is a guess. It
+refuses under \`snapshot-corrupt\` when a pre-image's bytes no longer match the digest
+the archive recorded — \`--force\` does not override that one, because the damage is
+to the undo itself — and under \`snapshot-missing\` for an archive older than the
+current snapshot format. Both mean version control is the way back.
+`,
+};
+//# sourceMappingURL=closing.js.map

package/dist/core/agent/workflows/closing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closing.js","sourceRoot":"","sources":["../../../../src/core/agent/workflows/closing.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,qFAAqF;IACvF,YAAY,EAAE,WAAW;IACzB,OAAO,EACL,6NAA6N;IAC/N,UAAU,EAAE,kCAAkC;IAC9C,YAAY,EAAE,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE;QACL,yEAAyE;QACzE,uGAAuG;QACvG,sFAAsF;QACtF,2EAA2E;QAC3E,6FAA6F;KAC9F;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoJP;CACA,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAmB;IACvC,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,yEAAyE;IACtF,YAAY,EAAE,WAAW;IACzB,OAAO,EACL,0MAA0M;IAC5M,UAAU,EAAE,gCAAgC;IAC5C,YAAY,EAAE,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE;QACL,oHAAoH;QACpH,sHAAsH;QACtH,uGAAuG;QACvG,6DAA6D;QAC7D,0EAA0E;KAC3E;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0EP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * The two post-build workflows, paired: the done-check (`loam-verify`) and the\n * merge it precedes (`loam-ship`). One file for two commands because six\n * workflows meet the five-file package cap somewhere, and this is the seam the\n * cycle already has — both describe what happens after the code is built, and\n * each body names the other's refusals (`record-federated`, `not-coherent`).\n */\nexport const LOAM_VERIFY: CommandContent = {\n  name: \"loam-verify\",\n  description:\n    \"Verify a built loam feature against its own promises, claim by claim, with evidence\",\n  argumentHint: \"<FEAT-id>\",\n  purpose:\n    \"Check that the code somebody built is the feature that was designed. loam derives the questions; a test runner and you answer them. loam never reads the service, so a verdict is worth exactly what its evidence is worth.\",\n  invocation: \"loam instructions loam-verify $1\",\n  placeholders: [\"feature\"],\n  spine: [\n    \"`loam verify` — the checklist, derived from the feature's own artifacts\",\n    \"run the generated suite with a JSON report: the scenario claims are the runner's to answer, not yours\",\n    \"answer the remaining claims yourself, every one carrying a `file:line` that resolves\",\n    \"record from each affected service's own repository, bound to that service\",\n    \"read the verdict honestly — a scenario confirmed on your word is `attested`, not `verified`\",\n  ],\n  body: `Check that the code somebody just built is the feature that was designed.\n\nloam derives the questions; the test runner and you answer them. loam never\nreads the service, so a verdict is worth exactly what its evidence is worth.\n\n1. \\`loam verify $1 --json\\`. \\`claims[]\\` is the checklist, derived from the feature's\n   own artifacts — one claim per new service, per operation its openapi delta adds,\n   per (direction, message) its asyncapi delta newly declares against the living\n   contract's send/receive sets (quotes and removals are never questions),\n   per tagged edge that names an operation, and per scenario of every changed\n   requirement, arch.spec.md deltas included. Each has a stable \\`id\\` and a\n   \\`subject\\` (the service whose code answers it); a claim that says arch.spec.md\n   wants an integration/ops test, not an acceptance test. An ARCHIVED feature returns its record as frozen history instead\n   (\\`frozen: true\\`) and \\`--record\\` / \\`--results\\` / \\`--contract-results\\` /\n   \\`--diff-answers\\` refuse it — \\`loam unarchive\\` first if the answers really\n   must change.\n2. The \\`scenario.tested\\` claims are the runner's to answer, not yours. In the\n   service's repo, run the generated suite with a JSON report —\n   \\`npx cucumber-js --format json:report.json\\` (cucumber-jvm, behave and\n   SpecFlow emit the same format). The generated scenarios carry\n   \\`@loam-digest-…\\` tags that ride into the report; that digest is the match,\n   so never retitle or hand-edit a generated scenario to make one pass.\n   If there is no runnable suite yet you MAY answer them yourself, and the record\n   will say so: \\`answered_by: agent\\` makes the feature **attested**, not verified\n   (\\`verified: false\\`, \\`verdict: \"attested\"\\`, the \\`verify.scenario-attested\\`\n   notice, and a \\`next.verify-attested\\` step in \\`loam status\\`). Nothing gates on\n   it — a legacy service with no suite must still be able to ship — but say so\n   when you hand back, and close it with \\`--results\\` the moment a suite runs.\n   \\`verify.digest-contested\\` (warn) is the case where two services word a\n   scenario identically: they share one digest, so no single report can say whose\n   suite ran it, and each service must record its own with \\`--service\\`.\n   The \\`api.exposes\\` claims have a mechanical channel too, when an API\n   contract-test suite exists: emit loam's contract-results shape from its\n   report — \\`{\"loamContractReport\": 1, \"results\": [{\"operationId\": \"…\",\n   \"status\": \"passed\"}]}\\`, a one-line transform for Specmatic, Pact, Dredd or a\n   property harness — and pass \\`--contract-results contract.json\\` alongside.\n   Only a status of exactly \\`passed\\` confirms the named operation\n   (\\`answered_by: external-runner\\`); anything else, and an operation the report\n   never exercised, stays \\`unconfirmed\\` with the reason, and under the flag the\n   report owns every api.exposes claim, so take those out of the answers file.\n3. Answer every OTHER claim by finding it in the code. Not by reasoning that it\n   must be there — by opening the file:\n   - \\`service.exists\\` — the service is deployable: its build, its entry point.\n   - \\`api.exposes\\` — the route handler serving that operationId, not the spec that\n     declares it — unless a contract-test report already answered it in step 2.\n   - \\`event.declares\\` — the code that puts the message on the wire (sends) or\n     handles it off the wire (receives), not the contract that names it.\n   - \\`c4.calls\\` — the call site in the CALLER.\n4. Write those answers as JSON — evidence is \\`file:line\\`, one entry per place it can\n   be seen:\n   \\`\\`\\`json\n   { \"answers\": [\n     { \"id\": \"<claim id>\", \"verdict\": \"confirmed\", \"evidence\": [\"src/split/Api.ts:42\"] },\n     { \"id\": \"<claim id>\", \"verdict\": \"unconfirmed\", \"note\": \"the split service has no entry point yet\" }\n   ] }\n   \\`\\`\\`\n5. Optional, before recording: cross-examine. Have a SECOND agent answer the\n   same checklist blind — a fresh context, given only \\`loam verify $1 --json\\`\n   and the code, never your answers file — then compare the two sets:\n\n   \\`\\`\\`sh\n   loam verify $1 --diff-answers yours.json theirs.json --json\n   \\`\\`\\`\n\n   Both files must answer EVERY claim in the compared scope,\n   \\`scenario.tested\\` included: the diff consults no test report, so this is a\n   DIFFERENT file from the one step 6 records under \\`--results\\` (that one\n   must omit the runner's claims; a step-6-shaped file here refuses\n   \\`answers-mismatch\\`). Narrowing with \\`--service <id>\\` compares one\n   service's claims — give the second agent the same lens, or its file will\n   not match the compared scope. An archived feature refuses the diff too:\n   frozen history has no current checklist. It writes nothing and changes no\n   verdict: \\`cross.agree-confirmed\\` / \\`cross.agree-unconfirmed\\` rows are the\n   cheap-to-skip queue, \\`disagreements[]\\` (\\`cross.disagree\\`) is what a human\n   reads first, and the \\`cross.evidence-disjoint\\` notice flags agreements\n   citing non-overlapping files — read those second. Agreement between two\n   same-model agents is correlated, so it ranks review; it never upgrades\n   \\`attested\\` to \\`verified\\`. Record only the answer set you stand behind, in\n   a separate run.\n6. Record, **in each affected service's own repository**, one service at a time:\n\n   \\`\\`\\`sh\n   loam verify $1 --service <id> --results report.json [--contract-results contract.json] --record answers.json --json\n   \\`\\`\\`\n\n   \\`--service <id>\\` narrows the checklist to that service's claims and binds the\n   answers to this repository's commit, writing ONE attestation into a shared\n   \\`schema: 2\\` \\`verification.yaml\\`. Running it in the next repo adds that repo's\n   attestation and leaves the others standing. In a repo whose ./loam.json\n   declares a \\`service\\`, \\`--service\\` may be omitted — it is substituted, and the\n   run still federates. \\`--results report.json\\` alone is legal when the\n   checklist is all scenarios.\n\n   ⚠ **Never run \\`loam verify $1 --record answers.json\\` without \\`--service\\`.**\n   That is the legacy all-at-once form: it writes the WHOLE record from one place,\n   and over a record that already carries other services' attestations it is\n   refused (\\`record-federated\\`, naming them) precisely because it would erase\n   them. If you meet that refusal, re-run with \\`--service\\`; do not work around it.\n\n   The other refusals: \\`answers-mismatch\\` (an id\n   nobody asked about, a claim you left out — re-run step 1, the feature moved —\n   or an answers entry for a \\`scenario.tested\\` claim: the runner owns those),\n   \\`answers-unevidenced\\` (a \\`confirmed\\` with nothing behind it),\n   \\`answers-unreadable\\` (a report or answers file it cannot read),\n   \\`record-unreadable\\` (a \\`verification.yaml\\` that exists but cannot be read as a\n   record — it is never overwritten; a human repairs it, and\n   \\`verify.record-miscounted\\` is the reason when its \\`summary\\` block contradicts\n   its own \\`claims[]\\`: neither half can be believed, so re-record rather than\n   editing the counts),\n   \\`service-mismatch\\` (\\`--service\\` names a service this repo does not declare) and\n   \\`repository-unavailable\\` (\\`--service\\` from a repo that declares none, or whose\n   commit cannot be read — an attestation must be bound to the code it is about).\n7. Report every \\`unconfirmed\\` claim and what it would take to close it, and read\n   \\`discarded\\` in the payload: it names every previous answer the new record does\n   not carry, and each one is either evidence that went stale or evidence that was\n   just dropped. A scenario claim the report failed or missed closes by fixing the\n   code and re-running the suite — never by editing the generated .feature. While\n   any claim stays unconfirmed or unanswered, \\`notices[]\\` carries\n   \\`verify.claims-open\\` (warn, gating nothing): the one-line \"not a clean\n   result\" summary with all four counts, so a partial record can never read as a\n   finished one from the notice lines alone.\n8. Reading is safe from anywhere: \\`loam verify $1 --service <id> --json\\` without\n   \\`--record\\` writes nothing and works from the docs repo too. \\`services\\` lists\n   every subject of the checklist, so it is how you find out which repos still\n   owe an attestation, and \\`loam status $1 --json\\` says the same thing in the\n   shape of a next step.\n\nAnything you cannot show is \\`unconfirmed\\` with a note. That is a successful record,\nand it is the useful one: nothing gates on this file, so the only thing it is for is\ntelling the next reader the truth. \\`loam archive\\` will ship the feature either way —\nwhich is exactly why a \\`confirmed\\` you cannot back up costs nothing now and misleads\neveryone later.\n\n\\`loam verify\\` — the notice and record codes its reports carry in \\`notices[]\\`,\ngathered from the steps above; branch on the code, never the prose:\n\n| code | what it means | what to do |\n|---|---|---|\n| \\`verify.claims-open\\` (warn) | a recorded feature still has unconfirmed or unanswered claims — the one-line \"not a clean result\" summary with all four counts, so a partial record can never read as finished from the notice lines alone; a feature with no record at all never carries it | close each open claim: fix the code and re-run the suite for a failed scenario, re-answer the rest with evidence, then re-record |\n| \\`verify.scenario-attested\\` (warn) | scenario claims were answered on an agent's word (\\`answered_by: agent\\`), so the verdict is **attested**, not verified — nothing gates on it, but say so when you hand back | run the generated suite with a JSON report and re-record with \\`--results report.json\\` the moment a suite exists |\n| \\`verify.digest-contested\\` (warn) | two or more services word a scenario identically, so they share one \\`@loam-digest-…\\` tag and no single cucumber report can say whose suite ran it — those scenario claims stay unconfirmed | each service records its own claims from its own repository with \\`--service <id>\\` |\n| \\`verify.operation-contested\\` (warn) | two services on the checklist expose the same operationId, so a contract report — which names no service — cannot say whose suite exercised it; those claims stay unconfirmed | each service records its own with \\`--service <id>\\`, passing its own contract report |\n| \\`verify.checklist-forked\\` (warn) | one or more services answered a DIFFERENT version of the feature's question set than the one it now asks — each attestation carries the \\`checklist\\` digest it answered, and the notice names the ones that do not match the current checklist. Measured against the present, not pairwise: services that all attested against a since-rewritten delta agree with each other perfectly and are all stale. Normal mid-rollout, since services attest as they finish. Attestations written before the field existed carry no digest and are never called stale | re-record the services on the older version from their own repositories (\\`loam verify <FEAT> --service <id> --record\\`), or accept the split knowingly — nothing gates on it |\n| \\`verify.record-miscounted\\` (error) | a verification.yaml whose \\`summary\\` block contradicts its own \\`claims[]\\` — neither half can be believed, so the record is refused as unreadable rather than trusted in either direction | re-record from the service's repo; never edit the counts by hand |\n| \\`verify.evidence-token-missing\\` (warn) | a just-confirmed citation's file at the attested commit does not contain the claim's own token (the operationId, message name or edge op) — the evidence may not show what the answer says | re-read that evidence while the answer can still be corrected; verdict-neutral, it gates nothing |\n| \\`cross.agree-confirmed\\` / \\`cross.agree-unconfirmed\\` (ok) | a \\`--diff-answers\\` row where both blind answer sets reach the same verdict — the cheap-to-skip review queue, though same-model agreement is correlated and proves nothing | nothing on its own; record only the answer set you stand behind, in a separate run |\n| \\`cross.disagree\\` (the rows a human reads first) | a \\`--diff-answers\\` row where the two blind answer sets contradict each other — one of them is wrong about the code | read both cited evidences and decide; the diff writes nothing and never moves a verdict |\n| \\`cross.evidence-disjoint\\` (warn) | a \\`--diff-answers\\` notice: claims BOTH sets confirm while citing non-overlapping files — two yeses that looked at different evidence | read those agreements second, after the disagreements; agreement over disjoint evidence is two guesses, not one proof |\n`,\n};\n\nexport const LOAM_SHIP: CommandContent = {\n  name: \"loam-ship\",\n  description: \"Archive a finished loam feature — merge its deltas into the living docs\",\n  argumentHint: \"<FEAT-id>\",\n  purpose:\n    \"Merge a shipped feature into the living specs, API and landscape. This is the one command that rewrites the source of truth, so every step before it exists to make the merge reviewable before it runs.\",\n  invocation: \"loam instructions loam-ship $1\",\n  placeholders: [\"feature\"],\n  spine: [\n    \"confirm the code is actually built and merged — archiving early makes the docs claim something that does not exist\",\n    \"`loam validate --feature $1` must come back valid; if it says nothing pinned the delta, rebase and re-validate first\",\n    \"`loam archive $1 --dry-run` — read the whole plan and every warning before the merge touches anything\",\n    \"`loam archive $1` for real, and read what it reports it did\",\n    \"`loam unarchive $1` is the undo if the plan turns out to have been wrong\",\n  ],\n  body: `Archive a shipped feature.\n\n1. Confirm the code is actually built and merged. Archiving folds the delta into the\n   living docs; doing it early makes the docs claim something that does not exist.\n   \\`loam status $1 --json\\` answers \"is this actually finished\" in one call, and its\n   \\`next[]\\` names what is outstanding if it is not.\n2. \\`loam validate --feature $1 --json\\` — must come back \\`valid: true\\`.\n   If it reports \\`delta.baseline-missing\\` or \\`openapi.baseline-missing\\`, run\n   \\`loam rebase $1\\` and re-validate BEFORE going on: those two say nothing has\n   pinned what this delta was written against, so the merge cannot tell the text\n   you EDITED from the text you merely restated. Both gate the archive — the\n   dry run in step 3 refuses on them too — and the only way past without the\n   pins is a human's \\`--approve\\`.\n3. \\`loam archive $1 --dry-run --json\\` first. \\`plan[]\\` is every file the merge would\n   write (\\`create\\` / \\`update\\`, then the final \\`move\\` into \\`features/archive/\\`), and\n   none of them are written — read it before letting the merge touch the source of\n   truth, and stop if a file you did not expect is on it. \\`warnings[]\\` is what the\n   merge will do that is legal but lossy — advisory warnings never block, which is\n   exactly why you read them now: \\`openapi.op-modified\\` means an operation the living\n   contract already defines gets overwritten wholesale (\\`openapi.component-modified\\`\n   is the same story for a component the merged operations carry),\n   \\`service.no-model\\` means a service arrives with no C4 centre behind it, and\n   \\`delta.added-conflict\\`\n   means another feature in flight adds the same requirement — the first to archive\n   lands it, and the other's archive is then refused (\\`delta.added-duplicate\\`: its\n   ADDED now collides with the living spec) unless a human \\`--approve\\`s the\n   replacement.\n4. \\`loam archive $1 --json\\`. It merges three axes into the living state — requirements\n   into \\`services/<svc>/spec.md\\`, endpoints into \\`services/<svc>/openapi.yaml\\`,\n   elements and edges into \\`architecture/landscape.likec4\\` — then moves the feature\n   under \\`features/archive/\\`. Success is \\`ok: true\\`; on \\`ok: false\\`, branch on\n   \\`error.code\\`:\n   - \\`not-coherent\\` — gating coherence issues; \\`issues[]\\` in the envelope lists them,\n     each with \\`gates\\` and \\`overridable\\` resolved (advisory warnings do not block).\n     Fix the breaches. \\`--approve\\` overrides the gating issues and is a human's\n     call to make, not yours: report the breach and stop. Two codes it does not\n     override even then — \\`delta.service-id-invalid\\` (a \\`specs/<svc>/\\` name the\n     id grammar refuses) and \\`c4.service-binding-invalid\\` (a \\`metadata { service }\\`\n     binding it refuses, anywhere inside a tagged element's block): each names a\n     path the merge would write mechanically, they arrive with\n     \\`overridable: false\\`, and the fix is a rename, never the flag.\n     \\`openapi.remove-marker-path-level\\` arrives\n     here too: an \\`x-loam-remove\\` written beside the methods instead of inside the\n     operation retires nothing.\n   - \\`living-outside-requirements\\` — the LIVING spec holds a requirement outside\n     \\`## Requirements\\`, and the merge would duplicate it. Re-home it, then re-run.\n     \\`--approve\\` does not move this one.\n   - \\`archive-exists\\` — \\`features/archive/\\` already has that directory; a human\n     decides what it is.\n   - \\`merge-failed\\` — the merge could not be computed, or failed and was rolled\n     back. Either way the living docs are unchanged; fix the reported cause, re-run.\n     A file loam cannot decode as UTF-8 refuses here by name rather than being\n     rewritten with replacement characters. So does a living document that still\n     holds git conflict markers — the \\`spec.merge-conflict\\` /\n     \\`landscape.merge-conflict\\` findings ride in \\`findings[]\\`, and \\`--approve\\`\n     does not override them: the loss is mechanical, not a judgment call.\n   - \\`docs-busy\\` — another \\`loam archive\\` or \\`loam unarchive\\` holds the docs\n     repo's lock. Nothing was read or written; wait for it and re-run once.\n   - \\`commit-interrupted\\` — a previous archive or unarchive was killed mid-commit\n     and this run cannot repair it on its own: a half-written file was edited\n     since, its pre-image is gone or altered, or \\`.loam-commit\\` cannot be read.\n     Run \\`loam doctor\\` (\\`doctor.commit-interrupted\\` / \\`doctor.commit-unreadable\\`\n     name the same state) and hand it to a human — re-running does not help.\n   - \\`rollback-incomplete\\` — the merge failed AND some files could not be restored.\n     Stop and hand it to a human; the message lists the files to check.\n\nArchived by mistake? \\`loam unarchive $1\\` restores the living docs from the snapshot\narchive left in \\`features/archive/$1*/.loam-before/\\` and re-opens the feature. Do not\nhand-edit the living docs back instead: the previous text of a \\`MODIFIED\\` requirement\nis in that snapshot and nowhere else, so anything you write by hand is a guess. It\nrefuses under \\`snapshot-corrupt\\` when a pre-image's bytes no longer match the digest\nthe archive recorded — \\`--force\\` does not override that one, because the damage is\nto the undo itself — and under \\`snapshot-missing\\` for an archive older than the\ncurrent snapshot format. Both mean version control is the way back.\n`,\n};\n"]}