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

package/VERSION

@@ -1 +1 @@
-0.8.6
+0.10.0

package/config/council.json

@@ -0,0 +1,19 @@
+{
+  "profiles": {
+    "default": {
+      "rounds": [
+        [ { "member": "reviewer" } ],
+        [
+          { "member": "security", "when": "security_class:high" },
+          { "member": "ui", "when": "ui_changes" },
+          { "member": "qa" }
+        ]
+      ],
+      "aggregation": "any-veto",
+      "on_round_bounce": "stop"
+    }
+  },
+  "gates": {
+    "task.review": "default"
+  }
+}

package/config/discovery.json

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

package/dist/aggregation.mjs

@@ -0,0 +1,60 @@
+export function aggregate(members, rule, opts = {}) {
+    // Safety invariant: any member that escalates short-circuits, regardless of
+    // blocking flag or rule — a hard blocker cannot be out-voted.
+    const escalators = members.filter((x) => x.verdict === 'escalate');
+    if (escalators.length > 0) {
+        return {
+            verdict: 'escalate',
+            rule,
+            members,
+            rationale: `escalated by ${escalators.map((x) => x.member).join(', ')}`,
+        };
+    }
+    // Only blocking members gate the pass/bounce decision.
+    const blocking = members.filter((x) => x.blocking !== false);
+    if (blocking.length === 0) {
+        return { verdict: 'pass', rule, members, rationale: 'no blocking members' };
+    }
+    const passes = blocking.filter((x) => x.verdict === 'pass');
+    const passCount = passes.length;
+    const total = blocking.length;
+    let pass;
+    let detail;
+    if (rule === 'any-veto') {
+        pass = passCount === total;
+        detail = `any-veto: ${passCount}/${total} passed`;
+    }
+    else if (rule === 'unanimous') {
+        // Currently identical to any-veto over blocking members. Kept as a distinct
+        // named rule for clarity and possible future divergence; do not merge.
+        pass = passCount === total;
+        detail = `unanimous: ${passCount}/${total} passed`;
+    }
+    else if (rule === 'majority') {
+        pass = passCount * 2 > total; // strict majority; ties → bounce
+        detail = `majority: ${passCount}/${total} passed`;
+    }
+    else if (rule === 'weighted') {
+        const totalWeight = blocking.reduce((s, x) => s + (x.weight ?? 1), 0);
+        const passWeight = passes.reduce((s, x) => s + (x.weight ?? 1), 0);
+        const threshold = opts.weightedThreshold;
+        pass = threshold !== undefined ? passWeight >= threshold : passWeight * 2 > totalWeight;
+        detail =
+            `weighted: passWeight ${passWeight}/${totalWeight}` +
+                (threshold !== undefined ? ` (threshold ${threshold})` : '');
+    }
+    else if (typeof rule === 'object' && rule !== null && 'quorum' in rule) {
+        const k = rule.quorum;
+        pass = passCount >= k;
+        detail = `quorum(${k}): ${passCount}/${total} passed`;
+    }
+    else {
+        throw new Error(`aggregate: unknown aggregation rule ${JSON.stringify(rule)}`);
+    }
+    return {
+        verdict: pass ? 'pass' : 'bounce',
+        rule,
+        members,
+        rationale: `${pass ? 'pass' : 'bounce'} — ${detail}`,
+    };
+}

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>
@@ -41,6 +42,9 @@
  *   secret-scan <repoRoot> --branch <branch>
  *   classify-security <repoRoot> <taskId> [--branch <branch>]
  *   set-task-field <repoRoot> <taskId> <field> <value>
+ *   council-plan <repoRoot> <taskId> [gateKey] [--changed-files=a,b,c]
+ *   aggregate-verdicts <membersJson> <rule> [--weighted-threshold=N]
+ *   apply-council-verdict <repoRoot> <taskId> <gate> <councilVerdictJson>
  */
 import { readFileSync, mkdirSync, copyFileSync, appendFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -61,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';
@@ -70,6 +75,8 @@ import { classifyFiles, normalizePath } from './scope-check.mjs';
 import { computeRfcTasksView } from './rfc-tasks.mjs';
 import { loadSecretPatternsConfig, scanSecrets } from './secret-scan.mjs';
 import { classifyTaskSecurity } from './security-classify.mjs';
+import { resolveCouncilPlan, applyCouncilVerdict } from './council.mjs';
+import { aggregate } from './aggregation.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -105,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' +
@@ -114,6 +122,9 @@ function usage(msg) {
         '  extend-scope <repoRoot> <taskId> --add <file>... --reason <text>\n' +
         '  secret-scan <repoRoot> --branch <branch>\n' +
         '  classify-security <repoRoot> <taskId> [--branch <branch>]\n' +
+        '  council-plan <repoRoot> <taskId> [gateKey] [--changed-files=a,b,c]\n' +
+        '  aggregate-verdicts <membersJson> <rule> [--weighted-threshold=N]\n' +
+        '  apply-council-verdict <repoRoot> <taskId> <gate> <councilVerdictJson>\n' +
         '  set-task-field <repoRoot> <taskId> <field> <value>\n');
     process.exit(2);
 }
