@pknx/waterfall-cli 0.1.0

package/lib/cli/sync/work-item-meta.ts

@@ -0,0 +1,117 @@
+/**
+ * Canonical JSON shape for STORY/BUG sync: comparable snapshots from spec or remote trackers.
+ * Comments: `user` + `email` + body; spec `{STORY|BUG}-NNN.comments.json`; remote tracker. Compared on sync by `email` + `createdAt` + `user` + body.
+ */
+
+/** Reference to an external system (Jira issue, Linear, etc.). */
+export type WorkItemExternalRef = {
+  system: string;
+  id: string;
+  url?: string;
+};
+
+/** Comment thread entry — tracker and/or waterfall `{id}.comments.json`. Author identity is `email`; `user` is display name. */
+export type WorkItemComment = {
+  /** Display name (waterfall `from`). */
+  user: string;
+  /** Stable author id (required for sync identity; same person as `user`). */
+  email: string;
+  /** ISO 8601 date-time */
+  createdAt: string;
+  body: string;
+  /** Remote comment id when syncing from a tracker */
+  externalId?: string;
+};
+
+/**
+ * Attachment bucket for sync (maps to PDF, images, video, Excel/Sheets, Word, …).
+ * Use {@link attachmentCategoryFromMimeOrName} when inferring from MIME or filename.
+ */
+export type WorkItemAttachmentCategory =
+  | "pdf"
+  | "image"
+  | "video"
+  | "spreadsheet"
+  | "document"
+  | "other";
+
+export type WorkItemAttachment = {
+  /** Stable id (spec filename, Jira attachment id, UUID, …) */
+  id: string;
+  name: string;
+  category: WorkItemAttachmentCategory;
+  mimeType?: string;
+  sizeBytes?: number;
+  /** Spec-relative path, https URL, or opaque provider locator */
+  href?: string;
+};
+
+/** One work item in a provider-agnostic form suitable for diffing. */
+export type WorkItemRecord = {
+  /** Stable id in waterfall-spec space, e.g. STORY-001, BUG-002 */
+  canonicalId: string;
+  kind: "story" | "bug";
+  /** Normalized lifecycle: open | closed | draft (extend as needed). */
+  state: string;
+  title: string;
+  /** SYS-NNN when inferable from path */
+  sysId?: string;
+  /** Path under spec root using / */
+  relPath?: string;
+  externalRefs?: WorkItemExternalRef[];
+  comments?: WorkItemComment[];
+  attachments?: WorkItemAttachment[];
+  /** Optional provider echo for debugging (not used in equality by default). */
+  providerPayload?: Record<string, unknown>;
+};
+
+/** Sort nested arrays for deterministic JSON and diff. */
+export function normalizeWorkItemRecord(r: WorkItemRecord): WorkItemRecord {
+  const { comments: c0, attachments: a0, ...rest } = r;
+  const comments = c0?.length
+    ? [...c0].sort((a, b) =>
+        `${a.email}\t${a.createdAt}\t${a.user}`.localeCompare(
+          `${b.email}\t${b.createdAt}\t${b.user}`,
+          "en",
+        ),
+      )
+    : undefined;
+  const attachments = a0?.length
+    ? [...a0].sort((a, b) => a.id.localeCompare(b.id, "en"))
+    : undefined;
+  return {
+    ...rest,
+    ...(comments ? { comments } : {}),
+    ...(attachments ? { attachments } : {}),
+  };
+}
+
+export type WorkItemMetaDocument = {
+  source: string;
+  kind: "story" | "bug";
+  generatedAt: string;
+  specRoot?: string;
+  items: WorkItemRecord[];
+};
+
+export function createMetaDocument(
+  source: string,
+  kind: "story" | "bug",
+  items: WorkItemRecord[],
+  specRoot?: string,
+): WorkItemMetaDocument {
+  return {
+    source,
+    kind,
+    generatedAt: new Date().toISOString(),
+    specRoot,
+    items: [...items]
+      .map(normalizeWorkItemRecord)
+      .sort((a, b) => a.canonicalId.localeCompare(b.canonicalId, "en")),
+  };
+}
+
+/** Deterministic JSON for file diff / tests (sorted keys, sorted items). */
+export function stringifyWorkItemMeta(doc: WorkItemMetaDocument): string {
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}

