orbital-command 0.1.0

package/templates/hooks/scope-helpers.sh

@@ -0,0 +1,188 @@
+#!/bin/bash
+# scope-helpers.sh — Shared utilities for scope lifecycle hooks
+#
+# Source this file from other scope hooks:
+#   source "$(dirname "$0")/scope-helpers.sh"
+set -e
+
+# Check if a file path is a scope markdown file
+is_scope_file() {
+  local fp="$1"
+  [[ "$fp" == *"scopes/"* && "$fp" == *.md ]]
+}
+
+SCOPE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+SCOPE_IMPLEMENTING_DIR="$SCOPE_PROJECT_DIR/scopes/implementing"
+
+# ─── Source workflow manifest (auto-generated by WorkflowEngine) ───
+MANIFEST_FILE="$SCOPE_PROJECT_DIR/.claude/config/workflow-manifest.sh"
+if [ -f "$MANIFEST_FILE" ]; then
+  source "$MANIFEST_FILE"
+else
+  # Fallback defaults (matches new Default trunk workflow)
+  WORKFLOW_BRANCHING_MODE="trunk"
+  WORKFLOW_STATUSES="icebox planning backlog implementing review completed main"
+  WORKFLOW_DIR_STATUSES="icebox planning backlog implementing review completed main"
+  WORKFLOW_ENTRY_STATUS="icebox"
+  WORKFLOW_EDGES=(
+    "planning:backlog:reviewScope"
+    "backlog:implementing:implementScope"
+    "implementing:review:reviewGate"
+    "review:completed:commit"
+    "completed:main:pushToMain"
+  )
+  WORKFLOW_BRANCH_MAP=(
+    "main:completed:main:pushToMain"
+  )
+  WORKFLOW_COMMIT_BRANCHES="^(main|feat/|fix/|scope/|chore/)"
+  WORKFLOW_DIRECTION_ALIASES=()
+fi
+
+# Ensure defaults for variables the manifest may not define
+WORKFLOW_COMMIT_BRANCHES="${WORKFLOW_COMMIT_BRANCHES:-^(main|feat/|fix/|scope/|chore/)}"
+if [ -z "${WORKFLOW_DIRECTION_ALIASES+x}" ]; then
+  WORKFLOW_DIRECTION_ALIASES=()
+fi
+
+# Map status to directory name (manifest-driven)
+status_to_dir() {
+  local scope_status="$1"
+  for s in $WORKFLOW_DIR_STATUSES; do
+    [ "$s" = "$scope_status" ] && echo "$scope_status" && return 0
+  done
+  echo "$WORKFLOW_ENTRY_STATUS"
+}
+
+# Move a scope file to the directory matching target_status
+move_scope() {
+  local src="$1" target_status="$2"
+  local dir_name=$(status_to_dir "$target_status")
+  local target_dir="$SCOPE_PROJECT_DIR/scopes/$dir_name"
+  local filename=$(basename "$src")
+  mkdir -p "$target_dir"
+  if ! git mv "$src" "$target_dir/$filename" 2>/dev/null; then
+    echo "WARNING: git mv failed for $filename, using plain mv" >&2
+    mv "$src" "$target_dir/$filename"
+  fi
+  echo "$target_dir/$filename"
+}
+
+# Find scopes with a given status in a specific directory
+find_scopes_by_status() {
+  local find_status="$1"
+  local dir="${2:-$SCOPE_IMPLEMENTING_DIR}"
+  [ -d "$dir" ] || return 1
+  for f in "$dir"/*.md; do
+    [ -f "$f" ] || continue
+    head -15 "$f" | grep -q "^status: $find_status" && echo "$f"
+  done
+}
+
+# Get the currently active scope (implementing > review > backlog > planning)
+# Uses a session-scoped cache to avoid O(n) directory scans on every call.
+# Call invalidate_active_scope_cache() after scope transitions.
+find_active_scope() {
+  local cache_file="$SCOPE_PROJECT_DIR/.claude/metrics/.active-scope"
+  # Check cache: must exist, be < 60s old, and point to a real file
+  if [ -f "$cache_file" ]; then
+    local cached
+    cached=$(cat "$cache_file" 2>/dev/null)
+    if [ -n "$cached" ] && [ -f "$cached" ]; then
+      local cache_age
+      if [ "$(uname)" = "Darwin" ]; then
+        cache_age=$(( $(date +%s) - $(stat -f %m "$cache_file") ))
+      else
+        cache_age=$(( $(date +%s) - $(stat -c %Y "$cache_file") ))
+      fi
+      if [ "$cache_age" -lt 60 ]; then
+        echo "$cached"
+        return 0
+      fi
+    fi
+  fi
+
+  # Cache miss — scan directories
+  local scope
+  scope=$(find_scopes_by_status "implementing" "$SCOPE_IMPLEMENTING_DIR" | head -1)
+  [ -z "$scope" ] && scope=$(find_scopes_by_status "review" "$SCOPE_PROJECT_DIR/scopes/review" | head -1)
+  [ -z "$scope" ] && scope=$(find_scopes_by_status "backlog" "$SCOPE_PROJECT_DIR/scopes/backlog" | head -1)
+  [ -z "$scope" ] && scope=$(find_scopes_by_status "planning" "$SCOPE_PROJECT_DIR/scopes/planning" | head -1)
+
+  if [ -n "$scope" ]; then
+    mkdir -p "$(dirname "$cache_file")"
+    printf '%s' "$scope" > "$cache_file"
+    echo "$scope"
+    return 0
+  fi
+  return 1
+}
+
+# Invalidate the active scope cache (call after transitions)
+invalidate_active_scope_cache() {
+  rm -f "$SCOPE_PROJECT_DIR/.claude/metrics/.active-scope"
+}
+
+# Get a YAML frontmatter field from a scope file
+get_frontmatter() {
+  local file="$1" field="$2"
+  sed -n '2,/^---$/p' "$file" | grep "^$field:" | sed "s/^$field:[[:space:]]*//; s/^[\"']//; s/[\"']$//"
+}
+
+# Set a simple frontmatter field (top-level only, e.g. status, updated)
+set_frontmatter() {
+  local file="$1" field="$2" value="$3"
+  local tmp="${file}.tmp.$$"
+  (
+    flock -x 200 2>/dev/null || true
+    sed "s/^${field}:.*/${field}: ${value}/" "$file" > "$tmp" && mv "$tmp" "$file"
+  ) 200>"${file}.lock"
+  rm -f "${file}.lock"
+}
+
+# Append a UUID to a sessions array key in frontmatter
+# Handles inline YAML arrays: key: [uuid1, uuid2]
+append_session_uuid() {
+  local file="$1" key="$2" uuid="$3"
+  local tmp="${file}.tmp.$$"
+  (
+    flock -x 200 2>/dev/null || true
+    awk -v key="$key" -v uuid="$uuid" '
+      BEGIN { found_sessions=0; found_key=0; added=0 }
+      /^sessions:/ { found_sessions=1 }
+      found_sessions && $0 ~ "^  " key ":" {
+        found_key=1
+        if (index($0, uuid) > 0) { added=1; print; next }
+        # Append UUID to existing array: [a, b] -> [a, b, uuid]
+        sub(/\]$/, ", " uuid "]")
+        added=1
+      }
+      # After sessions: block ends (next top-level key), insert key if not found
+      found_sessions && !found_key && /^[^ ]/ && !/^sessions:/ {
+        print "  " key ": [" uuid "]"
+        found_key=1; added=1
+      }
+      { print }
+      END {
+        # If sessions: block was never found, or key never added
+        if (!found_sessions) {
+          print "sessions:"
+          print "  " key ": [" uuid "]"
+        } else if (!added) {
+          print "  " key ": [" uuid "]"
+        }
+      }
+    ' "$file" > "$tmp" && mv "$tmp" "$file"
+  ) 200>"${file}.lock"
+  rm -f "${file}.lock"
+}
+
+# Find scope file by numeric ID across all directories
+find_scope_by_id() {
+  local id="$1"
+  local padded
+  local id_clean
+  id_clean=$(echo "$id" | sed 's/^0*//')
+  [ -z "$id_clean" ] && id_clean="0"
+  padded=$(printf '%03d' "$id_clean")
+  find "$SCOPE_PROJECT_DIR/scopes/" -name "${padded}-*.md" -o -name "${padded}[a-dX]-*.md" 2>/dev/null | head -1
+}

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

