@cloverleaf/reference-impl 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @cloverleaf/reference-impl
 
-Reference implementation of the Cloverleaf methodology as a set of Claude Code skills. This package implements the **Tight Loop** — Implementer + Reviewer — letting a user drive a Task from `pending` to `merged` with state, events, and feedback recorded in the repo under `.cloverleaf/`.
+Reference implementation of the Cloverleaf methodology as a set of Claude Code skills. Lets a user drive a Task from `pending` to `merged` with state, events, and feedback recorded in the repo under `.cloverleaf/`.
 
 Implements [Cloverleaf Standard](../standard/) v0.3.0 at L2 (Exchange) conformance.
 
@@ -15,15 +15,49 @@ npm install            # pulls @cloverleaf/standard + deps
 ./install.sh --project # local install into ./.claude/plugins/cloverleaf/
 ```
 
-## Skills provided
+## Scope (v0.2)
 
-| Slash command | Role |
-|---|---|
-| `/cloverleaf-new-task "<brief>"` | Scaffold a new Task JSON from a prose brief. |
-| `/cloverleaf-implement <TASK-ID>` | Dispatch Implementer subagent; advances pending → review. |
-| `/cloverleaf-review <TASK-ID>` | Dispatch Reviewer subagent; pass → automated-gates, bounce → implementing. |
-| `/cloverleaf-merge <TASK-ID>` | Human gate; confirm and transition automated-gates → merged. |
-| `/cloverleaf-run <TASK-ID>` | Orchestrator: loops implement → review with up to 3 bounces, pauses at the human merge gate. |
+v0.2 implements both paths of the Delivery track:
+
+- **Fast Lane** (`risk_class: "low"`): Implementer → Reviewer → Human Merge
+- **Full Pipeline** (`risk_class: "high"`): Implementer → Documenter → Reviewer → (UI Reviewer if `site/**` changed) → QA → Final Approval
+
+### Agents
+
+| Agent | Status | Mechanism |
+|---|---|---|
+| Implementer | Real | Subagent, code + tests on feature branch |
+| Documenter | Real (v0.2) | Subagent, doc-only commits per file-path rules |
+| Reviewer | Real | Subagent, read-only review of diff |
+| UI Reviewer | Real (v0.2) | Playwright + axe-core, single viewport, a11y only |
+| QA | Real (v0.2) | Per-package test runner via `git worktree` |
+| Plan | Stub | Deferred to v0.3 |
+| Researcher | Stub | Deferred to v0.3 |
+
+### Skills
+
+- `/cloverleaf-new-task` — scaffold a Task (auto-sets `risk_class`)
+- `/cloverleaf-implement` — run Implementer
+- `/cloverleaf-document` — run Documenter *(new in v0.2)*
+- `/cloverleaf-review` — run Reviewer
+- `/cloverleaf-ui-review` — run UI Reviewer *(new in v0.2)*
+- `/cloverleaf-qa` — run QA *(new in v0.2)*
+- `/cloverleaf-merge` — human gate (branches on state)
+- `/cloverleaf-run` — orchestrator (dispatches by `risk_class`)
+
+### Configuration
+
+Two JSON config files in `config/` (overridable per consumer project):
+
+- `config/ui-paths.json` — glob patterns that trigger UI Reviewer (default: `site/**`)
+- `config/qa-rules.json` — per-package test commands
+
+### Known limitations
+
+- Playwright installs ~300MB into each `git worktree` (v0.3 will cache).
+- Concurrent `/cloverleaf-run` on the same repo may race on preview ports.
+- UI Reviewer visual diff + multi-viewport deferred to v0.3.
+- QA does not produce HTML reports (no `report_uri`).
 
 ## Quick start — toy repo
 
@@ -41,21 +75,7 @@ In a Claude Code session in that directory:
 
 Watch it walk the state machine, produce a branch `cloverleaf/DEMO-001` with a `multiply` function + tests, and pause at the merge gate.
 
-## What's in v0.1.0
-
-- Implementer + Reviewer agents (wired as subagents).
-- Full state machine transitions from `pending` to `merged` (fast-lane path), with stub transitions through `documenting` and `automated-gates`.
-- Per-project committed audit trail under `.cloverleaf/`.
-- Max 3 bounces before `escalated`.
-
-## What's NOT in v0.1.0
-
-- Researcher, Plan, Documenter, UI Reviewer, QA agents (stub transitions only).
-- HTTP endpoints for the agent OpenAPI contracts — skills are markdown-driven, not servers. L3 conformance deferred.
-- `git push` / PR creation — branch stays local; user handles remote.
-- Path-rules or risk-classifier-rules enforcement — fast-lane is hardcoded.
-
-See [upcoming releases](../CHANGELOG.md) for the roadmap.
+See [CHANGELOG](../CHANGELOG.md) for the full release history and roadmap.
 
 ## Branch topology
 

package/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

package/config/qa-rules.json

@@ -0,0 +1,19 @@
+{
+  "rules": [
+    {
+      "cwd": "standard",
+      "match": ["standard/**"],
+      "command": "npm ci && npm test"
+    },
+    {
+      "cwd": "reference-impl",
+      "match": ["reference-impl/**"],
+      "command": "npm ci && npm test"
+    },
+    {
+      "cwd": "site",
+      "match": ["site/**"],
+      "command": "npm ci && npm run build"
+    }
+  ]
+}

package/config/ui-paths.json

@@ -0,0 +1,3 @@
+{
+  "patterns": ["site/**"]
+}

package/dist/cli.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * Cloverleaf CLI dispatcher.
+ *
+ * Usage: cli.ts <command> [args...]
+ *
+ * Commands:
+ *   load-task <repoRoot> <taskId>
+ *   infer-project <repoRoot>
+ *   next-task-id <repoRoot> [--project=<p>]
+ *   advance-status <repoRoot> <taskId> <toStatus> <actor> [gate] [path]
+ *   write-feedback <repoRoot> <taskId> <envelopeJsonPath>
+ *   latest-feedback <repoRoot> <taskId>
+ *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
+ */
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { loadTask } from './state.mjs';
+import { advanceStatus } from './state.mjs';
+import { emitGateDecision } from './events.mjs';
+import { writeFeedback, latestFeedback } from './feedback.mjs';
+import { nextTaskId, inferProject } from './ids.mjs';
+import { matchesUiPaths, loadDefaultPatterns } from './ui-paths.mjs';
+function die(msg, code = 1) {
+    process.stderr.write(msg + '\n');
+    process.exit(code);
+}
+function usage(msg) {
+    if (msg)
+        process.stderr.write(msg + '\n');
+    process.stderr.write('Usage: cli.ts <command> [args...]\n' +
+        'Commands:\n' +
+        '  load-task <repoRoot> <taskId>\n' +
+        '  infer-project <repoRoot>\n' +
+        '  next-task-id <repoRoot> [--project=<p>]\n' +
+        '  advance-status <repoRoot> <taskId> <toStatus> <actor> [gate] [path]\n' +
+        '  write-feedback <repoRoot> <taskId> <envelopeJsonPath>\n' +
+        '  latest-feedback <repoRoot> <taskId>\n' +
+        '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n');
+    process.exit(2);
+}
+const [, , command, ...rest] = process.argv;
+if (!command) {
+    usage('Error: no command given');
+}
+try {
+    switch (command) {
+        case 'load-task': {
+            const [repoRoot, taskId] = rest;
+            if (!repoRoot || !taskId)
+                usage('load-task requires <repoRoot> <taskId>');
+            const task = loadTask(repoRoot, taskId);
+            process.stdout.write(JSON.stringify(task, null, 2) + '\n');
+            break;
+        }
+        case 'infer-project': {
+            const [repoRoot] = rest;
+            if (!repoRoot)
+                usage('infer-project requires <repoRoot>');
+            const project = inferProject(repoRoot);
+            process.stdout.write(project + '\n');
+            break;
+        }
+        case 'next-task-id': {
+            // rest may contain --project=<p> flag among positional args
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [repoRoot] = positional;
+            if (!repoRoot)
+                usage('next-task-id requires <repoRoot>');
+            const projectFlag = flags.find((f) => f.startsWith('--project='));
+            const explicitProject = projectFlag ? projectFlag.replace('--project=', '') : undefined;
+            const project = inferProject(repoRoot, explicitProject);
+            const id = nextTaskId(repoRoot, project);
+            process.stdout.write(id + '\n');
+            break;
+        }
+        case 'advance-status': {
+            const [repoRoot, taskId, toStatus, actorArg, gate, path] = rest;
+            if (!repoRoot || !taskId || !toStatus || !actorArg)
+                usage('advance-status requires <repoRoot> <taskId> <toStatus> <actor> [gate] [path]');
+            if (actorArg !== 'agent' && actorArg !== 'human') {
+                die(`actor must be 'agent' or 'human' (got '${actorArg}')`, 2);
+            }
+            const actor = actorArg;
+            const opts = {};
+            if (gate)
+                opts.gate = gate;
+            if (path === 'fast_lane' || path === 'full_pipeline')
+                opts.path = path;
+            const updated = advanceStatus(repoRoot, taskId, toStatus, actor, opts);
+            process.stdout.write(updated.status + '\n');
+            break;
+        }
+        case 'write-feedback': {
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [repoRoot, taskId, envelopeJsonPath] = positional;
+            if (!repoRoot || !taskId || !envelopeJsonPath)
+                usage('write-feedback requires <repoRoot> <taskId> <envelopeJsonPath>');
+            const prefixFlag = flags.find((f) => f.startsWith('--prefix='));
+            const prefix = prefixFlag ? prefixFlag.split('=')[1] : 'r';
+            const envelope = JSON.parse(readFileSync(envelopeJsonPath, 'utf-8'));
+            const match = taskId.match(/^(.+)-\d+$/);
+            if (!match)
+                die(`Invalid taskId format: ${taskId}`);
+            const project = match[1];
+            const writtenPath = writeFeedback(repoRoot, { project, taskId, envelope, prefix });
+            process.stdout.write(writtenPath + '\n');
+            break;
+        }
+        case 'latest-feedback': {
+            const [repoRoot, taskId] = rest;
+            if (!repoRoot || !taskId)
+                usage('latest-feedback requires <repoRoot> <taskId>');
+            const envelope = latestFeedback(repoRoot, taskId);
+            if (envelope === null) {
+                process.stdout.write('');
+            }
+            else {
+                process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+            }
+            break;
+        }
+        case 'emit-gate-decision': {
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [repoRoot, workItemId, gate, decision, actorArg] = positional;
+            if (!repoRoot || !workItemId || !gate || !decision || !actorArg)
+                usage('emit-gate-decision requires <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]');
+            const validDecisions = ['approve', 'reject', 'revise', 'split', 'abandon', 'escalate'];
+            if (!validDecisions.includes(decision)) {
+                die(`decision must be one of: ${validDecisions.join(', ')}, got: ${decision}`);
+            }
+            if (actorArg !== 'agent' && actorArg !== 'human' && actorArg !== 'system') {
+                die(`actor must be "agent", "human", or "system", got: ${actorArg}`);
+            }
+            const commentFlag = flags.find((f) => f.startsWith('--comment='));
+            const comment = commentFlag ? commentFlag.replace('--comment=', '') : undefined;
+            // Derive project from workItemId (e.g. "DEMO-001" → "DEMO")
+            const wiMatch = workItemId.match(/^(.+)-\d+$/);
+            if (!wiMatch)
+                die(`Cannot derive project from workItemId: ${workItemId}`);
+            const project = wiMatch[1];
+            const writtenPath = emitGateDecision(repoRoot, {
+                project,
+                workItemType: 'task',
+                workItemId,
+                gate,
+                decision: decision,
+                actor: actorArg,
+                reasoning: comment,
+            });
+            process.stdout.write(writtenPath + '\n');
+            break;
+        }
+        case 'detect-ui-paths': {
+            const [repoRoot, taskId] = rest;
+            if (!repoRoot || !taskId) {
+                console.error('usage: detect-ui-paths <repo_root> <task-id>');
+                process.exit(1);
+            }
+            const branch = `cloverleaf/${taskId}`;
+            let changed;
+            try {
+                const out = execSync(`git diff --name-only main..${branch}`, {
+                    cwd: repoRoot,
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                changed = out.split('\n').map((l) => l.trim()).filter(Boolean);
+            }
+            catch (e) {
+                const err = e;
+                const stderrStr = typeof err.stderr === 'string' ? err.stderr : err.stderr?.toString() ?? '';
+                console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
+                process.exit(2);
+            }
+            const patterns = loadDefaultPatterns();
+            const result = matchesUiPaths(changed, patterns);
+            process.stdout.write(`${result}\n`);
+            process.exit(0);
+        }
+        default:
+            usage(`Unknown command: ${command}`);
+    }
+}
+catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // Surface "illegal transition" errors with the right language
+    const lower = msg.toLowerCase();
+    if (lower.includes('illegal') || lower.includes('not allowed')) {
+        die(`Illegal transition: ${msg}`);
+    }
+    die(`Error: ${msg}`);
+}

package/dist/events.mjs

@@ -0,0 +1,80 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { eventsDir } from './paths.mjs';
+import { nextEventId } from './ids.mjs';
+import { validateOrThrow } from './validate.mjs';
+function actorObject(kind) {
+    const id = kind === 'agent' ? 'implementer' : kind === 'human' ? 'local-user' : 'system';
+    return { kind, id };
+}
+export function formatReason(opts) {
+    const parts = [];
+    if (opts.gate)
+        parts.push(`gate=${opts.gate}`);
+    if (opts.path)
+        parts.push(`path=${opts.path}`);
+    return parts.length > 0 ? parts.join('; ') : undefined;
+}
+/**
+ * Emits a status-transition event to `.cloverleaf/events/`.
+ * File name: `<PROJECT>-<NNN>-status.json` where NNN is the next per-project
+ * sequential number derived from existing event files.
+ *
+ * Returns the absolute path of the written file.
+ */
+export function emitStatusTransition(repoRoot, params) {
+    const { project, workItemType, workItemId, from, to, actor } = params;
+    const seq = nextEventId(repoRoot, project);
+    const seqStr = String(seq).padStart(3, '0');
+    const filename = `${project}-${seqStr}-status.json`;
+    const filePath = join(eventsDir(repoRoot), filename);
+    // Build reason from gate and/or path if provided (schema only allows reason, not gate/path at top level).
+    const reason = formatReason({ gate: params.gate, path: params.path });
+    const doc = {
+        event_id: randomUUID(),
+        event_type: 'status_transition',
+        occurred_at: new Date().toISOString(),
+        work_item_id: { project, id: workItemId },
+        work_item_type: workItemType,
+        from_status: from,
+        to_status: to,
+        actor: actorObject(actor),
+    };
+    if (reason !== undefined) {
+        doc.reason = reason;
+    }
+    mkdirSync(eventsDir(repoRoot), { recursive: true });
+    validateOrThrow('https://cloverleaf.example/schemas/status-transition-event.schema.json', doc);
+    writeFileSync(filePath, JSON.stringify(doc, null, 2) + '\n');
+    return filePath;
+}
+/**
+ * Emits a gate-decision event to `.cloverleaf/events/`.
+ * File name: `<PROJECT>-<NNN>-gate.json`.
+ *
+ * Returns the absolute path of the written file.
+ */
+export function emitGateDecision(repoRoot, params) {
+    const { project, workItemId, gate, decision, actor, reasoning } = params;
+    const seq = nextEventId(repoRoot, project);
+    const seqStr = String(seq).padStart(3, '0');
+    const filename = `${project}-${seqStr}-gate.json`;
+    const filePath = join(eventsDir(repoRoot), filename);
+    const doc = {
+        event_id: randomUUID(),
+        event_type: 'gate_decision',
+        occurred_at: new Date().toISOString(),
+        gate,
+        work_item_id: { project, id: workItemId },
+        decision,
+        approver: actorObject(actor),
+    };
+    if (reasoning !== undefined) {
+        doc.comment = reasoning;
+    }
+    mkdirSync(eventsDir(repoRoot), { recursive: true });
+    validateOrThrow('https://cloverleaf.example/schemas/gate-decision-event.schema.json', doc);
+    writeFileSync(filePath, JSON.stringify(doc, null, 2) + '\n');
+    return filePath;
+}

package/dist/feedback.mjs

@@ -0,0 +1,41 @@
+import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { feedbackDir } from './paths.mjs';
+import { nextFeedbackIteration } from './ids.mjs';
+import { validateOrThrow } from './validate.mjs';
+export function writeFeedback(repoRoot, params) {
+    const match = params.taskId.match(/^(.+)-(\d+)$/);
+    if (!match)
+        throw new Error(`Invalid taskId: ${params.taskId}`);
+    const project = match[1];
+    const taskNum = parseInt(match[2], 10);
+    if (project !== params.project) {
+        throw new Error(`project mismatch: taskId=${params.taskId} vs project=${params.project}`);
+    }
+    const prefix = params.prefix ?? 'r';
+    const iteration = nextFeedbackIteration(repoRoot, project, taskNum, prefix);
+    const filename = `${params.taskId}-${prefix}${iteration}.json`;
+    const path = join(feedbackDir(repoRoot), filename);
+    mkdirSync(feedbackDir(repoRoot), { recursive: true });
+    validateOrThrow('https://cloverleaf.example/schemas/feedback.schema.json', params.envelope);
+    writeFileSync(path, JSON.stringify(params.envelope, null, 2) + '\n');
+    return path;
+}
+export function latestFeedback(repoRoot, taskId) {
+    const items = allFeedback(repoRoot, taskId);
+    return items.length === 0 ? null : items[items.length - 1];
+}
+export function allFeedback(repoRoot, taskId) {
+    const dir = feedbackDir(repoRoot);
+    if (!existsSync(dir))
+        return [];
+    const re = new RegExp(`^${escapeRegex(taskId)}-r(\\d+)\\.json$`);
+    const entries = readdirSync(dir)
+        .map((f) => ({ f, m: f.match(re) }))
+        .filter((x) => !!x.m)
+        .sort((a, b) => parseInt(a.m[1], 10) - parseInt(b.m[1], 10));
+    return entries.map(({ f }) => JSON.parse(readFileSync(join(dir, f), 'utf-8')));
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/ids.mjs

@@ -0,0 +1,60 @@
+import { readdirSync, existsSync } from 'node:fs';
+import { tasksDir, eventsDir, feedbackDir, projectsDir } from './paths.mjs';
+export function nextTaskId(repoRoot, project) {
+    const dir = tasksDir(repoRoot);
+    if (!existsSync(dir))
+        return `${project}-001`;
+    const re = new RegExp(`^${escapeRegex(project)}-(\\d+)\\.json$`);
+    const nums = readdirSync(dir)
+        .map((f) => f.match(re))
+        .filter((m) => !!m)
+        .map((m) => parseInt(m[1], 10));
+    const next = nums.length === 0 ? 1 : Math.max(...nums) + 1;
+    return `${project}-${String(next).padStart(3, '0')}`;
+}
+export function nextEventId(repoRoot, project) {
+    const dir = eventsDir(repoRoot);
+    if (!existsSync(dir))
+        return 1;
+    const re = new RegExp(`^${escapeRegex(project)}-(\\d+)-(status|gate)\\.json$`);
+    const nums = readdirSync(dir)
+        .map((f) => f.match(re))
+        .filter((m) => !!m)
+        .map((m) => parseInt(m[1], 10));
+    return nums.length === 0 ? 1 : Math.max(...nums) + 1;
+}
+export function nextFeedbackIteration(repoRoot, project, taskNum, prefix = 'r') {
+    const dir = feedbackDir(repoRoot);
+    if (!existsSync(dir))
+        return 1;
+    const suffix = String(taskNum).padStart(3, '0');
+    const escapedPrefix = escapeRegex(prefix);
+    const re = new RegExp(`^${escapeRegex(project)}-${suffix}-${escapedPrefix}(\\d+)\\.json$`);
+    const nums = readdirSync(dir)
+        .map((f) => f.match(re))
+        .filter((m) => !!m)
+        .map((m) => parseInt(m[1], 10));
+    return nums.length === 0 ? 1 : Math.max(...nums) + 1;
+}
+export function listProjects(repoRoot) {
+    const dir = projectsDir(repoRoot);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith('.json') && !f.endsWith('.meta.json'))
+        .map((f) => f.replace(/\.json$/, ''));
+}
+export function inferProject(repoRoot, explicit) {
+    if (explicit)
+        return explicit;
+    const projects = listProjects(repoRoot);
+    if (projects.length === 0)
+        throw new Error('No projects found under .cloverleaf/projects/');
+    if (projects.length > 1) {
+        throw new Error(`Multiple projects found (${projects.join(', ')}); specify one explicitly.`);
+    }
+    return projects[0];
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/index.mjs

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

package/dist/paths.mjs

@@ -0,0 +1,26 @@
+import { resolve } from 'node:path';
+const CLOVERLEAF = '.cloverleaf';
+export function cloverleafDir(repoRoot) {
+    return resolve(repoRoot, CLOVERLEAF);
+}
+export function projectsDir(repoRoot) {
+    return resolve(cloverleafDir(repoRoot), 'projects');
+}
+export function tasksDir(repoRoot) {
+    return resolve(cloverleafDir(repoRoot), 'tasks');
+}
+export function eventsDir(repoRoot) {
+    return resolve(cloverleafDir(repoRoot), 'events');
+}
+export function feedbackDir(repoRoot) {
+    return resolve(cloverleafDir(repoRoot), 'feedback');
+}
+export function rfcsDir(repoRoot) {
+    return resolve(cloverleafDir(repoRoot), 'rfcs');
+}
+export function spikesDir(repoRoot) {
+    return resolve(cloverleafDir(repoRoot), 'spikes');
+}
+export function plansDir(repoRoot) {
+    return resolve(cloverleafDir(repoRoot), 'plans');
+}

package/dist/ports.mjs

@@ -0,0 +1,19 @@
+import { createServer } from 'node:net';
+export function getFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.unref();
+        server.once('error', reject);
+        server.listen(0, () => {
+            const addr = server.address();
+            if (addr && typeof addr === 'object') {
+                const port = addr.port;
+                server.close(() => resolve(port));
+            }
+            else {
+                server.close();
+                reject(new Error('could not determine port'));
+            }
+        });
+    });
+}

