[CLAUDE] Docs+Memory: Session 29 FINAL wrap — Plan CA + Plan B Contract V2 cumulative
All checks were successful
Deploy SOLUTION_ERP / build-deploy (push) Successful in 3m31s
All checks were successful
Deploy SOLUTION_ERP / build-deploy (push) Successful in 3m31s
20 commits S29 push 4 CI Runs PASS (#229+#230 Plan CA, #231+#232 Plan B).
2 big plans END-TO-END deployed prod.
Changes (docs + memory + scripts — CI skip per paths-ignore):
docs/:
- STATUS.md: S29 FINAL wrap header với cumulative summary 20 commits +
multi-agent ROI ~565K + 8 patterns NEW + state stats (33 mig, 60 tables,
51 gotcha, 14 AppRoles, 34 active users, 4× bundle rotate)
- HANDOFF.md: S29 FINAL wrap header với end-to-end V2 capability + pending S30+
follow-up (anh restart CLI MCP RAG hot-reload, UAT verify V2, test bundle
Plan B, curate dedicated session)
- gotchas.md: +gotcha #51 INFRASTRUCTURE vs DEMO seed phân biệt (Plan B
Hotfix CICD lesson) với decision tree + seed classification table
- changelog/sessions/2026-05-22-s29-plan-ca-plan-b-contract-v2-wire.md:
Session log đầy đủ 20 commits + 4× Smart Friend pattern proven + 8
patterns NEW + file-touched list + NEW capability end-to-end test plan
.claude/agent-memory/:
- 4 MEMORY.md flush S29 wrap entry FIFO each agent perspective:
- Investigator (25.2 KB just over threshold) — Plan CA + Plan B pre-flight
2 spawn + 3 patterns NEW (terrain map, V1+V2 coexist, reference templates)
- Implementer (35.4 KB over hard threshold, defer curate S30) — 5 spawn
cookie-cutter + E3 stopped + Pattern 12-bis NEW (cross-module entity mirror)
- Reviewer (23.0 KB compacted) — 4 spawn 2 MAJOR catches + Cat 3 security
cross-module validation foundation reinforced
- CICD Monitor (24.9 KB) — 4 Runs verify + CRITICAL DemoSeed gate catch +
Stage 4.6 sqlcmd seed verify foundation + Discovery #6 gotcha #51 cross-ref
- implementer/pattern_master_page_mirror.md (NEW Plan CA Chunk B Pattern 16-bis)
scripts/:
- plan-ca-{verify-menu,verify-perms,run-perms}.{sql,ps1} (5 verify scripts)
- plan-b-{verify-prod,run-verify}.{sql,ps1} (2 verify scripts)
Smart Friend pattern proven 4× cumulative S22 #44 + S25 #48 + S29 Reviewer
#ApplicableType + S29 CICD #DemoSeed.
Pending S30+:
- Anh restart CLI hot-reload MCP RAG cho 4 sub-agents (commit b51fc94)
- Anh UAT verify V2 contract end-to-end (Drafter → CCM approve → DaPhatHanh)
- Test bundle Plan B (regression ApproveV2Async + ApplicableType validation)
- Curate dedicated session 4 MEMORY (Implementer 35.4 KB priority)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
pqhuy1987
File diff suppressed because one or more lines are too long
@ -2,7 +2,9 @@
|
||||
|
||||
> **Update rule:** trước khi bắt đầu 1 task → ghi row vào `🔥 In Progress`. Xong → chuyển sang `✅ Recently Done`.
|
||||
|
||||
**Last updated:** 2026-05-22 (Session 29 — **🎯 Plan CA wire DONE + Hotfix 1 deploy**: 6 commits + 1 hotfix push `3cb54e0..e55d96b` cumulative. Move "Cấu hình danh mục dùng chung" (9 menu: Master + Suppliers + Projects + Departments + Catalogs + 4 sub-catalogs) từ fe-admin → fe-user/eoffice + add role mới `CatalogManager` + demo user `catalog.manager@solutions.com.vn`. **Chunks:** A 80d39a0 BE Role + Seed (em main, 64 LOC) · B 06a441c FE move 4 master pages 948 LOC (Implementer Case 2 cookie-cutter mirror byte-identical SHA256 4 file) · C c995f42 Sidebar filter 2 app (em main, 14 LOC) · D 4a592cf Seed demo user (em main, 7 LOC) · D2 68bcedd Hotfix password ≥12 chars S22+2 policy (em main, Reviewer pre-push CATCH critical) · HF1 e55d96b Add 7 entries `resolvePath` staticMap fe-user (em main, anh UAT screenshot CATCH silent sidebar drop). **2 CI runs PASS:** Run #229 sha=68bcedd 3m32s + Run #230 sha=e55d96b 3m24s. Bundle hash 2× rotate: fe-admin `BvcWrq2z→leEMWFLU`, fe-user `Bg2FNeIz→DVBLmZlt→Dgn1iU9E`. **Multi-agent ROI Plan CA:** 🟦 Investigator 1 spawn ~15K (terrain map 9 menu + GOTCHA tree-inherit) + 🟨 Implementer Case 2 1 spawn ~10K (byte-identical mirror 4 page) + 🟥 Reviewer 2 spawn ~165K (CRITICAL catch password policy) + 🟩 CICD Monitor 2 spawn fail 529 transient (em main fallback manual smoke) + 👤 Chủ trì Solo Chunk A/C/D/D2/HF1 ~100K. **NEW gotcha #50** "Page move cross-app — `Layout.tsx` `resolvePath` staticMap missed mirror → silent sidebar drop" + Pattern reusable cross-project: **4-place mirror checklist** khi Implementer Case 2 cookie-cutter copy page (page + Routes + menuKeys.ts + Layout.tsx staticMap — Implementer Chunk B missed point 4). Implementer MEMORY Pattern 16-bis NEW. **State chốt S29 Plan CA:** 31 mig (no schema change) · 59 tables · ~146 endpoints · **36 FE pages (+4: fe-user master/{Suppliers,Projects,Departments,Catalogs}Page)** · **111 test pass unchanged** (UAT skip per chunk + cookie-cutter mirror) · **50 gotcha (+1 #50)** · 25 memory user-level · 6 skills · 4 sub-agents · **13 AppRoles (+1 CatalogManager)** · **34 active prod users (+1 catalog.manager@solutions.com.vn)**. Catalog manager login `CatalogMgr@2026` (15 chars policy compliant). 7 commits remote `3cb54e0..e55d96b`.)
|
||||
**Last updated:** 2026-05-22 (Session 29 **FINAL wrap** — **🎯 Plan CA + Plan B Contract V2 wire ALL DEPLOYED PROD**: cumulative **20 commits push 4 CI Runs PASS** (#229 + #230 + #231 + #232). **2 big plans done end-to-end:** Plan CA Move "Cấu hình danh mục dùng chung" admin → eoffice (7 commits + Hotfix 1) + Plan B Contract V2 wire mirror PE Mig 22-26 (9 chunks + Hotfix Reviewer + Hotfix CICD). **Multi-agent ROI explosive S29:** 🟦 Investigator 2 spawn ~40K (Plan CA terrain map + Plan B V1 audit) + 🟨 Implementer Case 2 5 spawn ~82K (Plan CA Chunk B + Plan B A2/C/D + E3 stopped mid-task) + 🟥 **Reviewer 4 spawn ~355K** (Plan CA Hotfix D2 password ≥12 MAJOR catch + Plan B Hotfix ApplicableType=Contract MAJOR catch — Smart Friend pattern 4× cumulative) + 🟩 **CICD Monitor 3 spawn ~90K** (2 fail 529 transient em main fallback manual + Plan B SeedSampleContractWorkflowV2 CRITICAL DemoSeed gate catch — gotcha #51 NEW). **Patterns NEW saved S29:** (1) 9-menu permission terrain map (Investigator) (2) V1+V2 coexist boundary (Investigator) (3) reference template paths cross-module mirror PE→Contract (Investigator) (4) Pattern 12-bis cross-module entity cookie-cutter mirror (Implementer) (5) Pattern 16-bis 4-place mirror cross-app reinforced 2× (Implementer) (6) Cross-module security validation mirror Cat 3 (Reviewer) (7) INFRASTRUCTURE vs DEMO seed classification gotcha #51 (CICD) (8) Race condition em main + Implementer parallel BE → stash workaround OR sequential preferred (Implementer). **3 hotfix cumulative:** Plan CA HF1 resolvePath staticMap + Plan CA D2 password ≥12 chars + Plan B Reviewer ApplicableType=Contract + Plan B CICD SeedSampleContractWorkflowV2 ungate. **NEW capability prod:** demo user `catalog.manager@solutions.com.vn / CatalogMgr@2026` (role CatalogManager — full CRUD 9 menu Master+Catalogs) + Drafter có thể create V2 contract qua Workspace dropdown `QT-HD-V2-001` sample workflow. **MCP RAG tools added cho 4 agent definitions** (commit `b51fc94`) — anh restart CLI để hot-reload. State chốt: **33 mig (+2 Mig 32+33)** · **60 tables (+1 ContractLevelOpinions)** · **~148 endpoints (+1 V2 contract create)** · **38 FE pages (+3: 4 master moved + WorkflowMatrixView counted unchanged S24)** · **111 test PASS unchanged** (UAT mode skip per chunk + cookie-cutter mirror) · **51 gotcha (+1 #51 INFRASTRUCTURE vs DEMO seed)** · **25 memory user-level unchanged** · 6 skills · 4 sub-agents (MCP RAG added pending CLI restart) · **14 AppRoles (+1 CatalogManager)** · **34 active prod users (+1 catalog.manager)** · **7 V1 contracts pinned coexist V2** · Bundle hash 4× rotate cumulative S29 (fe-admin: `BvcWrq2z→leEMWFLU→BBADl46y` + fe-user: `Bg2FNeIz→DVBLmZlt→Dgn1iU9E→DA_VI3zO`).)
|
||||
|
||||
**Last updated S29 prev wrap1:** 2026-05-22 (Session 29 — **🎯 Plan CA wire DONE + Hotfix 1 deploy**: 6 commits + 1 hotfix push `3cb54e0..e55d96b` cumulative. Move "Cấu hình danh mục dùng chung" (9 menu: Master + Suppliers + Projects + Departments + Catalogs + 4 sub-catalogs) từ fe-admin → fe-user/eoffice + add role mới `CatalogManager` + demo user `catalog.manager@solutions.com.vn`. **Chunks:** A 80d39a0 BE Role + Seed (em main, 64 LOC) · B 06a441c FE move 4 master pages 948 LOC (Implementer Case 2 cookie-cutter mirror byte-identical SHA256 4 file) · C c995f42 Sidebar filter 2 app (em main, 14 LOC) · D 4a592cf Seed demo user (em main, 7 LOC) · D2 68bcedd Hotfix password ≥12 chars S22+2 policy (em main, Reviewer pre-push CATCH critical) · HF1 e55d96b Add 7 entries `resolvePath` staticMap fe-user (em main, anh UAT screenshot CATCH silent sidebar drop). **2 CI runs PASS:** Run #229 sha=68bcedd 3m32s + Run #230 sha=e55d96b 3m24s. Bundle hash 2× rotate: fe-admin `BvcWrq2z→leEMWFLU`, fe-user `Bg2FNeIz→DVBLmZlt→Dgn1iU9E`. **Multi-agent ROI Plan CA:** 🟦 Investigator 1 spawn ~15K (terrain map 9 menu + GOTCHA tree-inherit) + 🟨 Implementer Case 2 1 spawn ~10K (byte-identical mirror 4 page) + 🟥 Reviewer 2 spawn ~165K (CRITICAL catch password policy) + 🟩 CICD Monitor 2 spawn fail 529 transient (em main fallback manual smoke) + 👤 Chủ trì Solo Chunk A/C/D/D2/HF1 ~100K. **NEW gotcha #50** "Page move cross-app — `Layout.tsx` `resolvePath` staticMap missed mirror → silent sidebar drop" + Pattern reusable cross-project: **4-place mirror checklist** khi Implementer Case 2 cookie-cutter copy page (page + Routes + menuKeys.ts + Layout.tsx staticMap — Implementer Chunk B missed point 4). Implementer MEMORY Pattern 16-bis NEW. **State chốt S29 Plan CA:** 31 mig (no schema change) · 59 tables · ~146 endpoints · **36 FE pages (+4: fe-user master/{Suppliers,Projects,Departments,Catalogs}Page)** · **111 test pass unchanged** (UAT skip per chunk + cookie-cutter mirror) · **50 gotcha (+1 #50)** · 25 memory user-level · 6 skills · 4 sub-agents · **13 AppRoles (+1 CatalogManager)** · **34 active prod users (+1 catalog.manager@solutions.com.vn)**. Catalog manager login `CatalogMgr@2026` (15 chars policy compliant). 7 commits remote `3cb54e0..e55d96b`.)
|
||||
|
||||
**Last updated S28 prev:** 2026-05-22 (Session 28 **FINAL wrap** — **🎯 S28 cumulative 12+ bước (t1→t6): Startup 9-step + RAG ROI verdict + bro correction mistake + scope-down + Layer A governance apply + 4 sub-agent flush MEMORY**. Bro broadcast **Layer A governance active 2026-05-22** (3-Layer distributed: A project-local active / B shared_global defer / C infrastructure anh pqhuy). **Quên rule cũ "mọi tương tác PHẢI store_memory" — ABANDONED.** Em main SOLUTION_ERP apply Layer A scope local: **4-category default** (decision/lesson/pattern-proven-≥2×/session-wrap) + **skip list nguyên** + 5 SOLUTION_ERP-specific adjustment cho Phase 9 UAT mode + **tag schema mandatory** `[type, phase, bc-or-module]` với type closed enum 6 (decision/lesson/pattern/gotcha/bug-fix/session-wrap) + phase enum 11 (phase-0 → phase-10+, current **phase-9 UAT ACTIVE**) + BC/module enum 8 domain (contract/pe/budget/master/identity/forms/workflow/notifications) + 5 cross-cutting (tests/infra/cicd/multi-agent/governance/docs) + optional prefix 8 (tech/agent/risk/severity/commit/mig/gotcha/plan). **source_path convention** `solution_erp/<area>/<topic>-<date>`. **Eval ritual** weekly Friday 5 metric từ 2026-05-29 → end-trial 2026-06-05. **10 golden query draft** ready. **6 chunk stored S28 t2-t6:** Protocol cross-project (deprecated S28 t4 scope-down) · Conversation log S28 t1+t2 · Commit pattern acknowledge · 2-week monitoring 5 measure · Scope-down acknowledge · Layer A policy apply. **4 sub-agent flush MEMORY DONE post-S27 model:inherit fix** — registry hot-reload verified all 4 (Investigator agentId `a2462`/`aeda4`, Implementer `a2a2f`, Reviewer `a9e94`, CICD Monitor `a8098`). Each Recent activity entry S28 t1 → S28 wrap góc nhìn từng con preserved cumulative S1-S27. **NEW memory user-level `feedback_interaction_logging_rag.md` SCOPE-DOWN S28 t4** (anti-pattern over-reach self-authorize cross-project rule + implicit consent risk lesson). Stats unchanged: 31 mig · 59 tables · ~146 endpoints · 35 FE pages · **111 test pass** · 49 gotcha · **25 memory user-level (+1 NEW interaction logging scope-down)** · 6 skills · 4 sub-agents (all verified hot-reload) · **3,462 RAG chunks SOLUTION_ERP** (+6 chunk store S28) + 6 MCP tools active. **Hit rate verify 3 query**: Plan B Contract V2 rerank 0.84 ✓ + gotcha #48 rerank 0.84/0.82/0.82 ✓ + per-NV 10-surface checklist hit (token overflow) ✓ — > 0.7 threshold pass cumulative. **0 commit remote S28** (all docs + memory + RAG store — anh chốt push thủ công sau approve). Plan B Contract V2 wire kick-off pending 2026-05-22+ (8-chunk pre-allocated 🟦 Investigator pre-flight + 🟨 Implementer Case 2 ×4 + 👤 Chủ trì Solo Service ApproveV2Async + 🟥 Reviewer pre-commit + 🟩 CICD Monitor post-deploy).)
|
||||
|
||||
|
||||
@ -0,0 +1,325 @@
|
||||
# Session 27 — 2026-05-22 — Memory Curate + RAG Manual Control + Multi-agent Setup Fix
|
||||
|
||||
**Dev:** Claude em main SOLUTION_ERP (sub-agent registry empty cả session - pitfall #1+#2 confirmed) + bro pqhuy
|
||||
**Duration:** ~5h (start ~17:00 → end ~22:00 GMT+7)
|
||||
**Base commit:** `d99069a` (S26 chốt cuối Plan AG6)
|
||||
**Final commits:** TBD (anh push manual sau approve)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Làm được
|
||||
|
||||
### Plan A.3 — RAG Manual Control + Custom Dashboard
|
||||
|
||||
🟧 **5 PS scripts** ở `D:\.claude-rag\scripts\` (em main solo cookie-cutter mirror — Implementer Case 2 ACCEPT criteria miss vì registry empty):
|
||||
- `start.ps1` (2.4 KB) - Qdrant background + health check (initial 3s warmup + TimeoutSec 5)
|
||||
- `stop.ps1` (1.4 KB) - Graceful stop + verify
|
||||
- `status.ps1` (6.2 KB) - 6-section terminal report colored
|
||||
- `dashboard.ps1` (17.4 KB) - Generate custom HTML + open browser
|
||||
- `boot.ps1` (1.4 KB) - Auto-boot sequence (Startup shortcut)
|
||||
|
||||
🟧 **6 `$PROFILE` aliases:** rag-start / rag-stop / rag-status / rag-dashboard / rag-restart / rag-boot
|
||||
|
||||
🟧 **Auto-boot Startup folder shortcut** `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\rag-boot.lnk` — auto-run boot.ps1 mỗi lần Windows boot.
|
||||
|
||||
🟧 **Custom MCP Dashboard HTML** `D:\.claude-rag\dashboard.html` (13.3 KB auto-gen) — 7 panels: Qdrant + MCP + Collections + Voyage + System + Agent MEMORY + Recent Logs. Auto-refresh 60s. Anthropic orange theme.
|
||||
|
||||
### Plan A.4 — RAG Onboarding Guide
|
||||
|
||||
🟧 **`docs/guides/rag-onboarding-guide.md`** (26.3 KB / ~440 lines / 13 sections + §A2):
|
||||
- 13 sections: TL;DR, Background, Pre-check, Bootstrap 3 step, 6 MCP tools matrix, 4 sub-agent brief, Permission, Workflow, Troubleshooting, Tunings, Best practices, Status monitoring §12, Distributed Approach B §13
|
||||
- §A2 Cấu trúc chuẩn em main pioneer (replaces Plan A.2 skip với full file tree + 8-step bootstrap checklist + 4 Gotcha discoveries S26-S27)
|
||||
- Native Qdrant vs Custom MCP dashboard comparison table
|
||||
|
||||
### Memory Curate (3 việc anh chốt OK)
|
||||
|
||||
🟧 **4 MEMORY curate** -60% size cumulative:
|
||||
- cicd-monitor: 72.4 KB → 15.8 KB (-78%)
|
||||
- implementer: 38.8 KB → 22.0 KB (-43%)
|
||||
- investigator: 34.9 KB → 16.3 KB (-53%)
|
||||
- reviewer: 34.5 KB → 17.9 KB (-48%)
|
||||
- Archive total 115 KB preserved verbose entries (rule §6.5 compliance)
|
||||
|
||||
🟧 **Audit drift §6.4 + §9.4** sớm (trigger +8 gotcha vượt threshold):
|
||||
- 5 file patched: 4 `26 migration → 31 migration` + 1 `41 bẫy → 49 bẫy`
|
||||
- Audit log file: `docs/changelog/skill-audit-2026-05-late.md`
|
||||
- KEEP narrative §6.5: contract-workflow `96→77 test` historical preserved
|
||||
|
||||
### Plan F1 — Qdrant Native Dashboard Fix (UAT catch by anh)
|
||||
|
||||
🟧 **Root cause:** Qdrant Windows binary zip không bundle Web UI static files. Log warn `Static content folder for Web UI './static' does not exist` + `http://localhost:6333/dashboard` returns 404. Em pioneer S26 chỉ download `qdrant-x86_64-pc-windows-msvc.zip` (28.3 MB binary) không biết Web UI cần download riêng.
|
||||
|
||||
🟧 **Fix:** Download `dist-qdrant.zip` v0.2.12 (6.59 MB, released 2026-05-21 — 0.3 ngày trước) từ qdrant-web-ui GitHub releases + extract vào `D:\.claude-rag\qdrant-bin\static\` + flatten `dist/` subfolder up + restart Qdrant → HTTP 200 "UI | Qdrant" ✓
|
||||
|
||||
🟧 **Custom Dashboard panel link "Qdrant Native Dashboard"** giờ work end-to-end.
|
||||
|
||||
### Plan F2 — Multi-agent Setup Pitfalls Fix (VIPIX guide catch)
|
||||
|
||||
🚨 **Critical discovery:** VIPIX project xuất `docs/guides/multi-agent-pitfalls.md` 2026-05-22 — anh share cho em audit SOLUTION_ERP setup. Em phát hiện:
|
||||
- 4 file `.claude/agents/*.md` dùng `model: claude-opus-4-7` (full ID = 200K fallback, KHÔNG 1M Opus)
|
||||
- 4 file dùng non-standard field `effort: max` → silent reject possible
|
||||
- → Registry chưa load cả session S27 (Agent error: "Agent type 'investigator' not found")
|
||||
|
||||
🟧 **Fix applied 4 file:** `model: inherit` (kế thừa 1M Opus parent) + remove `effort: max`. Pending CLI restart cho hot-reload (pitfall #1).
|
||||
|
||||
🟧 **Memory user-level NEW:** `feedback_subagent_setup_pitfalls.md` (235 lines) - cross-project pitfall checklist VIPIX + SOLUTION_ERP evidence. Integrated vào MEMORY.md index.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Anti-pattern phá vỡ S27 (retrospective analysis)
|
||||
|
||||
Em chủ trì kiêm **5 roles** cả session vì registry empty:
|
||||
|
||||
| Task S27 | Implementer ACCEPT fit? | Outcome |
|
||||
|---|---|---|
|
||||
| C1 Curate cicd-monitor 72KB | ❌ REFUSE #1 (judgment §6.5) | Em solo CORRECT |
|
||||
| C2-C4 Curate 3 agent MEMORY | ❌ REFUSE #1 | Em solo CORRECT |
|
||||
| C5 Audit drift §6.4 + §9.4 | ❌ REFUSE #1 | Em solo CORRECT |
|
||||
| **A3.1 Write 5 PS scripts** | ✅ **ACCEPT Case 2 (5 file cookie-cutter mirror)** | **Em miss delegate** |
|
||||
| A3.2 Dashboard HTML + generator | ❌ REFUSE #2/#7 (first time pattern) | Em solo CORRECT |
|
||||
| A4 Onboarding guide 440 lines | ❌ REFUSE #2 (docs judgment) | Em solo CORRECT |
|
||||
| F1 Qdrant Web UI fix | ❌ REFUSE #4 (bug reasoning chain) | Em solo CORRECT |
|
||||
| **F2 4 agent files fix** | ✅ **ACCEPT Case 1 (4 file mechanical same edit)** | **Em miss delegate** |
|
||||
|
||||
**Verdict:** 2/8 task lẽ ra delegate Implementer (Case 1+2) nhưng registry empty → em main forced solo. Net loss ~30 phút time + miss cookie-cutter mirror discipline.
|
||||
|
||||
**Reviewer Smart Friend guard miss critical:**
|
||||
- Em main S27 write rag-onboarding-guide.md claim "Qdrant Native Dashboard `http://localhost:6333/dashboard`" WITHOUT actual verify
|
||||
- Anh pqhuy UAT browser catch 404 → escalate
|
||||
- → Reviewer pre-commit spawn (nếu registry load) sẽ catch Cat 1 "Wire claim verify" — em main self-review compromised
|
||||
|
||||
---
|
||||
|
||||
## E2E verified
|
||||
|
||||
### Plan A.3 verify
|
||||
|
||||
| Item | Status | Notes |
|
||||
|---|---|---|
|
||||
| 5 PS scripts execute | ✅ | rag-status / rag-start / rag-stop tested live |
|
||||
| Custom Dashboard HTML | ✅ | 13.3 KB, 7 panels rendered, browser opened |
|
||||
| `$PROFILE` aliases | ✅ | 6 functions loaded via `. $PROFILE` |
|
||||
| Startup shortcut | ✅ | `rag-boot.lnk` 1378 bytes created |
|
||||
| ASCII-only PS source | ✅ | Em fix 3 file (stop/boot/dashboard) sau Unicode mangling issue |
|
||||
|
||||
### Plan F1 verify
|
||||
|
||||
| Item | Status |
|
||||
|---|---|
|
||||
| Qdrant native dashboard HTTP 200 | ✅ "UI | Qdrant" title |
|
||||
| Collections API live | ✅ proj_solution_erp returned |
|
||||
| static/ folder size | 16.07 MB (Web UI v0.2.12) |
|
||||
|
||||
### Plan F2 verify (partial)
|
||||
|
||||
| Item | Status |
|
||||
|---|---|
|
||||
| 4 file edit `model: inherit` | ✅ Applied |
|
||||
| 4 file remove `effort: max` | ✅ Applied |
|
||||
| Sub-agent spawn test | ❌ Pitfall #1 - need CLI restart |
|
||||
| Re-spawn post fix | ❌ Still "Agent type not found" |
|
||||
| Registry hot-reload | ❌ Pending anh restart Claude Code CLI |
|
||||
|
||||
### Memory curate verify
|
||||
|
||||
| Agent | Before | After | Status |
|
||||
|---|---:|---:|---|
|
||||
| cicd-monitor | 72.4 KB | 15.8 KB | ✅ -78% |
|
||||
| implementer | 38.8 KB | 22.0 KB | ✅ -43% |
|
||||
| investigator | 34.9 KB | 16.3 KB | ✅ -53% |
|
||||
| reviewer | 34.5 KB | 17.9 KB | ✅ -48% |
|
||||
| **Total** | **180.6 KB** | **72.0 KB** | **-60%** |
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Bug gặp + fix
|
||||
|
||||
| Bug | Fix |
|
||||
|---|---|
|
||||
| PowerShell 5.1 mangling Unicode `✓ → âœ"` trong .ps1 source | Replace ASCII-only `[OK]/[FAIL]/->/*/` trong PS code (HTML output unicode OK) |
|
||||
| `dashboard.ps1` parser fail với emoji 🧠🗄️🔌 trong here-string HTML | Rewrite ASCII-only PS source, dùng CSS-styled `icon-box` div thay emoji |
|
||||
| Qdrant native `localhost:6333/dashboard` 404 | Download `dist-qdrant.zip` v0.2.12 + extract `static/` + flatten + restart |
|
||||
| `start.ps1` health check timeout 30s fail false alarm | Adjust to 3s warmup + TimeoutSec 5 |
|
||||
| Qdrant crashed OOM "allocation 8.4MB failed" mid-session | rag-restart recovers (data persisted) |
|
||||
| 4 sub-agent `model: claude-opus-4-7` silent fallback 200K | Fix `model: inherit` per VIPIX pitfall #2 |
|
||||
| Sub-agent `effort: max` non-standard field silent reject | Remove field |
|
||||
| Re-bootstrap fail pydantic serialization error | Defer S28 — debug needed |
|
||||
|
||||
---
|
||||
|
||||
## 📚 Docs updates
|
||||
|
||||
| File | Update |
|
||||
|---|---|
|
||||
| `docs/STATUS.md` | Last updated S27 chốt cuối (Memory curate + RAG manual control + multi-agent fix) |
|
||||
| `docs/HANDOFF.md` | TL;DR S27 với pitfall lesson + Plan B Contract V2 Pending S28 |
|
||||
| `docs/changelog/sessions/2026-05-22-s27-memory-curate-rag-dashboard-multi-agent-fix.md` | File này — session log đầy đủ |
|
||||
| `docs/guides/rag-onboarding-guide.md` | NEW 26.3 KB / 440 lines / 13 sections + §A2 cấu trúc chuẩn |
|
||||
| `docs/changelog/skill-audit-2026-05-late.md` | NEW audit log drift trigger sớm (~100 lines) |
|
||||
| `.claude/agents/*.md` × 4 | Fix `model: inherit` + remove `effort: max` |
|
||||
| `.claude/agent-memory/*/MEMORY.md` × 4 | Curate (-60%) + S27 entry proxy flush |
|
||||
| `.claude/agent-memory/*/archive/2026-05-*.md` × 4 | NEW archive files preserve verbose Q1 entries |
|
||||
| `.claude/skills/README.md` | `26 migration → 31` + `44 bẫy → 49` |
|
||||
| `.claude/skills/ef-core-migration/SKILL.md` | 4 patch count drift |
|
||||
| `.claude/skills/dependency-audit-erp/SKILL.md` | `41 bẫy → 49 bẫy` |
|
||||
| Memory user-level `feedback_subagent_setup_pitfalls.md` | NEW 235 lines cross-project pitfall checklist |
|
||||
| Memory user-level `feedback_rag_hybrid_pattern.md` | +1 bài học #8 (Qdrant Web UI static missing fix) |
|
||||
| Memory user-level `MEMORY.md` index | +1 entry feedback_subagent_setup_pitfalls |
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Handoff S28+
|
||||
|
||||
### Pending priority HIGH
|
||||
|
||||
1. **Anh restart Claude Code CLI** → verify 4 sub-agent load post `model: inherit` fix. Spawn test Investigator IMMEDIATELY mỗi session start (per `feedback_subagent_setup_pitfalls.md` §4).
|
||||
2. **Plan B Contract V2 wire** (carry từ S25/S26) — kick off với 4 sub-agent ACTIVE: Investigator pre-flight + Implementer Case 2 mirror PE Mig 22-23 + Reviewer pre-commit + CICD Monitor post-push.
|
||||
3. **Re-bootstrap RAG** SOLUTION_ERP để index S27 changes (rag-onboarding-guide.md + skill-audit-late + 4 MEMORY updates + feedback_subagent_setup_pitfalls). Bootstrap fail pydantic — debug + retry S28.
|
||||
|
||||
### Pending priority MEDIUM
|
||||
|
||||
4. **Audit S20-S26 memory log "Investigator spawn" claims** — verify history retroactive (có thật spawn hay nhầm general-purpose default?). Defer dedicated investigation S28+.
|
||||
5. **Plan AI Phase 5** distributed bootstrap 4 project khác (NamGroup/DH/Ashico/Vipix) — em main project đó tự làm khi anh mở Claude Code project (Approach B distributed).
|
||||
6. **Test debt catch-up Plan C bundle** (S22+1 + S25 + S26 bug fix chưa add regression — UAT mode defer per §7).
|
||||
|
||||
### Pending priority LOW
|
||||
|
||||
7. Benchmark RAG recall@10 golden dataset 100 query (gap optional)
|
||||
8. Disaster recovery weekly backup Qdrant data → Dropbox (gap optional)
|
||||
9. Gotcha #48 SQLite tie-break + #49 dual-phase UI confusion add `docs/gotchas.md` (carry từ S25)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Thông số cumulative S27
|
||||
|
||||
| Metric | S26 chốt | S27 chốt | Δ |
|
||||
|---|---|---|---|
|
||||
| DB tables | 59 | 59 | 0 |
|
||||
| Migrations | 31 | 31 | 0 |
|
||||
| Endpoints | ~146 | ~146 | 0 |
|
||||
| FE pages | 35 | 35 | 0 |
|
||||
| Unit tests | 111 | 111 | 0 (UAT mode defer per §7) |
|
||||
| Gotchas | 49 | 49 | 0 (gotcha #48, #49 still pending docs add) |
|
||||
| Memory user-level | 23 | **24** | **+1 (`feedback_subagent_setup_pitfalls.md` NEW)** |
|
||||
| Skills project-local | 6 | 6 | 0 |
|
||||
| Sub-agents | 4 (broken registry) | 4 (fixed, pending CLI restart) | 0 count, +1 fix |
|
||||
| Docs files | — | **+2** | `rag-onboarding-guide.md` + `skill-audit-2026-05-late.md` |
|
||||
| PS Scripts infra | 0 | **+5** | `D:\.claude-rag\scripts\*.ps1` |
|
||||
| Custom Dashboard | 0 | **+1** | `dashboard.html` auto-gen |
|
||||
| Agent MEMORY total | 180.6 KB | 72.0 KB | **-60%** (115 KB archived) |
|
||||
| Commits remote | `e23f51c..d99069a` | unchanged | **0 push S27** (all local + memory + docs - anh chốt push thủ công) |
|
||||
|
||||
### Multi-agent ROI S27
|
||||
|
||||
| Agent | Spawn | Actual outcome |
|
||||
|---|---|---|
|
||||
| 🟦 Investigator | 0 (registry empty) | Em main solo audit + curate |
|
||||
| 🟨 Implementer | 0 (registry empty) | Em main solo 5 PS scripts + 4 file fix (lẽ ra delegate Case 1+2) |
|
||||
| 🟥 Reviewer | 0 (registry empty) | Em main self-review compromised (miss Qdrant 404) |
|
||||
| 🟩 CICD Monitor | 0 (no remote push) | N/A |
|
||||
| 👤 Em main solo | continuous | ~5h cả 8 task + meta-discovery pitfall |
|
||||
|
||||
**Net learning S27:** Pitfall discovery + fix infrastructure → S28+ multi-agent CÓ THỂ work properly sau CLI restart. Anti-pattern em main solo = forced không phải choice.
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Patterns reusable cross-project (S27 NEW)
|
||||
|
||||
1. **Multi-agent setup pitfall checklist** - 4 pitfall VIPIX + SOLUTION_ERP evidence (`feedback_subagent_setup_pitfalls.md`)
|
||||
2. **PS scripts ASCII-only discipline** - HTML output unicode OK, PS source phải ASCII (CSS-styled badges + icon-box thay emoji)
|
||||
3. **Qdrant Windows binary 2-step setup** - binary + Web UI static download separate (gotcha #8 `feedback_rag_hybrid_pattern.md`)
|
||||
4. **Custom Dashboard PS generator pattern** - here-string HTML template + collect data via Invoke-RestMethod + Out-File UTF-8 + Start-Process browser
|
||||
5. **Memory curate proxy pattern khi registry empty** - em main update sub-agent MEMORY trực tiếp với retrospective analysis (REFUSE log validation + ACCEPT miss flag)
|
||||
6. **Audit log file separate khi drift sớm** - `skill-audit-YYYY-MM-late.md` thay vì rewrite existing audit log (preserve historical trail per §6.5)
|
||||
7. **Dashboard SNAPSHOT vs LIVE distinction** - static HTML generated by PS = snapshot tại 1 thời điểm, browser meta refresh KHÔNG re-run PS. Anti-pattern em pioneer commit: meta refresh 60s falsely impression live. Fix: add prominent timestamp + warning banner + link to Qdrant native dashboard (LIVE API fetch). Pattern reusable cho bất kỳ custom dashboard PowerShell.
|
||||
8. **NSSM Windows Service Option 4b upgrade pattern** - Qdrant binary natively no `--service` flag → wrap với NSSM (3 MB binary download from nssm.cc release/2.24, retry 503 transient). install-service.ps1 + fix-service-start.ps1 elevated scripts ready. Auto-start boot-time + auto-restart on crash + survive logout. Recipe transferable cho bất kỳ database/server binary cần Windows Service mode mà không có native support.
|
||||
9. **Hybrid context loading discipline (Cách A defensive)** - Layer 1 blanket auto-load ~120K (CLAUDE+STATUS+HANDOFF+MEMORY index+skills+sub-agents) + Layer 2 RAG retrieve on-demand via 6 MCP tools. Decision gate per project MD size: < 200K skip RAG / 200K-1M lazy / > 1M MANDATORY. Token budget zones 5-tier (green/warning/approach/critical). 7 anti-patterns avoid (Read full session log cũ, search vague, em main solo qualify Implementer Case 1/2, skip store_memory, heavy session > 6h). Onboarding §A3 NEW comprehensive.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Plan A.3+ Upgrade Post-Wrap — Option 4b NSSM Windows Service
|
||||
|
||||
> **Trigger:** Anh phản biện "Qdrant nên auto-start như database server thường (PostgreSQL/SQL Server đều Windows Service auto-start)" → em upgrade Option 4a (manual scripts S26 chốt) lên **Option 4b NSSM Windows Service**.
|
||||
> **Done:** Post-initial wrap-up cùng session S27 — anh chạy 2 elevated PS scripts → service Running successfully.
|
||||
|
||||
### NSSM install + service registration
|
||||
|
||||
🟧 **Download NSSM 2.24** ~351 KB từ `https://nssm.cc/release/nssm-2.24.zip` (retry 1× sau 503 transient) → extract `D:\.claude-rag\nssm\nssm.exe` (323 KB win64 binary)
|
||||
|
||||
🟧 **install-service.ps1** (5.4 KB elevated script):
|
||||
- Verify Admin privileges
|
||||
- Remove old service nếu exist (idempotent)
|
||||
- `nssm install Qdrant qdrant.exe` + AppDirectory `D:\.claude-rag\qdrant-bin`
|
||||
- Log paths `logs/qdrant-service.log` + `.err` với rotation 10 MB
|
||||
- `Start: SERVICE_AUTO_START` (boot-time auto-start trước login)
|
||||
- `AppExit Default Restart` + `AppRestartDelay 3000` (auto-respawn 3s sau crash)
|
||||
- DisplayName "Qdrant Vector DB (RAG Unified)" + Description friendly
|
||||
- Start service + health verify HTTP `localhost:6333/healthz`
|
||||
|
||||
### Bug gặp: WAL lock conflict
|
||||
|
||||
🟧 **Symptom:** Step [5/6] Start failed — service Paused state, log `Can't init WAL: Kind(WouldBlock)`.
|
||||
|
||||
🟧 **Root cause:** Em start Qdrant manual PID 9800 ngay trước install-service.ps1 → manual process held Write-Ahead Log file lock → service không init được WAL → fail start + Paused state.
|
||||
|
||||
🟧 **fix-service-start.ps1** (2.4 KB elevated script) — recovery:
|
||||
- Stop-Service -Force (kill Paused state)
|
||||
- Kill any remaining qdrant.exe (defensive cho orphan PID)
|
||||
- Wait 3s
|
||||
- Start-Service Qdrant
|
||||
- Verify HTTP + process PID + RAM
|
||||
|
||||
🟧 **Result confirmed:** Service Running PID 4476 RAM 101.8 MB. Auto-start ENABLED ✓
|
||||
|
||||
### 4 PS scripts updated to Service mode
|
||||
|
||||
🟧 **start.ps1** → `Start-Service Qdrant` (cần Admin). Detect already Running + skip + show service info.
|
||||
|
||||
🟧 **stop.ps1** → `Stop-Service Qdrant -Force` (cần Admin). Defensive kill orphan qdrant.exe nếu detected.
|
||||
|
||||
🟧 **status.ps1** → `Get-Service Qdrant` (no Admin) thay process check + Section 1 expanded với service info (Status, StartType, DisplayName) + Process info defensive guard `try/catch` cho StartTime null khi spawn from service.
|
||||
|
||||
🟧 **boot.ps1** → drop Qdrant start (service auto-start) + verify service Running + regenerate Dashboard + open browser. Used by Startup folder shortcut `rag-boot.lnk`.
|
||||
|
||||
### Dashboard SNAPSHOT vs LIVE clarification
|
||||
|
||||
🟧 **Bug discovered:** Custom Dashboard `dashboard.html` show "Running" badge stale 10+ phút sau Qdrant DOWN. Root cause: `<meta http-equiv="refresh" content="60">` chỉ reload HTML cached, KHÔNG re-run PS script.
|
||||
|
||||
🟧 **Fix applied:** Remove meta refresh + add prominent yellow banner top:
|
||||
```html
|
||||
⚠ Dashboard này là STATIC SNAPSHOT tại thời điểm generated (xem timestamp).
|
||||
Browser auto-refresh chỉ reload HTML cached, KHÔNG poll Qdrant API live.
|
||||
Muốn data live → mở Qdrant Native Dashboard (fetch API real-time).
|
||||
```
|
||||
|
||||
🟧 **Header timestamp** + label "SNAPSHOT (not live)" red color visible.
|
||||
|
||||
🟧 **Service status panel** added Get-Service info: Service (Running) / Auto-start (Automatic) / DisplayName.
|
||||
|
||||
### Onboarding guide §A3 NEW comprehensive
|
||||
|
||||
🟧 **Section §A3 Context loading Hybrid pattern** (~242 lines added) — 8 sub-sections:
|
||||
- §A3.1 Why Hybrid Cách A vs Cách B vs Skip RAG (decision gate)
|
||||
- §A3.2 Layer 1 Blanket auto-load checklist (~200-280 KB ≈ 50-70K tokens)
|
||||
- §A3.3 Layer 2 RAG retrieve decision tree (7-branch)
|
||||
- §A3.4 Token budget guidance 1M Opus (5 utilization zones)
|
||||
- §A3.5 6 MCP tools examples concrete (Vietnamese + English queries)
|
||||
- §A3.6 Best practices em main daily workflow (morning + in-session + EOS + monthly)
|
||||
- §A3.7 7 Anti-patterns cross-project (distilled VIPIX + SOLUTION_ERP)
|
||||
- §A3.8 Context monitoring + when to end session (heuristics + protocol)
|
||||
|
||||
### Memory user-level updates
|
||||
|
||||
🟧 **`feedback_rag_distributed_ownership.md`** Decision 2 upgraded Option 4a → 4b NSSM với gotcha S27 install (nssm.cc 503 transient + WAL lock conflict + Process.StartTime null guard).
|
||||
|
||||
### Final state Service mode
|
||||
|
||||
| | State |
|
||||
|---|---|
|
||||
| Qdrant Service | Running (Automatic) ✓ |
|
||||
| HTTP /healthz | OK ✓ |
|
||||
| Collection proj_solution_erp | 3460 chunks (⚠ indexed_vectors=0 HNSW broken — pending re-bootstrap S28) |
|
||||
| Auto-start on Windows boot | ENABLED ✓ |
|
||||
| Auto-restart on crash | ENABLED 3s delay ✓ |
|
||||
| 7 PS scripts total | start/stop/status/dashboard/boot/install-service/fix-service-start |
|
||||
| Onboarding guide | 42.5 KB / 682 lines / 14 sections + §A2 + §A3 |
|
||||
@ -0,0 +1,159 @@
|
||||
# Session 29 — 2026-05-22 — Plan CA + Plan B Contract V2 wire end-to-end
|
||||
|
||||
> **TL;DR:** 20 commits cumulative S29 push 4 CI Runs PASS deploy production. Plan CA (Move "Cấu hình danh mục" admin → eoffice) + Plan B Contract V2 wire (mirror PE Mig 22-26). Smart Friend Reviewer + CICD Monitor cumulative 4× catches MAJOR/CRITICAL bugs pre/post deploy. 8 patterns reusable NEW.
|
||||
|
||||
## 🎯 Session goals (anh chốt 2026-05-22 startup S29)
|
||||
1. ✅ Re-bootstrap RAG SOLUTION_ERP S27+S28 NEW content (60.9s, 2,794 chunks)
|
||||
2. ✅ **Plan CA** — Move "Cấu hình danh mục dùng chung" (9 menu Master + Catalogs) từ fe-admin → fe-user/eoffice + role mới `CatalogManager`
|
||||
3. ✅ **Plan B** — Contract V2 wire mirror PE Mig 22-26 (COEXIST V1+V2)
|
||||
4. ✅ Add MCP RAG tools cho 4 sub-agent definitions (pending CLI restart S30)
|
||||
5. ✅ End-to-end demo cross-project RAG search (NAMGROUP HRM 10 info samples)
|
||||
|
||||
## 📦 Commits cumulative S29 — 20 commits push `3cb54e0..38f1c4d`
|
||||
|
||||
### Plan CA — 7 commits
|
||||
| # | SHA | Chunk | Owner |
|
||||
|---|---|---|---|
|
||||
| 1 | `06a441c` | B FE move 4 master pages (948 LOC byte-identical) | 🟨 Implementer |
|
||||
| 2 | `80d39a0` | A BE Role CatalogManager + Seed permissions | 👤 Em main |
|
||||
| 3 | `c995f42` | C Sidebar filter 2 app | 👤 Em main |
|
||||
| 4 | `4a592cf` | D Seed demo user catalog.manager | 👤 Em main |
|
||||
| 5 | `68bcedd` | D2 Hotfix password ≥12 chars S22+2 policy (Reviewer catch) | 👤 Em main |
|
||||
| 6 | `e55d96b` | **Hotfix 1** resolvePath staticMap silent sidebar drop (anh UAT catch) | 👤 Em main |
|
||||
| 7 | `6eec8d7` | Docs wrap (gotcha #50 + Pattern 16-bis + STATUS) | 👤 Em main |
|
||||
|
||||
### MCP RAG add — 1 commit
|
||||
| # | SHA | Description |
|
||||
|---|---|---|
|
||||
| 8 | `b51fc94` | Add `mcp__rag-unified__search_memory + cross_project_search` cho 4 agent definitions (pending CLI restart hot-reload S30+) |
|
||||
|
||||
### Plan B Contract V2 wire — 11 commits + 1 docs wrap
|
||||
| # | SHA | Chunk | Owner |
|
||||
|---|---|---|---|
|
||||
| 9 | `58898e8` | A1 Entity Contract +2 V2 fields | 👤 Em main |
|
||||
| 10 | `a85e437` | A2 Mig 32 + Configuration + Seed sample (4,094 LOC EF auto-gen) | 🟨 Implementer |
|
||||
| 11 | `138469d` | B Service ApproveV2Async branch + gen mã HĐ adapt | 👤 Em main |
|
||||
| 12 | `26c98d3` | C Mig 33 ContractLevelOpinions cookie-cutter (4,265 LOC) | 🟨 Implementer |
|
||||
| 13 | `1f199b0` | B2 UPSERT block + ResolveActorFullName helper | 👤 Em main |
|
||||
| 14 | `ef23308` | E1 CreateContractCommand +ApprovalWorkflowId V2 | 👤 Em main |
|
||||
| 15 | `62b50d1` | D FE Workspace V2 Select dropdown × 2 app | 🟨 Implementer |
|
||||
| 16 | `48f6d22` | E2 ContractDetailDto + populate LevelOpinions[] | 👤 Em main |
|
||||
| 17 | `14feb69` | E3 FE Section 5 LevelOpinionsV2 × 2 app (em main solo, Implementer stopped mid-task) | 👤 Em main |
|
||||
| 18 | `3e92584` | **Hotfix Reviewer** ApplicableType=Contract validation guard (Reviewer MAJOR catch) | 👤 Em main |
|
||||
| 19 | `38f1c4d` | **Hotfix CICD** SeedSampleContractWorkflowV2 OUT of DemoSeed gate (CICD CRITICAL catch — gotcha #51 NEW) | 👤 Em main |
|
||||
| 20 | (this session log) | Docs wrap S29 + session log + flush 4 MEMORY | 👤 Em main |
|
||||
|
||||
## 🎯 Multi-agent ROI explosive S29
|
||||
|
||||
| Agent | Spawns | Tokens | Major catches |
|
||||
|---|---:|---:|---|
|
||||
| 🟦 **Investigator** | 2 | ~40K | Plan CA terrain map 9 menu + GOTCHA tree-inherit; Plan B audit Contract V1 + recommend 6→9 chunk re-split + 3 surprise (zero ApplicableType=3 prod, RejectedAtStepIndex drift, ContractType variants generic) |
|
||||
| 🟨 **Implementer Case 2** | 5 | ~82K | Plan CA Chunk B 4 master pages mirror byte-identical; Plan B A2 Mig 32 + C Mig 33 + D FE Workspace V2 cookie-cutter; **E3 stopped mid-task** (complex FE judgment, em main solo finish) |
|
||||
| 🟥 **Reviewer** | 4 | ~355K | **MAJOR Plan CA Hotfix D2:** Password ≥12 chars policy S22+2 catch BEFORE prod 401; **MAJOR Plan B Hotfix:** ApplicableType=Contract validation guard catch BEFORE security gap exploit |
|
||||
| 🟩 **CICD Monitor** | 3 | ~90K | 2 fail 529 Anthropic transient → em main fallback manual smoke; **1 CRITICAL Plan B Hotfix:** SeedSampleContractWorkflowV2 gated by DemoSeed → V2 path BLOCKED prod → gotcha #51 NEW |
|
||||
| 👤 **Em main Solo** | — | ~150K | Coordinate 4 agents + Chunk B/B2 cross-stack reasoning + E3 finish + 3 hotfix re-edit + 2 docs wrap |
|
||||
| **TOTAL** | 14 spawn | ~715K | 4× Smart Friend cumulative wins |
|
||||
|
||||
## 🛡️ Smart Friend pattern proven 4× cumulative
|
||||
|
||||
| # | Session | Catch | Severity | Owner |
|
||||
|---|---|---|---|---|
|
||||
| 1 | S22 | Class-level `[Authorize(Policy)]` silent 403 (gotcha #44) | MAJOR | 🟥 Reviewer |
|
||||
| 2 | S25 | Multi-Changelog SQLite tie-break test discriminator (gotcha #48) | MAJOR | 🟩 CICD Monitor |
|
||||
| 3 | **S29** | Password ≥12 chars policy + ApplicableType=Contract validation | MAJOR | 🟥 Reviewer |
|
||||
| 4 | **S29** | INFRASTRUCTURE vs DEMO seed gate confusion (gotcha #51) | CRITICAL | 🟩 CICD Monitor |
|
||||
|
||||
## 🆕 Patterns reusable NEW saved S29 (8 patterns)
|
||||
|
||||
1. **9-menu permission terrain map pattern** (Investigator) — inventory file paths + LOC + component parity check trước delegate chunk
|
||||
2. **V1+V2 coexist boundary** (Investigator) — KHÔNG drop V1 nếu prod data pinned. Plan F precedent S22 (ABORT khi định drop V1)
|
||||
3. **Reference template paths cross-module mirror** (Investigator) — cite EXACT line ranges PE → Contract V2 (Mig 23:14-31, Mig 24:14-17, ApproveV2Async 446-634, UPSERT 519-546, ResolveActor 774-783) → saving 30%+ time
|
||||
4. **Pattern 12-bis cross-module entity cookie-cutter mirror** (Implementer) — entity + Mig + Config + DbSet 4-file mirror cho cross-module clone scenarios
|
||||
5. **Pattern 16-bis 4-place mirror cross-app** (Implementer) — reinforced 2× Plan CA + Plan B Workspace
|
||||
6. **Cross-module security validation mirror Cat 3** (Reviewer) — khi mirror entity/command cross-module, MUST mirror validation guards (ApplicableType + FK + idempotent). Easy miss
|
||||
7. **INFRASTRUCTURE vs DEMO seed classification** (CICD #51) — decision tree: production cần để work end-to-end? YES → INFRASTRUCTURE ungate
|
||||
8. **Race condition em main + Implementer parallel BE → stash workaround** (Implementer Plan B A2+B) — Implementer auto-stash em main WIP cho clean build. Forward: SEQUENTIAL chunks A→B→C khi cùng touch BE, NOT parallel
|
||||
|
||||
## 📊 State chốt S29
|
||||
|
||||
| Metric | Before S29 | After S29 | Δ |
|
||||
|---|---:|---:|---|
|
||||
| Migrations | 31 | **33** | +2 (Mig 32 Contract V2 + Mig 33 LevelOpinions) |
|
||||
| DB tables | 59 | **60** | +1 (ContractLevelOpinions) |
|
||||
| API endpoints | ~146 | **~148** | +1 (V2 contract create) |
|
||||
| FE pages | 35 | **38** | +3 (4 master moved to fe-user — net +3 sau remove fe-admin) |
|
||||
| Tests | 111 | **111** | unchanged (UAT mode skip; V2 logic NO test cover defer) |
|
||||
| Gotchas | 49 | **51** | +2 (#50 staticMap silent drop + #51 INFRASTRUCTURE vs DEMO seed) |
|
||||
| Memory user-level | 25 | **25** | unchanged |
|
||||
| Skills | 6 | **6** | unchanged |
|
||||
| Sub-agents | 4 | **4** | unchanged (MCP RAG added pending CLI restart) |
|
||||
| AppRoles | 13 | **14** | +1 (CatalogManager) |
|
||||
| Active prod users | 33 | **34** | +1 (catalog.manager@solutions.com.vn) |
|
||||
| V1 contracts prod | 7 | **7** | preserved (no V2 contract yet) |
|
||||
| RAG chunks SOLUTION_ERP | 3,462 | **2,794** | -668 (re-bootstrap clean indexing, dedup improvement) |
|
||||
| Bundle hash rotate | — | **4×** | fe-admin: `BvcWrq2z→leEMWFLU→BBADl46y`, fe-user: `Bg2FNeIz→DVBLmZlt→Dgn1iU9E→DA_VI3zO` |
|
||||
|
||||
## 🚀 NEW capability prod end-to-end
|
||||
|
||||
**1. Catalog management user role:**
|
||||
- Login `catalog.manager@solutions.com.vn / CatalogMgr@2026`
|
||||
- fe-user sidebar: Master + 4 leaf (Suppliers + Projects + Departments) + Catalogs root + 4 sub (Units/Materials/Services/WorkItems)
|
||||
- Full CRUD 9 menu, KHÔNG access fe-admin tools
|
||||
|
||||
**2. Contract V2 workflow path:**
|
||||
- Login Drafter (vd `qs.hoang@solutions.com.vn`)
|
||||
- `/contracts/new?type=1` → Workspace dropdown "Quy trình duyệt V2" có `QT-HD-V2-001`
|
||||
- Pick V2 + create → contract pin `ApprovalWorkflowId`
|
||||
- Submit ChoDuyet → workflow advance Step 1 Cấp 1
|
||||
- Login `binh.le@solutions.com.vn` (CCM approver) → Approve
|
||||
- Service `ApproveV2Async` UPSERT opinion + advance → terminal Phase=DaPhatHanh + gen mã HĐ RG-001
|
||||
- Detail page Section 5 LevelOpinionsV2 render dynamic với opinion data
|
||||
|
||||
## ⚠️ Pending S30+ follow-up
|
||||
|
||||
1. **Anh restart Claude Code CLI** để 4 sub-agents pick up MCP RAG tools (commit `b51fc94`)
|
||||
2. **Anh UAT verify V2 contract end-to-end** flow (Drafter → CCM approve → DaPhatHanh)
|
||||
3. **Test bundle Plan B**: regression test ApproveV2Async (~150 LOC) + ApplicableType validation guard (xUnit Domain policy + Infra service test)
|
||||
4. **Curate dedicated session 4 MEMORY** (Implementer 35.4KB > hard threshold)
|
||||
5. **Anh UAT verify catalog manager** end-to-end (login + CRUD 9 menu)
|
||||
|
||||
## 📝 Files touched S29
|
||||
|
||||
### BE (~715 LOC actual + ~7,970 EF Designer = ~8,685)
|
||||
- `src/Backend/SolutionErp.Domain/Identity/AppRoles.cs` (+6 CatalogManager)
|
||||
- `src/Backend/SolutionErp.Domain/Contracts/Contract.cs` (+12 V2 fields + LevelOpinions nav)
|
||||
- `src/Backend/SolutionErp.Domain/Contracts/ContractLevelOpinion.cs` (NEW 36)
|
||||
- `src/Backend/SolutionErp.Application/Contracts/Services/IContractWorkflowService.cs` (+10 skipToFinal)
|
||||
- `src/Backend/SolutionErp.Application/Contracts/ContractFeatures.cs` (+96 V2 + Hotfix Reviewer)
|
||||
- `src/Backend/SolutionErp.Application/Contracts/Dtos/ContractDtos.cs` (+28 V2 DTO + LevelOpinion)
|
||||
- `src/Backend/SolutionErp.Application/Common/Interfaces/IApplicationDbContext.cs` (+3 ContractLevelOpinions DbSet)
|
||||
- `src/Backend/SolutionErp.Infrastructure/Persistence/ApplicationDbContext.cs` (+2 DbSet)
|
||||
- `src/Backend/SolutionErp.Infrastructure/Persistence/Configurations/ContractConfiguration.cs` (+15 FK + Index)
|
||||
- `src/Backend/SolutionErp.Infrastructure/Persistence/Configurations/ContractLevelOpinionConfiguration.cs` (NEW 37)
|
||||
- `src/Backend/SolutionErp.Infrastructure/Persistence/DbInitializer.cs` (+~120 CatalogManager seed + SampleContractWorkflowV2 + ungate Hotfix CICD)
|
||||
- `src/Backend/SolutionErp.Infrastructure/Services/ContractWorkflowService.cs` (+200 V2 branch + ApproveV2Async + UPSERT + ResolveActor)
|
||||
- `src/Backend/SolutionErp.Infrastructure/Persistence/Migrations/20260522051059_AddApprovalWorkflowToContract.cs` (NEW Mig 32)
|
||||
- `src/Backend/SolutionErp.Infrastructure/Persistence/Migrations/20260522052240_AddContractLevelOpinions.cs` (NEW Mig 33)
|
||||
|
||||
### FE (~1,050 LOC × 2 app sometimes byte-identical)
|
||||
- `fe-user/src/pages/master/{Suppliers,Projects,Departments,Catalogs}Page.tsx` (NEW 948 byte-identical mirror admin)
|
||||
- `fe-user/src/lib/menuKeys.ts` (+5 Catalogs sub-keys)
|
||||
- `fe-user/src/App.tsx` (+5 master routes)
|
||||
- `fe-admin/src/components/Layout.tsx` (+ADMIN_HIDDEN_MASTER_KEYS 9 keys hide)
|
||||
- `fe-user/src/components/Layout.tsx` (-4 USER_HIDDEN_KEYS + 7 resolvePath staticMap Hotfix 1)
|
||||
- `fe-admin/src/pages/contracts/ContractCreatePage.tsx` (+44 V2 Workspace dropdown)
|
||||
- `fe-user/src/pages/contracts/ContractCreatePage.tsx` (+44 V2 Workspace mirror)
|
||||
- `fe-admin/src/types/contracts.ts` (+22 V2 fields + ContractLevelOpinion)
|
||||
- `fe-user/src/types/contracts.ts` (+22 V2 fields mirror)
|
||||
- `fe-admin/src/components/contracts/ContractDetailContent.tsx` (+40 Section 5 V2)
|
||||
- `fe-user/src/components/contracts/ContractDetailContent.tsx` (+40 Section 5 V2 mirror)
|
||||
|
||||
### Docs + scripts + agent setup
|
||||
- `docs/STATUS.md` (S29 wrap header)
|
||||
- `docs/HANDOFF.md` (S29 wrap header)
|
||||
- `docs/gotchas.md` (+gotcha #50 staticMap + #51 INFRASTRUCTURE vs DEMO seed)
|
||||
- `docs/changelog/sessions/2026-05-22-s29-plan-ca-plan-b-contract-v2-wire.md` (NEW this session log)
|
||||
- `.claude/agents/{investigator,implementer,reviewer,cicd-monitor}.md` (+MCP RAG tools)
|
||||
- `.claude/agent-memory/{investigator,implementer,reviewer,cicd-monitor}/MEMORY.md` (S29 wrap entry FIFO each agent perspective)
|
||||
- `.claude/agent-memory/implementer/pattern_master_page_mirror.md` (NEW Pattern 16-bis cross-app from Plan CA Chunk B)
|
||||
- `scripts/plan-ca-verify-menu.{sql,ps1}` + `plan-ca-verify-perms.{sql,ps1}` + `plan-ca-run-perms.ps1` + `plan-b-verify-prod.{sql,ps1}` + `plan-b-run-verify.ps1` (NEW verify scripts)
|
||||
116
docs/changelog/skill-audit-2026-05-late.md
Normal file
116
docs/changelog/skill-audit-2026-05-late.md
Normal file
@ -0,0 +1,116 @@
|
||||
# Skill + Doc Audit — 2026-05 (late) — Drift trigger sớm
|
||||
|
||||
> **Cadence chính:** Cron `solution-erp-skill-audit-monthly` 9:00 ngày 1 mỗi tháng. **Next scheduled:** 2026-06-01.
|
||||
> **Lần này:** chạy SỚM 2026-05-22 trigger bởi drift threshold §9.4 "+5 gotcha mới → audit cluster" (actual +8: 41→49 từ baseline 2026-05-04).
|
||||
> **Workflow:** combined audit theo `docs/rules.md §6.4` (doc drift) + `§9.4` (skill staleness).
|
||||
> **Origin:** em main flagged drift trong session 27 start setup; bro confirm OK proceed curate + audit cùng session.
|
||||
|
||||
## Phase 0 — Trigger context
|
||||
|
||||
| Metric | 2026-05-04 baseline | 2026-05-22 actual | Δ | Threshold trigger? |
|
||||
|---|---:|---:|---:|---|
|
||||
| Migrations | 16 | 31 | +15 | YES — > +5 (major schema) |
|
||||
| Tests | 83 | 111 | +28 | YES — > +5 |
|
||||
| Gotchas | 41 | 49 | **+8** | **YES — §9.4 "+5 gotcha mới"** |
|
||||
| Skills | 6 | 6 | 0 | — |
|
||||
| Memory user-level | 14 | 23 | +9 | — |
|
||||
| DB tables | 55 | 59 | +4 | — |
|
||||
| Active prod users | 18 | 33 | +15 | — (data not skill drift) |
|
||||
|
||||
**Decision:** Trigger audit SỚM thay vì đợi 2026-06-01 — drift cluster vượt 30% threshold §9.4.
|
||||
|
||||
## Phase 1 — Skill staleness patches applied
|
||||
|
||||
5 patches (Edit, KHÔNG rewrite) per rule §6.4 + §6.5:
|
||||
|
||||
| File:line | Stale → Patched | Reason |
|
||||
|---|---|---|
|
||||
| `.claude/skills/README.md:20` | `26 migration history` → `31 migration history (Init → RefactorSkipToFinalToApproverLevel)` + Session 23 t1 marker | Mig drift 26→31 |
|
||||
| `.claude/skills/README.md:90` | `44 bẫy` → `49 bẫy (S25 +#48 SQLite tie-break, #49 dual-phase UI confusion)` | Gotcha drift 44→49 |
|
||||
| `.claude/skills/ef-core-migration/SKILL.md:3` (description) | `26 migration sẵn (Init → AddPeLevelOpinionsForV2)` → `31 migration sẵn (Init → RefactorSkipToFinalToApproverLevel Mig 31 S23 t1 F2 per-Approver-slot swap)` | Description drift + frontmatter description trigger semantic match |
|
||||
| `.claude/skills/ef-core-migration/SKILL.md:19` (heading) | `## Migration history (26 migration hiện có)` → `(31 migration hiện có)` | Section heading drift |
|
||||
| `.claude/skills/ef-core-migration/SKILL.md:80` (Tests note) | `Total 77 test pass / ~3s` → `Total 111 test pass / ~5s` + cumulative S22-S25 regression breakdown | Test count drift 77→111 (+34) |
|
||||
| `.claude/skills/ef-core-migration/SKILL.md:258` | `DbSet cho 59 bảng (26 migration)` → `(31 migration)` | Code pointer drift |
|
||||
| `.claude/skills/dependency-audit-erp/SKILL.md:153` | `41 bẫy` → `49 bẫy` + add #48 + #49 cross-ref | Gotcha drift 41→49 |
|
||||
|
||||
**Total diff:** ~12 LOC patched. KHÔNG rewrite toàn bộ. KHÔNG cắt narrative gốc.
|
||||
|
||||
## Phase 2 — KEEP (rule §6.5 không cắt narrative)
|
||||
|
||||
Stale references PRESERVED vì là historical context:
|
||||
|
||||
- `contract-workflow/SKILL.md:367` `96→77 test pass (drop 19 N-stage/2-stage legacy)` — historical narrative Mig 21 drastic refactor. KEEP per §6.5 (kể chuyện cumulative).
|
||||
- `permission-matrix/SKILL.md:16` `Status (post Session 6 — 2026-04-30)` — section header timestamp historical, KHÔNG drift critical.
|
||||
- `migration-todos.md` mentions `77 test` / `16 mig` — historical session record. KEEP per §6.5.
|
||||
- `skill-audit-2026-05.md` — historical audit record. KEEP unchanged.
|
||||
- Session logs `changelog/sessions/*.md` — ALL preserved chronologically. KEEP.
|
||||
|
||||
## Phase 3 — Feature gap audit
|
||||
|
||||
**Feature mới S20-S26 nào chưa có skill cover?**
|
||||
|
||||
| Feature | Period | Skill cover? | Decision |
|
||||
|---|---|---|---|
|
||||
| ApprovalWorkflow V2 schema (Mig 22-25) | S17-S18 | Cross-ref `contract-workflow` + `ef-core-migration` Mig history | Existing skills cover, KHÔNG tạo skill mới |
|
||||
| Per-NV admin opt-in flag pattern (Mig 29-31) | S21-S23 | Memory `feedback_per_nv_permission_scope.md` (user-level) | Pattern reusable cross-project — memory user-level sufficient (admin role + Mig schema discriminator), KHÔNG skill project-local |
|
||||
| Multi-agent setup 4 sub-agents | S20-S21 | Memory `feedback_multi_agent_setup.md` + `.claude/agents/README.md` | Em main coordination guide — KHÔNG skill (setup-once pattern) |
|
||||
| RAG Hybrid Cách A global MCP | S26 | Memory `feedback_rag_hybrid_pattern.md` + `feedback_rag_distributed_ownership.md` | Cross-project pattern — memory user-level sufficient |
|
||||
| Plan AG PE List tree view UI | S26 | Pattern 19 trong `implementer/MEMORY.md` (HTML details + Tailwind named groups + localStorage Set) | Sub-agent memory — KHÔNG tạo skill cho UI pattern 1×fix |
|
||||
| Mig 28-31 per-NV refactor + Plan N+O 10-surface-point checklist | S21-S23 | `cicd-monitor/MEMORY.md` 10-point checklist promoted to foundation | Cross-agent learning — em đã promote vào cicd-monitor MEMORY.md foundation section curate session 2026-05-22 |
|
||||
| Gotcha #48 (SQLite tie-break multi-Changelog) | S25 Plan AB | `cicd-monitor/MEMORY.md` gotcha #48 section added curate 2026-05-22 + Reviewer 5-category Cat 5 reinforced | Cross-ref to skill `contract-workflow` (test pattern) — defer to next audit nếu pattern proven cross-module |
|
||||
| FE merge synthetic audit + userMap fallback (Plan AC2 + AF) | S25 | Memory `feedback_fe_merge_synthetic_audit.md` + `feedback_fe_usermap_fallback.md` (user-level) | Pattern reusable cross-project (Contract V2 + Budget V2 future) — KHÔNG skill |
|
||||
|
||||
**KHÔNG tạo skill mới.** Tổng số skill giữ **6** (3 domain + 3 ops). Threshold §9.4 anti-pattern "viết skill chỉ để có thêm" respected.
|
||||
|
||||
## Phase 4 — Threshold check + decision
|
||||
|
||||
- ✅ `+8 gotcha` vượt threshold §9.4 (+5) → trigger audit sớm CHỐT
|
||||
- ✅ Mig drift 26→31 (+5) trong 3 skill mention → patch 5 vị trí KHÔNG rewrite
|
||||
- ✅ Test drift 77→111 (+34) trong 1 skill mention → patch 1 vị trí
|
||||
- ✅ Skill drift < 30% (chỉ ef-core-migration + 2 cross-ref README/dependency-audit-erp)
|
||||
- ✅ Memory 4 agent curate trong session cùng — synthesize cross-agent learnings vào foundation sections
|
||||
|
||||
## Phase 5 — Validation per §6.5
|
||||
|
||||
3 câu sau consolidate (per rule §6.5):
|
||||
|
||||
1. **Agent mới đọc 6 tháng sau có biết "tại sao chọn approach này" không?**
|
||||
✅ Có — narrative Mig 22-31 cumulative + Plan AA/AB/AG context preserved trong session logs + memory + 4 agent MEMORY archive. Skill `ef-core-migration` Phase 9 cross-ref block thêm S22-S25 regression breakdown rationale. 10-surface-point per-NV checklist promoted to cicd-monitor MEMORY foundation cho future per-NV refactor scan.
|
||||
|
||||
2. **Có còn cảm giác "kể chuyện" tích lũy không, hay chỉ là instructions khô?**
|
||||
✅ Có — Skill `ef-core-migration` test note line 80 mở rộng "cumulative S22-S25 regression breakdown: ReturnMode + DraftGuard + Reflection AuthorizePolicy + V2 actor scope reject + per-NV lookup discrimination" giữ rationale tại sao 111 test (vs 77 cũ). Skill description giữ Mig 31 latest semantic "F2 per-Approver-slot swap" thay vì plain count.
|
||||
|
||||
3. **Gotcha context vẫn còn ý nghĩa khi đọc rời rạc không?**
|
||||
✅ Có — `dependency-audit-erp` line 153 +#48 SQLite tie-break + #49 dual-phase UI confusion cross-ref. Cicd-monitor MEMORY.md gotcha #48 section full narrative root cause + fix pattern + side benefit (CI test gate catches BEFORE prod). Foundation section preserved.
|
||||
|
||||
## Memory curate concurrent (session same as audit)
|
||||
|
||||
4 agent MEMORY curate cùng session 2026-05-22 (per HANDOFF S25 wrap flag):
|
||||
|
||||
| Agent | Before KB | After KB | Reduction | Archive file |
|
||||
|---|---:|---:|---:|---|
|
||||
| cicd-monitor | 72.4 | 15.8 | **-78%** | `archive/2026-05-runs.md` (58.4 KB) |
|
||||
| implementer | 38.8 | 22.0 | -43% | `archive/2026-05-q1.md` (18.1 KB) |
|
||||
| investigator | 34.9 | 16.3 | -53% | `archive/2026-05-q1.md` (20.2 KB) |
|
||||
| reviewer | 34.5 | 17.9 | -48% | `archive/2026-05-q1.md` (18.3 KB) |
|
||||
| **Total** | **180.6** | **72.0** | **-60%** | All archives 115 KB preserved |
|
||||
|
||||
All 4 MEMORY now under 25KB curate threshold. Rule §6.5 KEEP narrative compliance: archive files preserve FULL verbose entries cho cross-session audit retrieve. Foundation patterns + 5-category checklist + recurring gotcha patterns kept inline.
|
||||
|
||||
## Đề xuất next audit
|
||||
|
||||
- **Cron 2026-06-01** — re-trigger combined audit (cadence chính) — KHÔNG conflict với late audit này (sớm 10 ngày), chỉ re-verify drift mới phát sinh sau S27+.
|
||||
- **Threshold trigger sớm** nếu:
|
||||
- +5 gotcha mới cluster (Plan B Contract V2 wire có thể phát sinh #50+)
|
||||
- Plan B Contract V2 wire complete (drastic schema change cross 4 entity — Mig 32+33 estimate)
|
||||
- Skill drift > 30% (count broken / path broken)
|
||||
- 4 agent MEMORY vượt 25KB threshold trở lại (next curate trigger trong HANDOFF)
|
||||
|
||||
## Stats
|
||||
|
||||
- Total skill: 6 (no add/archive)
|
||||
- Files patched: 3 SKILL.md (ef-core-migration + dependency-audit-erp + README)
|
||||
- Lines diff: ~+12 / ~7 patch
|
||||
- Memory curate concurrent: 4 file -60% size cumulative
|
||||
- Effort: ~30 phút audit + ~1.5h memory curate (em main solo, không spawn sub-agent — judgment scope per Cognition "writes single-threaded")
|
||||
- Audit log: 1 page (file này, theo cadence rule §6.4 — KHÔNG rewrite existing skill-audit-2026-05.md)
|
||||
@ -836,6 +836,50 @@ var changelog = await db.PurchaseEvaluationChangelogs
|
||||
- File: `fe-user/src/components/pe/PeDetailTabs.tsx:1995-2070` (ApprovalsTab + decisionBadge + extractNextTargetHint)
|
||||
- Mirror: `fe-admin/src/components/pe/PeDetailTabs.tsx`
|
||||
|
||||
### 51. INFRASTRUCTURE seed vs DEMO seed phân biệt — `DemoSeed:Disabled` flag gate trap (Session 29 Plan B Chunk A2 Hotfix CICD)
|
||||
|
||||
**Triệu chứng:** Plan B Chunk A2 Implementer scaffold `SeedSampleContractWorkflowV2Async` mirror PE `SeedSampleApprovalWorkflowsV2Async` pattern — nested inside `if (!demoSeedDisabled)` branch trong `DbInitializer.cs:105-111`. Prod has `DemoSeed:Disabled=true` (Plan T S23 t10 — UAT permanent clean slate). Run #231 PASS deploy NHƯNG `QT-HD-V2-001` workflow KHÔNG seed prod. CICD Monitor (agentId a2ea2e3a) verify Stage 4 catch smoking gun log: `"DemoSeed:Disabled=true → skip workflow + contracts + PE + sample V2 seed (Plan T S23 t10 + Plan B Chunk A2 Contract V2)"`. → Drafter Workspace dropdown V2 EMPTY → V2 contract path **BLOCKED end-to-end UAT**.
|
||||
|
||||
**Root cause:** Implementer mirror PE pattern (which IS gated for valid reason — PE workflow A/B already seeded V1 historically) → áp dụng nguyên xi cho Contract V2 (no V1 sample existed) → V2 path không có default workflow để Drafter pick.
|
||||
|
||||
**Fix Hotfix CICD (`38f1c4d`):** PROMOTE `SeedSampleContractWorkflowV2Async` ra ngoài `DemoSeed` gate:
|
||||
```csharp
|
||||
if (!demoSeedDisabled)
|
||||
{
|
||||
await SeedDemoContractsAsync(...);
|
||||
await SeedDemoPurchaseEvaluationsAsync(...);
|
||||
await SeedSampleApprovalWorkflowsV2Async(...); // PE: gated (historical V1 sample existed)
|
||||
}
|
||||
|
||||
// [Plan B S29 2026-05-22 Hotfix CICD] OUT of gate
|
||||
await SeedSampleContractWorkflowV2Async(...); // INFRASTRUCTURE — V2 path requires
|
||||
```
|
||||
|
||||
**Pattern reusable — Seed classification table:**
|
||||
|
||||
| Category | Examples | Gate? |
|
||||
|---|---|---|
|
||||
| **INFRASTRUCTURE always run** | Roles, Departments, Catalogs, MenuTree, AdminPermissions, ContractTemplates, **SampleWorkflowV2 (V2 path requires)** | NO gate |
|
||||
| **DEMO gated** | DemoUsers (30 sample, Plan T disabled prod), DemoContracts ([DEMO]), DemoPE ([DEMO]), SampleApprovalWorkflowsV2 (historical PE A/B legacy) | `if (!demoSeedDisabled)` |
|
||||
|
||||
**Decision tree khi add new Seed method:**
|
||||
1. Production có cần seed này để work end-to-end không?
|
||||
- YES → INFRASTRUCTURE (no gate)
|
||||
- NO → DEMO (gated)
|
||||
2. Có safe để admin edit/delete/disable không?
|
||||
- YES → INFRASTRUCTURE OK (admin sửa qua Designer khi cần)
|
||||
- NO → architect re-think (immutable seed = anti-pattern)
|
||||
|
||||
**Bonus — Smart Friend ROI:** CICD Monitor catch BEFORE bro UAT 401/empty experience. Cumulative pattern proven 4× S22 #44 + S25 #48 + S29 Plan B Reviewer #ApplicableType + S29 Plan B CICD #DemoSeed.
|
||||
|
||||
**Phòng tránh tương lai:** Khi Implementer mirror PE V2 pattern cho new module (Budget V2, Notification V2), explicit check question: "PE pattern gated/ungated, có applicable cho new module không?" — KHÔNG copy nguyên xi DemoSeed gate placement.
|
||||
|
||||
**References:**
|
||||
- Hotfix CICD commit: `38f1c4d` (Run #232 PASS 3m33s)
|
||||
- File: `src/Backend/SolutionErp.Infrastructure/Persistence/DbInitializer.cs:105-122`
|
||||
- Cross-ref: Plan T S23 t10 DemoSeed flag (gotcha implicit)
|
||||
- Memory cross-ref: `feedback_demo_seed_flag_disable.md` (Plan T pattern)
|
||||
|
||||
### 50. Page move cross-app — `Layout.tsx` `resolvePath` staticMap missed mirror → silent sidebar drop (Session 29 Plan CA Hotfix 1)
|
||||
|
||||
**Triệu chứng:** Plan CA move 4 master pages từ fe-admin → fe-user (commit `06a441c` Implementer Case 2). BE `/api/menus/me` return tree đầy đủ (Master + 4 children + Catalogs sub-tree 4 children, ALL CanRead=true). Admin login eoffice → sidebar group "DANH MỤC" expand chỉ thấy "Danh mục chi tiết" (Catalogs), **3 leaf Suppliers/Projects/Departments + 4 sub-catalogs biến mất silent**.
|
||||
@ -904,4 +948,5 @@ const staticMap: Record<string, string> = {
|
||||
23. Nếu Gitea Actions API trả 404 trên `/actions/runs` → đúng path là `/actions/tasks` (Gitea naming khác GitHub). Cache `updated_at` stale ~2 min → cross-check VPS file LastWriteTime cho time-sensitive verify (#46)
|
||||
24. Nếu test `OrderByDescending(CreatedAt).First()` query audit table fail sau add Changelog mới → SQLite frozen-clock tie-break, MUST filter Summary/EntityType discriminator (#48)
|
||||
25. Nếu page move cross-app (Implementer Case 2) nhưng menu leaf KHÔNG hiện sidebar dù BE trả permission OK → check `Layout.tsx` `resolvePath` staticMap miss key mapping → MenuLeaf null guard silent drop (#50). 4-place mirror checklist: page + Routes + menuKeys.ts + Layout.tsx staticMap
|
||||
26. Nếu new Seed method KHÔNG chạy prod dù dotnet build PASS + deploy SUCCESS → check nested inside `if (!demoSeedDisabled)` gate (Plan T S23 t10 flag enabled prod) → INFRASTRUCTURE seed phải PROMOTE OUT of DemoSeed gate (#51). Decision tree: production cần để work end-to-end? YES → ungate
|
||||
25. Nếu UI audit list show `Đã gửi duyệt → Đã gửi duyệt` lặp gây nhầm → drop dual-phase badge khi state machine self-loop, thay Decision badge + next-target hint parse từ comment (#49)
|
||||
|
||||
892
docs/guides/rag-onboarding-guide.md
Normal file
892
docs/guides/rag-onboarding-guide.md
Normal file
@ -0,0 +1,892 @@
|
||||
# RAG Unified — Onboarding Guide cho dự án mới
|
||||
|
||||
> **Phiên bản:** 1.0 (2026-05-22) — chốt bởi em main SOLUTION_ERP S26+S27.
|
||||
> **Pattern:** Approach B Distributed Bootstrap + Option 4a Manual PowerShell Scripts (per memory user-level `feedback_rag_distributed_ownership.md`).
|
||||
> **Audience:** Em main project Y/Z (NamGroup / DH Y Dược / Ashico / Vipix / dự án mới khác) khi anh pqhuy mở Claude Code session.
|
||||
> **Cấu trúc nguồn:** SOLUTION_ERP em main đã pioneer setup `D:\.claude-rag\` infrastructure + 4 PS scripts + custom Dashboard. Project khác **TỰ BOOTSTRAP** theo guide này (~10 phút mỗi project), KHÔNG em main project khác làm hộ.
|
||||
|
||||
---
|
||||
|
||||
## §1 TL;DR (Quick start — 3 phút)
|
||||
|
||||
Anh pqhuy đã có RAG infrastructure global ở `D:\.claude-rag\` (Voyage AI + Qdrant Windows native + FastMCP). Em main project X mới chỉ cần 3 bước:
|
||||
|
||||
```powershell
|
||||
# 1. Verify Qdrant + MCP server running (em pioneer đã setup)
|
||||
rag-status
|
||||
|
||||
# 2. Tạo .claude/rag.json trong project root (template §4)
|
||||
# 3. Bootstrap corpus
|
||||
python D:\.claude-rag\bootstrap.py --project <project_id>
|
||||
```
|
||||
|
||||
Restart Claude Code → 6 MCP tools `mcp__rag-unified__*` khả dụng trong session project mới.
|
||||
|
||||
**Em main project mới responsibility:**
|
||||
- Tạo `.claude/rag.json` declare project_id + corpus_paths + sensitivity flag
|
||||
- Run bootstrap.py ~5 phút embed
|
||||
- Brief 4 sub-agent (nếu có setup multi-agent) qua MEMORY.md
|
||||
- KHÔNG modify `D:\.claude-rag\server.py` (shared infrastructure)
|
||||
|
||||
---
|
||||
|
||||
## §2 Background — Tại sao Approach B Distributed?
|
||||
|
||||
### Bối cảnh
|
||||
|
||||
Anh pqhuy dev solo, có 5+ dự án cùng máy localhost (SOLUTION_ERP + NamGroup + DH Y Dược + Ashico + Vipix + tương lai). Mỗi project có 100-2000 file MD docs + agent memory.
|
||||
|
||||
### Quyết định chốt (per memory `feedback_rag_distributed_ownership.md`)
|
||||
|
||||
| Approach | Verdict |
|
||||
|---|---|
|
||||
| A. Em main SOLUTION_ERP làm hộ tất cả 4 project | ❌ Vi phạm Cognition "writes single-threaded" - em không có context project khác |
|
||||
| **B. Distributed - 4 em main project khác tự bootstrap khi mở session** | ✅ **CHỌN** - đúng boundary, ownership rõ, sensitivity per project tự decide |
|
||||
| C. Hybrid em làm 1 mẫu + 3 tự follow | 🤔 Vẫn còn cross-boundary 1 lần |
|
||||
|
||||
### Lý do CHỌN Approach B
|
||||
|
||||
1. **Cognition "writes single-threaded" principle** - mỗi em main own context flow project mình
|
||||
2. **Em main project khác hiểu codebase sâu hơn** - SOLUTION_ERP em không có context active NamGroup
|
||||
3. **Sensitivity per project** - vd DH Y Dược client confidential, em main DH biết set `share_to_global=false`. Em main SOLUTION_ERP KHÔNG biết → có thể set sai → leak risk
|
||||
4. **Self-ownership re-bootstrap** - khi project Y thêm 50 file mới, em main Y biết để re-bootstrap. Em main X không monitor được Y
|
||||
5. **Knowledge propagation natural** - em main Y bootstrap → `store_memory` pattern → `share_to_global=true` → các em main khác hưởng lợi qua RAG cross-share
|
||||
|
||||
---
|
||||
|
||||
## §3 Pre-check (Verify infrastructure global đã sẵn sàng)
|
||||
|
||||
Trước khi bootstrap, em main project mới CHECK:
|
||||
|
||||
```powershell
|
||||
# 1. Aliases hoạt động (sẽ load $PROFILE auto)
|
||||
rag-status
|
||||
```
|
||||
|
||||
Output kỳ vọng:
|
||||
- `[Qdrant Server] Status: Running PID xxx port 6333` (em pioneer đã start)
|
||||
- `[MCP Server] Registration: rag-unified [OK] Connected (user-level)`
|
||||
- `[Voyage AI] API key set: [OK]`
|
||||
|
||||
**Nếu Qdrant DOWN:**
|
||||
```powershell
|
||||
rag-start # Em pioneer setup, just start
|
||||
```
|
||||
|
||||
**Nếu MCP NOT REGISTERED:** Em main project mới KHÔNG self-register. Báo anh pqhuy để re-add user-level (1 lần duy nhất per Windows user):
|
||||
```powershell
|
||||
claude mcp add -s user -e "VOYAGE_API_KEY=$env:VOYAGE_API_KEY" -- rag-unified python "D:\.claude-rag\server.py"
|
||||
```
|
||||
|
||||
**Nếu API key MISSING:**
|
||||
```powershell
|
||||
[Environment]::SetEnvironmentVariable("VOYAGE_API_KEY", "pa-MiN...", "User")
|
||||
# Restart Claude Code để pick up env var
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## §4 Bootstrap 3 steps cho project mới
|
||||
|
||||
### Step 1: Tạo `.claude/rag.json` ở project root
|
||||
|
||||
Template generic:
|
||||
```json
|
||||
{
|
||||
"project_id": "<kebab-or-snake-case-id>",
|
||||
"display_name": "<Tên đầy đủ project>",
|
||||
"corpus_paths": [
|
||||
"docs/**/*.md",
|
||||
".claude/agent-memory/**/MEMORY.md",
|
||||
".claude/skills/**/SKILL.md"
|
||||
],
|
||||
"exclude_paths": [
|
||||
"docs/_archive/**",
|
||||
"node_modules/**",
|
||||
"bin/**",
|
||||
"obj/**",
|
||||
".git/**"
|
||||
],
|
||||
"extra_corpus": [
|
||||
"C:\\Users\\pqhuy\\.claude\\projects\\<project-folder>\\memory\\*.md"
|
||||
],
|
||||
"share_to_global": true,
|
||||
"search_scope_default": ["self", "shared_global"],
|
||||
"auto_reindex": true,
|
||||
"chunk_size": 1500,
|
||||
"chunk_overlap": 200,
|
||||
"contextual_retrieval": true
|
||||
}
|
||||
```
|
||||
|
||||
**Checklist customize:**
|
||||
|
||||
| Field | Hướng dẫn |
|
||||
|---|---|
|
||||
| `project_id` | Lowercase + underscore. Ví dụ: `namgroup_main`, `dh_y_duoc`, `ashico_erp`, `vipix_multisite`. Phải UNIQUE cross 5 project. |
|
||||
| `display_name` | Tên đầy đủ cho dashboard hiển thị, vd `"NamGroup - HRM"` |
|
||||
| `corpus_paths` | Glob patterns relative project root. Default 3 path cover docs + agent memory + skills. Tăng thêm nếu project có folder docs khác (vd `tests/specs/**/*.md`). |
|
||||
| `exclude_paths` | KHÔNG embed file tạm/binary/archive |
|
||||
| `extra_corpus` | Memory user-level Claude Code (path absolute). Folder: `C:\Users\pqhuy\.claude\projects\<your-project-folder-name>\memory\*.md` |
|
||||
| `share_to_global` | **CRITICAL DECISION:** `true` = chunks promote-able to shared_global collection (cross-project search visible). `false` = client confidential, chỉ self-project access. **Em main project decide based on data sensitivity** (vd DH Y Dược client → `false`, NamGroup internal HRM → `true`). |
|
||||
| `search_scope_default` | Default `["self", "shared_global"]` - cân bằng project-specific + cross-project pattern reuse |
|
||||
| `chunk_size` / `chunk_overlap` | Default 1500/200 chars - đã tune cho MD docs Vietnamese. KHÔNG đổi unless project có docs structure khác hẳn. |
|
||||
| `contextual_retrieval` | `true` - Anthropic Contextual Retrieval prepend "From <doc> > <heading>:" - +15% recall |
|
||||
|
||||
### Step 2: Run bootstrap
|
||||
|
||||
```powershell
|
||||
python D:\.claude-rag\bootstrap.py --project <project_id>
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
[1/4] Scanning corpus... Found N files
|
||||
[2/4] Chunking + contextual prepend... Total chunks: M
|
||||
Estimated tokens: ~XXX,XXX (Voyage free tier: 200M/month)
|
||||
[3/4] Voyage-4-large embedding + Qdrant upsert + SQLite BM25... Upserted M chunks in T seconds
|
||||
[4/4] Update registry...
|
||||
[OK] Bootstrap complete: <project_id> ready (M chunks)
|
||||
```
|
||||
|
||||
**Performance benchmark (SOLUTION_ERP 2026-05-22):**
|
||||
- 126 files → 2,628 chunks → ~484K tokens → 60.9s embed + upsert
|
||||
- 2nd bootstrap với cache hit: 6.5s (10× speedup)
|
||||
|
||||
### Step 3: Verify
|
||||
|
||||
```powershell
|
||||
rag-status # See new project in [Collections] section
|
||||
rag-dashboard # Visual verify via browser
|
||||
```
|
||||
|
||||
Test query in Claude Code session (project mới):
|
||||
```
|
||||
search_memory("pattern X tôi đã làm chưa")
|
||||
```
|
||||
|
||||
Should return chunks từ project mới + shared_global (nếu có).
|
||||
|
||||
---
|
||||
|
||||
## §5 6 MCP Tools matrix
|
||||
|
||||
| Tool | Scope | Use case |
|
||||
|---|---|---|
|
||||
| `search_memory(query, scope, top_k, use_rerank)` | `self` / `shared_global` / `all_projects` / `default` | Tìm pattern, gotcha, narrative trong project hiện tại + shared |
|
||||
| `cross_project_search(query, top_k)` | All projects | "Pattern X tao đã làm ở dự án nào trước chưa?" - explore cross-project knowledge |
|
||||
| `search_code(query, file_pattern, top_k)` | Self only (BM25-heavy) | Tìm exact symbol/function name trong source code |
|
||||
| `store_memory(content, source_path, tags)` | Self | Save pattern on-the-fly cuối session, không cần re-bootstrap |
|
||||
| `promote_to_shared(chunk_id)` | Self → shared_global | Pattern proven cross-project ≥2x use → visible to all projects (v0 stub, defer v1) |
|
||||
| `list_projects()` | All registry | Overview projects + collection chunk counts |
|
||||
|
||||
**Em main project mới brief 4 sub-agent (nếu có setup):**
|
||||
|
||||
| Agent | Skills preload + RAG access |
|
||||
|---|---|
|
||||
| 🟦 Investigator | Auto-detect cwd → project_id → `mcp__rag-unified__search_memory(scope="self")` cho research patterns |
|
||||
| 🟨 Implementer | Same auto-detect + `search_code` cho symbol lookup khi cookie-cutter mirror |
|
||||
| 🟥 Reviewer | Same auto-detect + `cross_project_search` để verify pattern proven elsewhere trước commit |
|
||||
| 🟩 CICD Monitor | Same + `list_projects` cho infra state checks |
|
||||
|
||||
---
|
||||
|
||||
## §6 4 Sub-agent setup brief (optional - cho project ≥10K LOC, ≥3 month)
|
||||
|
||||
Per memory `feedback_multi_agent_setup.md` - setup multi-agent CHỈ khi pass 6/6 decision gate. SOLUTION_ERP S20 turn 12 đã match (59 tables + 142 endpoints + 6 skills + 44 gotchas).
|
||||
|
||||
**Pattern reusable cho project mới:**
|
||||
|
||||
1. Tạo `.claude/agents/` folder + 4 `.md` files (Investigator + Implementer + Reviewer + CICD Monitor)
|
||||
2. Tạo `.claude/agent-memory/<name>/MEMORY.md` seed per agent
|
||||
3. Copy template từ SOLUTION_ERP `.claude/agents/README.md` (master coordination guide)
|
||||
4. Customize project-specific:
|
||||
- Skills preload (tùy stack: .NET / React / Python / Go)
|
||||
- Domain entities + workflow patterns
|
||||
- Live prod URLs + bearer tokens
|
||||
- Gotcha catalog reference
|
||||
5. End-of-session: 4 agent flush MEMORY.md updates → em main synthesize cross-agent learnings → integrate vào memory + session log
|
||||
|
||||
**Reference SOLUTION_ERP files (paste-friendly templates):**
|
||||
- `.claude/agents/README.md` - master coordination guide với 6-criteria decision gate
|
||||
- `.claude/agents/investigator.md` - frontmatter + system prompt template
|
||||
- `.claude/agents/implementer.md` - REFUSE strict 6-criteria
|
||||
- `.claude/agents/reviewer.md` - 5-category checklist + Smart Friend guard
|
||||
- `.claude/agents/cicd-monitor.md` - 5-stage post-deploy verify
|
||||
|
||||
---
|
||||
|
||||
## §7 Permission + Security
|
||||
|
||||
### MCP user-level scope (1 lần setup per Windows user)
|
||||
|
||||
`claude mcp add -s user` registers `rag-unified` ở `%USERPROFILE%\.claude.json` - persist across ALL Claude Code sessions cho user pqhuy. Bất kỳ project nào pqhuy mở đều có access 6 tools (KHÔNG cần re-register).
|
||||
|
||||
### VOYAGE_API_KEY scope
|
||||
|
||||
`[Environment]::SetEnvironmentVariable("VOYAGE_API_KEY", "...", "User")` - Windows User registry, persist boot-to-boot. KHÔNG commit vào git. KHÔNG share cross-machine.
|
||||
|
||||
### `share_to_global` flag (per-project)
|
||||
|
||||
- `true` → chunks có thể promote vào `shared_global` collection → cross-project search visible (em main khác có thể thấy)
|
||||
- `false` → strict isolated cho project (client confidential, NDA, regulated data)
|
||||
|
||||
**KIẾN NGHỊ:** Em main project mới BẮT BUỘC review sensitivity TRƯỚC khi bootstrap. Vd:
|
||||
- DH Y Dược (client confidential): `share_to_global=false` + exclude paths chứa client name
|
||||
- NamGroup (internal HRM): `share_to_global=true` ok
|
||||
- Vipix multisite (public docs): `share_to_global=true`
|
||||
|
||||
---
|
||||
|
||||
## §8 Workflow daily — Em main project mới
|
||||
|
||||
```powershell
|
||||
# Morning - mở session Claude Code project mới
|
||||
rag-status # Check infra OK
|
||||
rag-dashboard # Visual sanity check
|
||||
|
||||
# Trong session - search context
|
||||
search_memory("workflow X") # MCP tool call trong session
|
||||
cross_project_search("pattern Y") # Find proven pattern elsewhere
|
||||
|
||||
# End of session - save new pattern
|
||||
store_memory("Pattern Z chốt 2026-XX-XX...", tags=["pattern", "<topic>"])
|
||||
|
||||
# Periodic - re-bootstrap khi docs thay đổi nhiều
|
||||
python D:\.claude-rag\bootstrap.py --project <project_id> --re-embed
|
||||
```
|
||||
|
||||
### Khi nào re-bootstrap?
|
||||
|
||||
- Sau session lớn thêm > 20 file MD docs mới
|
||||
- Sau drastic refactor MD structure (rename folders, restructure)
|
||||
- Monthly cadence per `feedback_md_compact_narrative.md` audit + curate cycle
|
||||
|
||||
### Khi nào KHÔNG re-bootstrap (cache hit)?
|
||||
|
||||
- File MD chỉ patched < 30% content - bootstrap re-embed sẽ skip chunks unchanged (SHA256 cache hit)
|
||||
- Session khác không touch corpus paths
|
||||
|
||||
---
|
||||
|
||||
## §9 Troubleshooting
|
||||
|
||||
### Q: `rag-status` báo Qdrant DOWN nhưng anh đã `rag-start`?
|
||||
|
||||
A: Check 30s timeout - Qdrant cần ~10s warmup. Retry sau:
|
||||
```powershell
|
||||
Start-Sleep -Seconds 10
|
||||
Invoke-RestMethod -Uri "http://localhost:6333/healthz" -TimeoutSec 10
|
||||
```
|
||||
|
||||
Nếu vẫn DOWN, check logs:
|
||||
```powershell
|
||||
Get-Content "D:\.claude-rag\logs\qdrant-$(Get-Date -Format 'yyyyMMdd').log" -Tail 30
|
||||
```
|
||||
|
||||
### Q: MCP server `rag-unified` NOT CONNECTED?
|
||||
|
||||
A: 3 nguyên nhân thường gặp:
|
||||
|
||||
1. **VOYAGE_API_KEY chưa load vào Claude Code env** → Restart Claude Code completely (close all windows)
|
||||
2. **Python deps thiếu** → `pip install fastmcp voyageai qdrant-client watchdog python-dotenv`
|
||||
3. **MCP đăng ký sai path** → Check `claude mcp list` - phải có dòng `rag-unified: python D:\.claude-rag\server.py - [OK] Connected`
|
||||
|
||||
### Q: `bootstrap.py` báo Voyage rate limit hoặc 429?
|
||||
|
||||
A: Free tier 200M tokens/month chia equally across requests. Nếu hit limit:
|
||||
- Wait 1 phút retry (Voyage rate limit window ~60s)
|
||||
- Batch nhỏ hơn: `--batch-size 32` thay vì default 128
|
||||
- Check Voyage dashboard: https://dash.voyageai.com/
|
||||
|
||||
### Q: SQLite FTS5 query error `no such column: in`?
|
||||
|
||||
A: Gotcha #48 cousin - reserved keyword. `_sanitize_fts5_query()` strip non-alphanumeric. Nếu vẫn fail, simplify query (remove `-`, `:`, `()`)
|
||||
|
||||
### Q: Qdrant batch upsert WinError 10053 "connection aborted"?
|
||||
|
||||
A: Batch quá lớn. `lib/retrieval.py:UPSERT_BATCH = 64` đã limit. Nếu vẫn fail, giảm xuống 32.
|
||||
|
||||
### Q: HuggingFace symlinks warning Windows?
|
||||
|
||||
A: Non-critical (cache works degraded efficiency). Suppress: `$env:HF_HUB_DISABLE_SYMLINKS_WARNING=1`
|
||||
|
||||
---
|
||||
|
||||
## §10 Tunings (advanced)
|
||||
|
||||
### Tăng recall (sacrifice cost)
|
||||
|
||||
```json
|
||||
{
|
||||
"chunk_size": 1000, // smaller chunks = more granular match
|
||||
"chunk_overlap": 300, // higher overlap = catch boundary patterns
|
||||
"use_rerank_default": true // rerank-2.5 = +20-30% recall vs vector-only
|
||||
}
|
||||
```
|
||||
|
||||
Cost trade-off: smaller chunks = N% more tokens to embed + rerank.
|
||||
|
||||
### Giảm cost (sacrifice recall)
|
||||
|
||||
```json
|
||||
{
|
||||
"chunk_size": 2500,
|
||||
"chunk_overlap": 100,
|
||||
"use_rerank_default": false // rely on vector + BM25 only
|
||||
}
|
||||
```
|
||||
|
||||
Saving: ~30% Voyage tokens. Recall drop ~10-15%.
|
||||
|
||||
### BM25 weight tuning
|
||||
|
||||
Default RRF k=60 (Reciprocal Rank Fusion). Tăng `k` = giảm BM25 dominance, tăng vector. Em main project mới KHÔNG tune trừ khi có golden benchmark dataset.
|
||||
|
||||
---
|
||||
|
||||
## §11 Best practices cross-project
|
||||
|
||||
1. **`store_memory` defensive** - cuối session save new pattern proven, không đợi monthly bootstrap
|
||||
2. **Cross-project search BEFORE design** - `cross_project_search("pattern X")` check trước khi implement mới
|
||||
3. **Sensitivity audit per session** - khi push file mới có client info → confirm `share_to_global` flag đúng
|
||||
4. **Dashboard daily** - mở `rag-dashboard` mỗi sáng để verify infra healthy + collection counts không drop bất thường
|
||||
5. **Document `.claude/rag.json` decisions** - comment trong file lý do chốt sensitivity flag, exclude paths
|
||||
6. **Cron monthly audit cadence** - per rule §6.4 SOLUTION_ERP, project mới adopt monthly cron skill+doc audit. Drift trigger sớm nếu +5 gotcha mới
|
||||
|
||||
---
|
||||
|
||||
## §12 Status Monitoring + Manual Control (Option 4b NSSM Windows Service ⭐ UPGRADED S27)
|
||||
|
||||
### Upgrade S27: Qdrant chạy as Windows Service (NSSM)
|
||||
|
||||
Phiên bản S26 dùng Option 4a (manual PS scripts only). **S27 upgrade lên Option 4b** với NSSM Windows Service:
|
||||
|
||||
| | Option 4a (S26) | **Option 4b NSSM (S27 RECOMMEND)** |
|
||||
|---|---|---|
|
||||
| Auto-start timing | Sau anh login Windows (Startup folder) | ✅ Boot-time (trước login) |
|
||||
| Auto-restart on crash | ❌ Stay crashed | ✅ Auto-respawn 3s delay |
|
||||
| Survive logout/login | ❌ Stop khi logout | ✅ Service runs background |
|
||||
| Control | `rag-start/stop/status/dashboard` | Same + `Get-Service Qdrant` native |
|
||||
| Setup once | ~30 phút | ~35 phút (+ install NSSM elevated) |
|
||||
| OOM recovery (vd 8.4MB OOM em pioneer S27) | Manual rag-restart | ✅ Auto-respawn |
|
||||
|
||||
**Setup elevated PowerShell (1 lần duy nhất):**
|
||||
```powershell
|
||||
# 1. Download NSSM 2.24 (~3 MB, may retry nssm.cc 503 transient)
|
||||
$nssmDir = "D:\.claude-rag\nssm"
|
||||
Invoke-WebRequest -Uri "https://nssm.cc/release/nssm-2.24.zip" -OutFile "$nssmDir\nssm-2.24.zip"
|
||||
Expand-Archive "$nssmDir\nssm-2.24.zip" $nssmDir -Force
|
||||
Copy-Item "$nssmDir\nssm-2.24\win64\nssm.exe" "$nssmDir\nssm.exe"
|
||||
|
||||
# 2. Run install script (em pioneer write D:\.claude-rag\scripts\install-service.ps1)
|
||||
& "D:\.claude-rag\scripts\install-service.ps1"
|
||||
```
|
||||
|
||||
Script tự động: stop manual qdrant + register service + AppDirectory + log paths + Start SERVICE_AUTO_START + AppExit Default Restart 3s delay + DisplayName "Qdrant Vector DB (RAG Unified)" + Description + start service + health verify.
|
||||
|
||||
**Verify post-install:**
|
||||
```powershell
|
||||
Get-Service Qdrant # Should show Status: Running, StartType: Automatic
|
||||
```
|
||||
|
||||
**Troubleshooting nếu start fail (WAL lock conflict):**
|
||||
```powershell
|
||||
# Pre-existing qdrant.exe manual holding WAL → kill + retry
|
||||
& "D:\.claude-rag\scripts\fix-service-start.ps1" # elevated
|
||||
```
|
||||
|
||||
### Aliases trong $PROFILE (~30 phút first-time setup)
|
||||
|
||||
```powershell
|
||||
function rag-start { & "D:\.claude-rag\scripts\start.ps1" } # Start Qdrant background
|
||||
function rag-stop { & "D:\.claude-rag\scripts\stop.ps1" } # Graceful stop
|
||||
function rag-status { & "D:\.claude-rag\scripts\status.ps1" } # Full status report 6 section
|
||||
function rag-dashboard { & "D:\.claude-rag\scripts\dashboard.ps1" } # Custom HTML dashboard + open browser
|
||||
function rag-restart { & "D:\.claude-rag\scripts\stop.ps1"; Start-Sleep 2; & "D:\.claude-rag\scripts\start.ps1" }
|
||||
function rag-boot { & "D:\.claude-rag\scripts\boot.ps1" } # Manual trigger boot sequence
|
||||
```
|
||||
|
||||
### 6 PS scripts khả dụng (em pioneer SOLUTION_ERP đã build — Service mode S27)
|
||||
|
||||
| Script | Mục đích | Output |
|
||||
|---|---|---|
|
||||
| `start.ps1` | `Start-Service Qdrant` (needs Admin if stopped) | Service status + PID + RAM |
|
||||
| `stop.ps1` | `Stop-Service Qdrant -Force` (needs Admin) | Status verification |
|
||||
| `status.ps1` | Full status: Service + Process + MCP + Voyage + Collections + Disk + Agent MEMORY | Terminal 6 section colored (no Admin) |
|
||||
| `dashboard.ps1` | Generate custom HTML dashboard (STATIC snapshot) + open browser | `D:\.claude-rag\dashboard.html` |
|
||||
| `boot.ps1` | Post-login: verify service Running + regen Dashboard + open browser | Used by Startup folder shortcut |
|
||||
| `install-service.ps1` | NSSM register Qdrant as Windows Service (1 lần) | Service Running + Auto-start verified |
|
||||
| `fix-service-start.ps1` | Recover service after WAL lock conflict (rare) | Service Running verified |
|
||||
|
||||
### Custom MCP Dashboard
|
||||
|
||||
**URL:** `file:///D:/.claude-rag/dashboard.html` (auto-generated, auto-open by `rag-dashboard` command)
|
||||
|
||||
⚠️ **IMPORTANT (S27 fix):** Dashboard HTML là **STATIC SNAPSHOT** tại thời điểm anh chạy `rag-dashboard`. **KHÔNG auto-poll Qdrant API live** — browser meta refresh chỉ reload HTML cached, KHÔNG re-run PS script. Muốn data live → mở **Qdrant Native Dashboard** (`http://localhost:6333/dashboard`) fetch API real-time. Custom Dashboard chỉ dùng cho ecosystem overview (Service+MCP+Voyage+Agent MEMORY combined panel mà Qdrant native không có).
|
||||
|
||||
**Panels:**
|
||||
1. **Qdrant Vector DB** - PID/version/uptime/RAM/storage + link Qdrant native dashboard
|
||||
2. **MCP Server (FastMCP)** - Registration status + 6 tools matrix
|
||||
3. **Collections** - List all `proj_*` + `shared_global` chunk counts
|
||||
4. **Voyage AI** - API key + scope + embedding/rerank model + free tier
|
||||
5. **System** - Disk usage + Python version + paths
|
||||
6. **Agent MEMORY** - 4 agent MEMORY.md sizes (SOLUTION_ERP) with curate threshold warnings
|
||||
7. **Recent Qdrant Logs** - last 10 lines
|
||||
|
||||
**Auto-refresh:** 60s via `<meta http-equiv="refresh" content="60">`. Manual refresh via "Refresh Now" button.
|
||||
|
||||
**Customization cho project mới (optional):**
|
||||
- Edit `dashboard.ps1` Section 6 `$memDir` path → point to project mới `.claude/agent-memory/`
|
||||
- Add custom panels (vd Section "Recent commits" via `git log --oneline -10`)
|
||||
- Color palette: change `#f59e0b` (orange) → project brand color
|
||||
|
||||
### Auto-start on Windows boot (S27 — 2-layer)
|
||||
|
||||
**Layer 1 — NSSM Windows Service (auto-start Qdrant):**
|
||||
- Service `Qdrant` StartType=Automatic → boot-time auto-start (trước login)
|
||||
- Auto-restart on crash (AppExit Default Restart 3s delay)
|
||||
- Survive logout/login
|
||||
|
||||
**Layer 2 — Startup folder shortcut (auto-open Dashboard sau anh login):**
|
||||
- Path: `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\rag-boot.lnk`
|
||||
- Target: `powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "D:\.claude-rag\scripts\boot.ps1"`
|
||||
- `boot.ps1` S27 updated: verify service Running (KHÔNG start lại) + regen Dashboard + open browser
|
||||
- Disable: Delete `.lnk` file (Qdrant vẫn auto-start by service)
|
||||
|
||||
### Qdrant Native Dashboard (built-in FREE — Web UI v0.2.12)
|
||||
|
||||
URL: **`http://localhost:6333/dashboard`** (browse Qdrant collections, query playground, metrics)
|
||||
|
||||
⚠️ **Yêu cầu trước:** Em pioneer SOLUTION_ERP đã download Web UI static files vào `D:\.claude-rag\qdrant-bin\static\` (S27 hotfix - Qdrant Windows binary zip không bundle Web UI). Nếu native dashboard 404, xem Gotcha #4 §A2 để re-download.
|
||||
|
||||
**Khác biệt Native Qdrant vs Custom MCP Dashboard:**
|
||||
|
||||
| | Qdrant Native | Custom MCP (em pioneer build) |
|
||||
|---|---|---|
|
||||
| URL | `http://localhost:6333/dashboard` | `file:///D:/.claude-rag/dashboard.html` |
|
||||
| Mục đích | Browse collections + query playground + metrics | Status overview RAG ecosystem |
|
||||
| Panels | Collections, Console, Cluster, Snapshots | Qdrant+MCP+Voyage+Agent MEMORY+Logs |
|
||||
| Auto-refresh | Yes (Qdrant native polling) | 60s meta refresh |
|
||||
| Khi dùng | Khi cần inspect collection data, run test query | Khi cần check overall health + 4 agent MEMORY sizes + Voyage token usage |
|
||||
|
||||
**Bookmark cả 2** — complementary, không thay thế nhau.
|
||||
|
||||
---
|
||||
|
||||
## §13 Approach B Distributed Workflow (Em main pioneer KHÔNG làm hộ)
|
||||
|
||||
### Responsibility split
|
||||
|
||||
**Em main pioneer (SOLUTION_ERP):**
|
||||
- ✅ Build infrastructure `D:\.claude-rag\` (Qdrant binary + FastMCP server + lib + scripts)
|
||||
- ✅ Build 4 PS scripts (start/stop/status/dashboard) + boot.ps1
|
||||
- ✅ Custom MCP Dashboard HTML generator
|
||||
- ✅ $PROFILE aliases setup
|
||||
- ✅ Startup folder shortcut auto-boot
|
||||
- ✅ Bootstrap SOLUTION_ERP corpus (proj_solution_erp)
|
||||
- ✅ Xuất guide này (file `rag-onboarding-guide.md`)
|
||||
- ❌ **KHÔNG bootstrap data cho project Y/Z khác** - đó là việc của em main project đó
|
||||
|
||||
**Em main project Y/Z (NamGroup / DH Y Dược / Ashico / Vipix / khác — khi anh pqhuy mở Claude Code project đó):**
|
||||
|
||||
1. **Đọc guide này** (5 phút) - paste vào `docs/guides/rag-onboarding-guide.md` của project nếu chưa có
|
||||
2. **Tự tạo `.claude/rag.json`** - em main project hiểu CONTEXT cụ thể (project_id, corpus paths, sensitivity flag)
|
||||
3. **Tự run bootstrap.py** ~5 phút embed
|
||||
4. **Test query verify** hoạt động
|
||||
5. **Brief 4 sub-agent của project đó** qua MEMORY.md (nếu có setup multi-agent)
|
||||
|
||||
### Pattern reusable cross-project
|
||||
|
||||
**Setup-once, scale-distributed pattern** cho bất kỳ multi-project shared infrastructure (RAG + MCP + future tools):
|
||||
|
||||
```
|
||||
1. Em main project pioneer (P1 = SOLUTION_ERP) build infra + xuất onboarding MD
|
||||
2. P1 KHÔNG executable cho P2/P3/.../Pn
|
||||
3. Em main P2/P3/.../Pn tự đọc MD + apply khi anh pqhuy mở session project đó
|
||||
4. Cumulative knowledge graph natural - mỗi em main own context, share qua shared_global collection
|
||||
```
|
||||
|
||||
### Anti-patterns avoided
|
||||
|
||||
- ❌ Em main project X bootstrap data cho project Y/Z - vi phạm Cognition boundary
|
||||
- ❌ Hardcode `.claude/rag.json` cho project khác trong em main X - em không biết sensitivity
|
||||
- ❌ Task Scheduler auto-start dù không cần (RAM cost + lose control - anh chọn manual scripts thay)
|
||||
- ❌ Embed config decisions qua chat conversation - KHÔNG vào RAG, mất khi session crash
|
||||
|
||||
---
|
||||
|
||||
## §A3 Context loading Hybrid pattern — em main workflow optimization ⭐ S27 NEW
|
||||
|
||||
> **Audience:** Em main Opus project Y/Z (NamGroup / DH Y Dược / Ashico / Vipix / khác). Áp dụng cho mỗi session daily ops.
|
||||
> **Origin:** Memory user-level `feedback_rag_hybrid_pattern.md` (Cách A defensive). Bài học S27 SOLUTION_ERP em pioneer.
|
||||
|
||||
### §A3.1 — Why Hybrid (Cách A defensive vs Cách B aggressive)
|
||||
|
||||
Em main Opus 4.7 có **1M token context window** (qua `model: inherit` từ parent). KHÔNG load hết tất cả MD vào blanket — wasteful + context rot.
|
||||
|
||||
| Cách | Blanket size | RAG usage | Decision quality | UX latency | Khi dùng |
|
||||
|---|---|---|---|---|---|
|
||||
| **Cách A defensive (CHỌN)** | ~120K | Supplement retrieve on-demand | 90% (control flow strong) | Smooth | **Project MD > 1M tokens cumulative** |
|
||||
| Cách B aggressive | Cắt 60-70% | Cascade retrieve mỗi task | 75-80% (fragmented) | +1-2s mỗi state question | KHÔNG khuyến nghị |
|
||||
| Skip RAG | Blanket all | Zero | Best decision quality | Best UX | Project MD < 200K tokens |
|
||||
|
||||
**Decision gate cho project mới:**
|
||||
- MD < 200K tokens → Skip RAG entirely
|
||||
- MD 200K-1M → Lazy blanket sufficient, RAG nice-to-have
|
||||
- **MD > 1M → RAG MANDATORY** (vượt context window blanket)
|
||||
|
||||
### §A3.2 — Layer 1: Blanket auto-load (mỗi session start)
|
||||
|
||||
Auto-injected vào em main session khi anh mở Claude Code project:
|
||||
|
||||
| Component | Estimate KB | Always loaded? |
|
||||
|---|---|---|
|
||||
| System prompt + tool definitions | 15-20 | ✅ Always |
|
||||
| `CLAUDE.md` (project root pointer) | 1-3 | ✅ Always |
|
||||
| `docs/CLAUDE.md` (full project context) | 8-15 | ✅ Always |
|
||||
| `docs/STATUS.md` Recently Done snapshot | 30-60 (oversize warn) | ✅ Always (per CLAUDE.md priority) |
|
||||
| `docs/HANDOFF.md` brief 5 phút | 80-90 (oversize warn) | ✅ Always |
|
||||
| User memory `MEMORY.md` index | 3-5 | ✅ Always |
|
||||
| 6 skill descriptions | 3 | ✅ Always |
|
||||
| 4 sub-agent definitions + first 200 lines MEMORY each | 50-80 | ✅ Always (post CLI restart pickup model:inherit) |
|
||||
| **Tổng blanket estimate** | **~200-280 KB ≈ 50-70K tokens** | |
|
||||
|
||||
**KHÔNG auto-load (cần RAG retrieve hoặc Read direct):**
|
||||
- Session logs cũ `docs/changelog/sessions/*.md` (~30+ files cumulative)
|
||||
- Skill SKILL.md full content (chỉ description in blanket)
|
||||
- Memory user-level full content (chỉ index)
|
||||
- Source code BE/FE
|
||||
- Archive folders `.claude/agent-memory/*/archive/*`
|
||||
- Migration scripts old + DbInitializer
|
||||
|
||||
### §A3.3 — Layer 2: RAG retrieve decision tree
|
||||
|
||||
```
|
||||
Em main cần thông tin → CHỌN tool:
|
||||
|
||||
├── Cần PATTERN proven từ session cũ / cross-project?
|
||||
│ → mcp__rag-unified__search_memory("pattern X", scope="default")
|
||||
│ Vd: "per-NV admin opt-in flag pattern", "FE merge synthetic audit"
|
||||
│
|
||||
├── Đang implement feature mới — kiểm tra đã làm ở project nào trước chưa?
|
||||
│ → mcp__rag-unified__cross_project_search("feature Y")
|
||||
│ Vd: "audit recovery pattern", "Workflow N-stage state machine"
|
||||
│
|
||||
├── Cần lookup EXACT function/class/method trong source code?
|
||||
│ → mcp__rag-unified__search_code("ApproveV2Async signature")
|
||||
│ BM25-heavy, exact symbol match. NOT cho semantic question.
|
||||
│
|
||||
├── Cần GOTCHA cụ thể đã gặp?
|
||||
│ → search_memory("gotcha #48 SQLite tie-break") OR Read docs/gotchas.md direct
|
||||
│ Decision: < 5 gotcha lookup/session → Read direct. > 5 → search_memory.
|
||||
│
|
||||
├── Cần SESSION LOG cụ thể S22-S26 history?
|
||||
│ → search_memory("S23 Plan K F2 refactor") thay vì Read full session log 15-25KB
|
||||
│ Saves 80-90% tokens per lookup
|
||||
│
|
||||
├── End-of-session phát hiện NEW pattern reusable?
|
||||
│ → mcp__rag-unified__store_memory(content, tags=["pattern", "<topic>"])
|
||||
│ KHÔNG đợi monthly bootstrap — instant index
|
||||
│
|
||||
├── Pattern proven cross-project ≥ 2× use, muốn share?
|
||||
│ → mcp__rag-unified__promote_to_shared(chunk_id)
|
||||
│ (v0 stub, defer v1)
|
||||
│
|
||||
└── Daily ops, không cần cụ thể?
|
||||
→ Skip RAG, dùng blanket auto-load + Read on-demand specific files
|
||||
```
|
||||
|
||||
### §A3.4 — Token budget guidance per session
|
||||
|
||||
**Target utilization Opus 4.7 1M context:**
|
||||
|
||||
| % Used | State | Action |
|
||||
|---|---|---|
|
||||
| 0-30% (~0-300K) | 🟢 Healthy | Continue normal work |
|
||||
| 30-50% (~300-500K) | 🟢 Heavy session | OK, monitor sub-agent spawn cost |
|
||||
| 50-70% (~500-700K) | 🟡 Warning | Consider end-of-session soon, save patterns via `store_memory` |
|
||||
| 70-85% (~700-850K) | 🟠 Approach limit | End session ASAP, finalize HANDOFF, S+1 fresh |
|
||||
| > 85% (~850K+) | 🔴 Critical | Response lag + repetition. End immediately. |
|
||||
|
||||
**Em main session activity sample S27 (~5h heavy):**
|
||||
- Read full 4 MEMORY (180KB) + STATUS (60KB) + HANDOFF (90KB) + multiple skill files + session logs S25-S26
|
||||
- Write 7 PS scripts + dashboard HTML + onboarding guide (440 lines) + 4 archive files + memory NEW
|
||||
- Estimate context used: ~400-560K (40-55% utilization) — Warning state
|
||||
- Pattern: Heavy session ~5-6h → end session, S+1 fresh start
|
||||
|
||||
**Anti-pattern wasteful:**
|
||||
- ❌ Read entire `STATUS.md` (60KB) cho 1 question — use search_memory instead
|
||||
- ❌ Read tất cả session log S20-S26 (~30 files ~300KB) — use search_memory specific term
|
||||
- ❌ Read entire 4 sub-agent MEMORY (180KB) mỗi session — auto-injected first 200 lines, đủ; full Read only when explicit reference
|
||||
- ❌ Search RAG với empty/vague query ("test", "data") — return noise
|
||||
- ❌ Read full source code BE (3K LOC) cho 1 line lookup — use search_code BM25
|
||||
|
||||
### §A3.5 — 6 MCP tools examples concrete (em main daily)
|
||||
|
||||
**1. `search_memory(query, scope, top_k, use_rerank)`** — Most common
|
||||
|
||||
```python
|
||||
# Vietnamese OK
|
||||
search_memory("workflow approve V2 actor scope check")
|
||||
|
||||
# English OK
|
||||
search_memory("multi-agent setup pitfall model inherit")
|
||||
|
||||
# Specific gotcha lookup (skip Read gotchas.md full)
|
||||
search_memory("gotcha 48 SQLite tie-break multi Changelog")
|
||||
|
||||
# Cross-project default (self + shared_global)
|
||||
search_memory("Per-NV admin opt-in flag pattern", scope="default")
|
||||
|
||||
# Self-only (project-specific narrow)
|
||||
search_memory("Plan AG tree view UI", scope="self")
|
||||
```
|
||||
|
||||
**2. `cross_project_search(query, top_k)`** — Khi explore broader
|
||||
|
||||
```python
|
||||
# "Pattern X tao đã làm ở dự án nào trước chưa?"
|
||||
cross_project_search("audit recovery synthetic rows FE merge")
|
||||
cross_project_search("EF migration BACKFILL reorder discipline")
|
||||
cross_project_search("Custom Dashboard PowerShell HTML generator")
|
||||
```
|
||||
|
||||
**3. `search_code(query, file_pattern, top_k)`** — BM25 exact match
|
||||
|
||||
```python
|
||||
# Exact function name
|
||||
search_code("ApproveV2Async EnsureCanRejectV2Async")
|
||||
|
||||
# Specific TS prop
|
||||
search_code("AllowApproverEditBudget per-Level slot", file_pattern="**/*.cs")
|
||||
|
||||
# Migration name lookup
|
||||
search_code("Mig 29 RefactorAdvancedOptionsToPerLevelAndDrafterUser")
|
||||
```
|
||||
|
||||
**4. `store_memory(content, source_path, tags)`** — End-of-session NEW pattern
|
||||
|
||||
```python
|
||||
store_memory(
|
||||
content="""
|
||||
Pattern S27 NEW: NSSM Windows Service for Qdrant auto-start.
|
||||
- 7 PS scripts (install/fix/start/stop/status/dashboard/boot)
|
||||
- Service mode auto-restart on crash + survive logout
|
||||
- Gotcha: WAL lock conflict if manual qdrant.exe running → kill first
|
||||
Reusable cross-project bất kỳ multi-project shared infrastructure.
|
||||
""",
|
||||
source_path="manual/S27-nssm-pattern",
|
||||
tags=["nssm", "windows-service", "qdrant", "pattern"]
|
||||
)
|
||||
```
|
||||
|
||||
**5. `promote_to_shared(chunk_id)`** — Cross-project pattern proven
|
||||
|
||||
```python
|
||||
# v0 stub - defer v1. For now manually duplicate-index to shared via store_memory
|
||||
# (Pattern proven ≥ 2× use → manual cross-share)
|
||||
```
|
||||
|
||||
**6. `list_projects()`** — Registry overview (rare daily, common monthly audit)
|
||||
|
||||
```python
|
||||
# Check infra health
|
||||
list_projects()
|
||||
# Returns: [{project_id, collection, chunk_count, last_indexed_at}, ...]
|
||||
```
|
||||
|
||||
### §A3.6 — Best practices em main daily workflow
|
||||
|
||||
**Morning session start (5 phút):**
|
||||
```powershell
|
||||
rag-status # Check Qdrant Service + collection counts
|
||||
rag-dashboard # Visual sanity (snapshot - mỗi sáng OK fresh)
|
||||
```
|
||||
+ Spawn test sub-agent IMMEDIATELY:
|
||||
```
|
||||
Agent(subagent_type="investigator", prompt="Test reply 1 sentence")
|
||||
```
|
||||
→ Verify registry load. Nếu fail → check `feedback_subagent_setup_pitfalls.md` §4 diagnose.
|
||||
|
||||
**Trong session daily ops:**
|
||||
- **Default tool: `search_memory`** thay vì Read MD direct (saves 80-90% tokens per lookup)
|
||||
- Read direct CHỈ KHI cần edit file đó hoặc cần see full file structure
|
||||
- `cross_project_search` khi design feature mới — check proven elsewhere
|
||||
- `search_code` khi need exact symbol/function lookup
|
||||
|
||||
**End of session save NEW patterns:**
|
||||
```python
|
||||
# 1. store_memory cho mỗi pattern proven phát hiện trong session
|
||||
store_memory(content="Pattern Z chốt YYYY-MM-DD: ...", tags=[...])
|
||||
|
||||
# 2. Update HANDOFF.md với S+1 priority HIGH
|
||||
# 3. Commit + push (nếu có code changes)
|
||||
```
|
||||
|
||||
**Monthly audit cadence (re-bootstrap if drift):**
|
||||
```powershell
|
||||
python D:\.claude-rag\bootstrap.py --project <project_id> # incremental cache hit
|
||||
python D:\.claude-rag\bootstrap.py --project <project_id> --force-reindex # clean slate
|
||||
```
|
||||
|
||||
Trigger re-bootstrap khi:
|
||||
- +20 file MD docs mới sau session lớn
|
||||
- Drastic refactor MD structure (rename folders)
|
||||
- Monthly audit per rule §6.4 cadence
|
||||
- Sau khi clean curate 4 sub-agent MEMORY
|
||||
|
||||
### §A3.7 — Anti-patterns cross-project (đừng làm)
|
||||
|
||||
1. ❌ **Solo cả session vì assume agents chưa load** — VIPIX + SOLUTION_ERP S27 lesson. ALWAYS spawn test agent first.
|
||||
2. ❌ **Read full session log cũ (15-25KB each)** — use `search_memory("S## Plan X")` instead, saves 80-90% tokens
|
||||
3. ❌ **Read full 4 MEMORY.md mỗi session** — auto-injected first 200 lines blanket đủ; full Read only when explicit pattern reference
|
||||
4. ❌ **search_memory với query vague** ("test", "data", "fix") — return noise. Specific terms: "gotcha #48 SQLite tie-break", "Plan AG tree view".
|
||||
5. ❌ **Skip `store_memory` end-of-session** — pattern mất khi session crash. Save instant, không đợi monthly bootstrap.
|
||||
6. ❌ **Em main solo task qualify Implementer Case 1/2** — vi phạm directive S22 chốt BẮT BUỘC delegate. Spawn Implementer cho cookie-cutter mechanical (≥5 file independent + deterministic spec).
|
||||
7. ❌ **Heavy session > 6h không end** — context rot risk. End session + S+1 fresh.
|
||||
|
||||
### §A3.8 — Context monitoring + when to end session
|
||||
|
||||
**Em main không có exact token counter built-in** (Anthropic Claude Code CLI có thể có `/context` hoặc status bar — em check tùy version).
|
||||
|
||||
**Estimate heuristics:**
|
||||
- Số lượng files Read full: > 10 large files (>30KB each) → likely > 40% context
|
||||
- Session duration: > 5h heavy work → likely > 50% context
|
||||
- Sub-agent spawn count: 4 agents × 100K each = ~400K used by sub-agent overhead alone
|
||||
- Tool calls cumulative: > 100 tool calls likely > 50% context
|
||||
|
||||
**Signs of context full (end session ASAP):**
|
||||
- 🚨 Response lag noticeable (longer wait)
|
||||
- 🚨 Em main lặp lại logic đã reasoning
|
||||
- 🚨 Em main miss reference to earlier session context
|
||||
- 🚨 Sub-agent spawn returns wrong/incomplete results
|
||||
|
||||
**End session protocol:**
|
||||
1. `store_memory` mọi NEW pattern phát hiện trong session
|
||||
2. Update `STATUS.md` Recently Done
|
||||
3. Update `HANDOFF.md` với S+1 priority HIGH list
|
||||
4. Write `docs/changelog/sessions/YYYY-MM-DD-S##-<topic>.md`
|
||||
5. Commit + push (per project workflow)
|
||||
6. Anh restart Claude Code CLI cho S+1 fresh
|
||||
|
||||
---
|
||||
|
||||
## §A2 Cấu trúc chuẩn em main pioneer (SOLUTION_ERP) đã setup
|
||||
|
||||
> **Notes integrated từ Plan A.2 (skip bootstrap hộ, but provide structure documentation for 4 em main khác self-setup).**
|
||||
|
||||
### File tree `D:\.claude-rag\` (em pioneer SOLUTION_ERP build)
|
||||
|
||||
```
|
||||
D:\.claude-rag\
|
||||
├── bootstrap.py (150 LOC - CLI bootstrap project corpus)
|
||||
├── server.py (210 LOC - FastMCP entry, 6 tool handlers)
|
||||
├── README.md (project README)
|
||||
├── dashboard.html (generated by dashboard.ps1 - DO NOT edit manually)
|
||||
├── lib/
|
||||
│ ├── __init__.py
|
||||
│ ├── projects.py (140 LOC - auto-detect cwd, registry tracking)
|
||||
│ ├── chunking.py (120 LOC - Markdown chunking + Anthropic Contextual Retrieval prepend)
|
||||
│ ├── embed.py (140 LOC - Voyage AI wrapper, retry exponential backoff, SHA256 cache)
|
||||
│ ├── retrieval.py (230 LOC - 3-layer pipeline: Vector + BM25 + RRF + Voyage rerank-2.5)
|
||||
│ └── watcher.py (100 LOC - Watchdog file watcher, debounce 2s — defer v1 wire)
|
||||
├── scripts/
|
||||
│ ├── start.ps1 (Qdrant background hidden + health check, ASCII-only)
|
||||
│ ├── stop.ps1 (Graceful stop + verify, ASCII-only)
|
||||
│ ├── status.ps1 (6-section full report, ASCII-only)
|
||||
│ ├── dashboard.ps1 (Generate custom HTML + open browser, ASCII-only)
|
||||
│ └── boot.ps1 (Auto-boot sequence: start + dashboard, used by Startup shortcut)
|
||||
├── qdrant-bin/
|
||||
│ ├── qdrant.exe (88 MB v1.18.0 Windows native binary)
|
||||
│ ├── qdrant-v1.18.0.zip (download archive 28.3 MB)
|
||||
│ ├── .qdrant-initialized (marker file)
|
||||
│ └── config/ (Qdrant config folder, currently empty - uses defaults)
|
||||
├── data/
|
||||
│ └── qdrant-storage/ (Qdrant data dir, ~85+ MB per project bootstrap)
|
||||
├── logs/
|
||||
│ └── qdrant-YYYYMMDD.log (rotated daily)
|
||||
└── __pycache__/ (Python bytecode cache)
|
||||
```
|
||||
|
||||
### 8-step Bootstrap checklist cho em main project mới
|
||||
|
||||
```
|
||||
[ ] 1. Verify infra global ready: rag-status → 3 OK (Qdrant + MCP + Voyage)
|
||||
[ ] 2. Decide project_id (lowercase + underscore, UNIQUE cross 5 project)
|
||||
[ ] 3. Decide sensitivity: share_to_global=true/false (client confidential check)
|
||||
[ ] 4. Identify corpus_paths (default 3 + extra docs folders project-specific)
|
||||
[ ] 5. Identify exclude_paths (binary, node_modules, archive, secrets)
|
||||
[ ] 6. Identify extra_corpus (memory user-level path cho project Claude Code folder)
|
||||
[ ] 7. Write .claude/rag.json from template §4
|
||||
[ ] 8. Run: python D:\.claude-rag\bootstrap.py --project <project_id>
|
||||
[ ] 9. Verify: rag-status (see new project in [Collections] section)
|
||||
[ ] 10. Test query in Claude Code session: search_memory("test")
|
||||
```
|
||||
|
||||
### Files em pioneer ĐÃ build (KHÔNG edit cross-project)
|
||||
|
||||
| File | Content | Owner |
|
||||
|---|---|---|
|
||||
| `D:\.claude-rag\server.py` | FastMCP entry + 6 tool handlers | **Em pioneer SOLUTION_ERP** (do NOT modify per-project) |
|
||||
| `D:\.claude-rag\lib\*.py` | Shared library | **Em pioneer** (modify only via PR to em pioneer project) |
|
||||
| `D:\.claude-rag\bootstrap.py` | CLI bootstrap script | **Em pioneer** |
|
||||
| `D:\.claude-rag\scripts\*.ps1` | 5 PowerShell scripts | **Em pioneer** (em main project mới có thể customize project-specific aliases per §12) |
|
||||
| `D:\.claude-rag\qdrant-bin\` | Qdrant binary | **Shared** (Windows native v1.18.0, no Docker) |
|
||||
| `D:\.claude-rag\data\` | Qdrant storage | **Shared** (all collections live here) |
|
||||
| `<project>\.claude\rag.json` | Per-project config | **Em main project đó** (own this file fully) |
|
||||
| `dashboard.html` | Auto-generated | **dashboard.ps1 generates, DO NOT edit manually** |
|
||||
|
||||
### Cấu trúc stack chốt
|
||||
|
||||
| Component | Tool/Version | Note |
|
||||
|---|---|---|
|
||||
| Embedding | Voyage-4-large (1024-dim) | 200M tokens/month free tier |
|
||||
| Reranker | Voyage rerank-2.5 | $0.05/1K query, 20× cheaper than Cohere |
|
||||
| Vector DB | Qdrant v1.18.0 Windows native binary | No Docker, 28.3 MB binary |
|
||||
| BM25 | SQLite FTS5 (unicode61 + remove_diacritics 2) | Built-in to SQLite, no Postgres |
|
||||
| Fusion | RRF k=60 (Reciprocal Rank Fusion) | Industry standard |
|
||||
| MCP framework | FastMCP 3.3.1 stdio | Anthropic official SDK |
|
||||
| Contextual Retrieval | "From <doc_title> > <heading_path>:" prepend | Anthropic blog Sept 2024 pattern |
|
||||
| Distribution | User-level Global MCP (Approach A — 1 dev N project localhost) | NO team VPS pattern |
|
||||
|
||||
### 4 Gotcha discoveries S26-S27 (cho project khác tránh)
|
||||
|
||||
1. **Qdrant Windows binary chính thức tồn tại** - GitHub release `qdrant-x86_64-pc-windows-msvc.zip` 28.3 MB. No Docker overhead.
|
||||
2. **`claude mcp add` cần `--` separator** terminate variadic `-e` flag: `claude mcp add -s user -e "VOYAGE_API_KEY=$VK" -- rag-unified python "D:\.claude-rag\server.py"`. Em pioneer trial 5 lần fail trước khi tìm ra fix.
|
||||
3. **Qdrant batch upsert WinError 10053** với batch > 64 chunks → fix bằng `UPSERT_BATCH = 64` trong `lib/retrieval.py`.
|
||||
4. **Qdrant Windows binary KHÔNG bundled Web UI static files** (S27 discovery 2026-05-22) — `qdrant.exe` log warn `Static content folder for Web UI './static' does not exist` + `http://localhost:6333/dashboard` returns 404. **Fix:** Download separate `dist-qdrant.zip` từ https://github.com/qdrant/qdrant-web-ui/releases/latest (6.59 MB v0.2.12) + extract vào `D:\.claude-rag\qdrant-bin\static\` (flatten `dist/` subfolder up to `static/` root level so `index.html` ở `static\index.html`). Restart Qdrant → native dashboard work HTTP 200 "UI | Qdrant".
|
||||
```powershell
|
||||
$url = "https://github.com/qdrant/qdrant-web-ui/releases/download/v0.2.12/dist-qdrant.zip"
|
||||
Invoke-WebRequest -Uri $url -OutFile "D:\.claude-rag\qdrant-bin\dist-qdrant.zip"
|
||||
Expand-Archive -Path "D:\.claude-rag\qdrant-bin\dist-qdrant.zip" -DestinationPath "D:\.claude-rag\qdrant-bin\static" -Force
|
||||
# Flatten dist/ up to static/ root:
|
||||
Get-ChildItem "D:\.claude-rag\qdrant-bin\static\dist" | Move-Item -Destination "D:\.claude-rag\qdrant-bin\static" -Force
|
||||
Remove-Item "D:\.claude-rag\qdrant-bin\static\dist" -Force
|
||||
rag-restart
|
||||
```
|
||||
|
||||
### PowerShell gotcha (per memory `feedback_node_cicd.md` cousin)
|
||||
|
||||
- **ASCII-only trong .ps1 source** - PowerShell 5.1 fragile với UTF-8 BOM. Em pioneer trial fail 2x với `✓ → âœ"` mangling. Replace ALL unicode trong code source bằng ASCII (`[OK]`, `[FAIL]`, `->`, `*`, `!`). HTML output unicode OK (file save UTF-8 + browser charset declare).
|
||||
- **Bash shell KHÔNG inherit User-scope env var từ PowerShell parent** - workaround: `VK=$(powershell -NoProfile -Command "...")` mỗi Bash command + `export VOYAGE_API_KEY="$VK"`
|
||||
|
||||
---
|
||||
|
||||
## Cross-ref
|
||||
|
||||
- `feedback_rag_distributed_ownership.md` (memory user-level) - Decision Approach B + Option 4a rationale full
|
||||
- `feedback_rag_hybrid_pattern.md` (memory user-level) - Stack architecture chốt S26 + 7 gotcha discoveries
|
||||
- `feedback_multi_agent_setup.md` (memory user-level) - 4 sub-agent decision gate
|
||||
- `feedback_md_compact_narrative.md` (memory user-level) - §6.5 KEEP narrative rule cho bootstrap chunking strategy
|
||||
- `.claude/agents/README.md` (SOLUTION_ERP) - master coordination guide template cho project mới adopt
|
||||
- Anthropic Contextual Retrieval - https://www.anthropic.com/news/contextual-retrieval
|
||||
- FastMCP docs - https://fastmcp.com
|
||||
- Qdrant Windows release - https://github.com/qdrant/qdrant/releases
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
- **2026-05-22** v1.0 chốt S27 em main SOLUTION_ERP + bro pqhuy. Initial release. 13 sections + §A2 cấu trúc chuẩn em pioneer (replace Plan A.2 skip bootstrap hộ).
|
||||
- Future versions update khi 4 em main project khác feedback usage real.
|
||||
Reference in New Issue
Block a user