dw-kit 1.3.0 → 1.3.4

package/.dw/core/ROLES.md

@@ -1,257 +1,257 @@
-<!-- core-version: 1.0 -->
-
-# Team Roles & Authority
-
-> **Nguyên tắc**: Roles = capabilities, không phải hierarchy.
-> Config `team.roles` quyết định phases nào available, không phải quality tier.
-
----
-
-## Role Overview
-
-| Role | Ký hiệu config | Core responsibility | Decision authority |
-|------|----------------|--------------------|--------------------|
-| Developer | `dev` | Implementation, testing | Code-level decisions |
-| Tech Lead | `techlead` | Architecture, code standards | Architecture decisions, plan approval |
-| Business Analyst | `ba` | Requirements, user stories | Requirements sign-off |
-| QC Engineer | `qc` | Test planning, quality verification | QA sign-off (Layer 4) |
-| Product Manager | `pm` | Progress visibility, metrics | Sprint planning, backlog priority |
-
-> `dev` luôn required. Các roles khác là optional — không có thì phase đó gracefully degrade.
-
----
-
-## Developer (`dev`)
-
-**Trách nhiệm chính**: Research → Plan → Execute → Commit
-
-### Phases Developer Owns
-
-| Phase | Responsibility |
-|-------|---------------|
-| Initialize | Tạo task docs, scope assessment |
-| Understand | Codebase research, context gathering |
-| Plan | Solution design, subtask breakdown |
-| Execute | Implementation, TDD, subtask commits |
-| Verify | Self-review (Layer 1), automated gates (Layer 2) |
-| Close | Commit, effort log, handoff |
-
-### Decision Authority
-
-- Code implementation decisions
-- Library/dependency choices (minor)
-- Subtask ordering và approach (trong scope của plan approved)
-- **DỪNG và hỏi khi**: architecture change, API contract change, scope expansion
-
-### Best Practices
-
-- Commit nhỏ, thường xuyên (mỗi subtask = 1 commit)
-- Update progress file sau mỗi subtask
-- Không implement ngoài scope plan đã approve
-- Phát hiện giả định sai → ghi Changelog + hỏi TL trước khi tiếp tục
-
----
-
-## Tech Lead (`techlead`)
-
-**Trách nhiệm chính**: Architecture quality, standards enforcement, plan approval
-
-### Phases TL Owns
-
-| Phase | Responsibility |
-|-------|---------------|
-| Plan | Architecture review, approve plan trước Execute |
-| Execute | Unblock architecture decisions during implementation |
-| Verify | Code review (Layer 3 — architecture focus) |
-| Close | Final technical sign-off |
-
-### Decision Authority
-
-- Architecture decisions (service boundaries, patterns, data models)
-- Plan approval: **explicit gate** — Execute không bắt đầu khi chưa có TL approve
-- A/B testing resolution: TL chọn approach khi hai approaches không rõ ưu/nhược
-- Technical debt acknowledgment: quyết định "acceptable" hay "must fix"
-
-### Architecture Review Checklist
-
-```
-[ ] Approach consistent với codebase patterns?
-[ ] Scalability implications acceptable?
-[ ] Security design đúng?
-[ ] API contract backward compatible (hoặc migration plan có)?
-[ ] Subtask breakdown hợp lý? Dependencies đúng?
-[ ] Risks identified và có mitigation?
-```
-
-### TL không có?
-
-- Plan vẫn proceed nhưng developer self-review architecture decisions
-- Ghi rõ trong plan: "Architecture decision by dev (no TL review)"
-- Architecture decisions nên bảo thủ hơn khi không có TL
-
----
-
-## Business Analyst (`ba`)
-
-**Trách nhiệm chính**: Requirements clarity, user stories, acceptance criteria
-
-### Phases BA Owns
-
-| Phase | Responsibility |
-|-------|---------------|
-| Initialize | Requirements gathering, user stories |
-| Plan | Review subtask acceptance criteria |
-| Verify | Acceptance criteria verification |
-
-### Decision Authority
-
-- Requirements sign-off: "dev builds the right thing"
-- Scope boundary: in-scope vs out-of-scope
-- Acceptance criteria: testable, specific, agreed
-
-### Requirements Output Format
-
-```markdown
-## User Story
-As a [role], I want [goal] so that [benefit].
-
-## Acceptance Criteria
-Given [precondition]
-When [action]
-Then [outcome]
-
-## Out of Scope
-- [explicitly excluded items]
-
-## Edge Cases to Handle
-- [edge case 1]
-- [edge case 2]
-```
-
-### BA không có?
-
-- Developer writes requirements từ conversation với stakeholder
-- Requirements review là developer + TL (không có independent BA)
-- Risk cao hơn về misunderstood requirements — tăng frequency of check-ins
-
----
-
-## QC Engineer (`qc`)
-
-**Trách nhiệm chính**: Test planning, independent quality verification
-
-### Phases QC Owns
-
-| Phase | Responsibility |
-|-------|---------------|
-| Plan | Test plan tạo song song với dev plan |
-| Verify | Execute test plan, Layer 4 sign-off |
-
-### Decision Authority
-
-- QA sign-off: **explicit gate** cho `thorough` depth — không thể self-approve
-- Bug severity classification
-- Regression scope: gì cần test lại sau change
-
-### Test Plan Structure
-
-```markdown
-## Test Cases
-### TC-1: [Test case name]
-- **Given**: [precondition]
-- **When**: [action]
-- **Then**: [expected result]
-- **Priority**: P1/P2/P3
-
-## Regression Checklist
-- [ ] [Feature 1 không bị ảnh hưởng]
-- [ ] [Feature 2 không bị ảnh hưởng]
-
-## Security Checklist (nếu applicable)
-- [ ] Input validation
-- [ ] Auth/authz checks
-- [ ] No data exposure
-
-## Performance Checklist (nếu applicable)
-- [ ] Response time acceptable
-- [ ] No N+1 queries introduced
-```
-
-### QC không có?
-
-- Developer tự execute test plan (nếu có) hoặc manual verification
-- Layer 4 QA sign-off skip — nhưng automated gates (Layer 4a) vẫn chạy
-- Risk cao hơn về undiscovered bugs
-
----
-
-## Product Manager (`pm`)
-
-**Trách nhiệm chính**: Progress visibility, metrics, sprint planning
-
-### Phases PM Owns
-
-| Phase | Responsibility |
-|-------|---------------|
-| Initialize | Sprint planning, priority |
-| Close | Sprint review, velocity tracking |
-| Standalone: Reports | Dashboard generation |
-
-### PM View
-
-PM không cần đọc code — PM đọc:
-- Progress files (status per subtask)
-- Dashboard reports (velocity, metrics)
-- Sprint review summaries
-
-### Dashboard Metrics
-
-| Metric | Source | Update frequency |
-|--------|--------|-----------------|
-| Tasks: done/in-progress/blocked | Progress files | Real-time |
-| Velocity | Closed tasks per sprint | Per sprint |
-| Estimate accuracy | Estimate vs actual | Per task |
-| DORA: deployment frequency | Git history | Per release |
-| DORA: lead time | Task start → deploy | Per release |
-
----
-
-## Multi-Role Workflow
-
-Full team workflow (tất cả roles):
-
-```
-BA: /dw-requirements     → requirements doc + user stories
-     ↓
-TL: /dw-arch-review      → architecture decision + approve
-     ↓
-Dev: /dw-task-init       → task docs
-Dev: /dw-research        → codebase analysis
-Dev+QC: /dw-plan         → dev plan + test plan (parallel)
-     ↓
-TL approve plan
-     ↓
-Dev: /dw-execute         → TDD implementation, commits
-     ↓
-TL: /dw-review           → architecture + code review
-     ↓
-QC: manual/auto testing  → Layer 4 verification
-     ↓
-Dev: /dw-commit          → pre-commit gates
-     ↓
-PM: /dw-dashboard        → visibility, metrics
-```
-
-Không phải mọi task cần full chain. `default_depth` + available roles quyết định.
-
----
-
-## Role-Depth Matrix
-
-| Role | Quick | Standard | Thorough |
-|------|-------|----------|----------|
-| dev | required | required | required |
-| techlead | not needed | arch decisions only | full review + approval |
-| ba | not needed | requirements check | full requirements |
-| qc | not needed | not needed | full test plan + sign-off |
-| pm | not needed | optional | dashboard |
+<!-- core-version: 1.0 -->
+
+# Team Roles & Authority
+
+> **Nguyên tắc**: Roles = capabilities, không phải hierarchy.
+> Config `team.roles` quyết định phases nào available, không phải quality tier.
+
+---
+
+## Role Overview
+
+| Role | Ký hiệu config | Core responsibility | Decision authority |
+|------|----------------|--------------------|--------------------|
+| Developer | `dev` | Implementation, testing | Code-level decisions |
+| Tech Lead | `techlead` | Architecture, code standards | Architecture decisions, plan approval |
+| Business Analyst | `ba` | Requirements, user stories | Requirements sign-off |
+| QC Engineer | `qc` | Test planning, quality verification | QA sign-off (Layer 4) |
+| Product Manager | `pm` | Progress visibility, metrics | Sprint planning, backlog priority |
+
+> `dev` luôn required. Các roles khác là optional — không có thì phase đó gracefully degrade.
+
+---
+
+## Developer (`dev`)
+
+**Trách nhiệm chính**: Research → Plan → Execute → Commit
+
+### Phases Developer Owns
+
+| Phase | Responsibility |
+|-------|---------------|
+| Initialize | Tạo task docs, scope assessment |
+| Understand | Codebase research, context gathering |
+| Plan | Solution design, subtask breakdown |
+| Execute | Implementation, TDD, subtask commits |
+| Verify | Self-review (Layer 1), automated gates (Layer 2) |
+| Close | Commit, effort log, handoff |
+
+### Decision Authority
+
+- Code implementation decisions
+- Library/dependency choices (minor)
+- Subtask ordering và approach (trong scope của plan approved)
+- **DỪNG và hỏi khi**: architecture change, API contract change, scope expansion
+
+### Best Practices
+
+- Commit nhỏ, thường xuyên (mỗi subtask = 1 commit)
+- Update progress file sau mỗi subtask
+- Không implement ngoài scope plan đã approve
+- Phát hiện giả định sai → ghi Changelog + hỏi TL trước khi tiếp tục
+
+---
+
+## Tech Lead (`techlead`)
+
+**Trách nhiệm chính**: Architecture quality, standards enforcement, plan approval
+
+### Phases TL Owns
+
+| Phase | Responsibility |
+|-------|---------------|
+| Plan | Architecture review, approve plan trước Execute |
+| Execute | Unblock architecture decisions during implementation |
+| Verify | Code review (Layer 3 — architecture focus) |
+| Close | Final technical sign-off |
+
+### Decision Authority
+
+- Architecture decisions (service boundaries, patterns, data models)
+- Plan approval: **explicit gate** — Execute không bắt đầu khi chưa có TL approve
+- A/B testing resolution: TL chọn approach khi hai approaches không rõ ưu/nhược
+- Technical debt acknowledgment: quyết định "acceptable" hay "must fix"
+
+### Architecture Review Checklist
+
+```
+[ ] Approach consistent với codebase patterns?
+[ ] Scalability implications acceptable?
+[ ] Security design đúng?
+[ ] API contract backward compatible (hoặc migration plan có)?
+[ ] Subtask breakdown hợp lý? Dependencies đúng?
+[ ] Risks identified và có mitigation?
+```
+
+### TL không có?
+
+- Plan vẫn proceed nhưng developer self-review architecture decisions
+- Ghi rõ trong plan: "Architecture decision by dev (no TL review)"
+- Architecture decisions nên bảo thủ hơn khi không có TL
+
+---
+
+## Business Analyst (`ba`)
+
+**Trách nhiệm chính**: Requirements clarity, user stories, acceptance criteria
+
+### Phases BA Owns
+
+| Phase | Responsibility |
+|-------|---------------|
+| Initialize | Requirements gathering, user stories |
+| Plan | Review subtask acceptance criteria |
+| Verify | Acceptance criteria verification |
+
+### Decision Authority
+
+- Requirements sign-off: "dev builds the right thing"
+- Scope boundary: in-scope vs out-of-scope
+- Acceptance criteria: testable, specific, agreed
+
+### Requirements Output Format
+
+```markdown
+## User Story
+As a [role], I want [goal] so that [benefit].
+
+## Acceptance Criteria
+Given [precondition]
+When [action]
+Then [outcome]
+
+## Out of Scope
+- [explicitly excluded items]
+
+## Edge Cases to Handle
+- [edge case 1]
+- [edge case 2]
+```
+
+### BA không có?
+
+- Developer writes requirements từ conversation với stakeholder
+- Requirements review là developer + TL (không có independent BA)
+- Risk cao hơn về misunderstood requirements — tăng frequency of check-ins
+
+---
+
+## QC Engineer (`qc`)
+
+**Trách nhiệm chính**: Test planning, independent quality verification
+
+### Phases QC Owns
+
+| Phase | Responsibility |
+|-------|---------------|
+| Plan | Test plan tạo song song với dev plan |
+| Verify | Execute test plan, Layer 4 sign-off |
+
+### Decision Authority
+
+- QA sign-off: **explicit gate** cho `thorough` depth — không thể self-approve
+- Bug severity classification
+- Regression scope: gì cần test lại sau change
+
+### Test Plan Structure
+
+```markdown
+## Test Cases
+### TC-1: [Test case name]
+- **Given**: [precondition]
+- **When**: [action]
+- **Then**: [expected result]
+- **Priority**: P1/P2/P3
+
+## Regression Checklist
+- [ ] [Feature 1 không bị ảnh hưởng]
+- [ ] [Feature 2 không bị ảnh hưởng]
+
+## Security Checklist (nếu applicable)
+- [ ] Input validation
+- [ ] Auth/authz checks
+- [ ] No data exposure
+
+## Performance Checklist (nếu applicable)
+- [ ] Response time acceptable
+- [ ] No N+1 queries introduced
+```
+
+### QC không có?
+
+- Developer tự execute test plan (nếu có) hoặc manual verification
+- Layer 4 QA sign-off skip — nhưng automated gates (Layer 4a) vẫn chạy
+- Risk cao hơn về undiscovered bugs
+
+---
+
+## Product Manager (`pm`)
+
+**Trách nhiệm chính**: Progress visibility, metrics, sprint planning
+
+### Phases PM Owns
+
+| Phase | Responsibility |
+|-------|---------------|
+| Initialize | Sprint planning, priority |
+| Close | Sprint review, velocity tracking |
+| Standalone: Reports | Dashboard generation |
+
+### PM View
+
+PM không cần đọc code — PM đọc:
+- Progress files (status per subtask)
+- Dashboard reports (velocity, metrics)
+- Sprint review summaries
+
+### Dashboard Metrics
+
+| Metric | Source | Update frequency |
+|--------|--------|-----------------|
+| Tasks: done/in-progress/blocked | Progress files | Real-time |
+| Velocity | Closed tasks per sprint | Per sprint |
+| Estimate accuracy | Estimate vs actual | Per task |
+| DORA: deployment frequency | Git history | Per release |
+| DORA: lead time | Task start → deploy | Per release |
+
+---
+
+## Multi-Role Workflow
+
+Full team workflow (tất cả roles):
+
+```
+BA: /dw:requirements     → requirements doc + user stories
+     ↓
+TL: /dw:arch-review      → architecture decision + approve
+     ↓
+Dev: /dw:task-init       → task docs
+Dev: /dw:research        → codebase analysis
+Dev+QC: /dw:plan         → dev plan + test plan (parallel)
+     ↓
+TL approve plan
+     ↓
+Dev: /dw:execute         → TDD implementation, commits
+     ↓
+TL: /dw:review           → architecture + code review
+     ↓
+QC: manual/auto testing  → Layer 4 verification
+     ↓
+Dev: /dw:commit          → pre-commit gates
+     ↓
+PM: /dw:dashboard        → visibility, metrics
+```
+
+Không phải mọi task cần full chain. `default_depth` + available roles quyết định.
+
+---
+
+## Role-Depth Matrix
+
+| Role | Quick | Standard | Thorough |
+|------|-------|----------|----------|
+| dev | required | required | required |
+| techlead | not needed | arch decisions only | full review + approval |
+| ba | not needed | requirements check | full requirements |
+| qc | not needed | not needed | full test plan + sign-off |
+| pm | not needed | optional | dashboard |

