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

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

@@ -1,9 +1,13 @@
 /**
  * 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.
+ * 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
@@ -20,11 +24,11 @@
  * 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.
+ * 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
@@ -90,7 +94,9 @@ export const REFUSALS = `- \`loam audit-openspec <root>\` is the read-only OpenS
   \`services-missing\`.
 - Both modes read frontmatter (\`frontmatter.missing\`, \`frontmatter.malformed\`,
   \`frontmatter.field-mismatch\`,
-  \`frontmatter.status-unknown\`, \`frontmatter.field-missing\`); a service's spec.md —
+  \`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,
@@ -103,8 +109,11 @@ export const REFUSALS = `- \`loam audit-openspec <root>\` is the read-only OpenS
   \`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.
+  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\`,
@@ -159,8 +168,9 @@ filtered-and-ordered row order, \`unowned[]\` listing the rows no rule matched,
 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\`).
+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
@@ -221,15 +231,20 @@ follows is the other half — which command raises which:
 - \`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.
+  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\`, and \`unknown-service\` for a
-  call endpoint nothing declares. An existing service directory is never moved,
-  and nothing is ever deleted.
+  \`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
@@ -240,7 +255,8 @@ Three different words for three different questions, and no command conflates th
 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. */
+/* 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

@@ -1 +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"]}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgOvB,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\\` 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\\`, \\`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

@@ -18,19 +18,29 @@ loam has no server or database. Delete it and the documents still make sense.
 
 \`architecture/landscape.likec4\` is the fleet map, and
 \`architecture/adrs/\` optional system-level decisions — only their links are graded.
-\`architecture/subsystems.likec4\` is GENERATED by \`loam subsystem sync\` from the
-directory tree under \`services/\` — one view per subsystem, a scoping aid, never
-hand-edited and never a second fleet map; its one styling opt-in is a
-\`global { styleGroup subsystems { … } }\` 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.
+\`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.
+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 \`verification.yaml\`.
+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
@@ -91,7 +101,9 @@ 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\`.
+   \`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:
@@ -112,7 +124,10 @@ seventh lifecycle step.
    \`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
+   \`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

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

@@ -1 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2KnB,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\\` is GENERATED by \\`loam subsystem sync\\` from the\ndirectory tree under \\`services/\\` — one view per subsystem, a scoping aid, never\nhand-edited and never a second fleet map; its one styling opt-in is a\n\\`global { styleGroup subsystems { … } }\\` declared in any \\`.likec4\\` under\n\\`architecture/\\`, which \\`sync\\` then references. A diagram you author belongs in the\nlandscape or in a file of your own name beside it.\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.\n\\`features/<FEAT>/\\` holds a change in flight: \\`intent.md\\`, \\`delta.likec4\\`,\nper-service requirement and contract deltas, and \\`verification.yaml\\`.\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>\\`, then \\`loam doctor\\`.\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.\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; 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\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"]}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0LnB,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.\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\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/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

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

@@ -1 +1 @@
-{"version":3,"file":"agents-stamp.js","sourceRoot":"","sources":["../../../src/core/agent/agents-stamp.ts"],"names":[],"mappings":"AAgBA,4DAA4D;AAC5D,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,2BAA2B,OAAO,MAAM,CAAC;AAClD,CAAC;AAED,kFAAkF;AAClF,MAAM,QAAQ,GAAG,wCAAwC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,CAAC,KAAK,IAAI,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACnE,CAAC;AAaD,uFAAuF;AACvF,SAAS,YAAY,CAAC,CAAS;IAC7B,MAAM,CAAC,GAAG,kEAAkE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrF,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO;QACL,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnD,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,CAAW,EAAE,CAAW;IAC1C,+EAA+E;IAC/E,kFAAkF;IAClF,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjG,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzD,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,CAAC;YAAE,SAAS;QACtB,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,IAAI,EAAE,IAAI,EAAE;YAAE,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,MAAc;IACzD,MAAM,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAC/B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE;YAAE,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC;IAC5E,CAAC;IACD,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,MAAc;IACxD,OAAO,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAmB,EAAE,MAAc;IACrE,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAChE,OAAO;QACL,QAAQ,EAAE,MAAM;QAChB,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EACL,uCAAuC,KAAK,qBAAqB,MAAM,2BAA2B;YAClG,8FAA8F;YAC9F,2FAA2F;YAC3F,2DAA2D,KAAK,yCAAyC;YACzG,sEAAsE;KACzE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAmB,EAAE,MAAc;IACpE,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO;YACL,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,cAAc;YACpB,OAAO,EACL,6FAA6F;gBAC7F,6FAA6F;gBAC7F,cAAc,eAAe,CAAC,MAAM,CAAC,yDAAyD;gBAC9F,iDAAiD;SACpD,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,OAAO;QACL,QAAQ,EAAE,MAAM;QAChB,IAAI,EAAE,cAAc;QACpB,OAAO,EACL,kCAAkC,KAAK,qBAAqB,MAAM,8BAA8B;YAChG,2FAA2F;YAC3F,6BAA6B,MAAM,mEAAmE;KACzG,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The AGENTS.md version stamp: detection, never refresh.\n *\n * AGENTS.md is written once by `loam init` and never touched again — that is\n * the ownership contract (agent.ts): it is a starting point, and a team's edits\n * to it outrank ours. But the file tells agents to branch on flag and code\n * tables, and those tables describe the binary that wrote them. OpenSpec hit\n * the same wall and answered with auto-refresh, which teaches everyone the file\n * belongs to the tool after all; loam answers with the smallest honest thing —\n * a version stamp in the generated file, and one warning when the stamp is\n * missing or trails the running binary. Reviewing the file and bumping the\n * stamp is a human act, and a hand-curated file silences the warning the same\n * way: by saying, in the stamp, that someone has looked.\n */\nimport type { Finding } from \"../vocabulary/report.js\";\n\n/** The stamp `loam init` writes at the top of AGENTS.md. */\nexport function agentsStampLine(version: string): string {\n  return `<!-- generated by loam v${version} -->`;\n}\n\n/** Matches a stamp line anywhere in the file; the capture is the version text. */\nconst STAMP_RE = /<!--\\s*generated by loam v(\\S+?)\\s*-->/;\n\n/**\n * The version the stamp names, or null when there is no stamp (or one whose\n * version does not read as numbers — unparseable is indistinguishable from\n * absent, and both get the same advice).\n */\nexport function agentsStampVersion(text: string): string | null {\n  const m = STAMP_RE.exec(text);\n  return m !== null && parseVersion(m[1]!) !== null ? m[1]! : null;\n}\n\n/** A version split the way precedence is decided: the triple, then the prerelease identifiers. */\ninterface ParsedVersion {\n  release: [number, number, number];\n  /**\n   * The dot-separated identifiers of a `-beta.2` suffix, empty for a final\n   * release. Build metadata (`+sha`) is dropped — semver excludes it from\n   * precedence, and two builds of one version are the same instructions.\n   */\n  pre: string[];\n}\n\n/** `X.Y.Z[-pre][+build]`, or null when the leading triple does not read as numbers. */\nfunction parseVersion(v: string): ParsedVersion | null {\n  const m = /^(\\d+)\\.(\\d+)\\.(\\d+)(?:-([0-9A-Za-z.-]+))?(?:\\+[0-9A-Za-z.-]+)?$/.exec(v);\n  if (m === null) return null;\n  return {\n    release: [Number(m[1]), Number(m[2]), Number(m[3])],\n    pre: m[4] === undefined ? [] : m[4].split(\".\"),\n  };\n}\n\n/**\n * Semver identifier precedence: numeric identifiers compare numerically and\n * rank below alphanumeric ones, and a longer identifier list outranks a prefix\n * of itself. -1 / 0 / 1, so the caller reads like the triple comparison above.\n */\nfunction comparePre(a: string[], b: string[]): number {\n  // No prerelease outranks any prerelease — `1.2.0` is newer than `1.2.0-beta.9`\n  // — which is why this cannot be the plain lexicographic walk the identifiers get.\n  if (a.length === 0 || b.length === 0) return a.length === b.length ? 0 : a.length === 0 ? 1 : -1;\n  for (let i = 0; i < Math.min(a.length, b.length); i += 1) {\n    const [x, y] = [a[i]!, b[i]!];\n    if (x === y) continue;\n    const [nx, ny] = [/^\\d+$/.test(x), /^\\d+$/.test(y)];\n    if (nx && ny) return Number(x) < Number(y) ? -1 : 1;\n    if (nx !== ny) return nx ? -1 : 1;\n    return x < y ? -1 : 1;\n  }\n  return a.length === b.length ? 0 : a.length < b.length ? -1 : 1;\n}\n\n/**\n * Does `stamp` name an older version than `binary`? A stamp NEWER than the\n * binary does not trail: that is an old binary, not a stale file, and the fix\n * (upgrade loam) is not an AGENTS.md edit.\n *\n * Prerelease identifiers are compared, not ignored, and the difference is the\n * whole reason this check exists. Comparing the numeric triple alone made\n * `0.1.0-beta.1` and `0.1.0-beta.2` indistinguishable — and beta.2 is precisely\n * the release that changed the FORM of every generated file (embedded protocol\n * text became a pointer at `loam instructions`), with a CHANGELOG telling\n * readers to delete the files and re-run `loam init`. The one upgrade that most\n * needed the warning was the one bump shape that could not raise it. A\n * prerelease line is where a generated file's form actually moves, because that\n * is what a prerelease is for.\n */\nexport function versionTrails(stamp: string, binary: string): boolean {\n  const s = parseVersion(stamp);\n  const b = parseVersion(binary);\n  if (s === null || b === null) return false;\n  for (let i = 0; i < 3; i += 1) {\n    if (s.release[i]! !== b.release[i]!) return s.release[i]! < b.release[i]!;\n  }\n  return comparePre(s.pre, b.pre) < 0;\n}\n\n/**\n * Does `stamp` name a version NEWER than the binary reading it? The mirror of\n * {@link versionTrails}, and a different subject rather than its negation:\n * equal versions are neither.\n */\nexport function versionAhead(stamp: string, binary: string): boolean {\n  return versionTrails(binary, stamp);\n}\n\n/**\n * `docs.binary-behind` — this loam is OLDER than the loam that wrote the docs\n * repo it is reading.\n *\n * The false-green this closes is the sharpest one in the product, because it\n * inverts the meaning of a passing run rather than merely missing a defect.\n * loam's whole promise is that a token spelled here must be spelled there — so\n * every check is an existence constraint over a value the parser recognised.\n * A binary that predates a grammar addition does not FAIL on the newer\n * directive; it does not see it, produces no value, has nothing to join, and\n * reports green. The corpus is checked less than it looks, and nothing anywhere\n * says so. `agents.stale` is the opposite direction and explicitly declines\n * this case (\"that is an old binary, not a stale file\") — correctly, because\n * the fix is different: upgrade loam, do not edit the file.\n *\n * A WARNING, not an error, and the reasoning is the `sources.stale` doctrine.\n * A mixed-version fleet is ordinary — one engineer's global install trails a\n * release by a week — and failing every command in that repo would be a\n * refusal aimed at the wrong person on the wrong day. What the message must do\n * instead is say plainly that a green run from this binary is worth less than\n * it appears, which no other finding says. A fleet that wants it to gate has\n * `--strict`, which is exactly the lever that doctrine reserves for this.\n *\n * Silent when there is no file, no stamp, or the stamp is equal or older —\n * every one of those is somebody else's finding.\n */\nexport function binaryBehindFinding(text: string | null, binary: string): Finding | null {\n  if (text === null) return null;\n  const stamp = agentsStampVersion(text);\n  if (stamp === null || !versionAhead(stamp, binary)) return null;\n  return {\n    severity: \"warn\",\n    code: \"docs.binary-behind\",\n    message:\n      `This docs repo was written by loam v${stamp}; this binary is v${binary}. A newer loam may check ` +\n      \"joins this one cannot parse — an unrecognised directive is read as prose, so it produces no \" +\n      \"join to fail and this run reports green without having graded it. Treat a pass from this \" +\n      `binary as incomplete rather than clean, and upgrade to v${stamp} or later (\\`npm i -g @ybotok/loam\\`). ` +\n      \"Nothing here is wrong with the documents; the reader is behind them.\",\n  };\n}\n\n/**\n * The one finding `loam validate --all` owes the agent contract. `text` is the\n * docs repo's AGENTS.md, or null when there is none — no file means no contract\n * to have drifted, and this check stays silent rather than inventing a second\n * meaning for its code. Returns null when the stamp is current (or newer).\n */\nexport function agentsStaleFinding(text: string | null, binary: string): Finding | null {\n  if (text === null) return null;\n  const stamp = agentsStampVersion(text);\n  if (stamp === null) {\n    return {\n      severity: \"warn\",\n      code: \"agents.stale\",\n      message:\n        \"AGENTS.md has no version stamp — it predates stamping or was hand-created, so nothing says \" +\n        \"which loam its flag and code tables describe. Review it against the current `loam --help`, \" +\n        `then add \\`${agentsStampLine(binary)}\\` near the top; a hand-curated file keeps the warning ` +\n        \"off the same way, by keeping the stamp current.\",\n    };\n  }\n  if (!versionTrails(stamp, binary)) return null;\n  return {\n    severity: \"warn\",\n    code: \"agents.stale\",\n    message:\n      `AGENTS.md was written by loam v${stamp}; this binary is v${binary} — the flag and code tables ` +\n      \"agents branch on may have moved. Review the file against the current `loam --help`, then \" +\n      `update the stamp line to v${binary} (a hand-curated file silences this by bumping the stamp itself).`,\n  };\n}\n"]}
+{"version":3,"file":"agents-stamp.js","sourceRoot":"","sources":["../../../src/core/agent/agents-stamp.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The AGENTS.md version stamp: detection, never refresh.\n *\n * AGENTS.md is written once by `loam init` and never touched again — that is\n * the ownership contract (agent.ts): it is a starting point, and a team's edits\n * to it outrank ours. But the file tells agents to branch on flag and code\n * tables, and those tables describe the binary that wrote them. OpenSpec hit\n * the same wall and answered with auto-refresh, which teaches everyone the file\n * belongs to the tool after all; loam answers with the smallest honest thing —\n * a version stamp in the generated file, and one warning when the stamp is\n * missing or trails the running binary. Reviewing the file and bumping the\n * stamp is a human act, and a hand-curated file silences the warning the same\n * way: by saying, in the stamp, that someone has looked.\n */\nimport type { Finding } from \"../vocabulary/report.js\";\n\n/** The stamp `loam init` writes at the top of AGENTS.md. */\nexport function agentsStampLine(version: string): string {\n  return `<!-- generated by loam v${version} -->`;\n}\n\n/** Matches a stamp line anywhere in the file; the capture is the version text. */\nconst STAMP_RE = /<!--\\s*generated by loam v(\\S+?)\\s*-->/;\n\n/**\n * `text` with its stamp, when it has one, rewritten to name `version` — every\n * other byte untouched. What lets a caller ask whether a generated file differs\n * from what a binary would write in anything BUT the stamp: the pointer files\n * carry this same line, and a release that changes nothing in their body still\n * changes it.\n */\nexport function restamped(text: string, version: string): string {\n  return text.replace(STAMP_RE, agentsStampLine(version));\n}\n\n/**\n * The version the stamp names, or null when there is no stamp (or one whose\n * version does not read as numbers — unparseable is indistinguishable from\n * absent, and both get the same advice).\n */\nexport function agentsStampVersion(text: string): string | null {\n  const m = STAMP_RE.exec(text);\n  return m !== null && parseVersion(m[1]!) !== null ? m[1]! : null;\n}\n\n/** A version split the way precedence is decided: the triple, then the prerelease identifiers. */\ninterface ParsedVersion {\n  release: [number, number, number];\n  /**\n   * The dot-separated identifiers of a `-beta.2` suffix, empty for a final\n   * release. Build metadata (`+sha`) is dropped — semver excludes it from\n   * precedence, and two builds of one version are the same instructions.\n   */\n  pre: string[];\n}\n\n/** `X.Y.Z[-pre][+build]`, or null when the leading triple does not read as numbers. */\nfunction parseVersion(v: string): ParsedVersion | null {\n  const m = /^(\\d+)\\.(\\d+)\\.(\\d+)(?:-([0-9A-Za-z.-]+))?(?:\\+[0-9A-Za-z.-]+)?$/.exec(v);\n  if (m === null) return null;\n  return {\n    release: [Number(m[1]), Number(m[2]), Number(m[3])],\n    pre: m[4] === undefined ? [] : m[4].split(\".\"),\n  };\n}\n\n/**\n * Semver identifier precedence: numeric identifiers compare numerically and\n * rank below alphanumeric ones, and a longer identifier list outranks a prefix\n * of itself. -1 / 0 / 1, so the caller reads like the triple comparison above.\n */\nfunction comparePre(a: string[], b: string[]): number {\n  // No prerelease outranks any prerelease — `1.2.0` is newer than `1.2.0-beta.9`\n  // — which is why this cannot be the plain lexicographic walk the identifiers get.\n  if (a.length === 0 || b.length === 0) return a.length === b.length ? 0 : a.length === 0 ? 1 : -1;\n  for (let i = 0; i < Math.min(a.length, b.length); i += 1) {\n    const [x, y] = [a[i]!, b[i]!];\n    if (x === y) continue;\n    const [nx, ny] = [/^\\d+$/.test(x), /^\\d+$/.test(y)];\n    if (nx && ny) return Number(x) < Number(y) ? -1 : 1;\n    if (nx !== ny) return nx ? -1 : 1;\n    return x < y ? -1 : 1;\n  }\n  return a.length === b.length ? 0 : a.length < b.length ? -1 : 1;\n}\n\n/**\n * Does `stamp` name an older version than `binary`? A stamp NEWER than the\n * binary does not trail: that is an old binary, not a stale file, and the fix\n * (upgrade loam) is not an AGENTS.md edit.\n *\n * Prerelease identifiers are compared, not ignored, and the difference is the\n * whole reason this check exists. Comparing the numeric triple alone made\n * `0.1.0-beta.1` and `0.1.0-beta.2` indistinguishable — and beta.2 is precisely\n * the release that changed the FORM of every generated file (embedded protocol\n * text became a pointer at `loam instructions`), with a CHANGELOG telling\n * readers to delete the files and re-run `loam init`. The one upgrade that most\n * needed the warning was the one bump shape that could not raise it. A\n * prerelease line is where a generated file's form actually moves, because that\n * is what a prerelease is for.\n */\nexport function versionTrails(stamp: string, binary: string): boolean {\n  const s = parseVersion(stamp);\n  const b = parseVersion(binary);\n  if (s === null || b === null) return false;\n  for (let i = 0; i < 3; i += 1) {\n    if (s.release[i]! !== b.release[i]!) return s.release[i]! < b.release[i]!;\n  }\n  return comparePre(s.pre, b.pre) < 0;\n}\n\n/**\n * Does `stamp` name a version NEWER than the binary reading it? The mirror of\n * {@link versionTrails}, and a different subject rather than its negation:\n * equal versions are neither.\n */\nexport function versionAhead(stamp: string, binary: string): boolean {\n  return versionTrails(binary, stamp);\n}\n\n/**\n * `docs.binary-behind` — this loam is OLDER than the loam that wrote the docs\n * repo it is reading.\n *\n * The false-green this closes is the sharpest one in the product, because it\n * inverts the meaning of a passing run rather than merely missing a defect.\n * loam's whole promise is that a token spelled here must be spelled there — so\n * every check is an existence constraint over a value the parser recognised.\n * A binary that predates a grammar addition does not FAIL on the newer\n * directive; it does not see it, produces no value, has nothing to join, and\n * reports green. The corpus is checked less than it looks, and nothing anywhere\n * says so. `agents.stale` is the opposite direction and explicitly declines\n * this case (\"that is an old binary, not a stale file\") — correctly, because\n * the fix is different: upgrade loam, do not edit the file.\n *\n * A WARNING, not an error, and the reasoning is the `sources.stale` doctrine.\n * A mixed-version fleet is ordinary — one engineer's global install trails a\n * release by a week — and failing every command in that repo would be a\n * refusal aimed at the wrong person on the wrong day. What the message must do\n * instead is say plainly that a green run from this binary is worth less than\n * it appears, which no other finding says. A fleet that wants it to gate has\n * `--strict`, which is exactly the lever that doctrine reserves for this.\n *\n * Silent when there is no file, no stamp, or the stamp is equal or older —\n * every one of those is somebody else's finding.\n */\nexport function binaryBehindFinding(text: string | null, binary: string): Finding | null {\n  if (text === null) return null;\n  const stamp = agentsStampVersion(text);\n  if (stamp === null || !versionAhead(stamp, binary)) return null;\n  return {\n    severity: \"warn\",\n    code: \"docs.binary-behind\",\n    message:\n      `This docs repo was written by loam v${stamp}; this binary is v${binary}. A newer loam may check ` +\n      \"joins this one cannot parse — an unrecognised directive is read as prose, so it produces no \" +\n      \"join to fail and this run reports green without having graded it. Treat a pass from this \" +\n      `binary as incomplete rather than clean, and upgrade to v${stamp} or later (\\`npm i -g @ybotok/loam\\`). ` +\n      \"Nothing here is wrong with the documents; the reader is behind them.\",\n  };\n}\n\n/**\n * The one finding `loam validate --all` owes the agent contract. `text` is the\n * docs repo's AGENTS.md, or null when there is none — no file means no contract\n * to have drifted, and this check stays silent rather than inventing a second\n * meaning for its code. Returns null when the stamp is current (or newer).\n */\nexport function agentsStaleFinding(text: string | null, binary: string): Finding | null {\n  if (text === null) return null;\n  const stamp = agentsStampVersion(text);\n  if (stamp === null) {\n    return {\n      severity: \"warn\",\n      code: \"agents.stale\",\n      message:\n        \"AGENTS.md has no version stamp — it predates stamping or was hand-created, so nothing says \" +\n        \"which loam its flag and code tables describe. Review it against the current `loam --help`, \" +\n        `then add \\`${agentsStampLine(binary)}\\` near the top; a hand-curated file keeps the warning ` +\n        \"off the same way, by keeping the stamp current.\",\n    };\n  }\n  if (!versionTrails(stamp, binary)) return null;\n  return {\n    severity: \"warn\",\n    code: \"agents.stale\",\n    message:\n      `AGENTS.md was written by loam v${stamp}; this binary is v${binary} — the flag and code tables ` +\n      \"agents branch on may have moved. Review the file against the current `loam --help`, then \" +\n      `update the stamp line to v${binary} (a hand-curated file silences this by bumping the stamp itself).`,\n  };\n}\n"]}

