orbital-command 0.1.0

package/templates/hooks/scope-transition.sh

@@ -0,0 +1,172 @@
+#!/bin/bash
+# scope-transition.sh — Centralized scope lifecycle transition utility
+#
+# Moves scope files between lifecycle directories and updates frontmatter.
+#
+# Usage:
+#   scope-transition.sh <direction|--from STATUS --to STATUS> [--scope ID] [--session UUID]
+#
+# Directions (backward-compat aliases):
+#   to-dev        — completed → dev   (called by /git-dev skill)
+#   to-staging    — dev → staging     (on push/PR to staging)
+#   to-production — staging → production (on push/PR to main)
+#
+# Generic form (manifest-driven):
+#   --from completed --to dev
+#   --from dev --to staging
+#
+# Options:
+#   --scope ID    — Transition a specific scope by numeric ID
+#   --session UUID — Session UUID to record (default: from get-session-id.sh)
+#
+# Exit codes:
+#   0 — Success (or nothing to transition)
+#   1 — Invalid arguments
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/scope-helpers.sh"
+
+# ─── Parse arguments ───
+DIRECTION=""
+SCOPE_ID=""
+SESSION_UUID=""
+FROM_STATUS=""
+TO_STATUS=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    to-dev|to-staging|to-production) DIRECTION="$1" ;;
+    --from) FROM_STATUS="$2"; shift ;;
+    --to) TO_STATUS="$2"; shift ;;
+    --scope) SCOPE_ID="$2"; shift ;;
+    --session) SESSION_UUID="$2"; shift ;;
+    *) echo "Unknown argument: $1" >&2; exit 1 ;;
+  esac
+  shift
+done
+
+# ─── Resolve direction alias or --from/--to ───
+if [ -n "$DIRECTION" ]; then
+  # Resolve via WORKFLOW_DIRECTION_ALIASES (from manifest or fallback)
+  RESOLVED=false
+  for alias_entry in "${WORKFLOW_DIRECTION_ALIASES[@]}"; do
+    IFS=':' read -r alias_name alias_from alias_to alias_skey <<< "$alias_entry"
+    if [ "$alias_name" = "$DIRECTION" ]; then
+      SOURCE_STATUS="$alias_from"
+      TARGET_STATUS="$alias_to"
+      SESSION_KEY="$alias_skey"
+      RESOLVED=true
+      break
+    fi
+  done
+
+  if [ "$RESOLVED" = false ]; then
+    VALID_ALIASES=""
+    for a in "${WORKFLOW_DIRECTION_ALIASES[@]}"; do
+      IFS=':' read -r aname _ _ _ <<< "$a"
+      VALID_ALIASES="${VALID_ALIASES:+$VALID_ALIASES, }$aname"
+    done
+    echo "ERROR: Unknown direction '$DIRECTION'." >&2
+    echo "  Valid directions: ${VALID_ALIASES:-none (use --from STATUS --to STATUS instead)}" >&2
+    echo "  Valid statuses: $WORKFLOW_STATUSES" >&2
+    exit 1
+  fi
+elif [ -n "$FROM_STATUS" ] && [ -n "$TO_STATUS" ]; then
+  # Generic --from/--to: look up session key from WORKFLOW_EDGES
+  SOURCE_STATUS="$FROM_STATUS"
+  TARGET_STATUS="$TO_STATUS"
+  SESSION_KEY=""
+  for edge_entry in "${WORKFLOW_EDGES[@]}"; do
+    IFS=':' read -r edge_from edge_to edge_skey <<< "$edge_entry"
+    if [ "$edge_from" = "$SOURCE_STATUS" ] && [ "$edge_to" = "$TARGET_STATUS" ]; then
+      SESSION_KEY="$edge_skey"
+      break
+    fi
+  done
+else
+  echo "Usage: scope-transition.sh <direction|--from STATUS --to STATUS> [--scope ID] [--session UUID]" >&2
+  echo "Directions: to-dev, to-staging, to-production (backward-compat aliases)" >&2
+  echo "Generic:    --from completed --to dev (manifest-driven)" >&2
+  exit 1
+fi
+
+# ─── File lock (flock-based, no TOCTOU race) ───
+LOCK_FILE="/tmp/orbital-scope-${SCOPE_ID:-all}.flock"
+exec 200>"$LOCK_FILE"
+if ! flock -n -x 200 2>/dev/null; then
+  echo "Scope ${SCOPE_ID:-all} locked by another process" >&2; exit 0
+fi
+trap 'rm -f "$LOCK_FILE" 2>/dev/null' EXIT
+
+SOURCE_DIR="$SCOPE_PROJECT_DIR/scopes/$SOURCE_STATUS"
+TARGET_DIR="$SCOPE_PROJECT_DIR/scopes/$TARGET_STATUS"
+
+# ─── Resolve session UUID ───
+if [ -z "$SESSION_UUID" ]; then
+  SESSION_UUID=$("$SCRIPT_DIR/get-session-id.sh" 2>/dev/null || true)
+fi
+
+# ─── Find matching scopes ───
+SCOPES_TO_TRANSITION=""
+
+if [ -n "$SCOPE_ID" ]; then
+  # Specific scope requested
+  SCOPE_FILE=$(find_scope_by_id "$SCOPE_ID")
+  if [ -n "$SCOPE_FILE" ]; then
+    FILE_STATUS=$(get_frontmatter "$SCOPE_FILE" "status")
+    if [ "$FILE_STATUS" = "$SOURCE_STATUS" ]; then
+      SCOPES_TO_TRANSITION="$SCOPE_FILE"
+    fi
+  fi
+else
+  # Find all scopes in source directory with matching status
+  SCOPES_TO_TRANSITION=$(find_scopes_by_status "$SOURCE_STATUS" "$SOURCE_DIR" 2>/dev/null || true)
+fi
+
+if [ -z "$SCOPES_TO_TRANSITION" ]; then
+  exit 0
+fi
+
+# ─── Transition each scope ───
+mkdir -p "$TARGET_DIR"
+TRANSITIONED=0
+TODAY=$(date +%Y-%m-%d)
+
+for scope_file in $SCOPES_TO_TRANSITION; do
+  [ -f "$scope_file" ] || continue
+  FILENAME=$(basename "$scope_file")
+  SCOPE_TITLE=$(get_frontmatter "$scope_file" "title")
+  SCOPE_NUM=$(get_frontmatter "$scope_file" "id")
+
+  # 1. Update status in frontmatter
+  set_frontmatter "$scope_file" "status" "$TARGET_STATUS"
+
+  # 2. Update the date
+  set_frontmatter "$scope_file" "updated" "$TODAY"
+
+  # 2b. Record baseCommit when entering implementing
+  if [ "$TARGET_STATUS" = "implementing" ]; then
+    BASE_SHA=$(git rev-parse HEAD 2>/dev/null)
+    [ -n "$BASE_SHA" ] && set_frontmatter "$scope_file" "baseCommit" "$BASE_SHA"
+  fi
+
+  # 3. Record session UUID if available
+  if [ -n "$SESSION_UUID" ] && [ -n "$SESSION_KEY" ]; then
+    append_session_uuid "$scope_file" "$SESSION_KEY" "$SESSION_UUID"
+  fi
+
+  # 4. Move file to target directory (scopes are gitignored, use plain mv)
+  mv "$scope_file" "$TARGET_DIR/$FILENAME"
+
+  # 5. Print summary
+  echo "   Scope $SCOPE_NUM ($FILENAME): $SOURCE_STATUS → $TARGET_STATUS"
+  TRANSITIONED=$((TRANSITIONED + 1))
+done
+
+if [ "$TRANSITIONED" -gt 0 ]; then
+  echo "   Transitioned $TRANSITIONED scope(s) $SOURCE_STATUS → $TARGET_STATUS"
+  # Invalidate active scope cache since status changed
+  invalidate_active_scope_cache
+fi

