dw-kit 1.9.0-rc.1 → 1.9.1

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

@@ -85,6 +85,16 @@ if [ "$ACTIVE_TASK_FORMAT" = "v3" ] && [ -n "$ACTIVE_TASK" ]; then
   fi
 fi
 
+# --- Refresh tasks-index@v1 (ADR-0017 doc contract) — fire-and-forget ---
+# Keeps the adapter read-contract (.dw/tasks/tasks-index.json) fresh after manual
+# task.md edits. Idempotent at the writer (writeTaskIndex sorts keys + skips the
+# write when the task set is byte-identical), so an unchanged set produces ZERO
+# git diff and never blocks a post-commit `git checkout` (#21). Silent; errors ignored.
+DW_BIN="$PROJECT_DIR/bin/dw.mjs"
+if [ -f "$DW_BIN" ] && [ -d "$PROJECT_DIR/.dw/tasks" ] && command -v node >/dev/null 2>&1; then
+  node "$DW_BIN" task index >/dev/null 2>&1 || true
+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")

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

@@ -73,12 +73,13 @@ Show preview (first 30 lines) rồi ask:
 Save this ADR to .dw/decisions/{NNNN}-{title}.md? (Y/n)
 ```
 
-Nếu yes → write file + print:
+Nếu yes → write file, sau đó chạy `dw decision index` (cập nhật `decisions-index@v1` — read-contract cho adapter, ADR-0017 v1.1), rồi print:
 ```
 ✓ ADR-{NNNN} created
   Status: Proposed
   Next: Review → change status to Accepted when approved
         Related task: update task.md (v3) / tracking.md (v2) với reference
+        decisions-index refreshed (dw decision index)
 ```
 
 ## Quality Bar

package/.claude/skills/dw-kit-report/SKILL.md

@@ -17,6 +17,18 @@ $ARGUMENTS
 
 ---
 
+## Nguyên tắc riêng tư (ĐỌC TRƯỚC — bắt buộc)
+
+Skill này tạo issue trên **repo bên thứ ba `dv-workflow/dv-workflow`** (ngoài project của bạn). Vì vậy **KHÔNG bao giờ tự động đưa thông tin nhận dạng của project người report vào issue**:
+
+- ❌ KHÔNG kèm `project.name` từ config (đây là tên codebase/đơn vị của người dùng).
+- ❌ KHÔNG kèm tên task, mã ticket nội bộ (vd `PROJ-123`), đường dẫn file độc quyền, hay code snippet.
+- ✅ CHỈ gửi: loại feedback, component của **dw-kit**, mô tả vấn đề (từ `$ARGUMENTS`), và môi trường tối thiểu (OS, shell, dw version).
+
+Nếu chính `$ARGUMENTS` chứa thông tin nhận dạng nội bộ → cảnh báo người dùng và đề nghị lược bỏ. **Luôn preview + xin xác nhận trước khi gửi (Bước 4).**
+
+---
+
 ## Bước 1: Thu Thập Context
 
 **OS detection:**
@@ -24,9 +36,9 @@ $ARGUMENTS
 uname -s 2>/dev/null || echo "Windows"
 ```
 
-**dw version:** Đọc `_toolkit.core_version` từ `.dw/config/dw.config.yml`
+**dw version:** Đọc `_toolkit.core_version` từ `.dw/config/dw.config.yml` (KHÔNG đọc `project.name`).
 
-**Task context:** Kiểm tra `.dw/tasks/` — task nào đang In Progress?
+**Workflow context:** Có task In Progress không, và depth của nó (quick/standard/thorough) — chỉ để giúp reproduce. Ghi nhận CÓ/KHÔNG + depth, **KHÔNG lấy tên task**.
 
 ---
 
@@ -83,8 +95,8 @@ Ví dụ:
 [Nội dung từ $ARGUMENTS — đầy đủ, rõ ràng]
 
 ## Context
