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

package/dist/commands/adopt/render.js

@@ -0,0 +1,309 @@
+/**
+ * The brief as a person reads it.
+ *
+ * A module of its own because the brief is the one loam output an agent is
+ * expected to FOLLOW rather than parse: `--json` carries the same eight targets,
+ * and this decides only how they read. The wrapping matters for that reason —
+ * a continuation line indented past its marker cannot be misread as a second
+ * bullet, which is what a hand-followed checklist gets wrong first.
+ */
+import { SEVERITY_MARK } from "../../core/vocabulary/report.js";
+import {} from "../../core/brief/brief.js";
+import { VIA_ALL } from "../../core/brief/checks.js";
+/* ------------------------------------------------------------------ */
+/* Text                                                                */
+/* ------------------------------------------------------------------ */
+/**
+ * `full` is the `--targets` pointer — the sentence naming the run that carries
+ * the invariant half of the brief. Its PRESENCE is what narrows this view, so
+ * the two views cannot disagree about what `--targets` means: exactly the
+ * sections `--targets` omits from `--json` are the sections skipped here.
+ * `undefined` is the default brief, unchanged byte for byte.
+ */
+export function render(b, warnings, full) {
+    console.log(`adopt ${b.service} — write the baseline into ${b.path}/\n`);
+    // In the header, before the work: a warning printed after eight artifact
+    // shapes is a warning read after the agent has started writing.
+    for (const w of warnings) {
+        console.log(wrap(`! ${w}`, "  "));
+        console.log("");
+    }
+    if (full === undefined) {
+        // First, above even the never-overwrite rule, because the rule is an
+        // instruction and this is the answer to "what am I looking at": measured on
+        // the example fleet, this view is over 650 lines and 5,600 words to an
+        // unpaged terminal, and the two rows that actually orient a person —
+        // `model.likec4 create MISSING`, `spec.md create MISSING` — land past line
+        // 450, behind four hundred lines of prose. `--json` is explicitly the agent
+        // contract, so nothing was served by leaving the human view unintroduced.
+        // `--targets` skips it — bullet three describes sections that view omits,
+        // and that view has its own pointer for the same job.
+        printOrientation(b);
+        console.log(wrap(b.rule, "  "));
+        // Before the artifact table, because the table is the output and this is the
+        // input: an agent that meets the file list first starts writing files.
+        printWalk(b);
+    }
+    console.log("\n  artifacts\n");
+    // The legend again, next to the thing it decodes. A reader who scrolls back
+    // to the table two hundred lines later arrives at four flags and no key, and
+    // the capital/lowercase distinction is invisible to anyone who has to
+    // remember it rather than read it.
+    console.log(wrap(LEGEND_LINE, "    "));
+    console.log("");
+    const width = Math.max(...b.targets.map((t) => t.artifact.length));
+    for (const t of b.targets) {
+        // `edit` is the shared fleet map: the file exists, but "present" would read
+        // as "nothing to do here", which is the opposite of why it is on the list.
+        // Two words for it, because the two states want different work: `UNDRAWN`
+        // when nothing resolves to the service, `EDGELESS` when an element does
+        // and no edge touches it — a reader acting on `UNDRAWN` there would look
+        // for a box that is already on the map.
+        const flag = t.action === "edit"
+            ? b.landscape.modelled === true
+                ? "EDGELESS"
+                : "UNDRAWN"
+            : t.partial === true
+                ? "PARTIAL"
+                : t.exists
+                    ? "present"
+                    : t.required
+                        ? "MISSING"
+                        : "missing";
+        console.log(`    ${t.artifact.padEnd(width)}  ${t.action.padEnd(6)}  ${flag.padEnd(7)}  ${t.purpose}`);
+    }
+    for (const t of b.targets)
+        printShape(t);
+    printLandscape(b);
+    if (full === undefined)
+        printChecking(b);
+    else {
+        // The pointer takes the place of the sections it stands for, in the same
+        // position they would have occupied. Anywhere else — a footnote under the
+        // closing instructions, say — and it reads as a cross-reference rather
+        // than as the notice that this brief is not all of the brief.
+        console.log("\n  the rest of the brief\n");
+        console.log(wrap(full, "    "));
+    }
+    console.log("\n  when you are done\n");
+    console.log(`    loam validate --service ${b.service} --json    # fix every error`);
+    // The fleet run is not a nicety: --service never reports the landscape
+    // cross-check, so a baseline can pass the line above with the fleet map
+    // never edited at all.
+    console.log(`    loam validate --all --json                        # in the docs repo: the fleet map`);
+    console.log(`    loam vouch --service ${b.service}              # a HUMAN, in the service's own repo`);
+    console.log("");
+    console.log(wrap("Leave everything `status: draft`. Vouching is somebody reading the code and saying the document matches it — it is not yours to do, and a status with no digest behind it is a claim with nothing behind it.", "    "));
+}
+/** The table's five flags, compressed to one terminal line for the scroll-back reader. */
+const LEGEND_LINE = "MISSING required · missing optional · present diff it · PARTIAL one feature's slice, adopt around it · UNDRAWN add to the map · EDGELESS an element exists, no edge does";
+/**
+ * A required target whose work is still outstanding.
+ *
+ * `!t.exists` alone is the wrong test, and the fleet map is the reason: for
+ * every repo after its first service `architecture/landscape.likec4` already
+ * exists, so `exists` is true while nothing in it resolves to this boundary —
+ * which `loam validate --all` grades `landscape.service-unmodelled`, an ERROR.
+ * `action` carries that distinction and nothing else does: `edit` is only ever
+ * the fleet map still owed — undrawn, or drawn with no edge touching it (see
+ * `BriefTarget.action`, core/brief/targets.ts).
+ */
+function outstanding(t) {
+    return t.required && (!t.exists || t.action === "edit" || t.partial === true);
+}
+/**
+ * The three sentences that make the rest of the page readable: how much of it
+ * is owed, what the table's own convention means, and what the four hundred
+ * lines below it are.
+ *
+ * Every number here is computed from the brief that was just assembled — the
+ * outstanding count off `targets`, the section sizes off `walk`, `checks` and
+ * `unchecked`. A literal would be right until the next check is added and
+ * silently wrong forever after, and this block's whole value is that a reader
+ * can trust it instead of scrolling to verify it.
+ */
+function printOrientation(b) {
+    const owed = b.targets.filter(outstanding);
+    console.log("  read this first\n");
+    // What is actually owed, named. The count is the load-bearing half: "some of
+    // these are required" is a sentence a reader skips, "three of the nine, and
+    // here they are" is one they act on.
+    console.log(bullet(owed.length === 0
+        ? `None of the ${String(b.targets.length)} artifacts below is both required and outstanding — every required one is already there. What is left is optional, or an existing document to diff your findings against.`
+        : `${String(owed.length)} of the ${String(b.targets.length)} artifacts below ${owed.length === 1 ? "is" : "are"} required and not yet done: ${owed.map((t) => t.artifact).join(", ")}. Everything else in the table is optional, or already written and wants diffing rather than replacing.`, "    "));
+    console.log("");
+    // The legend, in full. The table prints `MISSING` and `missing` as if the
+    // capitals were emphasis; they are the required/optional distinction, and
+    // nothing on the page said so. `UNDRAWN` needs more than a gloss — it is the
+    // one row that is not this boundary's file at all.
+    console.log(bullet("The flags in that table: `MISSING` in capitals is required and not there, lowercase `missing` is optional and not there, `present` means the file exists — diff it, never replace it. `PARTIAL` is a spec.md marked `adoption: partial`: one archived feature's slice, so keep every requirement in it, write the rest of the service around them, and then delete the `adoption: partial` line. `UNDRAWN` and `EDGELESS` mark the one row that is not this boundary's own file: `architecture/landscape.likec4` is the whole system's map and already holds every other boundary, so ADD to it rather than rewriting it. Until an element in it resolves to this directory, `loam validate --all` reports `landscape.service-unmodelled` (error); `EDGELESS` means an element already does and no edge touches it, so what the map lacks is the calls in and out of it, never a second element.", "    "));
+    console.log("");
+    // What the rest of the page is, so a reader who stops here still knows what
+    // they scrolled past — and where the same content lives for an agent, which
+    // is the reader this long body was written for.
+    console.log(bullet(`The rest of this page, in order: the ${String(b.walk.length)}-stop order to read the code in, then the grammar of each artifact — every rule there is one a later check depends on — then the ${String(b.checks.length)} named checks the result will face and the ${String(b.unchecked.length)} statements of what nothing checks. \`loam adopt --service ${b.service} --json\` carries the same targets for an agent, and \`--targets\` narrows that to only the part that varies by boundary.`, "    "));
+    console.log("");
+}
+/**
+ * The invariant half: the frontmatter rules, the checks that run, and the
+ * checks that do not exist. A function of its own only so `--targets` can skip
+ * all three in one place — the three sections are the exact set `--targets`
+ * omits from `--json`, and splitting them here is what keeps that a single
+ * decision instead of three that can drift apart.
+ */
+function printChecking(b) {
+    console.log("\n  frontmatter — on every markdown artifact\n");
+    for (const [field, what] of Object.entries(b.frontmatter.fields)) {
+        console.log(`    ${field}`);
+        console.log(wrap(what, "      "));
+    }
+    console.log(`\n    never write by hand: ${b.frontmatter.never.join(", ")}`);
+    console.log(`\n${wrap(b.frontmatter.why, "    ")}`);
+    // Attribution matters here: the fleet cross-check runs under `--all`, and a
+    // header promising it to `--service` sent agents chasing a finding that
+    // invocation never reports.
+    console.log(`\n  what \`loam validate --service ${b.service}\` then checks\n`);
+    for (const c of b.checks) {
+        if (c.via !== VIA_ALL)
+            printCheck(c);
+    }
+    console.log(`\n  and what only \`loam validate --all\` surfaces\n`);
+    for (const c of b.checks) {
+        if (c.via === VIA_ALL)
+            printCheck(c);
+    }
+    console.log("\n  what nothing checks\n");
+    for (const u of b.unchecked)
+        console.log(bullet(u, "    "));
+}
+/**
+ * The walk, numbered. The numbers are the point: an unordered list of nine
+ * places to look reads as nine optional suggestions, and the two stops that fix
+ * what the service IS have to happen before the surfaces are enumerated.
+ */
+function printWalk(b) {
+    console.log("\n  read the code in this order — nothing below is written from anything else\n");
+    for (const [i, stop] of b.walk.entries()) {
+        // The hang is explicit rather than derived: `wrap` infers one from a leading
+        // `- `, and a numbered stop whose second line starts at the number's own
+        // column reads as the next stop — which for a list whose ORDER is the point
+        // is the one misreading that costs something.
+        console.log(wrap(`${String(i + 1)}. ${stop.where}`, "    ", 88, "       "));
+        // Two more columns than the stop it belongs to: where-to-look and
+        // what-to-take are different sentences, and at one indent the second reads
+        // as a continuation of the first.
+        console.log(wrap(stop.find, "         "));
+        console.log(`         → ${stop.lands.join(", ")}`);
+        console.log("");
+    }
+    console.log(wrap(b.walkClose, "    "));
+}
+function printCheck(c) {
+    console.log(`    ${SEVERITY_MARK[c.severity]} ${c.code}`);
+    console.log(wrap(c.what, "        "));
+}
+const ACTION_NOTE = {
+    create: "",
+    diff: "   (exists — diff, do not replace)",
+    edit: "   (the whole fleet's file — ADD to it, never rewrite it)",
+};
+function printShape(t) {
+    console.log(`\n  ${t.path}${ACTION_NOTE[t.action]}\n`);
+    for (const rule of t.shape)
+        console.log(bullet(rule, "    "));
+    if (t.example === undefined)
+        return;
+    console.log("");
+    for (const line of t.example.trimEnd().split("\n"))
+        console.log(`      ${line}`.trimEnd());
+}
+function printLandscape(b) {
+    const l = b.landscape;
+    console.log("\n  what the fleet already says about this service\n");
+    // The instruction is the same sentence the JSON carries, printed from the
+    // same field — the text view and `--json` cannot drift into briefing two
+    // different writes.
+    if (!l.present) {
+        console.log("    architecture/landscape.likec4 does not exist yet — nothing to bind to.");
+        console.log("");
+        console.log(wrap(l.instruction ?? "", "    "));
+        return;
+    }
+    if (!l.parses) {
+        // Not "architecture/landscape.likec4 does not parse": the map is the whole
+        // `architecture/` project, so the file that broke is usually a sibling —
+        // and this line accused the landscape of errors `validate --all` blamed on
+        // a palette. The instruction printed directly below names the documents
+        // that actually failed, so the headline says the project and nothing more.
+        console.log("    The fleet map (architecture/) does not parse — fix that first; the files are named below.");
+        console.log("");
+        console.log(wrap(l.instruction ?? "", "    "));
+        printExpects(l);
+        return;
+    }
+    if (l.elements.length === 0) {
+        console.log(`    Nothing in the landscape models '${b.service}'.`);
+        console.log("");
+        console.log(wrap(l.instruction ?? "", "    "));
+        return;
+    }
+    for (const e of l.elements) {
+        const bound = e.bound ? "bound" : "matched by title — bind it";
+        console.log(`    ${e.id} = ${e.kind} '${e.title}'   (${bound})`);
+    }
+    for (const e of l.inbound)
+        console.log(`    ← ${e.from}  ${e.op ?? `"${e.title ?? ""}"`}`);
+    for (const e of l.outbound)
+        console.log(`    → ${e.to}  ${e.op ?? `"${e.title ?? ""}"`}`);
+    // The edgeless state: an element and no edge lines above it. The modelled
+    // branch used to return here without ever printing an instruction, which
+    // is how the text view briefed "the map owes nothing" over two empty lists.
+    if (l.instruction !== null) {
+        console.log("");
+        console.log(wrap(l.instruction, "    "));
+    }
+    printExpects(l);
+}
+/**
+ * What the fleet already calls on this service, and why the contract owes it.
+ *
+ * Printed in the unparseable branch as well as the healthy one: the landscape
+ * FILE still answers who calls this service when a sibling under `architecture/`
+ * breaks the project, and it is what decides whether `openapi.yaml` is flagged
+ * required — so a reader who is told the map is unreadable still gets the
+ * evidence behind that row.
+ */
+function printExpects(l) {
+    if (l.expects.length === 0)
+        return;
+    const it = l.expects.length === 1 ? "it" : "them";
+    console.log("");
+    console.log(wrap(`openapi.yaml must define ${l.expects.map((o) => `'${o}'`).join(", ")} — the fleet already calls ${it}, and a contract that omits ${it} fails spine.op-undefined the moment it lands.`, "    "));
+}
+/**
+ * Wrap prose so the brief is readable in a terminal. Continuation lines are
+ * indented past the marker, so a wrapped bullet cannot be misread as two.
+ */
+function wrap(text, indent, width = 88, hangIndent) {
+    const hang = hangIndent ?? (/^\s*-\s/.test(text) ? `${indent}  ` : indent);
+    const out = [];
+    let line = indent;
+    let pad = indent;
+    for (const word of text.trim().split(/\s+/)) {
+        if (line.length > pad.length && line.length + 1 + word.length > width) {
+            out.push(line);
+            pad = hang;
+            line = hang + word;
+        }
+        else {
+            line = line.length > pad.length ? `${line} ${word}` : line + word;
+        }
+    }
+    out.push(line);
+    return out.join("\n");
+}
+/** A bullet, wrapped with its continuation lines hanging under the text. */
+function bullet(text, indent) {
+    return wrap(`- ${text}`, indent);
+}
+//# sourceMappingURL=render.js.map

