# 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

- [x] **MERGE-01**: Team can list all merge-overwritten hotspots with file-level evidence and risk classification
- [x] **MERGE-02**: Team can restore required new-system logic removed during merge while avoiding duplicate behavior paths
- [x] **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
- [x] **LOGIC-03**: Thread creation/reuse logic remains correct for `thread_id`, `isnew`, and `xclaw_used` combinations
- [x] **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

### Input @ File References (Phase 6)

- [ ] **ATREF-01**: 输入框输入 `@` 时仅展示当前线程（artifacts + uploads）候选，且支持连续输入过滤
- [ ] **ATREF-02**: 选中文件后以可删除 chip 展示，并在同名场景显示“文件名 + 类型 + 路径尾段”，引用上限 10
- [ ] **ATREF-03**: 引用文件复用 `additional_kwargs.files` 提交，含来源元信息；失效引用软剔除并不阻断消息发送
- [ ] **ATREF-04**: 引用能力具备自动化回归验证（单测 + E2E）及按 style/logic/tests/docs 的提交分组计划

### Theme Tokenization and Color Guard (Phase 8)

- [ ] **P8-01**: Workspace 核心页面与组件（thread page、input box、artifact detail/list、workspace layout/header）中的 `bg-[#...]`/`text-[#...]`/`stroke="#..."` 等硬编码颜色迁移为 light/dark 主题 token
- [ ] **P8-02**: 建立颜色 token 注册表并满足“每个 distinct 颜色值对应一个 distinct token 名称”的唯一性约束（禁止多个不同颜色值映射到同名 token）
- [ ] **P8-03**: 增加自动化扫描守卫，阻止新增 `#hex` 与 `bg-[#...]`/`text-[#...]`（含同类 arbitrary color）回归
- [ ] **P8-04**: 覆盖 workspace 关键页面与组件的 light/dark 回归验证（静态扫描 + 自动化用例 + 可复现命令）

## 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 | Complete |
| MERGE-02 | Phase 1 | Complete |
| MERGE-03 | Phase 1 | Complete |
| LOGIC-03 | Phase 2 | Complete |
| LOGIC-04 | Phase 2 | Complete |
| 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 |
| ATREF-01 | Phase 6 | Pending |
| ATREF-02 | Phase 6 | Pending |
| ATREF-03 | Phase 6 | Pending |
| ATREF-04 | Phase 6 | Pending |
| P8-01 | Phase 8 | Pending |
| P8-02 | Phase 8 | Pending |
| P8-03 | Phase 8 | Pending |
| P8-04 | Phase 8 | Pending |

**Coverage:**
- v1 requirements: 21 total
- Mapped to phases: 21
- Unmapped: 0

---
*Requirements defined: 2026-04-07*
*Last updated: 2026-04-07 after initial definition*