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

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,8GAA8G;QAC9G,6FAA6F;QAC7F,qIAAqI;QACrI,kFAAkF;QAClF,sGAAsG;QACtG,0GAA0G;QAC1G,4HAA4H;QAC5H,uHAAuH;QACvH,mFAAmF;KACpF;IACD,2EAA2E;IAC3E,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,4EAA4E;IAC5E,sEAAsE;IACtE,4EAA4E;IAC5E,8EAA8E;IAC9E,2EAA2E;IAC3E,6EAA6E;IAC7E,6EAA6E;IAC7E,qEAAqE;IACrE,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyLP;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    \"decide whether this is a feature at all — a change that touches no requirement, operation or edge needs none\",\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    \"analyze before you pin — write what the documents leave open under `## Open questions` in intent.md, for a human to answer\",\n    \"`loam rebase` — pin every MODIFIED requirement and every living operation you edited to the version you wrote against\",\n    \"validate the feature, then read `loam dependencies` before anyone starts building\",\n  ],\n  // Step 0 and step 4b are the two this protocol was missing, and neither is\n  // graded — on purpose. Step 0 exists because the lightest lane loam has (no\n  // feature at all, for a change that moves no requirement, operation or edge)\n  // was true and written down nowhere, so the work that is most of a legacy\n  // fleet's week either walked the whole feature cycle or routed around loam.\n  // Step 4b exists because every check after it is a join between exact\n  // tokens: two services that agree on every operationId and disagree on what\n  // it means (one confirms a split the other answers 422 for) validate, archive\n  // and ship green, and a `Realizes:` whose requirement does not deliver the\n  // promise reads as a clean join. Nothing in the binary can read meaning, and\n  // a check pretending to would be the false green this tool exists to refuse,\n  // so the step asks for questions and leaves the answers to a person.\n  body: `Start a new feature in the loam docs repo (its path is \\`docsDir\\` in ./loam.json).\n\n0. First decide whether this needs a feature at all. A change that touches no\n   requirement, no operation and no fleet edge — a refactor, a dependency bump,\n   a fix that brings the code back to behaviour the living spec already\n   documents — needs NONE: nothing in the docs repo changes, so there is nothing\n   to scaffold, pin or archive. It is a code PR in the service repo, then\n   \\`loam validate --service <id>\\` there (the service repo is the only place\n   \\`sources.stale\\` is visible), then \\`loam vouch --pack --service <id>\\` to\n   prepare the re-read the moved sources owe — the vouch itself is a human's.\n   If the change alters what a requirement promises, it IS a feature, however\n   small: one \\`--touches\\`, a Why, the ADDED/MODIFIED requirement, and\n   \\`loam rebase\\` for a MODIFIED one — the rest of this page still applies.\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     Draw each edge with its relationship kind (\\`-[calls]->\\`, \\`-[publishes]->\\`,\n     \\`-[delivers]->\\`, …), and draw a direction only where the evidence shows\n     one: anything else is \\`-[connects]->\\`. A message runs producer\n     \\`-[publishes]->\\` topic and topic \\`-[delivers]->\\` consumer, never\n     producer \\`->\\` consumer. A producer outside the fleet is an \\`#external\\`\n     element whose edge carries \\`metadata { publishes }\\`. Declare every kind\n     you draw in the delta's own \\`specification\\`, and check that the living\n     map's declares it too. The archive copies the edge and never the\n     declaration, so a kind the map lacks refuses the archive (\\`merge-failed\\`)\n     even though validate and status call the feature ready.\n     \\`loam instructions loam-drawing\\` has the kinds and their styles\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     Write an edge by its endpoints' service names\n     (\\`order-service -> payment-service\\`), which resolve the same before and\n     after the archive\n   - write every document for a reviewer who has never seen the code.\n     \\`intent.md\\` gains a \\`## How to read this feature\\` section, a\n     business-requirement coverage table, and \\`## Open questions\\` as a table\n     (ID, question, blocks, owner, current default). Each spec delta opens\n     with a plain-language \\`## Purpose\\`. A long requirement body becomes a\n     one-line lead plus one bullet per SHALL sentence. Every abbreviation is\n     expanded on first use. \"This delta\" and \"this feature\" stay out of\n     requirement bodies and contract descriptions, because the archive copies\n     those into the living docs. A word the feature brings goes in\n     \\`glossary/<term>.md\\` and a decision in \\`adrs/\\`, both inside the feature,\n     and a cross-service flow in \\`usecases/<name>.likec4\\`, tagged with a\n     \\`#cap-\\` that resolves. \\`loam instructions loam-authoring\\`, \"Writing\n     for a person\", has the shapes\n   - \\`specs/<svc>/openapi.yaml\\` — define every operationId the edges reference.\n     A self-contained document holding ONLY the operations this feature adds,\n     changes or removes — never a copy of the living contract. An operation you\n     leave out stays exactly as the living contract has it, and a local \\`$ref\\`\n     (\\`#/components/schemas/Order\\`) resolves into the living document, so there\n     is nothing to restate. Every operation you quote costs a pin, and once a\n     parallel feature retires it — or moves it, and you quoted the old\n     address — a pinned quote is \\`openapi.baseline-invalid\\` and\n     \\`openapi.op-revived\\` both, an unpinned one \\`openapi.op-revived\\` alone\n     (\\`asyncapi.slot-revived\\` on the event axis) — archive refuses either.\n     Delete the quote; only a feature that MEANS to bring a retired operation\n     back keeps it, and archives past the finding with a human's \\`--approve\\`\n   - \\`specs/<svc>/asyncapi.yaml\\` — the event axis, only when the feature changes\n     what a service puts on or takes off the bus: an AsyncAPI 3.0 document\n     holding only the channel, operation and message slots you add, change or\n     remove (an edited slot is written out whole), new messages under\n     \\`components.messages\\`, and a \\`Publishes:\\`/\\`Consumes:\\` line on each\n     requirement that names them. \\`loam new\\` scaffolds none — an event\n     contract is genuinely optional\n   - for a service (or capability) this feature CREATES, the delta is the\n     living document's first draft, and \\`loam archive\\` carries only what you\n     mark as the document's own: the frontmatter \\`owner\\`, an H1 that neither\n     names $1 nor calls itself a delta (the scaffold's does both — retitle it),\n     and a \\`## Purpose\\` section — put the service's narrative there. Everything\n     else in the delta is read as being about the change and stays with it in\n     \\`features/archive/\\`, linked from the new document\n   - links: write each one so it resolves where you write it, relative to the\n     file. A link into this feature — from its deltas, or from any other\n     document whose links validate grades — is re-pointed by \\`loam archive\\`\n     to wherever the file ends up — a term in \\`glossary/<term>.md\\` at the living glossary,\n     anything else (an ADR in \\`adrs/\\` above all) inside\n     \\`features/archive/\\`, because a feature ADR is never copied into the living\n     tree. A decision meant to outlive this change belongs in\n     \\`architecture/adrs/\\` or the service's own \\`adrs/\\` instead. The same\n     holds inside this feature: its own documents (the intent, its ADRs) move\n     to \\`features/archive/\\` with it, and the archive re-expresses their links\n     for the move — never write them for the archived location yourself\n4b. **Analyze before you pin.** Nothing grades this step, which is why it is here:\n   every check after it is a join between exact tokens, so two services that\n   agree on every operationId and disagree on what it means validate, archive\n   and ship green. Read the feature as its reviewer will, before rebase freezes it:\n   - \\`loam show $1 --json\\` — its \\`review\\` object joins the intent, the C4\n     objects, the API/event slices and the dependencies\n   - \\`loam context <service> --feature $1 --json\\` for every service it touches —\n     the living requirements verbatim, the edges one hop out, and this delta\n   - the \\`neighbours\\` step 2b's \\`loam explore\\` reported\n   Then write what the documents leave open under \\`## Open questions\\` in\n   \\`intent.md\\` (the scaffold already carries the heading), one table row per\n   question — ID, the question, what it blocks (the requirement id or edge it is\n   about), its owner, and the default that gets built if nobody answers:\n   - a SHALL two engineers could build two ways — an unstated unit, bound,\n     ordering, or an \"eventually\" with no window\n   - a value, limit or window two services state differently (a refund window,\n     a rounding rule, a retry budget), and which side refuses when they\n     disagree — a caller that accepts what its provider answers 4xx for is a\n     contradiction no check can see\n   - a \\`Realizes:\\` line whose requirement does not actually deliver the\n     capability promise it names, or a promise this feature changes that no\n     realizing requirement keeps\n   - per call edge in the delta: the timeout, the retry and what makes it safe\n     to repeat, what a partial failure leaves behind, and what compensates it —\n     an edge no requirement answers these for is a question, not a default\n   - each \\`explore\\` neighbour outside \\`--touches\\`: why it is untouched, or that\n     it is a candidate — adding one means a \\`specs/<svc>/\\` delta in this feature,\n     because that directory IS the feature's service list\n   Ask; do not answer for the author. The default column records what the\n   documents imply today, not what you would choose. A human answers by editing the file —\n   replacing a question with the decision, or with a change to the delta.\n   Nothing is graded: an empty section is legal, and so is an answered one.\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:\\`), and every operation and\n   asyncapi channel/operation/message slot the living contract already holds\n   (\\`x-loam-based-on\\`), to the living version you wrote against. What the\n   feature ADDS has no living version and takes no pin, so an add-only contract\n   delta needs no rebase. Any living operation or slot the delta spells is one\n   the merge upserts, so it needs its pin even when you changed one line of it.\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,188 @@
+/**
+ * Building one service's slice: the delta brief, then a unit at a time —
+ * generated gherkin, steps, code, verify.
+ *
+ * Steps 3-5 are a LOOP, not a sequence, and that is why `loam tasks` sits at
+ * the head of them. They used to be three things done in order — generate the
+ * suite, write the definitions, implement — which is only the right order for a
+ * slice whose every requirement already owns a scenario. Where one does not,
+ * the next thing owed is a sentence in the docs repo, and the body had no step
+ * that could say so; where the suite is half written, nothing here answered
+ * which half. `at` answers both: the projection names which of four states the
+ * next unit is in, and each state names exactly one action, so the numbering
+ * below is a table of destinations rather than an itinerary. An editor adding a
+ * step must therefore say which `at` value routes to it, or it is unreachable.
+ */
+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 tasks` — the open units, ordered; `--next` is the single next unit, with the scenario verbatim and the fact that closes it",
+        "`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 --agent-profile service\` 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. \`loam tasks $1 --service $2 --next --json\` — ONE unit of work, and the loop
+   every step below runs inside. Step 2 is the whole brief; this is the next thing
+   to do in it. It writes nothing: the projection is derived from the verify
+   checklist, the delta scans, the feature's verification record and — in this,
+   the bound service repo — the digest stamps in the generated \`.feature\` files.
+   Drop \`--next\` to see every open unit instead of only the head.
+   Each entry of \`units[]\` carries its \`id\` (the same id the verify checklist uses
+   for that claim), \`kind\` (\`service.exists\`, \`api.exposes\`, \`event.declares\`,
+   \`c4.calls\`, \`scenario.tested\` or \`requirement.described\`), \`subject\`, \`claim\`,
+   \`digest\`, \`dependsOn\`, \`source\` — the path, line, requirement and scenario it was
+   derived from, with the scenario's own \`lines\` verbatim — and \`done.check\`.
+
+   \`at\` is the instruction. It says what the unit NEEDS, and each of its four
+   values names exactly one action:
+   - \`describe\` — the requirement owns no scenarios yet. Write the Given/When/Then
+     in the DOCS repo, on the requirement \`source\` names, and nothing else. loam
+     does not author, and no amount of code closes a unit sitting here.
+   - \`generate\` — no stamped \`.feature\` carries this scenario's digest. The only
+     action is \`loam gherkin $1\` in this repo (step 4). Do not write code.
+   - \`implement\` — the stamped scenario exists and no recorded run has confirmed
+     it. Write step definitions outside \`loam/\`, implement until the suite passes,
+     then \`loam verify $1 --service $2 --results report.json\` (step 5).
+   - \`attested\` — the claim was closed on somebody's word rather than on a run.
+     Run the suite and re-record it so it stops resting on an assertion. An
+     agent-attested scenario stays visible at \`attested\` forever, deliberately: it
+     is the one state that cannot be made to go away by ignoring it.
+
+   \`done.check\` is the FACT that closes the unit, and the RUNNER decides whether
+   that fact holds — never your own reading of the code you just wrote. Done means
+   the unit no longer appears, and it stops appearing only once its claim is
+   recorded confirmed in a verification record that is not stale. So re-run
+   \`loam tasks $1 --service $2 --json\` after every recording instead of working
+   down a list you copied out: \`frontier\` (the first ten open unit ids, in order)
+   and \`counts\` (\`open\`, \`done\`, \`attested\`) are recomputed from the documents on
+   every run, which is what makes taking the head of it always safe.
+   \`checklist\` is the digest of the question set the whole projection derives from.
+   If it differs from the one you started against, the question set moved under
+   you — re-read the feature before continuing, because what you closed earlier may
+   not be what is being asked now.
+   \`record\` says whether the answers were found at all (\`absent\`, \`recorded\`,
+   \`stale\`, \`unreadable\`) and \`stamps\` whether this repo's generated suite could be
+   read (\`read\`, \`unknown\`); an \`unknown\` makes every \`generate\` verdict a guess,
+   so fix the binding before acting on one. \`contracts\` restates step 6 as data
+   (\`expose[]\` and \`call[]\`), \`size\` the shape of the packet, \`review[]\` what a
+   reviewer of it will read, and \`waitingOn\` — whenever the packet is narrowed to one
+   service: by \`--service\`, or without it to this repo's own service when the feature
+   touches it — what another service still owes before your frontier can move.
+   Exit 1 with \`ok: true\` is step 2's rule again: delta.likec4 or one of the
+   contract axes did not parse, so the projection is SHORT by everything that
+   document would have contributed. Fix the document; do not work the units that
+   happened to survive it.
+4. \`at: "generate"\` — 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. Generating is the WHOLE action for a unit at
+   \`generate\`: go back to step 3, where the same unit now reads \`implement\`.
+5. \`at: "implement"\` — step definitions FIRST, outside \`loam/\`, then the code.
+   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.
+   Then implement until the suite passes — run it with a JSON report
+   (\`cucumber-js --format json:report.json\`; cucumber-jvm, behave, Reqnroll,
+   pytest-bdd \`--cucumberjson\` and godog write the same cucumber JSON):
+   \`loam verify $1 --service $2 --results report.json\` consumes that report as the
+   done-check's answer sheet. A runner with no cucumber formatter answers through
+   loam's runner-neutral shape instead, keyed by each scenario's \`@loam-digest\`
+   tag — adapting the runner's report into it is a build step you own:
+   \`{"loamScenarioReport": 1, "results": [{"digest": "<16 hex>", "status": "passed"}]}\`.
+   A cucumber run must have run every step of the stamped scenario: a report
+   entry whose step count differs is not that scenario's run and stays
+   unconfirmed. 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. Recording is what
+   closes the unit, so step 3 is the command AFTER it, not the end of the run.
+6. Honour the contract: every operation in \`architecture.inbound\` must exist under
+   exactly that operationId, and every one in \`architecture.outbound\` must be called.
+   The code you just wrote is evidence about the delta's edges. If an edge the
+   feature draws as \`connects\` is in fact a publish, a delivery, a read or a write,
+   redraw it in delta.likec4 with that kind (\`loam instructions loam-drawing\`) —
+   and step 7 applies, because that is a change to the feature's documents.
+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. Write the question under
+\`## Open questions\` in the feature's \`intent.md\`, where loam-feature's analyze
+step put the ones it found, so a person answers it once for every service.
+`,
+};
+//# 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;;;;;;;;;;;;;;GAcG;AACH,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,kIAAkI;QAClI,6FAA6F;QAC7F,2FAA2F;QAC3F,iEAAiE;QACjE,iGAAiG;QACjG,qGAAqG;KACtG;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwJP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * Building one service's slice: the delta brief, then a unit at a time —\n * generated gherkin, steps, code, verify.\n *\n * Steps 3-5 are a LOOP, not a sequence, and that is why `loam tasks` sits at\n * the head of them. They used to be three things done in order — generate the\n * suite, write the definitions, implement — which is only the right order for a\n * slice whose every requirement already owns a scenario. Where one does not,\n * the next thing owed is a sentence in the docs repo, and the body had no step\n * that could say so; where the suite is half written, nothing here answered\n * which half. `at` answers both: the projection names which of four states the\n * next unit is in, and each state names exactly one action, so the numbering\n * below is a table of destinations rather than an itinerary. An editor adding a\n * step must therefore say which `at` value routes to it, or it is unreachable.\n */\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 tasks` — the open units, ordered; `--next` is the single next unit, with the scenario verbatim and the fact that closes it\",\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 --agent-profile service\\` then\n\\`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. \\`loam tasks $1 --service $2 --next --json\\` — ONE unit of work, and the loop\n   every step below runs inside. Step 2 is the whole brief; this is the next thing\n   to do in it. It writes nothing: the projection is derived from the verify\n   checklist, the delta scans, the feature's verification record and — in this,\n   the bound service repo — the digest stamps in the generated \\`.feature\\` files.\n   Drop \\`--next\\` to see every open unit instead of only the head.\n   Each entry of \\`units[]\\` carries its \\`id\\` (the same id the verify checklist uses\n   for that claim), \\`kind\\` (\\`service.exists\\`, \\`api.exposes\\`, \\`event.declares\\`,\n   \\`c4.calls\\`, \\`scenario.tested\\` or \\`requirement.described\\`), \\`subject\\`, \\`claim\\`,\n   \\`digest\\`, \\`dependsOn\\`, \\`source\\` — the path, line, requirement and scenario it was\n   derived from, with the scenario's own \\`lines\\` verbatim — and \\`done.check\\`.\n\n   \\`at\\` is the instruction. It says what the unit NEEDS, and each of its four\n   values names exactly one action:\n   - \\`describe\\` — the requirement owns no scenarios yet. Write the Given/When/Then\n     in the DOCS repo, on the requirement \\`source\\` names, and nothing else. loam\n     does not author, and no amount of code closes a unit sitting here.\n   - \\`generate\\` — no stamped \\`.feature\\` carries this scenario's digest. The only\n     action is \\`loam gherkin $1\\` in this repo (step 4). Do not write code.\n   - \\`implement\\` — the stamped scenario exists and no recorded run has confirmed\n     it. Write step definitions outside \\`loam/\\`, implement until the suite passes,\n     then \\`loam verify $1 --service $2 --results report.json\\` (step 5).\n   - \\`attested\\` — the claim was closed on somebody's word rather than on a run.\n     Run the suite and re-record it so it stops resting on an assertion. An\n     agent-attested scenario stays visible at \\`attested\\` forever, deliberately: it\n     is the one state that cannot be made to go away by ignoring it.\n\n   \\`done.check\\` is the FACT that closes the unit, and the RUNNER decides whether\n   that fact holds — never your own reading of the code you just wrote. Done means\n   the unit no longer appears, and it stops appearing only once its claim is\n   recorded confirmed in a verification record that is not stale. So re-run\n   \\`loam tasks $1 --service $2 --json\\` after every recording instead of working\n   down a list you copied out: \\`frontier\\` (the first ten open unit ids, in order)\n   and \\`counts\\` (\\`open\\`, \\`done\\`, \\`attested\\`) are recomputed from the documents on\n   every run, which is what makes taking the head of it always safe.\n   \\`checklist\\` is the digest of the question set the whole projection derives from.\n   If it differs from the one you started against, the question set moved under\n   you — re-read the feature before continuing, because what you closed earlier may\n   not be what is being asked now.\n   \\`record\\` says whether the answers were found at all (\\`absent\\`, \\`recorded\\`,\n   \\`stale\\`, \\`unreadable\\`) and \\`stamps\\` whether this repo's generated suite could be\n   read (\\`read\\`, \\`unknown\\`); an \\`unknown\\` makes every \\`generate\\` verdict a guess,\n   so fix the binding before acting on one. \\`contracts\\` restates step 6 as data\n   (\\`expose[]\\` and \\`call[]\\`), \\`size\\` the shape of the packet, \\`review[]\\` what a\n   reviewer of it will read, and \\`waitingOn\\` — whenever the packet is narrowed to one\n   service: by \\`--service\\`, or without it to this repo's own service when the feature\n   touches it — what another service still owes before your frontier can move.\n   Exit 1 with \\`ok: true\\` is step 2's rule again: delta.likec4 or one of the\n   contract axes did not parse, so the projection is SHORT by everything that\n   document would have contributed. Fix the document; do not work the units that\n   happened to survive it.\n4. \\`at: \"generate\"\\` — in the service's repo, \\`loam gherkin $1 --json\\`. One\n   \\`.feature\\` file per changed requirement lands under \\`<gherkinDir>/loam/\\`\n   (default \\`features/loam/\\`), scenarios digest-stamped, arch requirements tagged\n   \\`@architecture\\`. Those files ARE the acceptance criteria. Never edit them:\n   regeneration rewrites the directory, and \\`loam validate\\` reports the suite stale\n   by digest, not by your intentions. Generating is the WHOLE action for a unit at\n   \\`generate\\`: go back to step 3, where the same unit now reads \\`implement\\`.\n5. \\`at: \"implement\"\\` — step definitions FIRST, outside \\`loam/\\`, then the code.\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.\n   Then implement until the suite passes — run it with a JSON report\n   (\\`cucumber-js --format json:report.json\\`; cucumber-jvm, behave, Reqnroll,\n   pytest-bdd \\`--cucumberjson\\` and godog write the same cucumber JSON):\n   \\`loam verify $1 --service $2 --results report.json\\` consumes that report as the\n   done-check's answer sheet. A runner with no cucumber formatter answers through\n   loam's runner-neutral shape instead, keyed by each scenario's \\`@loam-digest\\`\n   tag — adapting the runner's report into it is a build step you own:\n   \\`{\"loamScenarioReport\": 1, \"results\": [{\"digest\": \"<16 hex>\", \"status\": \"passed\"}]}\\`.\n   A cucumber run must have run every step of the stamped scenario: a report\n   entry whose step count differs is not that scenario's run and stays\n   unconfirmed. 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. Recording is what\n   closes the unit, so step 3 is the command AFTER it, not the end of the run.\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.\n   The code you just wrote is evidence about the delta's edges. If an edge the\n   feature draws as \\`connects\\` is in fact a publish, a delivery, a read or a write,\n   redraw it in delta.likec4 with that kind (\\`loam instructions loam-drawing\\`) —\n   and step 7 applies, because that is a change to the feature's documents.\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. Write the question under\n\\`## Open questions\\` in the feature's \\`intent.md\\`, where loam-feature's analyze\nstep put the ones it found, so a person answers it once for every service.\n`,\n};\n"]}

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

