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

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

@@ -1 +1 @@
-{"version":3,"file":"done-check.js","sourceRoot":"","sources":["../../../../../src/core/agent/workflows/reference/done-check.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,eAAe,GAAmB;IAC7C,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,4FAA4F;IAC9F,6EAA6E;IAC7E,+CAA+C;IAC/C,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,mOAAmO;IACrO,UAAU,EAAE,mCAAmC;IAC/C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE,CAAC,gBAAgB,CAAC;IACzB,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+KP;CACA,CAAC","sourcesContent":["/**\n * The `loam-done-check` reference page: how `loam verify` derives its claims,\n * who may answer them, and what separates **verified** from **attested**.\n *\n * It is the longest single section the corpus had after the code inventory —\n * three answer channels, the federated recording form, the evidence pins and\n * the six codes the record itself can carry — and every word of it is read at\n * one moment in the cycle, step 7. AGENTS.md's own step 7 names this page.\n *\n * The text is the AGENTS.md section verbatim. See ./reference.ts for why the\n * four pages exist and what was traded for them.\n */\nimport type { CommandContent } from \"../../contract.js\";\n\nexport const LOAM_DONE_CHECK: CommandContent = {\n  name: \"loam-done-check\",\n  description:\n    \"Reference: the done-check — how `loam verify` derives claims, and verified versus attested\",\n  // No arguments: one document, printed whole. See ./spine.ts for why the hint\n  // is empty rather than a spelled-out \"<none>\".\n  argumentHint: \"\",\n  purpose:\n    \"What `loam verify` asks, which of the three channels may answer each kind of claim, how a cross-service feature is recorded from each service's own repository, and why an agent's word yields `attested` rather than `verified`.\",\n  invocation: \"loam instructions loam-done-check\",\n  placeholders: [],\n  spine: [\"The done-check\"],\n  body: `The done-check: what \\`loam verify\\` asks, who may answer it, and what the answer is worth.\n\n## The done-check\n\n\\`loam verify <FEAT>\\` derives a checklist from the feature's own artifacts —\none claim per new service, per operation the delta adds, per tagged edge that\nnames an operation, and per scenario of every changed requirement, arch.spec.md\ndeltas included (those claims name their file, and the test they ask for is an\nintegration/ops test, not an acceptance test). Each claim has a stable id, so\ntwo runs are diffable and an answer cannot drift onto a different question.\n\nThree answer channels, and they never overlap. The \\`scenario.tested\\` claims\nare the TEST RUNNER's to answer: run the generated suite and pass its report\nback — cucumber JSON (\\`cucumber-js --format json:report.json\\`), or loam's own\nrunner-neutral shape \\`{\"loamScenarioReport\": 1, \"results\": [{\"digest\": \"…\",\n\"status\": \"passed\"}]}\\` that any runner can be adapted into, chosen by its\nmarker key. The digest is the contract, never the dialect: both read\n\\`answered_by: runner\\` because both are a real run reporting that digest green,\nso a JUnit or pytest fleet is not held at \\`attested\\` by a file format —\n\\`loam verify <FEAT> --results report.json\\`. A claim is confirmed only when a\nreport scenario carrying its \\`@loam-digest-<16hex>\\` tag ran at least one step\nand every step passed — every occurrence, when the report holds a re-run, and\nevery before/after hook with it. A failed, undefined, pending or skipped step,\na failed hook, or no matching scenario at all, is \\`unconfirmed\\` with the\nreason. The digest is the only identity: a reworded spec scenario matches\nnothing until the suite is regenerated and re-run. When a report exists,\nALWAYS pass \\`--results\\` — under it the runner owns every scenario claim, and\nan answers-file entry for one is refused.\n\nThe \\`api.exposes\\` claims have a mechanical channel of their own: an API\ncontract-test run, passed back with\n\\`loam verify <FEAT> --contract-results contract.json\\`. loam accepts one\nshape — its own documented contract-results JSON,\n\\`{\"loamContractReport\": 1, \"results\": [{\"operationId\": \"createSplit\",\n\"status\": \"passed\"}]}\\` — emitted from your contract tool's report in one\ntransform (Specmatic's own coverage JSON is refused by design: its \"covered\"\nstatus means exercised, not passed, so reading it would confirm what a red run\nrefuted). An entry whose status is exactly \\`passed\\` confirms the claim whose\noperationId it names — the record says \\`answered_by: external-runner\\` and the\nviews mark the line \\`[contract]\\` — while a failed or unknown status and an\noperation the report never exercised leave the claim \\`unconfirmed\\` with the\nreason; entries naming operations outside the checklist are ignored.\n\\`verify.operation-contested\\` (warn) is \\`verify.digest-contested\\`'s twin on\nthis axis: an operationId is unique per contract document, not per fleet, so\nwhen two services on the checklist expose the same one, a report entry — which\nnames no service — cannot say whose suite exercised it, those claims stay\nunconfirmed, and each service records its own with \\`--service\\`. Under the\nflag the contract report OWNS every api.exposes claim in scope, so an\nanswers-file entry for one is refused (\\`answers-mismatch\\`), and the record\npins the file consumed in \\`contractReport\\` (path, sha256 of the bytes, mtime,\noperation count) exactly as \\`report\\` pins the cucumber one. The verdict\nladder does not move: external evidence never answers a \\`scenario.tested\\`\nclaim, so \\`attested\\` versus \\`verified\\` still turns on scenario claims\nalone.\n\n\\`--record\\` without \\`--results\\` is the fallback for a service with no runnable\nsuite yet: there your word answers the scenario claims too. It still works, and\nit costs something you must know about. The record says who answered\n(\\`answered_by: agent\\`), and that answer changes the VERDICT: a feature whose\nscenario claims rest on an agent's word is **attested**, not verified.\n\\`verify --json\\` reports \\`verdict: \"attested\"\\` with \\`verified: false\\` and an\n\\`attested\\` count, \\`loam status\\` marks it and adds a \\`next.verify-attested\\` step,\nand the notice rides in \\`notices[]\\` under \\`verify.scenario-attested\\` (warn —\nnothing gates on it, because a legacy service with no suite must still be able\nto ship). Answer them mechanically the moment a suite runs:\n\\`loam verify <FEAT> --results <report.json>\\`.\n\nA record that leaves any claim unconfirmed or unanswered carries\n\\`verify.claims-open\\` (warn) in \\`notices[]\\` — the one-line \"not a clean\nresult\" summary with all four counts, on the read view and the frozen\npost-archive view alike; it gates nothing, and a feature with no record at all\nnever carries it, because not-started is not partial.\n\nFederated \\`--record\\` also stamps \\`evidence_pins\\` on each agent-confirmed\ncitation — the cited file's sha256 at the attested commit, the cited line's\ntext, and the literal token the claim asserts (operationId, message name, edge\nop). One notice rides beside the stamp: \\`verify.evidence-token-missing\\` (warn,\nverdict-neutral, gates nothing) says a cited file at the attested commit does\nnot contain the claim's token — read that evidence first, while the answer can\nstill be corrected. \\`loam validate\\`, run later in the service's repo,\nre-checks the pins and reports drift under the \\`evidence.*\\` findings; nothing\nthere moves a verdict either.\n\nTwo more codes belong to the record itself. \\`verify.record-miscounted\\` (error):\na \\`verification.yaml\\` whose \\`summary\\` block contradicts its own \\`claims[]\\` — the\nrecord is refused as unreadable rather than believed in either half, and\nre-recording is the repair, never editing the counts. \\`verify.digest-contested\\`\n(warn): two or more services word a scenario identically, so they share one\n\\`@loam-digest-…\\` tag and no single cucumber report can say whose suite ran it —\nthose scenario claims are left unconfirmed, and each service records its own\nfrom its own repository with \\`--service\\`.\n\nA federated record also says WHAT EACH SERVICE ANSWERED AGAINST. Every\nattestation carries the \\`checklist\\` digest it answered and, when the docs repo\nis a git checkout, the \\`docsCommit\\` that checklist was derived from — so the\nrecord pins both sides, the service repo through \\`commit\\` and the question set\nthrough these two. \\`verify.checklist-forked\\` (warn) is what that buys: it names the\nservices whose attestation answers a DIFFERENT checklist than the feature now\nasks, which the record-level \\`checklist\\` field alone could never show — it\nflagged every service or none, and never said which answers went stale. It is\nmeasured against the present rather than pairwise between attestations, because\nservices that all answered a since-rewritten delta agree with each other and are\nevery one of them stale. Differing \\`docsCommit\\` values are NOT a finding:\nrecording a week apart is normal for a feature in flight.\nNormal mid-rollout and it gates nothing; re-record the services on the older\nversion from their own repositories, or accept the split knowingly.\nAttestations written before the field existed carry no \\`checklist\\` and are not\ncounted as a third version — silence is not disagreement.\n\nA consumed report is written down: \\`report\\` and \\`contractReport\\` on the\nrecord (or on that repository's attestation) each carry the path, a sha256 of\nthe bytes, the file's mtime and how much it held — tagged scenarios for the\none, distinct operationIds for the other. That identifies WHICH file answered\nthe claims, and — when the file is committed — that it matches the attested\ncommit. It does not prove the file came from executing that commit; no digest\ncan.\n\nEverything else you answer from the code, and \\`--record answers.json\\` takes\nthose back, writing \\`features/<FEAT>/verification.yaml\\` — it travels into the\narchive with the feature and reads without loam. Alongside the mechanical\nflags, the answers file must answer exactly the claims no report owns: an\nentry for a report-owned claim is refused (\\`answers-mismatch\\`), and a\nmechanical flag alone is refused while claims outside its kind are\noutstanding. Every recorded verdict says who answered it\n(\\`answered_by: runner | external-runner | agent\\`), so a reviewer can tell a\ngreen run from somebody's word.\n\n**A cross-service feature is verified once per service, and the form matters.**\nThe claims of one feature belong to several services, and each service's code\nlives in its own repository — so the recording form is federated:\n\n\\`\\`\\`sh\n# in EACH affected service's own repo, not in the docs repo:\nloam verify FEAT-101 --service payment-service --results report.json --record answers.json\n# with an API contract suite, its report answers the api.exposes claims too:\nloam verify FEAT-101 --service payment-service --results report.json --contract-results contract.json --record answers.json\n\\`\\`\\`\n\n\\`--service <id>\\` narrows the checklist to that service's claims and binds the\nanswers to this repository's commit, producing one **attestation** per service\ninside a single \\`schema: 2\\` \\`verification.yaml\\`. Re-running it in the next\nrepo adds that repo's attestation and leaves the others standing. Omitting\n\\`--service\\` in a repo whose \\`loam.json\\` declares one substitutes it, so the\nshort form is safe there; a \\`--service\\` naming a service this repo does not\ndeclare is refused (\\`service-mismatch\\`), and \\`--service\\` from a repo that\ndeclares none is refused (\\`repository-unavailable\\`) — an attestation has to be\nbound to the code it is about.\n\n⚠ **The legacy all-at-once form \\`loam verify <FEAT> --record answers.json\\` with\nno \\`--service\\` writes the whole record from one place.** Over a record that\nalready carries other services' attestations it is refused outright\n(\\`record-federated\\`, naming the attestors) rather than merged or migrated — the\nalternative was one repo silently erasing nine others' evidence. Use it only for\na single-service feature that has never been recorded federated. A\n\\`verification.yaml\\` that exists but cannot be read is \\`record-unreadable\\`: it is\nnever overwritten and never reported as \"no record\".\n\nReading is not writing: \\`loam verify <FEAT> --service <id>\\` **without**\n\\`--record\\` is a pure lens on the checklist. A read-only verify checklist needs no\nbinding and works from the docs repo, or from anywhere else — the refusals above\nare about WRITING an attestation, and only about that. Every run lists all\nsubjects in \\`services\\`, and a recorded run reports in \\`discarded\\` every previous\nanswer the new record does not carry.\n\nIt refuses an answer set that does not answer the current checklist: an id that\nis not on it (\\`answers-mismatch\\`), a claim with no answer (same), or a\n\\`confirmed\\` with no evidence (\\`answers-unevidenced\\`). Evidence is \\`file:line\\`.\nA claim you cannot show is \\`unconfirmed\\` with a note saying why — that is a\nsuccessful record, and it is more useful to the next reader than a yes.\n\n**Nothing gates on it.** \\`loam archive\\` will ship an unverified feature. That\nis deliberate: coherence is something loam computed from the documents, and a\nverdict is your word about code loam never read. A gate in front of shipping\nwould only teach everyone that the cheapest way past it is to say yes. The\nrecord is for the reviewer who comes later, so leave it true.\n`,\n};\n"]}
+{"version":3,"file":"done-check.js","sourceRoot":"","sources":["../../../../../src/core/agent/workflows/reference/done-check.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,eAAe,GAAmB;IAC7C,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,4FAA4F;IAC9F,6EAA6E;IAC7E,+CAA+C;IAC/C,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,mOAAmO;IACrO,UAAU,EAAE,mCAAmC;IAC/C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE,CAAC,gBAAgB,CAAC;IACzB,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqMP;CACA,CAAC","sourcesContent":["/**\n * The `loam-done-check` reference page: how `loam verify` derives its claims,\n * who may answer them, and what separates **verified** from **attested**.\n *\n * It is the longest single section the corpus had after the code inventory —\n * three answer channels, the federated recording form, the evidence pins and\n * the six codes the record itself can carry — and every word of it is read at\n * one moment in the cycle, step 7. AGENTS.md's own step 7 names this page.\n *\n * The text is the AGENTS.md section verbatim. See ./reference.ts for why the\n * four pages exist and what was traded for them.\n */\nimport type { CommandContent } from \"../../contract.js\";\n\nexport const LOAM_DONE_CHECK: CommandContent = {\n  name: \"loam-done-check\",\n  description:\n    \"Reference: the done-check — how `loam verify` derives claims, and verified versus attested\",\n  // No arguments: one document, printed whole. See ./spine.ts for why the hint\n  // is empty rather than a spelled-out \"<none>\".\n  argumentHint: \"\",\n  purpose:\n    \"What `loam verify` asks, which of the three channels may answer each kind of claim, how a cross-service feature is recorded from each service's own repository, and why an agent's word yields `attested` rather than `verified`.\",\n  invocation: \"loam instructions loam-done-check\",\n  placeholders: [],\n  spine: [\"The done-check\"],\n  body: `The done-check: what \\`loam verify\\` asks, who may answer it, and what the answer is worth.\n\n## The done-check\n\n\\`loam verify <FEAT>\\` derives a checklist from the feature's own artifacts —\none claim per new service, per operation the delta adds, per tagged edge that\nnames an operation, and per scenario of every changed requirement, arch.spec.md\ndeltas included (those claims name their file, and the test they ask for is an\nintegration/ops test, not an acceptance test). Each claim has a stable id, so\ntwo runs are diffable and an answer cannot drift onto a different question.\n\nThree answer channels, and they never overlap. The \\`scenario.tested\\` claims\nare the TEST RUNNER's to answer: run the generated suite and pass its report\nback — cucumber JSON (\\`cucumber-js --format json:report.json\\`), or loam's own\nrunner-neutral shape \\`{\"loamScenarioReport\": 1, \"results\": [{\"digest\": \"…\",\n\"status\": \"passed\"}]}\\` that any runner can be adapted into, chosen by its\nmarker key. The digest is the contract, never the dialect: both read\n\\`answered_by: runner\\` because both are a real run reporting that digest green,\nso a JUnit or pytest fleet is not held at \\`attested\\` by a file format —\n\\`loam verify <FEAT> --results report.json\\`. A claim is confirmed only when a\nreport scenario carrying its \\`@loam-digest-<16hex>\\` tag ran at least one step\nand every step passed — every occurrence, when the report holds a re-run, and\nevery before/after hook with it — and, in a cucumber report, ran exactly as\nmany steps as the stamped scenario has: a hand-tagged stub is not that\nscenario's run. A failed, undefined, pending or skipped step, a failed hook, a\nstep count that differs, or no matching scenario at all, is \\`unconfirmed\\` with\nthe reason. A report that is not JSON (a JUnit XML file) is refused\n\\`answers-unreadable\\`, naming both shapes. The digest is the only identity: a reworded spec scenario matches\nnothing until the suite is regenerated and re-run. When a report exists,\nALWAYS pass \\`--results\\` — under it the runner owns every scenario claim, and\nan answers-file entry for one is refused.\n\nThe \\`api.exposes\\` claims have a mechanical channel of their own: an API\ncontract-test run, passed back with\n\\`loam verify <FEAT> --contract-results contract.json\\`. loam accepts one\nshape — its own documented contract-results JSON,\n\\`{\"loamContractReport\": 1, \"results\": [{\"operationId\": \"createSplit\",\n\"status\": \"passed\"}]}\\` — emitted from your contract tool's report in one\ntransform (Specmatic's own coverage JSON is refused by design: its \"covered\"\nstatus means exercised, not passed, so reading it would confirm what a red run\nrefuted). An entry whose status is exactly \\`passed\\` confirms the claim whose\noperationId it names — the record says \\`answered_by: external-runner\\` and the\nviews mark the line \\`[contract]\\` — while a failed or unknown status and an\noperation the report never exercised leave the claim \\`unconfirmed\\` with the\nreason; entries naming operations outside the checklist are ignored.\n\\`verify.operation-contested\\` (warn) is \\`verify.digest-contested\\`'s twin on\nthis axis: an operationId is unique per contract document, not per fleet, so\nwhen two services on the checklist expose the same one, a report entry — which\nnames no service — cannot say whose suite exercised it, those claims stay\nunconfirmed, and each service records its own with \\`--service\\`. Under the\nflag the contract report OWNS every api.exposes claim in scope, so an\nanswers-file entry for one is refused (\\`answers-mismatch\\`), and the record\npins the file consumed in \\`contractReport\\` (path, sha256 of the bytes, mtime,\noperation count) exactly as \\`report\\` pins the cucumber one. The verdict\nladder does not move: external evidence never answers a \\`scenario.tested\\`\nclaim, so \\`attested\\` versus \\`verified\\` still turns on scenario claims\nalone.\n\n\\`--record\\` without \\`--results\\` is the fallback for a service with no runnable\nsuite yet: there your word answers the scenario claims too. It still works, and\nit costs something you must know about. The record says who answered\n(\\`answered_by: agent\\`), and that answer changes the VERDICT: a feature whose\nscenario claims rest on an agent's word is **attested**, not verified.\n\\`verify --json\\` reports \\`verdict: \"attested\"\\` with \\`verified: false\\` and an\n\\`attested\\` count, \\`loam status\\` marks it and adds a \\`next.verify-attested\\` step,\nand the notice rides in \\`notices[]\\` under \\`verify.scenario-attested\\` (warn —\nnothing gates on it, because a legacy service with no suite must still be able\nto ship). Answer them mechanically the moment a suite runs:\n\\`loam verify <FEAT> --results <report.json>\\`.\n\nA record that leaves any claim unconfirmed or unanswered carries\n\\`verify.claims-open\\` (warn) in \\`notices[]\\` — the one-line \"not a clean\nresult\" summary with all four counts, on the read view and the frozen\npost-archive view alike; it gates nothing, and a feature with no record at all\nnever carries it, because not-started is not partial.\n\nFederated \\`--record\\` also stamps \\`evidence_pins\\` on each agent-confirmed\ncitation — the cited file's sha256 at the attested commit, the cited line's\ntext, and the literal token the claim asserts (operationId, message name, edge\nop). One notice rides beside the stamp: \\`verify.evidence-token-missing\\` (warn,\nverdict-neutral, gates nothing) says a cited file at the attested commit does\nnot contain the claim's token — read that evidence first, while the answer can\nstill be corrected. \\`loam validate\\`, run later in the service's repo,\nre-checks the pins and reports drift under the \\`evidence.*\\` findings; nothing\nthere moves a verdict either.\n\nTwo more codes belong to the record itself. \\`verify.record-miscounted\\` (error):\na record file whose \\`summary\\` block contradicts its own \\`claims[]\\` — the\nrecord is refused as unreadable rather than believed in either half, and the\nrepair is never editing the counts: a service's own \\`verification/<id>.yaml\\`\nis deleted and recorded again by that service, and the one-file\n\\`verification.yaml\\` is restored from version control and then recorded over.\n\\`verify.digest-contested\\`\n(warn): two or more services word a scenario identically, so they share one\n\\`@loam-digest-…\\` tag and no single cucumber report can say whose suite ran it —\nthose scenario claims are left unconfirmed, and each service records its own\nfrom its own repository with \\`--service\\`.\n\nA federated record also says WHAT EACH SERVICE ANSWERED AGAINST. Every\nattestation carries the \\`checklist\\` digest it answered and, when the docs repo\nis a git checkout, the \\`docsCommit\\` that checklist was derived from — so the\nrecord pins both sides, the service repo through \\`commit\\` and the question set\nthrough these two. \\`verify.checklist-forked\\` (warn) is what that buys: it names the\nservices whose attestation answers a DIFFERENT checklist than the feature now\nasks, which the record-level \\`checklist\\` field alone could never show — it\nflagged every service or none, and never said which answers went stale. It is\nmeasured against the present rather than pairwise between attestations, because\nservices that all answered a since-rewritten delta agree with each other and are\nevery one of them stale. Differing \\`docsCommit\\` values are NOT a finding:\nrecording a week apart is normal for a feature in flight.\nNormal mid-rollout and it gates nothing; re-record the services on the older\nversion from their own repositories. In a record kept as per-service files the\nanswers of the services it names do not count until they do: the record\nanswers the newest version its files answered, and an answer filed against an\nolder one could otherwise fill the slot of the question that replaced it.\nAttestations written before the field existed carry no \\`checklist\\` and are not\ncounted as a third version — silence is not disagreement.\n\nA consumed report is written down: \\`report\\` and \\`contractReport\\` on the\nrecord (or on that repository's attestation) each carry the path, a sha256 of\nthe bytes, the file's mtime and how much it held — tagged scenarios for the\none, distinct operationIds for the other. That identifies WHICH file answered\nthe claims, and — when the file is committed — that it matches the attested\ncommit. It does not prove the file came from executing that commit; no digest\ncan.\n\nEverything else you answer from the code, and \\`--record answers.json\\` takes\nthose back — into \\`features/<FEAT>/verification/<svc>.yaml\\` with \\`--service\\`,\ninto the one file \\`features/<FEAT>/verification.yaml\\` without — and either\ntravels into the archive with the feature and reads without loam. Alongside the mechanical\nflags, the answers file must answer exactly the claims no report owns: an\nentry for a report-owned claim is refused (\\`answers-mismatch\\`), and a\nmechanical flag alone is refused while claims outside its kind are\noutstanding. Every recorded verdict says who answered it\n(\\`answered_by: runner | external-runner | agent\\`), so a reviewer can tell a\ngreen run from somebody's word.\n\n**A cross-service feature is verified once per service, and the form matters.**\nThe claims of one feature belong to several services, and each service's code\nlives in its own repository — so the recording form is federated:\n\n\\`\\`\\`sh\n# in EACH affected service's own repo, not in the docs repo:\nloam verify FEAT-101 --service payment-service --results report.json --record answers.json\n# with an API contract suite, its report answers the api.exposes claims too:\nloam verify FEAT-101 --service payment-service --results report.json --contract-results contract.json --record answers.json\n\\`\\`\\`\n\n\\`--service <id>\\` narrows the checklist to that service's claims and binds the\nanswers to this repository's commit, producing that service's **attestation**\nas a file of its own, \\`features/<FEAT>/verification/<id>.yaml\\`. The directory\nis the record: loam adds the files up when it reads, and the verdict and\ncounts are computed from them, never stored. Re-running it in the next repo\nwrites that repo's file and touches no other — which is why two teams'\nattestations on two docs-repo branches merge cleanly, where one shared file\nconflicted every time. A one-file federated \\`verification.yaml\\` written\nbefore the directory is still read; a service that records again supersedes\nits share of it, and the file goes once every service it names has its own.\nOmitting\n\\`--service\\` in a repo whose \\`loam.json\\` declares one substitutes it, so the\nshort form is safe there; a \\`--service\\` naming a service this repo does not\ndeclare is refused (\\`service-mismatch\\`), and \\`--service\\` from a repo that\ndeclares none is refused (\\`repository-unavailable\\`) — an attestation has to be\nbound to the code it is about.\n\n⚠ **The legacy all-at-once form \\`loam verify <FEAT> --record answers.json\\` with\nno \\`--service\\` writes the whole record from one place.** Over a record that\nalready carries other services' attestations it is refused outright\n(\\`record-federated\\`, naming the attestors) rather than merged or migrated — the\nalternative was one repo silently erasing nine others' evidence. Use it only for\na single-service feature that has never been recorded federated. A record file\nthat exists but cannot be read — broken YAML, git conflict markers, a miscount\n— is \\`record-unreadable\\`: it is never overwritten and never reported as \"no\nrecord\", and the message names the file and the repair that is safe for it. A\nservice's own \\`verification/<id>.yaml\\` holds only that service's word, so that\nservice may delete it and record again; the one-file \\`verification.yaml\\` may\nhold other services' attestations, so it is restored from version control\n(after a merge, the copy on the branch you merged into) and never deleted.\n\nReading is not writing: \\`loam verify <FEAT> --service <id>\\` **without**\n\\`--record\\` is a pure lens on the checklist. A read-only verify checklist needs no\nbinding and works from the docs repo, or from anywhere else — the refusals above\nare about WRITING an attestation, and only about that. Every run lists all\nsubjects in \\`services\\`, and a recorded run reports in \\`discarded\\` every previous\nanswer the new record does not carry.\n\nIt refuses an answer set that does not answer the current checklist: an id that\nis not on it (\\`answers-mismatch\\`), a claim with no answer (same), or a\n\\`confirmed\\` with no evidence (\\`answers-unevidenced\\`). Evidence is \\`file:line\\`.\nA claim you cannot show is \\`unconfirmed\\` with a note saying why — that is a\nsuccessful record, and it is more useful to the next reader than a yes.\n\n**Nothing gates on it.** \\`loam archive\\` will ship an unverified feature. That\nis deliberate: coherence is something loam computed from the documents, and a\nverdict is your word about code loam never read. A gate in front of shipping\nwould only teach everyone that the cheapest way past it is to say yes. The\nrecord is for the reviewer who comes later, so leave it true.\n`,\n};\n"]}

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

@@ -0,0 +1,253 @@
+export const LOAM_DRAWING = {
+    name: "loam-drawing",
+    description: "Reference: drawing the map so a person can read it — relationship kinds and which way each arrow points, the legend, overview views",
+    // A reference page takes no arguments: see ../spine.ts for why the hint is
+    // empty rather than a spelled-out "<none>".
+    argumentHint: "",
+    purpose: "How to draw the C4 model so the picture reads: one relationship kind per kind of traffic and an arrow only where evidence gives one, a legend drawn from real edges, and overview views that each answer one question at one altitude.",
+    invocation: "loam instructions loam-drawing",
+    placeholders: [],
+    spine: [
+        "Which way an arrow points — the relationship kinds",
+        "The legend",
+        "Overview views that read",
+        "A feature's message flows",
+    ],
+    body: `Drawing the fleet so that a person can read it: one relationship kind per kind of traffic, an arrow only where evidence gives one, a legend, and overview views that each answer one question.
+
+Nothing on this page is graded. loam reads elements and relationships, never a
+view, and no check reads a relationship's kind — so a map can validate clean
+and still be a wall of tiny boxes joined by gray lines. Every spelling below was
+measured at the LikeC4 1.59.2 pin loam ships.
+
+## Which way an arrow points — the relationship kinds
+
+A plain \`->\` says only that two things are connected. A fleet drawn from
+deployment configuration, which says nothing more than that, ends with every
+arrow pointing into the broker and the stores. So give every relationship ONE
+kind, and give each kind one meaning:
+
+- \`publishes\` — producer \`->\` topic, with \`metadata { publishes '<message>' }\`:
+  the producer puts the message on the topic.
+- \`delivers\` — topic \`->\` consumer, with \`metadata { consumes '<message>' }\`:
+  the broker hands the message to the consumer.
+- \`reads\` — service \`->\` store, its head drawn at the SERVICE end (a tail
+  arrow): data flows out of the store into the service.
+- \`writes\` — service \`->\` store, its head at the store: data lands in the store.
+- \`readsWrites\` — service \`->\` store, heads at both ends: both.
+- \`calls\` — caller \`->\` provider, with \`metadata { op '<operationId>' }\`: a
+  synchronous request.
+- \`connects\` — gray, dashed, no arrowhead: a connection whose direction nobody
+  has established yet.
+
+For the store kinds the arrowhead is where the data lands, and putting it there
+is the style's job, never the arrow's: a store edge is ALWAYS written
+service \`->\` store, and a read gets its head at the service end from the
+\`reads\` style. Never flip a store edge to show a read. \`Covers:\` names an
+edge as \`a -> b\`, review order reads a plain edge's source as depending on its
+target, and the consumer census behind \`landscape.datastore-shared\` reads both
+directions only for an element whose kind is \`database\`, \`queue\`, \`topic\`,
+\`cache\` or \`bucket\` — a store drawn as any other kind has a service for a
+consumer only when the store is the edge's TARGET. SCHEMA.md, "Which way an edge
+points", lists every reader.
+
+**Never guess a direction.** Give an edge a direction only from evidence:
+
+- the service's code: the client that sends, the listener that receives, the
+  repository that writes;
+- a configuration name that says which side the service is on —
+  \`*_PRODUCER_*\`, \`*_CONSUMER_*\`, a consumer-group id;
+- the service's own \`asyncapi.yaml\`: \`action: send\` publishes,
+  \`action: receive\` consumes.
+
+Configuration that lists a broker address or a database URL says only that the
+two are connected: draw that as \`connects\`. A \`connects\` edge is an honest
+placeholder, not a defect, and adopting the service from its code is what turns
+it into a real kind (\`loam instructions loam-adopt <id>\`, step 3). A guessed
+\`publishes\` is worse than a \`connects\`: it reads exactly like a right one, it
+binds the event spine, and nobody goes back to check it.
+
+Declare the kinds once, in \`architecture/landscape.likec4\`'s own
+\`specification\` block, where every extending model borrows them:
+
+    specification {
+      relationship publishes {
+        color amber
+        line solid
+        head normal
+      }
+      relationship delivers {
+        color amber
+        line solid
+        head normal
+      }
+      relationship reads {
+        color green
+        head none
+        tail normal
+      }
+      relationship writes {
+        color green
+        head normal
+      }
+      relationship readsWrites {
+        color green
+        head normal
+        tail normal
+      }
+      relationship calls {
+        color secondary
+        line solid
+        head normal
+      }
+      relationship connects {
+        color gray
+        line dashed
+        head none
+        tail odot
+      }
+    }
+
+Then name the kind in brackets on each edge:
+
+    marketplace.checkoutWeb -[calls]-> marketplace.orderService 'createOrder' {
+      metadata { op 'createOrder' }
+    }
+    marketplace.orderService -[publishes]-> kafka.orderEvents 'OrderPlaced' {
+      metadata { publishes 'order.OrderPlaced' }
+    }
+    kafka.orderEvents -[delivers]-> marketplace.paymentService 'OrderPlaced' {
+      metadata { consumes 'order.OrderPlaced' }
+    }
+    marketplace.paymentService -[reads]-> marketplace.ordersDb 'order totals'
+    marketplace.orderService -[connects]-> kafka 'broker address in its deployment config'
+
+A store a service owns and nests INSIDE its own element cannot take an edge from
+that element: LikeC4 refuses a relationship between a parent and its child
+("Invalid parent-child relationship"). Draw that edge from the container that
+does the work, in the service's own model
+(\`marketplace.orderService.api -[readsWrites]-> marketplace.orderService.db\`),
+or draw the store beside the service.
+
+A feature's \`delta.likec4\` parses on its own, so it declares every kind it
+draws in its own \`specification\` block too. **The living map must declare that
+kind BEFORE the feature archives.** \`loam archive\` copies the edge into
+\`architecture/landscape.likec4\` as written and never copies a declaration.
+When the map lacks the kind, the merged map does not parse and the archive
+refuses with \`merge-failed\` ("Could not resolve reference to
+RelationshipKind"), while \`loam validate --feature\` and \`loam status\` still
+called the feature ready. A kind is vocabulary, not a change, so adding it to the
+map's \`specification\` is an ordinary edit to the living map, made in its own
+change.
+
+Two spellings to avoid:
+
+- **Never put a tag on a kind** (\`relationship publishes { #async }\`). LikeC4
+  copies a kind's tags onto every edge of that kind. A \`#<FEAT>\` there makes
+  every such edge in the delta part of the change, context included, and an
+  \`#obl-\` tag there claims the obligation for every edge of that kind. Tag the
+  edge instead.
+- **Never use the dotted form** (\`orderService .publishes kafka.orderEvents\`).
+  LikeC4 reads it, but not every loam reader does: \`loam validate --base\` scans
+  an extending model without the map's kinds and does not see such an edge.
+  Write \`-[publishes]->\`.
+
+\`connects\` carries \`tail odot\` on purpose. An edge with no arrowhead at either
+end is laid out with \`constraint=false\` and \`minlen=0\`, and enough of them
+collapse a view into one band. The small circle at the source keeps the edge in
+the layout without claiming a direction.
+
+The kind is the picture and the metadata is the join. \`metadata { op }\`,
+\`publishes\` and \`consumes\` are what loam grades (\`loam instructions loam-spine\`).
+A kind changes no grade, so a kind with no metadata beside it is a drawing that
+nothing checks.
+
+## The legend
+
+Add a \`legend\` view to \`architecture/landscape.likec4\` that draws ONE real
+edge of each kind the map uses. Use real services, a real topic and a real store,
+so that a reader learns the colours from the fleet itself. Name each edge by
+both of its endpoints:
+
+    view legend {
+      title 'Fleet / 0 · Legend'
+      include marketplace.checkoutWeb -> marketplace.orderService
+      include marketplace.orderService -> kafka.orderEvents
+      include kafka.orderEvents -> marketplace.paymentService
+      include marketplace.paymentService -> marketplace.ordersDb
+    }
+
+A view can name only elements the model declares, so the legend is written once
+the map has real edges of each kind, and it gains a line when the map gains a
+kind. \`loam init\` cannot scaffold one, because an empty map has nothing to draw.
+
+## Overview views that read
+
+A view is a picture for one reader with one question. Every rule below comes
+from an overview that drew the whole fleet and so showed nothing:
+
+- **One question per view, at one altitude.** "Who publishes to the broker?" is
+  one view, and "who calls whom" is another. A fleet overview draws subsystem
+  boxes, not services: the generated \`architecture/subsystems.likec4\` and
+  \`architecture/services.likec4\` views are the drill-down. Aim for at most
+  about 20 nodes and 25 drawn lines.
+- **Filter by ONE kind, and say it positively.** A view above service altitude
+  merges every relationship between two boxes into one drawn line. When those
+  relationships are of different kinds, LikeC4 falls back to the default gray
+  and the line says nothing. \`where kind is publishes\` keeps the line amber;
+  \`where kind is not calls\` and \`where kind is publishes or kind is connects\`
+  still merge into gray.
+- **Know the form that draws nothing.** Where \`fleet\`'s children are subsystem
+  groups, \`include fleet.* -> * where kind is publishes\` renders an EMPTY view,
+  with no error. Use a unary form, a named target or a tag target instead:
+
+      include fleet.* -> where kind is publishes
+      include fleet.* -> element.tag = #broker where kind is publishes
+      include kafka -> fleet.* where kind is delivers
+      include -> fleet.* where kind is delivers
+
+- **Prefer relationship rules to element lists.** An element included directly
+  brings every relationship between it and the others: \`include fleet.orders, kafka\`
+  draws one merged gray line, where
+  \`include fleet.orders -> where kind is publishes\` draws one amber line.
+- **Lay out rows with \`rank\`.** \`rank source { … }\`, \`rank same { … }\` and
+  \`rank sink { … }\` put nodes in rows, and the braces are required. A
+  \`rank source\` row whose nodes' edges all point INTO them is ignored, so a row
+  of consumers belongs at \`sink\`.
+- **Give a direction-less edge a marker.** An edge with no arrowhead at either
+  end is laid out unconstrained and collapses the view into one band, so give it
+  \`tail odot\`, as the \`connects\` style above does.
+- **Titles make folders.** LikeC4 splits a title on \`/\` into browser folders
+  and lists sub-folders before views, so number the views you want read in
+  order: \`title 'Fleet / 1 · Who publishes'\`.
+- **Never author \`view … of\` a subsystem or service element.** The generated
+  views own that drill-down, and an authored one in a file that sorts before
+  them — \`landscape.likec4\` does — takes the click from every other view that
+  draws the element.
+- **No \`xs\` nodes across a whole fleet, and no \`include parent.**\` with
+  excludes.** Together they drew a 68-node band at 2.5 pixels per label, a view
+  nobody can read.
+
+## A feature's message flows
+
+A feature delta draws a message the way the map does: through the broker. Write
+\`orderService -[publishes]-> kafka.orderEvents\` and
+\`kafka.orderEvents -[delivers]-> notificationService\`, never
+\`orderService -> notificationService\` for an event. A direct edge reads as a
+call, sits outside the event spine, and draws a second picture of the topic the
+map already draws. Point at the topic the living map nests in the broker, leave
+that context untagged, and tag only the edges the feature adds.
+
+A producer outside the fleet is an \`#external\` element, and the edge it
+publishes on carries the metadata (\`loam instructions loam-spine\`, "A message
+produced outside the fleet", has the full join):
+
+    crm = softwareSystem 'crm' {
+      #external
+    }
+    crm -[publishes]-> kafka.crmEvents 'CustomerUpdated' {
+      metadata { publishes 'crm.CustomerUpdated' }
+    }
+`,
+};
+//# sourceMappingURL=drawing.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"drawing.js","sourceRoot":"","sources":["../../../../../../src/core/agent/workflows/reference/drawing/drawing.ts"],"names":[],"mappings":"AA6BA,MAAM,CAAC,MAAM,YAAY,GAAmB;IAC1C,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,qIAAqI;IACvI,2EAA2E;IAC3E,4CAA4C;IAC5C,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,wOAAwO;IAC1O,UAAU,EAAE,gCAAgC;IAC5C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE;QACL,oDAAoD;QACpD,YAAY;QACZ,0BAA0B;QAC1B,2BAA2B;KAC5B;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2OP;CACA,CAAC","sourcesContent":["/**\n * The `loam-drawing` reference page: how to draw the C4 model so that a person\n * can read the picture — one relationship kind per kind of traffic, an arrow\n * that points where the evidence says, a legend, and overview views that each\n * answer one question.\n *\n * WHY A PAGE. A large real fleet was drawn by agents following loam's pages,\n * and every document validated while the pictures were unreadable: every arrow\n * pointed into the broker and the stores (deployment configuration says only\n * that two things are connected, and the agents turned that into a direction),\n * the overview views were walls of tiny boxes, and the lines were the default\n * gray because LikeC4 merges relationships of different kinds into one line\n * with no style. Nothing loam grades could have caught any of it — loam reads\n * elements and relationships and never a view, and no check reads a\n * relationship's KIND — so the only place the lesson can live is the text an\n * agent reads before it draws. That text is consulted at a moment the agent\n * can name (\"I am drawing an edge\", \"I am writing a view\"), which is the split\n * rule in ../reference.ts: a reference page, not AGENTS.md.\n *\n * WHY ITS OWN PACKAGE. ../ sits at the five-file cap, and this page is a\n * subject of its own rather than a section of an existing one: loam-spine says\n * which joins the metadata makes, and this page says how the picture is drawn\n * around them. Every LikeC4 spelling below was measured at the 1.59.2 pin\n * (`likec4 validate`, `export json`, `gen dot`) on a neutral fleet shaped like\n * examples/docs — never on the fleet the lesson came from, which is\n * confidential and must not reach this repository in any form.\n */\nimport type { CommandContent } from \"../../../contract.js\";\n\nexport const LOAM_DRAWING: CommandContent = {\n  name: \"loam-drawing\",\n  description:\n    \"Reference: drawing the map so a person can read it — relationship kinds and which way each arrow points, the legend, overview views\",\n  // A reference page takes no arguments: see ../spine.ts for why the hint is\n  // empty rather than a spelled-out \"<none>\".\n  argumentHint: \"\",\n  purpose:\n    \"How to draw the C4 model so the picture reads: one relationship kind per kind of traffic and an arrow only where evidence gives one, a legend drawn from real edges, and overview views that each answer one question at one altitude.\",\n  invocation: \"loam instructions loam-drawing\",\n  placeholders: [],\n  spine: [\n    \"Which way an arrow points — the relationship kinds\",\n    \"The legend\",\n    \"Overview views that read\",\n    \"A feature's message flows\",\n  ],\n  body: `Drawing the fleet so that a person can read it: one relationship kind per kind of traffic, an arrow only where evidence gives one, a legend, and overview views that each answer one question.\n\nNothing on this page is graded. loam reads elements and relationships, never a\nview, and no check reads a relationship's kind — so a map can validate clean\nand still be a wall of tiny boxes joined by gray lines. Every spelling below was\nmeasured at the LikeC4 1.59.2 pin loam ships.\n\n## Which way an arrow points — the relationship kinds\n\nA plain \\`->\\` says only that two things are connected. A fleet drawn from\ndeployment configuration, which says nothing more than that, ends with every\narrow pointing into the broker and the stores. So give every relationship ONE\nkind, and give each kind one meaning:\n\n- \\`publishes\\` — producer \\`->\\` topic, with \\`metadata { publishes '<message>' }\\`:\n  the producer puts the message on the topic.\n- \\`delivers\\` — topic \\`->\\` consumer, with \\`metadata { consumes '<message>' }\\`:\n  the broker hands the message to the consumer.\n- \\`reads\\` — service \\`->\\` store, its head drawn at the SERVICE end (a tail\n  arrow): data flows out of the store into the service.\n- \\`writes\\` — service \\`->\\` store, its head at the store: data lands in the store.\n- \\`readsWrites\\` — service \\`->\\` store, heads at both ends: both.\n- \\`calls\\` — caller \\`->\\` provider, with \\`metadata { op '<operationId>' }\\`: a\n  synchronous request.\n- \\`connects\\` — gray, dashed, no arrowhead: a connection whose direction nobody\n  has established yet.\n\nFor the store kinds the arrowhead is where the data lands, and putting it there\nis the style's job, never the arrow's: a store edge is ALWAYS written\nservice \\`->\\` store, and a read gets its head at the service end from the\n\\`reads\\` style. Never flip a store edge to show a read. \\`Covers:\\` names an\nedge as \\`a -> b\\`, review order reads a plain edge's source as depending on its\ntarget, and the consumer census behind \\`landscape.datastore-shared\\` reads both\ndirections only for an element whose kind is \\`database\\`, \\`queue\\`, \\`topic\\`,\n\\`cache\\` or \\`bucket\\` — a store drawn as any other kind has a service for a\nconsumer only when the store is the edge's TARGET. SCHEMA.md, \"Which way an edge\npoints\", lists every reader.\n\n**Never guess a direction.** Give an edge a direction only from evidence:\n\n- the service's code: the client that sends, the listener that receives, the\n  repository that writes;\n- a configuration name that says which side the service is on —\n  \\`*_PRODUCER_*\\`, \\`*_CONSUMER_*\\`, a consumer-group id;\n- the service's own \\`asyncapi.yaml\\`: \\`action: send\\` publishes,\n  \\`action: receive\\` consumes.\n\nConfiguration that lists a broker address or a database URL says only that the\ntwo are connected: draw that as \\`connects\\`. A \\`connects\\` edge is an honest\nplaceholder, not a defect, and adopting the service from its code is what turns\nit into a real kind (\\`loam instructions loam-adopt <id>\\`, step 3). A guessed\n\\`publishes\\` is worse than a \\`connects\\`: it reads exactly like a right one, it\nbinds the event spine, and nobody goes back to check it.\n\nDeclare the kinds once, in \\`architecture/landscape.likec4\\`'s own\n\\`specification\\` block, where every extending model borrows them:\n\n    specification {\n      relationship publishes {\n        color amber\n        line solid\n        head normal\n      }\n      relationship delivers {\n        color amber\n        line solid\n        head normal\n      }\n      relationship reads {\n        color green\n        head none\n        tail normal\n      }\n      relationship writes {\n        color green\n        head normal\n      }\n      relationship readsWrites {\n        color green\n        head normal\n        tail normal\n      }\n      relationship calls {\n        color secondary\n        line solid\n        head normal\n      }\n      relationship connects {\n        color gray\n        line dashed\n        head none\n        tail odot\n      }\n    }\n\nThen name the kind in brackets on each edge:\n\n    marketplace.checkoutWeb -[calls]-> marketplace.orderService 'createOrder' {\n      metadata { op 'createOrder' }\n    }\n    marketplace.orderService -[publishes]-> kafka.orderEvents 'OrderPlaced' {\n      metadata { publishes 'order.OrderPlaced' }\n    }\n    kafka.orderEvents -[delivers]-> marketplace.paymentService 'OrderPlaced' {\n      metadata { consumes 'order.OrderPlaced' }\n    }\n    marketplace.paymentService -[reads]-> marketplace.ordersDb 'order totals'\n    marketplace.orderService -[connects]-> kafka 'broker address in its deployment config'\n\nA store a service owns and nests INSIDE its own element cannot take an edge from\nthat element: LikeC4 refuses a relationship between a parent and its child\n(\"Invalid parent-child relationship\"). Draw that edge from the container that\ndoes the work, in the service's own model\n(\\`marketplace.orderService.api -[readsWrites]-> marketplace.orderService.db\\`),\nor draw the store beside the service.\n\nA feature's \\`delta.likec4\\` parses on its own, so it declares every kind it\ndraws in its own \\`specification\\` block too. **The living map must declare that\nkind BEFORE the feature archives.** \\`loam archive\\` copies the edge into\n\\`architecture/landscape.likec4\\` as written and never copies a declaration.\nWhen the map lacks the kind, the merged map does not parse and the archive\nrefuses with \\`merge-failed\\` (\"Could not resolve reference to\nRelationshipKind\"), while \\`loam validate --feature\\` and \\`loam status\\` still\ncalled the feature ready. A kind is vocabulary, not a change, so adding it to the\nmap's \\`specification\\` is an ordinary edit to the living map, made in its own\nchange.\n\nTwo spellings to avoid:\n\n- **Never put a tag on a kind** (\\`relationship publishes { #async }\\`). LikeC4\n  copies a kind's tags onto every edge of that kind. A \\`#<FEAT>\\` there makes\n  every such edge in the delta part of the change, context included, and an\n  \\`#obl-\\` tag there claims the obligation for every edge of that kind. Tag the\n  edge instead.\n- **Never use the dotted form** (\\`orderService .publishes kafka.orderEvents\\`).\n  LikeC4 reads it, but not every loam reader does: \\`loam validate --base\\` scans\n  an extending model without the map's kinds and does not see such an edge.\n  Write \\`-[publishes]->\\`.\n\n\\`connects\\` carries \\`tail odot\\` on purpose. An edge with no arrowhead at either\nend is laid out with \\`constraint=false\\` and \\`minlen=0\\`, and enough of them\ncollapse a view into one band. The small circle at the source keeps the edge in\nthe layout without claiming a direction.\n\nThe kind is the picture and the metadata is the join. \\`metadata { op }\\`,\n\\`publishes\\` and \\`consumes\\` are what loam grades (\\`loam instructions loam-spine\\`).\nA kind changes no grade, so a kind with no metadata beside it is a drawing that\nnothing checks.\n\n## The legend\n\nAdd a \\`legend\\` view to \\`architecture/landscape.likec4\\` that draws ONE real\nedge of each kind the map uses. Use real services, a real topic and a real store,\nso that a reader learns the colours from the fleet itself. Name each edge by\nboth of its endpoints:\n\n    view legend {\n      title 'Fleet / 0 · Legend'\n      include marketplace.checkoutWeb -> marketplace.orderService\n      include marketplace.orderService -> kafka.orderEvents\n      include kafka.orderEvents -> marketplace.paymentService\n      include marketplace.paymentService -> marketplace.ordersDb\n    }\n\nA view can name only elements the model declares, so the legend is written once\nthe map has real edges of each kind, and it gains a line when the map gains a\nkind. \\`loam init\\` cannot scaffold one, because an empty map has nothing to draw.\n\n## Overview views that read\n\nA view is a picture for one reader with one question. Every rule below comes\nfrom an overview that drew the whole fleet and so showed nothing:\n\n- **One question per view, at one altitude.** \"Who publishes to the broker?\" is\n  one view, and \"who calls whom\" is another. A fleet overview draws subsystem\n  boxes, not services: the generated \\`architecture/subsystems.likec4\\` and\n  \\`architecture/services.likec4\\` views are the drill-down. Aim for at most\n  about 20 nodes and 25 drawn lines.\n- **Filter by ONE kind, and say it positively.** A view above service altitude\n  merges every relationship between two boxes into one drawn line. When those\n  relationships are of different kinds, LikeC4 falls back to the default gray\n  and the line says nothing. \\`where kind is publishes\\` keeps the line amber;\n  \\`where kind is not calls\\` and \\`where kind is publishes or kind is connects\\`\n  still merge into gray.\n- **Know the form that draws nothing.** Where \\`fleet\\`'s children are subsystem\n  groups, \\`include fleet.* -> * where kind is publishes\\` renders an EMPTY view,\n  with no error. Use a unary form, a named target or a tag target instead:\n\n      include fleet.* -> where kind is publishes\n      include fleet.* -> element.tag = #broker where kind is publishes\n      include kafka -> fleet.* where kind is delivers\n      include -> fleet.* where kind is delivers\n\n- **Prefer relationship rules to element lists.** An element included directly\n  brings every relationship between it and the others: \\`include fleet.orders, kafka\\`\n  draws one merged gray line, where\n  \\`include fleet.orders -> where kind is publishes\\` draws one amber line.\n- **Lay out rows with \\`rank\\`.** \\`rank source { … }\\`, \\`rank same { … }\\` and\n  \\`rank sink { … }\\` put nodes in rows, and the braces are required. A\n  \\`rank source\\` row whose nodes' edges all point INTO them is ignored, so a row\n  of consumers belongs at \\`sink\\`.\n- **Give a direction-less edge a marker.** An edge with no arrowhead at either\n  end is laid out unconstrained and collapses the view into one band, so give it\n  \\`tail odot\\`, as the \\`connects\\` style above does.\n- **Titles make folders.** LikeC4 splits a title on \\`/\\` into browser folders\n  and lists sub-folders before views, so number the views you want read in\n  order: \\`title 'Fleet / 1 · Who publishes'\\`.\n- **Never author \\`view … of\\` a subsystem or service element.** The generated\n  views own that drill-down, and an authored one in a file that sorts before\n  them — \\`landscape.likec4\\` does — takes the click from every other view that\n  draws the element.\n- **No \\`xs\\` nodes across a whole fleet, and no \\`include parent.**\\` with\n  excludes.** Together they drew a 68-node band at 2.5 pixels per label, a view\n  nobody can read.\n\n## A feature's message flows\n\nA feature delta draws a message the way the map does: through the broker. Write\n\\`orderService -[publishes]-> kafka.orderEvents\\` and\n\\`kafka.orderEvents -[delivers]-> notificationService\\`, never\n\\`orderService -> notificationService\\` for an event. A direct edge reads as a\ncall, sits outside the event spine, and draws a second picture of the topic the\nmap already draws. Point at the topic the living map nests in the broker, leave\nthat context untagged, and tag only the edges the feature adds.\n\nA producer outside the fleet is an \\`#external\\` element, and the edge it\npublishes on carries the metadata (\\`loam instructions loam-spine\\`, \"A message\nproduced outside the fleet\", has the full join):\n\n    crm = softwareSystem 'crm' {\n      #external\n    }\n    crm -[publishes]-> kafka.crmEvents 'CustomerUpdated' {\n      metadata { publishes 'crm.CustomerUpdated' }\n    }\n`,\n};\n"]}

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

@@ -1,16 +1,19 @@
 import { LOAM_AUTHORING } from "./authoring.js";
 import { LOAM_CODES } from "./codes.js";
 import { LOAM_DONE_CHECK } from "./done-check.js";
+import { LOAM_DRAWING } from "./drawing/drawing.js";
 import { LOAM_SPINE } from "./spine.js";
 /**
- * The four pages, in the order AGENTS.md's own index names them — which is the
- * order their sections stood in the document they left, so a reader who knew
- * the file finds them where they were.
+ * The five pages, in the order AGENTS.md's own index names them. The first four
+ * stand in the order their sections stood in the document they left, so a
+ * reader who knew the file finds them where they were. The drawing page comes
+ * last because it never stood there.
  */
 export const REFERENCES = [
     LOAM_CODES,
     LOAM_SPINE,
     LOAM_AUTHORING,
     LOAM_DONE_CHECK,
+    LOAM_DRAWING,
 ];
 //# sourceMappingURL=reference.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../../../../src/core/agent/workflows/reference/reference.ts"],"names":[],"mappings":"AAwDA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAqB;IAC1C,UAAU;IACV,UAAU;IACV,cAAc;IACd,eAAe;CAChB,CAAC","sourcesContent":["/**\n * Why the reference pages exist, what decided which content became one, and the\n * list itself.\n *\n * THE MEASUREMENT. AGENTS.md is auto-loaded from the working directory by every\n * agents.md-aware host, on every session, and `loam init` writes it once and\n * never refreshes it. It had reached 109,399 bytes. Codex truncates the\n * AGENTS.md chain at 32,768 bytes and Windsurf caps a workspace rule file at\n * 12,000 characters — both silently, with no error and no way for the reader to\n * tell which half it was holding. Roughly seventy percent of the document was\n * being dropped on those two hosts, and which seventy percent depended on the\n * host rather than on what the reader needed.\n *\n * THE SPLIT RULE, which is not \"move the big parts\". Two kinds of content were\n * mixed in one file:\n *\n *  - what a reader needs to FORM a question — the layout, the cycle, which\n *    element is which service, what gates and what only advises, what the words\n *    mean. Without it an agent cannot ask anything, so it cannot be behind a\n *    command it does not know to run. That stays in AGENTS.md;\n *  - what a reader CONSULTS at a moment it can name — the grammars for writing\n *    one document, the inventory of what a command can report, the done-check's\n *    channels. The moment is nameable (\"I am writing an arch.spec.md\", \"a run\n *    reported something\"), so the page can be fetched then, and paying for it on\n *    every invocation of every session bought nothing.\n *\n * That rule is why `## Which element IS which service` stayed behind in\n * ../../agents-md/spine.ts while the rest of the ID spine left, and why the\n * per-invocation code inventory left while the three facts about the `--json`\n * envelope stayed. Size followed from the rule; it did not drive it.\n *\n * WHAT A PAGE COSTS AND WHAT IT BUYS. A page printed by the binary describes\n * the loam you are about to run, not the one that scaffolded the repository —\n * which is strictly better than a file `loam init` writes once and never\n * refreshes, and is why `agents.stale` exists at all. What it costs is\n * discoverability: a reference nobody can find is content deleted with extra\n * steps. Three things pay that back, and all three are asserted rather than\n * hoped for — AGENTS.md's own \"The reference pages\" section names each page\n * with the exact command (test/agents.test.ts), bare `loam instructions` lists\n * them beside the workflows (test/instructions.test.ts), and every stable code\n * that left is still in the corpus test/codes-drift.test.ts reads, because\n * {@link REFERENCES} feeds `PROTOCOLS`.\n *\n * WHAT A PAGE IS NOT. It is not a workflow. It has no steps, takes no\n * arguments, and `loam init` writes NO file for it — ../../protocol.ts feeds\n * this list to `PROTOCOLS` and `placeholderProblems` and to nothing else, so\n * `SLASH_COMMANDS` and `plannedCommandFiles` never see it and no repository\n * gains a generated artifact. Four pages are four more files in every repo loam\n * touches, and the whole point of the move was to stop shipping bytes nobody\n * asked for.\n *\n * THE MOVE WAS A MOVE. Every page's text is its AGENTS.md section verbatim.\n * Nothing was rewritten on the way, because a paraphrase is a second copy that\n * can drift — and removing one of those is what this whole change is for.\n */\nimport type { CommandContent } from \"../../contract.js\";\nimport { LOAM_AUTHORING } from \"./authoring.js\";\nimport { LOAM_CODES } from \"./codes.js\";\nimport { LOAM_DONE_CHECK } from \"./done-check.js\";\nimport { LOAM_SPINE } from \"./spine.js\";\n\n/**\n * The four pages, in the order AGENTS.md's own index names them — which is the\n * order their sections stood in the document they left, so a reader who knew\n * the file finds them where they were.\n */\nexport const REFERENCES: CommandContent[] = [\n  LOAM_CODES,\n  LOAM_SPINE,\n  LOAM_AUTHORING,\n  LOAM_DONE_CHECK,\n];\n"]}
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../../../../src/core/agent/workflows/reference/reference.ts"],"names":[],"mappings":"AAiEA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAqB;IAC1C,UAAU;IACV,UAAU;IACV,cAAc;IACd,eAAe;IACf,YAAY;CACb,CAAC","sourcesContent":["/**\n * Why the reference pages exist, what decided which content became one, and the\n * list itself.\n *\n * THE MEASUREMENT. AGENTS.md is auto-loaded from the working directory by every\n * agents.md-aware host, on every session, and `loam init` writes it once and\n * never refreshes it. It had reached 109,399 bytes. Codex truncates the\n * AGENTS.md chain at 32,768 bytes and Windsurf caps a workspace rule file at\n * 12,000 characters — both silently, with no error and no way for the reader to\n * tell which half it was holding. Roughly seventy percent of the document was\n * being dropped on those two hosts, and which seventy percent depended on the\n * host rather than on what the reader needed.\n *\n * THE SPLIT RULE, which is not \"move the big parts\". Two kinds of content were\n * mixed in one file:\n *\n *  - what a reader needs to FORM a question — the layout, the cycle, which\n *    element is which service, what gates and what only advises, what the words\n *    mean. Without it an agent cannot ask anything, so it cannot be behind a\n *    command it does not know to run. That stays in AGENTS.md;\n *  - what a reader CONSULTS at a moment it can name — the grammars for writing\n *    one document, the inventory of what a command can report, the done-check's\n *    channels. The moment is nameable (\"I am writing an arch.spec.md\", \"a run\n *    reported something\"), so the page can be fetched then, and paying for it on\n *    every invocation of every session bought nothing.\n *\n * That rule is why the binding rule — which element IS which service — stayed\n * in AGENTS.md while the rest of the ID spine left (it is ORIENTATION's\n * `## The identity rule` in ../../agents-md.ts now, condensed from the section\n * that used to stay behind), and why the per-invocation code inventory left\n * while the facts about the `--json` envelope stayed. Size followed from the\n * rule; it did not drive it.\n *\n * WHAT A PAGE COSTS AND WHAT IT BUYS. A page printed by the binary describes\n * the loam you are about to run, not the one that scaffolded the repository —\n * which is strictly better than a file `loam init` writes once and never\n * refreshes, and is why `agents.stale` exists at all. What it costs is\n * discoverability: a reference nobody can find is content deleted with extra\n * steps. Three things pay that back, and all three are asserted rather than\n * hoped for — AGENTS.md's own \"Reference pages\" section names each page\n * with the exact command (test/agents.test.ts), bare `loam instructions` lists\n * them beside the workflows (test/instructions.test.ts), and every stable code\n * that left is still in the corpus test/codes-drift.test.ts reads, because\n * {@link REFERENCES} feeds `PROTOCOLS`.\n *\n * WHAT A PAGE IS NOT. It is not a workflow. It has no steps, takes no\n * arguments, and `loam init` writes NO file for it — ../../protocol.ts feeds\n * this list to `PROTOCOLS` and `placeholderProblems` and to nothing else, so\n * `SLASH_COMMANDS` and `plannedCommandFiles` never see it and no repository\n * gains a generated artifact. Four pages are four more files in every repo loam\n * touches, and the whole point of the move was to stop shipping bytes nobody\n * asked for.\n *\n * THE MOVE WAS A MOVE. Every page's text is its AGENTS.md section verbatim.\n * Nothing was rewritten on the way, because a paraphrase is a second copy that\n * can drift — and removing one of those is what this whole change is for.\n *\n * THE FIFTH PAGE WAS NEVER A SECTION. `loam-drawing` (./drawing/drawing.ts)\n * was written as a page from the start: how to draw the map so that a person\n * can read it is consulted at the moment an edge or a view is drawn, which is\n * the split rule above, and no AGENTS.md section ever held it. It came from a\n * real fleet whose documents all validated while every picture of it was\n * unreadable. The page carries the rest of that story.\n */\nimport type { CommandContent } from \"../../contract.js\";\nimport { LOAM_AUTHORING } from \"./authoring.js\";\nimport { LOAM_CODES } from \"./codes.js\";\nimport { LOAM_DONE_CHECK } from \"./done-check.js\";\nimport { LOAM_DRAWING } from \"./drawing/drawing.js\";\nimport { LOAM_SPINE } from \"./spine.js\";\n\n/**\n * The five pages, in the order AGENTS.md's own index names them. The first four\n * stand in the order their sections stood in the document they left, so a\n * reader who knew the file finds them where they were. The drawing page comes\n * last because it never stood there.\n */\nexport const REFERENCES: CommandContent[] = [\n  LOAM_CODES,\n  LOAM_SPINE,\n  LOAM_AUTHORING,\n  LOAM_DONE_CHECK,\n  LOAM_DRAWING,\n];\n"]}

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

