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

package/dist/commands/archive/plan/landscape.js

@@ -0,0 +1,161 @@
+/**
+ * The fleet map merge, the flows drawn over it, and the services this archive
+ * brings into existence.
+ *
+ * The landscape is the one document every feature writes into, so it is spliced
+ * rather than rewritten: the authored file keeps its shape and the delta's
+ * elements are placed into it. A service arriving on the architecture axis alone
+ * has no `model.likec4` yet, and the warning for that is carried out of the plan
+ * — `validate` would report it next, and reporting it here is what stops that
+ * being a surprise.
+ *
+ * `planFlows` at the bottom is the other half of the same axis and shares this
+ * module for that reason rather than for the file cap: both write into
+ * `architecture/`, and the two merges are read together — the map gains the
+ * elements, the flow gains the ordered hops over them. It is a whole-file copy
+ * where the landscape is a splice, because a flow is a document of its own and
+ * there is nothing to merge partially.
+ */
+import { existsSync } from "node:fs";
+import { planWrite, readUtf8 } from "../../../core/staging/writes.js";
+import { planLandscapeMerge } from "../../../core/c4/splice/landscape-merge.js";
+import { titleOf } from "../../../core/c4/splice/identity/edges.js";
+import { parseServiceId } from "../../../core/kernel/ids/service.js";
+import { landscapePath as landscapeFile } from "../../../core/repo/paths.js";
+import { enumeratedServiceIds } from "../../../core/repo/service-target.js";
+import {} from "./state.js";
+import { ArchiveFailure } from "./refusal.js";
+import { featurePaths } from "../../../core/repo/paths.js";
+import { featureFlows, livingFlowPath, USECASE_SUBDIR } from "../../../core/usecases/delta/flows.js";
+export async function planLandscape(config, gated, plan, say) {
+    const { id, featureDir, deltaDoc, deltaServices } = gated;
+    const deltaLikec4 = featurePaths(featureDir).delta;
+    const { writes, planWarns, architectureServices } = plan;
+    const landscapePath = landscapeFile(config.docsDir);
+    if (deltaDoc !== undefined) {
+        const delta = deltaDoc;
+        if (delta.errors.length > 0) {
+            // --approve overrides loam's JUDGMENT about coherence, never its ability to
+            // read an axis. Skipping here would silently drop one merge axis in the one
+            // command engineered against quiet partial merges — same rule as an
+            // unparseable landscape or openapi: the plan stops before anything is written.
+            throw new ArchiveFailure("merge-failed", `delta.likec4 has ${delta.errors.length} parse error(s) — the architecture axis cannot be merged; fix it (\`loam validate --feature ${id}\`) or delete the file`);
+        }
+        // The feature tag is the whole selection mechanism of this merge, and since
+        // LikeC4 1.59.0 a specification KIND can carry a tag that every element or
+        // edge of that kind then inherits. A delta declaring its own feature tag on
+        // a kind makes `newEls`/`newRels` below select the entire document —
+        // including the context declarations the scaffold ships commented out
+        // precisely so they are NOT merged — and archive would splice somebody
+        // else's services into the fleet map at exit 0. Mechanical, so `--approve`
+        // does not reach it, and refused before the merge is even planned.
+        const kindTagged = [
+            ...Object.entries(delta.specification?.elementKindTags ?? {}),
+            ...Object.entries(delta.specification?.relationshipKindTags ?? {}),
+        ].find(([, tags]) => tags.includes(id));
+        if (kindTagged !== undefined) {
+            throw new ArchiveFailure("merge-failed", `delta.likec4 declares the feature tag '#${id}' on kind '${kindTagged[0]}' in its specification block, so every ` +
+                `'${kindTagged[0]}' in the file inherits it — the merge would treat the whole document as this feature's ` +
+                `additions, context elements included, and splice them into architecture/landscape.likec4. Nothing was ` +
+                `written. Remove '#${id}' from the kind and tag only the declarations ${id} actually adds.`);
+        }
+        const newEls = delta.elements.filter((e) => e.tags.includes(id));
+        const newRels = delta.relationships.filter((r) => r.tags.includes(id));
+        if (existsSync(landscapePath)) {
+            const plan = await planLandscapeMerge({
+                landscapeText: await readUtf8(landscapePath),
+                deltaText: await readUtf8(deltaLikec4),
+                deltaElements: delta.elements,
+                newEls,
+                newRels,
+                featureId: id,
+            });
+            // A service can arrive on the ARCHITECTURE axis alone: an element this
+            // merge ADDS, carrying a `metadata { service }` binding, with no
+            // `specs/<svc>/` anywhere in the feature. It is a service the fleet gate
+            // will demand a directory for the moment this merge lands, so it owes the
+            // same warning as one arriving with a requirement delta — and until it
+            // did, the closing "complete + current" line printed over a landscape
+            // this very archive had just made red. Read off the ADDED elements, not
+            // the tagged ones: an element the living landscape already had is not
+            // arriving, and one that is never merged is not there to demand anything.
+            // A binding is document text, which the service path builders no longer accept.
+            // The parse cannot actually filter anything here: an illegal binding is
+            // `c4.service-binding-invalid`, a coherence ERROR `--approve` does not
+            // override, refused before any merge is planned — so the `ok` test only
+            // carries the compiler's proof that document text never reaches a path.
+            for (const e of plan.addedEls) {
+                const parsed = e.service === undefined ? undefined : parseServiceId(e.service);
+                if (parsed?.ok === true)
+                    architectureServices.add(parsed.id);
+            }
+            if (plan.content !== null)
+                writes.push(planWrite(landscapePath, plan.content));
+            say(`\n  architecture: merged into landscape.likec4 — +${plan.addedEls.length} element(s), +${plan.addedRels.length} relationship(s)`);
+            for (const e of plan.addedEls)
+                say(`      + ${e.title} (${e.kind})`);
+            for (const r of plan.addedRels) {
+                say(`      + ${titleOf(delta.elements, r.source)} -> ${titleOf(delta.elements, r.target)}  "${r.title ?? ""}"`);
+            }
+        }
+        else {
+            say(`\n  architecture: no landscape.likec4 — ${newEls.length} element(s) not merged`);
+        }
+    }
+    // A service this archive BRINGS INTO EXISTENCE arrives without the one file
+    // `validate` demands of every service: its own model.likec4. The merge cannot
+    // write it — the delta's tagged subtree is a landscape-level box, not a
+    // container model, and inventing a plausible one is the kind of quiet fiction
+    // the rest of loam exists to prevent — so the archive says so instead, and
+    // stops claiming the docs are complete. Non-gating: the feature is coherent
+    // and the merge is correct; what is missing is the next step, and refusing
+    // here would make onboarding a new service impossible in one command.
+    // "New" is enumeration membership, not an existsSync of services/<svc>/ at
+    // the root: a FILED service exists wherever the tree walk found it, and the
+    // root probe would grade every filed service as newly created here.
+    const enumerated = new Set(await enumeratedServiceIds(config.docsDir));
+    const newServices = [...new Set([...deltaServices, ...architectureServices])].filter((svc) => !enumerated.has(svc));
+    for (const svc of newServices) {
+        // Two shapes of the same debt: a service with a requirement delta gets its
+        // directory from this merge, one that arrives only in the landscape gets no
+        // directory at all — and `validate --all` fails the second harder
+        // (`landscape.service-unmodelled` names the binding with nothing behind it).
+        const creates = deltaServices.some((d) => d === svc)
+            ? `this archive creates services/${svc}/, but nothing writes services/${svc}/model.likec4`
+            : `this archive puts '${svc}' in the landscape, but the fleet has no services/${svc}/ at all`;
+        planWarns.push({
+            severity: "warn",
+            code: "service.no-model",
+            subject: svc,
+            message: `${svc}: ${creates} — 'loam validate --all' will report the service as incomplete until it exists. Run 'loam adopt --service ${svc}' from the service repo, or write the model by hand.`,
+        });
+    }
+}
+/**
+ * The flows this feature brings, copied into `architecture/usecases/`.
+ *
+ * A create-only whole-file copy, and the smallest merge in the command: the
+ * document is views-only, it names nothing the landscape merge has not already
+ * placed (`planFlowOverlay` in the gate is what proves that, before this runs),
+ * and a flow the living tree already holds was refused at the gate
+ * (`usecase.flow-exists`, `core/usecases/delta/flows.ts` has the reasoning). So
+ * by the time this runs every path here is a file that does not exist, and
+ * `planWrite` marks it `exclusive` — a race that created it between the gate and
+ * the commit fails the write rather than overwriting somebody.
+ *
+ * It lives beside `planLandscape` rather than beside the requirement merges
+ * because it writes into `architecture/`, and the two merges are read together:
+ * the landscape gains the elements, the flow gains the hops over them.
+ * `unarchive` needs nothing new — a create is undone by deleting, which the
+ * snapshot manifest already records for every write in the plan.
+ */
+export async function planFlows(config, gated, plan, say) {
+    const flows = await featureFlows(gated.featureDir);
+    if (flows.length === 0)
+        return;
+    for (const flow of flows) {
+        plan.writes.push(planWrite(livingFlowPath(config.docsDir, flow.rel), await readUtf8(flow.path)));
+        say(`  use case: ${flow.rel} — created architecture/${USECASE_SUBDIR}/${flow.rel}`);
+    }
+}
+//# sourceMappingURL=landscape.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"landscape.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/landscape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet map merge, the flows drawn over it, and the services this archive\n * brings into existence.\n *\n * The landscape is the one document every feature writes into, so it is spliced\n * rather than rewritten: the authored file keeps its shape and the delta's\n * elements are placed into it. A service arriving on the architecture axis alone\n * has no `model.likec4` yet, and the warning for that is carried out of the plan\n * — `validate` would report it next, and reporting it here is what stops that\n * being a surprise.\n *\n * `planFlows` at the bottom is the other half of the same axis and shares this\n * module for that reason rather than for the file cap: both write into\n * `architecture/`, and the two merges are read together — the map gains the\n * elements, the flow gains the ordered hops over them. It is a whole-file copy\n * where the landscape is a splice, because a flow is a document of its own and\n * there is nothing to merge partially.\n */\nimport { existsSync } from \"node:fs\";\nimport { planWrite, readUtf8 } from \"../../../core/staging/writes.js\";\nimport { planLandscapeMerge } from \"../../../core/c4/splice/landscape-merge.js\";\nimport { titleOf } from \"../../../core/c4/splice/identity/edges.js\";\nimport { parseServiceId } from \"../../../core/kernel/ids/service.js\";\nimport { landscapePath as landscapeFile } from \"../../../core/repo/paths.js\";\nimport { enumeratedServiceIds } from \"../../../core/repo/service-target.js\";\nimport { type Gated, type Plan } from \"./state.js\";\nimport { ArchiveFailure } from \"./refusal.js\";\nimport { featurePaths } from \"../../../core/repo/paths.js\";\nimport { featureFlows, livingFlowPath, USECASE_SUBDIR } from \"../../../core/usecases/delta/flows.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\nexport async function planLandscape(\n  config: { docsDir: DocsDir },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { id, featureDir, deltaDoc, deltaServices } = gated;\n  const deltaLikec4 = featurePaths(featureDir).delta;\n  const { writes, planWarns, architectureServices } = plan;\n  const landscapePath = landscapeFile(config.docsDir);\n  if (deltaDoc !== undefined) {\n    const delta = deltaDoc;\n    if (delta.errors.length > 0) {\n      // --approve overrides loam's JUDGMENT about coherence, never its ability to\n      // read an axis. Skipping here would silently drop one merge axis in the one\n      // command engineered against quiet partial merges — same rule as an\n      // unparseable landscape or openapi: the plan stops before anything is written.\n      throw new ArchiveFailure(\n        \"merge-failed\",\n        `delta.likec4 has ${delta.errors.length} parse error(s) — the architecture axis cannot be merged; fix it (\\`loam validate --feature ${id}\\`) or delete the file`,\n      );\n    }\n    // The feature tag is the whole selection mechanism of this merge, and since\n    // LikeC4 1.59.0 a specification KIND can carry a tag that every element or\n    // edge of that kind then inherits. A delta declaring its own feature tag on\n    // a kind makes `newEls`/`newRels` below select the entire document —\n    // including the context declarations the scaffold ships commented out\n    // precisely so they are NOT merged — and archive would splice somebody\n    // else's services into the fleet map at exit 0. Mechanical, so `--approve`\n    // does not reach it, and refused before the merge is even planned.\n    const kindTagged = [\n      ...Object.entries(delta.specification?.elementKindTags ?? {}),\n      ...Object.entries(delta.specification?.relationshipKindTags ?? {}),\n    ].find(([, tags]) => tags.includes(id));\n    if (kindTagged !== undefined) {\n      throw new ArchiveFailure(\n        \"merge-failed\",\n        `delta.likec4 declares the feature tag '#${id}' on kind '${kindTagged[0]}' in its specification block, so every ` +\n          `'${kindTagged[0]}' in the file inherits it — the merge would treat the whole document as this feature's ` +\n          `additions, context elements included, and splice them into architecture/landscape.likec4. Nothing was ` +\n          `written. Remove '#${id}' from the kind and tag only the declarations ${id} actually adds.`,\n      );\n    }\n    const newEls = delta.elements.filter((e) => e.tags.includes(id));\n    const newRels = delta.relationships.filter((r) => r.tags.includes(id));\n    if (existsSync(landscapePath)) {\n      const plan = await planLandscapeMerge({\n        landscapeText: await readUtf8(landscapePath),\n        deltaText: await readUtf8(deltaLikec4),\n        deltaElements: delta.elements,\n        newEls,\n        newRels,\n        featureId: id,\n      });\n      // A service can arrive on the ARCHITECTURE axis alone: an element this\n      // merge ADDS, carrying a `metadata { service }` binding, with no\n      // `specs/<svc>/` anywhere in the feature. It is a service the fleet gate\n      // will demand a directory for the moment this merge lands, so it owes the\n      // same warning as one arriving with a requirement delta — and until it\n      // did, the closing \"complete + current\" line printed over a landscape\n      // this very archive had just made red. Read off the ADDED elements, not\n      // the tagged ones: an element the living landscape already had is not\n      // arriving, and one that is never merged is not there to demand anything.\n      // A binding is document text, which the service path builders no longer accept.\n      // The parse cannot actually filter anything here: an illegal binding is\n      // `c4.service-binding-invalid`, a coherence ERROR `--approve` does not\n      // override, refused before any merge is planned — so the `ok` test only\n      // carries the compiler's proof that document text never reaches a path.\n      for (const e of plan.addedEls) {\n        const parsed = e.service === undefined ? undefined : parseServiceId(e.service);\n        if (parsed?.ok === true) architectureServices.add(parsed.id);\n      }\n      if (plan.content !== null) writes.push(planWrite(landscapePath, plan.content));\n      say(`\\n  architecture: merged into landscape.likec4 — +${plan.addedEls.length} element(s), +${plan.addedRels.length} relationship(s)`);\n      for (const e of plan.addedEls) say(`      + ${e.title} (${e.kind})`);\n      for (const r of plan.addedRels) {\n        say(`      + ${titleOf(delta.elements, r.source)} -> ${titleOf(delta.elements, r.target)}  \"${r.title ?? \"\"}\"`);\n      }\n    } else {\n      say(`\\n  architecture: no landscape.likec4 — ${newEls.length} element(s) not merged`);\n    }\n  }\n\n  // A service this archive BRINGS INTO EXISTENCE arrives without the one file\n  // `validate` demands of every service: its own model.likec4. The merge cannot\n  // write it — the delta's tagged subtree is a landscape-level box, not a\n  // container model, and inventing a plausible one is the kind of quiet fiction\n  // the rest of loam exists to prevent — so the archive says so instead, and\n  // stops claiming the docs are complete. Non-gating: the feature is coherent\n  // and the merge is correct; what is missing is the next step, and refusing\n  // here would make onboarding a new service impossible in one command.\n  // \"New\" is enumeration membership, not an existsSync of services/<svc>/ at\n  // the root: a FILED service exists wherever the tree walk found it, and the\n  // root probe would grade every filed service as newly created here.\n  const enumerated = new Set<string>(await enumeratedServiceIds(config.docsDir));\n  const newServices = [...new Set([...deltaServices, ...architectureServices])].filter(\n    (svc) => !enumerated.has(svc),\n  );\n  for (const svc of newServices) {\n    // Two shapes of the same debt: a service with a requirement delta gets its\n    // directory from this merge, one that arrives only in the landscape gets no\n    // directory at all — and `validate --all` fails the second harder\n    // (`landscape.service-unmodelled` names the binding with nothing behind it).\n    const creates = deltaServices.some((d) => d === svc)\n      ? `this archive creates services/${svc}/, but nothing writes services/${svc}/model.likec4`\n      : `this archive puts '${svc}' in the landscape, but the fleet has no services/${svc}/ at all`;\n    planWarns.push({\n      severity: \"warn\",\n      code: \"service.no-model\",\n      subject: svc,\n      message: `${svc}: ${creates} — 'loam validate --all' will report the service as incomplete until it exists. Run 'loam adopt --service ${svc}' from the service repo, or write the model by hand.`,\n    });\n  }\n}\n\n/**\n * The flows this feature brings, copied into `architecture/usecases/`.\n *\n * A create-only whole-file copy, and the smallest merge in the command: the\n * document is views-only, it names nothing the landscape merge has not already\n * placed (`planFlowOverlay` in the gate is what proves that, before this runs),\n * and a flow the living tree already holds was refused at the gate\n * (`usecase.flow-exists`, `core/usecases/delta/flows.ts` has the reasoning). So\n * by the time this runs every path here is a file that does not exist, and\n * `planWrite` marks it `exclusive` — a race that created it between the gate and\n * the commit fails the write rather than overwriting somebody.\n *\n * It lives beside `planLandscape` rather than beside the requirement merges\n * because it writes into `architecture/`, and the two merges are read together:\n * the landscape gains the elements, the flow gains the hops over them.\n * `unarchive` needs nothing new — a create is undone by deleting, which the\n * snapshot manifest already records for every write in the plan.\n */\nexport async function planFlows(\n  config: { docsDir: DocsDir },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const flows = await featureFlows(gated.featureDir);\n  if (flows.length === 0) return;\n  for (const flow of flows) {\n    plan.writes.push(planWrite(livingFlowPath(config.docsDir, flow.rel), await readUtf8(flow.path)));\n    say(`  use case: ${flow.rel} — created architecture/${USECASE_SUBDIR}/${flow.rel}`);\n  }\n}\n"]}

