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

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

@@ -37,10 +37,14 @@ reads the service, so a verdict is worth exactly what its evidence is worth.
    must change.
 2. The \`scenario.tested\` claims are the runner's to answer, not yours. In the
    service's repo, run the generated suite with a JSON report —
-   \`npx cucumber-js --format json:report.json\` (cucumber-jvm, behave and
-   SpecFlow emit the same format). The generated scenarios carry
-   \`@loam-digest-…\` tags that ride into the report; that digest is the match,
-   so never retitle or hand-edit a generated scenario to make one pass.
+   \`npx cucumber-js --format json:report.json\` (cucumber-jvm, behave,
+   SpecFlow/Reqnroll, pytest-bdd \`--cucumberjson\` and godog emit the same
+   format). The generated scenarios carry \`@loam-digest-…\` tags that ride into
+   the report; that digest is the match, and the run must have executed every
+   step of the stamped scenario, so never retitle or hand-edit a generated
+   scenario to make one pass. A runner with no cucumber formatter answers
+   through loam's runner-neutral shape instead, keyed by the same digests:
+   \`{"loamScenarioReport": 1, "results": [{"digest": "…", "status": "passed"}]}\`.
    If there is no runnable suite yet you MAY answer them yourself, and the record
    will say so: \`answered_by: agent\` makes the feature **attested**, not verified
    (\`verified: false\`, \`verdict: "attested"\`, the \`verify.scenario-attested\`
@@ -105,29 +109,36 @@ reads the service, so a verdict is worth exactly what its evidence is worth.
    \`\`\`
 
    \`--service <id>\` narrows the checklist to that service's claims and binds the
-   answers to this repository's commit, writing ONE attestation into a shared
-   \`schema: 2\` \`verification.yaml\`. Running it in the next repo adds that repo's
-   attestation and leaves the others standing. In a repo whose ./loam.json
+   answers to this repository's commit, writing that service's attestation to
+   its OWN file, \`features/$1/verification/<id>.yaml\` — the directory is the
+   record, and loam adds the files up when it reads. Running it in the next repo
+   writes that repo's file and touches no other, so two teams' docs PRs never
+   conflict over the record. In a repo whose ./loam.json
    declares a \`service\`, \`--service\` may be omitted — it is substituted, and the
    run still federates. \`--results report.json\` alone is legal when the
    checklist is all scenarios.
 
    ⚠ **Never run \`loam verify $1 --record answers.json\` without \`--service\`.**
    That is the legacy all-at-once form: it writes the WHOLE record from one place,
-   and over a record that already carries other services' attestations it is
-   refused (\`record-federated\`, naming them) precisely because it would erase
-   them. If you meet that refusal, re-run with \`--service\`; do not work around it.
+   into the one file \`verification.yaml\`, and over a record that already carries
+   other services' attestations it is refused (\`record-federated\`, naming them)
+   precisely because it would put one unattested answer set over them. If you
+   meet that refusal, re-run with \`--service\`; do not work around it.
 
    The other refusals: \`answers-mismatch\` (an id
    nobody asked about, a claim you left out — re-run step 1, the feature moved —
    or an answers entry for a \`scenario.tested\` claim: the runner owns those),
    \`answers-unevidenced\` (a \`confirmed\` with nothing behind it),
    \`answers-unreadable\` (a report or answers file it cannot read),
-   \`record-unreadable\` (a \`verification.yaml\` that exists but cannot be read as a
-   record — it is never overwritten; a human repairs it, and
-   \`verify.record-miscounted\` is the reason when its \`summary\` block contradicts
-   its own \`claims[]\`: neither half can be believed, so re-record rather than
-   editing the counts),
+   \`record-unreadable\` (a record file that exists but cannot be read — broken
+   YAML, git conflict markers a merge left, or \`verify.record-miscounted\` when
+   its \`summary\` block contradicts its own \`claims[]\`. It is never overwritten,
+   and the message names the file and the safe repair: 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 repaired or restored from version
+   control — after a merge, the copy on the branch you merged into — and
+   **never deleted**. Never edit the counts to make them agree),
    \`service-mismatch\` (\`--service\` names a service this repo does not declare) and
    \`repository-unavailable\` (\`--service\` from a repo that declares none, or whose
    commit cannot be read — an attestation must be bound to the code it is about).
@@ -161,8 +172,8 @@ gathered from the steps above; branch on the code, never the prose:
 | \`verify.scenario-attested\` (warn) | scenario claims were answered on an agent's word (\`answered_by: agent\`), so the verdict is **attested**, not verified — nothing gates on it, but say so when you hand back | run the generated suite with a JSON report and re-record with \`--results report.json\` the moment a suite exists |
 | \`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 stay unconfirmed | each service records its own claims from its own repository with \`--service <id>\` |
 | \`verify.operation-contested\` (warn) | two services on the checklist expose the same operationId, so a contract report — which names no service — cannot say whose suite exercised it; those claims stay unconfirmed | each service records its own with \`--service <id>\`, passing its own contract report |
-| \`verify.checklist-forked\` (warn) | one or more services answered a DIFFERENT version of the feature's question set than the one it now asks — each attestation carries the \`checklist\` digest it answered, and the notice names the ones that do not match the current checklist. Measured against the present, not pairwise: services that all attested against a since-rewritten delta agree with each other perfectly and are all stale. Normal mid-rollout, since services attest as they finish. Attestations written before the field existed carry no digest and are never called stale | re-record the services on the older version from their own repositories (\`loam verify <FEAT> --service <id> --record\`), or accept the split knowingly — nothing gates on it |
-| \`verify.record-miscounted\` (error) | a verification.yaml whose \`summary\` block contradicts its own \`claims[]\` — neither half can be believed, so the record is refused as unreadable rather than trusted in either direction | re-record from the service's repo; never edit the counts by hand |
+| \`verify.checklist-forked\` (warn) | one or more services answered a DIFFERENT version of the feature's question set than the one it now asks — each attestation carries the \`checklist\` digest it answered, and the notice names the ones that do not match the current checklist. Measured against the present, not pairwise: services that all attested against a since-rewritten delta agree with each other perfectly and are all stale. Normal mid-rollout, since services attest as they finish. Attestations written before the field existed carry no digest and are never called stale. In a per-service record the answers of the services named do not count until they record again | re-record the services on the older version from their own repositories (\`loam verify <FEAT> --service <id> --record\`) — nothing gates on it |
+| \`verify.record-miscounted\` (error) | a record file whose \`summary\` block contradicts its own \`claims[]\` — neither half can be believed, so the record is refused as unreadable rather than trusted in either direction | a service's own \`verification/<id>.yaml\`: delete it and re-record from that service's repo; the one-file \`verification.yaml\`: restore it from version control, then re-record — never delete it, and never edit the counts by hand |
 | \`verify.evidence-token-missing\` (warn) | a just-confirmed citation's file at the attested commit does not contain the claim's own token (the operationId, message name or edge op) — the evidence may not show what the answer says | re-read that evidence while the answer can still be corrected; verdict-neutral, it gates nothing |
 | \`cross.agree-confirmed\` / \`cross.agree-unconfirmed\` (ok) | a \`--diff-answers\` row where both blind answer sets reach the same verdict — the cheap-to-skip review queue, though same-model agreement is correlated and proves nothing | nothing on its own; record only the answer set you stand behind, in a separate run |
 | \`cross.disagree\` (the rows a human reads first) | a \`--diff-answers\` row where the two blind answer sets contradict each other — one of them is wrong about the code | read both cited evidences and decide; the diff writes nothing and never moves a verdict |
@@ -181,6 +192,7 @@ export const LOAM_SHIP = {
         "`loam validate --feature $1` must come back valid; if it says nothing pinned the delta, rebase and re-validate first",
         "`loam archive $1 --dry-run` — read the whole plan and every warning before the merge touches anything",
         "`loam archive $1` for real, and read what it reports it did",
+        "every vouched spec on `revouchOwed[]` owes its owner's re-vouch — tell them; it lands in this same PR",
         "`loam unarchive $1` is the undo if the plan turns out to have been wrong",
     ],
     body: `Archive a shipped feature.
