openmoneta-dev-kit 2.1.0 → 2.2.0

package/VERSION

@@ -1 +1 @@
-2.1.0
+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.1.0",
+  "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/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/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/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>/`).