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

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

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

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

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

package/dist/core/agent/agents-md/shipped/archive-gate.js

@@ -0,0 +1,98 @@
+/**
+ * How a SHIPPED change is gated, undone or dropped: the archive gate,
+ * unarchive, and dropping a feature. The continuation of ../refusals.ts —
+ * that module holds what loam refuses and the error-envelope codes; this one
+ * holds what happens to a feature once the merge is on the table. Split
+ * there because the two subjects were one 300-plus-line file, and the file's
+ * own header already named them separately.
+ *
+ * One section of the AGENTS.md template. ../../agents-md.ts assembles the
+ * document by PLAIN CONCATENATION — no join separator — so this section
+ * starts at the first character of its opening heading and ends with the
+ * newline that closes its last line. Keep that shape when editing, or two
+ * sections glue onto one line in every docs repo loam scaffolds from now on.
+ */
+export const ARCHIVE_GATE = `## The archive gate
+
+The three axes agreeing is called **coherence**, and \`loam validate --feature\` reports
+it as such. \`loam archive\` runs the same coherence check first and refuses a feature
+with GATING issues — every error, plus the rare warning marked \`gates: true\` because
+the merge would silently drop authored content even though the document is legal.
+Advisory warnings never block: archive prints them and proceeds. Each one still names
+something real — usually something the merge will drop or overwrite — so read them
+before the merge runs, not after.
+
+\`--approve\` overrides the gating issues — only those, and archive prints exactly which
+ones it overrode. It is a human decision, not an agent's: if archive refuses, fix the
+breach or hand it back. Two refusals sit outside its reach, because the damage is
+mechanical rather than a judgment about the feature: \`delta.service-id-invalid\` — a
+\`specs/<svc>/\` directory whose name is not a legal service id, which the merge
+would materialise as a \`services/<svc>/\` every loam command then refuses to
+address — and \`c4.service-binding-invalid\` — an explicit \`metadata { service }\`
+binding that breaks the same grammar, on a tagged element or anything nested
+inside its block (the merge splices the whole authored block into the living
+landscape verbatim, untagged children included, and a \`../\` in the binding even
+collapses the archive's \`services/\` probe out of the docs repo). There is
+nothing a judgment call could accept: rename the directory, or fix the binding,
+instead.
+
+Breaches only the merge computation itself can see are reported at plan time,
+after the gate. \`living.requirement-outside-requirements\` (error): the LIVING spec
+holds a requirement outside \`## Requirements\`, and the merge rewrites only that
+section, so the requirement would land in the file twice — \`--approve\` does not
+override it, because the duplication is mechanical, not a judgment call; re-home the
+requirement first. \`openapi.op-modified\` (warn): the feature redefines an operation
+the living OpenAPI already has, and the merge overwrites the living definition
+wholesale.
+
+The OpenAPI merge also carries a \`$ref\` closure rooted in what it actually WROTE
+— the merged operations and the components this delta declares alike: every
+\`#/components/<kind>/<name>\` they reference, recursively with a component's own
+refs included, is copied from the feature document into the living one, so nothing
+lands pointing at a schema that stayed behind. A delta whose whole change is a
+shared schema, with no \`paths\` at all, is merged the same way and by the same
+rules. \`openapi.component-modified\` (warn): a carried component overwrites a
+living one that differs, wholesale, same discipline as an operation.
+\`openapi.ref-unresolved\` (error, \`--approve\` overrides): a ref reachable from the
+merged operations or a merged component resolves in neither document, so merging
+would write a dangling reference. External refs — URLs, file paths, anything not
+starting \`#/\` — are out of scope: left untouched, never gated.
+
+## Taking an archive back
+
+\`loam unarchive <FEAT>\` restores the living docs and re-opens the feature. It works
+by putting bytes back, not by inverting the merge — archive copies every file it is
+about to overwrite into \`features/archive/<FEAT>/.loam-before/\` first, because the
+previous text of a \`MODIFIED\` requirement is written down nowhere else. Do not edit
+or delete that directory, and never reconstruct an old living spec by hand from an
+archived delta: what the requirement said BEFORE is not in there, and a plausible
+reconstruction is a lie the next reader has no way to catch.
+
+Every pre-image is digested when the archive writes it, and re-checked before the
+restore stages anything: \`snapshot-corrupt\` means a pre-image's bytes no longer
+match the digest archive recorded for them, so restoring it would write text
+nobody authored. \`--force\` does NOT override that one — the damage is to the
+undo itself, not to the living docs — and the fix is version control.
+
+It refuses rather than guesses, under codes you can branch on: \`feature-active\` (a
+feature of that id is in flight again), \`snapshot-missing\` (archived before loam
+recorded this — the docs have to come back from version control), \`snapshot-stale\`
+(a merged file changed after the archive, so restoring would revert someone else's
+work). \`--force\` overrides the last one, and like \`--approve\` it is a human's call.
+
+A restore that fails outright splits the same way archive's does: \`restore-failed\`
+means nothing was restored or everything was rolled back — the living docs are
+unchanged, fix the reported cause and re-run; \`rollback-incomplete\` means the
+restore failed AND some files could not be put back — stop and hand it to a human,
+the message lists the files to check.
+
+## Dropping a feature
+
+A feature that was never archived is one directory and nothing else: no living doc
+references it until \`loam archive\` merges it. To abandon it, delete the directory —
+\`git rm -r features/<FEAT-dir>\` — and version control keeps the record of the
+attempt. An ARCHIVED feature is the opposite, its content folded into the living
+docs: run \`loam unarchive <FEAT>\` first, then delete. There is no \`loam abandon\`,
+deliberately — a removal that computes nothing is what version control is for.
+`;
+//# sourceMappingURL=archive-gate.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-gate.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/shipped/archive-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkF3B,CAAC","sourcesContent":["/**\n * How a SHIPPED change is gated, undone or dropped: the archive gate,\n * unarchive, and dropping a feature. The continuation of ../refusals.ts —\n * that module holds what loam refuses and the error-envelope codes; this one\n * holds what happens to a feature once the merge is on the table. Split\n * there because the two subjects were one 300-plus-line file, and the file's\n * own header already named them separately.\n *\n * One section of the AGENTS.md template. ../../agents-md.ts assembles the\n * document by PLAIN CONCATENATION — no join separator — so this section\n * starts at the first character of its opening heading and ends with the\n * newline that closes its last line. Keep that shape when editing, or two\n * sections glue onto one line in every docs repo loam scaffolds from now on.\n */\nexport const ARCHIVE_GATE = `## The archive gate\n\nThe three axes agreeing is called **coherence**, and \\`loam validate --feature\\` reports\nit as such. \\`loam archive\\` runs the same coherence check first and refuses a feature\nwith GATING issues — every error, plus the rare warning marked \\`gates: true\\` because\nthe merge would silently drop authored content even though the document is legal.\nAdvisory warnings never block: archive prints them and proceeds. Each one still names\nsomething real — usually something the merge will drop or overwrite — so read them\nbefore the merge runs, not after.\n\n\\`--approve\\` overrides the gating issues — only those, and archive prints exactly which\nones it overrode. It is a human decision, not an agent's: if archive refuses, fix the\nbreach or hand it back. Two refusals sit outside its reach, because the damage is\nmechanical rather than a judgment about the feature: \\`delta.service-id-invalid\\` — a\n\\`specs/<svc>/\\` directory whose name is not a legal service id, which the merge\nwould materialise as a \\`services/<svc>/\\` every loam command then refuses to\naddress — and \\`c4.service-binding-invalid\\` — an explicit \\`metadata { service }\\`\nbinding that breaks the same grammar, on a tagged element or anything nested\ninside its block (the merge splices the whole authored block into the living\nlandscape verbatim, untagged children included, and a \\`../\\` in the binding even\ncollapses the archive's \\`services/\\` probe out of the docs repo). There is\nnothing a judgment call could accept: rename the directory, or fix the binding,\ninstead.\n\nBreaches only the merge computation itself can see are reported at plan time,\nafter the gate. \\`living.requirement-outside-requirements\\` (error): the LIVING spec\nholds a requirement outside \\`## Requirements\\`, and the merge rewrites only that\nsection, so the requirement would land in the file twice — \\`--approve\\` does not\noverride it, because the duplication is mechanical, not a judgment call; re-home the\nrequirement first. \\`openapi.op-modified\\` (warn): the feature redefines an operation\nthe living OpenAPI already has, and the merge overwrites the living definition\nwholesale.\n\nThe OpenAPI merge also carries a \\`$ref\\` closure rooted in what it actually WROTE\n— the merged operations and the components this delta declares alike: every\n\\`#/components/<kind>/<name>\\` they reference, recursively with a component's own\nrefs included, is copied from the feature document into the living one, so nothing\nlands pointing at a schema that stayed behind. A delta whose whole change is a\nshared schema, with no \\`paths\\` at all, is merged the same way and by the same\nrules. \\`openapi.component-modified\\` (warn): a carried component overwrites a\nliving one that differs, wholesale, same discipline as an operation.\n\\`openapi.ref-unresolved\\` (error, \\`--approve\\` overrides): a ref reachable from the\nmerged operations or a merged component resolves in neither document, so merging\nwould write a dangling reference. External refs — URLs, file paths, anything not\nstarting \\`#/\\` — are out of scope: left untouched, never gated.\n\n## Taking an archive back\n\n\\`loam unarchive <FEAT>\\` restores the living docs and re-opens the feature. It works\nby putting bytes back, not by inverting the merge — archive copies every file it is\nabout to overwrite into \\`features/archive/<FEAT>/.loam-before/\\` first, because the\nprevious text of a \\`MODIFIED\\` requirement is written down nowhere else. Do not edit\nor delete that directory, and never reconstruct an old living spec by hand from an\narchived delta: what the requirement said BEFORE is not in there, and a plausible\nreconstruction is a lie the next reader has no way to catch.\n\nEvery pre-image is digested when the archive writes it, and re-checked before the\nrestore stages anything: \\`snapshot-corrupt\\` means a pre-image's bytes no longer\nmatch the digest archive recorded for them, so restoring it would write text\nnobody authored. \\`--force\\` does NOT override that one — the damage is to the\nundo itself, not to the living docs — and the fix is version control.\n\nIt refuses rather than guesses, under codes you can branch on: \\`feature-active\\` (a\nfeature of that id is in flight again), \\`snapshot-missing\\` (archived before loam\nrecorded this — the docs have to come back from version control), \\`snapshot-stale\\`\n(a merged file changed after the archive, so restoring would revert someone else's\nwork). \\`--force\\` overrides the last one, and like \\`--approve\\` it is a human's call.\n\nA restore that fails outright splits the same way archive's does: \\`restore-failed\\`\nmeans nothing was restored or everything was rolled back — the living docs are\nunchanged, fix the reported cause and re-run; \\`rollback-incomplete\\` means the\nrestore failed AND some files could not be put back — stop and hand it to a human,\nthe message lists the files to check.\n\n## Dropping a feature\n\nA feature that was never archived is one directory and nothing else: no living doc\nreferences it until \\`loam archive\\` merges it. To abandon it, delete the directory —\n\\`git rm -r features/<FEAT-dir>\\` — and version control keeps the record of the\nattempt. An ARCHIVED feature is the opposite, its content folded into the living\ndocs: run \\`loam unarchive <FEAT>\\` first, then delete. There is no \\`loam abandon\\`,\ndeliberately — a removal that computes nothing is what version control is for.\n`;\n"]}

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

