@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

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

@@ -12,9 +12,10 @@
  * describes. What stays is what `explain` does not say — how to opt a view in,
  * and that an untagged dynamic view is never graded at all.
  *
- * Same assembly contract as every section: ../../agents-md.ts concatenates with
- * NO join separator, so this string starts at the first character of its opening
- * line and ends with the newline that closes its last one.
+ * Same assembly contract as every part of the `loam-codes` page:
+ * ../../workflows/reference/codes.ts concatenates with NO join separator, so this
+ * string starts at the first character of its opening line and ends with
+ * the newline that closes its last one.
  */
 export const USECASE_VIEWS = `- Business use cases are \`dynamic view\`s, and \`loam validate --all\` grades the
   ones that opt in. Write the flow in a file of its own —
@@ -23,21 +24,93 @@ 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). ANY 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
+  rather than silence; so is a view carrying only \`#suite-<name>\` (below). An
+  UNTAGGED dynamic view is somebody's hand-drawn diagram
   and is never graded — that opt-in is what lets a fleet full of existing
   diagrams upgrade without turning red, and \`loam validate\`, \`loam diff\`,
-  \`loam delta\`, \`loam status\`, \`loam context\` and \`loam list capabilities\` all
+  \`loam delta\`, \`loam status\`, \`loam context\`, \`loam list capabilities\` and
+  \`loam list suites\` all
   read the same opt-in, so a flow one of them sees is a flow all of them see. On a tagged
   view: \`usecase.capability-unresolved\`, \`usecase.step-unbacked\`,
   \`usecase.step-contested\` and \`usecase.step-unlinked\`. The first is silent
   while architecture/capabilities.yaml is absent or unreadable, like the rest of
   the capability axis; the three step codes are about the model, and a return
   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.
+  that way rather than as fresh hops. Where the map joins one pair by several
+  edges naming different operations, open the step's title with the operation id
+  the hop means and then punctuation —
+  \`orders -> payments 'authorizePayment — authorizes the payment'\`
+  (or the message it publishes or consumes) — or the hop stays
+  \`usecase.step-contested\`: loam never picks one for you. Every message names
+  the file the view was written in, never the landscape.
+- A fleet flow says which test SUITES it runs in with \`#suite-<name>\` tags —
+  a separate prefix from \`#cap-\`, many-to-many (one view may carry several),
+  each declared as a \`tag suite-<name>\` in the landscape's \`specification\` so a
+  typo is a parse error. Tagging is the opt-in: a view carrying ONLY \`#suite-\`
+  tags is a use case and its hops are graded like any other's. To answer "which
+  services must be up for suite X", run \`loam list suites smoke --json\` (or
+  \`loam list suites --json\` for every suite): \`suites[]\` carries each suite's
+  \`views[]\` (\`id\`, \`file\`), \`services[]\` (enumerated service ids, through the
+  same element→service join the step grades use) and \`unresolved[]\` (\`element\`,
+  \`external\`) — participants no service stands for, never dropped, so a stand
+  that needs a double for them says so; \`ungrouped[]\` names the use cases in no
+  suite, and \`useCases.state\` is \`absent\`, \`ok\` or \`unreadable\` (with
+  \`error\`; \`suites\`/\`ungrouped\` are then absent, not empty). An unknown suite
+  name refuses \`unknown-target\` with close names. Only the fleet map's flows
+  are listed.
+- 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 that MODIFIES a requirement a LIVING flow claims — an \`architecture/\`
+  flow's \`#req-\` tag on a capability requirement, or a service-local flow's on
+  that service's own — gets \`usecase.requirement-modified\` (warn, never gates)
+  wherever the feature is graded (\`loam validate --feature\`, \`--all\` per active
+  feature, \`loam status <FEAT>\`, the archive): the tag still resolves after
+  the merge, so nothing else would say the drawing now answers to new words.
+  Read the flow against the replacement and redraw it in the same change if it
+  no longer keeps the promise. A feature that REMOVES such a requirement gets
+  \`usecase.requirement-unresolved\` (error, gates, \`--approve\`-overridable) in
+  the same places, naming the living flow: the tag will resolve to nothing, and
+  \`validate --all\` would report exactly that after the archive. Drop the tag in
+  the same change, or MODIFY the requirement instead. A MODIFIED gets the same
+  error, not the warning, when an id the feature adds flattens to that tag.
 - 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 +125,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;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqH5B,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 part of the `loam-codes` page:\n * ../../workflows/reference/codes.ts concatenates with NO join separator, so this\n * string starts at the first character of its opening line and ends with\n * 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). ANY 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; so is a view carrying only \\`#suite-<name>\\` (below). An\n  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\\`, \\`loam list capabilities\\` and\n  \\`loam list suites\\` 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. Where the map joins one pair by several\n  edges naming different operations, open the step's title with the operation id\n  the hop means and then punctuation —\n  \\`orders -> payments 'authorizePayment — authorizes the payment'\\`\n  (or the message it publishes or consumes) — or the hop stays\n  \\`usecase.step-contested\\`: loam never picks one for you. Every message names\n  the file the view was written in, never the landscape.\n- A fleet flow says which test SUITES it runs in with \\`#suite-<name>\\` tags —\n  a separate prefix from \\`#cap-\\`, many-to-many (one view may carry several),\n  each declared as a \\`tag suite-<name>\\` in the landscape's \\`specification\\` so a\n  typo is a parse error. Tagging is the opt-in: a view carrying ONLY \\`#suite-\\`\n  tags is a use case and its hops are graded like any other's. To answer \"which\n  services must be up for suite X\", run \\`loam list suites smoke --json\\` (or\n  \\`loam list suites --json\\` for every suite): \\`suites[]\\` carries each suite's\n  \\`views[]\\` (\\`id\\`, \\`file\\`), \\`services[]\\` (enumerated service ids, through the\n  same element→service join the step grades use) and \\`unresolved[]\\` (\\`element\\`,\n  \\`external\\`) — participants no service stands for, never dropped, so a stand\n  that needs a double for them says so; \\`ungrouped[]\\` names the use cases in no\n  suite, and \\`useCases.state\\` is \\`absent\\`, \\`ok\\` or \\`unreadable\\` (with\n  \\`error\\`; \\`suites\\`/\\`ungrouped\\` are then absent, not empty). An unknown suite\n  name refuses \\`unknown-target\\` with close names. Only the fleet map's flows\n  are listed.\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 that MODIFIES a requirement a LIVING flow claims — an \\`architecture/\\`\n  flow's \\`#req-\\` tag on a capability requirement, or a service-local flow's on\n  that service's own — gets \\`usecase.requirement-modified\\` (warn, never gates)\n  wherever the feature is graded (\\`loam validate --feature\\`, \\`--all\\` per active\n  feature, \\`loam status <FEAT>\\`, the archive): the tag still resolves after\n  the merge, so nothing else would say the drawing now answers to new words.\n  Read the flow against the replacement and redraw it in the same change if it\n  no longer keeps the promise. A feature that REMOVES such a requirement gets\n  \\`usecase.requirement-unresolved\\` (error, gates, \\`--approve\\`-overridable) in\n  the same places, naming the living flow: the tag will resolve to nothing, and\n  \\`validate --all\\` would report exactly that after the archive. Drop the tag in\n  the same change, or MODIFY the requirement instead. A MODIFIED gets the same\n  error, not the warning, when an id the feature adds flattens to that tag.\n- A FEATURE brings a flow the way it brings every other axis: write it at\n  \\`features/<FEAT>/usecases/<name>.likec4\\` — the same views-only document, in the\n  feature's own directory — and \\`loam archive\\` copies it into\n  \\`architecture/usecases/\\` while \\`loam unarchive\\` takes it back. That is what lets\n  an analyst add a cross-service requirement and an architect answer it with the\n  flow that keeps it IN ONE CHANGE: the \\`#req-\\` tag resolves against this\n  feature's own \\`capabilities/<cap>/spec.md\\` delta as well as the living tree, and\n  \\`capability.uncovered\\` counts the flow as cover. The flow is graded against the\n  map the same merge would leave behind, so a hop may name a service this\n  feature's \\`delta.likec4\\` adds. Two refusals guard it, and \\`--approve\\` moves\n  neither: \\`usecase.flow-exists\\` (the living \\`architecture/usecases/\\` already has\n  that file — the merge is a whole-file copy, so edit the living one directly\n  instead) and \\`usecase.flow-invalid\\` (loam could not read the flows against that\n  post-merge map — most often a hop naming an element neither the living\n  landscape nor the delta declares; the merge preview stages no service model, so\n  a container an extending model declares is not among them either). Do NOT put a\n  \\`dynamic view\\` inside\n  \\`delta.likec4\\`: that document re-declares the landscape's own identifiers and\n  carries its own \\`specification\\` block, so it cannot be read beside the map, and\n  the archive refuses it by name. A feature's \\`delta.likec4\\` keeps that shape\n  whatever shape the service models take — \\`features/**\\` stays excluded from the\n  root LikeC4 project, and the delta is pointed at alone\n  (\\`npx likec4 start features/<FEAT>\\`).\n`;\n"]}

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

