vietreport-admin/solution-erp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[CLAUDE] Docs: adopt Harness-11 engine tự-bảo-trì (3-workflow audit→implement→review)

Browse Source 
- engine-doc canonical docs/governance/harness-11-engine.md (PHẦN A/B/C/D + 3-tier D5/D6/D7 + one-direction-lock D8 + CAVEAT honest)
- scripts/governance-detectors.ps1 (C1 broken-pointer + C2/B3 staleness + C3 vocab-fork + C4 self-exclusion + C5 resolve, NO-API DÒ+FLAG-only, runtime-proven, FP-refined 59→27)
- scripts/memory-archive-gate.ps1 (PHẦN A: hysteresis 0.85 + keep-floor 5 + 2-strike + A7 NO-API L1-eval) + budget.json archive_gate
- B1 ×11 count→canonical-pointer (root CLAUDE.md, ef-core/dep-audit SKILL, skills/README, docs/CLAUDE.md) — drift mig53→55/test306→339/gotcha68→69 RESOLVED + ef-core +Mig 54/55 rows
- cadence-wire D1 session-start §2.1.3 + D2 session-end §L.b(c) + agents/README Upgrade S75
- run-trace TRACKED: audit wf_7fdc3bd5-930 / implement wf_c5e5844e-7c1 / review wf_d7ca1ff8-942 (REVIEW PASS, completeness-gate ĐẠT)
- check-email AI_INFRA harness-11 (verify whole-file 318ff9f6 + body b2a2fc1c) + adap-report + outbox report (body 7fa1b53a)
- 0 production code; state THẬT giữ nguyên (Mig 55 · 88 bảng · 339 test · gotcha 69 · menu 54 · bundle BYF5vIMJ/CB-tiRxd)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
pqhuy1987
2026-06-18 20:44:26 +07:00
parent 462bfbc854
commit e70c0462d7
25 changed files with 1452 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/CLAUDE.md
View File

@ -62,12 +62,12 @@ SOLUTION_ERP/
│ ├── PROJECT-MAP.md bản đồ tổng quan
│ ├── rules.md coding conventions
│ ├── architecture.md layered + PE §9 + Budget §10 + Testing §11
│ ├── gotchas.md 58 pitfall đã gặp
│ ├── gotchas.md pitfall đã gặp (số → docs/STATUS.md)
│ ├── forms-spec.md 8 form catalog + RG-001
│ ├── workflow-contract.md 9 phase HĐ + role matrix
│ ├── database/
│ │ ├── database-guide.md conventions + migration workflow
│ │ └── schema-diagram.md ERD 93 bảng (+§11 PE +§12 Budget +§13 PEDeptOpinions +§14 Contract V2 LevelOpinions; §16+ Mig 27-48 pending)
│ │ └── schema-diagram.md ERD 88 bảng (+§11 PE +§12 ~~Budget~~ DROP +§13 PEDeptOpinions +§14 Contract V2 LevelOpinions; §16+ Mig 27-55 pending)
│ ├── flows/ 6 sequence diagram (auth/permission/contract/form/sla + PE ref architecture)
│ ├── guides/ setup, cicd, deploy, runbook, security
│ ├── changelog/

46
docs/governance/adap-reports/2026-06-18-Governance-harness-11.md Normal file
View File