package/lib/cli/work-items/infer-bug-sys.ts

@@ -0,0 +1,147 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseWorkItemCanonicalId } from "../comments/item-comments";
+import type { WorkItemRecord } from "../sync/work-item-meta";
+import { resolveBugParentSysDir } from "./write-bug-to-spec";
+
+const SYS_DIR_RE = /^SYS-(\d{3})-/i;
+
+function listSysFolderNames(technicalDir: string): string[] {
+  if (!fs.existsSync(technicalDir)) return [];
+  return fs
+    .readdirSync(technicalDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && SYS_DIR_RE.test(e.name))
+    .map((e) => e.name)
+    .sort((a, b) => a.localeCompare(b, "en"));
+}
+
+function sysIdFromFolderName(folderName: string): string {
+  const m = folderName.match(SYS_DIR_RE);
+  if (!m?.[1]) throw new Error(`invalid SYS folder name: ${folderName}`);
+  return `SYS-${m[1]}`;
+}
+
+function readFirstHeading(mdPath: string): string {
+  try {
+    const text = fs.readFileSync(mdPath, "utf8");
+    const line = text.match(/^#\s+([^\n]+)/m)?.[1]?.trim();
+    return line ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function tokenizeForOverlap(s: string): Set<string> {
+  const out = new Set<string>();
+  for (const w of s.toLowerCase().split(/[^a-z0-9]+/)) {
+    if (w.length >= 3) out.add(w);
+  }
+  return out;
+}
+
+function overlapScore(a: string, b: string): number {
+  const ta = tokenizeForOverlap(a);
+  const tb = tokenizeForOverlap(b);
+  let n = 0;
+  for (const w of ta) {
+    if (tb.has(w)) n++;
+  }
+  return n;
+}
+
+function buildSysCorpus(sysDir: string, folderName: string): string {
+  const parts: string[] = [folderName.replace(/-/g, " ")];
+  let sysMd: string | undefined;
+  try {
+    for (const f of fs.readdirSync(sysDir)) {
+      if (/^SYS-\d{3}.*\.md$/i.test(f)) {
+        sysMd = path.join(sysDir, f);
+        break;
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  if (sysMd) parts.push(readFirstHeading(sysMd));
+  try {
+    for (const e of fs.readdirSync(sysDir, { withFileTypes: true })) {
+      if (e.isDirectory() && /^STORY-\d{3}-/i.test(e.name)) {
+        parts.push(e.name.replace(/-/g, " "));
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return parts.join(" ");
+}
+
+function bugTextForInference(record: WorkItemRecord): string {
+  const bits = [record.title ?? ""];
+  for (const c of record.comments ?? []) {
+    bits.push(c.body);
+    bits.push(c.user);
+  }
+  return bits.join("\n");
+}
+
+/**
+ * Resolve **SYS-NNN** for nesting a remote bug: explicit `record.sysId`, else single subsystem,
+ * else best token overlap against SYS folder slug, SYS markdown title, and STORY folder names.
+ */
+export function inferSysIdForRemoteBug(
+  specRoot: string,
+  record: WorkItemRecord,
+): string {
+  if (record.kind !== "bug") {
+    throw new Error("inferSysIdForRemoteBug: expected kind bug");
+  }
+
+  const root = path.resolve(specRoot);
+  const technical = path.join(root, "technical");
+  const dirs = listSysFolderNames(technical);
+  if (dirs.length === 0) {
+    throw new Error("no `technical/SYS-NNN-*` subsystem folders");
+  }
+
+  const rawSys = record.sysId?.trim();
+  if (rawSys) {
+    const { prefix, canonicalId } = parseWorkItemCanonicalId(rawSys);
+    if (prefix !== "SYS") {
+      throw new Error(`sysId must be SYS-NNN (got "${rawSys}")`);
+    }
+    const parent = resolveBugParentSysDir(root, canonicalId);
+    if (!parent) {
+      throw new Error(
+        `no folder matches sysId ${canonicalId} under technical/ (create that subsystem or fix sysId)`,
+      );
+    }
+    return canonicalId;
+  }
+
+  if (dirs.length === 1) {
+    return sysIdFromFolderName(dirs[0]!);
+  }
+
+  const bugText = bugTextForInference(record);
+  const scored = dirs.map((name) => {
+    const sysDir = path.join(technical, name);
+    const corpus = buildSysCorpus(sysDir, name);
+    return {
+      sysId: sysIdFromFolderName(name),
+      score: overlapScore(bugText, corpus),
+    };
+  });
+  scored.sort((a, b) => b.score - a.score);
+
+  if (scored[0]!.score === 0) {
+    throw new Error(
+      `cannot infer SYS for ${record.canonicalId} (no keyword overlap with any subsystem); set "sysId" on the remote item. Subsystems: ${scored.map((s) => s.sysId).join(", ")}.`,
+    );
+  }
+  if (scored.length > 1 && scored[0]!.score === scored[1]!.score) {
+    throw new Error(
+      `ambiguous SYS for ${record.canonicalId} (${scored[0]!.sysId} and ${scored[1]!.sysId} both score ${scored[0]!.score}); set "sysId" on the remote item.`,
+    );
+  }
+  return scored[0]!.sysId;
+}

package/lib/cli/work-items/remote-bug-import-scaffold.ts

@@ -0,0 +1,32 @@
+import type { WorkItemRecord } from "../sync/work-item-meta";
+
+/**
+ * Summary body for a bug materialized from remote sync: same refinement contract as
+ * `bug start` (Draft steering → agent removes block after synthesizing Summary).
+ */
+export function buildRemoteBugImportSummaryBody(record: WorkItemRecord): string {
+  const commentBlocks =
+    record.comments?.length ?
+      record.comments
+        .map((c) => {
+          const quoted = c.body
+            .trim()
+            .split(/\r?\n/)
+            .map((line) => (line.length ? `> ${line}` : ">"))
+            .join("\n");
+          return `**${c.user}** (\`${c.email}\`, ${c.createdAt}):\n\n${quoted}\n`;
+        })
+        .join("\n")
+    : "_*(no comments in remote snapshot)*_\n";
+
+  return `*(Replace with a clear defect summary per \`prompts/items/bug-document-structure.md\`. **Synthesize** from **Draft steering (remote import)** below — remove that section when done.)*
+
+## Draft steering (remote import)
+
+**Remote title:** ${(record.title ?? "").trim() || "(empty)"}
+
+**Tracker comments:**
+
+${commentBlocks}
+`;
+}

package/lib/cli/work-items/write-bug-to-spec.ts

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import path from "node:path";
+import { slugifyDescription } from "../core/slug";
+import { parseWorkItemCanonicalId } from "../comments/item-comments";
+
+/**
+ * Pick `technical/SYS-NNN-*` to nest a new BUG under.
+ * Uses `sysId` when set (`SYS-001`); otherwise the first existing `SYS-*` folder (sorted).
+ */
+export function resolveBugParentSysDir(
+  specRoot: string,
+  sysId?: string,
+): string | undefined {
+  const technical = path.join(path.resolve(specRoot), "technical");
+  if (!fs.existsSync(technical)) return undefined;
+  const dirs = fs
+    .readdirSync(technical, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && /^SYS-\d{3}-/i.test(e.name))
+    .map((e) => e.name)
+    .sort((a, b) => a.localeCompare(b, "en"));
+  if (dirs.length === 0) return undefined;
+
+  const want = sysId?.trim().match(/^SYS-(\d{3})$/i)?.[1];
+  if (want) {
+    const prefix = `SYS-${want}-`;
+    const hit = dirs.find((n) => n.toUpperCase().startsWith(prefix.toUpperCase()));
+    if (hit) return path.join(technical, hit);
+    return undefined;
+  }
+  return path.join(technical, dirs[0]!);
+}
+
+export function bugFolderBaseName(canonicalId: string, title: string): string {
+  const { canonicalId: id } = parseWorkItemCanonicalId(canonicalId);
+  const m = id.match(/^BUG-(\d{3})$/i);
+  const pad = m?.[1] ?? "000";
+  const rawTitle = title?.trim() || "imported";
+  const stripped = rawTitle.replace(
+    new RegExp(`^BUG-${pad}\\s*[—-]?\\s*`, "i"),
+    "",
+  ).trim();
+  const slug = slugifyDescription(stripped || rawTitle);
+  return `BUG-${pad}-${slug || "imported"}`;
+}
+
+export function statusLineForBugMd(state: string): string {
+  const s = state.trim().toLowerCase();
+  if (s === "closed" || s === "draft" || s === "open" || s === "in progress") {
+    return s === "in progress" ? "in progress" : s;
+  }
+  return s || "open";
+}
+
+export function bugHeadingLine(canonicalId: string, title: string): string {
+  const { canonicalId: id } = parseWorkItemCanonicalId(canonicalId);
+  const t = title?.trim() || id;
+  if (/^BUG-\d{3}\b/i.test(t)) return `# ${t}`;
+  return `# ${id} — ${t}`;
+}
+
+export function sysLineForBugFromParent(
+  parentDir: string,
+  sysIdOverride?: string,
+): string {
+  if (sysIdOverride?.trim()) return sysIdOverride.trim();
+  const base = path.basename(parentDir);
+  const m = base.match(/^(SYS-\d{3})/i);
+  return m?.[1]?.toUpperCase() ?? "TBD";
+}
+
+export function buildBugMarkdownContent(input: {
+  canonicalId: string;
+  title: string;
+  state: string;
+  sysLine: string;
+  summaryBody: string;
+}): string {
+  const { canonicalId } = parseWorkItemCanonicalId(input.canonicalId);
+  const summary = input.summaryBody.replace(/\n+$/, "");
+  return [
+    bugHeadingLine(canonicalId, input.title),
+    "",
+    `**Id:** ${canonicalId}`,
+    `**SYS:** ${input.sysLine}`,
+    `**Status:** ${statusLineForBugMd(input.state)}`,
+    "",
+    "## Summary",
+    "",
+    summary,
+    "",
+  ].join("\n");
+}
+
+export type WriteBugToSpecInput = {
+  specRoot: string;
+  canonicalId: string;
+  title: string;
+  state: string;
+  /** Overrides **SYS:** line; otherwise derived from parent folder name. */
+  sysId?: string;
+  /** Markdown under `## Summary` (may include multiple paragraphs / sections). */
+  summaryBody: string;
+  /** If set, nest the bug here; otherwise {@link resolveBugParentSysDir}. */
+  parentDir?: string;
+};
+
+export type WriteBugToSpecResult = {
+  root: string;
+  itemDir: string;
+  mdPath: string;
+  mdRel: string;
+};
+
+/**
+ * Create `technical/SYS-…/BUG-NNN-slug/BUG-NNN.md` (shared by `bug start` and remote bug materialization).
+ */
+export function writeBugToSpec(input: WriteBugToSpecInput): WriteBugToSpecResult {
+  const root = path.resolve(input.specRoot);
+  const { canonicalId, prefix } = parseWorkItemCanonicalId(input.canonicalId);
+  if (prefix !== "BUG" || !/^BUG-\d{3}$/i.test(canonicalId)) {
+    throw new Error(
+      `[waterfall] write bug: expected BUG-NNN id, got "${input.canonicalId}"`,
+    );
+  }
+
+  const parent =
+    input.parentDir ?? resolveBugParentSysDir(root, input.sysId);
+  if (!parent) {
+    throw new Error(
+      `[waterfall] write bug: no \`technical/SYS-NNN-*\` folder under spec; add a subsystem or pass a matching \`sysId\` (${canonicalId}).`,
+    );
+  }
+
+  const folderBase = bugFolderBaseName(canonicalId, input.title);
+  const itemDir = path.join(parent, folderBase);
+  if (fs.existsSync(itemDir)) {
+    throw new Error(
+      `[waterfall] write bug: folder already exists: ${path.relative(root, itemDir)}`,
+    );
+  }
+
+  const mdName = `${canonicalId}.md`;
+  const mdPath = path.join(itemDir, mdName);
+  fs.mkdirSync(itemDir, { recursive: true });
+
+  const sysLine = sysLineForBugFromParent(parent, input.sysId);
+  const body = buildBugMarkdownContent({
+    canonicalId,
+    title: input.title,
+    state: input.state,
+    sysLine,
+    summaryBody: input.summaryBody,
+  });
+  fs.writeFileSync(mdPath, body, "utf8");
+
+  const mdRel = path.relative(root, mdPath).split(path.sep).join("/");
+  return { root, itemDir, mdPath, mdRel };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@pknx/waterfall-cli",
+  "version": "0.1.0",
+  "description": "CLI for waterfall-spec workflows: CR/story lifecycle, agent prompts, work-item sync, PDF export.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "waterfall",
+    "waterfall-spec",
+    "cli",
+    "cursor",
+    "spec",
+    "workflow",
+    "agent"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "waterfall": "bin/waterfall.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "prompts",
+    "spec-template",
+    "README.md",
+    "LICENSE",
+    "!lib/**/*.test.ts"
+  ],
+  "scripts": {
+    "build": "echo \"@pknx/waterfall-cli: TypeScript runs via tsx at runtime; no compile step.\"",
+    "test": "vitest run",
+    "prepublishOnly": "npm test",
+    "pack:check": "npm pack --dry-run",
+    "waterfall": "node bin/waterfall.mjs",
+    "link:global": "npm link .",
+    "link:global:sudo": "sudo npm link ."
+  },
+  "dependencies": {
+    "@mermaid-js/mermaid-cli": "^11.12.0",
+    "pandoc-wasm": "^1.0.1",
+    "puppeteer": "^23.11.1",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "markdownlint-cli": "^0.48.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}

package/prompts/commands/bug-start.md

@@ -0,0 +1,46 @@
+# Process: start a new BUG (`waterfall bug start`)
+
+## Purpose
+
+Create a new **BUG** folder under an existing **`technical/SYS-<NNN>-<slug>/`**, with a minimal **`BUG-<NNN>.md`** scaffold, and advance `number.json` `next.BUG`.
+
+The **Waterfall CLI** runs **mechanical** scaffold + commit first, then invokes this prompt with **`--execute-agent`** (or dry-run) so **Summary** is **synthesized** prose per **`bug-document-structure`**, not an italic placeholder.
+
+## When this prompt runs (agent refinement — phase 2)
+
+The CLI has **already** created **`technical/SYS-…/BUG-<NNN>-<slug>/BUG-<NNN>.md`** (placeholder **Summary** + **`## Draft steering (CLI)`** nested under the matching SYS), bumped **`number.json`**, and **committed**.
+
+**Your task:** edit **only** that **`BUG-<NNN>.md`**:
+
+- Replace the **Summary** placeholder with a clear defect description per **[`bug-document-structure.md`](../items/bug-document-structure.md)** — **synthesize** from **Draft steering**; **no verbatim paste** as the only Summary.
+- **Remove** **`## Draft steering (CLI)`** (and nested content under it) when done.
+- Keep **Id**, **SYS**, **Status** unchanged unless correcting a clear mistake.
+
+**Out of scope for this agent pass:** **`number.json`**, other artifacts, SYS or STORY rewrites.
+
+## Scope of edits — mechanical phase only (CLI / human)
+
+Only touch:
+
+- New folder: `technical/SYS-…/BUG-<NNN>-<slug>/`
+- New file: `BUG-<NNN>.md`
+- `number.json` (`next.BUG` increment in same change)
+
+## Rules
+
+1. Use `next.BUG` as the numeric source of truth (three-digit, zero-padded).
+2. Keep folder slug kebab-case and short.
+3. `BUG-<NNN>.md` must include identity fields and **`## Summary`** per **[`bug-document-structure.md`](../items/bug-document-structure.md)**.
+
+### Operator steering vs canonical BUG prose
+
+The CLI **`waterfall bug start`** scaffold may include **`## Draft steering (CLI)`** and an italic placeholder under **Summary**.
+
+- **Synthesize** defect narrative from that steering — **not** a 1:1 paste of the steering block.
+- **Remove** **`## Draft steering (CLI)`** when **Summary** is complete.
+
+## Done when
+
+- **Summary** reads like a real defect report (repro + expected/actual where applicable).
+- **Draft steering** is removed.
+- Typed references to other items use **ids only**, not paths.

package/prompts/commands/cr-finish.md

@@ -0,0 +1,44 @@
+# Process: finish CR feature branch (`waterfall cr finish`)
+
+## Purpose
+
+**Before** running the CLI, use this checklist so the CR is **substantively** ready (content, consistency, completeness). The **`waterfall cr finish`** command only enforces **mechanical** git/spec rules and then **merges** your **`feature/CR-…`** branch **into local `develop`** (no PR flow).
+
+| Layer | Responsibility |
+|--------|----------------|
+| **This prompt (agent / human)** | Meaningful spec content: sections not empty, internal consistency, required links and downstream refs, triage state matches claims. |
+| **CLI `cr finish`** | Clean tree, commits ahead of `develop`, non-empty diff vs `develop`, `number.json` + **`changerequests/CR-<NNN>-*/CR-<NNN>.md`** present, no accidental `CURSOR.md` / `schemas/` in that diff, then **merge** into **`develop`**. |
+
+## Scope of edits (strict)
+
+| In scope | When |
+|----------|------|
+| **Mechanical fixes only** | Broken markdown links, front-matter typos (**Id**), `number.json` syntax — fixes that do not add new product scope. |
+| **Substance** | Filled **CR** sections, valid **Links and dependencies**, readiness to integrate — validated **via this prompt only**, not by the CLI. |
+
+**Out of scope here:** **New** **RQ**/**UC**/**STORY**/**TST** creation as part of “finish”; if triage is incomplete, stop and use the right edge prompt (**`cr-to-rq.md`**, etc.) before **`cr finish`**.
+
+## Preconditions
+
+- On **`feature/CR-<NNN>`** or **`feature/CR-<NNN>-<slug>`** (see **`CURSOR.md`**).
+- **[`before-changing-spec.md`](../global/before-changing-spec.md)** — understand what will integrate: **`git diff develop`**, **`git diff develop...HEAD`**.
+
+## Validation checklist (prompt only — not enforced by CLI)
+
+1. **Working tree** — intentional changes are **committed** or will be picked up by **`git add -A`** on finish; no stray untracked noise.
+2. **CR body** — **Summary** and scoped sections are **non-placeholder**; **Status** and **Links** match reality.
+3. **Downstream references** — links in **`## Links and dependencies`** resolve to existing artifacts where claimed.
+4. **`number.json`** — counters and ids are **consistent** with files on the branch (CLI only checks JSON shape + presence of **`next`**).
+5. **Closed artifacts** — no inappropriate edits under **`_STORY-*`** / **`_BUG-*`** for new scope.
+6. **Branch policy** — **`chore/*`** not used; work stayed on **`feature/CR-*`**.
+
+When this checklist passes, run **`waterfall cr finish`**.
+
+## CLI behavior (reference)
+
+The command commits remaining changes if needed, runs mechanical checks, **`git checkout develop`**, and **`git merge --no-ff`** the feature branch. If a check fails, it prints an error and **does not** merge.
+
+## Done when
+
+- Prompt checklist: **pass** or explicit fail with reasons.
+- CLI: **`develop`** checked out and feature branch **merged** locally, or CLI error with no merge.

package/prompts/commands/cr-start.md

@@ -0,0 +1,65 @@
+# Process: start a new CR (`waterfall cr start`)
+
+## Purpose
+
+Bootstrap a new change request **CR-NNN** with minimal files and a dedicated branch **`feature/CR-NNN-short-slug`** from **`develop`**, per **[`CURSOR.md`](CURSOR.md)** (Git workflow). **Convention:** **NNN** is the **three-digit zero-padded** id (e.g. `005`); **short-slug** is kebab-case — substitute both in every path and branch name.
+
+The **Waterfall CLI** does this in **two steps:** (1) **mechanical** — git + scaffold + `number.json` + commit; (2) **agent** — runs this prompt with **`--execute-agent`** (or dry-run preview) so **Summary** and **Proposed change** are **meaningful synthesized prose**, not placeholders.
+
+## When this prompt runs (agent refinement — phase 2)
+
+The CLI has **already** created the branch, written **`changerequests/CR-NNN-short-slug/CR-NNN.md`** (placeholders + **`## Draft steering (CLI)`**), bumped **`number.json`**, and **committed**. **Git diff vs `develop`** in the wire payload lists what changed.
+
+**Your task:** edit **only** that **`CR-NNN.md`** file:
+
+- Replace italic **Summary** and **Proposed change** placeholders with real sections per **[`cr-document-structure.md`](../items/cr-document-structure.md)** — **synthesize** from **Draft steering** and the operator hint; **no verbatim paste** of steering as the only content.
+- **Remove** **`## Draft steering (CLI)`** when done.
+- Keep **Id**, **Status**, **`## Links and dependencies`** / **`### Downstream references`** shape intact (downstream may stay empty).
+
+**Out of scope for this agent pass:** **`number.json`**, **`git`**, any other path, **`RQ-*`** / **`UC-*`**. Do not re-run scaffold or change the assigned **CR-NNN** id.
+
+## Scope of edits — mechanical phase only (CLI / human without agent)
+
+When performing the **full** bootstrap **without** the CLI (or documenting what the CLI does first), only touch:
+
+- **New folder + file:** `changerequests/CR-NNN-short-slug/CR-NNN.md`
+- **`number.json`:** read **`next.CR`** for **NNN**, then increment **`next.CR`** in the **same** commit
+
+**Out of scope:** `RQ-*`, `UC-*`, `SYS-*`, `STORY-*`, `BUG-*`, `TST-*`, any existing `CR-*` except the new pair, **`CURSOR.md`**. Do not create RQ or UC here — use **[`cr-to-rq.md`](cr-to-rq.md)** after the CR prose exists.
+
+## Preconditions
+
+- **`develop`** is current enough for your team (`git pull` if you use a remote).
+- Read **[`before-changing-spec.md`](../global/before-changing-spec.md)** before touching **`number.json`** or **`changerequests/`**.
+- **`next.CR`** must be the next free id (see **`CURSOR.md`**, **`number.json`**).
+
+## Rules
+
+1. **Branch:** from **`develop`**, create **`feature/CR-NNN-short-slug`**. The **`feature/`** prefix is mandatory (bare `cr-NNN-…` without `feature/` is out of process).
+2. **Slug:** kebab-case from the user description; short, filesystem-safe.
+3. **CR markdown:** include **Id**, **Status:** `draft`, plus **Summary** — **no** **`**Upstream:**`** field and **no** **`### Upstream`** (see **[`cr-document-structure.md`](../items/cr-document-structure.md)**).
+4. Include `## Links and dependencies` with a `### Downstream references` subsection only (empty on creation, filled during CR -> RQ).
+5. Linking this CR from **CR-001** is optional and can be a separate change unless team policy bundles it.
+
+### Operator steering vs canonical CR prose
+
+The CLI **`waterfall cr start`** scaffold may include **`## Draft steering (CLI)`** (blockquoted raw operator text) and italic placeholders under **Summary** / **Proposed change**. That steering is **input only**, not shippable spec.
+
+- **Synthesize:** derive goals, scope, constraints, and rationale from the steering text; write **new** markdown that satisfies **[`cr-document-structure.md`](../items/cr-document-structure.md)**.
+- **Forbidden:** leaving **Summary** or **Proposed change** as a **verbatim copy** of **Draft steering** or of the operator hint in the agent wire payload.
+- **Remove** **`## Draft steering (CLI)`** once canonical sections read well on their own.
+
+## Steps
+
+1. `git checkout develop` and `git pull` if applicable.
+2. `git checkout -b feature/CR-NNN-short-slug`.
+3. Read **`number.json`** → **`next.CR`** → form **NNN** with three-digit padding in filenames.
+4. Create **`changerequests/CR-NNN-short-slug/`** and add **`CR-NNN.md`** inside it.
+5. Set **`next.CR`** to NNN+1 in **`number.json`** in the same commit.
+6. Commit on the feature branch (e.g. `feat(CR-NNN): scaffold change request`).
+
+## Done when
+
+- Branch **`feature/CR-NNN-short-slug`** contains only the new CR markdown and **`number.json`** bump.
+- No RQ, UC, STORY, or TST files were created in this pass.
+