-- Task khi gặp vấn đề: [task name hoặc "general usage"]
-- Command/skill liên quan: [nếu biết]
+- Hoàn cảnh: ["general usage" hoặc "trong một task depth=X" — KHÔNG ghi tên task/ticket]
+- Command/skill dw-kit liên quan: [nếu biết]
 - Bước reproduce (nếu là bug):
   1. ...
   2. ...
@@ -95,12 +107,31 @@ Ví dụ:
 - [ ] Minor — annoying, có workaround dễ
 
 ---
-*Reported via `/dw:kit-report` | Project: [project.name từ config]*
+*Reported via `/dw:kit-report`*
 ```
 
+> Không thêm dòng `Project:` hay bất kỳ tên project/ticket/path nội bộ nào (xem Nguyên tắc riêng tư).
+
+---
+
+## Bước 4: Preview + Xác Nhận (BẮT BUỘC trước khi gửi)
+
+Issue sẽ được tạo trên repo bên thứ ba **công khai với dw-kit team**. Trước khi gửi, hiện đầy đủ title + body sẽ post và CHỜ người dùng đồng ý:
+
+```
+┌─ Sẽ gửi lên github.com/dv-workflow/dv-workflow ─────────────┐
+ TITLE: [title]
+
+ BODY:
+ [body đầy đủ]
+└─ Gõ "ok" để gửi · hoặc sửa nội dung trước ──────────────────┘
+```
+
+Trước khi hiện preview, **rà soát lần cuối**: nếu title/body (kể cả phần người dùng tự nhập trong `$ARGUMENTS`) còn chứa tên project, mã ticket nội bộ, đường dẫn file độc quyền, hay code snippet → cảnh báo rõ và đề nghị lược bỏ. **Chỉ sang Bước 5 sau khi người dùng xác nhận.**
+
 ---
 
-## Bước 4: Gửi Lên GitHub
+## Bước 5: Gửi Lên GitHub
 
 **Kiểm tra `gh` CLI:**
 ```bash
@@ -141,7 +172,7 @@ In ra:
 
 ---
 
-## Bước 5: Xác Nhận
+## Bước 6: Xác Nhận
 
 ```
 ✓ Issue đã được gửi: https://github.com/dv-workflow/dv-workflow/issues/[N]

package/.dw/core/schemas/decision-frontmatter.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dv-workflow/dv-workflow/blob/main/.dw/core/schemas/decision-frontmatter.schema.json",
+  "title": "decision-frontmatter",
+  "description": "Normalized ADR metadata for decisions-index@v1 (ADR-0017 v1.1). ADRs use two on-disk styles: YAML frontmatter (early, e.g. ADR-0001) OR markdown headers `# ADR-NNNN: Title` + `## Status:`/`## Date:`/`## Deciders:`/`## Related:`. The `dw decision index` parser tolerates both and projects to this normalized shape. New ADRs MAY adopt YAML frontmatter with these keys for lossless extraction.",
+  "type": "object",
+  "required": ["title", "status"],
+  "additionalProperties": true,
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "ADR title (without the `ADR-NNNN:` prefix)"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["Proposed", "Accepted", "Deprecated", "Superseded"],
+      "description": "Normalized lifecycle status keyword (extracted from a possibly-decorated status line, e.g. 'Accepted (Round 2, ...)')"
+    },
+    "status_raw": {
+      "type": ["string", "null"],
+      "description": "Original status string before normalization"
+    },
+    "date": {
+      "type": ["string", "null"],
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "First ISO date found in the Date field/header (YYYY-MM-DD)"
+    },
+    "deciders": {
+      "type": ["string", "null"],
+      "description": "Free-form deciders (names/roles)"
+    },
+    "related": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^ADR-\\d{3,4}$" },
+      "uniqueItems": true,
+      "description": "Referenced ADRs (from Related field/header + status line); excludes self. Causal-link candidates for org-memory ingest."
+    },
+    "supersedes": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^ADR-\\d{3,4}$" },
+      "uniqueItems": true,
+      "description": "ADRs this one supersedes"
+    },
+    "superseded_by": {
+      "type": ["string", "null"],
+      "pattern": "^ADR-\\d{3,4}$",
+      "description": "ADR that supersedes this one (from 'Superseded by ADR-NNNN' or frontmatter)"
+    },
+    "file": {
+      "type": "string",
+      "description": "Repo-relative path to the ADR markdown file"
+    }
+  }
+}