package/templates/hooks/session-enforcer.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# session-enforcer.sh — PreToolUse:Edit|Write hook
+#
+# Hard-blocks scope status transitions when the CURRENT session's UUID
+# is not recorded in the scope's sessions.<requiredKey> array.
+#
+# Handles both Edit (old_string/new_string) and Write (full content) tools.
+# Gracefully allows legacy scopes that don't have a sessions: block at all.
+set -e
+
+INPUT=$(cat)
+# Validate JSON input
+echo "$INPUT" | jq empty 2>/dev/null || exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Extract the file being edited/written
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+[ -z "$FILE_PATH" ] && exit 0
+
+# Only enforce on scope files (bash case * matches / in patterns)
+case "$FILE_PATH" in
+  */scopes/*.md) ;;
+  *) exit 0 ;;
+esac
+
+# ─── Determine tool type and extract statuses ───
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "Edit"')
+
+if [ "$TOOL_NAME" = "Write" ]; then
+  # Write tool: compare existing file on disk vs new content
+  if [ ! -f "$FILE_PATH" ]; then
+    # New file creation — no status transition to enforce
+    exit 0
+  fi
+  OLD_STATUS=$(sed -n '/^---$/,/^---$/p' "$FILE_PATH" | grep -oE '^status:\s*\S+' | head -1 | sed 's/status:[[:space:]]*//')
+  NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty')
+  [ -z "$NEW_CONTENT" ] && exit 0
+  TARGET_STATUS=$(echo "$NEW_CONTENT" | sed -n '/^---$/,/^---$/p' | grep -oE '^status:\s*\S+' | head -1 | sed 's/status:[[:space:]]*//')
+else
+  # Edit tool: compare old_string vs new_string
+  NEW_STRING=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty')
+  [ -z "$NEW_STRING" ] && exit 0
+  TARGET_STATUS=$(echo "$NEW_STRING" | grep -oE 'status:\s*\S+' | head -1 | sed 's/status:[[:space:]]*//')
+  OLD_STRING=$(echo "$INPUT" | jq -r '.tool_input.old_string // empty')
+  OLD_STATUS=$(echo "$OLD_STRING" | grep -oE 'status:\s*\S+' | head -1 | sed 's/status:[[:space:]]*//')
+fi
+
+# No status in the edit/write — not a status transition
+[ -z "$TARGET_STATUS" ] && exit 0
+
+# If status isn't changing, allow the edit
+[ "$TARGET_STATUS" = "$OLD_STATUS" ] && exit 0
+
+# ─── Map target status to required session key ───
+# This matrix matches WHO actually makes each transition:
+#   - createScope: /scope-create → planning
+#   - reviewScope: /scope-pre-review → backlog
+#   - implementScope: /scope-implement → implementing
+#   - verifyScope: /scope-post-review → review (different session required)
+#   - commit: /git-commit → completed
+#   - prDev: /git-dev → dev
+#   - pushToStaging: /git-staging → staging
+#   - pushToProduction: /git-production → production
+# ─── Source workflow manifest for edge-based session key lookup ───
+MANIFEST_FILE="${PROJECT_DIR}/.claude/config/workflow-manifest.sh"
+REQUIRED_KEY=""
+
+if [ -f "$MANIFEST_FILE" ]; then
+  source "$MANIFEST_FILE"
+  # Look up session key from WORKFLOW_EDGES: "from:to:sessionKey"
+  for edge_entry in "${WORKFLOW_EDGES[@]}"; do
+    IFS=':' read -r _from edge_to edge_skey <<< "$edge_entry"
+    if [ "$edge_to" = "$TARGET_STATUS" ] && [ -n "$edge_skey" ]; then
+      REQUIRED_KEY="$edge_skey"
+      break
+    fi
+  done
+  # No session key for this status — not enforced
+  [ -z "$REQUIRED_KEY" ] && exit 0
+else
+  # Fallback: hardcoded keys (don't silently disable enforcement)
+  case "$TARGET_STATUS" in
+    planning)                   REQUIRED_KEY="createScope" ;;
+    backlog)                    REQUIRED_KEY="reviewScope" ;;
+    implementing)               REQUIRED_KEY="implementScope" ;;
+    review)                     REQUIRED_KEY="reviewGate" ;;
+    completed)                  REQUIRED_KEY="commit" ;;
+    dev)                        REQUIRED_KEY="prDev" ;;
+    staging)                    REQUIRED_KEY="pushToStaging" ;;
+    production)                 REQUIRED_KEY="pushToProduction" ;;
+    main)                       REQUIRED_KEY="pushToMain" ;;
+    *) exit 0 ;;
+  esac
+fi
+
+# Get current session ID from hook stdin
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+if [ -z "$SESSION_ID" ]; then
+  # If we can't identify the session, allow (graceful degradation)
+  exit 0
+fi
+
+# ─── Record session UUID on scope for this transition ───
+# This ensures the UUID is present even for direct Edit transitions
+# (scope-lifecycle-gate.sh only records on Bash/git commands)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/scope-helpers.sh" 2>/dev/null || true
+if [ -f "$FILE_PATH" ] && type append_session_uuid &>/dev/null; then
+  append_session_uuid "$FILE_PATH" "$REQUIRED_KEY" "$SESSION_ID"
+fi
+
+# ─── Read scope file and check sessions block ───
+# For Write tool, check the FILE ON DISK (sessions were written by the
+# scope-lifecycle-gate hook before this call). For Edit tool, also check the file on disk.
+CHECK_FILE="$FILE_PATH"
+if [ ! -f "$CHECK_FILE" ]; then
+  exit 0
+fi
+
+# Check if sessions: block exists at all in frontmatter
+FRONTMATTER=$(sed -n '/^---$/,/^---$/p' "$CHECK_FILE")
+if ! echo "$FRONTMATTER" | grep -q '^sessions:'; then
+  # Legacy scope without sessions field — allow (backwards compatible)
+  exit 0
+fi
+
+# Look for the specific session key (handles both 2-space and 4-space indent)
+SESSIONS_LINE=$(echo "$FRONTMATTER" | grep "^[[:space:]]*$REQUIRED_KEY:" | head -1)
+
+if [ -z "$SESSIONS_LINE" ]; then
+  # sessions: block exists but this key is missing — session not recorded
+  echo "MUST_BLOCK: Session $SESSION_ID not found in sessions.$REQUIRED_KEY. The scope-lifecycle-gate hook should have recorded this — check .claude/hooks/scope-lifecycle-gate.sh. Format: sessions use inline YAML arrays, e.g. $REQUIRED_KEY: [$SESSION_ID]" >&2
+  exit 2
+fi
+
+# Check if our UUID appears in the line (fixed-string match, not regex)
+if echo "$SESSIONS_LINE" | grep -qF "$SESSION_ID"; then
+  exit 0
+fi
+
+echo "MUST_BLOCK: Session $SESSION_ID not found in sessions.$REQUIRED_KEY. The scope-lifecycle-gate hook should have recorded this — check .claude/hooks/scope-lifecycle-gate.sh. Format: sessions use inline YAML arrays — append UUID to existing array, e.g. $REQUIRED_KEY: [existing-uuid, $SESSION_ID]" >&2
+exit 2

