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

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

@@ -0,0 +1,273 @@
+/**
+ * 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 — used
+ * to be a continuation section beside this one, split off when the two
+ * subjects had grown past one file's ceiling. Nothing assembled it into
+ * anything loam shipped once AGENTS.md became ../agents-md.ts's ORIENTATION,
+ * and it was deleted: that teaching is the `loam-ship` protocol
+ * (../workflows/closing.ts) and ORIENTATION's own "Reading loam's output" and
+ * "Safety and hand-back" sections.
+ *
+ * Codes here are LISTED by the command that raises them, not glossed; the
+ * meanings come from `loam explain <code>`, out of the running binary. See
+ * ./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.
+ *
+ * The last part of the `loam-codes` page, not a section of AGENTS.md any more:
+ * ../workflows/reference/codes.ts assembles that page by PLAIN CONCATENATION —
+ * no join separator — so this string starts at the first character of its
+ * opening line and ends with the newline that closes its last one. Keep that
+ * shape when editing, or two parts glue onto one line on the printed page.
+ */
+export const REFUSALS = `- \`loam audit-openspec <root>\` is the read-only OpenSpec inventory; an explicit
+  \`--write-mapping\` writes a non-overwriting, digest-bound decision skeleton
+  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\`, and
+  \`frontmatter.owner-mismatch\` when one service's spec.md and arch.spec.md name two
+  different owners); a service's spec.md —
+  and its arch.spec.md, same conventions — additionally carries the sources chain
+  (\`sources.absent\`, \`sources.path-missing\`, \`sources.empty\`, \`sources.skipped\`,
+  \`sources.unvouched\`, \`sources.stale\`) plus the two doc-side checks,
+  \`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 service target's family is silent;
+  \`sources.unverifiable-from-here\` already names that blind spot. The record
+  itself lives in the docs repo, so the FEATURE target (\`--feature\`, and every
+  active feature under \`--all\`) raises \`evidence.record-unreadable\` from
+  anywhere — the same warn, about readability only.
+- \`loam archive\` alone reports the breaches only the merge computation can see:
+  \`living.requirement-outside-requirements\`, \`openapi.op-modified\`,
+  \`openapi.path-item-modified\`, \`openapi.component-modified\`,
+  \`openapi.ref-unresolved\`, \`openapi.remove-marker-path-level\`, the event
+  axis's own trio \`asyncapi.message-modified\` / \`asyncapi.channel-modified\` /
+  \`asyncapi.operation-modified\`, \`asyncapi.ref-unresolved\`,
+  \`asyncapi.remove-marker-inline\`, \`openapi.info-not-merged\` /
+  \`asyncapi.info-not-merged\` (the delta spells an \`info\` key the merge never
+  carries) and \`service.no-model\`. Two of those are
+  graded at validate time as well and are STRICTER here —
+  \`openapi.ref-unresolved\` and \`asyncapi.ref-unresolved\` are warnings there and
+  errors here, because the merged document is what would carry the dangling
+  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\`).
+
+A bare \`loam validate\` grades the service \`loam.json\` binds — unless no
+\`services/<id>/\` holds it and an active feature introduces it, which is the
+state of every new service's repository until that feature archives. There is
+no service to grade then: the run validates each introducing feature instead
+(the grade \`--feature\` gives, target for target), says so above the report,
+and \`--json\` carries \`boundService\` — \`{ id, living: false, introducedBy }\`.
+Naming the service, with \`--service <id>\` or the positional, still reads a
+service: that is \`service.unknown\`, and its message names the feature.
+
+Two rendering levers change nothing else: \`loam validate --errors-only\` drops
+the confirmations from the TEXT view (the \`--json\` payload is byte-identical),
+and \`loam list --needs-work\` narrows the service list to the ones with
+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\`, \`capabilities\`, \`glossary\`
+or \`suites\` section is refused (\`invalid-option\`), as is \`--needs-work\` with
+\`features\` or \`suites\`, and a \`[name]\` after any section but \`suites\`.
+
+\`--strict\` (every targeting mode, \`--all\` included) exits 1 when any error
+or warning exists — \`ok\`-severity findings are confirmations and never trip
+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 — each writes only its own
+  \`verification/<svc>.yaml\`, so both attestations survive, on one checkout or
+  on two docs-repo branches merged later. A \`record-unreadable\` names the file
+  that failed and its safe repair; never delete the one-file
+  \`verification.yaml\`, which may hold other services' attestations.
+- \`loam open\`: \`no-members\`, \`binding-duplicate\`, \`already-exists\` (the
+  workspace file, which loam never silently overwrites — pass \`--out\` or
+  \`--force\`) and \`invalid-option\`.
+- \`loam seed --from fleet.yaml\`: \`seed-file-invalid\`, \`seed-duplicate-service\`,
+  \`seed-unknown-subsystem\`, \`seed-landscape-edited\`, \`already-exists\` when a
+  generated views file in \`architecture/\` was written by somebody rather than by
+  loam (no \`// generated by loam\` first line — seed writes nothing at all in that
+  case), and \`unknown-service\` for a call endpoint nothing declares. An existing
+  service directory is never moved, and nothing is ever deleted.
+- \`internal\` — an unexpected throw, the one code with no stable meaning.
+
+\`--all\` reports a target per service, a target per feature in flight, and one target
+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 are not continued here:
+ * the section that once followed this one was never assembled again after
+ * AGENTS.md became ORIENTATION, and was deleted — see this file's header for
+ * where that teaching ships now. */
+//# sourceMappingURL=refusals.js.map

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

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

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

@@ -0,0 +1,203 @@
+/**
+ * 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.
+\`architecture/subsystems.likec4\` and \`architecture/services.likec4\` are both
+GENERATED by \`loam subsystem sync\` — one view per subsystem from the directory
+tree under \`services/\`, and one overview view per service the fleet map draws.
+Scoping aids, never hand-edited and never a second fleet map; each is stale
+(\`subsystem.views-stale\`, one finding per file) until the next \`sync\`. Their one
+styling opt-in is a \`global { styleGroup subsystems { … } }\` — or
+\`styleGroup services\` — declared in any \`.likec4\` under \`architecture/\`, which
+\`sync\` then references. A diagram you author belongs in the landscape or in a
+file of your own name beside it; an authored view \`of\` an element the generated
+file also draws is legal, and the file that sorts first wins the default
+drill-down target while both stay reachable.
+\`services/<id>/\` holds a boundary's living \`model.likec4\`, \`spec.md\`,
+\`arch.spec.md\`, OpenAPI, AsyncAPI, runbook and health facts — and
+\`services/<…>/<id>/usecases/*.likec4\`, the slot for a \`dynamic view\` over that
+service's OWN containers, tagged \`#req-<Requirement-ID>\`; a flow that crosses
+services lives in \`architecture/usecases/\` and is tagged \`#cap-\` instead. Title
+a service use case \`'<subsystem path> / <service id> / <use case>'\` — LikeC4
+splits a view title on \`/\` into browser folders, so that convention lands the
+flow in the same folder as the generated overview of its service. Nothing grades
+the title, and nothing grades the slot's absence: presence is never owed.
+\`features/<FEAT>/\` holds a change in flight: \`intent.md\`, \`delta.likec4\`,
+per-service requirement and contract deltas, and the verification record —
+\`verification/<svc>.yaml\`, one file per attesting service.
+\`features/archive/\` is shipped history.
+
+Living documents are the complete current state. A feature document is a diff
+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. Reports are numbered — \`loam-reports/NNN-YYYY-MM-DD-<slug>.md\`,
+cited by ordinal — and carry a \`Status:\` line, so \`loam doctor\` counts the
+directory and says which ordinal the next report takes. This is support, not a
+seventh lifecycle step.
+
+## The cycle
+
+0. **Wire the repo** — in each service checkout run
+   \`loam init --docs <path-to-docs-repo> --service <id> --agent-profile service\`,
+   then \`loam doctor\`. The service profile writes the five workflows that run
+   beside the code; \`loam-feature\` and \`loam-ship\` stay in the docs repo.
+1. **Adopt** — for an undocumented boundary load \`loam instructions loam-adopt
+   <id>\`, then use \`loam adopt --service <id> --json\`. Write drafts; a person,
+   never an agent, later vouches for them. Draw the map's edges in the same pass:
+   the brief's \`landscape.touched\` is the only place an edgeless element is named,
+   and \`landscape.service-isolated\` (fleet scope) goes quiet on the first edge.
+   Give each edge a direction only from evidence, and draw it as \`connects\` where
+   there is none.
+2. **Understand** — start or resume with \`loam status --json\`; its ordered
+   \`next[]\` is the work queue. Read \`next[0].execution\`: run it only when
+   \`runnable\` is true; otherwise use \`kind\`, \`cwd\`, \`needs\` and \`after\`
+   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;
+   \`loam tasks <FEAT> --service <id> --next --json\` is the next open unit of it —
+   its \`at\` says whether you owe a scenario, a generated suite or code, and
+   \`done.check\` is the fact that closes it. In that
+   service checkout, \`loam gherkin <FEAT>\` emits its executable scenarios.
+7. **Verify** — \`loam verify <FEAT> --json\` is the checklist. Record evidence
+   from each affected service's own checkout. Read
+   \`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.
+- \`loam instructions loam-drawing\` — relationship kinds and arrow direction, the
+  legend, and overview views a person can read. Read it before drawing an edge.
+
+Bare \`loam instructions\` lists the six workflows, the separate \`loam-report\`
+support protocol and these references. Generated agent command/skill files are
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../../../src/core/agent/agents-md.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8LnB,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,eAAe,CAAC,YAAY,CAAC,KAAK,WAAW,EAAE,CAAC","sourcesContent":["/**\n * The small, always-loaded orientation contract for a loam docs repository.\n *\n * Detailed grammars and workflows live behind `loam instructions`: those pages\n * describe the binary that is about to run, while this file is written once and\n * may be loaded into every agent turn for years. Keep only enough here to form\n * the next question, find the relevant page, and avoid an unsafe write.\n */\nimport { agentsStampLine } from \"./agents-stamp.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\n\nconst ORIENTATION = `# Working in this docs repo\n\nThis is a **loam** docs repo: plain files are the shared source of truth for a governed software\nfleet's architecture, requirements, contracts and verification evidence. A service may be a modular monolith, a network service, a CLI or a worker.\nloam has no server or database. Delete it and the documents still make sense.\n\n## What is where\n\n\\`architecture/landscape.likec4\\` is the fleet map, and\n\\`architecture/adrs/\\` optional system-level decisions — only their links are graded.\n\\`architecture/subsystems.likec4\\` and \\`architecture/services.likec4\\` are both\nGENERATED by \\`loam subsystem sync\\` — one view per subsystem from the directory\ntree under \\`services/\\`, and one overview view per service the fleet map draws.\nScoping aids, never hand-edited and never a second fleet map; each is stale\n(\\`subsystem.views-stale\\`, one finding per file) until the next \\`sync\\`. Their one\nstyling opt-in is a \\`global { styleGroup subsystems { … } }\\` — or\n\\`styleGroup services\\` — declared in any \\`.likec4\\` under \\`architecture/\\`, which\n\\`sync\\` then references. A diagram you author belongs in the landscape or in a\nfile of your own name beside it; an authored view \\`of\\` an element the generated\nfile also draws is legal, and the file that sorts first wins the default\ndrill-down target while both stay reachable.\n\\`services/<id>/\\` holds a boundary's living \\`model.likec4\\`, \\`spec.md\\`,\n\\`arch.spec.md\\`, OpenAPI, AsyncAPI, runbook and health facts — and\n\\`services/<…>/<id>/usecases/*.likec4\\`, the slot for a \\`dynamic view\\` over that\nservice's OWN containers, tagged \\`#req-<Requirement-ID>\\`; a flow that crosses\nservices lives in \\`architecture/usecases/\\` and is tagged \\`#cap-\\` instead. Title\na service use case \\`'<subsystem path> / <service id> / <use case>'\\` — LikeC4\nsplits a view title on \\`/\\` into browser folders, so that convention lands the\nflow in the same folder as the generated overview of its service. Nothing grades\nthe title, and nothing grades the slot's absence: presence is never owed.\n\\`features/<FEAT>/\\` holds a change in flight: \\`intent.md\\`, \\`delta.likec4\\`,\nper-service requirement and contract deltas, and the verification record —\n\\`verification/<svc>.yaml\\`, one file per attesting service.\n\\`features/archive/\\` is shipped history.\n\nLiving documents are the complete current state. A feature document is a diff\nagainst them, reviewed as a diff; \\`loam archive\\` folds it into living state.\nDo not hand-edit the living landscape to add a feature change.\n\n## Linking between documents\n\nDocuments join with **standard markdown links** whose targets are real relative\npaths, for example \\`[decision](../adrs/ADR-001.md)\\`. They render in pull-request\nreview instead of showing literal brackets,\nand make “does this link resolve” a filesystem question; \\`[[Wikilinks]]\\` would\nrequire shortest-unique-path guessing.\nObsidian supports markdown links, autocomplete and rename-tracking when its\nwikilink setting is off. \\`link.unresolved\\` grades missing targets and CASE\n**is** graded; links outside this repository, \\`#section\\` targets, a fenced code\nblock or an inline code span are deliberately not graded.\n\n## \\`loam.json\\` — the wiring\n\nEvery repository commits its own \\`loam.json\\`:\n\n\\`{ \"docsDir\": \"../docs\", \"service\": \"payment-service\", \"gherkinDir\": \"features\" }\\`\n\n\\`docsDir\\` is stored exactly as it was passed and resolved against the directory\nholding the \\`loam.json\\`, so a relative path survives a clone; an absolute one\nraises \\`doctor.docs-absolute\\`. \\`service\\` binds a service checkout to the one boundary\nit may write evidence for. \\`gherkinDir\\` is optional. \\`agentTools\\` and\n\\`agentProfile\\` record which agent surfaces and workflow subset init manages;\n\\`agentFiles\\` records digests so unchanged generated pointers can refresh while\ncustomized ones remain untouched. With no config, loam refuses with \\`no-config\\`\nrather than guessing.\n\n\\`loam init --docs <dir>\\` **joins** an existing docs repo. Add \\`--create\\` only\nwhen creating a new one; a typo must not scaffold a second source of truth.\n\n## Starting from chat\n\nThere are two equivalent entry points into the same version-matched protocol.\nPrefer the explicit one when a user wants a predictable lifecycle: invoke\n\\`/loam-feature <FEAT> \"<title>\"\\` to propose, \\`/loam-implement <FEAT> [service]\\`\nto build, \\`/loam-check\\` and \\`/loam-verify <FEAT>\\` to grade it, and\n\\`/loam-ship <FEAT>\\` to finish. Most hosts use that flat slash\nspelling; Gemini uses \\`/loam:feature\\`, Amazon Q uses \\`@loam-feature\\`, and a\nskills-only host can invoke \\`$loam-feature\\`. Natural-language requests may load\nthe matching Agent Skill instead. Once either entry point is selected, the agent\ndrives the internal status/edit/validate loop and asks the user only for a real\ndecision or human-only act; the user does not have to type every loam command.\n\nIf loam or an agent integration behaves unexpectedly, invoke \\`/loam-report\\` (or\nload \\`$loam-report\\` on a skills-only host). It collects a sanitized, reproducible\nMarkdown report under \\`loam-reports/\\` without repairing the repository, retrying a\nwriter or uploading anything. Reports are numbered — \\`loam-reports/NNN-YYYY-MM-DD-<slug>.md\\`,\ncited by ordinal — and carry a \\`Status:\\` line, so \\`loam doctor\\` counts the\ndirectory and says which ordinal the next report takes. This is support, not a\nseventh lifecycle step.\n\n## The cycle\n\n0. **Wire the repo** — in each service checkout run\n   \\`loam init --docs <path-to-docs-repo> --service <id> --agent-profile service\\`,\n   then \\`loam doctor\\`. The service profile writes the five workflows that run\n   beside the code; \\`loam-feature\\` and \\`loam-ship\\` stay in the docs repo.\n1. **Adopt** — for an undocumented boundary load \\`loam instructions loam-adopt\n   <id>\\`, then use \\`loam adopt --service <id> --json\\`. Write drafts; a person,\n   never an agent, later vouches for them. Draw the map's edges in the same pass:\n   the brief's \\`landscape.touched\\` is the only place an edgeless element is named,\n   and \\`landscape.service-isolated\\` (fleet scope) goes quiet on the first edge.\n   Give each edge a direction only from evidence, and draw it as \\`connects\\` where\n   there is none.\n2. **Understand** — start or resume with \\`loam status --json\\`; its ordered\n   \\`next[]\\` is the work queue. Read \\`next[0].execution\\`: run it only when\n   \\`runnable\\` is true; otherwise use \\`kind\\`, \\`cwd\\`, \\`needs\\` and \\`after\\`\n   to complete the edit or external-repo step. Use \\`loam list --json\\`, \\`loam show <id> --json\\`\n   and \\`loam explore <id> --json\\` before proposing a change. Never propose a\n   change to a service you have not read.\n3. **Scaffold** — load \\`loam instructions loam-feature <FEAT>\\`, then run\n   \\`loam new <FEAT> --title \"...\" --touches <service>\\`.\n4. **Author** — fill the scaffolded TODOs and run \\`loam rebase <FEAT>\\` after\n   reading the living baselines. The exact joins and authoring grammars are in\n   the reference pages below.\n5. **Check** — load \\`loam instructions loam-check --no-fix-tables\\`, run\n   \\`loam validate <FEAT> --json\\`, and use \\`loam explain <code>\\` for reported\n   codes. \\`loam dependencies --json\\` names features that must archive first.\n6. **Build** — load \\`loam instructions loam-implement <FEAT>\\`.\n   \\`loam delta <FEAT> --service <id> --json\\` is one service's task;\n   \\`loam tasks <FEAT> --service <id> --next --json\\` is the next open unit of it —\n   its \\`at\\` says whether you owe a scenario, a generated suite or code, and\n   \\`done.check\\` is the fact that closes it. In that\n   service checkout, \\`loam gherkin <FEAT>\\` emits its executable scenarios.\n7. **Verify** — \\`loam verify <FEAT> --json\\` is the checklist. Record evidence\n   from each affected service's own checkout. Read\n   \\`loam instructions loam-done-check\\` before recording anything.\n8. **Ship** — load \\`loam instructions loam-ship <FEAT>\\`; begin with\n   \\`loam archive <FEAT> --dry-run --json\\`, then archive only after the code is\n   merged and the plan is the one reviewed.\n\n## Reading loam's output\n\nEvery command takes \\`--json\\`. The envelope has \\`contractVersion\\`, \\`ok\\` and,\non refusal, \\`error.code\\`. Unknown flags are \\`invalid-option\\`; \\`--help\\` and\n\\`--version\\` pass through. Branch on stable codes, never message prose.\n\nValidation \\`findings[]\\` carry \\`severity\\`; archive-related findings also carry\n\\`gates\\`. Severity and gating are two different questions: errors invalidate,\nwhile \\`gates: true\\` makes archive refuse — archive is gated on coherence, so a\ngating finding stops it whatever its severity. Advisory warnings never block.\n\\`--approve\\` overrides the gating issues — only those that are judgement calls —\nand never a mechanical loss. For example \\`delta.requirement-not-merged\\` warns but gates;\n\\`living.requirement-outside-requirements\\` cannot be approved, while\n\\`openapi.op-modified\\` is reviewable.\n\n\\`loam status --json\\` orders executable next actions. Findings include structured\n\\`locations[]\\`; use their paths instead of extracting filenames from prose.\n\\`loam show <FEAT> --json\\` includes a \\`review\\` pack with intent, architecture,\ncontracts, dependencies, verification, blockers and the same next actions.\n\\`loam explain <code> --json\\`\nreturns one code's meaning and fix; \\`loam explain --codes --json\\` lists them.\nWhich codes an INVOCATION can raise is in \\`loam instructions loam-codes\\`.\n\n## The identity rule\n\nA service is the element whose \\`metadata { service '<id>' }\\` matches its\n\\`services/<id>/\\` directory. An exact element id is the legacy fallback. Never\ninfer identity from display names or containment. Relationships join to contracts\nthrough exact ids: OpenAPI \\`operationId\\`, requirement \\`Operations:\\`, and C4\n\\`metadata { op '...' }\\`. Consult \\`loam instructions loam-spine\\` before editing\na join.\n\n## Reference pages — fetch when needed\n\n- \\`loam instructions loam-codes\\` — finding/refusal inventory and fixes.\n- \\`loam instructions loam-spine\\` — operation, message, coverage, permission,\n  capability and baseline joins.\n- \\`loam instructions loam-authoring\\` — arch requirements, generated Gherkin\n  and frontmatter/vouch grammar.\n- \\`loam instructions loam-done-check\\` — verification evidence and verdicts.\n- \\`loam instructions loam-drawing\\` — relationship kinds and arrow direction, the\n  legend, and overview views a person can read. Read it before drawing an edge.\n\nBare \\`loam instructions\\` lists the six workflows, the separate \\`loam-report\\`\nsupport protocol and these references. Generated agent command/skill files are\nsmall pointers to them, so the runtime page wins if an old pointer disagrees with\nthe installed binary. MCP clients can read the same pages as\n\\`loam://orientation\\` and \\`loam://instructions/<name>\\` resources.\n\n## Safety and hand-back\n\nloam's writers are journaled, but the lifecycle still matters. Do not run\n\\`loam vouch\\` for a human, do not invent evidence, do not archive before code is\nmerged, and do not edit generated files under \\`<gherkinDir>/loam/\\` by hand.\n\\`loam unarchive <FEAT>\\` is the supported undo. To abandon a feature that was\nnever archived, review it and use \\`git rm -r features/<FEAT>\\`; loam deliberately\nhas no destructive drop command.\n\nFinish by reporting remaining warnings, unverifiable claims, files or directories\nyou did not inspect, and the exact human action still owed.\n`;\n\nexport const AGENTS_MD = `${agentsStampLine(LOAM_VERSION)}\\n${ORIENTATION}`;\n"]}

