@pknx/waterfall-cli 0.1.0

package/lib/cli/spec/spec-init.ts

@@ -0,0 +1,216 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { gitExecSync } from "../git/git-cli";
+import { POM_JSON_BASENAME } from "../project/pom-json";
+
+const DEFAULT_NUMBER_JSON = {
+  next: { CR: 1, RQ: 1, UC: 1, SYS: 1, STORY: 1, BUG: 1, TST: 1, HOR: 1 },
+};
+
+/** Minimal spec “law” so agents and `waterfall spec init` trees match prompts that reference CURSOR.md. */
+export const SPEC_SCAFFOLD_CURSOR_MD = `# Cursor guidance — waterfall spec (scaffold)
+
+This repository is a **structured requirements** tree (lifecycle **CR → RQ → UC → …**), not application source code.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| \`changerequests/\` | **CR-*** — one folder \`CR-<NNN>-<slug>/\` with canonical \`CR-<NNN>.md\` |
+| \`requirements/\` | **RQ-*** (\`RQ-<NNN>-<slug>/RQ-<NNN>.md\` + **UC-***) |
+| \`technical/\` | **SYS-*** (\`SYS-<NNN>-<slug>/SYS-<NNN>.md\`), **STORY-***, **BUG-*** |
+| \`technical/horizontals/\` | **HOR-*** (\`HOR-<NNN>-<slug>/HOR-<NNN>.md\`) |
+| \`tests/\` | **TST-*** test specifications |
+| \`number.json\` | Next numeric ids for artifacts |
+
+## Agents / Waterfall CLI
+
+When **Waterfall CLI** runs a built-in lifecycle prompt here, **only** change the artifact types that prompt allows. Full checklists live in **\`waterfall-cli/prompts/commands/\`**. **Operator hints** from the CLI are steering context — interpret them; do not paste them verbatim into Summary, Purpose, or titles. Do not copy **\`prompts/\`** structure text into spec files as filler.
+
+## Git (summary)
+
+Use **\`feature/CR-<NNN>-…\`** (or **\`feature/<short-slug>\`** for non-CR work) for spec edits; do not land CR-scoped work directly on **\`develop\`** without your team’s merge process.
+
+Expand this file for project-specific rules. A fuller template lives in **\`waterfall-spec\`** repos.
+`;
+
+/** Appended to \`CURSOR.md\` when \`waterfall spec init --full\` copies the template tree. */
+const CURSOR_FULL_SCAFFOLD_APPEND = `
+
+## Local prompt index (full scaffold)
+
+- **[prompts/workflows.md](./prompts/workflows.md)** — maps lifecycle steps to Waterfall CLI commands and shipped prompts.
+- **[prompts/before-changing-spec.md](./prompts/before-changing-spec.md)** — pointer to global editing rules in the CLI package.
+- **[doc/spec-structure.md](./doc/spec-structure.md)** — quick directory reference (non-normative).
+`;
+
+function git(specRoot: string, args: string[]): void {
+  gitExecSync(specRoot, args, { stdio: "inherit" });
+}
+
+/** Absolute path to \`spec-template/full\` (files mirrored into the spec repo). */
+export function specTemplateFullRoot(): string {
+  /** `lib/cli/spec` → `lib/cli` → `lib` → package root, then `spec-template/full`. */
+  return path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "..",
+    "spec-template",
+    "full",
+  );
+}
+
+/**
+ * Copy \`spec-template/full/**\` into \`targetAbs\` (recursive). Skips missing template root.
+ */
+export function copyFullSpecTemplate(targetAbs: string): void {
+  const root = specTemplateFullRoot();
+  if (!fs.existsSync(root)) {
+    throw new Error(`Full spec template missing: ${root}`);
+  }
+
+  function walk(rel: string): void {
+    const src = path.join(root, rel);
+    const st = fs.statSync(src);
+    if (st.isDirectory()) {
+      for (const name of fs.readdirSync(src)) {
+        walk(path.join(rel, name));
+      }
+      return;
+    }
+    const dest = path.join(targetAbs, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, fs.readFileSync(src), "utf8");
+  }
+
+  for (const name of fs.readdirSync(root)) {
+    walk(name);
+  }
+}
+
+export type SpecInitOptions = {
+  /** Human-readable project name; written to \`pom.json\` at the init target root. */
+  title: string;
+  /** Add \`prompts/**\`, \`doc/spec-structure.md\`, and extend \`CURSOR.md\` (from \`spec-template/full\`). */
+  full?: boolean;
+};
+
+export type ParsedSpecInitCli = {
+  full: boolean;
+  title: string;
+  targetDir: string;
+};
+
+/**
+ * Parse argv after \`spec init\`: requires \`--title\` (or \`--title=…\`); optional \`--full\`; remaining tokens = DIR.
+ */
+export function parseSpecInitCliArgs(tail: string[]): ParsedSpecInitCli {
+  let full = false;
+  let title: string | undefined;
+  const rest: string[] = [];
+  for (let i = 0; i < tail.length; i++) {
+    const a = tail[i]!;
+    if (a === "--full") {
+      full = true;
+      continue;
+    }
+    if (a === "--title") {
+      const v = tail[++i];
+      if (!v || v.startsWith("--")) {
+        throw new Error(
+          'spec init: --title requires a value (e.g. --title "My project")',
+        );
+      }
+      title = v;
+      continue;
+    }
+    if (a.startsWith("--title=")) {
+      const v = a.slice("--title=".length);
+      if (!v.trim()) {
+        throw new Error("spec init: --title= requires a non-empty value");
+      }
+      title = v;
+      continue;
+    }
+    rest.push(a);
+  }
+  if (!title?.trim()) {
+    throw new Error(
+      'spec init: required --title "…" is missing (project name for pom.json). Example: waterfall spec init --title "My product" ./my-spec',
+    );
+  }
+  const targetDir = rest.join(" ").trim() || ".";
+  return { full, title: title.trim(), targetDir };
+}
+
+/**
+ * Creates a new waterfall-spec-shaped directory: pom.json, layout, number.json, CURSOR.md, local git on develop.
+ * Use \`{ full: true }\` for the regeneratable template tree under \`waterfall-cli/spec-template/full/\`.
+ */
+export function runSpecInit(
+  cwd: string,
+  rawTargetDir: string,
+  options: SpecInitOptions,
+): void {
+  const abs = path.resolve(cwd, rawTargetDir.trim() || ".");
+  const projectTitle = options.title.trim();
+  if (!projectTitle) {
+    throw new Error("spec init: title must be a non-empty string (after trim)");
+  }
+
+  if (fs.existsSync(path.join(abs, POM_JSON_BASENAME))) {
+    throw new Error(`Refusing to init: ${POM_JSON_BASENAME} already exists: ${abs}`);
+  }
+  if (fs.existsSync(path.join(abs, "number.json"))) {
+    throw new Error(`Refusing to init: number.json already exists: ${abs}`);
+  }
+  if (fs.existsSync(path.join(abs, ".git"))) {
+    throw new Error(`Refusing to init: already a Git repository: ${abs}`);
+  }
+  if (fs.existsSync(abs) && fs.readdirSync(abs).length > 0) {
+    throw new Error(`Refusing to init: directory is not empty: ${abs}`);
+  }
+
+  fs.mkdirSync(abs, { recursive: true });
+  fs.writeFileSync(
+    path.join(abs, POM_JSON_BASENAME),
+    `${JSON.stringify({ title: projectTitle }, null, 2)}\n`,
+    "utf8",
+  );
+  for (const d of ["changerequests", "requirements", "technical", "tests"]) {
+    const sub = path.join(abs, d);
+    fs.mkdirSync(sub, { recursive: true });
+    fs.writeFileSync(path.join(sub, ".gitkeep"), "", "utf8");
+  }
+  const hor = path.join(abs, "technical", "horizontals");
+  fs.mkdirSync(hor, { recursive: true });
+  fs.writeFileSync(path.join(hor, ".gitkeep"), "", "utf8");
+  fs.writeFileSync(
+    path.join(abs, "number.json"),
+    `${JSON.stringify(DEFAULT_NUMBER_JSON, null, 2)}\n`,
+    "utf8",
+  );
+
+  if (options.full) {
+    copyFullSpecTemplate(abs);
+  }
+
+  const cursorBody = options.full
+    ? `${SPEC_SCAFFOLD_CURSOR_MD.replace(/\n$/, "")}${CURSOR_FULL_SCAFFOLD_APPEND}`
+    : SPEC_SCAFFOLD_CURSOR_MD;
+  fs.writeFileSync(path.join(abs, "CURSOR.md"), cursorBody, "utf8");
+
+  git(abs, ["init", "-b", "develop"]);
+  git(abs, ["config", "user.email", "waterfall-spec-init@local"]);
+  git(abs, ["config", "user.name", "waterfall spec init"]);
+  git(abs, ["add", "-A"]);
+  git(abs, [
+    "commit",
+    "-m",
+    options.full
+      ? "chore: init waterfall spec scaffold (full)"
+      : "chore: init waterfall spec scaffold",
+  ]);
+}

