orbital-command 0.2.0 → 0.3.0

package/shared/workflow-normalizer.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest';
+import { WorkflowNormalizer, PHASE_COLUMNS, allEnginesMatch } from './workflow-normalizer.js';
+import { WorkflowEngine } from './workflow-engine.js';
+import { DEFAULT_CONFIG, MINIMAL_CONFIG } from './__fixtures__/workflow-configs.js';
+
+describe('PHASE_COLUMNS', () => {
+  it('has 4 entries in correct order', () => {
+    expect(PHASE_COLUMNS).toHaveLength(4);
+    expect(PHASE_COLUMNS.map(c => c.phase)).toEqual(['queued', 'active', 'review', 'shipped']);
+    expect(PHASE_COLUMNS.map(c => c.order)).toEqual([0, 1, 2, 3]);
+  });
+});
+
+describe('WorkflowNormalizer', () => {
+  const engine = new WorkflowEngine(DEFAULT_CONFIG);
+  const normalizer = new WorkflowNormalizer(engine);
+
+  describe('phase inference with default config', () => {
+    it('entry point (icebox) maps to queued', () => {
+      expect(normalizer.getPhase('icebox')).toBe('queued');
+    });
+
+    it('planning group list maps to queued', () => {
+      expect(normalizer.getPhase('planning')).toBe('queued');
+    });
+
+    it('backlog (planning group with reviewScope session) maps to queued', () => {
+      expect(normalizer.getPhase('backlog')).toBe('queued');
+    });
+
+    it('implementing (sessionKey includes "implement") maps to active', () => {
+      expect(normalizer.getPhase('implementing')).toBe('active');
+    });
+
+    it('review (sessionKey includes "review") maps to review', () => {
+      expect(normalizer.getPhase('review')).toBe('review');
+    });
+
+    it('completed (sessionKey "commit") maps to review', () => {
+      expect(normalizer.getPhase('completed')).toBe('review');
+    });
+
+    it('main (terminal status with gitBranch) maps to shipped', () => {
+      expect(normalizer.getPhase('main')).toBe('shipped');
+    });
+  });
+
+  describe('getPhase()', () => {
+    it('returns queued for unknown list ID (default)', () => {
+      expect(normalizer.getPhase('nonexistent')).toBe('queued');
+    });
+  });
+
+  describe('getListsForPhase()', () => {
+    it('returns all lists for a given phase', () => {
+      const queued = normalizer.getListsForPhase('queued');
+      expect(queued.length).toBeGreaterThan(0);
+      for (const list of queued) {
+        expect(normalizer.getPhase(list.id)).toBe('queued');
+      }
+    });
+
+    it('shipped phase includes main', () => {
+      const shipped = normalizer.getListsForPhase('shipped');
+      expect(shipped.some(l => l.id === 'main')).toBe(true);
+    });
+  });
+
+  describe('getPhaseMap()', () => {
+    it('returns a map covering all lists', () => {
+      const map = normalizer.getPhaseMap();
+      const lists = engine.getLists();
+      for (const list of lists) {
+        expect(map.has(list.id)).toBe(true);
+      }
+    });
+  });
+
+  describe('resolveNormalizedTransition()', () => {
+    it('returns edges from a list to a target phase', () => {
+      // icebox → planning is forward, planning maps to queued
+      const edges = normalizer.resolveNormalizedTransition('icebox', 'queued');
+      expect(edges.length).toBeGreaterThan(0);
+      expect(edges[0].from).toBe('icebox');
+    });
+
+    it('returns empty when no edges match', () => {
+      // icebox has no edge to any shipped-phase list
+      const edges = normalizer.resolveNormalizedTransition('icebox', 'shipped');
+      expect(edges).toEqual([]);
+    });
+  });
+});
+
+describe('allEnginesMatch()', () => {
+  it('returns true for empty array', () => {
+    expect(allEnginesMatch([])).toBe(true);
+  });
+
+  it('returns true for single engine', () => {
+    expect(allEnginesMatch([new WorkflowEngine(DEFAULT_CONFIG)])).toBe(true);
+  });
+
+  it('returns true when all engines have same lists', () => {
+    const engines = [
+      new WorkflowEngine(DEFAULT_CONFIG),
+      new WorkflowEngine(DEFAULT_CONFIG),
+    ];
+    expect(allEnginesMatch(engines)).toBe(true);
+  });
+
+  it('returns false when engines differ', () => {
+    const engines = [
+      new WorkflowEngine(DEFAULT_CONFIG),
+      new WorkflowEngine(MINIMAL_CONFIG),
+    ];
+    expect(allEnginesMatch(engines)).toBe(false);
+  });
+});