package/.dw/core/schemas/goal-frontmatter.schema.json

@@ -73,12 +73,12 @@
     "icon": {
       "type": ["string", "null"],
       "maxLength": 8,
-      "description": "Optional emoji/icon for visual differentiation in portfolio cards (bigokr borrow)."
+      "description": "Optional emoji/icon for visual differentiation in portfolio cards."
     },
     "cycle": {
       "type": ["string", "null"],
       "maxLength": 32,
-      "description": "Optional temporal grouping label e.g. 'Q1 2026', 'v1.7-cycle', '2026 H1' (bigokr borrow). Portfolio groups goals by cycle."
+      "description": "Optional temporal grouping label e.g. 'Q1 2026', 'v1.7-cycle', '2026 H1'. Portfolio groups goals by cycle."
     }
   }
 }

package/.dw/core/schemas/task-frontmatter.schema.json

@@ -67,8 +67,8 @@
     },
     "schema_version": {
       "type": "string",
-      "enum": ["v3.0", "v3.1"],
-      "description": "Frontmatter schema version. v3.1 adds optional parent_goal_id, contributing_goal_ids, summary per ADR-0010."
+      "enum": ["task@v3.0", "task@v3.1", "v3.0", "v3.1"],
+      "description": "Frontmatter schema version. Canonical form is namespaced (task@v3.0/task@v3.1) to match the repo-wide @v convention (goal@v1, tasks-index@v1); bare v3.0/v3.1 stay valid for back-compat. v3.1 adds optional parent_goal_id, contributing_goal_ids, summary per ADR-0010 (#22)."
     },
     "blockers": {
       "type": "string",

package/.dw/core/templates/v3/task.md

@@ -8,7 +8,7 @@ owner: {name}
 depth: quick | standard | thorough
 related_adr: {ADR-NNNN | none}
 target_ship: {milestone or TBD}
-schema_version: v3.0
+schema_version: task@v3.0
 blockers: none
 ---
 
@@ -66,25 +66,42 @@ genuinely changes.
 
 {Forcing function: deadline, incident, dependency, opportunity.}
 
-### Subtasks (in scope)
-
-**ST-1: {Subtask name}**
-- {Concrete action}
-- Acceptance: {verifiable criterion}
-
-**ST-2: {Subtask name}**
-- ...
+<!--
+Subtasks live in the Section 3 tracker (one list, with per-subtask Acceptance +
+Est columns) — NOT duplicated here. Section 2 stays the stable intent contract;
+Section 3 owns the subtask breakdown + status.
+-->
 
 ### Out of Scope
 
 - {Explicit exclusions — prevents scope creep}
 
-### Success Criteria
+### Functional Acceptance (handoff scenarios)
 
-Measurable outcomes (not vibes):
+<!--
+Feature behaviour in business / user language — readable by PM/BA/QC WITHOUT code
+(no API/file/variable names). This is the cross-role handoff contract, NOT a full
+test plan (`/dw:test-plan` expands it into QC cases). Per-component acceptance
+lives with each subtask; this is the feature-level scenario layer.
+-->
 
-- [ ] {Numeric threshold, e.g., "p95 latency <100ms"}
-- [ ] {Binary gate, e.g., "passes smoke test"}
+- [ ] {User-visible scenario, e.g., "User resets password and gets a confirmation email"}
+- [ ] {Error / edge scenario, e.g., "Expired reset link shows a clear retry prompt"}
+- [ ] {Measurable gate where relevant, e.g., "p95 latency <100ms"}
+
+### Definition of Done (role lens)
+
+<!--
+Plain-language sign-off anchored to the outcome. Roles absent from `team.roles`
+sign by proxy / degrade gracefully. These are `- [ ]` checkboxes (NOT status
+markers — those live only in Section 3).
+-->
+
+- [ ] 🎯 **Goal** — result advances the linked goal's KR (update the goal)
+- [ ] 📋 **BA** — matches the business expectation
+- [ ] ✅ **QC** — handoff scenarios pass, incl. error cases + no regression
+- [ ] 🛠 **TL** — approach/code sound, no new tech debt, automated checks pass
+- [ ] 🤝 **Handoff** — docs sufficient + changes merged
 
 ### Dependencies
 
@@ -100,14 +117,19 @@ Measurable outcomes (not vibes):
 ## 3. Subtask Tracker
 
 <!--
-SINGLE SOURCE OF TRUTH for subtask status. This is the only section where
-status markers (⬜🟡✅🔴⏸) are allowed.
+SINGLE SOURCE OF TRUTH for the subtask breakdown AND status. The subtask list is
+NOT duplicated in Section 2 (#24). This is the only section where status markers
+(⬜🟡✅🔴⏸) are allowed — Section 2 stays status-free (drift-prevention).
+
+Columns (read by name, order-tolerant): Acceptance = per-subtask verifiable
+criterion; Est = optional effort estimate (hours / story-points / t-shirt per
+`estimation_unit`, `—` if unused, see `/dw:estimate`).
 -->
 
-| # | Subtask | Status | Date | Notes |
-|---|---------|--------|------|-------|
-| ST-1 | ... | ⬜ Pending | — | |
-| ST-2 | ... | ⬜ Pending | — | |
+| # | Subtask | Acceptance | Est | Status | Notes |
+|---|---------|-----------|-----|--------|-------|
+| ST-1 | {name} | {verifiable criterion} | — | ⬜ Pending | |
+| ST-2 | {name} | ... | — | ⬜ Pending | |
 
 Status legend: ⬜ Pending · 🟡 In Progress · ✅ Done · 🔴 Blocked · ⏸ Paused
 

package/README.md

@@ -2,7 +2,7 @@
 
 > An AI development workflow toolkit for teams using agentic IDEs (Claude Code, Cursor) — from idea to review-ready commits.
 
-**v1.3.6** · `npm install -g dw-kit` · [Docs](docs/README.md) · [Get started](docs/get-started.md) · [Cheatsheet](docs/cheatsheet.md) · [Migration v1.3](MIGRATION-v1.3.md) · [Changelog](CHANGELOG.md)
+**v1.9.1** · `npm install -g dw-kit` · [Docs](docs/README.md) · [Get started](docs/get-started.md) · [Cheatsheet](docs/cheatsheet.md) · [Migration v1.3](MIGRATION-v1.3.md) · [Changelog](CHANGELOG.md)
 
 ---
 
@@ -36,7 +36,10 @@ 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.9.0 (current, stable)** — substrate-complete for the realtime voice-orchestration Root Goal: persistent CLI-agent sessions, Telegram bridge, multi-workspace registry, browser voice MVP + orchestrator action-execution, multi-agent live debate, and the **DW Event/Document schema + adapter protocol** ([ADR-0011](.dw/decisions/0011-session-runtime-voice-orchestrator.md)/[0014](.dw/decisions/0014-orchestrator-action-execution.md)/[0015](.dw/decisions/0015-multi-agent-live-debate.md)/[0016](.dw/decisions/0016-dw-goal-outcome-pursuit-loop.md)/[0017](.dw/decisions/0017-dw-document-schema-index.md)). Plus team-dogfood fixes: `dw goal status` (#20), deterministic index writers (#21), `task@v3.x` schema_version converge (#22), v3 template Functional Acceptance + role-lens DoD + Est (#24).
+- **v1.8.0** — remote-agent-first substrate: `dw session *`, `dw connector telegram`, `dw workspace *`, `dw voice` (bilingual en+vi, hybrid orchestrator, action-execution with voice confirm).
+- **v1.7.0** — **Goals Layer (OKR-inspired)** ([ADR-0010](.dw/decisions/0010-goals-management-layer.md)): strategic layer above tasks — `dw goal *`, `goals-index@v1`, bidirectional task↔goal linking, portfolio + HTML view.
+- **v1.6.0** — **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). Audit trail via committed `reports/` + `events.jsonl`; claims gitignored ephemeral.
 - **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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-kit",
-  "version": "1.9.0-rc.1",
+  "version": "1.9.1",
   "description": "AI development workflow toolkit — structured, quality-assured, team-ready. From requirements to dashboard.",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "src/commands/",
     "src/lib/",
     ".dw/core/",
+    "!.dw/core/PILLARS.md",
     ".dw/config/",
     ".dw/adapters/",
     ".dw/security/",
@@ -50,7 +51,6 @@
     ".claude/skills/dw-upgrade/",
     ".claude/templates/",
     ".claude/settings.json",
-    "CLAUDE.md",
     "MIGRATION-v1.3.md",
     "MIGRATION-v1.5.md",
     "NOTICE",
@@ -65,7 +65,9 @@
     "test:renderer": "cd packages/dw-kit-render && npm test",
     "link": "npm link",
     "test:e2e-local": "bash scripts/e2e-local-check.sh",
-    "gen:event-schemas": "node scripts/generate-event-schemas.mjs"
+    "gen:event-schemas": "node scripts/generate-event-schemas.mjs",
+    "audit:pack": "node scripts/audit-pack.mjs",
+    "prepublishOnly": "node scripts/audit-pack.mjs"
   },
   "keywords": [
     "ai",

package/src/cli.mjs

@@ -195,6 +195,30 @@ export function run(argv) {
       await taskSummaryCommand(taskName, opts);
     });
 
+  taskCmd
+    .command('index')
+    .description('Regenerate .dw/tasks/tasks-index.json — DW Document Schema + Index v1.0 read-contract (ADR-0017)')
+    .option('--json', 'Print the machine-readable index (for external adapters)')
+    .option('--check', 'Print the current index without rebuilding')
+    .action(async (opts) => {
+      const { taskIndexCommand } = await import('./commands/task-index.mjs');
+      await taskIndexCommand(opts);
+    });
+
+  const decisionCmd = program
+    .command('decision')
+    .description('ADR operations (ADR-0017 v1.1 document contract)');
+
+  decisionCmd
+    .command('index')
+    .description('Regenerate .dw/decisions/decisions-index.json — decisions-index@v1 read-contract (ADR-0017 v1.1; consumed by external org-memory adapters)')
+    .option('--json', 'Print the machine-readable index (for adapters)')
+    .option('--check', 'Print the current index without rebuilding')
+    .action(async (opts) => {
+      const { decisionIndexCommand } = await import('./commands/decision-index.mjs');
+      await decisionIndexCommand(opts);
+    });
+
   const agentCmd = program
     .command('agent')
     .description('Agent OS multi-agent orchestration (ADR-0009): claim · release · renew · expire · claims · reports · conflicts · check-staged · verify');
@@ -495,6 +519,15 @@ export function run(argv) {
       await goalSetCommand(goalId, opts);
     });
 
