@chrono-meta/fh-gate 1.1.0 → 1.2.1

package/scripts/fh-goal.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+# fh-goal.sh — stop-hook-free goal runner for Codex/Claude primary workflows
+#
+# Runs a backend prompt, detects changed files, then runs fh-gate.
+# This is not Claude Code /goal parity; it is the portable quality-gated
+# execution path for environments without Stop hooks.
+
+set -euo pipefail
+
+VERSION="0.1.0"
+FH_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+_TMPDIR="${TMPDIR:-/tmp}"
+
+FH_BACKEND="${FH_BACKEND:-codex}"
+FH_TIMEOUT="${FH_TIMEOUT:-600}"
+FH_GATE_LEVEL="${FH_GATE_LEVEL:-quick}"
+FH_CALLER="${FH_CALLER:-fh-goal}"
+FH_DRY_RUN="${FH_DRY_RUN:-0}"
+FH_VERBOSE="${FH_VERBOSE:-0}"
+GOAL_PROMPT=""
+TARGET_FILES=""
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  fh-goal --prompt <task> [--files "path path"] [--gate quick|full]
+  fh-goal "task prompt"
+
+Environment:
+  FH_BACKEND=codex|claude   Backend to run the task (default: codex)
+  FH_MODEL=<model>          Backend model override
+  FH_TIMEOUT=600            Backend timeout seconds
+  FH_GATE_LEVEL=quick|full  Post-run fh-gate level
+  FH_DRY_RUN=1              Print backend prompt and planned gate only
+
+Examples:
+  FH_BACKEND=codex fh-goal --prompt "Implement X and update tests"
+  FH_BACKEND=codex fh-goal --prompt "Review docs" --files "README.md docs/codex-compat.md"
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --prompt)
+      GOAL_PROMPT="${2:-}"
+      shift 2
+      ;;
+    --files|--file|--target)
+      TARGET_FILES="${2:-}"
+      shift 2
+      ;;
+    --gate)
+      FH_GATE_LEVEL="${2:-}"
+      shift 2
+      ;;
+    --backend)
+      FH_BACKEND="${2:-}"
+      shift 2
+      ;;
+    --model)
+      FH_MODEL="${2:-}"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      if [[ -z "$GOAL_PROMPT" ]]; then
+        GOAL_PROMPT="$1"
+      else
+        GOAL_PROMPT="${GOAL_PROMPT} $1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+case "$FH_BACKEND" in
+  codex|claude) ;;
+  *)
+    echo "ERROR: FH_BACKEND must be codex or claude (got: $FH_BACKEND)" >&2
+    exit 11
+    ;;
+esac
+
+case "$FH_GATE_LEVEL" in
+  quick|full) ;;
+  *)
+    echo "ERROR: FH_GATE_LEVEL must be quick or full (got: $FH_GATE_LEVEL)" >&2
+    exit 11
+    ;;
+esac
+
+if [[ -z "$GOAL_PROMPT" ]]; then
+  echo "ERROR: missing goal prompt" >&2
+  usage >&2
+  exit 11
+fi
+
+if [[ -z "${FH_MODEL:-}" ]]; then
+  case "$FH_BACKEND" in
+    codex) FH_MODEL="gpt-5.5" ;;
+    claude) FH_MODEL="claude-sonnet-4-6" ;;
+  esac
+fi
+
+if ! command -v "$FH_BACKEND" &>/dev/null; then
+  echo "ERROR: '$FH_BACKEND' CLI not found." >&2
+  exit 10
+fi
+
+START_COMMIT="$(git -C "$FH_ROOT" rev-parse HEAD 2>/dev/null || true)"
+PROMPT_FILE=$(mktemp "${_TMPDIR}/fh_goal_prompt_XXXXXX")
+OUTPUT_FILE=$(mktemp "${_TMPDIR}/fh_goal_output_XXXXXX")
+ERR_FILE=$(mktemp "${_TMPDIR}/fh_goal_err_XXXXXX")
+cleanup() { rm -f "$PROMPT_FILE" "$OUTPUT_FILE" "$ERR_FILE"; }
+trap cleanup EXIT
+
+cat > "$PROMPT_FILE" <<PROMPT
+FH GOAL RUNNER v${VERSION}
+Backend: ${FH_BACKEND} | Model: ${FH_MODEL}
+
+Task:
+${GOAL_PROMPT}
+
+Execution rules:
+1. Work in the current repository.
+2. Make the requested changes if implementation is required.
+3. Prefer small, scoped edits.
+4. When finished, summarize changed files and verification performed.
+5. Do not claim FH governance passed; fh-goal runs fh-gate after this backend run.
+PROMPT
+
+if [[ "$FH_DRY_RUN" == "1" ]]; then
+  cat "$PROMPT_FILE"
+  echo
+  echo "Planned post-run gate: FH_BACKEND=${FH_BACKEND} scripts/fh-gate.sh \"${TARGET_FILES:-<changed files>}\" ${FH_GATE_LEVEL} ${FH_CALLER}"
+  exit 0
+fi
+
+echo "→ fh-goal v${VERSION} backend=${FH_BACKEND} model=${FH_MODEL} gate=${FH_GATE_LEVEL}" >&2
+
+_TIMEOUT_CMD=""
+if command -v gtimeout &>/dev/null; then
+  _TIMEOUT_CMD="gtimeout ${FH_TIMEOUT}"
+elif command -v timeout &>/dev/null; then
+  _TIMEOUT_CMD="timeout ${FH_TIMEOUT}"
+fi
+
+run_backend() {
+  case "$FH_BACKEND" in
+    claude) ${_TIMEOUT_CMD} claude --print --model "$FH_MODEL" ;;
+    codex) ${_TIMEOUT_CMD} codex exec -m "$FH_MODEL" - ;;
+  esac
+}
+
+if ! run_backend < "$PROMPT_FILE" > "$OUTPUT_FILE" 2>"$ERR_FILE"; then
+  echo "ERROR: ${FH_BACKEND} backend failed or timed out (${FH_TIMEOUT}s)" >&2
+  cat "$ERR_FILE" >&2
+  exit 10
+fi
+
+[[ "$FH_VERBOSE" == "1" ]] && cat "$ERR_FILE" >&2
+cat "$OUTPUT_FILE"
+
+if [[ -z "$TARGET_FILES" ]]; then
+  if [[ -n "$START_COMMIT" ]]; then
+    TARGET_FILES=$(git -C "$FH_ROOT" diff "$START_COMMIT"..HEAD --name-only 2>/dev/null | tr '\n' ' ' | xargs || true)
+  fi
+  if [[ -z "$TARGET_FILES" ]]; then
+    TARGET_FILES=$(git -C "$FH_ROOT" status --short 2>/dev/null | awk '{print $2}' | tr '\n' ' ' | xargs || true)
+  fi
+fi
+
+if [[ -z "$TARGET_FILES" ]]; then
+  echo "→ fh-goal: no changed files detected; skipping fh-gate" >&2
+  exit 0
+fi
+
+echo "→ fh-goal: running fh-gate on ${TARGET_FILES}" >&2
+FH_BACKEND="$FH_BACKEND" "$FH_ROOT/scripts/fh-gate.sh" "$TARGET_FILES" "$FH_GATE_LEVEL" "$FH_CALLER"

