dw-kit 1.4.0 → 1.6.0-rc.1

package/.claude/agents/executor.md

@@ -1,80 +1,80 @@
----
-name: executor
-description: "Agent thực hiện implementation theo plan đã approve. Có thể chạy trong isolated worktree. Tuân thủ TDD, commit sau mỗi subtask."
-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Grep
-  - Glob
-  - Agent
-disallowedTools:
-  - NotebookEdit
-model: inherit
----
-
-# Executor Agent
-
-Bạn là Senior Developer thực hiện implementation. Nhiệm vụ: execute plan đã được approve, tuân thủ TDD, commit sau mỗi subtask.
-
-## Nguyên Tắc
-
-1. **Đọc plan trước mỗi subtask** — không làm từ memory
-2. **Chỉ làm đúng scope** — không "while I'm here" fixes
-3. **TDD**: Test trước → implement → refactor → commit
-4. **Gặp ambiguity** → DỪNG và hỏi human, không tự suy diễn
-5. **Scope thay đổi** → cập nhật plan, hỏi human trước khi tiếp tục
-6. **Mỗi subtask done** → update progress file + commit
-
-## TDD Workflow (mỗi subtask)
-
-```
-1. Đọc acceptance criteria của subtask
-2. Viết test mô tả expected behavior → RED (failing)
-3. Implement tối thiểu để test pass → GREEN
-4. Refactor nếu cần (không thay đổi tests) → REFACTOR
-5. Verify: không còn debug code
-6. Update progress file: subtask status → Done
-7. Commit: git commit -m "type(scope): description"
-```
-
-## Khi Gặp Blocker
-
-```
-1. Ghi blocker vào progress file với mô tả đầy đủ
-2. Xác định: có thể self-resolve không?
-   - Có: document approach, proceed
-   - Không: DỪNG, escalate rõ ràng
-3. KHÔNG silent-skip subtask
-4. KHÔNG self-approve scope changes
-```
-
-## Worktree Mode (nếu được chỉ định)
-
-Khi task có risk cao (large refactor, breaking changes):
-- Xác nhận với human: "Task này có risk cao. Nên chạy trong isolated worktree. Confirm?"
-- Sau khi confirm: sử dụng isolation: "worktree" khi spawn sub-agents
-- Changes trong worktree không ảnh hưởng main branch cho đến khi human approve merge
-
-## Pre-Commit Checklist (mỗi subtask)
-
-```
-[ ] Logic đúng? Tests pass?
-[ ] Không còn console.log/debugger/var_dump
-[ ] Không có hardcoded credentials/tokens
-[ ] Commit message theo format: type(scope): description ≤72 chars
-[ ] Progress file updated
-```
-
-## Commit Format
-
-```
-<type>(<scope>): <mô tả ≤72 ký tự>
-
-[Chi tiết nếu cần — tại sao, không phải gì]
-
-Co-Authored-By: Claude <noreply@anthropic.com>
-```
-
-Types: `feat` `fix` `refactor` `test` `docs` `chore` `style` `perf`
+---
+name: executor
+description: "Agent thực hiện implementation theo plan đã approve. Có thể chạy trong isolated worktree. Tuân thủ TDD, commit sau mỗi subtask."
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+disallowedTools:
+  - NotebookEdit
+model: inherit
+---
+
+# Executor Agent
+
+Bạn là Senior Developer thực hiện implementation. Nhiệm vụ: execute plan đã được approve, tuân thủ TDD, commit sau mỗi subtask.
+
+## Nguyên Tắc
+
+1. **Đọc plan trước mỗi subtask** — không làm từ memory
+2. **Chỉ làm đúng scope** — không "while I'm here" fixes
+3. **TDD**: Test trước → implement → refactor → commit
+4. **Gặp ambiguity** → DỪNG và hỏi human, không tự suy diễn
+5. **Scope thay đổi** → cập nhật plan, hỏi human trước khi tiếp tục
+6. **Mỗi subtask done** → update progress file + commit
+
+## TDD Workflow (mỗi subtask)
+
+```
+1. Đọc acceptance criteria của subtask
+2. Viết test mô tả expected behavior → RED (failing)
+3. Implement tối thiểu để test pass → GREEN
+4. Refactor nếu cần (không thay đổi tests) → REFACTOR
+5. Verify: không còn debug code
+6. Update progress file: subtask status → Done
+7. Commit: git commit -m "type(scope): description"
+```
+
+## Khi Gặp Blocker
+
+```
+1. Ghi blocker vào progress file với mô tả đầy đủ
+2. Xác định: có thể self-resolve không?
+   - Có: document approach, proceed
+   - Không: DỪNG, escalate rõ ràng
+3. KHÔNG silent-skip subtask
+4. KHÔNG self-approve scope changes
+```
+
+## Worktree Mode (nếu được chỉ định)
+
+Khi task có risk cao (large refactor, breaking changes):
+- Xác nhận với human: "Task này có risk cao. Nên chạy trong isolated worktree. Confirm?"
+- Sau khi confirm: sử dụng isolation: "worktree" khi spawn sub-agents
+- Changes trong worktree không ảnh hưởng main branch cho đến khi human approve merge
+
+## Pre-Commit Checklist (mỗi subtask)
+
+```
+[ ] Logic đúng? Tests pass?
+[ ] Không còn console.log/debugger/var_dump
+[ ] Không có hardcoded credentials/tokens
+[ ] Commit message theo format: type(scope): description ≤72 chars
+[ ] Progress file updated
+```
+
+## Commit Format
+
+```
+<type>(<scope>): <imperative English ≤72 chars>
+
+[Optional body — explain WHY, not WHAT, wrap at 72]
+```
+
+Types: `feat` `fix` `refactor` `test` `docs` `chore` `style` `perf`
+
+English imperative mood. **Do not append `Co-Authored-By: Claude` or any AI signature.** Full rules: `.claude/rules/commit-standards.md`.

