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

package/dist/commands/explore.js

@@ -0,0 +1,195 @@
+import { loadConfig } from "../core/config.js";
+import { explore } from "../core/explore.js";
+import { FleetContext } from "../core/fleet-context.js";
+import { emitJson, fail, reportNoConfig } from "../core/json.js";
+import { assertServiceId, featureIdProblem, InvalidIdError } from "../core/ids.js";
+import { DocsRepoUnavailableError } from "../core/repo.js";
+import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from "./docs-repo-gate.js";
+import { plural } from "./format.js";
+/**
+ * The feature id in the suggested command line when `--as` did not say.
+ *
+ * It has to satisfy the feature-id grammar, because `scaffold` is documented as
+ * the literal `loam new` line and AGENTS.md's rule is that an instruction loam
+ * prints and loam refuses is a defect. `FEAT-NNN` — the obvious placeholder —
+ * is exactly that: `loam new FEAT-NNN` comes back `invalid-option`, so the last
+ * line of every default run was a command that could not be run.
+ *
+ * `FEAT-000` parses and is still unmistakably a placeholder, which buys the
+ * property the refusal was standing in for: an agent that pastes it unedited
+ * gets a feature called FEAT-000, visible in `loam list` within seconds and
+ * deletable with `git rm -r`. A plausible id (FEAT-1) would not be.
+ */
+const PLACEHOLDER = "FEAT-000";
+export function registerExplore(program) {
+    program
+        .command("explore")
+        .argument("[service...]", "service ids the change starts from")
+        .description("Read the fleet around a change nobody has written down yet — writes nothing")
+        .option("--json", "emit the machine contract instead of the human view")
+        .option("--op <operationId>", "seed from an operation instead of a service; repeatable", (value, prev = []) => [...prev, value])
+        .option("--as <FEAT>", `feature id for the suggested command line (default: ${PLACEHOLDER})`)
+        .action(async (serviceArgs, opts) => {
+        const json = opts.json === true;
+        const services = serviceArgs ?? [];
+        const operations = opts.op ?? [];
+        // `--as` is interpolated into the `loam new` line this command prints
+        // under `next:` and returns as `scaffold`, and `loam-feature` teaches an
+        // agent to pass `$1` straight into it. Unchecked, `explore` hands back a
+        // command `loam new` then refuses — loam instructing an agent to run
+        // something loam rejects, which is the one thing the printed-command
+        // guard exists to prevent and the one shape it cannot see, because it
+        // reads literal source strings and this line is assembled from argv.
+        // Same grammar as `new`'s, from core/ids.ts, so the two cannot disagree.
+        if (opts.as !== undefined) {
+            const problem = featureIdProblem(opts.as, "feature id for --as");
+            if (problem !== null) {
+                fail(json, "invalid-option", problem);
+                return;
+            }
+        }
+        if (services.length === 0 && operations.length === 0) {
+            fail(json, "invalid-option", "Nothing to explore from. Name at least one service, or pass --op <operationId>. " +
+                "`loam list services` is the fleet; `loam show <service>` is one of them.");
+            return;
+        }
+        // Rule 6 in docs/DESIGN.md: a raw argv string that reaches a path join is
+        // guarded at the command boundary. Every id here reaches `servicePaths`.
+        // Before `loadConfig`, exactly as `loam new` guards its `--touches` list:
+        // the grammar is a fact about the argument, not about the repository, so
+        // an unusable id should answer the same whether or not you are standing
+        // in a wired repo.
+        //
+        // A seed naming a service that does not EXIST is fine and reported as
+        // `unknown` — the feature may be introducing it — but one that could not
+        // be a service directory at all is a typo, not an intention.
+        try {
+            for (const id of services)
+                assertServiceId(id, "service");
+        }
+        catch (err) {
+            if (!(err instanceof InvalidIdError))
+                throw err;
+            fail(json, "invalid-option", err.message);
+            return;
+        }
+        const config = await loadConfig();
+        if (!config) {
+            reportNoConfig(json);
+            return;
+        }
+        const { docsDir } = config;
+        // `services`, not `docs`: every answer here is a statement about the
+        // fleet, and an empty ring read out of a directory that is not a docs
+        // repo says "nothing calls this service" about a repo nobody looked in.
+        if (!docsRepoReady(json, docsDir, "services"))
+            return;
+        try {
+            const result = await explore({
+                docsDir,
+                services,
+                operations,
+                featureId: opts.as ?? PLACEHOLDER,
+                context: new FleetContext(),
+            });
+            if (json) {
+                emitJson({ command: "explore", docsDir, ...result });
+                return;
+            }
+            print(result);
+        }
+        catch (err) {
+            if (err instanceof DocsRepoUnavailableError) {
+                reportDocsRepoError(json, err);
+                return;
+            }
+            // The scan is all-or-nothing — it reads every seed's contract to build
+            // one table — so the honest answer to an unreadable file is a refusal
+            // naming the path, not a ring with a silent hole in it.
+            reportRepositoryUnavailable(json, err, "the exploration would be missing a service", docsDir);
+        }
+    });
+}
+/* ------------------------------------------------------------------ */
+function print(r) {
+    if (!r.landscape.present || !r.landscape.parses) {
+        // Said first and without hedging: with no readable map there IS no ring,
+        // and a reader who takes the empty neighbour list at face value concludes
+        // the change is contained when nothing checked that.
+        const why = r.landscape.present ? "does not parse" : "does not exist";
+        console.log(`! architecture/landscape.likec4 ${why} — no neighbour below is derived, and none is missing either\n`);
+    }
+    for (const s of r.services) {
+        console.log(`${s.id}   ${label(s)}`);
+        if (!s.known) {
+            // Two different facts wear the same absence. A SEED nobody typed by
+            // accident is a service the feature introduces; one typed by accident is
+            // a typo, and the near-miss list is what separates them. A neighbour is
+            // neither — the fleet map drew an edge to something with no
+            // `services/<id>/`, which is usually an external system and occasionally
+            // a service nobody has adopted. Saying "typo" about that one sends a
+            // reader looking for a mistake they did not make.
+            const near = r.unknown.find((u) => u.id === s.id)?.nearest ?? [];
+            const why = s.reason === "seed"
+                ? "the feature introduces it, or the id is a typo"
+                : "an external system, or a service nobody has adopted";
+            console.log(`    no services/${s.id}/ — ${why}` +
+                (near.length > 0 ? `; closest existing: ${near.join(", ")}` : ""));
+        }
+        else {
+            if (s.missing.length > 0)
+                console.log(`    missing: ${s.missing.join(", ")}`);
+            if (!s.modelled)
+                console.log(`    not in the fleet map — no edge into it can be checked`);
+            // Said before `exposes`, and said at all: an unreadable contract exposes
+            // an empty list, and printing nothing there reads as "this service offers
+            // no endpoints" — the answer that turns a MODIFIED requirement into an
+            // ADDED one.
+            if (s.openapi.unreadable) {
+                console.log(`    ! openapi.yaml does not parse — nothing here lists what ${s.id} exposes`);
+                if (s.openapi.error !== undefined)
+                    console.log(`      ${s.openapi.error}`);
+            }
+            else if (s.operations.length > 0) {
+                console.log(`    exposes: ${s.operations.join(", ")}`);
+            }
+        }
+        for (const e of s.inbound)
+            console.log(`    ← ${e.service}${edgeNote(e.op, e.title)}`);
+        for (const e of s.outbound)
+            console.log(`    → ${e.service}${edgeNote(e.op, e.title)}`);
+        console.log("");
+    }
+    if (r.unresolvedOperations.length > 0) {
+        console.log(`! no living contract defines ${r.unresolvedOperations.join(", ")} — ` +
+            `the feature is adding ${r.unresolvedOperations.length === 1 ? "it" : "them"}, or the id is wrong\n`);
+    }
+    if (r.neighbours.length > 0) {
+        // The whole point of the command, so it is stated as a question rather than
+        // a list: these are candidates for --touches, and loam does not know which
+        // of them this change actually touches.
+        console.log(`${plural(r.neighbours.length, "neighbour")} one hop out: ${r.neighbours.join(", ")}`);
+        console.log("  weigh each one — loam knows they are connected, not whether you change them\n");
+    }
+    if (r.overlaps.length > 0) {
+        console.log("already in flight over this ground");
+        for (const o of r.overlaps)
+            console.log(`  ${o.feature}  ${o.services.join(", ")}`);
+        console.log("  `loam dependencies` says which must archive first, and what no ordering fixes\n");
+    }
+    console.log(`next: ${r.scaffold}`);
+}
+function label(s) {
+    const where = s.reason === "seed" ? "seed" : s.reason === "calls-seed" ? "calls a seed" : "called by a seed";
+    // `known`, matching the branch in `print` — not `maturity === null`. The two
+    // are set together and cannot disagree today, but discriminating on different
+    // fields for the same question is how they start to: a reader fixing one
+    // branch has no reason to look at the other.
+    return s.known ? `${where} · ${s.maturity}` : `${where} · not in the docs repo`;
+}
+function edgeNote(op, title) {
+    if (op !== null)
+        return `  ${op}`;
+    return title !== null ? `  "${title}"` : "";
+}
+//# sourceMappingURL=explore.js.map

