@pknx/waterfall-cli 0.1.0

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

@@ -0,0 +1,34 @@
+import type { WorkItemRecord } from "../work-item-meta";
+import type {
+  WorkItemProviderContext,
+  WorkItemSyncProvider,
+} from "../provider-types";
+
+/**
+ * Jira Cloud/Server adapter (skeleton). Configure via .waterfall, e.g.:
+ *   sync_story_provider=jira
+ *   sync_story_jira_site=https://your.atlassian.net
+ *   sync_story_jira_project=BOOK
+ * Auth: set JIRA_API_TOKEN + JIRA_USER_EMAIL (or provider-specific env) in .waterfall as UPPER_SNAKE passthrough.
+ * Map Jira comments → WorkItemComment (`email` = author id, `user` = display); attachments → WorkItemAttachment + category via attachmentCategoryFromMimeOrName.
+ */
+export class JiraWorkItemSyncProvider implements WorkItemSyncProvider {
+  readonly providerId = "jira";
+
+  fetchRemote(ctx: WorkItemProviderContext): WorkItemRecord[] {
+    const site = ctx.options.jira_site?.trim();
+    const project = ctx.options.jira_project?.trim();
+    if (!site || !project) {
+      process.stderr.write(
+        `[waterfall] Jira provider: sync_${ctx.kind}_jira_site / sync_${ctx.kind}_jira_project not set — remote snapshot empty (stub; no HTTP yet).\n`,
+      );
+      return [];
+    }
+    void site;
+    void project;
+    process.stderr.write(
+      `[waterfall] Jira provider: API sync not implemented yet (would query ${project} on ${site}).\n`,
+    );
+    return [];
+  }
+}

package/lib/cli/sync/providers/registry.ts

@@ -0,0 +1,26 @@
+import type { WorkItemSyncKind } from "../provider-types";
+import type { WorkItemSyncProvider } from "../provider-types";
+import { DirectWorkItemSyncProvider } from "./direct-provider";
+import { JiraWorkItemSyncProvider } from "./jira-provider";
+
+const jiraSingleton = new JiraWorkItemSyncProvider();
+const directSingleton = new DirectWorkItemSyncProvider();
+
+export function resolveWorkItemSyncProvider(
+  name: string | undefined,
+  kind: WorkItemSyncKind,
+): WorkItemSyncProvider {
+  const n = name?.trim().toLowerCase();
+  const label = kind === "story" ? "stories" : "bugs";
+  const keyPrefix = kind === "story" ? "sync_story" : "sync_bug";
+  if (!n || n === "none" || n === "off") {
+    throw new Error(
+      `[waterfall] sync ${label}: set ${keyPrefix}_provider in .waterfall (e.g. jira) or use --dump-spec only.`,
+    );
+  }
+  if (n === "jira") return jiraSingleton;
+  if (n === "direct") return directSingleton;
+  throw new Error(
+    `[waterfall] sync ${label}: unknown provider "${name}". Supported: jira (stub), direct (hint = sync JSON).`,
+  );
+}

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

