@cloverleaf/reference-impl 0.9.0 → 0.10.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, release).",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

package/VERSION

@@ -1 +1 @@
-0.9.0
+0.10.0

package/config/discovery.json

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

package/dist/cli.mjs

@@ -31,6 +31,7 @@
  *   next-work-item-id <repoRoot> <project>
  *   discovery-config --repo-root <repoRoot>
  *   prep-worktree <mainRoot> <worktreePath>
+ *   qa-report <runs.json> <out.html>
  *   dag-ready-tasks <repoRoot> <planId> <maxConcurrent>
  *   dag-detect-cycle <repoRoot> <planId>
  *   walk-state-read <repoRoot> <planId>
@@ -64,6 +65,7 @@ import { loadSpike, saveSpike, advanceSpikeStatus } from './spike.mjs';
 import { loadPlan, savePlan, advancePlanStatus, materialiseTasksFromPlan } from './plan.mjs';
 import { loadDiscoveryConfig } from './discovery-config.mjs';
 import { prepWorktree } from './prep-worktree.mjs';
+import { writeQaReportFromFile } from './qa-report.mjs';
 import { readUiReviewState, writeUiReviewState } from './ui-review-state.mjs';
 import { buildBaselinePath } from './visual-diff.mjs';
 import { computeReadyTasks, detectCycle } from './dag-walker.mjs';
