docs(FN-1158): add comprehensive project documentation suite

- Add docs index with structured navigation and links across the new documentation set - Document onboarding and technical foundations with getting-started and architecture guides - Add detailed CLI and settings references plus feature guides for dashboard, tasks, workflow steps, missions, multi-project, and agents - Add a contributing guide and polish cross-references between docs pages for discoverability - Include dashboard screenshots for key views to provide visual context in the guides
2026-04-08 00:17:08 -07:00
parent a4a99f31b0
commit 7eed8ed68a
20 changed files with 1665 additions and 0 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,125 @@
+# 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.
+
+## 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>"]
+
+    IP --> IR["In Review\n<i>ready to merge</i>"]
+    IR --> D["Done"]
+```
+
+At a high level:
+
+- **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
+
+```text
+.fusion/
+  fusion.db
+  tasks/
+    FN-001/
+      task.json
+      PROMPT.md
+      agent.log
+      attachments/
+  backups/
+```
+
+## AI Engine Components
+
+### 1) TriageProcessor
+
+- Reads rough task descriptions
+- Generates structured `PROMPT.md` with mission, file scope, steps, and acceptance criteria
+- Can be gated by `requirePlanApproval`
+
+### 2) Scheduler
+
+- Moves tasks from `todo` to `in-progress`
+- Enforces dependencies, concurrency limits, and overlap rules
+- Coordinates mission/slice progression hooks
+
+### 3) TaskExecutor
+
+- 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
+
+## Error Recovery and Resilience
+
+Fusion has multiple safety/recovery paths:
+
+- **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`)
+
+## Project Memory System
+
+When enabled (`memoryEnabled: true`), agents can use project memory files:
+
+- `.fusion/memory.md` — durable project learnings
+- Optional derived memory insights (via scheduled extraction)
+
+This helps agents retain patterns and pitfalls across tasks.
+
+## Git Worktree Isolation Model
+
+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
+
+Branch naming remains `fusion/{task-id}` regardless of worktree folder naming mode.
+
+## Related Guides
+
+- [Task Management](./task-management.md)
+- [Workflow Steps](./workflow-steps.md)
+- [Multi-Project](./multi-project.md)
+- [Settings Reference](./settings-reference.md)