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

package/dist/commands/new/new.js

@@ -0,0 +1,328 @@
+import { existsSync } from "node:fs";
+import {} from "../../core/staging/writes.js";
+import { commitScaffold } from "./commit.js";
+import { join } from "node:path";
+import { parseFeatureId } from "../../core/kernel/ids/feature.js";
+import { parseServiceIds } from "../../core/kernel/ids/service.js";
+import { configOrRefuse, emitJson, fail, repoPath } from "../../core/envelope/json.js";
+import { UnsafePathError, resolveInside } from "../../core/kernel/path-safety.js";
+import { featureIdFromDirName, nearestIds } from "../../core/repo/entries.js";
+import { featuresDir, landscapePath } from "../../core/repo/paths.js";
+import { loadArchitecture } from "../../core/c4/project/architecture.js";
+import { drawnServiceElements } from "../../core/c4/resolve/service.js";
+import { DocsRepoUnavailableError } from "../../core/repo/state.js";
+import { listServices } from "../../core/repo/repo.js";
+import { docsRepoReady, reportDocsRepoError } from "../policy/gate.js";
+import { sayRecovered } from "../policy/format.js";
+import { capabilityIdProblem } from "../../core/kernel/ids/capability.js";
+import { capabilityNotes } from "../../core/capabilities/authoring/notes.js";
+import { modifiedFiles, planModifies } from "./modifies.js";
+import { archSpecTemplate, deltaTemplate, intentTemplate, openapiTemplate, specTemplate } from "./templates.js";
+import { capabilityDeltaTemplate } from "./capability-template.js";
+export function registerNew(program) {
+    program
+        .command("new")
+        .argument("<featureId>", "feature id, e.g. FEAT-101")
+        .description("Scaffold a feature: intent, C4 delta, a requirement delta per service, a capability delta per promise")
+        .option("--title <text>", "human title; also becomes the directory slug")
+        // `--touches`, not `--service`: everywhere else `--service` selects the ONE
+        // operating target (defaulting to config.service), while this is a repeatable
+        // list of services the feature touches — a different arity and a different
+        // meaning deserve a different name.
+        .option("--touches <id>", "a service this feature touches (repeatable)", collect, [])
+        .option("--new-service <id>", "a service this feature introduces (repeatable)", collect, [])
+        // The INVERSION of the two flags above, and it composes with them rather
+        // than excluding them. `--touches` asks which services change before the
+        // business change has been written; `--capability` opens the document that
+        // changes and lets the service work be derived from it. A feature that
+        // does both — the analyst writes the promise, and one team already knows it
+        // owns part of the mechanism — is an ordinary shape, and refusing the
+        // combination would fight this axis's own archive gate: `capability.uncovered`
+        // refuses a promise nothing in the same feature keeps, so the fix it names
+        // is precisely a `--touches` service's `Realizes:` line living beside the
+        // capability delta.
+        //
+        // Repeatable, like both flags above: a business change that moves two
+        // promises is as real as a feature touching two services, and the flag that
+        // is not repeatable is the one that sends an author to mkdir by hand.
+        .option("--capability <id>", "a business capability this feature changes (repeatable)", collect, [])
+        // The small-change lane (./modifies.ts): the living requirement copied
+        // into an uncommented MODIFIED block, pinned at scaffold time.
+        .option("--modifies <Req-ID>", "a living requirement of a --touches service this feature rewrites (repeatable): scaffolds its MODIFIED block, already pinned", collect, [])
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (featureId, opts) => {
+        const json = opts.json === true;
+        // The grammar's verdict arrives as the brand: `featureDirName` demands
+        // a FeatureId, so an argv string cannot reach the directory derivation
+        // without passing through this parse — the producer the brand was
+        // missing while `isFeatureId` narrowed to plain string.
+        const parsedId = parseFeatureId(featureId, "feature id");
+        if (!parsedId.ok) {
+            return fail(json, "invalid-option", parsedId.problem);
+        }
+        const dirName = featureDirName(parsedId.id, opts.title);
+        // The round-trip is checked beside the grammar, not inside it: the
+        // grammar is a fact about the id, while `featureIdFromDirName` depends on
+        // the TITLE this command is about to slug into the directory name. Only
+        // `new` creates that directory, so only `new` owes that second half.
+        if (featureIdFromDirName(dirName) !== featureId) {
+            return fail(json, "invalid-option", `'${featureId}' does not survive the directory round-trip with this title.`);
+        }
+        // Service ids are validated BEFORE the config is even loaded, and long
+        // before anything is written: every one of them is interpolated into
+        // `specs/<id>/` under the new feature directory, so `--touches ../../x`
+        // was a writer pointed outside the docs repo. One grammar (core/kernel/ids/service.ts),
+        // the same one adopt/init/vouch refuse on, so a service that is legal to
+        // create is legal to name here and nowhere the two disagree.
+        // The LIST, not each item: a loop narrows the element and leaves the
+        // array unbranded, so what reached the writer below was `string[]` no
+        // matter how thoroughly each id had been checked. --touches first, so the
+        // id reported first is the one it was before.
+        const touches = parseServiceIds(opts.touches, "--touches");
+        if (!touches.ok)
+            return fail(json, "invalid-option", touches.problem);
+        const newServices = parseServiceIds(opts.newService, "--new-service");
+        if (!newServices.ok)
+            return fail(json, "invalid-option", newServices.problem);
+        // Same reasoning as the two lists above, one tree over. A capability id
+        // becomes `features/<dirName>/capabilities/<id>/` — a chain of
+        // directories, one per `/`-separated segment — so `--capability
+        // ../../evil` resolves to `features/evil/spec.md`, a directory
+        // `listFeatures` then enumerates as a feature, and one `..` further
+        // reaches the docs-repo root. `resolveInside` below cannot refuse either:
+        // both are still inside the repo. Checked here for that reason, and
+        // against the same directory-name grammar a service id passes
+        // (core/kernel/ids/capability.ts).
+        const capabilities = opts.capability;
+        for (const id of capabilities) {
+            const problem = capabilityIdProblem(id);
+            if (problem !== null)
+                return fail(json, "invalid-option", problem);
+        }
+        const config = await configOrRefuse(json);
+        if (config === null)
+            return;
+        const { docsDir } = config;
+        // Before a single file is scaffolded: a docsDir that is not a docs repo is
+        // refused, never written into. `features/<id>/**` lands happily in any
+        // directory, so without this gate `new` reported `ok: true` over a
+        // scaffold that no enumeration downstream will ever see — and a docsDir
+        // that is simply absent escaped as `internal` (the enumeration below
+        // throws) carrying the very sentence `list` and `show` report as
+        // `docs-missing`. See docs-repo-gate.ts's docsRepoReady. `services`, not
+        // `docs`: every id named by --touches/--new-service is a claim about
+        // `services/<id>/`, and the near-miss note below is computed against that
+        // directory, so a run without it is guessing.
+        if (!docsRepoReady(json, docsDir, "services"))
+            return;
+        // No unlocked existence fast-path, deliberately: staging creates the
+        // feature directory at plan time, so a HALF-scaffold from a killed run
+        // resolves like a finished feature — and an unlocked refusal here made
+        // \`loam new <id>\` answer already-exists over its own wreckage without
+        // ever reaching the recovery that would complete it, while doctor's fix
+        // printed exactly that re-run. Existence is asked once, under the lock,
+        // after recovery has run.
+        // A service named both ways is new — that is the more specific claim.
+        const created = new Set(newServices.ids);
+        const touched = touches.ids.filter((s) => !created.has(s));
+        const dir = join(featuresDir(docsDir), dirName);
+        // Resolved before anything is written: an id naming no living
+        // requirement refuses the whole scaffold, as a bad --touches id does.
+        const modifies = await planModifies(docsDir, touched, opts.modifies);
+        if (!modifies.ok)
+            return fail(json, modifies.code, modifies.message);
+        // `--modifies` and nothing else — every touched service has a requirement
+        // rewritten, none is introduced, no promise opened — is a feature that
+        // changes no architecture, and the scaffold's own advice for that case is
+        // "delete delta.likec4". So it is not written; validate and archive read
+        // a requirements-only feature as complete without it.
+        const requirementsOnly = modifies.targets.length > 0 && created.size === 0 && capabilities.length === 0 &&
+            touched.every((svc) => modifies.targets.some((t) => t.service === svc));
+        const files = { "intent.md": intentTemplate(featureId, opts.title) };
+        if (!requirementsOnly) {
+            files["delta.likec4"] = deltaTemplate(featureId, touched, [...created], await drawnIds(docsDir, touched));
+        }
+        for (const svc of [...touched, ...created]) {
+            files[join("specs", svc, "spec.md")] = specTemplate(featureId, svc);
+        }
+        Object.assign(files, modifiedFiles(featureId, modifies.targets, files));
+        // The business axis, and the ONE file `--capability` adds. No service
+        // spec rides with it, and that is the inversion rather than an omission:
+        // the whole point of opening the document that changes first is that the
+        // services realizing it are not known until the promise is written.
+        // `--touches` is still how a service the author already knows about gets
+        // its delta, which is why the two compose.
+        //
+        // Spelled relative, mirroring `featureCapabilityDeltasDir` +
+        // `capabilityDocPathsAt` in core/repo/authored/paths.ts — the path builders take a
+        // FeatureDir, whose provenance is an enumeration that read the directory,
+        // and this directory is about to be created rather than read. One
+        // directory per segment, exactly as the living tree spells nesting.
+        for (const cap of capabilities) {
+            files[join("capabilities", ...cap.split("/"), "spec.md")] = capabilityDeltaTemplate(featureId, cap);
+        }
+        for (const svc of created) {
+            files[join("specs", svc, "openapi.yaml")] = openapiTemplate(svc);
+            // The architecture axis is scaffolded only for a service this feature
+            // INTRODUCES, because that is the case where `c4.uncovered` will fire
+            // the moment the delta is written: a brand-new tagged element nothing
+            // covers. Handing an author a blank page for the outbox/retries/alerts
+            // requirement is how that axis stays empty across a whole fleet.
+            files[join("specs", svc, "arch.spec.md")] = archSpecTemplate(featureId, svc);
+        }
+        // The COMPLETE plan in memory before a byte lands on disk: every path
+        // resolved (belt and braces over the id grammar — resolveInside proves
+        // containment at the moment of the write, symlink cases included), and
+        // every write an exclusive create, because the feature must not exist.
+        // The sequential writeFile loop this replaces could die mid-scaffold and
+        // leave a partial feature the next run refused as already-exists.
+        const writes = [];
+        for (const [rel, content] of Object.entries(files)) {
+            let path;
+            try {
+                path = resolveInside(docsDir, join("features", dirName, rel), "feature file");
+            }
+            catch (err) {
+                if (!(err instanceof UnsafePathError))
+                    throw err;
+                return fail(json, "invalid-option", err.message);
+            }
+            writes.push({ path, content, exclusive: true });
+        }
+        const committed = await commitScaffold(docsDir, featureId, writes);
+        if (!committed.ok) {
+            if ("repoGone" in committed) {
+                reportDocsRepoError(json, committed.repoGone);
+                return;
+            }
+            if (committed.code === "already-exists") {
+                // After a recovery the refusal must SAY the repair happened: doctor
+                // told the operator to re-run this exact command, and "already
+                // exists" alone reads as the fix having failed.
+                return fail(json, "already-exists", `Feature '${featureId}' already exists at ${repoPath(docsDir, committed.existing?.dir ?? dir)}.` +
+                    (committed.recovered === null ? "" : ` (${sayRecovered(committed.recovered)} The scaffold is complete.)`));
+            }
+            return fail(json, committed.code, committed.message);
+        }
+        const recovered = committed.recovered;
+        const written = writes.map((w) => repoPath(docsDir, w.path));
+        // Both note families in ONE list, and the services first so an existing
+        // `--touches` consumer reads the same first element it always did. They
+        // are the same kind of statement — "the thing you named is not there yet,
+        // and here is what that means" — so splitting them into two payload keys
+        // would ask a consumer to learn a second shape for one idea.
+        const notes = [
+            ...(await unknownServiceNotes(docsDir, touched)),
+            ...(await capabilityNotes(docsDir, { dirName, ids: capabilities })),
+        ];
+        if (json) {
+            emitJson({
+                command: "new",
+                feature: featureId,
+                path: repoPath(docsDir, dir),
+                created: written,
+                ...(recovered === null ? {} : { recovered }),
+                // Not an error and not a finding: `--touches` on a service that does
+                // not exist yet is legal (adopt it later, or say `--new-service`),
+                // and `--capability` on a promise nobody has named is the ordinary
+                // way a new business area starts. Both are reported because the
+                // silent alternative is a delta that will never merge into anything,
+                // or a near-miss spelling filed as a second capability.
+                notes,
+            });
+            return;
+        }
+        console.log(`${featureId} scaffolded at ${repoPath(docsDir, dir)}`);
+        for (const w of written)
+            console.log(`  + ${w}`);
+        for (const t of modifies.targets)
+            console.log(`  ~ MODIFIED ${t.id}: copied from ${t.living}, Based-On already pinned`);
+        for (const note of notes)
+            console.log(`\n  note: ${note}`);
+        if (requirementsOnly) {
+            console.log(`\nNext: edit each MODIFIED requirement in place, write intent.md's Why, then\n` +
+                `\`loam validate --feature ${featureId}\` and \`loam archive ${featureId}\`. No delta.likec4 was written:\n` +
+                "rewriting requirements changes no architecture. If this change also moves an element or\n" +
+                "an edge, add one — `loam instructions loam-feature` shows its shape.");
+            return;
+        }
+        console.log(`\nNext: fill in the delta, then \`loam validate --feature ${featureId}\`.`);
+        console.log("If this feature changes no architecture, delete delta.likec4 — a requirements-only\n" +
+            "feature is complete without it, and an empty `model {}` validates clean too.");
+    });
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+/* ------------------------------------------------------------------ */
+/* Hints                                                               */
+/* ------------------------------------------------------------------ */
+/**
+ * `--touches <id>` naming neither a living `services/<id>/` nor a `--new-service`
+ * is almost always a typo, and it is silent by construction: the scaffold writes
+ * `specs/<id>/spec.md` happily, `loam validate` grades a delta against a living
+ * spec that is not there, and the mistake surfaces at archive time as a service
+ * appearing from nowhere. A note, not a refusal — naming a service that will be
+ * adopted next week is legitimate — but the near-miss is spelled out, because
+ * `order-api` vs `orders-api` is exactly the pair a person cannot see.
+ */
+async function unknownServiceNotes(docsDir, touched) {
+    if (touched.length === 0)
+        return [];
+    let known;
+    try {
+        known = (await listServices(docsDir)).map((s) => s.id);
+    }
+    catch (err) {
+        // No docs repo to compare against is a different diagnosis entirely, and
+        // `loam doctor` owns it. Saying nothing here beats inventing a typo hint
+        // out of an enumeration that never ran.
+        if (!(err instanceof DocsRepoUnavailableError))
+            throw err;
+        return [];
+    }
+    const notes = [];
+    for (const id of touched) {
+        if (known.includes(id))
+            continue;
+        const near = nearestIds(id, known);
+        notes.push(`--touches '${id}' matches no services/${id}/ in the docs repo` +
+            (near.length === 0 ? "" : ` — did you mean ${near.map((n) => `'${n}'`).join(" or ")}?`) +
+            ` If ${id} is introduced by this feature, pass --new-service ${id} instead.`);
+    }
+    return notes;
+}
+/**
+ * The element ids the fleet map already draws the touched services as, so the
+ * delta's context lines reuse them instead of guessing — the delta's own
+ * comment tells the author to reuse the map's identifiers, and it used to
+ * hand them a camel-cased guess that never matched a seeded map's `svc_<id>`.
+ *
+ * Best effort by design: `new` is a scaffolder, not a validator. No map, or
+ * one that does not parse, leaves every id to the seed convention, and
+ * `loam validate` reports the map on its own. The project loader and the
+ * resolver are the ones `loam adopt` reads, so the two commands cannot name
+ * one box two ways.
+ */
+async function drawnIds(docsDir, touched) {
+    if (touched.length === 0 || !existsSync(landscapePath(docsDir)))
+        return new Map();
+    const land = await loadArchitecture(docsDir);
+    if (land.errors.length > 0)
+        return new Map();
+    return drawnServiceElements(land.elements, new Set((await listServices(docsDir)).map((s) => s.id)));
+}
+/* ------------------------------------------------------------------ */
+/* Naming                                                              */
+/* ------------------------------------------------------------------ */
+function featureDirName(featureId, title) {
+    const slug = slugify(title ?? "");
+    return slug ? `${featureId}-${slug}` : featureId;
+}
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+//# sourceMappingURL=new.js.map

