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

package/dist/core/agent/workflows/feature.js

@@ -0,0 +1,105 @@
+/** Starting a feature: explore, scaffold, author the three axes, rebase, validate. */
+export const LOAM_FEATURE = {
+    name: "loam-feature",
+    description: "Start a new loam feature — scaffold it, then author the C4 delta and requirement deltas",
+    argumentHint: `<FEAT-id> "<title>"`,
+    purpose: "Start a feature in the docs repo: decide which services it touches, scaffold it, then author the C4 delta and one requirement delta per service. The `--touches` list is the hardest call in the cycle and nothing downstream catches one that is short by a service.",
+    invocation: 'loam instructions loam-feature $1 "$2"',
+    // $2 is the feature's human title: any string is a legal one.
+    placeholders: ["feature", "free"],
+    spine: [
+        "read `AGENTS.md` at the docs repo root — it defines the ID spine everything else depends on",
+        "`loam explore` around the services you think are involved: the ring one hop out, and what is already in flight over the same ground",
+        "`loam status` / `loam list` / `loam show` — what exists and what is already owed",
+        "`loam new` with a `--touches` per service it changes and a `--new-service` per service it introduces",
+        "author what the templates left as TODO: intent, the C4 delta, the per-service spec / arch spec / openapi",
+        "`loam rebase` — pin every MODIFIED requirement and every operation to the living version you wrote against",
+        "validate the feature, then read `loam dependencies` before anyone starts building",
+    ],
+    body: `Start a new feature in the loam docs repo (its path is \`docsDir\` in ./loam.json).
+
+1. Read \`AGENTS.md\` at the root of the docs repo first — it defines the ID spine
+   everything here depends on.
+2. Understand the current state before proposing a change:
+   - \`loam status --json\` — what is already in flight and what it is waiting on.
+     Run this FIRST if you joined this repository halfway or lost the session:
+     \`next[]\` is ordered and each entry carries the literal command to run, so it
+     tells you whether the work is to start $1 at all. \`loam status $1 --json\`
+     narrows it to one feature once $1 exists
+   - \`loam list --json\` — what services exist, and what documentation they are missing
+   - \`loam show <service> --json\` — what a service owns, exposes, and who already calls it
+2b. \`loam explore <service> --json --as $1\` around every service you believe this
+   feature touches. This is the step that decides step 3's \`--touches\` list, and it
+   is the only decision in the cycle nothing downstream catches — a list short by one
+   service produces a feature that validates, archives and ships with a consumer
+   nobody updated. Read four fields:
+   - \`neighbours\` — the services one hop out in the fleet map. Weigh each one. loam
+     knows they are connected, not whether you change them, and it deliberately
+     leaves them OUT of the suggested command line rather than guessing for you
+   - \`services[].maturity\` — a service at \`empty\` or \`partial\` has no baseline to
+     write a delta against, so the work starts with \`loam adopt --service <id>\`, not
+     with this feature
+   - \`services[].operations\` — what each already exposes, so an operation you are
+     about to "add" that is already there becomes a MODIFIED requirement instead
+   - \`overlaps\` — active features already carrying a delta for these services.
+     \`loam dependencies --json\` (step 7) then says which must archive first
+   \`--op <operationId>\` seeds from an operation when you know the call but not who
+   owns it. A seed naming no \`services/<id>/\` is reported in \`unknown\` with the
+   closest real ids rather than refused — the feature may be introducing it, and a
+   typo looks identical until you read that list. \`scaffold\` is the literal step-3
+   command line the seeds imply, with \`--new-service\` where the service does not
+   exist yet.
+3. Scaffold it: \`loam new $1 --title "$2"\`, adding \`--touches <id>\` for every service the
+   feature touches and \`--new-service <id>\` for every one it introduces. Every id goes
+   through the \`services/<id>/\` grammar, so a typo is refused (\`invalid-option\`)
+   rather than scaffolded; a \`--touches\` that matches nothing existing comes back as
+   a \`note\` with the close ids, not as a failure — read it, because a \`--touches\`
+   naming a service that does not exist is \`delta.service-unknown\` at validate time
+   and a phantom \`services/<typo>/\` directory if it ever archives.
+4. Author what the templates left as TODO. This step is gated, not advisory:
+   \`loam archive\` refuses a scaffold nobody edited (\`scaffold.placeholder\`,
+   \`intent.empty\`), so the placeholder text cannot reach the living docs.
+   - \`intent.md\` — the problem in business terms, in prose; the scaffold's
+     comment-only Why/Scope count as unwritten
+   - \`delta.likec4\` — new elements and edges, each tagged \`#$1\`; every call edge carries
+     \`metadata { op '<operationId>' }\`; replace the scaffolded TODO description on each
+     new service. For a requirements-only feature DELETE this
+     file: an empty delta is legal, but a scaffold left half-filled is not
+   - \`specs/<svc>/spec.md\` — the example requirement ships INSIDE the template's
+     comment: copy it out, unindent, one behaviour per requirement, SHALL, at
+     least one Given/When/Then scenario; add \`Operations:\` once the operation exists
+   - \`specs/<svc>/arch.spec.md\` — the architectural obligations (outbox, retries,
+     idempotency, alerts), same grammar; a \`Covers:\` line per requirement naming the
+     tagged elements/edges it accounts for, or \`c4.uncovered\` says nothing does
+   - \`specs/<svc>/openapi.yaml\` — define every operationId the edges reference
+   - \`specs/<svc>/asyncapi.yaml\` — the event axis, only when the feature changes
+     what a service puts on or takes off the bus: a complete AsyncAPI 3.0
+     document restating the living contract around the slots you change, new
+     messages under \`components.messages\`, and a \`Publishes:\`/\`Consumes:\` line
+     on each requirement that names them. \`loam new\` scaffolds none — an event
+     contract is genuinely optional
+5. **\`loam rebase $1\`** — the step between authoring and checking, and the one that
+   stops two features in flight from silently deleting each other's work. It pins
+   every MODIFIED/REMOVED requirement (\`Based-On:\`), every operation in the
+   contract delta and every asyncapi channel/operation/message slot
+   (\`x-loam-based-on\`) to the living version you wrote against.
+   Run it on the contract axes even if you changed exactly one endpoint: that is
+   what marks the REST of the document as quotation the merge must not write back.
+   Without the pins, \`delta.baseline-missing\` / \`openapi.baseline-missing\` /
+   \`asyncapi.baseline-missing\` GATE
+   the archive: before they did, the second feature to archive reverted the
+   first — with \`+0 ~1 -0\`, exit 0, and nobody told. Rebase clears them; a
+   human's \`--approve\` is the only other way past.
+   Restamping is not resolving: if rebase reports a requirement as MOVED, re-read
+   the living text and fold in what you still mean BEFORE you ship.
+6. \`loam validate --feature $1 --json\`. Do not stop while \`valid\` is false.
+7. \`loam dependencies $1 --json\` before anyone starts building: it says which
+   features in flight have to archive first (\`order\`) and which collisions no
+   ordering fixes (\`conflicts\`, \`cycles\`). Every conflict it names is one \`loam rebase\`
+   cannot fix for you — two intentions have to be merged by people.
+
+The operation's three spellings — the edge's \`op\`, the requirement's \`Operations:\`
+line, and the OpenAPI \`operationId\` — must match exactly.
+`,
+};
+//# sourceMappingURL=feature.js.map

