orbital-command 0.1.0

package/server/watchers/scope-watcher.ts

@@ -0,0 +1,38 @@
+import chokidar, { type FSWatcher } from 'chokidar';
+import path from 'path';
+import type { ScopeService } from '../services/scope-service.js';
+import { createLogger } from '../utils/logger.js';
+
+const log = createLogger('scope');
+
+export function startScopeWatcher(
+  scopesDir: string,
+  scopeService: ScopeService
+): FSWatcher {
+  const watcher = chokidar.watch(scopesDir, {
+    ignored: [/(^|[/\\])\../, /node_modules/, /_template\.md$/],
+    persistent: true,
+    ignoreInitial: true,
+    depth: 2, // scopes/completed/*.md
+  });
+
+  watcher
+    .on('add', (filePath: string) => {
+      if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath)) return;
+      log.info('Scope added', { file: path.basename(filePath) });
+      scopeService.updateFromFile(filePath);
+    })
+    .on('change', (filePath: string) => {
+      if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath)) return;
+      log.debug('Scope changed', { file: path.basename(filePath) });
+      scopeService.updateFromFile(filePath);
+    })
+    .on('unlink', (filePath: string) => {
+      if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath)) return;
+      log.info('Scope removed', { file: path.basename(filePath) });
+      scopeService.removeByFilePath(filePath);
+    })
+    .on('error', (err: unknown) => log.error('Scope watcher error', { error: String(err) }));
+
+  return watcher;
+}

package/shared/api-types.ts

@@ -0,0 +1,20 @@
+// ─── Shared API Types ────────────────────────────────────────
+//
+// Types shared between server and client. Single source of truth for
+// enums/unions that were previously duplicated across layers.
+
+export type SprintStatus = 'assembling' | 'dispatched' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+export type SprintScopeStatus = 'pending' | 'queued' | 'dispatched' | 'in_progress' | 'completed' | 'failed' | 'skipped';
+export type GroupType = 'sprint' | 'batch';
+
+export type GateStatus = 'pass' | 'fail' | 'running' | 'skipped';
+
+export type DeployStatus = 'deploying' | 'healthy' | 'failed' | 'rolled-back';
+export type DeployEnvironment = 'staging' | 'production';
+
+export interface AgentConfig {
+  id: string;
+  label: string;
+  emoji: string;
+  color: string;
+}

package/shared/default-workflow.json