package/dist/core/{agents-stamp.js → agent/agents-stamp.js}

@@ -4,6 +4,16 @@ export function agentsStampLine(version) {
 }
 /** Matches a stamp line anywhere in the file; the capture is the version text. */
 const STAMP_RE = /<!--\s*generated by loam v(\S+?)\s*-->/;
+/**
+ * `text` with its stamp, when it has one, rewritten to name `version` — every
+ * other byte untouched. What lets a caller ask whether a generated file differs
+ * from what a binary would write in anything BUT the stamp: the pointer files
+ * carry this same line, and a release that changes nothing in their body still
+ * changes it.
+ */
+export function restamped(text, version) {
+    return text.replace(STAMP_RE, agentsStampLine(version));
+}
 /**
  * The version the stamp names, or null when there is no stamp (or one whose
  * version does not read as numbers — unparseable is indistinguishable from
@@ -72,6 +82,56 @@ export function versionTrails(stamp, binary) {
     }
     return comparePre(s.pre, b.pre) < 0;
 }
+/**
+ * Does `stamp` name a version NEWER than the binary reading it? The mirror of
+ * {@link versionTrails}, and a different subject rather than its negation:
+ * equal versions are neither.
+ */
+export function versionAhead(stamp, binary) {
+    return versionTrails(binary, stamp);
+}
+/**
+ * `docs.binary-behind` — this loam is OLDER than the loam that wrote the docs
+ * repo it is reading.
+ *
+ * The false-green this closes is the sharpest one in the product, because it
+ * inverts the meaning of a passing run rather than merely missing a defect.
+ * loam's whole promise is that a token spelled here must be spelled there — so
+ * every check is an existence constraint over a value the parser recognised.
+ * A binary that predates a grammar addition does not FAIL on the newer
+ * directive; it does not see it, produces no value, has nothing to join, and
+ * reports green. The corpus is checked less than it looks, and nothing anywhere
+ * says so. `agents.stale` is the opposite direction and explicitly declines
+ * this case ("that is an old binary, not a stale file") — correctly, because
+ * the fix is different: upgrade loam, do not edit the file.
+ *
+ * A WARNING, not an error, and the reasoning is the `sources.stale` doctrine.
+ * A mixed-version fleet is ordinary — one engineer's global install trails a
+ * release by a week — and failing every command in that repo would be a
+ * refusal aimed at the wrong person on the wrong day. What the message must do
+ * instead is say plainly that a green run from this binary is worth less than
+ * it appears, which no other finding says. A fleet that wants it to gate has
+ * `--strict`, which is exactly the lever that doctrine reserves for this.
+ *
+ * Silent when there is no file, no stamp, or the stamp is equal or older —
+ * every one of those is somebody else's finding.
+ */
+export function binaryBehindFinding(text, binary) {
+    if (text === null)
+        return null;
+    const stamp = agentsStampVersion(text);
+    if (stamp === null || !versionAhead(stamp, binary))
+        return null;
+    return {
+        severity: "warn",
+        code: "docs.binary-behind",
+        message: `This docs repo was written by loam v${stamp}; this binary is v${binary}. A newer loam may check ` +
+            "joins this one cannot parse — an unrecognised directive is read as prose, so it produces no " +
+            "join to fail and this run reports green without having graded it. Treat a pass from this " +
+            `binary as incomplete rather than clean, and upgrade to v${stamp} or later (\`npm i -g @ybotok/loam\`). ` +
+            "Nothing here is wrong with the documents; the reader is behind them.",
+    };
+}
 /**
  * The one finding `loam validate --all` owes the agent contract. `text` is the
  * docs repo's AGENTS.md, or null when there is none — no file means no contract