@ybotok/loam 0.2.0-alpha.5 → 0.2.0-alpha.7

package/dist/core/agent/agents-md/map/subsystem.js

@@ -15,8 +15,8 @@ export const SUBSYSTEM_COMMANDS = `- \`loam subsystem <verb>\` manages the group
   [--owner]\` creates a group (an empty one is legal — its \`subsystem.yaml\` is a
   marker, never a member list); \`move <name>... --into <sub|.>\` relocates
   services and whole subtrees in ONE journaled transaction over the renames
-  plus the regenerated views file (\`--into .\` unfiles; the renames and the
-  regenerated views file are staged in git without committing, where git answers); \`rename <old> <new>\` renames a
+  plus BOTH regenerated views files (\`--into .\` unfiles; the renames and the
+  regenerated views files are staged in git without committing, where git answers); \`rename <old> <new>\` renames a
   group through the same transaction (services are never renamed — the id is
   the identity); \`rm <name>\` removes an EMPTY group; \`list\` shows the tree
   with member counts and the unfiled count (unfiled is permanent and normal —
@@ -24,25 +24,78 @@ export const SUBSYSTEM_COMMANDS = `- \`loam subsystem <verb>\` manages the group
   additive keys \`services[].subsystem\`, \`subsystems[]\` and
   \`unfiledServices\`); \`history <name>\` asks git how a service or subsystem
   moved and answers nothing — exit 0, no finding — when git will not say;
-  \`sync\` regenerates \`architecture/subsystems.likec4\`, the one repair for
-  \`subsystem.views-stale\`, and also writes one create-only
-  \`services/<…>/<id>/likec4.config.json\` per service model (never rewritten, never
-  removed; the team may edit it; commit the new files before a \`move\`, which
-  refuses over untracked paths) — the one thing that makes a model renderable
-  from the docs root beside the fleet map, and the repair for
-  \`service.likec4-config-missing\`. A flat fleet with no subsystems still owes
-  this run: the verb is the tree's, the file is the renderer's. With more than
-  one project \`likec4 validate\` at the docs root needs \`--project <name>\`
-  (\`build\` and \`export\` take every project); a
-  landscape view claiming a generated id is
-  \`subsystem.view-id-collision\`. Each generated view is titled by its PATH —
+  \`sync\` regenerates BOTH generated views files —
+  \`architecture/subsystems.likec4\` (one view per subsystem) and
+  \`architecture/services.likec4\` (one overview view per service the fleet map
+  draws) — the one repair for \`subsystem.views-stale\`, which grades each file
+  separately and names the one that drifted. It also maintains the RENDERER's
+  wiring for the service models. Which wiring a model needs is decided by the file's own
+  grammar, never by a config key: a model that declares its own
+  \`specification { element … }\` block STANDS ALONE — it cannot share a project
+  with the fleet map, since every kind it declares would be a duplicate there —
+  and a model with no such block EXTENDS the map with
+  \`extend <fully-qualified id> { … }\` and parses only INSIDE the root project.
+  So \`sync\` writes one create-only \`services/<…>/<id>/likec4.config.json\` per
+  STANDALONE model (never rewritten; the team may edit it; commit
+  the new files before a \`move\`, which refuses over untracked paths), DELETES one
+  sitting beside an EXTENDING model (that nested project claims the model out of
+  the root project, so \`likec4 validate .\` refuses without \`--project\` and,
+  wherever that project claims the model, \`export json --project fleet\` loses
+  the service's containers; \`--json\` lists what it removed as \`projects.removed\`), and rewrites
+  the root \`likec4.config.json\`'s \`exclude\` to hold \`services/<tree>/**\` for
+  exactly those models, keeping every entry that is not about \`services/\` in the
+  order the team wrote it. It rewrites that list when at least one extending model
+  exists, or when a standalone model's directory is not covered — an older repo
+  whose models all stand alone behind \`services/**\` is never touched. \`--json\`
+  carries the result as \`projects.exclude\`, and the text view prints one line when
+  it rewrote. Between them these repair four warnings:
+  \`service.likec4-config-missing\` (a standalone model with no project file),
+  \`service.likec4-config-stray\` (a project file beside an extending model),
+  \`service.model-excluded\` (an extending model the root \`exclude\` hides from the
+  renderer) and \`service.model-unexcluded\` (a standalone model it does not hide,
+  which blanks the whole root project). A flat fleet with no subsystems still owes
+  this run: the verb is the tree's, the files are the renderer's. A fleet whose
+  models all extend the map ends with ONE project and one picker entry, and
+  \`likec4 validate\` at the docs root needs no flag; each standalone model adds a
+  project, and with more than one \`likec4 validate\` needs \`--project <name>\`
+  (\`build\` and \`export\` take every project). A view id claimed twice inside one
+  project — the landscape and an extending model both minting it, or either
+  claiming a generated one — is
+  \`subsystem.view-id-collision\` — ids beginning \`subsystem_\` or \`service_\` are
+  loam's to mint. Each generated view is titled by its PATH —
   every marked ancestor's label and its own, which the renderer reads as
   folders — where a label is the marker's \`title\` or the directory name; the
-  marker's \`description\` rides along. So editing \`subsystem.yaml\` changes
+  marker's \`description\` rides along. A per-service view is titled
+  \`<subsystem path> / <service id>\`, so it lands in the same folder as its
+  group, and a \`dynamic view\` you write under
+  \`services/<…>/<id>/usecases/\` titled \`<subsystem path> / <service id> / <use
+  case>\` lands beside it. So editing \`subsystem.yaml\` changes
   what the renderer LABELS the group, a parent's title changes every view
-  beneath it, and either makes the file stale until the next \`sync\`. It is generated wholesale:
+  beneath it, and either makes both files stale until the next \`sync\`. Neither
+  generated file is part of the fleet-project load
+  (\`c4.fleet-project-invalid\` reads every other \`.likec4\` the root project holds);
+  \`subsystem.views-stale\` is the only check that reads them, by content
+  comparison against the deterministic re-render, never by reading what a view
+  shows. Each per-service view is declared \`of\` its service's element, which is
+  what makes every other view — the fleet map, its subsystem view, its peers'
+  views — drill into it with no authored link. Each subsystem view
+  carries \`global style subsystems\` — written after its title, the one line
+  LikeC4 gives a view for borrowing a palette — exactly when the \`architecture/\`
+  project declares a global style with that id (\`global { styleGroup subsystems
+  { style element.tag = #external { color gray } } }\`, in the landscape or in
+  ANY \`.likec4\` under \`architecture/\` the root \`exclude\` does not cover — a
+  \`palette.likec4\` beside the map counts); nothing otherwise, and loam never reads
+  what the group says. Declaring it is the whole opt-in and makes the file stale
+  once, until the next \`sync\`. When the project declares style groups under other
+  names only, the file opens with one comment line naming them and saying none is
+  \`subsystems\`, and the views carry the renderer's defaults — so declaring a group
+  under ANY name restales the file, because that comment is part of the bytes.
+  \`architecture/services.likec4\` reads a group named \`services\` the same way.
+  \`sync\` refuses to rewrite either file while \`architecture/\` does not parse
+  (\`action: "blocked"\`): fix the map first. Both are generated wholesale:
   an authored diagram of the same services belongs in the landscape or in a
-  file of your own name, never here. \`loam adopt --subsystem <name>\` briefs a new
+  file of your own name, never here. \`--json\` reports the subsystem file as
+  \`path\`/\`action\` and the per-service one as \`serviceViews\`. \`loam adopt --subsystem <name>\` briefs a new
   service's baseline directly into a group, so adoption need not land unfiled.
 `;
 //# sourceMappingURL=subsystem.js.map

package/dist/core/agent/agents-md/map/subsystem.js.map

@@ -1 +1 @@
-{"version":3,"file":"subsystem.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/subsystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCjC,CAAC","sourcesContent":["/**\n * The `loam subsystem` half of the command map — its own section module\n * because command-map.ts sat against the file-line limit and the agents-md\n * package against the five-file cap, so the tree surface's documentation\n * lives one package down and is concatenated after the map.\n *\n * Same assembly contract as every section: ../agents-md.ts concatenates with\n * NO join separator, so this string starts at the first character of its\n * opening line and ends with the newline that closes its last one.\n */\nexport const SUBSYSTEM_COMMANDS = `- \\`loam subsystem <verb>\\` manages the grouping tree under \\`services/\\` — the\n  navigable tree no identity depends on: a service id stays its leaf directory\n  name, every join key is byte-identical before and after a move, and the tree\n  carries no policy. Verbs: \\`new <name> [--under <sub>] [--title] [--description]\n  [--owner]\\` creates a group (an empty one is legal — its \\`subsystem.yaml\\` is a\n  marker, never a member list); \\`move <name>... --into <sub|.>\\` relocates\n  services and whole subtrees in ONE journaled transaction over the renames\n  plus the regenerated views file (\\`--into .\\` unfiles; the renames and the\n  regenerated views file are staged in git without committing, where git answers); \\`rename <old> <new>\\` renames a\n  group through the same transaction (services are never renamed — the id is\n  the identity); \\`rm <name>\\` removes an EMPTY group; \\`list\\` shows the tree\n  with member counts and the unfiled count (unfiled is permanent and normal —\n  a count, never a finding; \\`loam list --json\\` carries the same facts as\n  additive keys \\`services[].subsystem\\`, \\`subsystems[]\\` and\n  \\`unfiledServices\\`); \\`history <name>\\` asks git how a service or subsystem\n  moved and answers nothing — exit 0, no finding — when git will not say;\n  \\`sync\\` regenerates \\`architecture/subsystems.likec4\\`, the one repair for\n  \\`subsystem.views-stale\\`, and also writes one create-only\n  \\`services/<…>/<id>/likec4.config.json\\` per service model (never rewritten, never\n  removed; the team may edit it; commit the new files before a \\`move\\`, which\n  refuses over untracked paths) — the one thing that makes a model renderable\n  from the docs root beside the fleet map, and the repair for\n  \\`service.likec4-config-missing\\`. A flat fleet with no subsystems still owes\n  this run: the verb is the tree's, the file is the renderer's. With more than\n  one project \\`likec4 validate\\` at the docs root needs \\`--project <name>\\`\n  (\\`build\\` and \\`export\\` take every project); a\n  landscape view claiming a generated id is\n  \\`subsystem.view-id-collision\\`. Each generated view is titled by its PATH —\n  every marked ancestor's label and its own, which the renderer reads as\n  folders — where a label is the marker's \\`title\\` or the directory name; the\n  marker's \\`description\\` rides along. So editing \\`subsystem.yaml\\` changes\n  what the renderer LABELS the group, a parent's title changes every view\n  beneath it, and either makes the file stale until the next \\`sync\\`. It is generated wholesale:\n  an authored diagram of the same services belongs in the landscape or in a\n  file of your own name, never here. \\`loam adopt --subsystem <name>\\` briefs a new\n  service's baseline directly into a group, so adoption need not land unfiled.\n`;\n"]}
+{"version":3,"file":"subsystem.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/subsystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyFjC,CAAC","sourcesContent":["/**\n * The `loam subsystem` half of the command map — its own section module\n * because command-map.ts sat against the file-line limit and the agents-md\n * package against the five-file cap, so the tree surface's documentation\n * lives one package down and is concatenated after the map.\n *\n * Same assembly contract as every section: ../agents-md.ts concatenates with\n * NO join separator, so this string starts at the first character of its\n * opening line and ends with the newline that closes its last one.\n */\nexport const SUBSYSTEM_COMMANDS = `- \\`loam subsystem <verb>\\` manages the grouping tree under \\`services/\\` — the\n  navigable tree no identity depends on: a service id stays its leaf directory\n  name, every join key is byte-identical before and after a move, and the tree\n  carries no policy. Verbs: \\`new <name> [--under <sub>] [--title] [--description]\n  [--owner]\\` creates a group (an empty one is legal — its \\`subsystem.yaml\\` is a\n  marker, never a member list); \\`move <name>... --into <sub|.>\\` relocates\n  services and whole subtrees in ONE journaled transaction over the renames\n  plus BOTH regenerated views files (\\`--into .\\` unfiles; the renames and the\n  regenerated views files are staged in git without committing, where git answers); \\`rename <old> <new>\\` renames a\n  group through the same transaction (services are never renamed — the id is\n  the identity); \\`rm <name>\\` removes an EMPTY group; \\`list\\` shows the tree\n  with member counts and the unfiled count (unfiled is permanent and normal —\n  a count, never a finding; \\`loam list --json\\` carries the same facts as\n  additive keys \\`services[].subsystem\\`, \\`subsystems[]\\` and\n  \\`unfiledServices\\`); \\`history <name>\\` asks git how a service or subsystem\n  moved and answers nothing — exit 0, no finding — when git will not say;\n  \\`sync\\` regenerates BOTH generated views files —\n  \\`architecture/subsystems.likec4\\` (one view per subsystem) and\n  \\`architecture/services.likec4\\` (one overview view per service the fleet map\n  draws) — the one repair for \\`subsystem.views-stale\\`, which grades each file\n  separately and names the one that drifted. It also maintains the RENDERER's\n  wiring for the service models. Which wiring a model needs is decided by the file's own\n  grammar, never by a config key: a model that declares its own\n  \\`specification { element … }\\` block STANDS ALONE — it cannot share a project\n  with the fleet map, since every kind it declares would be a duplicate there —\n  and a model with no such block EXTENDS the map with\n  \\`extend <fully-qualified id> { … }\\` and parses only INSIDE the root project.\n  So \\`sync\\` writes one create-only \\`services/<…>/<id>/likec4.config.json\\` per\n  STANDALONE model (never rewritten; the team may edit it; commit\n  the new files before a \\`move\\`, which refuses over untracked paths), DELETES one\n  sitting beside an EXTENDING model (that nested project claims the model out of\n  the root project, so \\`likec4 validate .\\` refuses without \\`--project\\` and,\n  wherever that project claims the model, \\`export json --project fleet\\` loses\n  the service's containers; \\`--json\\` lists what it removed as \\`projects.removed\\`), and rewrites\n  the root \\`likec4.config.json\\`'s \\`exclude\\` to hold \\`services/<tree>/**\\` for\n  exactly those models, keeping every entry that is not about \\`services/\\` in the\n  order the team wrote it. It rewrites that list when at least one extending model\n  exists, or when a standalone model's directory is not covered — an older repo\n  whose models all stand alone behind \\`services/**\\` is never touched. \\`--json\\`\n  carries the result as \\`projects.exclude\\`, and the text view prints one line when\n  it rewrote. Between them these repair four warnings:\n  \\`service.likec4-config-missing\\` (a standalone model with no project file),\n  \\`service.likec4-config-stray\\` (a project file beside an extending model),\n  \\`service.model-excluded\\` (an extending model the root \\`exclude\\` hides from the\n  renderer) and \\`service.model-unexcluded\\` (a standalone model it does not hide,\n  which blanks the whole root project). A flat fleet with no subsystems still owes\n  this run: the verb is the tree's, the files are the renderer's. A fleet whose\n  models all extend the map ends with ONE project and one picker entry, and\n  \\`likec4 validate\\` at the docs root needs no flag; each standalone model adds a\n  project, and with more than one \\`likec4 validate\\` needs \\`--project <name>\\`\n  (\\`build\\` and \\`export\\` take every project). A view id claimed twice inside one\n  project — the landscape and an extending model both minting it, or either\n  claiming a generated one — is\n  \\`subsystem.view-id-collision\\` — ids beginning \\`subsystem_\\` or \\`service_\\` are\n  loam's to mint. Each generated view is titled by its PATH —\n  every marked ancestor's label and its own, which the renderer reads as\n  folders — where a label is the marker's \\`title\\` or the directory name; the\n  marker's \\`description\\` rides along. A per-service view is titled\n  \\`<subsystem path> / <service id>\\`, so it lands in the same folder as its\n  group, and a \\`dynamic view\\` you write under\n  \\`services/<…>/<id>/usecases/\\` titled \\`<subsystem path> / <service id> / <use\n  case>\\` lands beside it. So editing \\`subsystem.yaml\\` changes\n  what the renderer LABELS the group, a parent's title changes every view\n  beneath it, and either makes both files stale until the next \\`sync\\`. Neither\n  generated file is part of the fleet-project load\n  (\\`c4.fleet-project-invalid\\` reads every other \\`.likec4\\` the root project holds);\n  \\`subsystem.views-stale\\` is the only check that reads them, by content\n  comparison against the deterministic re-render, never by reading what a view\n  shows. Each per-service view is declared \\`of\\` its service's element, which is\n  what makes every other view — the fleet map, its subsystem view, its peers'\n  views — drill into it with no authored link. Each subsystem view\n  carries \\`global style subsystems\\` — written after its title, the one line\n  LikeC4 gives a view for borrowing a palette — exactly when the \\`architecture/\\`\n  project declares a global style with that id (\\`global { styleGroup subsystems\n  { style element.tag = #external { color gray } } }\\`, in the landscape or in\n  ANY \\`.likec4\\` under \\`architecture/\\` the root \\`exclude\\` does not cover — a\n  \\`palette.likec4\\` beside the map counts); nothing otherwise, and loam never reads\n  what the group says. Declaring it is the whole opt-in and makes the file stale\n  once, until the next \\`sync\\`. When the project declares style groups under other\n  names only, the file opens with one comment line naming them and saying none is\n  \\`subsystems\\`, and the views carry the renderer's defaults — so declaring a group\n  under ANY name restales the file, because that comment is part of the bytes.\n  \\`architecture/services.likec4\\` reads a group named \\`services\\` the same way.\n  \\`sync\\` refuses to rewrite either file while \\`architecture/\\` does not parse\n  (\\`action: \"blocked\"\\`): fix the map first. Both are generated wholesale:\n  an authored diagram of the same services belongs in the landscape or in a\n  file of your own name, never here. \\`--json\\` reports the subsystem file as\n  \\`path\\`/\\`action\\` and the per-service one as \\`serviceViews\\`. \\`loam adopt --subsystem <name>\\` briefs a new\n  service's baseline directly into a group, so adoption need not land unfiled.\n`;\n"]}

