@ybotok/loam 0.1.0-beta.2 → 0.2.0-alpha.1

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

@@ -0,0 +1,324 @@
+/**
+ * Reading loam's output, in its two deliveries.
+ *
+ * {@link READING_OUTPUT} and {@link REFERENCE_PAGES} are what AGENTS.md keeps:
+ * the `--json` envelope, the rule to branch on codes rather than prose, and the
+ * index of the pages this file no longer carries. {@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.
+ *
+ * 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.
+ *
+ * READING_OUTPUT and REFERENCE_PAGES are sections of the AGENTS.md template.
+ * ../agents-md.ts assembles the document by PLAIN CONCATENATION — no join
+ * separator — so every section starts at the first character of its opening line
+ * and ends with the newline that closes its last one. Keep that shape when
+ * editing, or two sections glue onto one line in every docs repo loam scaffolds
+ * from now on. CODE_MAP owes the same shape for the same reason, one level up:
+ * reference/codes.ts concatenates it with the modules listed above.
+ */
+import { STATUS_COMMAND } from "./map/status.js";
+/**
+ * The section AGENTS.md keeps. Three facts an agent needs BEFORE it can form a
+ * question — that every command speaks JSON, that the envelope survives a bad
+ * invocation, and that codes are the contract and prose is not — plus the two
+ * places the detail went.
+ */
+export const READING_OUTPUT = `## Reading loam's output
+
+Every command takes \`--json\`, and the envelope holds even when the INVOCATION
+is wrong: with \`--json\` anywhere in the arguments, an unknown flag, unknown
+command or missing argument still yields \`{ ok: false, error: { code:
+"invalid-option" } }\` on stdout with exit 1 (commander's own diagnostic goes
+to stderr; \`--help\` and \`--version\` output pass through untouched). Without
+\`--json\` the same refusal is plain text on stderr with nothing on stdout.
+
+Branch on \`findings[].code\`, never on the prose — the wording changes, the codes do
+not.
+
+**What a code MEANS is one command away**, and the answer 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. Reach for it rather than for a generated pointer:
+this page is printed by the binary that defines the codes.
+
+**Which codes an INVOCATION can raise** is the other half, and it is the one
+thing nothing else carries. It is a reference page rather than a section here:
+\`loam instructions loam-codes\`.
+
+`;
+/**
+ * The index. A reference nobody can find is content deleted with extra steps,
+ * so the exact command is spelled per page rather than described — and
+ * test/agents.test.ts asserts that every name in REFERENCES appears here inside
+ * its own `loam instructions` line, which is what makes a renamed page fail
+ * loudly instead of leaving a pointer at nothing.
+ */
+export const REFERENCE_PAGES = `## The reference pages
+
+This file is the orientation: the layout, the cycle, what gates and what only
+advises, and what the words mean. Four things it does NOT carry — the grammars
+you consult while writing ONE document, and the inventory of what each command
+can report — are **reference pages**, printed by the binary rather than written
+here. That is why: this file is auto-loaded on every session and never
+refreshed, while a page out of the binary describes the loam you are actually
+running, and is read at the one moment it is needed.
+
+- \`loam instructions loam-codes\` — which codes each invocation can raise:
+  \`validate --service\` / \`--feature\` / \`--all\`, \`status\`, \`doctor\`, \`gate\`,
+  \`context\`, \`diff\`, \`explore\`, \`dependencies\`, \`rebase\`, \`seed\`, \`subsystem\`,
+  \`mcp\`, the use-case views, the containment refusals, the error envelope, and
+  the OpenSpec migration surface.
+- \`loam instructions loam-spine\` — the ID spine: every join between the
+  artifacts (\`operationId\`, message name, \`Covers:\`, \`Requires:\`,
+  \`Capability:\`, \`Realizes:\`), the \`Based-On:\` baseline pins on both the
+  requirement and the contract axis, how to draw a shared broker, and how to
+  declare a message produced outside the fleet.
+- \`loam instructions loam-authoring\` — the grammars you author against:
+  the architecture spec axis (\`arch.spec.md\` and its \`Covers:\` line), the
+  generated Gherkin suite, and frontmatter with the vouch chain behind it.
+- \`loam instructions loam-done-check\` — the done-check: how \`loam verify\`
+  derives its claims, the three channels that may answer them, the federated
+  recording form, and what separates **verified** from **attested**.
+
+Each takes no arguments and prints whole. \`loam instructions\` with no argument
+lists them beside the six workflow protocols; \`loam explain <code>\` answers any
+single code without opening a page at all.
+
+`;
+/**
+ * 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.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\`,
+  \`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\`. 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\`.
+  The event axis is graded in feature scope too — the \`asyncapi.*\`
+  baseline/removal/conflict codes plus \`c4-event.*\` and \`spec-event.*\`.
+  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\`, \`landscape.datastore-private\` 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), 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\`),
+  \`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\`.
+  EXPECT the second one on the first \`loam doctor\` after an upgrade. It is not
+  evidence that anything was edited or broken: staleness reads the version
+  stamp only. 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".
+- \`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 makes the file yours — seed then refuses \`seed-landscape-edited\`
+  rather than overwrite. 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, or one of the four reference pages — \`loam-codes\`, \`loam-spine\`,
+  \`loam-authoring\`, \`loam-done-check\` — which take no arguments. With no
+  argument at all it lists both 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 "The reference pages" 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuB7B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B9B,CAAC;AAEF;;;GAGG;AACH,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BjB,CAAC;AAEF,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyJhB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,GAAG,cAAc,GAAG,QAAQ,CAAC","sourcesContent":["/**\n * Reading loam's output, in its two deliveries.\n *\n * {@link READING_OUTPUT} and {@link REFERENCE_PAGES} are what AGENTS.md keeps:\n * the `--json` envelope, the rule to branch on codes rather than prose, and the\n * index of the pages this file no longer carries. {@link CODE_MAP} is the\n * code-by-code map of `status`, `validate`, `doctor`, `rebase`, `dependencies`,\n * `explore`, `seed` and `instructions` — the part `loam instructions loam-codes`\n * prints. ../workflows/reference/codes.ts composes it with `./map/`,\n * `./map/lenses/` and `./refusals.ts`, in exactly the order ../agents-md.ts used\n * to concatenate them, so the assembled page is the section byte for byte.\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 * READING_OUTPUT and REFERENCE_PAGES are sections of the AGENTS.md template.\n * ../agents-md.ts assembles the document by PLAIN CONCATENATION — no join\n * separator — so every section starts at the first character of its opening line\n * and ends with the newline that closes its last one. Keep that shape when\n * editing, or two sections glue onto one line in every docs repo loam scaffolds\n * from now on. CODE_MAP owes the same shape for the same reason, one level up:\n * reference/codes.ts concatenates it with the modules listed above.\n */\nimport { STATUS_COMMAND } from \"./map/status.js\";\n\n/**\n * The section AGENTS.md keeps. Three facts an agent needs BEFORE it can form a\n * question — that every command speaks JSON, that the envelope survives a bad\n * invocation, and that codes are the contract and prose is not — plus the two\n * places the detail went.\n */\nexport const READING_OUTPUT = `## Reading loam's output\n\nEvery command takes \\`--json\\`, and the envelope holds even when the INVOCATION\nis wrong: with \\`--json\\` anywhere in the arguments, an unknown flag, unknown\ncommand or missing argument still yields \\`{ ok: false, error: { code:\n\"invalid-option\" } }\\` on stdout with exit 1 (commander's own diagnostic goes\nto stderr; \\`--help\\` and \\`--version\\` output pass through untouched). Without\n\\`--json\\` the same refusal is plain text on stderr with nothing on stdout.\n\nBranch on \\`findings[].code\\`, never on the prose — the wording changes, the codes do\nnot.\n\n**What a code MEANS is one command away**, and the answer 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. Reach for it rather than for a generated pointer:\nthis page is printed by the binary that defines the codes.\n\n**Which codes an INVOCATION can raise** is the other half, and it is the one\nthing nothing else carries. It is a reference page rather than a section here:\n\\`loam instructions loam-codes\\`.\n\n`;\n\n/**\n * The index. A reference nobody can find is content deleted with extra steps,\n * so the exact command is spelled per page rather than described — and\n * test/agents.test.ts asserts that every name in REFERENCES appears here inside\n * its own `loam instructions` line, which is what makes a renamed page fail\n * loudly instead of leaving a pointer at nothing.\n */\nexport const REFERENCE_PAGES = `## The reference pages\n\nThis file is the orientation: the layout, the cycle, what gates and what only\nadvises, and what the words mean. Four things it does NOT carry — the grammars\nyou consult while writing ONE document, and the inventory of what each command\ncan report — are **reference pages**, printed by the binary rather than written\nhere. That is why: this file is auto-loaded on every session and never\nrefreshed, while a page out of the binary describes the loam you are actually\nrunning, and is read at the one moment it is needed.\n\n- \\`loam instructions loam-codes\\` — which codes each invocation can raise:\n  \\`validate --service\\` / \\`--feature\\` / \\`--all\\`, \\`status\\`, \\`doctor\\`, \\`gate\\`,\n  \\`context\\`, \\`diff\\`, \\`explore\\`, \\`dependencies\\`, \\`rebase\\`, \\`seed\\`, \\`subsystem\\`,\n  \\`mcp\\`, the use-case views, the containment refusals, the error envelope, and\n  the OpenSpec migration surface.\n- \\`loam instructions loam-spine\\` — the ID spine: every join between the\n  artifacts (\\`operationId\\`, message name, \\`Covers:\\`, \\`Requires:\\`,\n  \\`Capability:\\`, \\`Realizes:\\`), the \\`Based-On:\\` baseline pins on both the\n  requirement and the contract axis, how to draw a shared broker, and how to\n  declare a message produced outside the fleet.\n- \\`loam instructions loam-authoring\\` — the grammars you author against:\n  the architecture spec axis (\\`arch.spec.md\\` and its \\`Covers:\\` line), the\n  generated Gherkin suite, and frontmatter with the vouch chain behind it.\n- \\`loam instructions loam-done-check\\` — the done-check: how \\`loam verify\\`\n  derives its claims, the three channels that may answer them, the federated\n  recording form, and what separates **verified** from **attested**.\n\nEach takes no arguments and prints whole. \\`loam instructions\\` with no argument\nlists them beside the six workflow protocols; \\`loam explain <code>\\` answers any\nsingle code without opening a page at all.\n\n`;\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.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\\`,\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\\`. 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\\`.\n  The event axis is graded in feature scope too — the \\`asyncapi.*\\`\n  baseline/removal/conflict codes plus \\`c4-event.*\\` and \\`spec-event.*\\`.\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\\`, \\`landscape.datastore-private\\` 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), 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\\`),\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  EXPECT the second one on the first \\`loam doctor\\` after an upgrade. It is not\n  evidence that anything was edited or broken: staleness reads the version\n  stamp only. Re-running \\`loam init\\` refreshes an unchanged pointer only when\n  its current bytes still match the digest recorded in \\`loam.json\\`; an\n  unrecorded or customized file stays in place 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\".\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 makes the file yours — seed then refuses \\`seed-landscape-edited\\`\n  rather than overwrite. Then adopt each 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, or one of the four reference pages — \\`loam-codes\\`, \\`loam-spine\\`,\n  \\`loam-authoring\\`, \\`loam-done-check\\` — which take no arguments. With no\n  argument at all it lists both sets. The pages ship inside the binary, so they\n  describe the loam you are about to run rather than the one that scaffolded the\n  repository; the command and skill files \\`loam init\\` writes are pointers at it,\n  and so is AGENTS.md's own \"The reference pages\" 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/cycle.js