package/dist/commands/archive/plan/refusal.js

@@ -0,0 +1,111 @@
+/**
+ * How `loam archive` refuses, and what a refusal prints.
+ *
+ * Every arm here keeps one property: a refusal means nothing was written. The
+ * `--json` shapes carry the issues that caused it so an agent can act on the
+ * list rather than on the sentence, and `ArchiveFailure` exists so a merge that
+ * could not be computed reports as a merge failure rather than as `internal` —
+ * a read-only directory or an unreadable pre-image is not a bug in loam, and
+ * saying so sends the reader looking for one.
+ */
+import { existsSync } from "node:fs";
+import { emitJsonError, repoPath } from "../../../core/envelope/json.js";
+import { approveOverrides, issueFinding, } from "../../../core/vocabulary/issue.js";
+import {} from "../../../core/staging/interrupted.js";
+import {} from "../../../core/staging/writes.js";
+import { findingJson } from "../../../core/vocabulary/report.js";
+/**
+ * A refusal or failure with its stable `--json` code attached. Thrown from the
+ * plan phase (nothing written yet) and from the commit's rollback path (whose
+ * message says whether the rollback held). Anything ELSE that escapes runArchive
+ * is a bug, and the action handler reports it as `internal`.
+ */
+export class ArchiveFailure extends Error {
+    code;
+    constructor(code, msg) {
+        super(msg);
+        this.code = code;
+    }
+}
+/**
+ * An Issue as the `--json` envelope spells it — the Finding shape, minus details.
+ * `gates` and `overridable` are always present and already resolved: a consumer
+ * must not have to re-implement the severity default to know what blocks
+ * archive, nor keep a code list to know what `--approve` can move.
+ */
+export function issueJson(i, scope) {
+    return {
+        ...findingJson(issueFinding(i), scope === undefined ? undefined : { path: scope, role: "scope" }),
+        overridable: approveOverrides(i),
+    };
+}
+/** The failure envelope plus the issues that caused it, so a caller need not re-run validate. */
+export function refuseJson(code, msg, issues, scope) {
+    emitJsonError(code, msg, { issues: issues.map((issue) => issueJson(issue, scope)) });
+}
+/**
+ * The same envelope for a refusal computed from `Finding`s rather than
+ * `Issue`s — the plan-time checks whose codes are not coherence's (they belong
+ * to the LIVING documents, not to the feature) and so are not `IssueCode`s.
+ *
+ * `gates: true` is asserted rather than derived: every finding listed in a
+ * refusal is a reason archive stopped, which is what the field means. Nothing
+ * advisory reaches here.
+ */
+export function refuseFindings(code, msg, findings, scope) {
+    emitJsonError(code, msg, {
+        issues: findings.map((finding) => ({
+            ...findingJson(finding, scope === undefined ? undefined : { path: scope, role: "scope" }),
+            gates: true,
+        })),
+    });
+}
+/**
+ * Take the docs repo's advisory lock for the WHOLE plan+commit window, then
+ * archive.
+ *
+ * The window is the point. Two archives that overlap do not fight over a
+ * rename: they each read the living landscape, each splice their additions into
+ * the bytes they read, and the second write replaces the first — both exit 0,
+ * and `validate` stays green over a landscape that is missing one feature's
+ * architecture, because a document with fewer elements is not an invalid one.
+ * That is the only silent-loss path in loam that a later command cannot even
+ * detect, so it is closed at the coarsest possible granularity: one writer per
+ * docs repo, refusing rather than queueing, because a CLI that blocks for an
+ * unknown time is worse for an agent than one that says `docs-busy`.
+ */
+/**
+ * What the recovery did, before this command's own output — a docs repo that
+ * changed under the caller is the first thing they have to be told, not a
+ * footnote. Shared by archive and unarchive through the same CommitRecovery.
+ */
+export function sayRecovery(r) {
+    const what = `an interrupted \`loam ${r.command} ${r.feature}\``;
+    if (r.outcome === "completed") {
+        console.log(`⚠ ${what} had in fact finished — cleared its commit record.\n`);
+        return;
+    }
+    if (r.outcome === "consistent") {
+        console.log(`⚠ ${what} was rolled back before it wrote anything — cleared its commit record.\n`);
+        return;
+    }
+    // An interrupted archive is UNDONE and an interrupted unarchive is FINISHED —
+    // the merged text a restore was replacing is written down nowhere, so there is
+    // nothing to go back to. Say which happened; the paths are the same either way.
+    const what_ = r.command === "archive" ? "put them back from" : "finished them from";
+    console.log(`⚠ ${what} left ${r.repaired.length} file(s) half-written; ${what_} its snapshot:`);
+    for (const p of r.repaired)
+        console.log(`  ↩ ${p}`);
+    console.log("");
+}
+/** The full plan, as files: what a dry run shows instead of doing. */
+export function printPlan(docsDir, writes, dirName) {
+    console.log(`\n  plan — ${writes.length} file(s):`);
+    for (const w of writes) {
+        const verb = existsSync(w.path) ? "update" : "create";
+        console.log(`    ${verb}  ${repoPath(docsDir, w.path)}`);
+    }
+    console.log(`    move    features/${dirName} → features/archive/${dirName}`);
+    console.log("\n  dry run — nothing was written.");
+}
+//# sourceMappingURL=refusal.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/refusal.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How `loam archive` refuses, and what a refusal prints.\n *\n * Every arm here keeps one property: a refusal means nothing was written. The\n * `--json` shapes carry the issues that caused it so an agent can act on the\n * list rather than on the sentence, and `ArchiveFailure` exists so a merge that\n * could not be computed reports as a merge failure rather than as `internal` —\n * a read-only directory or an unreadable pre-image is not a bug in loam, and\n * saying so sends the reader looking for one.\n */\nimport { existsSync } from \"node:fs\";\nimport { emitJsonError, repoPath, type ErrorCode } from \"../../../core/envelope/json.js\";\nimport {\n  approveOverrides,\n  issueFinding,\n  type Issue,\n} from \"../../../core/vocabulary/issue.js\";\nimport { type CommitRecovery } from \"../../../core/staging/interrupted.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { findingJson, type Finding } from \"../../../core/vocabulary/report.js\";\n\nexport interface ArchiveOptions {\n  approve?: boolean;\n  dryRun?: boolean;\n  json?: boolean;\n}\n\n\n/**\n * A refusal or failure with its stable `--json` code attached. 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 ELSE that escapes runArchive\n * is a bug, and the action handler reports it as `internal`.\n */\nexport class ArchiveFailure extends Error {\n  constructor(\n    readonly code: ErrorCode,\n    msg: string,\n  ) {\n    super(msg);\n  }\n}\n\n/**\n * An Issue as the `--json` envelope spells it — the Finding shape, minus details.\n * `gates` and `overridable` are always present and already resolved: a consumer\n * must not have to re-implement the severity default to know what blocks\n * archive, nor keep a code list to know what `--approve` can move.\n */\nexport function issueJson(i: Issue, scope?: string): Record<string, unknown> {\n  return {\n    ...findingJson(\n      issueFinding(i),\n      scope === undefined ? undefined : { path: scope, role: \"scope\" },\n    ),\n    overridable: approveOverrides(i),\n  };\n}\n\n/** The failure envelope plus the issues that caused it, so a caller need not re-run validate. */\nexport function refuseJson(code: ErrorCode, msg: string, issues: Issue[], scope?: string): void {\n  emitJsonError(code, msg, { issues: issues.map((issue) => issueJson(issue, scope)) });\n}\n\n/**\n * The same envelope for a refusal computed from `Finding`s rather than\n * `Issue`s — the plan-time checks whose codes are not coherence's (they belong\n * to the LIVING documents, not to the feature) and so are not `IssueCode`s.\n *\n * `gates: true` is asserted rather than derived: every finding listed in a\n * refusal is a reason archive stopped, which is what the field means. Nothing\n * advisory reaches here.\n */\nexport function refuseFindings(\n  code: ErrorCode,\n  msg: string,\n  findings: Finding[],\n  scope?: string,\n): void {\n  emitJsonError(code, msg, {\n    issues: findings.map((finding) => ({\n      ...findingJson(\n        finding,\n        scope === undefined ? undefined : { path: scope, role: \"scope\" },\n      ),\n      gates: true,\n    })),\n  });\n}\n\n/**\n * Take the docs repo's advisory lock for the WHOLE plan+commit window, then\n * archive.\n *\n * The window is the point. Two archives that overlap do not fight over a\n * rename: they each read the living landscape, each splice their additions into\n * the bytes they read, and the second write replaces the first — both exit 0,\n * and `validate` stays green over a landscape that is missing one feature's\n * architecture, because a document with fewer elements is not an invalid one.\n * That is the only silent-loss path in loam that a later command cannot even\n * detect, so it is closed at the coarsest possible granularity: one writer per\n * docs repo, refusing rather than queueing, because a CLI that blocks for an\n * unknown time is worse for an agent than one that says `docs-busy`.\n */\n\n/**\n * What the recovery did, before this command's own output — a docs repo that\n * changed under the caller is the first thing they have to be told, not a\n * footnote. Shared by archive and unarchive through the same CommitRecovery.\n */\nexport function sayRecovery(r: CommitRecovery): void {\n  const what = `an interrupted \\`loam ${r.command} ${r.feature}\\``;\n  if (r.outcome === \"completed\") {\n    console.log(`⚠ ${what} had in fact finished — cleared its commit record.\\n`);\n    return;\n  }\n  if (r.outcome === \"consistent\") {\n    console.log(`⚠ ${what} was rolled back before it wrote anything — cleared its commit record.\\n`);\n    return;\n  }\n  // An interrupted archive is UNDONE and an interrupted unarchive is FINISHED —\n  // the merged text a restore was replacing is written down nowhere, so there is\n  // nothing to go back to. Say which happened; the paths are the same either way.\n  const what_ = r.command === \"archive\" ? \"put them back from\" : \"finished them from\";\n  console.log(`⚠ ${what} left ${r.repaired.length} file(s) half-written; ${what_} its snapshot:`);\n  for (const p of r.repaired) console.log(`  ↩ ${p}`);\n  console.log(\"\");\n}\n\n/** The full plan, as files: what a dry run shows instead of doing. */\nexport function printPlan(docsDir: string, writes: PlannedWrite[], dirName: string): void {\n  console.log(`\\n  plan — ${writes.length} file(s):`);\n  for (const w of writes) {\n    const verb = existsSync(w.path) ? \"update\" : \"create\";\n    console.log(`    ${verb}  ${repoPath(docsDir, w.path)}`);\n  }\n  console.log(`    move    features/${dirName} → features/archive/${dirName}`);\n  console.log(\"\\n  dry run — nothing was written.\");\n}\n"]}