+  goalCmd
+    .command('status <goal-id> <new-status>')
+    .description('Transition lifecycle status (Draft|Active|Achieved|Pivoted); auto-bumps goal_version + emits goal_status_changed. Use `goal delete` to abandon.')
+    .option('--reason <text>', 'Optional reason, recorded in the goal_status_changed event')
+    .action(async (goalId, newStatus, opts) => {
+      const { goalStatusCommand } = await import('./commands/goal-status.mjs');
+      await goalStatusCommand(goalId, newStatus, opts);
+    });
+
   goalCmd
     .command('show [goal-id]')
     .description('ANSI snapshot of a goal (no arg = list all)')

package/src/commands/decision-index.mjs

@@ -0,0 +1,45 @@
+import chalk from 'chalk';
+import { rebuildDecisionIndex, readDecisionIndex, decisionIndexFile } from '../lib/decision-store.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+// `dw decision index` — regenerate .dw/decisions/decisions-index.json
+// (DW Document Schema + Index v1.0, ADR-0017 v1.1). Read-contract surface for
+// external org-memory adapters.
+//   dw decision index           rebuild + human summary
+//   dw decision index --json    rebuild + print machine-readable index
+//   dw decision index --check   print current index without rebuilding
+export async function decisionIndexCommand(opts = {}) {
+  const rootDir = process.cwd();
+  const index = opts.check ? readDecisionIndex(rootDir) : rebuildDecisionIndex(rootDir);
+
+  if (opts.json) {
+    console.log(JSON.stringify(index, null, 2));
+    logEvent({ event: 'decision', action: 'index.json', name: Object.keys(index.decisions).length }, rootDir);
+    return;
+  }
+
+  const decisions = index.decisions || {};
+  const ids = Object.keys(decisions);
+  const byStatus = {};
+  for (const id of ids) {
+    const s = decisions[id].status || 'Proposed';
+    byStatus[s] = (byStatus[s] || 0) + 1;
+  }
+
+  console.log();
+  console.log(chalk.bold(`  decisions-index (${chalk.cyan(index.schema_version)}) — ${ids.length} ADR(s)`));
+  console.log(chalk.dim(`  ${decisionIndexFile(rootDir)}`));
+  console.log();
+  if (ids.length === 0) {
+    console.log(chalk.dim('  (no ADRs — create one with /dw:decision)'));
+  } else {
+    for (const [status, n] of Object.entries(byStatus)) {
+      console.log(`  ${String(n).padStart(3)}  ${status}`);
+    }
+  }
+  console.log();
+  console.log(chalk.dim('  Tip: `dw decision index --json` for the machine-readable adapter contract.'));
+  console.log();
+
+  logEvent({ event: 'decision', action: opts.check ? 'index.check' : 'index.rebuild', name: ids.length }, rootDir);
+}