package/dist/core/agent/scaffold.js

@@ -53,8 +53,9 @@ import { AGENT_TOOLS, CLAUDE } from "./tools/registry.js";
  * Thinning the file is the third option. What remains is what does not move
  * between releases: what this workflow is for, and the verbs in order. What
  * leaves is everything version-shaped. `doctor.agent-files-stale` still reports
- * a file whose stamp has fallen behind, and now has almost nothing to be right
- * about — which is the point.
+ * a file whose stamp has fallen behind — once its body, stamp aside, is no
+ * longer the one this binary writes — and now has almost nothing to be right
+ * about, which is the point.
  *
  * The trade is real and worth stating: an agent that cannot execute `loam` now
  * has a spine instead of a protocol. That is the correct failure. The exact
@@ -64,12 +65,13 @@ import { AGENT_TOOLS, CLAUDE } from "./tools/registry.js";
  *
  * The last clause of the pointer is the one sentence here that changes what an
  * agent DOES rather than what it knows. `loam instructions loam-check` prints
- * 84 KB — about a fifth of a 100k-token window, 223 fix-table rows of which a
- * run needs two or three — and every file written from this stub opens by
- * telling the agent to run it. `--no-fix-tables` (commands/instructions.ts)
- * drops the rows, and `loam explain <code>` answers the one row the run turned
- * out to need in under 500 bytes. The flag is what makes the lazy path payable;
- * this sentence is what makes an agent take it.
+ * the largest page loam has — 109 KB measured 2026-10-10 (84 KB when this was
+ * first written), about a quarter of a 100k-token window, and hundreds of
+ * fix-table rows of which a run needs two or three — and every file written
+ * from this stub opens by telling the agent to run it. `--no-fix-tables`
+ * (commands/instructions.ts) drops the rows, and `loam explain <code>` answers
+ * the one row the run turned out to need on its own. The flag is what makes
+ * the lazy path payable; this sentence is what makes an agent take it.
  */
 function stubBody(c) {
     const steps = c.spine.map((s, i) => `  ${i + 1}. ${s}`).join("\n");
@@ -234,13 +236,6 @@ export async function syncAgentCommands(req) {
     }
     return out;
 }
