orbital-command 0.1.0

package/templates/hooks/block-push.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# block-push.sh — PreToolUse:Bash hook
+#
+# Enforces stage-specific git restrictions using flag files
+# managed by git-commit-guard.sh (PreToolUse:Skill):
+#   .block-push-active    → blocks git push   (during /git-commit)
+#   .implementing-session → blocks git commit/add (during /scope-implement)
+set -euo pipefail
+
+INPUT=$(cat)
+
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+[ -z "$TOOL_NAME" ] && TOOL_NAME="$CLAUDE_TOOL_NAME"
+[ "$TOOL_NAME" != "Bash" ] && exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+PUSH_FLAG="$PROJECT_DIR/.claude/.block-push-active"
+IMPL_FLAG="$PROJECT_DIR/.claude/.implementing-session"
+
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+[ -z "$COMMAND" ] && COMMAND="$INPUT"
+
+HOOK_DIR="$(dirname "$0")"
+
+# Build workflow-specific pipeline hint from manifest (only on block path)
+_pipeline_after() {
+  local start="$1" found=false result=""
+  source "$HOOK_DIR/scope-helpers.sh" 2>/dev/null || return
+  for s in $WORKFLOW_STATUSES; do
+    if [ "$found" = true ]; then
+      result="${result:+$result → }$s"
+    fi
+    [ "$s" = "$start" ] && found=true
+  done
+  echo "$result"
+}
+
+# Block git push during /git-commit
+if [ -f "$PUSH_FLAG" ]; then
+  if echo "$COMMAND" | grep -qE '(^|[;&|]\s*)git\s+push'; then
+    "$HOOK_DIR/orbital-emit.sh" VIOLATION '{"rule":"block-push","outcome":"blocked"}' 2>/dev/null || true
+    REMAINING=$(_pipeline_after "completed")
+    echo "BLOCKED: /git-commit only commits locally — it does not push to remote."
+    echo ""
+    echo "Your job is done once the commit is created. Do not push."
+    echo "The next workflow step pushes to: ${REMAINING:-the next stage}."
+    exit 2
+  fi
+fi
+
+# Block git commit/add during /scope-implement
+if [ -f "$IMPL_FLAG" ]; then
+  if echo "$COMMAND" | grep -qE '(^|[;&|]\s*)git\s+(commit|add)'; then
+    "$HOOK_DIR/orbital-emit.sh" VIOLATION '{"rule":"block-commit-implementing","outcome":"blocked"}' 2>/dev/null || true
+    REMAINING=$(_pipeline_after "implementing")
+    echo "BLOCKED: Implementing sessions must not commit."
+    echo ""
+    echo "Code changes stay uncommitted until the review pipeline handles them."
+    echo "Remaining pipeline: ${REMAINING:-review → completed}."
+    exit 2
+  fi
+fi
+
+exit 0

