openmoneta-dev-kit 1.12.0 → 2.0.0

package/VERSION

@@ -1 +1 @@
-1.12.0
+2.0.0

package/hooks/enforce-docs-first.sh

@@ -101,6 +101,8 @@ INDEX_FILE="$WORKSPACE/docs/INDEX.md"
 [[ -f "$INDEX_FILE" ]] || allow
 
 MARKER="$WORKSPACE/.cursor/.docs-index-read"
+DECISIONS_INDEX="$WORKSPACE/docs/decisions/INDEX.md"
+DECISIONS_MARKER="$WORKSPACE/.cursor/.decisions-read"
 
 case "$PATHS" in
   *"docs/INDEX.md"*)
@@ -110,6 +112,15 @@ case "$PATHS" in
     ;;
 esac
 
+# Đọc bất kỳ file nào trong docs/decisions/ → set marker decisions-read (vẫn allow vì là docs).
+case "$PATHS" in
+  *"docs/decisions/"*)
+    mkdir -p "$WORKSPACE/.cursor"
+    touch "$DECISIONS_MARKER"
+    allow
+    ;;
+esac
+
 case "$PATHS" in
   *"docs/"*|*"plans/"*|*".cursor/"*|*".github/"*|*".vscode/"*) allow ;;
   *"AGENTS.md"*|*"README"*|*"CHANGELOG"*|*"LICENSE"*) allow ;;
@@ -164,6 +175,29 @@ LƯU Ý:
 
 (Hook này chỉ chạy 1 lần / session. Sau khi đọc docs/INDEX.md, marker .cursor/.docs-index-read được set và hook sẽ allow mọi tool call source-code khác trong session.)"
   fi
+
+  # === Decisions-read gate (Decision Memory / chống flip-flop kiến trúc) ===
+  # Chỉ enforce khi project CÓ docs/decisions/INDEX.md (project chưa có quyết định nào thì bỏ qua → giữ Lean).
+  if [[ -f "$DECISIONS_INDEX" && ! -f "$DECISIONS_MARKER" ]]; then
+    deny "Bạn đang $TOOL_NAME source code TRƯỚC khi đọc docs/decisions/ (trí nhớ quyết định kiến trúc). Vi phạm Bước 1 (skill requirement-analysis 1.3b).
+
+DEBUG:
+- Tool: $TOOL_NAME
+- docs/decisions/INDEX.md: $DECISIONS_INDEX
+- Marker expected: $DECISIONS_MARKER
+- Tool input paths/patterns: $PATHS
+
+VÌ SAO ENFORCE:
+- Project này có quyết định kiến trúc đã ghi (ADR). Sửa code mà không đọc lịch sử quyết định = nguy cơ flip-flop kiến trúc (A1 → B1 → A1) làm loạn code.
+- ADR ghi: kiến trúc đang chọn, vì sao, phương án nào đã bị loại + root cause, hạn chế đã biết.
+
+HÀNH ĐỘNG NGAY:
+→ Read $DECISIONS_INDEX (set marker), tìm ADR liên quan tới module bạn sắp đụng, đọc ADR đó nếu định đổi kiến trúc, sau đó retry $TOOL_NAME.
+
+LƯU Ý:
+- Muốn ĐỔI/ĐẢO kiến trúc đã Accepted → phải supersede tường minh (skill decision-recorder), KHÔNG revert lặng lẽ.
+- Marker chỉ cần set 1 lần/session (auto-clean ở sessionStart)."
+  fi
 fi
 
 allow

package/hooks/inject-process-context.sh

@@ -10,12 +10,31 @@ set -euo pipefail
 
 INPUT_JSON=$(cat 2>/dev/null || echo '{}')
 
-# Reset docs-index marker mỗi session (force re-read INDEX.md)
+# Auto-register project vào Cursor registry (seed cho `update --all-projects`).
+# Im lặng. Chỉ append khi: workspace có docs/INDEX.md, Cursor install home đã cài,
+# và path chưa có trong registry (dedup, chuẩn hoá pwd -P).
+register_project_cursor() {
+  local ws="$1"
+  [[ -n "$ws" && -f "$ws/docs/INDEX.md" ]] || return 0
+  [[ -f "$HOME/.cursor/.openmoneta-version" ]] || return 0
+  local reg="$HOME/.cursor/.openmoneta-projects"
+  local abs
+  abs="$(cd "$ws" 2>/dev/null && pwd -P)" || return 0
+  [[ -n "$abs" ]] || return 0
+  if [[ -f "$reg" ]] && grep -qFx "$abs" "$reg" 2>/dev/null; then
+    return 0
+  fi
+  echo "$abs" >> "$reg" 2>/dev/null || true
+}
+
+# Reset docs-index + decisions marker mỗi session (force re-read INDEX.md + decisions/)
 if command -v jq >/dev/null 2>&1; then
   WORKSPACE_FROM_INPUT=$(echo "$INPUT_JSON" | jq -r '.workspace_roots[0] // ""' 2>/dev/null || echo "")
   if [[ -n "$WORKSPACE_FROM_INPUT" && -d "$WORKSPACE_FROM_INPUT/.cursor" ]]; then
     rm -f "$WORKSPACE_FROM_INPUT/.cursor/.docs-index-read" 2>/dev/null || true
+    rm -f "$WORKSPACE_FROM_INPUT/.cursor/.decisions-read" 2>/dev/null || true
   fi
+  register_project_cursor "$WORKSPACE_FROM_INPUT" 2>/dev/null || true
 fi
 
 # === Summary 6 bước (~45 dòng, ~650 tokens) ===
@@ -32,7 +51,7 @@ SUMMARY='# OpenMoneta Dev Kit v1.7.0 — Quy trình 6 bước (Adaptive Planning
 6. Safe Push: khi user yêu cầu push, PHẢI sync remote ngay trước push; KHÔNG force-push shared branch.
 
 ## 6 bước
-- **B1 Phân tích** (skill `requirement-analysis`): Read INDEX → match Token Routing → đọc README module candidate → đọc source → đặt câu hỏi critical để làm rõ yêu cầu, phân tích mọi trường hợp, phản biện và đề xuất phương án tối ưu nếu có (hoặc khai báo skip lý do).
+- **B1 Phân tích** (skill `requirement-analysis`): Read INDEX → match Token Routing → đọc README module candidate → đọc source → đặt câu hỏi critical để làm rõ yêu cầu, phân tích mọi trường hợp, phản biện và đề xuất phương án tối ưu nếu có (hoặc khai báo skip lý do). Nếu có `docs/decisions/INDEX.md`: PHẢI đọc ADR liên quan trước khi đổi kiến trúc (chống flip-flop A1→B1→A1); muốn đảo kiến trúc đã chốt → supersede tường minh (skill `decision-recorder`).
 - **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.

package/hooks/verify-completion.sh

@@ -7,6 +7,8 @@
 #   7. Cross-module sprawl >3 module → WARN
 #   8. Token-aware reading marker tồn tại → WARN nếu thiếu
 #   9. Nếu có plan: section "## Hiểu yêu cầu" có nội dung không trống → BLOCK (audit clarify)
+#   10. ADR supersede integrity: ADR mới "Supersedes: X" thì ADR X phải "Superseded by" → BLOCK
+#   11. Plan khai báo "## Quyết định kiến trúc" (đổi/đảo) nhưng không sinh/sửa ADR → BLOCK
 #
 # Đã bỏ (so với v1.4.x):
 #   - Check 2 (test result file) — test giờ on-demand