@@ -0,0 +1,165 @@
+/**
+ * What an agent DOES: the cycle step by step, adopting a service, what is
+ * authored versus derived, and the rules the validator enforces.
+ *
+ * The done-check itself is no longer here — it is `loam instructions
+ * loam-done-check` (../workflows/reference/done-check.ts). Steps 4 and 7 used
+ * to end `See "The requirement baseline"` and `See "The done-check"`, naming
+ * headings that were further down this same file; they now name the COMMAND
+ * that prints them. That is not a rewording for its own sake: a section
+ * reference to a section that left is a pointer at nothing, and a reader who
+ * scrolls looking for it concludes the file is truncated — which, on the two
+ * hosts that truncate silently, is a conclusion they cannot check.
+ *
+ * One section of the AGENTS.md template. ../agents-md.ts assembles the
+ * document by PLAIN CONCATENATION — no join separator — so every section
+ * starts at the first character of its opening line and ends with the newline
+ * that closes its last one. Keep that shape when editing, or two sections glue
+ * onto one line in every docs repo loam scaffolds from now on.
+ */
+export const CYCLE = `## The cycle
+
+0. **Wire the repo** — \`loam init --docs <path-to-docs-repo> --service <id>\` in
+   each service repo, then \`loam doctor\`. Once per repository, before anything
+   else; see "\`loam.json\` — the wiring" above. Every step below runs in a repo
+   that has been through this one.
+1. **Adopt** — a service with no documentation at all starts at
+   \`loam adopt --service <id> --json\`, which briefs you on the baseline to write.
+   See "Adopting a service" below. Once per service, not once per feature.
+2. **Understand** — \`loam status --json\` first if you joined halfway or lost the
+   session: it says what is in flight and what the next step is, for the fleet or
+   for one feature (\`loam status FEAT-101 --json\`). Then \`loam list --json\` and
+   \`loam show <service> --json\`.
+   Then \`loam explore <service> --json\` around the services you believe are
+   involved — it writes nothing and answers the one question the next step takes
+   as an argument: which services this change actually touches. It reports the
+   ring one hop out in the fleet map (\`neighbours\`), how far each service's
+   documentation has got (\`maturity\`), what each already exposes, the features
+   already in flight over the same ground (\`overlaps\`), and the \`loam new\` line
+   the seeds imply (\`scaffold\`). \`--op <operationId>\` seeds from an operation
+   when you know the call but not who owns it.
+   Never propose a change to a service you have not read.
+3. **Scaffold** — \`loam new FEAT-101 --title "..." --touches <existing> --new-service <new>\`.
+   The scaffold leaves a \`delta.likec4\` whose context elements are commented out —
+   a requirements-only feature should DELETE that file rather than ship an empty
+   one — and gives every \`--new-service\` a \`specs/<svc>/arch.spec.md\` alongside.
+   \`--capability <id>\` (repeatable, and it composes with \`--touches\`) scaffolds a
+   capability delta instead of a service one — the inversion of this step, for a
+   change whose BUSINESS side is what is known: open the promise that changes and
+   derive the service work from it. An id the fleet has never named is scaffolded
+   rather than refused, with the close spellings printed beside it; the archive
+   is what creates the living \`capabilities/<id>/spec.md\`.
+4. **Author** the four files the scaffold left as TODO: intent, delta.likec4,
+   a spec.md per service, an openapi.yaml per new service. Finish with
+   \`loam rebase FEAT-101\`: it pins every MODIFIED/REMOVED requirement and every
+   operation in the contract delta to the living version you wrote it against.
+   On the contract axis run it even when you changed nothing but one endpoint —
+   that is exactly what marks the REST of the document as quotation the merge
+   must not write. See \`loam instructions loam-spine\` — "The requirement baseline".
+5. **Check** — \`loam validate FEAT-101 --json\`. Fix every error before writing code.
+   \`loam dependencies --json\` says whether another feature in flight has to
+   archive first.
+6. **Build** — \`loam delta FEAT-101 --service <svc> --json\` is the task for one service:
+   intent, its requirement delta with scenarios verbatim, and the edges around it.
+   In the service's own repo, \`loam gherkin FEAT-101\` then emits those scenarios as
+   \`.feature\` files under \`<gherkinDir>/loam/\` — write step definitions against them
+   **first**, outside \`loam/\`, and implement until they pass.
+   If \`architecture.errors\` is non-empty the payload keeps \`ok: true\` (the command
+   ran) but the exit code is 1: the C4 slice is empty because delta.likec4 did not
+   parse, not because the feature changes no architecture — do not build on it.
+7. **Verify** — \`loam verify FEAT-101 --json\` turns the feature's own promises into a
+   checklist. The scenario claims are answered by the cucumber report
+   (\`--results report.json\`); answer the rest with evidence and record them
+   (\`--record answers.json --service <id>\`), **from each affected service's own
+   repo**. See \`loam instructions loam-done-check\`.
+8. **Ship** — \`loam archive FEAT-101\` once the code is merged. \`--dry-run\` shows
+   every file the merge would write, and writes none of them.
+
+## Adopting a service
+
+\`loam adopt --service <id>\` does not read code and never will. Nothing
+deterministic can look at a legacy service and say what its architecture MEANS,
+and a guessed model is worse than none: everybody downstream has to re-derive it
+to know whether to believe it. So loam takes the half of the job that is
+mechanical — stating the work, and checking the result — and you do the reading.
+
+The brief names every file to write, the grammar each must be in, what the
+landscape already says about the service (bind to those elements, do not draw a
+parallel fleet), the frontmatter, and the checks that follow. It also lists what
+**no** check will ever catch. Read that list: everything on it is a way to be
+wrong quietly, and \`loam validate\` passing means nothing about any of it.
+
+One of the targets is not under \`services/<id>/\`: \`architecture/landscape.likec4\`,
+the fleet map, carried with \`action: "edit"\` and a \`landscape.instruction\`
+spelling out the block this service owes it. That target appears only while
+nothing in the map resolves to the service. **Add to that file; never rewrite
+it** — every other service's elements and edges are in there. A service that is
+fully documented and undrawn is \`landscape.service-unmodelled\` (error) and is
+invisible to every cross-service check: no edge into it can be graded against
+its openapi.yaml, and no feature can draw a call to it.
+
+An adoption ends with two runs, not one: \`loam validate --service <id> --json\`
+for the baseline, then \`loam validate --all --json\` in the docs repo — the
+fleet cross-check the first invocation does not perform is exactly where a
+landscape edit that did not land shows up. Done, stated once: \`--service\`
+clean when run from inside the service's own repo, and \`--all\` reporting no
+\`landscape.*\` finding. The fleet run is never SILENT — \`sources.unverifiable-from-here\`
+(severity ok) appears per service as a confirmation, not work — so "keep going
+until validation is quiet" is the wrong loop; the two runs above are the test.
+
+Two rules the brief repeats and this file will too. An artifact that already
+exists is reported as \`action: "diff"\` — read it and report what disagrees;
+never replace it, because a document somebody wrote is evidence. And everything
+you write is \`status: draft\`: promotion is \`loam vouch\`, run by a person in the
+service's own repo — \`loam vouch --pack --service <id>\` (read-only) preps that read.
+
+## What you author, what loam derives
+
+Authored by hand: \`intent.md\`, \`delta.likec4\`, \`specs/<svc>/spec.md\`,
+\`specs/<svc>/arch.spec.md\`, \`specs/<svc>/openapi.yaml\`, ADRs, runbooks, health.
+
+Written by loam: the merge into \`services/<svc>/spec.md\`, \`services/<svc>/arch.spec.md\`,
+\`services/<svc>/openapi.yaml\` and \`architecture/landscape.likec4\` at archive time.
+
+**Do not hand-edit the living landscape to add a feature's changes.** Put them in a
+delta and archive it — otherwise the change has no intent, no requirement and no
+history behind it.
+
+## Rules the validator enforces
+
+- every requirement has at least one \`#### Scenario:\` — scenarios are the acceptance
+  criteria and the source for tests;
+- every operationId a requirement governs exists in that service's OpenAPI;
+- every C4 edge's \`op\` resolves to an operation the target actually exposes;
+- every operation is governed by some requirement (warning);
+- a "Calls" edge with no \`metadata { op }\` is unlinked (warning);
+- **the map is complete**: every \`services/<svc>/\` has an element in the landscape,
+  and every element that looks like a service has a directory (warning) or is
+  tagged \`#external\`;
+- **the diff applies**: a \`MODIFIED\` or \`REMOVED\` requirement exists in the living
+  spec, an \`ADDED\` one does not, and a section heading matches the grammar exactly;
+- a \`Requirement-ID: <id>\` is optional, but when present it is valid and unique;
+  archive selects by it, so carry the same ID through \`MODIFIED\` to rename a heading;
+- **every requirement in a delta is under a delta section**: one under a prose heading
+  (\`## Behavior\`) is documentation as far as the merge is concerned and is dropped
+  (warning). \`## Requirements\` is exempt — quoting the living state is legal.
+
+That last pair of rules exists because each of its failures used to be silent.
+\`MODIFIED\` of a requirement that does not exist merged as a creation; \`ADDED\` of one
+that does exist REPLACED it, scenarios and all; a near-miss heading like
+\`## ADDED Requirement\` (singular) parses as plain prose, so archive merged nothing and
+said nothing; and a requirement under \`## Behavior\` vanished the same way.
+
+Write the delta section heading on its own line exactly as \`## ADDED Requirements\`.
+The heading is the only thing that gives a requirement its kind: without a matching
+one, archive merges the requirement as nothing.
+
+Severity and gating are two different questions. An ERROR means the document is
+invalid — \`loam validate\` fails. A finding with \`gates: true\` means \`loam archive\`
+will refuse — the merge is unsafe. They usually agree (errors gate, warnings do
+not), and where they diverge the \`--json\` output says so: \`delta.requirement-not-merged\`
+is a warning (the shape is legal OpenSpec) that gates (the merge would drop the
+requirement). Leave a warning standing only deliberately.
+
+`;
+//# sourceMappingURL=cycle.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cycle.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/cycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgJpB,CAAC","sourcesContent":["/**\n * What an agent DOES: the cycle step by step, adopting a service, what is\n * authored versus derived, and the rules the validator enforces.\n *\n * The done-check itself is no longer here — it is `loam instructions\n * loam-done-check` (../workflows/reference/done-check.ts). Steps 4 and 7 used\n * to end `See \"The requirement baseline\"` and `See \"The done-check\"`, naming\n * headings that were further down this same file; they now name the COMMAND\n * that prints them. That is not a rewording for its own sake: a section\n * reference to a section that left is a pointer at nothing, and a reader who\n * scrolls looking for it concludes the file is truncated — which, on the two\n * hosts that truncate silently, is a conclusion they cannot check.\n *\n * One section of the AGENTS.md template. ../agents-md.ts assembles the\n * document by PLAIN CONCATENATION — no join separator — so every section\n * starts at the first character of its opening line and ends with the newline\n * that closes its last one. Keep that shape when editing, or two sections glue\n * onto one line in every docs repo loam scaffolds from now on.\n */\nexport const CYCLE = `## The cycle\n\n0. **Wire the repo** — \\`loam init --docs <path-to-docs-repo> --service <id>\\` in\n   each service repo, then \\`loam doctor\\`. Once per repository, before anything\n   else; see \"\\`loam.json\\` — the wiring\" above. Every step below runs in a repo\n   that has been through this one.\n1. **Adopt** — a service with no documentation at all starts at\n   \\`loam adopt --service <id> --json\\`, which briefs you on the baseline to write.\n   See \"Adopting a service\" below. Once per service, not once per feature.\n2. **Understand** — \\`loam status --json\\` first if you joined halfway or lost the\n   session: it says what is in flight and what the next step is, for the fleet or\n   for one feature (\\`loam status FEAT-101 --json\\`). Then \\`loam list --json\\` and\n   \\`loam show <service> --json\\`.\n   Then \\`loam explore <service> --json\\` around the services you believe are\n   involved — it writes nothing and answers the one question the next step takes\n   as an argument: which services this change actually touches. It reports the\n   ring one hop out in the fleet map (\\`neighbours\\`), how far each service's\n   documentation has got (\\`maturity\\`), what each already exposes, the features\n   already in flight over the same ground (\\`overlaps\\`), and the \\`loam new\\` line\n   the seeds imply (\\`scaffold\\`). \\`--op <operationId>\\` seeds from an operation\n   when you know the call but not who owns it.\n   Never propose a change to a service you have not read.\n3. **Scaffold** — \\`loam new FEAT-101 --title \"...\" --touches <existing> --new-service <new>\\`.\n   The scaffold leaves a \\`delta.likec4\\` whose context elements are commented out —\n   a requirements-only feature should DELETE that file rather than ship an empty\n   one — and gives every \\`--new-service\\` a \\`specs/<svc>/arch.spec.md\\` alongside.\n   \\`--capability <id>\\` (repeatable, and it composes with \\`--touches\\`) scaffolds a\n   capability delta instead of a service one — the inversion of this step, for a\n   change whose BUSINESS side is what is known: open the promise that changes and\n   derive the service work from it. An id the fleet has never named is scaffolded\n   rather than refused, with the close spellings printed beside it; the archive\n   is what creates the living \\`capabilities/<id>/spec.md\\`.\n4. **Author** the four files the scaffold left as TODO: intent, delta.likec4,\n   a spec.md per service, an openapi.yaml per new service. Finish with\n   \\`loam rebase FEAT-101\\`: it pins every MODIFIED/REMOVED requirement and every\n   operation in the contract delta to the living version you wrote it against.\n   On the contract axis run it even when you changed nothing but one endpoint —\n   that is exactly what marks the REST of the document as quotation the merge\n   must not write. See \\`loam instructions loam-spine\\` — \"The requirement baseline\".\n5. **Check** — \\`loam validate FEAT-101 --json\\`. Fix every error before writing code.\n   \\`loam dependencies --json\\` says whether another feature in flight has to\n   archive first.\n6. **Build** — \\`loam delta FEAT-101 --service <svc> --json\\` is the task for one service:\n   intent, its requirement delta with scenarios verbatim, and the edges around it.\n   In the service's own repo, \\`loam gherkin FEAT-101\\` then emits those scenarios as\n   \\`.feature\\` files under \\`<gherkinDir>/loam/\\` — write step definitions against them\n   **first**, outside \\`loam/\\`, and implement until they pass.\n   If \\`architecture.errors\\` is non-empty the payload keeps \\`ok: true\\` (the command\n   ran) but the exit code is 1: the C4 slice is empty because delta.likec4 did not\n   parse, not because the feature changes no architecture — do not build on it.\n7. **Verify** — \\`loam verify FEAT-101 --json\\` turns the feature's own promises into a\n   checklist. The scenario claims are answered by the cucumber report\n   (\\`--results report.json\\`); answer the rest with evidence and record them\n   (\\`--record answers.json --service <id>\\`), **from each affected service's own\n   repo**. See \\`loam instructions loam-done-check\\`.\n8. **Ship** — \\`loam archive FEAT-101\\` once the code is merged. \\`--dry-run\\` shows\n   every file the merge would write, and writes none of them.\n\n## Adopting a service\n\n\\`loam adopt --service <id>\\` does not read code and never will. Nothing\ndeterministic can look at a legacy service and say what its architecture MEANS,\nand a guessed model is worse than none: everybody downstream has to re-derive it\nto know whether to believe it. So loam takes the half of the job that is\nmechanical — stating the work, and checking the result — and you do the reading.\n\nThe brief names every file to write, the grammar each must be in, what the\nlandscape already says about the service (bind to those elements, do not draw a\nparallel fleet), the frontmatter, and the checks that follow. It also lists what\n**no** check will ever catch. Read that list: everything on it is a way to be\nwrong quietly, and \\`loam validate\\` passing means nothing about any of it.\n\nOne of the targets is not under \\`services/<id>/\\`: \\`architecture/landscape.likec4\\`,\nthe fleet map, carried with \\`action: \"edit\"\\` and a \\`landscape.instruction\\`\nspelling out the block this service owes it. That target appears only while\nnothing in the map resolves to the service. **Add to that file; never rewrite\nit** — every other service's elements and edges are in there. A service that is\nfully documented and undrawn is \\`landscape.service-unmodelled\\` (error) and is\ninvisible to every cross-service check: no edge into it can be graded against\nits openapi.yaml, and no feature can draw a call to it.\n\nAn adoption ends with two runs, not one: \\`loam validate --service <id> --json\\`\nfor the baseline, then \\`loam validate --all --json\\` in the docs repo — the\nfleet cross-check the first invocation does not perform is exactly where a\nlandscape edit that did not land shows up. Done, stated once: \\`--service\\`\nclean when run from inside the service's own repo, and \\`--all\\` reporting no\n\\`landscape.*\\` finding. The fleet run is never SILENT — \\`sources.unverifiable-from-here\\`\n(severity ok) appears per service as a confirmation, not work — so \"keep going\nuntil validation is quiet\" is the wrong loop; the two runs above are the test.\n\nTwo rules the brief repeats and this file will too. An artifact that already\nexists is reported as \\`action: \"diff\"\\` — read it and report what disagrees;\nnever replace it, because a document somebody wrote is evidence. And everything\nyou write is \\`status: draft\\`: promotion is \\`loam vouch\\`, run by a person in the\nservice's own repo — \\`loam vouch --pack --service <id>\\` (read-only) preps that read.\n\n## What you author, what loam derives\n\nAuthored by hand: \\`intent.md\\`, \\`delta.likec4\\`, \\`specs/<svc>/spec.md\\`,\n\\`specs/<svc>/arch.spec.md\\`, \\`specs/<svc>/openapi.yaml\\`, ADRs, runbooks, health.\n\nWritten by loam: the merge into \\`services/<svc>/spec.md\\`, \\`services/<svc>/arch.spec.md\\`,\n\\`services/<svc>/openapi.yaml\\` and \\`architecture/landscape.likec4\\` at archive time.\n\n**Do not hand-edit the living landscape to add a feature's changes.** Put them in a\ndelta and archive it — otherwise the change has no intent, no requirement and no\nhistory behind it.\n\n## Rules the validator enforces\n\n- every requirement has at least one \\`#### Scenario:\\` — scenarios are the acceptance\n  criteria and the source for tests;\n- every operationId a requirement governs exists in that service's OpenAPI;\n- every C4 edge's \\`op\\` resolves to an operation the target actually exposes;\n- every operation is governed by some requirement (warning);\n- a \"Calls\" edge with no \\`metadata { op }\\` is unlinked (warning);\n- **the map is complete**: every \\`services/<svc>/\\` has an element in the landscape,\n  and every element that looks like a service has a directory (warning) or is\n  tagged \\`#external\\`;\n- **the diff applies**: a \\`MODIFIED\\` or \\`REMOVED\\` requirement exists in the living\n  spec, an \\`ADDED\\` one does not, and a section heading matches the grammar exactly;\n- a \\`Requirement-ID: <id>\\` is optional, but when present it is valid and unique;\n  archive selects by it, so carry the same ID through \\`MODIFIED\\` to rename a heading;\n- **every requirement in a delta is under a delta section**: one under a prose heading\n  (\\`## Behavior\\`) is documentation as far as the merge is concerned and is dropped\n  (warning). \\`## Requirements\\` is exempt — quoting the living state is legal.\n\nThat last pair of rules exists because each of its failures used to be silent.\n\\`MODIFIED\\` of a requirement that does not exist merged as a creation; \\`ADDED\\` of one\nthat does exist REPLACED it, scenarios and all; a near-miss heading like\n\\`## ADDED Requirement\\` (singular) parses as plain prose, so archive merged nothing and\nsaid nothing; and a requirement under \\`## Behavior\\` vanished the same way.\n\nWrite the delta section heading on its own line exactly as \\`## ADDED Requirements\\`.\nThe heading is the only thing that gives a requirement its kind: without a matching\none, archive merges the requirement as nothing.\n\nSeverity and gating are two different questions. An ERROR means the document is\ninvalid — \\`loam validate\\` fails. A finding with \\`gates: true\\` means \\`loam archive\\`\nwill refuse — the merge is unsafe. They usually agree (errors gate, warnings do\nnot), and where they diverge the \\`--json\\` output says so: \\`delta.requirement-not-merged\\`\nis a warning (the shape is legal OpenSpec) that gates (the merge would drop the\nrequirement). Leave a warning standing only deliberately.\n\n`;\n"]}

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

@@ -0,0 +1,34 @@
+/**
+ * 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 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.
+ *
+ * The six 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.
+ */
+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 — vouch, attested, spine,
+  delta, axis, baseline — and \`loam explain\` alone lists the terms. 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;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;CAa9B,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 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 six 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.\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 — vouch, attested, spine,\n  delta, axis, baseline — and \\`loam explain\\` alone lists the terms. For\n  finding codes the meaning-and-fix text IS the /loam-check fix table, parsed\n  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"]}