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

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

@@ -25,22 +25,62 @@ export const SUBSYSTEM_COMMANDS = `- \`loam subsystem <verb>\` manages the group
   \`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.views-stale\`, and 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\`. 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
   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 the file stale until the next \`sync\`. The
+  generated file is NEVER 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 it, by byte comparison.
+  Each 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.
+  \`sync\` refuses to rewrite it at all while \`architecture/\` does not parse
+  (\`action: "blocked"\`): fix the map first. It is 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
   service's baseline directly into a group, so adoption need not land unfiled.

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EjC,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 maintains the RENDERER's wiring for the\n  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\\`. 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\\`. The\n  generated file is NEVER 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 it, by byte comparison.\n  Each 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  \\`sync\\` refuses to rewrite it at all while \\`architecture/\\` does not parse\n  (\\`action: \"blocked\"\\`): fix the map first. 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"]}

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.js

@@ -20,10 +20,15 @@ loam has no server or database. Delete it and the documents still make sense.
 \`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
+hand-edited and never a second fleet map; its one styling opt-in is a
+\`global { styleGroup subsystems { … } }\` 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.
 \`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.
 \`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 +83,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 +94,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2KnB,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; its one styling opt-in is a\n\\`global { styleGroup subsystems { … } }\\` declared in any \\`.likec4\\` under\n\\`architecture/\\`, which \\`sync\\` then references. 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 — 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.\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"]}

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

@@ -10,7 +10,7 @@ export const LOAM_ADOPT = {
         "wire this repo (`loam init`, then `loam doctor`) if it has no ./loam.json yet",
         "`loam adopt` — the brief: the order to read the service in, every file to write, the grammar of each, and what the fleet map already says",
         "walk the service in the brief's order — shape first, then one surface at a time — keeping the list of every path you open, because that list becomes `sources`",
-        "write the artifacts, everything `status: draft`, then `loam subsystem sync` for the per-service LikeC4 project file — loam's, never yours",
+        "write the artifacts, everything `status: draft` — the model EXTENDS the fleet map — then `loam subsystem sync` for the renderer wiring, which is loam's and never yours",
         "validate the service, then validate the whole fleet — a baseline that passes one and fails the other is documented and invisible",
         "hand back with what you could not determine from the code, which directories you never opened, the branch-to-scenario count per operation, and three behaviours your documents do not describe — then let a human vouch",
     ],
@@ -43,6 +43,13 @@ thin baseline that validates is thin, not done.
      read it, diff your findings against it, report what disagrees. Do not replace it.
      \`action: "edit"\` appears on exactly one target — \`architecture/landscape.likec4\`,
      the WHOLE FLEET's map: add this service's element and edges to it, never rewrite it.
+     It appears while nothing resolves to the service AND while the element that does
+     has no edge touching it; \`targets[].shape\` says which of the two you are in.
+     It does NOT appear when loam could not READ the map (\`landscape.modelled: null\`
+     — a broken landscape, or a broken sibling under \`architecture/\`): nothing is
+     known about what the map already draws, so no write to the whole fleet's map is
+     briefed. \`landscape.instruction\` carries the answer and names the documents that
+     failed; fix those and re-run.
    - \`targets[].shape\` — the grammar of each artifact, and \`example\` where one is
      shorter than a description. Every rule there is one a later check depends on;
      rules nothing checks are in \`unchecked[]\` instead, and are still worth following.
@@ -50,7 +57,13 @@ thin baseline that validates is thin, not done.
      Bind to them; do not draw a second version of the same box. \`landscape.expects\`
      lists operations other services already call — your openapi.yaml owes them.
      \`landscape.instruction\` is the write the fleet map still owes this service; it
-     is \`null\` once an element resolves to it, and only then.
+     is \`null\` once an element resolves to it AND at least one edge ANYWHERE in the
+     \`architecture/\` project touches that element (\`landscape.touched\`), and only
+     then — one edge closes the state, so draw every call in one pass.
+     \`landscape.attested\` lists the
+     calls \`services/$1/model.likec4\` already declares across its boundary — those
+     are the edges the map owes, collapsed to the service; an empty list on a
+     service with no model is not licence to invent one, and the instruction says so.
    - \`frontmatter\` — what to put in the header of every markdown artifact.
    - \`checks[]\` — what \`loam validate\` will run. \`unchecked[]\` — what it will not.
 2. Read \`AGENTS.md\` at the docs repo root, then walk the service — \`walk[]\` in the
@@ -70,31 +83,127 @@ thin baseline that validates is thin, not done.
    tying the document to the repository. Never pad it with paths you did not read:
    it is a record, and \`loam vouch\` hashes exactly what it names.
 3. Write the artifacts under \`services/$1/\`, in the order the brief lists them, and
-   make the landscape edit the brief asks for. Then run \`loam subsystem sync\` (from
+   make the landscape edit the brief asks for — the element where none resolves, the
+   edges where the element stands alone, and the map's own housekeeping
+   \`unchecked[]\` names: a placeholder tag to clear, a curated view to add the
+   element to.
+   **model.likec4 EXTENDS the fleet map.** It declares no \`specification\` block and
+   no copy of anything the map already draws: its whole body is
+   \`model { extend <fqn> { …containers… } }\`, where \`<fqn>\` is the FULLY-QUALIFIED
+   id of the element bound to \`services/$1/\` (the brief's \`landscape.elements\` names
+   it; \`extend orderService\` resolves to nothing when the id is
+   \`marketplace.orderService\`). Kinds and tags come from
+   \`architecture/landscape.likec4\` — a kind you need and the map does not declare
+   (\`element database\`, \`element queue\`) is added THERE, once, in the same landscape
+   edit. Cross-boundary edges are written OUTSIDE the extend block, from the container
+   that makes the call to the other party's element as the map spells it; an element
+   this file declares outside its own is \`c4.element-unowned\` (warn), and which fix
+   applies depends on whose it is — a store or component this service OWNS belongs
+   INSIDE the \`extend\` block (its id becomes \`<fqn>.<name>\`), a system the service
+   merely reaches is declared in the map instead, and another service's internals
+   belong in that service's model. If you are DIFFING an existing model
+   that carries its own \`specification\`, leave it alone: that shape is still legal
+   and still parsed on its own, and \`c4.declaration-diverged\` is what reports where
+   its copies of the map's elements have drifted. Migrating one is the recipe in
+   SCHEMA.md, "Two shapes of a service model" — not something to do inside an
+   adoption you were not asked to widen.
+   A flow behind one of your arch.spec.md requirements — a \`dynamic view\`
+   over this service's own containers — goes in a \`.likec4\` beside model.likec4
+   (\`services/$1/usecases/<name>.likec4\` by convention; \`views.likec4\` reads the
+   same, because the renderer's per-service project reads every \`.likec4\` under the
+   directory and so does loam), tagged \`#req-<Requirement-ID>\` of a requirement in
+   this service's spec.md or arch.spec.md, with the tag declared in the map's
+   \`specification\` block or in a tags-only \`specification { tag req-… }\` beside the
+   \`extend\` — in exactly ONE of the two. Declared in both, the model's own project
+   holds the tag twice: the error lands on whichever document carries the second
+   declaration, as \`c4.invalid\` (an error, and the model's grading is suspended
+   behind it) when that is model.likec4, or as \`usecase.flow-invalid\` when it is the
+   sibling. Step 4 grades it. It never goes in \`architecture/usecases/\`,
+   which cannot see your containers and turns the whole fleet \`landscape.invalid\`; a
+   flow that crosses services goes there and is tagged \`#cap-\`. Never a \`#cap-\` tag
+   beside a model. Then run \`loam subsystem sync\` (from
    this repo or the docs repo — it resolves \`docsDir\`): once the docs root carries
-   the \`likec4.config.json\` step 0's doctor asks for, it writes
-   \`services/$1/likec4.config.json\` — and the same file beside any other service
-   model in the docs repo still missing one — the LikeC4 project that makes a
-   model.likec4 renderable beside the fleet map from the docs root. Those files are
-   loam's — never write one yourself, never list it in \`sources\`, never diff it —
-   and \`sync\` leaves them untracked for you to commit.
+   the \`likec4.config.json\` step 0's doctor asks for, it keeps that file's
+   \`exclude\` list covering exactly the service directories whose models stand alone —
+   so an extending model stays inside the root project, where it is the only place it
+   parses and where the renderer draws it beside the map — and writes
+   \`services/<…>/<id>/likec4.config.json\` beside each STANDALONE model that has none.
+   Both are loam's — never write one yourself, never list it in \`sources\`, never
+   diff it, never hand-edit the root \`exclude\`'s \`services/\` entries — and \`sync\`
+   leaves what it wrote untracked for you to commit. A repo whose models all extend
+   the map usually has nothing for \`sync\` to write here, and that is the healthy
+   state, not a skipped step.
    Everything \`status: draft\`. Never write \`last_verified\`, \`sources_digest\`,
    \`content_digest\` or \`sources_files\`.
-4. \`loam validate --service $1 --json\`. Fix every error. \`sources.unvouched\` is
+4. \`loam validate --service $1 --json\`. Fix every error. \`c4.valid\` reading
+   "extends the fleet map" is the confirmation that the model was read as one
+   document with the map; \`c4.invalid\` on this run means the model plus the map do
+   not parse together, and every error is YOURS even where the message names
+   \`architecture/landscape.likec4\` — the map parses clean on its own, or
+   \`spine.landscape-invalid\` would say so instead and this model could not be read
+   at all. \`c4.element-unowned\` (warn) is an element you declared outside the
+   element you extend — nest it inside the \`extend\` block if this service owns it,
+   declare it in the map if the service only reaches it. \`sources.unvouched\` is
    expected on a fresh baseline — it closes when a person vouches, not when you do.
    \`sources.unwalked\` is the walk graded against the repository: its \`details\` name
    the top-level paths git tracks and \`sources\` never reached into. Treat each one
    as a place to go back to, not as a line to silence — the fix is reading it, or
    one sentence in step 6 saying why this document does not owe it.
+   \`usecase.*\` findings on this run are about the flows beside model.likec4:
+   \`usecase.step-unbacked\` is a hop no relationship in model.likec4 backs,
+   \`usecase.step-contested\` two edges backing one hop and naming different
+   operations, \`usecase.requirement-unresolved\` a \`#req-\` tag naming no
+   \`Requirement-ID:\` of this service's spec.md or arch.spec.md,
+   \`usecase.capability-unresolved\` a \`#cap-\` tag beside a model (drop it — a
+   capability is claimed on the fleet map, never inside one service), and
+   \`usecase.flow-invalid\` a file beside the model that does not read — the flows
+   were not graded, the model still was. \`usecase.step-unlinked\` never fires on a hop
+   whose caller and provider resolve to the same service — a service owes no
+   operationId to itself — but a hop from such a flow into another service's element
+   (a stand-in model.likec4 declares for a sibling, with no \`metadata { op }\`) still
+   warns here, exactly as it does on the fleet map.
 5. \`loam validate --all --json\` in the docs repo. This is the run that grades the
    fleet map: \`landscape.service-unmodelled\` means the element never landed,
    \`landscape.binding-unknown\` / \`landscape.binding-duplicate\` mean it landed wrong,
    and \`landscape.missing\` means there is no map at all. A baseline that passes step 4
    and fails this one is documented and invisible.
-   \`service.likec4-config-missing\` (a warning) means step 3's sync did not run; the
-   fix is that command.
-   Done, stated once: step 4 clean when run from inside the service's own repo, and
-   this run reporting no \`landscape.*\` finding and no \`service.likec4-config-missing\`.
+   \`landscape.service-isolated\` (a warning) means the element landed with no edge
+   anywhere in \`architecture/\` while \`services/$1/model.likec4\` declares calls across
+   its boundary — the map owes those edges. It goes quiet on the FIRST edge, so draw
+   every call the brief listed in one pass: nothing will name the ones you leave out.
+   A service whose model declares no such call and whose element
+   has no edge is SILENT here: \`landscape.touched: false\` in step 1's brief is the
+   only place that state is named, so read it before this run rather than hoping
+   for it in it.
+   Six warnings on this run are about the RENDERER's wiring rather than about any
+   document, and one command fixes four of them: \`service.model-excluded\` (the root
+   \`likec4.config.json\` excludes a directory holding a model that extends the map, so
+   the renderer never loads it), \`service.model-unexcluded\` (its mirror, and the most
+   damaging — a model that STANDS ALONE whose directory the root \`exclude\` does not
+   cover merges into the root project and duplicates every kind the map declares,
+   which blanks the whole project rather than one service),
+   \`service.likec4-config-stray\` (a project file beside an extending model, which
+   claims the model out of the root project),
+   \`service.likec4-config-missing\` (a model that stands alone with no project file of
+   its own) and, when the first four are clear, \`c4.fleet-project-invalid\` — every
+   document reads clean where loam grades it and the ONE project the renderer builds
+   out of the map plus every extending model does not parse, because something is
+   declared in two of them. The first four: run \`loam subsystem sync\` — it rewrites
+   the root \`exclude\`, writes the missing project file and DELETES the stray one. The
+   fifth is an authoring fix: the message names the file and line, and the answer is
+   to declare the tag or element once, in the map or in the single service that owns it.
+   A sixth reads the same list and is NOT one of sync's: \`landscape.excluded\` says the
+   root \`exclude\` covers \`architecture/landscape.likec4\` itself, so the renderer has no
+   map to draw at all and every extending model in the root project resolves against
+   nothing — delete or narrow that entry by hand, at the line the finding quotes. While
+   it stands, \`c4.fleet-project-invalid\` is not graded at all: that check reads the
+   renderer's project, so the one entry would come back once per model instead of once as
+   the cause. Fix it first, then re-run and read the fifth.
+   Done, stated once: step 4 clean when run from inside the service's own repo, this
+   run reporting no \`landscape.*\` finding, no \`service.*\` renderer warning and no
+   \`c4.fleet-project-invalid\`, and
+   step 1's brief re-run reporting \`landscape.touched: true\` — or, for a service that
+   truly makes and receives no call, a stated reason its element is edgeless.
    The fleet run is never SILENT —
    \`sources.unverifiable-from-here\` (severity ok) appears per service as a
    confirmation, not work — so "keep going until validation is quiet" is the wrong