package/.claude/hooks/pre-commit-gate.sh

@@ -67,6 +67,65 @@ if [ -n "$STAGED_FILES" ]; then
   fi
 fi
 
+# v1.5 (ADR-0008): v3 task.md SVG regen on staged commit
+# Diff-aware — only render tasks whose task.md changed.
+# Fail-graceful: sub-package absent → Mermaid fallback (in-md, no SVG needed).
+# Auto-stage SVG if user opts-in to commit (gitignored by default per .gitignore).
+DW_BIN="$CLAUDE_PROJECT_DIR/bin/dw.mjs"
+if [ -f "$DW_BIN" ] && command -v node >/dev/null 2>&1 && [ -n "$STAGED_FILES" ]; then
+  TIMELINE_TASKS=$(echo "$STAGED_FILES" | grep -E '^\.dw/tasks/[^/]+/task\.md$' | sed -E 's|^\.dw/tasks/([^/]+)/task\.md$|\1|' | sort -u)
+  if [ -n "$TIMELINE_TASKS" ]; then
+    echo "📐 dw-kit: regenerating timeline.svg for staged task.md" >&2
+    while IFS= read -r task; do
+      [ -z "$task" ] && continue
+      node "$DW_BIN" task render "$task" >/dev/null 2>&1 || true
+      # Auto-stage SVG if not gitignored (opt-in projects)
+      SVG_FILE="$CLAUDE_PROJECT_DIR/.dw/tasks/$task/timeline.svg"
+      if [ -f "$SVG_FILE" ]; then
+        if ! git -C "$CLAUDE_PROJECT_DIR" check-ignore -q "$SVG_FILE" 2>/dev/null; then
+          git -C "$CLAUDE_PROJECT_DIR" add "$SVG_FILE" 2>/dev/null || true
+          echo "   ✓ staged $task/timeline.svg" >&2
+        fi
+      fi
+    done <<EOF
+$TIMELINE_TASKS
+EOF
+  fi
+fi
+
+# v1.6 (ADR-0009 R2-2): Agent OS post-hoc check.
+# When ≥1 active claim exists, verify staged files fall within an active claim's write_scope.
+# Cooperative protocol — warn only (cannot prevent non-compliant agents).
+if [ -f "$DW_BIN" ] && command -v node >/dev/null 2>&1 && [ -n "$STAGED_FILES" ]; then
+  CLAIMS_DIR="$CLAUDE_PROJECT_DIR/.dw/cache/agents/claims"
+  if [ -d "$CLAIMS_DIR" ] && ls "$CLAIMS_DIR"/*.json >/dev/null 2>&1; then
+    OUT_OF_SCOPE=$(STAGED="$STAGED_FILES" node -e "
+      const fs = require('fs');
+      const path = require('path');
+      (async () => {
+        const { listClaims } = await import('$CLAUDE_PROJECT_DIR/src/lib/agent-claim.mjs');
+        const { pathMatchesScope } = await import('$CLAUDE_PROJECT_DIR/src/lib/agent-conflict.mjs');
+        const claims = listClaims(process.env.CLAUDE_PROJECT_DIR || '$CLAUDE_PROJECT_DIR').filter(c => c._live_status === 'created' || c._live_status === 'active');
+        if (claims.length === 0) return;
+        const allScopes = claims.flatMap(c => c.write_scope);
+        const staged = (process.env.STAGED || '').split(/\r?\n/).filter(Boolean);
+        const outside = staged.filter(f => !pathMatchesScope(f, allScopes));
+        if (outside.length > 0) {
+          console.log('Files NOT in any active claim write_scope:');
+          for (const f of outside.slice(0, 10)) console.log('  ' + f);
+          if (outside.length > 10) console.log('  ... +' + (outside.length - 10) + ' more');
+        }
+      })().catch(e => { /* fail-graceful */ });
+    " 2>/dev/null || true)
+    if [ -n "$OUT_OF_SCOPE" ]; then
+      echo "⚠️  Agent OS (ADR-0009 R2-2): post-hoc claim check" >&2
+      echo "$OUT_OF_SCOPE" >&2
+      echo "   Run \`dw agent claims\` to inspect; cooperative trust — proceed with care." >&2
+      ISSUES=$((ISSUES + 1))
+    fi
+  fi
+fi
+
 # Check: sensitive patterns?
 SENSITIVE=$(git diff --cached 2>/dev/null | grep "^+" | grep -iE '(password|secret|api_key|private_key)[[:space:]]*=[[:space:]]*.{8,}' | grep -v "^+++" | head -3)
 if [ -n "$SENSITIVE" ]; then

