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

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

@@ -0,0 +1,299 @@
+/**
+ * Reading loam's output: which codes each invocation can raise.
+ *
+ * {@link CODE_MAP} is the code-by-code map of `status`, `validate`, `doctor`,
+ * `rebase`, `dependencies`, `explore`, `seed` and `instructions` — the part
+ * `loam instructions loam-codes` prints. ../workflows/reference/codes.ts
+ * composes it with `./map/`, `./map/lenses/` and `./refusals.ts`, in exactly the
+ * order ../agents-md.ts used to concatenate them, so the assembled page is the
+ * section byte for byte.
+ *
+ * This module used to hold the other delivery too: `READING_OUTPUT` and
+ * `REFERENCE_PAGES`, the two AGENTS.md sections that stayed behind when the map
+ * left. Since 0.2.0-alpha.1 AGENTS.md is the single ORIENTATION literal in
+ * ../agents-md.ts, which carries its own condensed "Reading loam's output" and
+ * "Reference pages" sections, and nothing assembled the two old constants into
+ * anything loam shipped. They were deleted rather than left to be edited as if a
+ * reader would ever see them.
+ *
+ * WHY THE MAP LEFT THE FILE, given that this package's whole subject is a file.
+ * AGENTS.md is auto-loaded from the working directory by every agents.md-aware
+ * host, on every session, and `loam init` writes it once and never refreshes it.
+ * It reached 109,399 bytes; Codex truncates the AGENTS.md chain at 32,768 bytes
+ * and Windsurf caps a workspace rule file at 12,000 characters, both silently.
+ * Roughly seventy percent of the document was being dropped with no error and no
+ * way for the reader to tell which half it held — and this section alone was
+ * 44,433 of those bytes, 41% of the file. It is also the half a reader consults
+ * at a moment it can name (a run reported something) rather than the half it
+ * needs to form a question at all, which is what decided which side of the split
+ * it went. ../workflows/reference/reference.ts carries the rest of that argument.
+ *
+ * The move is a move and not a deletion: every byte is still shipped, still in
+ * the same corpus test/codes-drift.test.ts reads (AGENTS_MD + PROTOCOLS), and
+ * still one command away rather than one file away.
+ *
+ * WHAT THE MAP IS, AND WHAT IT DELIBERATELY IS NOT. The unique content is which
+ * codes which INVOCATION can raise: nothing else in the corpus says that, and an
+ * agent choosing what to run needs it. What it does not carry is a per-code
+ * gloss of what each code MEANS. That half used to be written twice — once here,
+ * once in the /loam-check fix tables — in two independently worded places, in a
+ * file `loam init` writes once and never refreshes, so the two drifted with
+ * nothing able to say which had rotted. `loam explain <code>` now answers
+ * meaning, severity and fix for every code named below, out of the running
+ * binary. test/agent-contract.test.ts holds that pointer honest: every code
+ * backticked in the corpus must resolve through `explainSubject`, so a family
+ * added here without an explanation fails by name. Keep the code list; add the
+ * gloss only where it says something `explain` cannot — a condition on when the
+ * invocation raises it at all, or a cross-reference between two codes.
+ *
+ * ONE PARAGRAPH THE MOVE MADE FALSE, and the reason to look for others like it.
+ * The `agents.stale` entry read "one check on this very file … the reason to
+ * distrust what you are reading", which was true while these bytes WERE the
+ * scaffolded AGENTS.md. On a page printed by the binary it is exactly backwards
+ * — this page cannot be stale, and the file it warns about is somewhere else —
+ * so the entry names AGENTS.md instead. A section that talks about its own
+ * document does not survive being moved to another one; that is the class to
+ * check for whenever anything else leaves this file.
+ *
+ * CODE_MAP is one part of the `loam-codes` page, which
+ * ../workflows/reference/codes.ts assembles by PLAIN CONCATENATION — no join
+ * separator — so it 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.
+ */
+import { STATUS_COMMAND } from "./map/status.js";
+/**
+ * The reference page's own opening: what the map is, where the /loam-check fix
+ * tables sit beside it, and the one family `loam explain` cannot answer.
+ */
+const MAP_INTRO = `**What this page is.** It says which codes an INVOCATION can raise. It does
+NOT say what they mean: that half is one command away and describes the loam you
+are running rather than the one that scaffolded this repo. \`loam explain <code>\`
+gives one code's meaning, its severity in each scope that grades it, and its fix;
+\`loam explain --codes\` lists the whole vocabulary and \`loam explain --codes --json\`
+is the machine-readable form. The one family \`explain\` does not answer
+is the OpenSpec migration surface (\`openspec.*\`, \`mapping.*\`) — those commands run
+before a repository has a governed loop to look a code up from — so those entries
+alone keep their notes here.
+
+The code-by-code fix table is a different document again: it lives in the
+\`/loam-check\` command \`loam init\` lays
+down. \`init\` writes that body twice for every tool it configures: once as a slash
+command in the tool's own command directory (you type it), and once as an Agent
+Skill at \`<tool-dir>/skills/loam-check/SKILL.md\` (the model loads it by itself when
+the task matches the skill's description). Same body, two ways in.
+
+Which tools get them is detected from the repo: \`loam init\` scans for the
+dot-directories of the tools it knows (\`.claude\`, \`.cursor\`, \`.gemini\`, …) and
+writes for the ones it finds, falling back to Claude Code when it finds none.
+\`loam init --tools <ids|all>\` overrides the scan — an unknown id is refused
+(\`invalid-option\`) rather than skipped — and \`--no-commands\` / \`--no-skills\`
+each suppress one delivery. The tools written for are recorded in
+\`loam.json\` as \`agentTools\`, which is how \`loam doctor\` tells a file missing
+because the binary grew a new command from one missing because nobody ever
+selected that tool.
+
+The map:
+
+`;
+const MAP_REST = `- \`loam validate --service <id>\` grades one service's own axes: \`service.unknown\`,
+  \`service.no-model\`, \`service.no-spec\`, \`service.no-openapi\`, \`c4.invalid\`,
+  \`c4.declaration-diverged\`, \`c4.element-unowned\`,
+  \`c4.no-relationships\`, \`requirements.missing-scenarios\`,
+  \`requirements.stepless-scenario\`, \`requirements.assertionless-scenario\`,
+  \`requirements.examples-unbound\`, \`requirements.examples-unreferenced\`,
+  \`spec.merge-conflict\`, \`spec.duplicate-requirement\`, \`spec.no-requirements\`,
+  \`spec.repeated-operations\`, \`spec.repeated-covers\`, \`openapi.invalid\`,
+  \`openapi.duplicate-operationid\`, \`openapi.response-undescribed\`,
+  \`openapi.ref-unresolved\`, \`api.ungoverned\`, \`api.ops-unlinked\`,
+  \`api.requirement-deprecated\`, \`spec-api.op-undefined\`,
+  \`spine.landscape-invalid\`, \`spine.op-undefined\`, \`spine.op-link-missing\`,
+  \`spine.op-deprecated\`; the async contract axis (AsyncAPI 3):
+  \`service.no-asyncapi\`, \`asyncapi.invalid\`, \`asyncapi.duplicate-message\`,
+  \`asyncapi.payload-undescribed\`, \`asyncapi.ref-unresolved\`,
+  \`spine.message-undefined\`, \`spec-event.message-undefined\`,
+  \`spine.message-unproduced\`, \`spine.message-external\`, \`spine.message-unbound\`,
+  \`asyncapi.message-contested\`, \`event.messages-unlinked\`, \`event.ungoverned\`,
+  \`event.covered\`; and the architecture spec axis: \`covers.unknown\`,
+  \`health.invalid\`, \`health.uncovered\`, \`health.dependency-unmodelled\`.
+  Run inside the service's own repo, once a generated suite exists under
+  \`<gherkinDir>/loam/\`, it also grades that suite against the living specs:
+  \`gherkin.missing\`, \`gherkin.stale\`, \`gherkin.orphaned\`. A service that never
+  ran \`loam gherkin\` stays quiet — that whole trio is conditional on the suite
+  existing here — and a file tagged with a feature still in flight answers to
+  that feature, not to the living spec it has not merged into yet.
+- \`loam validate --feature <id>\` grades a change's three axes against each other and
+  against the fleet in flight: \`delta.invalid\`, \`delta.nothing-tagged\`,
+  \`delta.service-unknown\`, \`delta.service-id-invalid\`, \`spec-api.op-undefined\`,
+  \`spec-api.op-pending\`, \`c4-api.op-undefined\`, \`c4-api.op-pending\`,
+  \`c4-api.op-deprecated\`, \`c4.op-ungoverned\`, \`c4.op-link-missing\`,
+  \`c4.service-binding-invalid\`, \`api.op-unconsumed\`,
+  \`service.no-requirement-delta\`, \`archedge.uncovered\`, and — the same four
+  codes service scope raises, graded here on the feature's own spec.md and
+  arch.spec.md deltas, because every one of those breaches merges into the
+  living document — \`spec.repeated-operations\`, \`spec.repeated-covers\`,
+  \`spec.merge-conflict\` and \`requirements.stepless-scenario\`. A feature
+  whose verification record will not read as one raises
+  \`evidence.record-unreadable\` (warn) here as well. Then the
+  architecture spec axis (\`c4.uncovered\`, plus \`covers.unknown\` on the
+  feature's arch.spec.md deltas), the delta-shape group:
+  \`delta.unknown-section\`, \`delta.no-delta-sections\`,
+  \`delta.requirement-not-merged\`, \`delta.modified-unknown\`, \`delta.removed-unknown\`,
+  \`delta.added-duplicate\`, \`delta.added-near-duplicate\`, \`delta.modified-pending\`,
+  \`delta.removed-pending\`, \`delta.added-conflict\`, \`delta.modified-conflict\`,
+  \`delta.living-duplicate-requirement\`, and the API-removal group:
+  \`openapi.remove-marker-anonymous\`, \`openapi.remove-op-consumed\`, and
+  \`openapi.op-revived\` (warn, gates archive: the delta spells an operation an
+  archived feature retired, or at an address one retired or moved it away
+  from while it lives on elsewhere, so the merge would put it back).
+  The event axis is graded in feature scope too — the \`asyncapi.*\`
+  baseline/removal/conflict codes, \`asyncapi.slot-revived\` (the same revival
+  on a channel, operation or message), plus \`c4-event.*\`, \`spec-event.*\` and
+  \`spine.message-unbound\` (a tagged edge's event key bound to a topic or other infrastructure).
+  Where a finding names another feature in flight (\`delta.*-pending\`,
+  \`delta.added-conflict\`, \`delta.modified-conflict\`, \`spec-api.op-pending\`,
+  \`c4-api.op-pending\`) the ORDER is the answer, and \`loam dependencies --json\`
+  is what computes it: \`order\` is a dependency-first sequence, \`conflicts\`
+  the pairs no ordering fixes, \`cycles\` the ones that need a human.
+- \`loam validate --all\` runs both of those for everything and adds the fleet
+  cross-check: \`landscape.missing\`, \`landscape.invalid\`,
+  \`landscape.merge-conflict\`, \`landscape.service-unmodelled\`,
+  \`landscape.service-undocumented\`, \`landscape.binding-unknown\`,
+  \`landscape.binding-duplicate\`, the fleet-shape advisories
+  \`landscape.platform-candidate\` and
+  \`landscape.datastore-shared\`, \`service.id-invalid\` (fleet scope only, and
+  graded before the map is opened, so it stands even when the landscape is
+  missing or unreadable), the four renderer-wiring warnings a
+  \`loam subsystem sync\` repairs — \`service.likec4-config-missing\` (a model that
+  STANDS ALONE, declaring its own \`specification\`, with no
+  \`likec4.config.json\` beside it: it renders nowhere from the docs root),
+  \`service.likec4-config-stray\` (that file beside a model that EXTENDS the map,
+  where it registers a project that CLAIMS the model, out of the root project
+  where the map's kinds are),
+  \`service.model-excluded\` (the root \`likec4.config.json\` excludes an extending
+  model's directory, so the renderer never loads it) and
+  \`service.model-unexcluded\` (it does NOT exclude a standalone model's, so the
+  renderer merges that model into the map and calls every declaration a
+  duplicate) — plus \`c4.fleet-project-invalid\` (warn: every document reads clean
+  where loam grades it and the ONE project the renderer builds out of the map and
+  every extending model does not, because something is declared in two of them),
+  a per-service \`sources.unverifiable-from-here\`, and
+  one check on the docs repo's own AGENTS.md, \`agents.stale\`. That last one is
+  the reason to distrust THAT file rather than this page: it fires when its
+  version stamp on line 1 (\`<!-- generated by loam vX.Y.Z -->\`) is missing or
+  older than the running binary, which is exactly when what it says may name a
+  loam that no longer exists. It is never refreshed automatically — your edits
+  outrank the template, so detection is all loam does, and a hand-curated file
+  silences it the same way, by keeping the stamp current. This page has no such
+  failure mode: it is printed by the binary it describes.
+  \`loam validate --all\`'s \`--json\` payload also carries the additive \`scorecard\` key — per-axis ceiling-vs-actual fleet
+  aggregates, the text report appending the same table; derived per run and never stored, so week-over-week is the pipeline's job: capture the key per run into a metrics store.
+  \`scorecard.adoption\` counts the services PARTICIPATING in each contract axis
+  (requirements, arch, openapi, asyncapi, permissions, capabilities; the
+  denominator is \`scorecard.services\`) — an axis at 0 of N reads "not started",
+  which is expected during staged adoption and distinct from partially adopted.
+  Text mode folds the warnings such an axis alone causes under one banner per
+  axis and says so; \`--json\` carries every finding unchanged, and the summary
+  counts, exit codes and \`--strict\` are identical either way.
+- \`loam doctor\` is read-only local/fleet preflight — the first thing to run in a
+  repo that behaves as though the fleet were empty. Every finding carries a
+  \`fix\` field naming the exact command or edit, so this is the one family you
+  rarely need \`loam explain\` for. Its blockers are \`doctor.config-missing\`,
+  \`doctor.config-invalid\`, \`doctor.docs-missing\`, \`doctor.services-missing\`, and
+  the three that say the fleet map cannot be read at all —
+  \`doctor.landscape-merge-conflict\`, \`doctor.landscape-invalid\` and
+  \`doctor.landscape-unreadable\`. It also grades what a WRITE that did not finish
+  left in the docs repo, reported as \`writePath\` beside the findings:
+  \`doctor.docs-locked\`, \`doctor.commit-interrupted\`, \`doctor.commit-unreadable\`
+  and \`doctor.staging-temps\`. When this repo is a service repo that same scan
+  covers \`<gherkinDir>/loam/\`, the root \`loam gherkin\` commits into.
+  Accessibility, portability and incomplete binding stay warnings:
+  \`doctor.docs-unreadable\`, \`doctor.docs-readonly\`, \`doctor.docs-absolute\`,
+  \`doctor.inventory-unreadable\`, \`doctor.landscape-missing\`,
+  \`doctor.service-unbound\` (never raised inside the docs repo itself, where
+  having no service binding is the correct state), \`doctor.service-unknown\`
+  (the same state \`loam status\` reports as \`next.adopt-bound\` — or, when an
+  active feature introduces the service, as that feature's \`next.feature\`, and
+  then the finding names the feature and \`currentService.introducedBy\` lists
+  it: there is nothing to adopt),
+  \`doctor.likec4-config-missing\`, and the two about this repo's own generated
+  command and skill files: \`doctor.agent-files-missing\` and
+  \`doctor.agent-files-stale\`.
+  The second one fires only for a file whose body differs from the one this
+  loam writes AND whose stamp is missing or older — so after an upgrade, expect
+  it when the release changed the pointer text, never for a stamp-only
+  difference, and never for an edited body under a current stamp (that stamp is
+  the record that somebody reviewed it). Re-running \`loam init\` refreshes an
+  unchanged pointer only when its current bytes still match the digest
+  recorded in \`loam.json\`; an unrecorded or customized file stays in place
+  for a human to review.
+- \`loam rebase <FEAT>\` writes the baseline pins: \`Based-On:\` under every
+  MODIFIED/REMOVED requirement in the feature's spec deltas, and
+  \`x-loam-based-on\` on every operation in its openapi.yaml, from the living text
+  as it stands right now. Run it when you finish authoring a delta and again
+  after you resolve a collision — it is the one mechanism standing between two
+  features in flight and silently reverting each other's landed work. It refuses
+  rather than inventing a pin, and re-pinning is not resolving: see
+  "The requirement baseline". An operation or event slot the delta spells that
+  an ARCHIVED feature retired is not pinned as new: rebase prints the
+  \`openapi.op-revived\` / \`asyncapi.slot-revived\` finding (and \`revived[]\` in
+  \`--json\`) and leaves the call — delete the quote, or re-add on purpose — to
+  you. It judges the delta as it will write it, pins included, so a quote its
+  own repin turns into an edit — repinned over whatever lives now at an
+  address an archived feature moved the entry away from — is in that list too,
+  under \`--dry-run\` as well.
+- \`loam dependencies [<FEAT>]\` derives the ordering of the features in flight
+  from the artifacts themselves — requirement identities and OpenAPI
+  operationIds, never from validator prose. It is the answer to every
+  "another feature in flight does this first" finding, and to
+  \`delta.added-conflict\` / \`delta.modified-conflict\`, which no ordering fixes.
+- \`loam explore [<service>...]\` reads the fleet around a change nobody has
+  written down yet, and writes nothing. It exists because \`loam new\`'s
+  \`--touches\` list is the hardest call in the cycle and the only one nothing
+  downstream catches: a list short by one service produces a feature that
+  validates, archives and ships with a consumer nobody updated. What it derives
+  is mechanical — the one-hop ring, each service's rung, its living operations,
+  who already calls whom, and which active features cover the same services. It
+  does NOT decide which of those neighbours you actually change; that is a
+  judgement about intent, and loam does not make those. \`--op <operationId>\`
+  seeds from the operation's defining service; \`--capability <id>\` (repeatable)
+  seeds from a declared capability's realizing services, and an id that seeds
+  nothing lands in the additive \`unresolvedCapabilities\` — beside
+  \`loam list capabilities\`, the rollup those seeds are read from.
+- \`loam seed --from fleet.yaml\` is the onboarding entry point for an empty
+  fleet: a tiny human-authored YAML — a \`services:\` list of ids, optional
+  \`subsystems:\`, \`externals:\` and \`calls:\` lines like
+  \`checkout -> payments\` — templated mechanically into
+  architecture/landscape.likec4 (one bound element per service, plain edges, no
+  guessed operationIds) plus one services/<id>/ directory per service, in one
+  journaled transaction. Not an extractor: the human stated every fact, and
+  "who calls whom" is the one thing no generator can read off a repository.
+  The seeded landscape carries a line-1 stamp; while it stands unedited,
+  editing fleet.yaml and re-running regenerates the map, and the first hand
+  edit anywhere in the file, including above the stub, makes it yours — seed
+  then refuses \`seed-landscape-edited\`
+  rather than overwrite. So seed is a day-zero step: fleet.yaml has no spelling
+  for \`metadata { op }\`, and once an edge carries one the map grows through
+  adopt briefs and feature C4 deltas, not through seed. Then adopt each
+  service: \`loam adopt --service <id>\`.
+- \`loam instructions [<page>] [args...]\` prints one of the six workflow
+  protocols — \`loam-adopt\`, \`loam-feature\`, \`loam-implement\`, \`loam-check\`,
+  \`loam-verify\`, \`loam-ship\` — with \`$1\`, \`$2\` filled in from the arguments you
+  pass, the \`loam-report\` support protocol, or one of the five reference pages —
+  \`loam-codes\`, \`loam-spine\`, \`loam-authoring\`, \`loam-done-check\`,
+  \`loam-drawing\` — which take no arguments. With no argument at all it lists all three sets. The pages ship
+  inside the binary, so they describe the loam you are about to run rather than
+  the one that scaffolded the repository; the command and skill files
+  \`loam init\` writes are pointers at it, and so is AGENTS.md's own
+  "Reference pages — fetch when needed" section. It reads no
+  \`loam.json\` and no docs repo, deliberately: \`loam-adopt\`'s own first step is
+  to run \`loam init\` when there is no config, so it cannot be the step that
+  requires one.
+`;
+/**
+ * The reference page's body, up to the modules that continue it. The bullets
+ * are ordered so `status` — the orientation command, the one to run when you
+ * have lost the session — is read first.
+ */
+export const CODE_MAP = MAP_INTRO + STATUS_COMMAND + MAP_REST;
+//# sourceMappingURL=command-map.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command-map.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/command-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;GAGG;AACH,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BjB,CAAC;AAEF,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiMhB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,GAAG,cAAc,GAAG,QAAQ,CAAC","sourcesContent":["/**\n * Reading loam's output: which codes each invocation can raise.\n *\n * {@link CODE_MAP} is the code-by-code map of `status`, `validate`, `doctor`,\n * `rebase`, `dependencies`, `explore`, `seed` and `instructions` — the part\n * `loam instructions loam-codes` prints. ../workflows/reference/codes.ts\n * composes it with `./map/`, `./map/lenses/` and `./refusals.ts`, in exactly the\n * order ../agents-md.ts used to concatenate them, so the assembled page is the\n * section byte for byte.\n *\n * This module used to hold the other delivery too: `READING_OUTPUT` and\n * `REFERENCE_PAGES`, the two AGENTS.md sections that stayed behind when the map\n * left. Since 0.2.0-alpha.1 AGENTS.md is the single ORIENTATION literal in\n * ../agents-md.ts, which carries its own condensed \"Reading loam's output\" and\n * \"Reference pages\" sections, and nothing assembled the two old constants into\n * anything loam shipped. They were deleted rather than left to be edited as if a\n * reader would ever see them.\n *\n * WHY THE MAP LEFT THE FILE, given that this package's whole subject is a file.\n * AGENTS.md is auto-loaded from the working directory by every agents.md-aware\n * host, on every session, and `loam init` writes it once and never refreshes it.\n * It reached 109,399 bytes; Codex truncates the AGENTS.md chain at 32,768 bytes\n * and Windsurf caps a workspace rule file at 12,000 characters, both silently.\n * Roughly seventy percent of the document was being dropped with no error and no\n * way for the reader to tell which half it held — and this section alone was\n * 44,433 of those bytes, 41% of the file. It is also the half a reader consults\n * at a moment it can name (a run reported something) rather than the half it\n * needs to form a question at all, which is what decided which side of the split\n * it went. ../workflows/reference/reference.ts carries the rest of that argument.\n *\n * The move is a move and not a deletion: every byte is still shipped, still in\n * the same corpus test/codes-drift.test.ts reads (AGENTS_MD + PROTOCOLS), and\n * still one command away rather than one file away.\n *\n * WHAT THE MAP IS, AND WHAT IT DELIBERATELY IS NOT. The unique content is which\n * codes which INVOCATION can raise: nothing else in the corpus says that, and an\n * agent choosing what to run needs it. What it does not carry is a per-code\n * gloss of what each code MEANS. That half used to be written twice — once here,\n * once in the /loam-check fix tables — in two independently worded places, in a\n * file `loam init` writes once and never refreshes, so the two drifted with\n * nothing able to say which had rotted. `loam explain <code>` now answers\n * meaning, severity and fix for every code named below, out of the running\n * binary. test/agent-contract.test.ts holds that pointer honest: every code\n * backticked in the corpus must resolve through `explainSubject`, so a family\n * added here without an explanation fails by name. Keep the code list; add the\n * gloss only where it says something `explain` cannot — a condition on when the\n * invocation raises it at all, or a cross-reference between two codes.\n *\n * ONE PARAGRAPH THE MOVE MADE FALSE, and the reason to look for others like it.\n * The `agents.stale` entry read \"one check on this very file … the reason to\n * distrust what you are reading\", which was true while these bytes WERE the\n * scaffolded AGENTS.md. On a page printed by the binary it is exactly backwards\n * — this page cannot be stale, and the file it warns about is somewhere else —\n * so the entry names AGENTS.md instead. A section that talks about its own\n * document does not survive being moved to another one; that is the class to\n * check for whenever anything else leaves this file.\n *\n * CODE_MAP is one part of the `loam-codes` page, which\n * ../workflows/reference/codes.ts assembles by PLAIN CONCATENATION — no join\n * separator — so it starts at the first character of its opening line and ends\n * with the newline that closes its last one. Keep that shape when editing, or\n * two parts glue onto one line on the printed page.\n */\nimport { STATUS_COMMAND } from \"./map/status.js\";\n\n/**\n * The reference page's own opening: what the map is, where the /loam-check fix\n * tables sit beside it, and the one family `loam explain` cannot answer.\n */\nconst MAP_INTRO = `**What this page is.** It says which codes an INVOCATION can raise. It does\nNOT say what they mean: that half is one command away and describes the loam you\nare running rather than the one that scaffolded this repo. \\`loam explain <code>\\`\ngives one code's meaning, its severity in each scope that grades it, and its fix;\n\\`loam explain --codes\\` lists the whole vocabulary and \\`loam explain --codes --json\\`\nis the machine-readable form. The one family \\`explain\\` does not answer\nis the OpenSpec migration surface (\\`openspec.*\\`, \\`mapping.*\\`) — those commands run\nbefore a repository has a governed loop to look a code up from — so those entries\nalone keep their notes here.\n\nThe code-by-code fix table is a different document again: it lives in the\n\\`/loam-check\\` command \\`loam init\\` lays\ndown. \\`init\\` writes that body twice for every tool it configures: once as a slash\ncommand in the tool's own command directory (you type it), and once as an Agent\nSkill at \\`<tool-dir>/skills/loam-check/SKILL.md\\` (the model loads it by itself when\nthe task matches the skill's description). Same body, two ways in.\n\nWhich tools get them is detected from the repo: \\`loam init\\` scans for the\ndot-directories of the tools it knows (\\`.claude\\`, \\`.cursor\\`, \\`.gemini\\`, …) and\nwrites for the ones it finds, falling back to Claude Code when it finds none.\n\\`loam init --tools <ids|all>\\` overrides the scan — an unknown id is refused\n(\\`invalid-option\\`) rather than skipped — and \\`--no-commands\\` / \\`--no-skills\\`\neach suppress one delivery. The tools written for are recorded in\n\\`loam.json\\` as \\`agentTools\\`, which is how \\`loam doctor\\` tells a file missing\nbecause the binary grew a new command from one missing because nobody ever\nselected that tool.\n\nThe map:\n\n`;\n\nconst MAP_REST = `- \\`loam validate --service <id>\\` grades one service's own axes: \\`service.unknown\\`,\n  \\`service.no-model\\`, \\`service.no-spec\\`, \\`service.no-openapi\\`, \\`c4.invalid\\`,\n  \\`c4.declaration-diverged\\`, \\`c4.element-unowned\\`,\n  \\`c4.no-relationships\\`, \\`requirements.missing-scenarios\\`,\n  \\`requirements.stepless-scenario\\`, \\`requirements.assertionless-scenario\\`,\n  \\`requirements.examples-unbound\\`, \\`requirements.examples-unreferenced\\`,\n  \\`spec.merge-conflict\\`, \\`spec.duplicate-requirement\\`, \\`spec.no-requirements\\`,\n  \\`spec.repeated-operations\\`, \\`spec.repeated-covers\\`, \\`openapi.invalid\\`,\n  \\`openapi.duplicate-operationid\\`, \\`openapi.response-undescribed\\`,\n  \\`openapi.ref-unresolved\\`, \\`api.ungoverned\\`, \\`api.ops-unlinked\\`,\n  \\`api.requirement-deprecated\\`, \\`spec-api.op-undefined\\`,\n  \\`spine.landscape-invalid\\`, \\`spine.op-undefined\\`, \\`spine.op-link-missing\\`,\n  \\`spine.op-deprecated\\`; the async contract axis (AsyncAPI 3):\n  \\`service.no-asyncapi\\`, \\`asyncapi.invalid\\`, \\`asyncapi.duplicate-message\\`,\n  \\`asyncapi.payload-undescribed\\`, \\`asyncapi.ref-unresolved\\`,\n  \\`spine.message-undefined\\`, \\`spec-event.message-undefined\\`,\n  \\`spine.message-unproduced\\`, \\`spine.message-external\\`, \\`spine.message-unbound\\`,\n  \\`asyncapi.message-contested\\`, \\`event.messages-unlinked\\`, \\`event.ungoverned\\`,\n  \\`event.covered\\`; and the architecture spec axis: \\`covers.unknown\\`,\n  \\`health.invalid\\`, \\`health.uncovered\\`, \\`health.dependency-unmodelled\\`.\n  Run inside the service's own repo, once a generated suite exists under\n  \\`<gherkinDir>/loam/\\`, it also grades that suite against the living specs:\n  \\`gherkin.missing\\`, \\`gherkin.stale\\`, \\`gherkin.orphaned\\`. A service that never\n  ran \\`loam gherkin\\` stays quiet — that whole trio is conditional on the suite\n  existing here — and a file tagged with a feature still in flight answers to\n  that feature, not to the living spec it has not merged into yet.\n- \\`loam validate --feature <id>\\` grades a change's three axes against each other and\n  against the fleet in flight: \\`delta.invalid\\`, \\`delta.nothing-tagged\\`,\n  \\`delta.service-unknown\\`, \\`delta.service-id-invalid\\`, \\`spec-api.op-undefined\\`,\n  \\`spec-api.op-pending\\`, \\`c4-api.op-undefined\\`, \\`c4-api.op-pending\\`,\n  \\`c4-api.op-deprecated\\`, \\`c4.op-ungoverned\\`, \\`c4.op-link-missing\\`,\n  \\`c4.service-binding-invalid\\`, \\`api.op-unconsumed\\`,\n  \\`service.no-requirement-delta\\`, \\`archedge.uncovered\\`, and — the same four\n  codes service scope raises, graded here on the feature's own spec.md and\n  arch.spec.md deltas, because every one of those breaches merges into the\n  living document — \\`spec.repeated-operations\\`, \\`spec.repeated-covers\\`,\n  \\`spec.merge-conflict\\` and \\`requirements.stepless-scenario\\`. A feature\n  whose verification record will not read as one raises\n  \\`evidence.record-unreadable\\` (warn) here as well. Then the\n  architecture spec axis (\\`c4.uncovered\\`, plus \\`covers.unknown\\` on the\n  feature's arch.spec.md deltas), the delta-shape group:\n  \\`delta.unknown-section\\`, \\`delta.no-delta-sections\\`,\n  \\`delta.requirement-not-merged\\`, \\`delta.modified-unknown\\`, \\`delta.removed-unknown\\`,\n  \\`delta.added-duplicate\\`, \\`delta.added-near-duplicate\\`, \\`delta.modified-pending\\`,\n  \\`delta.removed-pending\\`, \\`delta.added-conflict\\`, \\`delta.modified-conflict\\`,\n  \\`delta.living-duplicate-requirement\\`, and the API-removal group:\n  \\`openapi.remove-marker-anonymous\\`, \\`openapi.remove-op-consumed\\`, and\n  \\`openapi.op-revived\\` (warn, gates archive: the delta spells an operation an\n  archived feature retired, or at an address one retired or moved it away\n  from while it lives on elsewhere, so the merge would put it back).\n  The event axis is graded in feature scope too — the \\`asyncapi.*\\`\n  baseline/removal/conflict codes, \\`asyncapi.slot-revived\\` (the same revival\n  on a channel, operation or message), plus \\`c4-event.*\\`, \\`spec-event.*\\` and\n  \\`spine.message-unbound\\` (a tagged edge's event key bound to a topic or other infrastructure).\n  Where a finding names another feature in flight (\\`delta.*-pending\\`,\n  \\`delta.added-conflict\\`, \\`delta.modified-conflict\\`, \\`spec-api.op-pending\\`,\n  \\`c4-api.op-pending\\`) the ORDER is the answer, and \\`loam dependencies --json\\`\n  is what computes it: \\`order\\` is a dependency-first sequence, \\`conflicts\\`\n  the pairs no ordering fixes, \\`cycles\\` the ones that need a human.\n- \\`loam validate --all\\` runs both of those for everything and adds the fleet\n  cross-check: \\`landscape.missing\\`, \\`landscape.invalid\\`,\n  \\`landscape.merge-conflict\\`, \\`landscape.service-unmodelled\\`,\n  \\`landscape.service-undocumented\\`, \\`landscape.binding-unknown\\`,\n  \\`landscape.binding-duplicate\\`, the fleet-shape advisories\n  \\`landscape.platform-candidate\\` and\n  \\`landscape.datastore-shared\\`, \\`service.id-invalid\\` (fleet scope only, and\n  graded before the map is opened, so it stands even when the landscape is\n  missing or unreadable), the four renderer-wiring warnings a\n  \\`loam subsystem sync\\` repairs — \\`service.likec4-config-missing\\` (a model that\n  STANDS ALONE, declaring its own \\`specification\\`, with no\n  \\`likec4.config.json\\` beside it: it renders nowhere from the docs root),\n  \\`service.likec4-config-stray\\` (that file beside a model that EXTENDS the map,\n  where it registers a project that CLAIMS the model, out of the root project\n  where the map's kinds are),\n  \\`service.model-excluded\\` (the root \\`likec4.config.json\\` excludes an extending\n  model's directory, so the renderer never loads it) and\n  \\`service.model-unexcluded\\` (it does NOT exclude a standalone model's, so the\n  renderer merges that model into the map and calls every declaration a\n  duplicate) — plus \\`c4.fleet-project-invalid\\` (warn: every document reads clean\n  where loam grades it and the ONE project the renderer builds out of the map and\n  every extending model does not, because something is declared in two of them),\n  a per-service \\`sources.unverifiable-from-here\\`, and\n  one check on the docs repo's own AGENTS.md, \\`agents.stale\\`. That last one is\n  the reason to distrust THAT file rather than this page: it fires when its\n  version stamp on line 1 (\\`<!-- generated by loam vX.Y.Z -->\\`) is missing or\n  older than the running binary, which is exactly when what it says may name a\n  loam that no longer exists. It is never refreshed automatically — your edits\n  outrank the template, so detection is all loam does, and a hand-curated file\n  silences it the same way, by keeping the stamp current. This page has no such\n  failure mode: it is printed by the binary it describes.\n  \\`loam validate --all\\`'s \\`--json\\` payload also carries the additive \\`scorecard\\` key — per-axis ceiling-vs-actual fleet\n  aggregates, the text report appending the same table; derived per run and never stored, so week-over-week is the pipeline's job: capture the key per run into a metrics store.\n  \\`scorecard.adoption\\` counts the services PARTICIPATING in each contract axis\n  (requirements, arch, openapi, asyncapi, permissions, capabilities; the\n  denominator is \\`scorecard.services\\`) — an axis at 0 of N reads \"not started\",\n  which is expected during staged adoption and distinct from partially adopted.\n  Text mode folds the warnings such an axis alone causes under one banner per\n  axis and says so; \\`--json\\` carries every finding unchanged, and the summary\n  counts, exit codes and \\`--strict\\` are identical either way.\n- \\`loam doctor\\` is read-only local/fleet preflight — the first thing to run in a\n  repo that behaves as though the fleet were empty. Every finding carries a\n  \\`fix\\` field naming the exact command or edit, so this is the one family you\n  rarely need \\`loam explain\\` for. Its blockers are \\`doctor.config-missing\\`,\n  \\`doctor.config-invalid\\`, \\`doctor.docs-missing\\`, \\`doctor.services-missing\\`, and\n  the three that say the fleet map cannot be read at all —\n  \\`doctor.landscape-merge-conflict\\`, \\`doctor.landscape-invalid\\` and\n  \\`doctor.landscape-unreadable\\`. It also grades what a WRITE that did not finish\n  left in the docs repo, reported as \\`writePath\\` beside the findings:\n  \\`doctor.docs-locked\\`, \\`doctor.commit-interrupted\\`, \\`doctor.commit-unreadable\\`\n  and \\`doctor.staging-temps\\`. When this repo is a service repo that same scan\n  covers \\`<gherkinDir>/loam/\\`, the root \\`loam gherkin\\` commits into.\n  Accessibility, portability and incomplete binding stay warnings:\n  \\`doctor.docs-unreadable\\`, \\`doctor.docs-readonly\\`, \\`doctor.docs-absolute\\`,\n  \\`doctor.inventory-unreadable\\`, \\`doctor.landscape-missing\\`,\n  \\`doctor.service-unbound\\` (never raised inside the docs repo itself, where\n  having no service binding is the correct state), \\`doctor.service-unknown\\`\n  (the same state \\`loam status\\` reports as \\`next.adopt-bound\\` — or, when an\n  active feature introduces the service, as that feature's \\`next.feature\\`, and\n  then the finding names the feature and \\`currentService.introducedBy\\` lists\n  it: there is nothing to adopt),\n  \\`doctor.likec4-config-missing\\`, and the two about this repo's own generated\n  command and skill files: \\`doctor.agent-files-missing\\` and\n  \\`doctor.agent-files-stale\\`.\n  The second one fires only for a file whose body differs from the one this\n  loam writes AND whose stamp is missing or older — so after an upgrade, expect\n  it when the release changed the pointer text, never for a stamp-only\n  difference, and never for an edited body under a current stamp (that stamp is\n  the record that somebody reviewed it). Re-running \\`loam init\\` refreshes an\n  unchanged pointer only when its current bytes still match the digest\n  recorded in \\`loam.json\\`; an unrecorded or customized file stays in place\n  for a human to review.\n- \\`loam rebase <FEAT>\\` writes the baseline pins: \\`Based-On:\\` under every\n  MODIFIED/REMOVED requirement in the feature's spec deltas, and\n  \\`x-loam-based-on\\` on every operation in its openapi.yaml, from the living text\n  as it stands right now. Run it when you finish authoring a delta and again\n  after you resolve a collision — it is the one mechanism standing between two\n  features in flight and silently reverting each other's landed work. It refuses\n  rather than inventing a pin, and re-pinning is not resolving: see\n  \"The requirement baseline\". An operation or event slot the delta spells that\n  an ARCHIVED feature retired is not pinned as new: rebase prints the\n  \\`openapi.op-revived\\` / \\`asyncapi.slot-revived\\` finding (and \\`revived[]\\` in\n  \\`--json\\`) and leaves the call — delete the quote, or re-add on purpose — to\n  you. It judges the delta as it will write it, pins included, so a quote its\n  own repin turns into an edit — repinned over whatever lives now at an\n  address an archived feature moved the entry away from — is in that list too,\n  under \\`--dry-run\\` as well.\n- \\`loam dependencies [<FEAT>]\\` derives the ordering of the features in flight\n  from the artifacts themselves — requirement identities and OpenAPI\n  operationIds, never from validator prose. It is the answer to every\n  \"another feature in flight does this first\" finding, and to\n  \\`delta.added-conflict\\` / \\`delta.modified-conflict\\`, which no ordering fixes.\n- \\`loam explore [<service>...]\\` reads the fleet around a change nobody has\n  written down yet, and writes nothing. It exists because \\`loam new\\`'s\n  \\`--touches\\` list is the hardest call in the cycle and the only one nothing\n  downstream catches: a list short by one service produces a feature that\n  validates, archives and ships with a consumer nobody updated. What it derives\n  is mechanical — the one-hop ring, each service's rung, its living operations,\n  who already calls whom, and which active features cover the same services. It\n  does NOT decide which of those neighbours you actually change; that is a\n  judgement about intent, and loam does not make those. \\`--op <operationId>\\`\n  seeds from the operation's defining service; \\`--capability <id>\\` (repeatable)\n  seeds from a declared capability's realizing services, and an id that seeds\n  nothing lands in the additive \\`unresolvedCapabilities\\` — beside\n  \\`loam list capabilities\\`, the rollup those seeds are read from.\n- \\`loam seed --from fleet.yaml\\` is the onboarding entry point for an empty\n  fleet: a tiny human-authored YAML — a \\`services:\\` list of ids, optional\n  \\`subsystems:\\`, \\`externals:\\` and \\`calls:\\` lines like\n  \\`checkout -> payments\\` — templated mechanically into\n  architecture/landscape.likec4 (one bound element per service, plain edges, no\n  guessed operationIds) plus one services/<id>/ directory per service, in one\n  journaled transaction. Not an extractor: the human stated every fact, and\n  \"who calls whom\" is the one thing no generator can read off a repository.\n  The seeded landscape carries a line-1 stamp; while it stands unedited,\n  editing fleet.yaml and re-running regenerates the map, and the first hand\n  edit anywhere in the file, including above the stub, makes it yours — seed\n  then refuses \\`seed-landscape-edited\\`\n  rather than overwrite. So seed is a day-zero step: fleet.yaml has no spelling\n  for \\`metadata { op }\\`, and once an edge carries one the map grows through\n  adopt briefs and feature C4 deltas, not through seed. Then adopt each\n  service: \\`loam adopt --service <id>\\`.\n- \\`loam instructions [<page>] [args...]\\` prints one of the six workflow\n  protocols — \\`loam-adopt\\`, \\`loam-feature\\`, \\`loam-implement\\`, \\`loam-check\\`,\n  \\`loam-verify\\`, \\`loam-ship\\` — with \\`$1\\`, \\`$2\\` filled in from the arguments you\n  pass, the \\`loam-report\\` support protocol, or one of the five reference pages —\n  \\`loam-codes\\`, \\`loam-spine\\`, \\`loam-authoring\\`, \\`loam-done-check\\`,\n  \\`loam-drawing\\` — which take no arguments. With no argument at all it lists all three sets. The pages ship\n  inside the binary, so they describe the loam you are about to run rather than\n  the one that scaffolded the repository; the command and skill files\n  \\`loam init\\` writes are pointers at it, and so is AGENTS.md's own\n  \"Reference pages — fetch when needed\" section. It reads no\n  \\`loam.json\\` and no docs repo, deliberately: \\`loam-adopt\\`'s own first step is\n  to run \\`loam init\\` when there is no config, so it cannot be the step that\n  requires one.\n`;\n\n/**\n * The reference page's body, up to the modules that continue it. The bullets\n * are ordered so `status` — the orientation command, the one to run when you\n * have lost the session — is read first.\n */\nexport const CODE_MAP = MAP_INTRO + STATUS_COMMAND + MAP_REST;\n"]}

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

