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

package/dist/commands/migrate-openspec/print.js

@@ -0,0 +1,89 @@
+/**
+ * The human view of an inventory, shared by both verbs.
+ *
+ * `audit-openspec` and `migrate-openspec` print the same block and differ only
+ * in the word above it, so the renderer takes the mode rather than existing
+ * twice — the audit's readiness line and the migration's are the same claim and
+ * have to stay the same claim.
+ *
+ * The local `plural` is not a duplicate of `../format.ts`'s. That one spells
+ * the regular English plural only, and says so: an irregular noun belongs at
+ * the call site. "capability"/"capabilities" is exactly that noun, so this
+ * renderer carries the two-form variant instead of misspelling a count.
+ */
+import {} from "../../core/openspec/model/model.js";
+function plural(count, one, many = `${one}s`) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+export function printInventory(inventory, mode) {
+    const status = inventory.ready
+        ? "ready"
+        : inventory.mechanicallyCompatible
+            ? "compatible; explicit mapping/identity decisions remain"
+            : "living or active blockers found";
+    console.log(`OpenSpec ${mode} inventory — ${status}`);
+    console.log(`  root          ${inventory.root}`);
+    console.log(`  baseline      release ${inventory.baselines.release.version}@${inventory.baselines.release.commit} · main canary ${inventory.baselines.mainCanary.commit.slice(0, 7)}`);
+    console.log(`  living       ${plural(inventory.living.capabilities.length, "capability", "capabilities")} · ${plural(inventory.living.specFiles, "spec file")} · ${plural(inventory.living.requirements, "requirement")} · ${plural(inventory.living.scenarios, "scenario")}`);
+    console.log(`  changes      ${inventory.changes.counts.active} active · ${inventory.changes.counts.archived} archived`);
+    console.log(`  readiness    living ${inventory.readiness.living.compatible ? "ok" : "blocked"} · active ${inventory.readiness.active.compatible ? "ok" : "blocked"} · source ${inventory.readiness.sourceCurrent ? "current" : "stale"} · capabilities ${inventory.readiness.mappingsResolved ? "resolved" : "open"} · changes ${inventory.readiness.changesResolved ? "resolved" : "open"} · dispositions ${inventory.readiness.dispositionsResolved ? "resolved" : "open"} · archive ${inventory.archiveDiagnostics.length} diagnostic(s)`);
+    if (inventory.needsMapping.length > 0) {
+        console.log("\n  capability → service decisions");
+        for (const decision of inventory.needsMapping) {
+            console.log(`    ? ${decision.capability} → ${decision.suggestedService}  [${decision.status}]`);
+        }
+    }
+    if (inventory.needsChangeMapping.length > 0) {
+        console.log("\n  change → feature decisions");
+        for (const decision of inventory.needsChangeMapping) {
+            console.log(`    ? ${decision.change} → ${decision.suggestedFeature}  [${decision.status}]`);
+        }
+    }
+    const activeRenames = inventory.renamed.filter((rename) => rename.scope === "active");
+    if (activeRenames.length > 0) {
+        console.log("\n  RENAMED identity decisions");
+        for (const rename of activeRenames) {
+            console.log(`    ${rename.status === "mapped" ? "✓" : "?"} ${rename.key}  ${rename.from ?? "<missing FROM>"} → ${rename.to ?? "<missing TO>"}${rename.requirementId ? `  [${rename.requirementId}]` : ""}`);
+        }
+    }
+    if (inventory.needsDisposition.length > 0) {
+        console.log(`\n  authored artifact decisions (${inventory.needsDisposition.length})`);
+        for (const decision of inventory.needsDisposition.slice(0, 12)) {
+            console.log(`    ? ${decision.path} → ${decision.suggestedDisposition}  [${decision.status}]`);
+        }
+        if (inventory.needsDisposition.length > 12) {
+            console.log(`    … ${inventory.needsDisposition.length - 12} more in --json/mapping output`);
+        }
+    }
+    if (inventory.mappingIssues.length > 0) {
+        console.log("\n  mapping issues");
+        for (const item of inventory.mappingIssues)
+            console.log(`    ✗ ${item.code}  ${item.message}`);
+    }
+    if (inventory.unsupported.length > 0) {
+        console.log("\n  living/active blockers");
+        for (const item of inventory.unsupported) {
+            console.log(`    ✗ ${item.code}  ${item.path} — ${item.message}`);
+        }
+    }
+    if (inventory.archiveDiagnostics.length > 0) {
+        console.log(`\n  archive diagnostics (non-blocking, ${inventory.archiveDiagnostics.length})`);
+        for (const item of inventory.archiveDiagnostics.slice(0, 12)) {
+            console.log(`    · ${item.code}  ${item.path} — ${item.message}`);
+        }
+        if (inventory.archiveDiagnostics.length > 12) {
+            console.log(`    … ${inventory.archiveDiagnostics.length - 12} more in --json output`);
+        }
+    }
+    const dispositions = new Map();
+    for (const artifact of inventory.artifacts) {
+        dispositions.set(artifact.disposition, (dispositions.get(artifact.disposition) ?? 0) + 1);
+    }
+    if (dispositions.size > 0) {
+        console.log("\n  artifact disposition");
+        for (const [disposition, count] of [...dispositions].sort(([a], [b]) => a.localeCompare(b))) {
+            console.log(`    · ${disposition}  ${count}`);
+        }
+    }
+}
+//# sourceMappingURL=print.js.map

