docs(FN-1194): expand architecture documentation for current system

- Rewrite docs/architecture.md as a comprehensive "Fusion Architecture" guide grounded in the actual repository structure - Add package-level breakdowns, dependency graph, and runtime/data-flow diagrams across core, engine, dashboard, CLI, and desktop - Document storage model, task lifecycle, agent/heartbeat behavior, multi-project orchestration, settings hierarchy, and git/merge integration - Add a quick source-map section linking key implementation files for faster onboarding and navigation
2026-04-08 01:58:01 -07:00
parent d7f49c0dbe
commit 724ae7be41
1 changed files with 509 additions and 94 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,125 +1,540 @@
-# Architecture
+# Fusion Architecture

 [← Docs index](./README.md)

-This document explains how Fusion is structured, how data is stored, and how the AI execution pipeline moves work from idea to merged code.
+This document describes the actual architecture of Fusion as implemented in this repository (`gsxdsm/fusion`). It is intended as a practical onboarding map for developers and AI agents.

-## End-to-End Workflow
+---

-```mermaid
-graph TD
-    H((You)) -->|rough idea| T["Triage\n<i>auto-specification</i>"]
-    T --> TD["Todo\n<i>scheduled for execution</i>"]
-    TD --> IP["In Progress\n<i>plan, review, execute, review</i>"]
+## 1) Overview

-    IP --> IR["In Review\n<i>ready to merge</i>"]
-    IR --> D["Done"]
-```
+Fusion is an AI-orchestrated task board. It takes tasks through a structured lifecycle (`triage → todo → in-progress → in-review → done → archived`) and automates triage, execution, review, merge, and operational recovery.

-At a high level:
+At a high level, Fusion is split into:
+- **Core domain + persistence** (`@fusion/core`)
+- **Execution engine** (`@fusion/engine`)
+- **Dashboard API + SPA** (`@fusion/dashboard`)
+- **CLI + Pi extension** (`@gsxdsm/fusion`)
+- **Desktop shell** (`@fusion/desktop`)
+- **TUI stub** (`@fusion/tui`)

- **Triage** writes a full `PROMPT.md` spec
- **Scheduler** selects ready tasks (respecting dependencies and limits)
- **Executor** runs agents in isolated worktrees
- **Merger** finalizes tasks to `done` (direct squash merge or PR flow)
-
-## Workspace Packages
-
-| Package | Responsibility |
-|---|---|
-| `@fusion/core` | Domain model, TaskStore/MissionStore, SQLite persistence, shared types/defaults. |
-| `@fusion/dashboard` | Express API + React dashboard UI (kanban board, live updates, tooling surfaces). |
-| `@fusion/engine` | Triage, scheduling, execution, workflow steps, merge orchestration, automation runtime. |
-| `@fusion/tui` | Ink-based terminal UI package (lightweight terminal components). |
-| `@gsxdsm/fusion` | Published CLI (`fn`) + pi extension tools. |
-
-## Storage Architecture
-
-Fusion uses a **hybrid model**:
-
- **SQLite metadata:** `.fusion/fusion.db`
- **Blob/filesystem artifacts:** `.fusion/tasks/{id}/PROMPT.md`, `agent.log`, attachments
- **Global user settings:** `~/.pi/fusion/settings.json`
-
-### Why hybrid?
-
- SQLite gives transactional metadata updates and indexed queries.
- Filesystem storage keeps large task artifacts simple and portable.
-
-### Key SQLite behavior
-
- WAL mode enabled for concurrent readers/writers
- Foreign keys enforced
- Monotonic metadata timestamp used for change detection
-
-## Typical `.fusion/` Layout
+### High-level runtime diagram

 ```text
-.fusion/
-  fusion.db
-  tasks/
-    FN-001/
-      task.json
-      PROMPT.md
-      agent.log
-      attachments/
-  backups/
+                        ┌──────────────────────────────┐
+                        │   Human + AI Interactions    │
+                        │  (Dashboard, CLI, Pi tools)  │
+                        └──────────────┬───────────────┘
+                                       │
+                ┌──────────────────────┼──────────────────────┐
+                │                      │                      │
+      ┌─────────▼─────────┐  ┌─────────▼─────────┐  ┌─────────▼─────────┐
+      │  Dashboard (API)  │  │ CLI `fn` router   │  │ Pi extension tools │
+      │ + React SPA       │  │ (commands/*)      │  │ (extension.ts)     │
+      └─────────┬─────────┘  └─────────┬─────────┘  └─────────┬─────────┘
+                └──────────────┬────────┴──────────────┬───────┘
+                               │                       │
+                      ┌────────▼───────────────────────▼───────┐
+                      │            Engine Runtime               │
+                      │ Scheduler / Triage / Executor / Merger │
+                      │ Heartbeat / Self-healing / Autopilot   │
+                      └────────┬───────────────────────┬────────┘
+                               │                       │
+                   ┌───────────▼──────────┐   ┌────────▼─────────────┐
+                   │ @fusion/core         │   │ External systems      │
+                   │ stores + types       │   │ git, GitHub, models   │
+                   └───────┬──────────────┘   └───────────────────────┘
+                           │
+          ┌────────────────▼────────────────┐
+          │ Persistence                      │
+          │ - .fusion/fusion.db (SQLite/WAL)
+          │ - .fusion/tasks/* (PROMPT/logs)
+          │ - ~/.pi/fusion/fusion-central.db │
+          └──────────────────────────────────┘
 ```