package/dist/core/agent/workflows/feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature.js","sourceRoot":"","sources":["../../../../src/core/agent/workflows/feature.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,MAAM,CAAC,MAAM,YAAY,GAAmB;IAC1C,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,yFAAyF;IAC3F,YAAY,EAAE,qBAAqB;IACnC,OAAO,EACL,uQAAuQ;IACzQ,UAAU,EAAE,wCAAwC;IACpD,8DAA8D;IAC9D,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC;IACjC,KAAK,EAAE;QACL,6FAA6F;QAC7F,qIAAqI;QACrI,kFAAkF;QAClF,sGAAsG;QACtG,0GAA0G;QAC1G,4GAA4G;QAC5G,mFAAmF;KACpF;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoFP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/** Starting a feature: explore, scaffold, author the three axes, rebase, validate. */\nexport const LOAM_FEATURE: CommandContent = {\n  name: \"loam-feature\",\n  description:\n    \"Start a new loam feature — scaffold it, then author the C4 delta and requirement deltas\",\n  argumentHint: `<FEAT-id> \"<title>\"`,\n  purpose:\n    \"Start a feature in the docs repo: decide which services it touches, scaffold it, then author the C4 delta and one requirement delta per service. The `--touches` list is the hardest call in the cycle and nothing downstream catches one that is short by a service.\",\n  invocation: 'loam instructions loam-feature $1 \"$2\"',\n  // $2 is the feature's human title: any string is a legal one.\n  placeholders: [\"feature\", \"free\"],\n  spine: [\n    \"read `AGENTS.md` at the docs repo root — it defines the ID spine everything else depends on\",\n    \"`loam explore` around the services you think are involved: the ring one hop out, and what is already in flight over the same ground\",\n    \"`loam status` / `loam list` / `loam show` — what exists and what is already owed\",\n    \"`loam new` with a `--touches` per service it changes and a `--new-service` per service it introduces\",\n    \"author what the templates left as TODO: intent, the C4 delta, the per-service spec / arch spec / openapi\",\n    \"`loam rebase` — pin every MODIFIED requirement and every operation to the living version you wrote against\",\n    \"validate the feature, then read `loam dependencies` before anyone starts building\",\n  ],\n  body: `Start a new feature in the loam docs repo (its path is \\`docsDir\\` in ./loam.json).\n\n1. Read \\`AGENTS.md\\` at the root of the docs repo first — it defines the ID spine\n   everything here depends on.\n2. Understand the current state before proposing a change:\n   - \\`loam status --json\\` — what is already in flight and what it is waiting on.\n     Run this FIRST if you joined this repository halfway or lost the session:\n     \\`next[]\\` is ordered and each entry carries the literal command to run, so it\n     tells you whether the work is to start $1 at all. \\`loam status $1 --json\\`\n     narrows it to one feature once $1 exists\n   - \\`loam list --json\\` — what services exist, and what documentation they are missing\n   - \\`loam show <service> --json\\` — what a service owns, exposes, and who already calls it\n2b. \\`loam explore <service> --json --as $1\\` around every service you believe this\n   feature touches. This is the step that decides step 3's \\`--touches\\` list, and it\n   is the only decision in the cycle nothing downstream catches — a list short by one\n   service produces a feature that validates, archives and ships with a consumer\n   nobody updated. Read four fields:\n   - \\`neighbours\\` — the services one hop out in the fleet map. Weigh each one. loam\n     knows they are connected, not whether you change them, and it deliberately\n     leaves them OUT of the suggested command line rather than guessing for you\n   - \\`services[].maturity\\` — a service at \\`empty\\` or \\`partial\\` has no baseline to\n     write a delta against, so the work starts with \\`loam adopt --service <id>\\`, not\n     with this feature\n   - \\`services[].operations\\` — what each already exposes, so an operation you are\n     about to \"add\" that is already there becomes a MODIFIED requirement instead\n   - \\`overlaps\\` — active features already carrying a delta for these services.\n     \\`loam dependencies --json\\` (step 7) then says which must archive first\n   \\`--op <operationId>\\` seeds from an operation when you know the call but not who\n   owns it. A seed naming no \\`services/<id>/\\` is reported in \\`unknown\\` with the\n   closest real ids rather than refused — the feature may be introducing it, and a\n   typo looks identical until you read that list. \\`scaffold\\` is the literal step-3\n   command line the seeds imply, with \\`--new-service\\` where the service does not\n   exist yet.\n3. Scaffold it: \\`loam new $1 --title \"$2\"\\`, adding \\`--touches <id>\\` for every service the\n   feature touches and \\`--new-service <id>\\` for every one it introduces. Every id goes\n   through the \\`services/<id>/\\` grammar, so a typo is refused (\\`invalid-option\\`)\n   rather than scaffolded; a \\`--touches\\` that matches nothing existing comes back as\n   a \\`note\\` with the close ids, not as a failure — read it, because a \\`--touches\\`\n   naming a service that does not exist is \\`delta.service-unknown\\` at validate time\n   and a phantom \\`services/<typo>/\\` directory if it ever archives.\n4. Author what the templates left as TODO. This step is gated, not advisory:\n   \\`loam archive\\` refuses a scaffold nobody edited (\\`scaffold.placeholder\\`,\n   \\`intent.empty\\`), so the placeholder text cannot reach the living docs.\n   - \\`intent.md\\` — the problem in business terms, in prose; the scaffold's\n     comment-only Why/Scope count as unwritten\n   - \\`delta.likec4\\` — new elements and edges, each tagged \\`#$1\\`; every call edge carries\n     \\`metadata { op '<operationId>' }\\`; replace the scaffolded TODO description on each\n     new service. For a requirements-only feature DELETE this\n     file: an empty delta is legal, but a scaffold left half-filled is not\n   - \\`specs/<svc>/spec.md\\` — the example requirement ships INSIDE the template's\n     comment: copy it out, unindent, one behaviour per requirement, SHALL, at\n     least one Given/When/Then scenario; add \\`Operations:\\` once the operation exists\n   - \\`specs/<svc>/arch.spec.md\\` — the architectural obligations (outbox, retries,\n     idempotency, alerts), same grammar; a \\`Covers:\\` line per requirement naming the\n     tagged elements/edges it accounts for, or \\`c4.uncovered\\` says nothing does\n   - \\`specs/<svc>/openapi.yaml\\` — define every operationId the edges reference\n   - \\`specs/<svc>/asyncapi.yaml\\` — the event axis, only when the feature changes\n     what a service puts on or takes off the bus: a complete AsyncAPI 3.0\n     document restating the living contract around the slots you change, new\n     messages under \\`components.messages\\`, and a \\`Publishes:\\`/\\`Consumes:\\` line\n     on each requirement that names them. \\`loam new\\` scaffolds none — an event\n     contract is genuinely optional\n5. **\\`loam rebase $1\\`** — the step between authoring and checking, and the one that\n   stops two features in flight from silently deleting each other's work. It pins\n   every MODIFIED/REMOVED requirement (\\`Based-On:\\`), every operation in the\n   contract delta and every asyncapi channel/operation/message slot\n   (\\`x-loam-based-on\\`) to the living version you wrote against.\n   Run it on the contract axes even if you changed exactly one endpoint: that is\n   what marks the REST of the document as quotation the merge must not write back.\n   Without the pins, \\`delta.baseline-missing\\` / \\`openapi.baseline-missing\\` /\n   \\`asyncapi.baseline-missing\\` GATE\n   the archive: before they did, the second feature to archive reverted the\n   first — with \\`+0 ~1 -0\\`, exit 0, and nobody told. Rebase clears them; a\n   human's \\`--approve\\` is the only other way past.\n   Restamping is not resolving: if rebase reports a requirement as MOVED, re-read\n   the living text and fold in what you still mean BEFORE you ship.\n6. \\`loam validate --feature $1 --json\\`. Do not stop while \\`valid\\` is false.\n7. \\`loam dependencies $1 --json\\` before anyone starts building: it says which\n   features in flight have to archive first (\\`order\\`) and which collisions no\n   ordering fixes (\\`conflicts\\`, \\`cycles\\`). Every conflict it names is one \\`loam rebase\\`\n   cannot fix for you — two intentions have to be merged by people.\n\nThe operation's three spellings — the edge's \\`op\\`, the requirement's \\`Operations:\\`\nline, and the OpenAPI \\`operationId\\` — must match exactly.\n`,\n};\n"]}

package/dist/core/agent/workflows/implement.js

