dw-kit 1.2.0 → 1.3.0

package/.dw/core/PILLARS.md

@@ -0,0 +1,122 @@
+# dw-kit v2.0 — 5 Pillar Architecture
+
+dw-kit v2.0 positions itself as a **Context-First SDLC Governance Layer** — not a prescriptive workflow engine. AI drives execution; dw-kit provides guardrails, context, and decision trail.
+
+**Framing inversion:** `prescriptive workflow → descriptive governance`. Moat is organizational memory compounding over time — something IDE tools (Cursor, Copilot) structurally cannot own because they are session-scoped.
+
+---
+
+## Pillar 1: GUARDS — Block unsafe actions
+
+**Role:** Non-negotiable safety boundaries. Enforced by hooks, zero discretion.
+
+**Components:**
+- `.claude/hooks/privacy-block.sh` — Prevent reading `.env*`, `credentials*`, `*.pem`, key files
+- `.claude/hooks/pre-commit-gate.sh` — Quality checks + sensitive data scan before commits
+
+**Obsolescence test:** AI gets smarter → safety becomes MORE important (velocity × risk). These hooks never obsolete.
+
+**Team impact:** Prevents accidents at individual dev level, reduces incident count team-wide.
+
+---
+
+## Pillar 2: SURFACES — Make state visible
+
+**Role:** Shared team context. Human and AI both read.
+
+**Components:**
+- `.dw/tasks/ACTIVE.md` — Auto-generated index of active tasks (TechLead cat to see team state)
+- `.dw/context/project-map.md` — Module structure and boundaries
+- `.dw/context/modules/*.md` — Per-module documentation
+- `CLAUDE.md` + `.claude/rules/dw.md` — Auto-injected conventions
+
+**Obsolescence test:** AI gets smarter → teams coordinate more ambitiously → surfaces become MORE load-bearing.
+
+**Team impact:** New dev onboards from surfaces alone. TechLead audits without asking devs "what are you doing?"
+
+---
+
+## Pillar 3: RECORDS — Capture decisions
+
+**Role:** Organizational memory. The WHY behind architectural choices.
+
+**Components:**
+- `.dw/decisions/{NNNN}-{title}.md` — ADRs with structured YAML header
+- `/dw:decision` skill — Interactive ADR wizard
+- Status tracking: `Proposed | Accepted | Deprecated | Superseded by ADR-{NNNN}`
+
+**Obsolescence test:** AI gets smarter → needs WHY context to avoid technically-correct but strategically-wrong decisions. ADRs become MORE valuable.
+
+**Team impact:** Replaces scattered Slack threads. 6-month-old devs find decision trail. New hires understand architecture fast.
+
+**Unique moat:** IDE tools (Cursor, Copilot) structurally can't own this — they're session-scoped, ADRs are cross-session artifacts.
+
+---
+
+## Pillar 4: BRIDGES — Connect across sessions
+
+**Role:** Continuity over time. Handle the "long chat → no handoff → team lost context" problem.
+
+**Components:**
+- `.dw/tasks/{task}/tracking.md` — Mutable progress log with friction journal
+- Stop hook auto-handoff — Appends session summary to tracking.md on uncommitted changes
+- (v2.0+) Living docs detection — Flag when code diverges from docs
+
+**Obsolescence test:** AI sessions remain ephemeral regardless of capability. Bridges always needed.
+
+**Team impact:** Pick-up-where-left-off works across devs and across sessions. TechLead sees real velocity from actual logs, not status meeting summaries.
+
+---
+
+## Pillar 5: TUNES — Behavioral knobs
+
+**Role:** Team/solo customization. Governs how Pillars 1-4 behave.
+
+**Components:**
+- `.dw/config/dw.config.yml` — Master config (depth, roles, flags)
+- `.dw/config/dw.config.local.yml` — Machine-specific override (gitignored)
+- Presets: `solo` · `team` · `enterprise`
+- Depth routing: `quick` · `standard` · `thorough`
+- Role system: `dev` · `techlead` · `ba` · `qc` · `pm`
+
+**Obsolescence test:** Team size and preferences always vary. Config always needed.
+
+**Team impact:** Same dw-kit serves vibe coder (preset solo) and enterprise team (preset enterprise) with same core.
+
+---
+
+## Pillar Cross-References
+
+| Question | Answer location |
+|----------|----------------|
+| "Is this safe to do?" | Pillar 1 (Guards) — hooks block |
+| "What's everyone working on?" | Pillar 2 (Surfaces) — ACTIVE.md |
+| "Why did we choose X?" | Pillar 3 (Records) — ADRs |
+| "Where were we yesterday?" | Pillar 4 (Bridges) — tracking.md |
+| "How does our team work?" | Pillar 5 (Tunes) — config + presets |
+
+## Design Principles
+
+1. **Descriptive, not prescriptive** — AI chooses approach; dw-kit supplies context + safety
+2. **Obsolescence-aware** — Every feature passes "more valuable if AI smarter?" test
+3. **Dual audience** — Solo + team from same core, different defaults
+4. **Data-driven evolution** — Telemetry guides cut decisions, not gut-feel
+5. **Escape hatches** — `--no-dw`, `legacy_features: true`, `DW_NO_TELEMETRY=1`
+
+## Future: Pillar 6 — JANITORS (deferred to post-v2.0)
+
+**Status:** Draft, deferred — see `.dw/decisions/0003-pillar-6-janitors.md`
+
+**Role:** Reactive cleanup of AI-generated waste. Current 5 pillars are *preventive* (govern what goes in); Janitors governs *what stays*.
+
+**Rationale:** When 99% of code is AI-generated, prevention alone cannot scale. Inspired by urban waste management — cities use multi-tier systems (sort → collect → recycle → regulate), not just "don't litter."
+
+**Revisit:** After v2.0 GA (post 2026-08-15), based on real-world friction data.
+
+## Versioning
+
+- **v1.3** — Foundation (new format, scaffolding, telemetry)
+- **v1.4** — Data-driven cuts based on telemetry evidence
+- **v2.0** — Unified release with full 5-pillar integration
+- **v2.1+** — Advanced features (auto-handoff LLM, cross-repo, dashboard UI)
+- **v2.2+** — Janitors pillar (if validated by v2.0 friction data)

