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

package/dist/commands/validate/checks/vocabulary.js

@@ -1,16 +0,0 @@
-/**
- * The handful of facts every validate check speaks, and none of them owns.
- *
- * A leaf module rather than a paragraph beside its first caller, because the
- * checks are spread across packages and each of these is read from more than
- * one of them: the dispatcher's rollup and the service target's sources check
- * both name one finding code. ACTOR_KINDS and EXTERNAL_TAG lived here too, until they
- * reached a third copy (`core/gate/partners.ts`, `core/verify/checklist.ts`);
- * their shared spelling is now `core/vocabulary/maturity.ts`, beside the
- * landscape evidence that asks the same questions. The parser-diagnostic line
- * (`errorText`) went the same way, to `core/c4/likec4.ts` beside the type it
- * reads, once four hand-rolled copies had disagreed about the line base.
- */
-/** The one code the rollup line counts; spelled once so the two cannot drift. */
-export const UNVERIFIABLE = "sources.unverifiable-from-here";
-//# sourceMappingURL=vocabulary.js.map

package/dist/commands/validate/checks/vocabulary.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../../../../src/commands/validate/checks/vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,gCAAgC,CAAC","sourcesContent":["/**\n * The handful of facts every validate check speaks, and none of them owns.\n *\n * A leaf module rather than a paragraph beside its first caller, because the\n * checks are spread across packages and each of these is read from more than\n * one of them: the dispatcher's rollup and the service target's sources check\n * both name one finding code. ACTOR_KINDS and EXTERNAL_TAG lived here too, until they\n * reached a third copy (`core/gate/partners.ts`, `core/verify/checklist.ts`);\n * their shared spelling is now `core/vocabulary/maturity.ts`, beside the\n * landscape evidence that asks the same questions. The parser-diagnostic line\n * (`errorText`) went the same way, to `core/c4/likec4.ts` beside the type it\n * reads, once four hand-rolled copies had disagreed about the line base.\n */\n\n/** The one code the rollup line counts; spelled once so the two cannot drift. */\nexport const UNVERIFIABLE = \"sources.unverifiable-from-here\";\n"]}

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