package/templates/hooks/time-tracker.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# time-tracker.sh — Emit scope status transition events to Orbital dashboard
+# Trigger: PostToolUse:Edit (scope status changes)
+# 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
+
+# Detect status transitions
+STATUS=""
+echo "$NEW_STRING" | grep -qiE "status:.*planning" && STATUS="planning"
+echo "$NEW_STRING" | grep -qiE "status:.*backlog" && STATUS="backlog"
+echo "$NEW_STRING" | grep -qiE "status:.*implementing" && STATUS="implementing"
+echo "$NEW_STRING" | grep -qiE "status:.*complete" && STATUS="complete"
+echo "$NEW_STRING" | grep -qiE "🔄.*In Progress" && STATUS="phase_started"
+echo "$NEW_STRING" | grep -qiE "✅.*Done" && STATUS="phase_done"
+[ -z "$STATUS" ] && exit 0
+
+SCOPE_NAME=$(basename "$FILE_PATH" .md)
+
+# Emit SCOPE_TRANSITION event to Orbital dashboard
+HOOK_DIR="$(dirname "$0")"
+DATA=$(jq -n --arg from "" --arg to "$STATUS" --arg scope_name "$SCOPE_NAME" '{from: $from, to: $to, scope_name: $scope_name}')
+"$HOOK_DIR/orbital-emit.sh" SCOPE_TRANSITION "$DATA"
+
+exit 0