package/templates/hooks/block-workarounds.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+#
+# Claude Code PreToolUse Hook: Block Dangerous Workarounds
+#
+# Blocks two critical patterns that bypass safety:
+# 1. --no-verify (skips pre-commit hooks)
+# 2. Direct push to main (bypasses PR workflow)
+#
+set -euo pipefail
+
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+[ -z "$TOOL_NAME" ] && TOOL_NAME="$CLAUDE_TOOL_NAME"
+
+# Only process Bash tool calls
+[ "$TOOL_NAME" != "Bash" ] && exit 0
+
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+[ -z "$COMMAND" ] && COMMAND="$INPUT"
+
+HOOK_DIR="$(dirname "$0")"
+
+# Override mechanism: OVERRIDE_RULE="rule-name:reason"
+# When set, logs the override and allows the command through
+if [ -n "${OVERRIDE_RULE:-}" ]; then
+  RULE_NAME="${OVERRIDE_RULE%%:*}"
+  REASON="${OVERRIDE_RULE#*:}"
+  OVERRIDE_DATA=$(jq -n --arg rule "$RULE_NAME" --arg reason "$REASON" --arg outcome "overridden" '{rule: $rule, reason: $reason, outcome: $outcome}')
+  "$HOOK_DIR/orbital-emit.sh" OVERRIDE "$OVERRIDE_DATA"
+  echo "OVERRIDE: Rule '$RULE_NAME' overridden (reason: $REASON)"
+  exit 0
+fi
+
+# Pattern 1: --no-verify flag
+if echo "$COMMAND" | grep -qE "\-\-no-verify"; then
+  "$HOOK_DIR/orbital-emit.sh" VIOLATION '{"rule":"no-verify","pattern":"--no-verify","outcome":"blocked"}'
+  echo "BLOCKED: Attempting to skip verification hooks"
+  echo ""
+  echo "Fix the failing checks instead:"
+  echo "  cd backend && npm run type-check"
+  echo "  cd backend && npm run lint"
+  echo ""
+  echo "If a check is genuinely wrong, discuss with the user."
+  exit 2
+fi
+
+# Pattern 2: Direct push to main (covers: git push origin main, git push --force origin main, HEAD:main)
+if echo "$COMMAND" | grep -qE 'git push\b.*\bmain\b|HEAD:main'; then
+  "$HOOK_DIR/orbital-emit.sh" VIOLATION '{"rule":"push-main","pattern":"push to main","outcome":"blocked"}'
+  echo "BLOCKED: Direct push to main is forbidden"
+  echo ""
+  echo "Use /git-commit to route to the proper workflow:"
+  echo "  - Creates feature branch if needed"
+  echo "  - Opens PR to staging (not main)"
+  echo "  - Ensures CI runs before merge"
+  exit 2
+fi
+
+exit 0

package/templates/hooks/blocker-check.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# blocker-check.sh — Note unresolved blockers when advancing scope status
+# Trigger: PreToolUse:Edit (scope file with status change)
+# 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')
+
+source "$(dirname "$0")/scope-helpers.sh"
+is_scope_file "$FILE_PATH" || exit 0
+echo "$NEW_STRING" | grep -qiE "status:.*implementing|status:.*backlog|In Progress" || exit 0
+
+# Count BLOCKER references (exclude resolved ones)
+[ -f "$FILE_PATH" ] || exit 0
+BLOCKERS=$(grep -c "^- \[B-" "$FILE_PATH" || echo "0")
+
+if [ "$BLOCKERS" -gt 0 ]; then
+  echo ""
+  echo "🚧 $BLOCKERS blocker(s) found in $(basename "$FILE_PATH")"
+  echo "   Verify all are resolved before advancing status."
+  echo ""
+fi
+
+exit 0

package/templates/hooks/completion-checklist.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# completion-checklist.sh — Block completion when Definition of Done items are unchecked
+# Trigger: PreToolUse:Edit (scope status → complete)
+# Blocking: exits 2 when unchecked DoD items found
+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')
+
+source "$(dirname "$0")/scope-helpers.sh"
+is_scope_file "$FILE_PATH" || exit 0
+echo "$NEW_STRING" | grep -qiE "status:.*complete" || exit 0
+
+# Count unchecked DoD items
+UNCHECKED=$(sed -n '/Definition of Done/,/^═/p' "$FILE_PATH" 2>/dev/null | grep -c "\- \[ \]")
+
+if [ "${UNCHECKED:-0}" -gt 0 ]; then
+  echo "" >&2
+  echo "MUST_BLOCK: $UNCHECKED unchecked Definition of Done items in $(basename "$FILE_PATH")" >&2
+  echo "   Check all items in the '## Definition of Done' section: - [x] item (checked) vs - [ ] item (unchecked)." >&2
+  echo "" >&2
+  exit 2
+fi
+
+exit 0

package/templates/hooks/decision-capture.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# decision-capture.sh — Prompt to log decisions after user questions
+# Trigger: PostToolUse:AskUserQuestion
+# Nudge-style: always exits 0
+set -e
+
+source "$(dirname "$0")/scope-helpers.sh"
+SCOPE=$(find_active_scope) || exit 0
+
+echo ""
+echo "📋 User decision made — consider logging in"
+echo "   PROCESS > Decisions & Reasoning of $(basename "$SCOPE")"
+echo ""
+
+exit 0

