Build-blocker fix plan (2-week triage): what stops Marcus from building projects

[lwgray]

What is this, briefly

Marcus is an open-source system that takes a plain-English description of a software project, breaks it into tasks on a kanban board, and has independent AI coding agents build those tasks in parallel (each in its own git worktree), coordinating only through the shared board — never by talking to each other.

A build-blocker is a bug that stops Marcus from turning a description into a working project. It fails in one of three ways: the run hangs or loops and never finishes; it reports "done" but ships a broken app; or it quietly corrupts the task graph so the wrong thing gets built. This issue is the single tracking list for every build-blocker found in the last two weeks of bug reports (issues filed since ~2026-05-23).

How to read the priorities

• P0 — Land fixes that already exist. The fix is written or designed; landing it is the fastest unblock.
• P1 — Runaway / hang hard-stops. The run never finishes (infinite spawn loop, stuck-BLOCKED task, gridlock). No fix yet.
• P2 — Gate ships broken apps. The run "completes" but the app doesn't actually work, because the composition/verification gate passed something broken.
• P3 — Task-graph corruption. The run usually completes, but larger/more-complex projects get the wrong task graph (dropped features, duplicate work, orphan code). Severity scales with project size.

Dependency edges: #627 → #629 (the recovery tool enables the integration-claim fix) · #669 → #615 (root cause → symptom) · #693 ← #691 (detector backs the prompt fix).

P0 — land existing fixes

• Critical: Validation evidence collection sends entire worktree instead of agent delta — token explosion blocks parallel runs #696 — merge PR fix(#696): git-delta scoping + file manifest for validation evidence #697 (scope validation to the agent's git delta + manifest; stops the whole-worktree token explosion that overflows the 200k limit and blocks all parallel runs)
• bug: integration-verification task enters infinite agent spawn loop — lease too short + stale-completion rejection + no spawn-controller backoff = runaway when LLM calls fail #667 Fix 3 — autonomous BLOCKED after N silent recoveries + spawn-controller backoff (stops the infinite integration-verify spawn loop; Fixes 1/2/4 already merged in fix(#667): validation window + transactional late-completion-accept #668/fix(#667): trim orphaned subtasks from Marcus's in-memory working set (non-destructive; protects Cato) #673)

P1 — runaway / hang hard-stops

• bug: ephemeral subtask spawning explosion — todo-completion-2 created 279 worktrees for a 9-task project #628 — worktree spawn explosion (279 worktrees for a 9-task project); root-cause the O(N²) subtask×lifecycle / cleanup-misread
• Merge conflict leaves dirty index; rebase recovery fails with 'uncommitted changes' — task stuck blocked despite completed work #700 — clean the index before the merge-recovery rebase (git reset --merge/abort/stash) so conflicted tasks don't stick BLOCKED forever
• feat: add request_task_redo MCP tool so integration agents can send failed work back without violating Invariant #2 #627 — add request_task_redo MCP tool (recovery enabler) → then bug: integration-verification task never claims when an upstream dependency stays in BLOCKED or partial-done state #629 — best-effort/recovery claim path for the terminal integration task when an upstream stays BLOCKED/partial
• bug: integration verification dead-ends into project gridlock when the agent never declares verifications #676 — escape hatch for the verification-declare reject loop + guard the JSON-parse crash (stops project-wide gridlock)

P2 — gate ships broken apps

