@orchestrator-claude/cli 3.11.0 → 3.12.1

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

@@ -60,28 +60,33 @@ orch_get_token() {
   fi
 }
 
-# Get the active (in_progress) workflow ID
+# Get the active (non-terminal) workflow ID
+# Checks in_progress, awaiting_agent, and awaiting_approval statuses
 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
+  local status id
+  for status in in_progress awaiting_agent awaiting_approval; do
+    local resp
+    resp=$(curl -sf --max-time 3 "${API_URL}/api/v1/workflows?status=${status}&limit=1" \
+      -H "Authorization: Bearer $token" \
+      -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || continue
+
+    id=$(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) && [ -n "$id" ] && echo "$id" && return 0
+  done
+  return 1
 }
 
 # Call getNextAction for a workflow
@@ -90,7 +95,7 @@ orch_get_next_action() {
   local token
   token=$(orch_get_token) || return 1
 
-  curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${workflow_id}/next-action" \
+  curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${workflow_id}/pending-action" \
     -H "Authorization: Bearer $token" \
     -H "X-Project-ID: $PROJECT_ID" 2>/dev/null
 }
@@ -102,7 +107,7 @@ orch_evaluate_gate() {
   local token
   token=$(orch_get_token) || return 1
 
-  curl -sf --max-time 10 -X POST "${API_URL}/api/v1/workflows/${workflow_id}/evaluate-gate" \
+  curl -sf --max-time 10 -X POST "${API_URL}/api/v1/workflows/${workflow_id}/gate/evaluate" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $token" \
     -H "X-Project-ID: $PROJECT_ID" \

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

@@ -1,72 +1,58 @@
 #!/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.
+# ping-pong-enforcer.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: PostToolUse on Task (Agent tool)
+# Purpose: After ANY sub-agent returns, call getNextAction and inject
+#          the result as additionalContext into the main 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).
+# Output: JSON with additionalContext containing next action instructions
 
 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) || {
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || WORKFLOW_ID=""
+
+if [ -z "$WORKFLOW_ID" ]; then
   orch_log "PING-PONG: No active workflow, skipping"
   exit 0
-}
+fi
 
 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"
+NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || NEXT_ACTION=""
+
+if [ -z "$NEXT_ACTION" ]; then
+  orch_log "PING-PONG: getNextAction failed or empty"
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"[PING-PONG] Workflow ${WORKFLOW_ID} is active but getNextAction returned empty. Check workflow status with mcp__orchestrator-tools__getStatus.\"}}"
   exit 0
-}
+fi
 
-# Parse response
+# Extract key fields for the context message
 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")
+STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+PROMPT=$(orch_json_field "$NEXT_ACTION" "pendingAction.prompt")
 
-orch_log "PING-PONG: hasAction=$HAS_ACTION status=$STATUS agent=$AGENT phase=$CURRENT_PHASE"
+orch_log "PING-PONG: hasAction=$HAS_ACTION agent=$AGENT status=$STATUS"
 
-# 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"
+    CONTEXT="[PING-PONG] Next action for workflow ${WORKFLOW_ID}: Invoke agent '${AGENT}' via Agent tool. Status: awaiting_agent."
+    [ -n "$PROMPT" ] && CONTEXT="${CONTEXT} Prompt: ${PROMPT}"
   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' })"
+    CONTEXT="[PING-PONG] Workflow ${WORKFLOW_ID} requires human approval before continuing. Ask the user to approve, then call mcp__orchestrator-tools__approveAction."
   else
-    echo ""
-    echo "[ORCHESTRATOR] Workflow $WORKFLOW_ID — pending action status: $STATUS"
-    echo "Full response: $NEXT_ACTION"
+    CONTEXT="[PING-PONG] Workflow ${WORKFLOW_ID} pending action: agent=${AGENT}, status=${STATUS}."
   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
+  CONTEXT="[PING-PONG] No pending actions for workflow ${WORKFLOW_ID}. If current phase is implement, call mcp__orchestrator-extended__completeWorkflow to finalize."
 fi
 
+# Output structured JSON
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":$(echo "$CONTEXT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.stringify(d)))" 2>/dev/null)}}"
 exit 0

package/dist/templates/base/claude/hooks/post-phase-checkpoint.sh