package/.claude/hooks/stop-check.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# Stop hook: warn on uncommitted changes + auto-append handoff to active task tracking.md
-# v1.4: auto-handoff (ST-2.5) — append session summary to tracking.md when uncommitted
+# Stop hook: warn on uncommitted changes + auto-handoff + auto-rotate v3 task.md
+# v1.4: auto-handoff (ST-2.5) — append session summary when uncommitted
+# v1.5 (ADR-0008): v3 task.md support + auto-rotate Section 4 > 400 lines via `dw task rotate`
 # Output via stderr for user visibility. Always exit 0 (non-blocking).
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
@@ -22,60 +23,139 @@ else
   WARNINGS+=("Uncommitted changes:"$'\n'"$CHANGED")
 fi
 
-# --- Check in-progress tasks (both v1 3-file and v2 2-file formats) ---
+# --- Check in-progress tasks (v1 / v2 / v3 formats) ---
 TASKS_DIR="$PROJECT_DIR/.dw/tasks"
 ACTIVE_TASK=""
+ACTIVE_TASK_FORMAT=""
+ACTIVE_TASK_FILE=""
 
 if [ -d "$TASKS_DIR" ]; then
+  # v3 format (preferred): task.md with frontmatter status In Progress
+  while IFS= read -r timeline_file; do
+    if grep -qE "^status:[[:space:]]*(In Progress|Blocked)" "$timeline_file" 2>/dev/null; then
+      task_name=$(basename "$(dirname "$timeline_file")")
+      WARNINGS+=("Task active (v3): $task_name")
+      if [ -z "$ACTIVE_TASK" ]; then
+        ACTIVE_TASK="$task_name"
+        ACTIVE_TASK_FORMAT="v3"
+        ACTIVE_TASK_FILE="$timeline_file"
+      fi
+    fi
+  done < <(find "$TASKS_DIR" -maxdepth 3 -name "task.md" -not -path "*/archive/*" 2>/dev/null)
+
   # v1 format: {task}-progress.md with "Trạng thái: In Progress"
   while IFS= read -r progress_file; do
     if grep -q "Trạng thái: In Progress" "$progress_file" 2>/dev/null; then
       task_name=$(basename "$(dirname "$progress_file")")
       WARNINGS+=("Task in-progress (v1): $task_name")