package/templates/hooks/dependency-check.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# dependency-check.sh — Check blocked_by dependencies when advancing status
+# Trigger: PreToolUse:Edit (scope file with status change)
+# 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')
+
+source "$(dirname "$0")/scope-helpers.sh"
+is_scope_file "$FILE_PATH" || exit 0
+echo "$NEW_STRING" | grep -qiE "status:.*implementing|status:.*backlog" || exit 0
+
+# Extract blocked_by from frontmatter
+BLOCKED_BY=$(sed -n '2,/^---$/p' "$FILE_PATH" | grep "^blocked_by:" | sed 's/blocked_by:[[:space:]]*//' | tr -d '[]"')
+
+if [ -n "$BLOCKED_BY" ] && [ "$BLOCKED_BY" != " " ]; then
+  echo ""
+  echo "🔗 Dependencies: blocked_by: $BLOCKED_BY"
+  echo "   Verify blocking scopes are complete before starting."
+  echo ""
+fi
+
+exit 0

package/templates/hooks/end-session.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+#
+# Claude Code SessionEnd Hook: Session Cleanup
+#
+# Emits SESSION_END event to Orbital dashboard so active dispatch indicators
+# are cleared when a Claude session exits normally.
+#
+set -e
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PID="$PPID"
+
+# Emit session end event to Orbital dashboard (non-blocking)
+SESSION_DATA="{\"pid\":$PID"
+# Include dispatch ID if this session was launched by Orbital dispatch
+if [ -n "$ORBITAL_DISPATCH_ID" ]; then
+  SESSION_DATA="${SESSION_DATA},\"dispatch_id\":\"$ORBITAL_DISPATCH_ID\""
+fi
+SESSION_DATA="${SESSION_DATA}}"
+"$SCRIPT_DIR/orbital-emit.sh" SESSION_END "$SESSION_DATA" 2>/dev/null &
+
+# Clean up cached session ID file (new glob format + old format)
+rm -f "$PROJECT_DIR/.claude/metrics/.session-ids/${PID}"-* 2>/dev/null
+rm -f "$PROJECT_DIR/.claude/metrics/.session-ids/$PID" 2>/dev/null
+
+# Clean up skill guard flags
+rm -f "$PROJECT_DIR/.claude/.block-push-active" 2>/dev/null
+
+# SessionEnd hooks must never block termination
+exit 0

package/templates/hooks/exploration-logger.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# exploration-logger.sh — Remind to log exploration findings periodically
+# Trigger: PostToolUse:Grep|Glob (search operations)
+# Nudge-style: always exits 0
+set -e
+
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+[[ "$TOOL_NAME" == "Grep" || "$TOOL_NAME" == "Glob" ]] || exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+COUNTER_FILE="$PROJECT_DIR/.claude/metrics/.exploration-count"
+mkdir -p "$(dirname "$COUNTER_FILE")"
+
+# Atomic counter increment with flock
+(
+  flock -x 200 2>/dev/null || true
+  COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+  COUNT=$((COUNT + 1))
+  echo "$COUNT" > "$COUNTER_FILE"
+) 200>"${COUNTER_FILE}.lock"
+rm -f "${COUNTER_FILE}.lock"
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+
+# Remind every 25 searches
+if [ $((COUNT % 25)) -eq 0 ]; then
+  source "$(dirname "$0")/scope-helpers.sh"
+  SCOPE=$(find_active_scope) || exit 0
+
+  echo ""
+  echo "🔍 $COUNT searches this session — log key findings in"
+  echo "   PROCESS > Exploration Log of $(basename "$SCOPE")"
+  echo ""
+fi
+
+exit 0