@@ -1,322 +1,203 @@
 #!/bin/bash
-# Post-Phase Checkpoint Hook
-# Automatically creates git checkpoints when workflow phases complete
+# Post-Phase Checkpoint Hook (RFC-012 compatible)
+# Registers a checkpoint in PostgreSQL via the Orchestrator REST API.
+# Replaces the deprecated orchestrator-index.json approach (TD-105 F-04).
 #
 # Triggered by: PostToolUse on Task tool (after agent completes)
-# Behavior: Detects phase transitions and creates git commits
+# Behavior: Infers the just-completed phase from the active workflow state
+#           and registers a checkpoint via the REST API.
 #
-# Requirements:
-#   - jq (for JSON parsing)
-#   - git (for checkpoint commits)
+# Required env vars:
+#   ORCHESTRATOR_API_URL        - Base URL (e.g. http://localhost:3000)
+#   ORCHESTRATOR_PROJECT_TOKEN  - Bearer token for API authentication
 #
-# Debug mode: ORCH_CHECKPOINT_DEBUG=1 to enable verbose logging
+# Optional env vars:
+#   ORCHESTRATOR_PROJECT_ID     - Project ID for project-scoped workflow query
+#   ORCH_CHECKPOINT_DEBUG=1     - Enable verbose logging
+#
+# Always exits 0 (non-blocking).
 
-set -e
+set -euo pipefail
 
-# Configuration
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-INDEX_FILE="$PROJECT_ROOT/.orchestrator/orchestrator-index.json"
-STATE_DIR="$PROJECT_ROOT/.orchestrator/.state"
-LOG_FILE="$STATE_DIR/checkpoint-hook.log"
-LAST_PHASE_FILE="$STATE_DIR/last-checkpointed-phase"
-
-# Ensure state directory exists
-mkdir -p "$STATE_DIR"
-
-# Debug mode
+STATE_DIR="$SCRIPT_DIR/../../.orchestrator/.state"
+LOG_FILE="${STATE_DIR}/checkpoint-hook.log"
+LAST_PHASE_FILE="${STATE_DIR}/last-checkpointed-phase"
 DEBUG="${ORCH_CHECKPOINT_DEBUG:-0}"
 
-# Logging functions
-log_debug() {
-  if [ "$DEBUG" = "1" ]; then
-    echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [DEBUG] $1" >> "$LOG_FILE"
-    echo "[DEBUG] $1" >&2
-  fi
-}
-
-log_info() {
-  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [INFO] $1" >> "$LOG_FILE"
-  if [ "$DEBUG" = "1" ]; then
-    echo "[INFO] $1" >&2
-  fi
-}
+mkdir -p "$STATE_DIR"
 
