[CLAUDE] Infra: adopt AI_INFRA HMW-governance broadcast — ultra-on/off toggle + hmw.js checkpoint-gate + memory-safety (S49)
adap-apply 2026-06-03-Agent-ultracode-hmw-mem-governance (reviewer_gate PASS). PROJECT-FIT=ADOPT tailored: SE 8-agent roster. nac=executed-file (verified-pending restart+spawn-test). - T1/T2 toggle: .claude/commands/ultra-on.md + ultra-off.md; marker .claude/hmw-mode.on gitignored (T2 non-negotiable). - T3: session-start BUOC 0.5 reads marker -> reports ON/OFF. - S2/S3/S4: .claude/workflows/hmw.js P2 fan-out — checkpointApproved throw (mechanized), args JSON.parse-guard, role-whitelist fail-soft, VALID_ROLES=8 SE agents, sub-no-spawn-sub, return schema findings+memoryDelta 4-field (R1). - M1-M5: B1 slice-inject / M2 return-delta-only / B3 single-writer append-only / B2 harvest-lien / M5 store_memory-strip re-verified intact (0 tools-grant). - agents/README.md +HMW governance section (VALID_ROLES source-of-truth) + adap-report 5-field LOCK. Test 181 unchanged (no .cs/.tsx). CI-skip (all .md/.js/.gitignore). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
pqhuy1987
@ -139,6 +139,21 @@ All 7 agent có **4 RAG-READ MCP**: `search_memory` + `search_code` (BM25, prefe
|
||||
|
||||
---
|
||||
|
||||
## 🚦 HMW-mode — Workflow fan-out governance (S49, broadcast `ultracode-hmw-mem-governance`)
|
||||
|
||||
> Áp dụng KHI chạy **Workflow runtime fan-out** (`.claude/workflows/hmw.js`). Vận hành thường (Agent-tool spawn lẻ / parallel-trong-1-message) KHÔNG đổi — decision-tree trên vẫn chuẩn. Toggle: `/ultra-on` · `/ultra-off`.
|
||||
|
||||
- **Toggle 2-lệnh = on-ramp DUY NHẤT (T1/T2):** `/ultra-on` tạo marker `.claude/hmw-mode.on` (gitignored) + vào mode · `/ultra-off` xóa. Marker = single-source-of-truth, persist qua session/compact. `/session-start` đọc marker → BÁO ON/OFF (T3).
|
||||
- **Keyword = QUYỀN, KHÔNG lệnh (T4):** "workflow"/"ultracode" mở quyền hỏi, KHÔNG auto-run. Mode-OFF + "chạy workflow" → TỪ CHỐI + nhắc `/ultra-on`. CẤM native `/effort ultracode`. *(Bài học 515K-token false-trigger.)*
|
||||
- **Scope (S1):** Workflow fan-out CHỈ repo SOLUTION_ERP — KHÔNG fan-out repo/corpus khác.
|
||||
- **Checkpoint (S2):** `hmw.js` **throw** nếu `checkpointApproved≠true` (mechanized tripwire anti-accidental). Em main BÁO {số agent·vai·task} @inform → set cờ → fan-out (KHÔNG chờ confirm từng lần; marker-ON=consent). Sub KHÔNG spawn sub (S3).
|
||||
- **VALID_ROLES (8 — whitelist `hmw.js`):** `investigator-codebase` · `investigator-api` · `implementer-backend` · `implementer-frontend` · `test-specialist` · `reviewer` · `cicd-monitor` · `frontend-designer`. Role lạ → default subagent + WARN (fail-soft, S4c).
|
||||
- **Memory governance (M1–M5 + R1):** B1 slice-inject (agent ← slice MEMORY của đúng vai qua `args`) · M2 return-delta-only (`memoryDelta{task,verdict,learned,surprise}`) · B3 lead single-writer VERIFY→APPEND-only (no-overwrite-unverified) · B2 harvest-LIỀN sau mỗi workflow vào `agent-memory/<role>` · M5 `store_memory` strip (đã S47). **Containment = defense-in-depth** (git-diff + Qdrant chunk-count post-P2), KHÔNG allowlist đơn-độc (G-015: sub vẫn giữ Bash/Write — KHÔNG "read-only").
|
||||
|
||||
> Floor T/S/M/R đầy đủ → `.claude/commands/ultra-on.md`. adap-report → `docs/governance/adap-reports/2026-06-03-Agent-ultracode-hmw-mem-governance.md`.
|
||||
|
||||
---
|
||||
|
||||
## 💾 Memory discipline
|
||||
|
||||
Each agent `.claude/agent-memory/<name>/MEMORY.md` persistent diary. Spawn auto-inject first 200 lines/25KB. Update BEFORE return (BẮT BUỘC, entry ≤ 1.5K chars). 8 folder: investigator-codebase · investigator-api · implementer-backend · implementer-frontend · test-specialist · reviewer · cicd-monitor · frontend-designer.
|
||||
|
||||
@ -16,6 +16,14 @@ Em main PHẢI echo **TOÀN BỘ nội dung command body này** (đầy đủ Ph
|
||||
2. Em proceed execute Phase 1 → 3 sequential ngay
|
||||
3. Anh user điều chỉnh **cuối session** nếu cần thay đổi nội dung command (KHÔNG mid-flow interrupt)
|
||||
|
||||
## 📋 BƯỚC 0.5 — HMW-mode marker check (T3 — broadcast `ultracode-hmw-mem-governance`)
|
||||
|
||||
Em main đọc `.claude/hmw-mode.on` → **BÁO ngay đầu response** (anh khỏi quên đang ở mode đốt-token):
|
||||
- **Marker TỒN TẠI** → **🔥 HMW-mode = ON** — task LỚN sẽ chạy Workflow `hmw` fan-out theo `/ultra-on` (đốt-token cao). Gõ `/ultra-off` để tắt.
|
||||
- **Marker KHÔNG có** → **HMW-mode = OFF** — vận hành thường (Agent-tool spawn lẻ / solo theo `agents/README.md`). Workflow fan-out chỉ chạy sau `/ultra-on`.
|
||||
|
||||
> 🚦 **T4:** keyword "workflow"/"ultracode" (câu anh / reminder harness) = **QUYỀN hỏi, KHÔNG phải lệnh**. Mode-OFF + "chạy workflow" → em **TỪ CHỐI + nhắc gõ `/ultra-on`**, KHÔNG tự chạy. CẤM native `/effort ultracode`.
|
||||
|
||||
## Phase 1 — READ (load context)
|
||||
|
||||
Đọc theo thứ tự, KHÔNG skip:
|
||||
|
||||
11
.claude/commands/ultra-off.md
Normal file
11
.claude/commands/ultra-off.md
Normal file
@ -0,0 +1,11 @@
|
||||
---
|
||||
description: TẮT HMW-mode SOLUTION_ERP — về vận hành thường (Agent-tool spawn lẻ / solo theo agents/README decision-tree). Cặp với /ultra-on.
|
||||
---
|
||||
|
||||
# /ultra-off — TẮT HMW-mode (SOLUTION_ERP)
|
||||
|
||||
> Cặp với **`/ultra-on`**. 🔴 restart Claude Code nếu vừa tạo (no hot-reload).
|
||||
|
||||
Em main: **xóa marker** `.claude/hmw-mode.on` (Remove-Item; không có → "đã tắt sẵn") + **thoát HMW-mode** → task chạy **vận hành THƯỜNG** (Agent-tool spawn theo `.claude/agents/README.md` decision-tree / solo). `/session-start` kế báo **OFF**. Workflow fan-out chỉ chạy lại khi `/ultra-on` (deliberate on-ramp — KHÔNG consent-miệng, KHÔNG keyword auto-run).
|
||||
|
||||
> 🧠 **Ký ức GIỮ NGUYÊN:** memory đã harvest các lần HMW trước KHÔNG bị xóa (B3 append-only — memory là tài sản). Tắt mode chỉ dừng *chạy mới*, không đụng *đã lưu*.
|
||||
50
.claude/commands/ultra-on.md
Normal file
50
.claude/commands/ultra-on.md
Normal file
@ -0,0 +1,50 @@
|
||||
---
|
||||
description: BẬT HMW-mode SOLUTION_ERP — task LỚN chạy Workflow fan-out (8-agent roster) + sub giữ ký ức slice + verify-before-memory-write (no-overwrite-unverified) + harvest LIỀN sau mỗi workflow. /ultra-off để tắt. Gõ = anh CONSENT chạy Workflow (deliberate on-ramp).
|
||||
argument-hint: (trống = bật mode · hoặc kèm task lớn đầu tiên)
|
||||
---
|
||||
|
||||
# /ultra-on — BẬT HMW-mode (SOLUTION_ERP)
|
||||
|
||||
> Cặp **`/ultra-off`**. 🔴 restart Claude Code sau khi tạo/sửa (command `.md` no hot-reload).
|
||||
> Gõ lệnh này = **CONSENT chạy Workflow fan-out** · scope **CHỈ repo SOLUTION_ERP** (S1 — KHÔNG fan-out repo/corpus khác) · **same-model** Opus 4.8 inherit mỗi agent.
|
||||
> **Mode persist qua marker:** `/ultra-on` → em main tạo `.claude/hmw-mode.on` (Write) + vào mode → SỐNG qua session/compact. `/ultra-off` xóa. **`/session-start` đọc marker → BÁO anh ON/OFF** (khỏi quên đang ở mode đốt-token). marker = source-of-truth · **gitignored** (KHÔNG commit — tránh mode kẹt-ON khi clone = on-ramp ungoverned).
|
||||
|
||||
**Task đầu (nếu có):** $ARGUMENTS
|
||||
|
||||
## 🚦 Keyword = QUYỀN, KHÔNG phải LỆNH (T4 — bài học 515K-token false-trigger)
|
||||
- Chữ "workflow" / "ultracode" trong câu anh HOẶC trong reminder harness = **MỞ QUYỀN hỏi** (eligibility-to-ask), **KHÔNG** auto-run Workflow.
|
||||
- Mode-OFF + anh nói "chạy workflow" → em main **TỪ CHỐI + nhắc anh gõ `/ultra-on`**, KHÔNG tự chạy.
|
||||
- 🔴 CẤM dùng native `/effort ultracode` (nó auto-author+run workflow MỌI task — KHÔNG checkpoint / KHÔNG memory-harvest / KHÔNG scope-guard = ngược thiết kế). HMW = home-built orchestrator-workers, **marker-gated**.
|
||||
|
||||
## Phân loại (em main mỗi task)
|
||||
- **HMW (LỚN):** fan-out nhiều file/nguồn — sweep · audit · cross-stack review · mass migration · multi-source research. Số task THOẢI MÁI (harness queue theo slot, KHÔNG cap cứng) · spawn **ĐÚNG VAI** (`agentType` ∈ VALID_ROLES; role lạ → default subagent + cảnh báo).
|
||||
- **Thường (nhỏ):** <30min · 1–2 file · hỏi-đáp → Agent-tool spawn lẻ / solo theo `.claude/agents/README.md` decision-tree, KHÔNG HMW.
|
||||
|
||||
## VALID_ROLES (roster SOLUTION_ERP — 8 sub)
|
||||
`investigator-codebase` · `investigator-api` · `implementer-backend` · `implementer-frontend` · `test-specialist` · `reviewer` · `cicd-monitor` · `frontend-designer`
|
||||
> Role lạ ∉ list → `hmw.js` degrade về default subagent + WARN (fail-soft, KHÔNG crash). Windows MAX_PATH (Dropbox nested) → KHÔNG `isolation:worktree`.
|
||||
|
||||
## Quy trình HMW — vai trò từng phase
|
||||
| Phase | Ai | Làm |
|
||||
|---|---|---|
|
||||
| **P0** prep | 👤 em main | đọc MEMORY sub liên quan → **memory-pack SLICE/vai** (KHÔNG full) + `taskList` + chụp **chunk-count Qdrant baseline** + git status sạch |
|
||||
| **P1** decide | sub liên quan (full memory) | recommend approach + **acceptance-checklist** → em main chốt plan |
|
||||
| ⏸ **checkpoint** (inform) | 👤 em main | BÁO `{số agent · vai · task}` @inform → set `args.checkpointApproved=true` → fan-out NGAY (marker-ON=consent; anh interrupt nếu sai — KHÔNG chờ confirm từng lần) |
|
||||
| **P2** execute | Workflow `hmw` | fan-out agent: **memory-pack injected** qua `args` + `agentType` + schema. DEFAULT read/analyze; write = file-disjoint. inherit Opus |
|
||||
| **P3** harvest | 👤 em main (single-writer) | **NGAY sau P2** → VERIFY delta + APPEND-only vào MEMORY.md **mọi agent tham gia** (B3) |
|
||||
| **P4** final | sub quality (full memory) | reviewer PASS/FAIL · cicd-monitor drift · investigator verify · implementer/test scope → return delta |
|
||||
| **→** | 👤 em main | synthesize + **git-diff** + **chunk-count check** + commit (anh OK) |
|
||||
|
||||
## 🧠 KỶ LUẬT KÝ ỨC (cốt lõi — M1..M5 + R1)
|
||||
- **B1 (M1) có ký ức:** agent vai X ← memory-pack **slice của đúng sub X** (qua `args`; script KHÔNG đọc file — lead đọc `.claude/agent-memory/X/MEMORY.md` @P0 rồi bơm @P2). KHÔNG full memory.
|
||||
- **B2 (M4) đúng chỗ + harvest-LIỀN:** delta vai X → `.claude/agent-memory/X/MEMORY.md`. Harvest NGAY sau MỖI workflow (KHÔNG gom cuối session) → memory mọi agent fresh TRƯỚC lần spawn kế. Tốc-độ KHÔNG override B3.
|
||||
- **B3 (M3) KHÔNG ghi đè nếu chưa kiểm tra:** em main = **single-writer**, VERIFY delta → **APPEND-only**; KHÔNG overwrite/sửa/xóa entry cũ trừ khi verified; delta nghi ngờ → **pending-verify** (không nhập). *(Generalize: memory cũ = tài sản.)*
|
||||
- **R1 return contract:** mỗi agent return `findings` + `memoryDelta{task,verdict,learned,surprise}` (bắt buộc) + `checklistEvidence` (tùy). Agent **CHỈ return** — KHÔNG tự ghi ký ức kênh nào.
|
||||
- **M5 prereq (verify-ONLY, KHÔNG re-author):** `store_memory` đã strip khỏi MỌI sub (broadcast `Memory-store-memory-strip-global`, applied S47) → kênh RAG-write mechanized-blocked. Re-verify intact: `grep store_memory .claude/agents/*.md` → **0** ở dòng `tools:`.
|
||||
|
||||
### 🔴 Enforcement THẬT (G-015 — KHÔNG overclaim)
|
||||
- **Mechanized** = CHỈ `store_memory` gỡ khỏi allowlist (tool RAG-write đó **không-gọi-được**). KHÔNG = agent "read-only".
|
||||
- *"KHÔNG ghi file MEMORY.md"* = **prompt-rule, CHƯA mechanized** — sub vẫn giữ `Bash` (+ `Write/Edit` vai write) = kênh ghi MỞ (Bash ghi file bất kỳ / curl thẳng Qdrant `:6333`).
|
||||
- **Containment thật = defense-in-depth:** `git diff` post-P2 (bắt file-write) + **chunk-count Qdrant pre/post-P2** (bắt RAG-write). Lỗ residual (ghi ngoài-repo / Qdrant net-zero-delta) → sandbox / strip-`Bash` khỏi vai read-only = **defer** (Bash cần cho audit).
|
||||
|
||||
**Guards:** S1 scope-repo-mình · S2 checkpoint-throw (`hmw.js` GIỮ anti-accidental) · S3 sub-KHÔNG-spawn-sub · B3 + harvest-liền · git-diff + chunk-count post-P2 · same-model · số-task-thoải-mái + spawn-đúng-vai · KHÔNG bỏ P3.
|
||||
98
.claude/workflows/hmw.js
Normal file
98
.claude/workflows/hmw.js
Normal file
@ -0,0 +1,98 @@
|
||||
// hmw.js — HMW P2 (Execute) workflow cho SOLUTION_ERP. CHẠY bởi Workflow runtime (body wrap async →
|
||||
// top-level await/return hợp lệ); KHÔNG node-runnable trực tiếp (`node hmw.js` sẽ lỗi await).
|
||||
// Em main lo P0/P1/P3/P4 NGOÀI workflow; script này CHỈ lo P2 fan-out.
|
||||
// Invoke bằng {scriptPath} (no hot-reload — restart/re-invoke sau khi sửa). Scope = repo SOLUTION_ERP ONLY (S1).
|
||||
|
||||
export const meta = {
|
||||
name: 'hmw',
|
||||
description: 'HMW P2 execute (SOLUTION_ERP) — fan-out 8-agent roster có MEMORY-PACK slice (qua args vì script không đọc file) + return findings + checklistEvidence + memoryDelta (spawn-record 4-field). DEFAULT read/analyze; write fan-out = file-disjoint + em main git-diff sau P2. taskList thoải mái (queue theo slot, không cap cứng). memoryDelta KHÔNG tự ghi — em main VERIFY + APPEND-only @P3 (no-overwrite-unverified, B3). Same-model inherit Opus. Scope = repo SOLUTION_ERP ONLY (S1 — KHÔNG fan-out repo/corpus khác).',
|
||||
phases: [{ title: 'Execute', detail: 'fan-out memory-pack-injected agents, structured return' }],
|
||||
}
|
||||
|
||||
// ─── args (em main bơm @P2 sau khi P1 chốt) ──────────────────────────────────
|
||||
// args = {
|
||||
// memoryPack: { 'investigator-codebase':'<slice>', 'implementer-backend':'...', reviewer:'...', ... }, // SLICE liên quan, KHÔNG full
|
||||
// spec: '<acceptance-criteria / context chung>',
|
||||
// checkpointApproved: true, // em main set SAU khi BÁO {số agent·vai·task} @inform (S2)
|
||||
// taskList: [ { role:<VALID_ROLES|null>, label:'..', prompt:'..' }, ... ]
|
||||
// }
|
||||
|
||||
const VALID_ROLES = [
|
||||
'investigator-codebase', 'investigator-api',
|
||||
'implementer-backend', 'implementer-frontend',
|
||||
'test-specialist', 'reviewer', 'cicd-monitor', 'frontend-designer',
|
||||
]
|
||||
|
||||
const SCHEMA = {
|
||||
type: 'object',
|
||||
required: ['findings', 'memoryDelta'],
|
||||
properties: {
|
||||
findings: { type: 'string', description: 'Kết quả chính. MỌI claim kèm evidence file:line. KHÔNG narrative suông.' },
|
||||
checklistEvidence: { type: 'string', description: 'Bằng chứng cho acceptance-checklist P1 (số đo / PASS-FAIL / verdict).' },
|
||||
memoryDelta: {
|
||||
type: 'object',
|
||||
description: 'Spawn-record 4-field — RETURN-only để EM MAIN harvest @P3. Agent KHÔNG tự ghi ký ức (KHÔNG file MEMORY.md, KHÔNG store_memory/RAG). Em main VERIFY + APPEND-only (KHÔNG overwrite entry cũ nếu chưa kiểm tra — B3).',
|
||||
required: ['task', 'verdict', 'learned', 'surprise'],
|
||||
properties: {
|
||||
task: { type: 'string', description: 'việc gì (1 dòng)' },
|
||||
verdict: { type: 'string', description: 'kết luận / PASS-FAIL / root-cause' },
|
||||
learned: { type: 'string', description: 'pattern / anti-pattern rút ra' },
|
||||
surprise: { type: 'string', description: 'edge-case / bất ngờ (chống mất discovery)' },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
// S4b — args có thể tới OBJECT hoặc JSON-STRING (harness đôi khi stringify object args) → normalize defensive
|
||||
const A = (typeof args === 'string') ? JSON.parse(args) : (args || {})
|
||||
|
||||
if (!A || !Array.isArray(A.taskList) || A.taskList.length === 0) {
|
||||
throw new Error('hmw: cần args.taskList (mảng {role,label,prompt}) — em main bơm @P1. (đã thử JSON.parse nếu args bị stringify.)')
|
||||
}
|
||||
// S2 mechanize: checkpoint TRƯỚC P2 = gate CỨNG, không chỉ prompt. Em main BÁO {số agent·vai·task} @inform
|
||||
// (KHÔNG chờ confirm) → set args.checkpointApproved=true → fan-out. Flag GIỮ = anti-accidental-fire
|
||||
// (call quên-set-flag → throw, chặn 515K-class accidental).
|
||||
if (A.checkpointApproved !== true) {
|
||||
throw new Error('hmw: checkpointApproved chưa set — em-main BÁO {số agent·vai·task} @inform rồi set args.checkpointApproved=true (guard = anti-accidental-fire).')
|
||||
}
|
||||
// S4 — số task THOẢI MÁI: harness chạy theo slot, dư tự queue, KHÔNG cap cứng (soft notice only).
|
||||
if (A.taskList.length > 16) {
|
||||
log(`hmw: taskList=${A.taskList.length} (>16) → harness queue theo slot (thoải mái, không cap cứng).`)
|
||||
}
|
||||
|
||||
const memoryPack = A.memoryPack || {}
|
||||
const spec = A.spec || ''
|
||||
|
||||
phase('Execute')
|
||||
log(`HMW P2: fan-out ${A.taskList.length} task (same-model inherit, memory-pack-injected, scope=SOLUTION_ERP repo only)`)
|
||||
|
||||
const results = await parallel(A.taskList.map((t, i) => () => {
|
||||
const raw = t && t.role
|
||||
const role = VALID_ROLES.includes(raw) ? raw : undefined // S4c whitelist; invalid → default subagent (fail-soft)
|
||||
if (raw && !role) log(`⚠️ hmw: agentType "${raw}" ∉ VALID_ROLES → default subagent cho task #${i}`)
|
||||
|
||||
const mem = role && memoryPack[role] ? memoryPack[role] : ''
|
||||
const prompt = [
|
||||
mem ? `## MEMORY-PACK (${role}) — SLICE ký ức tích lũy của sub này, ĐỌC trước khi làm (KHÔNG phải full memory):\n${mem}\n` : '',
|
||||
spec ? `## SPEC / acceptance-criteria (chung):\n${spec}\n` : '',
|
||||
`## TASK:\n${(t && t.prompt) || '(thiếu prompt — lỗi taskList @P0)'}`,
|
||||
[
|
||||
'## OUTPUT (structured bắt buộc):',
|
||||
'- findings: kết quả + evidence file:line (KHÔNG narrative suông).',
|
||||
'- checklistEvidence: số đo / verdict cho acceptance-checklist.',
|
||||
'- memoryDelta {task·verdict·learned·surprise}: để EM MAIN harvest @P3.',
|
||||
'⚠️ KHÔNG ghi ký ức kênh nào: KHÔNG file MEMORY.md, KHÔNG store_memory/RAG-write (Qdrant). CHỈ return memoryDelta → em main VERIFY + APPEND-only @P3 (B3). KHÔNG overwrite file/chunk của sub khác.',
|
||||
'⚠️ Nếu task có WRITE file: CHỈ file-disjoint được giao (em main git-diff verify sau P2). KHÔNG đụng file ngoài phạm vi. Scope = repo SOLUTION_ERP only (S1).',
|
||||
].join('\n'),
|
||||
].filter(Boolean).join('\n')
|
||||
|
||||
return agent(prompt, {
|
||||
agentType: role || undefined,
|
||||
schema: SCHEMA,
|
||||
label: (t && t.label) || `hmw:${role || 'task'}-${i}`,
|
||||
})
|
||||
}))
|
||||
|
||||
// trả mảng kết quả (lọc null nếu agent lỗi/null — invalid-role vẫn chạy default subagent, KHÔNG skip)
|
||||
// về em main → P3 VERIFY + harvest + P4 checklist
|
||||
return results.filter(Boolean)
|
||||
Reference in New Issue
Block a user