@orchestrator-claude/cli 3.10.1 → 3.11.0

package/dist/index.d.ts

@@ -12,5 +12,5 @@
 /**
  * CLI version
  */
-export declare const CLI_VERSION = "3.10.1";
+export declare const CLI_VERSION = "3.11.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.10.1';
+export const CLI_VERSION = '3.11.0';
 /**
  * Main CLI function
  */

package/dist/templates/base/claude/hooks/dangling-workflow-guard.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# dangling-workflow-guard.sh — ADR-013 Core Hook
+# Trigger: Stop (session end)
+# Purpose: Before the conversation ends, check for workflows still
+#          in "in_progress" state. Warn the user and attempt to
+#          complete the workflow automatically.
+#
+# Exit 0 always (non-blocking — we don't want to prevent session exit).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+orch_log "DANGLING-GUARD: Stop hook triggered"
+
+# Find active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || {
+  orch_log "DANGLING-GUARD: No active workflow, clean exit"
+  exit 0
+}
+
+orch_log "DANGLING-GUARD: Found active workflow=$WORKFLOW_ID"
+
+# Get workflow status
+TOKEN=$(orch_get_token 2>/dev/null) || exit 0
+
+STATUS_RESP=$(curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${WORKFLOW_ID}/status" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || exit 0
+
+CURRENT_PHASE=$(orch_json_field "$STATUS_RESP" "currentPhase")
+WF_STATUS=$(orch_json_field "$STATUS_RESP" "status")
+
+orch_log "DANGLING-GUARD: status=$WF_STATUS phase=$CURRENT_PHASE"
+
+if [ "$WF_STATUS" = "in_progress" ] || [ "$WF_STATUS" = "running" ]; then
+  echo ""
+  echo "[DANGLING-GUARD] WARNING: Workflow $WORKFLOW_ID is still active (status: $WF_STATUS, phase: $CURRENT_PHASE)."
+
+  # If in implement phase with no pending actions, auto-complete
+  if [ "$CURRENT_PHASE" = "implement" ]; then
+    NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || exit 0
+    HAS_ACTION=$(orch_json_field "$NEXT_ACTION" "hasAction")
+
+    if [ "$HAS_ACTION" != "true" ]; then
+      echo "[DANGLING-GUARD] Auto-completing workflow (implement phase, no pending actions)..."
+      curl -sf --max-time 10 -X POST "${API_URL}/api/v1/workflows/${WORKFLOW_ID}/complete" \
+        -H "Content-Type: application/json" \
+        -H "Authorization: Bearer $TOKEN" \
+        -H "X-Project-ID: $PROJECT_ID" \
+        -d "{}" >> "$DEBUG_LOG" 2>&1 || true
+      echo "[DANGLING-GUARD] Workflow completed."
+      orch_log "DANGLING-GUARD: Auto-completed workflow $WORKFLOW_ID"
+    else
+      echo "[DANGLING-GUARD] Workflow has pending actions — cannot auto-complete."
+      echo "Resume this session to continue the workflow."
+    fi
+  else
+    echo "[DANGLING-GUARD] Workflow is in '$CURRENT_PHASE' phase — not auto-completing."
+    echo "Resume this session to continue the workflow."
+  fi
+fi
+
+exit 0

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

@@ -0,0 +1,80 @@
+#!/bin/bash
+# gate-guardian.sh — ADR-013 Core Hook
+# Trigger: PreToolUse on mcp__orchestrator-tools__advancePhase
+# Purpose: Before any phase advance, evaluate the gate.
+#          BLOCKS the advance if the gate fails (exit 1).
+#          Also enforces human approval for IMPLEMENT phase.
+#
+# Exit 0 = allow advancePhase to proceed
+# Exit 1 = BLOCK advancePhase (gate failed or approval required)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+# Read stdin (Claude Code passes tool input JSON)
+STDIN_DATA=$(orch_read_stdin)
+orch_log "GATE-GUARDIAN: PreToolUse advancePhase triggered"
+
+# Extract workflowId and targetPhase from tool input
+WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "tool_input.workflowId")
+TARGET_PHASE=$(orch_json_field "$STDIN_DATA" "tool_input.targetPhase")
+
+# Fallback: try without tool_input wrapper
+[ -z "$WORKFLOW_ID" ] && WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "workflowId")
+[ -z "$TARGET_PHASE" ] && TARGET_PHASE=$(orch_json_field "$STDIN_DATA" "targetPhase")
+
+orch_log "GATE-GUARDIAN: workflow=$WORKFLOW_ID targetPhase=$TARGET_PHASE"
+
+# If we can't parse the input, allow (don't break on edge cases)
+if [ -z "$WORKFLOW_ID" ] || [ -z "$TARGET_PHASE" ]; then
+  orch_log "GATE-GUARDIAN: Could not parse input, allowing"
+  exit 0
+fi
+
+# --- IMPLEMENT phase: check for human approval ---
+TARGET_LOWER=$(echo "$TARGET_PHASE" | tr '[:upper:]' '[:lower:]')
+
+if [ "$TARGET_LOWER" = "implement" ]; then
+  orch_log "GATE-GUARDIAN: Checking approval for IMPLEMENT phase"
+
+  # Check pending action status
+  NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || {
+    orch_log "GATE-GUARDIAN: Could not check approval, allowing"
+    exit 0
+  }
+
+  STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+
+  if [ "$STATUS" = "awaiting_approval" ]; then
+    echo ""
+    echo "[GATE-GUARDIAN] BLOCKED: Cannot advance to IMPLEMENT without human approval."
+    echo "The workflow requires user approval before implementation begins."
+    echo "Call mcp__orchestrator-tools__approveAction({ workflowId: '$WORKFLOW_ID' }) after user approves."
+    orch_log "GATE-GUARDIAN: BLOCKED — awaiting_approval for IMPLEMENT"
+    exit 1
+  fi
+fi
+
+# --- All phases: evaluate gate ---
+GATE_RESULT=$(orch_evaluate_gate "$WORKFLOW_ID" "$TARGET_PHASE" 2>/dev/null) || {
+  orch_log "GATE-GUARDIAN: evaluateGate call failed, allowing (API may not support this gate)"
+  exit 0
+}
+
+PASSED=$(orch_json_field "$GATE_RESULT" "passed")
+
+if [ "$PASSED" = "false" ]; then
+  REASONS=$(orch_json_field "$GATE_RESULT" "reasons")
+  echo ""
+  echo "[GATE-GUARDIAN] BLOCKED: Gate to '$TARGET_PHASE' did not pass."
+  echo "Reasons: $REASONS"
+  echo "Fix the issues before advancing."
+  orch_log "GATE-GUARDIAN: BLOCKED — gate failed for $TARGET_PHASE: $REASONS"
+  exit 1
+fi
+
+orch_log "GATE-GUARDIAN: Gate to $TARGET_PHASE PASSED"
+echo "[GATE-GUARDIAN] Gate to '$TARGET_PHASE' PASSED."
+exit 0

