forgedock 1.2.0 → 1.3.0

package/scripts/check-spec-markers.sh

@@ -0,0 +1,273 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-spec-markers.sh — Validate FORGE: annotation markers in commands/**/*.md and
+#                          detect unsubstituted {PLACEHOLDER} tokens in CI workflow files.
+#
+# Command specs contain two classes of spec-as-code marker defects:
+#
+#   1. Non-registry FORGE: markers — a typo or invented marker (e.g. FORGE:INVESTIAGOR,
+#      FORGE:NOTES) in a command spec will cause agents to look for a comment annotation
+#      that is never emitted, silently breaking pipeline state detection. (Ref: forge#633)
+#
+#   2. Unsubstituted {PLACEHOLDER} tokens in CI workflow YAML — a template variable like
+#      {GH_REPO} or {NUMBER} left unsubstituted in a workflow inline script means every
+#      CI run executes a malformed command that fails silently or produces wrong output.
+#      (Ref: forge#318; note: {PLACEHOLDER} tokens in commands/*.md are intentional
+#       spec notation and are NOT flagged by this check.)
+#
+# This script:
+#   1. Scans all *.md files in commands/ for <!-- FORGE:XXXX --> annotations.
+#   2. Validates XXXX against the known registry (see MARKER_REGISTRY below).
+#   3. Scans .github/workflows/*.yml for unsubstituted {PLACEHOLDER} tokens in run: blocks.
+#
+# Registry: covers all reserved types from packages/protocol/src/types.js
+# (RESERVED_TYPE_NAMES) plus all operational/pipeline markers used throughout the
+# ForgeDock spec corpus. Compound markers (FORGE:TYPE-SUBTYPE, FORGE:TYPE:SUBTYPE)
+# are validated by their primary type (the part before the first - or :).
+# Update the registry when adding new marker types.
+#
+# Allowlist: add <!-- allowlist:check-spec-markers --> on the same line as the marker
+# to suppress that specific hit.
+#
+# Usage:
+#   check-spec-markers.sh [<commands_dir> [<repo_root>]]
+#     commands_dir: path to the commands/ directory (default: ./commands)
+#     repo_root:    path to repo root for workflow scanning (default: .)
+#
+# Exit codes:
+#   0  no violations found
+#   1  one or more violations found (listed to stderr)
+#   2  usage / dependency error (commands_dir not found)
+#
+# <!-- Added: forge#1609 -->
+
+set -euo pipefail
+
+COMMANDS_DIR="${1:-./commands}"
+REPO_ROOT="${2:-.}"
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  sed -n '2,/^set -/p' "$0" | grep '^#' | sed 's/^# *//'
+  exit 0
+fi
+
+if [ ! -d "$COMMANDS_DIR" ]; then
+  echo "ERROR: commands directory not found: $COMMANDS_DIR" >&2
+  echo "Usage: $0 [<commands_dir> [<repo_root>]]" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# FORGE: marker registry
+#
+# Sources:
+#   - packages/protocol/src/types.js — RESERVED_TYPE_NAMES (reserved lifecycle types)
+#   - Operational pipeline markers used in commands/**/*.md specs
+#
+# Compound markers (FORGE:REVIEW-AGENT:material-change, FORGE:PHASE:COMPLETE) are
+# validated by their PRIMARY type only (the part before the first - or : after FORGE:).
+# Add entries for each primary type; sub-types are unrestricted.
+#
+# Update this list when new marker types are added to the protocol or spec corpus.
+# Keep sorted alphabetically for readability.
+# ---------------------------------------------------------------------------
+MARKER_REGISTRY="
+  ACCEPTANCE_GATE
+  ADR_EXTRACTED
+  ANCESTRY_FAILED
+  ARCHITECT
+  AUDIT
+  AUTOPILOT_CYCLE
+  AUTOPILOT_GATE
+  AUTOPILOT_IMPACT
+  BATCHABLE
+  BATCH_ID
+  BATCH_MEMBERS
+  BENCH_SCORECARD
+  BLOCKED_ON_HUMAN_MERGE
+  BUILDER
+  CALIBRATION_CHECK
+  CARD
+  CHECKPOINT
+  CLAIM
+  CLAIM_RELEASED
+  CONTEXT
+  CONTRACT
+  COORD_ISSUE
+  CRITIQUE
+  DECISION_RECORD
+  DECOMPOSED
+  DESIGN
+  DISPATCHER
+  DOSSIER_UPDATED
+  FAST_PATH
+  FINDING_SOURCE
+  FIX_CI
+  GATE_FAILED
+  GATE_FAILURE
+  GATE_PASS
+  HEARTBEAT
+  INDEP_VERIFY
+  INDEP_VERIFY_FAIL
+  INDEP_VERIFY_PASS
+  INVESTIGATOR
+  JSONL_PARSER_UTIL
+  KNOWLEDGE_GIST
+  LEARNED
+  LEARNED_RULES
+  LEDGER_INDEXED
+  MEMORY_INDEX
+  MEMORY_INDEXED
+  MILESTONE_INDEX
+  MODEL_TIER_NOTE
+  ORPHAN_ESCALATED
+  ORPHAN_RECOVERED
+  PATTERN
+  PHASE
+  PHASE_COMPLETE
+  PLAN_DAG
+  PRIOR_DECISIONS
+  PRIOR_GIST
+  PROTOCOL_SOURCE
+  PUSH_BLOCKED
+  PUSH_BLOCKED_EMPTY_BRANCH
+  PUSH_FAILED
+  REMEDIATION
+  REVIEW
+  REVIEWER
+  REVIEW_ROUTE
+  REVIEW_STARTED
+  SECURITY_AUDIT
+  SIGNAL_RESOLVED
+  SIGNAL_UNRESOLVED
+  SPAWN_POLICY
+  SPEC_DOCTOR_COMPLETE
+  SPEC_LOADED
+  STALL_DETECTED
+  STATE
+  SYNTHESIS_BRIEF
+  TEST_GATE
+  TRAIN_CANDIDATE
+  TRAJECTORY
+  UNBLOCKED
+  USER_FEEDBACK
+"
+
+# Build an alternation pattern for registry lookup.
+# Words separated by | for use with grep -E: ^(WORD1|WORD2|...)$
+REGISTRY_NAMES=$(echo "$MARKER_REGISTRY" | tr -s '[:space:]' '\n' | grep -vE '^\s*$' | sort -u | tr '\n' '|' | sed 's/|$//')
+REGISTRY_PATTERN="^(${REGISTRY_NAMES})$"
+
+# Allowlist token — a line containing this token is exempt
+ALLOWLIST_TOKEN='allowlist:check-spec-markers'
+
+VIOLATIONS=0
+
+# ---------------------------------------------------------------------------
+# Pass 1: Validate FORGE: markers in commands/**/*.md
+# ---------------------------------------------------------------------------
+
+find_md_files() {
+  find "$COMMANDS_DIR" -name '*.md' | sort
+}
+
+while IFS= read -r file; do
+  [ -f "$file" ] || continue
+
+  # Extract all lines containing <!-- FORGE:XXXX --> annotations with their line numbers.
+  while IFS= read -r markerline; do
+    [ -z "$markerline" ] && continue
+    lineno="${markerline%%:*}"
+    content="${markerline#*:}"
+
+    # Skip allowlisted lines
+    if echo "$content" | grep -qF "$ALLOWLIST_TOKEN"; then
+      continue
+    fi
+
+    # Skip markers that are inside code spans (backtick-quoted) — those are docs examples
+    # Heuristic: if the FORGE:TYPE appears between backticks on the same line, skip it
+    # We check for backtick on either side of the FORGE: marker
+    if echo "$content" | grep -qE "\`[^\`]*FORGE:[A-Z_]"; then
+      continue
+    fi
+
+    # Extract the full marker string after FORGE: — everything up to a space, -->, or end
+    # This captures compound markers like REVIEW-AGENT:material-change
+    full_marker=$(echo "$content" | grep -oE 'FORGE:[A-Z][A-Z0-9_:-]*' | head -1 | sed 's/^FORGE://')
+
+    [ -z "$full_marker" ] && continue
+
+    # Extract PRIMARY type: part before the first - or : separator
+    primary_type=$(echo "$full_marker" | sed 's/[-:].*//')
+
+    # Validate primary type against registry
+    if ! echo "$primary_type" | grep -qE "$REGISTRY_PATTERN"; then
+      echo "HIGH | $file:$lineno | unknown FORGE: marker 'FORGE:${full_marker}' (primary type '${primary_type}') — not in registry" >&2
+      VIOLATIONS=$((VIOLATIONS + 1))
+    fi
+  done < <(grep -nE '<!--[[:space:]]*FORGE:[A-Z]' "$file" 2>/dev/null || true)
+
+done < <(find_md_files)
+
+# ---------------------------------------------------------------------------
+# Pass 2: Detect unsubstituted {PLACEHOLDER} in .github/workflows/*.yml
+#
+# In workflow YAML, {PLACEHOLDER} tokens (not bash ${VAR} expansions) indicate
+# a template variable that should have been resolved before committing.
+#
+# Bash ${VAR} references are excluded — we strip ${...} patterns before scanning.
+# Pattern: {UPPERCASE_3+} — e.g. {GH_REPO}, {NUMBER}, {WORKTREE_PATH}
+# ---------------------------------------------------------------------------
+
+WORKFLOWS_DIR="${REPO_ROOT}/.github/workflows"
+
+if [ -d "$WORKFLOWS_DIR" ]; then
+  # Pattern: { followed by uppercase letter, then 2+ uppercase/digit/underscore, then }
+  # Preceded by something other than $ (to exclude bash ${VAR} expansions)
+  PLACEHOLDER_PATTERN='\{[A-Z][A-Z0-9_]{2,}\}'
+
+  while IFS= read -r wf_file; do
+    [ -f "$wf_file" ] || continue
+
+    LINENO=0
+
+    while IFS= read -r line; do
+      LINENO=$((LINENO + 1))
+
+      # Skip allowlisted lines
+      if echo "$line" | grep -qF "$ALLOWLIST_TOKEN"; then
+        continue
+      fi
+
+      # Skip comment lines
+      if echo "$line" | grep -qE '^[[:space:]]*#'; then
+        continue
+      fi
+
+      # Strip bash ${VAR} and $VAR patterns before checking for template placeholders
+      # so that ELAPSED in "${ELAPSED}s" doesn't false-positive as {ELAPSED}
+      stripped=$(echo "$line" | sed 's/\${\([^}]*\)}/BASH_VAR/g; s/\$[A-Za-z_][A-Za-z0-9_]*/BASH_VAR/g')
+
+      if echo "$stripped" | grep -qE "$PLACEHOLDER_PATTERN"; then
+        placeholder=$(echo "$stripped" | grep -oE "$PLACEHOLDER_PATTERN" | head -1)
+        echo "HIGH | $wf_file:$LINENO | unsubstituted placeholder '$placeholder' in workflow" >&2
+        VIOLATIONS=$((VIOLATIONS + 1))
+      fi
+    done < "$wf_file"
+  done < <(find "$WORKFLOWS_DIR" -name '*.yml' | sort)
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+
+if [ "$VIOLATIONS" -gt 0 ]; then
+  echo "check-spec-markers: $VIOLATIONS violation(s) found. See stderr for details." >&2
+  exit 1
+fi
+
+echo "OK: No marker or placeholder violations found"
+exit 0

