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

package/dist/commands/archive/plan/document/links.js

@@ -0,0 +1,284 @@
+/**
+ * Where every file of the feature will be once this archive lands — the half of
+ * the link rewrite that `core/links/parse.ts`'s `rebaseLinks` cannot know.
+ *
+ * THE DEFECT THIS CLOSES. The requirement merge has re-expressed a delta's
+ * relative links from the directory they were written in to the one they land
+ * in since the glossary axis shipped. But it re-expressed them against the
+ * target's OLD place, and the same archive moves the targets that sit inside
+ * the feature: a link from a delta to `features/<FEAT>/glossary/order.md` was
+ * rewritten faithfully into the living spec and resolved to nothing one rename
+ * later, when the term had been copied to `glossary/order.md` and the feature
+ * directory had gone to `features/archive/<FEAT>/`. Every such link was
+ * `link.unresolved` on the first `validate --all` after a clean archive — an
+ * error the feature gate could not see, because before the archive the link
+ * was correct.
+ *
+ * TWO RULES, and they are the archive's own moves rather than a guess:
+ *
+ * - A file the archive COPIES into the living tree — a glossary term, a flow,
+ *   a topology document — is cited at its living copy. That is the document
+ *   readers are meant to find, and the one `glossary.unlinked` counts a
+ *   citation of: a link left on the archived copy would resolve and still
+ *   leave the living term reading as a word nobody uses.
+ * - Every other file under the feature directory — its ADRs above all, the
+ *   intent, the deltas themselves — is cited where the feature now lives,
+ *   `features/archive/<FEAT>/`. Nothing else copies a feature ADR anywhere: it
+ *   records a decision taken for this change, and it stays with the change
+ *   (SCHEMA "Layout" says so beside the slot).
+ *
+ * Built per call from three directory walks — the glossary, the flows and the
+ * topology documents, the same walks `../specs.ts` and `../landscape.ts` make
+ * to copy them; a `Gated` field would be one more value the gate computes for
+ * a phase it does not own.
+ *
+ * THE OTHER TWO HALVES ARE THE LINKS NO MERGE CARRIES. The feature's own
+ * documents (`planFeatureLinks` below) stay in the feature and ride the rename,
+ * so their links out of it are one directory short the moment it lands. Every
+ * other document in the corpus (`planInboundLinks` below) stays where it is
+ * while the files it cites inside the feature move away from under it.
+ */
+import { dirname, resolve } from "node:path";
+import { repoPath } from "../../../../core/envelope/json.js";
+import { movedUnderVouch, parseFrontmatter, stringField } from "../../../../core/document/frontmatter.js";
+import { parseRequirements } from "../../../../core/document/parse.js";
+import { requirementDigest } from "../../../../core/document/spec.js";
+import { featureGlossary, livingTermPath } from "../../../../core/glossary/delta.js";
+import { allAuthoredDocuments, movedMarkdown } from "../../../../core/links/corpus.js";
+import { rebaseLinks } from "../../../../core/links/parse.js";
+import { inOrder } from "../../../../core/kernel/concurrency.js";
+import { acrossRename, isPathInside } from "../../../../core/kernel/path-safety.js";
+import { featuresDir, servicePathsAt } from "../../../../core/repo/paths.js";
+import { listServices } from "../../../../core/repo/repo.js";
+import { featureFlows, livingFlowPath } from "../../../../core/usecases/delta/flows.js";
+import { featureDeployments, livingDeploymentPath } from "../../../../core/deployment/delta.js";
+import { NotUtf8Error, planWrite, readUtf8 } from "../../../../core/staging/writes.js";
+export async function featureRetarget(docsDir, gated) {
+    const copies = new Map();
+    for (const term of (await featureGlossary(gated.featureDir)).terms) {
+        copies.set(resolve(term.path), resolve(livingTermPath(docsDir, term.id)));
+    }
+    for (const flow of await featureFlows(gated.featureDir)) {
+        copies.set(resolve(flow.path), resolve(livingFlowPath(docsDir, flow.rel)));
+    }
+    for (const doc of await featureDeployments(gated.featureDir)) {
+        copies.set(resolve(doc.path), resolve(livingDeploymentPath(docsDir, doc.rel)));
+    }
+    return (target) => copies.get(resolve(target)) ?? followsFeature(gated, target);
+}
+/**
+ * The feature's own markdown documents with their relative links re-expressed
+ * for `features/archive/<FEAT>/`, planned at their CURRENT paths so the swap
+ * lands before the rename carries them (`../../run.ts`).
+ *
+ * THE DEFECT THIS CLOSES. The archive is a directory rename, and every document
+ * that stays in the feature — the intent, its ADRs, the deltas, a capability
+ * delta, the archived copy of a term — kept links written one directory
+ * shallower than where they now sit: `../../services/x/spec.md` from
+ * `features/<FEAT>/intent.md` names `features/services/x/spec.md` once the
+ * intent is `features/archive/<FEAT>/intent.md`. Nothing grades an archived
+ * feature (`core/links/corpus.ts` says why), so nothing said so — but the
+ * living documents link INTO the archived feature's ADRs (`featureRetarget`
+ * above), and a reader who followed one landed on a decision whose own links
+ * were all off by one.
+ *
+ * ONE RULE, the rename's: a target inside the feature moves with it and every
+ * other target stays put — `subsystem move`'s rule for its own renames
+ * (`commands/subsystem/txn/links.ts`). So a link from the intent to its own
+ * ADR or its own glossary term is left exactly as written: the archived
+ * record keeps citing the archived copy, which is the text the feature was
+ * reviewed against, rather than being redirected to a living copy that will go
+ * on changing without it. Only the routes the rename broke are touched, and a
+ * link whose text still reaches its target keeps its spelling
+ * (`rebaseLinks`).
+ *
+ * The undo is the snapshot's, like every other write here: each rewritten
+ * document is a staged write, so its pre-image is parked and `loam unarchive`
+ * puts the authored bytes back (`core/staging/snapshot/snapshot.ts` says where
+ * it records them).
+ *
+ * A document that is not UTF-8 is left exactly as written, and the text
+ * output says so — `--json` has no key for it, and minting one for a document
+ * nothing grades was not worth a contract change. Every other read here would
+ * refuse it, but this one only corrects links, and refusing the archive over
+ * such a document would be the larger harm.
+ *
+ * Read with bounded concurrency and applied in input order (`inOrder`), as
+ * `subsystem move`'s rewrite reads its own: a large feature — one
+ * `loam migrate-openspec` filled with its legacy documents — is read in full
+ * under the lock.
+ */
+export async function planFeatureLinks(config, gated, planned, say) {
+    const { docsDir } = config;
+    const retarget = (target) => followsFeature(gated, target);
+    const read = await inOrder(await movedMarkdown(gated.featureDir), async (path) => {
+        try {
+            return { path, text: await readUtf8(path) };
+        }
+        catch (err) {
+            if (!(err instanceof NotUtf8Error))
+                throw err;
+            return { path, text: null };
+        }
+    });
+    const relinked = [];
+    for (const { path, text } of read) {
+        const lands = followsFeature(gated, path);
+        if (text === null) {
+            say(`  ⚠ ${repoPath(docsDir, lands)} is not UTF-8 — its links were left as written`);
+            continue;
+        }
+        const next = rebaseLinks(text, { from: dirname(path), to: dirname(lands), retarget });
+        if (next === text)
+            continue;
+        planned.writes.push(planWrite(path, next));
+        relinked.push(repoPath(docsDir, lands));
+    }
+    if (relinked.length === 0)
+        return;
+    say(`  feature documents: ${relinked.length} relinked for ${repoPath(docsDir, gated.archiveDest)}/`);
+    for (const path of relinked)
+        say(`      ${path}`);
+}
+/**
+ * Every other document in the link corpus whose links reach INTO the feature,
+ * re-expressed for where this archive leaves what they cite.
+ *
+ * THE DEFECT THIS CLOSES. Another change in flight builds on this one's
+ * decision (`../FEAT/adrs/0001-x.md` from its intent), or a living ADR cites
+ * the decision taken for it while the change is still open. Correct the moment
+ * before the archive, so no gate could say otherwise; `link.unresolved` the
+ * moment after, because the rename took the directory away from under the
+ * link. And no edit the author could make in advance would have helped: the
+ * archived path does not exist until the archive does. `subsystem move`
+ * rewrites the links into the directories it renames
+ * (`commands/subsystem/txn/links.ts`); this is the archive's rename owing the
+ * same correction.
+ *
+ * THE RULE IS `featureRetarget`'s, not the rename's. These documents are not
+ * the record of the change; they are the living corpus and the other changes
+ * in flight, read against the tree as it is. So a term the archive copies into
+ * `glossary/` is cited at the living copy — the one a reader is meant to find
+ * and the one `glossary.unlinked` counts — and everything that stays with the
+ * change, its ADRs and intent above all, is cited where the feature now lives.
+ * Only the routes into the feature change; every other link keeps its
+ * spelling (`rebaseLinks`).
+ *
+ * COMPOSED ONTO THE MERGE. A living spec the merge rewrites can cite the
+ * feature in its own narrative, and relinking the bytes on disk would plan a
+ * second write of its PRE-merge text — swapped after the merge's, it would
+ * undo the merge. So a document this plan already writes is relinked from the
+ * text the merge composed, and that one write is replaced in place.
+ *
+ * THE COSTS ARE SAID THE WAY THE MERGE SAYS ITS OWN. A rewritten route is still
+ * a changed byte. Under a vouch stamp it is `content.stale` until the owner
+ * re-vouches, so a vouched spec this moves joins `revouchOwed` exactly as one
+ * the merge moves does. Inside a living requirement it moves the digest a
+ * `Based-On:` pin holds, and the plan names the document. No git refusal of the
+ * kind `subsystem move` holds (`move-uncommitted`): archive never stages in
+ * git, and its undo is the snapshot — every write here is one of its rows, so
+ * `loam unarchive` puts the authored bytes back, a document edited since is
+ * `snapshot-stale` like any other, and one whose feature has been archived or
+ * removed since is left as it is (`commands/unarchive/restore.ts`).
+ *
+ * The two notes are the text output's alone — the walk that could not be made
+ * and the `Based-On:` cost. `--json` has no key for either: its `warnings` are
+ * coherence issues with codes, and a new key for an advisory the next
+ * `validate --all` grades in full was not worth a contract change. What an
+ * agent acts on is in the payload already: every relinked document is a `plan`
+ * row and every re-vouch it owes is on `revouchOwed`.
+ */
+export async function planInboundLinks(config, gated, planned, say) {
+    const { docsDir, fleet } = config;
+    let corpus;
+    try {
+        corpus = await allAuthoredDocuments(docsDir, fleet);
+    }
+    catch (err) {
+        // The gate enumerated this fleet already, so a walk that fails here is a
+        // tree `validate` will diagnose. The archive is not refused over a question
+        // it asks to keep the corpus readable — `subsystem move` decides the same —
+        // but it does not pretend the question was answered either.
+        say(`  ⚠ links INTO ${repoPath(docsDir, gated.featureDir)}/ were not checked — the fleet's documents could not be walked ` +
+            `(${err instanceof Error ? err.message : String(err)}); \`loam validate --all\` names any that broke.`);
+        return;
+    }
+    const retarget = await featureRetarget(docsDir, gated);
+    const vouchable = new Map();
+    for (const service of await listServices(docsDir, fleet)) {
+        const paths = servicePathsAt(service.dir);
+        vouchable.set(resolve(paths.spec), service.id);
+        vouchable.set(resolve(paths.archSpec), service.id);
+    }
+    const plannedAt = new Map(planned.writes.map((write, at) => [resolve(write.path), { at, write }]));
+    const seen = new Set();
+    const candidates = corpus.filter((path) => {
+        const key = resolve(path);
+        if (seen.has(key) || isPathInside(gated.featureDir, path))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const documents = await inOrder(candidates, async (path) => {
+        const composed = plannedAt.get(resolve(path));
+        if (composed !== undefined) {
+            // A delete or a Buffer is not text this rewrite may compose onto; no
+            // markdown planner hands over either.
+            const { content } = composed.write;
+            return { path, composed, text: typeof content === "string" ? content : null };
+        }
+        try {
+            return { path, composed, text: await readUtf8(path) };
+        }
+        catch {
+            // Absent (the corpus names every slot a service MAY fill) or not UTF-8,
+            // which `link.unreadable` already names: nothing loam could write back.
+            return { path, composed, text: null };
+        }
+    });
+    const pinned = (md) => parseRequirements(md).map(requirementDigest).join(",");
+    const relinked = [];
+    const notes = [];
+    for (const { path, composed, text } of documents) {
+        if (text === null)
+            continue;
+        const next = rebaseLinks(text, { from: dirname(path), to: dirname(path), retarget });
+        if (next === text)
+            continue;
+        // In place, at the index the merge's write already holds: nothing between
+        // here and the map above adds, removes or reorders a planned write.
+        if (composed === undefined)
+            planned.writes.push(planWrite(path, next));
+        else
+            planned.writes[composed.at] = { ...composed.write, content: next };
+        const where = repoPath(docsDir, path);
+        relinked.push(where);
+        // The merge's own question (`../specs.ts`), asked of the bytes about to be
+        // written — and once per document: a spec the merge already named is not
+        // owed a second re-vouch for the same commit.
+        const service = vouchable.get(resolve(path));
+        const fm = parseFrontmatter(next);
+        const named = planned.revouchOwed.some((owed) => resolve(owed.path) === resolve(path));
+        if (service !== undefined && !named && movedUnderVouch(fm, next)) {
+            planned.revouchOwed.push({ service, path, owner: stringField(fm, "owner") ?? null });
+        }
+        // Living documents only: a pin holds the digest of a LIVING requirement,
+        // so another feature's own delta text moving pins nothing.
+        if (!isPathInside(featuresDir(docsDir), path) && pinned(next) !== pinned(text)) {
+            notes.push(`${where}: links this archive rewrote sit inside requirements, so a feature in flight that pins one with Based-On: ` +
+                "reports delta.baseline-stale until `loam rebase` re-pins it.");
+        }
+    }
+    if (relinked.length === 0)
+        return;
+    say(`  links into the feature: ${relinked.length} document(s) relinked for ${repoPath(docsDir, gated.archiveDest)}/`);
+    for (const path of relinked)
+        say(`      ${path}`);
+    for (const note of notes)
+        say(`      note: ${note}`);
+}
+/** Where `target` will be once the feature directory has moved: its image under the archive when it is inside the feature, itself otherwise. */
+function followsFeature(gated, target) {
+    return acrossRename(target, gated.featureDir, gated.archiveDest);
+}
+//# sourceMappingURL=links.js.map

package/dist/commands/archive/plan/document/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/document/links.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Where every file of the feature will be once this archive lands — the half of\n * the link rewrite that `core/links/parse.ts`'s `rebaseLinks` cannot know.\n *\n * THE DEFECT THIS CLOSES. The requirement merge has re-expressed a delta's\n * relative links from the directory they were written in to the one they land\n * in since the glossary axis shipped. But it re-expressed them against the\n * target's OLD place, and the same archive moves the targets that sit inside\n * the feature: a link from a delta to `features/<FEAT>/glossary/order.md` was\n * rewritten faithfully into the living spec and resolved to nothing one rename\n * later, when the term had been copied to `glossary/order.md` and the feature\n * directory had gone to `features/archive/<FEAT>/`. Every such link was\n * `link.unresolved` on the first `validate --all` after a clean archive — an\n * error the feature gate could not see, because before the archive the link\n * was correct.\n *\n * TWO RULES, and they are the archive's own moves rather than a guess:\n *\n * - A file the archive COPIES into the living tree — a glossary term, a flow,\n *   a topology document — is cited at its living copy. That is the document\n *   readers are meant to find, and the one `glossary.unlinked` counts a\n *   citation of: a link left on the archived copy would resolve and still\n *   leave the living term reading as a word nobody uses.\n * - Every other file under the feature directory — its ADRs above all, the\n *   intent, the deltas themselves — is cited where the feature now lives,\n *   `features/archive/<FEAT>/`. Nothing else copies a feature ADR anywhere: it\n *   records a decision taken for this change, and it stays with the change\n *   (SCHEMA \"Layout\" says so beside the slot).\n *\n * Built per call from three directory walks — the glossary, the flows and the\n * topology documents, the same walks `../specs.ts` and `../landscape.ts` make\n * to copy them; a `Gated` field would be one more value the gate computes for\n * a phase it does not own.\n *\n * THE OTHER TWO HALVES ARE THE LINKS NO MERGE CARRIES. The feature's own\n * documents (`planFeatureLinks` below) stay in the feature and ride the rename,\n * so their links out of it are one directory short the moment it lands. Every\n * other document in the corpus (`planInboundLinks` below) stays where it is\n * while the files it cites inside the feature move away from under it.\n */\nimport { dirname, resolve } from \"node:path\";\nimport { repoPath } from \"../../../../core/envelope/json.js\";\nimport { movedUnderVouch, parseFrontmatter, stringField } from \"../../../../core/document/frontmatter.js\";\nimport { parseRequirements } from \"../../../../core/document/parse.js\";\nimport { requirementDigest } from \"../../../../core/document/spec.js\";\nimport { featureGlossary, livingTermPath } from \"../../../../core/glossary/delta.js\";\nimport { allAuthoredDocuments, movedMarkdown } from \"../../../../core/links/corpus.js\";\nimport { rebaseLinks } from \"../../../../core/links/parse.js\";\nimport { inOrder } from \"../../../../core/kernel/concurrency.js\";\nimport { acrossRename, isPathInside } from \"../../../../core/kernel/path-safety.js\";\nimport { featuresDir, servicePathsAt } from \"../../../../core/repo/paths.js\";\nimport { listServices } from \"../../../../core/repo/repo.js\";\nimport { featureFlows, livingFlowPath } from \"../../../../core/usecases/delta/flows.js\";\nimport { featureDeployments, livingDeploymentPath } from \"../../../../core/deployment/delta.js\";\nimport { NotUtf8Error, planWrite, readUtf8 } from \"../../../../core/staging/writes.js\";\nimport type { FleetContext } from \"../../../../core/fleet-context.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { Gated, Plan } from \"../state.js\";\n\n/** Absolute path in, the absolute path the same file will have after this archive out. */\nexport type Retarget = (target: string) => string;\n\nexport async function featureRetarget(docsDir: DocsDir, gated: Pick<Gated, \"featureDir\" | \"archiveDest\">): Promise<Retarget> {\n  const copies = new Map<string, string>();\n  for (const term of (await featureGlossary(gated.featureDir)).terms) {\n    copies.set(resolve(term.path), resolve(livingTermPath(docsDir, term.id)));\n  }\n  for (const flow of await featureFlows(gated.featureDir)) {\n    copies.set(resolve(flow.path), resolve(livingFlowPath(docsDir, flow.rel)));\n  }\n  for (const doc of await featureDeployments(gated.featureDir)) {\n    copies.set(resolve(doc.path), resolve(livingDeploymentPath(docsDir, doc.rel)));\n  }\n  return (target: string): string => copies.get(resolve(target)) ?? followsFeature(gated, target);\n}\n\n/**\n * The feature's own markdown documents with their relative links re-expressed\n * for `features/archive/<FEAT>/`, planned at their CURRENT paths so the swap\n * lands before the rename carries them (`../../run.ts`).\n *\n * THE DEFECT THIS CLOSES. The archive is a directory rename, and every document\n * that stays in the feature — the intent, its ADRs, the deltas, a capability\n * delta, the archived copy of a term — kept links written one directory\n * shallower than where they now sit: `../../services/x/spec.md` from\n * `features/<FEAT>/intent.md` names `features/services/x/spec.md` once the\n * intent is `features/archive/<FEAT>/intent.md`. Nothing grades an archived\n * feature (`core/links/corpus.ts` says why), so nothing said so — but the\n * living documents link INTO the archived feature's ADRs (`featureRetarget`\n * above), and a reader who followed one landed on a decision whose own links\n * were all off by one.\n *\n * ONE RULE, the rename's: a target inside the feature moves with it and every\n * other target stays put — `subsystem move`'s rule for its own renames\n * (`commands/subsystem/txn/links.ts`). So a link from the intent to its own\n * ADR or its own glossary term is left exactly as written: the archived\n * record keeps citing the archived copy, which is the text the feature was\n * reviewed against, rather than being redirected to a living copy that will go\n * on changing without it. Only the routes the rename broke are touched, and a\n * link whose text still reaches its target keeps its spelling\n * (`rebaseLinks`).\n *\n * The undo is the snapshot's, like every other write here: each rewritten\n * document is a staged write, so its pre-image is parked and `loam unarchive`\n * puts the authored bytes back (`core/staging/snapshot/snapshot.ts` says where\n * it records them).\n *\n * A document that is not UTF-8 is left exactly as written, and the text\n * output says so — `--json` has no key for it, and minting one for a document\n * nothing grades was not worth a contract change. Every other read here would\n * refuse it, but this one only corrects links, and refusing the archive over\n * such a document would be the larger harm.\n *\n * Read with bounded concurrency and applied in input order (`inOrder`), as\n * `subsystem move`'s rewrite reads its own: a large feature — one\n * `loam migrate-openspec` filled with its legacy documents — is read in full\n * under the lock.\n */\nexport async function planFeatureLinks(\n  config: { docsDir: DocsDir },\n  gated: Pick<Gated, \"featureDir\" | \"archiveDest\">,\n  planned: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { docsDir } = config;\n  const retarget = (target: string): string => followsFeature(gated, target);\n  const read = await inOrder(await movedMarkdown(gated.featureDir), async (path) => {\n    try {\n      return { path, text: await readUtf8(path) };\n    } catch (err) {\n      if (!(err instanceof NotUtf8Error)) throw err;\n      return { path, text: null };\n    }\n  });\n  const relinked: string[] = [];\n  for (const { path, text } of read) {\n    const lands = followsFeature(gated, path);\n    if (text === null) {\n      say(`  ⚠ ${repoPath(docsDir, lands)} is not UTF-8 — its links were left as written`);\n      continue;\n    }\n    const next = rebaseLinks(text, { from: dirname(path), to: dirname(lands), retarget });\n    if (next === text) continue;\n    planned.writes.push(planWrite(path, next));\n    relinked.push(repoPath(docsDir, lands));\n  }\n  if (relinked.length === 0) return;\n  say(`  feature documents: ${relinked.length} relinked for ${repoPath(docsDir, gated.archiveDest)}/`);\n  for (const path of relinked) say(`      ${path}`);\n}\n\n/**\n * Every other document in the link corpus whose links reach INTO the feature,\n * re-expressed for where this archive leaves what they cite.\n *\n * THE DEFECT THIS CLOSES. Another change in flight builds on this one's\n * decision (`../FEAT/adrs/0001-x.md` from its intent), or a living ADR cites\n * the decision taken for it while the change is still open. Correct the moment\n * before the archive, so no gate could say otherwise; `link.unresolved` the\n * moment after, because the rename took the directory away from under the\n * link. And no edit the author could make in advance would have helped: the\n * archived path does not exist until the archive does. `subsystem move`\n * rewrites the links into the directories it renames\n * (`commands/subsystem/txn/links.ts`); this is the archive's rename owing the\n * same correction.\n *\n * THE RULE IS `featureRetarget`'s, not the rename's. These documents are not\n * the record of the change; they are the living corpus and the other changes\n * in flight, read against the tree as it is. So a term the archive copies into\n * `glossary/` is cited at the living copy — the one a reader is meant to find\n * and the one `glossary.unlinked` counts — and everything that stays with the\n * change, its ADRs and intent above all, is cited where the feature now lives.\n * Only the routes into the feature change; every other link keeps its\n * spelling (`rebaseLinks`).\n *\n * COMPOSED ONTO THE MERGE. A living spec the merge rewrites can cite the\n * feature in its own narrative, and relinking the bytes on disk would plan a\n * second write of its PRE-merge text — swapped after the merge's, it would\n * undo the merge. So a document this plan already writes is relinked from the\n * text the merge composed, and that one write is replaced in place.\n *\n * THE COSTS ARE SAID THE WAY THE MERGE SAYS ITS OWN. A rewritten route is still\n * a changed byte. Under a vouch stamp it is `content.stale` until the owner\n * re-vouches, so a vouched spec this moves joins `revouchOwed` exactly as one\n * the merge moves does. Inside a living requirement it moves the digest a\n * `Based-On:` pin holds, and the plan names the document. No git refusal of the\n * kind `subsystem move` holds (`move-uncommitted`): archive never stages in\n * git, and its undo is the snapshot — every write here is one of its rows, so\n * `loam unarchive` puts the authored bytes back, a document edited since is\n * `snapshot-stale` like any other, and one whose feature has been archived or\n * removed since is left as it is (`commands/unarchive/restore.ts`).\n *\n * The two notes are the text output's alone — the walk that could not be made\n * and the `Based-On:` cost. `--json` has no key for either: its `warnings` are\n * coherence issues with codes, and a new key for an advisory the next\n * `validate --all` grades in full was not worth a contract change. What an\n * agent acts on is in the payload already: every relinked document is a `plan`\n * row and every re-vouch it owes is on `revouchOwed`.\n */\nexport async function planInboundLinks(\n  config: { docsDir: DocsDir; fleet: FleetContext },\n  gated: Pick<Gated, \"featureDir\" | \"archiveDest\">,\n  planned: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { docsDir, fleet } = config;\n  let corpus: string[];\n  try {\n    corpus = await allAuthoredDocuments(docsDir, fleet);\n  } catch (err) {\n    // The gate enumerated this fleet already, so a walk that fails here is a\n    // tree `validate` will diagnose. The archive is not refused over a question\n    // it asks to keep the corpus readable — `subsystem move` decides the same —\n    // but it does not pretend the question was answered either.\n    say(\n      `  ⚠ links INTO ${repoPath(docsDir, gated.featureDir)}/ were not checked — the fleet's documents could not be walked ` +\n        `(${err instanceof Error ? err.message : String(err)}); \\`loam validate --all\\` names any that broke.`,\n    );\n    return;\n  }\n  const retarget = await featureRetarget(docsDir, gated);\n  const vouchable = new Map<string, string>();\n  for (const service of await listServices(docsDir, fleet)) {\n    const paths = servicePathsAt(service.dir);\n    vouchable.set(resolve(paths.spec), service.id);\n    vouchable.set(resolve(paths.archSpec), service.id);\n  }\n  const plannedAt = new Map(planned.writes.map((write, at) => [resolve(write.path), { at, write }]));\n  const seen = new Set<string>();\n  const candidates = corpus.filter((path) => {\n    const key = resolve(path);\n    if (seen.has(key) || isPathInside(gated.featureDir, path)) return false;\n    seen.add(key);\n    return true;\n  });\n  const documents = await inOrder(candidates, async (path) => {\n    const composed = plannedAt.get(resolve(path));\n    if (composed !== undefined) {\n      // A delete or a Buffer is not text this rewrite may compose onto; no\n      // markdown planner hands over either.\n      const { content } = composed.write;\n      return { path, composed, text: typeof content === \"string\" ? content : null };\n    }\n    try {\n      return { path, composed, text: await readUtf8(path) };\n    } catch {\n      // Absent (the corpus names every slot a service MAY fill) or not UTF-8,\n      // which `link.unreadable` already names: nothing loam could write back.\n      return { path, composed, text: null };\n    }\n  });\n  const pinned = (md: string): string => parseRequirements(md).map(requirementDigest).join(\",\");\n  const relinked: string[] = [];\n  const notes: string[] = [];\n  for (const { path, composed, text } of documents) {\n    if (text === null) continue;\n    const next = rebaseLinks(text, { from: dirname(path), to: dirname(path), retarget });\n    if (next === text) continue;\n    // In place, at the index the merge's write already holds: nothing between\n    // here and the map above adds, removes or reorders a planned write.\n    if (composed === undefined) planned.writes.push(planWrite(path, next));\n    else planned.writes[composed.at] = { ...composed.write, content: next };\n    const where = repoPath(docsDir, path);\n    relinked.push(where);\n    // The merge's own question (`../specs.ts`), asked of the bytes about to be\n    // written — and once per document: a spec the merge already named is not\n    // owed a second re-vouch for the same commit.\n    const service = vouchable.get(resolve(path));\n    const fm = parseFrontmatter(next);\n    const named = planned.revouchOwed.some((owed) => resolve(owed.path) === resolve(path));\n    if (service !== undefined && !named && movedUnderVouch(fm, next)) {\n      planned.revouchOwed.push({ service, path, owner: stringField(fm, \"owner\") ?? null });\n    }\n    // Living documents only: a pin holds the digest of a LIVING requirement,\n    // so another feature's own delta text moving pins nothing.\n    if (!isPathInside(featuresDir(docsDir), path) && pinned(next) !== pinned(text)) {\n      notes.push(\n        `${where}: links this archive rewrote sit inside requirements, so a feature in flight that pins one with Based-On: ` +\n          \"reports delta.baseline-stale until `loam rebase` re-pins it.\",\n      );\n    }\n  }\n  if (relinked.length === 0) return;\n  say(`  links into the feature: ${relinked.length} document(s) relinked for ${repoPath(docsDir, gated.archiveDest)}/`);\n  for (const path of relinked) say(`      ${path}`);\n  for (const note of notes) say(`      note: ${note}`);\n}\n\n/** Where `target` will be once the feature directory has moved: its image under the archive when it is inside the feature, itself otherwise. */\nfunction followsFeature(gated: Pick<Gated, \"featureDir\" | \"archiveDest\">, target: string): string {\n  return acrossRename(target, gated.featureDir, gated.archiveDest);\n}\n"]}

package/dist/commands/archive/plan/document/run.js

@@ -0,0 +1,136 @@
+/**
+ * The in-place half of a requirement merge: a living document that already
+ * exists has its requirements RUN rewritten, and nothing else.
+ *
+ * Moved out of `../specs.ts` when that module took on what a CREATED document
+ * says (`./head.ts`) and where a merged link points (`./links.ts`): the three
+ * are the document-level questions a requirement merge answers, and the merge
+ * loop itself is what is left beside the contract and landscape planners.
+ */
+import { parseRequirements, splitRequirementsSection } from "../../../../core/document/parse.js";
+import { serializeRequirements } from "../../../../core/document/spec.js";
+/**
+ * Rewrite ONLY what the delta touched inside a living spec's requirements run.
+ * 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. `living` must be every living requirement — the gate's
+ * stray guard refuses any document whose requirements sit outside the section,
+ * using the same heading definition, before this output is ever written.
+ *
+ * Inside the run the unit is one requirement, and an untouched one is written
+ * back as its raw slice (`spliceRun`). The whole run used to be re-serialized,
+ * and `serializeRequirements` writes a blank line under every
+ * `### Requirement:` heading — so a living spec written without one, the shape
+ * the adopt brief's own examples taught, had that line inserted under every
+ * requirement the feature never mentioned. The diff, the vouch pack and the
+ * re-vouch all widened from the delta to the whole section.
+ *
+ * Exported for `../specs.ts`, which calls it for both corpora, and for
+ * test/archive.test.ts: the slice-to-requirement join (`verbatimSlices`) can
+ * only be handed a disagreeing pair directly, because the gate refuses every
+ * document that would produce one through the CLI.
+ */
+export function rewriteRequirementsRun(text, living, 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)}`;
+    if (s.run !== "")
+        return s.head + spliceRun(s, living, merged) + s.tail;
+    // The section held no requirements yet: head and tail are raw slices, and the
+    // glue supplies the blank lines the author never had reason to write.
+    const headGlue = s.head.endsWith("\n\n") ? "" : s.head.endsWith("\n") ? "\n" : "\n\n";
+    const tailGlue = s.tail === "" ? "" : "\n";
+    return s.head + headGlue + serializeRequirements(merged) + tailGlue + s.tail;
+}
+/** The line breaks (and blank lines) a slice ends with — what separates it from whatever follows. */
+const TRAILING_BREAKS = /(?:\r?\n[ \t]*)*$/;
+/**
+ * The merged run: every living requirement the delta left alone as its raw
+ * slice, every one it added or replaced serialized, in `merged`'s order.
+ *
+ * Keyed on object identity, which `applyRequirementDelta` keeps for exactly the
+ * requirements it did not touch — so there is no second reading here of what
+ * the delta changed, and no way for the splice and the algebra to disagree.
+ * Which slice belongs to which living requirement is `verbatimSlices`' join.
+ *
+ * Prose BETWEEN requirements rides in the slice of the requirement above it,
+ * which is where parseRequirements attributes it too: it survives verbatim
+ * beside an untouched requirement and goes with a replaced one, as it always
+ * did — a MODIFIED carries its full new text.
+ */
+function spliceRun(section, living, merged) {
+    const verbatim = verbatimSlices(section.requirements, living);
+    let out = "";
+    let previousVerbatim = true;
+    for (const requirement of merged) {
+        const raw = verbatim.get(requirement);
+        // Two untouched neighbours keep whatever the author put between them. Next
+        // to a serialized requirement the canonical blank line is ADDED after the
+        // untouched text, never by rewriting it.
+        if (out !== "" && (raw === undefined || !previousVerbatim))
+            out = withBlankLine(out);
+        out += raw ?? serializeRequirements([requirement]);
+        previousVerbatim = raw !== undefined;
+    }
+    if (out === "")
+        return "";
+    // The run ends as it ended: whatever separated the old last requirement from
+    // the next heading (or EOF) now follows the new last one — and at least a
+    // newline when a merged requirement lands where the file used to stop without one.
+    const ending = section.run.slice(section.run.search(TRAILING_BREAKS));
+    const body = out.slice(0, out.search(TRAILING_BREAKS));
+    return body + (ending === "" && merged.at(-1) !== living.at(-1) ? "\n" : ending);
+}
+/** A requirement's identity as the merge selects it: `Requirement-ID:` when authored, the exact heading otherwise. */
+const identity = (r) => (r.id === undefined ? `name:${r.name}` : `id:${r.id}`);
+/**
+ * Each living requirement's raw slice, joined on its IDENTITY — the slice read
+ * back through the same parser that produced `living`, so a slice can only
+ * land in place of the requirement it actually is.
+ *
+ * The join used to be by position, guarded by a count. The two walks agree in
+ * order today (one heading-and-fence definition, core/document/parse.ts, and
+ * the gate's stray guard refusing any requirement outside the section), but
+ * nothing declared that, and equal counts paired differently would have written
+ * one requirement's bytes where another belongs — under its vouch stamp, with
+ * nothing to say so.
+ *
+ * Fails closed to the empty map, which serializes every requirement — the old
+ * whole-run rewrite, still a correct merge and only a wider diff: when the
+ * counts differ, when a slice does not read as exactly one requirement, when
+ * two slices claim one identity, or when a living requirement finds no slice
+ * of its own.
+ */
+function verbatimSlices(slices, living) {
+    const none = new Map();
+    if (slices.length !== living.length)
+        return none;
+    const byIdentity = new Map();
+    for (const slice of slices) {
+        const [only, ...more] = parseRequirements(slice);
+        if (only === undefined || more.length > 0 || byIdentity.has(identity(only)))
+            return none;
+        byIdentity.set(identity(only), slice);
+    }
+    const verbatim = new Map();
+    for (const requirement of living) {
+        const slice = byIdentity.get(identity(requirement));
+        if (slice === undefined)
+            return none;
+        // Taken once: a second living requirement of the same identity finds nothing.
+        byIdentity.delete(identity(requirement));
+        verbatim.set(requirement, slice);
+    }
+    return verbatim;
+}
+/** `text` ending in a blank line: line breaks appended to make one, nothing rewritten. */
+function withBlankLine(text) {
+    const breaks = text.slice(text.search(TRAILING_BREAKS)).split("\n").length - 1;
+    return breaks >= 2 ? text : text + "\n".repeat(2 - breaks);
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/archive/plan/document/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/document/run.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The in-place half of a requirement merge: a living document that already\n * exists has its requirements RUN rewritten, and nothing else.\n *\n * Moved out of `../specs.ts` when that module took on what a CREATED document\n * says (`./head.ts`) and where a merged link points (`./links.ts`): the three\n * are the document-level questions a requirement merge answers, and the merge\n * loop itself is what is left beside the contract and landscape planners.\n */\nimport { parseRequirements, splitRequirementsSection } from \"../../../../core/document/parse.js\";\nimport { serializeRequirements, type Requirement } from \"../../../../core/document/spec.js\";\n\n/**\n * Rewrite ONLY what the delta touched inside a living spec's requirements run.\n * Byte-for-byte preserved: everything before the first requirement inside\n * `## Requirements` (the intro, the heading line, prose under the heading) and\n * everything from the section's end onward (the next `## ` heading to EOF) —\n * the old cut was a substring `indexOf(\"\\n## Requirements\")`, a prefix match\n * that also hit `## Requirements Extra` and silently destroyed every section\n * after the requirements. `living` must be every living requirement — the gate'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 *\n * Inside the run the unit is one requirement, and an untouched one is written\n * back as its raw slice (`spliceRun`). The whole run used to be re-serialized,\n * and `serializeRequirements` writes a blank line under every\n * `### Requirement:` heading — so a living spec written without one, the shape\n * the adopt brief's own examples taught, had that line inserted under every\n * requirement the feature never mentioned. The diff, the vouch pack and the\n * re-vouch all widened from the delta to the whole section.\n *\n * Exported for `../specs.ts`, which calls it for both corpora, and for\n * test/archive.test.ts: the slice-to-requirement join (`verbatimSlices`) can\n * only be handed a disagreeing pair directly, because the gate refuses every\n * document that would produce one through the CLI.\n */\nexport function rewriteRequirementsRun(text: string, living: Requirement[], 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  if (s.run !== \"\") return s.head + spliceRun(s, living, merged) + s.tail;\n  // The section held no requirements yet: head and tail are raw slices, and the\n  // glue supplies the blank lines the author never had reason to write.\n  const headGlue = s.head.endsWith(\"\\n\\n\") ? \"\" : s.head.endsWith(\"\\n\") ? \"\\n\" : \"\\n\\n\";\n  const tailGlue = s.tail === \"\" ? \"\" : \"\\n\";\n  return s.head + headGlue + serializeRequirements(merged) + tailGlue + s.tail;\n}\n\n/** The line breaks (and blank lines) a slice ends with — what separates it from whatever follows. */\nconst TRAILING_BREAKS = /(?:\\r?\\n[ \\t]*)*$/;\n\n/**\n * The merged run: every living requirement the delta left alone as its raw\n * slice, every one it added or replaced serialized, in `merged`'s order.\n *\n * Keyed on object identity, which `applyRequirementDelta` keeps for exactly the\n * requirements it did not touch — so there is no second reading here of what\n * the delta changed, and no way for the splice and the algebra to disagree.\n * Which slice belongs to which living requirement is `verbatimSlices`' join.\n *\n * Prose BETWEEN requirements rides in the slice of the requirement above it,\n * which is where parseRequirements attributes it too: it survives verbatim\n * beside an untouched requirement and goes with a replaced one, as it always\n * did — a MODIFIED carries its full new text.\n */\nfunction spliceRun(\n  section: { run: string; requirements: string[] },\n  living: Requirement[],\n  merged: Requirement[],\n): string {\n  const verbatim = verbatimSlices(section.requirements, living);\n  let out = \"\";\n  let previousVerbatim = true;\n  for (const requirement of merged) {\n    const raw = verbatim.get(requirement);\n    // Two untouched neighbours keep whatever the author put between them. Next\n    // to a serialized requirement the canonical blank line is ADDED after the\n    // untouched text, never by rewriting it.\n    if (out !== \"\" && (raw === undefined || !previousVerbatim)) out = withBlankLine(out);\n    out += raw ?? serializeRequirements([requirement]);\n    previousVerbatim = raw !== undefined;\n  }\n  if (out === \"\") return \"\";\n  // The run ends as it ended: whatever separated the old last requirement from\n  // the next heading (or EOF) now follows the new last one — and at least a\n  // newline when a merged requirement lands where the file used to stop without one.\n  const ending = section.run.slice(section.run.search(TRAILING_BREAKS));\n  const body = out.slice(0, out.search(TRAILING_BREAKS));\n  return body + (ending === \"\" && merged.at(-1) !== living.at(-1) ? \"\\n\" : ending);\n}\n\n/** A requirement's identity as the merge selects it: `Requirement-ID:` when authored, the exact heading otherwise. */\nconst identity = (r: Pick<Requirement, \"id\" | \"name\">): string => (r.id === undefined ? `name:${r.name}` : `id:${r.id}`);\n\n/**\n * Each living requirement's raw slice, joined on its IDENTITY — the slice read\n * back through the same parser that produced `living`, so a slice can only\n * land in place of the requirement it actually is.\n *\n * The join used to be by position, guarded by a count. The two walks agree in\n * order today (one heading-and-fence definition, core/document/parse.ts, and\n * the gate's stray guard refusing any requirement outside the section), but\n * nothing declared that, and equal counts paired differently would have written\n * one requirement's bytes where another belongs — under its vouch stamp, with\n * nothing to say so.\n *\n * Fails closed to the empty map, which serializes every requirement — the old\n * whole-run rewrite, still a correct merge and only a wider diff: when the\n * counts differ, when a slice does not read as exactly one requirement, when\n * two slices claim one identity, or when a living requirement finds no slice\n * of its own.\n */\nfunction verbatimSlices(slices: string[], living: Requirement[]): Map<Requirement, string> {\n  const none = new Map<Requirement, string>();\n  if (slices.length !== living.length) return none;\n  const byIdentity = new Map<string, string>();\n  for (const slice of slices) {\n    const [only, ...more] = parseRequirements(slice);\n    if (only === undefined || more.length > 0 || byIdentity.has(identity(only))) return none;\n    byIdentity.set(identity(only), slice);\n  }\n  const verbatim = new Map<Requirement, string>();\n  for (const requirement of living) {\n    const slice = byIdentity.get(identity(requirement));\n    if (slice === undefined) return none;\n    // Taken once: a second living requirement of the same identity finds nothing.\n    byIdentity.delete(identity(requirement));\n    verbatim.set(requirement, slice);\n  }\n  return verbatim;\n}\n\n/** `text` ending in a blank line: line breaks appended to make one, nothing rewritten. */\nfunction withBlankLine(text: string): string {\n  const breaks = text.slice(text.search(TRAILING_BREAKS)).split(\"\\n\").length - 1;\n  return breaks >= 2 ? text : text + \"\\n\".repeat(2 - breaks);\n}\n"]}

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

