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

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"]}

package/dist/core/explain/terms.js

@@ -0,0 +1,103 @@
+/**
+ * The concept terms `loam explain` answers — the vocabulary wall an agent hits
+ * in its first minute, before any docs repo exists to read, and the words loam
+ * itself prints to a person: the stage `loam status` reports, the claims and
+ * verdicts of `loam verify`, the steps of `loam tasks`, the rungs of the
+ * maturity ladder.
+ *
+ * The paragraphs live one package down, in ./terms/, one module per subject;
+ * this module assembles them and names the texts their pins point at. The
+ * split came when the registry outgrew its first six terms: twenty-odd
+ * paragraphs do not fit one 400-line file, src/core/explain/ was already at
+ * its five-file cap, and the terms fall into the four clusters the listing
+ * prints them under — which is a subject seam, not a line count. `TERMS` and
+ * `PIN_SOURCE_TEXT` stay exported from here so every importer (the lookup, the
+ * MCP tool table, the tests) reads the registry from where it always did.
+ *
+ * Each paragraph is authored in ./terms/, but it is not free to drift: every
+ * entry carries pin phrases lifted VERBATIM from the section that teaches the
+ * concept, and test/explain.test.ts asserts each phrase appears both in the
+ * paragraph and in its named source constant. Rewording that prose therefore
+ * breaks the pairing loudly — the same discipline the compiler applies to
+ * refusals.ts, done with a test because prose has no type. A pin phrase is
+ * kept to one source LINE, because the sections wrap at ~80 columns and a
+ * phrase spanning a wrap would never match.
+ *
+ * A source is no longer always an agents-md section. When the reference pages
+ * were split out of the scaffolded AGENTS.md, the frontmatter teaching went
+ * with them, and `vouch`'s pin went with the text rather than being reworded
+ * to something still in the file — the pairing is with whatever loam SHIPS as
+ * the teaching, not with one delivery of it.
+ *
+ * The converse failure is a source that ships NOWHERE, and it happened: once
+ * AGENTS.md became the one ORIENTATION literal (../agent/agents-md.ts), the old
+ * section constants this file still imported — the long cycle, the layout
+ * opening, the binding rule — were assembled into nothing, so the pins on them
+ * guarded prose no reader could see and the drift test passed vacuously. Those
+ * sources were deleted with the constants; a pin now names a page the binary
+ * prints or the AGENTS.md it writes, never a constant that merely compiles.
+ * The five sources added with the printed-word terms follow that rule: each is
+ * a whole page `loam instructions` prints — the loam-codes page rather than its
+ * `loam status` section, the /loam-implement body rather than its step 3.
+ */
+import { AGENTS_MD } from "../agent/agents-md.js";
+import { REFUSALS } from "../agent/agents-md/refusals.js";
+import { LOAM_CHECK } from "../agent/workflows/check.js";
+import { LOAM_VERIFY } from "../agent/workflows/closing.js";
+import { LOAM_FEATURE } from "../agent/workflows/feature.js";
+import { LOAM_IMPLEMENT } from "../agent/workflows/implement.js";
+import { LOAM_AUTHORING } from "../agent/workflows/reference/authoring.js";
+import { LOAM_CODES } from "../agent/workflows/reference/codes.js";
+import { LOAM_DONE_CHECK } from "../agent/workflows/reference/done-check.js";
+import { LOAM_DRAWING } from "../agent/workflows/reference/drawing/drawing.js";
+import { LOAM_SPINE } from "../agent/workflows/reference/spine.js";
+import { DOCUMENT_TERMS, DRAWING_TERMS } from "./terms/documents.js";
+import { DONE_CHECK_TERMS } from "./terms/done-check.js";
+import { STAGE_TERMS } from "./terms/stages.js";
+import { TASK_TERMS } from "./terms/tasks.js";
+/**
+ * The shipped texts the pins point at, for the drift test and for anyone
+ * auditing a pairing.
+ *
+ * `REFUSALS` is still listed and still pinned against, and it is no longer a
+ * section of AGENTS.md — it is the refusal half of the `loam-codes` page. The
+ * constant is what a pin names, and the constant did not move; only its
+ * delivery did. `CODES_PAGE` is that whole page, which is where the `loam
+ * status` section teaching the five stage values is printed.
+ *
+ * The workflow bodies are the raw protocol text, `$1`/`$2` placeholders and
+ * all — `loam instructions` substitutes them on the way out — so a pin phrase
+ * must never span a placeholder, or it would match here and not on the page a
+ * reader is shown.
+ */
+export const PIN_SOURCE_TEXT = {
+    AGENTS_MD,
+    SPINE_PAGE: LOAM_SPINE.body,
+    REFUSALS,
+    AUTHORING: LOAM_AUTHORING.body,
+    DRAWING: LOAM_DRAWING.body,
+    DONE_CHECK: LOAM_DONE_CHECK.body,
+    CODES_PAGE: LOAM_CODES.body,
+    CHECK: LOAM_CHECK.body,
+    FEATURE: LOAM_FEATURE.body,
+    IMPLEMENT: LOAM_IMPLEMENT.body,
+    VERIFY: LOAM_VERIFY.body,
+};
+/**
+ * The registry, by subject, in the order the bare `loam explain` listing
+ * prints it: where a feature stands first, because `loam status` is the first
+ * command a newcomer runs, then the two commands whose words its next steps
+ * send a reader to, then the document vocabulary underneath all three, and
+ * last the words for drawing the map, which no command prints and every page
+ * that draws an edge uses.
+ */
+export const TERM_GROUPS = [
+    STAGE_TERMS,
+    DONE_CHECK_TERMS,
+    TASK_TERMS,
+    DOCUMENT_TERMS,
+    DRAWING_TERMS,
+];
+/** Every term, flat, in listing order — what the lookup searches and the `--json` listing returns. */
+export const TERMS = TERM_GROUPS.flatMap((group) => group.terms);
+//# sourceMappingURL=terms.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"terms.js","sourceRoot":"","sources":["../../../src/core/explain/terms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,iDAAiD,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,eAAe,GAA8B;IACxD,SAAS;IACT,UAAU,EAAE,UAAU,CAAC,IAAI;IAC3B,QAAQ;IACR,SAAS,EAAE,cAAc,CAAC,IAAI;IAC9B,OAAO,EAAE,YAAY,CAAC,IAAI;IAC1B,UAAU,EAAE,eAAe,CAAC,IAAI;IAChC,UAAU,EAAE,UAAU,CAAC,IAAI;IAC3B,KAAK,EAAE,UAAU,CAAC,IAAI;IACtB,OAAO,EAAE,YAAY,CAAC,IAAI;IAC1B,SAAS,EAAE,cAAc,CAAC,IAAI;IAC9B,MAAM,EAAE,WAAW,CAAC,IAAI;CACzB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAyB;IAC/C,WAAW;IACX,gBAAgB;IAChB,UAAU;IACV,cAAc;IACd,aAAa;CACd,CAAC;AAEF,sGAAsG;AACtG,MAAM,CAAC,MAAM,KAAK,GAAyB,WAAW,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC","sourcesContent":["/**\n * The concept terms `loam explain` answers — the vocabulary wall an agent hits\n * in its first minute, before any docs repo exists to read, and the words loam\n * itself prints to a person: the stage `loam status` reports, the claims and\n * verdicts of `loam verify`, the steps of `loam tasks`, the rungs of the\n * maturity ladder.\n *\n * The paragraphs live one package down, in ./terms/, one module per subject;\n * this module assembles them and names the texts their pins point at. The\n * split came when the registry outgrew its first six terms: twenty-odd\n * paragraphs do not fit one 400-line file, src/core/explain/ was already at\n * its five-file cap, and the terms fall into the four clusters the listing\n * prints them under — which is a subject seam, not a line count. `TERMS` and\n * `PIN_SOURCE_TEXT` stay exported from here so every importer (the lookup, the\n * MCP tool table, the tests) reads the registry from where it always did.\n *\n * Each paragraph is authored in ./terms/, but it is not free to drift: every\n * entry carries pin phrases lifted VERBATIM from the section that teaches the\n * concept, and test/explain.test.ts asserts each phrase appears both in the\n * paragraph and in its named source constant. Rewording that prose therefore\n * breaks the pairing loudly — the same discipline the compiler applies to\n * refusals.ts, done with a test because prose has no type. A pin phrase is\n * kept to one source LINE, because the sections wrap at ~80 columns and a\n * phrase spanning a wrap would never match.\n *\n * A source is no longer always an agents-md section. When the reference pages\n * were split out of the scaffolded AGENTS.md, the frontmatter teaching went\n * with them, and `vouch`'s pin went with the text rather than being reworded\n * to something still in the file — the pairing is with whatever loam SHIPS as\n * the teaching, not with one delivery of it.\n *\n * The converse failure is a source that ships NOWHERE, and it happened: once\n * AGENTS.md became the one ORIENTATION literal (../agent/agents-md.ts), the old\n * section constants this file still imported — the long cycle, the layout\n * opening, the binding rule — were assembled into nothing, so the pins on them\n * guarded prose no reader could see and the drift test passed vacuously. Those\n * sources were deleted with the constants; a pin now names a page the binary\n * prints or the AGENTS.md it writes, never a constant that merely compiles.\n * The five sources added with the printed-word terms follow that rule: each is\n * a whole page `loam instructions` prints — the loam-codes page rather than its\n * `loam status` section, the /loam-implement body rather than its step 3.\n */\nimport { AGENTS_MD } from \"../agent/agents-md.js\";\nimport { REFUSALS } from \"../agent/agents-md/refusals.js\";\nimport { LOAM_CHECK } from \"../agent/workflows/check.js\";\nimport { LOAM_VERIFY } from \"../agent/workflows/closing.js\";\nimport { LOAM_FEATURE } from \"../agent/workflows/feature.js\";\nimport { LOAM_IMPLEMENT } from \"../agent/workflows/implement.js\";\nimport { LOAM_AUTHORING } from \"../agent/workflows/reference/authoring.js\";\nimport { LOAM_CODES } from \"../agent/workflows/reference/codes.js\";\nimport { LOAM_DONE_CHECK } from \"../agent/workflows/reference/done-check.js\";\nimport { LOAM_DRAWING } from \"../agent/workflows/reference/drawing/drawing.js\";\nimport { LOAM_SPINE } from \"../agent/workflows/reference/spine.js\";\nimport { DOCUMENT_TERMS, DRAWING_TERMS } from \"./terms/documents.js\";\nimport { DONE_CHECK_TERMS } from \"./terms/done-check.js\";\nimport type { PinSource, TermEntry, TermGroup } from \"./terms/entry.js\";\nimport { STAGE_TERMS } from \"./terms/stages.js\";\nimport { TASK_TERMS } from \"./terms/tasks.js\";\n\n/**\n * The shipped texts the pins point at, for the drift test and for anyone\n * auditing a pairing.\n *\n * `REFUSALS` is still listed and still pinned against, and it is no longer a\n * section of AGENTS.md — it is the refusal half of the `loam-codes` page. The\n * constant is what a pin names, and the constant did not move; only its\n * delivery did. `CODES_PAGE` is that whole page, which is where the `loam\n * status` section teaching the five stage values is printed.\n *\n * The workflow bodies are the raw protocol text, `$1`/`$2` placeholders and\n * all — `loam instructions` substitutes them on the way out — so a pin phrase\n * must never span a placeholder, or it would match here and not on the page a\n * reader is shown.\n */\nexport const PIN_SOURCE_TEXT: Record<PinSource, string> = {\n  AGENTS_MD,\n  SPINE_PAGE: LOAM_SPINE.body,\n  REFUSALS,\n  AUTHORING: LOAM_AUTHORING.body,\n  DRAWING: LOAM_DRAWING.body,\n  DONE_CHECK: LOAM_DONE_CHECK.body,\n  CODES_PAGE: LOAM_CODES.body,\n  CHECK: LOAM_CHECK.body,\n  FEATURE: LOAM_FEATURE.body,\n  IMPLEMENT: LOAM_IMPLEMENT.body,\n  VERIFY: LOAM_VERIFY.body,\n};\n\n/**\n * The registry, by subject, in the order the bare `loam explain` listing\n * prints it: where a feature stands first, because `loam status` is the first\n * command a newcomer runs, then the two commands whose words its next steps\n * send a reader to, then the document vocabulary underneath all three, and\n * last the words for drawing the map, which no command prints and every page\n * that draws an edge uses.\n */\nexport const TERM_GROUPS: readonly TermGroup[] = [\n  STAGE_TERMS,\n  DONE_CHECK_TERMS,\n  TASK_TERMS,\n  DOCUMENT_TERMS,\n  DRAWING_TERMS,\n];\n\n/** Every term, flat, in listing order — what the lookup searches and the `--json` listing returns. */\nexport const TERMS: readonly TermEntry[] = TERM_GROUPS.flatMap((group) => group.terms);\n"]}

