@jamie-tam/forge 6.0.0

package/hooks/config/gate-requirements.json

@@ -0,0 +1,79 @@
+{
+  "_comment": "Maps manifest gate names to required skill and agent invocations. Used by gate-enforcer.sh to verify prerequisites before allowing gate-passed: true. Agents are dispatched by skills internally — listed here so the enforcer can verify they were invoked via telemetry.",
+  "requirements": {
+    "skill": "discover-requirements",
+    "agent": null
+  },
+  "codebase-analysis": {
+    "skill": "discover-codebase-analysis",
+    "agent": "architect"
+  },
+  "brainstorm": {
+    "skill": "plan-brainstorm",
+    "agent": "critic"
+  },
+  "architecture": {
+    "skill": "plan-architecture",
+    "agents": ["architect", "critic"]
+  },
+  "task-decompose": {
+    "skill": "plan-task-decompose",
+    "agent": "spec-reviewer"
+  },
+  "design-system": {
+    "skill": "plan-design-system",
+    "agent": null
+  },
+  "scaffold": {
+    "skill": "build-scaffold",
+    "agent": null
+  },
+  "concept": {
+    "skill": "concept-slides",
+    "agent": "concept-designer"
+  },
+  "wireframe": {
+    "skill": "build-wireframe",
+    "agent": "wireframer"
+  },
+  "prototype": {
+    "skill": "build-prototype",
+    "agent": "prototype-builder"
+  },
+  "iterate": {
+    "skill": "iterate-prototype",
+    "agent": "prototype-reviewer"
+  },
+  "codify": {
+    "skill": "harden",
+    "agent": "prototype-codifier"
+  },
+  "runtime-reach": {
+    "skill": "support-runtime-reachability",
+    "agent": null
+  },
+  "wiki-lint": {
+    "skill": "support-wiki-lint",
+    "agent": null
+  },
+  "code-review": {
+    "skill": "quality-code-review",
+    "agent": "craft-reviewer"
+  },
+  "code-review-final": {
+    "skill": "quality-code-review",
+    "agent": "code-reviewer"
+  },
+  "test-plan": {
+    "skill": "quality-test-plan",
+    "agent": "critic"
+  },
+  "test-execution": {
+    "skill": "quality-test-execution",
+    "agent": "e2e-runner"
+  },
+  "uiux-review": {
+    "skill": "quality-uiux",
+    "agent": null
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,143 @@
+{
+  "description": "Guardrails for safe git operations and context preservation",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(git *--no-verify*)",
+            "command": "echo 'BLOCKED: --no-verify is not allowed. Fix the underlying issue instead of skipping hooks.' >&2; exit 2"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(git push*)",
+            "command": "echo 'Reminder: Review your changes before pushing. Have tests passed? Is the branch up to date?' >&2; exit 0"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scripts/gate-enforcer.sh\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scripts/gate-enforcer.sh\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scripts/gate-enforcer.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(git commit*)",
+            "command": "echo 'Reminder: Run the test suite to verify this commit does not break anything.' >&2; exit 0"
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scripts/telemetry.sh\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scripts/telemetry.sh\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scripts/wiki-lint.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scripts/wiki-lint.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scripts/wiki-lint.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scripts/session-start.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/scripts/pre-compact.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/scripts/analyze-telemetry.sh

@@ -0,0 +1,114 @@
+#!/bin/bash
+# Analyze telemetry from a harness run.
+# Usage: bash analyze-telemetry.sh [command-name]
+# Example: bash analyze-telemetry.sh greenfield
+#
+# Reads .forge/state/telemetry.jsonl and reports:
+# 1. Which skills were called (and how many times)
+# 2. Which agents were dispatched
+# 3. If a command name is given, compares against expected skills
+
+set -euo pipefail
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+TELEMETRY_FILE="$PROJECT_ROOT/.forge/state/telemetry.jsonl"
+
+if [ ! -f "$TELEMETRY_FILE" ]; then
+  echo "No telemetry file found at $TELEMETRY_FILE"
+  echo "Run a command first to generate telemetry."
+  exit 1
+fi
+
+COMMAND="${1:-}"
+
+echo "=== TELEMETRY ANALYSIS ==="
+echo ""
+
+echo "## Skills Called"
+jq -r 'select(.type == "skill") | .name' "$TELEMETRY_FILE" | sort | uniq -c | sort -rn
+echo ""
+
+echo "## Agents Dispatched"
+jq -r 'select(.type == "agent") | "\(.name) — \(.description)"' "$TELEMETRY_FILE" | sort | uniq -c | sort -rn
+echo ""
+
+echo "## Timeline"
+jq -r '"\(.timestamp) [\(.type)] \(.name)"' "$TELEMETRY_FILE"
+echo ""
+
+# Expected skills per command
+if [ -n "$COMMAND" ]; then
+  echo "## Compliance Check: /$COMMAND"
+  echo ""
+
+  case "$COMMAND" in
+    greenfield)
+      # discover-requirements is conditional (substantive existing requirements docs only).
+      # plan-design-system is conditional (skipped for backend-only/CLI projects without a frontend).
+      # quality-uiux is conditional (frontend projects only).
+      EXPECTED_SKILLS="discover-requirements concept-slides build-wireframe plan-design-system build-prototype iterate-prototype harden build-tdd quality-code-review quality-test-plan quality-test-execution quality-uiux build-pr-workflow support-gotcha"
+      EXPECTED_AGENTS=""
+      ;;
+    feature)
+      # plan-design-system is conditional (backend-only features skip; frontend features run).
+      # quality-uiux is conditional (frontend features only); deliver-deploy/onboarding conditional (non-internal features).
+      EXPECTED_SKILLS="discover-codebase-analysis concept-slides build-wireframe plan-design-system build-prototype iterate-prototype harden build-pr-workflow build-tdd quality-code-review quality-test-plan quality-test-execution quality-uiux deliver-deploy deliver-onboarding support-gotcha"
+      EXPECTED_AGENTS=""
+      ;;
+    bugfix)
+      EXPECTED_SKILLS="support-debug build-tdd quality-code-review build-pr-workflow support-gotcha"
+      EXPECTED_AGENTS=""
+      ;;
+    hotfix)
+      EXPECTED_SKILLS="support-debug build-tdd quality-test-execution quality-code-review deliver-deploy support-gotcha"
+      EXPECTED_AGENTS=""
+      ;;
+    refactor)
+      EXPECTED_SKILLS="discover-codebase-analysis plan-brainstorm plan-task-decompose build-tdd quality-code-review quality-test-execution build-pr-workflow support-gotcha"
+      EXPECTED_AGENTS=""
+      ;;
+    *)
+      echo "Unknown command: $COMMAND"
+      exit 1
+      ;;
+  esac
+
+  ACTUAL_SKILLS=$(jq -r 'select(.type == "skill") | .name' "$TELEMETRY_FILE" | sort -u)
+  ACTUAL_AGENTS=$(jq -r 'select(.type == "agent") | .name' "$TELEMETRY_FILE" | sort -u)
+
+  echo "### Skills"
+  for skill in $EXPECTED_SKILLS; do
+    if echo "$ACTUAL_SKILLS" | grep -q "^${skill}$"; then
+      echo "  ✓ $skill"
+    else
+      echo "  ✗ $skill — MISSING"
+    fi
+  done
+
+  echo ""
+  echo "### Agents"
+  if [ -n "$EXPECTED_AGENTS" ]; then
+    for agent in $EXPECTED_AGENTS; do
+      if echo "$ACTUAL_AGENTS" | grep -q "^${agent}$"; then
+        echo "  ✓ $agent"
+      else
+        echo "  ✗ $agent — MISSING"
+      fi
+    done
+  else
+    echo "  (none expected for /$COMMAND)"
+  fi
+
+  echo ""
+
+  # Unexpected calls
+  UNEXPECTED=""
+  for skill in $ACTUAL_SKILLS; do
+    if ! echo "$EXPECTED_SKILLS" | tr ' ' '\n' | grep -q "^${skill}$"; then
+      UNEXPECTED="$UNEXPECTED $skill"
+    fi
+  done
+  if [ -n "$UNEXPECTED" ]; then
+    echo "### Unexpected skills called:$UNEXPECTED"
+  fi
+fi