@@ -485,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)
@@ -796,6 +814,52 @@ try {
             process.stdout.write(JSON.stringify(result) + '\n');
             break;
         }
+        case 'council-plan': {
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [repoRoot, taskId, gateKey] = positional;
+            if (!repoRoot || !taskId)
+                usage('council-plan requires <repoRoot> <taskId> [gateKey]');
+            const cf = flags.find((f) => f.startsWith('--changed-files='));
+            const changedFiles = cf !== undefined
+                ? cf.replace('--changed-files=', '').split(',').filter(Boolean)
+                : undefined;
+            const plan = resolveCouncilPlan(repoRoot, taskId, gateKey || 'task.review', changedFiles !== undefined ? { changedFiles } : {});
+            process.stdout.write(JSON.stringify(plan) + '\n');
+            break;
+        }
+        case 'aggregate-verdicts': {
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const [membersJson, ruleArg] = positional;
+            if (!membersJson || !ruleArg)
+                usage('aggregate-verdicts requires <membersJson> <rule>');
+            const members = JSON.parse(membersJson);
+            let rule;
+            if (ruleArg.startsWith('quorum:')) {
+                const quorumN = parseInt(ruleArg.split(':')[1], 10);
+                if (Number.isNaN(quorumN) || quorumN < 1) {
+                    usage(`aggregate-verdicts: quorum value must be a positive integer, got '${ruleArg}'`);
+                }
+                rule = { quorum: quorumN };
+            }
+            else {
+                rule = ruleArg;
+            }
+            const wt = flags.find((f) => f.startsWith('--weighted-threshold='));
+            const opts = wt ? { weightedThreshold: parseFloat(wt.replace('--weighted-threshold=', '')) } : {};
+            process.stdout.write(JSON.stringify(aggregate(members, rule, opts)) + '\n');
+            break;
+        }
+        case 'apply-council-verdict': {
+            const [repoRoot, taskId, gate, verdictJson] = rest;
+            if (!repoRoot || !taskId || !gate || !verdictJson)
+                usage('apply-council-verdict requires <repoRoot> <taskId> <gate> <councilVerdictJson>');
+            const council = JSON.parse(verdictJson);
+            const result = applyCouncilVerdict(repoRoot, taskId, gate, council);
+            process.stdout.write(JSON.stringify(result) + '\n');
+            break;
+        }
         case 'set-task-field': {
             const [repoRoot, taskId, field, value] = rest;
             if (!repoRoot || !taskId || !field || value === undefined)

package/dist/council-config.mjs

@@ -0,0 +1,47 @@
+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 DEFAULT_CONFIG = join(here, '..', 'config', 'council.json');
+function isObject(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+// Full-replacement (not merge): a consumer council.json wholly replaces the
+// shipped default — matching the qa-rules / security-paths loaders. A partial
+// consumer file (e.g. only `profiles`) intentionally yields empty `gates`,
+// i.e. no bound gates → today's behavior. Per-profile shape validation is a
+// later (validator) slice; this loader normalizes only the top-level containers.
+function normalize(doc) {
+    return {
+        profiles: isObject(doc.profiles) ? doc.profiles : {},
+        gates: isObject(doc.gates) ? doc.gates : {},
+    };
+}
+function loadDefaultConfig() {
+    if (!existsSync(DEFAULT_CONFIG)) {
+        throw new Error(`council config not found at ${DEFAULT_CONFIG}`);
+    }
+    const parsed = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));
+    if (!isObject(parsed)) {
+        throw new Error(`council config malformed (not an object) at ${DEFAULT_CONFIG}`);
+    }
+    return normalize(parsed);
+}
+export function loadCouncilConfigWithSource(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'council.json');
+    if (existsSync(consumerPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(consumerPath, 'utf-8'));
+            if (!isObject(parsed))
+                throw new Error('council.json is not an object');
+            return { config: normalize(parsed), source: 'consumer' };
+        }
+        catch {
+            // malformed / non-object consumer config → fall back to package default
+        }
+    }
+    return { config: loadDefaultConfig(), source: 'default' };
+}
+export function loadCouncilConfig(repoRoot) {
+    return loadCouncilConfigWithSource(repoRoot).config;
+}