-log_warn() {
-  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [WARN] $1" >> "$LOG_FILE"
-  echo "[WARN] $1" >&2
-}
+log_info()  { echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [INFO]  $1" >> "$LOG_FILE"; }
+log_warn()  { echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [WARN]  $1" >> "$LOG_FILE"; echo "[WARN]  $1" >&2; }
+log_debug() { [ "$DEBUG" = "1" ] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [DEBUG] $1" >> "$LOG_FILE" || true; }
 
-log_error() {
-  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [ERROR] $1" >> "$LOG_FILE"
-  echo "[ERROR] $1" >&2
-}
+# ── prerequisites ─────────────────────────────────────────────────────────────
 
-# Check prerequisites
 check_prerequisites() {
-  # Check jq
-  if ! command -v jq &> /dev/null; then
-    log_error "jq is not installed. Checkpoints disabled."
+  if ! command -v curl &>/dev/null; then
+    log_warn "curl not found. Checkpoints disabled."
     return 1
   fi
-
-  # Check git
-  if ! command -v git &> /dev/null; then
-    log_error "git is not installed. Checkpoints disabled."
+  if ! command -v jq &>/dev/null; then
+    log_warn "jq not found. Checkpoints disabled."
     return 1
   fi
-
-  # Check if we're in a git repo
-  if ! git -C "$PROJECT_ROOT" rev-parse --is-inside-work-tree &> /dev/null; then
-    log_warn "Not a git repository. Checkpoints disabled."
+  if [ -z "${ORCHESTRATOR_API_URL:-}" ]; then
+    log_debug "ORCHESTRATOR_API_URL not set. Checkpoints disabled."
     return 1
   fi
-
-  # Check index file
-  if [ ! -f "$INDEX_FILE" ]; then
-    log_debug "No orchestrator-index.json found. Skipping."
+  if [ -z "${ORCHESTRATOR_PROJECT_TOKEN:-}" ]; then
+    log_debug "ORCHESTRATOR_PROJECT_TOKEN not set. Checkpoints disabled."
     return 1
   fi
-
   return 0
 }
 
-# Get current phase from orchestrator-index.json
-get_current_phase() {
-  local phase
-  phase=$(jq -r '.activeWorkflow.currentPhase // empty' "$INDEX_FILE" 2>/dev/null)
-  echo "$phase"
+# ── API helpers ────────────────────────────────────────────────────────────────
+
+get_active_workflow() {
+  local project_id="${ORCHESTRATOR_PROJECT_ID:-}"
+  local url="${ORCHESTRATOR_API_URL}/api/v1/workflows?status=in_progress&limit=1"
+  [ -n "$project_id" ] && url="${url}&projectId=${project_id}"
+
+  local tmpfile
+  tmpfile=$(mktemp 2>/dev/null) || return 1
+
+  curl -sf \
+    -H "Authorization: Bearer ${ORCHESTRATOR_PROJECT_TOKEN}" \
+    -H "Content-Type: application/json" \
+    "${url}" \
+    -o "$tmpfile" 2>/dev/null || { rm -f "$tmpfile"; return 1; }
+
+  local result
+  result=$(node -e "
+    const fs=require('fs');
+    try {
+      const d=fs.readFileSync('${tmpfile}','utf8');
+      const j=JSON.parse(d);
+      const wf=Array.isArray(j)?j[0]:j;
+      if(wf&&wf.id){ process.stdout.write(JSON.stringify(wf)); process.exit(0); }
+      process.exit(1);
+    } catch { process.exit(1); }" 2>/dev/null)
+  local rc=$?
+  rm -f "$tmpfile"
+  [ $rc -eq 0 ] && echo "$result" || return 1
 }
 
-# Get workflow ID
-get_workflow_id() {
-  local wf_id
-  wf_id=$(jq -r '.activeWorkflow.id // empty' "$INDEX_FILE" 2>/dev/null)
-  echo "$wf_id"
+create_checkpoint() {
+  local workflow_id="$1"
+  local phase="$2"
+  local description="$3"
+
+  local body
+  body=$(jq -n \
+    --arg phase "$phase" \
+    --arg desc "$description" \
+    '{ phase: $phase, description: $desc }')
+
+  local http_code
+  http_code=$(curl -sf -o /dev/null -w "%{http_code}" \
+    -X POST \
+    -H "Authorization: Bearer ${ORCHESTRATOR_PROJECT_TOKEN}" \
+    -H "Content-Type: application/json" \
+    -d "$body" \
+    "${ORCHESTRATOR_API_URL}/api/v1/workflows/${workflow_id}/checkpoints" 2>/dev/null) || echo ""
+
+  echo "$http_code"
 }
 
-# Get workflow status
-get_workflow_status() {
-  local status
-  status=$(jq -r '.activeWorkflow.status // empty' "$INDEX_FILE" 2>/dev/null)
-  echo "$status"
+# ── dedup guard ────────────────────────────────────────────────────────────────
+
+get_saved_last_phase() {
+  [ -f "$LAST_PHASE_FILE" ] && cat "$LAST_PHASE_FILE" || echo ""
 }
 
-# Get last checkpointed phase from checkpoints array (one with commitHash)
-get_last_checkpointed_phase() {
-  local phase
-  # Find the most recent checkpoint that has a commitHash (indicating it was git-committed)
-  phase=$(jq -r '
-    [.checkpoints[] | select(.commitHash != null and .commitHash != "")]
-    | sort_by(.createdAt)
-    | last
-    | .phase // empty
-  ' "$INDEX_FILE" 2>/dev/null)
-  echo "$phase"
+save_last_phase() {
+  echo "$1" > "$LAST_PHASE_FILE"
 }
 
-# Determine completed phase based on current phase
-# When we see currentPhase = PLAN, it means SPECIFY just completed
-get_completed_phase() {
-  local current_phase="$1"
-  local workflow_status="$2"
+# ── phase inference ────────────────────────────────────────────────────────────
 
-  case "$workflow_status" in
-    "completed")
-      echo "IMPLEMENT"
-      return
-      ;;
+# When workflow is at PLAN, it means SPECIFY just completed, etc.
+get_completed_phase() {
+  local current="$1"
+  local status="$2"
+  case "$status" in
+    "completed") echo "implement"; return ;;
   esac
-
-  case "$current_phase" in
-    "PLAN")
-      echo "SPECIFY"
-      ;;
-    "TASKS")
-      echo "PLAN"
-      ;;
-    "IMPLEMENT")
-      echo "TASKS"
-      ;;
-    *)
-      echo ""
-      ;;
+  case "${current,,}" in
+    "plan")      echo "specify" ;;
+    "tasks")     echo "plan"    ;;
+    "implement") echo "tasks"   ;;
+    *)           echo ""        ;;
   esac
 }
 