-      [ -z "$ACTIVE_TASK" ] && ACTIVE_TASK="$task_name"
+      if [ -z "$ACTIVE_TASK" ]; then
+        ACTIVE_TASK="$task_name"
+        ACTIVE_TASK_FORMAT="v1"
+        ACTIVE_TASK_FILE="$progress_file"
+      fi
     fi
   done < <(find "$TASKS_DIR" -maxdepth 3 -name "*-progress.md" -not -path "*/archive/*" 2>/dev/null)
 
   # v2 format: tracking.md with frontmatter status In Progress
   while IFS= read -r tracking_file; do
+    # Skip if same folder already has task.md (v3 takes precedence)
+    folder_dir=$(dirname "$tracking_file")
+    [ -f "$folder_dir/task.md" ] && continue
     if grep -qE "^status:.*(In Progress|Code Complete)" "$tracking_file" 2>/dev/null; then
-      task_name=$(basename "$(dirname "$tracking_file")")
+      task_name=$(basename "$folder_dir")
       WARNINGS+=("Task active (v2): $task_name")
-      [ -z "$ACTIVE_TASK" ] && ACTIVE_TASK="$task_name"
+      if [ -z "$ACTIVE_TASK" ]; then
+        ACTIVE_TASK="$task_name"
+        ACTIVE_TASK_FORMAT="v2"
+        ACTIVE_TASK_FILE="$tracking_file"
+      fi
     fi
   done < <(find "$TASKS_DIR" -maxdepth 3 -name "tracking.md" -not -path "*/archive/*" 2>/dev/null)
 fi
 
-# --- Auto-handoff: append snippet to active task's tracking.md if uncommitted + active task ---
-if [ "$HAS_UNCOMMITTED" = "1" ] && [ -n "$ACTIVE_TASK" ]; then
-  TRACKING_FILE="$TASKS_DIR/$ACTIVE_TASK/tracking.md"
-  if [ -f "$TRACKING_FILE" ]; then
-    TS=$(date -u +"%Y-%m-%d %H:%M UTC")
-    MARKER="<!-- dw-auto-handoff -->"
+# --- v3 auto-rotate (Section 4 > 400 lines → timeline-history.md) ---
+# Fire-and-forget; uses local dw CLI if available.
+if [ "$ACTIVE_TASK_FORMAT" = "v3" ] && [ -n "$ACTIVE_TASK" ]; then
+  DW_BIN="$PROJECT_DIR/bin/dw.mjs"
+  if [ -f "$DW_BIN" ] && command -v node >/dev/null 2>&1; then
+    ROTATE_OUTPUT=$(node "$DW_BIN" task rotate "$ACTIVE_TASK" --quiet 2>&1 || true)
+    if [ -n "$ROTATE_OUTPUT" ] && echo "$ROTATE_OUTPUT" | grep -q "rotated"; then
+      WARNINGS+=("Auto-rotated Section 4 → timeline-history.md ($ACTIVE_TASK)")
+    fi
+  fi
+fi
+
+# --- Auto-handoff: append snippet to active task's tracking/timeline file if uncommitted ---
+if [ "$HAS_UNCOMMITTED" = "1" ] && [ -n "$ACTIVE_TASK_FILE" ]; then
+  TS=$(date -u +"%Y-%m-%d %H:%M UTC")
+  MARKER="<!-- dw-auto-handoff -->"
 
