@cloverleaf/reference-impl 0.4.1 → 0.5.0

package/lib/cli.ts

@@ -14,15 +14,27 @@
  *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
  *   ui-review-config --repo-root <repoRoot>
  *   plugin-root
+ *   load-rfc <repoRoot> <id>
+ *   save-rfc <repoRoot> <filePath>
+ *   advance-rfc <repoRoot> <id> <toStatus> <agent|human> [gate]
+ *   load-spike <repoRoot> <id>
+ *   save-spike <repoRoot> <filePath>
+ *   advance-spike <repoRoot> <id> <toStatus> <agent|human>
+ *   load-plan <repoRoot> <id>
+ *   save-plan <repoRoot> <filePath>
+ *   advance-plan <repoRoot> <id> <toStatus> <agent|human> [gate]
+ *   materialise-tasks <repoRoot> <planId>
+ *   next-work-item-id <repoRoot> <project>
+ *   discovery-config --repo-root <repoRoot>
  */
 
 import { readFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
-import { loadTask } from './state.js';
-import { advanceStatus } from './state.js';
+import { loadTask } from './task.js';
+import { advanceStatus } from './task.js';
 import { emitGateDecision } from './events.js';
 import { writeFeedback, latestFeedback } from './feedback.js';
-import { nextTaskId, inferProject } from './ids.js';
+import { nextTaskId, inferProject, nextWorkItemId } from './ids.js';
 import { matchesUiPaths } from './ui-paths.js';
 import { loadUiPathsConfig } from './ui-paths.js';
 import { computeAffectedRoutes } from './affected-routes.js';
@@ -30,6 +42,10 @@ import { loadAffectedRoutesConfig } from './affected-routes.js';
 import { loadUiReviewConfig } from './ui-review-config.js';
 import { getPluginRoot } from './plugin-path.js';
 import type { FeedbackEnvelope } from './feedback.js';
+import { loadRfc, saveRfc, advanceRfcStatus, type RfcDoc } from './rfc.js';
+import { loadSpike, saveSpike, advanceSpikeStatus, type SpikeDoc } from './spike.js';
+import { loadPlan, savePlan, advancePlanStatus, materialiseTasksFromPlan, type PlanDoc } from './plan.js';
+import { loadDiscoveryConfig } from './discovery-config.js';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(msg + '\n');
@@ -49,7 +65,19 @@ function usage(msg?: string): never {
       '  latest-feedback <repoRoot> <taskId>\n' +
       '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n' +
       '  ui-review-config --repo-root <repoRoot>\n' +
-      '  plugin-root\n'
+      '  plugin-root\n' +
+      '  load-rfc <repoRoot> <id>\n' +
+      '  save-rfc <repoRoot> <filePath>\n' +
+      '  advance-rfc <repoRoot> <id> <toStatus> <agent|human> [gate]\n' +
+      '  load-spike <repoRoot> <id>\n' +
+      '  save-spike <repoRoot> <filePath>\n' +
+      '  advance-spike <repoRoot> <id> <toStatus> <agent|human>\n' +
+      '  load-plan <repoRoot> <id>\n' +
+      '  save-plan <repoRoot> <filePath>\n' +
+      '  advance-plan <repoRoot> <id> <toStatus> <agent|human> [gate]\n' +
+      '  materialise-tasks <repoRoot> <planId>\n' +
+      '  next-work-item-id <repoRoot> <project>\n' +
+      '  discovery-config --repo-root <repoRoot>\n'
   );
   process.exit(2);
 }
@@ -252,6 +280,101 @@ try {
       process.exit(0);
     }
 
