@dv.nghiem/flowdeck 0.5.4 → 0.5.5

package/dist/index.js

@@ -1206,46 +1206,48 @@ var ORCHESTRATOR_PROMPT = `You are the FlowDeck Orchestrator. You coordinate mul
 - Run the entire coding workflow yourself
 
 Your ONLY job is to:
-1. **Analyze** the request
-2. **Classify** the task type and estimate complexity/risk/ambiguity
-3. **Choose** the appropriate workflow and execution path
-4. **Route** work to the correct agent or execution path
+1. **Evaluate** the request
+2. **Clarify** only when critical ambiguity exists
+3. **Route** to the correct workflow and agent
+4. **Delegate** via native \`@agent-name\` mentions
 5. **Supervise** progress
 6. **Collect** results
 7. **Return** the final coordinated outcome
 
-## Routing-First Protocol
+## The Orchestrator Loop
 
-For EVERY user request, you MUST follow this exact sequence BEFORE any execution begins:
+For EVERY turn, follow this exact sequence:
 
-### Step 1: Analyze
-- Read STATE.md if it exists
-- Identify current phase and workflow class
-- Understand what the user is asking for
+### 1. Evaluate
+- Read STATE.md if it exists.
+- Identify current phase, workflow class, and incomplete steps.
+- Classify the task type and estimate simplicity, confidence, risk, codebase familiarity, and complexity.
+- Check for critical ambiguity: missing requirements, conflicting constraints, or inability to choose a workflow class.
 
-### Step 2: Classify
-Estimate:
-- Simplicity: Is this a rename, typo fix, config update, or simple question?
-- Confidence: How well does the request match known patterns?
-- Risk: Blast radius (files touched) and sensitivity (auth, security, data)
-- Codebase familiarity: Is the codebase mapping fresh?
-- Complexity: Cheap (classify, validate, summarize) vs expensive (architect, refactor)
+### 2. Clarify (only if critical ambiguity exists)
+- If the request is too vague to classify confidently, ask the human ONE targeted clarifying question.
+- Frame the question with a default recommendation and rationale.
+- If ambiguity is not critical, make a reasonable routing decision instead of asking.
+- Never ask more than one question per turn.
 
-### Step 3: Choose Workflow
-Select ONE of these workflow classes:
+### 3. Route
+- Select the minimal sufficient workflow class (quick, standard, explore, ui-heavy, bugfix, docs-only, verify-heavy).
+- Choose the next stage based on the Workflow Decision injected into your context.
+- Emit a routing decision in the exact format below.
 
-| Workflow Class | Execution Path | When to Select |
-|----------------|---------------|----------------|
-| \`quick\` | Route to @default-executor with \`direct-stock-tools\` mode | Simple, low-risk tasks (< 5 files, no ambiguity) |
-| \`standard\` | Plan with @planner → Execute with specialists → Verify with @reviewer | Normal implementation tasks |
-| \`explore\` | Discuss with @discusser → Plan with @planner → Execute with specialists | Ambiguous or unfamiliar tasks |
-| \`ui-heavy\` | Discuss with @discusser → Design with @design → Plan with @planner → Execute with specialists | UI/UX-heavy tasks |
-| \`bugfix\` | Discuss with @discusser → Fix with @debug-specialist / @backend-coder → Verify with @tester | Bug fixes |
-| \`docs-only\` | Route to @default-executor with \`inspect-only\` or \`simple-edit\` mode, or @writer for large docs | Documentation-only changes |
-| \`verify-heavy\` | Plan with @planner (enhanced checks) → Execute with specialists → Verify with @reviewer + @security-auditor | High blast radius or sensitive paths |
+### 4. Delegate
+- Mention the target agent with \`@agent-name <full task description>\`.
+- Provide focused context: task, relevant files, and expected output.
+- Do NOT execute the work yourself.
+
+### 5. Supervise / Loop
+- When the delegated agent finishes, evaluate the result.
+- If the workflow is incomplete, return to step 3 and route the next stage.
+- If a specialist fails twice, escalate to @supervisor or ask the human.
+
+## Routing Decision Format
 
-### Step 4: Log the Decision
-Before routing, you MUST emit a routing decision in this exact format:
+Before delegating, you MUST emit a routing decision in this exact format:
 
 \`\`\`
 ## Routing Decision
@@ -1253,17 +1255,33 @@ Before routing, you MUST emit a routing decision in this exact format:
 **Request:** <brief summary of user request>
 **Classification:** <task type> | Confidence: <0.0-1.0>
 **Workflow Selected:** <workflow class>
-**Reason:** <why this workflow was chosen>
+**Next Stage:** <stage name from Workflow Decision>
+**Reason:** <why this workflow and stage were chosen>
 **Execution Path:** <which agent(s) will execute>
 **Estimated Blast Radius:** <number of files or "unknown">
 \`\`\`
 
-### Step 5: Route and Supervise
-- Use native OpenCode agent routing: mention the agent with \`@agent-name <full task description>\`
-- Provide clear, focused context including task description and any relevant files
-- Wait for completion
-- Collect results
-- If escalation is needed, log the escalation and re-route
+## Workflow Classes
+
+Select ONE of these workflow classes:
+
+| Workflow Class | Execution Path | When to Select |
+|----------------|---------------|----------------|
+| \`quick\` | Route to @default-executor with \`direct-stock-tools\` mode | Simple, low-risk tasks (< 5 files, no ambiguity) |
+| \`standard\` | Plan with @planner → Execute with specialists → Verify with @reviewer | Normal implementation tasks |
+| \`explore\` | Discuss with @discusser → Plan with @planner → Execute with specialists | Ambiguous or unfamiliar tasks |
+| \`ui-heavy\` | Discuss with @discusser → Design with @design → Plan with @planner → Execute with specialists | UI/UX-heavy tasks |
+| \`bugfix\` | Discuss with @discusser → Fix with @debug-specialist / @backend-coder → Verify with @tester | Bug fixes |
+| \`docs-only\` | Route to @default-executor with \`inspect-only\` or \`simple-edit\` mode, or @writer for large docs | Documentation-only changes |
+| \`verify-heavy\` | Plan with @planner (enhanced checks) → Execute with specialists → Verify with @reviewer + @security-auditor | High blast radius or sensitive paths |
+
+## Tool Guard Response Protocol
+
+If you receive a block message from the Orchestrator Guard (e.g., "The orchestrator cannot use \`write\` directly"), you MUST:
+1. STOP attempting that tool.
+2. NEVER retry the same blocked tool.
+3. Immediately delegate the action to the appropriate agent from the routing options in the message.
+4. Do NOT crash, stop, or tell the user you are blocked. Treat the message as a routing instruction.
 
 ## What You MAY Do Directly
 
@@ -1276,6 +1294,8 @@ You may ONLY use these tools directly:
 - **decision-trace** — Record decisions
 - **policy-engine** — Check policies
 - **reflect** — Gather session artifacts
+- **load-rules / list-rules** — Discover agent capabilities and rules
+- **council** — Synthesize consensus across specialists
 
 You may NEVER use:
 - write, write_file, create, create_file
@@ -1306,6 +1326,9 @@ When workflow class is \`standard\`, \`explore\`, \`ui-heavy\`, \`bugfix\`, or \
   - \`@reviewer\` — code quality review
   - \`@security-auditor\` — security review
   - \`@debug-specialist\` — root cause analysis
+  - \`@build-error-resolver\` — build/type errors
+  - \`@performance-optimizer\` — performance bottlenecks
+  - \`@refactor-guide\` — safe refactoring
 
 ### Parallel Execution Patterns
 
@@ -6342,104 +6365,616 @@ import { join as join19, basename as basename2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { dirname as dirname3 } from "path";
 
-// src/services/prompt-cache.ts
-import { createHash as createHash3 } from "crypto";
-var DEFAULT_PROMPT_CACHE_TTL_MS = 5 * 60 * 1000;
-
-class PromptCacheImpl {
-  store = new Map;
-  getKey(description, stage, languages) {
-    const normalized = description.trim().toLowerCase().replace(/\s+/g, " ");
-    const sortedLanguages = [...languages].sort().join(",");
-    const payload = `${normalized}|${stage}|${sortedLanguages}`;
-    return createHash3("sha256").update(payload).digest("hex");
-  }
-  get(key) {
-    const entry = this.store.get(key);
-    if (!entry)
-      return;
-    if (Date.now() >= entry.expiresAt) {
-      this.store.delete(key);
-      return;
-    }
-    return entry.fragment;
+// src/services/preflight-explorer.ts
+var QUESTION_KIND_PATTERNS = [
+  {
+    kind: "what-tech-stack",
+    patterns: ["tech stack", "language", "framework", "what are you using", "what tech", "built with", "written in"]
+  },
+  {
+    kind: "is-project-initialized",
+    patterns: ["initialized", "set up", "codebase mapped", "map-codebase", "new feature"]
+  },
+  {
+    kind: "what-is-current-phase",
+    patterns: ["current phase", "which phase", "what phase", "where are we", "current state"]
+  },
+  {
+    kind: "what-patterns-exist",
+    patterns: ["existing pattern", "how is it done", "how does the codebase", "pattern used", "architecture"]
+  },
+  {
+    kind: "is-ui-heavy",
+    patterns: ["ui", "frontend", "user interface", "webpage", "web app", "dashboard", "landing page", "screen"]
+  },
+  {
+    kind: "has-existing-tests",
+    patterns: ["test", "spec", "coverage", "tdd", "regression"]
+  },
+  {
+    kind: "has-existing-docs",
+    patterns: ["docs", "documentation", "readme", "api docs"]
+  },
+  {
+    kind: "has-ci-cd",
+    patterns: ["ci/cd", "continuous integration", "deploy", "pipeline", "github actions", ".github/workflow"]
+  },
+  {
+    kind: "what-agents-available",
+    patterns: ["which agent", "available agent", "what agent"]
+  },
+  {
+    kind: "what-commands-available",
+    patterns: ["which command", "available command", "what command", "slash command"]
+  },
+  {
+    kind: "what-skills-available",
+    patterns: ["skill", "available skill"]
+  },
+  {
+    kind: "has-prior-decisions",
+    patterns: ["prior decision", "previous discussion", "what was decided", "earlier session", "previous phase"]
+  },
+  {
+    kind: "has-governance",
+    patterns: ["governance", "policy", "approval", "supervisor"]
   }
-  set(key, fragment, ttlMs = DEFAULT_PROMPT_CACHE_TTL_MS) {
-    this.store.set(key, {
-      fragment,
-      expiresAt: Date.now() + Math.max(0, ttlMs)
-    });
+];
+function shouldSuppressQuestion(question, result, sessionHistory) {
+  const lower = question.toLowerCase();
+  const alreadyAsked = sessionHistory.some((h) => h.toLowerCase().trim() === lower.trim());
+  if (alreadyAsked) {
+    return {
+      suppress: true,
+      reason: "This question was already asked in the current session."
+    };
   }
-  invalidate() {
-    this.store.clear();
-    invalidateCache();
+  const matchedEvidence = result.evidenceItems.filter((ev) => {
+    const qKind = classifyQuestionKind(lower);
+    return qKind !== null && qKind === ev.answersQuestion;
+  });
+  if (matchedEvidence.length > 0) {
+    return {
+      suppress: true,
+      answeredByEvidence: true,
+      reason: `Answered by repo evidence: ${matchedEvidence.map((e) => e.summary).join("; ")}`,
+      evidence: matchedEvidence
+    };
   }
+  return { suppress: false };
 }
-var sharedPromptCache = new PromptCacheImpl;
-
-// src/services/token-metrics.ts
-var ESTIMATION_COEFFICIENTS = {
-  prose: 4,
-  code: 3.5,
-  json: 3.5
-};
-var usageByRun = new Map;
-function toPositiveInt(value) {
-  if (typeof value === "string") {
-    const n = Number(value);
-    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
+function refineClassification(clarificationPrompt, result, sessionHistory) {
+  const promptLower = clarificationPrompt.toLowerCase();
+  const isTaskTypeQuestion = result.hasProjectMD && (promptLower.includes("new feature") || promptLower.includes("bug fix") || promptLower.includes("ui change") || promptLower.includes("documentation") || promptLower.includes("describe the task") || promptLower.includes("more detail"));
+  if (isTaskTypeQuestion) {
+    return {
+      clarificationStillNeeded: false,
+      resolvedReason: "PROJECT.md exists — project is initialized. Defaulting ambiguous task to feature."
+    };
   }
-  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
-    return Math.floor(value);
+  const suppress = shouldSuppressQuestion(clarificationPrompt, result, sessionHistory);
+  if (suppress.suppress) {
+    return {
+      clarificationStillNeeded: false,
+      resolvedReason: suppress.reason
+    };
   }
-  return 0;
-}
-function getAccumulated(runId) {
-  return usageByRun.get(runId) ?? {
-    inputTokens: 0,
-    outputTokens: 0,
-    reasoningTokens: 0,
-    cacheReadTokens: 0,
-    cacheWriteTokens: 0,
-    messageCount: 0
+  const lines = [];
+  if (result.hasProjectMD)
+    lines.push("PROJECT.md is present (project is initialized).");
+  if (result.hasStateMD)
+    lines.push("STATE.md is present (project has active session).");
+  if (result.hasPriorDiscussions)
+    lines.push("Prior DISCUSS.md files exist.");
+  if (result.techStack.length > 0)
+    lines.push(`Tech stack: ${result.techStack.join(", ")}.`);
+  if (result.implementationPatterns.length > 0) {
+    lines.push(`Implementation patterns: ${result.implementationPatterns.join(", ")}.`);
+  }
+  return {
+    clarificationStillNeeded: true,
+    supervisorContext: lines.length > 0 ? lines.join(" ") : undefined
   };
 }
-function recordMessageUsage(runId, usage) {
-  const current = getAccumulated(runId);
-  const next = {
-    inputTokens: current.inputTokens + toPositiveInt(usage.input),
-    outputTokens: current.outputTokens + toPositiveInt(usage.output),
-    reasoningTokens: current.reasoningTokens + toPositiveInt(usage.reasoning),
-    cacheReadTokens: current.cacheReadTokens + toPositiveInt(usage.cache?.read),
-    cacheWriteTokens: current.cacheWriteTokens + toPositiveInt(usage.cache?.write),
-    messageCount: current.messageCount + 1
-  };
-  usageByRun.set(runId, next);
+var STOP_WORDS = new Set([
+  "with",
+  "that",
+  "this",
+  "from",
+  "into",
+  "when",
+  "then",
+  "will",
+  "have",
+  "been",
+  "does",
+  "should",
+  "would",
+  "could",
+  "after",
+  "before",
+  "about"
+]);
+function classifyQuestionKind(questionLower) {
+  for (const { kind, patterns } of QUESTION_KIND_PATTERNS) {
+    if (patterns.some((p) => questionLower.includes(p)))
+      return kind;
+  }
+  return null;
 }
-function getRunUsage(runId) {
-  const u = getAccumulated(runId);
+
+// src/services/workflow-router.ts
+function stage(name, command, requiresApproval, skippable, args) {
+  return { name, command, args, requiresApproval, skippable };
+}
+function scoreTaskForRouting(criteria) {
+  const simplicity = (criteria.taskType === "simple" ? 1 : 0) * 0.3;
+  const confidence = criteria.confidence * 0.2;
+  const lowRisk = !criteria.isSensitive && criteria.blastRadius < 3 ? 0.2 : 0;
+  const knownCodebase = criteria.codebaseFreshness === "fresh" ? 0.15 : 0;
+  const cheapComplexity = criteria.complexity === "cheap" ? 0.15 : 0;
+  const total = simplicity + confidence + lowRisk + knownCodebase + cheapComplexity;
   return {
-    runId,
-    totalTokens: u.inputTokens + u.outputTokens + u.reasoningTokens + u.cacheReadTokens + u.cacheWriteTokens,
-    inputTokens: u.inputTokens,
-    outputTokens: u.outputTokens,
-    reasoningTokens: u.reasoningTokens,
-    cacheReadTokens: u.cacheReadTokens,
-    cacheWriteTokens: u.cacheWriteTokens,
-    messageCount: u.messageCount
+    simplicity,
+    confidence,
+    lowRisk,
+    knownCodebase,
+    cheapComplexity,
+    total
   };
 }
-function estimateTokens(text, kind = "prose") {
-  if (!text || text.length === 0)
-    return 0;
-  const coefficient = ESTIMATION_COEFFICIENTS[kind] ?? ESTIMATION_COEFFICIENTS.prose;
-  return Math.max(0, Math.round(text.length / coefficient));
-}
-
-// src/services/context-ingress.ts
-var DEFAULT_OPTIONS = {
-  maxEvents: 20,
-  eventMaxAgeMinutes: 30,
+function buildAdaptiveStageSequence(criteria) {
+  const scores = scoreTaskForRouting(criteria);
+  const totalScore = scores.total;
+  let workflowClass;
+  let stages;
+  let reason;
+  if (totalScore >= 0.75 && (criteria.taskType === "simple" || criteria.taskType === "docs")) {
+    workflowClass = "quick";
+    stages = [
+      stage("execute", "fd-execute", false, true),
+      stage("verify", "fd-verify", false, true)
+    ];
+    reason = `Quick workflow: score ${totalScore.toFixed(2)} >= 0.75 for ${criteria.taskType} task`;
+  } else if (criteria.taskType === "bugfix") {
+    workflowClass = "bugfix";
+    stages = [
+      stage("discuss", "fd-discuss", false, false),
+      stage("fix-bug", "fd-fix-bug", false, false),
+      stage("verify", "fd-verify", false, false)
+    ];
+    reason = "Bugfix workflow: task type is bugfix";
+  } else if (criteria.taskType === "docs" && totalScore < 0.75) {
+    workflowClass = "docs-only";
+    stages = [
+      stage("write-docs", "fd-write-docs", false, false),
+      stage("verify", "fd-verify", false, true)
+    ];
+    reason = `Docs-only workflow: score ${totalScore.toFixed(2)} < 0.75 for docs task`;
+  } else if (criteria.taskType === "ui-feature") {
+    workflowClass = "ui-heavy";
+    stages = [
+      stage("discuss", "fd-discuss", false, false),
+      stage("design", "fd-design", false, false, "--mode=draft"),
+      stage("plan", "fd-plan", true, false),
+      stage("execute", "fd-execute", false, false),
+      stage("verify", "fd-verify", false, false)
+    ];
+    reason = "UI-heavy workflow: task type indicates UI-heavy work";
+  } else if (criteria.blastRadius >= 5 || criteria.isSensitive) {
+    workflowClass = "verify-heavy";
+    stages = [
+      stage("plan", "fd-plan", true, false),
+      stage("execute", "fd-execute", false, false),
+      stage("verify", "fd-verify", false, false)
+    ];
+    reason = `Verify-heavy workflow: blastRadius=${criteria.blastRadius}, isSensitive=${criteria.isSensitive}`;
+  } else if (criteria.confidence < 0.6 || criteria.taskType === "ambiguous") {
+    workflowClass = "explore";
+    stages = [
+      stage("discuss", "fd-discuss", false, false),
+      stage("plan", "fd-plan", true, false),
+      stage("execute", "fd-execute", false, false),
+      stage("verify", "fd-verify", false, false)
+    ];
+    reason = `Explore workflow: confidence=${criteria.confidence}, taskType=${criteria.taskType}`;
+  } else {
+    workflowClass = "standard";
+    stages = [
+      stage("plan", "fd-plan", true, false),
+      stage("execute", "fd-execute", false, false),
+      stage("verify", "fd-verify", false, false)
+    ];
+    reason = `Standard workflow: score ${totalScore.toFixed(2)} with taskType ${criteria.taskType}`;
+  }
+  return {
+    workflowClass,
+    stages,
+    criteria,
+    scores,
+    reason
+  };
+}
+
+// src/services/quick-router.ts
+var BUG_SIGNALS = [
+  "fix",
+  "bug",
+  "broken",
+  "not working",
+  "doesn't work",
+  "does not work",
+  "error",
+  "crash",
+  "regression",
+  "debug",
+  "exception",
+  "failing",
+  "fails",
+  "incorrect",
+  "wrong output",
+  "infinite loop",
+  "null pointer",
+  "undefined",
+  "404",
+  "500",
+  "stack trace",
+  "traceback",
+  "root cause",
+  "why is"
+];
+var UI_SIGNALS = [
+  "landing page",
+  "dashboard",
+  "admin panel",
+  "admin page",
+  "app screen",
+  "onboarding",
+  "onboard",
+  "wireframe",
+  "mockup",
+  "design system",
+  "component library",
+  "ui component",
+  "ux flow",
+  "user interface",
+  "web app",
+  "web application",
+  "website",
+  "frontend page",
+  "mobile screen",
+  "login page",
+  "signup page",
+  "settings page",
+  "profile page",
+  "modal",
+  "dialog",
+  "sidebar",
+  "navigation",
+  "navbar",
+  "header",
+  "footer",
+  "layout",
+  "responsive",
+  "accessibility",
+  "a11y",
+  "dark mode",
+  "theme"
+];
+var DOCS_SIGNALS = [
+  "docs",
+  "documentation",
+  "readme",
+  "api docs",
+  "usage guide",
+  "write docs",
+  "document",
+  "document the",
+  "how to use",
+  "tutorial",
+  "changelog",
+  "contributing guide",
+  "docstring",
+  "jsdoc",
+  "tsdoc"
+];
+var SIMPLE_SIGNALS = [
+  "rename",
+  "move file",
+  "quick",
+  "minor",
+  "small change",
+  "one-liner",
+  "typo",
+  "update constant",
+  "update config",
+  "bump version"
+];
+var AMBIGUOUS_PATTERNS = [
+  /^(improve|make|update|change|add|remove|help|do|run|check|use)\s+\w+$/i
+];
+function classifyTask(description) {
+  const lower = description.toLowerCase().trim();
+  if (!lower) {
+    return _ambiguous([], "What task do you want to run? Please describe what you need done.");
+  }
+  const bugHits = BUG_SIGNALS.filter((s) => lower.includes(s));
+  const uiHits = UI_SIGNALS.filter((s) => lower.includes(s));
+  const docsHits = DOCS_SIGNALS.filter((s) => lower.includes(s));
+  const simpleHits = SIMPLE_SIGNALS.filter((s) => lower.includes(s));
+  const bugScore = Math.min(bugHits.length * 0.35, 1);
+  const uiScore = Math.min(uiHits.length * 0.3, 1);
+  const docsScore = Math.min(docsHits.length * 0.4, 1);
+  const simpleScore = Math.min(simpleHits.length * 0.45, 1);
+  if (bugScore >= 0.35 && bugScore >= uiScore && bugScore >= docsScore) {
+    return {
+      taskType: "bugfix",
+      confidence: Math.min(0.5 + bugScore * 0.5, 0.98),
+      signals: bugHits,
+      requiresDesign: false,
+      requiresTDD: true,
+      stageSequence: buildStageSequence("bugfix"),
+      clarificationNeeded: bugScore < 0.5,
+      clarificationPrompt: bugScore < 0.5 ? "Can you describe the specific bug? What is the expected vs actual behavior?" : undefined
+    };
+  }
+  if (uiScore >= 0.3) {
+    return {
+      taskType: "ui-feature",
+      confidence: Math.min(0.5 + uiScore * 0.45, 0.95),
+      signals: uiHits,
+      requiresDesign: true,
+      requiresTDD: true,
+      stageSequence: buildStageSequence("ui-feature"),
+      clarificationNeeded: false
+    };
+  }
+  if (docsScore >= 0.4 && docsScore >= bugScore) {
+    return {
+      taskType: "docs",
+      confidence: Math.min(0.55 + docsScore * 0.4, 0.95),
+      signals: docsHits,
+      requiresDesign: false,
+      requiresTDD: false,
+      stageSequence: buildStageSequence("docs"),
+      clarificationNeeded: false
+    };
+  }
+  if (simpleScore >= 0.45) {
+    return {
+      taskType: "simple",
+      confidence: Math.min(0.55 + simpleScore * 0.35, 0.9),
+      signals: simpleHits,
+      requiresDesign: false,
+      requiresTDD: false,
+      stageSequence: buildStageSequence("simple"),
+      clarificationNeeded: false
+    };
+  }
+  const wordCount = lower.split(/\s+/).filter(Boolean).length;
+  if (wordCount >= 5) {
+    return {
+      taskType: "feature",
+      confidence: Math.min(0.5 + wordCount * 0.02, 0.85),
+      signals: [],
+      requiresDesign: false,
+      requiresTDD: true,
+      stageSequence: buildStageSequence("feature"),
+      clarificationNeeded: wordCount < 8,
+      clarificationPrompt: wordCount < 8 ? "Is this a new feature, a bug fix, or a documentation task? A bit more context will help route it correctly." : undefined
+    };
+  }
+  const isAmbiguousPattern = AMBIGUOUS_PATTERNS.some((p) => p.test(lower));
+  if (isAmbiguousPattern || wordCount < 5) {
+    return _ambiguous([], "Can you describe the task in more detail? For example: is it a new feature, a bug fix, a UI change, or documentation?");
+  }
+  return {
+    taskType: "feature",
+    confidence: 0.6,
+    signals: [],
+    requiresDesign: false,
+    requiresTDD: true,
+    stageSequence: buildStageSequence("feature"),
+    clarificationNeeded: false
+  };
+}
+function _ambiguous(signals, prompt) {
+  return {
+    taskType: "ambiguous",
+    confidence: 0,
+    signals,
+    requiresDesign: false,
+    requiresTDD: false,
+    stageSequence: [],
+    clarificationNeeded: true,
+    clarificationPrompt: prompt
+  };
+}
+function buildStageSequence(taskType) {
+  switch (taskType) {
+    case "feature":
+      return [
+        stage2("discuss", "fd-discuss", false, false),
+        stage2("plan", "fd-plan", true, false),
+        stage2("execute", "fd-execute", false, false),
+        stage2("verify", "fd-verify", false, false)
+      ];
+    case "ui-feature":
+      return [
+        stage2("discuss", "fd-discuss", false, false),
+        stage2("design", "fd-design", false, false, "--mode=draft"),
+        stage2("plan", "fd-plan", true, false),
+        stage2("execute", "fd-execute", false, false),
+        stage2("verify", "fd-verify", false, false)
+      ];
+    case "bugfix":
+      return [
+        stage2("discuss", "fd-discuss", false, false),
+        stage2("fix-bug", "fd-fix-bug", false, false),
+        stage2("verify", "fd-verify", false, false)
+      ];
+    case "docs":
+      return [
+        stage2("discuss", "fd-discuss", false, false),
+        stage2("write-docs", "fd-write-docs", false, false),
+        stage2("verify", "fd-verify", false, true)
+      ];
+    case "simple":
+      return [
+        stage2("execute", "fd-execute", false, false),
+        stage2("verify", "fd-verify", false, true)
+      ];
+    case "ambiguous":
+      return [];
+    default:
+      return [];
+  }
+}
+function buildAdaptiveWorkflow(description, exploration) {
+  const base = exploration ? classifyTaskWithContext(description, exploration) : classifyTask(description);
+  const complexityResult = classifyTaskComplexity(description);
+  const criteria = {
+    taskType: base.taskType,
+    complexity: complexityResult.complexity,
+    confidence: base.confidence,
+    blastRadius: 0,
+    isSensitive: false,
+    codebaseFreshness: exploration ? "fresh" : "unknown",
+    requiresTests: base.requiresTDD
+  };
+  const route = buildAdaptiveStageSequence(criteria);
+  return {
+    ...base,
+    stageSequence: route.stages,
+    workflowClass: route.workflowClass,
+    scores: route.scores
+  };
+}
+function stage2(name, command, requiresApproval, skippable, args) {
+  return { name, command, args, requiresApproval, skippable };
+}
+function classifyTaskWithContext(description, exploration, sessionHistory = []) {
+  const base = classifyTask(description);
+  if (!base.clarificationNeeded) {
+    return base;
+  }
+  const refinement = refineClassification(base.clarificationPrompt ?? "", exploration, sessionHistory);
+  if (!refinement.clarificationStillNeeded) {
+    const resolvedType = base.taskType === "ambiguous" ? "feature" : base.taskType;
+    return {
+      ...base,
+      taskType: resolvedType,
+      stageSequence: buildStageSequence(resolvedType),
+      clarificationNeeded: false,
+      clarificationPrompt: undefined,
+      confidence: Math.max(base.confidence, 0.55)
+    };
+  }
+  const enrichedPrompt = refinement.supervisorContext ? `${base.clarificationPrompt ?? ""} (Context: ${refinement.supervisorContext})` : base.clarificationPrompt;
+  return {
+    ...base,
+    clarificationPrompt: enrichedPrompt
+  };
+}
+
+// src/services/prompt-cache.ts
+import { createHash as createHash3 } from "crypto";
+var DEFAULT_PROMPT_CACHE_TTL_MS = 5 * 60 * 1000;
+
+class PromptCacheImpl {
+  store = new Map;
+  getKey(description, stage3, languages) {
+    const normalized = description.trim().toLowerCase().replace(/\s+/g, " ");
+    const sortedLanguages = [...languages].sort().join(",");
+    const payload = `${normalized}|${stage3}|${sortedLanguages}`;
+    return createHash3("sha256").update(payload).digest("hex");
+  }
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry)
+      return;
+    if (Date.now() >= entry.expiresAt) {
+      this.store.delete(key);
+      return;
+    }
+    return entry.fragment;
+  }
+  set(key, fragment, ttlMs = DEFAULT_PROMPT_CACHE_TTL_MS) {
+    this.store.set(key, {
+      fragment,
+      expiresAt: Date.now() + Math.max(0, ttlMs)
+    });
+  }
+  invalidate() {
+    this.store.clear();
+    invalidateCache();
+  }
+}
+var sharedPromptCache = new PromptCacheImpl;
+
+// src/services/token-metrics.ts
+var ESTIMATION_COEFFICIENTS = {
+  prose: 4,
+  code: 3.5,
+  json: 3.5
+};
+var usageByRun = new Map;
+function toPositiveInt(value) {
+  if (typeof value === "string") {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
+  }
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return Math.floor(value);
+  }
+  return 0;
+}
+function getAccumulated(runId) {
+  return usageByRun.get(runId) ?? {
+    inputTokens: 0,
+    outputTokens: 0,
+    reasoningTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    messageCount: 0
+  };
+}
+function recordMessageUsage(runId, usage) {
+  const current = getAccumulated(runId);
+  const next = {
+    inputTokens: current.inputTokens + toPositiveInt(usage.input),
+    outputTokens: current.outputTokens + toPositiveInt(usage.output),
+    reasoningTokens: current.reasoningTokens + toPositiveInt(usage.reasoning),
+    cacheReadTokens: current.cacheReadTokens + toPositiveInt(usage.cache?.read),
+    cacheWriteTokens: current.cacheWriteTokens + toPositiveInt(usage.cache?.write),
+    messageCount: current.messageCount + 1
+  };
+  usageByRun.set(runId, next);
+}
+function getRunUsage(runId) {
+  const u = getAccumulated(runId);
+  return {
+    runId,
+    totalTokens: u.inputTokens + u.outputTokens + u.reasoningTokens + u.cacheReadTokens + u.cacheWriteTokens,
+    inputTokens: u.inputTokens,
+    outputTokens: u.outputTokens,
+    reasoningTokens: u.reasoningTokens,
+    cacheReadTokens: u.cacheReadTokens,
+    cacheWriteTokens: u.cacheWriteTokens,
+    messageCount: u.messageCount
+  };
+}
+function estimateTokens(text, kind = "prose") {
+  if (!text || text.length === 0)
+    return 0;
+  const coefficient = ESTIMATION_COEFFICIENTS[kind] ?? ESTIMATION_COEFFICIENTS.prose;
+  return Math.max(0, Math.round(text.length / coefficient));
+}
+
+// src/services/context-ingress.ts
+var DEFAULT_OPTIONS = {
+  maxEvents: 20,
+  eventMaxAgeMinutes: 30,
   planTruncateThreshold: 8000,
   planTruncateTo: 4000,
   totalTokenBudget: Number(process.env.FLOWDECK_CONTEXT_LIMIT) || 200000
@@ -6664,9 +7199,10 @@ class ContextIngressService {
     const codebaseDocs = trivial.isTrivialChat ? {} : this.readCodebaseDocs(input.projectRoot);
     const recentEvents = trivial.isTrivialChat ? [] : this.readRecentEvents(input.projectRoot);
     const route = this.buildRoute(input.description);
+    const workflowDecision = input.workflowDecision ?? buildAdaptiveWorkflow(input.description);
     const relevantRules = trivial.isTrivialChat ? [] : this.selectRelevantRules(input.projectRoot, input.description, state, route, input.currentStage);
     const relevantSkills = trivial.isTrivialChat ? [] : this.selectRelevantSkills(input.description);
-    const used = estimateTokens(JSON.stringify(state), "json") + estimateTokens(planContent, "prose") + estimateTokens(JSON.stringify(codebaseDocs), "prose") + estimateTokens(JSON.stringify(recentEvents), "json") + estimateTokens(JSON.stringify(relevantRules), "json") + estimateTokens(JSON.stringify(relevantSkills), "json");
+    const used = estimateTokens(JSON.stringify(state), "json") + estimateTokens(planContent, "prose") + estimateTokens(JSON.stringify(codebaseDocs), "prose") + estimateTokens(JSON.stringify(recentEvents), "json") + estimateTokens(JSON.stringify(relevantRules), "json") + estimateTokens(JSON.stringify(relevantSkills), "json") + estimateTokens(JSON.stringify(workflowDecision), "json");
     const total = this.options.totalTokenBudget;
     const actualUsage = getRunUsage(input.sessionId);
     const hasActualTokens = actualUsage.totalTokens > 0;
@@ -6689,7 +7225,8 @@ class ContextIngressService {
       recentEvents,
       selectedRules: relevantRules,
       selectedSkills: relevantSkills,
-      tokenBudget
+      tokenBudget,
+      workflowDecision
     };
     this._assembledBySession.set(input.sessionId, ctx);
     this.persistBudgetSnapshot(ctx);
@@ -6716,12 +7253,12 @@ class ContextIngressService {
     }
   }
   buildPromptFragment(ctx) {
-    const stage = String(ctx.planningState.phase ?? "discuss");
+    const stage3 = String(ctx.planningState.phase ?? "discuss");
     if (ctx.isTrivialChat) {
-      return `Greeting. Phase: ${stage}.`;
+      return `Greeting. Phase: ${stage3}.`;
     }
     const languages = getCachedLanguages(ctx.directory);
-    const cacheKey = sharedPromptCache.getKey(ctx.description, stage, languages);
+    const cacheKey = sharedPromptCache.getKey(ctx.description, stage3, languages);
     const cached = sharedPromptCache.get(cacheKey);
     if (cached)
       return cached;
@@ -6729,7 +7266,7 @@ class ContextIngressService {
       "# FlowDeck Context",
       "",
       `Task: ${ctx.description}`,
-      `Phase: ${stage}`,
+      `Phase: ${stage3}`,
       "",
       "## Selected rules"
     ];
@@ -6756,6 +7293,22 @@ class ContextIngressService {
       lines.push(`blockers: ${ctx.planningState.blockers.join(", ")}`);
     }
     lines.push(`next_action: ${ctx.planningState.next_action}`);
+    lines.push("", "## Workflow Decision");
+    const decision = ctx.workflowDecision;
+    if (decision) {
+      lines.push(`workflowClass: ${decision.workflowClass ?? decision.taskType}`);
+      lines.push(`taskType: ${decision.taskType}`);
+      lines.push(`confidence: ${decision.confidence.toFixed(2)}`);
+      lines.push(`requiresDesign: ${decision.requiresDesign}`);
+      lines.push(`requiresTDD: ${decision.requiresTDD}`);
+      lines.push(`stageSequence: ${decision.stageSequence.map((s) => s.name).join(" → ")}`);
+      if (decision.clarificationNeeded) {
+        lines.push(`clarificationNeeded: true`);
+        lines.push(`clarificationPrompt: ${decision.clarificationPrompt ?? "(none provided)"}`);
+      }
+    } else {
+      lines.push("_No workflow decision available._");
+    }
     lines.push("", "## Recent events");
     if (ctx.recentEvents.length === 0) {
       lines.push("_No recent events._");
@@ -6776,7 +7329,8 @@ class ContextIngressService {
     const eventsTokens = estimateTokens(JSON.stringify(ctx.recentEvents), "json");
     const rulesTokens = estimateTokens(JSON.stringify(ctx.selectedRules), "json");
     const skillsTokens = estimateTokens(JSON.stringify(ctx.selectedSkills), "json");
-    const totalFallbackTokens = stateTokens + planTokens + docsTokens + eventsTokens + rulesTokens + skillsTokens;
+    const workflowTokens = estimateTokens(JSON.stringify(ctx.workflowDecision), "json");
+    const totalFallbackTokens = stateTokens + planTokens + docsTokens + eventsTokens + rulesTokens + skillsTokens + workflowTokens;
     const actualUsage = getRunUsage(ctx.sessionID);
     const hasActualTokens = actualUsage.totalTokens > 0;
     const totalUsed = hasActualTokens ? actualUsage.totalTokens : ctx.tokenBudget.usedTokens;
@@ -6805,7 +7359,8 @@ class ContextIngressService {
       docs: makeSnapshot("docs", docsTokens),
       events: makeSnapshot("events", eventsTokens),
       rules: makeSnapshot("rules", rulesTokens),
-      skills: makeSnapshot("skills", skillsTokens)
+      skills: makeSnapshot("skills", skillsTokens),
+      workflow: makeSnapshot("workflow", workflowTokens)
     };
   }
   getTotalBudget(sessionID) {
@@ -6918,12 +7473,12 @@ class ContextIngressService {
     const sharedDir = join19(__dir, "..", "agents", "shared");
     if (!existsSync19(rulesDir))
       return [];
-    const stage = currentStage ?? this.inferStageFromRoute(route);
+    const stage3 = currentStage ?? this.inferStageFromRoute(route);
     const languages = getCachedLanguages(projectRoot);
-    const cacheKey = `${projectRoot}\x00${stage ?? ""}\x00${[...languages].sort().join(",")}`;
+    const cacheKey = `${projectRoot}\x00${stage3 ?? ""}\x00${[...languages].sort().join(",")}`;
     let selection = ruleSelectionCache.get(cacheKey);
     if (!selection) {
-      selection = selectRulePaths(rulesDir, { languages, stage });
+      selection = selectRulePaths(rulesDir, { languages, stage: stage3 });
       ruleSelectionCache.set(cacheKey, selection);
     }
     const seen = new Set;
@@ -7289,8 +7844,8 @@ class LoopDetector {
 var CONTRACTS = [
   {
     agent: "orchestrator",
-    role: "Coordinate multi-agent execution, inspect context directly, and route specialist work when appropriate.",
-    allowedTaskTypes: ["orchestration", "coordination", "delegation", "phase-management"],
+    role: "Coordinate multi-agent execution, inspect context directly, and route specialist work via native @agent-name mentions.",
+    allowedTaskTypes: ["orchestration", "coordination", "routing", "phase-management"],
     requiredInputs: ["STATE.md", "PLAN.md"],
     expectedOutputFields: ["completed_steps", "current_phase"],
     allowedTools: [
@@ -7585,55 +8140,302 @@ var CONTRACTS = [
     escalationConditions: ["documentation scope unclear"],
     stopConditions: ["docs written", "user confirms completeness"],
     successCriteria: [
-      "documentation written and accurate",
-      "no application code changed"
+      "documentation written and accurate",
+      "no application code changed"
+    ]
+  },
+  {
+    agent: "doc-updater",
+    role: "Update existing documentation after code changes.",
+    allowedTaskTypes: ["documentation-update", "doc-sync"],
+    requiredInputs: ["changed files", "change summary"],
+    expectedOutputFields: ["updated_docs"],
+    allowedTools: ["read", "write", "edit", "glob", "grep"],
+    forbiddenActions: [
+      "modify application code",
+      "delete documentation without replacement"
+    ],
+    escalationConditions: ["documentation conflicts with implementation"],
+    stopConditions: ["docs updated and synced"],
+    successCriteria: ["docs reflect current code", "no application code changed"]
+  },
+  {
+    agent: "mapper",
+    role: "Map codebase to structured documentation files in .codebase/.",
+    allowedTaskTypes: ["codebase-mapping", "documentation", "indexing"],
+    requiredInputs: ["project root"],
+    expectedOutputFields: ["codebase_docs"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "modify application source code",
+      "delete existing docs without replacement"
+    ],
+    escalationConditions: ["mapping conflicts with existing .codebase/ files"],
+    stopConditions: ["codebase docs written"],
+    successCriteria: [".codebase/ docs reflect current structure", "no application code changed"]
+  },
+  {
+    agent: "supervisor",
+    role: "Governance review layer. Inspects existing commands/agents, validates policy, returns structured approve/revise/block/escalate decision. Never creates new commands or workflows.",
+    allowedTaskTypes: ["governance-review", "policy-check", "pre-execution-review", "post-stage-review"],
+    requiredInputs: ["target name (command or agent)", "task context"],
+    expectedOutputFields: ["decision", "targetType", "targetName", "exists", "reasons", "missingRequirements", "riskFlags", "requiredChanges", "approvalStatus", "confidenceScore"],
+    allowedTools: ["read", "glob", "grep", "planning-state", "policy-engine"],
+    forbiddenActions: [
+      "create new commands",
+      "create new workflows",
+      "invent new agent names",
+      "modify command intent",
+      "replace orchestrator",
+      "become second dispatcher",
+      "execute implementation tasks",
+      "write or edit source files",
+      "run bash commands",
+      "modify PLAN.md or STATE.md"
+    ],
+    escalationConditions: [
+      "human approval required and not granted",
+      "confidence below threshold",
+      "critical policy violation with no safe path forward"
+    ],
+    stopConditions: ["structured decision issued", "review complete"],
+    successCriteria: [
+      "structured SupervisorDecision returned",
+      "no new commands or workflows created",
+      "existing registry not modified",
+      "decision is one of: approve, revise, block, escalate"
+    ]
+  },
+  {
+    agent: "default-executor",
+    role: "Execute simple, direct tasks routed by the orchestrator using full tool access.",
+    allowedTaskTypes: ["execution", "quick-fix", "simple-edit", "inspect-only", "quick-answer"],
+    requiredInputs: ["task description", "execution mode"],
+    expectedOutputFields: ["files_touched", "summary", "verification"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "orchestrate other agents",
+      "delegate to other agents",
+      "expand scope silently",
+      "invent new workflows"
+    ],
+    escalationConditions: [
+      "task touches more than 5 files",
+      "architectural decision needed",
+      "security-sensitive path encountered"
+    ],
+    stopConditions: ["task complete", "escalation required"],
+    successCriteria: [
+      "task completed as routed",
+      "scope not expanded",
+      "verification performed"
+    ]
+  },
+  {
+    agent: "code-explorer",
+    role: "Explore and map unfamiliar codebases before changes. Read-only analysis.",
+    allowedTaskTypes: ["exploration", "code-mapping", "call-path-tracing"],
+    requiredInputs: ["area or feature to explore"],
+    expectedOutputFields: ["structure", "entry_points", "key_components", "call_paths"],
+    allowedTools: [
+      "read",
+      "glob",
+      "grep",
+      "codegraph",
+      "codegraph-search",
+      "codegraph-node",
+      "codegraph-explore"
+    ],
+    forbiddenActions: [
+      "modify files",
+      "implement changes",
+      "run destructive commands"
+    ],
+    escalationConditions: ["codebase index missing and exploration blocked"],
+    stopConditions: ["exploration report complete"],
+    successCriteria: [
+      "report delivered",
+      "no files modified"
+    ]
+  },
+  {
+    agent: "debug-specialist",
+    role: "Diagnose bugs through systematic root cause analysis. Report only, do not implement fixes directly.",
+    allowedTaskTypes: ["debugging", "root-cause-analysis", "bug-investigation"],
+    requiredInputs: ["bug report or failure output"],
+    expectedOutputFields: ["root_cause", "evidence", "call_path", "recommended_fix"],
+    allowedTools: ["read", "glob", "grep", "bash"],
+    forbiddenActions: [
+      "implement fixes directly",
+      "suppress errors without fixing",
+      "modify application code"
+    ],
+    escalationConditions: [
+      "architectural problem found",
+      "security issue discovered"
+    ],
+    stopConditions: ["debug report complete"],
+    successCriteria: [
+      "root cause identified",
+      "fix recommended",
+      "no implementation done"
+    ]
+  },
+  {
+    agent: "build-error-resolver",
+    role: "Fix build errors, compilation failures, and dependency issues with minimal changes.",
+    allowedTaskTypes: ["build-fix", "type-error-fix", "dependency-fix"],
+    requiredInputs: ["build error output"],
+    expectedOutputFields: ["files_modified", "summary", "verification"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "use as any or @ts-ignore to suppress type errors",
+      "refactor unrelated code",
+      "add features while fixing builds"
+    ],
+    escalationConditions: [
+      "architectural problem causing build failure",
+      "security issue discovered"
+    ],
+    stopConditions: ["build passes", "escalation required"],
+    successCriteria: [
+      "build and type check pass",
+      "minimum changes applied",
+      "no type-safety suppression without explanation"
+    ]
+  },
+  {
+    agent: "task-splitter",
+    role: "Decompose complex tasks into parallel workstreams with explicit dependencies.",
+    allowedTaskTypes: ["task-decomposition", "parallel-planning"],
+    requiredInputs: ["complex task description"],
+    expectedOutputFields: ["waves", "dependencies", "agent_assignments"],
+    allowedTools: ["read", "glob", "grep", "planning-state"],
+    forbiddenActions: [
+      "execute tasks",
+      "modify files",
+      "assign non-existent agents"
+    ],
+    escalationConditions: ["task too small to benefit from parallelization"],
+    stopConditions: ["parallel execution plan complete"],
+    successCriteria: [
+      "plan delivered",
+      "dependencies clear",
+      "no file modifications"
+    ]
+  },
+  {
+    agent: "discusser",
+    role: "Extract requirements via structured Q&A and record decisions with D-XX numbering.",
+    allowedTaskTypes: ["requirements-gathering", "discussion", "decision-recording"],
+    requiredInputs: ["task description"],
+    expectedOutputFields: ["decisions", "suppressed_questions", "open_questions"],
+    allowedTools: ["read", "write", "edit", "glob", "grep", "planning-state"],
+    forbiddenActions: [
+      "implement features",
+      "skip decision recording",
+      "ask more than one question per turn"
+    ],
+    escalationConditions: ["conflict with prior decisions"],
+    stopConditions: ["requirements complete", "plan ready"],
+    successCriteria: [
+      "decisions recorded",
+      "no open questions remain"
+    ]
+  },
+  {
+    agent: "risk-analyst",
+    role: "Assess risk of proposed changes using patch trust and regression signals. Read-only.",
+    allowedTaskTypes: ["risk-assessment", "change-impact-analysis"],
+    requiredInputs: ["change description", "trust signals"],
+    expectedOutputFields: ["risk_level", "approval_required", "safer_alternative"],
+    allowedTools: ["read", "glob", "grep"],
+    forbiddenActions: [
+      "modify files",
+      "approve changes directly",
+      "invent risk signals not in input data"
+    ],
+    escalationConditions: ["critical risk identified"],
+    stopConditions: ["risk report complete"],
+    successCriteria: [
+      "structured report delivered",
+      "no file modifications"
+    ]
+  },
+  {
+    agent: "policy-enforcer",
+    role: "Apply policy gate matrix to decide whether a proposed edit can proceed. Read-only decision.",
+    allowedTaskTypes: ["policy-enforcement", "gate-decision"],
+    requiredInputs: ["file_path", "change_description", "policy_violations", "risk_score"],
+    expectedOutputFields: ["decision", "trigger", "recommended_action"],
+    allowedTools: ["read", "glob", "grep", "policy-engine"],
+    forbiddenActions: [
+      "modify files",
+      "deviate from gate matrix",
+      "approve blocked changes"
+    ],
+    escalationConditions: ["arch constraint violation"],
+    stopConditions: ["gate decision issued"],
+    successCriteria: [
+      "decision applied per matrix",
+      "no file modifications"
     ]
   },
   {
-    agent: "doc-updater",
-    role: "Update existing documentation after code changes.",
-    allowedTaskTypes: ["documentation-update", "doc-sync"],
-    requiredInputs: ["changed files", "change summary"],
-    expectedOutputFields: ["updated_docs"],
-    allowedTools: ["read", "write", "edit", "glob", "grep"],
+    agent: "performance-optimizer",
+    role: "Identify and fix performance bottlenecks using profiling data and measurements.",
+    allowedTaskTypes: ["performance-optimization", "profiling", "bottleneck-analysis"],
+    requiredInputs: ["performance complaint or metric"],
+    expectedOutputFields: ["baseline", "bottleneck", "fix", "after_measurement"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
     forbiddenActions: [
-      "modify application code",
-      "delete documentation without replacement"
+      "optimize without measurements",
+      "refactor unrelated code",
+      "skip before/after verification"
     ],
-    escalationConditions: ["documentation conflicts with implementation"],
-    stopConditions: ["docs updated and synced"],
-    successCriteria: ["docs reflect current code", "no application code changed"]
+    escalationConditions: ["architectural bottleneck requiring redesign"],
+    stopConditions: ["performance report complete"],
+    successCriteria: [
+      "before and after measurements provided",
+      "improvement verified"
+    ]
   },
   {
-    agent: "supervisor",
-    role: "Governance review layer. Inspects existing commands/agents, validates policy, returns structured approve/revise/block/escalate decision. Never creates new commands or workflows.",
-    allowedTaskTypes: ["governance-review", "policy-check", "pre-execution-review", "post-stage-review"],
-    requiredInputs: ["target name (command or agent)", "task context"],
-    expectedOutputFields: ["decision", "targetType", "targetName", "exists", "reasons", "missingRequirements", "riskFlags", "requiredChanges", "approvalStatus", "confidenceScore"],
-    allowedTools: ["read", "glob", "grep", "planning-state", "policy-engine"],
+    agent: "refactor-guide",
+    role: "Guide safe refactoring without changing behavior.",
+    allowedTaskTypes: ["refactoring", "code-cleanup", "structure-improvement"],
+    requiredInputs: ["refactoring target"],
+    expectedOutputFields: ["transformations", "test_results"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
     forbiddenActions: [
-      "create new commands",
-      "create new workflows",
-      "invent new agent names",
-      "modify command intent",
-      "replace orchestrator",
-      "become second dispatcher",
-      "execute implementation tasks",
-      "write or edit source files",
-      "run bash commands",
-      "modify PLAN.md or STATE.md"
+      "add features",
+      "leave tests failing",
+      "combine multiple transformations in one step"
     ],
-    escalationConditions: [
-      "human approval required and not granted",
-      "confidence below threshold",
-      "critical policy violation with no safe path forward"
+    escalationConditions: ["tests fail during refactor"],
+    stopConditions: ["refactor complete", "tests green"],
+    successCriteria: [
+      "behavior preserved",
+      "tests pass"
+    ]
+  },
+  {
+    agent: "auto-learner",
+    role: "Capture reusable knowledge from session artifacts as skills.",
+    allowedTaskTypes: ["knowledge-capture", "skill-creation"],
+    requiredInputs: ["session reflection artifacts"],
+    expectedOutputFields: ["skills_created", "summary"],
+    allowedTools: ["read", "reflect", "write"],
+    forbiddenActions: [
+      "ask user questions",
+      "create routine skills",
+      "create more than 3 skills per session"
     ],
-    stopConditions: ["structured decision issued", "review complete"],
+    escalationConditions: ["no valuable patterns found"],
+    stopConditions: ["skills written or no new skills identified"],
     successCriteria: [
-      "structured SupervisorDecision returned",
-      "no new commands or workflows created",
-      "existing registry not modified",
-      "decision is one of: approve, revise, block, escalate"
+      "valuable patterns captured",
+      "maximum 3 skills per session"
     ]
   }
 ];
@@ -7641,6 +8443,9 @@ var REGISTRY = new Map(CONTRACTS.map((c) => [c.agent, c]));
 function getContract(agent) {
   return REGISTRY.get(agent) ?? null;
 }
+function getAllContracts() {
+  return [...CONTRACTS];
+}
 
 // src/services/agent-validator.ts
 function resolveValidatorMode(directory) {
@@ -7742,2040 +8547,1528 @@ function validateAgentOutput(agent, output) {
           detail: `Agent "${agent}" output missing expected field "${field}"`,
           severity: "warn"
         });
-      }
-    }
-  }
-  const hasBlock = violations.some((v) => v.severity === "block");
-  const hasWarn = violations.some((v) => v.severity === "warn");
-  let action;
-  if (!hasBlock && !hasWarn) {
-    action = "allow";
-  } else if (hasBlock) {
-    action = "block";
-  } else {
-    action = "warn";
-  }
-  return {
-    agent,
-    valid: violations.length === 0,
-    action,
-    violations,
-    message: violations.length > 0 ? violations.map((v) => `[${v.rule}] ${v.detail}`).join("; ") : undefined
-  };
-}
-function validateToolAccess(directory, agent, toolName, opts = {}) {
-  return validateAgent(directory, { agent, toolUsed: toolName, ...opts });
-}
-
-// src/services/supervisor-binding.ts
-var REGISTERED_COMMANDS = [
-  "fd-ask",
-  "fd-checkpoint",
-  "fd-deploy-check",
-  "fd-design",
-  "fd-discuss",
-  "fd-doctor",
-  "fd-execute",
-  "fd-fix-bug",
-  "fd-guarded-edit",
-  "fd-map-codebase",
-  "fd-multi-repo",
-  "fd-new-feature",
-  "fd-plan",
-  "fd-quick",
-  "fd-reflect",
-  "fd-resume",
-  "fd-status",
-  "fd-suggest",
-  "fd-translate-intent",
-  "fd-verify",
-  "fd-write-docs",
-  "fd-done"
-];
-function resolveSupervisorConfig(directory) {
-  try {
-    const config = loadFlowDeckConfig(directory);
-    const sup = config.governance?.supervisor ?? {};
-    return {
-      enabled: sup.enabled ?? true,
-      mode: sup.mode ?? "advisory",
-      reviewedTargets: sup.reviewedTargets ?? [],
-      canBlock: sup.canBlock ?? true,
-      confidenceThreshold: sup.confidenceThreshold ?? 0.7,
-      postExecutionReview: sup.postExecutionReview ?? false
-    };
-  } catch {
-    return {
-      enabled: true,
-      mode: "advisory",
-      reviewedTargets: [],
-      canBlock: true,
-      confidenceThreshold: 0.7,
-      postExecutionReview: false
-    };
-  }
-}
-function isRegisteredCommand(name) {
-  return REGISTERED_COMMANDS.includes(name);
-}
-function isRegisteredAgent(name) {
-  return AGENT_NAMES.includes(name);
-}
-function isRegisteredTarget(name) {
-  if (isRegisteredCommand(name))
-    return { exists: true, type: "command" };
-  if (isRegisteredAgent(name))
-    return { exists: true, type: "agent" };
-  return { exists: false, type: "agent" };
-}
-function checkCommandPolicy(commandName, ctx) {
-  const reasons = [];
-  const riskFlags = [];
-  const missingRequirements = [];
-  const requiredChanges = [];
-  if (commandName === "fd-new-feature" || commandName === "fd-execute") {
-    const workflowClass = ctx.workflowClass;
-    if (workflowClass !== "quick" && workflowClass !== "docs-only") {
-      const taskLower = (ctx.taskDescription ?? "").toLowerCase();
-      const isUiHeavy = /landing page|dashboard|admin panel|website|web app|ui|ux|interface|frontend|component/.test(taskLower);
-      if (isUiHeavy && ctx.currentPhase === "execute" && ctx.designApprovalPresent === false) {
-        missingRequirements.push("design approval (design stage must complete before execute for UI-heavy tasks)");
-        riskFlags.push("UI-heavy task entering execute phase without design approval");
-        requiredChanges.push("Run /fd-design first and obtain design approval before proceeding to execute");
-      }
-    }
-  }
-  if (commandName === "fd-fix-bug") {
-    if (ctx.regressionTestPresent === false) {
-      missingRequirements.push("regression test (required before bugfix implementation)");
-      riskFlags.push("Bugfix command invoked without a regression test");
-      requiredChanges.push("Write a failing regression test before implementing the fix");
-    }
-  }
-  if (commandName === "fd-deploy-check") {
-    if (ctx.prerequisitesMet === false && ctx.missingInputs && ctx.missingInputs.length > 0) {
-      missingRequirements.push(...ctx.missingInputs);
-      riskFlags.push("Deploy check attempted with unmet prerequisites");
-    }
-  }
-  if (commandName === "fd-execute" && ctx.currentPhase && ctx.currentPhase !== "execute") {
-    const workflowClass = ctx.workflowClass;
-    const isQuick = workflowClass === "quick" || workflowClass === "docs-only";
-    if (!isQuick) {
-      riskFlags.push(`fd-execute invoked in phase "${ctx.currentPhase}" instead of "execute"`);
-      requiredChanges.push(`Ensure project phase is "execute" before running fd-execute (currently: ${ctx.currentPhase})`);
-    }
-  }
-  if (ctx.approvalRequired && !ctx.approvalGranted) {
-    missingRequirements.push("human approval (required for this command)");
-    riskFlags.push("Approval gate not satisfied");
-    requiredChanges.push("Obtain explicit human approval before proceeding");
-  }
-  const passed = missingRequirements.length === 0 && riskFlags.length === 0 && requiredChanges.length === 0;
-  if (passed) {
-    reasons.push(`Command "${commandName}" passed all policy checks`);
-  }
-  return { passed, reasons, riskFlags, missingRequirements, requiredChanges };
-}
-function checkAgentPolicy(agentName, ctx) {
-  const reasons = [];
-  const riskFlags = [];
-  const missingRequirements = [];
-  const requiredChanges = [];
-  const contract = getContract(agentName);
-  if (!contract) {
-    riskFlags.push(`Agent "${agentName}" has no registered capability contract`);
-    return { passed: false, reasons, riskFlags, missingRequirements, requiredChanges };
-  }
-  if (ctx.missingInputs && ctx.missingInputs.length > 0) {
-    for (const missing of ctx.missingInputs) {
-      const isRequired = contract.requiredInputs.some((r) => r.toLowerCase().includes(missing.toLowerCase()) || missing.toLowerCase().includes(r.toLowerCase()));
-      if (isRequired) {
-        missingRequirements.push(missing);
-        requiredChanges.push(`Provide "${missing}" before delegating to ${agentName}`);
-      }
-    }
-  }
-  if (ctx.approvalRequired && !ctx.approvalGranted) {
-    const needsApproval = contract.escalationConditions.some((c) => c.toLowerCase().includes("approval") || c.toLowerCase().includes("approve"));
-    if (needsApproval) {
-      missingRequirements.push("human approval");
-      riskFlags.push(`Agent "${agentName}" requires approval via escalation condition`);
-      requiredChanges.push("Obtain explicit human approval before proceeding");
-    }
-  }
-  if (agentName === "design" || agentName === "frontend-coder") {
-    const taskLower = (ctx.taskDescription ?? "").toLowerCase();
-    const isUiHeavy = /landing page|dashboard|admin panel|website|web app|ui|ux|interface|frontend|component/.test(taskLower);
-    if (agentName === "frontend-coder" && isUiHeavy && ctx.designApprovalPresent === false) {
-      missingRequirements.push("design handoff approval");
-      riskFlags.push("frontend-coder invoked for UI-heavy task without approved design handoff");
-      requiredChanges.push("Complete design stage and obtain design approval before delegating to frontend-coder");
-    }
-  }
-  const passed = missingRequirements.length === 0 && riskFlags.length === 0;
-  if (passed) {
-    reasons.push(`Agent "${agentName}" passed all policy checks`);
-  }
-  return { passed, reasons, riskFlags, missingRequirements, requiredChanges };
-}
-function computeConfidence(exists, policyResult, ctx) {
-  if (!exists)
-    return 0;
-  if (policyResult.riskFlags.length >= 3)
-    return 0.2;
-  if (policyResult.riskFlags.length === 2)
-    return 0.4;
-  if (policyResult.riskFlags.length === 1)
-    return 0.6;
-  if (policyResult.missingRequirements.length > 0)
-    return 0.5;
-  if (ctx.prerequisitesMet === false)
-    return 0.45;
-  return 0.95;
-}
-function resolveDecision(exists, policyResult, confidenceScore, threshold, ctx, clarificationQuestion) {
-  if (!exists) {
-    return { decision: "block", approvalStatus: "denied" };
-  }
-  if (ctx.approvalRequired && !ctx.approvalGranted) {
-    return { decision: "escalate", approvalStatus: "escalated", clarificationQuestion };
-  }
-  if (!policyResult.passed) {
-    if (policyResult.requiredChanges.length > 0) {
-      return { decision: "revise", approvalStatus: "pending" };
+      }
     }
-    return { decision: "block", approvalStatus: "denied" };
   }
-  if (confidenceScore < threshold) {
-    return { decision: "escalate", approvalStatus: "escalated", clarificationQuestion };
+  const hasBlock = violations.some((v) => v.severity === "block");
+  const hasWarn = violations.some((v) => v.severity === "warn");
+  let action;
+  if (!hasBlock && !hasWarn) {
+    action = "allow";
+  } else if (hasBlock) {
+    action = "block";
+  } else {
+    action = "warn";
   }
-  return { decision: "approve", approvalStatus: "approved" };
+  return {
+    agent,
+    valid: violations.length === 0,
+    action,
+    violations,
+    message: violations.length > 0 ? violations.map((v) => `[${v.rule}] ${v.detail}`).join("; ") : undefined
+  };
 }
-function runSupervisorReview(directory, targetName, ctx = {}, clarificationQuestion) {
-  const config = resolveSupervisorConfig(directory);
-  const reviewPhase = ctx.reviewPhase ?? "preflight";
-  const timestamp3 = new Date().toISOString();
-  if (config.reviewedTargets.length > 0 && !config.reviewedTargets.includes(targetName)) {
+function validateToolAccess(directory, agent, toolName, opts = {}) {
+  return validateAgent(directory, { agent, toolUsed: toolName, ...opts });
+}
+
+// src/services/supervisor-binding.ts
+var REGISTERED_COMMANDS = [
+  "fd-ask",
+  "fd-checkpoint",
+  "fd-deploy-check",
+  "fd-design",
+  "fd-discuss",
+  "fd-doctor",
+  "fd-execute",
+  "fd-fix-bug",
+  "fd-guarded-edit",
+  "fd-map-codebase",
+  "fd-multi-repo",
+  "fd-new-feature",
+  "fd-plan",
+  "fd-quick",
+  "fd-reflect",
+  "fd-resume",
+  "fd-status",
+  "fd-suggest",
+  "fd-translate-intent",
+  "fd-verify",
+  "fd-write-docs",
+  "fd-done"
+];
+function resolveSupervisorConfig(directory) {
+  try {
+    const config = loadFlowDeckConfig(directory);
+    const sup = config.governance?.supervisor ?? {};
     return {
-      decision: "approve",
-      targetType: "agent",
-      targetName,
-      exists: true,
-      reasons: [`Target "${targetName}" is not in the reviewed targets list — auto-approved`],
-      missingRequirements: [],
-      riskFlags: [],
-      requiredChanges: [],
-      approvalStatus: "approved",
-      confidenceScore: 1,
-      reviewPhase,
-      timestamp: timestamp3
+      enabled: sup.enabled ?? true,
+      mode: sup.mode ?? "advisory",
+      reviewedTargets: sup.reviewedTargets ?? [],
+      canBlock: sup.canBlock ?? true,
+      confidenceThreshold: sup.confidenceThreshold ?? 0.7,
+      postExecutionReview: sup.postExecutionReview ?? false
     };
-  }
-  const { exists, type: targetType } = isRegisteredTarget(targetName);
-  if (!exists) {
-    const decision2 = {
-      decision: "block",
-      targetType,
-      targetName,
-      exists: false,
-      reasons: [
-        `Target "${targetName}" is not registered in the FlowDeck command or agent registry.`,
-        "The supervisor does not create new commands or workflows.",
-        "Only registered targets can be executed."
-      ],
-      missingRequirements: [],
-      riskFlags: [`Unregistered target: "${targetName}"`],
-      requiredChanges: [
-        `Use one of the registered commands: ${REGISTERED_COMMANDS.join(", ")}`,
-        `Or use one of the registered agents: ${AGENT_NAMES.join(", ")}`
-      ],
-      approvalStatus: "denied",
-      confidenceScore: 0,
-      reviewPhase,
-      timestamp: timestamp3
+  } catch {
+    return {
+      enabled: true,
+      mode: "advisory",
+      reviewedTargets: [],
+      canBlock: true,
+      confidenceThreshold: 0.7,
+      postExecutionReview: false
     };
-    return decision2;
   }
-  const policyResult = targetType === "command" ? checkCommandPolicy(targetName, ctx) : checkAgentPolicy(targetName, ctx);
-  const confidenceScore = computeConfidence(exists, policyResult, ctx);
-  const { decision, approvalStatus, clarificationQuestion: escalationQuestion } = resolveDecision(exists, policyResult, confidenceScore, config.confidenceThreshold, ctx, clarificationQuestion);
-  const reasons = policyResult.reasons.length > 0 ? policyResult.reasons : decision === "approve" ? [`Target "${targetName}" reviewed and approved for execution`] : [`Target "${targetName}" reviewed — decision: ${decision}`];
-  const supervisorDecision = {
-    decision,
-    targetType,
-    targetName,
-    exists,
-    reasons,
-    missingRequirements: policyResult.missingRequirements,
-    riskFlags: policyResult.riskFlags,
-    requiredChanges: policyResult.requiredChanges,
-    approvalStatus,
-    confidenceScore,
-    reviewPhase,
-    timestamp: timestamp3,
-    ...escalationQuestion ? { clarificationQuestion: escalationQuestion } : {}
-  };
-  return supervisorDecision;
 }
-function reviewToolCall(directory, input) {
-  const targetName = input.agent;
-  const ctx = {
-    taskDescription: input.assembledContext?.description,
-    currentPhase: input.currentStage,
-    workflowClass: input.workflowClass,
-    designApprovalPresent: input.assembledContext?.planningState?.design_approved ?? false,
-    run_id: input.runId,
-    session_id: input.sessionID,
-    reviewPhase: "preflight"
-  };
-  const review = runSupervisorReview(directory, targetName, ctx);
-  const riskFlags = review.riskFlags;
-  const baseReason = review.reasons.join("; ");
-  switch (review.decision) {
-    case "approve":
-      return {
-        verdict: "allow",
-        reason: baseReason,
-        riskFlags,
-        source: "supervisor"
-      };
-    case "block":
-      return {
-        verdict: "deny",
-        reason: baseReason,
-        riskFlags,
-        source: "supervisor",
-        escalationMessage: review.requiredChanges.length > 0 ? review.requiredChanges.join("; ") : `Supervisor blocked ${targetName}`
-      };
-    case "revise":
-      return {
-        verdict: "ask",
-        reason: baseReason,
-        riskFlags,
-        source: "supervisor"
-      };
-    case "escalate":
-      return {
-        verdict: "ask",
-        reason: baseReason + (review.clarificationQuestion ? ` ${review.clarificationQuestion}` : ""),
-        riskFlags,
-        source: "supervisor"
-      };
-  }
+function isRegisteredCommand(name) {
+  return REGISTERED_COMMANDS.includes(name);
 }
-
-// src/hooks/tool-guard.ts
-import { existsSync as existsSync20, readFileSync as readFileSync20 } from "fs";
-import { join as join20 } from "path";
-
-// src/lib/task-routing.ts
-var UI_HEAVY_KEYWORDS = [
-  "landing page",
-  "marketing site",
-  "website",
-  "web app",
-  "mobile app",
-  "app screen",
-  "dashboard",
-  "admin panel",
-  "settings page",
-  "onboarding ux",
-  "kanban",
-  "design system",
-  "responsive",
-  "ui",
-  "ux",
-  "cta",
-  "conversion flow",
-  "saas interface",
-  "user-facing"
-];
-var NON_UI_KEYWORDS = [
-  "backend",
-  "infrastructure",
-  "migration",
-  "pipeline",
-  "api only",
-  "database only",
-  "cli",
-  "worker"
-];
-function isUiHeavyTask(input) {
-  const normalized = input.trim().toLowerCase();
-  if (!normalized)
-    return false;
-  const hasUiSignal = UI_HEAVY_KEYWORDS.some((keyword) => normalized.includes(keyword));
-  if (!hasUiSignal)
-    return false;
-  const hasOnlyNonUiSignals = NON_UI_KEYWORDS.some((keyword) => normalized.includes(keyword)) && !normalized.includes("frontend");
-  return !hasOnlyNonUiSignals;
+function isRegisteredAgent(name) {
+  return AGENT_NAMES.includes(name);
 }
-
-// src/hooks/tool-guard.ts
-var BLOCKED_PATTERNS = {
-  read: [".env", ".pem", ".key", ".secret"],
-  write: ["node_modules"],
-  bash: [
-    "rm -rf",
-    "rm -fr",
-    "rm --recursive --force",
-    "rm -r -f",
-    "mkfs",
-    "mkfs.ext4",
-    "mkfs.ext3",
-    "mkfs.xfs",
-    "mkfs.btrfs",
-    "dd if=",
-    "dd of=",
-    "chmod 777 /",
-    "chmod -r 777 /",
-    "mv / /dev/null",
-    ">/dev/sda",
-    ":(){ :|:& };:"
-  ]
-};
-function extractTargetPath(args) {
-  return String(args?.path ?? args?.file_path ?? args?.filename ?? args?.filePath ?? "");
+function isRegisteredTarget(name) {
+  if (isRegisteredCommand(name))
+    return { exists: true, type: "command" };
+  if (isRegisteredAgent(name))
+    return { exists: true, type: "agent" };
+  return { exists: false, type: "agent" };
 }
-function normalizeBashCommand(cmd) {
-  let normalized = cmd.toLowerCase().replace(/#.*$/gm, "").replace(/\s+/g, " ").replace(/\s*;\s*/g, "; ").replace(/\s*\|\s*/g, " | ").replace(/--recursive/g, "-r").replace(/--force/g, "-f").trim();
-  let prev = normalized;
-  while (true) {
-    const next = prev.replace(/(\s-[a-z])\s+-([a-z])/g, "$1$2");
-    if (next === prev)
-      break;
-    prev = next;
+function checkCommandPolicy(commandName, ctx) {
+  const reasons = [];
+  const riskFlags = [];
+  const missingRequirements = [];
+  const requiredChanges = [];
+  if (commandName === "fd-new-feature" || commandName === "fd-execute") {
+    const workflowClass = ctx.workflowClass;
+    if (workflowClass !== "quick" && workflowClass !== "docs-only") {
+      const taskLower = (ctx.taskDescription ?? "").toLowerCase();
+      const isUiHeavy = /landing page|dashboard|admin panel|website|web app|ui|ux|interface|frontend|component/.test(taskLower);
+      if (isUiHeavy && ctx.currentPhase === "execute" && ctx.designApprovalPresent === false) {
+        missingRequirements.push("design approval (design stage must complete before execute for UI-heavy tasks)");
+        riskFlags.push("UI-heavy task entering execute phase without design approval");
+        requiredChanges.push("Run /fd-design first and obtain design approval before proceeding to execute");
+      }
+    }
   }
-  return prev;
-}
-function isPipedToShell(normalized) {
-  const segments = normalized.split(" | ").map((s) => s.trim());
-  const downloaders = new Set(["curl", "wget"]);
-  const shells = new Set(["sh", "bash", "zsh", "fish"]);
-  for (let i = 0;i < segments.length - 1; i++) {
-    const first = segments[i].split(/\s+/)[0];
-    const next = segments[i + 1].split(/\s+/)[0];
-    if (downloaders.has(first) && shells.has(next))
-      return true;
+  if (commandName === "fd-fix-bug") {
+    if (ctx.regressionTestPresent === false) {
+      missingRequirements.push("regression test (required before bugfix implementation)");
+      riskFlags.push("Bugfix command invoked without a regression test");
+      requiredChanges.push("Write a failing regression test before implementing the fix");
+    }
   }
-  return false;
-}
-function isBashCommandDangerous(cmd) {
-  const normalized = normalizeBashCommand(cmd);
-  for (const p of BLOCKED_PATTERNS.bash) {
-    if (normalized.includes(p)) {
-      return `FLOWDECK: Dangerous bash command blocked (matched "${p}").`;
+  if (commandName === "fd-deploy-check") {
+    if (ctx.prerequisitesMet === false && ctx.missingInputs && ctx.missingInputs.length > 0) {
+      missingRequirements.push(...ctx.missingInputs);
+      riskFlags.push("Deploy check attempted with unmet prerequisites");
     }
   }
-  if (isPipedToShell(normalized)) {
-    return "FLOWDECK: Piping curl/wget directly to a shell is blocked.";
+  if (commandName === "fd-execute" && ctx.currentPhase && ctx.currentPhase !== "execute") {
+    const workflowClass = ctx.workflowClass;
+    const isQuick = workflowClass === "quick" || workflowClass === "docs-only";
+    if (!isQuick) {
+      riskFlags.push(`fd-execute invoked in phase "${ctx.currentPhase}" instead of "execute"`);
+      requiredChanges.push(`Ensure project phase is "execute" before running fd-execute (currently: ${ctx.currentPhase})`);
+    }
   }
-  if (/\bdd\b/.test(normalized) && /\/dev\/(sd|hd|nvme|mmcblk|disk)/.test(normalized)) {
-    return "FLOWDECK: dd command targeting a block device is blocked.";
+  if (ctx.approvalRequired && !ctx.approvalGranted) {
+    missingRequirements.push("human approval (required for this command)");
+    riskFlags.push("Approval gate not satisfied");
+    requiredChanges.push("Obtain explicit human approval before proceeding");
   }
-  if (/:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*}\s*;\s*:/.test(normalized)) {
-    return "FLOWDECK: Fork bomb pattern is blocked.";
+  const passed = missingRequirements.length === 0 && riskFlags.length === 0 && requiredChanges.length === 0;
+  if (passed) {
+    reasons.push(`Command "${commandName}" passed all policy checks`);
   }
-  return null;
+  return { passed, reasons, riskFlags, missingRequirements, requiredChanges };
 }
-function isBlocked(tool13, args) {
-  const patterns = BLOCKED_PATTERNS[tool13];
-  if (!patterns)
-    return null;
-  if (tool13 === "bash") {
-    const cmd = args.command;
-    if (!cmd)
-      return null;
-    return isBashCommandDangerous(cmd);
+function checkAgentPolicy(agentName, ctx) {
+  const reasons = [];
+  const riskFlags = [];
+  const missingRequirements = [];
+  const requiredChanges = [];
+  const contract = getContract(agentName);
+  if (!contract) {
+    riskFlags.push(`Agent "${agentName}" has no registered capability contract`);
+    return { passed: false, reasons, riskFlags, missingRequirements, requiredChanges };
   }
-  if (tool13 === "read" || tool13 === "write") {
-    const filePath = extractTargetPath(args);
-    if (!filePath)
-      return null;
-    for (const p of patterns) {
-      if (filePath.includes(p)) {
-        return tool13 === "read" ? `FLOWDECK: Access to "${p}" files is blocked.` : `FLOWDECK: Writing to "${p}" is blocked.`;
+  if (ctx.missingInputs && ctx.missingInputs.length > 0) {
+    for (const missing of ctx.missingInputs) {
+      const isRequired = contract.requiredInputs.some((r) => r.toLowerCase().includes(missing.toLowerCase()) || missing.toLowerCase().includes(r.toLowerCase()));
+      if (isRequired) {
+        missingRequirements.push(missing);
+        requiredChanges.push(`Provide "${missing}" before delegating to ${agentName}`);
       }
     }
-    return null;
   }
-  return null;
-}
-function checkArchConstraint(directory, filePath) {
-  const constraintsPath = join20(codebaseDir(directory), "CONSTRAINTS.md");
-  if (!existsSync20(constraintsPath))
-    return null;
-  try {
-    const content = readFileSync20(constraintsPath, "utf-8");
-    const match = content.match(/## Forbidden Paths\n([\s\S]*?)(?:\n##|$)/);
-    if (!match)
-      return null;
-    for (const line of match[1].split(`
-`)) {
-      const pattern = line.replace(/^-\s*/, "").split("#")[0].trim();
-      if (pattern && filePath.includes(pattern)) {
-        return `FLOWDECK [arch-constraint]: editing "${pattern}" is forbidden by .codebase/CONSTRAINTS.md`;
-      }
-    }
-  } catch {}
-  return null;
-}
-function checkPhaseEnforcement(directory) {
-  try {
-    const state = readPlanningState(directory);
-    const flowdeckConfig = resolveDesignFirstConfig(loadFlowDeckConfig(directory));
-    if (state.phase > 0 && state.phase < 3) {
-      return `FLOWDECK [phase-gate]: writing to codebase is blocked in phase ${state.phase} (${state.phase === 1 ? "discuss" : "plan"}). Run /fd-plan --confirm to enter execute phase.`;
+  if (ctx.approvalRequired && !ctx.approvalGranted) {
+    const needsApproval = contract.escalationConditions.some((c) => c.toLowerCase().includes("approval") || c.toLowerCase().includes("approve"));
+    if (needsApproval) {
+      missingRequirements.push("human approval");
+      riskFlags.push(`Agent "${agentName}" requires approval via escalation condition`);
+      requiredChanges.push("Obtain explicit human approval before proceeding");
     }
-    if (flowdeckConfig.enabled && flowdeckConfig.requireApprovalBeforeImplementation && isUiDesignApprovalRequired(directory)) {
-      if (flowdeckConfig.enforcement === "advisory") {
-        return `FLOWDECK [design-gate]: advisory design-first mode detected missing approval. Run /fd-design --mode=draft or set design_override=true in STATE.md.`;
-      }
-      return `FLOWDECK [design-gate]: UI-heavy task requires approved design handoff before implementation. Run /fd-design --mode=draft and ensure design_stage=handoff_complete + design_approved=true, or set explicit design_override with reason.`;
+  }
+  if (agentName === "design" || agentName === "frontend-coder") {
+    const taskLower = (ctx.taskDescription ?? "").toLowerCase();
+    const isUiHeavy = /landing page|dashboard|admin panel|website|web app|ui|ux|interface|frontend|component/.test(taskLower);
+    if (agentName === "frontend-coder" && isUiHeavy && ctx.designApprovalPresent === false) {
+      missingRequirements.push("design handoff approval");
+      riskFlags.push("frontend-coder invoked for UI-heavy task without approved design handoff");
+      requiredChanges.push("Complete design stage and obtain design approval before delegating to frontend-coder");
     }
-  } catch {}
-  return null;
-}
-function isUiDesignApprovalRequired(directory) {
-  const state = readPlanningState(directory);
-  if (state.design_override && state.design_override_reason && state.design_override_reason.trim().length > 0)
-    return false;
-  if (state.requires_design_first) {
-    return !(state.design_stage === "handoff_complete" && state.design_approved);
   }
-  if (state.task_type && isUiHeavyTask(state.task_type)) {
-    return !(state.design_stage === "handoff_complete" && state.design_approved);
+  const passed = missingRequirements.length === 0 && riskFlags.length === 0;
+  if (passed) {
+    reasons.push(`Agent "${agentName}" passed all policy checks`);
   }
-  const planPath = phasePlanPath(directory, state.phase || 1);
-  if (!existsSync20(planPath))
-    return false;
-  const planContent = readFileSync20(planPath, "utf-8");
-  if (!isUiHeavyTask(planContent))
-    return false;
-  return !(state.design_stage === "handoff_complete" && state.design_approved);
+  return { passed, reasons, riskFlags, missingRequirements, requiredChanges };
 }
-function allow(reason, riskFlags = []) {
-  return { verdict: "allow", reason, riskFlags, source: "tool-guard" };
+function computeConfidence(exists, policyResult, ctx) {
+  if (!exists)
+    return 0;
+  if (policyResult.riskFlags.length >= 3)
+    return 0.2;
+  if (policyResult.riskFlags.length === 2)
+    return 0.4;
+  if (policyResult.riskFlags.length === 1)
+    return 0.6;
+  if (policyResult.missingRequirements.length > 0)
+    return 0.5;
+  if (ctx.prerequisitesMet === false)
+    return 0.45;
+  return 0.95;
 }
-function deny(reason, escalationMessage, riskFlags = []) {
-  return {
-    verdict: "deny",
-    reason,
-    riskFlags,
-    source: "tool-guard",
-    escalationMessage
+function resolveDecision(exists, policyResult, confidenceScore, threshold, ctx, clarificationQuestion) {
+  if (!exists) {
+    return { decision: "block", approvalStatus: "denied" };
+  }
+  if (ctx.approvalRequired && !ctx.approvalGranted) {
+    return { decision: "escalate", approvalStatus: "escalated", clarificationQuestion };
+  }
+  if (!policyResult.passed) {
+    if (policyResult.requiredChanges.length > 0) {
+      return { decision: "revise", approvalStatus: "pending" };
+    }
+    return { decision: "block", approvalStatus: "denied" };
+  }
+  if (confidenceScore < threshold) {
+    return { decision: "escalate", approvalStatus: "escalated", clarificationQuestion };
+  }
+  return { decision: "approve", approvalStatus: "approved" };
+}
+function runSupervisorReview(directory, targetName, ctx = {}, clarificationQuestion) {
+  const config = resolveSupervisorConfig(directory);
+  const reviewPhase = ctx.reviewPhase ?? "preflight";
+  const timestamp3 = new Date().toISOString();
+  if (config.reviewedTargets.length > 0 && !config.reviewedTargets.includes(targetName)) {
+    return {
+      decision: "approve",
+      targetType: "agent",
+      targetName,
+      exists: true,
+      reasons: [`Target "${targetName}" is not in the reviewed targets list — auto-approved`],
+      missingRequirements: [],
+      riskFlags: [],
+      requiredChanges: [],
+      approvalStatus: "approved",
+      confidenceScore: 1,
+      reviewPhase,
+      timestamp: timestamp3
+    };
+  }
+  const { exists, type: targetType } = isRegisteredTarget(targetName);
+  if (!exists) {
+    const decision2 = {
+      decision: "block",
+      targetType,
+      targetName,
+      exists: false,
+      reasons: [
+        `Target "${targetName}" is not registered in the FlowDeck command or agent registry.`,
+        "The supervisor does not create new commands or workflows.",
+        "Only registered targets can be executed."
+      ],
+      missingRequirements: [],
+      riskFlags: [`Unregistered target: "${targetName}"`],
+      requiredChanges: [
+        `Use one of the registered commands: ${REGISTERED_COMMANDS.join(", ")}`,
+        `Or use one of the registered agents: ${AGENT_NAMES.join(", ")}`
+      ],
+      approvalStatus: "denied",
+      confidenceScore: 0,
+      reviewPhase,
+      timestamp: timestamp3
+    };
+    return decision2;
+  }
+  const policyResult = targetType === "command" ? checkCommandPolicy(targetName, ctx) : checkAgentPolicy(targetName, ctx);
+  const confidenceScore = computeConfidence(exists, policyResult, ctx);
+  const { decision, approvalStatus, clarificationQuestion: escalationQuestion } = resolveDecision(exists, policyResult, confidenceScore, config.confidenceThreshold, ctx, clarificationQuestion);
+  const reasons = policyResult.reasons.length > 0 ? policyResult.reasons : decision === "approve" ? [`Target "${targetName}" reviewed and approved for execution`] : [`Target "${targetName}" reviewed — decision: ${decision}`];
+  const supervisorDecision = {
+    decision,
+    targetType,
+    targetName,
+    exists,
+    reasons,
+    missingRequirements: policyResult.missingRequirements,
+    riskFlags: policyResult.riskFlags,
+    requiredChanges: policyResult.requiredChanges,
+    approvalStatus,
+    confidenceScore,
+    reviewPhase,
+    timestamp: timestamp3,
+    ...escalationQuestion ? { clarificationQuestion: escalationQuestion } : {}
   };
+  return supervisorDecision;
 }
-function evaluate(input) {
-  const { directory, tool: tool13, args } = input;
-  if (tool13 !== "bash" && tool13 !== "read" && tool13 !== "write" && tool13 !== "edit") {
-    return allow("Tool is not guardable");
-  }
-  const blocked = isBlocked(tool13, args);
-  if (blocked) {
-    return deny(blocked, blocked, ["dangerous-pattern"]);
-  }
-  if (tool13 === "write" || tool13 === "edit") {
-    const phaseBlock = checkPhaseEnforcement(directory);
-    if (phaseBlock) {
-      const isAdvisory = phaseBlock.includes("[design-gate]: advisory");
-      if (isAdvisory) {
-        return allow(phaseBlock, ["design-gate-advisory"]);
-      }
-      return deny(phaseBlock, phaseBlock, ["phase-gate"]);
-    }
-    const filePath = extractTargetPath(args);
-    const constraintBlock = checkArchConstraint(directory, filePath);
-    if (constraintBlock) {
-      return deny(constraintBlock, constraintBlock, ["arch-constraint"]);
-    }
+function reviewToolCall(directory, input) {
+  const targetName = input.agent;
+  const ctx = {
+    taskDescription: input.assembledContext?.description,
+    currentPhase: input.currentStage,
+    workflowClass: input.workflowClass,
+    designApprovalPresent: input.assembledContext?.planningState?.design_approved ?? false,
+    run_id: input.runId,
+    session_id: input.sessionID,
+    reviewPhase: "preflight"
+  };
+  const review = runSupervisorReview(directory, targetName, ctx);
+  const riskFlags = review.riskFlags;
+  const baseReason = review.reasons.join("; ");
+  switch (review.decision) {
+    case "approve":
+      return {
+        verdict: "allow",
+        reason: baseReason,
+        riskFlags,
+        source: "supervisor"
+      };
+    case "block":
+      return {
+        verdict: "deny",
+        reason: baseReason,
+        riskFlags,
+        source: "supervisor",
+        escalationMessage: review.requiredChanges.length > 0 ? review.requiredChanges.join("; ") : `Supervisor blocked ${targetName}`
+      };
+    case "revise":
+      return {
+        verdict: "ask",
+        reason: baseReason,
+        riskFlags,
+        source: "supervisor"
+      };
+    case "escalate":
+      return {
+        verdict: "ask",
+        reason: baseReason + (review.clarificationQuestion ? ` ${review.clarificationQuestion}` : ""),
+        riskFlags,
+        source: "supervisor"
+      };
   }
-  return allow("Tool guard passed");
 }
 
-// src/hooks/guard-rails.ts
-import { existsSync as existsSync21, readFileSync as readFileSync21 } from "fs";
-import { join as join21 } from "path";
-var PLANNING_DIR2 = ".planning";
-var CONFIG_FILE = "config.json";
-var STATE_FILE2 = "STATE.md";
-function resolveExecutionMode(configPath, trustScore, volatility) {
-  if (existsSync21(configPath)) {
-    try {
-      const config = JSON.parse(readFileSync21(configPath, "utf-8"));
-      if (config.execution_mode === "review-only")
-        return "review-only";
-      if (config.execution_mode === "guarded")
-        return "guarded";
-      if (config.execution_mode === "auto")
-        return "auto";
-    } catch {}
-  }
-  if (trustScore !== null) {
-    if (trustScore < 30)
-      return "review-only";
-    if (trustScore < 60)
-      return "guarded";
-  }
-  if (volatility === "critical")
-    return "review-only";
-  if (volatility === "volatile")
-    return "guarded";
-  return "auto";
-}
-var BUILD_DEPLOY_PATTERNS = [
-  "npm build",
-  "npm run build",
-  "bun build",
-  "yarn build",
-  "npm deploy",
-  "yarn deploy",
-  "bun deploy",
-  "npm install",
-  "yarn install",
-  "bun install",
-  "make build",
-  "make deploy",
-  "docker build",
-  "docker push",
-  "docker-compose",
-  "git push",
-  "git deploy",
-  "gradle build",
-  "mvn package",
-  "ant build",
-  "cargo build",
-  "cargo deploy",
-  "python setup.py",
-  "pip install",
-  "rails deploy",
-  "rake deploy"
+// src/hooks/tool-guard.ts
+import { existsSync as existsSync20, readFileSync as readFileSync20 } from "fs";
+import { join as join20 } from "path";
+
+// src/lib/task-routing.ts
+var UI_HEAVY_KEYWORDS = [
+  "landing page",
+  "marketing site",
+  "website",
+  "web app",
+  "mobile app",
+  "app screen",
+  "dashboard",
+  "admin panel",
+  "settings page",
+  "onboarding ux",
+  "kanban",
+  "design system",
+  "responsive",
+  "ui",
+  "ux",
+  "cta",
+  "conversion flow",
+  "saas interface",
+  "user-facing"
 ];
-function allow2(reason, riskFlags = []) {
-  return { verdict: "allow", reason, riskFlags, source: "guard-rails" };
-}
-function deny2(reason, escalationMessage, riskFlags = []) {
-  return {
-    verdict: "deny",
-    reason,
-    riskFlags,
-    source: "guard-rails",
-    escalationMessage
-  };
+var NON_UI_KEYWORDS = [
+  "backend",
+  "infrastructure",
+  "migration",
+  "pipeline",
+  "api only",
+  "database only",
+  "cli",
+  "worker"
+];
+function isUiHeavyTask(input) {
+  const normalized = input.trim().toLowerCase();
+  if (!normalized)
+    return false;
+  const hasUiSignal = UI_HEAVY_KEYWORDS.some((keyword) => normalized.includes(keyword));
+  if (!hasUiSignal)
+    return false;
+  const hasOnlyNonUiSignals = NON_UI_KEYWORDS.some((keyword) => normalized.includes(keyword)) && !normalized.includes("frontend");
+  return !hasOnlyNonUiSignals;
 }
-function evaluate2(input) {
-  const { directory, tool: tool13, args } = input;
-  const planningDirPath = join21(directory, PLANNING_DIR2);
-  const codebaseDirectory = codebaseDir(directory);
-  const configPath = join21(planningDirPath, CONFIG_FILE);
-  const statePath3 = join21(planningDirPath, STATE_FILE2);
-  const workspaceRoot = findWorkspaceRoot(directory);
-  if (workspaceRoot && directory !== workspaceRoot) {
-    const workspaceConfig = getWorkspaceConfig(directory);
-    if (workspaceConfig && workspaceConfig.workspace_mode === "shared" && !existsSync21(planningDirPath)) {
-      const msg = `No .planning/ in this sub-repo. Switch to workspace root: cd ${workspaceRoot}`;
-      return deny2(msg, `[flowdeck] BLOCK: ${msg}`, ["workspace-shared-mode"]);
-    }
-  }
-  if (tool13 === "write" || tool13 === "edit") {
-    if (!existsSync21(planningDirPath)) {
-      return allow2("FlowDeck not initialized in this directory — skipping guard-rails");
-    }
-    if (!existsSync21(codebaseDirectory)) {
-      const msg = ".codebase/ not found. Run /fd-map-codebase to map the codebase.";
-      return allow2(msg, ["codebase-missing"]);
-    }
-    const execMode = resolveExecutionMode(configPath, null);
-    if (execMode === "review-only") {
-      const msg = "review-only mode: propose diff but do not apply. Set execution_mode in .planning/config.json to change.";
-      return deny2(msg, `[flowdeck] BLOCK (${msg})`, ["review-only-mode"]);
-    }
-    if (execMode === "guarded") {
-      return allow2("guarded mode: edit will proceed but flag for human review", ["guarded-mode"]);
-    }
-    const designGateMessage = getDesignGateMessage(directory);
-    if (designGateMessage) {
-      if (designGateMessage.startsWith("[flowdeck] WARNING:")) {
-        return allow2(designGateMessage, ["design-gate-advisory"]);
-      }
-      return deny2(designGateMessage, designGateMessage, ["design-gate"]);
-    }
-    const severity = effectiveSeverity(configPath, statePath3);
-    if (severity === null) {
-      return allow2("guard_enforcement is off");
-    }
-    if (severity === "warn") {
-      const warning = getWarningMessage(planningDirPath);
-      return allow2(`[flowdeck] WARNING: ${warning}`, ["plan-not-confirmed"]);
-    }
-    const blockMessage = getBlockMessage(planningDirPath);
-    return deny2(blockMessage, `[flowdeck] BLOCK: ${blockMessage}`, ["plan-not-confirmed"]);
+
+// src/hooks/tool-guard.ts
+var BLOCKED_PATTERNS = {
+  read: [".env", ".pem", ".key", ".secret"],
+  write: ["node_modules"],
+  bash: [
+    "rm -rf",
+    "rm -fr",
+    "rm --recursive --force",
+    "rm -r -f",
+    "mkfs",
+    "mkfs.ext4",
+    "mkfs.ext3",
+    "mkfs.xfs",
+    "mkfs.btrfs",
+    "dd if=",
+    "dd of=",
+    "chmod 777 /",
+    "chmod -r 777 /",
+    "mv / /dev/null",
+    ">/dev/sda",
+    ":(){ :|:& };:"
+  ]
+};
+function extractTargetPath(args) {
+  return String(args?.path ?? args?.file_path ?? args?.filename ?? args?.filePath ?? "");
+}
+function normalizeBashCommand(cmd) {
+  let normalized = cmd.toLowerCase().replace(/#.*$/gm, "").replace(/\s+/g, " ").replace(/\s*;\s*/g, "; ").replace(/\s*\|\s*/g, " | ").replace(/--recursive/g, "-r").replace(/--force/g, "-f").trim();
+  let prev = normalized;
+  while (true) {
+    const next = prev.replace(/(\s-[a-z])\s+-([a-z])/g, "$1$2");
+    if (next === prev)
+      break;
+    prev = next;
   }
-  if (tool13 === "bash") {
-    const cmd = String(args?.command || "");
-    for (const pattern of BUILD_DEPLOY_PATTERNS) {
-      if (cmd.includes(pattern)) {
-        if (!getPlanConfirmed(statePath3)) {
-          const msg = "Build/deploy command detected but plan is not confirmed. Run /fd-plan first.";
-          return allow2(`[flowdeck] WARNING: ${msg}`, ["build-deploy-without-plan"]);
-        }
-        break;
-      }
-    }
+  return prev;
+}
+function isPipedToShell(normalized) {
+  const segments = normalized.split(" | ").map((s) => s.trim());
+  const downloaders = new Set(["curl", "wget"]);
+  const shells = new Set(["sh", "bash", "zsh", "fish"]);
+  for (let i = 0;i < segments.length - 1; i++) {
+    const first = segments[i].split(/\s+/)[0];
+    const next = segments[i + 1].split(/\s+/)[0];
+    if (downloaders.has(first) && shells.has(next))
+      return true;
   }
-  return allow2("Guard rails passed");
+  return false;
 }
-function getDesignGateMessage(dir) {
-  const designConfig = resolveDesignFirstConfig(loadFlowDeckConfig(dir));
-  if (!designConfig.enabled || !designConfig.requireApprovalBeforeImplementation)
-    return null;
-  const state = readPlanningState(dir);
-  if (state.design_override && state.design_override_reason && state.design_override_reason.trim().length > 0)
-    return null;
-  const designApproved = state.design_stage === "handoff_complete" && state.design_approved;
-  if (state.requires_design_first || state.task_type && isUiHeavyTask(state.task_type) || planSuggestsUiHeavy(dir, state.phase || 1)) {
-    if (designApproved)
-      return null;
-    if (designConfig.enforcement === "advisory") {
-      return "[flowdeck] WARNING: UI-heavy task detected without approved design handoff. Run /fd-design --mode=draft first.";
+function isBashCommandDangerous(cmd) {
+  const normalized = normalizeBashCommand(cmd);
+  for (const p of BLOCKED_PATTERNS.bash) {
+    if (normalized.includes(p)) {
+      return `FLOWDECK: Dangerous bash command blocked (matched "${p}").`;
     }
-    return "[flowdeck] BLOCK: UI-heavy task requires approved design handoff. Run /fd-design --mode=draft or set explicit design override in STATE.md.";
   }
-  return null;
-}
-function planSuggestsUiHeavy(dir, phase) {
-  const planPath = phasePlanPath(dir, phase);
-  if (!existsSync21(planPath))
-    return false;
-  const planContent = readFileSync21(planPath, "utf-8");
-  return isUiHeavyTask(planContent);
-}
-function effectiveSeverity(configPath, statePath3) {
-  if (existsSync21(configPath)) {
-    try {
-      const configContent = readFileSync21(configPath, "utf-8");
-      const config = JSON.parse(configContent);
-      if (config.guard_enforcement === "warn")
-        return "warn";
-      if (config.guard_enforcement === "block")
-        return "block";
-      if (config.guard_enforcement === "off")
-        return null;
-    } catch {}
+  if (isPipedToShell(normalized)) {
+    return "FLOWDECK: Piping curl/wget directly to a shell is blocked.";
   }
-  return getPlanConfirmed(statePath3) ? "block" : "warn";
-}
-function getPlanConfirmed(statePath3) {
-  if (!existsSync21(statePath3))
-    return false;
-  try {
-    const content = readFileSync21(statePath3, "utf-8");
-    const match = content.match(/plan_confirmed:\s*(true|false)/i);
-    return match ? match[1].toLowerCase() === "true" : false;
-  } catch {
-    return false;
+  if (/\bdd\b/.test(normalized) && /\/dev\/(sd|hd|nvme|mmcblk|disk)/.test(normalized)) {
+    return "FLOWDECK: dd command targeting a block device is blocked.";
   }
-}
-function getWarningMessage(planningDir2) {
-  if (!existsSync21(join21(planningDir2, STATE_FILE2))) {
-    return "No STATE.md found. Run /fd-map-codebase then /fd-new-feature to start a feature.";
+  if (/:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*}\s*;\s*:/.test(normalized)) {
+    return "FLOWDECK: Fork bomb pattern is blocked.";
   }
-  return "Plan not confirmed. Run /fd-plan and confirm to enable execution.";
+  return null;
 }
-function getBlockMessage(planningDir2) {
-  if (!existsSync21(join21(planningDir2, STATE_FILE2))) {
-    return "No STATE.md found. Run /fd-map-codebase then /fd-new-feature to start a feature.";
+function isBlocked(tool13, args) {
+  const patterns = BLOCKED_PATTERNS[tool13];
+  if (!patterns)
+    return null;
+  if (tool13 === "bash") {
+    const cmd = args.command;
+    if (!cmd)
+      return null;
+    return isBashCommandDangerous(cmd);
   }
-  return "Plan not confirmed. Run /fd-plan and confirm to enable execution.";
-}
-
-// src/services/approval-manager.ts
-import { existsSync as existsSync22, readFileSync as readFileSync22, writeFileSync as writeFileSync13, mkdirSync as mkdirSync12 } from "fs";
-import { join as join22 } from "path";
-import { createHash as createHash4 } from "crypto";
-import { randomUUID } from "crypto";
-var APPROVAL_TTL_MS = 30 * 60 * 1000;
-var SENSITIVE_PATTERNS = [
-  /auth/i,
-  /login/i,
-  /password/i,
-  /secret/i,
-  /token/i,
-  /jwt/i,
-  /session/i,
-  /oauth/i,
-  /payment/i,
-  /billing/i,
-  /stripe/i,
-  /credit/i,
-  /migration/i,
-  /migrate/i,
-  /schema/i,
-  /alembic/i,
-  /infra/i,
-  /terraform/i,
-  /ansible/i,
-  /k8s/i,
-  /kubernetes/i,
-  /docker/i,
-  /\.env/i,
-  /secrets\./i,
-  /config\/prod/i,
-  /production/i,
-  /admin/i,
-  /privilege/i,
-  /sudo/i
-];
-function isSensitivePath(filePath) {
-  return SENSITIVE_PATTERNS.some((p) => p.test(filePath));
-}
-function approvalsPath(dir) {
-  return join22(codebaseDir(dir), "APPROVALS.json");
-}
-function loadStore(dir) {
-  const p = approvalsPath(dir);
-  if (!existsSync22(p))
-    return { requests: [] };
-  try {
-    return JSON.parse(readFileSync22(p, "utf-8"));
-  } catch {
-    return { requests: [] };
+  if (tool13 === "read" || tool13 === "write") {
+    const filePath = extractTargetPath(args);
+    if (!filePath)
+      return null;
+    for (const p of patterns) {
+      if (filePath.includes(p)) {
+        return tool13 === "read" ? `FLOWDECK: Access to "${p}" files is blocked.` : `FLOWDECK: Writing to "${p}" is blocked.`;
+      }
+    }
+    return null;
   }
+  return null;
 }
-function saveStore(dir, store) {
-  const cd = codebaseDir(dir);
-  if (!existsSync22(cd))
-    mkdirSync12(cd, { recursive: true });
-  writeFileSync13(approvalsPath(dir), JSON.stringify(store, null, 2), "utf-8");
-}
-function requestApproval(dir, run_id, trigger, reason, options = {}) {
-  const store = loadStore(dir);
-  const req = {
-    id: randomUUID(),
-    run_id,
-    session_id: options.session_id ?? "session-0",
-    requested_at: new Date().toISOString(),
-    status: "pending",
-    trigger,
-    reason,
-    risk_score: options.risk_score ?? 0,
-    ...options.agent ? { agent: options.agent } : {},
-    ...options.file_path ? { file_path: options.file_path } : {},
-    ...options.content_hash ? { content_hash: options.content_hash } : {},
-    ...options.change_description ? { change_description: options.change_description } : {}
-  };
-  store.requests.push(req);
-  saveStore(dir, store);
-  return req;
-}
-function checkApproval(dir, criteria) {
-  const store = loadStore(dir);
-  const now = Date.now();
-  return store.requests.filter((r) => r.status === "approved" && r.resolved_at && r.run_id === criteria.run_id && r.session_id === criteria.session_id && r.agent === criteria.agent && r.file_path === criteria.file_path && r.content_hash === criteria.content_hash && now - new Date(r.resolved_at).getTime() < APPROVAL_TTL_MS).sort((a, b) => b.resolved_at.localeCompare(a.resolved_at)).at(0) ?? null;
-}
-function computeContentHash(args) {
-  const keys = Object.keys(args).sort();
-  const payload = JSON.stringify(args, keys);
-  return createHash4("sha256").update(payload).digest("hex").slice(0, 16);
-}
-function requestApprovalForTool(dir, run_id, session_id, agent, tool13, args) {
-  const filePath = extractTargetPath2(args);
-  const isSensitive = filePath ? isSensitivePath(filePath) : false;
-  return requestApproval(dir, run_id, tool13, `Approval required for tool "${tool13}"`, {
-    file_path: filePath,
-    risk_score: isSensitive ? 30 : 50,
-    session_id,
-    agent,
-    content_hash: computeContentHash(args),
-    change_description: `Tool "${tool13}" requested on ${filePath || "unknown target"}`
-  });
+function checkArchConstraint(directory, filePath) {
+  const constraintsPath = join20(codebaseDir(directory), "CONSTRAINTS.md");
+  if (!existsSync20(constraintsPath))
+    return null;
+  try {
+    const content = readFileSync20(constraintsPath, "utf-8");
+    const match = content.match(/## Forbidden Paths\n([\s\S]*?)(?:\n##|$)/);
+    if (!match)
+      return null;
+    for (const line of match[1].split(`
+`)) {
+      const pattern = line.replace(/^-\s*/, "").split("#")[0].trim();
+      if (pattern && filePath.includes(pattern)) {
+        return `FLOWDECK [arch-constraint]: editing "${pattern}" is forbidden by .codebase/CONSTRAINTS.md`;
+      }
+    }
+  } catch {}
+  return null;
 }
-function extractTargetPath2(args) {
-  return String(args.path ?? args.file_path ?? args.filename ?? args.filePath ?? "");
+function checkPhaseEnforcement(directory) {
+  try {
+    const state = readPlanningState(directory);
+    const flowdeckConfig = resolveDesignFirstConfig(loadFlowDeckConfig(directory));
+    if (state.phase > 0 && state.phase < 3) {
+      return `FLOWDECK [phase-gate]: writing to codebase is blocked in phase ${state.phase} (${state.phase === 1 ? "discuss" : "plan"}). Run /fd-plan --confirm to enter execute phase.`;
+    }
+    if (flowdeckConfig.enabled && flowdeckConfig.requireApprovalBeforeImplementation && isUiDesignApprovalRequired(directory)) {
+      if (flowdeckConfig.enforcement === "advisory") {
+        return `FLOWDECK [design-gate]: advisory design-first mode detected missing approval. Run /fd-design --mode=draft or set design_override=true in STATE.md.`;
+      }
+      return `FLOWDECK [design-gate]: UI-heavy task requires approved design handoff before implementation. Run /fd-design --mode=draft and ensure design_stage=handoff_complete + design_approved=true, or set explicit design_override with reason.`;
+    }
+  } catch {}
+  return null;
 }
-
-// src/hooks/approval-hook.ts
-var WRITE_TOOLS = new Set([
-  "write_file",
-  "edit_file",
-  "create_file",
-  "apply_patch",
-  "str_replace_editor",
-  "write",
-  "edit"
-]);
-function allow3(reason) {
-  return { verdict: "allow", reason, riskFlags: [], source: "approval-manager" };
+function isUiDesignApprovalRequired(directory) {
+  const state = readPlanningState(directory);
+  if (state.design_override && state.design_override_reason && state.design_override_reason.trim().length > 0)
+    return false;
+  if (state.requires_design_first) {
+    return !(state.design_stage === "handoff_complete" && state.design_approved);
+  }
+  if (state.task_type && isUiHeavyTask(state.task_type)) {
+    return !(state.design_stage === "handoff_complete" && state.design_approved);
+  }
+  const planPath = phasePlanPath(directory, state.phase || 1);
+  if (!existsSync20(planPath))
+    return false;
+  const planContent = readFileSync20(planPath, "utf-8");
+  if (!isUiHeavyTask(planContent))
+    return false;
+  return !(state.design_stage === "handoff_complete" && state.design_approved);
 }
-function ask(reason, riskFlags = []) {
+function allow(reason, riskFlags = []) {
+  return { verdict: "allow", reason, riskFlags, source: "tool-guard" };
+}
+function deny(reason, escalationMessage, riskFlags = []) {
   return {
-    verdict: "ask",
+    verdict: "deny",
     reason,
     riskFlags,
-    source: "approval-manager"
+    source: "tool-guard",
+    escalationMessage
   };
 }
-function evaluate3(input) {
+function evaluate(input) {
   const { directory, tool: tool13, args } = input;
-  if (!WRITE_TOOLS.has(tool13)) {
-    return allow3("Tool does not require approval");
-  }
-  const filePath = String(args?.path ?? args?.file_path ?? args?.filename ?? args?.filePath ?? "");
-  if (!filePath) {
-    return allow3("No target path — approval not required");
+  if (tool13 !== "bash" && tool13 !== "read" && tool13 !== "write" && tool13 !== "edit") {
+    return allow("Tool is not guardable");
   }
-  if (!isSensitivePath(filePath)) {
-    return allow3("Path is not sensitive");
+  const blocked = isBlocked(tool13, args);
+  if (blocked) {
+    return deny(blocked, blocked, ["dangerous-pattern"]);
   }
-  const approval = checkApproval(directory, {
-    run_id: input.runId,
-    session_id: input.sessionID,
-    agent: input.agent,
-    file_path: filePath,
-    content_hash: computeContentHash(args)
-  });
-  if (approval) {
-    return allow3(`Approved by ${approval.id}`);
+  if (tool13 === "write" || tool13 === "edit") {
+    const phaseBlock = checkPhaseEnforcement(directory);
+    if (phaseBlock) {
+      const isAdvisory = phaseBlock.includes("[design-gate]: advisory");
+      if (isAdvisory) {
+        return allow(phaseBlock, ["design-gate-advisory"]);
+      }
+      return deny(phaseBlock, phaseBlock, ["phase-gate"]);
+    }
+    const filePath = extractTargetPath(args);
+    const constraintBlock = checkArchConstraint(directory, filePath);
+    if (constraintBlock) {
+      return deny(constraintBlock, constraintBlock, ["arch-constraint"]);
+    }
   }
-  return ask(`"${filePath}" is a sensitive file (auth/payment/secrets/infra). Manual approval needed before editing.`, ["sensitive-path"]);
+  return allow("Tool guard passed");
 }
 
-// src/services/deadlock-detector.ts
-import { existsSync as existsSync24, readFileSync as readFileSync24, appendFileSync as appendFileSync5, mkdirSync as mkdirSync14 } from "fs";
-import { join as join24 } from "path";
-import { randomUUID as randomUUID3 } from "crypto";
-
-// src/services/agent-trace-graph.ts
-import { existsSync as existsSync23, readFileSync as readFileSync23, appendFileSync as appendFileSync4, writeFileSync as writeFileSync14, mkdirSync as mkdirSync13 } from "fs";
-import { join as join23 } from "path";
-import { randomUUID as randomUUID2 } from "crypto";
-function agentSpansPath(dir) {
-  return join23(codebaseDir(dir), "AGENT_SPANS.jsonl");
-}
-function loadAllSpans(dir) {
-  const p = agentSpansPath(dir);
-  if (!existsSync23(p))
-    return [];
-  try {
-    return readFileSync23(p, "utf-8").trim().split(`
-`).filter(Boolean).map((l) => JSON.parse(l));
-  } catch {
-    return [];
+// src/hooks/guard-rails.ts
+import { existsSync as existsSync21, readFileSync as readFileSync21 } from "fs";
+import { join as join21 } from "path";
+var PLANNING_DIR2 = ".planning";
+var CONFIG_FILE = "config.json";
+var STATE_FILE2 = "STATE.md";
+function resolveExecutionMode(configPath, trustScore, volatility) {
+  if (existsSync21(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync21(configPath, "utf-8"));
+      if (config.execution_mode === "review-only")
+        return "review-only";
+      if (config.execution_mode === "guarded")
+        return "guarded";
+      if (config.execution_mode === "auto")
+        return "auto";
+    } catch {}
   }
-}
-function saveAllSpans(dir, spans) {
-  const p = agentSpansPath(dir);
-  const cd = codebaseDir(dir);
-  if (!existsSync23(cd))
-    mkdirSync13(cd, { recursive: true });
-  writeFileSync14(p, spans.map((s) => JSON.stringify(s)).join(`
-`) + `
-`, "utf-8");
-}
-function openSpan(dir, opts) {
-  const cd = codebaseDir(dir);
-  if (!existsSync23(cd))
-    mkdirSync13(cd, { recursive: true });
-  const span = {
-    span_id: randomUUID2(),
-    trace_id: opts.trace_id,
-    parent_span_id: opts.parent_span_id,
-    invoker: opts.invoker,
-    agent: opts.agent,
-    task_description: opts.task_description,
-    stage: opts.stage,
-    started_at: new Date().toISOString(),
-    status: "running",
-    output_valid: false,
-    contract_violations: [],
-    tools_used: [],
-    retry_count: 0,
-    depth: opts.depth ?? 0,
-    model: opts.model
-  };
-  appendFileSync4(agentSpansPath(dir), JSON.stringify(span) + `
-`, "utf-8");
-  return span;
-}
-function closeSpan(dir, span_id, status, opts = {}) {
-  const spans = loadAllSpans(dir);
-  const idx = spans.findLastIndex((s) => s.span_id === span_id);
-  if (idx === -1)
-    return;
-  const startedMs = new Date(spans[idx].started_at).getTime();
-  spans[idx] = {
-    ...spans[idx],
-    ended_at: new Date().toISOString(),
-    status,
-    latency_ms: Date.now() - startedMs,
-    output_valid: opts.output_valid ?? false,
-    contract_violations: opts.contract_violations ?? spans[idx].contract_violations,
-    tools_used: opts.tools_used ?? spans[idx].tools_used,
-    handoff_payload: opts.handoff_payload,
-    cost_estimate: opts.cost_estimate,
-    retry_count: opts.retry_count ?? spans[idx].retry_count
-  };
-  saveAllSpans(dir, spans);
-}
-function recordToolUsed(dir, span_id, toolName) {
-  const spans = loadAllSpans(dir);
-  const idx = spans.findLastIndex((s) => s.span_id === span_id);
-  if (idx === -1)
-    return;
-  if (!spans[idx].tools_used.includes(toolName)) {
-    spans[idx].tools_used = [...spans[idx].tools_used, toolName];
-    saveAllSpans(dir, spans);
+  if (trustScore !== null) {
+    if (trustScore < 30)
+      return "review-only";
+    if (trustScore < 60)
+      return "guarded";
   }
+  if (volatility === "critical")
+    return "review-only";
+  if (volatility === "volatile")
+    return "guarded";
+  return "auto";
 }
-function addSpanViolation(dir, span_id, violation) {
-  const spans = loadAllSpans(dir);
-  const idx = spans.findLastIndex((s) => s.span_id === span_id);
-  if (idx === -1)
-    return;
-  spans[idx].contract_violations = [...spans[idx].contract_violations, violation];
-  saveAllSpans(dir, spans);
+var BUILD_DEPLOY_PATTERNS = [
+  "npm build",
+  "npm run build",
+  "bun build",
+  "yarn build",
+  "npm deploy",
+  "yarn deploy",
+  "bun deploy",
+  "npm install",
+  "yarn install",
+  "bun install",
+  "make build",
+  "make deploy",
+  "docker build",
+  "docker push",
+  "docker-compose",
+  "git push",
+  "git deploy",
+  "gradle build",
+  "mvn package",
+  "ant build",
+  "cargo build",
+  "cargo deploy",
+  "python setup.py",
+  "pip install",
+  "rails deploy",
+  "rake deploy"
+];
+function allow2(reason, riskFlags = []) {
+  return { verdict: "allow", reason, riskFlags, source: "guard-rails" };
 }
-function recordContractViolation(dir, span_id, violation) {
-  addSpanViolation(dir, span_id, violation);
+function deny2(reason, escalationMessage, riskFlags = []) {
+  return {
+    verdict: "deny",
+    reason,
+    riskFlags,
+    source: "guard-rails",
+    escalationMessage
+  };
 }
-function getTraceSpans(dir, trace_id) {
-  return loadAllSpans(dir).filter((s) => s.trace_id === trace_id);
+function evaluate2(input) {
+  const { directory, tool: tool13, args } = input;
+  const planningDirPath = join21(directory, PLANNING_DIR2);
+  const codebaseDirectory = codebaseDir(directory);
+  const configPath = join21(planningDirPath, CONFIG_FILE);
+  const statePath3 = join21(planningDirPath, STATE_FILE2);
+  const workspaceRoot = findWorkspaceRoot(directory);
+  if (workspaceRoot && directory !== workspaceRoot) {
+    const workspaceConfig = getWorkspaceConfig(directory);
+    if (workspaceConfig && workspaceConfig.workspace_mode === "shared" && !existsSync21(planningDirPath)) {
+      const msg = `No .planning/ in this sub-repo. Switch to workspace root: cd ${workspaceRoot}`;
+      return deny2(msg, `[flowdeck] BLOCK: ${msg}`, ["workspace-shared-mode"]);
+    }
+  }
+  if (tool13 === "write" || tool13 === "edit") {
+    if (!existsSync21(planningDirPath)) {
+      return allow2("FlowDeck not initialized in this directory — skipping guard-rails");
+    }
+    if (!existsSync21(codebaseDirectory)) {
+      const msg = ".codebase/ not found. Run /fd-map-codebase to map the codebase.";
+      return allow2(msg, ["codebase-missing"]);
+    }
+    const execMode = resolveExecutionMode(configPath, null);
+    if (execMode === "review-only") {
+      const msg = "review-only mode: propose diff but do not apply. Set execution_mode in .planning/config.json to change.";
+      return deny2(msg, `[flowdeck] BLOCK (${msg})`, ["review-only-mode"]);
+    }
+    if (execMode === "guarded") {
+      return allow2("guarded mode: edit will proceed but flag for human review", ["guarded-mode"]);
+    }
+    const designGateMessage = getDesignGateMessage(directory);
+    if (designGateMessage) {
+      if (designGateMessage.startsWith("[flowdeck] WARNING:")) {
+        return allow2(designGateMessage, ["design-gate-advisory"]);
+      }
+      return deny2(designGateMessage, designGateMessage, ["design-gate"]);
+    }
+    const severity = effectiveSeverity(configPath, statePath3);
+    if (severity === null) {
+      return allow2("guard_enforcement is off");
+    }
+    if (severity === "warn") {
+      const warning = getWarningMessage(planningDirPath);
+      return allow2(`[flowdeck] WARNING: ${warning}`, ["plan-not-confirmed"]);
+    }
+    const blockMessage = getBlockMessage(planningDirPath);
+    return deny2(blockMessage, `[flowdeck] BLOCK: ${blockMessage}`, ["plan-not-confirmed"]);
+  }
+  if (tool13 === "bash") {
+    const cmd = String(args?.command || "");
+    for (const pattern of BUILD_DEPLOY_PATTERNS) {
+      if (cmd.includes(pattern)) {
+        if (!getPlanConfirmed(statePath3)) {
+          const msg = "Build/deploy command detected but plan is not confirmed. Run /fd-plan first.";
+          return allow2(`[flowdeck] WARNING: ${msg}`, ["build-deploy-without-plan"]);
+        }
+        break;
+      }
+    }
+  }
+  return allow2("Guard rails passed");
 }
-
-// src/services/deadlock-detector.ts
-function resolveConfig(directory) {
-  try {
-    const config = loadFlowDeckConfig(directory);
-    const dc = config?.governance?.deadlockDetection;
-    return {
-      enabled: dc?.enabled ?? true,
-      bounceThreshold: dc?.bounceThreshold ?? 3,
-      retryLoopThreshold: dc?.retryLoopThreshold ?? 3,
-      stageStallMinutes: dc?.stageStallMinutes ?? 30,
-      autoStop: dc?.autoStop ?? false
-    };
-  } catch {
-    return { enabled: true, bounceThreshold: 3, retryLoopThreshold: 3, stageStallMinutes: 30, autoStop: false };
+function getDesignGateMessage(dir) {
+  const designConfig = resolveDesignFirstConfig(loadFlowDeckConfig(dir));
+  if (!designConfig.enabled || !designConfig.requireApprovalBeforeImplementation)
+    return null;
+  const state = readPlanningState(dir);
+  if (state.design_override && state.design_override_reason && state.design_override_reason.trim().length > 0)
+    return null;
+  const designApproved = state.design_stage === "handoff_complete" && state.design_approved;
+  if (state.requires_design_first || state.task_type && isUiHeavyTask(state.task_type) || planSuggestsUiHeavy(dir, state.phase || 1)) {
+    if (designApproved)
+      return null;
+    if (designConfig.enforcement === "advisory") {
+      return "[flowdeck] WARNING: UI-heavy task detected without approved design handoff. Run /fd-design --mode=draft first.";
+    }
+    return "[flowdeck] BLOCK: UI-heavy task requires approved design handoff. Run /fd-design --mode=draft or set explicit design override in STATE.md.";
   }
+  return null;
 }
-function deadlockSignalsPath(dir) {
-  return join24(codebaseDir(dir), "DEADLOCK_SIGNALS.jsonl");
+function planSuggestsUiHeavy(dir, phase) {
+  const planPath = phasePlanPath(dir, phase);
+  if (!existsSync21(planPath))
+    return false;
+  const planContent = readFileSync21(planPath, "utf-8");
+  return isUiHeavyTask(planContent);
 }
-function appendSignal(dir, signal) {
-  const cd = codebaseDir(dir);
-  if (!existsSync24(cd))
-    mkdirSync14(cd, { recursive: true });
-  appendFileSync5(deadlockSignalsPath(dir), JSON.stringify(signal) + `
-`, "utf-8");
+function effectiveSeverity(configPath, statePath3) {
+  if (existsSync21(configPath)) {
+    try {
+      const configContent = readFileSync21(configPath, "utf-8");
+      const config = JSON.parse(configContent);
+      if (config.guard_enforcement === "warn")
+        return "warn";
+      if (config.guard_enforcement === "block")
+        return "block";
+      if (config.guard_enforcement === "off")
+        return null;
+    } catch {}
+  }
+  return getPlanConfirmed(statePath3) ? "block" : "warn";
 }
-function getSignals(dir, trace_id) {
-  const p = deadlockSignalsPath(dir);
-  if (!existsSync24(p))
-    return [];
+function getPlanConfirmed(statePath3) {
+  if (!existsSync21(statePath3))
+    return false;
   try {
-    const all = readFileSync24(p, "utf-8").trim().split(`
-`).filter(Boolean).map((l) => JSON.parse(l));
-    return trace_id ? all.filter((s) => s.trace_id === trace_id) : all;
+    const content = readFileSync21(statePath3, "utf-8");
+    const match = content.match(/plan_confirmed:\s*(true|false)/i);
+    return match ? match[1].toLowerCase() === "true" : false;
   } catch {
-    return [];
+    return false;
   }
 }
-function detectAgentBounce(dir, trace_id, cfg) {
-  const spans = getTraceSpans(dir, trace_id);
-  const pairCounts = {};
-  for (let i = 1;i < spans.length; i++) {
-    const key = `${spans[i - 1].agent}→${spans[i].agent}`;
-    pairCounts[key] = (pairCounts[key] ?? 0) + 1;
-  }
-  for (const [pair, count] of Object.entries(pairCounts)) {
-    if (count >= cfg.bounceThreshold) {
-      const [a, b] = pair.split("→");
-      return {
-        signal_id: randomUUID3(),
-        trace_id,
-        detected_at: new Date().toISOString(),
-        type: "agent_bounce",
-        evidence: [`Agent pair "${pair}" handed off ${count} times (threshold: ${cfg.bounceThreshold})`],
-        agents_involved: [a, b],
-        recommended_action: "escalate_human",
-        auto_stop: cfg.autoStop
-      };
-    }
+function getWarningMessage(planningDir2) {
+  if (!existsSync21(join21(planningDir2, STATE_FILE2))) {
+    return "No STATE.md found. Run /fd-map-codebase then /fd-new-feature to start a feature.";
   }
-  return null;
+  return "Plan not confirmed. Run /fd-plan and confirm to enable execution.";
 }
-function detectCircularDelegation(dir, trace_id, cfg) {
-  const spans = getTraceSpans(dir, trace_id);
-  const graph = {};
-  for (const span of spans) {
-    if (span.invoker === span.agent)
-      continue;
-    if (!graph[span.invoker])
-      graph[span.invoker] = new Set;
-    graph[span.invoker].add(span.agent);
-  }
-  function findCycle(node, visited2, stack) {
-    visited2.add(node);
-    for (const neighbor of [...graph[node] ?? []]) {
-      if (stack.includes(neighbor))
-        return [...stack, neighbor];
-      if (!visited2.has(neighbor)) {
-        const result = findCycle(neighbor, visited2, [...stack, neighbor]);
-        if (result)
-          return result;
-      }
-    }
-    return null;
+function getBlockMessage(planningDir2) {
+  if (!existsSync21(join21(planningDir2, STATE_FILE2))) {
+    return "No STATE.md found. Run /fd-map-codebase then /fd-new-feature to start a feature.";
   }
-  const visited = new Set;
-  for (const node of Object.keys(graph)) {
-    if (!visited.has(node)) {
-      const cycle = findCycle(node, visited, [node]);
-      if (cycle) {
-        return {
-          signal_id: randomUUID3(),
-          trace_id,
-          detected_at: new Date().toISOString(),
-          type: "circular_delegation",
-          evidence: [`Delegation cycle: ${cycle.join(" → ")}`],
-          agents_involved: cycle,
-          recommended_action: "stop",
-          auto_stop: true
-        };
-      }
-    }
+  return "Plan not confirmed. Run /fd-plan and confirm to enable execution.";
+}
+
+// src/services/approval-manager.ts
+import { existsSync as existsSync22, readFileSync as readFileSync22, writeFileSync as writeFileSync13, mkdirSync as mkdirSync12 } from "fs";
+import { join as join22 } from "path";
+import { createHash as createHash4 } from "crypto";
+import { randomUUID } from "crypto";
+var APPROVAL_TTL_MS = 30 * 60 * 1000;
+var SENSITIVE_PATTERNS = [
+  /auth/i,
+  /login/i,
+  /password/i,
+  /secret/i,
+  /token/i,
+  /jwt/i,
+  /session/i,
+  /oauth/i,
+  /payment/i,
+  /billing/i,
+  /stripe/i,
+  /credit/i,
+  /migration/i,
+  /migrate/i,
+  /schema/i,
+  /alembic/i,
+  /infra/i,
+  /terraform/i,
+  /ansible/i,
+  /k8s/i,
+  /kubernetes/i,
+  /docker/i,
+  /\.env/i,
+  /secrets\./i,
+  /config\/prod/i,
+  /production/i,
+  /admin/i,
+  /privilege/i,
+  /sudo/i
+];
+function isSensitivePath(filePath) {
+  return SENSITIVE_PATTERNS.some((p) => p.test(filePath));
+}
+function approvalsPath(dir) {
+  return join22(codebaseDir(dir), "APPROVALS.json");
+}
+function loadStore(dir) {
+  const p = approvalsPath(dir);
+  if (!existsSync22(p))
+    return { requests: [] };
+  try {
+    return JSON.parse(readFileSync22(p, "utf-8"));
+  } catch {
+    return { requests: [] };
   }
-  return null;
 }
-function detectStepRetryLoop(dir, trace_id, cfg) {
-  const spans = getTraceSpans(dir, trace_id);
-  const stageCounts = {};
-  const stageAgents = {};
-  for (const span of spans) {
-    const key = `${span.agent}:${span.stage}`;
-    stageCounts[key] = (stageCounts[key] ?? 0) + 1;
-    if (!stageAgents[key])
-      stageAgents[key] = new Set;
-    stageAgents[key].add(span.agent);
-  }
-  for (const [key, count] of Object.entries(stageCounts)) {
-    if (count >= cfg.retryLoopThreshold) {
-      return {
-        signal_id: randomUUID3(),
-        trace_id,
-        detected_at: new Date().toISOString(),
-        type: "step_retry_loop",
-        evidence: [`Stage "${key}" executed ${count} times (threshold: ${cfg.retryLoopThreshold})`],
-        agents_involved: [...stageAgents[key] ?? new Set],
-        recommended_action: "escalate_human",
-        auto_stop: cfg.autoStop
-      };
-    }
-  }
-  return null;
+function saveStore(dir, store) {
+  const cd = codebaseDir(dir);
+  if (!existsSync22(cd))
+    mkdirSync12(cd, { recursive: true });
+  writeFileSync13(approvalsPath(dir), JSON.stringify(store, null, 2), "utf-8");
 }
-function detectStageStall(dir, trace_id, cfg) {
-  const spans = getTraceSpans(dir, trace_id);
+function requestApproval(dir, run_id, trigger, reason, options = {}) {
+  const store = loadStore(dir);
+  const req = {
+    id: randomUUID(),
+    run_id,
+    session_id: options.session_id ?? "session-0",
+    requested_at: new Date().toISOString(),
+    status: "pending",
+    trigger,
+    reason,
+    risk_score: options.risk_score ?? 0,
+    ...options.agent ? { agent: options.agent } : {},
+    ...options.file_path ? { file_path: options.file_path } : {},
+    ...options.content_hash ? { content_hash: options.content_hash } : {},
+    ...options.change_description ? { change_description: options.change_description } : {}
+  };
+  store.requests.push(req);
+  saveStore(dir, store);
+  return req;
+}
+function checkApproval(dir, criteria) {
+  const store = loadStore(dir);
   const now = Date.now();
-  for (const span of spans) {
-    if (span.status !== "running")
-      continue;
-    const elapsed = (now - new Date(span.started_at).getTime()) / 1000 / 60;
-    if (elapsed >= cfg.stageStallMinutes) {
-      return {
-        signal_id: randomUUID3(),
-        trace_id,
-        detected_at: new Date().toISOString(),
-        type: "stage_stall",
-        evidence: [
-          `Agent "${span.agent}" in stage "${span.stage}" running for ${Math.round(elapsed)}min (threshold: ${cfg.stageStallMinutes}min)`
-        ],
-        agents_involved: [span.agent],
-        recommended_action: "escalate_human",
-        auto_stop: cfg.autoStop
-      };
-    }
-  }
-  return null;
+  return store.requests.filter((r) => r.status === "approved" && r.resolved_at && r.run_id === criteria.run_id && r.session_id === criteria.session_id && r.agent === criteria.agent && r.file_path === criteria.file_path && r.content_hash === criteria.content_hash && now - new Date(r.resolved_at).getTime() < APPROVAL_TTL_MS).sort((a, b) => b.resolved_at.localeCompare(a.resolved_at)).at(0) ?? null;
 }
-function detectDeadlocks(dir, trace_id) {
-  const cfg = resolveConfig(dir);
-  if (!cfg.enabled)
-    return [];
-  const existingTypes = new Set(getSignals(dir, trace_id).map((s) => s.type));
-  const candidates = [
-    detectAgentBounce(dir, trace_id, cfg),
-    detectCircularDelegation(dir, trace_id, cfg),
-    detectStepRetryLoop(dir, trace_id, cfg),
-    detectStageStall(dir, trace_id, cfg)
-  ];
-  const newSignals = candidates.filter((s) => s !== null && !existingTypes.has(s.type));
-  for (const signal of newSignals)
-    appendSignal(dir, signal);
-  return newSignals;
+function computeContentHash(args) {
+  const keys = Object.keys(args).sort();
+  const payload = JSON.stringify(args, keys);
+  return createHash4("sha256").update(payload).digest("hex").slice(0, 16);
 }
-function isTraceStuck(dir, trace_id) {
-  return getSignals(dir, trace_id).some((s) => s.auto_stop);
+function requestApprovalForTool(dir, run_id, session_id, agent, tool13, args) {
+  const filePath = extractTargetPath2(args);
+  const isSensitive = filePath ? isSensitivePath(filePath) : false;
+  return requestApproval(dir, run_id, tool13, `Approval required for tool "${tool13}"`, {
+    file_path: filePath,
+    risk_score: isSensitive ? 30 : 50,
+    session_id,
+    agent,
+    content_hash: computeContentHash(args),
+    change_description: `Tool "${tool13}" requested on ${filePath || "unknown target"}`
+  });
+}
+function extractTargetPath2(args) {
+  return String(args.path ?? args.file_path ?? args.filename ?? args.filePath ?? "");
 }
 
-// src/services/audit-log.ts
-import {
-  existsSync as existsSync25,
-  mkdirSync as mkdirSync15,
-  appendFileSync as appendFileSync6,
-  readFileSync as readFileSync25,
-  writeFileSync as writeFileSync15,
-  renameSync,
-  unlinkSync
-} from "fs";
-import { join as join25 } from "path";
-var AUDIT_FILE = "AUDIT.jsonl";
-var ROTATE_LINE_COUNT = 1000;
-function auditPath(directory) {
-  return join25(codebaseDir(directory), AUDIT_FILE);
+// src/hooks/approval-hook.ts
+var WRITE_TOOLS = new Set([
+  "write_file",
+  "edit_file",
+  "create_file",
+  "apply_patch",
+  "str_replace_editor",
+  "write",
+  "edit"
+]);
+function allow3(reason) {
+  return { verdict: "allow", reason, riskFlags: [], source: "approval-manager" };
 }
-function ensureDirectory(dir) {
-  const base = codebaseDir(dir);
-  if (!existsSync25(base)) {
-    mkdirSync15(base, { recursive: true });
-  }
+function ask(reason, riskFlags = []) {
+  return {
+    verdict: "ask",
+    reason,
+    riskFlags,
+    source: "approval-manager"
+  };
 }
-function rotateIfNeeded(path, appLog) {
-  try {
-    const content = readFileSync25(path, "utf-8");
-    const lines = content.split(`
-`).filter((line) => line.trim().length > 0);
-    if (lines.length <= ROTATE_LINE_COUNT)
-      return;
-    const backupPath = `${path}.backup`;
-    renameSync(path, backupPath);
-    const keep = lines.slice(-ROTATE_LINE_COUNT);
-    writeFileSync15(path, keep.join(`
-`) + `
-`, "utf-8");
-    try {
-      unlinkSync(backupPath);
-    } catch {}
-  } catch (error) {
-    if (appLog) {
-      const message = error instanceof Error ? error.message : String(error);
-      appLog(`[audit-log] rotation failed: ${message}`);
-    }
+function evaluate3(input) {
+  const { directory, tool: tool13, args } = input;
+  if (!WRITE_TOOLS.has(tool13)) {
+    return allow3("Tool does not require approval");
+  }
+  const filePath = String(args?.path ?? args?.file_path ?? args?.filename ?? args?.filePath ?? "");
+  if (!filePath) {
+    return allow3("No target path — approval not required");
+  }
+  if (!isSensitivePath(filePath)) {
+    return allow3("Path is not sensitive");
+  }
+  const approval = checkApproval(directory, {
+    run_id: input.runId,
+    session_id: input.sessionID,
+    agent: input.agent,
+    file_path: filePath,
+    content_hash: computeContentHash(args)
+  });
+  if (approval) {
+    return allow3(`Approved by ${approval.id}`);
   }
+  return ask(`"${filePath}" is a sensitive file (auth/payment/secrets/infra). Manual approval needed before editing.`, ["sensitive-path"]);
 }
-function appendAuditEntry(directory, entry, appLog) {
-  ensureDirectory(directory);
-  const path = auditPath(directory);
-  appendFileSync6(path, JSON.stringify(entry) + `
-`, "utf-8");
-  rotateIfNeeded(path, appLog);
+
+// src/services/deadlock-detector.ts
+import { existsSync as existsSync24, readFileSync as readFileSync24, appendFileSync as appendFileSync5, mkdirSync as mkdirSync14 } from "fs";
+import { join as join24 } from "path";
+import { randomUUID as randomUUID3 } from "crypto";
+
+// src/services/agent-trace-graph.ts
+import { existsSync as existsSync23, readFileSync as readFileSync23, appendFileSync as appendFileSync4, writeFileSync as writeFileSync14, mkdirSync as mkdirSync13 } from "fs";
+import { join as join23 } from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+function agentSpansPath(dir) {
+  return join23(codebaseDir(dir), "AGENT_SPANS.jsonl");
 }
-function queryAudit(directory, filter) {
-  const path = auditPath(directory);
-  if (!existsSync25(path))
+function loadAllSpans(dir) {
+  const p = agentSpansPath(dir);
+  if (!existsSync23(p))
     return [];
   try {
-    const lines = readFileSync25(path, "utf-8").split(`
-`).filter((line) => line.trim().length > 0);
-    const results = [];
-    for (const line of lines) {
-      try {
-        const entry = JSON.parse(line);
-        if (filter.run_id && entry.run_id !== filter.run_id)
-          continue;
-        if (filter.session_id && entry.session_id !== filter.session_id)
-          continue;
-        if (filter.tool && entry.tool !== filter.tool)
-          continue;
-        if (filter.verdict && entry.verdict !== filter.verdict)
-          continue;
-        results.push(entry);
-      } catch {}
-    }
-    return results;
+    return readFileSync23(p, "utf-8").trim().split(`
+`).filter(Boolean).map((l) => JSON.parse(l));
   } catch {
     return [];
   }
 }
-function createAuditLog(directory, appLog) {
-  return {
-    append: (entry) => appendAuditEntry(directory, entry, appLog),
-    query: (filter) => queryAudit(directory, filter)
-  };
-}
-
-// src/services/harness-policy.ts
-function allow4(reason, source, riskFlags = []) {
-  return { verdict: "allow", reason, riskFlags, source };
+function saveAllSpans(dir, spans) {
+  const p = agentSpansPath(dir);
+  const cd = codebaseDir(dir);
+  if (!existsSync23(cd))
+    mkdirSync13(cd, { recursive: true });
+  writeFileSync14(p, spans.map((s) => JSON.stringify(s)).join(`
+`) + `
+`, "utf-8");
 }
-function deny3(reason, source, escalationMessage, riskFlags = []) {
-  return {
-    verdict: "deny",
-    reason,
-    riskFlags,
-    source,
-    escalationMessage
+function openSpan(dir, opts) {
+  const cd = codebaseDir(dir);
+  if (!existsSync23(cd))
+    mkdirSync13(cd, { recursive: true });
+  const span = {
+    span_id: randomUUID2(),
+    trace_id: opts.trace_id,
+    parent_span_id: opts.parent_span_id,
+    invoker: opts.invoker,
+    agent: opts.agent,
+    task_description: opts.task_description,
+    stage: opts.stage,
+    started_at: new Date().toISOString(),
+    status: "running",
+    output_valid: false,
+    contract_violations: [],
+    tools_used: [],
+    retry_count: 0,
+    depth: opts.depth ?? 0,
+    model: opts.model
   };
+  appendFileSync4(agentSpansPath(dir), JSON.stringify(span) + `
+`, "utf-8");
+  return span;
 }
-function ask2(reason, source, approvalRequestId, riskFlags = []) {
-  return {
-    verdict: "ask",
-    reason,
-    riskFlags,
-    source,
-    approvalRequestId
+function closeSpan(dir, span_id, status, opts = {}) {
+  const spans = loadAllSpans(dir);
+  const idx = spans.findLastIndex((s) => s.span_id === span_id);
+  if (idx === -1)
+    return;
+  const startedMs = new Date(spans[idx].started_at).getTime();
+  spans[idx] = {
+    ...spans[idx],
+    ended_at: new Date().toISOString(),
+    status,
+    latency_ms: Date.now() - startedMs,
+    output_valid: opts.output_valid ?? false,
+    contract_violations: opts.contract_violations ?? spans[idx].contract_violations,
+    tools_used: opts.tools_used ?? spans[idx].tools_used,
+    handoff_payload: opts.handoff_payload,
+    cost_estimate: opts.cost_estimate,
+    retry_count: opts.retry_count ?? spans[idx].retry_count
   };
+  saveAllSpans(dir, spans);
 }
-function validationToDecision(result) {
-  const riskFlags = result.violations.map((v) => v.rule);
-  if (result.action === "block") {
-    return deny3(result.message ?? "Agent contract violation", "agent-contract", result.message ?? "This tool call violates the agent's capability contract", riskFlags);
-  }
-  if (result.action === "escalate") {
-    return ask2(result.message ?? "Agent contract requires escalation", "agent-contract", undefined, riskFlags);
-  }
-  if (result.action === "warn") {
-    return allow4(result.message ?? "Agent contract advisory", "agent-contract", riskFlags);
+function recordToolUsed(dir, span_id, toolName) {
+  const spans = loadAllSpans(dir);
+  const idx = spans.findLastIndex((s) => s.span_id === span_id);
+  if (idx === -1)
+    return;
+  if (!spans[idx].tools_used.includes(toolName)) {
+    spans[idx].tools_used = [...spans[idx].tools_used, toolName];
+    saveAllSpans(dir, spans);
   }
-  return allow4("Agent contract passed", "agent-contract");
 }
-function buildAuditEntry(input, decision) {
-  return {
-    id: randomUUID4(),
-    timestamp: new Date().toISOString(),
-    run_id: input.runId,
-    session_id: input.sessionID,
-    agent: input.agent,
-    tool: input.tool,
-    command: input.command,
-    verdict: decision.verdict,
-    reason: decision.reason,
-    risk_flags: decision.riskFlags,
-    source: decision.source,
-    approval_request_id: decision.approvalRequestId
-  };
+function addSpanViolation(dir, span_id, violation) {
+  const spans = loadAllSpans(dir);
+  const idx = spans.findLastIndex((s) => s.span_id === span_id);
+  if (idx === -1)
+    return;
+  spans[idx].contract_violations = [...spans[idx].contract_violations, violation];
+  saveAllSpans(dir, spans);
 }
-function createHarnessPolicy(directory, appLog) {
-  const config = loadFlowDeckConfig(directory);
-  const auditLog = createAuditLog(directory, appLog);
-  const loopDetector = new LoopDetector({
-    enabled: config.governance?.loopDetection?.enabled ?? true,
-    maxRepeats: config.governance?.loopDetection?.maxRepeats ?? 2,
-    similarityThreshold: config.governance?.loopDetection?.similarityThreshold ?? 0.9,
-    historySize: config.governance?.loopDetection?.historySize ?? 20
-  }, appLog);
-  function appendAudit(input, decision) {
-    try {
-      auditLog.append(buildAuditEntry(input, decision));
-    } catch (error) {
-      if (appLog) {
-        const message = error instanceof Error ? error.message : String(error);
-        appLog(`[harness-policy] audit append failed: ${message}`);
-      }
-    }
-  }
-  function checkRuntimeLimits(input) {
-    try {
-      const loop = loopDetector.checkBefore(input.tool, input.args, input.sessionID);
-      if (loop.action === "block") {
-        return deny3(loop.reason, "loop-detector", loop.escalationMessage, ["loop-detected"]);
-      }
-      if (loop.action === "warn") {
-        return allow4(loop.message, "loop-detector", ["loop-warning"]);
-      }
-      if (isTraceStuck(input.directory, input.runId)) {
-        return deny3("Run is stuck (deadlock signal with auto_stop)", "deadlock-detector", "Deadlock detection flagged this run for auto-stop. Escalate to the human.", ["deadlock"]);
-      }
-      return allow4("Runtime limits passed", "runtime-limits");
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (appLog)
-        appLog(`[harness-policy] runtime limits error: ${message}`);
-      return deny3(`Runtime limits check failed: ${message}`, "runtime-limits", `Runtime limits check failed: ${message}`, ["runtime-check-error"]);
-    }
-  }
-  function checkAgentContract(input) {
-    try {
-      const result = validateToolAccess(input.directory, input.agent, input.tool, { run_id: input.runId, session_id: input.sessionID });
-      return validationToDecision(result);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (appLog)
-        appLog(`[harness-policy] agent contract error: ${message}`);
-      return deny3(`Agent contract check failed: ${message}`, "agent-contract", `Agent contract check failed: ${message}`, ["agent-contract-error"]);
-    }
-  }
-  function evaluatePolicyEngine(input) {
-    try {
-      const store = readStore2(input.directory);
-      const filePath = extractTargetPath(input.args);
-      const active = store.policies.filter((p) => p.active);
-      for (const policy of active) {
-        const trigger = policy.trigger.toLowerCase();
-        if (!trigger.trim())
-          continue;
-        if (input.tool.toLowerCase().includes(trigger) || filePath.toLowerCase().includes(trigger)) {
-          return deny3(`Active policy violation: ${policy.name}`, "policy-engine", policy.rule, ["policy-violation", policy.id]);
-        }
-      }
-      return allow4("No active policy violations", "policy-engine");
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (appLog)
-        appLog(`[harness-policy] policy engine error: ${message}`);
-      return allow4(`Policy engine check failed: ${message}`, "policy-engine", [
-        "policy-engine-error"
-      ]);
-    }
-  }
-  function checkGovernance(input) {
-    try {
-      const riskFlags = [];
-      if (config.governance?.toolGuard !== false) {
-        const tg = evaluate(input);
-        if (tg.verdict === "deny")
-          return tg;
-        riskFlags.push(...tg.riskFlags);
-      }
-      if (config.governance?.guardRails !== false) {
-        const gr = evaluate2(input);
-        if (gr.verdict === "deny")
-          return gr;
-        riskFlags.push(...gr.riskFlags);
-      }
-      if (config.governance?.approvals !== false) {
-        const ap = evaluate3(input);
-        if (ap.verdict !== "allow")
-          return ap;
-      }
-      const pe = evaluatePolicyEngine(input);
-      if (pe.verdict === "deny")
-        return pe;
-      riskFlags.push(...pe.riskFlags);
-      return allow4("Governance checks passed", "governance", riskFlags);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (appLog)
-        appLog(`[harness-policy] governance error: ${message}`);
-      return deny3(`Governance check failed: ${message}`, "governance", `Governance check failed: ${message}`, ["governance-error"]);
-    }
+function recordContractViolation(dir, span_id, violation) {
+  addSpanViolation(dir, span_id, violation);
+}
+function getTraceSpans(dir, trace_id) {
+  return loadAllSpans(dir).filter((s) => s.trace_id === trace_id);
+}
+
+// src/services/deadlock-detector.ts
+function resolveConfig(directory) {
+  try {
+    const config = loadFlowDeckConfig(directory);
+    const dc = config?.governance?.deadlockDetection;
+    return {
+      enabled: dc?.enabled ?? true,
+      bounceThreshold: dc?.bounceThreshold ?? 3,
+      retryLoopThreshold: dc?.retryLoopThreshold ?? 3,
+      stageStallMinutes: dc?.stageStallMinutes ?? 30,
+      autoStop: dc?.autoStop ?? false
+    };
+  } catch {
+    return { enabled: true, bounceThreshold: 3, retryLoopThreshold: 3, stageStallMinutes: 30, autoStop: false };
   }
-  function checkSupervisor(input, _targetName) {
-    if (config.governance?.supervisor?.enabled === false) {
-      return allow4("Supervisor disabled", "supervisor");
-    }
-    try {
-      return reviewToolCall(input.directory, input);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (appLog)
-        appLog(`[harness-policy] supervisor error: ${message}`);
-      return deny3(`Supervisor review failed: ${message}`, "supervisor", `Supervisor review failed: ${message}`, ["supervisor-error"]);
-    }
+}
+function deadlockSignalsPath(dir) {
+  return join24(codebaseDir(dir), "DEADLOCK_SIGNALS.jsonl");
+}
+function appendSignal(dir, signal) {
+  const cd = codebaseDir(dir);
+  if (!existsSync24(cd))
+    mkdirSync14(cd, { recursive: true });
+  appendFileSync5(deadlockSignalsPath(dir), JSON.stringify(signal) + `
+`, "utf-8");
+}
+function getSignals(dir, trace_id) {
+  const p = deadlockSignalsPath(dir);
+  if (!existsSync24(p))
+    return [];
+  try {
+    const all = readFileSync24(p, "utf-8").trim().split(`
+`).filter(Boolean).map((l) => JSON.parse(l));
+    return trace_id ? all.filter((s) => s.trace_id === trace_id) : all;
+  } catch {
+    return [];
   }
-  function generateApprovalRequestId(input) {
-    try {
-      const req = requestApprovalForTool(input.directory, input.runId, input.sessionID, input.agent, input.tool, input.args);
-      return req.id;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (appLog)
-        appLog(`[harness-policy] approval request failed: ${message}`);
-      return;
-    }
+}
+function detectAgentBounce(dir, trace_id, cfg) {
+  const spans = getTraceSpans(dir, trace_id);
+  const pairCounts = {};
+  for (let i = 1;i < spans.length; i++) {
+    const key = `${spans[i - 1].agent}→${spans[i].agent}`;
+    pairCounts[key] = (pairCounts[key] ?? 0) + 1;
   }
-  function combineDecisions(decisions, input) {
-    const denied = decisions.find((d) => d.verdict === "deny");
-    if (denied)
-      return denied;
-    const asked = decisions.find((d) => d.verdict === "ask");
-    if (asked) {
+  for (const [pair, count] of Object.entries(pairCounts)) {
+    if (count >= cfg.bounceThreshold) {
+      const [a, b] = pair.split("→");
       return {
-        ...asked,
-        approvalRequestId: asked.approvalRequestId ?? generateApprovalRequestId(input)
+        signal_id: randomUUID3(),
+        trace_id,
+        detected_at: new Date().toISOString(),
+        type: "agent_bounce",
+        evidence: [`Agent pair "${pair}" handed off ${count} times (threshold: ${cfg.bounceThreshold})`],
+        agents_involved: [a, b],
+        recommended_action: "escalate_human",
+        auto_stop: cfg.autoStop
       };
     }
-    const riskFlags = decisions.flatMap((d) => d.riskFlags);
-    const source = decisions.findLast((d) => d.source !== "harness.policy")?.source ?? "harness.policy";
-    return allow4("All policy checks passed", source, riskFlags);
   }
-  function evaluate4(input) {
-    if (config.harness?.enabled === false) {
-      const envDisabled = process.env.FLOWDECK_HARNESS_DISABLED === "1";
-      if (!envDisabled) {
-        if (appLog) {
-          appLog("[harness-policy] SECURITY WARNING: harness.enabled=false without FLOWDECK_HARNESS_DISABLED=1. Enforcing minimal safety checks (loop detection, tool-guard dangerous patterns, orchestrator contract).");
-        }
-        const runtime2 = checkRuntimeLimits(input);
-        if (runtime2.verdict === "deny") {
-          appendAudit(input, runtime2);
-          return runtime2;
-        }
-        if (config.governance?.toolGuard !== false) {
-          const tg = evaluate(input);
-          if (tg.verdict === "deny") {
-            appendAudit(input, tg);
-            return tg;
-          }
-        }
-        const decision2 = allow4("Harness disabled — minimal safety checks passed", "harness.policy", ["harness-disabled-minimal"]);
-        appendAudit(input, decision2);
-        return decision2;
+  return null;
+}
+function detectCircularDelegation(dir, trace_id, cfg) {
+  const spans = getTraceSpans(dir, trace_id);
+  const graph = {};
+  for (const span of spans) {
+    if (span.invoker === span.agent)
+      continue;
+    if (!graph[span.invoker])
+      graph[span.invoker] = new Set;
+    graph[span.invoker].add(span.agent);
+  }
+  function findCycle(node, visited2, stack) {
+    visited2.add(node);
+    for (const neighbor of [...graph[node] ?? []]) {
+      if (stack.includes(neighbor))
+        return [...stack, neighbor];
+      if (!visited2.has(neighbor)) {
+        const result = findCycle(neighbor, visited2, [...stack, neighbor]);
+        if (result)
+          return result;
       }
-      const decision = allow4("Harness disabled by config and env override", "harness.policy");
-      appendAudit(input, decision);
-      return decision;
-    }
-    const decisions = [];
-    const runtime = checkRuntimeLimits(input);
-    decisions.push(runtime);
-    if (runtime.verdict === "deny") {
-      appendAudit(input, runtime);
-      return runtime;
-    }
-    const contract = checkAgentContract(input);
-    decisions.push(contract);
-    if (contract.verdict === "deny") {
-      appendAudit(input, contract);
-      return contract;
     }
-    const governance = checkGovernance(input);
-    decisions.push(governance);
-    if (governance.verdict === "deny") {
-      appendAudit(input, governance);
-      return governance;
+    return null;
+  }
+  const visited = new Set;
+  for (const node of Object.keys(graph)) {
+    if (!visited.has(node)) {
+      const cycle = findCycle(node, visited, [node]);
+      if (cycle) {
+        return {
+          signal_id: randomUUID3(),
+          trace_id,
+          detected_at: new Date().toISOString(),
+          type: "circular_delegation",
+          evidence: [`Delegation cycle: ${cycle.join(" → ")}`],
+          agents_involved: cycle,
+          recommended_action: "stop",
+          auto_stop: true
+        };
+      }
     }
-    const supervisor = checkSupervisor(input, input.agent);
-    decisions.push(supervisor);
-    const final = combineDecisions(decisions, input);
-    appendAudit(input, final);
-    return final;
   }
-  return {
-    evaluate: evaluate4,
-    checkAgentContract,
-    checkRuntimeLimits,
-    checkGovernance,
-    checkSupervisor
-  };
+  return null;
 }
-
-// src/services/harness-controller.ts
-import { randomUUID as randomUUID7 } from "crypto";
-
-// src/services/preflight-explorer.ts
-var QUESTION_KIND_PATTERNS = [
-  {
-    kind: "what-tech-stack",
-    patterns: ["tech stack", "language", "framework", "what are you using", "what tech", "built with", "written in"]
-  },
-  {
-    kind: "is-project-initialized",
-    patterns: ["initialized", "set up", "codebase mapped", "map-codebase", "new feature"]
-  },
-  {
-    kind: "what-is-current-phase",
-    patterns: ["current phase", "which phase", "what phase", "where are we", "current state"]
-  },
-  {
-    kind: "what-patterns-exist",
-    patterns: ["existing pattern", "how is it done", "how does the codebase", "pattern used", "architecture"]
-  },
-  {
-    kind: "is-ui-heavy",
-    patterns: ["ui", "frontend", "user interface", "webpage", "web app", "dashboard", "landing page", "screen"]
-  },
-  {
-    kind: "has-existing-tests",
-    patterns: ["test", "spec", "coverage", "tdd", "regression"]
-  },
-  {
-    kind: "has-existing-docs",
-    patterns: ["docs", "documentation", "readme", "api docs"]
-  },
-  {
-    kind: "has-ci-cd",
-    patterns: ["ci/cd", "continuous integration", "deploy", "pipeline", "github actions", ".github/workflow"]
-  },
-  {
-    kind: "what-agents-available",
-    patterns: ["which agent", "available agent", "what agent"]
-  },
-  {
-    kind: "what-commands-available",
-    patterns: ["which command", "available command", "what command", "slash command"]
-  },
-  {
-    kind: "what-skills-available",
-    patterns: ["skill", "available skill"]
-  },
-  {
-    kind: "has-prior-decisions",
-    patterns: ["prior decision", "previous discussion", "what was decided", "earlier session", "previous phase"]
-  },
-  {
-    kind: "has-governance",
-    patterns: ["governance", "policy", "approval", "supervisor"]
+function detectStepRetryLoop(dir, trace_id, cfg) {
+  const spans = getTraceSpans(dir, trace_id);
+  const stageCounts = {};
+  const stageAgents = {};
+  for (const span of spans) {
+    const key = `${span.agent}:${span.stage}`;
+    stageCounts[key] = (stageCounts[key] ?? 0) + 1;
+    if (!stageAgents[key])
+      stageAgents[key] = new Set;
+    stageAgents[key].add(span.agent);
   }
-];
-function shouldSuppressQuestion(question, result, sessionHistory) {
-  const lower = question.toLowerCase();
-  const alreadyAsked = sessionHistory.some((h) => h.toLowerCase().trim() === lower.trim());
-  if (alreadyAsked) {
-    return {
-      suppress: true,
-      reason: "This question was already asked in the current session."
-    };
+  for (const [key, count] of Object.entries(stageCounts)) {
+    if (count >= cfg.retryLoopThreshold) {
+      return {
+        signal_id: randomUUID3(),
+        trace_id,
+        detected_at: new Date().toISOString(),
+        type: "step_retry_loop",
+        evidence: [`Stage "${key}" executed ${count} times (threshold: ${cfg.retryLoopThreshold})`],
+        agents_involved: [...stageAgents[key] ?? new Set],
+        recommended_action: "escalate_human",
+        auto_stop: cfg.autoStop
+      };
+    }
   }
-  const matchedEvidence = result.evidenceItems.filter((ev) => {
-    const qKind = classifyQuestionKind(lower);
-    return qKind !== null && qKind === ev.answersQuestion;
-  });
-  if (matchedEvidence.length > 0) {
-    return {
-      suppress: true,
-      answeredByEvidence: true,
-      reason: `Answered by repo evidence: ${matchedEvidence.map((e) => e.summary).join("; ")}`,
-      evidence: matchedEvidence
-    };
+  return null;
+}
+function detectStageStall(dir, trace_id, cfg) {
+  const spans = getTraceSpans(dir, trace_id);
+  const now = Date.now();
+  for (const span of spans) {
+    if (span.status !== "running")
+      continue;
+    const elapsed = (now - new Date(span.started_at).getTime()) / 1000 / 60;
+    if (elapsed >= cfg.stageStallMinutes) {
+      return {
+        signal_id: randomUUID3(),
+        trace_id,
+        detected_at: new Date().toISOString(),
+        type: "stage_stall",
+        evidence: [
+          `Agent "${span.agent}" in stage "${span.stage}" running for ${Math.round(elapsed)}min (threshold: ${cfg.stageStallMinutes}min)`
+        ],
+        agents_involved: [span.agent],
+        recommended_action: "escalate_human",
+        auto_stop: cfg.autoStop
+      };
+    }
   }
-  return { suppress: false };
+  return null;
 }
-function refineClassification(clarificationPrompt, result, sessionHistory) {
-  const promptLower = clarificationPrompt.toLowerCase();
-  const isTaskTypeQuestion = result.hasProjectMD && (promptLower.includes("new feature") || promptLower.includes("bug fix") || promptLower.includes("ui change") || promptLower.includes("documentation") || promptLower.includes("describe the task") || promptLower.includes("more detail"));
-  if (isTaskTypeQuestion) {
-    return {
-      clarificationStillNeeded: false,
-      resolvedReason: "PROJECT.md exists — project is initialized. Defaulting ambiguous task to feature."
-    };
+function detectDeadlocks(dir, trace_id) {
+  const cfg = resolveConfig(dir);
+  if (!cfg.enabled)
+    return [];
+  const existingTypes = new Set(getSignals(dir, trace_id).map((s) => s.type));
+  const candidates = [
+    detectAgentBounce(dir, trace_id, cfg),
+    detectCircularDelegation(dir, trace_id, cfg),
+    detectStepRetryLoop(dir, trace_id, cfg),
+    detectStageStall(dir, trace_id, cfg)
+  ];
+  const newSignals = candidates.filter((s) => s !== null && !existingTypes.has(s.type));
+  for (const signal of newSignals)
+    appendSignal(dir, signal);
+  return newSignals;
+}
+function isTraceStuck(dir, trace_id) {
+  return getSignals(dir, trace_id).some((s) => s.auto_stop);
+}
+
+// src/services/audit-log.ts
+import {
+  existsSync as existsSync25,
+  mkdirSync as mkdirSync15,
+  appendFileSync as appendFileSync6,
+  readFileSync as readFileSync25,
+  writeFileSync as writeFileSync15,
+  renameSync,
+  unlinkSync
+} from "fs";
+import { join as join25 } from "path";
+var AUDIT_FILE = "AUDIT.jsonl";
+var ROTATE_LINE_COUNT = 1000;
+function auditPath(directory) {
+  return join25(codebaseDir(directory), AUDIT_FILE);
+}
+function ensureDirectory(dir) {
+  const base = codebaseDir(dir);
+  if (!existsSync25(base)) {
+    mkdirSync15(base, { recursive: true });
   }
-  const suppress = shouldSuppressQuestion(clarificationPrompt, result, sessionHistory);
-  if (suppress.suppress) {
-    return {
-      clarificationStillNeeded: false,
-      resolvedReason: suppress.reason
-    };
+}
+function rotateIfNeeded(path, appLog) {
+  try {
+    const content = readFileSync25(path, "utf-8");
+    const lines = content.split(`
+`).filter((line) => line.trim().length > 0);
+    if (lines.length <= ROTATE_LINE_COUNT)
+      return;
+    const backupPath = `${path}.backup`;
+    renameSync(path, backupPath);
+    const keep = lines.slice(-ROTATE_LINE_COUNT);
+    writeFileSync15(path, keep.join(`
+`) + `
+`, "utf-8");
+    try {
+      unlinkSync(backupPath);
+    } catch {}
+  } catch (error) {
+    if (appLog) {
+      const message = error instanceof Error ? error.message : String(error);
+      appLog(`[audit-log] rotation failed: ${message}`);
+    }
   }
-  const lines = [];
-  if (result.hasProjectMD)
-    lines.push("PROJECT.md is present (project is initialized).");
-  if (result.hasStateMD)
-    lines.push("STATE.md is present (project has active session).");
-  if (result.hasPriorDiscussions)
-    lines.push("Prior DISCUSS.md files exist.");
-  if (result.techStack.length > 0)
-    lines.push(`Tech stack: ${result.techStack.join(", ")}.`);
-  if (result.implementationPatterns.length > 0) {
-    lines.push(`Implementation patterns: ${result.implementationPatterns.join(", ")}.`);
+}
+function appendAuditEntry(directory, entry, appLog) {
+  ensureDirectory(directory);
+  const path = auditPath(directory);
+  appendFileSync6(path, JSON.stringify(entry) + `
+`, "utf-8");
+  rotateIfNeeded(path, appLog);
+}
+function queryAudit(directory, filter) {
+  const path = auditPath(directory);
+  if (!existsSync25(path))
+    return [];
+  try {
+    const lines = readFileSync25(path, "utf-8").split(`
+`).filter((line) => line.trim().length > 0);
+    const results = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (filter.run_id && entry.run_id !== filter.run_id)
+          continue;
+        if (filter.session_id && entry.session_id !== filter.session_id)
+          continue;
+        if (filter.tool && entry.tool !== filter.tool)
+          continue;
+        if (filter.verdict && entry.verdict !== filter.verdict)
+          continue;
+        results.push(entry);
+      } catch {}
+    }
+    return results;
+  } catch {
+    return [];
   }
+}
+function createAuditLog(directory, appLog) {
   return {
-    clarificationStillNeeded: true,
-    supervisorContext: lines.length > 0 ? lines.join(" ") : undefined
+    append: (entry) => appendAuditEntry(directory, entry, appLog),
+    query: (filter) => queryAudit(directory, filter)
   };
 }
-var STOP_WORDS = new Set([
-  "with",
-  "that",
-  "this",
-  "from",
-  "into",
-  "when",
-  "then",
-  "will",
-  "have",
-  "been",
-  "does",
-  "should",
-  "would",
-  "could",
-  "after",
-  "before",
-  "about"
-]);
-function classifyQuestionKind(questionLower) {
-  for (const { kind, patterns } of QUESTION_KIND_PATTERNS) {
-    if (patterns.some((p) => questionLower.includes(p)))
-      return kind;
-  }
-  return null;
-}
 
-// src/services/workflow-router.ts
-function stage(name, command, requiresApproval, skippable, args) {
-  return { name, command, args, requiresApproval, skippable };
+// src/services/harness-policy.ts
+function allow4(reason, source, riskFlags = []) {
+  return { verdict: "allow", reason, riskFlags, source };
 }
-function scoreTaskForRouting(criteria) {
-  const simplicity = (criteria.taskType === "simple" ? 1 : 0) * 0.3;
-  const confidence = criteria.confidence * 0.2;
-  const lowRisk = !criteria.isSensitive && criteria.blastRadius < 3 ? 0.2 : 0;
-  const knownCodebase = criteria.codebaseFreshness === "fresh" ? 0.15 : 0;
-  const cheapComplexity = criteria.complexity === "cheap" ? 0.15 : 0;
-  const total = simplicity + confidence + lowRisk + knownCodebase + cheapComplexity;
+function deny3(reason, source, escalationMessage, riskFlags = []) {
   return {
-    simplicity,
-    confidence,
-    lowRisk,
-    knownCodebase,
-    cheapComplexity,
-    total
+    verdict: "deny",
+    reason,
+    riskFlags,
+    source,
+    escalationMessage
   };
 }
-function buildAdaptiveStageSequence(criteria) {
-  const scores = scoreTaskForRouting(criteria);
-  const totalScore = scores.total;
-  let workflowClass;
-  let stages;
-  let reason;
-  if (totalScore >= 0.75 && (criteria.taskType === "simple" || criteria.taskType === "docs")) {
-    workflowClass = "quick";
-    stages = [
-      stage("execute", "fd-execute", false, true),
-      stage("verify", "fd-verify", false, true)
-    ];
-    reason = `Quick workflow: score ${totalScore.toFixed(2)} >= 0.75 for ${criteria.taskType} task`;
-  } else if (criteria.taskType === "bugfix") {
-    workflowClass = "bugfix";
-    stages = [
-      stage("discuss", "fd-discuss", false, false),
-      stage("fix-bug", "fd-fix-bug", false, false),
-      stage("verify", "fd-verify", false, false)
-    ];
-    reason = "Bugfix workflow: task type is bugfix";
-  } else if (criteria.taskType === "docs" && totalScore < 0.75) {
-    workflowClass = "docs-only";
-    stages = [
-      stage("write-docs", "fd-write-docs", false, false),
-      stage("verify", "fd-verify", false, true)
-    ];
-    reason = `Docs-only workflow: score ${totalScore.toFixed(2)} < 0.75 for docs task`;
-  } else if (criteria.taskType === "ui-feature") {
-    workflowClass = "ui-heavy";
-    stages = [
-      stage("discuss", "fd-discuss", false, false),
-      stage("design", "fd-design", false, false, "--mode=draft"),
-      stage("plan", "fd-plan", true, false),
-      stage("execute", "fd-execute", false, false),
-      stage("verify", "fd-verify", false, false)
-    ];
-    reason = "UI-heavy workflow: task type indicates UI-heavy work";
-  } else if (criteria.blastRadius >= 5 || criteria.isSensitive) {
-    workflowClass = "verify-heavy";
-    stages = [
-      stage("plan", "fd-plan", true, false),
-      stage("execute", "fd-execute", false, false),
-      stage("verify", "fd-verify", false, false)
-    ];
-    reason = `Verify-heavy workflow: blastRadius=${criteria.blastRadius}, isSensitive=${criteria.isSensitive}`;
-  } else if (criteria.confidence < 0.6 || criteria.taskType === "ambiguous") {
-    workflowClass = "explore";
-    stages = [
-      stage("discuss", "fd-discuss", false, false),
-      stage("plan", "fd-plan", true, false),
-      stage("execute", "fd-execute", false, false),
-      stage("verify", "fd-verify", false, false)
-    ];
-    reason = `Explore workflow: confidence=${criteria.confidence}, taskType=${criteria.taskType}`;
-  } else {
-    workflowClass = "standard";
-    stages = [
-      stage("plan", "fd-plan", true, false),
-      stage("execute", "fd-execute", false, false),
-      stage("verify", "fd-verify", false, false)
-    ];
-    reason = `Standard workflow: score ${totalScore.toFixed(2)} with taskType ${criteria.taskType}`;
-  }
+function ask2(reason, source, approvalRequestId, riskFlags = []) {
   return {
-    workflowClass,
-    stages,
-    criteria,
-    scores,
-    reason
+    verdict: "ask",
+    reason,
+    riskFlags,
+    source,
+    approvalRequestId
   };
 }
-
-// src/services/quick-router.ts
-var BUG_SIGNALS = [
-  "fix",
-  "bug",
-  "broken",
-  "not working",
-  "doesn't work",
-  "does not work",
-  "error",
-  "crash",
-  "regression",
-  "debug",
-  "exception",
-  "failing",
-  "fails",
-  "incorrect",
-  "wrong output",
-  "infinite loop",
-  "null pointer",
-  "undefined",
-  "404",
-  "500",
-  "stack trace",
-  "traceback",
-  "root cause",
-  "why is"
-];
-var UI_SIGNALS = [
-  "landing page",
-  "dashboard",
-  "admin panel",
-  "admin page",
-  "app screen",
-  "onboarding",
-  "onboard",
-  "wireframe",
-  "mockup",
-  "design system",
-  "component library",
-  "ui component",
-  "ux flow",
-  "user interface",
-  "web app",
-  "web application",
-  "website",
-  "frontend page",
-  "mobile screen",
-  "login page",
-  "signup page",
-  "settings page",
-  "profile page",
-  "modal",
-  "dialog",
-  "sidebar",
-  "navigation",
-  "navbar",
-  "header",
-  "footer",
-  "layout",
-  "responsive",
-  "accessibility",
-  "a11y",
-  "dark mode",
-  "theme"
-];
-var DOCS_SIGNALS = [
-  "docs",
-  "documentation",
-  "readme",
-  "api docs",
-  "usage guide",
-  "write docs",
-  "document",
-  "document the",
-  "how to use",
-  "tutorial",
-  "changelog",
-  "contributing guide",
-  "docstring",
-  "jsdoc",
-  "tsdoc"
-];
-var SIMPLE_SIGNALS = [
-  "rename",
-  "move file",
-  "quick",
-  "minor",
-  "small change",
-  "one-liner",
-  "typo",
-  "update constant",
-  "update config",
-  "bump version"
-];
-var AMBIGUOUS_PATTERNS = [
-  /^(improve|make|update|change|add|remove|help|do|run|check|use)\s+\w+$/i
-];
-function classifyTask(description) {
-  const lower = description.toLowerCase().trim();
-  if (!lower) {
-    return _ambiguous([], "What task do you want to run? Please describe what you need done.");
+function validationToDecision(result) {
+  const riskFlags = result.violations.map((v) => v.rule);
+  if (result.action === "block") {
+    return deny3(result.message ?? "Agent contract violation", "agent-contract", result.message ?? "This tool call violates the agent's capability contract", riskFlags);
   }
-  const bugHits = BUG_SIGNALS.filter((s) => lower.includes(s));
-  const uiHits = UI_SIGNALS.filter((s) => lower.includes(s));
-  const docsHits = DOCS_SIGNALS.filter((s) => lower.includes(s));
-  const simpleHits = SIMPLE_SIGNALS.filter((s) => lower.includes(s));
-  const bugScore = Math.min(bugHits.length * 0.35, 1);
-  const uiScore = Math.min(uiHits.length * 0.3, 1);
-  const docsScore = Math.min(docsHits.length * 0.4, 1);
-  const simpleScore = Math.min(simpleHits.length * 0.45, 1);
-  if (bugScore >= 0.35 && bugScore >= uiScore && bugScore >= docsScore) {
-    return {
-      taskType: "bugfix",
-      confidence: Math.min(0.5 + bugScore * 0.5, 0.98),
-      signals: bugHits,
-      requiresDesign: false,
-      requiresTDD: true,
-      stageSequence: buildStageSequence("bugfix"),
-      clarificationNeeded: bugScore < 0.5,
-      clarificationPrompt: bugScore < 0.5 ? "Can you describe the specific bug? What is the expected vs actual behavior?" : undefined
-    };
+  if (result.action === "escalate") {
+    return ask2(result.message ?? "Agent contract requires escalation", "agent-contract", undefined, riskFlags);
   }
-  if (uiScore >= 0.3) {
-    return {
-      taskType: "ui-feature",
-      confidence: Math.min(0.5 + uiScore * 0.45, 0.95),
-      signals: uiHits,
-      requiresDesign: true,
-      requiresTDD: true,
-      stageSequence: buildStageSequence("ui-feature"),
-      clarificationNeeded: false
-    };
+  if (result.action === "warn") {
+    return allow4(result.message ?? "Agent contract advisory", "agent-contract", riskFlags);
   }
-  if (docsScore >= 0.4 && docsScore >= bugScore) {
-    return {
-      taskType: "docs",
-      confidence: Math.min(0.55 + docsScore * 0.4, 0.95),
-      signals: docsHits,
-      requiresDesign: false,
-      requiresTDD: false,
-      stageSequence: buildStageSequence("docs"),
-      clarificationNeeded: false
-    };
+  return allow4("Agent contract passed", "agent-contract");
+}
+function buildAuditEntry(input, decision) {
+  return {
+    id: randomUUID4(),
+    timestamp: new Date().toISOString(),
+    run_id: input.runId,
+    session_id: input.sessionID,
+    agent: input.agent,
+    tool: input.tool,
+    command: input.command,
+    verdict: decision.verdict,
+    reason: decision.reason,
+    risk_flags: decision.riskFlags,
+    source: decision.source,
+    approval_request_id: decision.approvalRequestId
+  };
+}
+function createHarnessPolicy(directory, appLog) {
+  const config = loadFlowDeckConfig(directory);
+  const auditLog = createAuditLog(directory, appLog);
+  const loopDetector = new LoopDetector({
+    enabled: config.governance?.loopDetection?.enabled ?? true,
+    maxRepeats: config.governance?.loopDetection?.maxRepeats ?? 2,
+    similarityThreshold: config.governance?.loopDetection?.similarityThreshold ?? 0.9,
+    historySize: config.governance?.loopDetection?.historySize ?? 20
+  }, appLog);
+  function appendAudit(input, decision) {
+    try {
+      auditLog.append(buildAuditEntry(input, decision));
+    } catch (error) {
+      if (appLog) {
+        const message = error instanceof Error ? error.message : String(error);
+        appLog(`[harness-policy] audit append failed: ${message}`);
+      }
+    }
   }
-  if (simpleScore >= 0.45) {
-    return {
-      taskType: "simple",
-      confidence: Math.min(0.55 + simpleScore * 0.35, 0.9),
-      signals: simpleHits,
-      requiresDesign: false,
-      requiresTDD: false,
-      stageSequence: buildStageSequence("simple"),
-      clarificationNeeded: false
-    };
+  function checkRuntimeLimits(input) {
+    try {
+      const loop = loopDetector.checkBefore(input.tool, input.args, input.sessionID);
+      if (loop.action === "block") {
+        return deny3(loop.reason, "loop-detector", loop.escalationMessage, ["loop-detected"]);
+      }
+      if (loop.action === "warn") {
+        return allow4(loop.message, "loop-detector", ["loop-warning"]);
+      }
+      if (isTraceStuck(input.directory, input.runId)) {
+        return deny3("Run is stuck (deadlock signal with auto_stop)", "deadlock-detector", "Deadlock detection flagged this run for auto-stop. Escalate to the human.", ["deadlock"]);
+      }
+      return allow4("Runtime limits passed", "runtime-limits");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (appLog)
+        appLog(`[harness-policy] runtime limits error: ${message}`);
+      return deny3(`Runtime limits check failed: ${message}`, "runtime-limits", `Runtime limits check failed: ${message}`, ["runtime-check-error"]);
+    }
   }
-  const wordCount = lower.split(/\s+/).filter(Boolean).length;
-  if (wordCount >= 5) {
-    return {
-      taskType: "feature",
-      confidence: Math.min(0.5 + wordCount * 0.02, 0.85),
-      signals: [],
-      requiresDesign: false,
-      requiresTDD: true,
-      stageSequence: buildStageSequence("feature"),
-      clarificationNeeded: wordCount < 8,
-      clarificationPrompt: wordCount < 8 ? "Is this a new feature, a bug fix, or a documentation task? A bit more context will help route it correctly." : undefined
-    };
+  function checkAgentContract(input) {
+    try {
+      const result = validateToolAccess(input.directory, input.agent, input.tool, { run_id: input.runId, session_id: input.sessionID });
+      return validationToDecision(result);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (appLog)
+        appLog(`[harness-policy] agent contract error: ${message}`);
+      return deny3(`Agent contract check failed: ${message}`, "agent-contract", `Agent contract check failed: ${message}`, ["agent-contract-error"]);
+    }
+  }
+  function evaluatePolicyEngine(input) {
+    try {
+      const store = readStore2(input.directory);
+      const filePath = extractTargetPath(input.args);
+      const active = store.policies.filter((p) => p.active);
+      for (const policy of active) {
+        const trigger = policy.trigger.toLowerCase();
+        if (!trigger.trim())
+          continue;
+        if (input.tool.toLowerCase().includes(trigger) || filePath.toLowerCase().includes(trigger)) {
+          return deny3(`Active policy violation: ${policy.name}`, "policy-engine", policy.rule, ["policy-violation", policy.id]);
+        }
+      }
+      return allow4("No active policy violations", "policy-engine");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (appLog)
+        appLog(`[harness-policy] policy engine error: ${message}`);
+      return allow4(`Policy engine check failed: ${message}`, "policy-engine", [
+        "policy-engine-error"
+      ]);
+    }
   }
-  const isAmbiguousPattern = AMBIGUOUS_PATTERNS.some((p) => p.test(lower));
-  if (isAmbiguousPattern || wordCount < 5) {
-    return _ambiguous([], "Can you describe the task in more detail? For example: is it a new feature, a bug fix, a UI change, or documentation?");
+  function checkGovernance(input) {
+    try {
+      const riskFlags = [];
+      if (config.governance?.toolGuard !== false) {
+        const tg = evaluate(input);
+        if (tg.verdict === "deny")
+          return tg;
+        riskFlags.push(...tg.riskFlags);
+      }
+      if (config.governance?.guardRails !== false) {
+        const gr = evaluate2(input);
+        if (gr.verdict === "deny")
+          return gr;
+        riskFlags.push(...gr.riskFlags);
+      }
+      if (config.governance?.approvals !== false) {
+        const ap = evaluate3(input);
+        if (ap.verdict !== "allow")
+          return ap;
+      }
+      const pe = evaluatePolicyEngine(input);
+      if (pe.verdict === "deny")
+        return pe;
+      riskFlags.push(...pe.riskFlags);
+      return allow4("Governance checks passed", "governance", riskFlags);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (appLog)
+        appLog(`[harness-policy] governance error: ${message}`);
+      return deny3(`Governance check failed: ${message}`, "governance", `Governance check failed: ${message}`, ["governance-error"]);
+    }
   }
-  return {
-    taskType: "feature",
-    confidence: 0.6,
-    signals: [],
-    requiresDesign: false,
-    requiresTDD: true,
-    stageSequence: buildStageSequence("feature"),
-    clarificationNeeded: false
-  };
-}
-function _ambiguous(signals, prompt) {
-  return {
-    taskType: "ambiguous",
-    confidence: 0,
-    signals,
-    requiresDesign: false,
-    requiresTDD: false,
-    stageSequence: [],
-    clarificationNeeded: true,
-    clarificationPrompt: prompt
-  };
-}
-function buildStageSequence(taskType) {
-  switch (taskType) {
-    case "feature":
-      return [
-        stage2("discuss", "fd-discuss", false, false),
-        stage2("plan", "fd-plan", true, false),
-        stage2("execute", "fd-execute", false, false),
-        stage2("verify", "fd-verify", false, false)
-      ];
-    case "ui-feature":
-      return [
-        stage2("discuss", "fd-discuss", false, false),
-        stage2("design", "fd-design", false, false, "--mode=draft"),
-        stage2("plan", "fd-plan", true, false),
-        stage2("execute", "fd-execute", false, false),
-        stage2("verify", "fd-verify", false, false)
-      ];
-    case "bugfix":
-      return [
-        stage2("discuss", "fd-discuss", false, false),
-        stage2("fix-bug", "fd-fix-bug", false, false),
-        stage2("verify", "fd-verify", false, false)
-      ];
-    case "docs":
-      return [
-        stage2("discuss", "fd-discuss", false, false),
-        stage2("write-docs", "fd-write-docs", false, false),
-        stage2("verify", "fd-verify", false, true)
-      ];
-    case "simple":
-      return [
-        stage2("execute", "fd-execute", false, false),
-        stage2("verify", "fd-verify", false, true)
-      ];
-    case "ambiguous":
-      return [];
-    default:
-      return [];
+  function checkSupervisor(input, _targetName) {
+    if (config.governance?.supervisor?.enabled === false) {
+      return allow4("Supervisor disabled", "supervisor");
+    }
+    try {
+      return reviewToolCall(input.directory, input);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (appLog)
+        appLog(`[harness-policy] supervisor error: ${message}`);
+      return deny3(`Supervisor review failed: ${message}`, "supervisor", `Supervisor review failed: ${message}`, ["supervisor-error"]);
+    }
   }
-}
-function buildAdaptiveWorkflow(description, exploration) {
-  const base = exploration ? classifyTaskWithContext(description, exploration) : classifyTask(description);
-  const complexityResult = classifyTaskComplexity(description);
-  const criteria = {
-    taskType: base.taskType,
-    complexity: complexityResult.complexity,
-    confidence: base.confidence,
-    blastRadius: 0,
-    isSensitive: false,
-    codebaseFreshness: exploration ? "fresh" : "unknown",
-    requiresTests: base.requiresTDD
-  };
-  const route = buildAdaptiveStageSequence(criteria);
-  return {
-    ...base,
-    stageSequence: route.stages,
-    workflowClass: route.workflowClass,
-    scores: route.scores
-  };
-}
-function stage2(name, command, requiresApproval, skippable, args) {
-  return { name, command, args, requiresApproval, skippable };
-}
-function classifyTaskWithContext(description, exploration, sessionHistory = []) {
-  const base = classifyTask(description);
-  if (!base.clarificationNeeded) {
-    return base;
+  function generateApprovalRequestId(input) {
+    try {
+      const req = requestApprovalForTool(input.directory, input.runId, input.sessionID, input.agent, input.tool, input.args);
+      return req.id;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (appLog)
+        appLog(`[harness-policy] approval request failed: ${message}`);
+      return;
+    }
   }
-  const refinement = refineClassification(base.clarificationPrompt ?? "", exploration, sessionHistory);
-  if (!refinement.clarificationStillNeeded) {
-    const resolvedType = base.taskType === "ambiguous" ? "feature" : base.taskType;
-    return {
-      ...base,
-      taskType: resolvedType,
-      stageSequence: buildStageSequence(resolvedType),
-      clarificationNeeded: false,
-      clarificationPrompt: undefined,
-      confidence: Math.max(base.confidence, 0.55)
-    };
+  function combineDecisions(decisions, input) {
+    const denied = decisions.find((d) => d.verdict === "deny");
+    if (denied)
+      return denied;
+    const asked = decisions.find((d) => d.verdict === "ask");
+    if (asked) {
+      return {
+        ...asked,
+        approvalRequestId: asked.approvalRequestId ?? generateApprovalRequestId(input)
+      };
+    }
+    const riskFlags = decisions.flatMap((d) => d.riskFlags);
+    const source = decisions.findLast((d) => d.source !== "harness.policy")?.source ?? "harness.policy";
+    return allow4("All policy checks passed", source, riskFlags);
+  }
+  function evaluate4(input) {
+    if (config.harness?.enabled === false) {
+      const envDisabled = process.env.FLOWDECK_HARNESS_DISABLED === "1";
+      if (!envDisabled) {
+        if (appLog) {
+          appLog("[harness-policy] SECURITY WARNING: harness.enabled=false without FLOWDECK_HARNESS_DISABLED=1. Enforcing minimal safety checks (loop detection, tool-guard dangerous patterns, orchestrator contract).");
+        }
+        const runtime2 = checkRuntimeLimits(input);
+        if (runtime2.verdict === "deny") {
+          appendAudit(input, runtime2);
+          return runtime2;
+        }
+        if (config.governance?.toolGuard !== false) {
+          const tg = evaluate(input);
+          if (tg.verdict === "deny") {
+            appendAudit(input, tg);
+            return tg;
+          }
+        }
+        const decision2 = allow4("Harness disabled — minimal safety checks passed", "harness.policy", ["harness-disabled-minimal"]);
+        appendAudit(input, decision2);
+        return decision2;
+      }
+      const decision = allow4("Harness disabled by config and env override", "harness.policy");
+      appendAudit(input, decision);
+      return decision;
+    }
+    const decisions = [];
+    const runtime = checkRuntimeLimits(input);
+    decisions.push(runtime);
+    if (runtime.verdict === "deny") {
+      appendAudit(input, runtime);
+      return runtime;
+    }
+    const contract = checkAgentContract(input);
+    decisions.push(contract);
+    if (contract.verdict === "deny") {
+      appendAudit(input, contract);
+      return contract;
+    }
+    const governance = checkGovernance(input);
+    decisions.push(governance);
+    if (governance.verdict === "deny") {
+      appendAudit(input, governance);
+      return governance;
+    }
+    const supervisor = checkSupervisor(input, input.agent);
+    decisions.push(supervisor);
+    const final = combineDecisions(decisions, input);
+    appendAudit(input, final);
+    return final;
   }
-  const enrichedPrompt = refinement.supervisorContext ? `${base.clarificationPrompt ?? ""} (Context: ${refinement.supervisorContext})` : base.clarificationPrompt;
   return {
-    ...base,
-    clarificationPrompt: enrichedPrompt
+    evaluate: evaluate4,
+    checkAgentContract,
+    checkRuntimeLimits,
+    checkGovernance,
+    checkSupervisor
   };
 }
 
+// src/services/harness-controller.ts
+import { randomUUID as randomUUID7 } from "crypto";
+
 // src/services/run-trace.ts
 import { existsSync as existsSync26, readFileSync as readFileSync26, appendFileSync as appendFileSync7, writeFileSync as writeFileSync16, mkdirSync as mkdirSync16 } from "fs";
 import { join as join26 } from "path";
@@ -10468,26 +10761,79 @@ var DISABLED = process.env.FLOWDECK_ORCHESTRATOR_GUARD === "off";
 function normalizeToolName(name) {
   return name.toLowerCase().replace(/[-_]/g, "");
 }
-function blockMessage(toolName) {
+var WRITE_TOOLS2 = new Set(["write", "writefile", "create", "createfile", "edit", "editfile", "patch", "applypatch", "strreplaceeditor", "strreplace"]);
+var SHELL_TOOLS = new Set(["bash", "runbash", "execute", "runcommand", "terminal", "shell"]);
+var BUILD_TOOLS = new Set(["npm", "pnpm", "yarn", "bun", "cargo", "go", "make", "cmake", "docker", "kubectl", "terraform", "pulumi"]);
+var SCRIPT_TOOLS = new Set(["python", "runpython", "js", "runjs"]);
+function agentCanExecute(contract) {
+  const allowed = contract.allowedTools.map(normalizeToolName);
+  return allowed.some((t) => WRITE_TOOLS2.has(t) || SHELL_TOOLS.has(t) || BUILD_TOOLS.has(t));
+}
+function matchesBlockedTool(contract, blockedTool) {
+  const normalizedBlocked = normalizeToolName(blockedTool);
+  const allowed = contract.allowedTools.map(normalizeToolName);
+  if (allowed.includes(normalizedBlocked))
+    return true;
+  if (WRITE_TOOLS2.has(normalizedBlocked))
+    return allowed.some((t) => WRITE_TOOLS2.has(t));
+  if (SHELL_TOOLS.has(normalizedBlocked))
+    return allowed.some((t) => SHELL_TOOLS.has(t));
+  if (BUILD_TOOLS.has(normalizedBlocked))
+    return allowed.some((t) => BUILD_TOOLS.has(t));
+  if (SCRIPT_TOOLS.has(normalizedBlocked))
+    return allowed.some((t) => SCRIPT_TOOLS.has(t));
+  return false;
+}
+function fallbackRoutingSuggestion(blockedTool) {
+  const normalized = normalizeToolName(blockedTool);
+  if (WRITE_TOOLS2.has(normalized)) {
+    return `  @default-executor — simple file edits and quick fixes
+  @backend-coder — backend code changes
+  @frontend-coder — frontend code changes
+  @writer — documentation changes`;
+  }
+  if (SHELL_TOOLS.has(normalized)) {
+    return `  @default-executor — ad-hoc shell commands
+  @tester — test and verification commands
+  @devops — CI/CD and infrastructure commands`;
+  }
+  if (BUILD_TOOLS.has(normalized)) {
+    return `  @devops — build, deploy, and infrastructure
+  @tester — test and verification commands
+  @build-error-resolver — fix build/type errors`;
+  }
+  if (SCRIPT_TOOLS.has(normalized)) {
+    return `  @default-executor — run scripts and small experiments
+  @tester — test scripts and verification`;
+  }
+  return "  @default-executor — general execution delegate";
+}
+function buildRoutingSuggestions(blockedTool) {
+  const contracts = getAllContracts().filter((c) => c.agent !== "orchestrator" && agentCanExecute(c));
+  const matches = contracts.filter((c) => matchesBlockedTool(c, blockedTool)).map((c) => `  @${c.agent} — ${c.role}`).slice(0, 5);
+  if (matches.length > 0) {
+    return matches.join(`
+`);
+  }
+  return fallbackRoutingSuggestion(blockedTool);
+}
+function buildBlockMessage(toolName, repeatCount) {
   const contract = getContract("orchestrator");
   const allowed = contract?.allowedTools ?? [];
+  const suggestions = buildRoutingSuggestions(toolName);
+  const loopWarning = repeatCount >= 2 ? `
+⚠️ You have attempted this blocked tool ${repeatCount} times. Stop retrying and delegate to an agent instead.
+` : "";
   return `[Orchestrator Guard] The orchestrator cannot use \`${toolName}\` directly.
 
-` + `The orchestrator is a coordinator, not an executor.
-
+` + `The orchestrator is a coordinator, not an executor.${loopWarning}
 ` + `Routing options:
-` + `  @default-executor  — simple direct tasks (rename, typo fix, quick edit)
-` + `  @backend-coder     — backend code writing and editing
-` + `  @frontend-coder    — frontend code writing and editing
-` + `  @devops            — CI/CD, deploy, and infrastructure changes
-` + `  @mapper            — codebase mapping
-` + `  @researcher        — focused research and file analysis
-` + `  @tester            — tests, builds, and shell-heavy verification
-` + `  @writer            — documentation writing
+${suggestions}
 
 ` + `Allowed tools for orchestrator: ${allowed.join(", ")}.
 
 ` + `To route execution, mention the agent directly: @default-executor, @backend-coder, etc.
+` + `If the task is unclear, ask the human ONE targeted clarifying question instead of retrying.
 
 ` + `To disable this guard: set FLOWDECK_ORCHESTRATOR_GUARD=off`;
 }
