@ybotok/loam 0.2.0-alpha.7 → 0.2.0-alpha.9

package/dist/commands/new/modifies.js

@@ -0,0 +1,206 @@
+/**
+ * `loam new --modifies <Req-ID>`: the small-change lane's one hand step,
+ * done by the scaffold.
+ *
+ * A change that rewrites a requirement the fleet already has used to cost a
+ * hand copy and a second command: the scaffold offered only the ADDED example
+ * inside its comment, so the author copied the living requirement into a
+ * `## MODIFIED Requirements` section by hand — most of a small delta is that
+ * copy — and then ran `loam rebase` to pin it. This module does both at
+ * scaffold time: it finds each named requirement in the living specs of the
+ * services the feature touches and writes it, UNCOMMENTED, under a MODIFIED
+ * heading with its `Based-On:` pin already set.
+ *
+ * THE PIN IS REBASE'S PIN, not a second rule for one. `requirementDigest` of
+ * the living requirement, selected by its `Requirement-ID:` exactly as
+ * `selectLiving` (commands/rebase/plan.ts) selects one, and written where
+ * `serializeRequirements` puts it — under the id line, where `pinEdit` inserts
+ * it too. So a scaffold followed by `loam rebase` reports every pin
+ * `unchanged`, and a living requirement that moves between this scaffold and
+ * the archive is `delta.baseline-stale`, exactly as if the author had copied
+ * and pinned it by hand at this moment. The gate is the same gate; only the
+ * typing went away.
+ *
+ * WHY THE BLOCK SHIPS LIVE, when every other template example ships inside a
+ * comment. Those examples are placeholder text nobody wrote, and a live one
+ * once archived a literal TODO into the living spec — so they declare nothing
+ * until a person copies them out. This block is the opposite: it is the
+ * fleet's own current text, and the one honest state for it to be in is the
+ * state archive would merge. Left unedited it merges as no change to the
+ * living wording, which is why the comment above it says to edit in place.
+ *
+ * ADDRESSED BY `Requirement-ID:` ONLY. A requirement without that line is
+ * addressed by its heading everywhere else, but a heading is free text with
+ * spaces in it and no grammar a flag value can be checked against; offering it
+ * here would teach identity-by-heading on the one path built to be typed.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { repoPath } from "../../core/envelope/json.js";
+import { NotUtf8DocumentError } from "../../core/kernel/document-bytes.js";
+import { parseRequirements, readRequirementsDocument } from "../../core/document/parse.js";
+import { REQUIREMENT_ID_RE, requirementDigest, serializeRequirements, withoutBaseline, } from "../../core/document/spec.js";
+import { compareIds, nearestIds } from "../../core/repo/entries.js";
+import { SPEC_AXES, servicePathsAt } from "../../core/repo/paths.js";
+import { enumeratedServices } from "../../core/repo/service-target.js";
+import { archSpecTemplate, specTemplate } from "./templates.js";
+/** Every identified requirement in one service's living spec files, one entry per (axis, requirement). */
+async function livingRequirements(docsDir, entry) {
+    const paths = servicePathsAt(entry.dir);
+    const found = [];
+    for (const axis of SPEC_AXES) {
+        const path = paths[axis.key];
+        if (!existsSync(path))
+            continue;
+        for (const r of parseRequirements(await readRequirementsDocument(path))) {
+            if (r.id === undefined)
+                continue;
+            // The pin is taken over the requirement WITHOUT any baseline it carries —
+            // a living document should hold none (archive strips them), and one that
+            // does must not end up with two `Based-On:` lines in the scaffold.
+            const living = withoutBaseline(r);
+            found.push({
+                id: r.id,
+                service: entry.id,
+                axis,
+                living: repoPath(docsDir, path),
+                requirement: { ...living, basedOn: requirementDigest(living) },
+            });
+        }
+    }
+    return found;
+}
+/**
+ * Which services OUTSIDE the touched set carry the id — read only on the
+ * refusal path, where a fleet-wide walk is paid once by a run that is about to
+ * stop anyway. The commonest way to miss is to name the right requirement and
+ * the wrong (or no) `--touches`, and the useful refusal names the service.
+ * An undecodable document there is skipped: this is a hint, not a grade.
+ */
+async function carriersElsewhere(docsDir, id, skip) {
+    const carriers = [];
+    for (const entry of await enumeratedServices(docsDir)) {
+        if (skip.has(entry.id))
+            continue;
+        try {
+            if ((await livingRequirements(docsDir, entry)).some((t) => t.id === id))
+                carriers.push(entry.id);
+        }
+        catch (err) {
+            if (!(err instanceof NotUtf8DocumentError))
+                throw err;
+        }
+    }
+    return carriers.sort(compareIds);
+}
+function unknownMessage(id, touched, known) {
+    const where = touched.length === 0
+        ? "this feature touches no service — name the one that owns it with --touches"
+        : `it names no requirement in the living specs of ${touched.map((s) => `'${s}'`).join(", ")}`;
+    const near = nearestIds(id, [...known]);
+    return (`--modifies '${id}': ${where}.` +
+        (near.length === 0 ? "" : ` Did you mean ${near.map((n) => `'${n}'`).join(" or ")}?`) +
+        " A requirement is addressed by its `Requirement-ID:` line; one without that line cannot be named here.");
+}
+/**
+ * Resolve every `--modifies` id against the living specs of the touched
+ * services, before anything is written. In flag order, each id once.
+ */
+export async function planModifies(docsDir, touched, ids) {
+    for (const id of ids) {
+        if (!REQUIREMENT_ID_RE.test(id)) {
+            return {
+                ok: false,
+                code: "invalid-option",
+                message: `--modifies '${id}' is not a Requirement-ID — it takes the value of a living requirement's \`Requirement-ID:\` line, not its heading.`,
+            };
+        }
+    }
+    const scope = new Set(touched);
+    let living = [];
+    try {
+        for (const entry of await enumeratedServices(docsDir)) {
+            if (scope.has(entry.id))
+                living = living.concat(await livingRequirements(docsDir, entry));
+        }
+    }
+    catch (err) {
+        if (!(err instanceof NotUtf8DocumentError))
+            throw err;
+        // A pin is a claim about text somebody read, and over a document loam could
+        // not decode it would be a digest of mojibake — `loam rebase` refuses the
+        // same document under the same code, and so does this, before any write.
+        return { ok: false, code: "merge-failed", message: `--modifies cannot copy from a living spec loam cannot read — nothing was scaffolded: ${err.message}` };
+    }
+    const targets = [];
+    for (const id of new Set(ids)) {
+        const hits = living.filter((t) => t.id === id);
+        if (hits.length === 1) {
+            targets.push(hits[0]);
+            continue;
+        }
+        if (hits.length > 1) {
+            // A Requirement-ID is unique inside ONE document, so two touched
+            // documents may both carry it (and a document that repeats one is its
+            // own finding, `delta.living-duplicate-requirement`). Picking one would
+            // be loam guessing which requirement the author means to rewrite.
+            return {
+                ok: false,
+                code: "invalid-option",
+                message: `--modifies '${id}' is a Requirement-ID in more than one living document this feature touches ` +
+                    `(${[...new Set(hits.map((t) => t.living))].join(", ")}), and an id is unique only inside its own document. ` +
+                    "Touch only the service whose requirement changes, and write the other service's delta by hand.",
+            };
+        }
+        const elsewhere = await carriersElsewhere(docsDir, id, scope);
+        const known = [...new Set(living.map((t) => t.id))];
+        return {
+            ok: false,
+            code: "unknown-target",
+            message: elsewhere.length > 0
+                ? `--modifies '${id}' is a requirement of ${elsewhere.map((s) => `'${s}'`).join(", ")}, which this feature does not touch — add --touches ${elsewhere[0]}.`
+                : unknownMessage(id, touched, known),
+        };
+    }
+    return { ok: true, targets };
+}
+/**
+ * The MODIFIED section one delta file carries, appended after the template's
+ * own comment. The guidance sits ABOVE the H2 on purpose: below it, before the
+ * first `### Requirement:`, it would be section prose of the very section the
+ * merge reads, and no comment there is worth that question.
+ */
+export function modifiedSection(featureId, targets) {
+    return `
+<!-- Each requirement below is the LIVING text, copied by \`loam new\` for an id you
+     named and pinned (Based-On:) to the version you are rewriting — the pin
+     \`loam rebase ${featureId}\` would write, so there is nothing to rebase unless the
+     living text moves first.
+     Edit it in place: a MODIFIED carries its full new text, and archive replaces the
+     living requirement with exactly what is here — left as copied, it changes nothing.
+     Keep the Requirement-ID: and Based-On: lines as they are. -->
+
+## MODIFIED Requirements
+
+${serializeRequirements(targets.map((t) => t.requirement))}`;
+}
+/**
+ * The delta files `--modifies` writes or extends, keyed as `new` keys its
+ * plan (relative to the feature directory). A business-axis target lands in
+ * the `spec.md` the touched service already gets; an architecture-axis target
+ * gets the `arch.spec.md` template a touched service is otherwise not handed,
+ * because the requirement it rewrites lives there.
+ */
+export function modifiedFiles(featureId, targets, planned) {
+    const out = {};
+    for (const t of targets) {
+        const rel = join("specs", t.service, t.axis.file);
+        if (rel in out)
+            continue;
+        const mine = targets.filter((other) => other.service === t.service && other.axis.key === t.axis.key);
+        const base = planned[rel] ?? (t.axis.key === "spec" ? specTemplate(featureId, t.service) : archSpecTemplate(featureId, t.service));
+        out[rel] = base + modifiedSection(featureId, mine);
+    }
+    return out;
+}
+//# sourceMappingURL=modifies.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modifies.js","sourceRoot":"","sources":["../../../src/commands/new/modifies.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam new --modifies <Req-ID>`: the small-change lane's one hand step,\n * done by the scaffold.\n *\n * A change that rewrites a requirement the fleet already has used to cost a\n * hand copy and a second command: the scaffold offered only the ADDED example\n * inside its comment, so the author copied the living requirement into a\n * `## MODIFIED Requirements` section by hand — most of a small delta is that\n * copy — and then ran `loam rebase` to pin it. This module does both at\n * scaffold time: it finds each named requirement in the living specs of the\n * services the feature touches and writes it, UNCOMMENTED, under a MODIFIED\n * heading with its `Based-On:` pin already set.\n *\n * THE PIN IS REBASE'S PIN, not a second rule for one. `requirementDigest` of\n * the living requirement, selected by its `Requirement-ID:` exactly as\n * `selectLiving` (commands/rebase/plan.ts) selects one, and written where\n * `serializeRequirements` puts it — under the id line, where `pinEdit` inserts\n * it too. So a scaffold followed by `loam rebase` reports every pin\n * `unchanged`, and a living requirement that moves between this scaffold and\n * the archive is `delta.baseline-stale`, exactly as if the author had copied\n * and pinned it by hand at this moment. The gate is the same gate; only the\n * typing went away.\n *\n * WHY THE BLOCK SHIPS LIVE, when every other template example ships inside a\n * comment. Those examples are placeholder text nobody wrote, and a live one\n * once archived a literal TODO into the living spec — so they declare nothing\n * until a person copies them out. This block is the opposite: it is the\n * fleet's own current text, and the one honest state for it to be in is the\n * state archive would merge. Left unedited it merges as no change to the\n * living wording, which is why the comment above it says to edit in place.\n *\n * ADDRESSED BY `Requirement-ID:` ONLY. A requirement without that line is\n * addressed by its heading everywhere else, but a heading is free text with\n * spaces in it and no grammar a flag value can be checked against; offering it\n * here would teach identity-by-heading on the one path built to be typed.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { repoPath } from \"../../core/envelope/json.js\";\nimport { NotUtf8DocumentError } from \"../../core/kernel/document-bytes.js\";\nimport { parseRequirements, readRequirementsDocument } from \"../../core/document/parse.js\";\nimport {\n  REQUIREMENT_ID_RE,\n  requirementDigest,\n  serializeRequirements,\n  withoutBaseline,\n  type Requirement,\n} from \"../../core/document/spec.js\";\nimport { compareIds, nearestIds, type ServiceEntry } from \"../../core/repo/entries.js\";\nimport { SPEC_AXES, servicePathsAt, type SpecAxis } from \"../../core/repo/paths.js\";\nimport { enumeratedServices } from \"../../core/repo/service-target.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { archSpecTemplate, specTemplate } from \"./templates.js\";\n\n/** One living requirement `--modifies` named, where it lives, and the pin it is scaffolded with. */\nexport interface ModifiedTarget {\n  readonly id: string;\n  readonly service: string;\n  readonly axis: SpecAxis;\n  /** The living document it was copied from, repo-relative — what a message names. */\n  readonly living: string;\n  /** The living requirement, its pin set — the block the delta carries. */\n  readonly requirement: Requirement;\n}\n\nexport type ModifiesPlan =\n  | { readonly ok: true; readonly targets: readonly ModifiedTarget[] }\n  | { readonly ok: false; readonly code: \"invalid-option\" | \"unknown-target\" | \"merge-failed\"; readonly message: string };\n\n/** Every identified requirement in one service's living spec files, one entry per (axis, requirement). */\nasync function livingRequirements(docsDir: DocsDir, entry: ServiceEntry): Promise<ModifiedTarget[]> {\n  const paths = servicePathsAt(entry.dir);\n  const found: ModifiedTarget[] = [];\n  for (const axis of SPEC_AXES) {\n    const path = paths[axis.key];\n    if (!existsSync(path)) continue;\n    for (const r of parseRequirements(await readRequirementsDocument(path))) {\n      if (r.id === undefined) continue;\n      // The pin is taken over the requirement WITHOUT any baseline it carries —\n      // a living document should hold none (archive strips them), and one that\n      // does must not end up with two `Based-On:` lines in the scaffold.\n      const living = withoutBaseline(r);\n      found.push({\n        id: r.id,\n        service: entry.id,\n        axis,\n        living: repoPath(docsDir, path),\n        requirement: { ...living, basedOn: requirementDigest(living) },\n      });\n    }\n  }\n  return found;\n}\n\n/**\n * Which services OUTSIDE the touched set carry the id — read only on the\n * refusal path, where a fleet-wide walk is paid once by a run that is about to\n * stop anyway. The commonest way to miss is to name the right requirement and\n * the wrong (or no) `--touches`, and the useful refusal names the service.\n * An undecodable document there is skipped: this is a hint, not a grade.\n */\nasync function carriersElsewhere(docsDir: DocsDir, id: string, skip: ReadonlySet<string>): Promise<string[]> {\n  const carriers: string[] = [];\n  for (const entry of await enumeratedServices(docsDir)) {\n    if (skip.has(entry.id)) continue;\n    try {\n      if ((await livingRequirements(docsDir, entry)).some((t) => t.id === id)) carriers.push(entry.id);\n    } catch (err) {\n      if (!(err instanceof NotUtf8DocumentError)) throw err;\n    }\n  }\n  return carriers.sort(compareIds);\n}\n\nfunction unknownMessage(id: string, touched: readonly string[], known: readonly string[]): string {\n  const where = touched.length === 0\n    ? \"this feature touches no service — name the one that owns it with --touches\"\n    : `it names no requirement in the living specs of ${touched.map((s) => `'${s}'`).join(\", \")}`;\n  const near = nearestIds(id, [...known]);\n  return (\n    `--modifies '${id}': ${where}.` +\n    (near.length === 0 ? \"\" : ` Did you mean ${near.map((n) => `'${n}'`).join(\" or \")}?`) +\n    \" A requirement is addressed by its `Requirement-ID:` line; one without that line cannot be named here.\"\n  );\n}\n\n/**\n * Resolve every `--modifies` id against the living specs of the touched\n * services, before anything is written. In flag order, each id once.\n */\nexport async function planModifies(\n  docsDir: DocsDir,\n  touched: readonly string[],\n  ids: readonly string[],\n): Promise<ModifiesPlan> {\n  for (const id of ids) {\n    if (!REQUIREMENT_ID_RE.test(id)) {\n      return {\n        ok: false,\n        code: \"invalid-option\",\n        message: `--modifies '${id}' is not a Requirement-ID — it takes the value of a living requirement's \\`Requirement-ID:\\` line, not its heading.`,\n      };\n    }\n  }\n  const scope = new Set(touched);\n  let living: ModifiedTarget[] = [];\n  try {\n    for (const entry of await enumeratedServices(docsDir)) {\n      if (scope.has(entry.id)) living = living.concat(await livingRequirements(docsDir, entry));\n    }\n  } catch (err) {\n    if (!(err instanceof NotUtf8DocumentError)) throw err;\n    // A pin is a claim about text somebody read, and over a document loam could\n    // not decode it would be a digest of mojibake — `loam rebase` refuses the\n    // same document under the same code, and so does this, before any write.\n    return { ok: false, code: \"merge-failed\", message: `--modifies cannot copy from a living spec loam cannot read — nothing was scaffolded: ${err.message}` };\n  }\n  const targets: ModifiedTarget[] = [];\n  for (const id of new Set(ids)) {\n    const hits = living.filter((t) => t.id === id);\n    if (hits.length === 1) {\n      targets.push(hits[0]!);\n      continue;\n    }\n    if (hits.length > 1) {\n      // A Requirement-ID is unique inside ONE document, so two touched\n      // documents may both carry it (and a document that repeats one is its\n      // own finding, `delta.living-duplicate-requirement`). Picking one would\n      // be loam guessing which requirement the author means to rewrite.\n      return {\n        ok: false,\n        code: \"invalid-option\",\n        message:\n          `--modifies '${id}' is a Requirement-ID in more than one living document this feature touches ` +\n          `(${[...new Set(hits.map((t) => t.living))].join(\", \")}), and an id is unique only inside its own document. ` +\n          \"Touch only the service whose requirement changes, and write the other service's delta by hand.\",\n      };\n    }\n    const elsewhere = await carriersElsewhere(docsDir, id, scope);\n    const known = [...new Set(living.map((t) => t.id))];\n    return {\n      ok: false,\n      code: \"unknown-target\",\n      message: elsewhere.length > 0\n        ? `--modifies '${id}' is a requirement of ${elsewhere.map((s) => `'${s}'`).join(\", \")}, which this feature does not touch — add --touches ${elsewhere[0]}.`\n        : unknownMessage(id, touched, known),\n    };\n  }\n  return { ok: true, targets };\n}\n\n/**\n * The MODIFIED section one delta file carries, appended after the template's\n * own comment. The guidance sits ABOVE the H2 on purpose: below it, before the\n * first `### Requirement:`, it would be section prose of the very section the\n * merge reads, and no comment there is worth that question.\n */\nexport function modifiedSection(featureId: string, targets: readonly ModifiedTarget[]): string {\n  return `\n<!-- Each requirement below is the LIVING text, copied by \\`loam new\\` for an id you\n     named and pinned (Based-On:) to the version you are rewriting — the pin\n     \\`loam rebase ${featureId}\\` would write, so there is nothing to rebase unless the\n     living text moves first.\n     Edit it in place: a MODIFIED carries its full new text, and archive replaces the\n     living requirement with exactly what is here — left as copied, it changes nothing.\n     Keep the Requirement-ID: and Based-On: lines as they are. -->\n\n## MODIFIED Requirements\n\n${serializeRequirements(targets.map((t) => t.requirement))}`;\n}\n\n/**\n * The delta files `--modifies` writes or extends, keyed as `new` keys its\n * plan (relative to the feature directory). A business-axis target lands in\n * the `spec.md` the touched service already gets; an architecture-axis target\n * gets the `arch.spec.md` template a touched service is otherwise not handed,\n * because the requirement it rewrites lives there.\n */\nexport function modifiedFiles(\n  featureId: string,\n  targets: readonly ModifiedTarget[],\n  planned: Readonly<Record<string, string>>,\n): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const t of targets) {\n    const rel = join(\"specs\", t.service, t.axis.file);\n    if (rel in out) continue;\n    const mine = targets.filter((other) => other.service === t.service && other.axis.key === t.axis.key);\n    const base = planned[rel] ?? (t.axis.key === \"spec\" ? specTemplate(featureId, t.service) : archSpecTemplate(featureId, t.service));\n    out[rel] = base + modifiedSection(featureId, mine);\n  }\n  return out;\n}\n"]}