@@ -0,0 +1,139 @@
+#!/bin/bash
+# scope-lifecycle-gate.sh — PreToolUse:Bash hook
+#
+# Intercepts git commit / git push / gh pr create and records session
+# UUIDs on active scopes before the command executes.
+#
+# Session recording:
+#   git commit (on feature branch) → records "commit" session on active scope
+#   git push to staging / gh pr --base staging → transitions dev → staging (with BATCH_SCOPE_IDS)
+#   git push to main / gh pr --base main → transitions staging → production (with BATCH_SCOPE_IDS)
+#
+# NOTE: completed → dev auto-transition removed (2026-03-04).
+# Use /git-dev to explicitly merge feature→dev.
+#
+# BATCH_SCOPE_IDS must be set (e.g. BATCH_SCOPE_IDS=093,094) for any
+# transition to occur. Without it, a warning is printed and no files move.
+#
+# Exit codes:
+#   0 — Allow the command to proceed
+#   2 — Block (never used here; transitions are advisory)
+set -euo pipefail
+
+INPUT=$(cat)
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# ─── Fast exit: only process git commit, git push, gh pr create ───
+echo "$COMMAND" | grep -qE '^git (commit|push)|^gh pr create' || exit 0
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+# ─── Resolve session UUID (from hook input or process tree) ───
+SESSION_UUID=$(echo "$INPUT" | jq -r '.session_id // empty')
+if [ -z "$SESSION_UUID" ]; then
+  SESSION_UUID=$("$SCRIPT_DIR/get-session-id.sh" 2>/dev/null || true)
+fi
+
+source "$SCRIPT_DIR/scope-helpers.sh"
+
+# ─── Determine current branch ───
+BRANCH=$(cd "$PROJECT_DIR" && git branch --show-current 2>/dev/null || true)
+
+# ─── git commit: record session on active scope ───
+if echo "$COMMAND" | grep -qE '^git commit'; then
+  # Only on branches matching commit pattern from manifest
+  if [[ "$BRANCH" =~ $WORKFLOW_COMMIT_BRANCHES ]]; then
+    # Record session on active scopes AND review scopes
+    # Note: scopes are gitignored, so no git add needed
+    if [ -n "$SESSION_UUID" ]; then
+      ACTIVE_SCOPE=$(find_active_scope 2>/dev/null || true)
+      if [ -n "$ACTIVE_SCOPE" ] && [ -f "$ACTIVE_SCOPE" ]; then
+        append_session_uuid "$ACTIVE_SCOPE" "commit" "$SESSION_UUID"
+      fi
+      # Also record on all review scopes (for review→completed transitions)
+      REVIEW_DIR="$PROJECT_DIR/scopes/review"
+      if [ -d "$REVIEW_DIR" ]; then
+        for f in "$REVIEW_DIR"/*.md; do
+          [ -f "$f" ] || continue
+          append_session_uuid "$f" "commit" "$SESSION_UUID"
+        done
+      fi
+    fi
+
+    # NOTE: completed → dev auto-transition removed.
+    # Use /git-dev to explicitly merge feature→dev and transition scopes.
+  fi
+  exit 0
+fi
+
+# ─── git push / gh pr create: determine target branch ───
+TARGET_BRANCH=""
+
+if echo "$COMMAND" | grep -qE '^git push'; then
+  # Check for branch names mentioned in WORKFLOW_BRANCH_MAP
+  for mapping in "${WORKFLOW_BRANCH_MAP[@]}"; do
+    IFS=':' read -r map_branch map_from map_to map_skey <<< "$mapping"
+    if echo "$COMMAND" | grep -qE "\\b${map_branch}\\b"; then
+      TARGET_BRANCH="$map_branch"
+      break
+    fi
+  done
+  # Also check if current branch matches a mapped branch
+  if [ -z "$TARGET_BRANCH" ]; then
+    for mapping in "${WORKFLOW_BRANCH_MAP[@]}"; do
+      IFS=':' read -r map_branch map_from map_to map_skey <<< "$mapping"
+      if [ "$BRANCH" = "$map_branch" ]; then
+        TARGET_BRANCH="$map_branch"
+        break
+      fi
+    done
+  fi
+elif echo "$COMMAND" | grep -qE '^gh pr create'; then
+  # gh pr create --base staging / --base main
+  TARGET_BRANCH=$(echo "$COMMAND" | grep -oE '\-\-base[[:space:]]+[a-z]+' | awk '{print $2}')
+fi
+
+# ─── Resolve target branch to transition via manifest ───
+TRANSITION_FROM=""
+TRANSITION_TO=""
+
+for mapping in "${WORKFLOW_BRANCH_MAP[@]}"; do
+  IFS=':' read -r map_branch map_from map_to map_skey <<< "$mapping"
+  if [ "$TARGET_BRANCH" = "$map_branch" ]; then
+    TRANSITION_FROM="$map_from"
+    TRANSITION_TO="$map_to"
+    break
+  fi
+done
+
+# ─── Execute transition if mapped ───
+if [ -n "$TRANSITION_FROM" ] && [ -n "$TRANSITION_TO" ]; then
+  if [ -n "$BATCH_SCOPE_IDS" ]; then
+    if ! echo "$BATCH_SCOPE_IDS" | grep -qE '^[0-9]+(,[0-9]+)*$'; then
+      echo "ERROR: BATCH_SCOPE_IDS contains invalid characters. Must be comma-separated integers with no spaces, e.g. BATCH_SCOPE_IDS=093,094,095" >&2
+      exit 1
+    fi
+    echo ""
+    echo "Batch: transitioning scopes [$BATCH_SCOPE_IDS] → $TRANSITION_TO..."
+    IFS=',' read -ra BATCH_IDS <<< "$BATCH_SCOPE_IDS"
+    for bid in "${BATCH_IDS[@]}"; do
+      bash "$SCRIPT_DIR/scope-transition.sh" --from "$TRANSITION_FROM" --to "$TRANSITION_TO" \
+        --scope "$bid" ${SESSION_UUID:+--session "$SESSION_UUID"}
+    done
+    echo ""
+  else
+    # Guard: require explicit BATCH_SCOPE_IDS to prevent accidental bulk transitions
+    SOURCE_DIR="$PROJECT_DIR/scopes/$TRANSITION_FROM"
+    if [ -d "$SOURCE_DIR" ]; then
+      SOURCE_COUNT=$(find "$SOURCE_DIR" -name '*.md' ! -name '_template.md' 2>/dev/null | wc -l | tr -d ' ')
+      if [ "$SOURCE_COUNT" -gt 0 ]; then
+        echo "   ⚠️  $SOURCE_COUNT $TRANSITION_FROM scope(s) found but no BATCH_SCOPE_IDS set."
+        echo "      Set BATCH_SCOPE_IDS=093,094 to transition specific scopes."
+      fi
+    fi
+  fi
+fi
+
+exit 0

package/templates/hooks/scope-prepare.sh

@@ -0,0 +1,244 @@
+#!/bin/bash
+# scope-prepare.sh — One-shot scope file preparation
+#
+# Consolidates file lookup, ID assignment, template scaffolding,
+# session recording, and gate cleanup into a single Bash call.
+#
+# Modes:
+#   --promote ID     Promote icebox idea to planning (renumber + move + scaffold)
+#   --scaffold ID    Apply template to existing planning scope
+#   --new            Create brand new scope
+#
+# Options:
+#   --title "..."    Scope title (required for --new)
+#   --desc "..."     Description / problem statement
+#   --category "..." Category tag (default: TBD)
+#
+# Output: JSON to stdout
+# Errors: to stderr
+# Exit: 0=success, 1=arg error, 2=source not found, 3=template missing, 4=collision
+set -e
+
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$HOOK_DIR/scope-helpers.sh"
+
+# ─── Argument parsing ────────────────────────────────────────────
+MODE=""
+SOURCE_ID=""
+TITLE=""
+DESCRIPTION=""
+CATEGORY="TBD"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --promote)   MODE="promote";  SOURCE_ID="$2"; shift 2 ;;
+    --scaffold)  MODE="scaffold"; SOURCE_ID="$2"; shift 2 ;;
+    --new)       MODE="new"; shift ;;
+    --title)     TITLE="$2"; shift 2 ;;
+    --desc)      DESCRIPTION="$2"; shift 2 ;;
+    --category)  CATEGORY="$2"; shift 2 ;;
+    *)           echo "Unknown argument: $1" >&2; exit 1 ;;
+  esac
+done
+
+if [ -z "$MODE" ]; then
+  echo "Usage: scope-prepare.sh --promote ID | --scaffold ID | --new --title \"...\"" >&2
+  exit 1
+fi
+
+if [ "$MODE" = "new" ] && [ -z "$TITLE" ]; then
+  echo "Error: --new requires --title" >&2
+  exit 1
+fi
+
+# ─── Session ID (inlined from get-session-id.sh) ────────────────
+SESSION_ID=""
+SESSION_DIR="$SCOPE_PROJECT_DIR/.claude/metrics/.session-ids"
+if [ -d "$SESSION_DIR" ]; then
+  CURRENT_PID=$PPID
+  VISITED=""
+  while [ "$CURRENT_PID" -gt 1 ] 2>/dev/null; do
+    case " $VISITED " in *" $CURRENT_PID "*) break ;; esac
+    VISITED="$VISITED $CURRENT_PID"
+    for f in "$SESSION_DIR/${CURRENT_PID}"-*; do
+      if [ -f "$f" ]; then
+        SESSION_ID=$(cat "$f")
+        break 2
+      fi
+    done
+    if [ -f "$SESSION_DIR/$CURRENT_PID" ]; then
+      SESSION_ID=$(cat "$SESSION_DIR/$CURRENT_PID")
+      break
+    fi
+    CURRENT_PID=$(ps -o ppid= -p "$CURRENT_PID" 2>/dev/null | tr -d ' ')
+    [ -z "$CURRENT_PID" ] && break
+  done
+fi
+
+# ─── Resolve source file + extract metadata ─────────────────────
+OLD_FILE=""
+NOW_DATE=$(date +%Y-%m-%d)
+NOW_TIME=$(date +%H:%M)
+CREATED_DATE="$NOW_DATE"
+
+case "$MODE" in
+  promote)
+    OLD_FILE=$(find_scope_by_id "$SOURCE_ID")
+    if [ -z "$OLD_FILE" ] || [ ! -f "$OLD_FILE" ]; then
+      echo "Error: Scope $SOURCE_ID not found" >&2
+      exit 2
+    fi
+    [ -z "$TITLE" ] && TITLE=$(get_frontmatter "$OLD_FILE" "title")
+    # Preserve original created date
+    orig_created=$(get_frontmatter "$OLD_FILE" "created")
+    [ -n "$orig_created" ] && CREATED_DATE="$orig_created"
+    # Extract description from body (everything after frontmatter closing ---)
+    if [ -z "$DESCRIPTION" ]; then
+      DESCRIPTION=$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$OLD_FILE" | head -20 | sed '/^$/d' | head -5)
+    fi
+    # Get category if set
+    orig_cat=$(get_frontmatter "$OLD_FILE" "category")
+    [ -n "$orig_cat" ] && [ "$orig_cat" != "TBD" ] && CATEGORY="$orig_cat"
+    ;;
+
+  scaffold)
+    OLD_FILE=$(find_scope_by_id "$SOURCE_ID")
+    if [ -z "$OLD_FILE" ] || [ ! -f "$OLD_FILE" ]; then
+      echo "Error: Scope $SOURCE_ID not found" >&2
+      exit 2
+    fi
+    [ -z "$TITLE" ] && TITLE=$(get_frontmatter "$OLD_FILE" "title")
+    orig_created=$(get_frontmatter "$OLD_FILE" "created")
+    [ -n "$orig_created" ] && CREATED_DATE="$orig_created"
+    if [ -z "$DESCRIPTION" ]; then
+      DESCRIPTION=$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$OLD_FILE" | head -20 | sed '/^$/d' | head -5)
+    fi
+    orig_cat=$(get_frontmatter "$OLD_FILE" "category")
+    [ -n "$orig_cat" ] && [ "$orig_cat" != "TBD" ] && CATEGORY="$orig_cat"
+    ;;
+esac
+
+# ─── Compute scope ID ───────────────────────────────────────────
+compute_next_id() {
+  local max_id=0
+  if [ -d "$SCOPE_PROJECT_DIR/scopes" ]; then
+    for dir in "$SCOPE_PROJECT_DIR/scopes"/*/; do
+      [ -d "$dir" ] || continue
+      [ "$(basename "$dir")" = "icebox" ] && continue
+      for f in "$dir"*.md; do
+        [ -f "$f" ] || continue
+        local num
+        num=$(basename "$f" | grep -oE '^[0-9]+' | sed 's/^0*//')
+        [ -z "$num" ] && continue
+        [ "$num" -gt "$max_id" ] 2>/dev/null && max_id=$num
+      done
+    done
+  fi
+  echo $((max_id + 1))
+}
+
+case "$MODE" in
+  promote)
+    SCOPE_ID=$(compute_next_id)
+    ;;
+  scaffold)
+    # Use existing ID from frontmatter
+    SCOPE_ID=$(get_frontmatter "$OLD_FILE" "id" | sed 's/^0*//')
+    [ -z "$SCOPE_ID" ] && SCOPE_ID=$(basename "$OLD_FILE" | grep -oE '^[0-9]+' | sed 's/^0*//')
+    ;;
+  new)
+    SCOPE_ID=$(compute_next_id)
+    ;;
+esac
+
+PADDED_ID=$(printf '%03d' "$SCOPE_ID")
+
+# ─── Build slug + paths ─────────────────────────────────────────
+SLUG=$(printf '%s' "$TITLE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/--*/-/g; s/^-//; s/-$//' | cut -c1-60)
+PLANNING_DIR="$SCOPE_PROJECT_DIR/scopes/planning"
+mkdir -p "$PLANNING_DIR"
+NEW_FILE="$PLANNING_DIR/${PADDED_ID}-${SLUG}.md"
+
+# For scaffold mode, the target IS the existing file (possibly same path)
+if [ "$MODE" = "scaffold" ]; then
+  NEW_FILE="$OLD_FILE"
+fi
+
+# Collision check (promote/new only)
+if [ "$MODE" != "scaffold" ] && [ -f "$NEW_FILE" ]; then
+  echo "Error: Target file already exists: $NEW_FILE" >&2
+  exit 4
+fi
+
+# ─── Template scaffolding ───────────────────────────────────────
+TEMPLATE="$SCOPE_PROJECT_DIR/scopes/_template.md"
+if [ ! -f "$TEMPLATE" ]; then
+  echo "Error: Template not found: $TEMPLATE (run 'orbital init' first)" >&2
+  exit 3
+fi
+
+# Escape description for sed replacement (handle &, /, \, newlines)
+ESCAPED_DESC=$(printf '%s' "$DESCRIPTION" | head -1 | sed 's/[&/\]/\\&/g')
+[ -z "$ESCAPED_DESC" ] && ESCAPED_DESC="[Problem statement - what's broken or needed]"
+
+# Escape title for sed
+ESCAPED_TITLE=$(printf '%s' "$TITLE" | sed 's/[&/\]/\\&/g; s/"/\\"/g')
+
+# Build sessions line
+if [ -n "$SESSION_ID" ]; then
+  SESSIONS_REPLACEMENT="sessions:\\
+  createScope: [$SESSION_ID]"
+else
+  SESSIONS_REPLACEMENT="sessions: {}"
+fi
+
+# Apply template substitutions
+# Note: some template lines have trailing YAML comments (e.g. "category: "TBD"  # ..."),
+# so we match the value portion without anchoring to end-of-line.
+sed \
+  -e "s/^id: NNN/id: $PADDED_ID/" \
+  -e "s/^title: \"Scope Title\"/title: \"$ESCAPED_TITLE\"/" \
+  -e "s/^category: \"TBD\".*/category: \"$CATEGORY\"/" \
+  -e "s/^created: YYYY-MM-DD/created: $CREATED_DATE/" \
+  -e "s/^updated: YYYY-MM-DD/updated: $NOW_DATE/" \
+  -e "s/^sessions: {}.*/$SESSIONS_REPLACEMENT/" \
+  -e "s/# Scope NNN: Title/# Scope $PADDED_ID: $ESCAPED_TITLE/" \
+  -e "s/YYYY-MM-DD HH:MM/$NOW_DATE $NOW_TIME/g" \
+  -e "s/Scope created$/Scope created via \/scope-create/" \
+  -e "s/\[Problem statement - what's broken or needed\]/$ESCAPED_DESC/" \
+  -e "s/\[What prompted this exploration\]/$ESCAPED_DESC/" \
+  "$TEMPLATE" > "$NEW_FILE"
+
+# ─── Cleanup old file (promote only) ────────────────────────────
+if [ "$MODE" = "promote" ] && [ -n "$OLD_FILE" ] && [ "$OLD_FILE" != "$NEW_FILE" ]; then
+  rm -f "$OLD_FILE"
+fi
+
+# ─── Gate lifecycle: remove marker + emit event ─────────────────
+MARKER="$SCOPE_PROJECT_DIR/.claude/metrics/.scope-create-session"
+rm -f "$MARKER"
+
+# Emit event in background (non-blocking)
+"$HOOK_DIR/orbital-emit.sh" SCOPE_GATE_LIFTED \
+  "{\"scope_file\":\"$NEW_FILE\",\"id\":$SCOPE_ID,\"mode\":\"$MODE\"}" \
+  --scope "$SCOPE_ID" --session "$SESSION_ID" 2>/dev/null &
+
+# ─── JSON output ────────────────────────────────────────────────
+# Compute relative path
+REL_PATH="${NEW_FILE#"$SCOPE_PROJECT_DIR/"}"
+
+# Manual JSON construction (no jq dependency)
+printf '{"id":"%s","path":"%s","title":"%s","description":"%s","session_id":"%s","category":"%s","mode":"%s"}\n' \
+  "$PADDED_ID" \
+  "$REL_PATH" \
+  "$(printf '%s' "$TITLE" | sed 's/"/\\"/g')" \
+  "$(printf '%s' "$DESCRIPTION" | head -1 | sed 's/"/\\"/g')" \
+  "$SESSION_ID" \
+  "$CATEGORY" \
+  "$MODE"
+
+# Print reminder to stderr (visible to Claude but not parsed as JSON)
+echo "" >&2
+echo "Scope document written. Write gate lifted." >&2
+echo "Remember: STOP here. Implementation is a separate session:" >&2
+echo "  /scope-implement $PADDED_ID" >&2