openmoneta-dev-kit 1.10.4 → 1.11.0

package/VERSION

@@ -1 +1 @@
-1.10.4
+1.11.0

package/opencode/AGENTS.md.tpl

@@ -6,18 +6,31 @@
 
 1. Luôn trả lời bằng tiếng Việt.
 2. Khi project có `docs/INDEX.md`, đọc file đó trước khi đọc source code để dùng Token Routing.
-3. Dùng OpenMoneta workflow 6 bước: phân tích yêu cầu, thiết kế module, adaptive planning, triển khai, update docs/close plan, safe push khi user yêu cầu push.
+3. Dùng OpenMoneta workflow 6 bước (xem bên dưới).
 4. Task nhỏ/rõ ràng có thể không cần plan. Task lớn/rủi ro/mơ hồ phải tạo repo plan `Status: Draft`, trình user review, chỉ triển khai sau khi user approve và đổi `Status: In Progress`.
 5. Nếu có plan `In Progress`, chỉ sửa file trong `## Files ảnh hưởng` / `## Files thay đổi`.
 6. Khi user yêu cầu push, phải fetch/rebase remote ngay trước push; không dùng `git push --force` trên shared branch.
 
+## 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).
+- **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`.
+- **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`.
+  - [ ] 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.
+
 ## OpenCode Notes
 
 - OpenCode đọc global rules từ `~/.config/opencode/AGENTS.md`.
 - OpenCode đọc project rules từ `AGENTS.md` ở project root. Project rules là source of truth cho từng repo.
 - OpenMoneta skills được cài vào `~/.config/opencode/skills/*/SKILL.md` và agent nên load bằng skill tool khi cần.
 - OpenMoneta subagents được cài vào `~/.config/opencode/agents/`.
-- OpenCode plugin guard trong `~/.config/opencode/plugins/openmoneta-guard.ts` enforce một phần workflow tương đương Cursor hooks.
+- 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).
 
 ## Khi Bắt Đầu Task
 

package/opencode/plugins/openmoneta-guard.ts

@@ -253,11 +253,174 @@ function fail(message: string): never {
   throw new Error(`[OpenMoneta Dev Kit]\n${message}`)
 }
 
