@orchestrator-claude/definitions 3.12.1 → 3.12.2

package/hooks/post-phase-checkpoint.sh

@@ -1,180 +1,202 @@
 #!/bin/bash
-# Post-Phase Checkpoint Hook (v2 — REST API)
-# Defense-in-depth: agents create checkpoints via MCP, this is a safety net.
-# 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)
-# Requirements: git
-# Debug mode: ORCH_CHECKPOINT_DEBUG=1 to enable verbose logging
+# Behavior: Infers the just-completed phase from the active workflow state
+#           and registers a checkpoint via the REST API.
+#
+# Required env vars:
+#   ORCHESTRATOR_API_URL        - Base URL (e.g. http://localhost:3000)
+#   ORCHESTRATOR_PROJECT_TOKEN  - Bearer token for API authentication
+#
+# 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)"
-STATE_DIR="$PROJECT_ROOT/.orchestrator/.state"
-LOG_FILE="$STATE_DIR/checkpoint-hook.log"
-LAST_PHASE_FILE="$STATE_DIR/last-checkpointed-phase"
-
-# API Configuration
-API_URL="${ORCHESTRATOR_API_URL:-http://localhost:3001}"
-AUTH_EMAIL="${ORCHESTRATOR_AUTH_EMAIL:-admin@orchestrator.local}"
-AUTH_PASSWORD="${ORCHESTRATOR_AUTH_PASSWORD:-admin123}"
-PROJECT_ID="${ORCHESTRATOR_PROJECT_ID:-d001d65d-25f5-4d13-b1dc-d006873e949c}"
+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}"
 
 mkdir -p "$STATE_DIR"
 
-DEBUG="${ORCH_CHECKPOINT_DEBUG:-0}"
+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_debug() {
-  if [ "$DEBUG" = "1" ]; then
-    echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [DEBUG] $1" >> "$LOG_FILE"
-    echo "[DEBUG] $1" >&2
-  fi
-}
+# ── prerequisites ─────────────────────────────────────────────────────────────
 
-log_info() {
-  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [INFO] $1" >> "$LOG_FILE"
-  if [ "$DEBUG" = "1" ]; then
-    echo "[INFO] $1" >&2
+check_prerequisites() {
+  if ! command -v curl &>/dev/null; then
+    log_warn "curl not found. Checkpoints disabled."
+    return 1
+  fi
+  if ! command -v jq &>/dev/null; then
+    log_warn "jq not found. Checkpoints disabled."
+    return 1
   fi
+  if [ -z "${ORCHESTRATOR_API_URL:-}" ]; then
+    log_debug "ORCHESTRATOR_API_URL not set. Checkpoints disabled."
+    return 1
+  fi
+  if [ -z "${ORCHESTRATOR_PROJECT_TOKEN:-}" ]; then
+    log_debug "ORCHESTRATOR_PROJECT_TOKEN not set. Checkpoints disabled."
+    return 1
+  fi
+  return 0
 }
 
-log_error() {
-  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [ERROR] $1" >> "$LOG_FILE"
-  echo "[ERROR] $1" >&2
-}
+# ── API helpers ────────────────────────────────────────────────────────────────
 
-# Auth (shared with other hooks — cached JWT)
-get_token() {
-  local cached="$STATE_DIR/jwt-token"
-  if [ -f "$cached" ]; then
-    local 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
-  local resp
-  resp=$(curl -s -f -X POST "${API_URL}/api/v1/auth/login" \
+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" \
-    -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.data?.accessToken||j.accessToken||j.token||'')}catch{console.log('')}})" 2>/dev/null)
-  [ -n "$token" ] && { echo "$token" > "$cached"; echo "$token"; }
+    "${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 info from REST API
-get_workflow_info() {
-  local token
-  token=$(get_token) || return 1
-  curl -s -f "${API_URL}/api/v1/workflows?status=in_progress" \
-    -H "Authorization: Bearer $token" \
-    -H "X-Project-ID: $PROJECT_ID" 2>/dev/null
-}
+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 ""
 
-# Determine completed phase from current phase
-# When currentPhase = PLAN, SPECIFY just completed; etc.
-get_completed_phase() {
-  case "$1" in
-    plan|PLAN) echo "specify" ;;
-    tasks|TASKS) echo "plan" ;;
-    implement|IMPLEMENT) echo "tasks" ;;
-    completed) echo "implement" ;;
-    *) echo "" ;;
-  esac
+  echo "$http_code"
 }
 
