@cloverleaf/reference-impl 0.4.1 → 0.5.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cloverleaf",
   "description": "Cloverleaf reference implementation — Claude Code skills for task scaffolding and the Delivery pipeline (implementer, documenter, reviewer, UI reviewer with multi-viewport visual diff, QA, merge).",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

package/VERSION

@@ -1 +1 @@
-0.4.1
+0.5.1

package/config/discovery.json

@@ -0,0 +1,5 @@
+{
+  "docContextUri": "",
+  "projectId": "",
+  "idStart": 1
+}

package/dist/cli.mjs

@@ -14,20 +14,36 @@
  *   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.mjs';
-import { advanceStatus } from './state.mjs';
+import { loadTask } from './task.mjs';
+import { advanceStatus } from './task.mjs';
 import { emitGateDecision } from './events.mjs';
 import { writeFeedback, latestFeedback } from './feedback.mjs';
-import { nextTaskId, inferProject } from './ids.mjs';
+import { nextTaskId, inferProject, nextWorkItemId } from './ids.mjs';
 import { matchesUiPaths } from './ui-paths.mjs';
 import { loadUiPathsConfig } from './ui-paths.mjs';
 import { computeAffectedRoutes } from './affected-routes.mjs';
 import { loadAffectedRoutesConfig } from './affected-routes.mjs';
 import { loadUiReviewConfig } from './ui-review-config.mjs';
 import { getPluginRoot } from './plugin-path.mjs';
+import { loadRfc, saveRfc, advanceRfcStatus } from './rfc.mjs';
+import { loadSpike, saveSpike, advanceSpikeStatus } from './spike.mjs';
+import { loadPlan, savePlan, advancePlanStatus, materialiseTasksFromPlan } from './plan.mjs';
+import { loadDiscoveryConfig } from './discovery-config.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -45,7 +61,19 @@ function usage(msg) {
         '  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);
 }
 const [, , command, ...rest] = process.argv;
@@ -242,6 +270,104 @@ try {
             process.stdout.write(getPluginRoot());
             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'));
+            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, 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'));
+            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);
+            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'));
+            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, 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/dist/discovery-config.mjs

@@ -0,0 +1,26 @@
+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 function loadDiscoveryConfig(repoRoot) {
+    const override = join(repoRoot, '.cloverleaf', 'config', 'discovery.json');
+    const fallback = JSON.parse(readFileSync(PACKAGE_DEFAULT, 'utf-8'));
+    if (existsSync(override)) {
+        try {
+            const doc = JSON.parse(readFileSync(override, 'utf-8'));
+            return normalise(doc, fallback);
+        }
+        catch {
+            // Malformed consumer JSON — fall through to package default.
+        }
+    }
+    return fallback;
+}
+function normalise(doc, fallback) {
+    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/dist/ids.mjs

@@ -1,5 +1,5 @@
 import { readdirSync, existsSync } from 'node:fs';
-import { tasksDir, eventsDir, feedbackDir, projectsDir } from './paths.mjs';
+import { tasksDir, eventsDir, feedbackDir, projectsDir, rfcsDir, spikesDir, plansDir } from './paths.mjs';
 export function nextTaskId(repoRoot, project) {
     const dir = tasksDir(repoRoot);
     if (!existsSync(dir))
@@ -55,6 +55,31 @@ export function inferProject(repoRoot, explicit) {
     }
     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, project) {
+    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) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/dist/index.mjs

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

package/dist/plan.mjs

@@ -0,0 +1,116 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { plansDir, tasksDir } from './paths.mjs';
+import { validateOrThrow } from './validate.mjs';
+import { advanceWorkItemStatus, loadStateMachine } from './work-item.mjs';
+export function loadPlan(repoRoot, id) {
+    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'));
+}
+export function savePlan(repoRoot, plan) {
+    validateOrThrow('https://cloverleaf.example/schemas/plan.schema.json', plan);
+    mkdirSync(plansDir(repoRoot), { recursive: true });
+    const path = join(plansDir(repoRoot), `${plan.id}.json`);
+    writeFileSync(path, JSON.stringify(plan, null, 2) + '\n');
+}
+export function advancePlanStatus(repoRoot, id, toStatus, actor, options = {}) {
+    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),
+        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) {
+    // Build adjacency: for each node, list of node ids it points TO.
+    const adj = new Map();
+    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();
+    for (const n of dag.nodes)
+        state.set(n.id, 'white');
+    const visit = (id) => {
+        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, plan) {
+    // 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 = [];
+    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/dist/rfc.mjs

@@ -0,0 +1,39 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { rfcsDir } from './paths.mjs';
+import { validateOrThrow } from './validate.mjs';
+import { advanceWorkItemStatus, loadStateMachine } from './work-item.mjs';
+export function loadRfc(repoRoot, id) {
+    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'));
+}
+export function saveRfc(repoRoot, rfc) {
+    validateOrThrow('https://cloverleaf.example/schemas/rfc.schema.json', rfc);
+    mkdirSync(rfcsDir(repoRoot), { recursive: true });
+    const path = join(rfcsDir(repoRoot), `${rfc.id}.json`);
+    writeFileSync(path, JSON.stringify(rfc, null, 2) + '\n');
+}
+export function advanceRfcStatus(repoRoot, id, toStatus, actor, options = {}) {
+    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),
+        proposed,
+        gate: options.gate,
+    });
+    return proposed;
+}