package/dist/commands/adopt/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/commands/adopt/render.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The brief as a person reads it.\n *\n * A module of its own because the brief is the one loam output an agent is\n * expected to FOLLOW rather than parse: `--json` carries the same eight targets,\n * and this decides only how they read. The wrapping matters for that reason —\n * a continuation line indented past its marker cannot be misread as a second\n * bullet, which is what a hand-followed checklist gets wrong first.\n */\nimport { SEVERITY_MARK } from \"../../core/vocabulary/report.js\";\nimport { type Brief } from \"../../core/brief/brief.js\";\nimport { VIA_ALL, type BriefCheck } from \"../../core/brief/checks.js\";\nimport type { BriefTarget } from \"../../core/brief/targets.js\";\n\n/* ------------------------------------------------------------------ */\n/* Text                                                                */\n/* ------------------------------------------------------------------ */\n\n/**\n * `full` is the `--targets` pointer — the sentence naming the run that carries\n * the invariant half of the brief. Its PRESENCE is what narrows this view, so\n * the two views cannot disagree about what `--targets` means: exactly the\n * sections `--targets` omits from `--json` are the sections skipped here.\n * `undefined` is the default brief, unchanged byte for byte.\n */\nexport function render(b: Brief, warnings: string[], full?: string): void {\n  console.log(`adopt ${b.service} — write the baseline into ${b.path}/\\n`);\n  // In the header, before the work: a warning printed after eight artifact\n  // shapes is a warning read after the agent has started writing.\n  for (const w of warnings) {\n    console.log(wrap(`! ${w}`, \"  \"));\n    console.log(\"\");\n  }\n  if (full === undefined) {\n    // First, above even the never-overwrite rule, because the rule is an\n    // instruction and this is the answer to \"what am I looking at\": measured on\n    // the example fleet, this view is over 650 lines and 5,600 words to an\n    // unpaged terminal, and the two rows that actually orient a person —\n    // `model.likec4 create MISSING`, `spec.md create MISSING` — land past line\n    // 450, behind four hundred lines of prose. `--json` is explicitly the agent\n    // contract, so nothing was served by leaving the human view unintroduced.\n    // `--targets` skips it — bullet three describes sections that view omits,\n    // and that view has its own pointer for the same job.\n    printOrientation(b);\n    console.log(wrap(b.rule, \"  \"));\n\n    // Before the artifact table, because the table is the output and this is the\n    // input: an agent that meets the file list first starts writing files.\n    printWalk(b);\n  }\n\n  console.log(\"\\n  artifacts\\n\");\n  // The legend again, next to the thing it decodes. A reader who scrolls back\n  // to the table two hundred lines later arrives at four flags and no key, and\n  // the capital/lowercase distinction is invisible to anyone who has to\n  // remember it rather than read it.\n  console.log(wrap(LEGEND_LINE, \"    \"));\n  console.log(\"\");\n  const width = Math.max(...b.targets.map((t) => t.artifact.length));\n  for (const t of b.targets) {\n    // `edit` is the shared fleet map: the file exists, but \"present\" would read\n    // as \"nothing to do here\", which is the opposite of why it is on the list.\n    // Two words for it, because the two states want different work: `UNDRAWN`\n    // when nothing resolves to the service, `EDGELESS` when an element does\n    // and no edge touches it — a reader acting on `UNDRAWN` there would look\n    // for a box that is already on the map.\n    const flag =\n      t.action === \"edit\"\n        ? b.landscape.modelled === true\n          ? \"EDGELESS\"\n          : \"UNDRAWN\"\n        : t.partial === true\n          ? \"PARTIAL\"\n          : t.exists\n            ? \"present\"\n            : t.required\n              ? \"MISSING\"\n              : \"missing\";\n    console.log(`    ${t.artifact.padEnd(width)}  ${t.action.padEnd(6)}  ${flag.padEnd(7)}  ${t.purpose}`);\n  }\n\n  for (const t of b.targets) printShape(t);\n\n  printLandscape(b);\n\n  if (full === undefined) printChecking(b);\n  else {\n    // The pointer takes the place of the sections it stands for, in the same\n    // position they would have occupied. Anywhere else — a footnote under the\n    // closing instructions, say — and it reads as a cross-reference rather\n    // than as the notice that this brief is not all of the brief.\n    console.log(\"\\n  the rest of the brief\\n\");\n    console.log(wrap(full, \"    \"));\n  }\n\n  console.log(\"\\n  when you are done\\n\");\n  console.log(`    loam validate --service ${b.service} --json    # fix every error`);\n  // The fleet run is not a nicety: --service never reports the landscape\n  // cross-check, so a baseline can pass the line above with the fleet map\n  // never edited at all.\n  console.log(`    loam validate --all --json                        # in the docs repo: the fleet map`);\n  console.log(`    loam vouch --service ${b.service}              # a HUMAN, in the service's own repo`);\n  console.log(\"\");\n  console.log(\n    wrap(\n      \"Leave everything `status: draft`. Vouching is somebody reading the code and saying the document matches it — it is not yours to do, and a status with no digest behind it is a claim with nothing behind it.\",\n      \"    \",\n    ),\n  );\n}\n\n/** The table's five flags, compressed to one terminal line for the scroll-back reader. */\nconst LEGEND_LINE =\n  \"MISSING required · missing optional · present diff it · PARTIAL one feature's slice, adopt around it · UNDRAWN add to the map · EDGELESS an element exists, no edge does\";\n\n/**\n * A required target whose work is still outstanding.\n *\n * `!t.exists` alone is the wrong test, and the fleet map is the reason: for\n * every repo after its first service `architecture/landscape.likec4` already\n * exists, so `exists` is true while nothing in it resolves to this boundary —\n * which `loam validate --all` grades `landscape.service-unmodelled`, an ERROR.\n * `action` carries that distinction and nothing else does: `edit` is only ever\n * the fleet map still owed — undrawn, or drawn with no edge touching it (see\n * `BriefTarget.action`, core/brief/targets.ts).\n */\nfunction outstanding(t: BriefTarget): boolean {\n  return t.required && (!t.exists || t.action === \"edit\" || t.partial === true);\n}\n\n/**\n * The three sentences that make the rest of the page readable: how much of it\n * is owed, what the table's own convention means, and what the four hundred\n * lines below it are.\n *\n * Every number here is computed from the brief that was just assembled — the\n * outstanding count off `targets`, the section sizes off `walk`, `checks` and\n * `unchecked`. A literal would be right until the next check is added and\n * silently wrong forever after, and this block's whole value is that a reader\n * can trust it instead of scrolling to verify it.\n */\nfunction printOrientation(b: Brief): void {\n  const owed = b.targets.filter(outstanding);\n  console.log(\"  read this first\\n\");\n\n  // What is actually owed, named. The count is the load-bearing half: \"some of\n  // these are required\" is a sentence a reader skips, \"three of the nine, and\n  // here they are\" is one they act on.\n  console.log(\n    bullet(\n      owed.length === 0\n        ? `None of the ${String(b.targets.length)} artifacts below is both required and outstanding — every required one is already there. What is left is optional, or an existing document to diff your findings against.`\n        : `${String(owed.length)} of the ${String(b.targets.length)} artifacts below ${owed.length === 1 ? \"is\" : \"are\"} required and not yet done: ${owed.map((t) => t.artifact).join(\", \")}. Everything else in the table is optional, or already written and wants diffing rather than replacing.`,\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n\n  // The legend, in full. The table prints `MISSING` and `missing` as if the\n  // capitals were emphasis; they are the required/optional distinction, and\n  // nothing on the page said so. `UNDRAWN` needs more than a gloss — it is the\n  // one row that is not this boundary's file at all.\n  console.log(\n    bullet(\n      \"The flags in that table: `MISSING` in capitals is required and not there, lowercase `missing` is optional and not there, `present` means the file exists — diff it, never replace it. `PARTIAL` is a spec.md marked `adoption: partial`: one archived feature's slice, so keep every requirement in it, write the rest of the service around them, and then delete the `adoption: partial` line. `UNDRAWN` and `EDGELESS` mark the one row that is not this boundary's own file: `architecture/landscape.likec4` is the whole system's map and already holds every other boundary, so ADD to it rather than rewriting it. Until an element in it resolves to this directory, `loam validate --all` reports `landscape.service-unmodelled` (error); `EDGELESS` means an element already does and no edge touches it, so what the map lacks is the calls in and out of it, never a second element.\",\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n\n  // What the rest of the page is, so a reader who stops here still knows what\n  // they scrolled past — and where the same content lives for an agent, which\n  // is the reader this long body was written for.\n  console.log(\n    bullet(\n      `The rest of this page, in order: the ${String(b.walk.length)}-stop order to read the code in, then the grammar of each artifact — every rule there is one a later check depends on — then the ${String(b.checks.length)} named checks the result will face and the ${String(b.unchecked.length)} statements of what nothing checks. \\`loam adopt --service ${b.service} --json\\` carries the same targets for an agent, and \\`--targets\\` narrows that to only the part that varies by boundary.`,\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n}\n\n/**\n * The invariant half: the frontmatter rules, the checks that run, and the\n * checks that do not exist. A function of its own only so `--targets` can skip\n * all three in one place — the three sections are the exact set `--targets`\n * omits from `--json`, and splitting them here is what keeps that a single\n * decision instead of three that can drift apart.\n */\nfunction printChecking(b: Brief): void {\n  console.log(\"\\n  frontmatter — on every markdown artifact\\n\");\n  for (const [field, what] of Object.entries(b.frontmatter.fields)) {\n    console.log(`    ${field}`);\n    console.log(wrap(what, \"      \"));\n  }\n  console.log(`\\n    never write by hand: ${b.frontmatter.never.join(\", \")}`);\n  console.log(`\\n${wrap(b.frontmatter.why, \"    \")}`);\n\n  // Attribution matters here: the fleet cross-check runs under `--all`, and a\n  // header promising it to `--service` sent agents chasing a finding that\n  // invocation never reports.\n  console.log(`\\n  what \\`loam validate --service ${b.service}\\` then checks\\n`);\n  for (const c of b.checks) {\n    if (c.via !== VIA_ALL) printCheck(c);\n  }\n  console.log(`\\n  and what only \\`loam validate --all\\` surfaces\\n`);\n  for (const c of b.checks) {\n    if (c.via === VIA_ALL) printCheck(c);\n  }\n\n  console.log(\"\\n  what nothing checks\\n\");\n  for (const u of b.unchecked) console.log(bullet(u, \"    \"));\n}\n\n/**\n * The walk, numbered. The numbers are the point: an unordered list of nine\n * places to look reads as nine optional suggestions, and the two stops that fix\n * what the service IS have to happen before the surfaces are enumerated.\n */\nfunction printWalk(b: Brief): void {\n  console.log(\"\\n  read the code in this order — nothing below is written from anything else\\n\");\n  for (const [i, stop] of b.walk.entries()) {\n    // The hang is explicit rather than derived: `wrap` infers one from a leading\n    // `- `, and a numbered stop whose second line starts at the number's own\n    // column reads as the next stop — which for a list whose ORDER is the point\n    // is the one misreading that costs something.\n    console.log(wrap(`${String(i + 1)}. ${stop.where}`, \"    \", 88, \"       \"));\n    // Two more columns than the stop it belongs to: where-to-look and\n    // what-to-take are different sentences, and at one indent the second reads\n    // as a continuation of the first.\n    console.log(wrap(stop.find, \"         \"));\n    console.log(`         → ${stop.lands.join(\", \")}`);\n    console.log(\"\");\n  }\n  console.log(wrap(b.walkClose, \"    \"));\n}\n\nfunction printCheck(c: BriefCheck): void {\n  console.log(`    ${SEVERITY_MARK[c.severity]} ${c.code}`);\n  console.log(wrap(c.what, \"        \"));\n}\n\nconst ACTION_NOTE: Record<BriefTarget[\"action\"], string> = {\n  create: \"\",\n  diff: \"   (exists — diff, do not replace)\",\n  edit: \"   (the whole fleet's file — ADD to it, never rewrite it)\",\n};\n\nfunction printShape(t: BriefTarget): void {\n  console.log(`\\n  ${t.path}${ACTION_NOTE[t.action]}\\n`);\n  for (const rule of t.shape) console.log(bullet(rule, \"    \"));\n  if (t.example === undefined) return;\n  console.log(\"\");\n  for (const line of t.example.trimEnd().split(\"\\n\")) console.log(`      ${line}`.trimEnd());\n}\n\nfunction printLandscape(b: Brief): void {\n  const l = b.landscape;\n  console.log(\"\\n  what the fleet already says about this service\\n\");\n  // The instruction is the same sentence the JSON carries, printed from the\n  // same field — the text view and `--json` cannot drift into briefing two\n  // different writes.\n  if (!l.present) {\n    console.log(\"    architecture/landscape.likec4 does not exist yet — nothing to bind to.\");\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  if (!l.parses) {\n    // Not \"architecture/landscape.likec4 does not parse\": the map is the whole\n    // `architecture/` project, so the file that broke is usually a sibling —\n    // and this line accused the landscape of errors `validate --all` blamed on\n    // a palette. The instruction printed directly below names the documents\n    // that actually failed, so the headline says the project and nothing more.\n    console.log(\"    The fleet map (architecture/) does not parse — fix that first; the files are named below.\");\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    printExpects(l);\n    return;\n  }\n  if (l.elements.length === 0) {\n    console.log(`    Nothing in the landscape models '${b.service}'.`);\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  for (const e of l.elements) {\n    const bound = e.bound ? \"bound\" : \"matched by title — bind it\";\n    console.log(`    ${e.id} = ${e.kind} '${e.title}'   (${bound})`);\n  }\n  for (const e of l.inbound) console.log(`    ← ${e.from}  ${e.op ?? `\"${e.title ?? \"\"}\"`}`);\n  for (const e of l.outbound) console.log(`    → ${e.to}  ${e.op ?? `\"${e.title ?? \"\"}\"`}`);\n  // The edgeless state: an element and no edge lines above it. The modelled\n  // branch used to return here without ever printing an instruction, which\n  // is how the text view briefed \"the map owes nothing\" over two empty lists.\n  if (l.instruction !== null) {\n    console.log(\"\");\n    console.log(wrap(l.instruction, \"    \"));\n  }\n  printExpects(l);\n}\n\n/**\n * What the fleet already calls on this service, and why the contract owes it.\n *\n * Printed in the unparseable branch as well as the healthy one: the landscape\n * FILE still answers who calls this service when a sibling under `architecture/`\n * breaks the project, and it is what decides whether `openapi.yaml` is flagged\n * required — so a reader who is told the map is unreadable still gets the\n * evidence behind that row.\n */\nfunction printExpects(l: Brief[\"landscape\"]): void {\n  if (l.expects.length === 0) return;\n  const it = l.expects.length === 1 ? \"it\" : \"them\";\n  console.log(\"\");\n  console.log(\n    wrap(\n      `openapi.yaml must define ${l.expects.map((o) => `'${o}'`).join(\", \")} — the fleet already calls ${it}, and a contract that omits ${it} fails spine.op-undefined the moment it lands.`,\n      \"    \",\n    ),\n  );\n}\n\n/**\n * Wrap prose so the brief is readable in a terminal. Continuation lines are\n * indented past the marker, so a wrapped bullet cannot be misread as two.\n */\nfunction wrap(text: string, indent: string, width = 88, hangIndent?: string): string {\n  const hang = hangIndent ?? (/^\\s*-\\s/.test(text) ? `${indent}  ` : indent);\n  const out: string[] = [];\n  let line = indent;\n  let pad = indent;\n  for (const word of text.trim().split(/\\s+/)) {\n    if (line.length > pad.length && line.length + 1 + word.length > width) {\n      out.push(line);\n      pad = hang;\n      line = hang + word;\n    } else {\n      line = line.length > pad.length ? `${line} ${word}` : line + word;\n    }\n  }\n  out.push(line);\n  return out.join(\"\\n\");\n}\n\n/** A bullet, wrapped with its continuation lines hanging under the text. */\nfunction bullet(text: string, indent: string): string {\n  return wrap(`- ${text}`, indent);\n}\n"]}