@@ -1,9 +1,13 @@
 /**
  * What loam REFUSES: the OpenSpec migration surface, the containment and
  * unreadable-file findings, and the error-envelope codes. What happens to a
- * SHIPPED change — the archive gate, unarchive, and dropping a feature — is
- * the continuation section in ./shipped/archive-gate.ts, split there because
- * the two subjects had grown past one file's ceiling.
+ * SHIPPED change — the archive gate, unarchive, and dropping a feature — used
+ * to be a continuation section beside this one, split off when the two
+ * subjects had grown past one file's ceiling. Nothing assembled it into
+ * anything loam shipped once AGENTS.md became ../agents-md.ts's ORIENTATION,
+ * and it was deleted: that teaching is the `loam-ship` protocol
+ * (../workflows/closing.ts) and ORIENTATION's own "Reading loam's output" and
+ * "Safety and hand-back" sections.
  *
  * Codes here are LISTED by the command that raises them, not glossed; the
  * meanings come from `loam explain <code>`, out of the running binary. See
@@ -20,11 +24,11 @@
  * resolve, so a family can never quietly lose its gloss and its explanation
  * at once.
  *
- * One section of the AGENTS.md template. ../agents-md.ts assembles the
- * document by PLAIN CONCATENATION — no join separator — so every section
- * starts at the first character of its opening line and ends with the newline
- * that closes its last one. Keep that shape when editing, or two sections glue
- * onto one line in every docs repo loam scaffolds from now on.
+ * The last part of the `loam-codes` page, not a section of AGENTS.md any more:
+ * ../workflows/reference/codes.ts assembles that page by PLAIN CONCATENATION —
+ * no join separator — so this string starts at the first character of its
+ * opening line and ends with the newline that closes its last one. Keep that
+ * shape when editing, or two parts glue onto one line on the printed page.
  */
 export const REFUSALS = `- \`loam audit-openspec <root>\` is the read-only OpenSpec inventory; an explicit
   \`--write-mapping\` writes a non-overwriting, digest-bound decision skeleton
@@ -90,7 +94,9 @@ export const REFUSALS = `- \`loam audit-openspec <root>\` is the read-only OpenS
   \`services-missing\`.
 - Both modes read frontmatter (\`frontmatter.missing\`, \`frontmatter.malformed\`,
   \`frontmatter.field-mismatch\`,
-  \`frontmatter.status-unknown\`, \`frontmatter.field-missing\`); a service's spec.md —
+  \`frontmatter.status-unknown\`, \`frontmatter.field-missing\`, and
+  \`frontmatter.owner-mismatch\` when one service's spec.md and arch.spec.md name two
+  different owners); a service's spec.md —
   and its arch.spec.md, same conventions — additionally carries the sources chain
   (\`sources.absent\`, \`sources.path-missing\`, \`sources.empty\`, \`sources.skipped\`,
   \`sources.unvouched\`, \`sources.stale\`) plus the two doc-side checks,
@@ -103,15 +109,20 @@ export const REFUSALS = `- \`loam audit-openspec <root>\` is the read-only OpenS
   \`evidence.token-missing\` and \`evidence.record-unreadable\` the warnings.
   Demote-only, by doctrine: a warn here is a reading priority for a reviewer,
   never a verdict change — no pin state moves \`attested\` or \`verified\` in
-  either direction. From the docs repo the family is silent;
-  \`sources.unverifiable-from-here\` already names that blind spot.
+  either direction. From the docs repo the service target's family is silent;
+  \`sources.unverifiable-from-here\` already names that blind spot. The record
+  itself lives in the docs repo, so the FEATURE target (\`--feature\`, and every
+  active feature under \`--all\`) raises \`evidence.record-unreadable\` from
+  anywhere — the same warn, about readability only.
 - \`loam archive\` alone reports the breaches only the merge computation can see:
   \`living.requirement-outside-requirements\`, \`openapi.op-modified\`,
   \`openapi.path-item-modified\`, \`openapi.component-modified\`,
   \`openapi.ref-unresolved\`, \`openapi.remove-marker-path-level\`, the event
   axis's own trio \`asyncapi.message-modified\` / \`asyncapi.channel-modified\` /
   \`asyncapi.operation-modified\`, \`asyncapi.ref-unresolved\`,
-  \`asyncapi.remove-marker-inline\` and \`service.no-model\`. Two of those are
+  \`asyncapi.remove-marker-inline\`, \`openapi.info-not-merged\` /
+  \`asyncapi.info-not-merged\` (the delta spells an \`info\` key the merge never
+  carries) and \`service.no-model\`. Two of those are
   graded at validate time as well and are STRICTER here —
   \`openapi.ref-unresolved\` and \`asyncapi.ref-unresolved\` are warnings there and
   errors here, because the merged document is what would carry the dangling
@@ -126,6 +137,15 @@ silent precedence rule is a report about a target nobody asked for. The
 positional together with \`--all\`, \`--service\` or \`--feature\` is refused
 (\`invalid-option\`).
 
+A bare \`loam validate\` grades the service \`loam.json\` binds — unless no
+\`services/<id>/\` holds it and an active feature introduces it, which is the
+state of every new service's repository until that feature archives. There is
+no service to grade then: the run validates each introducing feature instead
+(the grade \`--feature\` gives, target for target), says so above the report,
+and \`--json\` carries \`boundService\` — \`{ id, living: false, introducedBy }\`.
+Naming the service, with \`--service <id>\` or the positional, still reads a
+service: that is \`service.unknown\`, and its message names the feature.
+
 Two rendering levers change nothing else: \`loam validate --errors-only\` drops
 the confirmations from the TEXT view (the \`--json\` payload is byte-identical),
 and \`loam list --needs-work\` narrows the service list to the ones with
@@ -159,8 +179,9 @@ filtered-and-ordered row order, \`unowned[]\` listing the rows no rule matched,
 worklists. A CODEOWNERS path that cannot be read, or a line that cannot be
 parsed as \`pattern owner…\`, refuses \`owners-unreadable\` naming the path and
 line — fail-closed, exactly as \`answers-unreadable\` treats the other
-user-named file. Either flag with the \`features\` or \`capabilities\` section
-is refused (\`invalid-option\`).
+user-named file. Either flag with the \`features\`, \`capabilities\`, \`glossary\`
+or \`suites\` section is refused (\`invalid-option\`), as is \`--needs-work\` with
+\`features\` or \`suites\`, and a \`[name]\` after any section but \`suites\`.
 
 \`--strict\` (every targeting mode, \`--all\` included) exits 1 when any error
 or warning exists — \`ok\`-severity findings are confirmations and never trip
@@ -221,15 +242,20 @@ follows is the other half — which command raises which:
 - \`loam verify --record\` / \`--results\` / \`--contract-results\`:
   \`answers-unreadable\`, \`answers-mismatch\`, \`answers-unevidenced\`,
   \`record-federated\`, \`record-unreadable\` and \`record-raced\`. Two records for
-  different services land in either order — the later one waits, then merges,
-  and both attestations survive.
+  different services land in either order — each writes only its own
+  \`verification/<svc>.yaml\`, so both attestations survive, on one checkout or
+  on two docs-repo branches merged later. A \`record-unreadable\` names the file
+  that failed and its safe repair; never delete the one-file
+  \`verification.yaml\`, which may hold other services' attestations.
 - \`loam open\`: \`no-members\`, \`binding-duplicate\`, \`already-exists\` (the
   workspace file, which loam never silently overwrites — pass \`--out\` or
   \`--force\`) and \`invalid-option\`.
 - \`loam seed --from fleet.yaml\`: \`seed-file-invalid\`, \`seed-duplicate-service\`,
-  \`seed-unknown-subsystem\`, \`seed-landscape-edited\`, and \`unknown-service\` for a
-  call endpoint nothing declares. An existing service directory is never moved,
-  and nothing is ever deleted.
+  \`seed-unknown-subsystem\`, \`seed-landscape-edited\`, \`already-exists\` when a
+  generated views file in \`architecture/\` was written by somebody rather than by
+  loam (no \`// generated by loam\` first line — seed writes nothing at all in that
+  case), and \`unknown-service\` for a call endpoint nothing declares. An existing
+  service directory is never moved, and nothing is ever deleted.
 - \`internal\` — an unexpected throw, the one code with no stable meaning.
 
 \`--all\` reports a target per service, a target per feature in flight, and one target
@@ -240,7 +266,8 @@ Three different words for three different questions, and no command conflates th
 somebody says the code was built and showed evidence (\`verify\`). A feature can be
 valid and unverified, or verified and incoherent. Read the one you meant.
 `;