@@ -0,0 +1,105 @@
+/** Building one service's slice: the delta brief, generated gherkin, steps, code, verify. */
+export const LOAM_IMPLEMENT = {
+    name: "loam-implement",
+    description: "Implement a loam feature's slice for one service — generated gherkin first, tests from it, then code",
+    argumentHint: "<FEAT-id> [service]",
+    purpose: "Build one service's part of a feature, in that service's own repository. The generated Gherkin is the acceptance criterion — it comes before the step definitions, and those come before the code.",
+    invocation: "loam instructions loam-implement $1 $2",
+    placeholders: ["feature", "service"],
+    spine: [
+        "`loam status` — where this feature actually is, and what is owed before you start",
+        "`loam context` — the briefing: the service's living slice, and every delta in flight over it",
+        "`loam delta` — the task: the intent, every requirement verbatim, the endpoints, and the calls in and out",
+        "`loam gherkin` in the service's repo — the digest-stamped `.feature` files. Never edit them",
+        "write step definitions for the generated scenarios first, outside the generated directory",
+        "implement until the suite passes, running it with a JSON report",
+        "honour the contract in both directions: expose every inbound operation, call every outbound one",
+        "`loam rebase` if building made you change the feature's documents at all, then validate the feature",
+    ],
+    body: `Implement one service's part of a feature. Every step runs in the SERVICE'S own
+repository, which needs its own committed ./loam.json — if there is none,
+\`loam init --docs <path-to-docs-repo> --service $2\` then \`loam doctor\` first.
+
+0. \`loam status $1 --json\` — where this feature actually is. Run it before
+   anything else if you joined halfway or lost the session: it says which
+   artifacts are still owed, whether another feature has to archive first, and
+   what the next step is, each \`next[]\` entry carrying the literal command. It
+   writes nothing, so it is always safe to re-run.
+1. \`loam context $2 --feature $1 --json\` — the briefing to load before touching
+   code: the service's living requirements and arch requirements verbatim, its
+   operations and messages as they stand today, the permissions and capabilities
+   its requirements join to, the fleet edges around it, and this feature's delta
+   over it (\`--feature $1\` narrows the in-flight section; drop it to see every
+   feature working over this service). The delta below is WHAT CHANGES; the pack
+   is what it changes INTO — read it first so a MODIFIED requirement lands as an
+   edit rather than a rewrite, and an operation you are about to add is caught
+   when the living contract already defines it. Exit 1 with \`ok: true\` means a
+   document behind the pack did not parse; the empty section beside the flag is
+   the parse failure, not "nothing here".
+2. \`loam delta $1 --service $2 --json\` (drop \`--service\` to use the service configured
+   in ./loam.json). That output IS the task:
+   - \`intent\` — why this exists
+   - \`requirements[]\` — what to build, with \`scenarios[].lines\` verbatim
+   - \`archRequirements[]\` — the architectural obligations (outbox, retries, alerts),
+     same shape; their scenarios become integration/ops tests, and \`covers\` names
+     the model objects each exercises
+   - \`architecture\` — whether this service is new, and the calls in and out of it
+   - \`api\` — the endpoints this feature adds or retires for this service: path,
+     method, operationId and summary, with removals spelled \`REMOVE <METHOD> <path>\`
+   - \`openapi\` — whether that contract could be read at all: \`unreadable\`, plus an
+     \`error\` when the parser gave a message. It rides beside \`api\` rather than
+     inside it because \`api\` stays the operations array it has always been, and it
+     is what tells an empty \`api\` apart from a contract delta that did not parse
+   - \`services\` — every service this feature projects onto, so a run without
+     \`--service\` tells you which ones to ask for rather than guessing
+   Exit 1 with \`ok: true\` means one of the two authored documents behind this brief
+   did not parse: \`architecture.errors\` non-empty (delta.likec4), or
+   \`openapi.unreadable\` true (the feature's openapi.yaml for this service). The empty
+   slice is the parse failure itself, not "nothing changes there". Stop and fix that
+   document before building anything — for the delta, \`loam validate $1 --json\` names
+   the error; the contract delta is not graded by validate, so read the parser message
+   the payload carries.
+3. In the service's repo, \`loam gherkin $1 --json\` — one \`.feature\` file per changed
+   requirement lands under \`<gherkinDir>/loam/\` (default \`features/loam/\`), scenarios
+   digest-stamped, arch requirements tagged \`@architecture\`. Those files ARE the
+   acceptance criteria. Never edit them: regeneration rewrites the directory, and
+   \`loam validate\` reports the suite stale by digest, not by your intentions.
+4. Write step definitions for the generated scenarios FIRST — outside \`loam/\`.
+   Do not paraphrase a scenario into something easier to pass; it is the acceptance
+   criterion someone else reviews against.
+   Run \`loam steps --service $2 --json\` before you write any: it collapses every
+   written step onto the phrase a definition actually matches, so you see the size
+   of the registry you owe and which phrases already exist. Write ONE definition per
+   phrase row. If \`nearDuplicates\` is non-empty, two rows differ by an article or a
+   trailing \`because …\` clause and one definition was meant — fix the SPEC's wording
+   and regenerate, rather than writing the second definition.
+   A step's argument arrives as an argument: a \`"""\` docstring is the payload, an
+   indented table is a DataTable. Assert against them; do not re-parse the step text.
+5. Implement until the suite passes — run it with a JSON report
+   (\`cucumber-js --format json:report.json\`):
+   \`loam verify $1 --service $2 --results report.json\` consumes that report as the
+   done-check's answer sheet. Record from THIS repo, with \`--service\` — the
+   \`--service\`-less \`--record\` form writes the whole record from one place and is
+   refused (\`record-federated\`) once another service has attested.
+6. Honour the contract: every operation in \`architecture.inbound\` must exist under
+   exactly that operationId, and every one in \`architecture.outbound\` must be called.
+7. If building made you change the feature's documents at all — a requirement's
+   wording, an operation in its openapi.yaml — **\`loam rebase $1\`** before you
+   validate. Every edit you make in the docs repo while other features are in
+   flight is written against a living document that may have moved since the
+   feature directory was created, and the pins are the only thing that lets the
+   merge tell an EDIT from a QUOTE — for operations, path-level keys and
+   components alike. \`delta.baseline-missing\` and
+   \`openapi.baseline-missing\` are the warnings that say you skipped it — archive
+   refuses on them until you rebase (or a human \`--approve\`s the unpinned merge);
+   \`delta.baseline-stale\` / \`openapi.baseline-stale\` are archive refusing because
+   somebody landed a change underneath you — re-read theirs, fold in what you
+   still mean, then rebase again. Re-pinning without re-reading is how you
+   overwrite someone else's requirement with loam's blessing.
+8. \`loam validate --feature $1 --json\` before handing back.
+
+If the requirement is ambiguous, say so and stop — do not invent behaviour and
+leave the spec disagreeing with the code.
+`,
+};
+//# sourceMappingURL=implement.js.map