@@ -0,0 +1,46 @@
+/**
+ * The `loam explain` entry of the command map — its own section module for
+ * `./lenses/gate.ts`'s exact reason: command-map.ts sits against the 300-line
+ * limit, so the vocabulary command's documentation lives one package down and
+ * is concatenated after the map. It introduces no codes of its own: every
+ * subject it answers for is a code or term that already exists elsewhere,
+ * which is the point of the command.
+ *
+ * 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 term names below are HAND-LISTED, unlike the interpolated copies in
+ * commands/explain and core/mcp/tools — importing core/explain/terms.ts from
+ * here would close a package cycle, because terms.ts reads its pin sources
+ * from this very package's siblings (agents-md → map → explain → agents-md).
+ * test/explain.test.ts pins this string against TERMS instead: a term added
+ * to the registry without a name here fails there, loudly. They are written
+ * as plain words, not backticked, on purpose: everywhere else on this page a
+ * backticked dotted name is a finding code, and the five claim kinds are
+ * spelled exactly like one without being one.
+ */
+export const EXPLAIN_COMMAND = `- \`loam explain [<subject>]\` answers "what does this mean and what do I do
+  about it" from the binary itself: a finding code (\`spine.op-undefined\`), a
+  refusal code (\`docs-busy\`), or a concept term — the words loam prints to a
+  person. \`loam explain\` alone lists the terms under five headings: the
+  stages \`loam status\` reports (stage, which also answers missing, blocked and
+  draft; ready; done), the done-check \`loam verify\` asks (claim; its five kinds
+  service.exists, api.exposes, event.declares, c4.calls and scenario.tested;
+  attested; verified), the work packet \`loam tasks\` lists (unit, frontier,
+  describe, generate, implement), and the documents (delta, baseline, spine,
+  axis, coherence, vouch, maturity, which also answers its rungs empty,
+  partial, documented and sourced), and the picture (kind, which also answers
+  each relationship kind from publishes to connects; legend; overview;
+  purpose). For finding codes the meaning-and-fix
+  text IS the /loam-check fix table, parsed at runtime from the same body \`loam instructions loam-check\` prints, so the
+  two can never disagree; a code graded in more than one table (service scope
+  and \`loam archive\` plan time, say) explains every context it appears in,
+  and refusal meanings cover every \`error.code\` the envelope can carry. It
+  reads no \`loam.json\` and no docs repo, exactly like \`loam instructions\`
+  and for the same reason: the vocabulary wall is hit before the wiring
+  exists. An unknown subject refuses \`unknown-target\` and offers the closest
+  known names.
+`;
+//# sourceMappingURL=explain.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;CAqB9B,CAAC","sourcesContent":["/**\n * The `loam explain` entry of the command map — its own section module for\n * `./lenses/gate.ts`'s exact reason: command-map.ts sits against the 300-line\n * limit, so the vocabulary command's documentation lives one package down and\n * is concatenated after the map. It introduces no codes of its own: every\n * subject it answers for is a code or term that already exists elsewhere,\n * which is the point of the command.\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 term names below are HAND-LISTED, unlike the interpolated copies in\n * commands/explain and core/mcp/tools — importing core/explain/terms.ts from\n * here would close a package cycle, because terms.ts reads its pin sources\n * from this very package's siblings (agents-md → map → explain → agents-md).\n * test/explain.test.ts pins this string against TERMS instead: a term added\n * to the registry without a name here fails there, loudly. They are written\n * as plain words, not backticked, on purpose: everywhere else on this page a\n * backticked dotted name is a finding code, and the five claim kinds are\n * spelled exactly like one without being one.\n */\nexport const EXPLAIN_COMMAND = `- \\`loam explain [<subject>]\\` answers \"what does this mean and what do I do\n  about it\" from the binary itself: a finding code (\\`spine.op-undefined\\`), a\n  refusal code (\\`docs-busy\\`), or a concept term — the words loam prints to a\n  person. \\`loam explain\\` alone lists the terms under five headings: the\n  stages \\`loam status\\` reports (stage, which also answers missing, blocked and\n  draft; ready; done), the done-check \\`loam verify\\` asks (claim; its five kinds\n  service.exists, api.exposes, event.declares, c4.calls and scenario.tested;\n  attested; verified), the work packet \\`loam tasks\\` lists (unit, frontier,\n  describe, generate, implement), and the documents (delta, baseline, spine,\n  axis, coherence, vouch, maturity, which also answers its rungs empty,\n  partial, documented and sourced), and the picture (kind, which also answers\n  each relationship kind from publishes to connects; legend; overview;\n  purpose). For finding codes the meaning-and-fix\n  text IS the /loam-check fix table, parsed at runtime from the same body \\`loam instructions loam-check\\` prints, so the\n  two can never disagree; a code graded in more than one table (service scope\n  and \\`loam archive\\` plan time, say) explains every context it appears in,\n  and refusal meanings cover every \\`error.code\\` the envelope can carry. It\n  reads no \\`loam.json\\` and no docs repo, exactly like \\`loam instructions\\`\n  and for the same reason: the vocabulary wall is hit before the wiring\n  exists. An unknown subject refuses \\`unknown-target\\` and offers the closest\n  known names.\n`;\n"]}

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

