openmoneta-dev-kit 2.0.2 → 2.2.0

package/VERSION

@@ -1 +1 @@
-2.0.2
+2.2.0

package/hooks/inject-process-context.sh

@@ -59,7 +59,7 @@ SUMMARY='# OpenMoneta Dev Kit v1.7.0 — Quy trình 6 bước (Adaptive Planning
 - **B2 Thiết kế** (skill `module-architect`): SRP 1 module 1 trách nhiệm. Feature mới có concept riêng → module mới (KHÔNG nhét utils/common/shared). Existing project: backfill `docs/modules/<slug>/README.md` 3 sections nếu thiếu. Module mới → thêm keyword vào Token Routing.
 - **B3 Adaptive Plan** (skill `plan-writer`): task nhỏ/rõ → không cần plan. Task lớn/rủi ro/mơ hồ → tạo repo plan `Status: Draft`, trình user review, chỉ code sau khi user approve và đổi `Status: In Progress`.
 - **B4 Triển khai**: nếu có plan active → chỉ edit file trong scope plan. Không plan → chỉ sửa đúng yêu cầu; nếu vượt ngưỡng/rủi ro → dừng tạo plan Draft.
-- **B5 Update doc + close** (hook `verify-completion` Check 6 enforce): sync module README (Public API + Dependencies). Plan → `Status: Done` + auto-archive `git mv plans/<f>.md plans/archive/`.
+- **B5 Update doc + close** (hook `verify-completion` Check 6 enforce): chạm module nào → sync README module đó NGAY trong session (Trách nhiệm/Public API/Dependencies + ràng buộc; Check 6 nudge nếu README không đổi). Thay đổi chạm kiến trúc mà KHÔNG có plan → vẫn phải tạo ADR (`decision-recorder`); Check 12 nudge khi đổi đáng kể mà thiếu ADR. Plan → `Status: Done` + auto-archive `git mv plans/<f>.md plans/archive/`.
 - **B6 Pre-push Sync + Safe Push** (skill `safe-push`, CONDITIONAL): chỉ khi user yêu cầu push/commit+push. `git fetch` + rebase trước push, conflict code logic → hỏi user, verify lại, `git push` thường, retry ≤3, KHÔNG `--force` shared branch.
 
 ## Sub-agents (delegate khi cần)

package/hooks/verify-completion.sh

@@ -113,12 +113,17 @@ if [[ -x "$LIST_MODULES_SCRIPT" || -f "$LIST_MODULES_SCRIPT" ]]; then
   AFFECTED=$(bash "$LIST_MODULES_SCRIPT" "$CHANGES_FILE" 2>/dev/null || true)
 
   if [[ -n "$AFFECTED" ]]; then
+    # Danh sách path đã đổi trong session (để check README freshness — Tuyến 1).
+    CHANGED_PATHS=$(jq -r '.changes[] | .path' "$CHANGES_FILE" 2>/dev/null || true)
     while IFS=$'\t' read -r slug docs_path source_path; do
       [[ -z "$slug" ]] && continue
       MODULE_README="$WORKSPACE/$docs_path/README.md"
 
       if [[ ! -f "$MODULE_README" ]]; then
         ISSUES+=("❌ Module '$slug' (source: $source_path) bị sửa nhưng chưa có '$docs_path/README.md'. Tạo README 3 sections (Trách nhiệm + Public API + Dependencies) theo skill module-architect Bước 2.2 + cập nhật bảng 'Modules hiện có' và 'Token Routing' trong docs/INDEX.md.")
+      elif [[ "$LOOP_COUNT" -eq 0 ]] && ! printf '%s\n' "$CHANGED_PATHS" | grep -qFx "$docs_path/README.md"; then
+        # README freshness (nudge mềm 1 lần): module source đổi nhưng README chưa sync trong session.
+        ISSUES+=("⚠️→ Module '$slug' bị sửa source nhưng '$docs_path/README.md' KHÔNG được cập nhật trong session. Nếu có đổi Public API / Trách nhiệm / Dependencies / ràng buộc → sync README NGAY (skill module-architect Bước 5). Nếu chỉ fix nội bộ không đổi hợp đồng → bỏ qua, kết thúc lại lần nữa (nhắc 1 lần).")
       fi
     done <<< "$AFFECTED"
 
@@ -159,16 +164,34 @@ if [[ -n "$CHANGED_DECISIONS" ]]; then
 fi
 
 # Check 11: plan trong session khai báo đổi/đảo kiến trúc nhưng KHÔNG sinh/sửa ADR
+ARCH_DECLARED=0
 for plan in $ALL_RECENT_PLANS; do
   [[ -z "$plan" || ! -f "$plan" ]] && continue
   if grep -qE "^##[[:space:]]+Quyết định kiến trúc" "$plan" 2>/dev/null; then
     DECL=$(awk '/^##[[:space:]]+Quyết định kiến trúc/{flag=1; next} flag && /^##[[:space:]]/{exit} flag {print}' "$plan" | grep -iE 'supersede|đổi kiến trúc|revert|đảo ngược' || true)
-    if [[ -n "$DECL" && -z "$CHANGED_DECISIONS" ]]; then
-      ISSUES+=("❌ Plan '$(basename "$plan")' có '## Quyết định kiến trúc' khai báo đổi/đảo kiến trúc nhưng KHÔNG có docs/decisions/*.md được tạo/cập nhật. Tạo/supersede ADR (skill decision-recorder) trước khi đóng session.")
+    if [[ -n "$DECL" ]]; then
+      ARCH_DECLARED=1
+      if [[ -z "$CHANGED_DECISIONS" ]]; then
+        ISSUES+=("❌ Plan '$(basename "$plan")' có '## Quyết định kiến trúc' khai báo đổi/đảo kiến trúc nhưng KHÔNG có docs/decisions/*.md được tạo/cập nhật. Tạo/supersede ADR (skill decision-recorder) trước khi đóng session.")
+      fi
     fi
   fi
 done
 
