@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/hooks/session-optimize.mjs

@@ -3,7 +3,7 @@
  * lib/hooks/session-optimize.mjs — Session end optimization hook — triggers agent optimization for low-performers.
  *
  * Runs as a Stop hook at session end. Checks recent performance reviews for agents with avgScore < 0.7
- * and invokes `construct optimize <agent>` to generate and apply improvement patches.
+ * and schedules `construct optimize <agent> --dry-run` detached so the Stop hook returns within budget.
  *
  * @p95ms 300
  * @maxBlockingScope Stop (non-blocking, async)
@@ -12,110 +12,102 @@
  * @matcher  *
  * @exits 0 = pass
  */
-import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
-import { spawnSync } from 'child_process';
+import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CONSTRUCT_BIN = join(__dirname, '..', '..', 'bin', 'construct');
 
-const OPTIMIZATION_THRESHOLD = 0.7;     // Score below this triggers optimization
-const MIN_TRACES_PER_AGENT = 3;          // Minimum traces needed for optimization
-const OPTIMIZATION_DAYS = 7;            // Look back 7 days for performance data
+const OPTIMIZATION_THRESHOLD = 0.7;
+const MIN_TRACES_PER_AGENT = 3;
+const OPTIMIZATION_DAYS = 7;
 const OPTIMIZATION_LOG_DIR = join(homedir(), '.cx', 'optimization-logs');
+const REVIEWS_DIR = join(homedir(), '.cx', 'performance-reviews');
 
-// Ensure optimization log directory exists
 mkdirSync(OPTIMIZATION_LOG_DIR, { recursive: true });
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
 
-// Only run for Construct sessions
 const cwd = input?.cwd || process.cwd();
 const projectName = cwd.split('/').pop() || 'project';
 
-// Skip if this is not a Construct project or in global mode
 if (projectName !== 'construct' && !existsSync(join(cwd, '.cx'))) {
   process.exit(0);
 }
 
-// Reviews older than this trigger an auto-refresh on the next session-stop.
-// Six hours keeps optimization signal current without re-running review on
-// every short session. Operators can still run `construct review` manually.
 const REVIEW_REFRESH_MS = 6 * 60 * 60 * 1000;
 