package/dist/qa-rules.mjs

@@ -0,0 +1,15 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { matchesUiPaths } from './ui-paths.mjs';
+const here = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG = join(here, '..', 'config', 'qa-rules.json');
+export function loadDefaultRules() {
+    if (!existsSync(DEFAULT_CONFIG))
+        return [];
+    const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));
+    return Array.isArray(doc.rules) ? doc.rules : [];
+}
+export function selectTestCommands(changedFiles, rules) {
+    return rules.filter((rule) => matchesUiPaths(changedFiles, rule.match));
+}

package/dist/state.mjs

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { tasksDir, projectsDir } from './paths.mjs';
+import { emitStatusTransition, formatReason } from './events.mjs';
+// Import validator from @cloverleaf/standard.
+// The standard package ships TypeScript source only with no exports map.
+// Vitest (via vite-node) resolves .js → .ts for workspace symlinked packages,
+// so the .js convention works here. If it ever fails with "module not found",
+// switch the specifier to '@cloverleaf/standard/validators/index.ts'.
+import { validateStatusTransitionLegality } from '@cloverleaf/standard/validators/index.js';
+import { validateOrThrow } from './validate.mjs';
+const req = createRequire(import.meta.url);
+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'));
+}
+function loadTaskStateMachine() {
+    // state-machines/task.json is a static JSON asset. Navigate from standard's
+    // package.json — no exports map support needed.
+    const pkgPath = req.resolve('@cloverleaf/standard/package.json');
+    const pkgDir = pkgPath.replace(/\/package\.json$/, '');
+    return JSON.parse(readFileSync(`${pkgDir}/state-machines/task.json`, 'utf-8'));
+}
+export function advanceStatus(repoRoot, taskId, toStatus, actor, options = {}) {
+    const task = loadTask(repoRoot, taskId);
+    const from = task.status;
+    const sm = loadTaskStateMachine();
+    // Read risk_class directly from the task (defaulting to 'low' if absent).
+    // The validator derives itemPath from workItem.risk_class: low → fast_lane, else full_pipeline.
+    // If caller passed options.path, translate it back to risk_class for the validator.
+    const riskClass = options.path === 'fast_lane' ? 'low'
+        : options.path === 'full_pipeline' ? 'high'
+            : (task.risk_class ?? 'low');
+    // Build a minimal Task-shaped object so the validator can resolve path-tagged transitions.
+    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 reason = formatReason({ gate: options.gate, path: options.path });
+    const event = {
+        event_id: randomUUID(),
+        event_type: 'status_transition',
+        occurred_at: new Date().toISOString(),
+        work_item_id: { project: task.project, id: task.id },
+        work_item_type: 'task',
+        from_status: from,
+        to_status: toStatus,
+        actor: { kind: actor, id: actor },
+        ...(reason ? { reason } : {}),
+    };
+    const result = validateStatusTransitionLegality(event, sm, workItemForValidator);
+    if (!result.ok) {
+        const msgs = result.violations.map((v) => v.message).join('; ');
+        throw new Error(`Illegal transition ${from} → ${toStatus}: ${msgs}`);
+    }
+    // NEW: emit first, save second. validateStatusTransitionLegality stays above.
+    const emittedPath = emitStatusTransition(repoRoot, {
+        project: task.project,
+        workItemType: 'task',
+        workItemId: task.id,
+        from,
+        to: toStatus,
+        actor,
+        gate: options.gate,
+        path: options.path,
+    });
+    const proposed = { ...task, status: toStatus };
+    try {
+        saveTask(repoRoot, proposed);
+    }
+    catch (err) {
+        const inner = err instanceof Error ? err.message : String(err);
+        throw new Error(`orphan event written to ${emittedPath} but task save failed: ${inner}`);
+    }
+    return proposed;
+}