-    # Only append if no handoff snippet added in last 10 minutes (idempotency via marker + timestamp grep)
-    if ! grep -q "$MARKER.*$TS" "$TRACKING_FILE" 2>/dev/null; then
-      {
-        echo ""
-        echo "$MARKER"
-        echo "### Auto-handoff — $TS"
-        echo ""
-        echo "Session ended with uncommitted changes."
-        echo ""
-        echo "**Files changed:**"
-        echo '```'
-        git -C "$PROJECT_DIR" diff --stat --cached 2>/dev/null
-        git -C "$PROJECT_DIR" diff --stat 2>/dev/null
-        echo '```'
-        echo ""
-        echo "Next session: commit or continue work. Re-read spec.md + this tracking.md first."
-        echo ""
-      } >> "$TRACKING_FILE" 2>/dev/null
-      WARNINGS+=("Auto-handoff appended to: $TRACKING_FILE")
+  # Only append if no handoff snippet added in last 10 minutes (idempotency via marker + timestamp grep)
+  if ! grep -q "$MARKER.*$TS" "$ACTIVE_TASK_FILE" 2>/dev/null; then
+    if [ "$ACTIVE_TASK_FORMAT" = "v3" ]; then
+      READ_FIRST="Re-read this task.md (Section 1 + 3 + 5) first."
+    else
+      READ_FIRST="Re-read spec.md + this tracking.md first."
     fi
+
+    HANDOFF_SNIPPET=$({
+      echo ""
+      echo "$MARKER"
+      echo "### Auto-handoff — $TS"
+      echo ""
+      echo "Session ended with uncommitted changes."
+      echo ""
+      echo "**Files changed:**"
+      echo '```'
+      git -C "$PROJECT_DIR" diff --stat --cached 2>/dev/null
+      git -C "$PROJECT_DIR" diff --stat 2>/dev/null
+      echo '```'
+      echo ""
+      echo "Next session: commit or continue work. $READ_FIRST"
+      echo ""
+    })
+
+    if [ "$ACTIVE_TASK_FORMAT" = "v3" ]; then
+      # v3: insert before Section 5 closing (## 6. Annexes) so handoffs stay in Handoff section
+      # Use node for cross-platform reliable section insertion
+      if command -v node >/dev/null 2>&1; then
+        TMPF=$(mktemp)
+        printf '%s' "$HANDOFF_SNIPPET" > "$TMPF"
+        node -e "
+          const fs = require('fs');
+          const file = '$ACTIVE_TASK_FILE';
+          const snippet = fs.readFileSync('$TMPF', 'utf8');
+          const body = fs.readFileSync(file, 'utf8');
+          // Insert right before '## 6. Annexes' (or EOF if not found)
+          const sec6 = body.indexOf('## 6. Annexes');
+          if (sec6 >= 0) {
+            fs.writeFileSync(file, body.slice(0, sec6) + snippet + '\\n' + body.slice(sec6));
+          } else {
+            // No Section 6 yet — append (rare; only freshly-scaffolded tasks)
+            fs.appendFileSync(file, snippet);
+          }
+        " 2>/dev/null
+        rm -f "$TMPF"
+      else
+        # Fallback: append to EOF (degraded for v3 but still functional)
+        printf '%s' "$HANDOFF_SNIPPET" >> "$ACTIVE_TASK_FILE" 2>/dev/null
+      fi
+    else
+      # v1/v2: append to EOF (legacy behavior, unchanged)
+      printf '%s' "$HANDOFF_SNIPPET" >> "$ACTIVE_TASK_FILE" 2>/dev/null
+    fi
+    WARNINGS+=("Auto-handoff appended to: $ACTIVE_TASK_FILE")
   fi
 fi
 
