@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

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

@@ -1,4 +1,18 @@
-/** Building one service's slice: the delta brief, generated gherkin, steps, code, verify. */
+/**
+ * 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",
@@ -10,6 +24,7 @@ export const LOAM_IMPLEMENT = {
         "`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",
@@ -18,7 +33,8 @@ export const LOAM_IMPLEMENT = {
     ],
     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.
+\`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
@@ -59,12 +75,65 @@ repository, which needs its own committed ./loam.json — if there is none,
    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/\`.
+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
@@ -75,14 +144,26 @@ repository, which needs its own committed ./loam.json — if there is none,
    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\`):
+   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. Record from THIS repo, with \`--service\` — 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.
+   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
@@ -99,7 +180,9 @@ repository, which needs its own committed ./loam.json — if there is none,
 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.
+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

@@ -1 +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"]}
+{"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

@@ -1,18 +1,19 @@
 export const LOAM_AUTHORING = {
     name: "loam-authoring",
-    description: "Reference: the grammars you author against — arch.spec.md, the generated Gherkin suite, frontmatter",
+    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, and the frontmatter fields `loam vouch` stamps.",
+    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, and frontmatter.
+    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
 
@@ -161,7 +162,9 @@ the forgery — editing a spec after it was vouched used to leave \`status: veri
 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.
+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
@@ -204,6 +207,105 @@ 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

@@ -1 +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"]}
+{"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"]}

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

@@ -14,14 +14,16 @@
  * 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.
+ * section byte for byte. That is the assembly contract every part's header
+ * points back at: each starts at the first character of its opening line and
+ * ends with the newline that closes its last one, or two parts glue onto one
+ * line on the printed page.
  *
  * 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.
+ * AGENTS.md (../../agents-md.ts's ORIENTATION), and it is orientation, not a
+ * summary of this page: the envelope's keys, branching on codes rather than
+ * prose, severity versus gating, and a pointer here. 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";

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

@@ -1 +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"]}
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../../../../src/core/agent/workflows/reference/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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. That is the assembly contract every part's header\n * points back at: each starts at the first character of its opening line and\n * ends with the newline that closes its last one, or two parts glue onto one\n * line on the printed page.\n *\n * WHAT IS AND IS NOT DUPLICATED. `## Reading loam's output` still exists in\n * AGENTS.md (../../agents-md.ts's ORIENTATION), and it is orientation, not a\n * summary of this page: the envelope's keys, branching on codes rather than\n * prose, severity versus gating, and a pointer here. The per-invocation\n * inventory 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"]}

package/dist/core/agent/workflows/reference/done-check.js

@@ -30,9 +30,12 @@ so a JUnit or pytest fleet is not held at \`attested\` by a file format —
 \`loam verify <FEAT> --results report.json\`. A claim is confirmed only when a
 report scenario carrying its \`@loam-digest-<16hex>\` tag ran at least one step
 and every step passed — every occurrence, when the report holds a re-run, and
-every before/after hook with it. A failed, undefined, pending or skipped step,
-a failed hook, or no matching scenario at all, is \`unconfirmed\` with the
-reason. The digest is the only identity: a reworded spec scenario matches
+every before/after hook with it — and, in a cucumber report, ran exactly as
+many steps as the stamped scenario has: a hand-tagged stub is not that
+scenario's run. A failed, undefined, pending or skipped step, a failed hook, a
+step count that differs, or no matching scenario at all, is \`unconfirmed\` with
+the reason. A report that is not JSON (a JUnit XML file) is refused
+\`answers-unreadable\`, naming both shapes. The digest is the only identity: a reworded spec scenario matches
 nothing until the suite is regenerated and re-run. When a report exists,
 ALWAYS pass \`--results\` — under it the runner owns every scenario claim, and
 an answers-file entry for one is refused.
@@ -92,9 +95,12 @@ re-checks the pins and reports drift under the \`evidence.*\` findings; nothing
 there moves a verdict either.
 
 Two more codes belong to the record itself. \`verify.record-miscounted\` (error):
-a \`verification.yaml\` whose \`summary\` block contradicts its own \`claims[]\` — the
-record is refused as unreadable rather than believed in either half, and
-re-recording is the repair, never editing the counts. \`verify.digest-contested\`
+a record file whose \`summary\` block contradicts its own \`claims[]\` — the
+record is refused as unreadable rather than believed in either half, and the
+repair is never editing the counts: a service's own \`verification/<id>.yaml\`
+is deleted and recorded again by that service, and the one-file
+\`verification.yaml\` is restored from version control and then recorded over.
+\`verify.digest-contested\`
 (warn): two or more services word a scenario identically, so they share one
 \`@loam-digest-…\` tag and no single cucumber report can say whose suite ran it —
 those scenario claims are left unconfirmed, and each service records its own
@@ -113,7 +119,10 @@ services that all answered a since-rewritten delta agree with each other and are
 every one of them stale. Differing \`docsCommit\` values are NOT a finding:
 recording a week apart is normal for a feature in flight.
 Normal mid-rollout and it gates nothing; re-record the services on the older
-version from their own repositories, or accept the split knowingly.
+version from their own repositories. In a record kept as per-service files the
+answers of the services it names do not count until they do: the record
+answers the newest version its files answered, and an answer filed against an
+older one could otherwise fill the slot of the question that replaced it.
 Attestations written before the field existed carry no \`checklist\` and are not
 counted as a third version — silence is not disagreement.
 
@@ -126,8 +135,9 @@ commit. It does not prove the file came from executing that commit; no digest
 can.
 
 Everything else you answer from the code, and \`--record answers.json\` takes
-those back, writing \`features/<FEAT>/verification.yaml\` — it travels into the
-archive with the feature and reads without loam. Alongside the mechanical
+those back — into \`features/<FEAT>/verification/<svc>.yaml\` with \`--service\`,
+into the one file \`features/<FEAT>/verification.yaml\` without — and either
+travels into the archive with the feature and reads without loam. Alongside the mechanical
 flags, the answers file must answer exactly the claims no report owns: an
 entry for a report-owned claim is refused (\`answers-mismatch\`), and a
 mechanical flag alone is refused while claims outside its kind are
@@ -147,9 +157,16 @@ loam verify FEAT-101 --service payment-service --results report.json --contract-
 \`\`\`
 
 \`--service <id>\` narrows the checklist to that service's claims and binds the
-answers to this repository's commit, producing one **attestation** per service
-inside a single \`schema: 2\` \`verification.yaml\`. Re-running it in the next
-repo adds that repo's attestation and leaves the others standing. Omitting
+answers to this repository's commit, producing that service's **attestation**
+as a file of its own, \`features/<FEAT>/verification/<id>.yaml\`. The directory
+is the record: loam adds the files up when it reads, and the verdict and
+counts are computed from them, never stored. Re-running it in the next repo
+writes that repo's file and touches no other — which is why two teams'
+attestations on two docs-repo branches merge cleanly, where one shared file
+conflicted every time. A one-file federated \`verification.yaml\` written
+before the directory is still read; a service that records again supersedes
+its share of it, and the file goes once every service it names has its own.
+Omitting
 \`--service\` in a repo whose \`loam.json\` declares one substitutes it, so the
 short form is safe there; a \`--service\` naming a service this repo does not
 declare is refused (\`service-mismatch\`), and \`--service\` from a repo that
@@ -161,9 +178,14 @@ no \`--service\` writes the whole record from one place.** Over a record that
 already carries other services' attestations it is refused outright
 (\`record-federated\`, naming the attestors) rather than merged or migrated — the
 alternative was one repo silently erasing nine others' evidence. Use it only for
-a single-service feature that has never been recorded federated. A
-\`verification.yaml\` that exists but cannot be read is \`record-unreadable\`: it is
-never overwritten and never reported as "no record".
+a single-service feature that has never been recorded federated. A record file
+that exists but cannot be read — broken YAML, git conflict markers, a miscount
+— is \`record-unreadable\`: it is never overwritten and never reported as "no
+record", and the message names the file and the repair that is safe for it. A
+service's own \`verification/<id>.yaml\` holds only that service's word, so that
+service may delete it and record again; the one-file \`verification.yaml\` may
+hold other services' attestations, so it is restored from version control
+(after a merge, the copy on the branch you merged into) and never deleted.
 
 Reading is not writing: \`loam verify <FEAT> --service <id>\` **without**
 \`--record\` is a pure lens on the checklist. A read-only verify checklist needs no