@pknx/waterfall-cli 0.1.0

package/lib/cli/commands/horizontal/horizontal.ts

@@ -0,0 +1,232 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertBranchForCrScopedCommand } from "../../git/git-branch-guards";
+import { gitExecSync } from "../../git/git-cli";
+import { assertSpecRoot } from "../../spec/spec-root";
+import { slugifyDescription } from "../../core/slug";
+
+export const HORIZONTAL_ANCHORS = ["story"] as const;
+export type HorizontalAnchor = (typeof HORIZONTAL_ANCHORS)[number];
+
+type NumberJson = { next: { HOR: number } & Record<string, number> };
+
+function git(specRoot: string, args: string[]): void {
+  gitExecSync(specRoot, args, { stdio: "inherit" });
+}
+
+function gitCapture(specRoot: string, args: string[]): string {
+  return gitExecSync(specRoot, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).toString();
+}
+
+export function formatHorId(n: number): string {
+  return String(n).padStart(3, "0");
+}
+
+/** Accept `HOR-001`, `hor-001`, or `001`. */
+export function parseHorToken(tok: string): string | undefined {
+  const t = tok.trim();
+  const m = t.match(/^HOR-(\d{3})$/i) ?? t.match(/^(\d{3})$/);
+  return m?.[1];
+}
+
+export function assertHorizontalAnchor(raw: string): HorizontalAnchor {
+  const a = raw.trim().toLowerCase() as HorizontalAnchor;
+  if (!HORIZONTAL_ANCHORS.includes(a as HorizontalAnchor)) {
+    throw new Error(
+      `horizontal create: unknown anchor "${raw}" (use: ${HORIZONTAL_ANCHORS.join(", ")})`,
+    );
+  }
+  return a as HorizontalAnchor;
+}
+
+export function matchesHorizontalAnchor(anchor: HorizontalAnchor, relPath: string): boolean {
+  const n = relPath.replace(/\\/g, "/");
+  switch (anchor) {
+    case "story":
+      return /(^|\/)STORY-\d+/i.test(n) || /\/_STORY-\d+/i.test(n);
+    default:
+      return false;
+  }
+}
+
+function parseAnchorFromDoc(body: string): HorizontalAnchor {
+  const m = body.match(/\*\*Anchor item type:\*\*\s*(\S+)/i);
+  if (m?.[1]) {
+    const low = m[1].toLowerCase();
+    if (HORIZONTAL_ANCHORS.includes(low as HorizontalAnchor)) {
+      return low as HorizontalAnchor;
+    }
+  }
+  return "story";
+}
+
+function horizontalsDir(specRoot: string): string {
+  return path.join(specRoot, "technical", "horizontals");
+}
+
+/** Resolve the one `technical/horizontals` folder whose name starts with `HOR-{digits}-`. */
+export function findHorizontalDir(specRoot: string, digits: string): string {
+  const base = horizontalsDir(specRoot);
+  if (!fs.existsSync(base)) {
+    throw new Error(
+      `horizontal: missing ${path.relative(specRoot, base) + "/"}`,
+    );
+  }
+  const prefix = `HOR-${digits}-`;
+  const names = fs.readdirSync(base).filter((n) => n.startsWith(prefix));
+  if (names.length === 0) {
+    throw new Error(`horizontal: no folder matching ${prefix}* under technical/horizontals/`);
+  }
+  if (names.length > 1) {
+    throw new Error(
+      `horizontal: ambiguous HOR-${digits}: multiple folders (${names.join(", ")})`,
+    );
+  }
+  return path.join(base, names[0]!);
+}
+
+/** Path to `HOR-<digits>.md` inside the horizontal folder `dir`. */
+export function horizontalMarkdownPath(dir: string, digits: string): string {
+  return path.join(dir, `HOR-${digits}.md`);
+}
+
+/**
+ * Create `technical/horizontals/HOR-NNN-<slug>/HOR-NNN.md`, bump `next.HOR`, commit.
+ */
+export function runHorizontalCreate(
+  specRoot: string,
+  anchor: HorizontalAnchor,
+  horizontalNameRaw: string,
+  purpose: string,
+): void {
+  assertSpecRoot(specRoot);
+  assertBranchForCrScopedCommand(specRoot, "waterfall horizontal create");
+  const nameSlug = slugifyDescription(horizontalNameRaw.replace(/\//g, "-"));
+  if (!nameSlug || nameSlug === "change") {
+    throw new Error(
+      'horizontal create: give a concrete horizontal name (e.g. database-model, api-model, technical-stack)',
+    );
+  }
+
+  const numPath = path.join(specRoot, "number.json");
+  const raw = JSON.parse(fs.readFileSync(numPath, "utf8")) as NumberJson;
+  if (typeof raw.next?.HOR !== "number") {
+    throw new Error("horizontal create: number.json missing next.HOR (re-run spec init or add HOR: 1)");
+  }
+  const n = raw.next.HOR;
+  const id = formatHorId(n);
+  const base = `HOR-${id}-${nameSlug}`;
+  const horDir = path.join(horizontalsDir(specRoot), base);
+
+  if (fs.existsSync(horDir)) {
+    throw new Error(`horizontal folder already exists: technical/horizontals/${base}`);
+  }
+  fs.mkdirSync(horDir, { recursive: true });
+
+  const mdPath = path.join(horDir, `HOR-${id}.md`);
+  const purposeTrim = purpose.trim();
+  const steeringLines = purposeTrim
+    .split(/\r?\n/)
+    .map((line) => (line.length > 0 ? `> ${line}` : ">"));
+  const steeringBlock =
+    steeringLines.length > 0 ? steeringLines.join("\n") : "> _(empty)_";
+
+  const md = `# HOR-${id} — ${horizontalNameRaw.trim()} (horizontal on **${anchor}**)
+
+**Id:** HOR-${id}  
+**Anchor item type:** ${anchor}  
+**Horizontal name:** ${nameSlug}  
+**Status:** draft
+
+## Purpose
+
+*(One short paragraph on what this horizontal reconciles — per \`prompts/global/horizontal-structure.md\`. **Synthesize** from **Draft steering (CLI)**; do not paste it verbatim. Remove **Draft steering** when **Purpose** and **Aggregated definitions** are filled.)*
+
+## Draft steering (CLI)
+
+The operator supplied this when running \`waterfall horizontal create …\`. **Scratch input only**:
+
+${steeringBlock}
+
+## Aggregated definitions
+
+
+## Maintenance notes
+
+(Optional) Human revision notes for major model changes.
+`;
+
+  fs.writeFileSync(mdPath, md, "utf8");
+
+  raw.next.HOR = n + 1;
+  fs.writeFileSync(numPath, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
+
+  const relDir = path.relative(specRoot, horDir).replace(/\\/g, "/");
+  git(specRoot, ["add", `${relDir}/HOR-${id}.md`, "number.json"]);
+  git(specRoot, ["commit", "-m", `feat(HOR-${id}): scaffold horizontal (${anchor} / ${nameSlug})`]);
+}
+
+/**
+ * Resolves `develop...HEAD` name-only paths vs develop, filters by this horizontal’s anchor.
+ * Does **not** modify `HOR-<NNN>.md` — returns markdown for the operator / agent hint only.
+ */
+export function runHorizontalUpdate(specRoot: string, horToken: string): string {
+  assertSpecRoot(specRoot);
+  assertBranchForCrScopedCommand(specRoot, "waterfall horizontal update");
+  const digits = parseHorToken(horToken);
+  if (!digits) {
+    throw new Error(
+      `horizontal update: invalid id "${horToken}" (use HOR-NNN or NNN)`,
+    );
+  }
+
+  const dir = findHorizontalDir(specRoot, digits);
+  const mdPath = horizontalMarkdownPath(dir, digits);
+  if (!fs.existsSync(mdPath)) {
+    const rel = path.relative(specRoot, mdPath).replace(/\\/g, "/");
+    throw new Error(
+      `horizontal update: missing ${rel} — run horizontal create or add HOR-${digits}.md in the horizontal folder`,
+    );
+  }
+  const body = fs.readFileSync(mdPath, "utf8");
+  const anchor = parseAnchorFromDoc(body);
+
+  let names: string;
+  try {
+    names = gitCapture(specRoot, ["diff", "develop...HEAD", "--name-only"]);
+  } catch (e) {
+    throw new Error(
+      `horizontal update: git diff develop...HEAD failed (${(e as Error).message}). Is branch develop present?`,
+    );
+  }
+
+  const allPaths = names
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const matched = allPaths.filter((p) => matchesHorizontalAnchor(anchor, p));
+
+  const matchingBlock = matched.length
+    ? matched.map((p) => `- ${p}`).join("\n")
+    : `(No paths in this diff match anchor ${anchor}.)`;
+  const allBlock = allPaths.length
+    ? allPaths.map((p) => `- ${p}`).join("\n")
+    : "(None.)";
+
+  return [
+    `Horizontal update HOR-${digits} (anchor ${anchor})`,
+    "",
+    `Range develop...HEAD. ${matched.length} path(s) match this anchor; ${allPaths.length} path(s) changed in total. Do not paste these lists into HOR-${digits}.md — merge substance into the Aggregated definitions section only (typed ids in prose; see before-changing-spec.md).`,
+    "",
+    `Paths matching anchor ${anchor}`,
+    "",
+    matchingBlock,
+    "",
+    "All changed paths vs develop",
+    "",
+    allBlock,
+  ].join("\n");
+}

package/lib/cli/commands/horizontal-create.ts

@@ -0,0 +1,34 @@
+import { AGENT_GLOBAL_PROMPTS_HORIZONTAL_CREATE } from "../agent/global-prompts";
+import {
+  assertHorizontalAnchor,
+  runHorizontalCreate,
+} from "./horizontal/horizontal";
+import { assertBranchForCrScopedCommand } from "../git/git-branch-guards";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const horizontalCreateCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "horizontal" && r[1] === "create",
+  run(ctx, rest) {
+    const [, , anchorRaw, nameSlug, ...more] = rest;
+    const purpose = resolveOperatorHint(more.filter(Boolean), {
+      required: true,
+    }).text;
+    if (!anchorRaw || !nameSlug || !purpose) {
+      throw new Error(
+        'horizontal create requires anchor, name, and purpose: waterfall horizontal create story database-model "…"',
+      );
+    }
+    assertBranchForCrScopedCommand(ctx.specRoot, "waterfall horizontal create");
+    const anchor = assertHorizontalAnchor(anchorRaw);
+    runHorizontalCreate(ctx.specRoot, anchor, nameSlug, purpose);
+    const hint = `[horizontal create · anchor=${anchor} · name=${nameSlug}] ${purpose}`;
+    ctx.runAgentPrompt(
+      "prompts/commands/horizontal-create.md",
+      hint,
+      AGENT_GLOBAL_PROMPTS_HORIZONTAL_CREATE,
+      "waterfall horizontal create — refine HOR prose",
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/horizontal-update.ts

@@ -0,0 +1,32 @@
+import { runHorizontalUpdate } from "./horizontal/horizontal";
+import { assertBranchForCrScopedCommand } from "../git/git-branch-guards";
+import { AGENT_GLOBAL_PROMPTS_HORIZONTAL_UPDATE } from "../agent/global-prompts";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const horizontalUpdateCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "horizontal" && r[1] === "update",
+  run(ctx, rest) {
+    const horTok = rest[2];
+    if (!horTok) {
+      throw new Error(
+        "horizontal update requires HOR id: waterfall horizontal update HOR-001 [hint]",
+      );
+    }
+    assertBranchForCrScopedCommand(ctx.specRoot, "waterfall horizontal update");
+    const summary = runHorizontalUpdate(ctx.specRoot, horTok);
+    const tail = rest.slice(3);
+    const operator = resolveOperatorHint(tail.filter(Boolean), {
+      required: false,
+    }).text;
+    const hint = [operator, summary].filter(Boolean).join("\n\n");
+    ctx.runAgentPrompt(
+      "prompts/commands/horizontal-update.md",
+      hint,
+      AGENT_GLOBAL_PROMPTS_HORIZONTAL_UPDATE,
+      undefined,
+      { attachCrBranchPaths: false },
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/join-hint.ts

@@ -0,0 +1,4 @@
+/** Join argv fragments into one operator-hint string. */
+export function joinHint(parts: string[]): string {
+  return parts.join(" ").trim();
+}

package/lib/cli/commands/registry.ts

@@ -0,0 +1,59 @@
+import { exportPdfCommand } from "./export-pdf";
+import { syncBugsCommand, syncStoriesCommand } from "./sync-work-items";
+import { crAllCommand } from "./cr-all";
+import { crFinishCommand } from "./cr-finish";
+import { crStartCommand } from "./cr-start";
+import { crToRqCommand } from "./cr-to-rq";
+import { horizontalCreateCommand } from "./horizontal-create";
+import { horizontalUpdateCommand } from "./horizontal-update";
+import { rqAllCommand } from "./rq-all";
+import { rqToUcCommand } from "./rq-to-uc";
+import { commentAddCommand } from "./comment-add";
+import { storyCloseCommand } from "./story-close";
+import { sysStartCommand } from "./sys-start";
+import { bugStartCommand } from "./bug-start";
+import { testAllCommand } from "./test-all";
+import { testToStoryCommand } from "./test-to-story";
+import { ucAllCommand } from "./uc-all";
+import { ucToStoryCommand } from "./uc-to-story";
+import { ucToTestCommand } from "./uc-to-test";
+import type { CommandRunContext, WaterfallCommand } from "./types";
+
+/**
+ * Order is only relevant if two matchers could both match; keep specific
+ * multi-token commands before looser ones (e.g. `test to story` before `test all`).
+ */
+export const SPEC_COMMANDS: WaterfallCommand[] = [
+  syncStoriesCommand,
+  syncBugsCommand,
+  commentAddCommand,
+  exportPdfCommand,
+  crStartCommand,
+  sysStartCommand,
+  bugStartCommand,
+  horizontalCreateCommand,
+  horizontalUpdateCommand,
+  crFinishCommand,
+  crToRqCommand,
+  rqToUcCommand,
+  ucToStoryCommand,
+  ucToTestCommand,
+  testToStoryCommand,
+  crAllCommand,
+  rqAllCommand,
+  ucAllCommand,
+  testAllCommand,
+  storyCloseCommand,
+];
+
+export function dispatchSpecCommand(
+  ctx: CommandRunContext,
+  rest: string[],
+): number | null {
+  for (const cmd of SPEC_COMMANDS) {
+    if (cmd.matches(rest)) {
+      return cmd.run(ctx, rest);
+    }
+  }
+  return null;
+}

package/lib/cli/commands/resolve-operator-hint.ts

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import path from "node:path";
+import { joinHint } from "./join-hint";
+
+/** How the operator hint text was obtained. */
+export type OperatorHintSource = "inline" | "stdin" | "file";
+
+/** Resolved hint: use `text` for agents and git scaffolds. */
+export type ResolvedOperatorHint = {
+  source: OperatorHintSource;
+  /** UTF-8 content; newlines normalized; leading/trailing whitespace trimmed. */
+  text: string;
+  /** Absolute path when source is `file`. */
+  resolvedPath?: string;
+};
+
+export type ResolveOperatorHintOptions = {
+  /** When true, missing or blank hint throws. @default false */
+  required?: boolean;
+  /** Base directory for relative <code>@PATH</code> hints. @default process.cwd() */
+  cwd?: string;
+};
+
+/** Shorter text for <code>help -o json</code> positional rows. */
+export const OPERATOR_HINT_POSITIONAL_DESCRIPTION =
+  "Inline argv tokens (joined with spaces), a single - (read stdin UTF-8), or a single @PATH (read file UTF-8; PATH relative to cwd unless absolute).";
+
+/** Machine-readable documentation for <code>help -o json</code>. */
+export const OPERATOR_HINT_JSON = {
+  summary:
+    "Operator hints (steering text for agents, or descriptions for scaffolds) are resolved from argv after fixed command arguments.",
+  modes: [
+    {
+      id: "inline",
+      description:
+        "Default: all remaining argv tokens are joined with single spaces (shell quoting controls word boundaries).",
+    },
+    {
+      id: "stdin",
+      description:
+        'Exactly one token "-" reads the entire hint from standard input as UTF-8.',
+    },
+    {
+      id: "file",
+      description:
+        "Exactly one token whose value starts with @ reads the file path after @ (relative paths resolve against cwd).",
+    },
+  ],
+} as const;
+
+function normalizeHintBody(raw: string): string {
+  return raw.replace(/\r\n/g, "\n").trim();
+}
+
+function readStdinUtf8(): string {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    throw new Error(
+      `Cannot read operator hint from stdin: ${(e as Error).message}`,
+    );
+  }
+}
+
+/**
+ * Resolve operator-hint argv fragments to a single string and record the source.
+ * - Single <code>-</code> → stdin
+ * - Single <code>@path</code> → file (path may not be empty)
+ * - Otherwise → inline via {@link joinHint}
+ */
+export function resolveOperatorHint(
+  parts: string[],
+  options?: ResolveOperatorHintOptions,
+): ResolvedOperatorHint {
+  const required = options?.required ?? false;
+  const cwd = options?.cwd ?? process.cwd();
+  const filtered = parts.filter((p) => p.length > 0);
+
+  if (filtered.length === 0) {
+    if (required) {
+      throw new Error(
+        "Operator hint is required: pass inline text, - for stdin, or @PATH for a file (see waterfall help).",
+      );
+    }
+    return { source: "inline", text: "" };
+  }
+
+  if (filtered.length === 1 && filtered[0] === "-") {
+    const text = normalizeHintBody(readStdinUtf8());
+    if (required && !text) {
+      throw new Error("Operator hint from stdin is empty.");
+    }
+    return { source: "stdin", text };
+  }
+
+  if (filtered.length === 1 && filtered[0]!.startsWith("@")) {
+    const rel = filtered[0]!.slice(1);
+    if (!rel) {
+      throw new Error(
+        'File hint requires a path after "@", e.g. @./notes/hint.md',
+      );
+    }
+    const abs = path.isAbsolute(rel) ? rel : path.resolve(cwd, rel);
+    let raw: string;
+    try {
+      raw = fs.readFileSync(abs, "utf8");
+    } catch (e) {
+      throw new Error(
+        `Cannot read hint file ${abs}: ${(e as Error).message}`,
+      );
+    }
+    const text = normalizeHintBody(raw);
+    if (required && !text) {
+      throw new Error(`Hint file is empty: ${abs}`);
+    }
+    return { source: "file", text, resolvedPath: abs };
+  }
+
+  return { source: "inline", text: joinHint(filtered) };
+}

package/lib/cli/commands/rq-all.ts

@@ -0,0 +1,18 @@
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { ORCHESTRATE_RQ_ALL_ORDER } from "../core/prompt-map";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const rqAllCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "rq" && r[1] === "all",
+  run(ctx, rest) {
+    const tail = rest.slice(2);
+    ctx.runOrchestrate(
+      ORCHESTRATE_RQ_ALL_ORDER,
+      "waterfall rq all",
+      resolveOperatorHint(tail, { required: false }).text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/rq-to-uc.ts

@@ -0,0 +1,18 @@
+import { assertBranchForCrScopedCommand } from "../git/git-branch-guards";
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const rqToUcCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "rq" && r[1] === "to" && r[2] === "uc",
+  run(ctx, rest) {
+    assertBranchForCrScopedCommand(ctx.specRoot, "waterfall rq to uc");
+    const tail = rest.slice(3);
+    ctx.runAgentPrompt(
+      "prompts/commands/rq-to-uc.md",
+      resolveOperatorHint(tail, { required: true }).text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/story-close.ts

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertBranchDevelop } from "../git/git-branch-guards";
+import { gitExecSync } from "../git/git-cli";
+import { assertSpecRoot } from "../spec/spec-root";
+import type { WaterfallCommand } from "./types";
+
+function git(specRoot: string, args: string[]): void {
+  gitExecSync(specRoot, args, { stdio: "inherit" });
+}
+
+/** Parse STORY-018 or 018 -> padded "018" */
+export function parseStoryIdToken(arg: string): string {
+  const m = arg.match(/^STORY-(\d+)$/i) ?? arg.match(/^(\d+)$/);
+  if (!m) throw new Error(`Invalid story id "${arg}". Use STORY-NNN or NNN.`);
+  return String(parseInt(m[1]!, 10)).padStart(3, "0");
+}
+
+function walkStoryDirs(root: string): string[] {
+  const out: string[] = [];
+  const stack = [root];
+  while (stack.length) {
+    const d = stack.pop()!;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) {
+        if (/^STORY-\d{3}-/.test(e.name) && !e.name.startsWith("_")) {
+          out.push(p);
+        }
+        if (!e.name.startsWith(".") && e.name !== "node_modules") {
+          stack.push(p);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Find .../STORY-NNN-slug/ under technical/ */
+export function findOpenStoryFolder(
+  specRoot: string,
+  paddedId: string,
+): string {
+  const technical = path.join(specRoot, "technical");
+  if (!fs.existsSync(technical)) {
+    throw new Error(`No technical/ under ${specRoot}`);
+  }
+  const dirs = walkStoryDirs(technical);
+  const needle = `STORY-${paddedId}-`;
+  const hit = dirs.find((p) => path.basename(p).startsWith(needle));
+  if (!hit) {
+    throw new Error(
+      `No open STORY-${paddedId}-* folder found under technical/ (already closed or missing).`,
+    );
+  }
+  return hit;
+}
+
+/** Git mv folder to _STORY-...; update STORY-NNN.md status (minimal). */
+export function runStoryClose(specRoot: string, storyToken: string): void {
+  assertSpecRoot(specRoot);
+  const padded = parseStoryIdToken(storyToken);
+  const oldDir = findOpenStoryFolder(specRoot, padded);
+  const base = path.basename(oldDir);
+  const newBase = `_${base}`;
+  const parent = path.dirname(oldDir);
+  const newDir = path.join(parent, newBase);
+
+  const storyFile = fs
+    .readdirSync(oldDir)
+    .find((f) => /^STORY-\d{3}\.md$/i.test(f));
+  if (!storyFile) {
+    throw new Error(`No STORY-NNN.md in ${oldDir}`);
+  }
+  const storyPath = path.join(oldDir, storyFile);
+  let body = fs.readFileSync(storyPath, "utf8");
+  body = body.replace(/\*\*Status:\*\*\s*\w+/i, "**Status:** closed");
+  if (!/\*\*Closed:\*\*/i.test(body)) {
+    body = body.replace(
+      /(\*\*Status:\*\*[^\n]*\n)/i,
+      `$1**Closed:** ${new Date().toISOString().slice(0, 10)} — closed via waterfall CLI.\n`,
+    );
+  }
+  fs.writeFileSync(storyPath, body, "utf8");
+
+  git(specRoot, [
+    "mv",
+    path.relative(specRoot, oldDir),
+    path.relative(specRoot, newDir),
+  ]);
+
+  git(specRoot, ["add", "-A"]);
+  git(specRoot, [
+    "commit",
+    "-m",
+    `chore: close ${base} -> ${newBase}`,
+  ]);
+}
+
+export const storyCloseCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "story" && r[1] === "close",
+  run(ctx, rest) {
+    const tok = rest[2];
+    if (!tok) throw new Error("story close requires STORY-NNN or all");
+    const storyCloseLabel =
+      tok.toLowerCase() === "all"
+        ? "waterfall story close all"
+        : "waterfall story close";
+    assertBranchDevelop(ctx.specRoot, storyCloseLabel);
+    if (tok.toLowerCase() === "all") {
+      throw new Error(
+        "story close all: use explicit ids per story-close-all.md (not automated here).",
+      );
+    }
+    runStoryClose(ctx.specRoot, tok);
+    return 0;
+  },
+};