Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Task Board & Task Lifecycle Management
Overview
The task board is Fusion's core Kanban surface. It lets operators create tasks (free text, import, GitHub), track them through a workflow-driven lifecycle (planning/todo/in-progress/in-review/done), attach prompt specs, comments, and artifacts, declare dependencies and subtasks, and move or delete them with guard rails. Every piece of work in Fusion, including missions and research, eventually resolves to tasks on this board.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Creates and tracks tasks, reads prompt specs, adds comments/artifacts, manages dependencies |
| Agent executor | Consumes task state (spec, file scope, branch context) when driving implementation |
| Dashboard/CLICommand-line interface users | Same board and lifecycle surfaced on every device |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall let users create tasks via quick entry, a new-task modal, import, GitHub issues, and mission/research flows | Must | The system shall let users create tasks via quick entry, a new-task modal, import, GitHub issues, and mission/research flows |
| FR-2MustThe system shall render tasks on a board (column-based) and a list view, with search and filtering | Must | The system shall render tasks on a board (column-based) and a list view, with search and filtering |
| FR-3MustThe system shall persist a task's prompt/spec document, comments, artifacts, dependencies, subtasks, branch context, and file scope | Must | The system shall persist a task's prompt/spec document, comments, artifacts, dependencies, subtasks, branch context, and file scope |
| FR-4MustThe system shall enforce lifecycle move rules and guards (column eligibility, dependencies, user pause semantics) | Must | The system shall enforce lifecycle move rules and guards (column eligibility, dependencies, user pause semantics) |
| FR-5MustThe system shall let users move tasks between columns and move the board itself (board-level moves) | Must | The system shall let users move tasks between columns and move the board itself (board-level moves) |
| FR-6MustThe system shall support archiving and soft-delete with verification, keeping tombstones for audit | Must | The system shall support archiving and soft-delete with verification, keeping tombstones for audit |
| FR-7ShouldThe system shall expose task operations through the dashboard APIApplication programming interface, CLICommand-line interface, and workflow routes | Should | The system shall expose task operations through the dashboard APIApplication programming interface, CLICommand-line interface, and workflow routes |
| FR-8ShouldThe system shall render board columns in a resolved order with degraded-mode flags for unsupported columns | Should | The system shall render board columns in a resolved order with degraded-mode flags for unsupported columns |
| FR-9ShouldThe system shall group tasks (GroupTask) and break work into subtasks with their own lifecycle | Should | The system shall group tasks (GroupTask) and break work into subtasks with their own lifecycle |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustTask lifecycleThe domain state machine modeling a task's progression and its status values mutations shall use per-task advisory locks to prevent conflicting concurrent moves | Must | Concurrency | Task lifecycleThe domain state machine modeling a task's progression and its status values mutations shall use per-task advisory locks to prevent conflicting concurrent moves |
| NFR-2MustSoft-deleted tasks shall never be resurrected by lifecycle or self-healing sweeps | Must | Reliability | Soft-deleted tasks shall never be resurrected by lifecycle or self-healing sweeps |
| NFR-3ShouldThe board shall work on desktop and mobile breakpoints | Should | Usability | The board shall work on desktop and mobile breakpoints |
| NFR-4ShouldTask search and list reads shall complete without full-table scans in normal use | Should | Performance | Task search and list reads shall complete without full-table scans in normal use |
Constraints
- Task store lives in
@fusion/core; dashboard and CLICommand-line interface must not walk the raw DB directly - Port 4040 is reserved and must not be used by tests or tooling
- Backward moves (e.g. in-review → todo) require liveness proof before mutation
Acceptance Criteria
- FR-1MustThe system shall let users create tasks via quick entry, a new-task modal, import, GitHub issues, and mission/research flows
- Given an operator with the dashboard or CLICommand-line interface open
- When they create a task via quick entry, the modal, import, or GitHub
- Then the task appears on the board with a prompt spec and correct column
- FR-2MustThe system shall render tasks on a board (column-based) and a list view, with search and filtering
- Given tasks exist in the store
- When the board or list view is opened
- Then tasks render in resolved column order with search/filtering available
- FR-3MustThe system shall persist a task's prompt/spec document, comments, artifacts, dependencies, subtasks, branch context, and file scope
- Given a task with comments, artifacts, dependencies, and subtasks
- When the task detail is opened
- Then all attached data persists and renders correctly
- FR-4MustThe system shall enforce lifecycle move rules and guards (column eligibility, dependencies, user pause semantics)
- Given a task in a non-target column
- When an invalid move is attempted
- Then the move is rejected with a guard/error and the task column is unchanged
- FR-6MustThe system shall support archiving and soft-delete with verification, keeping tombstones for audit
- Given a task to remove
- When the operator archives/deletes it
- Then it becomes tombstoned and is never resurrected by sweeps
- NFR-1MustTask lifecycleThe domain state machine modeling a task's progression and its status values mutations shall use per-task advisory locks to prevent conflicting concurrent moves
- Given two concurrent lifecycle mutations on the same task
- When both are submitted
- Then exactly one wins and the loser is rejected, with no torn state
Conflicts
None identified yet.
Open Questions
- How are board-level (multiple-task) moves reconciled with per-task workflow selection?
Specification: Task Board & Task Lifecycle Management
Overview
The task board is implemented by a domain task store in @fusion/core (task creation, mutation ops, lifecycle ops, moves, comments, artifacts, file-scope, branch-context, search, and an advisory-lock), exposed through dashboard APIApplication programming interface route registrars and CLICommand-line interface commands, and rendered by React components in the dashboard SPA.
Architecture
board/list React components (Board, ListView, TaskDetail, NewTask, TaskCard, ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column)
│ fetch + mutate
▼
Dashboard APIApplication programming interface registrars (register-tasks, register-task-workflow-routes)
│
▼
@fusion/core task-store (task-creation, mutation-ops, lifecycle-ops, moves,
comments-ops, task-artifacts-ops, file-scope,
branch-context, search, task-advisory-lock)
│
▼
PostgreSQL (tasks + related rows, soft-delete tombstones)
Data Models
Task
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | int | PK, not null | Task identifier (padded in some flows, bare elsewhere per convention) |
| column | enum | not null | planning/todo/in-progress/in-review/done |
| status | enum | not null | Domain status; needs-replan is the durable graph replan signal |
| userPaused | bool | — | User-paused semantics for backward moves |
| prompt / spec doc | text | — | The task's specification/prompt |
| file-scope | json | — | Files the task is allowed to touch |
| branch-context | json | — | Assigned branch / shared-branch group |
APIApplication programming interface Contracts
POST /api/tasks
Request
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | yes | Task title |
| column | enum | no | Initial column (default planning) |
Response (200 OK)
| Field | Type | Description |
|---|---|---|
| task | object | The created task |
Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_INPUT | Malformed task payload |
| 404 | TASK_NOT_FOUND | Referenced task/issue missing |
Sequences
Create and move
Operator → dashboard create-task → task-store(task-creation) → DB (advisory lock)
Operator → move-task(in-progress → todo) → lifecycle guard → park with user-paused
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Domain store in core | @fusion/core task-store |
Single source of truth; dashboard/CLICommand-line interface never touch raw DB |
| Per-task advisory lock | task-advisory-lock.ts |
Prevents conflicting concurrent lifecycle mutations |
| Board move | moves.ts |
Supports per-task and board-level moves with guard rails |
| Soft-delete tombstone | keep tombstone | Preserves audit trail, prevents resurrect |
Risks and Unknowns
- Board-level move semantics across mixed workflow selections are not fully specified above.
Out of Scope
- Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns execution (see FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p2); lifecycle here is the board surface and its guards
- Specific merge behavior (see FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p5)
Test Plan: Task Board & Task Lifecycle Management
Scope
Covers task creation, lifecycle moves and guards, soft-delete/archive, comments and artifacts, search/filter, and the board/list rendering. Workflow-graph execution tests belong to FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p2.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Move task while planning rejects with guard | task in planning, invalid move | Move rejected, column unchanged |
| TC-2 | Delete task while planning rejected | planning task delete | Delete blocked |
| TC-3 | Task creation persists title/column | create payload | Task row with spec doc |
| TC-4 | Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md concurrency | concurrent doc writes | One writer wins under advisory lock |
| TC-5 | Soft-delete keeps tombstone | delete task | Tombstone present, row not resurrectable |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-6 | Task workflow routes expose move bypass guards | task exists | Route returns resolved column order / guard behavior |
| TC-7 | Task-not-found 404 | missing task id | 404 response |
| TC-8 | APIApplication programming interface task mutations from the SPA | live dashboard | Task created and rendered on board |
| TC-9 | Board move across columns | multiple tasks | Board order reflects resolved column order |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-10 | ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column unsupported by the workflow | ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column rendered with degraded-mode flag |
| TC-11 | Concurrent lifecycle mutations on same task | Exactly one succeeds under advisory lock |
| TC-12 | Mobile viewport board | Board renders usable on mobile breakpoints |
Test Infrastructure
- Vitest;
@fusion/core/@fusion/engine/@fusion/dashboardpackage test suites - In-memory fakes and PostgreSQL-backed suites where required
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall let users create tasks via quick entry, a new-task modal, import, GitHub issues, and mission/research flows | TC-1, TC-3, TC-8 |
| FR-2MustThe system shall render tasks on a board (column-based) and a list view, with search and filtering | TC-6, TC-9, TC-12 |
| FR-3MustThe system shall persist a task's prompt/spec document, comments, artifacts, dependencies, subtasks, branch context, and file scope | TC-4 |
| FR-4MustThe system shall enforce lifecycle move rules and guards (column eligibility, dependencies, user pause semantics) | TC-1, TC-10, TC-11 |
| FR-6MustThe system shall support archiving and soft-delete with verification, keeping tombstones for audit | TC-2, TC-5 |
| FR-7ShouldThe system shall expose task operations through the dashboard APIApplication programming interface, CLICommand-line interface, and workflow routes | TC-6, TC-7, TC-8 |
| NFR-1MustTask lifecycleThe domain state machine modeling a task's progression and its status values mutations shall use per-task advisory locks to prevent conflicting concurrent moves | TC-4, TC-11 |
| NFR-3ShouldThe board shall work on desktop and mobile breakpoints | TC-12 |
Key Test Files
packages/core/src/__tests__/move-task-if-planning.test.ts,delete-task-if-planning.test.ts,task-creation,task-document-concurrencypackages/dashboard/src/routes/__tests__/register-task-workflow-routes*.test.tspackages/dashboard/app/__tests__/api-tasks.test.ts,board-mobile-*.test.ts,column-role-degraded-flags.test.tspackages/cli/src/commands/__tests__/task.test.ts,task-lifecycle.test.ts,task-lock-retry.test.ts
requirements
- How are board-level (multiple-task) moves reconciled with per-task workflow selection?
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Plugins & Extension Ecosystem
Overview
A plugin SDK and management system lets third-party plugins extend the dashboard and engine. First-party "pi extensions" route Fusion's agent commands into different coding-agent CLIs (Claude CLICommand-line interface, Droid CLICommand-line interface, Llama.cpp), and plugins (e.g. reports, even-realities-glasses) plug into the runtime via manifests, lifecycle hooks, routes, and tools.
Stakeholders
| Stakeholder | Interest |
|---|---|
| End user | Discovers, installs, enables, configures, updates, uninstalls plugins |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks author | Builds plugins using the SDK/manifest/hooks/routes/tools |
| Operator | Manages plugin permission and interop, and the pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI fleet |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall discover, install, enable, configure, update, and uninstall plugins from a plugin manager | Must | The system shall discover, install, enable, configure, update, and uninstall plugins from a plugin manager |
| FR-2MustThe system shall run plugins via a plugin runner with skill-body delivery and lifecycle hooks | Must | The system shall run plugins via a plugin runner with skill-body delivery and lifecycle hooks |
| FR-3MustThe system shall expose plugin authoring surfaces (manifest, SDK, routes, tools, dashboard UIUser interface/runtime contributions) | Must | The system shall expose plugin authoring surfaces (manifest, SDK, routes, tools, dashboard UIUser interface/runtime contributions) |
| FR-4MustThe system shall route agent commands into coding-agent CLIs via first-party pi extensions (Claude CLICommand-line interface, Droid CLICommand-line interface, Llama.cpp) | Must | The system shall route agent commands into coding-agent CLIs via first-party pi extensions (Claude CLICommand-line interface, Droid CLICommand-line interface, Llama.cpp) |
| FR-5ShouldThe system shall validate plugin interop and version pinning (pi versions pinned) | Should | The system shall validate plugin interop and version pinning (pi versions pinned) |
| FR-6ShouldThe system shall expose plugin/extension management in dashboard (PluginManager, PiExtensionsManager) and CLICommand-line interface | Should | The system shall expose plugin/extension management in dashboard (PluginManager, PiExtensionsManager) and CLICommand-line interface |
| FR-7ShouldThe system shall document authoring guidance and support MCPModel Context Protocol discovery isolation for in-process runtime plugins | Should | The system shall document authoring guidance and support MCPModel Context Protocol discovery isolation for in-process runtime plugins |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustPlugins must not be force-installed without user action and must run under the plugin runner's permissions | Must | Security | Plugins must not be force-installed without user action and must run under the plugin runner's permissions |
| NFR-2MustPluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks interop drift must be checked at lint time | Must | Maintainability | PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks interop drift must be checked at lint time |
| NFR-3ShouldMCPModel Context Protocol discovery for in-process plugins must be isolated per plugin | Should | Performance | MCPModel Context Protocol discovery for in-process plugins must be isolated per plugin |
Constraints
- PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks SDK and runtime are part of the monorepo;
plugins/*are bundled - Authoring guidance lives in
docs/PLUGIN_AUTHORING.md
Acceptance Criteria
- FR-1MustThe system shall discover, install, enable, configure, update, and uninstall plugins from a plugin manager
- Given a plugin catalog entry
- When the user installs/enables it
- Then the plugin is installed, enabled, and configurable from the manager
- FR-2MustThe system shall run plugins via a plugin runner with skill-body delivery and lifecycle hooks
- Given an active plugin
- When the plugin runner runs
- Then lifecycle hooks and skill bodies are delivered per the contract
- FR-4MustThe system shall route agent commands into coding-agent CLIs via first-party pi extensions (Claude CLICommand-line interface, Droid CLICommand-line interface, Llama.cpp)
- Given the
fnCLICommand-line interface with a pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI - When a command is issued
- Then it routes into the target coding-agent CLICommand-line interface
- Given the
- NFR-2MustPluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks interop drift must be checked at lint time
- Given the workspace
- When lint runs
- Then plugin interop drift checks pass
Conflicts
None identified yet.
Open Questions
- Which plugins are bundled first-party vs. external (reports, even-realities) is per-plugin; confirm the canonical list.
Specification: Plugins & Extension Ecosystem
Overview
The plugin SDK (packages/plugin-sdk/) defines the authoring contract; core plugin management stores manifests and lifecycle; the engine plugin runner executes plugins with skill-body delivery; and first-party pi extensions route commands into Claude CLICommand-line interface, Droid CLICommand-line interface, and Llama.cpp. Dashboard surfaces include PluginManager and PiExtensionsManager.
Architecture
Dashboard (PluginManager, PiExtensionsManager) + CLICommand-line interface (plugin)
│ register-plugin-routes, register-plugins-automation-routes
▼
@fusion/core/plugins (manifest, lifecycle, storage)
│
▼
@fusion/engine (plugin-runner, plugin-skill-integration, in-process-runtime
plugin MCPModel Context Protocol discovery isolation)
│
▼
pi extensions (pi-claude-cli, droid-cli, pi-llama-cpp) ──► coding-agent CLIs
APIApplication programming interface Contracts
GET /api/plugins
Response (200 OK)
| Field | Type | Description |
|---|---|---|
| plugins | array | Installed plugins with manifest/config |
POST /api/plugins/:id/enable
Request
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | yes | PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks id |
Response
| Status | Code | Description |
|---|---|---|
| 200 | OK | PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks enabled |
| 404 | NOT_FOUND | Unknown plugin |
Sequences
PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks run
plugin-runner → load manifest → lifecycle hooks → deliver skill body → routes/tools active
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| SDK contract | packages/plugin-sdk/ |
Shared authoring types/helpers |
| Runner in engine | plugin-runner.ts |
Isolates plugin execution from core |
| Interop lint | check-plugin-interop-drift |
Catches drift at lint time |
| Version pinning | check-pi-versions-pinned |
Keeps extension versions aligned |
Risks and Unknowns
- In-process plugin MCPModel Context Protocol discovery isolation is covered by engine tests; confirm the canonical plugin inventory.
Out of Scope
- Fleet orchestration (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p9) and settings/provider config (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p8)
Test Plan: Plugins & Extension Ecosystem
Scope
Covers plugin runner execution and skill-body delivery, plugin management routes/UIUser interface, pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI CLICommand-line interface routing (Claude CLICommand-line interface, Droid CLICommand-line interface, Llama.cpp), and skill/CLICommand-line interface command surfaces.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks runner | plugin manifest | Lifecycle hooks run, skill body delivered |
| TC-2 | MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards plugin runner wiring | merge + plugin | PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks invoked during merge |
| TC-3 | In-process runtime plugin MCPModel Context Protocol discovery isolation | plugin set | Per-plugin MCPModel Context Protocol discovery isolated |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-4 | PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks skill integration | plugin skill | Skill body delivered |
| TC-5 | PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks skill body delivery | skills | Body delivered per contract |
| TC-6 | Claude CLICommand-line interface extension | command | Routed into Claude CLICommand-line interface |
| TC-7 | Droid CLICommand-line interface extension | command | Routed into Droid CLICommand-line interface |
| TC-8 | Llama.cpp extension | command | Routed into Llama.cpp |
| TC-9 | PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks manager routes | plugin store | CRUD supported |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-10 | Broken plugin manifest | Runner reports and does not crash host |
| TC-11 | Missing extension binary | CLICommand-line interface surfaces clear error |
Test Infrastructure
- Vitest engine/dashboard/CLICommand-line interface suites;
packages/cli/src/commands/__tests__/*extension*
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall discover, install, enable, configure, update, and uninstall plugins from a plugin manager | TC-9 |
| FR-2MustThe system shall run plugins via a plugin runner with skill-body delivery and lifecycle hooks | TC-1, TC-2, TC-4, TC-5 |
| FR-3MustThe system shall expose plugin authoring surfaces (manifest, SDK, routes, tools, dashboard UIUser interface/runtime contributions) | TC-10 |
| FR-4MustThe system shall route agent commands into coding-agent CLIs via first-party pi extensions (Claude CLICommand-line interface, Droid CLICommand-line interface, Llama.cpp) | TC-6, TC-7, TC-8, TC-11 |
| NFR-2MustPluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks interop drift must be checked at lint time | plugin-interop-drift check |
Key Test Files
packages/engine/src/__tests__/plugin-runner.test.ts,plugin-skill-integration.test.ts,plugin-skill-body-delivery.test.ts,merger-plugin-runner-wiring.test.ts,in-process-runtime-plugin-mcp-discovery-isolation.test.tspackages/cli/src/commands/__tests__/plugin.test.ts,claude-cli-extension.test.ts,droid-cli-extension.test.ts,llama-cpp-extension.test.tspackages/dashboard/src/routes/__tests__/register-approval-routes...+ plugin route tests,packages/dashboard/app/__tests__/api-plugins,PluginManager.test
requirements
- Which plugins are bundled first-party vs. external (reports, even-realities) is per-plugin; confirm the canonical list.
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Knowledge Graph & MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend)
Overview
Fusion maintains a deterministic LLMLarge language model-free knowledge graph over its own source, docs, and FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) rationale comments so agents and operators can query code structure without invoking a model.
The graph lives in packages/core/src/knowledge-graph/ with a memory backend in packages/core/src/memory/ and the MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Keeper epic FN-8920 layered on top for provenance-tagged inferred semantics.
The runtime artifact at .fusion-knowledge/graph is regenerable via fn knowledge-graph build and stays gitignored.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Rebuilds the graph explicitly and browses it in the dashboard MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) tab |
| Agent executor | Queries structure and rationale in process without model calls |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Keeper | Adds inferred semantic edges with provenance tags on top of deterministic extraction |
Functional Requirements
Order rows by priority: Must first, then Should, then May.
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall extract file, module, symbol, doc-concept, and rationale nodes with structural edges using only deterministic parsers and no LLMLarge language model calls. | Must | The system shall extract file, module, symbol, doc-concept, and rationale nodes with structural edges using only deterministic parsers and no LLMLarge language model calls. |
| FR-2MustThe system shall rebuild incrementally by re-extracting only files whose SHA-256 fingerprints changed and pruning ownership of deleted files. | Must | The system shall rebuild incrementally by re-extracting only files whose SHA-256 fingerprints changed and pruning ownership of deleted files. |
| FR-3MustThe system shall expose an in-process query APIApplication programming interface with queryNodes, neighbors, and shortestPath that retains complete edge provenance. | Must | The system shall expose an in-process query APIApplication programming interface with queryNodes, neighbors, and shortestPath that retains complete edge provenance. |
| FR-4MustThe system shall let MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Keeper add inferred relates-to and rationale-supports edges that are always stamped with inferred provenance. | Must | The system shall let MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Keeper add inferred relates-to and rationale-supports edges that are always stamped with inferred provenance. |
| FR-5MustThe system shall extract FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) rationale nodes from TypeScript parser comment ranges and markdown HTML comments outside fenced code. | Must | The system shall extract FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) rationale nodes from TypeScript parser comment ranges and markdown HTML comments outside fenced code. |
| FR-6MustThe system shall provide the `fn knowledge-graph build` CLICommand-line interface command and keep the regenerable artifact gitignored with rebuild documented. | Must | The system shall provide the fn knowledge-graph build CLICommand-line interface command and keep the regenerable artifact gitignored with rebuild documented. |
Non-Functional Requirements
Order rows by priority: Must first, then Should, then May.
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustThe system shall produce byte-identical artifacts for identical source on rebuild. | Must | Determinism | The system shall produce byte-identical artifacts for identical source on rebuild. |
| NFR-2MustThe system shall keep the roughly 85MB runtime artifact untracked so clones never carry compounding graph history. | Must | Maintainability | The system shall keep the roughly 85MB runtime artifact untracked so clones never carry compounding graph history. |
| NFR-3MustThe system shall parse TypeScript and TSX with a parser only and never require a type checker. | Must | Portability | The system shall parse TypeScript and TSX with a parser only and never require a type checker. |
| NFR-4ShouldThe system shall write artifacts as sorted LF JSONJavaScript Object Notation with nodes and edges before the manifest so torn writes trigger full rebuild. | Should | Reliability | The system shall write artifacts as sorted LF JSONJavaScript Object Notation with nodes and edges before the manifest so torn writes trigger full rebuild. |
Constraints
- TypeScript and TSX are the only languages with symbol extraction.
- Relative import resolution covers lexical ts, tsx, and index candidates without package or alias resolution.
- Export star records a re-export relationship without expanding names.
Acceptance Criteria
Every FR and NFR shall have at least one acceptance criterion.
Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).
-
FR-1MustThe system shall extract file, module, symbol, doc-concept, and rationale nodes with structural edges using only deterministic parsers and no LLMLarge language model calls.
gherkin @FR-1MustThe system shall extract file, module, symbol, doc-concept, and rationale nodes with structural edges using only deterministic parsers and no LLMLarge language model calls. Scenario: Parser-only build over the repo Given a checkout of the Fusion source tree When the operator runs `fn knowledge-graph build --force` Then nodes and edges are produced with no model call and every edge carries extracted provenance -
FR-2MustThe system shall rebuild incrementally by re-extracting only files whose SHA-256 fingerprints changed and pruning ownership of deleted files.
gherkin @FR-2MustThe system shall rebuild incrementally by re-extracting only files whose SHA-256 fingerprints changed and pruning ownership of deleted files. Scenario: Incremental rebuild after one file change Given a built graph with a recorded manifest When one source file changes and the build runs again Then only that file is re-extracted while unchanged files are reused from fingerprints -
FR-3MustThe system shall expose an in-process query APIApplication programming interface with queryNodes, neighbors, and shortestPath that retains complete edge provenance.
gherkin @FR-3MustThe system shall expose an in-process query APIApplication programming interface with queryNodes, neighbors, and shortestPath that retains complete edge provenance. Scenario: Query APIApplication programming interface round trip Given a built graph artifact When a caller invokes queryNodes, neighbors, and shortestPath Then results return deterministic node and edge objects with source, owner, and provenance intact -
FR-4MustThe system shall let MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Keeper add inferred relates-to and rationale-supports edges that are always stamped with inferred provenance.
gherkin @FR-4MustThe system shall let MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Keeper add inferred relates-to and rationale-supports edges that are always stamped with inferred provenance. Scenario: Inferred edges stay labeled Given the deterministic extracted graph When MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Keeper writes semantic relationships Then every new edge is stamped inferred and model output can never appear as extracted -
FR-5MustThe system shall extract FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) rationale nodes from TypeScript parser comment ranges and markdown HTML comments outside fenced code.
gherkin @FR-5MustThe system shall extract FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) rationale nodes from TypeScript parser comment ranges and markdown HTML comments outside fenced code. Scenario: FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) rationale extraction Given source and markdown files with stamped FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) headers When the build runs Then each stamped header yields a rationale node linked by rationale-supports -
FR-6MustThe system shall provide the `fn knowledge-graph build` CLICommand-line interface command and keep the regenerable artifact gitignored with rebuild documented.
gherkin @FR-6MustThe system shall provide the `fn knowledge-graph build` CLICommand-line interface command and keep the regenerable artifact gitignored with rebuild documented. Scenario: CLICommand-line interface rebuild replaces the artifact Given a missing or stale .fusion-knowledge/graph directory When the operator runs `fn knowledge-graph build` Then nodes, edges, and manifest are regenerated without requiring a git pull of the artifact -
NFR-1MustThe system shall produce byte-identical artifacts for identical source on rebuild.
gherkin @NFR-1MustThe system shall produce byte-identical artifacts for identical source on rebuild. Scenario: Rebuild stability Given identical source input When the build runs twice in a row Then the resulting artifact bytes are identical with no timestamps or host metadata -
NFR-2MustThe system shall keep the roughly 85MB runtime artifact untracked so clones never carry compounding graph history.
gherkin @NFR-2MustThe system shall keep the roughly 85MB runtime artifact untracked so clones never carry compounding graph history. Scenario: ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage stays untracked Given a fresh clone of the repository When the operator checks git status after a graph build Then .fusion-knowledge/graph remains ignored and no graph payload is staged -
NFR-3MustThe system shall parse TypeScript and TSX with a parser only and never require a type checker.
gherkin @NFR-3MustThe system shall parse TypeScript and TSX with a parser only and never require a type checker. Scenario: No checker dependency Given TypeScript sources with unresolvable imports When the build runs Then extraction completes best-effort without loading a type checker -
NFR-4ShouldThe system shall write artifacts as sorted LF JSONJavaScript Object Notation with nodes and edges before the manifest so torn writes trigger full rebuild.
gherkin @NFR-4ShouldThe system shall write artifacts as sorted LF JSONJavaScript Object Notation with nodes and edges before the manifest so torn writes trigger full rebuild. Scenario: Torn write recovery Given an interrupted build that wrote nodes but no manifest When the next build starts Then the incomplete artifact is discarded and a full rebuild runs
Conflicts
None identified yet.
Open Questions
- Should the dashboard MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) tab ever trigger an automatic rebuild on missing artifacts instead of reporting a recoverable status.
- Should symbol extraction expand beyond TypeScript and TSX to additional languages.
- Should the deferred FR-29 and FR-34 bundle format be revived for capability-fabric integration.
Specification: Knowledge Graph & MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend)
Overview
The build discovers source, doc, script, plugin, and dashboard files, extracts per-file facts with parser-only extractors, derives module nodes from the final file set, synthesizes import edges from manifest import references, and persists sorted LF JSONJavaScript Object Notation for queries. Incremental rebuilds reuse fingerprints so only changed files are re-extracted.
Architecture
Discovery in file-discovery.ts feeds per-language extractors behind the extract-file.ts dispatcher, graph-builder.ts assembles nodes and edges, graph-manifest.ts persists fingerprints and import references, and graph-query.ts serves in-process reads. The inferred-edge-writer.ts module is the sole writer of inferred provenance for MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Keeper semantics. The dashboard MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) tab reads through a small manifest-validated artifact cache and never rebuilds implicitly.
Data Models
Node
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | string | PK, not null | Path-derived identifier with percent-escaped separators. |
| kind | enum | not null | One of file, module, symbol, doc-concept, or rationale. |
| source | object | not null | Repository-relative path, line, and column anchor. |
| attributes | object | nullable | Symbol kind, declaration count, FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) stamp, and synthetic flags. |
ID scheme uses file colon path, module colon directory, symbol path hash name, doc path hash slug tilde index, and rationale path hash area at stamp tilde index.
Edge
| Field | Type | Constraints | Description |
|---|---|---|---|
| kind | enum | not null | Structural contains, imports, and re-exports or semantic relates-to and rationale-supports. |
| source | string | FK to node, not null | Provenance origin of the relationship. |
| owner | enum | not null | Either file or derived ownership. |
| provenance | enum | not null | Either extracted for deterministic facts or inferred for MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Keeper semantics. |
Manifest
| Field | Type | Constraints | Description |
|---|---|---|---|
| fingerprints | map | not null | Per-file SHA-256 hashes driving incremental reuse. |
| importRefs | map | not null | Persisted import references used to synthesize edges every build. |
APIApplication programming interface Contracts
The normative contract is the in-process query APIApplication programming interface plus the CLICommand-line interface and dashboard HTTPHypertext Transfer Protocol surface summarized below.
| Method | Path | Purpose |
|---|---|---|
| CLICommand-line interface | fn knowledge-graph build [--force] [--dir <path>] [--json] |
Builds or rebuilds the graph artifact. |
| GET | /api/knowledge/graph/status | Reports artifact presence and staleness. |
| GET | /api/knowledge/graph/nodes | Returns a capped page of nodes. |
| GET | /api/knowledge/graph/node | Returns one node by identifier. |
| GET | /api/knowledge/graph/neighbors | Returns bounded neighbor edges. |
| GET | /api/knowledge/graph/path | Returns a bounded undirected shortest path. |
| POST | /api/knowledge/graph/build | Triggers an explicit rebuild including force. |
Error codes shared across endpoints:
| Status | Code | Description |
|---|---|---|
| 404 | GRAPH_NOT_BUILT | ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage is missing and the operator should rebuild explicitly. |
| 404 | NODE_NOT_FOUND | Requested node identifier does not exist in the graph. |
| 400 | INVALID_ARTIFACT | Persisted artifact failed shape validation and a full rebuild is required. |
Sequences
Build then extract then manifest then query
sequenceDiagram
autonumber
participant C as CLICommand-line interface
participant D as Discovery
participant E as Extractors
participant M as Manifest
participant Q as Query
C->>D: build [--force]
D->>E: dispatch per discovered file
E-->>D: file nodes, symbols, rationale
D->>M: compare SHA-256 fingerprints
M-->>D: reuse or re-extract set
D->>M: write nodes, edges, then manifest
Q->>M: validate manifest cache
M-->>Q: serve queryNodes and neighbors
Incremental rebuild
sequenceDiagram
autonumber
participant B as Builder
participant M as Manifest
participant S as Store
B->>M: load fingerprints and import refs
M-->>B: changed, added, and deleted sets
B->>S: replace facts only for changed files
B->>S: prune ownership of deleted files
B->>S: re-derive modules and synthesize edges
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| TypeScript parsing | Parser only with no checker | Keeps extraction fast, deterministic, and independent of type resolution. |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage tracking | Gitignored regenerable directory | Avoids roughly 85MB of compounding history bloat for reproducible output. |
| Serialization | Sorted LF JSONJavaScript Object Notation with manifest last | Guarantees stable bytes and makes torn writes fail validation safely. |
| Recovery | Full rebuild on invalid or inconsistent artifact | Prevents partial trust in persisted nodes, edges, or import references. |
| Provenance | Single inferred-edge writer | Stops model output from ever masquerading as deterministic extraction. |
Risks and Unknowns
- The roughly 85MB artifact keeps query latency dependent on the manifest-validated cache rather than whole-graph loads.
- Lexical import resolution cannot follow tsconfig aliases, packages, or expanded export-star names.
- Duplicate exports collapse to the earliest position, which preserves determinism but loses per-declaration fidelity.
- Dashboard path queries use a bounded BFS that can report limit-reached instead of a complete path.
Out of Scope
- LLMLarge language model calls, embeddings, vector recall, and MCPModel Context Protocol tools.
- Source-validity diagnostics and CommonMark parsing.
- Languages beyond TypeScript and TSX symbol extraction.
- Cross-rename identity and the deferred FR-29 and FR-34 bundle format.
- Whole-graph force-directed canvas rendering in the dashboard.
Test Plan: Knowledge Graph & MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend)
Scope
This plan covers deterministic extraction, incremental rebuild, query behavior, artifact recovery, inferred-edge provenance, and the memory backend tests observed in the tree. Dashboard rendering and whole-graph canvas behavior are out of scope.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Module derivation from file set | derive-modules.test.ts fixture files | Stable module nodes derived every build. |
| TC-2 | Dispatcher composition across languages | extract-file-composition.test.ts mixed fixtures | Exactly one file node per discovered file. |
| TC-3 | FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) rationale extraction | extract-fnxc.test.ts comment fixtures | One rationale node per stamped header. |
| TC-4 | Markdown extraction outside fenced code | extract-markdown.test.ts markdown fixtures | Concepts and rationale only outside code spans. |
| TC-5 | TypeScript symbol extraction | extract-typescript.test.ts TS fixtures | Exported declarations become collapsed symbol nodes. |
| TC-6 | File discovery surface | file-discovery.test.ts repo layout | Package sources, scripts, plugins, docs, and dashboard app are included. |
| TC-7 | Graph node and edge identity | graph-identity.test.ts colliding fixtures | Deterministic path-derived identifiers with escaped separators. |
| TC-8 | Query APIApplication programming interface behavior | graph-query.test.ts built graph | queryNodes, neighbors, and shortestPath retain full provenance. |
| TC-9 | ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage serialization stability | graph-serialization.test.ts graph fixtures | Sorted LF JSONJavaScript Object Notation with content-derived values only. |
| TC-10 | Inferred-edge writer provenance | inferred-edge-writer.test.ts semantic inputs | Every written edge is stamped inferred unconditionally. |
| TC-11 | Import reference resolution | resolve-imports.test.ts relative imports | Lexical ts, tsx, and index candidates resolve without aliases. |
| TC-12 | MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) stash backend persistence | memory-backend-stash.test.ts session fixtures | Session capture persists and reloads through the stash backend. |
| TC-13 | MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) topic search | memory-search-topic.test.ts indexed records | Topic queries return the expected stored records. |
| TC-14 | Stash settings handling | stash-settings.test.ts settings fixtures | Stash configuration round-trips without loss. |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-15 | Builder equivalence between full and incremental runs | graph-builder-equivalence.test.ts with prior artifact | Incremental output matches a forced full rebuild byte for byte. |
| TC-16 | Incremental rebuild and deletion pruning | graph-builder-incremental.test.ts with changed tree | Only changed files re-extract and deleted ownership is pruned. |
| TC-17 | Store recovery on invalid artifacts | graph-store-recovery.test.ts with corrupt payloads | Shape violations and contradictions trigger complete rebuild. |
| TC-18 | ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage gitignore policy | graph-artifact-not-gitignored.test.ts with git check | Runtime graph directory stays ignored and rebuild is documented. |
End-to-End Tests
| ID | Description | Steps | Expected Outcome |
|---|---|---|---|
| TC-19 | CLICommand-line interface rebuild from scratch | Run fn knowledge-graph build --force on a checkout |
Nodes, edges, and manifest regenerate and queries succeed. |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-20 | Malformed TypeScript source with syntax errors | Extraction completes best-effort without blocking the build. |
| TC-21 | Interrupted build leaves nodes without a manifest | The next build discards the partial set and runs a full rebuild. |
Test Infrastructure
- Fixture trees for TypeScript, markdown, FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) comments, imports, and corrupt artifacts.
- Prior-artifact harness comparing incremental output against forced full rebuilds.
- Git ignore assertions proving the runtime artifact stays untracked.
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall extract file, module, symbol, doc-concept, and rationale nodes with structural edges using only deterministic parsers and no LLMLarge language model calls. | TC-2, TC-4, TC-5, TC-6 |
| FR-2MustThe system shall rebuild incrementally by re-extracting only files whose SHA-256 fingerprints changed and pruning ownership of deleted files. | TC-15, TC-16, TC-1, TC-11 |
| FR-3MustThe system shall expose an in-process query APIApplication programming interface with queryNodes, neighbors, and shortestPath that retains complete edge provenance. | TC-8, TC-7 |
| FR-4MustThe system shall let MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Keeper add inferred relates-to and rationale-supports edges that are always stamped with inferred provenance. | TC-10 |
| FR-5MustThe system shall extract FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) rationale nodes from TypeScript parser comment ranges and markdown HTML comments outside fenced code. | TC-3, TC-4 |
| FR-6MustThe system shall provide the `fn knowledge-graph build` CLICommand-line interface command and keep the regenerable artifact gitignored with rebuild documented. | TC-18, TC-19 |
| NFR-1MustThe system shall produce byte-identical artifacts for identical source on rebuild. | TC-9, TC-15 |
| NFR-2MustThe system shall keep the roughly 85MB runtime artifact untracked so clones never carry compounding graph history. | TC-18 |
| NFR-3MustThe system shall parse TypeScript and TSX with a parser only and never require a type checker. | TC-5, TC-20 |
| NFR-4ShouldThe system shall write artifacts as sorted LF JSONJavaScript Object Notation with nodes and edges before the manifest so torn writes trigger full rebuild. | TC-9, TC-17, TC-21 |
requirements
- Should the dashboard Memory tab ever trigger an automatic rebuild on missing artifacts instead of reporting a recoverable status.
- Should symbol extraction expand beyond TypeScript and TSX to additional languages.
- Should the deferred FR-29 and FR-34 bundle format be revived for capability-fabric integration.
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store Rooms & Messaging
Overview
Operators and agents need persistent, multi-participant conversation spaces outside of task-scoped planning chat. ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store rooms provide team discussion with membership, message history with pagination, file attachments, and AI-generated replies, while saved messaging scripts let operators reuse canned commands. This feature was reverse-engineered from shipped code during sync-sdlc.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Solo developer | Discusses work with agents in a persistent room instead of ephemeral task comments |
| Operator / power user | Reuses saved scripts and reviews room history across sessions |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall let operators create, read, update, and delete chat rooms with slug-collision protection. | Must | The system shall let operators create, read, update, and delete chat rooms with slug-collision protection. |
| FR-2MustThe system shall manage room membership (list, add, and remove agent members). | Must | The system shall manage room membership (list, add, and remove agent members). |
| FR-3MustThe system shall store and paginate room messages and support deleting a single message or clearing a room. | Must | The system shall store and paginate room messages and support deleting a single message or clearing a room. |
| FR-4ShouldThe system shall support file attachments on rooms and messages with MIME-type and size validation and path-traversal protection. | Should | The system shall support file attachments on rooms and messages with MIME-type and size validation and path-traversal protection. |
| FR-5ShouldThe system shall generate AI replies in rooms and surface generation failures as typed errors. | Should | The system shall generate AI replies in rooms and surface generation failures as typed errors. |
| FR-6ShouldThe system shall let operators save, list, and run named messaging scripts (name to command mappings). | Should | The system shall let operators save, list, and run named messaging scripts (name to command mappings). |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustThe system shall validate attachment paths so a crafted filename cannot escape the room attachment directory. | Must | Security | The system shall validate attachment paths so a crafted filename cannot escape the room attachment directory. |
| NFR-2ShouldMutating chat endpoints shall be rate-limited separately from read endpoints. | Should | Performance | Mutating chat endpoints shall be rate-limited separately from read endpoints. |
Constraints
- Room attachment storage lives under the project
.fusion/chat-room-attachmentsdirectory. - ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store message metadata is validated against the core message schema.
Acceptance Criteria
- FR-1MustThe system shall let operators create, read, update, and delete chat rooms with slug-collision protection.
@FR-1MustThe system shall let operators create, read, update, and delete chat rooms with slug-collision protection.
Scenario: Create a room with a duplicate slug
Given a room with slug "standup" exists
When an operator creates another room with slug "standup"
Then the request is rejected as a slug collision
- FR-3MustThe system shall store and paginate room messages and support deleting a single message or clearing a room.
@FR-3MustThe system shall store and paginate room messages and support deleting a single message or clearing a room.
Scenario: Paginate room messages
Given a room with more messages than one page holds
When an operator fetches messages with a page cursor
Then only that page is returned with a cursor for the next page
- NFR-1MustThe system shall validate attachment paths so a crafted filename cannot escape the room attachment directory.
@NFR-1MustThe system shall validate attachment paths so a crafted filename cannot escape the room attachment directory.
Scenario: Reject a traversal filename
Given an operator uploads an attachment named "../../secret"
When the upload is processed
Then the request is rejected and nothing is written outside the room directory
Open Questions
- Should chat rooms link to tasks or missions, or stay standalone team spaces?
Specification: ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store Rooms & Messaging
Overview
ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store persistence lives in @fusion/core (chat-store.ts, chat-types.ts) and is exposed through dashboard Express registrars (register-chat-room-routes.ts, register-messaging-scripts.ts, plus chat-project-services.ts for project scoping). AI replies are produced via the dashboard chat service with a typed RoomReplyGenerationError. Attachments are streamed to disk under .fusion/chat-room-attachments/<roomId> with basename and prefix validation.
Architecture
flowchart LR
UIUser interface[ChatView + chat services] -->|RESTRepresentational State Transfer /api/chat/rooms| Rooms[register-chat-room-routes]
UIUser interface -->|RESTRepresentational State Transfer /api/scripts| Scripts[register-messaging-scripts]
Rooms --> Store[chat-store in @fusion/core]
Rooms --> AI[dashboard chat service: AI replies]
Rooms --> Disk[.fusion/chat-room-attachments]
Data Models
ChatRoom
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | text | PK, not null | Room identifier |
| slug | text | unique, not null | Human-readable room key |
| status | text | not null | Room status |
| thinkingLevel | text | nullable | Per-room thinking level override |
ChatRoomMember
| Field | Type | Constraints | Description |
|---|---|---|---|
| roomId | text | FK, not null | Owning room |
| agentId | text | not null | Member agent |
ChatMessage
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | text | PK, not null | Message identifier |
| roomId | text | FK, not null | Owning room |
| metadata | json | validated | Validated message metadata |
APIApplication programming interface Contracts
Summary; full schemas live in the route implementations.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/chat/rooms | List rooms |
| POST | /api/chat/rooms | Create a room |
| GET | /api/chat/rooms/:id | Fetch one room |
| PATCH | /api/chat/rooms/:id | Update a room |
| DELETE | /api/chat/rooms/:id | Delete a room |
| GET/POST/DELETE | /api/chat/rooms/:id/members... | Manage membership |
| GET/POST/DELETE | /api/chat/rooms/:id/messages... | Manage messages |
| POST/GET | /api/chat/rooms/:id/attachments... | Upload and fetch attachments |
| GET/PUT/DELETE | /api/scripts... | Manage saved messaging scripts |
Key Sequences
- Post message: validate metadata, persist via chat-store, optionally trigger AI reply generation, return message or typed generation error.
- Upload attachment: check MIME allowlist and size caps, basename the filename, verify the resolved path stays under the room directory, stream to disk.
Technical Decisions
- Rate limits are split (
RATE_LIMITS.apifor reads,RATE_LIMITS.mutationfor writes). - Attachment validation is defense in depth: MIME allowlist plus size caps plus path containment.
- Only PlanningMode chat is covered by FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p3; team rooms are this feature's scope.
Risks and Unknowns
- Whether rooms should reference tasks or missions is undecided (see requirements open questions).
Test Plan: ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store Rooms & Messaging
Scope
Covers chat room CRUD, membership, message pagination and deletion, attachment validation, and AI reply failure surfacing. Out of scope: PlanningMode task chat (covered by FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p3).
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store memory focus behavior | Room with mixed message types | Focused messages selected per rule |
| TC-2 | Traversal filename rejected | Filename ../../secret |
Bad-request rejection, no write outside room dir |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-3 | Message tie pagination over PostgreSQL | Messages with identical timestamps | Stable paged order with cursor |
| TC-4 | Room CRUD round trip | Authenticated project context | Create, fetch, update, and delete succeed; duplicate slug rejected |
End-to-End Tests
| ID | Description | Steps | Expected Outcome |
|---|---|---|---|
| TC-5 | Operator chats with an agent in a room | Open ChatView, post a message, wait for reply | Message persists and AI reply renders or a typed error surfaces |
Coverage Matrix
| Requirement | Test cases |
|---|---|
| FR-1MustThe system shall let operators create, read, update, and delete chat rooms with slug-collision protection. | TC-4 |
| FR-2MustThe system shall manage room membership (list, add, and remove agent members). | TC-4 |
| FR-3MustThe system shall store and paginate room messages and support deleting a single message or clearing a room. | TC-3, TC-4 |
| FR-4ShouldThe system shall support file attachments on rooms and messages with MIME-type and size validation and path-traversal protection. | TC-2 |
| FR-5ShouldThe system shall generate AI replies in rooms and surface generation failures as typed errors. | TC-5 |
| NFR-1MustThe system shall validate attachment paths so a crafted filename cannot escape the room attachment directory. | TC-2 |
| NFR-2ShouldMutating chat endpoints shall be rate-limited separately from read endpoints. | TC-4 (rate-limited routes exercised) |
Test files: packages/core/src/chat/__tests__/chat-memory-focus.test.ts, packages/core/src/chat/__tests__/chat-message-tie-pagination.pg.test.ts.
requirements
- Should chat rooms link to tasks or missions, or stay standalone team spaces?
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Scheduled Automations & Routines
Overview
Operators need recurring work to run without being asked. This feature covers two related capabilities. An automation is a named schedule that runs a shell command or a list of steps on a cron expression. A routine is the richer form, with a trigger that can be a cron expression, an HMACHash-based message authentication code-signed webhook, an APIApplication programming interface call, or a manual signal, plus catch-up and concurrency policies and an assigned agent. Both are stored in a global lane and a project lane, both keep a bounded run history, and both surface live run output to the dashboard. This feature was reverse-engineered from shipped code during sync-sdlc.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Solo developer | Wants recurring commands, prompts, and task creation to run on a schedule without manual intervention |
| Operator / power user | Defines schedules and routines, chooses trigger and policy settings, and reads run history to confirm work happened |
| Maintainer / contributor | Keeps the scheduler, the stores, and the dashboard surface consistent and covered by tests |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall let operators create, read, update, and delete automations, each carrying a name, an optional description, a schedule type, a cron expression, either a command or a step list, an enabled flag, an optional timeout, and a global or project scope. | Must | The system shall let operators create, read, update, and delete automations, each carrying a name, an optional description, a schedule type, a cron expression, either a command or a step list, an enabled flag, an optional timeout, and a global or project scope. |
| FR-2MustThe system shall offer the preset schedule types hourly, daily, weekly, monthly, every15Minutes, every30Minutes, every2Hours, every6Hours, every12Hours, and weekdays, plus a custom schedule type whose cron expression the operator supplies, and shall derive the cron expression from the preset when the type is not custom. | Must | The system shall offer the preset schedule types hourly, daily, weekly, monthly, every15Minutes, every30Minutes, every2Hours, every6Hours, every12Hours, and weekdays, plus a custom schedule type whose cron expression the operator supplies, and shall derive the cron expression from the preset when the type is not custom. |
| FR-3MustThe system shall reject an automation with an empty name, an automation with neither a command nor steps, an automation with an unrecognised schedule type, and a custom automation whose cron expression does not parse. | Must | The system shall reject an automation with an empty name, an automation with neither a command nor steps, an automation with an unrecognised schedule type, and a custom automation whose cron expression does not parse. |
| FR-4MustThe system shall compute and store the next run time of an automation from its cron expression in UTC, and shall clear the next run time while the automation is disabled. | Must | The system shall compute and store the next run time of an automation from its cron expression in UTC, and shall clear the next run time while the automation is disabled. |
| FR-5MustThe system shall support multi-step automations whose steps run in order, where each step is a command step, an AI prompt step, or a create-task step, and shall stop the sequence after a failed step unless that step sets continueOnFailure. | Must | The system shall support multi-step automations whose steps run in order, where each step is a command step, an AI prompt step, or a create-task step, and shall stop the sequence after a failed step unless that step sets continueOnFailure. |
| FR-6MustThe system shall let an AI prompt step name a model provider and model, an optional thinking level, and an allowlist drawn from the selectable coding tools, and shall run the prompt with exactly that tool set. | Must | The system shall let an AI prompt step name a model provider and model, an optional thinking level, and an allowlist drawn from the selectable coding tools, and shall run the prompt with exactly that tool set. |
| FR-7MustThe system shall let a create-task step create a Fusion task carrying a title, a description, an optional target column, an optional model, and an optional thinking level, and shall attribute the new task to the originating schedule or routine. | Must | The system shall let a create-task step create a Fusion task carrying a title, a description, an optional target column, an optional model, and an optional thinking level, and shall attribute the new task to the originating schedule or routine. |
| FR-8MustThe system shall run an automation on demand and store the run result, including per-step results, in that automation's run history. | Must | The system shall run an automation on demand and store the run result, including per-step results, in that automation's run history. |
| FR-9MustThe system shall let an operator enable or disable an automation in one call, and shall recompute the next run time when the cadence changes or a disabled automation is re-enabled. | Must | The system shall let an operator enable or disable an automation in one call, and shall recompute the next run time when the cadence changes or a disabled automation is re-enabled. |
| FR-10MustThe system shall let an operator reorder the steps of a multi-step automation, and shall reject a reorder whose step IDs do not match the stored steps exactly. | Must | The system shall let an operator reorder the steps of a multi-step automation, and shall reject a reorder whose step IDs do not match the stored steps exactly. |
| FR-11MustThe system shall let operators create, read, update, and delete routines, each carrying a name, an optional description, an assigned agent, a trigger, either a command or a step list, a catch-up policy, an execution policy, an enabled flag, an optional timeout, and a global or project scope. | Must | The system shall let operators create, read, update, and delete routines, each carrying a name, an optional description, an assigned agent, a trigger, either a command or a step list, a catch-up policy, an execution policy, an enabled flag, an optional timeout, and a global or project scope. |
| FR-12MustThe system shall support the four routine trigger types cron, webhook, api, and manual, and shall validate the cron expression of a cron trigger and the secret of a webhook trigger. | Must | The system shall support the four routine trigger types cron, webhook, api, and manual, and shall validate the cron expression of a cron trigger and the secret of a webhook trigger. |
| FR-13MustThe system shall apply the routine catch-up policy, which is run, skip, or run_one, to occurrences the routine missed while it was not running. | Must | The system shall apply the routine catch-up policy, which is run, skip, or run_one, to occurrences the routine missed while it was not running. |
| FR-14MustThe system shall apply the routine execution policy, which is parallel, queue, or reject, when a run is requested while another run of the same routine is in progress. | Must | The system shall apply the routine execution policy, which is parallel, queue, or reject, when a run is requested while another run of the same routine is in progress. |
| FR-15MustThe system shall run a routine on demand and expose that routine's run history. | Must | The system shall run a routine on demand and expose that routine's run history. |
| FR-16MustThe system shall accept an HMACHash-based message authentication code-signed webhook call for a webhook-triggered routine, and shall refuse the call when the routine carries no secret, the signature header is missing, or the signature does not verify. | Must | The system shall accept an HMACHash-based message authentication code-signed webhook call for a webhook-triggered routine, and shall refuse the call when the routine carries no secret, the signature header is missing, or the signature does not verify. |
| FR-17MustThe system shall execute due automations and due routines on a poll interval, and shall skip execution while the engine is paused or the project is globally paused. | Must | The system shall execute due automations and due routines on a poll interval, and shall skip execution while the engine is paused or the project is globally paused. |
| FR-18MustThe system shall claim a due occurrence in storage before executing it, so that concurrent pollers, overlapping scopes, and separate engine processes do not run the same occurrence twice. | Must | The system shall claim a due occurrence in storage before executing it, so that concurrent pollers, overlapping scopes, and separate engine processes do not run the same occurrence twice. |
| FR-19ShouldThe system shall stream live run output to the dashboard over server-sent events, including step boundaries, text deltas, tool activity, and the terminal result, and shall replay the buffered events to a client that attaches after the run started. | Should | The system shall stream live run output to the dashboard over server-sent events, including step boundaries, text deltas, tool activity, and the terminal result, and shall replay the buffered events to a client that attaches after the run started. |
| FR-20ShouldThe system shall keep automations and routines in a global lane and a project lane, and shall isolate reads and writes by the requested scope. | Should | The system shall keep automations and routines in a global lane and a project lane, and shall isolate reads and writes by the requested scope. |
| FR-21ShouldThe system shall record every automation and routine configuration change as a versioned revision, so an operator can restore an earlier definition of the same entity. | Should | The system shall record every automation and routine configuration change as a versioned revision, so an operator can restore an earlier definition of the same entity. |
| FR-22ShouldThe system shall show automations and routines in the dashboard Automations view, with editors for both, a scope control, run controls, and a run history list. | Should | The system shall show automations and routines in the dashboard Automations view, with editors for both, a scope control, run controls, and a run history list. |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustThe system shall require a webhook secret of at least 16 characters when a routine is created or updated with a webhook trigger, and shall refuse a webhook call that does not carry a valid signature. | Must | Security | The system shall require a webhook secret of at least 16 characters when a routine is created or updated with a webhook trigger, and shall refuse a webhook call that does not carry a valid signature. |
| NFR-2MustThe system shall execute routine commands through a sandboxed backend rather than a bare shell, and shall record the sandbox prepare, run, and failure events in the run audit. | Must | Security | The system shall execute routine commands through a sandboxed backend rather than a bare shell, and shall record the sandbox prepare, run, and failure events in the run audit. |
| NFR-3MustThe system shall not let a project-scoped request read or change a global-scoped automation or routine, and shall not let a global-scoped request read or change a project-scoped one. | Must | Security | The system shall not let a project-scoped request read or change a global-scoped automation or routine, and shall not let a global-scoped request read or change a project-scoped one. |
| NFR-4MustThe system shall bound a run that hangs by a timeout, defaulting to 5 minutes, and shall allow a per-step timeout to override the schedule or routine timeout. | Must | Reliability | The system shall bound a run that hangs by a timeout, defaulting to 5 minutes, and shall allow a per-step timeout to override the schedule or routine timeout. |
| NFR-5MustThe system shall treat a due occurrence as claimed before execution so that a second poller observes the claim loss and skips the occurrence. | Must | Reliability | The system shall treat a due occurrence as claimed before execution so that a second poller observes the claim loss and skips the occurrence. |
| NFR-6MustThe system shall cap the command output buffer at 1 MB and the stored run output at 10 KB, marking truncated output as such. | Must | Performance | The system shall cap the command output buffer at 1 MB and the stored run output at 10 KB, marking truncated output as such. |
| NFR-7MustThe system shall retain at most 50 run history entries per automation and at most 50 per routine, dropping the oldest entries first. | Must | Performance | The system shall retain at most 50 run history entries per automation and at most 50 per routine, dropping the oldest entries first. |
| NFR-8ShouldThe system shall isolate failures so that one failing automation or routine does not stop the rest of the poll cycle. | Should | Availability | The system shall isolate failures so that one failing automation or routine does not stop the rest of the poll cycle. |
| NFR-9ShouldThe system shall keep a completed live run replayable for a bounded window, so a dashboard client that attaches late still receives the terminal result. | Should | Availability | The system shall keep a completed live run replayable for a bounded window, so a dashboard client that attaches late still receives the terminal result. |
| NFR-10ShouldThe system shall poll for due work no more often than every 10 seconds, and shall default to a 60 second interval. | Should | Performance | The system shall poll for due work no more often than every 10 seconds, and shall default to a 60 second interval. |
| NFR-11ShouldThe system shall log each scheduled execution, each lost claim, and each skip decision through the engine logger. | Should | Observability | The system shall log each scheduled execution, each lost claim, and each skip decision through the engine logger. |
| NFR-12ShouldThe system shall surface the durable outcome of a global routine in the backup settings surface, so an operator can distinguish a scheduled routine from a proven run. | Should | Observability | The system shall surface the durable outcome of a global routine in the backup settings surface, so an operator can distinguish a scheduled routine from a proven run. |
Constraints
- Automations and routines live in PostgreSQL. The legacy SQLite read path is not available, and a configuration change is refused when the versioned configuration backend is absent.
- A project lane row is partitioned by project ID, so the same automation or routine ID can exist in two projects without either project addressing the other row.
- Global routines live in the central
global_routinestable, not in the projectroutinestable. - The global routine name is unique, so a shared-cluster routine cannot be duplicated.
- The dashboard mounts the automation and routine routes under
/api. - The scope is read from the
scopequery parameter or thescopebody field, and an unrecognised value is a request error. - A cron trigger is evaluated in UTC. The routine trigger also carries an optional timezone, which the persisted cron computation does not apply.
- The scheduler runs on the utility lane and does not consume the task-lane semaphore.
Acceptance Criteria
- FR-1MustThe system shall let operators create, read, update, and delete automations, each carrying a name, an optional description, a schedule type, a cron expression, either a command or a step list, an enabled flag, an optional timeout, and a global or project scope.
@FR-1MustThe system shall let operators create, read, update, and delete automations, each carrying a name, an optional description, a schedule type, a cron expression, either a command or a step list, an enabled flag, an optional timeout, and a global or project scope.
Scenario: Create an automation
Given the dashboard APIApplication programming interface is running
When an operator posts an automation with a name, a schedule type, and a command
Then the response is 201 with the stored automation including its id, scope, and created timestamps
- FR-2MustThe system shall offer the preset schedule types hourly, daily, weekly, monthly, every15Minutes, every30Minutes, every2Hours, every6Hours, every12Hours, and weekdays, plus a custom schedule type whose cron expression the operator supplies, and shall derive the cron expression from the preset when the type is not custom.
@FR-2MustThe system shall offer the preset schedule types hourly, daily, weekly, monthly, every15Minutes, every30Minutes, every2Hours, every6Hours, every12Hours, and weekdays, plus a custom schedule type whose cron expression the operator supplies, and shall derive the cron expression from the preset when the type is not custom.
Scenario: Derive the cron expression from a preset
Given an operator creates an automation with schedule type "daily"
Then the stored automation carries the cron expression "0 0 * * *"
- FR-3MustThe system shall reject an automation with an empty name, an automation with neither a command nor steps, an automation with an unrecognised schedule type, and a custom automation whose cron expression does not parse.
@FR-3MustThe system shall reject an automation with an empty name, an automation with neither a command nor steps, an automation with an unrecognised schedule type, and a custom automation whose cron expression does not parse.
Scenario: Reject an automation with no work to do
Given an operator posts an automation with a name and no command and no steps
Then the response is 400 with a message that the command is required
- FR-4MustThe system shall compute and store the next run time of an automation from its cron expression in UTC, and shall clear the next run time while the automation is disabled.
@FR-4MustThe system shall compute and store the next run time of an automation from its cron expression in UTC, and shall clear the next run time while the automation is disabled.
Scenario: Compute the next run time
Given an operator creates an enabled automation with a valid cron expression
Then the stored automation carries a nextRunAt in the future
- FR-5MustThe system shall support multi-step automations whose steps run in order, where each step is a command step, an AI prompt step, or a create-task step, and shall stop the sequence after a failed step unless that step sets continueOnFailure.
@FR-5MustThe system shall support multi-step automations whose steps run in order, where each step is a command step, an AI prompt step, or a create-task step, and shall stop the sequence after a failed step unless that step sets continueOnFailure.
Scenario: Stop after a failed step
Given an automation has two command steps and the first step fails
When the automation runs
Then the second step does not run and the run result records one failed step
- FR-6MustThe system shall let an AI prompt step name a model provider and model, an optional thinking level, and an allowlist drawn from the selectable coding tools, and shall run the prompt with exactly that tool set.
@FR-6MustThe system shall let an AI prompt step name a model provider and model, an optional thinking level, and an allowlist drawn from the selectable coding tools, and shall run the prompt with exactly that tool set.
Scenario: Restrict the tools an AI prompt step may use
Given an AI prompt step names an allowlist of one selectable coding tool
When the step runs
Then the agent session receives exactly that tool allowlist
- FR-7MustThe system shall let a create-task step create a Fusion task carrying a title, a description, an optional target column, an optional model, and an optional thinking level, and shall attribute the new task to the originating schedule or routine.
@FR-7MustThe system shall let a create-task step create a Fusion task carrying a title, a description, an optional target column, an optional model, and an optional thinking level, and shall attribute the new task to the originating schedule or routine.
Scenario: Create a task from a create-task step
Given a create-task step carries a description and no target column
When the step runs
Then a Fusion task is created in the workflow intake column and its source records the schedule and step
- FR-8MustThe system shall run an automation on demand and store the run result, including per-step results, in that automation's run history.
@FR-8MustThe system shall run an automation on demand and store the run result, including per-step results, in that automation's run history.
Scenario: Record a manual run
Given an operator posts a manual run for an existing automation
Then the response carries the run result and the live run id, and the automation's run history holds the result
- FR-9MustThe system shall let an operator enable or disable an automation in one call, and shall recompute the next run time when the cadence changes or a disabled automation is re-enabled.
@FR-9MustThe system shall let an operator enable or disable an automation in one call, and shall recompute the next run time when the cadence changes or a disabled automation is re-enabled.
Scenario: Toggle an automation
Given an operator posts a toggle for a disabled automation
Then the returned automation is enabled and carries a recomputed nextRunAt
- FR-10MustThe system shall let an operator reorder the steps of a multi-step automation, and shall reject a reorder whose step IDs do not match the stored steps exactly.
@FR-10MustThe system shall let an operator reorder the steps of a multi-step automation, and shall reject a reorder whose step IDs do not match the stored steps exactly.
Scenario: Reject a reorder with the wrong step count
Given an automation has two steps
When an operator posts a reorder with one step id
Then the response is 400 with a step ID count mismatch message
- FR-11MustThe system shall let operators create, read, update, and delete routines, each carrying a name, an optional description, an assigned agent, a trigger, either a command or a step list, a catch-up policy, an execution policy, an enabled flag, an optional timeout, and a global or project scope.
@FR-11MustThe system shall let operators create, read, update, and delete routines, each carrying a name, an optional description, an assigned agent, a trigger, either a command or a step list, a catch-up policy, an execution policy, an enabled flag, an optional timeout, and a global or project scope.
Scenario: Create a routine
Given an operator posts a routine with a name, a cron trigger, and an agent id
Then the response is 201 with the stored routine including its catch-up and execution policies
- FR-12MustThe system shall support the four routine trigger types cron, webhook, api, and manual, and shall validate the cron expression of a cron trigger and the secret of a webhook trigger.
@FR-12MustThe system shall support the four routine trigger types cron, webhook, api, and manual, and shall validate the cron expression of a cron trigger and the secret of a webhook trigger.
Scenario: Reject an unknown trigger type
Given an operator posts a routine with trigger type "queue"
Then the response is 400 listing the supported trigger types
- FR-13MustThe system shall apply the routine catch-up policy, which is run, skip, or run_one, to occurrences the routine missed while it was not running.
@FR-13MustThe system shall apply the routine catch-up policy, which is run, skip, or run_one, to occurrences the routine missed while it was not running.
Scenario: Skip missed occurrences
Given a routine has catch-up policy "skip" and missed one cron occurrence
When the scheduler ticks
Then the routine runs once for the current occurrence and not once for the missed one
- FR-14MustThe system shall apply the routine execution policy, which is parallel, queue, or reject, when a run is requested while another run of the same routine is in progress.
@FR-14MustThe system shall apply the routine execution policy, which is parallel, queue, or reject, when a run is requested while another run of the same routine is in progress.
Scenario: Reject a concurrent run
Given a routine has execution policy "reject" and a run is already in progress
When a second run is requested
Then the second run returns a failed result stating that the routine was rejected
- FR-15MustThe system shall run a routine on demand and expose that routine's run history.
@FR-15MustThe system shall run a routine on demand and expose that routine's run history.
Scenario: Read a routine's run history
Given a routine has recorded runs
When an operator fetches the routine's runs
Then the response is the routine's run history array
- FR-16MustThe system shall accept an HMACHash-based message authentication code-signed webhook call for a webhook-triggered routine, and shall refuse the call when the routine carries no secret, the signature header is missing, or the signature does not verify.
@FR-16MustThe system shall accept an HMACHash-based message authentication code-signed webhook call for a webhook-triggered routine, and shall refuse the call when the routine carries no secret, the signature header is missing, or the signature does not verify.
Scenario: Refuse an unsigned webhook call
Given a webhook-triggered routine with a secret
When a caller posts to the routine's webhook without a signature header
Then the response is 401
- FR-17MustThe system shall execute due automations and due routines on a poll interval, and shall skip execution while the engine is paused or the project is globally paused.
@FR-17MustThe system shall execute due automations and due routines on a poll interval, and shall skip execution while the engine is paused or the project is globally paused.
Scenario: Skip execution while the engine is paused
Given an automation is due
When the engine settings report the engine as paused
Then the automation does not execute
- FR-18MustThe system shall claim a due occurrence in storage before executing it, so that concurrent pollers, overlapping scopes, and separate engine processes do not run the same occurrence twice.
@FR-18MustThe system shall claim a due occurrence in storage before executing it, so that concurrent pollers, overlapping scopes, and separate engine processes do not run the same occurrence twice.
Scenario: Run a due occurrence once across two pollers
Given a schedule is due
When two pollers claim the same due window concurrently
Then only one of them executes the schedule
- FR-19ShouldThe system shall stream live run output to the dashboard over server-sent events, including step boundaries, text deltas, tool activity, and the terminal result, and shall replay the buffered events to a client that attaches after the run started.
@FR-19ShouldThe system shall stream live run output to the dashboard over server-sent events, including step boundaries, text deltas, tool activity, and the terminal result, and shall replay the buffered events to a client that attaches after the run started.
Scenario: Stream a manual run
Given an operator starts a manual automation run
When a client opens the run stream for that automation
Then the client receives step, output, and terminal events for the run
- FR-20ShouldThe system shall keep automations and routines in a global lane and a project lane, and shall isolate reads and writes by the requested scope.
@FR-20ShouldThe system shall keep automations and routines in a global lane and a project lane, and shall isolate reads and writes by the requested scope.
Scenario: Keep the scopes apart
Given a global automation and a project automation exist
When an operator lists automations with scope "project"
Then only the project automation is returned
- FR-21ShouldThe system shall record every automation and routine configuration change as a versioned revision, so an operator can restore an earlier definition of the same entity.
@FR-21ShouldThe system shall record every automation and routine configuration change as a versioned revision, so an operator can restore an earlier definition of the same entity.
Scenario: Roll back a routine definition
Given a routine was renamed after it was created
When an operator restores the earlier configuration revision
Then the routine carries its earlier name again
- FR-22ShouldThe system shall show automations and routines in the dashboard Automations view, with editors for both, a scope control, run controls, and a run history list.
@FR-22ShouldThe system shall show automations and routines in the dashboard Automations view, with editors for both, a scope control, run controls, and a run history list.
Scenario: Show the Automations view
Given an operator opens Automations from the left sidebar
Then the view lists the automations and routines for the selected scope
- NFR-1MustThe system shall require a webhook secret of at least 16 characters when a routine is created or updated with a webhook trigger, and shall refuse a webhook call that does not carry a valid signature.
@NFR-1MustThe system shall require a webhook secret of at least 16 characters when a routine is created or updated with a webhook trigger, and shall refuse a webhook call that does not carry a valid signature.
Scenario: Refuse a webhook routine with a short secret
Given an operator posts a routine with a webhook trigger and a secret of 8 characters
Then the response is 400 explaining the 16 character minimum
- NFR-2MustThe system shall execute routine commands through a sandboxed backend rather than a bare shell, and shall record the sandbox prepare, run, and failure events in the run audit.
@NFR-2MustThe system shall execute routine commands through a sandboxed backend rather than a bare shell, and shall record the sandbox prepare, run, and failure events in the run audit.
Scenario: Audit a command routine
Given a routine runs a shell command
Then the run audit holds sandbox prepare and sandbox run rows for the routine
- NFR-3MustThe system shall not let a project-scoped request read or change a global-scoped automation or routine, and shall not let a global-scoped request read or change a project-scoped one.
@NFR-3MustThe system shall not let a project-scoped request read or change a global-scoped automation or routine, and shall not let a global-scoped request read or change a project-scoped one.
Scenario: Refuse a cross-scope read
Given a global automation exists
When a request reads that automation with scope "project"
Then the response is 404
- NFR-4MustThe system shall bound a run that hangs by a timeout, defaulting to 5 minutes, and shall allow a per-step timeout to override the schedule or routine timeout.
@NFR-4MustThe system shall bound a run that hangs by a timeout, defaulting to 5 minutes, and shall allow a per-step timeout to override the schedule or routine timeout.
Scenario: Time out a hanging run
Given an automation runs a command that does not finish
When the automation timeout elapses
Then the run result reports a failure naming the timeout
- NFR-5MustThe system shall treat a due occurrence as claimed before execution so that a second poller observes the claim loss and skips the occurrence.
@NFR-5MustThe system shall treat a due occurrence as claimed before execution so that a second poller observes the claim loss and skips the occurrence.
Scenario: Skip a lost claim
Given a poller loses the atomic claim for a due window
Then that poller skips the schedule and records no run
- NFR-6MustThe system shall cap the command output buffer at 1 MB and the stored run output at 10 KB, marking truncated output as such.
@NFR-6MustThe system shall cap the command output buffer at 1 MB and the stored run output at 10 KB, marking truncated output as such.
Scenario: Truncate oversized output
Given a run produces more output than the stored output cap
Then the stored output is truncated and marked as truncated
- NFR-7MustThe system shall retain at most 50 run history entries per automation and at most 50 per routine, dropping the oldest entries first.
@NFR-7MustThe system shall retain at most 50 run history entries per automation and at most 50 per routine, dropping the oldest entries first.
Scenario: Cap the run history
Given an automation has recorded more runs than the history cap
Then its run history holds only the most recent entries
- NFR-8ShouldThe system shall isolate failures so that one failing automation or routine does not stop the rest of the poll cycle.
@NFR-8ShouldThe system shall isolate failures so that one failing automation or routine does not stop the rest of the poll cycle.
Scenario: Isolate one failing routine
Given two routines are due and the first one throws during processing
Then the second routine still executes in the same poll cycle
- NFR-9ShouldThe system shall keep a completed live run replayable for a bounded window, so a dashboard client that attaches late still receives the terminal result.
@NFR-9ShouldThe system shall keep a completed live run replayable for a bounded window, so a dashboard client that attaches late still receives the terminal result.
Scenario: Replay a finished run
Given a manual run has already finished
When a client opens the run stream with that run id
Then the client receives the buffered events and the terminal result
- NFR-10ShouldThe system shall poll for due work no more often than every 10 seconds, and shall default to a 60 second interval.
@NFR-10ShouldThe system shall poll for due work no more often than every 10 seconds, and shall default to a 60 second interval.
Scenario: Enforce the minimum poll interval
Given the scheduler is constructed with a 1 second poll interval
Then the effective poll interval is 10 seconds
- NFR-11ShouldThe system shall log each scheduled execution, each lost claim, and each skip decision through the engine logger.
@NFR-11ShouldThe system shall log each scheduled execution, each lost claim, and each skip decision through the engine logger.
Scenario: Log a skipped schedule
Given a schedule is skipped because another poller holds its claim
Then the engine logger records the skip with the schedule name and id
- NFR-12ShouldThe system shall surface the durable outcome of a global routine in the backup settings surface, so an operator can distinguish a scheduled routine from a proven run.
@NFR-12ShouldThe system shall surface the durable outcome of a global routine in the backup settings surface, so an operator can distinguish a scheduled routine from a proven run.
Scenario: Show the global backup routine outcome
Given the shared backup routine has recorded a run
When an operator opens the backup settings
Then the surface shows the routine's last run result
Conflicts
None identified yet.
Open Questions
- The routine trigger carries an optional timezone, but the persisted next-run computation always uses UTC. The code does not show whether the timezone is meant to shift the cron evaluation.
catchUpLimitis stored on the routine row with a default of 5, but the catch-up path in the routine runner bounds catch-up with a separate constant of 10 intervals. The code does not show which bound is authoritative.- The
apiroutine trigger stores an endpoint on the routine, but no route in the dashboard serves that endpoint separately from the generic manual trigger route.
Specification: Scheduled Automations & Routines
Overview
The domain types live in @fusion/core under packages/core/src/automation/. automation.ts holds the schedule, step, and run-result types plus the preset cron map. routine.ts holds the routine type, its four trigger types, and its catch-up and execution policies. automation-store.ts, routine-store.ts, and global-routine-store.ts persist them in PostgreSQL through the shared async data layer. The engine schedules the work in packages/engine/src/scheduling/: cron-runner.ts polls due automations, routine-scheduler.ts polls due routines, and routine-runner.ts executes a routine either as a command or step sequence or as a heartbeat run for its assigned agent. The dashboard exposes the HTTPHypertext Transfer Protocol surface in packages/dashboard/src/routes/register-plugins-automation.ts, with automation-live-run.ts owning the replayable server-sent event registry and automation-step-execution.ts owning step validation and manual step execution. The React surface is ScheduledTasksModal.tsx plus ScheduleForm.tsx, ScheduleStepsEditor.tsx, RoutineEditor.tsx, RoutineCard.tsx, and ScheduleCard.tsx.
Architecture
+---------------------------+
Browser -------->| Dashboard /api/automations |
| Dashboard /api/routines |
+------------+--------------+
|
register-plugins-automation.ts
|
+--------------------+---------------------+
| | |
AutomationStore RoutineStore GlobalRoutineStore
(project.automations) (project.routines) (central.global_routines)
| | |
+--------+-----------+---------------------+
|
PostgreSQL (Drizzle)
^
|
+--------------------------------+ +-------------------------------+
| CronRunner (project scope) | | RoutineScheduler (project) |
| - polls due automations | | - polls due routines |
| - claims the due window | | - claims the central window |
| - runs command or steps | | - runs catch-up then the run |
+--------------------------------+ +-------------+-----------------+
|
RoutineRunner
/ | \
command steps AI steps create-task steps
|
HeartbeatMonitor (agent routines)
Live output path:
POST /automations/:id/run --+
POST /routines/:id/trigger --+--> AutomationLiveRunRegistry (in memory, 60s TTL)
|
GET /automations/:id/run/stream --+--> text/event-stream (step, output, tool, complete|error)
GET /routines/:id/run/stream --+
Data Models
ScheduledTask (automation)
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | text | PK with projectId, not null | Automation identifier, a UUID |
| projectId | text | PK with id, not null, defaults to the session project setting | ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree partition key |
| name | text | not null | Operator-facing name |
| description | text | nullable | Optional description |
| scheduleType | text | not null | One of hourly, daily, weekly, monthly, custom, every15Minutes, every30Minutes, every2Hours, every6Hours, every12Hours, weekdays |
| cronExpression | text | not null | Cron expression, derived from the preset unless the type is custom |
| command | text | not null | Shell command for the legacy single-command mode |
| steps | jsonb | nullable | Ordered step list, present for multi-step automations |
| enabled | integer | default 1 | 1 when the automation is active, 0 when it is not |
| timeoutMs | integer | nullable | Per-automation execution timeout, default 300000 |
| nextRunAt | text | nullable | ISO-8601 next due time, cleared while disabled |
| lastRunAt | text | nullable | ISO-8601 start of the last run |
| lastRunResult | jsonb | nullable | Result of the most recent run |
| runCount | integer | default 0 | Number of recorded runs |
| runHistory | jsonb | default [] | Recent run results, newest first, capped at 50 |
| scope | text | default "project" | "global" or "project" |
| createdAt | text | not null | ISO-8601 creation timestamp |
| updatedAt | text | not null | ISO-8601 last update timestamp |
AutomationStep
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | text | not null | Step identifier, a UUID generated by the editor |
| type | text | not null | "command", "ai-prompt", or "create-task" |
| name | text | not null | Step label |
| command | text | optional | Shell command for a command step |
| prompt | text | optional | Prompt text for an AI prompt step |
| modelProvider | text | optional | Model provider override, must be paired with modelId |
| modelId | text | optional | Model identifier override, must be paired with modelProvider |
| thinkingLevel | text | optional | Reasoning effort override, one of the known thinking levels, absent means inherit |
| allowedTools | string[] | optional | Tool names the AI step may use, absent means all selectable tools, empty means none |
| taskTitle | text | optional | Title for the task a create-task step creates |
| taskDescription | text | optional | Description for the task a create-task step creates, required for that step type |
| taskColumn | text | optional | Target column, absent means the workflow intake column resolves it |
| timeoutMs | number | optional | Per-step timeout override |
| continueOnFailure | boolean | optional | When true the sequence continues after this step fails, default false |
AutomationRunResult and AutomationStepResult
| Field | Type | Constraints | Description |
|---|---|---|---|
| success | boolean | not null | Whether the run or step succeeded |
| output | string | not null | Combined output, truncated to 10 KB |
| error | text | optional | Failure message |
| startedAt | string | not null | ISO-8601 run start |
| completedAt | string | not null | ISO-8601 run end |
| stepResults | AutomationStepResult[] | optional | Per-step results, present for multi-step runs |
| stepId | text | not null | Step that produced a step result |
| stepName | text | not null | Step label |
| stepIndex | number | not null | Zero-based position of the step |
| stepStartedAt | string | not null | ISO-8601 step start |
| stepCompletedAt | string | not null | ISO-8601 step end |
RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | text | PK with projectId, not null | RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies identifier, a UUID |
| projectId | text | PK with id, not null | ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree partition key |
| agentId | text | not null, default "" | Agent that runs the routine, required when the routine has no command or steps |
| name | text | not null | Operator-facing name |
| description | text | nullable | Optional description |
| triggerType | text | not null | "cron", "webhook", "api", or "manual" |
| triggerConfig | jsonb | not null | Trigger payload, holding the cron expression and timezone, the webhook path and secret, or the APIApplication programming interface endpoint |
| command | text | nullable | Shell command for the command action mode |
| steps | jsonb | nullable | Ordered step list, present for multi-step routines |
| timeoutMs | integer | nullable | Per-routine execution timeout, default 300000 |
| catchUpPolicy | text | not null, default "run_one" | "run", "skip", or "run_one" |
| executionPolicy | text | not null, default "queue" | "parallel", "queue", or "reject" |
| catchUpLimit | integer | default 5 | Maximum catch-up executions when the policy is "run" |
| enabled | integer | default 1 | 1 when the routine is active, 0 when it is not |
| lastRunAt | text | nullable | ISO-8601 start of the last run |
| lastRunResult | jsonb | nullable | Result of the most recent run |
| nextRunAt | text | nullable | ISO-8601 next due time, set only for an enabled cron routine |
| runCount | integer | default 0 | Number of recorded runs |
| runHistory | jsonb | default [] | Recent run results, newest first, capped at 50 |
| scope | text | default "project" | "global" or "project" |
| createdAt | text | not null | ISO-8601 creation timestamp |
| updatedAt | text | not null | ISO-8601 last update timestamp |
GlobalRoutine (central.global_routines)
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | text | PK, not null | RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies identifier |
| name | text | not null, unique | Shared routine name, unique across the cluster |
| description | text | nullable | Optional description |
| agentId | text | not null, default "" | Agent that runs the routine |
| triggerType | text | not null | Trigger type, cron only for a due routine |
| triggerConfig | jsonb | not null | Trigger payload |
| command | text | nullable | Shell command for the routine action |
| enabled | integer | not null, default 1 | 1 when the routine is active |
| lastRunAt | text | nullable | ISO-8601 start of the last run |
| lastRunResult | jsonb | nullable | Result of the most recent run |
| nextRunAt | text | nullable | ISO-8601 next due time |
| runCount | integer | not null, default 0 | Number of recorded runs |
| runHistory | jsonb | not null, default [] | Recent run results |
| createdAt | text | not null | ISO-8601 creation timestamp |
| updatedAt | text | not null | ISO-8601 last update timestamp |
AutomationLiveRunRecord (in memory)
| Field | Type | Constraints | Description |
|---|---|---|---|
| runId | text | PK in the registry | Run identifier |
| scheduleId | text | not null | Automation or routine the run belongs to |
| status | string | not null | "running", "complete", or "error" |
| buffer | SessionEventBuffer | capacity 200 | Buffered server-sent events for replay |
| listeners | set | runtime only | Connected stream subscribers |
| output | string | capped at 10240 | Accumulated streamed text |
| startedAt | number | epoch milliseconds | Wall-clock start, used for the auto-attach freshness window |
APIApplication programming interface Contracts
The normative contract is in api.yaml (OpenAPI 3.1).
| Method | Path | Purpose |
|---|---|---|
| GET | /api/automations | List automations, optionally filtered by scope |
| POST | /api/automations | Create an automation, 201 on success |
| GET | /api/automations/:id | Read one automation |
| PATCH | /api/automations/:id | Update an automation |
| DELETE | /api/automations/:id | Delete an automation, returns the deleted record |
| POST | /api/automations/:id/run | Run an automation now, returns the schedule, the result, and the live run id |
| GET | /api/automations/:id/run/stream | Stream live run output over server-sent events |
| POST | /api/automations/:id/toggle | Flip the enabled flag |
| POST | /api/automations/:id/steps/reorder | Reorder the steps by step ID |
| GET | /api/routines | List routines, optionally filtered by scope |
| POST | /api/routines | Create a routine, 201 on success |
| GET | /api/routines/:id | Read one routine |
| PATCH | /api/routines/:id | Update a routine |
| DELETE | /api/routines/:id | Delete a routine, returns the deleted record |
| POST | /api/routines/:id/run | Run a routine now, an alias of the trigger route |
| POST | /api/routines/:id/trigger | Run a routine now, the canonical manual trigger |
| GET | /api/routines/:id/run/stream | Stream live run output over server-sent events |
| GET | /api/routines/:id/runs | Read the routine run history |
| POST | /api/routines/:id/webhook | Accept a signed webhook call for a webhook-triggered routine |
Error codes shared across endpoints:
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_INPUT | Missing name, missing trigger, invalid schedule or trigger type, invalid cron, invalid policy, invalid step payload, or a routine that is disabled |
| 401 | UNAUTHORIZED | Missing or invalid webhook signature, or a webhook routine with no secret |
| 404 | NOT_FOUND | The automation or routine does not exist, or it belongs to another scope |
| 500 | INTERNAL_ERROR | An unexpected failure inside the handler |
| 503 | STORE_UNAVAILABLE | No automation store, routine store, or routine runner is resolvable for the requested scope |
Key Sequences
Create a multi-step automation
Operator Dashboard route AutomationStore PostgreSQL
| | | |
|--POST /api/automations| | |
|--------------------->| validate name, type, | |
| | cron, and steps | |
| |--createSchedule---------->| |
| | |--BEGIN--------------->|
| | | upsert automation |
| | | append config revision|
| | |--COMMIT------------->|
|<--201 automation------| | |
Scheduled automation run
CronRunner AutomationStore PostgreSQL Shell / Agent
| | | |
|--getDueSchedules(scope)| | |
|----------------------->| | |
| |-----due rows------>| | |
|--claimDueSchedule(id, expectedNextRunAt)-------->| |
| |--conditional UPDATE---->| |
| |---claimed or lost--| | |
| (lost claim: skip) | | |
|--executeSchedule--------------------------------->|--run steps------->|
| | | |
|--recordRun(result)---->|--upsert------------->| |
| |--emit schedule:run | |
RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies catch-up and execution
RoutineScheduler RoutineRunner RoutineStore
| | |
|--handleCatchUp(routine)-> |
| |--executeRoutine(missed) for each missed interval
| | |
|--executeRoutine(id, "cron")-------------->|
| |--startRoutineExecution-->|
| |--run action or heartbeat->|
| |--completeRoutineExecution->|
| | |
(a failure in one routine is logged and the loop continues)
Signed webhook trigger
Caller Dashboard route RoutineStore RoutineRunner
| | | |
|--POST /api/routines/:id/webhook | |
| | read raw body and the | |
| | x-hub-signature-256 head | |
| |--getRoutine------------>| |
| | verify HMACHash-based message authentication code over the raw body |
| |--triggerWebhook----------------------------->|
|<--200 routine+result---| | |
Live run stream
Client LiveRunRegistry Runner
| | |
|--POST .../run----------->|--start(runId)-------->|
| | |--onStep/onText---->|
| |<--broadcast(step)----|
|--GET .../run/stream----->| |
| (replay buffer, then subscribe) |
|<--event: step----------| |
|<--event: output--------| |
|<--event: complete------|<--complete(result)----|
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Where the domain types live | @fusion/core under packages/core/src/automation/ |
The stores, the engine, and the dashboard all import them from one place, and the barrel file re-exports the whole domain |
| Storage engine | PostgreSQL through the shared async data layer | The legacy SQLite write path is refused for configuration changes, because it has no durable atomic revision transaction |
| Configuration history | Every create, update, and delete appends a configuration revision in the same transaction as the row write | A failed revision insert must not leave a definition with no restore point |
| Cross-process due-window guard | A conditional update that advances next run at claim time | An in-memory guard does not stop a second engine process from running the same still-due row |
| Shared global routines | A separate central table with a unique name | A project-partitioned table would create one copy per project, and the shared-cluster backup must be singular |
| Concurrency control | A per-entity promise chain in the stores, plus the atomic claim for due windows | The chain serializes writes to one entity, and the claim stops duplicate execution across processes |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies command execution | A sandbox backend rather than a bare shell | A routine command is operator-configured and runs unattended, so it must be isolated and audited |
| Live output transport | Server-sent events over an in-memory registry with a 60 second TTL | The manual run result contract stays unchanged, and a late client can still replay the buffered events |
| Live stream implementation | One generic handler factory parameterised by store, entity getter, and not-found message | The automation and routine streams are otherwise identical, so a fix applies to both |
| Step model resolution | Step override first, then the execution lane, then the workflow lane, then project and global defaults | A scheduled AI step has no task or runtime model context, so the lane baseline supplies the default |
| Create-task target column | The column is omitted when the step names none | The workflow's own intake column resolves it, and an explicit column is still honoured |
| APIApplication programming interface trigger surface | The api trigger type is stored with its endpoint, but no route reads that endpoint, so the effective APIApplication programming interface trigger surface is the generic manual trigger route |
The code defines no separate endpoint that reads the stored endpoint value |
| Webhook authentication | HMACHash-based message authentication code over the raw request body using the x-hub-signature-256 header |
The body must be signed exactly as it was sent, so the raw bytes are verified rather than a re-serialised object |
| Scope selection | A scope query parameter or body field, defaulting to project for writes and to no filter for legacy reads |
Reads without a scope keep the original behaviour, and writes without a scope default to the project lane |
| Poll interval | 60 second default, clamped to a 10 second minimum | A tight poll wastes work, and a minimum interval keeps several engines from hammering the table |
| Scheduler lane | The utility lane, outside the task-lane semaphore | Automation and routine execution is independent of task execution concurrency |
Risks and Unknowns
- The routine trigger carries an optional timezone, but every persisted cron computation uses UTC. The code does not show whether the timezone shifts the evaluation.
catchUpLimitis stored with a default of 5 while the catch-up path bounds catch-up with a separate constant of 10 intervals. The code does not show which bound is authoritative.- The
apitrigger type stores an endpoint that no route reads, so the effective APIApplication programming interface trigger surface is the generic manual trigger route. - A routine that names neither a command, nor steps, nor an agent is refused at execution time, but the create route accepts it.
- The
thinkingLevelstep field is applied to scheduled, routine, and manual AI prompt runs, and is mapped onto a spawned task, but the stored value is not validated on the routine store path the way the route validates it. - A global routine is read through the central store and is not part of the routine list route, so the dashboard shows global routines through the global lane store rather than the central table.
Out of Scope
- The task lifecycle, the workflow graph, and the merge pipeline that a create-task step feeds into.
- The external signal connectors, which ingest webhooks into triage tasks rather than into routines.
- The knowledge graph, memory, and evals subsystems, except where a scheduled eval batch runs as a command step.
- The multi-node mesh coordination beyond the shared global routine table and the atomic due-window claim.
- The database backup policy itself. The backup routine is only covered here as a scheduled entity that the engine reconciles and the settings surface reports.
- The plugin management endpoints that share the same registrar.
Test Plan: Scheduled Automations & Routines
Scope
This plan covers the shipped behaviour of automations and routines: the domain types and presets, the store contracts, the engine schedulers and runners, the dashboard HTTPHypertext Transfer Protocol routes, and the React surfaces for the Automations view.
Out of scope: the task lifecycle a create-task step feeds into, the external signal connectors, the knowledge graph and memory subsystems, and the plugin management endpoints that share the same route registrar.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | The preset map holds every schedule type except custom, and each value is a valid 5-field cron expression | AUTOMATION_PRESETS |
Ten presets, each mapping to the expected cron expression, and no custom key |
| TC-2 | The schedule type union covers the preset keys plus custom | ScheduleType |
Every non-custom preset is a valid schedule type, and custom is a schedule type without a preset |
| TC-3 | The selectable tool list is unique and holds the builtin coding tools | AUTOMATION_SELECTABLE_TOOLS |
The seven named tools with no duplicate |
| TC-4 | The run history cap is a positive integer | MAX_RUN_HISTORY |
50 |
| TC-5 | The domain types accept every documented field combination | ScheduledTaskCreateInput, AutomationStep, AutomationRunResult, AutomationStepResult, ScheduledTask |
Each type accepts the documented fields, including an explicit empty allowedTools array |
| TC-6 | The preset cron expressions land on the expected dates | Each preset expression over the next seven runs | The weekdays preset never lands on a weekend, the monthly preset lands on day one, the 15-minute and 2-hour presets advance by their interval, and every preset produces a future time |
| TC-7 | A routine step with a thinking level is forwarded to the AI executor and an omitted level stays unset | A routine with an ai-prompt step |
The executor receives the explicit level, and an omitted level is passed as undefined |
| TC-8 | A create-task step maps its thinking level onto the spawned task | A routine and a schedule with a create-task step |
The explicit level reaches the task input and an omitted level stays undefined |
| TC-9 | A create-task step that names no column sends no column | A routine and a schedule with a create-task step |
The task input carries no column so the workflow intake resolves it, while an explicit column is honoured |
| TC-10 | The dashboard client builds the automation and routine URLs with the requested scope | A client call for a global and a project scope | The URLs carry /api/automations and /api/routines with the matching scope and projectId |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-11 | The automation routes list, create, read, update, delete, toggle, and reorder | A dashboard app with an automation store | Each route answers with the stored automation, and a create answers 201 |
| TC-12 | The automation route rejects invalid input | A dashboard app with an automation store | A missing name, a missing command, an invalid schedule type, a missing custom cron, an invalid cron, an unknown allowed tool, and an invalid thinking level all answer 400 |
| TC-13 | The manual automation run executes steps and records the result | A dashboard app with an automation store and a live run registry | The response carries the schedule, the result, and the live run id, and the per-step results are recorded |
| TC-14 | The manual run streams buffered live events and a terminal error for an unknown run | A dashboard app with a live run registry | A completed run replays its buffered events, and an unknown run id produces a terminal error event |
| TC-15 | The routine routes list, create, read, update, delete, trigger, and read runs | A dashboard app with a routine store and a routine runner | Each route answers with the stored routine, and a create answers 201 |
| TC-16 | The routine route rejects invalid input | A dashboard app with a routine store | A missing name, a missing trigger, an invalid trigger type, a missing or invalid cron, a short webhook secret, an invalid catch-up policy, an invalid execution policy, and an invalid thinking level all answer 400 |
| TC-17 | The webhook route authenticates the caller | A dashboard app with a webhook-triggered routine | A valid signature runs the routine, a missing or wrong signature answers 401, and a routine without a secret answers 401 |
| TC-18 | The scope-aware routes keep the lanes apart | A dashboard app with both a global and a project store | A wrong-scope read answers 404, a wrong-scope write answers 404, a project read never returns a global entity, and a project mutation never reaches the global lane |
| TC-19 | The store-unavailable paths answer 503 | A dashboard app without a resolvable store | A project-scoped read answers 503, while an omitted or global read falls back to an empty array |
| TC-20 | The cron runner polls, claims, and executes due automations | A cron runner with a store and an automation store | A due schedule is claimed and executed, a lost claim is skipped, and a schedule with no next run time is neither claimed nor executed |
| TC-21 | The cron runner does not run the same due window twice across two runners | Two cron runners sharing one store | The due window executes once for a legacy command, once for a step schedule, and once for an in-process intercept |
| TC-22 | The cron runner executes multi-step automations | A schedule with several steps | The steps run in order, a failure stops the sequence unless continueOnFailure is set, and the per-step timeout overrides the schedule timeout |
| TC-23 | The cron runner resolves the model for an AI prompt step | A schedule with an AI prompt step | The step override wins, then the execution lane, then the settings default, and the allowed tool list and thinking level are forwarded |
| TC-24 | The cron runner honours the poll interval floor and the pause settings | A cron runner with a short poll interval and a paused store | The poll interval is clamped to 10 seconds, and a paused store or engine produces no execution |
| TC-25 | The routine runner executes a routine and persists the outcome | A routine runner with a store, a heartbeat monitor, and a routine store | The heartbeat runs with the routine source and trigger detail, the run state is persisted, and the in-flight map is cleared |
| TC-26 | The routine runner applies the concurrency policies | A routine runner with an in-flight execution | A parallel routine runs again, a queue routine waits, and a reject routine returns a failed result |
| TC-27 | The routine runner applies the catch-up policy | A routine with a missed occurrence | A run-one routine runs once for the missed interval, a run routine runs for each missed interval, and a skip routine runs only for the current occurrence |
| TC-28 | The routine scheduler polls the right lane and isolates failures | A routine scheduler with both a project and a central store | The central routine is claimed and completed once, a due routine is processed in order, and a failing routine does not stop the loop |
| TC-29 | The routine scheduler verifies the webhook signature | A routine scheduler with a configured secret | A valid signature is accepted, and a wrong or missing signature is refused |
| TC-30 | The routine command runs in the sandbox and is audited | A routine runner with a task store | The run audit holds the sandbox prepare and sandbox run rows, and a failure produces a sandbox failure row |
| TC-31 | The backup routine is reconciled and its outcome is surfaced | A backup settings surface with a global routine | The routine keeps its next run when the cron is unchanged, and the surface shows the last run result |
| TC-32 | The Automations view lists, edits, runs, toggles, and deletes | A dashboard app with the Automations view | The view reloads on a scope change, a run shows inline output, a delete asks for confirmation, and a toggle calls the update route |
| TC-33 | The Automations view reconciles a successful run that ends with a stream error | A dashboard app with a failed stream on a successful run | The card shows the complete state and never the failed state |
| TC-34 | The routine editor builds the trigger and the scope for each trigger type | The routine editor with the cron, webhook, APIApplication programming interface, and manual trigger modes | Each mode sends the matching trigger, the scope toggle is submitted, and the name and cron fields are validated |
| TC-35 | The step editor adds, edits, deletes, and reorders steps | The step editor with an existing step list | A step is added for each of the three types, a step moves up and down, the first and last move buttons are disabled, and the step count is shown |
| TC-36 | The step editor stores the tool allowlist and the thinking level | The step editor with an advanced AI prompt step | All tools selected stores an undefined allowlist, a narrowed selection stores that list, and a cleared selection stores an empty list |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-37 | A custom schedule type is created without a cron expression | The request answers 400 and no automation is stored |
| TC-38 | A reorder names a step id that does not exist | The request answers 400 and the stored steps are unchanged |
| TC-39 | A reorder names a different number of step ids than the stored steps | The request answers 400 with a step ID count mismatch |
| TC-40 | An update empties the name or leaves neither a command nor steps | The request answers 400 and the stored automation is unchanged |
| TC-41 | A run of a routine that is disabled is requested | The request answers 400 and no run is recorded |
| TC-42 | A webhook call reaches a routine that is not webhook-triggered | The request answers 400 |
| TC-43 | A webhook routine carries no secret | The request answers 401 and no run is recorded |
| TC-44 | An unknown step type is executed | The step result reports an unknown step type failure and the run is recorded as failed |
| TC-45 | A command step carries no command, an AI step carries no prompt, or a create-task step carries no description | The step result reports the missing field and the sequence stops unless continueOnFailure is set |
| TC-46 | An AI prompt step runs with no executor configured | The step result reports that AI execution is not configured |
| TC-47 | A command times out | The run result reports a failure naming the timeout and the partial output is kept |
| TC-48 | A run produces more output than the stored cap | The stored output is truncated and marked as truncated |
| TC-49 | A run history exceeds the cap | The oldest entries are dropped and the newest are kept |
| TC-50 | A recordRun call fails after a successful execution | The tick continues to the next schedule and the failure is logged |
| TC-51 | A post-run callback throws | The callback error is logged and the returned run result is unchanged |
| TC-52 | The step identifier generator is unavailable | A step is still added with a fallback identifier |
| TC-53 | A run is started and the stream attaches with no run id | The stream waits for the next run of that entity and does not replay an unrelated finished run |
Test Infrastructure
- The dashboard route tests mount the router under
/apiwith an Express app and use in-memory store doubles. - The engine scheduler and runner tests use in-memory store doubles and an injected AI prompt executor, so no shell command and no model call reaches a network.
- The React component tests use a testing-library render with mocked fetch, so no dashboard server is needed.
- The sandbox audit tests use a fake run auditor and a fake sandbox backend.
- The core domain tests are pure type and value assertions with no database.
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall let operators create, read, update, and delete automations, each carrying a name, an optional description, a schedule type, a cron expression, either a command or a step list, an enabled flag, an optional timeout, and a global or project scope. | TC-11, TC-15, TC-31 |
| FR-2MustThe system shall offer the preset schedule types hourly, daily, weekly, monthly, every15Minutes, every30Minutes, every2Hours, every6Hours, every12Hours, and weekdays, plus a custom schedule type whose cron expression the operator supplies, and shall derive the cron expression from the preset when the type is not custom. | TC-1, TC-2, TC-6, TC-34 |
| FR-3MustThe system shall reject an automation with an empty name, an automation with neither a command nor steps, an automation with an unrecognised schedule type, and a custom automation whose cron expression does not parse. | TC-12, TC-16, TC-37, TC-40 |
| FR-4MustThe system shall compute and store the next run time of an automation from its cron expression in UTC, and shall clear the next run time while the automation is disabled. | TC-1, TC-6, TC-11 |
| FR-5MustThe system shall support multi-step automations whose steps run in order, where each step is a command step, an AI prompt step, or a create-task step, and shall stop the sequence after a failed step unless that step sets continueOnFailure. | TC-22, TC-35, TC-44, TC-45 |
| FR-6MustThe system shall let an AI prompt step name a model provider and model, an optional thinking level, and an allowlist drawn from the selectable coding tools, and shall run the prompt with exactly that tool set. | TC-7, TC-10, TC-23, TC-36 |
| FR-7MustThe system shall let a create-task step create a Fusion task carrying a title, a description, an optional target column, an optional model, and an optional thinking level, and shall attribute the new task to the originating schedule or routine. | TC-8, TC-9, TC-23, TC-25 |
| FR-8MustThe system shall run an automation on demand and store the run result, including per-step results, in that automation's run history. | TC-13, TC-20 |
| FR-9MustThe system shall let an operator enable or disable an automation in one call, and shall recompute the next run time when the cadence changes or a disabled automation is re-enabled. | TC-11, TC-34 |
| FR-10MustThe system shall let an operator reorder the steps of a multi-step automation, and shall reject a reorder whose step IDs do not match the stored steps exactly. | TC-38, TC-39 |
| FR-11MustThe system shall let operators create, read, update, and delete routines, each carrying a name, an optional description, an assigned agent, a trigger, either a command or a step list, a catch-up policy, an execution policy, an enabled flag, an optional timeout, and a global or project scope. | TC-15, TC-34 |
| FR-12MustThe system shall support the four routine trigger types cron, webhook, api, and manual, and shall validate the cron expression of a cron trigger and the secret of a webhook trigger. | TC-16, TC-34 |
| FR-13MustThe system shall apply the routine catch-up policy, which is run, skip, or run_one, to occurrences the routine missed while it was not running. | TC-27 |
| FR-14MustThe system shall apply the routine execution policy, which is parallel, queue, or reject, when a run is requested while another run of the same routine is in progress. | TC-26 |
| FR-15MustThe system shall run a routine on demand and expose that routine's run history. | TC-13, TC-15, TC-25 |
| FR-16MustThe system shall accept an HMACHash-based message authentication code-signed webhook call for a webhook-triggered routine, and shall refuse the call when the routine carries no secret, the signature header is missing, or the signature does not verify. | TC-17, TC-42, TC-43 |
| FR-17MustThe system shall execute due automations and due routines on a poll interval, and shall skip execution while the engine is paused or the project is globally paused. | TC-20, TC-24, TC-28 |
| FR-18MustThe system shall claim a due occurrence in storage before executing it, so that concurrent pollers, overlapping scopes, and separate engine processes do not run the same occurrence twice. | TC-20, TC-21, TC-28 |
| FR-19ShouldThe system shall stream live run output to the dashboard over server-sent events, including step boundaries, text deltas, tool activity, and the terminal result, and shall replay the buffered events to a client that attaches after the run started. | TC-14, TC-32, TC-33, TC-53 |
| FR-20ShouldThe system shall keep automations and routines in a global lane and a project lane, and shall isolate reads and writes by the requested scope. | TC-18, TC-19, TC-32 |
| FR-21ShouldThe system shall record every automation and routine configuration change as a versioned revision, so an operator can restore an earlier definition of the same entity. | TC-31 |
| FR-22ShouldThe system shall show automations and routines in the dashboard Automations view, with editors for both, a scope control, run controls, and a run history list. | TC-32, TC-33, TC-34, TC-35 |
| NFR-1MustThe system shall require a webhook secret of at least 16 characters when a routine is created or updated with a webhook trigger, and shall refuse a webhook call that does not carry a valid signature. | TC-16, TC-17, TC-43 |
| NFR-2MustThe system shall execute routine commands through a sandboxed backend rather than a bare shell, and shall record the sandbox prepare, run, and failure events in the run audit. | TC-30 |
| NFR-3MustThe system shall not let a project-scoped request read or change a global-scoped automation or routine, and shall not let a global-scoped request read or change a project-scoped one. | TC-18 |
| NFR-4MustThe system shall bound a run that hangs by a timeout, defaulting to 5 minutes, and shall allow a per-step timeout to override the schedule or routine timeout. | TC-22, TC-47 |
| NFR-5MustThe system shall treat a due occurrence as claimed before execution so that a second poller observes the claim loss and skips the occurrence. | TC-20, TC-21 |
| NFR-6MustThe system shall cap the command output buffer at 1 MB and the stored run output at 10 KB, marking truncated output as such. | TC-48 |
| NFR-7MustThe system shall retain at most 50 run history entries per automation and at most 50 per routine, dropping the oldest entries first. | TC-49 |
| NFR-8ShouldThe system shall isolate failures so that one failing automation or routine does not stop the rest of the poll cycle. | TC-28, TC-50 |
| NFR-9ShouldThe system shall keep a completed live run replayable for a bounded window, so a dashboard client that attaches late still receives the terminal result. | TC-14, TC-53 |
| NFR-10ShouldThe system shall poll for due work no more often than every 10 seconds, and shall default to a 60 second interval. | TC-24, TC-28 |
| NFR-11ShouldThe system shall log each scheduled execution, each lost claim, and each skip decision through the engine logger. | TC-50, TC-51 |
| NFR-12ShouldThe system shall surface the durable outcome of a global routine in the backup settings surface, so an operator can distinguish a scheduled routine from a proven run. | TC-31 |
Key Test Files
| File | Covers |
|---|---|
packages/core/src/__tests__/automation.test.ts |
The presets, the schedule type union, the selectable tools, the run history cap, the domain type contracts, and the preset cron edge cases |
packages/core/src/__tests__/backup-schedule-status.test.ts |
The backup routine sync planning, the reconciliation, and the surfaced schedule status |
packages/engine/src/__tests__/cron-runner.test.ts |
The cron runner start and stop, the poll tick, the due-window claim, the multi-step execution, the AI prompt and create-task steps, the scoped lane polling, and the output truncation |
packages/engine/src/__tests__/routine-runner.test.ts |
The routine execution, the heartbeat contract, the concurrency policies, the catch-up behaviour, and the manual and cron backup parity |
packages/engine/src/__tests__/routine-scheduler.test.ts |
The scheduler tick, the central global routine claim, the scoped lane polling, the pause regressions, the lane isolation, and the webhook signature checks |
packages/engine/src/__tests__/routine-runner-sandbox-audit.test.ts |
The sandbox prepare, run, and failure audit events for command routines and command steps |
packages/engine/src/__tests__/sandbox-wiring.test.ts |
The sandbox wiring for the routine runner |
packages/engine/src/__tests__/sandbox-wiring-audit.test.ts |
The sandbox wiring audit for the routine runner |
packages/dashboard/src/__tests__/routes-automation.test.ts |
The automation and routine HTTPHypertext Transfer Protocol routes, the validation errors, the manual run, the live stream, the webhook verification, and the scope isolation |
packages/dashboard/app/__tests__/api-settings.test.ts |
The automation and routine request URLs and their scope parameters |
packages/dashboard/app/components/__tests__/ScheduledTasksModal.test.tsx |
The Automations view presentation, the scope controls, the run flow, the live output reconciliation, and the delete and toggle actions |
packages/dashboard/app/components/__tests__/ScheduleForm.test.tsx |
The automation form create, edit, validation, cron auto-fill, submission, cancel, scope toggle, multi-step, and simple-mode cases |
packages/dashboard/app/components/__tests__/ScheduleStepsEditor.test.tsx |
The step addition, deletion, reordering, editing state, validation, empty state, tool selection, and model selection |
packages/dashboard/app/components/__tests__/ScheduleCard.test.tsx |
The schedule card rendering, the last run badge, the action buttons, and the run history |
packages/dashboard/app/components/__tests__/RoutineEditor.test.tsx |
The routine editor create, edit, trigger modes, scope selector, validation, submission, and cancel cases |
packages/dashboard/app/components/__tests__/RoutineCard.test.tsx |
The routine card rendering, the policy badges, the live output states, the action buttons, and the run history |
requirements
- The routine trigger carries an optional timezone, but the persisted next-run computation always uses UTC. The code does not show whether the timezone is meant to shift the cron evaluation.
catchUpLimitis stored on the routine row with a default of 5, but the catch-up path in the routine runner bounds catch-up with a separate constant of 10 intervals. The code does not show which bound is authoritative.- The
apiroutine trigger stores an endpoint on the routine, but no route in the dashboard serves that endpoint separately from the generic manual trigger route.
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Multi-Repository Workspaces
Overview
A workspace is a Fusion project whose root directory is not a Git repository and whose direct child directories are Git repositories.
Fusion detects those member repositories, records them in .fusion/workspace.json, and gives every task one worktree per member.
Review runs once per modified member, each member lands on its own local integration ref under a durable write fence, and a partial land is recovered instead of lost.
An operator can also revert a workspace task across all of its members.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator / power user | Registers a multi-repository project, manages its member list, and reads per-repository landing and review status |
| Solo developer | Ships one change that spans several repositories from one task, one board, and one review |
| Maintainer / contributor | Keeps the multi-repository lifecycle consistent, tested, and documented |
| Git hosting remote | Receives the fenced publication of a member's integration ref when publication is enabled |
Functional Requirements
Order rows by priority: Must first, then Should.
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall detect the member repositories of a project root by scanning only its direct children, excluding `node_modules`, `.fusion`, `.git`, `.pi`, and `.worktrees`, requiring a `.git` marker and a passing Git work-tree probe, and returning the members in sorted order | Must | The system shall detect the member repositories of a project root by scanning only its direct children, excluding node_modules, .fusion, .git, .pi, and .worktrees, requiring a .git marker and a passing Git work-tree probe, and returning the members in sorted order |
| FR-2MustThe system shall record the member list in `.fusion/workspace.json` and read it back, accepting only entries that are strings and normalized relative paths inside the workspace root | Must | The system shall record the member list in .fusion/workspace.json and read it back, accepting only entries that are strings and normalized relative paths inside the workspace root |
| FR-3MustThe system shall enable and disable workspace mode for a project, writing the `workspaceMode` setting in `.fusion/config.json` and the authority file `.fusion/workspace.json` in a documented order and reconciling the two when they diverge | Must | The system shall enable and disable workspace mode for a project, writing the workspaceMode setting in .fusion/config.json and the authority file .fusion/workspace.json in a documented order and reconciling the two when they diverge |
| FR-4MustThe system shall add a member repository to an existing workspace idempotently, accepting only an in-root direct child that is a Git work tree and rejecting excluded names, absolute paths, and `..` escapes | Must | The system shall add a member repository to an existing workspace idempotently, accepting only an in-root direct child that is a Git work tree and rejecting excluded names, absolute paths, and .. escapes |
| FR-5MustThe system shall acquire one worktree per configured member repository when a task starts, under a durable per-repository lease, and record the worktree path, branch, base branch, and base commit for each member | Must | The system shall acquire one worktree per configured member repository when a task starts, under a durable per-repository lease, and record the worktree path, branch, base branch, and base commit for each member |
| FR-6MustThe system shall resolve a base branch for each member repository, verify it in that repository, pin the resolved ref at acquisition, and fall back to that repository's own integration branch when the requested ref does not resolve | Must | The system shall resolve a base branch for each member repository, verify it in that repository, pin the resolved ref at acquisition, and fall back to that repository's own integration branch when the requested ref does not resolve |
| FR-7MustThe system shall refresh every member checkout onto its recorded base branch before execution dispatches, and keep the proven local checkout when the refresh is dirty, conflicting, or unresolvable | Must | The system shall refresh every member checkout onto its recorded base branch before execution dispatches, and keep the proven local checkout when the refresh is dirty, conflicting, or unresolvable |
| FR-8MustThe system shall require a confirmed repository scope on a workspace task and use that scope as the authority for review and landing, so an acquired checkout alone creates no obligation | Must | The system shall require a confirmed repository scope on a workspace task and use that scope as the authority for review and landing, so an acquired checkout alone creates no obligation |
| FR-9MustThe system shall review every modified in-scope member repository, qualify each finding with its repository, and return one aggregate verdict with a per-repository outcome for every scoped member | Must | The system shall review every modified in-scope member repository, qualify each finding with its repository, and return one aggregate verdict with a per-repository outcome for every scoped member |
| FR-10MustThe system shall capture review evidence per member from that member's recorded base commit to its task branch, including the changed file list, the repository-qualified file list, and a diff fingerprint | Must | The system shall capture review evidence per member from that member's recorded base commit to its task branch, including the changed file list, the repository-qualified file list, and a diff fingerprint |
| FR-11MustThe system shall land each member repository independently onto that member's own local integration ref under a durable write fence, and land as it goes so an earlier member can land before a later member fails | Must | The system shall land each member repository independently onto that member's own local integration ref under a durable write fence, and land as it goes so an earlier member can land before a later member fails |
| FR-12MustThe system shall record the landing proof for each member and skip a member that is already landed when a land is retried, so a retry never advances an integration ref twice | Must | The system shall record the landing proof for each member and skip a member that is already landed when a land is retried, so a retry never advances an integration ref twice |
| FR-13MustThe system shall recover a partial land by re-enqueuing the task and retrying only the unlanded members, and park the task for manual intervention when a member branch is gone and no landing proof exists | Must | The system shall recover a partial land by re-enqueuing the task and retrying only the unlanded members, and park the task for manual intervention when a member branch is gone and no landing proof exists |
| FR-14MustThe system shall revert a workspace task across every member repository by classifying all members before committing any of them, and roll every touched member back when one member conflicts | Must | The system shall revert a workspace task across every member repository by classifying all members before committing any of them, and roll every touched member back when one member conflicts |
| FR-15MustThe system shall block completion when a member's main checkout holds a commit attributed to the task, and report an uncommitted main-checkout change as a warning rather than a refusal | Must | The system shall block completion when a member's main checkout holds a commit attributed to the task, and report an uncommitted main-checkout change as a warning rather than a refusal |
| FR-16MustThe system shall classify a workspace task that acquired no member worktree as not applicable, commit-free eligible, or unproven, and use the same classification in review and in completion verification | Must | The system shall classify a workspace task that acquired no member worktree as not applicable, commit-free eligible, or unproven, and use the same classification in review and in completion verification |
| FR-17MustThe system shall expose workspace detection and the member list over HTTPHypertext Transfer Protocol, and let a caller add a member repository | Must | The system shall expose workspace detection and the member list over HTTPHypertext Transfer Protocol, and let a caller add a member repository |
| FR-18MustThe system shall list, read, and write files inside a workspace through the dashboard file routes, where a workspace is the project root or a task worktree | Must | The system shall list, read, and write files inside a workspace through the dashboard file routes, where a workspace is the project root or a task worktree |
| FR-19ShouldThe system shall prepare every configured or detected member at registration, giving each member a verifiable `HEAD` and the managed `.gitignore` rules, and register no project when preparation fails | Should | The system shall prepare every configured or detected member at registration, giving each member a verifiable HEAD and the managed .gitignore rules, and register no project when preparation fails |
| FR-20ShouldThe system shall apply one operator-supplied branch name to every acquired member repository, attaching to an existing branch when one is already there | Should | The system shall apply one operator-supplied branch name to every acquired member repository, attaching to an existing branch when one is already there |
| FR-21ShouldThe system shall interpret the declared File Scope per member repository, so a member prefix yields a member-local scope and a sibling member's declaration yields no authority | Should | The system shall interpret the declared File Scope per member repository, so a member prefix yields a member-local scope and a sibling member's declaration yields no authority |
| FR-22ShouldThe system shall publish a member's landing to that member's own remote when `pushAfterMerge` is enabled, and keep the landing on the local integration ref when it is disabled | Should | The system shall publish a member's landing to that member's own remote when pushAfterMerge is enabled, and keep the landing on the local integration ref when it is disabled |
| FR-23ShouldThe system shall revert a workspace task through one pull request per member repository when auto-merge is off, and refuse the direct integration-branch path | Should | The system shall revert a workspace task through one pull request per member repository when auto-merge is off, and refuse the direct integration-branch path |
| FR-24ShouldThe system shall remove the member worktrees and the workspace task directory after a successful merge and when a workspace task is archived, and preserve a member that holds uncommitted or unverifiable content | Should | The system shall remove the member worktrees and the workspace task directory after a successful merge and when a workspace task is archived, and preserve a member that holds uncommitted or unverifiable content |
Non-Functional Requirements
Order rows by priority: Must first, then Should.
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustAcquire, land, and merge dispatch shall contend on one durable project-and-repository lease key, and a fresh or reclaimed claim shall carry a higher fence token than the claim it replaces | Must | Concurrency | Acquire, land, and merge dispatch shall contend on one durable project-and-repository lease key, and a fresh or reclaimed claim shall carry a higher fence token than the claim it replaces |
| NFR-2MustThe workspace root shall stay browse-only and non-Git, and shall never be a task checkout, a reviewer working directory, or a landing target | Must | Isolation | The workspace root shall stay browse-only and non-Git, and shall never be a task checkout, a reviewer working directory, or a landing target |
| NFR-3MustA member entry shall be a normalized relative path inside the workspace root, and an absolute path, a `..` escape, or a non-string entry shall never reach a path join | Must | Isolation | A member entry shall be a normalized relative path inside the workspace root, and an absolute path, a .. escape, or a non-string entry shall never reach a path join |
| NFR-4MustA member's scope, review evidence, and landing obligations shall never be satisfied by another member's files | Must | Isolation | A member's scope, review evidence, and landing obligations shall never be satisfied by another member's files |
| NFR-5MustA landing whose proof write was lost shall still be recognized as landed through the task identifier trailer on the integration history, so the retry does not squash twice | Must | Reliability | A landing whose proof write was lost shall still be recognized as landed through the task identifier trailer on the integration history, so the retry does not squash twice |
| NFR-6MustA lost or refused lease renewal shall abort the owning land before its next durable or remote write, and the current owner and fence token shall remain the write authority | Must | Reliability | A lost or refused lease renewal shall abort the owning land before its next durable or remote write, and the current owner and fence token shall remain the write authority |
| NFR-7MustA remote publication shall compare-and-swap the target ref and every fence ref of the tenancy in one atomic push | Must | Reliability | A remote publication shall compare-and-swap the target ref and every fence ref of the tenancy in one atomic push |
| NFR-8MustA partial land shall stay recoverable and shall never be reported as one atomic merge | Must | Recoverability | A partial land shall stay recoverable and shall never be reported as one atomic merge |
| NFR-9MustA lease held by a dead node or a finished task shall be reclaimable once it expires, and the reclaim shall name the owner and the expected fence token | Must | Recoverability | A lease held by a dead node or a finished task shall be reclaimable once it expires, and the reclaim shall name the owner and the expected fence token |
| NFR-10MustThe aggregate workspace review verdict shall be deterministic and independent of the order in which members are reviewed | Must | Correctness | The aggregate workspace review verdict shall be deterministic and independent of the order in which members are reviewed |
| NFR-11MustReview and landing shall consume the same repository-qualified file list and the same per-repository diff fingerprint | Must | Correctness | Review and landing shall consume the same repository-qualified file list and the same per-repository diff fingerprint |
| NFR-12ShouldBase-branch decisions and land outcomes shall be written to the task log and to run audit with identifiers and fixed outcomes only, and never with ref names or file paths | Should | Observability | Base-branch decisions and land outcomes shall be written to the task log and to run audit with identifiers and fixed outcomes only, and never with ref names or file paths |
| NFR-13ShouldThe workspace configuration read shall be memoized per host, and a mode toggle shall invalidate the memo so a stale read cannot repopulate the old mode | Should | Performance | The workspace configuration read shall be memoized per host, and a mode toggle shall invalidate the memo so a stale read cannot repopulate the old mode |
| NFR-14ShouldEvery per-member worktree update shall go through the advisory-locked per-key store merge, so a concurrent sibling acquisition, landing, or teardown never loses an entry | Should | Durability | Every per-member worktree update shall go through the advisory-locked per-key store merge, so a concurrent sibling acquisition, landing, or teardown never loses an entry |
Constraints
- The member list lives in
.fusion/workspace.jsonand theworkspaceModesetting lives in.fusion/config.json, and the two are separate artifacts. - The workspace root never becomes a Git repository to make workspace mode work.
- The
workspaceModesetting is not itself the member list, so toggling the setting alone may not create or remove.fusion/workspace.json. - Every configured member is acquired for the task, so membership changes affect later tasks rather than a running task.
- A member's base branch is pinned at acquisition, and a later edit of the task's base branch never retargets an acquired member worktree.
- The land loop is non-atomic across members, and the CLICommand-line interface reports a partial land with a non-zero exit code.
- The
@fusion/*packages keep statically analyzable imports, and@fusion/corenever imports@fusion/engine. - New run-audit emitters use the bounded emitter seam so telemetry never delays a lifecycle transition.
Acceptance Criteria
Every FR and NFR shall have at least one acceptance criterion.
-
FR-1MustThe system shall detect the member repositories of a project root by scanning only its direct children, excluding `node_modules`, `.fusion`, `.git`, `.pi`, and `.worktrees`, requiring a `.git` marker and a passing Git work-tree probe, and returning the members in sorted order
gherkin @FR-1MustThe system shall detect the member repositories of a project root by scanning only its direct children, excluding `node_modules`, `.fusion`, `.git`, `.pi`, and `.worktrees`, requiring a `.git` marker and a passing Git work-tree probe, and returning the members in sorted order Scenario: Detect the member repositories of a project root Given a project root holding two direct child Git repositories and one child without a `.git` marker When workspace detection runs on that root Then the two Git repositories are returned in sorted order and the child without a marker is not returned -
FR-2MustThe system shall record the member list in `.fusion/workspace.json` and read it back, accepting only entries that are strings and normalized relative paths inside the workspace root
gherkin @FR-2MustThe system shall record the member list in `.fusion/workspace.json` and read it back, accepting only entries that are strings and normalized relative paths inside the workspace root Scenario: Reject a member entry that escapes the workspace root Given a workspace configuration file holding an absolute path and a `..` escape When the member list is read Then both entries are filtered out and the remaining in-root entries are kept -
FR-3MustThe system shall enable and disable workspace mode for a project, writing the `workspaceMode` setting in `.fusion/config.json` and the authority file `.fusion/workspace.json` in a documented order and reconciling the two when they diverge
gherkin @FR-3MustThe system shall enable and disable workspace mode for a project, writing the `workspaceMode` setting in `.fusion/config.json` and the authority file `.fusion/workspace.json` in a documented order and reconciling the two when they diverge Scenario: Enable workspace mode on a root with detected members Given a project root with no member list and two detected member repositories When workspace mode is enabled Then the mode setting is written before the member list file and the member list holds the detected repositories -
FR-4MustThe system shall add a member repository to an existing workspace idempotently, accepting only an in-root direct child that is a Git work tree and rejecting excluded names, absolute paths, and `..` escapes
gherkin @FR-4MustThe system shall add a member repository to an existing workspace idempotently, accepting only an in-root direct child that is a Git work tree and rejecting excluded names, absolute paths, and `..` escapes Scenario: Add a member repository twice Given a workspace whose member list already holds the repository `api` When the repository `api` is added again Then the outcome is already a member and the member list is unchanged -
FR-5MustThe system shall acquire one worktree per configured member repository when a task starts, under a durable per-repository lease, and record the worktree path, branch, base branch, and base commit for each member
gherkin @FR-5MustThe system shall acquire one worktree per configured member repository when a task starts, under a durable per-repository lease, and record the worktree path, branch, base branch, and base commit for each member Scenario: Acquire one worktree per configured member Given a task in a workspace configured with two member repositories When the task acquires its checkouts Then one worktree is acquired per member and each member records its worktree path, branch, and base commit -
FR-6MustThe system shall resolve a base branch for each member repository, verify it in that repository, pin the resolved ref at acquisition, and fall back to that repository's own integration branch when the requested ref does not resolve
gherkin @FR-6MustThe system shall resolve a base branch for each member repository, verify it in that repository, pin the resolved ref at acquisition, and fall back to that repository's own integration branch when the requested ref does not resolve Scenario: Fall back when the requested base branch does not resolve in a member Given a task that requests a base branch that does not exist in one member repository When the base branch is resolved for that member Then that member's own integration branch is selected and the fallback is recorded in the task log -
FR-7MustThe system shall refresh every member checkout onto its recorded base branch before execution dispatches, and keep the proven local checkout when the refresh is dirty, conflicting, or unresolvable
gherkin @FR-7MustThe system shall refresh every member checkout onto its recorded base branch before execution dispatches, and keep the proven local checkout when the refresh is dirty, conflicting, or unresolvable Scenario: Keep the local checkout when a base refresh conflicts Given an acquired member checkout whose recorded base cannot be fast-forwarded When the base refresh runs before execution Then the local checkout is kept unchanged and execution is not blocked -
FR-8MustThe system shall require a confirmed repository scope on a workspace task and use that scope as the authority for review and landing, so an acquired checkout alone creates no obligation
gherkin @FR-8MustThe system shall require a confirmed repository scope on a workspace task and use that scope as the authority for review and landing, so an acquired checkout alone creates no obligation Scenario: Refuse to review a workspace task with no confirmed repository scope Given a workspace task whose repository scope is not confirmed When code review runs Then the verdict is unavailable and not retryable -
FR-9MustThe system shall review every modified in-scope member repository, qualify each finding with its repository, and return one aggregate verdict with a per-repository outcome for every scoped member
gherkin @FR-9MustThe system shall review every modified in-scope member repository, qualify each finding with its repository, and return one aggregate verdict with a per-repository outcome for every scoped member Scenario: Aggregate one verdict across every modified member Given a workspace task with two modified in-scope members, one approved and one revised When code review completes Then the aggregate verdict is revised and each member carries its own outcome -
FR-10MustThe system shall capture review evidence per member from that member's recorded base commit to its task branch, including the changed file list, the repository-qualified file list, and a diff fingerprint
gherkin @FR-10MustThe system shall capture review evidence per member from that member's recorded base commit to its task branch, including the changed file list, the repository-qualified file list, and a diff fingerprint Scenario: Capture the diff from the recorded base to the task branch Given a member whose recorded base commit is behind its task branch When review evidence is captured for that member Then the changed files are the ones between the recorded base commit and the task branch and the file list is prefixed with the member name -
FR-11MustThe system shall land each member repository independently onto that member's own local integration ref under a durable write fence, and land as it goes so an earlier member can land before a later member fails
gherkin @FR-11MustThe system shall land each member repository independently onto that member's own local integration ref under a durable write fence, and land as it goes so an earlier member can land before a later member fails Scenario: Land one member and fail a later member Given a workspace task with two modified members where the second member's land fails When the land loop runs Then the first member's integration ref has advanced and the result reports a partial land -
FR-12MustThe system shall record the landing proof for each member and skip a member that is already landed when a land is retried, so a retry never advances an integration ref twice
gherkin @FR-12MustThe system shall record the landing proof for each member and skip a member that is already landed when a land is retried, so a retry never advances an integration ref twice Scenario: Skip a member that already landed on a retry Given a workspace task whose first member recorded a landing proof When the land loop is retried Then the first member is skipped and its integration ref is not advanced again -
FR-13MustThe system shall recover a partial land by re-enqueuing the task and retrying only the unlanded members, and park the task for manual intervention when a member branch is gone and no landing proof exists
gherkin @FR-13MustThe system shall recover a partial land by re-enqueuing the task and retrying only the unlanded members, and park the task for manual intervention when a member branch is gone and no landing proof exists Scenario: Recover a partial land by retrying the unlanded members Given a workspace task in review with one landed member and one member that failed to land When the partial-land sweep runs Then the task is re-enqueued so only the unlanded member is retried -
FR-14MustThe system shall revert a workspace task across every member repository by classifying all members before committing any of them, and roll every touched member back when one member conflicts
gherkin @FR-14MustThe system shall revert a workspace task across every member repository by classifying all members before committing any of them, and roll every touched member back when one member conflicts Scenario: Commit no member revert when one member conflicts Given a workspace task whose one member revert conflicts When the workspace revert runs Then every touched member is rolled back to its pre-call state and no member revert is committed -
FR-15MustThe system shall block completion when a member's main checkout holds a commit attributed to the task, and report an uncommitted main-checkout change as a warning rather than a refusal
gherkin @FR-15MustThe system shall block completion when a member's main checkout holds a commit attributed to the task, and report an uncommitted main-checkout change as a warning rather than a refusal Scenario: Block completion on a task-attributed main-checkout commit Given a member main checkout holding a commit that names the task identifier When task completion is requested Then completion is refused with a main-checkout edit violation -
FR-16MustThe system shall classify a workspace task that acquired no member worktree as not applicable, commit-free eligible, or unproven, and use the same classification in review and in completion verification
gherkin @FR-16MustThe system shall classify a workspace task that acquired no member worktree as not applicable, commit-free eligible, or unproven, and use the same classification in review and in completion verification Scenario: Classify a workspace task that acquired no member worktree Given a workspace task with an empty member worktree map and no commit-free eligibility When the zero-acquire classification runs Then the classification is unproven -
FR-17MustThe system shall expose workspace detection and the member list over HTTPHypertext Transfer Protocol, and let a caller add a member repository
gherkin @FR-17MustThe system shall expose workspace detection and the member list over HTTPHypertext Transfer Protocol, and let a caller add a member repository Scenario: List the members of a registered workspace Given a registered workspace holding the members `api` and `web` When the member list route is called Then the response holds `api` and `web` and the request is refused with a conflict for a project that is not a workspace -
FR-18MustThe system shall list, read, and write files inside a workspace through the dashboard file routes, where a workspace is the project root or a task worktree
gherkin @FR-18MustThe system shall list, read, and write files inside a workspace through the dashboard file routes, where a workspace is the project root or a task worktree Scenario: List files in a workspace Given a workspace whose identifier is the project root When the workspace file list route is called Then the response holds the requested path and the directory entries -
FR-19ShouldThe system shall prepare every configured or detected member at registration, giving each member a verifiable `HEAD` and the managed `.gitignore` rules, and register no project when preparation fails
gherkin @FR-19ShouldThe system shall prepare every configured or detected member at registration, giving each member a verifiable `HEAD` and the managed `.gitignore` rules, and register no project when preparation fails Scenario: Refuse to register a workspace when a member cannot be prepared Given a detected member repository that cannot be prepared When project registration completes Then no project row is registered or activated -
FR-20ShouldThe system shall apply one operator-supplied branch name to every acquired member repository, attaching to an existing branch when one is already there
gherkin @FR-20ShouldThe system shall apply one operator-supplied branch name to every acquired member repository, attaching to an existing branch when one is already there Scenario: Apply one operator branch to every member Given a workspace task with an operator-supplied branch name When the task acquires its checkouts Then every acquired member uses that branch name -
FR-21ShouldThe system shall interpret the declared File Scope per member repository, so a member prefix yields a member-local scope and a sibling member's declaration yields no authority
gherkin @FR-21ShouldThe system shall interpret the declared File Scope per member repository, so a member prefix yields a member-local scope and a sibling member's declaration yields no authority Scenario: Withhold a sibling member's scope from a member Given a declared file scope that names only the member `api` When the scope is resolved for the member `web` Then the resolved scope for `web` is empty -
FR-22ShouldThe system shall publish a member's landing to that member's own remote when `pushAfterMerge` is enabled, and keep the landing on the local integration ref when it is disabled
gherkin @FR-22ShouldThe system shall publish a member's landing to that member's own remote when `pushAfterMerge` is enabled, and keep the landing on the local integration ref when it is disabled Scenario: Publish a member land only when publication is enabled Given a workspace task whose publication setting is disabled When a member lands Then no fence ref is created and no remote write is attempted -
FR-23ShouldThe system shall revert a workspace task through one pull request per member repository when auto-merge is off, and refuse the direct integration-branch path
gherkin @FR-23ShouldThe system shall revert a workspace task through one pull request per member repository when auto-merge is off, and refuse the direct integration-branch path Scenario: Revert a workspace task through one pull request per member Given a workspace task in a project whose auto-merge is off When a workspace revert is requested Then the direct integration-branch path is refused and one pull request per member is prepared -
FR-24ShouldThe system shall remove the member worktrees and the workspace task directory after a successful merge and when a workspace task is archived, and preserve a member that holds uncommitted or unverifiable content
gherkin @FR-24ShouldThe system shall remove the member worktrees and the workspace task directory after a successful merge and when a workspace task is archived, and preserve a member that holds uncommitted or unverifiable content Scenario: Preserve a member that holds uncommitted content Given a merged workspace task whose member worktree holds uncommitted content When the cleanup runs Then that member worktree is preserved with its reason written to the task log -
NFR-1MustAcquire, land, and merge dispatch shall contend on one durable project-and-repository lease key, and a fresh or reclaimed claim shall carry a higher fence token than the claim it replaces
gherkin @NFR-1MustAcquire, land, and merge dispatch shall contend on one durable project-and-repository lease key, and a fresh or reclaimed claim shall carry a higher fence token than the claim it replaces Scenario: Fence out a second writer on the same member Given a live lease on one member repository held by another task When a second task tries to acquire or land that member Then the claim reports a conflict naming the holder -
NFR-2MustThe workspace root shall stay browse-only and non-Git, and shall never be a task checkout, a reviewer working directory, or a landing target
gherkin @NFR-2MustThe workspace root shall stay browse-only and non-Git, and shall never be a task checkout, a reviewer working directory, or a landing target Scenario: Never treat the workspace root as a checkout Given a workspace task whose member worktrees are recorded When the task's routing metadata is normalized Then the singular worktree and branch fields are cleared and every member entry is preserved -
NFR-3MustA member entry shall be a normalized relative path inside the workspace root, and an absolute path, a `..` escape, or a non-string entry shall never reach a path join
gherkin @NFR-3MustA member entry shall be a normalized relative path inside the workspace root, and an absolute path, a `..` escape, or a non-string entry shall never reach a path join Scenario: Refuse a member path that leaves the workspace root Given a caller that asks to add the member `../outside-repo` When the member is added Then the request is refused with an invalid path reason -
NFR-4MustA member's scope, review evidence, and landing obligations shall never be satisfied by another member's files
gherkin @NFR-4MustA member's scope, review evidence, and landing obligations shall never be satisfied by another member's files Scenario: Keep a member's landing obligation separate from its sibling Given a confirmed scope of two members where only one has changed files When the merge readiness is resolved Then only the member with changed files carries a landing obligation -
NFR-5MustA landing whose proof write was lost shall still be recognized as landed through the task identifier trailer on the integration history, so the retry does not squash twice
gherkin @NFR-5MustA landing whose proof write was lost shall still be recognized as landed through the task identifier trailer on the integration history, so the retry does not squash twice Scenario: Prove a lost landing proof through the task identifier trailer Given a member whose integration ref advanced with a squash commit carrying the task identifier trailer When the landed predicate runs without a recorded landing proof Then the member is reported as landed and the proven commit is returned -
NFR-6MustA lost or refused lease renewal shall abort the owning land before its next durable or remote write, and the current owner and fence token shall remain the write authority
gherkin @NFR-6MustA lost or refused lease renewal shall abort the owning land before its next durable or remote write, and the current owner and fence token shall remain the write authority Scenario: Abort a land when the lease renewal is lost Given a land whose lease renewal is refused When the land body reaches its next durable write Then the land aborts before that write -
NFR-7MustA remote publication shall compare-and-swap the target ref and every fence ref of the tenancy in one atomic push
gherkin @NFR-7MustA remote publication shall compare-and-swap the target ref and every fence ref of the tenancy in one atomic push Scenario: Reject a publication whose target moved Given a remote target ref that moved after the fence pin was published When the fenced push runs Then the push is rejected and the target ref is not overwritten -
NFR-8MustA partial land shall stay recoverable and shall never be reported as one atomic merge
gherkin @NFR-8MustA partial land shall stay recoverable and shall never be reported as one atomic merge Scenario: Report a partial land as a partial land Given a workspace land where one member failed When the merge result is reported to the operator Then the result reports that not all members landed and the task is not finalized -
NFR-9MustA lease held by a dead node or a finished task shall be reclaimable once it expires, and the reclaim shall name the owner and the expected fence token
gherkin @NFR-9MustA lease held by a dead node or a finished task shall be reclaimable once it expires, and the reclaim shall name the owner and the expected fence token Scenario: Reclaim an expired lease Given a held lease whose expiry has passed When the expired lease sweep runs Then the lease is reclaimed and the reclaimed key is reported -
NFR-10MustThe aggregate workspace review verdict shall be deterministic and independent of the order in which members are reviewed
gherkin @NFR-10MustThe aggregate workspace review verdict shall be deterministic and independent of the order in which members are reviewed Scenario: Keep the aggregate verdict independent of member order Given two members where one is revised and the other is unavailable When the members are reviewed in either order Then the aggregate verdict is revised in both runs -
NFR-11MustReview and landing shall consume the same repository-qualified file list and the same per-repository diff fingerprint
gherkin @NFR-11MustReview and landing shall consume the same repository-qualified file list and the same per-repository diff fingerprint Scenario: Refuse to land an approved member whose diff changed Given a member whose approved diff fingerprint no longer matches its current diff When the landing evidence is checked Then the member is reported as content changed and the task is routed back to review -
NFR-12ShouldBase-branch decisions and land outcomes shall be written to the task log and to run audit with identifiers and fixed outcomes only, and never with ref names or file paths
gherkin @NFR-12ShouldBase-branch decisions and land outcomes shall be written to the task log and to run audit with identifiers and fixed outcomes only, and never with ref names or file paths Scenario: Record a base-branch decision without ref names Given a base-branch fallback in one member When the decision is audited Then the audit row holds the task, the member, the stage, and the fixed outcome, and no ref name -
NFR-13ShouldThe workspace configuration read shall be memoized per host, and a mode toggle shall invalidate the memo so a stale read cannot repopulate the old mode
gherkin @NFR-13ShouldThe workspace configuration read shall be memoized per host, and a mode toggle shall invalidate the memo so a stale read cannot repopulate the old mode Scenario: Invalidate the memoized member list on a mode toggle Given a pending member list read for a project When workspace mode is toggled for that project Then the pending read cannot repopulate the previous mode -
NFR-14ShouldEvery per-member worktree update shall go through the advisory-locked per-key store merge, so a concurrent sibling acquisition, landing, or teardown never loses an entry
gherkin @NFR-14ShouldEvery per-member worktree update shall go through the advisory-locked per-key store merge, so a concurrent sibling acquisition, landing, or teardown never loses an entry Scenario: Preserve sibling entries on a per-member update Given a workspace task with two member entries When one member entry is updated Then the other member entry is preserved unchanged
Conflicts
None identified yet.
Open Questions
- The code does not say whether a workspace task may be created against a member list that changes while the task is in review. The membership snapshot is captured at acquisition, so the current behavior is that later membership changes affect only later tasks, and the intent behind that choice is not recorded.
Specification: Multi-Repository Workspaces
Overview
A workspace project keeps its root browse-only and non-Git, and treats the root's direct child Git repositories as its members.
@fusion/core owns detection, the member list in .fusion/workspace.json, the mode toggle, and the durable coordination leases and land intents in PostgreSQL.
@fusion/engine owns the per-member worktree acquisition, the per-member base resolution and refresh, the per-member review, the per-member land loop, the partial-land recovery sweep, and the per-member revert.
The dashboard exposes detection, the member list, and the workspace file browser over HTTPHypertext Transfer Protocol.
Architecture
┌──────────────────────────────────────────────────────────────────────────┐
│ Surfaces │
│ Setup Wizard / Settings CLICommand-line interface (fn project, fn task) │
│ Dashboard file browser (workspace = project | task) │
└──────────────────────────────────────────────────────────────────────────┘
│ RESTRepresentational State Transfer
┌──────────────────────────────────────────────────────────────────────────┐
│ @fusion/dashboard routes │
│ POST /projects/detect-workspace GET|POST /git/workspace-repos │
│ GET /workspaces GET|POST /files... │
└──────────────────────────────────────────────────────────────────────────┘
│
┌──────────────────────────────────────────────────────────────────────────┐
│ @fusion/core │
│ git/git-repository.ts │
│ detectWorkspaceRepos loadWorkspaceConfig saveWorkspaceConfig │
│ addWorkspaceRepo applyWorkspaceModeToggle │
│ withWorkspaceModeLock │
│ task-store/workspace-leases.ts tasks/workspace-lease-types.ts │
│ acquire / renew / release / reclaim / fence-ref / land-intent │
│ postgres/schema/project.ts │
│ workspace_coordination_leases workspace_land_intents │
└──────────────────────────────────────────────────────────────────────────┘
│
┌──────────────────────────────────────────────────────────────────────────┐
│ @fusion/engine │
│ worktree/ workspace-paths workspace-base-branch │
│ workspace-base-refresh workspace-review-evidence │
│ worktree-acquisition (acquireWorkspaceRepoWorktree) │
│ executor/ workspace-review-per-repo workspace-config-resolver │
│ workspace-main-checkout-guard workspace-zero-acquire │
│ merge/ merger-ai.landWorkspaceTask workspace-land-predicate │
│ workspace-fence-ref workspace-merge-readiness │
│ workspace-merge-dispatch-lease workspace-integration-target│
│ workspace-land-failure │
│ execution/ task-revert (revertWorkspaceTask, prepareWorkspaceRevertPr) │
│ self-healing.ts reconcileWorkspacePartialLands │
└──────────────────────────────────────────────────────────────────────────┘
│
┌──────────────────────────────────────────────────────────────────────────┐
│ Git and PostgreSQL │
│ ROOT/MEMBER main checkout ROOT/.fusion/worktrees/TASKID/ │
│ member integration ref member remote (optional) │
│ PostgreSQL project schema: leases, land intents, tasks │
└──────────────────────────────────────────────────────────────────────────┘
Data Models
WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop config file
Stored at <workspace-root>/.fusion/workspace.json.
| Field | Type | Constraints | Description |
|---|---|---|---|
| repos | string[] | Required, every entry a string, every entry a normalized relative path inside the workspace root | Member repository paths relative to the workspace root, sorted |
WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop worktree entry
Stored per task in tasks.workspace_worktrees, keyed by the member path relative to the workspace root.
| Field | Type | Constraints | Description |
|---|---|---|---|
| worktreePath | string | Not null | Absolute path of the member's linked checkout |
| branch | string | Not null | The task branch checked out in that member |
| baseBranch | string | Optional | The ref the member worktree was derived from and must later target |
| baseBranchFallbackFrom | string | Optional | The operator-requested ref that could not be used in that member |
| baseCommitSha | string | Optional | The per-member fork point captured at acquisition |
| landedSha | string | Optional | The commit that landed this member on its integration ref |
| revertBoundarySha | string | Optional | The integration commit created by a completed git-mode revert |
| landFailure | object | Optional | Display-only failure breadcrumb for the member, never part of a landed predicate |
Task repository scope
Stored per task in tasks.repository_scope.
| Field | Type | Constraints | Description |
|---|---|---|---|
| repositories | string[] | Not null, no empty entry, no duplicate | The confirmed member repositories |
| state | string | Optional, only confirmed |
The confirmation state of the scope |
| revision | number | Optional | Monotonic configuration generation that fences a stale review callback |
| confirmedAt | string | Optional | When the scope was confirmed |
| confirmedBy | string | Optional, only workspace |
The confirmer, always the configured workspace |
| reviewEvidence | map | Optional | Per-repository approved diff fingerprint and approval time |
| reviewRemediation | object | Optional | The reviewed repository, the normalized input signature, and the scope generation of a remediation episode |
| extensions | array | Optional | Historical manual-scope acceptance and refusal records |
WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop coordination lease
Table workspace_coordination_leases in the project schema.
| Field | Type | Constraints | Description |
|---|---|---|---|
| projectId | string | Primary key part, not null | The owning project |
| leaseKey | string | Primary key part, not null | The contended resource key, repo:MEMBER or merge-dispatch:TASKID |
| kind | string | Not null, one of acquire, land, merge-dispatch |
The tenancy type |
| ownerTaskId | string | Not null | The owning task |
| ownerNodeId | string | Not null | The owning node |
| ownerIncarnationId | string | Not null | The owning process incarnation, so a restarted process is not the same owner |
| ownerRunId | string | Optional | The owning run |
| fenceToken | bigint | Not null, increasing | The fencing authority, not a time-to-live |
| fenceRefName | string | Optional | The published fence ref name |
| fenceRefSha | string | Optional | The published fence ref commit |
| status | string | Not null, one of held, released, expired |
The lease state |
| acquiredAt | string | Not null | When the lease was claimed |
| renewedAt | string | Not null | When the lease was last renewed, observability only |
| expiresAt | string | Not null | The only liveness clock for the lease |
| createdAt | string | Not null | Row creation time |
| updatedAt | string | Not null | Row update time |
WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop land intent
Table workspace_land_intents in the project schema.
| Field | Type | Constraints | Description |
|---|---|---|---|
| projectId | string | Primary key part, not null | The owning project |
| taskId | string | Primary key part, not null | The landing task |
| repoRelPath | string | Primary key part, not null | The member path relative to the workspace root |
| remoteUrl | string | Not null | The member remote that receives the publication |
| integrationRef | string | Not null | The member integration ref that is advanced |
| intendedSha | string | Not null | The commit the land intends to publish |
| expectedTip | string | Not null | The integration tip the land expects to replace |
| fenceRefName | string | Not null | The fence ref that guards the publication |
| fenceRefSha | string | Not null | The fence ref commit that guards the publication |
| ownerTaskId | string | Not null | The lease owner triple member for the task |
| ownerNodeId | string | Not null | The lease owner triple member for the node |
| ownerIncarnationId | string | Not null | The lease owner triple member for the incarnation |
| fenceToken | bigint | Not null | The fence token of the tenancy that wrote the intent |
| status | string | Not null, one of pending, recorded, abandoned |
The intent state |
| resolvedSha | string | Optional | The commit proven to carry the work |
| resolution | string | Optional, one of landed, not-landed |
How the intent resolved |
| createdAt | string | Not null | Row creation time |
| updatedAt | string | Not null | Row update time |
| resolvedAt | string | Optional | When the intent resolved |
WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop member land result
Returned in memory by landWorkspaceTask.
| Field | Type | Constraints | Description |
|---|---|---|---|
| repo | string | Not null | The member path relative to the workspace root |
| repoRootDir | string | Not null | Absolute path of the member's main checkout |
| integrationBranch | string | Not null | The member's own integration branch |
| branch | string | Not null | The task branch that was landed |
| status | string | Not null, one of landed, empty, failed |
The outcome for that member |
| landedSha | string | Optional | The squash commit when the status is landed |
| localSync | object | Optional | How the member checkout was reconciled |
| dependencySyncDecision | string | Optional | The clean-room dependency decision for that member |
| error | string | Optional | The failure message when the status is failed |
| alreadyLanded | boolean | Optional | True when the landed predicate skipped the member on a retry |
WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop member revert result
Returned in memory by revertWorkspaceTask.
| Field | Type | Constraints | Description |
|---|---|---|---|
| repo | string | Not null | The member path relative to the workspace root |
| classification | string | Not null | The per-member classification, clean, reverted, or conflict |
| branch | string | Optional | The member branch the revert targeted |
| revertedCommits | array | Optional | The commits the member revert addressed |
APIApplication programming interface Contracts
The normative contract is in api.yaml (OpenAPI 3.1).
The table below is a summary; request and response schemas and error bodies are in api.yaml.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/projects/detect-workspace | Detect the member repositories of a directory |
| GET | /api/git/workspace-repos | List the registered members of a workspace, and the detected candidates when asked |
| POST | /api/git/workspace-repos | Add a member repository to a workspace |
| GET | /api/workspaces | List the browsable workspaces of a project, which are the project root and the task worktrees |
| GET | /api/files | List the files and directories at a path inside a workspace |
| GET | /api/files/{filepath} | Read one file inside a workspace |
| POST | /api/files/{filepath} | Write one file inside a workspace |
Error codes shared across endpoints:
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_INPUT | The request body or query is missing a required field or holds a value the route rejects |
| 400 | INVALID_WORKSPACE_REPO | The member path is not an in-root direct child Git work tree, or the name is excluded |
| 404 | NOT_FOUND | The requested file, path, or task does not exist |
| 409 | NOT_A_WORKSPACE | The project has no member list, so the route has nothing to report |
| 413 | FILE_TOO_LARGE | The file exceeds the size the file service accepts |
| 415 | UNSUPPORTED_MEDIA_TYPE | The file is binary and cannot be returned as text |
| 500 | INTERNAL_ERROR | An unexpected failure, reported with the operator-facing summary |
Key Sequences
Detect members and register a workspace
POST /api/projects/detect-workspace { path }
│
▼
path is absolute? ──no──► 400 INVALID_INPUT
│ yes
▼
path exists? ──no──► 400 INVALID_INPUT
│ yes
▼
detectWorkspaceRepos(root)
│ for each direct child, skip excluded names
│ require a .git marker, then a git rev-parse work-tree probe
▼
{ repos: [...sorted], isWorkspace: repos.length > 0 }
│
▼ operator confirms workspace mode
prepare every member (verifiable HEAD, managed .gitignore)
│ failure ──► no project row is registered or activated
▼
write .fusion/config.json settings.workspaceMode = true
▼
write .fusion/workspace.json { repos }
Land the members of a workspace task
merge dispatch
│
▼
claim merge-dispatch:TASKID lease ──conflict──► busy, retry later
│
▼
for each member, in sorted member order
│
├─ claim repo:MEMBER lease (kind land) ──conflict──► busy, retry later
├─ resolve the member's integration target (local when publication is off)
├─ resolve the member's integration branch and expected tip
├─ publish the fence ref refs/fusion/workspace-lease/SLUG
├─ write the land intent (pending)
├─ squash the member branch onto the member integration ref
├─ push with --atomic and --force-with-lease on the target and every fence ref
├─ persist landedSha under a valid lease, then resolve the intent (recorded)
└─ release the member lease
│
▼
every member landed or empty ──no──► partial land, task stays in review
│ yes
▼
finalize the task to done, then remove the member worktrees
Revert the members of a workspace task
revert request
│
▼
resolve the per-member attributable commits
│ squash proof first, then the member branch range
▼
classify every member
│ clean / already reverted / conflict
▼
any conflict? ──yes──► roll every touched member back, commit nothing
│ no
▼
apply the revert to every member, then commit every member
│
▼
record the member revert boundary commit
│
▼
auto-merge off ──yes──► prepare one pull request per member instead
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Member authority | .fusion/workspace.json is the single membership authority, the workspaceMode setting is a separate mirror |
The executor reads the file, so the file decides execution while the setting drives the dashboard toggle and registration suppression |
| Detection depth | One level of direct children only | A workspace root is a plain directory whose immediate children are the intended members, and a deeper scan would pick up dependency artifacts |
| Member path rules | Normalized relative in-root direct child, excluded names refused | A member path is joined onto the workspace root, so an absolute path or a .. escape would resolve outside the root |
| Mode toggle order | Write the setting mirror first on enable, remove the file first on disable | A half-written change must not leave the file enabling execution, and a partial delete must not be auto-detected back to enabled |
| Mode toggle serialization | One in-process lock per project root | The toggle reads, decides, and writes several files, and a concurrent toggle would otherwise lose a member |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main ownership | One worktree per configured member under one task directory | Agents never choose or extend checkouts, so a task sees one stable set of members for its whole lifetime |
| Root routing | The workspace root is never a checkout, a reviewer working directory, or a landing target | The root is not a Git repository, so any such use would break the member's own base and diff |
| Base pinning | The resolved member base is recorded at acquisition and wins over the task field afterwards | A later edit of the task's base branch must not retarget a checkout that already exists |
| Base fallback | The member's own integration branch when the requested ref does not resolve there | Members are independent repositories, so one member's ref cannot be assumed to exist in another |
| Scope authority | A confirmed repository scope, not the acquired checkouts, decides review and landing | Acquisition grants a checkout, and a checkout alone must not create a review or landing obligation |
| Review coverage | One reviewer per modified in-scope member, then one aggregate verdict | The reviewer runs with the member's working directory, so per-member evidence is what it can see |
| Aggregate severity | Rethink outranks revise, which outranks unavailable, which outranks the approval family | The aggregate must not depend on the order in which members are reviewed |
| Review and landing evidence | The same repository-qualified file list and the same per-member diff fingerprint | Landing must consume exactly what review approved |
| Land atomicity | Non-atomic per member, land as you go | A shared workspace integration branch would be wrong because members are independent repositories |
| Landed proof | The recorded landing commit, proven by an ancestor check | A recorded commit that is no longer reachable means the ref was rebuilt, so the member must land again |
| Lost proof fallback | The task identifier trailer on the integration history | A squash commit's parent is the integration tip, so branch ancestry cannot prove the landing, but the trailer can |
| Fence refs | A private ref per tenancy, published once per tenancy, reused on re-entry | Rotating the pin on re-entry would orphan a pending land intent that names the old pin |
| Publication | One atomic push that compares and swaps the target ref and every fence ref | A superseded owner must be rejected even when the target tip has not moved |
| Revert coverage | Classify all members, then commit all members | A half-reverted workspace is an inconsistent state, so a conflict rolls everything back |
| Recovery | A partial land re-enqueues the task and retries only the unlanded members | A partial land is recoverable state, not one atomic merge, so it must never be reported as a merge |
| Member worktree updates | One advisory-locked per-key store merge per member | A wholesale map replacement would lose a concurrent sibling acquisition, landing, or teardown entry |
Risks and Unknowns
- The land loop is non-atomic, so a failure after an earlier member landed leaves the workspace in a mixed state until the recovery sweep runs.
- A member's base branch can resolve in one member and not another, which produces a mixed workspace that needs operator inspection.
- The acquisition lease covers only the checkout creation, so two tasks can work in the same member at the same time after acquisition completes.
- A member that is added while a task is running is not acquired by that task, so the new work needs a follow-up task.
- The
workspaceModesetting and.fusion/workspace.jsonare separate artifacts, so a toggle alone can leave the two out of step. - The code does not record whether a workspace task may be created against a member list that changes during review.
Out of Scope
- A shared workspace integration branch, which would require the members to share one Git history.
- Root-level Git operations in a workspace, because the workspace root is not a Git repository.
- Nested member discovery, because detection stops at the direct children.
- WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP scripts, because the script runner cannot yet receive the multi-root boundary.
- The general file browser, the task file routes, and the file operation routes beyond the workspace file list, read, and write calls.
Test Plan: Multi-Repository Workspaces
Scope
Covers member detection, the member list file, the workspace mode toggle, member addition, per-member worktree acquisition and base resolution, the per-member review and its aggregate verdict, the per-member land loop, landed proof, the partial-land recovery sweep, the per-member revert, the main-checkout completion guard, the zero-acquire classification, and the HTTPHypertext Transfer Protocol surface for detection, the member list, and the workspace file browser.
Out of scope: the general task file routes, the file operation routes beyond list, read, and write, the dependency bootstrap, and the worktrunk worktree backend.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Detect the member repositories of a project root | A root with two Git children and one plain child | The two Git children are returned in sorted order and the plain child is not returned |
| TC-2 | Add a member repository | An eligible direct child, then the same child again | The first call reports added and the second reports already-member with the member list unchanged |
| TC-3 | Refuse an invalid member path | ../escape, ., a/.., group/a, and a plain directory |
The calls are refused with the reasons invalid-path, not-direct-child, not-direct-child, not-direct-child, and not-a-git-work-tree |
| TC-4 | Toggle workspace mode on and off | A root with detected members | The mode setting and the member list file are created and removed, and unrelated config survives |
| TC-5 | Preserve a curated member list and refuse an empty root | An existing non-empty member list, and a root with no sub-repositories | The curated list survives, and a root with no members reports the no-sub-repositories failure |
| TC-6 | Reconcile a failed toggle write | A failing mirror or file write | The observed member list is re-read and the mode setting is reconciled to it |
| TC-7 | Serialize concurrent toggles on one root | Two toggles on the same root | The critical sections run one after the other and the lock is released after a throwing body |
| TC-8 | Derive the owning member for a path | Repo-prefixed and unscoped paths against a member list | The longest matching member prefix wins and an unmatched path is unscoped |
| TC-9 | Resolve a member scope subset | A declared scope naming one member, resolved for a sibling | The sibling receives an empty scope and no fallback authority |
| TC-10 | Resolve a member base branch | A requestable base, a vanished recorded base, a sibling task branch, and an unresolvable base | The requestable base is used, and the other cases fall back to the member's own integration branch with the matching fallback reason |
| TC-11 | Refresh a member base | A live member checkout on a stale base | The checkout is moved onto the recorded base and the durable base commit is persisted |
| TC-12 | Skip a refresh that is dirty, conflicting, or unresolvable | A member checkout that cannot be fast-forwarded | The local checkout is kept, the result is marked skipped, and execution is not blocked |
| TC-13 | Classify a zero-acquire workspace task | An empty member map with and without a commit-free eligibility source | The classification is unproven without a source and commit-free-eligible with one |
| TC-14 | Resolve the merge readiness | A confirmed scope, a duplicate declaration, a duplicate worktree path, and a commit-free task | The ready, blocked, and no-op outcomes are returned for the matching inputs |
| TC-15 | Select the member integration target | A repository with no remote, one remote, origin, a configured remote, and an ambiguous remote |
The local, remote, and failure outcomes are returned for the matching inputs |
| TC-16 | Qualify a member review finding | A finding id and file path without a member prefix | The id is prefixed with member: and the file path with member/ |
| TC-17 | Aggregate the member review verdicts | Approved, revised, rethinking, and unavailable member verdicts | The aggregate takes the strongest severity and an approval with notes still approves |
| TC-18 | Capture a member review evidence set | A member with a recorded base commit and a task branch | The changed files come from the base-to-branch range, the file list is member-qualified, and a fingerprint is produced |
| TC-19 | Detect main-checkout work | A member main checkout with a task-attributed commit and with uncommitted changes | The attributed commit is a violation and the uncommitted change is a warning |
| TC-20 | Prove a landed member from the task trailer | An integration ref carrying a commit with the task identifier trailer and no recorded proof | The member is reported as landed and the exact commit is returned |
| TC-21 | Refuse a landed proof at or behind a revert boundary | A recorded proof behind the revert boundary | The member is not reported as landed |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-22 | Acquire every configured member | A workspace with two members and a task | One worktree per member, each with its own path, branch, and base commit |
| TC-23 | Hold a second writer off one member | A live acquire lease on one member | The second claim reports a conflict naming the holder and the caller holds |
| TC-24 | Release an acquire lease | An acquired member | The lease is released and the member can be acquired again |
| TC-25 | Keep the acquire lease authority | A lease claimed by another node or incarnation | The second claim contends instead of re-entering |
| TC-26 | Coordinate durable leases across processes | A PostgreSQL project schema | Acquire, renew, release, reclaim, and fence-ref writes all behave as one authority |
| TC-27 | Resolve a land intent | A pending intent with a live lease and one with a stale fence | The live holder resolves the intent and a stale fence is refused |
| TC-28 | Land the members of a workspace task | Two modified members | Each member advances its own integration ref and the result reports every member |
| TC-29 | Skip a member that already landed | A member with a recorded landing proof | The member is skipped and its ref is not advanced again |
| TC-30 | Land with publication disabled | The push-after-merge setting off | No fence ref is created and no remote write is attempted |
| TC-31 | Apply the member scope gates on a land | A squash that touches a file outside the member scope | The integration ref of that member does not advance |
| TC-32 | Reject a publication whose target moved | A remote target ref that moved after the fence pin was published | The atomic push is rejected and the target is not overwritten |
| TC-33 | Recover a partial land | A task in review with one landed member and one failed member | The sweep re-enqueues the task so only the unlanded member is retried |
| TC-34 | Revert the members of a workspace task | A landed member set with no conflict | Every member is reverted and committed |
| TC-35 | Roll back a conflicting workspace revert | One member whose revert conflicts | Every touched member is restored to its pre-call state and no member revert is committed |
| TC-36 | Revert through one pull request per member | A project with auto-merge off | The direct integration-branch path is refused and one pull request per member is prepared |
| TC-37 | Guard task completion on the main checkouts | A member main checkout holding a task-attributed commit | Completion is refused with the main-checkout edit reason |
| TC-38 | Prove the delivery of a workspace task | A task with a member worktree holding no commit | The acquired-worktree no-commit invariant refuses the completion |
| TC-39 | Keep the workspace root out of the routing | A task with member worktrees and stale singular routing metadata | The singular fields are cleared and every member entry survives |
| TC-40 | Resolve the workspace member list over HTTPHypertext Transfer Protocol | A registered workspace and a project that is not a workspace | The members are listed and the non-workspace project is refused with a conflict |
| TC-41 | Add a workspace member over HTTPHypertext Transfer Protocol | A valid member and an invalid member | The member is added and the invalid member is mapped to a route error |
| TC-42 | Detect the members over HTTPHypertext Transfer Protocol | An absolute path that exists and one that does not | The members and the workspace flag are returned and a missing path is refused |
| TC-43 | Browse the workspace files over HTTPHypertext Transfer Protocol | A workspace identifier of the project root and a task worktree | The listing, the read, and the write all return their payloads |
| TC-44 | Keep the member worktrees on reset | A workspace task with recorded member worktrees | Every member worktree is removed and the task returns to planning |
| TC-45 | Remove the member worktrees on archive | A workspace task with recorded member worktrees | Every member worktree is removed under a per-repository reservation |
| TC-46 | Clean up after a successful land | A merged workspace task | The member worktrees and the workspace task directory are removed |
| TC-47 | Preserve a member that holds uncommitted content | A merged workspace task with an uncommitted member | That member is preserved with its reason written to the task log |
End-to-End Tests
| ID | Description | Steps | Expected Outcome |
|---|---|---|---|
| TC-48 | Run a workspace task end to end | Register a workspace, create a task, execute, review, and merge | Each member is acquired, reviewed, and landed, and the task reaches done |
| TC-49 | Run the workspace pipeline smoke | A workspace project through the pipeline tier | The board, the task, and the merge report the member outcomes |
| TC-50 | Resolve a grouped workspace root in the extension | A member checkout in a grouped worktree root | The extension resolves the workspace root, not the member or the group container |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-51 | A member path leaves the workspace root | The path is rejected and never reaches a path join |
| TC-52 | A member list holds a non-string entry | The whole list is refused and the project falls back to single-repository mode |
| TC-53 | A requested base branch resolves in one member only | The other member falls back to its own integration branch and the fallback is logged |
| TC-54 | A task identifier is recycled | The trailer scan refuses to treat the older commit as this task's landing |
| TC-55 | A member is modified outside the confirmed scope | The review returns unavailable and names the out-of-scope member |
| TC-56 | A clean scoped member | The member is recorded as not reviewed and creates no landing obligation |
| TC-57 | A reviewer provider failure during a member review | The episode ends as unavailable and no partial findings are published |
| TC-58 | An approved member diff changes before the merge | The member is reported as content changed and the task is routed back to review |
| TC-59 | A lease renewal is refused during a land | The land aborts before its next durable write |
| TC-60 | An expired lease is left by a dead node | The lease is reclaimed after expiry and the reclaimed key is reported |
| TC-61 | A workspace task acquired no member | The task is classified as unproven and the review is unavailable and not retryable |
| TC-62 | A member repository cannot be prepared at registration | No project row is registered or activated |
Test Infrastructure
- Vitest across
packages/core,packages/engine,packages/dashboard, andpackages/cli. - PostgreSQL-backed tests under
packages/core/src/__tests__/postgres/use the embedded PostgreSQL instance for the lease, land-intent, concurrent-merge, and review-evidence publication suites. - The
*.real-git.test.tsfiles build throwaway Git repositories to exercise the land, the revert, the landed predicate, and the finalize cleanup against Git itself. - The
*.slow.test.tsfiles cover the long-running merge paths and stay outside the merge gate. - Temporary directories are created under the OS temp directory and removed after each test.
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall detect the member repositories of a project root by scanning only its direct children, excluding `node_modules`, `.fusion`, `.git`, `.pi`, and `.worktrees`, requiring a `.git` marker and a passing Git work-tree probe, and returning the members in sorted order | TC-1 |
| FR-2MustThe system shall record the member list in `.fusion/workspace.json` and read it back, accepting only entries that are strings and normalized relative paths inside the workspace root | TC-52 |
| FR-3MustThe system shall enable and disable workspace mode for a project, writing the `workspaceMode` setting in `.fusion/config.json` and the authority file `.fusion/workspace.json` in a documented order and reconciling the two when they diverge | TC-4, TC-5, TC-6, TC-7 |
| FR-4MustThe system shall add a member repository to an existing workspace idempotently, accepting only an in-root direct child that is a Git work tree and rejecting excluded names, absolute paths, and `..` escapes | TC-2, TC-3, TC-41 |
| FR-5MustThe system shall acquire one worktree per configured member repository when a task starts, under a durable per-repository lease, and record the worktree path, branch, base branch, and base commit for each member | TC-22, TC-24 |
| FR-6MustThe system shall resolve a base branch for each member repository, verify it in that repository, pin the resolved ref at acquisition, and fall back to that repository's own integration branch when the requested ref does not resolve | TC-10, TC-53 |
| FR-7MustThe system shall refresh every member checkout onto its recorded base branch before execution dispatches, and keep the proven local checkout when the refresh is dirty, conflicting, or unresolvable | TC-11, TC-12 |
| FR-8MustThe system shall require a confirmed repository scope on a workspace task and use that scope as the authority for review and landing, so an acquired checkout alone creates no obligation | TC-14, TC-56 |
| FR-9MustThe system shall review every modified in-scope member repository, qualify each finding with its repository, and return one aggregate verdict with a per-repository outcome for every scoped member | TC-17, TC-55, TC-57 |
| FR-10MustThe system shall capture review evidence per member from that member's recorded base commit to its task branch, including the changed file list, the repository-qualified file list, and a diff fingerprint | TC-18 |
| FR-11MustThe system shall land each member repository independently onto that member's own local integration ref under a durable write fence, and land as it goes so an earlier member can land before a later member fails | TC-28, TC-30, TC-32 |
| FR-12MustThe system shall record the landing proof for each member and skip a member that is already landed when a land is retried, so a retry never advances an integration ref twice | TC-20, TC-21, TC-29 |
| FR-13MustThe system shall recover a partial land by re-enqueuing the task and retrying only the unlanded members, and park the task for manual intervention when a member branch is gone and no landing proof exists | TC-33 |
| FR-14MustThe system shall revert a workspace task across every member repository by classifying all members before committing any of them, and roll every touched member back when one member conflicts | TC-34, TC-35, TC-36 |
| FR-15MustThe system shall block completion when a member's main checkout holds a commit attributed to the task, and report an uncommitted main-checkout change as a warning rather than a refusal | TC-19, TC-37 |
| FR-16MustThe system shall classify a workspace task that acquired no member worktree as not applicable, commit-free eligible, or unproven, and use the same classification in review and in completion verification | TC-13, TC-61 |
| FR-17MustThe system shall expose workspace detection and the member list over HTTPHypertext Transfer Protocol, and let a caller add a member repository | TC-40, TC-41, TC-42 |
| FR-18MustThe system shall list, read, and write files inside a workspace through the dashboard file routes, where a workspace is the project root or a task worktree | TC-43 |
| FR-19ShouldThe system shall prepare every configured or detected member at registration, giving each member a verifiable `HEAD` and the managed `.gitignore` rules, and register no project when preparation fails | TC-62 |
| FR-20ShouldThe system shall apply one operator-supplied branch name to every acquired member repository, attaching to an existing branch when one is already there | TC-48 |
| FR-21ShouldThe system shall interpret the declared File Scope per member repository, so a member prefix yields a member-local scope and a sibling member's declaration yields no authority | TC-8, TC-9 |
| FR-22ShouldThe system shall publish a member's landing to that member's own remote when `pushAfterMerge` is enabled, and keep the landing on the local integration ref when it is disabled | TC-30 |
| FR-23ShouldThe system shall revert a workspace task through one pull request per member repository when auto-merge is off, and refuse the direct integration-branch path | TC-36 |
| FR-24ShouldThe system shall remove the member worktrees and the workspace task directory after a successful merge and when a workspace task is archived, and preserve a member that holds uncommitted or unverifiable content | TC-45, TC-46, TC-47 |
| NFR-1MustAcquire, land, and merge dispatch shall contend on one durable project-and-repository lease key, and a fresh or reclaimed claim shall carry a higher fence token than the claim it replaces | TC-23, TC-25, TC-26, TC-59, TC-60 |
| NFR-2MustThe workspace root shall stay browse-only and non-Git, and shall never be a task checkout, a reviewer working directory, or a landing target | TC-39 |
| NFR-3MustA member entry shall be a normalized relative path inside the workspace root, and an absolute path, a `..` escape, or a non-string entry shall never reach a path join | TC-3, TC-51 |
| NFR-4MustA member's scope, review evidence, and landing obligations shall never be satisfied by another member's files | TC-9, TC-14, TC-56 |
| NFR-5MustA landing whose proof write was lost shall still be recognized as landed through the task identifier trailer on the integration history, so the retry does not squash twice | TC-20, TC-54 |
| NFR-6MustA lost or refused lease renewal shall abort the owning land before its next durable or remote write, and the current owner and fence token shall remain the write authority | TC-59 |
| NFR-7MustA remote publication shall compare-and-swap the target ref and every fence ref of the tenancy in one atomic push | TC-32 |
| NFR-8MustA partial land shall stay recoverable and shall never be reported as one atomic merge | TC-29, TC-33 |
| NFR-9MustA lease held by a dead node or a finished task shall be reclaimable once it expires, and the reclaim shall name the owner and the expected fence token | TC-60 |
| NFR-10MustThe aggregate workspace review verdict shall be deterministic and independent of the order in which members are reviewed | TC-17 |
| NFR-11MustReview and landing shall consume the same repository-qualified file list and the same per-repository diff fingerprint | TC-18, TC-58 |
| NFR-12ShouldBase-branch decisions and land outcomes shall be written to the task log and to run audit with identifiers and fixed outcomes only, and never with ref names or file paths | TC-10, TC-28 |
| NFR-13ShouldThe workspace configuration read shall be memoized per host, and a mode toggle shall invalidate the memo so a stale read cannot repopulate the old mode | TC-7 |
| NFR-14ShouldEvery per-member worktree update shall go through the advisory-locked per-key store merge, so a concurrent sibling acquisition, landing, or teardown never loses an entry | TC-22, TC-45 |
Key Test Files
- Detection, member list, and mode toggle:
packages/core/src/__tests__/workspace-add-repo.test.ts,packages/core/src/__tests__/workspace-mode-toggle.test.ts,packages/core/src/__tests__/settings-workspace-toggle-side-effect.test.ts - Durable coordination:
packages/core/src/__tests__/postgres/workspace-coordination-leases.pg.test.ts,packages/core/src/__tests__/postgres/workspace-leases.pg.test.ts,packages/core/src/__tests__/postgres/workspace-review-evidence-publish.pg.test.ts,packages/core/src/__tests__/postgres/workspace-worktrees-concurrent-merge.pg.test.ts - Acquisition and base resolution:
packages/engine/src/__tests__/worktree-acquisition-workspace.test.ts,packages/engine/src/__tests__/workspace-acquire-claim-release.test.ts,packages/engine/src/__tests__/workspace-acquire-contention-hold.test.ts,packages/engine/src/__tests__/workspace-acquire-lease-authority.test.ts,packages/engine/src/__tests__/workspace-base-branch.test.ts,packages/engine/src/__tests__/workspace-base-refresh.test.ts - Review:
packages/engine/src/__tests__/reviewer-workspace.test.ts,packages/engine/src/__tests__/workspace-review-evidence.test.ts,packages/engine/src/__tests__/workspace-review-complete-coverage.test.ts,packages/engine/src/__tests__/workspace-review-diff-base.test.ts,packages/engine/src/__tests__/workspace-review-findings.test.ts,packages/engine/src/__tests__/workspace-review-evidence-publish-fail-closed.test.ts,packages/engine/src/__tests__/workspace-review-remediation.test.ts,packages/engine/src/__tests__/workspace-review-remediation-routing.test.ts - Land:
packages/engine/src/__tests__/workspace-merger.test.ts,packages/engine/src/__tests__/workspace-merger-lease.test.ts,packages/engine/src/__tests__/workspace-merger-idempotency.slow.test.ts,packages/engine/src/__tests__/workspace-merger-scope-gates.test.ts,packages/engine/src/__tests__/workspace-push-after-merge.test.ts,packages/engine/src/__tests__/workspace-integration-target.test.ts,packages/engine/src/__tests__/workspace-land-predicate.revert-boundary.test.ts,packages/engine/src/__tests__/workspace-land-predicate-recycled-id.real-git.test.ts - Recovery and completion:
packages/engine/src/__tests__/self-healing-workspace.test.ts,packages/engine/src/__tests__/workspace-finalize-cleanup.real-git.test.ts,packages/engine/src/__tests__/workspace-post-landing-worktree-cleanup.test.ts,packages/engine/src/__tests__/executor-workspace-main-checkout-guard.test.ts,packages/engine/src/__tests__/executor-workspace-taskdone.test.ts,packages/engine/src/__tests__/workspace-zero-acquire.test.ts - Revert:
packages/engine/src/__tests__/task-revert.workspace.real-git.test.ts,packages/engine/src/__tests__/task-revert-workspace-pr.real-git.test.ts - HTTPHypertext Transfer Protocol surface:
packages/dashboard/src/__tests__/workspace-add-repo-route.test.ts,packages/dashboard/src/__tests__/settings-workspace-mode-route.test.ts,packages/dashboard/app/api/__tests__/workspace-files-api.test.ts,packages/dashboard/src/routes/__tests__/register-file-workspace-routes.test.ts - Documentation and lifecycle:
packages/dashboard/src/__tests__/workspace-documentation.test.ts,packages/dashboard/src/__tests__/task-reset-workspace-lifecycle.test.ts,packages/core/src/__tests__/archive-removes-workspace-worktrees.test.ts,packages/engine/src/__tests__/workspace-e2e.test.ts,packages/engine/src/__tests__/pipeline-smoke/pipeline-workspace.pipeline.test.ts
requirements
- The code does not say whether a workspace task may be created against a member list that changes while the task is in review. The membership snapshot is captured at acquisition, so the current behavior is that later membership changes affect only later tasks, and the intent behind that choice is not recorded.
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Insights: ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree Learning Extraction
Overview
Fusion runs a model-assisted extraction over project memory to produce normalized, deduplicated insights about a project, covering quality, security, architecture, reliability, and feature opportunities. Each extraction is tracked as a run with a status, a retry policy, and an ordered event trail, so an operator can see what happened and retry a transient failure. An operator reviews the insights in a dashboard view, dismisses, archives, or unarchives them, and turns a selected insight into a board task.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Reads the insights a project has produced and turns the useful ones into tracked work. |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree maintainer | Keeps the insight list free of noise by dismissing or archiving findings that no longer matter. |
| Agent | Queries persisted insights and insight runs through the CLICommand-line interface tool surface. |
| Engine scheduler | Publishes workflow insights such as backlog health and unlinked-mission advisories into the same store. |
| Model provider | Serves the extraction call, so the run must be bounded, cancellable, and retried on transient errors. |
Functional Requirements
Order rows by priority: Must first, then Should, then May.
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall persist each insight with an id, a project scope, a title, a body, a category, a status, a fingerprint, provenance, a link to the last run that produced it, and creation and update timestamps. | Must | The system shall persist each insight with an id, a project scope, a title, a body, a category, a status, a fingerprint, provenance, a link to the last run that produced it, and creation and update timestamps. |
| FR-2MustThe system shall classify each insight with one of the fifteen categories defined by the insight category type, covering quality, performance, architecture, security, reliability, user experience, testability, documentation, dependency, workflow, other, features, competitive analysis, research, and trends. | Must | The system shall classify each insight with one of the fifteen categories defined by the insight category type, covering quality, performance, architecture, security, reliability, user experience, testability, documentation, dependency, workflow, other, features, competitive analysis, research, and trends. |
| FR-3MustThe system shall move an insight through the generated, confirmed, stale, dismissed, and archived states, and shall return an archived insight to the confirmed state when it is unarchived. | Must | The system shall move an insight through the generated, confirmed, stale, dismissed, and archived states, and shall return an archived insight to the confirmed state when it is unarchived. |
| FR-4MustThe system shall deduplicate insights by project and fingerprint, updating the matching row in place and preserving its original id and creation timestamp instead of inserting a second row. | Must | The system shall deduplicate insights by project and fingerprint, updating the matching row in place and preserving its original id and creation timestamp instead of inserting a second row. |
| FR-5MustThe system shall track each extraction as a run that records its trigger, status, summary, error, the number of insights created and updated, the input and output metadata snapshots, and the lifecycle fields. | Must | The system shall track each extraction as a run that records its trigger, status, summary, error, the number of insights created and updated, the input and output metadata snapshots, and the lifecycle fields. |
| FR-6MustThe system shall treat a completed, failed, or cancelled run as immutable and shall reject any status change that the run state machine does not allow. | Must | The system shall treat a completed, failed, or cancelled run as immutable and shall reject any status change that the run state machine does not allow. |
| FR-7MustThe system shall keep an ordered event trail for each run, with a monotonically increasing sequence number, an event type, a message, an optional status and failure classification, and optional metadata. | Must | The system shall keep an ordered event trail for each run, with a monotonically increasing sequence number, an event type, a message, an optional status and failure classification, and optional metadata. |
| FR-8MustThe system shall execute a manual run by reading the project working memory, prompting the model with the working memory and the existing insights, parsing the returned insight list, merging the result into the insights memory file, and upserting every insight into the store. | Must | The system shall execute a manual run by reading the project working memory, prompting the model with the working memory and the existing insights, parsing the returned insight list, merging the result into the insights memory file, and upserting every insight into the store. |
| FR-9MustThe system shall classify a run failure as cancelled, timed out, retryable transient, or non-retryable, and shall retry a retryable failure until the configured attempt limit is reached. | Must | The system shall classify a run failure as cancelled, timed out, retryable transient, or non-retryable, and shall retry a retryable failure until the configured attempt limit is reached. |
| FR-10MustThe system shall refuse to start a second run for the same project and trigger while a pending or running run exists, and shall answer that request with a conflict status carrying the active run id. | Must | The system shall refuse to start a second run for the same project and trigger while a pending or running run exists, and shall answer that request with a conflict status carrying the active run id. |
| FR-11MustThe system shall cancel a pending run immediately, and shall abort the execution of a running run when the operator requests cancellation. | Must | The system shall cancel a pending run immediately, and shall abort the execution of a running run when the operator requests cancellation. |
| FR-12MustThe system shall retry a failed run whose failure class is retryable transient, reusing the model selection, reasoning effort, and input metadata recorded on the original run. | Must | The system shall retry a failed run whose failure class is retryable transient, reusing the model selection, reasoning effort, and input metadata recorded on the original run. |
| FR-13MustThe system shall sweep pending and running runs that have no live execution owner after the grace window, and shall mark each recovered run as failed with a non-retryable cause. | Must | The system shall sweep pending and running runs that have no live execution owner after the grace window, and shall mark each recovered run as failed with a non-retryable cause. |
| FR-14MustThe system shall expose HTTPHypertext Transfer Protocol endpoints to list insights, read one insight, update one insight, delete one insight, dismiss one insight, archive one insight, and unarchive one insight. | Must | The system shall expose HTTPHypertext Transfer Protocol endpoints to list insights, read one insight, update one insight, delete one insight, dismiss one insight, archive one insight, and unarchive one insight. |
| FR-15MustThe system shall expose HTTPHypertext Transfer Protocol endpoints to trigger a run, list runs, read one run, list the events of one run, cancel one run, and retry one run. | Must | The system shall expose HTTPHypertext Transfer Protocol endpoints to trigger a run, list runs, read one run, list the events of one run, cancel one run, and retry one run. |
| FR-16MustThe system shall return a task payload draft for an insight so the operator can create a board task from it, and shall archive the insight as part of that flow. | Must | The system shall return a task payload draft for an insight so the operator can create a board task from it, and shall archive the insight as part of that flow. |
| FR-17MustThe system shall present a dashboard insights view that groups insights by category, shows the latest run status, and offers the dismiss, archive, unarchive, and create-task actions on each insight. | Must | The system shall present a dashboard insights view that groups insights by category, shows the latest run status, and offers the dismiss, archive, unarchive, and create-task actions on each insight. |
| FR-18ShouldThe system shall let the operator select the model and the reasoning effort for a run, and shall record that selection on the run so a retry reproduces it. | Should | The system shall let the operator select the model and the reasoning effort for a run, and shall record that selection on the run so a retry reproduces it. |
| FR-19ShouldThe system shall order insight lists ascending by creation timestamp and then by id, and shall order run lists newest first by creation timestamp and then by id. | Should | The system shall order insight lists ascending by creation timestamp and then by id, and shall order run lists newest first by creation timestamp and then by id. |
| FR-20ShouldThe system shall let the caller filter the insight list by category, status, and producing run, and shall filter the run list by status and trigger, and shall reject a non-numeric or out-of-range pagination value. | Should | The system shall let the caller filter the insight list by category, status, and producing run, and shall filter the run list by status and trigger, and shall reject a non-numeric or out-of-range pagination value. |
| FR-21ShouldThe system shall expose persisted insights and insight runs to agents through the insight list, insight show, insight run list, and insight run show tools. | Should | The system shall expose persisted insights and insight runs to agents through the insight list, insight show, insight run list, and insight run show tools. |
| FR-22ShouldThe system shall recover an orphaned active run when a run request finds an active run with no live execution owner, and shall then start the new run. | Should | The system shall recover an orphaned active run when a run request finds an active run with no live execution owner, and shall then start the new run. |
Non-Functional Requirements
Order rows by priority: Must first, then Should, then May.
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustThe system shall recover every pending or running run that has no live execution owner once it passes the grace window, so a crashed process cannot leave a run active forever. | Must | Reliability | The system shall recover every pending or running run that has no live execution owner once it passes the grace window, so a crashed process cannot leave a run active forever. |
| NFR-2MustThe system shall bound each attempt with a timeout and shall abort the model call when the run is cancelled or the timeout elapses. | Must | Reliability | The system shall bound each attempt with a timeout and shall abort the model call when the run is cancelled or the timeout elapses. |
| NFR-3MustThe system shall compute the insight fingerprint as a deterministic hash of the lowercased and whitespace-collapsed title plus the lowercased category, so the same observation always maps to the same key. | Must | Deduplication | The system shall compute the insight fingerprint as a deterministic hash of the lowercased and whitespace-collapsed title plus the lowercased category, so the same observation always maps to the same key. |
| NFR-4MustThe system shall allow at most one active run per project and trigger, so a project never pays for two concurrent extractions of the same kind. | Must | Cost | The system shall allow at most one active run per project and trigger, so a project never pays for two concurrent extractions of the same kind. |
| NFR-5MustThe system shall append a durable event for every run creation, status change, attempt, retry, cancellation, and orphan recovery, so an operator can rebuild the history of a run from the event trail alone. | Must | Observability | The system shall append a durable event for every run creation, status change, attempt, retry, cancellation, and orphan recovery, so an operator can rebuild the history of a run from the event trail alone. |
| NFR-6ShouldThe system shall run the stale-run sweep at startup, on a fixed interval, and on demand before listing runs, and shall log a sweep failure without failing the surrounding request. | Should | Observability | The system shall run the stale-run sweep at startup, on a fixed interval, and on demand before listing runs, and shall log a sweep failure without failing the surrounding request. |
| NFR-7ShouldThe system shall store the operator's model and reasoning-effort selection on the run input metadata, so a retry uses the same provider and the same effort as the original attempt. | Should | Cost | The system shall store the operator's model and reasoning-effort selection on the run input metadata, so a retry uses the same provider and the same effort as the original attempt. |
| NFR-8ShouldThe system shall serve the same feature from the SQLite-backed insight store and the PostgreSQL-backed async insight store through one method surface, so callers behave the same in both backends. | Should | Portability | The system shall serve the same feature from the SQLite-backed insight store and the PostgreSQL-backed async insight store through one method surface, so callers behave the same in both backends. |
| NFR-9ShouldThe system shall run the extraction session with read-only tools and shall keep materialized secret values out of session diagnostics. | Should | Security | The system shall run the extraction session with read-only tools and shall keep materialized secret values out of session diagnostics. |
| NFR-10ShouldThe system shall bound the insight list by limit and offset, and the dashboard shall cap its persisted insight cache so a long-lived browser session cannot grow without bound. | Should | Performance | The system shall bound the insight list by limit and offset, and the dashboard shall cap its persisted insight cache so a long-lived browser session cannot grow without bound. |
Constraints
- Insights are scoped to one project, and the PostgreSQL tables partition rows by the project partition column.
- The insight body is nullable so a partially generated insight can be stored with a title only.
- The insight title is derived from the extracted content and truncated to one hundred characters.
- The extraction session runs with read-only tools, so an extraction never changes the project source.
- The memory insight categories pattern, principle, convention, pitfall, and context map onto the insight categories workflow, architecture, workflow, quality, and other.
- The dashboard insights view is gated behind the experimental insights feature flag.
- The dashboard and the CLICommand-line interface read the same store, so both backends must expose the same records.
Acceptance Criteria
Every FR and NFR shall have at least one acceptance criterion.
Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).
-
FR-1MustThe system shall persist each insight with an id, a project scope, a title, a body, a category, a status, a fingerprint, provenance, a link to the last run that produced it, and creation and update timestamps.
gherkin @FR-1MustThe system shall persist each insight with an id, a project scope, a title, a body, a category, a status, a fingerprint, provenance, a link to the last run that produced it, and creation and update timestamps. Scenario: Persist an insight with its full field set Given a project with an open insight store When an insight is created with a title, a body, a category, and provenance Then the stored insight carries an id, the project scope, the category, the status, the fingerprint, the provenance, a null last run link, and creation and update timestamps -
FR-2MustThe system shall classify each insight with one of the fifteen categories defined by the insight category type, covering quality, performance, architecture, security, reliability, user experience, testability, documentation, dependency, workflow, other, features, competitive analysis, research, and trends.
gherkin @FR-2MustThe system shall classify each insight with one of the fifteen categories defined by the insight category type, covering quality, performance, architecture, security, reliability, user experience, testability, documentation, dependency, workflow, other, features, competitive analysis, research, and trends. Scenario: Accept every declared insight category Given the insight category type When the category list is read Then it contains exactly fifteen values including features, competitive analysis, research, and trends -
FR-3MustThe system shall move an insight through the generated, confirmed, stale, dismissed, and archived states, and shall return an archived insight to the confirmed state when it is unarchived.
gherkin @FR-3MustThe system shall move an insight through the generated, confirmed, stale, dismissed, and archived states, and shall return an archived insight to the confirmed state when it is unarchived. Scenario: Archive and unarchive an insight Given a confirmed insight When it is archived and then unarchived Then the status moves to archived and back to confirmed -
FR-4MustThe system shall deduplicate insights by project and fingerprint, updating the matching row in place and preserving its original id and creation timestamp instead of inserting a second row.
gherkin @FR-4MustThe system shall deduplicate insights by project and fingerprint, updating the matching row in place and preserving its original id and creation timestamp instead of inserting a second row. Scenario: Re-extract the same observation Given a project with one insight holding fingerprint FP-1 When the same fingerprint is upserted again with new content Then the row keeps its original id and creation timestamp and holds the new content -
FR-5MustThe system shall track each extraction as a run that records its trigger, status, summary, error, the number of insights created and updated, the input and output metadata snapshots, and the lifecycle fields.
gherkin @FR-5MustThe system shall track each extraction as a run that records its trigger, status, summary, error, the number of insights created and updated, the input and output metadata snapshots, and the lifecycle fields. Scenario: Record a run and its outcome Given a project with an open insight store When a run is created for the manual trigger and later completes with two created and one updated insight Then the run records the trigger, the completed status, the summary, the two created and one updated counts, the input and output metadata, and the lifecycle attempt fields -
FR-6MustThe system shall treat a completed, failed, or cancelled run as immutable and shall reject any status change that the run state machine does not allow.
gherkin @FR-6MustThe system shall treat a completed, failed, or cancelled run as immutable and shall reject any status change that the run state machine does not allow. Scenario: Mutate a terminal run Given a completed run When the run is updated with any field Then the store refuses the write with a terminal immutability error -
FR-7MustThe system shall keep an ordered event trail for each run, with a monotonically increasing sequence number, an event type, a message, an optional status and failure classification, and optional metadata.
gherkin @FR-7MustThe system shall keep an ordered event trail for each run, with a monotonically increasing sequence number, an event type, a message, an optional status and failure classification, and optional metadata. Scenario: Read the event trail in order Given a run with a creation event and two status events When the run events are listed Then they come back ordered by sequence number with no gaps in the sequence -
FR-8MustThe system shall execute a manual run by reading the project working memory, prompting the model with the working memory and the existing insights, parsing the returned insight list, merging the result into the insights memory file, and upserting every insight into the store.
gherkin @FR-8MustThe system shall execute a manual run by reading the project working memory, prompting the model with the working memory and the existing insights, parsing the returned insight list, merging the result into the insights memory file, and upserting every insight into the store. Scenario: Run a manual extraction Given a project with working memory notes and no existing insights When a manual run is triggered Then the working memory is read, the model is prompted, the parsed insights are merged into the insights memory file, and each insight is upserted into the store -
FR-9MustThe system shall classify a run failure as cancelled, timed out, retryable transient, or non-retryable, and shall retry a retryable failure until the configured attempt limit is reached.
gherkin @FR-9MustThe system shall classify a run failure as cancelled, timed out, retryable transient, or non-retryable, and shall retry a retryable failure until the configured attempt limit is reached. Scenario: Classify and retry a transient failure Given a run configured for two attempts When the first attempt fails with a connection reset error Then the run records a retryable transient failure and the executor starts a second attempt -
FR-10MustThe system shall refuse to start a second run for the same project and trigger while a pending or running run exists, and shall answer that request with a conflict status carrying the active run id.
gherkin @FR-10MustThe system shall refuse to start a second run for the same project and trigger while a pending or running run exists, and shall answer that request with a conflict status carrying the active run id. Scenario: Refuse a concurrent run Given a project with a running manual run When a second manual run is requested Then the request is answered with a conflict status whose details name the active run id and status -
FR-11MustThe system shall cancel a pending run immediately, and shall abort the execution of a running run when the operator requests cancellation.
gherkin @FR-11MustThe system shall cancel a pending run immediately, and shall abort the execution of a running run when the operator requests cancellation. Scenario: Cancel a pending run Given a pending run When the operator cancels it Then the run moves to cancelled with a cancellation timestamp and a cancel_requested event -
FR-12MustThe system shall retry a failed run whose failure class is retryable transient, reusing the model selection, reasoning effort, and input metadata recorded on the original run.
gherkin @FR-12MustThe system shall retry a failed run whose failure class is retryable transient, reusing the model selection, reasoning effort, and input metadata recorded on the original run. Scenario: Retry a transiently failed run Given a failed run whose failure class is retryable transient When the operator retries it Then a new run is created that links to the original through the lifecycle retry fields and reuses the recorded model and reasoning effort -
FR-13MustThe system shall sweep pending and running runs that have no live execution owner after the grace window, and shall mark each recovered run as failed with a non-retryable cause.
gherkin @FR-13MustThe system shall sweep pending and running runs that have no live execution owner after the grace window, and shall mark each recovered run as failed with a non-retryable cause. Scenario: Recover an orphaned active run Given a running run with no live execution owner that is older than the grace window When the sweep runs Then the run moves to failed with a non-retryable orphaned-run cause and a warning event -
FR-14MustThe system shall expose HTTPHypertext Transfer Protocol endpoints to list insights, read one insight, update one insight, delete one insight, dismiss one insight, archive one insight, and unarchive one insight.
gherkin @FR-14MustThe system shall expose HTTPHypertext Transfer Protocol endpoints to list insights, read one insight, update one insight, delete one insight, dismiss one insight, archive one insight, and unarchive one insight. Scenario: Manage one insight over HTTPHypertext Transfer Protocol Given a project with a stored insight When the insight is read, updated, dismissed, archived, unarchived, and finally deleted Then each call answers with the updated insight and the delete answers with an empty success status -
FR-15MustThe system shall expose HTTPHypertext Transfer Protocol endpoints to trigger a run, list runs, read one run, list the events of one run, cancel one run, and retry one run.
gherkin @FR-15MustThe system shall expose HTTPHypertext Transfer Protocol endpoints to trigger a run, list runs, read one run, list the events of one run, cancel one run, and retry one run. Scenario: Exercise the run endpoints Given a project with an insight store When a run is triggered, the runs are listed, one run is read, its events are listed, and the run is cancelled Then the trigger answers with a created status and the reads answer with the run and its events -
FR-16MustThe system shall return a task payload draft for an insight so the operator can create a board task from it, and shall archive the insight as part of that flow.
gherkin @FR-16MustThe system shall return a task payload draft for an insight so the operator can create a board task from it, and shall archive the insight as part of that flow. Scenario: Draft a task from an insight Given a stored insight with a title and a body When the task draft endpoint is called Then the response carries the insight, a suggested title, and a suggested description -
FR-17MustThe system shall present a dashboard insights view that groups insights by category, shows the latest run status, and offers the dismiss, archive, unarchive, and create-task actions on each insight.
gherkin @FR-17MustThe system shall present a dashboard insights view that groups insights by category, shows the latest run status, and offers the dismiss, archive, unarchive, and create-task actions on each insight. Scenario: Browse insights in the dashboard Given insights in two categories and a latest completed run When the insights view renders Then it lists the populated categories, shows the run status, and offers the dismiss, archive, and create-task actions on each insight -
FR-18ShouldThe system shall let the operator select the model and the reasoning effort for a run, and shall record that selection on the run so a retry reproduces it.
gherkin @FR-18ShouldThe system shall let the operator select the model and the reasoning effort for a run, and shall record that selection on the run so a retry reproduces it. Scenario: Choose a model and reasoning effort for a run Given the operator opens the model picker beside the generate action When a model and a reasoning effort are chosen and a run is started Then the selection is stored in the browser and the run records it in its input metadata -
FR-19ShouldThe system shall order insight lists ascending by creation timestamp and then by id, and shall order run lists newest first by creation timestamp and then by id.
gherkin @FR-19ShouldThe system shall order insight lists ascending by creation timestamp and then by id, and shall order run lists newest first by creation timestamp and then by id. Scenario: Order lists deterministically Given two insights written in the same millisecond When the insights are listed Then they come back ordered by creation timestamp and then by ascending id -
FR-20ShouldThe system shall let the caller filter the insight list by category, status, and producing run, and shall filter the run list by status and trigger, and shall reject a non-numeric or out-of-range pagination value.
gherkin @FR-20ShouldThe system shall let the caller filter the insight list by category, status, and producing run, and shall filter the run list by status and trigger, and shall reject a non-numeric or out-of-range pagination value. Scenario: Reject a bad pagination value Given a caller filtering the insight list When the limit is not a number or is below one Then the request is answered with a bad request status -
FR-21ShouldThe system shall expose persisted insights and insight runs to agents through the insight list, insight show, insight run list, and insight run show tools.
gherkin @FR-21ShouldThe system shall expose persisted insights and insight runs to agents through the insight list, insight show, insight run list, and insight run show tools. Scenario: Query insights from an agent session Given an agent session with the insight tools registered When the agent lists insights and shows one by id Then the list tool reports the count and the show tool returns the stored insight -
FR-22ShouldThe system shall recover an orphaned active run when a run request finds an active run with no live execution owner, and shall then start the new run.
gherkin @FR-22ShouldThe system shall recover an orphaned active run when a run request finds an active run with no live execution owner, and shall then start the new run. Scenario: Recover an orphan before starting a run Given an active manual run with no live execution owner older than the grace window When a new manual run is requested Then the orphan is recovered to failed and the new run starts -
NFR-1MustThe system shall recover every pending or running run that has no live execution owner once it passes the grace window, so a crashed process cannot leave a run active forever.
gherkin @NFR-1MustThe system shall recover every pending or running run that has no live execution owner once it passes the grace window, so a crashed process cannot leave a run active forever. Scenario: No run stays active after a crash Given a process that stopped while a run was in the running state When the periodic sweep runs after the grace window Then the run is recovered to failed rather than left active -
NFR-2MustThe system shall bound each attempt with a timeout and shall abort the model call when the run is cancelled or the timeout elapses.
gherkin @NFR-2MustThe system shall bound each attempt with a timeout and shall abort the model call when the run is cancelled or the timeout elapses. Scenario: Bound an attempt by timeout Given a run with a configured attempt timeout When the attempt exceeds that timeout Then the attempt is aborted and the run is recorded as timed out -
NFR-3MustThe system shall compute the insight fingerprint as a deterministic hash of the lowercased and whitespace-collapsed title plus the lowercased category, so the same observation always maps to the same key.
gherkin @NFR-3MustThe system shall compute the insight fingerprint as a deterministic hash of the lowercased and whitespace-collapsed title plus the lowercased category, so the same observation always maps to the same key. Scenario: Fingerprint is stable across wording Given the same title written in different letter case and spacing When the fingerprint is computed for both Then both produce the same eight character hexadecimal value -
NFR-4MustThe system shall allow at most one active run per project and trigger, so a project never pays for two concurrent extractions of the same kind.
gherkin @NFR-4MustThe system shall allow at most one active run per project and trigger, so a project never pays for two concurrent extractions of the same kind. Scenario: One active run per trigger Given a project with a running scheduled run When a scheduled run is requested Then no second run is created for that project and trigger -
NFR-5MustThe system shall append a durable event for every run creation, status change, attempt, retry, cancellation, and orphan recovery, so an operator can rebuild the history of a run from the event trail alone.
gherkin @NFR-5MustThe system shall append a durable event for every run creation, status change, attempt, retry, cancellation, and orphan recovery, so an operator can rebuild the history of a run from the event trail alone. Scenario: Rebuild a run history from events Given a run that was created, retried, and then completed When its events are read Then the trail holds a creation event, an attempt event, a retry event, and a completion event -
NFR-6ShouldThe system shall run the stale-run sweep at startup, on a fixed interval, and on demand before listing runs, and shall log a sweep failure without failing the surrounding request.
gherkin @NFR-6ShouldThe system shall run the stale-run sweep at startup, on a fixed interval, and on demand before listing runs, and shall log a sweep failure without failing the surrounding request. Scenario: Sweep on demand before listing runs Given a caller listing insight runs When the request is served Then a stale-run sweep runs first and a sweep failure is logged without failing the list -
NFR-7ShouldThe system shall store the operator's model and reasoning-effort selection on the run input metadata, so a retry uses the same provider and the same effort as the original attempt.
gherkin @NFR-7ShouldThe system shall store the operator's model and reasoning-effort selection on the run input metadata, so a retry uses the same provider and the same effort as the original attempt. Scenario: Retry keeps the original cost profile Given a run that recorded a model provider, a model id, and a reasoning effort When that run is retried Then the retry attempt uses the same provider, model id, and reasoning effort -
NFR-8ShouldThe system shall serve the same feature from the SQLite-backed insight store and the PostgreSQL-backed async insight store through one method surface, so callers behave the same in both backends.
gherkin @NFR-8ShouldThe system shall serve the same feature from the SQLite-backed insight store and the PostgreSQL-backed async insight store through one method surface, so callers behave the same in both backends. Scenario: Same behavior in both backends Given a project served by the PostgreSQL-backed async insight store When an insight is upserted and a run is created Then the same method names return the same record shapes as the SQLite-backed store -
NFR-9ShouldThe system shall run the extraction session with read-only tools and shall keep materialized secret values out of session diagnostics.
gherkin @NFR-9ShouldThe system shall run the extraction session with read-only tools and shall keep materialized secret values out of session diagnostics. Scenario: Extraction cannot change the project Given a manual insight run When the extraction session is created Then the session is limited to read-only tools and carries no materialized secret values in its diagnostics -
NFR-10ShouldThe system shall bound the insight list by limit and offset, and the dashboard shall cap its persisted insight cache so a long-lived browser session cannot grow without bound.
gherkin @NFR-10ShouldThe system shall bound the insight list by limit and offset, and the dashboard shall cap its persisted insight cache so a long-lived browser session cannot grow without bound. Scenario: Bound the persisted insight cache Given a project with more than five hundred insights When the dashboard persists its insight cache Then the cache holds at most five hundred entries
Conflicts
The insight category type declares fifteen categories, and the CLICommand-line interface tool and the dashboard view accept all fifteen. The dashboard insight route validates the category filter and the category update against a shorter list of eleven categories that omits features, competitive analysis, research, and trends. A caller that filters or updates an insight by one of those four categories is answered with a bad request status even though the same values are accepted elsewhere.
Open Questions
- Should the dashboard insight route accept the four extended categories in its filter and update validation lists, or should the category type be reduced to the eleven values the route accepts.
- The
create-taskendpoint returns a payload draft and leaves the board task creation to the caller, so the endpoint name does not describe what it does. Should it be renamed or should it create the task itself. - The run trigger list includes schedule, task completion, and merge event, and the route accepts all of them, but no scheduler, task completion hook, or merge hook starts a run today, so the manual trigger is the one in use. Should the remaining triggers be wired or removed from the type.
- The insight category type documents features, competitive analysis, research, and trends, and the dashboard renders them, but the model extraction prompt only asks for pattern, principle, convention, pitfall, and context. Should the prompt produce the extended categories too.
Specification: Insights: ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree Learning Extraction
Overview
The feature stores normalized insights in a project-scoped store, runs a model-assisted extraction over the project working memory, and tracks every extraction as a run with a status, a retry policy, and an ordered event trail. The dashboard exposes the insights and the runs over HTTPHypertext Transfer Protocol, renders them in a category-grouped view, and lets the operator turn an insight into a board task. The same store is reachable from the CLICommand-line interface tool surface so agents can read the insights a project has produced.
Architecture
+-------------------------------------------+
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree working memory |
| .fusion/memory/MEMORY.md |
+------------------+------------------------+
|
| readWorkingMemory
v
+-------------+ POST /api/insights/run +------------------+ prompt +------------------+
| Dashboard | ------------------------> | Insights route | ---------> | Model session |
| Insights | <------------------------- | insights- | <-------- | (read-only |
| view | run + insight records | routes.ts | insights | tools) |
+-------------+ +--------+---------+ +------------------+
| |
list / read / update | | run lifecycle
dismiss / archive | v
unarchive / delete | +---------------------+
create-task draft | | Insight run |
| | executor |
| | insight-run- |
| | executor.ts |
| +----------+----------+
| |
| | store calls
| v
| +---------------------------+
| | Insight store |
| | - SQLite InsightStore |
| | - AsyncInsightStore (PG) |
| +-------------+-------------+
| |
| v
| +---------------------------+
| | project_insights |
| | project_insight_runs |
| | project_insight_run_ |
| | events |
| +---------------------------+
|
| mergeInsights
| writeInsightsMemory
| |
| v
| +---------------------------+
| | .fusion/memory/ |
| | memory-insights.md |
| +---------------------------+
+---------------------------+ +---------------------------+
| Insight run sweeper | | CLICommand-line interface agent session |
| insight-run-sweeper.ts | | fn_insight_list / _show |
| startup / periodic / | | fn_insight_run_list /_show |
| drive-by sweep | +-------------+-------------+
+-------------+-------------+ |
| |
+----------------------+-------------+
|
v
+---------------------------+
| Insight store |
+---------------------------+
Engine scheduler ---> backlog pressure reporter
unlinked missions advisory reporter ----> Insight store
The dashboard reads and writes the insights through the HTTPHypertext Transfer Protocol router. The router resolves the store once per request through the request-scoped store, so the same handler serves the SQLite-backed store and the PostgreSQL-backed store. The run executor drives the run state machine and the sweeper recovers runs whose owner disappeared.
Data Models
Insight
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | string | PK, not null | Store-assigned identifier with the INS- prefix. Stable across upserts. |
| projectId | string | not null | ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree the insight belongs to. |
| title | string | not null | Short summary, derived from the extracted content and truncated to one hundred characters. |
| content | string | nullable | Full body of the insight. Nullable for a title-only insight. |
| category | enum | not null | One of fifteen insight categories. |
| status | enum | not null | One of generated, confirmed, stale, dismissed, archived. |
| fingerprint | string | not null | Deterministic dedupe key derived from the normalized title and category. |
| provenance | object | nullable | Trigger, description, related entity ids, token estimate, and free-form metadata. |
| lastRunId | string | nullable | Id of the most recent run that produced or updated the insight. |
| createdAt | string | not null | ISO-8601 creation timestamp, preserved on upsert. |
| updatedAt | string | not null | ISO-8601 timestamp of the last change. |
InsightRun
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | string | PK, not null | Store-assigned identifier with the INSR- prefix. |
| projectId | string | not null | ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree the run belongs to. |
| trigger | enum | not null | One of schedule, manual, task completion, merge event, api. |
| status | enum | not null | One of pending, running, completed, failed, cancelled. Terminal states are immutable. |
| summary | string | nullable | Human-readable outcome written on completion. |
| error | string | nullable | Error message written on failure or cancellation. |
| insightsCreated | integer | not null, default 0 | Insights inserted by the run. |
| insightsUpdated | integer | not null, default 0 | Existing insights updated by the run. |
| inputMetadata | object | nullable | Snapshot of what was analyzed, including the model provider, model id, and reasoning effort. |
| outputMetadata | object | nullable | Snapshot of what was produced, including insight ids and token counts. |
| lifecycle | object | nullable | Terminal reason and cause, failure class, retryable flag, attempt and max attempts, and the retry and root run links. |
| createdAt | string | not null | ISO-8601 timestamp of run creation. |
| startedAt | string | nullable | ISO-8601 timestamp of the first attempt. |
| completedAt | string | nullable | ISO-8601 timestamp of the terminal transition, set automatically. |
| cancelledAt | string | nullable | ISO-8601 timestamp of cancellation, set automatically. |
InsightRunEvent
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | string | PK, not null | Store-assigned identifier with the INSEVT- prefix. |
| runId | string | FK to run, not null, cascade delete | Run the event belongs to. |
| seq | integer | not null | Per-run sequence number, allocated as the current maximum plus one. |
| type | enum | not null | One of status changed, retry scheduled, cancel requested, timeout, info, warning, error. |
| message | string | not null | Human-readable event text. |
| status | enum | nullable | Run status at the time of the event. |
| classification | enum | nullable | One of cancelled, timed out, retryable transient, non-retryable. |
| metadata | object | nullable | Free-form event metadata, including the recovery marker and source. |
| createdAt | string | not null | ISO-8601 timestamp of the event. |
MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) artifacts
| Path | Format | Description |
|---|---|---|
.fusion/memory/MEMORY.md |
Markdown | Working memory read as the extraction input. |
.fusion/memory/memory-insights.md |
Markdown | Insights memory merged with every extraction result. |
APIApplication programming interface Contracts
The normative contract is in api.yaml (OpenAPI 3.1), written alongside this document.
The table below is a summary; request and response schemas, error response bodies, and status codes are in api.yaml.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/insights | List insights with optional category, status, run, and pagination filters. |
| POST | /api/insights/run | Trigger an extraction run and execute it. |
| GET | /api/insights/runs | List runs with optional status, trigger, and pagination filters. |
| GET | /api/insights/runs/:id | Read one run. |
| GET | /api/insights/runs/:id/events | List the event trail of one run. |
| POST | /api/insights/runs/:id/cancel | Cancel a pending or running run. |
| POST | /api/insights/runs/:id/retry | Retry a failed run whose failure class is retryable transient. |
| GET | /api/insights/:id | Read one insight. |
| PATCH | /api/insights/:id | Update the title, body, category, or status of one insight. |
| DELETE | /api/insights/:id | Delete one insight. |
| POST | /api/insights/:id/dismiss | Move one insight to the dismissed state. |
| POST | /api/insights/:id/archive | Move one insight to the archived state. |
| POST | /api/insights/:id/unarchive | Move one archived insight back to the confirmed state. |
| POST | /api/insights/:id/create-task | Return a task payload draft built from one insight. |
Error codes shared across endpoints:
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_INPUT | A filter, pagination value, trigger, or reasoning effort is not accepted. |
| 404 | NOT_FOUND | The requested insight or run does not exist. |
| 409 | ACTIVE_RUN_CONFLICT | A run for the same project and trigger is already active. The details carry the active run id and status. |
| 409 | RUN_TERMINAL | The run already reached a terminal state and cannot be cancelled. |
| 409 | RUN_NOT_RETRYABLE | The run is not failed, or its failure class is not retryable transient. |
| 500 | INTERNAL_ERROR | The store could not be resolved or the request failed unexpectedly. |
Sequences
Manual extraction run
Client Route Executor Store Model
| | | | |
|-- POST /run ---->| | | |
| |-- find active --->| | |
| |<-- none ---------| | |
| |-- create run ---->|-- insert ------>| |
| | |<-- pending -----| |
| |<-- run id -------| | |
| | |-- set running -->| |
| | |-- read memory ->| |
| | | |-- prompt ----->|
| | | |<-- json -------|
| | |-- parse + merge ->| |
| | |-- upsert ------->| |
| | |-- set completed ->| |
| |<-- 201 run -------| | |
|<-- 201 run -------| | | |
Orphan recovery sweep
Sweeper Store Events Run
| | | |
|-- list stale ---->| | |
|<-- pending/running rows | |
| | | |
|-- append warning ->|-------------->| |
| | | |
|-- set failed ---->| | |
| |--- update ----->|----------------->|
| | | |
|-- append status_changed ->|-------->| |
| | | |
The sweeper skips a run whose id is registered in the live controller map. A run inside the grace window is skipped. A recovered run is marked failed with a non-retryable cause and the recovery source recorded in the event metadata.
Insight to board task
Operator View Route Store Board
| | | | |
|--- create task -->| | | |
| |-- draft ----->| | |
| | |-- get insight --->| |
| | |<-- insight -------| |
| | |-- archive ------>| |
| |<-- draft -----| | |
| |-- createTask -------------------------->| |
| |<-- task id ---------------------------------------->|
The draft endpoint does not create a task. The view archives the insight and then creates the task through the normal intake path, which resolves the landing column from the selected or project-default workflow.
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Dedupe key | Hash of the normalized title and category | Keeps a repeated observation on one row without needing an embedding store. |
| Upsert behavior | Update the matching row and keep the original id and creation timestamp | Preserves the identity an operator already acted on. |
| Run immutability | Terminal runs reject every field write | A completed or failed run is an audit record, not a scratch pad. |
| Event trail | Append-only rows with a per-run sequence number | Lets an operator rebuild a run's history without parsing log output. |
| Run execution | Synchronous inside the request with a per-attempt timeout | The dashboard shows a finished run immediately and the request is bounded. |
| Failure classification | Regex on the error message split into four classes | Keeps the executor free of provider-specific error handling while still separating transient from permanent failures. |
| Cancellation | An abort controller registered per run id | The sweeper can tell a live run from an orphan, and cancellation reaches the model call. |
| Orphan recovery | Startup sweep, five-minute interval, and a sweep before listing runs | Covers a crash, a slow run, and a stale row regardless of when it appeared. |
| Backend portability | One method surface over SQLite and PostgreSQL stores | The dashboard, the CLICommand-line interface, and the engine all call the same names. |
| Presentation order | Reversed in the dashboard hook, not in the store | The store keeps ascending order for stable pagination and dedupe. |
| Model selection | Stored in the run input metadata | A retry must reproduce the original provider and reasoning effort without new schema columns. |
| Extraction tool scope | Read-only tools for the extraction session | An extraction reads the project, it never changes the project. |
| Task creation | The endpoint returns a draft and the view creates the task | Task creation follows the normal intake path, including duplicate checks and the workflow landing column. |
Risks and Unknowns
- The route validates insight categories against eleven values while the type, the CLICommand-line interface, and the dashboard use fifteen, so four categories cannot be filtered or set over HTTPHypertext Transfer Protocol.
- The fingerprint is a 32-bit hash, so two different titles in the same category can collide and merge two distinct insights.
- The extraction runs inside the HTTPHypertext Transfer Protocol request, so a proxy or client timeout can cut the request while the run continues in the store.
- The run event metadata carries the raw error message, so provider error text can reach the event trail.
- The dashboard caches the insight list in browser storage, so a stale cache can show insights that were dismissed on another surface.
- The insight body is written to the insights memory file as well as to the store, so the two copies can drift when one write fails.
- The run trigger list offers schedule, task completion, and merge event, and the route accepts all of them, but no scheduler, task completion hook, or merge hook starts a run today, so the manual trigger is the one in use.
- The engine publishes workflow insights such as backlog health and unlinked-mission advisories into the same store, so those rows share the extraction lifecycle even though no extraction produced them.
Out of Scope
- Scheduled memory insight extraction and working memory pruning, which the memory subsystem owns.
- The task recommendations section of the insights view, which aggregates follow-up suggestions from completed tasks.
- The backlog pressure reporter and the unlinked missions advisory reporter, which publish into the store but define their own content.
- Cross-project insight queries, insight sharing between projects, and insight export.
- Embedding-based or semantic similarity dedupe.
- The run list and run detail surfaces of the CLICommand-line interface, beyond the read-only tools they call.
Test Plan: Insights: ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree Learning Extraction
Scope
This plan covers the insight store contract, the run executor and its retry classification, the run event trail, the orphan sweeper, the HTTPHypertext Transfer Protocol surface of the insights router, the dashboard insights view and its hook, the model and reasoning-effort selection, and the CLICommand-line interface insight tools.
Out of scope are the scheduled memory extraction automation and the working memory pruning, which the memory subsystem owns and which packages/core/src/__tests__/memory-insights.test.ts covers, and the content of the workflow insights published by the engine reporters.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Store resolution in PostgreSQL backend mode | packages/core/src/__tests__/postgres/insight-store.pg.test.ts |
The store resolves without throwing and returns the async store. |
| TC-2 | Fingerprint dedupe on upsert | packages/core/src/__tests__/postgres/insight-store.pg.test.ts |
A repeated fingerprint keeps the original id and creation timestamp and holds the new content. |
| TC-3 | Count agrees with the filtered list | packages/core/src/__tests__/postgres/insight-store.pg.test.ts |
The count matches the number of listed insights for the same filter. |
| TC-4 | Terminal run immutability | packages/core/src/__tests__/postgres/insight-store.pg.test.ts |
Updating a completed run throws the terminal immutability error. |
| TC-5 | Invalid run status transition | packages/core/src/__tests__/postgres/insight-store.pg.test.ts |
A transition the run state machine forbids throws the invalid transition error. |
| TC-6 | Recall capture at the store factory | packages/core/src/__tests__/postgres/insight-store.pg.test.ts |
A new insight writes a recall record through the live recall writer. |
| TC-7 | Run creation, event sequencing, and completion | packages/core/src/__tests__/postgres/insight-store.pg.test.ts |
Events come back in sequence order and the terminal update sets the completion timestamp. |
| TC-8 | Full run lifecycle against the async store | packages/core/src/__tests__/postgres/insight-run-execution.pg.test.ts |
A run moves from pending to running to completed with the summary and the insight counts. |
| TC-9 | Failed attempt against the async store | packages/core/src/__tests__/postgres/insight-run-execution.pg.test.ts |
A thrown attempt leaves a failed run with the error text. |
| TC-10 | Retry of a retryable transient failure | packages/core/src/__tests__/postgres/insight-run-execution.pg.test.ts |
The retry runs a new attempt that reaches completion. |
| TC-11 | Insight grouping by category | packages/dashboard/app/hooks/__tests__/useInsights.test.ts |
Insights land in the section of their category and empty sections carry no item. |
| TC-12 | Newest-first presentation order | packages/dashboard/app/hooks/__tests__/useInsights.test.ts |
The list is ordered newest first and equal timestamps break by descending id, with malformed timestamps last. |
| TC-13 | Dismissed insights are filtered out | packages/dashboard/app/hooks/__tests__/useInsights.test.ts |
Insights with the dismissed status are not shown. |
| TC-14 | Cached insight hydration | packages/dashboard/app/hooks/__tests__/useInsights.test.ts |
Cached insights render without a loading state and the cache is capped at five hundred entries and isolated per project. |
| TC-15 | Manual run trigger and refresh | packages/dashboard/app/hooks/__tests__/useInsights.test.ts |
A completed run triggers a refresh and the latest run is shown. |
| TC-16 | Active run conflict handling | packages/dashboard/app/hooks/__tests__/useInsights.test.ts |
A conflict response hydrates the active run and raises a friendly error, and the in-flight state is always cleared. |
| TC-17 | Dismiss, archive, and unarchive actions | packages/dashboard/app/hooks/__tests__/useInsights.test.ts |
Each action updates the local record and a failure records the error. |
| TC-18 | Model and reasoning-effort selection | packages/dashboard/app/__tests__/insight-model-selector.test.tsx |
The selection persists in browser storage, restores on mount, shows an indicator, and is forwarded when a run starts. |
| TC-19 | Category sections and status badges | packages/dashboard/app/components/__tests__/InsightsView.test.tsx |
The populated sections render with the expected order and each insight carries the status badge of its status. |
| TC-20 | View action wiring | packages/dashboard/app/components/__tests__/InsightsView.test.tsx |
The dismiss and create-task actions fire, the run button is disabled while a run is in flight, and failures show an inline error without a success toast. |
| TC-21 | View states | packages/dashboard/app/components/__tests__/InsightsView.test.tsx |
The loading, top-level error, run-level error, and global empty states each render. |
| TC-22 | Backlog health filter and archived insights | packages/dashboard/app/components/__tests__/InsightsView.test.tsx |
The backlog health toggle filters the list and archived insights render with the archived class and an unarchive button. |
| TC-23 | View layout tiers | packages/dashboard/app/components/__tests__/InsightsView.test.tsx |
The header action cluster keeps the title and controls on desktop, stacks the title on mobile, and reflows on tablet. |
| TC-24 | CLICommand-line interface insight tools | packages/cli/src/__tests__/extension-insights.test.ts |
The four insight tools register, list and show insights and runs, and report invalid pagination and missing ids. |
| TC-25 | Extraction MCPModel Context Protocol forwarding | packages/dashboard/src/__tests__/mcp-helper-forwarding.test.ts |
A manual run forwards the scoped MCPModel Context Protocol server set to a read-only session and answers with a created status. |
| TC-26 | MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) extraction helpers | packages/core/src/__tests__/memory-insights.test.ts |
The prompt includes the working memory and the existing insights, the response parser accepts fenced and prefixed JSONJavaScript Object Notation, the merge skips duplicates, and the trigger honors the time and growth thresholds. |
| TC-27 | Engine workflow insight publishers | packages/engine/src/__tests__/backlog-pressure-reporter.test.ts and packages/engine/src/__tests__/unlinked-missions-advisory-reporter.test.ts |
Each reporter upserts one deduplicated workflow insight and falls back to a log entry when the insight store is unavailable. |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-28 | Route mounting and lazy view registration | packages/dashboard/src/routes/register-integrated-routers.ts and packages/dashboard/app/__tests__/lazy-loaded-views-docs.test.ts |
The insights router is mounted at /api/insights and the insights view stays a lazy-loaded chunk listed in the documentation inventory. |
| TC-29 | Dashboard guide coverage | packages/dashboard/src/__tests__/dashboard-guide.test.ts |
The Insights View section is present in the dashboard guide. |
| TC-30 | Run execution against the async store | packages/core/src/__tests__/postgres/insight-run-execution.pg.test.ts |
A create, run, and complete cycle persists through the store with ordered status and info events. |
End-to-End Tests
| ID | Description | Steps | Expected Outcome |
|---|---|---|---|
| TC-31 | Manual extraction through the HTTPHypertext Transfer Protocol surface | Start the dashboard against a project with working memory, then call POST /api/insights/run |
The run completes, the insights are listed by GET /api/insights, and the run events are listed by GET /api/insights/runs/{id}/events. |
| TC-32 | Insight to board task | Select an insight in the dashboard view and use the create-task action | The insight is archived, a task payload draft is returned, and the task is created through the normal intake path. |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-33 | Model returns output that is not JSONJavaScript Object Notation | The extraction fails, the run is recorded as failed, and the insights memory file keeps its prior content. |
| TC-34 | A run is still active when a new run is requested | The request is answered with a conflict status that names the active run, and no second run row is created. |
| TC-35 | A run has no live owner after the grace window | The sweep marks the run failed with a non-retryable cause and appends a warning event and a status event. |
| TC-36 | A run is cancelled while it is pending | The run moves to cancelled with a cancellation timestamp and no execution is started. |
| TC-37 | A failed run is not classified as retryable transient | The retry request is answered with a conflict status and no new run is created. |
| TC-38 | An unknown insight or run id is requested | The request is answered with a not found status. |
| TC-39 | A bad pagination or filter value is sent | The request is answered with a bad request status. |
| TC-40 | The insight store cannot be resolved | The request is answered with an internal error status. |
| TC-41 | Two insights in one category produce the same fingerprint | The second upsert updates the first row instead of inserting a second one. |
Test Infrastructure
- The shared embedded PostgreSQL harness from
packages/core/src/__test-utils__/pg-test-harness.ts, which provides a project-scoped store for the store and executor tests. - A stubbed
executeAttemptcallback for the run executor tests, so no model provider is called. - An Express app with a fake task store for the router tests, with the core memory helpers spied on.
- A mocked
useInsightshook and a mockeduseTaskRecommendationshook for the view tests, plus a CSS fixture loader for the layout tier tests. - A mocked dashboard APIApplication programming interface module for the hook tests, including a fake
ApiRequestErrorthat carries a status and a details object. - Browser storage stubs for the model and reasoning-effort persistence tests.
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall persist each insight with an id, a project scope, a title, a body, a category, a status, a fingerprint, provenance, a link to the last run that produced it, and creation and update timestamps. | TC-2, TC-7, TC-11 |
| FR-2MustThe system shall classify each insight with one of the fifteen categories defined by the insight category type, covering quality, performance, architecture, security, reliability, user experience, testability, documentation, dependency, workflow, other, features, competitive analysis, research, and trends. | TC-19, TC-24 |
| FR-3MustThe system shall move an insight through the generated, confirmed, stale, dismissed, and archived states, and shall return an archived insight to the confirmed state when it is unarchived. | TC-17, TC-22 |
| FR-4MustThe system shall deduplicate insights by project and fingerprint, updating the matching row in place and preserving its original id and creation timestamp instead of inserting a second row. | TC-2, TC-41, TC-26 |
| FR-5MustThe system shall track each extraction as a run that records its trigger, status, summary, error, the number of insights created and updated, the input and output metadata snapshots, and the lifecycle fields. | TC-7, TC-8 |
| FR-6MustThe system shall treat a completed, failed, or cancelled run as immutable and shall reject any status change that the run state machine does not allow. | TC-4, TC-5 |
| FR-7MustThe system shall keep an ordered event trail for each run, with a monotonically increasing sequence number, an event type, a message, an optional status and failure classification, and optional metadata. | TC-7, TC-10, TC-30 |
| FR-8MustThe system shall execute a manual run by reading the project working memory, prompting the model with the working memory and the existing insights, parsing the returned insight list, merging the result into the insights memory file, and upserting every insight into the store. | TC-25, TC-26, TC-31 |
| FR-9MustThe system shall classify a run failure as cancelled, timed out, retryable transient, or non-retryable, and shall retry a retryable failure until the configured attempt limit is reached. | TC-9, TC-10, TC-33 |
| FR-10MustThe system shall refuse to start a second run for the same project and trigger while a pending or running run exists, and shall answer that request with a conflict status carrying the active run id. | TC-16, TC-34 |
| FR-11MustThe system shall cancel a pending run immediately, and shall abort the execution of a running run when the operator requests cancellation. | TC-36 |
| FR-12MustThe system shall retry a failed run whose failure class is retryable transient, reusing the model selection, reasoning effort, and input metadata recorded on the original run. | TC-10, TC-18 |
| FR-13MustThe system shall sweep pending and running runs that have no live execution owner after the grace window, and shall mark each recovered run as failed with a non-retryable cause. | TC-35 |
| FR-14MustThe system shall expose HTTPHypertext Transfer Protocol endpoints to list insights, read one insight, update one insight, delete one insight, dismiss one insight, archive one insight, and unarchive one insight. | TC-19, TC-38, TC-39 |
| FR-15MustThe system shall expose HTTPHypertext Transfer Protocol endpoints to trigger a run, list runs, read one run, list the events of one run, cancel one run, and retry one run. | TC-24, TC-30, TC-31 |
| FR-16MustThe system shall return a task payload draft for an insight so the operator can create a board task from it, and shall archive the insight as part of that flow. | TC-20, TC-32 |
| FR-17MustThe system shall present a dashboard insights view that groups insights by category, shows the latest run status, and offers the dismiss, archive, unarchive, and create-task actions on each insight. | TC-19, TC-20, TC-21, TC-22, TC-23 |
| FR-18ShouldThe system shall let the operator select the model and the reasoning effort for a run, and shall record that selection on the run so a retry reproduces it. | TC-15, TC-18 |
| FR-19ShouldThe system shall order insight lists ascending by creation timestamp and then by id, and shall order run lists newest first by creation timestamp and then by id. | TC-12 |
| FR-20ShouldThe system shall let the caller filter the insight list by category, status, and producing run, and shall filter the run list by status and trigger, and shall reject a non-numeric or out-of-range pagination value. | TC-24, TC-39 |
| FR-21ShouldThe system shall expose persisted insights and insight runs to agents through the insight list, insight show, insight run list, and insight run show tools. | TC-24 |
| FR-22ShouldThe system shall recover an orphaned active run when a run request finds an active run with no live execution owner, and shall then start the new run. | TC-34, TC-35 |
| NFR-1MustThe system shall recover every pending or running run that has no live execution owner once it passes the grace window, so a crashed process cannot leave a run active forever. | TC-35 |
| NFR-2MustThe system shall bound each attempt with a timeout and shall abort the model call when the run is cancelled or the timeout elapses. | TC-33, TC-36 |
| NFR-3MustThe system shall compute the insight fingerprint as a deterministic hash of the lowercased and whitespace-collapsed title plus the lowercased category, so the same observation always maps to the same key. | TC-2, TC-41 |
| NFR-4MustThe system shall allow at most one active run per project and trigger, so a project never pays for two concurrent extractions of the same kind. | TC-34 |
| NFR-5MustThe system shall append a durable event for every run creation, status change, attempt, retry, cancellation, and orphan recovery, so an operator can rebuild the history of a run from the event trail alone. | TC-7, TC-30, TC-35 |
| NFR-6ShouldThe system shall run the stale-run sweep at startup, on a fixed interval, and on demand before listing runs, and shall log a sweep failure without failing the surrounding request. | TC-35 |
| NFR-7ShouldThe system shall store the operator's model and reasoning-effort selection on the run input metadata, so a retry uses the same provider and the same effort as the original attempt. | TC-18 |
| NFR-8ShouldThe system shall serve the same feature from the SQLite-backed insight store and the PostgreSQL-backed async insight store through one method surface, so callers behave the same in both backends. | TC-1, TC-8, TC-30 |
| NFR-9ShouldThe system shall run the extraction session with read-only tools and shall keep materialized secret values out of session diagnostics. | TC-25 |
| NFR-10ShouldThe system shall bound the insight list by limit and offset, and the dashboard shall cap its persisted insight cache so a long-lived browser session cannot grow without bound. | TC-14 |
Key Test Files
packages/core/src/__tests__/postgres/insight-store.pg.test.tspackages/core/src/__tests__/postgres/insight-run-execution.pg.test.tspackages/dashboard/app/hooks/__tests__/useInsights.test.tspackages/dashboard/app/components/__tests__/InsightsView.test.tsxpackages/dashboard/app/__tests__/insight-model-selector.test.tsxpackages/dashboard/src/__tests__/mcp-helper-forwarding.test.tspackages/cli/src/__tests__/extension-insights.test.tspackages/core/src/__tests__/memory-insights.test.tspackages/engine/src/__tests__/backlog-pressure-reporter.test.tspackages/engine/src/__tests__/unlinked-missions-advisory-reporter.test.tspackages/dashboard/app/__tests__/lazy-loaded-views-docs.test.tspackages/dashboard/src/__tests__/dashboard-guide.test.ts
requirements
- Should the dashboard insight route accept the four extended categories in its filter and update validation lists, or should the category type be reduced to the eleven values the route accepts.
- The
create-taskendpoint returns a payload draft and leaves the board task creation to the caller, so the endpoint name does not describe what it does. Should it be renamed or should it create the task itself. - The run trigger list includes schedule, task completion, and merge event, and the route accepts all of them, but no scheduler, task completion hook, or merge hook starts a run today, so the manual trigger is the one in use. Should the remaining triggers be wired or removed from the type.
- The insight category type documents features, competitive analysis, research, and trends, and the dashboard renders them, but the model extraction prompt only asks for pattern, principle, convention, pitfall, and context. Should the prompt produce the extended categories too.
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Database & MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backup and Restore
Overview
Fusion keeps its durable state in one PostgreSQL cluster and keeps project and agent memory in files under the project root.
An operator can capture that state on demand or on a schedule, list what has been captured, restore it after a failure or a wrong change, and prune old copies.
A database backup is a set of PostgreSQL logical dumps covering the project, archive, and central schemas plus the migration bookkeeping table, so a restored database can be brought back in line with the code that is running.
A memory backup is a separate snapshot of the project and agent memory directories, captured and restored on its own schedule and its own retention count.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Needs a recoverable copy of the database and of memory before a risky change, and needs to see what is captured and when |
| Fleet maintainer | Needs the automatic backup schedule to run unattended and to report its last outcome |
| Database administrator | Needs a restored database to match the schema the running code expects |
| Maintainer / contributor | Needs the backup, restore, and prune commands to behave predictably from the CLICommand-line interface and the dashboard |
Functional Requirements
Order rows by priority: Must first, then Should, then May.
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall create a database backup that dumps the `project` and `archive` schemas into a `fusion-pg-` dump file, the `central` schema into a `fusion-central-pg-` dump file, and the `public.fusion_schema_migrations` bookkeeping table into a `fusion-migrations-pg-` dump file, where each name ends with the shared timestamp stem and the `.dump` extension | Must | The system shall create a database backup that dumps the project and archive schemas into a fusion-pg- dump file, the central schema into a fusion-central-pg- dump file, and the public.fusion_schema_migrations bookkeeping table into a fusion-migrations-pg- dump file, where each name ends with the shared timestamp stem and the .dump extension |
| FR-2MustThe system shall publish each dump by writing to a private in-progress artifact and renaming it into place only after the dump completed and the stem claim is still owned, so a partial dump is never listed and never restorable | Must | The system shall publish each dump by writing to a private in-progress artifact and renaming it into place only after the dump completed and the stem claim is still owned, so a partial dump is never listed and never restorable |
| FR-3MustThe system shall claim a backup stem exclusively with a per-stem reservation marker so two processes cannot capture the same stem | Must | The system shall claim a backup stem exclusively with a per-stem reservation marker so two processes cannot capture the same stem |
| FR-4MustThe system shall list backup stems newest first, grouping the project, central, and migration files of one stem into a single entry, and shall report a stem whose central or migration file is missing as incomplete instead of presenting it as a full backup | Must | The system shall list backup stems newest first, grouping the project, central, and migration files of one stem into a single entry, and shall report a stem whose central or migration file is missing as incomplete instead of presenting it as a full backup |
| FR-5MustThe system shall restore a selected stem by validating every source archive first, capturing a retained pre-restore stem, and then restoring the project and archive schemas, the central schema, and the migration bookkeeping in that order | Must | The system shall restore a selected stem by validating every source archive first, capturing a retained pre-restore stem, and then restoring the project and archive schemas, the central schema, and the migration bookkeeping in that order |
| FR-6MustThe system shall refuse to restore migration bookkeeping when the pre-restore capture is disabled, because that capture is the rollback source | Must | The system shall refuse to restore migration bookkeeping when the pre-restore capture is disabled, because that capture is the rollback source |
| FR-7MustThe system shall roll back every restore group it already committed from the retained pre-restore stem when a later group or the migration reconciliation fails, and shall report both the original failure and any rollback failure | Must | The system shall roll back every restore group it already committed from the retained pre-restore stem when a later group or the migration reconciliation fails, and shall report both the original failure and any rollback failure |
| FR-8MustThe system shall reconcile `public.fusion_schema_migrations` after a project restore by rewinding the ledger from the earliest missing schema sentinel and replaying the schema baseline, so an older dump cannot skip later schema upgrades | Must | The system shall reconcile public.fusion_schema_migrations after a project restore by rewinding the ledger from the earliest missing schema sentinel and replaying the schema baseline, so an older dump cannot skip later schema upgrades |
| FR-9MustThe system shall treat a selected `fusion-central-pg-*` dump as a central-only restore that leaves the migration bookkeeping untouched, and shall reject contradictory restore options | Must | The system shall treat a selected fusion-central-pg-* dump as a central-only restore that leaves the migration bookkeeping untouched, and shall reject contradictory restore options |
| FR-10MustThe system shall delete backups beyond the configured retention count, oldest first, and shall never delete a pre-restore stem or a stem that holds a live reservation | Must | The system shall delete backups beyond the configured retention count, oldest first, and shall never delete a pre-restore stem or a stem that holds a live reservation |
| FR-11MustThe system shall provide the `fn backup --create`, `fn backup --list`, `fn backup --restore` with a file argument, and `fn backup --cleanup` commands | Must | The system shall provide the fn backup --create, fn backup --list, fn backup --restore with a file argument, and fn backup --cleanup commands |
| FR-12MustThe system shall run an automatic database backup on a cron expression as a global routine named "Database Backup" that runs `fn backup --create` | Must | The system shall run an automatic database backup on a cron expression as a global routine named "Database Backup" that runs fn backup --create |
| FR-13MustThe system shall expose the database backup inventory at `GET /api/backups` and an immediate backup creation at `POST /api/backups`, and shall show the inventory together with the schedule evidence in the global Database Backups settings section | Must | The system shall expose the database backup inventory at GET /api/backups and an immediate backup creation at POST /api/backups, and shall show the inventory together with the schedule evidence in the global Database Backups settings section |
| FR-14MustThe system shall create a memory backup that snapshots the project memory directory `.fusion/memory` and the agent memory directory `.fusion/agent-memory` into a timestamped directory, honoring the configured scope | Must | The system shall create a memory backup that snapshots the project memory directory .fusion/memory and the agent memory directory .fusion/agent-memory into a timestamped directory, honoring the configured scope |
| FR-15MustThe system shall list memory backups with their scope, file count, size, and creation time, and shall delete memory backups beyond the configured retention count, oldest first | Must | The system shall list memory backups with their scope, file count, size, and creation time, and shall delete memory backups beyond the configured retention count, oldest first |
| FR-16MustThe system shall restore memory from a snapshot directory, and shall refuse to overwrite an existing memory file whose content differs from the snapshot unless the caller asks for overwrite | Must | The system shall restore memory from a snapshot directory, and shall refuse to overwrite an existing memory file whose content differs from the snapshot unless the caller asks for overwrite |
| FR-17MustThe system shall provide the `fn memory-backup --create` command with an optional `--scope` argument of `project`, `agents`, or `all`, plus the `fn memory-backup --list` command and the `fn memory-backup --restore` command with a directory argument | Must | The system shall provide the fn memory-backup --create command with an optional --scope argument of project, agents, or all, plus the fn memory-backup --list command and the fn memory-backup --restore command with a directory argument |
| FR-18MustThe system shall run an automatic memory backup on a cron expression as a project routine named "MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backup" that runs `fn memory-backup --create` | Must | The system shall run an automatic memory backup on a cron expression as a project routine named "MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backup" that runs fn memory-backup --create |
| FR-19MustThe system shall store the database backup policy (`autoBackupEnabled`, `autoBackupSchedule`, `autoBackupRetention`, `autoBackupDir`) in global settings, and the memory backup policy (`memoryBackupEnabled`, `memoryBackupSchedule`, `memoryBackupRetention`, `memoryBackupDir`, `memoryBackupScope`) in project settings | Must | The system shall store the database backup policy (autoBackupEnabled, autoBackupSchedule, autoBackupRetention, autoBackupDir) in global settings, and the memory backup policy (memoryBackupEnabled, memoryBackupSchedule, memoryBackupRetention, memoryBackupDir, memoryBackupScope) in project settings |
| FR-20MustThe system shall migrate the database backup settings from project scope to global scope once, adopting a single configured value, keeping any existing global value, and recording a conflict for the operator to resolve when projects disagree | Must | The system shall migrate the database backup settings from project scope to global scope once, adopting a single configured value, keeping any existing global value, and recording a conflict for the operator to resolve when projects disagree |
| FR-21ShouldThe system shall run the automatic backup inside the engine process when the scheduled command is the canonical `fn backup --create` or `fn memory-backup --create` form, and shall decline that interception when the command embeds a shell continuation, redirection, or substitution | Should | The system shall run the automatic backup inside the engine process when the scheduled command is the canonical fn backup --create or fn memory-backup --create form, and shall decline that interception when the command embeds a shell continuation, redirection, or substitution |
| FR-22ShouldThe system shall sweep abandoned in-progress artifacts and their reservation markers, and shall not sweep a live claim | Should | The system shall sweep abandoned in-progress artifacts and their reservation markers, and shall not sweep a live claim |
| FR-23ShouldThe system shall keep the next-run time of an existing backup routine when the desired routine fields are unchanged, so a settings save does not postpone a due backup | Should | The system shall keep the next-run time of an existing backup routine when the desired routine fields are unchanged, so a settings save does not postpone a due backup |
Non-Functional Requirements
Order rows by priority: Must first, then Should, then May.
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustThe system shall pass PostgreSQL connection components to `pg_dump` and `pg_restore` only through the libpq `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, and `PGDATABASE` environment variables, never as process arguments, and shall redact the connection-string password from any client error message | Must | Security | The system shall pass PostgreSQL connection components to pg_dump and pg_restore only through the libpq PGHOST, PGPORT, PGUSER, PGPASSWORD, and PGDATABASE environment variables, never as process arguments, and shall redact the connection-string password from any client error message |
| NFR-2MustThe system shall validate every source dump with `pg_restore --list` before any destructive restore, so a corrupt archive is refused before the target schemas are touched | Must | Data integrity | The system shall validate every source dump with pg_restore --list before any destructive restore, so a corrupt archive is refused before the target schemas are touched |
| NFR-3MustThe system shall run each restore in a single transaction, so a failed restore does not leave the target schemas half replaced | Must | Data integrity | The system shall run each restore in a single transaction, so a failed restore does not leave the target schemas half replaced |
| NFR-4MustThe system shall bound every `pg_dump` and `pg_restore` invocation with a client timeout of 120 seconds by default, so a hung native client cannot block the caller | Must | Availability | The system shall bound every pg_dump and pg_restore invocation with a client timeout of 120 seconds by default, so a hung native client cannot block the caller |
| NFR-5MustThe system shall apply the ledger rewind and the baseline replay in one transaction, so a failed replay cannot leave a rewound ledger against restored schemas | Must | Data integrity | The system shall apply the ledger rewind and the baseline replay in one transaction, so a failed replay cannot leave a rewound ledger against restored schemas |
| NFR-6MustThe system shall reject a backup directory that is absolute, that contains a parent-directory segment, or that starts with a drive letter, for both the database and the memory backup directory | Must | Security | The system shall reject a backup directory that is absolute, that contains a parent-directory segment, or that starts with a drive letter, for both the database and the memory backup directory |
| NFR-7MustThe system shall require certificate verification when reconciling migrations against a remote PostgreSQL host, and shall keep TLS off for loopback and embedded clusters that have no TLS | Must | Security | The system shall require certificate verification when reconciling migrations against a remote PostgreSQL host, and shall keep TLS off for loopback and embedded clusters that have no TLS |
| NFR-8MustThe system shall report the schedule evidence (enabled state, cron expression, next run, last run, last outcome, run count) alongside the backup inventory, so an empty inventory cannot hide a schedule failure | Must | Operability | The system shall report the schedule evidence (enabled state, cron expression, next run, last run, last outcome, run count) alongside the backup inventory, so an empty inventory cannot hide a schedule failure |
| NFR-9MustThe system shall order its `pg_dump` and `pg_restore` install-location search with the server major version, which is 15 for the embedded cluster, ahead of the later major versions, to avoid dump-format incompatibility | Must | Compatibility | The system shall order its pg_dump and pg_restore install-location search with the server major version, which is 15 for the embedded cluster, ahead of the later major versions, to avoid dump-format incompatibility |
| NFR-10ShouldThe system shall resolve `pg_dump` and `pg_restore` from `PATH` first and then from common install locations, and shall surface a missing binary as a named native client failure | Should | Operability | The system shall resolve pg_dump and pg_restore from PATH first and then from common install locations, and shall surface a missing binary as a named native client failure |
| NFR-11ShouldThe system shall keep a legacy two-member backup stem restorable, shall report its migration bookkeeping as unavailable, and shall still rewind and replay the ledger for it | Should | Compatibility | The system shall keep a legacy two-member backup stem restorable, shall report its migration bookkeeping as unavailable, and shall still rewind and replay the ledger for it |
| NFR-12ShouldThe system shall record the run count, the last run time, and the last run outcome of the backup routine, so an operator can see whether the schedule works | Should | Observability | The system shall record the run count, the last run time, and the last run outcome of the backup routine, so an operator can see whether the schedule works |
| NFR-13ShouldThe system shall warn the operator when automatic backups are enabled but no routine is registered, naming the two actions that reconcile it | Should | Operability | The system shall warn the operator when automatic backups are enabled but no routine is registered, naming the two actions that reconcile it |
| NFR-14ShouldThe system shall write each restored memory file to a temporary file and rename it into place, so a failed restore does not leave a truncated memory file | Should | Data integrity | The system shall write each restored memory file to a temporary file and rename it into place, so a failed restore does not leave a truncated memory file |
Constraints
- Restore dumps are local recovery artifacts and must never be committed to git. The
.gitignorepatternsfusion-pg-*.dumpandfusion-pg-*.sqlguard that naming pattern (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):RecoveryArtifacts). pg_dumpandpg_restoreare not bundled withembedded-postgres, which ships onlyinitdb,pg_ctl, and the server binary. The operator must install the PostgreSQL client tools or configure the binary paths.- The native backup commands take no cross-process lock and do not quiesce other writers. The operator must stop other Fusion writers and competing backup commands before a list, create, cleanup, or especially a restore.
- The database backup directory setting is relative to the global Fusion directory, and the memory backup directory setting is relative to the project root.
- The database backup policy is global because one PostgreSQL cluster holds every project. The memory backup policy stays project-scoped because the memory files are project-owned.
- A restore replaces the contents of the target schemas. It is destructive by design.
- The
fn backupandfn memory-backupcommands are operator surfaces. Agents have no backup or restore tool.
Acceptance Criteria
Every FR and NFR shall have at least one acceptance criterion.
Order criteria by FRs first (sorted by ID), then NFRs (sorted by ID).
-
FR-1MustThe system shall create a database backup that dumps the `project` and `archive` schemas into a `fusion-pg-` dump file, the `central` schema into a `fusion-central-pg-` dump file, and the `public.fusion_schema_migrations` bookkeeping table into a `fusion-migrations-pg-` dump file, where each name ends with the shared timestamp stem and the `.dump` extension
gherkin @FR-1MustThe system shall create a database backup that dumps the `project` and `archive` schemas into a `fusion-pg-` dump file, the `central` schema into a `fusion-central-pg-` dump file, and the `public.fusion_schema_migrations` bookkeeping table into a `fusion-migrations-pg-` dump file, where each name ends with the shared timestamp stem and the `.dump` extension Scenario: Create a database backup Given a running Fusion PostgreSQL cluster When the operator runs "fn backup --create" Then a "fusion-pg-" dump file holds the project and archive schemas And a "fusion-central-pg-" dump file holds the central schema And a "fusion-migrations-pg-" dump file holds public.fusion_schema_migrations And all three file names end with the same timestamp stem -
FR-2MustThe system shall publish each dump by writing to a private in-progress artifact and renaming it into place only after the dump completed and the stem claim is still owned, so a partial dump is never listed and never restorable
gherkin @FR-2MustThe system shall publish each dump by writing to a private in-progress artifact and renaming it into place only after the dump completed and the stem claim is still owned, so a partial dump is never listed and never restorable Scenario: Partial dump is never published Given a dump that fails midway When the backup runs Then no final dump file exists for that stem And the listing does not offer the stem -
FR-3MustThe system shall claim a backup stem exclusively with a per-stem reservation marker so two processes cannot capture the same stem
gherkin @FR-3MustThe system shall claim a backup stem exclusively with a per-stem reservation marker so two processes cannot capture the same stem Scenario: Two processes claim one stem Given two processes start a backup in the same second When both allocate a stem Then only one of them owns the stem And the other uses the next counter value -
FR-4MustThe system shall list backup stems newest first, grouping the project, central, and migration files of one stem into a single entry, and shall report a stem whose central or migration file is missing as incomplete instead of presenting it as a full backup
gherkin @FR-4MustThe system shall list backup stems newest first, grouping the project, central, and migration files of one stem into a single entry, and shall report a stem whose central or migration file is missing as incomplete instead of presenting it as a full backup Scenario: List stems newest first Given three stored backup stems When the operator runs "fn backup --list" Then the newest stem is listed first And one stem with a missing central file is shown as incomplete -
FR-5MustThe system shall restore a selected stem by validating every source archive first, capturing a retained pre-restore stem, and then restoring the project and archive schemas, the central schema, and the migration bookkeeping in that order
gherkin @FR-5MustThe system shall restore a selected stem by validating every source archive first, capturing a retained pre-restore stem, and then restoring the project and archive schemas, the central schema, and the migration bookkeeping in that order Scenario: Restore a project stem Given a stored project stem When the operator runs "fn backup --restore" with a dump file name Then every source archive is validated first And a pre-restore stem is retained And the project and archive schemas are restored And the central schema is restored And the migration bookkeeping is restored -
FR-6MustThe system shall refuse to restore migration bookkeeping when the pre-restore capture is disabled, because that capture is the rollback source
gherkin @FR-6MustThe system shall refuse to restore migration bookkeeping when the pre-restore capture is disabled, because that capture is the rollback source Scenario: Bookkeeping restore without a rollback source Given a caller that disables the pre-restore capture When the caller restores a stem that contains migration bookkeeping Then the request is refused And no dump client is invoked -
FR-7MustThe system shall roll back every restore group it already committed from the retained pre-restore stem when a later group or the migration reconciliation fails, and shall report both the original failure and any rollback failure
gherkin @FR-7MustThe system shall roll back every restore group it already committed from the retained pre-restore stem when a later group or the migration reconciliation fails, and shall report both the original failure and any rollback failure Scenario: Central restore fails after the project restore committed Given a stem that restores the project schemas and then fails on central When the restore runs Then the project and archive schemas are rolled back from the retained pre-restore stem And the failure names the retained dumps -
FR-8MustThe system shall reconcile `public.fusion_schema_migrations` after a project restore by rewinding the ledger from the earliest missing schema sentinel and replaying the schema baseline, so an older dump cannot skip later schema upgrades
gherkin @FR-8MustThe system shall reconcile `public.fusion_schema_migrations` after a project restore by rewinding the ledger from the earliest missing schema sentinel and replaying the schema baseline, so an older dump cannot skip later schema upgrades Scenario: Restore an older dump Given a restored schema that is missing a relation the ledger claims When the reconciliation runs Then the ledger is rewound from the earliest missing sentinel And the schema baseline is replayed -
FR-9MustThe system shall treat a selected `fusion-central-pg-*` dump as a central-only restore that leaves the migration bookkeeping untouched, and shall reject contradictory restore options
gherkin @FR-9MustThe system shall treat a selected `fusion-central-pg-*` dump as a central-only restore that leaves the migration bookkeeping untouched, and shall reject contradictory restore options Scenario: Central-only restore Given a stored "fusion-central-pg-" dump file When the operator restores it Then only the central schema is restored And the migration bookkeeping is left unchanged -
FR-10MustThe system shall delete backups beyond the configured retention count, oldest first, and shall never delete a pre-restore stem or a stem that holds a live reservation
gherkin @FR-10MustThe system shall delete backups beyond the configured retention count, oldest first, and shall never delete a pre-restore stem or a stem that holds a live reservation Scenario: Retention prunes the oldest stems Given a retention count of 2 and four stored stems When the cleanup runs Then the two oldest stems are deleted And every file of a pruned stem is deleted And a pre-restore stem is kept -
FR-11MustThe system shall provide the `fn backup --create`, `fn backup --list`, `fn backup --restore` with a file argument, and `fn backup --cleanup` commands
gherkin @FR-11MustThe system shall provide the `fn backup --create`, `fn backup --list`, `fn backup --restore` with a file argument, and `fn backup --cleanup` commands Scenario: Backup command surface Given the "fn" CLICommand-line interface When the operator runs "fn backup" with no flag Then the command prints the usage line and exits with status 1 -
FR-12MustThe system shall run an automatic database backup on a cron expression as a global routine named "Database Backup" that runs `fn backup --create`
gherkin @FR-12MustThe system shall run an automatic database backup on a cron expression as a global routine named "Database Backup" that runs `fn backup --create` Scenario: Automatic database backup Given automatic database backups are enabled with a valid cron expression When the settings are saved Then a global routine named "Database Backup" runs "fn backup --create" on that cron expression -
FR-13MustThe system shall expose the database backup inventory at `GET /api/backups` and an immediate backup creation at `POST /api/backups`, and shall show the inventory together with the schedule evidence in the global Database Backups settings section
gherkin @FR-13MustThe system shall expose the database backup inventory at `GET /api/backups` and an immediate backup creation at `POST /api/backups`, and shall show the inventory together with the schedule evidence in the global Database Backups settings section Scenario: Dashboard backup inventory Given the dashboard APIApplication programming interface is serving When the operator opens the Database Backups settings section Then "GET /api/backups" returns the stored dumps with the schedule evidence And "POST /api/backups" creates a backup immediately -
FR-14MustThe system shall create a memory backup that snapshots the project memory directory `.fusion/memory` and the agent memory directory `.fusion/agent-memory` into a timestamped directory, honoring the configured scope
gherkin @FR-14MustThe system shall create a memory backup that snapshots the project memory directory `.fusion/memory` and the agent memory directory `.fusion/agent-memory` into a timestamped directory, honoring the configured scope Scenario: Create a memory backup Given a project with memory files and agent memory files When the operator runs "fn memory-backup --create" Then a timestamped snapshot directory holds a copy of ".fusion/memory" and a copy of ".fusion/agent-memory" -
FR-15MustThe system shall list memory backups with their scope, file count, size, and creation time, and shall delete memory backups beyond the configured retention count, oldest first
gherkin @FR-15MustThe system shall list memory backups with their scope, file count, size, and creation time, and shall delete memory backups beyond the configured retention count, oldest first Scenario: List and prune memory backups Given a memory retention count of 1 and three stored snapshots When a new snapshot is created Then the listing shows the scope, file count, size, and creation time And the two oldest snapshots are deleted -
FR-16MustThe system shall restore memory from a snapshot directory, and shall refuse to overwrite an existing memory file whose content differs from the snapshot unless the caller asks for overwrite
gherkin @FR-16MustThe system shall restore memory from a snapshot directory, and shall refuse to overwrite an existing memory file whose content differs from the snapshot unless the caller asks for overwrite Scenario: Restore memory that would overwrite a changed file Given a memory file that differs from the snapshot When a restore runs without overwrite Then the restore is refused and names the file -
FR-17MustThe system shall provide the `fn memory-backup --create` command with an optional `--scope` argument of `project`, `agents`, or `all`, plus the `fn memory-backup --list` command and the `fn memory-backup --restore` command with a directory argument
gherkin @FR-17MustThe system shall provide the `fn memory-backup --create` command with an optional `--scope` argument of `project`, `agents`, or `all`, plus the `fn memory-backup --list` command and the `fn memory-backup --restore` command with a directory argument Scenario: MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) backup command surface Given the "fn" CLICommand-line interface When the operator runs "fn memory-backup --create --scope agents" Then only the agent memory directory is snapshotted -
FR-18MustThe system shall run an automatic memory backup on a cron expression as a project routine named "MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backup" that runs `fn memory-backup --create`
gherkin @FR-18MustThe system shall run an automatic memory backup on a cron expression as a project routine named "MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backup" that runs `fn memory-backup --create` Scenario: Automatic memory backup Given automatic memory backups are enabled with a valid cron expression When the settings are saved Then a project routine named "MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backup" runs "fn memory-backup --create" on that cron expression -
FR-19MustThe system shall store the database backup policy (`autoBackupEnabled`, `autoBackupSchedule`, `autoBackupRetention`, `autoBackupDir`) in global settings, and the memory backup policy (`memoryBackupEnabled`, `memoryBackupSchedule`, `memoryBackupRetention`, `memoryBackupDir`, `memoryBackupScope`) in project settings
gherkin @FR-19MustThe system shall store the database backup policy (`autoBackupEnabled`, `autoBackupSchedule`, `autoBackupRetention`, `autoBackupDir`) in global settings, and the memory backup policy (`memoryBackupEnabled`, `memoryBackupSchedule`, `memoryBackupRetention`, `memoryBackupDir`, `memoryBackupScope`) in project settings Scenario: Settings scope Given a project and a global configuration When the operator writes the backup settings Then the database backup policy is stored globally And the memory backup policy is stored on the project -
FR-20MustThe system shall migrate the database backup settings from project scope to global scope once, adopting a single configured value, keeping any existing global value, and recording a conflict for the operator to resolve when projects disagree
gherkin @FR-20MustThe system shall migrate the database backup settings from project scope to global scope once, adopting a single configured value, keeping any existing global value, and recording a conflict for the operator to resolve when projects disagree Scenario: Migrate the database backup settings once Given two projects with different backup settings and no global value When the migration runs Then the global value is adopted from the single configured project value And the conflict is recorded for the operator to resolve And a second run changes nothing -
FR-21ShouldThe system shall run the automatic backup inside the engine process when the scheduled command is the canonical `fn backup --create` or `fn memory-backup --create` form, and shall decline that interception when the command embeds a shell continuation, redirection, or substitution
gherkin @FR-21ShouldThe system shall run the automatic backup inside the engine process when the scheduled command is the canonical `fn backup --create` or `fn memory-backup --create` form, and shall decline that interception when the command embeds a shell continuation, redirection, or substitution Scenario: Scheduled backup runs in-process Given a scheduled command of "fn backup --create" When the cron runner executes it Then the backup runs inside the engine process And a command of "fn backup --create && notify-send done" is not intercepted -
FR-22ShouldThe system shall sweep abandoned in-progress artifacts and their reservation markers, and shall not sweep a live claim
gherkin @FR-22ShouldThe system shall sweep abandoned in-progress artifacts and their reservation markers, and shall not sweep a live claim Scenario: Sweep abandoned artifacts Given an abandoned reservation marker and a partial dump When the cleanup runs Then the marker and the partial dump are removed And a live reservation marker is kept -
FR-23ShouldThe system shall keep the next-run time of an existing backup routine when the desired routine fields are unchanged, so a settings save does not postpone a due backup
gherkin @FR-23ShouldThe system shall keep the next-run time of an existing backup routine when the desired routine fields are unchanged, so a settings save does not postpone a due backup Scenario: Save unchanged backup settings Given a registered backup routine with a next-run time When the operator saves the same backup settings Then the routine keeps its next-run time -
NFR-1MustThe system shall pass PostgreSQL connection components to `pg_dump` and `pg_restore` only through the libpq `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, and `PGDATABASE` environment variables, never as process arguments, and shall redact the connection-string password from any client error message
gherkin @NFR-1MustThe system shall pass PostgreSQL connection components to `pg_dump` and `pg_restore` only through the libpq `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, and `PGDATABASE` environment variables, never as process arguments, and shall redact the connection-string password from any client error message Scenario: Credentials stay out of the process list Given a PostgreSQL connection string with a password When a dump runs Then the password is passed only through the PGPASSWORD environment variable And it appears in no process argument And it is absent from the error message when the client fails -
NFR-2MustThe system shall validate every source dump with `pg_restore --list` before any destructive restore, so a corrupt archive is refused before the target schemas are touched
gherkin @NFR-2MustThe system shall validate every source dump with `pg_restore --list` before any destructive restore, so a corrupt archive is refused before the target schemas are touched Scenario: Corrupt archive is refused before the restore Given a corrupt source dump When a restore runs Then the archive listing fails And no restore command is issued against the target schemas -
NFR-3MustThe system shall run each restore in a single transaction, so a failed restore does not leave the target schemas half replaced
gherkin @NFR-3MustThe system shall run each restore in a single transaction, so a failed restore does not leave the target schemas half replaced Scenario: Restore runs as one transaction Given a valid source dump When the restore runs Then the restore client is called with a single-transaction flag -
NFR-4MustThe system shall bound every `pg_dump` and `pg_restore` invocation with a client timeout of 120 seconds by default, so a hung native client cannot block the caller
gherkin @NFR-4MustThe system shall bound every `pg_dump` and `pg_restore` invocation with a client timeout of 120 seconds by default, so a hung native client cannot block the caller Scenario: Native client timeout Given a native client that never settles When a dump is requested Then the call is abandoned at the client timeout -
NFR-5MustThe system shall apply the ledger rewind and the baseline replay in one transaction, so a failed replay cannot leave a rewound ledger against restored schemas
gherkin @NFR-5MustThe system shall apply the ledger rewind and the baseline replay in one transaction, so a failed replay cannot leave a rewound ledger against restored schemas Scenario: Baseline replay fails after the rewind Given a schema baseline that fails to apply When the reconciliation runs Then the ledger keeps its original versions -
NFR-6MustThe system shall reject a backup directory that is absolute, that contains a parent-directory segment, or that starts with a drive letter, for both the database and the memory backup directory
gherkin @NFR-6MustThe system shall reject a backup directory that is absolute, that contains a parent-directory segment, or that starts with a drive letter, for both the database and the memory backup directory Scenario: Reject an unsafe backup directory Given a backup directory of "../escape" When the backup settings are applied Then the directory is rejected -
NFR-7MustThe system shall require certificate verification when reconciling migrations against a remote PostgreSQL host, and shall keep TLS off for loopback and embedded clusters that have no TLS
gherkin @NFR-7MustThe system shall require certificate verification when reconciling migrations against a remote PostgreSQL host, and shall keep TLS off for loopback and embedded clusters that have no TLS Scenario: TLS policy for migration reconciliation Given a connection string for a loopback host And a connection string for a remote host When the reconciliation connection is built Then the loopback connection has TLS off And the remote connection requires certificate verification -
NFR-8MustThe system shall report the schedule evidence (enabled state, cron expression, next run, last run, last outcome, run count) alongside the backup inventory, so an empty inventory cannot hide a schedule failure
gherkin @NFR-8MustThe system shall report the schedule evidence (enabled state, cron expression, next run, last run, last outcome, run count) alongside the backup inventory, so an empty inventory cannot hide a schedule failure Scenario: Listing fails but schedule evidence survives Given the backup listing fails When "GET /api/backups" runs Then the response still carries the schedule evidence And it carries the listing error -
NFR-9MustThe system shall order its `pg_dump` and `pg_restore` install-location search with the server major version, which is 15 for the embedded cluster, ahead of the later major versions, to avoid dump-format incompatibility
gherkin @NFR-9MustThe system shall order its `pg_dump` and `pg_restore` install-location search with the server major version, which is 15 for the embedded cluster, ahead of the later major versions, to avoid dump-format incompatibility Scenario: Client binary search order Given the dump client is not on PATH When the client binary is resolved Then the install location for major version 15 is searched before the locations for major versions 16 and 17 -
NFR-10ShouldThe system shall resolve `pg_dump` and `pg_restore` from `PATH` first and then from common install locations, and shall surface a missing binary as a named native client failure
gherkin @NFR-10ShouldThe system shall resolve `pg_dump` and `pg_restore` from `PATH` first and then from common install locations, and shall surface a missing binary as a named native client failure Scenario: Client binary is missing Given no "pg_dump" binary is on PATH or in a known install location When a backup runs Then the backup fails and the error names the pg_dump spawn failure -
NFR-11ShouldThe system shall keep a legacy two-member backup stem restorable, shall report its migration bookkeeping as unavailable, and shall still rewind and replay the ledger for it
gherkin @NFR-11ShouldThe system shall keep a legacy two-member backup stem restorable, shall report its migration bookkeeping as unavailable, and shall still rewind and replay the ledger for it Scenario: Restore a legacy two-member stem Given a stored stem with a project dump and a central dump and no bookkeeping dump When the operator restores the project dump Then the restore succeeds And the bookkeeping is reported as unavailable And the ledger is still rewound and replayed -
NFR-12ShouldThe system shall record the run count, the last run time, and the last run outcome of the backup routine, so an operator can see whether the schedule works
gherkin @NFR-12ShouldThe system shall record the run count, the last run time, and the last run outcome of the backup routine, so an operator can see whether the schedule works Scenario: Schedule evidence carries the last outcome Given a backup routine that has run When the schedule status is built Then it carries the run count, the last run time, and the last outcome -
NFR-13ShouldThe system shall warn the operator when automatic backups are enabled but no routine is registered, naming the two actions that reconcile it
gherkin @NFR-13ShouldThe system shall warn the operator when automatic backups are enabled but no routine is registered, naming the two actions that reconcile it Scenario: Enabled policy with no registered routine Given automatic backups are enabled and no routine is registered When the Database Backups settings section renders Then a warning names restarting Fusion and saving the settings again -
NFR-14ShouldThe system shall write each restored memory file to a temporary file and rename it into place, so a failed restore does not leave a truncated memory file
gherkin @NFR-14ShouldThe system shall write each restored memory file to a temporary file and rename it into place, so a failed restore does not leave a truncated memory file Scenario: MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) restore writes through a temporary file Given a memory snapshot to restore When the restore runs Then each file is written to a temporary path and renamed into place
Conflicts
None identified yet.
Open Questions
- The dashboard inventory lists one row per dump file, so a complete three-file stem appears as three rows. Should the inventory group by stem instead?
- The CLICommand-line interface has no flag to restore the project schemas without also restoring the central schema. Is a project-only restore a required operator action?
- Pre-restore stems are retained indefinitely and the retention count never prunes them. What is the intended way to reclaim that disk space once a restore is confirmed?
- The CLICommand-line interface always restores memory with overwrite enabled, so the library guard against overwriting a changed memory file is unreachable from the operator surface. Should the CLICommand-line interface expose that choice?
Specification: Database & MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backup and Restore
Overview
Database backup and restore live in @fusion/core. BackupManager owns the operator-facing contract and delegates every dump and restore to PgBackupManager, which shells out to pg_dump and pg_restore with the connection components passed through libpq environment variables. A backup is a stem of up to three dump files: the project and archive schemas, the central schema, and the public.fusion_schema_migrations bookkeeping table. A restore validates the sources, captures a retained pre-restore stem, restores the groups in order, and then reconciles the migration ledger so the restored schema matches the running code. MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) backup and restore are a separate concern: MemoryBackupManager copies the project and agent memory directories into timestamped snapshot directories and restores them file by file. The operator reaches both through the fn backup and fn memory-backup commands, the dashboard settings sections, and two dashboard APIApplication programming interface routes.
Architecture
┌───────────────────────────────────────────────────────────────┐
│ Operator surfaces │
│ │
│ fn backup --create|--list|--restore|--cleanup │
│ fn memory-backup --create|--list|--restore │
│ Settings > Database Backups (global) │
│ Settings > MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backups (project) │
│ GET /api/backups POST /api/backups │
└───────────────────────────┬───────────────────────────────────┘
│
┌───────────────────────────▼───────────────────────────────────┐
│ @fusion/core │
│ │
│ backup/backup.ts BackupManager │
│ backup/backup-settings-migration.ts settings migration │
│ postgres/pg-backup.ts PgBackupManager │
│ postgres/restore-migration-reconcile.ts ledger reconcile │
│ memory/memory-backup.ts MemoryBackupManager │
│ automation/global-routine-store.ts "Database Backup" │
│ automation/routine-store.ts "MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backup" │
└──────┬────────────────────────────────┬────────────────────────┘
│ │
pg_dump / pg_restore filesystem copy / rename
(libpq PG* env vars) (.fusion/memory, .fusion/agent-memory)
│ │
┌────────────────────▼──────────────────┐ ┌──────────▼─────────────────────┐
│ PostgreSQL cluster │ │ ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree memory files │
│ schema project (dump 1) │ │ Agent memory files │
│ schema archive (dump 1) │ │ Snapshot directories │
│ schema central (dump 2) │ └────────────────────────────────┘
│ public.fusion_schema_migrations │
│ (dump 3) │
└────────────────────────────────────────┘
Engine cron runner
(packages/engine/src/scheduling/cron-runner.ts)
"fn backup --create" -> runBackupCommand in-process
"fn memory-backup --create" -> runMemoryBackupCommand in-process
Data Models
Backup stem (PgBackupPair)
| Field | Type | Constraints | Description |
|---|---|---|---|
| timestamp | string | not null, YYYYMMDD-HHMMSS with an optional -N counter, prefixed pre-restore- for a pre-restore stem |
Stem shared by the project, central, and migration dump files of one backup |
| project | PgDumpResult | optional | Dump of the project and archive schemas |
| central | PgDumpResult or { skipped: "disabled" \| "missing" } |
optional | Dump of the central schema, or the reason it was skipped |
| migrations | PgDumpResult or { skipped: "missing" } |
optional | Dump of public.fusion_schema_migrations, or the reason it is absent |
Dump file (PgDumpResult)
| Field | Type | Constraints | Description |
|---|---|---|---|
| filename | string | not null, matches fusion- plus an optional central- or migrations-, plus an optional pre-restore-, plus pg-, plus the stem, plus .dump |
Published file name |
| path | string | not null | Absolute path of the published file |
| sizeBytes | number | not null, 0 or greater | File size in bytes |
| createdAt | string | not null, ISO 8601 | Publication time |
Backup selection (PgBackupSelection)
| Field | Type | Constraints | Description |
|---|---|---|---|
| family | string | not null, regular or pre-restore |
Which family the selected file belongs to |
| stem | string | not null | Shared stem of the selected file |
| selectedKind | string | not null, project or central |
Which file the operator selected |
| selectedPath | string | not null | Resolved path of the selected file |
| projectPath | string | not null | Sibling project dump path |
| centralPath | string | not null | Sibling central dump path |
| migrationsPath | string | not null | Sibling migration bookkeeping dump path |
Restore result (BackupRestoreResult)
| Field | Type | Constraints | Description |
|---|---|---|---|
| restored | array of project and central |
not null | Groups that were restored |
| preRestoreBackup | BackupPairInfo | optional | The retained rollback stem |
| projectRollback | string | optional, succeeded |
ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree rollback outcome |
| centralRollback | string | optional, succeeded |
Central rollback outcome |
| migrationBookkeepingRollback | string | optional, succeeded |
Bookkeeping rollback outcome |
| migrationBookkeeping | string | not null, restored, unavailable, or skipped-central-only |
Bookkeeping outcome |
MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) snapshot (MemoryBackupInfo)
| Field | Type | Constraints | Description |
|---|---|---|---|
| filename | string | not null, matches memory-YYYY-MM-DD-HHMMSS with an optional -N counter |
Snapshot directory name |
| createdAt | string | not null, ISO 8601 | Snapshot creation time |
| size | number | not null, 0 or greater | Total bytes of the snapshot files |
| path | string | not null | Absolute path of the snapshot directory |
| scope | string | not null, project, agents, or all |
Which memory roots the snapshot holds |
| entryCount | number | not null, 0 or greater | Number of files in the snapshot |
Schedule status (BackupScheduleStatus)
| Field | Type | Constraints | Description |
|---|---|---|---|
| enabled | boolean | not null | Whether automatic backups are turned on |
| cronExpression | string | not null, defaults to 0 2 * * * |
The configured cron expression |
| routineRegistered | boolean | not null | Whether the backup routine exists |
| nextRunAt | string | optional | Next scheduled run time |
| lastRunAt | string | optional | Last run time |
| lastRunSucceeded | boolean | optional | Outcome of the last run |
| lastRunOutput | string | optional, truncated to 500 characters | Output of the last run |
| runCount | number | optional | How many times the routine has run |
Database backup settings (global)
| Field | Type | Constraints | Description |
|---|---|---|---|
| autoBackupEnabled | boolean | not null, default false |
Turns on the scheduled database backup |
| autoBackupSchedule | string | not null, default 0 2 * * * |
Cron expression for the database backup |
| autoBackupRetention | number | not null, default 7, 1 to 100 |
Number of backup stems to keep |
| autoBackupDir | string | not null, default .fusion/backups, relative to the global Fusion directory |
Where the dump files are written |
MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) backup settings (project)
| Field | Type | Constraints | Description |
|---|---|---|---|
| memoryBackupEnabled | boolean | not null, default false |
Turns on the scheduled memory backup |
| memoryBackupSchedule | string | not null, default 0 3 * * * |
Cron expression for the memory backup |
| memoryBackupRetention | number | not null, default 14, 1 to 100 |
Number of memory snapshots to keep |
| memoryBackupDir | string | not null, default .fusion/backups/memory, relative to the project root |
Where the snapshot directories are written |
| memoryBackupScope | string | not null, default all, one of project, agents, all |
Which memory roots a snapshot holds |
Migration rewind sentinel (RestoredSchemaRelationSentinel)
| Field | Type | Constraints | Description |
|---|---|---|---|
| version | string | not null | Migration version this sentinel guards |
| relations | string list | optional | Relations that must exist at that version |
| columns | relation and column pairs | optional | Columns that must exist at that version |
| primaryKeys | relation and ordered column list | optional | Primary key column list that must match, compared in order |
| columnTypes | relation, column, and data type | optional | ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column data type that must match |
| triggers | relation and trigger name | optional | Trigger that must exist |
| policies | relation and policy name | optional | Row-level security policy that must exist |
| indexes | relation and index name | optional | Index that must exist |
| absentColumns | relation and column pairs | optional | ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column that must not exist |
| forcedRowLevelSecurity | string list | optional | Relations that must have row-level security forced |
APIApplication programming interface Contracts
The normative contract is in api.yaml (OpenAPI 3.1).
The table below is a summary; request and response schemas, error response bodies, and auth requirements are in api.yaml.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/backups | List the stored database backup dumps and the automatic backup schedule evidence |
| POST | /api/backups | Create a database backup immediately and apply the retention count |
Error codes shared across endpoints:
| Status | Code | Description |
|---|---|---|
| 500 | BACKUP_FAILED | The backup command reported a failure, or the schedule could not be loaded |
A listing failure is not an error status. GET /api/backups returns 200 with an empty inventory, a listError string, and the schedule evidence.
Command surface
| Command | Purpose |
|---|---|
fn backup --create |
Create a database backup stem and apply retention |
fn backup --list |
List the stored database backup stems, newest first |
fn backup --restore with a file argument |
Restore from a selected project or central dump |
fn backup --cleanup |
Delete the stems beyond the retention count |
fn memory-backup --create with an optional --scope of project, agents, or all |
Create a memory snapshot |
fn memory-backup --list |
List the memory snapshots, newest first |
fn memory-backup --restore with a directory argument |
Restore memory from a snapshot directory |
Key Sequences
Create a database backup
Operator BackupManager PgBackupManager pg_dump Filesystem
| | | | |
|-- fn backup --create| | | |
| |-- createBackup() --->| | |
| | |-- mkdir backup dir ------------>|
| | |-- claim stem (marker) --------->|
| | | | |
| | |-- dump project+archive ------->|
| | | |-- .part file ->|
| | |-- publish .part -> final ------>|
| | | | |
| | |-- dump central ---------------->|
| | |-- publish .part -> final ------>|
| | | | |
| | |-- dump migration bookkeeping ->|
| | |-- publish .part -> final ------>|
| | | | |
| | |-- release marker -------------->|
| | |-- cleanup old stems ---------->|
| |<-- PgBackupPair -----| | |
|<-- output ---------| | | |
Restore a database backup
Operator BackupManager PgBackupManager pg_restore Ledger
| | | | |
|-- fn backup --restore FILE | | |
| |-- resolve selection->| | |
| | (project or central; a bookkeeping dump alone is refused)
| | | | |
| |-- validate sources ->| | |
| | |-- pg_restore --list -> |
| | | | |
| |-- capture pre-restore stem | |
| | |-- dump project+central+migrations|
| | | | |
| |-- restore project --->| | |
| | |-- pg_restore (single transaction)|
| |-- restore central --->| | |
| |-- restore bookkeeping -> | |
| | | | |
| |-- reconcile ledger ---------------------->| |
| | (rewind from earliest missing sentinel, replay baseline)
| | | | |
|<-- success ------ | | | |
| |
| on failure after the project group committed:
| |-- roll back project, central, bookkeeping from the retained stem
|<-- failure with the retained dump names -----
Create and restore a memory snapshot
Operator MemoryBackupManager Filesystem
| | |
|-- fn memory-backup --create |
| |-- mkdir snapshot tmp |
| |-- copy .fusion/memory -> snapshot/project
| |-- copy .fusion/agent-memory -> snapshot/agents
| |-- rename tmp -> final |
|<-- snapshot info --| |
|
|-- fn memory-backup --restore DIR |
| |-- read snapshot files |
| |-- write each file to a temporary path
| |-- rename each into place
| | (a changed destination file is refused without overwrite)
|<-- success --------| |
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Backup format | pg_dump --format=custom logical dumps |
Standard PostgreSQL format, supports parallel and selective restore through pg_restore |
| Schema coverage | Dump the project, archive, and central schemas rather than the whole cluster |
The cluster can hold unrelated databases, so a whole-cluster dump would capture more than Fusion owns |
| Bookkeeping dump | A separate fusion-migrations-pg-* file for public.fusion_schema_migrations |
pg_dump ignores --schema once --table is supplied, so the bookkeeping table needs its own archive |
| Credential transport | libpq PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE environment variables |
Keeps the password out of the process argument list and points the client at the embedded cluster's random port; the non-functional PG_CONNECTION_STRING variable is not used |
| Publication | Dump to a private .part path, then rename after the stem claim is rechecked |
A truncated archive is never restorable and never listed |
| Stem claim | An exclusively created .reserved marker holding an owner nonce |
A filename existence check is a cross-process race, so a single atomic claim covers both halves of a stem |
| Retention | Count stems, keep the newest N, never prune a pre-restore stem or a live claim | The rollback pair promised by a restore must survive retention |
| Restore ordering | ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree and archive, then central, then bookkeeping, then ledger reconciliation | The central schema holds the node and project registry, so it is restored after the project data it references |
| Rollback | Restore the retained pre-restore stem for every group already committed | A partial restore is worse than no restore, and the operator keeps the recovery evidence |
| Migration reconciliation | Rewind the ledger from the earliest missing schema sentinel, then replay the baseline in one transaction | Restoring an older dump drops later relations while the ledger still claims them, so the next startup would skip those migrations |
| Restore transaction | pg_restore --single-transaction |
A failed restore must not leave the target schemas half replaced |
| Client timeout | 120 seconds per native client invocation, configurable | A hung native client must not block the caller indefinitely |
| Backup root | The global Fusion directory for database dumps, the project root for memory snapshots | One PostgreSQL cluster serves every project, while the memory files are project-owned |
| Settings scope | Database backup policy in global settings, memory backup policy in project settings | Follows the ownership of the data each policy protects |
| Scheduled execution | The engine runs the canonical fn backup --create form in-process |
Shelling out would launch a possibly older binary from PATH; a command with shell metacharacters is not intercepted because its side effects cannot be mirrored |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) restore write | Write to a temporary file, then rename | A failed restore must not leave a truncated memory file |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) snapshot scope | project, agents, or all |
The operator can snapshot one memory root or both |
Risks and Unknowns
pg_dumpandpg_restoreare not bundled withembedded-postgres. A host without the PostgreSQL client tools cannot run a backup or restore, and the failure only appears when the command runs.- The native backup commands take no cross-process lock and do not quiesce other writers. A restore while the engine is writing can capture a torn state.
- A
pg_dumpmajor version that differs from the server major version can produce a dump that warns about format incompatibility. - The migration reconciliation catalog is a hand-maintained list of sentinels. A new migration that is not in the catalog can be skipped by a restore of an older dump.
- The pre-restore stems accumulate because retention never prunes them.
- The dashboard inventory lists one row per dump file, so a complete three-file stem appears as three rows.
- The CLICommand-line interface always restores memory with overwrite enabled, so the library guard against overwriting a changed memory file is unreachable from the operator surface.
fn backup --restorecannot restore the project schemas without also restoring the central schema, because the CLICommand-line interface does not expose theskipCentraloption.
Out of Scope
- Copying or moving a live database file (the SQLite file-copy backup path was removed with the PostgreSQL cutover)
- Backing up the Git worktrees, the git history, or the task worktree contents
- Backing up the dashboard configuration, the plugin directory, or the local model cache
- Encrypting the dump files at rest
- Uploading the dumps to object storage or any remote destination
- Cross-process locking or cluster-wide quiescence around the native backup commands
- The
fn db migratepre-migration SQLite copy, which belongs to the PostgreSQL cutover
Test Plan: Database & MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backup and Restore
Scope
Covers the PostgreSQL dump creation, listing, retention, and restore path, the migration ledger reconciliation after a restore, the backup settings scope and migration, the automatic backup schedule, the fn backup and fn memory-backup command surfaces, the in-process scheduled backup interception, and the dashboard GET and POST /api/backups routes.
Out of scope: the PostgreSQL cutover (fn db migrate) and its pre-migration SQLite copy, the memory backend itself, and any end-to-end test that restores a live production cluster.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | pg_dump produces the project, central, and bookkeeping dump files |
A PgBackupManager with an injected client exec |
Three published files that share one stem |
| TC-2 | The central dump is skipped when it is turned off | includeCentral: false |
No central file, and the pair records the skip |
| TC-3 | Connection components travel through the libpq environment variables | A connection string with a password | The exec env carries PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE, and the argv carries none of them |
| TC-4 | The same libpq environment reaches pg_restore |
A restore call | The restore exec env matches the dump exec env |
| TC-5 | A failed central dump removes the orphaned project dump | The central dump throws | No file from that stem remains |
| TC-6 | The project dump covers the project and archive schemas, the central dump covers only central |
A recorded pg_dump argv |
The schema flags match the two groups |
| TC-7 | The listing is empty when the backup directory is absent | No directory | An empty list |
| TC-8 | The listing reports project and central orphans and skips malformed files | A directory with orphan and malformed names | Orphans reported, malformed names ignored |
| TC-9 | One stem is shared by both halves | Two dumps in the same second | The same stem, and a counter suffix on collision |
| TC-10 | The listing returns pairs newest first | Several stored stems | Newest first |
| TC-11 | Retention keeps the configured count of stems | A retention count of 2 | The two oldest stems deleted, with every file of each stem |
| TC-12 | A source archive is listed before a destructive restore | A valid dump | The restore is called with the list-only flag first |
| TC-13 | A corrupt archive fails validation before the restore | A corrupt dump | The validation throws and no restore runs |
| TC-14 | The native client timeout stays bounded and the error is credential-safe | An injected client that never settles | The call is abandoned at the timeout, with no password in the message |
| TC-15 | A restore spawn failure redacts the password | A client that throws with a URL | The password is replaced by a mask |
| TC-16 | A missing dump file fails the restore | A path that does not exist | The restore throws |
| TC-17 | The stem claim is exclusive, publication is a rename, and no residue is left | Two concurrent claims | One owner, a rename-based publication, and no leftover files |
| TC-18 | Retention leaves pre-restore stems and live claims alone | A pre-restore stem and a live marker | Both survive the cleanup |
| TC-19 | Only abandoned reservations and their partial dumps are swept | A stale marker and a live marker | The stale one is removed and the live one is kept |
| TC-20 | The connection string parser handles both shapes | A URL form and a libpq keyword/value form | The expected host, port, user, password, and database |
| TC-21 | The migration rewind floor is the earliest missing sentinel | A catalog that misses an early relation | The floor is that relation's version, and the ledger is rewound from it |
| TC-22 | A later sentinel does not hide an earlier missing version | A catalog that misses 0011 while 0012 is present |
The rewind starts at 0011 |
| TC-23 | A present column with the wrong primary key still rewinds | A catalog where the column exists but the key is single-column | The rewind starts at the key repair version |
| TC-24 | A present trigger with a missing policy or unforced RLS still rewinds | A catalog missing the trigger, the policy, or the forced RLS | The rewind starts at the partition repair version |
| TC-25 | A wrong column data type still rewinds | A catalog where the counter column is integer |
The rewind starts at the bigint counter version |
| TC-26 | A failed baseline replay keeps the ledger versions | A baseline that throws | The ledger is unchanged |
| TC-27 | The reconciliation TLS policy separates loopback from remote hosts | A loopback URL and a remote URL | TLS off for loopback, certificate verification for remote |
| TC-28 | The backup root resolves to the global settings directory | A store that reports a global settings directory | The manager is built on that directory |
| TC-29 | An external connection string wins over the embedded registry | Both configured | The external string is used |
| TC-30 | The schedule status carries the run count, last run, and last outcome | A routine with a last run result | The evidence fields are populated and the output is bounded |
| TC-31 | An unchanged routine keeps its cadence | A routine that matches the desired fields | The sync plan is a no-op |
| TC-32 | The settings migration adopts a single configured project value | One project with a value | The global value is that value |
| TC-33 | The settings migration records a conflict when projects disagree | Two projects with different values | The conflict is recorded and the global value is not overwritten |
| TC-34 | The settings scope keeps the database policy global and the memory policy project-scoped | A global and a project configuration | The database keys land in global settings and the memory keys in project settings |
| TC-35 | The in-process backup command matcher accepts the canonical forms | fn backup --create, npx -y runfusion.ai backup --create, and case variants |
All intercepted |
| TC-36 | The in-process backup command matcher refuses other forms | fn backup --list, a command with a shell continuation, and a trailing positional argument |
None intercepted |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-37 | The backup inventory route returns the newest dumps and the schedule evidence | A registered backup routine | The response carries the backups, the count, the total size, and the schedule |
| TC-38 | A failed backup creation surfaces as a route error | A backup command that reports a failure | The route returns the failure instead of a success body |
| TC-39 | A failed listing still returns the schedule evidence | A manager that cannot list | An empty inventory, the listing error, and the schedule evidence |
| TC-40 | A paired restore validates, retains a pre-restore stem, then restores project before central | A fake PgBackupManager |
The call order is validation, pre-restore capture, project restore, central restore |
| TC-41 | A bookkeeping restore is refused without a pre-restore rollback source | A stem that contains bookkeeping | The restore is refused before any client call |
| TC-42 | A central restore failure rolls the project group back from the retained stem | A fake manager that fails on central | The project rollback is recorded and the failure names the retained dumps |
| TC-43 | A reconciliation failure rolls the project group back | A reconcile seam that throws | The project rollback is recorded |
| TC-44 | A central-only restore leaves the bookkeeping untouched | A selected central dump | The bookkeeping is reported as skipped for a central-only restore |
| TC-45 | The fn backup commands resolve the project store and close it |
A resolved project | Each command uses the resolved store and the store is closed |
| TC-46 | The fn backup commands retry a transient lock and fail cleanly when the lock persists |
A store that reports a lock error | The command retries, then fails with a clear error and closes the store |
| TC-47 | The fn memory-backup commands create, list, and restore |
A resolved project | Each command calls the matching core function |
| TC-48 | The fn memory-backup commands retry a transient lock and close the store |
A store that reports a lock error | The command retries, then fails with a clear error and closes the store |
| TC-49 | The CLICommand-line interface routes the backup and memory-backup flags | The argument parser | Each flag reaches its command, and a missing flag prints the usage line and exits 1 |
| TC-50 | The scheduled backup runs in-process and resolves the shared cluster root | A schedule whose command is fn backup --create |
The core backup command is called with the global settings directory |
| TC-51 | A manual automation run intercepts the in-process backup | A manual run of a fn backup --create schedule |
The run is intercepted instead of shelling out |
| TC-52 | The settings section styles use the design tokens | The backup section stylesheet | The selectors exist and use the token variables |
| TC-53 | A live PostgreSQL cluster separates the bookkeeping dump from the project dump | An embedded or shared PostgreSQL test harness | The bookkeeping listing names the bookkeeping table and the project listing does not |
| TC-54 | A live restore returns the ledger to the captured version set | A captured backup and a drifted ledger | The ledger matches the captured set and the drift marker is gone |
| TC-55 | A live legacy pair leaves the bookkeeping untouched | A stem whose bookkeeping file is removed | The bookkeeping is reported as unavailable and the ledger is unchanged |
| TC-56 | A live central-only restore leaves the bookkeeping untouched | A central dump | The bookkeeping is reported as skipped and the ledger is unchanged |
| TC-57 | A live bookkeeping restore without a pre-restore stem is refused before any mutation | A live task row in the project schema | The call is refused and the task rows and the ledger are unchanged |
End-to-End Tests
| ID | Description | Steps | Expected Outcome |
|---|---|---|---|
| TC-58 | The dashboard operator creates a backup and sees it in the inventory | Open the Database Backups settings section, press Backup Now, then reload the inventory | The creation succeeds and the new dump appears in the list |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-59 | The pg_dump binary is missing |
The backup fails with an error that explains the PostgreSQL client tools must be installed |
| TC-60 | The connection string cannot be parsed | The client receives no PG* values and the error is a clear connect failure |
| TC-61 | A selected file name is not a canonical dump name | The selection is refused with a message that names the expected pattern |
| TC-62 | A bookkeeping dump is selected for restore | The selection is refused because bookkeeping dumps cannot be restored alone |
| TC-63 | skipCentral and centralOnly are both requested |
The restore is refused as contradictory |
| TC-64 | The pre-restore capture did not produce a complete stem | The restore is refused before any target mutation |
| TC-65 | The rollback of a committed group also fails | Both the original failure and the rollback failure are reported |
| TC-66 | The backup directory is absolute, contains a parent-directory segment, or starts with a drive letter | The directory is rejected |
| TC-67 | The cron expression is invalid | The backup run is refused with the invalid expression named |
| TC-68 | The retention count is outside 1 to 100 | The retention value is rejected |
| TC-69 | A memory snapshot would overwrite a changed memory file | The restore is refused and names the file, unless overwrite was requested |
| TC-70 | The memory snapshot holds neither memory root | The backup fails and names the scope it looked for |
| TC-71 | The memory backup directory escapes the project root | The directory is rejected |
| TC-72 | A memory snapshot name already exists | A counter suffix is added so the new snapshot does not overwrite the old one |
Test Infrastructure
- Vitest across the
core,engine,dashboard, andclipackages. PgBackupManagertakes an injected client exec, so the dump and restore contract is proven without a live cluster and without wall-clock fixtures.- The shared PostgreSQL harness (
packages/core/src/__test-utils__/pg-test-harness.ts) provides the live cluster for the bookkeeping cases, and those cases skip whenpg_dumpandpg_restoreare not onPATH. - The dashboard route tests mount the registrar against a fake store.
- The CLICommand-line interface tests mock
@fusion/coreand the project context, and assert on the store close on every exit path. - The memory snapshot file operations are exercised only through the CLICommand-line interface tests, which mock the core manager.
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall create a database backup that dumps the `project` and `archive` schemas into a `fusion-pg-` dump file, the `central` schema into a `fusion-central-pg-` dump file, and the `public.fusion_schema_migrations` bookkeeping table into a `fusion-migrations-pg-` dump file, where each name ends with the shared timestamp stem and the `.dump` extension | TC-1, TC-2, TC-6, TC-53 |
| FR-2MustThe system shall publish each dump by writing to a private in-progress artifact and renaming it into place only after the dump completed and the stem claim is still owned, so a partial dump is never listed and never restorable | TC-5, TC-17 |
| FR-3MustThe system shall claim a backup stem exclusively with a per-stem reservation marker so two processes cannot capture the same stem | TC-9, TC-17 |
| FR-4MustThe system shall list backup stems newest first, grouping the project, central, and migration files of one stem into a single entry, and shall report a stem whose central or migration file is missing as incomplete instead of presenting it as a full backup | TC-7, TC-8, TC-10, TC-61 |
| FR-5MustThe system shall restore a selected stem by validating every source archive first, capturing a retained pre-restore stem, and then restoring the project and archive schemas, the central schema, and the migration bookkeeping in that order | TC-12, TC-16, TC-40, TC-53 |
| FR-6MustThe system shall refuse to restore migration bookkeeping when the pre-restore capture is disabled, because that capture is the rollback source | TC-41, TC-57 |
| FR-7MustThe system shall roll back every restore group it already committed from the retained pre-restore stem when a later group or the migration reconciliation fails, and shall report both the original failure and any rollback failure | TC-42, TC-43, TC-64, TC-65 |
| FR-8MustThe system shall reconcile `public.fusion_schema_migrations` after a project restore by rewinding the ledger from the earliest missing schema sentinel and replaying the schema baseline, so an older dump cannot skip later schema upgrades | TC-21, TC-22, TC-23, TC-24, TC-25, TC-26, TC-54 |
| FR-9MustThe system shall treat a selected `fusion-central-pg-*` dump as a central-only restore that leaves the migration bookkeeping untouched, and shall reject contradictory restore options | TC-44, TC-56, TC-62, TC-63 |
| FR-10MustThe system shall delete backups beyond the configured retention count, oldest first, and shall never delete a pre-restore stem or a stem that holds a live reservation | TC-11, TC-18, TC-19, TC-68 |
| FR-11MustThe system shall provide the `fn backup --create`, `fn backup --list`, `fn backup --restore` with a file argument, and `fn backup --cleanup` commands | TC-45, TC-46, TC-49 |
| FR-12MustThe system shall run an automatic database backup on a cron expression as a global routine named "Database Backup" that runs `fn backup --create` | TC-30, TC-31, TC-50, TC-67 |
| FR-13MustThe system shall expose the database backup inventory at `GET /api/backups` and an immediate backup creation at `POST /api/backups`, and shall show the inventory together with the schedule evidence in the global Database Backups settings section | TC-28, TC-37, TC-38, TC-39, TC-52, TC-58 |
| FR-14MustThe system shall create a memory backup that snapshots the project memory directory `.fusion/memory` and the agent memory directory `.fusion/agent-memory` into a timestamped directory, honoring the configured scope | TC-70, TC-72 |
| FR-15MustThe system shall list memory backups with their scope, file count, size, and creation time, and shall delete memory backups beyond the configured retention count, oldest first | TC-47, TC-72 |
| FR-16MustThe system shall restore memory from a snapshot directory, and shall refuse to overwrite an existing memory file whose content differs from the snapshot unless the caller asks for overwrite | TC-47, TC-69 |
| FR-17MustThe system shall provide the `fn memory-backup --create` command with an optional `--scope` argument of `project`, `agents`, or `all`, plus the `fn memory-backup --list` command and the `fn memory-backup --restore` command with a directory argument | TC-47, TC-48, TC-49 |
| FR-18MustThe system shall run an automatic memory backup on a cron expression as a project routine named "MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) Backup" that runs `fn memory-backup --create` | TC-30, TC-31, TC-48 |
| FR-19MustThe system shall store the database backup policy (`autoBackupEnabled`, `autoBackupSchedule`, `autoBackupRetention`, `autoBackupDir`) in global settings, and the memory backup policy (`memoryBackupEnabled`, `memoryBackupSchedule`, `memoryBackupRetention`, `memoryBackupDir`, `memoryBackupScope`) in project settings | TC-34 |
| FR-20MustThe system shall migrate the database backup settings from project scope to global scope once, adopting a single configured value, keeping any existing global value, and recording a conflict for the operator to resolve when projects disagree | TC-32, TC-33 |
| FR-21ShouldThe system shall run the automatic backup inside the engine process when the scheduled command is the canonical `fn backup --create` or `fn memory-backup --create` form, and shall decline that interception when the command embeds a shell continuation, redirection, or substitution | TC-35, TC-36, TC-50, TC-51 |
| FR-22ShouldThe system shall sweep abandoned in-progress artifacts and their reservation markers, and shall not sweep a live claim | TC-19 |
| FR-23ShouldThe system shall keep the next-run time of an existing backup routine when the desired routine fields are unchanged, so a settings save does not postpone a due backup | TC-31 |
| NFR-1MustThe system shall pass PostgreSQL connection components to `pg_dump` and `pg_restore` only through the libpq `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, and `PGDATABASE` environment variables, never as process arguments, and shall redact the connection-string password from any client error message | TC-3, TC-4, TC-15, TC-20, TC-29, TC-60 |
| NFR-2MustThe system shall validate every source dump with `pg_restore --list` before any destructive restore, so a corrupt archive is refused before the target schemas are touched | TC-12, TC-13 |
| NFR-3MustThe system shall run each restore in a single transaction, so a failed restore does not leave the target schemas half replaced | TC-40 |
| NFR-4MustThe system shall bound every `pg_dump` and `pg_restore` invocation with a client timeout of 120 seconds by default, so a hung native client cannot block the caller | TC-14 |
| NFR-5MustThe system shall apply the ledger rewind and the baseline replay in one transaction, so a failed replay cannot leave a rewound ledger against restored schemas | TC-26 |
| NFR-6MustThe system shall reject a backup directory that is absolute, that contains a parent-directory segment, or that starts with a drive letter, for both the database and the memory backup directory | TC-66, TC-71 |
| NFR-7MustThe system shall require certificate verification when reconciling migrations against a remote PostgreSQL host, and shall keep TLS off for loopback and embedded clusters that have no TLS | TC-27 |
| NFR-8MustThe system shall report the schedule evidence (enabled state, cron expression, next run, last run, last outcome, run count) alongside the backup inventory, so an empty inventory cannot hide a schedule failure | TC-30, TC-39 |
| NFR-9MustThe system shall order its `pg_dump` and `pg_restore` install-location search with the server major version, which is 15 for the embedded cluster, ahead of the later major versions, to avoid dump-format incompatibility | TC-10 |
| NFR-10ShouldThe system shall resolve `pg_dump` and `pg_restore` from `PATH` first and then from common install locations, and shall surface a missing binary as a named native client failure | TC-59 |
| NFR-11ShouldThe system shall keep a legacy two-member backup stem restorable, shall report its migration bookkeeping as unavailable, and shall still rewind and replay the ledger for it | TC-55 |
| NFR-12ShouldThe system shall record the run count, the last run time, and the last run outcome of the backup routine, so an operator can see whether the schedule works | TC-30 |
| NFR-13ShouldThe system shall warn the operator when automatic backups are enabled but no routine is registered, naming the two actions that reconcile it | TC-39 |
| NFR-14ShouldThe system shall write each restored memory file to a temporary file and rename it into place, so a failed restore does not leave a truncated memory file | TC-69 |
Key Test Files
packages/core/src/__tests__/postgres/pg-backup.test.tspackages/core/src/__tests__/backup.test.tspackages/core/src/__tests__/postgres/pg-backup-migration-bookkeeping.pg.test.tspackages/core/src/__tests__/backup-schedule-status.test.tspackages/core/src/__tests__/backup-settings-migration.test.tspackages/core/src/__tests__/backup-settings-scope.test.tspackages/cli/src/commands/__tests__/backup.test.tspackages/cli/src/commands/__tests__/backup-lock-retry.test.tspackages/cli/src/commands/__tests__/memory-backup.test.tspackages/cli/src/commands/__tests__/memory-backup-lock-retry.test.tspackages/cli/src/__tests__/bin.test.tspackages/engine/src/__tests__/cron-runner.test.tspackages/dashboard/src/routes/__tests__/register-system-maintenance-routes.test.tspackages/dashboard/src/__tests__/routes-automation.test.tspackages/dashboard/app/components/__tests__/SettingsModal.backup.css.test.ts
requirements
- The dashboard inventory lists one row per dump file, so a complete three-file stem appears as three rows. Should the inventory group by stem instead?
- The CLI has no flag to restore the project schemas without also restoring the central schema. Is a project-only restore a required operator action?
- Pre-restore stems are retained indefinitely and the retention count never prunes them. What is the intended way to reclaim that disk space once a restore is confirmed?
- The CLI always restores memory with overwrite enabled, so the library guard against overwriting a changed memory file is unreachable from the operator surface. Should the CLI expose that choice?
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Dev Server Lifecycle Management
Overview
Fusion detects a project's dev-server command from its package manifests, starts, stops, and restarts that command for the current task, streams its output as live logs, and embeds a preview of the running app in a dashboard panel.
The dashboard detects candidate scripts from the project root and from workspace packages, scores and ranks them, and lets the operator pick one.
The dashboard can target the checked-out worktree of an executing task so the preview reflects in-progress work instead of the integration branch.
A background probe and per-framework log parsers discover the app's local URL so the preview opens without operator input, and the operator can override that URL by hand.
The whole surface sits behind the devServerView experimental feature flag and is reachable from the right dock.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Solo developer | Runs the project's dev server from the dashboard and sees the app without leaving the board |
| Operator / power user | Chooses which script runs, points the server at a task worktree, and manages the preview URL |
| Maintainer / contributor | Keeps the canonical dev-server-* module family free of drift against the disconnected devserver-* family |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall detect candidate dev-server scripts from the project root `package.json` and from workspace `packages/*` and `apps/*` manifests, and rank them by a confidence score derived from script-name priority, framework dependency indicators, and the `private`/missing-`main` heuristic | Must | The system shall detect candidate dev-server scripts from the project root package.json and from workspace packages/* and apps/* manifests, and rank them by a confidence score derived from script-name priority, framework dependency indicators, and the private/missing-main heuristic |
| FR-2MustThe system shall expose the detected candidates over `GET /api/dev-server/detect`, read the persisted selection with `GET /api/dev-server/config`, and update the selected script, source, command, and preview URL override with `PUT /api/dev-server/config` | Must | The system shall expose the detected candidates over GET /api/dev-server/detect, read the persisted selection with GET /api/dev-server/config, and update the selected script, source, command, and preview URL override with PUT /api/dev-server/config |
| FR-3MustThe system shall start the dev server with `POST /api/dev-server/start`, spawning the command with a shell in the requested working directory, and shall reject the request with `400` when `command` or `cwd` is missing and with `409` when a server is already running | Must | The system shall start the dev server with POST /api/dev-server/start, spawning the command with a shell in the requested working directory, and shall reject the request with 400 when command or cwd is missing and with 409 when a server is already running |
| FR-4MustThe system shall stop the dev server with `POST /api/dev-server/stop` by sending `SIGTERM` to the process group and escalating to `SIGKILL` after the stop timeout, and shall restart it with `POST /api/dev-server/restart` using the stored command and working directory | Must | The system shall stop the dev server with POST /api/dev-server/stop by sending SIGTERM to the process group and escalating to SIGKILL after the stop timeout, and shall restart it with POST /api/dev-server/restart using the stored command and working directory |
| FR-5MustThe system shall report the current dev-server state over `GET /api/dev-server/status`, including status, command, working directory, process id, timestamps, exit code, the detected preview URL and port, the manual preview URL override, the resolved preview URL, and whether the process is running | Must | The system shall report the current dev-server state over GET /api/dev-server/status, including status, command, working directory, process id, timestamps, exit code, the detected preview URL and port, the manual preview URL override, the resolved preview URL, and whether the process is running |
| FR-6MustThe system shall persist the dev-server state and configuration to `.fusion/dev-server.json` in the project directory, and shall restore that state on load, capping the stored log history at 500 lines | Must | The system shall persist the dev-server state and configuration to .fusion/dev-server.json in the project directory, and shall restore that state on load, capping the stored log history at 500 lines |
| FR-7MustThe system shall stream dev-server output to the dashboard over the `GET /api/dev-server/logs/stream` server-sent events endpoint, sending the stored history first and then live `log`, `stopped`, `failed`, and `dev-server:url-detected` events, with a heartbeat comment every 30 seconds | Must | The system shall stream dev-server output to the dashboard over the GET /api/dev-server/logs/stream server-sent events endpoint, sending the stored history first and then live log, stopped, failed, and dev-server:url-detected events, with a heartbeat comment every 30 seconds |
| FR-8MustThe system shall detect the app's local preview URL from the process output, first by parsing framework-specific patterns (Vite, Next.js, Storybook, Angular) and then generic URL and keyword-plus-port patterns, and shall fall back to probing a fixed list of common local ports when no URL is announced | Must | The system shall detect the app's local preview URL from the process output, first by parsing framework-specific patterns (Vite, Next.js, Storybook, Angular) and then generic URL and keyword-plus-port patterns, and shall fall back to probing a fixed list of common local ports when no URL is announced |
| FR-9MustThe system shall let the operator override the preview URL with `PUT /api/dev-server/preview-url`, accepting only `http://` or `https://` URLs and clearing the override when the URL is empty | Must | The system shall let the operator override the preview URL with PUT /api/dev-server/preview-url, accepting only http:// or https:// URLs and clearing the override when the URL is empty |
| FR-10MustThe system shall render a Dev Server view in the dashboard that lists detected candidates, shows a status badge, starts, stops, and restarts the server, shows the running command, and exposes the preview URL override field | Must | The system shall render a Dev Server view in the dashboard that lists detected candidates, shows a status badge, starts, stops, and restarts the server, shows the running command, and exposes the preview URL override field |
| FR-11MustThe system shall let the operator point the dev server at the worktree of an executing task, listing only tasks in a work-in-progress column that have a worktree path, and using that worktree as the working directory of the started process | Must | The system shall let the operator point the dev server at the worktree of an executing task, listing only tasks in a work-in-progress column that have a worktree path, and using that worktree as the working directory of the started process |
| FR-12MustThe system shall embed the running app in an iframe preview that reports a loading, embedded, blocked, or error state, and shall offer an open-in-new-tab fallback when the app cannot be embedded | Must | The system shall embed the running app in an iframe preview that reports a loading, embedded, blocked, or error state, and shall offer an open-in-new-tab fallback when the app cannot be embedded |
| FR-13MustThe system shall show the dev-server output in a log panel that strips ANSI escape codes, filters by severity, searches the text, loads older lines, and can toggle fullscreen | Must | The system shall show the dev-server output in a log panel that strips ANSI escape codes, filters by severity, searches the text, loads older lines, and can toggle fullscreen |
| FR-14MustThe system shall show the Dev Server panel only when the `devServerView` experimental feature flag is enabled, and shall accept the legacy `devServer` flag as an alias for it | Must | The system shall show the Dev Server panel only when the devServerView experimental feature flag is enabled, and shall accept the legacy devServer flag as an alias for it |
| FR-15ShouldThe system shall show the preview in a modal when the right dock that hosts the view is narrower than 480 pixels, keeping the configuration and log panels usable | Should | The system shall show the preview in a modal when the right dock that hosts the view is narrower than 480 pixels, keeping the configuration and log panels usable |
| FR-16ShouldThe system shall restore the typed command, the selected script, and the selected task when the Dev Server view remounts, per project | Should | The system shall restore the typed command, the selected script, and the selected task when the Dev Server view remounts, per project |
| FR-17ShouldThe system shall poll the dev-server status every 3 seconds while the server is running or starting, and shall suspend that polling while the browser tab is hidden | Should | The system shall poll the dev-server status every 3 seconds while the server is running or starting, and shall suspend that polling while the browser tab is hidden |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustThe system shall reject a dev-server command that contains command substitution (`$(...)`, backticks, process substitution) or control characters, because the command is spawned with a shell | Must | Security | The system shall reject a dev-server command that contains command substitution ($(...), backticks, process substitution) or control characters, because the command is spawned with a shell |
| NFR-2MustThe system shall terminate the whole child process tree on stop, restart, cleanup, and dashboard server shutdown, so no dev-server process outlives the dashboard | Must | Resource cleanup | The system shall terminate the whole child process tree on stop, restart, cleanup, and dashboard server shutdown, so no dev-server process outlives the dashboard |
| NFR-3MustThe system shall clear the fallback port probe timer on stop, close, failure, restart, and cleanup, so a stopped server leaves no pending timer | Must | Resource cleanup | The system shall clear the fallback port probe timer on stop, close, failure, restart, and cleanup, so a stopped server leaves no pending timer |
| NFR-4MustThe system shall release the server-sent events listeners and the heartbeat interval when the client disconnects from the log stream | Must | Resource cleanup | The system shall release the server-sent events listeners and the heartbeat interval when the client disconnects from the log stream |
| NFR-5MustThe system shall mark a persisted running or starting server as stopped when its recorded process id is no longer alive, and shall log that recovery | Must | Availability | The system shall mark a persisted running or starting server as stopped when its recorded process id is no longer alive, and shall log that recovery |
| NFR-6MustThe system shall ignore late lifecycle callbacks, stale stdout detection, and stale fallback probes from a previous run, so a restart cannot write into the previous run's state | Must | Availability | The system shall ignore late lifecycle callbacks, stale stdout detection, and stale fallback probes from a previous run, so a restart cannot write into the previous run's state |
| NFR-7MustThe system shall never suggest the reserved dashboard port 4040 as a preview port | Must | Correctness | The system shall never suggest the reserved dashboard port 4040 as a preview port |
| NFR-8ShouldThe system shall keep the persisted and in-memory log history bounded to 500 lines | Should | Performance | The system shall keep the persisted and in-memory log history bounded to 500 lines |
| NFR-9ShouldThe system shall probe fallback ports sequentially in a fixed order so the first responsive port wins deterministically | Should | Performance | The system shall probe fallback ports sequentially in a fixed order so the first responsive port wins deterministically |
| NFR-10ShouldThe system shall record dev-server lifecycle transitions, the resolved preview URL and port, and the process exit code in the persisted state so an operator can inspect them after the fact | Should | Observability | The system shall record dev-server lifecycle transitions, the resolved preview URL and port, and the process exit code in the persisted state so an operator can inspect them after the fact |
| NFR-11ShouldThe system shall tolerate a malformed or missing `.fusion/dev-server.json` file by falling back to default state and configuration | Should | Availability | The system shall tolerate a malformed or missing .fusion/dev-server.json file by falling back to default state and configuration |
| NFR-12ShouldThe dashboard APIApplication programming interface shall use only the canonical `dev-server-*` module family, and the `devserver-*` family shall stay isolated from the runtime import graph | Should | Maintainability | The dashboard APIApplication programming interface shall use only the canonical dev-server-* module family, and the devserver-* family shall stay isolated from the runtime import graph |
Constraints
- The feature is gated behind the
devServerViewexperimental feature flag, withdevServeraccepted as a legacy alias - The canonical runtime family is
dev-server-*underpackages/dashboard/src(dev-server-routes.ts,dev-server-process.ts,dev-server-store.ts,dev-server-detect.ts,dev-server-port-detect.ts) - The
devserver-*family underpackages/dashboard/src(devserver-detect.ts,devserver-manager.ts,devserver-persistence.ts,devserver-types.ts) has no production importer and only its own unit tests - The two families persist to different files,
.fusion/dev-server.jsonand.fusion/devserver.json - The dashboard APIApplication programming interface mounts the router at
/api/dev-serverthrough theregisterIntegratedDevServerRouterregistrar - The child process is spawned through
superviseSpawnfrom@fusion/corewithshell: trueand a 24 hour maximum lifetime - Port 4040 is reserved for the dashboard and is never a preview port
- The persisted state file lives under the project directory and is not part of the task store
Acceptance Criteria
-
FR-1MustThe system shall detect candidate dev-server scripts from the project root `package.json` and from workspace `packages/*` and `apps/*` manifests, and rank them by a confidence score derived from script-name priority, framework dependency indicators, and the `private`/missing-`main` heuristic
gherkin @FR-1MustThe system shall detect candidate dev-server scripts from the project root `package.json` and from workspace `packages/*` and `apps/*` manifests, and rank them by a confidence score derived from script-name priority, framework dependency indicators, and the `private`/missing-`main` heuristic Scenario: Detect and rank candidate scripts Given a project root package.json with a "dev" script and a "serve" script When the operator requests the detected candidates Then the "dev" script is ranked above the "serve" script by confidence And the candidates for workspace packages are included with their relative source path -
FR-2MustThe system shall expose the detected candidates over `GET /api/dev-server/detect`, read the persisted selection with `GET /api/dev-server/config`, and update the selected script, source, command, and preview URL override with `PUT /api/dev-server/config`
gherkin @FR-2MustThe system shall expose the detected candidates over `GET /api/dev-server/detect`, read the persisted selection with `GET /api/dev-server/config`, and update the selected script, source, command, and preview URL override with `PUT /api/dev-server/config` Scenario: Persist the selected script Given a detected candidate named "dev" in the root package When the operator saves a config update with selectedScript "dev" and selectedCommand "vite" Then GET /api/dev-server/config returns the saved values And GET /api/dev-server/config returns all null fields when no config file exists -
FR-3MustThe system shall start the dev server with `POST /api/dev-server/start`, spawning the command with a shell in the requested working directory, and shall reject the request with `400` when `command` or `cwd` is missing and with `409` when a server is already running
gherkin @FR-3MustThe system shall start the dev server with `POST /api/dev-server/start`, spawning the command with a shell in the requested working directory, and shall reject the request with `400` when `command` or `cwd` is missing and with `409` when a server is already running Scenario: Start the dev server Given no dev server is running When the operator posts a command and a working directory to /api/dev-server/start Then the response status is "running" with the process id and the requested working directorygherkin @FR-3MustThe system shall start the dev server with `POST /api/dev-server/start`, spawning the command with a shell in the requested working directory, and shall reject the request with `400` when `command` or `cwd` is missing and with `409` when a server is already running Scenario: Reject an invalid start request Given no dev server is running When the operator posts a start request without a command Then the response status is 400gherkin @FR-3MustThe system shall start the dev server with `POST /api/dev-server/start`, spawning the command with a shell in the requested working directory, and shall reject the request with `400` when `command` or `cwd` is missing and with `409` when a server is already running Scenario: Refuse a second start Given a dev server is already running When the operator posts a start request Then the response status is 409 -
FR-4MustThe system shall stop the dev server with `POST /api/dev-server/stop` by sending `SIGTERM` to the process group and escalating to `SIGKILL` after the stop timeout, and shall restart it with `POST /api/dev-server/restart` using the stored command and working directory
gherkin @FR-4MustThe system shall stop the dev server with `POST /api/dev-server/stop` by sending `SIGTERM` to the process group and escalating to `SIGKILL` after the stop timeout, and shall restart it with `POST /api/dev-server/restart` using the stored command and working directory Scenario: Stop the dev server Given a dev server is running When the operator posts to /api/dev-server/stop Then the response status is "stopped" with an exit codegherkin @FR-4MustThe system shall stop the dev server with `POST /api/dev-server/stop` by sending `SIGTERM` to the process group and escalating to `SIGKILL` after the stop timeout, and shall restart it with `POST /api/dev-server/restart` using the stored command and working directory Scenario: Stop is idempotent Given no dev server is running When the operator posts to /api/dev-server/stop Then the response status is 200 and the current state is returned unchangedgherkin @FR-4MustThe system shall stop the dev server with `POST /api/dev-server/stop` by sending `SIGTERM` to the process group and escalating to `SIGKILL` after the stop timeout, and shall restart it with `POST /api/dev-server/restart` using the stored command and working directory Scenario: Restart uses the stored command Given a dev server was started with a command and a working directory When the operator posts to /api/dev-server/restart Then a new process runs with the same command and working directory -
FR-5MustThe system shall report the current dev-server state over `GET /api/dev-server/status`, including status, command, working directory, process id, timestamps, exit code, the detected preview URL and port, the manual preview URL override, the resolved preview URL, and whether the process is running
gherkin @FR-5MustThe system shall report the current dev-server state over `GET /api/dev-server/status`, including status, command, working directory, process id, timestamps, exit code, the detected preview URL and port, the manual preview URL override, the resolved preview URL, and whether the process is running Scenario: Report the current status Given a dev server with an auto-detected URL and a manual URL override When the operator requests /api/dev-server/status Then the response carries the manual URL as the resolved preview URL And the response carries the detected port and the running flag -
FR-6MustThe system shall persist the dev-server state and configuration to `.fusion/dev-server.json` in the project directory, and shall restore that state on load, capping the stored log history at 500 lines
gherkin @FR-6MustThe system shall persist the dev-server state and configuration to `.fusion/dev-server.json` in the project directory, and shall restore that state on load, capping the stored log history at 500 lines Scenario: Persist and restore the state Given a dev server that has produced more than 500 log lines When the store is written and loaded again Then the persisted file is at .fusion/dev-server.json and the log history holds the last 500 lines -
FR-7MustThe system shall stream dev-server output to the dashboard over the `GET /api/dev-server/logs/stream` server-sent events endpoint, sending the stored history first and then live `log`, `stopped`, `failed`, and `dev-server:url-detected` events, with a heartbeat comment every 30 seconds
gherkin @FR-7MustThe system shall stream dev-server output to the dashboard over the `GET /api/dev-server/logs/stream` server-sent events endpoint, sending the stored history first and then live `log`, `stopped`, `failed`, and `dev-server:url-detected` events, with a heartbeat comment every 30 seconds Scenario: Stream logs to the dashboard Given a client subscribed to /api/dev-server/logs/stream When the dev server writes a line to stdout Then the stream emits a "log" event carrying the line And the stream emitted the stored history before the live eventsgherkin @FR-7MustThe system shall stream dev-server output to the dashboard over the `GET /api/dev-server/logs/stream` server-sent events endpoint, sending the stored history first and then live `log`, `stopped`, `failed`, and `dev-server:url-detected` events, with a heartbeat comment every 30 seconds Scenario: Release the stream on disconnect Given a client subscribed to /api/dev-server/logs/stream When the client disconnects Then the manager no longer holds the stream listeners -
FR-8MustThe system shall detect the app's local preview URL from the process output, first by parsing framework-specific patterns (Vite, Next.js, Storybook, Angular) and then generic URL and keyword-plus-port patterns, and shall fall back to probing a fixed list of common local ports when no URL is announced
gherkin @FR-8MustThe system shall detect the app's local preview URL from the process output, first by parsing framework-specific patterns (Vite, Next.js, Storybook, Angular) and then generic URL and keyword-plus-port patterns, and shall fall back to probing a fixed list of common local ports when no URL is announced Scenario: Detect the preview URL from output Given a dev server that prints a Vite "Local: http://localhost:5173" line When the line is parsed Then the detected preview URL is http://localhost:5173 with port 5173gherkin @FR-8MustThe system shall detect the app's local preview URL from the process output, first by parsing framework-specific patterns (Vite, Next.js, Storybook, Angular) and then generic URL and keyword-plus-port patterns, and shall fall back to probing a fixed list of common local ports when no URL is announced Scenario: Probe a fallback port when no URL is announced Given a running dev server that printed no URL and has an open local port When the fallback probe grace period elapses Then the detected preview URL points at the first open common port -
FR-9MustThe system shall let the operator override the preview URL with `PUT /api/dev-server/preview-url`, accepting only `http://` or `https://` URLs and clearing the override when the URL is empty
gherkin @FR-9MustThe system shall let the operator override the preview URL with `PUT /api/dev-server/preview-url`, accepting only `http://` or `https://` URLs and clearing the override when the URL is empty Scenario: Set and clear the preview URL override Given a dev server with an auto-detected URL When the operator sets a manual URL of https://localhost:3000 Then the state carries the manual URL And an empty URL clears the overridegherkin @FR-9MustThe system shall let the operator override the preview URL with `PUT /api/dev-server/preview-url`, accepting only `http://` or `https://` URLs and clearing the override when the URL is empty Scenario: Reject a malformed preview URL Given a dev server When the operator sets a preview URL of "localhost:3000" Then the response status is 400 -
FR-10MustThe system shall render a Dev Server view in the dashboard that lists detected candidates, shows a status badge, starts, stops, and restarts the server, shows the running command, and exposes the preview URL override field
gherkin @FR-10MustThe system shall render a Dev Server view in the dashboard that lists detected candidates, shows a status badge, starts, stops, and restarts the server, shows the running command, and exposes the preview URL override field Scenario: Show the detected candidates Given the detection endpoint returns two candidates When the operator opens the Dev Server view Then the view renders a candidate button for each detected scriptgherkin @FR-10MustThe system shall render a Dev Server view in the dashboard that lists detected candidates, shows a status badge, starts, stops, and restarts the server, shows the running command, and exposes the preview URL override field Scenario: Drive the server from the view Given a stopped dev server When the operator clicks Start, Stop, and Restart in turn Then the view calls the matching lifecycle action for each click And the start button is disabled while the server is running -
FR-11MustThe system shall let the operator point the dev server at the worktree of an executing task, listing only tasks in a work-in-progress column that have a worktree path, and using that worktree as the working directory of the started process
gherkin @FR-11MustThe system shall let the operator point the dev server at the worktree of an executing task, listing only tasks in a work-in-progress column that have a worktree path, and using that worktree as the working directory of the started process Scenario: Target an executing task worktree Given one task in a work-in-progress column with a worktree path and one without a worktree path When the operator opens the Dev Server view Then only the task with a worktree appears in the task picker And selecting it and starting the server runs the command in that worktree -
FR-12MustThe system shall embed the running app in an iframe preview that reports a loading, embedded, blocked, or error state, and shall offer an open-in-new-tab fallback when the app cannot be embedded
gherkin @FR-12MustThe system shall embed the running app in an iframe preview that reports a loading, embedded, blocked, or error state, and shall offer an open-in-new-tab fallback when the app cannot be embedded Scenario: Embed the running app Given a running dev server with a preview URL When the preview iframe loads Then the embed status becomes "embedded"gherkin @FR-12MustThe system shall embed the running app in an iframe preview that reports a loading, embedded, blocked, or error state, and shall offer an open-in-new-tab fallback when the app cannot be embedded Scenario: Offer a fallback when embedding is blocked Given a preview URL that cannot be embedded When the embed status becomes "blocked" Then the fallback panel offers "Open in new tab" and "Retry embedded preview" -
FR-13MustThe system shall show the dev-server output in a log panel that strips ANSI escape codes, filters by severity, searches the text, loads older lines, and can toggle fullscreen
gherkin @FR-13MustThe system shall show the dev-server output in a log panel that strips ANSI escape codes, filters by severity, searches the text, loads older lines, and can toggle fullscreen Scenario: Filter and search the logs Given a set of log entries including stderr output When the operator filters by the error severity Then only the error entries remain And the ANSI escape codes are not rendered -
FR-14MustThe system shall show the Dev Server panel only when the `devServerView` experimental feature flag is enabled, and shall accept the legacy `devServer` flag as an alias for it
gherkin @FR-14MustThe system shall show the Dev Server panel only when the `devServerView` experimental feature flag is enabled, and shall accept the legacy `devServer` flag as an alias for it Scenario: Hide the panel when the flag is off Given the devServerView experimental feature flag is disabled When the right dock entries are computed Then the Dev Server entry is not visible And it is visible when the flag is enabled -
FR-15ShouldThe system shall show the preview in a modal when the right dock that hosts the view is narrower than 480 pixels, keeping the configuration and log panels usable
gherkin @FR-15ShouldThe system shall show the preview in a modal when the right dock that hosts the view is narrower than 480 pixels, keeping the configuration and log panels usable Scenario: Use a modal preview in a narrow dock Given the right dock body that hosts the view is narrower than 480 pixels When the Dev Server view renders Then the inline preview is replaced by an "Open preview" launcher that opens the preview in a modal -
FR-16ShouldThe system shall restore the typed command, the selected script, and the selected task when the Dev Server view remounts, per project
gherkin @FR-16ShouldThe system shall restore the typed command, the selected script, and the selected task when the Dev Server view remounts, per project Scenario: Restore the typed command after a remount Given the operator typed a custom command and selected a script When the Dev Server view unmounts and mounts again for the same project Then the typed command and the selected script are restored -
FR-17ShouldThe system shall poll the dev-server status every 3 seconds while the server is running or starting, and shall suspend that polling while the browser tab is hidden
gherkin @FR-17ShouldThe system shall poll the dev-server status every 3 seconds while the server is running or starting, and shall suspend that polling while the browser tab is hidden Scenario: Poll only while the server runs Given a running dev server When the status poll runs Then the status is fetched every 3 seconds And no poll happens while the server is stopped -
NFR-1MustThe system shall reject a dev-server command that contains command substitution (`$(...)`, backticks, process substitution) or control characters, because the command is spawned with a shell
gherkin @NFR-1MustThe system shall reject a dev-server command that contains command substitution (`$(...)`, backticks, process substitution) or control characters, because the command is spawned with a shell Scenario: Reject command substitution Given a dev-server command of "echo $(whoami)" When the operator starts the dev server Then the start is refused and no child process is spawned -
NFR-2MustThe system shall terminate the whole child process tree on stop, restart, cleanup, and dashboard server shutdown, so no dev-server process outlives the dashboard
gherkin @NFR-2MustThe system shall terminate the whole child process tree on stop, restart, cleanup, and dashboard server shutdown, so no dev-server process outlives the dashboard Scenario: Terminate the process tree on stop Given a running dev server When the operator stops it Then a termination signal is sent to the child's process groupgherkin @NFR-2MustThe system shall terminate the whole child process tree on stop, restart, cleanup, and dashboard server shutdown, so no dev-server process outlives the dashboard Scenario: Stop the servers on dashboard shutdown Given a running dev server When the dashboard HTTPHypertext Transfer Protocol server closes Then the dev server is stopped and cleaned up -
NFR-3MustThe system shall clear the fallback port probe timer on stop, close, failure, restart, and cleanup, so a stopped server leaves no pending timer
gherkin @NFR-3MustThe system shall clear the fallback port probe timer on stop, close, failure, restart, and cleanup, so a stopped server leaves no pending timer Scenario: Clear the probe timer on stop Given a running dev server with a pending fallback probe timer When the operator stops it Then no pending probe timer remains -
NFR-4MustThe system shall release the server-sent events listeners and the heartbeat interval when the client disconnects from the log stream
gherkin @NFR-4MustThe system shall release the server-sent events listeners and the heartbeat interval when the client disconnects from the log stream Scenario: Release the heartbeat on disconnect Given a client subscribed to the log stream When the client disconnects Then the heartbeat interval is cleared -
NFR-5MustThe system shall mark a persisted running or starting server as stopped when its recorded process id is no longer alive, and shall log that recovery
gherkin @NFR-5MustThe system shall mark a persisted running or starting server as stopped when its recorded process id is no longer alive, and shall log that recovery Scenario: Recover a stale persisted process id Given a persisted state with status "running" and a process id that is no longer alive When the store is loaded Then the status becomes "stopped" with exit code 1 And a recovery line is appended to the log history -
NFR-6MustThe system shall ignore late lifecycle callbacks, stale stdout detection, and stale fallback probes from a previous run, so a restart cannot write into the previous run's state
gherkin @NFR-6MustThe system shall ignore late lifecycle callbacks, stale stdout detection, and stale fallback probes from a previous run, so a restart cannot write into the previous run's state Scenario: Ignore late output from the previous run Given a dev server that was restarted When output from the previous process arrives afterwards Then the current run's state and logs are not modified -
NFR-7MustThe system shall never suggest the reserved dashboard port 4040 as a preview port
gherkin @NFR-7MustThe system shall never suggest the reserved dashboard port 4040 as a preview port Scenario: Never suggest the reserved port Given a dev server that prints "listening on port 4040" When the line is parsed Then no preview URL is detected for that port -
NFR-8ShouldThe system shall keep the persisted and in-memory log history bounded to 500 lines
gherkin @NFR-8ShouldThe system shall keep the persisted and in-memory log history bounded to 500 lines Scenario: Bound the log history Given a dev server that has produced more than 500 log lines When the lines are appended Then only the last 500 lines are retained -
NFR-9ShouldThe system shall probe fallback ports sequentially in a fixed order so the first responsive port wins deterministically
gherkin @NFR-9ShouldThe system shall probe fallback ports sequentially in a fixed order so the first responsive port wins deterministically Scenario: Probe ports in a fixed order Given two common local ports are open When the fallback probe runs Then the earlier port in the fixed list is reported -
NFR-10ShouldThe system shall record dev-server lifecycle transitions, the resolved preview URL and port, and the process exit code in the persisted state so an operator can inspect them after the fact
gherkin @NFR-10ShouldThe system shall record dev-server lifecycle transitions, the resolved preview URL and port, and the process exit code in the persisted state so an operator can inspect them after the fact Scenario: Record the lifecycle in the persisted state Given a dev server that was started and later stopped When the persisted state is read Then it carries the start timestamp, the stop timestamp, and the exit code -
NFR-11ShouldThe system shall tolerate a malformed or missing `.fusion/dev-server.json` file by falling back to default state and configuration
gherkin @NFR-11ShouldThe system shall tolerate a malformed or missing `.fusion/dev-server.json` file by falling back to default state and configuration Scenario: Fall back on a corrupt state file Given a .fusion/dev-server.json file that is not valid JSONJavaScript Object Notation When the store is loaded Then the state and the configuration fall back to their defaults -
NFR-12ShouldThe dashboard APIApplication programming interface shall use only the canonical `dev-server-*` module family, and the `devserver-*` family shall stay isolated from the runtime import graph
gherkin @NFR-12ShouldThe dashboard APIApplication programming interface shall use only the canonical `dev-server-*` module family, and the `devserver-*` family shall stay isolated from the runtime import graph Scenario: Keep the canonical family on the runtime path Given the dashboard APIApplication programming interface route registrars When the import graph is inspected Then the dev-server routes resolve only to the dev-server-* module family
Conflicts
None identified yet.
Open Questions
- The dashboard client calls
/api/devserver/*session endpoints first and falls back to/api/dev-server/*, but no/api/devserverrouter is registered in the backend, so the fallback is always taken. The intended owner of the session endpoint family is unresolved. - The client also requests
/api/dev-server/candidatesand/api/dev-server/logs/history, which the canonical router does not serve, so the client falls back to/detectand to the status response. - The disconnected
devserver-*family and thedev-server-manager.tswrapper both carry capabilities the canonical path lacks (event buffering with replay, stale process id recovery). Whether those are ported or dropped is undecided. - The Dev Server view hard-codes its manual-override flag to false, so the preview badge always reads "Auto" even after the operator saves a manual override that the backend does store. Whether the badge should read the backend's manual override is undecided.
Specification: Dev Server Lifecycle Management
Overview
The dev-server feature is a dashboard-owned subsystem in @fusion/dashboard with two layers.
The server layer is the canonical dev-server-* family under packages/dashboard/src: dev-server-detect.ts ranks candidate scripts, dev-server-store.ts persists state and configuration to .fusion/dev-server.json, dev-server-port-detect.ts parses preview URLs and probes fallback ports, dev-server-process.ts owns the child process lifecycle, and dev-server-routes.ts exposes the /api/dev-server/* routes including the server-sent events log stream.
The client layer is the React Dev Server view, lazy-loaded into the right dock behind the devServerView flag, with useDevServer for session and status, useDevServerLogs for paginated live logs, usePreviewEmbed for iframe embed detection, DevServerLogViewer for the log panel, and PreviewIframe for the live preview.
A second module family (devserver-detect.ts, devserver-manager.ts, devserver-persistence.ts, devserver-types.ts) exists in the same package with multi-server session types and a second persistence file, but nothing in the production import graph reaches it.
Architecture
┌──────────────────────────────────────────────┐
Dashboard SPA │ Right dock (overflowViewRegistry) │
(React 19) │ └── DevServerView [devServerView] │
│ ├── DevServerLogViewer │
│ └── PreviewIframe │
│ hooks: useDevServer / useDevServerLogs / │
│ usePreviewEmbed / useDevServerConfig│
└───────────────┬──────────────────────────────┘
│ HTTPHypertext Transfer Protocol + SSEServer-sent events (/api/dev-server/*)
┌───────────────▼──────────────────────────────┐
@fusion/dashboard │ dev-server-routes.ts (createDevServerRouter)
(Express 5) │ GET /detect GET /config PUT /config│
│ GET /status POST /start POST /stop │
│ POST /restart PUT /preview-url │
│ GET /logs/stream (text/event-stream) │
└───────────────┬──────────────────────────────┘
│
┌─────────────────────────┼──────────────────────────┐
│ │ │
┌──────────▼─────────┐ ┌───────────▼───────────┐ ┌──────────▼─────────┐
│ dev-server-detect │ │ dev-server-process │ │ dev-server-store │
│ .ts │ │ .ts │ │ .ts │
│ script ranking │ │ child process, logs, │ │ .fusion/ │
│ (confidence score) │ │ URL detection, stop │ │ dev-server.json │
└──────────┬─────────┘ │ escalation │ └──────────┬─────────┘
│ └───────────┬───────────┘ │
│ │ │
│ ┌───────────▼───────────┐ │
│ │ dev-server-port-detect│ │
│ │ .ts │ │
│ │ Vite/Next/Storybook/ │ │
│ │ Angular parsers, │ │
│ │ fallback port probe │ │
│ └───────────────────────┘ │
│ │
└────────────────┐ ┌────────────────────┘
│ │
┌───────────▼──────────────▼───────────┐
│ @fusion/core superviseSpawn │
│ (detached process group, max 24 h) │
└──────────────────────────────────────┘
Disconnected family (no production importer):
devserver-detect.ts, devserver-manager.ts,
devserver-persistence.ts, devserver-types.ts
-> .fusion/devserver.json, unit tests only
Data Models
DetectedScript
Produced by detectDevServerScripts and returned by GET /api/dev-server/detect.
| Field | Type | Constraints | Description |
|---|---|---|---|
| name | string | not empty, one of DEV_SERVER_SCRIPT_NAMES |
Script name from the manifest, for example dev |
| command | string | not empty | Full command string from the manifest scripts block |
| source | string | root or a project-relative directory path |
Where the manifest was found |
| packageName | string | optional | The name field of the owning manifest |
| confidence | number | 0 to 1 | Rank score from script-name priority, framework dependency indicator, and the private/missing-main heuristic |
DevServerState
The persisted runtime state. Stored under state in .fusion/dev-server.json.
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | string | may be empty | Server entry identifier |
| name | string | defaults to default |
Display name |
| status | string | one of starting, running, stopped, failed |
Current process status, normalized on load |
| command | string | may be empty | Command to execute |
| cwd | string | may be empty | Working directory of the command |
| scriptId | string | optional | Manifest script name the run was started from |
| packagePath | string | optional | Path of the manifest that owns the script |
| pid | number | optional | OS process id while running, cleared on stop and failure |
| startedAt | string | ISO timestamp, optional | When the process started |
| stoppedAt | string | ISO timestamp, optional | When the process stopped |
| exitCode | number | optional | Process exit code |
| detectedUrl | string | optional | Preview URL detected from output or probing |
| manualUrl | string | optional | Operator-set preview URL override |
| detectedPort | number | optional | Port detected from output or probing |
| logHistory | string[] | at most 500 entries, strings only | Ring buffer of recent output lines |
DevServerConfig
The persisted operator configuration. Stored under config in .fusion/dev-server.json.
| Field | Type | Constraints | Description |
|---|---|---|---|
| selectedScript | string | null or non-empty string | Selected script name |
| selectedSource | string | null or non-empty string | Source of the selected script, root or a relative path |
| selectedCommand | string | null or non-empty string | Full command of the selected script |
| previewUrlOverride | string | null or an http:// or https:// URL |
Manual preview URL |
| detectedPreviewUrl | string | null or an http:// or https:// URL |
Last auto-detected preview URL |
| selectedAt | string | null or ISO timestamp | When the selection was made |
DevServerStatusResponse
The body returned by GET /api/dev-server/status. The DevServerState fields plus three resolved fields.
| Field | Type | Constraints | Description |
|---|---|---|---|
| previewUrl | string | null | Manual override when set, otherwise the detected URL |
| detectedPort | number | null | Detected port |
| manualPreviewUrl | string | null | The manual override on its own |
| isRunning | boolean | not null | Whether the manager holds a live child process |
PortDetectionResult
Produced by detectPortFromLogLine and probeFallbackPorts.
| Field | Type | Constraints | Description |
|---|---|---|---|
| url | string | http:// or https://, host localhost or 127.0.0.1 |
Normalized preview URL |
| port | number | 1 to 65535, never 4040 | The preview port |
| source | string | vite, nextjs, storybook, angular, generic-url, generic-port, or fallback-probe |
Which parser or probe produced the result |
DevServerUrlDetectedEvent
The payload of the dev-server:url-detected server-sent event.
| Field | Type | Constraints | Description |
|---|---|---|---|
| url | string | not null | The detected preview URL |
| port | number | not null | The detected preview port |
| source | string | not null | The detection source |
| detectedAt | string | ISO timestamp | When detection happened |
DetectedDevServerCommand (client model)
The fields the dashboard client maps the backend candidates into.
| Field | Type | Constraints | Description |
|---|---|---|---|
| name | string | not null | Script name |
| command | string | not null | Command to run |
| cwd | string | not null, . for the project root |
Working directory to start in |
| scriptName | string | not null | Script name, equal to name |
| packagePath | string | not null | Manifest path, the cwd when the backend omits it |
| framework | string | optional | Framework matched from the command text |
DevServerSession (client model)
The fields the dashboard client uses for a running server. It is produced by mapping the legacy state and is the target of the not-yet-registered /api/devserver session endpoints.
| Field | Type | Constraints | Description |
|---|---|---|---|
| config.id | string | not null | Session identifier, default for the mapped legacy state |
| config.name | string | not null | Session display name |
| config.command | string | not null | Command to run |
| config.cwd | string | not null | Working directory |
| status | string | one of stopped, starting, running, failed, stopping |
Session status |
| runtime.pid | number | optional | OS process id |
| runtime.startedAt | string | ISO timestamp, optional | When the process started |
| runtime.exitCode | number | optional | Process exit code |
| runtime.previewUrl | string | optional | Preview URL known at start time |
| previewUrl | string | optional | Resolved preview URL |
| logHistory | array | at most 500 entries | Log entries with timestamp, stream, and text |
DevServerConfig (secondary family, disconnected)
The config fields of the disconnected devserver-* family, persisted to .fusion/devserver.json.
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | string | branded DevServerId, not null |
Config identifier |
| name | string | not null | Display name |
| command | string | not null | Command to run |
| cwd | string | not null | Working directory |
| env | object | optional, string values only | Extra environment variables |
| autoStart | boolean | optional | Whether the server starts with the dashboard |
APIApplication programming interface Contracts
The normative contract is in api.yaml (OpenAPI 3.1).
The table below is a summary; request and response schemas and error response bodies are in api.yaml.
All routes are mounted under /api/dev-server by the registerIntegratedDevServerRouter registrar.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/dev-server/detect |
List ranked dev-server script candidates for the project |
| GET | /api/dev-server/config |
Read the persisted dev-server configuration |
| PUT | /api/dev-server/config |
Update part of the persisted dev-server configuration |
| GET | /api/dev-server/status |
Read the current dev-server state and resolved preview URL |
| POST | /api/dev-server/start |
Start the dev server in a working directory |
| POST | /api/dev-server/stop |
Stop the running dev server |
| POST | /api/dev-server/restart |
Restart the dev server with the stored command |
| PUT | /api/dev-server/preview-url |
Set or clear the manual preview URL override |
| GET | /api/dev-server/logs/stream |
Stream dev-server output as server-sent events |
Error responses use the shared dashboard error body, { "error": string, "details"?: object }.
The body carries no machine-readable code, so the code column below names the condition.
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_INPUT | A required field is missing, a field has the wrong type, or a URL is not http:// or https:// |
| 409 | CONFLICT | A dev server is already running |
| 500 | INTERNAL_ERROR | The command could not be started, stopped, or restarted |
The client additionally calls /api/devserver, /api/devserver/:id, /api/devserver/:id/start, /api/devserver/:id/stop, /api/devserver/:id/restart, /api/devserver/:id/logs, /api/devserver/:id/preview, /api/devserver/detect, /api/devserver/:id/logs/stream, /api/dev-server/candidates, and /api/dev-server/logs/history.
No router serves those paths today, so the client falls back to the canonical /api/dev-server/* routes.
Sequences
Detect
Client Routes dev-server-detect Manifests
| | | |
| GET /detect | | |
|--------------------->| | |
| | detectDevServerScripts | |
| |------------------------->| |
| | | read package.json |
| | |--------------------->|
| | |<-- root scripts ----|
| | | |
| | | glob packages/* |
| | | and apps/* |
| | |--------------------->|
| | |<-- workspace pkgs --|
| | | |
| | | score each script |
| | | (priority + |
| | | framework + |
| | | private heuristic) |
| | | sort by confidence |
| |<----- candidates --------| |
| | | |
|<-- { candidates } ---| | |
Start
Client Routes Process manager Store Child
| | | | |
| POST /start | | | |
|------------>| | | |
| | validate command | | |
| | and cwd | | |
| | reject $() ` <() | | |
| | reject control ch | | |
| | | | |
| | check isRunning -> 409 conflict | |
| | | | |
| | manager.start() | | |
| |------------------->| | |
| | | state = starting | |
| | |---------------->| |
| | | | |
| | | superviseSpawn (shell: true) |
| | |--------------------------------->|
| | | | pid, status = running
| | |---------------->| |
| | | emit "started" | |
| |<------- state -----| | |
|<-- 200 state| | | |
| | | | |
| | |<---- stdout ----| |
| | | appendLog(line) | |
| | |---------------->| |
| | | detectPortFromLogLine(line) |
| | | -> detectedUrl, detectedPort |
| | |---------------->| |
| | | emit "url-detected" |
| | | | |
| | | (after grace period, if no URL) |
| | | probeFallbackPorts() |
| | |---------------->| |
Stop
Client Routes Process manager Store Child
| | | | |
| POST /stop | | | |
|------------->| | | |
| | if not running: | | |
| | return state | | |
| |<-- 200 state -----| | |
| | | | |
| | manager.stop() | | |
| |------------------->| | |
| | | SIGTERM to the process group |
| | |-------------------------------->|
| | | | |
| | | (stop timeout, 5 s) |
| | | SIGKILL to the process group |
| | |-------------------------------->|
| | | await close event |
| | |<--------------------------------|
| | | clear probe timer |
| | | state = stopped, exitCode, |
| | | stoppedAt, pid cleared |
| | |---------------->| |
| | | emit "stopped" | |
| |<------- state -----| | |
|<-- 200 state| | | |
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Canonical module family | The hyphenated dev-server-* family |
It is the only family on the production import graph, mounted by registerIntegratedDevServerRouter and torn down by stopAllDevServers in packages/dashboard/src/server.ts |
| Persistence file | .fusion/dev-server.json with a { state, config } payload |
It is the file the canonical store writes and the only one the dashboard reads back |
| Child process launch | superviseSpawn with shell: true and a 24 hour maximum lifetime |
The supervisor creates a detached process group, so a stop can tear down the shell wrapper and its descendants, and the lifetime caps a forgotten server |
| Command validation | Reject command substitution and control characters before spawning | The command is a project setting spawned through a shell, so substitution is the main payload of a settings-file compromise |
| Stop escalation | SIGTERM to the process group, then SIGKILL after 5 seconds |
A dev server spawns grandchildren, so a single PID signal would leave the tree running |
| Preview URL discovery | Framework parsers first, generic parsers second, TCP probe last | Framework output is the most reliable source, the probe covers servers that print nothing |
| Reserved port | 4040 excluded from every detected and probed port | The dashboard itself serves on 4040 |
| Log history bound | 500 lines in the store and 500 entries in the client | Keeps the persisted file and the rendered panel bounded |
| Log transport | Server-sent events on GET /logs/stream with a 30 second heartbeat |
The dashboard already uses server-sent events, and a long-lived HTTPHypertext Transfer Protocol stream avoids a polling loop |
| View placement | Right dock, lazy-loaded, gated by devServerView |
Keeps the panel out of the main bundle and out of the way when the operator does not want it |
| Narrow dock preview | A modal launcher below 480 pixels of dock width | The inline preview crowds the configuration and log panels in a narrow dock |
| Preview sandbox | allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox |
The preview renders a developer-controlled local app, and the fallback path lets the operator open it outside the frame |
Risks and Unknowns
- The client calls
/api/devserver/*and/api/dev-server/candidatesand/api/dev-server/logs/history, which no backend route serves. The client always takes its fallback path, so the intended owner of the session endpoint family is unresolved. - The
devserver-*family anddev-server-manager.tsboth carry capabilities the canonical path lacks, namely event buffering with replay and stale process id recovery. A fix can land in the wrong family and miss production. - The two families write two different files,
.fusion/dev-server.jsonand.fusion/devserver.json, and they can drift. - The dev-server command is spawned with a shell, so a command with
&&or a pipe is accepted, and the command substitution guard is a pattern check rather than a parser. - The preview iframe runs a developer-controlled local app with
allow-same-origin, so a hostile page served on the preview origin could reach the dashboard origin. The blast radius is limited to a local development port. - The status response resolves the preview URL from the manual override, so a stale override can shadow a freshly detected URL until the operator clears it.
- The Dev Server view hard-codes its manual-override flag to false, so the preview badge reports "Auto" even when the backend holds a manual override.
Out of Scope
- Multi-server dev-server sessions. The
devserver-*family models them but is not wired to the runtime. - The engine mission verification app harness and the CLICommand-line interface dev-source restart command, which reuse the port-detection rules for their own purposes.
- A non-shell dev-server launcher, and any port other than 4040 being reserved.
- The preview embed restrictions of a specific framework, which the embed detector only reports.
Test Plan: Dev Server Lifecycle Management
Scope
This plan covers the dev-server subsystem in @fusion/dashboard: script detection, the persisted store, preview-URL detection and port probing, the child-process lifecycle, the /api/dev-server/* routes, the disconnected devserver-* family, and the dashboard Dev Server view with its log viewer, preview iframe, and hooks.
Out of scope: - The engine mission verification app harness and the CLICommand-line interface dev-source restart command, which reuse the port-detection rules for their own purposes. - The right-dock placement of the view, which is covered by the dock and navigation tests.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Detect scripts in the root manifest and rank them | A root package.json with dev and serve scripts |
Both candidates returned, dev ranked above serve |
| TC-2 | Scan workspace manifests | packages/*/package.json and apps/*/package.json |
WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop candidates returned with their relative source path |
| TC-3 | Score candidates | A manifest with a framework dependency, and one that is private or has no main |
The framework and private heuristics raise the confidence score |
| TC-4 | Tolerate a malformed manifest | A package.json that is not valid JSONJavaScript Object Notation |
Empty candidate list, no throw |
| TC-5 | Read and write the persisted state | A state and a config written to .fusion/dev-server.json |
Both round-trip through the store |
| TC-6 | Normalize a corrupt state file | A .fusion/dev-server.json that is not valid JSONJavaScript Object Notation |
Default state and default config, no throw |
| TC-7 | Bound the persisted log history | More than 500 appended lines | The history holds the last 500 lines |
| TC-8 | Survive a removed project directory | A save after the project directory was deleted | The save is a no-op, no throw |
| TC-9 | Parse a Vite URL line | A Local: http://localhost:5173 line |
The URL and port 5173 are detected, source vite |
| TC-10 | Parse Next.js, Storybook, and Angular lines | The startup lines of each framework | The URL and port are detected, source nextjs, storybook, or angular |
| TC-11 | Parse a generic URL line and a keyword-plus-port line | A plain http://127.0.0.1:3000 line and a listening on port 4321 line |
Both are detected, source generic-url and generic-port |
| TC-12 | Strip ANSI codes and skip inspector lines | A colored URL line and a Node inspector line | The colored line is detected, the inspector line is ignored |
| TC-13 | Exclude the reserved port | A line announcing port 4040 | No preview URL is detected |
| TC-14 | Search the logs from newest to oldest | A list of log lines | The newest matching line wins |
| TC-15 | Probe fallback ports in order | Two open common ports | The earlier port in the fixed list is reported, source fallback-probe |
| TC-16 | Reject an unsafe start command | A command containing $(...) |
The start is refused before a child is spawned |
| TC-17 | Refuse a duplicate start | A manager that already holds a running child | The start throws and no second child is spawned |
| TC-18 | Start, persist output, and detect the announced URL | An injected child that writes a URL line | The state moves to running, the line is persisted, and the URL is detected once |
| TC-19 | Stop through the process-tree signal | An injected child and an injected kill function | The termination signal is sent and the fallback probe timer is cleared |
| TC-20 | Escalate to the kill signal | A child that ignores the termination signal | The kill signal is sent after the stop timeout |
| TC-21 | Clean up on failure and restart | A child that emits an error | The state is failed, the timer is cleared, and a restart produces a fresh child |
| TC-22 | Reconcile a stale persisted process id | A persisted running state whose process id is not alive |
The state becomes stopped with exit code 1 and a recovery line is appended |
| TC-23 | Rehydrate the persisted state and logs | A persisted state and log history | The snapshot carries the state and the restored logs |
| TC-24 | Detect the preview URL from a session log | A session whose child writes http://localhost:3000 |
The session carries the detected preview URL |
| TC-25 | Probe a fallback port in a session | A session with no announced URL and an open common port | The session preview URL points at the open port |
| TC-26 | Keep the manual override and the detected fields apart | A session with both a manual URL and a detected URL | The manual URL stays effective while the detected fields keep updating |
| TC-91 | Brand the session id | A plain string | The branded id is a string and equals the input |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-27 | Serve the detected candidates | A router mounted on a temporary project root | GET /api/dev-server/detect returns 200 with a candidates array |
| TC-28 | Serve the default config | A project root with no config file | GET /api/dev-server/config returns 200 with all fields null |
| TC-29 | Store a config update | A router on a project root | PUT /api/dev-server/config returns 200 and the stored values are read back |
| TC-30 | Reject an invalid config update | An empty body, and a previewUrlOverride that is not a URL |
Both return 400 |
| TC-31 | Serve the default status | A router on an empty project root | GET /api/dev-server/status returns 200 with status stopped, previewUrl null, detectedPort null, manualPreviewUrl null, and isRunning false |
| TC-32 | Resolve the preview URL in the status response | A store with a detected URL, a detected port, and a manual URL | The manual URL is the resolved previewUrl, and the detected port is reported |
| TC-33 | Fall back to the detected URL | A store with a detected URL and no manual URL | The detected URL is the resolved previewUrl |
| TC-34 | Start through the route | A router and a long-lived command | POST /api/dev-server/start returns 200 with status running and the requested working directory |
| TC-35 | Reject an invalid start | A start request without a command, and one without a working directory | Both return 400 |
| TC-36 | Refuse a concurrent start | A running dev server | The second POST /api/dev-server/start returns 409 |
| TC-37 | Stop through the route | A running dev server | POST /api/dev-server/stop returns 200 with status stopped |
| TC-38 | Keep stop idempotent | No running dev server | POST /api/dev-server/stop returns 200 with the unchanged state |
| TC-39 | Restart through the route | A dev server started with a command, a working directory, and a script id | POST /api/dev-server/restart returns 200 with the same command and script id |
| TC-40 | Refuse a restart with no stored command | No stored command | POST /api/dev-server/restart returns 400 |
| TC-41 | Set and clear the preview override | A router on a project root | PUT /api/dev-server/preview-url stores the manual URL, and an empty URL clears it |
| TC-42 | Reject a malformed preview URL | A URL of localhost:5173 |
PUT /api/dev-server/preview-url returns 400 |
| TC-43 | Open the log stream | A client subscribed to the stream | The response carries the text/event-stream content type, a : connected comment, and a history event with the stored lines |
| TC-44 | Forward live output | A subscribed client and a manager that emits an output event | The stream carries a log event with the line |
| TC-45 | Forward the URL-detected event | A subscribed client and a manager that emits a url-detected event | The stream carries a dev-server:url-detected event whose payload has exactly url, port, source, and detectedAt |
| TC-46 | Release the stream listeners | A subscribed client that disconnects | The manager listener count for output and url-detected returns to zero |
| TC-47 | Load the Dev Server view | A view with detected candidates | The candidate buttons render, and the no-candidates message renders when the list is empty |
| TC-48 | Drive the lifecycle from the view | A stopped server | Start, stop, and restart each call the matching hook action, and the start button is disabled while running |
| TC-49 | Select a candidate | A candidate click | The selected-script summary renders and the candidate list can be re-shown |
| TC-50 | Save the preview URL override | The preview URL input | The saved value is sent to the preview URL action |
| TC-51 | Target a task worktree | One task in a work-in-progress column with a worktree and one without | Only the task with a worktree is listed, and starting the server runs in that worktree |
| TC-52 | Guide the operator on a task switch | A running server | Switching the selected task shows the restart guidance message |
| TC-53 | Restore the typed command after a remount | An unmount and remount of the view | The typed command and the selected script are restored |
| TC-54 | Render the narrow dock preview launcher | A dock host narrower than 480 pixels | The inline preview is replaced by the launcher, and a true mobile viewport keeps the inline preview |
| TC-55 | Report the embed states | A preview URL | The states are loading, embedded, blocked, and error, and the blocked and error states offer open-in-new-tab and retry |
| TC-56 | Refresh the preview | A preview URL | The refresh action resets the embed state, and the fallback clears when the embed succeeds after a retry |
| TC-57 | Render the log viewer | A set of log entries | The entries, the timestamps, and the stderr badge render, the ANSI codes are stripped, the severity filter and the search work, the load-more button fires, and the fullscreen class toggles |
| TC-58 | Follow the log stream | New entries arriving while pinned | The view scrolls to the bottom while pinned, and the jump-to-latest action re-pins |
| TC-59 | Load and stream logs | The logs hook enabled for a project | The initial history loads, live entries append, entries deduplicate by id, the history caps at the maximum, and load-more fetches older entries |
| TC-60 | Reopen the log subscription on a project change | A project id change | The entries clear and a new subscription opens |
| TC-61 | Catch up after a reconnect | A reconnect event with the last seen event id | The hook fetches the entries after the last seen id |
| TC-62 | Instrument the log stream lifecycle | An open and a reconnect | Resume instrumentation records the stream open and the reconnect with the replay event id |
| TC-63 | Poll the session status | A running server | The status is fetched on a 3 second interval, and no poll runs while the server is stopped |
| TC-64 | Apply the session events | A dev-server:status event |
The session status and process id update |
| TC-65 | Clean up on unmount | An unmounted view | The server-sent events subscription is released |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-66 | The project has no package.json |
Detection returns an empty candidate list, and the view shows the no-candidates message |
| TC-67 | The project has no matching script name | Detection returns an empty candidate list |
| TC-68 | A workspace manifest is unreadable | That manifest is skipped and the other candidates are still returned |
| TC-69 | The state file holds an unknown status value | The status normalizes back to stopped |
| TC-70 | The state file holds a non-string log entry | The entry is filtered out of the history |
| TC-71 | The command is empty after trimming | The start is refused with 400 |
| TC-72 | The command contains command substitution | The start is refused before a child process is spawned |
| TC-92 | The command contains a backtick or a control character | The start is refused before a child process is spawned. No test covers these two guard branches today. |
| TC-73 | The child writes a line after the server was stopped | The late line does not reach the current state or the current log history |
| TC-74 | The fallback probe resolves after a stop | The probe does not write a detected URL into the stopped state |
| TC-75 | The detected URL write fails | The detection flag is reset so a later detection can run |
| TC-76 | The dev server prints an inspector line with a loopback URL | The line is not treated as a preview URL |
| TC-77 | The dev server prints a URL on a host other than localhost or 127.0.0.1 | The URL is not treated as a preview URL |
| TC-78 | The dev server prints a URL on a port above 65535 or 0 | The URL is not treated as a preview URL |
| TC-79 | No fallback port is open | The probe returns no result and the state keeps a null detected URL |
| TC-80 | The preview URL does not start with http:// or https:// | The preview URL update is refused with 400 |
| TC-81 | The preview URL is set to an empty string | The manual override is cleared and the detected URL becomes effective again |
| TC-82 | The config update body is not a JSONJavaScript Object Notation object | The update is refused with 400 |
| TC-83 | The config update body carries no known field | The update is refused with 400 |
| TC-84 | The client disconnects from the log stream | The heartbeat interval is cleared and the manager listeners are removed |
| TC-85 | The child process is killed externally | The close handler moves the state to stopped and records the exit code |
| TC-86 | The dashboard server shuts down | The running dev servers are stopped and cleaned up |
| TC-87 | The Dev Server view is hosted in a narrow right dock | The preview moves into a modal and the configuration and log panels stay usable |
| TC-88 | The browser tab is hidden while the server runs | The status polling is suspended and the view refreshes once when the tab becomes visible again |
| TC-89 | The operator selects a different task while the server runs | The view shows the restart guidance instead of silently changing the target |
| TC-90 | The selected task leaves the work-in-progress list | The selection is cleared |
Test Infrastructure
- The backend route tests build an Express app in-process with
express.json()and mount the router at/api/dev-server, then drive it with therequesthelper frompackages/dashboard/src/test-request.ts. - The server-sent events tests use a mock socket over
http.IncomingMessageandhttp.ServerResponseto capture the written chunks. - The process tests inject a fake child process through the
spawnandkillManagedProcessoptions, so no shell child runs. - The store tests use a temporary project root created with
mkdtempSyncunder the OS temp directory and removed inafterEach. - The port-probe tests stub the
node:netconnection to control which ports answer. - The frontend tests use Vitest with the React Testing Library, and stub the APIApplication programming interface client and the server-sent events bus.
- The narrow-dock tests drive the host width through a mocked
ResizeObserverandmatchMedia.
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall detect candidate dev-server scripts from the project root `package.json` and from workspace `packages/*` and `apps/*` manifests, and rank them by a confidence score derived from script-name priority, framework dependency indicators, and the `private`/missing-`main` heuristic | TC-1, TC-2, TC-3, TC-4, TC-27, TC-66, TC-67, TC-68 |
| FR-2MustThe system shall expose the detected candidates over `GET /api/dev-server/detect`, read the persisted selection with `GET /api/dev-server/config`, and update the selected script, source, command, and preview URL override with `PUT /api/dev-server/config` | TC-28, TC-29, TC-30, TC-82, TC-83, TC-47, TC-49 |
| FR-3MustThe system shall start the dev server with `POST /api/dev-server/start`, spawning the command with a shell in the requested working directory, and shall reject the request with `400` when `command` or `cwd` is missing and with `409` when a server is already running | TC-17, TC-34, TC-35, TC-36, TC-48, TC-71 |
| FR-4MustThe system shall stop the dev server with `POST /api/dev-server/stop` by sending `SIGTERM` to the process group and escalating to `SIGKILL` after the stop timeout, and shall restart it with `POST /api/dev-server/restart` using the stored command and working directory | TC-37, TC-38, TC-39, TC-40, TC-48 |
| FR-5MustThe system shall report the current dev-server state over `GET /api/dev-server/status`, including status, command, working directory, process id, timestamps, exit code, the detected preview URL and port, the manual preview URL override, the resolved preview URL, and whether the process is running | TC-31, TC-32, TC-33, TC-63, TC-64 |
| FR-6MustThe system shall persist the dev-server state and configuration to `.fusion/dev-server.json` in the project directory, and shall restore that state on load, capping the stored log history at 500 lines | TC-5, TC-6, TC-7, TC-8, TC-69, TC-70, TC-22, TC-23 |
| FR-7MustThe system shall stream dev-server output to the dashboard over the `GET /api/dev-server/logs/stream` server-sent events endpoint, sending the stored history first and then live `log`, `stopped`, `failed`, and `dev-server:url-detected` events, with a heartbeat comment every 30 seconds | TC-43, TC-44, TC-45, TC-46, TC-59, TC-60, TC-61, TC-62, TC-65 |
| FR-8MustThe system shall detect the app's local preview URL from the process output, first by parsing framework-specific patterns (Vite, Next.js, Storybook, Angular) and then generic URL and keyword-plus-port patterns, and shall fall back to probing a fixed list of common local ports when no URL is announced | TC-9, TC-10, TC-11, TC-12, TC-13, TC-14, TC-15, TC-24, TC-25, TC-26, TC-76, TC-77, TC-78, TC-79 |
| FR-9MustThe system shall let the operator override the preview URL with `PUT /api/dev-server/preview-url`, accepting only `http://` or `https://` URLs and clearing the override when the URL is empty | TC-41, TC-42, TC-50, TC-80, TC-81 |
| FR-10MustThe system shall render a Dev Server view in the dashboard that lists detected candidates, shows a status badge, starts, stops, and restarts the server, shows the running command, and exposes the preview URL override field | TC-47, TC-48, TC-49, TC-50 |
| FR-11MustThe system shall let the operator point the dev server at the worktree of an executing task, listing only tasks in a work-in-progress column that have a worktree path, and using that worktree as the working directory of the started process | TC-51, TC-52, TC-89, TC-90 |
| FR-12MustThe system shall embed the running app in an iframe preview that reports a loading, embedded, blocked, or error state, and shall offer an open-in-new-tab fallback when the app cannot be embedded | TC-55, TC-56 |
| FR-13MustThe system shall show the dev-server output in a log panel that strips ANSI escape codes, filters by severity, searches the text, loads older lines, and can toggle fullscreen | TC-57, TC-58 |
| FR-14MustThe system shall show the Dev Server panel only when the `devServerView` experimental feature flag is enabled, and shall accept the legacy `devServer` flag as an alias for it | TC-47 |
| FR-15ShouldThe system shall show the preview in a modal when the right dock that hosts the view is narrower than 480 pixels, keeping the configuration and log panels usable | TC-54, TC-87 |
| FR-16ShouldThe system shall restore the typed command, the selected script, and the selected task when the Dev Server view remounts, per project | TC-53 |
| FR-17ShouldThe system shall poll the dev-server status every 3 seconds while the server is running or starting, and shall suspend that polling while the browser tab is hidden | TC-63, TC-88 |
| NFR-1MustThe system shall reject a dev-server command that contains command substitution (`$(...)`, backticks, process substitution) or control characters, because the command is spawned with a shell | TC-16, TC-72, TC-92 |
| NFR-2MustThe system shall terminate the whole child process tree on stop, restart, cleanup, and dashboard server shutdown, so no dev-server process outlives the dashboard | TC-19, TC-20, TC-86 |
| NFR-3MustThe system shall clear the fallback port probe timer on stop, close, failure, restart, and cleanup, so a stopped server leaves no pending timer | TC-19, TC-21, TC-74 |
| NFR-4MustThe system shall release the server-sent events listeners and the heartbeat interval when the client disconnects from the log stream | TC-46, TC-84 |
| NFR-5MustThe system shall mark a persisted running or starting server as stopped when its recorded process id is no longer alive, and shall log that recovery | TC-22 |
| NFR-6MustThe system shall ignore late lifecycle callbacks, stale stdout detection, and stale fallback probes from a previous run, so a restart cannot write into the previous run's state | TC-73, TC-74, TC-75, TC-85 |
| NFR-7MustThe system shall never suggest the reserved dashboard port 4040 as a preview port | TC-13 |
| NFR-8ShouldThe system shall keep the persisted and in-memory log history bounded to 500 lines | TC-7, TC-59 |
| NFR-9ShouldThe system shall probe fallback ports sequentially in a fixed order so the first responsive port wins deterministically | TC-15, TC-25 |
| NFR-10ShouldThe system shall record dev-server lifecycle transitions, the resolved preview URL and port, and the process exit code in the persisted state so an operator can inspect them after the fact | TC-5, TC-18, TC-22, TC-23, TC-31 |
| NFR-11ShouldThe system shall tolerate a malformed or missing `.fusion/dev-server.json` file by falling back to default state and configuration | TC-6, TC-69, TC-70 |
| NFR-12ShouldThe dashboard APIApplication programming interface shall use only the canonical `dev-server-*` module family, and the `devserver-*` family shall stay isolated from the runtime import graph | TC-1, TC-2, TC-3, TC-4, TC-24, TC-25, TC-91 |
No automated guard asserts the import-graph boundary, so NFR-12ShouldThe dashboard APIApplication programming interface shall use only the canonical `dev-server-*` module family, and the `devserver-*` family shall stay isolated from the runtime import graph rests on the disconnected family's unit tests plus review.
Key Test Files
Backend, canonical family:
packages/dashboard/src/__tests__/dev-server-detect.test.tspackages/dashboard/src/__tests__/dev-server-store.test.tspackages/dashboard/src/__tests__/dev-server-port-detect.test.tspackages/dashboard/src/__tests__/dev-server-process.test.tspackages/dashboard/src/__tests__/dev-server-manager.test.tspackages/dashboard/src/__tests__/dev-server-manager-persistence.test.tspackages/dashboard/src/__tests__/dev-server-routes.test.tspackages/dashboard/src/__tests__/dev-server-config-routes.test.ts
Backend, disconnected family:
packages/dashboard/src/__tests__/devserver-types.test.tspackages/dashboard/src/__tests__/devserver-detect.test.tspackages/dashboard/src/__tests__/devserver-persistence.test.tspackages/dashboard/src/__tests__/devserver-manager.test.tspackages/dashboard/src/__tests__/devserver-preview-detect.test.ts
Frontend:
packages/dashboard/app/components/__tests__/DevServerView.test.tsxpackages/dashboard/app/components/__tests__/DevServerView.preview.test.tsxpackages/dashboard/app/components/__tests__/DevServerLogViewer.test.tsxpackages/dashboard/app/components/__tests__/PreviewIframe.test.tsxpackages/dashboard/app/hooks/__tests__/useDevServer.test.tspackages/dashboard/app/hooks/__tests__/useDevServerLogs.test.tspackages/dashboard/app/hooks/__tests__/useDevServerLogs.resume-instrumentation.test.ts
requirements
- The dashboard client calls
/api/devserver/*session endpoints first and falls back to/api/dev-server/*, but no/api/devserverrouter is registered in the backend, so the fallback is always taken. The intended owner of the session endpoint family is unresolved. - The client also requests
/api/dev-server/candidatesand/api/dev-server/logs/history, which the canonical router does not serve, so the client falls back to/detectand to the status response. - The disconnected
devserver-*family and thedev-server-manager.tswrapper both carry capabilities the canonical path lacks (event buffering with replay, stale process id recovery). Whether those are ported or dropped is undecided. - The Dev Server view hard-codes its manual-override flag to false, so the preview badge always reads "Auto" even after the operator saves a manual override that the backend does store. Whether the badge should read the backend's manual override is undecided.
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Computer Use: Desktop GUI Automation
Overview
fn computer lets an agent inspect and operate local desktop application windows through a strict snapshot, act, snapshot loop.
The CLICommand-line interface captures the accessibility tree of a window, persists it as a snapshot, performs one deliberate action bound to that snapshot, and then requires a fresh capture before the next action.
Every element action is fenced by a snapshot, so an agent cannot act on a window state it never observed.
The surface is macOS-only today and returns an explicit unsupported-platform error elsewhere.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Solo developer | Drives a desktop application from an agent session without clicking through the GUI by hand |
| Agent author | Needs one command surface with a stable JSONJavaScript Object Notation contract so an agent can read the window state and act on it safely |
| Operator / power user | Needs the automation to fail closed when a window changed, so a stale plan cannot damage the machine |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall expose `fn computer` with the twelve subcommands `capabilities`, `permissions`, `list-apps`, `list-windows`, `get-app-state`, `click`, `set-value`, `type-text`, `press-key`, `hotkey`, `scroll`, and `drag` | Must | The system shall expose fn computer with the twelve subcommands capabilities, permissions, list-apps, list-windows, get-app-state, click, set-value, type-text, press-key, hotkey, scroll, and drag |
| FR-2MustThe system shall capture the accessibility tree of a target app window in `get-app-state` and persist a snapshot record under the resolved project root before returning its snapshot id | Must | The system shall capture the accessibility tree of a target app window in get-app-state and persist a snapshot record under the resolved project root before returning its snapshot id |
| FR-3MustThe system shall resolve every element-bound action through a snapshot record, and shall refuse the action with `SNAPSHOT_REQUIRED` when the target app has no snapshot | Must | The system shall resolve every element-bound action through a snapshot record, and shall refuse the action with SNAPSHOT_REQUIRED when the target app has no snapshot |
| FR-4MustThe system shall consume the app's latest snapshot pointer after a successful action, so the next element action fails with `SNAPSHOT_STALE` and reason `consumed-by-action` until a new capture re-arms the pointer | Must | The system shall consume the app's latest snapshot pointer after a successful action, so the next element action fails with SNAPSHOT_STALE and reason consumed-by-action until a new capture re-arms the pointer |
| FR-5MustThe system shall re-resolve the recorded window and replay the recorded accessibility locator before an action, and shall fail with `ELEMENT_UNRESOLVABLE` when the path no longer resolves or the role, subrole, or identifier no longer match | Must | The system shall re-resolve the recorded window and replay the recorded accessibility locator before an action, and shall fail with ELEMENT_UNRESOLVABLE when the path no longer resolves or the role, subrole, or identifier no longer match |
| FR-6MustThe system shall refuse an unusable snapshot and report exactly one reason from the fixed set `not-found`, `superseded`, `expired`, `pid-changed`, `window-mismatch`, `window-gone`, `consumed-by-action` | Must | The system shall refuse an unusable snapshot and report exactly one reason from the fixed set not-found, superseded, expired, pid-changed, window-mismatch, window-gone, consumed-by-action |
| FR-7MustThe system shall store element indexes as a sparse map keyed by the index emitted during capture, and shall fail with `ELEMENT_INDEX_NOT_FOUND` when the requested index is absent from that map | Must | The system shall store element indexes as a sparse map keyed by the index emitted during capture, and shall fail with ELEMENT_INDEX_NOT_FOUND when the requested index is absent from that map |
| FR-8MustThe system shall resolve an app target as an exact bundle id, then an exact unambiguous app name, then a `pid:` prefix with the numeric process id, and shall fail with `APP_NOT_FOUND` or `AMBIGUOUS_APP` | Must | The system shall resolve an app target as an exact bundle id, then an exact unambiguous app name, then a pid: prefix with the numeric process id, and shall fail with APP_NOT_FOUND or AMBIGUOUS_APP |
| FR-9MustThe system shall report Accessibility and Screen Recording permission state as `granted`, `denied`, or `unknown` from non-mutating preflights, and shall never report a grant it did not probe | Must | The system shall report Accessibility and Screen Recording permission state as granted, denied, or unknown from non-mutating preflights, and shall never report a grant it did not probe |
| FR-10MustThe system shall report `supported: false` from `capabilities` and `permissions` on a platform other than macOS, and shall fail every other subcommand there with `UNSUPPORTED_PLATFORM` | Must | The system shall report supported: false from capabilities and permissions on a platform other than macOS, and shall fail every other subcommand there with UNSUPPORTED_PLATFORM |
| FR-11MustThe system shall emit one envelope per invocation carrying `schemaVersion` 1, `ok`, `command`, and either `result` or `error`, and shall exit 0 on success and 1 on failure | Must | The system shall emit one envelope per invocation carrying schemaVersion 1, ok, command, and either result or error, and shall exit 0 on success and 1 on failure |
| FR-12MustThe system shall read a value from stdin when `--value-stdin` or `--text-stdin` is used, and shall not place that value in process arguments | Must | The system shall read a value from stdin when --value-stdin or --text-stdin is used, and shall not place that value in process arguments |
| FR-13ShouldThe system shall capture the selected window as a screenshot stored under the project root and report the file path, and shall report a screenshot failure as `screenshotError` without discarding the captured accessibility tree | Should | The system shall capture the selected window as a screenshot stored under the project root and report the file path, and shall report a screenshot failure as screenshotError without discarding the captured accessibility tree |
| FR-14ShouldThe system shall select a window with `--window-id` or `--window-index`, refuse both together, and restore a minimized window when `--restore-window` is passed to `get-app-state` | Should | The system shall select a window with --window-id or --window-index, refuse both together, and restore a minimized window when --restore-window is passed to get-app-state |
| FR-15ShouldThe system shall support a coordinate drag form and an element drag form as mutually exclusive forms, and shall support targetless `type-text`, `press-key`, and `scroll` that act on the focused element of the target app | Should | The system shall support a coordinate drag form and an element drag form as mutually exclusive forms, and shall support targetless type-text, press-key, and scroll that act on the focused element of the target app |
| FR-16ShouldThe system shall render the full command guide from the binary through `fn skills get computer-use`, and the shipped `computer-use` discovery skill shall carry no static command or flag list | Should | The system shall render the full command guide from the binary through fn skills get computer-use, and the shipped computer-use discovery skill shall carry no static command or flag list |
| FR-17ShouldThe system shall report capabilities as the platform, the adapter id, the supported flag, the action inventory split into supported and unsupported actions, and the feature flags for screenshot, restore-window, stdin secrets, and cross-invocation snapshots | Should | The system shall report capabilities as the platform, the adapter id, the supported flag, the action inventory split into supported and unsupported actions, and the feature flags for screenshot, restore-window, stdin secrets, and cross-invocation snapshots |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustThe system shall never act on an element it did not observe, so every element action re-resolves the window and the locator and verifies identity before the operating-system call | Must | Safety | The system shall never act on an element it did not observe, so every element action re-resolves the window and the locator and verifies identity before the operating-system call |
| NFR-2MustThe system shall keep a secret value out of process arguments, out of the snapshot record the command writes, out of error messages, and out of the JSONJavaScript Object Notation envelope | Must | Security | The system shall keep a secret value out of process arguments, out of the snapshot record the command writes, out of error messages, and out of the JSONJavaScript Object Notation envelope |
| NFR-3MustThe system shall keep the operating-system automation program static, and shall pass untrusted app names, window ids, and locator paths as arguments or stdin instead of interpolating them into the program source | Must | Security | The system shall keep the operating-system automation program static, and shall pass untrusted app names, window ids, and locator paths as arguments or stdin instead of interpolating them into the program source |
| NFR-4MustThe system shall run on macOS only, using the operating-system `osascript` and `screencapture` built-ins, with no downloaded helper, native module, or automation dependency | Must | Portability | The system shall run on macOS only, using the operating-system osascript and screencapture built-ins, with no downloaded helper, native module, or automation dependency |
| NFR-5MustThe system shall emit exactly one error per invocation, let the first failing stage win, and order the stages as group routing, flag parsing, platform resolution, action support, built-in and permission gate, stdin read, app resolution, supplied-window resolution, snapshot resolution, sparse element lookup, window and locator replay, then the operating-system call | Must | Error contract | The system shall emit exactly one error per invocation, let the first failing stage win, and order the stages as group routing, flag parsing, platform resolution, action support, built-in and permission gate, stdin read, app resolution, supplied-window resolution, snapshot resolution, sparse element lookup, window and locator replay, then the operating-system call |
| NFR-6MustThe system shall bound every operating-system command with a fixed timeout of 5 seconds for the permission probe, 10 seconds for discovery, 20 seconds for state capture, 15 seconds for a screenshot, 10 seconds for locator replay, and 10 seconds for an action, and shall offer no user-configurable timeout flag | Must | Availability | The system shall bound every operating-system command with a fixed timeout of 5 seconds for the permission probe, 10 seconds for discovery, 20 seconds for state capture, 15 seconds for a screenshot, 10 seconds for locator replay, and 10 seconds for an action, and shall offer no user-configurable timeout flag |
| NFR-7MustThe system shall change `schemaVersion` and the error code list only for a breaking reshape, and shall add error codes without removing or renaming existing ones | Must | Compatibility | The system shall change schemaVersion and the error code list only for a breaking reshape, and shall add error codes without removing or renaming existing ones |
| NFR-8ShouldThe system shall keep snapshots, latest pointers, and screenshots under the resolved Fusion project root, so state is not shared across projects and a capture from one directory is visible to a later invocation from another directory in the same project | Should | Isolation | The system shall keep snapshots, latest pointers, and screenshots under the resolved Fusion project root, so state is not shared across projects and a capture from one directory is visible to a later invocation from another directory in the same project |
| NFR-9ShouldThe system shall serialize concurrent CLICommand-line interface processes on a per-app lock, so a capture cannot be lost and a stale action cannot consume a newer capture | Should | Concurrency | The system shall serialize concurrent CLICommand-line interface processes on a per-app lock, so a capture cannot be lost and a stale action cannot consume a newer capture |
| NFR-10ShouldThe system shall check the command surface descriptor, the parser flag literals, the emitted error codes, and the rendered guide against each other, so the shipped guide cannot drift from the binary | Should | Maintainability | The system shall check the command surface descriptor, the parser flag literals, the emitted error codes, and the rendered guide against each other, so the shipped guide cannot drift from the binary |
Constraints
- The surface is the
fn computerCLICommand-line interface. It exposes no HTTPHypertext Transfer Protocol route. - macOS is the only supported platform. Linux and Windows use the unsupported adapter.
- Only the macOS
osascriptandscreencapturebuilt-ins are used. Fusion downloads no helper, native module, or automation dependency. - The JXA automation program is static and receives values as arguments or stdin.
- Snapshots, latest pointers, and screenshots live under the
.fusion/computer-use/directory of the resolved project root. The root is resolved once per invocation by walking upward for a Fusion project marker. - Element indexes are sparse and snapshot-scoped. An index is never derived from
elementCount, position, or bounds. - A snapshot expires five minutes after capture by default, and
expiresAtpublishes the exact deadline. - One latest pointer exists per app, not per window.
- The
--snapshot-idvalue must match^cs_[A-Za-z0-9]{10,40}$and is validated before any filesystem access. - The command surface descriptor is the single source for the help text, the shipped guide, and the flag validation rules.
- The shipped
computer-useskill is a thin discovery stub. It lists no subcommand and no flag.
Acceptance Criteria
-
FR-1MustThe system shall expose `fn computer` with the twelve subcommands `capabilities`, `permissions`, `list-apps`, `list-windows`, `get-app-state`, `click`, `set-value`, `type-text`, `press-key`, `hotkey`, `scroll`, and `drag`
gherkin @FR-1MustThe system shall expose `fn computer` with the twelve subcommands `capabilities`, `permissions`, `list-apps`, `list-windows`, `get-app-state`, `click`, `set-value`, `type-text`, `press-key`, `hotkey`, `scroll`, and `drag` Scenario: The command surface lists the shipped subcommands Given the fn CLICommand-line interface When the operator runs fn computer --help Then the output names capabilities, permissions, list-apps, list-windows, get-app-state, click, set-value, type-text, press-key, hotkey, scroll, and drag -
FR-2MustThe system shall capture the accessibility tree of a target app window in `get-app-state` and persist a snapshot record under the resolved project root before returning its snapshot id
gherkin @FR-2MustThe system shall capture the accessibility tree of a target app window in `get-app-state` and persist a snapshot record under the resolved project root before returning its snapshot id Scenario: Capturing a window persists a snapshot before returning it Given a running app with one window When the operator runs fn computer get-app-state --app com.apple.Safari --json Then the envelope carries a snapshot id starting with cs_ and a record file exists under the project root -
FR-3MustThe system shall resolve every element-bound action through a snapshot record, and shall refuse the action with `SNAPSHOT_REQUIRED` when the target app has no snapshot
gherkin @FR-3MustThe system shall resolve every element-bound action through a snapshot record, and shall refuse the action with `SNAPSHOT_REQUIRED` when the target app has no snapshot Scenario: An element action without a snapshot is refused Given a running app that has never been captured When the operator runs fn computer click --app com.apple.Safari --element-index 7 --json Then the envelope carries error code SNAPSHOT_REQUIRED and no operating-system action runs -
FR-4MustThe system shall consume the app's latest snapshot pointer after a successful action, so the next element action fails with `SNAPSHOT_STALE` and reason `consumed-by-action` until a new capture re-arms the pointer
gherkin @FR-4MustThe system shall consume the app's latest snapshot pointer after a successful action, so the next element action fails with `SNAPSHOT_STALE` and reason `consumed-by-action` until a new capture re-arms the pointer Scenario: A successful action consumes its capture Given a fresh capture of an app When the operator runs fn computer click --app com.apple.Safari --element-index 7 --json Then the result reports snapshotConsumed true and the next element action fails with reason consumed-by-action -
FR-5MustThe system shall re-resolve the recorded window and replay the recorded accessibility locator before an action, and shall fail with `ELEMENT_UNRESOLVABLE` when the path no longer resolves or the role, subrole, or identifier no longer match
gherkin @FR-5MustThe system shall re-resolve the recorded window and replay the recorded accessibility locator before an action, and shall fail with `ELEMENT_UNRESOLVABLE` when the path no longer resolves or the role, subrole, or identifier no longer match Scenario: A changed element is refused before the action Given a capture whose element no longer resolves When the operator runs fn computer click --app com.apple.Safari --element-index 7 --json Then the envelope carries error code ELEMENT_UNRESOLVABLE and no operating-system action runs -
FR-6MustThe system shall refuse an unusable snapshot and report exactly one reason from the fixed set `not-found`, `superseded`, `expired`, `pid-changed`, `window-mismatch`, `window-gone`, `consumed-by-action`
gherkin @FR-6MustThe system shall refuse an unusable snapshot and report exactly one reason from the fixed set `not-found`, `superseded`, `expired`, `pid-changed`, `window-mismatch`, `window-gone`, `consumed-by-action` Scenario: A superseded capture is refused with its reason Given two captures of the same app When the operator runs fn computer click --app com.apple.Safari --element-index 7 --snapshot-id cs_01HABCDE123456 --json Then the envelope carries error code SNAPSHOT_STALE and details reason superseded -
FR-7MustThe system shall store element indexes as a sparse map keyed by the index emitted during capture, and shall fail with `ELEMENT_INDEX_NOT_FOUND` when the requested index is absent from that map
gherkin @FR-7MustThe system shall store element indexes as a sparse map keyed by the index emitted during capture, and shall fail with `ELEMENT_INDEX_NOT_FOUND` when the requested index is absent from that map Scenario: An index absent from the capture is refused Given a capture whose elements are indexed sparsely When the operator runs fn computer click --app com.apple.Safari --element-index 2 --json Then the envelope carries error code ELEMENT_INDEX_NOT_FOUND and the remediation asks for a fresh capture -
FR-8MustThe system shall resolve an app target as an exact bundle id, then an exact unambiguous app name, then a `pid:` prefix with the numeric process id, and shall fail with `APP_NOT_FOUND` or `AMBIGUOUS_APP`
gherkin @FR-8MustThe system shall resolve an app target as an exact bundle id, then an exact unambiguous app name, then a `pid:` prefix with the numeric process id, and shall fail with `APP_NOT_FOUND` or `AMBIGUOUS_APP` Scenario: An ambiguous app name is refused Given two running apps share a name When the operator runs fn computer hotkey --app Notes --keys cmd+k --json Then the envelope carries error code AMBIGUOUS_APP with a remediation to use a bundle id or pid -
FR-9MustThe system shall report Accessibility and Screen Recording permission state as `granted`, `denied`, or `unknown` from non-mutating preflights, and shall never report a grant it did not probe
gherkin @FR-9MustThe system shall report Accessibility and Screen Recording permission state as `granted`, `denied`, or `unknown` from non-mutating preflights, and shall never report a grant it did not probe Scenario: Permission state is reported without a claim Given a host where the permission probe cannot run When the operator runs fn computer permissions --json Then every check reports status unknown and granted false -
FR-10MustThe system shall report `supported: false` from `capabilities` and `permissions` on a platform other than macOS, and shall fail every other subcommand there with `UNSUPPORTED_PLATFORM`
gherkin @FR-10MustThe system shall report `supported: false` from `capabilities` and `permissions` on a platform other than macOS, and shall fail every other subcommand there with `UNSUPPORTED_PLATFORM` Scenario: A platform other than macOS is unsupported Given a host that is not macOS When the operator runs fn computer capabilities --json Then the result reports supported false and lists every action as unsupported And running fn computer list-apps --json fails with error code UNSUPPORTED_PLATFORM -
FR-11MustThe system shall emit one envelope per invocation carrying `schemaVersion` 1, `ok`, `command`, and either `result` or `error`, and shall exit 0 on success and 1 on failure
gherkin @FR-11MustThe system shall emit one envelope per invocation carrying `schemaVersion` 1, `ok`, `command`, and either `result` or `error`, and shall exit 0 on success and 1 on failure Scenario: The envelope is versioned and single Given any computer subcommand When the operator runs it with --json Then stdout carries exactly one object with schemaVersion 1, ok, and command And a successful run exits 0 and a failed run exits 1 -
FR-12MustThe system shall read a value from stdin when `--value-stdin` or `--text-stdin` is used, and shall not place that value in process arguments
gherkin @FR-12MustThe system shall read a value from stdin when `--value-stdin` or `--text-stdin` is used, and shall not place that value in process arguments Scenario: A secret value travels through stdin Given an editable element in a captured window When the operator pipes the value into fn computer set-value --app com.apple.Safari --element-index 7 --value-stdin --json Then the value is absent from the process arguments and from the record the command writes -
FR-13ShouldThe system shall capture the selected window as a screenshot stored under the project root and report the file path, and shall report a screenshot failure as `screenshotError` without discarding the captured accessibility tree
gherkin @FR-13ShouldThe system shall capture the selected window as a screenshot stored under the project root and report the file path, and shall report a screenshot failure as `screenshotError` without discarding the captured accessibility tree Scenario: A failed screenshot keeps the captured tree Given a capture whose screenshot step fails When the operator runs fn computer get-app-state --app com.apple.Safari --json Then the result carries the snapshot and a screenshotError, and no screenshot path -
FR-14ShouldThe system shall select a window with `--window-id` or `--window-index`, refuse both together, and restore a minimized window when `--restore-window` is passed to `get-app-state`
gherkin @FR-14ShouldThe system shall select a window with `--window-id` or `--window-index`, refuse both together, and restore a minimized window when `--restore-window` is passed to `get-app-state` Scenario: The two window selectors are mutually exclusive Given a running app When the operator runs fn computer get-app-state --app com.apple.Safari --window-id w1 --window-index 0 --json Then the envelope carries error code INVALID_ARGUMENTS -
FR-15ShouldThe system shall support a coordinate drag form and an element drag form as mutually exclusive forms, and shall support targetless `type-text`, `press-key`, and `scroll` that act on the focused element of the target app
gherkin @FR-15ShouldThe system shall support a coordinate drag form and an element drag form as mutually exclusive forms, and shall support targetless `type-text`, `press-key`, and `scroll` that act on the focused element of the target app Scenario: A coordinate drag needs no snapshot Given a running app When the operator runs fn computer drag --app com.apple.Safari --from-x 1 --from-y 2 --to-x 3 --to-y 4 --json Then the action runs with a null snapshot id and no element indexes -
FR-16ShouldThe system shall render the full command guide from the binary through `fn skills get computer-use`, and the shipped `computer-use` discovery skill shall carry no static command or flag list
gherkin @FR-16ShouldThe system shall render the full command guide from the binary through `fn skills get computer-use`, and the shipped `computer-use` discovery skill shall carry no static command or flag list Scenario: The guide matches the binary that runs it Given the installed fn CLICommand-line interface When the operator runs fn skills get computer-use Then the output names every subcommand, every flag, and every error code And the shipped computer-use skill file lists no subcommand and no flag -
FR-17ShouldThe system shall report capabilities as the platform, the adapter id, the supported flag, the action inventory split into supported and unsupported actions, and the feature flags for screenshot, restore-window, stdin secrets, and cross-invocation snapshots
gherkin @FR-17ShouldThe system shall report capabilities as the platform, the adapter id, the supported flag, the action inventory split into supported and unsupported actions, and the feature flags for screenshot, restore-window, stdin secrets, and cross-invocation snapshots Scenario: Capabilities describe the platform and the action inventory Given the installed fn CLICommand-line interface When the operator runs fn computer capabilities --json Then the result carries the platform, the adapter id, the supported flag, both action lists, and the four feature flags -
NFR-1MustThe system shall never act on an element it did not observe, so every element action re-resolves the window and the locator and verifies identity before the operating-system call
gherkin @NFR-1MustThe system shall never act on an element it did not observe, so every element action re-resolves the window and the locator and verifies identity before the operating-system call Scenario: The action replays the locator before it acts Given a capture of an app When the operator runs fn computer click --app com.apple.Safari --element-index 7 --json Then the window is resolved and the locator is replayed before the action call And the action uses the bounds observed during that replay -
NFR-2MustThe system shall keep a secret value out of process arguments, out of the snapshot record the command writes, out of error messages, and out of the JSONJavaScript Object Notation envelope
gherkin @NFR-2MustThe system shall keep a secret value out of process arguments, out of the snapshot record the command writes, out of error messages, and out of the JSONJavaScript Object Notation envelope Scenario: A secret value never reaches the output Given a value supplied through stdin When the operator runs fn computer set-value --app com.apple.Safari --element-index 7 --value-stdin --json Then the envelope, the error text, and the record the command writes contain no part of the value -
NFR-3MustThe system shall keep the operating-system automation program static, and shall pass untrusted app names, window ids, and locator paths as arguments or stdin instead of interpolating them into the program source
gherkin @NFR-3MustThe system shall keep the operating-system automation program static, and shall pass untrusted app names, window ids, and locator paths as arguments or stdin instead of interpolating them into the program source Scenario: Untrusted values stay out of the program source Given an app name and a locator path When the operator runs an element action Then the program source passed to the operating system is unchanged and the values arrive as arguments -
NFR-4MustThe system shall run on macOS only, using the operating-system `osascript` and `screencapture` built-ins, with no downloaded helper, native module, or automation dependency
gherkin @NFR-4MustThe system shall run on macOS only, using the operating-system `osascript` and `screencapture` built-ins, with no downloaded helper, native module, or automation dependency Scenario: No automation dependency is installed Given the published CLICommand-line interface package When the operator inspects its contents Then the computer surface runs through the operating-system built-ins only -
NFR-5MustThe system shall emit exactly one error per invocation, let the first failing stage win, and order the stages as group routing, flag parsing, platform resolution, action support, built-in and permission gate, stdin read, app resolution, supplied-window resolution, snapshot resolution, sparse element lookup, window and locator replay, then the operating-system call
gherkin @NFR-5MustThe system shall emit exactly one error per invocation, let the first failing stage win, and order the stages as group routing, flag parsing, platform resolution, action support, built-in and permission gate, stdin read, app resolution, supplied-window resolution, snapshot resolution, sparse element lookup, window and locator replay, then the operating-system call Scenario: The first failing stage decides the error Given a malformed flag on an unsupported platform When the operator runs the subcommand with --json Then the envelope carries error code INVALID_ARGUMENTS and no other error appears -
NFR-6MustThe system shall bound every operating-system command with a fixed timeout of 5 seconds for the permission probe, 10 seconds for discovery, 20 seconds for state capture, 15 seconds for a screenshot, 10 seconds for locator replay, and 10 seconds for an action, and shall offer no user-configurable timeout flag
gherkin @NFR-6MustThe system shall bound every operating-system command with a fixed timeout of 5 seconds for the permission probe, 10 seconds for discovery, 20 seconds for state capture, 15 seconds for a screenshot, 10 seconds for locator replay, and 10 seconds for an action, and shall offer no user-configurable timeout flag Scenario: Every operating-system call is bounded Given an action that never returns When the operator runs fn computer click --app com.apple.Safari --element-index 7 --json Then the call is terminated at the action timeout and the envelope carries error code TIMEOUT -
NFR-7MustThe system shall change `schemaVersion` and the error code list only for a breaking reshape, and shall add error codes without removing or renaming existing ones
gherkin @NFR-7MustThe system shall change `schemaVersion` and the error code list only for a breaking reshape, and shall add error codes without removing or renaming existing ones Scenario: The error code list grows without renames Given the published contract When the error code inventory is compared with the codes emitted by the source Then every emitted code is a member of the published list -
NFR-8ShouldThe system shall keep snapshots, latest pointers, and screenshots under the resolved Fusion project root, so state is not shared across projects and a capture from one directory is visible to a later invocation from another directory in the same project
gherkin @NFR-8ShouldThe system shall keep snapshots, latest pointers, and screenshots under the resolved Fusion project root, so state is not shared across projects and a capture from one directory is visible to a later invocation from another directory in the same project Scenario: A capture is visible across directories in one project Given a capture made from a nested directory of a project When the operator runs an element action from the project root Then the action finds the same snapshot record under the project root -
NFR-9ShouldThe system shall serialize concurrent CLICommand-line interface processes on a per-app lock, so a capture cannot be lost and a stale action cannot consume a newer capture
gherkin @NFR-9ShouldThe system shall serialize concurrent CLICommand-line interface processes on a per-app lock, so a capture cannot be lost and a stale action cannot consume a newer capture Scenario: A capture that runs during an action is not lost Given an action in progress on an app When a capture for the same app starts concurrently Then the capture completes after the action and the newest capture stays usable -
NFR-10ShouldThe system shall check the command surface descriptor, the parser flag literals, the emitted error codes, and the rendered guide against each other, so the shipped guide cannot drift from the binary
gherkin @NFR-10ShouldThe system shall check the command surface descriptor, the parser flag literals, the emitted error codes, and the rendered guide against each other, so the shipped guide cannot drift from the binary Scenario: The shipped guide matches the descriptor Given the command surface descriptor When the guide is rendered Then the guide contains every subcommand, every flag, and every error code without truncation
Conflicts
None identified yet.
Open Questions
- Which platform receives the next adapter if the surface is extended beyond macOS. The code today has only the macOS adapter and the unsupported adapter.
- Whether
paste-textandperform-secondary-actionare planned additions. The documentation records them as absent from capabilities rather than as stubs.
Specification: Computer Use: Desktop GUI Automation
Overview
The computer surface lives in the published CLICommand-line interface package at packages/cli/src/commands/computer.ts and packages/cli/src/commands/computer/.
A single dispatcher validates the flags, resolves the state root, runs the handler, validates the result against the contract, and prints one versioned envelope.
The contract in computer/contract.ts holds the frozen subcommand, action, and error-code tuples, the result shapes, and the envelope.
The snapshot store in computer/snapshot-store.ts persists capture records and the per-app latest pointer under the resolved project root, and it enforces the freshness order that decides whether an action may run.
The adapter registry in computer/adapter-registry.ts returns the macOS adapter on darwin and the unsupported adapter everywhere else.
The macOS adapter drives the operating-system built-ins through the exec seam, and the exec seam spawns them asynchronously with a bounded lifetime and no shell.
The agent-facing guide is rendered in-process from the same descriptor, and the shipped skill stays a thin discovery stub.
Architecture
fn computer SUBCOMMAND [--json] packages/cli/src/bin.ts
│
▼
runComputer commands/computer.ts
│ validateFlags → resolveComputerStateRoot → handler → validateResult → envelope
│
├──► contract.ts frozen tuples, result shapes, envelope, error codes
│
├──► snapshot-store.ts records + per-app latest pointer, freshness order
│ PROJECT_ROOT/.fusion/computer-use/
│ snapshots/SNAPSHOT_ID.json
│ latest/TARGET_KEY_SLUG.json
│ screenshots/computer-EPOCH_MS.png
│
└──► adapter-registry.ts
├── darwin ──► adapter-macos.ts
│ │ ComputerExecSeam (exec-seam.ts)
│ ▼
│ osascript -l JavaScript -e STATIC_PROGRAM
│ screencapture -x -l CAPTURE_WINDOW_ID FILE
│ static program source: computer/scripts/macos-jxa.ts
│
└── other ──► adapter-unsupported.ts
capabilities/permissions report supported: false
every other method raises UNSUPPORTED_PLATFORM
Agent-facing surface
fn skills get computer-use ──► guide.ts renderComputerUseGuide()
packages/cli/skill/computer-use/SKILL.md (thin discovery stub, no command list)
Data Models
App snapshot
| Field | Type | Constraints | Description |
|---|---|---|---|
| snapshotId | string | matches ^cs_[A-Za-z0-9]{10,40}$, not null |
Identifier of the capture, used as the action fence |
| targetKey | string | the bundle: prefix followed by the bundle id, or the pid: prefix followed by the process id, not null |
App scope of the capture |
| windowKey | string | the target key, a hash sign, and the window id, not null | Window scope of the capture |
| capturedAt | string | ISO 8601 timestamp, not null | Time of the capture |
| expiresAt | string | ISO 8601 timestamp after capturedAt, not null |
Deadline after which the capture is refused |
| app | AppRef | not null | The captured application |
| window | WindowRef | not null | The captured window |
| elementCount | number | integer, not null | Number of elements in the capture |
| elements | map of string to Element | sparse map keyed by the element index, not null | The captured elements |
App reference
| Field | Type | Constraints | Description |
|---|---|---|---|
| bundleId | string or null | nullable | The application bundle id, null when the operating system reports none |
| name | string | not null | The application display name |
| pid | number | integer, not null | The operating-system process id |
Window reference
| Field | Type | Constraints | Description |
|---|---|---|---|
| windowId | string | not null | Identifier of the window |
| windowIndex | number | integer, not null | Position of the window in the application window list |
| title | string | not null | The window title |
| bounds | Bounds or null | nullable | The window rectangle |
| minimized | boolean | not null | Whether the window is minimized |
Element and locator
| Field | Type | Constraints | Description |
|---|---|---|---|
| index | number | integer, sparse, not null | The index emitted during capture |
| role | string | not null | The accessibility role |
| title | string or null | nullable | The accessibility name |
| value | string or null | nullable | The current value |
| label | string or null | nullable | The accessibility description |
| enabled | boolean | not null | Whether the element accepts actions |
| focused | boolean | not null | Whether the element holds focus |
| bounds | Bounds or null | nullable | The element rectangle |
| actions | array of string | not null | The accessibility actions the element offers |
| locator | ElementLocator | not null | The replay identity of the element |
The locator carries kind (literal ax-path), path (the path from the window root), role, subrole, identifier, and title.
The role, subrole, and identifier are compared on replay, so a different element that now occupies the path is refused.
Action result
| Field | Type | Constraints | Description |
|---|---|---|---|
| action | string | one of the seven action names, not null | The action that was performed |
| app | AppRef | not null | The target application |
| snapshotId | string or null | null for hotkey and coordinate drag, else the fence id | The snapshot the action was bound to |
| elementIndex | number or null | null for drag and hotkey, else the targeted index | The targeted element index |
| fromElementIndex | number or null | null except for element-form drag | The drag start index |
| toElementIndex | number or null | null except for element-form drag | The drag end index |
| performed | boolean | literal true, not null |
The action reached the operating system |
| snapshotConsumed | boolean | not null | Whether the app's latest capture was burned |
Envelope and error
| Field | Type | Constraints | Description |
|---|---|---|---|
| schemaVersion | number | literal 1, not null |
Contract version |
| ok | boolean | not null | Whether the invocation succeeded |
| command | string | the computer. prefix followed by the subcommand, or computer for a group-level failure, not null |
The command name |
| result | unknown | present only when ok is true |
The command payload |
| error | ComputerError | present only when ok is false |
The failure payload |
The error carries code (a member of the published error-code list), message, an optional remediation, and an optional flat details map whose values are strings, numbers, or booleans.
Remediation is required for UNSUPPORTED_PLATFORM, PERMISSION_DENIED, PERMISSION_UNVERIFIED, SNAPSHOT_REQUIRED, SNAPSHOT_STALE, ELEMENT_INDEX_NOT_FOUND, ELEMENT_UNRESOLVABLE, AMBIGUOUS_APP, and ACTION_UNSUPPORTED.
APIApplication programming interface Contracts
The feature exposes no HTTPHypertext Transfer Protocol route, so there is no OpenAPI document.
The contract surface is the fn computer command set below.
| Subcommand | Required flags | Operation | Result |
|---|---|---|---|
capabilities |
none | Report the platform, the adapter id, the supported flag, the action inventory, and the feature flags | CapabilitiesResult |
permissions |
none | Report the Accessibility and Screen Recording permission state | PermissionsResult |
list-apps |
none | List the running applications available for selection, sorted by name | ListAppsResult |
list-windows |
--app |
List the windows of one application | ListWindowsResult |
get-app-state |
--app |
Capture a window and its accessible elements, then persist the snapshot | AppStateResult |
click |
--app, --element-index |
Click a captured element | ActionResult |
set-value |
--app, --element-index, and one of --value or --value-stdin |
Set the value of a captured editable element | ActionResult |
type-text |
--app, and one of --text or --text-stdin |
Type text into the app or a captured element | ActionResult |
press-key |
--app, --key |
Press a key in the app or a captured element | ActionResult |
hotkey |
--app, --keys |
Send a plus-separated key chord to the app | ActionResult |
scroll |
--app, --direction |
Scroll the app or a captured element, three steps by default | ActionResult |
drag |
--app, and either all four coordinate flags or both element-index flags |
Drag between coordinates or two captured elements | ActionResult |
Optional flags on the element actions are --snapshot-id, --window-id, and --window-index.
--window-id and --window-index are mutually exclusive.
hotkey and coordinate-form drag accept neither snapshot nor window flags.
type-text, press-key, and scroll accept --element-index, and they require it when a snapshot or window flag is present.
get-app-state also accepts --no-screenshot and --restore-window.
Every subcommand accepts the global --json flag.
Error codes shared across the subcommands:
| Code | Meaning |
|---|---|
UNSUPPORTED_PLATFORM |
No supported adapter on this platform |
PERMISSION_DENIED |
A required permission is denied, or a required built-in is missing |
PERMISSION_UNVERIFIED |
An unknown probe was followed by a permission-shaped operating-system failure |
INVALID_ARGUMENTS |
An invalid subcommand, flag, number, enum, or snapshot id |
APP_NOT_FOUND |
No running application matches the target |
AMBIGUOUS_APP |
More than one application name matches the target |
WINDOW_NOT_FOUND |
The supplied live window selector did not match |
SNAPSHOT_REQUIRED |
An element action has no snapshot for the target app |
SNAPSHOT_STALE |
The snapshot is no longer usable, with a reason in the fixed stale-reason list |
ELEMENT_INDEX_NOT_FOUND |
The sparse index is absent from the snapshot |
ELEMENT_UNRESOLVABLE |
The recorded locator no longer resolves, or the identity differs |
ACTION_UNSUPPORTED |
The adapter does not support the action |
ACTION_FAILED |
The operating-system action failed |
SCREENSHOT_FAILED |
The screenshot failed, reported inside screenshotError |
TIMEOUT |
A bounded operating-system call ran out of time |
INTERNAL |
An unexpected failure, reported redacted |
Key Sequences
Capture a snapshot
operator runComputer snapshot store macOS adapter osascript
│ │ │ │ │
│ get-app-state │ │ │ │
│------------------->│ validateFlags │ │ │
│ │ resolve state root │ │ │
│ │------------------->│ │ │
│ │ withAppFence │ │ │
│ │ captureState ──────────────────────────────>│ │
│ │ │ │ permission probe │
│ │ │ │------------------->│
│ │ │ │ accessibility ok │
│ │ │ │------------------->│
│ │ │ │ list windows │
│ │ │ │------------------->│
│ │ │ │ state capture │
│ │ │ │------------------->│
│ │ │ │ tree + elements │
│ │ │<──────────────────────│ │
│ │ persist record ───>│ │ │
│ │ │ write snapshot.json │ │
│ │ │ write latest pointer │ │
│ │<────────────────────│ │ │
│<───────────────────│ envelope │ │ │
Act on a snapshot
operator runComputer store adapter
│ │ │ │
│ click --element-index 7 │ │
│------------------->│ validateFlags │ │
│ │ resolve app │ │
│ │ withAppFence ──────────────────────>│
│ │ resolve record ───>│ │
│ │ │ freshness order │
│ │ │ not-found / superseded / consumed-by-action /
│ │ │ expired / pid-changed / window-mismatch
│ │<--------------------│ refusal │
│ │ getElement(index) ─>│ │
│ │ resolve window ─────────────────────>│
│ │ resolve locator ────────────────────>│
│ │ │ │ verify role, subrole, identifier
│ │ │ │ ELEMENT_UNRESOLVABLE on mismatch
│ │ perform action ────────────────────>│
│ │ consume pointer ──>│ │
│ │<--------------------│ consumed │
│<-------------------│ envelope: snapshotConsumed true │
The snapshot, act, snapshot loop
┌────────────────────────────── one iteration ──────────────────────────────┐
│ │
│ fn computer get-app-state --app com.apple.Safari --json │
│ capture the tree, persist the record, publish snapshotId │
│ │
│ fn computer click --app com.apple.Safari --element-index 7 │
│ resolve the record, replay the window and the locator, act, │
│ then consume the app's latest capture │
│ │
└──────────────────────────────────────────────────────────────────────────┘
│ │
│ next element action │ next element action
▼ ▼
SNAPSHOT_STALE / consumed-by-action SNAPSHOT_STALE / consumed-by-action
(until a new capture re-arms) (until a new capture re-arms)
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Safety model | Bind every element action to a snapshot and consume the capture after each action | A successful action can change focus, navigation, scrolling, or the rendered tree, so a second index from the first capture may name a different element |
| Locator identity | Replay the recorded accessibility path and compare role, subrole, and identifier | A path that now holds a different element must be refused instead of acted on |
| Bounds source | Use the bounds observed during the replay | Saved bounds from the capture are stale by definition |
| Snapshot storage | Persist records and the latest pointer on disk under the project root | Each CLICommand-line interface invocation is a separate process, so the capture must survive the process |
| State root | Resolve the project root once per invocation by walking upward for a project marker | Capture and replay often run from different directories in the same project |
| Pointer scope | One latest pointer per app, not per window | The app's tree is the unit that changes, and the pointer decides whether a fresh capture exists |
| Concurrency | Hold a per-app directory lock across capture, replay, and consumption | A concurrent capture must not be lost and a stale action must not consume a newer capture |
| Platform support | macOS only, with an unsupported adapter elsewhere | A clear failure is safer than a silent no-op that makes a caller believe an action happened |
| Operating-system access | Use the osascript and screencapture built-ins through a spawn seam |
Fusion downloads no helper, native module, or automation dependency |
| Program safety | Keep the JXA program static and pass values as arguments or stdin | App names, window ids, and locator paths are untrusted input |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Read values from stdin and redact long tokens in error text | A secret must not reach the process table, the snapshot records, or the output |
| Permissions | Report granted, denied, or unknown from non-mutating preflights | A denied screen capture can still save wallpaper pixels, so capture success is not proof of permission |
| Error contract | One append-only error-code list, one flat details map, one deterministic failure order | Callers branch on codes safely, and the first failing stage decides the outcome |
| Guide ownership | Render the guide in-process from the command surface descriptor | The shipped guide cannot drift from the binary that will run the commands |
| Skill form | Ship a thin discovery stub with no command or flag list | A static list in the skill file would drift from the installed binary |
Risks and Unknowns
- The adapter surface is macOS-only. Another platform needs a new adapter behind the same contract, and no such adapter exists yet.
- The macOS adapter depends on the accessibility tree, so an application that draws its controls without accessibility metadata cannot be inspected or driven.
- Screenshot capture maps the accessibility window to a Quartz window id by process id, title, and bounds. A collision or a title change degrades the screenshot without affecting the captured tree.
- The permission preflight reads the state of the host process, so a headless host or a remote shell reports unknown and the action outcome then depends on the form of the operating-system failure.
- The state root falls back to the resolved start path when no project marker is found, so two invocations from unrelated directories in the same project can miss each other's captures.
Out of Scope
- Linux and Windows adapters. Both report
supported: falseand fail withUNSUPPORTED_PLATFORM. - A dashboard or HTTPHypertext Transfer Protocol surface for computer use. The feature is the
fn computerCLICommand-line interface. - Any native automation helper, native module, or downloaded binary.
paste-textandperform-secondary-action. They are absent from the action inventory rather than present as stubs.- A user-configurable timeout. The seam timeouts are fixed.
- Cross-project sharing of snapshots, pointers, or screenshots.
- A remote or networked desktop. The surface drives the local desktop only.
Test Plan: Computer Use: Desktop GUI Automation
Scope
Covers the fn computer command surface, the snapshot store and its freshness order, the macOS adapter driven through an injected exec seam, the unsupported adapter, the command surface descriptor, the rendered guide, and the shipped discovery skill.
The tests never touch the host desktop. The macOS adapter is exercised through a fake exec seam that returns canned stdout, stderr, exit codes, and timeouts.
Out of scope are the operating-system built-ins themselves, the macOS permission prompts, the screenshot image content, and the Hermes and Claude skill staging paths that only install the shipped skill.
Two behaviors have no direct assertion today. The stdin transport for a secret value is covered only through the exactly-one-source rule, and the restore of a minimized window is covered only through the flag validation. Both are listed in the coverage matrix with the test that comes closest.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Sparse element indexes persist as map keys | A capture with indexes 0, 3, and 7 | Index 7 resolves, index 2 raises ELEMENT_INDEX_NOT_FOUND, and the record file stores the element under key 7 |
| TC-2 | A capture keeps its identity across a fresh store instance | A record read by a new store over the same root | The app, window, and locator of the record are returned unchanged |
| TC-3 | The freshness order raises the documented codes | Resolve with no snapshot, with a superseded id, with an unknown id, and after the deadline | SNAPSHOT_REQUIRED, then SNAPSHOT_STALE with superseded, not-found, and expired, each with remediation naming get-app-state |
| TC-4 | Supersession is checked before expiry, then pid and window | A superseded id after the deadline, a changed pid, and a mismatched asserted window | superseded first, then pid-changed, then window-mismatch |
| TC-5 | Consumption burns the app pointer | Consume after a capture, then resolve with and without the id | Both resolves raise SNAPSHOT_STALE with consumed-by-action, and a fresh capture re-arms the pointer |
| TC-6 | A late consumption does not consume a newer capture | A consume and a persist interleaved, including a concurrent pair | The newer capture stays resolvable |
| TC-7 | A legacy pointer and an unparsable record | A pointer without consumedAt, and a record file that is not JSONJavaScript Object Notation |
The legacy pointer resolves, and the unparsable record raises not-found |
| TC-8 | Expired records are pruned | A capture with a past deadline | The record file is removed by a single-level directory read |
| TC-9 | The contract keeps frozen inventories and a stable envelope | The exported tuples and envelope builders | The subcommand, action, error-code, and stale-reason tuples are frozen and duplicate free, the envelope carries schemaVersion 1, and the timeout table holds the six fixed values |
| TC-10 | The contract validates ids, permissions, state, and action shapes | A valid id, a path-shaped id, a permission result, a state result, and action results for drag, hotkey, and click | The path-shaped id is rejected, the permission result without a probe is rejected, a state result with both a screenshot and an error is rejected, and an action result without snapshotConsumed is rejected |
| TC-11 | App and window addressing stay separate | An app with a bundle id, two window ids, and a hostile target key | The target key is the bundle: prefix followed by the bundle id, the window keys differ per window, and the slug holds no path separator |
| TC-12 | The state root resolves from the project marker | A marked root, a nested directory, an unmarked directory, and a relative path | The marked root and the nested directory resolve to the root, the unmarked directory resolves to itself, and a relative path resolves to an absolute path |
| TC-13 | The registry injects the macOS adapter dependencies | A darwin platform with an injected factory |
The factory receives the seam, the clock, and the project root |
| TC-14 | The unsupported adapter rejects every operation | A linux and a win32 platform |
Capabilities report supported: false with every action unsupported, permissions report no checks, and every other method raises UNSUPPORTED_PLATFORM with a macOS remediation |
| TC-15 | A denied Accessibility grant blocks automation | A probe that reports a denied Accessibility grant | hotkey and drag raise PERMISSION_DENIED after one probe and no automation call |
| TC-16 | A missing osascript is reported as unknown permissions | A seam that fails to spawn osascript |
Permissions report both checks as unknown and not granted, and every operation raises PERMISSION_DENIED with the missing-binary detail |
| TC-17 | A probe that times out, exits non-zero, or returns malformed output | Three failing probe results | Each keeps both checks unknown and does not report a missing binary |
| TC-18 | The guide renders the whole descriptor | The rendered guide | Every subcommand, every flag, and every error code appears, every required heading appears once, and no truncation marker is present |
| TC-19 | The guide renders the invocation rules | The rendered guide | The mutually exclusive pairs, the exactly-one-value rules, the element-index requirement, and the drag form rules all appear |
| TC-20 | The shipped skill stays a thin discovery stub | Every shipped SKILL.md |
The computer-use skill names only the three read-only probes, no other shipped skill carries a computer command, and the frontmatter parses |
| TC-21 | The built-in guide matches the installed binary | fn skills get computer-use and fn --version |
The guide is printed and its version matches the binary version |
| TC-22 | The computer-use skill ships in the published package | The packed package contents | skill/computer-use/SKILL.md is present |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-23 | A capture emits one envelope and persists a record | A fake adapter and a temporary project root | The envelope carries schemaVersion 1, ok true, the computer.get-app-state command, and a cs_ prefixed snapshot id |
| TC-24 | A capture crosses directories in one project | A capture from a nested directory and an action from the project root | The action finds the same record, and the nested directory holds no state directory |
| TC-25 | A stale id is refused and the latest id replays before the action | Two captures and a recording fake adapter | The stale id raises SNAPSHOT_STALE with superseded and the action does not run, while the latest id resolves the window, then the locator, then the action, and the action uses the bounds from the replay |
| TC-26 | The loop refuses the next element action until a fresh capture | A capture, a click, a second click, and a new capture | The click reports snapshotConsumed true, the second click raises consumed-by-action with remediation naming get-app-state, and the click after the new capture succeeds |
| TC-27 | Every action form consumes the captured pointer | A capture before each of the eight action forms | Each action reports snapshotConsumed true, and the following element action raises consumed-by-action |
| TC-28 | A failed action and read commands do not consume the pointer | A failing click, then a read, then targetless actions | The failing action does not consume the pointer, the read does not consume it, and each targetless action does consume it |
| TC-29 | The command fence is held through consumption | An action that blocks while a capture starts | The capture completes after the action, and the newest capture stays usable |
| TC-30 | Both drag endpoints come from one snapshot fence | A concurrent latest update during a drag | The record is resolved once, and the drag receives both endpoints and the one snapshot id |
| TC-31 | A coordinate drag runs without a snapshot | A complete set of coordinate flags | The action receives a null snapshot id, the four coordinates, and no element indexes |
| TC-32 | Element-scoped typing uses the replay path | A capture and a typed element | The locator is replayed once and the typing action runs once |
| TC-33 | The descriptor, the dispatcher, and the contract agree | The exported subcommand sets | The three sets are equal, and each declared required and mutually exclusive flag is enforced by the validator |
| TC-34 | The conditional forms, the parser literals, and the error codes are checked | The descriptor, the parser source, and the emitting sources | The conditional forms are refused, the parser flag literals equal the declared flags, and every emitted code belongs to the published list |
| TC-35 | A coordinate drag posts a CoreGraphics event sequence | The macOS adapter over a fake seam | The program posts a mouse event creation and a post for the drag, the arguments carry the operation, the app name, and the four coordinates, and the call uses the 10 second action timeout |
| TC-36 | The scroll direction maps to a fixed key code | The macOS adapter over a fake seam for each of the four directions | The program carries the direction and the amount, and the fixed key code for that direction |
| TC-37 | A failed screenshot keeps the captured tree | A seam that fails to spawn screencapture |
The state carries the tree, the screenshot is null, the error is SCREENSHOT_FAILED, and the capture call used the screenshot timeout |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-38 | The recorded window no longer exists | The action raises SNAPSHOT_STALE with reason window-gone and a remediation naming get-app-state |
| TC-39 | The recorded locator no longer resolves | The action raises ELEMENT_UNRESOLVABLE and the details carry the snapshot id and the element index |
| TC-40 | A replay raises a timeout, an unverified permission, or a denied permission | Each code is preserved as raised, and none is rewritten as a stale-element error |
| TC-41 | One drag endpoint cannot be resolved | The action raises ELEMENT_UNRESOLVABLE and the details carry the failing endpoint index |
| TC-42 | The replayed element has a different role or is not live | The action raises ELEMENT_UNRESOLVABLE after two operating-system calls and no further automation |
| TC-43 | A permission-shaped replay failure | The action raises PERMISSION_UNVERIFIED instead of reporting an unresolvable element |
| TC-44 | osascript disappears during a replay |
The action raises PERMISSION_DENIED with the missing-binary detail |
| TC-45 | An unknown subcommand and a missing subcommand | Both raise INVALID_ARGUMENTS under the group-level command name |
| TC-46 | Both text sources are supplied | The invocation is refused with INVALID_ARGUMENTS before any app discovery |
| TC-47 | A dotted bundle spelling matches no bundle id | The target falls back to an exact app name and the action runs against that app |
Test Infrastructure
- The suite runs with Vitest in the CLICommand-line interface package under
packages/cli/src/commands/__tests__/. - A fake
ComputerAdapterimplements the whole adapter interface, so no test touches the host desktop. - A fake
ComputerExecSeamreturns canned stdout, stderr, exit codes, and timeout flags for theosascriptandscreencapturecalls. - A
ComputerSnapshotStoreis built over a temporary directory with an injected clock, so the freshness order and the expiry are deterministic. - A temporary project root with a
.fusion/project.jsonmarker exercises the state-root resolution. - The
runComputerdispatcher is called with injectedstdout,stderr,stdin,adapter,store, andclockoptions, so the envelope and the exit code are observable without a process. - The tests run on every platform, so the macOS adapter is only reached through the injected seam.
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall expose `fn computer` with the twelve subcommands `capabilities`, `permissions`, `list-apps`, `list-windows`, `get-app-state`, `click`, `set-value`, `type-text`, `press-key`, `hotkey`, `scroll`, and `drag` | TC-18, TC-33 |
| FR-2MustThe system shall capture the accessibility tree of a target app window in `get-app-state` and persist a snapshot record under the resolved project root before returning its snapshot id | TC-23, TC-1, TC-8 |
| FR-3MustThe system shall resolve every element-bound action through a snapshot record, and shall refuse the action with `SNAPSHOT_REQUIRED` when the target app has no snapshot | TC-3, TC-26 |
| FR-4MustThe system shall consume the app's latest snapshot pointer after a successful action, so the next element action fails with `SNAPSHOT_STALE` and reason `consumed-by-action` until a new capture re-arms the pointer | TC-5, TC-26, TC-27, TC-28 |
| FR-5MustThe system shall re-resolve the recorded window and replay the recorded accessibility locator before an action, and shall fail with `ELEMENT_UNRESOLVABLE` when the path no longer resolves or the role, subrole, or identifier no longer match | TC-25, TC-39, TC-42 |
| FR-6MustThe system shall refuse an unusable snapshot and report exactly one reason from the fixed set `not-found`, `superseded`, `expired`, `pid-changed`, `window-mismatch`, `window-gone`, `consumed-by-action` | TC-3, TC-4, TC-38 |
| FR-7MustThe system shall store element indexes as a sparse map keyed by the index emitted during capture, and shall fail with `ELEMENT_INDEX_NOT_FOUND` when the requested index is absent from that map | TC-1 |
| FR-8MustThe system shall resolve an app target as an exact bundle id, then an exact unambiguous app name, then a `pid:` prefix with the numeric process id, and shall fail with `APP_NOT_FOUND` or `AMBIGUOUS_APP` | TC-47 |
| FR-9MustThe system shall report Accessibility and Screen Recording permission state as `granted`, `denied`, or `unknown` from non-mutating preflights, and shall never report a grant it did not probe | TC-16, TC-17 |
| FR-10MustThe system shall report `supported: false` from `capabilities` and `permissions` on a platform other than macOS, and shall fail every other subcommand there with `UNSUPPORTED_PLATFORM` | TC-14 |
| FR-11MustThe system shall emit one envelope per invocation carrying `schemaVersion` 1, `ok`, `command`, and either `result` or `error`, and shall exit 0 on success and 1 on failure | TC-23, TC-45 |
| FR-12MustThe system shall read a value from stdin when `--value-stdin` or `--text-stdin` is used, and shall not place that value in process arguments | TC-46 |
| FR-13ShouldThe system shall capture the selected window as a screenshot stored under the project root and report the file path, and shall report a screenshot failure as `screenshotError` without discarding the captured accessibility tree | TC-37 |
| FR-14ShouldThe system shall select a window with `--window-id` or `--window-index`, refuse both together, and restore a minimized window when `--restore-window` is passed to `get-app-state` | TC-33 |
| FR-15ShouldThe system shall support a coordinate drag form and an element drag form as mutually exclusive forms, and shall support targetless `type-text`, `press-key`, and `scroll` that act on the focused element of the target app | TC-30, TC-31, TC-32 |
| FR-16ShouldThe system shall render the full command guide from the binary through `fn skills get computer-use`, and the shipped `computer-use` discovery skill shall carry no static command or flag list | TC-18, TC-19, TC-20, TC-21 |
| FR-17ShouldThe system shall report capabilities as the platform, the adapter id, the supported flag, the action inventory split into supported and unsupported actions, and the feature flags for screenshot, restore-window, stdin secrets, and cross-invocation snapshots | TC-9, TC-14 |
| NFR-1MustThe system shall never act on an element it did not observe, so every element action re-resolves the window and the locator and verifies identity before the operating-system call | TC-25, TC-39, TC-42 |
| NFR-2MustThe system shall keep a secret value out of process arguments, out of the snapshot record the command writes, out of error messages, and out of the JSONJavaScript Object Notation envelope | TC-46 |
| NFR-3MustThe system shall keep the operating-system automation program static, and shall pass untrusted app names, window ids, and locator paths as arguments or stdin instead of interpolating them into the program source | TC-35, TC-36 |
| NFR-4MustThe system shall run on macOS only, using the operating-system `osascript` and `screencapture` built-ins, with no downloaded helper, native module, or automation dependency | TC-14, TC-22 |
| NFR-5MustThe system shall emit exactly one error per invocation, let the first failing stage win, and order the stages as group routing, flag parsing, platform resolution, action support, built-in and permission gate, stdin read, app resolution, supplied-window resolution, snapshot resolution, sparse element lookup, window and locator replay, then the operating-system call | TC-40, TC-45, TC-46 |
| NFR-6MustThe system shall bound every operating-system command with a fixed timeout of 5 seconds for the permission probe, 10 seconds for discovery, 20 seconds for state capture, 15 seconds for a screenshot, 10 seconds for locator replay, and 10 seconds for an action, and shall offer no user-configurable timeout flag | TC-9, TC-37 |
| NFR-7MustThe system shall change `schemaVersion` and the error code list only for a breaking reshape, and shall add error codes without removing or renaming existing ones | TC-9, TC-34 |
| NFR-8ShouldThe system shall keep snapshots, latest pointers, and screenshots under the resolved Fusion project root, so state is not shared across projects and a capture from one directory is visible to a later invocation from another directory in the same project | TC-11, TC-12, TC-24 |
| NFR-9ShouldThe system shall serialize concurrent CLICommand-line interface processes on a per-app lock, so a capture cannot be lost and a stale action cannot consume a newer capture | TC-6, TC-29, TC-30 |
| NFR-10ShouldThe system shall check the command surface descriptor, the parser flag literals, the emitted error codes, and the rendered guide against each other, so the shipped guide cannot drift from the binary | TC-18, TC-33, TC-34 |
Key Test Files
packages/cli/src/commands/__tests__/computer-commands.test.tspackages/cli/src/commands/__tests__/computer-snapshot-index.test.tspackages/cli/src/commands/__tests__/computer-adapter-registry.test.tspackages/cli/src/commands/__tests__/computer-contract.test.tspackages/cli/src/commands/__tests__/computer-state-root.test.tspackages/cli/src/commands/__tests__/computer-surface-descriptor.test.tspackages/cli/src/commands/__tests__/computer-use-guide.test.tspackages/cli/src/commands/__tests__/computer-use-skill.test.tspackages/cli/src/commands/__tests__/skills-get.test.tspackages/cli/src/__tests__/package-config.test.ts
requirements
- Which platform receives the next adapter if the surface is extended beyond macOS. The code today has only the macOS adapter and the unsupported adapter.
- Whether
paste-textandperform-secondary-actionare planned additions. The documentation records them as absent from capabilities rather than as stubs.
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Selectable Workflows & Visual Workflow Editor
Overview
Fusion replaces the fixed legacy lifecycle with a graph-of-nodes workflow: each task runs through a user-selectable workflow composed of plan/code/review/gate/merge (and exit-gate) nodes. Operators pick a built-in workflow or author a custom one visually in a workflow editor, and the engine executes the graph with a single review authority per concern.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Selects or authora workflows, tunes nodes, validates and imports/exports workflow definitions |
| Engine | Executes the selected workflow graph against each task |
| Power user / workflow author | Uses the visual editor to author custom workflows |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall provide built-in workflows (e.g. six-column, coding, brainstorming, coding-ideas, lead-generation, custom v1) | Must | The system shall provide built-in workflows (e.g. six-column, coding, brainstorming, coding-ideas, lead-generation, custom v1) |
| FR-2MustThe system shall execute a task through the selected workflow graph via a graph executor and per-node runners (code, gate, merge, exit-gate, review) | Must | The system shall execute a task through the selected workflow graph via a graph executor and per-node runners (code, gate, merge, exit-gate, review) |
| FR-3MustThe system shall let operators select a workflow per task and resolve a default workflow | Must | The system shall let operators select a workflow per task and resolve a default workflow |
| FR-4MustThe system shall render the workflow editor: view, author, validate, import/export, and tune nodes/settings | Must | The system shall render the workflow editor: view, author, validate, import/export, and tune nodes/settings |
| FR-5MustThe system shall define a workflow IRIntermediate representation and transition policy governing node transitions and gates | Must | The system shall define a workflow IRIntermediate representation and transition policy governing node transitions and gates |
| FR-6ShouldThe system shall support workflow graphs with foreach and loop constructs for repeated subgraphs | Should | The system shall support workflow graphs with foreach and loop constructs for repeated subgraphs |
| FR-7ShouldThe system shall expose workflows through dashboard APIApplication programming interface routes and validate user-authored definitions | Should | The system shall expose workflows through dashboard APIApplication programming interface routes and validate user-authored definitions |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustGraph execution shall preserve workflow/node state across restarts (durable execution results) | Must | Consistency | Graph execution shall preserve workflow/node state across restarts (durable execution results) |
| NFR-2MustExactly one authority (the graph) owns review of plan/code/browser concerns | Must | Correctness | Exactly one authority (the graph) owns review of plan/code/browser concerns |
| NFR-3ShouldCustom workflows shall meet the end-to-end reliability acceptance map | Should | Reliability | Custom workflows shall meet the end-to-end reliability acceptance map |
Constraints
- Plan/code/browser review is owned exclusively by workflow-graph nodes; do not reintroduce a second review authority inside implementation sessions
task.status === "needs-review"/needs-replanare graph signals, not legacy; their writers must remain
Acceptance Criteria
- FR-1MustThe system shall provide built-in workflows (e.g. six-column, coding, brainstorming, coding-ideas, lead-generation, custom v1)
- Given a fresh task
- When workflow resolution runs
- Then a built-in or user-selected workflow is assigned
- FR-2MustThe system shall execute a task through the selected workflow graph via a graph executor and per-node runners (code, gate, merge, exit-gate, review)
- Given an in-progress task
- When the graph executor runs
- Then the graph advances through the selected nodes via their runners
- FR-3MustThe system shall let operators select a workflow per task and resolve a default workflow
- Given operator input and no selection
- When a default workflow is needed
- Then a sensible default (no-selection default) applies
- FR-4MustThe system shall render the workflow editor: view, author, validate, import/export, and tune nodes/settings
- Given a workflow definition
- When opened in the editor
- Then it can be validated, edited, imported, and exported
- FR-5MustThe system shall define a workflow IRIntermediate representation and transition policy governing node transitions and gates
- Given a graph with gates
- When a gate fails
- Then the graph halts or routes per transition policy
- NFR-1MustGraph execution shall preserve workflow/node state across restarts (durable execution results)
- Given a restart mid-graph
- When the task resumes
- Then graph execution state is preserved, not reset
Conflicts
None identified yet.
Open Questions
- How many built-in workflows are considered a supported face-public contract, and where is the canonically catalogued?
Specification: Selectable Workflows & Visual Workflow Editor
Overview
Workflows are modeled as an intermediate representation (workflow IRIntermediate representation) of nodes and transitions in @fusion/core, executed by a graph executor and node runners in @fusion/engine, and authored visually in the dashboard's workflow editor. Definition types, built-in workflows, transition policy, and settings resolution live in core; execution, review, planning, foreach/loop, and task-runtime services live in the engine.
Architecture
Workflow editor (WorkflowNodeEditor, WorkflowSimpleCanvas, WorkflowFieldsPanel,
WorkflowSettingsPanel, WorkflowSelector) [dashboard/app]
│ author / validate / select
▼
Dashboard APIApplication programming interface (register-workflow-routes, board-workflows)
│
▼
@fusion/core/workflows (workflow-ir, workflow-definition-types,
workflow-transitions, workflow-transition-policy,
workflow-settings-resolver, builtin-workflows, builtin-*)
│
▼
@fusion/engine/workflows (workflow-graph-executor, workflow-node-runner,
workflow-node-handlers, workflow-review-service,
workflow-planning-service, workflow-graph-foreach,
workflow-graph-loop, workflow-task-runtime)
│ per-node runners (code / gate / merge / exit-gate / review)
▼
Task store / worktree execution
Data Models
Workflow Definition
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | string | PK | Workflow identifier |
| kind | enum | not null | builtin / custom / v1 |
| nodes | array | not null | Graph nodes with node type, settings, and successors |
| settings | object | — | Workflow-level settings (oversight level, gates, merge strategy) |
APIApplication programming interface Contracts
POST /api/workflows/validate
Request
| Field | Type | Required | Description |
|---|---|---|---|
| definition | object | yes | Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations to validate |
Response (200 OK)
| Field | Type | Description |
|---|---|---|
| valid | boolean | Whether the definition is valid |
| errors | array | Validation errors |
Sequences
Graph advance
graph-executor → node-runner(code) → runner executes in worktree
→ next node (review) → workflow-review-service → verdict
→ gate/merge node → transition policy → next or terminal
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations in core | workflow-ir.ts |
Single canonical representation shared by editor and engine |
| Graph executor in engine | workflow-graph-executor.ts |
Executes transitions outside the domain layer |
| Single review authority | graph-owned review nodes | Prevents duplicate Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP race |
| Visual editor | dashboard components | Operator-authored custom workflows without file editing |
Risks and Unknowns
- Custom workflow reliability acceptance across restart durability and deferred journeys is a tracked map (
docs/custom-workflow-reliability-acceptance-map.md).
Out of Scope
- Non-graph legacy lifecycle execution (deleted; ratcheted by
legacy-tombstones.test.ts) - Merging mechanics themselves (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p5)
Test Plan: Selectable Workflows & Visual Workflow Editor
Scope
Covers built-in workflow IRs and catalog, workflow selection/resolution, graph execution and node runners, gates and transitions, the editor surface, and workflow validation routes. Lifecycle-board and merge tests belong to FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p1/FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p5.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Built-in workflow catalog resolves | no selection | Default built-in workflow applied |
| TC-2 | Built-in IRIntermediate representation parses (coding, brainstorming, coding-ideas, lead-generation) | IRIntermediate representation definition | Valid IRIntermediate representation, correct node set |
| TC-3 | Custom v1 workflow dispatch | v1 definition | Dispatches to the intended node |
| TC-4 | Workflow settings resolver / no-selection default | settings + task | Resolved workflow |
| TC-5 | Legacy workflow IRIntermediate representation call sites still allowlisted | legacy IRIntermediate representation usage | Only allowlisted call sites exist |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-6 | Workflow lifecycle through built-in workflow | task in progress | Graph advances to done |
| TC-7 | Executor fast-mode workflows | fast-mode enabled | Executes via graph boundary |
| TC-8 | Workflow validate route | invalid definition | 400 / validation errors |
| TC-9 | Graph boundary (no legacy fallback) | store without workflow selection | Fail-closed park, not fallback |
| TC-10 | Workflow editor render + authoring | dashboard | Editor renders, nodes editable |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-11 | Gate fails mid-graph | Graph halts or routes per transition policy |
| TC-12 | Graph interrupted by restart | Execution state preserved |
Test Infrastructure
- Vitest across
@fusion/core,@fusion/engine,@fusion/dashboard - Workflow editor component tests under
packages/dashboard/app/components/__tests__/WorkflowNodeEditor*
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall provide built-in workflows (e.g. six-column, coding, brainstorming, coding-ideas, lead-generation, custom v1) | TC-1, TC-2 |
| FR-2MustThe system shall execute a task through the selected workflow graph via a graph executor and per-node runners (code, gate, merge, exit-gate, review) | TC-6, TC-9 |
| FR-3MustThe system shall let operators select a workflow per task and resolve a default workflow | TC-1, TC-4 |
| FR-4MustThe system shall render the workflow editor: view, author, validate, import/export, and tune nodes/settings | TC-8, TC-10 |
| FR-5MustThe system shall define a workflow IRIntermediate representation and transition policy governing node transitions and gates | TC-11 |
| NFR-1MustGraph execution shall preserve workflow/node state across restarts (durable execution results) | TC-12 |
| NFR-2MustExactly one authority (the graph) owns review of plan/code/browser concerns | TC-9 |
Key Test Files
packages/core/src/__tests__/builtin-workflows.test.ts,builtin-*-workflow-ir.test.ts,custom-v1-workflow-dispatch.test.ts,legacy-workflow-ir-callsite-allowlist.test.tspackages/engine/src/__tests__/builtin-workflows-lifecycle.test.ts,executor-graph-boundary.test.ts,executor-fast-mode-workflows.test.ts,benchmark-six-column-workflow.test.ts,workflow-*.test.tspackages/dashboard/src/routes/__tests__/workflow-validate-route.test.ts,board-workflowspackages/dashboard/app/components/__tests__/WorkflowNodeEditor*packages/core/src/__tests__/legacy-tombstones.test.ts(workflow cutover ratchet)
requirements
- How many built-in workflows are considered a supported face-public contract, and where is the canonically catalogued?
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Planning Mode & Planner Oversight
Overview
A dedicated planning flow (Planning Mode chat, Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP, specification editor) plus an automated planner overseer let operators shape a task before execution and keep human control over high-stakes actions. The overseer runs across oversight levels (off/observe/steer/autonomous) with human confirmation gates on merge, PRPull request, and destructive actions, and records an Intervention Timeline in Task Detail.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Shapes plans, approves/rejects Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP, watches and steers planner work |
| Planner lane | Produces the plan and plan artifacts |
| Oversight automation | Monitors planner work and withholds/recommends actions |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall provide a Planning Mode chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node that produce and review a plan for a task | Must | The system shall provide a Planning Mode chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node that produce and review a plan for a task |
| FR-2MustThe system shall persist plan approval state and plan artifacts (plan-md writeback) | Must | The system shall persist plan approval state and plan artifacts (plan-md writeback) |
| FR-3MustThe system shall run a planner overseer across `off`/`observe`/`steer`/`autonomous` levels with per-task overrides | Must | The system shall run a planner overseer across off/observe/steer/autonomous levels with per-task overrides |
| FR-4MustThe system shall gate merge/PRPull request and destructive actions behind a human confirmation where oversight level requires it | Must | The system shall gate merge/PRPull request and destructive actions behind a human confirmation where oversight level requires it |
| FR-5MustThe system shall record planner interventions and events, surfacing them as an Intervention Timeline in Task Detail | Must | The system shall record planner interventions and events, surfacing them as an Intervention Timeline in Task Detail |
| FR-6ShouldThe system shall withhold oversight actions for user-paused or auto-merge-off tasks (deduped event) | Should | The system shall withhold oversight actions for user-paused or auto-merge-off tasks (deduped event) |
| FR-7ShouldThe system shall recover planner handoffs and continuation across runs | Should | The system shall recover planner handoffs and continuation across runs |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustThe planner role must not be treated as a board column | Must | Correctness | The planner role must not be treated as a board column |
| NFR-2MustPlan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP state must survive engine restart (handoff recovery) | Must | Reliability | Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP state must survive engine restart (handoff recovery) |
| NFR-3ShouldOversight settings must be visible and togglable in Settings + Task Detail | Should | Usability | Oversight settings must be visible and togglable in Settings + Task Detail |
Constraints
- Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP is owned by a workflow-graph node; do not reintroduce an in-session review authority
- Being user-paused or auto-merge-off must withhold full oversight action
Acceptance Criteria
- FR-1MustThe system shall provide a Planning Mode chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node that produce and review a plan for a task
- Given a task in planning
- When Planning Mode is used
- Then a plan is drafted and reviewable at the Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node
- FR-3MustThe system shall run a planner overseer across `off`/`observe`/`steer`/`autonomous` levels with per-task overrides
- Given a configured oversight level
- When the planner produces work
- Then the overseer acts per the level and per-task override
- FR-4MustThe system shall gate merge/PRPull request and destructive actions behind a human confirmation where oversight level requires it
- Given a merge/PRPull request or destructive action with human confirmation required
- When the action is attempted
- Then it is held until a human confirms
- FR-5MustThe system shall record planner interventions and events, surfacing them as an Intervention Timeline in Task Detail
- Given interventions or events
- When Task Detail is opened
- Then the Intervention Timeline shows them
- NFR-1MustThe planner role must not be treated as a board column
- Given planner state
- When rendered
- Then the planner role is not represented as a board column
Conflicts
None identified yet.
Open Questions
- Which destructive actions are governed by default vs. opt-in confirmation?
Specification: Planning Mode & Planner Oversight
Overview
Planning is owned by a workflow-graph Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node, fed by a Planning Mode chat and a specification editor. An overseer controller in @fusion/core (state, events, interventions, recovery) plus engine planner lanes produce plan artifacts and record events; the dashboard surfaces Planning Mode, the Intervention Timeline, and oversight controls.
Architecture
Dashboard (PlanningModeModal, TaskPlannerChatTab, SpecEditor,
PlannerInterventionTimeline, plannerOverseerBadge)
│
▼
Dashboard APIApplication programming interface (register-planning-chat, register-planning-subtask-routes,
tasks-overseer-controls, tasks-planner-overseer-state)
│
▼
@fusion/core/planner (plan-approval, planner-confirmation,
planner-intervention, planner-overseer-state,
planner-overseer-events, planner-recovery, overseer-advice,
planning-plan-md)
│
▼
@fusion/engine (planner-lane-resolution, planning-handoff-recovery,
plan-review-continuation, plan-review-feedback-history,
plan-artifact-writeback, overseer/)
Data Models
Planner Oversight State
| Field | Type | Constraints | Description |
|---|---|---|---|
| oversightLevel | enum | not null | off / observe / steer / autonomous |
| perTaskOverride | enum | — | Per-task override of the global level |
| confirmation | object | — | Pending human confirmation for merge/PRPull request/destructive actions |
| interventions | array | — | Timeline of overseer interventions |
APIApplication programming interface Contracts
GET /api/tasks/:id/overseer-state
Response (200 OK)
| Field | Type | Description |
|---|---|---|
| oversightLevel | enum | Effective oversight level |
| interventions | array | Intervention timeline entries |
Sequences
Plan and review
Planning Mode → planner produces plan → Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node (workflow graph)
→ verdict approved / changes-requested
→ on failure: plan-replan → requestPreMergeOptionalStepFix → executor replan
Oversight action
overseer tick → evaluateOverseerHumanControl (guard) → withhold/steer/confirm
→ if user-paused/auto-merge-off → emit task:oversight-withheld-human-control (deduped)
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Oversight levels | off/observe/steer/autonomous | Escalating automation with a human gate at the top |
| Guard-first | evaluateOverseerHumanControl runs before classification |
Prevents actions on paused/auto-merge-off tasks |
| Graph-owned Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | workflow node | No duplicate review authority |
| Intervention Timeline | persisted interventions + events | Operator observability of overseer behavior |
Risks and Unknowns
- Confirmation state must survive engine restarts (handoff recovery), tracked by engine tests.
Out of Scope
- Plan execution (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p4) and merge mechanics (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p5)
Test Plan: Planning Mode & Planner Oversight
Scope
Covers plan approval, planner confirmation, overseer state/events, interventions, the human-control guard, handoff recovery, and dashboard control surfaces. Board move tests belong to FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p1.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Planner confirmation lifecycle | confirmation request | Pending → resolved confirmation |
| TC-2 | Planner intervention record | intervention | Timeline entry persisted |
| TC-3 | Overseer state transitions | oversight level change | State reflects override |
| TC-4 | Overseer events emitted | overseer action | Event recorded with ids/outcomes metadata |
| TC-5 | Planner recovery | interrupted handoff | Recovery enqueues continuation |
| TC-6 | Planner role is not a column | planner state | Not rendered as a board column |
| TC-7 | Oversight human-control guard | user-paused/auto-merge-off task | All oversight action withheld |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-8 | Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates runtime | engine running | Overseer tick acts per level |
| TC-9 | Overseer intervention wiring | steer level + intervention | Intervention routed to operator |
| TC-10 | Overseer runtime snapshot | active planner | Snapshot reflects runtime state |
| TC-11 | Executor live overseer retry gate | execution + overseer | Retry gated by overseer |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-12 | Overseer off cleanup | Cleanup removes overseer state |
| TC-13 | Plan-review failure | Replan via plan-replan seam |
Test Infrastructure
- Vitest in core/engine/dashboard suites;
planner-overseer-*.test.tsfamily
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall provide a Planning Mode chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node that produce and review a plan for a task | TC-13 |
| FR-2MustThe system shall persist plan approval state and plan artifacts (plan-md writeback) | TC-1, TC-5 |
| FR-3MustThe system shall run a planner overseer across `off`/`observe`/`steer`/`autonomous` levels with per-task overrides | TC-3, TC-4, TC-8, TC-9, TC-10 |
| FR-4MustThe system shall gate merge/PRPull request and destructive actions behind a human confirmation where oversight level requires it | TC-11 |
| FR-5MustThe system shall record planner interventions and events, surfacing them as an Intervention Timeline in Task Detail | TC-2, TC-4 |
| FR-6ShouldThe system shall withhold oversight actions for user-paused or auto-merge-off tasks (deduped event) | TC-7 |
| NFR-1MustThe planner role must not be treated as a board column | TC-6 |
Key Test Files
packages/core/src/__tests__/planner-confirmation.test.ts,planner-intervention.test.ts,planner-overseer-events.test.ts,planner-overseer-state.test.ts,planner-recovery.test.ts,overseer-emission-guard.test.ts,planner-role-is-not-a-column.test.tspackages/engine/src/__tests__/planner-overseer.test.ts,planner-overseer-off-cleanup.test.ts,planner-overseer-intervention-wiring.test.ts,planner-overseer-runtime-snapshot.test.ts,executor-live-overseer-retry-gate.test.tspackages/dashboard/src/routes/__tests__/tasks-overseer-controls.test.ts,tasks-planner-overseer-state.test.ts,register-planning-subtask-routes.parent-close.test.ts
requirements
- Which destructive actions are governed by default vs. opt-in confirmation?
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Agent Execution Engine
Overview
The execution engine is the multi-agent runtime: the scheduler and triage pull eligible tasks into execution, the executor claims and drives permission-bounded agent sessions, durable agents run on heartbeats and auto-recover from error states, and permission policies and sandboxes constrain what agents can do.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Manages agents, presets, permissions, and watches runs |
| Agent | Executes tasks under a bounded permission policy |
| Enterprise/security | Enforces permission policy and command sandboxing |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall triage eligible tasks and schedule them into execution respecting capacity and dependencies | Must | The system shall triage eligible tasks and schedule them into execution respecting capacity and dependencies |
| FR-2MustThe executor shall create and drive permission-bounded agent sessions for claimed tasks | Must | The executor shall create and drive permission-bounded agent sessions for claimed tasks |
| FR-3MustDurable agents shall run on heartbeats and auto-recover from recoverable error states up to a bounded budget | Must | Durable agents shall run on heartbeats and auto-recover from recoverable error states up to a bounded budget |
| FR-4MustThe system shall enforce agent permission policies and presets | Must | The system shall enforce agent permission policies and presets |
| FR-5MustThe system shall isolate executor commands via pluggable sandbox backends | Must | The system shall isolate executor commands via pluggable sandbox backends |
| FR-6ShouldThe system shall expose agent management (list, detail, new, permission editing) in the dashboard | Should | The system shall expose agent management (list, detail, new, permission editing) in the dashboard |
| FR-7ShouldThe system shall record run-audit events for task lifetime and agent actions with ids/counts/outcomes-only metadata | Should | The system shall record run-audit events for task lifetime and agent actions with ids/counts/outcomes-only metadata |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustHeartbeats and self-healing shall not move user-paused or operator-actionable-parked agents backward | Must | Reliability | Heartbeats and self-healing shall not move user-paused or operator-actionable-parked agents backward |
| NFR-2MustSandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode boundaries must be applied before executing user-provided commands | Must | Security | SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode boundaries must be applied before executing user-provided commands |
| NFR-3MustExecutor must not use `execSync` for user-configured commands | Must | Maintainability | Executor must not use execSync for user-configured commands |
Constraints
task.status === "needs-review"/needs-replanare graph signals, not legacy; their writers must remain- Task-review and executor mechanics live in the engine; the dashboard only reads via the domain APIApplication programming interface
- Modal review of execution is owned by workflow nodes; not reintroduce a second authority
Acceptance Criteria
- FR-1MustThe system shall triage eligible tasks and schedule them into execution respecting capacity and dependencies
- Given eligible tasks
- When triage/scheduler run
- Then tasks are claimed and scheduled within capacity, respecting dependencies
- FR-2MustThe executor shall create and drive permission-bounded agent sessions for claimed tasks
- Given a claimed task
- When the executor runs
- Then a permission-bounded agent session is created and driven to completion
- FR-3MustDurable agents shall run on heartbeats and auto-recover from recoverable error states up to a bounded budget
- Given a durable agent in a recoverable error state
- When the heartbeat timer or self-healing sweep runs
- Then it clears the error and retries up to the shared budget, or parks on exhaustion
- FR-4MustThe system shall enforce agent permission policies and presets
- Given a restricted action
- When the agent attempts it
- Then permission policy blocks or prompts per the policy
- FR-5MustThe system shall isolate executor commands via pluggable sandbox backends
- Given a user-configured command
- When executed
- Then it runs under the configured sandbox backend
- NFR-2MustSandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode boundaries must be applied before executing user-provided commands
- Given a sandboxed command
- When execution begins
- Then the sandbox boundary is enforced
Conflicts
None identified yet.
Open Questions
- The precise capacity/claim accounting across solver lanes is under
.docs/agents.mdand settings reference.
Specification: Agent Execution Engine
Overview
The engine's scheduler and triage claim eligible tasks; the executor creates permission-bounded agent sessions and drives them in git worktrees; durable agents run on heartbeats with bounded auto-recovery; permission policies and sandboxes constrain commands; and every lifecycle event is recorded in the run-audit.
Architecture
scheduler / triage ── claim/lease ──► executor (task session, worktree)
│ │
│ agent session
│ ▼
capacity/caps permission policy + sandbox backend
│ │
▼ ▼
task store (advisory locks, run-audit) agent heartbeat (durable agents)
Data Models
Agent
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | string | PK | Agent identifier |
| status | enum | not null | idle/active/error/paused |
| pauseReason | enum | — | error-retry-exhausted, error-unrecoverable, etc. |
| permissionPolicy | object | not null | Bounded tool/action policy |
APIApplication programming interface Contracts
POST /api/agents
Request
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | yes | Agent name |
| model | string | no | Assigned model |
Response (200 OK)
| Field | Type | Description |
|---|---|---|
| agent | object | Created agent |
Sequences
Execution
triage → scheduler claim → executor creates session
→ permission check per tool → sandbox (bubblewrap/spawn) → agent runs
→ verdict → task advances (workflow graph) → run-audit events
Durable recovery
heartbeat → error state → recoverable? → clear + retry (shared budget)
→ exhausted → park paused (pauseReason: error-retry-exhausted)
→ operator-actionable → park (pauseReason: error-unrecoverable)
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Async exec for user commands | async exec with timeout |
No blocking shellout for user config |
| superviseSpawn for children | from @fusion/core |
Managed child processes, no nohup/detached spawn |
| Shared heartbeat budget | timer + self-healing + automation | Bounded recovery; single exhaustion point |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode pluggable | bubblewrap / spawn-based | Command isolation backends |
Risks and Unknowns
- ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners/capacity accounting across lanes is detailed in scheduler tests and docs/agents.md.
Out of Scope
- Merge mechanics (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p5) and planner oversight (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p3)
Test Plan: Agent Execution Engine
Scope
Covers triage/scheduler claiming, executor session driving, permission policy enforcement, sandbox isolation, agent heartbeat recovery, and run-audit emission. Merge and review nodes belong to FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p5.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Agent permission policy | restricted action | Action blocked/prompted per policy |
| TC-2 | Agent store routing policy | agent config | Correct lane routing |
| TC-3 | Assigned-task ranking (triage) | task candidates | Ranked claim order |
| TC-4 | SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode audit on routine runner | sandboxed command | SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode applied, audit recorded |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-5 | Scheduler auto-claim invalidation | stale claim | ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners invalidated |
| TC-6 | Executor approval gate | gated task | Held until approval |
| TC-7 | Agent heartbeat procedures | durable agent | Heartbeat moves work / parks correctly |
| TC-8 | Triage column audit | triage run | ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column assignment correct |
| TC-9 | Scheduler paused dispatch refusal | paused task | Dispatch refused |
| TC-10 | Scheduler fanout escalation lanes | overloaded lane | Escalation applies |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-11 | Agent heartbeat error recovery | Recoverable → retry; exhausted → parked paused |
| TC-12 | Deleted blocker wip dependent | Scheduler avoids deadlock |
| TC-13 | Node unreachable during scheduling | Claims audited, no loss |
Test Infrastructure
- Vitest engine/core suites; PostgreSQL-backed where required; fake timers for heartbeat
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall triage eligible tasks and schedule them into execution respecting capacity and dependencies | TC-3, TC-5, TC-8, TC-9, TC-10 |
| FR-2MustThe executor shall create and drive permission-bounded agent sessions for claimed tasks | TC-6 |
| FR-3MustDurable agents shall run on heartbeats and auto-recover from recoverable error states up to a bounded budget | TC-7, TC-11 |
| FR-4MustThe system shall enforce agent permission policies and presets | TC-1, TC-2 |
| FR-5MustThe system shall isolate executor commands via pluggable sandbox backends | TC-4 |
| FR-7ShouldThe system shall record run-audit events for task lifetime and agent actions with ids/counts/outcomes-only metadata | TC-12, TC-13 |
Key Test Files
packages/engine/src/__tests__/triage-*.test.ts,executor-*.test.ts,agent-heartbeat-*.test.ts,scheduler-*.test.ts,routine-runner.test.ts,routine-runner-sandbox-audit.test.tspackages/core/src/__tests__/agent-permissions.test.ts,agent-permission-policy.test.ts,agent-store-routing-policy.test.ts,assigned-task-ranking.test.tspackages/dashboard/src/routes/__tests__/agent-core-routes.test.ts,agent-onboarding-routes.test.tspackages/dashboard/app/__tests__/agent-runs-ui.test.ts,agent-detail-settings-theme-styling.test.ts
requirements
- The precise capacity/claim accounting across solver lanes is under
.docs/agents.mdand settings reference.
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Automated Code Review, Merge & PRPull request
Overview
Fusion takes finished branches through automated code review, safe merges into the default branch (squash, rebase, PRPull request paths), and GitHub/GitLab PRPull request creation and monitoring. The merger and PRPull request automation apply file-scope, lineage, and diff-volume guards and resolve conflicts to land reviewed work without manual merge work.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Approves merges/PRs, monitors PRs, reads merge advance notice |
| Reviewer | Reviews the branch at the graph review node |
| VCS system | GitHub/GitLab hosting for PRs and branches |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall run code review as a workflow-graph node before merge | Must | The system shall run code review as a workflow-graph node before merge |
| FR-2MustThe system shall merge finished branches into the default branch with a configurable commit strategy (squash default) | Must | The system shall merge finished branches into the default branch with a configurable commit strategy (squash default) |
| FR-3MustThe system shall resolve merge conflicts and reconcile divergent branches (auto-prerebase, smart pull) | Must | The system shall resolve merge conflicts and reconcile divergent branches (auto-prerebase, smart pull) |
| FR-4MustThe system shall enforce file-scope, overlap-guard, and diff-volume gates before forming a squash commit | Must | The system shall enforce file-scope, overlap-guard, and diff-volume gates before forming a squash commit |
| FR-5MustThe system shall drive GitHub/GitLab PRs: create, monitor, respond, finalize | Must | The system shall drive GitHub/GitLab PRs: create, monitor, respond, finalize |
| FR-6ShouldThe system shall detect already-merged/landed branches and skip or classify accordingly | Should | The system shall detect already-merged/landed branches and skip or classify accordingly |
| FR-7ShouldThe system shall expose merge advance notice and merge detail surfaces in the dashboard | Should | The system shall expose merge advance notice and merge detail surfaces in the dashboard |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustEvery squash commit must overlap the task file-scope; violations fail with FileScopeViolationError | Must | Correctness | Every squash commit must overlap the task file-scope; violations fail with FileScopeViolationError |
| NFR-2MustEmpty cherry-picks are no-ops; duplicate on-main commits are dropped before merging | Must | Integrity | Empty cherry-picks are no-ops; duplicate on-main commits are dropped before merging |
| NFR-3MustPost-squash audit policy (`warn`/`block`/`off`) must be respected | Must | Reliability | Post-squash audit policy (warn/block/off) must be respected |
| NFR-4MustTriple-proof must protect against moving a user-paused or auto-merge-off branch backward | Must | Liveness | Triple-proof must protect against moving a user-paused or auto-merge-off branch backward |
Constraints
- Prefer squash by default; history-preserving merges require opt-in strategy
- Never force-add ignored artifacts on squash merges
- GitLab parity is tracked as a first-class supported surface (
docs/gitlab-parity-inventory.md)
Acceptance Criteria
- FR-1MustThe system shall run code review as a workflow-graph node before merge
- Given a finished branch
- When the review node runs
- Then a review verdict is produced before merge consideration
- FR-2MustThe system shall merge finished branches into the default branch with a configurable commit strategy (squash default)
- Given an approved branch
- When merge proceeds
- Then it lands in the default branch under the configured strategy
- FR-4MustThe system shall enforce file-scope, overlap-guard, and diff-volume gates before forming a squash commit
- Given a branch whose changed files are out of the task file-scope
- When merge runs
- Then the squash is rejected with a FileScopeViolationError
- FR-5MustThe system shall drive GitHub/GitLab PRs: create, monitor, respond, finalize
- Given a PRPull request to open
- When the PRPull request monitor runs
- Then a PRPull request is created, monitored, and finalized
- NFR-1MustEvery squash commit must overlap the task file-scope; violations fail with FileScopeViolationError
- Given merged changes
- When the commit is formed
- Then the scope/invariant holds on the squash commit
Conflicts
None identified yet.
Open Questions
- Which auto-merge policies require explicit operator opt-in versus default?
Specification: Automated Code Review, Merge & PRPull request
Overview
Review runs as a workflow-graph node (review), then the merger lands finished branches: squash by default, with rebase/PRPull request paths, conflict resolution, smart-pull/auto-prerebase, and a stack of guards (file-scope, overlap, diff-volume, lineage). PRPull request automation drives GitHub/GitLab create/monitor/respond/finalize.
Architecture
workflow graph ── review node (workflow-review-service) ──► verdict
│
▼
merger (merger.ts + merge/) ── squash/rebase/PRPull request
│ guards: file-scope, overlap, diff-volume, lineage, post-squash audit
▼
default branch / PRPull request (GitHub | GitLab) ── pr-monitor, pr-nodes, pr-response-run
Data Models
Merge Plan / Branch Group
| Field | Type | Constraints | Description |
|---|---|---|---|
| taskId | int | PK | Task being merged |
| branchName | string | not null | Working branch / shared-branch-group |
| strategy | enum | not null | always-squash / auto / always-rebase |
| landedSha | string | — | Commit SHA after landing |
Sequences
Merge
approval → merge-active → pre-merge review node
→ guard checks (file-scope overlap diff-volume)
→ auto-prerebase/smart-pull on divergence
→ squash commit (default) → post-squash audit (warn/block/off)
→ push → verify → in-review/done
PRPull request lifecycle
pr-create node → PRPull request monitor → PRPull request checks → response-run → finalize → merge
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Squash default | directMergeCommitStrategy="always-squash" |
Clean history; opt-in for multi-commit |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges invariant | FileScopeViolationError |
Prevents out-of-scope changes landing |
| Smart prefer-main overlap | overlap-guard flip | Recent main overlap can favor branch |
| Post-squash audit | warn/block/off modes | Prevents suspicious shrinkage |
Risks and Unknowns
- Divergent push races are handled by recovery-branch safety refs and push:origin aborted outcomes.
Out of Scope
- Planner oversight gates (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p3) and the board surface (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p1)
Test Plan: Automated Code Review, Merge & PRPull request
Scope
Covers review-node verdicts, merge strategies and conflict resolution, merge guards (file-scope, overlap, diff-volume, lineage), post-squash audit, smart-pull/auto-prerebase, already-merged detection, and PRPull request create/monitor/finalize.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges invariant on squash | out-of-scope files | FileScopeViolationError |
| TC-2 | Already-merged detector | landed branch | Classified landed, skipped |
| TC-3 | Empty cherry-pick | no-op commit | No empty commit created |
| TC-4 | Diff-volume gate | suspicious shrinkage | Squash blocked |
| TC-5 | Overlap guard | recent main overlap | Flip to prefer-branch when smart |
| TC-6 | Merge advance events | merge plan | Events emitted |
| TC-7 | Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) retry cap settings | retryable merge | Retry up to cap then park |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-8 | MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards conflict resolution | conflict on branch | Resolved and merged |
| TC-9 | Auto-prerebase on divergence | divergent branch | Fast-forward reconciled |
| TC-10 | Commit strategy real-git | rebase vs squash | Correct commit topology |
| TC-11 | PRPull request monitor response run | PRPull request updated | Monitor responds and finalizes |
| TC-12 | Merge advance notice route | merge in progress | Advance notice served |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-13 | Duplicate commits on main | Dropped before merging |
| TC-14 | Push divergence after merge | Recovery-branch safety ref; non-fatal aborted push |
| TC-15 | ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point auto-recovery | First pass bounded; repeated escalates |
Test Infrastructure
- Vitest engine suite; real-git tests (
merger-*.real-git.test.ts); slow variants for dependency installs
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall run code review as a workflow-graph node before merge | TC-2 |
| FR-2MustThe system shall merge finished branches into the default branch with a configurable commit strategy (squash default) | TC-8, TC-10 |
| FR-3MustThe system shall resolve merge conflicts and reconcile divergent branches (auto-prerebase, smart pull) | TC-9 |
| FR-4MustThe system shall enforce file-scope, overlap-guard, and diff-volume gates before forming a squash commit | TC-1, TC-4, TC-5 |
| FR-5MustThe system shall drive GitHub/GitLab PRs: create, monitor, respond, finalize | TC-11 |
| FR-6ShouldThe system shall detect already-merged/landed branches and skip or classify accordingly | TC-2, TC-13 |
| FR-7ShouldThe system shall expose merge advance notice and merge detail surfaces in the dashboard | TC-6, TC-12 |
| NFR-1MustEvery squash commit must overlap the task file-scope; violations fail with FileScopeViolationError | TC-1 |
| NFR-2MustEmpty cherry-picks are no-ops; duplicate on-main commits are dropped before merging | TC-3, TC-13 |
| NFR-3MustPost-squash audit policy (`warn`/`block`/`off`) must be respected | TC-15 |
Key Test Files
packages/engine/src/__tests__/merger-*.test.ts,already-merged-detector.real-git.test.ts,auto-merge-fact-providers.test.ts,auto-merge-retry-cap-settings.test.ts,smart-pull/pr-*testspackages/dashboard/src/routes/__tests__/register-task-workflow-routes.merge-advance-events.test.ts,...merge.test.ts,task-review-routes.test.tspackages/cli/src/commands/__tests__/pr-lock-retry.test.ts,git.test.ts
requirements
- Which auto-merge policies require explicit operator opt-in versus default?
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Missions, GoalsMeasurable objectives tracked in the dashboard with a refinement gate, ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context & EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance
Overview
A product-hierarchy layer (missions → milestones → features) drives task work, optionally fueled by goals anchors, research runs, and evals. Missions break into milestones and features, research produces cited findings, goals anchor objectives, and evolutions score task outcomes.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Program/PM | Defines missions, milestones, features, goals/KRs |
| Researcher | Runs research and exports findings |
| Evaluator | Scores task outcomes with evidence |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall model the hierarchy mission → milestone → feature and track their progress | Must | The system shall model the hierarchy mission → milestone → feature and track their progress |
| FR-2MustThe system shall sync missions, features, and their state on the board and drive them via autopilot/execution loops | Must | The system shall sync missions, features, and their state on the board and drive them via autopilot/execution loops |
| FR-3MustThe system shall manage goals, objectives, and key results with citation extraction and anchoring | Must | The system shall manage goals, objectives, and key results with citation extraction and anchoring |
| FR-4MustThe system shall run research/broadly-scoped research (research store, orchestrator, step-runner, providers) and manage findings | Must | The system shall run research/broadly-scoped research (research store, orchestrator, step-runner, providers) and manage findings |
| FR-5ShouldThe system shall score task/feature outcomes via evals with evidence persistence | Should | The system shall score task/feature outcomes via evals with evidence persistence |
| FR-6ShouldThe system shall expose missions, goals, research, and evals in dashboard views (MissionManager, GoalsView, ResearchView) | Should | The system shall expose missions, goals, research, and evals in dashboard views (MissionManager, GoalsView, ResearchView) |
| FR-7ShouldThe system shall integrate missions and research with task execution | Should | The system shall integrate missions and research with task execution |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustRun-audit events from missions/research must hold ids/counts/outcomes-only metadata (never prose) | Must | Consistency | Run-audit events from missions/research must hold ids/counts/outcomes-only metadata (never prose) |
| NFR-2MustFeature IDs for milestones must be converted/anchored to board tasks deterministically | Must | Correctness | Feature IDs for milestones must be converted/anchored to board tasks deterministically |
| NFR-3ShouldResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context steps must not block unrelated task lane work | Should | Performance | ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context steps must not block unrelated task lane work |
Constraints
- ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context/experiment sessions use
research_*for cited search/synthesis andexperiment_session_*for upstream parity - Mission completion gates are governed by a documented contract (
docs/missions-completion-contract.md)
Acceptance Criteria
- FR-1MustThe system shall model the hierarchy mission → milestone → feature and track their progress, FR-2MustThe system shall sync missions, features, and their state on the board and drive them via autopilot/execution loops
- Given a mission with milestones/features and project context
- When the mission autopilot/execution loop runs
- Then attached board tasks and features progress per the mission plan and sync state
- FR-3MustThe system shall manage goals, objectives, and key results with citation extraction and anchoring
- Given goals and objectives
- When citation extraction runs
- Then goals are anchored to evidence
- FR-4MustThe system shall run research/broadly-scoped research (research store, orchestrator, step-runner, providers) and manage findings
- Given a research request
- When research runs
- Then a research run is persisted with findings
- FR-5ShouldThe system shall score task/feature outcomes via evals with evidence persistence
- Given a task to score
- When an eval runs
- Then a scored outcome is persisted with evidence and the intended reason + acceptance
Conflicts
None identified yet.
Open Questions
- How are
evaluationsandinsightsintegrated routers wired (primary surface for each) — a concrete focus area identified at sync, awaiting mapping. - The exact KPIs/KRs that anchor goal refinement are not fully instrumented.
Specification: Missions, GoalsMeasurable objectives tracked in the dashboard with a refinement gate, ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context & EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance
Overview
Missions (mission → milestone → feature) are modeled in @fusion/core and driven by engine autopilot/execution loops with board sync. GoalsMeasurable objectives tracked in the dashboard with a refinement gate add objectives/KRs with citation extraction. ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context runs are orchestrated with providers and step runners. EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance score outcomes with persisted evidence. Dashboard views surface all four.
Architecture
Dashboard (MissionManager, GoalsView, ResearchView, MissionInterviewModal)
│ integrated routers (register-integrated-routers)
▼
@fusion/core (mission-store, goal-store, research-store)
│
▼
@fusion/engine (mission-autopilot, mission-execution-loop, mission-feature-sync,
mission-verification, mission-symbol-admission,
goal-*, research-orchestrator/step-runner/dispatcher, eval-*)
Data Models
Mission / Milestone / Feature
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | string | PK | Mission id |
| milestone | object | — | Milestones with their features |
| feature | object | — | Feature synced to board task |
| progress | int | — | Completion-derived progress |
APIApplication programming interface Contracts
GET /api/missions/:id
Response (200 OK)
| Field | Type | Description |
|---|---|---|
| mission | object | Mission with milestones/features |
Sequences
Mission autopilot
mission → autopilot → features synced to board → execution loop → verification
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Hierarchy in core store | mission-store.ts |
Single domain model |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes in engine | mission-autopilot.ts |
Drives execution outside domain |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context orchestrator | engine providers | Cited-search/synthesis + experiment sessions |
| Run-audit hygiene | ids/counts/outcomes only | Never persist prose or research prompt text |
Risks and Unknowns
evaluationsandinsightsintegrated routers are not fully mapped to a canonical feature surface at sync time.
Out of Scope
- Board rendering (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p1) and execution engine (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p4) internals
Test Plan: Missions, GoalsMeasurable objectives tracked in the dashboard with a refinement gate, ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context & EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance
Scope
Covers mission hierarchy and sync, mission autopilot and execution loop, goals/citations/anchoring, research orchestration and providers, and eval follow-ups. Board and merge mechanics belong to FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p1/FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p5.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Mission store validation diagnostics | invalid mission | Diagnostic error |
| TC-2 | Mission store sync auto-merge | mission sync | Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) transition applied |
| TC-3 | Mission store sync loop transition | loop transition | State machine advances |
| TC-4 | Goal citation extraction | goals text | Citations extracted |
| TC-5 | Goal citation audit aggregation | citations | Aggregated audit output |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-6 | Mission autopilot | mission with features | Features sync to board tasks |
| TC-7 | Mission execution loop | autopilot active | Loop drives feature execution |
| TC-8 | Mission scheduler | schedulable missions | Scheduled per policy |
| TC-9 | Mission feature sync | feature changes | Board reflects sync |
| TC-10 | Mission verification | completed feature | Verification gate runs |
| TC-11 | Goal context injection | active goal | Context injected into sessions |
| TC-12 | Goal anchoring audit | goal anchors | Anchoring audit passes |
| TC-13 | Eval follow-ups | scored task | Follow-ups enqueued |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-14 | Duplicate mission feature | Deduplicated / diagnostic |
| TC-15 | ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context provider failure | Step-runner handles and reports |
Test Infrastructure
- Vitest in core/engine/dashboard; engine mission/goal/research suites
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall model the hierarchy mission → milestone → feature and track their progress | TC-1, TC-2, TC-3 |
| FR-2MustThe system shall sync missions, features, and their state on the board and drive them via autopilot/execution loops | TC-6, TC-7, TC-8, TC-9 |
| FR-3MustThe system shall manage goals, objectives, and key results with citation extraction and anchoring | TC-4, TC-5, TC-11, TC-12 |
| FR-4MustThe system shall run research/broadly-scoped research (research store, orchestrator, step-runner, providers) and manage findings | TC-15 |
| FR-5ShouldThe system shall score task/feature outcomes via evals with evidence persistence | TC-13 |
| FR-6ShouldThe system shall expose missions, goals, research, and evals in dashboard views (MissionManager, GoalsView, ResearchView) | TC-14 |
Key Test Files
packages/core/src/__tests__/mission-store.*.test.ts,goal-citation-extractor.test.ts,goal-citation-audit-aggregation.test.tspackages/engine/src/__tests__/mission-autopilot.test.ts,mission-execution-loop.test.ts,mission-scheduler.test.ts,mission-feature-sync*.test.ts,mission-verification*.test.ts,goal-*.test.ts,eval-followups.test.tspackages/dashboard/src/routes/__tests__/mission-*.test.ts, research route testspackages/dashboard/app/__tests__/api-missions.test.ts;packages/cli/src/commands/__tests__/research.test.ts
requirements
- How are
evaluationsandinsightsintegrated routers wired (primary surface for each) — a concrete focus area identified at sync, awaiting mapping. - The exact KPIs/KRs that anchor goal refinement are not fully instrumented.
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage & Operational Monitoring
Overview
The Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage is the operator "mission control" surface for the agent fleet: fleet health, usage and cost per task, system diagnostics, and external signal connectors (Sentry/Datadog/PagerDuty/generic webhooks) that flow into the board and command surfaces.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Monitors fleet health, usage/cost, and signals in one place |
| Cost/ops | Tracks token usage and per-task cost |
| External systems | Sends HMACHash-based message authentication code-signed signal events into Fusion |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall provide a Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage view with fleet and health surfaces | Must | The system shall provide a Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage view with fleet and health surfaces |
| FR-2MustThe system shall track usage and cost per task (token usage, cost tabs, usage indicator) | Must | The system shall track usage and cost per task (token usage, cost tabs, usage indicator) |
| FR-3MustThe system shall receive HMACHash-based message authentication code-signed external signal connectors (Sentry/Datadog/PagerDuty/webhooks) and map payloads | Must | The system shall receive HMACHash-based message authentication code-signed external signal connectors (Sentry/Datadog/PagerDuty/webhooks) and map payloads |
| FR-4MustThe system shall expose diagnostics and monitor routes for system health | Must | The system shall expose diagnostics and monitor routes for system health |
| FR-5ShouldThe system shall stream realtime status via the shared `/api/events` SSEServer-sent events bus | Should | The system shall stream realtime status via the shared /api/events SSEServer-sent events bus |
| FR-6ShouldThe system shall expose usage/signals/monitor data through dashboard APIApplication programming interface route registrars | Should | The system shall expose usage/signals/monitor data through dashboard APIApplication programming interface route registrars |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustSignal connectors must verify HMACHash-based message authentication code signatures before accepting payloads | Must | Security | Signal connectors must verify HMACHash-based message authentication code signatures before accepting payloads |
| NFR-2MustMonitoring/usage reads must not degrade dashboard interactive latency | Must | Performance | Monitoring/usage reads must not degrade dashboard interactive latency |
| NFR-3ShouldHealth surfaces must degrade gracefully when a node is unreachable | Should | Availability | Health surfaces must degrade gracefully when a node is unreachable |
Constraints
- Port 4040 is reserved; monitoring tools must not bind it
- Usage/cost data is read-only outside the engine's accounting writer
Acceptance Criteria
- FR-1MustThe system shall provide a Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage view with fleet and health surfaces
- Given an operator
- When the Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage is opened
- Then fleet/health surfaces render from monitor data
- FR-2MustThe system shall track usage and cost per task (token usage, cost tabs, usage indicator)
- Given executed tasks
- When the usage view is opened
- Then per-task cost and usage are shown
- FR-3MustThe system shall receive HMACHash-based message authentication code-signed external signal connectors (Sentry/Datadog/PagerDuty/webhooks) and map payloads
- Given an HMACHash-based message authentication code-signed signal payload
- When a signal connector receives it
- Then it is verified and mapped into the board/command surface
- NFR-1MustSignal connectors must verify HMACHash-based message authentication code signatures before accepting payloads
- Given an unsigned signal payload
- When a signal connector receives it
- Then it is rejected
Conflicts
None identified yet.
Open Questions
- Which usage metrics are authoritative for cost accounting (token counts vs. provider billing)?
Specification: Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage & Operational Monitoring
Overview
The Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage (packages/dashboard/app/components/command-center/) surfaces fleet health; usage/cost route registrars track per-task usage; signal connectors accept HMACHash-based message authentication code-signed payloads; and monitor/diagnostics routes report system health. Real-time status flows over the shared /api/events SSEServer-sent events bus.
Architecture
Dashboard CommandCenter (components/command-center + monitor routes)
│ register-command-center-routes, register-usage-routes,
│ register-signal-routes, monitor-routes, register-diagnostics-routes
▼
Signal connectors (HMACHash-based message authentication code verify) ──► board/command surface
│ /api/events (SSEServer-sent events)
▼
@fusion/core task store (usage/cost accounting)
Data Models
Usage / Cost
| Field | Type | Constraints | Description |
|---|---|---|---|
| taskId | int | PK/FK | Task the usage pertains to |
| tokens | json | — | Input/output token totals per model |
| costMs | int | — | Computed cost in ms-equivalent |
APIApplication programming interface Contracts
POST /api/signals/
Request
| Field | Type | Required | Description |
|---|---|---|---|
| type | enum | yes | sentry / datadog / pagerduty / webhook |
| payload | object | yes | Signal payload |
| signature | string | yes | HMACHash-based message authentication code signature |
Response
| Status | Code | Description |
|---|---|---|
| 202 | ACCEPTED | Signal accepted |
| 401 | UNAUTHORIZED | HMACHash-based message authentication code verification failed |
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| HMACHash-based message authentication code signing | docs/signals-connectors.md |
Authenticates payload origin |
| Realtime over SSEServer-sent events | shared /api/events |
Single event stream for status |
| Cost in core | task store accounting | Read-only outside writer |
Risks and Unknowns
- Cost accounting basis (token vs. billing) is unresolved; tracked in requirements.
Out of Scope
- Executor internals (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p4) and merge mechanics (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p5)
Test Plan: Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage & Operational Monitoring
Scope
Covers the Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage fleet/health surfaces, usage and cost tracking, HMACHash-based message authentication code signal connectors, and monitor/diagnostics routes.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Signal connector route validation | valid/invalid type | 202 for valid, 401/400 otherwise |
| TC-2 | Usage/cost accounting | task tokens | Per-task usage/cost rows |
| TC-3 | Monitor route health | system snapshot | Health payload rendered |
| TC-4 | Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage controls CSS contract | control styles | Tokens applied per contract |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-5 | Signal payload mapped to board | HMACHash-based message authentication code-signed payload | Board/command surface updated |
| TC-6 | Usage route from live store | executed tasks | Usage data served |
| TC-7 | Diagnostics routes | engine running | Diagnostics served |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-8 | Unsigned signal | Rejected 401 |
| TC-9 | Unreachable node in health | Degrades gracefully |
Test Infrastructure
- Vitest dashboard suites; command-center component interactive tests
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall provide a Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage view with fleet and health surfaces | TC-3, TC-4 |
| FR-2MustThe system shall track usage and cost per task (token usage, cost tabs, usage indicator) | TC-2, TC-6 |
| FR-3MustThe system shall receive HMACHash-based message authentication code-signed external signal connectors (Sentry/Datadog/PagerDuty/webhooks) and map payloads | TC-1, TC-5, TC-8 |
| FR-4MustThe system shall expose diagnostics and monitor routes for system health | TC-7 |
| NFR-1MustSignal connectors must verify HMACHash-based message authentication code signatures before accepting payloads | TC-8 |
Key Test Files
packages/dashboard/src/routes/__tests__/register-signal-routes*.test.ts,codebase-metrics-route.test.ts,register-system-maintenance-routes.test.tspackages/dashboard/app/components/command-center/__tests__/*,packages/dashboard/app/__tests__/usage-*.test
requirements
- Which usage metrics are authoritative for cost accounting (token counts vs. provider billing)?
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies, Settings & Provider Configuration
Overview
Fusion ships an encrypted secrets store with per-secret access policies, a global/project settings system with sync, model/provider credential management, and MCPModel Context Protocol server configuration. These surfaces are exposed through the Settings modal, CLICommand-line interface commands, and APIApplication programming interface routes, and constrain how agents access credentials and models.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Manages settings, secrets, providers, MCPModel Context Protocol servers, and model selection |
| Agents | Resolve provider/model and secret references during execution |
| Security | Enforces access policies on secret scopes |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall store secrets encrypted at rest with AES-256-GCM under scopes with access policies | Must | The system shall store secrets encrypted at rest with AES-256-GCM under scopes with access policies |
| FR-2MustThe system shall manage global and project settings with sync and precedence resolution | Must | The system shall manage global and project settings with sync and precedence resolution |
| FR-3MustThe system shall manage provider/model credentials with instance rotation and fallback resolution | Must | The system shall manage provider/model credentials with instance rotation and fallback resolution |
| FR-4MustThe system shall configure and validate MCPModel Context Protocol servers, including secret references and CLICommand-line interface/dashboard import/export | Must | The system shall configure and validate MCPModel Context Protocol servers, including secret references and CLICommand-line interface/dashboard import/export |
| FR-5MustThe system shall expose secrets/settings/mcp/provider operations via CLICommand-line interface, dashboard APIApplication programming interface, and Settings modal | Must | The system shall expose secrets/settings/mcp/provider operations via CLICommand-line interface, dashboard APIApplication programming interface, and Settings modal |
| FR-6ShouldThe system shall resolve the model-selection hierarchy (global→project→task→lane) per settings reference | Should | The system shall resolve the model-selection hierarchy (global→project→task→lane) per settings reference |
| FR-7ShouldThe system shall record credential rotation in the run-audit with append-only ids/counts/outcomes metadata | Should | The system shall record credential rotation in the run-audit with append-only ids/counts/outcomes metadata |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustCredential material must never be persisted in run-audit or logs | Must | Security | Credential material must never be persisted in run-audit or logs |
| NFR-2MustSecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies must be masked/redacted in settings UIUser interface and CLICommand-line interface output | Must | Security | SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies must be masked/redacted in settings UIUser interface and CLICommand-line interface output |
| NFR-3MustSettings sync must reconcile across nodes/projects without clobbering | Must | Reliability | Settings sync must reconcile across nodes/projects without clobbering |
| NFR-4ShouldThe onboarding wizard should guide provider setup with a quick-start list | Should | Usability | The onboarding wizard should guide provider setup with a quick-start list |
Constraints
- SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies master-key handling and scopes are documented in
docs/secrets.mdanddocs/architecture.md - Model resolution precedence is defined in
docs/settings-reference.md
Acceptance Criteria
- FR-1MustThe system shall store secrets encrypted at rest with AES-256-GCM under scopes with access policies
- Given a secret with a scope
- When stored
- Then it is encrypted at rest and only readable per its access policy
- FR-2MustThe system shall manage global and project settings with sync and precedence resolution
- Given global and project settings
- When read
- Then precedence is resolved per the settings reference
- FR-3MustThe system shall manage provider/model credentials with instance rotation and fallback resolution
- Given multiple provider instances
- When rotation/fallback applies
- Then instances rotate with append-only run-audit records
- FR-4MustThe system shall configure and validate MCPModel Context Protocol servers, including secret references and CLICommand-line interface/dashboard import/export
- Given an MCPModel Context Protocol server config
- When validated
- Then invalid configs are rejected with clear errors
- NFR-1MustCredential material must never be persisted in run-audit or logs
- Given credential rotation
- When audit records are written
- Then no secret material appears in the audit
Conflicts
None identified yet.
Open Questions
- How does secrets sync between nodes authenticate (auth parity review exists in docs)?
Specification: SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies, Settings & Provider Configuration
Overview
SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies are stored encrypted at rest (AES-256-GCM) under scopes with access policies in @fusion/core; global/project settings merge with precedence; providers/models resolve instances with rotation/fallback; MCPModel Context Protocol servers are configured with secret references. All are surfaced via the Settings modal, CLICommand-line interface, and APIApplication programming interface routes.
Architecture
Settings modal / CLICommand-line interface commands / APIApplication programming interface routes
(register-secrets-routes, register-config-mcp-pi-settings-routes,
register-custom-provider-routes, register-model-routes, register-provider-routes)
│
▼
@fusion/core (secrets-store, secrets-crypto, master-key, secret-access-policy,
secrets-sync, config/settings, settings-ops, mcp)
│
▼
PostgreSQL / file-backed secrets + sync
Data Models
Secret
| Field | Type | Constraints | Description |
|---|---|---|---|
| name | string | PK | Secret name |
| scope | enum | not null | Global / project / task scope |
| ciphertext | string | not null | AES-256-GCM encrypted value |
| accessPolicy | enum | not null | Who may read it |
Settings
| Field | Type | Constraints | Description |
|---|---|---|---|
| key | string | PK | Setting key |
| value | json | — | Setting value |
| level | enum | — | Global / project / task |
APIApplication programming interface Contracts
POST /api/settings/mcp
Request
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | yes | MCPModel Context Protocol server name |
| command | string | yes | Launch command |
| secretRefs | object | no | Secret references |
| enabled | bool | no | Enabled flag |
Response (200 OK)
- 200 with config; 400 INVALID_INPUT on validation failure
Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Encryption at rest | AES-256-GCM under master key | Single encryption model documented in docs/secrets.md |
| Model hierarchy | global → project → task → lane | Deterministic precedence (docs/settings-reference.md) |
| Credential rotation | append-only rotation events | Never expose credentials in audit |
| MCPModel Context Protocol import/export | CLICommand-line interface + dashboard | Operator-friendly configuration |
Risks and Unknowns
- SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies sync between nodes authentication parity is an open security review area.
Out of Scope
- Agent execution (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p4) and command center (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p7) internals
Test Plan: SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies, Settings & Provider Configuration
Scope
Covers secrets encryption and scopes, settings merge/precedence and sync, provider/model resolution and rotation, MCPModel Context Protocol configuration and validation, and the CLICommand-line interface/dashboard surfaces.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | Secret scope validation | scoped secret | Scope accepted/rejected per policy |
| TC-2 | SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies crypto (AES-256-GCM) | plaintext | Round-trip encrypt/decrypt |
| TC-3 | Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped merge | global+project | Merged with correct precedence |
| TC-4 | Configuration revision store | revision write | Revision recorded |
| TC-5 | Custom provider registry | provider def | Registered/validated |
| TC-6 | Run-audit secret taxonomy | audit rows | Secret material never present |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-7 | SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies env writer | scoped secret | Env written per access policy |
| TC-8 | SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies sync across nodes | two nodes | SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies synced with auth parity |
| TC-9 | MCPModel Context Protocol config route | mcp config | 200 valid / 400 invalid |
| TC-10 | Settings memory routes | settings | Read/write round-trip |
| TC-11 | Custom provider routes | provider | CRUD works |
| TC-12 | Settings export/import (CLICommand-line interface) | settings file | Round-trip preserved |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-13 | Rotation exhaustion | Append-only exhaustion recorded, starting instance excluded |
| TC-14 | Dangling credential instance | Falls back to provider default with metadata |
Test Infrastructure
- Vitest core/engine/dashboard/CLICommand-line interface suites
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall store secrets encrypted at rest with AES-256-GCM under scopes with access policies | TC-1, TC-2 |
| FR-2MustThe system shall manage global and project settings with sync and precedence resolution | TC-3, TC-4, TC-8 |
| FR-3MustThe system shall manage provider/model credentials with instance rotation and fallback resolution | TC-5, TC-11, TC-13, TC-14 |
| FR-4MustThe system shall configure and validate MCPModel Context Protocol servers, including secret references and CLICommand-line interface/dashboard import/export | TC-9 |
| FR-5MustThe system shall expose secrets/settings/mcp/provider operations via CLICommand-line interface, dashboard APIApplication programming interface, and Settings modal | TC-10, TC-12 |
| NFR-1MustCredential material must never be persisted in run-audit or logs | TC-6 |
Key Test Files
packages/core/src/__tests__/secrets-*.test.ts,is-secret-scope.test.ts,automation.test.ts,configuration-revision-store.test.tspackages/engine/src/__tests__/secrets-env-writer.test.ts,run-audit-secret-taxonomy.test.ts,effective-settings-merge.test.tspackages/dashboard/src/routes/__tests__/register-secrets-routes.test.ts,register-config-mcp-pi-settings-routes.test.ts,custom-provider-routes*.test.tspackages/cli/src/commands/__tests__/settings.test.ts,settings-export.test.ts,mcp.test.ts,provider-auth.test.ts,provider-settings.test.ts,custom-provider-registry.test.ts
requirements
- How does secrets sync between nodes authenticate (auth parity review exists in docs)?
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |
Pipeline Progress ?⚪ not started not yet begun✏️ draft initial version🔍 in review under review🚧 in progress actively worked on⛔ blocked waiting on dependency✅ done completed⏭️ skipped not applicable
Requirements: Multi-Node Operator Surfaces & Shells
Overview
Fusion runs as a fleet across machines. Operators manage multiple projects and nodes (cluster/mesh sharing a PostgreSQL backend), plus native desktop (Electron) and mobile (Capacitor) shells and the fn CLICommand-line interface with its TUITerminal user interface. Every surface drives and observes the same board.
Stakeholders
| Stakeholder | Interest |
|---|---|
| Operator | Manages projects, nodes, mesh membership, and remote access |
| Mobile/desktop users | Runs Fusion on phones and native apps via a shared shell bridge |
| CLICommand-line interface users | Drives Fusion from the terminal and TUITerminal user interface |
Functional Requirements
| ID | Priority | Requirement |
|---|---|---|
| FR-1MustThe system shall let operators create/manage projects and nodes with registration and onboarding | Must | The system shall let operators create/manage projects and nodes with registration and onboarding |
| FR-2MustThe system shall coordinate nodes via a shared mesh/cluster protocol over a shared PostgreSQL backend | Must | The system shall coordinate nodes via a shared mesh/cluster protocol over a shared PostgreSQL backend |
| FR-3MustThe system shall ship desktop (Electron) and mobile (Capacitor) shells that wrap the dashboard SPA via a shared shell bridge | Must | The system shall ship desktop (Electron) and mobile (Capacitor) shells that wrap the dashboard SPA via a shared shell bridge |
| FR-4MustThe system shall expose CLICommand-line interface commands and TUITerminal user interface for serve, daemon, dashboard, project, node, and mesh | Must | The system shall expose CLICommand-line interface commands and TUITerminal user interface for serve, daemon, dashboard, project, node, and mesh |
| FR-5ShouldThe system shall support remote access with tokenized login and QR/manual setup | Should | The system shall support remote access with tokenized login and QR/manual setup |
| FR-6ShouldThe system shall stream node/project scoped events over the shared `/api/events` bus | Should | The system shall stream node/project scoped events over the shared /api/events bus |
Non-Functional Requirements
| ID | Priority | Category | Requirement |
|---|---|---|---|
| NFR-1MustClaims/leases and membership must survive node unreachability (scheduler node-unreachable audit) | Must | Reliability | Claims/leases and membership must survive node unreachability (scheduler node-unreachable audit) |
| NFR-2MustNode auth and remote access must not expose the dashboard without tokens | Must | Security | Node auth and remote access must not expose the dashboard without tokens |
| NFR-3ShouldUnreachable nodes must degrade gracefully in the UIUser interface | Should | Availability | Unreachable nodes must degrade gracefully in the UIUser interface |
Constraints
- Desktop/mobile are excluded from the workspace typecheck (packages
@fusion/desktop,@fusion/mobile) - Port 4040 is reserved for the dashboard; shells must use the configured token flow
Acceptance Criteria
- FR-1MustThe system shall let operators create/manage projects and nodes with registration and onboarding, FR-2MustThe system shall coordinate nodes via a shared mesh/cluster protocol over a shared PostgreSQL backend
- Given a registered node/project
- When the mesh runs
- Then nodes claim/lease work over the shared backend and report membership
- FR-3MustThe system shall ship desktop (Electron) and mobile (Capacitor) shells that wrap the dashboard SPA via a shared shell bridge
- Given a native shell
- When it connects
- Then it drives the dashboard SPA through the shared
window.fusionShellbridge
- FR-4MustThe system shall expose CLICommand-line interface commands and TUITerminal user interface for serve, daemon, dashboard, project, node, and mesh
- Given the
fnCLICommand-line interface - When
serve,daemon,dashboard,project,node, ormeshruns - Then the corresponding surface operates correctly
- Given the
- NFR-1MustClaims/leases and membership must survive node unreachability (scheduler node-unreachable audit)
- Given an unreachable node
- When scheduling runs
- Then claims are audited and work is not lost
Conflicts
None identified yet.
Open Questions
- Retired multi-leader mesh replication is documented as "shared mesh protocol"; confirm whether the active topology is single-leader-shared-Postgres or multi-node writes.
Specification: Multi-Node Operator Surfaces & Shells
Overview
Projects and nodes are managed through @fusion/core (project, node, mesh, central modules) and dashboard route registrars; nodes coordinate over a shared PostgreSQL backend with claims/leases and membership. Native shells wrap the dashboard SPA via a shared window.fusionShell bridge; the fn CLICommand-line interface drives serve/daemon/dashboard/project/node/mesh.
Architecture
Desktop (Electron) / Mobile (Capacitor) ── window.fusionShell bridge
│
Dashboard SPA + shells (shell-host)
│
▼
Dashboard APIApplication programming interface (register-project-routes, register-node-routes, register-mesh-routes,
register-discovery-routes, register-settings-sync-*,
register-docker-*)
│
▼
@fusion/core (project-*, mesh/, central/) ──► PostgreSQL (shared backend)
│
▼
engine (project-engine, scheduler node-unreachable audit, fanout lanes)
Data Models
Node
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | string | PK | Node id |
| url | string | not null | Node endpoint |
| status | enum | not null | online/offline |
| claims/leases | json | — | Current claims |
APIApplication programming interface Contracts
POST /api/projects
Request
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | yes | ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree name |
| nodeUrl | string | no | Optional node URL |
Response (200 OK)
| Field | Type | Description |
|---|---|---|
| project | object | Created project |
Sequences
Node onboarding
register → discover → onboard (QR/manual/tokenized link) → mesh membership
Technical Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Shared backend | single PostgreSQL + claims/leases | Retired multi-leader mesh replication |
| Shell bridge | window.fusionShell + shell-host |
Normalizes host type across shells |
| Native shells out of typecheck | desktop/mobile excluded | Packaging-focused packages |
Risks and Unknowns
- Multi-leader mesh replication is retired; active topology is shared-Postgres with claims/leases (see docs/shared-mesh-protocol.md).
Out of Scope
- Fleet execution scheduling internals (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-p4)
Test Plan: Multi-Node Operator Surfaces & Shells
Scope
Covers project/node management, mesh coordination over shared PostgreSQL, shell onboarding and the shell bridge, and the CLICommand-line interface serve/daemon/dashboard/project/node/mesh surfaces.
Unit Tests
| ID | Description | Input | Expected Output |
|---|---|---|---|
| TC-1 | MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes task replication | task mutation | Replicated across nodes |
| TC-2 | Node route CRUD | node payload | Nodes created/updated |
| TC-3 | ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree CRUD | project payload | Projects managed |
| TC-4 | Shell onboarding backcompat | legacy profile | Backcompat onboarding applied |
| TC-5 | ShellContext bridge | host type | Normalized shell host |
Integration Tests
| ID | Description | Preconditions | Expected Outcome |
|---|---|---|---|
| TC-6 | Scheduler node-unreachable audit | unreachable node | Claims audited, work preserved |
| TC-7 | Scheduler fanout escalation lanes | overloaded lane | Escalation applied |
| TC-8 | Shell onboarding E2E | fresh device | Onboard via profile |
| TC-9 | Node/project APIApplication programming interface integration | live server | Routes serve data |
| TC-10 | CLICommand-line interface serve/daemon/dashboard | CLICommand-line interface installed | Processes supervised |
Edge Cases and Failure Scenarios
| ID | Scenario | Expected Behavior |
|---|---|---|
| TC-11 | Autolaunch bypass | Bypass respected |
| TC-12 | Node unreachable | Degrades gracefully |
Test Infrastructure
- Vitest across core/engine/dashboard/CLICommand-line interface; Electron/Capacitor shell E2E where applicable
Coverage Matrix
| Requirement | Test Cases |
|---|---|
| FR-1MustThe system shall let operators create/manage projects and nodes with registration and onboarding | TC-2, TC-3, TC-9 |
| FR-2MustThe system shall coordinate nodes via a shared mesh/cluster protocol over a shared PostgreSQL backend | TC-1, TC-6 |
| FR-3MustThe system shall ship desktop (Electron) and mobile (Capacitor) shells that wrap the dashboard SPA via a shared shell bridge | TC-4, TC-5, TC-8 |
| FR-4MustThe system shall expose CLICommand-line interface commands and TUITerminal user interface for serve, daemon, dashboard, project, node, and mesh | TC-10 |
| NFR-1MustClaims/leases and membership must survive node unreachability (scheduler node-unreachable audit) | TC-6, TC-7 |
Key Test Files
packages/core/src/__tests__/mesh-task-replication.test.ts, project testspackages/engine/src/__tests__/scheduler-node-unreachable-audit.test.ts,scheduler-fanout-escalation-lanes.test.tspackages/dashboard/src/routes/__tests__/register-node-routes.test.ts,api-node.test.ts,api-projects.test.tspackages/cli/src/commands/__tests__/node.test.ts,project.test.ts,serve.test.ts,daemon.test.ts,dashboard-supervise.test.ts,onboard-*.test.tspackages/dashboard/app/__tests__/App.shell-onboarding.test.tsx,ShellContext.test.tsx
requirements
- Retired multi-leader mesh replication is documented as "shared mesh protocol"; confirm whether the active topology is single-leader-shared-Postgres or multi-node writes.
Vocabulary
This file defines domain-specific terms, acronyms, and abbreviations used across the project. Keeping definitions here avoids ambiguity in requirements, specs, and discussions. Add new terms as they are introduced. Terms within each table are sorted alphabetically by the first column.
Domain Terms
| Term | Definition |
|---|---|
| Active-session leaseA path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive | A path-keyed, in-memory claim that a worktree path is held by one task's running session, used both for mutual exclusion and as proof that the task is alive |
| Agent slotA unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane | A unit of a project's concurrent-agent capacity, drawn from one shared pool by planning, execution, and merge alike, so a project cannot exceed its operator-facing limit by spending capacity in a different lane |
| Approval requestA durable hold that blocks a task from advancing until a human approves, recorded with who approved and when | A durable hold that blocks a task from advancing until a human approves, recorded with who approved and when |
| ArtifactA registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage | A registry entry for a deliverable produced by an agent, chat, workflow, or task, with a type, an author, and optional task linkage |
| Auto-mergeAutomated promotion of finished branches into the default branch (squash/rebase/PR paths) | Automated promotion of finished branches into the default branch (squash/rebase/PRPull request paths) |
| AutopilotThe named process that watches an active mission and activates the next pending slice once the current slice completes | The named process that watches an active mission and activates the next pending slice once the current slice completes |
| Branch assignment modeThe strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch | The strategy by which a task acquires its working branch and merge target, such as a shared branch group or the project default branch |
| ChatPersistent chat sessions and rooms for operator and agent conversation, backed by the chat store | Persistent chat sessions and rooms for operator and agent conversation, backed by the chat store |
| Checkout leaseExclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat | Exclusive execution ownership of a task, held through a claim row plus lease metadata and validated on every heartbeat |
| ClaimThe authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners | The authoritative ownership row for a task in the central database, keyed by project and task, used to fence out stale owners |
| ColumnA workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column | A workflow-defined unit of task state with an id, a display name, and a set of traits, where a task's board position is its current column |
| Column agentA permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column | A permanent agent binding on a workflow-defined column that staffs the session-running work attributable to that column |
| Command CenterThe operator "mission control" dashboard for the agent fleet, signals, and usage | The operator "mission control" dashboard for the agent fleet, signals, and usage |
| Compound engineering sessionA single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact | A single interactive run of a compound engineering stage, where an agent drives a question-and-answer flow and produces the stage artifact |
| ContaminationForeign commits from other tasks that appear on a task's branch beyond its recorded fork point | Foreign commits from other tasks that appear on a task's branch beyond its recorded fork point |
| Contract assertionA checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done | A checkable acceptance criterion on a mission feature, judged by an AI validator to decide whether the feature is genuinely done |
| Custom task fieldA workflow-declared typed task field whose values live in `tasks.customFields` and are validated against the resolving workflow's schema | A workflow-declared typed task field whose values live in tasks.customFields and are validated against the resolving workflow's schema |
| Default workflowThe built-in workflow `builtin:coding` that reproduces the legacy pipeline, with six columns whose ids match the historical status names | The built-in workflow builtin:coding that reproduces the legacy pipeline, with six columns whose ids match the historical status names |
| Distributed task IDA task identifier allocated from shared reservations so that concurrent nodes never mint the same id | A task identifier allocated from shared reservations so that concurrent nodes never mint the same id |
| Durable agentA persistent agent that runs on a heartbeat and can be auto-recovered from error states | A persistent agent that runs on a heartbeat and can be auto-recovered from error states |
| Effective agentThe agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult | The agent identity that runs a piece of work after column-agent precedence resolves, and the principal that identity-keyed subsystems consult |
| Effective settingsThe per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped | The per-task settings map the engine reads at runtime, where stored workflow values fall back to declaration defaults and invalid values are dropped |
| EvalsCanonical 0–100 scoring of agent performance, task outcome quality, and process compliance | Canonical 0–100 scoring of agent performance, task outcome quality, and process compliance |
| Fork pointThe commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns | The commit on the integration branch from which a task's branch was created, the lower bound of the changes that task owns |
| Global settingsUser-level settings that apply across every surface and every project, validated at the write boundary | User-level settings that apply across every surface and every project, validated at the write boundary |
| GoalsMeasurable objectives tracked in the dashboard with a refinement gate | Measurable objectives tracked in the dashboard with a refinement gate |
| Group promotionThe gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request | The gated, repeatable act of merging a complete shared branch group toward the project default branch, creating or reusing the group's single managed pull request |
| Heartbeat runA short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits | A short permanent-agent wake triggered by a timer, assignment, message, or on demand, which takes one coordination action and exits |
| Hold nodeA workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires | A workflow node kind expressing passive dwell, where a card rests in its column until a release condition fires |
| IdeationA bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy | A bounded project-scoped session that collects ideas and candidates, which converge into the mission hierarchy |
| In-reviewThe column between execution and completion, where work is done and the branch awaits merging | The column between execution and completion, where work is done and the branch awaits merging |
| Integration branchThe local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork | The local branch, by default the project default branch, where the merger lands task branches and from which new task worktrees fork |
| LaneA horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns | A horizontal row on the board, one per workflow in use by visible cards, each rendering that workflow's columns |
| Loop stateA mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory | A mission feature's position in the execution loop, distinct from its board column, and possibly stale or contradictory |
| Manual-requiredThe merge-request state for a task whose merge needs an explicit human go-ahead | The merge-request state for a task whose merge needs an explicit human go-ahead |
| MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) | Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend) |
| Merge queueThe ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time | The ordered line of in-review tasks awaiting auto-merge, with a single merge active at a time |
| Mission / milestone / slice / featureThe product-hierarchy layers (mission to milestone to slice to feature) that drive task work | The product-hierarchy layers (mission to milestone to slice to feature) that drive task work |
| PatchnodeDashboard feed rendered from denormalized ledger entries, durable across archive cleanup | Dashboard feed rendered from denormalized ledger entries, durable across archive cleanup |
| Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP | The workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP |
| Planner overseerAutomated oversight of planning work across `off` / `observe` / `steer` / `autonomous` levels with human-confirmation gates | Automated oversight of planning work across off / observe / steer / autonomous levels with human-confirmation gates |
| Planning modeA dedicated human-in-the-loop planning chat and Plan Review node for shaping a task before execution | A dedicated human-in-the-loop planning chat and Plan ReviewThe workflow gate that judges a task's plan before execution, returning APPROVE, APPROVE_WITH_NOTES, REVISE, or CLOSE_NO_OP node for shaping a task before execution |
| PR entityThe single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group | The single first-class record of a pull request Fusion manages, whether it came from one task or a shared branch group |
| ProjectA registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree | A registered workspace Fusion can operate on, with a canonical local path, project-scoped settings, and a usable git work tree |
| ResearchCited search-and-synthesis pipeline that runs bounded investigations into actionable task context | Cited search-and-synthesis pipeline that runs bounded investigations into actionable task context |
| Review-response loopThe process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open | The process where an agent acts on pull request review feedback, either by pushing a fix and replying to the thread or by posting its reasoning and leaving the thread open |
| RoutineA recurring task automation with a trigger mode (cron, webhook, API, or manual) plus execution and catch-up policies | A recurring task automation with a trigger mode (cron, webhook, APIApplication programming interface, or manual) plus execution and catch-up policies |
| Run auditAppend-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) | Append-only structured event log of engine/task lifecycle events (ids/counts-outcomes metadata only) |
| Self-healingEngine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state | Engine sweeps that reconcile stranded, orphaned, or stale task/agent/worktree state |
| Signals connectorHMAC-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion | HMACHash-based message authentication code-signed external ingest (Sentry/Datadog/PagerDuty/webhooks) into Fusion |
| SliceA vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done | A vertically-scoped, independently completable chunk of a milestone that holds features and is complete only when all of them are done |
| Split / joinParallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode | Parallel-branch workflow node kinds, where a split launches its outgoing edges concurrently and a join synchronizes them with an all, any, or quorum mode |
| Step instanceOne runtime expansion of a `foreach` template subgraph, bound to a single planned step and identified deterministically | One runtime expansion of a foreach template subgraph, bound to a single planned step and identified deterministically |
| Task boardThe kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items | The kanban surface of workflow columns (planning/todo/in-progress/in-review/done or graph-driven variants) that tracks AI-orchestrated work items |
| Task documentA persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md | A persisted, revision-tracked document attached to a task, such as its plan or its PROMPT.md |
| Task lifecycleThe domain state machine modeling a task's progression and its status values | The domain state machine modeling a task's progression and its status values |
| Task lineageThe durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them | The durable identity a task carries in its commit trailers, so commits can be attributed back to the task that produced them |
| TraitComposable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry | Composable column configuration made of declarative flags plus optional lifecycle hooks, registered through one registry |
| Transition pendingA persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them | A persisted marker written with a column change that records the post-commit hooks still owed, so a crash re-runs them |
| Validator runA single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome | A single execution that evaluates a mission feature's contract assertions and yields a pass, fail, blocked, error, or inconclusive outcome |
| Workflow extensionA plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers | A plugin-contributed workflow capability registered through the engine, such as column metadata, movement policies, or node handlers |
| Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns | A DAGDirected acyclic graph of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns |
| Workflow nodeA unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner | A unit in the workflow graph (e.g. plan, code, review, gate, merge, exit-gate) with its own runner |
| Workflow settingA typed setting declared by a workflow, whose values persist per workflow and project through a validating store | A typed setting declared by a workflow, whose values persist per workflow and project through a validating store |
| Workflow work itemA durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease | A durable row for one unit of workflow-graph work, with a state, an attempt count, and a lease |
| WorkspaceMulti-repository project variant with one task worktree per sub-repository and a per-repository land loop | Multi-repository project variant with one task worktree per sub-repository and a per-repository land loop |
Technical Terms
| Term | Definition |
|---|---|
| Boot smokeThe gate's "the app starts and serves" proof, where the CLI answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly | The gate's "the app starts and serves" proof, where the CLICommand-line interface answers its help command and a server boots on a throwaway port, answers its health endpoint, and shuts down cleanly |
| Bounded run-audit emitterThe engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks | The engine and core seam that records a run-audit row without letting telemetry delay, abort, or wedge the owning branch, by absorbing absent, throwing, rejecting, and hanging sinks |
| Deletion ratchetThe standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries | The standing policy that a test observed failing without a corresponding bug is quarantined on sight and then deleted two weeks later, never appeased with widened timeouts or retries |
| Drizzle ORMThe typed SQL schema layer that defines Fusion's PostgreSQL tables under `packages/core/src/postgres/schema/` | The typed SQLStructured Query Language schema layer that defines Fusion's PostgreSQL tables under packages/core/src/postgres/schema/ |
| Embedded PostgreSQLThe locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs | The locally launched PostgreSQL 15 instance that backs the project, central, and archive schemas in local and development runs |
| File-scopeThe set of files a task is allowed/expected to touch; enforced on squash merges | The set of files a task is allowed/expected to touch; enforced on squash merges |
| File-scope leaseA durable claim that a task owns a set of files, used to block overlapping work on the same paths | A durable claim that a task owns a set of files, used to block overlapping work on the same paths |
| Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints | Deterministic LLMLarge language model-free structure graph of the codebase, built incrementally from fingerprints |
| Merge gateThe minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list | The minimal set of pull-request checks that block a merge: lint, typecheck, build, boot smoke, and a curated engine test suite, with membership held by an explicit allow-list |
| MergerEngine component that lands branches via squash/rebase/PR with conflict resolution and guards | Engine component that lands branches via squash/rebase/PRPull request with conflict resolution and guards |
| MeshDistributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes | Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend, with a central schema holding project registration, claims, and nodes |
| Node runnerPer-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) | Per-node implementation (code-runner, gate-runner, merge-runner, exit-gate-runner, review) |
| pi extensionA first-party carrier that routes Fusion's agent commands into a specific coding-agent CLI | A first-party carrier that routes Fusion's agent commands into a specific coding-agent CLICommand-line interface |
| PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks | First-party extension unit contributing custom tools, routes, settings, and lifecycle hooks |
| Plugin entryThe single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory | The single loadable file persisted as a plugin's path and dynamically imported by the loader, which is never a package directory |
| SandboxPluggable executor command isolation (bubblewrap, macOS `sandbox-exec`, native) with a fail-hard or fallback-native failure mode | Pluggable executor command isolation (bubblewrap, macOS sandbox-exec, native) with a fail-hard or fallback-native failure mode |
| Schema-version sweepThe repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter | The repo-wide hunt for hard-coded assertions of the old schema version, performed in the same commit as any bump of the version counter |
| SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` | A produced SDLC artifactA produced SDLC artifact instance (requirements, specification, plan, tests, etc.) under `.sdlc/features/<N>-<slug>/` instance (requirements, specification, plan, tests, etc.) under .sdlc/features/<N>-<slug>/ |
| SecretsEncrypted-at-rest credential storage with project and global scopes and per-key access policies | Encrypted-at-rest credential storage with project and global scopes and per-key access policies |
| Smart pullThe one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring | The one-shot pull workflow that advances the checked-out integration branch while keeping local work safe, by fast-forwarding directly or by stashing and restoring |
| Symbol lockA durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol | A durable, project-scoped claim on a normalized code symbol key, held by a task to keep later scheduling phases from conflicting over the same symbol |
| Task store / task-advisory lockThe domain persistence layer and per-task advisory locking used for lifecycle moves | The domain persistence layer and per-task advisory locking used for lifecycle moves |
| Tool surfaceThe set of `fn_`-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy | The set of fn_-prefixed tools an agent may call, whose availability depends on the lane, the column, and the agent's permission policy |
| Triple-proof livenessThe canonical proof that a task/session is contended before backward moves | The canonical proof that a task/session is contended before backward moves |
| Workflow graph executorEngine component that drives the workflow graph through its node runners | Engine component that drives the workflow graph through its node runners |
| Workflow IRThe declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations | The declarative intermediate representation of a workflow, holding its columns, traits, nodes, edges, and settings declarations |
| WorktreeAn isolated git working tree used for branch-scoped task work, keeping the primary checkout on main | An isolated git working tree used for branch-scoped task work, keeping the primary checkout on main |
| WorktrunkExternal git-worktree manager CLI (`wt`) used for branch-scoped worktrees | External git-worktree manager CLICommand-line interface (wt) used for branch-scoped worktrees |
Acronyms and Abbreviations
| Abbreviation | Expansion |
|---|---|
| ACPAgent Client Protocol | Agent Client Protocol |
| APIApplication programming interface | Application programming interface |
| CLICommand-line interface | Command-line interface |
| DAGDirected acyclic graph | Directed acyclic graph |
| FEATFeature identifier in SDLC artifacts (`FEAT-N`) | Feature identifier in SDLCSoftware development lifecycle artifacts (FEATFeature identifier in SDLC artifacts (`FEAT-N`)-N) |
| FN-XXXXFusion task/issue tracker identifier | Fusion task/issue tracker identifier |
| FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`) | Source comment stamp that encodes a requirement (FNXCSource comment stamp that encodes a requirement (`FNXC:<Area> <yyyy-MM-dd-hh:mm>`):<Area> <yyyy-MM-dd-hh:mm>) |
| FR / NFRFunctional / non-functional requirement | Functional / non-functional requirement |
| HMACHash-based message authentication code | Hash-based message authentication code |
| HTTPHypertext Transfer Protocol | Hypertext Transfer Protocol |
| IRIntermediate representation | Intermediate representation |
| JSONJavaScript Object Notation | JavaScript Object Notation |
| JWTJSON Web Token | JSONJavaScript Object Notation Web Token |
| L10n / i18nLocalization / internationalization | Localization / internationalization |
| LLMLarge language model | Large language model |
| MCPModel Context Protocol | Model Context Protocol |
| OIDCOpenID Connect | OpenID Connect |
| PRPull request | Pull request |
| PTYPseudo-terminal | Pseudo-terminal |
| PWAProgressive web app | Progressive web app |
| RESTRepresentational State Transfer | Representational State Transfer |
| SDLCSoftware development lifecycle | Software development lifecycle |
| SLA / SLO / SLIService-level agreement / objective / indicator | Service-level agreement / objective / indicator |
| SQLStructured Query Language | Structured Query Language |
| SSEServer-sent events | Server-sent events |
| TUITerminal user interface | Terminal user interface |
| UIUser interface | User interface |
| YAMLYAML Ain't Markup Language | YAMLYAML Ain't Markup Language Ain't Markup Language |