@@ -202,8 +214,10 @@ export const LOAM_SHIP = {
    truth, and stop if a file you did not expect is on it. \`warnings[]\` is what the
    merge will do that is legal but lossy — advisory warnings never block, which is
    exactly why you read them now: \`openapi.op-modified\` means an operation the living
-   contract already defines gets overwritten wholesale (\`openapi.component-modified\`
-   is the same story for a component the merged operations carry),
+   contract already defines gets overwritten wholesale, and its \`details\` name the
+   current consumers that overwrite lands on (\`asyncapi.message-modified\` likewise for
+   a message; \`openapi.component-modified\` is the same story for a component the
+   merged operations carry, with no consumer list),
    \`service.no-model\` means a service arrives with no C4 centre behind it, and
    \`delta.added-conflict\`
    means another feature in flight adds the same requirement — the first to archive
@@ -215,7 +229,11 @@ export const LOAM_SHIP = {
    elements and edges into \`architecture/landscape.likec4\` and, for an addition nested
    under a service whose model EXTENDS the map, into that
    \`services/<…>/<svc>/model.likec4\` instead — then moves the feature
-   under \`features/archive/\`. Success is \`ok: true\`; on \`ok: false\`, branch on
+   under \`features/archive/\`, whole: its verification record travels with it,
+   the per-service \`verification/<id>.yaml\` files and any one-file
+   \`verification.yaml\` alike, and \`loam verify $1\` reads it back afterwards as
+   frozen history. Verification never gates the archive — an open or missing
+   record ships as exactly that. Success is \`ok: true\`; on \`ok: false\`, branch on
    \`error.code\`:
    - \`not-coherent\` — gating coherence issues; \`issues[]\` in the envelope lists them,
      each with \`gates\` and \`overridable\` resolved (advisory warnings do not block).
@@ -228,7 +246,12 @@ export const LOAM_SHIP = {
      \`overridable: false\`, and the fix is a rename, never the flag.
      \`openapi.remove-marker-path-level\` arrives
      here too: an \`x-loam-remove\` written beside the methods instead of inside the
-     operation retires nothing.
+     operation retires nothing. So do \`openapi.op-revived\` and
+     \`asyncapi.slot-revived\`: the delta spells an operation, slot or message an
+     ARCHIVED feature retired, and the merge would put it back. If the delta only
+     quoted it, delete the quote; whether the feature brings it back on purpose is
+     the human's \`--approve\`, and the archive output then names what came back
+     and whose retirement it reverses.
    - \`living-outside-requirements\` — the LIVING spec holds a requirement outside
      \`## Requirements\`, and the merge would duplicate it. Re-home it, then re-run.
      \`--approve\` does not move this one.
@@ -250,6 +273,16 @@ export const LOAM_SHIP = {
      name the same state) and hand it to a human — re-running does not help.
    - \`rollback-incomplete\` — the merge failed AND some files could not be restored.
      Stop and hand it to a human; the message lists the files to check.
+5. Re-vouches are owed. \`revouchOwed[]\` — on the dry run and the real merge alike —
+   names every VOUCHED spec the merge moves under its vouch stamp, with the
+   document's \`owner\`. \`content.stale\` follows on each, and honestly: the merged
+   text is words nobody has yet read against the code. You cannot clear it — a
+   vouch is a person's, run in that service's own repo (\`loam vouch --service <id>\`,
+   after \`loam vouch --pack --service <id>\` for what to re-read). Name the
+   documents and owners in your hand-back, and say the re-vouches belong in the
+   SAME PR as this archive: a docs repo gated on
+   \`loam validate --all --base <ref> --strict\` keeps the archive's PR red until they
+   land. Never edit a stamp by hand to turn it green.
 
 Archived by mistake? \`loam unarchive $1\` restores the living docs from the snapshot
 archive left in \`features/archive/$1*/.loam-before/\` and re-opens the feature. Do not

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

@@ -1 +1 @@
-{"version":3,"file":"closing.js","sourceRoot":"","sources":["../../../../src/core/agent/workflows/closing.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,qFAAqF;IACvF,YAAY,EAAE,WAAW;IACzB,OAAO,EACL,6NAA6N;IAC/N,UAAU,EAAE,kCAAkC;IAC9C,YAAY,EAAE,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE;QACL,yEAAyE;QACzE,uGAAuG;QACvG,sFAAsF;QACtF,2EAA2E;QAC3E,6FAA6F;KAC9F;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoJP;CACA,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAmB;IACvC,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,yEAAyE;IACtF,YAAY,EAAE,WAAW;IACzB,OAAO,EACL,0MAA0M;IAC5M,UAAU,EAAE,gCAAgC;IAC5C,YAAY,EAAE,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE;QACL,oHAAoH;QACpH,sHAAsH;QACtH,uGAAuG;QACvG,6DAA6D;QAC7D,0EAA0E;KAC3E;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * The two post-build workflows, paired: the done-check (`loam-verify`) and the\n * merge it precedes (`loam-ship`). One file for two commands because six\n * workflows meet the five-file package cap somewhere, and this is the seam the\n * cycle already has — both describe what happens after the code is built, and\n * each body names the other's refusals (`record-federated`, `not-coherent`).\n */\nexport const LOAM_VERIFY: CommandContent = {\n  name: \"loam-verify\",\n  description:\n    \"Verify a built loam feature against its own promises, claim by claim, with evidence\",\n  argumentHint: \"<FEAT-id>\",\n  purpose:\n    \"Check that the code somebody built is the feature that was designed. loam derives the questions; a test runner and you answer them. loam never reads the service, so a verdict is worth exactly what its evidence is worth.\",\n  invocation: \"loam instructions loam-verify $1\",\n  placeholders: [\"feature\"],\n  spine: [\n    \"`loam verify` — the checklist, derived from the feature's own artifacts\",\n    \"run the generated suite with a JSON report: the scenario claims are the runner's to answer, not yours\",\n    \"answer the remaining claims yourself, every one carrying a `file:line` that resolves\",\n    \"record from each affected service's own repository, bound to that service\",\n    \"read the verdict honestly — a scenario confirmed on your word is `attested`, not `verified`\",\n  ],\n  body: `Check that the code somebody just built is the feature that was designed.\n\nloam derives the questions; the test runner and you answer them. loam never\nreads the service, so a verdict is worth exactly what its evidence is worth.\n\n1. \\`loam verify $1 --json\\`. \\`claims[]\\` is the checklist, derived from the feature's\n   own artifacts — one claim per new service, per operation its openapi delta adds,\n   per (direction, message) its asyncapi delta newly declares against the living\n   contract's send/receive sets (quotes and removals are never questions),\n   per tagged edge that names an operation, and per scenario of every changed\n   requirement, arch.spec.md deltas included. Each has a stable \\`id\\` and a\n   \\`subject\\` (the service whose code answers it); a claim that says arch.spec.md\n   wants an integration/ops test, not an acceptance test. An ARCHIVED feature returns its record as frozen history instead\n   (\\`frozen: true\\`) and \\`--record\\` / \\`--results\\` / \\`--contract-results\\` /\n   \\`--diff-answers\\` refuse it — \\`loam unarchive\\` first if the answers really\n   must change.\n2. The \\`scenario.tested\\` claims are the runner's to answer, not yours. In the\n   service's repo, run the generated suite with a JSON report —\n   \\`npx cucumber-js --format json:report.json\\` (cucumber-jvm, behave and\n   SpecFlow emit the same format). The generated scenarios carry\n   \\`@loam-digest-…\\` tags that ride into the report; that digest is the match,\n   so never retitle or hand-edit a generated scenario to make one pass.\n   If there is no runnable suite yet you MAY answer them yourself, and the record\n   will say so: \\`answered_by: agent\\` makes the feature **attested**, not verified\n   (\\`verified: false\\`, \\`verdict: \"attested\"\\`, the \\`verify.scenario-attested\\`\n   notice, and a \\`next.verify-attested\\` step in \\`loam status\\`). Nothing gates on\n   it — a legacy service with no suite must still be able to ship — but say so\n   when you hand back, and close it with \\`--results\\` the moment a suite runs.\n   \\`verify.digest-contested\\` (warn) is the case where two services word a\n   scenario identically: they share one digest, so no single report can say whose\n   suite ran it, and each service must record its own with \\`--service\\`.\n   The \\`api.exposes\\` claims have a mechanical channel too, when an API\n   contract-test suite exists: emit loam's contract-results shape from its\n   report — \\`{\"loamContractReport\": 1, \"results\": [{\"operationId\": \"…\",\n   \"status\": \"passed\"}]}\\`, a one-line transform for Specmatic, Pact, Dredd or a\n   property harness — and pass \\`--contract-results contract.json\\` alongside.\n   Only a status of exactly \\`passed\\` confirms the named operation\n   (\\`answered_by: external-runner\\`); anything else, and an operation the report\n   never exercised, stays \\`unconfirmed\\` with the reason, and under the flag the\n   report owns every api.exposes claim, so take those out of the answers file.\n3. Answer every OTHER claim by finding it in the code. Not by reasoning that it\n   must be there — by opening the file:\n   - \\`service.exists\\` — the service is deployable: its build, its entry point.\n   - \\`api.exposes\\` — the route handler serving that operationId, not the spec that\n     declares it — unless a contract-test report already answered it in step 2.\n   - \\`event.declares\\` — the code that puts the message on the wire (sends) or\n     handles it off the wire (receives), not the contract that names it.\n   - \\`c4.calls\\` — the call site in the CALLER.\n4. Write those answers as JSON — evidence is \\`file:line\\`, one entry per place it can\n   be seen:\n   \\`\\`\\`json\n   { \"answers\": [\n     { \"id\": \"<claim id>\", \"verdict\": \"confirmed\", \"evidence\": [\"src/split/Api.ts:42\"] },\n     { \"id\": \"<claim id>\", \"verdict\": \"unconfirmed\", \"note\": \"the split service has no entry point yet\" }\n   ] }\n   \\`\\`\\`\n5. Optional, before recording: cross-examine. Have a SECOND agent answer the\n   same checklist blind — a fresh context, given only \\`loam verify $1 --json\\`\n   and the code, never your answers file — then compare the two sets:\n\n   \\`\\`\\`sh\n   loam verify $1 --diff-answers yours.json theirs.json --json\n   \\`\\`\\`\n\n   Both files must answer EVERY claim in the compared scope,\n   \\`scenario.tested\\` included: the diff consults no test report, so this is a\n   DIFFERENT file from the one step 6 records under \\`--results\\` (that one\n   must omit the runner's claims; a step-6-shaped file here refuses\n   \\`answers-mismatch\\`). Narrowing with \\`--service <id>\\` compares one\n   service's claims — give the second agent the same lens, or its file will\n   not match the compared scope. An archived feature refuses the diff too:\n   frozen history has no current checklist. It writes nothing and changes no\n   verdict: \\`cross.agree-confirmed\\` / \\`cross.agree-unconfirmed\\` rows are the\n   cheap-to-skip queue, \\`disagreements[]\\` (\\`cross.disagree\\`) is what a human\n   reads first, and the \\`cross.evidence-disjoint\\` notice flags agreements\n   citing non-overlapping files — read those second. Agreement between two\n   same-model agents is correlated, so it ranks review; it never upgrades\n   \\`attested\\` to \\`verified\\`. Record only the answer set you stand behind, in\n   a separate run.\n6. Record, **in each affected service's own repository**, one service at a time:\n\n   \\`\\`\\`sh\n   loam verify $1 --service <id> --results report.json [--contract-results contract.json] --record answers.json --json\n   \\`\\`\\`\n\n   \\`--service <id>\\` narrows the checklist to that service's claims and binds the\n   answers to this repository's commit, writing ONE attestation into a shared\n   \\`schema: 2\\` \\`verification.yaml\\`. Running it in the next repo adds that repo's\n   attestation and leaves the others standing. In a repo whose ./loam.json\n   declares a \\`service\\`, \\`--service\\` may be omitted — it is substituted, and the\n   run still federates. \\`--results report.json\\` alone is legal when the\n   checklist is all scenarios.\n\n   ⚠ **Never run \\`loam verify $1 --record answers.json\\` without \\`--service\\`.**\n   That is the legacy all-at-once form: it writes the WHOLE record from one place,\n   and over a record that already carries other services' attestations it is\n   refused (\\`record-federated\\`, naming them) precisely because it would erase\n   them. If you meet that refusal, re-run with \\`--service\\`; do not work around it.\n\n   The other refusals: \\`answers-mismatch\\` (an id\n   nobody asked about, a claim you left out — re-run step 1, the feature moved —\n   or an answers entry for a \\`scenario.tested\\` claim: the runner owns those),\n   \\`answers-unevidenced\\` (a \\`confirmed\\` with nothing behind it),\n   \\`answers-unreadable\\` (a report or answers file it cannot read),\n   \\`record-unreadable\\` (a \\`verification.yaml\\` that exists but cannot be read as a\n   record — it is never overwritten; a human repairs it, and\n   \\`verify.record-miscounted\\` is the reason when its \\`summary\\` block contradicts\n   its own \\`claims[]\\`: neither half can be believed, so re-record rather than\n   editing the counts),\n   \\`service-mismatch\\` (\\`--service\\` names a service this repo does not declare) and\n   \\`repository-unavailable\\` (\\`--service\\` from a repo that declares none, or whose\n   commit cannot be read — an attestation must be bound to the code it is about).\n7. Report every \\`unconfirmed\\` claim and what it would take to close it, and read\n   \\`discarded\\` in the payload: it names every previous answer the new record does\n   not carry, and each one is either evidence that went stale or evidence that was\n   just dropped. A scenario claim the report failed or missed closes by fixing the\n   code and re-running the suite — never by editing the generated .feature. While\n   any claim stays unconfirmed or unanswered, \\`notices[]\\` carries\n   \\`verify.claims-open\\` (warn, gating nothing): the one-line \"not a clean\n   result\" summary with all four counts, so a partial record can never read as a\n   finished one from the notice lines alone.\n8. Reading is safe from anywhere: \\`loam verify $1 --service <id> --json\\` without\n   \\`--record\\` writes nothing and works from the docs repo too. \\`services\\` lists\n   every subject of the checklist, so it is how you find out which repos still\n   owe an attestation, and \\`loam status $1 --json\\` says the same thing in the\n   shape of a next step.\n\nAnything you cannot show is \\`unconfirmed\\` with a note. That is a successful record,\nand it is the useful one: nothing gates on this file, so the only thing it is for is\ntelling the next reader the truth. \\`loam archive\\` will ship the feature either way —\nwhich is exactly why a \\`confirmed\\` you cannot back up costs nothing now and misleads\neveryone later.\n\n\\`loam verify\\` — the notice and record codes its reports carry in \\`notices[]\\`,\ngathered from the steps above; branch on the code, never the prose:\n\n| code | what it means | what to do |\n|---|---|---|\n| \\`verify.claims-open\\` (warn) | a recorded feature still has unconfirmed or unanswered claims — the one-line \"not a clean result\" summary with all four counts, so a partial record can never read as finished from the notice lines alone; a feature with no record at all never carries it | close each open claim: fix the code and re-run the suite for a failed scenario, re-answer the rest with evidence, then re-record |\n| \\`verify.scenario-attested\\` (warn) | scenario claims were answered on an agent's word (\\`answered_by: agent\\`), so the verdict is **attested**, not verified — nothing gates on it, but say so when you hand back | run the generated suite with a JSON report and re-record with \\`--results report.json\\` the moment a suite exists |\n| \\`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 stay unconfirmed | each service records its own claims from its own repository with \\`--service <id>\\` |\n| \\`verify.operation-contested\\` (warn) | two services on the checklist expose the same operationId, so a contract report — which names no service — cannot say whose suite exercised it; those claims stay unconfirmed | each service records its own with \\`--service <id>\\`, passing its own contract report |\n| \\`verify.checklist-forked\\` (warn) | one or more services answered a DIFFERENT version of the feature's question set than the one it now asks — each attestation carries the \\`checklist\\` digest it answered, and the notice names the ones that do not match the current checklist. Measured against the present, not pairwise: services that all attested against a since-rewritten delta agree with each other perfectly and are all stale. Normal mid-rollout, since services attest as they finish. Attestations written before the field existed carry no digest and are never called stale | re-record the services on the older version from their own repositories (\\`loam verify <FEAT> --service <id> --record\\`), or accept the split knowingly — nothing gates on it |\n| \\`verify.record-miscounted\\` (error) | a verification.yaml whose \\`summary\\` block contradicts its own \\`claims[]\\` — neither half can be believed, so the record is refused as unreadable rather than trusted in either direction | re-record from the service's repo; never edit the counts by hand |\n| \\`verify.evidence-token-missing\\` (warn) | a just-confirmed citation's file at the attested commit does not contain the claim's own token (the operationId, message name or edge op) — the evidence may not show what the answer says | re-read that evidence while the answer can still be corrected; verdict-neutral, it gates nothing |\n| \\`cross.agree-confirmed\\` / \\`cross.agree-unconfirmed\\` (ok) | a \\`--diff-answers\\` row where both blind answer sets reach the same verdict — the cheap-to-skip review queue, though same-model agreement is correlated and proves nothing | nothing on its own; record only the answer set you stand behind, in a separate run |\n| \\`cross.disagree\\` (the rows a human reads first) | a \\`--diff-answers\\` row where the two blind answer sets contradict each other — one of them is wrong about the code | read both cited evidences and decide; the diff writes nothing and never moves a verdict |\n| \\`cross.evidence-disjoint\\` (warn) | a \\`--diff-answers\\` notice: claims BOTH sets confirm while citing non-overlapping files — two yeses that looked at different evidence | read those agreements second, after the disagreements; agreement over disjoint evidence is two guesses, not one proof |\n`,\n};\n\nexport const LOAM_SHIP: CommandContent = {\n  name: \"loam-ship\",\n  description: \"Archive a finished loam feature — merge its deltas into the living docs\",\n  argumentHint: \"<FEAT-id>\",\n  purpose:\n    \"Merge a shipped feature into the living specs, API and landscape. This is the one command that rewrites the source of truth, so every step before it exists to make the merge reviewable before it runs.\",\n  invocation: \"loam instructions loam-ship $1\",\n  placeholders: [\"feature\"],\n  spine: [\n    \"confirm the code is actually built and merged — archiving early makes the docs claim something that does not exist\",\n    \"`loam validate --feature $1` must come back valid; if it says nothing pinned the delta, rebase and re-validate first\",\n    \"`loam archive $1 --dry-run` — read the whole plan and every warning before the merge touches anything\",\n    \"`loam archive $1` for real, and read what it reports it did\",\n    \"`loam unarchive $1` is the undo if the plan turns out to have been wrong\",\n  ],\n  body: `Archive a shipped feature.\n\n1. Confirm the code is actually built and merged. Archiving folds the delta into the\n   living docs; doing it early makes the docs claim something that does not exist.\n   \\`loam status $1 --json\\` answers \"is this actually finished\" in one call, and its\n   \\`next[]\\` names what is outstanding if it is not.\n2. \\`loam validate --feature $1 --json\\` — must come back \\`valid: true\\`.\n   If it reports \\`delta.baseline-missing\\` or \\`openapi.baseline-missing\\`, run\n   \\`loam rebase $1\\` and re-validate BEFORE going on: those two say nothing has\n   pinned what this delta was written against, so the merge cannot tell the text\n   you EDITED from the text you merely restated. Both gate the archive — the\n   dry run in step 3 refuses on them too — and the only way past without the\n   pins is a human's \\`--approve\\`.\n3. \\`loam archive $1 --dry-run --json\\` first. \\`plan[]\\` is every file the merge would\n   write (\\`create\\` / \\`update\\`, then the final \\`move\\` into \\`features/archive/\\`), and\n   none of them are written — read it before letting the merge touch the source of\n   truth, and stop if a file you did not expect is on it. \\`warnings[]\\` is what the\n   merge will do that is legal but lossy — advisory warnings never block, which is\n   exactly why you read them now: \\`openapi.op-modified\\` means an operation the living\n   contract already defines gets overwritten wholesale (\\`openapi.component-modified\\`\n   is the same story for a component the merged operations carry),\n   \\`service.no-model\\` means a service arrives with no C4 centre behind it, and\n   \\`delta.added-conflict\\`\n   means another feature in flight adds the same requirement — the first to archive\n   lands it, and the other's archive is then refused (\\`delta.added-duplicate\\`: its\n   ADDED now collides with the living spec) unless a human \\`--approve\\`s the\n   replacement.\n4. \\`loam archive $1 --json\\`. It merges three axes into the living state — requirements\n   into \\`services/<svc>/spec.md\\`, endpoints into \\`services/<svc>/openapi.yaml\\`,\n   elements and edges into \\`architecture/landscape.likec4\\` and, for an addition nested\n   under a service whose model EXTENDS the map, into that\n   \\`services/<…>/<svc>/model.likec4\\` instead — then moves the feature\n   under \\`features/archive/\\`. Success is \\`ok: true\\`; on \\`ok: false\\`, branch on\n   \\`error.code\\`:\n   - \\`not-coherent\\` — gating coherence issues; \\`issues[]\\` in the envelope lists them,\n     each with \\`gates\\` and \\`overridable\\` resolved (advisory warnings do not block).\n     Fix the breaches. \\`--approve\\` overrides the gating issues and is a human's\n     call to make, not yours: report the breach and stop. Two codes it does not\n     override even then — \\`delta.service-id-invalid\\` (a \\`specs/<svc>/\\` name the\n     id grammar refuses) and \\`c4.service-binding-invalid\\` (a \\`metadata { service }\\`\n     binding it refuses, anywhere inside a tagged element's block): each names a\n     path the merge would write mechanically, they arrive with\n     \\`overridable: false\\`, and the fix is a rename, never the flag.\n     \\`openapi.remove-marker-path-level\\` arrives\n     here too: an \\`x-loam-remove\\` written beside the methods instead of inside the\n     operation retires nothing.\n   - \\`living-outside-requirements\\` — the LIVING spec holds a requirement outside\n     \\`## Requirements\\`, and the merge would duplicate it. Re-home it, then re-run.\n     \\`--approve\\` does not move this one.\n   - \\`archive-exists\\` — \\`features/archive/\\` already has that directory; a human\n     decides what it is.\n   - \\`merge-failed\\` — the merge could not be computed, or failed and was rolled\n     back. Either way the living docs are unchanged; fix the reported cause, re-run.\n     A file loam cannot decode as UTF-8 refuses here by name rather than being\n     rewritten with replacement characters. So does a living document that still\n     holds git conflict markers — the \\`spec.merge-conflict\\` /\n     \\`landscape.merge-conflict\\` findings ride in \\`findings[]\\`, and \\`--approve\\`\n     does not override them: the loss is mechanical, not a judgment call.\n   - \\`docs-busy\\` — another \\`loam archive\\` or \\`loam unarchive\\` holds the docs\n     repo's lock. Nothing was read or written; wait for it and re-run once.\n   - \\`commit-interrupted\\` — a previous archive or unarchive was killed mid-commit\n     and this run cannot repair it on its own: a half-written file was edited\n     since, its pre-image is gone or altered, or \\`.loam-commit\\` cannot be read.\n     Run \\`loam doctor\\` (\\`doctor.commit-interrupted\\` / \\`doctor.commit-unreadable\\`\n     name the same state) and hand it to a human — re-running does not help.\n   - \\`rollback-incomplete\\` — the merge failed AND some files could not be restored.\n     Stop and hand it to a human; the message lists the files to check.\n\nArchived by mistake? \\`loam unarchive $1\\` restores the living docs from the snapshot\narchive left in \\`features/archive/$1*/.loam-before/\\` and re-opens the feature. Do not\nhand-edit the living docs back instead: the previous text of a \\`MODIFIED\\` requirement\nis in that snapshot and nowhere else, so anything you write by hand is a guess. It\nrefuses under \\`snapshot-corrupt\\` when a pre-image's bytes no longer match the digest\nthe archive recorded — \\`--force\\` does not override that one, because the damage is\nto the undo itself — and under \\`snapshot-missing\\` for an archive older than the\ncurrent snapshot format. Both mean version control is the way back.\n`,\n};\n"]}
+{"version":3,"file":"closing.js","sourceRoot":"","sources":["../../../../src/core/agent/workflows/closing.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,qFAAqF;IACvF,YAAY,EAAE,WAAW;IACzB,OAAO,EACL,6NAA6N;IAC/N,UAAU,EAAE,kCAAkC;IAC9C,YAAY,EAAE,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE;QACL,yEAAyE;QACzE,uGAAuG;QACvG,sFAAsF;QACtF,2EAA2E;QAC3E,6FAA6F;KAC9F;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+JP;CACA,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAmB;IACvC,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,yEAAyE;IACtF,YAAY,EAAE,WAAW;IACzB,OAAO,EACL,0MAA0M;IAC5M,UAAU,EAAE,gCAAgC;IAC5C,YAAY,EAAE,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE;QACL,oHAAoH;QACpH,sHAAsH;QACtH,uGAAuG;QACvG,6DAA6D;QAC7D,uGAAuG;QACvG,0EAA0E;KAC3E;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiGP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * The two post-build workflows, paired: the done-check (`loam-verify`) and the\n * merge it precedes (`loam-ship`). One file for two commands because six\n * workflows meet the five-file package cap somewhere, and this is the seam the\n * cycle already has — both describe what happens after the code is built, and\n * each body names the other's refusals (`record-federated`, `not-coherent`).\n */\nexport const LOAM_VERIFY: CommandContent = {\n  name: \"loam-verify\",\n  description:\n    \"Verify a built loam feature against its own promises, claim by claim, with evidence\",\n  argumentHint: \"<FEAT-id>\",\n  purpose:\n    \"Check that the code somebody built is the feature that was designed. loam derives the questions; a test runner and you answer them. loam never reads the service, so a verdict is worth exactly what its evidence is worth.\",\n  invocation: \"loam instructions loam-verify $1\",\n  placeholders: [\"feature\"],\n  spine: [\n    \"`loam verify` — the checklist, derived from the feature's own artifacts\",\n    \"run the generated suite with a JSON report: the scenario claims are the runner's to answer, not yours\",\n    \"answer the remaining claims yourself, every one carrying a `file:line` that resolves\",\n    \"record from each affected service's own repository, bound to that service\",\n    \"read the verdict honestly — a scenario confirmed on your word is `attested`, not `verified`\",\n  ],\n  body: `Check that the code somebody just built is the feature that was designed.\n\nloam derives the questions; the test runner and you answer them. loam never\nreads the service, so a verdict is worth exactly what its evidence is worth.\n\n1. \\`loam verify $1 --json\\`. \\`claims[]\\` is the checklist, derived from the feature's\n   own artifacts — one claim per new service, per operation its openapi delta adds,\n   per (direction, message) its asyncapi delta newly declares against the living\n   contract's send/receive sets (quotes and removals are never questions),\n   per tagged edge that names an operation, and per scenario of every changed\n   requirement, arch.spec.md deltas included. Each has a stable \\`id\\` and a\n   \\`subject\\` (the service whose code answers it); a claim that says arch.spec.md\n   wants an integration/ops test, not an acceptance test. An ARCHIVED feature returns its record as frozen history instead\n   (\\`frozen: true\\`) and \\`--record\\` / \\`--results\\` / \\`--contract-results\\` /\n   \\`--diff-answers\\` refuse it — \\`loam unarchive\\` first if the answers really\n   must change.\n2. The \\`scenario.tested\\` claims are the runner's to answer, not yours. In the\n   service's repo, run the generated suite with a JSON report —\n   \\`npx cucumber-js --format json:report.json\\` (cucumber-jvm, behave,\n   SpecFlow/Reqnroll, pytest-bdd \\`--cucumberjson\\` and godog emit the same\n   format). The generated scenarios carry \\`@loam-digest-…\\` tags that ride into\n   the report; that digest is the match, and the run must have executed every\n   step of the stamped scenario, so never retitle or hand-edit a generated\n   scenario to make one pass. A runner with no cucumber formatter answers\n   through loam's runner-neutral shape instead, keyed by the same digests:\n   \\`{\"loamScenarioReport\": 1, \"results\": [{\"digest\": \"…\", \"status\": \"passed\"}]}\\`.\n   If there is no runnable suite yet you MAY answer them yourself, and the record\n   will say so: \\`answered_by: agent\\` makes the feature **attested**, not verified\n   (\\`verified: false\\`, \\`verdict: \"attested\"\\`, the \\`verify.scenario-attested\\`\n   notice, and a \\`next.verify-attested\\` step in \\`loam status\\`). Nothing gates on\n   it — a legacy service with no suite must still be able to ship — but say so\n   when you hand back, and close it with \\`--results\\` the moment a suite runs.\n   \\`verify.digest-contested\\` (warn) is the case where two services word a\n   scenario identically: they share one digest, so no single report can say whose\n   suite ran it, and each service must record its own with \\`--service\\`.\n   The \\`api.exposes\\` claims have a mechanical channel too, when an API\n   contract-test suite exists: emit loam's contract-results shape from its\n   report — \\`{\"loamContractReport\": 1, \"results\": [{\"operationId\": \"…\",\n   \"status\": \"passed\"}]}\\`, a one-line transform for Specmatic, Pact, Dredd or a\n   property harness — and pass \\`--contract-results contract.json\\` alongside.\n   Only a status of exactly \\`passed\\` confirms the named operation\n   (\\`answered_by: external-runner\\`); anything else, and an operation the report\n   never exercised, stays \\`unconfirmed\\` with the reason, and under the flag the\n   report owns every api.exposes claim, so take those out of the answers file.\n3. Answer every OTHER claim by finding it in the code. Not by reasoning that it\n   must be there — by opening the file:\n   - \\`service.exists\\` — the service is deployable: its build, its entry point.\n   - \\`api.exposes\\` — the route handler serving that operationId, not the spec that\n     declares it — unless a contract-test report already answered it in step 2.\n   - \\`event.declares\\` — the code that puts the message on the wire (sends) or\n     handles it off the wire (receives), not the contract that names it.\n   - \\`c4.calls\\` — the call site in the CALLER.\n4. Write those answers as JSON — evidence is \\`file:line\\`, one entry per place it can\n   be seen:\n   \\`\\`\\`json\n   { \"answers\": [\n     { \"id\": \"<claim id>\", \"verdict\": \"confirmed\", \"evidence\": [\"src/split/Api.ts:42\"] },\n     { \"id\": \"<claim id>\", \"verdict\": \"unconfirmed\", \"note\": \"the split service has no entry point yet\" }\n   ] }\n   \\`\\`\\`\n5. Optional, before recording: cross-examine. Have a SECOND agent answer the\n   same checklist blind — a fresh context, given only \\`loam verify $1 --json\\`\n   and the code, never your answers file — then compare the two sets:\n\n   \\`\\`\\`sh\n   loam verify $1 --diff-answers yours.json theirs.json --json\n   \\`\\`\\`\n\n   Both files must answer EVERY claim in the compared scope,\n   \\`scenario.tested\\` included: the diff consults no test report, so this is a\n   DIFFERENT file from the one step 6 records under \\`--results\\` (that one\n   must omit the runner's claims; a step-6-shaped file here refuses\n   \\`answers-mismatch\\`). Narrowing with \\`--service <id>\\` compares one\n   service's claims — give the second agent the same lens, or its file will\n   not match the compared scope. An archived feature refuses the diff too:\n   frozen history has no current checklist. It writes nothing and changes no\n   verdict: \\`cross.agree-confirmed\\` / \\`cross.agree-unconfirmed\\` rows are the\n   cheap-to-skip queue, \\`disagreements[]\\` (\\`cross.disagree\\`) is what a human\n   reads first, and the \\`cross.evidence-disjoint\\` notice flags agreements\n   citing non-overlapping files — read those second. Agreement between two\n   same-model agents is correlated, so it ranks review; it never upgrades\n   \\`attested\\` to \\`verified\\`. Record only the answer set you stand behind, in\n   a separate run.\n6. Record, **in each affected service's own repository**, one service at a time:\n\n   \\`\\`\\`sh\n   loam verify $1 --service <id> --results report.json [--contract-results contract.json] --record answers.json --json\n   \\`\\`\\`\n\n   \\`--service <id>\\` narrows the checklist to that service's claims and binds the\n   answers to this repository's commit, writing that service's attestation to\n   its OWN file, \\`features/$1/verification/<id>.yaml\\` — the directory is the\n   record, and loam adds the files up when it reads. Running it in the next repo\n   writes that repo's file and touches no other, so two teams' docs PRs never\n   conflict over the record. In a repo whose ./loam.json\n   declares a \\`service\\`, \\`--service\\` may be omitted — it is substituted, and the\n   run still federates. \\`--results report.json\\` alone is legal when the\n   checklist is all scenarios.\n\n   ⚠ **Never run \\`loam verify $1 --record answers.json\\` without \\`--service\\`.**\n   That is the legacy all-at-once form: it writes the WHOLE record from one place,\n   into the one file \\`verification.yaml\\`, and over a record that already carries\n   other services' attestations it is refused (\\`record-federated\\`, naming them)\n   precisely because it would put one unattested answer set over them. If you\n   meet that refusal, re-run with \\`--service\\`; do not work around it.\n\n   The other refusals: \\`answers-mismatch\\` (an id\n   nobody asked about, a claim you left out — re-run step 1, the feature moved —\n   or an answers entry for a \\`scenario.tested\\` claim: the runner owns those),\n   \\`answers-unevidenced\\` (a \\`confirmed\\` with nothing behind it),\n   \\`answers-unreadable\\` (a report or answers file it cannot read),\n   \\`record-unreadable\\` (a record file that exists but cannot be read — broken\n   YAML, git conflict markers a merge left, or \\`verify.record-miscounted\\` when\n   its \\`summary\\` block contradicts its own \\`claims[]\\`. It is never overwritten,\n   and the message names the file and the safe repair: a service's own\n   \\`verification/<id>.yaml\\` holds only that service's word, so that service\n   may delete it and record again; the one-file \\`verification.yaml\\` may hold\n   other services' attestations, so it is repaired or restored from version\n   control — after a merge, the copy on the branch you merged into — and\n   **never deleted**. Never edit the counts to make them agree),\n   \\`service-mismatch\\` (\\`--service\\` names a service this repo does not declare) and\n   \\`repository-unavailable\\` (\\`--service\\` from a repo that declares none, or whose\n   commit cannot be read — an attestation must be bound to the code it is about).\n7. Report every \\`unconfirmed\\` claim and what it would take to close it, and read\n   \\`discarded\\` in the payload: it names every previous answer the new record does\n   not carry, and each one is either evidence that went stale or evidence that was\n   just dropped. A scenario claim the report failed or missed closes by fixing the\n   code and re-running the suite — never by editing the generated .feature. While\n   any claim stays unconfirmed or unanswered, \\`notices[]\\` carries\n   \\`verify.claims-open\\` (warn, gating nothing): the one-line \"not a clean\n   result\" summary with all four counts, so a partial record can never read as a\n   finished one from the notice lines alone.\n8. Reading is safe from anywhere: \\`loam verify $1 --service <id> --json\\` without\n   \\`--record\\` writes nothing and works from the docs repo too. \\`services\\` lists\n   every subject of the checklist, so it is how you find out which repos still\n   owe an attestation, and \\`loam status $1 --json\\` says the same thing in the\n   shape of a next step.\n\nAnything you cannot show is \\`unconfirmed\\` with a note. That is a successful record,\nand it is the useful one: nothing gates on this file, so the only thing it is for is\ntelling the next reader the truth. \\`loam archive\\` will ship the feature either way —\nwhich is exactly why a \\`confirmed\\` you cannot back up costs nothing now and misleads\neveryone later.\n\n\\`loam verify\\` — the notice and record codes its reports carry in \\`notices[]\\`,\ngathered from the steps above; branch on the code, never the prose:\n\n| code | what it means | what to do |\n|---|---|---|\n| \\`verify.claims-open\\` (warn) | a recorded feature still has unconfirmed or unanswered claims — the one-line \"not a clean result\" summary with all four counts, so a partial record can never read as finished from the notice lines alone; a feature with no record at all never carries it | close each open claim: fix the code and re-run the suite for a failed scenario, re-answer the rest with evidence, then re-record |\n| \\`verify.scenario-attested\\` (warn) | scenario claims were answered on an agent's word (\\`answered_by: agent\\`), so the verdict is **attested**, not verified — nothing gates on it, but say so when you hand back | run the generated suite with a JSON report and re-record with \\`--results report.json\\` the moment a suite exists |\n| \\`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 stay unconfirmed | each service records its own claims from its own repository with \\`--service <id>\\` |\n| \\`verify.operation-contested\\` (warn) | two services on the checklist expose the same operationId, so a contract report — which names no service — cannot say whose suite exercised it; those claims stay unconfirmed | each service records its own with \\`--service <id>\\`, passing its own contract report |\n| \\`verify.checklist-forked\\` (warn) | one or more services answered a DIFFERENT version of the feature's question set than the one it now asks — each attestation carries the \\`checklist\\` digest it answered, and the notice names the ones that do not match the current checklist. Measured against the present, not pairwise: services that all attested against a since-rewritten delta agree with each other perfectly and are all stale. Normal mid-rollout, since services attest as they finish. Attestations written before the field existed carry no digest and are never called stale. In a per-service record the answers of the services named do not count until they record again | re-record the services on the older version from their own repositories (\\`loam verify <FEAT> --service <id> --record\\`) — nothing gates on it |\n| \\`verify.record-miscounted\\` (error) | a record file whose \\`summary\\` block contradicts its own \\`claims[]\\` — neither half can be believed, so the record is refused as unreadable rather than trusted in either direction | a service's own \\`verification/<id>.yaml\\`: delete it and re-record from that service's repo; the one-file \\`verification.yaml\\`: restore it from version control, then re-record — never delete it, and never edit the counts by hand |\n| \\`verify.evidence-token-missing\\` (warn) | a just-confirmed citation's file at the attested commit does not contain the claim's own token (the operationId, message name or edge op) — the evidence may not show what the answer says | re-read that evidence while the answer can still be corrected; verdict-neutral, it gates nothing |\n| \\`cross.agree-confirmed\\` / \\`cross.agree-unconfirmed\\` (ok) | a \\`--diff-answers\\` row where both blind answer sets reach the same verdict — the cheap-to-skip review queue, though same-model agreement is correlated and proves nothing | nothing on its own; record only the answer set you stand behind, in a separate run |\n| \\`cross.disagree\\` (the rows a human reads first) | a \\`--diff-answers\\` row where the two blind answer sets contradict each other — one of them is wrong about the code | read both cited evidences and decide; the diff writes nothing and never moves a verdict |\n| \\`cross.evidence-disjoint\\` (warn) | a \\`--diff-answers\\` notice: claims BOTH sets confirm while citing non-overlapping files — two yeses that looked at different evidence | read those agreements second, after the disagreements; agreement over disjoint evidence is two guesses, not one proof |\n`,\n};\n\nexport const LOAM_SHIP: CommandContent = {\n  name: \"loam-ship\",\n  description: \"Archive a finished loam feature — merge its deltas into the living docs\",\n  argumentHint: \"<FEAT-id>\",\n  purpose:\n    \"Merge a shipped feature into the living specs, API and landscape. This is the one command that rewrites the source of truth, so every step before it exists to make the merge reviewable before it runs.\",\n  invocation: \"loam instructions loam-ship $1\",\n  placeholders: [\"feature\"],\n  spine: [\n    \"confirm the code is actually built and merged — archiving early makes the docs claim something that does not exist\",\n    \"`loam validate --feature $1` must come back valid; if it says nothing pinned the delta, rebase and re-validate first\",\n    \"`loam archive $1 --dry-run` — read the whole plan and every warning before the merge touches anything\",\n    \"`loam archive $1` for real, and read what it reports it did\",\n    \"every vouched spec on `revouchOwed[]` owes its owner's re-vouch — tell them; it lands in this same PR\",\n    \"`loam unarchive $1` is the undo if the plan turns out to have been wrong\",\n  ],\n  body: `Archive a shipped feature.\n\n1. Confirm the code is actually built and merged. Archiving folds the delta into the\n   living docs; doing it early makes the docs claim something that does not exist.\n   \\`loam status $1 --json\\` answers \"is this actually finished\" in one call, and its\n   \\`next[]\\` names what is outstanding if it is not.\n2. \\`loam validate --feature $1 --json\\` — must come back \\`valid: true\\`.\n   If it reports \\`delta.baseline-missing\\` or \\`openapi.baseline-missing\\`, run\n   \\`loam rebase $1\\` and re-validate BEFORE going on: those two say nothing has\n   pinned what this delta was written against, so the merge cannot tell the text\n   you EDITED from the text you merely restated. Both gate the archive — the\n   dry run in step 3 refuses on them too — and the only way past without the\n   pins is a human's \\`--approve\\`.\n3. \\`loam archive $1 --dry-run --json\\` first. \\`plan[]\\` is every file the merge would\n   write (\\`create\\` / \\`update\\`, then the final \\`move\\` into \\`features/archive/\\`), and\n   none of them are written — read it before letting the merge touch the source of\n   truth, and stop if a file you did not expect is on it. \\`warnings[]\\` is what the\n   merge will do that is legal but lossy — advisory warnings never block, which is\n   exactly why you read them now: \\`openapi.op-modified\\` means an operation the living\n   contract already defines gets overwritten wholesale, and its \\`details\\` name the\n   current consumers that overwrite lands on (\\`asyncapi.message-modified\\` likewise for\n   a message; \\`openapi.component-modified\\` is the same story for a component the\n   merged operations carry, with no consumer list),\n   \\`service.no-model\\` means a service arrives with no C4 centre behind it, and\n   \\`delta.added-conflict\\`\n   means another feature in flight adds the same requirement — the first to archive\n   lands it, and the other's archive is then refused (\\`delta.added-duplicate\\`: its\n   ADDED now collides with the living spec) unless a human \\`--approve\\`s the\n   replacement.\n4. \\`loam archive $1 --json\\`. It merges three axes into the living state — requirements\n   into \\`services/<svc>/spec.md\\`, endpoints into \\`services/<svc>/openapi.yaml\\`,\n   elements and edges into \\`architecture/landscape.likec4\\` and, for an addition nested\n   under a service whose model EXTENDS the map, into that\n   \\`services/<…>/<svc>/model.likec4\\` instead — then moves the feature\n   under \\`features/archive/\\`, whole: its verification record travels with it,\n   the per-service \\`verification/<id>.yaml\\` files and any one-file\n   \\`verification.yaml\\` alike, and \\`loam verify $1\\` reads it back afterwards as\n   frozen history. Verification never gates the archive — an open or missing\n   record ships as exactly that. Success is \\`ok: true\\`; on \\`ok: false\\`, branch on\n   \\`error.code\\`:\n   - \\`not-coherent\\` — gating coherence issues; \\`issues[]\\` in the envelope lists them,\n     each with \\`gates\\` and \\`overridable\\` resolved (advisory warnings do not block).\n     Fix the breaches. \\`--approve\\` overrides the gating issues and is a human's\n     call to make, not yours: report the breach and stop. Two codes it does not\n     override even then — \\`delta.service-id-invalid\\` (a \\`specs/<svc>/\\` name the\n     id grammar refuses) and \\`c4.service-binding-invalid\\` (a \\`metadata { service }\\`\n     binding it refuses, anywhere inside a tagged element's block): each names a\n     path the merge would write mechanically, they arrive with\n     \\`overridable: false\\`, and the fix is a rename, never the flag.\n     \\`openapi.remove-marker-path-level\\` arrives\n     here too: an \\`x-loam-remove\\` written beside the methods instead of inside the\n     operation retires nothing. So do \\`openapi.op-revived\\` and\n     \\`asyncapi.slot-revived\\`: the delta spells an operation, slot or message an\n     ARCHIVED feature retired, and the merge would put it back. If the delta only\n     quoted it, delete the quote; whether the feature brings it back on purpose is\n     the human's \\`--approve\\`, and the archive output then names what came back\n     and whose retirement it reverses.\n   - \\`living-outside-requirements\\` — the LIVING spec holds a requirement outside\n     \\`## Requirements\\`, and the merge would duplicate it. Re-home it, then re-run.\n     \\`--approve\\` does not move this one.\n   - \\`archive-exists\\` — \\`features/archive/\\` already has that directory; a human\n     decides what it is.\n   - \\`merge-failed\\` — the merge could not be computed, or failed and was rolled\n     back. Either way the living docs are unchanged; fix the reported cause, re-run.\n     A file loam cannot decode as UTF-8 refuses here by name rather than being\n     rewritten with replacement characters. So does a living document that still\n     holds git conflict markers — the \\`spec.merge-conflict\\` /\n     \\`landscape.merge-conflict\\` findings ride in \\`findings[]\\`, and \\`--approve\\`\n     does not override them: the loss is mechanical, not a judgment call.\n   - \\`docs-busy\\` — another \\`loam archive\\` or \\`loam unarchive\\` holds the docs\n     repo's lock. Nothing was read or written; wait for it and re-run once.\n   - \\`commit-interrupted\\` — a previous archive or unarchive was killed mid-commit\n     and this run cannot repair it on its own: a half-written file was edited\n     since, its pre-image is gone or altered, or \\`.loam-commit\\` cannot be read.\n     Run \\`loam doctor\\` (\\`doctor.commit-interrupted\\` / \\`doctor.commit-unreadable\\`\n     name the same state) and hand it to a human — re-running does not help.\n   - \\`rollback-incomplete\\` — the merge failed AND some files could not be restored.\n     Stop and hand it to a human; the message lists the files to check.\n5. Re-vouches are owed. \\`revouchOwed[]\\` — on the dry run and the real merge alike —\n   names every VOUCHED spec the merge moves under its vouch stamp, with the\n   document's \\`owner\\`. \\`content.stale\\` follows on each, and honestly: the merged\n   text is words nobody has yet read against the code. You cannot clear it — a\n   vouch is a person's, run in that service's own repo (\\`loam vouch --service <id>\\`,\n   after \\`loam vouch --pack --service <id>\\` for what to re-read). Name the\n   documents and owners in your hand-back, and say the re-vouches belong in the\n   SAME PR as this archive: a docs repo gated on\n   \\`loam validate --all --base <ref> --strict\\` keeps the archive's PR red until they\n   land. Never edit a stamp by hand to turn it green.\n\nArchived by mistake? \\`loam unarchive $1\\` restores the living docs from the snapshot\narchive left in \\`features/archive/$1*/.loam-before/\\` and re-opens the feature. Do not\nhand-edit the living docs back instead: the previous text of a \\`MODIFIED\\` requirement\nis in that snapshot and nowhere else, so anything you write by hand is a guess. It\nrefuses under \\`snapshot-corrupt\\` when a pre-image's bytes no longer match the digest\nthe archive recorded — \\`--force\\` does not override that one, because the damage is\nto the undo itself — and under \\`snapshot-missing\\` for an archive older than the\ncurrent snapshot format. Both mean version control is the way back.\n`,\n};\n"]}

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