@@ -0,0 +1,311 @@
+export const LOAM_AUTHORING = {
+    name: "loam-authoring",
+    description: "Reference: the grammars you author against — arch.spec.md, the generated Gherkin suite, frontmatter, and writing a feature a person can follow",
+    // 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, the frontmatter fields `loam vouch` stamps, and how to write a feature's documents so a reviewer can follow them.",
+    invocation: "loam instructions loam-authoring",
+    placeholders: [],
+    spine: [
+        "The architecture spec axis",
+        "The generated Gherkin suite",
+        "Frontmatter — who vouched for this, and from what",
+        "Writing for a person",
+    ],
+    body: `The grammars you author against: the architecture spec axis, the generated Gherkin suite, frontmatter, and writing a feature a person can follow.
+
+## 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. The fleet readouts say the same: \`loam list\` shows
+\`vouched (stale)\` and owes the row a re-vouch, and \`loam status\` emits
+\`next.revouch\` — a step for a person, never for you.
+
+\`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.
+
+## Writing for a person
+
+A feature is read by a reviewer before anyone builds it, and its requirements
+are read for years after \`loam archive\` copies them into the living docs. loam
+grades the joins and never the prose, so nothing in this section is checked: a
+delta can validate clean and still be one nobody can follow.
+
+**intent.md** opens with the problem in business terms — \`## Why\` and
+\`## Scope\`, the two sections the archive gate reads — and then carries the three
+things a reviewer looks for first:
+
+- \`## How to read this feature\`: two or three sentences saying which services
+  change, which document to open first, and which picture shows the change (the
+  delta's own view, or a flow under the feature's \`usecases/\`).
+- a business-requirement coverage table, one row per business requirement the
+  feature was asked to meet, naming what keeps it:
+
+      | Business requirement | Kept by | Where |
+      |---|---|---|
+      | A customer can split one payment between two cards | PAY-SPLIT-1 | payment-split-service spec.md |
+      | Every payee gets a receipt | uc_split_receipt | usecases/split-receipt.likec4 |
+
+- \`## Open questions\` (the scaffold already writes the heading) as a table, so
+  that a person can answer each question and a reader can see what each blocks:
+
+      | ID | Question | Blocks | Owner | Current default |
+      |---|---|---|---|---|
+      | Q1 | Is a split refunded per card or as a whole? | PAY-SPLIT-3 | payments-team | per card |
+
+  The current default is what gets built if nobody answers, so write one for
+  every question.
+
+**Each spec delta opens with a plain-language \`## Purpose\`**: what the service
+does in this change, written for someone who has never opened its code. Where
+the delta CREATES the living document — a new service's spec.md, a first
+arch.spec.md, a new capability — \`loam archive\` copies that section into the
+new document as its narrative. Where the living document already exists, the
+section stays with the archived delta, and the archive plan says so on that
+file's line; if the service's own narrative should change, edit the living
+document in the same change.
+
+**Write a long requirement body as a lead and bullets.** A new requirement
+states one behaviour. A requirement carried over from another source often
+arrives as one paragraph of SHALL sentences. Keep every sentence, but open with
+one line that says what the requirement is for, and give each SHALL sentence a
+bullet of its own:
+
+    ### Requirement: Split a payment
+    Requirement-ID: PAY-SPLIT-1
+
+    A payment can be divided between several payees.
+
+    - The service SHALL accept between two and five payees per split.
+    - The service SHALL reject a split whose shares do not add up to the authorized amount.
+
+**Expand every abbreviation the first time a document uses it**, in words a new
+reader knows: "service-level objective (SLO)", then "SLO".
+
+**Keep review-time wording out of what the archive copies.** "This delta", "this
+feature", "the new endpoint" and "we now" read correctly in review. But
+\`loam archive\` copies requirement bodies, scenarios and contract descriptions
+into living documents, where "this feature" points at a pull request that merged
+long ago. Write what the service does, not what the change does. Prose about the
+change belongs in \`intent.md\`, which stays with the feature.
+
+**A feature's vocabulary, decisions and flows travel with it.**
+
+- A word the feature brings is \`features/<FEAT>/glossary/<term>.md\`, which the
+  archive copies into \`glossary/\`. A term the living glossary already defines is
+  edited there instead, because the copy never overwrites
+  (\`glossary.term-exists\`).
+- A decision is \`features/<FEAT>/adrs/NNNN-<slug>.md\`. It stays with the
+  feature under \`features/archive/\`, and the living documents that link to it go
+  on resolving. A decision meant to outlive the change belongs in
+  \`architecture/adrs/\` or the service's own \`adrs/\` instead.
+- A flow that keeps a promise across services is
+  \`features/<FEAT>/usecases/<name>.likec4\`: a \`dynamic view\` tagged
+  \`#cap-<capability>\`, naming a capability the fleet declares, and
+  \`#req-<Requirement-ID>\`, naming the promise it keeps. A promise the feature's
+  own capability delta adds resolves too. \`usecase.capability-unresolved\` and
+  \`usecase.requirement-unresolved\` grade both tags before the archive.
+
+Link to all three from the deltas, written relative to the file you write in:
+\`loam archive\` re-points every link into the feature for the move.
+
+**Write a \`Covers:\` edge by service name**:
+\`Covers: order-service -> payment-service\`. An edge spelled by its endpoints'
+service names resolves the same before and after the archive. A delta's own
+element id may not, and \`covers.unknown\` at feature scope says when it would not.
+A kinded spelling such as \`order-service -[calls]-> payment-service\` is accepted,
+but the kind is read past rather than compared: it covers every edge from the
+first service to the second, whatever its kind. So write the plain arrow.
+
+**Draw a producer outside the fleet as an \`#external\` element**, with the edge
+it publishes on carrying \`metadata { publishes }\`, so that the consumer's
+\`Consumes:\` line has a producer to join to. \`loam instructions loam-spine\`
+("A message produced outside the fleet") has the join, and
+\`loam instructions loam-drawing\` has the drawing.
+`,
+};
+//# 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":"AAuBA,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,IAAI,EAAE,gBAAgB;IACtB,WAAW,EACT,gJAAgJ;IAClJ,6EAA6E;IAC7E,+CAA+C;IAC/C,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,4QAA4Q;IAC9Q,UAAU,EAAE,kCAAkC;IAC9C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE;QACL,4BAA4B;QAC5B,6BAA6B;QAC7B,mDAAmD;QACnD,sBAAsB;KACvB;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqSP;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 first three sections are the three AGENTS.md sections verbatim, in their\n * original order, so a cross-reference elsewhere in the corpus still names the\n * same headings. The fourth, \"Writing for a person\", was written for this page\n * and never stood in AGENTS.md. A large real fleet was migrated into one feature\n * whose every delta validated, and its reviewers still could not follow it: no\n * purpose said what a service did, requirement bodies were a source document\n * pasted whole, and \"this delta\" was copied into the living docs by the\n * archive. No check reads prose, so this is where that lesson lives. Its\n * examples are neutral; nothing from that fleet may enter this repository.\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, and writing a feature a person can follow\",\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, the frontmatter fields `loam vouch` stamps, and how to write a feature's documents so a reviewer can follow them.\",\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    \"Writing for a person\",\n  ],\n  body: `The grammars you author against: the architecture spec axis, the generated Gherkin suite, frontmatter, and writing a feature a person can follow.\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. The fleet readouts say the same: \\`loam list\\` shows\n\\`vouched (stale)\\` and owes the row a re-vouch, and \\`loam status\\` emits\n\\`next.revouch\\` — a step for a person, never for you.\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## Writing for a person\n\nA feature is read by a reviewer before anyone builds it, and its requirements\nare read for years after \\`loam archive\\` copies them into the living docs. loam\ngrades the joins and never the prose, so nothing in this section is checked: a\ndelta can validate clean and still be one nobody can follow.\n\n**intent.md** opens with the problem in business terms — \\`## Why\\` and\n\\`## Scope\\`, the two sections the archive gate reads — and then carries the three\nthings a reviewer looks for first:\n\n- \\`## How to read this feature\\`: two or three sentences saying which services\n  change, which document to open first, and which picture shows the change (the\n  delta's own view, or a flow under the feature's \\`usecases/\\`).\n- a business-requirement coverage table, one row per business requirement the\n  feature was asked to meet, naming what keeps it:\n\n      | Business requirement | Kept by | Where |\n      |---|---|---|\n      | A customer can split one payment between two cards | PAY-SPLIT-1 | payment-split-service spec.md |\n      | Every payee gets a receipt | uc_split_receipt | usecases/split-receipt.likec4 |\n\n- \\`## Open questions\\` (the scaffold already writes the heading) as a table, so\n  that a person can answer each question and a reader can see what each blocks:\n\n      | ID | Question | Blocks | Owner | Current default |\n      |---|---|---|---|---|\n      | Q1 | Is a split refunded per card or as a whole? | PAY-SPLIT-3 | payments-team | per card |\n\n  The current default is what gets built if nobody answers, so write one for\n  every question.\n\n**Each spec delta opens with a plain-language \\`## Purpose\\`**: what the service\ndoes in this change, written for someone who has never opened its code. Where\nthe delta CREATES the living document — a new service's spec.md, a first\narch.spec.md, a new capability — \\`loam archive\\` copies that section into the\nnew document as its narrative. Where the living document already exists, the\nsection stays with the archived delta, and the archive plan says so on that\nfile's line; if the service's own narrative should change, edit the living\ndocument in the same change.\n\n**Write a long requirement body as a lead and bullets.** A new requirement\nstates one behaviour. A requirement carried over from another source often\narrives as one paragraph of SHALL sentences. Keep every sentence, but open with\none line that says what the requirement is for, and give each SHALL sentence a\nbullet of its own:\n\n    ### Requirement: Split a payment\n    Requirement-ID: PAY-SPLIT-1\n\n    A payment can be divided between several payees.\n\n    - The service SHALL accept between two and five payees per split.\n    - The service SHALL reject a split whose shares do not add up to the authorized amount.\n\n**Expand every abbreviation the first time a document uses it**, in words a new\nreader knows: \"service-level objective (SLO)\", then \"SLO\".\n\n**Keep review-time wording out of what the archive copies.** \"This delta\", \"this\nfeature\", \"the new endpoint\" and \"we now\" read correctly in review. But\n\\`loam archive\\` copies requirement bodies, scenarios and contract descriptions\ninto living documents, where \"this feature\" points at a pull request that merged\nlong ago. Write what the service does, not what the change does. Prose about the\nchange belongs in \\`intent.md\\`, which stays with the feature.\n\n**A feature's vocabulary, decisions and flows travel with it.**\n\n- A word the feature brings is \\`features/<FEAT>/glossary/<term>.md\\`, which the\n  archive copies into \\`glossary/\\`. A term the living glossary already defines is\n  edited there instead, because the copy never overwrites\n  (\\`glossary.term-exists\\`).\n- A decision is \\`features/<FEAT>/adrs/NNNN-<slug>.md\\`. It stays with the\n  feature under \\`features/archive/\\`, and the living documents that link to it go\n  on resolving. A decision meant to outlive the change belongs in\n  \\`architecture/adrs/\\` or the service's own \\`adrs/\\` instead.\n- A flow that keeps a promise across services is\n  \\`features/<FEAT>/usecases/<name>.likec4\\`: a \\`dynamic view\\` tagged\n  \\`#cap-<capability>\\`, naming a capability the fleet declares, and\n  \\`#req-<Requirement-ID>\\`, naming the promise it keeps. A promise the feature's\n  own capability delta adds resolves too. \\`usecase.capability-unresolved\\` and\n  \\`usecase.requirement-unresolved\\` grade both tags before the archive.\n\nLink to all three from the deltas, written relative to the file you write in:\n\\`loam archive\\` re-points every link into the feature for the move.\n\n**Write a \\`Covers:\\` edge by service name**:\n\\`Covers: order-service -> payment-service\\`. An edge spelled by its endpoints'\nservice names resolves the same before and after the archive. A delta's own\nelement id may not, and \\`covers.unknown\\` at feature scope says when it would not.\nA kinded spelling such as \\`order-service -[calls]-> payment-service\\` is accepted,\nbut the kind is read past rather than compared: it covers every edge from the\nfirst service to the second, whatever its kind. So write the plain arrow.\n\n**Draw a producer outside the fleet as an \\`#external\\` element**, with the edge\nit publishes on carrying \\`metadata { publishes }\\`, so that the consumer's\n\\`Consumes:\\` line has a producer to join to. \\`loam instructions loam-spine\\`\n(\"A message produced outside the fleet\") has the join, and\n\\`loam instructions loam-drawing\\` has the drawing.\n`,\n};\n"]}