package/scripts/fh-run.sh

@@ -0,0 +1,269 @@
+#!/usr/bin/env bash
+# fh-run.sh — FH runtime adapter for skills and agents
+#
+# Runs a FH skill or agent document through a selectable backend.
+# This is the Codex/Claude bridge for steps that previously assumed
+# Claude Code Agent(...) dispatch or slash-command invocation.
+
+set -euo pipefail
+
+VERSION="0.1.0"
+FH_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+_TMPDIR="${TMPDIR:-/tmp}"
+
+FH_BACKEND="${FH_BACKEND:-auto}"
+FH_TIMEOUT="${FH_TIMEOUT:-180}"
+FH_DRY_RUN="${FH_DRY_RUN:-0}"
+FH_VERBOSE="${FH_VERBOSE:-0}"
+FH_RUN_PROMPT="${FH_RUN_PROMPT:-}"
+FH_RUN_MODE=""
+FH_RUN_NAME=""
+FH_RUN_UNIT=""
+TARGETS=()
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  fh-run --skill <name> [--file <path> ...] [--prompt <text>]
+  fh-run --agent <name> [--file <path> ...] [--prompt <text>]
+  fh-run --unit <path>  [--file <path> ...] [--prompt <text>]
+
+Environment:
+  FH_BACKEND=auto|codex|claude   Runtime backend (default: auto)
+  FH_MODEL=<model>               Backend model override
+  FH_TIMEOUT=180                 Backend timeout seconds
+  FH_DRY_RUN=1                   Print assembled prompt only
+
+Examples:
+  FH_BACKEND=codex fh-run --skill source-grounding-audit --file docs/foo.md
+  FH_BACKEND=codex fh-run --agent fh-commons:quench-challenger --file plugins/fh-meta/skills/foo/SKILL.md
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --skill)
+      FH_RUN_MODE="skill"
+      FH_RUN_NAME="${2:-}"
+      shift 2
+      ;;
+    --agent)
+      FH_RUN_MODE="agent"
+      FH_RUN_NAME="${2:-}"
+      shift 2
+      ;;
+    --unit)
+      FH_RUN_MODE="unit"
+      FH_RUN_UNIT="${2:-}"
+      shift 2
+      ;;
+    --file|--target)
+      TARGETS+=("${2:-}")
+      shift 2
+      ;;
+    --prompt)
+      FH_RUN_PROMPT="${2:-}"
+      shift 2
+      ;;
+    --backend)
+      FH_BACKEND="${2:-}"
+      shift 2
+      ;;
+    --model)
+      FH_MODEL="${2:-}"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    --)
+      shift
+      while [[ $# -gt 0 ]]; do
+        TARGETS+=("$1")
+        shift
+      done
+      ;;
+    *)
+      TARGETS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+case "$FH_BACKEND" in
+  auto|codex|claude) ;;
+  *)
+    echo "ERROR: FH_BACKEND must be auto, codex, or claude (got: $FH_BACKEND)" >&2
+    exit 11
+    ;;
+esac
+
+if [[ "$FH_BACKEND" == "auto" ]]; then
+  if command -v codex &>/dev/null; then
+    FH_BACKEND="codex"
+  elif command -v claude &>/dev/null; then
+    FH_BACKEND="claude"
+  else
+    echo "ERROR: no supported backend found. Install 'codex' or 'claude'." >&2
+    exit 10
+  fi
+fi
+
+if [[ -z "${FH_MODEL:-}" ]]; then
+  case "$FH_BACKEND" in
+    codex) FH_MODEL="gpt-5.5" ;;
+    claude) FH_MODEL="claude-sonnet-4-6" ;;
+  esac
+fi
+
+resolve_unit() {
+  local mode="$1"
+  local name="$2"
+  local plugin=""
+  local bare="$name"
+
+  if [[ "$name" == *:* ]]; then
+    plugin="${name%%:*}"
+    bare="${name#*:}"
+  fi
+
+  if [[ "$mode" == "unit" ]]; then
+    [[ -f "$FH_RUN_UNIT" ]] && printf "%s\n" "$FH_RUN_UNIT" && return 0
+    [[ -f "$FH_ROOT/$FH_RUN_UNIT" ]] && printf "%s\n" "$FH_ROOT/$FH_RUN_UNIT" && return 0
+    return 1
+  fi
+
+  if [[ "$mode" == "skill" ]]; then
+    local candidates=()
+    if [[ -n "$plugin" ]]; then
+      candidates+=("$FH_ROOT/plugins/$plugin/skills/$bare/SKILL.md")
+    fi
+    candidates+=(
+      "$FH_ROOT/plugins/fh-meta/skills/$bare/SKILL.md"
+      "$FH_ROOT/plugins/fh-commons/skills/$bare/SKILL.md"
+    )
+    for f in "${candidates[@]}"; do
+      [[ -f "$f" ]] && printf "%s\n" "$f" && return 0
+    done
+    return 1
+  fi
+
+  if [[ "$mode" == "agent" ]]; then
+    local candidates=()
+    if [[ -n "$plugin" ]]; then
+      candidates+=("$FH_ROOT/plugins/$plugin/agents/$bare.md")
+    fi
+    candidates+=(
+      "$FH_ROOT/.claude/agents/$bare.md"
+      "$FH_ROOT/plugins/fh-meta/agents/$bare.md"
+      "$FH_ROOT/plugins/fh-commons/agents/$bare.md"
+    )
+    for f in "${candidates[@]}"; do
+      [[ -f "$f" ]] && printf "%s\n" "$f" && return 0
+    done
+    return 1
+  fi
+
+  return 1
+}
+
+if [[ -z "$FH_RUN_MODE" ]]; then
+  echo "ERROR: choose --skill, --agent, or --unit" >&2
+  usage >&2
+  exit 11
+fi
+
+if [[ "$FH_RUN_MODE" != "unit" && -z "$FH_RUN_NAME" ]]; then
+  echo "ERROR: missing $FH_RUN_MODE name" >&2
+  exit 11
+fi
+
+UNIT_FILE="$(resolve_unit "$FH_RUN_MODE" "$FH_RUN_NAME" || true)"
+if [[ -z "$UNIT_FILE" ]]; then
+  echo "ERROR: unable to resolve FH $FH_RUN_MODE '${FH_RUN_NAME:-$FH_RUN_UNIT}'" >&2
+  exit 11
+fi
+
+PROMPT_FILE=$(mktemp "${_TMPDIR}/fh_run_prompt_XXXXXX")
+OUTPUT_FILE=$(mktemp "${_TMPDIR}/fh_run_output_XXXXXX")
+ERR_FILE=$(mktemp "${_TMPDIR}/fh_run_err_XXXXXX")
+cleanup() { rm -f "$PROMPT_FILE" "$OUTPUT_FILE" "$ERR_FILE"; }
+trap cleanup EXIT
+
+{
+  printf "FH RUNTIME ADAPTER v%s\n" "$VERSION"
+  printf "Backend: %s | Model: %s\n" "$FH_BACKEND" "$FH_MODEL"
+  printf "Unit: %s\n" "$UNIT_FILE"
+  printf "\n"
+  printf "You are executing the FH %s below. Follow its workflow and output contract.\n" "$FH_RUN_MODE"
+  printf "If the unit references Claude Code Agent(...) dispatch, treat this invocation as the isolated agent run.\n"
+  printf "If the unit references a slash command, execute the documented workflow directly.\n"
+  printf "\n"
+  if [[ -n "$FH_RUN_PROMPT" ]]; then
+    printf "User task:\n%s\n\n" "$FH_RUN_PROMPT"
+  fi
+  if [[ "${#TARGETS[@]}" -gt 0 ]]; then
+    printf "Target paths:\n"
+    for t in "${TARGETS[@]}"; do
+      printf "  - %s\n" "$t"
+    done
+    printf "\n"
+  fi
+  printf "===== FH UNIT DOCUMENT START =====\n"
+  cat "$UNIT_FILE"
+  printf "\n===== FH UNIT DOCUMENT END =====\n"
+
+  if [[ "${#TARGETS[@]}" -gt 0 ]]; then
+    for t in "${TARGETS[@]}"; do
+      local_path="$t"
+      [[ -f "$local_path" ]] || local_path="$FH_ROOT/$t"
+      if [[ -f "$local_path" ]]; then
+        printf "\n===== TARGET FILE: %s =====\n" "$t"
+        sed -n '1,2000p' "$local_path"
+        printf "\n===== END TARGET FILE: %s =====\n" "$t"
+      elif [[ -d "$local_path" ]]; then
+        printf "\n===== TARGET DIRECTORY: %s =====\n" "$t"
+        find "$local_path" -maxdepth 2 -type f | sort | sed "s#^$FH_ROOT/##"
+        printf "===== END TARGET DIRECTORY: %s =====\n" "$t"
+      else
+        printf "\nWARNING: target path not found: %s\n" "$t"
+      fi
+    done
+  fi
+} > "$PROMPT_FILE"
+
+if [[ "$FH_DRY_RUN" == "1" ]]; then
+  cat "$PROMPT_FILE"
+  exit 0
+fi
+
+if ! command -v "$FH_BACKEND" &>/dev/null; then
+  echo "ERROR: '$FH_BACKEND' CLI not found." >&2
+  exit 10
+fi
+
+echo "→ fh-run v${VERSION} backend=${FH_BACKEND} model=${FH_MODEL} unit=${FH_RUN_MODE}:${FH_RUN_NAME:-$FH_RUN_UNIT}" >&2
+
+_TIMEOUT_CMD=""
+if command -v gtimeout &>/dev/null; then
+  _TIMEOUT_CMD="gtimeout ${FH_TIMEOUT}"
+elif command -v timeout &>/dev/null; then
+  _TIMEOUT_CMD="timeout ${FH_TIMEOUT}"
+fi
+
+run_backend() {
+  case "$FH_BACKEND" in
+    claude) ${_TIMEOUT_CMD} claude --print --model "$FH_MODEL" ;;
+    codex) ${_TIMEOUT_CMD} codex exec -m "$FH_MODEL" - ;;
+  esac
+}
+
+if ! run_backend < "$PROMPT_FILE" > "$OUTPUT_FILE" 2>"$ERR_FILE"; then
+  echo "ERROR: ${FH_BACKEND} backend failed or timed out (${FH_TIMEOUT}s)" >&2
+  cat "$ERR_FILE" >&2
+  exit 10
+fi
+
+[[ "$FH_VERBOSE" == "1" ]] && cat "$ERR_FILE" >&2
+cat "$OUTPUT_FILE"