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

package/dist/core/explain/terms/done-check.js

@@ -0,0 +1,144 @@
+export const DONE_CHECK_TERMS = {
+    heading: "the done-check — what `loam verify` asks, and what an answer is worth",
+    terms: [
+        {
+            term: "claim",
+            aliases: ["claims", "checklist", "confirmed", "unconfirmed", "unanswered"],
+            paragraph: "A claim is one question on the done-check's checklist: a promise the feature's documents make about code. " +
+                "loam asks it so that evidence, not prose, can answer it. " +
+                "`loam verify <FEAT>` derives a checklist from the feature's own artifacts: one claim per new service " +
+                "(`service.exists`), per operation the contract delta adds (`api.exposes`), per message the event contract " +
+                "newly declares (`event.declares`), per tagged edge that names an operation (`c4.calls`), and per scenario of " +
+                "every changed requirement (`scenario.tested`) — `loam explain <kind>` says what each one asks and who may answer it. " +
+                "Each claim has a stable id, so two runs are diffable and an answer cannot drift onto a different question; " +
+                "`loam tasks` uses the same id for the unit that closes it. " +
+                "An answer is `confirmed` with `file:line` evidence or `unconfirmed` with a note saying why — a successful " +
+                "record either way — and a claim nobody answered is `unanswered`. Every recorded answer says who gave it " +
+                "(`answered_by: runner | external-runner | agent`), and that is what separates **verified** from **attested**.",
+            pins: [
+                { source: "DONE_CHECK", phrase: "`loam verify <FEAT>` derives a checklist from the feature's own artifacts" },
+                { source: "DONE_CHECK", phrase: "Each claim has a stable id, so" },
+                { source: "DONE_CHECK", phrase: "two runs are diffable and an answer cannot drift onto a different question" },
+                { source: "DONE_CHECK", phrase: "`answered_by: runner | external-runner | agent`" },
+            ],
+        },
+        {
+            term: "service.exists",
+            aliases: [],
+            paragraph: "A `service.exists` claim asks whether a service the feature introduces has actually been built. " +
+                "`loam verify` derives one per new service the feature's delta.likec4 adds to the fleet map. " +
+                "Answer it by finding it in the code, not by reasoning that it must be there. What to open: " +
+                "`service.exists` — the service is deployable: its build, its entry point. " +
+                "The answer is `file:line` evidence, recorded from that service's own repository with " +
+                "`loam verify <FEAT> --service <id> --record answers.json`. No test runner answers this kind, so an agent's " +
+                "word is the expected answer here, and it never makes the verdict **attested** — only scenario claims do.",
+            pins: [{ source: "VERIFY", phrase: "`service.exists` — the service is deployable: its build, its entry point." }],
+        },
+        {
+            term: "api.exposes",
+            aliases: [],
+            paragraph: "An `api.exposes` claim asks whether the service really serves an operation the feature's contract delta adds. " +
+                "`loam verify` derives one per operationId in the feature's openapi.yaml that the living contract does not " +
+                "already define; an operation the delta merely restates is never asked about. " +
+                "What to open: `api.exposes` — the route handler serving that operationId, not the spec that declares it. " +
+                "It also has a mechanical channel: an API contract-test run, passed back in loam's contract-results shape with " +
+                "`loam verify <FEAT> --contract-results contract.json`, answers it as `answered_by: external-runner`. " +
+                "In `loam tasks`, a `c4.calls` unit depends on the `api.exposes` unit that promises the operation it calls.",
+            pins: [
+                { source: "VERIFY", phrase: "`api.exposes` — the route handler serving that operationId, not the spec that" },
+                { source: "DONE_CHECK", phrase: "`loam verify <FEAT> --contract-results contract.json`" },
+            ],
+        },
+        {
+            term: "event.declares",
+            aliases: [],
+            paragraph: "An `event.declares` claim asks whether the service sends or receives a message the feature's event contract " +
+                "newly declares. " +
+                "For a feature, `loam verify` derives one per (direction, message) its asyncapi delta newly declares against the " +
+                "living contract's send/receive sets — quotes and removals are never questions. " +
+                "What to open: `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. " +
+                "It is answered with `file:line` evidence through `loam verify <FEAT> --service <id> --record answers.json`.",
+            pins: [
+                { source: "VERIFY", phrase: "`event.declares` — the code that puts the message on the wire (sends) or" },
+                { source: "VERIFY", phrase: "per (direction, message) its asyncapi delta newly declares against the living" },
+            ],
+        },
+        {
+            term: "c4.calls",
+            aliases: [],
+            paragraph: "A `c4.calls` claim asks whether a call the feature draws on the architecture really exists in the caller's code. " +
+                "`loam verify` derives one per edge in delta.likec4 that is tagged with the feature and names an operation " +
+                "(`metadata { op '<operationId>' }`); an untagged edge is context, and an edge with no operation names nothing " +
+                "specific enough to look for. " +
+                "What to open: `c4.calls` — the call site in the CALLER. " +
+                "Its subject is the calling service, so it is answered from that service's repository, and in `loam tasks` it " +
+                "depends on the `api.exposes` unit for the operation it calls when the same feature adds that operation.",
+            pins: [{ source: "VERIFY", phrase: "`c4.calls` — the call site in the CALLER." }],
+        },
+        {
+            term: "scenario.tested",
+            aliases: [],
+            paragraph: "A `scenario.tested` claim asks whether one scenario of a changed requirement passes in a test run. " +
+                "The run is of the service's generated suite, in that service's own repository. " +
+                "`loam verify` derives one per scenario of every requirement the feature adds or modifies, arch.spec.md deltas " +
+                "included (those want an integration or ops test, not an acceptance test). " +
+                "The `scenario.tested` claims are the runner's to answer, not yours. Run the suite `loam gherkin <FEAT>` " +
+                "generated, with a JSON report, and pass it back with `loam verify <FEAT> --service <id> --results report.json`; " +
+                "the match is the scenario's `@loam-digest-…` tag. The digest is the only identity: a reworded spec scenario " +
+                "matches nothing until the suite is regenerated and re-run. " +
+                "With no runnable suite your word may answer them, and the feature is then **attested**, not verified — these " +
+                "are the only claims that verdict turns on.",
+            pins: [
+                { source: "VERIFY", phrase: "The `scenario.tested` claims are the runner's to answer, not yours." },
+                { source: "DONE_CHECK", phrase: "The digest is the only identity: a reworded spec scenario matches" },
+            ],
+        },
+        {
+            term: "attested",
+            aliases: ["attest", "attestation"],
+            paragraph: "Attested is the verdict one rung below verified on the done-check's ladder. " +
+                "Verified means somebody says the code was built and showed evidence — and for scenario claims that evidence is a " +
+                "test runner's report, answered mechanically. Without a runnable suite your word can still answer them " +
+                "(`loam verify <FEAT> --record` alone), but the record says who answered, and a feature whose " +
+                "scenario claims rest on an agent's word is **attested**, not verified. Nothing gates on the difference; " +
+                "pass `--results <report>` the moment a suite runs and the verdict moves on its own. " +
+                "In `loam tasks` it is also the fourth step a unit can wait at, and the one that is not work to write: " +
+                "the claim was closed on somebody's word rather than on a run, so the unit stays visible at `attested` until a " +
+                "test run re-records it.",
+            pins: [
+                { source: "REFUSALS", phrase: "somebody says the code was built and showed evidence" },
+                // Left the cycle with the done-check teaching; repaired by following the
+                // text, as `vouch`'s two were.
+                { source: "DONE_CHECK", phrase: "scenario claims rest on an agent's word is **attested**, not verified" },
+                { source: "IMPLEMENT", phrase: "the claim was closed on somebody's word rather than on a run" },
+            ],
+        },
+        {
+            // The other half of the most overloaded word in loam's output. The status
+            // row and the scorecard print the verdict (`verified · attested ·
+            // unverified`), while a document's frontmatter prints `status: verified`
+            // for a vouch — and the two have nothing to do with each other. A reader
+            // who looks the word up after either one gets both meanings here.
+            term: "verified",
+            aliases: ["unverified", "verdict", "verdicts"],
+            paragraph: "Verified is the done-check's top verdict: every claim recorded confirmed, the scenario claims by a test run. " +
+                "Every claim on the checklist has an answer with evidence, and no scenario claim rests on somebody's word. " +
+                "A record's `verdict` (`verified` | `attested` | `unverified`) is computed from its claims, never stored: " +
+                "`unverified` means some claim is still unconfirmed or unanswered, or the record answers a checklist the feature " +
+                "no longer asks; **attested** means complete, with a scenario claim resting on an agent's word. " +
+                "Between `verified` and `attested` the verdict turns on the scenario claims alone, so a `verified` record can still rest " +
+                "partly on an agent's word about kinds the verdict does not turn on — `service.exists` or `c4.calls`, which " +
+                "only the code can answer. " +
+                "Only `verified` makes a feature in flight `done`. **Nothing gates on it.** `loam archive` will ship an " +
+                "unverified feature. " +
+                "The same word on a living document means something else: `status: verified` in a spec.md's frontmatter is a " +
+                "person's vouch for the words, not a test result (`loam explain vouch`).",
+            pins: [
+                { source: "CODES_PAGE", phrase: "`verdict` (`verified` | `attested` | `unverified`)" },
+                { source: "CODES_PAGE", phrase: "partly on an agent's word about kinds the verdict does not turn on" },
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=done-check.js.map

package/dist/core/explain/terms/done-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"done-check.js","sourceRoot":"","sources":["../../../../src/core/explain/terms/done-check.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The done-check terms: what `loam verify` asks (a claim, and the five kinds\n * of one), and what the answer is worth (the verdicts).\n *\n * One entry per claim kind rather than one `claim` entry with the kinds as\n * aliases, because the kinds differ in exactly the fact a reader looks one up\n * for: WHO may answer it. A `scenario.tested` claim is a test runner's, an\n * `api.exposes` claim may be a contract suite's, and the other three are\n * answered from the code — a single paragraph listing all five would answer\n * `loam explain c4.calls` with four sentences about something else. Each kind\n * is pinned to its own line of the /loam-verify body, which is where the\n * binary already teaches \"what to open\" one kind at a time.\n *\n * `attested` moved here from the old flat registry with its paragraph and\n * pins intact, and gained a sentence and a pin of its own: `loam tasks` prints\n * the same word as the fourth step a unit waits at, and the two meanings are\n * one fact seen from two commands, so one entry answers both rather than two\n * entries competing for one name.\n */\nimport type { TermGroup } from \"./entry.js\";\n\nexport const DONE_CHECK_TERMS: TermGroup = {\n  heading: \"the done-check — what `loam verify` asks, and what an answer is worth\",\n  terms: [\n    {\n      term: \"claim\",\n      aliases: [\"claims\", \"checklist\", \"confirmed\", \"unconfirmed\", \"unanswered\"],\n      paragraph:\n        \"A claim is one question on the done-check's checklist: a promise the feature's documents make about code. \" +\n        \"loam asks it so that evidence, not prose, can answer it. \" +\n        \"`loam verify <FEAT>` derives a checklist from the feature's own artifacts: one claim per new service \" +\n        \"(`service.exists`), per operation the contract delta adds (`api.exposes`), per message the event contract \" +\n        \"newly declares (`event.declares`), per tagged edge that names an operation (`c4.calls`), and per scenario of \" +\n        \"every changed requirement (`scenario.tested`) — `loam explain <kind>` says what each one asks and who may answer it. \" +\n        \"Each claim has a stable id, so two runs are diffable and an answer cannot drift onto a different question; \" +\n        \"`loam tasks` uses the same id for the unit that closes it. \" +\n        \"An answer is `confirmed` with `file:line` evidence or `unconfirmed` with a note saying why — a successful \" +\n        \"record either way — and a claim nobody answered is `unanswered`. Every recorded answer says who gave it \" +\n        \"(`answered_by: runner | external-runner | agent`), and that is what separates **verified** from **attested**.\",\n      pins: [\n        { source: \"DONE_CHECK\", phrase: \"`loam verify <FEAT>` derives a checklist from the feature's own artifacts\" },\n        { source: \"DONE_CHECK\", phrase: \"Each claim has a stable id, so\" },\n        { source: \"DONE_CHECK\", phrase: \"two runs are diffable and an answer cannot drift onto a different question\" },\n        { source: \"DONE_CHECK\", phrase: \"`answered_by: runner | external-runner | agent`\" },\n      ],\n    },\n    {\n      term: \"service.exists\",\n      aliases: [],\n      paragraph:\n        \"A `service.exists` claim asks whether a service the feature introduces has actually been built. \" +\n        \"`loam verify` derives one per new service the feature's delta.likec4 adds to the fleet map. \" +\n        \"Answer it by finding it in the code, not by reasoning that it must be there. What to open: \" +\n        \"`service.exists` — the service is deployable: its build, its entry point. \" +\n        \"The answer is `file:line` evidence, recorded from that service's own repository with \" +\n        \"`loam verify <FEAT> --service <id> --record answers.json`. No test runner answers this kind, so an agent's \" +\n        \"word is the expected answer here, and it never makes the verdict **attested** — only scenario claims do.\",\n      pins: [{ source: \"VERIFY\", phrase: \"`service.exists` — the service is deployable: its build, its entry point.\" }],\n    },\n    {\n      term: \"api.exposes\",\n      aliases: [],\n      paragraph:\n        \"An `api.exposes` claim asks whether the service really serves an operation the feature's contract delta adds. \" +\n        \"`loam verify` derives one per operationId in the feature's openapi.yaml that the living contract does not \" +\n        \"already define; an operation the delta merely restates is never asked about. \" +\n        \"What to open: `api.exposes` — the route handler serving that operationId, not the spec that declares it. \" +\n        \"It also has a mechanical channel: an API contract-test run, passed back in loam's contract-results shape with \" +\n        \"`loam verify <FEAT> --contract-results contract.json`, answers it as `answered_by: external-runner`. \" +\n        \"In `loam tasks`, a `c4.calls` unit depends on the `api.exposes` unit that promises the operation it calls.\",\n      pins: [\n        { source: \"VERIFY\", phrase: \"`api.exposes` — the route handler serving that operationId, not the spec that\" },\n        { source: \"DONE_CHECK\", phrase: \"`loam verify <FEAT> --contract-results contract.json`\" },\n      ],\n    },\n    {\n      term: \"event.declares\",\n      aliases: [],\n      paragraph:\n        \"An `event.declares` claim asks whether the service sends or receives a message the feature's event contract \" +\n        \"newly declares. \" +\n        \"For a feature, `loam verify` derives one per (direction, message) its asyncapi delta newly declares against the \" +\n        \"living contract's send/receive sets — quotes and removals are never questions. \" +\n        \"What to open: `event.declares` — the code that puts the message on the wire (sends) or handles it off the \" +\n        \"wire (receives), not the contract that names it. \" +\n        \"It is answered with `file:line` evidence through `loam verify <FEAT> --service <id> --record answers.json`.\",\n      pins: [\n        { source: \"VERIFY\", phrase: \"`event.declares` — the code that puts the message on the wire (sends) or\" },\n        { source: \"VERIFY\", phrase: \"per (direction, message) its asyncapi delta newly declares against the living\" },\n      ],\n    },\n    {\n      term: \"c4.calls\",\n      aliases: [],\n      paragraph:\n        \"A `c4.calls` claim asks whether a call the feature draws on the architecture really exists in the caller's code. \" +\n        \"`loam verify` derives one per edge in delta.likec4 that is tagged with the feature and names an operation \" +\n        \"(`metadata { op '<operationId>' }`); an untagged edge is context, and an edge with no operation names nothing \" +\n        \"specific enough to look for. \" +\n        \"What to open: `c4.calls` — the call site in the CALLER. \" +\n        \"Its subject is the calling service, so it is answered from that service's repository, and in `loam tasks` it \" +\n        \"depends on the `api.exposes` unit for the operation it calls when the same feature adds that operation.\",\n      pins: [{ source: \"VERIFY\", phrase: \"`c4.calls` — the call site in the CALLER.\" }],\n    },\n    {\n      term: \"scenario.tested\",\n      aliases: [],\n      paragraph:\n        \"A `scenario.tested` claim asks whether one scenario of a changed requirement passes in a test run. \" +\n        \"The run is of the service's generated suite, in that service's own repository. \" +\n        \"`loam verify` derives one per scenario of every requirement the feature adds or modifies, arch.spec.md deltas \" +\n        \"included (those want an integration or ops test, not an acceptance test). \" +\n        \"The `scenario.tested` claims are the runner's to answer, not yours. Run the suite `loam gherkin <FEAT>` \" +\n        \"generated, with a JSON report, and pass it back with `loam verify <FEAT> --service <id> --results report.json`; \" +\n        \"the match is the scenario's `@loam-digest-…` tag. The digest is the only identity: a reworded spec scenario \" +\n        \"matches nothing until the suite is regenerated and re-run. \" +\n        \"With no runnable suite your word may answer them, and the feature is then **attested**, not verified — these \" +\n        \"are the only claims that verdict turns on.\",\n      pins: [\n        { source: \"VERIFY\", phrase: \"The `scenario.tested` claims are the runner's to answer, not yours.\" },\n        { source: \"DONE_CHECK\", phrase: \"The digest is the only identity: a reworded spec scenario matches\" },\n      ],\n    },\n    {\n      term: \"attested\",\n      aliases: [\"attest\", \"attestation\"],\n      paragraph:\n        \"Attested is the verdict one rung below verified on the done-check's ladder. \" +\n        \"Verified means somebody says the code was built and showed evidence — and for scenario claims that evidence is a \" +\n        \"test runner's report, answered mechanically. Without a runnable suite your word can still answer them \" +\n        \"(`loam verify <FEAT> --record` alone), but the record says who answered, and a feature whose \" +\n        \"scenario claims rest on an agent's word is **attested**, not verified. Nothing gates on the difference; \" +\n        \"pass `--results <report>` the moment a suite runs and the verdict moves on its own. \" +\n        \"In `loam tasks` it is also the fourth step a unit can wait at, and the one that is not work to write: \" +\n        \"the claim was closed on somebody's word rather than on a run, so the unit stays visible at `attested` until a \" +\n        \"test run re-records it.\",\n      pins: [\n        { source: \"REFUSALS\", phrase: \"somebody says the code was built and showed evidence\" },\n        // Left the cycle with the done-check teaching; repaired by following the\n        // text, as `vouch`'s two were.\n        { source: \"DONE_CHECK\", phrase: \"scenario claims rest on an agent's word is **attested**, not verified\" },\n        { source: \"IMPLEMENT\", phrase: \"the claim was closed on somebody's word rather than on a run\" },\n      ],\n    },\n    {\n      // The other half of the most overloaded word in loam's output. The status\n      // row and the scorecard print the verdict (`verified · attested ·\n      // unverified`), while a document's frontmatter prints `status: verified`\n      // for a vouch — and the two have nothing to do with each other. A reader\n      // who looks the word up after either one gets both meanings here.\n      term: \"verified\",\n      aliases: [\"unverified\", \"verdict\", \"verdicts\"],\n      paragraph:\n        \"Verified is the done-check's top verdict: every claim recorded confirmed, the scenario claims by a test run. \" +\n        \"Every claim on the checklist has an answer with evidence, and no scenario claim rests on somebody's word. \" +\n        \"A record's `verdict` (`verified` | `attested` | `unverified`) is computed from its claims, never stored: \" +\n        \"`unverified` means some claim is still unconfirmed or unanswered, or the record answers a checklist the feature \" +\n        \"no longer asks; **attested** means complete, with a scenario claim resting on an agent's word. \" +\n        \"Between `verified` and `attested` the verdict turns on the scenario claims alone, so a `verified` record can still rest \" +\n        \"partly on an agent's word about kinds the verdict does not turn on — `service.exists` or `c4.calls`, which \" +\n        \"only the code can answer. \" +\n        \"Only `verified` makes a feature in flight `done`. **Nothing gates on it.** `loam archive` will ship an \" +\n        \"unverified feature. \" +\n        \"The same word on a living document means something else: `status: verified` in a spec.md's frontmatter is a \" +\n        \"person's vouch for the words, not a test result (`loam explain vouch`).\",\n      pins: [\n        { source: \"CODES_PAGE\", phrase: \"`verdict` (`verified` | `attested` | `unverified`)\" },\n        { source: \"CODES_PAGE\", phrase: \"partly on an agent's word about kinds the verdict does not turn on\" },\n      ],\n    },\n  ],\n};\n"]}

package/dist/core/explain/terms/entry.js

@@ -0,0 +1,14 @@
+/**
+ * What one concept term IS, apart from any term's words: the entry shape the
+ * four subject modules beside this one fill in, and the names of the shipped
+ * pages a pin may point at.
+ *
+ * A module of its own, holding only types, because of where the assembler
+ * sits. `../terms.ts` imports every subject module of this package to build
+ * `TERMS`, so a subject module that reached back up into it for `TermEntry`
+ * would close a file-level cycle through a type — erased at runtime, but a
+ * cycle every graph in the gate still has to be told to ignore. Down here the
+ * graph stays a tree: the subjects import this, the assembler imports them.
+ */
+export {};
+//# sourceMappingURL=entry.js.map

package/dist/core/explain/terms/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../../src/core/explain/terms/entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG","sourcesContent":["/**\n * What one concept term IS, apart from any term's words: the entry shape the\n * four subject modules beside this one fill in, and the names of the shipped\n * pages a pin may point at.\n *\n * A module of its own, holding only types, because of where the assembler\n * sits. `../terms.ts` imports every subject module of this package to build\n * `TERMS`, so a subject module that reached back up into it for `TermEntry`\n * would close a file-level cycle through a type — erased at runtime, but a\n * cycle every graph in the gate still has to be told to ignore. Down here the\n * graph stays a tree: the subjects import this, the assembler imports them.\n */\n\n/**\n * The shipped texts a pin may name — each one a page `loam instructions`\n * prints, or the AGENTS.md loam writes. `../terms.ts` maps every name to its\n * bytes (`PIN_SOURCE_TEXT`), and the `Record` there makes a name added here\n * without a text a compile error rather than a pin that guards nothing.\n */\nexport type PinSource =\n  | \"AGENTS_MD\"\n  | \"SPINE_PAGE\"\n  | \"REFUSALS\"\n  | \"AUTHORING\"\n  | \"DRAWING\"\n  | \"DONE_CHECK\"\n  | \"CODES_PAGE\"\n  | \"CHECK\"\n  | \"FEATURE\"\n  | \"IMPLEMENT\"\n  | \"VERIFY\";\n\nexport interface TermPin {\n  readonly source: PinSource;\n  /** A verbatim single-line substring of both the paragraph and the source section. */\n  readonly phrase: string;\n}\n\nexport interface TermEntry {\n  readonly term: string;\n  readonly aliases: readonly string[];\n  /** The explanation. Its FIRST sentence doubles as the no-argument listing's summary. */\n  readonly paragraph: string;\n  readonly pins: readonly TermPin[];\n}\n\n/**\n * The terms of one subject, under the heading the bare `loam explain` listing\n * prints above them.\n *\n * The heading exists for a reader, not for the lookup: twenty-odd terms in one\n * flat column read as a glossary nobody scans, and the words a newcomer meets\n * arrive in clusters — the stages `loam status` prints, the claims and\n * verdicts of `loam verify`, the steps of `loam tasks` — so the listing is\n * grouped the way the output that printed them is. The `--json` listing stays\n * the flat `terms[]` it always was; a group is typography, never a key.\n */\nexport interface TermGroup {\n  readonly heading: string;\n  readonly terms: readonly TermEntry[];\n}\n"]}

package/dist/core/explain/terms/stages.js

@@ -0,0 +1,71 @@
+export const STAGE_TERMS = {
+    heading: "feature stages — what `loam status` reports",
+    terms: [
+        {
+            term: "stage",
+            aliases: ["stages", "missing", "blocked", "draft"],
+            paragraph: "A stage is where a feature, or one artifact it owes, stands — one of five closed values `loam status` reports. " +
+                "In `--json` a feature carries it as `stage` and each artifact as `status`. " +
+                "`missing` (owed, nothing in the way — write it now). " +
+                "`blocked` (not written and not writable yet; the entry names what comes first — an artifact it derives from, " +
+                "or another feature that has to archive first). " +
+                "`draft` (on disk, and the shared checks report an error against it, or a warning that gates archive — what " +
+                "exists is wrong, and the fix is in the documents). " +
+                "`ready` and `done` have entries of their own, because they are the two that mislead. " +
+                "The pairs are the point: `missing` says write it now where `blocked` says you cannot yet, and `draft` says the " +
+                "document is wrong where `ready` says it is right and the world has not caught up. " +
+                "A feature's stage is the worst thing it owes, graded on the union of what `loam validate --feature` and " +
+                "`loam archive` refuse, so it may be more pessimistic than either and can never be greener than both; the " +
+                "fleet form never says `draft`, because grading is a per-feature cost it does not pay. " +
+                "Not to be confused with `status: draft` in a document's frontmatter, which says no person has vouched for it " +
+                "yet (`loam explain vouch`).",
+            pins: [
+                { source: "CODES_PAGE", phrase: "`missing` (owed, nothing in" },
+                { source: "CODES_PAGE", phrase: "`blocked` (not written and not writable yet; the entry" },
+                { source: "CODES_PAGE", phrase: "`draft` (on disk, and the shared checks report an error" },
+                { source: "CODES_PAGE", phrase: "so it may be more pessimistic than either and can never be greener than both" },
+            ],
+        },
+        {
+            term: "ready",
+            aliases: [],
+            paragraph: "Ready means the documents are written and pass the shared checks — it does not mean anything is built or verified. " +
+                "On a feature, `ready` is every artifact on disk and clean while the done-check is not yet discharged: the " +
+                "code may not exist yet, and the claims `loam verify` asks are not all answered by evidence. " +
+                "As an artifact's `status`, `ready` (on disk and clean, but something outside the documents — code, a test " +
+                "run, a recording — still has to answer it) is a verification record whose claims are still open. " +
+                "A record that is complete but rests on an agent's word for a scenario claim — **attested** — is still " +
+                "`ready`, because only a `verified` verdict makes a feature `done`. " +
+                "So the next move from `ready` is never another edit to a document that is already right: it is " +
+                "`loam tasks <FEAT>` for the work still open, and `loam verify <FEAT>` for what the checklist still asks. " +
+                "The stage that means the document itself is wrong is `draft`.",
+            pins: [
+                { source: "CODES_PAGE", phrase: "`ready` (on disk and clean, but something" },
+                { source: "CODES_PAGE", phrase: "outside the documents — code, a test run, a recording — still has to answer it" },
+            ],
+        },
+        {
+            term: "done",
+            aliases: [],
+            paragraph: "Done means nothing more is owed — and on an archived feature it says only that the feature was archived, not that " +
+                "anybody verified it. " +
+                "A feature in flight earns `done`: every artifact is clean and the done-check's verdict is `verified` (every " +
+                "claim recorded confirmed, the scenario claims by a test run), so its next step is `next.archive` — a dry run " +
+                "of `loam archive <FEAT>`, then the merge. " +
+                "An ARCHIVED feature is `done` whatever its record says, because it is archived and for no other reason. " +
+                "Archiving merges documents; it checks no code and no evidence, and it does not wait for the done-check. " +
+                "**Nothing gates on it.** `loam archive` will ship an unverified feature. " +
+                "The verification verdict beside the stage (`verified`, `attested`, `unverified`, or no record at all) is what " +
+                "says whether it was ever verified, and the `next.archived` step `loam status` gives it says the same. " +
+                "On an artifact row, `done` on a file that is not there means the feature owes no such file. " +
+                "In `loam tasks`, `done` counts units that have left the packet: the unit no longer appears, and it stops " +
+                "appearing only once its claim is recorded confirmed in a verification record that is not stale.",
+            pins: [
+                { source: "CODES_PAGE", phrase: "is `done` whatever its record says" },
+                { source: "DONE_CHECK", phrase: "**Nothing gates on it.** `loam archive` will ship an unverified feature." },
+                { source: "IMPLEMENT", phrase: "the unit no longer appears, and it stops appearing only once its claim is" },
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=stages.js.map

package/dist/core/explain/terms/stages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stages.js","sourceRoot":"","sources":["../../../../src/core/explain/terms/stages.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,WAAW,GAAc;IACpC,OAAO,EAAE,6CAA6C;IACtD,KAAK,EAAE;QACL;YACE,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC;YAClD,SAAS,EACP,iHAAiH;gBACjH,6EAA6E;gBAC7E,uDAAuD;gBACvD,+GAA+G;gBAC/G,iDAAiD;gBACjD,6GAA6G;gBAC7G,qDAAqD;gBACrD,uFAAuF;gBACvF,iHAAiH;gBACjH,oFAAoF;gBACpF,0GAA0G;gBAC1G,2GAA2G;gBAC3G,wFAAwF;gBACxF,+GAA+G;gBAC/G,6BAA6B;YAC/B,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,6BAA6B,EAAE;gBAC/D,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,wDAAwD,EAAE;gBAC1F,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,yDAAyD,EAAE;gBAC3F,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,8EAA8E,EAAE;aACjH;SACF;QACD;YACE,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,EAAE;YACX,SAAS,EACP,qHAAqH;gBACrH,4GAA4G;gBAC5G,8FAA8F;gBAC9F,4GAA4G;gBAC5G,mGAAmG;gBACnG,wGAAwG;gBACxG,qEAAqE;gBACrE,iGAAiG;gBACjG,2GAA2G;gBAC3G,+DAA+D;YACjE,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,2CAA2C,EAAE;gBAC7E,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,gFAAgF,EAAE;aACnH;SACF;QACD;YACE,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,EAAE;YACX,SAAS,EACP,oHAAoH;gBACpH,uBAAuB;gBACvB,8GAA8G;gBAC9G,+GAA+G;gBAC/G,4CAA4C;gBAC5C,0GAA0G;gBAC1G,0GAA0G;gBAC1G,2EAA2E;gBAC3E,gHAAgH;gBAChH,wGAAwG;gBACxG,8FAA8F;gBAC9F,2GAA2G;gBAC3G,iGAAiG;YACnG,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,oCAAoC,EAAE;gBACtE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,0EAA0E,EAAE;gBAC5G,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,2EAA2E,EAAE;aAC7G;SACF;KACF;CACF,CAAC","sourcesContent":["/**\n * The stage terms: the five closed values `loam status` reports for a feature\n * and for every artifact it owes (core/status/report.ts, \"The status\n * vocabulary\"), and the two of them that mislead.\n *\n * `ready` and `done` are entries of their own rather than aliases of `stage`\n * because they are where a reader goes wrong, and in opposite directions.\n * `ready` reads as \"built\" and means only that the DOCUMENTS are right — the\n * code may not exist and no claim may be answered. `done` on an archived\n * feature reads as \"verified\" and means only that it was archived, which\n * checks no code and no evidence. The JSON `stage` values are a frozen\n * contract and keep their spelling; the words around them are what can be\n * fixed, and these paragraphs are where `loam explain` fixes them.\n *\n * The other three share `stage` as aliases: each one is a single clause, and\n * the pairs (missing against blocked, draft against ready) are only legible\n * read together.\n */\nimport type { TermGroup } from \"./entry.js\";\n\nexport const STAGE_TERMS: TermGroup = {\n  heading: \"feature stages — what `loam status` reports\",\n  terms: [\n    {\n      term: \"stage\",\n      aliases: [\"stages\", \"missing\", \"blocked\", \"draft\"],\n      paragraph:\n        \"A stage is where a feature, or one artifact it owes, stands — one of five closed values `loam status` reports. \" +\n        \"In `--json` a feature carries it as `stage` and each artifact as `status`. \" +\n        \"`missing` (owed, nothing in the way — write it now). \" +\n        \"`blocked` (not written and not writable yet; the entry names what comes first — an artifact it derives from, \" +\n        \"or another feature that has to archive first). \" +\n        \"`draft` (on disk, and the shared checks report an error against it, or a warning that gates archive — what \" +\n        \"exists is wrong, and the fix is in the documents). \" +\n        \"`ready` and `done` have entries of their own, because they are the two that mislead. \" +\n        \"The pairs are the point: `missing` says write it now where `blocked` says you cannot yet, and `draft` says the \" +\n        \"document is wrong where `ready` says it is right and the world has not caught up. \" +\n        \"A feature's stage is the worst thing it owes, graded on the union of what `loam validate --feature` and \" +\n        \"`loam archive` refuse, so it may be more pessimistic than either and can never be greener than both; the \" +\n        \"fleet form never says `draft`, because grading is a per-feature cost it does not pay. \" +\n        \"Not to be confused with `status: draft` in a document's frontmatter, which says no person has vouched for it \" +\n        \"yet (`loam explain vouch`).\",\n      pins: [\n        { source: \"CODES_PAGE\", phrase: \"`missing` (owed, nothing in\" },\n        { source: \"CODES_PAGE\", phrase: \"`blocked` (not written and not writable yet; the entry\" },\n        { source: \"CODES_PAGE\", phrase: \"`draft` (on disk, and the shared checks report an error\" },\n        { source: \"CODES_PAGE\", phrase: \"so it may be more pessimistic than either and can never be greener than both\" },\n      ],\n    },\n    {\n      term: \"ready\",\n      aliases: [],\n      paragraph:\n        \"Ready means the documents are written and pass the shared checks — it does not mean anything is built or verified. \" +\n        \"On a feature, `ready` is every artifact on disk and clean while the done-check is not yet discharged: the \" +\n        \"code may not exist yet, and the claims `loam verify` asks are not all answered by evidence. \" +\n        \"As an artifact's `status`, `ready` (on disk and clean, but something outside the documents — code, a test \" +\n        \"run, a recording — still has to answer it) is a verification record whose claims are still open. \" +\n        \"A record that is complete but rests on an agent's word for a scenario claim — **attested** — is still \" +\n        \"`ready`, because only a `verified` verdict makes a feature `done`. \" +\n        \"So the next move from `ready` is never another edit to a document that is already right: it is \" +\n        \"`loam tasks <FEAT>` for the work still open, and `loam verify <FEAT>` for what the checklist still asks. \" +\n        \"The stage that means the document itself is wrong is `draft`.\",\n      pins: [\n        { source: \"CODES_PAGE\", phrase: \"`ready` (on disk and clean, but something\" },\n        { source: \"CODES_PAGE\", phrase: \"outside the documents — code, a test run, a recording — still has to answer it\" },\n      ],\n    },\n    {\n      term: \"done\",\n      aliases: [],\n      paragraph:\n        \"Done means nothing more is owed — and on an archived feature it says only that the feature was archived, not that \" +\n        \"anybody verified it. \" +\n        \"A feature in flight earns `done`: every artifact is clean and the done-check's verdict is `verified` (every \" +\n        \"claim recorded confirmed, the scenario claims by a test run), so its next step is `next.archive` — a dry run \" +\n        \"of `loam archive <FEAT>`, then the merge. \" +\n        \"An ARCHIVED feature is `done` whatever its record says, because it is archived and for no other reason. \" +\n        \"Archiving merges documents; it checks no code and no evidence, and it does not wait for the done-check. \" +\n        \"**Nothing gates on it.** `loam archive` will ship an unverified feature. \" +\n        \"The verification verdict beside the stage (`verified`, `attested`, `unverified`, or no record at all) is what \" +\n        \"says whether it was ever verified, and the `next.archived` step `loam status` gives it says the same. \" +\n        \"On an artifact row, `done` on a file that is not there means the feature owes no such file. \" +\n        \"In `loam tasks`, `done` counts units that have left the packet: the unit no longer appears, and it stops \" +\n        \"appearing only once its claim is recorded confirmed in a verification record that is not stale.\",\n      pins: [\n        { source: \"CODES_PAGE\", phrase: \"is `done` whatever its record says\" },\n        { source: \"DONE_CHECK\", phrase: \"**Nothing gates on it.** `loam archive` will ship an unverified feature.\" },\n        { source: \"IMPLEMENT\", phrase: \"the unit no longer appears, and it stops appearing only once its claim is\" },\n      ],\n    },\n  ],\n};\n"]}

package/dist/core/explain/terms/tasks.js

@@ -0,0 +1,97 @@
+export const TASK_TERMS = {
+    heading: "the work packet — what `loam tasks` lists",
+    terms: [
+        {
+            term: "unit",
+            aliases: ["units", "work packet", "packet"],
+            paragraph: "A unit is one piece of open work in the packet `loam tasks` derives, and its id is the id of the done-check " +
+                "claim it closes. " +
+                "`loam tasks <FEAT> --service <id> --next --json` is ONE unit of work, and the loop an implementation runs " +
+                "inside; drop `--next` for every open unit. " +
+                "Each entry of `units[]` carries its `id` (the same id the verify checklist uses for that claim), its `kind`, " +
+                "the `source` it was derived from, and `done.check` — the fact that closes it. " +
+                "`at` is the instruction. It is the step the unit waits at — `describe`, `generate`, `implement` or " +
+                "`attested` — and each names exactly one action (`loam explain <step>`). " +
+                "The packet is derived, never stored: from the verify checklist, the delta, the verification record and, in a " +
+                "bound service repo, the digest stamps of the generated `.feature` files, so it is recomputed on every run. " +
+                "One kind is not a claim: `requirement.described`, a requirement with no scenario yet (`loam explain describe`).",
+            pins: [
+                { source: "IMPLEMENT", phrase: "ONE unit of work, and the loop" },
+                { source: "IMPLEMENT", phrase: "(the same id the verify checklist uses" },
+                { source: "IMPLEMENT", phrase: "`at` is the instruction." },
+            ],
+        },
+        {
+            term: "frontier",
+            aliases: [],
+            paragraph: "The frontier is the head of the work packet: the first ten open unit ids, in the order `loam tasks` says to " +
+                "take them. " +
+                "`--json` carries it as `frontier` (the first ten open unit ids, in order), with how many more are open beside " +
+                "it, and `--next` prints its head alone, in full, with what closes it. " +
+                "It is recomputed from the documents on every run, which is what makes taking the head of it always safe — so " +
+                "re-run `loam tasks <FEAT> --service <id>` after every recording instead of working down a list you copied out. " +
+                "When the packet is narrowed to one service, `waitingOn` names what another service still owes before your " +
+                "frontier can move.",
+            pins: [
+                { source: "IMPLEMENT", phrase: "`frontier` (the first ten open unit ids, in order)" },
+                { source: "IMPLEMENT", phrase: "every run, which is what makes taking the head of it always safe" },
+                { source: "IMPLEMENT", phrase: "still owes before your frontier can move" },
+            ],
+        },
+        {
+            term: "describe",
+            aliases: ["requirement.described"],
+            paragraph: "Describe is the first step a `loam tasks` unit can wait at: the requirement owns no scenarios yet. " +
+                "So there is nothing to generate a test from and nothing for `loam verify` to claim. " +
+                "Write the Given/When/Then in the DOCS repo, on the requirement the unit's `source` names, and nothing else — " +
+                "loam does not author, and no amount of code closes a unit sitting here. " +
+                "Its kind is `requirement.described`, the one unit kind that is not a done-check claim, because a requirement " +
+                "with no scenario asks no question anybody could answer with evidence; it closes when the requirement carries " +
+                "at least one `#### Scenario:`, which `loam validate --feature <FEAT>` grades. " +
+                "The steps after it are `generate`, `implement` and `attested`.",
+            pins: [
+                { source: "IMPLEMENT", phrase: "the requirement owns no scenarios yet" },
+                { source: "IMPLEMENT", phrase: "no amount of code closes a unit sitting here" },
+            ],
+        },
+        {
+            term: "generate",
+            aliases: [],
+            paragraph: "Generate is the step a `loam tasks` unit waits at when its scenario's test has not been generated yet. " +
+                "`generate` means no stamped `.feature` carries this scenario's digest, and the only action is " +
+                "`loam gherkin <FEAT>` in the service's own repository — do not write code. It writes one digest-stamped " +
+                "`.feature` per changed requirement under `<gherkinDir>/loam/`. Those files ARE the acceptance criteria. " +
+                "Never edit them: regeneration rewrites the directory. Generating is the whole action, and on the next run the " +
+                "same unit reads `implement`. " +
+                "The stamps are read from the repository `loam tasks` runs in, and nobody else's: an `unknown` makes every " +
+                "`generate` verdict a guess, so fix the binding before acting on one.",
+            pins: [
+                { source: "IMPLEMENT", phrase: "no stamped `.feature` carries this scenario's digest" },
+                { source: "IMPLEMENT", phrase: "Those files ARE the acceptance criteria." },
+                { source: "IMPLEMENT", phrase: "an `unknown` makes every `generate` verdict a guess" },
+            ],
+        },
+        {
+            term: "implement",
+            aliases: [],
+            paragraph: "Implement is the step a `loam tasks` unit waits at when what is still owed is code, or a recorded answer " +
+                "about code. " +
+                "For a scenario claim it means the stamped scenario exists and no recorded run has confirmed it: write step " +
+                "definitions outside the generated `loam/` directory, implement until the suite passes, then record the run " +
+                "with `loam verify <FEAT> --service <id> --results report.json`. " +
+                "For the other claim kinds it means the claim is not yet recorded confirmed: answer from the code with " +
+                "`file:line` evidence (`loam verify <FEAT> --record answers.json --service <id>`), or for `api.exposes` with a " +
+                "contract-test report. " +
+                "Either way the record decides — never your own reading of the code you just wrote — and the unit leaves " +
+                "the packet only once its claim is recorded confirmed. " +
+                "A scenario also reads `implement` when nothing could see its generated test — the stamps are read from the " +
+                "repository `loam tasks` runs in alone — so check `stamps` before writing a test by hand. " +
+                "`loam instructions loam-implement <FEAT>` is the whole protocol.",
+            pins: [
+                { source: "IMPLEMENT", phrase: "the stamped scenario exists and no recorded run has confirmed" },
+                { source: "IMPLEMENT", phrase: "never your own reading of the code you just wrote" },
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=tasks.js.map

package/dist/core/explain/terms/tasks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../../../../src/core/explain/terms/tasks.ts"],"names":[],"mappings":"AAeA,MAAM,CAAC,MAAM,UAAU,GAAc;IACnC,OAAO,EAAE,2CAA2C;IACpD,KAAK,EAAE;QACL;YACE,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,CAAC;YAC3C,SAAS,EACP,8GAA8G;gBAC9G,mBAAmB;gBACnB,4GAA4G;gBAC5G,6CAA6C;gBAC7C,+GAA+G;gBAC/G,gFAAgF;gBAChF,qGAAqG;gBACrG,0EAA0E;gBAC1E,+GAA+G;gBAC/G,6GAA6G;gBAC7G,iHAAiH;YACnH,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,gCAAgC,EAAE;gBACjE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,wCAAwC,EAAE;gBACzE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,0BAA0B,EAAE;aAC5D;SACF;QACD;YACE,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,EAAE;YACX,SAAS,EACP,8GAA8G;gBAC9G,aAAa;gBACb,gHAAgH;gBAChH,wEAAwE;gBACxE,+GAA+G;gBAC/G,iHAAiH;gBACjH,4GAA4G;gBAC5G,oBAAoB;YACtB,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,oDAAoD,EAAE;gBACrF,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,kEAAkE,EAAE;gBACnG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,0CAA0C,EAAE;aAC5E;SACF;QACD;YACE,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,CAAC,uBAAuB,CAAC;YAClC,SAAS,EACP,qGAAqG;gBACrG,sFAAsF;gBACtF,+GAA+G;gBAC/G,0EAA0E;gBAC1E,+GAA+G;gBAC/G,+GAA+G;gBAC/G,gFAAgF;gBAChF,gEAAgE;YAClE,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,uCAAuC,EAAE;gBACxE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,8CAA8C,EAAE;aAChF;SACF;QACD;YACE,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,EAAE;YACX,SAAS,EACP,yGAAyG;gBACzG,gGAAgG;gBAChG,0GAA0G;gBAC1G,0GAA0G;gBAC1G,gHAAgH;gBAChH,+BAA+B;gBAC/B,4GAA4G;gBAC5G,sEAAsE;YACxE,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,sDAAsD,EAAE;gBACvF,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,0CAA0C,EAAE;gBAC3E,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,qDAAqD,EAAE;aACvF;SACF;QACD;YACE,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,EAAE;YACX,SAAS,EACP,2GAA2G;gBAC3G,cAAc;gBACd,6GAA6G;gBAC7G,6GAA6G;gBAC7G,kEAAkE;gBAClE,wGAAwG;gBACxG,gHAAgH;gBAChH,wBAAwB;gBACxB,0GAA0G;gBAC1G,wDAAwD;gBACxD,6GAA6G;gBAC7G,2FAA2F;gBAC3F,kEAAkE;YACpE,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,+DAA+D,EAAE;gBAChG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,mDAAmD,EAAE;aACrF;SACF;KACF;CACF,CAAC","sourcesContent":["/**\n * The work-packet terms: the words `loam tasks` prints — a unit, the frontier,\n * and the steps a unit waits at (core/tasks/unit.ts `TaskStep`).\n *\n * The fourth step, `attested`, is not here: it is the same fact as the\n * done-check verdict of that name, seen from `loam tasks` rather than from\n * `loam verify`, and ./done-check.ts answers both readings in one entry. A\n * second `attested` would be a name two entries compete for.\n *\n * Every pin points at step 3 of the /loam-implement body, which is where the\n * binary teaches the packet — each step's own bullet there is one line, so\n * each entry here pins the clause that bullet opens with.\n */\nimport type { TermGroup } from \"./entry.js\";\n\nexport const TASK_TERMS: TermGroup = {\n  heading: \"the work packet — what `loam tasks` lists\",\n  terms: [\n    {\n      term: \"unit\",\n      aliases: [\"units\", \"work packet\", \"packet\"],\n      paragraph:\n        \"A unit is one piece of open work in the packet `loam tasks` derives, and its id is the id of the done-check \" +\n        \"claim it closes. \" +\n        \"`loam tasks <FEAT> --service <id> --next --json` is ONE unit of work, and the loop an implementation runs \" +\n        \"inside; drop `--next` for every open unit. \" +\n        \"Each entry of `units[]` carries its `id` (the same id the verify checklist uses for that claim), its `kind`, \" +\n        \"the `source` it was derived from, and `done.check` — the fact that closes it. \" +\n        \"`at` is the instruction. It is the step the unit waits at — `describe`, `generate`, `implement` or \" +\n        \"`attested` — and each names exactly one action (`loam explain <step>`). \" +\n        \"The packet is derived, never stored: from the verify checklist, the delta, the verification record and, in a \" +\n        \"bound service repo, the digest stamps of the generated `.feature` files, so it is recomputed on every run. \" +\n        \"One kind is not a claim: `requirement.described`, a requirement with no scenario yet (`loam explain describe`).\",\n      pins: [\n        { source: \"IMPLEMENT\", phrase: \"ONE unit of work, and the loop\" },\n        { source: \"IMPLEMENT\", phrase: \"(the same id the verify checklist uses\" },\n        { source: \"IMPLEMENT\", phrase: \"`at` is the instruction.\" },\n      ],\n    },\n    {\n      term: \"frontier\",\n      aliases: [],\n      paragraph:\n        \"The frontier is the head of the work packet: the first ten open unit ids, in the order `loam tasks` says to \" +\n        \"take them. \" +\n        \"`--json` carries it as `frontier` (the first ten open unit ids, in order), with how many more are open beside \" +\n        \"it, and `--next` prints its head alone, in full, with what closes it. \" +\n        \"It is recomputed from the documents on every run, which is what makes taking the head of it always safe — so \" +\n        \"re-run `loam tasks <FEAT> --service <id>` after every recording instead of working down a list you copied out. \" +\n        \"When the packet is narrowed to one service, `waitingOn` names what another service still owes before your \" +\n        \"frontier can move.\",\n      pins: [\n        { source: \"IMPLEMENT\", phrase: \"`frontier` (the first ten open unit ids, in order)\" },\n        { source: \"IMPLEMENT\", phrase: \"every run, which is what makes taking the head of it always safe\" },\n        { source: \"IMPLEMENT\", phrase: \"still owes before your frontier can move\" },\n      ],\n    },\n    {\n      term: \"describe\",\n      aliases: [\"requirement.described\"],\n      paragraph:\n        \"Describe is the first step a `loam tasks` unit can wait at: the requirement owns no scenarios yet. \" +\n        \"So there is nothing to generate a test from and nothing for `loam verify` to claim. \" +\n        \"Write the Given/When/Then in the DOCS repo, on the requirement the unit's `source` names, and nothing else — \" +\n        \"loam does not author, and no amount of code closes a unit sitting here. \" +\n        \"Its kind is `requirement.described`, the one unit kind that is not a done-check claim, because a requirement \" +\n        \"with no scenario asks no question anybody could answer with evidence; it closes when the requirement carries \" +\n        \"at least one `#### Scenario:`, which `loam validate --feature <FEAT>` grades. \" +\n        \"The steps after it are `generate`, `implement` and `attested`.\",\n      pins: [\n        { source: \"IMPLEMENT\", phrase: \"the requirement owns no scenarios yet\" },\n        { source: \"IMPLEMENT\", phrase: \"no amount of code closes a unit sitting here\" },\n      ],\n    },\n    {\n      term: \"generate\",\n      aliases: [],\n      paragraph:\n        \"Generate is the step a `loam tasks` unit waits at when its scenario's test has not been generated yet. \" +\n        \"`generate` means no stamped `.feature` carries this scenario's digest, and the only action is \" +\n        \"`loam gherkin <FEAT>` in the service's own repository — do not write code. It writes one digest-stamped \" +\n        \"`.feature` per changed requirement under `<gherkinDir>/loam/`. Those files ARE the acceptance criteria. \" +\n        \"Never edit them: regeneration rewrites the directory. Generating is the whole action, and on the next run the \" +\n        \"same unit reads `implement`. \" +\n        \"The stamps are read from the repository `loam tasks` runs in, and nobody else's: an `unknown` makes every \" +\n        \"`generate` verdict a guess, so fix the binding before acting on one.\",\n      pins: [\n        { source: \"IMPLEMENT\", phrase: \"no stamped `.feature` carries this scenario's digest\" },\n        { source: \"IMPLEMENT\", phrase: \"Those files ARE the acceptance criteria.\" },\n        { source: \"IMPLEMENT\", phrase: \"an `unknown` makes every `generate` verdict a guess\" },\n      ],\n    },\n    {\n      term: \"implement\",\n      aliases: [],\n      paragraph:\n        \"Implement is the step a `loam tasks` unit waits at when what is still owed is code, or a recorded answer \" +\n        \"about code. \" +\n        \"For a scenario claim it means the stamped scenario exists and no recorded run has confirmed it: write step \" +\n        \"definitions outside the generated `loam/` directory, implement until the suite passes, then record the run \" +\n        \"with `loam verify <FEAT> --service <id> --results report.json`. \" +\n        \"For the other claim kinds it means the claim is not yet recorded confirmed: answer from the code with \" +\n        \"`file:line` evidence (`loam verify <FEAT> --record answers.json --service <id>`), or for `api.exposes` with a \" +\n        \"contract-test report. \" +\n        \"Either way the record decides — never your own reading of the code you just wrote — and the unit leaves \" +\n        \"the packet only once its claim is recorded confirmed. \" +\n        \"A scenario also reads `implement` when nothing could see its generated test — the stamps are read from the \" +\n        \"repository `loam tasks` runs in alone — so check `stamps` before writing a test by hand. \" +\n        \"`loam instructions loam-implement <FEAT>` is the whole protocol.\",\n      pins: [\n        { source: \"IMPLEMENT\", phrase: \"the stamped scenario exists and no recorded run has confirmed\" },\n        { source: \"IMPLEMENT\", phrase: \"never your own reading of the code you just wrote\" },\n      ],\n    },\n  ],\n};\n"]}