@orchestrator-claude/cli 3.19.0 → 3.20.0

package/dist/index.d.ts

@@ -12,5 +12,5 @@
 /**
  * CLI version
  */
-export declare const CLI_VERSION = "3.19.0";
+export declare const CLI_VERSION = "3.20.0";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -24,7 +24,7 @@ import { OutputFormatter } from './formatters/OutputFormatter.js';
 /**
  * CLI version
  */
-export const CLI_VERSION = '3.19.0';
+export const CLI_VERSION = '3.20.0';
 /**
  * Main CLI function
  */

package/dist/templates/base/CLAUDE.md.hbs

@@ -22,6 +22,7 @@ The main conversation IS the orchestrator — it coordinates all phases directly
 5. **NEVER edit `.orchestrator/orchestrator-index.json`** — state is in PostgreSQL
 6. **Access artifacts via MCP tools** (`artifactStore`, `artifactRetrieve`), not filesystem paths
 7. **NEVER invoke `Agent(subagent_type: "orchestrator")`** — YOU are the orchestrator (RFC-022)
+8. **Before reading/editing files: if more than a single file or single concern, dispatch a sub-agent** — direct file operations consume 2-5k tokens per file; sub-agents return focused results in ~2k tokens total
 
 ## How Workflows Work
 

package/dist/templates/base/claude/hooks/gate-guardian.ts

