oh-my-customcodex 0.1.0

package/templates/.claude/hooks/scripts/session-autofix-prompt.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Session Auto-Fix Prompt — UserPromptSubmit prompt hook (#838)
+# One-shot: reads SessionStart findings and injects into first user prompt.
+# Protocol: stdout text -> injected into model context
+
+FIXES_FILE="/tmp/.codex-session-fixes-${PPID}"
+
+# Only fire if findings exist (one-shot)
+if [ ! -f "$FIXES_FILE" ]; then
+  exit 0
+fi
+
+# Read and remove (one-shot: prevent repeated injection)
+FINDINGS=$(cat "$FIXES_FILE")
+rm -f "$FIXES_FILE"
+
+ISSUE_COUNT=$(echo "$FINDINGS" | jq -r '.issue_count // 0' 2>/dev/null)
+
+if [ "$ISSUE_COUNT" -gt 0 ]; then
+  echo "[Session Auto-Fix] Previous session left ${ISSUE_COUNT} issue(s):"
+  echo "$FINDINGS" | jq -r '.issues[]' 2>/dev/null | while IFS= read -r issue; do
+    type="${issue%%:*}"
+    msg="${issue#*:}"
+    echo "  - [${type}] ${msg}"
+  done
+  FIX_COUNT=$(echo "$FINDINGS" | jq -r '.fix_count // 0' 2>/dev/null)
+  if [ "$FIX_COUNT" -gt 0 ]; then
+    echo "Auto-fixed: ${FIX_COUNT} item(s)."
+  fi
+  echo ""
+  echo "Consider addressing remaining issues before starting new work."
+fi
+
+exit 0

package/templates/.claude/hooks/scripts/session-autofix.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# Session Auto-Fix — SessionStart command hook (#838)
+# Detects previous session issues: uncommitted changes, template sync,
+# AGENTS.md counts, gitignore blocking, wiki staleness, broken skill refs.
+# Protocol: stdin JSON -> stdout pass-through, exit 0 always
+# Time budget: <3s
+
+input=$(cat)
+FIXES_FILE="/tmp/.codex-session-fixes-${PPID}"
+LOG_DIR=".codex/outputs/session-fixes"
+ISSUES=()
+FIXES=()
+ISSUE_COUNT=0
+FIX_COUNT=0
+
+# Utility: add issue
+add_issue() {
+  ISSUES+=("$1")
+  ISSUE_COUNT=$((ISSUE_COUNT + 1))
+}
+
+add_fix() {
+  FIXES+=("$1")
+  FIX_COUNT=$((FIX_COUNT + 1))
+}
+
+# ─── Check 1: Uncommitted changes ───
+uncommitted=$(git status --porcelain 2>/dev/null | head -20)
+if [ -n "$uncommitted" ]; then
+  count=$(echo "$uncommitted" | wc -l | tr -d ' ')
+  add_issue "uncommitted:${count} uncommitted changes detected"
+fi
+
+# ─── Check 2: Template sync (lightweight count comparison) ───
+if [ -d "templates/.codex/agents" ] && [ -d ".codex/agents" ]; then
+  src_agents=$(ls .codex/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
+  tpl_agents=$(ls templates/.codex/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$src_agents" != "$tpl_agents" ]; then
+    add_issue "template-sync:Agent count mismatch (source:${src_agents} vs template:${tpl_agents})"
+  fi
+
+  src_skills=$(find .codex/skills -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
+  tpl_skills=$(find templates/.codex/skills -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$src_skills" != "$tpl_skills" ]; then
+    add_issue "template-sync:Skill count mismatch (source:${src_skills} vs template:${tpl_skills})"
+  fi
+
+  src_rules=$(ls .codex/rules/*.md 2>/dev/null | wc -l | tr -d ' ')
+  tpl_rules=$(ls templates/.codex/rules/*.md 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$src_rules" != "$tpl_rules" ]; then
+    add_issue "template-sync:Rule count mismatch (source:${src_rules} vs template:${tpl_rules})"
+  fi
+
+  src_guides=$(find guides -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
+  tpl_guides=$(find templates/guides -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$src_guides" != "$tpl_guides" ]; then
+    add_issue "template-sync:Guide count mismatch (source:${src_guides} vs template:${tpl_guides})"
+  fi
+fi
+
+# ─── Check 3: AGENTS.md count validation ───
+if [ -f "AGENTS.md" ]; then
+  actual_agents=$(ls .codex/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
+  doc_agents=$(grep -oE '[0-9]+ 파일\)' AGENTS.md | head -1 | grep -oE '[0-9]+' || echo "0")
+  if [ "$actual_agents" != "$doc_agents" ] && [ "$doc_agents" != "0" ]; then
+    add_issue "claude-md:Agent count in AGENTS.md ($doc_agents) != actual ($actual_agents)"
+  fi
+fi
+
+# ─── Check 4: Gitignore blocking new .codex/ files ───
+new_files=$(git ls-files --others --exclude-standard .codex/ 2>/dev/null | head -5)
+ignored_new=""
+if [ -n "$new_files" ]; then
+  while IFS= read -r f; do
+    if git check-ignore --quiet "$f" 2>/dev/null; then
+      ignored_new="${ignored_new}${f}\n"
+    fi
+  done <<< "$new_files"
+fi
+if [ -n "$ignored_new" ]; then
+  add_issue "gitignore:New .codex/ files blocked by .gitignore"
+fi
+
+# ─── Check 5: Wiki staleness (lightweight) ───
+if [ -d "wiki" ]; then
+  missing_wiki=0
+  for agent in .codex/agents/*.md; do
+    name=$(basename "$agent" .md)
+    if [ ! -f "wiki/agents/${name}.md" ]; then
+      missing_wiki=$((missing_wiki + 1))
+    fi
+  done
+  if [ "$missing_wiki" -gt 0 ]; then
+    add_issue "wiki-stale:${missing_wiki} agent(s) missing wiki pages"
+  fi
+fi
+
+# ─── Check 6: Broken skill references (lightweight) ───
+broken_refs=0
+for agent in .codex/agents/*.md; do
+  skills_line=$(grep -E '^skills:' "$agent" 2>/dev/null | head -1)
+  if [ -n "$skills_line" ]; then
+    skills=$(echo "$skills_line" | sed 's/skills: *\[//;s/\]//;s/,/ /g;s/"//g' | tr -d "'")
+    for skill in $skills; do
+      skill=$(echo "$skill" | tr -d ' ')
+      if [ -n "$skill" ] && [ ! -f ".codex/skills/${skill}/SKILL.md" ]; then
+        broken_refs=$((broken_refs + 1))
+      fi
+    done
+  fi
+done
+if [ "$broken_refs" -gt 0 ]; then
+  add_issue "broken-refs:${broken_refs} broken skill reference(s) in agent frontmatter"
+fi
+
+# ─── Report ───
+if [ "$ISSUE_COUNT" -gt 0 ]; then
+  echo "[Session Auto-Fix] ${ISSUE_COUNT} issue(s) detected:" >&2
+  for issue in "${ISSUES[@]}"; do
+    type="${issue%%:*}"
+    msg="${issue#*:}"
+    echo "  ⚠ [${type}] ${msg}" >&2
+  done
+  if [ "$FIX_COUNT" -gt 0 ]; then
+    echo "[Session Auto-Fix] Auto-fixed ${FIX_COUNT} item(s):" >&2
+    for fix in "${FIXES[@]}"; do
+      echo "  ✓ ${fix}" >&2
+    done
+  fi
+fi
+
+# ─── Write findings for prompt hook ───
+if command -v jq >/dev/null 2>&1; then
+  issues_json=$(printf '%s\n' "${ISSUES[@]}" | jq -R . | jq -s .)
+  fixes_json=$(printf '%s\n' "${FIXES[@]}" | jq -R . | jq -s .)
+  echo "{\"issue_count\":${ISSUE_COUNT},\"fix_count\":${FIX_COUNT},\"issues\":${issues_json},\"fixes\":${fixes_json}}" > "$FIXES_FILE"
+else
+  echo "{\"issue_count\":${ISSUE_COUNT},\"fix_count\":${FIX_COUNT}}" > "$FIXES_FILE"
+fi
+
+# ─── JSONL log ───
+mkdir -p "$LOG_DIR" 2>/dev/null
+echo "{\"date\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"issue_count\":${ISSUE_COUNT},\"fix_count\":${FIX_COUNT}}" >> "${LOG_DIR}/$(date +%Y-%m-%d).jsonl" 2>/dev/null
+
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/session-env-check.sh

@@ -0,0 +1,254 @@
+#!/bin/bash
+set -euo pipefail
+
+# Session Environment Check Hook
+# Trigger: SessionStart
+# Purpose: Check availability of codex CLI and Agent Teams, report via stderr
+# Protocol: stdin JSON -> stdout pass-through, exit 0 always
+
+input=$(cat)
+
+echo "" >&2
+echo "--- [Session Environment Check] ---" >&2
+
+# Check codex CLI availability
+CODEX_STATUS="unavailable"
+if command -v codex >/dev/null 2>&1; then
+  if [ -n "${OPENAI_API_KEY:-}" ]; then
+    CODEX_STATUS="available (authenticated)"
+  else
+    CODEX_STATUS="installed but OPENAI_API_KEY not set"
+  fi
+fi
+
+# Check Gemini CLI availability
+GEMINI_STATUS="unavailable"
+if command -v gemini >/dev/null 2>&1; then
+  if [ -n "${GOOGLE_API_KEY:-}" ] || [ -n "${GEMINI_API_KEY:-}" ]; then
+    GEMINI_STATUS="available (authenticated)"
+  else
+    GEMINI_STATUS="installed (gcloud auth may be available)"
+  fi
+fi
+
+# Check RTK CLI availability
+RTK_STATUS="unavailable"
+if command -v rtk >/dev/null 2>&1; then
+  RTK_STATUS="available"
+fi
+
+# Check Agent Teams availability
+AGENT_TEAMS_STATUS="disabled"
+if [ "${OMCODEX_AGENT_TEAMS:-0}" = "1" ]; then
+  AGENT_TEAMS_STATUS="enabled"
+fi
+
+# Claude Code version detection
+CLAUDE_VERSION="unknown"
+if command -v claude >/dev/null 2>&1; then
+  CLAUDE_VERSION=$(claude --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
+fi
+
+# Version compatibility check
+MIN_COMPAT_VERSION="2.1.63"
+COMPAT_STATUS="unknown"
+if [ "$CLAUDE_VERSION" != "unknown" ]; then
+  if printf '%s\n' "$MIN_COMPAT_VERSION" "$CLAUDE_VERSION" | sort -V | head -1 | grep -q "^${MIN_COMPAT_VERSION}$"; then
+    COMPAT_STATUS="compatible"
+  else
+    COMPAT_STATUS="outdated"
+  fi
+fi
+
+# v2.1.88+ features notice
+if [ "$CLAUDE_VERSION" != "unknown" ]; then
+  if printf '%s\n' "2.1.88" "$CLAUDE_VERSION" | sort -V | head -1 | grep -q "^2\.1\.88$"; then
+    if [ -z "${CLAUDE_CODE_NO_FLICKER:-}" ]; then
+      echo "  [v2.1.88] Tip: CLAUDE_CODE_NO_FLICKER=1 for flicker-free rendering" >&2
+    fi
+  fi
+fi
+
+# Git workflow reminder
+CURRENT_BRANCH="unknown"
+if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+fi
+
+# Drift Detection: compare git HEAD between sessions
+DRIFT_STATUS="not-git"
+if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  SESSION_STATE_DIR="$HOME/.codex/session-state"
+  mkdir -p "$SESSION_STATE_DIR"
+
+  PROJECT_HASH=$(echo "$(pwd)" | md5 2>/dev/null || echo "$(pwd)" | md5sum 2>/dev/null | cut -c1-8)
+  # md5 on macOS outputs "MD5 (stdin) = <hash>", extract just the hash
+  PROJECT_HASH=$(echo "$PROJECT_HASH" | grep -oE '[a-f0-9]{32}' | cut -c1-8)
+  STATE_FILE="${SESSION_STATE_DIR}/${PROJECT_HASH}.last-head"
+
+  CURRENT_HEAD=$(git log -1 --format="%H" 2>/dev/null || echo "")
+
+  if [ -n "$CURRENT_HEAD" ]; then
+    if [ -f "$STATE_FILE" ]; then
+      LAST_HEAD=$(cat "$STATE_FILE" 2>/dev/null || echo "")
+      if [ -n "$LAST_HEAD" ] && [ "$LAST_HEAD" != "$CURRENT_HEAD" ]; then
+        DRIFT_STATUS="drifted"
+        NEW_COMMITS=$(git rev-list --count "${LAST_HEAD}..${CURRENT_HEAD}" 2>/dev/null || echo "?")
+        CHANGED_FILES=$(git diff --name-only "${LAST_HEAD}..${CURRENT_HEAD}" 2>/dev/null | head -10)
+      else
+        DRIFT_STATUS="clean"
+      fi
+    else
+      DRIFT_STATUS="first-session"
+    fi
+
+    # Save current HEAD for next session
+    echo "$CURRENT_HEAD" > "$STATE_FILE"
+  fi
+fi
+
+# --- CI Status Check ---
+# Check last CI run status if gh CLI is available
+if command -v gh &>/dev/null; then
+  ci_status=$(gh run list --limit 1 --json conclusion -q '.[0].conclusion' 2>/dev/null || echo "unknown")
+  ci_name=$(gh run list --limit 1 --json name -q '.[0].name' 2>/dev/null || echo "unknown")
+  if [ "$ci_status" = "failure" ]; then
+    echo "[Session] ⚠ WARNING: Last CI run FAILED (${ci_name}) — check before pushing" >&2
+  elif [ "$ci_status" = "success" ]; then
+    echo "[Session] CI: last run passed (${ci_name})" >&2
+  elif [ "$ci_status" != "unknown" ]; then
+    echo "[Session] CI: last run status: ${ci_status} (${ci_name})" >&2
+  fi
+fi
+
+# Update availability check (local cache only — no network calls)
+OMCUSTOM_UPDATE_STATUS="unknown"
+INSTALLED_VERSION=""
+CACHED_LATEST=""
+
+# Read installed version from .omcustomrc.json
+if [ -f ".omcustomrc.json" ]; then
+  INSTALLED_VERSION=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' .omcustomrc.json 2>/dev/null | head -1 | grep -o '"[^"]*"$' | tr -d '"')
+fi
+
+# Read cached latest version (no network call)
+CACHE_FILE="$HOME/.oh-my-customcodex/self-update-cache.json"
+if [ ! -f "$CACHE_FILE" ] && [ -f "$HOME/.oh-my-customcode/self-update-cache.json" ]; then
+  CACHE_FILE="$HOME/.oh-my-customcode/self-update-cache.json"
+fi
+if [ -f "$CACHE_FILE" ]; then
+  CACHED_LATEST=$(grep -o '"latestVersion"[[:space:]]*:[[:space:]]*"[^"]*"' "$CACHE_FILE" 2>/dev/null | grep -o '"[^"]*"$' | tr -d '"' || true)
+  if [ -z "$CACHED_LATEST" ]; then
+    CACHED_LATEST=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$CACHE_FILE" 2>/dev/null | head -1 | grep -o '"[^"]*"$' | tr -d '"' || true)
+  fi
+fi
+
+if [ -n "$INSTALLED_VERSION" ] && [ -n "$CACHED_LATEST" ]; then
+  if [ "$INSTALLED_VERSION" != "$CACHED_LATEST" ]; then
+    # Simple version comparison using sort -V
+    OLDER=$(printf '%s\n' "$INSTALLED_VERSION" "$CACHED_LATEST" | sort -V | head -1)
+    if [ "$OLDER" = "$INSTALLED_VERSION" ] && [ "$INSTALLED_VERSION" != "$CACHED_LATEST" ]; then
+      OMCUSTOM_UPDATE_STATUS="available"
+    else
+      OMCUSTOM_UPDATE_STATUS="up-to-date"
+    fi
+  else
+    OMCUSTOM_UPDATE_STATUS="up-to-date"
+  fi
+elif [ -n "$INSTALLED_VERSION" ]; then
+  OMCUSTOM_UPDATE_STATUS="no-cache"
+else
+  OMCUSTOM_UPDATE_STATUS="not-installed"
+fi
+
+# Write status to file for other hooks to reference
+STATUS_FILE="/tmp/.codex-env-status-${PPID}"
+cat > "$STATUS_FILE" << ENVEOF
+codex=${CODEX_STATUS}
+gemini=${GEMINI_STATUS}
+rtk=${RTK_STATUS}
+agent_teams=${AGENT_TEAMS_STATUS}
+git_branch=${CURRENT_BRANCH}
+claude_version=${CLAUDE_VERSION}
+compat_status=${COMPAT_STATUS}
+drift_status=${DRIFT_STATUS}
+omcodex_update=${OMCUSTOM_UPDATE_STATUS}
+ENVEOF
+
+# Report to stderr (visible in conversation)
+echo "  codex CLI: ${CODEX_STATUS}" >&2
+echo "  gemini CLI: ${GEMINI_STATUS}" >&2
+echo "  RTK CLI:      ${RTK_STATUS}" >&2
+echo "  Agent Teams: ${AGENT_TEAMS_STATUS}" >&2
+echo "  Claude Code: v${CLAUDE_VERSION} (${COMPAT_STATUS})" >&2
+if [ "$COMPAT_STATUS" = "outdated" ]; then
+  echo "  ⚠ Claude Code v${MIN_COMPAT_VERSION}+ recommended for full hook compatibility" >&2
+fi
+echo "" >&2
+echo "  [Git Workflow Reminder]" >&2
+echo "  Current branch: ${CURRENT_BRANCH}" >&2
+if [ "$CURRENT_BRANCH" = "develop" ] || [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
+  echo "  ⚠ You are on a protected branch!" >&2
+  echo "  ⚠ Create a feature branch before making changes:" >&2
+  echo "    git checkout -b feat/your-feature develop" >&2
+else
+  echo "  ✓ Feature branch detected" >&2
+fi
+echo "  Rules: feature branch → commit → push → PR → merge" >&2
+echo "" >&2
+
+# Drift Detection report
+echo "  [Drift Detection]" >&2
+case "$DRIFT_STATUS" in
+  drifted)
+    echo "  ⚠ Repository changed since last session" >&2
+    echo "  New commits: ${NEW_COMMITS}" >&2
+    if [ -n "${CHANGED_FILES:-}" ]; then
+      echo "  Changed files:" >&2
+      echo "$CHANGED_FILES" | while IFS= read -r file; do
+        echo "    - ${file}" >&2
+      done
+    fi
+    ;;
+  clean)
+    echo "  ✓ No changes since last session" >&2
+    ;;
+  first-session)
+    echo "  First session for this project" >&2
+    ;;
+  not-git)
+    echo "  Skipped (not a git repository)" >&2
+    ;;
+esac
+echo "" >&2
+echo "  [Lockfile Drift]" >&2
+echo "  Note: file-level lockfile drift (template hash changes) is checked via 'omcodex doctor'" >&2
+echo "  Run 'omcodex doctor' to detect modified/removed template files since install." >&2
+echo "------------------------------------" >&2
+
+# SessionEnd hooks timeout (v2.1.74+)
+if [ -z "${CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS:-}" ]; then
+  echo "[SessionEnv] ⚠ CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS not set (default: 1500ms)" >&2
+  echo "[SessionEnv] Recommend: export CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=10000" >&2
+fi
+
+# Update Check report
+echo "" >&2
+echo "  [Update Check]" >&2
+if [ -n "$INSTALLED_VERSION" ] && [ -n "$CACHED_LATEST" ]; then
+  if [ "$OMCUSTOM_UPDATE_STATUS" = "available" ]; then
+    echo "  ⚡ oh-my-customcodex v${CACHED_LATEST} available (current: v${INSTALLED_VERSION})" >&2
+    echo "     Run 'omcodex update' to apply" >&2
+  else
+    echo "  ✓ oh-my-customcodex is up to date (v${INSTALLED_VERSION})" >&2
+  fi
+elif [ -n "$INSTALLED_VERSION" ]; then
+  echo "  ℹ oh-my-customcodex v${INSTALLED_VERSION} (run 'omcodex doctor --updates' to check for updates)" >&2
+else
+  echo "  ℹ oh-my-customcodex not detected in this project" >&2
+fi
+echo "------------------------------------" >&2
+
+# Pass through
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/skill-extractor-analyzer.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# skill-extractor-analyzer.sh — Stop hook for skill candidate detection
+# Advisory-only: exit 0 always. Emits stderr message if candidates found.
+
+set -euo pipefail
+
+# Pass through stdin (Stop hook protocol)
+input=$(cat)
+
+OUTCOMES_FILE="/tmp/.codex-task-outcomes-${PPID}"
+PROPOSALS_FILE="/tmp/.codex-skill-proposals-${PPID}"
+
+# Early exit if no outcomes
+if [ ! -f "$OUTCOMES_FILE" ] || [ ! -s "$OUTCOMES_FILE" ]; then
+  echo "$input"
+  exit 0
+fi
+
+# Count qualifying patterns (3+ successes with 80%+ rate)
+# Group by agent_type+skill, count successes
+CANDIDATES=0
+
+if command -v jq &>/dev/null; then
+  # Parse JSONL and group by agent_type+skill
+  CANDIDATES=$(cat "$OUTCOMES_FILE" | \
+    jq -s '
+      group_by(.agent_type + "|" + (.skill // "none"))
+      | map({
+          key: .[0].agent_type + "|" + (.[0].skill // "none"),
+          total: length,
+          successes: [.[] | select(.outcome == "success")] | length
+        })
+      | map(select(.successes >= 3 and (.successes / .total) >= 0.8))
+      | length
+    ' 2>/dev/null || echo "0")
+fi
+
+if [ "$CANDIDATES" -gt 0 ] 2>/dev/null; then
+  echo "[skill-extractor] ${CANDIDATES} skill candidate(s) detected from session outcomes" >&2
+  echo "[skill-extractor] Run /skill-extractor to review and create" >&2
+
+  # Save proposal count for Stop prompt hook to pick up
+  echo "{\"candidates\": $CANDIDATES, \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" > "$PROPOSALS_FILE" || true
+fi
+
+# CRITICAL: Always pass through input and exit 0
+# This hook MUST NEVER block session termination
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/stage-blocker.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Stage-blocking hook: blocks Write/Edit in non-implement stages
+# Mutual Exclusion: This hook is mutually exclusive with autonomous mode (R010).
+# When /tmp/.codex-dev-stage exists, autonomous mode cannot be activated.
+# When /tmp/.codex-autonomous-$PPID exists, /structured-dev-cycle should not be started.
+# See: MUST-orchestrator-coordination.md "Autonomous Execution Mode" section.
+if [ -f /tmp/.codex-dev-stage ]; then
+  stage=$(cat /tmp/.codex-dev-stage | tr -d '[:space:]')
+  if [ -z "$stage" ]; then exit 0; fi
+  case "$stage" in
+    plan|verify-plan|verify-impl|compound|done)
+      echo "⛔ BLOCKED: Write/Edit disabled in '$stage' stage. Only allowed during 'implement' stage. Use 'echo implement > /tmp/.codex-dev-stage' to transition."
+      exit 2
+      ;;
+  esac
+fi

package/templates/.claude/hooks/scripts/stale-todo-scanner.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+set -euo pipefail
+
+# Stale TODO Scanner Hook
+# Trigger: SessionStart
+# Purpose: Scan TODO.md files for staleness and pending items, report via stderr
+# Protocol: stdin JSON -> stdout pass-through, exit 0 always
+# Note: Zero network calls — local file scanning only
+
+input=$(cat)
+
+TODO_FILES=("TODO.md" ".codex/TODO.md" ".claude/TODO.md")
+NOW=$(date +%s)
+FOUND_ANY=false
+FOUND_STALE=false
+PRINTED_HEADER=false
+
+print_header() {
+  if [ "$PRINTED_HEADER" = false ]; then
+    echo "" >&2
+    echo "--- [TODO Health Check] ---" >&2
+    PRINTED_HEADER=true
+  fi
+}
+
+for TODO_FILE in "${TODO_FILES[@]}"; do
+  if [ ! -f "$TODO_FILE" ]; then
+    continue
+  fi
+
+  FOUND_ANY=true
+  print_header
+
+  # Parse "Last updated: YYYY-MM-DD" header
+  LAST_UPDATED_LINE=$(grep -m1 "> Last updated:" "$TODO_FILE" 2>/dev/null || echo "")
+  DATE_STR=$(echo "$LAST_UPDATED_LINE" | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' | head -1 || echo "")
+
+  # Count pending items (grep -c exits 1 when no matches on some systems — normalize to 0)
+  PENDING_COUNT=$(grep -c "^- \[ \]" "$TODO_FILE" 2>/dev/null) || PENDING_COUNT=0
+
+  if [ -z "$DATE_STR" ]; then
+    echo "  ${TODO_FILE}: no 'Last updated' header found" >&2
+    echo "    Pending items: ${PENDING_COUNT}" >&2
+    continue
+  fi
+
+  # Cross-platform date parsing: try GNU date first, fallback to BSD date
+  FILE_EPOCH=""
+  if date -d "$DATE_STR" +%s >/dev/null 2>&1; then
+    # GNU date (Linux)
+    FILE_EPOCH=$(date -d "$DATE_STR" +%s)
+  elif date -j -f "%Y-%m-%d" "$DATE_STR" +%s >/dev/null 2>&1; then
+    # BSD date (macOS)
+    FILE_EPOCH=$(date -j -f "%Y-%m-%d" "$DATE_STR" +%s)
+  else
+    echo "  ${TODO_FILE}: could not parse date '${DATE_STR}'" >&2
+    echo "    Pending items: ${PENDING_COUNT}" >&2
+    continue
+  fi
+
+  DAYS_OLD=$(( (NOW - FILE_EPOCH) / 86400 ))
+
+  if [ "$DAYS_OLD" -gt 30 ]; then
+    STATUS="⚠⚠ critical — stale >30d"
+    FOUND_STALE=true
+  elif [ "$DAYS_OLD" -gt 7 ]; then
+    STATUS="⚠ stale >7d"
+    FOUND_STALE=true
+  else
+    STATUS="up to date"
+  fi
+
+  echo "  ${TODO_FILE}: last updated ${DAYS_OLD} days ago (${STATUS})" >&2
+  echo "    Pending items: ${PENDING_COUNT}" >&2
+done
+
+if [ "$FOUND_ANY" = false ] || [ "$FOUND_STALE" = false ]; then
+  if [ "$FOUND_ANY" = false ]; then
+    : # No TODO files found — skip silently
+  else
+    echo "  ✓ All TODO files are up to date" >&2
+  fi
+fi
+
+if [ "$PRINTED_HEADER" = true ]; then
+  echo "------------------------------------" >&2
+fi
+
+# Pass through
+echo "$input"
+exit 0