package/shared/workflow-normalizer.ts

@@ -0,0 +1,118 @@
+import type { Phase, WorkflowList, WorkflowEdge } from './workflow-config.js';
+export type { Phase } from './workflow-config.js';
+import type { WorkflowEngine } from './workflow-engine.js';
+
+// ─── Phase Mapping ──────────────────────────────────────────
+
+/** Infer a list's semantic phase from its properties. */
+function inferPhase(list: WorkflowList, terminalStatuses: string[]): Phase {
+  // Explicit phase takes priority
+  if (list.phase) return list.phase;
+
+  // Terminal statuses or lists with a git branch → shipped
+  if (terminalStatuses.includes(list.id) || list.gitBranch) return 'shipped';
+
+  // Entry points and planning group → queued
+  if (list.isEntryPoint) return 'queued';
+  if (list.group === 'planning') return 'queued';
+
+  // Session key inference
+  if (list.sessionKey) {
+    if (list.sessionKey.toLowerCase().includes('implement')) return 'active';
+    if (list.sessionKey.toLowerCase().includes('review') ||
+        list.sessionKey.toLowerCase().includes('gate') ||
+        list.sessionKey.toLowerCase().includes('commit') ||
+        list.sessionKey.toLowerCase().includes('verify')) return 'review';
+    if (list.sessionKey.toLowerCase().includes('push') ||
+        list.sessionKey.toLowerCase().includes('deploy')) return 'shipped';
+    if (list.sessionKey.toLowerCase().includes('create') ||
+        list.sessionKey.toLowerCase().includes('scope')) return 'queued';
+  }
+
+  // Group-based inference
+  if (list.group === 'development') {
+    // Lists earlier in development → active, later → review
+    return list.order <= 3 ? 'active' : 'review';
+  }
+  if (list.group === 'active') return 'active';
+  if (list.group?.startsWith('deploy')) return 'shipped';
+  if (list.group === 'main') return 'shipped';
+
+  // Default: use order-based heuristic
+  return 'queued';
+}
+
+// ─── Normalizer ─────────────────────────────────────────────
+
+/** Phase column definition for the All Projects board. */
+export interface PhaseColumn {
+  phase: Phase;
+  label: string;
+  order: number;
+}
+
+/** The four normalized columns. */
+export const PHASE_COLUMNS: readonly PhaseColumn[] = [
+  { phase: 'queued', label: 'Queued', order: 0 },
+  { phase: 'active', label: 'Active', order: 1 },
+  { phase: 'review', label: 'Review', order: 2 },
+  { phase: 'shipped', label: 'Shipped', order: 3 },
+] as const;
+
+/**
+ * Maps workflow lists to semantic phases for the All Projects board.
+ *
+ * Each WorkflowEngine's lists get mapped to one of four phases.
+ * When all projects share the same workflow, the board shows full columns.
+ * When workflows differ, the board uses these normalized phases.
+ */
+export class WorkflowNormalizer {
+  private phaseMap: Map<string, Phase>;
+
+  constructor(private engine: WorkflowEngine) {
+    this.phaseMap = new Map();
+    const lists = engine.getLists();
+    const terminalStatuses = engine.getConfig().terminalStatuses ?? [];
+
+    for (const list of lists) {
+      this.phaseMap.set(list.id, inferPhase(list, terminalStatuses));
+    }
+  }
+
+  /** Get the phase for a list/status ID. */
+  getPhase(listId: string): Phase {
+    return this.phaseMap.get(listId) ?? 'queued';
+  }
+
+  /** Get all lists that map to a given phase. */
+  getListsForPhase(phase: Phase): WorkflowList[] {
+    return this.engine.getLists().filter(l => this.getPhase(l.id) === phase);
+  }
+
+  /** Get the full phase map. */
+  getPhaseMap(): ReadonlyMap<string, Phase> {
+    return this.phaseMap;
+  }
+
+  /**
+   * Find valid workflow transitions from `currentListId` whose target
+   * maps to `targetPhase`. Used for DnD in the All Projects phase view.
+   */
+  resolveNormalizedTransition(currentListId: string, targetPhase: Phase): WorkflowEdge[] {
+    const config = this.engine.getConfig();
+    return config.edges.filter(edge =>
+      edge.from === currentListId && this.getPhase(edge.to) === targetPhase
+    );
+  }
+}
+
+/**
+ * Check if all engines share the same workflow (same list IDs in same order).
+ * When true, the All Projects board can show full columns instead of phases.
+ */
+export function allEnginesMatch(engines: WorkflowEngine[]): boolean {
+  if (engines.length <= 1) return true;
+
+  const firstLists = engines[0].getLists().map(l => l.id).join(',');
+  return engines.every(e => e.getLists().map(l => l.id).join(',') === firstLists);
+}

