orbital-command 0.1.0

package/templates/hooks/orbital-report-deploy.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# orbital-report-deploy.sh — Report deployment events to Orbital dashboard
+#
+# Usage:
+#   orbital-report-deploy.sh <environment> <status> [commit_sha] [branch] [pr_number]
+#
+# Actions:
+#   New deployment:  orbital-report-deploy.sh staging deploying abc1234 feature/x 42
+#   Update status:   ORBITAL_DEPLOY_ID=5 orbital-report-deploy.sh staging healthy
+#
+# Environment variables:
+#   ORBITAL_DEPLOY_ID   — existing deployment ID to update (PATCH instead of POST)
+#   ORBITAL_URL         — base URL (default: http://localhost:4444)
+#
+# Health check URLs are read from .claude/orbital.config.json under "healthChecks".
+# If not configured, the health check step is skipped.
+#
+# Fails silently if the Orbital server is not running.
+set -e
+
+ENVIRONMENT="${1:?Usage: orbital-report-deploy.sh <environment> <status> [commit_sha] [branch] [pr_number]}"
+STATUS="${2:?Usage: orbital-report-deploy.sh <environment> <status> [commit_sha] [branch] [pr_number]}"
+COMMIT_SHA="${3:-}"
+BRANCH="${4:-}"
+PR_NUMBER="${5:-}"
+
+ORBITAL_URL="${ORBITAL_URL:-http://localhost:4444}"
+
+# Find project root for config lookup
+if [ -n "$CLAUDE_PROJECT_DIR" ]; then
+  PROJECT_ROOT="$CLAUDE_PROJECT_DIR"
+else
+  PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
+fi
+
+if [ -n "$ORBITAL_DEPLOY_ID" ]; then
+  # Update existing deployment — build payload with jq
+  JQ_ARGS=(--arg status "$STATUS")
+  JQ_EXPR='{status: $status}'
+  [ -n "$COMMIT_SHA" ] && JQ_ARGS+=(--arg details "$COMMIT_SHA") && JQ_EXPR='{status: $status, details: $details}'
+  PAYLOAD=$(jq -n "${JQ_ARGS[@]}" "$JQ_EXPR")
+
+  curl --fail --silent --max-time 2 \
+    -X PATCH \
+    -H "Content-Type: application/json" \
+    -d "$PAYLOAD" \
+    "$ORBITAL_URL/api/orbital/deployments/$ORBITAL_DEPLOY_ID" > /dev/null 2>&1 || true
+else
+  # Create new deployment record — build payload with jq
+  JQ_ARGS=(--arg environment "$ENVIRONMENT" --arg status "$STATUS")
+  JQ_EXPR='{environment: $environment, status: $status}'
+
+  [ -n "$COMMIT_SHA" ] && JQ_ARGS+=(--arg commit_sha "$COMMIT_SHA") && JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, commit_sha: $commit_sha}/')
+  [ -n "$BRANCH" ] && JQ_ARGS+=(--arg branch "$BRANCH") && JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, branch: $branch}/')
+  [ -n "$PR_NUMBER" ] && JQ_ARGS+=(--argjson pr_number "$PR_NUMBER") && JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, pr_number: $pr_number}/')
+
+  # Read health check URL from orbital.config.json if configured
+  HEALTH_URL=""
+  if command -v jq >/dev/null 2>&1 && [ -f "$PROJECT_ROOT/.claude/orbital.config.json" ]; then
+    HEALTH_URL=$(jq -r ".healthChecks[\"$ENVIRONMENT\"] // empty" "$PROJECT_ROOT/.claude/orbital.config.json" 2>/dev/null)
+  fi
+  [ -n "$HEALTH_URL" ] && JQ_ARGS+=(--arg health_check_url "$HEALTH_URL") && JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, health_check_url: $health_check_url}/')
+
+  PAYLOAD=$(jq -n "${JQ_ARGS[@]}" "$JQ_EXPR")
+
+  # POST and capture the response to extract deployment ID
+  RESPONSE=$(curl --fail --silent --max-time 2 \
+    -X POST \
+    -H "Content-Type: application/json" \
+    -d "$PAYLOAD" \
+    "$ORBITAL_URL/api/orbital/deployments" 2>/dev/null) || true
+
+  # Print the deployment ID for callers to capture
+  if [ -n "$RESPONSE" ]; then
+    DEPLOY_ID=$(echo "$RESPONSE" | jq -r '.id // empty' 2>/dev/null)
+    [ -n "$DEPLOY_ID" ] && echo "$DEPLOY_ID"
+  fi
+fi