-# Create git checkpoint
-create_git_checkpoint() {
-  local phase="$1"
-  local commit_hash=""
-
-  log_info "Creating git checkpoint for phase: $phase"
-
-  # Stage all changes
-  git -C "$PROJECT_ROOT" add -A 2>/dev/null || {
-    log_warn "Failed to stage changes"
-    return 1
-  }
-
-  # Check if there are staged changes
-  if git -C "$PROJECT_ROOT" diff --cached --quiet 2>/dev/null; then
-    log_info "No changes to commit for phase: $phase"
-    echo ""
-    return 0
-  fi
-
-  # Create commit with standard message
-  local commit_msg="[orchestrator] ${phase}: Auto-checkpoint after ${phase} phase"
-
-  if git -C "$PROJECT_ROOT" commit -m "$commit_msg" --no-verify 2>/dev/null; then
-    commit_hash=$(git -C "$PROJECT_ROOT" rev-parse HEAD 2>/dev/null)
-    log_info "Checkpoint commit created: $commit_hash"
-    echo "$commit_hash"
-  else
-    log_warn "Failed to create commit"
-    echo ""
-    return 1
-  fi
-}
-
-# Update orchestrator-index.json with checkpoint
-update_orchestrator_index() {
-  local workflow_id="$1"
-  local phase="$2"
-  local commit_hash="$3"
-  local created_at
-
-  created_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-  local checkpoint_id="cp_${workflow_id}_$(date +%s)"
-  local description="Auto-checkpoint after ${phase} phase"
-
-  log_debug "Updating index with checkpoint: $checkpoint_id"
-
-  # Create temp file for atomic update
-  local temp_file="${INDEX_FILE}.tmp.$$"
-
-  # Use jq to add checkpoint and update statistics
-  if jq --arg id "$checkpoint_id" \
-       --arg wfId "$workflow_id" \
-       --arg phase "$phase" \
-       --arg hash "$commit_hash" \
-       --arg date "$created_at" \
-       --arg desc "$description" '
-    # Add checkpoint to array
-    .checkpoints += [{
-      id: $id,
-      workflowId: $wfId,
-      phase: $phase,
-      commitHash: $hash,
-      createdAt: $date,
-      description: $desc
-    }] |
-    # Update statistics
-    .statistics.totalCheckpoints = (.checkpoints | length) |
-    .statistics.lastActivity = $date
-  ' "$INDEX_FILE" > "$temp_file" 2>/dev/null; then
-
-    # Validate JSON
-    if jq empty "$temp_file" 2>/dev/null; then
-      mv "$temp_file" "$INDEX_FILE"
-      log_info "Index updated with checkpoint: $checkpoint_id"
-      return 0
-    else
-      log_error "Generated invalid JSON"
-      rm -f "$temp_file"
-      return 1
-    fi
-  else
-    log_error "Failed to update index with jq"
-    rm -f "$temp_file"
-    return 1
-  fi
-}
-
-# Save last checkpointed phase
-save_last_phase() {
-  local phase="$1"
-  echo "$phase" > "$LAST_PHASE_FILE"
-}
-
-# Get saved last phase (from state file, not index)
-get_saved_last_phase() {
-  if [ -f "$LAST_PHASE_FILE" ]; then
-    cat "$LAST_PHASE_FILE"
-  else
-    echo ""
-  fi
-}
+# ── main ───────────────────────────────────────────────────────────────────────
 