@ -0,0 +1,46 @@
# adap-report — Harness-11 (engine bộ-nhớ-và-governance TỰ-BẢO-TRÌ)
- **id:** 2026-06-18-Governance-harness-11
- **source broadcast:** `ai_infra/broadcasts/outbox/all/2026-06-18-Governance-harness-11.md` (+ checklist `2026-06-18-Governance-checklist-harness-11.md`) · directed heads-up `outbox/se/2026-06-18-ai_infra-to-se-harness-11-available.md` (inbox verify ✓ whole-file `318ff9f6` + body `b2a2fc1c`)
- **adopted by:** se (SOLUTION_ERP) · **session:** S75 · **date:** 2026-06-18
- **protocol:** Harness-9 PART-2 mandate = 3 workflow tách biệt + report-with-run-id
- AUDIT `wf_7fdc3bd5-930` (4× investigator-codebase) → IMPLEMENT `wf_c5e5844e-7c1` (2× general-purpose script ∥ + em-main MD cluster) → REVIEW `wf_d7ca1ff8-942` (3× reviewer adversarial)
- **run-trace:** `.claude/workflows/runs/{2026-06-18-h11-audit,-h11-implement,-h11-review}/` (TRACKED FLAT)
## VERDICT: ✅ ADOPTED — completeness-gate ĐẠT (B+C+D function-floor đủ-trọn), REVIEW PASS 0-blocker
H11 = chuẩn-hoá lại cái SE đã thể-hiện MỘT PHẦN (Harness-9 L2-recovery + Harness-10 run-trace + single-writer). AUDIT xác nhận: nhiều cấu-phần PRESENT sẵn, GAP thật = **PHẦN C (3 detector-script)** + **B1/B3 (derived→canonical pointer + freshness)** + **D5-D8 (3-tier + one-direction-lock chưa nhãn-hoá)**.
## Nấc theo PHẦN (trung-thực executed-file vs runtime · mechanized vs convention)
| PHẦN | Trạng-thái | Nấc |
|---|---|---|
| **A** (hot-mem auto-archive 🟡) | A1-A3 PRESENT sẵn (H9) · A4 hysteresis 0.85 / A5 keep-floor 5 / A6 2-strike / A7 NO-API L1-eval = **MỚI** | `memory-archive-gate.ps1` runtime-proven (A7 186/186 pointer-resolve, A4/A5 DRY-RUN observed). A6 2-strike = executed-file (cần 2 -Apply mới đủ runtime). budget.json `archive_gate` params. mechanized DRY-RUN planner; MOVE thật = em-main (D5 semantic-null). |
| **B** (derived→canonical 🔴) | B1 ✅ (11 edit count→pointer `docs/STATUS.md`) · B2 ✅ · B3 ✅ (=C2) · B4 ✅ | B1 landed + **drift THẬT root CLAUDE.md RESOLVED** (post-B1 re-run: 3 TP-flag mig53/test306/gotcha68 GONE). runtime-proven. |
| **C** (3 grep detector 🔴 MANDATE) | C1/C2/C3 + C4 + C5 = **MỚI build** | `governance-detectors.ps1` runtime-proven: bắt drift thật + C4 0-self-match + C5 100%-resolve + NO-API + 0-auto-write. **Refinement post-R2:** 59→27 flag (C2 context-skip + C1 `[-_]` normalize). |
| **D** (orchestration 🔴) | D1/D2 wired MỚI (session-start §2.1.3 + session-end §L.b(c)) · D3/D4/D9/D10/D11 PRESENT-mạnh sẵn · **D5/D6/D7 3-tier + D8 one-direction-lock = MỚI codify** | mix. D4/D9/D11 mechanized (hmw.js:76 THROW · store_memory strip · md5sum byte-0-loss). engine-doc `docs/governance/harness-11-engine.md` = canonical. |
## Tailoring (SE-specific)
- Detector = **PowerShell .ps1** (khớp `scripts/*.ps1` + `measure-agent-memory.ps1` precedent), KHÔNG bash — chạy `powershell.exe -File`.
- A = DRY-RUN planner (in kế-hoạch, người duyệt) thay auto-move — vì MOVE đụng memory canonical (D6/D9 single-writer).
- Canonical = `docs/STATUS.md` CURRENT-STATE table (nguồn-chuẩn state); detector cross-check disk (mig=`ls Migrations/*.cs`, gotcha=max `### N`).
- Engine-doc TỰ-NÓ B1-compliant (0 hardcoded volatile-count) — dogfood.
## Honest caveats (KHÔNG nói quá)
- **no-OS-hook:** detector/gate chạy TRONG thân session-start/end body, em-main kích — DÒ tự-động, SỬA+GÁC dựa người. KHÔNG fully-autonomous.
- **auto-WRITE luật = CỐ Ý chưa làm** (defer ≥2 sự-cố thật, hiện 0). Mọi thứ chạm luật/copy = chỉ DÒ+FLAG.
- **C2 residual ~11 FP** (module-local "4 bảng Budget" historical, "1 migration" prose revert-cmd) = soft-net chấp-nhận (LOW/MED advisory exit-0, self-documented). FP-rate cắt từ ~89%→~40% sau refinement.
- **C1 13 wikilink-dangling = REAL pre-existing** memory-index drift (genuinely-missing + cross-scope) — engine SURFACE đúng; fix từng cái = chore riêng, KHÔNG block adap.
- **C3 console mojibake VN-variant** = cosmetic Bash-capture (match THẬT đúng — gotcha #30 code-point builder).
- **A6 2-strike** = executed-file logic (runtime cần 2 lần -Apply); **detector stateless** nên 2-strike-for-flag là convention em-main, KHÔNG mechanized-per-detector (KHÔNG over-claim).
## Reverse-findings (đề-xuất ngược AI_INFRA)
1. **gotcha #30 = floor-class lesson cho mọi sister Windows:** detector .ps1 NO-API tiếng-Việt BẮT BUỘC build token từ Unicode code-point (`[char]0x1EAB`...) — `powershell.exe -File` decode .ps1 UTF-8-no-BOM bằng ANSI-1252 → literal Việt mojibake → detector MÙ token bản-địa (vòng-1 thiếu 18/71 flag). Đề-xuất thêm vào H11 checklist PHẦN C như cảnh-báo encoding cho dự-án non-ASCII.
2. **C2 count-token grep = soft-net FP cao bản-chất** (~89% raw) — cần context-skip (table-row + version-prefix + historical-marker) để dùng được; đề-xuất H11 checklist note FP-mitigation pattern.
3. **B1 + C2 = cặp bổ-trợ:** B1 (pointer-conversion) gỡ copy → C2 chỉ gác doc copy MỚI. Sau B1, C2 trên doc đã-pointer = no-op (đúng ý-đồ). Xác-nhận thiết-kế này khớp intent H11.
## Evidence
- 3 run-id (trên) · run-trace synthesis 3 file `*-synthesis.md` (audit/implement/review) · ledger `runs/_ledger.md` 3 row CLOSE.
- Detector runtime: exit 0, 27 flag post-refinement (C4 0-self-match, NO-API grep 0-hit, 0-auto-write git pre==post).
- Archive-gate runtime: A7 186/186 pointer-resolve, A4/A5 DRY-RUN observed.
- State THẬT GIỮ NGUYÊN (0 production code): Mig 55 · 88 bảng · 339 test · gotcha 69 · menu 54 · bundle `BYF5vIMJ`/`CB-tiRxd`.

84
docs/governance/harness-11-engine.md Normal file
View File

@ -0,0 +1,84 @@
# Harness-11 — Engine bộ-nhớ-và-governance TỰ-BẢO-TRÌ (SE canonical)
> **Adopt S75 (2026-06-18)** — AI_INFRA broadcast `2026-06-18-Governance-harness-11` + checklist (inbox `broadcasts/inbox/ai_infra/`). Áp qua 2 workflow (IMPLEMENT `wf_c5e5844e-7c1` + REVIEW) per mandate ⑤. adap-report → `docs/governance/adap-reports/2026-06-18-Governance-harness-11.md`.
>
> 🔑 **Đây là CANONICAL cho engine governance của SE.** Doc khác (`agents/README`, `session-start/end`) **TRỎ về đây**, KHÔNG copy luật (B1 dogfood — một-chỗ-đổi).
>
> 🔑 **Nguyên-lý lõi:** "tự-bảo-trì" = luôn-TỰ-BIẾT khi có drift (detector tự-động, NÊU-CỜ ngay) **CHỨ KHÔNG tự-viết-lại** nội-dung/luật. DÒ tự-động; SỬA do người-chủ-trì (em-main) làm trên cờ. **BAR-KHÔNG-HẠ = một-người-ghi (single-writer)** — "tự-bảo-trì" TUYỆT-ĐỐI KHÔNG miễn-trừ chốt này.
---
## Bản-đồ artifact (engine SE)
| Cấu phần | Artifact | Nấc |
|---|---|---|
| PHẦN A — hot-mem auto-archive | `scripts/memory-archive-gate.ps1` + `.claude/agent-memory/memory-budget.json` (`archive_gate` params) + `session-end.md §L.b` | mechanized DRY-RUN planner + convention trigger (no-OS-hook) |
| PHẦN B — derived→canonical + freshness | luật B1 (dưới) + `scripts/governance-detectors.ps1` (C2 staleness) | detector mechanized + fix gated qua người |
| PHẦN C — 3 grep detector | `scripts/governance-detectors.ps1` (C1/C2/C3 + C4 self-exclusion + C5 resolve-condition) | mechanized NO-API, DÒ+FLAG-only |
| PHẦN D — orchestration | doc này (3-tier + 1-direction) + `session-start.md`/`session-end.md`/`ultra-on.md` cadence + `hmw.js` checkpoint | mix mechanized + convention |
| Canonical state (nguồn-chuẩn) | `docs/STATUS.md` CURRENT STATE table | — |
---
## PHẦN A — Hot-mem auto-archive by budget (🟡 TAILORED)
SE-present từ Harness-9 (L2 archive byte-exact + `_INDEX` substring-pointer + gist). Harness-11 thêm 3 tham-số chống-thrash + standing-gate:
- **A1 byte-gate @session-end** — `memory-archive-gate.ps1` đo byte mỗi `agent-memory/<sub>/MEMORY.md` vs cap. (Trigger = `session-end.md §L.b` convention người-kích — engine no-OS-hook.)
- **A2 additive MOVE** — bản-cũ-nhất → `archive/<YYYY-MM>.md`, NEVER overwrite (runtime-proven `h910-curate`: +N -0 byte-exact).
- **A3 `_INDEX` pointer-only** — 1 dòng/bản-ghi, con-trỏ substring sha-keyed (`memory-budget.json:19`).
- **A4 hysteresis** — dồn tới DƯỚI `low_watermark = 0.85 × cap` (không dừng ở vạch). [param `archive_gate.low_watermark_ratio`]
- **A5 keep-floor** — luôn giữ ≥ `keep_floor_entries` (5) bản-ghi gần nhất, không vét sạch.
- **A6 2-strike** — chỉ ĐỀ-XUẤT dồn khi over-cap ở 2 lần kiểm liên-tiếp (`strike_threshold`), chống alert-fatigue.
- **A7 NO-API L1-eval** — sau dồn: (i) resolve-con-trỏ (mọi pointer `_INDEX` grep-định-vị được trong archive) + (ii) byte-0-loss (tổng trước = sau). grep + measure only, KHÔNG API.
> 🟡 Con-số (cap 25600, 0.85, 5, 2) = TAILOR. SE chọn DRY-RUN planner (in kế-hoạch + người duyệt) thay auto-move — vì move = đụng memory canonical (D6/D9, không tự-ghi).
## PHẦN B — Derived-doc TRỎ canonical, KHÔNG copy (🔴 FUNCTION-FLOOR)
- **B1 — derived TRỎ canonical:** tài-liệu-dẫn-xuất (`CLAUDE.md` root/docs, `skills/*/SKILL.md`, `agents/README`) KHÔNG copy volatile-token (mig#·test#·gotcha#·table#·bundle-hash·model) — **TRỎ `docs/STATUS.md`** (canonical). Lý-do: một-chỗ-đổi-N-chỗ-drift = nguồn drift #1 (chứng-minh sống: root CLAUDE.md kẹt mig 53 qua S70-S74).
- **B2 — giữ readability:** dữ-kiện-ổn-định (tech-stack, module-table, convention) GIỮ inline đọc-được; CHỈ pointer cái HAY-đổi (tránh pointer-soup). Exemplar sẵn: `docs/PROJECT-MAP.md` (0 count-token, 241 dòng).
- **B3 — freshness-DETECT:** `governance-detectors.ps1` (detector C2) grep volatile-token derived vs canonical → FLAG lệch (KHÔNG tự sửa).
- **B4 — fix GATED qua người:** FLAG → em-main xem diff → ghi (single-writer). KHÔNG đường tự-ghi-thẳng. (Mechanized backstop: git-diff commit-gate + run-folder TRACKED.)
## PHẦN C — 3 bộ dò grep tất-định (🔴 FUNCTION-FLOOR MANDATE)
Tất cả ở `scripts/governance-detectors.ps1` — NO-API (grep/measure only), **DÒ+NÊU-CỜ-only** (không tự sửa). Chạy @session-start (D1) báo cờ.
- **C1 broken-pointer** — grep ref nội-bộ (gotcha #N > max · `[[wikilink]]` target thiếu) → FLAG dangling.
- **C2 derived-staleness** (= B3) — count-token derived vs STATUS canonical (+ cross-check disk: mig = `ls Migrations/*.cs` excl Designer/Snapshot; gotcha = max `### N.` trong gotchas.md) → FLAG mismatch + 'canonical-itself-stale' nếu STATUS lệch disk.
- **C3 vocab-fork** — alias-set (seed: `wave-folder↔run-trace`, `Dự trù PRO↔Ngân sách PRO`, `two-tier↔all-inherit`) → FLAG khi ≥2 biến-thể cùng sống.
- **C4 self-line exclusion** 🔴 — detector loại path tự-mô-tả (`governance-detectors.ps1`, `harness-11-engine.md`, `broadcasts/**`, `runs/**`) TRƯỚC khi FLAG → 0 self-match.
- **C5 resolve-condition** 🔴 — mỗi FLAG kèm `resolve: <điều-kiện-gỡ-cờ>`. 2-strike anti-repeat = convention em-main áp (detector stateless per-run; KHÔNG over-claim mechanized-2-strike cho detector).
## PHẦN D — Engine điều-phối (🔴 FUNCTION-FLOOR)
### D.1 — Bảng-nhịp 4-lớp (SE-present, cadence-file)
- **D1 session-start = DÒ+BÁO** — `session-start.md §2.1.1` monitor RE-REPORT + §2.1.2 budget-audit + **chạy `governance-detectors.ps1` báo cờ** (KHÔNG sửa). INFORM-only.
- **D2 session-end = BẢO-TRÌ+archive** — `session-end.md §L` (byte-gate A + harvest-GATE 5-trục + gác-cờ chưa xử-lý).
- **D3 per-turn = chắt-lọc-APPEND** — harvest-LIỀN sau mỗi fan-out (`ultra-on.md` P3, C4 primary), qua em-main.
- **D4 threshold = workflow-gate** — chạm hệ-trọng → bắt qua Workflow (`hmw.js:76` checkpoint THROW = mechanized tripwire). run-id = bằng-chứng.
### D.2 — Tách-an-toàn 3-tầng (🔴 NHÃN-HOÁ EXPLICIT — đây là chuẩn-hoá H11)
> 🧪 **Phép-thử-ranh-giới tất-định:** hỏi "thao-tác này có git-diff vô-hại-ngữ-nghĩa không?" → CÓ = tầng AUTO; chạm prose/luật/con-trỏ/thẩm-quyền/copy = tầng DÒ+FLAG. KHÔNG tin nhãn "máy-móc thôi mà" — xét git-diff THẬT.
| Tầng | Cái gì | Đường-đi |
|---|---|---|
| **D5 — AUTO (semantic-null)** | dồn-archive ADDITIVE (byte-0-loss) · dựng-lại `_INDEX` · APPEND-chắt-lọc gist · đo-byte | tự-động OK (có A7 NO-API gate bảo-chứng) |
| **D6 — DÒ + NÊU-CỜ** | mọi thứ chạm prose/luật/con-trỏ-mục/thẩm-quyền/copy-chéo (3 detector C + monitor H1/H2) | chỉ FLAG → em-main soạn bản sửa (KHÔNG nhánh tự-ghi) |
| **D7 — OWNER-APPROVE** | đổi-luật · đổi-thẩm-quyền · ghi-lan derived · đổi-tên-khái-niệm · nâng-guard chính-thức | anh (project-owner) duyệt trước hiệu-lực |
### D.3 — Bốn chốt chống-tự-hỏng
- **D8 khoá-chiều 1-CHIỀU** 🔴 (codify mới H11) — DÒ chỉ đi **canonical → derived** (bắt derived cũ). **TUYỆT-ĐỐI KHÔNG** lấy giá-trị từ derived ghi ngược canonical. (Vd: detector đọc STATUS so root CLAUDE.md; KHÔNG bao giờ đọc root CLAUDE.md ghi vào STATUS.)
- **D9 chỉ-APPEND single-writer** 🔑 BAR-KHÔNG-HẠ — mọi ghi-bộ-nhớ = APPEND qua em-main; KHÔNG sub tự ghi đè memory-chính/luật. Mechanized: `store_memory` strip mọi sub (runtime S48 0/8) + hmw.js SCHEMA return-delta-only.
- **D10 ghi qua file-tool only** — Write/Edit, KHÔNG shell-append (tránh mojibake/$-expansion = gotcha #61). hmw.js:111 cấm Bash-write MD. (convention — Bash residual chưa block cứng.)
- **D11 archive = MOVE-không-XOÁ** — byte 0-loss (md5sum/grep-Fxf artifact `_ledger.md:14`).
---
## CAVEAT (trung-thực — đọc trước khi tự nhận "đã tự-bảo-trì")
- **No-OS-hook:** detector + gate chạy TRONG thân session-start/end body do em-main kích — KHÔNG fully-autonomous. Đúng mức: **DÒ tự-động + toàn-diện; SỬA + GÁC dựa người-chủ-trì.**
- **Auto-WRITE luật/copy = MỐI-NGUY #1, CỐ Ý CHƯA LÀM** — defer tới ≥2 sự-cố thật mà thủ-công thất-bại (hiện 0). Chọn nhánh chỉ-DÒ-NÊU-CỜ cho mọi thứ chạm luật/copy (1-sửa-sai → N-chỗ-sai + phá hash broadcast đóng-băng).
- **Single-writer bar-không-hạ** — cám-dỗ "để nó tự sửa cho nhanh" phải dừng trước chốt D9.
- **Detector = LƯỚI giảm-sót, KHÔNG khoá-cứng** — bắt @đầu/đóng-phiên (theo nhịp); giữa 2 nhịp có khoảng-mù. Phòng-thủ-nhiều-lớp, không bảo-đảm tuyệt-đối.
- **Nấc dogfood:** A2/A3/D4/D9/D11 = SE runtime-mechanized SẴN (H11 = chuẩn-hoá). C1-C3 + B3 + memory-archive-gate = MỚI build S75. D5-D8 + B1 = nhãn-hoá/codify cái ngầm-có. Phân-định 'detector viết-thành-lệnh' (executed-file) ≠ 'đã chạy-quan-sát' (runtime).