package/dist/core/agent/workflows/implement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"implement.js","sourceRoot":"","sources":["../../../../src/core/agent/workflows/implement.ts"],"names":[],"mappings":"AAEA,6FAA6F;AAC7F,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,IAAI,EAAE,gBAAgB;IACtB,WAAW,EACT,sGAAsG;IACxG,YAAY,EAAE,qBAAqB;IACnC,OAAO,EACL,oMAAoM;IACtM,UAAU,EAAE,wCAAwC;IACpD,YAAY,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC;IACpC,KAAK,EAAE;QACL,mFAAmF;QACnF,8FAA8F;QAC9F,0GAA0G;QAC1G,6FAA6F;QAC7F,2FAA2F;QAC3F,iEAAiE;QACjE,iGAAiG;QACjG,qGAAqG;KACtG;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoFP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/** Building one service's slice: the delta brief, generated gherkin, steps, code, verify. */\nexport const LOAM_IMPLEMENT: CommandContent = {\n  name: \"loam-implement\",\n  description:\n    \"Implement a loam feature's slice for one service — generated gherkin first, tests from it, then code\",\n  argumentHint: \"<FEAT-id> [service]\",\n  purpose:\n    \"Build one service's part of a feature, in that service's own repository. The generated Gherkin is the acceptance criterion — it comes before the step definitions, and those come before the code.\",\n  invocation: \"loam instructions loam-implement $1 $2\",\n  placeholders: [\"feature\", \"service\"],\n  spine: [\n    \"`loam status` — where this feature actually is, and what is owed before you start\",\n    \"`loam context` — the briefing: the service's living slice, and every delta in flight over it\",\n    \"`loam delta` — the task: the intent, every requirement verbatim, the endpoints, and the calls in and out\",\n    \"`loam gherkin` in the service's repo — the digest-stamped `.feature` files. Never edit them\",\n    \"write step definitions for the generated scenarios first, outside the generated directory\",\n    \"implement until the suite passes, running it with a JSON report\",\n    \"honour the contract in both directions: expose every inbound operation, call every outbound one\",\n    \"`loam rebase` if building made you change the feature's documents at all, then validate the feature\",\n  ],\n  body: `Implement one service's part of a feature. Every step runs in the SERVICE'S own\nrepository, which needs its own committed ./loam.json — if there is none,\n\\`loam init --docs <path-to-docs-repo> --service $2\\` then \\`loam doctor\\` first.\n\n0. \\`loam status $1 --json\\` — where this feature actually is. Run it before\n   anything else if you joined halfway or lost the session: it says which\n   artifacts are still owed, whether another feature has to archive first, and\n   what the next step is, each \\`next[]\\` entry carrying the literal command. It\n   writes nothing, so it is always safe to re-run.\n1. \\`loam context $2 --feature $1 --json\\` — the briefing to load before touching\n   code: the service's living requirements and arch requirements verbatim, its\n   operations and messages as they stand today, the permissions and capabilities\n   its requirements join to, the fleet edges around it, and this feature's delta\n   over it (\\`--feature $1\\` narrows the in-flight section; drop it to see every\n   feature working over this service). The delta below is WHAT CHANGES; the pack\n   is what it changes INTO — read it first so a MODIFIED requirement lands as an\n   edit rather than a rewrite, and an operation you are about to add is caught\n   when the living contract already defines it. Exit 1 with \\`ok: true\\` means a\n   document behind the pack did not parse; the empty section beside the flag is\n   the parse failure, not \"nothing here\".\n2. \\`loam delta $1 --service $2 --json\\` (drop \\`--service\\` to use the service configured\n   in ./loam.json). That output IS the task:\n   - \\`intent\\` — why this exists\n   - \\`requirements[]\\` — what to build, with \\`scenarios[].lines\\` verbatim\n   - \\`archRequirements[]\\` — the architectural obligations (outbox, retries, alerts),\n     same shape; their scenarios become integration/ops tests, and \\`covers\\` names\n     the model objects each exercises\n   - \\`architecture\\` — whether this service is new, and the calls in and out of it\n   - \\`api\\` — the endpoints this feature adds or retires for this service: path,\n     method, operationId and summary, with removals spelled \\`REMOVE <METHOD> <path>\\`\n   - \\`openapi\\` — whether that contract could be read at all: \\`unreadable\\`, plus an\n     \\`error\\` when the parser gave a message. It rides beside \\`api\\` rather than\n     inside it because \\`api\\` stays the operations array it has always been, and it\n     is what tells an empty \\`api\\` apart from a contract delta that did not parse\n   - \\`services\\` — every service this feature projects onto, so a run without\n     \\`--service\\` tells you which ones to ask for rather than guessing\n   Exit 1 with \\`ok: true\\` means one of the two authored documents behind this brief\n   did not parse: \\`architecture.errors\\` non-empty (delta.likec4), or\n   \\`openapi.unreadable\\` true (the feature's openapi.yaml for this service). The empty\n   slice is the parse failure itself, not \"nothing changes there\". Stop and fix that\n   document before building anything — for the delta, \\`loam validate $1 --json\\` names\n   the error; the contract delta is not graded by validate, so read the parser message\n   the payload carries.\n3. In the service's repo, \\`loam gherkin $1 --json\\` — one \\`.feature\\` file per changed\n   requirement lands under \\`<gherkinDir>/loam/\\` (default \\`features/loam/\\`), scenarios\n   digest-stamped, arch requirements tagged \\`@architecture\\`. Those files ARE the\n   acceptance criteria. Never edit them: regeneration rewrites the directory, and\n   \\`loam validate\\` reports the suite stale by digest, not by your intentions.\n4. Write step definitions for the generated scenarios FIRST — outside \\`loam/\\`.\n   Do not paraphrase a scenario into something easier to pass; it is the acceptance\n   criterion someone else reviews against.\n   Run \\`loam steps --service $2 --json\\` before you write any: it collapses every\n   written step onto the phrase a definition actually matches, so you see the size\n   of the registry you owe and which phrases already exist. Write ONE definition per\n   phrase row. If \\`nearDuplicates\\` is non-empty, two rows differ by an article or a\n   trailing \\`because …\\` clause and one definition was meant — fix the SPEC's wording\n   and regenerate, rather than writing the second definition.\n   A step's argument arrives as an argument: a \\`\"\"\"\\` docstring is the payload, an\n   indented table is a DataTable. Assert against them; do not re-parse the step text.\n5. Implement until the suite passes — run it with a JSON report\n   (\\`cucumber-js --format json:report.json\\`):\n   \\`loam verify $1 --service $2 --results report.json\\` consumes that report as the\n   done-check's answer sheet. Record from THIS repo, with \\`--service\\` — the\n   \\`--service\\`-less \\`--record\\` form writes the whole record from one place and is\n   refused (\\`record-federated\\`) once another service has attested.\n6. Honour the contract: every operation in \\`architecture.inbound\\` must exist under\n   exactly that operationId, and every one in \\`architecture.outbound\\` must be called.\n7. If building made you change the feature's documents at all — a requirement's\n   wording, an operation in its openapi.yaml — **\\`loam rebase $1\\`** before you\n   validate. Every edit you make in the docs repo while other features are in\n   flight is written against a living document that may have moved since the\n   feature directory was created, and the pins are the only thing that lets the\n   merge tell an EDIT from a QUOTE — for operations, path-level keys and\n   components alike. \\`delta.baseline-missing\\` and\n   \\`openapi.baseline-missing\\` are the warnings that say you skipped it — archive\n   refuses on them until you rebase (or a human \\`--approve\\`s the unpinned merge);\n   \\`delta.baseline-stale\\` / \\`openapi.baseline-stale\\` are archive refusing because\n   somebody landed a change underneath you — re-read theirs, fold in what you\n   still mean, then rebase again. Re-pinning without re-reading is how you\n   overwrite someone else's requirement with loam's blessing.\n8. \\`loam validate --feature $1 --json\\` before handing back.\n\nIf the requirement is ambiguous, say so and stop — do not invent behaviour and\nleave the spec disagreeing with the code.\n`,\n};\n"]}

package/dist/core/agent/workflows/reference/authoring.js