package/MIGRATION-v1.3.md

@@ -1,8 +1,8 @@
 # Migration Guide — dw-kit v1.2.x → v1.3
 
-**Target version:** 1.3.0
-**Ship date:** 2026-05-12 (target)
-**Status:** In Progress
+**Current version:** 1.3.4
+**Patch chain:** 1.3.0 → 1.3.1 (task-init + retroactive emit v2) → 1.3.2 (task-doc health metric) → 1.3.3 (writer skills v1/v2 compat + docs cleanup) → 1.3.4 (/dw:plan Quick Debate)
+**Status:** Shipped
 
 This guide documents all user-visible changes in v1.3. v1.3 is **fully backward compatible** with v1.2.x — existing projects continue to work. New features are opt-in.
 
@@ -17,7 +17,8 @@ This guide documents all user-visible changes in v1.3. v1.3 is **fully backward
 | ACTIVE index | `.dw/tasks/ACTIVE.md` auto-generated | New feature |
 | Telemetry | Local-only metrics in `.dw/metrics/events.jsonl` | Opt-out via `DW_NO_TELEMETRY=1` |
 | Solo preset | `dw init --preset solo` available | New option |
-| Skill naming | `/dw-*` may be renamed to `/dw:*` (pending harness verification) | **Potentially breaking** |
+| Skill naming | `/dw-*` renamed to `/dw:*` (verified working in Claude CLI) | **Breaking** — update custom prompts |
+| `/dw:plan` debate | Quick Debate (red/blue self-critique) integrated — depth-driven | v1.3.4 opt-in for standard, default for thorough |
 | Archive | 8 Done tasks moved to `.dw/tasks/archive/` in dw-kit repo itself | No user impact |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-kit",
