@cloverleaf/reference-impl 0.4.0 → 0.5.0

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.0",
+  "version": "0.5.0",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

package/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.1

package/config/discovery.json

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

package/config/ui-review.json

@@ -12,6 +12,7 @@
   },
   "axe": {
     "viewports": ["desktop"],
-    "dedupeBy": ["ruleId", "target"]
+    "dedupeBy": ["ruleId", "target"],
+    "ignored": []
   }
 }

package/dist/axe-dedupe.mjs

@@ -7,9 +7,13 @@ const SEVERITY_MAP = {
 function dedupeKeyOf(raw, keys) {
     return keys.map((k) => raw[k]).join('||');
 }
-export function dedupeAxeFindings(raws, keys) {
+export function dedupeAxeFindings(raws, keys, ignored = []) {
+    // Filter out ignored (ruleId, target) tuples BEFORE grouping.
+    const filtered = raws.filter((raw) => {
+        return !ignored.some((i) => i.ruleId === raw.ruleId && i.target === raw.target);
+    });
     const groups = new Map();
-    for (const raw of raws) {
+    for (const raw of filtered) {
         const key = dedupeKeyOf(raw, keys);
         const existing = groups.get(key);
         if (existing) {

package/dist/cli.mjs

@@ -13,19 +13,37 @@
  *   latest-feedback <repoRoot> <taskId>
  *   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);
@@ -42,7 +60,20 @@ function usage(msg) {
         '  write-feedback <repoRoot> <taskId> <envelopeJsonPath>\n' +
         '  latest-feedback <repoRoot> <taskId>\n' +
         '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n' +
-        '  ui-review-config --repo-root <repoRoot>\n');
+        '  ui-review-config --repo-root <repoRoot>\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;
@@ -235,6 +266,108 @@ try {
             process.stdout.write(JSON.stringify(config, null, 2));
             process.exit(0);
         }
+        case 'plugin-root': {
+            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/feedback.mjs

@@ -29,7 +29,7 @@ export function allFeedback(repoRoot, taskId) {
     const dir = feedbackDir(repoRoot);
     if (!existsSync(dir))
         return [];
-    const re = new RegExp(`^${escapeRegex(taskId)}-r(\\d+)\\.json$`);
+    const re = new RegExp(`^${escapeRegex(taskId)}-[ruq](\\d+)\\.json$`);
     const entries = readdirSync(dir)
         .map((f) => ({ f, m: f.match(re) }))
         .filter((x) => !!x.m)

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,115 @@
+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);
+    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/plugin-path.mjs

@@ -0,0 +1,19 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+const here = dirname(fileURLToPath(import.meta.url));
+/**
+ * Absolute path to the plugin root.
+ *
+ * At runtime, this module lives at <plugin-root>/lib/plugin-path.js (or .ts in dev),
+ * so the plugin root is the parent directory.
+ *
+ * Works under:
+ * - dev mode (repo source: <repo>/reference-impl/)
+ * - npm install (node_modules/@cloverleaf/reference-impl/)
+ * - claude plugin install cache (~/.claude/plugins/cache/cloverleaf-local/cloverleaf/0.4.1/)
+ * - legacy symlink into ~/.claude/plugins/cloverleaf/
+ * - claude --plugin-dir <path>
+ */
+export function getPluginRoot() {
+    return resolve(here, '..');
+}

package/dist/rfc.mjs

@@ -0,0 +1,38 @@
+import { readFileSync, writeFileSync, existsSync } 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);
+    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,37 @@
+import { readFileSync, writeFileSync, existsSync } 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);
+    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,57 @@
+import { readFileSync, writeFileSync, existsSync } 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);
+    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/ui-review-config.mjs

@@ -10,11 +10,15 @@ const HARDCODED_FALLBACK = {
         desktop: { width: 1280, height: 800 },
     },
     visualDiff: { enabled: true, threshold: 0.1, maxDiffRatio: 0.01, mask: [] },
-    axe: { viewports: ['desktop'], dedupeBy: ['ruleId', 'target'] },
+    axe: { viewports: ['desktop'], dedupeBy: ['ruleId', 'target'], ignored: [] },
 };
 function readAsConfig(path) {
     try {
         const doc = JSON.parse(readFileSync(path, 'utf-8'));
+        // Back-compat: if ignored is missing from an older override, default it.
+        if (doc.axe && !('ignored' in doc.axe)) {
+            doc.axe.ignored = [];
+        }
         return doc;
     }
     catch {

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 };
+}

package/lib/axe-dedupe.ts

@@ -24,9 +24,20 @@ function dedupeKeyOf(raw: RawAxeFinding, keys: DedupeKey[]): string {
   return keys.map((k) => raw[k]).join('||');
 }
 
-export function dedupeAxeFindings(raws: RawAxeFinding[], keys: DedupeKey[]): Finding[] {
+export function dedupeAxeFindings(
+  raws: RawAxeFinding[],
+  keys: DedupeKey[],
+  ignored: Array<{ ruleId: string; target: string }> = []
+): Finding[] {
+  // Filter out ignored (ruleId, target) tuples BEFORE grouping.
+  const filtered = raws.filter((raw) => {
+    return !ignored.some(
+      (i) => i.ruleId === raw.ruleId && i.target === raw.target
+    );
+  });
+
   const groups = new Map<string, { first: RawAxeFinding; viewports: string[] }>();
-  for (const raw of raws) {
+  for (const raw of filtered) {
     const key = dedupeKeyOf(raw, keys);
     const existing = groups.get(key);
     if (existing) {