• bug: composition/integration verify that the project BUILDS, not that it BEHAVES — and the checks assume web (curl 2xx / DOM), not pipelines/CLIs/libraries #677 — gate must prove the app BEHAVES, not just BUILDS, and handle non-web stacks (linchpin: bug: composition+verify pipeline ships unplayable apps when spec-coverage gap-fill creates redundant tasks (orphan source trees pass smoke gate) #636/bug: composition step doesn't detect orphan source trees — agent-built files that no task imports get ignored #638/bug: verify-snake-5 ships with stale-state bug in setNextDirection — LEFT arrow permanently blocked (build verification doesn't catch behavioral correctness) #654/bug: verification-command generator infers tech stack from prose, not the scaffold's actual dependency manifest #643 funnel through it)
• bug: composition step doesn't detect orphan source trees — agent-built files that no task imports get ignored #638 — detect orphan source trees (files no task imports → unwired, unplayable apps)
• Composition task reimplements domain logic instead of wiring it (presentation renderer shadowed in test109) #691 + Detect when the composition agent shadows a domain export (imported-but-never-used) — the detection half of #691 #693 — build the shadowed-export detector (Detect when the composition agent shadows a domain export (imported-but-never-used) — the detection half of #691 #693) behind the feat(#691): instruct composition agent to wire domains, not reimplement them #692 prompt fix (composition reimplementing instead of wiring domain logic)
• bug: verification-command generator infers tech stack from prose, not the scaffold's actual dependency manifest #643 — feed the real dependency manifest to the verification-command generator (kills hallucinated tools like playwright on a Vite-only scaffold)
• bug: trivial-spec /marcus runs ship wrong-language output and over-decompose (constraint-drop in 5 prompts + domain floor for prototype mode) #649 — trivial-spec: relax domain floor + preserve the language constraint (ships TS for "vanilla JS") + composer build-check
• bug: composition+verify pipeline ships unplayable apps when spec-coverage gap-fill creates redundant tasks (orphan source trees pass smoke gate) #636 — resolve smoke-gate ownership (Marcus-authored contract verification, Invariant Task Assigned 4 times #2 v2); overlaps bug: composition/integration verify that the project BUILDS, not that it BEHAVES — and the checks assume web (curl 2xx / DOM), not pipelines/CLIs/libraries #677/feat: promote contract verification gate from soft rollout to hard cutover (drop agent-authored verifications path) #647

P3 — task-graph corruption (scales with size)