-# Create git checkpoint
-create_git_checkpoint() {
-  local phase="$1"
-
-  log_info "Creating git checkpoint for phase: $phase"
+# ── dedup guard ────────────────────────────────────────────────────────────────
 
-  git -C "$PROJECT_ROOT" add -A 2>/dev/null || return 1
+get_saved_last_phase() {
+  [ -f "$LAST_PHASE_FILE" ] && cat "$LAST_PHASE_FILE" || echo ""
+}
 
-  # 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
+save_last_phase() {
+  echo "$1" > "$LAST_PHASE_FILE"
+}
 
-  local commit_msg="[orchestrator] ${phase}: Auto-checkpoint after ${phase} phase"
+# ── phase inference ────────────────────────────────────────────────────────────
 
-  if git -C "$PROJECT_ROOT" commit -m "$commit_msg" --no-verify 2>/dev/null; then
-    local commit_hash
-    commit_hash=$(git -C "$PROJECT_ROOT" rev-parse HEAD 2>/dev/null)
-    log_info "Checkpoint commit created: $commit_hash"
-    echo "$commit_hash"
-  else
-    log_error "Failed to create commit"
-    echo ""
-    return 1
-  fi
+# 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,,}" in
+    "plan")      echo "specify" ;;
+    "tasks")     echo "plan"    ;;
+    "implement") echo "tasks"   ;;
+    *)           echo ""        ;;
+  esac
 }
 
-# Register checkpoint via REST API
-register_checkpoint() {
-  local wf_id="$1"
-  local phase="$2"
-  local commit_hash="$3"
-  local description="$4"
-  local token
-  token=$(get_token) || return 1
-  curl -s -f -X POST "${API_URL}/api/v1/checkpoints" \
-    -H "Content-Type: application/json" \
-    -H "Authorization: Bearer $token" \
-    -H "X-Project-ID: $PROJECT_ID" \
-    -d "{\"workflowId\":\"${wf_id}\",\"description\":\"${description}\",\"commitHash\":\"${commit_hash}\"}" >> "$LOG_FILE" 2>&1 || true
-}
+# ── main ───────────────────────────────────────────────────────────────────────
 
 main() {
   log_debug "Hook triggered"
 
-  # Prerequisites
-  command -v git &>/dev/null || { log_error "git not found"; exit 0; }
-  git -C "$PROJECT_ROOT" rev-parse --is-inside-work-tree &>/dev/null || { exit 0; }
-
-  # Get workflow from API
-  WORKFLOW_RESP=$(get_workflow_info) || { log_debug "No API access"; exit 0; }
-
-  WORKFLOW_DATA=$(echo "$WORKFLOW_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;
-        if(!wf){console.log('{}');return;}
-        console.log(JSON.stringify({id:wf.id||'',phase:wf.currentPhase||wf.phase||'',status:wf.status||''}));
-      }catch{console.log('{}')}
-    });
-  " 2>/dev/null)
+  if ! check_prerequisites; then
+    exit 0
+  fi
 
-  WF_ID=$(echo "$WORKFLOW_DATA" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).id||'')}catch{console.log('')}})" 2>/dev/null)
-  CURRENT_PHASE=$(echo "$WORKFLOW_DATA" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).phase||'')}catch{console.log('')}})" 2>/dev/null)
+  local workflow_json
+  workflow_json=$(get_active_workflow 2>/dev/null) || workflow_json=""
 
-  [ -z "$CURRENT_PHASE" ] && { log_debug "No active phase"; exit 0; }
+  if [ -z "$workflow_json" ]; then
+    log_debug "No active workflow found via API."
+    exit 0
+  fi
 
-  COMPLETED_PHASE=$(get_completed_phase "$CURRENT_PHASE")
-  [ -z "$COMPLETED_PHASE" ] && { log_debug "No completed phase from: $CURRENT_PHASE"; exit 0; }
+  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 "")
 
-  # Check if already checkpointed
-  SAVED=$(cat "$LAST_PHASE_FILE" 2>/dev/null || echo "")
-  [ "$COMPLETED_PHASE" = "$SAVED" ] && { log_debug "Already checkpointed: $COMPLETED_PHASE"; exit 0; }
+  if [ -z "$workflow_id" ] || [ -z "$current_phase" ]; then
+    log_debug "Could not parse workflow ID or phase."
+    exit 0
+  fi
 
-  log_debug "Current phase: $CURRENT_PHASE, Completed phase: $COMPLETED_PHASE, WF: $WF_ID"
+  local completed_phase
+  completed_phase=$(get_completed_phase "$current_phase" "$workflow_status")
 
-  # Create git checkpoint
-  COMMIT_HASH=$(create_git_checkpoint "$COMPLETED_PHASE")
+  if [ -z "$completed_phase" ]; then
+    log_debug "No completed phase inferred from current_phase=${current_phase}."
+    exit 0
+  fi
 
