@cloverleaf/reference-impl 0.8.6 → 0.10.0

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

@@ -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, existsSync } from 'node:fs';
@@ -63,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';
@@ -73,6 +78,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');
@@ -110,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' +
@@ -119,6 +127,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);
@@ -498,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)
@@ -817,6 +835,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/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/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');
+}