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

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

@@ -0,0 +1,373 @@
+/**
+ * The fix tables: run loam's checks and repair what they find, code by code.
+ * The largest body on purpose — it is the other half of the codes-drift
+ * documentation corpus (with ../agents-md/), so a new finding code gets its
+ * row here.
+ */
+export const LOAM_CHECK = {
+    name: "loam-check",
+    description: "Validate the loam docs repo and fix what it reports",
+    argumentHint: "[--all | <FEAT-id> | <service>]",
+    purpose: "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.",
+    // No `$1`, unlike the other five. This body carries no placeholder at all —
+    // `loam-check`'s argument is a target you pass to `loam validate`, not
+    // something the protocol interpolates — and the argument hint's FIRST form
+    // is `--all`, so `loam instructions loam-check $1` expanded to
+    // `loam instructions loam-check --all`, which commander reads as an unknown
+    // option and refuses with exit 1. A pointer file whose one instruction
+    // fails leaves an agent with no protocol at all, which is a state the fat
+    // body could never reach. The command still tolerates a leading-dash
+    // argument (see `allowUnknownOption` in commands/instructions.ts); this is
+    // the half of the fix that stops loam printing the broken line in the first
+    // place.
+    invocation: "loam instructions loam-check --no-fix-tables",
+    // The one protocol whose body names no placeholder: its target (`--all`, a
+    // feature id, a service id) is spelled inside the `loam validate` line the
+    // agent chooses, not substituted into the page.
+    placeholders: [],
+    spine: [
+        "`loam validate --all` in the docs repo for the fleet, or `loam validate <target>` for one feature or service",
+        "fix every error, and every finding that gates the archive",
+        "leave an advisory warning standing only if you can say why, and say it",
+        "re-run until the grade is the one you meant",
+    ],
+    body: `Run loam's checks and fix what they find.
+
+- whole fleet: \`loam validate --all --json\` (run in the docs repo)
+- one target: \`loam validate <FEAT-id | service-id> --json\` — the feature reading is
+  tried first; \`--feature <id>\` / \`--service <id>\` force one when a name could be both,
+  and \`target.ambiguous\` (warn) says when a name really was both and which reading was taken
+- \`--strict\` (any mode) exits 1 on any warning too. Exit code only: \`valid\` and the
+  payload do not change, so the stricter grade lives in the CI invocation, not the repo
+- \`--errors-only\` drops the \`ok\` confirmations from the text view; the \`--json\`
+  payload is byte-identical either way
+- under \`--all\`, warn codes tied to a contract axis (\`service.no-spec\`,
+  \`spec.no-requirements\`, \`service.no-openapi\`'s warn form,
+  \`spine.op-link-missing\`, \`permissions.unenforced\`, \`capability.unrealized\`)
+  collapse in the TEXT view to one "axis not started" banner per axis when that
+  axis has zero participating services fleet-wide (\`scorecard.adoption\`) —
+  expected during staged adoption; \`--json\` carries every finding unchanged
+- refusals before any grading: \`docs-missing\` / \`services-missing\` (\`docsDir\` in
+  ./loam.json points at nothing, or at a directory with no \`services/\`) — run
+  \`loam doctor\` and fix the wiring, do not read an empty report as a clean fleet
+
+Branch on \`findings[].code\`, not the prose. Errors fail validate; a coherence finding
+with \`gates: true\` will stop \`loam archive\` even when it is a warning. Fix every
+error and every gating finding. Leave an advisory warning only if you can say why,
+and say it.
+
+A clean run grades the joins and never the picture. No check reads a view or a
+relationship's kind, so a fleet can validate with its arrows guessed and every
+overview unreadable. When the work drew edges or views, open them
+(\`npx likec4 start\` in the docs repo) and hold them against
+\`loam instructions loam-drawing\` before calling it done.
+
+\`--service <id>\` — one service's own axes (\`--all\` runs these for every service):
+
+| code | what it means | what to do |
+|---|---|---|
+| \`service.unknown\` | no \`services/<id>/\` at all — the id is a typo until proven otherwise. The proof otherwise is an active feature that INTRODUCES the service: its only documents are that feature's \`specs/<id>/\` until it archives, and the message names the feature instead of a near-miss. A bare \`loam validate\` in a repository bound to such a service never raises it — it validates the introducing features instead, says so first, and \`--json\` carries \`boundService\` | use one of the ids the message offers, or \`loam list services\`; never \`loam adopt\` a misspelling. When the message names a feature that introduces the service there is nothing to adopt — adopting would write \`services/<id>/\` ahead of the merge: run \`loam validate --feature <FEAT-id>\` |
+| \`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 |
+| \`c4.invalid\` | model.likec4 does not parse. How it was READ depends on the file's own grammar (SCHEMA.md, "Two shapes of a service model"): a model declaring its own \`specification\` is parsed ALONE, exactly as before; a model with none EXTENDS the fleet map and is parsed together with \`architecture/landscape.likec4\`. In the second case every error belongs to the model even when the message names the map — the map parsed clean by itself, or \`spine.landscape-invalid\` would be standing here instead and this model could not be read at all | fix this first — an unreadable axis makes every other check meaningless. For an extending model the usual causes are a kind the map does not declare (add \`element database\` to the map's one \`specification\` block), an \`extend\` naming a partial id (it takes the FULLY-QUALIFIED id — \`marketplace.orderService\`, never \`orderService\`), or a \`description\` written inside the \`extend\` block, which belongs on the map's declaration. A model that declares an element kind AND writes \`extend\` is the standalone shape with an \`extend\` that can never resolve; the details say so and name the two lines, one of which has to go |
+| \`landscape.service-unmodelled\` | the same code as the fleet row below, raised on the SERVICE target when this service's model.likec4 EXTENDS the fleet map and no element in \`architecture/\` resolves to \`services/<id>/\`. An extending model says what is INSIDE the element the map binds; with no such element there is nothing to be inside, so no count in the model means anything and neither \`c4.valid\` nor \`c4.invalid\` is claimed. A model that STANDS ALONE never reaches it here — it answers for its own elements, and the fleet run owns that state | draw the element, or bind an existing one with \`metadata { service '<id>' }\`; then re-run |
+| \`c4.declaration-diverged\` (warn) | a model that STANDS ALONE declares an element the fleet map (\`architecture/\`) also declares, and the two copies disagree about \`kind\`, \`title\`, the tag SET or the \`metadata { service }\` binding. The two declarations are joined by id, then by the \`metadata { service }\` binding both wrote, then by the map element whose id ends with the model's as a dotted tail — so a map that GROUPS its services under a parent is compared like any other, and an ambiguous tail is compared with nothing. A tail that is a BARE last segment (\`db\`, \`api\`, \`agent\`) joins only a FLEET-LEVEL map element — one no ancestor of which stands for a service, so a top-level element or a box the map draws inside a plain grouping element, never an element drawn inside a service's own — because one service's private store and another service's store are two elements owned by two services, not one element declared twice, while a box the map draws at fleet level and a model re-declares at top level is one name given two meanings. Two documents are two authorities on one element, and until now nothing read them together: a copy losing \`#platform\` changes what every view filtering on that tag shows, and no check said so. One finding per divergent element, naming both declarations and which fields differ; \`description\` is deliberately NOT compared, because it is prose nothing grades, while the other four each change what a view shows or what loam resolves. Silent while the map does not parse, and impossible for a model that extends the map — there is one declaration | copy the map's declaration verbatim into the model, treating the map as the authority; or migrate the model to the extending shape (the ordered recipe is in SCHEMA.md, "Two shapes of a service model"), after which the element is declared once and cannot diverge. When the message says copying the map's declaration would not clear it, the difference comes off \`specification { element <kind> { … } }\` and no copy can fix it — the message names the document whose specification declares tags on that kind, and the repair is to match the two blocks there, or to migrate to the extending shape so there is one specification and one declaration |
+| \`c4.element-unowned\` (warn) | a model that EXTENDS the fleet map declares an element outside the element that resolves to this service — one finding per element, with its id and kind. An extending model adds elements under its own element and nowhere else: what it adds elsewhere lands in the fleet project as this service's private copy of somebody else's box | a store or component this service OWNS goes inside the \`extend <fqn> { }\` block, where its id becomes \`<fqn>.<name>\` — that is the usual answer and the one the old wording omitted. Otherwise: declare a system this service merely REACHES in \`architecture/landscape.likec4\`, once, and point an edge at it from the container that reaches it; put another service's internals in that service's own model |
+| \`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 |
+| \`requirements.missing-scenarios\` | a requirement with no scenario | add the acceptance criteria; do not delete the requirement |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`spec.requirement-id-repeated\` | one requirement declares \`Requirement-ID\` more than once | keep exactly one identity line |
+| \`spec.requirement-id-duplicate\` | one ID identifies multiple requirements in the same file | give each requirement its own stable ID |
+| \`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. The \`details\` name the operationIds that differ — served but not in the committed copy, committed but no longer served — and the message says when the sets agree, so a reworded description reads apart from vanished endpoints. 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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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>\` |
+| \`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 |
+| \`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. A pinned operation whose living one a parallel feature has since REMOVED lands here too, and \`openapi.op-revived\` fires beside it — the pinned quote reports both: re-read the living contract and delete the whole operation from the delta — dropping only the pin clears this one and leaves \`openapi.op-revived\`, because unpinned it reads as an addition. Keep it only if this feature deliberately brings the operation back: then drop the pin and archive with \`--approve\` past \`openapi.op-revived\`. One a parallel feature MOVED to another slot (or retired here, before another re-added it elsewhere) lands here as well, and the message names where it lives now: delete the quote and make any change there — archiving past it while it still lives there would answer the operationId at both addresses; to move it back on purpose, drop the pin and add a removal marker at that address, or define another operation there. If you edited it, settle with that feature first |
+| \`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 |
+| \`api.ungoverned\` (warn) | operation(s) no requirement's \`Operations:\` line names | write the requirement, or link an existing one |
+| \`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 |
+| \`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 |
+| \`spine.landscape-invalid\` | the \`architecture/\` project does not parse, so the C4↔API spine cannot be checked. The whole project, not the landscape file alone: a \`architecture/usecases/x.likec4\` that does not read reports this on a single-service run exactly as under \`--all\`. For a service whose model EXTENDS the map the message carries one clause more — the model cannot be read either, so neither \`c4.valid\` nor \`c4.invalid\` is emitted for it and every model-dependent check on that service is suspended rather than failing. The message names the broken document(s) repo-relative and \`locations[0]\` points at the first of them | fix the file the message names, under \`architecture/\`, before anything else — one unreadable document there suspends the cross-service layer for the whole fleet |
+| \`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 |
+| \`spine.op-link-missing\` (warn) | a landscape "Calls" edge into this service with no \`metadata { op }\` | link it to the operationId |
+| \`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 |
+| \`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 |
+| \`asyncapi.invalid\` | asyncapi.yaml exists but does not read as AsyncAPI 3.0: it does not parse, or its \`asyncapi:\` field says 1.x or 2.x (whose \`publish\`/\`subscribe\` loam does not read — the \`details\` name the version). 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, or upgrade an older document with \`asyncapi convert --target-version=3.0.0\` (the AsyncAPI CLI) — the event axis is unchecked until it reads |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`spine.message-unbound\` (warn) | a landscape edge this service drew carries an event key on the wrong end: \`publishes\` binds the edge's SOURCE and \`consumes\` its TARGET, and that end is infrastructure (a \`topic\`, \`queue\`, \`database\`, \`cache\` or \`bucket\`, itself or by an ancestor), which neither publishes nor consumes, while this service sits at the other one. The key binds nothing, so no contract is checked against it and the spine counts one link fewer — it used to say nothing at all. An \`#external\` system at that end is an outside producer or consumer, drawn correctly, and stays silent | turn the edge round, as the message spells it: the arrow follows the message, producer \`-[publishes]->\` topic and topic \`-[delivers]->\` consumer (\`loam instructions loam-drawing\`). An edge carrying both keys cannot serve both: move the key the message names onto an edge of its own |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`covers.unknown\` (warn) | a \`Covers:\` entry in arch.spec.md resolves to no element, edge, alert or SLI — living and feature deltas alike. An edge entry may carry the relationship's kind as LikeC4 writes the edge, \`a -[kind]-> b\` or \`a .kind b\`: the kind is read past, not compared, so it covers what \`a -> b\` covers. Not raised for a service whose model.likec4 could not be read (\`c4.invalid\`, or \`spine.landscape-invalid\` for a model that extends the map): nothing is graded against a model nobody could read | fix the id (the message offers close ones); a mistyped entry silently costs the coverage it was written for |
+| \`usecase.step-unbacked\` | a hop of a \`#req-\`-tagged \`dynamic view\` in this service's own LikeC4 project — any \`.likec4\` beside model.likec4, or a view inside it — that NO relationship in model.likec4 backs. LikeC4 reports no error for it, so the diagram renders and the renderer's project parses; only this convicts it. The message reads \`<svc>: services/<tree>/<file> — dynamic view '<id>' step N\` | 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>\` |
+| \`usecase.step-contested\` (warn) | two or more relationships in model.likec4 back one hop of a service-local flow and name DIFFERENT operations — an absent \`metadata { op }\` counts as a value — so nothing can say which one the hop exercises; \`details\` lists every candidate | open the step's title with the operation id (or message name) the hop means, then punctuation — \`'createOrder — places the order'\` — or give the candidates one operation, or draw the hop between the elements that name exactly one |
+| \`usecase.step-unlinked\` (warn) | the same code as the fleet row below, raised on a service-local flow: the relationship backing a hop of a \`#req-\`-tagged \`dynamic view\` beside model.likec4 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 stand-in a model declares for a sibling service is the case that reaches it here. Never between two containers of THIS service: a service owes no operationId to itself. The \`--all\` row spells out all four mechanical guards | add \`metadata { op '<operationId>' }\` to the edge in \`model { }\`, or \`metadata { publishes '<message>' }\` / \`consumes\` where the hop is an event |
+| \`usecase.requirement-unresolved\` | a \`#req-<slug>\` tag on a flow beside model.likec4 whose slug names no \`Requirement-ID\` of THIS service — scoped by the directory, never by a \`#cap-\` tag: the ids of spec.md and arch.spec.md together. Four arms: neither document exists, neither declares a \`Requirement-ID:\`, none flattens to the slug (close ids offered as the tag to write), or two flatten alike — a Requirement-ID is unique inside ONE document and this service has two | add \`Requirement-ID: <id>\` to the requirement this flow keeps, or fix the slug; for two colliding ids, rename one |
+| \`usecase.capability-unresolved\` | a \`#cap-\` tag on a \`dynamic view\` inside this service's own project, where no capability can be claimed — a capability is a fleet promise realized by a hop sequence across the fleet map, and this flow's hops are this service's containers. Fires whether or not \`architecture/capabilities.yaml\` exists: the reason is placement, not vocabulary. The view stays opted in and its steps are graded | move the flow to \`architecture/usecases/\` if it crosses services, else drop the \`#cap-\` tag and keep the \`#req-\` one |
+| \`usecase.flow-invalid\` | a \`.likec4\` beside model.likec4 that does not parse as part of the service's LikeC4 project — an unresolved element, a syntax error, or a \`specification\` block the project already has (that is a duplicate whether the model declares one or the fleet map does). Every \`.likec4\` under the service directory is read as ONE project the way the renderer reads it — for an extending model that project is the fleet map plus those documents — and the renderer refuses the whole project over one broken file; no flow in it was graded. model.likec4 itself still parses and is graded (\`c4.valid\`, \`Covers:\`, health) — this is never \`c4.invalid\`. A sibling the service's OWN \`likec4.config.json\` \`exclude\` covers is not in that project and is not graded | fix the file the finding names (\`locations[0]\`, and one \`details\` line per error prefixed by its file) — the renderer refuses the same project until it reads. An undeclared reserved tag adds one further \`details\` line naming the \`tag <name>\` declaration to write and the \`specification { }\` block it belongs in |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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>\` |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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\`) |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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, matched exactly and never by suffix. Resolved against the service model, never the fleet map read on its own: the model carries everything the service touches (private stores included, as nested containers), and the on-call file must name the same world. For a model that EXTENDS the map the set is its own SLICE — the elements it adds, plus every endpoint of its own edges and each endpoint's ANCESTORS — so \`kafka\` answers through an edge that names \`kafka.orderEvents\`, and a peer service answers through the binding on the map's element the model points at. 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 (a system the service reaches as an element of the FLEET MAP with the real edge drawn from the container that reaches it; a private store as a nested container), correct the id to one of the element's three names — the service id or a top-level system id is the spelling that survives either model shape — or delete the entry |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 service target's whole \`evidence\` family is silent, and only \`evidence.record-unreadable\` still fires there, on the feature target | nothing — it is the confirmation |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`evidence.record-unreadable\` (warn) | a file of a feature's verification record (its \`verification.yaml\`, or a \`verification/<svc>.yaml\`) exists but cannot be read as a record (broken YAML, git conflict markers, a malformed \`evidence_pins\` block, a summary contradicting its claims) — none of its evidence was checked, and a silent skip would read as clean | follow the repair the finding names for that file: this service's own \`verification/<svc>.yaml\` may be repaired, or deleted and re-recorded from this repo; the one-file \`verification.yaml\` may hold other services' attestations, so it is repaired or restored from version control, never deleted. loam never overwrites a record it could not read |
+
+\`--feature <FEAT-id>\` — a change's three axes against each other. The SAME checks
+gate \`loam archive\` (errors block it; warnings never do), so a clean run here is
+what lets a feature ship:
+
+| code | what it means | what to do |
+|---|---|---|
+| \`delta.invalid\` | delta.likec4 does not parse | fix this first — an unreadable axis makes every other check meaningless |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`spec-api.op-undefined\` | a requirement governs an operation its provider's OpenAPI does not define | define the endpoint, or correct the \`Operations:\` line |
+| \`spec-api.op-pending\` (warn) | the governed operation is defined by another feature in flight | archive that feature first |
+| \`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 |
+| \`c4-api.op-pending\` (warn) | the called operation is defined by another feature in flight | archive that feature first |
+| \`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 |
+| \`c4-api.op-removing\` | a NEW tagged edge consumes an operation this feature removes — with a removal marker, or by defining another operation at its method and path so the merge leaves it defined nowhere | remove or redirect the new edge; one feature cannot retire and add consumption of the same operation |
+| \`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 |
+| \`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 |
+| \`openapi.remove-marker-missing\` | a REMOVED requirement governs an operation the service's living contract still defines, but the feature has no removal marker for it. Owed only while there is a living operation to retire: not for an id the service's own contract does not define (a consumer's REMOVED requirement naming another service's operation), and not for one this delta already replaces at its method and path. A living contract that does not parse proves neither, so the marker is still owed there | add the exact path/method operation with its operationId and \`x-loam-remove: true\` to the feature openapi.yaml |
+| \`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 |
+| \`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 |
+| \`openapi.remove-op-consumed\` | the feature takes out of the contract an operation the fleet would still consume after this merge — read once for the gate and \`loam diff\` alike: an edge of the \`architecture/\` project with \`metadata { op }\` into the provider; another service's requirement (spec.md or arch.spec.md) whose \`Operations:\` line names it, unless that service's own contract defines the same id (then it names its own); a use-case hop attributed to it; and the provider's OWN spec.md requirements (an arch.spec.md \`Operations:\` line is never graded against its own contract, so the provider's strands nothing) and self-edges still naming it. Every requirement is read as the merge would leave it — one this feature MODIFIES to drop the id or REMOVES no longer counts, another service's included, and an unappliable spec delta fails closed. Two shapes: a removal marker retires it, or the delta defines ANOTHER operation at its method and path, and the contract the merge would write then defines it nowhere (the merge writes per method and path, so it replaces it there). The message names what replaces it and where; \`details[]\` lists the consumers. A consumer document loam cannot read — a spec.md or arch.spec.md that is not UTF-8, the provider's own spec.md included, or a service id two directories claim — refuses too, named in \`details[]\`: nobody could prove it does not name the operation. An edge into the provider drawn with no \`metadata { op }\`, or a use-case hop whose edges name different operations, does not refuse (\`loam diff\` lists them as doubts) | make each document listed readable (re-save it as UTF-8, or leave one directory per service id); fix each consumer in the same change — drop or redraw the edge by editing the living map (the landscape merge only adds edges, so a \`delta.likec4\` can never take one away), MODIFY or REMOVE the requirement in this feature's \`specs/<service>/\` delta (a REMOVED one owes no marker where the overwrite already takes the operation out) — or archive with \`--approve\` if the consumer is already gone in code. An overwrite: define the replaced operation at another address in the same delta if it is to stay; for a rename, redraw the living edge and restate the governing requirement as a MODIFIED naming the new operation |
+| \`openapi.op-revived\` (warn, gates archive) | the feature's openapi.yaml spells an operation the living contract no longer has, and an ARCHIVED feature's removal marker retired it — or spells it at an address an archived feature MOVED it away from (or retired it from, before another re-added it elsewhere), so the merge would answer it at both addresses (one operationId at two slots). Judged on the contract the merge would write: an operation the living contract still holds that ends up at one address is not graded — moved back with its own removal marker where it lives now, or swapped out there by another operation, with or without an operationId — and a removal marker where the operation does not live removes nothing, so it excuses nothing. The message names the operation, the archived feature(s), what each did there (moved it, and where to, or retired it) and, apart from that, where it lives now — and, when another operation lives at the address the delta spells it at, names that one too (one written with no operationId by what it is): the merge writes per method and path, so archiving replaces it there. Absent from living reads like an addition, so the merge would put it back. Read from the markers under \`features/archive/\`, counted only where that feature's snapshot shows the merge carried them out: an operation removed by hand-editing a living contract, or retired by an archive since deleted from disk, is invisible to it | retired: delete the quote if you only restated it; archive with \`--approve\` if the feature brings it back on purpose (drop its \`x-loam-based-on\` first — a pin over nothing is \`openapi.baseline-invalid\`). Two addresses: delete the quote and make any change at the address the message names; to move it back on purpose, add a removal marker for it at that address in the same delta (or define another operation there) — and where another operation lives at the quoted address now, the delta replaces it, so define that one at another address in it if it is to stay. Where the delta already spells that address, no marker can stand beside what it holds there, and the message offers \`--approve\` instead |
+| \`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 |
+| \`c4-event.message-pending\` (warn) | the named message is introduced by another feature in flight | archive that feature first |
+| \`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 |
+| \`spec-event.message-pending\` (warn) | the named message is introduced by another feature in flight — or a delta \`Consumes:\` line (and, as \`c4-event.message-pending\`, a tagged \`consumes\` edge) names a message whose only sender is another feature's asyncapi delta. Archived first, this feature leaves \`spine.message-unproduced\` for \`validate --all\`, and the archive prints that in place of its closing line | archive that feature first |
+| \`spine.message-unproduced\` | a delta's \`Consumes:\` line or tagged \`consumes\` edge names a message nothing would send after this merge — no service's contract as the merge leaves it, no \`#external\` element publishing it on the living map or in this delta. Validate's own code, raised before the archive lands the consumer it would report. Suspended while any contract in the fleet does not read, as at service scope | add the producer's \`action: send\` operation (its asyncapi.yaml, living or in this feature's \`specs/<service>/\` delta), draw the \`#external\` system publishing it, or drop the consumption |
+| \`spine.message-unbound\` (warn) | a tagged edge in delta.likec4 carries an event key on the wrong end — \`publishes\` binds the SOURCE, \`consumes\` the TARGET — and that end is infrastructure (a topic or store, by its kind in the delta) while a service sits at the other one. Nothing grades the key here, and once archived the living spine reports the same code. An \`#external\` system at that end stays silent, as at service scope | turn the edge round, or split a two-key edge, as the message spells it, before the archive splices it — producer \`-[publishes]->\` topic, topic \`-[delivers]->\` consumer |
+| \`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 |
+| \`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>\` |
+| \`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. A pinned slot whose living one a parallel feature has since REMOVED lands here too: re-read the living contract and delete the slot from the delta, unless this feature deliberately brings it back — then drop the pin and archive with \`--approve\` past \`asyncapi.slot-revived\`. A pinned \`components.messages\` key whose message a parallel feature MOVED elsewhere (another key, or inline under a channel) — or retired there, before another re-declared it elsewhere — lands here as well, and the message names where it is declared now: delete the quote and make any change there — archiving past it would declare the name in two places; to move it back on purpose, drop the pin and take the name out of there as \`asyncapi.slot-revived\`'s row says |
+| \`asyncapi.slot-revived\` (warn, gates archive) | the feature's asyncapi.yaml declares a \`channels\`/\`operations\` slot, or a message by name, that the living contract no longer has, and an ARCHIVED feature retired it — a slot marker, or a channel removal that took the channel's inline messages (named from that feature's \`.loam-before/\` snapshot) — or declares a message at a key an archived feature MOVED it away from (or retired it from, before another re-declared it elsewhere), so the merge would declare its name in two places (the message says what that feature did there, where the name is declared now, and any other message declared at that key now, which archiving replaces there) — judged on the contract the merge would write, so a delta that also takes the name out of where it is declared now (restating or retiring the channel it stands inline in, a marker at its \`components.messages\` key, or another message declared at that key) is moving it back, and is not graded. Absent from living reads like an addition, so the merge would put it back. A message inline under a channel the delta brings back is that channel's finding, unless the merge would also declare its name elsewhere — then it is a two-places finding of its own. A removal made by hand-editing a living contract, or an archive since deleted from disk, is invisible to it | retired: delete the quote if you only restated it; archive with \`--approve\` if the feature brings it back on purpose. Two places: delete the quote and make any change where the message says it is declared now; to move it back on purpose, take it out of there in the same delta — a removal marker at a \`components.messages\` key, AND every channel (or operation) the message names as still \`$ref\`-ing that key restated with the \`$ref\` pointed at the quoted key (retired alone, the key leaves them pointing at nothing, and their send stops sending the message: \`asyncapi.remove-message-consumed\`); for a declaration inline under a channel, restate channel \`<ck>\` with a \`$ref\`, or retire channel \`<ck>\` (a marker nested on the inline message retires nothing: \`asyncapi.remove-marker-inline\`); where another message is declared at the quoted key now, define it at another key to keep it. Where the delta already spells that key, the message offers \`--approve\` instead |
+| \`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 |
+| \`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 |
+| \`asyncapi.remove-marker-missing\` | a REMOVED requirement's \`Publishes:\`/\`Consumes:\` line names a message the living contract still declares, and the contract the merge would write still declares it, with no matching marker in the feature's asyncapi.yaml (a message this delta already takes out — a slot re-keyed to another name — owes none) | 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 |
+| \`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 |
+| \`asyncapi.remove-message-consumed\` | the feature retires a message — a marker, or a removal or edit that stops the service sending it (a slot re-keyed, a send turned to receive) — that the fleet would still name after this merge: a \`consumes\` edge of the \`architecture/\` project, another service's \`Consumes:\` line in either spec file, or a use-case hop backed by such an edge, while nothing would still send the message after this merge (another service's contract, as the merge leaves it, keeps them served, and so does an \`#external\` element whose \`publishes\` edge is in the living map — the outside producer \`spine.message-unproduced\` accepts — unless this feature's \`specs/<service>/\` makes that element a service); or the provider's OWN \`Publishes:\` line or \`publishes\` edge (the spine grades that edge on its source), whoever else sends it — each read as the merge would leave it; \`details[]\` lists them. A consumer document loam cannot read (a spec file that is not UTF-8, the provider's own included) or a service id two directories claim refuses too, named in \`details[]\` — another service's only while nothing would still send the message | make each document listed readable (re-save it as UTF-8, or leave one directory per service id); fix each in the same change (drop the consumes edge, or drop or redraw the provider's publishes edge, in the living map, MODIFY or REMOVE the requirement in this feature's \`specs/<service>/\` delta — a REMOVED one owes no marker for a message the merge already takes out), keep it sent — by an operation in this service, or, for the consumers, by one in another service's asyncapi.yaml (living or in this feature's delta) or by an \`#external\` element's \`publishes\` edge in the living map — or archive with \`--approve\` if it is already gone in code |
+| \`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 |
+| \`c4.op-ungoverned\` (warn) | an operation is called but no requirement governs it | write the requirement |
+| \`c4.op-link-missing\` (warn) | a "Calls" edge in the delta with no \`metadata { op }\` | link it to the operationId |
+| \`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 |
+| \`api.op-unconsumed\` (warn) | an added operation no edge consumes | model the caller, or say why it is provider-only |
+| \`service.no-requirement-delta\` (warn) | a new service with no spec delta — a tagged \`softwareSystem\` of ours that no \`services/<id>/\` and no living map element already stands for. An \`#external\` element, a grouping that contains a service, and the stub of a living element are not new services and never raise it | write \`specs/<svc>/spec.md\`; or, if the system is somebody else's, tag it \`#external\` |
+| \`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 |
+| \`intent.empty\` (warn, gates archive) | intent.md is missing, or its Why/Scope hold nothing outside the scaffold's own comments — questions under \`## Open questions\` do not count | write why the feature exists — it is the first thing a reviewer reads. \`--approve\` overrides |
+| \`archedge.uncovered\` (warn) | no scenario names a tagged edge (a heuristic) | write the scenario, or say why the edge needs none |
+| \`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. The line the message offers is spelled as it will resolve once living: an edge by its endpoints' service names, an element by the service it stands for or the id the merge gives it — the delta's own id only when the merge preview cannot be computed | add the requirement to \`specs/<svc>/arch.spec.md\` (outbox? retries? alerts?), or the architectural obligations ship unchecked |
+| \`covers.unknown\` (warn) | at feature scope, besides the typo: a \`Covers:\` entry that resolves ONLY through delta.likec4's own ids — a stub the delta declares where the living map nests it (\`orderService\` for \`marketplace.orderService\`), or a child under such a stub, which the merge lands under the living parent. It resolves here and is \`covers.unknown\` the moment the archive lands it | write the spelling the message offers — an edge by service names (\`a-service -> b-service\`), an element by the id the merged map gives it; both resolve before and after the archive |
+| \`health.uncovered\` (warn) | at feature scope: an alert or SLI in the service's health.yaml that a LIVING arch.spec.md requirement covers today and nothing would after this merge — a MODIFIED requirement restates its whole block, so a \`Covers: sli:<id>\` line not carried over is a line the merge deletes. Only what the merge takes away; a signal already uncovered is the service target's warning | keep the entry on the MODIFIED requirement, or cover the signal from another requirement in the delta |
+| \`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 |
+| \`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. Also fires on the SERVICE target, under \`--service\` and per service under \`--all\`, for a \`.likec4\` beside model.likec4 that does not read as part of that service's own project — there the flows beside the model were not graded while model.likec4 itself still was | 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\` |
+| \`usecase.step-unbacked\` / \`usecase.requirement-unresolved\` / \`usecase.capability-unresolved\` | a feature's own flow (\`features/<FEAT>/usecases/*.likec4\`) graded as \`validate --all\` grades it once archived: a hop no relationship on the POST-MERGE map backs, a \`#req-\` tag no \`#cap-\` tag scopes or that names no requirement of that capability as the merge leaves it (an id this feature's capability delta ADDS resolves; one it REMOVES does not), or a \`#cap-\` tag naming no capability. Same codes, same sentences, opened by the feature file's path. Errors, so they gate archive | the fixes the fleet-scope rows give: draw the edge (in delta.likec4, tagged, or in the living map), add the \`#cap-\` tag, or correct the id |
+| \`usecase.requirement-modified\` (warn, never gates) | a LIVING flow whose \`#req-\` tag claims a requirement this feature MODIFIES — an \`architecture/\` flow scoped by its \`#cap-\` tag to a capability requirement the feature's capability delta rewrites, or a flow beside a service's model naming one of that service's spec.md / arch.spec.md requirements the feature's \`specs/\` delta rewrites. A MODIFIED keeps the id and replaces the whole text, so the tag still resolves after the archive and every grade stays green while the flow may draw what the new wording forbids. When an id the same feature ADDS flattens to that tag, the tag would not resolve, and the flow gets \`usecase.requirement-unresolved\` instead of this warning | read the named flow against the replacement; if it no longer keeps the promise, redraw it (or drop the tag) in the same change. The warning names the flow and the requirement and stays until the feature archives — loam cannot read a flow's meaning, only that the promise moved under it |
+| \`usecase.requirement-unresolved\` (error, gates archive, \`--approve\`-overridable) | a LIVING flow whose \`#req-\` tag claims a requirement this feature REMOVES — the same two altitudes as \`usecase.requirement-modified\`, a service-local tag read against BOTH of that service's documents. The merge deletes the promise and leaves the tag, so the next \`validate --all\` reports this same error against the living flow; it is raised here first, with the view as its subject as the fleet names it, and only when the tag resolves today and would not after the merge (a removal the delta re-spells under an id flattening to the same tag earns nothing). A MODIFIED earns it too, instead of \`usecase.requirement-modified\`, when an id the feature adds flattens to the same tag | drop the tag from the named living flow (or point it at the promise that replaces this one) in the same change, or MODIFY the requirement instead of removing it; for colliding ids, rename one. \`--approve\` merges past it deliberately, and the living docs then carry exactly this error |
+| \`usecase.step-contested\` / \`usecase.step-unlinked\` (warn) | the same two hop warnings the fleet gives, raised before the archive on a feature's own flow over the post-merge map | as at fleet scope — open the step's title with the operation id the hop means, then punctuation; give the candidates one operation; or \`metadata { op }\` on the edge |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`deployment.doc-exists\` | a \`features/<FEAT>/deployment/<name>.likec4\` whose file the LIVING \`architecture/\` already holds. The merge is a whole-file copy, so it would replace an authored topology wholesale, and \`--approve\` does NOT move it — the same act, and the same severity, as \`usecase.flow-exists\` one axis over. The collision is on the FILE, never on what is inside it: two features may both \`extend\` one living region from documents of their own and both archive | delete the feature's copy and edit \`architecture/<name>.likec4\` directly in the same change — or, to ADD to what that file declares, rename the feature's document and say \`extend\` in it |
+| \`deployment.doc-invalid\` | a \`features/<FEAT>/deployment/*.likec4\` loam could not read against the map this feature's own merge would leave behind — a parse error, an unresolved element, or a landscape merge that itself refuses. The corpus is the feature's \`deployment/\` PLUS the living \`architecture/\` documents it \`extend\`s, so the fault may be in either and every message names its file. \`--approve\` does not move it: the flag overrides loam's judgement about coherence, never its ability to read an axis | fix what the messages name. A document instancing an element only this feature's \`delta.likec4\` adds is LEGAL and resolves — that is what the merge preview is for; one naming an element the merge does not land is the case this refuses |
+| \`deployment.doc-reserved\` | a \`features/<FEAT>/deployment/<name>.likec4\` whose name loam owns inside \`architecture/\`: \`subsystems.likec4\` and \`services.likec4\` (both generated, overwritten wholesale by \`loam subsystem sync\`, and parsed by nothing — so topology landing in either is invisible from the moment it archives), \`landscape.likec4\` (spliced into, never replaced), or any path under \`usecases/\` (the flow tree). Refused whether or not the target exists, which is the point: three of the four fail silently when it does not | rename the feature's document — its name is yours to choose, and \`extend\` is how it adds to what a living document already declares |
+| \`delta.unknown-section\` | a heading that nearly matches the delta grammar | fix it — everything under it merges as NOTHING today, silently |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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) |
+| \`delta.removed-unknown\` | REMOVED one that does not exist | drop the section, or fix the name |
+| \`delta.added-duplicate\` | ADDED a name the living spec already has | use MODIFIED — as written, the merge REPLACES the living requirement |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`delta.removed-pending\` (warn) | REMOVED something another feature in flight introduces | archive that feature first; \`loam dependencies --json\` says in which order |
+| \`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\` |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`evidence.record-unreadable\` (warn) | a file of this feature's verification record (\`verification.yaml\`, or a \`verification/<svc>.yaml\`) exists but cannot be read as a record — broken YAML, git conflict markers after a merge, a shape that is not a record, a summary contradicting its claims. The same code and sentence the service target raises from a service repo; here it fires from anywhere, the docs repo included, because the record lives there. Readability only: the verdict stays \`loam verify\`'s and \`loam status\`'s, and as a warning it never stops \`loam archive\` | repair the file the finding names, following the recipe it carries: a \`verification/<svc>.yaml\` holds one service's word and may be deleted and recorded again from that service's repo; the one-file \`verification.yaml\` may hold other services' attestations, so it is repaired or restored from version control, never deleted. loam never overwrites a record it could not read |
+
+\`--all\` — everything above for every target, plus the fleet cross-check:
+
+| code | what it means | what to do |
+|---|---|---|
+| \`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 |
+| \`landscape.invalid\` | the living landscape does not parse. The fleet map is graded as the \`architecture/\` project and NOTHING ELSE — the landscape plus every \`architecture/**/*.likec4\` except the generated views files (\`subsystems.likec4\` and \`services.likec4\`) — whatever shape the service models take. That is deliberate: the renderer's root project is wider (it also holds every extending model), so a hop in \`architecture/usecases/\` naming a CONTAINER an extending model declares renders perfectly and is \`landscape.invalid\` here. A cross-service flow names service elements; a container-level flow lives beside the model that declares the container. One broken service model must never blank the fleet's own map | fix it first — the fleet cross-check cannot run against a document nobody can read. If the unresolved name is a container an extending model declares, the reference belongs one altitude down whatever carries it: a use-case hop moves beside that service's model.likec4 and is tagged \`#req-\`; a model edge names the SERVICE on the map and the container in the service's own model |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`subsystem.views-stale\` | a GENERATED views file under \`architecture/\` does not match the tree and the map. There are TWO, written by the same command in the same commit, and each earns its own finding naming its own path: \`architecture/subsystems.likec4\` (one view per subsystem) and \`architecture/services.likec4\` (one overview view per service the fleet map draws — the service, its own interior, every peer the map gives it, and \`of <element>\`, which is what makes every other view drill into it). A file is stale when it drifted after a move, is absent while the thing it mirrors exists, lingers after the last of them was removed, or the map moved under it — a service added, an edge drawn, a subsystem renamed, or the global style groups changed. Styling restales the subsystem file twice over: declaring or removing a group named \`subsystems\` changes whether its views carry the \`global style subsystems\` line, and declaring a group under ANY other name changes the disclosure comment that names what is available; the per-service file reads a group named \`services\` the same way. The census reads every \`.likec4\` under \`architecture/\` the root \`likec4.config.json\` does not exclude, so a palette in a sibling counts. One error per stale file, graded by content comparison against the deterministic re-render — never by reading what a view SHOWS (docs/DESIGN.md rule 26) | run \`loam subsystem sync\` — the single regenerator for both files. Never edit either by hand; authored views belong in the landscape or a file of your own, and an authored view \`of\` the same element keeps precedence whenever its file sorts first (\`landscape.likec4\` does, ahead of \`services.likec4\`), with both still reachable. \`sync\` refuses to rewrite a generated file while \`architecture/\` does not parse (\`action: "blocked"\`) — fix the map first; \`validate\` already skips the staleness question in that state. A docs repo that has not run \`sync\` since \`architecture/services.likec4\` existed sees this once for that file; one run clears it |
+| \`service.likec4-config-missing\` (warn) | a model that STANDS ALONE — it declares its own \`specification\` block, so it is parsed alone and cannot share a project with the map — with no \`likec4.config.json\` beside it. It renders only as a project of its own and this one has none: a box on the fleet map with nothing renderable inside it. One warning per service, on the fleet target, only when the root \`likec4.config.json\` exists (\`loam doctor\` prints that one); never gating, because no loam check reads the model any differently. A model that EXTENDS the map never earns this — it belongs to the root project | run \`loam subsystem sync\` — it creates the file (create-only: a file that already exists is yours and is never touched). Never hand-write it; the bytes are a function of the service id, and the writer spells them once |
+| \`service.likec4-config-stray\` (warn) | the mirror: a \`likec4.config.json\` beside a model that EXTENDS the fleet map. The renderer registers that file as a project of its own rooted at that directory, so \`likec4 validate .\` at the docs root refuses without \`--project\`, and wherever that nested project claims the model it parses alone, out of the root project where the map's kinds are: the model does not resolve and \`export json --project fleet\` loses the service's containers (measured, likec4 1.59.2 — it happened on a seeded fleet and not on \`examples/docs\`). Fleet target, root-gated like its siblings, never gating | run \`loam subsystem sync\` — it deletes the file (or delete it yourself). loam never writes one beside an extending model, so this one is a leftover from before the model migrated, or was hand-written |
+| \`service.model-excluded\` (warn) | a model that EXTENDS the fleet map whose directory the root \`likec4.config.json\`'s \`exclude\` covers — or whose \`model.likec4\` a FILE-shaped entry (\`services/**/model.likec4\`) names; the message says which shape it found. An entry is read the way the renderer reads it: a bare entry is a raw path PREFIX from a \`/\` boundary, so \`services\`, \`services/\`, \`services/*\`, \`services/**\`, \`services/**/*\`, a wildcard segment in the middle (\`services/*/legacy\`) and the bare \`services/pay\` all cover \`services/payment-service\` — while \`services/pay/**\` wants the literal separator and covers nothing there. The renderer never loads the model, so the service is a box with nothing inside it from the docs root, while every loam check still grades it perfectly: the gap is invisible except here. The finding quotes the entry verbatim, because the repair is to edit that line | for a DIRECTORY entry, run \`loam subsystem sync\` — it rewrites the root project's \`exclude\` to cover exactly the models that stand alone, keeping every entry that is not about \`services/\` in the order the team wrote it. For a FILE-shaped entry sync repairs nothing: remove or narrow that line by hand, then re-run |
+| \`service.model-unexcluded\` (warn) | the mirror of that one: a model that STANDS ALONE whose directory the root \`exclude\` does NOT cover. The renderer merges it into the root project and reports every kind and element it declares as a duplicate of the map's — which blanks the whole root project, not just this service. The most damaging of the four, and the one a fresh scaffold walks into the moment somebody writes a model in the old shape. An entry already covering the directory in any of its spellings satisfies it — no second glob is wanted, and none is appended | run \`loam subsystem sync\` — it adds \`services/<tree>/**\` to the root project's \`exclude\`. Or migrate the model to extend the map (SCHEMA.md, "Two shapes of a service model"), after which no exclusion is wanted |
+| \`landscape.excluded\` (warn) | the same root \`exclude\` list, one level up: an entry covering \`architecture/landscape.likec4\` itself. The renderer then loads NO fleet map — it draws nothing, and every model that EXTENDS the map resolves against nothing in the root project, which is also what WOULD turn \`c4.fleet-project-invalid\` into a page of unresolved references — measured on the packaged example fleet, one authored line came back as 161 of them. So that check is not graded at all while this entry stands, and this finding is the only line in the run that names the cause; remove the entry and the fleet project is graded again. loam is otherwise unaffected: the architecture loader keeps the map whatever the list says, so every grade in the run is right, and that is exactly why the state was invisible until this code existed. An entry is matched as a FILE path here, not as a directory, so \`architecture/*.likec4\` — a line somebody wrote for a palette — covers it while \`services/**\` and \`features/**\` do not. Quoted verbatim, because the repair is to edit that line | remove the entry, or narrow it to the paths it was written for. NOT \`loam subsystem sync\`: that command maintains only the \`services/\` entries in the list and leaves every other line exactly as the team wrote it, so it would report success and change nothing |
+| \`c4.fleet-project-invalid\` (warn) | every document reads clean where loam grades it, and the ONE project the renderer builds out of them does not parse. \`--all\` only, only when at least one extending model exists, the map itself parses, and the root \`exclude\` does not cover the map (\`landscape.excluded\` then names that one entry and this check stands down behind it, because this load reads what the renderer reads and has no floor under the map): loam walks the docs root and loads what the renderer's root project loads — everything the root \`exclude\` leaves, minus the generated views files (\`subsystems.likec4\` and \`services.likec4\`), minus every STANDALONE service directory (\`service.model-unexcluded\` owns that state), minus \`features/\` (a delta carries its own \`specification\` and the directory is transient) — and reports each error that is NOT already present in the map alone, in some per-service project, or in a service-flow project the same run made. A \`.likec4\` in a SUBSYSTEM directory, above every service, is in that set. That difference is exactly the class no per-service grade can see: two services each declaring \`tag req-AUTH\` locally, two models adding the same child id under one element, a broken untagged sibling nobody opted in. All of them are renderer-fatal and all of them were silent. \`locations[0]\` is the file the error is IN, \`details\` carry \`<path>: L<n>: <error>\` 1-based — path, colon, space, then the line, exactly as the message's own head spells it, so an agent splitting on the separator gets the same two halves from either — and the message tail names the failure it actually is — a double declaration, an unresolved reference, or neither. \`subject\` is the service whose directory holds the file, where there is one | declare it once — in \`architecture/landscape.likec4\`, or in the single service that owns it — at the file and line the message names. Never by excluding the directory: that hides the model from the renderer instead (\`service.model-excluded\`) |
+| \`subsystem.view-id-collision\` | a document the root project reads declares a view whose id is one loam GENERATES — \`subsystem_<name>\` into \`architecture/subsystems.likec4\`, or \`service_<id>\` into \`architecture/services.likec4\`. Two reserved prefixes, one code, because the failure is identical: LikeC4 merges every file of a project into one model 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. Under \`--all\` the census covers every EXTENDING model's authored view ids as well as the landscape's, because those documents are in the same root project now; a standalone model's are not, since its views live in a project of its own. 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 it, and a \`service_\`-looking id is reserved only for a service the fleet MAP DRAWS — an unmodelled \`services/<id>/\` mints nothing until an element resolves to it | rename the view in the file the finding names — the message names which file and which prefix. Ids beginning \`subsystem_\` or \`service_\` are loam's to mint; both generated files are written by \`loam subsystem sync\` and are never hand-edited |
+| \`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\`) |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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\` |
+| \`landscape.service-isolated\` (warn) | an element resolves to a \`services/<id>/\` and no edge anywhere in \`architecture/\` touches it, while that service's own \`model.likec4\` declares a call across its boundary. The map draws the service and nothing reaches it, so every cross-service check is vacuous over it — and \`loam validate --service\` cannot see it. Evidence-gated: a service whose model declares no cross-boundary call is silent here, and the adopt brief's \`landscape.touched\` is the only place that state is named. Binary, too: ONE edge closes it, so a map drawing one of five attested calls is silent — the check is touched/untouched, not a set difference, and the calls left undrawn are named nowhere. An \`#external\` element is never the subject, whatever it is bound to; the touched side applies no tag filter — an edge on an \`#external\` element the service owns (a kind-tagged topic, say) still touches it, exactly as the adopt brief's \`landscape.touched\` counts it | draw each attested call as one edge on the element, collapsed to the service, carrying \`metadata { op '<operationId>' }\` for a call or \`publishes\`/\`consumes\` for an event, naming the other party as the map already spells it — never a second element |
+| \`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 |
+| \`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. A service counts at the source of an edge into the element, and at EITHER end where the element's end is infrastructure (a \`database\`, \`queue\`, \`topic\`, \`cache\` or \`bucket\`), so a broker's consumers drawn \`topic -> service\` count | 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 |
+| \`landscape.datastore-shared\` (warn) | a datastore consumed by two or more services — the strongest coupling in the fleet, stated rather than inferred. Two shapes: a store drawn as a fleet-level peer, and a store NESTED inside its owner's element that another service reaches — the message adds \` — <owner>'s own store, written as '<store-fqn>'\` for the second, \`<store-fqn>\` being the store's own id, and then says the move is ONE-WAY at this point: the other consumers' edges resolve only against a declaration the MAP holds, so out of the owner's \`extend\` block onto the map is always safe while moving it back INTO the \`extend\` block breaks them (\`c4.invalid\` on that service's model, or \`landscape.invalid\` when the edge is drawn on the map). Consumers are counted from the map's edges AND from every extending model's attested calls, in EITHER direction: a store never initiates, so \`store -> service\` (a read drawn as the data's flow) counts that service exactly as \`service -> store\` does | 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 |
+| \`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, or carried by a flow inside a service's own project (a \`dynamic view\` beside model.likec4), where no capability can be claimed — that arm fires whether or not the vocabulary exists, and the fix is to drop the tag or move the flow to \`architecture/usecases/\` | 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 |
+| \`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 |
+| \`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 |
+| \`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>)\` — \`(publishes: <message>)\`, \`(consumes: <message>)\` or \`(no op)\` where that is what the edge declares | say which one the hop means by opening the step's title with that candidate's operation id or message name — \`orders -> payments 'authorizePayment — authorizes the payment'\` — or give the candidates one operation. Only the title's OPENING counts, matched exactly against a name an edge declares, followed by the end of the title or by punctuation, and only among the candidates: the name as the first word of a sentence (\`'read the order'\`), a name later in it, or a relationship's own title picks nothing. Drawing the hop between containers instead works only where the map itself draws them — a container an extending model declares does not resolve on a fleet flow. 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 |
+| \`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. Never on a hop whose caller and provider resolve to the SAME service — two containers of one service, inside its own project or drawn on the landscape — because a service owes no operationId to itself; that is the fourth mechanical guard, and its whole scope. A hop from a service-local flow into ANOTHER service's element (a stand-in model.likec4 declares for a sibling, with no \`metadata { op }\`) still warns, on the service target, exactly as it does on the fleet map | add \`metadata { op '<operationId>' }\` to the edge in \`model { }\`, or \`metadata { publishes '<message>' }\` / \`consumes\` where the hop is an event |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+
+frontmatter and provenance — services' spec.md and arch.spec.md, and features'
+intent.md, both modes:
+
+| code | what it means | what to do |
+|---|---|---|
+| \`frontmatter.missing\` (warn) | no frontmatter at all | add owner, status and sources |
+| \`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 |
+| \`frontmatter.field-mismatch\` | the doc names a different service/feature than the one it lives under | fix the frontmatter, or move the file |
+| \`frontmatter.status-unknown\` | a status nobody defined (\`verifed\`) | use the documented vocabulary — a typo here reads as unverified forever |
+| \`frontmatter.field-missing\` (warn) | owner, status or the identity field is absent | fill them in |
+| \`frontmatter.owner-mismatch\` (warn) | one service's spec.md and arch.spec.md both name an \`owner\` and the two differ — \`loam show\` and \`loam context\` print only spec.md's, so the other is a second answer nobody sees. The \`details\` list each file's value. Compares the two files only, never CODEOWNERS | make the two agree; only a person knows which one is current |
+| \`sources.absent\` (warn) | the doc names no sources | nothing ties it to the code, so nothing can tell you when it goes stale |
+| \`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 |
+| \`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 |
+| \`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>\` |
+| \`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 |
+| \`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 |
+| \`sources.unvouched\` (warn) | \`sources\` with no \`sources_digest\` — nobody ever stamped it | leave it: vouching is a human's reading, not yours |
+| \`sources.unwalked\` (warn) | \`sources\` leaves whole top-level paths of the service repo untouched — the \`details\` name them, measured against the files git tracks — minus loam's own (\`loam.json\` and the agent files it recorded) and \`.gitignore\`, which no document owes a reading of. 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 |
+| \`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 |
+| \`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 |
+| \`sources.resolved\` (ok) | every listed source still exists in the service repo | nothing — it is the confirmation |
+| \`sources.current\` (ok) | the stamped \`sources_digest\` still matches the code — nothing moved since a human vouched | nothing — it is the confirmation |
+| \`sources.walked\` (ok) | no whole top-level path of the service repo is left untouched by \`sources\` | nothing — it is the confirmation |
+
+\`loam archive\` — breaches the merge computation sees, reported at plan time.
+Most never appear in \`validate\`; the ones that do are graded harder here,
+because the merge is about to WRITE the breach into the living contract
+(\`openapi.ref-unresolved\` and \`asyncapi.ref-unresolved\` are validate warns but
+plan errors; \`openapi.remove-marker-path-level\` fires in validate on a living
+contract too):
+
+| code | what it means | what to do |
+|---|---|---|
+| \`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 |
+| \`openapi.op-modified\` (warn) | the feature redefines an operation the living OpenAPI already has — the merge overwrites the living definition wholesale. The message ends with whether the CURRENT fleet names the operation, and \`details\` lists who does — landscape edges, other services' living requirements, use-case hops — then any consumer that could not be checked; the same scan \`loam diff\` runs. Whether the change breaks them is not graded | make sure the redefinition is intended and safe for every consumer listed (\`oasdiff breaking\` on the two contract states tells a breaking change from an additive one); if not, align the feature's openapi.yaml with the living one |
+| \`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 |
+| \`service.no-model\` (error, never gates archive) | the archive brings a service into the fleet without writing its \`model.likec4\` — a binding the map gains with no \`specs/<id>/\` in the feature, so no directory either, or (under \`--approve\`) a \`specs/<id>/\` the merged map never draws. A service whose \`services/<id>/\` the archive creates and the merged map draws gets an empty extending model written beside its documents, with whatever the delta drew inside the service spliced into it, and raises nothing. An error because \`validate --all\` reports one next (\`landscape.binding-unknown\` for a binding with no directory, \`service.no-model\` for a directory with no model; the message names which), in \`--json\` \`warnings[]\` with \`gates: false\`, and printed by the dry run and the real run in place of the closing line | give the service its documents — \`loam adopt --service <id>\` from its repo writes the directory and the model — or write them by hand; until then \`validate --all\` grades the fleet incomplete |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`asyncapi.message-modified\` (warn) | the delta redefines a \`components.messages\` slot the living AsyncAPI already has — the merge overwrites the living message wholesale. The message ends with whether the CURRENT fleet consumes it, and \`details\` lists who does — \`consumes\` edges, other services' \`Consumes:\` lines, use-case hops — then any consumer that could not be checked; the same scan \`loam diff\` runs. Whether the change breaks them is not graded | make sure the redefinition is intended and safe for every consumer listed; if not, align the feature's asyncapi.yaml with the living one, then \`loam rebase\` so the restatement classifies as a quote |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`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 |
+| \`openapi.info-not-merged\` (warn) | the feature's openapi.yaml spells an \`info\` key — a \`version\`, a \`description\` — differently from the living contract, and the merge carries paths and components only, never \`info\`: the living contract keeps its own, so the delta's change would be lost with exit 0. Only keys the delta declares are compared | if the \`info\` should move, edit the living \`services/<id>/openapi.yaml\` in the same change; if it should not, drop \`info\` from the delta or restate the living values |
+| \`asyncapi.info-not-merged\` (warn) | the event-axis twin: the feature's asyncapi.yaml spells an \`info\` key differently from the living contract, and the merge carries channels, operations and components only | edit the living \`services/<id>/asyncapi.yaml\` in the same change if it should move; otherwise drop or restate \`info\` in the delta |
+| \`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 |
+
+\`loam validate <target>\` — the positional form's own finding, both modes:
+
+| code | what it means | what to do |
+|---|---|---|
+| \`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 |
+
+confirmations — the \`ok\`-severity findings a clean axis reports, so silence is
+never the signal (\`--errors-only\` hides them from the text view; \`--json\`
+always carries them):
+
+| code | what it means | what to do |
+|---|---|---|
+| \`c4.valid\` (ok) | the service's model.likec4 parses and the C4 axis was actually graded. Its message says HOW the file was read: "extends the fleet map — N elements · M relationships" for a model with no \`specification\` block of its own, parsed together with \`architecture/landscape.likec4\`; the plain wording for one that stands alone. A trailing \` · K tagged flow(s) graded\` says the service's own project declared use cases and they were graded — the one surface a HEALTHY intra-service flow appears on | nothing — it is the confirmation |
+| \`delta.valid\` (ok) | the feature's delta.likec4 parses and its tagged change is well-formed | nothing — it is the confirmation |
+| \`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 |
+| \`requirements.covered\` (ok) | every requirement carries at least one scenario | nothing — it is the confirmation |
+| \`api.covered\` (ok) | every operation in openapi.yaml is governed by some requirement's \`Operations:\` line | nothing — it is the confirmation |
+| \`event.covered\` (ok) | the event axis joins clean — every declared message is linked and governed | nothing — it is the confirmation |
+| \`spine.resolved\` (ok) | every inbound landscape call into this service resolves to an operation its OpenAPI defines | nothing — it is the confirmation |
+| \`landscape.matched\` (ok) | every \`services/<id>/\` resolves to a landscape element and every binding holds | nothing — it is the confirmation |
+
+\`sources.stale\`, \`content.stale\` and \`sources.sampled-vouch\` are the warnings you
+cannot close by yourself. Fix what the code now says, then hand it back — the stamp
+is a person's claim to have read it, and the last of the three says how much of it
+they read.
+`,
+};
+//# sourceMappingURL=check.js.map