package/dist/core/explore/describe.js

@@ -0,0 +1,105 @@
+/**
+ * One service as the explorer sees it: what it is, what it touches, and the
+ * `loam new` line that would start work on it.
+ *
+ * Split from the walk in `./explore.ts` because it answers per SERVICE while
+ * that answers per QUESTION — the walk decides which services are in the answer
+ * and why, this fills each one in. `DescribeRequest` is a record rather than a
+ * parameter list for the ordinary reason: nine facts about one service, and no
+ * call site should be able to transpose two of them.
+ */
+import { existsSync } from "node:fs";
+import { FleetContext } from "../fleet-context.js";
+import {} from "../c4/likec4.js";
+import { landscapeEvidence, maturityGaps, serviceMaturity } from "../vocabulary/maturity.js";
+import { compareIds } from "../repo/entries.js";
+import { servicePathsAt } from "../repo/paths.js";
+// Type-only, so it is erased and no runtime edge points back at the walk.
+import {} from "./explore.js";
+export async function describe(req) {
+    const { id, reason, entry, relationships, svcOf } = req;
+    // The edge partition, the modelled probe and the apiExpected rule are ONE
+    // derivation (core/vocabulary/maturity.ts `landscapeEvidence`), shared with
+    // the context pack's living slice — the same rule spelled twice is how the
+    // same service grades `partial` in one command and `documented` in another.
+    const { inbound, outbound, modelled, apiExpected } = landscapeEvidence({
+        id,
+        parses: req.parses,
+        relationships,
+        elementIds: req.elements.map((e) => e.id),
+        svcOf,
+    });
+    // A service that does not exist has no rung: `empty` would be a claim about a
+    // directory nobody has made, and it reads as "exists, nothing in it" — the
+    // one state a caller most needs to tell it apart from.
+    if (entry === undefined) {
+        return {
+            id,
+            reason,
+            known: false,
+            maturity: null,
+            missing: [],
+            modelled,
+            operations: [],
+            // Not `unreadable`: there is no contract here to fail to read. A service
+            // with no directory owes nothing, and reporting a parse failure over an
+            // absent file would send a reader looking for a document to fix.
+            openapi: { unreadable: false },
+            inbound,
+            outbound,
+        };
+    }
+    const archSpec = existsSync(servicePathsAt(entry.dir).archSpec);
+    const input = { entry, archSpec, apiExpected };
+    // `readOpenapi`, not `operationIds`: a contract that exists but does not
+    // parse comes back from the id list as an EMPTY set, indistinguishable from a
+    // service with no endpoints — and "this service offers nothing" is the worst
+    // possible lie to tell somebody deciding whether to call it.
+    const api = await req.context.readOpenapi(servicePathsAt(entry.dir).openapi);
+    const operations = api.ops.filter((o) => !o.remove).map((o) => o.id);
+    return {
+        id,
+        reason,
+        known: true,
+        maturity: serviceMaturity(input),
+        missing: maturityGaps(input),
+        modelled,
+        operations,
+        openapi: {
+            unreadable: api.unreadable,
+            ...(api.error === undefined ? {} : { error: api.error }),
+        },
+        inbound,
+        outbound,
+    };
+}
+/**
+ * The service whose living contract defines an operationId, or null.
+ *
+ * Reads every service's `openapi.yaml`, which is the cost of asking a question
+ * nothing indexes. It is YAML, not LikeC4 — the expensive parse in this
+ * codebase — and it happens only when somebody passes `--op`.
+ */
+export async function operationOwner(entries, op, context) {
+    for (const entry of entries) {
+        if (!entry.has.openapi)
+            continue;
+        const api = await context.readOpenapi(servicePathsAt(entry.dir).openapi);
+        if (api.ops.some((o) => o.id === op && !o.remove))
+            return entry.id;
+    }
+    return null;
+}
+/**
+ * The `loam new` line the seeds imply. A seed that names no existing service is
+ * `--new-service`, not `--touches`: those are different scaffolds, and getting
+ * it wrong is what leaves a feature with a requirement delta for a service that
+ * has no directory to archive into.
+ */
+export function newCommand(featureId, seeds, known) {
+    const flags = [...seeds]
+        .sort(compareIds)
+        .map((id) => (known.has(id) ? `--touches ${id}` : `--new-service ${id}`));
+    return `loam new ${featureId}${flags.length > 0 ? ` ${flags.join(" ")}` : ""}`;
+}
+//# sourceMappingURL=describe.js.map