+# --- Nudge dw task show (first-of-session, v3 only) ---
+NUDGE_FILE="$PROJECT_DIR/.dw/cache/.show-nudge-$(date -u +%Y-%m-%d)"
+if [ "$ACTIVE_TASK_FORMAT" = "v3" ] && [ -n "$ACTIVE_TASK" ] && [ ! -f "$NUDGE_FILE" ]; then
+  mkdir -p "$PROJECT_DIR/.dw/cache" 2>/dev/null
+  touch "$NUDGE_FILE" 2>/dev/null
+  WARNINGS+=("Tip: \`dw task show $ACTIVE_TASK\` (terminal) · \`dw task view $ACTIVE_TASK\` (HTML in browser) · \`dw task lint\` (drift check)")
+fi
+
 # --- Print warnings ---
 if [ ${#WARNINGS[@]} -gt 0 ]; then
   printf -- "--- dw stop-check ---\n" >&2

package/.claude/rules/commit-standards.md

@@ -1,37 +1,48 @@
-# Commit Standards
-
-## Format
-```
-<type>(<scope>): <mô tả tiếng Việt hoặc tiếng Anh>
-
-[Body - chi tiết thay đổi, lý do]
-[Blank line]
-[Footer - breaking changes, references]
-
-Co-Authored-By: Claude <noreply@anthropic.com>
-```
-
-## Types
-| Type | Khi nào dùng |
-|------|-------------|
-| `feat` | Tính năng mới |
-| `fix` | Sửa lỗi |
-| `refactor` | Tái cấu trúc, không thay đổi behavior |
-| `test` | Thêm/sửa tests |
-| `docs` | Tài liệu, comments |
-| `chore` | Build, config, dependencies |
-| `style` | Format, whitespace (không thay đổi logic) |
-| `perf` | Cải thiện performance |
-
-## Quy tắc
-- Mỗi commit = 1 subtask hoặc 1 đơn vị logic hoàn chỉnh
-- Mô tả ngắn <= 72 ký tự
-- Dùng thì hiện tại: "thêm", "sửa", "cập nhật" (không phải "đã thêm")
-- KHÔNG commit files chứa secrets (.env, credentials, tokens)
-- KHÔNG commit console.log/debugger còn sót
-
-## Branch Naming
-```
-<type>/<task-name>
-```
-Ví dụ: `feat/user-auth`, `fix/login-redirect`, `refactor/api-structure`
+# Commit Standards
+
+## Format
+
+```
+<type>(<scope>): <imperative English subject ≤72 chars>
+
+[Optional body — explain WHY, wrap at 72 chars]
+
+[Optional footer — BREAKING CHANGE: ..., Refs: #123]
+```
+
+**English only.** Use imperative mood: `add user auth`, `fix login redirect`, `update API client` — never `added`, `fixes`, or past tense.
+
+**Do not append `Co-Authored-By: Claude` or any AI signature.** Commits are authored by the human who reviewed and shipped them.
+
+## Types
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `refactor` | Restructure without behavior change |
+| `test` | Add or update tests |
+| `docs` | Documentation, comments |
+| `chore` | Build, config, dependencies |
+| `style` | Format, whitespace (no logic change) |
+| `perf` | Performance improvement |
+
+## Rules
+
+- One commit = one subtask or one complete logical unit
+- Subject ≤72 chars; body wrapped at 72
+- Imperative present tense (`add`, `fix`, `update` — not `added`, `fixed`, `updates`)
+- Never commit secrets (`.env`, credentials, tokens)
+- Never commit leftover `console.log`, `debugger`, etc.
+
+## Branch Naming
+
+```
+<type>/<task-name>
+```
+
+Examples: `feat/user-auth`, `fix/login-redirect`, `refactor/api-structure`
+
+## Localization Override
+
+This convention defaults to English to match the global open-source norm. A team that ships only in another language MAY override this rule in their own project by editing this file — but the toolkit itself ships English-default templates.

package/.claude/rules/dw.md

@@ -18,7 +18,7 @@ Prompt contains `--no-dw` → ignore all dw instructions for that request, work
 | **Guards** | Block unsafe actions | privacy-block, pre-commit-gate | Non-negotiable safety |
 | **Surfaces** | Make state visible | ACTIVE.md, project-map, modules | Shared team context |
 | **Records** | Capture decisions | ADRs in `.dw/decisions/` | Organizational memory |
-| **Bridges** | Connect across sessions | auto-handoff, tracking.md | Continuity over time |
+| **Bridges** | Connect across sessions | auto-handoff, task.md, auto-rotate | Continuity over time |
 | **Tunes** | Behavioral knobs | roles, depth, presets | Team/solo customization |
 
 ---
@@ -30,8 +30,8 @@ Assess per task — file count, API changes, git blame:
 | Scope | Depth | Approach |
 |-------|-------|----------|
 | ≤2 files, hotfix | quick | Understand → Execute → Close |
-| 3–5 files, new module | standard | spec.md + tracking.md |
-| 6+ files, API/DB/security | thorough | Full 2-file + optional reports/ |
+| 3–5 files, new module | standard | task.md (Sections 1-5) |
+| 6+ files, API/DB/security | thorough | Full task.md + Section 6 Annexes + optional Section 7 Debate |
 
 Default when unsure: `standard`.
 
@@ -40,22 +40,56 @@ Default when unsure: `standard`.
 ## Session Start
 
 1. Read `.dw/tasks/ACTIVE.md` — single source of truth for team state
-2. Resume any task with status `In Progress` from its `tracking.md`
+2. Resume any task with status `In Progress` from its `task.md` (v3) / `tracking.md` (v2)
 3. Check `.dw/decisions/` for recent ADRs if task touches architecture
+4. Optional quick scan: `dw task show <name>` for ANSI snapshot
 
 ---
 
-## Task Docs (v2 default — 2 files)
+## Task Docs (v3 default — 1 file, per ADR-0008)
 
 ```
 .dw/tasks/{task-name}/
-├── spec.md      # Intent + plan (stable after approve)
-└── tracking.md  # Progress + handoff (mutable)
+├── task.md              # canonical SoT: Snapshot + Intent + Tracker + Changelog + Handoff
+├── timeline.svg             # auto-rendered sidecar (v1.6+ via dw-kit-render)
+└── (free-form appendages):
+    ├── baseline.md          # benchmark snapshots
+    ├── experiment-{id}.md   # spike notes
+    ├── debate-r{N}.md       # extended adversarial logs
+    └── timeline-history.md  # auto-rotated changelog overflow
 ```
 
-Legacy 3-file (`context + plan + progress`) still supported for older tasks.
+**Section structure** (status lives ONLY in Section 3 — drift prevention):
+1. Snapshot · 2. Intent & Scope · 3. Subtask Tracker · 4. Timeline/Changelog · 5. Handoff & Friction · 6. Annexes · 7. Debate Log (optional thorough)
 
-Templates at `.dw/core/templates/v2/`.
+**Lint default strict** — drift markers (✅🟡 status) in Section 2 → error. Configure via `task.lint: warn | off` in `dw.config.yml`.
+
+**CLI:** `dw task new <name>` (scaffold) · `dw task show [name]` (ANSI snapshot) · `dw task lint [name]` (drift + schema check) · `dw task migrate <name>` (v2→v3) · `dw task rotate [name]` (auto Section-4 overflow).
+
+**Backward compat:**
+- v2 (`spec.md` + `tracking.md`) read-only — migrate via `dw task migrate <name>`.
+- v1 (3-file `context + plan + progress`) read-only legacy.
+
+Templates: `.dw/core/templates/v3/task.md`. Schema: `.dw/core/schemas/task-frontmatter.schema.json` (ajv-validated).
+
+---
+
+## Agent OS (v1.6+, ADR-0009)
+
+Multi-agent orchestration protocol. Multiple AI agents (Claude Code / Codex / Gemini / human) work from same `task.md` without conflict.
+
+```
+dw agent claim <task> --subtasks ST-1 --write "src/foo.js" --vendor claude --lease 1h
+dw agent claims                          # list active
+dw agent conflicts                        # detect overlaps (exit 1 if dirty)
+dw agent release <claim-id>               # clean exit
+```
+
+**Cooperative-only:** protocol catches violations post-hoc via `dw agent conflicts` + `pre-commit-gate`. Not an enforcement system.
+
+**Storage:** `.dw/cache/agents/claims/{id}.json` (gitignored ephemeral); `.dw/tasks/{task}/reports/{agent}-{ts}.md` + `events.jsonl` (committed audit).
+
+**Workflow:** orchestrator role splits work → agents claim → write → release → reports merged into `task.md` Section 3/4 → orchestrator stops before push/release for human approval.
 
 ---
 
@@ -82,11 +116,13 @@ See `.dw/core/skills-index.md` for complete list with descriptions.
 ## Commit Format
 
 ```
-<type>(<scope>): <description ≤72 chars>
+<type>(<scope>): <imperative English subject ≤72 chars>
 ```
 
 Types: `feat` `fix` `refactor` `test` `docs` `chore` `style` `perf`
 
+English imperative mood (`add`, `fix`, `update` — not past tense or other languages). **Do not append `Co-Authored-By: Claude` or any AI signature.** Full rules: `.claude/rules/commit-standards.md`.
+
 ---
 
 ## Hooks
@@ -95,7 +131,7 @@ Types: `feat` `fix` `refactor` `test` `docs` `chore` `style` `perf`
 |------|---------|
 | `privacy-block` | Guard — block .env/credentials/keys |
 | `pre-commit-gate` | Guard — quality check + sensitive scan |
-| `stop-check` | Bridge — auto-handoff to tracking.md + uncommitted warning |
+| `stop-check` | Bridge — auto-handoff to task.md (v3) / tracking.md (v2) + auto-rotate Section 4 + uncommitted warning |
 | `telemetry-log` | Meta — local event log for v1.4 cut decisions |
 
 Legacy (deprecated, removal in v2.0 based on telemetry): scout-block, post-write, progress-ping, session-init, safety-guard.

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

@@ -48,17 +48,20 @@ Nếu không có changes → thông báo "Không có gì để commit."
 
 ### 5. Tạo commit message
 
-Nếu có `$ARGUMENTS` → dùng làm mô tả:
+Nếu có `$ARGUMENTS` → dùng làm subject (rewrite sang English imperative nếu input không phải English):
 ```
-<auto-detect-type>(<auto-detect-scope>): $ARGUMENTS
+<auto-detect-type>(<auto-detect-scope>): <imperative English ≤72 chars>
 
-Co-Authored-By: Claude <noreply@anthropic.com>
+[Optional body — explain WHY in English, wrap at 72]
 ```
 
+**KHÔNG append `Co-Authored-By: Claude` hoặc bất kỳ AI signature nào.**
+Convention chi tiết: `.claude/rules/commit-standards.md`.
+
 Nếu KHÔNG có `$ARGUMENTS` → phân tích diff và tạo message tự động:
 - Detect type từ loại thay đổi (feat/fix/refactor/test/docs/chore)
 - Detect scope từ files/directories changed
-- Viết mô tả ngắn gọn
+- Subject: imperative English, ≤72 chars (`add X`, `fix Y`, `update Z` — không past tense)
 
 ### 6. Thực hiện commit
 ```bash

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

@@ -78,7 +78,7 @@ Nếu yes → write file + print:
 ✓ ADR-{NNNN} created
   Status: Proposed
   Next: Review → change status to Accepted when approved
-        Related task: update tracking.md với reference
+        Related task: update task.md (v3) / tracking.md (v2) với reference
 ```
 
 ## Quality Bar
@@ -110,7 +110,8 @@ Trong các case này, đẩy lại user với câu hỏi clarify.
 
 ## Super-power: Link related task
 
-Sau khi save ADR, nếu đang trong task folder (check `.dw/tasks/*/tracking.md` có reference đến decision này không):
+Sau khi save ADR, nếu đang trong task folder, check task file theo thứ tự ưu tiên:
 
-1. Append vào `tracking.md` section Changelog: `Referenced: ADR-{NNNN}`
-2. Update `spec.md` frontmatter `related_adr: ADR-{NNNN}` nếu chưa có
+- **v3** (default): `.dw/tasks/*/task.md` — append Section 4 Changelog entry: `Referenced: ADR-{NNNN}`; update frontmatter `related_adr: ADR-{NNNN}` nếu chưa có.
+- **v2**: `.dw/tasks/*/tracking.md` — append Changelog entry; update spec.md frontmatter `related_adr`.
+- **v1** (legacy): `.dw/tasks/*/*-progress.md` — append changelog