@cloverleaf/reference-impl 0.8.5 → 0.9.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.9.0",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

package/VERSION

@@ -1 +1 @@
-0.8.5
+0.9.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/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

@@ -41,6 +41,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';
@@ -70,6 +73,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);
@@ -114,6 +119,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);
 }
@@ -796,6 +804,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/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/lib/aggregation.ts

@@ -0,0 +1,87 @@
+import type { Verdict } from './feedback.js';
+
+export type ThresholdRule =
+  | 'any-veto'
+  | 'unanimous'
+  | 'majority'
+  | 'weighted'
+  | { quorum: number };
+
+export interface MemberVerdict {
+  member: string;
+  verdict: Verdict; // 'pass' | 'bounce' | 'escalate'
+  blocking?: boolean; // default true; advisory members (false) don't gate
+  weight?: number; // default 1; only used by 'weighted'
+}
+
+export interface CouncilVerdict {
+  verdict: Verdict;
+  rule: ThresholdRule;
+  rationale: string;
+  members: MemberVerdict[];
+}
+
+export function aggregate(
+  members: MemberVerdict[],
+  rule: ThresholdRule,
+  opts: { weightedThreshold?: number } = {},
+): CouncilVerdict {
+  // 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: boolean;
+  let detail: string;
+
+  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/lib/cli.ts

@@ -41,6 +41,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, existsSync } from 'node:fs';
@@ -73,6 +76,8 @@ import type { SiblingScope } from './scope-check.js';
 import { computeRfcTasksView, type RfcTasksView } from './rfc-tasks.js';
 import { loadSecretPatternsConfig, scanSecrets } from './secret-scan.js';
 import { classifyTaskSecurity } from './security-classify.js';
+import { resolveCouncilPlan, applyCouncilVerdict } from './council.js';
+import { aggregate, type MemberVerdict, type ThresholdRule, type CouncilVerdict } from './aggregation.js';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(msg + '\n');
@@ -119,6 +124,9 @@ function usage(msg?: string): never {
       '  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);
@@ -817,6 +825,55 @@ try {
       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) as MemberVerdict[];
+      let rule: ThresholdRule;
+      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 as ThresholdRule;
+      }
+      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) as CouncilVerdict;
+      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/lib/council-config.ts