@@ -0,0 +1,202 @@
+import type { LogLevel } from "../core/cli-log";
+import { traceExportPdfLine } from "../core/cli-log";
+import type { SyncLeadSystem, SyncWorkItemBlock } from "../config/sync-work-item-config";
+import { effectiveSyncLead } from "../config/sync-work-item-config";
+import { diffWorkItemSets, type WorkItemDiffEntry } from "./diff-work-items";
+import { collectBugsFromSpec, collectStoriesFromSpec } from "./spec-work-items";
+import type { WorkItemProviderContext } from "./provider-types";
+import type { WorkItemSyncKind } from "./provider-types";
+import { applyRemoteCommentsToSpec } from "./apply-remote-comments";
+import { materializeRemoteOnlyBugsToSpec } from "./materialize-remote-bugs";
+import { createMetaDocument, stringifyWorkItemMeta } from "./work-item-meta";
+import { resolveWorkItemSyncProvider } from "./providers/registry";
+
+export type SyncWorkItemsCliOptions = {
+  dumpSpec: boolean;
+  hint?: string;
+};
+
+export type SyncWorkItemsHooks = {
+  /**
+   * After remote comments are applied to spec (so `*.comments.json` is current).
+   * Used to run `sync-bugs-refine-imports` for newly materialized BUG markdown.
+   */
+  afterBugsMaterialized?: (args: {
+    specRoot: string;
+    mdRels: string[];
+  }) => void;
+};
+
+function formatMismatchLeadingNote(m: WorkItemDiffEntry, lead: SyncLeadSystem): string {
+  if (m.field === "state" || m.field === "title") {
+    const val = lead === "waterfall" ? m.spec : m.remote;
+    return `    → leading=${lead}: canonical ${m.field} is ${lead} ${JSON.stringify(val)}\n`;
+  }
+  return `    → leading=${lead}: canonical ${m.field} follows ${lead}\n`;
+}
+
+function collectSpec(kind: WorkItemSyncKind, specRoot: string) {
+  return kind === "story"
+    ? collectStoriesFromSpec(specRoot)
+    : collectBugsFromSpec(specRoot);
+}
+
+export function runSyncWorkItems(
+  specRoot: string,
+  cwd: string,
+  kind: WorkItemSyncKind,
+  block: SyncWorkItemBlock | undefined,
+  logLevel: LogLevel,
+  opts: SyncWorkItemsCliOptions,
+  hooks?: SyncWorkItemsHooks,
+): void {
+  let specItems = collectSpec(kind, specRoot);
+  const specDoc = createMetaDocument(
+    "waterfall-spec",
+    kind,
+    specItems,
+    specRoot,
+  );
+
+  if (opts.dumpSpec) {
+    process.stdout.write(stringifyWorkItemMeta(specDoc));
+    return;
+  }
+
+  const label = kind === "story" ? "stories" : "bugs";
+  const keyPrefix = kind === "story" ? "sync_story" : "sync_bug";
+  const lead = effectiveSyncLead(block, kind);
+  traceExportPdfLine(
+    logLevel,
+    `sync ${label} · provider=${block.provider ?? "(none)"} leading=${lead}${opts.hint?.length ? ` hint=${opts.hint.length}ch` : ""}`,
+  );
+
+  if (!block?.provider?.trim()) {
+    throw new Error(
+      `[waterfall] sync ${label}: set ${keyPrefix}_provider (e.g. jira) in .waterfall for remote compare/push/pull.`,
+    );
+  }
+
+  const ctx: WorkItemProviderContext = {
+    cwd,
+    specRoot,
+    kind,
+    options: block.options,
+    ...(opts.hint !== undefined && opts.hint !== "" ? { hint: opts.hint } : {}),
+  };
+
+  const provider = resolveWorkItemSyncProvider(block.provider, kind);
+  const remoteItems = provider.fetchRemote(ctx);
+
+  let specIds = new Set(specItems.map((x) => x.canonicalId));
+  let materializedBugMdRels: string[] = [];
+  if (kind === "bug" && lead === "remote") {
+    materializedBugMdRels = materializeRemoteOnlyBugsToSpec(
+      specRoot,
+      remoteItems,
+      specIds,
+    );
+    if (materializedBugMdRels.length > 0) {
+      traceExportPdfLine(
+        logLevel,
+        `sync ${label} · materialized ${materializedBugMdRels.length} bug(s) from remote into technical/`,
+      );
+      process.stdout.write(
+        `[waterfall] sync ${label} · created ${materializedBugMdRels.length} bug folder(s) under technical/ from remote\n`,
+      );
+      specItems = collectSpec(kind, specRoot);
+      specIds = new Set(specItems.map((x) => x.canonicalId));
+    }
+  }
+
+  const commentsWritten = applyRemoteCommentsToSpec(
+    specRoot,
+    kind,
+    remoteItems,
+    specIds,
+  );
+  if (commentsWritten > 0) {
+    traceExportPdfLine(
+      logLevel,
+      `sync ${label} · wrote remote comments to ${commentsWritten} work item(s)`,
+    );
+    process.stdout.write(
+      `[waterfall] sync ${label} · wrote remote comments to ${commentsWritten} work item(s)\n`,
+    );
+  }
+  specItems = collectSpec(kind, specRoot);
+
+  if (
+    materializedBugMdRels.length > 0 &&
+    hooks?.afterBugsMaterialized
+  ) {
+    hooks.afterBugsMaterialized({
+      specRoot,
+      mdRels: materializedBugMdRels,
+    });
+    specItems = collectSpec(kind, specRoot);
+  }
+
+  const diff = diffWorkItemSets(specItems, remoteItems);
+  process.stdout.write(
+    `[waterfall] sync ${label} · spec items=${specItems.length} remote items=${remoteItems.length}\n`,
+  );
+  if (diff.onlyInSpec.length) {
+    process.stdout.write(`  only in spec: ${diff.onlyInSpec.join(", ")}\n`);
+    process.stdout.write(
+      lead === "waterfall"
+        ? `    → leading=waterfall: on reconcile, remote should gain these (e.g. push).\n`
+        : `    → leading=remote: spec-only ids are ahead of remote truth; trim or unlink spec to match remote.\n`,
+    );
+  }
+  if (diff.onlyInRemote.length) {
+    process.stdout.write(
+      `  only in remote: ${diff.onlyInRemote.join(", ")}\n`,
+    );
+    process.stdout.write(
+      lead === "waterfall"
+        ? `    → leading=waterfall: remote-only ids are not in spec; drop remote or add spec rows to match.\n`
+        : `    → leading=remote: on reconcile, spec should gain these (e.g. pull).\n`,
+    );
+  }
+  if (diff.mismatches.length) {
+    for (const m of diff.mismatches) {
+      process.stdout.write(
+        `  mismatch ${m.canonicalId} ${m.field}: spec=${JSON.stringify(m.spec)} remote=${JSON.stringify(m.remote)}\n`,
+      );
+      process.stdout.write(formatMismatchLeadingNote(m, lead));
+    }
+  }
+  if (
+    diff.onlyInSpec.length === 0 &&
+    diff.onlyInRemote.length === 0 &&
+    diff.mismatches.length === 0
+  ) {
+    process.stdout.write(
+      `  (no differences in ids / state / title / comments / attachments)\n`,
+    );
+  }
+
+  if (!provider.pullToSpec) {
+    process.stdout.write(
+      `[waterfall] sync ${label} · pull (state/title/attachments remote→spec) not implemented for provider ${provider.providerId}.\n`,
+    );
+  }
+  if (provider.providerId !== "direct" && !provider.pushToRemote) {
+    process.stdout.write(
+      `[waterfall] sync ${label} · push (spec→remote) not implemented for provider ${provider.providerId}.\n`,
+    );
+  }
+
+  if (provider.providerId === "direct") {
+    const outDoc = createMetaDocument(
+      "waterfall-direct-out",
+      kind,
+      specItems,
+      specRoot,
+    );
+    process.stdout.write(`\n`);
+    process.stdout.write(stringifyWorkItemMeta(outDoc));
+  }
+
+}

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