@@ -0,0 +1,40 @@
+/**
+ * Which element in the C4 model IS which service — the binding rule, and the
+ * two-way completeness check `loam validate --all` runs over `services/`.
+ *
+ * This module used to carry the whole ID spine: every join between the
+ * artifacts, the `Based-On:` baseline pins, how to draw a shared broker, and
+ * how to declare a message produced outside the fleet. Those are now the
+ * `loam-spine` reference page (../workflows/reference/spine.ts), printed by
+ * `loam instructions loam-spine` — grammars a reader consults while writing one
+ * document, in a file that was being truncated by two hosts before it reached
+ * them (./command-map.ts's header has the measurement).
+ *
+ * THIS section stayed, and the line between it and the page it lost is worth
+ * saying: an agent cannot read the landscape at all without knowing that a box's
+ * title is its service id unless `metadata { service }` says otherwise. It is
+ * orientation, not reference — it is needed to form the question, not to answer
+ * it.
+ *
+ * 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 SPINE = `## Which element IS which service
+
+An element says which service it is with \`metadata { service 'payment-service' }\`.
+Without one, its **title** is used instead — which is what most of this repo relies
+on, and also the trap: rename a box in a diagram and every check joining it to
+\`services/<svc>/\` silently stops matching. Bind an element whenever its title is
+not exactly the directory name, and prefer binding over renaming a directory.
+
+\`services/\` is the list of services — there is no manifest, and none should be
+added. \`loam validate --all\` compares that list to the landscape both ways: a
+directory nothing draws is an error, and an element with no directory is a warning.
+Systems that are not ours — kafka, a payment gateway — carry \`#external\`, which
+says so once and stops the warning for good.
+
+`;
+//# sourceMappingURL=spine.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spine.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/spine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;;;;CAcpB,CAAC","sourcesContent":["/**\n * Which element in the C4 model IS which service — the binding rule, and the\n * two-way completeness check `loam validate --all` runs over `services/`.\n *\n * This module used to carry the whole ID spine: every join between the\n * artifacts, the `Based-On:` baseline pins, how to draw a shared broker, and\n * how to declare a message produced outside the fleet. Those are now the\n * `loam-spine` reference page (../workflows/reference/spine.ts), printed by\n * `loam instructions loam-spine` — grammars a reader consults while writing one\n * document, in a file that was being truncated by two hosts before it reached\n * them (./command-map.ts's header has the measurement).\n *\n * THIS section stayed, and the line between it and the page it lost is worth\n * saying: an agent cannot read the landscape at all without knowing that a box's\n * title is its service id unless `metadata { service }` says otherwise. It is\n * orientation, not reference — it is needed to form the question, not to answer\n * it.\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 SPINE = `## Which element IS which service\n\nAn element says which service it is with \\`metadata { service 'payment-service' }\\`.\nWithout one, its **title** is used instead — which is what most of this repo relies\non, and also the trap: rename a box in a diagram and every check joining it to\n\\`services/<svc>/\\` silently stops matching. Bind an element whenever its title is\nnot exactly the directory name, and prefer binding over renaming a directory.\n\n\\`services/\\` is the list of services — there is no manifest, and none should be\nadded. \\`loam validate --all\\` compares that list to the landscape both ways: a\ndirectory nothing draws is an error, and an element with no directory is a warning.\nSystems that are not ours — kafka, a payment gateway — carry \\`#external\\`, which\nsays so once and stops the warning for good.\n\n`;\n"]}

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

@@ -0,0 +1,170 @@
+/**
+ * The small, always-loaded orientation contract for a loam docs repository.
+ *
+ * Detailed grammars and workflows live behind `loam instructions`: those pages
+ * describe the binary that is about to run, while this file is written once and
+ * may be loaded into every agent turn for years. Keep only enough here to form
+ * the next question, find the relevant page, and avoid an unsafe write.
+ */
+import { agentsStampLine } from "./agents-stamp.js";
+import { LOAM_VERSION } from "../envelope/version.js";
+const ORIENTATION = `# Working in this docs repo
+
+This is a **loam** docs repo: plain files are the shared source of truth for a governed software
+fleet's architecture, requirements, contracts and verification evidence. A service may be a modular monolith, a network service, a CLI or a worker.
+loam has no server or database. Delete it and the documents still make sense.
+
+## What is where
+
+\`architecture/landscape.likec4\` is the fleet map, and
+\`architecture/adrs/\` optional system-level decisions — only their links are graded.
+\`services/<id>/\` holds a boundary's living \`model.likec4\`, \`spec.md\`,
+\`arch.spec.md\`, OpenAPI, AsyncAPI, runbook and health facts.
+\`features/<FEAT>/\` holds a change in flight: \`intent.md\`, \`delta.likec4\`,
+per-service requirement and contract deltas, and \`verification.yaml\`.
+\`features/archive/\` is shipped history.
+
+Living documents are the complete current state. A feature document is a diff
+against them, reviewed as a diff; \`loam archive\` folds it into living state.
+Do not hand-edit the living landscape to add a feature change.
+
+## Linking between documents
+
+Documents join with **standard markdown links** whose targets are real relative
+paths, for example \`[decision](../adrs/ADR-001.md)\`. They render in pull-request
+review instead of showing literal brackets,
+and make “does this link resolve” a filesystem question; \`[[Wikilinks]]\` would
+require shortest-unique-path guessing.
+Obsidian supports markdown links, autocomplete and rename-tracking when its
+wikilink setting is off. \`link.unresolved\` grades missing targets and CASE
+**is** graded; links outside this repository, \`#section\` targets, a fenced code
+block or an inline code span are deliberately not graded.
+
+## \`loam.json\` — the wiring
+
+Every repository commits its own \`loam.json\`:
+
+\`{ "docsDir": "../docs", "service": "payment-service", "gherkinDir": "features" }\`
+
+\`docsDir\` is stored exactly as it was passed and resolved against the directory
+holding the \`loam.json\`, so a relative path survives a clone; an absolute one
+raises \`doctor.docs-absolute\`. \`service\` binds a service checkout to the one boundary
+it may write evidence for. \`gherkinDir\` is optional. \`agentTools\` and
+\`agentProfile\` record which agent surfaces and workflow subset init manages;
+\`agentFiles\` records digests so unchanged generated pointers can refresh while
+customized ones remain untouched. With no config, loam refuses with \`no-config\`
+rather than guessing.
+
+\`loam init --docs <dir>\` **joins** an existing docs repo. Add \`--create\` only
+when creating a new one; a typo must not scaffold a second source of truth.
+
+## Starting from chat
+
+There are two equivalent entry points into the same version-matched protocol.
+Prefer the explicit one when a user wants a predictable lifecycle: invoke
+\`/loam-feature <FEAT> "<title>"\` to propose, \`/loam-implement <FEAT> [service]\`
+to build, \`/loam-check\` and \`/loam-verify <FEAT>\` to grade it, and
+\`/loam-ship <FEAT>\` to finish. Most hosts use that flat slash
+spelling; Gemini uses \`/loam:feature\`, Amazon Q uses \`@loam-feature\`, and a
+skills-only host can invoke \`$loam-feature\`. Natural-language requests may load
+the matching Agent Skill instead. Once either entry point is selected, the agent
+drives the internal status/edit/validate loop and asks the user only for a real
+decision or human-only act; the user does not have to type every loam command.
+
+If loam or an agent integration behaves unexpectedly, invoke \`/loam-report\` (or
+load \`$loam-report\` on a skills-only host). It collects a sanitized, reproducible
+Markdown report under \`loam-reports/\` without repairing the repository, retrying a
+writer or uploading anything. This is support, not a seventh lifecycle step.
+
+## The cycle
+
+0. **Wire the repo** — in each service checkout run
+   \`loam init --docs <path-to-docs-repo> --service <id>\`, then \`loam doctor\`.
+1. **Adopt** — for an undocumented boundary load \`loam instructions loam-adopt
+   <id>\`, then use \`loam adopt --service <id> --json\`. Write drafts; a person,
+   never an agent, later vouches for them.
+2. **Understand** — start or resume with \`loam status --json\`; its ordered
+   \`next[]\` is the work queue. Read \`next[0].execution\`: run it only when
+   \`runnable\` is true; otherwise use \`kind\`, \`cwd\`, \`needs\` and \`after\`
+   to complete the edit or external-repo step. Use \`loam list --json\`, \`loam show <id> --json\`
+   and \`loam explore <id> --json\` before proposing a change. Never propose a
+   change to a service you have not read.
+3. **Scaffold** — load \`loam instructions loam-feature <FEAT>\`, then run
+   \`loam new <FEAT> --title "..." --touches <service>\`.
+4. **Author** — fill the scaffolded TODOs and run \`loam rebase <FEAT>\` after
+   reading the living baselines. The exact joins and authoring grammars are in
+   the reference pages below.
+5. **Check** — load \`loam instructions loam-check --no-fix-tables\`, run
+   \`loam validate <FEAT> --json\`, and use \`loam explain <code>\` for reported
+   codes. \`loam dependencies --json\` names features that must archive first.
+6. **Build** — load \`loam instructions loam-implement <FEAT>\`.
+   \`loam delta <FEAT> --service <id> --json\` is one service's task; in that
+   service checkout, \`loam gherkin <FEAT>\` emits its executable scenarios.
+7. **Verify** — \`loam verify <FEAT> --json\` is the checklist. Record evidence
+   from each affected service's own checkout. Read
+   \`loam instructions loam-done-check\` before recording anything.
+8. **Ship** — load \`loam instructions loam-ship <FEAT>\`; begin with
+   \`loam archive <FEAT> --dry-run --json\`, then archive only after the code is
+   merged and the plan is the one reviewed.
+
+## Reading loam's output
+
+Every command takes \`--json\`. The envelope has \`contractVersion\`, \`ok\` and,
+on refusal, \`error.code\`. Unknown flags are \`invalid-option\`; \`--help\` and
+\`--version\` pass through. Branch on stable codes, never message prose.
+
+Validation \`findings[]\` carry \`severity\`; archive-related findings also carry
+\`gates\`. Severity and gating are two different questions: errors invalidate,
+while \`gates: true\` makes archive refuse — archive is gated on coherence, so a
+gating finding stops it whatever its severity. Advisory warnings never block.
+\`--approve\` overrides the gating issues — only those that are judgement calls —
+and never a mechanical loss. For example \`delta.requirement-not-merged\` warns but gates;
+\`living.requirement-outside-requirements\` cannot be approved, while
+\`openapi.op-modified\` is reviewable.
+
+\`loam status --json\` orders executable next actions. Findings include structured
+\`locations[]\`; use their paths instead of extracting filenames from prose.
+\`loam show <FEAT> --json\` includes a \`review\` pack with intent, architecture,
+contracts, dependencies, verification, blockers and the same next actions.
+\`loam explain <code> --json\`
+returns one code's meaning and fix; \`loam explain --codes --json\` lists them.
+Which codes an INVOCATION can raise is in \`loam instructions loam-codes\`.
+
+## The identity rule
+
+A service is the element whose \`metadata { service '<id>' }\` matches its
+\`services/<id>/\` directory. An exact element id is the legacy fallback. Never
+infer identity from display names or containment. Relationships join to contracts
+through exact ids: OpenAPI \`operationId\`, requirement \`Operations:\`, and C4
+\`metadata { op '...' }\`. Consult \`loam instructions loam-spine\` before editing
+a join.
+
+## Reference pages — fetch when needed
+
+- \`loam instructions loam-codes\` — finding/refusal inventory and fixes.
+- \`loam instructions loam-spine\` — operation, message, coverage, permission,
+  capability and baseline joins.
+- \`loam instructions loam-authoring\` — arch requirements, generated Gherkin
+  and frontmatter/vouch grammar.
+- \`loam instructions loam-done-check\` — verification evidence and verdicts.
+
+Bare \`loam instructions\` lists the six workflows, the separate \`loam-report\`
+support protocol and these references. Generated agent command/skill files are
+small pointers to them, so the runtime page wins if an old pointer disagrees with
+the installed binary. MCP clients can read the same pages as
+\`loam://orientation\` and \`loam://instructions/<name>\` resources.
+
+## Safety and hand-back
+
+loam's writers are journaled, but the lifecycle still matters. Do not run
+\`loam vouch\` for a human, do not invent evidence, do not archive before code is
+merged, and do not edit generated files under \`<gherkinDir>/loam/\` by hand.
+\`loam unarchive <FEAT>\` is the supported undo. To abandon a feature that was
+never archived, review it and use \`git rm -r features/<FEAT>\`; loam deliberately
+has no destructive drop command.
+
+Finish by reporting remaining warnings, unverifiable claims, files or directories
+you did not inspect, and the exact human action still owed.
+`;
+export const AGENTS_MD = `${agentsStampLine(LOAM_VERSION)}\n${ORIENTATION}`;
+//# sourceMappingURL=agents-md.js.map