package/scripts/classify-lane.sh

@@ -1,14 +1,19 @@
 #!/usr/bin/env bash
 # classify-lane.sh — Deterministic lane routing from issue milestone
 #
-# Usage: classify-lane.sh <issue_number> [-R <owner/repo>]
+# Usage: classify-lane.sh <issue_number> [-R <owner/repo>] [--json]
 #   issue_number: GitHub issue number (required)
 #   -R <owner/repo>: GitHub repository (optional, defaults to current repo)
+#   --json: emit structured JSON object instead of plain lane string (optional)
 #
-# Output: lane string written to stdout
+# Output: lane string written to stdout (default)
 #   staging              — issue has no milestone (fast lane)
 #   milestone/{slug}     — issue has a milestone (feature lane, slug = lowercased, spaces→hyphens, git-invalid chars stripped)
 #
+# Output: JSON object when --json flag is passed
+#   {"lane":"staging","branch":"staging","source":"fast-lane","milestone":null}
+#   {"lane":"milestone/{slug}","branch":"milestone/{slug}","source":"feature-lane","milestone":"{title}","slug":"{slug}"}
+#
 # Exit codes: 0 = success, 1 = error (invalid issue, gh auth failure, branch missing, etc.)
 #
 # Branch existence validation:
@@ -23,11 +28,12 @@ set -euo pipefail
 
 ISSUE_NUMBER="${1:-}"
 GH_REPO_ARGS=()