package/dist/core/explore/describe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.js","sourceRoot":"","sources":["../../../src/core/explore/describe.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One service as the explorer sees it: what it is, what it touches, and the\n * `loam new` line that would start work on it.\n *\n * Split from the walk in `./explore.ts` because it answers per SERVICE while\n * that answers per QUESTION — the walk decides which services are in the answer\n * and why, this fills each one in. `DescribeRequest` is a record rather than a\n * parameter list for the ordinary reason: nine facts about one service, and no\n * call site should be able to transpose two of them.\n */\nimport { existsSync } from \"node:fs\";\nimport { FleetContext } from \"../fleet-context.js\";\nimport { type Elem, type Rel } from \"../c4/likec4.js\";\nimport { landscapeEvidence, maturityGaps, serviceMaturity } from \"../vocabulary/maturity.js\";\nimport { compareIds, type ServiceEntry } from \"../repo/entries.js\";\nimport { servicePathsAt } from \"../repo/paths.js\";\n// Type-only, so it is erased and no runtime edge points back at the walk.\nimport { type ExploreReason, type ExploreService } from \"./explore.js\";\n\ninterface DescribeRequest {\n  id: string;\n  reason: ExploreReason;\n  entry: ServiceEntry | undefined;\n  relationships: Rel[];\n  svcOf: (id: string) => string;\n  elements: Elem[];\n  /** Whether the landscape parsed — what makes its silence evidence rather than absence. */\n  parses: boolean;\n  context: FleetContext;\n}\n\nexport async function describe(req: DescribeRequest): Promise<ExploreService> {\n  const { id, reason, entry, relationships, svcOf } = req;\n\n  // The edge partition, the modelled probe and the apiExpected rule are ONE\n  // derivation (core/vocabulary/maturity.ts `landscapeEvidence`), shared with\n  // the context pack's living slice — the same rule spelled twice is how the\n  // same service grades `partial` in one command and `documented` in another.\n  const { inbound, outbound, modelled, apiExpected } = landscapeEvidence({\n    id,\n    parses: req.parses,\n    relationships,\n    elementIds: req.elements.map((e) => e.id),\n    svcOf,\n  });\n\n  // A service that does not exist has no rung: `empty` would be a claim about a\n  // directory nobody has made, and it reads as \"exists, nothing in it\" — the\n  // one state a caller most needs to tell it apart from.\n  if (entry === undefined) {\n    return {\n      id,\n      reason,\n      known: false,\n      maturity: null,\n      missing: [],\n      modelled,\n      operations: [],\n      // Not `unreadable`: there is no contract here to fail to read. A service\n      // with no directory owes nothing, and reporting a parse failure over an\n      // absent file would send a reader looking for a document to fix.\n      openapi: { unreadable: false },\n      inbound,\n      outbound,\n    };\n  }\n\n  const archSpec = existsSync(servicePathsAt(entry.dir).archSpec);\n  const input = { entry, archSpec, apiExpected };\n\n  // `readOpenapi`, not `operationIds`: a contract that exists but does not\n  // parse comes back from the id list as an EMPTY set, indistinguishable from a\n  // service with no endpoints — and \"this service offers nothing\" is the worst\n  // possible lie to tell somebody deciding whether to call it.\n  const api = await req.context.readOpenapi(servicePathsAt(entry.dir).openapi);\n  const operations = api.ops.filter((o) => !o.remove).map((o) => o.id);\n\n  return {\n    id,\n    reason,\n    known: true,\n    maturity: serviceMaturity(input),\n    missing: maturityGaps(input),\n    modelled,\n    operations,\n    openapi: {\n      unreadable: api.unreadable,\n      ...(api.error === undefined ? {} : { error: api.error }),\n    },\n    inbound,\n    outbound,\n  };\n}\n\n/**\n * The service whose living contract defines an operationId, or null.\n *\n * Reads every service's `openapi.yaml`, which is the cost of asking a question\n * nothing indexes. It is YAML, not LikeC4 — the expensive parse in this\n * codebase — and it happens only when somebody passes `--op`.\n */\nexport async function operationOwner(\n  entries: ServiceEntry[],\n  op: string,\n  context: FleetContext,\n): Promise<ServiceEntry[\"id\"] | null> {\n  for (const entry of entries) {\n    if (!entry.has.openapi) continue;\n    const api = await context.readOpenapi(servicePathsAt(entry.dir).openapi);\n    if (api.ops.some((o) => o.id === op && !o.remove)) return entry.id;\n  }\n  return null;\n}\n\n/**\n * The `loam new` line the seeds imply. A seed that names no existing service is\n * `--new-service`, not `--touches`: those are different scaffolds, and getting\n * it wrong is what leaves a feature with a requirement delta for a service that\n * has no directory to archive into.\n */\nexport function newCommand(featureId: string, seeds: string[], known: ReadonlySet<string>): string {\n  const flags = [...seeds]\n    .sort(compareIds)\n    .map((id) => (known.has(id) ? `--touches ${id}` : `--new-service ${id}`));\n  return `loam new ${featureId}${flags.length > 0 ? ` ${flags.join(\" \")}` : \"\"}`;\n}\n"]}