package/dist/council-result.mjs

@@ -0,0 +1,19 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { councilRunDir } from './paths.mjs';
+export function councilResultPath(repoRoot, taskId, gate) {
+    return join(councilRunDir(repoRoot, taskId), `${gate}.json`);
+}
+export function writeCouncilResult(repoRoot, taskId, result) {
+    const dir = councilRunDir(repoRoot, taskId);
+    mkdirSync(dir, { recursive: true });
+    const path = councilResultPath(repoRoot, taskId, result.gate);
+    writeFileSync(path, JSON.stringify(result, null, 2) + '\n');
+    return path;
+}
+export function readCouncilResult(repoRoot, taskId, gate) {
+    const path = councilResultPath(repoRoot, taskId, gate);
+    if (!existsSync(path))
+        return null;
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}

package/dist/council.mjs

@@ -0,0 +1,159 @@
+import { execFileSync } from 'node:child_process';
+import { loadCouncilConfigWithSource } from './council-config.mjs';
+import { loadTask, saveTask, advanceStatus } from './task.mjs';
+import { writeCouncilResult } from './council-result.mjs';
+import { classifyTaskSecurity } from './security-classify.mjs';
+import { loadAffectedRoutesConfig, computeAffectedRoutes } from './affected-routes.mjs';
+export function evaluateWhen(predicate, ctx) {
+    switch (predicate) {
+        case undefined:
+        case 'always':
+            return true;
+        case 'security_class:high':
+            return ctx.securityHigh;
+        case 'ui_changes':
+            return ctx.uiChanges;
+        default:
+            return false; // unknown predicate → inactive (fail-closed)
+    }
+}
+export function resolveBinding(binding, task) {
+    if (binding === undefined)
+        return { profile: null, mode: 'decisive' };
+    if (typeof binding === 'string')
+        return { profile: binding, mode: 'decisive' };
+    if ('profile' in binding)
+        return { profile: binding.profile, mode: binding.mode ?? 'decisive' };
+    // conditional selector { by, map }
+    const key = String(task[binding.by] ?? '');
+    const selected = key in binding.map ? binding.map[key] : (binding.map['*'] ?? null);
+    return { profile: selected, mode: 'decisive' };
+}
+/**
+ * Resolve changed files for predicate evaluation. Callers should pass
+ * `opts.changedFiles` (e.g. from a prior `git diff`); when omitted we run
+ * `git diff main..cloverleaf/<taskId>` and fall back to [] on any git error.
+ * Exported for direct testing of the (now orchestrator-live) git path.
+ */
+export function resolveChangedFiles(repoRoot, taskId, opts = {}) {
+    if (opts.changedFiles !== undefined)
+        return opts.changedFiles;
+    try {
+        const out = execFileSync('git', ['-C', repoRoot, 'diff', '--name-only', `main..cloverleaf/${taskId}`], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        return out.split('\n').filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export function resolveCouncilPlan(repoRoot, taskId, gateKey = 'task.review', opts = {}) {
+    const { config, source } = loadCouncilConfigWithSource(repoRoot);
+    const task = loadTask(repoRoot, taskId);
+    const { profile: profileName, mode } = resolveBinding(config.gates[gateKey], task);
+    const empty = {
+        gate: gateKey, profile: null, mode, rounds: [],
+        aggregation: 'any-veto', on_round_bounce: 'stop', source,
+    };
+    if (profileName === null)
+        return empty;
+    const profile = config.profiles[profileName];
+    if (!profile) {
+        if (source === 'consumer') {
+            process.stderr.write(`cloverleaf-cli council-plan: profile '${profileName}' bound to gate '${gateKey}' not found in council.json; falling back to today's behavior.\n`);
+        }
+        return empty; // unknown profile → fail toward today's behavior
+    }
+    const changed = resolveChangedFiles(repoRoot, taskId, opts);
+    const securityHigh = classifyTaskSecurity(repoRoot, taskId, { changedFiles: changed }).effective === 'high';
+    const affected = computeAffectedRoutes(changed, loadAffectedRoutesConfig(repoRoot));
+    const uiChanges = affected === 'all' || affected.length > 0;
+    const ctx = { securityHigh, uiChanges };
+    const rounds = [];
+    for (const round of profile.rounds) {
+        const active = round
+            .filter((member) => evaluateWhen(member.when, ctx))
+            .map((member) => ({ member: member.member, blocking: member.blocking !== false, weight: member.weight ?? 1 }));
+        if (active.length > 0)
+            rounds.push(active);
+    }
+    return {
+        gate: gateKey,
+        profile: profileName,
+        mode,
+        rounds,
+        aggregation: profile.aggregation,
+        on_round_bounce: profile.on_round_bounce ?? 'stop',
+        source,
+    };
+}
+/**
+ * Drive the FSM transition implied by a council verdict (the runner's terminal step).
+ * Council-authoritative: on a pass it records the council's gating verdict so the
+ * v0.8.1 security precondition is satisfied for any high-security gated transition;
+ * the per-member basis (incl. an omitted or out-voted `security` member) is written
+ * to the result artifact. Walks the minimal legal path to the lane's pre-merge state.
+ */
+export function applyCouncilVerdict(repoRoot, taskId, gate, council) {
+    if (gate !== 'task.review') {
+        throw new Error(`apply-council-verdict: gate '${gate}' is not supported yet — the FSM walk is hardcoded for the ` +
+            `task.review → merge lane. Binding other gates needs a gate-aware walk (council Slice 3).`);
+    }
+    const task = loadTask(repoRoot, taskId);
+    if (task.status !== 'review') {
+        throw new Error(`apply-council-verdict: task ${taskId} is '${task.status}', expected 'review'`);
+    }
+    const lane = task.risk_class === 'high' ? 'full' : 'fast';
+    const securityMember = council.members.find((m) => m.member === 'security');
+    const walk = ['review'];
+    if (council.verdict === 'escalate') {
+        advanceStatus(repoRoot, taskId, 'escalated', 'agent');
+        walk.push('escalated');
+    }
+    else if (council.verdict === 'bounce') {
+        advanceStatus(repoRoot, taskId, 'implementing', 'agent');
+        walk.push('implementing');
+    }
+    else {
+        // pass — minimal legal walk; review→automated-gates resets the security verdict,
+        // so set the council's gating verdict AFTER that transition.
+        advanceStatus(repoRoot, taskId, 'automated-gates', 'agent');
+        walk.push('automated-gates');
+        const atGates = loadTask(repoRoot, taskId);
+        atGates.security_review_verdict = 'pass';
+        saveTask(repoRoot, atGates);
+        if (lane === 'full') {
+            advanceStatus(repoRoot, taskId, 'qa', 'agent', { path: 'full_pipeline' });
+            walk.push('qa');
+            advanceStatus(repoRoot, taskId, 'final-gate', 'agent', { path: 'full_pipeline' });
+            walk.push('final-gate');
+        }
+    }
+    const qaTraversedAdministratively = lane === 'full' && walk.includes('qa') && !council.members.some((m) => m.member === 'qa');
+    const result = {
+        gate,
+        final_verdict: council.verdict,
+        rule: council.rule,
+        rationale: council.rationale,
+        members: council.members.map((m) => ({
+            member: m.member,
+            verdict: m.verdict,
+            blocking: m.blocking !== false,
+            weight: m.weight ?? 1,
+        })),
+        walk,
+        ...(qaTraversedAdministratively
+            ? { walk_note: 'qa state traversed administratively; no qa member ran' }
+            : {}),
+        security: {
+            member_verdict: securityMember ? securityMember.verdict : 'absent',
+            gating_verdict_set: council.verdict === 'pass' ? 'pass' : null,
+            basis: !securityMember
+                ? 'no security member configured; advanced under council authority'
+                : securityMember.verdict === 'pass'
+                    ? 'security member passed'
+                    : `security member returned '${securityMember.verdict}'; council ${council.verdict} by rule ${JSON.stringify(council.rule)}`,
+        },
+    };
+    writeCouncilResult(repoRoot, taskId, result);
+    return result;
+}

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/paths.mjs

@@ -30,3 +30,6 @@ export function runsDir(repoRoot) {
 export function uiReviewRunDir(repoRoot, taskId) {
     return resolve(runsDir(repoRoot), taskId, 'ui-review');
 }
+export function councilRunDir(repoRoot, taskId) {
+    return resolve(runsDir(repoRoot), taskId, 'council');
+}

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;