solution-erp/.claude/workflows/README.md

.claude/workflows/ — Workflow fan-out + run-trace convention (Harness-10)

Mục đích: convention cho HMW workflow fan-out + run-trace folder (mỗi workflow run → 1 thư mục runs/<run-id>/ git TRACKED, gom plan + per-sub + harvest + ledger 2-nhịp). Adopt AI_INFRA Harness-10 (anh 06-18) — kế thừa wave-folder memory-isolation Harness-2 nhưng đổi từ transient-gitignored sang tracked-run-folder để audit trực-tiếp qua git-diff. Canonical rule: AI_INFRA CANONICAL-RULES.md §J4 (return-delta default) + §J6 (run-trace + 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) · RUN-TRACE mode (§J6, args.run).
• README.md — file này (convention).
• runs/ — git TRACKED (qua negation .gitignore:83 !.claude/**), không gitignore. Mỗi workflow run = 1 sub-folder runs/<run-id>/. Xem runs/README.md cho cấu trúc chi-tiết + ledger 2-nhịp + 3-layer anti-miss.

Run-trace = mỗi workflow run → runs/<run-id>/ TRACKED

Mỗi lần chạy workflow fan-out (RUN-TRACE mode) → 1 thư mục run git theo dõi, gồm:

.claude/workflows/runs/<run-id>/         ← TRACKED (hiện trong git-diff = audit trực-tiếp)
├── run.md                               ← Run-MD chính — EM MAIN ghi @P1 (plan + agents-table + spec + guards + status OPEN→CLOSE)
├── sub-md/<role>-<i>.md                 ← per-sub — full working detail (write-sub tự ghi @P2 · read-only sub → em main scribe @P3)
└── harvest/<topic>-synthesis.md         ← gom kết-quả — EM MAIN ghi NGAY sau mỗi fan-out turn (C4 per-turn primary)

• runs/_ledger.md — sổ run 2-nhịp: ghi OPEN-beat lúc mở run + CLOSE-beat (timestamp + verdict + harvest) lúc đóng. Orphan = OPEN mà không CLOSE → phải giải-quyết-cứng (điều tra + đóng tay hoặc đánh-dấu aborted). Chi-tiết runs/README.md.

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

	DEFAULT return-delta-only (§J4)	RUN-TRACE mode (§J6)
Khi dùng	fan-out NHẸ (~2-3 phút, read/analyze — vd recon)	workflow DÀI / sinh nhiều detail / cần audit-trail
Sub ghi file?	KHÔNG — chỉ return memoryDelta + findings	write-sub GHI full-detail vào runs/<run-id>/sub-md/<role>-<i>.md; read-only sub → findings + subMdPath → em main scribe
Lead làm	VERIFY + APPEND @P3 (B3)	đọc sub-md/ on-demand + ghi harvest/ per-turn (C4) + H2 gom @session-end (B5, backstop)
Rủi ro mất detail	có (delta lossy) — chấp nhận cho việc nhẹ	KHÔNG (full-detail giữ trong run-folder tracked)

Mặc định DEFAULT. RUN-TRACE chỉ bật khi workflow dài/nhiều detail/cần dấu-vết (set args.run = {name, dir}). KHÔNG bắt mọi fan-out tạo run-folder.

Quy trình RUN-TRACE (B1–B6)

1. B3 SCAFFOLD TRƯỚC (em main @P1): tạo runs/<run-id>/ + run.md + sub-md/.gitkeep + harvest/.gitkeep, và ghi OPEN-beat vào runs/_ledger.md. ⚠️ hmw.js chạy JS-sandbox no-filesystem → KHÔNG tự tạo folder; em main Write @P1 TRƯỚC khi invoke Workflow. (Đây là fragile-point — quên scaffold = run mất dấu-vết âm-thầm; xem runs/README.md §C7.)
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 runs/<run-id>/sub-md/<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 trong runs/<run-id>/ (sub-md của mình) + 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 → run-folder TRACKED → mọi write trong run-folder HIỆN trong diff = audit trực-tiếp; tracked-change NGOÀI runs/<run-id>/ VÀ NGOÀI code-disjoint đã giao = vi-phạm (thay model Harness-2 B6 "mọi tracked-change = vi-phạm"). Verify pattern bằng git check-ignore -v (test match thật, đừng tin .gitignore text — bẫy exit-code: dùng && IGNORED || NOT).
5. B5 HARVEST (per-turn primary C4 + close-gate backstop): em main ghi harvest/<topic>-synthesis.md NGAY sau mỗi fan-out turn (đọc sub-md/ + findings → 5-trục integrity → consolidate). @session-end ⬜ harvest-curator H2 §L.b(f) VERIFY per-turn harvest đã xong cho mọi runs/<id>/ (idempotent — KHÔNG re-APPEND, chống DUPLICATE-HARVEST) + giữ 5-trục GATE làm backstop, rồi đề-xuất em main APPEND vào agent-memory/<role> sub tương-ứng.

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 run-trace).
• ⚠️ 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 (no-overclaim): run-folder TRACKED ≠ read-only-ENFORCED — sub vẫn giữ Bash (write-channel mở: ghi-ngoài-repo git-diff mù / curl Qdrant). Containment THẬT = em-main single-writer + git-diff (in-repo, run-folder tracked nên hiện) + chunk-count (RAG), defense-in-depth, KHÔNG sandbox cứng. KHÔNG claim "ENFORCED", KHÔNG bỏ chunk-count.