Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

✅Done: completed requirements⚪Not Started: not yet begun existing-solutions⚪Not Started: not yet begun codebase-analysis⚪Not Started: not yet begun feasibility✅Done: completed specification⚪Not Started: not yet begun plan

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

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 API, CLICommand-line interface, and workflow routes	Should	The system shall expose task operations through the dashboard API, 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 API 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, Column)
      │  fetch + mutate
      ▼
Dashboard API 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

API 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 document 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	API 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	Column unsupported by the workflow	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/dashboard package 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 API, 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-concurrency
packages/dashboard/src/routes/__tests__/register-task-workflow-routes*.test.ts
packages/dashboard/app/__tests__/api-tasks.test.ts, board-mobile-*.test.ts, column-role-degraded-flags.test.ts
packages/cli/src/commands/__tests__/task.test.ts, task-lifecycle.test.ts, task-lock-retry.test.ts

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.

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

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 fn CLICommand-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
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

API 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.ts
packages/cli/src/commands/__tests__/plugin.test.ts, claude-cli-extension.test.ts, droid-cli-extension.test.ts, llama-cpp-extension.test.ts
packages/dashboard/src/routes/__tests__/register-approval-routes... + plugin route tests, packages/dashboard/app/__tests__/api-plugins, PluginManager.test

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Knowledge Graph & MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend)

Overview

Fusion maintains a deterministic LLM-free knowledge graph over its own source, docs, and FNXC 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 LLM calls.	Must	The system shall extract file, module, symbol, doc-concept, and rationale nodes with structural edges using only deterministic parsers and no LLM 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 API with queryNodes, neighbors, and shortestPath that retains complete edge provenance.	Must	The system shall expose an in-process query API 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 FNXC rationale nodes from TypeScript parser comment ranges and markdown HTML comments outside fenced code.	Must	The system shall extract FNXC 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 JSON with nodes and edges before the manifest so torn writes trigger full rebuild.	Should	Reliability	The system shall write artifacts as sorted LF JSON 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).

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 JSON 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, FNXC 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.

API Contracts

The normative contract is the in-process query API plus the CLICommand-line interface and dashboard HTTP 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	Artifact 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.
Artifact tracking	Gitignored regenerable directory	Avoids roughly 85MB of compounding history bloat for reproducible output.
Serialization	Sorted LF JSON 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

LLM 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	FNXC 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 API behavior	graph-query.test.ts built graph	queryNodes, neighbors, and shortestPath retain full provenance.
TC-9	Artifact serialization stability	graph-serialization.test.ts graph fixtures	Sorted LF JSON 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	Artifact 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, FNXC 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 LLM 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 API 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 FNXC 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 JSON with nodes and edges before the manifest so torn writes trigger full rebuild.	TC-9, TC-17, TC-21

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

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 IR and transition policy governing node transitions and gates	Must	The system shall define a workflow IR 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 API routes and validate user-authored definitions	Should	The system shall expose workflows through dashboard API 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-replan are 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 IR 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 IR) 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 API (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)

API Contracts

POST /api/workflows/validate

Request

Field	Type	Required	Description
definition	object	yes	Workflow IR 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 IR 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 Review 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 IR parses (coding, brainstorming, coding-ideas, lead-generation)	IR definition	Valid IR, 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 IR call sites still allowlisted	legacy IR 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 IR 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.ts
packages/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.ts
packages/dashboard/src/routes/__tests__/workflow-validate-route.test.ts, board-workflows
packages/dashboard/app/components/__tests__/WorkflowNodeEditor*
packages/core/src/__tests__/legacy-tombstones.test.ts (workflow cutover ratchet)

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: Planning Mode & Planner Oversight

Overview

A dedicated planning flow (Planning Mode chat, Plan Review, 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 Review, 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 Review node that produce and review a plan for a task	Must	The system shall provide a Planning Mode chat and Plan Review 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 Review state must survive engine restart (handoff recovery)	Must	Reliability	Plan Review 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 Review 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 Review 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 Review 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 Review 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 API (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

API 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 Review 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 Review	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.ts family

Coverage Matrix

Requirement	Test Cases
FR-1MustThe system shall provide a Planning Mode chat and Plan Review 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.ts
packages/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.ts
packages/dashboard/src/routes/__tests__/tasks-overseer-controls.test.ts, tasks-planner-overseer-state.test.ts, register-planning-subtask-routes.parent-close.test.ts

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

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, spawn-based) boundaries must be applied before executing user-provided commands	Must	Security	SandboxPluggable executor command isolation (bubblewrap, spawn-based) 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-replan are graph signals, not legacy; their writers must remain
Task-review and executor mechanics live in the engine; the dashboard only reads via the domain API
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, spawn-based) 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.md and 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

