dw-kit 1.4.0 → 1.6.0-rc.1

package/.claude/skills/dw-execute/SKILL.md

@@ -18,14 +18,20 @@ Task: **$ARGUMENTS**
 - `tracking.log_work` → ghi effort tracking không
 - `workflow.default_depth` → `thorough` = cần docs-update, review bắt buộc
 
-## Detect Task Format (v1 vs v2)
+## Detect Task Format (v3 / v2 / v1)
 
-Kiểm tra `{paths.tasks}/$ARGUMENTS/`:
-- **v2**: có `spec.md` + `tracking.md` → đọc/ghi 2 files này.
+Kiểm tra `{paths.tasks}/$ARGUMENTS/` theo thứ tự ưu tiên:
+- **v3** (default, per ADR-0008): có `task.md` → đọc/ghi 1 file này.
+- **v2**: có `spec.md` + `tracking.md` → đọc/ghi 2 files; gợi ý migrate: `dw task migrate $ARGUMENTS`.
 - **v1** (legacy): có `-context.md`/`-plan.md`/`-progress.md` → đọc/ghi bộ 3 files.
 
 ## Trước Khi Bắt Đầu
 
+**v3:**
+1. Đọc `{paths.tasks}/$ARGUMENTS/task.md` — Sections 1-5: Snapshot, Intent & Scope (incl. Subtasks + Success Criteria), Subtask Tracker, Timeline/Changelog, Handoff.
+2. Xác nhận frontmatter `status: Approved` hoặc `In Progress`.
+3. Optional: `dw task show $ARGUMENTS` để quick ANSI snapshot.
+
 **v2:**
 1. Đọc `{paths.tasks}/$ARGUMENTS/spec.md` — Intent, Scope, Subtasks, Success Criteria, Research Findings.
 2. Đọc `{paths.tasks}/$ARGUMENTS/tracking.md` — Subtask Progress table, Changelog, Handoff Notes.
@@ -64,6 +70,13 @@ Nếu có progress → tiếp tục từ subtask cuối cùng chưa done.
 - Nếu `quality.block_on_fail = false` → cảnh báo, cho phép tiếp tục
 
 ### Step 5: Cập nhật Progress
+
+**v3** (default): Cập nhật `{paths.tasks}/$ARGUMENTS/task.md`:
+- Section 3 (Subtask Tracker): update row với status `✅ Done`, Date, Notes (commit SHA). **Đây là single source of truth — KHÔNG paste status vào Section 2**.
+- Section 4 (Timeline/Changelog): append entry với heading `### {date} — ST-N complete`, body: actions taken / decisions / pain points.
+- Update frontmatter `last_updated`. Update Section 1 Snapshot fields (Phase, Status).
+- Lint check: `dw task lint $ARGUMENTS` — báo drift markers nếu rò vào Section 2.
+
 **v2**: Cập nhật `{paths.tasks}/$ARGUMENTS/tracking.md`:
 - Update row trong section `## Subtask Progress` table với status `✅ Done`, Date, Notes (commit SHA).
 - Append entry vào `## Changelog` theo format:
@@ -79,7 +92,7 @@ Nếu có progress → tiếp tục từ subtask cuối cùng chưa done.
 ```
 
 Nếu `tracking.log_work = true`, ghi effort thực tế:
-- **v2**: thêm cột "Actual" vào Subtask Progress table hoặc ghi trong Changelog entry.
+- **v3/v2**: thêm cột "Actual" vào Subtask Tracker table hoặc ghi trong Changelog entry.
 - **v1**:
   ```markdown
   ### Effort Log
@@ -114,7 +127,7 @@ Subtask ST-N of $ARGUMENTS
 
 ## Khi Hoàn Thành Tất Cả Subtasks
 