+    case 'load-rfc': {
+      const [repoRoot, id] = rest;
+      if (!repoRoot || !id) usage('load-rfc <repoRoot> <id>');
+      process.stdout.write(JSON.stringify(loadRfc(repoRoot, id), null, 2));
+      break;
+    }
+
+    case 'save-rfc': {
+      const [repoRoot, filePath] = rest;
+      if (!repoRoot || !filePath) usage('save-rfc <repoRoot> <filePath>');
+      const rfc = JSON.parse(readFileSync(filePath, 'utf-8')) as RfcDoc;
+      saveRfc(repoRoot, rfc);
+      break;
+    }
+
+    case 'advance-rfc': {
+      const [repoRoot, id, toStatus, actor, gate] = rest;
+      if (!repoRoot || !id || !toStatus || !actor) usage('advance-rfc <repoRoot> <id> <toStatus> <agent|human> [gate]');
+      if (actor !== 'agent' && actor !== 'human') usage('advance-rfc: actor must be agent or human');
+      const opts = gate ? { gate } : {};
+      advanceRfcStatus(repoRoot, id, toStatus, actor as 'agent' | 'human', opts);
+      break;
+    }
+
+    case 'load-spike': {
+      const [repoRoot, id] = rest;
+      if (!repoRoot || !id) usage('load-spike <repoRoot> <id>');
+      process.stdout.write(JSON.stringify(loadSpike(repoRoot, id), null, 2));
+      break;
+    }
+
+    case 'save-spike': {
+      const [repoRoot, filePath] = rest;
+      if (!repoRoot || !filePath) usage('save-spike <repoRoot> <filePath>');
+      const spike = JSON.parse(readFileSync(filePath, 'utf-8')) as SpikeDoc;
+      saveSpike(repoRoot, spike);
+      break;
+    }
+
+    case 'advance-spike': {
+      const [repoRoot, id, toStatus, actor] = rest;
+      if (!repoRoot || !id || !toStatus || !actor) usage('advance-spike <repoRoot> <id> <toStatus> <agent|human>');
+      if (actor !== 'agent' && actor !== 'human') usage('advance-spike: actor must be agent or human');
+      advanceSpikeStatus(repoRoot, id, toStatus, actor as 'agent' | 'human');
+      break;
+    }
+
+    case 'load-plan': {
+      const [repoRoot, id] = rest;
+      if (!repoRoot || !id) usage('load-plan <repoRoot> <id>');
+      process.stdout.write(JSON.stringify(loadPlan(repoRoot, id), null, 2));
+      break;
+    }
+
+    case 'save-plan': {
+      const [repoRoot, filePath] = rest;
+      if (!repoRoot || !filePath) usage('save-plan <repoRoot> <filePath>');
+      const plan = JSON.parse(readFileSync(filePath, 'utf-8')) as PlanDoc;
+      savePlan(repoRoot, plan);
+      break;
+    }
+
+    case 'advance-plan': {
+      const [repoRoot, id, toStatus, actor, gate] = rest;
+      if (!repoRoot || !id || !toStatus || !actor) usage('advance-plan <repoRoot> <id> <toStatus> <agent|human> [gate]');
+      if (actor !== 'agent' && actor !== 'human') usage('advance-plan: actor must be agent or human');
+      const opts = gate ? { gate } : {};
+      advancePlanStatus(repoRoot, id, toStatus, actor as 'agent' | 'human', opts);
+      break;
+    }
+
+    case 'materialise-tasks': {
+      const [repoRoot, planId] = rest;
+      if (!repoRoot || !planId) usage('materialise-tasks <repoRoot> <planId>');
+      const plan = loadPlan(repoRoot, planId);
+      const ids = materialiseTasksFromPlan(repoRoot, plan);
+      process.stdout.write(JSON.stringify({ task_ids: ids }));
+      break;
+    }
+
+    case 'next-work-item-id': {
+      const [repoRoot, project] = rest;
+      if (!repoRoot || !project) usage('next-work-item-id <repoRoot> <project>');
+      process.stdout.write(nextWorkItemId(repoRoot, project));
+      break;
+    }
+
+    case 'discovery-config': {
+      const idx = rest.indexOf('--repo-root');
+      if (idx < 0 || !rest[idx + 1]) usage('discovery-config --repo-root <repoRoot>');
+      const c = loadDiscoveryConfig(rest[idx + 1]);
+      process.stdout.write(JSON.stringify(c, null, 2));
+      break;
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/lib/discovery-config.ts

@@ -0,0 +1,35 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DEFAULT = join(here, '..', 'config', 'discovery.json');
+
+export interface DiscoveryConfig {
+  docContextUri: string;
+  projectId: string;
+  idStart: number;
+}
+
+export function loadDiscoveryConfig(repoRoot: string): DiscoveryConfig {
+  const override = join(repoRoot, '.cloverleaf', 'config', 'discovery.json');
+  const fallback = JSON.parse(readFileSync(PACKAGE_DEFAULT, 'utf-8')) as DiscoveryConfig;
+
+  if (existsSync(override)) {
+    try {
+      const doc = JSON.parse(readFileSync(override, 'utf-8')) as Partial<DiscoveryConfig>;
+      return normalise(doc, fallback);
+    } catch {
+      // Malformed consumer JSON — fall through to package default.
+    }
+  }
+  return fallback;
+}
+
+function normalise(doc: Partial<DiscoveryConfig>, fallback: DiscoveryConfig): DiscoveryConfig {
+  return {
+    docContextUri: typeof doc.docContextUri === 'string' ? doc.docContextUri : fallback.docContextUri,
+    projectId:     typeof doc.projectId     === 'string' ? doc.projectId     : fallback.projectId,
+    idStart:       typeof doc.idStart       === 'number' ? doc.idStart       : fallback.idStart,
+  };
+}

package/lib/ids.ts

@@ -1,5 +1,5 @@
 import { readdirSync, existsSync } from 'node:fs';
-import { tasksDir, eventsDir, feedbackDir, projectsDir } from './paths.js';
+import { tasksDir, eventsDir, feedbackDir, projectsDir, rfcsDir, spikesDir, plansDir } from './paths.js';
 
 export function nextTaskId(repoRoot: string, project: string): string {
   const dir = tasksDir(repoRoot);
@@ -55,6 +55,30 @@ export function inferProject(repoRoot: string, explicit?: string): string {
   return projects[0];
 }
 
+/**
+ * Returns unpadded per-project IDs (e.g., `CLV-13`) by scanning all four
+ * work-item directories and taking max+1. Matches the canonical convention
+ * used in @cloverleaf/standard example scenarios (oauth-rollout: ACME-100,
+ * ACME-200). Legacy `nextTaskId` retains three-digit padding (e.g., CLV-001)
+ * for back-compat with existing task files.
+ */
+export function nextWorkItemId(repoRoot: string, project: string): string {
+  const dirs = [rfcsDir(repoRoot), spikesDir(repoRoot), plansDir(repoRoot), tasksDir(repoRoot)];
+  const pat = new RegExp(`^${escapeRegex(project)}-(\\d+)\\.json$`);
+  let max = 0;
+  for (const d of dirs) {
+    if (!existsSync(d)) continue;
+    for (const f of readdirSync(d)) {
+      const m = pat.exec(f);
+      if (m) {
+        const n = parseInt(m[1], 10);
+        if (n > max) max = n;
+      }
+    }
+  }
+  return `${project}-${max + 1}`;
+}
+
 function escapeRegex(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/lib/index.ts

@@ -1,6 +1,6 @@
 export * from './paths.js';
 export * from './ids.js';
-export * from './state.js';
+export * from './task.js';
 export * from './events.js';
 export * from './feedback.js';
 export * from './validate.js';

package/lib/plan.ts

@@ -0,0 +1,147 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { plansDir, tasksDir } from './paths.js';
+import { validateOrThrow } from './validate.js';
+import { advanceWorkItemStatus, loadStateMachine } from './work-item.js';
+
+export interface WorkItemRef {
+  project: string;
+  id: string;
+}
+
+export interface TaskDag {
+  nodes: WorkItemRef[];
+  edges: Array<{ from: WorkItemRef; to: WorkItemRef }>;
+}
+
+export interface PlanDoc {
+  type: 'plan';
+  project: string;
+  id: string;
+  status: string;
+  owner: { kind: 'agent' | 'human' | 'system'; id: string };
+  parent_rfc: WorkItemRef;
+  task_dag: TaskDag;
+  tasks: Array<Record<string, unknown>>;
+  path_reviewer_map?: Array<{ pattern: string; role: string }>;
+  [key: string]: unknown;
+}
+
+export function loadPlan(repoRoot: string, id: string): PlanDoc {
+  const path = join(plansDir(repoRoot), `${id}.json`);
+  if (!existsSync(path)) throw new Error(`Plan ${id} not found at ${path}`);
+  return JSON.parse(readFileSync(path, 'utf-8')) as PlanDoc;
+}
+
+export function savePlan(repoRoot: string, plan: PlanDoc): void {
+  validateOrThrow('https://cloverleaf.example/schemas/plan.schema.json', plan);
+  const path = join(plansDir(repoRoot), `${plan.id}.json`);
+  writeFileSync(path, JSON.stringify(plan, null, 2) + '\n');
+}
+
+export function advancePlanStatus(
+  repoRoot: string,
+  id: string,
+  toStatus: string,
+  actor: 'agent' | 'human',
+  options: { gate?: string } = {}
+): PlanDoc {
+  const plan = loadPlan(repoRoot, id);
+  const from = plan.status;
+  const sm = loadStateMachine('plan');
+  const fixture = { type: 'plan', id: plan.id, project: plan.project, status: plan.status };
+
+  const proposed = { ...plan, status: toStatus };
+  advanceWorkItemStatus({
+    repoRoot,
+    workItemType: 'plan',
+    project: plan.project,
+    id: plan.id,
+    from,
+    to: toStatus,
+    actor,
+    stateMachine: sm,
+    validateFixture: fixture,
+    save: (p) => savePlan(repoRoot, p as PlanDoc),
+    proposed,
+    gate: options.gate,
+  });
+  return proposed;
+}
+
+/**
+ * Build a directed graph from the DAG's edges and detect any cycle.
+ * Returns the first node id involved in a cycle, or null.
+ */
+function detectCycle(dag: TaskDag): string | null {
+  // Build adjacency: for each node, list of node ids it points TO.
+  const adj = new Map<string, string[]>();
+  for (const n of dag.nodes) adj.set(n.id, []);
+  for (const e of dag.edges) {
+    const from = e.from.id;
+    const to = e.to.id;
+    if (!adj.has(from)) adj.set(from, []);
+    adj.get(from)!.push(to);
+  }
+
+  const state = new Map<string, 'white' | 'grey' | 'black'>();
+  for (const n of dag.nodes) state.set(n.id, 'white');
+
+  const visit = (id: string): boolean => {
+    const s = state.get(id);
+    if (s === 'grey') return true; // back-edge → cycle
+    if (s === 'black') return false;
+    state.set(id, 'grey');
+    for (const next of adj.get(id) ?? []) {
+      if (visit(next)) return true;
+    }
+    state.set(id, 'black');
+    return false;
+  };
+
+  for (const n of dag.nodes) {
+    if (visit(n.id)) return n.id;
+  }
+  return null;
+}
+
+/**
+ * Materialise all inline tasks from an approved Plan onto disk as
+ * .cloverleaf/tasks/<id>.json. Atomic: pre-validates every task before
+ * any file write. Throws on cycle in task_dag or AJV failure — no
+ * partial materialisation on failure. Returns the ordered list of
+ * materialised task IDs.
+ *
+ * If a task file already exists at the target path, it is OVERWRITTEN.
+ * Callers responsible for Delivery state consistency should not invoke
+ * this on a Plan whose tasks are already materialised and in-flight.
+ *
+ * Called by /cloverleaf-discover after a human approves the Plan at
+ * task_batch_gate. The gate ensures this function is invoked at most
+ * once per Plan in normal operation.
+ */
+export function materialiseTasksFromPlan(repoRoot: string, plan: PlanDoc): string[] {
+  // 1. Cycle check on edges.
+  const cycleAt = detectCycle(plan.task_dag);
+  if (cycleAt) throw new Error(`Plan task_dag contains a cycle involving ${cycleAt}`);
+
+  // 2. Pre-validate every task before ANY file write.
+  for (const task of plan.tasks) {
+    validateOrThrow('https://cloverleaf.example/schemas/task.schema.json', task);
+  }
+
+  // 3. Ensure the tasks directory exists (no-op on fresh repos that haven't
+  //    initialised .cloverleaf/tasks/ yet). Placed after cycle-check and
+  //    validation so those fast-path shorts-circuit without any FS side-effect.
+  mkdirSync(tasksDir(repoRoot), { recursive: true });
+
+  // 4. Write all task files.
+  const ids: string[] = [];
+  for (const task of plan.tasks) {
+    const id = String(task['id']);
+    const path = join(tasksDir(repoRoot), `${id}.json`);
+    writeFileSync(path, JSON.stringify(task, null, 2) + '\n');
+    ids.push(id);
+  }
+  return ids;
+}

package/lib/rfc.ts

@@ -0,0 +1,62 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { rfcsDir } from './paths.js';
+import { validateOrThrow } from './validate.js';
+import { advanceWorkItemStatus, loadStateMachine } from './work-item.js';
+
+export interface RfcDoc {
+  type: 'rfc';
+  project: string;
+  id: string;
+  title: string;
+  status: string;
+  owner: { kind: 'agent' | 'human' | 'system'; id: string };
+  problem: string;
+  solution: string;
+  unknowns: string[];
+  acceptance_criteria: string[];
+  out_of_scope: string[];
+  [key: string]: unknown;
+}
+
+export function loadRfc(repoRoot: string, id: string): RfcDoc {
+  const path = join(rfcsDir(repoRoot), `${id}.json`);
+  if (!existsSync(path)) throw new Error(`RFC ${id} not found at ${path}`);
+  return JSON.parse(readFileSync(path, 'utf-8')) as RfcDoc;
+}
+
+export function saveRfc(repoRoot: string, rfc: RfcDoc): void {
+  validateOrThrow('https://cloverleaf.example/schemas/rfc.schema.json', rfc);
+  const path = join(rfcsDir(repoRoot), `${rfc.id}.json`);
+  writeFileSync(path, JSON.stringify(rfc, null, 2) + '\n');
+}
+
+export function advanceRfcStatus(
+  repoRoot: string,
+  id: string,
+  toStatus: string,
+  actor: 'agent' | 'human',
+  options: { gate?: string } = {}
+): RfcDoc {
+  const rfc = loadRfc(repoRoot, id);
+  const from = rfc.status;
+  const sm = loadStateMachine('rfc');
+  const fixture = { type: 'rfc', id: rfc.id, project: rfc.project, status: rfc.status };
+
+  const proposed = { ...rfc, status: toStatus };
+  advanceWorkItemStatus({
+    repoRoot,
+    workItemType: 'rfc',
+    project: rfc.project,
+    id: rfc.id,
+    from,
+    to: toStatus,
+    actor,
+    stateMachine: sm,
+    validateFixture: fixture,
+    save: (p) => saveRfc(repoRoot, p as RfcDoc),
+    proposed,
+    gate: options.gate,
+  });
+  return proposed;
+}

package/lib/spike.ts

@@ -0,0 +1,60 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spikesDir } from './paths.js';
+import { validateOrThrow } from './validate.js';
+import { advanceWorkItemStatus, loadStateMachine } from './work-item.js';
+
+export interface SpikeDoc {
+  type: 'spike';
+  project: string;
+  id: string;
+  title: string;
+  status: string;
+  owner: { kind: 'agent' | 'human' | 'system'; id: string };
+  parent_rfc: { project: string; id: string };
+  question: string;
+  method: 'research' | 'prototype' | 'benchmark';
+  findings?: string;
+  recommendation?: string;
+  [key: string]: unknown;
+}
+
+export function loadSpike(repoRoot: string, id: string): SpikeDoc {
+  const path = join(spikesDir(repoRoot), `${id}.json`);
+  if (!existsSync(path)) throw new Error(`Spike ${id} not found at ${path}`);
+  return JSON.parse(readFileSync(path, 'utf-8')) as SpikeDoc;
+}
+
+export function saveSpike(repoRoot: string, spike: SpikeDoc): void {
+  validateOrThrow('https://cloverleaf.example/schemas/spike.schema.json', spike);
+  const path = join(spikesDir(repoRoot), `${spike.id}.json`);
+  writeFileSync(path, JSON.stringify(spike, null, 2) + '\n');
+}
+
+export function advanceSpikeStatus(
+  repoRoot: string,
+  id: string,
+  toStatus: string,
+  actor: 'agent' | 'human'
+): SpikeDoc {
+  const spike = loadSpike(repoRoot, id);
+  const from = spike.status;
+  const sm = loadStateMachine('spike');
+  const fixture = { type: 'spike', id: spike.id, project: spike.project, status: spike.status };
+
+  const proposed = { ...spike, status: toStatus };
+  advanceWorkItemStatus({
+    repoRoot,
+    workItemType: 'spike',
+    project: spike.project,
+    id: spike.id,
+    from,
+    to: toStatus,
+    actor,
+    stateMachine: sm,
+    validateFixture: fixture,
+    save: (p) => saveSpike(repoRoot, p as SpikeDoc),
+    proposed,
+  });
+  return proposed;
+}

package/lib/task.ts

@@ -0,0 +1,90 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tasksDir, projectsDir } from './paths.js';
+import type { Task as SMTask } from '@cloverleaf/standard/validators/index.js';
+import { validateOrThrow } from './validate.js';
+import { advanceWorkItemStatus, loadStateMachine } from './work-item.js';
+
+export interface TaskDoc {
+  type: 'task';
+  project: string;
+  id: string;
+  title: string;
+  status: string;
+  risk_class: 'low' | 'high';
+  owner: { kind: 'agent' | 'human' | 'system'; id: string };
+  acceptance_criteria: string[];
+  definition_of_done: string[];
+  context: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ProjectDoc {
+  key: string;
+  name: string;
+  [key: string]: unknown;
+}
+
+export function loadTask(repoRoot: string, taskId: string): TaskDoc {
+  const path = join(tasksDir(repoRoot), `${taskId}.json`);
+  if (!existsSync(path)) throw new Error(`Task ${taskId} not found at ${path}`);
+  return JSON.parse(readFileSync(path, 'utf-8')) as TaskDoc;
+}
+
+export function saveTask(repoRoot: string, task: TaskDoc): void {
+  validateOrThrow('https://cloverleaf.example/schemas/task.schema.json', task);
+  const path = join(tasksDir(repoRoot), `${task.id}.json`);
+  writeFileSync(path, JSON.stringify(task, null, 2) + '\n');
+}
+
+export function loadProject(repoRoot: string, projectId: string): ProjectDoc {
+  const path = join(projectsDir(repoRoot), `${projectId}.json`);
+  if (!existsSync(path)) throw new Error(`Project ${projectId} not found at ${path}`);
+  return JSON.parse(readFileSync(path, 'utf-8')) as ProjectDoc;
+}
+
+export function advanceStatus(
+  repoRoot: string,
+  taskId: string,
+  toStatus: string,
+  actor: 'agent' | 'human',
+  options: { gate?: string; path?: 'fast_lane' | 'full_pipeline' } = {}
+): TaskDoc {
+  const task = loadTask(repoRoot, taskId);
+  const from = task.status;
+  const sm = loadStateMachine('task');
+
+  const riskClass: 'low' | 'high' =
+    options.path === 'fast_lane' ? 'low'
+    : options.path === 'full_pipeline' ? 'high'
+    : (task.risk_class ?? 'low');
+
+  const workItemForValidator: SMTask = {
+    type: 'task',
+    id: task.id,
+    project: task.project,
+    status: task.status,
+    risk_class: riskClass,
+    context: { rfc: { project: task.project, id: task.id } },
+    definition_of_done: task.definition_of_done,
+    acceptance_criteria: task.acceptance_criteria,
+  };
+
+  const proposed = { ...task, status: toStatus };
+  advanceWorkItemStatus({
+    repoRoot,
+    workItemType: 'task',
+    project: task.project,
+    id: task.id,
+    from,
+    to: toStatus,
+    actor,
+    stateMachine: sm,
+    validateFixture: workItemForValidator as unknown as Record<string, unknown>,
+    save: (p) => saveTask(repoRoot, p as TaskDoc),
+    proposed,
+    gate: options.gate,
+    path: options.path,
+  });
+  return proposed;
+}

package/lib/work-item.ts

@@ -0,0 +1,78 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { emitStatusTransition, formatReason } from './events.js';
+import { validateStatusTransitionLegality } from '@cloverleaf/standard/validators/index.js';
+import type { StatusTransitions } from '@cloverleaf/standard/validators/index.js';
+
+const req = createRequire(import.meta.url);
+
+export function loadStateMachine(type: 'task' | 'rfc' | 'spike' | 'plan'): StatusTransitions {
+  const pkgPath = req.resolve('@cloverleaf/standard/package.json');
+  const pkgDir = pkgPath.replace(/\/package\.json$/, '');
+  return JSON.parse(readFileSync(`${pkgDir}/state-machines/${type}.json`, 'utf-8')) as StatusTransitions;
+}
+
+export interface AdvanceWorkItemParams<T> {
+  repoRoot: string;
+  workItemType: 'task' | 'rfc' | 'spike' | 'plan';
+  project: string;
+  id: string;
+  from: string;
+  to: string;
+  actor: 'agent' | 'human';
+  stateMachine: StatusTransitions;
+  validateFixture: Record<string, unknown>;
+  save: (proposed: T & { status: string }) => void;
+  proposed: T;
+  gate?: string;
+  path?: 'fast_lane' | 'full_pipeline';
+}
+
+export interface AdvanceWorkItemResult {
+  from: string;
+  to: string;
+}
+
+export function advanceWorkItemStatus<T>(params: AdvanceWorkItemParams<T>): AdvanceWorkItemResult {
+  const { repoRoot, workItemType, project, id, from, to, actor, stateMachine, validateFixture, save, gate, path } = params;
+
+  const reason = formatReason({ gate, path });
+  const event = {
+    event_id: randomUUID(),
+    event_type: 'status_transition' as const,
+    occurred_at: new Date().toISOString(),
+    work_item_id: { project, id },
+    work_item_type: workItemType,
+    from_status: from,
+    to_status: to,
+    actor: { kind: actor, id: actor },
+    ...(reason ? { reason } : {}),
+  };
+
+  const result = validateStatusTransitionLegality(event, stateMachine, validateFixture as never);
+  if (!result.ok) {
+    const msgs = result.violations.map((v) => v.message).join('; ');
+    throw new Error(`Illegal transition ${from} → ${to}: ${msgs}`);
+  }
+
+  const emittedPath = emitStatusTransition(repoRoot, {
+    project,
+    workItemType,
+    workItemId: id,
+    from,
+    to,
+    actor,
+    gate,
+    path,
+  });
+
+  try {
+    save(params.proposed as T & { status: string });
+  } catch (err) {
+    const inner = err instanceof Error ? err.message : String(err);
+    throw new Error(`orphan event written to ${emittedPath} but ${workItemType} save failed: ${inner}`);
+  }
+
+  return { from, to };
+}