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

package/dist/core/explain/terms.js

@@ -1,9 +1,21 @@
 /**
  * The concept terms `loam explain` answers — the vocabulary wall an agent hits
- * in its first minute, before any docs repo exists to read.
+ * 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.
  *
- * Each paragraph is authored HERE, but it is not free to drift: every entry
- * carries pin phrases lifted VERBATIM from the section that teaches the
+ * 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
@@ -16,129 +28,76 @@
  * 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 { ARTIFACTS } from "../agent/agents-md/artifacts.js";
-import { CYCLE } from "../agent/agents-md/cycle.js";
+import { AGENTS_MD } from "../agent/agents-md.js";
 import { REFUSALS } from "../agent/agents-md/refusals.js";
-import { SPINE } from "../agent/agents-md/spine.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 section constants the pins point at, for the drift test and for anyone
+ * 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.
+ * 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 = {
-    SPINE,
+    AGENTS_MD,
     SPINE_PAGE: LOAM_SPINE.body,
     REFUSALS,
-    CYCLE,
-    ARTIFACTS,
     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,
 };
-export const TERMS = [
-    {
-        term: "vouch",
-        aliases: ["vouched", "vouching"],
-        paragraph: "A vouch is the human promotion of a living document from draft to verified. " +
-            "Promoting draft to verified is their call, not yours: a person runs `loam vouch --service <id>` in the service's own repo, " +
-            "and the stamp records the date, who vouched (from git), and digests of both the source files and the document body — " +
-            "which is what lets a later `loam validate` report `sources.stale` and `content.stale` when the code or the words move. " +
-            "**`loam vouch` is not yours to run**, and it is built so that it cannot be. It refuses unattended runs (`vouch-unattended`), " +
-            "records a no as `vouch-declined`, and refuses to stamp when git can name nobody (`vouch-unattributable`); " +
-            "when your work leaves a document ready, hand back and say a vouch is owed.",
-        pins: [
-            // Both phrases left AGENTS.md with the frontmatter teaching and are now
-            // in `loam instructions loam-authoring`. Repaired by following the text,
-            // not by rewording the paragraph to something still in the file: the
-            // pairing exists so this paragraph and the teaching cannot drift, and
-            // re-pinning to a different sentence would have quietly ended it.
-            { source: "AUTHORING", phrase: "Promoting draft to verified is their call, not yours" },
-            { source: "AUTHORING", phrase: "**`loam vouch` is not yours to run**, and it is built so that it cannot be." },
-        ],
-    },
-    {
-        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.",
-        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" },
-        ],
-    },
-    {
-        term: "spine",
-        aliases: [],
-        paragraph: "The spine is a family of exact joins, not one magic id. Its ids are the feature tag (`#FEAT-101`), the service " +
-            "binding (`metadata { service }`), the synchronous operationId, the asynchronous message name, `Covers:` " +
-            "architecture coverage, `Requires:` permissions and `Capability:` realization. Three artifacts describe one synchronous call — " +
-            "a C4 edge, a requirement's `Operations:` line, the provider's openapi.yaml — joined by the operationId, and that " +
-            "join is what `loam validate` checks. Spell it identically in all three places. The `spine.*` findings are exactly " +
-            "these joins failing to resolve, and a mismatch is a broken contract between services, not a style problem.",
-        pins: [
-            { source: "SPINE_PAGE", phrase: "The spine is a family of exact joins, not one magic id" },
-            { source: "SPINE_PAGE", phrase: "Spell it identically in all three places." },
-        ],
-    },
-    {
-        term: "delta",
-        aliases: ["deltas"],
-        paragraph: "A delta is a feature's change, stated against the living docs rather than in them. " +
-            "The living spec.md is the complete current state; a feature's copy is a diff against it, reviewed as a diff, with " +
-            "requirements grouped under `## ADDED`, `## MODIFIED` or `## REMOVED Requirements`; delta.likec4 carries the " +
-            "architecture change with every changed element tagged `#<FEAT>` (untagged elements are context, not changes); " +
-            "and the contract deltas are complete documents whose baseline pins mark what is merely quoted. " +
-            "`loam archive` folds the delta into the living state. The `delta.*` findings grade that algebra — whether the " +
-            "diff still applies to the living document it claims to change.",
-        pins: [
-            { source: "ARTIFACTS", phrase: "is a diff against it, reviewed as a diff" },
-            { source: "ARTIFACTS", phrase: "`loam archive` folds the delta into the living state." },
-        ],
-    },
-    {
-        term: "axis",
-        aliases: ["axes"],
-        paragraph: "An axis is one language a service is described in, and loam's checks are joins BETWEEN axes rather than opinions within one. " +
-            "The three: architecture — a C4 edge names the operation it calls; behaviour — a requirement declares the " +
-            "operations it governs; contract — the provider's `openapi.yaml` defines it (asyncapi.yaml is the same axis for " +
-            "events, and arch.spec.md is the behaviour axis for architectural obligations). A finding code's prefix names the " +
-            "axes that disagree — `spec-api.op-undefined` is the behaviour axis joined against the contract axis — and the fix " +
-            "is whichever side is wrong about the world.",
-        pins: [
-            { source: "SPINE_PAGE", phrase: "architecture — a C4 edge names the operation it calls" },
-            { source: "SPINE_PAGE", phrase: "behaviour — a requirement declares the operations it governs" },
-            { source: "SPINE_PAGE", phrase: "contract — the provider's `openapi.yaml` defines it" },
-        ],
-    },
-    {
-        term: "baseline",
-        aliases: ["based-on", "baselines"],
-        paragraph: "A baseline is the pin tying a delta to the living version it was written against. It rides as `Based-On:` under a " +
-            "MODIFIED/REMOVED requirement and `x-loam-based-on` on a contract surface — written by `loam rebase <FEAT>`, never by " +
-            "hand. It exists because a MODIFIED requirement carries its FULL new text, not a diff, so the merge REPLACES the " +
-            "living text wholesale; the pin is what lets archive tell an edit from a quote and refuse a stale one " +
-            "(`delta.baseline-stale`, `openapi.baseline-stale`) instead of silently reverting work that landed in between. " +
-            `**Restamping is not resolving.** A pin claims "I read this version". ` +
-            "Re-read the living text and fold in what you still mean before you re-pin.",
-        pins: [
-            // Without the sentence-initial "A": the paragraph embeds the clause
-            // mid-sentence, and a pin is a verbatim substring of BOTH sides.
-            { source: "SPINE_PAGE", phrase: "MODIFIED requirement carries its FULL new text, not a diff" },
-            { source: "SPINE_PAGE", phrase: `**Restamping is not resolving.** A pin claims "I read this version".` },
-        ],
-    },
+/**
+ * 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

@@ -1 +1 @@
-{"version":3,"file":"terms.js","sourceRoot":"","sources":["../../../src/core/explain/terms.ts"],"names":[],"mappings":"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","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.\n *\n * Each paragraph is authored HERE, but it is not free to drift: every entry\n * 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 */\nimport { ARTIFACTS } from \"../agent/agents-md/artifacts.js\";\nimport { CYCLE } from \"../agent/agents-md/cycle.js\";\nimport { REFUSALS } from \"../agent/agents-md/refusals.js\";\nimport { SPINE } from \"../agent/agents-md/spine.js\";\nimport { LOAM_AUTHORING } from \"../agent/workflows/reference/authoring.js\";\nimport { LOAM_DONE_CHECK } from \"../agent/workflows/reference/done-check.js\";\nimport { LOAM_SPINE } from \"../agent/workflows/reference/spine.js\";\n\nexport type PinSource =\n  | \"SPINE\"\n  | \"SPINE_PAGE\"\n  | \"REFUSALS\"\n  | \"CYCLE\"\n  | \"ARTIFACTS\"\n  | \"AUTHORING\"\n  | \"DONE_CHECK\";\n\n/**\n * The section constants 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.\n */\nexport const PIN_SOURCE_TEXT: Record<PinSource, string> = {\n  SPINE,\n  SPINE_PAGE: LOAM_SPINE.body,\n  REFUSALS,\n  CYCLE,\n  ARTIFACTS,\n  AUTHORING: LOAM_AUTHORING.body,\n  DONE_CHECK: LOAM_DONE_CHECK.body,\n};\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\nexport const TERMS: readonly TermEntry[] = [\n  {\n    term: \"vouch\",\n    aliases: [\"vouched\", \"vouching\"],\n    paragraph:\n      \"A vouch is the human promotion of a living document from draft to verified. \" +\n      \"Promoting draft to verified is their call, not yours: a person runs `loam vouch --service <id>` in the service's own repo, \" +\n      \"and the stamp records the date, who vouched (from git), and digests of both the source files and the document body — \" +\n      \"which is what lets a later `loam validate` report `sources.stale` and `content.stale` when the code or the words move. \" +\n      \"**`loam vouch` is not yours to run**, and it is built so that it cannot be. It refuses unattended runs (`vouch-unattended`), \" +\n      \"records a no as `vouch-declined`, and refuses to stamp when git can name nobody (`vouch-unattributable`); \" +\n      \"when your work leaves a document ready, hand back and say a vouch is owed.\",\n    pins: [\n      // Both phrases left AGENTS.md with the frontmatter teaching and are now\n      // in `loam instructions loam-authoring`. Repaired by following the text,\n      // not by rewording the paragraph to something still in the file: the\n      // pairing exists so this paragraph and the teaching cannot drift, and\n      // re-pinning to a different sentence would have quietly ended it.\n      { source: \"AUTHORING\", phrase: \"Promoting draft to verified is their call, not yours\" },\n      { source: \"AUTHORING\", phrase: \"**`loam vouch` is not yours to run**, and it is built so that it cannot be.\" },\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    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    ],\n  },\n  {\n    term: \"spine\",\n    aliases: [],\n    paragraph:\n      \"The spine is a family of exact joins, not one magic id. Its ids are the feature tag (`#FEAT-101`), the service \" +\n      \"binding (`metadata { service }`), the synchronous operationId, the asynchronous message name, `Covers:` \" +\n      \"architecture coverage, `Requires:` permissions and `Capability:` realization. Three artifacts describe one synchronous call — \" +\n      \"a C4 edge, a requirement's `Operations:` line, the provider's openapi.yaml — joined by the operationId, and that \" +\n      \"join is what `loam validate` checks. Spell it identically in all three places. The `spine.*` findings are exactly \" +\n      \"these joins failing to resolve, and a mismatch is a broken contract between services, not a style problem.\",\n    pins: [\n      { source: \"SPINE_PAGE\", phrase: \"The spine is a family of exact joins, not one magic id\" },\n      { source: \"SPINE_PAGE\", phrase: \"Spell it identically in all three places.\" },\n    ],\n  },\n  {\n    term: \"delta\",\n    aliases: [\"deltas\"],\n    paragraph:\n      \"A delta is a feature's change, stated against the living docs rather than in them. \" +\n      \"The living spec.md is the complete current state; a feature's copy is a diff against it, reviewed as a diff, with \" +\n      \"requirements grouped under `## ADDED`, `## MODIFIED` or `## REMOVED Requirements`; delta.likec4 carries the \" +\n      \"architecture change with every changed element tagged `#<FEAT>` (untagged elements are context, not changes); \" +\n      \"and the contract deltas are complete documents whose baseline pins mark what is merely quoted. \" +\n      \"`loam archive` folds the delta into the living state. The `delta.*` findings grade that algebra — whether the \" +\n      \"diff still applies to the living document it claims to change.\",\n    pins: [\n      { source: \"ARTIFACTS\", phrase: \"is a diff against it, reviewed as a diff\" },\n      { source: \"ARTIFACTS\", phrase: \"`loam archive` folds the delta into the living state.\" },\n    ],\n  },\n  {\n    term: \"axis\",\n    aliases: [\"axes\"],\n    paragraph:\n      \"An axis is one language a service is described in, and loam's checks are joins BETWEEN axes rather than opinions within one. \" +\n      \"The three: architecture — a C4 edge names the operation it calls; behaviour — a requirement declares the \" +\n      \"operations it governs; contract — the provider's `openapi.yaml` defines it (asyncapi.yaml is the same axis for \" +\n      \"events, and arch.spec.md is the behaviour axis for architectural obligations). A finding code's prefix names the \" +\n      \"axes that disagree — `spec-api.op-undefined` is the behaviour axis joined against the contract axis — and the fix \" +\n      \"is whichever side is wrong about the world.\",\n    pins: [\n      { source: \"SPINE_PAGE\", phrase: \"architecture — a C4 edge names the operation it calls\" },\n      { source: \"SPINE_PAGE\", phrase: \"behaviour — a requirement declares the operations it governs\" },\n      { source: \"SPINE_PAGE\", phrase: \"contract — the provider's `openapi.yaml` defines it\" },\n    ],\n  },\n  {\n    term: \"baseline\",\n    aliases: [\"based-on\", \"baselines\"],\n    paragraph:\n      \"A baseline is the pin tying a delta to the living version it was written against. It rides as `Based-On:` under a \" +\n      \"MODIFIED/REMOVED requirement and `x-loam-based-on` on a contract surface — written by `loam rebase <FEAT>`, never by \" +\n      \"hand. It exists because a MODIFIED requirement carries its FULL new text, not a diff, so the merge REPLACES the \" +\n      \"living text wholesale; the pin is what lets archive tell an edit from a quote and refuse a stale one \" +\n      \"(`delta.baseline-stale`, `openapi.baseline-stale`) instead of silently reverting work that landed in between. \" +\n      `**Restamping is not resolving.** A pin claims \"I read this version\". ` +\n      \"Re-read the living text and fold in what you still mean before you re-pin.\",\n    pins: [\n      // Without the sentence-initial \"A\": the paragraph embeds the clause\n      // mid-sentence, and a pin is a verbatim substring of BOTH sides.\n      { source: \"SPINE_PAGE\", phrase: \"MODIFIED requirement carries its FULL new text, not a diff\" },\n      { source: \"SPINE_PAGE\", phrase: `**Restamping is not resolving.** A pin claims \"I read this version\".` },\n    ],\n  },\n];\n"]}
+{"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/explore.js

@@ -16,15 +16,20 @@
  * documentation has got — and stops. Which of those neighbours the feature
  * really touches is a judgement about intent, and loam does not make those.
  *
- * The landscape is parsed ONCE for the whole exploration. Per-service reads of
- * it exist (`brief/landscape.ts`'s `landscapeContext`) and are correct for one service;
+ * "The fleet map" here is the `architecture/` PROJECT — the landscape plus every
+ * other `.likec4` under it, minus the generated views file — and not the
+ * landscape FILE. See the read below for the disagreement that reading one file
+ * caused.
+ *
+ * It is parsed ONCE for the whole exploration. Per-service reads of it exist
+ * (`brief/landscape.ts`'s `landscapeContext`) and are correct for one service;
  * calling one of those per seed is how `validate --all` came to cost 13 seconds
  * on 120 services, and this command sits in front of authoring, where that is
  * the difference between a habit and a thing people skip.
  */
 import { existsSync } from "node:fs";
 import { FleetContext } from "../fleet-context.js";
-import {} from "../c4/likec4.js";
+import { brokenDocumentPaths } from "../c4/likec4.js";
 import { serviceResolver } from "../c4/resolve/service.js";
 import {} from "../vocabulary/maturity.js";
 import { capabilityRollup, unresolvedCapabilities } from "../capabilities/rollup.js";
@@ -43,9 +48,24 @@ export async function explore(req) {
     const entries = await context.listServices(docsDir);
     const byId = new Map(entries.map((e) => [e.id, e]));
     const known = new Set(byId.keys());
-    const landPath = landscapePath(docsDir);
-    const present = existsSync(landPath);
-    const land = present ? await context.loadLikeC4(landPath) : null;
+    // The `architecture/` PROJECT, never `architecture/landscape.likec4` alone.
+    // The map is a project — the landscape merged with every use case, palette and
+    // second `model { }` block beside it — and reading one file of it made this
+    // command answer differently from `loam adopt` and `loam context` about the
+    // same tree (reproduced: with a broken `architecture/palette.likec4` beside a
+    // landscape that parses, `context checkout-web --json` reported
+    // `landscape.parses: false` while `explore checkout-web --json` reported
+    // `parses: true` and went on to describe every edge). `core/pack/living.ts`
+    // named this module as the last reader that disagreed. Whichever answer is
+    // right, an agent handed both has no way to tell — and the renderer's answer
+    // is the project's.
+    //
+    // `present` stays a fact about the FILE, because that file is the WRITE target:
+    // `loam new`'s scaffold and every brief ask for edits to
+    // `architecture/landscape.likec4` by name, and "the project is empty" is not
+    // the same instruction as "there is no map to edit".
+    const present = existsSync(landscapePath(docsDir));
+    const land = present ? await context.architecture(docsDir) : null;
     const parses = land !== null && land.errors.length === 0;
     const elements = parses ? land.elements : [];
     const relationships = parses ? land.relationships : [];
@@ -79,9 +99,15 @@ export async function explore(req) {
     // other: a service can realize a capability without appearing in its drawn
     // flow, and a flow can pass through a service that has written nothing down.
     //
-    // The scan gates its own load, and this whole block is already behind
-    // `--capability` being passed at all, so an exploration by service or by
-    // operation never touches `architecture/` as a project.
+    // The scan gates its own load — a fleet whose documents mention no reserved
+    // tag never starts LikeC4 for it — and this whole block is behind
+    // `--capability` being passed at all. What it is no longer behind is the
+    // project itself: the read above loads `architecture/` for every exploration,
+    // so a `--capability` run pays for a SECOND parse of the same documents
+    // (`readUseCases` takes a `DocsDir`, not this invocation's memo). Accepted
+    // rather than unnoticed: the alternative is a seam that hands the scan a
+    // pre-loaded project, which is a change to a module five callers share, and
+    // the cost lands only on the flag that already opts into the fleet rollup.
     const capSeeds = [];
     let unresolvedCaps = [];
     if (req.capabilities.length > 0) {
@@ -167,7 +193,11 @@ export async function explore(req) {
         services,
         neighbours: [...ring.keys()].sort(compareIds),
         overlaps,
-        landscape: { present, parses },
+        landscape: {
+            present,
+            parses,
+            broken: land === null ? [] : brokenDocumentPaths(docsDir, land.errors),
+        },
         scaffold: newCommand(featureId, seeds, known),
     };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"explore.js","sourceRoot":"","sources":["../../../src/core/explore/explore.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The blast radius of a change nobody has written down yet.\n *\n * Everything else in loam answers a question about documents that exist. This\n * module answers the one that comes BEFORE the first document: which services\n * does this feature actually touch? On a fleet of a hundred that call is the\n * hardest one in the cycle and the only one made with no tool in hand —\n * `loam new FEAT-101 --touches a --touches b` takes the answer as an argument\n * and scaffolds whatever it was told. A `--touches` list short by one service\n * is not caught by anything: the feature validates, archives, and ships with a\n * consumer nobody updated.\n *\n * So this states the work the same way `brief/brief.ts` does. It reads the fleet map\n * and the living contracts, reports the ring of services around the seeds, the\n * features already in flight over the same ground, and how far each service's\n * documentation has got — and stops. Which of those neighbours the feature\n * really touches is a judgement about intent, and loam does not make those.\n *\n * The landscape is parsed ONCE for the whole exploration. Per-service reads of\n * it exist (`brief/landscape.ts`'s `landscapeContext`) and are correct for one service;\n * calling one of those per seed is how `validate --all` came to cost 13 seconds\n * on 120 services, and this command sits in front of authoring, where that is\n * the difference between a habit and a thing people skip.\n */\nimport { existsSync } from \"node:fs\";\nimport { FleetContext } from \"../fleet-context.js\";\nimport { type Rel } from \"../c4/likec4.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport { type Maturity } from \"../vocabulary/maturity.js\";\nimport { capabilityRollup, unresolvedCapabilities } from \"../capabilities/rollup.js\";\nimport { compareIds, nearestIds, type ServiceEntry } from \"../repo/entries.js\";\nimport { landscapePath } from \"../repo/paths.js\";\nimport { readUseCases } from \"../usecases/fleet.js\";\nimport { servicesInFlowsClaiming } from \"../usecases/capability.js\";\nimport { describe, newCommand, operationOwner } from \"./describe.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/** One end of a call the fleet map already draws. */\nexport interface ExploreEdge {\n  /** The service at the other end. */\n  service: string;\n  /** The operationId the call uses, or null for an edge nobody tied to one. */\n  op: string | null;\n  title: string | null;\n}\n\n/**\n * Why a service is in the answer. Seeds were asked for; the rest were derived.\n *\n * A neighbour on both sides of a seed reports `calls-seed` — see the overlap\n * rule in `explore`. The field is a hint about where to look, not a complete\n * description of the edges; `inbound`/`outbound` are that.\n */\nexport type ExploreReason = \"seed\" | \"calls-seed\" | \"called-by-seed\";\n\nexport interface ExploreService {\n  id: string;\n  reason: ExploreReason;\n  /** Whether `services/<id>/` exists at all. */\n  known: boolean;\n  /**\n   * How far this service's documentation has got, or null when it does not\n   * exist yet. A `--touches` naming a service at `empty` or `partial` is a\n   * different job from one naming a vouched service, and the difference decides\n   * whether the feature starts with `loam adopt`.\n   */\n  maturity: Maturity | null;\n  /** What stands between it and `vouched` — `maturityGaps`, so it matches `list --needs-work`. */\n  missing: string[];\n  /** Whether anything in the fleet map resolves to it. */\n  modelled: boolean;\n  /** operationIds its living contract exposes today, `x-loam-remove` markers excluded. */\n  operations: string[];\n  /**\n   * Whether that contract could be read at all, beside the `error` the parser\n   * gave when it could not.\n   *\n   * It rides next to `operations` rather than inside it for the reason `delta`\n   * carries the same pair: an unreadable contract yields an EMPTY operation\n   * list, indistinguishable from a service with no endpoints — and this is the\n   * field the workflow tells an agent to read before deciding whether an\n   * operation it is about to add already exists. Answering `[]` over a YAML\n   * error is how a MODIFIED requirement gets authored as ADDED.\n   */\n  openapi: { unreadable: boolean; error?: string };\n  inbound: ExploreEdge[];\n  outbound: ExploreEdge[];\n}\n\n/** An active feature already working over ground the exploration covers. */\nexport interface ExploreOverlap {\n  feature: string;\n  /** The explored services it already carries a delta for. */\n  services: string[];\n}\n\nexport interface Exploration {\n  /** The seed ids, as asked for. */\n  seeds: string[];\n  /**\n   * Seeds that name no `services/<id>/`, each with the closest real ids. A seed\n   * may legitimately be a service the feature INTRODUCES, so this is reported\n   * rather than refused — but a typo produces exactly the same shape, and the\n   * near-miss list is what tells the two apart.\n   */\n  unknown: Array<{ id: string; nearest: string[] }>;\n  /** Operation seeds that resolved to no service's living contract. */\n  unresolvedOperations: string[];\n  /**\n   * Capability seeds that seeded nothing: not declared in\n   * architecture/capabilities.yaml (the file may not exist at all — explore\n   * refuses nothing, every miss is a field), or declared and realized by no\n   * living requirement. One list on purpose; splitting the two miss kinds\n   * waits for a consumer to ask.\n   */\n  unresolvedCapabilities: string[];\n  /** Seeds first, then the ring, each in id order. */\n  services: ExploreService[];\n  /** Ids the ring added that were not asked for — the candidates to weigh. */\n  neighbours: string[];\n  overlaps: ExploreOverlap[];\n  landscape: { present: boolean; parses: boolean };\n  /**\n   * The literal `loam new` line the seeds imply — seeds only. The ring is\n   * deliberately NOT folded in: this module's whole claim is that it does not\n   * know which neighbours the feature touches, and a command line that quietly\n   * included them would make the guess on the reader's behalf and look derived\n   * while doing it.\n   *\n   * Named for what it does rather than `command`, which is the envelope's key\n   * for the command that RAN. The rename is not cosmetic: `emitJson` spreads\n   * the payload LAST, so a payload field called `command` would silently\n   * OVERRIDE the envelope's — `command` would come back as\n   * `\"loam new FEAT-000 …\"`, and every consumer branching on\n   * `command === \"explore\"` (the same key `status`, `doctor`, `dependencies`,\n   * `archive` and `unarchive` emit) would quietly stop matching, with tsc and\n   * the linter green throughout.\n   */\n  scaffold: string;\n}\n\nexport interface ExploreRequest {\n  docsDir: DocsDir;\n  /** Service ids to explore around. Checked at the command boundary. */\n  services: ServiceEntry[\"id\"][];\n  /** operationIds to explore around; each resolves to the service that defines it. */\n  operations: string[];\n  /** Declared capability ids to explore around; each seeds its realizing services. */\n  capabilities: string[];\n  /** Placeholder feature id for the suggested command line. */\n  featureId: string;\n  context?: FleetContext;\n}\n\n/**\n * Read the fleet around a proposed change. Reads only; writes nothing, and\n * refuses nothing — every miss is reported as a field.\n */\nexport async function explore(req: ExploreRequest): Promise<Exploration> {\n  const { docsDir, featureId } = req;\n  const context = req.context ?? new FleetContext();\n  const entries = await context.listServices(docsDir);\n  const byId = new Map<string, ServiceEntry>(entries.map((e) => [e.id, e]));\n  const known: ReadonlySet<string> = new Set(byId.keys());\n\n  const landPath = landscapePath(docsDir);\n  const present = existsSync(landPath);\n  const land = present ? await context.loadLikeC4(landPath) : null;\n  const parses = land !== null && land.errors.length === 0;\n  const elements = parses ? land.elements : [];\n  const relationships: Rel[] = parses ? land.relationships : [];\n  // One resolver for the whole scan, built with the real service ids so an edge\n  // drawn into a modelled container (`paymentService.api`) counts for the\n  // service that owns it — the same resolution `list`, `show` and `validate`\n  // use, so no two commands can disagree about who calls whom.\n  const svcOf = serviceResolver(elements, known);\n\n  // Operation seeds resolve through the living contracts, not the map: the map\n  // says who CALLS an operation, and the question here is who DEFINES it.\n  const opSeeds: ServiceEntry[\"id\"][] = [];\n  const unresolvedOperations: string[] = [];\n  for (const op of req.operations) {\n    const owner = await operationOwner(entries, op, context);\n    if (owner === null) unresolvedOperations.push(op);\n    else opSeeds.push(owner);\n  }\n\n  // Capability seeds resolve through the vocabulary and the fleet rollup —\n  // one rollup pass for ALL requested ids, through this exploration's shared\n  // context cache, never a fresh walk per capability. A realizing service is\n  // by construction an enumerated one, so every seed it adds is `known`.\n  //\n  // And through the fleet's USE CASES, which answer the same question off a\n  // different document. The rollup finds services whose living requirements\n  // carry a `Capability:` line; a `dynamic view` tagged `#cap-<slug>` finds the\n  // services the flow actually runs through — including ones whose spec.md has\n  // never named the capability, which on a brownfield fleet is most of them.\n  // The two are unioned rather than ranked because neither is a subset of the\n  // other: a service can realize a capability without appearing in its drawn\n  // flow, and a flow can pass through a service that has written nothing down.\n  //\n  // The scan gates its own load, and this whole block is already behind\n  // `--capability` being passed at all, so an exploration by service or by\n  // operation never touches `architecture/` as a project.\n  const capSeeds: ServiceEntry[\"id\"][] = [];\n  let unresolvedCaps: string[] = [];\n  if (req.capabilities.length > 0) {\n    const vocab = await context.capabilities(docsDir);\n    const rows = await capabilityRollup({ services: entries, vocab, read: (p) => context.readRequirements(p) });\n    const wanted = new Set(req.capabilities);\n    const realizing = new Set(rows.filter((r) => wanted.has(r.id)).flatMap((r) => r.services));\n    const scan = await readUseCases({ docsDir, known });\n    for (const id of servicesInFlowsClaiming(scan, req.capabilities)) realizing.add(id);\n    capSeeds.push(...entries.filter((e) => realizing.has(e.id)).map((e) => e.id));\n    // `unresolvedCapabilities` is unchanged on purpose: it grades the\n    // VOCABULARY — declared or not, realized by a living requirement or not —\n    // and a capability drawn in a flow but realized by nobody is still a\n    // capability nothing implements. Letting a tag silence that would hide the\n    // gap the field exists to name.\n    unresolvedCaps = unresolvedCapabilities(rows, req.capabilities);\n  }\n\n  const seeds = [...new Set([...req.services, ...opSeeds, ...capSeeds])];\n  const unknown = seeds\n    .filter((id) => !known.has(id))\n    .map((id) => ({ id, nearest: nearestIds(id, [...known]) }));\n\n  // The ring: one hop, both directions. A seed that is not modelled contributes\n  // nothing here and that is the honest answer — an invisible service has no\n  // neighbours anyone can derive, which is what `landscape.service-unmodelled`\n  // is about.\n  //\n  // The two directions are collected separately rather than written into one\n  // map as the loop goes, because a neighbour can be BOTH — it calls a seed and\n  // the seed calls it — and a single-map version answers whichever edge the\n  // parser happened to yield last. That is a field whose value depends on the\n  // order lines appear in a `.likec4` file, which is the kind of answer that\n  // reads as derived and is not.\n  const seedSet = new Set<string>(seeds);\n  const callsSeed = new Set<string>();\n  const calledBySeed = new Set<string>();\n  for (const r of relationships) {\n    const from = svcOf(r.source);\n    const to = svcOf(r.target);\n    if (seedSet.has(from) && !seedSet.has(to)) calledBySeed.add(to);\n    if (seedSet.has(to) && !seedSet.has(from)) callsSeed.add(from);\n  }\n\n  // `calls-seed` wins the overlap, deterministically. Of the two directions it\n  // is the one that more often has to be touched: a consumer depends on the\n  // seed's contract, so a change to that contract is what breaks it, while a\n  // provider the seed merely calls is usually unaffected by the seed changing.\n  const ring = new Map<string, ExploreReason>([\n    ...[...calledBySeed].map((id) => [id, \"called-by-seed\" as const] as const),\n    ...[...callsSeed].map((id) => [id, \"calls-seed\" as const] as const),\n  ]);\n\n  const ordered: Array<{ id: string; reason: ExploreReason }> = [\n    ...[...seeds].sort(compareIds).map((id) => ({ id, reason: \"seed\" as const })),\n    ...[...ring]\n      .sort(([a], [b]) => compareIds(a, b))\n      .map(([id, reason]) => ({ id, reason })),\n  ];\n\n  const services: ExploreService[] = [];\n  for (const { id, reason } of ordered) {\n    services.push(\n      await describe({\n        id,\n        reason,\n        entry: byId.get(id),\n        relationships,\n        svcOf,\n        elements,\n        parses,\n        context,\n      }),\n    );\n  }\n\n  const covered = new Set(services.map((s) => s.id));\n  const features = await context.listFeatures(docsDir);\n  const overlaps: ExploreOverlap[] = features\n    .map((f) => ({ feature: f.id, services: f.services.filter((s) => covered.has(s)) }))\n    .filter((o) => o.services.length > 0)\n    .sort((a, b) => compareIds(a.feature, b.feature));\n\n  return {\n    seeds,\n    unknown,\n    unresolvedOperations,\n    unresolvedCapabilities: unresolvedCaps,\n    services,\n    neighbours: [...ring.keys()].sort(compareIds),\n    overlaps,\n    landscape: { present, parses },\n    scaffold: newCommand(featureId, seeds, known),\n  };\n}\n"]}
+{"version":3,"file":"explore.js","sourceRoot":"","sources":["../../../src/core/explore/explore.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The blast radius of a change nobody has written down yet.\n *\n * Everything else in loam answers a question about documents that exist. This\n * module answers the one that comes BEFORE the first document: which services\n * does this feature actually touch? On a fleet of a hundred that call is the\n * hardest one in the cycle and the only one made with no tool in hand —\n * `loam new FEAT-101 --touches a --touches b` takes the answer as an argument\n * and scaffolds whatever it was told. A `--touches` list short by one service\n * is not caught by anything: the feature validates, archives, and ships with a\n * consumer nobody updated.\n *\n * So this states the work the same way `brief/brief.ts` does. It reads the fleet map\n * and the living contracts, reports the ring of services around the seeds, the\n * features already in flight over the same ground, and how far each service's\n * documentation has got — and stops. Which of those neighbours the feature\n * really touches is a judgement about intent, and loam does not make those.\n *\n * \"The fleet map\" here is the `architecture/` PROJECT — the landscape plus every\n * other `.likec4` under it, minus the generated views file — and not the\n * landscape FILE. See the read below for the disagreement that reading one file\n * caused.\n *\n * It is parsed ONCE for the whole exploration. Per-service reads of it exist\n * (`brief/landscape.ts`'s `landscapeContext`) and are correct for one service;\n * calling one of those per seed is how `validate --all` came to cost 13 seconds\n * on 120 services, and this command sits in front of authoring, where that is\n * the difference between a habit and a thing people skip.\n */\nimport { existsSync } from \"node:fs\";\nimport { FleetContext } from \"../fleet-context.js\";\nimport { brokenDocumentPaths, type Rel } from \"../c4/likec4.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport { type Maturity } from \"../vocabulary/maturity.js\";\nimport { capabilityRollup, unresolvedCapabilities } from \"../capabilities/rollup.js\";\nimport { compareIds, nearestIds, type ServiceEntry } from \"../repo/entries.js\";\nimport { landscapePath } from \"../repo/paths.js\";\nimport { readUseCases } from \"../usecases/fleet.js\";\nimport { servicesInFlowsClaiming } from \"../usecases/capability.js\";\nimport { describe, newCommand, operationOwner } from \"./describe.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/** One end of a call the fleet map already draws. */\nexport interface ExploreEdge {\n  /** The service at the other end. */\n  service: string;\n  /** The operationId the call uses, or null for an edge nobody tied to one. */\n  op: string | null;\n  title: string | null;\n}\n\n/**\n * Why a service is in the answer. Seeds were asked for; the rest were derived.\n *\n * A neighbour on both sides of a seed reports `calls-seed` — see the overlap\n * rule in `explore`. The field is a hint about where to look, not a complete\n * description of the edges; `inbound`/`outbound` are that.\n */\nexport type ExploreReason = \"seed\" | \"calls-seed\" | \"called-by-seed\";\n\nexport interface ExploreService {\n  id: string;\n  reason: ExploreReason;\n  /** Whether `services/<id>/` exists at all. */\n  known: boolean;\n  /**\n   * How far this service's documentation has got, or null when it does not\n   * exist yet. A `--touches` naming a service at `empty` or `partial` is a\n   * different job from one naming a vouched service, and the difference decides\n   * whether the feature starts with `loam adopt`.\n   */\n  maturity: Maturity | null;\n  /** What stands between it and `vouched` — `maturityGaps`, so it matches `list --needs-work`. */\n  missing: string[];\n  /** Whether anything in the fleet map resolves to it. */\n  modelled: boolean;\n  /** operationIds its living contract exposes today, `x-loam-remove` markers excluded. */\n  operations: string[];\n  /**\n   * Whether that contract could be read at all, beside the `error` the parser\n   * gave when it could not.\n   *\n   * It rides next to `operations` rather than inside it for the reason `delta`\n   * carries the same pair: an unreadable contract yields an EMPTY operation\n   * list, indistinguishable from a service with no endpoints — and this is the\n   * field the workflow tells an agent to read before deciding whether an\n   * operation it is about to add already exists. Answering `[]` over a YAML\n   * error is how a MODIFIED requirement gets authored as ADDED.\n   */\n  openapi: { unreadable: boolean; error?: string };\n  inbound: ExploreEdge[];\n  outbound: ExploreEdge[];\n}\n\n/** An active feature already working over ground the exploration covers. */\nexport interface ExploreOverlap {\n  feature: string;\n  /** The explored services it already carries a delta for. */\n  services: string[];\n}\n\nexport interface Exploration {\n  /** The seed ids, as asked for. */\n  seeds: string[];\n  /**\n   * Seeds that name no `services/<id>/`, each with the closest real ids. A seed\n   * may legitimately be a service the feature INTRODUCES, so this is reported\n   * rather than refused — but a typo produces exactly the same shape, and the\n   * near-miss list is what tells the two apart.\n   */\n  unknown: Array<{ id: string; nearest: string[] }>;\n  /** Operation seeds that resolved to no service's living contract. */\n  unresolvedOperations: string[];\n  /**\n   * Capability seeds that seeded nothing: not declared in\n   * architecture/capabilities.yaml (the file may not exist at all — explore\n   * refuses nothing, every miss is a field), or declared and realized by no\n   * living requirement. One list on purpose; splitting the two miss kinds\n   * waits for a consumer to ask.\n   */\n  unresolvedCapabilities: string[];\n  /** Seeds first, then the ring, each in id order. */\n  services: ExploreService[];\n  /** Ids the ring added that were not asked for — the candidates to weigh. */\n  neighbours: string[];\n  overlaps: ExploreOverlap[];\n  /**\n   * `broken` is the `architecture/` documents that failed, docs-relative POSIX,\n   * deduped and sorted — `[]` while `parses` is true. `parses` answers for the\n   * PROJECT, so the broken document is very often a SIBLING beside a landscape\n   * that reads perfectly, and naming the landscape file was a claim about bytes\n   * loam read fine (verification 2026-09-04). Spelled as `landscape.invalid`\n   * spells it (both through `c4/likec4.ts`'s `brokenDocumentPaths`), so the\n   * two surfaces name one file one way.\n   */\n  landscape: { present: boolean; parses: boolean; broken: string[] };\n  /**\n   * The literal `loam new` line the seeds imply — seeds only. The ring is\n   * deliberately NOT folded in: this module's whole claim is that it does not\n   * know which neighbours the feature touches, and a command line that quietly\n   * included them would make the guess on the reader's behalf and look derived\n   * while doing it.\n   *\n   * Named for what it does rather than `command`, which is the envelope's key\n   * for the command that RAN. The rename is not cosmetic: `emitJson` spreads\n   * the payload LAST, so a payload field called `command` would silently\n   * OVERRIDE the envelope's — `command` would come back as\n   * `\"loam new FEAT-000 …\"`, and every consumer branching on\n   * `command === \"explore\"` (the same key `status`, `doctor`, `dependencies`,\n   * `archive` and `unarchive` emit) would quietly stop matching, with tsc and\n   * the linter green throughout.\n   */\n  scaffold: string;\n}\n\nexport interface ExploreRequest {\n  docsDir: DocsDir;\n  /** Service ids to explore around. Checked at the command boundary. */\n  services: ServiceEntry[\"id\"][];\n  /** operationIds to explore around; each resolves to the service that defines it. */\n  operations: string[];\n  /** Declared capability ids to explore around; each seeds its realizing services. */\n  capabilities: string[];\n  /** Placeholder feature id for the suggested command line. */\n  featureId: string;\n  context?: FleetContext;\n}\n\n/**\n * Read the fleet around a proposed change. Reads only; writes nothing, and\n * refuses nothing — every miss is reported as a field.\n */\nexport async function explore(req: ExploreRequest): Promise<Exploration> {\n  const { docsDir, featureId } = req;\n  const context = req.context ?? new FleetContext();\n  const entries = await context.listServices(docsDir);\n  const byId = new Map<string, ServiceEntry>(entries.map((e) => [e.id, e]));\n  const known: ReadonlySet<string> = new Set(byId.keys());\n\n  // The `architecture/` PROJECT, never `architecture/landscape.likec4` alone.\n  // The map is a project — the landscape merged with every use case, palette and\n  // second `model { }` block beside it — and reading one file of it made this\n  // command answer differently from `loam adopt` and `loam context` about the\n  // same tree (reproduced: with a broken `architecture/palette.likec4` beside a\n  // landscape that parses, `context checkout-web --json` reported\n  // `landscape.parses: false` while `explore checkout-web --json` reported\n  // `parses: true` and went on to describe every edge). `core/pack/living.ts`\n  // named this module as the last reader that disagreed. Whichever answer is\n  // right, an agent handed both has no way to tell — and the renderer's answer\n  // is the project's.\n  //\n  // `present` stays a fact about the FILE, because that file is the WRITE target:\n  // `loam new`'s scaffold and every brief ask for edits to\n  // `architecture/landscape.likec4` by name, and \"the project is empty\" is not\n  // the same instruction as \"there is no map to edit\".\n  const present = existsSync(landscapePath(docsDir));\n  const land = present ? await context.architecture(docsDir) : null;\n  const parses = land !== null && land.errors.length === 0;\n  const elements = parses ? land.elements : [];\n  const relationships: Rel[] = parses ? land.relationships : [];\n  // One resolver for the whole scan, built with the real service ids so an edge\n  // drawn into a modelled container (`paymentService.api`) counts for the\n  // service that owns it — the same resolution `list`, `show` and `validate`\n  // use, so no two commands can disagree about who calls whom.\n  const svcOf = serviceResolver(elements, known);\n\n  // Operation seeds resolve through the living contracts, not the map: the map\n  // says who CALLS an operation, and the question here is who DEFINES it.\n  const opSeeds: ServiceEntry[\"id\"][] = [];\n  const unresolvedOperations: string[] = [];\n  for (const op of req.operations) {\n    const owner = await operationOwner(entries, op, context);\n    if (owner === null) unresolvedOperations.push(op);\n    else opSeeds.push(owner);\n  }\n\n  // Capability seeds resolve through the vocabulary and the fleet rollup —\n  // one rollup pass for ALL requested ids, through this exploration's shared\n  // context cache, never a fresh walk per capability. A realizing service is\n  // by construction an enumerated one, so every seed it adds is `known`.\n  //\n  // And through the fleet's USE CASES, which answer the same question off a\n  // different document. The rollup finds services whose living requirements\n  // carry a `Capability:` line; a `dynamic view` tagged `#cap-<slug>` finds the\n  // services the flow actually runs through — including ones whose spec.md has\n  // never named the capability, which on a brownfield fleet is most of them.\n  // The two are unioned rather than ranked because neither is a subset of the\n  // other: a service can realize a capability without appearing in its drawn\n  // flow, and a flow can pass through a service that has written nothing down.\n  //\n  // The scan gates its own load — a fleet whose documents mention no reserved\n  // tag never starts LikeC4 for it — and this whole block is behind\n  // `--capability` being passed at all. What it is no longer behind is the\n  // project itself: the read above loads `architecture/` for every exploration,\n  // so a `--capability` run pays for a SECOND parse of the same documents\n  // (`readUseCases` takes a `DocsDir`, not this invocation's memo). Accepted\n  // rather than unnoticed: the alternative is a seam that hands the scan a\n  // pre-loaded project, which is a change to a module five callers share, and\n  // the cost lands only on the flag that already opts into the fleet rollup.\n  const capSeeds: ServiceEntry[\"id\"][] = [];\n  let unresolvedCaps: string[] = [];\n  if (req.capabilities.length > 0) {\n    const vocab = await context.capabilities(docsDir);\n    const rows = await capabilityRollup({ services: entries, vocab, read: (p) => context.readRequirements(p) });\n    const wanted = new Set(req.capabilities);\n    const realizing = new Set(rows.filter((r) => wanted.has(r.id)).flatMap((r) => r.services));\n    const scan = await readUseCases({ docsDir, known });\n    for (const id of servicesInFlowsClaiming(scan, req.capabilities)) realizing.add(id);\n    capSeeds.push(...entries.filter((e) => realizing.has(e.id)).map((e) => e.id));\n    // `unresolvedCapabilities` is unchanged on purpose: it grades the\n    // VOCABULARY — declared or not, realized by a living requirement or not —\n    // and a capability drawn in a flow but realized by nobody is still a\n    // capability nothing implements. Letting a tag silence that would hide the\n    // gap the field exists to name.\n    unresolvedCaps = unresolvedCapabilities(rows, req.capabilities);\n  }\n\n  const seeds = [...new Set([...req.services, ...opSeeds, ...capSeeds])];\n  const unknown = seeds\n    .filter((id) => !known.has(id))\n    .map((id) => ({ id, nearest: nearestIds(id, [...known]) }));\n\n  // The ring: one hop, both directions. A seed that is not modelled contributes\n  // nothing here and that is the honest answer — an invisible service has no\n  // neighbours anyone can derive, which is what `landscape.service-unmodelled`\n  // is about.\n  //\n  // The two directions are collected separately rather than written into one\n  // map as the loop goes, because a neighbour can be BOTH — it calls a seed and\n  // the seed calls it — and a single-map version answers whichever edge the\n  // parser happened to yield last. That is a field whose value depends on the\n  // order lines appear in a `.likec4` file, which is the kind of answer that\n  // reads as derived and is not.\n  const seedSet = new Set<string>(seeds);\n  const callsSeed = new Set<string>();\n  const calledBySeed = new Set<string>();\n  for (const r of relationships) {\n    const from = svcOf(r.source);\n    const to = svcOf(r.target);\n    if (seedSet.has(from) && !seedSet.has(to)) calledBySeed.add(to);\n    if (seedSet.has(to) && !seedSet.has(from)) callsSeed.add(from);\n  }\n\n  // `calls-seed` wins the overlap, deterministically. Of the two directions it\n  // is the one that more often has to be touched: a consumer depends on the\n  // seed's contract, so a change to that contract is what breaks it, while a\n  // provider the seed merely calls is usually unaffected by the seed changing.\n  const ring = new Map<string, ExploreReason>([\n    ...[...calledBySeed].map((id) => [id, \"called-by-seed\" as const] as const),\n    ...[...callsSeed].map((id) => [id, \"calls-seed\" as const] as const),\n  ]);\n\n  const ordered: Array<{ id: string; reason: ExploreReason }> = [\n    ...[...seeds].sort(compareIds).map((id) => ({ id, reason: \"seed\" as const })),\n    ...[...ring]\n      .sort(([a], [b]) => compareIds(a, b))\n      .map(([id, reason]) => ({ id, reason })),\n  ];\n\n  const services: ExploreService[] = [];\n  for (const { id, reason } of ordered) {\n    services.push(\n      await describe({\n        id,\n        reason,\n        entry: byId.get(id),\n        relationships,\n        svcOf,\n        elements,\n        parses,\n        context,\n      }),\n    );\n  }\n\n  const covered = new Set(services.map((s) => s.id));\n  const features = await context.listFeatures(docsDir);\n  const overlaps: ExploreOverlap[] = features\n    .map((f) => ({ feature: f.id, services: f.services.filter((s) => covered.has(s)) }))\n    .filter((o) => o.services.length > 0)\n    .sort((a, b) => compareIds(a.feature, b.feature));\n\n  return {\n    seeds,\n    unknown,\n    unresolvedOperations,\n    unresolvedCapabilities: unresolvedCaps,\n    services,\n    neighbours: [...ring.keys()].sort(compareIds),\n    overlaps,\n    landscape: {\n      present,\n      parses,\n      broken: land === null ? [] : brokenDocumentPaths(docsDir, land.errors),\n    },\n    scaffold: newCommand(featureId, seeds, known),\n  };\n}\n"]}