Multi-architect coordination layer for codev/afx (roster · board · dedup-at-spawn · lifecycle · bounded state · checkout isolation)

[waleedkadous]

SPIR feature. A first-class coordination layer for multi-architect workspaces in codev/afx. From a field report by a heavy-use private workspace (peak 5 architects + 7 builders), generalized and routed via the relaying operator. Build all six points as one coherent SPIR.

Problem

Codev lets an operator spawn N architects but gives no first-class way to see, route, dedup, or retire them — so every coordination function falls back on the one human. Observed failure modes (all recurred):

1. Human is the registry — no command answers "which architect owns what."
2. Human is the message router — cross-architect coordination relayed by hand (sibling messaging exists but is under-surfaced).
3. Duplicate investigation — one symptom independently investigated by 3 architects under 3 issues; overlap found only after the fact (~3× cost). No code collision.
4. Lifecycle / state drift — ~14 architect identities in ~2 weeks; retirement by hand-renaming state files to *-inactive; some live architects have no state file; one appointed architect's state file was never created. State files grow unbounded (tens of KB of strikethrough history), making resume-cold expensive.
5. Shared checkout couples the fleet — all architects share one git checkout; a branch switch by any one yanks it from siblings, and builders branch from the shared HEAD, so one stale checkout = everyone's stale builders. Current mitigation is a fragile "never switch branches" discipline rule.

An audit found the fleet's actual code changes are largely orthogonal — the problem is coordination, not diff contention.

Scope — all six (one SPIR)

1. Architect roster — afx architects: table of each architect, owned open issues, live builders, last-activity, state-file path. Single source of truth for "who owns what."
2. Unified board / digest — auto-generated cross-architect open-thread digest (one artifact vs N state files), regenerated on spawn/gate/merge. Columns: item, owning architect, state, who-owes-next. Prefer extending the existing dashboard Work view / afx tower over a separate artifact.
3. Issue-ownership ledger + dedup-at-spawn — record issue→architect on spawn (spawn already knows the spawning architect via affinity Multi-architect routing: builder→architect messages misrouted to 'main' when worktree has its own state.db #774); warn + require override when a second architect spawns on an already-owned issue. Issue-level dedup only; fuzzy "same symptom" matching is out of scope for now.
4. Formal lifecycle — enhance the existing afx workspace add-architect / remove-architect: enforce a state file on add (from a template); archive + release builders/issues on retire. (The add/remove commands already exist; the gap is the state-file + archive/release semantics, not the commands.)
5. Bounded, templated state files — cap the "current state" head + auto-rotate history, so resume-cold cost stays predictable. Applies to codev/state/<id>_thread.md.
6. Per-architect checkout isolation — give each architect its own checkout root/worktree, eliminating shared-checkout coupling, the stale-HEAD → stale-builder hazard, and the "never switch branches" constraint. Largest/riskiest piece — touches Tower, the builder-base model, and disk; needs careful design + 3-way review.

What already exists (build the gaps, not duplicates)

• afx workspace add-architect and remove-architect exist → Installation Process Failures - Multiple Steps Being Skipped #4 is an enhancement.
• afx status lists architects; afx tower is a cross-project board; sibling messaging afx send architect:<name> exists but is under-surfaced → Context Window Optimization - AI Needs Project Knowledge Without Breaking Limits #2 router.
• No afx architects roster, no ownership ledger / dedup-at-spawn, no bounded-state mechanism, no per-architect checkout.

Suggested sequencing (for the plan)

#3 + #1 (dedup + roster) are highest-leverage / cheapest; #5 is contained; #4 / #2 are enhancements of existing surfaces; #6 is the big structural fix and should be designed carefully (possibly staged last).

Notes

• Generalized pattern; source workspace is private. Full detail available from the source architect via the relaying operator.