-## AI Engine Components
+---

-### 1) TriageProcessor
+## 2) Monorepo Structure

- Reads rough task descriptions
- Generates structured `PROMPT.md` with mission, file scope, steps, and acceptance criteria
- Can be gated by `requirePlanApproval`
+| Package | Published | Role | Key files |
+|---|---|---|---|
+| `@fusion/core` | Private | Domain model, stores, SQLite adapters, settings, shared types | `packages/core/src/types.ts`, `store.ts`, `db.ts`, `central-core.ts`, `agent-store.ts` |
+| `@fusion/engine` | Private | AI orchestration runtime (triage, scheduler, executor, merger, recovery) | `packages/engine/src/triage.ts`, `scheduler.ts`, `executor.ts`, `merger.ts`, `project-runtime.ts` |
+| `@fusion/dashboard` | Private | Express API server + React app | `packages/dashboard/src/server.ts`, `routes.ts`, `sse.ts`, `websocket.ts`, `packages/dashboard/app/App.tsx` |
+| `@gsxdsm/fusion` | **Published** | CLI binary (`fn`) + Pi extension | `packages/cli/src/bin.ts`, `commands/*`, `project-resolver.ts`, `extension.ts` |
+| `@fusion/desktop` | Private | Electron shell around Fusion dashboard/client | `packages/desktop/src/main.ts`, `ipc.ts`, `preload.ts`, `scripts/build.ts` |
+| `@fusion/tui` | Private | Ink-based terminal package (currently minimal stub) | `packages/tui/src/index.tsx` |

-### 2) Scheduler
+> Note: The workspace also contains `@fusion/mobile` (`packages/mobile`), which packages dashboard assets for Capacitor targets.

- Moves tasks from `todo` to `in-progress`
- Enforces dependencies, concurrency limits, and overlap rules
- Coordinates mission/slice progression hooks
+---

-### 3) TaskExecutor
+## 3) Package Dependencies

- Creates/attaches task worktrees (`fusion/{task-id}` branches)
- Runs agent sessions with tooling (task update/logging/review/spawn)
- Supports step session mode (`runStepsInNewSessions`) and parallel step execution (`maxParallelSteps`)
- Executes configured pre-merge workflow steps
+### Workspace dependency graph

-## Error Recovery and Resilience
+```text
+                         ┌────────────────────┐
+                         │   @fusion/core     │
+                         └─────────┬──────────┘
+                                   │
+                    ┌──────────────▼──────────────┐
+                    │       @fusion/engine        │
+                    └──────────────┬──────────────┘
+                                   │
+                    ┌──────────────▼──────────────┐
+                    │     @fusion/dashboard       │
+                    └──────────────┬──────────────┘
+                                   │
+                  ┌────────────────▼────────────────┐
+                  │      @gsxdsm/fusion (CLI)       │
+                  │  (workspace composition + build)│
+                  └────────────────┬────────────────┘
+                                   │
+                    ┌──────────────▼──────────────┐
+                    │      @fusion/desktop        │
+                    │ (embeds dashboard client)   │
+                    └──────────────────────────────┘

-Fusion has multiple safety/recovery paths:
+        @fusion/tui is currently independent/minimal.
+```