package/hooks/scripts/gate-enforcer.sh

@@ -0,0 +1,164 @@
+#!/bin/bash
+# PreToolUse hook: blocks manifest gate-passed updates when required
+# skill/agent was not invoked. Reads gate-requirements.json for mapping
+# and telemetry.jsonl for invocation history.
+#
+# Only fires on Edit/Write targeting manifest.yaml with gate-passed: true.
+# Returns { continue: false } to block, { continue: true } to allow.
+#
+# Gate matching handles three YAML cases:
+#   1. Inline:  requirements: { status: complete, gate-passed: true }
+#   2. Block:   requirements:\n  gate-passed: true  (name on different line)
+#   3. Narrow edit: old_string="gate-passed: false" new_string="gate-passed: true"
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=""
+CONTENT=""
+
+# Extract file path and content based on tool type
+if [ "$TOOL_NAME" = "Edit" ]; then
+  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // ""')
+elif [ "$TOOL_NAME" = "Write" ]; then
+  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')
+elif [ "$TOOL_NAME" = "MultiEdit" ]; then
+  # MultiEdit targets one file with multiple edits. file_path is at the top
+  # level (same as Edit); the new content lives in tool_input.edits[*].new_string.
+  # Concatenate all new_string fields so gate detection scans every proposed
+  # change in the batch — otherwise a multi-edit could slip a `gate-passed: true`
+  # write past the enforcement gate that single-Edit catches.
+  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+  CONTENT=$(echo "$INPUT" | jq -r '[.tool_input.edits[]?.new_string] | join("\n")')
+else
+  echo '{"continue":true}'
+  exit 0
+fi
+
+# Only check manifest.yaml edits
+if [[ "$FILE_PATH" != *manifest.yaml ]]; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+# Inline YAML on a gate key is a bypass surface — `code-review-final: { status:
+# passed, gate-passed: true }` sneaks past the block-form line-anchored regex
+# below because `gate-passed:` is mid-line. Reject inline form on any gate key
+# explicitly so authors must use block form (where enforcement actually works).
+# A gate key followed immediately by `{` indicates flow-mapping syntax; pair
+# that with `gate-passed: true` anywhere on the same line and we treat it as a
+# hard block.
+INLINE_BYPASS_LINE=$(echo "$CONTENT" | grep -nE "^[[:space:]]*[a-z][a-z0-9-]*:[[:space:]]*\{[^}]*gate-passed:[[:space:]]*true" || true)
+if [ -n "$INLINE_BYPASS_LINE" ]; then
+  echo "GATE ENFORCEMENT: inline-form YAML for a gate-passed assignment is not allowed (line: ${INLINE_BYPASS_LINE}). Use block form so the enforcer can validate prerequisites:" >&2
+  echo "  code-review-final:" >&2
+  echo "    status: complete" >&2
+  echo "    gate-passed: true" >&2
+  echo "{\"continue\":false,\"reason\":\"GATE ENFORCEMENT: inline-form YAML on a gate-passed assignment is not allowed; use block form.\"}"
+  exit 2
+fi
+
+# Only check edits that set gate-passed: true.
+# Anchor to actual YAML-key syntax: line must start (after optional whitespace) with
+# the literal key "gate-passed:" followed by optional whitespace and "true". This
+# prevents false-positives on prose/comments that mention the phrase — e.g. a
+# manifest comment explaining when the field becomes true.
+if ! echo "$CONTENT" | grep -qE "^[[:space:]]*gate-passed:[[:space:]]*true([[:space:]]|$|,|})"; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+# Locate config and telemetry
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONFIG="$SCRIPT_DIR/../config/gate-requirements.json"
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+TELEMETRY="$PROJECT_ROOT/.forge/state/telemetry.jsonl"
+
+if [ ! -f "$CONFIG" ]; then
+  echo '{"continue":true}' # No config = no enforcement
+  exit 0
+fi
+
+# Check each gate being passed against requirements
+BLOCKED_REASONS=""
+
+for GATE in $(jq -r 'keys[] | select(. != "_comment")' "$CONFIG"); do
+  GATE_MATCH=false
+
+  # Method 1: Gate name appears anywhere in the edit content
+  # Handles inline YAML and block YAML (gate name on different line from gate-passed)
+  if echo "$CONTENT" | grep -q "$GATE"; then
+    GATE_MATCH=true
+  # Method 2 (Edit/MultiEdit): Gate name is near the edit location in the actual file
+  # Handles narrow edits (e.g., changing just "gate-passed: false" to "true")
+  elif [ "$TOOL_NAME" = "Edit" ] && [ -f "$FILE_PATH" ]; then
+    OLD_STRING=$(echo "$INPUT" | jq -r '.tool_input.old_string // ""')
+    if [ -n "$OLD_STRING" ]; then
+      FIRST_LINE=$(echo "$OLD_STRING" | head -1)
+      if [ -n "$FIRST_LINE" ] && grep -B 10 -F "$FIRST_LINE" "$FILE_PATH" 2>/dev/null | grep -q "[[:space:]]*${GATE}[[:space:]]*:"; then
+        GATE_MATCH=true
+      fi
+    fi
+  elif [ "$TOOL_NAME" = "MultiEdit" ] && [ -f "$FILE_PATH" ]; then
+    # For each edit's old_string, check the first line and see whether the
+    # gate name appears in nearby file context. Emit one first-line per edit
+    # (jq splits on records, not embedded newlines) so multi-line old_strings
+    # still get probed by their starting line.
+    EDIT_COUNT=$(echo "$INPUT" | jq '.tool_input.edits | length // 0')
+    for ((i = 0; i < EDIT_COUNT; i++)); do
+      OLD_STRING=$(echo "$INPUT" | jq -r ".tool_input.edits[$i].old_string // \"\"")
+      [ -z "$OLD_STRING" ] && continue
+      FIRST_LINE=$(echo "$OLD_STRING" | head -1)
+      if [ -n "$FIRST_LINE" ] && grep -B 10 -F "$FIRST_LINE" "$FILE_PATH" 2>/dev/null | grep -q "[[:space:]]*${GATE}[[:space:]]*:"; then
+        GATE_MATCH=true
+        break
+      fi
+    done
+  fi
+
+  if [ "$GATE_MATCH" = true ]; then
+    REQUIRED_SKILL=$(jq -r ".\"$GATE\".skill // empty" "$CONFIG")
+
+    # Resolve required agents: agents array first, then single agent field
+    REQUIRED_AGENTS=$(jq -r "if .\"$GATE\".agents then .\"$GATE\".agents[] else .\"$GATE\".agent // empty end" "$CONFIG" 2>/dev/null)
+
+    # Check skill invocation in telemetry
+    if [ -n "$REQUIRED_SKILL" ]; then
+      if [ ! -f "$TELEMETRY" ] || ! grep -q "\"name\":\"$REQUIRED_SKILL\"" "$TELEMETRY"; then
+        BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires skill '$REQUIRED_SKILL' (not found in telemetry). "
+      fi
+    fi
+
+    # Check agent dispatch in telemetry
+    for AGENT in $REQUIRED_AGENTS; do
+      if [ -n "$AGENT" ] && [ "$AGENT" != "null" ]; then
+        if [ ! -f "$TELEMETRY" ] || ! grep -q "\"name\":\"$AGENT\"" "$TELEMETRY"; then
+          BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires agent '$AGENT' (not found in telemetry). "
+        fi
+      fi
+    done
+  fi
+done
+
+if [ -n "$BLOCKED_REASONS" ]; then
+  # The hook's JSON `reason` field is currently swallowed by Claude Code (only
+  # the generic "Execution stopped by hook" line is surfaced to the user).
+  # Echo the reason to stderr so it actually reaches the user — stderr from
+  # PreToolUse hooks IS surfaced in the tool-error output.
+  echo "GATE ENFORCEMENT: ${BLOCKED_REASONS}Load the required skill/agent before marking the gate as passed." >&2
+
+  # Escape for JSON (still emit reason in case a future harness surfaces it).
+  ESCAPED=$(echo "$BLOCKED_REASONS" | sed 's/"/\\"/g')
+  echo "{\"continue\":false,\"reason\":\"GATE ENFORCEMENT: ${ESCAPED}Load the required skill/agent before marking the gate as passed.\"}"
+  # PreToolUse hooks only block when exit code is 2; exit 0 would allow the
+  # tool call despite the JSON block decision. Keep the JSON emit above for
+  # user-facing context.
+  exit 2
+fi
+
+echo '{"continue":true}'
+exit 0