-  "version": "1.3.0",
+  "version": "1.3.4",
   "description": "AI development workflow toolkit — structured, quality-assured, team-ready. From requirements to dashboard.",
   "type": "module",
   "bin": {

package/src/commands/metrics.mjs

@@ -1,5 +1,5 @@
 import { readEvents, summarize } from '../lib/telemetry.mjs';
-import { analyze, THRESHOLDS } from '../lib/cut-analysis.mjs';
+import { analyze, analyzeTaskDocs, THRESHOLDS, TASK_DOC_THRESHOLDS } from '../lib/cut-analysis.mjs';
 import { banner, log, info, warn, ok, err } from '../lib/ui.mjs';
 import chalk from 'chalk';
 
@@ -162,4 +162,24 @@ function cutAnalysisReport(opts) {
   log(`  Hook:  avg_latency > ${THRESHOLDS.hook.maxAvgLatencyMs}ms OR fires/session > ${THRESHOLDS.hook.maxFiresPerSession}`);
   log('');
   info('Caveat: "devs" proxied by unique session hashes — undercounts real headcount.');
+
+  // Task doc health — invalidation trigger for 3→2 file consolidation (ADR-0001)
+  const td = analyzeTaskDocs(process.cwd());
+  if (td && td.totalTasks > 0) {
+    log('');
+    log(chalk.bold('Task Doc Health (ADR-0001 invalidation signal for 3→2 consolidation)'));
+    log(`  Tasks total: ${td.totalTasks}  (v2=${td.v2Count}, v1=${td.v1Count})`);
+    log(`  tracking.md lines: avg=${td.avgTrackingLines}  max=${td.maxTrackingLines}`);
+    log(`  Tasks with ≥3 md files: ${td.extraFilesCount} (${td.extraFilesPct}%)`);
+    if (td.triggers.length === 0) {
+      ok('No task-doc invalidation triggers fired — 3→2 consolidation holding.');
+    } else {
+      for (const t of td.triggers) {
+        err(t);
+      }
+    }
+    log('');
+    info('Task doc thresholds:');
+    log(`  avg_tracking_lines > ${TASK_DOC_THRESHOLDS.trackingLinesWarn}  OR  pct_tasks_with_3plus_files > ${TASK_DOC_THRESHOLDS.extraFilesPctWarn}%`);
+  }
 }

package/src/lib/cut-analysis.mjs

@@ -1,8 +1,17 @@
 // Cut Criteria Matrix — implements ADR-0001 v1.4 decision gate.
 // Consumes telemetry events, emits cut candidates with evidence.
 
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
+// Task doc thresholds — invalidation triggers for 3→2 file consolidation (ADR-0001)
+export const TASK_DOC_THRESHOLDS = {
+  trackingLinesWarn: 400,   // avg tracking.md lines → reopen 3→2 decision
+  extraFilesPctWarn: 30,    // % tasks with ≥3 md files → tasks re-growing structure
+};
+
 // Never-cut: skills that are the workflow's load-bearing verbs.
 export const CRITICAL_SKILLS = new Set([
   'dw:flow', 'dw:task-init', 'dw:commit', 'dw:handoff',
@@ -133,6 +142,76 @@ function evaluateHook(name, events, totalSessions) {
   return { name, type: 'hook', qualify, stats: s, reasons };
 }
 
+export function analyzeTaskDocs(rootDir = process.cwd()) {
+  const tasksDir = join(rootDir, '.dw', 'tasks');
+  if (!existsSync(tasksDir)) return null;
+
+  const entries = readdirSync(tasksDir).filter((name) => {
+    if (name === 'archive' || name === 'ACTIVE.md') return false;
+    try {
+      return statSync(join(tasksDir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+
+  const tasks = [];
+  for (const name of entries) {
+    const dir = join(tasksDir, name);
+    let mdFiles;
+    try {
+      mdFiles = readdirSync(dir).filter((f) => f.endsWith('.md'));
+    } catch {
+      continue;
+    }
+    const hasSpec = mdFiles.includes('spec.md');
+    const hasTracking = mdFiles.includes('tracking.md');
+    const format = hasSpec && hasTracking ? 'v2' : mdFiles.some((f) => f.endsWith('-progress.md')) ? 'v1' : 'unknown';
+
+    let trackingLines = 0;
+    if (hasTracking) {
+      try {
+        trackingLines = readFileSync(join(dir, 'tracking.md'), 'utf8').split('\n').length;
+      } catch {
+        /* skip */
+      }
+    }
+
+    tasks.push({ name, format, mdFileCount: mdFiles.length, trackingLines });
+  }
+
+  const v2 = tasks.filter((t) => t.format === 'v2');
+  const avgTrackingLines =
+    v2.length > 0 ? Math.round(v2.reduce((s, t) => s + t.trackingLines, 0) / v2.length) : 0;
+  const maxTrackingLines = v2.length > 0 ? Math.max(...v2.map((t) => t.trackingLines)) : 0;
+  const extraFiles = tasks.filter((t) => t.mdFileCount >= 3);
+  const extraFilesPct = tasks.length > 0 ? Math.round((extraFiles.length / tasks.length) * 100) : 0;
+
+  const triggers = [];
+  if (avgTrackingLines > TASK_DOC_THRESHOLDS.trackingLinesWarn) {
+    triggers.push(
+      `avg_tracking_lines=${avgTrackingLines} > ${TASK_DOC_THRESHOLDS.trackingLinesWarn} — tracking.md phình → reopen 3→2 decision (ADR-0001)`
+    );
+  }
+  if (extraFilesPct > TASK_DOC_THRESHOLDS.extraFilesPctWarn) {
+    triggers.push(
+      `${extraFilesPct}% tasks have ≥3 md files > ${TASK_DOC_THRESHOLDS.extraFilesPctWarn}% — structure re-growing → reopen 3→2 decision (ADR-0001)`
+    );
+  }
+
+  return {
+    totalTasks: tasks.length,
+    v2Count: v2.length,
+    v1Count: tasks.filter((t) => t.format === 'v1').length,
+    avgTrackingLines,
+    maxTrackingLines,
+    extraFilesCount: extraFiles.length,
+    extraFilesPct,
+    triggers,
+    tasks,
+  };
+}
+
 export function analyze(events) {
   const totalSessions = uniqueSessions(events);
   const totalDays = coverageDays(events);