@@ -8,16 +8,41 @@ export const LOAM_FEATURE = {
     // $2 is the feature's human title: any string is a legal one.
     placeholders: ["feature", "free"],
     spine: [
+        "decide whether this is a feature at all — a change that touches no requirement, operation or edge needs none",
         "read `AGENTS.md` at the docs repo root — it defines the ID spine everything else depends on",
         "`loam explore` around the services you think are involved: the ring one hop out, and what is already in flight over the same ground",
         "`loam status` / `loam list` / `loam show` — what exists and what is already owed",
         "`loam new` with a `--touches` per service it changes and a `--new-service` per service it introduces",
         "author what the templates left as TODO: intent, the C4 delta, the per-service spec / arch spec / openapi",
-        "`loam rebase` — pin every MODIFIED requirement and every operation to the living version you wrote against",
+        "analyze before you pin — write what the documents leave open under `## Open questions` in intent.md, for a human to answer",
+        "`loam rebase` — pin every MODIFIED requirement and every living operation you edited to the version you wrote against",
         "validate the feature, then read `loam dependencies` before anyone starts building",
     ],
+    // Step 0 and step 4b are the two this protocol was missing, and neither is
+    // graded — on purpose. Step 0 exists because the lightest lane loam has (no
+    // feature at all, for a change that moves no requirement, operation or edge)
+    // was true and written down nowhere, so the work that is most of a legacy
+    // fleet's week either walked the whole feature cycle or routed around loam.
+    // Step 4b exists because every check after it is a join between exact
+    // tokens: two services that agree on every operationId and disagree on what
+    // it means (one confirms a split the other answers 422 for) validate, archive
+    // and ship green, and a `Realizes:` whose requirement does not deliver the
+    // promise reads as a clean join. Nothing in the binary can read meaning, and
+    // a check pretending to would be the false green this tool exists to refuse,
+    // so the step asks for questions and leaves the answers to a person.
     body: `Start a new feature in the loam docs repo (its path is \`docsDir\` in ./loam.json).
 
+0. First decide whether this needs a feature at all. A change that touches no
+   requirement, no operation and no fleet edge — a refactor, a dependency bump,
+   a fix that brings the code back to behaviour the living spec already
+   documents — needs NONE: nothing in the docs repo changes, so there is nothing
+   to scaffold, pin or archive. It is a code PR in the service repo, then
+   \`loam validate --service <id>\` there (the service repo is the only place
+   \`sources.stale\` is visible), then \`loam vouch --pack --service <id>\` to
+   prepare the re-read the moved sources owe — the vouch itself is a human's.
+   If the change alters what a requirement promises, it IS a feature, however
+   small: one \`--touches\`, a Why, the ADDED/MODIFIED requirement, and
+   \`loam rebase\` for a MODIFIED one — the rest of this page still applies.
 1. Read \`AGENTS.md\` at the root of the docs repo first — it defines the ID spine
    everything here depends on.
 2. Understand the current state before proposing a change:
@@ -71,20 +96,63 @@ export const LOAM_FEATURE = {
    - \`specs/<svc>/arch.spec.md\` — the architectural obligations (outbox, retries,
      idempotency, alerts), same grammar; a \`Covers:\` line per requirement naming the
      tagged elements/edges it accounts for, or \`c4.uncovered\` says nothing does
-   - \`specs/<svc>/openapi.yaml\` — define every operationId the edges reference
+   - \`specs/<svc>/openapi.yaml\` — define every operationId the edges reference.
+     A self-contained document holding ONLY the operations this feature adds,
+     changes or removes — never a copy of the living contract. An operation you
+     leave out stays exactly as the living contract has it, and a local \`$ref\`
+     (\`#/components/schemas/Order\`) resolves into the living document, so there
+     is nothing to restate. Every operation you quote costs a pin, and once a
+     parallel feature retires it — or moves it, and you quoted the old
+     address — a pinned quote is \`openapi.baseline-invalid\` and
+     \`openapi.op-revived\` both, an unpinned one \`openapi.op-revived\` alone
+     (\`asyncapi.slot-revived\` on the event axis) — archive refuses either.
+     Delete the quote; only a feature that MEANS to bring a retired operation
+     back keeps it, and archives past the finding with a human's \`--approve\`
    - \`specs/<svc>/asyncapi.yaml\` — the event axis, only when the feature changes
-     what a service puts on or takes off the bus: a complete AsyncAPI 3.0
-     document restating the living contract around the slots you change, new
-     messages under \`components.messages\`, and a \`Publishes:\`/\`Consumes:\` line
-     on each requirement that names them. \`loam new\` scaffolds none — an event
+     what a service puts on or takes off the bus: an AsyncAPI 3.0 document
+     holding only the channel, operation and message slots you add, change or
+     remove (an edited slot is written out whole), new messages under
+     \`components.messages\`, and a \`Publishes:\`/\`Consumes:\` line on each
+     requirement that names them. \`loam new\` scaffolds none — an event
      contract is genuinely optional
+4b. **Analyze before you pin.** Nothing grades this step, which is why it is here:
+   every check after it is a join between exact tokens, so two services that
+   agree on every operationId and disagree on what it means validate, archive
+   and ship green. Read the feature as its reviewer will, before rebase freezes it:
+   - \`loam show $1 --json\` — its \`review\` object joins the intent, the C4
+     objects, the API/event slices and the dependencies
+   - \`loam context <service> --feature $1 --json\` for every service it touches —
+     the living requirements verbatim, the edges one hop out, and this delta
+   - the \`neighbours\` step 2b's \`loam explore\` reported
+   Then write what the documents leave open under \`## Open questions\` in
+   \`intent.md\` (the scaffold already carries the heading), one line per question,
+   naming the requirement id or edge it is about:
+   - a SHALL two engineers could build two ways — an unstated unit, bound,
+     ordering, or an "eventually" with no window
+   - a value, limit or window two services state differently (a refund window,
+     a rounding rule, a retry budget), and which side refuses when they
+     disagree — a caller that accepts what its provider answers 4xx for is a
+     contradiction no check can see
+   - a \`Realizes:\` line whose requirement does not actually deliver the
+     capability promise it names, or a promise this feature changes that no
+     realizing requirement keeps
+   - per call edge in the delta: the timeout, the retry and what makes it safe
+     to repeat, what a partial failure leaves behind, and what compensates it —
+     an edge no requirement answers these for is a question, not a default
+   - each \`explore\` neighbour outside \`--touches\`: why it is untouched, or that
+     it is a candidate — adding one means a \`specs/<svc>/\` delta in this feature,
+     because that directory IS the feature's service list
+   Ask; do not answer for the author. A human answers by editing the file —
+   replacing a question with the decision, or with a change to the delta.
+   Nothing is graded: an empty section is legal, and so is an answered one.
 5. **\`loam rebase $1\`** — the step between authoring and checking, and the one that
    stops two features in flight from silently deleting each other's work. It pins
-   every MODIFIED/REMOVED requirement (\`Based-On:\`), every operation in the
-   contract delta and every asyncapi channel/operation/message slot
-   (\`x-loam-based-on\`) to the living version you wrote against.
-   Run it on the contract axes even if you changed exactly one endpoint: that is
-   what marks the REST of the document as quotation the merge must not write back.
+   every MODIFIED/REMOVED requirement (\`Based-On:\`), and every operation and
+   asyncapi channel/operation/message slot the living contract already holds
+   (\`x-loam-based-on\`), to the living version you wrote against. What the
+   feature ADDS has no living version and takes no pin, so an add-only contract
+   delta needs no rebase. Any living operation or slot the delta spells is one
+   the merge upserts, so it needs its pin even when you changed one line of it.
    Without the pins, \`delta.baseline-missing\` / \`openapi.baseline-missing\` /
    \`asyncapi.baseline-missing\` GATE
    the archive: before they did, the second feature to archive reverted the

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

@@ -1 +1 @@
-{"version":3,"file":"feature.js","sourceRoot":"","sources":["../../../../src/core/agent/workflows/feature.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,MAAM,CAAC,MAAM,YAAY,GAAmB;IAC1C,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,yFAAyF;IAC3F,YAAY,EAAE,qBAAqB;IACnC,OAAO,EACL,uQAAuQ;IACzQ,UAAU,EAAE,wCAAwC;IACpD,8DAA8D;IAC9D,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC;IACjC,KAAK,EAAE;QACL,6FAA6F;QAC7F,qIAAqI;QACrI,kFAAkF;QAClF,sGAAsG;QACtG,0GAA0G;QAC1G,4GAA4G;QAC5G,mFAAmF;KACpF;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoFP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/** Starting a feature: explore, scaffold, author the three axes, rebase, validate. */\nexport const LOAM_FEATURE: CommandContent = {\n  name: \"loam-feature\",\n  description:\n    \"Start a new loam feature — scaffold it, then author the C4 delta and requirement deltas\",\n  argumentHint: `<FEAT-id> \"<title>\"`,\n  purpose:\n    \"Start a feature in the docs repo: decide which services it touches, scaffold it, then author the C4 delta and one requirement delta per service. The `--touches` list is the hardest call in the cycle and nothing downstream catches one that is short by a service.\",\n  invocation: 'loam instructions loam-feature $1 \"$2\"',\n  // $2 is the feature's human title: any string is a legal one.\n  placeholders: [\"feature\", \"free\"],\n  spine: [\n    \"read `AGENTS.md` at the docs repo root — it defines the ID spine everything else depends on\",\n    \"`loam explore` around the services you think are involved: the ring one hop out, and what is already in flight over the same ground\",\n    \"`loam status` / `loam list` / `loam show` — what exists and what is already owed\",\n    \"`loam new` with a `--touches` per service it changes and a `--new-service` per service it introduces\",\n    \"author what the templates left as TODO: intent, the C4 delta, the per-service spec / arch spec / openapi\",\n    \"`loam rebase` — pin every MODIFIED requirement and every operation to the living version you wrote against\",\n    \"validate the feature, then read `loam dependencies` before anyone starts building\",\n  ],\n  body: `Start a new feature in the loam docs repo (its path is \\`docsDir\\` in ./loam.json).\n\n1. Read \\`AGENTS.md\\` at the root of the docs repo first — it defines the ID spine\n   everything here depends on.\n2. Understand the current state before proposing a change:\n   - \\`loam status --json\\` — what is already in flight and what it is waiting on.\n     Run this FIRST if you joined this repository halfway or lost the session:\n     \\`next[]\\` is ordered and each entry carries the literal command to run, so it\n     tells you whether the work is to start $1 at all. \\`loam status $1 --json\\`\n     narrows it to one feature once $1 exists\n   - \\`loam list --json\\` — what services exist, and what documentation they are missing\n   - \\`loam show <service> --json\\` — what a service owns, exposes, and who already calls it\n2b. \\`loam explore <service> --json --as $1\\` around every service you believe this\n   feature touches. This is the step that decides step 3's \\`--touches\\` list, and it\n   is the only decision in the cycle nothing downstream catches — a list short by one\n   service produces a feature that validates, archives and ships with a consumer\n   nobody updated. Read four fields:\n   - \\`neighbours\\` — the services one hop out in the fleet map. Weigh each one. loam\n     knows they are connected, not whether you change them, and it deliberately\n     leaves them OUT of the suggested command line rather than guessing for you\n   - \\`services[].maturity\\` — a service at \\`empty\\` or \\`partial\\` has no baseline to\n     write a delta against, so the work starts with \\`loam adopt --service <id>\\`, not\n     with this feature\n   - \\`services[].operations\\` — what each already exposes, so an operation you are\n     about to \"add\" that is already there becomes a MODIFIED requirement instead\n   - \\`overlaps\\` — active features already carrying a delta for these services.\n     \\`loam dependencies --json\\` (step 7) then says which must archive first\n   \\`--op <operationId>\\` seeds from an operation when you know the call but not who\n   owns it. A seed naming no \\`services/<id>/\\` is reported in \\`unknown\\` with the\n   closest real ids rather than refused — the feature may be introducing it, and a\n   typo looks identical until you read that list. \\`scaffold\\` is the literal step-3\n   command line the seeds imply, with \\`--new-service\\` where the service does not\n   exist yet.\n3. Scaffold it: \\`loam new $1 --title \"$2\"\\`, adding \\`--touches <id>\\` for every service the\n   feature touches and \\`--new-service <id>\\` for every one it introduces. Every id goes\n   through the \\`services/<id>/\\` grammar, so a typo is refused (\\`invalid-option\\`)\n   rather than scaffolded; a \\`--touches\\` that matches nothing existing comes back as\n   a \\`note\\` with the close ids, not as a failure — read it, because a \\`--touches\\`\n   naming a service that does not exist is \\`delta.service-unknown\\` at validate time\n   and a phantom \\`services/<typo>/\\` directory if it ever archives.\n4. Author what the templates left as TODO. This step is gated, not advisory:\n   \\`loam archive\\` refuses a scaffold nobody edited (\\`scaffold.placeholder\\`,\n   \\`intent.empty\\`), so the placeholder text cannot reach the living docs.\n   - \\`intent.md\\` — the problem in business terms, in prose; the scaffold's\n     comment-only Why/Scope count as unwritten\n   - \\`delta.likec4\\` — new elements and edges, each tagged \\`#$1\\`; every call edge carries\n     \\`metadata { op '<operationId>' }\\`; replace the scaffolded TODO description on each\n     new service. For a requirements-only feature DELETE this\n     file: an empty delta is legal, but a scaffold left half-filled is not\n   - \\`specs/<svc>/spec.md\\` — the example requirement ships INSIDE the template's\n     comment: copy it out, unindent, one behaviour per requirement, SHALL, at\n     least one Given/When/Then scenario; add \\`Operations:\\` once the operation exists\n   - \\`specs/<svc>/arch.spec.md\\` — the architectural obligations (outbox, retries,\n     idempotency, alerts), same grammar; a \\`Covers:\\` line per requirement naming the\n     tagged elements/edges it accounts for, or \\`c4.uncovered\\` says nothing does\n   - \\`specs/<svc>/openapi.yaml\\` — define every operationId the edges reference\n   - \\`specs/<svc>/asyncapi.yaml\\` — the event axis, only when the feature changes\n     what a service puts on or takes off the bus: a complete AsyncAPI 3.0\n     document restating the living contract around the slots you change, new\n     messages under \\`components.messages\\`, and a \\`Publishes:\\`/\\`Consumes:\\` line\n     on each requirement that names them. \\`loam new\\` scaffolds none — an event\n     contract is genuinely optional\n5. **\\`loam rebase $1\\`** — the step between authoring and checking, and the one that\n   stops two features in flight from silently deleting each other's work. It pins\n   every MODIFIED/REMOVED requirement (\\`Based-On:\\`), every operation in the\n   contract delta and every asyncapi channel/operation/message slot\n   (\\`x-loam-based-on\\`) to the living version you wrote against.\n   Run it on the contract axes even if you changed exactly one endpoint: that is\n   what marks the REST of the document as quotation the merge must not write back.\n   Without the pins, \\`delta.baseline-missing\\` / \\`openapi.baseline-missing\\` /\n   \\`asyncapi.baseline-missing\\` GATE\n   the archive: before they did, the second feature to archive reverted the\n   first — with \\`+0 ~1 -0\\`, exit 0, and nobody told. Rebase clears them; a\n   human's \\`--approve\\` is the only other way past.\n   Restamping is not resolving: if rebase reports a requirement as MOVED, re-read\n   the living text and fold in what you still mean BEFORE you ship.\n6. \\`loam validate --feature $1 --json\\`. Do not stop while \\`valid\\` is false.\n7. \\`loam dependencies $1 --json\\` before anyone starts building: it says which\n   features in flight have to archive first (\\`order\\`) and which collisions no\n   ordering fixes (\\`conflicts\\`, \\`cycles\\`). Every conflict it names is one \\`loam rebase\\`\n   cannot fix for you — two intentions have to be merged by people.\n\nThe operation's three spellings — the edge's \\`op\\`, the requirement's \\`Operations:\\`\nline, and the OpenAPI \\`operationId\\` — must match exactly.\n`,\n};\n"]}
+{"version":3,"file":"feature.js","sourceRoot":"","sources":["../../../../src/core/agent/workflows/feature.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,MAAM,CAAC,MAAM,YAAY,GAAmB;IAC1C,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,yFAAyF;IAC3F,YAAY,EAAE,qBAAqB;IACnC,OAAO,EACL,uQAAuQ;IACzQ,UAAU,EAAE,wCAAwC;IACpD,8DAA8D;IAC9D,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC;IACjC,KAAK,EAAE;QACL,8GAA8G;QAC9G,6FAA6F;QAC7F,qIAAqI;QACrI,kFAAkF;QAClF,sGAAsG;QACtG,0GAA0G;QAC1G,4HAA4H;QAC5H,uHAAuH;QACvH,mFAAmF;KACpF;IACD,2EAA2E;IAC3E,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,4EAA4E;IAC5E,sEAAsE;IACtE,4EAA4E;IAC5E,8EAA8E;IAC9E,2EAA2E;IAC3E,6EAA6E;IAC7E,6EAA6E;IAC7E,qEAAqE;IACrE,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0IP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/** Starting a feature: explore, scaffold, author the three axes, rebase, validate. */\nexport const LOAM_FEATURE: CommandContent = {\n  name: \"loam-feature\",\n  description:\n    \"Start a new loam feature — scaffold it, then author the C4 delta and requirement deltas\",\n  argumentHint: `<FEAT-id> \"<title>\"`,\n  purpose:\n    \"Start a feature in the docs repo: decide which services it touches, scaffold it, then author the C4 delta and one requirement delta per service. The `--touches` list is the hardest call in the cycle and nothing downstream catches one that is short by a service.\",\n  invocation: 'loam instructions loam-feature $1 \"$2\"',\n  // $2 is the feature's human title: any string is a legal one.\n  placeholders: [\"feature\", \"free\"],\n  spine: [\n    \"decide whether this is a feature at all — a change that touches no requirement, operation or edge needs none\",\n    \"read `AGENTS.md` at the docs repo root — it defines the ID spine everything else depends on\",\n    \"`loam explore` around the services you think are involved: the ring one hop out, and what is already in flight over the same ground\",\n    \"`loam status` / `loam list` / `loam show` — what exists and what is already owed\",\n    \"`loam new` with a `--touches` per service it changes and a `--new-service` per service it introduces\",\n    \"author what the templates left as TODO: intent, the C4 delta, the per-service spec / arch spec / openapi\",\n    \"analyze before you pin — write what the documents leave open under `## Open questions` in intent.md, for a human to answer\",\n    \"`loam rebase` — pin every MODIFIED requirement and every living operation you edited to the version you wrote against\",\n    \"validate the feature, then read `loam dependencies` before anyone starts building\",\n  ],\n  // Step 0 and step 4b are the two this protocol was missing, and neither is\n  // graded — on purpose. Step 0 exists because the lightest lane loam has (no\n  // feature at all, for a change that moves no requirement, operation or edge)\n  // was true and written down nowhere, so the work that is most of a legacy\n  // fleet's week either walked the whole feature cycle or routed around loam.\n  // Step 4b exists because every check after it is a join between exact\n  // tokens: two services that agree on every operationId and disagree on what\n  // it means (one confirms a split the other answers 422 for) validate, archive\n  // and ship green, and a `Realizes:` whose requirement does not deliver the\n  // promise reads as a clean join. Nothing in the binary can read meaning, and\n  // a check pretending to would be the false green this tool exists to refuse,\n  // so the step asks for questions and leaves the answers to a person.\n  body: `Start a new feature in the loam docs repo (its path is \\`docsDir\\` in ./loam.json).\n\n0. First decide whether this needs a feature at all. A change that touches no\n   requirement, no operation and no fleet edge — a refactor, a dependency bump,\n   a fix that brings the code back to behaviour the living spec already\n   documents — needs NONE: nothing in the docs repo changes, so there is nothing\n   to scaffold, pin or archive. It is a code PR in the service repo, then\n   \\`loam validate --service <id>\\` there (the service repo is the only place\n   \\`sources.stale\\` is visible), then \\`loam vouch --pack --service <id>\\` to\n   prepare the re-read the moved sources owe — the vouch itself is a human's.\n   If the change alters what a requirement promises, it IS a feature, however\n   small: one \\`--touches\\`, a Why, the ADDED/MODIFIED requirement, and\n   \\`loam rebase\\` for a MODIFIED one — the rest of this page still applies.\n1. Read \\`AGENTS.md\\` at the root of the docs repo first — it defines the ID spine\n   everything here depends on.\n2. Understand the current state before proposing a change:\n   - \\`loam status --json\\` — what is already in flight and what it is waiting on.\n     Run this FIRST if you joined this repository halfway or lost the session:\n     \\`next[]\\` is ordered and each entry carries the literal command to run, so it\n     tells you whether the work is to start $1 at all. \\`loam status $1 --json\\`\n     narrows it to one feature once $1 exists\n   - \\`loam list --json\\` — what services exist, and what documentation they are missing\n   - \\`loam show <service> --json\\` — what a service owns, exposes, and who already calls it\n2b. \\`loam explore <service> --json --as $1\\` around every service you believe this\n   feature touches. This is the step that decides step 3's \\`--touches\\` list, and it\n   is the only decision in the cycle nothing downstream catches — a list short by one\n   service produces a feature that validates, archives and ships with a consumer\n   nobody updated. Read four fields:\n   - \\`neighbours\\` — the services one hop out in the fleet map. Weigh each one. loam\n     knows they are connected, not whether you change them, and it deliberately\n     leaves them OUT of the suggested command line rather than guessing for you\n   - \\`services[].maturity\\` — a service at \\`empty\\` or \\`partial\\` has no baseline to\n     write a delta against, so the work starts with \\`loam adopt --service <id>\\`, not\n     with this feature\n   - \\`services[].operations\\` — what each already exposes, so an operation you are\n     about to \"add\" that is already there becomes a MODIFIED requirement instead\n   - \\`overlaps\\` — active features already carrying a delta for these services.\n     \\`loam dependencies --json\\` (step 7) then says which must archive first\n   \\`--op <operationId>\\` seeds from an operation when you know the call but not who\n   owns it. A seed naming no \\`services/<id>/\\` is reported in \\`unknown\\` with the\n   closest real ids rather than refused — the feature may be introducing it, and a\n   typo looks identical until you read that list. \\`scaffold\\` is the literal step-3\n   command line the seeds imply, with \\`--new-service\\` where the service does not\n   exist yet.\n3. Scaffold it: \\`loam new $1 --title \"$2\"\\`, adding \\`--touches <id>\\` for every service the\n   feature touches and \\`--new-service <id>\\` for every one it introduces. Every id goes\n   through the \\`services/<id>/\\` grammar, so a typo is refused (\\`invalid-option\\`)\n   rather than scaffolded; a \\`--touches\\` that matches nothing existing comes back as\n   a \\`note\\` with the close ids, not as a failure — read it, because a \\`--touches\\`\n   naming a service that does not exist is \\`delta.service-unknown\\` at validate time\n   and a phantom \\`services/<typo>/\\` directory if it ever archives.\n4. Author what the templates left as TODO. This step is gated, not advisory:\n   \\`loam archive\\` refuses a scaffold nobody edited (\\`scaffold.placeholder\\`,\n   \\`intent.empty\\`), so the placeholder text cannot reach the living docs.\n   - \\`intent.md\\` — the problem in business terms, in prose; the scaffold's\n     comment-only Why/Scope count as unwritten\n   - \\`delta.likec4\\` — new elements and edges, each tagged \\`#$1\\`; every call edge carries\n     \\`metadata { op '<operationId>' }\\`; replace the scaffolded TODO description on each\n     new service. For a requirements-only feature DELETE this\n     file: an empty delta is legal, but a scaffold left half-filled is not\n   - \\`specs/<svc>/spec.md\\` — the example requirement ships INSIDE the template's\n     comment: copy it out, unindent, one behaviour per requirement, SHALL, at\n     least one Given/When/Then scenario; add \\`Operations:\\` once the operation exists\n   - \\`specs/<svc>/arch.spec.md\\` — the architectural obligations (outbox, retries,\n     idempotency, alerts), same grammar; a \\`Covers:\\` line per requirement naming the\n     tagged elements/edges it accounts for, or \\`c4.uncovered\\` says nothing does\n   - \\`specs/<svc>/openapi.yaml\\` — define every operationId the edges reference.\n     A self-contained document holding ONLY the operations this feature adds,\n     changes or removes — never a copy of the living contract. An operation you\n     leave out stays exactly as the living contract has it, and a local \\`$ref\\`\n     (\\`#/components/schemas/Order\\`) resolves into the living document, so there\n     is nothing to restate. Every operation you quote costs a pin, and once a\n     parallel feature retires it — or moves it, and you quoted the old\n     address — a pinned quote is \\`openapi.baseline-invalid\\` and\n     \\`openapi.op-revived\\` both, an unpinned one \\`openapi.op-revived\\` alone\n     (\\`asyncapi.slot-revived\\` on the event axis) — archive refuses either.\n     Delete the quote; only a feature that MEANS to bring a retired operation\n     back keeps it, and archives past the finding with a human's \\`--approve\\`\n   - \\`specs/<svc>/asyncapi.yaml\\` — the event axis, only when the feature changes\n     what a service puts on or takes off the bus: an AsyncAPI 3.0 document\n     holding only the channel, operation and message slots you add, change or\n     remove (an edited slot is written out whole), new messages under\n     \\`components.messages\\`, and a \\`Publishes:\\`/\\`Consumes:\\` line on each\n     requirement that names them. \\`loam new\\` scaffolds none — an event\n     contract is genuinely optional\n4b. **Analyze before you pin.** Nothing grades this step, which is why it is here:\n   every check after it is a join between exact tokens, so two services that\n   agree on every operationId and disagree on what it means validate, archive\n   and ship green. Read the feature as its reviewer will, before rebase freezes it:\n   - \\`loam show $1 --json\\` — its \\`review\\` object joins the intent, the C4\n     objects, the API/event slices and the dependencies\n   - \\`loam context <service> --feature $1 --json\\` for every service it touches —\n     the living requirements verbatim, the edges one hop out, and this delta\n   - the \\`neighbours\\` step 2b's \\`loam explore\\` reported\n   Then write what the documents leave open under \\`## Open questions\\` in\n   \\`intent.md\\` (the scaffold already carries the heading), one line per question,\n   naming the requirement id or edge it is about:\n   - a SHALL two engineers could build two ways — an unstated unit, bound,\n     ordering, or an \"eventually\" with no window\n   - a value, limit or window two services state differently (a refund window,\n     a rounding rule, a retry budget), and which side refuses when they\n     disagree — a caller that accepts what its provider answers 4xx for is a\n     contradiction no check can see\n   - a \\`Realizes:\\` line whose requirement does not actually deliver the\n     capability promise it names, or a promise this feature changes that no\n     realizing requirement keeps\n   - per call edge in the delta: the timeout, the retry and what makes it safe\n     to repeat, what a partial failure leaves behind, and what compensates it —\n     an edge no requirement answers these for is a question, not a default\n   - each \\`explore\\` neighbour outside \\`--touches\\`: why it is untouched, or that\n     it is a candidate — adding one means a \\`specs/<svc>/\\` delta in this feature,\n     because that directory IS the feature's service list\n   Ask; do not answer for the author. A human answers by editing the file —\n   replacing a question with the decision, or with a change to the delta.\n   Nothing is graded: an empty section is legal, and so is an answered one.\n5. **\\`loam rebase $1\\`** — the step between authoring and checking, and the one that\n   stops two features in flight from silently deleting each other's work. It pins\n   every MODIFIED/REMOVED requirement (\\`Based-On:\\`), and every operation and\n   asyncapi channel/operation/message slot the living contract already holds\n   (\\`x-loam-based-on\\`), to the living version you wrote against. What the\n   feature ADDS has no living version and takes no pin, so an add-only contract\n   delta needs no rebase. Any living operation or slot the delta spells is one\n   the merge upserts, so it needs its pin even when you changed one line of it.\n   Without the pins, \\`delta.baseline-missing\\` / \\`openapi.baseline-missing\\` /\n   \\`asyncapi.baseline-missing\\` GATE\n   the archive: before they did, the second feature to archive reverted the\n   first — with \\`+0 ~1 -0\\`, exit 0, and nobody told. Rebase clears them; a\n   human's \\`--approve\\` is the only other way past.\n   Restamping is not resolving: if rebase reports a requirement as MOVED, re-read\n   the living text and fold in what you still mean BEFORE you ship.\n6. \\`loam validate --feature $1 --json\\`. Do not stop while \\`valid\\` is false.\n7. \\`loam dependencies $1 --json\\` before anyone starts building: it says which\n   features in flight have to archive first (\\`order\\`) and which collisions no\n   ordering fixes (\\`conflicts\\`, \\`cycles\\`). Every conflict it names is one \\`loam rebase\\`\n   cannot fix for you — two intentions have to be merged by people.\n\nThe operation's three spellings — the edge's \\`op\\`, the requirement's \\`Operations:\\`\nline, and the OpenAPI \\`operationId\\` — must match exactly.\n`,\n};\n"]}

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

@@ -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,64 @@ 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\` — \`--service\` runs only — 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,12 +143,20 @@ 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.
 7. If building made you change the feature's documents at all — a requirement's
@@ -99,7 +175,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