docs: initialize project planning artifacts
This commit is contained in:
parent
6411b3d7a0
commit
9015696f83
|
|
@ -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*
|
||||
|
|
@ -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*
|
||||
|
|
@ -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`
|
||||
|
|
@ -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.
|
||||
|
|
@ -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"
|
||||
}
|
||||
Loading…
Reference in New Issue