package/templates/hooks/end-session.sh

@@ -12,7 +12,9 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PID="$PPID"
 
 # Emit session end event to Orbital dashboard (non-blocking)
-SESSION_DATA="{\"pid\":$PID"
+# normal_exit=true tells the server this was a clean shutdown, so dispatches
+# should resolve as "completed" rather than "abandoned".
+SESSION_DATA="{\"pid\":$PID,\"normal_exit\":true"
 # 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\""

package/templates/hooks/orbital-emit.sh

@@ -69,11 +69,11 @@ if [ -n "$SCOPE_ID" ]; then
 fi
 if [ -n "$AGENT" ]; then
   JQ_ARGS+=(--arg agent "$AGENT")
-  JQ_EXPR=$(echo "$JQ_EXPR" | sed 's/}$/, agent: $agent}/')
+  JQ_EXPR="${JQ_EXPR%\}}, 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}/')
+  JQ_EXPR="${JQ_EXPR%\}}, session_id: \$session_id}"
 fi
 
 jq -n "${JQ_ARGS[@]}" "$JQ_EXPR" > "$EVENT_FILE"

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

@@ -50,16 +50,16 @@ else
   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}/')
+  [ -n "$COMMIT_SHA" ] && JQ_ARGS+=(--arg commit_sha "$COMMIT_SHA") && JQ_EXPR="${JQ_EXPR%\}}, commit_sha: \$commit_sha}"
+  [ -n "$BRANCH" ] && JQ_ARGS+=(--arg branch "$BRANCH") && JQ_EXPR="${JQ_EXPR%\}}, branch: \$branch}"
+  [ -n "$PR_NUMBER" ] && JQ_ARGS+=(--argjson pr_number "$PR_NUMBER") && JQ_EXPR="${JQ_EXPR%\}}, 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}/')
+  [ -n "$HEALTH_URL" ] && JQ_ARGS+=(--arg health_check_url "$HEALTH_URL") && JQ_EXPR="${JQ_EXPR%\}}, health_check_url: \$health_check_url}"
 
   PAYLOAD=$(jq -n "${JQ_ARGS[@]}" "$JQ_EXPR")
 

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