package/dist/core/agent/agents-md/map/usecases.js

@@ -23,7 +23,13 @@ export const USECASE_VIEWS = `- Business use cases are \`dynamic view\`s, and \`
   tag the view \`#cap-<capability>\` to have it graded. The tag spells a declared
   capability id with every \`/\` flattened to \`-\` (a LikeC4 tag name cannot carry a
   slash), and it must be declared as a \`tag\` in the one \`specification\` block the
-  project has, since LikeC4 refuses an undeclared tag. EITHER reserved prefix
+  \`architecture/\` project has, since LikeC4 refuses an undeclared tag. loam grades
+  the fleet map as THAT project and nothing else — the landscape plus its
+  siblings, never a service model — so a hop here names SERVICE elements: a step
+  naming a container that a service's extending model declares resolves in the
+  renderer's wider root project and is \`landscape.invalid\` for loam, which takes
+  the whole fleet map down. Container-level flows live beside the model that
+  declares them (below). EITHER reserved prefix
   opts a view in — a view carrying only \`#req-<requirement>\` is graded too, and
   earns \`usecase.requirement-unresolved\` for the \`#cap-\` tag it is missing
   rather than silence. An UNTAGGED dynamic view is somebody's hand-drawn diagram
@@ -38,6 +44,37 @@ export const USECASE_VIEWS = `- Business use cases are \`dynamic view\`s, and \`
   hop written \`a <- b\` is attributed to the call it answers, so spell replies
   that way rather than as fresh hops. Every message names the file the view was
   written in, never the landscape.
+- A flow behind ONE service's own requirement — the hop sequence over its
+  containers that an arch.spec.md \`Covers:\` names — lives in that service's own
+  LikeC4 project: any \`.likec4\` beside \`services/<…>/<svc>/model.likec4\`
+  (\`usecases/<name>.likec4\` by convention, or \`views.likec4\`), or a \`dynamic view\`
+  inside model.likec4 itself; loam reads exactly what the renderer's per-service
+  project reads. Never \`architecture/usecases/\`, which cannot resolve a container
+  and turns the whole fleet \`landscape.invalid\`. Tag it \`#req-<Requirement-ID>\`
+  (the id flattened as above). The tag has to be DECLARED where that project can
+  see it: in model.likec4's own \`specification\` block when the model declares one
+  and therefore stands alone; in \`architecture/landscape.likec4\`'s block when the
+  model EXTENDS the map, or in a tags-only \`specification { tag req-… }\` beside
+  the \`extend\`, which is legal and lands the tag in the project's specification.
+  Declaring it in BOTH is a duplicate, and the code is the one that lands where
+  the second declaration's FILE is: \`c4.invalid\` (an error, and the model's
+  grading is suspended behind it) when the tags-only block is in model.likec4,
+  \`usecase.flow-invalid\` when it is in a sibling. \`c4.fleet-project-invalid\` is
+  the fleet-scope class one step out — two SERVICES each declaring the same tag
+  locally, which no per-service project sees.
+  Then \`loam validate --service <svc>\` grades it — under
+  \`--all\`, per service: \`usecase.step-unbacked\` and \`usecase.step-contested\`
+  against model.likec4, \`usecase.requirement-unresolved\` against THIS service's
+  spec.md and arch.spec.md ids, and \`usecase.flow-invalid\` when a sibling file
+  breaks the project (model.likec4 is still graded alone). \`usecase.step-unlinked\`
+  never fires on a hop whose caller and provider resolve to the same service — a
+  service owes no operationId to itself — while a hop from such a flow into another
+  service's element (a stand-in the model declares for a sibling, with no
+  \`metadata { op }\`) still warns, exactly as on the fleet map. A \`#cap-\` tag on
+  such a flow is \`usecase.capability-unresolved\`: a capability is claimed on the
+  fleet map, never inside one service. A resolved service-local \`#req-\` keeps its
+  own grade and nothing else — it is not \`keptBy\`, not \`Covers:\`, and no feature
+  carries one yet.
 - A FEATURE brings a flow the way it brings every other axis: write it at
   \`features/<FEAT>/usecases/<name>.likec4\` — the same views-only document, in the
   feature's own directory — and \`loam archive\` copies it into
@@ -52,9 +89,14 @@ export const USECASE_VIEWS = `- Business use cases are \`dynamic view\`s, and \`
   that file — the merge is a whole-file copy, so edit the living one directly
   instead) and \`usecase.flow-invalid\` (loam could not read the flows against that
   post-merge map — most often a hop naming an element neither the living
-  landscape nor the delta declares). Do NOT put a \`dynamic view\` inside
+  landscape nor the delta declares; the merge preview stages no service model, so
+  a container an extending model declares is not among them either). Do NOT put a
+  \`dynamic view\` inside
   \`delta.likec4\`: that document re-declares the landscape's own identifiers and
   carries its own \`specification\` block, so it cannot be read beside the map, and
-  the archive refuses it by name.
+  the archive refuses it by name. A feature's \`delta.likec4\` keeps that shape
+  whatever shape the service models take — \`features/**\` stays excluded from the
+  root LikeC4 project, and the delta is pointed at alone
+  (\`npx likec4 start features/<FEAT>\`).
 `;
 //# sourceMappingURL=usecases.js.map

package/dist/core/agent/agents-md/map/usecases.js.map

@@ -1 +1 @@
-{"version":3,"file":"usecases.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/usecases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwC5B,CAAC","sourcesContent":["/**\n * The use-case axis of the command map — its own section module for\n * `./subsystem.ts`'s exact reason: command-map.ts sat against the file-line\n * limit and the agents-md package against the five-file cap, so a family added\n * to the `validate --all` cross-check documents itself one package down and is\n * concatenated after the map. The four `usecase.*` codes are what\n * test/codes-drift.test.ts finds here.\n *\n * They are LISTED and not glossed: their fix rows live in the /loam-check\n * table and `loam explain usecase.step-unbacked` prints them, so writing the\n * meanings out again here is the duplication ../../command-map.ts's header\n * describes. What stays is what `explain` does not say — how to opt a view in,\n * and that an untagged dynamic view is never graded at all.\n *\n * Same assembly contract as every section: ../../agents-md.ts concatenates with\n * NO join separator, so this string starts at the first character of its opening\n * line and ends with the newline that closes its last one.\n */\nexport const USECASE_VIEWS = `- Business use cases are \\`dynamic view\\`s, and \\`loam validate --all\\` grades the\n  ones that opt in. Write the flow in a file of its own —\n  \\`architecture/usecases/<name>.likec4\\`, a \\`views { }\\` block over the landscape's\n  elements, which loam reads as ONE LikeC4 project together with the map — and\n  tag the view \\`#cap-<capability>\\` to have it graded. The tag spells a declared\n  capability id with every \\`/\\` flattened to \\`-\\` (a LikeC4 tag name cannot carry a\n  slash), and it must be declared as a \\`tag\\` in the one \\`specification\\` block the\n  project has, since LikeC4 refuses an undeclared tag. EITHER reserved prefix\n  opts a view in — a view carrying only \\`#req-<requirement>\\` is graded too, and\n  earns \\`usecase.requirement-unresolved\\` for the \\`#cap-\\` tag it is missing\n  rather than silence. An UNTAGGED dynamic view is somebody's hand-drawn diagram\n  and is never graded — that opt-in is what lets a fleet full of existing\n  diagrams upgrade without turning red, and \\`loam validate\\`, \\`loam diff\\`,\n  \\`loam delta\\`, \\`loam status\\`, \\`loam context\\` and \\`loam list capabilities\\` all\n  read the same opt-in, so a flow one of them sees is a flow all of them see. On a tagged\n  view: \\`usecase.capability-unresolved\\`, \\`usecase.step-unbacked\\`,\n  \\`usecase.step-contested\\` and \\`usecase.step-unlinked\\`. The first is silent\n  while architecture/capabilities.yaml is absent or unreadable, like the rest of\n  the capability axis; the three step codes are about the model, and a return\n  hop written \\`a <- b\\` is attributed to the call it answers, so spell replies\n  that way rather than as fresh hops. Every message names the file the view was\n  written in, never the landscape.\n- A FEATURE brings a flow the way it brings every other axis: write it at\n  \\`features/<FEAT>/usecases/<name>.likec4\\` — the same views-only document, in the\n  feature's own directory — and \\`loam archive\\` copies it into\n  \\`architecture/usecases/\\` while \\`loam unarchive\\` takes it back. That is what lets\n  an analyst add a cross-service requirement and an architect answer it with the\n  flow that keeps it IN ONE CHANGE: the \\`#req-\\` tag resolves against this\n  feature's own \\`capabilities/<cap>/spec.md\\` delta as well as the living tree, and\n  \\`capability.uncovered\\` counts the flow as cover. The flow is graded against the\n  map the same merge would leave behind, so a hop may name a service this\n  feature's \\`delta.likec4\\` adds. Two refusals guard it, and \\`--approve\\` moves\n  neither: \\`usecase.flow-exists\\` (the living \\`architecture/usecases/\\` already has\n  that file — the merge is a whole-file copy, so edit the living one directly\n  instead) and \\`usecase.flow-invalid\\` (loam could not read the flows against that\n  post-merge map — most often a hop naming an element neither the living\n  landscape nor the delta declares). Do NOT put a \\`dynamic view\\` inside\n  \\`delta.likec4\\`: that document re-declares the landscape's own identifiers and\n  carries its own \\`specification\\` block, so it cannot be read beside the map, and\n  the archive refuses it by name.\n`;\n"]}
+{"version":3,"file":"usecases.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/usecases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkF5B,CAAC","sourcesContent":["/**\n * The use-case axis of the command map — its own section module for\n * `./subsystem.ts`'s exact reason: command-map.ts sat against the file-line\n * limit and the agents-md package against the five-file cap, so a family added\n * to the `validate --all` cross-check documents itself one package down and is\n * concatenated after the map. The four `usecase.*` codes are what\n * test/codes-drift.test.ts finds here.\n *\n * They are LISTED and not glossed: their fix rows live in the /loam-check\n * table and `loam explain usecase.step-unbacked` prints them, so writing the\n * meanings out again here is the duplication ../../command-map.ts's header\n * describes. What stays is what `explain` does not say — how to opt a view in,\n * and that an untagged dynamic view is never graded at all.\n *\n * Same assembly contract as every section: ../../agents-md.ts concatenates with\n * NO join separator, so this string starts at the first character of its opening\n * line and ends with the newline that closes its last one.\n */\nexport const USECASE_VIEWS = `- Business use cases are \\`dynamic view\\`s, and \\`loam validate --all\\` grades the\n  ones that opt in. Write the flow in a file of its own —\n  \\`architecture/usecases/<name>.likec4\\`, a \\`views { }\\` block over the landscape's\n  elements, which loam reads as ONE LikeC4 project together with the map — and\n  tag the view \\`#cap-<capability>\\` to have it graded. The tag spells a declared\n  capability id with every \\`/\\` flattened to \\`-\\` (a LikeC4 tag name cannot carry a\n  slash), and it must be declared as a \\`tag\\` in the one \\`specification\\` block the\n  \\`architecture/\\` project has, since LikeC4 refuses an undeclared tag. loam grades\n  the fleet map as THAT project and nothing else — the landscape plus its\n  siblings, never a service model — so a hop here names SERVICE elements: a step\n  naming a container that a service's extending model declares resolves in the\n  renderer's wider root project and is \\`landscape.invalid\\` for loam, which takes\n  the whole fleet map down. Container-level flows live beside the model that\n  declares them (below). EITHER reserved prefix\n  opts a view in — a view carrying only \\`#req-<requirement>\\` is graded too, and\n  earns \\`usecase.requirement-unresolved\\` for the \\`#cap-\\` tag it is missing\n  rather than silence. An UNTAGGED dynamic view is somebody's hand-drawn diagram\n  and is never graded — that opt-in is what lets a fleet full of existing\n  diagrams upgrade without turning red, and \\`loam validate\\`, \\`loam diff\\`,\n  \\`loam delta\\`, \\`loam status\\`, \\`loam context\\` and \\`loam list capabilities\\` all\n  read the same opt-in, so a flow one of them sees is a flow all of them see. On a tagged\n  view: \\`usecase.capability-unresolved\\`, \\`usecase.step-unbacked\\`,\n  \\`usecase.step-contested\\` and \\`usecase.step-unlinked\\`. The first is silent\n  while architecture/capabilities.yaml is absent or unreadable, like the rest of\n  the capability axis; the three step codes are about the model, and a return\n  hop written \\`a <- b\\` is attributed to the call it answers, so spell replies\n  that way rather than as fresh hops. Every message names the file the view was\n  written in, never the landscape.\n- A flow behind ONE service's own requirement — the hop sequence over its\n  containers that an arch.spec.md \\`Covers:\\` names — lives in that service's own\n  LikeC4 project: any \\`.likec4\\` beside \\`services/<…>/<svc>/model.likec4\\`\n  (\\`usecases/<name>.likec4\\` by convention, or \\`views.likec4\\`), or a \\`dynamic view\\`\n  inside model.likec4 itself; loam reads exactly what the renderer's per-service\n  project reads. Never \\`architecture/usecases/\\`, which cannot resolve a container\n  and turns the whole fleet \\`landscape.invalid\\`. Tag it \\`#req-<Requirement-ID>\\`\n  (the id flattened as above). The tag has to be DECLARED where that project can\n  see it: in model.likec4's own \\`specification\\` block when the model declares one\n  and therefore stands alone; in \\`architecture/landscape.likec4\\`'s block when the\n  model EXTENDS the map, or in a tags-only \\`specification { tag req-… }\\` beside\n  the \\`extend\\`, which is legal and lands the tag in the project's specification.\n  Declaring it in BOTH is a duplicate, and the code is the one that lands where\n  the second declaration's FILE is: \\`c4.invalid\\` (an error, and the model's\n  grading is suspended behind it) when the tags-only block is in model.likec4,\n  \\`usecase.flow-invalid\\` when it is in a sibling. \\`c4.fleet-project-invalid\\` is\n  the fleet-scope class one step out — two SERVICES each declaring the same tag\n  locally, which no per-service project sees.\n  Then \\`loam validate --service <svc>\\` grades it — under\n  \\`--all\\`, per service: \\`usecase.step-unbacked\\` and \\`usecase.step-contested\\`\n  against model.likec4, \\`usecase.requirement-unresolved\\` against THIS service's\n  spec.md and arch.spec.md ids, and \\`usecase.flow-invalid\\` when a sibling file\n  breaks the project (model.likec4 is still graded alone). \\`usecase.step-unlinked\\`\n  never fires on a hop whose caller and provider resolve to the same service — a\n  service owes no operationId to itself — while a hop from such a flow into another\n  service's element (a stand-in the model declares for a sibling, with no\n  \\`metadata { op }\\`) still warns, exactly as on the fleet map. A \\`#cap-\\` tag on\n  such a flow is \\`usecase.capability-unresolved\\`: a capability is claimed on the\n  fleet map, never inside one service. A resolved service-local \\`#req-\\` keeps its\n  own grade and nothing else — it is not \\`keptBy\\`, not \\`Covers:\\`, and no feature\n  carries one yet.\n- A FEATURE brings a flow the way it brings every other axis: write it at\n  \\`features/<FEAT>/usecases/<name>.likec4\\` — the same views-only document, in the\n  feature's own directory — and \\`loam archive\\` copies it into\n  \\`architecture/usecases/\\` while \\`loam unarchive\\` takes it back. That is what lets\n  an analyst add a cross-service requirement and an architect answer it with the\n  flow that keeps it IN ONE CHANGE: the \\`#req-\\` tag resolves against this\n  feature's own \\`capabilities/<cap>/spec.md\\` delta as well as the living tree, and\n  \\`capability.uncovered\\` counts the flow as cover. The flow is graded against the\n  map the same merge would leave behind, so a hop may name a service this\n  feature's \\`delta.likec4\\` adds. Two refusals guard it, and \\`--approve\\` moves\n  neither: \\`usecase.flow-exists\\` (the living \\`architecture/usecases/\\` already has\n  that file — the merge is a whole-file copy, so edit the living one directly\n  instead) and \\`usecase.flow-invalid\\` (loam could not read the flows against that\n  post-merge map — most often a hop naming an element neither the living\n  landscape nor the delta declares; the merge preview stages no service model, so\n  a container an extending model declares is not among them either). Do NOT put a\n  \\`dynamic view\\` inside\n  \\`delta.likec4\\`: that document re-declares the landscape's own identifiers and\n  carries its own \\`specification\\` block, so it cannot be read beside the map, and\n  the archive refuses it by name. A feature's \\`delta.likec4\\` keeps that shape\n  whatever shape the service models take — \\`features/**\\` stays excluded from the\n  root LikeC4 project, and the delta is pointed at alone\n  (\\`npx likec4 start features/<FEAT>\\`).\n`;\n"]}

