From 67e73047488737e87648d063f3886b6145ef323e Mon Sep 17 00:00:00 2001 From: MT-Mint <798521692@qq.com> Date: Tue, 7 Apr 2026 11:54:45 +0800 Subject: [PATCH] docs: initialize project planning artifacts --- .planning/PROJECT.md | 75 +++++++++++++++++++++++++++++++++++++++ .planning/REQUIREMENTS.md | 73 +++++++++++++++++++++++++++++++++++++ .planning/ROADMAP.md | 57 +++++++++++++++++++++++++++++ .planning/STATE.md | 26 ++++++++++++++ .planning/config.json | 41 +++++++++++++++++++++ 5 files changed, 272 insertions(+) create mode 100644 .planning/PROJECT.md create mode 100644 .planning/REQUIREMENTS.md create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md create mode 100644 .planning/config.json diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 00000000..3ce5c1b2 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,75 @@ +# 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* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 00000000..bb4297d7 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,73 @@ +# Requirements: DeerFlow Frontend Merge Recovery + +**Defined:** 2026-04-07 +**Core Value:** Keep the frontend visually familiar while preserving and hardening new-system behavior end to end. + +## v1 Requirements + +### Merge Reconciliation + +- [ ] **MERGE-01**: Team can list all merge-overwritten hotspots with file-level evidence and risk classification +- [ ] **MERGE-02**: Team can restore required new-system logic removed during merge while avoiding duplicate behavior paths +- [ ] **MERGE-03**: Team can identify and reconcile Titan-overlap code paths with explicit keep/replace decisions + +### UI Visual Alignment + +- [ ] **UI-01**: Workspace visual style aligns with legacy baseline for typography, spacing, and component hierarchy +- [ ] **UI-02**: Visual alignment changes do not break chat/thread/artifact interactions +- [ ] **UI-03**: Global style changes remain consistent across main workspace pages + +### New-System Logic Integrity + +- [ ] **LOGIC-01**: iframe communication flow functions correctly for selected skill and parent message events +- [ ] **LOGIC-02**: Markdown download flow works from generation to export trigger in workspace +- [ ] **LOGIC-03**: Thread creation/reuse logic remains correct for `thread_id`, `isnew`, and `xclaw_used` combinations +- [ ] **LOGIC-04**: Skills bootstrap API contract is explicitly reconciled (`content_id` vs `content_ids`) without silent breakage + +### Quality and Regression Safety + +- [ ] **TEST-01**: E2E tests cover message/history, input/compose, welcome/routing, and artifact/thread reuse flows +- [ ] **TEST-02**: Recovery changes are committed in separable concern groups (style vs logic vs tests) +- [ ] **TEST-03**: Critical conflict files have before/after verification notes for reviewer auditing + +## v2 Requirements + +### Tooling Improvements + +- **TOOL-01**: Add automated conflict hotspot detector for future merges +- **TOOL-02**: Add style-vs-logic diff classifier script for commit preparation + +## Out of Scope + +| Feature | Reason | +|---------|--------| +| New product feature development unrelated to merge recovery | Would dilute stabilization focus | +| Backend architecture refactors not required by frontend recovery | Not necessary for current milestone objective | +| Full design system reimplementation | Too large for recovery scope | + +## Traceability + +| Requirement | Phase | Status | +|-------------|-------|--------| +| MERGE-01 | Phase 1 | Pending | +| MERGE-02 | Phase 1 | Pending | +| MERGE-03 | Phase 1 | Pending | +| LOGIC-03 | Phase 2 | Pending | +| LOGIC-04 | Phase 2 | Pending | +| UI-01 | Phase 3 | Pending | +| UI-02 | Phase 3 | Pending | +| UI-03 | Phase 3 | Pending | +| LOGIC-01 | Phase 4 | Pending | +| LOGIC-02 | Phase 4 | Pending | +| TEST-01 | Phase 5 | Pending | +| TEST-02 | Phase 5 | Pending | +| TEST-03 | Phase 5 | Pending | + +**Coverage:** +- v1 requirements: 13 total +- Mapped to phases: 13 +- Unmapped: 0 + +--- +*Requirements defined: 2026-04-07* +*Last updated: 2026-04-07 after initial definition* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 00000000..2c7a7558 --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,57 @@ +# Roadmap: DeerFlow Frontend Merge Recovery + +**Created:** 2026-04-07 +**Source:** .planning/PROJECT.md + .planning/REQUIREMENTS.md + +## Phase 1: Conflict Inventory and Decision Matrix + +**Goal:** Build an auditable conflict inventory covering merge-overwritten regions, Titan-overlap regions, and keep/replace candidates. + +**Covers:** MERGE-01, MERGE-03 + +- Produce file-level conflict matrix with risk levels +- Mark visual-only, logic-only, and mixed-change files +- Identify Titan-linked hotspots and expected behavior per hotspot + +## Phase 2: Thread and Skills Logic Reconciliation + +**Goal:** Reconcile thread bootstrap/routing and skills API logic so merged behavior is explicit and stable. + +**Covers:** MERGE-02, LOGIC-03, LOGIC-04 + +- Reconcile `thread_id`/`isnew`/`xclaw_used` behavior in chat flow +- Decide and implement skills bootstrap contract direction +- Verify no duplicate or dead logic paths remain + +## Phase 3: Legacy Visual Alignment Pass + +**Goal:** Align workspace visual presentation to legacy baseline without regressing logic. + +**Covers:** UI-01, UI-02, UI-03 + +- Apply visual alignment in layout and component layers +- Keep behavioral code intact while adjusting style semantics +- Validate visual consistency across core workspace views + +## Phase 4: Iframe + Markdown New-System Stabilization + +**Goal:** Keep and harden new-system capabilities for iframe communication and markdown export. + +**Covers:** LOGIC-01, LOGIC-02 + +- Stabilize parent/child messaging and selected-skill event flows +- Stabilize markdown conversion and download triggers +- Validate artifact integration points + +## Phase 5: Test Hardening and Commit Hygiene + +**Goal:** Lock recovery with regression tests and clean commit structure. + +**Covers:** TEST-01, TEST-02, TEST-03 + +- Finalize and run E2E suite for target scenarios +- Split commits into style / logic / tests concern buckets +- Attach reviewer-oriented verification notes for high-risk files + +--- +*Next command:* `/gsd-plan-phase 1` diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 00000000..3b0f7f49 --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,26 @@ +# STATE.md + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-04-07) + +**Core value:** Keep the frontend visually familiar while preserving and hardening new-system behavior end to end. +**Current focus:** Phase 1 - Conflict Inventory and Decision Matrix + +## Workflow State + +- Current workflow: new-project completed +- Next workflow: plan-phase +- Next command: /gsd-plan-phase 1 + +## Artifacts + +- PROJECT: .planning/PROJECT.md +- REQUIREMENTS: .planning/REQUIREMENTS.md +- ROADMAP: .planning/ROADMAP.md +- CODEBASE MAP: .planning/codebase/ + +## Notes + +- Repository is brownfield with active uncommitted merge-recovery changes in frontend. +- Planning docs were initialized specifically for merge recovery and alignment. diff --git a/.planning/config.json b/.planning/config.json new file mode 100644 index 00000000..95ab1575 --- /dev/null +++ b/.planning/config.json @@ -0,0 +1,41 @@ +{ + "model_profile": "balanced", + "commit_docs": true, + "parallelization": true, + "search_gitignored": false, + "brave_search": false, + "firecrawl": false, + "exa_search": false, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}", + "quick_branch_template": null + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true, + "auto_advance": false, + "node_repair": true, + "node_repair_budget": 2, + "ui_phase": true, + "ui_safety_gate": true, + "text_mode": false, + "research_before_questions": false, + "discuss_mode": "discuss", + "skip_discuss": false, + "code_review": true, + "code_review_depth": "standard" + }, + "hooks": { + "context_warnings": true + }, + "project_code": null, + "phase_naming": "sequential", + "agent_skills": {}, + "resolve_model_ids": "omit", + "mode": "yolo", + "granularity": "standard" +} \ No newline at end of file