dw-kit 1.8.0-rc.1 → 1.9.0-rc.1

package/.claude/rules/dw.md

@@ -101,6 +101,8 @@ Core workflow: `/dw:flow` · `/dw:task-init` · `/dw:research` · `/dw:plan` ·
 
 `/dw:plan` includes **Quick Debate** (red/blue self-critique): default ON for `thorough`, auto-trigger on high-stakes signals for `standard`, off for `quick`. Override via `--debate` / `--no-debate` / `--debate-deep`.
 
+Goals (ADR-0010/0016): `/dw:goal` (outcome-driven pursuit loop — drive Goal tới KR, leo thang tư duy khi kẹt; `--auto` long-horizon) · `/dw:goal-sync` (reactive sync khi human pivot)
+
 Decisions: `/dw:decision [title]` — create ADR
 
 Dev: `/dw:debug` · `/dw:review` · `/dw:thinking` · `/dw:prompt` · `/dw:docs-update`

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

@@ -0,0 +1,206 @@
+---
+name: dw:goal
+description: "Drive một Goal tới các Key Results bằng vòng lặp pursuit hướng kết quả. Đo gap → hành động → đo lại; khi một cách thất bại thì NÂNG CẤP tư duy (leo bậc) thay vì lặp lại. Dừng theo termination contract. Khác dw:goal-sync (chỉ đồng bộ) và dw:flow (drive 1 task)."
+argument-hint: "[goal-id] [--auto] [--max-iter N]"
+---
+
+# dw:goal — Vòng Lặp Đeo Bám Mục Tiêu (Outcome-Driven Pursuit)
+
+Goal: **$ARGUMENTS** (để trống = goal liên quan task đang làm via `parent_goal_id`)
+
+> Triết lý (ADR-0016): **quan tâm tới KẾT QUẢ, không phải effort.** Plan là thứ vứt đi
+> được — nếu plan fail thì Goal vẫn sống, ta nghĩ plan mới. Cần thì **xoáy nhiều vòng**,
+> và mỗi lần fail phải **nâng cấp tư duy** (leo bậc thang) chứ không lặp lại cách cũ.
+> Success = KR đo được chạm target, KHÔNG phải "đã làm xong task".
+
+## Vị trí trong hệ skill (không trùng lặp)
+
+```
+dw:goal      → drive 1 GOAL tới các KR, qua NHIỀU task & NHIỀU lần thử   ← skill này
+  ├─ dw:goal-sync → primitive cho pha OBSERVE (đọc goal + tail events)
+  ├─ dw:flow      → drive 1 TASK end-to-end tới Done (giữ human gate riêng)
+  ├─ dw:plan / dw:thinking → công cụ cho pha ORIENT + ladder L1/L2
+  └─ dw goal *  CLI → tầng dữ liệu (đọc KR, update progress, link task, events)
+```
+
+`dw:goal` **điều phối** các mảnh trên thành một loop hướng kết quả. Nó KHÔNG tự
+implement task (giao cho `dw:flow`), KHÔNG tự plan từ đầu (gọi `dw:plan`).
+
+## Khi nào dùng
+
+- Có một Goal (`G-{slug}`) với Key Results đã định nghĩa, muốn AI **chủ động đẩy** tới đích.
+- Goal cần nhiều task / nhiều lần thử mới đạt — không phải 1 task đơn lẻ (dùng `dw:flow`).
+- Bị kẹt ở một KR và muốn AI **thử cách tiếp cận khác** một cách có hệ thống.
+
+## Bước 0 — Khởi động & parse args
+
+Parse `$ARGUMENTS`:
+- `goal-id` (`G-{slug}`) — validate regex. Nếu trống → derive từ task đang làm
+  (`parent_goal_id` trong `.dw/tasks/{task}/task.md`, giống `dw:goal-sync` Bước 1).
+  Không có → dừng, gợi ý `dw goal portfolio` để chọn.
+- Tự chủ (xem "Thang tự chủ"): _(không cờ)_ = **A0 supervised** (mặc định, dừng cuối mỗi vòng);
+  `--auto` = **A1 checkpoint** (dừng ở ranh giới mỗi KR đạt); `--auto=full` = **A2 full** (chỉ hard-stop).
+- `--max-iter N` — trần số vòng cho A1/A2 (mặc định **5**). A0 không cần.
+
+Đọc config `.dw/config/dw.config.yml` (nếu cần): `quality.test_command` để đo KR
+auto-measurable; `team.roles` (có `techlead` → strategic pivot cần TL).
+
+Đọc journal nếu có: `.dw/goals/{goal-id}/goal-loop.md` — phục hồi state vòng trước
+(iteration #, ladder rung mỗi KR, bài học Reflexion). Không có = bắt đầu từ iteration 1, L0.
+
+## Vòng lặp Pursuit (mỗi vòng = một "vòng xoáy")
+
+Lặp các pha **OBSERVE → ORIENT → DECIDE → ACT → VERIFY → REFLECT**, rồi xét EXIT.
+
+### 1. OBSERVE — đo trạng thái thật
+
+Tái dùng logic `dw:goal-sync`:
+
+```bash
+dw goal show $GOAL          # ANSI snapshot: status, version, KR table
+dw goal summary $GOAL       # strategic context ngắn
+grep "\"goal_id\":\"$GOAL\"" .dw/events-global.jsonl | tail -30   # drift gần đây
+```
+
+Đọc Section 3 (KR table) → với mỗi KR lấy `current` vs `target`. Tính **gap** = target − current.
+Đọc Section 3 (Linked Tasks) → trạng thái các task đang góp cho goal.
+
+Phân loại mỗi KR (3 loại — quyết định nước đi đúng):
+- **Auto-measurable** (đo được bằng lệnh): test count, coverage %, smoke pass/fail, file tồn tại, tag git… → đo trực tiếp.
+- **Human-attested** (định tính: "adoption ≥5 teams", "UX mượt"…) → KHÔNG bịa số. Khi cần cập nhật loại này → **STOP hỏi human attest**.
+- **Wait-gated** (chặn bởi *thời gian*, không bởi tư duy: "≥30 ngày telemetry baseline", "chờ CI/cron chạy", "chờ deadline"…) → KR chỉ tiến khi thời gian trôi. **TUYỆT ĐỐI không leo ladder** (leo bậc = thrash, không cách nghĩ nào làm thời gian trôi nhanh hơn). Nước đi đúng: refresh `current` theo lượng đã trôi nếu cần, rồi **⏳ pause với ETA resume**.
+
+### 2. ORIENT — phân tích gap (nạp THINKING.md)
+
+- KR nào gap lớn nhất / đang block các KR khác? → chọn **KR mục tiêu** cho vòng này.
+- **Hỏi trước khi leo ladder: KR này chặn bởi *tư duy* hay bởi *thời gian*?** Nếu là wait-gated → KHÔNG leo, chuyển sang ⏳ pause. Chỉ leo ladder khi cái chặn là approach/tư duy.
+- Áp dụng `.claude/skills/dw-thinking/THINKING.md`: giả định nào đang chặn? dependency? failure mode? `current` có bị **stale** (set lâu rồi, chưa refresh) không?
+- Đọc bài học Reflexion từ journal: cách nào đã thử & thất bại cho KR này?
+- Kết luận trạng thái goal: `on-track | stuck | infeasible | achieved`. (wait-gated mà đúng ETA = **on-track**, KHÔNG phải stuck.)
+
+### 3. DECIDE — chọn nước đi ở ĐÚNG bậc thang tư duy
+
+Nước đi điển hình: spawn/resume một task nhắm thẳng KR mục tiêu, hoặc một hành động nhỏ trực tiếp, hoặc reframe. **Chọn strategy theo bậc ladder hiện tại của KR đó** (xem Thang Nâng Cấp Tư Duy bên dưới).
+
+### 4. ACT — thực thi
+
+- **Task-level work** → giao cho `/dw:flow <task>` (flow giữ human gate của nó: GATE C plan, GATE D changes). Tạo task mới bằng `dw task new` + `dw goal link $GOAL <task>` nếu chưa có.
+- **Cập nhật KR**: sau khi có kết quả đo được, cập nhật `current` trong Section 3 (qua edit goal.md hoặc lệnh `dw goal` tương ứng). Emit event tiến độ.
+- **Agent OS**: nếu môi trường multi-agent, claim trước khi ghi (`dw agent claim`).
+
+### 5. VERIFY — ĐO LẠI KR mục tiêu (bắt buộc)
+
+Chạy lại phép đo của KR (test command, đếm, kiểm tra artifact…). Ghi **delta** vào journal + Section 4 timeline.
+
+> Đây là điểm cốt lõi: **thành công tính bằng delta đo được, không phải bằng việc đã làm.**
+> Nếu KR human-attested → hỏi human, không tự đánh ✅.
+
+### 6. REFLECT — học & quyết định bậc kế (Reflexion)
+
+- KR **tiến về target** → chốt; chuyển KR kế; có thể **hạ về L0** cho KR mới.
+- KR **không nhúc nhích / đi sai** → ghi *vì sao* thành một dòng bài học trong journal, rồi **leo 1 bậc ladder** cho vòng sau.
+
+### 7. EXIT — xét termination contract (xem dưới). Nếu chưa exit → vòng kế.
+
+---
+
+## Thang Nâng Cấp Tư Duy ("nâng cấp tư duy") — cơ chế lõi
+
+Vòng fail thì **PHẢI leo bậc**; **KHÔNG** chạy lại cùng một bậc. Vòng thành công có thể hạ về L0 cho KR kế.
+
+| Bậc | Chiến lược | Tái dùng |
+|-----|-----------|----------|
+| **L0** | Thực thi trực tiếp — làm việc task hiển nhiên | `dw:execute` / inline |
+| **L1** | Plan có cấu trúc — áp THINKING.md, tạo plan thật | `dw:plan`, `dw:thinking` |
+| **L2** | Debate đối kháng — red/blue mổ approach, tìm giả định ẩn đang chặn | `dw:plan` Quick Debate (Mode A 2-pass mặc định; Mode B subagents song song nếu có) |
+| **L3** | Reframe — nghi ngờ *cách tiếp cận*: có đường orthogonal? chia nhỏ khác? chạy spike/experiment de-risk? | annex `experiment-{id}.md` |
+| **L4** | Nghi ngờ *chính Goal* — KR có đo đúng thứ cần? target khả thi? → đề xuất `Pivoted` / sửa KR | `dw goal bump --reason` |
+| **L5** | Escalate human — DỪNG, trình diagnosis + options, trả quyền | AskUser / GATE |
+
+Thang này biến "nâng cấp tư duy" mơ hồ thành cơ chế cụ thể, kiểm toán được — chống thrash (lặp cách hỏng) và chống spin vô tiến triển.
+
+---
+
+## Termination Contract (điều kiện dừng tường minh)
+
+- ✅ **Achieved** — mọi KR in-scope chạm target → `dw goal` status → `Achieved`, viết summary, DỪNG.
+- 🔴 **Infeasible** — đã tới L4 mà không còn đường → đề xuất `Abandoned`/`Pivoted`, DỪNG chờ human.
+- ⏸ **Budget-exhausted** — chạm `--max-iter` HOẶC hết ngân sách time/turn → **wrap-up nhẹ nhàng** (kiểu Codex): ghi tiến độ + việc còn lại vào Section 5 / journal, lưu state, DỪNG. **Resumable** session sau.
+- ⏳ **Wait-gated pause** — KR mục tiêu là wait-gated (chặn bởi thời gian), không còn KR actionable nào khác → DỪNG với **ETA resume cụ thể**. KHÔNG leo ladder, KHÔNG tạo task lấp chỗ.
+- 🚧 **No-progress guard** — N vòng liên tiếp (mặc định **2**) KR-delta = 0 *và* không có diagnosis mới → ép leo bậc ngay; nếu đã ở L5 → DỪNG + escalate. (Chống loop vô hạn, mượn từ Codex loop-suppression.)
+- 🛑 **Irreversible-action boundary** — trước MỌI hành động khó đảo (push / release / merge / gửi ra ngoài) → **LUÔN DỪNG chờ human** (ADR-0009). KHÔNG bao giờ tự push.
+- 👤 **Human interrupt** — pause goal, lưu state.
+
+## Thang tự chủ (autonomy tăng dần — "tự động hoá dần dần")
+
+Tự chủ là một **núm xoay 3 nấc**, không phải bật/tắt. Bắt đầu thấp, **nâng dần khi đã tin** loop chạy đúng trên goal/loại KR cụ thể. Mỗi nấc chỉ NỚI điểm dừng định kỳ — **các hard-stop của Termination Contract luôn áp dụng ở mọi nấc**.
+
+| Nấc | Cờ | Dừng định kỳ ở đâu | Khi nào dùng |
+|-----|----|--------------------|--------------|
+| **A0 · supervised** (MẶC ĐỊNH) | _(không cờ)_ | Cuối **mỗi vòng** | Goal mới / KR rủi ro / chưa tin loop |
+| **A1 · checkpoint** | `--auto` | Cuối mỗi **KR đạt target** (ranh giới KR), không dừng giữa các vòng cùng một KR | Đã tin loop với KR auto-measurable; muốn nó tự xoáy 1 KR tới đích rồi báo |
+| **A2 · full** | `--auto=full` | Không dừng định kỳ — chỉ hard-stop | Goal rõ ràng, KR auto-measurable, đã chạy A1 trơn tru ít nhất 1 lần |
+
+`--max-iter N` (mặc định 5) áp cho A1/A2. **`--auto` mặc định = A1 (checkpoint)** — nấc giữa an toàn; phải gõ rõ `--auto=full` mới lên A2. Đây chính là "tự động hoá dần dần": default-auto là nấc thận trọng, không nhảy thẳng full.
+
+**Bất biến ở mọi nấc:**
+- Hard-stop của Termination Contract (irreversible boundary, no-progress guard, ladder L5, wait-gated) **không bao giờ bị nới**.
+- Việc task vẫn đi qua human gate của `dw:flow` (GATE C/D). Loop chỉ tự chủ ở tầng *chọn KR / leo bậc / đo đạc*.
+- Càng lên nấc cao, journal `goal-loop.md` càng phải ghi đầy đủ (để human audit lại chuỗi quyết định đã tự chạy).
+
+**Lộ trình tự động hoá sâu hơn (P2/P3, telemetry-gated):** đo KR auto-measurable tự động qua CLI helper (`dw goal gap`), rồi tới adapter chạy `test_command`/đếm artifact và tự ghi `current` — giảm dần phần human phải đo tay. Xem ADR-0016 Phasing.
+
+## State bền vững giữa các session — `goal-loop.md`
+
+Khi loop kéo dài nhiều session HOẶC chạy `--auto`, ghi annex `.dw/goals/{goal-id}/goal-loop.md`
+(appendage hợp lệ theo goal.md Section 6). Cấu trúc gợi ý:
+
+```markdown
+# Goal Loop Journal — {goal-id}
+
+## Iteration {N} — {YYYY-MM-DD HH:MM} — mode: {supervised|auto}
+- Target KR: KR-00X (gap: {target} − {current})
+- Ladder rung: L{n}
+- Move: {nước đi đã làm}
+- Verify delta: {KR-00X: {old} → {new}}  | hoặc: no change
+- Lesson (nếu fail): {vì sao không tiến + sẽ thử gì khác}
+
+## Reflexion memory (per-KR — tránh lặp cách hỏng)
+- KR-001: [L0 fail: lý do] → [L1 fail: lý do] → [đang ở L2]
+- KR-002: ✅ đạt ở L0
+
+## Budget
+- Iterations: {used}/{max}   | Stopped-by: {achieved|budget|no-progress|...}
+```
+
+Session mới đọc journal này để **resume** đúng bậc + nhớ bài học. Đây là bản file-based, vendor-neutral của "thread-level goal persistence" mà Codex `/goal` làm.
+
+## Vendor neutrality (W-6 — ADR-0010)
+
+Skill là quy trình markdown bất kỳ agent (Claude/Codex/Gemini/CI) đọc được; mọi state nằm trong file (`goal.md`, `events-global.jsonl`, `goal-loop.md`). Bậc cần subagent (L2 Mode B, exploration song song) **degrade nhẹ nhàng** về single-agent 2-pass cho agent không có subagent. Loop chỉ dùng Tier-1 file-watch — KHÔNG phụ thuộc SSE/HTTP.
+
+## Output (mỗi vòng — supervised; hoặc cuối run — auto)
+
+```
+🎯 Goal $GOAL — $TITLE   (iteration N, mode: supervised|auto)
+   Target KR vòng này : KR-00X  (gap: target − current)
+   Ladder rung        : L{n}  ({tên strategy})
+   Move               : {tóm tắt nước đi}
+   Verify             : KR-00X {old} → {new}   [✅ moved | ⚠ no change]
+   Reflexion          : {bài học nếu fail}
+   ──
+   Trạng thái goal    : on-track | stuck | infeasible | achieved
+   Next               : {KR/nước đi vòng sau}  hoặc  {lý do DỪNG + options}
+```
+
+Supervised → kết bằng: "Vòng N xong. `continue` / `redirect: …` / `stop`?"
+
+## Liên quan
+
+- `dw:goal-sync` — primitive pha OBSERVE (đồng bộ phản ứng khi human pivot)
+- `dw:flow` — orchestrator 1 task (pha ACT giao cho nó)
+- `dw:plan` · `dw:thinking` — công cụ pha ORIENT + ladder L1/L2
+- `dw goal show|summary|portfolio|link|bump` — tầng dữ liệu/state
+- ADR-0016 (`.dw/decisions/0016-goal-pursuit-loop-skill.md`) — full thiết kế loop + ladder + contract
+- ADR-0010 — Goals Layer (KR schema, events, vendor neutrality W-6)
+- ADR-0009 — Agent OS (human gate + cooperative claim)

package/.claude/skills/dw-goal-sync/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: dw:goal-sync
+description: "Đồng bộ trạng thái Goal hiện tại từ .dw/events-global.jsonl. Đọc summary + linked tasks + recent events để re-plan khi human pivot mục tiêu giữa session."
+argument-hint: "[goal-id]"
+---
+
+# Đồng Bộ Trạng Thái Goal
+
+Goal: **$ARGUMENTS** (để trống = goal liên quan task đang làm via `parent_goal_id`)
+
+## Khi nào dùng
+
+- Khi human report là goal vừa pivot (status change, summary edit, KR added)
+- Khi bắt đầu session mới và task đang làm có `parent_goal_id` set
+- Khi `dw goal portfolio` cho thấy goal liên quan có `goal_version` cao hơn version đã đọc trước
+- Trong dài session, định kỳ resync để bắt event human chỉnh trên browser editor
+
+## Bước 1 — Resolve goal_id
+
+Nếu user truyền `$ARGUMENTS`:
+- Validate ID format `G-{slug}` qua regex
+- Dùng trực tiếp
+
+Nếu không, derive từ task đang làm:
+```bash
+# Get current task (most recent v3 task in .dw/tasks/)
+TASK=$(ls -t .dw/tasks/*/task.md 2>/dev/null | head -1 | awk -F/ '{print $(NF-1)}')
+# Extract parent_goal_id from frontmatter
+GOAL=$(grep -E '^parent_goal_id:' ".dw/tasks/$TASK/task.md" | sed 's/parent_goal_id:\s*//;s/["'"'"']//g')
+```
+
+Nếu `parent_goal_id` = `none` hoặc empty → không có goal để sync, dừng.
+
+## Bước 2 — Snapshot hiện tại
+
+```bash
+dw goal show $GOAL                          # ANSI snapshot
+dw goal summary $GOAL                       # 1000-char summary
+```
+
+Đọc cấu trúc:
+- `status` (Draft / Active / Achieved / Abandoned / Pivoted) — nếu Pivoted hoặc Abandoned, cần re-plan
+- `goal_version` — track để detect changes future
+- `summary` — strategic context
+- `cycle` — temporal grouping (Q2 2026, etc.)
+- `target_date` — deadline
+- Linked tasks — cross-task picture
+
+## Bước 3 — Tail events log (Tier 1)
+
+Đọc events gần đây cho goal này từ `.dw/events-global.jsonl`:
+
+```bash
+# Filter events for this goal (last 50 lines)
+grep "\"goal_id\":\"$GOAL\"" .dw/events-global.jsonl | tail -50
+```
+
+Hoặc programmatic via `src/lib/goal-watch.mjs`:
+
+```javascript
+import { iterateGoalEvents } from 'dw-kit/lib/goal-watch.mjs';
+
+const recentEvents = [];
+for await (const ev of iterateGoalEvents({ goalId: $GOAL, backfill: 50 })) {
+  recentEvents.push(ev);
+  if (recentEvents.length >= 50) break;
+}
+```
+
+Event types để chú ý:
+- `goal_status_changed` — human pivoted; re-read goal.md immediately
+- `goal_pivoted` — version bump with reason; check `summary` field for why
+- `goal_field_updated` (field: `summary` | `icon` | `cycle`) — context drift
+- `goal_kr_progress` — KR moved
+- `goal_task_linked` / `goal_task_unlinked` — scope changed
+
+## Bước 4 — Detect drift vs last-known version
+
+So sánh `goal_version` từ Bước 2 với version agent ghi nhớ trước đó (nếu có).
+
+Nếu version tăng:
+1. **Re-read** `.dw/goals/$GOAL/goal.md` đầy đủ Section 1-5
+2. **Re-check** task.md đang làm — `parent_goal_id` còn match không?
+3. **Re-plan** subtasks nếu strategic intent thay đổi
+4. Nếu Pivoted/Abandoned status — STOP execution, ask human
+
+Nếu version không đổi nhưng có `goal_field_updated` events:
+- Summary changed → soft refresh strategic context only
+- Cycle/icon changed → cosmetic, không re-plan
+
+## Bước 5 — Subscribe (long-running session)
+
+Đối với session dài, set up watcher để auto-detect future changes:
+
+```javascript
+import { watchGoal } from 'dw-kit/lib/goal-watch.mjs';
+
+const unsubscribe = watchGoal('$GOAL', (event) => {
+  if (event.event === 'goal_status_changed' || event.event === 'goal_pivoted') {
+    // Stop current work, re-read goal, notify human
+  }
+});
+```
+
+**Vendor neutrality (W-6):** Tier 1 fs.watch trên `events-global.jsonl` là cách DUY NHẤT để non-Claude agents (Codex, Gemini, CI) react. Đừng dùng SSE `/events.sse` cho agents — chỉ browser UI dùng SSE.
+
+**Rotation:** `.dw/events-global.jsonl` rotate sang `.dw/events-global-YYYYMM.jsonl` khi đạt 500KB/5000 lines (C-4). Historical events trong archive files; watcher auto-detect new lines trong current file.
+
+## Output
+
+Brief summary cho human:
+
+```
+🎯 Goal $GOAL — $TITLE
+   Status: $STATUS (v$VERSION, last_updated $DATE)
+   Recent activity: N events trong last 50 lines
+   - YYYY-MM-DDTHH:MM:SSZ goal_status_changed: $FROM → $TO
+   - YYYY-MM-DDTHH:MM:SSZ goal_field_updated summary
+   ...
+   
+[Drift analysis if version bumped vs last-known]
+[Suggested next action if Pivoted/Abandoned]
+```
+
+## Liên quan
+
+- `dw goal show $GOAL` — full ANSI snapshot
+- `dw goal portfolio` — all goals overview
+- `dw goal lint $GOAL` — drift detection vs goals-index.json
+- `.dw/research/agentchattr-fit-analysis.md` — summary primitive borrow context
+- ADR-0010 § Round 2 — full Goals Layer architecture

package/.claude/templates/agent-report.md

@@ -1,35 +1,35 @@
----
-date: [ISO timestamp — e.g. 2026-04-02T14:30:00]
-from: [agent-role — researcher | planner | developer | reviewer | debugger]
-to: [agent-role — planner | developer | user]
-task: [task-name]
-status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
----
-
-## Summary
-
-[1-3 câu tóm tắt kết quả / findings]
-
-## Details
-
-[Chi tiết findings, decisions, hoặc implementation notes]
-
-## Concerns (nếu DONE_WITH_CONCERNS)
-
-- [Concern 1]
-- [Concern 2]
-
-## Blockers (nếu BLOCKED)
-
-- **Blocker**: [Mô tả vấn đề]
-- **Owner**: [Ai cần resolve]
-- **Unblock by**: [Action cần làm]
-
-## Needs (nếu NEEDS_CONTEXT)
-
-- [ ] [Thông tin cần thêm]
-- [ ] [Quyết định cần từ user/TL]
-
-## Next Steps
-
-- [Bước tiếp theo đề xuất]
+---
+date: [ISO timestamp — e.g. 2026-04-02T14:30:00]
+from: [agent-role — researcher | planner | developer | reviewer | debugger]
+to: [agent-role — planner | developer | user]
+task: [task-name]
+status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+---
+
+## Summary
+
+[1-3 câu tóm tắt kết quả / findings]
+
+## Details
+
+[Chi tiết findings, decisions, hoặc implementation notes]
+
+## Concerns (nếu DONE_WITH_CONCERNS)
+
+- [Concern 1]
+- [Concern 2]
+
+## Blockers (nếu BLOCKED)
+
+- **Blocker**: [Mô tả vấn đề]
+- **Owner**: [Ai cần resolve]
+- **Unblock by**: [Action cần làm]
+
+## Needs (nếu NEEDS_CONTEXT)
+
+- [ ] [Thông tin cần thêm]
+- [ ] [Quyết định cần từ user/TL]
+
+## Next Steps
+
+- [Bước tiếp theo đề xuất]

package/.dw/config/agents.yml

@@ -10,6 +10,14 @@
 
 schema_version: agents@v1
 
+# ADR-0015 KR-D: multi-agent live debate roster. Trigger via voice
+# "debate <topic>" / "tranh luận <topic>". Server spawns these agents
+# in parallel; replies stream to browser via SSE. Each entry MUST also
+# exist under `agents:` below.
+voice_debate:
+  roster: [claude, codex]
+  timeout_ms: 30000
+
 agents:
   # Anthropic Claude Code — non-interactive print mode.
   # Install: https://docs.claude.com/en/docs/claude-code

package/.dw/core/AGENTS.md

@@ -1,53 +1,53 @@
-# Agent Communication Protocol — dw-kit v1.2
-
-## Mục Đích
-
-Khi một task lớn cần nhiều "vai" khác nhau (researcher → planner → developer), việc ghi lại kết quả từng bước giúp:
-- Team members (người hoặc agent) biết chính xác task đang ở đâu
-- Audit trail rõ ràng: ai quyết định gì, lúc nào
-- Session tiếp theo có thể tiếp tục mà không cần hỏi lại
-
-## Convention: Reports Directory
-
-```
-.dw/tasks/[task-name]/
-├── [name]-context.md      # Research findings
-├── [name]-plan.md         # Implementation plan
-├── [name]-progress.md     # Progress tracking
-└── reports/               # Agent communication (v1.2+)
-    ├── 260402-1430-from-researcher-to-planner-analysis.md
-    ├── 260402-1500-from-planner-to-developer-subtask-1.md
-    └── 260402-1600-from-developer-to-reviewer-pr-ready.md
-```
-
-**Filename format**: `[YYMMDD-HHMM]-from-[role]-to-[role]-[description].md`
-
-## Status Codes
-
-| Status | Nghĩa |
-|--------|-------|
-| `DONE` | Hoàn thành, output sẵn sàng để dùng |
-| `DONE_WITH_CONCERNS` | Xong nhưng có điểm đáng chú ý / cần review |
-| `BLOCKED` | Bị chặn, cần action từ bên ngoài để tiếp tục |
-| `NEEDS_CONTEXT` | Thiếu thông tin, cần human confirm |
-
-## Khi Nào Tạo Report
-
-- Sau khi `dw-research` hoàn thành → report `from-researcher-to-planner`
-- Sau khi `dw-plan` approved → report `from-planner-to-developer`
-- Khi phát hiện blocker trong execute → report `from-developer-to-user` với `BLOCKED`
-- Sau khi review xong → report `from-reviewer-to-developer`
-
-## Khi Nào KHÔNG Cần Report
-
-- Tasks `quick` depth (≤2 files, hotfix) → không cần overhead này
-- Solo dev, single session → progress.md đã đủ
-- Thông tin đã có trong context.md / plan.md → không duplicate
-
-## Template
-
-Dùng `.claude/templates/agent-report.md`
-
-## Lưu Ý Quan Trọng
-
-Reports là **cho con người đọc**, không phải protocol cho AI. Claude Code đã communicate qua conversation context. Reports giúp team members theo dõi task cross-session, không phải AI-to-AI messaging.
+# Agent Communication Protocol — dw-kit v1.2
+
+## Mục Đích
+
+Khi một task lớn cần nhiều "vai" khác nhau (researcher → planner → developer), việc ghi lại kết quả từng bước giúp:
+- Team members (người hoặc agent) biết chính xác task đang ở đâu
+- Audit trail rõ ràng: ai quyết định gì, lúc nào
+- Session tiếp theo có thể tiếp tục mà không cần hỏi lại
+
+## Convention: Reports Directory
+
+```
+.dw/tasks/[task-name]/
+├── [name]-context.md      # Research findings
+├── [name]-plan.md         # Implementation plan
+├── [name]-progress.md     # Progress tracking
+└── reports/               # Agent communication (v1.2+)
+    ├── 260402-1430-from-researcher-to-planner-analysis.md
+    ├── 260402-1500-from-planner-to-developer-subtask-1.md
+    └── 260402-1600-from-developer-to-reviewer-pr-ready.md
+```
+
+**Filename format**: `[YYMMDD-HHMM]-from-[role]-to-[role]-[description].md`
+
+## Status Codes
+
+| Status | Nghĩa |
+|--------|-------|
+| `DONE` | Hoàn thành, output sẵn sàng để dùng |
+| `DONE_WITH_CONCERNS` | Xong nhưng có điểm đáng chú ý / cần review |
+| `BLOCKED` | Bị chặn, cần action từ bên ngoài để tiếp tục |
+| `NEEDS_CONTEXT` | Thiếu thông tin, cần human confirm |
+
+## Khi Nào Tạo Report
+
+- Sau khi `dw-research` hoàn thành → report `from-researcher-to-planner`
+- Sau khi `dw-plan` approved → report `from-planner-to-developer`
+- Khi phát hiện blocker trong execute → report `from-developer-to-user` với `BLOCKED`
+- Sau khi review xong → report `from-reviewer-to-developer`
+
+## Khi Nào KHÔNG Cần Report
+
+- Tasks `quick` depth (≤2 files, hotfix) → không cần overhead này
+- Solo dev, single session → progress.md đã đủ
+- Thông tin đã có trong context.md / plan.md → không duplicate
+
+## Template
+
+Dùng `.claude/templates/agent-report.md`
+
+## Lưu Ý Quan Trọng
+
+Reports là **cho con người đọc**, không phải protocol cho AI. Claude Code đã communicate qua conversation context. Reports giúp team members theo dõi task cross-session, không phải AI-to-AI messaging.

package/.dw/core/schemas/events/created.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dv-workflow/dv-workflow/schemas/events/created.schema.json",
+  "title": "DW Event: created",
+  "description": "Category: session-lifecycle. See docs/specs/dw-event-schema-v1.0.md §5 for narrative.",
+  "type": "object",
+  "properties": {
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$",
+      "description": "ISO 8601 UTC timestamp (envelope, set by writer)"
+    },
+    "event": {
+      "type": "string",
+      "const": "created",
+      "description": "Event name (envelope)"
+    },
+    "agent": {
+      "type": "string"
+    },
+    "goal": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "ts",
+    "event",
+    "agent",
+    "goal"
+  ],
+  "additionalProperties": true
+}

