dw-kit 1.3.6 → 1.6.0-rc.1

package/MIGRATION-v1.5.md

@@ -0,0 +1,330 @@
+# Migration Guide — dw-kit v1.3/v1.4 → v1.5
+
+**Status:** In active development (per ADR-0008)
+**Breaking change:** Task docs format default switches from v2 (2-file) to v3 (1-file `task.md`).
+**Backward compat:** v2 + v1 read paths preserved. Migration is opt-in per task via `dw task migrate`.
+
+---
+
+## At a Glance
+
+| Area | Change | Impact |
+|------|--------|--------|
+| Task docs | New v3 single-file `task.md` (replaces v2 `spec.md` + `tracking.md`) | **Default for new tasks** — old tasks read-compat |
+| Frontmatter | JSON-schema validated (ajv) via `.dw/core/schemas/task-frontmatter.schema.json` | Strict on save (per lint) |
+| CLI | New `dw task` family: `show`, `new`, `migrate`, `lint`, `rotate` | New surface |
+| Lint | `dw task lint` default `strict` — blocks drift markers in Section 2, line caps, schema | Opt-out via `task_lint: off` in `dw.config.yml` |
+| Hook | `stop-check` now auto-rotates Section 4 > 400 lines → `timeline-history.md` + nudges `dw task show` | Automatic |
+| Indexer | `active-index.mjs` reads v3 first, falls back to v2 / v1 | Backward compatible |
+| Skills | 7 skills updated for v3 (task-init / execute / handoff / research / plan / decision / retroactive) | Auto-detect format |
+| Migration backups | v2 spec.md / tracking.md preserved as `.v2bak` (gitignored) | Reversible via `--rollback` |
+
+---
+
+## The Drift Problem (Motivation)
+
+Per ADR-0008 evidence:
+
+- `dw-kit-v2-lean-optimization` task accumulated **1081 lines** across `spec.md` (227) + `tracking.md` (615) + ad-hoc `baseline.md` (89) + `execution-log.md` (150) — variance crossed beyond what the v2 template was designed for.
+- Status markers leaked into `spec.md` ("✅ COMPLETED 2026-04-21" inline) while `tracking.md` had its own "Subtask Progress" table → **two sources of truth for the same field**.
+- TechLead reviewer reported "rối, lười đọc" (cluttered, skipped) when reviewing v2 layouts.
+
+v3 fixes structurally:
+
+- **Single source of truth:** `task.md` contains Snapshot + Intent + Tracker + Changelog + Handoff in one file.
+- **No drift surface:** there is no second file to paste status into. Lint enforces "status lives only in Section 3".
+- **Bounded preview:** `timeline.svg` sidecar (when rendered) is fixed composition (~10-20KB) regardless of task lifetime.
+- **Auto-rotation:** Section 4 (Changelog) overflow above 400 lines → `timeline-history.md` via `stop-check` hook.
+
+Trade-off: cross-repo migration of existing v2 tasks. Tooling provided.
+
+---
+
+## New Format — `task.md` v3
+
+```
+.dw/tasks/{name}/
+├── task.md              # canonical SoT (Sections 1-5 + optional 6 Debate)
+└── (free-form supplements — indexer ignores; lint warns on generic names):
+    ├── baseline.md          # benchmark snapshots
+    ├── experiment-{id}.md   # spike notes
+    ├── debate-r{N}.md       # extended adversarial logs
+    └── timeline-history.md  # auto-rotated changelog overflow
+```
+
+**Section structure:**
+
+| # | Section | Purpose | Lint rule |
+|---|---------|---------|-----------|
+| 1 | Snapshot | Always-visible ≤15-line header for fast scan | — |
+| 2 | Intent & Scope | Stable intent, Subtasks list, Out of Scope, Success Criteria, Dependencies, Risk Register | **No status markers** (✅🟡 trigger error); line cap 200 |
+| 3 | Subtask Tracker | Single source of truth for ST status | Status legend required; line cap 80 |
+| 4 | Timeline / Changelog | Reverse-chronological session log | Auto-rotate > 400 lines |
+| 5 | Handoff & Friction | For-next-session + friction journal | — |
+| 6 | Annexes | List of supplementary files | — |
+| 7 | Debate Log (optional) | Thorough-depth red/blue adversarial output | — |
+
+**Frontmatter schema** (`.dw/core/schemas/task-frontmatter.schema.json`):
+
+Required: `task_id`, `created`, `last_updated`, `status`, `owner`, `depth`, `schema_version` (= `v3.0`).
+Optional: `phase`, `related_adr`, `target_ship`, `blockers`.
+`status` enum: Draft | Approved | In Progress | Blocked | Paused | Done.
+`depth` enum: quick | standard | thorough.
+`related_adr` pattern: `ADR-NNNN` or `none`.
+
+`additionalProperties: false` — typo fields rejected (drift prevention).
+
+---
+
+## CLI Reference
+
+### `dw task new <name> [options]`
+
+Scaffold new v3 task from template.
+
+```
+dw task new my-feature --depth standard --title "My feature" --adr ADR-0008
+```
+
+Writes `.dw/tasks/my-feature/task.md` with filled frontmatter + Section skeletons.
+
+### `dw task show [name] [-v]`
+
+ANSI terminal snapshot of Section 1 + Section 3.
+
+```
+dw task show                  # auto-pick most recent v3 task
+dw task show my-feature       # specific task
+dw task show -v               # include Section 1 body
+```
+
+### `dw task lint [name] [-l level]`
+
+Schema validate + drift marker scan + line caps + appendage name check.
+
+```
+dw task lint                  # lint all v3 tasks
+dw task lint my-feature       # single task
+dw task lint -l warn          # downgrade errors to warnings
+DW_NO_TELEMETRY=1 dw task lint  # skip telemetry events
+```
+
+Default level: `strict` (errors → exit 1). Override via `dw.config.yml`:
+
+```yaml
+task:
+  lint: strict   # strict | warn | off
+```
+
+Or legacy flat key:
+```yaml
+task_lint: strict
+```
+
+Solo preset → `off`. Enterprise → `strict`.
+
+### `dw task migrate [name] [flags]`
+
+Migrate v2 `spec.md` + `tracking.md` → v3 `task.md`.
+
+```
+dw task migrate my-task --dry-run   # preview without writing
+dw task migrate my-task --diff       # diff against existing task.md
+dw task migrate my-task              # apply (creates .v2bak backups)
+dw task migrate --all --dry-run      # preview all v2 tasks
+dw task migrate --all                # apply to all v2 tasks
+dw task migrate my-task --rollback   # restore from .v2bak
+dw task migrate my-task --force      # overwrite existing v3
+dw task migrate my-task --remove-v2  # delete spec.md/tracking.md after migration (default keeps them)
+```
+
+**Migration mapping:**
+
+| v2 source | v3 destination |
+|-----------|----------------|
+| `spec.md` Intent + Why Now | Section 2 → Intent + Why Now |
+| `spec.md` Scope → In Scope | Section 2 → Subtasks (status markers stripped) |
+| `spec.md` Out of Scope | Section 2 → Out of Scope |
+| `spec.md` Success Criteria | Section 2 → Success Criteria |
+| `spec.md` Risks & Mitigations | Section 2 → Risk Register |
+| `spec.md` Dependencies | Section 2 → Dependencies |
+| `tracking.md` Status Snapshot | Section 1 |
+| `tracking.md` Subtask Progress | Section 3 Subtask Tracker |
+| `tracking.md` Changelog | Section 4 Timeline/Changelog |
+| `tracking.md` Handoff Notes | Section 5 |
+| `tracking.md` Friction Journal | Section 5 (Friction subsection) |
+| `tracking.md` Agent Debate Log | Section 7 (if present) |
+| Merged frontmatter | v3 frontmatter (status auto-normalized to enum) |
+
+**Status normalization:** v2 freeform status (e.g., "v1.3.0 Verified Ship-Ready (audit passed)") maps to nearest v3 enum value via keyword priority: Blocked > Done > Paused > In Progress > Approved > Draft.
+
+**Backups:** `spec.md` → `spec.md.v2bak`, `tracking.md` → `tracking.md.v2bak`. Both gitignored. Use `--rollback` to restore.
+
+### `dw task rotate [name] [-n] [-q]`
+
+Auto-rotate Section 4 (Timeline/Changelog) > 400 lines into `timeline-history.md`. Keeps last 8 entries in `task.md`. Idempotent. Invoked automatically by `stop-check` hook.
+
+### `dw task render [name] [-n] [-f svg|png|svg,png] [--mermaid-only]`
+
+Render `timeline.svg` sidecar from manifest via `dw-kit-render` sub-package. SVG is bounded composition (status card + Subtask Gantt + status transition strip) ~200-465KB per task. Gitignored by default (opt-in commit cho GitHub inline preview). Falls back to Mermaid Gantt block injection in Section 4 if sub-package absent.
+
+### `dw task view [name] [--no-open]`
+
+Render full interactive HTML preview at `.dw/cache/preview/{task}.html` and open in browser. **Primary surface for human dev orchestrator tracking subtasks.** Self-contained (CSS + JS inlined, no CDN deps). Features:
+
+- **Sticky snapshot card** (always visible): status badge + key meta + blocker banner + progress stats (✅/🟡/🔴/⬜ counts + percentage bar).
+- **Sidebar navigation** with section anchors + search box (filter sections by keyword).
+- **Sections rendered as proper HTML**: headings, tables, code blocks (Mermaid blocks render as text but visible), bullet/numbered lists, blockquotes.
+- **Collapsible H2 sections** (click heading to fold).
+- **Dark/light theme** via `prefers-color-scheme`.
+
+Gitignored output (`.dw/cache/preview/`). Regenerates on each invocation — no caching.
+
+---
+
+## Migration Steps for Existing Projects
+
+### 1. Backup (recommended)
+
+```
+git checkout -b task-migrate-v3
+git status   # confirm clean
+```
+
+### 2. Preview migration
+
+```
+dw task migrate --all --dry-run
+```
+
+Review proposed v3 output. Status normalization, section mapping, and frontmatter merge are shown.
+
+### 3. Apply per-task with diff
+
+```
+dw task migrate task-1 --diff   # if already migrated, show diff vs existing
+dw task migrate task-1          # apply
+dw task lint task-1             # verify clean
+```
+
+Repeat for each task. Or batch:
+
+```
+dw task migrate --all
+dw task lint                    # verify all
+```
+
+### 4. Refresh ACTIVE.md
+
+```
+dw active
+```
+
+### 5. Commit
+
+```
+git add .dw/tasks/
+git commit -m "chore(tasks): migrate v2 spec+tracking to v3 timeline (ADR-0008)"
+```
+
+`.v2bak` files are gitignored — they stay locally for rollback if needed.
+
+### 6. Rollback path (if needed)
+
+```
+dw task migrate task-1 --rollback
+```
+
+Restores v2 files from `.v2bak`, deletes v3 `task.md`. ACTIVE.md falls back to reading `tracking.md`.
+
+---
+
+## Breaking Changes
+
+### 1. `dw active` v3 precedence
+
+If both `task.md` and `tracking.md` exist in a task folder, **v3 wins**. To force v2 read during migration, delete `task.md` temporarily.
+
+### 2. Lint default strict
+
+`dw task lint` exits non-zero on any error (drift markers, schema violations). To run advisory-only:
+
+```yaml
+# .dw/config/dw.config.yml
+task:
+  lint: warn   # or "off"
+```
+
+### 3. Section 2 drift-marker enforcement
+
+Pasting status markers (`✅ COMPLETED 2026-04-21`, `🟡 IN PROGRESS`, `Status: Done`) anywhere in Section 2 → lint error. Status only in Section 3 (Subtask Tracker). Backtick-quoted examples (e.g., discussing drift in docs) are skipped by lint.
+
+### 4. Generic appendage names → warning
+
+Files named `notes.md`, `extra.md`, `wip.md`, etc. in task folders → lint warning. Prefer specific names: `baseline.md`, `experiment-{id}.md`, `debate-r{N}.md`.
+
+---
+
+## SVG Preview (Deferred to v1.6+)
+
+Per ADR-0008 Option H, `task.md` references an inline `timeline.svg` sidecar that GitHub markdown viewer renders inline for human casual preview. The full render pipeline (extends ADR-0007 `dw-kit-render` sub-package) lands in v1.6 telemetry-gated.
+
+For v1.5: the SVG reference is comment-suppressed in templates (`<!-- ![Timeline](./timeline.svg) -->`) so no broken-image icons appear in GitHub PR view. Mermaid Gantt + timeline blocks in Section 4 provide native GitHub-rendered fallback visualization.
+
+When v1.6 ships:
+- `dw task render <name>` produces `timeline.svg` (deterministic XML, ~10-20KB).
+- `stop-check` + `pre-commit` hooks auto-regenerate on session end / commit.
+- Template comment markers around the image ref are removed → inline render activates.
+- Optional `dw task view` opens interactive HTML in browser.
+- Optional `dw task watch` daemon for live preview during pair-with-agent dev.
+
+---
+
+## Telemetry
+
+New events (under `event: 'task'`):
+
+- `task.show.invoke`
+- `task.new`
+- `task.migrate.run` / `task.migrate.rollback`
+- `task.lint.run` / `task.lint.violation`
+- `task.rotate.run`
+
+Inspected via `dw metrics show` (under "Task actions" bucket). Local-only, opt-out via `DW_NO_TELEMETRY=1`.
+
+---
+
+## Skills Updated
+
+7 skills now v3-aware (task.md preferred, v2 + v1 read-compat):
+
+- `/dw:task-init` — defaults to `dw task new`; falls back to template fill.
+- `/dw:execute` — reads task.md Sections 1/2/3; updates Section 3 tracker + Section 4 changelog.
+- `/dw:handoff` — writes to Section 5 (Handoff & Friction).
+- `/dw:research` — appends Research Findings subsection to Section 2.
+- `/dw:plan` — fills Section 2 subsections; promotes status Draft → Approved.
+- `/dw:decision` — cross-links ADR to task.md frontmatter + Changelog.
+- `/dw:retroactive` — generates As-Built task.md from code + git history.
+
+---
+
+## Sunset Plan for v2
+
+Per ADR-0008 Open Items:
+
+- v2 templates at `.dw/core/templates/v2/` remain for legacy read.
+- 60 days post-v1.5 ship: telemetry review `task.format.read` event distribution.
+- If v2 reads < 5% of v3 reads → propose v2 template removal in v1.7.
+- v2 read code path in `active-index.mjs` and skills stays (cheap to maintain, supports archived tasks).
+
+v1 (3-file `context + plan + progress`) read path stays indefinitely (small set of legacy tasks).
+
+---
+
+## References
+
+- ADR-0008: [.dw/decisions/0008-task-docs-format-one-file-timeline.md](.dw/decisions/0008-task-docs-format-one-file-timeline.md) (full debate, 7 rounds)
+- Bootstrap task: [.dw/tasks/task-docs-v3/task.md](.dw/tasks/task-docs-v3/task.md) (dogfooded v3 format)
+- Template: [.dw/core/templates/v3/task.md](.dw/core/templates/v3/task.md)
+- Schema: [.dw/core/schemas/task-frontmatter.schema.json](.dw/core/schemas/task-frontmatter.schema.json)
+- ADR-0007 (render infrastructure to be reused in v1.6): [.dw/decisions/0007-decoupled-review-render-pipeline.md](.dw/decisions/0007-decoupled-review-render-pipeline.md)