package/templates/lessons-learned.md

@@ -0,0 +1,15 @@
+# Lessons Learned
+
+Record insights from debugging sessions, incidents, and post-mortems.
+
+## Format
+
+### YYYY-MM-DD: Title
+**Context**: What happened
+**Root cause**: Why it happened
+**Lesson**: What to do differently
+**Prevention**: How to avoid in future
+
+---
+
+<!-- Add entries above this line -->

package/templates/orbital.config.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://orbital-command.dev/schemas/orbital.config.schema.json",
+  "projectName": "My Project",
+  "scopesDir": "scopes",
+  "eventsDir": ".claude/orbital-events",
+  "dbDir": ".claude/orbital",
+  "configDir": ".claude/config",
+  "serverPort": 4444,
+  "clientPort": 4445,
+  "terminal": {
+    "adapter": "auto",
+    "profilePrefix": "Orbital"
+  },
+  "claude": {
+    "executable": "claude",
+    "flags": ["--dangerously-skip-permissions"]
+  },
+  "commands": {
+    "typeCheck": null,
+    "lint": null,
+    "build": null,
+    "test": null,
+    "validateTemplates": null,
+    "validateDocs": null,
+    "checkRules": null
+  },
+  "categories": ["feature", "bugfix", "refactor", "infrastructure", "docs"],
+  "agents": [
+    { "id": "attacker", "label": "Attacker", "emoji": "\ud83d\udde1\ufe0f", "color": "#ff1744" },
+    { "id": "chaos", "label": "Chaos", "emoji": "\ud83d\udca5", "color": "#F97316" },
+    { "id": "frontend-designer", "label": "Frontend Designer", "emoji": "\ud83c\udfa8", "color": "#EC4899" },
+    { "id": "architect", "label": "Architect", "emoji": "\ud83c\udfd7\ufe0f", "color": "#536dfe" },
+    { "id": "rules-enforcer", "label": "Rules Enforcer", "emoji": "\ud83d\udccb", "color": "#6B7280" }
+  ]
+}