package/dist/templates/base/claude/hooks/orch-helpers.sh

@@ -0,0 +1,128 @@
+#!/bin/bash
+# orch-helpers.sh — Shared helper functions for Orchestrator hooks
+# ADR-013: Deterministic Orchestration
+# Sourced by all hooks. NOT called directly.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+STATE_DIR="$PROJECT_ROOT/.orchestrator/.state"
+DEBUG_LOG="$STATE_DIR/hook-debug.log"
+
+# API Configuration (from .env or defaults)
+API_URL="${ORCHESTRATOR_API_URL:-http://localhost:3001}"
+AUTH_EMAIL="${ORCHESTRATOR_ADMIN_EMAIL:-${ORCHESTRATOR_AUTH_EMAIL:-admin@orchestrator.local}}"
+AUTH_PASSWORD="${ORCHESTRATOR_ADMIN_PASSWORD:-${ORCHESTRATOR_AUTH_PASSWORD:-admin123}}"
+PROJECT_ID="${ORCHESTRATOR_PROJECT_ID}"
+
+mkdir -p "$STATE_DIR"
+
+orch_log() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*" >> "$DEBUG_LOG" 2>/dev/null || true
+}
+
+# Read stdin (Claude Code passes JSON via stdin)
+orch_read_stdin() {
+  if [ ! -t 0 ]; then
+    cat
+  else
+    echo ""
+  fi
+}
+
+# Get cached JWT token (login if expired)
+orch_get_token() {
+  local cached="$STATE_DIR/jwt-token"
+  if [ -f "$cached" ]; then
+    local age
+    age=$(( $(date +%s) - $(stat -c%Y "$cached" 2>/dev/null || stat -f%m "$cached" 2>/dev/null || echo 0) ))
+    if [ "$age" -lt 3500 ]; then
+      cat "$cached"
+      return
+    fi
+  fi
+
+  [ -z "$PROJECT_ID" ] && return 1
+
+  local resp
+  resp=$(curl -sf --max-time 5 -X POST "${API_URL}/api/v1/auth/login" \
+    -H "Content-Type: application/json" \
+    -H "X-Project-ID: $PROJECT_ID" \
+    -d "{\"email\":\"${AUTH_EMAIL}\",\"password\":\"${AUTH_PASSWORD}\"}" 2>/dev/null) || return 1
+
+  local token
+  token=$(echo "$resp" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const j=JSON.parse(d);console.log(j.accessToken||j.data?.accessToken||'')}catch{console.log('')}})" 2>/dev/null)
+
+  if [ -n "$token" ] && [ "$token" != "" ]; then
+    echo "$token" > "$cached"
+    echo "$token"
+  else
+    return 1
+  fi
+}
+
+# Get the active (in_progress) workflow ID
+orch_get_active_workflow() {
+  local token
+  token=$(orch_get_token) || return 1
+
+  local resp
+  resp=$(curl -sf --max-time 5 "${API_URL}/api/v1/workflows?status=in_progress&limit=1" \
+    -H "Authorization: Bearer $token" \
+    -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || return 1
+
+  echo "$resp" | node -e "
+    let d='';
+    process.stdin.on('data',c=>d+=c);
+    process.stdin.on('end',()=>{
+      try {
+        const j=JSON.parse(d);
+        const wfs=j.data||j;
+        const wf=Array.isArray(wfs)?wfs[0]:wfs;
+        const id=wf?.id||'';
+        if(id) console.log(id); else process.exit(1);
+      } catch { process.exit(1); }
+    });" 2>/dev/null
+}
+
+# Call getNextAction for a workflow
+orch_get_next_action() {
+  local workflow_id="$1"
+  local token
+  token=$(orch_get_token) || return 1
+
+  curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${workflow_id}/next-action" \
+    -H "Authorization: Bearer $token" \
+    -H "X-Project-ID: $PROJECT_ID" 2>/dev/null
+}
+
+# Call evaluateGate for a workflow
+orch_evaluate_gate() {
+  local workflow_id="$1"
+  local target_phase="$2"
+  local token
+  token=$(orch_get_token) || return 1
+
+  curl -sf --max-time 10 -X POST "${API_URL}/api/v1/workflows/${workflow_id}/evaluate-gate" \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $token" \
+    -H "X-Project-ID: $PROJECT_ID" \
+    -d "{\"targetPhase\":\"${target_phase}\"}" 2>/dev/null
+}
+
+# Extract a field from JSON string using node
+orch_json_field() {
+  local json="$1"
+  local field="$2"
+  echo "$json" | node -e "
+    let d='';
+    process.stdin.on('data',c=>d+=c);
+    process.stdin.on('end',()=>{
+      try {
+        const j=JSON.parse(d);
+        const parts='${field}'.split('.');
+        let v=j;
+        for(const p of parts) v=v?.[p];
+        console.log(v||'');
+      } catch { console.log(''); }
+    });" 2>/dev/null
+}

package/dist/templates/base/claude/hooks/ping-pong-enforcer.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# ping-pong-enforcer.sh — ADR-013 Core Hook
+# Trigger: PostToolUse on Agent
+# Purpose: After ANY sub-agent returns, automatically call getNextAction
+#          and inject the result into the conversation.
+#
+# This makes Ping-Pong DETERMINISTIC: the LLM always receives the next
+# action regardless of whether it "remembers" to call getNextAction.
+#
+# Output goes to stdout → injected into Claude conversation context.
+# Exit 0 always (non-blocking — informational injection).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+# Read stdin (Claude Code passes tool result JSON)
+STDIN_DATA=$(orch_read_stdin)
+orch_log "PING-PONG: PostToolUse Agent triggered"
+
+# Find active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || {
+  orch_log "PING-PONG: No active workflow, skipping"
+  exit 0
+}
+
+orch_log "PING-PONG: Active workflow=$WORKFLOW_ID"
+
+# Call getNextAction
+NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || {
+  orch_log "PING-PONG: getNextAction failed, skipping"
+  exit 0
+}
+
+# Parse response
+HAS_ACTION=$(orch_json_field "$NEXT_ACTION" "hasAction")
+STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+AGENT=$(orch_json_field "$NEXT_ACTION" "pendingAction.agent")
+CURRENT_PHASE=$(orch_json_field "$NEXT_ACTION" "currentPhase")
+
+orch_log "PING-PONG: hasAction=$HAS_ACTION status=$STATUS agent=$AGENT phase=$CURRENT_PHASE"
+
+# Inject result into conversation
+if [ "$HAS_ACTION" = "true" ]; then
+  if [ "$STATUS" = "awaiting_agent" ]; then
+    echo ""
+    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — next action: invoke agent '$AGENT'"
+    echo "You MUST invoke this agent via Task tool with subagent_type='$AGENT'."
+    echo "Workflow ID: $WORKFLOW_ID | Phase: $CURRENT_PHASE"
+  elif [ "$STATUS" = "awaiting_approval" ]; then
+    echo ""
+    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — AWAITING HUMAN APPROVAL"
+    echo "Phase: $CURRENT_PHASE. Ask the user to review artifacts and approve before continuing."
+    echo "After approval, call: mcp__orchestrator-tools__approveAction({ workflowId: '$WORKFLOW_ID' })"
+  else
+    echo ""
+    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — pending action status: $STATUS"
+    echo "Full response: $NEXT_ACTION"
+  fi
+else
+  if [ "$CURRENT_PHASE" = "implement" ]; then
+    echo ""
+    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — no more actions. Phase: implement."
+    echo "You MUST call: mcp__orchestrator-tools__completeWorkflow({ workflowId: '$WORKFLOW_ID' })"
+  else
+    echo ""
+    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — no pending actions. Phase: $CURRENT_PHASE."
+  fi
+fi
+
+exit 0

package/dist/templates/base/claude/settings.json

@@ -19,6 +19,7 @@
       "Write(tests/**)",
       "Write(docs/**)",
       "mcp__orchestrator-tools__*",
+      "mcp__orchestrator-extended__*",
       "mcp__perplexity__*",
       "mcp__knowledge-base__*"
     ],
