create-metaclaw 3.3.0

package/installer/modules/core/src/self-improve.ts.txt

@@ -0,0 +1,48 @@
+/**
+ * Self-Improvement Module — Generator->Reflector->Curator pattern
+ * Auto-generated by MetaClaw Installer
+ */
+
+import { getDb } from "./db.js";
+import { log } from "./observability.js";
+
+export function recordOutcome(promptType: string, score: number, feedback?: string) {
+  const db = getDb();
+  const version = db.prepare(
+    "SELECT id, total_runs, avg_score FROM prompt_versions WHERE prompt_type = ? AND is_active = 1 ORDER BY version DESC LIMIT 1"
+  ).get(promptType) as any;
+
+  if (version) {
+    const newTotal = version.total_runs + 1;
+    const newAvg = ((version.avg_score * version.total_runs) + score) / newTotal;
+    db.prepare("UPDATE prompt_versions SET total_runs = ?, avg_score = ? WHERE id = ?").run(newTotal, newAvg, version.id);
+  }
+
+  log("info", "self_improve.outcome", { promptType, score, feedback });
+}
+
+export function shouldOptimize(promptType: string): boolean {
+  const db = getDb();
+  const version = db.prepare(
+    "SELECT total_runs, avg_score FROM prompt_versions WHERE prompt_type = ? AND is_active = 1 ORDER BY version DESC LIMIT 1"
+  ).get(promptType) as any;
+
+  if (!version) return false;
+  return version.total_runs > 0 && version.total_runs % 30 === 0;
+}
+
+export function getCurrentPrompt(promptType: string): string | null {
+  const db = getDb();
+  const row = db.prepare(
+    "SELECT content FROM prompt_versions WHERE prompt_type = ? AND is_active = 1 ORDER BY version DESC LIMIT 1"
+  ).get(promptType) as any;
+  return row?.content || null;
+}
+
+export function savePromptVersion(promptType: string, content: string, createdBy: string = "curator") {
+  const db = getDb();
+  const current = db.prepare("SELECT MAX(version) as v FROM prompt_versions WHERE prompt_type = ?").get(promptType) as any;
+  const nextVersion = (current?.v || 0) + 1;
+  db.prepare("INSERT INTO prompt_versions (prompt_type, version, content, created_by) VALUES (?, ?, ?, ?)").run(promptType, nextVersion, content, createdBy);
+  log("info", "self_improve.new_version", { promptType, version: nextVersion, createdBy });
+}

package/installer/modules/core/src/self-update.ts.txt