package/dist/core/agent/agents-md/refusals.js

@@ -227,9 +227,11 @@ follows is the other half — which command raises which:
   workspace file, which loam never silently overwrites — pass \`--out\` or
   \`--force\`) and \`invalid-option\`.
 - \`loam seed --from fleet.yaml\`: \`seed-file-invalid\`, \`seed-duplicate-service\`,
-  \`seed-unknown-subsystem\`, \`seed-landscape-edited\`, and \`unknown-service\` for a
-  call endpoint nothing declares. An existing service directory is never moved,
-  and nothing is ever deleted.
+  \`seed-unknown-subsystem\`, \`seed-landscape-edited\`, \`already-exists\` when a
+  generated views file in \`architecture/\` was written by somebody rather than by
+  loam (no \`// generated by loam\` first line — seed writes nothing at all in that
+  case), and \`unknown-service\` for a call endpoint nothing declares. An existing
+  service directory is never moved, and nothing is ever deleted.
 - \`internal\` — an unexpected throw, the one code with no stable meaning.
 
 \`--all\` reports a target per service, a target per feature in flight, and one target

package/dist/core/agent/agents-md/refusals.js.map

@@ -1 +1 @@
-{"version":3,"file":"refusals.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/refusals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqNvB,CAAC;AAEF;;2DAE2D","sourcesContent":["/**\n * What loam REFUSES: the OpenSpec migration surface, the containment and\n * unreadable-file findings, and the error-envelope codes. What happens to a\n * SHIPPED change — the archive gate, unarchive, and dropping a feature — is\n * the continuation section in ./shipped/archive-gate.ts, split there because\n * the two subjects had grown past one file's ceiling.\n *\n * Codes here are LISTED by the command that raises them, not glossed; the\n * meanings come from `loam explain <code>`, out of the running binary. See\n * ./command-map.ts's header for why the duplicated gloss left.\n *\n * THE ONE EXCEPTION IS THE FIRST BULLET. `loam explain` cannot answer\n * `openspec.*` or `mapping.*` — those commands grade a repository still in\n * another tool's shape, before it has a governed loop to look a code up from,\n * and the catalogue leaves them unanswered for that reason. Pointing this\n * section's reader at an explanation that does not exist is the exact failure\n * the pointer exists to prevent, so the migration notes stay written out here\n * until the catalogue reaches them. test/agent-contract.test.ts enforces the\n * boundary from the other side: every OTHER code backticked in AGENTS_MD must\n * resolve, so a family can never quietly lose its gloss and its explanation\n * at once.\n *\n * One section of the AGENTS.md template. ../agents-md.ts assembles the\n * document by PLAIN CONCATENATION — no join separator — so every section\n * starts at the first character of its opening line and ends with the newline\n * that closes its last one. Keep that shape when editing, or two sections glue\n * onto one line in every docs repo loam scaffolds from now on.\n */\nexport const REFUSALS = `- \\`loam audit-openspec <root>\\` is the read-only OpenSpec inventory; an explicit\n  \\`--write-mapping\\` writes a non-overwriting, digest-bound decision skeleton\n  outside the source tree. \\`loam migrate-openspec <root> --map <file>\\` validates\n  that mapping and stays dry-run unless both \\`--apply\\` and an empty \\`--target\\`\n  are supplied. Living/active shape diagnostics are \\`openspec.workspace-empty\\`\n  (the audited root holds no living spec and no active change, so there is\n  nothing to migrate and no verdict over it can be \\`ready\\`),\n  \\`openspec.specs-missing\\`,\n  \\`openspec.config-invalid\\`, \\`openspec.external-store-pointer\\`,\n  \\`openspec.living-empty\\`, \\`openspec.living-requirements-outside-section\\`,\n  \\`openspec.living-delta-section\\`, \\`openspec.nonstandard-living-spec\\` (markdown\n  under \\`specs/\\` named neither spec.md nor design.md, so no capability reads\n  it), \\`openspec.change-metadata-invalid\\`,\n  \\`openspec.change-schema-unresolved\\`, \\`openspec.skip-specs-with-specs\\`,\n  \\`openspec.change-no-specs\\`, \\`openspec.change-empty\\`,\n  \\`openspec.change-without-delta-sections\\`,\n  \\`openspec.change-requirements-outside-delta-sections\\`,\n  \\`openspec.change-quoted-requirements\\` (requirements under a \\`## Requirements\\`\n  heading INSIDE a change delta — the shape OpenSpec's own living-spec template\n  mandates, and one that stages nothing, so loam refuses it rather than counting\n  requirements it cannot route),\n  \\`openspec.hidden-change-directory\\` (a dot-prefixed directory under\n  \\`changes/\\` is not enumerated as a change, so nothing under it migrates —\n  rename it or move it out; under \\`changes/archive/\\` the same code is an archive\n  diagnostic and does not gate, because frozen history never blocks),\n  \\`openspec.nonstandard-change-spec\\`, \\`openspec.renamed-malformed\\`,\n  \\`openspec.requirement-id-invalid\\`, \\`openspec.requirement-id-repeated\\`,\n  \\`openspec.requirement-id-duplicate\\` (a stable \\`Requirement-ID\\` that is\n  malformed, declared twice, or shared by two requirements — identity is never\n  inferred from an invalid declaration, so the RENAMED chain cannot be followed\n  through it), \\`openspec.symlink-unsupported\\`, and \\`openspec.non-utf8-artifact\\`;\n  the same shapes in frozen history are non-blocking archive diagnostics.\n  Mapping refuses stale or incomplete decisions under \\`mapping.source-missing\\`,\n  \\`mapping.source-root-mismatch\\`, \\`mapping.source-digest-mismatch\\`,\n  \\`mapping.unknown-capability\\`, \\`mapping.unknown-requirement\\`,\n  \\`mapping.requirement-allocation-missing\\`,\n  \\`mapping.requirement-service-unknown\\`, \\`mapping.service-allocation-empty\\`,\n  \\`mapping.unknown-change\\`, \\`mapping.change-title-missing\\`,\n  \\`mapping.feature-id-invalid\\`, \\`mapping.feature-id-duplicate\\`,\n  \\`mapping.unknown-rename\\`, \\`mapping.invalid-requirement-id\\`,\n  \\`mapping.rename-source-missing\\`, \\`mapping.rename-source-ambiguous\\`,\n  \\`mapping.rename-source-id-invalid\\`, \\`mapping.rename-target-conflict\\`,\n  \\`mapping.rename-existing-id-conflict\\`, \\`mapping.rename-id-conflict\\`,\n  \\`mapping.rename-double-source\\`, \\`mapping.rename-double-target\\`,\n  \\`mapping.rename-chain\\`,\n  \\`mapping.unknown-artifact\\`, and \\`mapping.invalid-artifact-disposition\\`.\n- Repository containment failures are explicit: \\`sources.path-outside\\` rejects a\n  provenance source outside the service repo and \\`gherkin.path-outside\\` rejects a\n  generated-suite target outside it. Federated verify recording refuses under\n  \\`service-mismatch\\`, \\`unknown-service\\` or \\`repository-unavailable\\` when the\n  selected service, fleet identity and repository commit cannot be bound safely,\n  and under \\`record-federated\\` when the legacy all-at-once form would erase other\n  repositories' attestations. \\`loam gherkin --service <id>\\` and\n  \\`loam vouch --service <id>\\` answer that same wrong-repo pair\n  (\\`repository-unavailable\\`, \\`service-mismatch\\`) for the same reason. Neither is\n  \\`invalid-option\\`: the flags were right and the directory was wrong, so the fix\n  is to re-run in the service's own checkout, never to re-read the invocation.\n- A file loam cannot read is reported, never skipped: \\`service.unreadable\\` and\n  \\`feature.unreadable\\` (both errors) name the path and say that nothing about\n  that target was checked while the rest of the fleet still was. The whole docs\n  repo being unreachable is a refusal instead: \\`docs-missing\\` or\n  \\`services-missing\\`.\n- Both modes read frontmatter (\\`frontmatter.missing\\`, \\`frontmatter.malformed\\`,\n  \\`frontmatter.field-mismatch\\`,\n  \\`frontmatter.status-unknown\\`, \\`frontmatter.field-missing\\`); a service's spec.md —\n  and its arch.spec.md, same conventions — additionally carries the sources chain\n  (\\`sources.absent\\`, \\`sources.path-missing\\`, \\`sources.empty\\`, \\`sources.skipped\\`,\n  \\`sources.unvouched\\`, \\`sources.stale\\`) plus the two doc-side checks,\n  \\`content.stale\\` and \\`sources.sampled-vouch\\`, which need no service repo and so\n  fire from the docs repo too.\n- A service target run from the service's own repository also re-checks the\n  \\`evidence_pins\\` its federated verification records carry, against the working\n  tree: \\`evidence.checked\\` and \\`evidence.unpinned\\` are the confirmations,\n  \\`evidence.unresolved\\`, \\`evidence.moved\\`, \\`evidence.line-changed\\`,\n  \\`evidence.token-missing\\` and \\`evidence.record-unreadable\\` the warnings.\n  Demote-only, by doctrine: a warn here is a reading priority for a reviewer,\n  never a verdict change — no pin state moves \\`attested\\` or \\`verified\\` in\n  either direction. From the docs repo the family is silent;\n  \\`sources.unverifiable-from-here\\` already names that blind spot.\n- \\`loam archive\\` alone reports the breaches only the merge computation can see:\n  \\`living.requirement-outside-requirements\\`, \\`openapi.op-modified\\`,\n  \\`openapi.path-item-modified\\`, \\`openapi.component-modified\\`,\n  \\`openapi.ref-unresolved\\`, \\`openapi.remove-marker-path-level\\`, the event\n  axis's own trio \\`asyncapi.message-modified\\` / \\`asyncapi.channel-modified\\` /\n  \\`asyncapi.operation-modified\\`, \\`asyncapi.ref-unresolved\\`,\n  \\`asyncapi.remove-marker-inline\\` and \\`service.no-model\\`. Two of those are\n  graded at validate time as well and are STRICTER here —\n  \\`openapi.ref-unresolved\\` and \\`asyncapi.ref-unresolved\\` are warnings there and\n  errors here, because the merged document is what would carry the dangling\n  reference — so \\`loam explain\\` on either prints both contexts.\n\n\\`loam validate <target>\\` is the positional spelling of the first two: a feature id\nor a service id, tried in that order, so the feature wins when one name could be\nboth and \\`--service\\`/\\`--feature\\` force the reading. When the name really is both,\nthe run says so — \\`target.ambiguous\\` (warn) names the reading it took and the\nflag that forces the other, and \\`--json\\` carries \\`resolvedKind\\` — because a\nsilent precedence rule is a report about a target nobody asked for. The\npositional together with \\`--all\\`, \\`--service\\` or \\`--feature\\` is refused\n(\\`invalid-option\\`).\n\nTwo rendering levers change nothing else: \\`loam validate --errors-only\\` drops\nthe confirmations from the TEXT view (the \\`--json\\` payload is byte-identical),\nand \\`loam list --needs-work\\` narrows the service list to the ones with\nsomething missing — the adoption worklist. \\`loam list --needs-work --review-order\\`\norders that worklist by fan-in — the services the most other services depend on\nfirst: drawn call edges into each, plus event subscriptions (a drawn \\`consumes\\`\nedge, or a living \\`Consumes:\\` line naming a message it sends) — a count, never\na priority judgement — and its \\`--json\\` rows then additionally carry \\`fanIn\\`\nand \\`reviewRank\\`; without \\`--needs-work\\` the flag is refused (\\`invalid-option\\`).\n\nTwo campaign flags slice that same services section and change nothing about\nany row. \\`loam list --subsystem <name>\\` limits the listing to the services\nfiled under one subsystem, at any depth: \\`services[]\\`, the \\`maturity\\` rollup\nand \\`subsystems[]\\` reflect the slice (\\`unfiledServices\\` is omitted — it is a\nfleet-root fact), while every per-row fact — \\`fanIn\\`, \\`apiExpected\\`,\n\\`missing\\` — is still computed fleet-wide, so filtering changes which rows\nappear, never what a row says; with \\`--review-order\\` the filter applies first\nand \\`reviewRank\\` stays contiguous within the filtered worklist. The name\n\\`unfiled\\` selects the services filed under no subsystem while nothing in the\ntree claims that name (a real subsystem or service spelled \\`unfiled\\` wins).\nAn unknown name refuses \\`unknown-target\\` with close-name hints; a service\nname refuses \\`invalid-option\\`. \\`loam list --owners <path>\\` joins each listed\nservice's directory to the owning teams in the named CODEOWNERS file —\ndirectory-pattern rules only, last match wins, an owner-less directory rule\nCLEARING ownership for what it matches exactly as the forge reads it; a\nrecognised rule outside that subset (any other wildcard use, \\`*\\` included)\nis reported under \\`skippedRules\\`, never guessed at — and \\`--json\\` gains the additive \\`owners\\`\nkey (\\`path\\`, \\`teams[]\\` with each team's services in the listing's own\nfiltered-and-ordered row order, \\`unowned[]\\` listing the rows no rule matched,\n\\`skippedRules[]\\`), so the per-team arrays are the per-team campaign\nworklists. A CODEOWNERS path that cannot be read, or a line that cannot be\nparsed as \\`pattern owner…\\`, refuses \\`owners-unreadable\\` naming the path and\nline — fail-closed, exactly as \\`answers-unreadable\\` treats the other\nuser-named file. Either flag with the \\`features\\` or \\`capabilities\\` section\nis refused (\\`invalid-option\\`).\n\n\\`--strict\\` (every targeting mode, \\`--all\\` included) exits 1 when any error\nor warning exists — \\`ok\\`-severity findings are confirmations and never trip\nit. It changes the exit code and nothing else:\n\\`valid\\` still means \"no errors\", and the \\`--json\\` payload stays byte-for-byte\nwhat it was. The stricter grade is a per-invocation lever, visible in the CI\npipeline that passes the flag — deliberately not a per-repo profile.\n\n\\`loam delta <FEAT> --json\\` exits 1 when either authored document behind the brief\nfailed to parse — \\`architecture.errors\\` non-empty, or \\`openapi.unreadable\\` true —\nwith \\`ok: true\\` and the full payload intact: the empty C4 slice means the delta\ndid not parse, and an empty \\`api\\` beside \\`openapi.unreadable\\` means the contract\ndelta did not parse, neither of them \"this feature changes nothing there\". Branch\non the exit code before consuming either slice as a task brief.\n\nFindings with severity \\`ok\\` are confirmations, not work: \\`c4.valid\\`, \\`delta.valid\\`,\n\\`requirements.covered\\`, \\`api.covered\\`, \\`spine.resolved\\`, \\`event.covered\\`, \\`coherence.ok\\`,\n\\`landscape.matched\\`, \\`archedge.covered\\`, \\`sources.resolved\\`, \\`sources.current\\`,\n\\`sources.walked\\`, \\`gherkin.current\\`.\n\nA finding's \\`subject\\` names the service it is about. The envelope separates \\`ok\\` (the\ncommand ran) from \\`valid\\` (the docs pass). A refusal is \\`ok: false\\` with a stable\n\\`error.code\\`, and \\`loam explain <code>\\` has the meaning of every one of them. What\nfollows is the other half — which command raises which:\n\n- Before any command can read anything: \\`no-config\\`, \\`config-invalid\\`,\n  \\`docs-missing\\`, \\`services-missing\\`, \\`unknown-target\\`, \\`invalid-option\\`.\n  \\`invalid-option\\` covers flags that contradict each other AND a value that\n  cannot be right — a \\`loam list\\` section that is not services or features, or a\n  service id that is not a legal \\`services/<id>/\\` directory name.\n- Every JOURNALED writer — \\`archive\\`, \\`unarchive\\`, \\`rebase\\`, \\`vouch\\`, \\`new\\`,\n  \\`gherkin\\`, \\`seed\\`, \\`subsystem\\` and \\`verify --record\\` — shares one transaction\n  and therefore one set of refusals: \\`docs-busy\\`, \\`commit-interrupted\\`,\n  \\`merge-failed\\` and \\`rollback-incomplete\\`. Learn them once and you have read\n  them for all nine. \\`loam doctor\\` names the interrupted state as\n  \\`doctor.commit-interrupted\\` and \\`loam validate\\` leads every mode with\n  \\`docs.commit-interrupted\\` while the journal sits there; every journaled writer\n  recovers a finished predecessor's journal on its next run and reports it as\n  \\`recovered\\` in \\`--json\\`.\n- \\`loam new\\`: \\`already-exists\\` — also the answer when a concurrent \\`new\\` for the\n  same id wins the race.\n- \\`loam vouch\\`: \\`sources-absent\\`, \\`sources-path-missing\\`, \\`vouch-raced\\`, and the\n  wrong-repo pair \\`repository-unavailable\\` / \\`service-mismatch\\`, because\n  \\`sources\\` resolve against the service's own checkout and from anywhere else\n  those paths are somebody else's.\n- \\`loam archive\\`: \\`not-coherent\\`, \\`living-outside-requirements\\`,\n  \\`archive-exists\\` — see the archive gate below.\n- \\`loam unarchive\\`: \\`feature-active\\`, \\`snapshot-missing\\`, \\`snapshot-stale\\`,\n  \\`snapshot-corrupt\\`, \\`restore-failed\\` — see \"Taking an archive back\".\n- \\`loam gherkin\\`: \\`gherkin-conflict\\`, plus the same wrong-repo pair, refused\n  before anything is written because the generated files land in the repo loam\n  is standing in.\n- \\`loam subsystem\\`: \\`subsystem-not-empty\\`, \\`move-uncommitted\\`, \\`move-failed\\`,\n  and \\`unknown-target\\` / \\`already-exists\\` / \\`invalid-option\\` for names that\n  resolve to nothing, collide in the flat namespace, or break the grammar.\n  \\`move-failed\\` is deliberately distinct from \\`merge-failed\\`: the move's own\n  transaction rolled back cleanly, nothing changed, and re-running can work.\n- \\`loam verify --record\\` / \\`--results\\` / \\`--contract-results\\`:\n  \\`answers-unreadable\\`, \\`answers-mismatch\\`, \\`answers-unevidenced\\`,\n  \\`record-federated\\`, \\`record-unreadable\\` and \\`record-raced\\`. Two records for\n  different services land in either order — the later one waits, then merges,\n  and both attestations survive.\n- \\`loam open\\`: \\`no-members\\`, \\`binding-duplicate\\`, \\`already-exists\\` (the\n  workspace file, which loam never silently overwrites — pass \\`--out\\` or\n  \\`--force\\`) and \\`invalid-option\\`.\n- \\`loam seed --from fleet.yaml\\`: \\`seed-file-invalid\\`, \\`seed-duplicate-service\\`,\n  \\`seed-unknown-subsystem\\`, \\`seed-landscape-edited\\`, and \\`unknown-service\\` for a\n  call endpoint nothing declares. An existing service directory is never moved,\n  and nothing is ever deleted.\n- \\`internal\\` — an unexpected throw, the one code with no stable meaning.\n\n\\`--all\\` reports a target per service, a target per feature in flight, and one target\nof kind \\`landscape\\` for the fleet-level checks that belong to no single service.\n\nThree different words for three different questions, and no command conflates them:\n\\`ok\\` — the command ran; \\`valid\\` — the documents pass (\\`validate\\`); \\`verified\\` —\nsomebody says the code was built and showed evidence (\\`verify\\`). A feature can be\nvalid and unverified, or verified and incoherent. Read the one you meant.\n`;\n\n/* The archive gate, unarchive, and dropping a feature continue in\n * ./shipped/archive-gate.ts — one document section split at its own subject\n * seam, concatenated after this one by ../agents-md.ts. */\n"]}
+{"version":3,"file":"refusals.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/refusals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuNvB,CAAC;AAEF;;2DAE2D","sourcesContent":["/**\n * What loam REFUSES: the OpenSpec migration surface, the containment and\n * unreadable-file findings, and the error-envelope codes. What happens to a\n * SHIPPED change — the archive gate, unarchive, and dropping a feature — is\n * the continuation section in ./shipped/archive-gate.ts, split there because\n * the two subjects had grown past one file's ceiling.\n *\n * Codes here are LISTED by the command that raises them, not glossed; the\n * meanings come from `loam explain <code>`, out of the running binary. See\n * ./command-map.ts's header for why the duplicated gloss left.\n *\n * THE ONE EXCEPTION IS THE FIRST BULLET. `loam explain` cannot answer\n * `openspec.*` or `mapping.*` — those commands grade a repository still in\n * another tool's shape, before it has a governed loop to look a code up from,\n * and the catalogue leaves them unanswered for that reason. Pointing this\n * section's reader at an explanation that does not exist is the exact failure\n * the pointer exists to prevent, so the migration notes stay written out here\n * until the catalogue reaches them. test/agent-contract.test.ts enforces the\n * boundary from the other side: every OTHER code backticked in AGENTS_MD must\n * resolve, so a family can never quietly lose its gloss and its explanation\n * at once.\n *\n * One section of the AGENTS.md template. ../agents-md.ts assembles the\n * document by PLAIN CONCATENATION — no join separator — so every section\n * starts at the first character of its opening line and ends with the newline\n * that closes its last one. Keep that shape when editing, or two sections glue\n * onto one line in every docs repo loam scaffolds from now on.\n */\nexport const REFUSALS = `- \\`loam audit-openspec <root>\\` is the read-only OpenSpec inventory; an explicit\n  \\`--write-mapping\\` writes a non-overwriting, digest-bound decision skeleton\n  outside the source tree. \\`loam migrate-openspec <root> --map <file>\\` validates\n  that mapping and stays dry-run unless both \\`--apply\\` and an empty \\`--target\\`\n  are supplied. Living/active shape diagnostics are \\`openspec.workspace-empty\\`\n  (the audited root holds no living spec and no active change, so there is\n  nothing to migrate and no verdict over it can be \\`ready\\`),\n  \\`openspec.specs-missing\\`,\n  \\`openspec.config-invalid\\`, \\`openspec.external-store-pointer\\`,\n  \\`openspec.living-empty\\`, \\`openspec.living-requirements-outside-section\\`,\n  \\`openspec.living-delta-section\\`, \\`openspec.nonstandard-living-spec\\` (markdown\n  under \\`specs/\\` named neither spec.md nor design.md, so no capability reads\n  it), \\`openspec.change-metadata-invalid\\`,\n  \\`openspec.change-schema-unresolved\\`, \\`openspec.skip-specs-with-specs\\`,\n  \\`openspec.change-no-specs\\`, \\`openspec.change-empty\\`,\n  \\`openspec.change-without-delta-sections\\`,\n  \\`openspec.change-requirements-outside-delta-sections\\`,\n  \\`openspec.change-quoted-requirements\\` (requirements under a \\`## Requirements\\`\n  heading INSIDE a change delta — the shape OpenSpec's own living-spec template\n  mandates, and one that stages nothing, so loam refuses it rather than counting\n  requirements it cannot route),\n  \\`openspec.hidden-change-directory\\` (a dot-prefixed directory under\n  \\`changes/\\` is not enumerated as a change, so nothing under it migrates —\n  rename it or move it out; under \\`changes/archive/\\` the same code is an archive\n  diagnostic and does not gate, because frozen history never blocks),\n  \\`openspec.nonstandard-change-spec\\`, \\`openspec.renamed-malformed\\`,\n  \\`openspec.requirement-id-invalid\\`, \\`openspec.requirement-id-repeated\\`,\n  \\`openspec.requirement-id-duplicate\\` (a stable \\`Requirement-ID\\` that is\n  malformed, declared twice, or shared by two requirements — identity is never\n  inferred from an invalid declaration, so the RENAMED chain cannot be followed\n  through it), \\`openspec.symlink-unsupported\\`, and \\`openspec.non-utf8-artifact\\`;\n  the same shapes in frozen history are non-blocking archive diagnostics.\n  Mapping refuses stale or incomplete decisions under \\`mapping.source-missing\\`,\n  \\`mapping.source-root-mismatch\\`, \\`mapping.source-digest-mismatch\\`,\n  \\`mapping.unknown-capability\\`, \\`mapping.unknown-requirement\\`,\n  \\`mapping.requirement-allocation-missing\\`,\n  \\`mapping.requirement-service-unknown\\`, \\`mapping.service-allocation-empty\\`,\n  \\`mapping.unknown-change\\`, \\`mapping.change-title-missing\\`,\n  \\`mapping.feature-id-invalid\\`, \\`mapping.feature-id-duplicate\\`,\n  \\`mapping.unknown-rename\\`, \\`mapping.invalid-requirement-id\\`,\n  \\`mapping.rename-source-missing\\`, \\`mapping.rename-source-ambiguous\\`,\n  \\`mapping.rename-source-id-invalid\\`, \\`mapping.rename-target-conflict\\`,\n  \\`mapping.rename-existing-id-conflict\\`, \\`mapping.rename-id-conflict\\`,\n  \\`mapping.rename-double-source\\`, \\`mapping.rename-double-target\\`,\n  \\`mapping.rename-chain\\`,\n  \\`mapping.unknown-artifact\\`, and \\`mapping.invalid-artifact-disposition\\`.\n- Repository containment failures are explicit: \\`sources.path-outside\\` rejects a\n  provenance source outside the service repo and \\`gherkin.path-outside\\` rejects a\n  generated-suite target outside it. Federated verify recording refuses under\n  \\`service-mismatch\\`, \\`unknown-service\\` or \\`repository-unavailable\\` when the\n  selected service, fleet identity and repository commit cannot be bound safely,\n  and under \\`record-federated\\` when the legacy all-at-once form would erase other\n  repositories' attestations. \\`loam gherkin --service <id>\\` and\n  \\`loam vouch --service <id>\\` answer that same wrong-repo pair\n  (\\`repository-unavailable\\`, \\`service-mismatch\\`) for the same reason. Neither is\n  \\`invalid-option\\`: the flags were right and the directory was wrong, so the fix\n  is to re-run in the service's own checkout, never to re-read the invocation.\n- A file loam cannot read is reported, never skipped: \\`service.unreadable\\` and\n  \\`feature.unreadable\\` (both errors) name the path and say that nothing about\n  that target was checked while the rest of the fleet still was. The whole docs\n  repo being unreachable is a refusal instead: \\`docs-missing\\` or\n  \\`services-missing\\`.\n- Both modes read frontmatter (\\`frontmatter.missing\\`, \\`frontmatter.malformed\\`,\n  \\`frontmatter.field-mismatch\\`,\n  \\`frontmatter.status-unknown\\`, \\`frontmatter.field-missing\\`); a service's spec.md —\n  and its arch.spec.md, same conventions — additionally carries the sources chain\n  (\\`sources.absent\\`, \\`sources.path-missing\\`, \\`sources.empty\\`, \\`sources.skipped\\`,\n  \\`sources.unvouched\\`, \\`sources.stale\\`) plus the two doc-side checks,\n  \\`content.stale\\` and \\`sources.sampled-vouch\\`, which need no service repo and so\n  fire from the docs repo too.\n- A service target run from the service's own repository also re-checks the\n  \\`evidence_pins\\` its federated verification records carry, against the working\n  tree: \\`evidence.checked\\` and \\`evidence.unpinned\\` are the confirmations,\n  \\`evidence.unresolved\\`, \\`evidence.moved\\`, \\`evidence.line-changed\\`,\n  \\`evidence.token-missing\\` and \\`evidence.record-unreadable\\` the warnings.\n  Demote-only, by doctrine: a warn here is a reading priority for a reviewer,\n  never a verdict change — no pin state moves \\`attested\\` or \\`verified\\` in\n  either direction. From the docs repo the family is silent;\n  \\`sources.unverifiable-from-here\\` already names that blind spot.\n- \\`loam archive\\` alone reports the breaches only the merge computation can see:\n  \\`living.requirement-outside-requirements\\`, \\`openapi.op-modified\\`,\n  \\`openapi.path-item-modified\\`, \\`openapi.component-modified\\`,\n  \\`openapi.ref-unresolved\\`, \\`openapi.remove-marker-path-level\\`, the event\n  axis's own trio \\`asyncapi.message-modified\\` / \\`asyncapi.channel-modified\\` /\n  \\`asyncapi.operation-modified\\`, \\`asyncapi.ref-unresolved\\`,\n  \\`asyncapi.remove-marker-inline\\` and \\`service.no-model\\`. Two of those are\n  graded at validate time as well and are STRICTER here —\n  \\`openapi.ref-unresolved\\` and \\`asyncapi.ref-unresolved\\` are warnings there and\n  errors here, because the merged document is what would carry the dangling\n  reference — so \\`loam explain\\` on either prints both contexts.\n\n\\`loam validate <target>\\` is the positional spelling of the first two: a feature id\nor a service id, tried in that order, so the feature wins when one name could be\nboth and \\`--service\\`/\\`--feature\\` force the reading. When the name really is both,\nthe run says so — \\`target.ambiguous\\` (warn) names the reading it took and the\nflag that forces the other, and \\`--json\\` carries \\`resolvedKind\\` — because a\nsilent precedence rule is a report about a target nobody asked for. The\npositional together with \\`--all\\`, \\`--service\\` or \\`--feature\\` is refused\n(\\`invalid-option\\`).\n\nTwo rendering levers change nothing else: \\`loam validate --errors-only\\` drops\nthe confirmations from the TEXT view (the \\`--json\\` payload is byte-identical),\nand \\`loam list --needs-work\\` narrows the service list to the ones with\nsomething missing — the adoption worklist. \\`loam list --needs-work --review-order\\`\norders that worklist by fan-in — the services the most other services depend on\nfirst: drawn call edges into each, plus event subscriptions (a drawn \\`consumes\\`\nedge, or a living \\`Consumes:\\` line naming a message it sends) — a count, never\na priority judgement — and its \\`--json\\` rows then additionally carry \\`fanIn\\`\nand \\`reviewRank\\`; without \\`--needs-work\\` the flag is refused (\\`invalid-option\\`).\n\nTwo campaign flags slice that same services section and change nothing about\nany row. \\`loam list --subsystem <name>\\` limits the listing to the services\nfiled under one subsystem, at any depth: \\`services[]\\`, the \\`maturity\\` rollup\nand \\`subsystems[]\\` reflect the slice (\\`unfiledServices\\` is omitted — it is a\nfleet-root fact), while every per-row fact — \\`fanIn\\`, \\`apiExpected\\`,\n\\`missing\\` — is still computed fleet-wide, so filtering changes which rows\nappear, never what a row says; with \\`--review-order\\` the filter applies first\nand \\`reviewRank\\` stays contiguous within the filtered worklist. The name\n\\`unfiled\\` selects the services filed under no subsystem while nothing in the\ntree claims that name (a real subsystem or service spelled \\`unfiled\\` wins).\nAn unknown name refuses \\`unknown-target\\` with close-name hints; a service\nname refuses \\`invalid-option\\`. \\`loam list --owners <path>\\` joins each listed\nservice's directory to the owning teams in the named CODEOWNERS file —\ndirectory-pattern rules only, last match wins, an owner-less directory rule\nCLEARING ownership for what it matches exactly as the forge reads it; a\nrecognised rule outside that subset (any other wildcard use, \\`*\\` included)\nis reported under \\`skippedRules\\`, never guessed at — and \\`--json\\` gains the additive \\`owners\\`\nkey (\\`path\\`, \\`teams[]\\` with each team's services in the listing's own\nfiltered-and-ordered row order, \\`unowned[]\\` listing the rows no rule matched,\n\\`skippedRules[]\\`), so the per-team arrays are the per-team campaign\nworklists. A CODEOWNERS path that cannot be read, or a line that cannot be\nparsed as \\`pattern owner…\\`, refuses \\`owners-unreadable\\` naming the path and\nline — fail-closed, exactly as \\`answers-unreadable\\` treats the other\nuser-named file. Either flag with the \\`features\\` or \\`capabilities\\` section\nis refused (\\`invalid-option\\`).\n\n\\`--strict\\` (every targeting mode, \\`--all\\` included) exits 1 when any error\nor warning exists — \\`ok\\`-severity findings are confirmations and never trip\nit. It changes the exit code and nothing else:\n\\`valid\\` still means \"no errors\", and the \\`--json\\` payload stays byte-for-byte\nwhat it was. The stricter grade is a per-invocation lever, visible in the CI\npipeline that passes the flag — deliberately not a per-repo profile.\n\n\\`loam delta <FEAT> --json\\` exits 1 when either authored document behind the brief\nfailed to parse — \\`architecture.errors\\` non-empty, or \\`openapi.unreadable\\` true —\nwith \\`ok: true\\` and the full payload intact: the empty C4 slice means the delta\ndid not parse, and an empty \\`api\\` beside \\`openapi.unreadable\\` means the contract\ndelta did not parse, neither of them \"this feature changes nothing there\". Branch\non the exit code before consuming either slice as a task brief.\n\nFindings with severity \\`ok\\` are confirmations, not work: \\`c4.valid\\`, \\`delta.valid\\`,\n\\`requirements.covered\\`, \\`api.covered\\`, \\`spine.resolved\\`, \\`event.covered\\`, \\`coherence.ok\\`,\n\\`landscape.matched\\`, \\`archedge.covered\\`, \\`sources.resolved\\`, \\`sources.current\\`,\n\\`sources.walked\\`, \\`gherkin.current\\`.\n\nA finding's \\`subject\\` names the service it is about. The envelope separates \\`ok\\` (the\ncommand ran) from \\`valid\\` (the docs pass). A refusal is \\`ok: false\\` with a stable\n\\`error.code\\`, and \\`loam explain <code>\\` has the meaning of every one of them. What\nfollows is the other half — which command raises which:\n\n- Before any command can read anything: \\`no-config\\`, \\`config-invalid\\`,\n  \\`docs-missing\\`, \\`services-missing\\`, \\`unknown-target\\`, \\`invalid-option\\`.\n  \\`invalid-option\\` covers flags that contradict each other AND a value that\n  cannot be right — a \\`loam list\\` section that is not services or features, or a\n  service id that is not a legal \\`services/<id>/\\` directory name.\n- Every JOURNALED writer — \\`archive\\`, \\`unarchive\\`, \\`rebase\\`, \\`vouch\\`, \\`new\\`,\n  \\`gherkin\\`, \\`seed\\`, \\`subsystem\\` and \\`verify --record\\` — shares one transaction\n  and therefore one set of refusals: \\`docs-busy\\`, \\`commit-interrupted\\`,\n  \\`merge-failed\\` and \\`rollback-incomplete\\`. Learn them once and you have read\n  them for all nine. \\`loam doctor\\` names the interrupted state as\n  \\`doctor.commit-interrupted\\` and \\`loam validate\\` leads every mode with\n  \\`docs.commit-interrupted\\` while the journal sits there; every journaled writer\n  recovers a finished predecessor's journal on its next run and reports it as\n  \\`recovered\\` in \\`--json\\`.\n- \\`loam new\\`: \\`already-exists\\` — also the answer when a concurrent \\`new\\` for the\n  same id wins the race.\n- \\`loam vouch\\`: \\`sources-absent\\`, \\`sources-path-missing\\`, \\`vouch-raced\\`, and the\n  wrong-repo pair \\`repository-unavailable\\` / \\`service-mismatch\\`, because\n  \\`sources\\` resolve against the service's own checkout and from anywhere else\n  those paths are somebody else's.\n- \\`loam archive\\`: \\`not-coherent\\`, \\`living-outside-requirements\\`,\n  \\`archive-exists\\` — see the archive gate below.\n- \\`loam unarchive\\`: \\`feature-active\\`, \\`snapshot-missing\\`, \\`snapshot-stale\\`,\n  \\`snapshot-corrupt\\`, \\`restore-failed\\` — see \"Taking an archive back\".\n- \\`loam gherkin\\`: \\`gherkin-conflict\\`, plus the same wrong-repo pair, refused\n  before anything is written because the generated files land in the repo loam\n  is standing in.\n- \\`loam subsystem\\`: \\`subsystem-not-empty\\`, \\`move-uncommitted\\`, \\`move-failed\\`,\n  and \\`unknown-target\\` / \\`already-exists\\` / \\`invalid-option\\` for names that\n  resolve to nothing, collide in the flat namespace, or break the grammar.\n  \\`move-failed\\` is deliberately distinct from \\`merge-failed\\`: the move's own\n  transaction rolled back cleanly, nothing changed, and re-running can work.\n- \\`loam verify --record\\` / \\`--results\\` / \\`--contract-results\\`:\n  \\`answers-unreadable\\`, \\`answers-mismatch\\`, \\`answers-unevidenced\\`,\n  \\`record-federated\\`, \\`record-unreadable\\` and \\`record-raced\\`. Two records for\n  different services land in either order — the later one waits, then merges,\n  and both attestations survive.\n- \\`loam open\\`: \\`no-members\\`, \\`binding-duplicate\\`, \\`already-exists\\` (the\n  workspace file, which loam never silently overwrites — pass \\`--out\\` or\n  \\`--force\\`) and \\`invalid-option\\`.\n- \\`loam seed --from fleet.yaml\\`: \\`seed-file-invalid\\`, \\`seed-duplicate-service\\`,\n  \\`seed-unknown-subsystem\\`, \\`seed-landscape-edited\\`, \\`already-exists\\` when a\n  generated views file in \\`architecture/\\` was written by somebody rather than by\n  loam (no \\`// generated by loam\\` first line — seed writes nothing at all in that\n  case), and \\`unknown-service\\` for a call endpoint nothing declares. An existing\n  service directory is never moved, and nothing is ever deleted.\n- \\`internal\\` — an unexpected throw, the one code with no stable meaning.\n\n\\`--all\\` reports a target per service, a target per feature in flight, and one target\nof kind \\`landscape\\` for the fleet-level checks that belong to no single service.\n\nThree different words for three different questions, and no command conflates them:\n\\`ok\\` — the command ran; \\`valid\\` — the documents pass (\\`validate\\`); \\`verified\\` —\nsomebody says the code was built and showed evidence (\\`verify\\`). A feature can be\nvalid and unverified, or verified and incoherent. Read the one you meant.\n`;\n\n/* The archive gate, unarchive, and dropping a feature continue in\n * ./shipped/archive-gate.ts — one document section split at its own subject\n * seam, concatenated after this one by ../agents-md.ts. */\n"]}

package/dist/core/agent/agents-md.js

@@ -18,12 +18,26 @@ loam has no server or database. Delete it and the documents still make sense.
 
 \`architecture/landscape.likec4\` is the fleet map, and
 \`architecture/adrs/\` optional system-level decisions — only their links are graded.
-\`architecture/subsystems.likec4\` is GENERATED by \`loam subsystem sync\` from the
-directory tree under \`services/\` — one view per subsystem, a scoping aid, never
-hand-edited and never a second fleet map. A diagram you author belongs in the
-landscape or in a file of your own name beside it.
+\`architecture/subsystems.likec4\` and \`architecture/services.likec4\` are both
+GENERATED by \`loam subsystem sync\` — one view per subsystem from the directory
+tree under \`services/\`, and one overview view per service the fleet map draws.
+Scoping aids, never hand-edited and never a second fleet map; each is stale
+(\`subsystem.views-stale\`, one finding per file) until the next \`sync\`. Their one
+styling opt-in is a \`global { styleGroup subsystems { … } }\` — or
+\`styleGroup services\` — declared in any \`.likec4\` under \`architecture/\`, which
+\`sync\` then references. A diagram you author belongs in the landscape or in a
+file of your own name beside it; an authored view \`of\` an element the generated
+file also draws is legal, and the file that sorts first wins the default
+drill-down target while both stay reachable.
 \`services/<id>/\` holds a boundary's living \`model.likec4\`, \`spec.md\`,
-\`arch.spec.md\`, OpenAPI, AsyncAPI, runbook and health facts.
+\`arch.spec.md\`, OpenAPI, AsyncAPI, runbook and health facts — and
+\`services/<…>/<id>/usecases/*.likec4\`, the slot for a \`dynamic view\` over that
+service's OWN containers, tagged \`#req-<Requirement-ID>\`; a flow that crosses
+services lives in \`architecture/usecases/\` and is tagged \`#cap-\` instead. Title
+a service use case \`'<subsystem path> / <service id> / <use case>'\` — LikeC4
+splits a view title on \`/\` into browser folders, so that convention lands the
+flow in the same folder as the generated overview of its service. Nothing grades
+the title, and nothing grades the slot's absence: presence is never owed.
 \`features/<FEAT>/\` holds a change in flight: \`intent.md\`, \`delta.likec4\`,
 per-service requirement and contract deltas, and \`verification.yaml\`.
 \`features/archive/\` is shipped history.
@@ -78,7 +92,10 @@ decision or human-only act; the user does not have to type every loam command.
 If loam or an agent integration behaves unexpectedly, invoke \`/loam-report\` (or
 load \`$loam-report\` on a skills-only host). It collects a sanitized, reproducible
 Markdown report under \`loam-reports/\` without repairing the repository, retrying a
-writer or uploading anything. This is support, not a seventh lifecycle step.
+writer or uploading anything. Reports are numbered — \`loam-reports/NNN-YYYY-MM-DD-<slug>.md\`,
+cited by ordinal — and carry a \`Status:\` line, so \`loam doctor\` counts the
+directory and says which ordinal the next report takes. This is support, not a
+seventh lifecycle step.
 
 ## The cycle
 
@@ -86,7 +103,9 @@ writer or uploading anything. This is support, not a seventh lifecycle step.
    \`loam init --docs <path-to-docs-repo> --service <id>\`, then \`loam doctor\`.
 1. **Adopt** — for an undocumented boundary load \`loam instructions loam-adopt
    <id>\`, then use \`loam adopt --service <id> --json\`. Write drafts; a person,
-   never an agent, later vouches for them.
+   never an agent, later vouches for them. Draw the map's edges in the same pass:
+   the brief's \`landscape.touched\` is the only place an edgeless element is named,
+   and \`landscape.service-isolated\` (fleet scope) goes quiet on the first edge.
 2. **Understand** — start or resume with \`loam status --json\`; its ordered
    \`next[]\` is the work queue. Read \`next[0].execution\`: run it only when
    \`runnable\` is true; otherwise use \`kind\`, \`cwd\`, \`needs\` and \`after\`

package/dist/core/agent/agents-md.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../../../src/core/agent/agents-md.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiKnB,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,eAAe,CAAC,YAAY,CAAC,KAAK,WAAW,EAAE,CAAC","sourcesContent":["/**\n * The small, always-loaded orientation contract for a loam docs repository.\n *\n * Detailed grammars and workflows live behind `loam instructions`: those pages\n * describe the binary that is about to run, while this file is written once and\n * may be loaded into every agent turn for years. Keep only enough here to form\n * the next question, find the relevant page, and avoid an unsafe write.\n */\nimport { agentsStampLine } from \"./agents-stamp.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\n\nconst ORIENTATION = `# Working in this docs repo\n\nThis is a **loam** docs repo: plain files are the shared source of truth for a governed software\nfleet's architecture, requirements, contracts and verification evidence. A service may be a modular monolith, a network service, a CLI or a worker.\nloam has no server or database. Delete it and the documents still make sense.\n\n## What is where\n\n\\`architecture/landscape.likec4\\` is the fleet map, and\n\\`architecture/adrs/\\` optional system-level decisions — only their links are graded.\n\\`architecture/subsystems.likec4\\` is GENERATED by \\`loam subsystem sync\\` from the\ndirectory tree under \\`services/\\` — one view per subsystem, a scoping aid, never\nhand-edited and never a second fleet map. A diagram you author belongs in the\nlandscape or in a file of your own name beside it.\n\\`services/<id>/\\` holds a boundary's living \\`model.likec4\\`, \\`spec.md\\`,\n\\`arch.spec.md\\`, OpenAPI, AsyncAPI, runbook and health facts.\n\\`features/<FEAT>/\\` holds a change in flight: \\`intent.md\\`, \\`delta.likec4\\`,\nper-service requirement and contract deltas, and \\`verification.yaml\\`.\n\\`features/archive/\\` is shipped history.\n\nLiving documents are the complete current state. A feature document is a diff\nagainst them, reviewed as a diff; \\`loam archive\\` folds it into living state.\nDo not hand-edit the living landscape to add a feature change.\n\n## Linking between documents\n\nDocuments join with **standard markdown links** whose targets are real relative\npaths, for example \\`[decision](../adrs/ADR-001.md)\\`. They render in pull-request\nreview instead of showing literal brackets,\nand make “does this link resolve” a filesystem question; \\`[[Wikilinks]]\\` would\nrequire shortest-unique-path guessing.\nObsidian supports markdown links, autocomplete and rename-tracking when its\nwikilink setting is off. \\`link.unresolved\\` grades missing targets and CASE\n**is** graded; links outside this repository, \\`#section\\` targets, a fenced code\nblock or an inline code span are deliberately not graded.\n\n## \\`loam.json\\` — the wiring\n\nEvery repository commits its own \\`loam.json\\`:\n\n\\`{ \"docsDir\": \"../docs\", \"service\": \"payment-service\", \"gherkinDir\": \"features\" }\\`\n\n\\`docsDir\\` is stored exactly as it was passed and resolved against the directory\nholding the \\`loam.json\\`, so a relative path survives a clone; an absolute one\nraises \\`doctor.docs-absolute\\`. \\`service\\` binds a service checkout to the one boundary\nit may write evidence for. \\`gherkinDir\\` is optional. \\`agentTools\\` and\n\\`agentProfile\\` record which agent surfaces and workflow subset init manages;\n\\`agentFiles\\` records digests so unchanged generated pointers can refresh while\ncustomized ones remain untouched. With no config, loam refuses with \\`no-config\\`\nrather than guessing.\n\n\\`loam init --docs <dir>\\` **joins** an existing docs repo. Add \\`--create\\` only\nwhen creating a new one; a typo must not scaffold a second source of truth.\n\n## Starting from chat\n\nThere are two equivalent entry points into the same version-matched protocol.\nPrefer the explicit one when a user wants a predictable lifecycle: invoke\n\\`/loam-feature <FEAT> \"<title>\"\\` to propose, \\`/loam-implement <FEAT> [service]\\`\nto build, \\`/loam-check\\` and \\`/loam-verify <FEAT>\\` to grade it, and\n\\`/loam-ship <FEAT>\\` to finish. Most hosts use that flat slash\nspelling; Gemini uses \\`/loam:feature\\`, Amazon Q uses \\`@loam-feature\\`, and a\nskills-only host can invoke \\`$loam-feature\\`. Natural-language requests may load\nthe matching Agent Skill instead. Once either entry point is selected, the agent\ndrives the internal status/edit/validate loop and asks the user only for a real\ndecision or human-only act; the user does not have to type every loam command.\n\nIf loam or an agent integration behaves unexpectedly, invoke \\`/loam-report\\` (or\nload \\`$loam-report\\` on a skills-only host). It collects a sanitized, reproducible\nMarkdown report under \\`loam-reports/\\` without repairing the repository, retrying a\nwriter or uploading anything. This is support, not a seventh lifecycle step.\n\n## The cycle\n\n0. **Wire the repo** — in each service checkout run\n   \\`loam init --docs <path-to-docs-repo> --service <id>\\`, then \\`loam doctor\\`.\n1. **Adopt** — for an undocumented boundary load \\`loam instructions loam-adopt\n   <id>\\`, then use \\`loam adopt --service <id> --json\\`. Write drafts; a person,\n   never an agent, later vouches for them.\n2. **Understand** — start or resume with \\`loam status --json\\`; its ordered\n   \\`next[]\\` is the work queue. Read \\`next[0].execution\\`: run it only when\n   \\`runnable\\` is true; otherwise use \\`kind\\`, \\`cwd\\`, \\`needs\\` and \\`after\\`\n   to complete the edit or external-repo step. Use \\`loam list --json\\`, \\`loam show <id> --json\\`\n   and \\`loam explore <id> --json\\` before proposing a change. Never propose a\n   change to a service you have not read.\n3. **Scaffold** — load \\`loam instructions loam-feature <FEAT>\\`, then run\n   \\`loam new <FEAT> --title \"...\" --touches <service>\\`.\n4. **Author** — fill the scaffolded TODOs and run \\`loam rebase <FEAT>\\` after\n   reading the living baselines. The exact joins and authoring grammars are in\n   the reference pages below.\n5. **Check** — load \\`loam instructions loam-check --no-fix-tables\\`, run\n   \\`loam validate <FEAT> --json\\`, and use \\`loam explain <code>\\` for reported\n   codes. \\`loam dependencies --json\\` names features that must archive first.\n6. **Build** — load \\`loam instructions loam-implement <FEAT>\\`.\n   \\`loam delta <FEAT> --service <id> --json\\` is one service's task; in that\n   service checkout, \\`loam gherkin <FEAT>\\` emits its executable scenarios.\n7. **Verify** — \\`loam verify <FEAT> --json\\` is the checklist. Record evidence\n   from each affected service's own checkout. Read\n   \\`loam instructions loam-done-check\\` before recording anything.\n8. **Ship** — load \\`loam instructions loam-ship <FEAT>\\`; begin with\n   \\`loam archive <FEAT> --dry-run --json\\`, then archive only after the code is\n   merged and the plan is the one reviewed.\n\n## Reading loam's output\n\nEvery command takes \\`--json\\`. The envelope has \\`contractVersion\\`, \\`ok\\` and,\non refusal, \\`error.code\\`. Unknown flags are \\`invalid-option\\`; \\`--help\\` and\n\\`--version\\` pass through. Branch on stable codes, never message prose.\n\nValidation \\`findings[]\\` carry \\`severity\\`; archive-related findings also carry\n\\`gates\\`. Severity and gating are two different questions: errors invalidate,\nwhile \\`gates: true\\` makes archive refuse — archive is gated on coherence, so a\ngating finding stops it whatever its severity. Advisory warnings never block.\n\\`--approve\\` overrides the gating issues — only those that are judgement calls —\nand never a mechanical loss. For example \\`delta.requirement-not-merged\\` warns but gates;\n\\`living.requirement-outside-requirements\\` cannot be approved, while\n\\`openapi.op-modified\\` is reviewable.\n\n\\`loam status --json\\` orders executable next actions. Findings include structured\n\\`locations[]\\`; use their paths instead of extracting filenames from prose.\n\\`loam show <FEAT> --json\\` includes a \\`review\\` pack with intent, architecture,\ncontracts, dependencies, verification, blockers and the same next actions.\n\\`loam explain <code> --json\\`\nreturns one code's meaning and fix; \\`loam explain --codes --json\\` lists them.\nWhich codes an INVOCATION can raise is in \\`loam instructions loam-codes\\`.\n\n## The identity rule\n\nA service is the element whose \\`metadata { service '<id>' }\\` matches its\n\\`services/<id>/\\` directory. An exact element id is the legacy fallback. Never\ninfer identity from display names or containment. Relationships join to contracts\nthrough exact ids: OpenAPI \\`operationId\\`, requirement \\`Operations:\\`, and C4\n\\`metadata { op '...' }\\`. Consult \\`loam instructions loam-spine\\` before editing\na join.\n\n## Reference pages — fetch when needed\n\n- \\`loam instructions loam-codes\\` — finding/refusal inventory and fixes.\n- \\`loam instructions loam-spine\\` — operation, message, coverage, permission,\n  capability and baseline joins.\n- \\`loam instructions loam-authoring\\` — arch requirements, generated Gherkin\n  and frontmatter/vouch grammar.\n- \\`loam instructions loam-done-check\\` — verification evidence and verdicts.\n\nBare \\`loam instructions\\` lists the six workflows, the separate \\`loam-report\\`\nsupport protocol and these references. Generated agent command/skill files are\nsmall pointers to them, so the runtime page wins if an old pointer disagrees with\nthe installed binary. MCP clients can read the same pages as\n\\`loam://orientation\\` and \\`loam://instructions/<name>\\` resources.\n\n## Safety and hand-back\n\nloam's writers are journaled, but the lifecycle still matters. Do not run\n\\`loam vouch\\` for a human, do not invent evidence, do not archive before code is\nmerged, and do not edit generated files under \\`<gherkinDir>/loam/\\` by hand.\n\\`loam unarchive <FEAT>\\` is the supported undo. To abandon a feature that was\nnever archived, review it and use \\`git rm -r features/<FEAT>\\`; loam deliberately\nhas no destructive drop command.\n\nFinish by reporting remaining warnings, unverifiable claims, files or directories\nyou did not inspect, and the exact human action still owed.\n`;\n\nexport const AGENTS_MD = `${agentsStampLine(LOAM_VERSION)}\\n${ORIENTATION}`;\n"]}
+{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../../../src/core/agent/agents-md.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoLnB,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,eAAe,CAAC,YAAY,CAAC,KAAK,WAAW,EAAE,CAAC","sourcesContent":["/**\n * The small, always-loaded orientation contract for a loam docs repository.\n *\n * Detailed grammars and workflows live behind `loam instructions`: those pages\n * describe the binary that is about to run, while this file is written once and\n * may be loaded into every agent turn for years. Keep only enough here to form\n * the next question, find the relevant page, and avoid an unsafe write.\n */\nimport { agentsStampLine } from \"./agents-stamp.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\n\nconst ORIENTATION = `# Working in this docs repo\n\nThis is a **loam** docs repo: plain files are the shared source of truth for a governed software\nfleet's architecture, requirements, contracts and verification evidence. A service may be a modular monolith, a network service, a CLI or a worker.\nloam has no server or database. Delete it and the documents still make sense.\n\n## What is where\n\n\\`architecture/landscape.likec4\\` is the fleet map, and\n\\`architecture/adrs/\\` optional system-level decisions — only their links are graded.\n\\`architecture/subsystems.likec4\\` and \\`architecture/services.likec4\\` are both\nGENERATED by \\`loam subsystem sync\\` — one view per subsystem from the directory\ntree under \\`services/\\`, and one overview view per service the fleet map draws.\nScoping aids, never hand-edited and never a second fleet map; each is stale\n(\\`subsystem.views-stale\\`, one finding per file) until the next \\`sync\\`. Their one\nstyling opt-in is a \\`global { styleGroup subsystems { … } }\\` — or\n\\`styleGroup services\\` — declared in any \\`.likec4\\` under \\`architecture/\\`, which\n\\`sync\\` then references. A diagram you author belongs in the landscape or in a\nfile of your own name beside it; an authored view \\`of\\` an element the generated\nfile also draws is legal, and the file that sorts first wins the default\ndrill-down target while both stay reachable.\n\\`services/<id>/\\` holds a boundary's living \\`model.likec4\\`, \\`spec.md\\`,\n\\`arch.spec.md\\`, OpenAPI, AsyncAPI, runbook and health facts — and\n\\`services/<…>/<id>/usecases/*.likec4\\`, the slot for a \\`dynamic view\\` over that\nservice's OWN containers, tagged \\`#req-<Requirement-ID>\\`; a flow that crosses\nservices lives in \\`architecture/usecases/\\` and is tagged \\`#cap-\\` instead. Title\na service use case \\`'<subsystem path> / <service id> / <use case>'\\` — LikeC4\nsplits a view title on \\`/\\` into browser folders, so that convention lands the\nflow in the same folder as the generated overview of its service. Nothing grades\nthe title, and nothing grades the slot's absence: presence is never owed.\n\\`features/<FEAT>/\\` holds a change in flight: \\`intent.md\\`, \\`delta.likec4\\`,\nper-service requirement and contract deltas, and \\`verification.yaml\\`.\n\\`features/archive/\\` is shipped history.\n\nLiving documents are the complete current state. A feature document is a diff\nagainst them, reviewed as a diff; \\`loam archive\\` folds it into living state.\nDo not hand-edit the living landscape to add a feature change.\n\n## Linking between documents\n\nDocuments join with **standard markdown links** whose targets are real relative\npaths, for example \\`[decision](../adrs/ADR-001.md)\\`. They render in pull-request\nreview instead of showing literal brackets,\nand make “does this link resolve” a filesystem question; \\`[[Wikilinks]]\\` would\nrequire shortest-unique-path guessing.\nObsidian supports markdown links, autocomplete and rename-tracking when its\nwikilink setting is off. \\`link.unresolved\\` grades missing targets and CASE\n**is** graded; links outside this repository, \\`#section\\` targets, a fenced code\nblock or an inline code span are deliberately not graded.\n\n## \\`loam.json\\` — the wiring\n\nEvery repository commits its own \\`loam.json\\`:\n\n\\`{ \"docsDir\": \"../docs\", \"service\": \"payment-service\", \"gherkinDir\": \"features\" }\\`\n\n\\`docsDir\\` is stored exactly as it was passed and resolved against the directory\nholding the \\`loam.json\\`, so a relative path survives a clone; an absolute one\nraises \\`doctor.docs-absolute\\`. \\`service\\` binds a service checkout to the one boundary\nit may write evidence for. \\`gherkinDir\\` is optional. \\`agentTools\\` and\n\\`agentProfile\\` record which agent surfaces and workflow subset init manages;\n\\`agentFiles\\` records digests so unchanged generated pointers can refresh while\ncustomized ones remain untouched. With no config, loam refuses with \\`no-config\\`\nrather than guessing.\n\n\\`loam init --docs <dir>\\` **joins** an existing docs repo. Add \\`--create\\` only\nwhen creating a new one; a typo must not scaffold a second source of truth.\n\n## Starting from chat\n\nThere are two equivalent entry points into the same version-matched protocol.\nPrefer the explicit one when a user wants a predictable lifecycle: invoke\n\\`/loam-feature <FEAT> \"<title>\"\\` to propose, \\`/loam-implement <FEAT> [service]\\`\nto build, \\`/loam-check\\` and \\`/loam-verify <FEAT>\\` to grade it, and\n\\`/loam-ship <FEAT>\\` to finish. Most hosts use that flat slash\nspelling; Gemini uses \\`/loam:feature\\`, Amazon Q uses \\`@loam-feature\\`, and a\nskills-only host can invoke \\`$loam-feature\\`. Natural-language requests may load\nthe matching Agent Skill instead. Once either entry point is selected, the agent\ndrives the internal status/edit/validate loop and asks the user only for a real\ndecision or human-only act; the user does not have to type every loam command.\n\nIf loam or an agent integration behaves unexpectedly, invoke \\`/loam-report\\` (or\nload \\`$loam-report\\` on a skills-only host). It collects a sanitized, reproducible\nMarkdown report under \\`loam-reports/\\` without repairing the repository, retrying a\nwriter or uploading anything. Reports are numbered — \\`loam-reports/NNN-YYYY-MM-DD-<slug>.md\\`,\ncited by ordinal — and carry a \\`Status:\\` line, so \\`loam doctor\\` counts the\ndirectory and says which ordinal the next report takes. This is support, not a\nseventh lifecycle step.\n\n## The cycle\n\n0. **Wire the repo** — in each service checkout run\n   \\`loam init --docs <path-to-docs-repo> --service <id>\\`, then \\`loam doctor\\`.\n1. **Adopt** — for an undocumented boundary load \\`loam instructions loam-adopt\n   <id>\\`, then use \\`loam adopt --service <id> --json\\`. Write drafts; a person,\n   never an agent, later vouches for them. Draw the map's edges in the same pass:\n   the brief's \\`landscape.touched\\` is the only place an edgeless element is named,\n   and \\`landscape.service-isolated\\` (fleet scope) goes quiet on the first edge.\n2. **Understand** — start or resume with \\`loam status --json\\`; its ordered\n   \\`next[]\\` is the work queue. Read \\`next[0].execution\\`: run it only when\n   \\`runnable\\` is true; otherwise use \\`kind\\`, \\`cwd\\`, \\`needs\\` and \\`after\\`\n   to complete the edit or external-repo step. Use \\`loam list --json\\`, \\`loam show <id> --json\\`\n   and \\`loam explore <id> --json\\` before proposing a change. Never propose a\n   change to a service you have not read.\n3. **Scaffold** — load \\`loam instructions loam-feature <FEAT>\\`, then run\n   \\`loam new <FEAT> --title \"...\" --touches <service>\\`.\n4. **Author** — fill the scaffolded TODOs and run \\`loam rebase <FEAT>\\` after\n   reading the living baselines. The exact joins and authoring grammars are in\n   the reference pages below.\n5. **Check** — load \\`loam instructions loam-check --no-fix-tables\\`, run\n   \\`loam validate <FEAT> --json\\`, and use \\`loam explain <code>\\` for reported\n   codes. \\`loam dependencies --json\\` names features that must archive first.\n6. **Build** — load \\`loam instructions loam-implement <FEAT>\\`.\n   \\`loam delta <FEAT> --service <id> --json\\` is one service's task; in that\n   service checkout, \\`loam gherkin <FEAT>\\` emits its executable scenarios.\n7. **Verify** — \\`loam verify <FEAT> --json\\` is the checklist. Record evidence\n   from each affected service's own checkout. Read\n   \\`loam instructions loam-done-check\\` before recording anything.\n8. **Ship** — load \\`loam instructions loam-ship <FEAT>\\`; begin with\n   \\`loam archive <FEAT> --dry-run --json\\`, then archive only after the code is\n   merged and the plan is the one reviewed.\n\n## Reading loam's output\n\nEvery command takes \\`--json\\`. The envelope has \\`contractVersion\\`, \\`ok\\` and,\non refusal, \\`error.code\\`. Unknown flags are \\`invalid-option\\`; \\`--help\\` and\n\\`--version\\` pass through. Branch on stable codes, never message prose.\n\nValidation \\`findings[]\\` carry \\`severity\\`; archive-related findings also carry\n\\`gates\\`. Severity and gating are two different questions: errors invalidate,\nwhile \\`gates: true\\` makes archive refuse — archive is gated on coherence, so a\ngating finding stops it whatever its severity. Advisory warnings never block.\n\\`--approve\\` overrides the gating issues — only those that are judgement calls —\nand never a mechanical loss. For example \\`delta.requirement-not-merged\\` warns but gates;\n\\`living.requirement-outside-requirements\\` cannot be approved, while\n\\`openapi.op-modified\\` is reviewable.\n\n\\`loam status --json\\` orders executable next actions. Findings include structured\n\\`locations[]\\`; use their paths instead of extracting filenames from prose.\n\\`loam show <FEAT> --json\\` includes a \\`review\\` pack with intent, architecture,\ncontracts, dependencies, verification, blockers and the same next actions.\n\\`loam explain <code> --json\\`\nreturns one code's meaning and fix; \\`loam explain --codes --json\\` lists them.\nWhich codes an INVOCATION can raise is in \\`loam instructions loam-codes\\`.\n\n## The identity rule\n\nA service is the element whose \\`metadata { service '<id>' }\\` matches its\n\\`services/<id>/\\` directory. An exact element id is the legacy fallback. Never\ninfer identity from display names or containment. Relationships join to contracts\nthrough exact ids: OpenAPI \\`operationId\\`, requirement \\`Operations:\\`, and C4\n\\`metadata { op '...' }\\`. Consult \\`loam instructions loam-spine\\` before editing\na join.\n\n## Reference pages — fetch when needed\n\n- \\`loam instructions loam-codes\\` — finding/refusal inventory and fixes.\n- \\`loam instructions loam-spine\\` — operation, message, coverage, permission,\n  capability and baseline joins.\n- \\`loam instructions loam-authoring\\` — arch requirements, generated Gherkin\n  and frontmatter/vouch grammar.\n- \\`loam instructions loam-done-check\\` — verification evidence and verdicts.\n\nBare \\`loam instructions\\` lists the six workflows, the separate \\`loam-report\\`\nsupport protocol and these references. Generated agent command/skill files are\nsmall pointers to them, so the runtime page wins if an old pointer disagrees with\nthe installed binary. MCP clients can read the same pages as\n\\`loam://orientation\\` and \\`loam://instructions/<name>\\` resources.\n\n## Safety and hand-back\n\nloam's writers are journaled, but the lifecycle still matters. Do not run\n\\`loam vouch\\` for a human, do not invent evidence, do not archive before code is\nmerged, and do not edit generated files under \\`<gherkinDir>/loam/\\` by hand.\n\\`loam unarchive <FEAT>\\` is the supported undo. To abandon a feature that was\nnever archived, review it and use \\`git rm -r features/<FEAT>\\`; loam deliberately\nhas no destructive drop command.\n\nFinish by reporting remaining warnings, unverifiable claims, files or directories\nyou did not inspect, and the exact human action still owed.\n`;\n\nexport const AGENTS_MD = `${agentsStampLine(LOAM_VERSION)}\\n${ORIENTATION}`;\n"]}

package/dist/core/agent/support/report.js

@@ -63,11 +63,31 @@ more for secrets before handing it back.
 
 ## Write one separate report
 
-Create \`loam-reports/YYYY-MM-DD-<short-slug>.md\` at the current repository root. Use a short neutral
-slug based on the symptom, not a customer, person or secret. Never overwrite a different incident;
-add a numeric suffix when the path exists. Reports are ordinary project files so the team can
-review or commit them deliberately, but do not upload, submit an issue, send telemetry, or contact
-any service automatically.
+Create \`loam-reports/NNN-YYYY-MM-DD-<short-slug>.md\` in the directory holding the \`loam.json\` that
+resolved — or, when a \`loam.json\` was found but does not parse, beside that file, so a report about
+the broken config joins the corpus already there; only when there is no config file at or above you
+is it the directory you run in.
+\`loam doctor --json\` hands you that whole directory — that root WITH \`loam-reports/\`
+already on the end — as \`reports.dir\`: write inside the path it gives, never joined onto
+\`loam-reports/\` a second time. \`NNN\` is an ordinal of at least three digits, zero-padded, one more
+than the highest already in that directory — read \`reports.next\` from the same output, which says
+\`001\` when the directory is empty or absent, and widens past three digits rather than reusing a
+number once the corpus gets there. Use a short neutral slug based on the symptom, not a customer,
+person or secret. Never
+overwrite a different incident: a path that already exists means a concurrent report claimed that
+ordinal, so take the next one rather than adding a suffix. That check is on the PATH, and the
+promise is about the ordinal, so re-run \`loam doctor --json\` after writing: if two entries carry
+the same \`ordinal\`, the one with the later \`Recorded\` timestamp renames itself to the next free
+number. The ordinal is the report's handle —
+cite one by its number in a commit message, an issue, or another report's cross-references, and
+never by filename, which is free to be renamed. The ordinal is unique within that directory, not
+across a fleet: a service repository and the docs repository each number their own, so when two
+repositories are in play cite \`<repo>/loam-reports/NNN\`.
+
+Reports are ordinary project files so the team can review or commit them deliberately, but
+do not upload, submit an issue, send telemetry, or contact any service automatically.
+\`loam doctor\` reads the directory — how many reports it holds, how many are in each status, and
+which ordinal comes next — and that is a local read of local files: nothing is transmitted.
 
 Use this shape, omitting only fields that truly cannot be known and marking them \`not collected\`:
 
@@ -75,6 +95,7 @@ Use this shape, omitting only fields that truly cannot be known and marking them
 
     - Recorded: <ISO-8601 timestamp>
     - Classification: <one value above>
+    - Status: open
     - Repository role: <docs | service | combined | unresolved>
     - loam version: <version>
     - Entry point: <chat command, skill, or CLI command; sanitized>
@@ -91,6 +112,19 @@ Use this shape, omitting only fields that truly cannot be known and marking them
     ## Missing evidence
     ## Sanitization
 
+\`Status\` is written as \`open\` and stays the report's own record of where it got to. The vocabulary
+is \`open\`, \`sent\` (handed to loam's author — the person forwarding a report sets this, never the
+agent writing it), \`fixed in <version>\`, and \`superseded by <NNN>\` naming the report that
+replaced this one. Close a report by editing its own \`Status\` line: there is no index to keep in
+step, and \`loam doctor\` counts the directory by reading that line's first word, so
+\`fixed in 0.2.0-alpha.5\` counts as fixed. It reads that line from the HEADER FIELD BLOCK only —
+the lines above the first \`##\` heading, quoted code skipped in either markdown spelling: a fence
+(closed only by a run of the same character at least as long as the one that opened it, so a
+\`\`\` inside a \`\`\`\` block is content) and an indented block, which is the shape THIS template is
+printed in above. So a report that quotes this template, however it quotes it, still counts as
+whatever its own header says. A report written before this
+field existed has no \`Status\` line and counts as unstated.
+
 In \`Machine contract\`, include exit code plus the stable envelope fields and relevant finding
 codes/locations; do not paste an entire large JSON payload. In \`Sanitization\`, list the kinds of
 values removed without revealing them. If no workaround is known, say so rather than inventing one.

package/dist/core/agent/support/report.js.map

@@ -1 +1 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../../src/core/agent/support/report.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,uFAAuF;IACzF,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,oOAAoO;IACtO,UAAU,EAAE,+BAA+B;IAC3C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE;QACL,+EAA+E;QAC/E,iFAAiF;QACjF,yFAAyF;QACzF,gFAAgF;QAChF,wFAAwF;KACzF;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiFP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * The incident-reporting protocol: preserve a small, sanitized reproducer when\n * loam or its agent integration behaves unexpectedly, without turning loam\n * into a telemetry service or retrying a risky write.\n */\nexport const LOAM_REPORT: CommandContent = {\n  name: \"loam-report\",\n  description:\n    \"Record unexpected loam or agent behavior as a sanitized, reproducible Markdown report\",\n  argumentHint: \"\",\n  purpose:\n    \"Collect one unexpected loam or agent-integration incident into a separate, reviewable Markdown file. This is local diagnostics only: redact secrets, never upload automatically, and never repeat a writer merely to reproduce it.\",\n  invocation: \"loam instructions loam-report\",\n  placeholders: [],\n  spine: [\n    \"preserve the user's original symptom and expected result before investigating\",\n    \"collect the binary version, wiring diagnosis and the smallest safe reproduction\",\n    \"classify the failure without repairing, retrying a writer or changing project documents\",\n    \"sanitize commands, paths and output, then write one report under loam-reports/\",\n    \"hand back the report path, classification and any evidence that could not be collected\",\n  ],\n  body: `Record one incident where loam, a generated command/skill, or the agent following it\nbehaved unexpectedly. The result is a local diagnostic document, not a repair and not telemetry.\nDo not change architecture/spec files while collecting it.\n\n## Preserve the symptom first\n\nBefore running anything, write down the user's original request, what they expected, what actually\nhappened, the command or chat entry point involved, and whether any files may already have changed.\nDo not improve or reinterpret the failing command yet: a cleaned-up command is not a reproduction.\n\nClassify the incident as one of these, using \\`inconclusive\\` until the evidence supports another:\n\n- \\`loam-product\\` — the binary violated its documented contract or produced internally inconsistent output;\n- \\`project-data\\` — the binary correctly reported invalid, incomplete or stale repository documents;\n- \\`agent-workflow\\` — the generated command/skill was missing, stale, misrouted or followed incorrectly;\n- \\`host-infrastructure\\` — permissions, filesystem, process, shell or tool-host behavior prevented the run;\n- \\`inconclusive\\` — the available evidence does not distinguish the above.\n\n## Collect only safe evidence\n\n1. Run \\`loam --version\\` and record the result.\n2. Run \\`loam doctor --json\\`. If it succeeds, keep \\`healthy\\`, the finding codes and their structured\n   locations/fixes, the resolved repository role, and the write-path state. If it refuses, keep\n   \\`error.code\\` and the sanitized message. Do not apply the fixes during reporting.\n3. When the repository is wired, run \\`loam status --json\\` and keep only the state and next-action\n   rows relevant to this incident. A refusal is evidence too; keep its \\`error.code\\`.\n4. Re-run the original operation only when it is read-only and safe. Never re-run \\`init\\`, \\`new\\`,\n   \\`rebase\\`, \\`subsystem\\`, \\`archive\\`, \\`unarchive\\`, \\`vouch\\`, a recording form of \\`verify\\`, or\n   any other writer merely to make it fail twice. For a writer, record its original exit/output and\n   inspect \\`doctor\\`, \\`status\\` and version only. Do not repair, roll back or delete anything unless\n   the user separately asks for that action.\n5. Prefer the JSON envelope: record \\`contractVersion\\`, \\`ok\\`, \\`command\\`, \\`error.code\\`, finding\n   codes and \\`locations[]\\`. Quote only the smallest stdout/stderr excerpt that demonstrates the\n   symptom. State what was omitted.\n\n## Sanitize before writing\n\nNever include credentials, tokens, cookies, authorization headers, private keys, environment dumps,\nor values of variables whose names contain \\`TOKEN\\`, \\`SECRET\\`, \\`PASSWORD\\`, \\`AUTH\\`, \\`COOKIE\\` or\n\\`KEY\\`. Replace each value with \\`<redacted>\\`. Replace the user's home directory with \\`<home>\\` and\nprefer repository-relative paths. Do not copy source files, architecture/spec bodies, or a complete\ncommand output when a code and short excerpt prove the same fact. Review the finished report once\nmore for secrets before handing it back.\n\n## Write one separate report\n\nCreate \\`loam-reports/YYYY-MM-DD-<short-slug>.md\\` at the current repository root. Use a short neutral\nslug based on the symptom, not a customer, person or secret. Never overwrite a different incident;\nadd a numeric suffix when the path exists. Reports are ordinary project files so the team can\nreview or commit them deliberately, but do not upload, submit an issue, send telemetry, or contact\nany service automatically.\n\nUse this shape, omitting only fields that truly cannot be known and marking them \\`not collected\\`:\n\n    # loam problem report: <short title>\n\n    - Recorded: <ISO-8601 timestamp>\n    - Classification: <one value above>\n    - Repository role: <docs | service | combined | unresolved>\n    - loam version: <version>\n    - Entry point: <chat command, skill, or CLI command; sanitized>\n    - Side effects observed: <none known | paths changed | unknown>\n\n    ## Summary\n    ## Expected\n    ## Actual\n    ## Minimal safe reproduction\n    ## Machine contract\n    ## Doctor and status evidence\n    ## Files changed or write state\n    ## Workaround\n    ## Missing evidence\n    ## Sanitization\n\nIn \\`Machine contract\\`, include exit code plus the stable envelope fields and relevant finding\ncodes/locations; do not paste an entire large JSON payload. In \\`Sanitization\\`, list the kinds of\nvalues removed without revealing them. If no workaround is known, say so rather than inventing one.\n\nFinish by telling the user the report path, classification, whether project files changed, and which\nevidence was unavailable. Keep diagnosis separate from certainty: a plausible cause belongs under\n\\`Summary\\` as a hypothesis until the reproduction proves it.\n`,\n};\n"]}
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../../src/core/agent/support/report.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,uFAAuF;IACzF,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,oOAAoO;IACtO,UAAU,EAAE,+BAA+B;IAC3C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE;QACL,+EAA+E;QAC/E,iFAAiF;QACjF,yFAAyF;QACzF,gFAAgF;QAChF,wFAAwF;KACzF;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmHP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * The incident-reporting protocol: preserve a small, sanitized reproducer when\n * loam or its agent integration behaves unexpectedly, without turning loam\n * into a telemetry service or retrying a risky write.\n */\nexport const LOAM_REPORT: CommandContent = {\n  name: \"loam-report\",\n  description:\n    \"Record unexpected loam or agent behavior as a sanitized, reproducible Markdown report\",\n  argumentHint: \"\",\n  purpose:\n    \"Collect one unexpected loam or agent-integration incident into a separate, reviewable Markdown file. This is local diagnostics only: redact secrets, never upload automatically, and never repeat a writer merely to reproduce it.\",\n  invocation: \"loam instructions loam-report\",\n  placeholders: [],\n  spine: [\n    \"preserve the user's original symptom and expected result before investigating\",\n    \"collect the binary version, wiring diagnosis and the smallest safe reproduction\",\n    \"classify the failure without repairing, retrying a writer or changing project documents\",\n    \"sanitize commands, paths and output, then write one report under loam-reports/\",\n    \"hand back the report path, classification and any evidence that could not be collected\",\n  ],\n  body: `Record one incident where loam, a generated command/skill, or the agent following it\nbehaved unexpectedly. The result is a local diagnostic document, not a repair and not telemetry.\nDo not change architecture/spec files while collecting it.\n\n## Preserve the symptom first\n\nBefore running anything, write down the user's original request, what they expected, what actually\nhappened, the command or chat entry point involved, and whether any files may already have changed.\nDo not improve or reinterpret the failing command yet: a cleaned-up command is not a reproduction.\n\nClassify the incident as one of these, using \\`inconclusive\\` until the evidence supports another:\n\n- \\`loam-product\\` — the binary violated its documented contract or produced internally inconsistent output;\n- \\`project-data\\` — the binary correctly reported invalid, incomplete or stale repository documents;\n- \\`agent-workflow\\` — the generated command/skill was missing, stale, misrouted or followed incorrectly;\n- \\`host-infrastructure\\` — permissions, filesystem, process, shell or tool-host behavior prevented the run;\n- \\`inconclusive\\` — the available evidence does not distinguish the above.\n\n## Collect only safe evidence\n\n1. Run \\`loam --version\\` and record the result.\n2. Run \\`loam doctor --json\\`. If it succeeds, keep \\`healthy\\`, the finding codes and their structured\n   locations/fixes, the resolved repository role, and the write-path state. If it refuses, keep\n   \\`error.code\\` and the sanitized message. Do not apply the fixes during reporting.\n3. When the repository is wired, run \\`loam status --json\\` and keep only the state and next-action\n   rows relevant to this incident. A refusal is evidence too; keep its \\`error.code\\`.\n4. Re-run the original operation only when it is read-only and safe. Never re-run \\`init\\`, \\`new\\`,\n   \\`rebase\\`, \\`subsystem\\`, \\`archive\\`, \\`unarchive\\`, \\`vouch\\`, a recording form of \\`verify\\`, or\n   any other writer merely to make it fail twice. For a writer, record its original exit/output and\n   inspect \\`doctor\\`, \\`status\\` and version only. Do not repair, roll back or delete anything unless\n   the user separately asks for that action.\n5. Prefer the JSON envelope: record \\`contractVersion\\`, \\`ok\\`, \\`command\\`, \\`error.code\\`, finding\n   codes and \\`locations[]\\`. Quote only the smallest stdout/stderr excerpt that demonstrates the\n   symptom. State what was omitted.\n\n## Sanitize before writing\n\nNever include credentials, tokens, cookies, authorization headers, private keys, environment dumps,\nor values of variables whose names contain \\`TOKEN\\`, \\`SECRET\\`, \\`PASSWORD\\`, \\`AUTH\\`, \\`COOKIE\\` or\n\\`KEY\\`. Replace each value with \\`<redacted>\\`. Replace the user's home directory with \\`<home>\\` and\nprefer repository-relative paths. Do not copy source files, architecture/spec bodies, or a complete\ncommand output when a code and short excerpt prove the same fact. Review the finished report once\nmore for secrets before handing it back.\n\n## Write one separate report\n\nCreate \\`loam-reports/NNN-YYYY-MM-DD-<short-slug>.md\\` in the directory holding the \\`loam.json\\` that\nresolved — or, when a \\`loam.json\\` was found but does not parse, beside that file, so a report about\nthe broken config joins the corpus already there; only when there is no config file at or above you\nis it the directory you run in.\n\\`loam doctor --json\\` hands you that whole directory — that root WITH \\`loam-reports/\\`\nalready on the end — as \\`reports.dir\\`: write inside the path it gives, never joined onto\n\\`loam-reports/\\` a second time. \\`NNN\\` is an ordinal of at least three digits, zero-padded, one more\nthan the highest already in that directory — read \\`reports.next\\` from the same output, which says\n\\`001\\` when the directory is empty or absent, and widens past three digits rather than reusing a\nnumber once the corpus gets there. Use a short neutral slug based on the symptom, not a customer,\nperson or secret. Never\noverwrite a different incident: a path that already exists means a concurrent report claimed that\nordinal, so take the next one rather than adding a suffix. That check is on the PATH, and the\npromise is about the ordinal, so re-run \\`loam doctor --json\\` after writing: if two entries carry\nthe same \\`ordinal\\`, the one with the later \\`Recorded\\` timestamp renames itself to the next free\nnumber. The ordinal is the report's handle —\ncite one by its number in a commit message, an issue, or another report's cross-references, and\nnever by filename, which is free to be renamed. The ordinal is unique within that directory, not\nacross a fleet: a service repository and the docs repository each number their own, so when two\nrepositories are in play cite \\`<repo>/loam-reports/NNN\\`.\n\nReports are ordinary project files so the team can review or commit them deliberately, but\ndo not upload, submit an issue, send telemetry, or contact any service automatically.\n\\`loam doctor\\` reads the directory — how many reports it holds, how many are in each status, and\nwhich ordinal comes next — and that is a local read of local files: nothing is transmitted.\n\nUse this shape, omitting only fields that truly cannot be known and marking them \\`not collected\\`:\n\n    # loam problem report: <short title>\n\n    - Recorded: <ISO-8601 timestamp>\n    - Classification: <one value above>\n    - Status: open\n    - Repository role: <docs | service | combined | unresolved>\n    - loam version: <version>\n    - Entry point: <chat command, skill, or CLI command; sanitized>\n    - Side effects observed: <none known | paths changed | unknown>\n\n    ## Summary\n    ## Expected\n    ## Actual\n    ## Minimal safe reproduction\n    ## Machine contract\n    ## Doctor and status evidence\n    ## Files changed or write state\n    ## Workaround\n    ## Missing evidence\n    ## Sanitization\n\n\\`Status\\` is written as \\`open\\` and stays the report's own record of where it got to. The vocabulary\nis \\`open\\`, \\`sent\\` (handed to loam's author — the person forwarding a report sets this, never the\nagent writing it), \\`fixed in <version>\\`, and \\`superseded by <NNN>\\` naming the report that\nreplaced this one. Close a report by editing its own \\`Status\\` line: there is no index to keep in\nstep, and \\`loam doctor\\` counts the directory by reading that line's first word, so\n\\`fixed in 0.2.0-alpha.5\\` counts as fixed. It reads that line from the HEADER FIELD BLOCK only —\nthe lines above the first \\`##\\` heading, quoted code skipped in either markdown spelling: a fence\n(closed only by a run of the same character at least as long as the one that opened it, so a\n\\`\\`\\` inside a \\`\\`\\`\\` block is content) and an indented block, which is the shape THIS template is\nprinted in above. So a report that quotes this template, however it quotes it, still counts as\nwhatever its own header says. A report written before this\nfield existed has no \\`Status\\` line and counts as unstated.\n\nIn \\`Machine contract\\`, include exit code plus the stable envelope fields and relevant finding\ncodes/locations; do not paste an entire large JSON payload. In \\`Sanitization\\`, list the kinds of\nvalues removed without revealing them. If no workaround is known, say so rather than inventing one.\n\nFinish by telling the user the report path, classification, whether project files changed, and which\nevidence was unavailable. Keep diagnosis separate from certainty: a plausible cause belongs under\n\\`Summary\\` as a hypothesis until the reproduction proves it.\n`,\n};\n"]}