@@ -0,0 +1,209 @@
+export const LOAM_AUTHORING = {
+    name: "loam-authoring",
+    description: "Reference: the grammars you author against — arch.spec.md, the generated Gherkin suite, frontmatter",
+    // No arguments: one document, printed whole. See ./spine.ts for why the hint
+    // is empty rather than a spelled-out "<none>".
+    argumentHint: "",
+    purpose: "What each document you author by hand must contain: the architecture requirements axis and its `Covers:` line, how scenarios become an executable suite, and the frontmatter fields `loam vouch` stamps.",
+    invocation: "loam instructions loam-authoring",
+    placeholders: [],
+    spine: [
+        "The architecture spec axis",
+        "The generated Gherkin suite",
+        "Frontmatter — who vouched for this, and from what",
+    ],
+    body: `The grammars you author against: the architecture spec axis, the generated Gherkin suite, and frontmatter.
+
+## The architecture spec axis
+
+The business spec will never mention the transactional outbox — that is
+architecture. Retries, idempotency, metrics, alerts: real obligations no business
+scenario states, and exactly where generated code cuts corners unless the
+obligations are derived mechanically. They live in \`arch.spec.md\` — living and
+delta, same grammar, same delta algebra, merged by \`loam archive\` through the
+same code path (the two files are separate requirement namespaces).
+
+Where a business requirement carries \`Operations:\`, an arch requirement carries
+\`Covers:\` — the model objects its scenarios exercise, comma-separated:
+
+\`\`\`
+Covers: paymentService.db, paymentService -> kafka, alert:payment_5xx, sli:availability
+\`\`\`
+
+a C4 element (id, or the service a bound element stands for), an edge
+(\`source -> target\`), or a health signal the service's health.yaml declares.
+Every entry must resolve — \`covers.unknown\` (warn) is the typo guard, because a
+mistyped entry silently costs the coverage it was written for.
+
+Coverage is then derived, never trusted, as two warnings: a feature's NEW tagged
+elements and edges want a covering requirement in its arch.spec.md deltas
+(\`c4.uncovered\`), and every alert/SLI health.yaml declares wants one in the
+living arch spec (\`health.uncovered\`). None of this gates \`loam archive\`;
+\`--strict\` is the CI escalation. An absent arch.spec.md is not a finding —
+partial adoption is supported — but write one for any service with real
+architecture, or its obligations ship unchecked.
+
+**Effective configuration and dependency semantics live here too, by
+convention.** Facts about the service that no artifact structurally holds —
+the value a deploy chart actually sets, the retry budget a client library
+hardcodes ("retries: -1 is unbounded"), the delivery or idempotency guarantee
+a driver decides — are ARCH REQUIREMENTS: prose with a \`Covers:\` line naming
+the element or edge whose behaviour the fact decides. loam will never verify
+the values; naming the home is the point. A service whose timeout comes from
+an env var in a chart in another repository is otherwise described by no file
+in this repo, and two adoptions will file the same fact two different ways.
+
+**Test levels, mapped once.** A business scenario is an acceptance test. An arch
+scenario is an integration/ops test — the outbox relay under a dead broker, the
+retry that stays idempotent, the alert rule that actually fires. \`api.exposes\`
+is a contract test. Unit tests sit below spec granularity and are your TDD
+concern, not the specs'.
+
+## The generated Gherkin suite
+
+Scenarios are the acceptance criteria, and \`loam gherkin\` makes them
+executable: real \`.feature\` files, written into the SERVICE'S repo — the one
+loam command that writes there, because tests live with the code they gate.
+Output lands in \`<gherkinDir>/loam/\` (\`gherkinDir\` is an optional loam.json
+fact, default \`features\`), and that \`loam/\` subdirectory is loam's own
+derived space — and a committed one: an emission lands through the same lock
+and journal the docs repo's writers use, as \`loam/.loam-lock\` and
+\`loam/.loam-commit\` dotfiles that exist only while a run is in flight (or
+after a kill, where the journal is what lets the next run finish the job).
+Regeneration rewrites its scope and deletes its orphans, so
+never hand-edit inside it — step definitions and hand-written features belong
+outside it, and loam never touches a byte outside \`loam/\`.
+
+- \`loam gherkin FEAT-101\` — the feature's ADDED/MODIFIED requirements for this
+  service, both spec axes. Files carry \`@FEAT-101\`; arch-axis files add
+  \`@architecture\` and are named \`arch--<slug>.feature\` — their scenarios are
+  integration/ops tests, not acceptance tests.
+- \`loam gherkin --service <id>\` (no feature) — the full living suite from
+  spec.md + arch.spec.md: the regression skeleton a legacy service gets at
+  adoption.
+
+One file per requirement (\`Feature:\` is the requirement name). Bullet lines
+opening with Given/When/Then/And/But — the \`- **WHEN** ...\` convention
+included — become steps; every other body line is kept as scenario
+description. A valid Markdown table AT THE MARGIN becomes the \`Examples:\` of
+a \`Scenario Outline\`; a malformed table stays in the description and is
+reported, because it will run once rather than once per row.
+
+A step takes an ARGUMENT by carrying it INDENTED underneath: an indented table
+becomes that step's data table (the rows an outbox or a DB table must hold after
+the pass), a fenced block becomes its docstring, indentation intact (the request
+payload). Indented under a step means this step's rows; at the margin means the
+scenario's cases. A block no step precedes stays description and is reported as
+\`strandedBlocks\` — the document reads, and the TEST lost its argument. Each scenario is
+tagged \`@loam-digest-<16hex>\`: the same body
+hash \`loam verify\` folds into its claim ids, riding into cucumber's JSON
+report as a tag, so the suite, the claim and the report cannot quietly
+disagree about what a scenario says. \`loam validate
+--service <id>\`, run in the service repo, grades the suite by those digests
+(\`gherkin.missing\` / \`gherkin.stale\` / \`gherkin.orphaned\`, all warn) — the
+fix is always regeneration, never editing a generated file.
+
+The flow, closed end to end: \`loam gherkin FEAT-101\` → \`loam steps --service
+<id>\` (the phrase inventory: how many step definitions this suite needs, one
+per phrase row, and which phrases differ only by an article or a trailing
+clause) → write step definitions (outside \`loam/\`) → run the suite with a JSON report
+(\`cucumber-js --format json:report.json\`) → implement until green →
+\`loam verify FEAT-101 --service <id> --results report.json [--contract-results contract.json] [--record rest.json]\`,
+run in that same service repo. The digest
+tags ride through the runner into the report, so the \`scenario.tested\` claims
+are answered mechanically from the passing report rather than anybody's word.
+This proves which digest-matched report bytes loam accepted; it does not prove
+the report was produced by executing the attested commit. See
+\`loam instructions loam-done-check\` for what \`--record\` still covers.
+
+## Frontmatter — who vouched for this, and from what
+
+Every markdown artifact opens with a YAML block:
+
+\`\`\`yaml
+---
+service: payment-service     # or  feature: FEAT-101
+status: verified             # services: draft -> verified
+                             # features: proposed -> in_progress -> built -> done
+owner: payments-team
+last_verified: 2026-07-31    # written by \`loam vouch\` — do not hand-edit
+sources:                     # files/directories in the SERVICE'S repo this was written from — no globs
+  - src/main/java/com/shop/payment/
+sources_digest: 6f1c0a…      # written by \`loam vouch\` — do not hand-edit
+content_digest: 9b2f41…      # written by \`loam vouch\` — do not hand-edit
+sources_files: |             # written by \`loam vouch\` — do not hand-edit
+  9b2f41…  src/main/java/com/shop/payment/Api.java
+vouch_scope: sampled 2/9 seed=1a2b3c4d5e6f7089   # only when the vouch read a SAMPLE
+---
+\`\`\`
+
+\`sources\` matters more than it looks. Everything else loam checks is internal
+consistency — and a corpus can agree with itself perfectly while describing nothing
+that exists. \`sources\` is the one thing tying a document to code: \`loam validate\`,
+run inside that service's repository, checks every listed path is still there.
+Entries are literal files and directories only — a directory covers everything
+beneath it. Glob patterns are refused loudly (\`loam vouch\` will not stamp them,
+\`loam validate\` errors on them): a pattern dialect nobody can be sure of digests
+a different file set than intended, corrupting the staleness signal silently.
+
+\`sources_digest\` is what makes that tie say something over time: a hash of the
+CONTENT of those files, taken when a human last vouched for the document. Every
+later \`loam validate\` re-computes it, so it can tell a document nobody has checked
+(\`sources.unvouched\`) from one that still matches the code (\`sources.current\`) from
+one the code has moved out from under (\`sources.stale\`). On \`sources.stale\` or
+\`content.stale\`, \`loam vouch --pack --service <id>\` (read-only, stamps nothing)
+prints exactly what to re-read before the human re-vouches — the body's diff since
+the last vouch, the source files that moved, and the sections already covered.
+
+\`content_digest\` is the same promise about the document itself: a hash of the
+body below the frontmatter, stamped by the same vouch. It closes the other half of
+the forgery — editing a spec after it was vouched used to leave \`status: verified\`
+standing over words nobody read. \`loam validate\` recomputes it wherever it can
+read the doc (no service repo needed, so it fires from the docs repo too) and
+reports \`content.stale\` (warn): only a person can say whether verified still
+holds of the new words.
+
+\`vouch_scope\` appears only when the person vouched after reading a SAMPLE of the
+document — \`loam vouch --sample <n>\`, whose whole purpose is that a partial read
+is recorded as a partial read. Its value is one flat string,
+\`sampled <k>/<n> seed=<16 hex>\`: k sections read of n, and the seed those k were
+chosen with. The seed is \`sha256(<service> NUL <content_digest> NUL <sources_digest>)\`
+truncated to 16 hex characters, and the sections are ranked by
+\`sha256(<seed> NUL <index> NUL <heading>)\` with the lowest k taken, over every H2
+and H3 heading of the body outside code fences — so anybody holding the document
+can recompute exactly which sections that person was shown, and an agent cannot
+steer the pick without rewriting the document (which changes the seed and voids the
+stamp). \`status\` stays \`verified\` and the maturity rung stays \`vouched\`: the scope
+qualifies that claim, it is not a fourth status. \`loam validate\` reports
+\`sources.sampled-vouch\` (warn) while it is there, \`loam list\` shows
+\`vouched (sampled)\`, and a later FULL \`loam vouch\` deletes the field. Never write
+or delete it by hand: removing it turns a partial read into a full one on every
+surface at once, which is the one forgery this field exists to make impossible.
+
+Write \`sources\` for anything you author from reading code, and leave \`status: draft\`
+until a human has read it. Promoting draft to verified is their call, not yours, and
+it has its own command — \`loam vouch --service <id>\`, run inside that service's repo,
+which stamps the status, the date, the identity (\`vouched_by\`, from git), both digests
+and the per-file index
+(\`sources_files\`, which is what lets a later \`sources.stale\` name the paths that
+moved) together — into the living spec.md
+and, when the service has one, arch.spec.md, in one all-or-nothing run: a file whose
+sources cannot be verified refuses the whole vouch. Never write those six fields by
+hand: a status with no digest behind it is a claim with nothing behind it. If the
+document changed under vouch between the read and the write, it refuses with
+\`vouch-raced\` and stamps nothing — re-read and re-run.
+
+**\`loam vouch\` is not yours to run**, and it is built so that it cannot be. It is
+the one command whose output is a claim about a HUMAN act — everything else loam
+checks is internal consistency, which fluent prose satisfies on its own — so it
+refuses \`vouch-unattended\` when stdin is not a terminal (and in \`--json\` mode,
+where a question cannot be asked), answers \`vouch-declined\` when the person says
+no, and refuses \`vouch-unattributable\` when git can name nobody, because a stamp
+with no \`vouched_by\` behind it records only that the word was written. \`--yes\`
+exists for a person's own scripted run; typing it on someone's behalf is
+writing their name. The generated command and skill files pre-approve loam's
+read-only and authoring verbs one by one and deliberately not this one: when
+the work is done, hand back and say a vouch is owed.
+`,
+};
+//# sourceMappingURL=authoring.js.map