package/lib/cli/spec/spec-root.ts

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export type ResolveSpecRootOptions = {
+  env?: NodeJS.ProcessEnv;
+  cwd: string;
+  /** From `--spec-root` */
+  explicitSpecRoot?: string;
+};
+
+/**
+ * Resolution order (STORY-018 — keep in sync with spec / tests):
+ * 1. Merged global `specRoot` (CLI `--spec-root` > `WATERFALL_SPEC_ROOT` > `./.waterfall` / `~/.waterfall` `spec_root`, cwd file wins) passed as explicitSpecRoot
+ * 2. `WATERFALL_SPEC_ROOT` (fallback if explicitSpecRoot unset)
+ * 3. Nearest `waterfall.json` (walking up from cwd): `waterfallSpecRelativePath` resolved from that file’s directory
+ * 4. Walk up from cwd for a directory containing `CURSOR.md`
+ */
+export function resolveSpecRoot(opts: ResolveSpecRootOptions): string {
+  const env = opts.env ?? process.env;
+  if (opts.explicitSpecRoot?.trim()) {
+    return path.resolve(opts.cwd, opts.explicitSpecRoot.trim());
+  }
+  if (env.WATERFALL_SPEC_ROOT?.trim()) {
+    return path.resolve(opts.cwd, env.WATERFALL_SPEC_ROOT.trim());
+  }
+  const fromWaterfallJson = findSpecViaWaterfallJson(opts.cwd);
+  if (fromWaterfallJson) return fromWaterfallJson;
+  const walked = walkForCursorPrompts(opts.cwd);
+  if (walked) return walked;
+  throw new Error(
+    "Could not resolve waterfall-spec root. Set WATERFALL_SPEC_ROOT, pass --spec-root, run from a directory with waterfall.json + waterfallSpecRelativePath, or from inside a waterfall-spec checkout (CURSOR.md).",
+  );
+}
+
+function findSpecViaWaterfallJson(start: string): string | undefined {
+  let dir = path.resolve(start);
+  const { root } = path.parse(dir);
+  for (;;) {
+    const wj = path.join(dir, "waterfall.json");
+    if (fs.existsSync(wj)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(wj, "utf8")) as {
+          waterfallSpecRelativePath?: string;
+        };
+        if (raw.waterfallSpecRelativePath) {
+          const spec = path.resolve(dir, raw.waterfallSpecRelativePath);
+          if (isResolvableSpecPath(spec)) return spec;
+        }
+      } catch {
+        /* ignore malformed */
+      }
+    }
+    if (dir === root) break;
+    dir = path.dirname(dir);
+  }
+  return undefined;
+}
+
+function walkForCursorPrompts(start: string): string | undefined {
+  let dir = path.resolve(start);
+  const { root } = path.parse(dir);
+  for (;;) {
+    if (isSpecRoot(dir)) return dir;
+    if (dir === root) break;
+    dir = path.dirname(dir);
+  }
+  return undefined;
+}
+
+export function isSpecRoot(absPath: string): boolean {
+  const cursor = path.join(absPath, "CURSOR.md");
+  return fs.existsSync(cursor);
+}
+
+/** Scaffold from waterfall spec init: number.json + changerequests/ (CURSOR.md optional but now written by spec init). */
+export function isScaffoldSpecRoot(absPath: string): boolean {
+  const num = path.join(absPath, "number.json");
+  const cr = path.join(absPath, "changerequests");
+  if (!fs.existsSync(num) || !fs.existsSync(cr)) return false;
+  return fs.statSync(cr).isDirectory();
+}
+
+function isResolvableSpecPath(absPath: string): boolean {
+  return isSpecRoot(absPath) || isScaffoldSpecRoot(absPath);
+}
+
+export function assertSpecRoot(absPath: string): void {
+  if (!isResolvableSpecPath(absPath)) {
+    throw new Error(
+      `Not a valid waterfall-spec root (missing CURSOR.md or spec scaffold — number.json + changerequests/): ${absPath}`,
+    );
+  }
+}