package/templates/hooks/orbital-report-gates.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# orbital-report-gates.sh — Report quality gate results to Orbital dashboard
+#
+# Usage:
+#   orbital-report-gates.sh <gate_name> <pass|fail> [duration_ms] [details]
+#
+# Environment variables:
+#   ORBITAL_GATE_COMMIT_SHA  — commit SHA to tag the run (auto-detected if not set)
+#   ORBITAL_GATE_SCOPE_ID    — scope ID to associate with (optional)
+#   ORBITAL_URL              — base URL (default: http://localhost:4444)
+#
+# Fails silently if the Orbital server is not running.
+set -e
+
+GATE_NAME="${1:?Usage: orbital-report-gates.sh <gate_name> <pass|fail> [duration_ms] [details]}"
+STATUS="${2:?Usage: orbital-report-gates.sh <gate_name> <pass|fail> [duration_ms] [details]}"
+DURATION_MS="${3:-null}"
+DETAILS="${4:-}"
+
+ORBITAL_URL="${ORBITAL_URL:-http://localhost:4444}"
+COMMIT_SHA="${ORBITAL_GATE_COMMIT_SHA:-$(git rev-parse --short HEAD 2>/dev/null || echo "")}"
+SCOPE_ID="${ORBITAL_GATE_SCOPE_ID:-null}"
+
+# Build JSON payload using jq for safe escaping
+JQ_ARGS=(--arg gate_name "$GATE_NAME" --arg status "$STATUS")
+JQ_EXPR='{gate_name: $gate_name, status: $status}'
+
+[ "$SCOPE_ID" != "null" ] && JQ_ARGS+=(--argjson scope_id "$SCOPE_ID") && JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, scope_id: $scope_id}/')
+[ "$DURATION_MS" != "null" ] && JQ_ARGS+=(--argjson duration_ms "$DURATION_MS") && JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, duration_ms: $duration_ms}/')
+[ -n "$COMMIT_SHA" ] && JQ_ARGS+=(--arg commit_sha "$COMMIT_SHA") && JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, commit_sha: $commit_sha}/')
+[ -n "$DETAILS" ] && JQ_ARGS+=(--arg details "$DETAILS") && JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, details: $details}/')
+
+PAYLOAD=$(jq -n "${JQ_ARGS[@]}" "$JQ_EXPR")
+
+# POST to Orbital server — silent fail if not running
+curl --fail --silent --max-time 2 \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD" \
+  "$ORBITAL_URL/api/orbital/gates" > /dev/null 2>&1 || true

package/templates/hooks/orbital-report-violation.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# orbital-report-violation.sh — Emit a VIOLATION event to Orbital dashboard
+#
+# Usage:
+#   orbital-report-violation.sh <rule_name> [file] [details]
+#
+# Examples:
+#   orbital-report-violation.sh "no-any" "src/services/foo.ts" "Found ': any' on line 42"
+#   orbital-report-violation.sh "file-size" "src/big.ts" "452 lines (limit 400)"
+#   orbital-report-violation.sh "no-console" "" "3 console.log found"
+#
+# Delegates to orbital-emit.sh for file-based event delivery.
+set -e
+
+RULE="${1:?Usage: orbital-report-violation.sh <rule_name> [file] [details]}"
+FILE="${2:-}"
+DETAILS="${3:-}"
+
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Build JSON data payload using jq for safe escaping
+JQ_ARGS=(--arg rule "$RULE" --arg outcome "detected")
+JQ_EXPR='{rule: $rule, outcome: $outcome}'
+
+if [ -n "$FILE" ]; then
+  JQ_ARGS+=(--arg file "$FILE")
+  JQ_EXPR='{rule: $rule, outcome: $outcome, file: $file}'
+fi
+if [ -n "$DETAILS" ]; then
+  JQ_ARGS+=(--arg details "$DETAILS")
+  JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, details: $details}/')
+fi
+
+DATA=$(jq -n "${JQ_ARGS[@]}" "$JQ_EXPR")
+
+"$HOOK_DIR/orbital-emit.sh" VIOLATION "$DATA"