+JSON_OUTPUT=false
 
-# Parse arguments: issue number + optional -R flag
+# Parse arguments: issue number + optional -R flag + optional --json flag
 if [ -z "$ISSUE_NUMBER" ]; then
   echo "ERROR: issue number is required" >&2
-  echo "Usage: classify-lane.sh <issue_number> [-R <owner/repo>]" >&2
+  echo "Usage: classify-lane.sh <issue_number> [-R <owner/repo>] [--json]" >&2
   exit 1
 fi
 
@@ -37,7 +43,7 @@ while [ $# -gt 0 ]; do
     -R)
       if [ $# -lt 2 ]; then
         echo "ERROR: -R requires a value <owner/repo>" >&2
-        echo "Usage: classify-lane.sh <issue_number> [-R <owner/repo>]" >&2
+        echo "Usage: classify-lane.sh <issue_number> [-R <owner/repo>] [--json]" >&2
         exit 1
       fi
       if ! [[ "$2" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; then
@@ -47,6 +53,10 @@ while [ $# -gt 0 ]; do
       GH_REPO_ARGS=(-R "$2")
       shift 2
       ;;
+    --json)
+      JSON_OUTPUT=true
+      shift
+      ;;
     *)
       echo "ERROR: unknown argument: $1" >&2
       exit 1
@@ -94,7 +104,12 @@ if [ -z "$MILESTONE_TITLE" ]; then
     echo "       Run: git push origin HEAD:$STAGING_BRANCH  (from the default branch)" >&2
     exit 1
   fi
-  echo "$STAGING_BRANCH"
+  if [ "$JSON_OUTPUT" = "true" ]; then
+    printf '{"lane":"%s","branch":"%s","source":"fast-lane","milestone":null}\n' \
+      "$STAGING_BRANCH" "$STAGING_BRANCH"
+  else
+    echo "$STAGING_BRANCH"
+  fi
 else
   # Slugify: lowercase, spaces → hyphens, strip git-invalid chars, collapse multiple hyphens,
   # strip leading/trailing hyphens.
@@ -134,5 +149,12 @@ else
     exit 1
   fi
 
-  echo "$LANE"
+  if [ "$JSON_OUTPUT" = "true" ]; then
+    # Escape double quotes in milestone title for safe JSON embedding.
+    MILESTONE_ESCAPED="${MILESTONE_TITLE//\"/\\\"}"
+    printf '{"lane":"%s","branch":"%s","source":"feature-lane","milestone":"%s","slug":"%s"}\n' \
+      "$LANE" "$LANE" "$MILESTONE_ESCAPED" "$SLUG"
+  else
+    echo "$LANE"
+  fi
 fi

package/scripts/forge-run.sh

@@ -0,0 +1,322 @@
+#!/usr/bin/env bash
+# forge-run.sh — Universal shell-script entry point for non-Claude agents
+#
+# Usage: forge-run.sh <command> <issue_number> [-R <owner/repo>]
+#   command:      Pipeline command to run (currently: work-on)
+#   issue_number: GitHub issue number (required)
+#   -R <owner/repo>: GitHub repository (optional, defaults to current repo)
+#
+# Description:
+#   GitHub-state-aware phase router. Reads workflow:* labels and FORGE annotation
+#   comments on the given issue to determine the current pipeline phase, then emits
+#   structured JSON events to stdout describing phase state and transitions.
+#
+#   This script does NOT invoke LLM agents — it reports what phase the pipeline is
+#   in and what the next action should be. It is designed to be called by any
+#   agent runtime that can execute bash (Aider /run, Cursor terminal, CI runners,
+#   OpenCode shell) to get deterministic routing information without re-implementing
+#   the phase detection logic.
+#
+# JSON Event Schema:
+#   Each event is a single JSON object on its own line (newline-delimited JSON):
+#
+#   Phase detection:
+#   {"event":"phase_detected","command":"work-on","issue":N,"phase":"<phase>","ts":"<ISO8601>"}
+#
+#   Phase detail:
+#   {"event":"phase_detail","phase":"<phase>","lane":"<lane>","branch":"<branch>","labels":["<label>",...]}
+#
+#   Action required:
+#   {"event":"action_required","phase":"<phase>","action":"<description>","ts":"<ISO8601>"}
+#
+#   Terminal state:
+#   {"event":"terminal","phase":"<phase>","label":"<terminal-label>","issue":N,"ts":"<ISO8601>"}
+#
+#   Error:
+#   {"event":"error","code":"<error_code>","message":"<message>","ts":"<ISO8601>"}
+#
+# Phase values (work-on command):
+#   no-comments          — No investigation started; next: Phase 1 (investigate)
+#   investigating        — Investigation in progress (partial comment, no INVESTIGATION:COMPLETE)
+#   ready-to-build       — Investigation complete; next: Phase 3 (build)
+#   building             — Build in progress (no FORGE:BUILDER comment yet)
+#   awaiting-pr          — Builder complete, no PR; next: Phase 4 (create PR)
+#   in-review            — PR exists, review in progress; next: Phase 5 (auto-review)
+#   merged               — Terminal: workflow:merged label set
+#   invalid              — Terminal: workflow:invalid label set
+#   decomposed           — Terminal: workflow:decomposed label set (sub-issues spawned)
+#   needs-human          — Terminal: needs-human label set
+#
+# Exit codes: 0 = success, 1 = error (invalid args, gh auth failure, etc.)
+#
+# <!-- Added: forge#965 -->
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+# ISO 8601 timestamp (UTC)
+ts() { date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "1970-01-01T00:00:00Z"; }
+
+# Emit a JSON event to stdout (one object per line — NDJSON)
+emit() {
+  local json="$1"
+  printf '%s\n' "$json"
+}
+
+# Emit an error event and exit 1
+die() {
+  local code="$1"
+  local message="$2"
+  local ts_val
+  ts_val=$(ts)
+  # Escape double quotes in message for JSON embedding
+  message="${message//\"/\\\"}"
+  emit "{\"event\":\"error\",\"code\":\"${code}\",\"message\":\"${message}\",\"ts\":\"${ts_val}\"}"
+  exit 1
+}
+
+# JSON-escape a string (double-quote characters only — sufficient for ASCII label/branch values)
+json_str() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  printf '%s' "$s"
+}
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+COMMAND="${1:-}"
+ISSUE_NUMBER="${2:-}"
+GH_REPO_ARGS=()
+
+if [ -z "$COMMAND" ]; then
+  die "MISSING_COMMAND" "command is required. Usage: forge-run.sh <command> <issue_number> [-R <owner/repo>]"
+fi
+
+if [ -z "$ISSUE_NUMBER" ]; then
+  die "MISSING_ISSUE" "issue_number is required. Usage: forge-run.sh <command> <issue_number> [-R <owner/repo>]"
+fi
+
+# Validate command
+case "$COMMAND" in
+  work-on) ;;
+  *)
+    die "UNKNOWN_COMMAND" "unknown command: ${COMMAND}. Supported: work-on"
+    ;;
+esac
+
+# Validate issue number is numeric
+if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
+  die "INVALID_ISSUE" "issue_number must be numeric, got: ${ISSUE_NUMBER}"
+fi
+
+# Parse remaining flags
+shift 2
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -R)
+      if [ $# -lt 2 ]; then
+        die "MISSING_REPO" "-R requires a value <owner/repo>. Usage: forge-run.sh <command> <issue_number> [-R <owner/repo>]"
+      fi
+      if ! [[ "$2" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; then
+        die "INVALID_REPO" "-R value must be owner/repo format, got: ${2}"
+      fi
+      GH_REPO_ARGS=(-R "$2")
+      shift 2
+      ;;
+    *)
+      die "UNKNOWN_FLAG" "unknown argument: ${1}. Usage: forge-run.sh <command> <issue_number> [-R <owner/repo>]"
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Locate scripts directory (where classify-lane.sh lives alongside this script)
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLASSIFY_LANE="${SCRIPT_DIR}/classify-lane.sh"
+
+if [ ! -x "$CLASSIFY_LANE" ]; then
+  die "MISSING_SCRIPT" "classify-lane.sh not found or not executable at: ${CLASSIFY_LANE}"
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 1: Read issue state from GitHub
+# ---------------------------------------------------------------------------
+
+# Fetch issue: state, labels
+GH_STDERR_TMP=$(mktemp)
+ISSUE_JSON=$(gh issue view "$ISSUE_NUMBER" "${GH_REPO_ARGS[@]}" \
+  --json number,state,labels,title \
+  2>"$GH_STDERR_TMP") || {
+  MSG=$(cat "$GH_STDERR_TMP")
+  rm -f "$GH_STDERR_TMP"
+  die "GH_FETCH_FAILED" "failed to fetch issue #${ISSUE_NUMBER}: ${MSG}"
+}
+rm -f "$GH_STDERR_TMP"
+
+# Extract state and labels
+ISSUE_STATE=$(printf '%s' "$ISSUE_JSON" | jq -r '.state')
+LABELS_JSON=$(printf '%s' "$ISSUE_JSON" | jq -c '[.labels[].name]')
+ISSUE_TITLE=$(printf '%s' "$ISSUE_JSON" | jq -r '.title')
+
+# Check if issue is closed
+if [ "$ISSUE_STATE" = "CLOSED" ]; then
+  ts_val=$(ts)
+  emit "{\"event\":\"terminal\",\"phase\":\"closed\",\"label\":\"closed\",\"issue\":${ISSUE_NUMBER},\"ts\":\"${ts_val}\"}"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 2: Detect terminal labels
+# ---------------------------------------------------------------------------
+
+TERMINAL_LABEL=""
+for label in "workflow:merged" "workflow:invalid" "workflow:decomposed" "needs-human"; do
+  if printf '%s' "$LABELS_JSON" | jq -e --arg l "$label" 'contains([$l])' > /dev/null 2>&1; then
+    TERMINAL_LABEL="$label"
+    break
+  fi
+done
+
+if [ -n "$TERMINAL_LABEL" ]; then
+  ts_val=$(ts)
+  emit "{\"event\":\"terminal\",\"phase\":\"${TERMINAL_LABEL}\",\"label\":\"$(json_str "${TERMINAL_LABEL}")\",\"issue\":${ISSUE_NUMBER},\"ts\":\"${ts_val}\"}"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 3: Read FORGE annotation comments to determine pipeline phase
+# ---------------------------------------------------------------------------
+
+# gh issue view with --json comments is the reliable approach: it accepts the -R flag
+# via GH_REPO_ARGS and handles both default-repo and explicit-repo cases.
+# gh api repos/{owner}/{repo}/... would need GH_REPO env var for -R override — avoided here.
+GH_STDERR_TMP=$(mktemp)
+COMMENTS_JSON=$(gh issue view "$ISSUE_NUMBER" "${GH_REPO_ARGS[@]}" \
+  --json comments --jq '[.comments[] | {id: .id, body: .body}]' \
+  2>"$GH_STDERR_TMP") || {
+  MSG=$(cat "$GH_STDERR_TMP")
+  rm -f "$GH_STDERR_TMP"
+  die "GH_COMMENTS_FAILED" "failed to fetch comments for issue #${ISSUE_NUMBER}: ${MSG}"
+}
+rm -f "$GH_STDERR_TMP" 2>/dev/null || true
+
+if [ -z "$COMMENTS_JSON" ]; then
+  COMMENTS_JSON="[]"
+fi
+
+# Detect annotation presence
+has_annotation() {
+  local marker="$1"
+  printf '%s' "$COMMENTS_JSON" | jq -e --arg m "$marker" 'any(.[]; .body | contains($m))' > /dev/null 2>&1
+}
+
+# Detect complete annotation (has both the annotation tag AND its completion sentinel)
+is_annotation_complete() {
+  local open_tag="$1"
+  local sentinel="$2"
+  printf '%s' "$COMMENTS_JSON" | jq -e \
+    --arg o "$open_tag" --arg s "$sentinel" \
+    'any(.[]; (.body | contains($o)) and (.body | contains($s)))' > /dev/null 2>&1
+}
+
+INVESTIGATOR_COMPLETE=false
+BUILDER_COMPLETE=false
+BUILDER_PRESENT=false
+REVIEW_STARTED=false
+
+if is_annotation_complete "FORGE:INVESTIGATOR" "INVESTIGATION:COMPLETE"; then
+  INVESTIGATOR_COMPLETE=true
+fi
+if has_annotation "FORGE:BUILDER"; then
+  BUILDER_PRESENT=true
+fi
+if is_annotation_complete "FORGE:BUILDER" "FORGE:BUILDER:COMPLETE"; then
+  BUILDER_COMPLETE=true
+fi
+if has_annotation "FORGE:REVIEW_STARTED"; then
+  REVIEW_STARTED=true
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 4: Determine current workflow phase from labels + annotations
+# ---------------------------------------------------------------------------
+
+# Read current workflow labels
+WORKFLOW_LABEL=""
+for label in "workflow:in-review" "workflow:building" "workflow:ready-to-build" "workflow:investigating"; do
+  if printf '%s' "$LABELS_JSON" | jq -e --arg l "$label" 'contains([$l])' > /dev/null 2>&1; then
+    WORKFLOW_LABEL="$label"
+    break
+  fi
+done
+
+# Phase detection logic (matches work-on.md Phase 0B: "Determine resume point")
+PHASE="no-comments"
+ACTION=""
+
+if [ "$REVIEW_STARTED" = "true" ]; then
+  PHASE="in-review"
+  ACTION="Review in progress — /review-pr handles merge. Check PR state."
+elif [ "$BUILDER_COMPLETE" = "true" ] && [ "$WORKFLOW_LABEL" != "workflow:in-review" ]; then
+  PHASE="awaiting-pr"
+  ACTION="Builder complete. Create PR targeting the classified lane branch."
+elif [ "$BUILDER_PRESENT" = "true" ] && [ "$BUILDER_COMPLETE" = "false" ]; then
+  PHASE="building"
+  ACTION="Builder comment present but incomplete. Resume build from FORGE:BUILDER comment."
+elif [ "$WORKFLOW_LABEL" = "workflow:building" ]; then
+  PHASE="building"
+  ACTION="Build phase active. No FORGE:BUILDER comment yet — build not complete."
+elif [ "$INVESTIGATOR_COMPLETE" = "true" ] || [ "$WORKFLOW_LABEL" = "workflow:ready-to-build" ]; then
+  PHASE="ready-to-build"
+  ACTION="Investigation complete. Invoke /work-on ${ISSUE_NUMBER} to continue to build phase."
+elif has_annotation "FORGE:INVESTIGATOR" && [ "$INVESTIGATOR_COMPLETE" = "false" ]; then
+  PHASE="investigating"
+  ACTION="Investigation comment present but incomplete (no INVESTIGATION:COMPLETE sentinel). Delete partial comment and restart investigation."
+elif [ "$WORKFLOW_LABEL" = "workflow:investigating" ]; then
+  PHASE="investigating"
+  ACTION="Investigation in progress. No FORGE:INVESTIGATOR comment yet."
+else
+  PHASE="no-comments"
+  ACTION="No pipeline activity detected. Invoke /work-on ${ISSUE_NUMBER} to start investigation."
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 5: Classify lane (for informational output in phase_detail event)
+# ---------------------------------------------------------------------------
+
+LANE=""
+BRANCH=""
+LANE_JSON=""
+if LANE_JSON=$("$CLASSIFY_LANE" "$ISSUE_NUMBER" "${GH_REPO_ARGS[@]}" --json 2>/dev/null); then
+  LANE=$(printf '%s' "$LANE_JSON" | jq -r '.lane // empty')
+  BRANCH=$(printf '%s' "$LANE_JSON" | jq -r '.branch // empty')
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 6: Emit events
+# ---------------------------------------------------------------------------
+
+ts_val=$(ts)
+
+# Event 1: phase_detected
+emit "{\"event\":\"phase_detected\",\"command\":\"$(json_str "${COMMAND}")\",\"issue\":${ISSUE_NUMBER},\"phase\":\"$(json_str "${PHASE}")\",\"ts\":\"${ts_val}\"}"
+
+# Event 2: phase_detail
+LABELS_STR=$(printf '%s' "$LABELS_JSON")
+emit "{\"event\":\"phase_detail\",\"phase\":\"$(json_str "${PHASE}")\",\"lane\":\"$(json_str "${LANE}")\",\"branch\":\"$(json_str "${BRANCH}")\",\"labels\":${LABELS_STR}}"
+
+# Event 3: action_required (only for non-terminal active phases)
+if [ -n "$ACTION" ]; then
+  ts_val=$(ts)
+  ACTION_ESCAPED="${ACTION//\"/\\\"}"
+  emit "{\"event\":\"action_required\",\"phase\":\"$(json_str "${PHASE}")\",\"action\":\"${ACTION_ESCAPED}\",\"ts\":\"${ts_val}\"}"
+fi
+
+exit 0