package/templates/hooks/files-changed-summary.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# files-changed-summary.sh — Show planned vs actual files before completion
+# Trigger: PreToolUse:Edit (scope status → complete)
+# 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')
+
+source "$(dirname "$0")/scope-helpers.sh"
+is_scope_file "$FILE_PATH" || exit 0
+echo "$NEW_STRING" | grep -qiE "status:.*complete" || exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Count file references in scope
+PLANNED=$(grep -cE '`[^`]+\.(ts|tsx|js|jsx|css|sh)`' "$FILE_PATH" 2>/dev/null || echo "?")
+
+# Count actual files changed since scope began (use baseCommit if available)
+BASE_COMMIT=$(get_frontmatter "$FILE_PATH" "baseCommit" 2>/dev/null)
+if [ -n "$BASE_COMMIT" ]; then
+  ACTUAL=$(cd "$PROJECT_DIR" && git diff --name-only "$BASE_COMMIT"...HEAD 2>/dev/null | wc -l | tr -d ' ')
+else
+  ACTUAL=$(cd "$PROJECT_DIR" && git diff --name-only HEAD~5 2>/dev/null | wc -l | tr -d ' ')
+fi
+
+echo ""
+echo "📂 Scope completion summary for $(basename "$FILE_PATH"):"
+echo "   Planned: ~$PLANNED file references in scope"
+echo "   Changed: ~$ACTUAL files in recent commits"
+echo "   Review PROCESS > Deviations from Spec if significant difference"
+echo ""
+
+exit 0

package/templates/hooks/get-session-id.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# get-session-id.sh — Parallel-safe session UUID lookup
+#
+# Reads the session ID cached by init-session.sh at session start.
+# Walks up the process tree from $PPID to find the session file,
+# which handles callers nested at any depth (e.g. subagent shells).
+#
+# Usage (from skills via Bash tool):
+#   SESSION_UUID=$(bash .claude/hooks/get-session-id.sh)
+#
+# Exit codes:
+#   0 — Success, UUID printed to stdout
+#   1 — Session ID not found
+set -e
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SESSION_DIR="$PROJECT_DIR/.claude/metrics/.session-ids"
+
+# Walk up the process tree checking each ancestor PID.
+# init-session.sh keys on $PPID (Claude Code's PID), but callers
+# may be nested deeper (e.g. Skill tool -> Bash tool -> this script).
+CURRENT_PID=$PPID
+VISITED=""
+while [ "$CURRENT_PID" -gt 1 ] 2>/dev/null; do
+  # Cycle detection
+  case " $VISITED " in
+    *" $CURRENT_PID "*) break ;;
+  esac
+  VISITED="$VISITED $CURRENT_PID"
+
+  # New format: {PID}-{UUID}
+  for f in "$SESSION_DIR/${CURRENT_PID}"-*; do
+    if [ -f "$f" ]; then
+      cat "$f"
+      exit 0
+    fi
+  done
+  # Old format: just {PID}
+  if [ -f "$SESSION_DIR/$CURRENT_PID" ]; then
+    cat "$SESSION_DIR/$CURRENT_PID"
+    exit 0
+  fi
+  # Move to parent
+  CURRENT_PID=$(ps -o ppid= -p "$CURRENT_PID" 2>/dev/null | tr -d ' ')
+  [ -z "$CURRENT_PID" ] && break
+done
+
+echo "ERROR: No session ID found in process tree from PID $PPID. Was init-session.sh invoked?" >&2
+exit 1

package/templates/hooks/git-commit-guard.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# git-commit-guard.sh — PreToolUse:Skill hook
+#
+# Manages skill-scoped flag files so block-push.sh can enforce
+# stage-specific restrictions:
+#   /git-commit      → .block-push-active    (blocks git push)
+#   /scope-implement → .implementing-session  (blocks git commit/add)
+# Clears flags when any other skill is invoked.
+set -euo pipefail
+
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+
+SKILL=$(echo "$INPUT" | jq -r '.tool_input.skill // empty')
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+PUSH_FLAG="$PROJECT_DIR/.claude/.block-push-active"
+IMPL_FLAG="$PROJECT_DIR/.claude/.implementing-session"
+
+# /git-commit → block pushes during commit skill
+if [ "$SKILL" = "git-commit" ]; then
+  touch "$PUSH_FLAG"
+else
+  rm -f "$PUSH_FLAG"
+fi
+
+# /scope-implement → block commits during implementing
+if [ "$SKILL" = "scope-implement" ]; then
+  touch "$IMPL_FLAG"
+else
+  rm -f "$IMPL_FLAG"
+fi
+
+exit 0