package/lib/cli/sync/apply-remote-comments.ts

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import {
+  parseWorkItemCanonicalId,
+  resolveItemCommentStorage,
+  type ItemCommentEntry,
+  type ItemCommentsFile,
+  type ItemCommentState,
+} from "../comments/item-comments";
+import type { WorkItemSyncKind } from "./provider-types";
+import type { WorkItemComment, WorkItemRecord } from "./work-item-meta";
+
+function parseBodyToStateAndHint(body: string): {
+  state: ItemCommentState;
+  hint: string;
+} {
+  const m = body.match(/^\[(OPEN|RESOLVED|REJECTED)\]\s*([\s\S]*)$/);
+  if (m) {
+    return { state: m[1] as ItemCommentState, hint: m[2] ?? "" };
+  }
+  return { state: "OPEN", hint: body };
+}
+
+function stableCommentId(c: WorkItemComment): string {
+  const ext = c.externalId?.trim();
+  if (ext) return ext;
+  const h = createHash("sha256")
+    .update(`${c.email}\0${c.createdAt}\0${c.body}`)
+    .digest("hex")
+    .slice(0, 24);
+  return `sync:${h}`;
+}
+
+function remoteCommentToEntry(c: WorkItemComment): ItemCommentEntry {
+  const { state, hint } = parseBodyToStateAndHint(c.body);
+  const t = c.createdAt;
+  return {
+    id: stableCommentId(c),
+    from: c.user,
+    email: c.email,
+    hint,
+    state,
+    createdAt: t,
+    updatedAt: t,
+  };
+}
+
+/**
+ * For each remote work item that exists in the spec tree, replace `{id}.comments.json` with the remote
+ * comment list (or an empty `comments` array when remote has none). Remote is authoritative for comments.
+ */
+export function applyRemoteCommentsToSpec(
+  specRoot: string,
+  kind: WorkItemSyncKind,
+  remoteItems: WorkItemRecord[],
+  specCanonicalIds: Set<string>,
+): number {
+  const root = path.resolve(specRoot);
+  let written = 0;
+  for (const r of remoteItems) {
+    if (r.kind !== kind) continue;
+    if (!specCanonicalIds.has(r.canonicalId)) continue;
+    let storage: ReturnType<typeof resolveItemCommentStorage>;
+    try {
+      storage = resolveItemCommentStorage(root, r.canonicalId);
+    } catch {
+      continue;
+    }
+    const { canonicalId: itemId } = parseWorkItemCanonicalId(r.canonicalId);
+    const entries = (r.comments ?? []).map(remoteCommentToEntry);
+    entries.sort((a, b) =>
+      `${a.email}\t${a.createdAt}\t${a.from}`.localeCompare(
+        `${b.email}\t${b.createdAt}\t${b.from}`,
+        "en",
+      ),
+    );
+    const file: ItemCommentsFile = { itemId, comments: entries };
+    fs.writeFileSync(
+      storage.commentsPath,
+      `${JSON.stringify(file, null, 2)}\n`,
+      "utf8",
+    );
+    written++;
+  }
+  return written;
+}

