dw-kit 1.8.0-rc.2 → 1.9.0

package/src/lib/task-store.mjs

@@ -0,0 +1,164 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+// DW Document Schema + Index v1.0 (ADR-0017) — task half.
+// Mirrors goal-store.mjs / goals-index@v1: a committed manifest so external
+// adapters read task state from one O(1) file instead of reverse-engineering
+// every task.md.
+
+const TASKS_DIR = '.dw/tasks';
+const INDEX_FILE = '.dw/tasks/tasks-index.json';
+const SCHEMA_VERSION = 'tasks-index@v1';
+
+export function tasksDir(rootDir = process.cwd()) {
+  return join(rootDir, TASKS_DIR);
+}
+
+export function taskFile(taskId, rootDir = process.cwd()) {
+  return join(rootDir, TASKS_DIR, taskId, 'task.md');
+}
+
+export function taskIndexFile(rootDir = process.cwd()) {
+  return join(rootDir, INDEX_FILE);
+}
+
+function nowUtc() {
+  return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+// Stable key order so the same task set always serializes byte-identically,
+// regardless of writer path (syncTaskIndexEntry appends; rebuildTaskIndex uses
+// readdirSync order, which is filesystem-dependent). Without this the two paths
+// disagree and the post-commit hook refresh churns the file (#21).
+function sortTasks(tasks) {
+  const sorted = {};
+  for (const id of Object.keys(tasks || {}).sort()) sorted[id] = tasks[id];
+  return sorted;
+}
+
+// schema_version naming (#22): task frontmatter accepts both the legacy bare
+// form (v3.0/v3.1) and the canonical namespaced form (task@v3.0/task@v3.1) that
+// matches the repo-wide @v convention (goal@v1, *-index@v1). New writes emit the
+// namespaced form; readers tolerate both. `bareSchemaVersion` strips the prefix
+// for version-comparison logic; `canonicalSchemaVersion` adds it for emission.
+export function bareSchemaVersion(v) {
+  if (!v || typeof v !== 'string') return v;
+  return v.startsWith('task@') ? v.slice('task@'.length) : v;
+}
+
+export function canonicalSchemaVersion(v) {
+  if (!v || typeof v !== 'string') return v;
+  return v.startsWith('task@') ? v : `task@${v}`;
+}
+
+function emptyIndex() {
+  return { schema_version: SCHEMA_VERSION, last_updated: nowUtc(), tasks: {} };
+}
+
+export function readTaskIndex(rootDir = process.cwd()) {
+  const file = taskIndexFile(rootDir);
+  if (!existsSync(file)) return emptyIndex();
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || !parsed.tasks) return emptyIndex();
+    return parsed;
+  } catch {
+    return emptyIndex();
+  }
+}
+
+export function writeTaskIndex(index, rootDir = process.cwd()) {
+  const file = taskIndexFile(rootDir);
+  const dir = dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tasks = sortTasks(index.tasks);
+  // Skip the write entirely when the task set is byte-identical to disk: this
+  // keeps the on-disk `last_updated` (the spec freshness signal, ADR-0017) and
+  // guarantees zero git diff. `last_updated` advances only on a real change.
+  const prior = readTaskIndex(rootDir);
+  if (existsSync(file) && JSON.stringify(sortTasks(prior.tasks)) === JSON.stringify(tasks)) {
+    return prior;
+  }
+  const updated = { schema_version: SCHEMA_VERSION, last_updated: nowUtc(), tasks };
+  writeFileSync(file, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+  return updated;
+}
+
+export function listTaskIds(rootDir = process.cwd()) {
+  const dir = tasksDir(rootDir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((entry) => {
+    if (entry === 'archive' || entry === 'ACTIVE.md') return false;
+    try {
+      const path = join(dir, entry);
+      return statSync(path).isDirectory() && existsSync(join(path, 'task.md'));
+    } catch {
+      return false;
+    }
+  });
+}
+
+export function readTask(taskId, rootDir = process.cwd()) {
+  const file = taskFile(taskId, rootDir);
+  if (!existsSync(file)) return null;
+  const content = readFileSync(file, 'utf8');
+  return { fm: parseFrontmatter(content), content, file };
+}
+
+export function extractTaskTitle(content) {
+  const m = content.match(/^#\s+(?:Timeline:|Spec:)?\s*(.+?)\s*$/m);
+  return m ? m[1].trim() : null;
+}
+
+// doc@v1 task projection — consumer-facing fields only (no body text).
+function taskEntry(taskId, rootDir) {
+  const task = readTask(taskId, rootDir);
+  if (!task) return null;
+  const fm = task.fm || {};
+  return {
+    title: extractTaskTitle(task.content) || taskId,
+    status: fm.status || 'Draft',
+    phase: fm.phase || null,
+    owner: fm.owner || 'unknown',
+    depth: fm.depth || null,
+    related_adr: fm.related_adr || null,
+    target_ship: fm.target_ship || null,
+    parent_goal_id: fm.parent_goal_id && fm.parent_goal_id !== 'none' ? fm.parent_goal_id : null,
+    contributing_goal_ids: Array.isArray(fm.contributing_goal_ids) ? fm.contributing_goal_ids : [],
+    summary: fm.summary || null,
+    schema_version: fm.schema_version || null,
+    last_updated: fm.last_updated || new Date().toISOString().slice(0, 10),
+  };
+}
+
+export function syncTaskIndexEntry(taskId, rootDir = process.cwd()) {
+  const entry = taskEntry(taskId, rootDir);
+  if (!entry) return null;
+  const index = readTaskIndex(rootDir);
+  index.tasks[taskId] = entry;
+  writeTaskIndex(index, rootDir);
+  return entry;
+}
+
+export function removeTaskIndexEntry(taskId, rootDir = process.cwd()) {
+  const index = readTaskIndex(rootDir);
+  if (index.tasks[taskId]) {
+    delete index.tasks[taskId];
+    writeTaskIndex(index, rootDir);
+    return true;
+  }
+  return false;
+}
+
+// Authoritative full rebuild — scans .dw/tasks/ and rewrites the index.
+// Idempotency (sorted keys + skip-when-identical) lives in writeTaskIndex, so an
+// unchanged task set produces zero git diff and the stop-check refresh is safe.
+export function rebuildTaskIndex(rootDir = process.cwd()) {
+  const index = emptyIndex();
+  for (const taskId of listTaskIds(rootDir)) {
+    const entry = taskEntry(taskId, rootDir);
+    if (entry) index.tasks[taskId] = entry;
+  }
+  return writeTaskIndex(index, rootDir);
+}

package/src/lib/voice-action.mjs

@@ -150,6 +150,149 @@ function loadAgentsConfig(rootDir) {
   return yaml.load(readFileSync(p, 'utf8')) || { agents: {} };
 }
 
+// F-43/F-47 (owner directive 2026-05-28): the spawned agent should know about
+// common environment friction (SSL/TLS cert, Win32 PATHEXT + .cmd shells,
+// missing CLIs, CRLF/LF, port-in-use, gitignored secrets) and try to
+// diagnose + self-fix before escalating. Anything that touches infra (regen
+// cert, install package, modify env vars) MUST surface for human approval.
+const ENV_FRICTION_HINTS_EN = [
+  `Common environment friction to watch for and self-handle (per owner directive):`,
+  `- SSL/TLS: if HTTPS/curl/git fails with cert errors, check .dw/cache/voice/tls/; on Win32 try \`mkcert -install\` or regenerate via tls-helpers.mjs. If the project must call a vendor with self-signed certs, surface — do NOT silently set NODE_TLS_REJECT_UNAUTHORIZED.`,
+  `- Win32 spawn: claude/codex/gemini ship as .cmd shims; raw spawn(shell:false) fails ENOENT. Use src/lib/spawn-helpers.mjs (resolveCommandPath + spawnAgent). See F-18/F-29/F-40 for the recurring pattern.`,
+  `- Missing CLI: if "claude not on PATH" → ask user to install/reopen terminal; do not try alternative agents without permission.`,
+  `- CRLF/LF: bin/dw.mjs often shows phantom diffs on Win32. Ignore unless a real content change is present.`,
+  `- Port in use: 4500 is the voice server default; if EADDRINUSE, find the existing server (Get-CimInstance Win32_Process | Where CommandLine -like '*dw.mjs voice*') and reconcile before relaunching.`,
+  `- Gitignored secrets: never commit .dw/cache/voice/voice.token, .dw/config/connectors.local.yml, or anything under .dw/cache/. The privacy-block hook will reject; respect it.`,
+  `- Anything that touches infra (cert install, env vars, dependency add) → STOP and surface for human approval before applying.`,
+].join('\n');
+const ENV_FRICTION_HINTS_VI = [
+  `Các friction môi trường thường gặp — tự chẩn đoán và xử lý nếu được (theo owner directive):`,
+  `- SSL/TLS: nếu HTTPS/curl/git lỗi cert, kiểm tra .dw/cache/voice/tls/; trên Win32 thử \`mkcert -install\` hoặc regenerate qua tls-helpers.mjs. Nếu phải gọi vendor có self-signed cert, BÁO LẠI — TUYỆT ĐỐI KHÔNG silently set NODE_TLS_REJECT_UNAUTHORIZED.`,
+  `- Win32 spawn: claude/codex/gemini là .cmd shims; raw spawn(shell:false) ENOENT. Dùng src/lib/spawn-helpers.mjs (resolveCommandPath + spawnAgent). Xem F-18/F-29/F-40.`,
+  `- Thiếu CLI: nếu "claude not on PATH" → hỏi user cài lại / mở terminal mới; KHÔNG tự đổi sang agent khác mà không xin phép.`,
+  `- CRLF/LF: bin/dw.mjs hay show diff giả trên Win32. Bỏ qua trừ khi có content change thật.`,
+  `- Port in use: 4500 mặc định cho voice server; nếu EADDRINUSE, tìm process cũ (Get-CimInstance Win32_Process | Where CommandLine -like '*dw.mjs voice*') và reconcile trước.`,
+  `- Secret bị gitignored: KHÔNG commit .dw/cache/voice/voice.token, .dw/config/connectors.local.yml, hoặc bất cứ thứ gì trong .dw/cache/. privacy-block hook sẽ reject; tôn trọng.`,
+  `- Bất cứ gì touch infra (cert install, env vars, thêm dependency) → DỪNG và báo human approve trước khi áp dụng.`,
+].join('\n');
+
+// F-43: bare goal_id arg → full task-execution prompt. When the user says
+// "khởi động agent cho goal X" / "start agent for goal X", the orchestrator
+// often emits goal="G-X" — just an identifier. The spawned `claude --print`
+// has no instruction what to DO and defaults to "explain this" mode (one-shot
+// status reply, then exit). Expanding the id into a real task prompt gives
+// the agent enough scaffolding to actually work on the goal autonomously.
+//
+// Exported for tests.
+export function expandGoalIdToTaskPrompt(goalArg, rootDir, lang = 'en') {
+  if (typeof goalArg !== 'string') return goalArg;
+  const trimmed = goalArg.trim();
+  // Case 1: bare goal_id (G-{alphanumeric/hyphen, ≤32}) → expand from goal.md.
+  // Case 2 (F-47): short topic phrase (≤80 chars, no newlines, looks like a
+  // topic not a sentence) → wrap with a discovery preamble that tells the
+  // agent to grep .dw/goals/ for the topic and pick the matching goal before
+  // continuing per F-43. This catches the common voice flow where the user
+  // says "start agent for goal multi-agent" and the orchestrator emits
+  // goal="the multi-agent orchestration goal" — 47 chars of topic, no id.
+  const isBareGoalId = /^G-[A-Za-z0-9_-]{1,32}$/.test(trimmed);
+  const isShortTopic = !isBareGoalId
+    && !trimmed.includes('\n')
+    && trimmed.length > 0
+    && trimmed.length <= 80
+    // Likely-topic heuristic: must explicitly mention goal/task/rgoal/KR.
+    // Don't trigger on short generic prompts like "fix login bug" — only when
+    // the user (or orchestrator) clearly intended to reference a goal/task.
+    && /\b(goal|task|rgoal|kr-?[a-z]|mục tiêu|nhiệm vụ)\b/i.test(trimmed);
+
+  if (!isBareGoalId && !isShortTopic) return goalArg;
+
+  if (isBareGoalId) {
+    const goalDir = join(rootDir, '.dw', 'goals', trimmed);
+    const goalFile = join(goalDir, 'goal.md');
+    if (!existsSync(goalFile)) return goalArg; // unknown goal — leave for the agent to discover
+  }
+
+  // F-47 short topic branch: build discovery preamble + full workflow.
+  if (isShortTopic) {
+    const L = lang === 'vi' ? 'vi' : 'en';
+    if (L === 'vi') {
+      return [
+        `Người dùng yêu cầu làm việc trên topic: "${trimmed}".`,
+        ``,
+        `Bước 1 — Discovery:`,
+        `- Đọc .dw/goals/goals-index.json để xem danh sách goal_id + title.`,
+        `- Match "${trimmed}" với goal_id phù hợp nhất (so khớp keyword hoặc title substring).`,
+        `- Nếu không có match rõ ràng, ưu tiên goal Active gần đây nhất phù hợp ngữ cảnh.`,
+        ``,
+        `Bước 2 — Execute (theo F-43 workflow):`,
+        `1. Đọc .dw/goals/<matched-id>/goal.md (Section 1 + 3 + 5).`,
+        `2. Tìm linked task qua frontmatter "Linked tasks" hoặc grep parent_goal_id: <matched-id> trong .dw/tasks/.`,
+        `3. Đọc task.md v3 (Section 3 Subtask Tracker) — chọn subtask đầu tiên ⬜ Pending hoặc 🟡 In Progress.`,
+        `4. Thực hiện subtask (TDD nếu code thay đổi). Update Section 3 status sau mỗi subtask.`,
+        `5. Commit theo .claude/rules/commit-standards.md (English imperative, KHÔNG đính kèm Co-Authored-By: Claude).`,
+        `6. DỪNG trước push/release — báo cáo state hiện tại để human review.`,
+        ``,
+        ENV_FRICTION_HINTS_VI,
+        ``,
+        `Nếu KHÔNG có goal match cho "${trimmed}", báo lại và đề xuất tạo goal mới.`,
+      ].join('\n');
+    }
+    return [
+      `User asked to work on topic: "${trimmed}".`,
+      ``,
+      `Step 1 — Discovery:`,
+      `- Read .dw/goals/goals-index.json to list goal_id + title pairs.`,
+      `- Match "${trimmed}" against the closest goal_id (keyword overlap or title substring).`,
+      `- If no obvious match, prefer the most recent Active goal that fits context.`,
+      ``,
+      `Step 2 — Execute (per F-43 workflow):`,
+      `1. Read .dw/goals/<matched-id>/goal.md (Sections 1 + 3 + 5).`,
+      `2. Find the linked task via frontmatter "Linked tasks" or grep parent_goal_id: <matched-id> under .dw/tasks/.`,
+      `3. Read task.md v3 (Section 3 Subtask Tracker) — pick the first ⬜ Pending or 🟡 In Progress subtask.`,
+      `4. Execute the subtask (TDD if code changes). Update Section 3 status after each subtask.`,
+      `5. Commit per .claude/rules/commit-standards.md (English imperative, do NOT append Co-Authored-By: Claude).`,
+      `6. STOP before push/release — surface the diff + state for human review.`,
+      ``,
+      ENV_FRICTION_HINTS_EN,
+      ``,
+      `If NO goal matches "${trimmed}", report back and propose creating a new one.`,
+    ].join('\n');
+  }
+  const L = lang === 'vi' ? 'vi' : 'en';
+  if (L === 'vi') {
+    return [
+      `Tiếp tục thực hiện goal ${trimmed}.`,
+      ``,
+      `Quy trình bắt buộc:`,
+      `1. Đọc .dw/goals/${trimmed}/goal.md để load context (Section 1 Snapshot + Section 3 KR table + Section 5 Friction Journal).`,
+      `2. Tìm linked task qua "Linked tasks" trong frontmatter, hoặc grep parent_goal_id: ${trimmed} trong .dw/tasks/.`,
+      `3. Đọc task.md v3 (Section 3 Subtask Tracker) — chọn subtask đầu tiên có status ⬜ Pending hoặc 🟡 In Progress.`,
+      `4. Thực hiện subtask (TDD nếu code thay đổi). Update Section 3 status + Section 4 timeline sau mỗi subtask.`,
+      `5. Commit theo .claude/rules/commit-standards.md (English imperative, KHÔNG đính kèm Co-Authored-By: Claude).`,
+      `6. DỪNG trước push/release — báo cáo diff + state hiện tại để human review.`,
+      ``,
+      ENV_FRICTION_HINTS_VI,
+      ``,
+      `Nếu không có v3 task cho goal này, scaffold trước bằng "dw task new <name>". Nếu mọi subtask đã ✅ Done, báo cáo và đề xuất task tiếp theo.`,
+    ].join('\n');
+  }
+  return [
+    `Continue execution of goal ${trimmed}.`,
+    ``,
+    `Required workflow:`,
+    `1. Read .dw/goals/${trimmed}/goal.md to load context (Section 1 Snapshot + Section 3 KR table + Section 5 Friction Journal).`,
+    `2. Find the linked task via the "Linked tasks" field in frontmatter, or grep parent_goal_id: ${trimmed} under .dw/tasks/.`,
+    `3. Read the task.md v3 (Section 3 Subtask Tracker) — pick the first subtask with status ⬜ Pending or 🟡 In Progress.`,
+    `4. Execute the subtask (TDD if code changes). Update Section 3 status + Section 4 timeline after each subtask.`,
+    `5. Commit per .claude/rules/commit-standards.md (English imperative, do NOT append Co-Authored-By: Claude).`,
+    `6. STOP before push/release — surface the diff + current state for human review.`,
+    ``,
+    ENV_FRICTION_HINTS_EN,
+    ``,
+    `If no v3 task exists for this goal, scaffold one with "dw task new <name>" first. If every subtask is ✅ Done, report status and propose the next task.`,
+  ].join('\n');
+}
+
 /**
  * Execute a validated action against session-store. Returns:
  *   { ok, display, spoken, data }
@@ -186,6 +329,20 @@ export async function executeAction({ name, args, rootDir, lang = 'en-US' }) {
   }
 
   if (name === 'start_session') {
+    // F-43 (Critical): when args.goal is just a bare goal_id (e.g.
+    // "G-rgoal-realtime-orch"), claude --print receives only 23 chars and
+    // has no instruction what to DO — defaults to "explain this" mode →
+    // one-shot status report → exit. Expand bare goal_id into a full task
+    // prompt that tells the spawned agent to read the goal file + linked
+    // task and continue execution. The expansion is also handled by the
+    // orchestrator system prompt (Layer 2), but this is the safety net
+    // for direct callers + sloppy LLM outputs.
+    const originalGoal = args.goal;
+    const expanded = expandGoalIdToTaskPrompt(args.goal, rootDir, L);
+    const goalWasExpanded = expanded !== args.goal;
+    if (goalWasExpanded) {
+      args.goal = expanded;
+    }
     if (args.goal.length > GOAL_MAX_LEN) {
       return { ok: false, display: `Error: goal too long (${args.goal.length}>${GOAL_MAX_LEN})`, spoken: L === 'vi' ? 'Mục tiêu quá dài.' : 'Goal too long.' };
     }
@@ -227,6 +384,14 @@ export async function executeAction({ name, args, rootDir, lang = 'en-US' }) {
       }
       updateSessionStatus(state.session_id, { pid: child.pid, status: 'running' }, rootDir);
       appendEvent(state.session_id, { event: 'started', pid: child.pid, command: def.command, goal_mode: mode, via: 'voice-action' }, rootDir);
+      if (goalWasExpanded) {
+        appendEvent(state.session_id, {
+          event: 'goal_expanded',
+          from: originalGoal,
+          to_chars: args.goal.length,
+          reason: 'F-43: bare goal_id expanded to full task prompt',
+        }, rootDir);
+      }
       if (useDetached) child.unref();
       closeFd(fd);
       return {

package/src/lib/voice-parser.mjs

@@ -109,6 +109,19 @@ const COMMAND_TABLE = [
     // <goal>" still works for explicit cases, but ambiguous natural phrasings
     // ("start claude với mục tiêu là...") now correctly fall through to the
     // orchestrator (LLM is better at parsing intent than regex).
+    // ADR-0015: debate trigger comes BEFORE start so "debate <topic>" isn't
+    // misread as "start a session for debate" (start patterns are looser).
+    name: 'debate',
+    patterns: [
+      /^(?:let'?s\s+)?debate\s*:?\s+(.+)$/i,
+      /^compare\s+(?:claude\s+and\s+codex|codex\s+and\s+claude|agents)\s+on\s+(.+)$/i,
+      /^tranh\s+luận\s*:?\s+(.+)$/i,
+      // VN mix: "tranh luận về <topic>" / "debate về <topic>"
+      /^(?:tranh\s+luận|debate)\s+về\s+(.+)$/i,
+    ],
+    extract: (m) => ({ topic: (m[1] || '').trim() }),
+  },
+  {
     name: 'start',
     patterns: [
       /^start\s+(?:a\s+)?(?:new\s+)?(?:session\s+)?(?:with|using)\s+([\w_-]+)(?:\s+(?:to\s+|for\s+|on\s+|doing\s+)?(.+))?$/i,

package/.dw/config/connectors.local.yml

@@ -1,38 +0,0 @@
-# .dw/config/connectors.local.yml — GITIGNORED. Secrets live here.
-# Created/updated by `dw connector telegram setup`.
-# Token + allow-list overrides the template in .dw/config/connectors.yml.
-telegram:
-  enabled: true
-  bot_token: 8693679403:AAG9FrgUd5Ig9eDTAWnA9RqhbMnShRi3Si0
-  allowed_user_ids:
-    - 6603235862
-
-# Voice channel (Phase 4 substrate of G-rgoal-realtime-orch).
-# `dw voice` boots a localhost HTTP server with a browser page using Web
-# Speech API for ASR + TTS. Optional orchestrator hybrid: when the regex
-# parser misses, hand the transcript to the configured agent (Claude Code /
-# Codex / Gemini) with a voice-aware system prompt.
-voice:
-  # Default UI language for SpeechRecognition + TTS. User can override on the
-  # page via dropdown. Common values: en-US · vi-VN · ja-JP · ko-KR · zh-CN.
-  # Browser support varies — Chrome / Edge / Safari are best.
-  lang: en-US
-  # Extra languages to surface in the dropdown (beyond `lang` + en-US default).
-  extra_langs: [vi-VN]
-  # Server-side TTS fallback when no native browser/OS voice matches the
-  # selected language. F-23 (G-dogfood-v1.7): a fresh Windows install has
-  # no Vietnamese SAPI voice; we proxy MP3 from Google Translate's public
-  # TTS endpoint. Modes:
-  #   auto    — only when no native voice matches (default; balanced)
-  #   always  — always use server-side (best for cross-machine consistency)
-  #   none    — never use server-side (privacy: spoken text stays local)
-  # Privacy note: in `auto`/`always`, the spoken text leaves the machine to
-  # translate.google.com. Disable with `none` if that is unacceptable.
-  fallback_tts: auto
-  orchestrator:
-    enabled: true          # opt-in. To enable WITHOUT committing it, add the
-                             # same `voice:` section to `.dw/config/connectors.local.yml`
-                             # (gitignored) — the local file overrides this template
-                             # via deep-merge (same pattern as bot_token + allow-list).
-    agent: claude            # must exist in .dw/config/agents.yml; CLI must be on PATH
-    timeout_ms: 30000        # max wait per turn (Claude is typically 2-8s)

package/.dw/core/PILLARS.md

@@ -1,122 +0,0 @@
-# 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/CLAUDE.md

@@ -1,44 +0,0 @@
-# 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.8.0-rc.1** (2026-05-25) — 4/5 phase substrate for [G-rgoal-realtime-orch](.dw/goals/G-rgoal-realtime-orch/goal.md) voice-meeting Root Goal: persistent CLI-agent session runtime (`dw session *`), Telegram chat bridge (`dw connector telegram setup`) with 1-command interactive wizard, multi-workspace registry (`dw workspace *`), and browser voice MVP (`dw voice`) with hybrid orchestrator fallback (Claude/Codex/Gemini), full bilingual UX (en + vi), voice-not-installed fallback via Google Translate TTS proxy. **v1.7.0 stable** on `main` (2026-05-24). 284/284 smoke tests. Active ADRs: ADR-0001 (Pragmatic Lean), ADR-0005/0006 (Supply-Chain Guard; sunset review 2026-08-12), ADR-0008 (Task Docs v3, v1.5), ADR-0009 (Agent OS, v1.6), ADR-0010 (Goals Layer, v1.7), ADR-0011 (Session Runtime + Voice Orchestrator, v1.8 — Accepted).
-
----
-
-## 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 task.md v3 / tracking.md v2)
-  metrics/    Local telemetry (events.jsonl)
-  config/     dw.config.yml
-  security/   IoC namespace fixture (Guards pillar — ADR-0005)
-  research/   Investigation notes, RFC-style proposals, voter panel outputs
-```
-
-## 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