package/hooks/scripts/pre-compact.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# Pre-compact hook: Save critical state before context window compression.
+# This ensures the agent can recover its working context after compaction.
+#
+# Writes to .forge/state/notepad.md which survives context compression
+# because it's re-read by the agent when it detects context loss.
+#
+# Scans `.forge/work/*/` (typed subdirs) for the single in-progress work item.
+# Skips `escalated`/`completed` manifests (terminal states). Uses `{type}/{name}`
+# as the canonical work identifier because names can collide across types.
+
+set -euo pipefail
+
+# Find project root (look for .forge/ or .git/)
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+STATE_DIR="$PROJECT_ROOT/.forge/state"
+
+# Create state directory if needed
+mkdir -p "$STATE_DIR"
+
+# Ensure .forge/state/ is gitignored
+if [ -f "$PROJECT_ROOT/.gitignore" ]; then
+    if ! grep -q '.forge/state' "$PROJECT_ROOT/.gitignore" 2>/dev/null; then
+        echo '.forge/state/' >> "$PROJECT_ROOT/.gitignore"
+    fi
+fi
+
+# Find active work item (status: in-progress), scanning typed subdirs
+NOTEPAD="$STATE_DIR/notepad.md"
+ACTIVE_WORK=""      # Canonical identifier: {type}/{name}
+MANIFEST_PATH=""
+
+if [ -d "$PROJECT_ROOT/.forge/work" ]; then
+    for manifest in "$PROJECT_ROOT/.forge/work"/*/*/manifest.yaml; do
+        if [ -f "$manifest" ] && grep -q 'status: in-progress' "$manifest" 2>/dev/null; then
+            WORK_NAME="$(basename "$(dirname "$manifest")")"
+            WORK_TYPE="$(basename "$(dirname "$(dirname "$manifest")")")"
+            ACTIVE_WORK="$WORK_TYPE/$WORK_NAME"
+            MANIFEST_PATH="$manifest"
+            break
+        fi
+    done
+fi
+
+# Build notepad content
+{
+    echo "# Forge Context Recovery"
+    echo ""
+    echo "**This file was auto-generated before context compaction.**"
+    echo "**Re-read the manifest and continue from where you left off.**"
+    echo ""
+    echo "## Active Work Item"
+
+    if [ -n "$ACTIVE_WORK" ]; then
+        echo "- Work: $ACTIVE_WORK"
+        echo "- Manifest: $MANIFEST_PATH"
+        echo ""
+
+        # Extract current phase info from manifest
+        if command -v grep &>/dev/null && [ -f "$MANIFEST_PATH" ]; then
+            echo "### Phase Status (from manifest)"
+            echo '```yaml'
+            grep -A 1 'status:\|gate-passed:' "$MANIFEST_PATH" 2>/dev/null | head -30
+            echo '```'
+        fi
+    else
+        echo "- No active work item found"
+    fi
+
+    echo ""
+    echo "## Recovery Instructions"
+    echo "1. Read the manifest file listed above"
+    echo "2. Find the first phase with \`status: pending\` or \`gate-passed: false\`"
+    echo "3. Continue from that phase"
+    echo "4. If build phase: check which tasks are complete vs pending"
+    echo ""
+    echo "---"
+    echo "*Generated at: $(date -u '+%Y-%m-%dT%H:%M:%SZ')*"
+} > "$NOTEPAD"
+
+# Log compaction event to telemetry
+TELEMETRY_FILE="$STATE_DIR/telemetry.jsonl"
+TIMESTAMP="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+WORK_JSON="${ACTIVE_WORK:-null}"
+if [ -n "$ACTIVE_WORK" ]; then WORK_JSON="\"$ACTIVE_WORK\""; fi
+
+echo "{\"event\":\"compact\",\"timestamp\":\"$TIMESTAMP\",\"work\":$WORK_JSON}" >> "$TELEMETRY_FILE"
+
+echo "Pre-compact: Saved context recovery state to $NOTEPAD" >&2
+exit 0

