@dv.nghiem/flowdeck 0.3.6 → 0.3.8

package/dist/index.js

@@ -2480,7 +2480,7 @@ async function guardRailsHook(ctx, input, _output) {
     for (const pattern of BUILD_DEPLOY_PATTERNS) {
       if (cmd.includes(pattern)) {
         if (!getPlanConfirmed(statePath2)) {
-          throw new Error(`[flowdeck] WARNING: Build/deploy command detected but plan is not confirmed. Run /plan first.`);
+          throw new Error(`[flowdeck] WARNING: Build/deploy command detected but plan is not confirmed. Run /fd-plan first.`);
         }
         break;
       }
@@ -2543,15 +2543,15 @@ function getPlanConfirmed(statePath2) {
 }
 function getWarningMessage(planningDir2) {
   if (!existsSync18(join18(planningDir2, STATE_FILE2))) {
-    return "No .planning/ found. Run /new-project first.";
+    return "No .planning/ found. Run /fd-new-project first.";
   }
-  return "Plan not confirmed. Run /plan and confirm to enable execution.";
+  return "Plan not confirmed. Run /fd-plan and confirm to enable execution.";
 }
 function getBlockMessage(planningDir2) {
   if (!existsSync18(join18(planningDir2, STATE_FILE2))) {
-    return "No .planning/ found. Run /new-project first.";
+    return "No .planning/ found. Run /fd-new-project first.";
   }
-  return "Plan not confirmed. Run /plan and confirm to enable execution.";
+  return "Plan not confirmed. Run /fd-plan and confirm to enable execution.";
 }
 
 // src/hooks/tool-guard.ts
@@ -2689,7 +2689,7 @@ async function sessionStartHook(ctx) {
     return {
       flowdeck_phase: null,
       flowdeck_status: "no_plan",
-      flowdeck_warning: "Run /new-project or /map-codebase to initialize.",
+      flowdeck_warning: "Run /fd-new-project or /fd-map-codebase to initialize.",
       flowdeck_has_codebase: existsSync20(codebaseDirectory),
       ...workspaceRoot && config?.sub_repos ? {
         flowdeck_workspace_root: workspaceRoot,
@@ -3605,16 +3605,16 @@ MUST execute at session start:
 3. Check which steps are marked complete
 4. Begin execution from the first incomplete step
 
-If STATE.md does not exist, tell the user: "No STATE.md found. Run \`/new-project\` to initialize."
+If STATE.md does not exist, tell the user: "No STATE.md found. Run \`/fd-new-project\` to initialize."
 
 ## Phase Gating
 
 Only orchestrate in the **execute** phase.
 
 If the project is in another phase:
-- **discuss** phase: "Run \`/discuss\` to complete requirements gathering first."
-- **plan** phase: "Run \`/plan\` to create the implementation plan first."
-- **review** phase: "Run \`/review-code\` to complete the review phase."
+- **discuss** phase: "Run \`/fd-discuss\` to complete requirements gathering first."
+- **plan** phase: "Run \`/fd-plan\` to create the implementation plan first."
+- **review** phase: "Run \`/fd-verify\` to complete the review phase."
 
 ## Step Execution
 
@@ -5539,7 +5539,7 @@ Discussion is complete when:
 - All decisions recorded in DISCUSS.md
 - No open questions remain
 
-Report: "Requirements gathering complete. N decisions recorded. Ready for /plan."`;
+Report: "Requirements gathering complete. N decisions recorded. Ready for /fd-plan."`;
 var createTaskSplitterAgent = (model, customPrompt, customAppendPrompt) => {
   const prompt = resolvePrompt(TASK_SPLITTER_PROMPT, customPrompt, customAppendPrompt);
   return {
@@ -6278,6 +6278,133 @@ var createDesignAgent = (model, customPrompt, customAppendPrompt) => {
   };
 };
 
+// src/agents/supervisor.ts
+var SUPERVISOR_PROMPT = `You are the FlowDeck Supervisor Agent — a governance layer that reviews existing commands and agents before or after execution.
+
+## Role and Hard Constraints
+
+**You review. You do not execute.**
+
+You sit above the orchestrator's execution path. Your only job is to inspect an already-selected command or agent, validate it against policy, and return a structured decision.
+
+### You MUST NEVER:
+- Invent a new command name
+- Invent a new workflow definition
+- Suggest creating a new agent
+- Replace or duplicate the orchestrator
+- Execute implementation tasks
+- Become a second dispatcher
+- Modify the intent of an existing command
+
+### You MAY:
+- Inspect an existing registered command or agent
+- Validate that required stages are present
+- Detect policy violations in the selected target
+- Flag risk before execution
+- Decide: approve / revise / block / escalate
+- Request that the orchestrator obtain missing prerequisites
+
+## Registered Commands (source of truth — do not add to this list)
+
+fd-ask, fd-checkpoint, fd-deploy-check, fd-design, fd-discuss, fd-doctor,
+fd-execute, fd-fix-bug, fd-map-codebase, fd-multi-repo, fd-new-feature,
+fd-new-project, fd-plan, fd-quick, fd-reflect, fd-resume, fd-status,
+fd-suggest, fd-translate-intent, fd-verify, fd-write-docs
+
+## Registered Agents (source of truth — do not add to this list)
+
+orchestrator, planner, backend-coder, frontend-coder, devops, plan-checker,
+tester, reviewer, researcher, writer, security-auditor, doc-updater, mapper,
+code-explorer, debug-specialist, build-error-resolver, task-splitter, discusser,
+architect, risk-analyst, policy-enforcer, performance-optimizer, refactor-guide,
+auto-learner, design, supervisor
+
+## Policy Checks
+
+When reviewing a command or agent, evaluate ONLY the following against what already exists:
+
+### Design-first policy
+- If the task is UI-heavy (dashboard, landing page, web app, UI, UX, admin panel) and the current phase is "execute", the design stage MUST have completed with approval.
+- If design approval is absent: decision = revise | required change = complete design stage first.
+
+### Bugfix regression policy
+- If the command is fd-fix-bug, a regression test MUST exist before implementation.
+- If no regression test: decision = revise | required change = write failing regression test first.
+
+### Phase ordering policy
+- fd-execute must only run in the "execute" phase.
+- If invoked in a different phase: decision = revise.
+
+### Missing inputs policy
+- If a registered agent has required inputs listed in its contract and they are absent: decision = revise.
+
+### Approval gate policy
+- If an operation requires explicit human approval and none was granted: decision = escalate.
+
+### Unregistered target policy
+- If the requested command or agent is NOT in the registered lists above: decision = block.
+- Do NOT suggest or create a replacement. Report that the target is unavailable.
+
+## Decision Output Format
+
+Always respond with a valid JSON object matching this schema exactly:
+
+\`\`\`json
+{
+  "decision": "approve" | "revise" | "block" | "escalate",
+  "targetType": "command" | "agent" | "workflow",
+  "targetName": "<exact registered name>",
+  "exists": true | false,
+  "reasons": ["<human-readable reason>"],
+  "missingRequirements": ["<what is absent>"],
+  "riskFlags": ["<risk description>"],
+  "requiredChanges": ["<what must change before proceeding>"],
+  "approvalStatus": "approved" | "pending" | "denied" | "escalated",
+  "confidenceScore": 0.0–1.0,
+  "reviewPhase": "preflight" | "post-stage",
+  "timestamp": "<ISO 8601>"
+}
+\`\`\`
+
+### Decision rules:
+- **approve**: target exists, all policy checks pass, confidence ≥ threshold
+- **revise**: target exists, fixable issues found — list requiredChanges so caller can resolve
+- **block**: target does not exist OR critical unfixable policy violation
+- **escalate**: human approval required OR confidence below threshold
+
+### On unregistered targets:
+If a requested command or workflow is not in the registered lists, set:
+- decision: "block"
+- exists: false
+- reasons: explain the target is not registered
+- requiredChanges: list valid registered alternatives
+- Do NOT invent a new command or workflow to substitute
+
+## Diagnostics
+
+Before issuing a decision, log:
+1. Which existing command/agent was reviewed
+2. Whether it exists in the registry
+3. Which policy checks ran
+4. Why the decision was reached
+5. Whether review is preflight or post-stage
+6. Whether human escalation is recommended`;
+function createSupervisorAgent(model, customPrompt, customAppendPrompt) {
+  const prompt = resolvePrompt(SUPERVISOR_PROMPT, customPrompt, customAppendPrompt);
+  const definition = {
+    name: "supervisor",
+    description: "Governance supervisor that reviews existing commands and agents before execution. Approves, revises, blocks, or escalates — never creates new commands or workflows.",
+    config: {
+      temperature: 0.1,
+      prompt
+    }
+  };
+  if (typeof model === "string" && model) {
+    definition.config.model = model;
+  }
+  return definition;
+}
+
 // src/agents/index.ts
 var AGENT_NAMES = [
   "orchestrator",
@@ -6304,7 +6431,8 @@ var AGENT_NAMES = [
   "performance-optimizer",
   "refactor-guide",
   "auto-learner",
-  "design"
+  "design",
+  "supervisor"
 ];
 var PRIMARY_AGENTS = new Set(["orchestrator"]);
 var ALL_MODES_AGENTS = new Set;
@@ -6370,6 +6498,8 @@ function createAgent(name, model, customPrompt, customAppendPrompt) {
       return createAutoLearnerAgent(model);
     case "design":
       return createDesignAgent(model, customPrompt, customAppendPrompt);
+    case "supervisor":
+      return createSupervisorAgent(model, customPrompt, customAppendPrompt);
     default:
       console.warn(`[flowdeck] Unknown agent: ${name}`);
       return;
@@ -6407,6 +6537,632 @@ function getAgentConfigs(agentModels) {
   return configs;
 }
 
+// src/services/agent-contract-registry.ts
+var CONTRACTS = [
+  {
+    agent: "orchestrator",
+    role: "Coordinate multi-agent execution. Delegates all work — never implements directly.",
+    allowedTaskTypes: ["orchestration", "coordination", "delegation", "phase-management"],
+    requiredInputs: ["STATE.md", "PLAN.md"],
+    expectedOutputFields: ["delegated_steps", "completed_steps", "current_phase"],
+    allowedTools: [
+      "delegate",
+      "run-pipeline",
+      "council",
+      "planning-state",
+      "codebase-state",
+      "workspace-state",
+      "repo-memory",
+      "decision-trace",
+      "policy-engine",
+      "context-generator",
+      "create-skill",
+      "reflect"
+    ],
+    forbiddenActions: [
+      "write_file",
+      "edit_file",
+      "create_file",
+      "bash",
+      "patch",
+      "apply_patch",
+      "read source files directly"
+    ],
+    escalationConditions: [
+      "delegated agent fails twice",
+      "delegation budget exhausted",
+      "deadlock detected",
+      "all agents blocked on the same step"
+    ],
+    stopConditions: [
+      "all PLAN.md steps completed",
+      "user requests stop",
+      "budget exceeded with no fallback"
+    ],
+    successCriteria: [
+      "all plan steps delegated and completed",
+      "STATE.md phase updated to review",
+      "no implementation performed directly by orchestrator"
+    ]
+  },
+  {
+    agent: "planner",
+    role: "Create detailed implementation plans. Output PLAN.md with numbered steps.",
+    allowedTaskTypes: ["planning", "task-breakdown", "step-decomposition"],
+    requiredInputs: ["task description or STATE.md"],
+    expectedOutputFields: ["steps", "phase"],
+    allowedTools: ["read", "glob", "grep", "planning-state", "workspace-state"],
+    forbiddenActions: [
+      "write source files",
+      "run bash commands",
+      "edit application code",
+      "implement features"
+    ],
+    escalationConditions: [
+      "requirements are ambiguous",
+      "dependencies between steps unclear",
+      "conflicting constraints"
+    ],
+    stopConditions: ["PLAN.md written and reviewed by plan-checker", "user confirms plan"],
+    successCriteria: [
+      "PLAN.md contains numbered steps with assigned agents",
+      "each step has clear success criteria",
+      "no implementation performed"
+    ]
+  },
+  {
+    agent: "plan-checker",
+    role: "Review PLAN.md quality before execution. Read-only.",
+    allowedTaskTypes: ["plan-review", "quality-check"],
+    requiredInputs: ["PLAN.md"],
+    expectedOutputFields: ["verdict", "issues", "recommendations"],
+    allowedTools: ["read", "glob", "grep"],
+    forbiddenActions: ["write or edit any files", "modify PLAN.md"],
+    escalationConditions: ["plan is fundamentally flawed", "critical gaps found"],
+    stopConditions: ["review complete", "verdict issued"],
+    successCriteria: ["structured review output", "no file modifications"]
+  },
+  {
+    agent: "design",
+    role: "Design UX, wireframes, and visual systems for UI-heavy tasks.",
+    allowedTaskTypes: ["ux-design", "wireframe", "visual-system", "design-handoff", "frontend-handoff"],
+    requiredInputs: ["task description", "requirements"],
+    expectedOutputFields: ["design_stage", "wireframes", "component_structure", "design_tokens"],
+    allowedTools: ["read", "write", "glob", "grep", "planning-state"],
+    forbiddenActions: [
+      "run bash commands",
+      "write application logic",
+      "implement backend code",
+      "implement React components"
+    ],
+    escalationConditions: [
+      "design requirements unclear",
+      "conflicting UX requirements",
+      "brand guidelines missing"
+    ],
+    stopConditions: ["design_stage=handoff_complete", "design_approved=true"],
+    successCriteria: [
+      "design document written",
+      "design_stage set to handoff_complete",
+      "design_approved set to true",
+      "no application code written"
+    ]
+  },
+  {
+    agent: "backend-coder",
+    role: "Implement backend features: API, services, data layer, business logic.",
+    allowedTaskTypes: ["implementation", "backend", "api", "database", "service", "bugfix"],
+    requiredInputs: ["PLAN.md step description", "relevant context files"],
+    expectedOutputFields: ["files_modified", "summary"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "modify frontend UI component files",
+      "change CI/CD config without devops involvement"
+    ],
+    escalationConditions: [
+      "architecture decision needed",
+      "security-sensitive change without audit",
+      "database migration required"
+    ],
+    stopConditions: ["step implementation complete", "tests pass", "reviewer approves"],
+    successCriteria: [
+      "code written per plan step",
+      "no regressions introduced",
+      "tests exist or updated"
+    ]
+  },
+  {
+    agent: "frontend-coder",
+    role: "Implement frontend features: UI components, client state, rendering.",
+    allowedTaskTypes: ["implementation", "frontend", "ui", "component", "styling", "bugfix"],
+    requiredInputs: ["PLAN.md step description", "design handoff for UI-heavy tasks"],
+    expectedOutputFields: ["files_modified", "summary"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "modify backend API files",
+      "change server configuration",
+      "implement without approved design for UI-heavy tasks"
+    ],
+    escalationConditions: [
+      "design handoff missing for UI-heavy task",
+      "component library or design system unclear"
+    ],
+    stopConditions: ["step implementation complete", "tests pass", "reviewer approves"],
+    successCriteria: [
+      "components implemented per approved design",
+      "no regressions introduced",
+      "tests exist or updated"
+    ]
+  },
+  {
+    agent: "devops",
+    role: "Implement DevOps and infrastructure changes: CI/CD, deployment, infra scripts.",
+    allowedTaskTypes: ["implementation", "ci-cd", "deployment", "infrastructure", "operations"],
+    requiredInputs: ["PLAN.md step description"],
+    expectedOutputFields: ["files_modified", "summary"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "modify application source code",
+      "deploy to production without approval"
+    ],
+    escalationConditions: [
+      "production deployment requires approval",
+      "destructive infra change"
+    ],
+    stopConditions: ["pipeline or infra change complete", "reviewer approves"],
+    successCriteria: ["infrastructure code written per plan", "no prod deployment without approval"]
+  },
+  {
+    agent: "tester",
+    role: "Write and run tests following TDD principles. Tests before implementation.",
+    allowedTaskTypes: ["testing", "tdd", "regression", "integration-test", "unit-test"],
+    requiredInputs: ["feature or step description", "relevant source files"],
+    expectedOutputFields: ["test_files_written", "tests_passing", "coverage_summary"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "delete failing tests to make suite pass",
+      "implement application features",
+      "skip TDD cycle (red → green → refactor)"
+    ],
+    escalationConditions: [
+      "test infrastructure broken",
+      "flaky tests blocking all progress"
+    ],
+    stopConditions: ["all tests pass", "coverage meets threshold"],
+    successCriteria: [
+      "tests written before implementation",
+      "all new tests pass",
+      "no test deletions to fix failures"
+    ]
+  },
+  {
+    agent: "reviewer",
+    role: "Review code quality, security, and convention adherence. Read-only.",
+    allowedTaskTypes: ["review", "code-review", "quality-check"],
+    requiredInputs: ["files to review", "context of changes"],
+    expectedOutputFields: ["verdict", "issues", "recommendations"],
+    allowedTools: ["read", "glob", "grep"],
+    forbiddenActions: [
+      "write or edit any files",
+      "make code changes",
+      "approve security-sensitive changes without security audit"
+    ],
+    escalationConditions: [
+      "security issues found",
+      "critical bugs found",
+      "architectural violations"
+    ],
+    stopConditions: ["review complete", "verdict issued"],
+    successCriteria: [
+      "structured review output with severity levels",
+      "issues categorized",
+      "no file modifications"
+    ]
+  },
+  {
+    agent: "security-auditor",
+    role: "Security audit: OWASP Top 10, injection, auth vulnerabilities. Read-only.",
+    allowedTaskTypes: ["security-audit", "vulnerability-scan", "auth-review"],
+    requiredInputs: ["files to audit", "change context"],
+    expectedOutputFields: ["findings", "severity_breakdown", "recommendations"],
+    allowedTools: ["read", "glob", "grep"],
+    forbiddenActions: [
+      "write or edit files",
+      "make changes to fix vulnerabilities directly"
+    ],
+    escalationConditions: [
+      "CRITICAL vulnerability found",
+      "auth bypass detected",
+      "data exposure found"
+    ],
+    stopConditions: ["audit complete", "all findings documented"],
+    successCriteria: [
+      "OWASP checklist evaluated",
+      "findings documented with severity levels",
+      "no file modifications"
+    ]
+  },
+  {
+    agent: "researcher",
+    role: "Research documentation, APIs, best practices. Read-only analysis.",
+    allowedTaskTypes: ["research", "api-lookup", "documentation", "best-practices"],
+    requiredInputs: ["research topic or question"],
+    expectedOutputFields: ["findings", "references", "recommendations"],
+    allowedTools: ["read", "glob", "grep", "web-search"],
+    forbiddenActions: ["write or edit files", "implement solutions"],
+    escalationConditions: [
+      "critical information unavailable",
+      "conflicting official documentation"
+    ],
+    stopConditions: ["research question answered", "findings documented"],
+    successCriteria: [
+      "findings clearly summarized",
+      "sources cited",
+      "no file modifications"
+    ]
+  },
+  {
+    agent: "architect",
+    role: "Design system architecture, create ADRs, define API contracts.",
+    allowedTaskTypes: ["architecture", "adr", "api-design", "system-design"],
+    requiredInputs: ["feature or system description", "existing codebase context"],
+    expectedOutputFields: ["architecture_document", "adr", "api_contracts"],
+    allowedTools: ["read", "write", "glob", "grep", "planning-state"],
+    forbiddenActions: ["write application code", "run bash commands"],
+    escalationConditions: [
+      "major architectural conflict with existing system",
+      "breaking API change required"
+    ],
+    stopConditions: ["ADR written", "architecture reviewed"],
+    successCriteria: [
+      "architecture documented with tradeoffs",
+      "no application code written"
+    ]
+  },
+  {
+    agent: "writer",
+    role: "Draft project documentation: README, API docs, user guides.",
+    allowedTaskTypes: ["documentation", "readme", "api-docs", "user-guide"],
+    requiredInputs: ["feature description or codebase context"],
+    expectedOutputFields: ["documentation_files"],
+    allowedTools: ["read", "write", "edit", "glob", "grep"],
+    forbiddenActions: ["modify application code", "run bash commands"],
+    escalationConditions: ["documentation scope unclear"],
+    stopConditions: ["docs written", "user confirms completeness"],
+    successCriteria: [
+      "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: "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"
+    ]
+  }
+];
+var REGISTRY = new Map(CONTRACTS.map((c) => [c.agent, c]));
+function getContract(agent) {
+  return REGISTRY.get(agent) ?? null;
+}
+
+// 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-map-codebase",
+  "fd-multi-repo",
+  "fd-new-feature",
+  "fd-new-project",
+  "fd-plan",
+  "fd-quick",
+  "fd-reflect",
+  "fd-resume",
+  "fd-status",
+  "fd-suggest",
+  "fd-translate-intent",
+  "fd-verify",
+  "fd-write-docs"
+];
+function resolveSupervisorConfig(directory) {
+  try {
+    const config = loadFlowDeckConfig(directory);
+    const sup = config?.governance?.supervisor ?? {};
+    return {
+      enabled: sup.enabled ?? false,
+      mode: sup.mode ?? "advisory",
+      reviewedTargets: sup.reviewedTargets ?? [],
+      canBlock: sup.canBlock ?? true,
+      confidenceThreshold: sup.confidenceThreshold ?? 0.7,
+      postExecutionReview: sup.postExecutionReview ?? false
+    };
+  } catch {
+    return {
+      enabled: false,
+      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 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") {
+    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) {
+  if (!exists) {
+    return { decision: "block", approvalStatus: "denied" };
+  }
+  if (ctx.approvalRequired && !ctx.approvalGranted) {
+    return { decision: "escalate", approvalStatus: "escalated" };
+  }
+  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" };
+  }
+  return { decision: "approve", approvalStatus: "approved" };
+}
+function runSupervisorReview(directory, targetName, ctx = {}) {
+  const config = resolveSupervisorConfig(directory);
+  const reviewPhase = ctx.reviewPhase ?? "preflight";
+  const timestamp2 = 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: timestamp2
+    };
+  }
+  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: timestamp2
+    };
+    _emitTelemetry(directory, decision2, ctx);
+    return decision2;
+  }
+  const policyResult = targetType === "command" ? checkCommandPolicy(targetName, ctx) : checkAgentPolicy(targetName, ctx);
+  const confidenceScore = computeConfidence(exists, policyResult, ctx);
+  const { decision, approvalStatus } = resolveDecision(exists, policyResult, confidenceScore, config.confidenceThreshold, ctx);
+  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: timestamp2
+  };
+  _emitTelemetry(directory, supervisorDecision, ctx);
+  return supervisorDecision;
+}
+function shouldProceed(decision, mode, canBlock) {
+  if (!decision.exists)
+    return false;
+  if (!canBlock)
+    return true;
+  if (mode === "strict") {
+    return decision.decision === "approve" || decision.decision === "revise";
+  }
+  return decision.decision !== "block" || decision.confidenceScore > 0.3;
+}
+function _emitTelemetry(directory, decision, ctx) {
+  try {
+    appendEvent(directory, {
+      session_id: ctx.session_id ?? "session-0",
+      run_id: ctx.run_id ?? "unknown",
+      event: "supervisor.review",
+      agent: "supervisor",
+      status: decision.decision === "approve" ? "ok" : decision.decision === "block" ? "blocked" : decision.decision === "escalate" ? "approved" : "ok",
+      meta: {
+        targetName: decision.targetName,
+        targetType: decision.targetType,
+        exists: decision.exists,
+        decision: decision.decision,
+        confidenceScore: decision.confidenceScore,
+        riskFlags: decision.riskFlags,
+        missingRequirements: decision.missingRequirements,
+        reviewPhase: decision.reviewPhase
+      }
+    });
+  } catch {}
+}
+
 // src/index.ts
 function loadRulePaths() {
   const __dir = dirname4(fileURLToPath2(import.meta.url));
@@ -6626,6 +7382,33 @@ var plugin = async (input, _options) => {
         }
       }
       orchestratorGuard.check(toolInput.sessionID ?? "", toolInput.tool ?? toolInput.name ?? "");
+      const toolName = toolInput.tool ?? toolInput.name ?? "";
+      if (toolName === "delegate" || toolName === "run-pipeline") {
+        const supConfig = resolveSupervisorConfig(directory);
+        if (supConfig.enabled) {
+          const args = toolOutput?.args ?? toolInput?.args ?? {};
+          const agentTarget = typeof args.agent === "string" ? args.agent.replace(/^@/, "") : Array.isArray(args.steps) && args.steps[0]?.agent ? String(args.steps[0].agent).replace(/^@/, "") : "";
+          if (agentTarget) {
+            const decision = runSupervisorReview(directory, agentTarget, {
+              taskDescription: typeof args.prompt === "string" ? args.prompt : undefined,
+              reviewPhase: "preflight",
+              session_id: toolInput.sessionID ?? toolInput.sessionId ?? ""
+            });
+            const proceed = shouldProceed(decision, supConfig.mode, supConfig.canBlock);
+            appLog(`[Supervisor] ${decision.reviewPhase} review of "${decision.targetName}": ` + `decision=${decision.decision} exists=${decision.exists} confidence=${decision.confidenceScore.toFixed(2)} ` + `${decision.riskFlags.length > 0 ? `risks=[${decision.riskFlags.join("; ")}]` : ""}`);
+            if (!proceed) {
+              const summary = [
+                `[Supervisor] Execution blocked for target "${decision.targetName}".`,
+                ...decision.reasons,
+                ...decision.missingRequirements.length > 0 ? [`Missing: ${decision.missingRequirements.join(", ")}`] : [],
+                ...decision.requiredChanges.length > 0 ? [`Required changes: ${decision.requiredChanges.join("; ")}`] : []
+              ].join(`
+`);
+              throw new Error(summary);
+            }
+          }
+        }
+      }
       await telemetryHook({ directory }, toolInput, toolOutput);
       await approvalHook({ directory }, toolInput, toolOutput);
       await guardRailsHook({ directory }, toolInput, toolOutput);
@@ -6643,6 +7426,30 @@ var plugin = async (input, _options) => {
       } catch (err) {
         console.error("[FlowDeck Memory] Tool execution error:", err);
       }
+      const afterToolName = toolInput.tool ?? toolInput.name ?? "";
+      if (afterToolName === "delegate" || afterToolName === "run-pipeline") {
+        try {
+          const supConfig = resolveSupervisorConfig(directory);
+          if (supConfig.enabled && supConfig.postExecutionReview) {
+            const args = toolOutput?.args ?? toolInput?.args ?? {};
+            const agentTarget = typeof args.agent === "string" ? args.agent.replace(/^@/, "") : Array.isArray(args.steps) && args.steps[0]?.agent ? String(args.steps[0].agent).replace(/^@/, "") : "";
+            if (agentTarget) {
+              const executionErrored = toolOutput?.error != null || toolOutput?.status === "error" || typeof toolOutput?.output === "string" && toolOutput.output.startsWith("Error:");
+              const decision = runSupervisorReview(directory, agentTarget, {
+                taskDescription: typeof args.prompt === "string" ? args.prompt : undefined,
+                reviewPhase: "post-stage",
+                session_id: toolInput.sessionID ?? toolInput.sessionId ?? "",
+                prerequisitesMet: !executionErrored
+              });
+              const logLevel = decision.decision === "block" || decision.decision === "escalate" ? "[Supervisor][WARN]" : "[Supervisor]";
+              appLog(`${logLevel} post-stage review of "${decision.targetName}": ` + `decision=${decision.decision} exists=${decision.exists} confidence=${decision.confidenceScore.toFixed(2)} ` + `executionErrored=${executionErrored} ` + `${decision.riskFlags.length > 0 ? `risks=[${decision.riskFlags.join("; ")}]` : ""}`);
+              if (supConfig.mode === "strict" && !shouldProceed(decision, "strict", supConfig.canBlock)) {
+                appLog(`[Supervisor][STRICT] Post-execution governance violation detected for "${decision.targetName}". ` + `Review the scorecard and telemetry for this run. ` + `Reasons: ${decision.reasons.join("; ")}`);
+              }
+            }
+          }
+        } catch {}
+      }
       await contextMonitor["tool.execute.after"](toolInput, toolOutput);
     }
   };