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

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

@@ -12,35 +12,48 @@
  * meaning, the severity and the fix. See ../../command-map.ts's header for why
  * the gloss left.
  *
- * 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 DIFF_COMMAND = `- \`loam diff --base <ref>\` reports the fleet-meaningful changes between the
   living docs and a base git ref of the DOCS repo (a branch, \`origin/main\`, a
   commit sha) — the review lens for a docs-repo PR. Read-only: the base state
   is read with read-only git questions (\`rev-parse\`/\`ls-tree\`/\`show\`), no
   checkout, nothing written. \`validate --all\` stays the fleet gate; diff says
-  what a branch CHANGES, and names who currently depends on every removal.
+  what a branch CHANGES, and names the authored consumers of every removal,
+  deprecation and modification.
   Codes, per service and grouped by the artifact they are computed over:
   \`diff.service-added\` and \`diff.service-removed\` over the \`services/<id>/\`
   directory; \`diff.requirement-added\`, \`diff.requirement-removed\` and
   \`diff.requirement-modified\` over spec.md's living requirements;
-  \`diff.op-added\`, \`diff.op-removed\`, \`diff.op-removed-consumed\` and
-  \`diff.op-deprecated\` over the OpenAPI contract; \`diff.message-added\`,
-  \`diff.message-removed\` and \`diff.message-removed-consumed\` over the AsyncAPI
-  contract; and \`diff.consumer-added\` / \`diff.consumer-removed\` over the
-  cross-service joins — another service's requirement naming this service's
-  operation or message. The two \`-consumed\` codes are the errors: they are the
-  removals something in the fleet still names, with the victims in
-  \`details[]\`. Exit 0 = diff computed, nothing breaking, everything readable;
-  exit 1 = a refusal, any error finding (\`breaking: true\` in \`--json\`), or a
-  subject whose artifact could not be read on either side — those axes are
-  SUSPENDED and reported (\`unreadable\` in the payload and the summary), never
-  graded as "nothing changed" or "everything added". Refusals reuse existing
-  codes: \`repository-unavailable\` when the docs repo has no git history to ask,
-  and \`unknown-target\` when \`--base\` resolves to no commit there. For the
-  byte-level OpenAPI breaking-change catalogue, run oasdiff on the two states
-  of one contract instead — loam deliberately does not reimplement it.
+  \`diff.op-added\`, \`diff.op-removed\`, \`diff.op-removed-consumed\`,
+  \`diff.op-deprecated\` and \`diff.op-modified\` over the OpenAPI contract;
+  \`diff.message-added\`, \`diff.message-removed\`,
+  \`diff.message-removed-consumed\` and \`diff.message-modified\` over the
+  AsyncAPI contract; and \`diff.consumer-added\` / \`diff.consumer-removed\`
+  over the cross-service joins — another service's requirement naming this
+  service's operation or message. The two \`-consumed\` codes are the errors:
+  they are the removals something in the fleet still names, with the victims
+  in \`details[]\` — the same consumers \`loam archive\` refuses a removal on
+  (edges of the \`architecture/\` project, both spec files, use-case hops; a
+  line naming its own service's operation of the same id is no victim). The two contract \`-modified\` codes are warnings whoever
+  is joined: the operation or message changed — its own node or anything its
+  \`$ref\`s reach — and \`details[]\` names who to check it against, but loam
+  does not grade whether the change breaks them. A landscape edge into the
+  provider drawn with no \`metadata { op }\` is listed as a consumer nobody
+  could check, never dropped. Exit 0 = diff computed, nothing breaking,
+  everything readable; exit 1 = a refusal, any error finding
+  (\`breaking: true\` in \`--json\`), or a subject whose artifact could not be
+  read on either side — those axes are SUSPENDED and reported (\`unreadable\`
+  in the payload and the summary), never graded as "nothing changed" or
+  "everything added". An unreadable openapi.yaml or asyncapi.yaml whose bytes
+  the base holds identically is skipped instead: the branch did not touch it.
+  Refusals reuse existing codes: \`repository-unavailable\`
+  when the docs repo has no git history to ask, and \`unknown-target\` when
+  \`--base\` resolves to no commit there. For the byte-level breaking-change
+  catalogue, run oasdiff (OpenAPI) or \`asyncapi diff\` (AsyncAPI) on the two
+  states of one contract instead — loam deliberately does not reimplement it.
 `;
 //# sourceMappingURL=diff.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../../../../src/core/agent/agents-md/map/lenses/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0B3B,CAAC","sourcesContent":["/**\n * The `loam diff` entry of the command map — the PR-review lens of this\n * package, split out for `./context.ts`'s exact reason: command-map.ts sat\n * against the file-line limit, so the branch-diff surface's documentation\n * lives down here and is concatenated after the map. It is also the\n * documentation home of the whole `diff.*` code vocabulary, which\n * codes-drift requires.\n *\n * The codes are grouped by the ARTIFACT they are computed over and not\n * glossed: that grouping is what nothing else says, while\n * `loam explain diff.op-removed-consumed` (and every sibling) carries the\n * meaning, the severity and the fix. See ../../command-map.ts's header for why\n * the gloss left.\n *\n * Same assembly contract as every section: ../../../agents-md.ts concatenates\n * with NO join separator, so this string starts at the first character of its\n * opening line and ends with the newline that closes its last one.\n */\nexport const DIFF_COMMAND = `- \\`loam diff --base <ref>\\` reports the fleet-meaningful changes between the\n  living docs and a base git ref of the DOCS repo (a branch, \\`origin/main\\`, a\n  commit sha) — the review lens for a docs-repo PR. Read-only: the base state\n  is read with read-only git questions (\\`rev-parse\\`/\\`ls-tree\\`/\\`show\\`), no\n  checkout, nothing written. \\`validate --all\\` stays the fleet gate; diff says\n  what a branch CHANGES, and names who currently depends on every removal.\n  Codes, per service and grouped by the artifact they are computed over:\n  \\`diff.service-added\\` and \\`diff.service-removed\\` over the \\`services/<id>/\\`\n  directory; \\`diff.requirement-added\\`, \\`diff.requirement-removed\\` and\n  \\`diff.requirement-modified\\` over spec.md's living requirements;\n  \\`diff.op-added\\`, \\`diff.op-removed\\`, \\`diff.op-removed-consumed\\` and\n  \\`diff.op-deprecated\\` over the OpenAPI contract; \\`diff.message-added\\`,\n  \\`diff.message-removed\\` and \\`diff.message-removed-consumed\\` over the AsyncAPI\n  contract; and \\`diff.consumer-added\\` / \\`diff.consumer-removed\\` over the\n  cross-service joins — another service's requirement naming this service's\n  operation or message. The two \\`-consumed\\` codes are the errors: they are the\n  removals something in the fleet still names, with the victims in\n  \\`details[]\\`. Exit 0 = diff computed, nothing breaking, everything readable;\n  exit 1 = a refusal, any error finding (\\`breaking: true\\` in \\`--json\\`), or a\n  subject whose artifact could not be read on either side — those axes are\n  SUSPENDED and reported (\\`unreadable\\` in the payload and the summary), never\n  graded as \"nothing changed\" or \"everything added\". Refusals reuse existing\n  codes: \\`repository-unavailable\\` when the docs repo has no git history to ask,\n  and \\`unknown-target\\` when \\`--base\\` resolves to no commit there. For the\n  byte-level OpenAPI breaking-change catalogue, run oasdiff on the two states\n  of one contract instead — loam deliberately does not reimplement it.\n`;\n"]}
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../../../../src/core/agent/agents-md/map/lenses/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsC3B,CAAC","sourcesContent":["/**\n * The `loam diff` entry of the command map — the PR-review lens of this\n * package, split out for `./context.ts`'s exact reason: command-map.ts sat\n * against the file-line limit, so the branch-diff surface's documentation\n * lives down here and is concatenated after the map. It is also the\n * documentation home of the whole `diff.*` code vocabulary, which\n * codes-drift requires.\n *\n * The codes are grouped by the ARTIFACT they are computed over and not\n * glossed: that grouping is what nothing else says, while\n * `loam explain diff.op-removed-consumed` (and every sibling) carries the\n * meaning, the severity and the fix. See ../../command-map.ts's header for why\n * the gloss left.\n *\n * Same assembly contract as every part of the `loam-codes` page:\n * ../../../workflows/reference/codes.ts concatenates with NO join separator,\n * so this string starts at the first character of its opening line and ends\n * with the newline that closes its last one.\n */\nexport const DIFF_COMMAND = `- \\`loam diff --base <ref>\\` reports the fleet-meaningful changes between the\n  living docs and a base git ref of the DOCS repo (a branch, \\`origin/main\\`, a\n  commit sha) — the review lens for a docs-repo PR. Read-only: the base state\n  is read with read-only git questions (\\`rev-parse\\`/\\`ls-tree\\`/\\`show\\`), no\n  checkout, nothing written. \\`validate --all\\` stays the fleet gate; diff says\n  what a branch CHANGES, and names the authored consumers of every removal,\n  deprecation and modification.\n  Codes, per service and grouped by the artifact they are computed over:\n  \\`diff.service-added\\` and \\`diff.service-removed\\` over the \\`services/<id>/\\`\n  directory; \\`diff.requirement-added\\`, \\`diff.requirement-removed\\` and\n  \\`diff.requirement-modified\\` over spec.md's living requirements;\n  \\`diff.op-added\\`, \\`diff.op-removed\\`, \\`diff.op-removed-consumed\\`,\n  \\`diff.op-deprecated\\` and \\`diff.op-modified\\` over the OpenAPI contract;\n  \\`diff.message-added\\`, \\`diff.message-removed\\`,\n  \\`diff.message-removed-consumed\\` and \\`diff.message-modified\\` over the\n  AsyncAPI contract; and \\`diff.consumer-added\\` / \\`diff.consumer-removed\\`\n  over the cross-service joins — another service's requirement naming this\n  service's operation or message. The two \\`-consumed\\` codes are the errors:\n  they are the removals something in the fleet still names, with the victims\n  in \\`details[]\\` — the same consumers \\`loam archive\\` refuses a removal on\n  (edges of the \\`architecture/\\` project, both spec files, use-case hops; a\n  line naming its own service's operation of the same id is no victim). The two contract \\`-modified\\` codes are warnings whoever\n  is joined: the operation or message changed — its own node or anything its\n  \\`$ref\\`s reach — and \\`details[]\\` names who to check it against, but loam\n  does not grade whether the change breaks them. A landscape edge into the\n  provider drawn with no \\`metadata { op }\\` is listed as a consumer nobody\n  could check, never dropped. Exit 0 = diff computed, nothing breaking,\n  everything readable; exit 1 = a refusal, any error finding\n  (\\`breaking: true\\` in \\`--json\\`), or a subject whose artifact could not be\n  read on either side — those axes are SUSPENDED and reported (\\`unreadable\\`\n  in the payload and the summary), never graded as \"nothing changed\" or\n  \"everything added\". An unreadable openapi.yaml or asyncapi.yaml whose bytes\n  the base holds identically is skipped instead: the branch did not touch it.\n  Refusals reuse existing codes: \\`repository-unavailable\\`\n  when the docs repo has no git history to ask, and \\`unknown-target\\` when\n  \\`--base\\` resolves to no commit there. For the byte-level breaking-change\n  catalogue, run oasdiff (OpenAPI) or \\`asyncapi diff\\` (AsyncAPI) on the two\n  states of one contract instead — loam deliberately does not reimplement it.\n`;\n"]}

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

