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

package/dist/commands/delta/print.js

@@ -12,6 +12,7 @@ import {} from "../../core/projection/arch-slice.js";
 import {} from "../../core/projection/events.js";
 import {} from "../../core/usecases/touch.js";
 import {} from "../../core/capabilities/delta/summary.js";
+import { droppedSentence } from "../../core/document/apply.js";
 /**
  * The requirement delta, in full.
  *
@@ -89,7 +90,7 @@ export function printEvents(events) {
     if (events.unreadable) {
         // Same wording stance as printApi above, `asyncapi.invalid` being the
         // validate finding on this file.
-        console.log("Events: asyncapi.yaml does not parse");
+        console.log("Events: asyncapi.yaml does not read as AsyncAPI 3.0");
         if (events.error !== undefined)
             console.log(`  ${events.error}`);
         console.log();
@@ -196,6 +197,21 @@ export function printCapabilities(capabilities) {
     }
     console.log();
 }
+/**
+ * What the merge would take out of the living documents, per document — the
+ * archive plan's own lines (`core/document/apply.ts`), printed BEFORE the
+ * archive, which is the only moment a reader can still put a scenario back.
+ * Silent when nothing is taken: a section that said "(none)" on every
+ * additive feature would teach the reader to skip it.
+ */
+export function printDropped(rows) {
+    if (rows.length === 0)
+        return;
+    console.log("Taken out of the living docs by the merge:");
+    for (const row of rows)
+        console.log(`  ${row.path}: ${row.kind === "REMOVED" ? "-" : "~"} ${droppedSentence(row)}`);
+    console.log();
+}
 export function indent(text, pad) {
     return text
         .split("\n")

package/dist/commands/delta/print.js.map

@@ -1 +1 @@
-{"version":3,"file":"print.js","sourceRoot":"","sources":["../../../src/commands/delta/print.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAoB,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAiB,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAkB,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAmB,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAA2B,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAA+B,MAAM,0CAA0C,CAAC;AAEvF;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAmB,EAAE,KAAa;IAClE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,YAAY,CAAC,CAAC;QAClC,OAAO;IACT,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC;QACpD,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QACvE,uEAAuE;QACvE,oEAAoE;QACpE,yEAAyE;QACzE,yDAAyD;QACzD,0DAA0D;QAC1D,6CAA6C;QAC7C,EAAE;QACF,uEAAuE;QACvE,yEAAyE;QACzE,6EAA6E;QAC7E,2EAA2E;QAC3E,0EAA0E;QAC1E,wEAAwE;QACxE,iEAAiE;QACjE,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACvD,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACzC,wEAAwE;YACxE,qEAAqE;YACrE,6DAA6D;YAC7D,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,KAAK;gBAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,CAAC,GAAG,EAAE,CAAC;IAChB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAa;IACpC,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;QACnB,oEAAoE;QACpE,uEAAuE;QACvE,yEAAyE;QACzE,+DAA+D;QAC/D,uEAAuE;QACvE,gEAAgE;QAChE,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;QAChD,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,GAAG,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,kDAAkD,CAAC,CAAC;QAChE,OAAO;IACT,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,oDAAoD,CAAC,CAAC;IAClE,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,OAAO,CAAC,GAAG,CACT,KAAK,MAAM,GAAG,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,WAAW,GAAG,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CACxG,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,GAAG,EAAE,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAkB;IAC5C,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,sEAAsE;QACtE,iCAAiC;QACjC,OAAO,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;QACpD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QACjE,OAAO,CAAC,GAAG,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,qDAAqD,CAAC,CAAC;QACnE,OAAO;IACT,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAC;IACtE,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,MAAM,SAAS,GAAG,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,GAAG,CAAC;QAC9E,OAAO,CAAC,GAAG,CAAC,KAAK,MAAM,GAAG,SAAS,GAAG,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,CAAC,GAAG,EAAE,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAe,EAAE,OAAe;IAC7D,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,GAAG,CAAC,8DAA8D,CAAC,CAAC;QAC5E,OAAO;IACT,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7B,IAAI,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,OAAO,EAAE,CAAC,CAAC;IACjE,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;QACzD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,GAAG,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;QACzD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,GAAG,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3E,OAAO,CAAC,GAAG,CAAC,6CAA6C,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,CAAC,GAAG,EAAE,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,QAA4B,EAAE,OAAe;IACzE,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;QACxB,OAAO,CAAC,GAAG,CAAC,8FAA8F,CAAC,CAAC;QAC5G,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;QACrE,OAAO,CAAC,GAAG,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IACD,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,sCAAsC,OAAO,KAAK,CAAC,CAAC;QAChE,OAAO;IACT,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,8DAA8D,CAAC,CAAC;IAC5E,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACtE,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,GAAG,CAAC;YACjE,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,OAAO,GAAG,KAAK,KAAK,IAAI,CAAC,MAAM,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,EAAE,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAA+C;IAC/E,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACtC,OAAO,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAC;IACtE,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACnE,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC;YACvF,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,OAAO,KAAK,EAAE,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,EAAE,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,GAAW;IAC9C,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SACxC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC","sourcesContent":["/**\n * The delta as a person reads it: requirements, contract changes, the\n * architecture slice for one service, and the business promises the feature\n * changes.\n *\n * Rendering only. Everything printed here comes from `../../core/projection/`\n * or `../../core/capabilities/`, which is also what `--json` emits.\n */\nimport { type Requirement } from \"../../core/document/spec.js\";\nimport { type ApiSlice } from \"../../core/projection/api.js\";\nimport { type ArchSlice } from \"../../core/projection/arch-slice.js\";\nimport { type EventSlice } from \"../../core/projection/events.js\";\nimport { type UseCaseBlastRadius } from \"../../core/usecases/touch.js\";\nimport { type CapabilityDeltaSummary } from \"../../core/capabilities/delta/summary.js\";\n\n/**\n * The requirement delta, in full.\n *\n * The text view used to print headings and scenario NAMES only, which made it a\n * table of contents for a file the reader then had to open — while `--json`\n * carried the requirement body and the Given/When/Then lines verbatim. The two\n * are the same briefing, so they carry the same content: a person reading this\n * in a terminal is being asked to implement it, exactly like the agent reading\n * the payload.\n */\nexport function printRequirements(reqs: Requirement[], label: string): void {\n  if (reqs.length === 0) {\n    console.log(`${label}: (none)\\n`);\n    return;\n  }\n  console.log(`${label}:`);\n  for (const r of reqs) {\n    const tag = r.kind === \"BASE\" ? \"\" : `[${r.kind}] `;\n    const n = r.scenarios.length;\n    console.log(`  ${tag}${r.name}  (${n} scenario${n === 1 ? \"\" : \"s\"})`);\n    // The body VERBATIM, and that is the whole of the requirement's text —\n    // `Operations:`, `Covers:`, `Publishes:`, `Consumes:`, `Requires:`,\n    // `Realizes:`, `Requirement-ID:` and `Based-On:` are body lines, kept in\n    // `text` on purpose so a requirement round-trips through\n    // `serializeRequirements` and rides inside its own digest\n    // (core/document/parse.ts states that rule).\n    //\n    // This used to print `Operations:` and `Covers:` AGAIN from the parsed\n    // fields underneath, so every requirement carrying either line showed it\n    // twice — and the other five directives, which have no such re-print, showed\n    // it once. Nothing caught it: the human view is not asserted anywhere, and\n    // the duplication is only visible on a requirement that has one. Found by\n    // running `loam delta` over loam's own self-model, which is the kind of\n    // pressure ROADMAP.md's self-hosting section says the axis buys.\n    const body = r.text.join(\"\\n\").trim();\n    if (body.length > 0) console.log(indent(body, \"    \"));\n    for (const s of r.scenarios) {\n      console.log(`\\n    Scenario: ${s.name}`);\n      // Verbatim, bullets and markdown emphasis included: these lines are the\n      // acceptance criteria, and paraphrasing them here would put a second\n      // wording of the contract in front of whoever implements it.\n      for (const line of s.lines) console.log(`      ${line}`);\n    }\n    console.log();\n  }\n}\n\nexport function printApi(api: ApiSlice): void {\n  if (api.unreadable) {\n    // Worded like `loam show`'s answer for the same failure on a living\n    // contract, and deliberately WITHOUT a \"run `loam validate`\" hint: the\n    // parser's own message is already quoted below and the exit code carries\n    // the failure, so another command adds a hop, not information.\n    // (`validate --feature` does grade `openapi.invalid` on this same file\n    // these days; the fix is still in the YAML, not in its output.)\n    console.log(\"API: openapi.yaml does not parse\");\n    if (api.error !== undefined) console.log(`  ${api.error}`);\n    console.log();\n    return;\n  }\n  if (api.changes.length === 0) {\n    console.log(\"API: (the openapi delta defines no operations)\\n\");\n    return;\n  }\n  console.log(\"API (this feature's openapi.yaml for the service):\");\n  for (const op of api.changes) {\n    const marker = op.remove ? \"REMOVE \" : \"\";\n    console.log(\n      `  ${marker}${op.method} ${op.path}  ${op.operationId}${op.summary === null ? \"\" : ` — ${op.summary}`}`,\n    );\n  }\n  console.log();\n}\n\nexport function printEvents(events: EventSlice): void {\n  if (events.unreadable) {\n    // Same wording stance as printApi above, `asyncapi.invalid` being the\n    // validate finding on this file.\n    console.log(\"Events: asyncapi.yaml does not parse\");\n    if (events.error !== undefined) console.log(`  ${events.error}`);\n    console.log();\n    return;\n  }\n  if (events.changes.length === 0) {\n    console.log(\"Events: (the asyncapi delta declares no messages)\\n\");\n    return;\n  }\n  console.log(\"Events (this feature's asyncapi.yaml for the service):\");\n  for (const m of events.changes) {\n    const marker = m.remove ? \"REMOVE \" : \"\";\n    const direction = m.direction === null ? \"\" : `${m.direction.toUpperCase()} `;\n    console.log(`  ${marker}${direction}${m.message}  (${m.slot})`);\n  }\n  console.log();\n}\n\nexport function printArchSlice(arch: ArchSlice, service: string): void {\n  if (arch.errors.length > 0) {\n    console.log(\"Architecture: delta.likec4 has errors — run `loam validate`.\");\n    return;\n  }\n  console.log(\"Architecture:\");\n  if (arch.isNew) console.log(`  NEW service — create ${service}`);\n  if (arch.outbound.length > 0) {\n    console.log(\"  Outbound (new calls from this service):\");\n    for (const e of arch.outbound) console.log(`    → ${e.service}  \"${e.title ?? \"\"}\"`);\n  }\n  if (arch.inbound.length > 0) {\n    console.log(\"  Inbound (this service is newly called):\");\n    for (const e of arch.inbound) console.log(`    ← ${e.service}  \"${e.title ?? \"\"}\"`);\n  }\n  if (!arch.isNew && arch.outbound.length === 0 && arch.inbound.length === 0) {\n    console.log(\"  (no architecture change for this service)\");\n  }\n  console.log();\n}\n\n/**\n * The business flows this service already appears in.\n *\n * Printed even when it is empty, unlike the sections above, which are skipped\n * when the feature has no such file. Those absences are facts about the FEATURE\n * — no asyncapi.yaml means this change declares no events — while this one is a\n * fact about the fleet, and \"no use case draws this service\" is the answer an\n * implementer most needs to see stated rather than inferred from a missing\n * heading.\n *\n * The unreadable arm exists so that emptiness is never ambiguous: an\n * `architecture/` that does not parse produces the same empty list as a fleet\n * that draws nothing, and only this line tells the two apart.\n */\nexport function printUseCases(useCases: UseCaseBlastRadius, service: string): void {\n  if (useCases.unreadable) {\n    console.log(\"Use cases: architecture/ does not parse, so the flows through this service could not be read\");\n    if (useCases.error !== undefined) console.log(`  ${useCases.error}`);\n    console.log();\n    return;\n  }\n  if (useCases.flows.length === 0) {\n    console.log(`Use cases: (no declared flow draws ${service})\\n`);\n    return;\n  }\n  console.log(\"Use cases (business flows this service is already a hop of):\");\n  for (const flow of useCases.flows) {\n    console.log(`  ${flow.title ?? flow.id}  [${flow.id}]  ${flow.file}`);\n    for (const step of flow.steps) {\n      const label = step.title === undefined ? \"\" : ` '${step.title}'`;\n      console.log(`    step ${step.ordinal}${label}: ${step.source} -> ${step.target}`);\n    }\n  }\n  console.log();\n}\n\n/**\n * The business promises this feature changes, and the exact `Realizes:` entry\n * each one is addressed by.\n *\n * SILENT WHEN THERE ARE NONE, unlike the use-case section above, and the\n * asymmetry is deliberate. \"No declared flow draws this service\" is an answer\n * about the FLEET — the flows exist and none of them names you — so saying so\n * is informative. A feature with no capability delta is the normal state of\n * every feature in a fleet that has not adopted the business axis, and a line\n * announcing that on every projection would be the noise that teaches people to\n * skim the brief.\n *\n * The entry is printed WHOLE (`Realizes: refunds#REF-1`) rather than as a\n * capability and an id a reader has to assemble: it is text somebody is about\n * to paste into a requirement, and the one spelling mistake it can carry —\n * the `#` — is the one nothing downstream can suggest a fix for.\n */\nexport function printCapabilities(capabilities: readonly CapabilityDeltaSummary[]): void {\n  if (capabilities.length === 0) return;\n  console.log(\"Capabilities (business promises this feature changes):\");\n  for (const c of capabilities) {\n    console.log(`  ${c.id}  +${c.added} ~${c.modified} -${c.removed}`);\n    for (const p of c.promises) {\n      const entry = p.id === null ? \"(no Requirement-ID: yet)\" : `Realizes: ${c.id}#${p.id}`;\n      console.log(`    ${p.kind} '${p.name}' — ${entry}`);\n    }\n  }\n  console.log();\n}\n\nexport function indent(text: string, pad: string): string {\n  return text\n    .split(\"\\n\")\n    .map((l) => (l.length > 0 ? pad + l : l))\n    .join(\"\\n\");\n}\n"]}
+{"version":3,"file":"print.js","sourceRoot":"","sources":["../../../src/commands/delta/print.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The delta as a person reads it: requirements, contract changes, the\n * architecture slice for one service, and the business promises the feature\n * changes.\n *\n * Rendering only. Everything printed here comes from `../../core/projection/`\n * or `../../core/capabilities/`, which is also what `--json` emits.\n */\nimport { type Requirement } from \"../../core/document/spec.js\";\nimport { type ApiSlice } from \"../../core/projection/api.js\";\nimport { type ArchSlice } from \"../../core/projection/arch-slice.js\";\nimport { type EventSlice } from \"../../core/projection/events.js\";\nimport { type UseCaseBlastRadius } from \"../../core/usecases/touch.js\";\nimport { type CapabilityDeltaSummary } from \"../../core/capabilities/delta/summary.js\";\nimport { droppedSentence, type DroppedRow } from \"../../core/document/apply.js\";\n\n/**\n * The requirement delta, in full.\n *\n * The text view used to print headings and scenario NAMES only, which made it a\n * table of contents for a file the reader then had to open — while `--json`\n * carried the requirement body and the Given/When/Then lines verbatim. The two\n * are the same briefing, so they carry the same content: a person reading this\n * in a terminal is being asked to implement it, exactly like the agent reading\n * the payload.\n */\nexport function printRequirements(reqs: Requirement[], label: string): void {\n  if (reqs.length === 0) {\n    console.log(`${label}: (none)\\n`);\n    return;\n  }\n  console.log(`${label}:`);\n  for (const r of reqs) {\n    const tag = r.kind === \"BASE\" ? \"\" : `[${r.kind}] `;\n    const n = r.scenarios.length;\n    console.log(`  ${tag}${r.name}  (${n} scenario${n === 1 ? \"\" : \"s\"})`);\n    // The body VERBATIM, and that is the whole of the requirement's text —\n    // `Operations:`, `Covers:`, `Publishes:`, `Consumes:`, `Requires:`,\n    // `Realizes:`, `Requirement-ID:` and `Based-On:` are body lines, kept in\n    // `text` on purpose so a requirement round-trips through\n    // `serializeRequirements` and rides inside its own digest\n    // (core/document/parse.ts states that rule).\n    //\n    // This used to print `Operations:` and `Covers:` AGAIN from the parsed\n    // fields underneath, so every requirement carrying either line showed it\n    // twice — and the other five directives, which have no such re-print, showed\n    // it once. Nothing caught it: the human view is not asserted anywhere, and\n    // the duplication is only visible on a requirement that has one. Found by\n    // running `loam delta` over loam's own self-model, which is the kind of\n    // pressure ROADMAP.md's self-hosting section says the axis buys.\n    const body = r.text.join(\"\\n\").trim();\n    if (body.length > 0) console.log(indent(body, \"    \"));\n    for (const s of r.scenarios) {\n      console.log(`\\n    Scenario: ${s.name}`);\n      // Verbatim, bullets and markdown emphasis included: these lines are the\n      // acceptance criteria, and paraphrasing them here would put a second\n      // wording of the contract in front of whoever implements it.\n      for (const line of s.lines) console.log(`      ${line}`);\n    }\n    console.log();\n  }\n}\n\nexport function printApi(api: ApiSlice): void {\n  if (api.unreadable) {\n    // Worded like `loam show`'s answer for the same failure on a living\n    // contract, and deliberately WITHOUT a \"run `loam validate`\" hint: the\n    // parser's own message is already quoted below and the exit code carries\n    // the failure, so another command adds a hop, not information.\n    // (`validate --feature` does grade `openapi.invalid` on this same file\n    // these days; the fix is still in the YAML, not in its output.)\n    console.log(\"API: openapi.yaml does not parse\");\n    if (api.error !== undefined) console.log(`  ${api.error}`);\n    console.log();\n    return;\n  }\n  if (api.changes.length === 0) {\n    console.log(\"API: (the openapi delta defines no operations)\\n\");\n    return;\n  }\n  console.log(\"API (this feature's openapi.yaml for the service):\");\n  for (const op of api.changes) {\n    const marker = op.remove ? \"REMOVE \" : \"\";\n    console.log(\n      `  ${marker}${op.method} ${op.path}  ${op.operationId}${op.summary === null ? \"\" : ` — ${op.summary}`}`,\n    );\n  }\n  console.log();\n}\n\nexport function printEvents(events: EventSlice): void {\n  if (events.unreadable) {\n    // Same wording stance as printApi above, `asyncapi.invalid` being the\n    // validate finding on this file.\n    console.log(\"Events: asyncapi.yaml does not read as AsyncAPI 3.0\");\n    if (events.error !== undefined) console.log(`  ${events.error}`);\n    console.log();\n    return;\n  }\n  if (events.changes.length === 0) {\n    console.log(\"Events: (the asyncapi delta declares no messages)\\n\");\n    return;\n  }\n  console.log(\"Events (this feature's asyncapi.yaml for the service):\");\n  for (const m of events.changes) {\n    const marker = m.remove ? \"REMOVE \" : \"\";\n    const direction = m.direction === null ? \"\" : `${m.direction.toUpperCase()} `;\n    console.log(`  ${marker}${direction}${m.message}  (${m.slot})`);\n  }\n  console.log();\n}\n\nexport function printArchSlice(arch: ArchSlice, service: string): void {\n  if (arch.errors.length > 0) {\n    console.log(\"Architecture: delta.likec4 has errors — run `loam validate`.\");\n    return;\n  }\n  console.log(\"Architecture:\");\n  if (arch.isNew) console.log(`  NEW service — create ${service}`);\n  if (arch.outbound.length > 0) {\n    console.log(\"  Outbound (new calls from this service):\");\n    for (const e of arch.outbound) console.log(`    → ${e.service}  \"${e.title ?? \"\"}\"`);\n  }\n  if (arch.inbound.length > 0) {\n    console.log(\"  Inbound (this service is newly called):\");\n    for (const e of arch.inbound) console.log(`    ← ${e.service}  \"${e.title ?? \"\"}\"`);\n  }\n  if (!arch.isNew && arch.outbound.length === 0 && arch.inbound.length === 0) {\n    console.log(\"  (no architecture change for this service)\");\n  }\n  console.log();\n}\n\n/**\n * The business flows this service already appears in.\n *\n * Printed even when it is empty, unlike the sections above, which are skipped\n * when the feature has no such file. Those absences are facts about the FEATURE\n * — no asyncapi.yaml means this change declares no events — while this one is a\n * fact about the fleet, and \"no use case draws this service\" is the answer an\n * implementer most needs to see stated rather than inferred from a missing\n * heading.\n *\n * The unreadable arm exists so that emptiness is never ambiguous: an\n * `architecture/` that does not parse produces the same empty list as a fleet\n * that draws nothing, and only this line tells the two apart.\n */\nexport function printUseCases(useCases: UseCaseBlastRadius, service: string): void {\n  if (useCases.unreadable) {\n    console.log(\"Use cases: architecture/ does not parse, so the flows through this service could not be read\");\n    if (useCases.error !== undefined) console.log(`  ${useCases.error}`);\n    console.log();\n    return;\n  }\n  if (useCases.flows.length === 0) {\n    console.log(`Use cases: (no declared flow draws ${service})\\n`);\n    return;\n  }\n  console.log(\"Use cases (business flows this service is already a hop of):\");\n  for (const flow of useCases.flows) {\n    console.log(`  ${flow.title ?? flow.id}  [${flow.id}]  ${flow.file}`);\n    for (const step of flow.steps) {\n      const label = step.title === undefined ? \"\" : ` '${step.title}'`;\n      console.log(`    step ${step.ordinal}${label}: ${step.source} -> ${step.target}`);\n    }\n  }\n  console.log();\n}\n\n/**\n * The business promises this feature changes, and the exact `Realizes:` entry\n * each one is addressed by.\n *\n * SILENT WHEN THERE ARE NONE, unlike the use-case section above, and the\n * asymmetry is deliberate. \"No declared flow draws this service\" is an answer\n * about the FLEET — the flows exist and none of them names you — so saying so\n * is informative. A feature with no capability delta is the normal state of\n * every feature in a fleet that has not adopted the business axis, and a line\n * announcing that on every projection would be the noise that teaches people to\n * skim the brief.\n *\n * The entry is printed WHOLE (`Realizes: refunds#REF-1`) rather than as a\n * capability and an id a reader has to assemble: it is text somebody is about\n * to paste into a requirement, and the one spelling mistake it can carry —\n * the `#` — is the one nothing downstream can suggest a fix for.\n */\nexport function printCapabilities(capabilities: readonly CapabilityDeltaSummary[]): void {\n  if (capabilities.length === 0) return;\n  console.log(\"Capabilities (business promises this feature changes):\");\n  for (const c of capabilities) {\n    console.log(`  ${c.id}  +${c.added} ~${c.modified} -${c.removed}`);\n    for (const p of c.promises) {\n      const entry = p.id === null ? \"(no Requirement-ID: yet)\" : `Realizes: ${c.id}#${p.id}`;\n      console.log(`    ${p.kind} '${p.name}' — ${entry}`);\n    }\n  }\n  console.log();\n}\n\n/**\n * What the merge would take out of the living documents, per document — the\n * archive plan's own lines (`core/document/apply.ts`), printed BEFORE the\n * archive, which is the only moment a reader can still put a scenario back.\n * Silent when nothing is taken: a section that said \"(none)\" on every\n * additive feature would teach the reader to skip it.\n */\nexport function printDropped(rows: ReadonlyArray<DroppedRow & { path: string }>): void {\n  if (rows.length === 0) return;\n  console.log(\"Taken out of the living docs by the merge:\");\n  for (const row of rows) console.log(`  ${row.path}: ${row.kind === \"REMOVED\" ? \"-\" : \"~\"} ${droppedSentence(row)}`);\n  console.log();\n}\n\nexport function indent(text: string, pad: string): string {\n  return text\n    .split(\"\\n\")\n    .map((l) => (l.length > 0 ? pad + l : l))\n    .join(\"\\n\");\n}\n"]}

package/dist/commands/dependencies.js

@@ -1,8 +1,7 @@
-import { loadConfig } from "../core/envelope/config.js";
 import { analyzeDependencies } from "../core/dependencies/dependencies.js";
 import {} from "../core/dependencies/facts.js";
 import { FleetContext } from "../core/fleet-context.js";
-import { emitJson, fail, reportNoConfig } from "../core/envelope/json.js";
+import { configOrRefuse, emitJson, fail } from "../core/envelope/json.js";
 import { missingFeatureMessage, resolveFeature } from "../core/repo/repo.js";
 export function registerDependencies(program) {
     program
@@ -12,12 +11,9 @@ export function registerDependencies(program) {
         .option("--json", "emit the machine contract instead of the human view")
         .action(async (featureArg, opts) => {
         const json = opts.json === true;
-        const loaded = await loadConfig();
-        if (loaded.kind !== "loaded") {
-            reportNoConfig(json, loaded);
+        const config = await configOrRefuse(json);
+        if (config === null)
             return;
-        }
-        const config = loaded.config;
         const context = new FleetContext();
         const feature = featureArg === undefined
             ? null

package/dist/commands/dependencies.js.map

@@ -1 +1 @@
-{"version":3,"file":"dependencies.js","sourceRoot":"","sources":["../../src/commands/dependencies.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { loadConfig } from \"../core/envelope/config.js\";\nimport { analyzeDependencies } from \"../core/dependencies/dependencies.js\";\nimport { type DependencyGraph, type DependencyReason } from \"../core/dependencies/facts.js\";\nimport { FleetContext } from \"../core/fleet-context.js\";\nimport { emitJson, fail, reportNoConfig } from \"../core/envelope/json.js\";\nimport { missingFeatureMessage, resolveFeature } from \"../core/repo/repo.js\";\n\ninterface DependenciesOptions {\n  json?: boolean;\n}\n\nexport function registerDependencies(program: Command): void {\n  program\n    .command(\"dependencies\")\n    .argument(\"[featureId]\", \"active feature id; omit for the whole in-flight graph\")\n    .description(\"Show dependencies and conflicts derived from active feature artifacts\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureArg: string | undefined, opts: DependenciesOptions) => {\n      const json = opts.json === true;\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\n\n      const context = new FleetContext();\n      const feature = featureArg === undefined\n        ? null\n        : await resolveFeature(config.docsDir, featureArg, \"exclude\", context);\n      if (featureArg !== undefined && feature === null) {\n        // The shared miss message rather than a local one: this command resolves\n        // in `exclude` mode, so the commonest miss is an id that HAS shipped, and\n        // \"no active feature\" leaves the reader to discover that themselves. The\n        // helper reuses the context already built above, so saying so costs one\n        // enumeration this invocation has already paid for.\n        fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureArg, context));\n        return;\n      }\n\n      const graph = await analyzeDependencies(config.docsDir, feature?.id, context);\n      if (json) {\n        emitJson({\n          command: \"dependencies\",\n          docsDir: config.docsDir,\n          feature: feature?.id ?? null,\n          ...graph,\n        });\n        return;\n      }\n      printGraph(graph, feature?.id);\n    });\n}\n\nfunction reasonText(reason: DependencyReason): string {\n  return reason.kind === \"operation\"\n    ? `${reason.service} operation ${reason.operationId}`\n    : `${reason.service}/${reason.axis} ${reason.identity}`;\n}\n\nfunction printGraph(graph: DependencyGraph, featureId?: string): void {\n  const scope = featureId === undefined ? \"active features\" : `${featureId} and prerequisites`;\n  console.log(`dependencies — ${scope} (${graph.nodes.length})`);\n  console.log(`  order: ${graph.order.length === 0 ? \"(none)\" : graph.order.join(\" → \")}`);\n\n  for (const node of graph.nodes) {\n    console.log(`\\n  ${node.id}${node.dependsOn.length === 0 ? \"  (independent)\" : \"\"}`);\n    for (const edge of graph.edges.filter((candidate) => candidate.from === node.id)) {\n      console.log(`    depends on ${edge.to}`);\n      for (const reason of edge.reasons) console.log(`      - ${reasonText(reason)}`);\n    }\n  }\n\n  if (graph.conflicts.length > 0) {\n    console.log(\"\\n  conflicts\");\n    for (const conflict of graph.conflicts) {\n      const where = conflict.kind === \"requirement\"\n        ? `${conflict.service}/${conflict.axis}`\n        : conflict.service;\n      // \"added by\" vs \"changed by\": the two collisions want different fixes.\n      // Two features ADDING the same identity is usually duplicated work that\n      // should become one feature; two features CHANGING it is usually genuine\n      // parallel work whose second archive would silently overwrite the first's\n      // full text, so the losers need to be re-based, not merged.\n      const how = conflict.change === \"added\" ? \"added by\" : \"changed by\";\n      console.log(`    ! ${where} ${conflict.identity} — ${how} ${conflict.features.join(\", \")}`);\n    }\n  }\n\n  if (graph.cycles.length > 0) {\n    console.log(\"\\n  cycles\");\n    for (const cycle of graph.cycles) console.log(`    ! ${cycle.join(\" ↔ \")}`);\n  }\n}\n"]}
+{"version":3,"file":"dependencies.js","sourceRoot":"","sources":["../../src/commands/dependencies.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { analyzeDependencies } from \"../core/dependencies/dependencies.js\";\nimport { type DependencyGraph, type DependencyReason } from \"../core/dependencies/facts.js\";\nimport { FleetContext } from \"../core/fleet-context.js\";\nimport { configOrRefuse, emitJson, fail } from \"../core/envelope/json.js\";\nimport { missingFeatureMessage, resolveFeature } from \"../core/repo/repo.js\";\n\ninterface DependenciesOptions {\n  json?: boolean;\n}\n\nexport function registerDependencies(program: Command): void {\n  program\n    .command(\"dependencies\")\n    .argument(\"[featureId]\", \"active feature id; omit for the whole in-flight graph\")\n    .description(\"Show dependencies and conflicts derived from active feature artifacts\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureArg: string | undefined, opts: DependenciesOptions) => {\n      const json = opts.json === true;\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n\n      const context = new FleetContext();\n      const feature = featureArg === undefined\n        ? null\n        : await resolveFeature(config.docsDir, featureArg, \"exclude\", context);\n      if (featureArg !== undefined && feature === null) {\n        // The shared miss message rather than a local one: this command resolves\n        // in `exclude` mode, so the commonest miss is an id that HAS shipped, and\n        // \"no active feature\" leaves the reader to discover that themselves. The\n        // helper reuses the context already built above, so saying so costs one\n        // enumeration this invocation has already paid for.\n        fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureArg, context));\n        return;\n      }\n\n      const graph = await analyzeDependencies(config.docsDir, feature?.id, context);\n      if (json) {\n        emitJson({\n          command: \"dependencies\",\n          docsDir: config.docsDir,\n          feature: feature?.id ?? null,\n          ...graph,\n        });\n        return;\n      }\n      printGraph(graph, feature?.id);\n    });\n}\n\nfunction reasonText(reason: DependencyReason): string {\n  return reason.kind === \"operation\"\n    ? `${reason.service} operation ${reason.operationId}`\n    : `${reason.service}/${reason.axis} ${reason.identity}`;\n}\n\nfunction printGraph(graph: DependencyGraph, featureId?: string): void {\n  const scope = featureId === undefined ? \"active features\" : `${featureId} and prerequisites`;\n  console.log(`dependencies — ${scope} (${graph.nodes.length})`);\n  console.log(`  order: ${graph.order.length === 0 ? \"(none)\" : graph.order.join(\" → \")}`);\n\n  for (const node of graph.nodes) {\n    console.log(`\\n  ${node.id}${node.dependsOn.length === 0 ? \"  (independent)\" : \"\"}`);\n    for (const edge of graph.edges.filter((candidate) => candidate.from === node.id)) {\n      console.log(`    depends on ${edge.to}`);\n      for (const reason of edge.reasons) console.log(`      - ${reasonText(reason)}`);\n    }\n  }\n\n  if (graph.conflicts.length > 0) {\n    console.log(\"\\n  conflicts\");\n    for (const conflict of graph.conflicts) {\n      const where = conflict.kind === \"requirement\"\n        ? `${conflict.service}/${conflict.axis}`\n        : conflict.service;\n      // \"added by\" vs \"changed by\": the two collisions want different fixes.\n      // Two features ADDING the same identity is usually duplicated work that\n      // should become one feature; two features CHANGING it is usually genuine\n      // parallel work whose second archive would silently overwrite the first's\n      // full text, so the losers need to be re-based, not merged.\n      const how = conflict.change === \"added\" ? \"added by\" : \"changed by\";\n      console.log(`    ! ${where} ${conflict.identity} — ${how} ${conflict.features.join(\", \")}`);\n    }\n  }\n\n  if (graph.cycles.length > 0) {\n    console.log(\"\\n  cycles\");\n    for (const cycle of graph.cycles) console.log(`    ! ${cycle.join(\" ↔ \")}`);\n  }\n}\n"]}

package/dist/commands/diff/diff.js

@@ -1,13 +1,11 @@
-import { loadConfig } from "../../core/envelope/config.js";
-import { emitJson, fail, reportNoConfig } from "../../core/envelope/json.js";
+import { configOrRefuse, emitJson, fail } from "../../core/envelope/json.js";
 import { findingJson } from "../../core/vocabulary/report.js";
-import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from "../policy/gate.js";
+import { baseOrRefuse, docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from "../policy/gate.js";
 import { DocsRepoUnavailableError } from "../../core/repo/state.js";
 import { FleetContext } from "../../core/fleet-context.js";
-import { resolveBase } from "../../core/diff/base-git.js";
 import { readBaseFleet } from "../../core/diff/base-state.js";
-import { readCurrentFleet } from "../../core/diff/current-state.js";
-import { victimIndex } from "../../core/diff/victims.js";
+import { livingFleet } from "../../core/consumers/current.js";
+import { consumerIndex } from "../../core/consumers/consumers.js";
 import { computeDiff } from "../../core/diff/semantic.js";
 import { printDiff } from "./print.js";
 export function registerDiff(program) {
@@ -18,43 +16,38 @@ export function registerDiff(program) {
         .option("--json", "emit the machine contract instead of the human view")
         .action(async (opts) => {
         const json = opts.json === true;
-        const loaded = await loadConfig();
-        if (loaded.kind !== "loaded") {
-            reportNoConfig(json, loaded);
+        const config = await configOrRefuse(json);
+        if (config === null)
             return;
-        }
-        const { docsDir } = loaded.config;
+        const { docsDir } = config;
         // "services" on purpose: both sides of the diff are enumerations of the
         // fleet, and a docsDir with no services/ has no fleet to diff.
         if (!docsRepoReady(json, docsDir, "services"))
             return;
-        const base = await resolveBase(docsDir, opts.base);
         // Unlike provenance's "git will not say", diff REFUSES when git cannot
         // answer: without the base there is no honest diff, and a silently
-        // empty base would report the whole fleet as added.
-        if (base.kind === "no-git") {
-            fail(json, "repository-unavailable", `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +
-                `loam diff reads the base state with read-only git questions (rev-parse/ls-tree/show), so it needs the docs repo ` +
-                `to be a git checkout with the base ref present. Clone the docs repo with its history, then re-run.`);
-            return;
-        }
-        if (base.kind === "no-ref") {
-            fail(json, "unknown-target", `--base ${opts.base} does not resolve to a commit in the docs repo at ${docsDir}` +
-                `${base.detail === "" ? "" : ` (${base.detail})`}. ` +
-                `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`);
+        // empty base would report the whole fleet as added. The two refusals
+        // are `loam gate --since`'s too, so they live in commands/policy/gate.ts.
+        const base = await baseOrRefuse(json, docsDir, {
+            flag: "--base",
+            ref: opts.base,
+            reads: "loam diff reads the base state",
+        });
+        if (base === null)
             return;
-        }
         const context = new FleetContext();
         let diff;
         try {
-            const baseFleet = await readBaseFleet({ docsDir, commit: base.commit, prefix: base.prefix });
+            const baseFleet = await readBaseFleet(base);
             if (baseFleet.kind === "failed") {
                 fail(json, "repository-unavailable", `git could not list services/ at ${opts.base} in the docs repo at ${docsDir} (${baseFleet.detail}) — ` +
                     `without the base tree there is no honest diff. Re-run once git can answer.`);
                 return;
             }
-            const current = await readCurrentFleet(docsDir, context);
-            const victims = victimIndex({ docsDir, context, current: current.services, ambiguous: current.ambiguous });
+            // The index reads the same memoised fleet (`livingFleet`), so the
+            // working-tree side and the victims are one read of one snapshot.
+            const current = await livingFleet(docsDir, context);
+            const victims = consumerIndex({ docsDir, context });
             diff = await computeDiff({ base: baseFleet.fleet, current, victims });
         }
         catch (err) {

package/dist/commands/diff/diff.js.map

@@ -1 +1 @@
-{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../src/commands/diff/diff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam diff --base <ref>` — the review lens over a docs-repo branch: what\n * changed in fleet-meaningful terms since a base git ref of the DOCS repo,\n * with the current consumers of every removal named. Read-only by\n * construction: the base state comes out of git's object store\n * (`core/diff/base-git.ts`), the current state off the working tree, and\n * nothing is written anywhere.\n *\n * Exit semantics: 0 when the diff was computed and nothing is breaking AND\n * every artifact on both sides could be read; 1 for a refusal, for any\n * error-severity finding (a removal the fleet still consumes — which is what\n * makes this a free gate on a docs-repo PR), and for a diff with suspended\n * axes — \"nobody could look\" must not exit as \"nothing changed\"\n * (`loam context` set that precedent for silent holes).\n */\nimport type { Command } from \"commander\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { emitJson, fail, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { findingJson } from \"../../core/vocabulary/report.js\";\nimport { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from \"../policy/gate.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { resolveBase } from \"../../core/diff/base-git.js\";\nimport { readBaseFleet } from \"../../core/diff/base-state.js\";\nimport { readCurrentFleet } from \"../../core/diff/current-state.js\";\nimport { victimIndex } from \"../../core/diff/victims.js\";\nimport { computeDiff, type FleetDiff } from \"../../core/diff/semantic.js\";\nimport { printDiff } from \"./print.js\";\n\ninterface DiffOptions {\n  base: string;\n  json?: boolean;\n}\n\nexport function registerDiff(program: Command): void {\n  program\n    .command(\"diff\")\n    .description(\"Semantic diff of the living docs against a base git ref of the docs repo — fleet-meaningful changes, with the joined victims of every removal named\")\n    .requiredOption(\"--base <ref>\", \"base git ref of the docs repo (e.g. main, origin/main, a commit sha)\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: DiffOptions) => {\n      const json = opts.json === true;\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const { docsDir } = loaded.config;\n      // \"services\" on purpose: both sides of the diff are enumerations of the\n      // fleet, and a docsDir with no services/ has no fleet to diff.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      const base = await resolveBase(docsDir, opts.base);\n      // Unlike provenance's \"git will not say\", diff REFUSES when git cannot\n      // answer: without the base there is no honest diff, and a silently\n      // empty base would report the whole fleet as added.\n      if (base.kind === \"no-git\") {\n        fail(\n          json,\n          \"repository-unavailable\",\n          `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +\n            `loam diff reads the base state with read-only git questions (rev-parse/ls-tree/show), so it needs the docs repo ` +\n            `to be a git checkout with the base ref present. Clone the docs repo with its history, then re-run.`,\n        );\n        return;\n      }\n      if (base.kind === \"no-ref\") {\n        fail(\n          json,\n          \"unknown-target\",\n          `--base ${opts.base} does not resolve to a commit in the docs repo at ${docsDir}` +\n            `${base.detail === \"\" ? \"\" : ` (${base.detail})`}. ` +\n            `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`,\n        );\n        return;\n      }\n\n      const context = new FleetContext();\n      let diff: FleetDiff;\n      try {\n        const baseFleet = await readBaseFleet({ docsDir, commit: base.commit, prefix: base.prefix });\n        if (baseFleet.kind === \"failed\") {\n          fail(\n            json,\n            \"repository-unavailable\",\n            `git could not list services/ at ${opts.base} in the docs repo at ${docsDir} (${baseFleet.detail}) — ` +\n              `without the base tree there is no honest diff. Re-run once git can answer.`,\n          );\n          return;\n        }\n        const current = await readCurrentFleet(docsDir, context);\n        const victims = victimIndex({ docsDir, context, current: current.services, ambiguous: current.ambiguous });\n        diff = await computeDiff({ base: baseFleet.fleet, current, victims });\n      } catch (err) {\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        reportRepositoryUnavailable(json, err, \"the fleet could not be diffed\", docsDir);\n        return;\n      }\n\n      // Error findings gate (the validate convention); suspended axes gate too,\n      // because an exit 0 over a diff nobody could fully read would be the\n      // \"green over zero services\" failure one step later.\n      if (diff.breaking || diff.summary.unreadable > 0) process.exitCode = 1;\n      if (json) {\n        emitJson({\n          command: \"diff\",\n          docsDir,\n          base: { ref: opts.base, commit: base.commit },\n          services: diff.services.map((s) => ({\n            id: s.id,\n            change: s.change,\n            findings: s.findings.map((finding) =>\n              findingJson(finding, { path: `services/${s.id}`, role: \"scope\" }),\n            ),\n            unreadable: s.unreadable,\n            ...(s.ambiguous === undefined ? {} : { ambiguous: s.ambiguous }),\n          })),\n          breaking: diff.breaking,\n          summary: diff.summary,\n        });\n        return;\n      }\n      printDiff(diff, { ref: opts.base, commit: base.commit });\n    });\n}\n"]}
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../src/commands/diff/diff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam diff --base <ref>` — the review lens over a docs-repo branch: what\n * changed in fleet-meaningful terms since a base git ref of the DOCS repo,\n * with the authored consumers of every removal, deprecation and contract\n * modification named. Read-only by\n * construction: the base state comes out of git's object store\n * (`core/diff/base-git.ts`), the current state off the working tree, and\n * nothing is written anywhere.\n *\n * Exit semantics: 0 when the diff was computed and nothing is breaking AND\n * every artifact on both sides could be read; 1 for a refusal, for any\n * error-severity finding (a removal the fleet still consumes — which is what\n * makes this a free gate on a docs-repo PR), and for a diff with suspended\n * axes — \"nobody could look\" must not exit as \"nothing changed\"\n * (`loam context` set that precedent for silent holes). A contract that cannot\n * be read but is byte-identical at the base is not a suspended axis: the branch\n * did not touch it, and core/diff/semantic.ts skips it rather than failing every\n * PR over a file nobody changed.\n */\nimport type { Command } from \"commander\";\nimport { configOrRefuse, emitJson, fail } from \"../../core/envelope/json.js\";\nimport { findingJson } from \"../../core/vocabulary/report.js\";\nimport { baseOrRefuse, docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from \"../policy/gate.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { readBaseFleet } from \"../../core/diff/base-state.js\";\nimport { livingFleet } from \"../../core/consumers/current.js\";\nimport { consumerIndex } from \"../../core/consumers/consumers.js\";\nimport { computeDiff, type FleetDiff } from \"../../core/diff/semantic.js\";\nimport { printDiff } from \"./print.js\";\n\ninterface DiffOptions {\n  base: string;\n  json?: boolean;\n}\n\nexport function registerDiff(program: Command): void {\n  program\n    .command(\"diff\")\n    .description(\"Semantic diff of the living docs against a base git ref of the docs repo — fleet-meaningful changes, with the joined victims of every removal named\")\n    .requiredOption(\"--base <ref>\", \"base git ref of the docs repo (e.g. main, origin/main, a commit sha)\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: DiffOptions) => {\n      const json = opts.json === true;\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const { docsDir } = config;\n      // \"services\" on purpose: both sides of the diff are enumerations of the\n      // fleet, and a docsDir with no services/ has no fleet to diff.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      // Unlike provenance's \"git will not say\", diff REFUSES when git cannot\n      // answer: without the base there is no honest diff, and a silently\n      // empty base would report the whole fleet as added. The two refusals\n      // are `loam gate --since`'s too, so they live in commands/policy/gate.ts.\n      const base = await baseOrRefuse(json, docsDir, {\n        flag: \"--base\",\n        ref: opts.base,\n        reads: \"loam diff reads the base state\",\n      });\n      if (base === null) return;\n\n      const context = new FleetContext();\n      let diff: FleetDiff;\n      try {\n        const baseFleet = await readBaseFleet(base);\n        if (baseFleet.kind === \"failed\") {\n          fail(\n            json,\n            \"repository-unavailable\",\n            `git could not list services/ at ${opts.base} in the docs repo at ${docsDir} (${baseFleet.detail}) — ` +\n              `without the base tree there is no honest diff. Re-run once git can answer.`,\n          );\n          return;\n        }\n        // The index reads the same memoised fleet (`livingFleet`), so the\n        // working-tree side and the victims are one read of one snapshot.\n        const current = await livingFleet(docsDir, context);\n        const victims = consumerIndex({ docsDir, context });\n        diff = await computeDiff({ base: baseFleet.fleet, current, victims });\n      } catch (err) {\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        reportRepositoryUnavailable(json, err, \"the fleet could not be diffed\", docsDir);\n        return;\n      }\n\n      // Error findings gate (the validate convention); suspended axes gate too,\n      // because an exit 0 over a diff nobody could fully read would be the\n      // \"green over zero services\" failure one step later.\n      if (diff.breaking || diff.summary.unreadable > 0) process.exitCode = 1;\n      if (json) {\n        emitJson({\n          command: \"diff\",\n          docsDir,\n          base: { ref: opts.base, commit: base.commit },\n          services: diff.services.map((s) => ({\n            id: s.id,\n            change: s.change,\n            findings: s.findings.map((finding) =>\n              findingJson(finding, { path: `services/${s.id}`, role: \"scope\" }),\n            ),\n            unreadable: s.unreadable,\n            ...(s.ambiguous === undefined ? {} : { ambiguous: s.ambiguous }),\n          })),\n          breaking: diff.breaking,\n          summary: diff.summary,\n        });\n        return;\n      }\n      printDiff(diff, { ref: opts.base, commit: base.commit });\n    });\n}\n"]}

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { diagnose } from "../core/doctor/doctor.js";
 import {} from "../core/doctor/report.js";
+import { REPORTS_DIR } from "../core/doctor/reports/scan.js";
 import { emitJson } from "../core/envelope/json.js";
 export function registerDoctor(program) {
     program
@@ -50,6 +51,59 @@ function writePathLabel(residue) {
     ];
     return parts.length === 0 ? "clean" : parts.join(" · ");
 }
+/**
+ * How the binding resolved, as a reader standing in the repo would say it.
+ * `unknown` alone read as "loam has never heard of this service" for one a
+ * feature in flight introduces — the service whose repository is most likely to
+ * be brand new — so that case names the feature, in the words `show` uses for
+ * the same fact. The JSON keeps `status: "unknown"` and carries `introducedBy`.
+ */
+function bindingLabel(current) {
+    const introducedBy = current.introducedBy ?? [];
+    if (introducedBy.length === 0)
+        return current.status;
+    return `introduced by ${introducedBy.join(", ")} (in flight)`;
+}
+/**
+ * The order the statuses are printed in — the lifecycle a report walks, so the
+ * row reads left to right the way the corpus drains.
+ *
+ * A `Record` over the union rather than an array of strings, because that makes
+ * tsc the thing that notices a new status: adding one to `ProblemReportStatus`
+ * fails to compile here instead of silently never being printed.
+ */
+const REPORT_STATUS_ORDER = {
+    open: 0,
+    sent: 1,
+    fixed: 2,
+    superseded: 3,
+    unstated: 4,
+};
+/**
+ * The report corpus as one line: how many there are, how they split by status,
+ * and which ordinal the next one takes.
+ *
+ * Zero counts are left out — a status nothing is in is not news, and this row
+ * is read at a glance — while the total is always there, because "twelve
+ * reports" is the fact somebody scanning for the corpus is looking for. An
+ * absent or empty directory prints `(none)` rather than a row of zeroes: a
+ * repository that has never had to write a report is the normal one.
+ */
+function reportsLabel(reports) {
+    if (!reports.present || reports.total === 0)
+        return "(none)";
+    const counted = new Map();
+    for (const entry of reports.entries) {
+        counted.set(entry.status, (counted.get(entry.status) ?? 0) + 1);
+    }
+    const split = [...counted]
+        .sort(([a], [b]) => REPORT_STATUS_ORDER[a] - REPORT_STATUS_ORDER[b])
+        .map(([status, count]) => `${status} ${count}`);
+    // The directory's NAME, not `reports.dir`: the payload spells the absolute
+    // path so an agent can act on it, while the row is read by a person standing
+    // in the repository, for whom the absolute spelling is only longer.
+    return [`${REPORTS_DIR}/ ${reports.total}`, ...split, `next ${reports.next}`].join(" · ");
+}
 function printDoctor(report) {
     console.log(`loam doctor — ${report.healthy ? "healthy" : "blocked"}`);
     console.log(`  runtime       ${report.runtime.package}@${report.runtime.version}`);
@@ -60,7 +114,7 @@ function printDoctor(report) {
     console.log(`  docsDir       ${report.docs.path ?? "(unresolved)"}`);
     console.log(`  access        exists ${yesNo(report.docs.exists)} · read ${yesNo(report.docs.readable)} · write ${yesNo(report.docs.writable)}`);
     console.log(`  fleet         services/ ${yesNo(report.docs.servicesDir)} · landscape ${yesNo(report.docs.landscape)} · ${report.counts.services} services · ${report.counts.activeFeatures} active features`);
-    console.log(`  binding       ${report.currentService.configured ?? "(none)"} · ${report.currentService.status}`);
+    console.log(`  binding       ${report.currentService.configured ?? "(none)"} · ${bindingLabel(report.currentService)}`);
     // The agent surface is reported whether or not it has drifted — like every
     // line above it, this is state, not a complaint. Only the findings block is
     // silent when there is nothing to say.
@@ -68,6 +122,11 @@ function printDoctor(report) {
     console.log(`  agents        ${agents.tools.length === 0 ? "(none)" : agents.tools.join(", ")} · ${agents.profile}`
         + ` (${agents.toolsSource}) · ${agents.plannedFiles} files · ${agents.missingFiles.length} missing`
         + ` · ${agents.staleFiles.length} stale · AGENTS.md ${stampLabel(agents.stamp)}`);
+    // The problem reports, for the same reason and with a stronger one behind it:
+    // the `loam-report` protocol asks a repository to accumulate this corpus, and
+    // until now no loam command mentioned the directory at all. Printed as state,
+    // never as a finding — an open report is not a defect in the repo holding it.
+    console.log(`  reports       ${reportsLabel(report.reports)}`);
     // The write path is state too, and its clean answer is the one worth printing
     // most often: a reader who has just been told the docs are half-written needs
     // to see it go away.

package/dist/commands/doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { diagnose } from \"../core/doctor/doctor.js\";\nimport { type DoctorReport } from \"../core/doctor/report.js\";\nimport { emitJson } from \"../core/envelope/json.js\";\n\ninterface DoctorOptions {\n  json?: boolean;\n}\n\nexport function registerDoctor(program: Command): void {\n  program\n    .command(\"doctor\")\n    .description(\"Diagnose local loam configuration and docs-repo accessibility without writing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: DoctorOptions) => {\n      const report = await diagnose();\n      if (opts.json === true) emitJson({ command: \"doctor\", ...report });\n      else printDoctor(report);\n      if (!report.healthy) process.exitCode = 1;\n    });\n}\n\nfunction yesNo(value: boolean): string {\n  return value ? \"yes\" : \"no\";\n}\n\n/**\n * The stamp as one readable token. \"absent\" and \"unstamped\" are kept apart\n * because they are different repos: the first has no AGENTS.md at all, the\n * second has one nobody has claimed a version for.\n */\nfunction stampLabel(stamp: DoctorReport[\"agents\"][\"stamp\"]): string {\n  if (!stamp.present) return \"absent\";\n  if (stamp.version === null) return \"unstamped\";\n  return `v${stamp.version}${stamp.stale ? \" (stale)\" : \"\"}`;\n}\n\n/**\n * What a killed writer left in the docs repo, as one line. \"clean\" is the\n * answer on every healthy repo, and \"(unresolved)\" keeps it apart from clean:\n * a docsDir that never resolved was never looked at.\n */\nfunction writePathLabel(residue: DoctorReport[\"writePath\"]): string {\n  if (residue === null) return \"(unresolved)\";\n  const parts = [\n    ...(residue.lock === null ? [] : [`lock held${residue.lock.stale ? \" (stale)\" : \"\"}`]),\n    ...(residue.intentUnreadable\n      ? [\"interrupted commit (unreadable)\"]\n      : residue.intent === null\n        ? []\n        : [`interrupted ${residue.intent.command} of ${\"feature\" in residue.intent ? residue.intent.feature : residue.intent.target}`]),\n    ...(residue.temps.length === 0 ? [] : [`${residue.temps.length} orphaned temp file(s)`]),\n  ];\n  return parts.length === 0 ? \"clean\" : parts.join(\" · \");\n}\n\nfunction printDoctor(report: DoctorReport): void {\n  console.log(`loam doctor — ${report.healthy ? \"healthy\" : \"blocked\"}`);\n  console.log(`  runtime       ${report.runtime.package}@${report.runtime.version}`);\n  console.log(`  node          ${report.runtime.node} ${report.runtime.platform}/${report.runtime.arch}`);\n  console.log(`  config        ${report.config.status}  ${report.config.path}`);\n  if (report.config.error !== null) console.log(`                ${report.config.error}`);\n  console.log(`  docsDir       ${report.docs.path ?? \"(unresolved)\"}`);\n  console.log(\n    `  access        exists ${yesNo(report.docs.exists)} · read ${yesNo(report.docs.readable)} · write ${yesNo(report.docs.writable)}`,\n  );\n  console.log(\n    `  fleet         services/ ${yesNo(report.docs.servicesDir)} · landscape ${yesNo(report.docs.landscape)} · ${report.counts.services} services · ${report.counts.activeFeatures} active features`,\n  );\n  console.log(\n    `  binding       ${report.currentService.configured ?? \"(none)\"} · ${report.currentService.status}`,\n  );\n  // The agent surface is reported whether or not it has drifted — like every\n  // line above it, this is state, not a complaint. Only the findings block is\n  // silent when there is nothing to say.\n  const agents = report.agents;\n  console.log(\n    `  agents        ${agents.tools.length === 0 ? \"(none)\" : agents.tools.join(\", \")} · ${agents.profile}`\n    + ` (${agents.toolsSource}) · ${agents.plannedFiles} files · ${agents.missingFiles.length} missing`\n    + ` · ${agents.staleFiles.length} stale · AGENTS.md ${stampLabel(agents.stamp)}`,\n  );\n  // The write path is state too, and its clean answer is the one worth printing\n  // most often: a reader who has just been told the docs are half-written needs\n  // to see it go away.\n  console.log(`  write path    ${writePathLabel(report.writePath)}`);\n  if (report.findings.length > 0) {\n    console.log(\"\\n  findings\");\n    for (const finding of report.findings) {\n      console.log(`    ${finding.severity === \"blocker\" ? \"✗\" : \"⚠\"} ${finding.code}: ${finding.message}`);\n      // The fix is printed on its own indented line rather than appended to the\n      // message: what is wrong and what to type are two different sentences,\n      // and someone scanning a blocked repo reads down the `fix:` column.\n      console.log(`      fix: ${finding.fix}`);\n    }\n  }\n}\n"]}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { diagnose } from \"../core/doctor/doctor.js\";\nimport { type DoctorReport, type ProblemReportStatus } from \"../core/doctor/report.js\";\nimport { REPORTS_DIR } from \"../core/doctor/reports/scan.js\";\nimport { emitJson } from \"../core/envelope/json.js\";\n\ninterface DoctorOptions {\n  json?: boolean;\n}\n\nexport function registerDoctor(program: Command): void {\n  program\n    .command(\"doctor\")\n    .description(\"Diagnose local loam configuration and docs-repo accessibility without writing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: DoctorOptions) => {\n      const report = await diagnose();\n      if (opts.json === true) emitJson({ command: \"doctor\", ...report });\n      else printDoctor(report);\n      if (!report.healthy) process.exitCode = 1;\n    });\n}\n\nfunction yesNo(value: boolean): string {\n  return value ? \"yes\" : \"no\";\n}\n\n/**\n * The stamp as one readable token. \"absent\" and \"unstamped\" are kept apart\n * because they are different repos: the first has no AGENTS.md at all, the\n * second has one nobody has claimed a version for.\n */\nfunction stampLabel(stamp: DoctorReport[\"agents\"][\"stamp\"]): string {\n  if (!stamp.present) return \"absent\";\n  if (stamp.version === null) return \"unstamped\";\n  return `v${stamp.version}${stamp.stale ? \" (stale)\" : \"\"}`;\n}\n\n/**\n * What a killed writer left in the docs repo, as one line. \"clean\" is the\n * answer on every healthy repo, and \"(unresolved)\" keeps it apart from clean:\n * a docsDir that never resolved was never looked at.\n */\nfunction writePathLabel(residue: DoctorReport[\"writePath\"]): string {\n  if (residue === null) return \"(unresolved)\";\n  const parts = [\n    ...(residue.lock === null ? [] : [`lock held${residue.lock.stale ? \" (stale)\" : \"\"}`]),\n    ...(residue.intentUnreadable\n      ? [\"interrupted commit (unreadable)\"]\n      : residue.intent === null\n        ? []\n        : [`interrupted ${residue.intent.command} of ${\"feature\" in residue.intent ? residue.intent.feature : residue.intent.target}`]),\n    ...(residue.temps.length === 0 ? [] : [`${residue.temps.length} orphaned temp file(s)`]),\n  ];\n  return parts.length === 0 ? \"clean\" : parts.join(\" · \");\n}\n\n/**\n * How the binding resolved, as a reader standing in the repo would say it.\n * `unknown` alone read as \"loam has never heard of this service\" for one a\n * feature in flight introduces — the service whose repository is most likely to\n * be brand new — so that case names the feature, in the words `show` uses for\n * the same fact. The JSON keeps `status: \"unknown\"` and carries `introducedBy`.\n */\nfunction bindingLabel(current: DoctorReport[\"currentService\"]): string {\n  const introducedBy = current.introducedBy ?? [];\n  if (introducedBy.length === 0) return current.status;\n  return `introduced by ${introducedBy.join(\", \")} (in flight)`;\n}\n\n/**\n * The order the statuses are printed in — the lifecycle a report walks, so the\n * row reads left to right the way the corpus drains.\n *\n * A `Record` over the union rather than an array of strings, because that makes\n * tsc the thing that notices a new status: adding one to `ProblemReportStatus`\n * fails to compile here instead of silently never being printed.\n */\nconst REPORT_STATUS_ORDER: Record<ProblemReportStatus, number> = {\n  open: 0,\n  sent: 1,\n  fixed: 2,\n  superseded: 3,\n  unstated: 4,\n};\n\n/**\n * The report corpus as one line: how many there are, how they split by status,\n * and which ordinal the next one takes.\n *\n * Zero counts are left out — a status nothing is in is not news, and this row\n * is read at a glance — while the total is always there, because \"twelve\n * reports\" is the fact somebody scanning for the corpus is looking for. An\n * absent or empty directory prints `(none)` rather than a row of zeroes: a\n * repository that has never had to write a report is the normal one.\n */\nfunction reportsLabel(reports: DoctorReport[\"reports\"]): string {\n  if (!reports.present || reports.total === 0) return \"(none)\";\n  const counted = new Map<ProblemReportStatus, number>();\n  for (const entry of reports.entries) {\n    counted.set(entry.status, (counted.get(entry.status) ?? 0) + 1);\n  }\n  const split = [...counted]\n    .sort(([a], [b]) => REPORT_STATUS_ORDER[a] - REPORT_STATUS_ORDER[b])\n    .map(([status, count]) => `${status} ${count}`);\n  // The directory's NAME, not `reports.dir`: the payload spells the absolute\n  // path so an agent can act on it, while the row is read by a person standing\n  // in the repository, for whom the absolute spelling is only longer.\n  return [`${REPORTS_DIR}/ ${reports.total}`, ...split, `next ${reports.next}`].join(\" · \");\n}\n\nfunction printDoctor(report: DoctorReport): void {\n  console.log(`loam doctor — ${report.healthy ? \"healthy\" : \"blocked\"}`);\n  console.log(`  runtime       ${report.runtime.package}@${report.runtime.version}`);\n  console.log(`  node          ${report.runtime.node} ${report.runtime.platform}/${report.runtime.arch}`);\n  console.log(`  config        ${report.config.status}  ${report.config.path}`);\n  if (report.config.error !== null) console.log(`                ${report.config.error}`);\n  console.log(`  docsDir       ${report.docs.path ?? \"(unresolved)\"}`);\n  console.log(\n    `  access        exists ${yesNo(report.docs.exists)} · read ${yesNo(report.docs.readable)} · write ${yesNo(report.docs.writable)}`,\n  );\n  console.log(\n    `  fleet         services/ ${yesNo(report.docs.servicesDir)} · landscape ${yesNo(report.docs.landscape)} · ${report.counts.services} services · ${report.counts.activeFeatures} active features`,\n  );\n  console.log(\n    `  binding       ${report.currentService.configured ?? \"(none)\"} · ${bindingLabel(report.currentService)}`,\n  );\n  // The agent surface is reported whether or not it has drifted — like every\n  // line above it, this is state, not a complaint. Only the findings block is\n  // silent when there is nothing to say.\n  const agents = report.agents;\n  console.log(\n    `  agents        ${agents.tools.length === 0 ? \"(none)\" : agents.tools.join(\", \")} · ${agents.profile}`\n    + ` (${agents.toolsSource}) · ${agents.plannedFiles} files · ${agents.missingFiles.length} missing`\n    + ` · ${agents.staleFiles.length} stale · AGENTS.md ${stampLabel(agents.stamp)}`,\n  );\n  // The problem reports, for the same reason and with a stronger one behind it:\n  // the `loam-report` protocol asks a repository to accumulate this corpus, and\n  // until now no loam command mentioned the directory at all. Printed as state,\n  // never as a finding — an open report is not a defect in the repo holding it.\n  console.log(`  reports       ${reportsLabel(report.reports)}`);\n  // The write path is state too, and its clean answer is the one worth printing\n  // most often: a reader who has just been told the docs are half-written needs\n  // to see it go away.\n  console.log(`  write path    ${writePathLabel(report.writePath)}`);\n  if (report.findings.length > 0) {\n    console.log(\"\\n  findings\");\n    for (const finding of report.findings) {\n      console.log(`    ${finding.severity === \"blocker\" ? \"✗\" : \"⚠\"} ${finding.code}: ${finding.message}`);\n      // The fix is printed on its own indented line rather than appended to the\n      // message: what is wrong and what to type are two different sentences,\n      // and someone scanning a blocked repo reads down the `fix:` column.\n      console.log(`      fix: ${finding.fix}`);\n    }\n  }\n}\n"]}

package/dist/commands/explain/explain.js

@@ -1,31 +1,42 @@
 import { emitJson, fail } from "../../core/envelope/json.js";
 import { LOAM_VERSION } from "../../core/envelope/version.js";
-import { explainSubject, firstSentence, knownSubjects, listCodes, listTerms, } from "../../core/explain/lookup.js";
+import { explainSubject, firstSentence, knownSubjects, listCodes, listTermGroups, listTerms, } from "../../core/explain/lookup.js";
 import { nearestIds } from "../../core/repo/entries.js";
 // Interpolated from the registry that owns the terms, never hand-listed: a
 // copied list beside TERMS is a list that silently trails it.
 const TERM_LIST = listTerms()
     .map(({ term }) => term)
     .join(", ");
-/** The listing printed when no subject is asked for — also where codes are said to come from. */
+/**
+ * The listing printed when no subject is asked for — also where codes are said to come from.
+ *
+ * The text view prints the terms under their subject headings, one column wide
+ * across every group so the summaries line up down the page; the `--json` view
+ * stays the flat `terms[]` it has always been, because a heading is for a
+ * reader scanning twenty terms and nothing a caller should branch on.
+ */
 function printTermListing(json) {
-    const terms = listTerms();
     if (json) {
+        const terms = listTerms();
         emitJson({ command: "explain", version: LOAM_VERSION, terms: terms.map(({ term, summary }) => ({ term, description: summary })) });
         return;
     }
-    console.log(`loam ${LOAM_VERSION} — the vocabulary\n`);
-    const width = Math.max(...terms.map(({ term }) => term.length));
-    for (const { term, summary } of terms)
-        console.log(`  ${term.padEnd(width)}  ${summary}`);
+    const groups = listTermGroups();
+    console.log(`loam ${LOAM_VERSION} — the vocabulary`);
+    const width = Math.max(...groups.flatMap(({ terms }) => terms.map(({ term }) => term.length)));
+    for (const { heading, terms } of groups) {
+        console.log(`\n${heading}`);
+        for (const { term, summary } of terms)
+            console.log(`  ${term.padEnd(width)}  ${summary}`);
+    }
     console.log("\nFinding codes come from `loam validate` and `loam verify` output; refusal codes arrive as error.code" +
         "\nin any --json envelope. `loam explain <subject>` explains one.");
 }
 /**
  * How much of a code's meaning the inventory shows before it stops.
  *
- * The term listing prints whole first sentences because there are six of them
- * and each is under 200 characters. The code listing prints 270-odd rows whose
+ * The term listing prints whole first sentences because there are two dozen of
+ * them, each under 200 characters. The code listing prints 270-odd rows whose
  * first sentences run to 377 characters, and a row that wraps four times is a
  * paragraph, not a line of a table — it destroys the one thing this listing is
  * for, which is scanning names. Nothing is lost: the sentence is verbatim in
@@ -71,9 +82,75 @@ function printCodeListing(json) {
     print(refusals);
     console.log("\n`loam explain <code>` prints one in full; `loam explain` with no argument lists the concept terms.");
 }
+/**
+ * The command a fix-table scope stands for, or null when the scope is a phrase.
+ *
+ * The tables label their scopes the way /loam-check's prose introduces them:
+ * `--service <id>`, `--feature <FEAT-id>` and `--all` for `loam validate`'s
+ * three modes, and a whole invocation (`loam archive`, `loam verify`, the
+ * family registry's `loam status`) for every other command. Printed as they
+ * stand, in brackets, the flag forms read as optional CLI syntax — `[--feature
+ * <FEAT-id>]` is how a usage line spells an optional flag — rather than as
+ * "this is where it was reported". So the text view says the invocation in
+ * full; the `--json` `entries[].scope` keeps the table's own label, untouched.
+ *
+ * Two /loam-check tables are introduced by a phrase instead ("frontmatter and
+ * provenance", "confirmations"); both grade inside `loam validate`, and the
+ * caller says so. test/explain.test.ts holds the premise that makes that
+ * reading safe: a scope that is neither a flag nor a `loam …` invocation comes
+ * from the /loam-check body and from nowhere else.
+ */
+function invocationOf(scope) {
+    if (scope.startsWith("--"))
+        return `loam validate ${scope}`;
+    if (scope.startsWith("loam "))
+        return scope;
+    return null;
+}
+/**
+ * One scope block's header, in words: which command reports the code there,
+ * and at what severity.
+ *
+ * `step` is the family registry's note for a `next.*` code, which no command
+ * grades — `loam status` recommends it — so that one header says it is a
+ * recommendation instead of printing "step" where a severity belongs.
+ */
+function scopeHeader(entry) {
+    const invocation = invocationOf(entry.scope);
+    const where = invocation === null ? "`loam validate`" : `\`${invocation}\``;
+    const table = invocation === null ? ` (${entry.scope})` : "";
+    if (entry.severityNote === "step")
+        return `when ${where} suggests it as a next step${table}`;
+    return `when ${where} reports it${table} — ${entry.severityNote}`;
+}
+/**
+ * The finding page's first line: what kind of code this is, and how many
+ * contexts follow.
+ *
+ * It used to be `code (error; warn) — surfaced by …`: every scope's
+ * severity joined into one parenthetical nobody could map back to a scope, and
+ * the adoption brief's `via` repeating what the first block's header already
+ * says. The severities now live on the block each one belongs to. The `via`
+ * is kept only where no block names its invocation — a /loam-check table
+ * introduced by a phrase, whose rows the brief still runs under one exact
+ * command a reader would otherwise have to guess.
+ */
+function findingHeadline(subject, finding) {
+    const { entries, via } = finding;
+    if (entries.every((entry) => entry.severityNote === "step")) {
+        return `${subject} — a next-step code: a recommendation \`loam status\` makes, not a finding`;
+    }
+    const places = entries.length > 1 ? `, reported in ${entries.length} places` : "";
+    const unnamed = via !== undefined && !entries.some((entry) => invocationOf(entry.scope) === via);
+    return `${subject} — a finding code${places}${unnamed ? `; \`${via}\` reports it` : ""}`;
+}
 function printText(subject, explanation) {
     if (explanation.kind === "term") {
-        console.log(`${explanation.term}\n\n${explanation.paragraph}`);
+        // An alias is answered by its term's entry, and the name printed on top is
+        // the term's — so a reader who asked for `partial` and got `maturity` is
+        // told that is the entry their word belongs to, not left to wonder.
+        const asked = subject.toLowerCase() === explanation.term ? "" : ` — the entry for '${subject}'`;
+        console.log(`${explanation.term}${asked}\n\n${explanation.paragraph}`);
         return;
     }
     if (explanation.kind === "refusal") {
@@ -86,10 +163,9 @@ function printText(subject, explanation) {
     // `openapi.ref-unresolved` is a warn under `--service` and an error at
     // archive plan time, and a reader asking "does this block my archive?" must
     // not have to guess which note belongs to which context.
-    const severities = [...new Set(explanation.entries.map((entry) => entry.severityNote))];
-    console.log(`${subject} (${severities.join("; ")})${explanation.via === undefined ? "" : ` — surfaced by \`${explanation.via}\``}`);
+    console.log(findingHeadline(subject, explanation));
     for (const entry of explanation.entries) {
-        console.log(`\n[${entry.scope}] (${entry.severityNote})`);
+        console.log(`\n${scopeHeader(entry)}`);
         console.log(`  what it means: ${entry.meaning}`);
         if (entry.fix !== "")
             console.log(`  what to do: ${entry.fix}`);