fusion/docs/workflow-policy-ownership-map.md

Workflow Policy Ownership Map

Purpose

This map is the U1 characterization artifact for moving merge, retry, scheduling, and recovery policy into workflow IR/runtime. It classifies current production branches before code is deleted or moved so later cutover work can prove that no legacy engine control path was left unowned.

Ownership Categories

• substrate: engine/core mechanics that remain below workflow policy.
• workflow-policy: decisions that must be represented by workflow nodes, workflow node state, or workflow recovery events.
• capability: operations invoked by workflow nodes while still using shared guard services.
• compat-projection: legacy task fields or records that may remain as derived summaries during migration.
• delete-after-cutover: branches that should disappear once workflow parity is authoritative.

Catalog

Surface	Current source	Current owner	Target owner	Disposition
Auto-merge queue enqueue and dequeue	packages/engine/src/project-engine.ts	ProjectEngine merge queue	workflow merge work items and merge-gate nodes	workflow-policy, delete-after-cutover
In-review handoff delay and startup sweep	packages/engine/src/project-engine.ts	task:moved listener plus in-review scan	workflow completion handoff node creates merge work	workflow-policy
Manual onMerge requests	packages/engine/src/project-engine.ts	engine public merge queue entry point	explicit human/manual workflow event that wakes merge node	workflow-policy, capability
Merge request shadow contract	packages/core/src/store.ts, packages/engine/src/project-engine.ts, packages/engine/src/merger.ts	store record plus shadow parity branches	workflow work-item state or compatibility projection	compat-projection
Merge checkout, integration, conflict resolution, squash, finalize	packages/engine/src/merger.ts, packages/engine/src/merger-ai.ts, packages/engine/src/merger-integration-worktree.ts	merger lifecycle procedures	workflow merge node capabilities calling guard services	capability
Branch-group member integration and group promotion	packages/engine/src/group-merge-coordinator.ts, packages/engine/src/merge-trait.ts, packages/engine/src/merger-integration-worktree.ts	group coordinator and merger helpers	branch-group workflow subgraph with separate member and promotion nodes	workflow-policy, capability
Merge target and auto-merge eligibility guards	packages/core/src/task-merge.ts	shared helper used by engine paths	shared guard service called by workflow nodes	substrate
Dependency satisfaction treats in-review as satisfied	packages/engine/src/scheduler.ts, packages/core/src/task-merge.ts	scheduler/task helper lifecycle interpretation	workflow completion handoff state and compatibility projection	workflow-policy, compat-projection
Active scope leases include unmerged in-review worktrees	packages/engine/src/scheduler.ts	scheduler overlap policy	workflow work leases plus repository guard services	workflow-policy, substrate
PR monitor starts/stops from in-review transitions	packages/engine/src/scheduler.ts	scheduler task-move listener	workflow PR/watch nodes or workflow events	workflow-policy
Generic agent capacity, routing, claim, and lease mechanics	packages/engine/src/scheduler.ts	scheduler	scheduler substrate claiming runnable workflow work	substrate
Executor retry storm cap	packages/engine/src/__tests__/executor-retry-storm.test.ts, packages/engine/src/project-engine.ts	engine retry counters and execution loop	workflow node retry policy plus runtime substrate guard	workflow-policy, substrate
Generic backoff helpers	packages/engine/src/retry-with-backoff.ts, packages/engine/src/rate-limit-retry.ts	helper functions	reusable substrate helper called by retry nodes	substrate
Transient merge error classification	packages/engine/src/transient-merge-error-classifier.ts	helper used by merger/self-healing	merge-node classification input, not route owner	substrate
Task-level retry summary fields	packages/core/src/retry-summary.ts, packages/core/src/manual-retry-reset.ts	task metadata and reset patch	compatibility projection from workflow node/run retry state	compat-projection
Manual retry reset	packages/core/src/manual-retry-reset.ts, dashboard/API callers	task metadata patch	workflow event clearing targeted failed node retry state	workflow-policy, compat-projection
Recover mergeable in-review tasks	packages/engine/src/self-healing.ts	self-healing directly re-enqueues merge	workflow recovery event wakes merge node	workflow-policy, delete-after-cutover
Completion handoff limbo recovery	packages/engine/src/self-healing.ts	self-healing re-emits auto-merge handoff	workflow recovery event or idempotent handoff node wake	workflow-policy
Transient merge failure recovery	packages/engine/src/self-healing.ts	self-healing resets merge retries and re-enqueues	merge-node retry policy and retry-after work item	workflow-policy, delete-after-cutover
Stale merge status recovery	packages/engine/src/self-healing.ts	self-healing clears status and may enqueue merge	workflow recovery event plus merge work reconciliation	workflow-policy
Already-landed and no-op finalization	packages/engine/src/self-healing.ts, packages/engine/src/merger.ts	self-healing/merger lifecycle paths	workflow recovery/finalize nodes with repository guard services	workflow-policy, capability
Backward in-review recovery paths	packages/engine/src/self-healing.ts, docs/self-healing-backward-move-audit.md	proof-gated self-healing mutations	workflow recovery nodes; engine only emits facts	workflow-policy, delete-after-cutover
Workflow runtime execution facade	packages/engine/src/workflow-task-runtime.ts, packages/engine/src/workflow-graph-executor.ts	runtime executes graph nodes	remains workflow runtime owner	substrate, workflow-policy
Built-in default workflow definitions	packages/core/src/builtin-coding-workflow-ir.ts, packages/core/src/builtin-stepwise-coding-workflow-ir.ts, packages/core/src/builtin-pr-workflow-ir.ts	partial lifecycle expression	authoritative source for default scheduling, retry, merge, and recovery regions	workflow-policy
Dashboard task-card merge/retry/stall badges	packages/dashboard/app/components/TaskCard.tsx	task fields and legacy classifications	workflow run/work-item projection first, legacy fields second	compat-projection
Reliability and diagnostics surfaces	docs/diagnostics.md, dashboard reliability views	self-healing and engine status strings	workflow-native recovery and held-work reasons	compat-projection

Non-Bypassable Guard Services

These remain centralized and are called by workflow node capabilities before mutating git state:

• File-scope and squash overlap checks.
• Branch target and branch-group target validation.
• Worktree ownership and lease checks.
• Auto-merge processing gate, including autoMerge:false terminal-until-human semantics and the shared-branch member integration exception.
• Run-audit correlation for git operations and recovery facts.

Deletion Gates

• No production caller may start checkout, branch integration, squash, or finalize except a workflow merge node or an explicit human/manual API that records an equivalent workflow event.
• Scheduler may claim runnable workflow work, apply capacity/routing/leases, and monitor PR/watch substrate events; it must not infer merge eligibility, retry routing, or task lifecycle advancement from task columns.
• SelfHealingManager may publish typed recovery facts and reconcile metadata; it must not directly requeue, pause, fail, unpause, or move merge/retry tasks except through guarded workflow primitives.
• Task-level retry and merge fields are compatibility summaries. Workflow run/node/work-item state is the policy authority.