@@ -11,11 +11,12 @@
  * the meaning, the conditional severity and the fix. See ../../command-map.ts's
  * header for why the gloss left.
  *
- * 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 GATE_COMMAND = `- \`loam gate [--service <id>]\` is the DEPLOY-pipeline question — can this
+export const GATE_COMMAND = `- \`loam gate [--service <id>] [--since <ref>]\` is the DEPLOY-pipeline question — can this
   service deploy, as far as recorded evidence can say — asked as a pure query:
   it executes nothing, writes nothing, takes no lock, and deliberately changes
   nothing about what gates \`loam archive\` (verify still never gates the
@@ -40,6 +41,12 @@ export const GATE_COMMAND = `- \`loam gate [--service <id>]\` is the DEPLOY-pipe
   \`verification\` covers every ACTIVE feature carrying a specs/ delta for the
   service, through the verification record's own verdicts:
   \`gate.feature-unverified\` and the reused \`verify.scenario-attested\`.
+  Without \`--since\` that is in-flight features only — a feature leaves the
+  check the moment it is archived. \`--since <ref>\` (a docs-repo git ref: the
+  docs commit the last deploy recorded) also grades every feature archived
+  after it, under the same codes, its \`features[]\` row carrying
+  \`archived: true\`; it reads git as \`loam diff --base <ref>\` does and refuses
+  the same way when git cannot answer.
   \`interrupted\` reuses \`docs.commit-interrupted\`: a \`.loam-commit\` journal
   means the docs may be half-written, so nothing graded from them describes one
   state. One unreadable sibling artifact degrades that ONE subject as
@@ -47,7 +54,8 @@ export const GATE_COMMAND = `- \`loam gate [--service <id>]\` is the DEPLOY-pipe
   Exit semantics are validate's: any error fails (exit 1, \`verdict: "fail"\`),
   warnings are advisory (exit 0, \`verdict: "pass"\`), and \`--strict\` is the CI
   lever that fails warnings too — the report and the \`--json\` payload do not
-  change under it. The payload carries \`landscape\`
+  change under it. The payload carries \`since\` (\`{ ref, commit }\` or
+  null), \`landscape\`
   (\`read\`/\`absent\`/\`invalid\`), \`partners[]\` (each with its maturity
   rung, role and joins), \`features[]\` (the per-record tallies) and
   \`checks[]\` (the findings, by check), so a pipeline that wants a stricter

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

@@ -1 +1 @@
-{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../../../../src/core/agent/agents-md/map/lenses/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsC3B,CAAC","sourcesContent":["/**\n * The `loam gate` entry of the command map — the deploy-pipeline lens of this\n * package, split out for `./context.ts`'s exact reason: command-map.ts sat\n * against the file-line limit, so the deploy gate's documentation lives down\n * here and is concatenated after the map. Its four `gate.*` codes are what\n * test/codes-drift.test.ts finds here.\n *\n * The codes are grouped by CHECK and not glossed: which check raises what is\n * the payload's own `checks[]` shape and is the unique thing this section\n * says, while `loam explain gate.partners-unknown` (and every sibling) carries\n * the meaning, the conditional severity and the fix. See ../../command-map.ts's\n * header for why the gloss left.\n *\n * Same assembly contract as every section: ../../../agents-md.ts concatenates\n * with NO join separator, so this string starts at the first character of its\n * opening line and ends with the newline that closes its last one.\n */\nexport const GATE_COMMAND = `- \\`loam gate [--service <id>]\\` is the DEPLOY-pipeline question — can this\n  service deploy, as far as recorded evidence can say — asked as a pure query:\n  it executes nothing, writes nothing, takes no lock, and deliberately changes\n  nothing about what gates \\`loam archive\\` (verify still never gates the\n  merge; gate's verdict is advice to a pipeline loam does not own). In a bound\n  service repo the invocation is literally \\`loam gate --json\\`; \\`--service\\`\n  names any other adopted service, and one nobody adopted refuses\n  \\`unknown-service\\` — recorded evidence cannot answer for it. Four checks, and\n  the code tells you which one spoke. \\`partners\\` derives the direct joins from\n  the LIVING landscape: \\`gate.service-undocumented\\`,\n  \\`gate.partner-undocumented\\` and \\`gate.partners-unknown\\` — the last one\n  severity-splits on why the map could not answer, so read\n  \\`loam explain gate.partners-unknown\\` before treating it as advisory. A\n  partner tagged \\`#external\\` is exempt from the middle one on purpose — its\n  docs are somebody else's — but an ADOPTED service is never exempt, whatever\n  zone the map draws it inside.\n  \\`freshness\\` re-reports two staleness findings \\`validate\\` already owns,\n  \\`content.stale\\` and \\`sources.stale\\`, over the gated service and its\n  documented partners, plus the one integrity error that makes freshness\n  unjudgeable, \\`frontmatter.malformed\\`; it decodes the spec bytes itself, so a\n  UTF-16 spec.md is a \\`service.unreadable\\` error naming the file, never a quiet\n  pass. The rest of provenance stays \\`validate\\`'s report to make.\n  \\`verification\\` covers every ACTIVE feature carrying a specs/ delta for the\n  service, through the verification record's own verdicts:\n  \\`gate.feature-unverified\\` and the reused \\`verify.scenario-attested\\`.\n  \\`interrupted\\` reuses \\`docs.commit-interrupted\\`: a \\`.loam-commit\\` journal\n  means the docs may be half-written, so nothing graded from them describes one\n  state. One unreadable sibling artifact degrades that ONE subject as\n  \\`service.unreadable\\` / \\`feature.unreadable\\` instead of killing the report.\n  Exit semantics are validate's: any error fails (exit 1, \\`verdict: \"fail\"\\`),\n  warnings are advisory (exit 0, \\`verdict: \"pass\"\\`), and \\`--strict\\` is the CI\n  lever that fails warnings too — the report and the \\`--json\\` payload do not\n  change under it. The payload carries \\`landscape\\`\n  (\\`read\\`/\\`absent\\`/\\`invalid\\`), \\`partners[]\\` (each with its maturity\n  rung, role and joins), \\`features[]\\` (the per-record tallies) and\n  \\`checks[]\\` (the findings, by check), so a pipeline that wants a stricter\n  bar — \\`vouched\\` partners, no attested scenarios — branches on the data\n  rather than waiting for a flag.\n`;\n"]}
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../../../../src/core/agent/agents-md/map/lenses/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6C3B,CAAC","sourcesContent":["/**\n * The `loam gate` entry of the command map — the deploy-pipeline lens of this\n * package, split out for `./context.ts`'s exact reason: command-map.ts sat\n * against the file-line limit, so the deploy gate's documentation lives down\n * here and is concatenated after the map. Its four `gate.*` codes are what\n * test/codes-drift.test.ts finds here.\n *\n * The codes are grouped by CHECK and not glossed: which check raises what is\n * the payload's own `checks[]` shape and is the unique thing this section\n * says, while `loam explain gate.partners-unknown` (and every sibling) carries\n * the meaning, the conditional severity and the fix. See ../../command-map.ts's\n * header for why the gloss left.\n *\n * Same assembly contract as every part of the `loam-codes` page:\n * ../../../workflows/reference/codes.ts concatenates with NO join separator,\n * so this string starts at the first character of its opening line and ends\n * with the newline that closes its last one.\n */\nexport const GATE_COMMAND = `- \\`loam gate [--service <id>] [--since <ref>]\\` is the DEPLOY-pipeline question — can this\n  service deploy, as far as recorded evidence can say — asked as a pure query:\n  it executes nothing, writes nothing, takes no lock, and deliberately changes\n  nothing about what gates \\`loam archive\\` (verify still never gates the\n  merge; gate's verdict is advice to a pipeline loam does not own). In a bound\n  service repo the invocation is literally \\`loam gate --json\\`; \\`--service\\`\n  names any other adopted service, and one nobody adopted refuses\n  \\`unknown-service\\` — recorded evidence cannot answer for it. Four checks, and\n  the code tells you which one spoke. \\`partners\\` derives the direct joins from\n  the LIVING landscape: \\`gate.service-undocumented\\`,\n  \\`gate.partner-undocumented\\` and \\`gate.partners-unknown\\` — the last one\n  severity-splits on why the map could not answer, so read\n  \\`loam explain gate.partners-unknown\\` before treating it as advisory. A\n  partner tagged \\`#external\\` is exempt from the middle one on purpose — its\n  docs are somebody else's — but an ADOPTED service is never exempt, whatever\n  zone the map draws it inside.\n  \\`freshness\\` re-reports two staleness findings \\`validate\\` already owns,\n  \\`content.stale\\` and \\`sources.stale\\`, over the gated service and its\n  documented partners, plus the one integrity error that makes freshness\n  unjudgeable, \\`frontmatter.malformed\\`; it decodes the spec bytes itself, so a\n  UTF-16 spec.md is a \\`service.unreadable\\` error naming the file, never a quiet\n  pass. The rest of provenance stays \\`validate\\`'s report to make.\n  \\`verification\\` covers every ACTIVE feature carrying a specs/ delta for the\n  service, through the verification record's own verdicts:\n  \\`gate.feature-unverified\\` and the reused \\`verify.scenario-attested\\`.\n  Without \\`--since\\` that is in-flight features only — a feature leaves the\n  check the moment it is archived. \\`--since <ref>\\` (a docs-repo git ref: the\n  docs commit the last deploy recorded) also grades every feature archived\n  after it, under the same codes, its \\`features[]\\` row carrying\n  \\`archived: true\\`; it reads git as \\`loam diff --base <ref>\\` does and refuses\n  the same way when git cannot answer.\n  \\`interrupted\\` reuses \\`docs.commit-interrupted\\`: a \\`.loam-commit\\` journal\n  means the docs may be half-written, so nothing graded from them describes one\n  state. One unreadable sibling artifact degrades that ONE subject as\n  \\`service.unreadable\\` / \\`feature.unreadable\\` instead of killing the report.\n  Exit semantics are validate's: any error fails (exit 1, \\`verdict: \"fail\"\\`),\n  warnings are advisory (exit 0, \\`verdict: \"pass\"\\`), and \\`--strict\\` is the CI\n  lever that fails warnings too — the report and the \\`--json\\` payload do not\n  change under it. The payload carries \\`since\\` (\\`{ ref, commit }\\` or\n  null), \\`landscape\\`\n  (\\`read\\`/\\`absent\\`/\\`invalid\\`), \\`partners[]\\` (each with its maturity\n  rung, role and joins), \\`features[]\\` (the per-record tallies) and\n  \\`checks[]\\` (the findings, by check), so a pipeline that wants a stricter\n  bar — \\`vouched\\` partners, no attested scenarios — branches on the data\n  rather than waiting for a flag.\n`;\n"]}

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

@@ -5,9 +5,10 @@
  * concatenated after the map. It introduces no codes of its own: every tool
  * result is an existing envelope, which is the point of the section.
  *
- * 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.
  *
  * The command names in the roster below are HAND-LISTED: importing
  * core/mcp/tools.ts from here would close a package cycle (tools.ts reads
@@ -15,9 +16,9 @@
  * sources). test/mcp-protocol.test.ts pins this string against MCP_TOOLS
  * instead: a tool added to the table without its name here fails there.
  */
-export const MCP_COMMAND = `- \`loam mcp\` serves the fourteen base read commands — validate, status, list, show,
-  delta, diff, explore, dependencies, doctor, context, gate, steps, explain,
-  instructions — as MCP tools over stdio (JSON-RPC 2.0), for hosts that reach
+export const MCP_COMMAND = `- \`loam mcp\` serves the sixteen base read commands — validate, status, list, show,
+  delta, tasks, diff, explore, dependencies, doctor, context, adopt, gate, steps,
+  explain, instructions — as MCP tools over stdio (JSON-RPC 2.0), for hosts that reach
   tools through MCP rather than a shell:
   configure the host to launch \`loam mcp\` in the repository the tools should
   answer for, or run \`loam init --mcp\` there and let it write the \`.mcp.json\`
@@ -33,7 +34,9 @@ export const MCP_COMMAND = `- \`loam mcp\` serves the fourteen base read command
   \`instructions\`, are served so an MCP-only host can reach them BEFORE this
   repository is wired: the first line of every generated skill is
   \`loam instructions <workflow>\`, and a host that could not run it could not
-  fetch the protocol its own skill points at. An explicit \`mcp --author\` adds
+  fetch the protocol its own skill points at. \`adopt\` is served because it
+  writes nothing: the loam-adopt protocol opens by running it, and its brief is
+  what the agent then writes from. An explicit \`mcp --author\` adds
   \`new\`, \`rebase\`, \`gherkin\` and an archive dry-run. It never exposes
   \`vouch\`, evidence recording or a committing archive; those stay in the CLI,
   where the permission flow is yours.

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

@@ -1 +1 @@
-{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsB1B,CAAC","sourcesContent":["/**\n * The `loam mcp` entry of the command map — its own section module for\n * `./lenses/gate.ts`'s exact reason: command-map.ts sat against the file-line limit,\n * so the MCP facade's documentation lives one package down and is\n * concatenated after the map. It introduces no codes of its own: every tool\n * result is an existing envelope, which is the point of the section.\n *\n * Same assembly contract as every section: ../../agents-md.ts concatenates\n * with NO join separator, so this string starts at the first character of its\n * opening line and ends with the newline that closes its last one.\n *\n * The command names in the roster below are HAND-LISTED: importing\n * core/mcp/tools.ts from here would close a package cycle (tools.ts reads\n * core/explain/terms.ts, which reads this package's siblings for its pin\n * sources). test/mcp-protocol.test.ts pins this string against MCP_TOOLS\n * instead: a tool added to the table without its name here fails there.\n */\nexport const MCP_COMMAND = `- \\`loam mcp\\` serves the fourteen base read commands — validate, status, list, show,\n  delta, diff, explore, dependencies, doctor, context, gate, steps, explain,\n  instructions — as MCP tools over stdio (JSON-RPC 2.0), for hosts that reach\n  tools through MCP rather than a shell:\n  configure the host to launch \\`loam mcp\\` in the repository the tools should\n  answer for, or run \\`loam init --mcp\\` there and let it write the \\`.mcp.json\\`\n  every host reads. Like every other file \\`init\\` lays down, an existing one is\n  reported and never merged into. Every tool result carries the same \\`--json\\` envelope the CLI\n  prints, verbatim, so everything above about codes and envelopes applies\n  unchanged — branch on \\`ok\\` and \\`error.code\\` exactly as you would reading\n  the command's stdout. The orientation and instruction pages are MCP resources,\n  and every tool declares the envelope output schema. Every base tool is advertised with\n  \\`annotations.readOnlyHint: true\\` — the machine signal a host needs to\n  approve a call without prompting, and the reason the table stays read-only\n  by construction. The two that read no config, \\`explain\\` and\n  \\`instructions\\`, are served so an MCP-only host can reach them BEFORE this\n  repository is wired: the first line of every generated skill is\n  \\`loam instructions <workflow>\\`, and a host that could not run it could not\n  fetch the protocol its own skill points at. An explicit \\`mcp --author\\` adds\n  \\`new\\`, \\`rebase\\`, \\`gherkin\\` and an archive dry-run. It never exposes\n  \\`vouch\\`, evidence recording or a committing archive; those stay in the CLI,\n  where the permission flow is yours.\n`;\n"]}
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;CAwB1B,CAAC","sourcesContent":["/**\n * The `loam mcp` entry of the command map — its own section module for\n * `./lenses/gate.ts`'s exact reason: command-map.ts sat against the file-line limit,\n * so the MCP facade's documentation lives one package down and is\n * concatenated after the map. It introduces no codes of its own: every tool\n * result is an existing envelope, which is the point of the section.\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 *\n * The command names in the roster below are HAND-LISTED: importing\n * core/mcp/tools.ts from here would close a package cycle (tools.ts reads\n * core/explain/terms.ts, which reads this package's siblings for its pin\n * sources). test/mcp-protocol.test.ts pins this string against MCP_TOOLS\n * instead: a tool added to the table without its name here fails there.\n */\nexport const MCP_COMMAND = `- \\`loam mcp\\` serves the sixteen base read commands — validate, status, list, show,\n  delta, tasks, diff, explore, dependencies, doctor, context, adopt, gate, steps,\n  explain, instructions — as MCP tools over stdio (JSON-RPC 2.0), for hosts that reach\n  tools through MCP rather than a shell:\n  configure the host to launch \\`loam mcp\\` in the repository the tools should\n  answer for, or run \\`loam init --mcp\\` there and let it write the \\`.mcp.json\\`\n  every host reads. Like every other file \\`init\\` lays down, an existing one is\n  reported and never merged into. Every tool result carries the same \\`--json\\` envelope the CLI\n  prints, verbatim, so everything above about codes and envelopes applies\n  unchanged — branch on \\`ok\\` and \\`error.code\\` exactly as you would reading\n  the command's stdout. The orientation and instruction pages are MCP resources,\n  and every tool declares the envelope output schema. Every base tool is advertised with\n  \\`annotations.readOnlyHint: true\\` — the machine signal a host needs to\n  approve a call without prompting, and the reason the table stays read-only\n  by construction. The two that read no config, \\`explain\\` and\n  \\`instructions\\`, are served so an MCP-only host can reach them BEFORE this\n  repository is wired: the first line of every generated skill is\n  \\`loam instructions <workflow>\\`, and a host that could not run it could not\n  fetch the protocol its own skill points at. \\`adopt\\` is served because it\n  writes nothing: the loam-adopt protocol opens by running it, and its brief is\n  what the agent then writes from. An explicit \\`mcp --author\\` adds\n  \\`new\\`, \\`rebase\\`, \\`gherkin\\` and an archive dry-run. It never exposes\n  \\`vouch\\`, evidence recording or a committing archive; those stay in the CLI,\n  where the permission flow is yours.\n`;\n"]}

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

@@ -35,7 +35,11 @@ export const STATUS_COMMAND = `- \`loam status [<FEAT>]\` is the orientation sur
   never elided: a \`.loam-commit\` journal says a writer was killed mid-commit, so
   some of the files everything else is derived from may be half-written.
   Fleet-wide the rest are \`next.adopt-bound\`, \`next.adopt\`,
-  \`next.complete-service\`, \`next.feature\`, \`next.archive\`, \`next.fleet-clean\`,
+  \`next.complete-service\`, \`next.revouch\` (a vouched document's words moved
+  under its stamp — \`content.stale\`; its \`execution\` is a human review, never
+  yours to run: prepare \`loam vouch --pack --service <id>\` and hand the vouch
+  to a person),
+  \`next.feature\`, \`next.archive\`, \`next.fleet-clean\`,
   \`next.elided\` (the fleet list hit its cap and says how many steps of the same
   kinds it left out — it is ordered most-unblocking first, so work down it and
   re-run) and \`next.fleet-gate\`, always last while anything is outstanding:
@@ -56,7 +60,9 @@ export const STATUS_COMMAND = `- \`loam status [<FEAT>]\` is the orientation sur
   so it may be more pessimistic than either and can never be greener than both.
   \`verification\` carries \`verdict\` (\`verified\` | \`attested\` | \`unverified\`)
   and \`attested\` (how many scenario claims rest on an agent's word) beside the
-  recounted totals, and \`checks.issues[]\` carries \`gates\` and \`details\` on every
-  finding.
+  recounted totals, plus \`answered\` (the confirmed claims per \`answered_by\`:
+  \`runner\`, \`external-runner\`, \`agent\` — a \`verified\` record can still rest
+  partly on an agent's word about kinds the verdict does not turn on), and
+  \`checks.issues[]\` carries \`gates\` and \`details\` on every finding.
 `;
 //# sourceMappingURL=status.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwC7B,CAAC","sourcesContent":["/**\n * The `loam status` entry of the command map — its own section module for\n * `./mcp.ts`'s exact reason: command-map.ts sat against the file-line limit,\n * so the orientation surface's documentation lives one package down. Unlike\n * its siblings it is not concatenated AFTER the map: status is deliberately\n * the map's FIRST bullet, so ../command-map.ts composes it into COMMAND_MAP\n * between the preamble and the validate entries. The `next.*` fleet and\n * feature codes are what test/codes-drift.test.ts finds here.\n *\n * The `next.*` codes are LISTED, not glossed: `loam explain next.adopt` (and\n * every sibling) answers what a step means and what to run, out of the binary\n * rather than out of this file. See ../command-map.ts's header for why the\n * gloss left. What survives here is what `explain` cannot say — that the list\n * splits fleet-wide from per-feature, and that `next.recover-commit` outranks\n * everything in both forms.\n *\n * Same assembly contract as every section: the composition concatenates with\n * NO join separator, so this string starts at the first character of its\n * opening line and ends with the newline that closes its last one.\n */\nexport const STATUS_COMMAND = `- \\`loam status [<FEAT>]\\` is the orientation surface — the question you have when\n  you join a repository halfway, or come back having lost the session, and the one\n  every other command assumed you could already answer. It writes nothing and\n  stores nothing: there is no state file, every answer is re-derived from the\n  files, so a document someone edited in another window is visible on the next run\n  with nothing to invalidate. Artifacts come back as \\`missing\\` (owed, nothing in\n  the way — write it now), \\`blocked\\` (not written and not writable yet; the entry\n  names what comes first), \\`draft\\` (on disk, and the shared checks report an error\n  against it — what exists is wrong), \\`ready\\` (on disk and clean, but something\n  outside the documents — code, a test run, a recording — still has to answer it)\n  or \\`done\\`. The payload's reason to exist is \\`next[]\\`: ordered, first entry\n  first, each carrying a code and the literal command to run — so a step needs no\n  gloss here, and \\`loam explain <code>\\` has the long form of any of them.\n  \\`next.recover-commit\\` outranks every other step in both forms below and is\n  never elided: a \\`.loam-commit\\` journal says a writer was killed mid-commit, so\n  some of the files everything else is derived from may be half-written.\n  Fleet-wide the rest are \\`next.adopt-bound\\`, \\`next.adopt\\`,\n  \\`next.complete-service\\`, \\`next.feature\\`, \\`next.archive\\`, \\`next.fleet-clean\\`,\n  \\`next.elided\\` (the fleet list hit its cap and says how many steps of the same\n  kinds it left out — it is ordered most-unblocking first, so work down it and\n  re-run) and \\`next.fleet-gate\\`, always last while anything is outstanding:\n  \\`loam validate --all\\` is what CI runs, and the fleet form grades nothing\n  itself. A docs repo with no services and no features instead gets the\n  first-hour ladder — \\`next.author-landscape\\`, \\`next.bind-service\\`,\n  \\`next.adopt-first\\` — which the \\`/loam-adopt\\` body walks.\n  On one feature: \\`next.author-intent\\`, \\`next.touch-service\\`,\n  \\`next.author-spec\\`, \\`next.author-openapi\\`, \\`next.author-scenarios\\`,\n  \\`next.rebase\\`, \\`next.archive-first\\`, \\`next.fix-coherence\\`,\n  \\`next.generate-tests\\`, \\`next.verify\\`, \\`next.verify-unconfirmed\\`,\n  \\`next.attest-service\\` (this repo IS one of the services that owes an answer,\n  so the step is bound to this commit), \\`next.verify-attested\\` — see\n  \"The done-check\" for what attested costs — \\`next.archive\\`, and\n  \\`next.archived\\` for one that shipped.\n  It grades nothing of its own: the verdict is the one \\`loam validate --feature\\`\n  and \\`loam archive\\` compute — status takes the UNION of what both of them refuse,\n  so it may be more pessimistic than either and can never be greener than both.\n  \\`verification\\` carries \\`verdict\\` (\\`verified\\` | \\`attested\\` | \\`unverified\\`)\n  and \\`attested\\` (how many scenario claims rest on an agent's word) beside the\n  recounted totals, and \\`checks.issues[]\\` carries \\`gates\\` and \\`details\\` on every\n  finding.\n`;\n"]}
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8C7B,CAAC","sourcesContent":["/**\n * The `loam status` entry of the command map — its own section module for\n * `./mcp.ts`'s exact reason: command-map.ts sat against the file-line limit,\n * so the orientation surface's documentation lives one package down. Unlike\n * its siblings it is not concatenated AFTER the map: status is deliberately\n * the map's FIRST bullet, so ../command-map.ts composes it into COMMAND_MAP\n * between the preamble and the validate entries. The `next.*` fleet and\n * feature codes are what test/codes-drift.test.ts finds here.\n *\n * The `next.*` codes are LISTED, not glossed: `loam explain next.adopt` (and\n * every sibling) answers what a step means and what to run, out of the binary\n * rather than out of this file. See ../command-map.ts's header for why the\n * gloss left. What survives here is what `explain` cannot say — that the list\n * splits fleet-wide from per-feature, and that `next.recover-commit` outranks\n * everything in both forms.\n *\n * Same assembly contract as every section: the composition concatenates with\n * NO join separator, so this string starts at the first character of its\n * opening line and ends with the newline that closes its last one.\n */\nexport const STATUS_COMMAND = `- \\`loam status [<FEAT>]\\` is the orientation surface — the question you have when\n  you join a repository halfway, or come back having lost the session, and the one\n  every other command assumed you could already answer. It writes nothing and\n  stores nothing: there is no state file, every answer is re-derived from the\n  files, so a document someone edited in another window is visible on the next run\n  with nothing to invalidate. Artifacts come back as \\`missing\\` (owed, nothing in\n  the way — write it now), \\`blocked\\` (not written and not writable yet; the entry\n  names what comes first), \\`draft\\` (on disk, and the shared checks report an error\n  against it — what exists is wrong), \\`ready\\` (on disk and clean, but something\n  outside the documents — code, a test run, a recording — still has to answer it)\n  or \\`done\\`. The payload's reason to exist is \\`next[]\\`: ordered, first entry\n  first, each carrying a code and the literal command to run — so a step needs no\n  gloss here, and \\`loam explain <code>\\` has the long form of any of them.\n  \\`next.recover-commit\\` outranks every other step in both forms below and is\n  never elided: a \\`.loam-commit\\` journal says a writer was killed mid-commit, so\n  some of the files everything else is derived from may be half-written.\n  Fleet-wide the rest are \\`next.adopt-bound\\`, \\`next.adopt\\`,\n  \\`next.complete-service\\`, \\`next.revouch\\` (a vouched document's words moved\n  under its stamp — \\`content.stale\\`; its \\`execution\\` is a human review, never\n  yours to run: prepare \\`loam vouch --pack --service <id>\\` and hand the vouch\n  to a person),\n  \\`next.feature\\`, \\`next.archive\\`, \\`next.fleet-clean\\`,\n  \\`next.elided\\` (the fleet list hit its cap and says how many steps of the same\n  kinds it left out — it is ordered most-unblocking first, so work down it and\n  re-run) and \\`next.fleet-gate\\`, always last while anything is outstanding:\n  \\`loam validate --all\\` is what CI runs, and the fleet form grades nothing\n  itself. A docs repo with no services and no features instead gets the\n  first-hour ladder — \\`next.author-landscape\\`, \\`next.bind-service\\`,\n  \\`next.adopt-first\\` — which the \\`/loam-adopt\\` body walks.\n  On one feature: \\`next.author-intent\\`, \\`next.touch-service\\`,\n  \\`next.author-spec\\`, \\`next.author-openapi\\`, \\`next.author-scenarios\\`,\n  \\`next.rebase\\`, \\`next.archive-first\\`, \\`next.fix-coherence\\`,\n  \\`next.generate-tests\\`, \\`next.verify\\`, \\`next.verify-unconfirmed\\`,\n  \\`next.attest-service\\` (this repo IS one of the services that owes an answer,\n  so the step is bound to this commit), \\`next.verify-attested\\` — see\n  \"The done-check\" for what attested costs — \\`next.archive\\`, and\n  \\`next.archived\\` for one that shipped.\n  It grades nothing of its own: the verdict is the one \\`loam validate --feature\\`\n  and \\`loam archive\\` compute — status takes the UNION of what both of them refuse,\n  so it may be more pessimistic than either and can never be greener than both.\n  \\`verification\\` carries \\`verdict\\` (\\`verified\\` | \\`attested\\` | \\`unverified\\`)\n  and \\`attested\\` (how many scenario claims rest on an agent's word) beside the\n  recounted totals, plus \\`answered\\` (the confirmed claims per \\`answered_by\\`:\n  \\`runner\\`, \\`external-runner\\`, \\`agent\\` — a \\`verified\\` record can still rest\n  partly on an agent's word about kinds the verdict does not turn on), and\n  \\`checks.issues[]\\` carries \\`gates\\` and \\`details\\` on every finding.\n`;\n"]}

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

@@ -4,9 +4,10 @@
  * package against the five-file cap, so the tree surface's documentation
  * lives one package down and is concatenated after the map.
  *
- * 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 SUBSYSTEM_COMMANDS = `- \`loam subsystem <verb>\` manages the grouping tree under \`services/\` — the
   navigable tree no identity depends on: a service id stays its leaf directory
@@ -15,8 +16,8 @@ export const SUBSYSTEM_COMMANDS = `- \`loam subsystem <verb>\` manages the group
   [--owner]\` creates a group (an empty one is legal — its \`subsystem.yaml\` is a
   marker, never a member list); \`move <name>... --into <sub|.>\` relocates
   services and whole subtrees in ONE journaled transaction over the renames
-  plus the regenerated views file (\`--into .\` unfiles; the renames and the
-  regenerated views file are staged in git without committing, where git answers); \`rename <old> <new>\` renames a
+  plus BOTH regenerated views files (\`--into .\` unfiles; the renames and the
+  regenerated views files are staged in git without committing, where git answers); \`rename <old> <new>\` renames a
   group through the same transaction (services are never renamed — the id is
   the identity); \`rm <name>\` removes an EMPTY group; \`list\` shows the tree
   with member counts and the unfiled count (unfiled is permanent and normal —
@@ -24,9 +25,12 @@ export const SUBSYSTEM_COMMANDS = `- \`loam subsystem <verb>\` manages the group
   additive keys \`services[].subsystem\`, \`subsystems[]\` and
   \`unfiledServices\`); \`history <name>\` asks git how a service or subsystem
   moved and answers nothing — exit 0, no finding — when git will not say;
-  \`sync\` regenerates \`architecture/subsystems.likec4\`, the one repair for
-  \`subsystem.views-stale\`, and also maintains the RENDERER's wiring for the
-  service models. Which wiring a model needs is decided by the file's own
+  \`sync\` regenerates BOTH generated views files —
+  \`architecture/subsystems.likec4\` (one view per subsystem) and
+  \`architecture/services.likec4\` (one overview view per service the fleet map
+  draws) — the one repair for \`subsystem.views-stale\`, which grades each file
+  separately and names the one that drifted. It also maintains the RENDERER's
+  wiring for the service models. Which wiring a model needs is decided by the file's own
   grammar, never by a config key: a model that declares its own
   \`specification { element … }\` block STANDS ALONE — it cannot share a project
   with the fleet map, since every kind it declares would be a duplicate there —
@@ -58,16 +62,24 @@ export const SUBSYSTEM_COMMANDS = `- \`loam subsystem <verb>\` manages the group
   (\`build\` and \`export\` take every project). A view id claimed twice inside one
   project — the landscape and an extending model both minting it, or either
   claiming a generated one — is
-  \`subsystem.view-id-collision\`. Each generated view is titled by its PATH —
+  \`subsystem.view-id-collision\` — ids beginning \`subsystem_\` or \`service_\` are
+  loam's to mint. Each generated view is titled by its PATH —
   every marked ancestor's label and its own, which the renderer reads as
   folders — where a label is the marker's \`title\` or the directory name; the
-  marker's \`description\` rides along. So editing \`subsystem.yaml\` changes
+  marker's \`description\` rides along. A per-service view is titled
+  \`<subsystem path> / <service id>\`, so it lands in the same folder as its
+  group, and a \`dynamic view\` you write under
+  \`services/<…>/<id>/usecases/\` titled \`<subsystem path> / <service id> / <use
+  case>\` lands beside it. So editing \`subsystem.yaml\` changes
   what the renderer LABELS the group, a parent's title changes every view
-  beneath it, and either makes the file stale until the next \`sync\`. The
-  generated file is NEVER part of the fleet-project load
+  beneath it, and either makes both files stale until the next \`sync\`. Neither
+  generated file is part of the fleet-project load
   (\`c4.fleet-project-invalid\` reads every other \`.likec4\` the root project holds);
-  \`subsystem.views-stale\` is the only check that reads it, by byte comparison.
-  Each view
+  \`subsystem.views-stale\` is the only check that reads them, by content
+  comparison against the deterministic re-render, never by reading what a view
+  shows. Each per-service view is declared \`of\` its service's element, which is
+  what makes every other view — the fleet map, its subsystem view, its peers'
+  views — drill into it with no authored link. Each subsystem view
   carries \`global style subsystems\` — written after its title, the one line
   LikeC4 gives a view for borrowing a palette — exactly when the \`architecture/\`
   project declares a global style with that id (\`global { styleGroup subsystems
@@ -79,10 +91,12 @@ export const SUBSYSTEM_COMMANDS = `- \`loam subsystem <verb>\` manages the group
   names only, the file opens with one comment line naming them and saying none is
   \`subsystems\`, and the views carry the renderer's defaults — so declaring a group
   under ANY name restales the file, because that comment is part of the bytes.
-  \`sync\` refuses to rewrite it at all while \`architecture/\` does not parse
-  (\`action: "blocked"\`): fix the map first. It is generated wholesale:
+  \`architecture/services.likec4\` reads a group named \`services\` the same way.
+  \`sync\` refuses to rewrite either file while \`architecture/\` does not parse
+  (\`action: "blocked"\`): fix the map first. Both are generated wholesale:
   an authored diagram of the same services belongs in the landscape or in a
-  file of your own name, never here. \`loam adopt --subsystem <name>\` briefs a new
+  file of your own name, never here. \`--json\` reports the subsystem file as
+  \`path\`/\`action\` and the per-service one as \`serviceViews\`. \`loam adopt --subsystem <name>\` briefs a new
   service's baseline directly into a group, so adoption need not land unfiled.
 `;
 //# sourceMappingURL=subsystem.js.map

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

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

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

@@ -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 —
@@ -29,13 +30,15 @@ export const USECASE_VIEWS = `- Business use cases are \`dynamic view\`s, and \`
   naming a container that a service's extending model declares resolves in the
   renderer's wider root project and is \`landscape.invalid\` for loam, which takes
   the whole fleet map down. Container-level flows live beside the model that
-  declares them (below). EITHER reserved prefix
+  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
@@ -44,6 +47,21 @@ export const USECASE_VIEWS = `- Business use cases are \`dynamic view\`s, and \`
   hop written \`a <- b\` is attributed to the call it answers, so spell replies
   that way rather than as fresh hops. Every message names the file the view was
   written in, never the landscape.
+- A 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\`

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