@@ -47,6 +48,17 @@
             "on_failure": "ignore"
           }
         ]
+      },
+      {
+        "matcher": "mcp__orchestrator-tools__advancePhase",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/gate-guardian.sh",
+            "timeout": 15000,
+            "on_failure": "warn"
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -61,14 +73,8 @@
           },
           {
             "type": "command",
-            "command": ".claude/hooks/post-agent-artifact-relay.sh",
+            "command": ".claude/hooks/ping-pong-enforcer.sh",
             "timeout": 15000,
-            "on_failure": "ignore"
-          },
-          {
-            "type": "command",
-            "command": ".claude/hooks/post-implement-validate.sh",
-            "timeout": 10000,
             "on_failure": "warn"
           },
           {
@@ -79,6 +85,19 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/dangling-workflow-guard.sh",
+            "timeout": 15000,
+            "on_failure": "ignore"
+          }
+        ]
+      }
     ]
   },
   "enableAllProjectMcpServers": true,

package/package.json

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

package/templates/base/claude/hooks/dangling-workflow-guard.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# dangling-workflow-guard.sh — ADR-013 Core Hook
+# Trigger: Stop (session end)
+# Purpose: Before the conversation ends, check for workflows still
+#          in "in_progress" state. Warn the user and attempt to
+#          complete the workflow automatically.
+#
+# Exit 0 always (non-blocking — we don't want to prevent session exit).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+orch_log "DANGLING-GUARD: Stop hook triggered"
+
+# Find active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || {
+  orch_log "DANGLING-GUARD: No active workflow, clean exit"
+  exit 0
+}
+
+orch_log "DANGLING-GUARD: Found active workflow=$WORKFLOW_ID"
+
+# Get workflow status
+TOKEN=$(orch_get_token 2>/dev/null) || exit 0
+
+STATUS_RESP=$(curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${WORKFLOW_ID}/status" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || exit 0
+
+CURRENT_PHASE=$(orch_json_field "$STATUS_RESP" "currentPhase")
+WF_STATUS=$(orch_json_field "$STATUS_RESP" "status")
+
+orch_log "DANGLING-GUARD: status=$WF_STATUS phase=$CURRENT_PHASE"
+
+if [ "$WF_STATUS" = "in_progress" ] || [ "$WF_STATUS" = "running" ]; then
+  echo ""
+  echo "[DANGLING-GUARD] WARNING: Workflow $WORKFLOW_ID is still active (status: $WF_STATUS, phase: $CURRENT_PHASE)."
+
+  # If in implement phase with no pending actions, auto-complete
+  if [ "$CURRENT_PHASE" = "implement" ]; then
+    NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || exit 0
+    HAS_ACTION=$(orch_json_field "$NEXT_ACTION" "hasAction")
+
+    if [ "$HAS_ACTION" != "true" ]; then
+      echo "[DANGLING-GUARD] Auto-completing workflow (implement phase, no pending actions)..."
+      curl -sf --max-time 10 -X POST "${API_URL}/api/v1/workflows/${WORKFLOW_ID}/complete" \
+        -H "Content-Type: application/json" \
+        -H "Authorization: Bearer $TOKEN" \
+        -H "X-Project-ID: $PROJECT_ID" \
+        -d "{}" >> "$DEBUG_LOG" 2>&1 || true
+      echo "[DANGLING-GUARD] Workflow completed."
+      orch_log "DANGLING-GUARD: Auto-completed workflow $WORKFLOW_ID"
+    else
+      echo "[DANGLING-GUARD] Workflow has pending actions — cannot auto-complete."
+      echo "Resume this session to continue the workflow."
+    fi
+  else
+    echo "[DANGLING-GUARD] Workflow is in '$CURRENT_PHASE' phase — not auto-completing."
+    echo "Resume this session to continue the workflow."
+  fi
+fi
+
+exit 0

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

@@ -0,0 +1,80 @@
+#!/bin/bash
+# gate-guardian.sh — ADR-013 Core Hook
+# Trigger: PreToolUse on mcp__orchestrator-tools__advancePhase
+# Purpose: Before any phase advance, evaluate the gate.
+#          BLOCKS the advance if the gate fails (exit 1).
+#          Also enforces human approval for IMPLEMENT phase.
+#
+# Exit 0 = allow advancePhase to proceed
+# Exit 1 = BLOCK advancePhase (gate failed or approval required)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+# Read stdin (Claude Code passes tool input JSON)
+STDIN_DATA=$(orch_read_stdin)
+orch_log "GATE-GUARDIAN: PreToolUse advancePhase triggered"
+
+# Extract workflowId and targetPhase from tool input
+WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "tool_input.workflowId")
+TARGET_PHASE=$(orch_json_field "$STDIN_DATA" "tool_input.targetPhase")
+
+# Fallback: try without tool_input wrapper
+[ -z "$WORKFLOW_ID" ] && WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "workflowId")
+[ -z "$TARGET_PHASE" ] && TARGET_PHASE=$(orch_json_field "$STDIN_DATA" "targetPhase")
+
+orch_log "GATE-GUARDIAN: workflow=$WORKFLOW_ID targetPhase=$TARGET_PHASE"
+
+# If we can't parse the input, allow (don't break on edge cases)
+if [ -z "$WORKFLOW_ID" ] || [ -z "$TARGET_PHASE" ]; then
+  orch_log "GATE-GUARDIAN: Could not parse input, allowing"
+  exit 0
+fi
+
+# --- IMPLEMENT phase: check for human approval ---
+TARGET_LOWER=$(echo "$TARGET_PHASE" | tr '[:upper:]' '[:lower:]')
+
+if [ "$TARGET_LOWER" = "implement" ]; then
+  orch_log "GATE-GUARDIAN: Checking approval for IMPLEMENT phase"
+
+  # Check pending action status
+  NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || {
+    orch_log "GATE-GUARDIAN: Could not check approval, allowing"
+    exit 0
+  }
+
+  STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+
+  if [ "$STATUS" = "awaiting_approval" ]; then
+    echo ""
+    echo "[GATE-GUARDIAN] BLOCKED: Cannot advance to IMPLEMENT without human approval."
+    echo "The workflow requires user approval before implementation begins."
+    echo "Call mcp__orchestrator-tools__approveAction({ workflowId: '$WORKFLOW_ID' }) after user approves."
+    orch_log "GATE-GUARDIAN: BLOCKED — awaiting_approval for IMPLEMENT"
+    exit 1
+  fi
+fi
+
+# --- All phases: evaluate gate ---
+GATE_RESULT=$(orch_evaluate_gate "$WORKFLOW_ID" "$TARGET_PHASE" 2>/dev/null) || {
+  orch_log "GATE-GUARDIAN: evaluateGate call failed, allowing (API may not support this gate)"
+  exit 0
+}
+
+PASSED=$(orch_json_field "$GATE_RESULT" "passed")
+
+if [ "$PASSED" = "false" ]; then
+  REASONS=$(orch_json_field "$GATE_RESULT" "reasons")
+  echo ""
+  echo "[GATE-GUARDIAN] BLOCKED: Gate to '$TARGET_PHASE' did not pass."
+  echo "Reasons: $REASONS"
+  echo "Fix the issues before advancing."
+  orch_log "GATE-GUARDIAN: BLOCKED — gate failed for $TARGET_PHASE: $REASONS"
+  exit 1
+fi
+
+orch_log "GATE-GUARDIAN: Gate to $TARGET_PHASE PASSED"
+echo "[GATE-GUARDIAN] Gate to '$TARGET_PHASE' PASSED."
+exit 0