• Contract consistency gate: compare type structure, not type names (false-positive fallback) #669 → contract_first systematically falls back at standard+ via cross-contract type-consistency check #615 — contract consistency gate: compare type structure, not names (Contract consistency gate: compare type structure, not type names (false-positive fallback) #669 is the root cause of the contract_first systematically falls back at standard+ via cross-contract type-consistency check #615 contract_first→feature_based silent downgrade at standard+)
• bug: gap-fill rollup (#611) misroutes criteria onto semantically unrelated tasks — keyboard handler landed on Vite-setup task #665 — LLM-pick the gap-fill criteria anchor (stop misrouting behaviors onto unrelated tasks → silently dropped features)
• bug: spec_coverage augmenter inserts redundant gap-fill tasks for umbrella phrases already covered by other tasks #637 — fix umbrella-phrase false-positive gap-fill (source of orphan code)
• Functional requirements with empty descriptions fall through to infrastructure stub #617 — replace the empty-description boilerplate stub with real task content
• Decomposer emits near-duplicate tasks at enterprise complexity (no fuzzy dedup pass) #620 — fuzzy dedup for enterprise near-duplicate tasks (stop double-implementation)
• Design-ghost auto-completion is non-deterministic (status=todo sometimes instead of done) #619 — make design-ghost auto-completion deterministic (design tasks stuck todo block the graph)
• _collect_task_artifacts uses wrong kanban_client.get_attachments contract (same bug as #623) #624 — fix the get_attachments contract (stop silently dropping kanban artifacts from agent context)

Glossary

Term	Meaning
worktree	a per-agent private git checkout so parallel agents don't clobber each other's files
composition	the final task that wires separately-built domain modules into one runnable app
integration-verification / smoke gate	the terminal task that builds + runs the composed app and checks user-facing outcomes work
orphan source tree	files committed to the repo that nothing imports — present but never executed
design-ghost	a design task Marcus pre-computes and stamps done so no agent has to claim it
gap-fill	an augmenter that adds tasks/criteria for spec items it thinks no task covers
contract_first	the decomposition strategy that writes per-domain interface type contracts before implementation

How this was triaged

Read all open bug issues filed since ~2026-05-23, clustered them by pipeline stage (decompose → dispatch → spawn → compose → verify/merge), assessed each for whether and how it scales with project size or parallelism, and cross-referenced the PRs that do or don't fix it.

Related

• Milestone: v0.3.9 (due 2026-07-23)
• Already fixed (verify & close): [Bug] Required features silently dropped during decomposition → no implementation task → #680 gotchas orphaned #683 (PRs feat(#683 Cause 2): synthesize impl tasks for core gaps with no implementation home #687/feat(#683 Cause 1): outcome-aware feature filter — cap by complexity tier, never drop a core feature #688) · perf: request_next_task makes a Claude LLM call on every poll (the real 13-15s regression) #626 (PR perf(context): cache analyze_dependencies + thundering-herd lock (#626) #631) · bug: Marcus marks tasks DONE in kanban when worktree merge to main fails — filesystem/kanban divergence (root cause of verify-snake-4 broken-game failure) #651 (PRs fix(#651): mark task BLOCKED when worktree merge to main fails #653/feat(#651): auto-recover BLOCKED-by-merge-conflict tasks via worktree rebase (Option A) #656/feat(#206): file-level lock registry MVP (baton arbitration) #658)
• Deferred: feat: promote contract verification gate from soft rollout to hard cutover (drop agent-authored verifications path) #647 (v0.6.0 — hard cutover, gated on >90% happy-path data)

[linear-code]

PM-316

[lwgray]

Re-sequenced by the session-model plan (see #706)

The P0–P3 ordering below is superseded by a 6-phase plan that accounts for the migration to long-lived pull-loop sessions (#706). What changes for THIS epic:

• Phase 1 (start now, re-architecture-safe): bug: integration-verification task enters infinite agent spawn loop — lease too short + stale-completion rejection + no spawn-controller backoff = runaway when LLM calls fail #667 (circuit-breaker half only) → Merge conflict leaves dirty index; rebase recovery fails with 'uncommitted changes' — task stuck blocked despite completed work #700 (bridge index-clean fix) → bug: integration verification dead-ends into project gridlock when the agent never declares verifications #676 → feat: add request_task_redo MCP tool so integration agents can send failed work back without violating Invariant #2 #627 → bug: integration-verification task never claims when an upstream dependency stays in BLOCKED or partial-done state #629 → _collect_task_artifacts uses wrong kanban_client.get_attachments contract (same bug as #623) #624
• Deleted instead of fixed (on the Phase-3 launcher landing, tracked in Epic: session-model migration — spawn-per-task → long-lived pull-loop sessions #706): bug: ephemeral subtask spawning explosion — todo-completion-2 created 279 worktrees for a 9-task project #628, Spawn-thrash detector tears down healthy-but-slow runs (resets only on task completion) #703, and bug: integration-verification task enters infinite agent spawn loop — lease too short + stale-completion rejection + no spawn-controller backoff = runaway when LLM calls fail #667's spawn-backoff half — do not spend weekends on these
• Phase 4 (verification moat, unchanged): bug: composition/integration verify that the project BUILDS, not that it BEHAVES — and the checks assume web (curl 2xx / DOM), not pipelines/CLIs/libraries #677 → bug: verification-command generator infers tech stack from prose, not the scaffold's actual dependency manifest #643 → bug: composition+verify pipeline ships unplayable apps when spec-coverage gap-fill creates redundant tasks (orphan source trees pass smoke gate) #636 → bug: composition step doesn't detect orphan source trees — agent-built files that no task imports get ignored #638 → Detect when the composition agent shadows a domain export (imported-but-never-used) — the detection half of #691 #693
• Phase 5 (WAIT for the seam ADR in Epic: session-model migration — spawn-per-task → long-lived pull-loop sessions #706): Contract consistency gate: compare type structure, not type names (false-positive fallback) #669→contract_first systematically falls back at standard+ via cross-contract type-consistency check #615, bug: gap-fill rollup (#611) misroutes criteria onto semantically unrelated tasks — keyboard handler landed on Vite-setup task #665, bug: spec_coverage augmenter inserts redundant gap-fill tasks for umbrella phrases already covered by other tasks #637, Decomposer emits near-duplicate tasks at enterprise complexity (no fuzzy dedup pass) #620, Design-ghost auto-completion is non-deterministic (status=todo sometimes instead of done) #619, Functional requirements with empty descriptions fall through to infrastructure stub #617, bug: trivial-spec /marcus runs ship wrong-language output and over-decompose (constraint-drop in 5 prompts + domain floor for prototype mode) #649 — decomposition granularity moves to the session seam first, then each of these gets re-triaged at the new coarse granularity (some will shrink or vanish). Fixing them at today's fine granularity is likely throwaway work.

Interim rule: no large experiments until #706 Phase 3 lands — the shed bugs still bite live runs.

Gate unchanged in spirit, upgraded in content: 5 consecutive unattended runs of the Shape-B benchmark (contract → 4 components → integrate+verify), behaviorally verified.