package/dist/commands/archive/plan/specs.js

@@ -0,0 +1,237 @@
+/**
+ * The requirements merge: the feature's ADDED/MODIFIED/REMOVED requirements
+ * applied into each living service spec. The contract merges live beside it in
+ * `./contracts/` — one file per axis, split out when the OpenAPI half made
+ * this one carry two merges.
+ *
+ * ONE code path for the pair of requirement-carrying files — the business
+ * spec.md and the architecture arch.spec.md ride the same delta algebra, the
+ * same prose-preserving rewrite and the same guards, parameterized by filename.
+ * A fork here would be two places the merge could disagree.
+ *
+ * Nothing is written. Everything lands in the `Plan`, so a failure on any axis
+ * leaves the living docs exactly as they were.
+ */
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { rebaseLinks } from "../../../core/links/parse.js";
+import { planWrite, readUtf8 } from "../../../core/staging/writes.js";
+import { featureSpecPaths, SPEC_AXES } from "../../../core/repo/paths.js";
+import { capabilityDocsDir, glossaryDir, livingCapabilityPaths } from "../../../core/repo/authored/paths.js";
+import { featureGlossary, livingTermPath } from "../../../core/glossary/delta.js";
+import { locateServicePaths } from "../../../core/repo/service-target.js";
+import { isRequirementsHeading, parseRequirements, sectionHeadings, splitRequirementsSection, } from "../../../core/document/parse.js";
+import { applyRequirementDelta } from "../../../core/document/apply.js";
+import { serializeRequirements } from "../../../core/document/spec.js";
+import {} from "../../../core/document/spec.js";
+import { ArchiveFailure } from "./refusal.js";
+import {} from "./state.js";
+export async function planSpecs(config, gated, plan, say) {
+    const { featureDir, deltaServices } = gated;
+    const { writes } = plan;
+    // Requirements merge — apply ADDED/MODIFIED/REMOVED into each living service
+    // spec. ONE code path for the pair of requirement-carrying files: the business
+    // spec.md and the architecture arch.spec.md ride the same delta algebra, the
+    // same prose-preserving rewrite and the same guards, parameterized by filename
+    // (SPEC_AXES) — a fork here would be two places the merge could disagree.
+    for (const svc of deltaServices) {
+        for (const axis of SPEC_AXES) {
+            const deltaPath = featureSpecPaths(featureDir, svc)[axis.key];
+            if (!existsSync(deltaPath))
+                continue;
+            // The shared context: this is a deltaServices × SPEC_AXES loop, and a
+            // context-less locate is a full fleet walk per iteration.
+            const livingPath = (await locateServicePaths(config.docsDir, svc, config.fleet))[axis.key];
+            // Resolved BEFORE the delta is parsed, because the parse now depends on
+            // it: a requirement's markdown links are relative to the file they were
+            // written in, and this merge moves the text two directories up the tree.
+            // `core/links/parse.ts`'s `rebaseLinks` states the defect; the ordering
+            // here is what lets the fix see both ends of the move, including a
+            // service filed under a subsystem, whose living directory is deeper still.
+            const deltaReqs = parseRequirements(rebaseLinks(await readUtf8(deltaPath), { from: dirname(deltaPath), to: dirname(livingPath) }));
+            if (!existsSync(livingPath)) {
+                // New service (or first arch spec) — create the living file from the
+                // ADDED/MODIFIED requirements.
+                const created = applyRequirementDelta([], deltaReqs);
+                if (created.length === 0) {
+                    say(`  ${axis.label}: ${svc} — nothing to merge (delta leaves no requirements), no living ${axis.file} created`);
+                    continue;
+                }
+                const heading = axis.key === "spec" ? svc : `${svc} — architecture`;
+                const frontmatter = `---\nservice: ${svc}\nstatus: draft\n---\n\n# ${heading}\n\n`;
+                writes.push(planWrite(livingPath, `${frontmatter}## Requirements\n\n${serializeRequirements(created)}`));
+                say(`  ${axis.label}: ${svc} — created living ${axis.file} (${created.length} requirement(s))`);
+                continue;
+            }
+            const livingText = await readUtf8(livingPath);
+            // TWO `## Requirements` headings would put the rewrite's one-section
+            // invariant to a choice it must not make: the run of the first would be
+            // rewritten while the second survived verbatim in the tail — and its
+            // requirements, collected by parseRequirements, would land in the run TOO.
+            // Mechanical, like a model-less landscape, so merge-failed, not --approve.
+            const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));
+            if (reqHeadings.length > 1) {
+                throw new ArchiveFailure("merge-failed", `living ${axis.file} for ${svc} has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(", ")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`);
+            }
+            const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);
+            writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));
+            const c = summarize(deltaReqs);
+            say(`  ${axis.label}: ${svc} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);
+        }
+    }
+}
+/**
+ * The BUSINESS corpus's merge: a feature's `capabilities/<id>/spec.md` deltas
+ * applied into the living `capabilities/<id>/spec.md`.
+ *
+ * Here rather than in a sixth file in this package because this module already
+ * owns "requirements merged into a living document" — it owns
+ * `rewriteRequirementsRun`, the two-headings refusal and the `applyRequirementDelta`
+ * call, and the business corpus needs all three unchanged. What differs from
+ * `planSpecs` above is only where the living document lives and what a CREATED
+ * one says at the top.
+ *
+ * ARCHIVE CREATES THE LIVING DOCUMENT, by exact analogy with the new-service
+ * branch above. The directory IS the list on this axis (`core/capabilities/tree.ts`),
+ * so an archive that merged into a file it refused to create would make the
+ * whole delta merge nothing — which is the `delta.no-delta-sections` failure
+ * class, arriving through the merge instead of through the grammar.
+ *
+ * NO FRONTMATTER on a created capability document, and that is a decision
+ * rather than an omission. Nothing reads a capability document's frontmatter:
+ * `readCapabilityTree` classifies by the file's PRESENCE and
+ * `readCapabilityVocabulary` takes `description`/`owner` from the YAML side. A
+ * `status:` field invented here would be the "second list nothing keeps
+ * current" this axis was designed against.
+ *
+ * AND IT SAYS SO OUT LOUD. Creating the first `capabilities/<id>/spec.md`
+ * creates `capabilities/`, which is one of the two ways a fleet opts INTO the
+ * capability axis — from the next command on, `loam validate --all` grades a
+ * corpus that did not exist before. A merge that changes what the whole fleet
+ * is graded on must not do it silently.
+ */
+export async function planCapabilities(config, gated, plan, say) {
+    const { writes } = plan;
+    // Whether `capabilities/` exists is asked BEFORE the loop, because the loop
+    // is what would create it; `creating` records whether this run actually
+    // materialises a document, so the adoption line below is not printed by a
+    // run whose every capability delta merged into a document already there.
+    const adopting = !existsSync(capabilityDocsDir(config.docsDir));
+    let creating = false;
+    for (const doc of gated.capabilityDeltas) {
+        const livingPath = livingCapabilityPaths(config.docsDir, doc.id).spec;
+        // Same move, same rewrite: `features/<FEAT>/capabilities/<id>/` is two
+        // directories deeper than `capabilities/<id>/`, so a citation of a glossary
+        // term or an ADR would land pointing above the repository.
+        const deltaReqs = parseRequirements(rebaseLinks(await readUtf8(doc.spec), { from: dirname(doc.spec), to: dirname(livingPath) }));
+        if (!existsSync(livingPath)) {
+            const created = applyRequirementDelta([], deltaReqs);
+            if (created.length === 0) {
+                say(`  capability: ${doc.id} — nothing to merge (delta leaves no requirements), no living spec.md created`);
+                continue;
+            }
+            // The heading is the id and nothing else. loam merges requirements and
+            // never prose, so it must not fabricate the narrative that is the whole
+            // point of the document — the line below tells the author it is theirs.
+            writes.push(planWrite(livingPath, `# ${doc.id}\n\n## Requirements\n\n${serializeRequirements(created)}`));
+            creating = true;
+            say(`  capability: ${doc.id} — created capabilities/${doc.id}/spec.md (${created.length} requirement(s))`);
+            say(`      write the narrative above '## Requirements' — loam merges requirements, not prose`);
+            continue;
+        }
+        const livingText = await readUtf8(livingPath);
+        // The same one-section invariant as the service axis above, and the same
+        // reason it cannot be guessed at.
+        const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));
+        if (reqHeadings.length > 1) {
+            throw new ArchiveFailure("merge-failed", `living capabilities/${doc.id}/spec.md has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(", ")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`);
+        }
+        const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);
+        writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));
+        const c = summarize(deltaReqs);
+        say(`  capability: ${doc.id} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);
+    }
+    if (adopting && creating) {
+        say(`  capabilities/ did not exist — this archive opts the fleet into the business axis, and \`loam validate --all\` grades it from now on`);
+    }
+}
+/**
+ * Rewrite ONLY the requirements run of a living spec. Byte-for-byte preserved:
+ * everything before the first requirement inside `## Requirements` (the intro,
+ * the heading line, prose under the heading) and everything from the section's
+ * end onward (the next `## ` heading to EOF) — the old cut was a substring
+ * `indexOf("\n## Requirements")`, a prefix match that also hit
+ * `## Requirements Extra` and silently destroyed every section after the
+ * requirements. Prose BETWEEN requirements is body text of whatever is open
+ * above it (parseRequirements attributes it to the previous requirement's last
+ * scenario, or its text) and survives inside the re-serialized run, framing
+ * normalized. `merged` must contain every living requirement — runArchive's
+ * stray guard refuses any document whose requirements sit outside the section,
+ * using the same heading definition, before this output is ever written.
+ */
+function rewriteRequirementsRun(text, merged) {
+    const s = splitRequirementsSection(text);
+    // No `## Requirements` at all: the stray guard has already refused any doc
+    // whose requirements live elsewhere, so this one has none — open the section.
+    if (s === null)
+        return `${text.trimEnd()}\n\n## Requirements\n\n${serializeRequirements(merged)}`;
+    const body = serializeRequirements(merged);
+    // head/tail are raw slices; only the run's own framing is normalized. When
+    // the section held no requirements yet, the glue supplies the blank line the
+    // author never had reason to write.
+    const headGlue = s.run !== "" || s.head.endsWith("\n\n") ? "" : s.head.endsWith("\n") ? "\n" : "\n\n";
+    const tailGlue = s.tail === "" ? "" : "\n";
+    return s.head + headGlue + body + tailGlue + s.tail;
+}
+function summarize(reqs) {
+    const c = { ADDED: 0, MODIFIED: 0, REMOVED: 0 };
+    for (const r of reqs) {
+        if (r.kind === "ADDED")
+            c.ADDED += 1;
+        else if (r.kind === "MODIFIED")
+            c.MODIFIED += 1;
+        else if (r.kind === "REMOVED")
+            c.REMOVED += 1;
+    }
+    return c;
+}
+/**
+ * The vocabulary merge: each `features/<FEAT>/glossary/<term>.md` copied to
+ * `glossary/<term>.md`.
+ *
+ * A WHOLE-FILE COPY, and there is nothing else it could be. A capability delta
+ * is folded into a living document by the requirement algebra because the two
+ * documents share identified parts; a term document has one part, and merging
+ * two definitions of one word is not something a machine may attempt. So the
+ * definition the author wrote in the feature IS the definition that lands,
+ * verbatim — loam re-encodes it as UTF-8 through `readUtf8` and changes nothing
+ * else, not even the trailing newline.
+ *
+ * CREATE-ONLY, which is why this loop has no other branch. A term the living
+ * glossary already defines was refused at the gate (`glossary.term-exists`,
+ * `core/glossary/delta.ts` has the reasoning), so by the time the plan runs
+ * every path here is a file that does not exist. `planWrite` marks it
+ * `exclusive`, so a race that created it between the gate and the commit fails
+ * the write rather than overwriting somebody.
+ *
+ * AND IT SAYS SO OUT LOUD when it creates `glossary/`, exactly as
+ * `planCapabilities` does for `capabilities/`: the directory's existence is the
+ * axis's opt-in, so this merge changes what `loam validate --all` grades from
+ * the next command on, and a merge that widens the fleet's own gate must not do
+ * it silently.
+ */
+export async function planGlossary(config, gated, plan, say) {
+    const glossary = await featureGlossary(gated.featureDir);
+    if (!glossary.present || glossary.terms.length === 0)
+        return;
+    // Asked BEFORE the loop, because the loop is what would create it.
+    const adopting = !existsSync(glossaryDir(config.docsDir));
+    for (const term of glossary.terms) {
+        plan.writes.push(planWrite(livingTermPath(config.docsDir, term.id), await readUtf8(term.path)));
+        say(`  glossary: ${term.id} — created glossary/${term.id}.md`);
+    }
+    if (adopting) {
+        say(`  glossary/ did not exist — this archive opts the fleet into the domain vocabulary, and \`loam validate --all\` grades it from now on`);
+    }
+}
+//# sourceMappingURL=specs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"specs.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/specs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The requirements merge: the feature's ADDED/MODIFIED/REMOVED requirements\n * applied into each living service spec. The contract merges live beside it in\n * `./contracts/` — one file per axis, split out when the OpenAPI half made\n * this one carry two merges.\n *\n * ONE code path for the pair of requirement-carrying files — the business\n * spec.md and the architecture arch.spec.md ride the same delta algebra, the\n * same prose-preserving rewrite and the same guards, parameterized by filename.\n * A fork here would be two places the merge could disagree.\n *\n * Nothing is written. Everything lands in the `Plan`, so a failure on any axis\n * leaves the living docs exactly as they were.\n */\nimport { existsSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { rebaseLinks } from \"../../../core/links/parse.js\";\nimport { planWrite, readUtf8 } from \"../../../core/staging/writes.js\";\nimport { featureSpecPaths, SPEC_AXES } from \"../../../core/repo/paths.js\";\nimport { capabilityDocsDir, glossaryDir, livingCapabilityPaths } from \"../../../core/repo/authored/paths.js\";\nimport { featureGlossary, livingTermPath } from \"../../../core/glossary/delta.js\";\nimport { locateServicePaths } from \"../../../core/repo/service-target.js\";\nimport {\n  isRequirementsHeading,\n  parseRequirements,\n  sectionHeadings,\n  splitRequirementsSection,\n} from \"../../../core/document/parse.js\";\nimport { applyRequirementDelta } from \"../../../core/document/apply.js\";\nimport { serializeRequirements } from \"../../../core/document/spec.js\";\nimport { type Requirement } from \"../../../core/document/spec.js\";\nimport { ArchiveFailure } from \"./refusal.js\";\nimport { type Gated, type Plan } from \"./state.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../../../core/fleet-context.js\";\n\nexport async function planSpecs(\n  config: { docsDir: DocsDir; fleet?: FleetContext },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { featureDir, deltaServices } = gated;\n  const { writes } = plan;\n  // Requirements merge — apply ADDED/MODIFIED/REMOVED into each living service\n  // spec. ONE code path for the pair of requirement-carrying files: the business\n  // spec.md and the architecture arch.spec.md ride the same delta algebra, the\n  // same prose-preserving rewrite and the same guards, parameterized by filename\n  // (SPEC_AXES) — a fork here would be two places the merge could disagree.\n  for (const svc of deltaServices) {\n    for (const axis of SPEC_AXES) {\n      const deltaPath = featureSpecPaths(featureDir, svc)[axis.key];\n      if (!existsSync(deltaPath)) continue;\n\n      // The shared context: this is a deltaServices × SPEC_AXES loop, and a\n      // context-less locate is a full fleet walk per iteration.\n      const livingPath = (await locateServicePaths(config.docsDir, svc, config.fleet))[axis.key];\n      // Resolved BEFORE the delta is parsed, because the parse now depends on\n      // it: a requirement's markdown links are relative to the file they were\n      // written in, and this merge moves the text two directories up the tree.\n      // `core/links/parse.ts`'s `rebaseLinks` states the defect; the ordering\n      // here is what lets the fix see both ends of the move, including a\n      // service filed under a subsystem, whose living directory is deeper still.\n      const deltaReqs = parseRequirements(\n        rebaseLinks(await readUtf8(deltaPath), { from: dirname(deltaPath), to: dirname(livingPath) }),\n      );\n      if (!existsSync(livingPath)) {\n        // New service (or first arch spec) — create the living file from the\n        // ADDED/MODIFIED requirements.\n        const created = applyRequirementDelta([], deltaReqs);\n        if (created.length === 0) {\n          say(`  ${axis.label}: ${svc} — nothing to merge (delta leaves no requirements), no living ${axis.file} created`);\n          continue;\n        }\n        const heading = axis.key === \"spec\" ? svc : `${svc} — architecture`;\n        const frontmatter = `---\\nservice: ${svc}\\nstatus: draft\\n---\\n\\n# ${heading}\\n\\n`;\n        writes.push(planWrite(livingPath, `${frontmatter}## Requirements\\n\\n${serializeRequirements(created)}`));\n        say(`  ${axis.label}: ${svc} — created living ${axis.file} (${created.length} requirement(s))`);\n        continue;\n      }\n      const livingText = await readUtf8(livingPath);\n      // TWO `## Requirements` headings would put the rewrite's one-section\n      // invariant to a choice it must not make: the run of the first would be\n      // rewritten while the second survived verbatim in the tail — and its\n      // requirements, collected by parseRequirements, would land in the run TOO.\n      // Mechanical, like a model-less landscape, so merge-failed, not --approve.\n      const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));\n      if (reqHeadings.length > 1) {\n        throw new ArchiveFailure(\n          \"merge-failed\",\n          `living ${axis.file} for ${svc} has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(\", \")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`,\n        );\n      }\n      const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);\n      writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));\n\n      const c = summarize(deltaReqs);\n      say(`  ${axis.label}: ${svc} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);\n    }\n  }\n}\n\n/**\n * The BUSINESS corpus's merge: a feature's `capabilities/<id>/spec.md` deltas\n * applied into the living `capabilities/<id>/spec.md`.\n *\n * Here rather than in a sixth file in this package because this module already\n * owns \"requirements merged into a living document\" — it owns\n * `rewriteRequirementsRun`, the two-headings refusal and the `applyRequirementDelta`\n * call, and the business corpus needs all three unchanged. What differs from\n * `planSpecs` above is only where the living document lives and what a CREATED\n * one says at the top.\n *\n * ARCHIVE CREATES THE LIVING DOCUMENT, by exact analogy with the new-service\n * branch above. The directory IS the list on this axis (`core/capabilities/tree.ts`),\n * so an archive that merged into a file it refused to create would make the\n * whole delta merge nothing — which is the `delta.no-delta-sections` failure\n * class, arriving through the merge instead of through the grammar.\n *\n * NO FRONTMATTER on a created capability document, and that is a decision\n * rather than an omission. Nothing reads a capability document's frontmatter:\n * `readCapabilityTree` classifies by the file's PRESENCE and\n * `readCapabilityVocabulary` takes `description`/`owner` from the YAML side. A\n * `status:` field invented here would be the \"second list nothing keeps\n * current\" this axis was designed against.\n *\n * AND IT SAYS SO OUT LOUD. Creating the first `capabilities/<id>/spec.md`\n * creates `capabilities/`, which is one of the two ways a fleet opts INTO the\n * capability axis — from the next command on, `loam validate --all` grades a\n * corpus that did not exist before. A merge that changes what the whole fleet\n * is graded on must not do it silently.\n */\nexport async function planCapabilities(\n  config: { docsDir: DocsDir; fleet?: FleetContext },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { writes } = plan;\n  // Whether `capabilities/` exists is asked BEFORE the loop, because the loop\n  // is what would create it; `creating` records whether this run actually\n  // materialises a document, so the adoption line below is not printed by a\n  // run whose every capability delta merged into a document already there.\n  const adopting = !existsSync(capabilityDocsDir(config.docsDir));\n  let creating = false;\n  for (const doc of gated.capabilityDeltas) {\n    const livingPath = livingCapabilityPaths(config.docsDir, doc.id).spec;\n    // Same move, same rewrite: `features/<FEAT>/capabilities/<id>/` is two\n    // directories deeper than `capabilities/<id>/`, so a citation of a glossary\n    // term or an ADR would land pointing above the repository.\n    const deltaReqs = parseRequirements(\n      rebaseLinks(await readUtf8(doc.spec), { from: dirname(doc.spec), to: dirname(livingPath) }),\n    );\n    if (!existsSync(livingPath)) {\n      const created = applyRequirementDelta([], deltaReqs);\n      if (created.length === 0) {\n        say(`  capability: ${doc.id} — nothing to merge (delta leaves no requirements), no living spec.md created`);\n        continue;\n      }\n      // The heading is the id and nothing else. loam merges requirements and\n      // never prose, so it must not fabricate the narrative that is the whole\n      // point of the document — the line below tells the author it is theirs.\n      writes.push(planWrite(livingPath, `# ${doc.id}\\n\\n## Requirements\\n\\n${serializeRequirements(created)}`));\n      creating = true;\n      say(`  capability: ${doc.id} — created capabilities/${doc.id}/spec.md (${created.length} requirement(s))`);\n      say(`      write the narrative above '## Requirements' — loam merges requirements, not prose`);\n      continue;\n    }\n    const livingText = await readUtf8(livingPath);\n    // The same one-section invariant as the service axis above, and the same\n    // reason it cannot be guessed at.\n    const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));\n    if (reqHeadings.length > 1) {\n      throw new ArchiveFailure(\n        \"merge-failed\",\n        `living capabilities/${doc.id}/spec.md has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(\", \")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`,\n      );\n    }\n    const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);\n    writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));\n    const c = summarize(deltaReqs);\n    say(`  capability: ${doc.id} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);\n  }\n  if (adopting && creating) {\n    say(`  capabilities/ did not exist — this archive opts the fleet into the business axis, and \\`loam validate --all\\` grades it from now on`);\n  }\n}\n\n/**\n * Rewrite ONLY the requirements run of a living spec. Byte-for-byte preserved:\n * everything before the first requirement inside `## Requirements` (the intro,\n * the heading line, prose under the heading) and everything from the section's\n * end onward (the next `## ` heading to EOF) — the old cut was a substring\n * `indexOf(\"\\n## Requirements\")`, a prefix match that also hit\n * `## Requirements Extra` and silently destroyed every section after the\n * requirements. Prose BETWEEN requirements is body text of whatever is open\n * above it (parseRequirements attributes it to the previous requirement's last\n * scenario, or its text) and survives inside the re-serialized run, framing\n * normalized. `merged` must contain every living requirement — runArchive's\n * stray guard refuses any document whose requirements sit outside the section,\n * using the same heading definition, before this output is ever written.\n */\nfunction rewriteRequirementsRun(text: string, merged: Requirement[]): string {\n  const s = splitRequirementsSection(text);\n  // No `## Requirements` at all: the stray guard has already refused any doc\n  // whose requirements live elsewhere, so this one has none — open the section.\n  if (s === null) return `${text.trimEnd()}\\n\\n## Requirements\\n\\n${serializeRequirements(merged)}`;\n  const body = serializeRequirements(merged);\n  // head/tail are raw slices; only the run's own framing is normalized. When\n  // the section held no requirements yet, the glue supplies the blank line the\n  // author never had reason to write.\n  const headGlue = s.run !== \"\" || s.head.endsWith(\"\\n\\n\") ? \"\" : s.head.endsWith(\"\\n\") ? \"\\n\" : \"\\n\\n\";\n  const tailGlue = s.tail === \"\" ? \"\" : \"\\n\";\n  return s.head + headGlue + body + tailGlue + s.tail;\n}\n\nfunction summarize(reqs: Requirement[]): { ADDED: number; MODIFIED: number; REMOVED: number } {\n  const c = { ADDED: 0, MODIFIED: 0, REMOVED: 0 };\n  for (const r of reqs) {\n    if (r.kind === \"ADDED\") c.ADDED += 1;\n    else if (r.kind === \"MODIFIED\") c.MODIFIED += 1;\n    else if (r.kind === \"REMOVED\") c.REMOVED += 1;\n  }\n  return c;\n}\n\n/**\n * The vocabulary merge: each `features/<FEAT>/glossary/<term>.md` copied to\n * `glossary/<term>.md`.\n *\n * A WHOLE-FILE COPY, and there is nothing else it could be. A capability delta\n * is folded into a living document by the requirement algebra because the two\n * documents share identified parts; a term document has one part, and merging\n * two definitions of one word is not something a machine may attempt. So the\n * definition the author wrote in the feature IS the definition that lands,\n * verbatim — loam re-encodes it as UTF-8 through `readUtf8` and changes nothing\n * else, not even the trailing newline.\n *\n * CREATE-ONLY, which is why this loop has no other branch. A term the living\n * glossary already defines was refused at the gate (`glossary.term-exists`,\n * `core/glossary/delta.ts` has the reasoning), so by the time the plan runs\n * every path here is a file that does not exist. `planWrite` marks it\n * `exclusive`, so a race that created it between the gate and the commit fails\n * the write rather than overwriting somebody.\n *\n * AND IT SAYS SO OUT LOUD when it creates `glossary/`, exactly as\n * `planCapabilities` does for `capabilities/`: the directory's existence is the\n * axis's opt-in, so this merge changes what `loam validate --all` grades from\n * the next command on, and a merge that widens the fleet's own gate must not do\n * it silently.\n */\nexport async function planGlossary(\n  config: { docsDir: DocsDir },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const glossary = await featureGlossary(gated.featureDir);\n  if (!glossary.present || glossary.terms.length === 0) return;\n  // Asked BEFORE the loop, because the loop is what would create it.\n  const adopting = !existsSync(glossaryDir(config.docsDir));\n  for (const term of glossary.terms) {\n    plan.writes.push(planWrite(livingTermPath(config.docsDir, term.id), await readUtf8(term.path)));\n    say(`  glossary: ${term.id} — created glossary/${term.id}.md`);\n  }\n  if (adopting) {\n    say(`  glossary/ did not exist — this archive opts the fleet into the domain vocabulary, and \\`loam validate --all\\` grades it from now on`);\n  }\n}\n"]}