- **Transient error retry:** bounded retry flow for temporary failures
- **Stuck task detection:** inactivity timeout can terminate/requeue hung runs
- **Context-limit recovery:** compact-and-resume flow when model context overflows
- **Workflow step failure handling:** marks task failed/in-review for inspection rather than silently passing
- **Pause semantics:** global hard-stop (`globalPause`) and soft scheduler pause (`enginePaused`)
+Concrete references:
+- `@fusion/engine` depends on `@fusion/core` (`packages/engine/package.json`)
+- `@fusion/dashboard` depends on both `@fusion/core` and `@fusion/engine`
+- CLI command entrypoint (`packages/cli/src/bin.ts`) dynamically imports command modules that use core/engine/dashboard capabilities
+- Desktop build script copies dashboard client output (`packages/desktop/scripts/build.ts`)

-## Project Memory System
+---

-When enabled (`memoryEnabled: true`), agents can use project memory files:
+## 4) Core Package (`@fusion/core`)

- `.fusion/memory.md` — durable project learnings
- Optional derived memory insights (via scheduled extraction)
+### Responsibility
+`@fusion/core` is the shared domain and persistence layer.

-This helps agents retain patterns and pitfalls across tasks.
+### Main components
+- **Types and constants**: `packages/core/src/types.ts`
+  - Columns: `COLUMNS`
+  - Transition map: `VALID_TRANSITIONS`
+  - Settings defaults: `DEFAULT_GLOBAL_SETTINGS`, `DEFAULT_PROJECT_SETTINGS`
+  - Workflow types (`WorkflowStep`, `WorkflowStepPhase`, etc.)
+- **TaskStore**: `packages/core/src/store.ts`
+  - Main task CRUD + lifecycle store
+  - Emits board events (`task:created`, `task:moved`, `task:updated`, ...)
+  - Hybrid model: SQLite metadata + filesystem blobs under `.fusion/tasks/{id}`
+- **Database adapter**: `packages/core/src/db.ts`
+  - SQLite (`node:sqlite`) with WAL mode + foreign keys
+  - JSON helpers: `toJson`, `toJsonNullable`, `fromJson`
+  - Tables: `tasks`, `config`, `activityLog`, `archivedTasks`, `automations`, `agents`, `agentHeartbeats`, mission hierarchy tables, `__meta`
+- **CentralCore**: `packages/core/src/central-core.ts`
+  - Global project registry, health, central activity feed, global concurrency
+  - Backed by `packages/core/src/central-db.ts` (`~/.pi/fusion/fusion-central.db`)
+- **Specialized stores**:
+  - `AgentStore` (`agent-store.ts`) — filesystem-based agent metadata + heartbeat run history
+  - `MissionStore` (`mission-store.ts`) — mission/milestone/slice/feature hierarchy
+  - `AutomationStore` (`automation-store.ts`) — scheduled jobs
+  - `MessageStore` (`message-store.ts`) — mailbox/inbox/outbox messaging

-## Git Worktree Isolation Model
+### Shared utilities
+From `packages/core/src/index.ts` exports:
+- GitHub CLI wrappers: `gh-cli.ts`
+- Backups: `backup.ts`
+- Settings import/export: `settings-export.ts`
+- AI title summarization: `ai-summarize.ts`
+- Project memory helpers: `project-memory.ts`, `memory-insights.ts`
+- Migration and compatibility helpers: `db-migrate.ts`, `migration.ts`

-Every active task runs in its own git worktree:
+---

- Avoids cross-task file collisions
- Makes cleanup/retry deterministic
- Enables parallel execution safely
- Supports pooled reuse when `recycleWorktrees` is enabled
+## 5) Engine Package (`@fusion/engine`)

-Branch naming remains `fusion/{task-id}` regardless of worktree folder naming mode.
+`@fusion/engine` executes the autonomous workflow.

