# `.claude/workflows/` — Workflow + wave-folder convention (Harness 2)

> **Mục đích:** convention cho HMW workflow fan-out + **wave-folder memory-isolation** (adopt AI_INFRA Harness 2, anh 06-07). Canonical rule: AI_INFRA `CANONICAL-RULES.md` §J4 (return-delta default) + §J6 (wave-mode + agent-team) — pull qua `cross_project_search`, KHÔNG copy. Tailor SE 8-role roster + S1 scope.

## Files (tracked)
- `hmw.js` — HMW P2 fan-out script. 2 mode: DEFAULT return-delta-only (§J4) · WAVE-MODE (§J6, `args.wave`).
- `README.md` — file này (convention).
- `wave-<tên>/` — **gitignored** (`.gitignore:93` `.claude/workflows/wave-*/`), transient per-workflow.

## 2 MODE memory (ADD — anh 06-07, KHÔNG thay return-delta)

| | DEFAULT return-delta-only (§J4) | WAVE-MODE (§J6, Harness 2) |
|---|---|---|
| Khi dùng | fan-out NHẸ (~2-3 phút, read/analyze — vd recon wave) | workflow DÀI / sinh nhiều detail |
| Sub ghi file? | KHÔNG — chỉ return `memoryDelta` | GHI full-detail vào `wave-<tên>/sub-<role>-<i>.md` |
| Lead làm | VERIFY + APPEND @P3 (B3) | đọc wave on-demand + H2 gom @session-end (B5) |
| Rủi ro mất detail | có (delta lossy) — chấp nhận cho việc nhẹ | KHÔNG (full-detail giữ isolated) |

> Mặc định DEFAULT. WAVE-MODE chỉ bật khi workflow dài/nhiều detail (set `args.wave`). KHÔNG bắt mọi fan-out wave-folder.

## Wave-folder structure (WAVE-MODE)
```
.claude/workflows/wave-<tên>/        ← gitignored (transient; H2 gom rồi → có thể xóa sau commit)
├── wave.md                          ← Wave-MD chính — EM MAIN ghi @P1 (task-list + vai + spec + status + harvest-state)
├── sub-<role>-<i>.md                ← sub-MD — SUB tự ghi @P2 (vd sub-investigator-codebase-0.md) — full working detail
└── _harvest.md                      ← H2 (harvest-curator) ghi propose @session-end (gom gì về agent-memory nào)
```

## Quy trình WAVE-MODE (B1–B6)
1. **B3 SCAFFOLD TRƯỚC (em main @P1):** tạo folder `wave-<tên>/` + `wave.md` (task-list + vai rõ). ⚠️ `hmw.js` chạy JS-sandbox **no-filesystem** → KHÔNG tự tạo folder; **em main Write @P1** TRƯỚC khi invoke Workflow.
2. **B1 spawn-from-real-sub:** mỗi task `role ∈ VALID_ROLES` (8 sub) → workflow-agent = sub THẬT (`agentType` inherit memory-pack slice + skill identity), KHÔNG agent vô-danh.
3. **B4 phân-quyền TOOL-AWARE:** `hmw.js` inject vào prompt mỗi sub đường-dẫn `sub-<role>-<i>.md` + lệnh ghi ĐÚNG file đó.
   - **Write sub (CÓ Write/Edit):** implementer-backend · implementer-frontend · test-specialist · frontend-designer → ghi-direct sub-MD via Write/Edit.
   - **Read-only sub (CHỈ Bash):** investigator-codebase · investigator-api · reviewer · cicd-monitor → 🔴 KHÔNG Bash-write MD (mojibake) → full-detail vào `findings` + `subMdPath` → **em main scribe @P3** (single-writer).
4. **B6 ISOLATION (AUDIT cẩn-thận):** sub CHỈ ghi `wave-<tên>/sub-*.md` (+ code-file-disjoint nếu giao). 🔴 KHÔNG ghi `agent-memory/*` chính · KHÔNG MD canonical (CLAUDE/README/STATUS/agents) · KHÔNG sub-MD agent khác. **Em main `git status`/`git diff` + chunk-count sau P2** → tracked-file đổi NGOÀI code-disjoint = **vi-phạm** (wave-folder gitignored nên KHÔNG hiện trong diff = sạch). Verify pattern bằng `git check-ignore -v` (test match thật, đừng tin .gitignore text).
5. **B5 HARVEST (⬜ harvest-curator H2 @session-end §L.b(f)):** đọc `wave-<tên>/sub-*.md` → 5-trục integrity → đề-xuất em main consolidate APPEND vào `agent-memory/<role>` sub tương-ứng → sub-chính có đầy-đủ memory. Ghi `_harvest.md` propose.

## Agent-team (`.claude/agent-teams/<tên>/` — gitignored `.gitignore:94`)
- Cùng nguyên-lý isolation: teammate **KHÔNG có memory-dir built-in** (khác subagent) → folder riêng cho teammate ghi MD-session (A1, tránh overwrite memory chuẩn).
- Team spawn TỪ **sub-agent chính có memory dự-án rõ-ràng** (A2 — mang identity/skill sub thật trong 8 roster).
- H2 harvest-curator gom `.claude/agent-teams/<tên>/` → agent-memory tương-ứng (giống wave).
- ⚠️ **Caveat: Agent-Team experimental + Windows 11 in-process only** (no split-pane) → SE **CHƯA dùng team thật** → A = **convention-ready** (n-a runtime), cơ-chế isolation chung qua workflow.

## Guard
- **S1:** Workflow CHỈ repo SOLUTION_ERP — KHÔNG fan-out repo/corpus khác (`cross_project_search` = READ reference only).
- **S2/S3:** chỉ chạy khi HMW-mode ON (`/ultra-on` → marker `.claude/hmw-mode.on`) + checkpoint INFORM (`hmw.js` throw nếu `checkpointApproved≠true`) + sub KHÔNG spawn sub.
- **G-015 accuracy:** isolation = defense-in-depth (gitignore wave-*/ + em main git-diff post-P2 + chunk-count), KHÔNG sandbox cứng. Read-only sub vẫn giữ Bash = ghi-ngoài-repo (git-diff mù) / curl Qdrant (chunk-count bắt). KHÔNG claim "ENFORCED".