package/dist/commands/explore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore.js","sourceRoot":"","sources":["../../src/commands/explore.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { loadConfig } from \"../core/config.js\";\nimport { explore, type Exploration, type ExploreService } from \"../core/explore.js\";\nimport { FleetContext } from \"../core/fleet-context.js\";\nimport { emitJson, fail, reportNoConfig } from \"../core/json.js\";\nimport { assertServiceId, featureIdProblem, InvalidIdError } from \"../core/ids.js\";\nimport { DocsRepoUnavailableError } from \"../core/repo.js\";\nimport { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from \"./docs-repo-gate.js\";\nimport { plural } from \"./format.js\";\n\n/**\n * The feature id in the suggested command line when `--as` did not say.\n *\n * It has to satisfy the feature-id grammar, because `scaffold` is documented as\n * the literal `loam new` line and AGENTS.md's rule is that an instruction loam\n * prints and loam refuses is a defect. `FEAT-NNN` — the obvious placeholder —\n * is exactly that: `loam new FEAT-NNN` comes back `invalid-option`, so the last\n * line of every default run was a command that could not be run.\n *\n * `FEAT-000` parses and is still unmistakably a placeholder, which buys the\n * property the refusal was standing in for: an agent that pastes it unedited\n * gets a feature called FEAT-000, visible in `loam list` within seconds and\n * deletable with `git rm -r`. A plausible id (FEAT-1) would not be.\n */\nconst PLACEHOLDER = \"FEAT-000\";\n\ninterface ExploreOptions {\n  json?: boolean;\n  op?: string[];\n  as?: string;\n}\n\nexport function registerExplore(program: Command): void {\n  program\n    .command(\"explore\")\n    .argument(\"[service...]\", \"service ids the change starts from\")\n    .description(\"Read the fleet around a change nobody has written down yet — writes nothing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .option(\n      \"--op <operationId>\",\n      \"seed from an operation instead of a service; repeatable\",\n      (value: string, prev: string[] = []) => [...prev, value],\n    )\n    .option(\"--as <FEAT>\", `feature id for the suggested command line (default: ${PLACEHOLDER})`)\n    .action(async (serviceArgs: string[], opts: ExploreOptions) => {\n      const json = opts.json === true;\n      const services = serviceArgs ?? [];\n      const operations = opts.op ?? [];\n\n      // `--as` is interpolated into the `loam new` line this command prints\n      // under `next:` and returns as `scaffold`, and `loam-feature` teaches an\n      // agent to pass `$1` straight into it. Unchecked, `explore` hands back a\n      // command `loam new` then refuses — loam instructing an agent to run\n      // something loam rejects, which is the one thing the printed-command\n      // guard exists to prevent and the one shape it cannot see, because it\n      // reads literal source strings and this line is assembled from argv.\n      // Same grammar as `new`'s, from core/ids.ts, so the two cannot disagree.\n      if (opts.as !== undefined) {\n        const problem = featureIdProblem(opts.as, \"feature id for --as\");\n        if (problem !== null) {\n          fail(json, \"invalid-option\", problem);\n          return;\n        }\n      }\n      if (services.length === 0 && operations.length === 0) {\n        fail(\n          json,\n          \"invalid-option\",\n          \"Nothing to explore from. Name at least one service, or pass --op <operationId>. \" +\n            \"`loam list services` is the fleet; `loam show <service>` is one of them.\",\n        );\n        return;\n      }\n\n      // Rule 6 in docs/DESIGN.md: a raw argv string that reaches a path join is\n      // guarded at the command boundary. Every id here reaches `servicePaths`.\n      // Before `loadConfig`, exactly as `loam new` guards its `--touches` list:\n      // the grammar is a fact about the argument, not about the repository, so\n      // an unusable id should answer the same whether or not you are standing\n      // in a wired repo.\n      //\n      // A seed naming a service that does not EXIST is fine and reported as\n      // `unknown` — the feature may be introducing it — but one that could not\n      // be a service directory at all is a typo, not an intention.\n      try {\n        for (const id of services) assertServiceId(id, \"service\");\n      } catch (err) {\n        if (!(err instanceof InvalidIdError)) throw err;\n        fail(json, \"invalid-option\", err.message);\n        return;\n      }\n\n      const config = await loadConfig();\n      if (!config) {\n        reportNoConfig(json);\n        return;\n      }\n      const { docsDir } = config;\n      // `services`, not `docs`: every answer here is a statement about the\n      // fleet, and an empty ring read out of a directory that is not a docs\n      // repo says \"nothing calls this service\" about a repo nobody looked in.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      try {\n        const result = await explore({\n          docsDir,\n          services,\n          operations,\n          featureId: opts.as ?? PLACEHOLDER,\n          context: new FleetContext(),\n        });\n        if (json) {\n          emitJson({ command: \"explore\", docsDir, ...result });\n          return;\n        }\n        print(result);\n      } catch (err) {\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        // The scan is all-or-nothing — it reads every seed's contract to build\n        // one table — so the honest answer to an unreadable file is a refusal\n        // naming the path, not a ring with a silent hole in it.\n        reportRepositoryUnavailable(json, err, \"the exploration would be missing a service\", docsDir);\n      }\n    });\n}\n\n/* ------------------------------------------------------------------ */\n\nfunction print(r: Exploration): void {\n  if (!r.landscape.present || !r.landscape.parses) {\n    // Said first and without hedging: with no readable map there IS no ring,\n    // and a reader who takes the empty neighbour list at face value concludes\n    // the change is contained when nothing checked that.\n    const why = r.landscape.present ? \"does not parse\" : \"does not exist\";\n    console.log(\n      `! architecture/landscape.likec4 ${why} — no neighbour below is derived, and none is missing either\\n`,\n    );\n  }\n\n  for (const s of r.services) {\n    console.log(`${s.id}   ${label(s)}`);\n    if (!s.known) {\n      // Two different facts wear the same absence. A SEED nobody typed by\n      // accident is a service the feature introduces; one typed by accident is\n      // a typo, and the near-miss list is what separates them. A neighbour is\n      // neither — the fleet map drew an edge to something with no\n      // `services/<id>/`, which is usually an external system and occasionally\n      // a service nobody has adopted. Saying \"typo\" about that one sends a\n      // reader looking for a mistake they did not make.\n      const near = r.unknown.find((u) => u.id === s.id)?.nearest ?? [];\n      const why =\n        s.reason === \"seed\"\n          ? \"the feature introduces it, or the id is a typo\"\n          : \"an external system, or a service nobody has adopted\";\n      console.log(\n        `    no services/${s.id}/ — ${why}` +\n          (near.length > 0 ? `; closest existing: ${near.join(\", \")}` : \"\"),\n      );\n    } else {\n      if (s.missing.length > 0) console.log(`    missing: ${s.missing.join(\", \")}`);\n      if (!s.modelled) console.log(`    not in the fleet map — no edge into it can be checked`);\n      // Said before `exposes`, and said at all: an unreadable contract exposes\n      // an empty list, and printing nothing there reads as \"this service offers\n      // no endpoints\" — the answer that turns a MODIFIED requirement into an\n      // ADDED one.\n      if (s.openapi.unreadable) {\n        console.log(`    ! openapi.yaml does not parse — nothing here lists what ${s.id} exposes`);\n        if (s.openapi.error !== undefined) console.log(`      ${s.openapi.error}`);\n      } else if (s.operations.length > 0) {\n        console.log(`    exposes: ${s.operations.join(\", \")}`);\n      }\n    }\n    for (const e of s.inbound) console.log(`    ← ${e.service}${edgeNote(e.op, e.title)}`);\n    for (const e of s.outbound) console.log(`    → ${e.service}${edgeNote(e.op, e.title)}`);\n    console.log(\"\");\n  }\n\n  if (r.unresolvedOperations.length > 0) {\n    console.log(\n      `! no living contract defines ${r.unresolvedOperations.join(\", \")} — ` +\n        `the feature is adding ${r.unresolvedOperations.length === 1 ? \"it\" : \"them\"}, or the id is wrong\\n`,\n    );\n  }\n\n  if (r.neighbours.length > 0) {\n    // The whole point of the command, so it is stated as a question rather than\n    // a list: these are candidates for --touches, and loam does not know which\n    // of them this change actually touches.\n    console.log(\n      `${plural(r.neighbours.length, \"neighbour\")} one hop out: ${r.neighbours.join(\", \")}`,\n    );\n    console.log(\"  weigh each one — loam knows they are connected, not whether you change them\\n\");\n  }\n\n  if (r.overlaps.length > 0) {\n    console.log(\"already in flight over this ground\");\n    for (const o of r.overlaps) console.log(`  ${o.feature}  ${o.services.join(\", \")}`);\n    console.log(\"  `loam dependencies` says which must archive first, and what no ordering fixes\\n\");\n  }\n\n  console.log(`next: ${r.scaffold}`);\n}\n\nfunction label(s: ExploreService): string {\n  const where = s.reason === \"seed\" ? \"seed\" : s.reason === \"calls-seed\" ? \"calls a seed\" : \"called by a seed\";\n  // `known`, matching the branch in `print` — not `maturity === null`. The two\n  // are set together and cannot disagree today, but discriminating on different\n  // fields for the same question is how they start to: a reader fixing one\n  // branch has no reason to look at the other.\n  return s.known ? `${where} · ${s.maturity}` : `${where} · not in the docs repo`;\n}\n\nfunction edgeNote(op: string | null, title: string | null): string {\n  if (op !== null) return `  ${op}`;\n  return title !== null ? `  \"${title}\"` : \"\";\n}\n"]}