package/dist/commands/new/new.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"new.js","sourceRoot":"","sources":["../../../src/commands/new/new.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { existsSync } from \"node:fs\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { commitScaffold } from \"./commit.js\";\nimport { join } from \"node:path\";\nimport { type FeatureId, parseFeatureId } from \"../../core/kernel/ids/feature.js\";\nimport { parseServiceIds } from \"../../core/kernel/ids/service.js\";\nimport { configOrRefuse, emitJson, fail, repoPath } from \"../../core/envelope/json.js\";\nimport { UnsafePathError, resolveInside } from \"../../core/kernel/path-safety.js\";\nimport { featureIdFromDirName, nearestIds } from \"../../core/repo/entries.js\";\nimport { featuresDir, landscapePath } from \"../../core/repo/paths.js\";\nimport { loadArchitecture } from \"../../core/c4/project/architecture.js\";\nimport { drawnServiceElements } from \"../../core/c4/resolve/service.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { listServices } from \"../../core/repo/repo.js\";\nimport { docsRepoReady, reportDocsRepoError } from \"../policy/gate.js\";\nimport { sayRecovered } from \"../policy/format.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { capabilityIdProblem } from \"../../core/kernel/ids/capability.js\";\nimport { capabilityNotes } from \"../../core/capabilities/authoring/notes.js\";\nimport { modifiedFiles, planModifies } from \"./modifies.js\";\nimport { archSpecTemplate, deltaTemplate, intentTemplate, openapiTemplate, specTemplate } from \"./templates.js\";\nimport { capabilityDeltaTemplate } from \"./capability-template.js\";\n\ninterface NewOptions {\n  title?: string;\n  touches: string[];\n  newService: string[];\n  capability: string[];\n  modifies: string[];\n  json?: boolean;\n}\n\nexport function registerNew(program: Command): void {\n  program\n    .command(\"new\")\n    .argument(\"<featureId>\", \"feature id, e.g. FEAT-101\")\n    .description(\"Scaffold a feature: intent, C4 delta, a requirement delta per service, a capability delta per promise\")\n    .option(\"--title <text>\", \"human title; also becomes the directory slug\")\n    // `--touches`, not `--service`: everywhere else `--service` selects the ONE\n    // operating target (defaulting to config.service), while this is a repeatable\n    // list of services the feature touches — a different arity and a different\n    // meaning deserve a different name.\n    .option(\"--touches <id>\", \"a service this feature touches (repeatable)\", collect, [])\n    .option(\"--new-service <id>\", \"a service this feature introduces (repeatable)\", collect, [])\n    // The INVERSION of the two flags above, and it composes with them rather\n    // than excluding them. `--touches` asks which services change before the\n    // business change has been written; `--capability` opens the document that\n    // changes and lets the service work be derived from it. A feature that\n    // does both — the analyst writes the promise, and one team already knows it\n    // owns part of the mechanism — is an ordinary shape, and refusing the\n    // combination would fight this axis's own archive gate: `capability.uncovered`\n    // refuses a promise nothing in the same feature keeps, so the fix it names\n    // is precisely a `--touches` service's `Realizes:` line living beside the\n    // capability delta.\n    //\n    // Repeatable, like both flags above: a business change that moves two\n    // promises is as real as a feature touching two services, and the flag that\n    // is not repeatable is the one that sends an author to mkdir by hand.\n    .option(\"--capability <id>\", \"a business capability this feature changes (repeatable)\", collect, [])\n    // The small-change lane (./modifies.ts): the living requirement copied\n    // into an uncommented MODIFIED block, pinned at scaffold time.\n    .option(\n      \"--modifies <Req-ID>\",\n      \"a living requirement of a --touches service this feature rewrites (repeatable): scaffolds its MODIFIED block, already pinned\",\n      collect,\n      [],\n    )\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureId: string, opts: NewOptions) => {\n      const json = opts.json === true;\n\n      // The grammar's verdict arrives as the brand: `featureDirName` demands\n      // a FeatureId, so an argv string cannot reach the directory derivation\n      // without passing through this parse — the producer the brand was\n      // missing while `isFeatureId` narrowed to plain string.\n      const parsedId = parseFeatureId(featureId, \"feature id\");\n      if (!parsedId.ok) {\n        return fail(json, \"invalid-option\", parsedId.problem);\n      }\n      const dirName = featureDirName(parsedId.id, opts.title);\n      // The round-trip is checked beside the grammar, not inside it: the\n      // grammar is a fact about the id, while `featureIdFromDirName` depends on\n      // the TITLE this command is about to slug into the directory name. Only\n      // `new` creates that directory, so only `new` owes that second half.\n      if (featureIdFromDirName(dirName) !== featureId) {\n        return fail(\n          json,\n          \"invalid-option\",\n          `'${featureId}' does not survive the directory round-trip with this title.`,\n        );\n      }\n\n      // Service ids are validated BEFORE the config is even loaded, and long\n      // before anything is written: every one of them is interpolated into\n      // `specs/<id>/` under the new feature directory, so `--touches ../../x`\n      // was a writer pointed outside the docs repo. One grammar (core/kernel/ids/service.ts),\n      // the same one adopt/init/vouch refuse on, so a service that is legal to\n      // create is legal to name here and nowhere the two disagree.\n      // The LIST, not each item: a loop narrows the element and leaves the\n      // array unbranded, so what reached the writer below was `string[]` no\n      // matter how thoroughly each id had been checked. --touches first, so the\n      // id reported first is the one it was before.\n      const touches = parseServiceIds(opts.touches, \"--touches\");\n      if (!touches.ok) return fail(json, \"invalid-option\", touches.problem);\n      const newServices = parseServiceIds(opts.newService, \"--new-service\");\n      if (!newServices.ok) return fail(json, \"invalid-option\", newServices.problem);\n\n      // Same reasoning as the two lists above, one tree over. A capability id\n      // becomes `features/<dirName>/capabilities/<id>/` — a chain of\n      // directories, one per `/`-separated segment — so `--capability\n      // ../../evil` resolves to `features/evil/spec.md`, a directory\n      // `listFeatures` then enumerates as a feature, and one `..` further\n      // reaches the docs-repo root. `resolveInside` below cannot refuse either:\n      // both are still inside the repo. Checked here for that reason, and\n      // against the same directory-name grammar a service id passes\n      // (core/kernel/ids/capability.ts).\n      const capabilities = opts.capability;\n      for (const id of capabilities) {\n        const problem = capabilityIdProblem(id);\n        if (problem !== null) return fail(json, \"invalid-option\", problem);\n      }\n\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const { docsDir } = config;\n      // Before a single file is scaffolded: a docsDir that is not a docs repo is\n      // refused, never written into. `features/<id>/**` lands happily in any\n      // directory, so without this gate `new` reported `ok: true` over a\n      // scaffold that no enumeration downstream will ever see — and a docsDir\n      // that is simply absent escaped as `internal` (the enumeration below\n      // throws) carrying the very sentence `list` and `show` report as\n      // `docs-missing`. See docs-repo-gate.ts's docsRepoReady. `services`, not\n      // `docs`: every id named by --touches/--new-service is a claim about\n      // `services/<id>/`, and the near-miss note below is computed against that\n      // directory, so a run without it is guessing.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      // No unlocked existence fast-path, deliberately: staging creates the\n      // feature directory at plan time, so a HALF-scaffold from a killed run\n      // resolves like a finished feature — and an unlocked refusal here made\n      // \\`loam new <id>\\` answer already-exists over its own wreckage without\n      // ever reaching the recovery that would complete it, while doctor's fix\n      // printed exactly that re-run. Existence is asked once, under the lock,\n      // after recovery has run.\n\n      // A service named both ways is new — that is the more specific claim.\n      const created = new Set(newServices.ids);\n      const touched = touches.ids.filter((s) => !created.has(s));\n      const dir = join(featuresDir(docsDir), dirName);\n\n      // Resolved before anything is written: an id naming no living\n      // requirement refuses the whole scaffold, as a bad --touches id does.\n      const modifies = await planModifies(docsDir, touched, opts.modifies);\n      if (!modifies.ok) return fail(json, modifies.code, modifies.message);\n      // `--modifies` and nothing else — every touched service has a requirement\n      // rewritten, none is introduced, no promise opened — is a feature that\n      // changes no architecture, and the scaffold's own advice for that case is\n      // \"delete delta.likec4\". So it is not written; validate and archive read\n      // a requirements-only feature as complete without it.\n      const requirementsOnly =\n        modifies.targets.length > 0 && created.size === 0 && capabilities.length === 0 &&\n        touched.every((svc) => modifies.targets.some((t) => t.service === svc));\n\n      const files: Record<string, string> = { \"intent.md\": intentTemplate(featureId, opts.title) };\n      if (!requirementsOnly) {\n        files[\"delta.likec4\"] = deltaTemplate(featureId, touched, [...created], await drawnIds(docsDir, touched));\n      }\n      for (const svc of [...touched, ...created]) {\n        files[join(\"specs\", svc, \"spec.md\")] = specTemplate(featureId, svc);\n      }\n      Object.assign(files, modifiedFiles(featureId, modifies.targets, files));\n      // The business axis, and the ONE file `--capability` adds. No service\n      // spec rides with it, and that is the inversion rather than an omission:\n      // the whole point of opening the document that changes first is that the\n      // services realizing it are not known until the promise is written.\n      // `--touches` is still how a service the author already knows about gets\n      // its delta, which is why the two compose.\n      //\n      // Spelled relative, mirroring `featureCapabilityDeltasDir` +\n      // `capabilityDocPathsAt` in core/repo/authored/paths.ts — the path builders take a\n      // FeatureDir, whose provenance is an enumeration that read the directory,\n      // and this directory is about to be created rather than read. One\n      // directory per segment, exactly as the living tree spells nesting.\n      for (const cap of capabilities) {\n        files[join(\"capabilities\", ...cap.split(\"/\"), \"spec.md\")] = capabilityDeltaTemplate(featureId, cap);\n      }\n      for (const svc of created) {\n        files[join(\"specs\", svc, \"openapi.yaml\")] = openapiTemplate(svc);\n        // The architecture axis is scaffolded only for a service this feature\n        // INTRODUCES, because that is the case where `c4.uncovered` will fire\n        // the moment the delta is written: a brand-new tagged element nothing\n        // covers. Handing an author a blank page for the outbox/retries/alerts\n        // requirement is how that axis stays empty across a whole fleet.\n        files[join(\"specs\", svc, \"arch.spec.md\")] = archSpecTemplate(featureId, svc);\n      }\n\n      // The COMPLETE plan in memory before a byte lands on disk: every path\n      // resolved (belt and braces over the id grammar — resolveInside proves\n      // containment at the moment of the write, symlink cases included), and\n      // every write an exclusive create, because the feature must not exist.\n      // The sequential writeFile loop this replaces could die mid-scaffold and\n      // leave a partial feature the next run refused as already-exists.\n      const writes: PlannedWrite[] = [];\n      for (const [rel, content] of Object.entries(files)) {\n        let path: string;\n        try {\n          path = resolveInside(docsDir, join(\"features\", dirName, rel), \"feature file\");\n        } catch (err) {\n          if (!(err instanceof UnsafePathError)) throw err;\n          return fail(json, \"invalid-option\", err.message);\n        }\n        writes.push({ path, content, exclusive: true });\n      }\n\n      const committed = await commitScaffold(docsDir, featureId, writes);\n      if (!committed.ok) {\n        if (\"repoGone\" in committed) {\n          reportDocsRepoError(json, committed.repoGone);\n          return;\n        }\n        if (committed.code === \"already-exists\") {\n          // After a recovery the refusal must SAY the repair happened: doctor\n          // told the operator to re-run this exact command, and \"already\n          // exists\" alone reads as the fix having failed.\n          return fail(\n            json,\n            \"already-exists\",\n            `Feature '${featureId}' already exists at ${repoPath(docsDir, committed.existing?.dir ?? dir)}.` +\n              (committed.recovered === null ? \"\" : ` (${sayRecovered(committed.recovered)} The scaffold is complete.)`),\n          );\n        }\n        return fail(json, committed.code, committed.message);\n      }\n      const recovered = committed.recovered;\n      const written = writes.map((w) => repoPath(docsDir, w.path));\n\n      // Both note families in ONE list, and the services first so an existing\n      // `--touches` consumer reads the same first element it always did. They\n      // are the same kind of statement — \"the thing you named is not there yet,\n      // and here is what that means\" — so splitting them into two payload keys\n      // would ask a consumer to learn a second shape for one idea.\n      const notes = [\n        ...(await unknownServiceNotes(docsDir, touched)),\n        ...(await capabilityNotes(docsDir, { dirName, ids: capabilities })),\n      ];\n\n      if (json) {\n        emitJson({\n          command: \"new\",\n          feature: featureId,\n          path: repoPath(docsDir, dir),\n          created: written,\n          ...(recovered === null ? {} : { recovered }),\n          // Not an error and not a finding: `--touches` on a service that does\n          // not exist yet is legal (adopt it later, or say `--new-service`),\n          // and `--capability` on a promise nobody has named is the ordinary\n          // way a new business area starts. Both are reported because the\n          // silent alternative is a delta that will never merge into anything,\n          // or a near-miss spelling filed as a second capability.\n          notes,\n        });\n        return;\n      }\n      console.log(`${featureId} scaffolded at ${repoPath(docsDir, dir)}`);\n      for (const w of written) console.log(`  + ${w}`);\n      for (const t of modifies.targets) console.log(`  ~ MODIFIED ${t.id}: copied from ${t.living}, Based-On already pinned`);\n      for (const note of notes) console.log(`\\n  note: ${note}`);\n      if (requirementsOnly) {\n        console.log(\n          `\\nNext: edit each MODIFIED requirement in place, write intent.md's Why, then\\n` +\n            `\\`loam validate --feature ${featureId}\\` and \\`loam archive ${featureId}\\`. No delta.likec4 was written:\\n` +\n            \"rewriting requirements changes no architecture. If this change also moves an element or\\n\" +\n            \"an edge, add one — `loam instructions loam-feature` shows its shape.\",\n        );\n        return;\n      }\n      console.log(`\\nNext: fill in the delta, then \\`loam validate --feature ${featureId}\\`.`);\n      console.log(\n        \"If this feature changes no architecture, delete delta.likec4 — a requirements-only\\n\" +\n          \"feature is complete without it, and an empty `model {}` validates clean too.\",\n      );\n    });\n}\n\nfunction collect(value: string, previous: string[]): string[] {\n  return [...previous, value];\n}\n\n/* ------------------------------------------------------------------ */\n/* Hints                                                               */\n/* ------------------------------------------------------------------ */\n\n/**\n * `--touches <id>` naming neither a living `services/<id>/` nor a `--new-service`\n * is almost always a typo, and it is silent by construction: the scaffold writes\n * `specs/<id>/spec.md` happily, `loam validate` grades a delta against a living\n * spec that is not there, and the mistake surfaces at archive time as a service\n * appearing from nowhere. A note, not a refusal — naming a service that will be\n * adopted next week is legitimate — but the near-miss is spelled out, because\n * `order-api` vs `orders-api` is exactly the pair a person cannot see.\n */\nasync function unknownServiceNotes(docsDir: DocsDir, touched: string[]): Promise<string[]> {\n  if (touched.length === 0) return [];\n  let known: string[];\n  try {\n    known = (await listServices(docsDir)).map((s) => s.id);\n  } catch (err) {\n    // No docs repo to compare against is a different diagnosis entirely, and\n    // `loam doctor` owns it. Saying nothing here beats inventing a typo hint\n    // out of an enumeration that never ran.\n    if (!(err instanceof DocsRepoUnavailableError)) throw err;\n    return [];\n  }\n  const notes: string[] = [];\n  for (const id of touched) {\n    if (known.includes(id)) continue;\n    const near = nearestIds(id, known);\n    notes.push(\n      `--touches '${id}' matches no services/${id}/ in the docs repo` +\n        (near.length === 0 ? \"\" : ` — did you mean ${near.map((n) => `'${n}'`).join(\" or \")}?`) +\n        ` If ${id} is introduced by this feature, pass --new-service ${id} instead.`,\n    );\n  }\n  return notes;\n}\n\n/**\n * The element ids the fleet map already draws the touched services as, so the\n * delta's context lines reuse them instead of guessing — the delta's own\n * comment tells the author to reuse the map's identifiers, and it used to\n * hand them a camel-cased guess that never matched a seeded map's `svc_<id>`.\n *\n * Best effort by design: `new` is a scaffolder, not a validator. No map, or\n * one that does not parse, leaves every id to the seed convention, and\n * `loam validate` reports the map on its own. The project loader and the\n * resolver are the ones `loam adopt` reads, so the two commands cannot name\n * one box two ways.\n */\nasync function drawnIds(docsDir: DocsDir, touched: string[]): Promise<ReadonlyMap<string, string>> {\n  if (touched.length === 0 || !existsSync(landscapePath(docsDir))) return new Map();\n  const land = await loadArchitecture(docsDir);\n  if (land.errors.length > 0) return new Map();\n  return drawnServiceElements(land.elements, new Set((await listServices(docsDir)).map((s) => s.id)));\n}\n\n/* ------------------------------------------------------------------ */\n/* Naming                                                              */\n/* ------------------------------------------------------------------ */\n\nfunction featureDirName(featureId: FeatureId, title: string | undefined): string {\n  const slug = slugify(title ?? \"\");\n  return slug ? `${featureId}-${slug}` : featureId;\n}\n\nfunction slugify(text: string): string {\n  return text\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n}\n"]}