@@ -0,0 +1,345 @@
+/**
+ * Self-Update Module — keeps the agent's knowledge and config current
+ * Auto-generated by MetaClaw Installer v3.3.0
+ *
+ * Responsibilities:
+ * 1. Periodic memory consolidation (update CLAUDE.md, SOUL.md with learnings)
+ * 2. Prompt optimization (Generator→Reflector→Curator loop)
+ * 3. Metrics rollup and reporting
+ * 4. Detect when context is getting stale and trigger refresh
+ * 5. Log rotation and cleanup
+ *
+ * Schedule: configurable via config table (default: every 6 hours)
+ */
+
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import type { SDKResultMessage, SDKResultSuccess } from "@anthropic-ai/claude-agent-sdk";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { getDb, getConfig, setConfig, getTodayMetrics, recordAction } from "./db.js";
+import { log } from "./observability.js";
+import { getCurrentPrompt, savePromptVersion, shouldOptimize } from "./self-improve.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_DIR = path.join(__dirname, "..");
+
+// Default update interval: 6 hours (in milliseconds)
+const DEFAULT_UPDATE_INTERVAL_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * Check if a self-update cycle is due and run it if so.
+ * Called at the start of every agent run.
+ */
+export async function runSelfUpdate(): Promise<void> {
+  const db = getDb();
+  const lastUpdate = getConfig("last_self_update");
+  const intervalMs = parseInt(getConfig("self_update_interval_ms") || String(DEFAULT_UPDATE_INTERVAL_MS));
+
+  if (lastUpdate) {
+    const elapsed = Date.now() - new Date(lastUpdate).getTime();
+    if (elapsed < intervalMs) {
+      return; // Not due yet
+    }
+  }
+
+  log("info", "self_update.start", {});
+  console.log("[Self-Update] Running periodic maintenance...");
+
+  try {
+    // 1. Regenerate dashboard data
+    regenerateDashboard();
+
+    // 2. Consolidate metrics into CLAUDE.md
+    await updateClaudeMd();
+
+    // 3. Run prompt optimization if enough data
+    await optimizePrompts();
+
+    // 4. Rotate old logs
+    rotateOldLogs();
+
+    // 5. Update heartbeat
+    updateHeartbeat();
+
+    // 6. Update SESSION.md with current state
+    updateSessionState();
+
+    // Record completion
+    setConfig("last_self_update", new Date().toISOString());
+    log("info", "self_update.complete", {});
+    console.log("[Self-Update] Complete.");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log("error", "self_update.failed", { error: msg });
+    console.error("[Self-Update] Failed: " + msg);
+  }
+}
+
+/**
+ * Update CLAUDE.md with latest metrics and learnings.
+ */
+async function updateClaudeMd(): Promise<void> {
+  const claudeMdPath = path.join(PROJECT_DIR, "CLAUDE.md");
+  if (!fs.existsSync(claudeMdPath)) return;
+
+  const currentContent = fs.readFileSync(claudeMdPath, "utf-8");
+
+  // Gather metrics from last 7 days
+  const db = getDb();
+  const weekMetrics = db.prepare(`
+    SELECT
+      SUM(actions_taken) as total_actions,
+      SUM(actions_succeeded) as total_succeeded,
+      SUM(actions_failed) as total_failed,
+      SUM(total_cost_usd) as total_cost,
+      COUNT(*) as days_active
+    FROM daily_metrics
+    WHERE date > date('now', '-7 days')
+  `).get() as any;
+
+  // Get prompt performance
+  const promptStats = db.prepare(`
+    SELECT prompt_type, version, avg_score, total_runs
+    FROM prompt_versions
+    WHERE is_active = 1
+    ORDER BY prompt_type
+  `).all() as any[];
+
+  // Build the metrics section
+  const metricsSection = [
+    "",
+    "## Latest Metrics (auto-updated)",
+    "Last updated: " + new Date().toISOString().slice(0, 16),
+    "",
+    weekMetrics ? [
+      "### Last 7 Days",
+      "- Actions: " + (weekMetrics.total_actions || 0),
+      "- Success rate: " + (weekMetrics.total_actions > 0 ? ((weekMetrics.total_succeeded / weekMetrics.total_actions) * 100).toFixed(1) + "%" : "N/A"),
+      "- Cost: $" + (weekMetrics.total_cost || 0).toFixed(2),
+      "- Days active: " + (weekMetrics.days_active || 0),
+    ].join("\n") : "No metrics yet.",
+    "",
+    promptStats.length > 0 ? [
+      "### Prompt Performance",
+      ...promptStats.map((p: any) => "- " + p.prompt_type + " v" + p.version + ": avg " + (p.avg_score || 0).toFixed(1) + "/10 (" + p.total_runs + " runs)"),
+    ].join("\n") : "",
+  ].join("\n");
+
+  // Replace or append metrics section
+  const metricsMarker = "## Latest Metrics (auto-updated)";
+  if (currentContent.includes(metricsMarker)) {
+    // Replace existing metrics section (from marker to next ## or end)
+    const before = currentContent.split(metricsMarker)[0];
+    const afterMatch = currentContent.split(metricsMarker)[1]?.match(/\n## [^L]/);
+    const after = afterMatch ? currentContent.split(metricsMarker)[1].slice(afterMatch.index!) : "";
+    fs.writeFileSync(claudeMdPath, before + metricsSection + after);
+  } else {
+    // Append
+    fs.writeFileSync(claudeMdPath, currentContent + "\n" + metricsSection);
+  }
+
+  log("info", "self_update.claude_md_updated", {});
+}
+
+/**
+ * Run the Curator — optimize prompts based on performance data.
+ * Only runs when shouldOptimize() returns true (every 30 runs).
+ */
+async function optimizePrompts(): Promise<void> {
+  const db = getDb();
+
+  // Get all prompt types that need optimization
+  const promptTypes = db.prepare(
+    "SELECT DISTINCT prompt_type FROM prompt_versions WHERE is_active = 1"
+  ).all() as any[];
+
+  for (const { prompt_type } of promptTypes) {
+    if (!shouldOptimize(prompt_type)) continue;
+
+    const current = getCurrentPrompt(prompt_type);
+    if (!current) continue;
+
+    // Get recent performance data
+    const recentActions = db.prepare(`
+      SELECT status, details, cost_usd
+      FROM action_log
+      WHERE action_type LIKE '%${prompt_type}%'
+      ORDER BY created_at DESC
+      LIMIT 50
+    `).all() as any[];
+
+    const successRate = recentActions.length > 0
+      ? recentActions.filter((a: any) => a.status === "success").length / recentActions.length
+      : 0;
+
+    // Only optimize if success rate is below 90%
+    if (successRate > 0.9) {
+      log("info", "self_update.skip_optimize", { prompt_type, successRate });
+      continue;
+    }
+
+    log("info", "self_update.optimizing_prompt", { prompt_type, successRate });
+
+    try {
+      // Ask Claude to improve the prompt
+      const optimizePrompt = [
+        "You are a prompt optimization expert. Analyze this prompt and its performance data, then produce an improved version.",
+        "",
+        "CURRENT PROMPT:",
+        current,
+        "",
+        "PERFORMANCE DATA:",
+        "- Success rate: " + (successRate * 100).toFixed(1) + "%",
+        "- Total recent runs: " + recentActions.length,
+        "- Common failure details: " + recentActions.filter((a: any) => a.status === "error").map((a: any) => a.details).filter(Boolean).slice(0, 5).join("; "),
+        "",
+        "RULES:",
+        "- Change ONE thing at a time (so we can measure impact)",
+        "- Keep the same structure and format",
+        "- Focus on the biggest failure mode",
+        "- The improved prompt must be directly usable (no meta-commentary)",
+        "",
+        "Output ONLY the improved prompt text. Nothing else.",
+      ].join("\n");
+
+      let improvedPrompt = "";
+      const stream = query({
+        prompt: optimizePrompt,
+        options: { allowedTools: [], maxTurns: 1, model: "claude-sonnet-4-6" },
+      });
+
+      for await (const message of stream) {
+        if (message.type === "assistant") {
+          const msg = message as any;
+          if (msg.message?.content) {
+            for (const block of msg.message.content) {
+              if (block.type === "text") improvedPrompt += block.text;
+            }
+          }
+        }
+      }
+
+      if (improvedPrompt.trim()) {
+        savePromptVersion(prompt_type, improvedPrompt.trim(), "curator");
+        log("info", "self_update.prompt_optimized", { prompt_type });
+      }
+    } catch (err) {
+      log("error", "self_update.optimize_failed", { prompt_type, error: String(err) });
+    }
+  }
+}
+
+/**
+ * Rotate logs older than 30 days.
+ */
+function rotateOldLogs(): void {
+  const logsDir = path.join(PROJECT_DIR, "data", "logs");
+  if (!fs.existsSync(logsDir)) return;
+
+  const thirtyDaysAgo = new Date();
+  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
+
+  const files = fs.readdirSync(logsDir);
+  let rotated = 0;
+
+  for (const file of files) {
+    if (!file.endsWith(".jsonl")) continue;
+    const filePath = path.join(logsDir, file);
+    const stats = fs.statSync(filePath);
+    if (stats.mtime < thirtyDaysAgo) {
+      fs.unlinkSync(filePath);
+      rotated++;
+    }
+  }
+
+  if (rotated > 0) {
+    log("info", "self_update.logs_rotated", { count: rotated });
+  }
+}
+
+/**
+ * Update HEARTBEAT.md with last run timestamp.
+ */
+function updateHeartbeat(): void {
+  const heartbeatPath = path.join(PROJECT_DIR, "HEARTBEAT.md");
+  if (!fs.existsSync(heartbeatPath)) return;
+
+  let content = fs.readFileSync(heartbeatPath, "utf-8");
+  const now = new Date().toISOString().slice(0, 16);
+
+  if (content.includes("Last run:")) {
+    content = content.replace(/Last run:.*/, "Last run: " + now);
+  } else {
+    content += "\nLast run: " + now;
+  }
+
+  fs.writeFileSync(heartbeatPath, content);
+}
+
+/**
+ * Regenerate dashboard.json for the HTML dashboard.
+ */
+function regenerateDashboard(): void {
+  try {
+    const { execSync } = require("child_process");
+    execSync("npx tsx src/update-dashboard.ts", { cwd: PROJECT_DIR, stdio: "pipe", timeout: 15000 });
+    log("info", "self_update.dashboard_regenerated", {});
+  } catch {
+    // Non-critical — dashboard will update on next manual run
+  }
+}
+
+/**
+ * Update SESSION.md with current agent state.
+ */
+function updateSessionState(): void {
+  const sessionPath = path.join(PROJECT_DIR, "SESSION.md");
+  const db = getDb();
+  const now = new Date().toISOString().slice(0, 16);
+
+  const metrics = db.prepare("SELECT * FROM daily_metrics ORDER BY date DESC LIMIT 7").all() as any[];
+  const totalActions = metrics.reduce((s: number, m: any) => s + (m.actions_taken || 0), 0);
+  const totalCost = metrics.reduce((s: number, m: any) => s + (m.total_cost_usd || 0), 0);
+  const breaker = db.prepare("SELECT state, reason FROM circuit_breaker WHERE name = 'main'").get() as any;
+
+  const promptInfo = db.prepare(
+    "SELECT version, avg_score, total_runs FROM prompt_versions WHERE is_active = 1 ORDER BY version DESC LIMIT 1"
+  ).get() as any;
+
+  const content = [
+    "# Agent Session State",
+    "> Auto-updated: " + now,
+    "",
+    "## Health",
+    "- Circuit breaker: " + (breaker?.state || "closed").toUpperCase(),
+    breaker?.reason ? "- Reason: " + breaker.reason : "",
+    "",
+    "## Last 7 Days",
+    "- Total actions: " + totalActions,
+    "- Total cost: $" + totalCost.toFixed(2),
+    ...metrics.map((m: any) => "- " + m.date + ": " + m.actions_taken + " actions, $" + (m.total_cost_usd || 0).toFixed(4)),
+    "",
+    "## Self-Improvement",
+    promptInfo ? "- Current prompt: v" + promptInfo.version + " (avg score: " + (promptInfo.avg_score || 0).toFixed(1) + "/10, " + promptInfo.total_runs + " runs)" : "- Prompt: v1 (default)",
+    "- Next optimization: run #" + (promptInfo ? Math.ceil((promptInfo.total_runs + 1) / 30) * 30 : 30),
+  ].filter(Boolean).join("\n");
+
+  fs.writeFileSync(sessionPath, content);
+  log("info", "self_update.session_updated", {});
+}
+
+/**
+ * Force a self-update cycle (for manual trigger).
+ */
+export async function forceSelfUpdate(): Promise<void> {
+  setConfig("last_self_update", "2000-01-01T00:00:00Z");
+  await runSelfUpdate();
+}
+
+// --- CLI Entry Point ---
+if (process.argv[1]?.includes("self-update")) {
+  getDb();
+  console.log("Forcing self-update cycle...\n");
+  forceSelfUpdate().then(() => process.exit(0));
+}

package/installer/modules/core/src/sync-context.ts.txt

@@ -0,0 +1,133 @@
+/**
+ * MetaClaw — Context Auto-Sync
+ *
+ * Builds a fresh memory/CONTEXT.md every 30 min + before/after cron cycles.
+ * Pulls: state.json, tasks.json, system-context.json, recent messages, agent heartbeats.
+ * Gives the cron agent a single-file brain that stays current without LLM calls.
+ *
+ * Borrowed from AXIOM's pattern: "Cron agent went from 0 real work to 15 articles + 3 packages
+ * overnight after implementing this." — QIS bucket ops.memory.navigatable-context-architecture
+ */
+
+import fs from "fs";
+import path from "path";
+
+const PROJECT_ROOT = process.cwd();
+const OUTPUT = path.join(PROJECT_ROOT, "memory", "CONTEXT.md");
+
+function load<T>(file: string, fallback: T): T {
+  try { return JSON.parse(fs.readFileSync(path.join(PROJECT_ROOT, file), "utf-8")); }
+  catch { return fallback; }
+}
+
+function build(): string {
+  const state: any = load("data/state.json", {});
+  const tasks: any = load("data/tasks.json", { human_tasks: [], ai_tasks: [] });
+  const context: any = load("data/system-context.json", {});
+
+  const now = new Date().toISOString();
+  const pendingHTs = (tasks.human_tasks || []).filter((t: any) => t.status === "pending").slice(0, 5);
+  const pendingATs = (tasks.ai_tasks || []).filter((t: any) => t.status === "pending").slice(0, 5);
+  const criticalHTs = pendingHTs.filter((t: any) => t.priority === "critical");
+
+  const lines: string[] = [];
+  lines.push(`# CONTEXT.md — Live Agent Brief`);
+  lines.push(`**Synced:** ${now}`);
+  lines.push(`**Agent:** ${state.agent_name || "unknown"}`);
+  lines.push("");
+  lines.push("> This file is auto-generated. Read it FIRST every cycle. It's your single-file brain.");
+  lines.push("");
+
+  lines.push("## Current State");
+  lines.push(`- **Next priority action:** ${state.next_priority_action || "(none set)"}`);
+  if (state.last_action) lines.push(`- **Last action:** ${state.last_action}`);
+  if (state.metrics) lines.push(`- **Metrics:** ${JSON.stringify(state.metrics)}`);
+  lines.push("");
+
+  lines.push("## Setup Progress");
+  const progress = tasks.setup_progress;
+  if (progress) {
+    lines.push(`- Phase: **${progress.phase}**`);
+    lines.push(`- Completed: ${progress.completed_ht}/${progress.total_ht} (${progress.percent}%)`);
+  }
+  lines.push("");
+
+  if (criticalHTs.length > 0) {
+    lines.push("## 🚨 CRITICAL HUMAN TASKS (blocking work)");
+    for (const ht of criticalHTs) {
+      lines.push(`- **${ht.title}** (${ht.estimated_minutes}min) — ${ht.why}`);
+    }
+    lines.push("");
+  }
+
+  if (pendingHTs.length > 0) {
+    lines.push("## Pending Human Tasks (top 5)");
+    for (const ht of pendingHTs) {
+      lines.push(`- [${ht.priority}] ${ht.title}`);
+    }
+    lines.push("");
+  }
+
+  if (pendingATs.length > 0) {
+    lines.push("## Pending AI Tasks (top 5 — your work queue)");
+    for (const at of pendingATs) {
+      const blocked = at.requires_ht && at.requires_ht.length > 0 ? ` [blocked by ${at.requires_ht.join(",")}]` : "";
+      lines.push(`- [${at.priority}] ${at.title}${blocked}`);
+    }
+    lines.push("");
+  }
+
+  if (context.whatWorks && Array.isArray(context.whatWorks) && context.whatWorks.length > 0) {
+    lines.push("## What's Working (from system-context)");
+    for (const w of context.whatWorks.slice(0, 5)) {
+      lines.push(`- ${typeof w === "string" ? w : JSON.stringify(w).slice(0, 150)}`);
+    }
+    lines.push("");
+  }
+
+  if (context.whatDoesntWork && Array.isArray(context.whatDoesntWork) && context.whatDoesntWork.length > 0) {
+    lines.push("## What Doesn't Work (avoid these)");
+    for (const w of context.whatDoesntWork.slice(0, 5)) {
+      lines.push(`- ${typeof w === "string" ? w : JSON.stringify(w).slice(0, 150)}`);
+    }
+    lines.push("");
+  }
+
+  // Inbox — recent messages
+  try {
+    const inboxPath = `__INBOX_ROOT__\\${(state.agent_name || "").toLowerCase()}`;
+    if (fs.existsSync(inboxPath)) {
+      const files = fs.readdirSync(inboxPath).filter(f => f.endsWith(".json")).slice(-5);
+      if (files.length > 0) {
+        lines.push("## Recent Inbox Messages");
+        for (const f of files) lines.push(`- ${f}`);
+        lines.push("");
+      }
+    }
+  } catch {}
+
+  lines.push("## Always-Required Reads");
+  lines.push("- `CLAUDE.md` — identity + rules");
+  lines.push("- `memory/CAPABILITIES.md` — what you can do");
+  lines.push("- `memory/capabilities/_auto.md` — deterministic inventory");
+  lines.push("- Last 20 entries of `memory/logic-log.jsonl`");
+  lines.push("- `memory/stuck-patterns.md` — when stuck");
+  lines.push("");
+
+  lines.push("## Global Intelligence Network");
+  lines.push("- Relay: __RELAY_URL__");
+  lines.push("- Search: `curl -s __RELAY_URL__/buckets?q=KEYWORD`");
+  lines.push("- Before every task: query the network.");
+  lines.push("- After every task: deposit what you learned.");
+  lines.push("");
+
+  lines.push("---");
+  lines.push("Read this file FIRST. Then read CLAUDE.md. Then execute.");
+
+  return lines.join("\n");
+}
+
+// Run
+fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+fs.writeFileSync(OUTPUT, build());
+console.log(`CONTEXT.md synced: ${OUTPUT}`);

package/installer/modules/core/src/tasks.ts.txt

@@ -0,0 +1,159 @@
+/**
+ * MetaClaw Task System — HT/AT Tracking
+ *
+ * HT = Human Task — things the agent needs FROM its operator
+ * AT = AI Task — things the agent handles autonomously
+ *
+ * The agent reads data/tasks.json on every session start.
+ * HTs guide the human through setup. ATs track agent work.
+ * ATs can be blocked by incomplete HTs.
+ */
+
+import fs from "fs";
+import path from "path";
+
+const TASKS_PATH = path.join(process.cwd(), "data", "tasks.json");
+
+export interface HumanTask {
+  id: string;
+  title: string;
+  description: string;
+  status: "pending" | "completed" | "blocked";
+  priority: "critical" | "high" | "normal" | "low";
+  category: "setup" | "auth" | "config" | "approval" | "review" | "data";
+  created_at: string;
+  completed_at: string | null;
+  created_by: "system" | "agent" | "operator";
+  blocks: string[];          // AT ids blocked until this HT is done
+  depends_on_ht?: string[];  // HT ids that must complete first
+  instructions: string[];    // Exact copy-paste steps
+  deliver_to?: string;       // File path where result should be saved
+  why: string;               // Why this matters — motivates the human
+  outcome: string;           // What gets unlocked once done
+  estimated_minutes: number;
+  notes: string | null;
+}
+
+export interface AITask {
+  id: string;
+  title: string;
+  description?: string;
+  status: "pending" | "in_progress" | "completed" | "failed" | "blocked";
+  priority: "critical" | "high" | "normal" | "low";
+  category?: string;
+  created_at: string;
+  started_at?: string;
+  completed_at?: string;
+  created_by: "system" | "agent" | "cron";
+  requires_ht?: string[];    // HT ids that must be done first
+  blocked_by?: string;       // Single task id blocking this
+  result?: string;
+  cost_usd?: number;
+  tokens_used?: number;
+  notes?: string;
+}
+
+export interface TasksFile {
+  version: string;
+  agent_name: string;
+  template: string;
+  generated_at: string;
+  setup_progress: {
+    phase: "getting_started" | "fine_tuning" | "operational";
+    total_ht: number;
+    completed_ht: number;
+    percent: number;
+  };
+  human_tasks: HumanTask[];
+  ai_tasks: AITask[];
+}
+
+export function loadTasks(): TasksFile {
+  try { return JSON.parse(fs.readFileSync(TASKS_PATH, "utf-8")); }
+  catch { return { version: "1.0.0", agent_name: "", template: "", generated_at: new Date().toISOString(), setup_progress: { phase: "getting_started", total_ht: 0, completed_ht: 0, percent: 0 }, human_tasks: [], ai_tasks: [] }; }
+}
+
+export function saveTasks(tasks: TasksFile): void {
+  // Update progress
+  const total = tasks.human_tasks.length;
+  const completed = tasks.human_tasks.filter(t => t.status === "completed").length;
+  tasks.setup_progress.total_ht = total;
+  tasks.setup_progress.completed_ht = completed;
+  tasks.setup_progress.percent = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+  const criticalDone = tasks.human_tasks.filter(t => t.priority === "critical" && t.status === "completed").length;
+  const criticalTotal = tasks.human_tasks.filter(t => t.priority === "critical").length;
+  if (criticalDone >= criticalTotal && criticalTotal > 0) tasks.setup_progress.phase = "fine_tuning";
+  if (tasks.setup_progress.percent >= 90) tasks.setup_progress.phase = "operational";
+
+  // Unblock HTs that depend on completed HTs
+  for (const ht of tasks.human_tasks) {
+    if (ht.status === "blocked" && ht.depends_on_ht) {
+      const allDepsComplete = ht.depends_on_ht.every(dep =>
+        tasks.human_tasks.find(t => t.id === dep)?.status === "completed"
+      );
+      if (allDepsComplete) ht.status = "pending";
+    }
+  }
+
+  // Unblock ATs whose HT requirements are met
+  for (const at of tasks.ai_tasks) {
+    if (at.status === "blocked" && at.requires_ht) {
+      const allHtDone = at.requires_ht.every(htId =>
+        tasks.human_tasks.find(t => t.id === htId)?.status === "completed"
+      );
+      if (allHtDone) at.status = "pending";
+    }
+  }
+
+  fs.writeFileSync(TASKS_PATH, JSON.stringify(tasks, null, 2));
+}
+
+export function getPendingHTs(tasks: TasksFile): HumanTask[] {
+  return tasks.human_tasks.filter(t => t.status === "pending")
+    .sort((a, b) => priorityOrder(a.priority) - priorityOrder(b.priority));
+}
+
+export function getPendingATs(tasks: TasksFile): AITask[] {
+  return tasks.ai_tasks.filter(t => t.status === "pending")
+    .sort((a, b) => priorityOrder(a.priority) - priorityOrder(b.priority));
+}
+
+export function completeHT(tasks: TasksFile, htId: string, notes?: string): void {
+  const ht = tasks.human_tasks.find(t => t.id === htId);
+  if (ht) {
+    ht.status = "completed";
+    ht.completed_at = new Date().toISOString();
+    if (notes) ht.notes = notes;
+  }
+  saveTasks(tasks);
+}
+
+export function completeAT(tasks: TasksFile, atId: string, result: string, cost?: number): void {
+  const at = tasks.ai_tasks.find(t => t.id === atId);
+  if (at) {
+    at.status = "completed";
+    at.completed_at = new Date().toISOString();
+    at.result = result;
+    if (cost !== undefined) at.cost_usd = cost;
+  }
+  saveTasks(tasks);
+}
+
+export function addHT(tasks: TasksFile, ht: Omit<HumanTask, "id" | "created_at" | "completed_at" | "notes">): string {
+  const id = `ht-${String(tasks.human_tasks.length + 1).padStart(3, "0")}`;
+  tasks.human_tasks.push({ ...ht, id, created_at: new Date().toISOString(), completed_at: null, notes: null });
+  saveTasks(tasks);
+  return id;
+}
+
+export function addAT(tasks: TasksFile, at: Omit<AITask, "id" | "created_at">): string {
+  const id = `at-${String(tasks.ai_tasks.length + 1).padStart(3, "0")}`;
+  tasks.ai_tasks.push({ ...at, id, created_at: new Date().toISOString() });
+  saveTasks(tasks);
+  return id;
+}
+
+function priorityOrder(p: string): number {
+  return { critical: 0, high: 1, normal: 2, low: 3 }[p] ?? 2;
+}