@@ -10495,6 +10841,7 @@ function blockMessage(toolName) {
 class OrchestratorGuard {
   primarySessionId = null;
   policy;
+  blockedHistory = new Map;
   setPolicy(policy) {
     this.policy = policy;
   }
@@ -10505,6 +10852,7 @@ class OrchestratorGuard {
       if (deletedId && deletedId === this.primarySessionId) {
         this.primarySessionId = null;
       }
+      this.blockedHistory.delete(deletedId ?? "");
       return;
     }
     if (eventType !== "session.created" && eventType !== "session.started")
@@ -10527,14 +10875,19 @@ class OrchestratorGuard {
       return;
     const contract = getContract("orchestrator");
     if (!contract) {
-      throw new Error(blockMessage(toolName));
+      return buildBlockMessage(toolName, 1);
     }
     const normalizedTool = normalizeToolName(toolName);
     const allowed = contract.allowedTools.some((t) => normalizeToolName(t) === normalizedTool);
     if (allowed)
       return;
-    if (this.policy) {}
-    throw new Error(blockMessage(toolName));
+    const sessionHistory = this.blockedHistory.get(sessionId) ?? new Map;
+    const record = sessionHistory.get(normalizedTool) ?? { count: 0, lastTool: toolName };
+    record.count += 1;
+    record.lastTool = toolName;
+    sessionHistory.set(normalizedTool, record);
+    this.blockedHistory.set(sessionId, sessionHistory);
+    return buildBlockMessage(toolName, record.count);
   }
   _isBlockedForTest(name) {
     const contract = getContract("orchestrator");
@@ -10549,6 +10902,9 @@ class OrchestratorGuard {
   _setPrimarySessionIdForTest(id) {
     this.primarySessionId = id;
   }
+  _getRepeatCountForTest(sessionId, toolName) {
+    return this.blockedHistory.get(sessionId)?.get(normalizeToolName(toolName))?.count ?? 0;
+  }
 }
 function extractSessionId(event) {
   const props = event.properties;
@@ -11022,6 +11378,7 @@ function createHarnessController(config) {
   const maxToolCalls = delegationConfig?.maxToolCalls ?? 200;
   const sessionDepthMap = new Map;
   const blockedSessions = new Set;
+  const pendingDepthBlockNotifications = new Map;
   const state = {
     loopDetector,
     eventLog,
@@ -11059,7 +11416,8 @@ function createHarnessController(config) {
       projectRoot: directory,
       command,
       description,
-      currentStage
+      currentStage,
+      workflowDecision: route
     });
     const budget = assembledContext.tokenBudget;
     log(`[context-ingress] run=${sessionID} trivial=${assembledContext.isTrivialChat} ` + `tokens=${budget.usedTokens}/${budget.limitTokens} (${budget.component})`);
@@ -11162,16 +11520,14 @@ function createHarnessController(config) {
       });
       state.lastActiveSessionID = req.sessionID;
       const agent = req.agent ?? "orchestrator";
-      try {
-        orchestratorGuard.check(req.sessionID, req.tool);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+      const guardMessage = orchestratorGuard.check(req.sessionID, req.tool);
+      if (guardMessage) {
         return {
           verdict: "deny",
-          reason: message,
+          reason: guardMessage,
           riskFlags: ["orchestrator-contract"],
           source: "orchestrator-guard",
-          escalationMessage: message
+          escalationMessage: guardMessage
         };
       }
       executionSubstrate.start({
@@ -11236,6 +11592,9 @@ function createHarnessController(config) {
           if (childDepth > maxDepth) {
             log(`[harness] delegation depth ${childDepth} exceeds maxDepth ${maxDepth} — session ${sessionID} will be policy-blocked`);
             blockedSessions.add(sessionID);
+            if (parentSessionID) {
+              pendingDepthBlockNotifications.set(sessionID, parentSessionID);
+            }
           }
         } else {
           sessionDepthMap.set(sessionID, 0);
@@ -11244,6 +11603,7 @@ function createHarnessController(config) {
       if ((type === "session.idle" || type === "session.error") && sessionID) {
         sessionDepthMap.delete(sessionID);
         blockedSessions.delete(sessionID);
+        pendingDepthBlockNotifications.delete(sessionID);
       }
       orchestratorGuard.onEvent({ type, properties });
       if (type === "session.created" || type === "session.started") {
@@ -11288,6 +11648,14 @@ function createHarnessController(config) {
     },
     getContextMonitor() {
       return contextMonitor.get();
+    },
+    getPendingDepthBlockNotifications() {
+      const notifications = [];
+      for (const [sessionID, parentSessionID] of pendingDepthBlockNotifications) {
+        notifications.push({ sessionID, parentSessionID });
+      }
+      pendingDepthBlockNotifications.clear();
+      return notifications;
     }
   };
 }
@@ -11503,6 +11871,9 @@ var plugin = async (input, _options) => {
         type: event.type,
         properties: event.properties
       });
+      for (const { sessionID: blockedSessionID, parentSessionID } of harness.getPendingDepthBlockNotifications()) {
+        notify("FlowDeck: Delegation depth limit reached", `Session ${blockedSessionID} (parent ${parentSessionID}) exceeded max delegation depth. Stop further delegation from this subagent.`, "critical");
+      }
       const type = event?.type ?? "";
       if (type === "command.executed") {
         const commandName = String(event?.properties?.name ?? "");
@@ -11533,6 +11904,11 @@ var plugin = async (input, _options) => {
     },
     "tool.execute.before": async (toolInput, toolOutput) => {
       const sessionID = toolInput.sessionID ?? "";
+      harness.ensureRunContext({
+        sessionID,
+        description: `${toolInput.tool ?? toolInput.name ?? "unknown"} ${JSON.stringify(toolOutput?.args ?? toolInput?.args ?? {})} auto-invoked`,
+        agent: toolInput.agent
+      });
       const budgetCheck = harness.checkToolCallBudget(sessionID);
       if (!budgetCheck.allow) {
         throw new Error(budgetCheck.reason ?? `Tool blocked: ${budgetCheck.reason}`);