@@ -0,0 +1,79 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import type { ThresholdRule } from './aggregation.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG = join(here, '..', 'config', 'council.json');
+
+export type WhenPredicate = 'always' | 'security_class:high' | 'ui_changes';
+
+export interface CouncilMember {
+  member: string; // built-in id: 'reviewer' | 'security' | 'ui' | 'qa'
+  when?: WhenPredicate; // default 'always'
+  blocking?: boolean; // default true
+  weight?: number; // default 1
+}
+
+export interface CouncilProfile {
+  rounds: CouncilMember[][];
+  aggregation: ThresholdRule;
+  on_round_bounce?: 'stop' | 'continue'; // default 'stop'
+}
+
+export type GateBinding =
+  | string
+  | { profile: string; mode?: 'decisive' | 'advisory' }
+  | { by: string; map: Record<string, string | null> };
+
+export interface CouncilConfig {
+  profiles: Record<string, CouncilProfile>;
+  gates: Record<string, GateBinding>;
+}
+
+function isObject(x: unknown): x is Record<string, unknown> {
+  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: Record<string, unknown>): CouncilConfig {
+  return {
+    profiles: isObject(doc.profiles) ? (doc.profiles as Record<string, CouncilProfile>) : {},
+    gates: isObject(doc.gates) ? (doc.gates as Record<string, GateBinding>) : {},
+  };
+}
+
+function loadDefaultConfig(): CouncilConfig {
+  if (!existsSync(DEFAULT_CONFIG)) {
+    throw new Error(`council config not found at ${DEFAULT_CONFIG}`);
+  }
+  const parsed: unknown = 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: string,
+): { config: CouncilConfig; source: 'consumer' | 'default' } {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'council.json');
+  if (existsSync(consumerPath)) {
+    try {
+      const parsed: unknown = 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: string): CouncilConfig {
+  return loadCouncilConfigWithSource(repoRoot).config;
+}

package/lib/council-result.ts

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { councilRunDir } from './paths.js';
+import type { Verdict } from './feedback.js';
+import type { ThresholdRule } from './aggregation.js';
+
+export interface CouncilResultMember {
+  member: string;
+  verdict: Verdict;
+  blocking: boolean;
+  weight: number;
+}
+
+export interface CouncilResult {
+  gate: string;
+  final_verdict: Verdict;
+  rule: ThresholdRule;
+  rationale: string;
+  members: CouncilResultMember[];
+  walk: string[]; // states walked, e.g. ["review","automated-gates","qa","final-gate"]
+  walk_note?: string; // set when a state was traversed administratively (e.g. qa with no qa member)
+  security: {
+    member_verdict: Verdict | 'absent';
+    gating_verdict_set: 'pass' | null; // security_review_verdict the council set, if any
+    basis: string; // human-readable explanation of the security decision
+  };
+}
+
+export function councilResultPath(repoRoot: string, taskId: string, gate: string): string {
+  return join(councilRunDir(repoRoot, taskId), `${gate}.json`);
+}
+
+export function writeCouncilResult(repoRoot: string, taskId: string, result: CouncilResult): string {
+  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: string, taskId: string, gate: string): CouncilResult | null {
+  const path = councilResultPath(repoRoot, taskId, gate);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf-8')) as CouncilResult;
+}

package/lib/council.ts

@@ -0,0 +1,203 @@
+import { execFileSync } from 'node:child_process';
+import { loadCouncilConfigWithSource, type CouncilConfig, type GateBinding, type WhenPredicate } from './council-config.js';
+import type { ThresholdRule, CouncilVerdict } from './aggregation.js';
+import { loadTask, saveTask, advanceStatus } from './task.js';
+import { writeCouncilResult, type CouncilResult } from './council-result.js';
+import { classifyTaskSecurity } from './security-classify.js';
+import { loadAffectedRoutesConfig, computeAffectedRoutes } from './affected-routes.js';
+
+export interface ResolvedMember {
+  member: string;
+  blocking: boolean;
+  weight: number;
+}
+
+export interface CouncilPlan {
+  gate: string;
+  profile: string | null; // null → no council bound (today's behavior)
+  mode: 'decisive' | 'advisory';
+  rounds: ResolvedMember[][];
+  aggregation: ThresholdRule;
+  on_round_bounce: 'stop' | 'continue';
+  source: 'consumer' | 'default';
+}
+
+interface WhenContext {
+  securityHigh: boolean;
+  uiChanges: boolean;
+}
+
+export function evaluateWhen(predicate: WhenPredicate | undefined, ctx: WhenContext): boolean {
+  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: GateBinding | undefined,
+  task: Record<string, unknown>,
+): { profile: string | null; mode: 'decisive' | 'advisory' } {
+  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: string, taskId: string, opts: { changedFiles?: string[] } = {}): string[] {
+  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: string,
+  taskId: string,
+  gateKey = 'task.review',
+  opts: { changedFiles?: string[] } = {},
+): CouncilPlan {
+  const { config, source } = loadCouncilConfigWithSource(repoRoot);
+  const task = loadTask(repoRoot, taskId) as unknown as Record<string, unknown>;
+
+  const { profile: profileName, mode } = resolveBinding(config.gates[gateKey], task);
+  const empty: CouncilPlan = {
+    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: WhenContext = { securityHigh, uiChanges };
+
+  const rounds: ResolvedMember[][] = [];
+  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: string,
+  taskId: string,
+  gate: string,
+  council: CouncilVerdict,
+): CouncilResult {
+  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: 'fast' | 'full' = task.risk_class === 'high' ? 'full' : 'fast';
+  const securityMember = council.members.find((m) => m.member === 'security');
+  const walk: string[] = ['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: CouncilResult = {
+    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/lib/paths.ts

@@ -41,3 +41,7 @@ export function runsDir(repoRoot: string): string {
 export function uiReviewRunDir(repoRoot: string, taskId: string): string {
   return resolve(runsDir(repoRoot), taskId, 'ui-review');
 }
+
+export function councilRunDir(repoRoot: string, taskId: string): string {
+  return resolve(runsDir(repoRoot), taskId, 'council');
+}

package/package.json

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

package/prompts/ui-reviewer.md

@@ -92,7 +92,7 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
    SERVER_PID=$!
    ```
 
-   > **Playwright script placement (Bug #3 fix):** If you need to write a standalone `.mjs` driver script at any point, place it **inside the worktree** (e.g., `$WT/site/playwright-driver.mjs`) and run it from there (`node "$WT/site/playwright-driver.mjs"`). Node's ESM module resolution walks up from the script's own directory — a script placed outside the worktree (where `node_modules/playwright` was installed by `npm ci`) cannot resolve the `playwright` import and will fail.
+   > **Playwright/driver script placement (Bug #3 fix) — applies to EVERY script you write, including retries and ad-hoc fallbacks:** place any standalone `.mjs` driver **inside the worktree** (e.g., `$WT/site/playwright-driver.mjs`) and run it from there (`node "$WT/site/playwright-driver.mjs"`). Node's ESM module resolution walks up from the script's own directory — a script placed anywhere outside the worktree (e.g. `/tmp`) cannot resolve the `playwright` import (or any `node_modules` package) and fails with `ERR_MODULE_NOT_FOUND`. If a driver errors and you retry, fix it in place in `$WT/site/` — never relocate or recreate it under `/tmp`.
 
 4. Wait up to 30s for `http://localhost:{{preview_port}}/` to respond 200. If the server fails to start in 30s, kill it and return verdict `escalate`.
 
@@ -117,6 +117,9 @@ Do not attempt to launch a missing engine — fail fast with `verdict: "escalate
    a. Launch a Playwright browser context using the `browser` engine.
 
    b. **Visual-diff pass (when `visualDiff.enabled` is true):**
+
+      **Visual diffing is ONLY `compareVisual` (pixelmatch). There is no ImageMagick.** Never shell out to `convert`, `compare`, `magick`, or any external image tool to diff or convert images — they are not installed and not a dependency. Screenshot via Playwright (`page.screenshot`) → pass the buffer to `compareVisual` (`lib/visual-diff.ts`). If `compareVisual` is hard to invoke, your driver script failed to resolve — fix the script (see the placement rule), do **not** substitute an external tool.
+
       For each route in the (capped) route list × each viewport in `{{ui_review_config}}.viewports`:
       - Set Playwright viewport to `{ width, height }` from the config.
       - Apply mask CSS — inject a style that sets `visibility: hidden` on any selector in `visualDiff.mask`.

package/skills/cloverleaf-run/SKILL.md

@@ -57,9 +57,11 @@ Recovery sequence:
 
 2. Load task: `cloverleaf-cli load-task <repo_root> <TASK-ID>`. Verify `status === "pending"`. If not, report and stop.
 
-3. Read `task.risk_class`:
-   - `"low"` → go to section 4 (Fast Lane)
-   - `"high"` → go to section 5 (Full Pipeline)
+3. **Council gate detection (opt-in).** Run `cloverleaf-cli council-plan <repo_root> <TASK-ID> task.review` and parse the JSON plan. If `plan.source === "consumer"` **and** `plan.profile !== null`, the project has opted into a configured review council — drive the review phase via **section 7 (Council review path)** instead of the hardcoded reviewer/security/ui/qa steps in sections 4/5. Otherwise (`source: "default"`, or no `task.review` binding) proceed exactly as today:
+   - `task.risk_class === "low"` → section 4 (Fast Lane)
+   - `task.risk_class === "high"` → section 5 (Full Pipeline)
+
+   When the council path is active it still uses the Implementer (and, for the full pipeline, the Documenter) to produce the branch; only the review→merge portion is council-driven.
 
 ### 4. Fast Lane
 
@@ -122,6 +124,35 @@ Loop:
 - Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> escalated (bounce budget exhausted)"`.
 - Report: "✗ Escalated `<TASK-ID>`. Review `.cloverleaf/feedback/` and either refine the task or take over manually. Counters: reviewer=<N>, ui_reviewer=<N>, qa=<N>, security=<N>."
 
+### 7. Council review path (opt-in; active when council-plan source is "consumer")
+
+Initialize `council_bounces = 0`.
+
+7.1 **Produce the branch.** Run the Implementer (`/cloverleaf-implement <TASK-ID>` steps); for `risk_class: "high"` also run the Documenter (`/cloverleaf-document <TASK-ID>` steps). The task reaches `review`.
+
+7.2 **Run the council members (verdict-only).** Re-run `cloverleaf-cli council-plan <repo_root> <TASK-ID> task.review` to get `plan.rounds`, `plan.aggregation`, `plan.on_round_bounce`. For each round **in order**, for each member in the round, dispatch the member's prompt as a **read-only** subagent and capture its `{verdict, summary, findings}` envelope — do **not** advance state:
+   - `reviewer` → `prompts/reviewer.md`, feedback prefix `r`
+   - `security` → `prompts/security-reviewer.md`, prefix `s`
+   - `ui` → `prompts/ui-reviewer.md`, prefix `u`
+   - `qa` → `prompts/qa.md`, prefix `q`
+
+   **Dispatch conventions:** invoke the Task tool in foreground (default — never `run_in_background`); do not poll with foreground `sleep`. Substitute `{{task}}`, `{{branch}}` (`cloverleaf/<TASK-ID>`), `{{base_branch}}` (`main`), `{{repo_root}}`, `{{diff}}` (`git diff main..cloverleaf/<TASK-ID> -- ':(exclude).cloverleaf/'`).
+
+   Persist each member's envelope: `echo '<envelope>' > /tmp/clv-council-<member>.json && cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/clv-council-<member>.json --prefix=<r|s|u|q>`. Collect a members array `[{ "member": "<id>", "verdict": "<pass|bounce|escalate>", "blocking": <plan member blocking>, "weight": <plan member weight> }]`.
+
+   **Short-circuit:** if any member returns `escalate`, stop immediately. Otherwise, after each round, if `plan.on_round_bounce === "stop"` and any **blocking** member in that round returned `bounce`, stop before the next round. Always finish the members already running in the current round (batched).
+
+7.3 **Aggregate.** Map `plan.aggregation` to the CLI rule argument: a string passes through; `{ "quorum": k }` → `quorum:k`. Run `cloverleaf-cli aggregate-verdicts '<members-json>' <rule>` and capture the council verdict JSON.
+
+7.4 **Apply.** Run `cloverleaf-cli apply-council-verdict <repo_root> <TASK-ID> task.review '<council-verdict-json>'`. The FSM walk may self-commit some transitions (e.g. `security_class → high`, the rework verdict-reset), so the wrap-up commit can find nothing staged — that is expected. Commit the remainder: `git add .cloverleaf/ && (git diff --cached --quiet || git commit -m "cloverleaf: <TASK-ID> council review (<verdict>)")`.
+
+7.5 **Branch on the task's new status (reload with `load-task`):**
+   - `automated-gates` (fast lane pass) or `final-gate` (full pipeline pass) → proceed to the merge: inline `/cloverleaf-merge <TASK-ID>`.
+   - `implementing` (bounce) → `council_bounces += 1`. If `council_bounces >= 3`, escalate (section 6). Else return to 7.1.
+   - `escalated` → stop and surface to the user (review `.cloverleaf/feedback/` and `.cloverleaf/runs/<TASK-ID>/council/task.review.json`).
+
+The council result artifact at `.cloverleaf/runs/<TASK-ID>/council/task.review.json` records per-member verdicts, the aggregate, and the security basis (incl. an omitted or out-voted `security` member). On any member-dispatch failure or unparseable envelope, stop and report — never treat a failed member as a pass.
+
 ## Rules
 
 - Each agent has its own 3-bounce budget. Bounces from different agents do NOT share counters.