-## Related Guides
+### Agent roles
+- **Triage**: `TriageProcessor` (`triage.ts`) generates task specs (`PROMPT.md`)
+- **Executor**: `TaskExecutor` (`executor.ts`) implements tasks in worktrees
+- **Reviewer**: `reviewStep()` (`reviewer.ts`) performs plan/code reviews
+- **Merger**: `aiMergeTask()` (`merger.ts`) merges approved work

- [Task Management](./task-management.md)
- [Workflow Steps](./workflow-steps.md)
- [Multi-Project](./multi-project.md)
- [Settings Reference](./settings-reference.md)
+### Scheduling and execution
+- `Scheduler` (`scheduler.ts`)
+  - Polls and event-triggers scheduling
+  - Respects dependencies and concurrency/worktree limits
+  - Integrates mission progression hooks
+- `TaskExecutor` (`executor.ts`)
+  - Creates/reuses worktrees
+  - Runs model sessions via `createKbAgent()` (`pi.ts`)
+  - Supports tool-calling workflow (`task_update`, `task_log`, `task_create`, `review_step`, `spawn_agent`, ...)
+- `StepSessionExecutor` (`step-session-executor.ts`)
+  - Optional per-step sessions (`runStepsInNewSessions`)
+  - File-scope conflict analysis + parallel wave execution
+
+### Concurrency and resiliency
+- `AgentSemaphore` (`concurrency.ts`) controls slot acquisition
+- `StuckTaskDetector` (`stuck-task-detector.ts`) handles inactivity/loop stalls
+- `SelfHealingManager` (`self-healing.ts`) handles auto-unpause, maintenance, stuck kill budgets
+- `UsageLimitPauser` (`usage-limit-detector.ts`) and retry helpers (`rate-limit-retry.ts`)
+
+### Worktree management
+- `WorktreePool` (`worktree-pool.ts`) recycles idle worktrees when enabled
+- Branch naming convention in executor: `fusion/{task-id-lower}`
+
+### Heartbeat execution
+Implemented in `agent-heartbeat.ts`:
+- `HeartbeatMonitor`
+- `HeartbeatTriggerScheduler` (timer, assignment, on-demand triggers)
+- `WakeContext` / per-agent runtime config support
+
+### Mission automation
+- `MissionAutopilot` (`mission-autopilot.ts`) watches mission progress and auto-activates slices
+
+### Multi-runtime support + IPC
+- Runtime contracts: `project-runtime.ts`
+- Orchestration: `ProjectManager` and `HybridExecutor`
+- Runtime implementations:
+  - `runtimes/in-process-runtime.ts`
+  - `runtimes/child-process-runtime.ts`
+  - `runtimes/remote-node-runtime.ts`
+- IPC protocol/transport:
+  - `ipc/ipc-protocol.ts`
+  - `ipc/ipc-host.ts`
+  - `ipc/ipc-worker.ts`
+  - worker entrypoint: `runtimes/child-process-worker.ts`
+
+---
+
+## 6) Dashboard Package (`@fusion/dashboard`)
+
+### Server layer
+- Entry exports: `packages/dashboard/src/index.ts`
+- Main server factory: `createServer()` in `packages/dashboard/src/server.ts`
+- API routes: `createApiRoutes()` in `packages/dashboard/src/routes.ts`
+
+Key server capabilities:
+- REST APIs for tasks, git, GitHub, agents, missions, planning, automations, settings
+- Project-scoped store reuse via `project-store-resolver.ts`
+- Rate limiting (`rate-limit.ts`)
+- Static SPA hosting (Vite build output)
+
+### Real-time channels
+- **SSE**: `/api/events` (`sse.ts`)
+  - Emits `task:*`, mission events, AI session updates
+- **Badge WebSocket**: `/api/ws` (`setupBadgeWebSocket` in `server.ts`, manager in `websocket.ts`)
+  - Broadcasts lightweight badge snapshots (`prInfo` / `issueInfo`)
+- **Terminal WebSocket**: `/api/terminal/ws` (also in `server.ts`)
+
+### Frontend SPA layer
+- App entry: `packages/dashboard/app/main.tsx`
+- Root composition: `packages/dashboard/app/App.tsx`
+- Core board components: `components/Board.tsx`, `Column.tsx`, `TaskCard.tsx`, `TaskDetailModal.tsx`
+- List/creation UX: `ListView.tsx`, `QuickEntryBox.tsx`, `InlineCreateCard.tsx`
+
+### Key hooks
+- `useTasks.ts` — SSE-driven task sync with reconnect + timestamp conflict handling
+- `useBadgeWebSocket.ts` — shared singleton badge socket/subscriptions
+- `useAgents.ts`, `useProjects.ts`, `useCurrentProject.ts`, `useTerminal.ts`
+
+### Planning and decomposition features
+- Backend planners:
+  - `planning.ts`
+  - `subtask-breakdown.ts`
+- UI modals:
+  - `PlanningModeModal.tsx`
+  - `SubtaskBreakdownModal.tsx`
+- Multi-task creation endpoints are wired under planning/subtask routes in `routes.ts`
+
+---
+
+## 7) CLI Package (`@gsxdsm/fusion`)
+
+### Command entrypoint
+- `packages/cli/src/bin.ts`
+  - Bootstraps environment
+  - Parses global flags (including `--project`)
+  - Routes subcommands (`task`, `project`, `settings`, `git`, `backup`, `mission`, `agent`, `message`, etc.)
+
+### Command modules
+- `packages/cli/src/commands/*`
+  - Task operations, settings, git wrappers, backup operations, project/node management
+
+### Project selection
+- `packages/cli/src/project-resolver.ts`
+  - Resolution order: explicit `--project` → CWD detection (`.fusion`) → default/fallback logic
+  - Integrates `CentralCore` and `ProjectManager`
+
+### Pi extension
+- `packages/cli/src/extension.ts`
+  - Registers tool set for in-chat task/mission operations
+  - Uses `TaskStore` directly for extension-side actions
+
+### Binary identity
+- Published package defines `fn` binary (`packages/cli/package.json`)
+
+---
+
+## 8) Storage Architecture
+
+Fusion uses a hybrid storage model.
+
+### Per-project storage
+- **SQLite DB**: `.fusion/fusion.db`
+- **Filesystem blobs** (task-local artifacts):
+  - `.fusion/tasks/{TASK_ID}/PROMPT.md`
+  - `.fusion/tasks/{TASK_ID}/agent.log`
+  - `.fusion/tasks/{TASK_ID}/attachments/*`
+
+SQLite schema is initialized in `packages/core/src/db.ts` and uses:
+- WAL mode (`PRAGMA journal_mode = WAL`)
+- Foreign keys (`PRAGMA foreign_keys = ON`)
+- `__meta.lastModified` for change detection/polling
+
+### Central storage (multi-project)
+- **Central DB**: `~/.pi/fusion/fusion-central.db`
+- Schema in `packages/core/src/central-db.ts`
+  - `projects`, `projectHealth`, `centralActivityLog`, `globalConcurrency`, `nodes`, `__meta`
+
+### File-based side stores
+Some data remains intentionally filesystem-based:
+- Agents: `.fusion/agents/*` (`AgentStore`)
+- Messages: `.fusion/messages/*` (`MessageStore`)
+
+### Migration from legacy file storage
+- Detection + migration: `packages/core/src/db-migrate.ts`
+- Migrates legacy task/config/log/archive/automation/agent data into SQLite
+- Creates `.bak` backups (for example `task.json.bak`, `config.json.bak`, `archive.jsonl.bak`)
+
+### Archive system
+- Archived task snapshots are stored in SQLite `archivedTasks`
+- `TaskStore` archive helpers:
+  - `archiveTaskAndCleanup()`
+  - `cleanupArchivedTasks()`
+  - `readArchiveLog()` / `findInArchive()`
+  - `unarchiveTask()` with restore behavior
+
+---
+
+## 9) Task Lifecycle
+
+Lifecycle constants are defined in `packages/core/src/types.ts`:
+- Columns: `triage`, `todo`, `in-progress`, `in-review`, `done`, `archived`
+- Transition rules via `VALID_TRANSITIONS`
+
+### Lifecycle flow
+
+```text
+triage
+  │ (TriageProcessor writes PROMPT.md)
+  ▼
+todo
+  │ (Scheduler selects task, dependencies satisfied)
+  ▼
+in-progress
+  │ (TaskExecutor runs in worktree)
+  ▼
+in-review
+  │ (implementation complete + pre-merge workflow steps)
+  ▼
+done
+  │
+  └──────────────▶ archived
+```
+
+### Execution detail
+- **Triage phase**: `TriageProcessor` generates executable spec
+- **Execution phase**: `TaskExecutor` performs implementation, tool calls, tests/build commands
+- **Review phase**: optional `reviewStep()` workflow depending on prompt review level
+- **Merge phase**: `aiMergeTask()` handles merge strategy and post-merge workflow steps
+
+### Step status model
+Task steps use statuses: `pending`, `in-progress`, `done`, `skipped`.
+
+### Workflow steps
+- Defined in project config as `WorkflowStep`
+- **Pre-merge** steps run in executor (`runWorkflowSteps()`)
+- **Post-merge** steps run in merger (`runPostMergeWorkflowSteps()`)
+
+---
+
+## 10) Agent System
+
+Fusion has two complementary agent models:
+
+1. **Task pipeline agents** (triage/executor/reviewer/merger) managed by engine runtime
+2. **Persistent registered agents** managed by `AgentStore`
+
+### Persistent agent storage
+`packages/core/src/agent-store.ts` persists to:
+- `.fusion/agents/{id}.json`
+- `.fusion/agents/{id}-heartbeats.jsonl`
+- `.fusion/agents/{id}-keys.jsonl`
+- `.fusion/agents/{id}-revisions.jsonl`
+
+### Agent spawning from executor
+`TaskExecutor` supports hierarchical child agents via:
+- `createSpawnAgentTool()`
+- `runSpawnedChild()`
+- `terminateChildAgent()` / `terminateAllChildren()`
+
+Limits are controlled by project settings (`maxSpawnedAgentsPerParent`, `maxSpawnedAgentsGlobal`).
+
+### Heartbeat monitoring and triggers
+`agent-heartbeat.ts` provides:
+- Health monitoring and run tracking (`HeartbeatMonitor`)
+- Trigger scheduling (`HeartbeatTriggerScheduler`) for:
+  - timer
+  - task assignment
+  - on-demand runs
+
+### Custom instructions
+`packages/engine/src/agent-instructions.ts` resolves per-agent instruction text/path with path-traversal and extension validation.
+
+---
+
+## 11) Multi-Project Architecture
+
+Multi-project orchestration spans core + engine.
+
+### Core control plane
+- `CentralCore` (`packages/core/src/central-core.ts`) maintains:
+  - Project registry
+  - Health metrics
+  - Unified central activity feed
+  - Global concurrency state
+  - Node registry (`local` / `remote`)
+
+### Engine orchestration
+- `HybridExecutor` (`packages/engine/src/hybrid-executor.ts`) is the top-level orchestrator
+- `ProjectManager` instantiates per-project runtimes and forwards events with project attribution
+
+### Runtime abstraction
+Defined in `project-runtime.ts`:
+- `ProjectRuntime` interface
+- `RuntimeStatus` and `RuntimeMetrics`
+
+Implementations:
+- `InProcessRuntime`
+- `ChildProcessRuntime`
+- `RemoteNodeRuntime`
+
+### IPC protocol (child-process mode)
+In `packages/engine/src/ipc/ipc-protocol.ts`:
+- Host commands: `START_RUNTIME`, `STOP_RUNTIME`, `GET_STATUS`, `GET_METRICS`, `PING`
+- Worker events: `TASK_CREATED`, `TASK_MOVED`, `TASK_UPDATED`, `ERROR_EVENT`, `HEALTH_CHANGED`
+
+### Multi-project runtime diagram
+
+```text
+                   HybridExecutor
+                        │
+                ┌───────┴────────┐
+                │   ProjectManager│
+                └───┬─────────┬───┘
+                    │         │
+        ┌───────────▼───┐  ┌──▼──────────────┐
+        │InProcessRuntime│  │ChildProcessRuntime│
+        │(local process) │  │(fork + IPC host)  │
+        └──────┬─────────┘  └──┬───────────────┘
+               │                │
+          TaskStore/Scheduler   │
+                                ▼
+                        child-process-worker
+                        + InProcessRuntime
+```
+
+---
+
+## 12) Settings Hierarchy
+
+Settings are split by scope.
+
+### Global scope
+- File: `~/.pi/fusion/settings.json`
+- Managed by `GlobalSettingsStore` (`packages/core/src/global-settings.ts`)
+- Examples: `themeMode`, `colorTheme`, default model/provider, notification preferences
+
+### Project scope
+- Stored in per-project config (`config` table + compatibility file `.fusion/config.json`)
+- Includes engine/runtime controls (`maxConcurrent`, `autoMerge`, worktree and workflow behavior, etc.)
+
+### Merged view
+- `Settings` combines global + project values
+- Defaults in `DEFAULT_GLOBAL_SETTINGS` and `DEFAULT_PROJECT_SETTINGS`
+- Scope key lists in `GLOBAL_SETTINGS_KEYS` and `PROJECT_SETTINGS_KEYS`
+
+### Model controls
+- Per-task model overrides on task fields:
+  - `modelProvider` / `modelId`
+  - `validatorModelProvider` / `validatorModelId`
+  - `planningModelProvider` / `planningModelId`
+  - `thinkingLevel`
+- Reusable presets via `ModelPreset`
+- Agent prompt template overrides via `agentPrompts`
+
+---
+
+## 13) Git Integration
+
+Git behavior is implemented primarily in engine executor/merger + dashboard/CLI git APIs.
+
+### Worktree model
+- Each active task runs in isolated worktree under `.worktrees/*`
+- Executor creates branches like `fusion/{task-id}` (`executor.ts`)
+- `WorktreePool` can recycle idle worktrees when enabled
+
+### Merge strategies
+- Setting type: `MergeStrategy = "direct" | "pull-request"` (`types.ts`)
+- `aiMergeTask()` in `merger.ts` performs merge flow
+- Supports workflow-step execution after merge (post-merge phase)
+
+### Conflict handling
+`merger.ts` includes conflict classification and auto-resolution helpers:
+- lock files (`LOCKFILE_PATTERNS`)
+- generated files (`GENERATED_PATTERNS`)
+- whitespace-trivial conflicts
+
+### PR and badge integration
+- Engine PR monitor: `pr-monitor.ts` and `pr-comment-handler.ts`
+- Dashboard GitHub APIs + webhook route in `routes.ts`
+- Badge snapshots are streamed via `/api/ws` and `useBadgeWebSocket.ts`
+
+---
+
+## 14) Key Design Decisions
+
+1. **SQLite + WAL for local-first reliability**
+   - Chosen for simple deployment and strong transactional behavior
+   - WAL mode enables concurrent readers/writers with low ops overhead
+
+2. **Hybrid persistence (DB + filesystem blobs)**
+   - Structured metadata in SQLite, large text/artifacts in task directories
+   - Keeps DB efficient while preserving inspectable task artifacts
+
+3. **Git worktree isolation as core execution primitive**
+   - Prevents cross-task interference
+   - Makes concurrent task execution safer
+   - Enables deterministic cleanup/retry/recovery
+
+4. **Agent-as-tool-caller pattern**
+   - Engine tools (`task_update`, `task_log`, `review_step`, `spawn_agent`, etc.) create explicit, auditable state transitions
+   - Prompts are role-specific (`TRIAGE_SYSTEM_PROMPT`, `EXECUTOR_SYSTEM_PROMPT`, etc.)
+
+5. **Separation of real-time channels by concern**
+   - SSE for broad board/missions/session state updates (`/api/events`)
+   - Dedicated badge WebSocket (`/api/ws`) for lightweight PR/issue badge snapshots
+
+6. **Multi-project control plane with runtime abstraction**
+   - `CentralCore` decouples registry/health/concurrency from per-project execution
+   - `ProjectRuntime` interface allows multiple isolation strategies (in-process, child-process, remote node)
+
+---
+
+## Source Map (quick navigation)
+
+- **Core exports:** `packages/core/src/index.ts`
+- **Engine exports:** `packages/engine/src/index.ts`
+- **Dashboard exports:** `packages/dashboard/src/index.ts`
+- **CLI entry:** `packages/cli/src/bin.ts`
+- **Pi extension:** `packages/cli/src/extension.ts`
+- **Runtime abstraction:** `packages/engine/src/project-runtime.ts`
+- **Multi-project orchestrator:** `packages/engine/src/hybrid-executor.ts`