mika kuns
f205843020
A child merge that came back blocked/verify_failed/untracked_collision during a parent/children unit merge used to vanish: DrainAsync only logged it server-side, PlanningMergeAborted carried no reason, and ApproveReview/review_task always reported StatusMerged for a task with children regardless of the real outcome, so a failed unit merge left the parent stuck with no visible error. - PlanningMergeOrchestrator.StartAsync/ContinueAsync/DrainAsync now return a PlanningMergeResult(Status, Reason) instead of void, and PlanningMergeAborted carries that reason to the UI. - WorkerHub.ApproveReview and ExternalMcpService.ReviewTask's approve branch propagate the real status/reason for a parent with children instead of hardcoding "merged" (or masking a non-conflict failure as "conflict"). - StartAsync now requires the parent to already be WaitingForReview for improvement parents too, not just planning ones, so a stale caller can no longer trigger a partial child merge. - HasActiveMerge now also covers the window between the last child merging and FinalizeParentDoneAsync completing, closing a gap where a concurrent Cancel could race the parent's own approve-to-Done transition. - IslandsShellViewModel.OnPlanningMergeAborted flashes the reason via FlashFooterError instead of only clearing the external-merge banner.
Explore-notes
Distilled, reusable maps of complex subsystems, produced by deep code exploration. The goal: stop re-exploring the same subsystem from scratch in every new session.
These sit between the CLAUDE.md files and the code:
- CLAUDE.md — high-level orientation, hand-maintained, always-loaded.
- explore-notes — deeper subsystem detail (flows, who-calls-whom, invariants) that is too fine-grained for a CLAUDE.md but stable enough to be worth caching. Read on demand.
- code — the only source of truth.
Index
| Note | Covers |
|---|---|
| worker-task-pipeline | TaskRunner end-to-end: config resolution, worktree, CLI invocation, streaming, commit |
| usage-monitoring | OAuth usage endpoint, gate, throttle, per-run token accounting, usage pill/modal |
| external-mcp | The claudedo MCP tool surface + its two test-enforced conventions |
| review-merge | Approve=merge-unit, verify gate, MergeCommit/revert, diff stack, conflict resolver |
| conpty-sessions | Interactive/planning/list-handler launch specs + the arg-flattening gotcha |
| installer-preflight | CLI version/login/auto-mode research, the ExecutableResolver/shim root cause, and the Installer's Checks/+SystemCheckPage implementation status |
| list-virtualization-spike | Phase 2a gate spike: virtualized ListBox + the existing ghost-drag InputHitTest model, verified headless |
Rules
- Only stable structure. Flows, responsibilities, entry points, invariants, relative file paths. No line numbers, no exhaustive symbol dumps — those rot fastest.
- Verify before trusting. A note is a starting map, not authority. Always confirm against current code before acting on it. Each note records the commit it was verified against so you can diff for drift.
- Not a substitute for CLAUDE.md. If a fact belongs in orientation, put it there.
Header every note must carry
> **Explore-note — verify before trusting.** Distilled map of a subsystem, not authoritative.
> Last verified against commit `<short-hash>` (<date>).
> Drift check: `git log --oneline <short-hash>..HEAD -- <paths this note covers>`
> Stable structure only (no line numbers). See docs/explore-notes/README.md.
Workflow
- Before deep-exploring a subsystem, check for a matching note here and read it first; explore only to fill gaps or confirm.
- After a deep explore, distill the durable findings into a new/updated note and bump its "verified against" commit line.
- If the drift check shows the covered paths changed a lot since the verified commit, treat the note as suspect and re-verify the parts you rely on.