@gonrocca/nodd 0.1.0

package/extensions/nodd-models.test.ts

@@ -0,0 +1,174 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { MECHANISM_PLACEHOLDER } from "../src/models/slots.ts";
+import register, { runModelsCommand, type ConfigIo } from "./nodd-models.ts";
+
+const registry = {
+  getAll: () => [
+    { provider: "anthropic", id: "claude-sonnet-4-5" },
+    { provider: "anthropic", id: "claude-opus-4-1" },
+    { provider: "openai-codex", id: "gpt-5-codex" },
+  ],
+};
+
+function memoryIo(initial: Record<string, unknown> = {}): ConfigIo & { writes: Record<string, unknown>[] } {
+  let data = { ...initial };
+  const writes: Record<string, unknown>[] = [];
+  return {
+    writes,
+    readConfig: () => ({ ...data }),
+    writeConfig: (next) => {
+      data = next;
+      writes.push(next);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The display
+// ---------------------------------------------------------------------------
+test("the no-arg output lists all seven steps with the four mechanisms marked", () => {
+  const io = memoryIo({ models: { implement: "anthropic/claude-opus-4-1" } });
+  const output = runModelsCommand("", io, registry);
+
+  for (const step of ["authorize", "explore", "resolve-uncertainty", "classify", "track", "implement", "close"]) {
+    assert.ok(output.includes(step), `${step} must be listed`);
+  }
+  for (const mechanism of ["authorize", "classify", "track", "close"]) {
+    const row = output.split("\n").find((line) => line.includes(mechanism))!;
+    assert.ok(row.includes(MECHANISM_PLACEHOLDER), `${mechanism} must be marked as a mechanism: ${row}`);
+  }
+  assert.ok(output.includes("anthropic/claude-opus-4-1"), "an assigned slot shows its model");
+  assert.equal(io.writes.length, 0, "displaying writes nothing");
+});
+
+test("the two global slots are listed alongside the steps", () => {
+  const output = runModelsCommand("", memoryIo(), registry);
+  assert.ok(output.includes("default"));
+  assert.ok(output.includes("orchestrator"));
+});
+
+// ---------------------------------------------------------------------------
+// Direct assignment
+// ---------------------------------------------------------------------------
+test("a valid assignment writes only models.implement and preserves unrelated keys", () => {
+  const io = memoryIo({
+    models: { explore: "anthropic/claude-sonnet-4-5" },
+    gates: { track: { enabled: false } },
+    somethingElse: { deep: [1, 2, 3] },
+  });
+
+  const output = runModelsCommand("implement=anthropic/claude-opus-4-1", io, registry);
+  assert.equal(io.writes.length, 1, "a valid assignment writes exactly once");
+
+  const written = io.writes[0];
+  assert.deepEqual(written.models, {
+    explore: "anthropic/claude-sonnet-4-5",
+    implement: "anthropic/claude-opus-4-1",
+  });
+  assert.deepEqual(written.gates, { track: { enabled: false } }, "gate flags survive a model write");
+  assert.deepEqual(written.somethingElse, { deep: [1, 2, 3] }, "an unknown key survives byte-for-byte");
+  assert.match(output, /implement/);
+});
+
+test("classify=x/y is rejected as a mechanism and writes nothing", () => {
+  const io = memoryIo();
+  const output = runModelsCommand("classify=anthropic/claude-opus-4-1", io, registry);
+  assert.match(output, /mecanismo/);
+  assert.equal(io.writes.length, 0);
+});
+
+test("an unknown model is rejected against the live registry and writes nothing", () => {
+  const io = memoryIo();
+  assert.match(runModelsCommand("implement=unknown/model", io, registry), /provider desconocido/);
+  assert.match(runModelsCommand("implement=anthropic/gpt-9", io, registry), /modelo desconocido/);
+  assert.equal(io.writes.length, 0);
+});
+
+test("an unparseable argument reports usage and writes nothing", () => {
+  const io = memoryIo();
+  assert.match(runModelsCommand("implement", io, registry), /uso/i);
+  assert.equal(io.writes.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// Profiles, through the same command
+// ---------------------------------------------------------------------------
+test("profile new writes once and activates the profile", () => {
+  const io = memoryIo({ models: { implement: "anthropic/claude-opus-4-1" } });
+  const output = runModelsCommand("profile new fast", io, registry);
+  assert.equal(io.writes.length, 1);
+  assert.equal(io.writes[0].activeProfile, "fast");
+  assert.match(output, /fast/);
+});
+
+test("profile list writes nothing", () => {
+  const io = memoryIo({ profiles: { fast: { models: {} } }, activeProfile: "fast" });
+  const output = runModelsCommand("profile list", io, registry);
+  assert.ok(output.includes("fast"));
+  assert.equal(io.writes.length, 0);
+});
+
+test("editing a slot with a profile active mirrors into that profile", () => {
+  const io = memoryIo({
+    models: { implement: "anthropic/claude-sonnet-4-5" },
+    profiles: { fast: { models: { implement: "anthropic/claude-sonnet-4-5" } } },
+    activeProfile: "fast",
+  });
+  runModelsCommand("implement=anthropic/claude-opus-4-1", io, registry);
+  assert.deepEqual(
+    (io.writes[0].profiles as Record<string, unknown>).fast,
+    { models: { implement: "anthropic/claude-opus-4-1" } },
+  );
+});
+
+// ---------------------------------------------------------------------------
+// The picker host
+// ---------------------------------------------------------------------------
+test("quitting the picker produces zero writes; saving writes once", async () => {
+  const quitIo = memoryIo();
+  await register.runPicker({ type: "quit" }, quitIo);
+  assert.equal(quitIo.writes.length, 0, "quit writes nothing");
+
+  const saveIo = memoryIo({ unrelated: true });
+  await register.runPicker({ type: "save", models: { implement: "anthropic/claude-opus-4-1" } }, saveIo);
+  assert.equal(saveIo.writes.length, 1);
+  assert.deepEqual(saveIo.writes[0].models, { implement: "anthropic/claude-opus-4-1" });
+  assert.equal(saveIo.writes[0].unrelated, true, "the picker's save preserves unrelated keys");
+});
+
+test("the command is registered with pi under its own name", () => {
+  const commands = new Map<string, unknown>();
+  register({ registerCommand: (name: string, options: unknown) => commands.set(name, options) } as never);
+  assert.ok(commands.has("nodd-models"), "the command must be /nodd-models, never /zero-models");
+  assert.ok(!commands.has("zero-models"));
+});
+
+test("the picker component renders rows and is a plain object, no TUI import", () => {
+  const component = register.createComponent(
+    { models: { implement: "anthropic/claude-opus-4-1" }, groups: new Map([["anthropic", ["claude-opus-4-1"]]]) },
+    () => {},
+  );
+  const lines = component.render(80);
+  assert.ok(Array.isArray(lines), "render returns string[]");
+  assert.ok(lines.length > 7, "every slot row is rendered");
+  assert.ok(lines.some((line) => line.includes(MECHANISM_PLACEHOLDER)), "mechanism rows are visible in the picker");
+  assert.ok(lines.some((line) => line.includes("anthropic/claude-opus-4-1")));
+});
+
+// ---------------------------------------------------------------------------
+// The absolute rule
+// ---------------------------------------------------------------------------
+test("this extension imports no TUI package, as a value or as a type", () => {
+  const source = readFileSync(new URL("./nodd-models.ts", import.meta.url), "utf8");
+  const forbidden = `@earendil-works/${["pi", "tui"].join("-")}`;
+  assert.ok(!source.includes(forbidden), "not a value import, not an import type, not a string");
+  assert.ok(/interface Component/.test(source), "the component contract is declared locally");
+});
+
+test("nothing in this extension names forge's config file", () => {
+  const source = readFileSync(new URL("./nodd-models.ts", import.meta.url), "utf8");
+  assert.ok(!source.includes(`zero${"."}json`), "NODD never opens forge's config");
+  assert.ok(source.includes("nodd.json") || source.includes("noddConfigPath"), "it uses its own");
+});

package/extensions/nodd-models.ts

@@ -0,0 +1,253 @@
+// `/nodd-models` — a deterministic handler, not a prompt.
+//
+// Adapted from `zero-models.ts:929-1161`. It owns its own command name and its
+// own file: forge's phase models stay `/zero-models`' business, and
+// `~/.pi/nodd.json` is the only file this touches.
+//
+// **The no-TUI rule is absolute** (`zero-models.ts:22-32`): this file does not
+// import pi's TUI package at all — not a value import, not an `import type`, and
+// not even as a string, which is why the name is not written here.
+// `ctx.ui.custom`'s factory only needs an object exposing
+// `render(width): string[]`, so the contract is declared locally below. A stray
+// ambient specifier would crash `node --test` with `ERR_MODULE_NOT_FOUND`, and
+// the test file imports this module directly.
+
+/** What `ctx.ui.custom()`'s factory must return. Declared locally on purpose. */
+interface Component {
+  render(width: number): string[];
+  handleInput?(data: string): void;
+  invalidate?(): void;
+}
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { mergeConfig, noddConfigPath } from "../src/config.ts";
+import { SLOT_ROWS } from "../src/models/slots.ts";
+import { assignmentPatch, groupByProvider, parseAssignment, validateAssignment, type RegistryModel } from "../src/models/assign.ts";
+import { applyProfileCommand, isValidProfileName, mirrorToActiveProfile, readActiveProfile, readProfiles } from "../src/models/profiles.ts";
+import { createPickerState, enter, moveCursor, renderRows, stage, type EnterResult, type PickerState } from "../src/models/picker.ts";
+
+export type ConfigIo = {
+  readConfig(): Record<string, unknown>;
+  writeConfig(next: Record<string, unknown>): void;
+};
+
+export function fileConfigIo(path: string = noddConfigPath()): ConfigIo {
+  return {
+    readConfig() {
+      try {
+        return JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+      } catch {
+        return {};
+      }
+    },
+    writeConfig(next) {
+      writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    },
+  };
+}
+
+type ModelRegistry = { getAll(): RegistryModel[] };
+
+const USAGE =
+  "uso: /nodd-models · /nodd-models <slot>=<provider>/<modelo> · /nodd-models profile [list|new <n>|save [n]|use <n>|delete <n>]";
+
+function groupsFrom(registry: ModelRegistry | undefined): Map<string, string[]> {
+  try {
+    const all = registry?.getAll?.();
+    return all && all.length > 0 ? groupByProvider(all) : new Map();
+  } catch {
+    // A registry that throws is a registry we do not have. Validation degrades
+    // to permissive rather than making the command unusable.
+    return new Map();
+  }
+}
+
+function currentModels(raw: Record<string, unknown>): Record<string, string> {
+  const models = raw.models;
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(typeof models === "object" && models !== null ? models : {})) {
+    if (typeof value === "string") out[key] = value;
+  }
+  return out;
+}
+
+/** The slot table: every canonical step, with the mechanisms marked. */
+function renderTable(raw: Record<string, unknown>): string {
+  const models = currentModels(raw);
+  const width = Math.max(...SLOT_ROWS.map((row) => row.id.length));
+  const rows = SLOT_ROWS.map((row) => {
+    const value = row.kind === "mechanism" ? row.placeholder : models[row.id] ?? row.placeholder;
+    return `  ${row.id.padEnd(width)}  →  ${value}`;
+  });
+
+  const active = readActiveProfile(raw);
+  const header = active ? `nodd · modelos (perfil activo: ${active})` : "nodd · modelos";
+  return [header, ...rows].join("\n");
+}
+
+function renderProfileList(raw: Record<string, unknown>): string {
+  const { profiles, defects } = readProfiles(raw);
+  const names = Object.keys(profiles).sort();
+  if (names.length === 0) {
+    return "nodd · no hay perfiles todavía. Creá el primero con: /nodd-models profile new <nombre>";
+  }
+  const active = readActiveProfile(raw);
+  const rows = names.map((name) => (name === active ? `  * ${name}  (activo)` : `    ${name}`));
+  return ["nodd · perfiles:", ...rows, ...defects.map((d) => `  ! ${d}`)].join("\n");
+}
+
+function runProfile(args: string[], io: ConfigIo): string {
+  const [verb, name, from, fromName] = args;
+
+  if (!verb || verb === "list") return renderProfileList(io.readConfig());
+
+  const command =
+    verb === "new" ? { kind: "new" as const, name: name ?? "", ...(from === "from" && fromName ? { from: fromName } : {}) }
+    : verb === "save" ? { kind: "save" as const, ...(name ? { name } : {}) }
+    : verb === "use" ? { kind: "use" as const, name: name ?? "" }
+    : verb === "delete" || verb === "rm" ? { kind: "delete" as const, name: name ?? "" }
+    : null;
+
+  if (!command) return USAGE;
+  if (command.kind !== "save" && !isValidProfileName(command.name)) {
+    return `nodd · nombre de perfil inválido: ${command.name || "(vacío)"}`;
+  }
+
+  const result = applyProfileCommand(io.readConfig(), command);
+  if (!result.ok) return `nodd · ${result.message}`;
+  io.writeConfig(result.data);
+  return `nodd · ${result.message}`;
+}
+
+/**
+ * The deterministic handler. Display writes nothing; a valid assignment writes
+ * once, through the merge that preserves unrelated keys.
+ */
+export function runModelsCommand(args: string, io: ConfigIo, registry?: ModelRegistry): string {
+  const words = args.trim().split(/\s+/).filter((word) => word !== "");
+
+  if (words.length === 0) return renderTable(io.readConfig());
+  if (words[0] === "profile") return runProfile(words.slice(1), io);
+
+  const assignment = parseAssignment(words[0]);
+  if (!assignment) return USAGE;
+
+  const validation = validateAssignment(assignment, groupsFrom(registry));
+  if (!validation.ok) return `nodd · ${validation.message}`;
+
+  const raw = io.readConfig();
+  const patch = assignmentPatch({ models: currentModels(raw) }, { ...assignment, provider: validation.provider });
+  // Mirror after the write so editing a slot under an active profile edits that
+  // profile too, rather than leaving the two silently divergent.
+  io.writeConfig(mirrorToActiveProfile(mergeConfig(raw, patch)));
+
+  return `nodd · ${assignment.slot} → ${patch.models[assignment.slot]}`;
+}
+
+/** Persist a picker outcome. Quit writes nothing; save writes once. */
+function runPicker(result: EnterResult, io: ConfigIo): void {
+  if (result.type !== "save") return;
+  const raw = io.readConfig();
+  io.writeConfig(mirrorToActiveProfile(mergeConfig(raw, { models: result.models })));
+}
+
+/**
+ * The `ctx.ui.custom` component. It holds one `PickerState` and forwards
+ * keystrokes to the pure state machine; every decision lives there.
+ */
+function createComponent(
+  input: { models: Record<string, string>; groups: Map<string, string[]> },
+  done: (result: EnterResult) => void,
+  requestRender: () => void = () => {},
+): Component {
+  let state: PickerState = createPickerState(input);
+  let choosing: { slot: string; options: string[]; cursor: number } | null = null;
+
+  return {
+    render(width: number): string[] {
+      const inner = Math.max(20, width - 4);
+      const lines = choosing
+        ? [
+            `elegí un modelo para ${choosing.slot}:`,
+            ...choosing.options.map((option, i) => `${i === choosing!.cursor ? "❯" : " "} ${option}`),
+          ]
+        : [
+            "nodd · modelos (↑↓ mover · enter elegir · q salir)",
+            ...renderRows(state).map((row, i) => {
+              const marker = i === state.cursor ? "❯" : " ";
+              return `${marker} ${row.id.padEnd(20)} →  ${row.value}`;
+            }),
+          ];
+      return lines.map((line) => line.slice(0, inner));
+    },
+
+    handleInput(data: string): void {
+      if (choosing) {
+        if (data === "\r" || data === "\n") {
+          state = stage(state, choosing.slot, choosing.options[choosing.cursor]);
+          choosing = null;
+        } else if (data === "\u001b[A") choosing.cursor = Math.max(0, choosing.cursor - 1);
+        else if (data === "\u001b[B") choosing.cursor = Math.min(choosing.options.length - 1, choosing.cursor + 1);
+        else if (data === "q" || data === "\u001b") choosing = null;
+        requestRender();
+        return;
+      }
+
+      if (data === "\u001b[A") state = moveCursor(state, -1);
+      else if (data === "\u001b[B") state = moveCursor(state, 1);
+      else if (data === "q" || data === "\u001b") done({ type: "quit" });
+      else if (data === "\r" || data === "\n") {
+        const result = enter(state);
+        if (result.type === "choose") choosing = { slot: result.slot, options: result.options, cursor: 0 };
+        else done(result);
+      }
+      requestRender();
+    },
+  };
+}
+
+type PiApi = {
+  registerCommand?(name: string, options: { description?: string; handler: (args: string, ctx: unknown) => unknown }): void;
+};
+
+type PiCtx = {
+  ui?: {
+    notify?(message: string, tone?: string): void;
+    custom?<T>(factory: (tui: { requestRender(): void }, theme: unknown, keys: unknown, done: (result: T) => void) => Component): Promise<T>;
+  };
+  modelRegistry?: ModelRegistry;
+};
+
+function register(pi?: PiApi): void {
+  pi?.registerCommand?.("nodd-models", {
+    description: "Configurar los modelos de NODD: /nodd-models [<slot>=<provider>/<modelo>|profile …]",
+    handler: async (args: string, rawCtx: unknown) => {
+      const ctx = rawCtx as PiCtx;
+      const notify = ctx?.ui?.notify;
+      const io = fileConfigIo();
+
+      try {
+        // No arguments plus a custom-UI host: open the picker. Otherwise the
+        // deterministic text path, which is the whole command in a headless run.
+        if (args.trim() === "" && typeof ctx?.ui?.custom === "function") {
+          const groups = groupsFrom(ctx.modelRegistry);
+          const result = await ctx.ui.custom<EnterResult>((tui, _theme, _keys, done) =>
+            createComponent({ models: currentModels(io.readConfig()), groups }, done, () => tui.requestRender()),
+          );
+          runPicker(result, io);
+          notify?.(result.type === "save" ? "nodd · modelos guardados" : "nodd · sin cambios", "info");
+          return;
+        }
+
+        notify?.(runModelsCommand(args ?? "", io, ctx?.modelRegistry), "info");
+      } catch (err) {
+        notify?.(`nodd-models: ${err instanceof Error ? err.message : String(err)}`, "error");
+      }
+    },
+  });
+}
+
+register.runPicker = runPicker;
+register.createComponent = createComponent;
+
+export default register;

package/extensions/nodd-promote.test.ts

@@ -0,0 +1,150 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { emptyDoc, renderFeatureDoc, type FeatureDoc } from "../src/feature-doc.ts";
+import register, { runPromote } from "./nodd-promote.ts";
+
+function workspace(): string {
+  return mkdtempSync(join(tmpdir(), "nodd-promote-"));
+}
+
+function sampleDoc(): FeatureDoc {
+  return {
+    ...emptyDoc({ slug: "cache-warmup", title: "Warm the cache on boot" }),
+    objective: "Serve the first request from a warm cache.",
+    constraints: "No new dependencies.",
+    tasks: [
+      {
+        id: "T001",
+        title: "Read the boot sequence",
+        checked: true,
+        evidence: { command: "node --test src/boot.test.ts", outcome: "success" },
+        candidate: "a1b2c3d",
+      },
+      { id: "T002", title: "Preload the hot keys", checked: false },
+    ],
+  };
+}
+
+function seedRun(root: string, doc: FeatureDoc = sampleDoc()): string {
+  const dir = join(root, ".nodd", doc.slug);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "feature.md"), renderFeatureDoc(doc), "utf8");
+  return root;
+}
+
+// ---------------------------------------------------------------------------
+// Exactly one file
+// ---------------------------------------------------------------------------
+test("promotion writes requirements.md and nothing else under .sdd/", () => {
+  const root = seedRun(workspace());
+  const result = runPromote("cache-warmup", root);
+
+  assert.equal(result.ok, true, result.message);
+  const sddDir = join(root, ".sdd", "cache-warmup");
+  assert.deepEqual(readdirSync(sddDir), ["requirements.md"], "exactly one file");
+  assert.ok(!existsSync(join(sddDir, "design.md")), "design.md must be absent so forge resumes at plan");
+  assert.ok(!existsSync(join(sddDir, "tasks.md")), "tasks.md must be absent so forge resumes at plan");
+});
+
+test("the written requirements carry the objective and the resolved task's evidence", () => {
+  const root = seedRun(workspace());
+  runPromote("cache-warmup", root);
+
+  const written = readFileSync(join(root, ".sdd", "cache-warmup", "requirements.md"), "utf8");
+  assert.ok(written.includes("Serve the first request from a warm cache."));
+  assert.ok(written.includes("node --test src/boot.test.ts"));
+  assert.match(written, /not be redone/i);
+});
+
+// ---------------------------------------------------------------------------
+// Never an overwrite
+// ---------------------------------------------------------------------------
+test("an existing requirements.md is refused, not overwritten", () => {
+  const root = seedRun(workspace());
+  const target = join(root, ".sdd", "cache-warmup", "requirements.md");
+  mkdirSync(join(root, ".sdd", "cache-warmup"), { recursive: true });
+  writeFileSync(target, "HAND WRITTEN, DO NOT CLOBBER\n", "utf8");
+
+  const result = runPromote("cache-warmup", root);
+  assert.equal(result.ok, false);
+  assert.match(result.message, /ya existe|already exists/i);
+  assert.equal(readFileSync(target, "utf8"), "HAND WRITTEN, DO NOT CLOBBER\n", "byte-identical after the refusal");
+});
+
+test("a missing run is reported, not thrown", () => {
+  const root = workspace();
+  const result = runPromote("no-such-run", root);
+  assert.equal(result.ok, false);
+  assert.ok(result.message.includes("no-such-run"));
+});
+
+test("an empty slug is refused with usage", () => {
+  assert.equal(runPromote("", workspace()).ok, false);
+});
+
+// ---------------------------------------------------------------------------
+// Forge is optional
+// ---------------------------------------------------------------------------
+test("with forge absent the artifact is still written and the manual step reported", () => {
+  const root = seedRun(workspace());
+  const result = runPromote("cache-warmup", root, { forgeAvailable: false });
+
+  assert.equal(result.ok, true);
+  assert.ok(existsSync(join(root, ".sdd", "cache-warmup", "requirements.md")), "the artifact is written regardless");
+  assert.match(result.message, /forge --continue cache-warmup/, "it names the exact command to run by hand");
+});
+
+test("with forge present the message still names the continue command and never runs it", () => {
+  const root = seedRun(workspace());
+  const result = runPromote("cache-warmup", root, { forgeAvailable: true });
+  assert.equal(result.ok, true);
+  assert.match(result.message, /forge --continue cache-warmup/);
+});
+
+// ---------------------------------------------------------------------------
+// REQ: no-sdd-artifacts-off-route
+// ---------------------------------------------------------------------------
+test("this is the only module in the package that writes under .sdd/", () => {
+  const roots = ["../src", "../src/gates", "../src/models", "."];
+  const offenders: string[] = [];
+
+  for (const root of roots) {
+    const dir = new URL(`${root}/`, import.meta.url);
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith(".ts") || name.endsWith(".test.ts")) continue;
+      if (name === "nodd-promote.ts") continue;
+      const source = readFileSync(new URL(name, dir), "utf8")
+        .split("\n")
+        .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+        .join("\n");
+      if (source.includes(".sdd")) offenders.push(`${root}/${name}`);
+    }
+  }
+
+  assert.deepEqual(offenders, [], "only /nodd-promote may write under .sdd/");
+});
+
+test("the tracked route leaves .sdd/ untouched across many file writes", () => {
+  const root = seedRun(workspace());
+  mkdirSync(join(root, ".sdd"), { recursive: true });
+  writeFileSync(join(root, ".sdd", "sentinel.md"), "untouched\n", "utf8");
+
+  // A `tracked` run touching ten files: the feature doc is rewritten each time
+  // and nothing reaches .sdd/.
+  const { writeFeatureDoc } = register;
+  for (let i = 0; i < 10; i++) {
+    writeFeatureDoc(root, { ...sampleDoc(), objective: `revision ${i}` });
+  }
+
+  assert.deepEqual(readdirSync(join(root, ".sdd")), ["sentinel.md"], ".sdd/ gained nothing");
+  assert.equal(readFileSync(join(root, ".sdd", "sentinel.md"), "utf8"), "untouched\n");
+});
+
+test("the command registers as /nodd-promote", () => {
+  const commands = new Map<string, unknown>();
+  register({ registerCommand: (name: string, options: unknown) => commands.set(name, options) } as never);
+  assert.ok(commands.has("nodd-promote"));
+});

package/extensions/nodd-promote.ts

@@ -0,0 +1,96 @@
+// `/nodd-promote <slug>` — the single door from NODD into forge.
+//
+// It writes **exactly one file**: `.sdd/<slug>/requirements.md`. No `design.md`,
+// no `tasks.md`, no checklist, so forge's resume algorithm lands on `no-plan`
+// and restarts at `plan` (`orchestrator.md:102-105`).
+//
+// This is also the enforcement point for `REQ: no-sdd-artifacts-off-route`: it is
+// the only module in the package that names `.sdd` in executable code, and a
+// test in `nodd-promote.test.ts` scans every other source file to keep it that
+// way. A tracked run can rewrite the feature doc ten times and leave `.sdd/`
+// byte-identical.
+//
+// Forge is an **optional** dependency (`clarifications.md`). When it is absent
+// the artifact is still written and the message names the exact command to run
+// by hand — promotion must never fail because the consumer is not installed. The
+// command never launches forge itself; handing control to another orchestrator
+// is the user's decision.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseFeatureDoc, renderFeatureDoc, type FeatureDoc } from "../src/feature-doc.ts";
+import { writeVerified } from "../src/io.ts";
+import { promotedRequirements } from "../src/promote.ts";
+
+export type PromoteResult = { ok: boolean; message: string };
+
+function featurePath(root: string, slug: string): string {
+  return join(root, ".nodd", slug, "feature.md");
+}
+
+function requirementsPath(root: string, slug: string): string {
+  return join(root, ".sdd", slug, "requirements.md");
+}
+
+/** Writes the feature doc under `.nodd/`, which is the only place NODD's own
+ *  route writes. Exposed so the `.sdd/`-untouched test can drive a real
+ *  multi-write run rather than assert against a mock. */
+function writeFeatureDoc(root: string, doc: FeatureDoc): void {
+  writeVerified(featurePath(root, doc.slug), renderFeatureDoc(doc));
+}
+
+export function runPromote(
+  slug: string,
+  root: string,
+  options: { forgeAvailable?: boolean } = {},
+): PromoteResult {
+  const trimmed = slug.trim();
+  if (trimmed === "") return { ok: false, message: "uso: /nodd-promote <slug>" };
+
+  const source = featurePath(root, trimmed);
+  if (!existsSync(source)) {
+    return { ok: false, message: `nodd · no existe la feature ${trimmed} (${source})` };
+  }
+
+  const target = requirementsPath(root, trimmed);
+  // Refusing beats merging: an existing requirements.md was written by forge or
+  // by hand, and either way NODD is not the author who gets to replace it.
+  if (existsSync(target)) {
+    return { ok: false, message: `nodd · ${target} ya existe; no se sobrescribe. Movelo o borralo y repetí.` };
+  }
+
+  const { doc, defects } = parseFeatureDoc(readFileSync(source, "utf8"));
+  const written = writeVerified(target, promotedRequirements(doc));
+  if (!written.ok) return { ok: false, message: `nodd · no se pudo escribir ${target}: ${written.limitation}` };
+
+  const next =
+    options.forgeAvailable === false
+      ? `forge no está instalado: corré \`/forge --continue ${trimmed}\` donde sí lo esté`
+      : `seguí con \`/forge --continue ${trimmed}\``;
+
+  const note = defects.length > 0 ? ` (la feature tenía ${defects.length} defecto(s): ${defects.join("; ")})` : "";
+  return { ok: true, message: `nodd · ${target} escrito. ${next}.${note}` };
+}
+
+type PiApi = {
+  registerCommand?(name: string, options: { description?: string; handler: (args: string, ctx: unknown) => unknown }): void;
+};
+
+function register(pi?: PiApi): void {
+  pi?.registerCommand?.("nodd-promote", {
+    description: "Promover una feature de NODD a forge: /nodd-promote <slug>",
+    handler: (args: string, rawCtx: unknown) => {
+      const ctx = rawCtx as { ui?: { notify?(message: string, tone?: string): void } };
+      try {
+        const result = runPromote(args ?? "", process.cwd());
+        ctx?.ui?.notify?.(result.message, result.ok ? "info" : "error");
+      } catch (err) {
+        ctx?.ui?.notify?.(`nodd-promote: ${err instanceof Error ? err.message : String(err)}`, "error");
+      }
+    },
+  });
+}
+
+register.writeFeatureDoc = writeFeatureDoc;
+
+export default register;