@@ -0,0 +1,226 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  itemCommentsJsonPath,
+  readItemCommentsFile,
+} from "../comments/item-comments";
+import { attachmentCategoryFromMimeOrName } from "./attachment-category";
+import type {
+  WorkItemAttachment,
+  WorkItemComment,
+  WorkItemRecord,
+} from "./work-item-meta";
+
+/** Infer state from folder name and optional markdown **Status:** line. */
+export function inferWorkItemState(
+  folderBase: string,
+  statusLine: string | undefined,
+  kind: "story" | "bug",
+): string {
+  const prefix = kind === "story" ? "_STORY-" : "_BUG-";
+  if (folderBase.startsWith(prefix)) return "closed";
+  const s = statusLine?.trim().toLowerCase();
+  if (s === "closed") return "closed";
+  if (s === "in progress") return "in_progress";
+  if (s === "draft" || s === "open") return s;
+  if (s) return s;
+  return "open";
+}
+
+function readStatusFromMd(mdPath: string): string | undefined {
+  try {
+    const text = fs.readFileSync(mdPath, "utf8");
+    const m = text.match(/^\*\*Status:\*\*\s*(.+)$/im);
+    return m?.[1]?.trim();
+  } catch {
+    return undefined;
+  }
+}
+
+function readTitleFromMd(mdPath: string): string {
+  try {
+    const text = fs.readFileSync(mdPath, "utf8");
+    const m = text.match(/^#\s+([^\n]+)/m);
+    return m?.[1]?.trim() || path.basename(mdPath, ".md");
+  } catch {
+    return path.basename(mdPath, ".md");
+  }
+}
+
+const STORY_DIR = /^(_)?STORY-(\d{3})-/;
+const BUG_DIR = /^(_)?BUG-(\d{3})-/;
+
+function walk(
+  root: string,
+  kind: "story" | "bug",
+  re: RegExp,
+  fileRe: RegExp,
+): WorkItemWalkHit[] {
+  const out: WorkItemWalkHit[] = [];
+  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 (re.test(e.name)) {
+          const md = fs
+            .readdirSync(p)
+            .find((f) => fileRe.test(f));
+          if (md) {
+            out.push({
+              dir: p,
+              folderBase: e.name,
+              mdPath: path.join(p, md),
+              paddedId: e.name.match(/\d{3}/)?.[0] ?? "",
+            });
+          }
+        }
+        if (!e.name.startsWith(".") && e.name !== "node_modules") {
+          stack.push(p);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+type WorkItemWalkHit = {
+  dir: string;
+  folderBase: string;
+  mdPath: string;
+  paddedId: string;
+};
+
+function sysIdFromPath(specRoot: string, dir: string): string | undefined {
+  const rel = path.relative(specRoot, dir).split(path.sep).join("/");
+  const m = rel.match(/SYS-(\d{3})/i);
+  return m ? `SYS-${m[1]}` : undefined;
+}
+
+/**
+ * Other **files** in the STORY|BUG folder (same directory as the canonical `.md`), excluding that markdown.
+ * Not committed as a separate meta file — computed when building the work-item snapshot. Nested subdirs are ignored.
+ */
+export function collectAttachmentsFromItemFolder(
+  specRoot: string,
+  itemDir: string,
+  mdFileName: string,
+): WorkItemAttachment[] {
+  const out: WorkItemAttachment[] = [];
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(itemDir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  const mdLower = mdFileName.toLowerCase();
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    const name = e.name;
+    if (name.startsWith(".")) continue;
+    if (name.toLowerCase() === mdLower) continue;
+    if (/\.sync\.json$/i.test(name)) continue;
+    if (/\.comments\.json$/i.test(name)) continue;
+    const abs = path.join(itemDir, name);
+    let sizeBytes: number | undefined;
+    try {
+      sizeBytes = fs.statSync(abs).size;
+    } catch {
+      /* ignore */
+    }
+    const relFromSpec = path.relative(specRoot, abs).split(path.sep).join("/");
+    out.push({
+      id: relFromSpec,
+      name,
+      category: attachmentCategoryFromMimeOrName(undefined, name),
+      sizeBytes,
+      href: relFromSpec,
+    });
+  }
+  out.sort((a, b) => a.id.localeCompare(b.id, "en"));
+  return out;
+}
+
+/** Map `{CANONICAL}.comments.json` entries into {@link WorkItemComment} for sync/dump-spec. */
+export function waterfallCommentsFileToWorkItemComments(
+  itemDir: string,
+  canonicalId: string,
+): WorkItemComment[] | undefined {
+  const p = itemCommentsJsonPath(itemDir, canonicalId);
+  const file = readItemCommentsFile(p);
+  if (!file?.comments.length) return undefined;
+  const comments: WorkItemComment[] = file.comments.map((c) => ({
+    user: c.from,
+    email: c.email.trim(),
+    createdAt: c.createdAt,
+    body:
+      c.state === "OPEN" ? c.hint : `[${c.state}] ${c.hint}`,
+    externalId: `waterfall:${c.id}`,
+  }));
+  return comments;
+}
+
+export function collectStoriesFromSpec(specRoot: string): WorkItemRecord[] {
+  const technical = path.join(specRoot, "technical");
+  if (!fs.existsSync(technical)) return [];
+  const hits = walk(technical, "story", STORY_DIR, /^STORY-\d{3}\.md$/i);
+  const out: WorkItemRecord[] = [];
+  for (const h of hits) {
+    const id = `STORY-${h.paddedId}`;
+    const statusLine = readStatusFromMd(h.mdPath);
+    const state = inferWorkItemState(h.folderBase, statusLine, "story");
+    const attachments = collectAttachmentsFromItemFolder(
+      specRoot,
+      h.dir,
+      path.basename(h.mdPath),
+    );
+    const comments = waterfallCommentsFileToWorkItemComments(h.dir, id);
+    out.push({
+      canonicalId: id,
+      kind: "story",
+      state,
+      title: readTitleFromMd(h.mdPath),
+      sysId: sysIdFromPath(specRoot, h.dir),
+      relPath: path.relative(specRoot, h.mdPath).split(path.sep).join("/"),
+      ...(comments?.length ? { comments } : {}),
+      ...(attachments.length ? { attachments } : {}),
+    });
+  }
+  return out;
+}
+
+export function collectBugsFromSpec(specRoot: string): WorkItemRecord[] {
+  const technical = path.join(specRoot, "technical");
+  if (!fs.existsSync(technical)) return [];
+  const hits = walk(technical, "bug", BUG_DIR, /^BUG-\d{3}\.md$/i);
+  const out: WorkItemRecord[] = [];
+  for (const h of hits) {
+    const id = `BUG-${h.paddedId}`;
+    const statusLine = readStatusFromMd(h.mdPath);
+    const state = inferWorkItemState(h.folderBase, statusLine, "bug");
+    const attachments = collectAttachmentsFromItemFolder(
+      specRoot,
+      h.dir,
+      path.basename(h.mdPath),
+    );
+    const comments = waterfallCommentsFileToWorkItemComments(h.dir, id);
+    out.push({
+      canonicalId: id,
+      kind: "bug",
+      state,
+      title: readTitleFromMd(h.mdPath),
+      sysId: sysIdFromPath(specRoot, h.dir),
+      relPath: path.relative(specRoot, h.mdPath).split(path.sep).join("/"),
+      ...(comments?.length ? { comments } : {}),
+      ...(attachments.length ? { attachments } : {}),
+    });
+  }
+  return out;
+}

package/lib/cli/sync/sync-hint-json.ts

@@ -0,0 +1,163 @@
+import type {
+  WorkItemAttachment,
+  WorkItemAttachmentCategory,
+  WorkItemComment,
+  WorkItemExternalRef,
+  WorkItemRecord,
+} from "./work-item-meta";
+import { normalizeWorkItemRecord } from "./work-item-meta";
+
+const CATEGORIES = new Set<WorkItemAttachmentCategory>([
+  "pdf",
+  "image",
+  "video",
+  "spreadsheet",
+  "document",
+  "other",
+]);
+
+function fail(msg: string): never {
+  throw new Error(`[waterfall] direct provider: ${msg}`);
+}
+
+function requireString(x: unknown, ctx: string): string {
+  if (typeof x !== "string" || !x.trim()) {
+    fail(`${ctx}: expected non-empty string`);
+  }
+  return x;
+}
+
+function optionalString(x: unknown): string | undefined {
+  if (x === undefined || x === null) return undefined;
+  if (typeof x !== "string") fail(`expected string, got ${typeof x}`);
+  return x;
+}
+
+function validateExternalRefs(x: unknown, ctx: string): WorkItemExternalRef[] | undefined {
+  if (x === undefined || x === null) return undefined;
+  if (!Array.isArray(x)) fail(`${ctx}: externalRefs must be an array`);
+  return x.map((e, j) => {
+    if (!e || typeof e !== "object") fail(`${ctx}[${j}]: object expected`);
+    const o = e as Record<string, unknown>;
+    return {
+      system: requireString(o.system, `${ctx}[${j}].system`),
+      id: requireString(o.id, `${ctx}[${j}].id`),
+      url: optionalString(o.url),
+    };
+  });
+}
+
+function validateComments(x: unknown, ctx: string): WorkItemComment[] | undefined {
+  if (x === undefined || x === null) return undefined;
+  if (!Array.isArray(x)) fail(`${ctx}: comments must be an array`);
+  return x.map((c, j) => {
+    if (!c || typeof c !== "object") fail(`${ctx}[${j}]: object expected`);
+    const o = c as Record<string, unknown>;
+    return {
+      user: requireString(o.user, `${ctx}[${j}].user`),
+      email: requireString(o.email, `${ctx}[${j}].email`),
+      createdAt: requireString(o.createdAt, `${ctx}[${j}].createdAt`),
+      body: requireString(o.body, `${ctx}[${j}].body`),
+      externalId: optionalString(o.externalId),
+    };
+  });
+}
+
+function validateAttachments(x: unknown, ctx: string): WorkItemAttachment[] | undefined {
+  if (x === undefined || x === null) return undefined;
+  if (!Array.isArray(x)) fail(`${ctx}: attachments must be an array`);
+  return x.map((a, j) => {
+    if (!a || typeof a !== "object") fail(`${ctx}[${j}]: object expected`);
+    const o = a as Record<string, unknown>;
+    const category = o.category;
+    if (typeof category !== "string" || !CATEGORIES.has(category as WorkItemAttachmentCategory)) {
+      fail(
+        `${ctx}[${j}].category: expected one of ${[...CATEGORIES].join(", ")}`,
+      );
+    }
+    return {
+      id: requireString(o.id, `${ctx}[${j}].id`),
+      name: requireString(o.name, `${ctx}[${j}].name`),
+      category: category as WorkItemAttachmentCategory,
+      mimeType: optionalString(o.mimeType),
+      sizeBytes:
+        o.sizeBytes === undefined || o.sizeBytes === null
+          ? undefined
+          : typeof o.sizeBytes === "number" && Number.isFinite(o.sizeBytes)
+            ? o.sizeBytes
+            : fail(`${ctx}[${j}].sizeBytes: number expected`),
+      href: optionalString(o.href),
+    };
+  });
+}
+
+function validateWorkItemRecordAt(
+  x: unknown,
+  index: number,
+  expectedKind: "story" | "bug",
+): WorkItemRecord {
+  const ctx = `items[${index}]`;
+  if (!x || typeof x !== "object") fail(`${ctx}: object expected`);
+  const o = x as Record<string, unknown>;
+  const kind = requireString(o.kind, `${ctx}.kind`);
+  if (kind !== expectedKind) {
+    fail(`${ctx}.kind "${kind}" does not match sync kind "${expectedKind}"`);
+  }
+  const rec: WorkItemRecord = {
+    canonicalId: requireString(o.canonicalId, `${ctx}.canonicalId`),
+    kind: expectedKind,
+    state: requireString(o.state, `${ctx}.state`),
+    title: requireString(o.title, `${ctx}.title`),
+    sysId: optionalString(o.sysId),
+    relPath: optionalString(o.relPath),
+    externalRefs: validateExternalRefs(o.externalRefs, `${ctx}.externalRefs`),
+    comments: validateComments(o.comments, `${ctx}.comments`),
+    attachments: validateAttachments(o.attachments, `${ctx}.attachments`),
+    providerPayload:
+      o.providerPayload === undefined || o.providerPayload === null
+        ? undefined
+        : typeof o.providerPayload === "object" && !Array.isArray(o.providerPayload)
+          ? (o.providerPayload as Record<string, unknown>)
+          : fail(`${ctx}.providerPayload: object expected`),
+  };
+  return normalizeWorkItemRecord(rec);
+}
+
+/**
+ * Parse a sync hint string as JSON and validate the work-item meta shape expected by
+ * {@link stringifyWorkItemMeta} / `--dump-spec` (object with `items`, or a top-level array of items).
+ * Document `kind`, when present, must match {@link expectedKind}.
+ */
+export function parseWorkItemRecordsFromSyncHintJson(
+  raw: string,
+  expectedKind: "story" | "bug",
+): WorkItemRecord[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    fail(`hint is not valid JSON: ${(e as Error).message}`);
+  }
+
+  let itemsRaw: unknown;
+  if (Array.isArray(parsed)) {
+    itemsRaw = parsed;
+  } else {
+    if (!parsed || typeof parsed !== "object") {
+      fail("hint JSON must be an object or a top-level array of work items");
+    }
+    const o = parsed as Record<string, unknown>;
+    if (typeof o.kind === "string" && o.kind !== expectedKind) {
+      fail(`document kind "${o.kind}" does not match sync kind "${expectedKind}"`);
+    }
+    itemsRaw = o.items;
+  }
+
+  if (!Array.isArray(itemsRaw)) {
+    fail(
+      "hint must be a top-level array of work items or an object with an `items` array",
+    );
+  }
+
+  return itemsRaw.map((item, i) => validateWorkItemRecordAt(item, i, expectedKind));
+}