package/.dw/core/templates/v2/spec.md

@@ -0,0 +1,68 @@
+---
+task_id: {task-name}
+created: {YYYY-MM-DD}
+status: Draft | Approved | In Progress | Done
+owner: {name}
+depth: quick | standard | thorough
+related_adr: {ADR-XXXX | none}
+target_ship: {YYYY-MM-DD | none}
+---
+
+# Spec: {Task Title}
+
+## Intent
+
+{1-2 paragraphs — what and why. No background padding.}
+
+## Why Now
+
+{Forcing function. Deadline, incident, dependency, opportunity.}
+
+## Scope
+
+### In Scope
+
+**ST-1: {Subtask name}**
+- {Concrete action}
+- Acceptance: {verifiable criterion}
+- Effort: {hours or days}
+
+**ST-2: ...**
+
+### Out of Scope (Won't Contain)
+
+- {Explicit exclusions — prevents scope creep}
+
+## Timeline (if ship target)
+
+| Phase | Duration | Target Date |
+|-------|----------|-------------|
+| ... | ... | ... |
+
+## Risks & Mitigations
+
+| Risk | Severity | Mitigation |
+|------|----------|-----------|
+| ... | H/M/L | ... |
+
+## Success Criteria
+
+Measurable outcomes (not vibes):
+
+- [ ] {Numeric threshold, e.g., "latency <100ms p95"}
+- [ ] {Binary gate, e.g., "passes smoke test"}
+
+## Dependencies
+
+- {Upstream blockers}
+- {External systems}
+
+## Known Unknowns (admitted gaps)
+
+- {Question 1 — to resolve during execution}
+
+## Acceptance (Task Complete When)
+
+- [ ] {High-level criteria, e.g., "shipped to prod"}
+- [ ] {Documentation updated}
+- [ ] {Migration note added if breaking}

package/.dw/core/templates/v2/tracking.md