package/templates/base/claude/hooks/orch-helpers.sh

@@ -0,0 +1,128 @@
+#!/bin/bash
+# orch-helpers.sh — Shared helper functions for Orchestrator hooks
+# ADR-013: Deterministic Orchestration
+# Sourced by all hooks. NOT called directly.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+STATE_DIR="$PROJECT_ROOT/.orchestrator/.state"
+DEBUG_LOG="$STATE_DIR/hook-debug.log"
+
+# API Configuration (from .env or defaults)
+API_URL="${ORCHESTRATOR_API_URL:-http://localhost:3001}"
+AUTH_EMAIL="${ORCHESTRATOR_ADMIN_EMAIL:-${ORCHESTRATOR_AUTH_EMAIL:-admin@orchestrator.local}}"
+AUTH_PASSWORD="${ORCHESTRATOR_ADMIN_PASSWORD:-${ORCHESTRATOR_AUTH_PASSWORD:-admin123}}"
+PROJECT_ID="${ORCHESTRATOR_PROJECT_ID}"
+
+mkdir -p "$STATE_DIR"
+
+orch_log() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*" >> "$DEBUG_LOG" 2>/dev/null || true
+}
+
+# Read stdin (Claude Code passes JSON via stdin)
+orch_read_stdin() {
+  if [ ! -t 0 ]; then
+    cat
+  else
+    echo ""
+  fi
+}
+
+# Get cached JWT token (login if expired)
+orch_get_token() {
+  local cached="$STATE_DIR/jwt-token"
+  if [ -f "$cached" ]; then
+    local age
+    age=$(( $(date +%s) - $(stat -c%Y "$cached" 2>/dev/null || stat -f%m "$cached" 2>/dev/null || echo 0) ))
+    if [ "$age" -lt 3500 ]; then
+      cat "$cached"
+      return
+    fi
+  fi
+
+  [ -z "$PROJECT_ID" ] && return 1
+
+  local resp
+  resp=$(curl -sf --max-time 5 -X POST "${API_URL}/api/v1/auth/login" \
+    -H "Content-Type: application/json" \
+    -H "X-Project-ID: $PROJECT_ID" \
+    -d "{\"email\":\"${AUTH_EMAIL}\",\"password\":\"${AUTH_PASSWORD}\"}" 2>/dev/null) || return 1
+
+  local token
+  token=$(echo "$resp" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const j=JSON.parse(d);console.log(j.accessToken||j.data?.accessToken||'')}catch{console.log('')}})" 2>/dev/null)
+
+  if [ -n "$token" ] && [ "$token" != "" ]; then
+    echo "$token" > "$cached"
+    echo "$token"
+  else
+    return 1
+  fi
+}
+
+# Get the active (in_progress) workflow ID
+orch_get_active_workflow() {
+  local token
+  token=$(orch_get_token) || return 1
+
+  local resp
+  resp=$(curl -sf --max-time 5 "${API_URL}/api/v1/workflows?status=in_progress&limit=1" \
+    -H "Authorization: Bearer $token" \
+    -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || return 1
+
+  echo "$resp" | node -e "
+    let d='';
+    process.stdin.on('data',c=>d+=c);
+    process.stdin.on('end',()=>{
+      try {
+        const j=JSON.parse(d);
+        const wfs=j.data||j;
+        const wf=Array.isArray(wfs)?wfs[0]:wfs;
+        const id=wf?.id||'';
+        if(id) console.log(id); else process.exit(1);
+      } catch { process.exit(1); }
+    });" 2>/dev/null
+}
+
+# Call getNextAction for a workflow
+orch_get_next_action() {
+  local workflow_id="$1"
+  local token
+  token=$(orch_get_token) || return 1
+
+  curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${workflow_id}/next-action" \
+    -H "Authorization: Bearer $token" \
+    -H "X-Project-ID: $PROJECT_ID" 2>/dev/null
+}
+
+# Call evaluateGate for a workflow
+orch_evaluate_gate() {
+  local workflow_id="$1"
+  local target_phase="$2"
+  local token
+  token=$(orch_get_token) || return 1
+
+  curl -sf --max-time 10 -X POST "${API_URL}/api/v1/workflows/${workflow_id}/evaluate-gate" \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $token" \
+    -H "X-Project-ID: $PROJECT_ID" \
+    -d "{\"targetPhase\":\"${target_phase}\"}" 2>/dev/null
+}
+
+# Extract a field from JSON string using node
+orch_json_field() {
+  local json="$1"
+  local field="$2"
+  echo "$json" | node -e "
+    let d='';
+    process.stdin.on('data',c=>d+=c);
+    process.stdin.on('end',()=>{
+      try {
+        const j=JSON.parse(d);
+        const parts='${field}'.split('.');
+        let v=j;
+        for(const p of parts) v=v?.[p];
+        console.log(v||'');
+      } catch { console.log(''); }
+    });" 2>/dev/null
+}

package/templates/base/claude/hooks/ping-pong-enforcer.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# ping-pong-enforcer.sh — ADR-013 Core Hook
+# Trigger: PostToolUse on Agent
+# Purpose: After ANY sub-agent returns, automatically call getNextAction
+#          and inject the result into the conversation.
+#
+# This makes Ping-Pong DETERMINISTIC: the LLM always receives the next
+# action regardless of whether it "remembers" to call getNextAction.
+#
+# Output goes to stdout → injected into Claude conversation context.
+# Exit 0 always (non-blocking — informational injection).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+# Read stdin (Claude Code passes tool result JSON)
+STDIN_DATA=$(orch_read_stdin)
+orch_log "PING-PONG: PostToolUse Agent triggered"
+
+# Find active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || {
+  orch_log "PING-PONG: No active workflow, skipping"
+  exit 0
+}
+
+orch_log "PING-PONG: Active workflow=$WORKFLOW_ID"
+
+# Call getNextAction
+NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || {
+  orch_log "PING-PONG: getNextAction failed, skipping"
+  exit 0
+}
+
+# Parse response
+HAS_ACTION=$(orch_json_field "$NEXT_ACTION" "hasAction")
+STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+AGENT=$(orch_json_field "$NEXT_ACTION" "pendingAction.agent")
+CURRENT_PHASE=$(orch_json_field "$NEXT_ACTION" "currentPhase")
+
+orch_log "PING-PONG: hasAction=$HAS_ACTION status=$STATUS agent=$AGENT phase=$CURRENT_PHASE"
+
+# Inject result into conversation
+if [ "$HAS_ACTION" = "true" ]; then
+  if [ "$STATUS" = "awaiting_agent" ]; then
+    echo ""
+    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — next action: invoke agent '$AGENT'"
+    echo "You MUST invoke this agent via Task tool with subagent_type='$AGENT'."
+    echo "Workflow ID: $WORKFLOW_ID | Phase: $CURRENT_PHASE"
+  elif [ "$STATUS" = "awaiting_approval" ]; then
+    echo ""
+    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — AWAITING HUMAN APPROVAL"
+    echo "Phase: $CURRENT_PHASE. Ask the user to review artifacts and approve before continuing."
+    echo "After approval, call: mcp__orchestrator-tools__approveAction({ workflowId: '$WORKFLOW_ID' })"
+  else
+    echo ""
+    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — pending action status: $STATUS"
+    echo "Full response: $NEXT_ACTION"
+  fi
+else
+  if [ "$CURRENT_PHASE" = "implement" ]; then
+    echo ""
+    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — no more actions. Phase: implement."
+    echo "You MUST call: mcp__orchestrator-tools__completeWorkflow({ workflowId: '$WORKFLOW_ID' })"
+  else
+    echo ""
+    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — no pending actions. Phase: $CURRENT_PHASE."
+  fi
+fi
+
+exit 0

package/templates/base/claude/settings.json

@@ -19,6 +19,7 @@
       "Write(tests/**)",
       "Write(docs/**)",
       "mcp__orchestrator-tools__*",
+      "mcp__orchestrator-extended__*",
       "mcp__perplexity__*",
       "mcp__knowledge-base__*"
     ],
@@ -47,6 +48,17 @@
             "on_failure": "ignore"
           }
         ]
+      },
+      {
+        "matcher": "mcp__orchestrator-tools__advancePhase",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/gate-guardian.sh",
+            "timeout": 15000,
+            "on_failure": "warn"
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -61,14 +73,8 @@
           },
           {
             "type": "command",
-            "command": ".claude/hooks/post-agent-artifact-relay.sh",
+            "command": ".claude/hooks/ping-pong-enforcer.sh",
             "timeout": 15000,
-            "on_failure": "ignore"
-          },
-          {
-            "type": "command",
-            "command": ".claude/hooks/post-implement-validate.sh",
-            "timeout": 10000,
             "on_failure": "warn"
           },
           {
@@ -79,6 +85,19 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/dangling-workflow-guard.sh",
+            "timeout": 15000,
+            "on_failure": "ignore"
+          }
+        ]
+      }
     ]
   },
   "enableAllProjectMcpServers": true,