@@ -1,9 +1,22 @@
 /**
- * gate-guardian.ts — PreToolUse[advancePhase] hook (RFC-022 Phase 2)
- * Replaces gate-guardian.sh
- * Guards IMPLEMENT phase advance (requires human approval).
- * ALLOWs quick/interactive modes and non-IMPLEMENT phases.
- * FAIL-CLOSED on parse errors.
+ * gate-guardian.ts — PreToolUse[advancePhase] hook (ADR-017 Phase 4)
+ * Adaptive Gate Engine: replaces binary IMPLEMENT-only gate with risk-based engine.
+ *
+ * Flow:
+ *   1. readStdin() → workflowId, targetPhase
+ *   2. getWorkflowMode() → quick/interactive: ALLOW immediately
+ *   3. validate parse → fail: DENY fail-closed
+ *   4. getToken() → fail: DENY fail-closed
+ *   5. if targetPhase matches /implement/i → getNextAction() pending-action check:
+ *      - approved/awaiting_agent → ALLOW (short-circuit, skip classifyRisk)
+ *      - not approved → DENY
+ *   6. classifyRisk(targetPhase) → riskLevel
+ *   7. buildGateContext() + deriveGateStrategy() → GateDecision
+ *   8. switch strategy:
+ *      AUTO_APPROVE      → allow + telemetry context
+ *      ASK_HUMAN         → deny + approval instructions
+ *      BLOCK_AND_REQUIRE → deny + requiredAction
+ *   9. log(HOOK, JSON summary)
  */
 
 import {
@@ -14,11 +27,41 @@ import {
   getWorkflowMode,
   getNextAction,
   outputPreToolUse,
+  type PendingAction,
 } from "./lib/api-client.js";
+import { classifyRisk, deriveGateStrategy, type GateContext } from "./lib/gate-logic.js";
 
 const HOOK = "GATE-GUARDIAN";
 
-async function main(): Promise<void> {
+// ─────────────────────────────────────────────────────────────
+// Dependency injection interface (enables testing without IO)
+// ─────────────────────────────────────────────────────────────
+
+export interface HookDeps {
+  readStdin: () => Promise<Record<string, unknown>>;
+  getWorkflowMode: (id: string) => Promise<string | null>;
+  getToken: () => Promise<string | null>;
+  getNextAction: (id: string) => Promise<PendingAction | null>;
+  output: (opts: { decision: "allow" | "deny"; reason?: string; context?: string }) => void;
+  log: (prefix: string, msg: string) => void;
+}
+
+const defaultDeps: HookDeps = {
+  readStdin,
+  getWorkflowMode,
+  getToken,
+  getNextAction,
+  output: outputPreToolUse,
+  log,
+};
+
+// ─────────────────────────────────────────────────────────────
+// Core logic (exported for testing)
+// ─────────────────────────────────────────────────────────────
+
+export async function mainWithDeps(deps: HookDeps): Promise<void> {
+  const { readStdin, getWorkflowMode, getToken, getNextAction, output, log } = deps;
+
   const stdin = await readStdin();
   log(HOOK, "PreToolUse advancePhase triggered");
 
@@ -27,31 +70,34 @@ async function main(): Promise<void> {
 
   log(HOOK, `workflow=${workflowId} targetPhase=${targetPhase}`);
 
-  // Check workflow mode — quick/interactive skip gate
+  // ── Step 2: Mode check — quick/interactive bypass gate entirely ──────────
   if (workflowId) {
     const mode = await getWorkflowMode(workflowId);
-    log(HOOK, `workflow=${workflowId} mode=${mode || "legacy"}`);
+    log(HOOK, `workflow=${workflowId} mode=${mode ?? "legacy"}`);
 
     if (mode === "quick") {
-      outputPreToolUse({
+      output({
         decision: "allow",
-        context: `Gate to '${targetPhase}' allowed: quick mode skips gate evaluation.`,
+        context: `[GATE] AUTO_APPROVE: quick mode skips gate evaluation for '${targetPhase}'.`,
       });
+      log(HOOK, `ALLOW quick mode phase=${targetPhase}`);
       return;
     }
+
     if (mode === "interactive") {
-      outputPreToolUse({
+      output({
         decision: "allow",
-        context: `Gate to '${targetPhase}' allowed: interactive mode skips artifact gate evaluation.`,
+        context: `[GATE] AUTO_APPROVE: interactive mode skips artifact gate evaluation for '${targetPhase}'.`,
       });
+      log(HOOK, `ALLOW interactive mode phase=${targetPhase}`);
       return;
     }
   }
 
-  // FAIL-CLOSED: can't parse input → DENY
+  // ── Step 3: Parse validation — FAIL-CLOSED ───────────────────────────────
   if (!workflowId || !targetPhase) {
     log(HOOK, "DENY (could not parse input)");
-    outputPreToolUse({
+    output({
       decision: "deny",
       reason: "Gate Guardian: Could not parse workflowId or targetPhase.",
       context: "Ensure you pass both workflowId and targetPhase to advancePhase.",
@@ -59,44 +105,96 @@ async function main(): Promise<void> {
     return;
   }
 
-  // Auth check — FAIL-CLOSED
+  // ── Step 4: Auth check — FAIL-CLOSED ────────────────────────────────────
   const token = await getToken();
   if (!token) {
     log(HOOK, "DENY (auth failed)");
-    outputPreToolUse({
+    output({
       decision: "deny",
       reason: "Gate Guardian: Authentication failed.",
-      context:
-        "Check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID env vars.",
+      context: "Check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID env vars.",
     });
     return;
   }
 
-  // IMPLEMENT phase requires approval
-  if (targetPhase.toLowerCase() === "implement") {
-    log(HOOK, "Checking approval for IMPLEMENT phase");
+  // ── Step 5: IMPLEMENT short-circuit (RF-008) ─────────────────────────────
+  // If targetPhase contains "implement", check pending-action BEFORE classifyRisk.
+  // This prevents AUTO_APPROVE from being applied to implement phases.
+  //
+  // Phase 4: Only 'implement' phases have the approval path (via pending-action).
+  // Other HIGH-risk phases (deploy, migrate, delete) will always ASK_HUMAN → DENY.
+  // An approval path for these will be added in Phase 5 (Adaptive Gate V2).
+  if (/implement/i.test(targetPhase)) {
+    log(HOOK, "Checking approval for IMPLEMENT-type phase");
     const action = await getNextAction(workflowId);
-    if (action) {
-      const status = action.pendingAction?.status || "";
-      if (status !== "approved" && status !== "awaiting_agent") {
-        log(HOOK, `DENY (IMPLEMENT requires approval, status=${status})`);
-        outputPreToolUse({
-          decision: "deny",
-          reason: `Gate Guardian: IMPLEMENT requires human approval. Status: ${status}.`,
-          context:
-            "Ask the user for approval first. Then call mcp__orchestrator-tools__approveAction.",
-        });
-        return;
-      }
+    const status = action?.pendingAction?.status ?? "";
+
+    if (status === "approved" || status === "awaiting_agent") {
+      output({
+        decision: "allow",
+        context: `[GATE] IMPLEMENT approved (status=${status}): proceeding to phase '${targetPhase}'.`,
+      });
+      log(HOOK, JSON.stringify({ hook: "gate-guardian", strategy: "IMPLEMENT_APPROVED", targetPhase, workflowId }));
+      return;
     }
+
+    output({
+      decision: "deny",
+      reason: `Gate Guardian: IMPLEMENT requires human approval. Status: ${status || "not-set"}.`,
+      context: "Ask the user for approval first. Then call mcp__orchestrator-tools__approveAction.",
+    });
+    log(HOOK, JSON.stringify({ hook: "gate-guardian", strategy: "IMPLEMENT_DENIED", targetPhase, workflowId, reason: "pending-action not approved" }));
+    return;
+  }
+
+  // ── Steps 6–8: Adaptive engine for non-implement phases ──────────────────
+  const riskLevel = classifyRisk(targetPhase);
+
+  const ctx: GateContext = {
+    workflowId,
+    targetPhase,
+    // Reserved for Phase 5+6 — will be populated when OLAP integration provides
+    // workflow context. Currently unused by deriveGateStrategy().
+    currentPhase: "",
+    executionMode: null,
+    workflowMode: null,
+    riskLevel,
+  };
+
+  const decision = deriveGateStrategy(ctx);
+
+  log(HOOK, JSON.stringify({ strategy: decision.strategy, targetPhase, riskLevel, reason: decision.reason }));
+
+  switch (decision.strategy) {
+    case "AUTO_APPROVE":
+      output({
+        decision: "allow",
+        context: `[GATE] AUTO_APPROVE: ${decision.reason}`,
+      });
+      break;
+
+    case "ASK_HUMAN":
+      output({
+        decision: "deny",
+        reason: `Gate Guardian: ${decision.reason} Ask user for approval.`,
+      });
+      break;
+
+    case "BLOCK_AND_REQUIRE":
+      output({
+        decision: "deny",
+        reason: `Gate Guardian BLOCKED: ${decision.reason}. Required: ${decision.requiredAction ?? "unspecified"}.`,
+      });
+      break;
   }
+}
 
-  // Non-IMPLEMENT or approved: ALLOW
-  log(HOOK, `ALLOW (phase=${targetPhase})`);
-  outputPreToolUse({
-    decision: "allow",
-    context: `Gate to '${targetPhase}' allowed.`,
-  });
+// ─────────────────────────────────────────────────────────────
+// Entry point (production use)
+// ─────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  await mainWithDeps(defaultDeps);
 }
 
 main().catch(() => process.exit(0));

package/dist/templates/base/claude/hooks/lib/gate-logic.ts

@@ -0,0 +1,58 @@
+/**
+ * gate-logic.ts — Pure gate logic functions for Adaptive Gate Engine (ADR-017 Phase 4)
+ * Zero IO — no imports from node:fs, fetch, or api-client.
+ * Fully testable without any mocks.
+ */
+
+export type RiskLevel = "HIGH" | "LOW";
+export type GateStrategy = "AUTO_APPROVE" | "ASK_HUMAN" | "BLOCK_AND_REQUIRE";
+
+export interface GateContext {
+  workflowId: string;
+  targetPhase: string;
+  currentPhase: string;
+  executionMode: string | null;
+  workflowMode: string | null;
+  riskLevel: RiskLevel;
+}
+
+export interface GateDecision {
+  strategy: GateStrategy;
+  reason: string;
+  requiredAction?: string; // only for BLOCK_AND_REQUIRE
+}
+
+/**
+ * Classify the risk level of a target phase.
+ * HIGH risk: implement, deploy, migrate, delete (case-insensitive, substring match).
+ * LOW risk: everything else.
+ */
+export function classifyRisk(targetPhase: string): RiskLevel {
+  if (/implement|deploy|migrate|delete/i.test(targetPhase)) {
+    return "HIGH";
+  }
+  return "LOW";
+}
+
+/**
+ * Derive the gate strategy based on context.
+ * Rules (evaluated in order):
+ *   1. HIGH risk → ASK_HUMAN
+ *   2. default   → AUTO_APPROVE
+ *
+ * BLOCK_AND_REQUIRE exists as a type but has no trigger rule yet.
+ */
+export function deriveGateStrategy(ctx: GateContext): GateDecision {
+  if (ctx.riskLevel === "HIGH") {
+    return {
+      strategy: "ASK_HUMAN",
+      reason: `Phase '${ctx.targetPhase}' is high-risk and requires human approval before proceeding.`,
+    };
+  }
+
+  // Default: AUTO_APPROVE
+  return {
+    strategy: "AUTO_APPROVE",
+    reason: `Phase '${ctx.targetPhase}' is low-risk — auto-approved.`,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestrator-claude/cli",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "description": "Orchestrator CLI - Project scaffolding, migration and management",
   "type": "module",
   "main": "dist/index.js",

package/templates/base/CLAUDE.md.hbs

@@ -22,6 +22,7 @@ The main conversation IS the orchestrator — it coordinates all phases directly
 5. **NEVER edit `.orchestrator/orchestrator-index.json`** — state is in PostgreSQL
 6. **Access artifacts via MCP tools** (`artifactStore`, `artifactRetrieve`), not filesystem paths
 7. **NEVER invoke `Agent(subagent_type: "orchestrator")`** — YOU are the orchestrator (RFC-022)
+8. **Before reading/editing files: if more than a single file or single concern, dispatch a sub-agent** — direct file operations consume 2-5k tokens per file; sub-agents return focused results in ~2k tokens total
 
 ## How Workflows Work
 

package/templates/base/claude/hooks/gate-guardian.ts

@@ -1,9 +1,22 @@
 /**
- * gate-guardian.ts — PreToolUse[advancePhase] hook (RFC-022 Phase 2)
- * Replaces gate-guardian.sh
- * Guards IMPLEMENT phase advance (requires human approval).
- * ALLOWs quick/interactive modes and non-IMPLEMENT phases.
- * FAIL-CLOSED on parse errors.
+ * gate-guardian.ts — PreToolUse[advancePhase] hook (ADR-017 Phase 4)
+ * Adaptive Gate Engine: replaces binary IMPLEMENT-only gate with risk-based engine.
+ *
+ * Flow:
+ *   1. readStdin() → workflowId, targetPhase
+ *   2. getWorkflowMode() → quick/interactive: ALLOW immediately
+ *   3. validate parse → fail: DENY fail-closed
+ *   4. getToken() → fail: DENY fail-closed
+ *   5. if targetPhase matches /implement/i → getNextAction() pending-action check:
+ *      - approved/awaiting_agent → ALLOW (short-circuit, skip classifyRisk)
+ *      - not approved → DENY
+ *   6. classifyRisk(targetPhase) → riskLevel
+ *   7. buildGateContext() + deriveGateStrategy() → GateDecision
+ *   8. switch strategy:
+ *      AUTO_APPROVE      → allow + telemetry context
+ *      ASK_HUMAN         → deny + approval instructions
+ *      BLOCK_AND_REQUIRE → deny + requiredAction
+ *   9. log(HOOK, JSON summary)
  */
 
 import {
@@ -14,11 +27,41 @@ import {
   getWorkflowMode,
   getNextAction,
   outputPreToolUse,
+  type PendingAction,
 } from "./lib/api-client.js";
+import { classifyRisk, deriveGateStrategy, type GateContext } from "./lib/gate-logic.js";
 
 const HOOK = "GATE-GUARDIAN";
 
-async function main(): Promise<void> {
+// ─────────────────────────────────────────────────────────────
+// Dependency injection interface (enables testing without IO)
+// ─────────────────────────────────────────────────────────────
+
+export interface HookDeps {
+  readStdin: () => Promise<Record<string, unknown>>;
+  getWorkflowMode: (id: string) => Promise<string | null>;
+  getToken: () => Promise<string | null>;
+  getNextAction: (id: string) => Promise<PendingAction | null>;
+  output: (opts: { decision: "allow" | "deny"; reason?: string; context?: string }) => void;
+  log: (prefix: string, msg: string) => void;
+}
+
+const defaultDeps: HookDeps = {
+  readStdin,
+  getWorkflowMode,
+  getToken,
+  getNextAction,
+  output: outputPreToolUse,
+  log,
+};
+
+// ─────────────────────────────────────────────────────────────
+// Core logic (exported for testing)
+// ─────────────────────────────────────────────────────────────
+
+export async function mainWithDeps(deps: HookDeps): Promise<void> {
+  const { readStdin, getWorkflowMode, getToken, getNextAction, output, log } = deps;
+
   const stdin = await readStdin();
   log(HOOK, "PreToolUse advancePhase triggered");
 
@@ -27,31 +70,34 @@ async function main(): Promise<void> {
 
   log(HOOK, `workflow=${workflowId} targetPhase=${targetPhase}`);
 
-  // Check workflow mode — quick/interactive skip gate
+  // ── Step 2: Mode check — quick/interactive bypass gate entirely ──────────
   if (workflowId) {
     const mode = await getWorkflowMode(workflowId);
-    log(HOOK, `workflow=${workflowId} mode=${mode || "legacy"}`);
+    log(HOOK, `workflow=${workflowId} mode=${mode ?? "legacy"}`);
 
     if (mode === "quick") {
-      outputPreToolUse({
+      output({
         decision: "allow",
-        context: `Gate to '${targetPhase}' allowed: quick mode skips gate evaluation.`,
+        context: `[GATE] AUTO_APPROVE: quick mode skips gate evaluation for '${targetPhase}'.`,
       });
+      log(HOOK, `ALLOW quick mode phase=${targetPhase}`);
       return;
     }
+
     if (mode === "interactive") {
-      outputPreToolUse({
+      output({
         decision: "allow",
-        context: `Gate to '${targetPhase}' allowed: interactive mode skips artifact gate evaluation.`,
+        context: `[GATE] AUTO_APPROVE: interactive mode skips artifact gate evaluation for '${targetPhase}'.`,
       });
+      log(HOOK, `ALLOW interactive mode phase=${targetPhase}`);
       return;
     }
   }
 
-  // FAIL-CLOSED: can't parse input → DENY
+  // ── Step 3: Parse validation — FAIL-CLOSED ───────────────────────────────
   if (!workflowId || !targetPhase) {
     log(HOOK, "DENY (could not parse input)");
-    outputPreToolUse({
+    output({
       decision: "deny",
       reason: "Gate Guardian: Could not parse workflowId or targetPhase.",
       context: "Ensure you pass both workflowId and targetPhase to advancePhase.",
@@ -59,44 +105,96 @@ async function main(): Promise<void> {
     return;
   }
 
-  // Auth check — FAIL-CLOSED
+  // ── Step 4: Auth check — FAIL-CLOSED ────────────────────────────────────
   const token = await getToken();
   if (!token) {
     log(HOOK, "DENY (auth failed)");
-    outputPreToolUse({
+    output({
       decision: "deny",
       reason: "Gate Guardian: Authentication failed.",
-      context:
-        "Check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID env vars.",
+      context: "Check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID env vars.",
     });
     return;
   }
 
-  // IMPLEMENT phase requires approval
-  if (targetPhase.toLowerCase() === "implement") {
-    log(HOOK, "Checking approval for IMPLEMENT phase");
+  // ── Step 5: IMPLEMENT short-circuit (RF-008) ─────────────────────────────
+  // If targetPhase contains "implement", check pending-action BEFORE classifyRisk.
+  // This prevents AUTO_APPROVE from being applied to implement phases.
+  //
+  // Phase 4: Only 'implement' phases have the approval path (via pending-action).
+  // Other HIGH-risk phases (deploy, migrate, delete) will always ASK_HUMAN → DENY.
+  // An approval path for these will be added in Phase 5 (Adaptive Gate V2).
+  if (/implement/i.test(targetPhase)) {
+    log(HOOK, "Checking approval for IMPLEMENT-type phase");
     const action = await getNextAction(workflowId);
-    if (action) {
-      const status = action.pendingAction?.status || "";
-      if (status !== "approved" && status !== "awaiting_agent") {
-        log(HOOK, `DENY (IMPLEMENT requires approval, status=${status})`);
-        outputPreToolUse({
-          decision: "deny",
-          reason: `Gate Guardian: IMPLEMENT requires human approval. Status: ${status}.`,
-          context:
-            "Ask the user for approval first. Then call mcp__orchestrator-tools__approveAction.",
-        });
-        return;
-      }
+    const status = action?.pendingAction?.status ?? "";
+
+    if (status === "approved" || status === "awaiting_agent") {
+      output({
+        decision: "allow",
+        context: `[GATE] IMPLEMENT approved (status=${status}): proceeding to phase '${targetPhase}'.`,
+      });
+      log(HOOK, JSON.stringify({ hook: "gate-guardian", strategy: "IMPLEMENT_APPROVED", targetPhase, workflowId }));
+      return;
     }
+
+    output({
+      decision: "deny",
+      reason: `Gate Guardian: IMPLEMENT requires human approval. Status: ${status || "not-set"}.`,
+      context: "Ask the user for approval first. Then call mcp__orchestrator-tools__approveAction.",
+    });
+    log(HOOK, JSON.stringify({ hook: "gate-guardian", strategy: "IMPLEMENT_DENIED", targetPhase, workflowId, reason: "pending-action not approved" }));
+    return;
+  }
+
+  // ── Steps 6–8: Adaptive engine for non-implement phases ──────────────────
+  const riskLevel = classifyRisk(targetPhase);
+
+  const ctx: GateContext = {
+    workflowId,
+    targetPhase,
+    // Reserved for Phase 5+6 — will be populated when OLAP integration provides
+    // workflow context. Currently unused by deriveGateStrategy().
+    currentPhase: "",
+    executionMode: null,
+    workflowMode: null,
+    riskLevel,
+  };
+
+  const decision = deriveGateStrategy(ctx);
+
+  log(HOOK, JSON.stringify({ strategy: decision.strategy, targetPhase, riskLevel, reason: decision.reason }));
+
+  switch (decision.strategy) {
+    case "AUTO_APPROVE":
+      output({
+        decision: "allow",
+        context: `[GATE] AUTO_APPROVE: ${decision.reason}`,
+      });
+      break;
+
+    case "ASK_HUMAN":
+      output({
+        decision: "deny",
+        reason: `Gate Guardian: ${decision.reason} Ask user for approval.`,
+      });
+      break;
+
+    case "BLOCK_AND_REQUIRE":
+      output({
+        decision: "deny",
+        reason: `Gate Guardian BLOCKED: ${decision.reason}. Required: ${decision.requiredAction ?? "unspecified"}.`,
+      });
+      break;
   }
+}
 
-  // Non-IMPLEMENT or approved: ALLOW
-  log(HOOK, `ALLOW (phase=${targetPhase})`);
-  outputPreToolUse({
-    decision: "allow",
-    context: `Gate to '${targetPhase}' allowed.`,
-  });
+// ─────────────────────────────────────────────────────────────
+// Entry point (production use)
+// ─────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  await mainWithDeps(defaultDeps);
 }
 
 main().catch(() => process.exit(0));

package/templates/base/claude/hooks/lib/gate-logic.ts

@@ -0,0 +1,58 @@
+/**
+ * gate-logic.ts — Pure gate logic functions for Adaptive Gate Engine (ADR-017 Phase 4)
+ * Zero IO — no imports from node:fs, fetch, or api-client.
+ * Fully testable without any mocks.
+ */
+
+export type RiskLevel = "HIGH" | "LOW";
+export type GateStrategy = "AUTO_APPROVE" | "ASK_HUMAN" | "BLOCK_AND_REQUIRE";
+
+export interface GateContext {
+  workflowId: string;
+  targetPhase: string;
+  currentPhase: string;
+  executionMode: string | null;
+  workflowMode: string | null;
+  riskLevel: RiskLevel;
+}
+
+export interface GateDecision {
+  strategy: GateStrategy;
+  reason: string;
+  requiredAction?: string; // only for BLOCK_AND_REQUIRE
+}
+
+/**
+ * Classify the risk level of a target phase.
+ * HIGH risk: implement, deploy, migrate, delete (case-insensitive, substring match).
+ * LOW risk: everything else.
+ */
+export function classifyRisk(targetPhase: string): RiskLevel {
+  if (/implement|deploy|migrate|delete/i.test(targetPhase)) {
+    return "HIGH";
+  }
+  return "LOW";
+}
+
+/**
+ * Derive the gate strategy based on context.
+ * Rules (evaluated in order):
+ *   1. HIGH risk → ASK_HUMAN
+ *   2. default   → AUTO_APPROVE
+ *
+ * BLOCK_AND_REQUIRE exists as a type but has no trigger rule yet.
+ */
+export function deriveGateStrategy(ctx: GateContext): GateDecision {
+  if (ctx.riskLevel === "HIGH") {
+    return {
+      strategy: "ASK_HUMAN",
+      reason: `Phase '${ctx.targetPhase}' is high-risk and requires human approval before proceeding.`,
+    };
+  }
+
+  // Default: AUTO_APPROVE
+  return {
+    strategy: "AUTO_APPROVE",
+    reason: `Phase '${ctx.targetPhase}' is low-risk — auto-approved.`,
+  };
+}