@@ -1,221 +0,0 @@
-/**
- * The document's opening arc: what the docs repo HOLDS — the layout, how its
- * documents link to each other, the glossary, architectural obligations, and
- * the `loam.json` wiring every repository commits.
- *
- * The three sections that used to close this file — the architecture spec
- * axis, the generated Gherkin suite, and the frontmatter/vouch chain — are now
- * the `loam-authoring` reference page (../workflows/reference/authoring.ts),
- * printed by `loam instructions loam-authoring` rather than written into
- * AGENTS.md. They are grammars consulted while writing ONE document, and the
- * file they were in is auto-loaded on every session by hosts that truncate it
- * silently; ./command-map.ts's header carries the measurement that decided it.
- * What is left here is what an agent must know before it can form a question
- * at all.
- *
- * One section of the AGENTS.md template. ../agents-md.ts assembles the
- * document by PLAIN CONCATENATION — no join separator — so every section
- * starts at the first character of its opening line and ends with the newline
- * that closes its last one. Keep that shape when editing, or two sections glue
- * onto one line in every docs repo loam scaffolds from now on.
- */
-export const ARTIFACTS = `# Working in this docs repo
-
-This is a **loam** docs repo: the shared source of truth for a governed software
-system — its architecture, requirements, contracts and evidence. Everything here
-is plain files. \`loam\` reads and writes them; delete \`loam\` and the docs remain.
-
-**The bar this artifact set aims at is reproducibility**: a reader should be able
-to answer, from these files alone — what each governed boundary exposes, what it
-reaches, what shapes it exchanges, how it is run, and what pages whom —
-without opening the code. \`loam validate\` grades form and joins, never depth:
-green means the files agree with each other, and the bar is what "done" is
-measured against — a thin baseline that validates is thin, not done.
-
-## Layout
-
-\`\`\`
-architecture/landscape.likec4     the living C4 model of the whole system
-architecture/permissions.yaml     optional system-wide authorization vocabulary
-architecture/obligations.yaml     optional ARCHITECTURAL obligations (#obl-<name> on the map)
-architecture/adrs/NNNN-*.md       optional SYSTEM-level decisions (MADR) — only their links are graded
-glossary/<term>.md                optional domain vocabulary — one file per term, nesting allowed
-services/<svc>/
-  model.likec4                    this governed boundary's C4
-  spec.md                         its living requirements (current state)
-  arch.spec.md                    its living ARCHITECTURE requirements (outbox, retries, alerts)
-  openapi.yaml                    its API contract
-  asyncapi.yaml                   its AsyncAPI 3 event contract
-  usecases/<name>.likec4          optional flows INSIDE this boundary — dynamic views over its containers, graded when tagged #req- (any .likec4 beside model.likec4 is read the same way)
-  adrs/  runbook.md  health.yaml  why it is like this, how to run it
-features/<FEAT>/                  a change in flight
-  intent.md                       why, in business terms
-  delta.likec4                    the architecture change, tagged #<FEAT>
-  specs/<svc>/spec.md             the requirement change for one governed boundary
-  specs/<svc>/arch.spec.md        the architectural requirement change, same delta grammar
-  specs/<svc>/openapi.yaml        the endpoints this feature adds
-  specs/<svc>/asyncapi.yaml       the event-contract delta (optional; a complete AsyncAPI 3 document)
-  verification.yaml               what was checked once the code was built
-features/archive/<FEAT>/          shipped changes — the evolution history
-\`\`\`
-
-## Linking between documents
-
-Documents here link to each other with **standard markdown links**, and the
-target is a relative path to the file:
-
-\`\`\`markdown
-[0001 — transactional outbox](../../architecture/adrs/0001-transactional-outbox.md)
-\`\`\`
-
-Two reasons, and the second is the one that decides it. A markdown link renders
-as a link in pull-request review, which is where these documents are actually
-read, while \`[[0001 transactional outbox]]\` renders there as the literal
-brackets somebody typed. And its target is a real relative path, so "does this
-link resolve" is a filesystem question with a yes-or-no answer — where resolving
-a wikilink means reimplementing Obsidian's shortest-unique-path search across the
-whole repo, which is guessing, and loam refuses and names rather than guessing.
-
-You lose nothing by it. Obsidian reads a repo written this way with no
-integration at all — graph view, backlinks and search all work on markdown links
-— and its per-vault \`Use [[Wikilinks]]\` setting turns OFF, after which its own
-autocomplete and rename-tracking produce markdown links too. The authoring
-comfort is a toggle in somebody's editor, not a decision this repo carries.
-
-**\`loam validate\` resolves these links** (\`link.unresolved\`, error): a relative
-target that names nothing is a broken join, reported once per document with
-every bad link and its line. A link here is a **join**, not decoration — a
-requirement that names a term wants that term's document linked, and an ADR that
-supersedes another wants to say which, the same kind of relationship
-\`Operations:\` and \`Covers:\` already state.
-
-Three things are deliberately NOT graded, so write them freely: a target outside
-this repository (\`../../some-service/README.md\` — that tree may not be checked
-out beside these documents), a link to a heading (\`#section\`), and any link
-inside a fenced code block or an inline code span, which is how a document shows
-the convention without being convicted for it.
-
-CASE **is** graded, and deliberately: \`[Order](Order.md)\` beside a file called
-\`order.md\` resolves on Windows and macOS and 404s on GitHub and every Linux
-runner, so the message names the stored spelling on all of them alike.
-
-## The glossary — the system's domain words
-
-\`glossary/<term>.md\`, one file per term, nesting allowed
-(\`glossary/payments/authorization.md\` is the term \`payments/authorization\`). There is
-no \`glossary.yaml\`: a definition is prose, and the DIRECTORY is the list. The
-directory's existence is the opt-in — a system without one hears nothing.
-
-**A term is checkable because a link is a join.** Cite it from the document that
-uses the word — a requirement, a capability document, a feature's intent — with an
-ordinary relative link:
-
-\`\`\`markdown
-An [Order](../../glossary/order.md) is what a customer has confirmed.
-\`\`\`
-
-A citation that does not resolve is \`link.unresolved\` like any other; a term nothing
-outside \`glossary/\` cites is \`glossary.unlinked\` (warn). Terms citing each other is
-normal and does NOT count as adoption — a glossary is a network of definitions, and
-two terms defining each other say nothing about whether the system uses either word.
-\`loam list glossary\` prints every term with the documents that cite it.
-
-**A feature may bring a new word with it**: write it at
-\`features/<FEAT>/glossary/<term>.md\` and \`loam archive\` copies it into \`glossary/\`,
-\`loam unarchive\` takes it back out. This route is CREATE-ONLY — a term the living
-glossary already defines is \`glossary.term-exists\`, which \`--approve\` does not
-override, because the merge is a whole-file copy and would replace an authored
-definition wholesale. To CHANGE a definition, edit \`glossary/<term>.md\` directly in
-the same pull request, where git produces an ordinary conflict.
-
-Cite the new word at its FUTURE living path (\`../../../../glossary/order.md\` from a
-\`specs/<svc>/\` delta) — that link resolves while the feature is in flight, and the
-merge re-expresses it from wherever the text lands, so it keeps resolving afterwards.
-
-Write the definition for a reader who knows the business and not this system: what the
-word means, and what it is NOT (an order is not a cart). Never which service owns it —
-that is the system map's question and it changes.
-
-
-## Architectural obligations — what the architect hands the team
-
-An architect has always had one checked channel here: an edge carrying
-\`metadata { op 'authorizePayment' }\` obliges the provider to define that operationId,
-or \`spine.op-undefined\` fails the gate. Obligations are the same handoff for the rules
-that VARY — an outbox on this publisher and not that one, a circuit breaker on two
-edges out of five — and they are three separate things on purpose:
-
-- an **ADR** in \`architecture/adrs/\` says WHAT was decided, as thin or as thick as the
-  decision needs;
-- a **\`#obl-<name>\` tag** on an element or an edge in \`architecture/landscape.likec4\`
-  says WHERE it applies, so one ADR governs three edges and not the fourth without the
-  document forking;
-- **\`architecture/obligations.yaml\`** declares the names, so a mistyped tag is an error
-  rather than a word nobody notices.
-
-\`\`\`yaml
-obligations:
-  outbox:
-    description: Publishers write the event and the state change in one transaction.
-    adr: architecture/adrs/0001-transactional-outbox.md   # relative to the docs repo root
-\`\`\`
-
-**Your side of it is \`Covers:\`**. A tagged object with no living requirement covering it
-is \`obligation.uncovered\` (warn), and the finding names the service, the object and the
-exact line to write — \`Covers: <element>\` or \`Covers: <source> -> <target>\` in that
-service's \`arch.spec.md\`, with a scenario that proves it. An id is its own tag suffix,
-so it may hold letters, digits, \`_\` and \`-\` only.
-
-## \`loam.json\` — the wiring, in every repo
-
-A governed system is **N + 1 repositories**: this docs repo, and one per governed
-implementation boundary. Paths and commands call that boundary a \`service\`; it
-may be a modular monolith, a network service, a CLI or a worker. Every repo
-commits its own \`loam.json\`, so an agent, human or CI runner can find the rest
-of the system. There is no global config; without a \`loam.json\`, commands refuse
-with \`no-config\` rather than guessing.
-
-\`\`\`json
-{ "docsDir": "../docs-repo", "service": "payment-service", "gherkinDir": "features" }
-\`\`\`
-
-- \`docsDir\` — where the docs repo is, **stored exactly as it was passed** and
-  resolved against the directory holding the \`loam.json\`. So \`../docs-repo\`
-  keeps working on every machine that checks the repos out side by side, which
-  is the point of committing the file. An absolute path is a warning
-  (\`doctor.docs-absolute\`): it resolves only on the machine that ran \`loam init\`.
-  The docs repo's own \`loam.json\` says \`"docsDir": "."\`.
-- \`service\` — the canonical id of the governed boundary THIS repo contains, i.e. the
-  \`services/<id>/\` directory it is allowed to speak for. \`loam vouch\`,
-  \`loam gherkin\` and \`loam verify --service\` when writing with \`--record\`,
-  \`--results\` or \`--contract-results\` bind to it; without it they refuse
-  (\`repository-unavailable\`) rather than write another boundary's documents
-  from a repo that is not that boundary's. A read-only verify checklist needs no
-  binding and works from the docs repo.
-- \`gherkinDir\` — optional, default \`features\`: the directory \`loam gherkin\`
-  writes its own \`loam/\` subtree into.
-- \`agentTools\` — optional: the agent tools \`loam init\` has written command and
-  skill files for here, accumulated across runs. Written by \`init\`, read by
-  \`loam doctor\`; nothing else depends on it, and a config without it loads.
-
-**Step 0 of everything below, once per repo:**
-
-\`\`\`sh
-loam init --docs ../docs-repo --service payment-service   # in EACH service repo
-loam doctor                                               # before you trust any of it
-\`\`\`
-
-\`loam init --docs <dir>\` **joins** an existing docs repo; creating a new one
-takes \`--create\`, so a mistyped path cannot quietly scaffold a second source of
-truth beside the real one. \`loam doctor\` is the read-only preflight: it reads
-loam.json defensively, resolves \`docsDir\`, probes access, checks \`services/\` and
-the system map, and reports the service binding — run it first when anything
-behaves as though the system were empty.
-
-**Living vs delta.** \`services/<svc>/spec.md\` is the complete current state.
-\`features/<FEAT>/specs/<svc>/spec.md\` is a diff against it, reviewed as a diff, with
-requirements grouped under \`## ADDED\`, \`## MODIFIED\` or \`## REMOVED Requirements\`.
-\`loam archive\` folds the delta into the living state.
-
-`;
-//# sourceMappingURL=artifacts.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsMxB,CAAC","sourcesContent":["/**\n * The document's opening arc: what the docs repo HOLDS — the layout, how its\n * documents link to each other, the glossary, architectural obligations, and\n * the `loam.json` wiring every repository commits.\n *\n * The three sections that used to close this file — the architecture spec\n * axis, the generated Gherkin suite, and the frontmatter/vouch chain — are now\n * the `loam-authoring` reference page (../workflows/reference/authoring.ts),\n * printed by `loam instructions loam-authoring` rather than written into\n * AGENTS.md. They are grammars consulted while writing ONE document, and the\n * file they were in is auto-loaded on every session by hosts that truncate it\n * silently; ./command-map.ts's header carries the measurement that decided it.\n * What is left here is what an agent must know before it can form a question\n * at all.\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 ARTIFACTS = `# Working in this docs repo\n\nThis is a **loam** docs repo: the shared source of truth for a governed software\nsystem — its architecture, requirements, contracts and evidence. Everything here\nis plain files. \\`loam\\` reads and writes them; delete \\`loam\\` and the docs remain.\n\n**The bar this artifact set aims at is reproducibility**: a reader should be able\nto answer, from these files alone — what each governed boundary exposes, what it\nreaches, what shapes it exchanges, how it is run, and what pages whom —\nwithout opening the code. \\`loam validate\\` grades form and joins, never depth:\ngreen means the files agree with each other, and the bar is what \"done\" is\nmeasured against — a thin baseline that validates is thin, not done.\n\n## Layout\n\n\\`\\`\\`\narchitecture/landscape.likec4     the living C4 model of the whole system\narchitecture/permissions.yaml     optional system-wide authorization vocabulary\narchitecture/obligations.yaml     optional ARCHITECTURAL obligations (#obl-<name> on the map)\narchitecture/adrs/NNNN-*.md       optional SYSTEM-level decisions (MADR) — only their links are graded\nglossary/<term>.md                optional domain vocabulary — one file per term, nesting allowed\nservices/<svc>/\n  model.likec4                    this governed boundary's C4\n  spec.md                         its living requirements (current state)\n  arch.spec.md                    its living ARCHITECTURE requirements (outbox, retries, alerts)\n  openapi.yaml                    its API contract\n  asyncapi.yaml                   its AsyncAPI 3 event contract\n  usecases/<name>.likec4          optional flows INSIDE this boundary — dynamic views over its containers, graded when tagged #req- (any .likec4 beside model.likec4 is read the same way)\n  adrs/  runbook.md  health.yaml  why it is like this, how to run it\nfeatures/<FEAT>/                  a change in flight\n  intent.md                       why, in business terms\n  delta.likec4                    the architecture change, tagged #<FEAT>\n  specs/<svc>/spec.md             the requirement change for one governed boundary\n  specs/<svc>/arch.spec.md        the architectural requirement change, same delta grammar\n  specs/<svc>/openapi.yaml        the endpoints this feature adds\n  specs/<svc>/asyncapi.yaml       the event-contract delta (optional; a complete AsyncAPI 3 document)\n  verification.yaml               what was checked once the code was built\nfeatures/archive/<FEAT>/          shipped changes — the evolution history\n\\`\\`\\`\n\n## Linking between documents\n\nDocuments here link to each other with **standard markdown links**, and the\ntarget is a relative path to the file:\n\n\\`\\`\\`markdown\n[0001 — transactional outbox](../../architecture/adrs/0001-transactional-outbox.md)\n\\`\\`\\`\n\nTwo reasons, and the second is the one that decides it. A markdown link renders\nas a link in pull-request review, which is where these documents are actually\nread, while \\`[[0001 transactional outbox]]\\` renders there as the literal\nbrackets somebody typed. And its target is a real relative path, so \"does this\nlink resolve\" is a filesystem question with a yes-or-no answer — where resolving\na wikilink means reimplementing Obsidian's shortest-unique-path search across the\nwhole repo, which is guessing, and loam refuses and names rather than guessing.\n\nYou lose nothing by it. Obsidian reads a repo written this way with no\nintegration at all — graph view, backlinks and search all work on markdown links\n— and its per-vault \\`Use [[Wikilinks]]\\` setting turns OFF, after which its own\nautocomplete and rename-tracking produce markdown links too. The authoring\ncomfort is a toggle in somebody's editor, not a decision this repo carries.\n\n**\\`loam validate\\` resolves these links** (\\`link.unresolved\\`, error): a relative\ntarget that names nothing is a broken join, reported once per document with\nevery bad link and its line. A link here is a **join**, not decoration — a\nrequirement that names a term wants that term's document linked, and an ADR that\nsupersedes another wants to say which, the same kind of relationship\n\\`Operations:\\` and \\`Covers:\\` already state.\n\nThree things are deliberately NOT graded, so write them freely: a target outside\nthis repository (\\`../../some-service/README.md\\` — that tree may not be checked\nout beside these documents), a link to a heading (\\`#section\\`), and any link\ninside a fenced code block or an inline code span, which is how a document shows\nthe convention without being convicted for it.\n\nCASE **is** graded, and deliberately: \\`[Order](Order.md)\\` beside a file called\n\\`order.md\\` resolves on Windows and macOS and 404s on GitHub and every Linux\nrunner, so the message names the stored spelling on all of them alike.\n\n## The glossary — the system's domain words\n\n\\`glossary/<term>.md\\`, one file per term, nesting allowed\n(\\`glossary/payments/authorization.md\\` is the term \\`payments/authorization\\`). There is\nno \\`glossary.yaml\\`: a definition is prose, and the DIRECTORY is the list. The\ndirectory's existence is the opt-in — a system without one hears nothing.\n\n**A term is checkable because a link is a join.** Cite it from the document that\nuses the word — a requirement, a capability document, a feature's intent — with an\nordinary relative link:\n\n\\`\\`\\`markdown\nAn [Order](../../glossary/order.md) is what a customer has confirmed.\n\\`\\`\\`\n\nA citation that does not resolve is \\`link.unresolved\\` like any other; a term nothing\noutside \\`glossary/\\` cites is \\`glossary.unlinked\\` (warn). Terms citing each other is\nnormal and does NOT count as adoption — a glossary is a network of definitions, and\ntwo terms defining each other say nothing about whether the system uses either word.\n\\`loam list glossary\\` prints every term with the documents that cite it.\n\n**A feature may bring a new word with it**: write it at\n\\`features/<FEAT>/glossary/<term>.md\\` and \\`loam archive\\` copies it into \\`glossary/\\`,\n\\`loam unarchive\\` takes it back out. This route is CREATE-ONLY — a term the living\nglossary already defines is \\`glossary.term-exists\\`, which \\`--approve\\` does not\noverride, because the merge is a whole-file copy and would replace an authored\ndefinition wholesale. To CHANGE a definition, edit \\`glossary/<term>.md\\` directly in\nthe same pull request, where git produces an ordinary conflict.\n\nCite the new word at its FUTURE living path (\\`../../../../glossary/order.md\\` from a\n\\`specs/<svc>/\\` delta) — that link resolves while the feature is in flight, and the\nmerge re-expresses it from wherever the text lands, so it keeps resolving afterwards.\n\nWrite the definition for a reader who knows the business and not this system: what the\nword means, and what it is NOT (an order is not a cart). Never which service owns it —\nthat is the system map's question and it changes.\n\n\n## Architectural obligations — what the architect hands the team\n\nAn architect has always had one checked channel here: an edge carrying\n\\`metadata { op 'authorizePayment' }\\` obliges the provider to define that operationId,\nor \\`spine.op-undefined\\` fails the gate. Obligations are the same handoff for the rules\nthat VARY — an outbox on this publisher and not that one, a circuit breaker on two\nedges out of five — and they are three separate things on purpose:\n\n- an **ADR** in \\`architecture/adrs/\\` says WHAT was decided, as thin or as thick as the\n  decision needs;\n- a **\\`#obl-<name>\\` tag** on an element or an edge in \\`architecture/landscape.likec4\\`\n  says WHERE it applies, so one ADR governs three edges and not the fourth without the\n  document forking;\n- **\\`architecture/obligations.yaml\\`** declares the names, so a mistyped tag is an error\n  rather than a word nobody notices.\n\n\\`\\`\\`yaml\nobligations:\n  outbox:\n    description: Publishers write the event and the state change in one transaction.\n    adr: architecture/adrs/0001-transactional-outbox.md   # relative to the docs repo root\n\\`\\`\\`\n\n**Your side of it is \\`Covers:\\`**. A tagged object with no living requirement covering it\nis \\`obligation.uncovered\\` (warn), and the finding names the service, the object and the\nexact line to write — \\`Covers: <element>\\` or \\`Covers: <source> -> <target>\\` in that\nservice's \\`arch.spec.md\\`, with a scenario that proves it. An id is its own tag suffix,\nso it may hold letters, digits, \\`_\\` and \\`-\\` only.\n\n## \\`loam.json\\` — the wiring, in every repo\n\nA governed system is **N + 1 repositories**: this docs repo, and one per governed\nimplementation boundary. Paths and commands call that boundary a \\`service\\`; it\nmay be a modular monolith, a network service, a CLI or a worker. Every repo\ncommits its own \\`loam.json\\`, so an agent, human or CI runner can find the rest\nof the system. There is no global config; without a \\`loam.json\\`, commands refuse\nwith \\`no-config\\` rather than guessing.\n\n\\`\\`\\`json\n{ \"docsDir\": \"../docs-repo\", \"service\": \"payment-service\", \"gherkinDir\": \"features\" }\n\\`\\`\\`\n\n- \\`docsDir\\` — where the docs repo is, **stored exactly as it was passed** and\n  resolved against the directory holding the \\`loam.json\\`. So \\`../docs-repo\\`\n  keeps working on every machine that checks the repos out side by side, which\n  is the point of committing the file. An absolute path is a warning\n  (\\`doctor.docs-absolute\\`): it resolves only on the machine that ran \\`loam init\\`.\n  The docs repo's own \\`loam.json\\` says \\`\"docsDir\": \".\"\\`.\n- \\`service\\` — the canonical id of the governed boundary THIS repo contains, i.e. the\n  \\`services/<id>/\\` directory it is allowed to speak for. \\`loam vouch\\`,\n  \\`loam gherkin\\` and \\`loam verify --service\\` when writing with \\`--record\\`,\n  \\`--results\\` or \\`--contract-results\\` bind to it; without it they refuse\n  (\\`repository-unavailable\\`) rather than write another boundary's documents\n  from a repo that is not that boundary's. A read-only verify checklist needs no\n  binding and works from the docs repo.\n- \\`gherkinDir\\` — optional, default \\`features\\`: the directory \\`loam gherkin\\`\n  writes its own \\`loam/\\` subtree into.\n- \\`agentTools\\` — optional: the agent tools \\`loam init\\` has written command and\n  skill files for here, accumulated across runs. Written by \\`init\\`, read by\n  \\`loam doctor\\`; nothing else depends on it, and a config without it loads.\n\n**Step 0 of everything below, once per repo:**\n\n\\`\\`\\`sh\nloam init --docs ../docs-repo --service payment-service   # in EACH service repo\nloam doctor                                               # before you trust any of it\n\\`\\`\\`\n\n\\`loam init --docs <dir>\\` **joins** an existing docs repo; creating a new one\ntakes \\`--create\\`, so a mistyped path cannot quietly scaffold a second source of\ntruth beside the real one. \\`loam doctor\\` is the read-only preflight: it reads\nloam.json defensively, resolves \\`docsDir\\`, probes access, checks \\`services/\\` and\nthe system map, and reports the service binding — run it first when anything\nbehaves as though the system were empty.\n\n**Living vs delta.** \\`services/<svc>/spec.md\\` is the complete current state.\n\\`features/<FEAT>/specs/<svc>/spec.md\\` is a diff against it, reviewed as a diff, with\nrequirements grouped under \\`## ADDED\\`, \\`## MODIFIED\\` or \\`## REMOVED Requirements\\`.\n\\`loam archive\\` folds the delta into the living state.\n\n`;\n"]}

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

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

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

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

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

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

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

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