-# Main execution
 main() {
   log_debug "Hook triggered"
 
-  # Check prerequisites
   if ! check_prerequisites; then
-    log_debug "Prerequisites not met, exiting"
-    exit 0  # Don't fail the hook
+    exit 0
   fi
 
-  # Get current state
-  local current_phase
-  current_phase=$(get_current_phase)
+  local workflow_json
+  workflow_json=$(get_active_workflow 2>/dev/null) || workflow_json=""
 
-  if [ -z "$current_phase" ]; then
-    log_debug "No active workflow phase found"
+  if [ -z "$workflow_json" ]; then
+    log_debug "No active workflow found via API."
     exit 0
   fi
 
-  local workflow_id
-  workflow_id=$(get_workflow_id)
+  local workflow_id current_phase workflow_status
+  workflow_id=$(echo "$workflow_json"     | jq -r '.id // empty'           2>/dev/null || echo "")
+  current_phase=$(echo "$workflow_json"  | jq -r '.currentPhase // empty'  2>/dev/null || echo "")
+  workflow_status=$(echo "$workflow_json" | jq -r '.status // empty'        2>/dev/null || echo "")
 
-  local workflow_status
-  workflow_status=$(get_workflow_status)
-
-  log_debug "Current phase: $current_phase, Status: $workflow_status, Workflow: $workflow_id"
+  if [ -z "$workflow_id" ] || [ -z "$current_phase" ]; then
+    log_debug "Could not parse workflow ID or phase."
+    exit 0
+  fi
 
-  # Determine which phase just completed
   local completed_phase
   completed_phase=$(get_completed_phase "$current_phase" "$workflow_status")
 
   if [ -z "$completed_phase" ]; then
-    log_debug "No completed phase detected from current phase: $current_phase"
+    log_debug "No completed phase inferred from current_phase=${current_phase}."
     exit 0
   fi
 
-  # Check if we already checkpointed this phase
-  local last_checkpointed
-  last_checkpointed=$(get_last_checkpointed_phase)
-
-  local saved_last_phase
-  saved_last_phase=$(get_saved_last_phase)
-
-  log_debug "Completed phase: $completed_phase, Last checkpointed: $last_checkpointed, Saved: $saved_last_phase"
-
-  # Skip if already checkpointed
-  if [ "$completed_phase" = "$last_checkpointed" ] || [ "$completed_phase" = "$saved_last_phase" ]; then
-    log_debug "Phase $completed_phase already checkpointed, skipping"
+  # Dedup guard — skip if we already checkpointed this phase
+  local saved_last
+  saved_last=$(get_saved_last_phase)
+  if [ "$completed_phase" = "$saved_last" ]; then
+    log_debug "Phase ${completed_phase} already checkpointed. Skipping."
     exit 0
   fi
 
-  # Create checkpoint
-  local commit_hash
-  commit_hash=$(create_git_checkpoint "$completed_phase")
+  local description="Auto-checkpoint after ${completed_phase} phase"
+  local http_code
+  http_code=$(create_checkpoint "$workflow_id" "$completed_phase" "$description")
 
-  # Update index (even if no commit, to track the checkpoint)
-  if [ -n "$commit_hash" ]; then
-    if update_orchestrator_index "$workflow_id" "$completed_phase" "$commit_hash"; then
+  case "$http_code" in
+    201|200)
       save_last_phase "$completed_phase"
-      log_info "Checkpoint complete for phase: $completed_phase (commit: $commit_hash)"
-    else
-      log_error "Failed to update index for phase: $completed_phase"
-    fi
-  else
-    log_info "No changes to checkpoint for phase: $completed_phase"
-    save_last_phase "$completed_phase"
-  fi
+      log_info "Checkpoint registered: workflow=${workflow_id}, phase=${completed_phase}"
+      ;;
+    409)
+      save_last_phase "$completed_phase"
+      log_info "Checkpoint already exists (409): phase=${completed_phase}"
+      ;;
+    "")
+      log_warn "API unreachable. Checkpoint skipped for phase=${completed_phase}."
+      ;;
+    *)
+      log_warn "Unexpected HTTP ${http_code} creating checkpoint for phase=${completed_phase}."
+      ;;
+  esac
 
   exit 0
 }
 
-# Run main function
 main "$@"