package/dist/commands/format.js

@@ -0,0 +1,17 @@
+/**
+ * Small shaping helpers for the human renderers.
+ *
+ * They live in `commands/` and not in `core/`: nothing here computes an answer,
+ * it only decides how an answer reads to a person. The `--json` payloads never
+ * touch this file.
+ */
+/**
+ * "1 service", "2 services". The regular English plural, spelled once because
+ * five renderers had drifted into five copies of the same ternary and a sixth
+ * would have been written the next time somebody counted something. A noun with
+ * an irregular plural does not belong here — say both forms at the call site.
+ */
+export function plural(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+//# sourceMappingURL=format.js.map

package/dist/commands/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/commands/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,CAAS,EAAE,IAAY;IAC5C,OAAO,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAC7C,CAAC","sourcesContent":["/**\n * Small shaping helpers for the human renderers.\n *\n * They live in `commands/` and not in `core/`: nothing here computes an answer,\n * it only decides how an answer reads to a person. The `--json` payloads never\n * touch this file.\n */\n\n/**\n * \"1 service\", \"2 services\". The regular English plural, spelled once because\n * five renderers had drifted into five copies of the same ternary and a sixth\n * would have been written the next time somebody counted something. A noun with\n * an irregular plural does not belong here — say both forms at the call site.\n */\nexport function plural(n: number, noun: string): string {\n  return `${n} ${noun}${n === 1 ? \"\" : \"s\"}`;\n}\n"]}

package/dist/commands/gherkin.js

@@ -1,14 +1,14 @@
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { loadConfig } from "../core/config.js";
-import { decodeDocument, NotUtf8DocumentError } from "../core/fleet-context.js";
-import { emitJson, emitJsonError, fail, reportNoConfig } from "../core/json.js";
+import { decodeDocument, NotUtf8DocumentError } from "../core/document-bytes.js";
+import { emitJson, emitJsonError, fail, NO_SERVICE_MESSAGE, reportNoConfig } from "../core/json.js";
 import { featureSpecPaths, listFeatures, missingFeatureMessage, resolveFeature, servicePaths, SPEC_AXES, } from "../core/repo.js";
 import { parseRequirements } from "../core/spec.js";
 import { axisLabel, featureFilesUnder, gherkinRoot, parseStampedFeature, planEmission, } from "../core/gherkin.js";
 import { LOAM_VERSION } from "../core/version.js";
-import { resolveInside, UnsafePathError } from "../core/path-safety.js";
+import { isPathInside, resolveInside, UnsafePathError } from "../core/path-safety.js";
 export function registerGherkin(program) {
     program
         .command("gherkin")
@@ -27,7 +27,7 @@ export function registerGherkin(program) {
         }
         const service = opts.service ?? config.service;
         if (service === undefined) {
-            return fail(json, "invalid-option", "No service. Pass --service <id> or set it in loam.json.");
+            return fail(json, "invalid-option", NO_SERVICE_MESSAGE);
         }
         // The emission writes into the repo loam is standing in, so it can only
         // run where that repo is this service's — vouch's refusal, verbatim logic.
@@ -53,6 +53,11 @@ export function registerGherkin(program) {
             return fail(json, "invalid-option", `Cannot emit Gherkin: ${err.message}. The output directory must stay inside the service repo.`);
         }
         const rel = (abs) => relative(repoDir, abs).split(/[\\/]/).join("/");
+        const feature = featureArg === undefined ? null : await resolveFeature(config.docsDir, featureArg, "exclude");
+        if (featureArg !== undefined && feature === null) {
+            return fail(json, "unknown-target", await missingFeatureMessage(config.docsDir, featureArg));
+        }
+        const scope = feature === null ? { mode: "living" } : { mode: "feature", featureId: feature.id };
         // The requirement set, by scope. Feature mode takes ADDED and MODIFIED —
         // a BASE requirement is the living state quoted, a REMOVED one is being
         // retired, and neither is behaviour anybody is about to test. Living mode
@@ -64,18 +69,10 @@ export function registerGherkin(program) {
         // a destructive one — an empty plan makes every existing .feature under
         // loam/ an orphan, and a living run DELETES its orphans. The whole
         // generated suite would go because a docs file was written by PowerShell.
-        let mode = "living";
-        let featureId;
         const byAxis = [];
         const readSpec = async (path) => parseRequirements(decodeDocument(await readFile(path), path));
         try {
-            if (featureArg !== undefined) {
-                const feature = await resolveFeature(config.docsDir, featureArg, "exclude");
-                if (!feature) {
-                    return fail(json, "unknown-target", await missingFeatureMessage(config.docsDir, featureArg));
-                }
-                mode = "feature";
-                featureId = feature.id;
+            if (feature !== null) {
                 const paths = featureSpecPaths(feature.dir, service);
                 for (const axis of SPEC_AXES) {
                     const path = paths[axis.key];
@@ -104,7 +101,11 @@ export function registerGherkin(program) {
         }
         // `service` is not decoration: it salts every `@loam-digest-…` stamp, and
         // it is the same string `loam verify` files the matching claims under.
-        const plan = planEmission(byAxis, { service, featureTag: featureId, version: LOAM_VERSION });
+        const plan = planEmission(byAxis, {
+            service,
+            featureTag: scope.mode === "feature" ? scope.featureId : undefined,
+            version: LOAM_VERSION,
+        });
         // Orphans of THIS scope, inside loam/ and nowhere else. Feature mode owns
         // only its own emissions: stamped files carrying this feature's tag whose
         // file is no longer in the plan (a requirement renamed or dropped).
@@ -117,14 +118,46 @@ export function registerGherkin(program) {
         // deletion and replacement, and feature mode has to recognise another
         // feature's in-flight file to refuse overwriting it.
         const activeIds = new Set((await listFeatures(config.docsDir)).map((f) => f.id));
+        // "Inside loam/" has to hold after the links are resolved, not merely in
+        // the spelling of the path. `featureFilesUnder` FOLLOWS symlinks and
+        // recurses with the LINK's path, so a planted `<gherkinDir>/loam/sub ->
+        // /outside` hands back candidates that read as ours while `unlink`
+        // resolves them and destroys files that were never in this repo. Planned
+        // names are flat, so nothing nested is ever spared by `planned.has(...)`,
+        // and deletion is the one irreversible thing this command does: a
+        // candidate is an orphan only when its CONTAINING directory really
+        // resolves inside the owned root. The write path below refuses the same
+        // attack for the same reason.
+        //
+        // The candidate FILE is deliberately NOT resolved. A symlinked .feature
+        // sitting directly in loam/ is loam's to remove — unlinking it takes the
+        // link and leaves its target alone — so only the directory chain has to
+        // be ours.
+        const realOrNull = (p) => {
+            try {
+                return realpathSync(p);
+            }
+            catch {
+                return null;
+            }
+        };
+        // A root that does not resolve — absent, dangling, or vanished mid-run —
+        // proves nothing about what lives beneath it, so nothing is collected.
+        // Leaving an orphan behind is self-repairing (`loam validate` grades it
+        // `gherkin.orphaned` and the next run removes it); a deletion taken on an
+        // unproven path is not.
+        const rootReal = realOrNull(root);
         const orphans = [];
-        if (existsSync(root)) {
+        if (rootReal !== null) {
             for (const abs of await featureFilesUnder(root)) {
                 if (planned.has(relative(root, abs).split(/[\\/]/).join("/")))
                     continue;
+                const holder = realOrNull(dirname(abs));
+                if (holder === null || !isPathInside(rootReal, holder))
+                    continue;
                 const stamped = parseStampedFeature(await readFile(abs, "utf8"));
-                if (mode === "feature") {
-                    if (stamped !== null && stamped.tags.includes(featureId))
+                if (scope.mode === "feature") {
+                    if (stamped !== null && stamped.tags.includes(scope.featureId))
                         orphans.push(abs);
                 }
                 else {
@@ -153,16 +186,17 @@ export function registerGherkin(program) {
                 continue;
             }
             const existing = parseStampedFeature(await readFile(path, "utf8"));
-            if (mode === "living") {
+            if (scope.mode === "living") {
                 if (existing !== null && existing.tags.some((t) => activeIds.has(t))) {
                     actions.push({ ...f, path, action: "kept", kept: existing });
                     continue;
                 }
             }
-            else {
-                const owners = existing === null
-                    ? []
-                    : existing.tags.filter((t) => t !== featureId && activeIds.has(t));
+            else if (existing !== null) {
+                // An unstamped file is nobody's delta — it owns nothing, so it is
+                // replaced like any other, which is what the empty owner list used
+                // to say the long way round.
+                const owners = existing.tags.filter((t) => t !== scope.featureId && activeIds.has(t));
                 if (owners.length > 0) {
                     actions.push({ ...f, path, action: "conflict", kept: existing, owners });
                     continue;
@@ -172,26 +206,31 @@ export function registerGherkin(program) {
         }
         // All or nothing: one conflicting file refuses the whole emission, so a
         // half-written suite can never be the state an agent has to reason about.
-        const conflicts = actions.filter((a) => a.action === "conflict");
-        if (conflicts.length > 0) {
-            const detail = conflicts
-                .map((c) => `${rel(c.path)} is @${c.owners.join(" @")} (requirement '${c.requirement.name}')`)
-                .join("; ");
-            const message = `Cannot emit gherkin for ${featureId}: ${conflicts.length} file(s) belong to another feature still in flight — ${detail}. ` +
-                `A .feature file carries one feature's delta; overwriting would revert that feature's wording and destroy the digest stamps \`loam verify --results\` matches on. ` +
-                `Archive (or abandon) the owning feature first, or rename the requirement in ${featureId}'s delta so the two stop sharing a file name.`;
-            if (json) {
-                emitJsonError("gherkin-conflict", message, {
-                    conflicts: conflicts.map((c) => ({
-                        path: rel(c.path),
-                        action: "conflict",
-                        requirement: c.requirement.name,
-                        inFlight: c.owners,
-                    })),
-                });
-                return;
+        // Only a feature run can conflict — living mode keeps the in-flight file
+        // rather than refusing — and standing inside that scope is also how the
+        // message names the feature without asserting there is one.
+        if (scope.mode === "feature") {
+            const conflicts = actions.filter((a) => a.action === "conflict");
+            if (conflicts.length > 0) {
+                const detail = conflicts
+                    .map((c) => `${rel(c.path)} is @${c.owners.join(" @")} (requirement '${c.requirement.name}')`)
+                    .join("; ");
+                const message = `Cannot emit gherkin for ${scope.featureId}: ${conflicts.length} file(s) belong to another feature still in flight — ${detail}. ` +
+                    `A .feature file carries one feature's delta; overwriting would revert that feature's wording and destroy the digest stamps \`loam verify --results\` matches on. ` +
+                    `Archive (or abandon) the owning feature first, or rename the requirement in ${scope.featureId}'s delta so the two stop sharing a file name.`;
+                if (json) {
+                    emitJsonError("gherkin-conflict", message, {
+                        conflicts: conflicts.map((c) => ({
+                            path: rel(c.path),
+                            action: "conflict",
+                            requirement: c.requirement.name,
+                            inFlight: c.owners,
+                        })),
+                    });
+                    return;
+                }
+                return fail(json, "gherkin-conflict", message);
             }
-            return fail(json, "gherkin-conflict", message);
         }
         const writes = actions.filter((a) => a.action !== "kept");
         if (!dryRun) {
@@ -207,8 +246,8 @@ export function registerGherkin(program) {
         }
         if (json) {
             emitJson({
-                mode,
-                ...(featureId === undefined ? {} : { feature: featureId }),
+                mode: scope.mode,
+                ...(scope.mode === "feature" ? { feature: scope.featureId } : {}),
                 service,
                 root: rel(root),
                 written: !dryRun,
@@ -229,11 +268,11 @@ export function registerGherkin(program) {
             });
             return;
         }
-        const head = mode === "feature" ? `${featureId} · ${service}` : `${service} (living suite)`;
+        const head = scope.mode === "feature" ? `${scope.featureId} · ${service}` : `${service} (living suite)`;
         console.log(`gherkin ${head} → ${rel(root)}/${dryRun ? "  (dry run)" : ""}\n`);
         if (actions.length === 0) {
-            console.log(mode === "feature"
-                ? `  ${featureId} has no ADDED or MODIFIED requirements for ${service} — nothing to emit.`
+            console.log(scope.mode === "feature"
+                ? `  ${scope.featureId} has no ADDED or MODIFIED requirements for ${service} — nothing to emit.`
                 : `  the living specs hold no requirements for ${service} — nothing to emit.`);
         }
         // `conflict` never reaches here — the run refused above — but the map is