package/dist/core/agent/workflows/reference/authoring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.js","sourceRoot":"","sources":["../../../../../src/core/agent/workflows/reference/authoring.ts"],"names":[],"mappings":"AAgBA,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,IAAI,EAAE,gBAAgB;IACtB,WAAW,EACT,qGAAqG;IACvG,6EAA6E;IAC7E,+CAA+C;IAC/C,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,0MAA0M;IAC5M,UAAU,EAAE,kCAAkC;IAC9C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE;QACL,4BAA4B;QAC5B,6BAA6B;QAC7B,mDAAmD;KACpD;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgMP;CACA,CAAC","sourcesContent":["/**\n * The `loam-authoring` reference page: the grammars of the documents you write.\n *\n * The architecture spec axis (`arch.spec.md` and its `Covers:` line), the\n * generated Gherkin suite, and the frontmatter/vouch chain that ties a\n * document to the code it was written from.\n *\n * All three are consulted at a moment you can name — while authoring one file\n * — and none of them is needed to form the question. That is the split this\n * page exists to make; ./reference.ts records why it had to be made at all.\n *\n * The text is the three AGENTS.md sections verbatim, in their original order,\n * so a cross-reference elsewhere in the corpus still names the same headings.\n */\nimport type { CommandContent } from \"../../contract.js\";\n\nexport const LOAM_AUTHORING: CommandContent = {\n  name: \"loam-authoring\",\n  description:\n    \"Reference: the grammars you author against — arch.spec.md, the generated Gherkin suite, frontmatter\",\n  // No arguments: one document, printed whole. See ./spine.ts for why the hint\n  // is empty rather than a spelled-out \"<none>\".\n  argumentHint: \"\",\n  purpose:\n    \"What each document you author by hand must contain: the architecture requirements axis and its `Covers:` line, how scenarios become an executable suite, and the frontmatter fields `loam vouch` stamps.\",\n  invocation: \"loam instructions loam-authoring\",\n  placeholders: [],\n  spine: [\n    \"The architecture spec axis\",\n    \"The generated Gherkin suite\",\n    \"Frontmatter — who vouched for this, and from what\",\n  ],\n  body: `The grammars you author against: the architecture spec axis, the generated Gherkin suite, and frontmatter.\n\n## The architecture spec axis\n\nThe business spec will never mention the transactional outbox — that is\narchitecture. Retries, idempotency, metrics, alerts: real obligations no business\nscenario states, and exactly where generated code cuts corners unless the\nobligations are derived mechanically. They live in \\`arch.spec.md\\` — living and\ndelta, same grammar, same delta algebra, merged by \\`loam archive\\` through the\nsame code path (the two files are separate requirement namespaces).\n\nWhere a business requirement carries \\`Operations:\\`, an arch requirement carries\n\\`Covers:\\` — the model objects its scenarios exercise, comma-separated:\n\n\\`\\`\\`\nCovers: paymentService.db, paymentService -> kafka, alert:payment_5xx, sli:availability\n\\`\\`\\`\n\na C4 element (id, or the service a bound element stands for), an edge\n(\\`source -> target\\`), or a health signal the service's health.yaml declares.\nEvery entry must resolve — \\`covers.unknown\\` (warn) is the typo guard, because a\nmistyped entry silently costs the coverage it was written for.\n\nCoverage is then derived, never trusted, as two warnings: a feature's NEW tagged\nelements and edges want a covering requirement in its arch.spec.md deltas\n(\\`c4.uncovered\\`), and every alert/SLI health.yaml declares wants one in the\nliving arch spec (\\`health.uncovered\\`). None of this gates \\`loam archive\\`;\n\\`--strict\\` is the CI escalation. An absent arch.spec.md is not a finding —\npartial adoption is supported — but write one for any service with real\narchitecture, or its obligations ship unchecked.\n\n**Effective configuration and dependency semantics live here too, by\nconvention.** Facts about the service that no artifact structurally holds —\nthe value a deploy chart actually sets, the retry budget a client library\nhardcodes (\"retries: -1 is unbounded\"), the delivery or idempotency guarantee\na driver decides — are ARCH REQUIREMENTS: prose with a \\`Covers:\\` line naming\nthe element or edge whose behaviour the fact decides. loam will never verify\nthe values; naming the home is the point. A service whose timeout comes from\nan env var in a chart in another repository is otherwise described by no file\nin this repo, and two adoptions will file the same fact two different ways.\n\n**Test levels, mapped once.** A business scenario is an acceptance test. An arch\nscenario is an integration/ops test — the outbox relay under a dead broker, the\nretry that stays idempotent, the alert rule that actually fires. \\`api.exposes\\`\nis a contract test. Unit tests sit below spec granularity and are your TDD\nconcern, not the specs'.\n\n## The generated Gherkin suite\n\nScenarios are the acceptance criteria, and \\`loam gherkin\\` makes them\nexecutable: real \\`.feature\\` files, written into the SERVICE'S repo — the one\nloam command that writes there, because tests live with the code they gate.\nOutput lands in \\`<gherkinDir>/loam/\\` (\\`gherkinDir\\` is an optional loam.json\nfact, default \\`features\\`), and that \\`loam/\\` subdirectory is loam's own\nderived space — and a committed one: an emission lands through the same lock\nand journal the docs repo's writers use, as \\`loam/.loam-lock\\` and\n\\`loam/.loam-commit\\` dotfiles that exist only while a run is in flight (or\nafter a kill, where the journal is what lets the next run finish the job).\nRegeneration rewrites its scope and deletes its orphans, so\nnever hand-edit inside it — step definitions and hand-written features belong\noutside it, and loam never touches a byte outside \\`loam/\\`.\n\n- \\`loam gherkin FEAT-101\\` — the feature's ADDED/MODIFIED requirements for this\n  service, both spec axes. Files carry \\`@FEAT-101\\`; arch-axis files add\n  \\`@architecture\\` and are named \\`arch--<slug>.feature\\` — their scenarios are\n  integration/ops tests, not acceptance tests.\n- \\`loam gherkin --service <id>\\` (no feature) — the full living suite from\n  spec.md + arch.spec.md: the regression skeleton a legacy service gets at\n  adoption.\n\nOne file per requirement (\\`Feature:\\` is the requirement name). Bullet lines\nopening with Given/When/Then/And/But — the \\`- **WHEN** ...\\` convention\nincluded — become steps; every other body line is kept as scenario\ndescription. A valid Markdown table AT THE MARGIN becomes the \\`Examples:\\` of\na \\`Scenario Outline\\`; a malformed table stays in the description and is\nreported, because it will run once rather than once per row.\n\nA step takes an ARGUMENT by carrying it INDENTED underneath: an indented table\nbecomes that step's data table (the rows an outbox or a DB table must hold after\nthe pass), a fenced block becomes its docstring, indentation intact (the request\npayload). Indented under a step means this step's rows; at the margin means the\nscenario's cases. A block no step precedes stays description and is reported as\n\\`strandedBlocks\\` — the document reads, and the TEST lost its argument. Each scenario is\ntagged \\`@loam-digest-<16hex>\\`: the same body\nhash \\`loam verify\\` folds into its claim ids, riding into cucumber's JSON\nreport as a tag, so the suite, the claim and the report cannot quietly\ndisagree about what a scenario says. \\`loam validate\n--service <id>\\`, run in the service repo, grades the suite by those digests\n(\\`gherkin.missing\\` / \\`gherkin.stale\\` / \\`gherkin.orphaned\\`, all warn) — the\nfix is always regeneration, never editing a generated file.\n\nThe flow, closed end to end: \\`loam gherkin FEAT-101\\` → \\`loam steps --service\n<id>\\` (the phrase inventory: how many step definitions this suite needs, one\nper phrase row, and which phrases differ only by an article or a trailing\nclause) → write step definitions (outside \\`loam/\\`) → run the suite with a JSON report\n(\\`cucumber-js --format json:report.json\\`) → implement until green →\n\\`loam verify FEAT-101 --service <id> --results report.json [--contract-results contract.json] [--record rest.json]\\`,\nrun in that same service repo. The digest\ntags ride through the runner into the report, so the \\`scenario.tested\\` claims\nare answered mechanically from the passing report rather than anybody's word.\nThis proves which digest-matched report bytes loam accepted; it does not prove\nthe report was produced by executing the attested commit. See\n\\`loam instructions loam-done-check\\` for what \\`--record\\` still covers.\n\n## Frontmatter — who vouched for this, and from what\n\nEvery markdown artifact opens with a YAML block:\n\n\\`\\`\\`yaml\n---\nservice: payment-service     # or  feature: FEAT-101\nstatus: verified             # services: draft -> verified\n                             # features: proposed -> in_progress -> built -> done\nowner: payments-team\nlast_verified: 2026-07-31    # written by \\`loam vouch\\` — do not hand-edit\nsources:                     # files/directories in the SERVICE'S repo this was written from — no globs\n  - src/main/java/com/shop/payment/\nsources_digest: 6f1c0a…      # written by \\`loam vouch\\` — do not hand-edit\ncontent_digest: 9b2f41…      # written by \\`loam vouch\\` — do not hand-edit\nsources_files: |             # written by \\`loam vouch\\` — do not hand-edit\n  9b2f41…  src/main/java/com/shop/payment/Api.java\nvouch_scope: sampled 2/9 seed=1a2b3c4d5e6f7089   # only when the vouch read a SAMPLE\n---\n\\`\\`\\`\n\n\\`sources\\` matters more than it looks. Everything else loam checks is internal\nconsistency — and a corpus can agree with itself perfectly while describing nothing\nthat exists. \\`sources\\` is the one thing tying a document to code: \\`loam validate\\`,\nrun inside that service's repository, checks every listed path is still there.\nEntries are literal files and directories only — a directory covers everything\nbeneath it. Glob patterns are refused loudly (\\`loam vouch\\` will not stamp them,\n\\`loam validate\\` errors on them): a pattern dialect nobody can be sure of digests\na different file set than intended, corrupting the staleness signal silently.\n\n\\`sources_digest\\` is what makes that tie say something over time: a hash of the\nCONTENT of those files, taken when a human last vouched for the document. Every\nlater \\`loam validate\\` re-computes it, so it can tell a document nobody has checked\n(\\`sources.unvouched\\`) from one that still matches the code (\\`sources.current\\`) from\none the code has moved out from under (\\`sources.stale\\`). On \\`sources.stale\\` or\n\\`content.stale\\`, \\`loam vouch --pack --service <id>\\` (read-only, stamps nothing)\nprints exactly what to re-read before the human re-vouches — the body's diff since\nthe last vouch, the source files that moved, and the sections already covered.\n\n\\`content_digest\\` is the same promise about the document itself: a hash of the\nbody below the frontmatter, stamped by the same vouch. It closes the other half of\nthe forgery — editing a spec after it was vouched used to leave \\`status: verified\\`\nstanding over words nobody read. \\`loam validate\\` recomputes it wherever it can\nread the doc (no service repo needed, so it fires from the docs repo too) and\nreports \\`content.stale\\` (warn): only a person can say whether verified still\nholds of the new words.\n\n\\`vouch_scope\\` appears only when the person vouched after reading a SAMPLE of the\ndocument — \\`loam vouch --sample <n>\\`, whose whole purpose is that a partial read\nis recorded as a partial read. Its value is one flat string,\n\\`sampled <k>/<n> seed=<16 hex>\\`: k sections read of n, and the seed those k were\nchosen with. The seed is \\`sha256(<service> NUL <content_digest> NUL <sources_digest>)\\`\ntruncated to 16 hex characters, and the sections are ranked by\n\\`sha256(<seed> NUL <index> NUL <heading>)\\` with the lowest k taken, over every H2\nand H3 heading of the body outside code fences — so anybody holding the document\ncan recompute exactly which sections that person was shown, and an agent cannot\nsteer the pick without rewriting the document (which changes the seed and voids the\nstamp). \\`status\\` stays \\`verified\\` and the maturity rung stays \\`vouched\\`: the scope\nqualifies that claim, it is not a fourth status. \\`loam validate\\` reports\n\\`sources.sampled-vouch\\` (warn) while it is there, \\`loam list\\` shows\n\\`vouched (sampled)\\`, and a later FULL \\`loam vouch\\` deletes the field. Never write\nor delete it by hand: removing it turns a partial read into a full one on every\nsurface at once, which is the one forgery this field exists to make impossible.\n\nWrite \\`sources\\` for anything you author from reading code, and leave \\`status: draft\\`\nuntil a human has read it. Promoting draft to verified is their call, not yours, and\nit has its own command — \\`loam vouch --service <id>\\`, run inside that service's repo,\nwhich stamps the status, the date, the identity (\\`vouched_by\\`, from git), both digests\nand the per-file index\n(\\`sources_files\\`, which is what lets a later \\`sources.stale\\` name the paths that\nmoved) together — into the living spec.md\nand, when the service has one, arch.spec.md, in one all-or-nothing run: a file whose\nsources cannot be verified refuses the whole vouch. Never write those six fields by\nhand: a status with no digest behind it is a claim with nothing behind it. If the\ndocument changed under vouch between the read and the write, it refuses with\n\\`vouch-raced\\` and stamps nothing — re-read and re-run.\n\n**\\`loam vouch\\` is not yours to run**, and it is built so that it cannot be. It is\nthe one command whose output is a claim about a HUMAN act — everything else loam\nchecks is internal consistency, which fluent prose satisfies on its own — so it\nrefuses \\`vouch-unattended\\` when stdin is not a terminal (and in \\`--json\\` mode,\nwhere a question cannot be asked), answers \\`vouch-declined\\` when the person says\nno, and refuses \\`vouch-unattributable\\` when git can name nobody, because a stamp\nwith no \\`vouched_by\\` behind it records only that the word was written. \\`--yes\\`\nexists for a person's own scripted run; typing it on someone's behalf is\nwriting their name. The generated command and skill files pre-approve loam's\nread-only and authoring verbs one by one and deliberately not this one: when\nthe work is done, hand back and say a vouch is owed.\n`,\n};\n"]}