package/hooks/scripts/session-start.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Session start check: surface promotion-pending gotchas, unresolved hotfix
+# workarounds, and paused work items. Runs as a SessionStart hook — warns
+# loudly via stderr but does not block (Claude Code treats SessionStart exit
+# codes advisorily).
+#
+# Resolves .forge at the repo root via `git rev-parse --show-toplevel` to match
+# pre-compact.sh and telemetry.sh. Scans `.forge/work/*/` (typed subdirs) and
+# skips `escalated`/`completed` manifests (terminal states).
+
+set -u
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+FORGE_DIR="$PROJECT_ROOT/.forge"
+GLOBAL_GOTCHAS="$HOME/.claude/gotchas"
+WARNINGS=""
+
+# Hard-interrupt: promotion-pending gotchas.
+# When `support-gotcha` auto-drafts a proposed rule at the 3rd occurrence,
+# the gotcha's INDEX status column flips to `promotion-pending` and a
+# `Proposed Rule` block is appended to the gotcha file. The next
+# session-start surfaces every such entry so the user can approve / defer /
+# reject before doing other work.
+#
+# Match the INDEX table cell explicitly — `| promotion-pending |` — so the
+# scan does not false-positive on prose that happens to mention the literal
+# string ("see legend: promotion-pending entries..."). The cell can carry
+# trailing whitespace before the closing pipe; allow it with `[[:space:]]*`.
+PENDING_FILES=""
+for index_path in "$PROJECT_ROOT/aiwiki/gotchas/INDEX.md" "$GLOBAL_GOTCHAS/INDEX.md"; do
+  [ -f "$index_path" ] || continue
+  if grep -Eq '\|[[:space:]]*promotion-pending[[:space:]]*\|' "$index_path" 2>/dev/null; then
+    PENDING_FILES="${PENDING_FILES}${index_path}\n"
+  fi
+done
+
+if [ -n "$PENDING_FILES" ]; then
+  COUNT=$(printf "%b" "$PENDING_FILES" | grep -c '.' || echo 0)
+  WARNINGS="${WARNINGS}HARD-INTERRUPT: ${COUNT} gotcha index file(s) contain promotion-pending entries — auto-drafted rules awaiting review.\n"
+  WARNINGS="${WARNINGS}  Files:\n"
+  WARNINGS="${WARNINGS}$(printf "%b" "$PENDING_FILES" | sed 's/^/    /')\n"
+  WARNINGS="${WARNINGS}  Action: invoke support-gotcha to walk each promotion-pending entry (approve / defer / reject) BEFORE starting other work.\n"
+fi
+
+# Check for unresolved hotfix workarounds
+if [ -d "$PROJECT_ROOT/aiwiki/gotchas" ]; then
+  HOTFIX_FILES=$(grep -rl "severity: hotfix-workaround" "$PROJECT_ROOT/aiwiki/gotchas/" 2>/dev/null | while read -r f; do
+    if grep -q "resolved: false" "$f" 2>/dev/null || ! grep -q "resolved: true" "$f" 2>/dev/null; then
+      echo "$f"
+    fi
+  done)
+
+  if [ -n "$HOTFIX_FILES" ]; then
+    COUNT=$(echo "$HOTFIX_FILES" | wc -l | tr -d ' ')
+    WARNINGS="${WARNINGS}WARNING: ${COUNT} unresolved hotfix workaround(s) in aiwiki/gotchas/. Run /evolve or address these before starting new work.\n"
+  fi
+fi
+
+# Check for paused work items across all typed subdirs
+if [ -d "$FORGE_DIR/work" ]; then
+  PAUSED_ITEMS=""
+  for manifest in "$FORGE_DIR/work"/*/*/manifest.yaml; do
+    [ -f "$manifest" ] || continue
+    if grep -q 'status: paused' "$manifest" 2>/dev/null; then
+      # Extract {type}/{name} from path: .../.forge/work/{type}/{name}/manifest.yaml
+      TYPE_NAME="$(basename "$(dirname "$(dirname "$manifest")")")/$(basename "$(dirname "$manifest")")"
+      PAUSED_ITEMS="${PAUSED_ITEMS}${TYPE_NAME}\n"
+    fi
+  done
+
+  if [ -n "$PAUSED_ITEMS" ]; then
+    COUNT=$(printf "%b" "$PAUSED_ITEMS" | grep -c '.' || echo 0)
+    WARNINGS="${WARNINGS}WARNING: ${COUNT} paused work item(s) found. Resume with the relevant command or close them out.\n"
+  fi
+fi
+
+if [ -n "$WARNINGS" ]; then
+  printf "%b" "$WARNINGS" >&2
+fi
+
+exit 0