package/dist/spike.mjs

@@ -0,0 +1,38 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { spikesDir } from './paths.mjs';
+import { validateOrThrow } from './validate.mjs';
+import { advanceWorkItemStatus, loadStateMachine } from './work-item.mjs';
+export function loadSpike(repoRoot, id) {
+    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'));
+}
+export function saveSpike(repoRoot, spike) {
+    validateOrThrow('https://cloverleaf.example/schemas/spike.schema.json', spike);
+    mkdirSync(spikesDir(repoRoot), { recursive: true });
+    const path = join(spikesDir(repoRoot), `${spike.id}.json`);
+    writeFileSync(path, JSON.stringify(spike, null, 2) + '\n');
+}
+export function advanceSpikeStatus(repoRoot, id, toStatus, actor) {
+    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),
+        proposed,
+    });
+    return proposed;
+}

package/dist/task.mjs

@@ -0,0 +1,58 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tasksDir, projectsDir } from './paths.mjs';
+import { validateOrThrow } from './validate.mjs';
+import { advanceWorkItemStatus, loadStateMachine } from './work-item.mjs';
+export function loadTask(repoRoot, taskId) {
+    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'));
+}
+export function saveTask(repoRoot, task) {
+    validateOrThrow('https://cloverleaf.example/schemas/task.schema.json', task);
+    mkdirSync(tasksDir(repoRoot), { recursive: true });
+    const path = join(tasksDir(repoRoot), `${task.id}.json`);
+    writeFileSync(path, JSON.stringify(task, null, 2) + '\n');
+}
+export function loadProject(repoRoot, projectId) {
+    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'));
+}
+export function advanceStatus(repoRoot, taskId, toStatus, actor, options = {}) {
+    const task = loadTask(repoRoot, taskId);
+    const from = task.status;
+    const sm = loadStateMachine('task');
+    const riskClass = options.path === 'fast_lane' ? 'low'
+        : options.path === 'full_pipeline' ? 'high'
+            : (task.risk_class ?? 'low');
+    const workItemForValidator = {
+        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,
+        save: (p) => saveTask(repoRoot, p),
+        proposed,
+        gate: options.gate,
+        path: options.path,
+    });
+    return proposed;
+}

package/dist/work-item.mjs

@@ -0,0 +1,49 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { emitStatusTransition, formatReason } from './events.mjs';
+import { validateStatusTransitionLegality } from '@cloverleaf/standard/validators/index.js';
+const req = createRequire(import.meta.url);
+export function loadStateMachine(type) {
+    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'));
+}
+export function advanceWorkItemStatus(params) {
+    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',
+        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);
+    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);
+    }
+    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 };
+}