@@ -0,0 +1,616 @@
+{
+  "version": 1,
+  "name": "Default Workflow",
+  "branchingMode": "trunk",
+  "description": "7-list trunk-based workflow with direct push to main",
+  "lists": [
+    {
+      "id": "icebox",
+      "label": "Icebox",
+      "order": 0,
+      "group": "planning",
+      "color": "187 72% 43%",
+      "hex": "#1faabd",
+      "isEntryPoint": true,
+      "hasDirectory": true
+    },
+    {
+      "id": "planning",
+      "label": "Planning",
+      "order": 1,
+      "group": "planning",
+      "color": "231 99% 66%",
+      "hex": "#526cfe",
+      "hasDirectory": true,
+      "sessionKey": "createScope"
+    },
+    {
+      "id": "backlog",
+      "label": "Backlog",
+      "order": 2,
+      "group": "planning",
+      "color": "330 81% 60%",
+      "hex": "#ec4899",
+      "supportsSprint": true,
+      "hasDirectory": true,
+      "sessionKey": "reviewScope"
+    },
+    {
+      "id": "implementing",
+      "label": "Implementing",
+      "order": 3,
+      "group": "development",
+      "color": "0 84% 60%",
+      "hex": "#ef4444",
+      "hasDirectory": true,
+      "sessionKey": "implementScope"
+    },
+    {
+      "id": "review",
+      "label": "Review",
+      "order": 4,
+      "group": "development",
+      "color": "45 93% 58%",
+      "hex": "#eab308",
+      "supportsBatch": true,
+      "hasDirectory": true,
+      "sessionKey": "reviewGate"
+    },
+    {
+      "id": "completed",
+      "label": "Completed",
+      "order": 5,
+      "group": "development",
+      "color": "175 70% 42%",
+      "hex": "#20b6aa",
+      "supportsBatch": true,
+      "hasDirectory": true,
+      "sessionKey": "commit"
+    },
+    {
+      "id": "main",
+      "label": "Main",
+      "order": 6,
+      "group": "main",
+      "color": "153 100% 39%",
+      "hex": "#00c76d",
+      "hasDirectory": true,
+      "gitBranch": "main",
+      "sessionKey": "pushToMain"
+    }
+  ],
+  "edges": [
+    {
+      "from": "icebox",
+      "to": "planning",
+      "direction": "forward",
+      "command": "/scope-create {id}",
+      "confirmLevel": "quick",
+      "label": "Create Scope",
+      "description": "Launches /scope-create with idea context pre-filled.",
+      "dispatchOnly": false,
+      "hooks": ["session-enforcer", "scope-create-gate", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "planning",
+      "to": "backlog",
+      "direction": "forward",
+      "command": "/scope-pre-review {id}",
+      "confirmLevel": "quick",
+      "label": "Team Review",
+      "description": "Runs full agent team review, locks spec, moves to backlog.",
+      "dispatchOnly": true,
+      "hooks": ["session-enforcer", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "planning",
+      "to": "implementing",
+      "direction": "shortcut",
+      "command": "/scope-implement {id}",
+      "confirmLevel": "full",
+      "checklist": [
+        "Scope is small and well-understood",
+        "Spec is complete — no open questions",
+        "No cross-scope dependencies to resolve first"
+      ],
+      "label": "Fast Track",
+      "description": "Skips team review and starts implementing directly.",
+      "dispatchOnly": false,
+      "humanOnly": true,
+      "hooks": ["session-enforcer", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "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,
+      "hooks": ["session-enforcer", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "implementing",
+      "to": "review",
+      "direction": "forward",
+      "command": "/scope-post-review {id}",
+      "confirmLevel": "quick",
+      "label": "Launch Post-Review",
+      "description": "Runs quality gates, formal verification, and code review.",
+      "dispatchOnly": true,
+      "hooks": ["session-enforcer", "review-gate-check", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "implementing",
+      "to": "completed",
+      "direction": "shortcut",
+      "command": null,
+      "confirmLevel": "full",
+      "checklist": [
+        "Change is small and self-contained",
+        "I have manually verified this change works",
+        "No review verdict needed for this scope"
+      ],
+      "label": "Skip Review",
+      "description": "Moves directly to completed without running the review gate.",
+      "dispatchOnly": false,
+      "humanOnly": true,
+      "hooks": ["session-enforcer", "completion-checklist", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "implementing",
+      "to": "backlog",
+      "direction": "backward",
+      "command": null,
+      "confirmLevel": "quick",
+      "label": "Back to Backlog",
+      "description": "Returns this scope to the backlog. Use when implementation was not started or session failed.",
+      "dispatchOnly": false,
+      "humanOnly": true,
+      "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "review",
+      "to": "completed",
+      "direction": "forward",
+      "command": "/git-commit",
+      "confirmLevel": "quick",
+      "label": "Commit",
+      "description": "Commits scope work.",
+      "dispatchOnly": true,
+      "hooks": ["session-enforcer", "completion-checklist", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update", "scope-commit-logger"]
+    },
+    {
+      "from": "completed",
+      "to": "main",
+      "direction": "forward",
+      "command": "/git-main",
+      "confirmLevel": "quick",
+      "label": "Push to Main",
+      "description": "Pushes or PRs scope work to the main branch.",
+      "dispatchOnly": true,
+      "hooks": ["session-enforcer", "blocker-check", "dependency-check", "scope-transition", "orbital-scope-update", "scope-commit-logger"]
+    },
+    {
+      "from": "review",
+      "to": "implementing",
+      "direction": "backward",
+      "command": "/scope-implement {id}",
+      "confirmLevel": "quick",
+      "label": "Back to Implementing",
+      "description": "Re-opens implementation to address review findings.",
+      "dispatchOnly": true,
+      "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "completed",
+      "to": "implementing",
+      "direction": "backward",
+      "command": "/scope-implement {id}",
+      "confirmLevel": "quick",
+      "label": "Back to Implementing",
+      "description": "Re-opens implementation to fix issues found after commit.",
+      "dispatchOnly": true,
+      "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "main",
+      "to": "implementing",
+      "direction": "backward",
+      "command": "/scope-implement {id}",
+      "confirmLevel": "quick",
+      "label": "Back to Implementing",
+      "description": "Re-opens implementation to fix issues found after push to main.",
+      "dispatchOnly": true,
+      "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "planning",
+      "to": "icebox",
+      "direction": "backward",
+      "command": null,
+      "confirmLevel": "quick",
+      "label": "Demote to Idea",
+      "description": "Sends this scope back to the icebox as an idea.",
+      "dispatchOnly": false,
+      "humanOnly": true,
+      "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
+    },
+    {
+      "from": "backlog",
+      "to": "planning",
+      "direction": "backward",
+      "command": null,
+      "confirmLevel": "quick",
+      "label": "Revert to Planning",
+      "description": "Sends this scope back for more planning. Unlocks spec.",
+      "dispatchOnly": false,
+      "humanOnly": true,
+      "hooks": ["session-enforcer", "scope-transition", "orbital-scope-update"]
+    }
+  ],
+  "hooks": [
+    {
+      "id": "session-enforcer",
+      "label": "Session Authorization",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/session-enforcer.sh",
+      "blocking": true,
+      "description": "Blocks unauthorized status transitions without a valid session",
+      "category": "guard"
+    },
+    {
+      "id": "completion-checklist",
+      "label": "Completion Checklist",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/completion-checklist.sh",
+      "blocking": true,
+      "description": "Blocks completion if DoD items are unchecked",
+      "category": "guard"
+    },
+    {
+      "id": "review-gate-check",
+      "label": "Review Verdict Check",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/review-gate-check.sh",
+      "blocking": false,
+      "description": "Warns if review verdict file is missing",
+      "category": "gate"
+    },
+    {
+      "id": "blocker-check",
+      "label": "Blocker Check",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/blocker-check.sh",
+      "blocking": false,
+      "description": "Warns if unresolved blockers exist on the scope",
+      "category": "gate"
+    },
+    {
+      "id": "dependency-check",
+      "label": "Dependency Check",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/dependency-check.sh",
+      "blocking": false,
+      "description": "Warns if cross-scope dependencies are unresolved",
+      "category": "gate"
+    },
+    {
+      "id": "scope-create-gate",
+      "label": "Scope Creation Gate",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/scope-create-gate.sh",
+      "blocking": false,
+      "description": "Validates new scope structure before creation",
+      "category": "gate"
+    },
+    {
+      "id": "scope-transition",
+      "label": "Scope File Mover",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/scope-transition.sh",
+      "blocking": false,
+      "description": "Moves scope files between directories and updates frontmatter",
+      "category": "lifecycle"
+    },
+    {
+      "id": "orbital-scope-update",
+      "label": "Dashboard Sync",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/orbital-scope-update.sh",
+      "blocking": false,
+      "description": "Pushes status updates to the Orbital Command dashboard",
+      "category": "observer"
+    },
+    {
+      "id": "scope-commit-logger",
+      "label": "Commit Logger",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/scope-commit-logger.sh",
+      "blocking": false,
+      "description": "Logs git commits that mention scope IDs",
+      "category": "observer"
+    },
+    {
+      "id": "scope-gate",
+      "label": "Scope Document Gate",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/scope-gate.sh",
+      "blocking": false,
+      "description": "Triggers scope document creation after plan approval",
+      "category": "gate"
+    },
+    {
+      "id": "scope-lifecycle-gate",
+      "label": "Scope Lifecycle Gate",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/scope-lifecycle-gate.sh",
+      "blocking": false,
+      "description": "Records session UUIDs on scopes before git operations",
+      "category": "gate"
+    },
+    {
+      "id": "scope-file-sync",
+      "label": "Scope File Sync",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/scope-file-sync.sh",
+      "blocking": false,
+      "description": "Flags out-of-scope files before git commits",
+      "category": "gate"
+    },
+    {
+      "id": "init-session",
+      "label": "Session Init",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/init-session.sh",
+      "blocking": false,
+      "description": "Caches session ID for parallel-safe lookup at session start",
+      "category": "lifecycle"
+    },
+    {
+      "id": "end-session",
+      "label": "Session End",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/end-session.sh",
+      "blocking": false,
+      "description": "Emits SESSION_END event when Claude session exits",
+      "category": "lifecycle"
+    },
+    {
+      "id": "scope-create-cleanup",
+      "label": "Scope Create Cleanup",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/scope-create-cleanup.sh",
+      "blocking": false,
+      "description": "Removes scope-create session marker after scope document written",
+      "category": "lifecycle"
+    },
+    {
+      "id": "get-session-id",
+      "label": "Get Session ID",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/get-session-id.sh",
+      "blocking": false,
+      "description": "Reads cached session UUID from process tree",
+      "category": "lifecycle"
+    },
+    {
+      "id": "orbital-emit",
+      "label": "Orbital Event Emitter",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/orbital-emit.sh",
+      "blocking": false,
+      "description": "Emits events to Orbital dashboard via file-based bus",
+      "category": "lifecycle"
+    },
+    {
+      "id": "scope-helpers",
+      "label": "Scope Helpers",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/scope-helpers.sh",
+      "blocking": false,
+      "description": "Shared utility functions for scope lifecycle hooks",
+      "category": "lifecycle"
+    },
+    {
+      "id": "decision-capture",
+      "label": "Decision Capture",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/decision-capture.sh",
+      "blocking": false,
+      "description": "Nudges user to log decisions after asking questions",
+      "category": "observer"
+    },
+    {
+      "id": "exploration-logger",
+      "label": "Exploration Logger",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/exploration-logger.sh",
+      "blocking": false,
+      "description": "Tracks search operations and nudges to log findings",
+      "category": "observer"
+    },
+    {
+      "id": "files-changed-summary",
+      "label": "Files Changed Summary",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/files-changed-summary.sh",
+      "blocking": false,
+      "description": "Shows planned vs actual files changed before scope completion",
+      "category": "observer"
+    },
+    {
+      "id": "phase-verify-reminder",
+      "label": "Phase Verify Reminder",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/phase-verify-reminder.sh",
+      "blocking": false,
+      "description": "Reminds to verify before marking a phase as done",
+      "category": "observer"
+    },
+    {
+      "id": "scope-create-tracker",
+      "label": "Scope Create Tracker",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/scope-create-tracker.sh",
+      "blocking": false,
+      "description": "Tracks when scope create skill is invoked in a session",
+      "category": "observer"
+    },
+    {
+      "id": "orbital-report-gates",
+      "label": "Report Gates",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/orbital-report-gates.sh",
+      "blocking": false,
+      "description": "Reports quality gate results to Orbital dashboard",
+      "category": "observer"
+    },
+    {
+      "id": "orbital-report-deploy",
+      "label": "Report Deploy",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/orbital-report-deploy.sh",
+      "blocking": false,
+      "description": "Reports deployment events to Orbital dashboard",
+      "category": "observer"
+    },
+    {
+      "id": "orbital-report-violation",
+      "label": "Report Violation",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/orbital-report-violation.sh",
+      "blocking": false,
+      "description": "Emits enforcement violation events to Orbital dashboard",
+      "category": "observer"
+    },
+    {
+      "id": "agent-trigger",
+      "label": "Agent Trigger",
+      "timing": "before",
+      "type": "shell",
+      "target": ".claude/hooks/agent-trigger.sh",
+      "blocking": false,
+      "description": "Auto-invokes agent review when editing sensitive files",
+      "category": "observer"
+    },
+    {
+      "id": "time-tracker",
+      "label": "Time Tracker",
+      "timing": "after",
+      "type": "shell",
+      "target": ".claude/hooks/time-tracker.sh",
+      "blocking": false,
+      "description": "Emits scope status transition events for time tracking",
+      "category": "observer"
+    }
+  ],
+  "groups": [
+    { "id": "planning", "label": "Planning", "order": 0 },
+    { "id": "development", "label": "Development", "order": 1 },
+    { "id": "main", "label": "Main", "order": 2 }
+  ],
+  "eventInference": [
+    {
+      "eventType": "SCOPE_STATUS_CHANGED",
+      "targetStatus": "",
+      "dataField": "to",
+      "forwardOnly": true
+    },
+    {
+      "eventType": "AGENT_STARTED",
+      "targetStatus": "implementing",
+      "forwardOnly": true
+    },
+    {
+      "eventType": "AGENT_STARTED",
+      "targetStatus": "review",
+      "conditions": { "mode": "review" },
+      "forwardOnly": true
+    },
+    {
+      "eventType": "AGENT_COMPLETED",
+      "targetStatus": "implementing",
+      "forwardOnly": true
+    },
+    {
+      "eventType": "AGENT_COMPLETED",
+      "targetStatus": "",
+      "conditions": {
+        "outcome": ["success", "failure", "committed"],
+        "dispatchResolution": true
+      },
+      "forwardOnly": false
+    },
+    {
+      "eventType": "AGENT_CONSENSUS",
+      "targetStatus": "implementing",
+      "forwardOnly": true
+    },
+    {
+      "eventType": "GATE_STARTED",
+      "targetStatus": "review",
+      "forwardOnly": true
+    },
+    {
+      "eventType": "GATE_PASSED",
+      "targetStatus": "review",
+      "forwardOnly": true
+    },
+    {
+      "eventType": "GATE_FAILED",
+      "targetStatus": "review",
+      "forwardOnly": true
+    },
+    {
+      "eventType": "ALL_GATES_PASSED",
+      "targetStatus": "review",
+      "forwardOnly": true
+    },
+    {
+      "eventType": "PR_CREATED",
+      "targetStatus": "review",
+      "forwardOnly": true
+    },
+    {
+      "eventType": "PR_MERGED",
+      "targetStatus": "review",
+      "forwardOnly": true
+    },
+    {
+      "eventType": "SCOPE_COMPLETED",
+      "targetStatus": "completed",
+      "forwardOnly": true
+    }
+  ],
+  "allowedCommandPrefixes": ["/scope-", "/git-", "/test-", "/session-"],
+  "terminalStatuses": ["main"],
+  "commitBranchPatterns": "^(main|feat/|fix/|scope/|chore/)"
+}