deerflow2/.planning/PROJECT.md

DeerFlow Frontend Merge Recovery

What This Is

This project is a brownfield recovery and alignment effort for DeerFlow frontend after branch merges introduced regressions and overwrites. It restores missing new-system capabilities while aligning visual styling to the established legacy UX language. It is primarily for the internal development team maintaining chat, artifacts, and skill bootstrap workflows.

Core Value

Keep the frontend visually familiar while preserving and hardening new-system behavior end to end.

Requirements

Validated

• ✓ Chat thread routing, history rendering, and message streaming are already in production workflows — existing
• ✓ Artifact browsing and file detail rendering are already integrated into workspace flows — existing
• ✓ Core frontend/backend API integration for threads, uploads, and skills exists and is operational — existing

Active

• Restore merge-overwritten logic from key author history (including Titan-owned behavior) where still required
• Align visual layer to legacy UI expectations without regressing new-system architecture
• Keep iframe communication and markdown download flows working in the merged codebase
• Add and stabilize E2E tests for thread reuse, input/compose, and message/history integrity
• Produce a clean staged/commit strategy that separates visual, logic, and test concerns

Out of Scope

• Full redesign of the workspace information architecture — not required for merge recovery
• Backend feature expansion unrelated to merge regression scope — defer to future milestone
• New product features beyond current chat/artifact/skill flows — avoid scope creep during stabilization

Context

• The repository is a brownfield monorepo with active frontend and backend development.
• Recent branch merges introduced broad frontend diffs with mixed staged/unstaged states.
• Conflict hotspots include chat routing, skill bootstrap API contracts, memory settings, and high-churn workspace components.
• Key objective from the team: visual alignment to old code style, logical alignment to new system capabilities.
• There is explicit concern that some Titan-authored logic paths were overwritten during conflict resolution.

Constraints

• Compatibility: Must keep existing routes and query behaviors (thread_id, isnew, xclaw_used) stable — avoid breaking external entry links
• Quality: Changes must be split into reviewable commits by concern (style vs logic vs tests) — enables safer rollback
• Scope: Focus on frontend merge recovery first — do not expand into unrelated roadmap items
• Verification: E2E and targeted regression checks must be present before considering recovery complete

Key Decisions

Decision	Rationale	Outcome
Preserve old visual language while keeping new-system logic primitives	Minimizes user disruption while retaining technical evolution	— Pending
Treat merge recovery as a dedicated milestone with explicit conflict inventory	Reduces accidental loss during ad-hoc edits	— Pending
Prioritize Titan-overlap files for first-pass reconciliation	Highest risk of silent behavior regression	— Pending
Split commits by concern area (style, logic, tests)	Improves review quality and rollback safety	— Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd-transition):

1. Requirements invalidated? -> Move to Out of Scope with reason
2. Requirements validated? -> Move to Validated with phase reference
3. New requirements emerged? -> Add to Active
4. Decisions to log? -> Add to Key Decisions
5. "What This Is" still accurate? -> Update if drifted

After each milestone (via /gsd-complete-milestone):

1. Full review of all sections
2. Core Value check - still the right priority?
3. Audit Out of Scope - reasons still valid?
4. Update Context with current state

---

Last updated: 2026-04-07 after initialization