+# Check 12: thay đổi "đáng kể" KHÔNG qua plan kiến trúc + KHÔNG có ADR → nudge mềm 1 lần.
+# Backstop cho ca sửa code chạm kiến trúc nhưng không tạo plan (Check 11 không bắt được).
+# Ngưỡng CHẶT (≥4 module HOẶC ≥12 file code) để hiếm khi kêu, tránh false-positive.
+if [[ "$LOOP_COUNT" -eq 0 && -f "$WORKSPACE/docs/decisions/INDEX.md" && -z "$CHANGED_DECISIONS" && "$ARCH_DECLARED" -eq 0 ]]; then
+  NUM_CODE_FILES=$(jq -r '.changes[] | .path' "$CHANGES_FILE" 2>/dev/null \
+    | grep -vE '^(docs/|plans/|README|\.gitignore|\.env\.example|AGENTS\.md|\.cursor/|CHANGELOG|VERSION$|package(-lock)?\.json|pnpm-lock|yarn\.lock)' \
+    | grep -cvE '^$' || true)
+  NUM_CODE_FILES=${NUM_CODE_FILES:-0}
+  NUM_MODULES=${NUM_MODULES:-0}
+  if [[ "$NUM_MODULES" -ge 4 || "$NUM_CODE_FILES" -ge 12 ]]; then
+    ISSUES+=("⚠️→ Session đụng $NUM_MODULES module / $NUM_CODE_FILES file code nhưng KHÔNG tạo/sửa ADR nào và KHÔNG có plan khai báo kiến trúc. NẾU đây là quyết định kiến trúc (đổi data flow, đổi cách module giao tiếp, thay/đảo 1 cơ chế, fix bug bằng cách đổi thiết kế) → tạo ADR (skill decision-recorder) hoặc nâng lên plan TRƯỚC khi đóng. Nếu chỉ là thay đổi thường (refactor nội bộ, đổi text, thêm field) → bỏ qua, kết thúc lại lần nữa (nhắc 1 lần).")
+  fi
+fi
+
 # === Output ===
 WARN_STR=""
 if [[ ${#WARNINGS[@]} -gt 0 ]]; then

package/opencode/AGENTS.md.tpl

@@ -16,11 +16,11 @@
 - **B1 Phân tích** (skill `requirement-analysis`): Read `docs/INDEX.md` → match Token Routing → đọc README module liên quan → đọc source → hỏi clarify nếu yêu cầu chưa rõ (ghi vào `## Hiểu yêu cầu` của plan). **Nếu có `docs/decisions/INDEX.md`: PHẢI đọc nó + ADR liên quan trước khi đổi kiến trúc** (plugin guard chặn read source nếu chưa đọc `docs/decisions/`). Muốn đảo kiến trúc đã chốt → supersede tường minh (skill `decision-recorder`), chống flip-flop A1→B1→A1.
 - **B2 Thiết kế** (skill `module-architect`): SRP 1 module 1 trách nhiệm. Feature có concept riêng → module mới (KHÔNG nhét utils/common/shared). **Module có source nhưng chưa có doc → BẮT BUỘC backfill `docs/modules/<slug>/README.md` 3 sections (Trách nhiệm + Public API + Dependencies)** trước khi sang B4. Module mới → thêm keyword vào Token Routing của `docs/INDEX.md`.
 - **B3 Adaptive Plan** (skill `plan-writer`): task nhỏ/rõ → không cần plan. Task lớn/rủi ro/mơ hồ → tạo repo plan `Status: Draft`, trình user review, chỉ code sau khi user approve và đổi `Status: In Progress`. Plan đổi/đảo kiến trúc → thêm section `## Quyết định kiến trúc` (`Supersede ADR-NNNN` + lý do root cause cũ hết đúng).
-- **B4 Triển khai**: có plan active → chỉ edit file trong scope plan; không plan → chỉ sửa đúng yêu cầu. Mỗi sub-task xong → tick `- [x]`.
+- **B4 Triển khai**: có plan active → chỉ edit file trong scope plan; không plan → chỉ sửa đúng yêu cầu. Mỗi sub-task xong → tick `- [x]`. **Bug-fix hoá ra chạm kiến trúc** (đổi data flow / cách module giao tiếp / thay-đảo cơ chế) → nâng lên B3 hoặc tạo ADR, KHÔNG âm thầm sửa.
 - **B5 Update doc + close plan** — **mandatory closing checklist** (plugin guard `event:session.idle` sẽ re-prompt nếu thiếu):
-  - [ ] Sync `docs/modules/<slug>/README.md` cho mọi module bị sửa: **Trách nhiệm + Public API + Dependencies**.
+  - [ ] Sync `docs/modules/<slug>/README.md` cho MỌI module bị sửa NGAY trong session: **Trách nhiệm + Public API + Dependencies** (+ **Lưu ý/Ràng buộc** nếu có invariant mới). Guard Check 6 nudge nếu module source đổi mà README không đổi.
   - [ ] Module mới đã có trong bảng "Modules hiện có" + "Token Routing" của `docs/INDEX.md`.
-  - [ ] Nếu session đổi kiến trúc → tạo/supersede ADR trong `docs/decisions/` + link vào README module + cập nhật `docs/decisions/INDEX.md` (skill `decision-recorder`).
+  - [ ] Nếu session đổi kiến trúc (kể cả KHÔNG có plan) → tạo/supersede ADR trong `docs/decisions/` + link vào README module + cập nhật `docs/decisions/INDEX.md` (skill `decision-recorder`). Guard Check 12 nudge khi đổi đáng kể (≥4 module / ≥12 file) mà thiếu ADR.
   - [ ] Plan → `Status: Done` + tick mọi checkbox.
   - [ ] **AUTO-ARCHIVE**: `git mv plans/<file>.md plans/archive/<file>.md` + update `plans/INDEX.md` (Active → Archived).
 - **B6 Pre-push Sync + Safe Push** (skill `safe-push`, CONDITIONAL): chỉ khi user yêu cầu push. `git fetch` + rebase trước push, conflict logic → hỏi user, `git push` thường, KHÔNG `--force` shared branch.
@@ -32,7 +32,7 @@
 - OpenMoneta skills được cài vào `~/.config/opencode/skills/*/SKILL.md` và agent nên load bằng skill tool khi cần.
 - **Bảo trì doc dự án cũ** (ON-DEMAND): khi user yêu cầu tạo/refresh docs còn thiếu hoặc lỗi thời, chạy `bash ~/.config/opencode/scripts/docs-audit.sh` để soi rồi load skill `docs-maintenance` (backfill MISSING + refresh STALE + sync `docs/INDEX.md`).
 - OpenMoneta subagents được cài vào `~/.config/opencode/agents/`.
-- OpenCode plugin guard trong `~/.config/opencode/plugins/openmoneta-guard.ts` enforce workflow tương đương Cursor hooks: `tool.execute.before` (docs-first + decisions-read gate + plan gate), `tool.execute.after` (track changes), và `event:session.idle` (verify B2/B5 + ADR integrity: module README, close plan, supersede ADR, re-prompt nhắc hoàn tất với loop guard ≤4 lần).
+- OpenCode plugin guard trong `~/.config/opencode/plugins/openmoneta-guard.ts` enforce workflow tương đương Cursor hooks: `tool.execute.before` (docs-first + decisions-read gate + plan gate), `tool.execute.after` (track changes), và `event:session.idle` (verify B2/B5 + ADR integrity: module README tồn tại + freshness nudge (Check 6), close plan, supersede ADR (Check 10/11), ADR backstop khi đổi đáng kể không plan (Check 12), re-prompt nhắc hoàn tất với loop guard ≤4 lần).
 
 ## Khi Bắt Đầu Task
 

package/opencode/plugins/openmoneta-guard.ts

@@ -320,8 +320,10 @@ function planHasUnderstanding(planPath: string): boolean {
   return foundHeading && hasContent
 }
 
-// Build danh sách issue tương đương verify-completion Check 5/6/9.
-function buildVerifyIssues(root: string): string[] {
+// Build danh sách issue tương đương verify-completion Check 5/6/9/10/11/12.
+// firstNudge = true khi đây là lần re-prompt đầu (verify-loop count === 0) — dùng cho
+// các nudge mềm "1 lần" (README freshness + Check 12 ADR backstop), parity với LOOP_COUNT == 0.
+function buildVerifyIssues(root: string, firstNudge = true): string[] {
   const paths = readSessionChanges(root)
   if (paths.length === 0) return []
   if (!paths.some((p) => !NON_CODE_CHANGE.test(p))) return []
@@ -366,11 +368,17 @@ function buildVerifyIssues(root: string): string[] {
     }
   }
 
-  // Check 6: module bị sửa phải có docs/modules/<slug>/README.md
+  // Check 6: module bị sửa phải có docs/modules/<slug>/README.md (+ README freshness — Tuyến 1)
   for (const { slug, docsPath } of inferModules(paths)) {
-    if (!fs.existsSync(path.join(root, docsPath, "README.md"))) {
+    const readmeRel = `${docsPath}/README.md`
+    if (!fs.existsSync(path.join(root, readmeRel))) {
       issues.push(
-        `❌ Module '${slug}' bị sửa nhưng thiếu '${docsPath}/README.md'. Tạo README 3 sections (Trách nhiệm + Public API + Dependencies) + cập nhật docs/INDEX.md (Bước 2/5).`,
+        `❌ Module '${slug}' bị sửa nhưng thiếu '${readmeRel}'. Tạo README 3 sections (Trách nhiệm + Public API + Dependencies) + cập nhật docs/INDEX.md (Bước 2/5).`,
+      )
+    } else if (firstNudge && !paths.includes(readmeRel)) {
+      // README freshness (nudge mềm 1 lần): module source đổi nhưng README chưa sync.
+      issues.push(
+        `⚠️→ Module '${slug}' bị sửa source nhưng '${readmeRel}' KHÔNG được cập nhật trong session. Nếu có đổi Public API / Trách nhiệm / Dependencies / ràng buộc → sync README NGAY (Bước 5). Nếu chỉ fix nội bộ không đổi hợp đồng → bỏ qua, kết thúc lại lần nữa (nhắc 1 lần).`,
       )
     }
   }
@@ -403,6 +411,7 @@ function buildVerifyIssues(root: string): string[] {
   }
 
   // Check 11: plan khai báo "## Quyết định kiến trúc" (đổi/đảo) nhưng không sinh/sửa ADR
+  let archDeclared = false
   for (const plan of planSet) {
     if (!fs.existsSync(plan)) continue
     const lines = fs.readFileSync(plan, "utf8").split(/\r?\n/)
@@ -416,9 +425,32 @@ function buildVerifyIssues(root: string): string[] {
       if (inSection && /^##\s+/.test(line)) break
       if (inSection && /supersede|đổi kiến trúc|revert|đảo ngược/i.test(line)) declared = true
     }
-    if (declared && changedDecisions.length === 0) {
+    if (declared) {
+      archDeclared = true
+      if (changedDecisions.length === 0) {
+        issues.push(
+          `❌ Plan '${path.basename(plan)}' có '## Quyết định kiến trúc' khai báo đổi/đảo kiến trúc nhưng KHÔNG có docs/decisions/*.md được tạo/cập nhật. Tạo/supersede ADR (skill decision-recorder) trước khi kết thúc.`,
+        )
+      }
+    }
+  }
+
+  // Check 12: thay đổi "đáng kể" KHÔNG qua plan kiến trúc + KHÔNG có ADR → nudge mềm 1 lần.
+  // Backstop cho ca sửa code chạm kiến trúc nhưng không tạo plan. Ngưỡng CHẶT (≥4 module HOẶC
+  // ≥12 file code) để hiếm khi kêu, tránh false-positive.
+  if (
+    firstNudge &&
+    fs.existsSync(path.join(root, "docs", "decisions", "INDEX.md")) &&
+    changedDecisions.length === 0 &&
+    !archDeclared
+  ) {
+    const numModules = inferModules(paths).length
+    const numCodeFiles = paths.filter(
+      (p) => !/^(docs\/|plans\/|README|\.gitignore|\.env\.example|AGENTS\.md|\.cursor\/|CHANGELOG|VERSION$|package(-lock)?\.json|pnpm-lock|yarn\.lock)/.test(p),
+    ).length
+    if (numModules >= 4 || numCodeFiles >= 12) {
       issues.push(
-        `❌ Plan '${path.basename(plan)}' có '## Quyết định kiến trúc' khai báo đổi/đảo kiến trúc nhưng KHÔNG có docs/decisions/*.md được tạo/cập nhật. Tạo/supersede ADR (skill decision-recorder) trước khi kết thúc.`,
+        `⚠️→ Session đụng ${numModules} module / ${numCodeFiles} file code nhưng KHÔNG tạo/sửa ADR nào và KHÔNG có plan khai báo kiến trúc. NẾU đây là quyết định kiến trúc (đổi data flow, đổi cách module giao tiếp, thay/đảo 1 cơ chế, fix bug bằng cách đổi thiết kế) → tạo ADR (skill decision-recorder) hoặc nâng lên plan TRƯỚC khi đóng. Nếu chỉ là thay đổi thường → bỏ qua, kết thúc lại lần nữa (nhắc 1 lần).`,
       )
     }
   }
@@ -518,7 +550,7 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
       {
         loaded_at: new Date().toISOString(),
         root,
-        version: "2.0.2",
+        version: "2.2.0",
         load_count: globalState[globalKey],
       },
       null,
@@ -686,8 +718,12 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
     }) => {
       if (event.type !== "session.idle") return
       try {
-        const issues = buildVerifyIssues(root)
         const sessionID = asString(event.properties?.sessionID)
+        const loop = readVerifyLoop(root)
+        const count = loop.sessionID === sessionID ? loop.count : 0
+
+        // count === 0 ⇒ lần nhắc đầu ⇒ bật các nudge mềm "1 lần" (parity LOOP_COUNT == 0).
+        const issues = buildVerifyIssues(root, count === 0)
 
         if (issues.length === 0) {
           clearSessionChanges(root)
@@ -695,9 +731,6 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
           return
         }
 
-        const loop = readVerifyLoop(root)
-        const count = loop.sessionID === sessionID ? loop.count : 0
-
         if (count >= VERIFY_LOOP_LIMIT) {
           console.warn(
             `[OpenMoneta Dev Kit] verify-completion: đã nhắc ${count} lần, graceful exit. ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmoneta-dev-kit",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "OpenMoneta Dev Kit — Biến Cursor IDE / OpenCode thành team developer hoàn chỉnh với quy trình 6 bước, adaptive planning, hooks enforcement, và token-aware doc routing",
   "keywords": [
     "cursor",

package/scripts/docs-audit.sh

@@ -9,8 +9,11 @@
 #   bash docs-audit.sh --report       # như trên
 #   bash docs-audit.sh --worklist     # TSV: <slug>\t<docsPath>\t<sourcePath>\t<missing|stale|ok>
 #   bash docs-audit.sh --validate     # liệt kê GHOST (doc trỏ source/module không tồn tại)
+#   bash docs-audit.sh --decisions    # audit ADR (docs/decisions/): legacy / index-sync / supersede / module-link
+#   bash docs-audit.sh --decisions-worklist  # TSV: <issue>\t<path> cho skill xử lý
 #
 # Stale detection: so commit mới nhất của source vs README (git); fallback mtime filesystem.
+# ADR audit chỉ MECHANICAL (không bịa nội dung): phát hiện nợ ADR, không tự sửa.
 
 set -uo pipefail
 
@@ -18,8 +21,10 @@ MODE="report"
 case "${1:-}" in
   --worklist) MODE="worklist" ;;
   --validate) MODE="validate" ;;
+  --decisions) MODE="decisions" ;;
+  --decisions-worklist) MODE="decisions-worklist" ;;
   --report|"") MODE="report" ;;
-  *) echo "[!] Mode không hợp lệ: $1 (dùng --report|--worklist|--validate)" >&2; exit 2 ;;
+  *) echo "[!] Mode không hợp lệ: $1 (dùng --report|--worklist|--validate|--decisions|--decisions-worklist)" >&2; exit 2 ;;
 esac
 
 GIT_OK=0
@@ -100,6 +105,125 @@ slug_to_source() {
   fi
 }
 
+# ---------- MODE: decisions / decisions-worklist (ADR audit) ----------
+if [[ "$MODE" == "decisions" || "$MODE" == "decisions-worklist" ]]; then
+  WL=0; [[ "$MODE" == "decisions-worklist" ]] && WL=1
+  DDIR="docs/decisions"
+
+  emit() { # <issue> <path-or-msg>
+    if [[ "$WL" -eq 1 ]]; then printf '%s\t%s\n' "$1" "$2"; else printf '  %-16s %s\n' "$1" "$2"; fi
+  }
+
+  # ADR đúng format = NNNN-slug.md (NNNN sequential). Loại trừ file date YYYY-MM-DD-slug.md (legacy).
+  is_adr_file() {
+    local b="$1"
+    [[ "$b" =~ ^[0-9][0-9][0-9][0-9]-.*\.md$ ]] || return 1
+    [[ "$b" =~ ^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]- ]] && return 1
+    return 0
+  }
+  adr_files() { # in ra path các ADR đúng format
+    local f b
+    for f in "$DDIR"/[0-9][0-9][0-9][0-9]-*.md; do
+      [[ -f "$f" ]] || continue
+      b=$(basename "$f")
+      is_adr_file "$b" && echo "$f"
+    done
+  }
+
+  if [[ ! -d "$DDIR" ]]; then
+    [[ "$WL" -eq 0 ]] && echo "  Project chưa có layer Decision Memory (docs/decisions/). Bỏ qua ADR audit."
+    exit 0
+  fi
+
+  n_legacy=0; n_orphan=0; n_ghost=0; n_supersede=0; n_modlink=0
+
+  # (1) Legacy: file trong docs/decisions/ không theo NNNN-slug.md (ngoài INDEX.md)
+  for f in "$DDIR"/*; do
+    [[ -f "$f" ]] || continue
+    b=$(basename "$f")
+    [[ "$b" == "INDEX.md" ]] && continue
+    if ! is_adr_file "$b"; then
+      emit "LEGACY" "$f"
+      n_legacy=$((n_legacy+1))
+    fi
+  done
+
+  # (2a) ADR file đúng format nhưng KHÔNG có trong bảng INDEX
+  while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    b=$(basename "$f")
+    if [[ -f "$DDIR/INDEX.md" ]] && grep -qF "$b" "$DDIR/INDEX.md" 2>/dev/null; then :; else
+      emit "NOT-IN-INDEX" "$f"
+      n_orphan=$((n_orphan+1))
+    fi
+  done < <(adr_files)
+
+  # (2b) INDEX trỏ ADR file đã mất
+  if [[ -f "$DDIR/INDEX.md" ]]; then
+    while IFS= read -r ref; do
+      [[ -z "$ref" ]] && continue
+      [[ -f "$DDIR/$ref" ]] || { emit "INDEX-GHOST" "$DDIR/INDEX.md → $ref"; n_ghost=$((n_ghost+1)); }
+    done < <(grep -oE '[0-9]{4}-[A-Za-z0-9._-]+\.md' "$DDIR/INDEX.md" 2>/dev/null | sort -u)
+  fi
+
+  # (3) Supersede integrity
+  while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    sup=$(grep -oE '^\*\*Supersedes\*\*:[[:space:]]*ADR-[0-9]{4}' "$f" 2>/dev/null | grep -oE '[0-9]{4}' | head -1)
+    [[ -z "$sup" ]] && continue
+    target=$(ls "$DDIR/${sup}-"*.md 2>/dev/null | head -1)
+    if [[ -z "$target" ]]; then
+      emit "SUPERSEDE-MISS" "$(basename "$f") → ADR-$sup không tồn tại"
+      n_supersede=$((n_supersede+1))
+    elif ! grep -qE '^\*\*Status\*\*:.*Superseded by' "$target" 2>/dev/null; then
+      emit "SUPERSEDE-OPEN" "$(basename "$target") chưa đổi Status sang 'Superseded by' (bị $(basename "$f") thay)"
+      n_supersede=$((n_supersede+1))
+    fi
+  done < <(adr_files)
+
+  # (4) Module link (advisory): ADR khai Module(s) có docs/modules/<slug>/README.md nhưng chưa link ADR
+  while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    b=$(basename "$f")
+    mods=$(grep -oE '^\*\*Module\(s\)\*\*:.*' "$f" 2>/dev/null | sed -E 's/^\*\*Module\(s\)\*\*:[[:space:]]*//')
+    [[ -z "$mods" ]] && continue
+    IFS=',' read -ra arr <<< "$mods"
+    for m in "${arr[@]}"; do
+      slug=$(echo "$m" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')
+      [[ -z "$slug" || "$slug" == "—" ]] && continue
+      readme="docs/modules/$slug/README.md"
+      [[ -f "$readme" ]] || continue
+      if ! grep -qF "$b" "$readme" 2>/dev/null; then
+        emit "MODLINK" "$readme chưa link $b (Module(s) của ADR)"
+        n_modlink=$((n_modlink+1))
+      fi
+    done
+  done < <(adr_files)
+
+  if [[ "$WL" -eq 1 ]]; then exit 0; fi
+
+  total=$((n_legacy+n_orphan+n_ghost+n_supersede))
+  echo ""
+  echo "  ADR audit — $(pwd)/$DDIR"
+  echo "  ──────────────────────────────────────────────────────────────"
+  if [[ "$total" -eq 0 && "$n_modlink" -eq 0 ]]; then
+    echo "  ✓ Sạch: ADR đăng ký đầy đủ trong INDEX, không legacy/ghost, supersede toàn vẹn."
+  else
+    echo "  Tổng: $total vấn đề cần xử lý"
+    echo "    · $n_legacy legacy (file không theo NNNN-slug.md, chưa đăng ký)"
+    echo "    · $n_orphan ADR chưa có trong INDEX"
+    echo "    · $n_ghost INDEX trỏ ADR đã mất"
+    echo "    · $n_supersede supersede không toàn vẹn"
+    [[ "$n_modlink" -gt 0 ]] && echo "    · $n_modlink module README chưa link ADR (advisory)"
+    echo ""
+    echo "  → Để MIGRATE legacy (reformat file có sẵn nội dung) + đăng ký INDEX:"
+    echo "     mở Cursor/OpenCode và yêu cầu chạy skill 'docs-maintenance' (phạm vi ADR)."
+    echo "  → ADR còn THIẾU cho quyết định CHƯA ghi: dùng skill 'decision-recorder' (cần ngữ cảnh thật, KHÔNG bịa từ code)."
+  fi
+  echo ""
+  exit 0
+fi
+
 MODULES=$(collect_modules | sort -u)
 
 # ---------- MODE: validate (ghost) ----------

package/skills/decision-recorder/SKILL.md

@@ -19,8 +19,12 @@ KHÔNG ĐẢO NGƯỢC một kiến trúc đã Accepted (LOCKED) khi CHƯA:
 
 ## Khi nào TẠO ADR
 
+> **Trigger này áp dụng kể cả KHÔNG có plan.** Nếu đang fix bug / sửa code mà chạm 1 trong các dấu hiệu dưới → DỪNG, tạo ADR NGAY (hoặc nâng lên plan), KHÔNG âm thầm sửa rồi đóng session. Hook Check 12 sẽ nudge nếu thay đổi đáng kể mà thiếu ADR.
+
 - Chọn giữa ≥2 phương án kiến trúc có trade-off thật (state management, data flow, sync vs async, pattern...).
-- Đổi cách triển khai một tính năng đang chạy (vd: polling → websocket).
+- Đổi cách triển khai một tính năng đang chạy (vd: polling → websocket; DB heartbeat → in-memory).
+- **Đổi data flow / đổi cách các module giao tiếp với nhau** (đổi contract giữa module, đổi nguồn sự thật).
+- **Thay/đảo một cơ chế cốt lõi** dù khởi đầu chỉ là "fix bug" — fix bug bằng cách ĐỔI THIẾT KẾ = quyết định kiến trúc.
 - `systematic-debugging` xác nhận một approach hỏng do bản chất kiến trúc (không phải bug vặt).
 - Đảo ngược / thay thế một quyết định cũ.
 

package/skills/docs-maintenance/SKILL.md

@@ -1,22 +1,33 @@
 ---
 name: docs-maintenance
-description: "ON-DEMAND ONLY: dùng khi user yêu cầu tạo docs còn thiếu / backfill module README / refresh docs lỗi thời / audit docs / bảo trì docs dự án cũ. KHÔNG tự trigger trong quy trình bình thường."
+description: "ON-DEMAND ONLY: dùng khi user yêu cầu tạo docs còn thiếu / backfill module README / refresh docs lỗi thời / audit docs / bảo trì docs dự án cũ / audit & migrate ADR legacy. KHÔNG tự trigger trong quy trình bình thường."
 ---
 
 # Docs Maintenance
 
-Quét cả repo một lượt để **backfill module README còn thiếu** và **refresh README đã lỗi thời** so với code, rồi **đồng bộ `docs/INDEX.md`** (Modules hiện có + Token Routing).
+Quét cả repo một lượt để **backfill module README còn thiếu** và **refresh README đã lỗi thời** so với code, rồi **đồng bộ `docs/INDEX.md`** (Modules hiện có + Token Routing). Ngoài ra **audit + migrate ADR legacy** trong `docs/decisions/` (phần mechanical, KHÔNG bịa rationale).
 
 Dùng khi onboard/bảo trì **dự án cũ** đã tích lũy nợ doc (code đụng nhiều nhưng README không được cập nhật), hoặc khi user yêu cầu rõ. Đây là phiên bản "chạy hàng loạt cho cả repo" của skill `module-architect` (vốn chạy từng module/session).
 
+## Hai phạm vi tách bạch
+
+| Phạm vi | Nguồn chân lý | Skill này làm | KHÔNG làm |
+|---|---|---|---|
+| **Module README** (WHAT) | Source code (verify bằng grep) | Backfill MISSING + refresh STALE + sync INDEX | — |
+| **ADR** (WHY/WHY-NOT) | Phán đoán kiến trúc của con người | Audit mechanical (legacy/index-sync/supersede/module-link) + **migrate file legacy ĐÃ CÓ nội dung** | **KHÔNG bịa rationale ADR từ code**; tạo ADR cho quyết định CHƯA ghi → `decision-recorder` |
+
 ## Iron Law
 
 ```
-CHỈ VIẾT NHỮNG GÌ VERIFY ĐƯỢC TRONG CODE. KHÔNG BỊA API / PATH / DEPENDENCY.
+CHỈ VIẾT NHỮNG GÌ VERIFY ĐƯỢC TRONG NGUỒN. KHÔNG BỊA.
+- Module README: mỗi dòng truy về symbol/import có thật trong source.
+- ADR: mỗi rationale truy về nội dung file legacy ĐÃ CÓ. KHÔNG suy diễn WHY/root-cause từ code hiện tại.
 ```
 
 Stale docs còn tệ hơn không có docs — session sau AI đọc sai, làm sai. Mỗi dòng trong README phải truy về một symbol/import có thật trong source. Không chắc → mô tả mức ý định cao, KHÔNG bịa signature.
 
+**ADR bịa còn nguy hiểm hơn**: ADR giả tạo ra "trí nhớ quyết định" sai → session sau tin theo và đảo kiến trúc sai hướng — phá đúng cái Decision Memory muốn chống. KHÔNG bao giờ chế WHY/rejected-alternatives/root-cause từ code. File legacy không đủ rationale → BÁO user, KHÔNG tự điền.
+
 ## Ranh giới (Lean — KHÔNG làm gì)
 
 - **KHÔNG** sinh bộ doc tổng quan kiểu khác (`system-architecture.md`, `project-roadmap.md`, `codebase-summary.md`...). Mô hình OM là **per-module README 3 sections + `docs/INDEX.md`**, đủ để navigate token-aware.
@@ -81,6 +92,48 @@ Cho mỗi module status `stale`:
 
 In tóm tắt: `created / updated / skipped` + cảnh báo (module không verify được, ghost). Gợi ý chạy lại `openmoneta docs --validate` để xác nhận sạch.
 
+## ADR audit + migrate legacy (docs/decisions/)
+
+Chạy khi user yêu cầu "audit ADR", "bảo trì decisions", "migrate quyết định cũ", hoặc khi onboard dự án có `docs/decisions/` lộn xộn. Bỏ qua nếu project chưa có `docs/decisions/`.
+
+### 1. Audit (deterministic)
+
+```bash
+bash ~/.cursor/scripts/docs-audit.sh --decisions            # report 4 loại vấn đề
+bash ~/.cursor/scripts/docs-audit.sh --decisions-worklist   # TSV: <issue>\t<path>
+```
+
+(OpenCode: `~/.config/opencode/scripts/docs-audit.sh`.) 4 loại issue:
+
+- **LEGACY**: file trong `docs/decisions/` không theo `NNNN-slug.md` (vd `YYYY-MM-DD-*.md`) → ứng viên migrate.
+- **NOT-IN-INDEX**: ADR đúng format nhưng thiếu dòng trong `INDEX.md`.
+- **INDEX-GHOST**: `INDEX.md` trỏ ADR file đã mất.
+- **SUPERSEDE-MISS / SUPERSEDE-OPEN**: `Supersedes: ADR-XXXX` trỏ ADR không tồn tại, hoặc ADR cũ chưa đổi Status sang `Superseded by`.
+- **MODLINK** (advisory): module README chưa link ADR khai trong `Module(s)`.
+
+### 2. Migrate LEGACY → ADR chuẩn (CHỈ reformat, KHÔNG bịa)
+
+Cho mỗi file LEGACY:
+
+1. **Đọc file legacy** — nó ĐÃ CÓ rationale thật. KHÔNG suy diễn từ code.
+2. Xác định `NNNN` mới = max ADR hiện có trong INDEX + 1 (4 chữ số).
+3. Tạo `docs/decisions/NNNN-<slug>.md` theo `~/.cursor/templates/adr.md.tpl`, **map nội dung có sẵn** vào 5 section (Context/Decision/Rejected alternatives/Consequences/Failed approaches log). Phần nào file cũ KHÔNG có → để trống + ghi `(legacy: không ghi rõ)`, KHÔNG chế ra.
+4. Field: `Status` (giữ theo file cũ nếu có, mặc định `Accepted (LOCKED)`), `Date` (lấy từ tên file/nội dung cũ), `Module(s)` (nếu suy được từ nội dung), `Plan nguồn: —`.
+5. Xóa file legacy cũ (đã chuyển nội dung) — hoặc nếu format cũ là chuẩn nội bộ của dự án, hỏi user trước khi xóa.
+6. Thêm dòng vào bảng `INDEX.md`.
+
+### 3. Sửa NOT-IN-INDEX / INDEX-GHOST / SUPERSEDE / MODLINK
+
+- **NOT-IN-INDEX**: đọc ADR → thêm dòng vào bảng INDEX (id, tiêu đề, status, module, date).
+- **INDEX-GHOST**: dòng INDEX trỏ file mất → hỏi user (xóa dòng hay khôi phục file). KHÔNG tự xóa.
+- **SUPERSEDE-OPEN**: đổi ADR cũ sang `Status: Superseded by ADR-NNNN` (mechanical, an toàn).
+- **SUPERSEDE-MISS**: target không tồn tại → BÁO user (có thể typo hoặc file mất), KHÔNG đoán.
+- **MODLINK**: thêm link ADR vào section "## Quyết định kiến trúc (ADR)" của module README.
+
+### 4. Báo nếu thiếu rationale
+
+File legacy chỉ có tiêu đề/1 dòng, không đủ WHY → migrate phần có được, **liệt kê rõ cho user** ADR nào cần bổ sung rationale qua `decision-recorder`. KHÔNG tự bịa cho đủ section.
+
 ## Bảng Rationalization (cái cớ → sự thật)
 
 | Cái cớ | Sự thật |
@@ -90,6 +143,8 @@ In tóm tắt: `created / updated / skipped` + cảnh báo (module không verify
 | "Viết lại cả README cho gọn" | Phá nội dung đang đúng + tốn token. Chỉ sửa phần lệch. |
 | "Thêm doc tổng quan cho đầy đủ" | Trái Lean. OM chỉ module README + INDEX. |
 | "Module mới khỏi thêm Token Routing" | Không có keyword → AI không tìm thấy module → đọc loạn. Bắt buộc thêm. |
+| "File legacy thiếu WHY, mình suy từ code cho đủ ADR" | Bịa rationale = trí nhớ quyết định giả = tệ hơn không có. Để trống + báo user. |
+| "Tạo luôn ADR cho quyết định chưa ai ghi" | Sai skill. Đó là việc của `decision-recorder` (cần ngữ cảnh thật). |
 
 ## Red Flags — DỪNG
 
@@ -98,9 +153,14 @@ In tóm tắt: `created / updated / skipped` + cảnh báo (module không verify
 - Đang định sinh `system-architecture.md` / `codebase-summary.md`.
 - Đang định xóa GHOST mà chưa hỏi user.
 - Tạo module mới trong INDEX nhưng quên Token Routing keyword.
+- Đang điền section Rejected-alternatives/root-cause của ADR mà chưa thấy nó trong file legacy.
+- Đang tạo ADR mới cho quyết định chưa từng được ghi (→ việc của `decision-recorder`).
+- Đang xóa file legacy/INDEX-GHOST mà chưa hỏi user.
 
 ## Examples
 
 - User: "Dự án này nhiều module thiếu docs, tạo giúp" → `init`: chạy worklist → tạo mọi MISSING + refresh STALE → sync INDEX → report.
 - User: "Doc còn khớp code không?" → `audit`: chỉ report.
 - User: "Cập nhật doc 3 module vừa refactor" → `sync` (giới hạn các slug đó).
+- User: "Audit ADR / decisions lộn xộn" → `docs-audit.sh --decisions` → report 4 loại issue.
+- User: "Migrate mấy file quyết định cũ vào ADR chuẩn" → đọc từng file legacy → reformat sang `NNNN-slug.md` + đăng ký INDEX (không bịa phần thiếu, báo user).

package/skills/module-architect/SKILL.md

@@ -70,7 +70,7 @@ Khi nào IGNORE rule (không tách dù dài):
 - Config files (webpack, playwright, biome, ...).
 - File có cohesion cực cao (vd 1 state machine 500 dòng cho 1 workflow rõ ràng).
 
-#### 3. Mỗi module có `README.md` riêng (3 sections, lean)
+#### 3. Mỗi module có `README.md` riêng (3 section bắt buộc + 2 tùy, lean)
 
 ```markdown
 # <Tên module>
@@ -82,13 +82,27 @@ Khi nào IGNORE rule (không tách dù dài):
 - `funcA(arg1: X, arg2: Y): Z` — mô tả 1 dòng
 - `class Foo` — mô tả 1 dòng
 
+## Lưu ý / Ràng buộc (invariants)   <!-- TÙY: chỉ khi có ràng buộc không hiển nhiên -->
+
+- <quy tắc phải giữ / cạm bẫy, vd: "phải init DB trước khi gọi", "chạy cả Cursor + OpenCode nên giữ path trừu tượng">
+
+## Quyết định kiến trúc (ADR)   <!-- TÙY: chỉ khi module có ADR -->
+
+- [ADR-0003](../../decisions/0003-...md) — <1 dòng> (Accepted)
+
 ## Dependencies
 
 - Internal: `modules/auth`, `modules/db`
 - External: `axios`, `zod`
 ```
 
-> Chỉ 3 sections. KHÔNG thêm Owner/Stability/Cách dùng/Anti-patterns vào README mặc định — chúng dễ stale và AI hiếm khi dùng. Nếu module có quirk đặc biệt (vd phải init theo thứ tự), thêm section `## Lưu ý` ngắn ≤5 bullet.
+**3 section BẮT BUỘC**: Trách nhiệm + Public API + Dependencies.
+
+**2 section TÙY** (thêm khi có, vì là trí nhớ chống regression — đừng bỏ nếu thật sự có):
+- **`## Lưu ý / Ràng buộc (invariants)`** (≤5 bullet): ràng buộc/cạm bẫy ngầm mà session sau dễ phá nếu không biết (thứ tự init, side-effect, môi trường chạy, giả định dữ liệu). Đây là tri thức ngầm hay mất giữa các session → gây regression; ghi ngắn gọn ngay khi phát hiện.
+- **`## Quyết định kiến trúc (ADR)`**: list ADR-NNNN chi phối module (link). Tạo qua skill `decision-recorder`.
+
+> KHÔNG thêm Owner/Stability/Cách dùng/tutorial — dễ stale, AI hiếm dùng. Giữ README lean: chỉ ghi cái session sau THỰC SỰ cần để không hiểu lệch / không phá đồ.
 
 ### Cấu trúc folder mẫu
 
@@ -204,7 +218,7 @@ Quy tắc maintenance:
 
 ### Bước 5 workflow — Sync module README (BẮT BUỘC)
 
-> Hook `verify-completion` Check 6 sẽ **CHẶN** session kết thúc nếu module bị sửa nhưng không có `docs/modules/<slug>/README.md`.
+> Hook `verify-completion` Check 6: **CHẶN** nếu module bị sửa nhưng thiếu `docs/modules/<slug>/README.md`; và **nudge mềm 1 lần** (README freshness) nếu module source đổi nhưng README KHÔNG được cập nhật trong session. Chạm module nào → sync README module đó NGAY trong session, KHÔNG để "sửa sau".
 
 **Cách xác định module từ file path** (cho file đã sửa trong session):
 
@@ -227,6 +241,7 @@ Quy tắc maintenance:
 4. Check section **Dependencies**:
    - Có `import` mới từ module khác? → thêm.
    - Có `import` bị xóa? → xóa.
+4b. Check section **Lưu ý / Ràng buộc**: thay đổi có tạo ra ràng buộc/cạm bẫy ngầm mới (thứ tự init, side-effect, giả định dữ liệu)? → thêm bullet ngắn. Đây là thứ chống regression cho session sau.
 5. Nếu module **mới được backfill** ở Bước 2.2 → đảm bảo `docs/INDEX.md` đã có trong bảng "Modules hiện có" + Token Routing.
 6. **Nếu session ra/đổi quyết định kiến trúc cho module này** → tạo/cập nhật ADR (skill `decision-recorder`) trong `docs/decisions/` + thêm/sync section "## Quyết định kiến trúc (ADR)" trong README module (list các ADR-NNNN liên quan) + cập nhật `docs/decisions/INDEX.md`. KHÔNG bắt buộc cho task không đổi kiến trúc.
 

package/skills/requirement-analysis/SKILL.md

@@ -47,6 +47,7 @@ description: "Dùng khi bắt đầu phân tích một yêu cầu trước khi t
   - Kiểm tra phần **Rejected alternatives** + **Failed approaches log**: phương án bạn định chuyển sang có phải cái đã từng bị loại/hỏng không? Nếu CÓ và root cause còn đúng → KHÔNG lặp lại (đây chính là cái bẫy `A1 → B1 → A1`).
 - Khi ADR tóm tắt chưa đủ ngữ cảnh → theo link **`Plan nguồn`** xuống `plans/archive/<file>.md` (tầng chi tiết, chỉ nạp khi cần).
 - Muốn đổi kiến trúc đã khóa → áp dụng skill `decision-recorder` (quy trình supersede tường minh).
+- **Bug-fix hoá ra chạm kiến trúc**: nếu trong lúc làm 1 task tưởng nhỏ (fix bug) mà phát hiện phải đổi data flow / đổi cách module giao tiếp / thay-đảo cơ chế cốt lõi → KHÔNG âm thầm sửa rồi đóng. Nâng lên B3 (tạo plan) HOẶC tạo ADR ngay (skill `decision-recorder`), kể cả khi task khởi đầu không có plan.
 
 #### Anti-pattern token waste
 

package/src/cli.js

@@ -56,6 +56,7 @@ Biến Cursor IDE / OpenCode thành team developer hoàn chỉnh.
 
   openmoneta docs                 Audit module README (thiếu/lỗi thời) + sync INDEX
   openmoneta docs --validate      Phát hiện doc trỏ module/source không tồn tại (ghost)
+  openmoneta docs --decisions     Audit ADR (docs/decisions/): legacy/index-sync/supersede/module-link
 
   openmoneta uninstall            Gỡ cài đặt
 

package/src/commands/docs.js

@@ -6,6 +6,8 @@ const { getPkgRoot, isWindows } = require("../lib/paths")
 async function run(args) {
   const validate = args.includes("--validate")
   const worklist = args.includes("--worklist")
+  const decisions = args.includes("--decisions")
+  const decisionsWorklist = args.includes("--decisions-worklist")
 
   const pkgRoot = getPkgRoot()
   const script = path.join(pkgRoot, "scripts", "docs-audit.sh")
@@ -17,7 +19,9 @@ async function run(args) {
   }
 
   let mode = "--report"
-  if (validate) mode = "--validate"
+  if (decisionsWorklist) mode = "--decisions-worklist"
+  else if (decisions) mode = "--decisions"
+  else if (validate) mode = "--validate"
   else if (worklist) mode = "--worklist"
 
   try {

package/templates/docs-INDEX.md.tpl

@@ -41,10 +41,12 @@
 
 ## Cách thêm module mới
 
-1. Tạo `docs/modules/<module-name>/README.md` với 3 sections:
+1. Tạo `docs/modules/<module-name>/README.md` với 3 section BẮT BUỘC + 2 section TÙY:
    - **Trách nhiệm**: 1 câu không có "và".
    - **Public API**: function/class export.
    - **Dependencies**: internal + external.
+   - *(tùy)* **Lưu ý / Ràng buộc (invariants)**: ≤5 bullet ràng buộc/cạm bẫy ngầm (thứ tự init, side-effect, giả định dữ liệu) — thêm khi có, để session sau không phá đồ.
+   - *(tùy)* **Quyết định kiến trúc (ADR)**: link ADR-NNNN chi phối module (xem `docs/decisions/` + skill `decision-recorder`).
 2. Update bảng "Modules hiện có" ở trên.
 3. **BẮT BUỘC**: thêm 3-5 keyword vào bảng "Token Routing" (cho cả VN + EN).
 4. Tạo source folder tương ứng (`src/modules/<name>/` hoặc `apps/<name>/` hoặc `packages/<name>/`).