package/lib/cli/sync/attachment-category.ts

@@ -0,0 +1,43 @@
+import type { WorkItemAttachmentCategory } from "./work-item-meta";
+
+/**
+ * Map MIME type or filename to a coarse category for sync and UI.
+ */
+export function attachmentCategoryFromMimeOrName(
+  mimeType?: string,
+  name?: string,
+): WorkItemAttachmentCategory {
+  const m = mimeType?.trim().toLowerCase() ?? "";
+  const base = name?.trim().toLowerCase() ?? "";
+  const ext = base.includes(".") ? base.slice(base.lastIndexOf(".")) : "";
+
+  if (m === "application/pdf" || ext === ".pdf") return "pdf";
+  if (
+    m.startsWith("image/") ||
+    [".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp"].includes(ext)
+  ) {
+    return "image";
+  }
+  if (
+    m.startsWith("video/") ||
+    [".mp4", ".webm", ".mov", ".mkv", ".avi"].includes(ext)
+  ) {
+    return "video";
+  }
+  if (
+    m.includes("spreadsheet") ||
+    m.includes("excel") ||
+    [".xls", ".xlsx", ".ods", ".csv"].includes(ext)
+  ) {
+    return "spreadsheet";
+  }
+  if (
+    m.includes("word") ||
+    m.includes("msword") ||
+    m.includes("wordprocessingml") ||
+    [".doc", ".docx", ".odt", ".rtf"].includes(ext)
+  ) {
+    return "document";
+  }
+  return "other";
+}