-1. Cập nhật status: **v2** `tracking.md` frontmatter `status: Done` · **v1** progress.md `Trạng thái: Done`.
+1. Cập nhật status: **v3** `task.md` frontmatter `status: Done` · **v2** `tracking.md` frontmatter `status: Done` · **v1** progress.md `Trạng thái: Done`.
 2. Tóm tắt: subtasks completed, commits, issues encountered
 3. Luôn gợi ý: "Tiếp theo: `/dw:review $ARGUMENTS`"
 4. Nếu `workflow.default_depth = thorough`: "Cần chạy `/dw:docs-update $ARGUMENTS`"

package/.claude/skills/dw-handoff/SKILL.md

@@ -23,8 +23,9 @@ git stash list               # stashed work
 
 ### 2. Task progress
 
-**Detect format**: Nếu có `tracking.md` → v2. Nếu có `-progress.md` → v1.
+**Detect format**: Nếu có `task.md` → v3 (default). Nếu có `tracking.md` → v2. Nếu có `-progress.md` → v1.
 
+- **v3** (default): Đọc `{paths.tasks}/$ARGUMENTS/task.md` — Section 3 Subtask Tracker, Section 4 Changelog, Section 5 Handoff & Friction.
 - **v2**: Đọc `{paths.tasks}/$ARGUMENTS/tracking.md` — Subtask Progress table, Changelog, Handoff Notes (nếu đã có).
 - **v1**: Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`.
 
@@ -40,11 +41,13 @@ Tìm:
 
 ## Viết Handoff Notes
 
+**v3** (default): Update `## 5. Handoff & Friction` section trong `{paths.tasks}/$ARGUMENTS/task.md`. Replace nội dung "For next session" hoặc append new entry. Cũng update frontmatter `last_updated` và Section 1 Snapshot (Phase, Status, Blockers). KHÔNG paste status markers vào Section 2 (drift prevention per lint).
+
 **v2**: Replace (hoặc append nếu muốn giữ lịch sử) section `## Handoff Notes` trong `{paths.tasks}/$ARGUMENTS/tracking.md`. Cũng update frontmatter `last_updated`.
 
 **v1**: Ghi vào mục "Handoff Notes" trong `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`.
 
-Format (chung cho cả 2):
+Format (chung cho 3 format):
 
 ```markdown
 ## Handoff Notes
@@ -86,7 +89,9 @@ Sau khi ghi xong, hiển thị:
 - Tóm tắt handoff notes
 - Lệnh để người/agent tiếp theo bắt đầu:
   ```