package/dist/commands/migrate-openspec/print.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"print.js","sourceRoot":"","sources":["../../../src/commands/migrate-openspec/print.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The human view of an inventory, shared by both verbs.\n *\n * `audit-openspec` and `migrate-openspec` print the same block and differ only\n * in the word above it, so the renderer takes the mode rather than existing\n * twice — the audit's readiness line and the migration's are the same claim and\n * have to stay the same claim.\n *\n * The local `plural` is not a duplicate of `../format.ts`'s. That one spells\n * the regular English plural only, and says so: an irregular noun belongs at\n * the call site. \"capability\"/\"capabilities\" is exactly that noun, so this\n * renderer carries the two-form variant instead of misspelling a count.\n */\nimport { type OpenSpecInventory } from \"../../core/openspec/model/model.js\";\n\nfunction plural(count: number, one: string, many = `${one}s`): string {\n  return `${count} ${count === 1 ? one : many}`;\n}\n\nexport function printInventory(inventory: OpenSpecInventory, mode: \"audit\" | \"migration\"): void {\n  const status = inventory.ready\n    ? \"ready\"\n    : inventory.mechanicallyCompatible\n      ? \"compatible; explicit mapping/identity decisions remain\"\n      : \"living or active blockers found\";\n  console.log(`OpenSpec ${mode} inventory — ${status}`);\n  console.log(`  root          ${inventory.root}`);\n  console.log(\n    `  baseline      release ${inventory.baselines.release.version}@${inventory.baselines.release.commit} · main canary ${inventory.baselines.mainCanary.commit.slice(0, 7)}`,\n  );\n  console.log(\n    `  living       ${plural(inventory.living.capabilities.length, \"capability\", \"capabilities\")} · ${plural(inventory.living.specFiles, \"spec file\")} · ${plural(inventory.living.requirements, \"requirement\")} · ${plural(inventory.living.scenarios, \"scenario\")}`,\n  );\n  console.log(\n    `  changes      ${inventory.changes.counts.active} active · ${inventory.changes.counts.archived} archived`,\n  );\n  console.log(\n    `  readiness    living ${inventory.readiness.living.compatible ? \"ok\" : \"blocked\"} · active ${inventory.readiness.active.compatible ? \"ok\" : \"blocked\"} · source ${inventory.readiness.sourceCurrent ? \"current\" : \"stale\"} · capabilities ${inventory.readiness.mappingsResolved ? \"resolved\" : \"open\"} · changes ${inventory.readiness.changesResolved ? \"resolved\" : \"open\"} · dispositions ${inventory.readiness.dispositionsResolved ? \"resolved\" : \"open\"} · archive ${inventory.archiveDiagnostics.length} diagnostic(s)`,\n  );\n\n  if (inventory.needsMapping.length > 0) {\n    console.log(\"\\n  capability → service decisions\");\n    for (const decision of inventory.needsMapping) {\n      console.log(`    ? ${decision.capability} → ${decision.suggestedService}  [${decision.status}]`);\n    }\n  }\n  if (inventory.needsChangeMapping.length > 0) {\n    console.log(\"\\n  change → feature decisions\");\n    for (const decision of inventory.needsChangeMapping) {\n      console.log(`    ? ${decision.change} → ${decision.suggestedFeature}  [${decision.status}]`);\n    }\n  }\n  const activeRenames = inventory.renamed.filter((rename) => rename.scope === \"active\");\n  if (activeRenames.length > 0) {\n    console.log(\"\\n  RENAMED identity decisions\");\n    for (const rename of activeRenames) {\n      console.log(\n        `    ${rename.status === \"mapped\" ? \"✓\" : \"?\"} ${rename.key}  ${rename.from ?? \"<missing FROM>\"} → ${rename.to ?? \"<missing TO>\"}${rename.requirementId ? `  [${rename.requirementId}]` : \"\"}`,\n      );\n    }\n  }\n  if (inventory.needsDisposition.length > 0) {\n    console.log(`\\n  authored artifact decisions (${inventory.needsDisposition.length})`);\n    for (const decision of inventory.needsDisposition.slice(0, 12)) {\n      console.log(`    ? ${decision.path} → ${decision.suggestedDisposition}  [${decision.status}]`);\n    }\n    if (inventory.needsDisposition.length > 12) {\n      console.log(`    … ${inventory.needsDisposition.length - 12} more in --json/mapping output`);\n    }\n  }\n  if (inventory.mappingIssues.length > 0) {\n    console.log(\"\\n  mapping issues\");\n    for (const item of inventory.mappingIssues) console.log(`    ✗ ${item.code}  ${item.message}`);\n  }\n  if (inventory.unsupported.length > 0) {\n    console.log(\"\\n  living/active blockers\");\n    for (const item of inventory.unsupported) {\n      console.log(`    ✗ ${item.code}  ${item.path} — ${item.message}`);\n    }\n  }\n  if (inventory.archiveDiagnostics.length > 0) {\n    console.log(`\\n  archive diagnostics (non-blocking, ${inventory.archiveDiagnostics.length})`);\n    for (const item of inventory.archiveDiagnostics.slice(0, 12)) {\n      console.log(`    · ${item.code}  ${item.path} — ${item.message}`);\n    }\n    if (inventory.archiveDiagnostics.length > 12) {\n      console.log(`    … ${inventory.archiveDiagnostics.length - 12} more in --json output`);\n    }\n  }\n  const dispositions = new Map<string, number>();\n  for (const artifact of inventory.artifacts) {\n    dispositions.set(artifact.disposition, (dispositions.get(artifact.disposition) ?? 0) + 1);\n  }\n  if (dispositions.size > 0) {\n    console.log(\"\\n  artifact disposition\");\n    for (const [disposition, count] of [...dispositions].sort(([a], [b]) => a.localeCompare(b))) {\n      console.log(`    · ${disposition}  ${count}`);\n    }\n  }\n}\n"]}