package/lib/cli/sync/diff-work-items.ts

@@ -0,0 +1,113 @@
+import type { WorkItemComment, WorkItemRecord } from "./work-item-meta";
+
+export type WorkItemDiffEntry = {
+  canonicalId: string;
+  field: "missing" | "state" | "title" | "comments" | "attachments";
+  spec?: string;
+  remote?: string;
+};
+
+/** Stable compare: author = `email`; sort by `email` + `createdAt`, row includes `user` + `body`. */
+function commentsSignature(c: WorkItemComment[] | undefined): string {
+  if (!c?.length) return "";
+  return JSON.stringify(
+    [...c].sort((a, b) =>
+      `${a.email}\t${a.createdAt}\t${a.user}`.localeCompare(
+        `${b.email}\t${b.createdAt}\t${b.user}`,
+        "en",
+      ),
+    ).map((x) => ({
+      email: x.email,
+      user: x.user,
+      createdAt: x.createdAt,
+      body: x.body,
+    })),
+  );
+}
+
+function attachmentsSignature(
+  a: WorkItemRecord["attachments"],
+): string {
+  if (!a?.length) return "";
+  return JSON.stringify(
+    [...a].sort((x, y) => x.id.localeCompare(y.id, "en")),
+  );
+}
+
+export type WorkItemDiffReport = {
+  onlyInSpec: string[];
+  onlyInRemote: string[];
+  mismatches: WorkItemDiffEntry[];
+};
+
+function byId(items: WorkItemRecord[]): Map<string, WorkItemRecord> {
+  const m = new Map<string, WorkItemRecord>();
+  for (const i of items) m.set(i.canonicalId, i);
+  return m;
+}
+
+/**
+ * Compare spec snapshot vs remote snapshot (same kind).
+ * Comments: compared on author `email` + `createdAt` order and per-row `user` + `body` (see {@link commentsSignature}).
+ */
+export function diffWorkItemSets(
+  specItems: WorkItemRecord[],
+  remoteItems: WorkItemRecord[],
+): WorkItemDiffReport {
+  const A = byId(specItems);
+  const B = byId(remoteItems);
+  const onlyInSpec: string[] = [];
+  const onlyInRemote: string[] = [];
+  const mismatches: WorkItemDiffEntry[] = [];
+
+  for (const id of A.keys()) {
+    if (!B.has(id)) onlyInSpec.push(id);
+  }
+  for (const id of B.keys()) {
+    if (!A.has(id)) onlyInRemote.push(id);
+  }
+  for (const id of A.keys()) {
+    const a = A.get(id)!;
+    const b = B.get(id);
+    if (!b) continue;
+    if (a.state !== b.state) {
+      mismatches.push({
+        canonicalId: id,
+        field: "state",
+        spec: a.state,
+        remote: b.state,
+      });
+    }
+    if (a.title.trim() !== b.title.trim()) {
+      mismatches.push({
+        canonicalId: id,
+        field: "title",
+        spec: a.title,
+        remote: b.title,
+      });
+    }
+    const ca = commentsSignature(a.comments);
+    const cb = commentsSignature(b.comments);
+    if (ca !== cb) {
+      mismatches.push({
+        canonicalId: id,
+        field: "comments",
+        spec: `${a.comments?.length ?? 0} (digest len ${ca.length})`,
+        remote: `${b.comments?.length ?? 0} (digest len ${cb.length})`,
+      });
+    }
+    const aa = attachmentsSignature(a.attachments);
+    const ab = attachmentsSignature(b.attachments);
+    if (aa !== ab) {
+      mismatches.push({
+        canonicalId: id,
+        field: "attachments",
+        spec: `${a.attachments?.length ?? 0} (digest len ${aa.length})`,
+        remote: `${b.attachments?.length ?? 0} (digest len ${ab.length})`,
+      });
+    }
+  }
+  onlyInSpec.sort();
+  onlyInRemote.sort();
+  return { onlyInSpec, onlyInRemote, mismatches };
+}