package/templates/hooks/orbital-scope-update.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# orbital-scope-update.sh — Update scope status on the Orbital dashboard
+#
+# Usage:
+#   orbital-scope-update SCOPE_ID STATUS
+#   orbital-scope-update 78 implementing
+#   orbital-scope-update 35,66,70 implementing   # bulk update
+#
+# Valid statuses: backlog, team-review, blockers, implementing,
+#                 testing, gates, code-review, pr-ci, staging, production, done
+#
+# Falls back to file-based event if Orbital server isn't reachable.
+set -e
+
+SCOPE_IDS="${1:?Usage: orbital-scope-update SCOPE_ID[,SCOPE_ID,...] STATUS}"
+STATUS="${2:?Usage: orbital-scope-update SCOPE_ID STATUS}"
+
+ORBITAL_API="http://localhost:4444/api/orbital"
+
+# Try the REST API first (fastest, real-time)
+if command -v curl &>/dev/null; then
+  # Check if it's a bulk update (comma-separated IDs)
+  if [[ "$SCOPE_IDS" == *","* ]]; then
+    # Build bulk JSON payload using jq for safe escaping
+    IFS=',' read -ra IDS <<< "$SCOPE_IDS"
+    SCOPES_JSON=$(printf '%s\n' "${IDS[@]}" | tr -d ' ' | jq -R 'tonumber' | jq -s --arg status "$STATUS" '[.[] | {id: ., status: $status}]')
+    PAYLOAD=$(jq -n --argjson scopes "$SCOPES_JSON" '{scopes: $scopes}')
+
+    HTTP_CODE=$(curl -s -o /dev/null -w '%{http_code}' -X PATCH \
+      -H 'Content-Type: application/json' \
+      -d "$PAYLOAD" \
+      "$ORBITAL_API/scopes/bulk/status" 2>/dev/null) || true
+  else
+    PAYLOAD=$(jq -n --arg status "$STATUS" '{status: $status}')
+    HTTP_CODE=$(curl -s -o /dev/null -w '%{http_code}' -X PATCH \
+      -H 'Content-Type: application/json' \
+      -d "$PAYLOAD" \
+      "$ORBITAL_API/scopes/$SCOPE_IDS" 2>/dev/null) || true
+  fi
+
+  if [ "$HTTP_CODE" = "200" ]; then
+    exit 0
+  fi
+fi
+
+# Fallback: emit SCOPE_STATUS_CHANGED event via file bus
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+IFS=',' read -ra IDS <<< "$SCOPE_IDS"
+for id in "${IDS[@]}"; do
+  id=$(echo "$id" | tr -d ' ')
+  DATA=$(jq -n --arg to "$STATUS" '{to: $to}')
+  "$SCRIPT_DIR/orbital-emit.sh" SCOPE_STATUS_CHANGED "$DATA" --scope "$id" 2>/dev/null &
+done

package/templates/hooks/phase-verify-reminder.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# phase-verify-reminder.sh — Remind to verify before marking phase done
+# Trigger: PreToolUse:Edit (scope file with completion marker)
+# Nudge-style: always exits 0
+set -e
+
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+NEW_STRING=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty')
+
+# Only trigger on scope files
+source "$(dirname "$0")/scope-helpers.sh"
+is_scope_file "$FILE_PATH" || exit 0
+
+# Only trigger when marking something as done
+echo "$NEW_STRING" | grep -qE "✅|Done" || exit 0
+
+echo ""
+echo "✅ Marking phase done — verify first:"
+echo "   □ npm run type-check && npm run build"
+echo "   □ Changes tested or reviewed"
+echo ""
+
+exit 0