-/* The archive gate, unarchive, and dropping a feature continue in
- * ./shipped/archive-gate.ts — one document section split at its own subject
- * seam, concatenated after this one by ../agents-md.ts. */
+/* The archive gate, unarchive, and dropping a feature are not continued here:
+ * the section that once followed this one was never assembled again after
+ * AGENTS.md became ORIENTATION, and was deleted — see this file's header for
+ * where that teaching ships now. */
 //# sourceMappingURL=refusals.js.map

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

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

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

@@ -18,10 +18,29 @@ loam has no server or database. Delete it and the documents still make sense.
 
 \`architecture/landscape.likec4\` is the fleet map, and
 \`architecture/adrs/\` optional system-level decisions — only their links are graded.
+\`architecture/subsystems.likec4\` and \`architecture/services.likec4\` are both
+GENERATED by \`loam subsystem sync\` — one view per subsystem from the directory
+tree under \`services/\`, and one overview view per service the fleet map draws.
+Scoping aids, never hand-edited and never a second fleet map; each is stale
+(\`subsystem.views-stale\`, one finding per file) until the next \`sync\`. Their one
+styling opt-in is a \`global { styleGroup subsystems { … } }\` — or
+\`styleGroup services\` — declared in any \`.likec4\` under \`architecture/\`, which
+\`sync\` then references. A diagram you author belongs in the landscape or in a
+file of your own name beside it; an authored view \`of\` an element the generated
+file also draws is legal, and the file that sorts first wins the default
+drill-down target while both stay reachable.
 \`services/<id>/\` holds a boundary's living \`model.likec4\`, \`spec.md\`,
-\`arch.spec.md\`, OpenAPI, AsyncAPI, runbook and health facts.
+\`arch.spec.md\`, OpenAPI, AsyncAPI, runbook and health facts — and
+\`services/<…>/<id>/usecases/*.likec4\`, the slot for a \`dynamic view\` over that
+service's OWN containers, tagged \`#req-<Requirement-ID>\`; a flow that crosses
+services lives in \`architecture/usecases/\` and is tagged \`#cap-\` instead. Title
+a service use case \`'<subsystem path> / <service id> / <use case>'\` — LikeC4
+splits a view title on \`/\` into browser folders, so that convention lands the
+flow in the same folder as the generated overview of its service. Nothing grades
+the title, and nothing grades the slot's absence: presence is never owed.
 \`features/<FEAT>/\` holds a change in flight: \`intent.md\`, \`delta.likec4\`,
-per-service requirement and contract deltas, and \`verification.yaml\`.
+per-service requirement and contract deltas, and the verification record —
+\`verification/<svc>.yaml\`, one file per attesting service.
 \`features/archive/\` is shipped history.
 
 Living documents are the complete current state. A feature document is a diff
@@ -74,15 +93,24 @@ 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
 
 0. **Wire the repo** — in each service checkout run
-   \`loam init --docs <path-to-docs-repo> --service <id>\`, then \`loam doctor\`.
+   \`loam init --docs <path-to-docs-repo> --service <id> --agent-profile service\`,
+   then \`loam doctor\`. The service profile writes the five workflows that run
+   beside the code; \`loam-feature\` and \`loam-ship\` stay in the docs repo.
 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.
+   Give each edge a direction only from evidence, and draw it as \`connects\` where
+   there is none.
 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\`
@@ -98,7 +126,10 @@ writer or uploading anything. This is support, not a seventh lifecycle step.
    \`loam validate <FEAT> --json\`, and use \`loam explain <code>\` for reported
    codes. \`loam dependencies --json\` names features that must archive first.
 6. **Build** — load \`loam instructions loam-implement <FEAT>\`.
-   \`loam delta <FEAT> --service <id> --json\` is one service's task; in that
+   \`loam delta <FEAT> --service <id> --json\` is one service's task;
+   \`loam tasks <FEAT> --service <id> --next --json\` is the next open unit of it —
+   its \`at\` says whether you owe a scenario, a generated suite or code, and
+   \`done.check\` is the fact that closes it. In that
    service checkout, \`loam gherkin <FEAT>\` emits its executable scenarios.
 7. **Verify** — \`loam verify <FEAT> --json\` is the checklist. Record evidence
    from each affected service's own checkout. Read
@@ -147,6 +178,8 @@ a join.
 - \`loam instructions loam-authoring\` — arch requirements, generated Gherkin
   and frontmatter/vouch grammar.
 - \`loam instructions loam-done-check\` — verification evidence and verdicts.
+- \`loam instructions loam-drawing\` — relationship kinds and arrow direction, the
+  legend, and overview views a person can read. Read it before drawing an edge.
 
 Bare \`loam instructions\` lists the six workflows, the separate \`loam-report\`
 support protocol and these references. Generated agent command/skill files are

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6JnB,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\\`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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8LnB,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,eAAe,CAAC,YAAY,CAAC,KAAK,WAAW,EAAE,CAAC","sourcesContent":["/**\n * The small, always-loaded orientation contract for a loam docs repository.\n *\n * Detailed grammars and workflows live behind `loam instructions`: those pages\n * describe the binary that is about to run, while this file is written once and\n * may be loaded into every agent turn for years. Keep only enough here to form\n * the next question, find the relevant page, and avoid an unsafe write.\n */\nimport { agentsStampLine } from \"./agents-stamp.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\n\nconst ORIENTATION = `# Working in this docs repo\n\nThis is a **loam** docs repo: plain files are the shared source of truth for a governed software\nfleet's architecture, requirements, contracts and verification evidence. A service may be a modular monolith, a network service, a CLI or a worker.\nloam has no server or database. Delete it and the documents still make sense.\n\n## What is where\n\n\\`architecture/landscape.likec4\\` is the fleet map, and\n\\`architecture/adrs/\\` optional system-level decisions — only their links are graded.\n\\`architecture/subsystems.likec4\\` and \\`architecture/services.likec4\\` are both\nGENERATED by \\`loam subsystem sync\\` — one view per subsystem from the directory\ntree under \\`services/\\`, and one overview view per service the fleet map draws.\nScoping aids, never hand-edited and never a second fleet map; each is stale\n(\\`subsystem.views-stale\\`, one finding per file) until the next \\`sync\\`. Their one\nstyling opt-in is a \\`global { styleGroup subsystems { … } }\\` — or\n\\`styleGroup services\\` — declared in any \\`.likec4\\` under \\`architecture/\\`, which\n\\`sync\\` then references. A diagram you author belongs in the landscape or in a\nfile of your own name beside it; an authored view \\`of\\` an element the generated\nfile also draws is legal, and the file that sorts first wins the default\ndrill-down target while both stay reachable.\n\\`services/<id>/\\` holds a boundary's living \\`model.likec4\\`, \\`spec.md\\`,\n\\`arch.spec.md\\`, OpenAPI, AsyncAPI, runbook and health facts — and\n\\`services/<…>/<id>/usecases/*.likec4\\`, the slot for a \\`dynamic view\\` over that\nservice's OWN containers, tagged \\`#req-<Requirement-ID>\\`; a flow that crosses\nservices lives in \\`architecture/usecases/\\` and is tagged \\`#cap-\\` instead. Title\na service use case \\`'<subsystem path> / <service id> / <use case>'\\` — LikeC4\nsplits a view title on \\`/\\` into browser folders, so that convention lands the\nflow in the same folder as the generated overview of its service. Nothing grades\nthe title, and nothing grades the slot's absence: presence is never owed.\n\\`features/<FEAT>/\\` holds a change in flight: \\`intent.md\\`, \\`delta.likec4\\`,\nper-service requirement and contract deltas, and the verification record —\n\\`verification/<svc>.yaml\\`, one file per attesting service.\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> --agent-profile service\\`,\n   then \\`loam doctor\\`. The service profile writes the five workflows that run\n   beside the code; \\`loam-feature\\` and \\`loam-ship\\` stay in the docs repo.\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.\n   Give each edge a direction only from evidence, and draw it as \\`connects\\` where\n   there is none.\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;\n   \\`loam tasks <FEAT> --service <id> --next --json\\` is the next open unit of it —\n   its \\`at\\` says whether you owe a scenario, a generated suite or code, and\n   \\`done.check\\` is the fact that closes it. 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- \\`loam instructions loam-drawing\\` — relationship kinds and arrow direction, the\n  legend, and overview views a person can read. Read it before drawing an edge.\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/agents-stamp.js

@@ -4,6 +4,16 @@ export function agentsStampLine(version) {
 }
 /** Matches a stamp line anywhere in the file; the capture is the version text. */
 const STAMP_RE = /<!--\s*generated by loam v(\S+?)\s*-->/;
+/**
+ * `text` with its stamp, when it has one, rewritten to name `version` — every
+ * other byte untouched. What lets a caller ask whether a generated file differs
+ * from what a binary would write in anything BUT the stamp: the pointer files
+ * carry this same line, and a release that changes nothing in their body still
+ * changes it.
+ */
+export function restamped(text, version) {
+    return text.replace(STAMP_RE, agentsStampLine(version));
+}
 /**
  * The version the stamp names, or null when there is no stamp (or one whose
  * version does not read as numbers — unparseable is indistinguishable from