package/lib/cli/sync/materialize-remote-bugs.ts

@@ -0,0 +1,66 @@
+import { parseWorkItemCanonicalId } from "../comments/item-comments";
+import { inferSysIdForRemoteBug } from "../work-items/infer-bug-sys";
+import { buildRemoteBugImportSummaryBody } from "../work-items/remote-bug-import-scaffold";
+import { writeBugToSpec } from "../work-items/write-bug-to-spec";
+import type { WorkItemRecord } from "./work-item-meta";
+
+export { resolveBugParentSysDir } from "../work-items/write-bug-to-spec";
+
+/**
+ * Create spec folders + `BUG-NNN.md` for each remote bug whose id is not yet in the spec tree.
+ * Only intended when sync leading is `remote` (remote is authoritative for new ids).
+ *
+ * Resolves **SYS** via {@link inferSysIdForRemoteBug} when `sysId` is omitted.
+ * Scaffold matches `bug start` (Draft steering for agent refinement).
+ *
+ * @returns Spec-relative paths to created `BUG-NNN.md` files (forward slashes).
+ */
+export function materializeRemoteOnlyBugsToSpec(
+  specRoot: string,
+  remoteItems: WorkItemRecord[],
+  specCanonicalIds: Set<string>,
+): string[] {
+  const root = specRoot;
+  const mdRels: string[] = [];
+  for (const r of remoteItems) {
+    if (r.kind !== "bug") continue;
+    const { canonicalId } = parseWorkItemCanonicalId(r.canonicalId);
+    if (!/^BUG-\d{3}$/i.test(canonicalId)) continue;
+    if (specCanonicalIds.has(canonicalId)) continue;
+
+    let sysId: string;
+    try {
+      sysId = inferSysIdForRemoteBug(root, r);
+    } catch (e) {
+      throw new Error(
+        `[waterfall] sync bugs: cannot import ${canonicalId} — ${(e as Error).message}`,
+      );
+    }
+
+    try {
+      const { mdRel } = writeBugToSpec({
+        specRoot: root,
+        canonicalId,
+        title: r.title?.trim() || canonicalId,
+        state: r.state,
+        sysId,
+        summaryBody: buildRemoteBugImportSummaryBody(r),
+      });
+      mdRels.push(mdRel);
+    } catch (e) {
+      const msg = (e as Error).message;
+      if (msg.includes("no `technical/SYS-NNN")) {
+        throw new Error(
+          `[waterfall] sync bugs: cannot import ${canonicalId} — no \`technical/SYS-NNN-*\` folder under spec; add a subsystem or set \`sysId\` in the remote item and ensure that SYS exists.`,
+        );
+      }
+      if (msg.includes("folder already exists")) {
+        throw new Error(
+          `[waterfall] sync bugs: cannot import ${canonicalId} — folder already exists under spec`,
+        );
+      }
+      throw e;
+    }
+  }
+  return mdRels;
+}

