solution-erp/.claude/workflows/runs/2026-07-11-h21-mtv3-adopt/spec-h21-mtv3-adopt-11-07-2026.md

# SPEC — h21-mtv3-adopt — 11-07-2026 (S110)

> **Provenance (H21 note-c):** engine-propose = investigator-codebase **Fable-real single-deep-pass** (vai anh gán trong lệnh; #53-garble lượt return → SendMessage-resume recover, verdict PASS) → **lead verified + chỉnh 2 điểm** (worker Opus edit-DIRECT file được giao thay vì draft-relay [precedent S103 build-lane, git-diff backstop] · row-11 review-gate = reviewer Fable-real per lệnh anh) → **lead tự ghi file này** (single-writer). Worker KHÔNG tự đọc file — lead bơm nguyên văn qua prompt/args (hmw.js:9 pattern).

## Mục 1 — Tính-năng / đề-bài

Adopt **Harness-21** + **model-tier-v3** trên SOLUTION_ERP: chuyển engine-đắt từ mode-marker + 2-vai-cố-định sang **per-invocation** (`/fable-real <vai> <đề-bài>` = single top-model deep-pass · `/fable-clone <vai> <đề-bài>` = ensemble tier-2), mỗi run engine-đắt sinh **spec-file 3-mục** (engine propose → lead verify + ghi → worker thực thi theo spec bơm qua args); reword floor model-tier "lead LUÔN top-model" → "lead = frontier-class owner-choice {Fable 5 | Opus 4.8 — cả hai 1M MAX}, CẤM Sonnet/Haiku-class ghế lead" + phân biệt owner-choice vs outage (0 caveat / 0 revert-nghĩa-vụ khi owner chọn) + 1-line-ask phiên đầu sau outage đóng; + triage-S5 caveat hot-reload ENV-DEPENDENT.
**Xong nghĩa là:** grep token-cũ trên tài liệu ACTIVE = 0 sót · marker file đã xóa · 4 ghi-chú trung-thực a-d hiện diện · 2 adap-report + email AI_INFRA gửi · mark mới trình anh chờ confirm (KHÔNG tự stamp).

## Mục 2 — Cách implement

### Quyết định thiết kế
- **D1 — Lệnh:** GIỮ tên 2 lệnh (form tự quyết H21 §6), đổi semantics: `<vai>` BẮT BUỘC ∈ 12-sub roster + `<đề-bài>`; hiệu lực CHỈ lượt đó, 0 marker. Thiếu/sai vai → hỏi anh 1 dòng, KHÔNG tự chọn. Honest-note a/b: bảo-đảm = owner-gated tầng lệnh + kỷ-luật lead, KHÔNG claim code-enforced; lệnh gõ không-vai = hỏi lại (không có alias tự-chọn-vai).
- **D2 — Spec-file:** `.claude/workflows/runs/<run-id>/spec-<tên-tính-năng>-<dd-mm-yyyy>.md`, 3 heading cố định (Tính-năng/đề-bài · Cách implement · Checklist [vai + deliverable + acceptance đo được]). Run chấm/verify CŨNG sinh (mục-2 = kế-hoạch xử issue — note d). Worker nhận spec QUA ARGS/prompt (không tự Read). Reuse run-trace H10 git-TRACKED → anh audit qua git.
- **D3 — Marker:** xóa `.claude/fable-real-mode.on` (em-main, đã làm trước WF); `.gitignore:89-92` GIỮ pattern (file cũ Dropbox-sync tái xuất vẫn ignored) + comment → "🧊 retired H21 S110 — chỉ còn phòng-hờ".
- **D4 — session-start BƯỚC 0.5b:** retire-reword GIỮ số thứ tự (tránh renumber churn): nội dung mới = "Engine-đắt H21: KHÔNG còn mode/marker — chỉ chạy trong lượt anh gõ `/fable-real|/fable-clone <vai> <đề-bài>`; lead không tự gọi". **BƯỚC 0.5 (HMW) GIỮ NGUYÊN.**
- **D5 — engine §K:** banner supersede-partial ngay dưới title `:315` + point-edit K.A (2 vai → reference-example, vai do anh gán) + K.B (marker/toggle → 🧊 note-supersede từng gạch, giữ nguyên văn cũ có đánh dấu — KHÔNG rewrite) + K.D point-1 reword MTv3 + point-2 reword per-invocation; **K.C GIỮ 3 GAP-guard** (chỉ đổi trigger-wording "clone-mode" → "lệnh-B ensemble"); **+K.E MỚI**: spec-file pipeline 3-mục + 4 honest-note a-d + bảng 2 lệnh per-invocation.
- **D6 — runbook (60KB — point-edit ~20 cụm, KHÔNG rewrite):** title banner H21 · §1 dùng-nhanh (đọc-marker → lệnh-owner-lượt-này) · §2.1 marker-lifecycle đóng khung 🧊 history + thêm "INVOCATION lifecycle" · `$mode` → `$engine{real-single, clone-ensemble}` derive từ TÊN LỆNH lượt này · `:140`/`:455` floor reword MTv3 · §2.5 matrix (:145-158) tương-tác 2 marker → còn 1 marker hmw + per-invocation · §5.1 PRE-FLIGHT vars `MARKER_PRESENT/MODE/ANH_CONSENT_REAL` → `INVOCATION{lệnh,vai,đề-bài}/ROLE_VALID/SPEC_PATH` · AP-4 (báo marker-state) → AP mới "chạy engine-đắt ngoài lượt-lệnh anh = vi phạm" · template lane §3/§4 GIỮ làm ví dụ per-invocation · §5.5 dogfood-form S108 GIỮ snapshot + 1 dòng đầu "form theo khung H19-marker, trước H21".
- **D7 — session-start BƯỚC 0.6:** +4 vế MTv3 (lead = owner-choice per-session {Fable|Opus 4.8}, đổi giữa phiên hợp lệ ghi 1 dòng) · outage-path H5 GIỮ · bỏ "Fable UP → tự về" (auto-revert) → "outage đóng → phiên đầu hỏi anh ĐÚNG 1 DÒNG ('hạng-nhất resolve lại — giữ hạng-hai hay đổi?'), 1 lần" · flip-record gắn nhãn {owner-choice|outage}.
- **D8 — Mark:** đề xuất 1 mark MỚI (H21+MTv3 gộp) supersede `RC-pqhuy1987-03-07-2026-17-46-35` → row cũ 📦; **CHỜ anh confirm** — em-main KHÔNG tự stamp/sửa (P8).
- **D9 — Triage-S5:** caveat ENV-DEPENDENT 3 chỗ: `agents/README.md:18` + `:263` + user-memory `project_harness4_two_tier_model.md` — "hub experiment NGƯỢC (0 notice + spawn not-found ×2) ⇒ ENV-DEPENDENT, KHÔNG fleet-generalize từ 1 datapoint; restart = default an toàn".
- **D10 — hmw.js:38:** reword COMMENT ONLY ("tier:'fable' CHỈ dùng trong lượt lệnh engine-đắt anh gõ (H21) — lead KHÔNG tự ý"); code KHÔNG đổi.
- **D11 — Outward:** 2 adap-report (H21 + MTv3 — MTv3 report PHẢI cite triage-S2 waive all-inherit) + 3 supersede-note 1-dòng header lên adap-report cũ (H19 fable-clone · model-tier-v2-pin-simple · checklist-model-tier) + email AI_INFRA kèm run-id.
- **D12 — STATUS/HANDOFF:** S110 blurb mới ("H21 adopted — marker retired, per-invocation") + 🧊-inline tại 2 câu "VẪN ON" + HANDOFF NEXT-anh item(1) thay bằng hướng-dẫn lệnh mới + restart-CLI note.

### Ràng buộc thật
Worker Opus edit-DIRECT trong PHẠM VI file được giao (disjoint 3 lane), mọi write khác = residual → em-main git-diff revert (AS-10 backstop) · governance ledger (ACTIVE-MARKS) + user-memory + STATUS/HANDOFF + marker + email = em-main tự làm · EDIT command/session-start `.md` = restart CLI mới ăn runtime (S27 + S5 env-dependent) · HISTORY (session-log · archive verbatim · adap-report body cũ · diary · dogfood-form) GIỮ nguyên văn.

### Đường chết cần né
(X1) gỡ nhầm `hmw-mode.on`/BƯỚC 0.5/`ultra-*` — HỆ KHÁC (HMW fan-out consent, evidence: ultra-on/off grep `fable`=0) · (X2) sửa session-log/verbatim archive · (X3) rewrite runbook toàn bộ · (X4) worker Write file NGOÀI phạm-vi giao · (X5) tự stamp/sửa mark · (X6) quên restart-CLI note → chạy semantics cũ · (X7) đổi code hmw.js (chỉ comment) · (X8) claim "code-enforced" (note a cấm) · (X9) xóa gitignore pattern (file cũ sync lại → commit → semantics-ma).

## Mục 3 — Checklist thực hiện

| # | Vai | Deliverable | Acceptance (đo được) |
|---|---|---|---|
| 1 | em-main | Xóa marker + `.gitignore:89-91` comment 🧊 | `Test-Path .claude/fable-real-mode.on` = False; `git check-ignore` vẫn IGNORED |
| 2 | worker-opus-1 (edit-direct) | Redesign 2 command file (D1) + honest-note a/b | grep `Write.*marker\|Remove-Item` 2 file = 0 dòng ACTIVE; `<vai>` bắt buộc documented; "hỏi lại anh" present |
| 3 | worker-opus-1 (edit-direct) | session-start BƯỚC 0.5b reword (D4) + BƯỚC 0.6 MTv3 (D7) | grep "Marker TỒN TẠI" vùng 0.5b = 0; grep "tự về" BƯỚC 0.6 = 0; "ĐÚNG 1 DÒNG" ≥ 1; BƯỚC 0.5 HMW untouched |
| 4 | worker-opus-2 (edit-direct) | engine §K banner + K.A/K.B/K.D point-edit + K.E mới (D5) | 4 note a-d grep-được; K.D point-1 = "frontier-class owner-choice"; văn cũ còn nguyên kèm 🧊 |
| 5 | worker-opus-3 (edit-direct) | runbook ~20 point-edit (D6) | grep `Test-Path .claude/fable-real-mode.on` ngoài khối-🧊/history = 0; title có banner H21 |
| 6 | em-main | STATUS/HANDOFF S110 (D12) @closeout | HANDOFF NEXT-anh hết "/fable-clone nếu muốn về ảo"; blurb S110 chứa "per-invocation" |
| 7 | em-main | Triage-S5 caveat 3 file (D9) | grep "ENV-DEPENDENT" ≥1 hit mỗi file |
| 8 | em-main | hmw.js:38 comment (D10) | grep "khi hệ-trọng" hmw.js = 0; `node --check` OK |
| 9 | em-main (nằm trong D5/K.E) | Spec-template + naming codify | Template 3-heading grep-được trong engine K.E |
| 10 | em-main | 2 adap-report + 3 supersede-note + email + đề-xuất mark (D8/D11) | 2 report mới có hash-verify; ACTIVE-MARKS row cũ CHƯA đổi (chờ anh); AskUserQuestion đã trình |
| 11 | reviewer **Fable-real** (vai anh gán trong lệnh) | Cổng-cuối sweep 2-đầu-khác-trục: grep-suite token-cũ ACTIVE=0 + 4-note present + boundary hmw nguyên + spec-compliance + biên-case (vai sai/thiếu → hỏi anh?) | Verdict PASS/FAIL kèm evidence; hmw-mode.on + BƯỚC 0.5 untouched |
| 12 | em-main | Restart-CLI note cho anh | HANDOFF NEXT-anh có dòng restart |

**Map sàn-5-điểm H21 §6:** (1) spec-file 3-mục → #9+D2 · (2) worker theo spec → D2 pipe-args · (3) chỉ chạy khi owner gõ → D1 · (4) vai owner gán đích-danh → D1 · (5) lead không tự gọi → D1+D10+AP-mới-runbook.