@@ -25,10 +25,10 @@ SCOPE_ID="${ORBITAL_GATE_SCOPE_ID:-null}"
 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}/')
+[ "$SCOPE_ID" != "null" ] && JQ_ARGS+=(--argjson scope_id "$SCOPE_ID") && JQ_EXPR="${JQ_EXPR%\}}, scope_id: \$scope_id}"
+[ "$DURATION_MS" != "null" ] && JQ_ARGS+=(--argjson duration_ms "$DURATION_MS") && JQ_EXPR="${JQ_EXPR%\}}, duration_ms: \$duration_ms}"
+[ -n "$COMMIT_SHA" ] && JQ_ARGS+=(--arg commit_sha "$COMMIT_SHA") && JQ_EXPR="${JQ_EXPR%\}}, commit_sha: \$commit_sha}"
+[ -n "$DETAILS" ] && JQ_ARGS+=(--arg details "$DETAILS") && JQ_EXPR="${JQ_EXPR%\}}, details: \$details}"
 
 PAYLOAD=$(jq -n "${JQ_ARGS[@]}" "$JQ_EXPR")
 

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

@@ -15,7 +15,7 @@ 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"
+ORBITAL_API="${ORBITAL_URL:-http://localhost:4444}/api/orbital"
 
 # Try the REST API first (fastest, real-time)
 if command -v curl &>/dev/null; then

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

@@ -1,8 +1,8 @@
 #!/bin/bash
 #
-# scope-create-cleanup.sh — PostToolUse:Write cleanup
+# scope-create-cleanup.sh — PostToolUse:Write|Edit cleanup
 #
-# After a successful Write, checks if the written file is a scope document.
+# After a successful Write or Edit, checks if the file is a scope document.
 # If so, removes the .scope-create-session marker to lift the write gate.
 #
 set -e

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