@@ -20,7 +20,6 @@ import { readUtf8 } from "../../../core/staging/writes.js";
 import { loadFile } from "../../../core/c4/likec4.js";
 import { archiveDir as archiveRoot, featurePaths, featureSpecPaths, SPEC_AXES } from "../../../core/repo/paths.js";
 import { livingCapabilityPaths } from "../../../core/repo/authored/paths.js";
-import { featureCapabilityDeltas } from "../../../core/capabilities/delta/tree.js";
 import { locateServicePaths } from "../../../core/repo/service-target.js";
 import { featureSpecServices, missingFeatureMessage, resolveFeature } from "../../../core/repo/repo.js";
 import { featureCoherence } from "../../../core/coherence/coherence.js";
@@ -31,7 +30,7 @@ import { refuseFindings, refuseJson, sayRecovery } from "./refusal.js";
 import {} from "./state.js";
 export async function gate(config, featureId, opts, say) {
     const json = opts.json === true;
-    const dryRun = opts.dryRun === true;
+    // Before anything is read: a commit that was killed between two renames left
     // the living docs half-written, and every other command in loam would have
     // planned against them as if they were the truth. Under the same lock, so the
     // repair cannot race a writer. It refuses when the half-merged files have been
@@ -62,9 +61,7 @@ export async function gate(config, featureId, opts, say) {
     // no-context path `core/coherence/declared.ts` already documents paying for
     // the arch delta — so this is not the run's only walk, only the one every
     // phase downstream of the gate shares.
-    const capabilityDeltas = (config.fleet === undefined
-        ? await featureCapabilityDeltas(featureDir)
-        : await config.fleet.featureCapabilityDeltas(featureDir)).docs;
+    const capabilityDeltas = (await config.fleet.featureCapabilityDeltas(featureDir)).docs;
     // A `specs/<svc>/` whose NAME is not a legal service id, refused before
     // anything joins that name into a path: the conflict scan below probes
     // `services/<svc>/<axis>` with it, and the requirements merge would
@@ -104,7 +101,7 @@ export async function gate(config, featureId, opts, say) {
     // Git conflict markers in a LIVING document this merge would rewrite, before
     // anything else is asked of it. Both sides of somebody's merge are in the
     // file, so nothing it says is anyone's text — and the requirements rewrite
-    // deletes whichever marker lines fall inside the section it owns, turning a
+    // deletes whichever marker lines fall inside a requirement it replaces, turning a
     // conflict anyone can see into a file nobody can tell is wrong. Checked ahead
     // of the coherence gate for `inspectLandscape`'s reason: a conflicted
     // document parses, so every verdict downstream of it is an opinion about half
@@ -142,19 +139,23 @@ export async function gate(config, featureId, opts, say) {
     // the rest. The register is issue.ts's `approveOverrides` — the same data
     // the `overridable` key in the envelope is resolved from — never a code
     // string spelled here, because two spellings of "what the flag moves" would
-    // drift. Today the register holds one code: a `metadata { service }` binding
-    // the id grammar refuses, anywhere in a tagged element's spliced block. The
-    // landscape merge would splice that name into the living map verbatim, and
-    // the new-service scan would probe `services/<binding>/` with it — a '../'
-    // collapses the probe out of services/ altogether — so the refusal is a
-    // mechanical fact about the path the name becomes, not a judgment about the
-    // feature. Same doctrine as the illegal-specs-name refusal above; the dry
-    // run is gated the same way, and the --json envelope stays not-coherent
-    // with every issue attached, exactly like the overridable branch below, so
-    // a consumer branches on the code and not on which refusal path fired.
+    // drift. What the register HOLDS has grown: it began as one code (a
+    // `metadata { service }` binding the id grammar refuses, where the merge
+    // would splice the name into the living map verbatim and probe
+    // `services/<binding>/` with it) and now holds the create-only collisions of
+    // every whole-file axis besides. They share the doctrine and nothing else —
+    // each is a mechanical fact about what the merge would write, never a
+    // judgment about the feature — which is why the message below counts them
+    // and lets each issue say its own sentence.
+    //
+    // IT USED TO NAME BINDINGS, and had been wrong for every other code in the
+    // register since the use-case slot landed: a feature whose flow collided
+    // with a living one was refused with "1 element binding(s) name an illegal
+    // service id", about a feature that binds nothing. A refusal headline that
+    // describes the wrong breach sends its reader to the wrong file first.
     const nonOverridable = issues.filter((i) => !approveOverrides(i));
     if (nonOverridable.length > 0) {
-        const msg = `archive ${id} — BLOCKED: ${nonOverridable.length} element binding(s) name an illegal service id; --approve does not override this`;
+        const msg = `archive ${id} — BLOCKED: ${nonOverridable.length} issue(s) --approve does not override; each names what the merge would write`;
         if (json) {
             refuseJson("not-coherent", msg, issues, `features/${dirName}`);
             return null;
@@ -166,7 +167,9 @@ export async function gate(config, featureId, opts, say) {
         // line says which of the marks the flag cannot move.
         for (const i of issues)
             console.error(`  ${SEVERITY_MARK[i.severity]} ${i.message}`);
-        console.error(`\nOf these, --approve does not override the ${nonOverridable.length} illegal binding(s) — the merge would write a name loam can never resolve into services/, mechanically. Fix the binding(s); the other issues gate as usual.`);
+        console.error(`\nOf these, --approve does not override ${nonOverridable.length}: ${[...new Set(nonOverridable.map((i) => i.code))].sort().join(", ")}. ` +
+            "Each is a mechanical fact about what the merge would write — a name loam cannot resolve, or a file it would replace wholesale — not a judgement the flag can move. " +
+            "Fix those; the other issues gate as usual.");
         sayExplain("not-coherent");
         process.exitCode = 1;
         return null;
@@ -298,7 +301,6 @@ export async function gate(config, featureId, opts, say) {
         fail(json, "archive-exists", `archive ${id} — BLOCKED: features/archive/${dirName} already exists. Remove or rename it, then re-run.`);
         return null;
     }
-    say(`archive ${id}${dryRun ? "  (dry run)" : ""}\n`);
     return {
         id,
         dirName,