API 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, spawn-based) pluggable	bubblewrap / spawn-based	Command isolation backends

Risks and Unknowns

Claim/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, spawn-based) audit on routine runner	sandboxed command	SandboxPluggable executor command isolation (bubblewrap, spawn-based) applied, audit recorded

Integration Tests

ID	Description	Preconditions	Expected Outcome
TC-5	Scheduler auto-claim invalidation	stale claim	Claim 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	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.ts
packages/core/src/__tests__/agent-permissions.test.ts, agent-permission-policy.test.ts, agent-store-routing-policy.test.ts, assigned-task-ranking.test.ts
packages/dashboard/src/routes/__tests__/agent-core-routes.test.ts, agent-onboarding-routes.test.ts
packages/dashboard/app/__tests__/agent-runs-ui.test.ts, agent-detail-settings-theme-styling.test.ts

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

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	Contamination 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-* tests
packages/dashboard/src/routes/__tests__/register-task-workflow-routes.merge-advance-events.test.ts, ...merge.test.ts, task-review-routes.test.ts
packages/cli/src/commands/__tests__/pr-lock-retry.test.ts, git.test.ts

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

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 and experiment_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 evaluations and insights integrated 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

API 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
Autopilot 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

evaluations and insights integrated 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.ts
packages/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.ts
packages/dashboard/src/routes/__tests__/mission-*.test.ts, research route tests
packages/dashboard/app/__tests__/api-missions.test.ts; packages/cli/src/commands/__tests__/research.test.ts

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

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` SSE bus	Should	The system shall stream realtime status via the shared `/api/events` SSE bus
FR-6ShouldThe system shall expose usage/signals/monitor data through dashboard API route registrars	Should	The system shall expose usage/signals/monitor data through dashboard API 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 SSE 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 (SSE)
      ▼
@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

API 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 SSE	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.ts
packages/dashboard/app/components/command-center/__tests__/*, packages/dashboard/app/__tests__/usage-*.test

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

Requirements: SecretsEncrypted-at-rest credential storage with project and global scopes, 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 API 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 API, and Settings modal	Must	The system shall expose secrets/settings/mcp/provider operations via CLICommand-line interface, dashboard API, 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 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 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 master-key handling and scopes are documented in docs/secrets.md and docs/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, Settings & Provider Configuration

Overview

SecretsEncrypted-at-rest credential storage with project and global scopes 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 API routes.

Architecture

Settings modal / CLICommand-line interface commands / API 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

API 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 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, 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 crypto (AES-256-GCM)	plaintext	Round-trip encrypt/decrypt
TC-3	Effective settings 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 env writer	scoped secret	Env written per access policy
TC-8	SecretsEncrypted-at-rest credential storage with project and global scopes sync across nodes	two nodes	SecretsEncrypted-at-rest credential storage with project and global scopes 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 API, 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.ts
packages/engine/src/__tests__/secrets-env-writer.test.ts, run-audit-secret-taxonomy.test.ts, effective-settings-merge.test.ts
packages/dashboard/src/routes/__tests__/register-secrets-routes.test.ts, register-config-mcp-pi-settings-routes.test.ts, custom-provider-routes*.test.ts
packages/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

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Current Phase

documentation

Phases Done

3 / 9

Completion

33%

Re-enter At

existing-solutions

3 completed6 remaining

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

Foundation

›

Build

⚪Not Started: not yet begun implementation✅Done: completed testing

›

Ship

⚪Not Started: not yet begun documentation

❓ Open Questions📖 Vocabulary

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.fusionShell bridge
FR-4MustThe system shall expose CLICommand-line interface commands and TUITerminal user interface for serve, daemon, dashboard, project, node, and mesh
- Given the fn CLICommand-line interface
- When serve, daemon, dashboard, project, node, or mesh runs
- Then the corresponding surface operates correctly
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 API (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

API Contracts

POST /api/projects

Request

Field	Type	Required	Description
name	string	yes	Project 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 task replication	task mutation	Replicated across nodes
TC-2	Node route CRUD	node payload	Nodes created/updated
TC-3	Project 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 API 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 tests
packages/engine/src/__tests__/scheduler-node-unreachable-audit.test.ts, scheduler-fanout-escalation-lanes.test.ts
packages/dashboard/src/routes/__tests__/register-node-routes.test.ts, api-node.test.ts, api-projects.test.ts
packages/cli/src/commands/__tests__/node.test.ts, project.test.ts, serve.test.ts, daemon.test.ts, dashboard-supervise.test.ts, onboard-*.test.ts
packages/dashboard/app/__tests__/App.shell-onboarding.test.tsx, ShellContext.test.tsx

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Abbreviation	Expansion
ACPAgent Client Protocol	Agent Client Protocol
CLICommand-line interface	Command-line interface
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
FR / NFRFunctional / non-functional requirement	Functional / non-functional requirement
HMACHash-based message authentication code	Hash-based message authentication code
L10n / i18nLocalization / internationalization	Localization / internationalization
MCPModel Context Protocol	Model Context Protocol
PRPull request	Pull request
SDLCSoftware development lifecycle	Software development lifecycle
SLA / SLO / SLIService-level agreement / objective / indicator	Service-level agreement / objective / indicator
TUITerminal user interface	Terminal user interface
UIUser interface	User interface

Term	Definition
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)
ChatPersistent chat rooms and threads for operator and agent conversation, backed by the chat store	Persistent chat rooms and threads for operator and agent conversation, backed by the chat store
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
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
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
GoalsMeasurable objectives tracked in the dashboard with a refinement gate	Measurable objectives tracked in the dashboard with a refinement gate
MemoryPluggable persistent recall of task shots, transcripts, and recall hits (Stash backend)	Pluggable persistent recall of task shots, transcripts, and recall hits (Stash backend)
Mission / milestone / featureThe product-hierarchy layers (mission → milestone → feature) that drive task work	The product-hierarchy layers (mission → milestone → 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
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 Review node for shaping a task before execution
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
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
Smart pullStrategy-aware pull logic during merge conflict handling	Strategy-aware pull logic during merge conflict handling
Task boardThe kanban surface of planning/todo/in-progress/in-review/done (or graph-driven variants) that tracks AI-orchestrated work items	The kanban surface of planning/todo/in-progress/in-review/done (or graph-driven variants) that tracks AI-orchestrated work items
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
Workflow graphA DAG of nodes (plan/code/review/gate/merge) a task traverses; replaces the fixed legacy lifecycle columns	A DAG 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
WorkspaceMulti-repository project shape with one task worktree per sub-repository and a per-repository land loop	Multi-repository project shape with one task worktree per sub-repository and a per-repository land loop

Term	Definition
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
Knowledge graphDeterministic LLM-free structure graph of the codebase, built incrementally from fingerprints	Deterministic LLM-free structure graph of the codebase, built incrementally from fingerprints
Legislature: artifactA produced SDLC artifact instance (requirements, specification, tests, etc.) under `.sdlc/`	A produced SDLCSoftware development lifecycle artifact instance (requirements, specification, tests, etc.) under `.sdlc/`
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	Distributed coordination across multiple Fusion nodes sharing a PostgreSQL backend
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
SandboxPluggable executor command isolation (bubblewrap, spawn-based)	Pluggable executor command isolation (bubblewrap, spawn-based)
SecretsEncrypted-at-rest credential storage with project and global scopes	Encrypted-at-rest credential storage with project and global scopes
Smart pull / auto-prerebaseStrategies to reconcile divergent branches before merge	Strategies to reconcile divergent branches before merge
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
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
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

SDLC Status Dashboard

Features

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

Stakeholders

Functional Requirements

Non-Functional Requirements

Constraints

Acceptance Criteria

Conflicts

Open Questions

Specification: Task Board & Task Lifecycle Management

Overview

Architecture

Data Models

Task

API Contracts

POST /api/tasks

Sequences

Create and move

Technical Decisions

Risks and Unknowns

Out of Scope

Test Plan: Task Board & Task Lifecycle Management

Scope

Unit Tests

Integration Tests

Edge Cases and Failure Scenarios

Test Infrastructure

Coverage Matrix

Key Test Files

requirements

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

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

Stakeholders

Functional Requirements

Non-Functional Requirements

Constraints

Acceptance Criteria

Conflicts

Open Questions

Specification: Plugins & Extension Ecosystem

Overview

Architecture

API Contracts

GET /api/plugins

POST /api/plugins/:id/enable

Sequences

PluginFirst-party extension unit contributing custom tools, routes, settings, and lifecycle hooks run

Technical Decisions

Risks and Unknowns

Out of Scope

Test Plan: Plugins & Extension Ecosystem

Scope

Unit Tests

Integration Tests

Edge Cases and Failure Scenarios

Test Infrastructure

Coverage Matrix

Key Test Files

requirements

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

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

Stakeholders

Functional Requirements

Non-Functional Requirements

Constraints

Acceptance Criteria

Conflicts

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

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

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

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

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