@@ -62,7 +62,6 @@ VIOLATION_DATA=$(jq -n --arg rule "scope-create-gate" --arg file "$FILE_PATH" --
 "$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}"
 

package/templates/hooks/scope-helpers.sh

@@ -176,6 +176,24 @@ append_session_uuid() {
   rm -f "${file}.lock"
 }
 
+# Find icebox file by slug (e.g. "onboarding-flow" matches scopes/icebox/onboarding-flow.md)
+# or legacy scopes/icebox/502-onboarding-flow.md)
+find_scope_by_slug() {
+  local slug="$1"
+  local icebox_dir="$SCOPE_PROJECT_DIR/scopes/icebox"
+  [ -d "$icebox_dir" ] || return 1
+  # Try slug-only file first
+  if [ -f "$icebox_dir/${slug}.md" ]; then
+    echo "$icebox_dir/${slug}.md"
+    return 0
+  fi
+  # Fall back to legacy numeric-prefixed: {NNN}-{slug}.md
+  for f in "$icebox_dir"/*-"${slug}.md"; do
+    [ -f "$f" ] && echo "$f" && return 0
+  done
+  return 1
+}
+
 # Find scope file by numeric ID across all directories
 find_scope_by_id() {
   local id="$1"

package/templates/hooks/scope-prepare.sh

@@ -5,7 +5,7 @@
 # session recording, and gate cleanup into a single Bash call.
 #
 # Modes:
-#   --promote ID     Promote icebox idea to planning (renumber + move + scaffold)
+#   --promote SLUG|ID  Promote icebox idea to planning (renumber + move + scaffold)
 #   --scaffold ID    Apply template to existing planning scope
 #   --new            Create brand new scope
 #
@@ -13,6 +13,7 @@
 #   --title "..."    Scope title (required for --new)
 #   --desc "..."     Description / problem statement
 #   --category "..." Category tag (default: TBD)
+#   --effort "..."   Effort estimate (default: TBD)
 #
 # Output: JSON to stdout
 # Errors: to stderr
@@ -28,6 +29,7 @@ SOURCE_ID=""
 TITLE=""
 DESCRIPTION=""
 CATEGORY="TBD"
+EFFORT="TBD"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -37,12 +39,13 @@ while [[ $# -gt 0 ]]; do
     --title)     TITLE="$2"; shift 2 ;;
     --desc)      DESCRIPTION="$2"; shift 2 ;;
     --category)  CATEGORY="$2"; shift 2 ;;
+    --effort)    EFFORT="$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
+  echo "Usage: scope-prepare.sh --promote SLUG|ID | --scaffold ID | --new --title \"...\"" >&2
   exit 1
 fi
 
@@ -77,13 +80,18 @@ fi
 
 # ─── Resolve source file + extract metadata ─────────────────────
 OLD_FILE=""
+FULL_BODY=""
 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")
+    # Try slug-based lookup first (new format), fall back to numeric ID (legacy)
+    OLD_FILE=$(find_scope_by_slug "$SOURCE_ID")
+    if [ -z "$OLD_FILE" ] || [ ! -f "$OLD_FILE" ]; then
+      OLD_FILE=$(find_scope_by_id "$SOURCE_ID")
+    fi
     if [ -z "$OLD_FILE" ] || [ ! -f "$OLD_FILE" ]; then
       echo "Error: Scope $SOURCE_ID not found" >&2
       exit 2
@@ -92,13 +100,18 @@ case "$MODE" in
     # 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 ---)
+    # Extract full body (everything after frontmatter closing ---) for template injection
+    FULL_BODY=$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$OLD_FILE")
+    # Short description (first non-empty line) for JSON output
     if [ -z "$DESCRIPTION" ]; then
-      DESCRIPTION=$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$OLD_FILE" | head -20 | sed '/^$/d' | head -5)
+      DESCRIPTION=$(printf '%s' "$FULL_BODY" | sed '/^$/d' | head -1)
     fi
     # Get category if set
     orig_cat=$(get_frontmatter "$OLD_FILE" "category")
     [ -n "$orig_cat" ] && [ "$orig_cat" != "TBD" ] && CATEGORY="$orig_cat"
+    # Get effort if set
+    orig_effort=$(get_frontmatter "$OLD_FILE" "effort_estimate")
+    [ -n "$orig_effort" ] && [ "$orig_effort" != "TBD" ] && EFFORT="$orig_effort"
     ;;
 
   scaffold)
@@ -110,11 +123,15 @@ case "$MODE" in
     [ -z "$TITLE" ] && TITLE=$(get_frontmatter "$OLD_FILE" "title")
     orig_created=$(get_frontmatter "$OLD_FILE" "created")
     [ -n "$orig_created" ] && CREATED_DATE="$orig_created"
+    # Extract full body for template injection
+    FULL_BODY=$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$OLD_FILE")
     if [ -z "$DESCRIPTION" ]; then
-      DESCRIPTION=$(awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$OLD_FILE" | head -20 | sed '/^$/d' | head -5)
+      DESCRIPTION=$(printf '%s' "$FULL_BODY" | sed '/^$/d' | head -1)
     fi
     orig_cat=$(get_frontmatter "$OLD_FILE" "category")
     [ -n "$orig_cat" ] && [ "$orig_cat" != "TBD" ] && CATEGORY="$orig_cat"
+    orig_effort=$(get_frontmatter "$OLD_FILE" "effort_estimate")
+    [ -n "$orig_effort" ] && [ "$orig_effort" != "TBD" ] && EFFORT="$orig_effort"
     ;;
 esac
 
@@ -130,6 +147,8 @@ compute_next_id() {
         local num
         num=$(basename "$f" | grep -oE '^[0-9]+' | sed 's/^0*//')
         [ -z "$num" ] && continue
+        # Skip legacy icebox-origin IDs (500+) to prevent namespace pollution
+        [ "$num" -ge 500 ] 2>/dev/null && continue
         [ "$num" -gt "$max_id" ] 2>/dev/null && max_id=$num
       done
     done
@@ -199,6 +218,7 @@ sed \
   -e "s/^id: NNN/id: $PADDED_ID/" \
   -e "s/^title: \"Scope Title\"/title: \"$ESCAPED_TITLE\"/" \
   -e "s/^category: \"TBD\".*/category: \"$CATEGORY\"/" \
+  -e "s/^effort_estimate: \"TBD\".*/effort_estimate: \"$EFFORT\"/" \
   -e "s/^created: YYYY-MM-DD/created: $CREATED_DATE/" \
   -e "s/^updated: YYYY-MM-DD/updated: $NOW_DATE/" \
   -e "s/^sessions: {}.*/$SESSIONS_REPLACEMENT/" \
@@ -209,6 +229,29 @@ sed \
   -e "s/\[What prompted this exploration\]/$ESCAPED_DESC/" \
   "$TEMPLATE" > "$NEW_FILE"
 
+# ─── Inject full body into Overview section ────────────────────
+# When promoting/scaffolding, preserve the original idea body in the
+# SPECIFICATION > Overview section instead of losing it to the template.
+if [ -n "$FULL_BODY" ] && [ "$(printf '%s' "$FULL_BODY" | sed '/^[[:space:]]*$/d' | wc -l)" -gt 0 ]; then
+  BODY_TMP=$(mktemp)
+  printf '%s\n' "$FULL_BODY" > "$BODY_TMP"
+
+  awk -v bodyfile="$BODY_TMP" '
+    /^### Overview/ {
+      print
+      print ""
+      while ((getline line < bodyfile) > 0) print line
+      # Skip the original placeholder lines (blank + [Problem statement...])
+      getline  # blank line after ### Overview
+      getline  # [Problem statement...] line
+      next
+    }
+    { print }
+  ' "$NEW_FILE" > "${NEW_FILE}.tmp" && mv "${NEW_FILE}.tmp" "$NEW_FILE"
+
+  rm -f "$BODY_TMP"
+fi
+
 # ─── Cleanup old file (promote only) ────────────────────────────
 if [ "$MODE" = "promote" ] && [ -n "$OLD_FILE" ] && [ "$OLD_FILE" != "$NEW_FILE" ]; then
   rm -f "$OLD_FILE"
@@ -223,22 +266,34 @@ rm -f "$MARKER"
   "{\"scope_file\":\"$NEW_FILE\",\"id\":$SCOPE_ID,\"mode\":\"$MODE\"}" \
   --scope "$SCOPE_ID" --session "$SESSION_ID" 2>/dev/null &
 
+# ─── Read available categories from config ─────────────────────
+AVAILABLE_CATEGORIES=""
+CONFIG_FILE="$SCOPE_PROJECT_DIR/.claude/orbital.config.json"
+if command -v jq >/dev/null 2>&1 && [ -f "$CONFIG_FILE" ]; then
+  AVAILABLE_CATEGORIES=$(jq -r '.categories // [] | join(", ")' "$CONFIG_FILE" 2>/dev/null)
+fi
+EFFORT_BUCKETS="<1H, 1-4H, 4H+"
+
 # ─── 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' \
+printf '{"id":"%s","path":"%s","title":"%s","description":"%s","session_id":"%s","category":"%s","effort":"%s","mode":"%s","available_categories":"%s","effort_buckets":"%s"}\n' \
   "$PADDED_ID" \
   "$REL_PATH" \
   "$(printf '%s' "$TITLE" | sed 's/"/\\"/g')" \
-  "$(printf '%s' "$DESCRIPTION" | head -1 | sed 's/"/\\"/g')" \
+  "$(printf '%s' "$DESCRIPTION" | sed 's/"/\\"/g')" \
   "$SESSION_ID" \
   "$CATEGORY" \
-  "$MODE"
+  "$EFFORT" \
+  "$MODE" \
+  "$AVAILABLE_CATEGORIES" \
+  "$EFFORT_BUCKETS"
 
 # 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 document scaffolded. Write gate lifted." >&2
+echo "Now proceed to Step 2: categorize and estimate effort." >&2
+echo "After specification is complete, STOP. Implementation is a separate session:" >&2
 echo "  /scope-implement $PADDED_ID" >&2

package/templates/migrations/renames.json

@@ -0,0 +1 @@
+{}

package/templates/orbital.config.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://orbital-command.dev/schemas/orbital.config.schema.json",
+  "$schema": "https://raw.githubusercontent.com/SakaraLabs/orbital-command/main/schemas/orbital.config.schema.json",
   "projectName": "My Project",
   "scopesDir": "scopes",
   "eventsDir": ".claude/orbital-events",
@@ -31,5 +31,10 @@
     { "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" }
-  ]
+  ],
+  "telemetry": {
+    "enabled": true,
+    "url": "https://orbital-telemetry.mike-calle.workers.dev/ingest/a7f3x9k2m1",
+    "headers": {}
+  }
 }