package/dist/commands/new/commit.js

@@ -0,0 +1,76 @@
+/**
+ * The scaffold's commit window: lock, recover, the one existence check, the
+ * exclusive-create transaction. Split from new.ts on the same seam vouch's
+ * commitStamp and gherkin's commitEmission sit on — everything in here holds
+ * the docs lock, nothing outside it does — and, as there, the split keeps the
+ * window's extent visible in the code shape. This module prints nothing; the
+ * caller renders every arm.
+ */
+import {} from "../../core/repo/entries.js";
+import {} from "../../core/kernel/ids/dirs.js";
+import { resolveFeature } from "../../core/repo/repo.js";
+import { DocsRepoUnavailableError } from "../../core/repo/state.js";
+import { stageWrites } from "../../core/staging/commit.js";
+import { InterruptedCommitError } from "../../core/staging/interrupted.js";
+import { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import { commitStaged } from "../../core/staging/txn/transaction.js";
+import {} from "../../core/staging/writes.js";
+export async function commitScaffold(docsDir, featureId, writes) {
+    // The commit window holds the docs lock: two `new`s for one id serialise
+    // into a stable already-exists, and a predecessor's interrupted commit is
+    // rolled forward (or refused) before this one stages anything.
+    let releaseLock;
+    try {
+        releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);
+    }
+    catch (err) {
+        if (err instanceof DocsBusyError)
+            return { ok: false, code: "docs-busy", message: err.message };
+        throw err;
+    }
+    try {
+        let recovered;
+        try {
+            recovered = await recoverInterruptedCommit(docsDir);
+        }
+        catch (err) {
+            if (!(err instanceof InterruptedCommitError))
+                throw err;
+            return { ok: false, code: "commit-interrupted", message: err.message };
+        }
+        // The one existence check, UNDER the lock and AFTER recovery: two racing
+        // runs serialise on it, and a recovered half-scaffold has been completed
+        // by the recovery above, so this refusal is truthful.
+        let existing;
+        try {
+            existing = await resolveFeature(docsDir, featureId, "include");
+        }
+        catch (err) {
+            // The command's gate already refused both broken states, so reaching
+            // here means the docs repo went away between that check and this read.
+            // Same breach, same two codes — the alternative is a stack trace under
+            // `internal` that names neither.
+            if (!(err instanceof DocsRepoUnavailableError))
+                throw err;
+            return { ok: false, repoGone: err };
+        }
+        if (existing)
+            return { ok: false, code: "already-exists", existing, recovered };
+        const staged = await stageWrites(writes);
+        const committed = await commitStaged({ root: docsDir, command: "new", rerun: `loam new ${featureId}`, target: featureId }, staged, "scaffolded");
+        if (!committed.ok) {
+            // A lost exclusive-create race IS the feature existing: the other `new`
+            // won, and this refusal is the same stable answer the check above gives
+            // when it sees the winner first.
+            return committed.raced
+                ? { ok: false, code: "already-exists", existing: null, recovered }
+                : { ok: false, code: committed.code, message: committed.message };
+        }
+        return { ok: true, recovered };
+    }
+    finally {
+        await releaseLock();
+    }
+}
+//# sourceMappingURL=commit.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../src/commands/new/commit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The scaffold's commit window: lock, recover, the one existence check, the\n * exclusive-create transaction. Split from new.ts on the same seam vouch's\n * commitStamp and gherkin's commitEmission sit on — everything in here holds\n * the docs lock, nothing outside it does — and, as there, the split keeps the\n * window's extent visible in the code shape. This module prints nothing; the\n * caller renders every arm.\n */\nimport { type FeatureEntry } from \"../../core/repo/entries.js\";\nimport { type DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { resolveFeature } from \"../../core/repo/repo.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { type CommitRecovery, InterruptedCommitError } from \"../../core/staging/interrupted.js\";\nimport { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { recoverInterruptedCommit } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\n\nexport type ScaffoldCommit =\n  | { ok: true; recovered: CommitRecovery | null }\n  | {\n      ok: false;\n      code: \"docs-busy\" | \"commit-interrupted\" | \"merge-failed\" | \"rollback-incomplete\";\n      message: string;\n    }\n  /** The feature exists — found by the under-lock check, or by losing the create race. */\n  | { ok: false; code: \"already-exists\"; existing: FeatureEntry | null; recovered: CommitRecovery | null }\n  /**\n   * The docs repo went away between the command's gate and the locked read.\n   * Deliberately NOT a `code:` arm: the caller renders it through the shared\n   * docs-repo reporter, and the codes-drift collector reads every `code:`\n   * literal as a stable emission — which this discriminant is not.\n   */\n  | { ok: false; repoGone: DocsRepoUnavailableError };\n\nexport async function commitScaffold(\n  docsDir: DocsDir,\n  featureId: string,\n  writes: PlannedWrite[],\n): Promise<ScaffoldCommit> {\n  // The commit window holds the docs lock: two `new`s for one id serialise\n  // into a stable already-exists, and a predecessor's interrupted commit is\n  // rolled forward (or refused) before this one stages anything.\n  let releaseLock: () => Promise<void>;\n  try {\n    releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);\n  } catch (err) {\n    if (err instanceof DocsBusyError) return { ok: false, code: \"docs-busy\", message: err.message };\n    throw err;\n  }\n  try {\n    let recovered: CommitRecovery | null;\n    try {\n      recovered = await recoverInterruptedCommit(docsDir);\n    } catch (err) {\n      if (!(err instanceof InterruptedCommitError)) throw err;\n      return { ok: false, code: \"commit-interrupted\", message: err.message };\n    }\n    // The one existence check, UNDER the lock and AFTER recovery: two racing\n    // runs serialise on it, and a recovered half-scaffold has been completed\n    // by the recovery above, so this refusal is truthful.\n    let existing: FeatureEntry | null;\n    try {\n      existing = await resolveFeature(docsDir, featureId, \"include\");\n    } catch (err) {\n      // The command's gate already refused both broken states, so reaching\n      // here means the docs repo went away between that check and this read.\n      // Same breach, same two codes — the alternative is a stack trace under\n      // `internal` that names neither.\n      if (!(err instanceof DocsRepoUnavailableError)) throw err;\n      return { ok: false, repoGone: err };\n    }\n    if (existing) return { ok: false, code: \"already-exists\", existing, recovered };\n    const staged = await stageWrites(writes);\n    const committed = await commitStaged(\n      { root: docsDir, command: \"new\", rerun: `loam new ${featureId}`, target: featureId },\n      staged,\n      \"scaffolded\",\n    );\n    if (!committed.ok) {\n      // A lost exclusive-create race IS the feature existing: the other `new`\n      // won, and this refusal is the same stable answer the check above gives\n      // when it sees the winner first.\n      return committed.raced\n        ? { ok: false, code: \"already-exists\", existing: null, recovered }\n        : { ok: false, code: committed.code, message: committed.message };\n    }\n    return { ok: true, recovered };\n  } finally {\n    await releaseLock();\n  }\n}\n"]}

package/dist/commands/new/new.js

@@ -0,0 +1,283 @@
+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 { UnsafePathError, resolveInside } from "../../core/kernel/path-safety.js";
+import { featureIdFromDirName, nearestIds } from "../../core/repo/entries.js";
+import { featuresDir } from "../../core/repo/paths.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";
+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, [])
+        .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 loaded = await loadConfig();
+        if (loaded.kind !== "loaded") {
+            reportNoConfig(json, loaded);
+            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
+        // 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);
+        const files = {
+            "intent.md": intentTemplate(featureId, opts.title),
+            "delta.likec4": deltaTemplate(featureId, touched, [...created]),
+        };
+        for (const svc of [...touched, ...created]) {
+            files[join("specs", svc, "spec.md")] = specTemplate(featureId, svc);
+        }
+        // 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 note of notes)
+            console.log(`\n  note: ${note}`);
+        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;
+}
+/* ------------------------------------------------------------------ */
+/* 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, "");
+}
+/** A LikeC4 identifier for a service name: `payment-split-service` -> `paymentSplitService`. */
+//# 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 { 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"]}