package/dist/commands/new/new.js

@@ -1,20 +1,24 @@
+import { existsSync } from "node:fs";
 import {} from "../../core/staging/writes.js";
 import { commitScaffold } from "./commit.js";
 import { join } from "node:path";
-import { loadConfig } from "../../core/envelope/config.js";
 import { parseFeatureId } from "../../core/kernel/ids/feature.js";
 import { parseServiceIds } from "../../core/kernel/ids/service.js";
-import { emitJson, fail, repoPath, reportNoConfig } from "../../core/envelope/json.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 } from "../../core/repo/paths.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 { archSpecTemplate, capabilityDeltaTemplate, deltaTemplate, intentTemplate, openapiTemplate, specTemplate, } from "./templates.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")
@@ -42,6 +46,9 @@ export function registerNew(program) {
         // 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;
@@ -92,12 +99,9 @@ export function registerNew(program) {
             if (problem !== null)
                 return fail(json, "invalid-option", problem);
         }
-        const loaded = await loadConfig();
-        if (loaded.kind !== "loaded") {
-            reportNoConfig(json, loaded);
+        const config = await configOrRefuse(json);
+        if (config === null)
             return;
-        }
-        const config = loaded.config;
         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
@@ -122,13 +126,26 @@ export function registerNew(program) {
         const created = new Set(newServices.ids);
         const touched = touches.ids.filter((s) => !created.has(s));
         const dir = join(featuresDir(docsDir), dirName);
-        const files = {
-            "intent.md": intentTemplate(featureId, opts.title),
-            "delta.likec4": deltaTemplate(featureId, touched, [...created]),
-        };
+        // 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
@@ -218,8 +235,17 @@ export function registerNew(program) {
         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.");
@@ -266,6 +292,26 @@ async function unknownServiceNotes(docsDir, touched) {
     }
     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                                                              */
 /* ------------------------------------------------------------------ */
@@ -279,5 +325,4 @@ function slugify(text) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
 }
-/** A LikeC4 identifier for a service name: `payment-split-service` -> `paymentSplitService`. */
 //# sourceMappingURL=new.js.map

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

@@ -1 +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 { type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { commitScaffold } from \"./commit.js\";\nimport { join } from \"node:path\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { type FeatureId, parseFeatureId } from \"../../core/kernel/ids/feature.js\";\nimport { parseServiceIds } from \"../../core/kernel/ids/service.js\";\nimport { emitJson, fail, repoPath, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { UnsafePathError, resolveInside } from \"../../core/kernel/path-safety.js\";\nimport { featureIdFromDirName, nearestIds } from \"../../core/repo/entries.js\";\nimport { featuresDir } from \"../../core/repo/paths.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 {\n  archSpecTemplate,\n  capabilityDeltaTemplate,\n  deltaTemplate,\n  intentTemplate,\n  openapiTemplate,\n  specTemplate,\n} from \"./templates.js\";\n\ninterface NewOptions {\n  title?: string;\n  touches: string[];\n  newService: string[];\n  capability: 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    .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 loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\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      const files: Record<string, string> = {\n        \"intent.md\": intentTemplate(featureId, opts.title),\n        \"delta.likec4\": deltaTemplate(featureId, touched, [...created]),\n      };\n      for (const svc of [...touched, ...created]) {\n        files[join(\"specs\", svc, \"spec.md\")] = specTemplate(featureId, svc);\n      }\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 note of notes) console.log(`\\n  note: ${note}`);\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/* 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\n/** A LikeC4 identifier for a service name: `payment-split-service` -> `paymentSplitService`. */\n"]}
+{"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"]}