@@ -134,6 +136,39 @@ if [[ -f "$WORKSPACE/docs/INDEX.md" && ! -f "$WORKSPACE/.cursor/.docs-index-read
   WARNINGS+=("⚠️ Session có code change nhưng marker .cursor/.docs-index-read không tồn tại — AI có thể đã skip Bước 1 (Read docs/INDEX.md). Verify hook 'enforce-docs-first' đang chạy: cat ~/.cursor/hooks.json | jq '.hooks.preToolUse'. Nếu hook không chạy → restart Cursor sau khi cài v1.5.0.")
 fi
 
+# === Check 10/11: Decision Memory (ADR) integrity — chống flip-flop kiến trúc ===
+CHANGED_DECISIONS=$(jq -r '.changes[] | .path' "$CHANGES_FILE" 2>/dev/null | grep -E '^docs/decisions/.*\.md$' | grep -v 'docs/decisions/INDEX.md' || true)
+
+# Check 10: ADR mới/sửa khai báo "Supersedes: ADR-NNNN" thì ADR đích phải đã đổi sang "Superseded by"
+if [[ -n "$CHANGED_DECISIONS" ]]; then
+  while IFS= read -r rel_adr; do
+    [[ -z "$rel_adr" ]] && continue
+    ADR_FILE="$WORKSPACE/$rel_adr"
+    [[ -f "$ADR_FILE" ]] || continue
+    SUPERSEDES=$(grep -ioE 'supersedes\*{0,2}:?[[:space:]]*ADR-[0-9]+' "$ADR_FILE" 2>/dev/null | grep -oE 'ADR-[0-9]+' | head -1 || true)
+    if [[ -n "$SUPERSEDES" ]]; then
+      NUM=$(echo "$SUPERSEDES" | grep -oE '[0-9]+')
+      TARGET=$(ls "$WORKSPACE/docs/decisions/${NUM}-"*.md 2>/dev/null | head -1 || true)
+      if [[ -z "$TARGET" ]]; then
+        ISSUES+=("❌ ADR '$(basename "$ADR_FILE")' khai báo 'Supersedes: $SUPERSEDES' nhưng không tìm thấy docs/decisions/${NUM}-*.md.")
+      elif ! grep -qiE 'superseded by' "$TARGET" 2>/dev/null; then
+        ISSUES+=("❌ ADR cũ '$(basename "$TARGET")' bị supersede bởi '$(basename "$ADR_FILE")' nhưng chưa đổi Status sang 'Superseded by ADR-...'. Cập nhật để tránh 2 ADR Accepted xung đột (gây flip-flop). Xem skill decision-recorder.")
+      fi
+    fi
+  done <<< "$CHANGED_DECISIONS"
+fi
+
+# Check 11: plan trong session khai báo đổi/đảo kiến trúc nhưng KHÔNG sinh/sửa ADR
+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.")
+    fi
+  fi
+done
+
 # === Output ===
 WARN_STR=""
 if [[ ${#WARNINGS[@]} -gt 0 ]]; then

package/opencode/AGENTS.md.tpl

@@ -13,13 +13,14 @@
 
 ## Quy trình 6 bước
 
-- **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).
+- **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`.
+- **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]`.
 - **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**.
   - [ ] 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`).
   - [ ] 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.
@@ -31,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 + plan gate), `tool.execute.after` (track changes), và `event:session.idle` (verify B2/B5: module README + close plan, 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, close plan, supersede ADR, 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

@@ -375,6 +375,54 @@ function buildVerifyIssues(root: string): string[] {
     }
   }
 
+  // Check 10/11: Decision Memory (ADR) integrity — chống flip-flop kiến trúc
+  const changedDecisions = paths.filter(
+    (p) => /^docs\/decisions\/.*\.md$/.test(p) && p !== "docs/decisions/INDEX.md",
+  )
+
+  // Check 10: ADR mới "Supersedes: ADR-NNNN" thì ADR đích phải đã "Superseded by"
+  for (const rel of changedDecisions) {
+    const abs = path.join(root, rel)
+    if (!fs.existsSync(abs)) continue
+    const match = fs.readFileSync(abs, "utf8").match(/supersedes\*{0,2}:?\s*ADR-(\d+)/i)
+    if (!match) continue
+    const num = match[1]
+    const decisionsDir = path.join(root, "docs", "decisions")
+    const target = fs.existsSync(decisionsDir)
+      ? fs.readdirSync(decisionsDir).find((f) => f.startsWith(`${num}-`) && f.endsWith(".md"))
+      : undefined
+    if (!target) {
+      issues.push(
+        `❌ ADR '${path.basename(abs)}' khai báo 'Supersedes: ADR-${num}' nhưng không tìm thấy docs/decisions/${num}-*.md.`,
+      )
+    } else if (!/superseded by/i.test(fs.readFileSync(path.join(decisionsDir, target), "utf8"))) {
+      issues.push(
+        `❌ ADR cũ '${target}' bị supersede bởi '${path.basename(abs)}' nhưng chưa đổi Status sang 'Superseded by ADR-...'. Cập nhật để tránh 2 ADR Accepted xung đột (flip-flop). Xem skill decision-recorder.`,
+      )
+    }
+  }
+
+  // Check 11: plan khai báo "## Quyết định kiến trúc" (đổi/đảo) nhưng không sinh/sửa ADR
+  for (const plan of planSet) {
+    if (!fs.existsSync(plan)) continue
+    const lines = fs.readFileSync(plan, "utf8").split(/\r?\n/)
+    let inSection = false
+    let declared = false
+    for (const line of lines) {
+      if (/^##\s+Quyết định kiến trúc/.test(line)) {
+        inSection = true
+        continue
+      }
+      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) {
+      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.`,
+      )
+    }
+  }
+
   return issues
 }
 
@@ -400,6 +448,33 @@ function clearVerifyLoop(root: string) {
   fs.rmSync(path.join(root, ".cursor", ".openmoneta-verify-loop.json"), { force: true })
 }
 