package/dist/commands/archive/archive.js

@@ -0,0 +1,74 @@
+import { CodedFailure, configOrRefuse, fail } from "../../core/envelope/json.js";
+import { message } from "../../core/staging/commit.js";
+import { acquireDocsLock, DocsBusyError } from "../../core/staging/lock.js";
+import {} from "./plan/refusal.js";
+import { archiveLocked } from "./run.js";
+import { LandscapeSpliceError } from "../../core/c4/splice/contract.js";
+import { NotUtf8Error } from "../../core/staging/writes.js";
+import { OpenapiMergeError } from "../../core/openapi/merge/error.js";
+import { InterruptedCommitError } from "../../core/staging/interrupted.js";
+/**
+ * The code a failed archive answers with. A `CodedFailure` is thrown from the
+ * plan phase (nothing written yet) and from the commit's rollback path (whose
+ * message says whether the rollback held). Anything that escapes runArchive and
+ * matches no arm below is a bug, and reports as `internal`.
+ */
+function archiveErrorCode(err) {
+    if (err instanceof CodedFailure)
+        return err.code;
+    // Another writer holds the docs repo — the lock is taken refuse-fast below.
+    if (err instanceof DocsBusyError)
+        return "docs-busy";
+    // Every splice refusal is the mechanical merge answer — see the class.
+    if (err instanceof LandscapeSpliceError)
+        return "merge-failed";
+    if (err instanceof NotUtf8Error)
+        return "merge-failed";
+    // The merge branch wraps its own call and re-throws as merge-failed; the
+    // create branch (`stripOpenapiRemovalMarkers`) does not, so one unreadable
+    // feature contract answered merge-failed or `internal` depending on whether
+    // the service already had a living openapi.yaml. The code answers "can I
+    // trust the repo?", and that answer does not turn on which side of the merge
+    // the document sat on.
+    if (err instanceof OpenapiMergeError)
+        return "merge-failed";
+    if (err instanceof InterruptedCommitError)
+        return "commit-interrupted";
+    return "internal";
+}
+export function registerArchive(program) {
+    program
+        .command("archive")
+        .argument("<featureId>", "feature id, e.g. FEAT-101")
+        .description("Merge a finished feature's deltas into the living specs + model, then archive it (checks the documents, not the code)")
+        .option("--approve", "archive despite GATING coherence issues (may corrupt the living docs); advisory warnings never block")
+        .option("--dry-run", "print the whole merge plan and write nothing")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (featureId, opts) => {
+        const json = opts.json === true;
+        try {
+            await runArchive(featureId, opts);
+        }
+        catch (err) {
+            // Plan-phase failures happen before any write; commit-phase failures are
+            // rolled back by runArchive, which says so in the message it throws.
+            // A file loam cannot decode is one it cannot merge, and that is the same
+            // answer as any other merge it could not compute: nothing was written.
+            fail(json, archiveErrorCode(err), `archive ${featureId} failed: ${message(err)}`);
+        }
+    });
+}
+async function runArchive(featureId, opts) {
+    const json = opts.json === true;
+    const config = await configOrRefuse(json);
+    if (config === null)
+        return;
+    const release = await acquireDocsLock(config.docsDir);
+    try {
+        await archiveLocked(config, featureId, opts);
+    }
+    finally {
+        await release();
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/commands/archive/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../src/commands/archive/archive.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,IAAI,EAAkB,MAAM,6BAA6B,CAAC;AACjG,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAuB,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAE3E;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,GAAY;IACpC,IAAI,GAAG,YAAY,YAAY;QAAE,OAAO,GAAG,CAAC,IAAI,CAAC;IACjD,4EAA4E;IAC5E,IAAI,GAAG,YAAY,aAAa;QAAE,OAAO,WAAW,CAAC;IACrD,uEAAuE;IACvE,IAAI,GAAG,YAAY,oBAAoB;QAAE,OAAO,cAAc,CAAC;IAC/D,IAAI,GAAG,YAAY,YAAY;QAAE,OAAO,cAAc,CAAC;IACvD,yEAAyE;IACzE,2EAA2E;IAC3E,4EAA4E;IAC5E,yEAAyE;IACzE,6EAA6E;IAC7E,uBAAuB;IACvB,IAAI,GAAG,YAAY,iBAAiB;QAAE,OAAO,cAAc,CAAC;IAC5D,IAAI,GAAG,YAAY,sBAAsB;QAAE,OAAO,oBAAoB,CAAC;IACvE,OAAO,UAAU,CAAC;AACpB,CAAC;AAGD,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,QAAQ,CAAC,aAAa,EAAE,2BAA2B,CAAC;SACpD,WAAW,CAAC,uHAAuH,CAAC;SACpI,MAAM,CAAC,WAAW,EAAE,sGAAsG,CAAC;SAC3H,MAAM,CAAC,WAAW,EAAE,8CAA8C,CAAC;SACnE,MAAM,CAAC,QAAQ,EAAE,qDAAqD,CAAC;SACvE,MAAM,CAAC,KAAK,EAAE,SAAiB,EAAE,IAAoB,EAAE,EAAE;QACxD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,yEAAyE;YACzE,qEAAqE;YACrE,yEAAyE;YACzE,uEAAuE;YACvE,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAAE,WAAW,SAAS,YAAY,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpF,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,SAAiB,EAAE,IAAoB;IAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;IAChC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO;IAC5B,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,EAAE,CAAC;IAClB,CAAC;AACH,CAAC","sourcesContent":["/**\n * `loam archive`: fold a finished feature's three axes into the living docs.\n *\n * Registration and the lock, nothing else. Everything the command actually does\n * is under `./plan/` and `./run.ts`, in that order — the gate refuses, the plan\n * computes, the commit swaps.\n */\nimport type { Command } from \"commander\";\nimport { CodedFailure, configOrRefuse, fail, type ErrorCode } from \"../../core/envelope/json.js\";\nimport { message } from \"../../core/staging/commit.js\";\nimport { acquireDocsLock, DocsBusyError } from \"../../core/staging/lock.js\";\nimport { type ArchiveOptions } from \"./plan/refusal.js\";\nimport { archiveLocked } from \"./run.js\";\nimport { LandscapeSpliceError } from \"../../core/c4/splice/contract.js\";\nimport { NotUtf8Error } from \"../../core/staging/writes.js\";\nimport { OpenapiMergeError } from \"../../core/openapi/merge/error.js\";\nimport { InterruptedCommitError } from \"../../core/staging/interrupted.js\";\n\n/**\n * The code a failed archive answers with. A `CodedFailure` is thrown from the\n * plan phase (nothing written yet) and from the commit's rollback path (whose\n * message says whether the rollback held). Anything that escapes runArchive and\n * matches no arm below is a bug, and reports as `internal`.\n */\nfunction archiveErrorCode(err: unknown): ErrorCode {\n  if (err instanceof CodedFailure) return err.code;\n  // Another writer holds the docs repo — the lock is taken refuse-fast below.\n  if (err instanceof DocsBusyError) return \"docs-busy\";\n  // Every splice refusal is the mechanical merge answer — see the class.\n  if (err instanceof LandscapeSpliceError) return \"merge-failed\";\n  if (err instanceof NotUtf8Error) return \"merge-failed\";\n  // The merge branch wraps its own call and re-throws as merge-failed; the\n  // create branch (`stripOpenapiRemovalMarkers`) does not, so one unreadable\n  // feature contract answered merge-failed or `internal` depending on whether\n  // the service already had a living openapi.yaml. The code answers \"can I\n  // trust the repo?\", and that answer does not turn on which side of the merge\n  // the document sat on.\n  if (err instanceof OpenapiMergeError) return \"merge-failed\";\n  if (err instanceof InterruptedCommitError) return \"commit-interrupted\";\n  return \"internal\";\n}\n\n\nexport function registerArchive(program: Command): void {\n  program\n    .command(\"archive\")\n    .argument(\"<featureId>\", \"feature id, e.g. FEAT-101\")\n    .description(\"Merge a finished feature's deltas into the living specs + model, then archive it (checks the documents, not the code)\")\n    .option(\"--approve\", \"archive despite GATING coherence issues (may corrupt the living docs); advisory warnings never block\")\n    .option(\"--dry-run\", \"print the whole merge plan and write nothing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureId: string, opts: ArchiveOptions) => {\n      const json = opts.json === true;\n      try {\n        await runArchive(featureId, opts);\n      } catch (err) {\n        // Plan-phase failures happen before any write; commit-phase failures are\n        // rolled back by runArchive, which says so in the message it throws.\n        // A file loam cannot decode is one it cannot merge, and that is the same\n        // answer as any other merge it could not compute: nothing was written.\n        fail(json, archiveErrorCode(err), `archive ${featureId} failed: ${message(err)}`);\n      }\n    });\n}\n\nasync function runArchive(featureId: string, opts: ArchiveOptions): Promise<void> {\n  const json = opts.json === true;\n  const config = await configOrRefuse(json);\n  if (config === null) return;\n  const release = await acquireDocsLock(config.docsDir);\n  try {\n    await archiveLocked(config, featureId, opts);\n  } finally {\n    await release();\n  }\n}\n"]}