package/templates/hooks/init-session.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+#
+# Claude Code SessionStart Hook: Session Initialization
+#
+set -e
+
+INPUT=$(cat)
+if echo "$INPUT" | jq empty 2>/dev/null; then
+  SOURCE=$(echo "$INPUT" | jq -r '.source // "startup"')
+else
+  SOURCE="startup"
+fi
+[ -z "$SOURCE" ] && SOURCE="startup"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# ─── Cache session ID for parallel-safe lookup by skills ───
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+if [ -n "$SESSION_ID" ]; then
+  SESSION_DIR="$PROJECT_DIR/.claude/metrics/.session-ids"
+  mkdir -p "$SESSION_DIR"
+  printf '%s' "$SESSION_ID" > "$SESSION_DIR/${PPID}-${SESSION_ID}"
+  # Clean up stale session files older than 4h with PID liveness check
+  find "$SESSION_DIR" -type f -mmin +240 2>/dev/null | while IFS= read -r f; do
+    STALE_PID=$(basename "$f" | cut -d'-' -f1)
+    if [ -n "$STALE_PID" ] && ! kill -0 "$STALE_PID" 2>/dev/null; then
+      rm -f "$f"
+    fi
+  done
+fi
+
+# Clean stale markers from previous sessions
+rm -f "$PROJECT_DIR/.claude/metrics/.scope-create-session"
+rm -f "$PROJECT_DIR/.claude/metrics/.exploration-count"
+rm -f "$PROJECT_DIR/.claude/metrics/.active-scope"
+
+# Resolve project name from orbital.config.json or git repo name
+PROJECT_NAME=""
+if command -v jq >/dev/null 2>&1 && [ -f "$PROJECT_DIR/.claude/orbital.config.json" ]; then
+  PROJECT_NAME=$(jq -r '.projectName // empty' "$PROJECT_DIR/.claude/orbital.config.json" 2>/dev/null)
+fi
+[ -z "$PROJECT_NAME" ] && PROJECT_NAME=$(basename "$(git -C "$PROJECT_DIR" rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null) || true
+[ -z "$PROJECT_NAME" ] && PROJECT_NAME="Project"
+
+# Abbreviated banner for resumed/compacted sessions
+if [ "$SOURCE" = "resume" ] || [ "$SOURCE" = "compact" ]; then
+  cat << EOF
+
+══════════════════════════════════════════════════════════════════════════════
+${PROJECT_NAME} SESSION RESUMED
+══════════════════════════════════════════════════════════════════════════════
+
+  Rules: .claude/quick/rules.md | Git: /git-commit | Test: /test-checks
+
+══════════════════════════════════════════════════════════════════════════════
+
+EOF
+  exit 0
+fi
+
+# Full banner for new/cleared sessions
+cat << EOF
+
+══════════════════════════════════════════════════════════════════════════════
+${PROJECT_NAME} SESSION INITIALIZED
+══════════════════════════════════════════════════════════════════════════════
+
+KEY REFERENCES:
+
+   Entry point:    .claude/INDEX.md
+   All rules:      .claude/quick/rules.md
+   Anti-patterns:  .claude/anti-patterns/dangerous-shortcuts.md
+
+GIT WORKFLOW:
+
+   /git-commit   → Commit work
+   /git-main     → Push to main (or /git-staging, /git-production for Gitflow)
+
+══════════════════════════════════════════════════════════════════════════════
+
+EOF
+
+# Emit session start event to Orbital dashboard (non-blocking)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SESSION_DATA="{\"source\":\"$SOURCE\",\"pid\":$PPID"
+# Include dispatch ID if this session was launched by Orbital dispatch
+if [ -n "$ORBITAL_DISPATCH_ID" ]; then
+  SESSION_DATA="${SESSION_DATA},\"dispatch_id\":\"$ORBITAL_DISPATCH_ID\""
+fi
+SESSION_DATA="${SESSION_DATA}}"
+"$SCRIPT_DIR/orbital-emit.sh" SESSION_START "$SESSION_DATA" 2>/dev/null &
+
+exit 0

package/templates/hooks/orbital-emit.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# orbital-emit.sh — Emit events to Orbital dashboard via file-based bus
+#
+# Usage:
+#   orbital-emit EVENT_TYPE '{"key": "value"}'
+#   orbital-emit EVENT_TYPE '{"key": "value"}' --scope 78 --agent attacker --session abc123
+#
+# Events are written as JSON files to .claude/orbital-events/
+# The Orbital server watches this directory and ingests them.
+# If the server isn't running, events queue up and are processed on startup.
+set -e
+
+EVENT_TYPE="${1:?Usage: orbital-emit EVENT_TYPE '{\"key\": \"value\"}' [--scope N] [--agent NAME] [--session ID]}"
+EVENT_DATA="${2:-'{}'}"
+shift 2 2>/dev/null || shift 1
+
+# Parse optional named arguments
+SCOPE_ID=""
+AGENT=""
+SESSION_ID=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --scope)  SCOPE_ID="$2"; shift 2 ;;
+    --agent)  AGENT="$2"; shift 2 ;;
+    --session) SESSION_ID="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+EVENT_ID=$(uuidgen 2>/dev/null | tr '[:upper:]' '[:lower:]' \
+  || cat /proc/sys/kernel/random/uuid 2>/dev/null \
+  || python3 -c 'import uuid; print(uuid.uuid4())' 2>/dev/null \
+  || echo "$(date +%s)-$$-$RANDOM")
+
+# Find project root
+if [ -n "$CLAUDE_PROJECT_DIR" ]; then
+  PROJECT_ROOT="$CLAUDE_PROJECT_DIR"
+else
+  PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
+fi
+
+EVENTS_DIR="${PROJECT_ROOT}/.claude/orbital-events"
+mkdir -p "$EVENTS_DIR"
+
+# Validate inputs
+[[ -n "$SCOPE_ID" && ! "$SCOPE_ID" =~ ^[0-9]+$ ]] && SCOPE_ID=""
+
+# Validate EVENT_DATA is valid JSON; fall back to wrapping as string
+if ! echo "$EVENT_DATA" | jq empty 2>/dev/null; then
+  EVENT_DATA=$(jq -n --arg d "$EVENT_DATA" '$d')
+fi
+
+# Build JSON with optional top-level fields using jq for safe escaping
+EVENT_FILE="${EVENTS_DIR}/${EVENT_ID}.json"
+
+JQ_ARGS=(
+  --arg id "$EVENT_ID"
+  --arg type "$EVENT_TYPE"
+  --argjson data "$EVENT_DATA"
+  --arg timestamp "$TIMESTAMP"
+)
+JQ_EXPR='{id: $id, type: $type, data: $data, timestamp: $timestamp}'
+
+if [ -n "$SCOPE_ID" ]; then
+  JQ_ARGS+=(--argjson scope_id "$SCOPE_ID")
+  JQ_EXPR='{id: $id, type: $type, scope_id: $scope_id, data: $data, timestamp: $timestamp}'
+fi
+if [ -n "$AGENT" ]; then
+  JQ_ARGS+=(--arg agent "$AGENT")
+  JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, agent: $agent}/')
+fi
+if [ -n "$SESSION_ID" ]; then
+  JQ_ARGS+=(--arg session_id "$SESSION_ID")
+  JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, session_id: $session_id}/')
+fi
+
+jq -n "${JQ_ARGS[@]}" "$JQ_EXPR" > "$EVENT_FILE"