package/templates/hooks/review-gate-check.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# review-gate-check.sh — PreToolUse:Edit hook
+#
+# Blocks scope completion (status → completed) unless a valid review verdict
+# exists with PASS verdict and session separation.
+#
+# Exit codes:
+#   0 — Allow the edit
+#   2 — Block (no verdict, failed verdict, or session separation violation)
+set -euo pipefail
+
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+NEW_STRING=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty')
+
+# Only enforce on scope files
+source "$(dirname "$0")/scope-helpers.sh"
+is_scope_file "$FILE_PATH" || exit 0
+
+# Only enforce when status is being set to completed
+echo "$NEW_STRING" | grep -qiE "status:.*completed" || exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+VERDICTS_DIR="$PROJECT_DIR/.claude/review-verdicts"
+
+# ─── Extract scope number from filename ───
+FILENAME=$(basename "$FILE_PATH" .md)
+# Handle patterns: 083-platform-fees, 047a-critical-fixes
+SCOPE_NUM=$(echo "$FILENAME" | grep -oE '^[0-9]+' | head -1)
+
+if [ -z "$SCOPE_NUM" ]; then
+  # Can't determine scope number — allow (template files, etc.)
+  exit 0
+fi
+
+# Pad to 3 digits for verdict file lookup (force base-10 to avoid octal)
+SCOPE_NUM_CLEAN=$((10#${SCOPE_NUM}))
+PADDED=$(printf '%03d' "$SCOPE_NUM_CLEAN")
+VERDICT_FILE="$VERDICTS_DIR/${PADDED}.json"
+
+# ─── Check verdict file exists ───
+if [ ! -f "$VERDICT_FILE" ]; then
+  echo "" >&2
+  echo "MUST_BLOCK: No review verdict found for scope $PADDED." >&2
+  echo "   Run: /scope-post-review $PADDED" >&2
+  echo "   The review gate must pass before a scope can be completed." >&2
+  echo "   Verdict file expected at: .claude/review-verdicts/${PADDED}.json" >&2
+  echo "   Format: {\"verdict\": \"PASS\", \"reviewSession\": \"uuid\", \"implementSession\": \"uuid\"}" >&2
+  echo "" >&2
+  exit 2
+fi
+
+# ─── Validate verdict is PASS ───
+VERDICT=$(jq -r '.verdict // empty' "$VERDICT_FILE")
+if [ "$VERDICT" != "PASS" ]; then
+  echo "" >&2
+  echo "MUST_BLOCK: Review verdict for scope $PADDED is '$VERDICT', not PASS." >&2
+  echo "   Fix the failing criteria and re-run: /scope-post-review $PADDED" >&2
+  echo "   Verdict file: .claude/review-verdicts/${PADDED}.json" >&2
+  echo "" >&2
+  exit 2
+fi
+
+# ─── Validate session separation ───
+REVIEW_SESSION=$(jq -r '.reviewSession // empty' "$VERDICT_FILE")
+IMPLEMENT_SESSION=$(jq -r '.implementSession // empty' "$VERDICT_FILE")
+
+if [ -n "$REVIEW_SESSION" ] && [ -n "$IMPLEMENT_SESSION" ]; then
+  if [ "$REVIEW_SESSION" = "$IMPLEMENT_SESSION" ]; then
+    echo "" >&2
+    echo "MUST_BLOCK: Session separation violation in verdict for scope $PADDED." >&2
+    echo "   The review session ($REVIEW_SESSION) matches the implement session." >&2
+    echo "   A different Claude Code session must run /scope-post-review (the user starts a new session)." >&2
+    echo "" >&2
+    exit 2
+  fi
+fi
+
+# All checks passed
+exit 0

package/templates/hooks/scope-commit-logger.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# scope-commit-logger.sh — Suggest Implementation Log entry after commits
+# Trigger: PostToolUse:Bash (git commit detected)
+# Nudge-style: always exits 0
+set -e
+
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+echo "$COMMAND" | grep -qE "git commit" || exit 0
+
+# Check commit succeeded
+EXIT_CODE=$(echo "$INPUT" | jq -r '.tool_result.exitCode // .tool_result.exit_code // "0"')
+[ "$EXIT_CODE" != "0" ] && exit 0
+
+source "$(dirname "$0")/scope-helpers.sh"
+SCOPE=$(find_active_scope) || exit 0
+
+COMMIT_HASH=$(cd "$SCOPE_PROJECT_DIR" && git rev-parse --short HEAD 2>/dev/null || true)
+COMMIT_MSG=$(cd "$SCOPE_PROJECT_DIR" && git log -1 --pretty=format:%s 2>/dev/null || true)
+SCOPE_ID=$(echo "$(basename "$SCOPE")" | grep -oE '[0-9]+' | head -1)
+
+# Emit COMMIT event to Orbital dashboard
+HOOK_DIR="$(dirname "$0")"
+COMMIT_DATA=$(jq -n --arg hash "$COMMIT_HASH" --arg message "$COMMIT_MSG" '{hash: $hash, message: $message}')
+AGENT_DATA=$(jq -n --arg outcome "committed" --arg commit_hash "$COMMIT_HASH" '{outcome: $outcome, commit_hash: $commit_hash}')
+"$HOOK_DIR/orbital-emit.sh" COMMIT "$COMMIT_DATA" --scope "$SCOPE_ID"
+"$HOOK_DIR/orbital-emit.sh" AGENT_COMPLETED "$AGENT_DATA" --scope "$SCOPE_ID" &
+
+echo ""
+echo "📝 Consider updating Implementation Log in $(basename "$SCOPE"):"
+echo "   Commit: $COMMIT_HASH"
+echo "   Add: phase, what changed, issues encountered"
+echo ""
+
+exit 0

package/templates/hooks/scope-create-cleanup.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+#
+# scope-create-cleanup.sh — PostToolUse:Write cleanup
+#
+# After a successful Write, checks if the written file is a scope document.
+# If so, removes the .scope-create-session marker to lift the write gate.
+#
+set -e
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+MARKER="$PROJECT_DIR/.claude/metrics/.scope-create-session"
+
+# Fast exit: no marker = nothing to clean
+[ -f "$MARKER" ] || exit 0
+
+# Extract file_path from tool input
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+[ -z "$FILE_PATH" ] && exit 0
+
+# Check if written file is a scope document in planning/
+case "$FILE_PATH" in
+  */scopes/planning/*.md)
+    rm -f "$MARKER"
+    HOOK_DIR="$(dirname "$0")"
+    GATE_DATA=$(jq -n --arg scope_file "$FILE_PATH" '{scope_file: $scope_file}')
+    "$HOOK_DIR/orbital-emit.sh" SCOPE_GATE_LIFTED "$GATE_DATA" 2>/dev/null &
+    echo ""
+    echo "Scope document written. Write gate lifted."
+    echo "Remember: STOP here. Implementation is a separate session:"
+    echo "  /scope-implement NNN"
+    ;;
+esac
+
+exit 0

package/templates/hooks/scope-create-gate.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+#
+# scope-create-gate.sh — PreToolUse:Write|Edit blocker
+#
+# Blocks writes to non-scope files while a /scope create session is active.
+# The marker (.scope-create-session) is set by scope-create-tracker.sh and
+# removed by scope-create-cleanup.sh after the scope document is written.
+#
+# Exit codes: 0 = allow, 2 = block
+set -e
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+MARKER="$PROJECT_DIR/.claude/metrics/.scope-create-session"
+
+# Fast exit: no marker = no gate
+[ -f "$MARKER" ] || exit 0
+
+# Optional: auto-expire stale markers (older than 2 hours)
+if [ "$(uname)" = "Darwin" ]; then
+  MARKER_AGE=$(( $(date +%s) - $(stat -f %m "$MARKER") ))
+else
+  MARKER_AGE=$(( $(date +%s) - $(stat -c %Y "$MARKER") ))
+fi
+if [ "$MARKER_AGE" -gt 900 ]; then
+  rm -f "$MARKER"
+  exit 0
+fi
+
+# Extract file_path from tool input
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# If no file_path found, allow (defensive — don't break unknown tool shapes)
+[ -z "$FILE_PATH" ] && exit 0
+
+# ─── Allowlisted paths ───
+# 1. Scope files
+case "$FILE_PATH" in
+  */scopes/*) exit 0 ;;
+esac
+
+# 2. Plan files (both project-local and home directory)
+case "$FILE_PATH" in
+  */.claude/plans/*) exit 0 ;;
+esac
+
+# 3. Claude project config files
+case "$FILE_PATH" in
+  "$PROJECT_DIR"/.claude/*) exit 0 ;;
+esac
+
+# 4. Home-directory Claude plans
+HOME_DIR="${HOME:-/Users/$(whoami)}"
+case "$FILE_PATH" in
+  "$HOME_DIR"/.claude/plans/*) exit 0 ;;
+esac
+
+# ─── Block everything else ───
+HOOK_DIR="$(dirname "$0")"
+VIOLATION_DATA=$(jq -n --arg rule "scope-create-gate" --arg file "$FILE_PATH" --arg outcome "blocked" '{rule: $rule, file: $file, outcome: $outcome}')
+"$HOOK_DIR/orbital-emit.sh" VIOLATION "$VIOLATION_DATA" 2>/dev/null &
+
+# Resolve entry status from workflow manifest
+HOOK_DIR="$(dirname "$0")"
+source "$HOOK_DIR/scope-helpers.sh" 2>/dev/null || true
+ENTRY="${WORKFLOW_ENTRY_STATUS:-planning}"
+
+echo "BLOCKED: Write to non-scope file during /scope create"
+echo ""
+echo "  File: $FILE_PATH"
+echo ""
+echo "  You must write the scope document first:"
+echo "    1. Find next scope number (highest NNN in scopes/**/*.md + 1, zero-padded to 3 digits)"
+echo "    2. Copy template from scopes/_template.md"
+echo "    3. Write to scopes/$ENTRY/NNN-short-description.md"
+echo ""
+echo "  After the scope document is written, the gate lifts automatically."
+echo "  To abandon: delete .claude/metrics/.scope-create-session"
+exit 2

package/templates/hooks/scope-create-tracker.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# scope-create-tracker.sh — Track when /scope create is invoked
+# Trigger: PostToolUse:Skill
+set -e
+
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+SKILL=$(echo "$INPUT" | jq -r '.tool_input.skill // empty')
+
+# Only track scope create invocations
+[[ "$SKILL" == "scope-create" ]] || exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+mkdir -p "$PROJECT_DIR/.claude/metrics"
+echo "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$PROJECT_DIR/.claude/metrics/.scope-create-session"
+
+exit 0

package/templates/hooks/scope-file-sync.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# scope-file-sync.sh — Flag out-of-scope files before commits
+# Trigger: PreToolUse:Bash (git commit detected)
+# Nudge-style: always exits 0
+set -e
+
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+echo "$COMMAND" | grep -qE "git commit" || exit 0
+
+source "$(dirname "$0")/scope-helpers.sh"
+SCOPE=$(find_active_scope) || exit 0
+
+# Get staged files
+STAGED=$(cd "$SCOPE_PROJECT_DIR" && git diff --cached --name-only 2>/dev/null)
+[ -z "$STAGED" ] && exit 0
+
+# Get file references from scope's Files Summary table
+SCOPE_FILES=$(grep -oE '`[^`]+\.(ts|tsx|js|jsx|md|json|sh|css)`' "$SCOPE" | tr -d '`' | sort -u)
+[ -z "$SCOPE_FILES" ] && exit 0
+
+# Build a patterns file for grep -Ff matching (O(n) instead of O(n²))
+SCOPE_PATTERNS_FILE=$(mktemp)
+trap "rm -f '$SCOPE_PATTERNS_FILE'" EXIT
+# Add both full paths and basenames as patterns
+echo "$SCOPE_FILES" > "$SCOPE_PATTERNS_FILE"
+echo "$SCOPE_FILES" | xargs -I{} basename {} >> "$SCOPE_PATTERNS_FILE"
+
+OUT_OF_SCOPE=""
+for staged_file in $STAGED; do
+  # Skip non-code and meta files
+  [[ "$staged_file" == *.lock ]] && continue
+  [[ "$staged_file" == *"node_modules"* ]] && continue
+  [[ "$staged_file" == *".claude/"* ]] && continue
+  [[ "$staged_file" == *"scopes/"* ]] && continue
+
+  # Check if staged file or its basename matches any scope file pattern
+  if ! echo "$staged_file" | grep -qFf "$SCOPE_PATTERNS_FILE" && \
+     ! basename "$staged_file" | grep -qFf "$SCOPE_PATTERNS_FILE"; then
+    OUT_OF_SCOPE="$OUT_OF_SCOPE   - $staged_file\n"
+  fi
+done
+
+if [ -n "$OUT_OF_SCOPE" ]; then
+  echo ""
+  echo "⚠️  Files outside scope ($(basename "$SCOPE")):"
+  echo -e "$OUT_OF_SCOPE"
+  echo "   If intentional, document in PROCESS > Deviations from Spec"
+  echo ""
+fi
+
+exit 0

package/templates/hooks/scope-gate.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# scope-gate.sh — After plan approval, instruct agent to write scope doc
+# Trigger: PostToolUse:ExitPlanMode
+# Only fires when /scope create was invoked this session
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+MARKER="$PROJECT_DIR/.claude/metrics/.scope-create-session"
+
+# Only act if /scope create was invoked this session
+[ -f "$MARKER" ] || exit 0
+
+# NOTE: Marker is NOT deleted here — scope-create-gate.sh (PreToolUse)
+# blocks non-scope writes until the scope document is created.
+# scope-create-cleanup.sh (PostToolUse) removes the marker after the scope is written.
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  SCOPE DOCUMENT REQUIRED"
+echo ""
+echo "  Write the scope document now using your plan."
+echo "  Follow the create skill steps:"
+echo "    1. Find next scope number"
+echo "    2. Copy template from scopes/_template.md"
+echo "    3. Fill SPECIFICATION from your plan"
+echo "    4. Set status: planning, spec_locked: true"
+echo ""
+echo "  ⛔ Writes to non-scope files are BLOCKED until"
+echo "     the scope document is written."
+echo ""
+echo "  Then STOP. Implementation is a separate session:"
+echo "    /scope-implement NNN"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+exit 0