package/dist/core/agent/workflows/reference/codes.js

@@ -0,0 +1,65 @@
+/**
+ * The `loam-codes` reference page: which codes each INVOCATION can raise.
+ *
+ * The largest of the four pages and the one this migration is mostly about. As
+ * a section of AGENTS.md it was 44,433 bytes — 41% of a 109,399-byte file that
+ * Codex truncates at 32,768 and Windsurf at 12,000 characters, both silently.
+ * It is also the half a reader consults at a moment it can NAME (a run reported
+ * something) rather than the half it needs to form a question at all, which is
+ * what decided which side of the split it went. ./reference.ts carries the rest
+ * of that argument.
+ *
+ * This module does one thing: it CONCATENATES, in the order ../../agents-md.ts
+ * used to. Nothing here reformats a part on the way past, and nothing here is
+ * written — every byte comes from ../../agents-md/, which is where the sections
+ * already lived and where they stayed. The parts still carry their own trailing
+ * newlines and are joined with no separator, so the printed page is the old
+ * section byte for byte.
+ *
+ * WHAT IS AND IS NOT DUPLICATED. `## Reading loam's output` still exists in
+ * AGENTS.md (../../agents-md/command-map.ts's READING_OUTPUT), and it is a
+ * different three facts, not a summary of these: that every command speaks
+ * JSON, that the envelope survives a bad invocation, and that codes are the
+ * contract, plus the two places the detail went. The per-invocation inventory
+ * below appears in exactly one place.
+ */
+import { CODE_MAP } from "../../agents-md/command-map.js";
+import { CONTEXT_COMMAND } from "../../agents-md/map/lenses/context.js";
+import { DIFF_COMMAND } from "../../agents-md/map/lenses/diff.js";
+import { GATE_COMMAND } from "../../agents-md/map/lenses/gate.js";
+import { EXPLAIN_COMMAND } from "../../agents-md/map/explain.js";
+import { MCP_COMMAND } from "../../agents-md/map/mcp.js";
+import { SUBSYSTEM_COMMANDS } from "../../agents-md/map/subsystem.js";
+import { USECASE_VIEWS } from "../../agents-md/map/usecases.js";
+import { REFUSALS } from "../../agents-md/refusals.js";
+export const LOAM_CODES = {
+    name: "loam-codes",
+    description: "Reference: which codes each invocation can raise, command by command",
+    // No arguments: one document, printed whole. See ./spine.ts for why the hint
+    // is empty rather than a spelled-out "<none>".
+    argumentHint: "",
+    purpose: "The per-invocation inventory: which findings `validate --service` / `--feature` / `--all`, `status`, `doctor`, `gate`, `context`, `diff`, `explore`, `dependencies`, `rebase`, `seed`, `subsystem` and `mcp` can report, and the refusals the containment surface answers with.",
+    invocation: "loam instructions loam-codes",
+    placeholders: [],
+    // The page carries no `## ` headings — it is one list, and the bullets are
+    // the structure. The spine names the invocations it walks instead, which is
+    // what a reader is actually looking one of up.
+    spine: [
+        "validate --service / --feature / --all",
+        "status, doctor, rebase, dependencies, explore, seed",
+        "context, gate, subsystem, use-case views, diff, explain, mcp",
+        "the containment refusals and the OpenSpec migration surface",
+    ],
+    // CODE_MAP already opens with the page's own "**What this page is.**" and
+    // leads with `status`, the orientation command.
+    body: CODE_MAP +
+        CONTEXT_COMMAND +
+        GATE_COMMAND +
+        SUBSYSTEM_COMMANDS +
+        USECASE_VIEWS +
+        DIFF_COMMAND +
+        EXPLAIN_COMMAND +
+        MCP_COMMAND +
+        REFUSALS,
+};
+//# sourceMappingURL=codes.js.map