package/dist/commands/archive/closing.js

@@ -0,0 +1,42 @@
+/**
+ * The advisories that mean "archive the other feature first" AND name an error
+ * the fleet gate reports once this one lands alone — `spec-api.op-undefined`,
+ * `spine.op-undefined`, `spec-event.message-undefined`,
+ * `spine.message-unproduced`. The delta pair (`delta.modified-pending`,
+ * `delta.removed-pending`) is NOT here, because the line below would be false
+ * for it: the merge appends a MODIFIED it cannot find and drops a REMOVED one,
+ * so `validate --all` reports nothing — the cost lands on the OTHER feature's
+ * archive (`delta.added-duplicate`) or nowhere, which is that warning's own
+ * sentence to say.
+ */
+const ORDERING = new Set([
+    "spec-api.op-pending",
+    "c4-api.op-pending",
+    "spec-event.message-pending",
+    "c4-event.message-pending",
+]);
+/** The `⚠` lines owed in place of the closing claim — empty when the claim is true. */
+export function outstandingLines(state) {
+    const lines = [];
+    // One line per stale file rather than one line listing them: each names a file
+    // a reader opens, and a comma-joined series would have to choose a verb that
+    // reads wrong for one of the two counts.
+    for (const path of state.staleViews) {
+        lines.push(`  ⚠ ${path} no longer matches the tree and this map — run \`loam subsystem sync\`.`);
+    }
+    for (const w of state.planWarns)
+        if (w.severity === "error")
+            lines.push(`  ⚠ ${w.message}`);
+    const ordering = state.advisory.filter((i) => ORDERING.has(i.code));
+    if (ordering.length > 0) {
+        lines.push(`  ⚠ ${state.dryRun ? "archiving this now lands" : "this archive landed"} ahead of ${ordering.length} change(s) still in flight ` +
+            "that it waits on (the pending warnings above) — `loam validate --all` reports each as an error until that feature archives too.");
+    }
+    if (state.overridden.length > 0) {
+        lines.push(state.dryRun
+            ? `  ⚠ --approve would merge past ${state.overridden.length} gating issue(s) — the living docs would carry them; \`loam validate --all\` says what they cost.`
+            : `  ⚠ merged past ${state.overridden.length} gating issue(s) with --approve — the living docs carry them now; \`loam validate --all\` says what they cost.`);
+    }
+    return lines;
+}
+//# sourceMappingURL=closing.js.map