package/templates/settings-hooks.json

@@ -76,7 +76,7 @@
         ]
       },
       {
-        "matcher": "Write",
+        "matcher": "Write|Edit",
         "hooks": [
           { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scope-create-cleanup.sh", "_orbital": true }
         ]

package/templates/skills/git-commit/SKILL.md

@@ -40,8 +40,7 @@ Find scopes in `scopes/review/` that have a passing verdict:
 1. List files in `scopes/review/*.md`
 2. For each, extract the scope number and check `.claude/review-verdicts/{NNN}.json`
 3. If verdict exists and `verdict === "PASS"`:
-   - `mv scopes/review/{file} scopes/completed/`
-   - Update frontmatter: `status: completed`
+   - Transition: `bash .claude/hooks/scope-transition.sh --from review --to completed --scope {NNN}`
    - Update DASHBOARD: `📦 **Status**: Committed`
 4. If scope is in `scopes/review/` with **no** passing verdict:
    - Warn: "Scope {NNN} is in review but hasn't passed the review gate."
@@ -59,14 +58,20 @@ git commit -m "type(scope): description"
 - Follow conventional commit format
 - Do NOT push or create PRs — those are separate skills
 
-### Step 4: Signal Completion
+### Step 4: Signal Completion (REQUIRED)
 
-If working on a dispatched scope, emit the agent completion event:
+**Always emit after a successful commit** — this is not optional:
 
 ```bash
+# With a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"save"}' --scope "{NNN}"
+
+# Without a scope (general commit):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"save"}'
 ```
 
+The `--scope` flag is optional. Omit it when committing work that isn't tied to a specific scope.
+
 ## Quick Reference
 
 | User Says | Action |

package/templates/skills/git-dev/SKILL.md

@@ -42,8 +42,7 @@ git status --porcelain
 
 Find scopes in `scopes/completed/`:
 1. For each scope file in `scopes/completed/*.md`:
-   - `mv scopes/completed/{file} scopes/dev/`
-   - Update frontmatter: `status: dev`
+   - Transition: `bash .claude/hooks/scope-transition.sh --from completed --to dev --scope {NNN}`
    - Update DASHBOARD: `🔀 **Status**: Merged to Dev`
 
 If BATCH_SCOPE_IDS is set, only transition those specific scopes.
@@ -68,10 +67,16 @@ git checkout "$FEATURE_BRANCH"
 
 If merge conflicts occur, resolve them before continuing.
 
-### Step 4: Signal Completion
+### Step 4: Signal Completion (REQUIRED)
+
+**Always emit after a successful merge** — this is not optional:
 
 ```bash
+# With a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_dev"}' --scope "{NNN}"
+
+# Without a scope:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_dev"}'
 ```
 
 ## Output