package/README.md

@@ -36,6 +36,9 @@ It’s designed for collaboration (Dev / Tech Lead / QA / PM) and keeps work aud
 
 ## Release notes
 
+- **v1.6.0-rc.1 (current)** — **Agent OS Multi-Agent Orchestration** ([ADR-0009](.dw/decisions/0009-agent-os-multi-agent-orchestration.md)): file-based cooperative protocol for Claude Code / Codex / Gemini / human agents to work from same `task.md` without conflict. 6-command CLI `dw agent *` (claim / release / expire / claims / reports / conflicts). Dual ownership model: `subtasks` (semantic) + `write_scope` (filesystem). Lifecycle states + lease (wall+relative) per Round 2. Audit trail via committed `reports/` + `events.jsonl`; claims gitignored ephemeral. Trust = cooperative, post-hoc conflict detection.
+- **v1.5.0 — Task Docs v3** ([ADR-0008](.dw/decisions/0008-task-docs-format-one-file-timeline.md)): single-file `task.md` replaces v2 `spec.md` + `tracking.md` (drift fixed structurally). 8-command CLI `dw task *` (show / new / view / watch / render / lint / migrate / rotate). Lean HTML dashboard for human dev orchestrator (~10KB, scan-in-5-seconds) + bounded SVG sidecar via `dw-kit-render` v0.2. Live preview server with auto-refresh. Migration script with `--dry-run`, `--diff`, `--rollback`. Lint strict-default blocks drift markers. See [`MIGRATION-v1.5.md`](MIGRATION-v1.5.md).
+- **v1.4 (in progress)** — Optional **Review Render Pipeline** ([ADR-0007](.dw/decisions/0007-decoupled-review-render-pipeline.md)): `/dw:review --visual` plus a separate `dw-kit-render` package turn findings into SVG + PNG cards for PR comments / Slack / stakeholders. Pure JS + WASM, universal `npm install`, no system deps. See [`docs/review-renderer.md`](docs/review-renderer.md).
 - **v1.3.6** (2026-05-14) — Supply-Chain Guard upgraded to 3-pillar architecture: OSV snapshot + curated IoC fixture (version-aware, wired into default scan) + **AI-Native NEW-package heuristic** that catches zero-day-ish risk at the AI-edit boundary. See [`CHANGELOG.md#v136--2026-05-14`](CHANGELOG.md#v136--2026-05-14) and [ADR-0006](.dw/decisions/0006-supply-chain-guard-heuristic.md).
 - v1.3.5 (2026-05-12) — AI-Native Supply-Chain Guard: `dw security-scan` CLI + OSV.dev auto-sync + Edit-lockfile hook + scoped `.gitignore` for end-user projects. See [ADR-0005](.dw/decisions/0005-supply-chain-guard.md). Public 90-day sunset review committed for 2026-08-12.
 - v1.3.4 (2026-04-21) — `/dw:plan` Quick Debate (red/blue self-critique), depth-driven activation
@@ -45,6 +48,21 @@ It’s designed for collaboration (Dev / Tech Lead / QA / PM) and keeps work aud
 - Full changelog: `CHANGELOG.md`
 - Latest release notes: [GitHub Releases](https://github.com/dv-workflow/dv-workflow/releases)
 
+### What's in v1.5.0-rc.1 for your team
+
+**Drift fix structurally.** v2 split `spec.md` + `tracking.md` was leaking status markers across both files. v3 puts everything in one `task.md` (Sections 1-7: Snapshot · Intent · Tracker · Changelog · Handoff · Annexes · Debate). Status lives ONLY in Section 3 — enforced by `dw task lint` strict default.
+
+- **`dw task new <name>`** — scaffold v3 task from template, frontmatter ajv-validated.
+- **`dw task show [name]`** — ANSI terminal snapshot (~30 lines).
+- **`dw task view [name]`** — lean HTML dashboard in browser. 4 cards: snapshot + progress bar + subtask tracker + recent activity + handoff. ~10KB, self-contained (no CDN), scan-in-5-seconds. Trace `task.md` for full details.
+- **`dw task watch [name]`** — live-preview server. fs.watch + 800ms debounce + browser auto-refresh on save. Pair-with-agent workflow.
+- **`dw task render [name]`** — `timeline.svg` sidecar via `dw-kit-render` (satori+resvg). Bounded composition. Mermaid Gantt fallback if sub-package absent.
+- **`dw task lint [name]`** — schema validate + drift-marker detect + line-cap thresholds. Default `strict` (exit 1 on errors). Configurable via `task.lint: warn|off`.
+- **`dw task migrate <name>`** — v2 → v3 with `--dry-run`, `--diff`, `--rollback`, `--all`. `.v2bak` backups preserved (gitignored).
+- **`dw task rotate [name]`** — auto Section-4 overflow > 400 lines → `timeline-history.md`. Invoked by `stop-check` hook.
+- **3-tier auto-sync**: `stop-check` (session end) · `pre-commit-gate` (commit gate) · `dw task watch` (real-time opt-in).
+- **7 skills v3-aware** (task-init / execute / handoff / research / plan / decision / retroactive) — read v3 first, fall back v2/v1.
+
 ### What's in v1.3.6 for your team
 
 Reaction time when a supply-chain incident drops goes from 24-72 hours (wait for OSV index + npm publish cycle) to **~1 hour** (AI edits lockfile → hook fires → heuristic flags BEFORE anyone knows).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-kit",
-  "version": "1.3.6",
+  "version": "1.6.0-rc.1",
   "description": "AI development workflow toolkit — structured, quality-assured, team-ready. From requirements to dashboard.",
   "type": "module",
   "bin": {
@@ -49,13 +49,15 @@
     ".claude/templates/",
     ".claude/settings.json",
     "CLAUDE.md",
-    "MIGRATION-v1.3.md"
+    "MIGRATION-v1.3.md",
+    "MIGRATION-v1.5.md"
   ],
   "engines": {
     "node": ">=18"
   },
   "scripts": {
     "test": "node src/smoke-test.mjs",
+    "test:renderer": "cd packages/dw-kit-render && npm test",
     "link": "npm link",
     "test:e2e-local": "bash scripts/e2e-local-check.sh"
   },

package/src/cli.mjs

@@ -93,6 +93,167 @@ export function run(argv) {
       console.log(chalk.green('✓') + ` Wrote ${target}`);
     });
 
+  const taskCmd = program
+    .command('task')
+    .description('v3 task docs operations (ADR-0008): show · new · migrate · lint');
+
+  taskCmd
+    .command('show [task-name]')
+    .description('Print ANSI snapshot (status + subtask tracker) of a v3 task')
+    .option('-v, --verbose', 'Include Section 1 Snapshot body')
+    .action(async (taskName, opts) => {
+      const { taskShowCommand } = await import('./commands/task-show.mjs');
+      await taskShowCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('new <task-name>')
+    .description('Scaffold a new v3 task from template')
+    .option('-d, --depth <level>', 'quick | standard | thorough', 'standard')
+    .option('-t, --title <title>', 'Human-readable task title')
+    .option('-o, --owner <name>', 'Task owner', '')
+    .option('-a, --adr <ref>', 'Related ADR (ADR-NNNN or none)', 'none')
+    .option('--target <ship>', 'Target ship milestone', 'TBD')
+    .action(async (taskName, opts) => {
+      const { taskNewCommand } = await import('./commands/task-new.mjs');
+      await taskNewCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('migrate [task-name]')
+    .description('Migrate v2 spec.md + tracking.md → v3 task.md')
+    .option('-n, --dry-run', 'Preview without writing')
+    .option('--diff', 'Show diff against existing task.md')
+    .option('--all', 'Scan and migrate all v2 tasks')
+    .option('--force', 'Overwrite existing task.md')
+    .option('--remove-v2', 'Delete spec.md/tracking.md after backup (default keeps them)')
+    .option('--rollback', 'Restore v2 files from .v2bak backups (requires task name)')
+    .action(async (taskName, opts) => {
+      const { taskMigrateCommand } = await import('./commands/task-migrate.mjs');
+      await taskMigrateCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('lint [task-name]')
+    .description('Lint v3 task.md: schema validate + drift markers + line caps')
+    .option('-l, --level <level>', 'strict | warn | off (overrides config)', '')
+    .action(async (taskName, opts) => {
+      const { lintTaskCommand } = await import('./commands/lint-task.mjs');
+      await lintTaskCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('rotate [task-name]')
+    .description('Auto-rotate Section 4 (Timeline/Changelog) > 400 lines to timeline-history.md (keeps last 8 entries)')
+    .option('-n, --dry-run', 'Preview without writing')
+    .option('-q, --quiet', 'Suppress output (hook usage)')
+    .action(async (taskName, opts) => {
+      const { taskRotateCommand } = await import('./commands/task-rotate.mjs');
+      await taskRotateCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('render [task-name]')
+    .description('Render timeline.svg sidecar via dw-kit-render sub-package; falls back to Mermaid block in Section 4 if absent')
+    .option('-n, --dry-run', 'Print manifest without writing files')
+    .option('-f, --format <kind>', 'svg | png | svg,png', 'svg')
+    .option('--mermaid-only', 'Skip SVG, only inject Mermaid fallback block')
+    .option('--always-mermaid', 'Inject Mermaid block AND SVG (both)')
+    .action(async (taskName, opts) => {
+      const formats = String(opts.format || 'svg').split(',').map((s) => s.trim()).filter(Boolean);
+      const { taskRenderCommand } = await import('./commands/task-render.mjs');
+      await taskRenderCommand(taskName, { ...opts, formats });
+    });
+
+  taskCmd
+    .command('view [task-name]')
+    .description('Render lean HTML dashboard (snapshot + tracker + recent activity + handoff) and open in browser')
+    .option('--no-open', 'Generate HTML without opening browser (prints path)')
+    .action(async (taskName, opts) => {
+      const { taskViewCommand } = await import('./commands/task-view.mjs');
+      await taskViewCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('watch [task-name]')
+    .description('Watch task.md for changes and live-reload the HTML preview in browser (local server, debounced)')
+    .option('-p, --port <port>', 'Local server port (auto-finds next available if busy)', parseInt)
+    .action(async (taskName, opts) => {
+      const { taskWatchCommand } = await import('./commands/task-watch.mjs');
+      await taskWatchCommand(taskName, opts);
+    });
+
+  const agentCmd = program
+    .command('agent')
+    .description('Agent OS multi-agent orchestration (ADR-0009): claim · release · claims · reports · conflicts');
+
+  agentCmd
+    .command('claim <task-id>')
+    .description('Create a cooperative claim for a task (subtasks + write_scope)')
+    .option('-s, --subtasks <list>', 'Comma-separated subtask IDs (e.g. ST-1,ST-2)')
+    .option('-w, --write <paths>', 'Comma-separated write_scope glob paths')
+    .option('-r, --read <paths>', 'Comma-separated read_scope hint paths (informational)')
+    .option('-a, --agent <id>', 'Agent identifier (default: env DW_AGENT_ID or auto-generated)')
+    .option('-v, --vendor <name>', 'Vendor: claude | codex | gemini | human | other', 'claude')
+    .option('--role <role>', 'worker | reader | orchestrator | reviewer', 'worker')
+    .option('-l, --lease <duration>', 'Lease duration (e.g. 30m, 1h, 4h, 1d)', '1h')
+    .option('--worktree <path>', 'Worktree path if agent uses git worktree (R2-3)')
+    .option('-f, --force', 'Override conflict detection (use sparingly)')
+    .action(async (taskId, opts) => {
+      const { agentClaimCommand } = await import('./commands/agent-claim.mjs');
+      await agentClaimCommand(taskId, opts);
+    });
+
+  agentCmd
+    .command('release <claim-id>')
+    .description('Release a claim (clean exit; transitions status to "released")')
+    .option('-r, --reason <text>', 'Optional reason for release')
+    .action(async (claimId, opts) => {
+      const { agentReleaseCommand } = await import('./commands/agent-claim.mjs');
+      await agentReleaseCommand(claimId, opts);
+    });
+
+  agentCmd
+    .command('expire <claim-id>')
+    .description('Mark a claim as expired or invalidated (orchestrator action)')
+    .option('-r, --reason <text>', 'Reason for expiry')
+    .option('--invalidate', 'Invalidate instead of expire (orchestrator override)')
+    .action(async (claimId, opts) => {
+      const { agentExpireCommand } = await import('./commands/agent-claim.mjs');
+      await agentExpireCommand(claimId, opts);
+    });
+
+  agentCmd
+    .command('claims')
+    .description('List claims (default: active only). Filter by task / status / --all to include released')
+    .option('-t, --task <id>', 'Filter by task ID')
+    .option('-s, --status <status>', 'Filter by status: created | active | released | expired | invalidated')
+    .option('--all', 'Include released and invalidated claims')
+    .action(async (opts) => {
+      const { agentClaimsCommand } = await import('./commands/agent-inspect.mjs');
+      await agentClaimsCommand(opts);
+    });
+
+  agentCmd
+    .command('reports')
+    .description('List agent reports across tasks (read-only audit view)')
+    .option('-t, --task <id>', 'Filter by task ID')
+    .option('-a, --agent <id>', 'Filter by agent ID')
+    .action(async (opts) => {
+      const { agentReportsCommand } = await import('./commands/agent-inspect.mjs');
+      await agentReportsCommand(opts);
+    });
+
+  agentCmd
+    .command('conflicts')
+    .description('Detect overlapping active claims (subtask or write_scope). Exits 1 if conflicts found (use --no-strict to suppress).')
+    .option('-t, --task <id>', 'Filter by task ID')
+    .option('--no-strict', 'Do not exit 1 on conflict (just report)')
+    .action(async (opts) => {
+      const { agentConflictsCommand } = await import('./commands/agent-inspect.mjs');
+      await agentConflictsCommand(opts);
+    });
+
   program
     .command('dashboard')
     .description('Show team dashboard — active tasks, ADRs, telemetry summary, health')
@@ -131,6 +292,21 @@ export function run(argv) {
       await securityScanCommand(opts);
     });
 
+  const reviewCmd = program
+    .command('review')
+    .description('Review subcommands (ADR-0007)');
+
+  reviewCmd
+    .command('render <manifest>')
+    .description('Render a /dw:review --visual manifest into SVG/PNG (requires dw-kit-render) or markdown summary fallback')
+    .option('-f, --format <kind>', 'Override output formats: svg | png | both', null)
+    .option('-s, --strategy <name>', 'Override strategy: auto | plugin | markdown-only', null)
+    .option('-q, --quiet', 'Suppress info logs (still exits non-zero on hard errors)')
+    .action(async (manifest, opts) => {
+      const { reviewRenderCommand } = await import('./commands/review-render.mjs');
+      await reviewRenderCommand(manifest, opts);
+    });
+
   program
     .command('claude-vn-fix')
     .description('Patch Claude CLI to fix Vietnamese IME (local, with backup/restore)')