+function spawnDetached(args, { cwd: workDir = cwd } = {}) {
+  try {
+    const child = spawn(process.execPath, args, {
+      cwd: workDir,
+      stdio: 'ignore',
+      detached: true,
+      env: process.env,
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function listReviewJsonFiles(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => join(dir, name));
+}
+
 function maybeRefreshReviews() {
-  const reviewsDir = join(homedir(), '.cx', 'performance-reviews');
   let needsRefresh = false;
   try {
-    if (!existsSync(reviewsDir)) {
+    const files = listReviewJsonFiles(REVIEWS_DIR);
+    if (files.length === 0) {
       needsRefresh = true;
     } else {
-      const files = spawnSync('find', [reviewsDir, '-name', '*.json', '-type', 'f'], {
-        encoding: 'utf8', timeout: 5000,
-      }).stdout.trim().split('\n').filter(Boolean);
-      if (files.length === 0) {
-        needsRefresh = true;
-      } else {
-        const newestMs = files.reduce((acc, f) => {
-          try {
-            const m = Number(spawnSync('stat', ['-f', '%m', f], { encoding: 'utf8' }).stdout.trim());
-            return Number.isFinite(m) ? Math.max(acc, m * 1000) : acc;
-          } catch { return acc; }
-        }, 0);
-        if (Date.now() - newestMs > REVIEW_REFRESH_MS) needsRefresh = true;
-      }
+      const newestMs = files.reduce((acc, filePath) => {
+        try {
+          return Math.max(acc, statSync(filePath).mtimeMs);
+        } catch {
+          return acc;
+        }
+      }, 0);
+      if (Date.now() - newestMs > REVIEW_REFRESH_MS) needsRefresh = true;
     }
-  } catch { /* tolerate fs errors silently — refresh is best-effort */ }
+  } catch {
+    /* refresh is best-effort */
+  }
 
   if (!needsRefresh) return;
 
-  // Refresh detached so the Stop hook does not block on telemetry latency.
-  try {
-    spawnSync(process.execPath, [CONSTRUCT_BIN, 'review', '--quiet'], {
-      stdio: 'ignore',
-      timeout: 60_000,
-      detached: true,
-    });
-  } catch { /* refresh is best-effort; manual `construct review` is always available */ }
+  spawnDetached([CONSTRUCT_BIN, 'review', '--quiet']);
 }
 
-// Read the most recent performance review
 function getLatestPerformanceReview() {
-  const reviewsDir = join(homedir(), '.cx', 'performance-reviews');
-  if (!existsSync(reviewsDir)) return null;
-
   try {
-    const files = spawnSync('find', [reviewsDir, '-name', '*.json', '-type', 'f'], {
-      encoding: 'utf8',
-      timeout: 5000
-    }).stdout.trim().split('\n').filter(Boolean);
-
+    const files = listReviewJsonFiles(REVIEWS_DIR);
     if (files.length === 0) return null;
-    
-    // Sort by modification time, newest first
+
     files.sort((a, b) => {
       try {
-        const statA = spawnSync('stat', ['-f', '%m', a], { encoding: 'utf8' }).stdout.trim();
-        const statB = spawnSync('stat', ['-f', '%m', b], { encoding: 'utf8' }).stdout.trim();
-        return parseInt(statB) - parseInt(statA);
+        return statSync(b).mtimeMs - statSync(a).mtimeMs;
       } catch {
         return 0;
       }
     });
-    
-    const latestFile = files[0];
-    const content = readFileSync(latestFile, 'utf8');
-    return JSON.parse(content);
+
+    return JSON.parse(readFileSync(files[0], 'utf8'));
   } catch (error) {
     console.error(`Error reading performance reviews: ${error.message}`);
     return null;
   }
 }
 
-// Check if agent needs optimization
 function needsOptimization(agentStats) {
   return (
     agentStats.scoredInvocations >= MIN_TRACES_PER_AGENT &&
@@ -124,101 +116,25 @@ function needsOptimization(agentStats) {
   );
 }
 
-// Run optimization for a specific agent
-function optimizeAgent(agentName) {
-  console.log(`🔧 Optimizing ${agentName} (score < ${OPTIMIZATION_THRESHOLD})`);
-  
-  const logFile = join(OPTIMIZATION_LOG_DIR, `${new Date().toISOString().split('T')[0]}-${agentName}.log`);
-  const startTime = Date.now();
-  
-  try {
-    // Preview only. The new contract requires an explicit --apply from the
-    // operator; hook-driven runs must never modify prompt files.
-    const result = spawnSync(CONSTRUCT_BIN, ['optimize', agentName, `--days=${OPTIMIZATION_DAYS}`, '--dry-run'], {
-      cwd,
-      encoding: 'utf8',
-      timeout: 300000, // 5 minutes timeout for optimization
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-    
-    const duration = Date.now() - startTime;
-    
-    // Log the optimization attempt
-    const logEntry = {
-      timestamp: new Date().toISOString(),
-      agent: agentName,
-      durationMs: duration,
-      success: result.status === 0,
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.status,
-      signal: result.signal
-    };
-    
-    writeFileSync(logFile, JSON.stringify(logEntry, null, 2) + '\n');
-    
-    if (result.status === 0) {
-      console.log(`✅ Optimization for ${agentName} completed in ${duration}ms`);
-      
-      // Record observation about the optimization
-      recordOptimizationObservation(agentName, true, duration);
-    } else {
-      console.log(`❌ Optimization for ${agentName} failed with code ${result.status}`);
-      console.log(`Stderr: ${result.stderr.slice(0, 500)}...`);
-      
-      // Record observation about the failure
-      recordOptimizationObservation(agentName, false, duration, result.stderr);
-    }
-    
-    return result.status === 0;
-  } catch (error) {
-    console.error(`❌ Optimization for ${agentName} threw error: ${error.message}`);
-    
-    const logEntry = {
-      timestamp: new Date().toISOString(),
-      agent: agentName,
-      durationMs: Date.now() - startTime,
-      success: false,
-      error: error.message,
-      stack: error.stack
-    };
-    
-    writeFileSync(logFile, JSON.stringify(logEntry, null, 2) + '\n');
-    return false;
-  }
-}
-
-// Record optimization observation for learning
-function recordOptimizationObservation(agentName, success, durationMs, error = null) {
-  const observation = {
-    role: 'construct',
-    category: success ? 'pattern' : 'anti-pattern',
-    summary: success 
-      ? `Auto-optimized ${agentName} in ${durationMs}ms`
-      : `Auto-optimization failed for ${agentName}: ${error?.slice(0, 200) || 'unknown error'}`,
-    content: success
-      ? `Automatic optimization triggered for ${agentName} after performance review showed avgScore < ${OPTIMIZATION_THRESHOLD}. Optimization completed successfully in ${durationMs}ms.`
-      : `Automatic optimization failed for ${agentName}. Error: ${error || 'Unknown'}. System should notify maintainer.`,
-    tags: ['auto-optimization', 'performance-review', agentName],
-    confidence: 0.9
-  };
-  
-  try {
-    // Use existing observation recording if available
-    const observationFile = join(homedir(), '.cx', 'observations', `${Date.now()}-${agentName}-optimization.json`);
-    mkdirSync(dirname(observationFile), { recursive: true });
-    writeFileSync(observationFile, JSON.stringify(observation, null, 2) + '\n');
-  } catch (error) {
-    // Non-critical - observation recording failed
-    console.error(`Failed to record optimization observation: ${error.message}`);
-  }
+function scheduleAgentOptimization(agentName) {
+  const logFile = join(OPTIMIZATION_LOG_DIR, `${new Date().toISOString().split('T')[0]}-${agentName}-scheduled.json`);
+  const scheduled = spawnDetached([
+    CONSTRUCT_BIN,
+    'optimize',
+    agentName,
+    `--days=${OPTIMIZATION_DAYS}`,
+    '--dry-run',
+  ]);
+  writeFileSync(logFile, `${JSON.stringify({
+    timestamp: new Date().toISOString(),
+    agent: agentName,
+    scheduled,
+    mode: 'detached-dry-run',
+  })}\n`);
+  return scheduled;
 }
 
-// Main optimization logic
 function main() {
-  // If the most recent review is missing or stale (>6h), kick off a refresh
-  // detached so the Stop hook returns promptly. The refresh runs on the next
-  // session's Stop if it's still in flight; nothing here blocks user work.
   maybeRefreshReviews();
 
   const review = getLatestPerformanceReview();
@@ -226,92 +142,53 @@ function main() {
     console.log('📊 No performance review data found. Run `construct review` first.');
     process.exit(0);
   }
-  
-  console.log(`📊 Checking ${review.agentStats.length} agents from performance review ${review.generated}`);
-  
+
   const agentsNeedingOptimization = review.agentStats.filter(needsOptimization);
-  
+
   if (agentsNeedingOptimization.length === 0) {
     console.log(`✅ All ${review.agentStats.length} agents have scores >= ${OPTIMIZATION_THRESHOLD} or insufficient data`);
     process.exit(0);
   }
-  
-  console.log(`🔧 Found ${agentsNeedingOptimization.length} agents needing optimization:`);
-  agentsNeedingOptimization.forEach(agent => {
-    console.log(`  • ${agent.name}: avgScore=${agent.avgScore}, invocations=${agent.invocations}`);
-  });
-  
-  // Sequential optimization keeps prompt-tuning deterministic and avoids
-  // colliding writes to per-agent prompt files.
-  let optimizedCount = 0;
-  let failedCount = 0;
-  
+
+  console.log(`🔧 Scheduling ${agentsNeedingOptimization.length} detached optimization preview(s):`);
+  let scheduledCount = 0;
   for (const agent of agentsNeedingOptimization) {
-    const success = optimizeAgent(agent.name);
-    if (success) {
-      optimizedCount++;
-    } else {
-      failedCount++;
-    }
-    
-    // Small delay between optimizations to avoid rate limits
-    if (agentsNeedingOptimization.length > 1) {
-      spawnSync('sleep', ['10'], { encoding: 'utf8' });
-    }
-  }
-  
-  // Summary
-  console.log(`\n📈 Optimization Summary:`);
-  console.log(`  • Agents checked: ${review.agentStats.length}`);
-  console.log(`  • Needing optimization: ${agentsNeedingOptimization.length}`);
-  console.log(`  • Successfully optimized: ${optimizedCount}`);
-  console.log(`  • Failed: ${failedCount}`);
-  
-  if (optimizedCount > 0) {
-    console.log(`\n💡 Optimized agents will be evaluated in the next performance review.`);
-    console.log(`   Run \`construct review\` after next session to see improvements.`);
+    console.log(`  • ${agent.name}: avgScore=${agent.avgScore}, invocations=${agent.invocations}`);
+    if (scheduleAgentOptimization(agent.name)) scheduledCount += 1;
   }
-  
-  // Log summary to file
-  const summary = {
+
+  const summaryFile = join(OPTIMIZATION_LOG_DIR, `${new Date().toISOString().split('T')[0]}-summary.json`);
+  writeFileSync(summaryFile, `${JSON.stringify({
     timestamp: new Date().toISOString(),
     project: projectName,
     reviewDate: review.generated,
     agentsChecked: review.agentStats.length,
     agentsNeedingOptimization: agentsNeedingOptimization.length,
-    optimizedCount,
-    failedCount,
-    agents: agentsNeedingOptimization.map(a => ({
+    scheduledCount,
+    agents: agentsNeedingOptimization.map((a) => ({
       name: a.name,
       avgScore: a.avgScore,
       invocations: a.invocations,
-      optimized: optimizeAgent.includes ? 'yes' : 'no'
-    }))
-  };
-  
-  const summaryFile = join(OPTIMIZATION_LOG_DIR, `${new Date().toISOString().split('T')[0]}-summary.json`);
-  writeFileSync(summaryFile, JSON.stringify(summary, null, 2) + '\n');
+    })),
+  }, null, 2)}\n`);
+
+  console.log(`\n📈 Optimization previews scheduled: ${scheduledCount}/${agentsNeedingOptimization.length}`);
 }
 
-// Run main logic
 try {
   main();
 } catch (error) {
   console.error(`❌ Session optimization hook crashed: ${error.message}`);
-  console.error(error.stack);
-  
-  // Log the crash
   const crashLog = join(OPTIMIZATION_LOG_DIR, 'crashes', `${Date.now()}-crash.json`);
   mkdirSync(dirname(crashLog), { recursive: true });
-  writeFileSync(crashLog, JSON.stringify({
+  writeFileSync(crashLog, `${JSON.stringify({
     timestamp: new Date().toISOString(),
     error: error.message,
     stack: error.stack,
     cwd,
-    projectName
-  }, null, 2) + '\n');
-  
+    projectName,
+  }, null, 2)}\n`);
   process.exit(1);
 }
 
-process.exit(0);
+process.exit(0);

package/lib/hooks/session-start.mjs

@@ -265,28 +265,31 @@ const selfKnowledgeNote = '\nSelf-knowledge: call `knowledge_search` for any Con
 let sourcesNote = '';
 let embedStatusNote = '';
 try {
-  const repos = (process.env.GITHUB_REPOS ?? '').split(',').map(r => r.trim()).filter(Boolean);
-  const jiraConfigured = !!(process.env.JIRA_BASE_URL);
-  const linearConfigured = !!(process.env.LINEAR_API_KEY);
-  const hasSources = repos.length > 0 || jiraConfigured || linearConfigured;
+  const { loadProjectConfig } = await import('../config/project-config.mjs');
+  const { resolveEffectiveSourceTargetsFromConfig } = await import('../config/source-targets.mjs');
+  const { config } = loadProjectConfig(process.cwd(), process.env);
+  const targets = resolveEffectiveSourceTargetsFromConfig(config, process.env);
+  const repos = targets.filter((t) => t.provider === 'github').map((t) => t.selector.repo);
+  const jiraTargets = targets.filter((t) => t.provider === 'jira');
+  const linearTargets = targets.filter((t) => t.provider === 'linear');
+  const slackTargets = targets.filter((t) => t.provider === 'slack');
+  const hasSources = targets.length > 0;
   if (hasSources) {
     const parts = [];
     if (repos.length > 0) parts.push(`GitHub repos: ${repos.join(', ')}`);
-    if (jiraConfigured) parts.push('Jira: configured');
-    if (linearConfigured) parts.push('Linear: configured');
-    // Surface which sources are wired so `provider_fetch` is the obvious
-    // tool for questions about them. The "fetch first, don't answer from
-    // memory" policy lives in the persona.
+    if (jiraTargets.length > 0) parts.push(`Jira projects: ${jiraTargets.map((t) => t.selector.project).join(', ')}`);
+    if (linearTargets.length > 0) parts.push(`Linear teams: ${linearTargets.map((t) => t.selector.team).join(', ')}`);
+    if (slackTargets.length > 0) parts.push(`Slack channels: ${slackTargets.map((t) => t.selector.channel).join(', ')}`);
     sourcesNote = '\nProvider sources wired: ' + parts.join(' · ') +
       '. Use `provider_fetch` for any question about them.\n';
   }
+} catch { /* best effort */ }
 
-  // Embed daemon status — surface as a one-liner so operator always knows state
+try {
   const { resolveEmbedStatus, autoStartEmbedIfNeeded } = await import('../embed/cli.mjs');
   const embedStatus = resolveEmbedStatus(process.env);
   if (embedStatus.level !== 'none') {
     embedStatusNote = `\n## Embed daemon\n${embedStatus.label} · ${embedStatus.detail}\n`;
-    // Auto-start if CX_AUTO_EMBED=1 and daemon is stopped
     if (embedStatus.level === 'stopped' && process.env.CX_AUTO_EMBED === '1') {
       const result = await autoStartEmbedIfNeeded(process.env);
       if (result.started) {
@@ -319,11 +322,10 @@ try {
 // plugin so both platforms surface the same prelude on session start.
 
 let intakeReviewNote = '';
-let brokerStatusNote = '';
 try {
-  const { buildIntakePrelude, buildBrokerStatusLine } = await import('../intake/session-prelude.mjs');
-  intakeReviewNote = buildIntakePrelude({ cwd, env: process.env });
-  brokerStatusNote = `\n${buildBrokerStatusLine({ env: process.env })}\n`;
+  const { buildSessionPrelude } = await import('../intake/session-prelude.mjs');
+  const prelude = buildSessionPrelude({ cwd, env: process.env });
+  intakeReviewNote = prelude ? `\n${prelude}\n` : '';
 } catch { /* best effort */ }
 
 // Missing-env-vars notice. Reads .env.example from the project root,
@@ -383,7 +385,7 @@ try {
 // that pollutes the caller's output contract, so the resolved output mode routes
 // the payload to stdout (interactive), stderr, or a debug log (silent).
 
-const payload = `${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`;
+const payload = `${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`;
 try {
   const { mode } = resolveHookOutputMode({ cwd, env: process.env });
   writeHookContext({ payload, mode });

package/lib/host-disposition.mjs

@@ -2,6 +2,13 @@
  * lib/host-disposition.mjs — single source of truth for the disposition of
  * every artifact Construct creates in a host project (ADR-0027 §1).
  *
+ * Scope model (see docs/concepts/project-scopes.md):
+ *   templates/, docs/  — package/repo durable sources (committed)
+ *   .construct/        — per-project launcher (ignored)
+ *   .cx/               — per-project runtime: intake, oracle, observations, demos (ignored)
+ *   ~/.construct/      — user credentials and doctor state
+ *   ~/.cx/             — user-scope telemetry fallback
+ *
  * `IGNORED_PATTERNS` enumerates machine-specific, sync-regenerated artifacts
  * that must never be committed; the init `.gitignore` writer and the
  * `gitignore-coverage` reconciliation both read from here, and uninstall /

package/lib/improvement/cli.mjs

@@ -0,0 +1,189 @@
+/**
+ * lib/improvement/cli.mjs — CLI handlers for `construct improvement <subcommand>`.
+ *
+ * Subcommands: submit, review, pending, show, approve, apply, rollback, list.
+ * Each command reads or writes durable state under `.cx/improvement/` and routes
+ * proposals through the governed controller; apply and rollback record human acts
+ * but do not mutate live artifacts.
+ */
+import fs from 'node:fs';
+
+import {
+  applyRecord,
+  approveRecord,
+  formatReviewSummary,
+  listPending,
+  resolveKnownApprovers,
+  reviewRecord,
+  rollbackRecord,
+  submitBundle,
+} from './surface.mjs';
+import { listRecords, loadRecord } from './store.mjs';
+
+function readJsonArg(args, prefix) {
+  const hit = args.find((a) => a.startsWith(prefix));
+  if (!hit) return null;
+  const file = hit.slice(prefix.length);
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function flagValue(args, prefix) {
+  const hit = args.find((a) => a.startsWith(prefix));
+  return hit ? hit.slice(prefix.length) : null;
+}
+
+function usage() {
+  process.stderr.write(
+    'Usage: construct improvement <submit|review|pending|show|approve|apply|rollback|list> [--json]\n'
+    + '  submit   --bundle=FILE | (--trace=FILE --dataset=FILE --report=FILE [--trigger=KIND])\n'
+    + '  review   <id>\n'
+    + '  pending\n'
+    + '  show     <id>\n'
+    + '  approve  <id> [--identity=USER]\n'
+    + '  apply    <id> [--monitor=ID]\n'
+    + '  rollback <id> [--reason=TEXT]\n'
+    + '  list     [--state=STATE]\n',
+  );
+}
+
+export async function runImprovementCli(args, { projectDir = process.cwd() } = {}) {
+  const json = args.includes('--json');
+  const sub = args.find((a) => !a.startsWith('-'));
+  const positional = args.filter((a) => !a.startsWith('-'));
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    usage();
+    return sub === '--help' || sub === '-h' ? 0 : 1;
+  }
+
+  const write = (payload) => {
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+  };
+
+  switch (sub) {
+    case 'submit': {
+      const bundle = readJsonArg(args, '--bundle=');
+      const trace = bundle?.trace ?? readJsonArg(args, '--trace=');
+      const dataset = bundle?.dataset ?? readJsonArg(args, '--dataset=');
+      const evaluationReport = bundle?.evaluationReport ?? readJsonArg(args, '--report=');
+      const triggerKind = flagValue(args, '--trigger=') || bundle?.trigger?.kind || 'operator-request';
+      const trigger = bundle?.trigger || { kind: triggerKind, optIn: true };
+      const result = submitBundle({
+        projectDir,
+        bundle: bundle || {
+          trace,
+          trigger,
+          dataset,
+          evaluationReport,
+          approver: flagValue(args, '--approver=') || resolveKnownApprovers(projectDir)[0] || null,
+        },
+      });
+      if (json) write(result);
+      else if (!result.ok) {
+        process.stderr.write(`submit refused: ${result.stage || result.error}\n`);
+        if (result.governance?.refusals?.length) {
+          process.stderr.write(`  refusals: ${result.governance.refusals.join(', ')}\n`);
+        }
+        return 1;
+      } else {
+        process.stdout.write(`submitted ${result.record.id} → ${result.record.proposal.state}\n`);
+      }
+      return result.ok ? 0 : 1;
+    }
+
+    case 'review': {
+      const id = positional[1];
+      if (!id) { usage(); return 1; }
+      const result = reviewRecord(projectDir, id);
+      if (!result.ok) {
+        process.stderr.write(`review failed: ${result.error}\n`);
+        return 1;
+      }
+      if (json) write(result);
+      else process.stdout.write(formatReviewSummary(result.record, result.governance) + '\n');
+      return 0;
+    }
+
+    case 'pending': {
+      const pending = listPending(projectDir);
+      if (json) write({ pending });
+      else {
+        if (!pending.length) process.stdout.write('No proposals awaiting approval.\n');
+        for (const row of pending) {
+          process.stdout.write(`${row.id} · ${row.proposal?.type} · ${row.proposal?.state}\n`);
+        }
+      }
+      return 0;
+    }
+
+    case 'show': {
+      const id = positional[1];
+      if (!id) { usage(); return 1; }
+      const record = loadRecord(projectDir, id);
+      if (!record) {
+        process.stderr.write(`not found: ${id}\n`);
+        return 1;
+      }
+      if (json) write(record);
+      else process.stdout.write(formatReviewSummary(record) + '\n');
+      return 0;
+    }
+
+    case 'approve': {
+      const id = positional[1];
+      if (!id) { usage(); return 1; }
+      const result = approveRecord(projectDir, id, { identity: flagValue(args, '--identity=') });
+      if (!result.ok) {
+        process.stderr.write(`approve failed: ${result.error}\n`);
+        return 1;
+      }
+      if (json) write(result);
+      else process.stdout.write(`approved ${id} → ${result.record.proposal.state}\n`);
+      return 0;
+    }
+
+    case 'apply': {
+      const id = positional[1];
+      if (!id) { usage(); return 1; }
+      const result = applyRecord(projectDir, id, { monitor: flagValue(args, '--monitor=') });
+      if (!result.ok) {
+        process.stderr.write(`apply failed: ${result.error}\n`);
+        return 1;
+      }
+      if (json) write(result);
+      else process.stdout.write(`applied ${id} → ${result.record.proposal.state}\n`);
+      return 0;
+    }
+
+    case 'rollback': {
+      const id = positional[1];
+      if (!id) { usage(); return 1; }
+      const result = rollbackRecord(projectDir, id, { reason: flagValue(args, '--reason=') || 'operator-rollback' });
+      if (!result.ok) {
+        process.stderr.write(`rollback failed: ${result.error}\n`);
+        return 1;
+      }
+      if (json) write(result);
+      else process.stdout.write(`rolled back ${id} → ${result.record.proposal.state}\n`);
+      return 0;
+    }
+
+    case 'list': {
+      const state = flagValue(args, '--state=');
+      const rows = listRecords(projectDir, { state });
+      if (json) write({ proposals: rows });
+      else {
+        if (!rows.length) process.stdout.write('No improvement proposals.\n');
+        for (const row of rows) {
+          process.stdout.write(`${row.id} · ${row.proposal?.type} · ${row.proposal?.state}\n`);
+        }
+      }
+      return 0;
+    }
+
+    default:
+      process.stderr.write(`Unknown subcommand: ${sub}\n`);
+      usage();
+      return 1;
+  }
+}