package/templates/presets/development.json

@@ -0,0 +1,42 @@
+{
+  "name": "Development",
+  "version": 1,
+  "branchingMode": "trunk",
+  "lists": [
+    { "id": "backlog", "label": "Backlog", "order": 0, "group": "planning", "color": "230 99% 67%", "hex": "#536dfe", "hasDirectory": true, "isEntryPoint": true },
+    { "id": "implementing", "label": "Implementing", "order": 1, "group": "development", "color": "40 100% 50%", "hex": "#ffaa00", "hasDirectory": true, "sessionKey": "implementScope", "activeHooks": ["block-commit-implementing"] },
+    { "id": "review", "label": "Review", "order": 2, "group": "development", "color": "263 69% 50%", "hex": "#6b26d9", "hasDirectory": true, "sessionKey": "reviewGate" },
+    { "id": "completed", "label": "Completed", "order": 3, "group": "development", "color": "174 70% 42%", "hex": "#20b6aa", "hasDirectory": true, "sessionKey": "commit" },
+    { "id": "dev", "label": "Dev", "order": 4, "group": "deploy", "color": "197 100% 63%", "hex": "#42c3ff", "hasDirectory": true, "gitBranch": "dev" }
+  ],
+  "edges": [
+    { "from": "backlog", "to": "implementing", "direction": "forward", "command": "/scope-implement {id}", "confirmLevel": "quick", "label": "Start Implementing", "description": "Opens a Claude session running /scope-implement.", "dispatchOnly": true },
+    { "from": "implementing", "to": "review", "direction": "forward", "command": "/scope-post-review {id}", "confirmLevel": "full", "label": "Run Review Gate", "description": "Launches formal review gate.", "dispatchOnly": true },
+    { "from": "review", "to": "completed", "direction": "forward", "command": "/git-commit", "confirmLevel": "full", "label": "Commit", "description": "Commits scope work to feature branch.", "dispatchOnly": true },
+    { "from": "completed", "to": "dev", "direction": "forward", "command": "/git-dev", "confirmLevel": "full", "label": "Merge to Dev", "description": "Merges feature branch into dev.", "dispatchOnly": true },
+    { "from": "review", "to": "implementing", "direction": "backward", "command": null, "confirmLevel": "quick", "label": "Back to Implementing", "description": "Re-opens implementation to address review findings.", "dispatchOnly": false },
+    { "from": "completed", "to": "implementing", "direction": "backward", "command": null, "confirmLevel": "quick", "label": "Back to Implementing", "description": "Re-opens implementation to fix issues.", "dispatchOnly": false },
+    { "from": "implementing", "to": "backlog", "direction": "backward", "command": null, "confirmLevel": "quick", "label": "Back to Backlog", "description": "Returns scope to backlog.", "dispatchOnly": false, "humanOnly": true }
+  ],
+  "hooks": [
+    {
+      "id": "block-commit-implementing",
+      "label": "Block Commit (Implementing)",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/block-push.sh",
+      "blocking": true,
+      "description": "Blocks git commit/add during implementing sessions",
+      "category": "guard"
+    }
+  ],
+  "groups": [
+    { "id": "planning", "label": "Planning", "order": 0 },
+    { "id": "development", "label": "Development", "order": 1 },
+    { "id": "deploy", "label": "Deploy", "order": 2 }
+  ],
+  "eventInference": [],
+  "allowedCommandPrefixes": ["/scope-", "/git-", "/test-", "/session-"],
+  "terminalStatuses": ["dev"],
+  "commitBranchPatterns": "^(dev|feat/|fix/|scope/|chore/)"
+}