+// Auto-register project vào OpenCode registry (seed cho `update --all-projects`).
+// Im lặng + try/catch — seed không được phép làm fail guard. Chỉ append khi:
+// project có docs/INDEX.md, OpenCode install home đã cài, path chưa có trong registry.
+function registerProjectOpenCode(root: string) {
+  try {
+    if (!fs.existsSync(path.join(root, "docs", "INDEX.md"))) return
+    const home = process.env.HOME || process.env.USERPROFILE || ""
+    const xdg = process.env.XDG_CONFIG_HOME || path.join(home, ".config")
+    const ocHome = path.join(xdg, "opencode")
+    if (!fs.existsSync(path.join(ocHome, ".openmoneta-version"))) return
+    const reg = path.join(ocHome, ".openmoneta-projects")
+    const abs = fs.realpathSync(root)
+    let lines: string[] = []
+    if (fs.existsSync(reg)) {
+      lines = fs
+        .readFileSync(reg, "utf8")
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+    }
+    if (lines.includes(abs)) return
+    fs.appendFileSync(reg, `${abs}\n`)
+  } catch {
+    // im lặng
+  }
+}
+
 type SessionPromptClient = {
   session?: {
     prompt?: (input: {
@@ -423,8 +498,10 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
   const client = ctx.client
   const root = projectRoot(ctx)
   const marker = path.join(root, ".cursor", ".docs-index-read")
+  const decisionsMarker = path.join(root, ".cursor", ".decisions-read")
   const guardLoadedMarker = path.join(root, ".cursor", ".openmoneta-guard-loaded.json")
   const docsIndex = path.join(root, "docs", "INDEX.md")
+  const decisionsIndex = path.join(root, "docs", "decisions", "INDEX.md")
   const pendingEdits = new Map<string, string[]>()
 
   fs.mkdirSync(path.dirname(marker), { recursive: true })
@@ -434,7 +511,7 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
       {
         loaded_at: new Date().toISOString(),
         root,
-        version: "1.11.0",
+        version: "2.0.0",
         load_count: globalState[globalKey],
       },
       null,
@@ -442,11 +519,17 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
     )}\n`,
   )
 
+  // Seed project vào OpenCode registry để `update --all-projects` thấy project này.
+  registerProjectOpenCode(root)
+
   // OpenCode does not have Cursor's sessionStart hook, so reset the docs-first
-  // marker when the plugin is loaded for a new OpenCode process/session.
+  // + decisions-read markers when the plugin is loaded for a new OpenCode process/session.
   if (fs.existsSync(marker)) {
     fs.rmSync(marker, { force: true })
   }
+  if (fs.existsSync(decisionsMarker)) {
+    fs.rmSync(decisionsMarker, { force: true })
+  }
 
   return {
     "tool.execute.before": async (
@@ -463,6 +546,11 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
           fs.writeFileSync(marker, new Date().toISOString())
           return
         }
+        if (target.includes("docs/decisions/")) {
+          fs.mkdirSync(path.dirname(decisionsMarker), { recursive: true })
+          fs.writeFileSync(decisionsMarker, new Date().toISOString())
+          return
+        }
         if (shouldCheckRead(tool, target) && !fs.existsSync(marker)) {
           fail(
             [
@@ -475,6 +563,20 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
             ].join("\n"),
           )
         }
+        if (shouldCheckRead(tool, target) && fs.existsSync(decisionsIndex) && !fs.existsSync(decisionsMarker)) {
+          fail(
+            [
+              "Bạn đang đọc/search source code trước khi đọc `docs/decisions/` (trí nhớ quyết định kiến trúc).",
+              "",
+              "Project này có ADR. Sửa code mà không đọc lịch sử quyết định = nguy cơ flip-flop kiến trúc (A1 → B1 → A1).",
+              "",
+              "Quy trình đúng:",
+              "1. Read `docs/decisions/INDEX.md`.",
+              "2. Đọc ADR liên quan tới module nếu định đổi kiến trúc.",
+              "3. Muốn đảo kiến trúc đã chốt → supersede tường minh (skill decision-recorder).",
+            ].join("\n"),
+          )
+        }
       }
 
       if (isBashTool(tool) && fs.existsSync(docsIndex)) {
@@ -484,6 +586,11 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
           fs.writeFileSync(marker, new Date().toISOString())
           return
         }
+        if (command.includes("docs/decisions")) {
+          fs.mkdirSync(path.dirname(decisionsMarker), { recursive: true })
+          fs.writeFileSync(decisionsMarker, new Date().toISOString())
+          return
+        }
         if (isSourceSearchCommand(command) && !fs.existsSync(marker)) {
           fail(
             [
@@ -498,6 +605,21 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
             ].join("\n"),
           )
         }
+        if (
+          isSourceSearchCommand(command) &&
+          fs.existsSync(decisionsIndex) &&
+          !fs.existsSync(decisionsMarker)
+        ) {
+          fail(
+            [
+              "Bạn đang chạy shell command search source code trước khi đọc `docs/decisions/` (trí nhớ quyết định kiến trúc).",
+              "",
+              `Command bị chặn: ${command}`,
+              "",
+              "Read `docs/decisions/INDEX.md` trước (chống flip-flop kiến trúc), rồi mới search source.",
+            ].join("\n"),
+          )
+        }
       }
 
       if (isEditTool(tool)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmoneta-dev-kit",
-  "version": "1.12.0",
+  "version": "2.0.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/init-project.sh

@@ -337,6 +337,40 @@ sync_plans_index() {
   UPDATED+=("sync: $dst (giữ ACTIVE PLANS / PLANS EXTRA / ARCHIVED PLANS / PLANS NOTES)")
 }
 
+sync_decisions_index() {
+  local src="$TEMPLATES/decisions-INDEX.md.tpl"
+  local dst="docs/decisions/INDEX.md"
+
+  # Template mới (v2.0.0+). Nếu install home cũ chưa có → bỏ qua êm.
+  [[ -f "$src" ]] || return 0
+
+  if [[ ! -f "$dst" ]]; then
+    render_template "$src" "$dst"
+    CREATED+=("file: $dst")
+    return
+  fi
+
+  local rendered content
+  rendered=$(mktemp)
+  render_template "$src" "$rendered"
+
+  content=$(mktemp)
+  if extract_block "$dst" "PROJECT DECISIONS" "$content" || extract_section_table "$dst" "## Quyết định hiện có" "$content"; then
+    replace_block "$rendered" "PROJECT DECISIONS" "$content"
+  fi
+  rm -f "$content"
+
+  if cmp -s "$rendered" "$dst"; then
+    SKIPPED+=("file: $dst (đã sync, không đổi)")
+    rm -f "$rendered"
+    return
+  fi
+
+  backup_before_sync "$dst"
+  mv "$rendered" "$dst"
+  UPDATED+=("sync: $dst (giữ PROJECT DECISIONS)")
+}
+
 sync_opencode_project_guard() {
   # Guard is now global-only (~/.config/opencode/plugins/).
   # Just clean up any old project-level plugins from pre-v1.9 migration.
@@ -347,6 +381,7 @@ sync_opencode_project_guard() {
 echo "==> Tạo thư mục tối thiểu..."
 ensure_dir "docs"
 ensure_dir "docs/modules"
+ensure_dir "docs/decisions"
 ensure_dir "plans"
 ensure_dir "plans/archive"
 ensure_dir ".cursor"
@@ -356,6 +391,7 @@ echo "==> Sync managed templates..."
 
 sync_agents_md
 sync_docs_index
+sync_decisions_index
 sync_plans_index
 sync_opencode_project_guard
 
@@ -365,7 +401,9 @@ GITIGNORE=".gitignore"
 PATTERNS=(
   ".cursor/.session-changes.json"
   ".cursor/.docs-index-read"
+  ".cursor/.decisions-read"
   ".cursor/.openmoneta-guard-loaded.json"
+  ".cursor/.openmoneta-verify-loop.json"
   ".cursor/.changelog-baseline"
   ".cursor/.last-test-result"
   ".cursor/.ui-session.json"

package/skills/decision-recorder/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: decision-recorder
+description: "Dùng khi ra/đổi/đảo một quyết định KIẾN TRÚC (chọn giữa ≥2 phương án, đổi cách triển khai một tính năng, hoặc muốn revert kiến trúc đã có). Ghi ADR vào docs/decisions/ để chống flip-flop kiến trúc xuyên session. KHÔNG dùng cho task code thường."
+---
+
+# Decision Recorder (ADR)
+
+Lớp **Decision Memory** giải quyết vòng lặp phá code: `A1 lỗi → session đổi sang B1 → B1 lỗi nhỏ → session mới (quên hết) đưa về A1 → lỗi cũ tái diễn`. ADR lưu **WHY + WHY-NOT + root cause** để mọi session sau hiểu vì sao kiến trúc hiện tại được chọn.
+
+## Iron Law
+
+```
+KHÔNG ĐẢO NGƯỢC một kiến trúc đã Accepted (LOCKED) khi CHƯA:
+  (1) đọc ADR đang khóa của nó, VÀ
+  (2) supersede tường minh (ADR mới + chứng minh root cause cũ KHÔNG còn đúng).
+```
+
+**Vi phạm chữ = vi phạm tinh thần.** Đổi kiến trúc "cho nhanh" rồi định ghi ADR sau = sai. Phải đọc + supersede TRƯỚC.
+
+## Khi nào TẠO 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).
+- `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ũ.
+
+## Khi nào KHÔNG tạo ADR (tránh token bloat)
+
+- Bug fix, thêm field, đổi text/CSS, rename, refactor nội bộ không đổi kiến trúc.
+- Task nhỏ thường ngày. ADR chỉ dành cho **quyết định kiến trúc đáng nhớ**.
+
+## Cách tạo ADR mới
+
+1. Đọc `docs/decisions/INDEX.md` để biết số ADR lớn nhất hiện có → `NNNN` mới = max + 1 (4 chữ số).
+2. Copy template `~/.cursor/templates/adr.md.tpl` (hoặc `~/.config/opencode/templates/adr.md.tpl`) → `docs/decisions/NNNN-<slug>.md`.
+3. Điền 5 section: Context, Decision, **Rejected alternatives (kèm root cause)**, Consequences (known limitations), Failed approaches log.
+4. Điền field: `Status: Accepted (LOCKED)`, `Date`, `Module(s)`, `Plan nguồn` (link plan archive nếu có — đây là **tầng chi tiết**), `Supersedes` (nếu thay ADR cũ).
+5. Cập nhật bảng trong `docs/decisions/INDEX.md`.
+6. Link ADR vào `docs/modules/<slug>/README.md` section "## Quyết định kiến trúc (ADR)".
+
+## Quy trình SUPERSEDE (đảo/đổi quyết định cũ) — BẮT BUỘC
+
+1. Đọc ADR cũ (`Accepted (LOCKED)`) + phần **Rejected alternatives** + **Failed approaches log** của nó.
+2. Tự hỏi: root cause khiến phương án cũ bị loại có còn đúng không? Nếu CÒN đúng → **KHÔNG revert** (đây chính là cái bẫy flip-flop).
+3. Nếu thật sự cần đổi: tạo ADR mới với `Supersedes: ADR-XXXX` + chứng minh trong section Context vì sao root cause cũ hết hiệu lực.
+4. Đổi ADR cũ sang `Status: Superseded by ADR-NNNN` (giữ nguyên nội dung — không xóa, là lịch sử).
+5. Plan tương ứng phải có section "## Quyết định kiến trúc" ghi rõ supersede (xem skill `plan-writer`).
+
+## Token-lean (guideline, KHÔNG enforce cứng)
+
+- Soft target **~40 dòng/ADR**, viết gạch đầu dòng. Quy tắc vàng: **"viết đủ để session sau không lặp lại sai lầm, không hơn"**.
+- **Miễn giới hạn** cho phần root cause chi tiết + "Failed approaches log" (giữ sắc thái quan trọng).
+- Cấu trúc 2 tầng: ADR = tóm tắt (luôn nạp); `Plan nguồn` (`plans/archive/<file>.md`) = chi tiết (nạp khi cần). KHÔNG tạo file `*-detail.md` riêng.
+
+## Red Flags — DỪNG
+
+- Định đổi kiến trúc mà chưa đọc ADR đang khóa của module.
+- Định revert về phương án từng bị loại mà không kiểm tra root cause cũ.
+- Tạo ADR mới `Accepted` nhưng KHÔNG đổi ADR cũ sang `Superseded by` (để 2 ADR Accepted xung đột — hook `verify-completion` Check 10 sẽ chặn).
+- ADR phình dài vì văn xuôi thừa (không phải vì root cause).
+- Tạo ADR cho task code thường (lạm dụng → token bloat).

package/skills/docs-maintenance/SKILL.md

@@ -42,14 +42,14 @@ Stale docs còn tệ hơn không có docs — session sau AI đọc sai, làm sa
 
 ## Workflow
 
-### 1. Lấy danh sách (deterministic)
+### 1. Lấy danh sách + soi ghost (deterministic)
 
 ```bash
-bash ~/.cursor/scripts/docs-audit.sh --worklist
-# Output TSV: <slug>\t<docsPath>\t<sourcePath>\t<missing|stale|ok>
+bash ~/.cursor/scripts/docs-audit.sh --worklist    # MISSING/STALE/ok (TSV: slug\tdocs\tsource\tstatus)
+bash ~/.cursor/scripts/docs-audit.sh --validate     # liệt kê GHOST (doc/INDEX trỏ source/module đã mất)
 ```
 
-(OpenCode: `~/.config/opencode/scripts/docs-audit.sh`.) Mode `audit` chỉ in report rồi dừng, không qua các bước dưới.
+(OpenCode: `~/.config/opencode/scripts/docs-audit.sh`.) **BẮT BUỘC chạy cả `--validate`** ở mọi mode để không bỏ sót ghost. Mode `audit` in cả 2 kết quả rồi dừng, không qua các bước tạo/sửa dưới.
 
 ### 2. (Repo lớn) đọc song song
 
@@ -75,7 +75,7 @@ Cho mỗi module status `stale`:
 ### 5. Sync `docs/INDEX.md`
 
 - Module mới → thêm dòng vào bảng "Modules hiện có" + **3-5 keyword (VN+EN)** vào bảng "Token Routing" (bắt buộc, để hook docs-first + token-aware reading hoạt động).
-- GHOST → báo user, đề xuất xóa dòng/thư mục (KHÔNG tự xóa nếu chưa chắc).
+- **GHOST** (từ `--validate` ở Bước 1) → LIỆT KÊ rõ từng ghost cho user. **KHÔNG tự xóa** — map slug→source là heuristic, có thể là module vừa đổi tên/di chuyển. Hỏi user bằng `AskQuestion` (xóa doc/dòng INDEX, hay map lại sang source mới); chỉ thao tác sau khi user xác nhận từng cái.
 
 ### 6. Report cuối
 

package/skills/module-architect/SKILL.md

@@ -228,9 +228,18 @@ Quy tắc maintenance:
    - Có `import` mới từ module khác? → thêm.
    - Có `import` bị xóa? → xóa.
 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.
 
 > KHÔNG cần update `changelog.md` cấp module — v1.5.0 bỏ enforcement này. Lịch sử dùng `git log` thay.
 
+**Section ADR trong README module** (chỉ thêm khi module có quyết định kiến trúc):
+
+```markdown
+## Quyết định kiến trúc (ADR)
+
+- [ADR-0003](../../decisions/0003-state-via-store.md) — dùng store tập trung thay vì props drilling (Accepted).
+```
+
 ### Anti-patterns
 
 - ❌ Copy nguyên block code vào README (sẽ stale).
@@ -243,6 +252,7 @@ Quy tắc maintenance:
 
 - [ ] Module README đã sync với public API thực tế (nếu API đổi).
 - [ ] Module mới được tạo → đã thêm vào bảng "Modules hiện có" + Token Routing trong `docs/INDEX.md`.
+- [ ] Nếu session đổi kiến trúc → ADR đã tạo/cập nhật trong `docs/decisions/` + link vào README module + bảng `docs/decisions/INDEX.md` (xem skill `decision-recorder`).
 - [ ] Plan đánh dấu `Status: Done`.
 - [ ] Plan file đã `git mv` sang `plans/archive/<file>.md` (auto-archive).
 - [ ] `plans/INDEX.md` đã chuyển plan từ Active sang Archived.

package/skills/plan-writer/SKILL.md

@@ -91,6 +91,7 @@ Không được tự tạo plan rồi tự approve.
 - Định sửa file không nằm trong `## Files ảnh hưởng`.
 - Định bỏ qua plan cho task chạm auth/payment/db/migration/deploy.
 - Section `## Hiểu yêu cầu` trống mà vẫn định code.
+- Định đổi/đảo kiến trúc đã có ADR mà plan thiếu section `## Quyết định kiến trúc` (supersede).
 
 **Tất cả đều nghĩa là: DỪNG, quay lại review gate.**
 
@@ -118,6 +119,17 @@ HOẶC
 
 <1-2 câu: làm gì, vì sao>
 
+## Quyết định kiến trúc
+
+> CHỈ BẮT BUỘC khi plan ĐỔI/ĐẢO kiến trúc một module (đổi cách triển khai, revert, chọn lại pattern). Bỏ section này cho plan thường. Hook `verify-completion` Check 11 chặn nếu section này khai báo đổi kiến trúc nhưng KHÔNG sinh/sửa ADR trong `docs/decisions/`.
+
+- **ADR liên quan**: ADR-NNNN (đọc trước khi đổi).
+- **Supersede**: `Supersede ADR-XXXX` (nếu đảo ngược quyết định cũ).
+- **Lý do root cause cũ không còn đúng**: <chứng minh vì sao phương án cũ từng bị loại nay đã ổn — nếu không chứng minh được thì KHÔNG đổi>.
+- **ADR sẽ tạo/cập nhật ở Bước 5**: `docs/decisions/NNNN-<slug>.md`.
+
+Xem skill `decision-recorder` cho quy trình supersede đầy đủ.
+
 ## Modules ảnh hưởng
 
 > Hook `verify-completion` Check 6 sẽ chặn nếu module ở đây không có README. Quy ước slug xem skill `module-architect` Bước 2.1.

package/skills/requirement-analysis/SKILL.md

@@ -38,6 +38,16 @@ description: "Dùng khi bắt đầu phân tích một yêu cầu trước khi t
 - **KHÔNG scan** `docs/architecture/`, `docs/api/`, `docs/security/` trừ khi yêu cầu user trực tiếp đụng đến.
 - Sau khi đọc README → mới được Read/Grep/Glob source code của module đó (hook đã unlock).
 
+### Bước 1.3b — Đọc trí nhớ quyết định (ADR) — CHỐNG FLIP-FLOP
+
+> **HOOK ENFORCEMENT**: nếu `docs/decisions/INDEX.md` tồn tại, hook `enforce-docs-first` chặn Read source cho tới khi đã đọc `docs/decisions/`. Marker: `<workspace>/.cursor/.decisions-read` (auto-clean mỗi sessionStart).
+
+- Đọc `docs/decisions/INDEX.md` → tìm ADR liên quan tới module candidate (xem cột Module / link trong README module).
+- **Nếu yêu cầu có dấu hiệu đổi/đảo kiến trúc** (đổi cách triển khai, "chuyển sang...", "thử cách khác", revert) → BẮT BUỘC đọc ADR `Accepted (LOCKED)` của module đó TRƯỚC.
+  - 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).
+
 #### Anti-pattern token waste
 
 - ❌ Đọc tất cả `docs/modules/*/README.md` "để hiểu toàn bộ dự án" → 19 module × 30 dòng = ~9k tokens phí phạm.
@@ -155,6 +165,7 @@ Subagent trả về tóm tắt + danh sách câu hỏi, parent agent dùng để
 ## Output bắt buộc trước khi sang Bước 2
 
 - [ ] Đã đọc `docs/INDEX.md` (hook unlock cho phép Read source).
+- [ ] Đã đọc `docs/decisions/INDEX.md` + ADR liên quan (nếu tồn tại); nếu định đổi kiến trúc → đã đọc ADR đang khóa + check root cause cũ.
 - [ ] Tóm tắt yêu cầu (2-3 câu).
 - [ ] Liệt kê module ảnh hưởng (slug + trạng thái có sẵn / NEW / backfill).
 - [ ] Giả thuyết / edge cases / rủi ro.

package/skills/systematic-debugging/SKILL.md

@@ -80,6 +80,15 @@ Sau **3+ fix thất bại**, đây KHÔNG phải giả thuyết sai mà là **ki
 
 → **DỪNG, hỏi user** trước khi thử fix thứ 4: pattern này có sai từ gốc không? Có nên đổi kiến trúc thay vì vá tiếp không?
 
+### Persist root cause vào ADR (CHỐNG FLIP-FLOP xuyên session)
+
+Khi đã **xác nhận** một approach/kiến trúc hỏng do bản chất (không phải bug vặt):
+
+1. Tìm ADR liên quan trong `docs/decisions/` (theo module). Nếu chưa có ADR cho concern đó → tạo qua skill `decision-recorder`.
+2. **Append vào "Failed approaches log"** của ADR: `YYYY-MM-DD — <approach> — root cause: <nguyên nhân gốc>`. (Phần này miễn giới hạn dòng.)
+3. Mục đích: session sau đọc ADR sẽ KHÔNG thử lại đúng approach đã hỏng (đây chính là cái bẫy `A1 → B1 → A1`).
+4. Nếu quyết định **đổi kiến trúc** → theo quy trình supersede của `decision-recorder` (tạo ADR mới + đổi ADR cũ sang Superseded), KHÔNG revert lặng lẽ.
+
 ## Bảng Rationalization (cái cớ → sự thật)
 
 | Cái cớ | Sự thật |
@@ -120,3 +129,4 @@ Nếu bắt gặp mình đang nghĩ:
 
 - `test-strategy` — viết test reproduce bug ở Phase 4 (khi cần TDD-first).
 - `plan-writer` — nếu fix biến thành refactor lớn/đổi kiến trúc → dừng, tạo plan.
+- `decision-recorder` — persist root cause của approach hỏng vào ADR + quy trình supersede khi đổi kiến trúc (chống flip-flop).

package/src/commands/update.js

@@ -57,6 +57,104 @@ function pruneRegistry() {
   return pruned
 }
 
+const SCAN_PRUNE_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "Library",
+  ".Trash",
+  ".cache",
+  ".npm",
+  ".cargo",
+  ".gradle",
+  ".venv",
+  "dist",
+  "build",
+])
+
+function findProjects(root, maxDepth) {
+  const out = []
+  function walk(dir, depth) {
+    if (depth > maxDepth) return
+    if (isOpenmonetaProject(dir)) {
+      try {
+        fs.accessSync(path.join(dir, "AGENTS.md"))
+        out.push(dir)
+      } catch {
+        // thiếu AGENTS.md → không tính là OM project khi scan
+      }
+    }
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      if (SCAN_PRUNE_DIRS.has(e.name) || e.name.startsWith(".")) continue
+      walk(path.join(dir, e.name), depth + 1)
+    }
+  }
+  walk(root, 0)
+  return out
+}
+
+function scanSeed(root, pkgRoot) {
+  let absRoot
+  try {
+    absRoot = fs.realpathSync(root)
+  } catch {
+    console.log(`  [!] Scan root không tồn tại: ${root}`)
+    return
+  }
+  const targets = ["cursor", "opencode"].filter((t) => isInstalled(t))
+  if (targets.length === 0) {
+    console.log(`  [!] Chưa có install home nào để seed registry.`)
+    return
+  }
+  let kitRoot
+  try {
+    kitRoot = fs.realpathSync(pkgRoot)
+  } catch {
+    kitRoot = pkgRoot
+  }
+  const uniq = [
+    ...new Set(
+      findProjects(absRoot, 5)
+        .map((p) => {
+          try {
+            return fs.realpathSync(p)
+          } catch {
+            return p
+          }
+        })
+        .filter((p) => p !== kitRoot)
+    ),
+  ]
+  let seeded = 0
+  for (const t of targets) {
+    const reg = getProjectRegistry(t)
+    let existing = new Set()
+    try {
+      existing = new Set(
+        fs
+          .readFileSync(reg, "utf8")
+          .split("\n")
+          .map((l) => l.trim())
+          .filter(Boolean)
+      )
+    } catch {
+      // registry chưa tồn tại → tạo mới khi append
+    }
+    const toAdd = uniq.filter((p) => !existing.has(p))
+    if (toAdd.length) {
+      fs.appendFileSync(reg, toAdd.map((p) => `${p}\n`).join(""))
+      seeded += toAdd.length
+    }
+  }
+  console.log(`  Scan: thấy ${uniq.length} OM project, seed ${seeded} entry mới.`)
+}
+
 function syncProject(initScript, dir) {
   if (isWindows()) {
     execSync(`bash "${initScript}" "${dir}"`, { stdio: "inherit", shell: true })
@@ -69,7 +167,14 @@ async function run(args) {
   const checkOnly = args.includes("--check")
   const autoYes = args.includes("--yes") || args.includes("-y")
   const skipProjects = args.includes("--skip-projects")
-  const allProjects = args.includes("--all-projects")
+  const scanIdx = args.indexOf("--scan")
+  const scan = scanIdx !== -1
+  let scanRoot = process.env.HOME || process.env.USERPROFILE || "."
+  if (scan) {
+    const next = args[scanIdx + 1]
+    if (next && !next.startsWith("-")) scanRoot = next
+  }
+  const allProjects = args.includes("--all-projects") || scan
   const force = args.includes("--force")
 
   const local = getLocalVersion()
@@ -140,6 +245,11 @@ async function run(args) {
     const initScript = path.join(pkgRoot, "scripts", "init-project.sh")
     const cwd = process.cwd()
 
+    if (scan) {
+      console.log(`\n  ▶ --scan: dò OM project để seed registry...`)
+      scanSeed(scanRoot, pkgRoot)
+    }
+
     if (allProjects) {
       const pruned = pruneRegistry()
       if (pruned > 0) console.log(`\n  ℹ Registry: prune ${pruned} entry chết.`)
@@ -196,4 +306,7 @@ async function run(args) {
   console.log(`\n  🎉 Hoàn tất. Restart Cursor/OpenCode để áp dụng.`)
 }
 
-module.exports = { run, _internal: { isOpenmonetaProject, readRegistry, pruneRegistry } }
+module.exports = {
+  run,
+  _internal: { isOpenmonetaProject, readRegistry, pruneRegistry, findProjects, scanSeed },
+}

package/templates/AGENTS.md.tpl

@@ -21,9 +21,10 @@
 1. Read `docs/INDEX.md` (Modules + Token Routing) → match keyword user → 1-3 module candidate.
 2. Read `plans/INDEX.md` (check overlap với plan active).
 3. Read `docs/modules/<candidate>/README.md` (CHỈ module liên quan, không scan toàn bộ).
-4. Read source code module candidate (giờ hook unlock).
-5. Tóm tắt yêu cầu + giả thuyết + edge case + rủi ro.
-6. **Đặt câu hỏi critical để làm rõ yêu cầu** (`AskQuestion`) HOẶC khai báo `Lý do skip clarify` cho task trivial (typo, bump version, đổi 1 hằng số). Mục đích: làm rõ yêu cầu người dùng, phân tích tất cả trường hợp có thể xảy ra, phản biện và đề xuất phương án tối ưu hơn nếu có. Số lượng câu hỏi tùy thuộc vào độ phức tạp của task.
+4. **Nếu có `docs/decisions/INDEX.md`**: Read nó + ADR liên quan của module candidate (hook `enforce-docs-first` chặn Read source nếu chưa đọc `docs/decisions/`). Định đổi kiến trúc → đọc ADR đang khóa + check root cause cũ TRƯỚC (chống flip-flop A1→B1→A1).
+5. Read source code module candidate (giờ hook unlock).
+6. Tóm tắt yêu cầu + giả thuyết + edge case + rủi ro.
+7. **Đặt câu hỏi critical để làm rõ yêu cầu** (`AskQuestion`) HOẶC khai báo `Lý do skip clarify` cho task trivial (typo, bump version, đổi 1 hằng số). Mục đích: làm rõ yêu cầu người dùng, phân tích tất cả trường hợp có thể xảy ra, phản biện và đề xuất phương án tối ưu hơn nếu có. Số lượng câu hỏi tùy thuộc vào độ phức tạp của task.
 
 ### Bước 2 — Thiết kế module
 
@@ -43,6 +44,7 @@
 - Khi đã có plan `In Progress`, hook `check-plan-exists` enforce file scope theo `## Files ảnh hưởng` / `## Files thay đổi`.
 - Khi plan còn `Draft`, hook chặn code edit để tránh Agent tự approve plan.
 - Plan đụng >2 module → BẮT BUỘC thêm subsection "Lý do cross-module".
+- **Plan đổi/đảo kiến trúc** → BẮT BUỘC thêm section "## Quyết định kiến trúc" (`Supersede ADR-NNNN` + lý do root cause cũ hết đúng). Hook `verify-completion` Check 11 chặn nếu khai báo đổi kiến trúc mà không sinh ADR.
 - Update `plans/INDEX.md` (thêm vào Active).
 
 ### Bước 4 — Triển khai
@@ -58,6 +60,7 @@
 
 - Sync `docs/modules/<slug>/README.md` (Public API + Dependencies) nếu API đổi.
 - Module mới → đảm bảo đã có trong bảng "Modules hiện có" + "Token Routing" của `docs/INDEX.md`.
+- **Nếu session ra/đổi quyết định kiến trúc** → tạo/supersede ADR trong `docs/decisions/` + link vào README module (section "## Quyết định kiến trúc (ADR)") + cập nhật `docs/decisions/INDEX.md` (skill `decision-recorder`).
 - Plan → `Status: Done` + tick mọi checkbox.
 - **AUTO-ARCHIVE**: `git mv plans/<file>.md plans/archive/<file>.md` + update `plans/INDEX.md`.
 
@@ -83,7 +86,7 @@
 
 ## Skills có sẵn
 
-**Core (luôn relevant)**: `requirement-analysis`, `module-architect`, `plan-writer`.
+**Core (luôn relevant)**: `requirement-analysis`, `module-architect`, `plan-writer`, `decision-recorder`.
 
 **Core conditional**: `safe-push` (Bước 6 — chỉ khi user yêu cầu push).
 
@@ -95,9 +98,9 @@
 
 | Hook | Khi nào | Hậu quả |
 |---|---|---|
-| `enforce-docs-first` | preToolUse Read/Glob/Grep | BLOCK source code đọc nếu chưa Read `docs/INDEX.md` |
+| `enforce-docs-first` | preToolUse Read/Glob/Grep | BLOCK source code đọc nếu chưa Read `docs/INDEX.md`; nếu có `docs/decisions/INDEX.md` thì còn BLOCK đến khi đã đọc `docs/decisions/` (chống flip-flop kiến trúc) |
 | `check-plan-exists` | preToolUse Write/StrReplace/EditNotebook/Delete | ALLOW task thường không plan; BLOCK file nhạy cảm không plan, plan Draft, hoặc file ngoài scope plan |
-| `verify-completion` | stop (Cursor) / `session.idle` (OpenCode) | Cursor BLOCK kết thúc nếu Check 5/6/9 fail; OpenCode re-prompt nhắc hoàn tất (plan Done + checkbox, module README, "Hiểu yêu cầu"), loop guard ≤4 lần |
+| `verify-completion` | stop (Cursor) / `session.idle` (OpenCode) | Cursor BLOCK kết thúc nếu Check 5/6/9/10/11 fail (gồm ADR supersede integrity + plan đổi kiến trúc thiếu ADR); OpenCode re-prompt nhắc hoàn tất, loop guard ≤4 lần |
 
 ## Override cho dự án này
 

package/templates/adr.md.tpl

@@ -0,0 +1,37 @@
+# ADR-{{NNNN}}: {{Tiêu đề quyết định}}
+
+<!--
+HƯỚNG DẪN (xóa khi viết xong):
+- Token-lean: viết gạch đầu dòng, SOFT TARGET ~40 dòng. Đây là GUIDELINE, không phải luật cứng.
+- Quy tắc vàng: "viết đủ để session sau KHÔNG lặp lại sai lầm, không hơn".
+- ĐƯỢC PHÉP vượt 40 dòng cho phần root cause chi tiết và "Failed approaches log" (miễn trừ).
+- Cấu trúc 2 tầng: file này = TÓM TẮT (luôn nạp). Chi tiết đầy đủ nằm ở "Plan nguồn" (nạp khi cần).
+- Đánh số {{NNNN}} = max ADR hiện có + 1 (4 chữ số: 0001, 0002, ...).
+-->
+
+**Status**: Accepted (LOCKED)        <!-- Accepted (LOCKED) | Proposed | Superseded by ADR-MMMM -->
+**Date**: {{YYYY-MM-DD}}
+**Module(s)**: {{slug-module-liên-quan}}
+**Plan nguồn**: {{plans/archive/<file>.md hoặc "—" nếu quyết định inline}}
+**Supersedes**: {{ADR-XXXX hoặc "—"}}
+
+## Context — vấn đề cần quyết
+
+- (vì sao phải ra quyết định này)
+
+## Decision — chọn gì (kiến trúc hiện hành)
+
+- (kiến trúc/hướng được chọn — đây là cái đang chạy)
+
+## Rejected alternatives — phương án bị loại + VÌ SAO
+
+- **{{Phương án A}}**: bị loại vì {{lý do / root cause nếu đã thử & hỏng}}.
+- (giữ sắc thái root cause để session sau không thử lại cái đã hỏng)
+
+## Consequences — hệ quả, known limitations, accepted trade-offs
+
+- (những hạn chế đã biết — gồm các "bug nhỏ" chấp nhận được, đừng để session sau tưởng là lỗi cần đổi kiến trúc)
+
+## Failed approaches log — append-only (miễn giới hạn dòng)
+
+<!-- systematic-debugging append vào đây khi 1 approach được XÁC NHẬN hỏng. Format: YYYY-MM-DD — approach — root cause. -->

package/templates/decisions-INDEX.md.tpl

@@ -0,0 +1,28 @@
+<!-- KIT_VERSION: v{{VERSION}} -->
+# Decisions Index (ADR)
+
+> **Trí nhớ quyết định kiến trúc của dự án.** AI ở Bước 1 PHẢI đọc file này trước khi sửa source (hook `enforce-docs-first` chặn nếu chưa đọc). Mỗi quyết định kiến trúc = 1 file `docs/decisions/NNNN-<slug>.md`.
+>
+> **Mục đích**: chống flip-flop kiến trúc xuyên session — Agent biết đã chọn gì, vì sao, đã loại phương án nào (kèm root cause), và hạn chế đã biết.
+
+## Cách dùng (BẮT BUỘC)
+
+1. **Trước khi đổi kiến trúc 1 module** → đọc ADR `Accepted (LOCKED)` của module đó. KHÔNG đảo ngược khi chưa supersede tường minh.
+2. **Tạo ADR mới**: copy `~/.cursor/templates/adr.md.tpl` (hoặc `~/.config/opencode/templates/adr.md.tpl`) → `docs/decisions/NNNN-<slug>.md`, đánh số `NNNN` = max hiện có + 1.
+3. **Supersede (đảo/đổi quyết định cũ)**: tạo ADR mới với `Supersedes: ADR-XXXX` + chứng minh root cause cũ hết đúng; đổi ADR cũ sang `Status: Superseded by ADR-NNNN`. Cập nhật bảng dưới.
+4. Cập nhật bảng dưới + link ADR vào `docs/modules/<slug>/README.md` (section "## Quyết định kiến trúc (ADR)").
+5. Chi tiết: skill `decision-recorder`.
+
+## Quyết định hiện có
+
+<!-- BEGIN PROJECT DECISIONS -->
+| ADR | Tiêu đề (ngắn) | Status | Module(s) | Date |
+|---|---|---|---|---|
+| (chưa có) | | | | |
+<!-- END PROJECT DECISIONS -->
+
+## Quy ước
+
+- File: `docs/decisions/NNNN-<slug-kebab-case>.md` (NNNN = 4 chữ số tăng dần).
+- Status: `Accepted (LOCKED)` (đang hiệu lực, khóa) → `Superseded by ADR-MMMM` (đã thay thế).
+- ADR token-lean (soft target ~40 dòng); chi tiết đầy đủ ở `Plan nguồn` (tầng chi tiết, nạp khi cần).

package/templates/docs-INDEX.md.tpl

@@ -9,6 +9,7 @@
 | Đường dẫn | Mục đích |
 |---|---|
 | `docs/modules/<name>/README.md` | Mục đích, public API, deps của từng module |
+| `docs/decisions/INDEX.md` + `docs/decisions/NNNN-*.md` | Trí nhớ quyết định kiến trúc (ADR): chọn gì, vì sao, loại phương án nào, root cause |
 <!-- END PROJECT DOC STRUCTURE -->
 
 ## Modules hiện có
@@ -34,6 +35,7 @@
 | email, mail, notification, thông báo, push, SMS | (vd: `notifications`) | |
 | upload, file, ảnh, image, storage, S3 | (vd: `storage`) | |
 | search, tìm kiếm, filter, sort | (vd: `search`) | |
+| quyết định, kiến trúc, ADR, decision, architecture, vì sao, why, revert, đảo ngược, supersede | `docs/decisions/` (xem `docs/decisions/INDEX.md`) | Đọc ADR liên quan TRƯỚC khi đổi kiến trúc |
 | (thêm dòng cho mỗi domain concept của dự án) | | |
 <!-- END PROJECT TOKEN ROUTING -->
 
@@ -46,6 +48,11 @@
 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>/`).
+5. Nếu module có quyết định kiến trúc đáng nhớ → tạo ADR (`docs/decisions/`) + link vào README module (section "## Quyết định kiến trúc (ADR)"). Xem skill `decision-recorder`.
+
+## Decisions (ADR) hiện có
+
+Xem `docs/decisions/INDEX.md` — trí nhớ quyết định kiến trúc (chống flip-flop xuyên session). Đọc ADR liên quan TRƯỚC khi đổi kiến trúc một module.
 
 ## Plans hiện có
 

package/templates/plans-INDEX.md.tpl

@@ -31,6 +31,7 @@
 - Status trong file: `Draft` (chờ user review) → `In Progress` (đã approve) → `Done`.
 - **Auto-archive**: ngay khi đổi Status → Done, chạy `git mv plans/<file>.md plans/archive/<file>.md` và update bảng Archived bên trên.
 - Plan template: 5 sections (Hiểu yêu cầu, Mục tiêu, Modules ảnh hưởng, Files ảnh hưởng, Tasks). Plan minimal chỉ dùng khi vẫn muốn audit cho task nhỏ.
+- **Plan đổi/đảo kiến trúc** PHẢI có section "## Quyết định kiến trúc" (`Supersede ADR-NNNN` + lý do root cause cũ hết đúng) và sinh/cập nhật ADR trong `docs/decisions/` ở Bước 5. Xem skill `decision-recorder`.
 - Skill: `~/.cursor/skills/plan-writer/SKILL.md`.
 
 ## Ghi chú riêng của dự án

package/update.ps1

@@ -7,6 +7,7 @@
 #   .\update.ps1 -Check                 # chỉ check, không cài
 #   .\update.ps1 -Project C:\path       # global + sync thêm project chỉ định
 #   .\update.ps1 -AllProjects           # global + sync MỌI project trong registry
+#   .\update.ps1 -Scan [-ScanRoot path] # dò OM project (mặc định $HOME) → seed registry → sync all
 #   .\update.ps1 -SkipProjects          # global only (old behavior)
 
 param(
@@ -15,6 +16,8 @@ param(
     [switch]$Check,
     [switch]$SkipProjects,
     [switch]$AllProjects,
+    [switch]$Scan,
+    [string]$ScanRoot,
     [string[]]$Project
 )
 
@@ -124,6 +127,49 @@ function Invoke-PruneRegistry {
     return $pruned
 }
 
+# Helper: scan tìm OM project (docs\INDEX.md + AGENTS.md) → seed registry mỗi home tồn tại
+function Invoke-ScanSeed {
+    $root = if ($ScanRoot) { $ScanRoot } else { $env:USERPROFILE }
+    $absRoot = (Resolve-Path $root -ErrorAction SilentlyContinue).Path
+    if (-not $absRoot) { Write-Host "  [!] Scan root không tồn tại: $root"; return }
+
+    $homes = @()
+    if (Test-Path (Join-Path $env:USERPROFILE ".cursor\.openmoneta-version")) {
+        $homes += (Join-Path $env:USERPROFILE ".cursor\.openmoneta-projects")
+    }
+    $ocBase = if ($env:XDG_CONFIG_HOME) { "$env:XDG_CONFIG_HOME\opencode" } else { "$env:USERPROFILE\.config\opencode" }
+    if (Test-Path (Join-Path $ocBase ".openmoneta-version")) {
+        $homes += (Join-Path $ocBase ".openmoneta-projects")
+    }
+    if ($homes.Count -eq 0) { Write-Host "  [!] Chưa có install home nào để seed registry."; return }
+
+    $prune = @('node_modules', '.git', 'Library', '.Trash', '.cache', '.npm', '.cargo', '.gradle', '.venv', 'dist', 'build')
+    Write-Host "  Scanning '$absRoot' (depth ~6)..."
+    $indexes = Get-ChildItem -Path $absRoot -Recurse -Depth 6 -Filter "INDEX.md" -File -ErrorAction SilentlyContinue |
+        Where-Object { (Split-Path $_.DirectoryName -Leaf) -eq "docs" }
+
+    $found = 0; $seeded = 0
+    $absKit = (Resolve-Path $RepoDir -ErrorAction SilentlyContinue).Path
+    foreach ($idx in $indexes) {
+        $proj = Split-Path (Split-Path $idx.FullName -Parent) -Parent
+        $skip = $false
+        foreach ($d in $prune) { if ($proj -like "*\$d\*" -or $proj -like "*\$d") { $skip = $true; break } }
+        if ($skip) { continue }
+        if (-not (Test-Path (Join-Path $proj "AGENTS.md"))) { continue }
+        $abs = (Resolve-Path $proj -ErrorAction SilentlyContinue).Path
+        if (-not $abs -or $abs -eq $absKit) { continue }
+        $found++
+        foreach ($reg in $homes) {
+            $existing = @()
+            if (Test-Path $reg) { $existing = Get-Content $reg | ForEach-Object { $_.Trim() } | Where-Object { $_ } }
+            if ($existing -contains $abs) { continue }
+            Add-Content -Path $reg -Value $abs
+            $seeded++
+        }
+    }
+    Write-Host "  Scan: thấy $found OM project, seed $seeded entry mới vào registry."
+}
+
 # Helper: collect projects to sync
 function Get-OpenMonetaProjects {
     $found = @()
@@ -262,6 +308,13 @@ if ($SkipProjects) {
     exit 0
 }
 
+if ($Scan) {
+    $AllProjects = $true
+    Write-Host ""
+    Write-Host "==> -Scan: dò OM project để seed registry..."
+    Invoke-ScanSeed
+}
+
 if ($AllProjects) {
     Write-Host ""
     Write-Host "==> -AllProjects: dọn registry + gom mọi project đã đăng ký..."

package/update.sh

@@ -9,6 +9,7 @@
 #   bash update.sh --check              # chỉ check, không cài
 #   bash update.sh --project /path      # global + sync thêm project chỉ định
 #   bash update.sh --all-projects       # global + sync MỌI project trong registry
+#   bash update.sh --scan [root]        # dò OM project (mặc định $HOME) → seed registry → sync all
 #   bash update.sh --skip-projects      # global only (old behavior)
 
 set -euo pipefail
@@ -22,31 +23,42 @@ SKIP_PROJECTS=0
 FORCE=0
 CHECK_ONLY=0
 ALL_PROJECTS=0
+SCAN=0
+SCAN_ROOT=""
 PROJECT_PATHS=()
 
-for arg in "$@"; do
-  case "$arg" in
+while [[ $# -gt 0 ]]; do
+  case "$1" in
     --yes|-y) AUTO_YES=1 ;;
     --force) FORCE=1 ;;
     --check) CHECK_ONLY=1 ;;
     --all-projects) ALL_PROJECTS=1 ;;
     --skip-projects) SKIP_PROJECTS=1 ;;
+    --scan)
+      SCAN=1
+      ALL_PROJECTS=1
+      if [[ -n "${2:-}" && "${2:-}" != -* ]]; then
+        SCAN_ROOT="$2"
+        shift
+      fi
+      ;;
     --help|-h)
-      grep '^#' "$0" | sed 's/^# \?//' | head -17
+      grep '^#' "$0" | sed 's/^# \?//' | head -18
       exit 0
       ;;
     --project)
-      shift
-      if [[ -n "${1:-}" && "${1:-}" != -* ]]; then
-        PROJECT_PATHS+=("$1")
+      if [[ -n "${2:-}" && "${2:-}" != -* ]]; then
+        PROJECT_PATHS+=("$2")
+        shift
       fi
       ;;
     *)
-      if [[ "$arg" != -* ]]; then
-        PROJECT_PATHS+=("$arg")
+      if [[ "$1" != -* ]]; then
+        PROJECT_PATHS+=("$1")
       fi
       ;;
   esac
+  shift
 done
 
 cd "$REPO_DIR"
@@ -146,6 +158,45 @@ prune_registry() {
   return 0
 }
 
+# === Helper: scan tìm OM project (docs/INDEX.md + AGENTS.md) → seed registry mỗi home tồn tại ===
+scan_seed() {
+  local root="${SCAN_ROOT:-$HOME}"
+  local abs_root
+  abs_root="$(cd "$root" 2>/dev/null && pwd -P)" || { echo "  [!] Scan root không tồn tại: $root"; return 0; }
+
+  local homes=()
+  [[ -f "$HOME/.cursor/.openmoneta-version" ]] && homes+=("$HOME/.cursor/.openmoneta-projects")
+  [[ -f "${XDG_CONFIG_HOME:-$HOME/.config}/opencode/.openmoneta-version" ]] && \
+    homes+=("${XDG_CONFIG_HOME:-$HOME/.config}/opencode/.openmoneta-projects")
+  if [[ ${#homes[@]} -eq 0 ]]; then
+    echo "  [!] Chưa có install home nào để seed registry."
+    return 0
+  fi
+
+  echo "  Scanning '$abs_root' (maxdepth project ~5)..."
+  local found=0 seeded=0 idx proj abs reg
+  while IFS= read -r idx; do
+    proj="$(dirname "$(dirname "$idx")")"
+    [[ -f "$proj/AGENTS.md" ]] || continue
+    abs="$(cd "$proj" 2>/dev/null && pwd -P)" || continue
+    [[ -z "$abs" || "$abs" == "$REPO_DIR" ]] && continue
+    found=$((found + 1))
+    for reg in "${homes[@]}"; do
+      if [[ -f "$reg" ]] && grep -qFx "$abs" "$reg" 2>/dev/null; then
+        continue
+      fi
+      echo "$abs" >> "$reg"
+      seeded=$((seeded + 1))
+    done
+  done < <(find "$abs_root" -maxdepth 7 \
+      \( -name node_modules -o -name .git -o -name Library -o -name .Trash \
+         -o -name .cache -o -name .npm -o -name .cargo -o -name .gradle \
+         -o -name .venv -o -name dist -o -name build \) -prune -o \
+      -type f -path '*/docs/INDEX.md' -print 2>/dev/null)
+
+  echo "  Scan: thấy $found OM project, seed $seeded entry mới vào registry."
+}
+
 # === Helper: collect projects to sync ===
 collect_projects() {
   local found=()
@@ -293,6 +344,12 @@ print_registry_hint() {
   return 0
 }
 
+if [[ $SCAN -eq 1 ]]; then
+  echo ""
+  echo "==> --scan: dò OM project để seed registry..."
+  scan_seed
+fi
+
 if [[ $ALL_PROJECTS -eq 1 ]]; then
   echo ""
   echo "==> --all-projects: dọn registry + gom mọi project đã đăng ký..."