@@ -0,0 +1,62 @@
+---
+task_id: {task-name}
+started: {YYYY-MM-DD}
+last_updated: {YYYY-MM-DD}
+status: Not Started | In Progress | Blocked | Done
+current_phase: {phase name}
+blockers: {none | description}
+---
+
+# Tracking: {Task Title}
+
+## Status Snapshot
+
+**Phase:** {current}
+**Next milestone:** {date or deliverable}
+
+## Subtask Progress
+
+| # | Subtask | Status | Date | Notes |
+|---|---------|--------|------|-------|
+| ST-1 | ... | ⬜ Pending | — | |
+
+Status legend: ⬜ Pending · 🟡 In Progress · ✅ Done · 🔴 Blocked · ⏸ Paused
+
+## Changelog
+
+### {YYYY-MM-DD} — {Session/commit title}
+
+**Actions taken:**
+- ...
+
+**Decisions made:**
+- ...
+
+**Pain points logged:**
+- ...
+
+## Handoff Notes
+
+**For next session (or next agent):**
+
+- **Read first:** {files}
+- **Current state:** {phase, subtask}
+- **Don't do:** {anti-patterns}
+- **Watch out:** {risks, gotchas}
+
+## Friction Journal
+
+Every time current system causes friction while working, append here:
+
+| Date | Friction | Component | Proposed fix |
+|------|----------|-----------|-------------|
+| ... | ... | ... | ... |
+
+## Agent Debate Log (optional, for thorough depth)
+
+### {Date} — {Context}
+
+**Red-bot findings:** ...
+**Blue-bot suggestions:** ...
+**Incorporated:** ...
+**Deferred:** ...

package/.dw/core/v14-evaluation-protocol.md