-  if [ -n "$COMMIT_HASH" ]; then
-    register_checkpoint "$WF_ID" "$COMPLETED_PHASE" "$COMMIT_HASH" "Auto-checkpoint after ${COMPLETED_PHASE} phase"
-    log_info "Checkpoint: phase=$COMPLETED_PHASE commit=$COMMIT_HASH"
-  else
-    log_info "No changes for phase: $COMPLETED_PHASE"
+  # 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
 
-  echo "$COMPLETED_PHASE" > "$LAST_PHASE_FILE"
+  local description="Auto-checkpoint after ${completed_phase} phase"
+  local http_code
+  http_code=$(create_checkpoint "$workflow_id" "$completed_phase" "$description")
+
+  case "$http_code" in
+    201|200)
+      save_last_phase "$completed_phase"
+      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
 }
 

package/hooks/prompt-orchestrator.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# prompt-orchestrator.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: UserPromptSubmit
+# Purpose: On every user prompt, inject orchestrator context.
+#          If no workflow active, remind about workflow requirement.
+#          If workflow active, inject current state.
+#
+# Output: JSON with additionalContext (never blocks prompts)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+orch_log "PROMPT-ORCH: UserPromptSubmit triggered"
+
+# Find active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || WORKFLOW_ID=""
+
+if [ -z "$WORKFLOW_ID" ]; then
+  # No workflow — inject reminder (lightweight, no API calls)
+  orch_log "PROMPT-ORCH: No active workflow, injecting reminder"
+  echo '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"[ORCHESTRATOR] No active workflow. If this request involves creating, modifying, or fixing code, you must start a workflow first (detectWorkflow → startWorkflow). The workflow-guard hook will block writes to src/ without a workflow."}}'
+  exit 0
+fi
+
+# Active workflow — inject state
+NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || NEXT_ACTION=""
+HAS_ACTION=$(orch_json_field "$NEXT_ACTION" "hasAction")
+AGENT=$(orch_json_field "$NEXT_ACTION" "pendingAction.agent")
+PA_STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+
+if [ "$HAS_ACTION" = "true" ]; then
+  CONTEXT="[ORCHESTRATOR] Active workflow: ${WORKFLOW_ID}. Next: invoke '${AGENT}' (${PA_STATUS})."
+else
+  CONTEXT="[ORCHESTRATOR] Active workflow: ${WORKFLOW_ID}. No pending actions."
+fi
+
+orch_log "PROMPT-ORCH: workflow=$WORKFLOW_ID hasAction=$HAS_ACTION"
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"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/hooks/session-orchestrator.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# session-orchestrator.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: SessionStart
+# Purpose: On session start, check for active workflow and inject context.
+#          Helps the LLM resume work from where it left off.
+#
+# Output: JSON with additionalContext containing workflow state
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+orch_log "SESSION-ORCH: SessionStart hook triggered"
+
+# Find active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || WORKFLOW_ID=""
+
+if [ -z "$WORKFLOW_ID" ]; then
+  orch_log "SESSION-ORCH: No active workflow"
+  echo '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"[ORCHESTRATOR] No active workflow. For feature requests, bug fixes, or refactoring, start with:\n1. mcp__orchestrator-tools__detectWorkflow\n2. mcp__orchestrator-tools__startWorkflow\n3. Follow the nextStep returned\n\nDirect implementation is blocked by the workflow-guard hook."}}'
+  exit 0
+fi
+
+# Get workflow details
+TOKEN=$(orch_get_token 2>/dev/null) || TOKEN=""
+if [ -z "$TOKEN" ]; then
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"[ORCHESTRATOR] Active workflow: ${WORKFLOW_ID} (could not fetch details — auth failed).\"}}"
+  exit 0
+fi
+
+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) || STATUS_RESP=""
+
+PHASE=$(orch_json_field "$STATUS_RESP" "currentPhase")
+STATUS=$(orch_json_field "$STATUS_RESP" "status")
+WF_TYPE=$(orch_json_field "$STATUS_RESP" "type")
+
+# Get next action
+NEXT_ACTION=$(orch_get_next_action "$WORKFLOW_ID" 2>/dev/null) || NEXT_ACTION=""
+HAS_ACTION=$(orch_json_field "$NEXT_ACTION" "hasAction")
+AGENT=$(orch_json_field "$NEXT_ACTION" "pendingAction.agent")
+PA_STATUS=$(orch_json_field "$NEXT_ACTION" "pendingAction.status")
+
+CONTEXT="[ORCHESTRATOR] Active workflow: ${WORKFLOW_ID}\nType: ${WF_TYPE}\nPhase: ${PHASE}\nStatus: ${STATUS}"
+
+if [ "$HAS_ACTION" = "true" ]; then
+  CONTEXT="${CONTEXT}\nNext action: invoke '${AGENT}' (${PA_STATUS})"
+fi
+
+orch_log "SESSION-ORCH: Injecting workflow context (wf=$WORKFLOW_ID phase=$PHASE)"
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"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