-/**
- * Backward-compatible create-only wrapper. Callers that own no digest manifest
- * leave every existing file alone and receive only the paths created.
- */
-export async function scaffoldAgentCommands(cwd, toolIds = ["claude"], delivery = DELIVERIES) {
-    return (await syncAgentCommands({ cwd, toolIds, delivery })).created;
-}
 /**
  * The registry ids whose marker paths are present in `cwd` — what `loam init`
  * writes for when nobody passed `--tools`.

package/dist/core/agent/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/core/agent/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAS,QAAQ,CAAC,CAAiB;IACjC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,KAAK,aAAa;QACpC,CAAC,CAAC;;uEAEiE;QACnE,CAAC,CAAC;;;iDAG2C,CAAC;IAChD,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK,aAAa;QACrC,CAAC,CAAC;;uEAEiE;QACnE,CAAC,CAAC;;;;;kFAK4E,CAAC;IACjF,OAAO,GAAG,CAAC,CAAC,OAAO;;EAEnB,KAAK;;;;;;MAMD,CAAC,CAAC,UAAU;;;;EAIhB,KAAK;;EAEL,MAAM;;;;;;CAMP,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,GAAG,CAAC,CAAiB,EAAkB,EAAE,CAAC,CAAC;IACtD,GAAG,CAAC;IACJ,IAAI,EAAE,GAAG,eAAe,CAAC,YAAY,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE;CAC3D,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,cAAc,GAA2B,MAAM,CAAC,WAAW,CACtE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAC/D,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAU,CAAC;AAG1D,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;AAGnE,MAAM,gBAAgB,GAA8C;IAClE,IAAI,EAAE,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;IAC9F,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;CAC1E,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAW,EACX,OAAiB,EACjB,QAAQ,GAAwB,UAAU,EAC1C,OAAO,GAAiB,MAAM;IAE9B,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;QAC5B,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC7B,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;QACrE,MAAM,QAAQ,GAAuB,EAAE,CAAC;QACxC,sEAAsE;QACtE,wEAAwE;QACxE,2BAA2B;QAC3B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QACrC,IAAI,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,KAAK,KAAK,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7E,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAC5B,cAAc,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC1F,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAClC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;SAC9B,CAAC,CAAC,CACJ,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,OAAwB;IAC7C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,YAAY,CAAC,GAAW,EAAE,IAAY;IAC7C,OAAO,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,GAAW,EACX,OAAgC,EAChC,QAAsD,EACtD,OAAyC;IAEzC,MAAM,GAAG,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,OAAO;QAAE,OAAO,GAAG,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC;AASD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,GAMvC;IACC,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,EAAE,OAAO,GAAG,MAAM,EAAE,KAAK,GAAG,EAAE,EAAE,GAAG,GAAG,CAAC;IAC/F,MAAM,GAAG,GAAkB,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACvE,KAAK,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;QACrF,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAChD,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YACvC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACpD,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;YACxB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,OAAO;YAAE,SAAS;QACrC,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACvC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,GAAW,EACX,OAAO,GAAa,CAAC,QAAQ,CAAC,EAC9B,QAAQ,GAAwB,UAAU;IAE1C,OAAO,CAAC,MAAM,iBAAiB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;AACvE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC;SAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;SACjF,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;AACvB,CAAC","sourcesContent":["/**\n * The generated FILES: what a pointer file contains (the stub), what this\n * binary would write (SLASH_COMMANDS, plannedCommandFiles), and how the files\n * land and are detected on disk.\n *\n * The command and skill files go into the repo `init` runs in, because that is\n * where the agent is invoked — for whichever tools the repo shows signs of, via\n * the AGENT_TOOLS registry (tools/registry.ts): one shared body, a per-tool\n * path and wrapper. A delivery is refreshed only while its bytes still match\n * the digest loam recorded when it wrote them; a team's edits revoke that\n * authority and outrank ours.\n *\n * Two deliveries, one body. A slash command has to be TYPED, so it only ever\n * reaches an agent whose operator already knows loam exists. A skill is loaded\n * by the model itself when the task matches its `description`, which is how the\n * protocol reaches an agent that was never told about it. That difference is\n * the whole reason both are written by default.\n *\n * The per-tool command and skill files carry the same version stamp AGENTS.md\n * does (agents-md.ts), for the same reason and with the same answer:\n * `loam doctor` reports `doctor.agent-files-stale` without writing. A later\n * `loam init` can refresh only a digest-matched pointer. Without the stamp,\n * absence was the only drift doctor could see — a command file mangled to one\n * line left it saying `healthy: true`, which across a hundred repositories is\n * invisible rot with no repair path.\n */\nimport { createHash } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, join, relative } from \"node:path\";\nimport { agentsStampLine } from \"./agents-stamp.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\nimport type { AgentFileEmitter, CommandContent } from \"./contract.js\";\nimport { AGENT_COMMANDS } from \"./protocol.js\";\nimport { AGENT_TOOLS, CLAUDE } from \"./tools/registry.js\";\n\n/**\n * What a generated file actually contains: the purpose, the spine, and the\n * command that prints the rest.\n *\n * The protocol itself stays in `body` and ships inside the binary, reachable as\n * `loam instructions <name>`. The file on disk gets a pointer to it, because\n * these two things go stale in opposite directions and only one of them can be\n * fixed. A generated file is refreshed only while its bytes still match the\n * digest loam recorded; any edit revokes that authority because your edits\n * outrank the template. Without that distinction a repo scaffolded a year ago\n * holds a year-old protocol: exact\n * flags, exact finding codes, exact step order, all of it asserted with total\n * confidence by a file whose reader has no way to know it is describing a\n * different release. That is not a hypothetical failure mode. It is the one\n * every project shipping generated agent instructions has had, and the fix\n * everybody reaches for — regenerate on upgrade — trades it for silently\n * overwriting what a human wrote.\n *\n * Thinning the file is the third option. What remains is what does not move\n * between releases: what this workflow is for, and the verbs in order. What\n * leaves is everything version-shaped. `doctor.agent-files-stale` still reports\n * a file whose stamp has fallen behind, and now has almost nothing to be right\n * about — which is the point.\n *\n * The trade is real and worth stating: an agent that cannot execute `loam` now\n * has a spine instead of a protocol. That is the correct failure. The exact\n * diagnostic and lifecycle invocations belong to the binary-owned page; an\n * agent that cannot run loam cannot finish either kind from an embedded copy —\n * it can only try using a year-old flag.\n *\n * The last clause of the pointer is the one sentence here that changes what an\n * agent DOES rather than what it knows. `loam instructions loam-check` prints\n * 84 KB — about a fifth of a 100k-token window, 223 fix-table rows of which a\n * run needs two or three — and every file written from this stub opens by\n * telling the agent to run it. `--no-fix-tables` (commands/instructions.ts)\n * drops the rows, and `loam explain <code>` answers the one row the run turned\n * out to need in under 500 bytes. The flag is what makes the lazy path payable;\n * this sentence is what makes an agent take it.\n */\nfunction stubBody(c: CommandContent): string {\n  const steps = c.spine.map((s, i) => `  ${i + 1}. ${s}`).join(\"\\n\");\n  const entry = c.name === \"loam-report\"\n    ? `This support protocol has two equivalent chat entry points: the explicit command a\nuser chooses, and the Agent Skill an unexpected-run request may load. Both reach\nthe same local, sanitized report; the agent owns the diagnostic steps.`\n    : `This workflow has two equivalent chat entry points: the explicit command a user\nchooses, and the Agent Skill a natural-language request may load. Both reach this\nsame body and must produce the same status/edit/validate loop; do not make the\nuser type the internal loam commands one by one.`;\n  const output = c.name === \"loam-report\"\n    ? `The runtime protocol decides which diagnostics are safe to run and what may enter the\nreport. Do not infer permission to retry a writer, repair files or send the result\nfrom the broader lifecycle commands another generated skill may allow.`\n    : `Every step above is a \\`loam\\` invocation, and each command's own \\`--json\\` output\ncarries what to do next: findings have stable codes, and \\`loam status --json\\` puts\nthe ordered \\`next[]\\` — each entry a code and the literal command — in one place.\nBranch on the codes, never on the prose. The check workflow starts with\n\\`--no-fix-tables\\`; use \\`loam explain <code>\\` for each code the run actually\nreports, and remove that flag only when you deliberately need the complete table.`;\n  return `${c.purpose}\n\n${entry}\n\n**Run this first.** It is the protocol, and it ships with the binary you are about\nto call — so it names this loam's flags, its finding codes and its fix tables,\nnot the ones that were current when this repository was scaffolded:\n\n    ${c.invocation}\n\nThe spine it fills in, so you can tell a run that went sideways from one that did not:\n\n${steps}\n\n${output}\n\nThis file is a pointer, not the protocol. loam may refresh it while its bytes still\nmatch the digest recorded in loam.json. Editing it revokes that authority: your\nchanges outrank the template and stay untouched. Where this file and\n\\`loam instructions\\` disagree, the command is right.\n`;\n}\n\n/**\n * The command body a file actually gets: the pointer, under the same version\n * stamp AGENTS.md carries.\n *\n * The stamp is applied once, here, rather than in twenty wrappers — it is a\n * fact about loam, not about a tool's dialect, and a per-wrapper copy is twenty\n * chances to forget it. It rides at the top of the BODY (not the file) because\n * every dialect puts something of its own first: YAML frontmatter, a TOML key,\n * a title line. An HTML comment is invisible in all of them, and\n * `agentsStampVersion` matches it wherever in the file it lands.\n *\n * A repo initialized before stamping existed has unstamped files, which is\n * exactly what `doctor.agent-files-stale` is for: nobody has confirmed that\n * those instructions still describe this binary.\n */\nconst stubbed = (c: CommandContent): CommandContent => ({\n  ...c,\n  body: `${agentsStampLine(LOAM_VERSION)}\\n\\n${stubBody(c)}`,\n});\n\n/**\n * The Claude-format files, keyed by command name: exactly what **this** binary\n * would write, derived through the same adapter that writes them, so the export\n * and a freshly scaffolded repo can never disagree.\n *\n * Read that scope literally. It used to be described as the on-disk contract of\n * every repo initialized before `--tools` existed, and that is no longer true\n * of anything but a fresh scaffold: a file holds the STUB now, every repo\n * scaffolded before that holds the full protocol. A recorded, byte-identical\n * pointer can refresh; an older unrecorded file or any customized file cannot,\n * so an export cannot describe files this binary did not write.\n *\n * The protocol those older files carry is `PROTOCOLS`. Anything asserting on\n * protocol content wants that one — this answers \"what would loam write here\",\n * not \"what does loam instruct\".\n */\nexport const SLASH_COMMANDS: Record<string, string> = Object.fromEntries(\n  AGENT_COMMANDS.map((c) => [c.name, CLAUDE.format(stubbed(c))]),\n);\n\n/** The two ways a command body reaches an agent. Both are on by default. */\nexport const DELIVERIES = [\"commands\", \"skills\"] as const;\nexport type Delivery = (typeof DELIVERIES)[number];\n\nexport const AGENT_PROFILES = [\"full\", \"service\", \"docs\"] as const;\nexport type AgentProfile = (typeof AGENT_PROFILES)[number];\n\nconst PROFILE_COMMANDS: Record<AgentProfile, ReadonlySet<string>> = {\n  full: new Set(AGENT_COMMANDS.map((command) => command.name)),\n  service: new Set([\"loam-adopt\", \"loam-implement\", \"loam-check\", \"loam-verify\", \"loam-report\"]),\n  docs: new Set([\"loam-feature\", \"loam-check\", \"loam-ship\", \"loam-report\"]),\n};\n\n/**\n * Every file the selected tools would lay down, in creation order — the same\n * list `init` probes for `skipped` BEFORE the scaffold runs, so created +\n * skipped is the same list on every repo.\n *\n * Called with two arguments it returns EVERYTHING the binary would write under\n * default delivery: commands and skills both. That is the contract callers\n * outside this module depend on — `loam doctor` asks \"what should be here?\"\n * and a half-answer would report a fully-scaffolded repo as fully scaffolded\n * while ignoring every skill file. The name predates the second delivery and is\n * kept because it is imported elsewhere; `delivery` narrows it.\n */\nexport function plannedCommandFiles(\n  cwd: string,\n  toolIds: string[],\n  delivery: readonly Delivery[] = DELIVERIES,\n  profile: AgentProfile = \"full\",\n): Array<{ path: string; content: string }> {\n  return toolIds.flatMap((id) => {\n    const tool = AGENT_TOOLS[id];\n    if (tool === undefined) throw new Error(`unknown agent tool: ${id}`);\n    const emitters: AgentFileEmitter[] = [];\n    // A tool declares only the deliveries it actually reads, so an absent\n    // emitter is a fact about the tool, never a reason to fall back to some\n    // other tool's convention.\n    const { path, format, skill } = tool;\n    if (delivery.includes(\"commands\") && path !== undefined && format !== undefined) {\n      emitters.push({ path, format });\n    }\n    if (delivery.includes(\"skills\") && skill !== undefined) emitters.push(skill);\n    return emitters.flatMap((e) =>\n      AGENT_COMMANDS.filter((command) => PROFILE_COMMANDS[profile].has(command.name)).map((c) => ({\n        path: join(cwd, ...e.path(c.name)),\n        content: e.format(stubbed(c)),\n      })),\n    );\n  });\n}\n\nfunction contentDigest(content: string | Buffer): string {\n  return createHash(\"sha256\").update(content).digest(\"hex\");\n}\n\nfunction manifestPath(cwd: string, path: string): string {\n  return relative(cwd, path).replaceAll(\"\\\\\", \"/\");\n}\n\nexport function updatedAgentFileManifest(\n  cwd: string,\n  planned: Array<{ path: string }>,\n  existing: Readonly<Record<string, string>> | undefined,\n  managed: Readonly<Record<string, string>>,\n): Record<string, string> {\n  const out = { ...existing };\n  for (const file of planned) delete out[manifestPath(cwd, file.path)];\n  return Object.assign(out, managed);\n}\n\nexport interface AgentFileSync {\n  created: string[];\n  refreshed: string[];\n  /** Repo-relative path -> digest of the bytes loam is allowed to refresh. */\n  managed: Record<string, string>;\n}\n\n/**\n * Create missing files and refresh only files still byte-identical to the\n * digest recorded when loam last wrote them. A human edit breaks that equality\n * and therefore revokes loam's authority over the file without a marker block\n * or a prompt.\n */\nexport async function syncAgentCommands(req: {\n  cwd: string;\n  toolIds?: string[];\n  delivery?: readonly Delivery[];\n  profile?: AgentProfile;\n  known?: Readonly<Record<string, string>>;\n}): Promise<AgentFileSync> {\n  const { cwd, toolIds = [\"claude\"], delivery = DELIVERIES, profile = \"full\", known = {} } = req;\n  const out: AgentFileSync = { created: [], refreshed: [], managed: {} };\n  for (const { path, content } of plannedCommandFiles(cwd, toolIds, delivery, profile)) {\n    const key = manifestPath(cwd, path);\n    const desired = contentDigest(content);\n    if (!existsSync(path)) {\n      await mkdir(dirname(path), { recursive: true });\n      await writeFile(path, content, \"utf8\");\n      out.created.push(path);\n      out.managed[key] = desired;\n      continue;\n    }\n    const current = contentDigest(await readFile(path));\n    if (current === desired) {\n      out.managed[key] = desired;\n      continue;\n    }\n    if (known[key] !== current) continue;\n    await writeFile(path, content, \"utf8\");\n    out.refreshed.push(path);\n    out.managed[key] = desired;\n  }\n  return out;\n}\n\n/**\n * Backward-compatible create-only wrapper. Callers that own no digest manifest\n * leave every existing file alone and receive only the paths created.\n */\nexport async function scaffoldAgentCommands(\n  cwd: string,\n  toolIds: string[] = [\"claude\"],\n  delivery: readonly Delivery[] = DELIVERIES,\n): Promise<string[]> {\n  return (await syncAgentCommands({ cwd, toolIds, delivery })).created;\n}\n\n/**\n * The registry ids whose marker paths are present in `cwd` — what `loam init`\n * writes for when nobody passed `--tools`.\n *\n * A repo with `.cursor/` and no Claude Code used to get `.claude/commands/`\n * and nothing it could actually run. Presence is the whole test, and existence\n * (not directory-ness) is what is asked, because a marker is as often a file as\n * a directory — `.github/copilot-instructions.md` is the honest signal for\n * Copilot where `.github/` itself is noise.\n */\nexport function detectAgentTools(cwd: string): string[] {\n  return Object.entries(AGENT_TOOLS)\n    .filter(([, tool]) => tool.detect.some((marker) => existsSync(join(cwd, marker))))\n    .map(([id]) => id);\n}\n"]}
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/core/agent/scaffold.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The generated FILES: what a pointer file contains (the stub), what this\n * binary would write (SLASH_COMMANDS, plannedCommandFiles), and how the files\n * land and are detected on disk.\n *\n * The command and skill files go into the repo `init` runs in, because that is\n * where the agent is invoked — for whichever tools the repo shows signs of, via\n * the AGENT_TOOLS registry (tools/registry.ts): one shared body, a per-tool\n * path and wrapper. A delivery is refreshed only while its bytes still match\n * the digest loam recorded when it wrote them; a team's edits revoke that\n * authority and outrank ours.\n *\n * Two deliveries, one body. A slash command has to be TYPED, so it only ever\n * reaches an agent whose operator already knows loam exists. A skill is loaded\n * by the model itself when the task matches its `description`, which is how the\n * protocol reaches an agent that was never told about it. That difference is\n * the whole reason both are written by default.\n *\n * The per-tool command and skill files carry the same version stamp AGENTS.md\n * does (agents-md.ts), for the same reason and with the same answer:\n * `loam doctor` reports `doctor.agent-files-stale` without writing. A later\n * `loam init` can refresh only a digest-matched pointer. Without the stamp,\n * absence was the only drift doctor could see — a command file mangled to one\n * line left it saying `healthy: true`, which across a hundred repositories is\n * invisible rot with no repair path.\n */\nimport { createHash } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, join, relative } from \"node:path\";\nimport { agentsStampLine } from \"./agents-stamp.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\nimport type { AgentFileEmitter, CommandContent } from \"./contract.js\";\nimport { AGENT_COMMANDS } from \"./protocol.js\";\nimport { AGENT_TOOLS, CLAUDE } from \"./tools/registry.js\";\n\n/**\n * What a generated file actually contains: the purpose, the spine, and the\n * command that prints the rest.\n *\n * The protocol itself stays in `body` and ships inside the binary, reachable as\n * `loam instructions <name>`. The file on disk gets a pointer to it, because\n * these two things go stale in opposite directions and only one of them can be\n * fixed. A generated file is refreshed only while its bytes still match the\n * digest loam recorded; any edit revokes that authority because your edits\n * outrank the template. Without that distinction a repo scaffolded a year ago\n * holds a year-old protocol: exact\n * flags, exact finding codes, exact step order, all of it asserted with total\n * confidence by a file whose reader has no way to know it is describing a\n * different release. That is not a hypothetical failure mode. It is the one\n * every project shipping generated agent instructions has had, and the fix\n * everybody reaches for — regenerate on upgrade — trades it for silently\n * overwriting what a human wrote.\n *\n * Thinning the file is the third option. What remains is what does not move\n * between releases: what this workflow is for, and the verbs in order. What\n * leaves is everything version-shaped. `doctor.agent-files-stale` still reports\n * a file whose stamp has fallen behind — once its body, stamp aside, is no\n * longer the one this binary writes — and now has almost nothing to be right\n * about, which is the point.\n *\n * The trade is real and worth stating: an agent that cannot execute `loam` now\n * has a spine instead of a protocol. That is the correct failure. The exact\n * diagnostic and lifecycle invocations belong to the binary-owned page; an\n * agent that cannot run loam cannot finish either kind from an embedded copy —\n * it can only try using a year-old flag.\n *\n * The last clause of the pointer is the one sentence here that changes what an\n * agent DOES rather than what it knows. `loam instructions loam-check` prints\n * the largest page loam has — 109 KB measured 2026-10-10 (84 KB when this was\n * first written), about a quarter of a 100k-token window, and hundreds of\n * fix-table rows of which a run needs two or three — and every file written\n * from this stub opens by telling the agent to run it. `--no-fix-tables`\n * (commands/instructions.ts) drops the rows, and `loam explain <code>` answers\n * the one row the run turned out to need on its own. The flag is what makes\n * the lazy path payable; this sentence is what makes an agent take it.\n */\nfunction stubBody(c: CommandContent): string {\n  const steps = c.spine.map((s, i) => `  ${i + 1}. ${s}`).join(\"\\n\");\n  const entry = c.name === \"loam-report\"\n    ? `This support protocol has two equivalent chat entry points: the explicit command a\nuser chooses, and the Agent Skill an unexpected-run request may load. Both reach\nthe same local, sanitized report; the agent owns the diagnostic steps.`\n    : `This workflow has two equivalent chat entry points: the explicit command a user\nchooses, and the Agent Skill a natural-language request may load. Both reach this\nsame body and must produce the same status/edit/validate loop; do not make the\nuser type the internal loam commands one by one.`;\n  const output = c.name === \"loam-report\"\n    ? `The runtime protocol decides which diagnostics are safe to run and what may enter the\nreport. Do not infer permission to retry a writer, repair files or send the result\nfrom the broader lifecycle commands another generated skill may allow.`\n    : `Every step above is a \\`loam\\` invocation, and each command's own \\`--json\\` output\ncarries what to do next: findings have stable codes, and \\`loam status --json\\` puts\nthe ordered \\`next[]\\` — each entry a code and the literal command — in one place.\nBranch on the codes, never on the prose. The check workflow starts with\n\\`--no-fix-tables\\`; use \\`loam explain <code>\\` for each code the run actually\nreports, and remove that flag only when you deliberately need the complete table.`;\n  return `${c.purpose}\n\n${entry}\n\n**Run this first.** It is the protocol, and it ships with the binary you are about\nto call — so it names this loam's flags, its finding codes and its fix tables,\nnot the ones that were current when this repository was scaffolded:\n\n    ${c.invocation}\n\nThe spine it fills in, so you can tell a run that went sideways from one that did not:\n\n${steps}\n\n${output}\n\nThis file is a pointer, not the protocol. loam may refresh it while its bytes still\nmatch the digest recorded in loam.json. Editing it revokes that authority: your\nchanges outrank the template and stay untouched. Where this file and\n\\`loam instructions\\` disagree, the command is right.\n`;\n}\n\n/**\n * The command body a file actually gets: the pointer, under the same version\n * stamp AGENTS.md carries.\n *\n * The stamp is applied once, here, rather than in twenty wrappers — it is a\n * fact about loam, not about a tool's dialect, and a per-wrapper copy is twenty\n * chances to forget it. It rides at the top of the BODY (not the file) because\n * every dialect puts something of its own first: YAML frontmatter, a TOML key,\n * a title line. An HTML comment is invisible in all of them, and\n * `agentsStampVersion` matches it wherever in the file it lands.\n *\n * A repo initialized before stamping existed has unstamped files, which is\n * exactly what `doctor.agent-files-stale` is for: nobody has confirmed that\n * those instructions still describe this binary.\n */\nconst stubbed = (c: CommandContent): CommandContent => ({\n  ...c,\n  body: `${agentsStampLine(LOAM_VERSION)}\\n\\n${stubBody(c)}`,\n});\n\n/**\n * The Claude-format files, keyed by command name: exactly what **this** binary\n * would write, derived through the same adapter that writes them, so the export\n * and a freshly scaffolded repo can never disagree.\n *\n * Read that scope literally. It used to be described as the on-disk contract of\n * every repo initialized before `--tools` existed, and that is no longer true\n * of anything but a fresh scaffold: a file holds the STUB now, every repo\n * scaffolded before that holds the full protocol. A recorded, byte-identical\n * pointer can refresh; an older unrecorded file or any customized file cannot,\n * so an export cannot describe files this binary did not write.\n *\n * The protocol those older files carry is `PROTOCOLS`. Anything asserting on\n * protocol content wants that one — this answers \"what would loam write here\",\n * not \"what does loam instruct\".\n */\nexport const SLASH_COMMANDS: Record<string, string> = Object.fromEntries(\n  AGENT_COMMANDS.map((c) => [c.name, CLAUDE.format(stubbed(c))]),\n);\n\n/** The two ways a command body reaches an agent. Both are on by default. */\nexport const DELIVERIES = [\"commands\", \"skills\"] as const;\nexport type Delivery = (typeof DELIVERIES)[number];\n\nexport const AGENT_PROFILES = [\"full\", \"service\", \"docs\"] as const;\nexport type AgentProfile = (typeof AGENT_PROFILES)[number];\n\nconst PROFILE_COMMANDS: Record<AgentProfile, ReadonlySet<string>> = {\n  full: new Set(AGENT_COMMANDS.map((command) => command.name)),\n  service: new Set([\"loam-adopt\", \"loam-implement\", \"loam-check\", \"loam-verify\", \"loam-report\"]),\n  docs: new Set([\"loam-feature\", \"loam-check\", \"loam-ship\", \"loam-report\"]),\n};\n\n/**\n * Every file the selected tools would lay down, in creation order — the same\n * list `init` probes for `skipped` BEFORE the scaffold runs, so created +\n * skipped is the same list on every repo.\n *\n * Called with two arguments it returns EVERYTHING the binary would write under\n * default delivery: commands and skills both. That is the contract callers\n * outside this module depend on — `loam doctor` asks \"what should be here?\"\n * and a half-answer would report a fully-scaffolded repo as fully scaffolded\n * while ignoring every skill file. The name predates the second delivery and is\n * kept because it is imported elsewhere; `delivery` narrows it.\n */\nexport function plannedCommandFiles(\n  cwd: string,\n  toolIds: string[],\n  delivery: readonly Delivery[] = DELIVERIES,\n  profile: AgentProfile = \"full\",\n): Array<{ path: string; content: string }> {\n  return toolIds.flatMap((id) => {\n    const tool = AGENT_TOOLS[id];\n    if (tool === undefined) throw new Error(`unknown agent tool: ${id}`);\n    const emitters: AgentFileEmitter[] = [];\n    // A tool declares only the deliveries it actually reads, so an absent\n    // emitter is a fact about the tool, never a reason to fall back to some\n    // other tool's convention.\n    const { path, format, skill } = tool;\n    if (delivery.includes(\"commands\") && path !== undefined && format !== undefined) {\n      emitters.push({ path, format });\n    }\n    if (delivery.includes(\"skills\") && skill !== undefined) emitters.push(skill);\n    return emitters.flatMap((e) =>\n      AGENT_COMMANDS.filter((command) => PROFILE_COMMANDS[profile].has(command.name)).map((c) => ({\n        path: join(cwd, ...e.path(c.name)),\n        content: e.format(stubbed(c)),\n      })),\n    );\n  });\n}\n\nfunction contentDigest(content: string | Buffer): string {\n  return createHash(\"sha256\").update(content).digest(\"hex\");\n}\n\nfunction manifestPath(cwd: string, path: string): string {\n  return relative(cwd, path).replaceAll(\"\\\\\", \"/\");\n}\n\nexport function updatedAgentFileManifest(\n  cwd: string,\n  planned: Array<{ path: string }>,\n  existing: Readonly<Record<string, string>> | undefined,\n  managed: Readonly<Record<string, string>>,\n): Record<string, string> {\n  const out = { ...existing };\n  for (const file of planned) delete out[manifestPath(cwd, file.path)];\n  return Object.assign(out, managed);\n}\n\nexport interface AgentFileSync {\n  created: string[];\n  refreshed: string[];\n  /** Repo-relative path -> digest of the bytes loam is allowed to refresh. */\n  managed: Record<string, string>;\n}\n\n/**\n * Create missing files and refresh only files still byte-identical to the\n * digest recorded when loam last wrote them. A human edit breaks that equality\n * and therefore revokes loam's authority over the file without a marker block\n * or a prompt.\n */\nexport async function syncAgentCommands(req: {\n  cwd: string;\n  toolIds?: string[];\n  delivery?: readonly Delivery[];\n  profile?: AgentProfile;\n  known?: Readonly<Record<string, string>>;\n}): Promise<AgentFileSync> {\n  const { cwd, toolIds = [\"claude\"], delivery = DELIVERIES, profile = \"full\", known = {} } = req;\n  const out: AgentFileSync = { created: [], refreshed: [], managed: {} };\n  for (const { path, content } of plannedCommandFiles(cwd, toolIds, delivery, profile)) {\n    const key = manifestPath(cwd, path);\n    const desired = contentDigest(content);\n    if (!existsSync(path)) {\n      await mkdir(dirname(path), { recursive: true });\n      await writeFile(path, content, \"utf8\");\n      out.created.push(path);\n      out.managed[key] = desired;\n      continue;\n    }\n    const current = contentDigest(await readFile(path));\n    if (current === desired) {\n      out.managed[key] = desired;\n      continue;\n    }\n    if (known[key] !== current) continue;\n    await writeFile(path, content, \"utf8\");\n    out.refreshed.push(path);\n    out.managed[key] = desired;\n  }\n  return out;\n}\n\n/**\n * The registry ids whose marker paths are present in `cwd` — what `loam init`\n * writes for when nobody passed `--tools`.\n *\n * A repo with `.cursor/` and no Claude Code used to get `.claude/commands/`\n * and nothing it could actually run. Presence is the whole test, and existence\n * (not directory-ness) is what is asked, because a marker is as often a file as\n * a directory — `.github/copilot-instructions.md` is the honest signal for\n * Copilot where `.github/` itself is noise.\n */\nexport function detectAgentTools(cwd: string): string[] {\n  return Object.entries(AGENT_TOOLS)\n    .filter(([, tool]) => tool.detect.some((marker) => existsSync(join(cwd, marker))))\n    .map(([id]) => id);\n}\n"]}

package/dist/core/agent/tools/dialects.js

@@ -58,6 +58,7 @@ const LOAM_ALLOWED_VERBS = [
     "status",
     "steps",
     "subsystem",
+    "tasks",
     "unarchive",
     "validate",
     "verify",