-  Đọc: {paths.tasks}/$ARGUMENTS/tracking.md     (v2)
+  Đọc: {paths.tasks}/$ARGUMENTS/task.md     (v3 default)
+    hoặc {paths.tasks}/$ARGUMENTS/tracking.md     (v2)
     hoặc {paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md  (v1 legacy)
+  Snapshot: dw task show $ARGUMENTS
   Tiếp tục: /dw:execute $ARGUMENTS
   ```

package/.claude/skills/dw-plan/SKILL.md

@@ -28,15 +28,17 @@ Task: **$ARGUMENTS**
 - CHỈ đọc, phân tích, và viết plan
 - DỪNG LẠI cuối cùng để chờ user/TL approve
 
-## Detect Task Format (v1 vs v2)
+## Detect Task Format (v3 / v2 / v1)
 
-Kiểm tra `{paths.tasks}/$ARGUMENTS/`:
+Kiểm tra `{paths.tasks}/$ARGUMENTS/` theo thứ tự ưu tiên:
+- **v3** (default per ADR-0008): có `task.md` → plan output update Section 2 (Intent & Scope subsections Subtasks/Out of Scope/Success Criteria/Risk Register/Dependencies).
 - **v2**: có `spec.md` + `tracking.md` → plan output update trực tiếp vào `spec.md` (sections Scope/Subtasks/Risks/Success Criteria).
 - **v1** (legacy): có `-context.md`/`-plan.md`/`-progress.md` → plan output ghi vào `$ARGUMENTS-plan.md`.
 - Chưa có gì → gợi ý `/dw:task-init $ARGUMENTS` trước.
 
 ## Bước 1: Đọc Context
 
+- **v3** (default): Đọc `{paths.tasks}/$ARGUMENTS/task.md` Section 2 (đã có Research Findings subsection nếu chạy `/dw:research`).
 - **v2**: Đọc `{paths.tasks}/$ARGUMENTS/spec.md` (bao gồm section `## Research Findings` nếu đã chạy `/dw:research`).
 - **v1**: Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md` — file research đã tạo.
 - Nếu chưa có research findings → thông báo: "Cần chạy `/dw:research $ARGUMENTS` trước."
@@ -71,6 +73,17 @@ Thứ tự subtasks theo dependency graph:
 
 ## Bước 4: Viết plan
 
+**v3** (default): Update `task.md` trực tiếp — điền vào Section 2 subsections:
+- `### Subtasks (in scope)`: ST-1, ST-2, ... với Acceptance criteria. KHÔNG dùng status markers (✅🟡) ở đây — drift markers trigger lint error.
+- `### Out of Scope`: các điểm loại trừ rõ ràng.
+- `### Success Criteria`: checkbox list measurable.
+- `### Dependencies`: upstream blockers / external.
+- `### Risk Register` (optional, thorough only): table | ID | Risk | Severity | Mitigation | Owner |.
+
+Section 3 (Subtask Tracker): khởi tạo với 1 row per ST, status `⬜ Pending`. Đây là single source of truth cho status.
+Frontmatter: đổi `status: Draft` → `status: Approved` chỉ SAU khi user approve.
+Update Section 1 Snapshot fields (Phase, Status, Next milestone).
+
 **v2**: Update `spec.md` trực tiếp — điền vào các section có sẵn:
 - `## Scope → In Scope`: thêm ST-1, ST-2, ... với mô tả + acceptance + effort
 - `## Scope → Out of Scope`: các điểm loại trừ rõ ràng

package/.claude/skills/dw-research/SKILL.md

@@ -24,17 +24,17 @@ Task: **$ARGUMENTS**
 
 Đọc `.dw/config/dw.config.yml` → lấy `paths.tasks` để biết output location.
 
-## Detect Task Format (v1 vs v2)
+## Detect Task Format (v3 / v2 / v1)
 
-Kiểm tra `{paths.tasks}/$ARGUMENTS/`:
+Kiểm tra `{paths.tasks}/$ARGUMENTS/` theo thứ tự ưu tiên:
+- Nếu có `task.md` → **v3 format** (default per ADR-0008). Output ghi vào Section 2 (Intent & Scope) subsection "## Research Findings" hoặc Appendage `research.md`.
 - Nếu có `spec.md` + `tracking.md` → **v2 format**. Output ghi vào spec.md section "## Research Findings".
 - Nếu có `-context.md`/`-plan.md`/`-progress.md` → **v1 format** (legacy). Output ghi vào `$ARGUMENTS-context.md` như cũ.
 - Nếu chưa có gì → gợi ý user chạy `/dw:task-init $ARGUMENTS` trước.
 
-Trong các bước dưới, "context file" = `spec.md` (v2) hoặc `$ARGUMENTS-context.md` (v1).
-
 ## Bước 1: Đọc yêu cầu
 
+- **v3** (default): Đọc `{paths.tasks}/$ARGUMENTS/task.md` Section 2 (Intent + Scope + Subtasks).
 - **v2**: Đọc `{paths.tasks}/$ARGUMENTS/spec.md` lấy Intent + Scope.
 - **v1**: Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md` nếu đã có mô tả yêu cầu.
 - Hoặc lấy yêu cầu từ conversation context.
@@ -63,6 +63,8 @@ Từ framework `.claude/skills/dw-thinking/THINKING.md`:
 
 ## Bước 4: Ghi kết quả
 
+**v3 format** (default): Trong `{paths.tasks}/$ARGUMENTS/task.md`, append subsection `### Research Findings` dưới Section 2 "Intent & Scope" (sau `### Why Now`, trước `### Subtasks`). Hoặc tạo appendage file `research.md` trong cùng folder nếu research dài (>100 dòng). KHÔNG paste status markers vào Section 2.
+
 **v2 format**: Append (hoặc replace nếu đã có) section `## Research Findings` vào `spec.md`, đặt ngay sau section `## Intent`. Giữ frontmatter và các section khác không đổi.
 
 **v1 format** (legacy): Ghi vào `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md`.
@@ -117,7 +119,7 @@ Dùng template `.claude/templates/agent-report.md` với:
 - Details: key files, patterns, dependencies
 - Next Steps: những gì planner cần biết
 
-> Quick depth tasks: bỏ qua bước này — tracking.md (v2) / progress.md (v1) đã đủ.
+> Quick depth tasks: bỏ qua bước này — task.md (v3) / tracking.md (v2) / progress.md (v1) đã đủ.
 
 ## Bước 6: Tóm tắt
 

package/.claude/skills/dw-retroactive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dw:retroactive
-description: "Retroactively document một feature/task đã được implement trước khi dùng dw. Reverse-engineer từ code + git history, tạo spec.md + tracking.md (v2 format, As-Built flavor)."
+description: "Retroactively document một feature/task đã được implement trước khi dùng dw. Reverse-engineer từ code + git history, tạo task.md (v3 format, As-Built flavor)."
 argument-hint: "[feature-name]"
 allowed-tools:
   - Read
@@ -19,7 +19,7 @@ allowed-tools:
 
 Feature: **$ARGUMENTS**
 
-> Reverse-engineer feature đã tồn tại từ code + git history. Tạo task docs v2 format (`spec.md` + `tracking.md`) với flavor As-Built — để AI và team có context đầy đủ khi làm task liên quan.
+> Reverse-engineer feature đã tồn tại từ code + git history. Tạo task docs v3 format (`task.md`) với flavor As-Built — để AI và team có context đầy đủ khi làm task liên quan.
 
 ---
 
@@ -32,7 +32,7 @@ Feature: **$ARGUMENTS**
 ## Kiểm tra đã có docs chưa
 
 Kiểm tra `{paths.tasks}/$ARGUMENTS/` đã tồn tại chưa:
-- Nếu có `spec.md` hoặc `tracking.md` → hỏi user: "Đã có task docs cho `$ARGUMENTS`. Overwrite hay skip?"
+- Nếu có `task.md` / `spec.md` / `tracking.md` → hỏi user: "Đã có task docs cho `$ARGUMENTS`. Overwrite hay skip?"
 - Nếu chưa → tiếp tục
 
 ---
@@ -80,80 +80,93 @@ Từ framework `.dw/core/THINKING.md`:
 
 ---
 
-## Bước 5: Tạo task docs (v2 format, As-Built flavor)
+## Bước 5: Tạo task docs (v3 format, As-Built flavor)
 
-Tạo thư mục `{paths.tasks}/$ARGUMENTS/` và **2 files** theo template v2 tại `.dw/core/templates/v2/`.
+Tạo thư mục `{paths.tasks}/$ARGUMENTS/` và **1 file** theo template v3 tại `.dw/core/templates/v3/task.md`.
 
-### 5a. spec.md (As-Built)
+Cách nhanh: `dw task new $ARGUMENTS --depth thorough --adr none --target "as-built"` → sau đó edit Section 2-5.
 
-Đọc template `.dw/core/templates/v2/spec.md`, điền:
-
-**Frontmatter:**
+### Điền frontmatter:
 - `task_id: $ARGUMENTS`
-- `created: [today]`
+- `created: [first-commit-date từ git]`
+- `last_updated: [today]`
 - `status: Done` ← đã implement
+- `phase: Maintained (pre-dw)`
 - `owner: [main author từ git shortlog]`
-- `depth: retroactive`
+- `depth: thorough`
 - `related_adr: none`
-- `target_ship: [first-commit-date]`
+- `target_ship: as-built ([first-commit-date])`
+- `schema_version: v3.0`
+- `blockers: none`
 
-**Body sections** (lấp bằng findings retroactive):
+### Body sections (lấp bằng findings retroactive):
 
-- **Intent**: 1-2 paragraphs mô tả feature làm gì (dựa trên code)
-- **Why Now**: "As-built documentation — feature pre-dw adoption" + lý do document hóa
-- **Scope → In Scope**: liệt kê component đã implement dưới dạng ST-1, ST-2... với:
-  - Concrete action = mô tả component đã implement
-  - Acceptance = how it was verified (tests / manual check)
-  - Effort = `as-built`
-- **Scope → Out of Scope**: những gì rõ ràng KHÔNG nằm trong feature (suy từ code boundaries)
-- **Risks & Mitigations**: tech debt, antipatterns, security concerns phát hiện
-- **Success Criteria**: current behavior được kiểm chứng bằng gì (tests, prod metrics nếu biết)
-- **Dependencies**: upstream modules/services + downstream consumers
-- **Known Unknowns**: câu hỏi cần human review (verbal decisions không có trong code)
-- **Acceptance**: đánh dấu `[x]` các items đã done (feature đang chạy prod)
-
-**Thêm note trên đầu Intent**:
+**Section 1 — Snapshot:**
+- Phase: `Maintained (pre-dw)`
+- Status: `Done`
+- Next milestone: `— (maintained as-is)`
+- Owner: maintainer chính
+- Blockers: `none`
+- Last updated: today
+
+**Section 2 — Intent & Scope:**
+
+Thêm note trên đầu Intent:
 ```markdown
 > ⚠ As-Built Documentation — Generated retroactively from code + git history.
 > Verbal context (Slack threads, meetings) có thể thiếu. Cần human review bổ sung.
 ```
 
-Ghi vào `{paths.tasks}/$ARGUMENTS/spec.md`.
+- `### Intent`: 1-2 paragraphs mô tả feature làm gì (dựa trên code).
+- `### Why Now`: "As-built documentation — feature pre-dw adoption" + lý do document hóa.
+- `### Subtasks (in scope)`: liệt kê component đã implement dưới dạng **ST-1, ST-2...** với:
+  - Concrete action = mô tả component đã implement
+  - Acceptance = how it was verified (tests / manual check)
+- `### Out of Scope`: những gì rõ ràng KHÔNG nằm trong feature (suy từ code boundaries).
+- `### Success Criteria`: current behavior được kiểm chứng bằng gì (tests, prod metrics nếu biết).
+- `### Dependencies`: upstream modules/services + downstream consumers.
+- `### Risk Register` (optional): tech debt, antipatterns, security concerns phát hiện.
+- `### Known Unknowns`: câu hỏi cần human review (verbal decisions không có trong code).
 
-### 5b. tracking.md (As-Built)
+**KHÔNG dùng status markers** (`✅` `🟡` `← START HERE`) trong Section 2 — drift prevention per lint.
 
-Đọc template `.dw/core/templates/v2/tracking.md`, điền:
+**Section 3 — Subtask Tracker:**
 
-**Frontmatter:**
-- `task_id: $ARGUMENTS`
-- `started: [first-commit-date từ git]`
-- `last_updated: [today]`
-- `status: Done`
-- `current_phase: Maintained`
-- `blockers: none`
+Map các component đã tìm ở Bước 2 thành table:
+```
+| ST   | Subtask | Status | Date | Notes |
+|------|---------|--------|------|-------|
+| ST-1 | [tên]   | ✅ Done | [first-commit-date] | [commit SHA] |
+```
+
+**Section 4 — Timeline / Changelog:**
+
+Parse git log ra entries:
+```markdown
+### YYYY-MM-DD — [commit subject]
+**Actions taken:** [summary]
+```
 
-**Body sections:**
-
-- **Status Snapshot**: Phase `Done (pre-dw)` · Next milestone `— (maintained as-is)`
-- **Subtask Progress** table: map các component đã tìm ở Bước 2 thành ST-N với status ✅ Done, Date = commit date đầu tiên của component, Notes = commit SHA hoặc file path
-- **Changelog**: parse git log ra thành entries theo ngày. Format:
-  ```
-  ### YYYY-MM-DD — [commit subject]
-  **Actions taken:** [summary]
-  ```
-- **Handoff Notes**: cho next session/agent:
-  - **Read first:** `spec.md` (as-built) + key files từ bước 2
-  - **Current state:** Done, maintained
-  - **Don't do:** [stable contracts không nên thay đổi]
-  - **Watch out:** [tech debt + gotchas]
-- **Friction Journal**: để trống hoặc nhập tech debt đã ghi nhận từ Bước 4
-- **Agent Debate Log**: bỏ qua (không applicable cho retroactive)
-
-Ghi vào `{paths.tasks}/$ARGUMENTS/tracking.md`.
+**Section 5 — Handoff & Friction:**
+
+- **For next session:**
+  - Read first: `task.md` (as-built) + key files từ Bước 2
+  - Current state: Done, maintained
+  - Don't do: [stable contracts không nên thay đổi]
+  - Watch out: [tech debt + gotchas]
+- **Friction Journal:** tech debt đã ghi nhận từ Bước 4
+
+**Section 6 — Annexes:** (none, hoặc `architecture.md` nếu cần diagram dài).
+
+Ghi vào `{paths.tasks}/$ARGUMENTS/task.md`.
 
 ### 5c. Cập nhật ACTIVE.md
 
-Chạy `dw active` (hoặc `writeActiveIndex`) để regenerate team index.
+Chạy `dw active` để regenerate team index.
+
+### 5d. Lint check
+
+Chạy `dw task lint $ARGUMENTS` — verify frontmatter schema valid + no drift markers in Section 2.
 
 ---
 
@@ -167,9 +180,8 @@ Chạy `dw active` (hoặc `writeActiveIndex`) để regenerate team index.
 ║  Git commits       : [N, từ [date] đến [date]]
 ║  Maintainer chính  : [author]
 ╠══════════════════════════════════════════════════════╣
-║  Docs đã tạo (v2 format):
-║    {paths.tasks}/$ARGUMENTS/spec.md      (As-Built)
-║    {paths.tasks}/$ARGUMENTS/tracking.md  (Done, maintained)
+║  Docs đã tạo (v3 format):
+║    {paths.tasks}/$ARGUMENTS/task.md (As-Built, Done)
 ╠══════════════════════════════════════════════════════╣
 ║  Key findings:
 ║  • [Finding 1]
@@ -179,8 +191,8 @@ Chạy `dw active` (hoặc `writeActiveIndex`) để regenerate team index.
 ║  • [Warning nếu có]
 ╠══════════════════════════════════════════════════════╣
 ║  Tiếp theo:
+║  → Snapshot:          dw task show $ARGUMENTS
 ║  → Task liên quan:    /dw:research $ARGUMENTS
-║    (AI đọc spec.md làm foundation)
 ║  → Human review:      điền Known Unknowns + Handoff Notes
 ╚══════════════════════════════════════════════════════╝
 ```
@@ -189,7 +201,7 @@ Chạy `dw active` (hoặc `writeActiveIndex`) để regenerate team index.
 
 ## Lưu ý
 
-- **As-built ≠ forward plan**: spec.md mô tả hiện trạng, không phải kế hoạch tương lai.
+- **As-built ≠ forward plan**: task.md mô tả hiện trạng, không phải kế hoạch tương lai.
 - **Best-effort**: AI chỉ thấy code + git — context ẩn (verbal decisions, Slack threads) có thể thiếu. Human review là bắt buộc cho phần `Known Unknowns`.
-- **v2 format**: Chỉ tạo 2 files (`spec.md` + `tracking.md`). Không dùng lại v1 3-file format (`context + plan + progress`) nữa.
-- **Tools khác vẫn đọc được**: `dw active`, `session-init` hook, `/dw:dashboard` đều hỗ trợ v2 format song song với legacy v1.
+- **v3 format** (ADR-0008): Chỉ tạo 1 file `task.md`. Không tạo legacy v2 (`spec.md` + `tracking.md`) hoặc v1 (`context + plan + progress`) nữa.
+- **Tools khác vẫn đọc được**: `dw active`, stop-check hook, `/dw:dashboard` đều support v3 song song với v2/v1 legacy.

package/.claude/skills/dw-task-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dw:task-init
-description: "Khởi tạo bộ documentation cho task mới. Tạo thư mục và 2 files v2 (spec.md + tracking.md)."
+description: "Khởi tạo bộ documentation cho task mới (v3 1-file task.md theo ADR-0008). Tạo qua `dw task new` hoặc render template thủ công."
 argument-hint: "[task-name]"
 ---
 
@@ -11,61 +11,66 @@ argument-hint: "[task-name]"
 Đọc `.dw/config/dw.config.yml`:
 - `paths.tasks` → thư mục chứa task docs (mặc định: `.dw/tasks`)
 - `workflow.default_depth` → `quick | standard | thorough`
-- `project.language` → ngôn ngữ note thêm (templates hiện tại là vi/en-agnostic)
+- `project.language` → ngôn ngữ note thêm
 
-## Tạo Thư Mục & Files (v2 format)
+## Tạo Task (v3 format — default)
+
+Cách nhanh nhất: chạy CLI
 
 ```
-{paths.tasks}/$ARGUMENTS/
-├── spec.md      # Intent + subtasks + success criteria (stable after approve)
-└── tracking.md  # Progress + changelog + handoff (mutable)
+dw task new $ARGUMENTS --depth {default_depth} [--title "..."] [--adr ADR-NNNN]
 ```
 
-### 1. Tạo spec.md
-
-Đọc template từ `.dw/core/templates/v2/spec.md`, điền vào:
-- `{task-name}` → `$ARGUMENTS`
-- `{YYYY-MM-DD}` (created) → ngày hiện tại
-- `status` → `Draft`
-- `depth` → giá trị `workflow.default_depth` từ config
-- `owner` → để trống (user tự điền)
-- `related_adr` → `none`
-- `target_ship` → `none`
-
-Ghi vào `{paths.tasks}/$ARGUMENTS/spec.md`.
+Lệnh này:
+- Đọc template `.dw/core/templates/v3/task.md`
+- Điền frontmatter (task_id, created/last_updated = today, status: Draft, depth, owner, schema_version: v3.0)
+- Tạo `{paths.tasks}/$ARGUMENTS/task.md`
+- Log telemetry event `task.new`
 
-### 2. Tạo tracking.md
+### Nếu CLI không khả dụng — manual fallback
 
-Đọc template từ `.dw/core/templates/v2/tracking.md`, điền vào:
+Đọc template từ `.dw/core/templates/v3/task.md`, điền vào:
 - `{task-name}` → `$ARGUMENTS`
-- `{YYYY-MM-DD}` (started & last_updated) → ngày hiện tại
-- `status` → `Not Started`
-- `current_phase` → `Init`
-- `blockers` → `none`
+- `{YYYY-MM-DD}` → ngày hiện tại (3 chỗ: created, last_updated, optional changelog entry)
+- `status: Draft` → giữ nguyên
+- `depth` → giá trị `workflow.default_depth` từ config
+- `owner` → từ env DW_OWNER hoặc để trống
+- `related_adr: {ADR-NNNN | none}` → `none` (hoặc ADR nếu task liên quan)
+- `target_ship: {milestone or TBD}` → `TBD`
+- `# Timeline: {Task Title}` → tiêu đề task
 
-Ghi vào `{paths.tasks}/$ARGUMENTS/tracking.md`.
+Ghi vào `{paths.tasks}/$ARGUMENTS/task.md` (chỉ 1 file).
 
-### 3. Cập nhật ACTIVE.md
+## Cập Nhật ACTIVE.md
 
-Sau khi tạo xong 2 files, chạy `dw active` (hoặc invoke `writeActiveIndex`) để regenerate `{paths.tasks}/ACTIVE.md` — team index sẽ thấy task mới.
+Chạy `dw active` để regenerate `{paths.tasks}/ACTIVE.md` — team index sẽ thấy task mới.
 
 ## Sau Khi Tạo
 
 Hiển thị cho user:
 
-1. Danh sách files đã tạo:
-   - `{paths.tasks}/$ARGUMENTS/spec.md`
-   - `{paths.tasks}/$ARGUMENTS/tracking.md`
+1. File đã tạo: `{paths.tasks}/$ARGUMENTS/task.md`
 
 2. Workflow tiếp theo theo `workflow.default_depth`:
    - **quick**: "Code ngay hoặc `/dw:research $ARGUMENTS` nếu cần khảo sát."
    - **standard**: "`/dw:research $ARGUMENTS` → `/dw:plan $ARGUMENTS` → approve → `/dw:execute $ARGUMENTS`"
    - **thorough**: "`/dw:requirements $ARGUMENTS` → `/dw:research $ARGUMENTS` → `/dw:estimate $ARGUMENTS` → `/dw:plan $ARGUMENTS`"
 
-3. Nếu team có BA role: "BA có thể chạy `/dw:requirements $ARGUMENTS` trước để chuẩn bị yêu cầu."
+3. Useful commands:
+   - `dw task show $ARGUMENTS` — terminal snapshot
+   - `dw task lint $ARGUMENTS` — drift check
+   - `dw active` — team index
+
+## v3 Format Rules (per ADR-0008)
+
+- **Single source of truth:** `task.md` chứa Snapshot + Intent + Subtask Tracker + Changelog + Handoff. Không có file thứ 2 cho status.
+- **Section 2 (Intent & Scope) frozen sau approve** — không status markers (`✅🟡🔴`), không dates inline. Status lives only in Section 3.
+- **Section 3 (Subtask Tracker) = single source of truth** cho subtask status (⬜🟡✅🔴⏸).
+- **Section 4 auto-rotate** > 400 dòng → `timeline-history.md` (qua stop-check hook).
+- **Appendages allowed**: `baseline.md`, `experiment-{id}.md`, `debate-r{N}.md`, `timeline-history.md`. Tránh tên generic (`notes.md`, `extra.md` — lint warn).
+- **Lint default strict**: `dw task lint` chạy schema validate + drift check.
 
-## Lưu ý v2 format
+## Legacy Format Support
 
-- `spec.md` ổn định sau khi approve — subtasks + success criteria không thay đổi mà không có lý do.
-- `tracking.md` mutable — cập nhật mỗi session (Subtask Progress table, Changelog, Friction Journal).
-- Legacy 3-file format (`context + plan + progress`) vẫn được đọc bởi các skill khác để backward compat, nhưng **không tạo mới** cho task mới.
+- **v2 (deprecated)**: 2-file `spec.md` + `tracking.md`. Đọc-only (backward compat); migrate qua `dw task migrate $ARGUMENTS` (dry-run trước).
+- **v1 (legacy)**: 3-file `context.md` + `plan.md` + `progress.md`. Đọc-only; không tạo mới.