package/lib/cli/sync/provider-types.ts

@@ -0,0 +1,43 @@
+import type { WorkItemRecord } from "./work-item-meta";
+
+export type WorkItemSyncKind = "story" | "bug";
+
+export type WorkItemProviderContext = {
+  cwd: string;
+  specRoot: string;
+  kind: WorkItemSyncKind;
+  /** Keys from .waterfall `sync_<kind>_<provider>_*` (suffix after sync_story_ / sync_bug_ excluding provider). */
+  options: Record<string, string>;
+  /**
+   * Optional CLI hint (inline argv joined, `-` stdin, `@PATH` file). Most providers ignore it;
+   * `direct` treats it as JSON in the same shape as `--dump-spec`.
+   */
+  hint?: string;
+};
+
+/**
+ * External tracker integration. Implementations map between {@link WorkItemRecord} and the remote API.
+ * Sync applies remote comments to spec, diffs, then adapter-specific output (e.g. direct prints spec JSON).
+ */
+export interface WorkItemSyncProvider {
+  readonly providerId: string;
+
+  /** Items as seen in the remote system (canonical ids should align with spec when linked). Sync for now; HTTP adapters may move to async later. */
+  fetchRemote(ctx: WorkItemProviderContext): WorkItemRecord[];
+
+  /**
+   * Push spec-side changes to remote (issues create/update, transitions). Optional until implemented.
+   */
+  pushToRemote?(
+    ctx: WorkItemProviderContext,
+    items: WorkItemRecord[],
+  ): Promise<void>;
+
+  /**
+   * Apply remote changes into the spec tree. Optional until implemented.
+   */
+  pullToSpec?(
+    ctx: WorkItemProviderContext,
+    items: WorkItemRecord[],
+  ): Promise<void>;
+}

package/lib/cli/sync/providers/direct-provider.ts

@@ -0,0 +1,27 @@
+import type {
+  WorkItemProviderContext,
+  WorkItemSyncProvider,
+} from "../provider-types";
+import type { WorkItemRecord } from "../work-item-meta";
+import { parseWorkItemRecordsFromSyncHintJson } from "../sync-hint-json";
+
+/**
+ * Uses the CLI hint as remote-side JSON: same shape as `--dump-spec` output (object with `items`,
+ * optional `kind` / `source` / …) or a top-level array of {@link WorkItemRecord} objects.
+ * Requires a non-empty hint; validates strictly and returns normalized items for diff/merge paths.
+ * The sync runner always appends the current spec snapshot to stdout as JSON (`source`:
+ * `waterfall-direct-out`) after the text report when using this provider.
+ */
+export class DirectWorkItemSyncProvider implements WorkItemSyncProvider {
+  readonly providerId = "direct";
+
+  fetchRemote(ctx: WorkItemProviderContext): WorkItemRecord[] {
+    const hint = ctx.hint?.trim();
+    if (!hint) {
+      throw new Error(
+        `[waterfall] direct provider: pass a sync JSON hint (inline argv, - for stdin, or @PATH); same shape as sync --dump-spec.`,
+      );
+    }
+    return parseWorkItemRecordsFromSyncHintJson(hint, ctx.kind);
+  }
+}