-export const OpenMonetaGuard = async (ctx: { worktree?: string; directory?: string }) => {
+// === verify-completion parity (port từ Cursor hook verify-completion.sh) ===
+
+const VERIFY_LOOP_LIMIT = 4
+const NON_CODE_CHANGE = /^(docs\/|plans\/|README|\.gitignore|\.env\.example|AGENTS\.md|\.cursor\/)/
+
+function readSessionChanges(root: string): string[] {
+  const file = path.join(root, ".cursor", ".session-changes.json")
+  if (!fs.existsSync(file)) return []
+  try {
+    const data = JSON.parse(fs.readFileSync(file, "utf8")) as { changes?: { path?: string }[] }
+    return (data.changes || []).map((c) => asString(c.path)).filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
+function clearSessionChanges(root: string) {
+  fs.rmSync(path.join(root, ".cursor", ".session-changes.json"), { force: true })
+}
+
+// Port logic infer module slug từ scripts/list-affected-modules.sh
+function inferModules(paths: string[]): { slug: string; docsPath: string }[] {
+  const out = new Map<string, string>()
+  for (const p of paths) {
+    if (!p) continue
+    if (/^(docs|plans|tests|scripts|infra|logs|\.cursor|node_modules)\//.test(p)) continue
+    if (["AGENTS.md", "CHANGELOG.md", "README.md", ".gitignore", ".env.example"].includes(p)) continue
+    const seg = p.split("/")
+    if (p.startsWith("apps/") && seg.length >= 2) {
+      out.set(`apps-${seg[1]}`, `docs/modules/apps-${seg[1]}`)
+    } else if (p.startsWith("packages/") && seg.length >= 2) {
+      out.set(`packages-${seg[1]}`, `docs/modules/packages-${seg[1]}`)
+    } else if (p.startsWith("src/modules/") && seg.length >= 3) {
+      out.set(seg[2], `docs/modules/${seg[2]}`)
+    } else if (p.startsWith("src/") && seg.length >= 2 && seg[1] !== "modules") {
+      out.set(seg[1], `docs/modules/${seg[1]}`)
+    }
+  }
+  return [...out.entries()].map(([slug, docsPath]) => ({ slug, docsPath }))
+}
+
+function planUntickedCount(planPath: string): number {
+  const match = fs.readFileSync(planPath, "utf8").match(/^- \[ \]/gm)
+  return match ? match.length : 0
+}
+
+// Check 9: có heading "## Hiểu yêu cầu" + nội dung không trống (bỏ dòng blockquote `>`)
+function planHasUnderstanding(planPath: string): boolean {
+  const lines = fs.readFileSync(planPath, "utf8").split(/\r?\n/)
+  let inSection = false
+  let foundHeading = false
+  let hasContent = false
+  for (const line of lines) {
+    if (/^##\s+Hiểu yêu cầu/.test(line)) {
+      foundHeading = true
+      inSection = true
+      continue
+    }
+    if (inSection && /^##\s+/.test(line)) break
+    if (inSection) {
+      const trimmed = line.trim()
+      if (trimmed && !trimmed.startsWith(">")) hasContent = true
+    }
+  }
+  return foundHeading && hasContent
+}
+
+// Build danh sách issue tương đương verify-completion Check 5/6/9.
+function buildVerifyIssues(root: string): string[] {
+  const paths = readSessionChanges(root)
+  if (paths.length === 0) return []
+  if (!paths.some((p) => !NON_CODE_CHANGE.test(p))) return []
+
+  const issues: string[] = []
+
+  const draftPlans = listPlans(root, "Draft")
+  const inProgressPlans = listPlans(root, "In Progress")
+  const activePlans = [...draftPlans, ...inProgressPlans]
+
+  // Check 5: plan active phải Done + hết checkbox
+  for (const plan of activePlans) {
+    const name = path.basename(plan)
+    const unticked = planUntickedCount(plan)
+    if (unticked > 0) {
+      issues.push(`❌ Plan '${name}' còn ${unticked} checkbox '- [ ]' chưa tick. Hoàn thành các task (Bước 5).`)
+    }
+    if (draftPlans.includes(plan)) {
+      issues.push(
+        `❌ Plan '${name}' vẫn ở trạng thái Draft (chưa được user approve) nhưng có code change gắn vào.`,
+      )
+    } else {
+      issues.push(
+        `❌ Plan '${name}' vẫn In Progress. Đổi Status: Done + git mv plans/${name} sang plans/archive/ (Bước 5).`,
+      )
+    }
+  }
+
+  // Check 9: plan active + plan sửa trong session phải có "## Hiểu yêu cầu" không trống
+  const planSet = new Set<string>(activePlans)
+  for (const rel of paths) {
+    if (/^plans\/.*\.md$/.test(rel) && rel !== "plans/INDEX.md") {
+      const abs = path.join(root, rel)
+      if (fs.existsSync(abs)) planSet.add(abs)
+    }
+  }
+  for (const plan of planSet) {
+    if (!planHasUnderstanding(plan)) {
+      issues.push(
+        `❌ Plan '${path.basename(plan)}' thiếu/trống section '## Hiểu yêu cầu' (audit clarify Bước 1).`,
+      )
+    }
+  }
+
+  // Check 6: module bị sửa phải có docs/modules/<slug>/README.md
+  for (const { slug, docsPath } of inferModules(paths)) {
+    if (!fs.existsSync(path.join(root, docsPath, "README.md"))) {
+      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).`,
+      )
+    }
+  }
+
+  return issues
+}
+
+type VerifyLoopState = { sessionID: string; count: number }
+
+function readVerifyLoop(root: string): VerifyLoopState {
+  const file = path.join(root, ".cursor", ".openmoneta-verify-loop.json")
+  if (!fs.existsSync(file)) return { sessionID: "", count: 0 }
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as VerifyLoopState
+  } catch {
+    return { sessionID: "", count: 0 }
+  }
+}
+
+function writeVerifyLoop(root: string, state: VerifyLoopState) {
+  const file = path.join(root, ".cursor", ".openmoneta-verify-loop.json")
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`)
+}
+
+function clearVerifyLoop(root: string) {
+  fs.rmSync(path.join(root, ".cursor", ".openmoneta-verify-loop.json"), { force: true })
+}
+
+type SessionPromptClient = {
+  session?: {
+    prompt?: (input: {
+      path: { id: string }
+      body: { parts: { type: string; text: string }[] }
+    }) => Promise<unknown>
+  }
+}
+
+type GuardContext = {
+  worktree?: string
+  directory?: string
+  client?: SessionPromptClient
+}
+
+export const OpenMonetaGuard = async (ctx: GuardContext) => {
   const globalKey = Symbol.for("openmoneta.devkit.guard.loaded")
   const globalState = globalThis as Record<symbol, number>
   globalState[globalKey] = (globalState[globalKey] || 0) + 1
 
+  const client = ctx.client
   const root = projectRoot(ctx)
   const marker = path.join(root, ".cursor", ".docs-index-read")
   const guardLoadedMarker = path.join(root, ".cursor", ".openmoneta-guard-loaded.json")
@@ -271,7 +434,7 @@ export const OpenMonetaGuard = async (ctx: { worktree?: string; directory?: stri
       {
         loaded_at: new Date().toISOString(),
         root,
-        version: "1.8.6",
+        version: "1.11.0",
         load_count: globalState[globalKey],
       },
       null,
@@ -383,6 +546,62 @@ export const OpenMonetaGuard = async (ctx: { worktree?: string; directory?: stri
         trackChange(root, relativePath, input.tool)
       }
     },
+
+    // Parity với Cursor hook `stop`/verify-completion. OpenCode `event` không block
+    // được như Cursor, nên khi phiên idle mà còn thiếu B2/B5 ta re-prompt lại session
+    // để buộc Agent hoàn tất, kèm loop guard chống lặp vô hạn.
+    event: async ({
+      event,
+    }: {
+      event: { type: string; properties?: Record<string, unknown> }
+    }) => {
+      if (event.type !== "session.idle") return
+      try {
+        const issues = buildVerifyIssues(root)
+        const sessionID = asString(event.properties?.sessionID)
+
+        if (issues.length === 0) {
+          clearSessionChanges(root)
+          clearVerifyLoop(root)
+          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. ` +
+              `Hãy review thủ công:\n${issues.join("\n")}`,
+          )
+          return
+        }
+
+        if (!client?.session?.prompt || !sessionID) {
+          console.warn(
+            `[OpenMoneta Dev Kit] verify-completion còn ${issues.length} việc nhưng không re-prompt được ` +
+              `(thiếu client/sessionID):\n${issues.join("\n")}`,
+          )
+          return
+        }
+
+        const message = [
+          "[OpenMoneta Dev Kit — verify-completion] Phiên chưa nên kết thúc, còn thiếu Bước 2/5:",
+          "",
+          ...issues,
+          "",
+          `Hoàn tất các mục trên rồi mới kết thúc. (Còn ${VERIFY_LOOP_LIMIT - count - 1} lần nhắc nữa.)`,
+        ].join("\n")
+
+        await client.session.prompt({
+          path: { id: sessionID },
+          body: { parts: [{ type: "text", text: message }] },
+        })
+        writeVerifyLoop(root, { sessionID, count: count + 1 })
+      } catch (err) {
+        console.warn(`[OpenMoneta Dev Kit] verify-completion event error: ${String(err)}`)
+      }
+    },
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmoneta-dev-kit",
-  "version": "1.10.4",
+  "version": "1.11.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/src/commands/update.js

@@ -40,16 +40,17 @@ async function run(args) {
   const pkgRoot = getPkgRoot()
 
   try {
-    if (!isWindows()) {
-      execSync("git rev-parse --is-inside-work-tree", { stdio: "pipe", cwd: pkgRoot })
-      const branch = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8", cwd: pkgRoot }).trim()
-      console.log(`\n  ▶ Git pull (branch: ${branch})...`)
-      execSync(`git pull origin "${branch}"`, { stdio: "inherit", cwd: pkgRoot })
-    } else {
-      execSync("powershell.exe -Command \"& { git pull }\"", { stdio: "inherit", cwd: pkgRoot, shell: true })
-    }
+    execSync("git rev-parse --is-inside-work-tree", { stdio: "pipe", cwd: pkgRoot })
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8", cwd: pkgRoot }).trim()
+    console.log(`\n  ▶ Git pull (branch: ${branch})...`)
+    execSync(`git pull origin "${branch}"`, { stdio: "inherit", cwd: pkgRoot })
   } catch {
-    console.warn(`  ⚠ Không thể git pull, dùng source hiện tại.`)
+    try {
+      console.log(`\n  ▶ NPM update: openmoneta-dev-kit@latest...`)
+      execSync(`npm install -g openmoneta-dev-kit@latest`, { stdio: "inherit" })
+    } catch {
+      console.warn(`  ⚠ Không thể cập nhật source (git/npm). Dùng source hiện tại.`)
+    }
   }
 
   if (isInstalled("cursor")) {

package/templates/AGENTS.md.tpl

@@ -54,7 +54,7 @@
 
 ### Bước 5 — Update doc + close plan
 
-> Skill: `module-architect` (đã merge `doc-maintainer`). Hook `verify-completion` Check 6 chặn nếu module README thiếu.
+> Skill: `module-architect` (đã merge `doc-maintainer`). Cursor: hook `verify-completion` Check 6 chặn kết thúc nếu module README thiếu. OpenCode: plugin guard `event:session.idle` re-prompt nhắc hoàn tất (loop guard ≤4 lần).
 
 - 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`.
@@ -91,11 +91,13 @@
 
 ## Hooks enforce
 
+> Cursor dùng bash hooks (`~/.cursor/hooks/`). OpenCode dùng plugin guard `openmoneta-guard.ts` — `tool.execute.before/after` tương đương 2 hook đầu, `event:session.idle` tương đương `verify-completion` (re-prompt thay vì block cứng).
+
 | 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` |
 | `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 | BLOCK kết thúc nếu Check 5/6/9 fail (plan Done + checkbox, module README, "Hiểu yêu cầu") |
+| `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 |
 
 ## Override cho dự án này