@@ -0,0 +1,50 @@
+/**
+ * The `loam context` entry of the command map — one of the three consumer
+ * LENSES this package holds (the agent briefing here, `./gate.ts`'s deploy
+ * pipeline, `./diff.ts`'s PR review), the family carved out of `../` when the
+ * map package hit its own five-file cap: command-map.ts sits against the
+ * file-line limit, so the pack's documentation lives down here and is
+ * concatenated after the map.
+ *
+ * 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 CONTEXT_COMMAND = `- \`loam context <service>\` assembles the docs slice bound to one service as a
+  single deterministic briefing — the pack an agent loads before working in
+  that service's repository. It writes nothing. One payload carries the living
+  requirements and arch requirements VERBATIM (bodies and scenarios included),
+  the OpenAPI operations with the requirements governing each, the AsyncAPI
+  messages with their send/receive direction, the fleet edges one hop out with
+  the map's own health beside them (\`landscape.present\` is the FILE,
+  \`landscape.parses\` is the whole \`architecture/\` project the renderer loads,
+  as \`loam adopt\` reads it — an empty edge list under a map that does not parse
+  is "nobody could look", never "nobody calls this"), the \`Requires:\` permissions resolved against the
+  vocabulary (an undeclared entry is carried with \`declared: false\`, never
+  refused — and when the vocabulary ITSELF does not read, its parse failure
+  rides beside them, so \`declared: false\` there means nobody could look, not
+  that the claim is wrong), the capabilities this service realizes with the
+  capability vocabulary's own health beside them, maturity and provenance,
+  presence pointers for the runbook/health/ADRs, and every ACTIVE feature's
+  delta over this service in \`loam delta\`'s own shapes. \`--feature <FEAT>\`
+  narrows the in-flight section to that one feature and is echoed back as the
+  \`feature\` key, so a narrowed pack says it is one; a known feature that does
+  not touch the service still projects, with empty sections and its own
+  services list. A service an active feature INTRODUCES (its
+  \`features/<FEAT>/specs/<svc>/\` exists, \`services/<svc>/\` does not yet) is
+  briefed from that feature's delta: the payload carries \`living: false\` and
+  \`introducedBy\`, the living sections are empty, and \`path\` is the feature's
+  \`specs/<svc>/\`. Two features introducing the same service refuse with
+  \`invalid-option\` until \`--feature\` names one. \`loam show <svc>\` and
+  \`loam steps --service <svc>\` answer for such a service the same way, from
+  the delta and marked \`living: false\`. Exit 1 with \`ok: true\` means a
+  document behind the pack did not parse — the fleet map, a living contract, a fleet vocabulary, another
+  service's spec during the capability join, or an included feature's document
+  (a feature whose delta.likec4 does not parse is still INCLUDED, its errors
+  in the payload, because a change nobody can read is in flight, not absent)
+  — and the empty section beside the flag IS the parse failure, not "nothing
+  here". Identical state yields identical bytes, so packs are diffable across
+  runs.
+`;
+//# sourceMappingURL=context.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../../../src/core/agent/agents-md/map/lenses/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmC9B,CAAC","sourcesContent":["/**\n * The `loam context` entry of the command map — one of the three consumer\n * LENSES this package holds (the agent briefing here, `./gate.ts`'s deploy\n * pipeline, `./diff.ts`'s PR review), the family carved out of `../` when the\n * map package hit its own five-file cap: command-map.ts sits against the\n * file-line limit, so the pack's documentation lives down here and is\n * 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,\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 CONTEXT_COMMAND = `- \\`loam context <service>\\` assembles the docs slice bound to one service as a\n  single deterministic briefing — the pack an agent loads before working in\n  that service's repository. It writes nothing. One payload carries the living\n  requirements and arch requirements VERBATIM (bodies and scenarios included),\n  the OpenAPI operations with the requirements governing each, the AsyncAPI\n  messages with their send/receive direction, the fleet edges one hop out with\n  the map's own health beside them (\\`landscape.present\\` is the FILE,\n  \\`landscape.parses\\` is the whole \\`architecture/\\` project the renderer loads,\n  as \\`loam adopt\\` reads it — an empty edge list under a map that does not parse\n  is \"nobody could look\", never \"nobody calls this\"), the \\`Requires:\\` permissions resolved against the\n  vocabulary (an undeclared entry is carried with \\`declared: false\\`, never\n  refused — and when the vocabulary ITSELF does not read, its parse failure\n  rides beside them, so \\`declared: false\\` there means nobody could look, not\n  that the claim is wrong), the capabilities this service realizes with the\n  capability vocabulary's own health beside them, maturity and provenance,\n  presence pointers for the runbook/health/ADRs, and every ACTIVE feature's\n  delta over this service in \\`loam delta\\`'s own shapes. \\`--feature <FEAT>\\`\n  narrows the in-flight section to that one feature and is echoed back as the\n  \\`feature\\` key, so a narrowed pack says it is one; a known feature that does\n  not touch the service still projects, with empty sections and its own\n  services list. A service an active feature INTRODUCES (its\n  \\`features/<FEAT>/specs/<svc>/\\` exists, \\`services/<svc>/\\` does not yet) is\n  briefed from that feature's delta: the payload carries \\`living: false\\` and\n  \\`introducedBy\\`, the living sections are empty, and \\`path\\` is the feature's\n  \\`specs/<svc>/\\`. Two features introducing the same service refuse with\n  \\`invalid-option\\` until \\`--feature\\` names one. \\`loam show <svc>\\` and\n  \\`loam steps --service <svc>\\` answer for such a service the same way, from\n  the delta and marked \\`living: false\\`. Exit 1 with \\`ok: true\\` means a\n  document behind the pack did not parse — the fleet map, a living contract, a fleet vocabulary, another\n  service's spec during the capability join, or an included feature's document\n  (a feature whose delta.likec4 does not parse is still INCLUDED, its errors\n  in the payload, because a change nobody can read is in flight, not absent)\n  — and the empty section beside the flag IS the parse failure, not \"nothing\n  here\". Identical state yields identical bytes, so packs are diffable across\n  runs.\n`;\n"]}

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

@@ -0,0 +1,59 @@
+/**
+ * The `loam diff` entry of the command map — the PR-review lens of this
+ * package, split out for `./context.ts`'s exact reason: command-map.ts sat
+ * against the file-line limit, so the branch-diff surface's documentation
+ * lives down here and is concatenated after the map. It is also the
+ * documentation home of the whole `diff.*` code vocabulary, which
+ * codes-drift requires.
+ *
+ * The codes are grouped by the ARTIFACT they are computed over and not
+ * glossed: that grouping is what nothing else says, while
+ * `loam explain diff.op-removed-consumed` (and every sibling) carries the
+ * meaning, the severity and the fix. See ../../command-map.ts's header for why
+ * the gloss left.
+ *
+ * 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 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\`,
+  \`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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,65 @@
+/**
+ * The `loam gate` entry of the command map — the deploy-pipeline lens of this
+ * package, split out for `./context.ts`'s exact reason: command-map.ts sat
+ * against the file-line limit, so the deploy gate's documentation lives down
+ * here and is concatenated after the map. Its four `gate.*` codes are what
+ * test/codes-drift.test.ts finds here.
+ *
+ * The codes are grouped by CHECK and not glossed: which check raises what is
+ * the payload's own `checks[]` shape and is the unique thing this section
+ * says, while `loam explain gate.partners-unknown` (and every sibling) carries
+ * the meaning, the conditional severity and the fix. See ../../command-map.ts's
+ * header for why the gloss left.
+ *
+ * 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>] [--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
+  merge; gate's verdict is advice to a pipeline loam does not own). In a bound
+  service repo the invocation is literally \`loam gate --json\`; \`--service\`
+  names any other adopted service, and one nobody adopted refuses
+  \`unknown-service\` — recorded evidence cannot answer for it. Four checks, and
+  the code tells you which one spoke. \`partners\` derives the direct joins from
+  the LIVING landscape: \`gate.service-undocumented\`,
+  \`gate.partner-undocumented\` and \`gate.partners-unknown\` — the last one
+  severity-splits on why the map could not answer, so read
+  \`loam explain gate.partners-unknown\` before treating it as advisory. A
+  partner tagged \`#external\` is exempt from the middle one on purpose — its
+  docs are somebody else's — but an ADOPTED service is never exempt, whatever
+  zone the map draws it inside.
+  \`freshness\` re-reports two staleness findings \`validate\` already owns,
+  \`content.stale\` and \`sources.stale\`, over the gated service and its
+  documented partners, plus the one integrity error that makes freshness
+  unjudgeable, \`frontmatter.malformed\`; it decodes the spec bytes itself, so a
+  UTF-16 spec.md is a \`service.unreadable\` error naming the file, never a quiet
+  pass. The rest of provenance stays \`validate\`'s report to make.
+  \`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
+  \`service.unreadable\` / \`feature.unreadable\` instead of killing the report.
+  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 \`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
+  bar — \`vouched\` partners, no attested scenarios — branches on the data
+  rather than waiting for a flag.
+`;
+//# sourceMappingURL=gate.js.map

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

@@ -0,0 +1 @@
+{"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"]}