package/src/commands/goal-delete.mjs

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import chalk from 'chalk';
 import { parseFrontmatter, stringifyFrontmatter } from '../lib/frontmatter.mjs';
-import { readGoal, removeIndexEntry, findLinkedTaskIds, goalDir, todayIso, nowUtc } from '../lib/goal-store.mjs';
+import { readGoal, removeIndexEntry, syncIndexEntry, findLinkedTaskIds, goalDir, todayIso, nowUtc } from '../lib/goal-store.mjs';
 import { logGoalEvent } from '../lib/goal-events.mjs';
 import { logEvent } from '../lib/telemetry.mjs';
 
@@ -94,6 +94,8 @@ export async function goalDeleteCommand(goalId, opts = {}) {
   fm.last_updated = todayIso();
   const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
   writeFileSync(goal.file, stringifyFrontmatter(fm) + body, 'utf8');
+  // Keep goals-index in sync — otherwise `goal lint` flags status drift (#20).
+  syncIndexEntry(goalId, rootDir);
 
   logGoalEvent({
     event: 'goal_status_changed',

package/src/commands/goal-link.mjs

@@ -5,6 +5,7 @@ import { parseFrontmatter, stringifyFrontmatter } from '../lib/frontmatter.mjs';
 import { readGoal, syncIndexEntry, todayIso } from '../lib/goal-store.mjs';
 import { logGoalEvent } from '../lib/goal-events.mjs';
 import { logEvent } from '../lib/telemetry.mjs';
+import { bareSchemaVersion } from '../lib/task-store.mjs';
 
 const TASKS_DIR = '.dw/tasks';
 
@@ -17,7 +18,8 @@ function writeTaskFrontmatter(taskId, mutator, rootDir = process.cwd()) {
   const content = readFileSync(file, 'utf8');
   const fm = parseFrontmatter(content);
   const updated = mutator({ ...fm });
-  if (updated.schema_version === 'v3.0') updated.schema_version = 'v3.1';
+  // Linking goal fields requires v3.1; bump v3.0 → canonical task@v3.1 (#22).
+  if (bareSchemaVersion(updated.schema_version) === 'v3.0') updated.schema_version = 'task@v3.1';
   updated.last_updated = todayIso();
   const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
   writeFileSync(file, stringifyFrontmatter(updated) + body, 'utf8');

package/src/commands/goal-status.mjs

@@ -0,0 +1,95 @@
+import chalk from 'chalk';
+import {
+  readGoal,
+  updateGoalFrontmatter,
+  syncIndexEntry,
+  goalStatusEnum,
+  todayIso,
+} from '../lib/goal-store.mjs';
+import { logGoalEvent } from '../lib/goal-events.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+// Statuses whose entry carries cascade + archive semantics owned by `goal delete`.
+const DELEGATED_STATUSES = new Set(['Abandoned']);
+// Closed states — reopening them is a backward move worth warning about.
+const CLOSED_STATUSES = new Set(['Achieved', 'Abandoned']);
+
+// Title-case a user-typed status so `active` matches the PascalCase enum (#20).
+function normalizeStatus(input, allowed) {
+  if (!input) return input;
+  const exact = allowed.find((s) => s === input);
+  if (exact) return exact;
+  return allowed.find((s) => s.toLowerCase() === input.toLowerCase()) || input;
+}
+
+export async function goalStatusCommand(goalId, newStatusRaw, opts = {}) {
+  const rootDir = process.cwd();
+
+  const allowed = goalStatusEnum(rootDir);
+  if (!goalId || !newStatusRaw) {
+    console.error(chalk.red(`✗ Usage: dw goal status <goal-id> <${allowed.join('|')}> [--reason "..."]`));
+    process.exit(1);
+  }
+
+  const newStatus = normalizeStatus(newStatusRaw, allowed);
+  if (!allowed.includes(newStatus)) {
+    console.error(chalk.red(`✗ Invalid status "${newStatusRaw}". Allowed: ${allowed.join(', ')}`));
+    process.exit(1);
+  }
+
+  // Abandonment is owned by `goal delete` (linked-task cascade + goal_archived
+  // event). Redirect rather than create a second, divergent abandon path (#20).
+  if (DELEGATED_STATUSES.has(newStatus)) {
+    console.error(chalk.red(`✗ Use \`dw goal delete ${goalId}\` to abandon a goal.`));
+    console.error(chalk.dim('  It handles linked-task cleanup (--cascade) and emits goal_archived.'));
+    process.exit(1);
+  }
+
+  const goal = readGoal(goalId, rootDir);
+  if (!goal) {
+    console.error(chalk.red(`✗ Goal ${goalId} not found`));
+    process.exit(1);
+  }
+
+  const fromStatus = goal.fm.status || 'Draft';
+  if (fromStatus === newStatus) {
+    console.log(chalk.dim(`  ${goalId} is already ${newStatus} — no change.`));
+    return;
+  }
+
+  // Warn (don't block) on reopening a closed goal — least surprise per ADR-0001.
+  if (CLOSED_STATUSES.has(fromStatus)) {
+    console.error(chalk.yellow(`  ⚠ reopening a ${fromStatus} goal → ${newStatus}`));
+  }
+
+  const changedBy = process.env.USER || process.env.USERNAME || 'unknown';
+  const oldVersion = goal.fm.goal_version || 1;
+  const newVersion = oldVersion + 1; // ADR-0010 Q4/C-1: status transitions are material → auto-bump
+
+  updateGoalFrontmatter(goalId, (fm) => {
+    fm.status = newStatus;
+    fm.goal_version = newVersion;
+    // Leaving any non-Abandoned target must clear a stale archive timestamp
+    // (schema: archived_at null = active). Covers reopen from a soft-delete.
+    if (fm.archived_at) fm.archived_at = null;
+    fm.last_updated = todayIso();
+    return fm;
+  }, rootDir);
+  syncIndexEntry(goalId, rootDir);
+
+  logGoalEvent({
+    event: 'goal_status_changed',
+    goal_id: goalId,
+    from_status: fromStatus,
+    to_status: newStatus,
+    changed_by: changedBy,
+    ...(opts.reason ? { reason: opts.reason } : {}),
+  }, rootDir);
+  logEvent({ event: 'goal', action: 'status', name: goalId, from: fromStatus, to: newStatus }, rootDir);
+
+  console.log();
+  console.log(chalk.green(`  ✓  ${chalk.bold(goalId)} status ${fromStatus} → ${newStatus} (v${oldVersion} → v${newVersion})`));
+  if (opts.reason) console.log(chalk.dim(`     Reason: ${opts.reason}`));
+  console.log(chalk.dim('     Logged to .dw/events-global.jsonl as goal_status_changed'));
+  console.log();
+}

package/src/commands/lint-task.mjs

@@ -106,6 +106,26 @@ export async function lintTaskCommand(taskName, opts = {}) {
     level,
   }, rootDir);
 
+  // tasks-index freshness advisory (ADR-0017 doc contract) — read-only, never mutates.
+  try {
+    const { readTaskIndex, listTaskIds, readTask } = await import('../lib/task-store.mjs');
+    const index = readTaskIndex(rootDir);
+    const idxKeys = new Set(Object.keys(index.tasks || {}));
+    const onDisk = listTaskIds(rootDir);
+    const missing = onDisk.filter((id) => !idxKeys.has(id));
+    let statusDrift = 0;
+    for (const id of onDisk) {
+      const entry = index.tasks?.[id];
+      if (!entry) continue;
+      const t = readTask(id, rootDir);
+      if (t && (t.fm.status || 'Draft') !== entry.status) statusDrift++;
+    }
+    if (missing.length || statusDrift) {
+      console.log(chalk.dim(`  ℹ tasks-index stale (${missing.length} unindexed, ${statusDrift} status drift) — run \`dw task index\``));
+      console.log();
+    }
+  } catch { /* advisory only */ }
+
   if (level === 'strict' && totalErrors > 0) {
     process.exit(1);
   }

package/src/commands/task-index.mjs

@@ -0,0 +1,47 @@
+import chalk from 'chalk';
+import { rebuildTaskIndex, readTaskIndex, taskIndexFile } from '../lib/task-store.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+// `dw task index` — regenerate .dw/tasks/tasks-index.json (DW Document Schema
+// + Index v1.0, ADR-0017). Read-only contract surface for adapters.
+//   dw task index           rebuild + human summary
+//   dw task index --json    rebuild + print machine-readable index
+//   dw task index --check    print current index without rebuilding (--json optional)
+export async function taskIndexCommand(opts = {}) {
+  const rootDir = process.cwd();
+  const index = opts.check ? readTaskIndex(rootDir) : rebuildTaskIndex(rootDir);
+
+  if (opts.json) {
+    console.log(JSON.stringify(index, null, 2));
+    logEvent({ event: 'task', action: 'index.json', name: Object.keys(index.tasks).length }, rootDir);
+    return;
+  }
+
+  const tasks = index.tasks || {};
+  const ids = Object.keys(tasks);
+  const byStatus = {};
+  for (const id of ids) {
+    const s = tasks[id].status || 'Draft';
+    byStatus[s] = (byStatus[s] || 0) + 1;
+  }
+
+  console.log();
+  console.log(chalk.bold(`  tasks-index (${chalk.cyan(index.schema_version)}) — ${ids.length} task(s)`));
+  console.log(chalk.dim(`  ${taskIndexFile(rootDir)}`));
+  console.log();
+  if (ids.length === 0) {
+    console.log(chalk.dim('  (no tasks — scaffold one with `dw task new <name>`)'));
+  } else {
+    for (const [status, n] of Object.entries(byStatus)) {
+      console.log(`  ${String(n).padStart(3)}  ${status}`);
+    }
+    const linked = ids.filter((id) => tasks[id].parent_goal_id).length;
+    console.log();
+    console.log(chalk.dim(`  ${linked}/${ids.length} linked to a parent goal`));
+  }
+  console.log();
+  console.log(chalk.dim('  Tip: `dw task index --json` for the machine-readable adapter contract.'));
+  console.log();
+
+  logEvent({ event: 'task', action: opts.check ? 'index.check' : 'index.rebuild', name: ids.length }, rootDir);
+}