@@ -101,9 +101,12 @@ heading refuses the archive here as it does in a spec delta, and
 \`spec.md\` — an empty one is not a delta, so the merge would carry nothing.
 \`loam archive\` merges it into the living document in the same
 transaction as the service merge, creating \`capabilities/<id>/spec.md\` — and
-so the whole tree — when this is the first feature to mention it; the heading
-is the id and the narrative above \`## Requirements\` is yours to write, because
-loam merges requirements and never prose. The document's three rules above are
+so the whole tree — when this is the first feature to mention it. Only what
+the delta marks as the document's own comes across: its H1 as the title
+(unless it names the feature or calls itself a delta — then the title is the
+id), its \`## Purpose\` section as the narrative, and a line linking back to the
+archived delta for everything else, because loam merges requirements and never
+prose; after that the narrative is yours to edit in place. The document's three rules above are
 graded on the delta BEFORE the merge, so a capability requirement filed at the
 wrong altitude is refused while you still hold it. Editing the living document
 directly is still legal; the delta is what makes two features touching one
@@ -199,16 +202,44 @@ the shape that reverts someone else's landed change at exit 0. A migrated
 corpus is not stranded by this: \`loam rebase <FEAT>\` pins every delta in one
 command, and a human's \`--approve\` archives unpinned when the loss is meant.
 
-### The same pin on the contract axis — and why it matters more there
-
-A feature's \`openapi.yaml\` is a COMPLETE document, not a patch: you restate the
-living contract around the slot you are changing, and the merge upserts every
-operation the document spells. So the collision on this axis needs no overlap at
-all. Two features touching one service, editing DIFFERENT operations, destroy
-each other — the second to archive quietly pushes its authoring-time copy of the
-operation it never meant to touch back over whatever landed in between.
-
-The same marker fixes it, as a vendor extension beside \`x-loam-remove\`:
+### The same pin on the contract axis
+
+A feature's \`openapi.yaml\` is a self-contained document holding ONLY what the
+feature adds, changes or removes — not a copy of the living contract. The merge
+walks only the paths and methods the delta spells: an operation you leave out
+stays exactly as the living contract has it, a local \`$ref\`
+(\`#/components/schemas/Order\`) resolves into the living document, and a new
+operation has no living version to pin — an add-only delta needs no rebase.
+
+What the merge does upsert is every operation the document DOES spell. So an
+operation you quote without changing it — copied for context, or a whole
+contract pasted in — is a collision waiting for someone else's edit: two
+features over one service, each quoting the operation the other edits, destroy
+each other, and the second to archive pushes its authoring-time copy back over
+whatever landed in between. Quote nothing you do not change. Each quote costs a
+pin, and a parallel feature that REMOVES the quoted operation makes it worse
+either way: pinned, the quote is \`openapi.baseline-invalid\`, an error that
+blocks your archive, and \`openapi.op-revived\` beside it; unpinned, it is
+\`openapi.op-revived\` alone — a warning that gates, because the merge would
+read the dead operation as a new one and put it back (\`asyncapi.slot-revived\`
+is the same finding on a channel, operation or message slot). A parallel
+feature that MOVES the operation to another address does the same to a quote
+of the old one, which archived would answer the operationId at both. The fix
+for both is to delete the quote. Keep it only when the feature brings a
+retired operation back ON PURPOSE: then drop any pin, and a human archives
+with \`--approve\`. \`loam rebase\` never pins a retired operation as new —
+nothing lives at its slot, so there is no version to pin — and prints the same
+finding (\`revived[]\` in \`--json\`), so the decision stays with you. It judges
+the delta as it will write it, pins included: a quote of an address another
+operation lives at now — one a move vacated, since re-occupied — IS repinned,
+over the operation living there, which makes it an edit the merge would write;
+the revival that edit makes is reported by that rebase (or its \`--dry-run\`),
+not first by the next validate. The check reads the removal
+markers of the features under \`features/archive/\` — a removal made by
+hand-editing a living contract is invisible to it.
+
+The guard against that collision, for every living operation the delta does
+spell, is a pin — a vendor extension beside \`x-loam-remove\`:
 
 \`\`\`yaml
 paths:
@@ -218,8 +249,9 @@ paths:
       x-loam-based-on: 86feabe621ed887d
 \`\`\`
 
-\`loam rebase\` writes one on EVERY operation in the delta, pinned to the living
-version. That is what lets the merge tell a QUOTE from an EDIT:
+\`loam rebase\` writes one on every operation in the delta the living contract
+already holds, pinned to the living version; what the feature adds gets none.
+That is what lets the merge tell a QUOTE from an EDIT:
 
 - pin equals the operation's own content → you quoted it → **the merge skips it
   entirely** and the living contract keeps whatever it holds. Archive prints
@@ -228,12 +260,15 @@ version. That is what lets the merge tell a QUOTE from an EDIT:
 - pin matches neither → you edited it AND somebody landed a change to it →
   \`openapi.baseline-stale\`, refused.
 
-Not covered, deliberately, and worth knowing: path-level keys (\`parameters\`,
-\`servers\`) and \`components/schemas\` are still upserted wholesale, so a restated
-schema can still revert another feature's change to it —
-\`openapi.path-item-modified\` and \`openapi.component-modified\` are your only
-warning there. Removal markers carry no pin either; \`openapi.remove-target-mismatch\`
-is what guards those.
+The two surfaces an in-operation key cannot reach — path-level keys
+(\`parameters\`, \`servers\`, \`summary\`, \`x-*\`) and every
+\`components/<kind>/<name>\` — are pinned the same way through one root record,
+\`x-loam-baselines\`, which \`loam rebase\` also writes and the merge strips: a
+quoted key or component is skipped, an edited one is written and warned as
+\`openapi.path-item-modified\` / \`openapi.component-modified\`. A new component
+is copied in when something the merge writes references it; a living one you
+only \`$ref\` needs no copy in the delta at all. Removal markers carry no pin;
+\`openapi.remove-target-mismatch\` is what guards those.
 
 ## Drawing a shared broker
 
@@ -248,19 +283,25 @@ element and point the edges at it — \`paymentService -> kafka.paymentEvents\`,
 \`paymentService -> kafka\`. One hub of degree sixty becomes twelve of degree
 five, and it is the truer model besides: what a producer and a consumer share is
 the topic, never the broker. Every check joins the same way, because an edge into
-a nested element resolves to the element that owns it. Declare the kind once and
-tag it there —
+a nested element resolves to the element that owns it. Declare the kind once —
 
     specification {
       element topic {
-        #external
         style { shape queue }
       }
     }
 
-— because **LikeC4 does not inherit tags**: a topic nested inside an \`#external\`
-broker is not external itself, and \`loam validate --all\` will ask for a
-\`services/payment.events/\` nobody owes (\`landscape.service-undocumented\`).
+The KIND is what does the work: since 2026-09-07 loam reads \`database\`, \`queue\`,
+\`topic\`, \`cache\` and \`bucket\` as infrastructure rather than as candidate
+services, so a topic drawn this way is out of the service census and nobody is
+asked for a \`services/payment.events/\` (measured: the same element spelled
+\`container\` earns \`landscape.service-undocumented\`, spelled \`topic\` it earns
+nothing). This used to need \`#external\` ON THE KIND as a workaround, because
+**LikeC4 does not inherit tags** and a topic nested inside an \`#external\` broker
+is not external itself. That workaround is no longer owed. Tag the kind
+\`#external\` if you want the topics out of the fleet VIEW as well — that is what
+the next paragraph's \`exclude\` reads, and it is a rendering choice now rather
+than a way to silence a check.
 
 **Scope the views.** \`exclude element.tag = #external\` keeps the fleet overview to
 the calls between our own services; a second view over the broker draws the event