Flightdeck 2 Governance And Communication Review

flightdeck-2-review.md

Flightdeck 2 Governance And Communication Review

Executive Summary

Flightdeck already has the right execution substrate for multi-agent work: clear role separation, role-scoped tool permissions, a typed task DAG, reviewer handoff, and persistent status/reporting surfaces. The main gap versus Paperclip is not orchestration power. It is operational governance.

Paperclip's strongest transferable patterns for Flightdeck are:

1. First-class approval and interaction objects rather than implied "gated" states.
2. Explicit blocker ownership and unblock actions rather than blocked tasks with only dependency/state visibility.
3. Scoped wake context for each heartbeat or comment-triggered turn rather than generic periodic prompts.
4. Mandatory run closeout that records what changed, what remains, and who acts next.

I would not copy Paperclip's full company/inbox/checkout model into Flightdeck yet. That would be overkill for a local-first orchestration product. The right move is to add a thin governance layer on top of the existing DAG/orchestrator core.

What To Adopt

1. First-class approvals and interactions

Flightdeck already distinguishes governance outcomes such as gate_human and propose_and_wait, but those outcomes do not appear to persist as a concrete review object with assignee, requested decision, return target, or wake policy. In practice that means governance exists as logic, but not yet as an operational queue.

• Evidence: GovernanceEngine.checkGate() returns gate_human and propose_and_wait, while recordDecision() only adjusts decision status and getPendingDecisions() is still a stub in packages/server/src/governance/GovernanceEngine.ts lines 132-175.

Recommendation:

• Add Approval and Interaction records in SQLite.
• Include requestedBy, currentParticipant, returnAssignee, status, requestedAction, contextRef, and wakePolicy.
• Wire collaborative and supervised governance to those records instead of a bare gated task state.

Why this transfers well from Paperclip:

• It creates a clean waiting state for humans.
• It gives Lead and Director deterministic resume points.
• It avoids mixing "needs approval", "blocked", and "waiting for clarification" into the same task state.

2. Explicit blocker ownership and unblock actions

Flightdeck has internal dependency sequencing, but it lacks first-class external blocker semantics. A blocked task needs more than a state value. It needs a named owner and exact unblock action.

• Evidence: the task model includes dependsOn and task state, but no blockedReason, blockedOwner, or nextAction fields in packages/shared/src/core/types.ts lines 61-85.
• Evidence: daily reporting lists blocked tasks only by id, title, and state in packages/server/src/reporting/DailyReport.ts lines 27-37 and 69-75.
• Evidence: worker delegation context tells agents "If blocked, use flightdeck_escalate" but does not provide a structured blocker contract in packages/server/src/api/routes/tasks.ts lines 65-72.

Recommendation:

• Keep dependsOn for internal DAG ordering.
• Add explicit blocker metadata for human approvals, secrets, external services, environment issues, or upstream tasks.
• Require every blocked task to record blockedKind, blockedReason, blockedOwner, and blockedAction.

Why this transfers well from Paperclip:

• Paperclip's "blocked with exact unblock owner/action" rule is one of its best governance habits.
• It prevents blocked work from degrading into vague waiting.

3. Scoped wake context instead of generic heartbeat prompts

Flightdeck uses heartbeat-driven management roles effectively, especially Scout, but the current heartbeat guidance is generic. Paperclip's better pattern is to wake an agent with a compact reason-specific context pack and require the agent to respond to the newest signal first.

• Evidence: the default heartbeat template is a general checklist in packages/server/src/storage/ProjectStore.ts lines 33-52.
• Evidence: Scout is explicitly heartbeat-driven and proactive in docs/roles/scout.md lines 3-29.

Recommendation:

• Add a wake-context or heartbeat-context API that returns:
• reason
• latest comments or messages
• tasks changed since last turn
• pending approvals
• new blockers
• expected next action
• For comment-triggered wakes, make the newest comment mandatory context and require the responding agent to acknowledge it before broad exploration.

Why this transfers well from Paperclip:

• It reduces blind polling.
• It keeps token use focused on deltas.
• It improves agent continuity after long-running or intermittent execution.

4. Mandatory run closeout and disposition discipline

Flightdeck has persistent status artifacts, but those artifacts summarize system state more than execution accountability. Paperclip is stricter about every heartbeat ending with an explicit disposition and a "what changed / what remains / next owner" trail.

• Evidence: status.md summarizes counts, epics, active agents, and recent completions, but not next owner/action or unblock responsibility in packages/server/src/status/StatusFileWriter.ts lines 79-140.

Recommendation:

• Require Lead, Director, Worker, and Reviewer to emit a structured closeout after each meaningful turn.
• Include:
• status disposition
• what changed
• what remains
• next owner
• next action
• If blocked, require the blocker owner/action fields above.

Why this transfers well from Paperclip:

• It makes asynchronous handoff auditable.
• It reduces repeated rediscovery on wake.

5. Typed board/user interaction modes

Flightdeck already has good role separation and messaging, but collaborative governance will become brittle if all human coordination is free-form chat.

• Evidence: the architecture and contribution docs show strong separation among Lead, Director, Scout, Workers, and Reviewers, plus channel/DM messaging, in ARCHITECTURE.md lines 128-178 and CONTRIBUTING.md lines 75-96.

Recommendation:

• Model at least three human interaction types:
• request_confirmation
• ask_user_questions
• suggest_tasks
• Keep chat for discussion, but use typed interactions whenever the system needs a decision to resume execution.

What To Avoid Or Simplify

1. Do not copy Paperclip's full company governance model

Paperclip has assignments, checkouts, inboxes, parent/child issue trees, and company-wide routing. Flightdeck does not need all of that yet. It already has a good local project execution model.

Keep:

• role/tool boundaries
• human approval discipline
• blocker clarity
• wake-context discipline

Skip for now:

• global issue inbox semantics
• per-heartbeat checkout ownership
• company org charts and cross-agent board governance

2. Do not add more AI roles before fixing governance primitives

Flightdeck already has a broad role set. The bottleneck is not missing personas. It is missing structured waiting and approval flows.

3. Do not let "heartbeat" become an excuse for polling

Paperclip's better idea is delta-driven wake behavior. Flightdeck should keep periodic Scout passes, but Lead and Director should increasingly wake from specific events, comments, approvals, and blockers.

First Repo And Process Changes

1. Implement ApprovalStore and InteractionStore, then route gate_human and propose_and_wait through them.
2. Extend the task schema and API with blocker metadata: blockedKind, blockedReason, blockedOwner, blockedAction, and optional external reference fields.
3. Add a compact wake-context endpoint for Lead, Director, Scout, and reviewers so each turn starts from deltas rather than broad scans.
4. Extend status.md, daily reports, and task detail views to show next owner/action, not just current state.
5. Add a governance lifecycle doc that defines when work should be running, gated, blocked, in_review, or waiting on a typed human interaction.

Suggested Hiring Or Role Additions

No immediate hiring change is necessary. The repo already has enough conceptual role coverage for the next milestone.

If Flightdeck turns its governance layer into a serious product surface, the next addition should be a human-facing operator or release-manager workflow, not another AI agent role. Later, if security_sensitive approvals become common, a dedicated security reviewer role would be justified.

Bottom Line

Flightdeck's current architecture is strong enough to support Paperclip-style governance. The right adoption path is incremental:

1. keep the current role and DAG model
2. add first-class approvals/interactions
3. add explicit blocker ownership
4. make wakes delta-scoped
5. require end-of-turn closeout

That gives Flightdeck most of Paperclip's operational clarity without inheriting all of its organizational complexity.