package/dist/core/agent/workflows/reference/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../../../../src/core/agent/workflows/reference/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAGvD,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,YAAY;IAClB,WAAW,EAAE,sEAAsE;IACnF,6EAA6E;IAC7E,+CAA+C;IAC/C,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,iRAAiR;IACnR,UAAU,EAAE,8BAA8B;IAC1C,YAAY,EAAE,EAAE;IAChB,2EAA2E;IAC3E,4EAA4E;IAC5E,+CAA+C;IAC/C,KAAK,EAAE;QACL,wCAAwC;QACxC,qDAAqD;QACrD,8DAA8D;QAC9D,6DAA6D;KAC9D;IACD,0EAA0E;IAC1E,gDAAgD;IAChD,IAAI,EACF,QAAQ;QACR,eAAe;QACf,YAAY;QACZ,kBAAkB;QAClB,aAAa;QACb,YAAY;QACZ,eAAe;QACf,WAAW;QACX,QAAQ;CACX,CAAC","sourcesContent":["/**\n * The `loam-codes` reference page: which codes each INVOCATION can raise.\n *\n * The largest of the four pages and the one this migration is mostly about. As\n * a section of AGENTS.md it was 44,433 bytes — 41% of a 109,399-byte file that\n * Codex truncates at 32,768 and Windsurf at 12,000 characters, both silently.\n * It is also the half a reader consults at a moment it can NAME (a run reported\n * something) rather than the half it needs to form a question at all, which is\n * what decided which side of the split it went. ./reference.ts carries the rest\n * of that argument.\n *\n * This module does one thing: it CONCATENATES, in the order ../../agents-md.ts\n * used to. Nothing here reformats a part on the way past, and nothing here is\n * written — every byte comes from ../../agents-md/, which is where the sections\n * already lived and where they stayed. The parts still carry their own trailing\n * newlines and are joined with no separator, so the printed page is the old\n * section byte for byte.\n *\n * WHAT IS AND IS NOT DUPLICATED. `## Reading loam's output` still exists in\n * AGENTS.md (../../agents-md/command-map.ts's READING_OUTPUT), and it is a\n * different three facts, not a summary of these: that every command speaks\n * JSON, that the envelope survives a bad invocation, and that codes are the\n * contract, plus the two places the detail went. The per-invocation inventory\n * below appears in exactly one place.\n */\nimport { CODE_MAP } from \"../../agents-md/command-map.js\";\nimport { CONTEXT_COMMAND } from \"../../agents-md/map/lenses/context.js\";\nimport { DIFF_COMMAND } from \"../../agents-md/map/lenses/diff.js\";\nimport { GATE_COMMAND } from \"../../agents-md/map/lenses/gate.js\";\nimport { EXPLAIN_COMMAND } from \"../../agents-md/map/explain.js\";\nimport { MCP_COMMAND } from \"../../agents-md/map/mcp.js\";\nimport { SUBSYSTEM_COMMANDS } from \"../../agents-md/map/subsystem.js\";\nimport { USECASE_VIEWS } from \"../../agents-md/map/usecases.js\";\nimport { REFUSALS } from \"../../agents-md/refusals.js\";\nimport type { CommandContent } from \"../../contract.js\";\n\nexport const LOAM_CODES: CommandContent = {\n  name: \"loam-codes\",\n  description: \"Reference: which codes each invocation can raise, command by command\",\n  // No arguments: one document, printed whole. See ./spine.ts for why the hint\n  // is empty rather than a spelled-out \"<none>\".\n  argumentHint: \"\",\n  purpose:\n    \"The per-invocation inventory: which findings `validate --service` / `--feature` / `--all`, `status`, `doctor`, `gate`, `context`, `diff`, `explore`, `dependencies`, `rebase`, `seed`, `subsystem` and `mcp` can report, and the refusals the containment surface answers with.\",\n  invocation: \"loam instructions loam-codes\",\n  placeholders: [],\n  // The page carries no `## ` headings — it is one list, and the bullets are\n  // the structure. The spine names the invocations it walks instead, which is\n  // what a reader is actually looking one of up.\n  spine: [\n    \"validate --service / --feature / --all\",\n    \"status, doctor, rebase, dependencies, explore, seed\",\n    \"context, gate, subsystem, use-case views, diff, explain, mcp\",\n    \"the containment refusals and the OpenSpec migration surface\",\n  ],\n  // CODE_MAP already opens with the page's own \"**What this page is.**\" and\n  // leads with `status`, the orientation command.\n  body:\n    CODE_MAP +\n    CONTEXT_COMMAND +\n    GATE_COMMAND +\n    SUBSYSTEM_COMMANDS +\n    USECASE_VIEWS +\n    DIFF_COMMAND +\n    EXPLAIN_COMMAND +\n    MCP_COMMAND +\n    REFUSALS,\n};\n"]}