dw-kit 1.9.3 → 1.10.0

package/src/lib/goal-events.mjs

@@ -43,7 +43,10 @@ function rotateIfNeeded(file) {
 
 // Issue #14 Bug 1 — same smart truncation as agent-events.mjs adapted for goal events.
 // Identifying fields differ: goal_id + field instead of claim_id + agent_id.
-const GOAL_IDENTIFY_FIELDS = ['ts', 'event', 'goal_id', 'kr_id', 'field', 'changed_by'];
+// Includes trust/autopilot audit fields (gate, actor, reason) so a
+// gate_auto_approved event stays attributable even under hard truncation
+// (review round 2: W-5).
+const GOAL_IDENTIFY_FIELDS = ['ts', 'event', 'goal_id', 'kr_id', 'field', 'changed_by', 'gate', 'actor', 'reason', 'task'];
 
 function smartTruncateGoal(enriched, originalBytes) {
   // Step 1: truncate large string-valued fields like `new` (long summaries) or `staged_files` arrays

package/src/lib/overnight-digest.mjs

@@ -0,0 +1,241 @@
+// Morning-review digest builder for Overnight Autopilot (ADR-0023).
+//
+// An unattended overnight run emits events to .dw/events-global.jsonl; this
+// module turns a run's events into ONE scannable artifact a human reads cold
+// the next morning. Pure functions (buildDigest/summarizeRun) so the output is
+// deterministic and unit-testable; writeDigest handles the filesystem.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+export const DIGEST_SCHEMA_VERSION = 'overnight-digest@v1';
+export const DIGEST_FILE = 'OVERNIGHT.md';
+
+// Event types the autopilot loop emits (subset of events-global.jsonl).
+const EV_DONE = 'subtask_completed';
+const EV_AUTO = 'gate_auto_approved';
+const EV_PARK = 'parked';
+const EV_STOP = 'hard_stop';
+const EV_WRAP = 'overnight_wrapup';
+
+/**
+ * Reduce a run's events into counts + grouped items.
+ * @param {object[]} events
+ */
+export function summarizeRun(events = []) {
+  const done = [];
+  const autoApproved = [];
+  const parked = [];
+  const hardStops = [];
+  let stopReason = 'unknown';
+  let wrapupSeen = false;
+
+  for (const e of events) {
+    switch (e && e.event) {
+      case EV_DONE: done.push(e); break;
+      case EV_AUTO: autoApproved.push(e); break;
+      case EV_PARK: parked.push(e); break;
+      case EV_STOP: hardStops.push(e); break;
+      case EV_WRAP: wrapupSeen = true; if (e.stop_reason) stopReason = e.stop_reason; break;
+      default: break;
+    }
+  }
+
+  return {
+    counts: {
+      done: done.length,
+      parked: parked.length,
+      hardStops: hardStops.length,
+      autoApproved: autoApproved.length,
+    },
+    stopReason,
+    wrapupSeen,
+    done,
+    autoApproved,
+    parked,
+    hardStops,
+  };
+}
+
+/**
+ * The machine-readable read-contract object (overnight-digest@v1). OVERNIGHT.md
+ * is for humans; this is what the schema describes and adapters consume.
+ */
+// Coerce a possibly-missing/odd value to a string or undefined — so projected
+// items always satisfy the overnight-digest@v1 schema regardless of raw event
+// shape (round-3 verify: malformed events must not produce schema-invalid JSON).
+const str = (v) => (v == null ? undefined : String(v));
+const strArr = (v) => (Array.isArray(v) ? v.map(String) : undefined);
+const int = (v) => { const n = Math.trunc(Number(v)); return Number.isFinite(n) ? n : undefined; };
+const nnInt = (v) => { const n = int(v); return n != null && n >= 0 ? n : undefined; }; // schema minimum:0
+const bool = (v) => (typeof v === 'boolean' ? v : undefined);
+const prune = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+
+// Project an evidence object to the schema-typed shape so OVERNIGHT.json stays
+// valid even if an event stored loose types (e.g. tests.exit as a string).
+function projectEvidence(ev) {
+  if (!ev || typeof ev !== 'object') return undefined;
+  const out = {};
+  if (ev.tests && typeof ev.tests === 'object') {
+    out.tests = prune({ command: str(ev.tests.command), passed: int(ev.tests.passed), failed: int(ev.tests.failed), exit: int(ev.tests.exit) });
+  }
+  if (ev.review && typeof ev.review === 'object') {
+    out.review = prune({ critical: nnInt(ev.review.critical), warning: nnInt(ev.review.warning), suggestion: nnInt(ev.review.suggestion) });
+  }
+  if (ev.diff && typeof ev.diff === 'object') {
+    out.diff = prune({ files: int(ev.diff.files), insertions: int(ev.diff.insertions), deletions: int(ev.diff.deletions), within_scope: bool(ev.diff.within_scope) });
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+export function buildDigestData({ events = [], date = new Date().toISOString().slice(0, 10), goal = null } = {}) {
+  const s = summarizeRun(events);
+  return {
+    schema_version: DIGEST_SCHEMA_VERSION,
+    date,
+    goal,
+    counts: s.counts,
+    stopReason: s.stopReason,
+    wrapupSeen: s.wrapupSeen,
+    done: s.done.map((e) => prune({ subtask: str(e.subtask), commit: str(e.commit), summary: str(e.summary) })),
+    autoApproved: s.autoApproved.map((e) => prune({ gate: str(e.gate), task: e.task == null ? null : String(e.task), reason: str(e.reason), evidence: projectEvidence(e.evidence) })),
+    parked: s.parked.map((e) => prune({ item: str(e.item), question: str(e.question), options: strArr(e.options) })),
+    hardStops: s.hardStops.map((e) => prune({ gate: str(e.gate), blocker: str(e.blocker), reason: str(e.reason) })),
+  };
+}
+
+function line(...parts) { return parts.join(' '); }
+
+/**
+ * Render the morning-review digest as Markdown.
+ * @param {object} params
+ * @param {object[]} params.events  run events
+ * @param {string} [params.date]    ISO date string for the header
+ * @param {string} [params.goal]    goal id/title the run pursued
+ */
+export function buildDigest({ events = [], date = new Date().toISOString().slice(0, 10), goal = null } = {}) {
+  const s = summarizeRun(events);
+  const out = [];
+
+  out.push(`# Overnight Autopilot — ${date}`);
+  out.push('');
+  out.push(`> ${DIGEST_SCHEMA_VERSION} · auto-generated from \`.dw/events-global.jsonl\`. Read cold, act on the **⏸ Parked** section, then review the diff.`);
+  if (goal) out.push(`> Goal: ${goal}`);
+  out.push('');
+
+  // 1. Verdict line
+  out.push('## Verdict');
+  out.push(line(
+    `✅ ${s.counts.done} done`,
+    `· ⏸ ${s.counts.parked} parked`,
+    `· 🛑 ${s.counts.hardStops} hard-stops`,
+    `· ⚡ ${s.counts.autoApproved} auto-approved`,
+    `· ⌛ stopped: ${s.stopReason}`,
+  ));
+  // No wrap-up event despite work having happened = the loop may have died
+  // mid-run without the graceful stop ADR-0023 promises. Surface that loudly.
+  // Zero-activity (no events at all) is "no run", not a crash — don't warn
+  // (round-2 verify: 5.4 false-positive fix).
+  const hadActivity = s.counts.done + s.counts.parked + s.counts.hardStops + s.counts.autoApproved > 0;
+  if (!s.wrapupSeen && hadActivity) {
+    out.push('');
+    out.push('> 🛑 **NO WRAP-UP event found — the run may have crashed.** Inspect the working tree and tests manually before resuming; an irreversible step may have been left half-done.');
+  }
+  out.push('');
+
+  // 2. Done
+  out.push('## ✅ Done');
+  if (s.done.length === 0) {
+    out.push('_Nothing completed this run._');
+  } else {
+    for (const e of s.done) {
+      const sha = e.commit ? ` \`${String(e.commit).slice(0, 9)}\`` : '';
+      out.push(`- ${e.subtask || e.summary || 'subtask'}${sha}${e.summary && e.subtask ? ` — ${e.summary}` : ''}`);
+    }
+  }
+  out.push('');
+
+  // 3. Auto-approved
+  out.push('## ⚡ Auto-approved (Trust Mode)');
+  if (s.autoApproved.length === 0) {
+    out.push('_No gates were auto-approved._');
+  } else {
+    for (const e of s.autoApproved) {
+      out.push(`- **${e.gate || 'gate'}**${e.task ? ` (${e.task})` : ''} — ${e.reason || 'trusted'}`);
+      // EVD verify (ADR-0023 §evidence): show the BASIS, not just the outcome,
+      // so a human can spot a call they'd have made differently.
+      const ev = e.evidence;
+      if (ev && typeof ev === 'object') {
+        const bits = [];
+        if (ev.tests) bits.push(`tests ${ev.tests.passed ?? '?'}/${ev.tests.failed ?? '?'} ${Number(ev.tests.exit) === 0 ? '✓' : '✗'}`);
+        if (ev.review) bits.push(`${ev.review.critical ?? '?'} Critical · ${ev.review.warning ?? 0} Warning`);
+        if (ev.diff) bits.push(`diff +${ev.diff.insertions ?? '?'}/−${ev.diff.deletions ?? '?'} in ${ev.diff.files ?? '?'} files${ev.diff.within_scope === false ? ' ⚠ OUT OF SCOPE' : ''}`);
+        if (bits.length) out.push(`    basis: ${bits.join(' · ')}`);
+      }
+    }
+  }
+  out.push('');
+
+  // 4. Parked for you — the section the human acts on
+  out.push('## ⏸ Parked for you');
+  if (s.parked.length === 0) {
+    out.push('_Nothing parked — the agent did not hit an ambiguous or irreversible decision._');
+  } else {
+    for (const e of s.parked) {
+      out.push(`- **${e.item || 'decision'}** — ${e.question || 'needs your call'}`);
+      if (Array.isArray(e.options) && e.options.length) {
+        out.push(`  - options: ${e.options.join(' · ')}`);
+      }
+    }
+  }
+  out.push('');
+
+  // 5. Hard-stops hit
+  out.push('## 🛑 Hard-stops hit');
+  if (s.hardStops.length === 0) {
+    out.push('_No Guard or Critical hard-stop fired._');
+  } else {
+    for (const e of s.hardStops) {
+      out.push(`- **${e.gate || e.blocker || 'hard-stop'}** — ${e.reason || e.blocker || 'blocked'}`);
+    }
+  }
+  out.push('');
+
+  // 6. Review next
+  out.push('## Review next');
+  out.push('```bash');
+  out.push('git log --oneline --since="12 hours ago"   # what landed overnight');
+  out.push('git diff main...HEAD                         # full diff to review');
+  out.push('dw goal status                              # outcome progress');
+  out.push('# resume the loop after you clear parked items:');
+  out.push('dw goal --auto=full --trust');
+  out.push('```');
+  out.push('');
+
+  return out.join('\n');
+}
+
+/**
+ * Write the digest to OVERNIGHT.md, rotating any prior run into
+ * .dw/cache/overnight/{date}.md so history is kept but the root stays a single
+ * current file.
+ */
+export function writeDigest(rootDir, content, { date = new Date().toISOString().slice(0, 10) } = {}) {
+  const target = join(rootDir, DIGEST_FILE);
+  if (existsSync(target)) {
+    const archiveDir = join(rootDir, '.dw', 'cache', 'overnight');
+    if (!existsSync(archiveDir)) mkdirSync(archiveDir, { recursive: true });
+    // Avoid clobbering a prior same-day run's archive (review round 2: W-1).
+    let archive = join(archiveDir, `${date}.md`);
+    for (let n = 1; existsSync(archive); n++) archive = join(archiveDir, `${date}-${n}.md`);
+    try {
+      renameSync(target, archive);
+    } catch (e) {
+      try { process.stderr.write(`⚠  overnight: could not rotate prior ${DIGEST_FILE} (${e.message}) — overwriting.\n`); } catch { /* stderr closed */ }
+    }
+  }
+  const dir = dirname(target);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(target, content, 'utf8');
+  return target;
+}

package/src/lib/tls-helpers.mjs

@@ -10,12 +10,33 @@
 //
 // F-24 fix (G-rgoal-realtime-orch KR-A production-readiness).
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, statSync } from 'node:fs';
+import { join, delimiter } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { networkInterfaces } from 'node:os';
 import { resolveCommandPath } from './spawn-helpers.mjs';
 
+// Whether `cmd` is actually an executable on PATH.
+//
+// `resolveCommandPath` is spawn-oriented: on POSIX it returns `found: true`
+// unconditionally (spawn resolves PATH itself), so it CANNOT answer "is this
+// binary installed?" — trusting its `.found` here false-positived `mkcert` on
+// any Linux box without it. So on POSIX we walk PATH and check for an
+// executable regular file; on Win32 `resolveCommandPath` already does a real
+// PATH+PATHEXT walk, so we defer to it.
+function commandInstalled(cmd) {
+  if (process.platform === 'win32') return resolveCommandPath(cmd).found;
+  const dirs = (process.env.PATH || '').split(delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const p = join(dir, cmd);
+    try {
+      const st = statSync(p);
+      if (st.isFile() && (st.mode & 0o111) !== 0) return true; // any exec bit
+    } catch { /* not here — keep looking */ }
+  }
+  return false;
+}
+
 const TLS_DIR_REL = '.dw/cache/voice/tls';
 const KEY_FILE = 'key.pem';
 const CERT_FILE = 'cert.pem';
@@ -29,10 +50,11 @@ const CERT_DAYS = 3650; // 10y — local cert; we don't rotate often
  * Returns { name: 'mkcert' | 'openssl' | 'none', path: string | null }
  */
 export function detectTlsProvider() {
-  const mkcert = resolveCommandPath('mkcert');
-  if (mkcert.found) return { name: 'mkcert', path: mkcert.path, needsShell: mkcert.needsShell };
-  const openssl = resolveCommandPath('openssl');
-  if (openssl.found) return { name: 'openssl', path: openssl.path, needsShell: openssl.needsShell };
+  for (const name of ['mkcert', 'openssl']) {
+    if (!commandInstalled(name)) continue;
+    const r = resolveCommandPath(name); // path + needsShell details
+    return { name, path: r.path, needsShell: r.needsShell };
+  }
   return { name: 'none', path: null, needsShell: false };
 }
 

package/src/lib/trust.mjs

@@ -0,0 +1,139 @@
+// Trust Mode gate-resolution logic (ADR-0022).
+//
+// `dw:flow` human gates fall into two classes. Trust Mode may auto-approve the
+// *convenience* gates (reversible review of intent/output) when the user opts
+// in; it can NEVER relax the *safety* gates (irreversible / unsafe). This module
+// is the single source of truth for that taxonomy, so the skill, the CLI, and
+// the tests all agree on what is and isn't relaxable.
+
+import { getTrustConfig } from './config.mjs';
+import { logGoalEvent } from './goal-events.mjs';
+
+// Canonical gate ids and their class. Gate ids are the stable contract the
+// skill passes in (mapped from GATE A/B/C/D and the quick-depth Q1/Q2).
+export const GATES = {
+  scope: { class: 'convenience', maps: 'GATE A / Q1', configKey: 'scope' },
+  plan: { class: 'convenience', maps: 'GATE C', configKey: 'plan' },
+  changes: { class: 'convenience', maps: 'GATE D / Q2', configKey: 'changes' },
+  arch: { class: 'safety', maps: 'GATE B (TL architecture sign-off)', configKey: null },
+};
+
+/**
+ * Normalize a one-shot `--trust` flag into a predicate over gate ids.
+ * Accepts:
+ *   true            → trust every convenience gate this run
+ *   "plan"          → trust only that gate
+ *   "scope,plan"    → trust those gates
+ *   ["scope","plan"]→ same
+ *   undefined/false → no one-shot trust
+ */
+export function parseTrustFlag(flag) {
+  if (flag === true) return { all: true, gates: new Set() };
+  if (!flag) return { all: false, gates: new Set() };
+  // CLI passes strings; treat "true"/"all" (the bare `--trust`) as "every convenience gate".
+  const raw = Array.isArray(flag) ? flag : String(flag).split(',');
+  const gates = new Set(raw.map((g) => g.trim().toLowerCase()).filter(Boolean));
+  if (gates.has('true') || gates.has('all')) return { all: true, gates: new Set() };
+  return { all: false, gates };
+}
+
+/**
+ * Decide whether a single gate may be auto-approved.
+ *
+ * @param {object} params
+ * @param {string} params.gate        canonical gate id (see GATES)
+ * @param {object} params.config      loaded dw config (for workflow.trust)
+ * @param {*}      [params.flag]       one-shot `--trust` flag value (this run)
+ * @param {boolean}[params.hasCritical] true when a Critical review finding exists (GATE D)
+ * @param {object} [params.evidence]   EVD verify (ADR-0023): {tests:{exit},review:{critical}} — when
+ *                                     present, criticality/red-tests are derived from the evidence
+ *                                     itself, not just the caller's flag.
+ * @returns {{ autoApprove: boolean, reason: string, gateClass: string }}
+ */
+export function resolveGate({ gate, config, flag, hasCritical = false, evidence, runCount } = {}) {
+  const meta = GATES[gate];
+  if (!meta) {
+    return { autoApprove: false, reason: `unknown gate "${gate}" — manual`, gateClass: 'unknown' };
+  }
+
+  // Invariant: safety hard-stops are structurally unreachable by Trust Mode.
+  if (meta.class === 'safety') {
+    return {
+      autoApprove: false,
+      reason: `safety gate (${meta.maps}) — never auto-approved`,
+      gateClass: 'safety',
+    };
+  }
+
+  // EVD verify (ADR-0023): when evidence is supplied for GATE D, derive the
+  // safety signals from the evidence — stronger than a bare --critical flag the
+  // caller might forget. Evidence that shows a Critical finding or red tests
+  // forces a manual stop even when `changes` is trusted.
+  const criticalFromEvidence = gate === 'changes' && evidence?.review && Number(evidence.review.critical) >= 1;
+  // Only treat tests as failed when a real exit code is present and non-zero.
+  // A `tests` object without `exit` must NOT block (round-2 verify: false positive).
+  const exitCode = Number(evidence?.tests?.exit);
+  const testsFailedFromEvidence = gate === 'changes' && evidence?.tests && Number.isFinite(exitCode) && exitCode !== 0;
+
+  // Invariant: a Critical review finding forces GATE D to a manual stop even
+  // when `changes` is trusted.
+  if (gate === 'changes' && (hasCritical || criticalFromEvidence)) {
+    return {
+      autoApprove: false,
+      reason: 'Critical review finding — manual approval required',
+      gateClass: 'convenience',
+    };
+  }
+  if (testsFailedFromEvidence) {
+    return {
+      autoApprove: false,
+      reason: `tests not green (exit ${evidence.tests.exit}) — manual approval required`,
+      gateClass: 'convenience',
+    };
+  }
+
+  const trust = getTrustConfig(config);
+
+  // require_evidence (ADR-0023 follow-up): when set, GATE D will not auto-approve
+  // without an evidence object citing a REAL numeric review.critical count — an
+  // empty {review:{}} must NOT satisfy it (round-3 verify: bypass via empty object).
+  // Require a real numeric critical count — a boolean `false` or `[]` both coerce
+  // to 0 via Number(), so check the type, not just finiteness (final verify).
+  const hasReviewCount = typeof evidence?.review?.critical === 'number'
+    && Number.isFinite(evidence.review.critical);
+  if (gate === 'changes' && trust.require_evidence && !hasReviewCount) {
+    return {
+      autoApprove: false,
+      reason: 'workflow.trust.require_evidence — supply --evidence with a numeric review.critical count',
+      gateClass: 'convenience',
+    };
+  }
+
+  const oneShot = parseTrustFlag(flag);
+  if (oneShot.all || oneShot.gates.has(gate)) {
+    return { autoApprove: true, reason: `--trust (this run): ${meta.maps}`, gateClass: 'convenience' };
+  }
+
+  if (trust.enabled && trust.auto_approve[meta.configKey]) {
+    // Budget: once an unattended run reaches its cap, stop auto-approving so the
+    // bound is real at the decision point, not just advisory (round-2 verify: W-3).
+    if (trust.max_auto_subtasks > 0 && Number.isInteger(runCount) && runCount >= trust.max_auto_subtasks) {
+      return { autoApprove: false, reason: `budget reached (${runCount}/${trust.max_auto_subtasks} auto-approved) — manual`, gateClass: 'convenience' };
+    }
+    return { autoApprove: true, reason: `workflow.trust.auto_approve.${meta.configKey}`, gateClass: 'convenience' };
+  }
+
+  // Invariant: default is fully manual.
+  return { autoApprove: false, reason: 'manual (Trust Mode off for this gate)', gateClass: 'convenience' };
+}
+
+/**
+ * Audit an auto-approval to .dw/events-global.jsonl so the skipped human is
+ * always recoverable. Invariant 4 of ADR-0022.
+ */
+export function logTrustEvent({ gate, task, reason, evidence }, rootDir = process.cwd()) {
+  return logGoalEvent(
+    { event: 'gate_auto_approved', actor: 'trust-mode', gate, task: task || null, reason: reason || null, evidence: evidence || null },
+    rootDir,
+  );
+}

package/README.vi.md

@@ -1,230 +0,0 @@
-# dw-kit
-
-[🇬🇧 English](README.md) · 🇻🇳 **Tiếng Việt**
-
-[![npm version](https://img.shields.io/npm/v/dw-kit?color=cb3837&logo=npm)](https://www.npmjs.com/package/dw-kit)
-[![downloads](https://img.shields.io/npm/dm/dw-kit?color=blue)](https://www.npmjs.com/package/dw-kit)
-[![node](https://img.shields.io/node/v/dw-kit?color=339933&logo=node.js)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/dw-kit?color=success)](LICENSE)
-
-> **Lớp harness quản trị cho việc dev cùng AI.** Cho con agent code của bạn một quy trình lặp lại được, hàng rào an toàn, và một bộ nhớ sống lâu hơn cửa sổ chat — để nó giao việc đã sẵn-sàng-review thay vì đoán mò đầy tự tin.
-
-```bash
-npm install -g dw-kit && dw init
-```
-
-Sau đó, ngay trong AI IDE của bạn:
-
-```
-/dw:flow làm cái việc bạn thực sự muốn
-```
-
-Xong. `dw` lo phần còn lại — và **dừng lại chờ bạn duyệt** trước khi viết code.
-
-> **Dùng được với bất kỳ AI agent có CLI nào** — Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot. Bản thân CLI `dw` và bộ methodology bằng Markdown là universal: agent của bạn đọc được file và chạy được shell là dùng được dw-kit. Bộ harness *đầy đủ* (hooks, tự động hóa skill, điều phối đa-agent) ở mức hạng-nhất trên **[Claude Code](https://claude.ai/code)**; các agent/IDE còn lại nhận lớp methodology qua generic adapter.
-
----
-
-## Vì sao cần dw-kit?
-
-AI agent nhanh nhưng không nhớ gì: quên ngữ cảnh giữa các session, bỏ qua bước lập kế hoạch, và chẳng có khái niệm "khoan đã, để con người ngó qua cái này trước." dw-kit bọc agent của bạn trong một quy trình gọn nhẹ — giữ lại tốc độ, bỏ đi hỗn loạn.
-
-```
-   Khởi tạo → Khảo sát → Lập KH → Thực thi → Kiểm chứng → Đóng
-       │          │         │         │           │          │
-     scope     đọc      thiết kế    TDD,       quality   handoff
-     + docs    code    (✋ DỪNG    1 commit    gates +    + lưu
-                       chờ OK)    /subtask    review    trữ
-```
-
-- **✋ Checkpoint của con người** — agent dừng ở bước Lập kế hoạch chờ bạn gật đầu, không tự ý phóng tới.
-- **🛡️ Guards** — hook chặn commit secret, `.env`, và sửa đổi nguy hiểm ngay trước khi chúng xảy ra.
-- **🧠 Bộ nhớ sống qua nhiều session** — quyết định, task docs, ghi chú bàn giao giúp session sau tiếp tục từ con số không.
-- **🌏 Song ngữ trọn vẹn** — UX tiếng Anh + tiếng Việt ngay từ đầu.
-
----
-
-## Sinh ra để tự hiệu chỉnh — với bạn trong vòng lặp
-
-Hai cơ chế giữ cho agent trung thực chứ không chỉ "bận rộn".
-
-**Vòng lặp đeo bám — `/dw:goal`.** Phần lớn agent tối ưu cho *"tôi đã làm xong task."* dw-kit tối ưu cho *kết quả*. Đưa cho nó một Goal với các Key Result đo được, nó chạy một vòng lặp kiểu OODA, **đo lại khoảng cách (gap) sau mỗi vòng**. Khi một cách thất bại, nó **nâng cấp tư duy** — leo lên một bậc thang lập luận — chứ không lặp lại nước đi cũ. Nó chỉ thoát khi KR thực sự chạm target, không phải khi hết hơi. *(ADR-0016)*
-
-```
-   đo gap → hành động → đo lại ──┐
-       ▲                         │
-       └──── kẹt? leo bậc ◀───────┘   leo thang, đừng lặp lại
-   chỉ thoát khi Key Result đạt
-```
-
-Độ tự chủ là một núm vặn: **supervised** (dừng mỗi vòng) → **checkpoint** (`--auto`, dừng ở mỗi KR đạt) → **full** (`--auto=full`, chỉ hard-stop), giới hạn bởi `--max-iter`.
-
-**Phản biện đối kháng, rồi tới bạn — `/dw:plan`.** Trước khi một plan tới tay bạn, dw "quay" nó bằng một màn **tranh luận red-team / blue-team**: red tấn công tìm failure mode và giả định ngầm, blue củng cố hoặc nhượng bộ. Bạn nhận được plan *đã được mài sắc* kèm những điểm còn tranh cãi — rồi **việc thực thi dừng lại chờ bạn duyệt.** Phản xạ ấy lặp lại ở bước **Kiểm chứng** (`/dw:review`: tính đúng · bảo mật · convention · độ phủ) và ở mọi commit gate. Agent đề xuất; bạn quyết định và lái.
-
-> Debate tùy theo depth — tắt với `quick`, tự kích hoạt khi phát hiện tín hiệu high-stakes ở `standard`, bật mặc định với `thorough`. Override bằng `--debate` / `--no-debate`.
-
----
-
-## Harness: dw quản trị agent của bạn như thế nào
-
-dw-kit nằm *bên trên* con agent code như một lớp harness quản trị mỏng — ba tầng bền vững mà nó đọc và ghi trong lúc làm việc:
-
-| Tầng | Quản lý | Artifact |
-|------|---------|----------|
-| **Context** | Thứ agent biết, ở mỗi session | `CLAUDE.md`, ADR (`/dw:decision`), ghi chú handoff |
-| **Tasks** | Một nguồn sự thật cho mỗi đơn vị công việc | `task.md` (v3 — lint + schema, chống drift trạng thái), index `ACTIVE.md` |
-| **Goals** | Kết quả ở tầng trên task | `dw goal *`, Key Results, link task ↔ goal |
-
-Vì trạng thái này nằm trong **file thuần, không phải cửa sổ chat**, nó sống qua reset session, đổi model, và bàn giao giữa agent với agent hoặc với người — thứ một trợ lý IDE bó hẹp trong một session về cấu trúc không thể sở hữu.
-
-### Điều phối đa-agent song song (Agent OS)
-
-Một task hiếm khi chỉ cần một agent. **Agent OS** cho phép một orchestrator chia `task.md` thành các đơn vị công việc có ranh giới rồi giao cho *các* agent chạy **song song** — ví dụ Claude Code lo API, Codex lo test, Gemini lo docs, một con người lo phần migration hóc búa:
-
-```bash
-dw agent claim payments --subtasks ST-1 --write "src/api/**" --vendor claude --lease 1h
-dw agent claim payments --subtasks ST-2 --write "test/**"    --vendor codex
-dw agent conflicts        # exit 1 nếu hai claim đè nhau về file hoặc subtask
-```
-
-Mỗi agent **claim** subtask + phạm vi file trước khi sửa, nên việc song song không giẫm chân nhau. Đây là cơ chế **hợp tác, không cưỡng bức**: trùng lặp bị bắt bởi `dw agent conflicts` và hook `pre-commit-gate`, report của từng agent gộp ngược về một `task.md` duy nhất, và **orchestrator dừng chờ bạn duyệt trước khi push.** *(ADR-0009)*
-
----
-
-## Bắt đầu nhanh
-
-```bash
-# 1. Cài đặt
-npm install -g dw-kit
-
-# 2. Thiết lập trong project (wizard, hoặc --solo cho zero-config)
-dw init
-dw init --solo        # chế độ vibe-coder: chỉ guards, không task docs
-
-# 3. Drive một task từ AI IDE
-/dw:flow thêm tính năng đăng nhập
-```
-
-Vài skill khác nên biết:
-
-```
-/dw:prompt      # biến ý tưởng mơ hồ thành prompt sắc, làm được ngay
-/dw:plan        # lập kế hoạch + tự phản biện red/blue, rồi dừng chờ duyệt
-/dw:review      # tính đúng · bảo mật · convention · độ phủ test
-/dw:decision    # ghi lại một quyết định kiến trúc (ADR)
-/dw:goal        # drive một Goal tới các Key Result (vòng lặp đeo bám)
-```
-
----
-
-## Hướng dẫn nhanh: ship tính năng đầu tiên
-
-```bash
-dw init                          # một lần: dựng .dw/ + .claude/ trong repo của bạn
-```
-
-Sau đó, ngay trong Claude Code:
-
-```
-/dw:flow thêm chức năng reset mật khẩu qua email
-```
-
-Diễn biến, theo thứ tự:
-
-1. **Khởi tạo + Khảo sát** — dw chốt phạm vi, dựng `task.md`, và đọc code auth của bạn (chưa sửa gì).
-2. **Lập kế hoạch** — đề xuất subtask, tự phản biện red/blue, rồi **dừng.** Bạn trả lời *"go"* hoặc lái lại.
-3. **Thực thi** — làm từng subtask một, TDD, mỗi subtask một commit (hoặc rải subtask ra cho nhiều agent chạy song song qua Agent OS). Secret / `.env` bị chặn ở gate.
-4. **Kiểm chứng** — chạy test của bạn + một lượt `/dw:review` (tính đúng · bảo mật · convention).
-5. **Đóng** — ghi handoff để session ngày mai tiếp tục mà bạn không phải giải thích lại.
-
-Thích kiểm soát thủ công? Tự chạy từng phase và duyệt giữa mỗi bước:
-
-```
-/dw:plan  →  (bạn review)  →  /dw:execute  →  /dw:review  →  /dw:commit
-```
-
----
-
-## Chọn độ sâu (depth)
-
-Không có cỡ nào vừa cho tất cả. Đặt mặc định, override theo từng task khi rủi ro tăng.
-
-| Depth | Hợp với | Quy trình |
-|-------|---------|-----------|
-| `quick` | Hotfix, code quen, solo | Khảo sát → Thực thi → Đóng |
-| `standard` | Tính năng mới, team nhỏ | Đủ 6 phase |
-| `thorough` | Thay đổi API / DB / bảo mật | Đủ quy trình + arch-review + test-plan + debate |
-
-```yaml
-# .dw/config/dw.config.yml
-workflow:
-  default_depth: "standard"
-```
-
----
-
-## Lệnh cốt lõi
-
-```bash
-dw init [--solo]        # wizard thiết lập / preset (solo · team · enterprise)
-dw doctor               # kiểm tra sức khỏe cài đặt
-dw upgrade [--check]    # cập nhật file toolkit (giữ nguyên tùy biến của bạn)
-dw task new <name>      # tạo khung task doc v3
-dw task show [name]     # ảnh chụp ANSI của một task
-dw goal status          # tiến độ Goals → Key Results
-dw security-scan        # supply-chain guard kiểu AI-native (OSV + heuristic)
-dw dashboard            # task đang chạy + ADR + tóm tắt telemetry
-dw metrics              # telemetry chỉ-cục-bộ (tắt bằng: DW_NO_TELEMETRY=1)
-```
-
-Tham chiếu lệnh đầy đủ và danh mục skill nằm trong [`docs/`](docs/).
-
----
-
-## Thứ được thêm vào repo của bạn
-
-```
-.dw/
-  core/       methodology + PILLARS.md
-  config/     dw.config.yml (+ tùy chọn .local.yml)
-  decisions/  ADR — bản ghi quyết định kiến trúc
-  tasks/      task docs + ACTIVE.md index
-  metrics/    telemetry cục bộ (có thể opt-out)
-.claude/      skills, hooks, agents, rules cho AI IDE của bạn
-CLAUDE.md     ngữ cảnh project agent đọc mỗi session
-```
-
-Tất cả là Markdown + YAML thuần — kiểm toán được, diff được, và là của bạn.
-
----
-
-## 5 trụ cột
-
-dw-kit là một **lớp quản trị ưu tiên ngữ cảnh** (context-first), không phải cỗ máy áp đặt. Năm trụ cột theo động từ:
-
-| Trụ cột | Mục đích | Ví dụ |
-|---------|----------|-------|
-| **Guards** | An toàn trước khi hành động | `privacy-block`, `pre-commit-gate` |
-| **Surfaces** | Làm trạng thái hiện rõ | `ACTIVE.md`, `dw dashboard` |
-| **Records** | Lưu giữ ký ức | ADR, task docs |
-| **Bridges** | Liền mạch qua các session | auto-handoff, `task.md` |
-| **Tunes** | Thích nghi theo hình hài team | preset, config flag |
-
-**Nguyên tắc thiết kế — phép thử lỗi thời:** mỗi tính năng phải trả lời được *"liệu nó có giá trị **hơn** khi AI thông minh hơn không?"* Nếu không, nó bị cắt.
-
-Đặc tả đầy đủ: [`.dw/core/PILLARS.md`](.dw/core/PILLARS.md).
-
----
-
-## Yêu cầu
-
-- **Node.js ≥ 18**
-- Một công cụ code dạng agentic có CLI — [Claude Code](https://claude.ai/code) (harness đầy đủ) hoặc bất kỳ agent / IDE nào khác qua generic adapter (lớp methodology)
-
-## Liên kết
-
-[Changelog](CHANGELOG.md) · [Releases](https://github.com/dv-workflow/dv-workflow/releases) · [Chính sách bảo mật](SECURITY.md) · [Giấy phép (Apache-2.0)](LICENSE)
-
----
-
-Thực hiện tận tâm bởi [huygdv](mailto:huygdv19@gmail.com) · [Báo lỗi](https://github.com/dv-workflow/dv-workflow/issues)