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

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

@@ -0,0 +1,323 @@
+/**
+ * The two post-build workflows, paired: the done-check (`loam-verify`) and the
+ * merge it precedes (`loam-ship`). One file for two commands because six
+ * workflows meet the five-file package cap somewhere, and this is the seam the
+ * cycle already has — both describe what happens after the code is built, and
+ * each body names the other's refusals (`record-federated`, `not-coherent`).
+ */
+export const LOAM_VERIFY = {
+    name: "loam-verify",
+    description: "Verify a built loam feature against its own promises, claim by claim, with evidence",
+    argumentHint: "<FEAT-id>",
+    purpose: "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.",
+    invocation: "loam instructions loam-verify $1",
+    placeholders: ["feature"],
+    spine: [
+        "`loam verify` — the checklist, derived from the feature's own artifacts",
+        "run the generated suite with a JSON report: the scenario claims are the runner's to answer, not yours",
+        "answer the remaining claims yourself, every one carrying a `file:line` that resolves",
+        "record from each affected service's own repository, bound to that service",
+        "read the verdict honestly — a scenario confirmed on your word is `attested`, not `verified`",
+    ],
+    body: `Check that the code somebody just built is the feature that was designed.
+
+loam derives the questions; the test runner and you answer them. loam never
+reads the service, so a verdict is worth exactly what its evidence is worth.
+
+1. \`loam verify $1 --json\`. \`claims[]\` is the checklist, derived from the feature's
+   own artifacts — one claim per new service, per operation its openapi delta adds,
+   per (direction, message) its asyncapi delta newly declares against the living
+   contract's send/receive sets (quotes and removals are never questions),
+   per tagged edge that names an operation, and per scenario of every changed
+   requirement, arch.spec.md deltas included. Each has a stable \`id\` and a
+   \`subject\` (the service whose code answers it); a claim that says arch.spec.md
+   wants an integration/ops test, not an acceptance test. An ARCHIVED feature returns its record as frozen history instead
+   (\`frozen: true\`) and \`--record\` / \`--results\` / \`--contract-results\` /
+   \`--diff-answers\` refuse it — \`loam unarchive\` first if the answers really
+   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,
+   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\`
+   notice, and a \`next.verify-attested\` step in \`loam status\`). Nothing gates on
+   it — a legacy service with no suite must still be able to ship — but say so
+   when you hand back, and close it with \`--results\` the moment a suite runs.
+   \`verify.digest-contested\` (warn) is the case where two services word a
+   scenario identically: they share one digest, so no single report can say whose
+   suite ran it, and each service must record its own with \`--service\`.
+   The \`api.exposes\` claims have a mechanical channel too, when an API
+   contract-test suite exists: emit loam's contract-results shape from its
+   report — \`{"loamContractReport": 1, "results": [{"operationId": "…",
+   "status": "passed"}]}\`, a one-line transform for Specmatic, Pact, Dredd or a
+   property harness — and pass \`--contract-results contract.json\` alongside.
+   Only a status of exactly \`passed\` confirms the named operation
+   (\`answered_by: external-runner\`); anything else, and an operation the report
+   never exercised, stays \`unconfirmed\` with the reason, and under the flag the
+   report owns every api.exposes claim, so take those out of the answers file.
+3. Answer every OTHER claim by finding it in the code. Not by reasoning that it
+   must be there — by opening the file:
+   - \`service.exists\` — the service is deployable: its build, its entry point.
+   - \`api.exposes\` — the route handler serving that operationId, not the spec that
+     declares it — unless a contract-test report already answered it in step 2.
+   - \`event.declares\` — the code that puts the message on the wire (sends) or
+     handles it off the wire (receives), not the contract that names it.
+   - \`c4.calls\` — the call site in the CALLER.
+4. Write those answers as JSON — evidence is \`file:line\`, one entry per place it can
+   be seen:
+   \`\`\`json
+   { "answers": [
+     { "id": "<claim id>", "verdict": "confirmed", "evidence": ["src/split/Api.ts:42"] },
+     { "id": "<claim id>", "verdict": "unconfirmed", "note": "the split service has no entry point yet" }
+   ] }
+   \`\`\`
+5. Optional, before recording: cross-examine. Have a SECOND agent answer the
+   same checklist blind — a fresh context, given only \`loam verify $1 --json\`
+   and the code, never your answers file — then compare the two sets:
+
+   \`\`\`sh
+   loam verify $1 --diff-answers yours.json theirs.json --json
+   \`\`\`
+
+   Both files must answer EVERY claim in the compared scope,
+   \`scenario.tested\` included: the diff consults no test report, so this is a
+   DIFFERENT file from the one step 6 records under \`--results\` (that one
+   must omit the runner's claims; a step-6-shaped file here refuses
+   \`answers-mismatch\`). Narrowing with \`--service <id>\` compares one
+   service's claims — give the second agent the same lens, or its file will
+   not match the compared scope. An archived feature refuses the diff too:
+   frozen history has no current checklist. It writes nothing and changes no
+   verdict: \`cross.agree-confirmed\` / \`cross.agree-unconfirmed\` rows are the
+   cheap-to-skip queue, \`disagreements[]\` (\`cross.disagree\`) is what a human
+   reads first, and the \`cross.evidence-disjoint\` notice flags agreements
+   citing non-overlapping files — read those second. Agreement between two
+   same-model agents is correlated, so it ranks review; it never upgrades
+   \`attested\` to \`verified\`. Record only the answer set you stand behind, in
+   a separate run.
+6. Record, **in each affected service's own repository**, one service at a time:
+
+   \`\`\`sh
+   loam verify $1 --service <id> --results report.json [--contract-results contract.json] --record answers.json --json
+   \`\`\`
+
+   \`--service <id>\` narrows the checklist to that service's claims and binds the
+   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,
+   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 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).
+7. Report every \`unconfirmed\` claim and what it would take to close it, and read
+   \`discarded\` in the payload: it names every previous answer the new record does
+   not carry, and each one is either evidence that went stale or evidence that was
+   just dropped. A scenario claim the report failed or missed closes by fixing the
+   code and re-running the suite — never by editing the generated .feature. While
+   any claim stays unconfirmed or unanswered, \`notices[]\` carries
+   \`verify.claims-open\` (warn, gating nothing): the one-line "not a clean
+   result" summary with all four counts, so a partial record can never read as a
+   finished one from the notice lines alone.
+8. Reading is safe from anywhere: \`loam verify $1 --service <id> --json\` without
+   \`--record\` writes nothing and works from the docs repo too. \`services\` lists
+   every subject of the checklist, so it is how you find out which repos still
+   owe an attestation, and \`loam status $1 --json\` says the same thing in the
+   shape of a next step.
+
+Anything you cannot show is \`unconfirmed\` with a note. That is a successful record,
+and it is the useful one: nothing gates on this file, so the only thing it is for is
+telling the next reader the truth. \`loam archive\` will ship the feature either way —
+which is exactly why a \`confirmed\` you cannot back up costs nothing now and misleads
+everyone later.
+
+\`loam verify\` — the notice and record codes its reports carry in \`notices[]\`,
+gathered from the steps above; branch on the code, never the prose:
+
+| code | what it means | what to do |
+|---|---|---|
+| \`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 |
+| \`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. 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 |
+| \`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 |
+`,
+};
+export const LOAM_SHIP = {
+    name: "loam-ship",
+    description: "Archive a finished loam feature — merge its deltas into the living docs",
+    argumentHint: "<FEAT-id>",
+    purpose: "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.",
+    invocation: "loam instructions loam-ship $1",
+    placeholders: ["feature"],
+    spine: [
+        "confirm the code is actually built and merged — archiving early makes the docs claim something that does not exist",
+        "`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.
+
+1. Confirm the code is actually built and merged. Archiving folds the delta into the
+   living docs; doing it early makes the docs claim something that does not exist.
+   \`loam status $1 --json\` answers "is this actually finished" in one call, and its
+   \`next[]\` names what is outstanding if it is not.
+2. \`loam validate --feature $1 --json\` — must come back \`valid: true\`.
+   If it reports \`delta.baseline-missing\` or \`openapi.baseline-missing\`, run
+   \`loam rebase $1\` and re-validate BEFORE going on: those two say nothing has
+   pinned what this delta was written against, so the merge cannot tell the text
+   you EDITED from the text you merely restated. Both gate the archive — the
+   dry run in step 3 refuses on them too — and the only way past without the
+   pins is a human's \`--approve\`.
+3. \`loam archive $1 --dry-run --json\` first. \`plan[]\` is every file the merge would
+   write (\`create\` / \`update\`, then the final \`move\` into \`features/archive/\`) —
+   including an \`update\` for each of the feature's own documents whose links the
+   move re-expresses, at its path before the move, and for each document outside
+   the feature (another feature in flight, a living ADR) whose links into it the
+   archive rewrites — and none of them are written —
+   read it before letting the merge touch the source of 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, 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 on the map with no directory behind it
+   (an error, the one \`validate --all\` will report until \`loam adopt\` writes its
+   documents — it never blocks the merge, and the run prints it instead of claiming
+   the docs complete; a service whose directory the archive creates and the map
+   draws gets an empty extending model instead, and raises nothing), and
+   \`delta.added-conflict\`
+   means another feature in flight adds the same requirement — the first to archive
+   lands it, and the other's archive is then refused (\`delta.added-duplicate\`: its
+   ADDED now collides with the living spec) unless a human \`--approve\`s the
+   replacement. \`dropped[]\` is what each MODIFIED or REMOVED requirement takes OUT
+   of a living document — the scenarios and the \`Covers:\` / \`Operations:\` / … entries
+   its new text does not restate. None of it is a warning, and all of it is gone
+   after the merge: restate in the delta anything that must survive, then re-run.
+   The plan also prints one note per document the merge CREATES, saying whether
+   the delta's title and \`## Purpose\` came across. A created document with no
+   purpose arrives with no narrative at all. And read what lands verbatim — the
+   requirement bodies, scenarios and contract descriptions — for review-time
+   wording such as "this delta" or "this feature": in a living document it points
+   at a change nobody will remember. Fix both in the delta before the merge
+   (\`loam instructions loam-authoring\`, "Writing for a person").
+4. \`loam archive $1 --json\`. It merges three axes into the living state — requirements
+   into \`services/<svc>/spec.md\`, endpoints into \`services/<svc>/openapi.yaml\`,
+   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 — a service the archive creates and
+   the merged map draws gets that model too, written empty at \`services/<svc>/model.likec4\` and holding
+   whatever the delta drew inside the service; it lands unfiled, and
+   \`loam subsystem move <svc> --into <subsystem>\` files it — then moves the feature
+   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).
+     Fix the breaches. \`--approve\` overrides the gating issues and is a human's
+     call to make, not yours: report the breach and stop. Two codes it does not
+     override even then — \`delta.service-id-invalid\` (a \`specs/<svc>/\` name the
+     id grammar refuses) and \`c4.service-binding-invalid\` (a \`metadata { service }\`
+     binding it refuses, anywhere inside a tagged element's block): each names a
+     path the merge would write mechanically, they arrive with
+     \`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. 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.
+   - \`archive-exists\` — \`features/archive/\` already has that directory; a human
+     decides what it is.
+   - \`merge-failed\` — the merge could not be computed, or failed and was rolled
+     back. Either way the living docs are unchanged; fix the reported cause, re-run.
+     "Could not resolve reference to RelationshipKind" means the delta draws a
+     relationship kind (\`-[publishes]->\`) that the living map's \`specification\`
+     does not declare: the archive copies the edge and never the declaration.
+     Declare the kind in \`architecture/landscape.likec4\` — it is vocabulary, not
+     a feature change — then re-run.
+     A file loam cannot decode as UTF-8 refuses here by name rather than being
+     rewritten with replacement characters. So does a living document that still
+     holds git conflict markers — the \`spec.merge-conflict\` /
+     \`landscape.merge-conflict\` findings ride in \`findings[]\`, and \`--approve\`
+     does not override them: the loss is mechanical, not a judgment call.
+   - \`docs-busy\` — another \`loam archive\` or \`loam unarchive\` holds the docs
+     repo's lock. Nothing was read or written; wait for it and re-run once.
+   - \`commit-interrupted\` — a previous archive or unarchive was killed mid-commit
+     and this run cannot repair it on its own: a half-written file was edited
+     since, its pre-image is gone or altered, or \`.loam-commit\` cannot be read.
+     Run \`loam doctor\` (\`doctor.commit-interrupted\` / \`doctor.commit-unreadable\`
+     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
+hand-edit the living docs back instead: the previous text of a \`MODIFIED\` requirement
+is in that snapshot and nowhere else, so anything you write by hand is a guess. It
+refuses under \`snapshot-corrupt\` when a pre-image's bytes no longer match the digest
+the archive recorded — \`--force\` does not override that one, because the damage is
+to the undo itself — and under \`snapshot-missing\` for an archive older than the
+current snapshot format. Both mean version control is the way back.
+`,
+};
+//# sourceMappingURL=closing.js.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2HP;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/\\`) —\n   including an \\`update\\` for each of the feature's own documents whose links the\n   move re-expresses, at its path before the move, and for each document outside\n   the feature (another feature in flight, a living ADR) whose links into it the\n   archive rewrites — and none of them are written —\n   read it before letting the merge touch the source of truth, and stop if a file\n   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 on the map with no directory behind it\n   (an error, the one \\`validate --all\\` will report until \\`loam adopt\\` writes its\n   documents — it never blocks the merge, and the run prints it instead of claiming\n   the docs complete; a service whose directory the archive creates and the map\n   draws gets an empty extending model instead, and raises nothing), 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. \\`dropped[]\\` is what each MODIFIED or REMOVED requirement takes OUT\n   of a living document — the scenarios and the \\`Covers:\\` / \\`Operations:\\` / … entries\n   its new text does not restate. None of it is a warning, and all of it is gone\n   after the merge: restate in the delta anything that must survive, then re-run.\n   The plan also prints one note per document the merge CREATES, saying whether\n   the delta's title and \\`## Purpose\\` came across. A created document with no\n   purpose arrives with no narrative at all. And read what lands verbatim — the\n   requirement bodies, scenarios and contract descriptions — for review-time\n   wording such as \"this delta\" or \"this feature\": in a living document it points\n   at a change nobody will remember. Fix both in the delta before the merge\n   (\\`loam instructions loam-authoring\\`, \"Writing for a person\").\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 — a service the archive creates and\n   the merged map draws gets that model too, written empty at \\`services/<svc>/model.likec4\\` and holding\n   whatever the delta drew inside the service; it lands unfiled, and\n   \\`loam subsystem move <svc> --into <subsystem>\\` files it — 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     \"Could not resolve reference to RelationshipKind\" means the delta draws a\n     relationship kind (\\`-[publishes]->\\`) that the living map's \\`specification\\`\n     does not declare: the archive copies the edge and never the declaration.\n     Declare the kind in \\`architecture/landscape.likec4\\` — it is vocabulary, not\n     a feature change — then 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

@@ -0,0 +1,220 @@
+/** Starting a feature: explore, scaffold, author the three axes, rebase, validate. */
+export const LOAM_FEATURE = {
+    name: "loam-feature",
+    description: "Start a new loam feature — scaffold it, then author the C4 delta and requirement deltas",
+    argumentHint: `<FEAT-id> "<title>"`,
+    purpose: "Start a feature in the docs repo: decide which services it touches, scaffold it, then author the C4 delta and one requirement delta per service. The `--touches` list is the hardest call in the cycle and nothing downstream catches one that is short by a service.",
+    invocation: 'loam instructions loam-feature $1 "$2"',
+    // $2 is the feature's human title: any string is a legal one.
+    placeholders: ["feature", "free"],
+    spine: [
+        "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",
+        "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:
+   - \`loam status --json\` — what is already in flight and what it is waiting on.
+     Run this FIRST if you joined this repository halfway or lost the session:
+     \`next[]\` is ordered and each entry carries the literal command to run, so it
+     tells you whether the work is to start $1 at all. \`loam status $1 --json\`
+     narrows it to one feature once $1 exists
+   - \`loam list --json\` — what services exist, and what documentation they are missing
+   - \`loam show <service> --json\` — what a service owns, exposes, and who already calls it
+2b. \`loam explore <service> --json --as $1\` around every service you believe this
+   feature touches. This is the step that decides step 3's \`--touches\` list, and it
+   is the only decision in the cycle nothing downstream catches — a list short by one
+   service produces a feature that validates, archives and ships with a consumer
+   nobody updated. Read four fields:
+   - \`neighbours\` — the services one hop out in the fleet map. Weigh each one. loam
+     knows they are connected, not whether you change them, and it deliberately
+     leaves them OUT of the suggested command line rather than guessing for you
+   - \`services[].maturity\` — a service at \`empty\` or \`partial\` has no baseline to
+     write a delta against, so the work starts with \`loam adopt --service <id>\`, not
+     with this feature
+   - \`services[].operations\` — what each already exposes, so an operation you are
+     about to "add" that is already there becomes a MODIFIED requirement instead
+   - \`overlaps\` — active features already carrying a delta for these services.
+     \`loam dependencies --json\` (step 7) then says which must archive first
+   \`--op <operationId>\` seeds from an operation when you know the call but not who
+   owns it. A seed naming no \`services/<id>/\` is reported in \`unknown\` with the
+   closest real ids rather than refused — the feature may be introducing it, and a
+   typo looks identical until you read that list. \`scaffold\` is the literal step-3
+   command line the seeds imply, with \`--new-service\` where the service does not
+   exist yet.
+3. Scaffold it: \`loam new $1 --title "$2"\`, adding \`--touches <id>\` for every service the
+   feature touches and \`--new-service <id>\` for every one it introduces. Every id goes
+   through the \`services/<id>/\` grammar, so a typo is refused (\`invalid-option\`)
+   rather than scaffolded; a \`--touches\` that matches nothing existing comes back as
+   a \`note\` with the close ids, not as a failure — read it, because a \`--touches\`
+   naming a service that does not exist is \`delta.service-unknown\` at validate time
+   and a phantom \`services/<typo>/\` directory if it ever archives.
+4. Author what the templates left as TODO. This step is gated, not advisory:
+   \`loam archive\` refuses a scaffold nobody edited (\`scaffold.placeholder\`,
+   \`intent.empty\`), so the placeholder text cannot reach the living docs.
+   - \`intent.md\` — the problem in business terms, in prose; the scaffold's
+     comment-only Why/Scope count as unwritten
+   - \`delta.likec4\` — new elements and edges, each tagged \`#$1\`; every call edge carries
+     \`metadata { op '<operationId>' }\`; replace the scaffolded TODO description on each
+     new service. For a requirements-only feature DELETE this
+     file: an empty delta is legal, but a scaffold left half-filled is not.
+     Draw each edge with its relationship kind (\`-[calls]->\`, \`-[publishes]->\`,
+     \`-[delivers]->\`, …), and draw a direction only where the evidence shows
+     one: anything else is \`-[connects]->\`. A message runs producer
+     \`-[publishes]->\` topic and topic \`-[delivers]->\` consumer, never
+     producer \`->\` consumer. A producer outside the fleet is an \`#external\`
+     element whose edge carries \`metadata { publishes }\`. Declare every kind
+     you draw in the delta's own \`specification\`, and check that the living
+     map's declares it too. The archive copies the edge and never the
+     declaration, so a kind the map lacks refuses the archive (\`merge-failed\`)
+     even though validate and status call the feature ready.
+     \`loam instructions loam-drawing\` has the kinds and their styles
+   - \`specs/<svc>/spec.md\` — the example requirement ships INSIDE the template's
+     comment: copy it out, unindent, one behaviour per requirement, SHALL, at
+     least one Given/When/Then scenario; add \`Operations:\` once the operation exists
+   - \`specs/<svc>/arch.spec.md\` — the architectural obligations (outbox, retries,
+     idempotency, alerts), same grammar; a \`Covers:\` line per requirement naming the
+     tagged elements/edges it accounts for, or \`c4.uncovered\` says nothing does.
+     Write an edge by its endpoints' service names
+     (\`order-service -> payment-service\`), which resolve the same before and
+     after the archive
+   - write every document for a reviewer who has never seen the code.
+     \`intent.md\` gains a \`## How to read this feature\` section, a
+     business-requirement coverage table, and \`## Open questions\` as a table
+     (ID, question, blocks, owner, current default). Each spec delta opens
+     with a plain-language \`## Purpose\`. A long requirement body becomes a
+     one-line lead plus one bullet per SHALL sentence. Every abbreviation is
+     expanded on first use. "This delta" and "this feature" stay out of
+     requirement bodies and contract descriptions, because the archive copies
+     those into the living docs. A word the feature brings goes in
+     \`glossary/<term>.md\` and a decision in \`adrs/\`, both inside the feature,
+     and a cross-service flow in \`usecases/<name>.likec4\`, tagged with a
+     \`#cap-\` that resolves. \`loam instructions loam-authoring\`, "Writing
+     for a person", has the shapes
+   - \`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: 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
+   - for a service (or capability) this feature CREATES, the delta is the
+     living document's first draft, and \`loam archive\` carries only what you
+     mark as the document's own: the frontmatter \`owner\`, an H1 that neither
+     names $1 nor calls itself a delta (the scaffold's does both — retitle it),
+     and a \`## Purpose\` section — put the service's narrative there. Everything
+     else in the delta is read as being about the change and stays with it in
+     \`features/archive/\`, linked from the new document
+   - links: write each one so it resolves where you write it, relative to the
+     file. A link into this feature — from its deltas, or from any other
+     document whose links validate grades — is re-pointed by \`loam archive\`
+     to wherever the file ends up — a term in \`glossary/<term>.md\` at the living glossary,
+     anything else (an ADR in \`adrs/\` above all) inside
+     \`features/archive/\`, because a feature ADR is never copied into the living
+     tree. A decision meant to outlive this change belongs in
+     \`architecture/adrs/\` or the service's own \`adrs/\` instead. The same
+     holds inside this feature: its own documents (the intent, its ADRs) move
+     to \`features/archive/\` with it, and the archive re-expresses their links
+     for the move — never write them for the archived location yourself
+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 table row per
+   question — ID, the question, what it blocks (the requirement id or edge it is
+   about), its owner, and the default that gets built if nobody answers:
+   - 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. The default column records what the
+   documents imply today, not what you would choose. 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:\`), 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
+   first — with \`+0 ~1 -0\`, exit 0, and nobody told. Rebase clears them; a
+   human's \`--approve\` is the only other way past.
+   Restamping is not resolving: if rebase reports a requirement as MOVED, re-read
+   the living text and fold in what you still mean BEFORE you ship.
+6. \`loam validate --feature $1 --json\`. Do not stop while \`valid\` is false.
+7. \`loam dependencies $1 --json\` before anyone starts building: it says which
+   features in flight have to archive first (\`order\`) and which collisions no
+   ordering fixes (\`conflicts\`, \`cycles\`). Every conflict it names is one \`loam rebase\`
+   cannot fix for you — two intentions have to be merged by people.
+
+The operation's three spellings — the edge's \`op\`, the requirement's \`Operations:\`
+line, and the OpenAPI \`operationId\` — must match exactly.
+`,
+};
+//# sourceMappingURL=feature.js.map