package/dist/commands/archive/closing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closing.js","sourceRoot":"","sources":["../../../src/commands/archive/closing.ts"],"names":[],"mappings":"AA8BA;;;;;;;;;;GAUG;AACH,MAAM,QAAQ,GAA2B,IAAI,GAAG,CAAY;IAC1D,qBAAqB;IACrB,mBAAmB;IACnB,4BAA4B;IAC5B,0BAA0B;CAC3B,CAAC,CAAC;AAgBH,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,6EAA6E;IAC7E,yCAAyC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,yEAAyE,CAAC,CAAC;IACnG,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS;QAAE,IAAI,CAAC,CAAC,QAAQ,KAAK,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5F,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CACR,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,qBAAqB,aAAa,QAAQ,CAAC,MAAM,6BAA6B;YAC/H,iIAAiI,CACpI,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CACR,KAAK,CAAC,MAAM;YACV,CAAC,CAAC,kCAAkC,KAAK,CAAC,UAAU,CAAC,MAAM,mGAAmG;YAC9J,CAAC,CAAC,mBAAmB,KAAK,CAAC,UAAU,CAAC,MAAM,gHAAgH,CAC/J,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["/**\n * What the archive still owes the fleet after its merge — the lines that stand\n * in for \"living spec + landscape are now complete + current.\".\n *\n * That closing line is a claim about the whole docs repo, and it is the line a\n * reader stops at. It may be printed only when this archive leaves nothing the\n * next `validate --all` will fail on, so every reason it cannot be is listed\n * here, once, for the real run and the dry run alike. The dry run used to print\n * none of them: `--json` carried `service.no-model` in `warnings`, the real run\n * printed it after the commit, and the text dry run — the one a person reads\n * before deciding — said nothing (the real-fleet review, 2026-10-21).\n *\n * FOUR REASONS, each a breach the next `validate --all` reports:\n *\n *  - a plan finding of ERROR severity that does not gate — `service.no-model`,\n *    a service this archive brings in without writing its model (a binding the\n *    map gains with no directory; one whose directory the archive creates and\n *    the merged map draws gets an empty model, `plan/landscape.ts`). Read off the\n *    severity, not a code list: the plan files an error exactly when it knows\n *    validate will, and a second list here is the copy that drifts;\n *  - an advisory that orders this feature behind another one still in flight\n *    and softens a fleet-gate error (four of the `*-pending` family): archived\n *    first, the merge lands a reference the other feature's merge has not made\n *    true yet;\n *  - gating issues the caller merged past with `--approve`;\n *  - a generated views file the new map no longer matches — known only once\n *    the commit has happened, so the dry run cannot name it.\n */\nimport type { Issue, IssueCode } from \"../../core/vocabulary/issue.js\";\n\n/**\n * The advisories that mean \"archive the other feature first\" AND name an error\n * the fleet gate reports once this one lands alone — `spec-api.op-undefined`,\n * `spine.op-undefined`, `spec-event.message-undefined`,\n * `spine.message-unproduced`. The delta pair (`delta.modified-pending`,\n * `delta.removed-pending`) is NOT here, because the line below would be false\n * for it: the merge appends a MODIFIED it cannot find and drops a REMOVED one,\n * so `validate --all` reports nothing — the cost lands on the OTHER feature's\n * archive (`delta.added-duplicate`) or nowhere, which is that warning's own\n * sentence to say.\n */\nconst ORDERING: ReadonlySet<IssueCode> = new Set<IssueCode>([\n  \"spec-api.op-pending\",\n  \"c4-api.op-pending\",\n  \"spec-event.message-pending\",\n  \"c4-event.message-pending\",\n]);\n\n/** Everything the archive knows about what it leaves behind. */\nexport interface Outstanding {\n  /** The coherence gate's advisory warnings. */\n  advisory: readonly Issue[];\n  /** The plan's own findings — overwrites, and the services it creates with no model. */\n  planWarns: readonly Issue[];\n  /** Gating issues `--approve` walked past. */\n  overridden: readonly Issue[];\n  /** Generated views the committed map no longer matches; empty before a commit. */\n  staleViews: readonly string[];\n  /** Phrase it as what WOULD remain — the dry run's tense. */\n  dryRun: boolean;\n}\n\n/** The `⚠` lines owed in place of the closing claim — empty when the claim is true. */\nexport function outstandingLines(state: Outstanding): string[] {\n  const lines: string[] = [];\n  // One line per stale file rather than one line listing them: each names a file\n  // a reader opens, and a comma-joined series would have to choose a verb that\n  // reads wrong for one of the two counts.\n  for (const path of state.staleViews) {\n    lines.push(`  ⚠ ${path} no longer matches the tree and this map — run \\`loam subsystem sync\\`.`);\n  }\n  for (const w of state.planWarns) if (w.severity === \"error\") lines.push(`  ⚠ ${w.message}`);\n  const ordering = state.advisory.filter((i) => ORDERING.has(i.code));\n  if (ordering.length > 0) {\n    lines.push(\n      `  ⚠ ${state.dryRun ? \"archiving this now lands\" : \"this archive landed\"} ahead of ${ordering.length} change(s) still in flight ` +\n        \"that it waits on (the pending warnings above) — `loam validate --all` reports each as an error until that feature archives too.\",\n    );\n  }\n  if (state.overridden.length > 0) {\n    lines.push(\n      state.dryRun\n        ? `  ⚠ --approve would merge past ${state.overridden.length} gating issue(s) — the living docs would carry them; \\`loam validate --all\\` says what they cost.`\n        : `  ⚠ merged past ${state.overridden.length} gating issue(s) with --approve — the living docs carry them now; \\`loam validate --all\\` says what they cost.`,\n    );\n  }\n  return lines;\n}\n"]}