package/.dw/core/schemas/events/debate_agent_failed.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dv-workflow/dv-workflow/schemas/events/debate_agent_failed.schema.json",
+  "title": "DW Event: debate_agent_failed",
+  "description": "Category: debate. See docs/specs/dw-event-schema-v1.0.md §5 for narrative.",
+  "type": "object",
+  "properties": {
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$",
+      "description": "ISO 8601 UTC timestamp (envelope, set by writer)"
+    },
+    "event": {
+      "type": "string",
+      "const": "debate_agent_failed",
+      "description": "Event name (envelope)"
+    },
+    "debate_id": {
+      "type": "string"
+    },
+    "agent": {
+      "type": "string"
+    },
+    "error": {
+      "type": "string"
+    },
+    "exit_code": {
+      "type": "integer"
+    },
+    "ms": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "ts",
+    "event",
+    "debate_id",
+    "agent"
+  ],
+  "additionalProperties": true
+}

package/.dw/core/schemas/events/debate_agent_replied.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dv-workflow/dv-workflow/schemas/events/debate_agent_replied.schema.json",
+  "title": "DW Event: debate_agent_replied",
+  "description": "Category: debate. See docs/specs/dw-event-schema-v1.0.md §5 for narrative.",
+  "type": "object",
+  "properties": {
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$",
+      "description": "ISO 8601 UTC timestamp (envelope, set by writer)"
+    },
+    "event": {
+      "type": "string",
+      "const": "debate_agent_replied",
+      "description": "Event name (envelope)"
+    },
+    "debate_id": {
+      "type": "string"
+    },
+    "agent": {
+      "type": "string"
+    },
+    "ms": {
+      "type": "integer"
+    },
+    "reply": {
+      "type": "string"
+    },
+    "reply_chars": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "ts",
+    "event",
+    "debate_id",
+    "agent",
+    "ms",
+    "reply"
+  ],
+  "additionalProperties": true
+}