@@ -110,6 +112,7 @@ function usage(msg) {
         '  next-work-item-id <repoRoot> <project>\n' +
         '  discovery-config --repo-root <repoRoot>\n' +
         '  prep-worktree <mainRoot> <worktreePath>\n' +
+        '  qa-report <runs.json> <out.html>\n' +
         '  dag-ready-tasks <repoRoot> <planId> <maxConcurrent>\n' +
         '  dag-detect-cycle <repoRoot> <planId>\n' +
         '  walk-state-read <repoRoot> <planId>\n' +
@@ -493,6 +496,13 @@ try {
             prepWorktree(mainRoot, worktreePath);
             break;
         }
+        case 'qa-report': {
+            const [runsJsonPath, outHtmlPath] = rest;
+            if (!runsJsonPath || !outHtmlPath)
+                usage('qa-report requires <runs.json> <out.html>');
+            writeQaReportFromFile(runsJsonPath, outHtmlPath);
+            break;
+        }
         case 'dag-ready-tasks': {
             const [repoRoot, planId, maxConcurrentStr] = rest;
             if (!repoRoot || !planId || !maxConcurrentStr)

package/dist/discovery-config.mjs

@@ -13,6 +13,7 @@ export function loadDiscoveryConfig(repoRoot) {
         prep_copy_dirs: Array.isArray(rawFallback.prep_copy_dirs)
             ? rawFallback.prep_copy_dirs.filter((p) => typeof p === 'string')
             : [],
+        worktree_setup_command: typeof rawFallback.worktree_setup_command === 'string' ? rawFallback.worktree_setup_command : '',
     };
     if (existsSync(override)) {
         try {
@@ -33,5 +34,6 @@ function normalise(doc, fallback) {
         prep_copy_dirs: Array.isArray(doc.prep_copy_dirs)
             ? doc.prep_copy_dirs.filter((p) => typeof p === 'string')
             : fallback.prep_copy_dirs,
+        worktree_setup_command: typeof doc.worktree_setup_command === 'string' ? doc.worktree_setup_command : fallback.worktree_setup_command,
     };
 }

package/dist/prep-worktree.mjs

@@ -87,42 +87,61 @@ function buildMissingNodeModulesError(mainRoot) {
     return new Error(`main missing standard/node_modules at ${mainStandardNm} — run \`npm ci\` in main's standard/ first`);
 }
 export function prepWorktree(mainRoot, worktreePath) {
-    const wtStandardPkg = join(worktreePath, 'standard', 'package.json');
-    const wtRefImplPkg = join(worktreePath, 'reference-impl', 'package.json');
-    if (!existsSync(wtStandardPkg)) {
-        throw new Error(`worktree missing standard/package.json at ${wtStandardPkg}`);
+    const embedded = existsSync(join(worktreePath, 'standard', 'package.json')) &&
+        existsSync(join(worktreePath, 'reference-impl', 'package.json'));
+    // configRoot is where .cloverleaf/config/discovery.json is read from. Embedded mode
+    // walks up to the primary repo (which holds node_modules + the config); a non-monorepo
+    // consumer uses mainRoot directly.
+    let configRoot;
+    if (embedded) {
+        const resolvedMain = findPrimaryRoot(mainRoot);
+        if (resolvedMain === null) {
+            throw buildMissingNodeModulesError(mainRoot);
+        }
+        configRoot = resolvedMain;
+    }
+    else {
+        configRoot = mainRoot;
+    }
+    const config = loadDiscoveryConfig(configRoot);
+    if (embedded) {
+        // Embedded / monorepo mode: prime the cloverleaf TS tooling (unchanged behavior).
+        copyEmbeddedArtifacts(configRoot, worktreePath);
     }
-    if (!existsSync(wtRefImplPkg)) {
-        throw new Error(`worktree missing reference-impl/package.json at ${wtRefImplPkg}`);
+    // Both modes: copy any gitignored dirs the consumer's tests/briefs reference.
+    copyPrepDirs(configRoot, config.prep_copy_dirs, worktreePath);
+    if (embedded) {
+        // Build standard/ fresh from the worktree's own sources.
+        execSync('npm run build', {
+            cwd: join(worktreePath, 'standard'),
+            stdio: 'pipe',
+        });
     }
-    // Resolve the actual primary repo root: start from mainRoot and walk up until we find a
-    // directory containing both standard/node_modules and reference-impl/node_modules.
-    const resolvedMain = findPrimaryRoot(mainRoot);
-    if (resolvedMain === null) {
-        throw buildMissingNodeModulesError(mainRoot);
+    // Both modes: run the consumer's worktree setup command, if configured.
+    if (config.worktree_setup_command.trim() !== '') {
+        execSync(config.worktree_setup_command, {
+            cwd: worktreePath,
+            stdio: 'pipe',
+        });
     }
-    const mainStandardNm = join(resolvedMain, 'standard', 'node_modules');
-    const mainRefImplNm = join(resolvedMain, 'reference-impl', 'node_modules');
-    const wtStandardNm = join(worktreePath, 'standard', 'node_modules');
-    const wtRefImplNm = join(worktreePath, 'reference-impl', 'node_modules');
-    // verbatimSymlinks keeps relative symlink targets byte-identical, so the @cloverleaf/standard
-    // link in reference-impl/node_modules/ resolves against the worktree after copy.
-    //
-    // primeCopy wipes the destination before cpSync. Two reasons:
-    //   1. Idempotence: a partial prior run (or a re-invocation after a test failure) may
-    //      leave partial state; we must not trip on it.
-    //   2. cpSync with verbatimSymlinks: true does not reliably overwrite an existing
-    //      symlink at the destination even with force: true (CLV-20 Reviewer repro was
-    //      EEXIST on vite/node_modules/.bin on second invocation).
-    primeCopy(mainStandardNm, wtStandardNm);
-    primeCopy(mainRefImplNm, wtRefImplNm);
+}
+/**
+ * Embedded / monorepo mode: copy the primary repo's installed cloverleaf TS deps + built
+ * dist into the worktree, preserving the @cloverleaf/standard relative symlink. (See the
+ * file header for the CLV-16/17/37/52 history.)
+ */
+function copyEmbeddedArtifacts(resolvedMain, worktreePath) {
+    primeCopy(join(resolvedMain, 'standard', 'node_modules'), join(worktreePath, 'standard', 'node_modules'));
+    primeCopy(join(resolvedMain, 'reference-impl', 'node_modules'), join(worktreePath, 'reference-impl', 'node_modules'));
     primeCopy(join(resolvedMain, 'reference-impl', 'dist'), join(worktreePath, 'reference-impl', 'dist'));
-    // Honor discovery_config.prep_copy_dirs: copy each listed gitignored directory
-    // (e.g., docs/superpowers) from mainRoot into the worktree. Walker briefs reference
-    // these paths but git checkouts of main don't carry gitignored content.
-    const discoveryConfig = loadDiscoveryConfig(resolvedMain);
-    for (const dir of discoveryConfig.prep_copy_dirs) {
-        const srcPath = join(resolvedMain, dir);
+}
+/**
+ * Honor discovery_config.prep_copy_dirs: copy each listed gitignored directory from
+ * configRoot into the worktree. Missing entries warn and are skipped.
+ */
+function copyPrepDirs(configRoot, dirs, worktreePath) {
+    for (const dir of dirs) {
+        const srcPath = join(configRoot, dir);
         const dstPath = join(worktreePath, dir);
         if (!existsSync(srcPath)) {
             process.stderr.write(`prep-worktree: prep_copy_dirs entry '${dir}' not found at ${srcPath} — skipping.\n`);
@@ -130,10 +149,6 @@ export function prepWorktree(mainRoot, worktreePath) {
         }
         primeCopy(srcPath, dstPath);
     }
-    execSync('npm run build', {
-        cwd: join(worktreePath, 'standard'),
-        stdio: 'pipe',
-    });
 }
 function primeCopy(src, dst) {
     if (existsSync(dst)) {

package/dist/qa-report.mjs

@@ -1,3 +1,5 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
 function escape(s) {
     if (s === undefined || s === null)
         return '';
@@ -28,6 +30,17 @@ function renderRow(r) {
     </tr>
   `;
 }
+/**
+ * Read a QA runs JSON file (array of QaRunResult), render the HTML report, and write it to
+ * outHtmlPath, creating the parent directory if needed. Lets QA write its report via the
+ * cloverleaf-cli bin instead of importing a monorepo dist path.
+ */
+export function writeQaReportFromFile(runsJsonPath, outHtmlPath) {
+    const runs = JSON.parse(readFileSync(runsJsonPath, 'utf-8'));
+    const html = renderQaReport(runs);
+    mkdirSync(dirname(outHtmlPath), { recursive: true });
+    writeFileSync(outHtmlPath, html, 'utf-8');
+}
 export function renderQaReport(runs) {
     const empty = runs.length === 0
         ? `<p class="empty">No runs / results.</p>`

package/dist/rfc-tasks.mjs

@@ -3,8 +3,7 @@ import { join } from 'node:path';
 import { plansDir, tasksDir, rfcsDir } from './paths.mjs';
 /**
  * A task is "standalone" (RFC-direct) iff it has no parent (absent or null)
- * AND it has a non-empty context.rfc.id. See
- * docs/superpowers/specs/2026-05-12-rfc-direct-tasks-design.md §"Discriminator".
+ * AND it has a non-empty context.rfc.id.
  */
 export function isStandaloneTask(task) {
     const parent = task.parent;

package/lib/cli.ts

@@ -31,6 +31,7 @@
  *   next-work-item-id <repoRoot> <project>
  *   discovery-config --repo-root <repoRoot>
  *   prep-worktree <mainRoot> <worktreePath>
+ *   qa-report <runs.json> <out.html>
  *   dag-ready-tasks <repoRoot> <planId> <maxConcurrent>
  *   dag-detect-cycle <repoRoot> <planId>
  *   walk-state-read <repoRoot> <planId>
@@ -66,6 +67,7 @@ import { loadSpike, saveSpike, advanceSpikeStatus, type SpikeDoc } from './spike
 import { loadPlan, savePlan, advancePlanStatus, materialiseTasksFromPlan, type PlanDoc } from './plan.js';
 import { loadDiscoveryConfig } from './discovery-config.js';
 import { prepWorktree } from './prep-worktree.js';
+import { writeQaReportFromFile } from './qa-report.js';
 import { readUiReviewState, writeUiReviewState } from './ui-review-state.js';
 import { buildBaselinePath } from './visual-diff.js';
 import { computeReadyTasks, detectCycle } from './dag-walker.js';
@@ -115,6 +117,7 @@ function usage(msg?: string): never {
       '  next-work-item-id <repoRoot> <project>\n' +
       '  discovery-config --repo-root <repoRoot>\n' +
       '  prep-worktree <mainRoot> <worktreePath>\n' +
+      '  qa-report <runs.json> <out.html>\n' +
       '  dag-ready-tasks <repoRoot> <planId> <maxConcurrent>\n' +
       '  dag-detect-cycle <repoRoot> <planId>\n' +
       '  walk-state-read <repoRoot> <planId>\n' +
@@ -506,6 +509,13 @@ try {
       break;
     }
 
+    case 'qa-report': {
+      const [runsJsonPath, outHtmlPath] = rest;
+      if (!runsJsonPath || !outHtmlPath) usage('qa-report requires <runs.json> <out.html>');
+      writeQaReportFromFile(runsJsonPath, outHtmlPath);
+      break;
+    }
+
     case 'dag-ready-tasks': {
       const [repoRoot, planId, maxConcurrentStr] = rest;
       if (!repoRoot || !planId || !maxConcurrentStr)

package/lib/discovery-config.ts

@@ -10,6 +10,7 @@ export interface DiscoveryConfig {
   projectId: string;
   idStart: number;
   prep_copy_dirs: string[];
+  worktree_setup_command: string;
 }
 
 export function loadDiscoveryConfig(repoRoot: string): DiscoveryConfig {
@@ -22,6 +23,8 @@ export function loadDiscoveryConfig(repoRoot: string): DiscoveryConfig {
     prep_copy_dirs: Array.isArray(rawFallback.prep_copy_dirs)
       ? (rawFallback.prep_copy_dirs as unknown[]).filter((p): p is string => typeof p === 'string')
       : [],
+    worktree_setup_command:
+      typeof rawFallback.worktree_setup_command === 'string' ? rawFallback.worktree_setup_command : '',
   };
 
   if (existsSync(override)) {
@@ -43,5 +46,7 @@ function normalise(doc: Partial<DiscoveryConfig>, fallback: DiscoveryConfig): Di
     prep_copy_dirs: Array.isArray(doc.prep_copy_dirs)
       ? (doc.prep_copy_dirs as unknown[]).filter((p): p is string => typeof p === 'string')
       : fallback.prep_copy_dirs,
+    worktree_setup_command:
+      typeof doc.worktree_setup_command === 'string' ? doc.worktree_setup_command : fallback.worktree_setup_command,
   };
 }

package/lib/prep-worktree.ts

@@ -95,48 +95,69 @@ function buildMissingNodeModulesError(mainRoot: string): Error {
 }
 
 export function prepWorktree(mainRoot: string, worktreePath: string): void {
-  const wtStandardPkg = join(worktreePath, 'standard', 'package.json');
-  const wtRefImplPkg = join(worktreePath, 'reference-impl', 'package.json');
+  const embedded =
+    existsSync(join(worktreePath, 'standard', 'package.json')) &&
+    existsSync(join(worktreePath, 'reference-impl', 'package.json'));
 
-  if (!existsSync(wtStandardPkg)) {
-    throw new Error(`worktree missing standard/package.json at ${wtStandardPkg}`);
-  }
-  if (!existsSync(wtRefImplPkg)) {
-    throw new Error(`worktree missing reference-impl/package.json at ${wtRefImplPkg}`);
+  // configRoot is where .cloverleaf/config/discovery.json is read from. Embedded mode
+  // walks up to the primary repo (which holds node_modules + the config); a non-monorepo
+  // consumer uses mainRoot directly.
+  let configRoot: string;
+  if (embedded) {
+    const resolvedMain = findPrimaryRoot(mainRoot);
+    if (resolvedMain === null) {
+      throw buildMissingNodeModulesError(mainRoot);
+    }
+    configRoot = resolvedMain;
+  } else {
+    configRoot = mainRoot;
   }
 
-  // Resolve the actual primary repo root: start from mainRoot and walk up until we find a
-  // directory containing both standard/node_modules and reference-impl/node_modules.
-  const resolvedMain = findPrimaryRoot(mainRoot);
-  if (resolvedMain === null) {
-    throw buildMissingNodeModulesError(mainRoot);
+  const config = loadDiscoveryConfig(configRoot);
+
+  if (embedded) {
+    // Embedded / monorepo mode: prime the cloverleaf TS tooling (unchanged behavior).
+    copyEmbeddedArtifacts(configRoot, worktreePath);
   }
 
-  const mainStandardNm = join(resolvedMain, 'standard', 'node_modules');
-  const mainRefImplNm = join(resolvedMain, 'reference-impl', 'node_modules');
+  // Both modes: copy any gitignored dirs the consumer's tests/briefs reference.
+  copyPrepDirs(configRoot, config.prep_copy_dirs, worktreePath);
 
-  const wtStandardNm = join(worktreePath, 'standard', 'node_modules');
-  const wtRefImplNm = join(worktreePath, 'reference-impl', 'node_modules');
+  if (embedded) {
+    // Build standard/ fresh from the worktree's own sources.
+    execSync('npm run build', {
+      cwd: join(worktreePath, 'standard'),
+      stdio: 'pipe',
+    });
+  }
+
+  // Both modes: run the consumer's worktree setup command, if configured.
+  if (config.worktree_setup_command.trim() !== '') {
+    execSync(config.worktree_setup_command, {
+      cwd: worktreePath,
+      stdio: 'pipe',
+    });
+  }
+}
 
-  // verbatimSymlinks keeps relative symlink targets byte-identical, so the @cloverleaf/standard
-  // link in reference-impl/node_modules/ resolves against the worktree after copy.
-  //
-  // primeCopy wipes the destination before cpSync. Two reasons:
-  //   1. Idempotence: a partial prior run (or a re-invocation after a test failure) may
-  //      leave partial state; we must not trip on it.
-  //   2. cpSync with verbatimSymlinks: true does not reliably overwrite an existing
-  //      symlink at the destination even with force: true (CLV-20 Reviewer repro was
-  //      EEXIST on vite/node_modules/.bin on second invocation).
-  primeCopy(mainStandardNm, wtStandardNm);
-  primeCopy(mainRefImplNm, wtRefImplNm);
+/**
+ * Embedded / monorepo mode: copy the primary repo's installed cloverleaf TS deps + built
+ * dist into the worktree, preserving the @cloverleaf/standard relative symlink. (See the
+ * file header for the CLV-16/17/37/52 history.)
+ */
+function copyEmbeddedArtifacts(resolvedMain: string, worktreePath: string): void {
+  primeCopy(join(resolvedMain, 'standard', 'node_modules'), join(worktreePath, 'standard', 'node_modules'));
+  primeCopy(join(resolvedMain, 'reference-impl', 'node_modules'), join(worktreePath, 'reference-impl', 'node_modules'));
   primeCopy(join(resolvedMain, 'reference-impl', 'dist'), join(worktreePath, 'reference-impl', 'dist'));
+}
 
-  // Honor discovery_config.prep_copy_dirs: copy each listed gitignored directory
-  // (e.g., docs/superpowers) from mainRoot into the worktree. Walker briefs reference
-  // these paths but git checkouts of main don't carry gitignored content.
-  const discoveryConfig = loadDiscoveryConfig(resolvedMain);
-  for (const dir of discoveryConfig.prep_copy_dirs) {
-    const srcPath = join(resolvedMain, dir);
+/**
+ * Honor discovery_config.prep_copy_dirs: copy each listed gitignored directory from
+ * configRoot into the worktree. Missing entries warn and are skipped.
+ */
+function copyPrepDirs(configRoot: string, dirs: string[], worktreePath: string): void {
+  for (const dir of dirs) {
+    const srcPath = join(configRoot, dir);
     const dstPath = join(worktreePath, dir);
     if (!existsSync(srcPath)) {
       process.stderr.write(`prep-worktree: prep_copy_dirs entry '${dir}' not found at ${srcPath} — skipping.\n`);
@@ -144,11 +165,6 @@ export function prepWorktree(mainRoot: string, worktreePath: string): void {
     }
     primeCopy(srcPath, dstPath);
   }
-
-  execSync('npm run build', {
-    cwd: join(worktreePath, 'standard'),
-    stdio: 'pipe',
-  });
 }
 
 function primeCopy(src: string, dst: string): void {

package/lib/qa-report.ts

@@ -1,3 +1,6 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
 export interface QaRunResult {
   ruleId: string;
   command: string;
@@ -39,6 +42,18 @@ function renderRow(r: QaRunResult): string {
   `;
 }
 
+/**
+ * Read a QA runs JSON file (array of QaRunResult), render the HTML report, and write it to
+ * outHtmlPath, creating the parent directory if needed. Lets QA write its report via the
+ * cloverleaf-cli bin instead of importing a monorepo dist path.
+ */
+export function writeQaReportFromFile(runsJsonPath: string, outHtmlPath: string): void {
+  const runs = JSON.parse(readFileSync(runsJsonPath, 'utf-8')) as QaRunResult[];
+  const html = renderQaReport(runs);
+  mkdirSync(dirname(outHtmlPath), { recursive: true });
+  writeFileSync(outHtmlPath, html, 'utf-8');
+}
+
 export function renderQaReport(runs: QaRunResult[]): string {
   const empty = runs.length === 0
     ? `<p class="empty">No runs / results.</p>`

package/lib/rfc-tasks.ts

@@ -6,8 +6,7 @@ import type { PlanDoc } from './plan.js';
 
 /**
  * A task is "standalone" (RFC-direct) iff it has no parent (absent or null)
- * AND it has a non-empty context.rfc.id. See
- * docs/superpowers/specs/2026-05-12-rfc-direct-tasks-design.md §"Discriminator".
+ * AND it has a non-empty context.rfc.id.
  */
 export function isStandaloneTask(task: TaskDoc): boolean {
   const parent = (task as Record<string, unknown>).parent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

package/prompts/implementer.md

@@ -8,6 +8,7 @@ You are the Cloverleaf Implementer agent. Your job: take a Task and produce work
 - `feedback`: optional — the most recent feedback envelope from a prior Reviewer bounce. If present, address every finding before re-submitting.
 - `repo_root`: absolute path to the consumer repo.
 - `base_branch`: the branch to branch off (default: `main`).
+- `test_rules`: a JSON object `{ rules: [...] }` whose `rules` is a list of `{cwd, match, command}` entries (from `qa-rules.json`).
 
 ## Your process
 
@@ -26,7 +27,7 @@ You are the Cloverleaf Implementer agent. Your job: take a Task and produce work
 2. If `feedback` is present, re-read each finding; plan how to address them.
 3. Create a new branch named `cloverleaf/<task.id>` from `base_branch` using `git checkout -b cloverleaf/<task.id>`.
 4. Implement the code + tests needed to satisfy every acceptance criterion.
-5. Run the project's test command (typically `npm test` — check package.json `scripts.test`). All tests must pass.
+5. Run the project's tests. Your test rules are provided as `{{test_rules}}` — a JSON object `{ rules: [...] }` whose `rules` is a list of `{cwd, match, command}` entries; each `match` is a list of glob patterns. For each rule whose `match` covers a file you changed, run its `command` in its `cwd`. All must pass. (If no rule matches your changes, there is nothing to run.)
 6. Stage and commit your changes with message `feat: <task.title> [<task.id>]`.
 7. Return a structured JSON result to stdout:
 
@@ -54,5 +55,5 @@ If you cannot complete the task:
 - Do NOT open a PR.
 - Do NOT modify `.cloverleaf/` — state transitions are the skill's job.
 - Do NOT skip tests or write placeholder tests. Every acceptance criterion must be covered by a real, meaningful test.
-- Work within the existing project patterns. If the repo has a tsconfig, package.json scripts, or test conventions, follow them.
+- Work within the existing project patterns. Follow the repo's existing conventions — its configuration, scripts, and test layout.
 - Small, focused commits are preferred but a single well-scoped commit is acceptable for this task.

package/prompts/qa.md

@@ -25,11 +25,11 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 
    Run this as the first executable step before anything else. Session B sessions may inherit an arbitrary `cwd` from the walker harness; this anchors you at the repo root.
 
-1. Set up isolated worktree and prepare its node_modules + standard/dist. The `prep-worktree`
-   helper copies main's `standard/node_modules` and `reference-impl/node_modules` into the
-   worktree and runs the standard build script so the @cloverleaf/standard symlink resolves
-   correctly inside the worktree. (Without this, `tsc` fails with `Cannot find module
-   '@cloverleaf/standard/validators/index.js'` because git worktrees don't inherit node_modules.)
+1. Set up an isolated worktree and prime it so the project's tests can run. The
+   `prep-worktree` helper prepares the worktree's dependencies (for a TypeScript monorepo it
+   copies the built tooling; for other projects it runs the configured `worktree_setup_command`
+   and copies any `prep_copy_dirs`). Without it, a fresh worktree may lack the dependencies the
+   tests need.
    ```bash
    TMPDIR=$(mktemp -d)
    SHA=$(git rev-parse {{branch}})
@@ -50,8 +50,8 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
    - Run it in `"$TMPDIR/<cwd>"`
    - Capture stdout, stderr, exit code
    - Parse test output to extract `passed`, `failed`, `total`:
-     - Vitest: `Tests  N passed | M failed (T)` or similar
-     - npm build: treat exit 0 as `{passed: 1, failed: 0, total: 1}`, non-zero as `{passed: 0, failed: 1, total: 1}`
+     - Exit code is the universal signal: exit 0 = the command's checks passed; non-zero = failed.
+     - When the output format is recognized, also extract counts, e.g. Vitest (`Tests N passed | M failed`), pytest (`N passed, M failed`), or a plain build/lint (exit 0 → `{passed: 1, failed: 0, total: 1}`).
    - On failure, collect up to 10 failure names/messages as findings with `severity: "error"` and `rule: "qa.<suite>.<test-name>"`
 
 5. Aggregate results: sum `passed`, `failed`, `total` across all runs.
@@ -59,7 +59,7 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 6. Compute verdict:
    - `pass` — every command exited 0 AND aggregated `failed === 0`
    - `bounce` — any command exited non-zero OR `failed > 0`; findings list the first ~10 failures
-   - `escalate` — any command failed deterministically on 3 consecutive retries (attempt the rerun yourself), OR `npm ci` itself failed (infrastructure problem)
+   - `escalate` — any command failed deterministically on 3 consecutive retries (attempt the rerun yourself), OR the worktree setup itself failed (infrastructure problem)
 
 7. Teardown:
    ```bash
@@ -72,17 +72,25 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 - Read-only. Do NOT edit source files.
 - Use `git worktree`: do NOT `git checkout` in the main working directory.
 - Always teardown the worktree, even on error.
-- **Loading or running a module directly.** Do not improvise `node -e "import('./lib/x.js')"` to spot-check a module — sources are `.ts` and the build emits `.mjs`, so a bare `.js` import resolves to neither and fails with `ERR_MODULE_NOT_FOUND`. Use `npx tsx` instead (already in the worktree's `node_modules`): it resolves `.ts` sources **and** the project's `.js`-style import specifiers, so the natural import works. Run it from the worktree's `reference-impl/` directory; for anything the test suite already covers, prefer `npm test`.
+- **Loading or running a module directly (TypeScript projects).** If your project is TypeScript, do not improvise `node -e "import('./lib/x.js')"` to spot-check a module — sources are `.ts` and the build emits `.mjs`, so a bare `.js` import resolves to neither. Use `npx tsx` instead (resolves `.ts` sources and `.js`-style import specifiers):
 
   ```bash
   npx tsx -e "import('./lib/<module>.js').then(m => console.log(Object.keys(m)))"
   ```
 
+  For other ecosystems, use your language's module-load or REPL equivalent. For anything the test suite already covers, prefer running the tests.
+
 ## QA Report (v0.4)
 
 After executing all matched QA rules, write an HTML report summarizing each run to `<repoRoot>/.cloverleaf/runs/{taskId}/qa/report.html` (substitute `{taskId}` with the `id` field from the task input, e.g., `{{task.id}}`).
 
-Use `renderQaReport(runs)` from `lib/qa-report.ts` to produce the HTML. The compiled artifact is at `<repoRoot>/reference-impl/dist/qa-report.mjs` — invoke via `node --input-type=module` or import from there. Ensure the output directory exists first (`mkdir -p`).
+Write the runs array (one `{ruleId, command, cwd, durationMs, passed, stdoutTail, stderrTail}` object per executed command) to a temp JSON file, then generate the report via the CLI:
+
+```bash
+cloverleaf-cli qa-report /tmp/cl-qa-runs-{taskId}.json "<repoRoot>/.cloverleaf/runs/{taskId}/qa/report.html"
+```
+
+The CLI creates the output directory.
 
 In the feedback you emit, include the report as an attachment on a single info-level finding (or on whichever summary finding you already emit):
 

package/prompts/reviewer.md

@@ -8,6 +8,7 @@ You are the Cloverleaf Reviewer agent. Your job: perform a fresh-eyes review of
 - `branch`: the branch name the Implementer produced (e.g., `cloverleaf/DEMO-001`).
 - `base_branch`: the branch to diff against (default: `main`).
 - `repo_root`: absolute path to the consumer repo.
+- `test_rules`: a JSON object `{ rules: [...] }` whose `rules` is a list of `{cwd, match, command}` entries (from `qa-rules.json`).
 
 ## Your process
 
@@ -49,15 +50,16 @@ A `pass` verdict MAY have an empty `findings` array or omit it. A `bounce` verdi
 - You are a fresh pair of eyes. Do not rubber-stamp. If you have substantive doubts, bounce.
 - Check that tests actually cover the AC; a passing test suite with no AC coverage is a bounce.
 - Do NOT modify any files. You are read-only.
-- Do NOT use `git checkout` or `git switch`. Read files via `git show <branch>:<path>`. If you need a live checkout to run tests, use a worktree and prime it with `cloverleaf-cli prep-worktree` (copies main's node_modules + builds standard/dist inside the worktree — without this, `tsc` fails with `Cannot find module '@cloverleaf/standard/validators/index.js'`):
+- Do NOT use `git checkout` or `git switch`. Read files via `git show <branch>:<path>`. If you need a live checkout to run tests, use a worktree and prime it with `cloverleaf-cli prep-worktree` (prepares the worktree so the project's tests can run):
 
   ```bash
   MAIN=$(pwd)
   SHA=$(git rev-parse cloverleaf/<task-id>)
   git worktree add --detach /tmp/cl-review-<task-id> "$SHA"
   cloverleaf-cli prep-worktree "$MAIN" /tmp/cl-review-<task-id>
-  cd /tmp/cl-review-<task-id>/reference-impl
-  npm test
+  # Run the project's tests. Your rules are in {{test_rules}} (JSON object { rules: [{cwd, match, command}, ...] }).
+  # For each rule whose match globs cover a changed file, run its command in
+  # /tmp/cl-review-<task-id>/<cwd>.
   cd -
   git worktree remove /tmp/cl-review-<task-id>
   ```
@@ -65,10 +67,12 @@ A `pass` verdict MAY have an empty `findings` array or omit it. A `bounce` verdi
   Use `--detach` with a SHA rather than a branch name: when running inside a walker worktree, the feature branch (and main) may already be checked out in another worktree, causing `git worktree add` to fail with "fatal: branch … is already checked out". Detaching at a SHA bypasses this constraint entirely.
 
   This keeps `.cloverleaf/` on main intact.
-- **Loading or running a module directly.** Do not improvise `node -e "import('./lib/x.js')"` to spot-check a module — sources are `.ts` and the build emits `.mjs`, so a bare `.js` import resolves to neither and fails with `ERR_MODULE_NOT_FOUND`. Use `npx tsx` instead (already in the worktree's `node_modules`): it resolves `.ts` sources **and** the project's `.js`-style import specifiers, so the natural import works. Run it from the worktree's `reference-impl/` directory; for anything the test suite already covers, prefer `npm test`.
+- **Loading or running a module directly (TypeScript projects).** If your project is TypeScript, do not improvise `node -e "import('./lib/x.js')"` to spot-check a module — sources are `.ts` and the build emits `.mjs`, so a bare `.js` import resolves to neither. Use `npx tsx` instead (resolves `.ts` sources and `.js`-style import specifiers):
 
   ```bash
   npx tsx -e "import('./lib/<module>.js').then(m => console.log(Object.keys(m)))"
   ```
+
+  For other ecosystems, use your language's module-load or REPL equivalent. For anything the test suite already covers, prefer running the tests.
 - Severities (per the Cloverleaf feedback schema): `blocker` = wrong behavior / missing AC / broken tests; `error` = notable defect that should be fixed but doesn't break AC; `warning` = should fix; `info` = nit / style. Use `blocker` and `error` for bounces.
 - If a criterion is subjective, lean toward pass — the task author chose those words deliberately.

package/skills/cloverleaf-implement/SKILL.md

@@ -23,6 +23,16 @@ The user has invoked this skill with a TASK-ID (e.g., `DEMO-001`).
    ```
    Capture the output. If present and the latest verdict is `bounce`, pass it into the subagent.
 
+3b. Load the project's test rules (consumer override or shipped default):
+   ```bash
+   if [ -f "<repo_root>/.cloverleaf/config/qa-rules.json" ]; then
+     cat "<repo_root>/.cloverleaf/config/qa-rules.json"
+   else
+     cat "$(cloverleaf-cli plugin-root)/config/qa-rules.json"
+   fi
+   ```
+   Capture the output as `test_rules`.
+
 4. Dispatch the Implementer subagent via the Task tool:
    - `subagent_type`: `general-purpose`
    - `model`: `sonnet`
@@ -31,6 +41,7 @@ The user has invoked this skill with a TASK-ID (e.g., `DEMO-001`).
      - `{{feedback}}` → the feedback JSON if present, else the literal string `null`
      - `{{repo_root}}` → absolute path to the current repo
      - `{{base_branch}}` → `main` (or the current default branch)
+     - `{{test_rules}}` → the test rules JSON captured in step 3b
 
    **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
 

package/skills/cloverleaf-review/SKILL.md

@@ -37,10 +37,20 @@ description: Run the Reviewer agent on a task in the `review` state. Emits a fee
    ```
    Capture this output for the subagent.
 
+4b. Load the project's test rules (consumer override or shipped default):
+   ```bash
+   if [ -f "<repo_root>/.cloverleaf/config/qa-rules.json" ]; then
+     cat "<repo_root>/.cloverleaf/config/qa-rules.json"
+   else
+     cat "$(cloverleaf-cli plugin-root)/config/qa-rules.json"
+   fi
+   ```
+   Capture the output as `test_rules`.
+
 5. Dispatch the Reviewer subagent via the Task tool:
    - `subagent_type`: `general-purpose`
    - `model`: `sonnet`
-   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/reviewer.md` with substitutions for `{{task}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{diff}}`.
+   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/reviewer.md` with substitutions for `{{task}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{diff}}`, `{{test_rules}}`.
 
    **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.