@@ -0,0 +1,118 @@
+# v1.4 Evaluation Protocol
+
+> How to decide what to cut in v1.4, based on telemetry evidence from v1.3 in production.
+> Anchored to [ADR-0001](../decisions/0001-v2-pragmatic-lean.md) Cut Criteria Matrix.
+
+---
+
+## Purpose
+
+Prove dw-kit can **cut itself** when data says so — validates the "not a framework cage" principle and grows organizational memory via ADRs.
+
+## Timeline
+
+| Phase | Dates | Activity |
+|-------|-------|----------|
+| Prep | Week 0 | v1.3.0 published + installed on all teams |
+| Collect | Week 1–4 | Normal use; telemetry accumulates locally per dev |
+| Aggregate | End of Week 4 | Each dev exports `.dw/metrics/events.jsonl`, TechLead merges |
+| Analyze | Week 5 (day 1–2) | Run `dw metrics cut-analysis` on merged data |
+| Survey | Week 5 (day 2–3) | Team survey on flagged items (qualitative check) |
+| Decide | Week 5 (day 4) | ADR per confirmed cut |
+| Execute | Week 5 (day 5) | Remove files + settings + write MIGRATION-v1.4.md |
+| Ship | Week 6 | v1.4.0 release |
+
+## Evaluation Steps
+
+### 1. Collect (end of week 4)
+
+Each dev runs:
+```bash
+cp .dw/metrics/events.jsonl ~/dw-metrics-<dev-name>.jsonl
+```
+
+TechLead merges into a single evaluation workspace:
+```bash
+mkdir -p ~/dw-v14-eval/.dw/metrics
+cat ~/dw-metrics-*.jsonl > ~/dw-v14-eval/.dw/metrics/events.jsonl
+```
+
+### 2. Analyze
+
+```bash
+cd ~/dw-v14-eval
+dw metrics cut-analysis --since 2026-05-12
+```
+
+Output flags skills/hooks qualifying per [ADR-0001 Cut Criteria](../decisions/0001-v2-pragmatic-lean.md):
+
+- **Skill**: `uses/week/dev < 5` AND `devs ≥ 5` AND `coverage_days ≥ 21`
+- **Hook**: `avg_latency > 500ms` OR `fires/session > 10`
+
+**Caveat**: session-hash proxy undercounts real headcount. If flagged count is borderline → lean keep.
+
+### 3. Survey (qualitative gate)
+
+For each flagged item, ask the team:
+
+1. Did you use `/dw:{name}` in the last 4 weeks?
+2. If removed, would you miss it? (1=no / 5=yes)
+3. Any use case that telemetry wouldn't capture?
+
+**Cut only if**: telemetry flags AND <30% of devs answer ≥4 on question 2.
+
+### 4. Decide (per cut)
+
+For each confirmed cut:
+
+```bash
+/dw:decision "Remove {hook-or-skill-name}"
+```
+
+ADR must include:
+- Evidence: uses/week/dev, fires/session, latency (paste from `cut-analysis`)
+- Survey result
+- Rollback plan (git revert SHA + how to reinstate)
+- Supersedes line if any prior ADR protected this item
+
+### 5. Execute
+
+For each cut:
+- Delete `.claude/hooks/{name}.sh` or `.claude/skills/dw-{name}/`
+- Remove entry from `.claude/settings.json` hooks block
+- Remove from `package.json#files` if listed
+- Add row to `MIGRATION-v1.4.md` with "What changed / Why / Rollback"
+
+### 6. Ship
+
+- Version bump: `1.3.x → 1.4.0`
+- Split commits: one per cut + one for MIGRATION doc
+- `npm publish`
+- Announce to teams with link to MIGRATION-v1.4.md and relevant ADRs
+
+## Protected Items (never cut in v1.4)
+
+**Critical-path skills** (workflow load-bearing):
+`dw:flow`, `dw:task-init`, `dw:commit`, `dw:handoff`, `dw:execute`, `dw:plan`, `dw:research`, `dw:thinking`, `dw:review`, `dw:debug`, `dw:decision`
+
+**Per-project skills** (low cadence is expected):
+`dw:onboard`, `dw:retroactive`, `dw:config-init`, `dw:upgrade`, `dw:rollback`
+
+If any flagged by matrix → override is "keep" with a 1-line note in the analysis report.
+
+## Failure Modes
+
+| Failure | Mitigation |
+|---------|------------|
+| <21 days coverage | Postpone v1.4, extend collection window |
+| <5 unique sessions | Insufficient data; wait or onboard more devs to v1.3 |
+| Data merge error | Each jsonl is self-contained; re-merge from backups |
+| Team disagrees with data | Qualitative survey overrides; document in ADR |
+| Post-cut regret | Execute rollback plan from ADR; issue v1.4.1 patch |
+
+## Success Signals
+
+- ≥2 ADRs written (shows data-driven cuts happened, not just "feels right")
+- Auto-loaded rules bytes ↓ ≥30% from v1.3 baseline ([baseline.md](../tasks/dw-kit-v2-lean-optimization/baseline.md))
+- Team NPS for dw-kit ≥ v1.3 level (cuts didn't hurt workflow)
+- Zero rollback in first 2 weeks post-v1.4

package/CLAUDE.md

@@ -1,39 +1,42 @@
-# dw-kit (repo)
-
-Workflow toolkit codebase. dw rules live in `.claude/rules/` — auto-loaded by Claude Code.
-
-Config: `.dw/config/dw.config.yml`
-
----
-
-## Tech Stack
-
-- Runtime: Node.js ≥18, ESM (`.mjs`)
-- CLI: `commander` · UI: `enquirer`, `chalk` · Config: `js-yaml`, `ajv`
-- Tests: `node src/smoke-test.mjs`
-
-## Repo Structure
-
-```
-bin/          CLI entrypoint
-src/
-  commands/   CLI subcommands (init, upgrade, validate, ...)
-  lib/        Shared utilities (config, copy, ui, ...)
-.claude/
-  hooks/      Bash hooks — python3-free, node only (Windows compat)
-  rules/      dw-core.md + dw-skills.md (auto-loaded by Claude Code)
-  skills/     Slash command definitions
-  templates/  Agent report template
-.dw/
-  core/       WORKFLOW.md, THINKING.md, QUALITY.md, ROLES.md
-  config/     dw.config.yml for this repo
-  tasks/      Active task docs
-```
-
-## Dev Notes
-
-- All source ESM (`import`/`export`) — no CommonJS
-- `TOOLKIT_ROOT` resolved from `import.meta.url` in each command
-- Hooks use `node` for JSON parsing (not python3 — Windows compat)
-- Skills `dw-kit-evolve` and `dw-kit-audit` are maintainer-only — excluded from npm package
-- Published package files declared explicitly in `package.json#files`
+# dw-kit (repo)
+
+Workflow toolkit codebase. Rules live in `.claude/rules/` (auto-loaded).
+
+**v2.0 direction:** Context-First SDLC Governance Layer (5 pillars — see `.dw/core/PILLARS.md`)
+**Current:** v1.4.0-dev · v1.3.0 ready to ship · ADR-0001 active
+
+---
+
+## Tech Stack
+
+- Runtime: Node.js ≥18, ESM (`.mjs`)
+- CLI: `commander` · UI: `enquirer`, `chalk` · Config: `js-yaml`, `ajv`
+- Tests: `node src/smoke-test.mjs`
+
+## Repo Structure
+
+```
+bin/          CLI entrypoint
+src/
+  commands/   CLI subcommands (init, upgrade, dashboard, metrics, ...)
+  lib/        Shared utilities (config, telemetry, active-index, ...)
+.claude/
+  hooks/      Bash hooks (Guards pillar)
+  rules/      dw.md (consolidated) + code-style + commit-standards
+  skills/     Slash commands with dw:* namespace
+.dw/
+  core/       WORKFLOW · THINKING · QUALITY · ROLES · PILLARS · templates/
+  decisions/  ADRs (Records pillar)
+  tasks/      Active + archive/ (Bridges pillar — via tracking.md)
+  metrics/    Local telemetry (events.jsonl)
+  config/     dw.config.yml
+```
+
+## Dev Notes
+
+- All source ESM — no CommonJS
+- `TOOLKIT_ROOT` resolved from `import.meta.url` in each command
+- Hooks python3-free (node only — Windows compat)
+- `dw-kit-evolve` + `dw-kit-audit` are maintainer-only — excluded from npm package
+- Published package files declared explicitly in `package.json#files`
+- Telemetry local-only, `DW_NO_TELEMETRY=1` to disable

package/MIGRATION-v1.3.md

@@ -0,0 +1,201 @@
+# Migration Guide — dw-kit v1.2.x → v1.3
+
+**Target version:** 1.3.0
+**Ship date:** 2026-05-12 (target)
+**Status:** In Progress
+
+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.
+
+---
+
+## At a Glance
+
+| Area | Change | Impact |
+|------|--------|--------|
+| Task docs | New 2-file format (`spec.md` + `tracking.md`) available; 3-file legacy still works | Opt-in |
+| Decisions layer | New `.dw/decisions/` directory for ADRs | New feature |
+| 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** |
+| Archive | 8 Done tasks moved to `.dw/tasks/archive/` in dw-kit repo itself | No user impact |
+
+---
+
+## New Features (Opt-In)
+
+### 1. Task Docs v2 Format
+
+**Before (v1.x):** 3 files per task
+```
+.dw/tasks/{name}/
+├── {name}-context.md
+├── {name}-plan.md
+└── {name}-progress.md
+```
+
+**Now (v1.3):** Simpler 2-file default
+```
+.dw/tasks/{name}/
+├── spec.md       # Intent + plan merged
+└── tracking.md   # Progress + handoff
+```
+
+Templates at `.dw/core/templates/v2/spec.md` and `.dw/core/templates/v2/tracking.md`.
+
+**Migration:** Existing 3-file tasks continue to work. For new tasks, copy from new templates.
+
+### 2. Decisions Layer (ADRs)
+
+New `.dw/decisions/` directory for Architecture Decision Records.
+
+- Template: `.dw/decisions/_template.md`
+- Format: YAML frontmatter + TL;DR + Context + Options + Decision + Consequences
+- Example: `.dw/decisions/0001-v2-pragmatic-lean.md` (dw-kit's own v2 direction)
+
+**Why:** Capture *why* decisions were made, not just *what*. Complements code and git history.
+
+### 3. ACTIVE.md Auto-Index
+
+`.dw/tasks/ACTIVE.md` auto-generated with 1 line per active task. Format:
+```
+- `{task-name}` · {status} · {last-updated} · {blockers}
+```
+
+Excludes `.dw/tasks/archive/`. TechLead can `cat .dw/tasks/ACTIVE.md` to see team state at a glance.
+
+**New CLI:** `dw active` to regenerate.
+
+### 4. Local Telemetry
+
+**Privacy-first design:**
+- **Local-only by default.** Zero network calls.
+- Schema: append-only JSONL at `.dw/metrics/events.jsonl`
+- Events logged: skill invocations, hook fires, task lifecycle
+- Inspect: `dw metrics show`
+- Opt-out: `DW_NO_TELEMETRY=1` environment variable
+
+**What's collected:** timestamps, event type, skill/hook name, session hash, depth, latency. **Not collected:** file contents, prompts, personal data.
+
+**Internal team policy (for 2 internal teams only):** Mandatory for v1.4 cut decisions. Can still set `DW_NO_TELEMETRY=1` on specific machine.
+
+### 5. Solo Preset
+
+**New:** `dw init --preset solo` — optimized for solo developers / vibe coders.
+
+**Enabled by default:** `privacy-block`, `pre-commit-gate` hooks only (safety-critical).
+**Disabled:** Task docs, session-init, scout-block, post-write, progress-ping, telemetry.
+
+Target: working setup in <30 seconds, zero friction.
+
+---
+
+## Potentially Breaking (Pending Verification)
+
+### Skill Naming: `/dw-{name}` → `/dw:{name}`
+
+**Status:** Pending Claude Code harness verification.
+
+**Rationale:** Colon creates clear namespace separator, matches industry conventions (`git:log`, `npm:run`).
+
+**Change:** SKILL.md frontmatter `name:` field. Directory names unchanged (`:` illegal on Windows filesystems).
+
+**Before:** `name: dw-thinking` → invoke `/dw-thinking`
+**After:** `name: dw:thinking` → invoke `/dw:thinking`
+
+**Mapping table (if applied):**
+
+| v1.x | v1.3+ |
+|------|-------|
+| `/dw-flow` | `/dw:flow` |
+| `/dw-task-init` | `/dw:task-init` |
+| `/dw-research` | `/dw:research` |
+| `/dw-plan` | `/dw:plan` |
+| `/dw-execute` | `/dw:execute` |
+| `/dw-commit` | `/dw:commit` |
+| `/dw-handoff` | `/dw:handoff` |
+| `/dw-debug` | `/dw:debug` |
+| `/dw-review` | `/dw:review` |
+| `/dw-thinking` | `/dw:thinking` |
+| `/dw-prompt` | `/dw:prompt` |
+| `/dw-docs-update` | `/dw:docs-update` |
+| `/dw-requirements` | `/dw:requirements` |
+| `/dw-test-plan` | `/dw:test-plan` |
+| `/dw-arch-review` | `/dw:arch-review` |
+| `/dw-dashboard` | `/dw:dashboard` |
+| `/dw-sprint-review` | `/dw:sprint-review` |
+| `/dw-estimate` | `/dw:estimate` |
+| `/dw-log-work` | `/dw:log-work` |
+| `/dw-onboard` | `/dw:onboard` |
+| `/dw-retroactive` | `/dw:retroactive` |
+| `/dw-config-init` | `/dw:config-init` |
+| `/dw-config-validate` | `/dw:config-validate` |
+| `/dw-upgrade` | `/dw:upgrade` |
+| `/dw-rollback` | `/dw:rollback` |
+| `/dw-archive` | `/dw:archive` |
+| `/dw-kit-report` | `/dw:kit-report` |
+| `/dw-kit-evolve` | `/dw:kit-evolve` |
+| `/dw-kit-audit` | `/dw:kit-audit` |
+
+See `ADR-0002` for full rationale.
+
+---
+
+## Deprecations (No Removal in v1.3)
+
+These are marked for removal in v1.4+ based on telemetry evidence:
+
+| Feature | Replacement | Removal Target |
+|---------|-------------|----------------|
+| `scout-block.sh` hook | Permission allowlist in settings.json | v1.4 |
+| `post-write.sh` hook | None (low-value reminder) | v1.4 |
+| `progress-ping.sh` hook | `tracking.md` manual + Stop hook | v1.4 |
+| `session-init.sh` hook inject context | `.dw/tasks/ACTIVE.md` auto-loaded | v1.4 |
+| Split rules files (5 files) | Consolidated 1-2 files | v1.4 |
+| 3-file task docs mandatory | 2-file default (legacy still works) | v2.0 |
+| Prescriptive `/dw-research`, `/dw-plan`, `/dw-execute` | Context injector pattern | v2.0 |
+
+**Escape hatch:** Set `legacy_features: true` in `.dw/config/dw.config.yml` to keep v1.x behavior through v2.0.
+
+---
+
+## Upgrade Steps
+
+### Automated
+```bash
+npx dw-kit upgrade
+```
+
+This will:
+1. Merge new templates into `.dw/core/templates/v2/`
+2. Create `.dw/decisions/` if missing
+3. Generate initial `.dw/tasks/ACTIVE.md`
+4. Add telemetry module (local-only)
+5. NOT touch existing task docs or skills
+
+### Manual Checks After Upgrade
+
+- [ ] Verify `.dw/tasks/ACTIVE.md` generated correctly
+- [ ] Read new `ADR-0001` to understand v2.0 direction
+- [ ] Optional: set `DW_NO_TELEMETRY=1` if you want to opt out
+- [ ] Optional: try `dw init --preset solo` for new projects
+
+### Rollback
+```bash
+npm install -g dw-kit@1.2.1
+```
+Your existing `.dw/` data remains compatible with v1.2.1.
+
+---
+
+## Known Issues
+
+- Skill naming (`/dw:*`) pending Claude Code harness verification. If harness rejects `:` in skill `name:` field, rename will be reverted in v1.3.1.
+
+---
+
+## Feedback
+
+- Internal teams: Slack channel `#dw-kit`
+- Open source: https://github.com/dv-workflow/dv-workflow/issues
+- Use `/dw-kit-report` (or `/dw:kit-report` after rename) to file structured feedback.