claudeos-core 2.0.1 → 2.1.0

package/README.vi.md

@@ -12,6 +12,20 @@ ClaudeOS-Core đọc codebase của bạn, trích xuất mọi pattern tìm th
 
 ---
 
+## Có Gì Mới Trong v2.1.0
+
+v2.1.0 tái kiến trúc Pass 3 để loại bỏ lỗi `Prompt is too long` trên các dự án cỡ trung bình đến lớn. Trước đây, một lời gọi Pass 3 đơn lẻ phải phát ra toàn bộ cây tài liệu cùng lúc — hàng chục file trải dài qua `CLAUDE.md`, rules, standards, skills và guides — và output tích lũy luôn vượt context window khi vượt quá ~5 domain. Fix này mang tính **cấu trúc**, không phải tinh chỉnh prompt:
+
+- **Pass 3 split mode** (luôn bật) — Pass 3 được tách thành các lời gọi `claude -p` tuần tự (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`). Mỗi stage bắt đầu với **context window mới**, nên tràn output do tích lũy không còn khả thi bất kể kích thước dự án.
+- **Fact sheet giữa các stage** — Stage `3a` đọc kết quả phân tích Pass 2 một lần và chắt lọc thành `pass3a-facts.md` kích thước 5–10 KB. Tất cả stage sau tham chiếu fact sheet này thay vì đọc lại `pass2-merged.json` 100–500 KB, giữ tính nhất quán xuyên file qua các context mới.
+- **Chia batch tự động** (tự động ở ≥16 domain) — Stage 3b/3c được chia thêm thành các batch 15 domain mỗi cái, giữ output của mỗi stage dưới ~50 file. Admin frontend React 19 + Vite 6 với 18 domain hoàn thành trong **102 phút với 101 file được tạo qua 8 stage, 0 lỗi tràn output** (chạy thực tế production, 2026-04-20).
+- **Loại bỏ tạo master plan** — Các file `claudeos-core/plan/*-master.md` không còn được tạo nữa. Master plan là backup nội bộ mà Claude Code không đọc lúc runtime, và việc tổng hợp chúng trong Pass 3d là nguyên nhân tràn chính. Dùng `git` để backup/restore thay thế.
+- **Pass 4 gap-fill: `skills/00.shared/MANIFEST.md`** — Nếu Pass 3c bỏ sót skill registry (dự án ít skill), Pass 4 giờ tự động tạo stub để `.claude/rules/50.sync/03.skills-sync.md` không bao giờ trỏ tới file không tồn tại.
+
+Một vài fix nhỏ: `memory --help` giờ hiển thị help của subcommand memory (trước đây hiển thị top-level); `memory score` không còn để lại các dòng `importance` trùng lặp; marker summary của `memory compact` giờ là markdown list item đúng định dạng. Chi tiết đầy đủ: [CHANGELOG.md](./CHANGELOG.md).
+
+---
+
 ## Tại sao chọn ClaudeOS-Core?
 
 Mọi công cụ Claude Code khác hoạt động như sau:
@@ -222,7 +236,7 @@ npx claudeos-core init --lang en    # English (mặc định)
 
 > **Lưu ý:** Cài đặt này chỉ áp dụng cho ngôn ngữ của các file tài liệu được tạo. Phân tích code (Pass 1–2) luôn chạy bằng tiếng Anh; output được tạo (Pass 3) được viết bằng ngôn ngữ bạn chọn. Các ví dụ code bên trong file được tạo vẫn giữ nguyên cú pháp ngôn ngữ lập trình gốc.
 
-Vậy thôi. Sau 5–20 phút (Pass 1×N + Pass 2 + Pass 3 + Pass 4 memory scaffolding), tất cả tài liệu được tạo và sẵn sàng sử dụng. CLI hiển thị thanh tiến trình kèm phần trăm, thời gian đã trôi qua và ETA cho mỗi pass.
+Vậy thôi. Sau 10 phút (dự án nhỏ) đến 2 giờ (monorepo 60+ domain), tất cả tài liệu được tạo và sẵn sàng sử dụng. CLI hiển thị thanh tiến trình kèm phần trăm, thời gian đã trôi qua và ETA cho mỗi pass. Xem [Tự Động Mở Rộng Theo Kích Thước Dự Án](#tự-động-mở-rộng-theo-kích-thước-dự-án) để biết thời gian chi tiết theo kích thước dự án.
 
 ### Cài Đặt Thủ Công Từng Bước
 
@@ -249,11 +263,13 @@ mkdir -p claudeos-core/standard/{00.core,10.backend-api,20.frontend-ui,30.securi
 # Skills
 mkdir -p claudeos-core/skills/{00.shared,10.backend-crud/scaffold-crud-feature,20.frontend-page/scaffold-page-feature,50.testing,90.experimental}
 
-# Guide, Plan, Database, MCP, Generated, Memory (v2.0.0: thêm memory)
+# Guide, Database, MCP, Generated, Memory (v2.0.0: thêm memory; v2.1.0: bỏ plan)
 mkdir -p claudeos-core/guide/{01.onboarding,02.usage,03.troubleshooting,04.architecture}
-mkdir -p claudeos-core/{plan,database,mcp-guide,generated,memory}
+mkdir -p claudeos-core/{database,mcp-guide,generated,memory}
 ```
 
+> **Lưu ý v2.1.0:** Thư mục `claudeos-core/plan/` không còn được tạo nữa. Việc tạo master plan đã bị loại bỏ vì master plan là backup nội bộ mà Claude Code không đọc lúc runtime, và việc tổng hợp chúng đã gây ra lỗi `Prompt is too long`. Dùng `git` để backup/restore thay thế.
+
 #### Step 3: Chạy plan-installer (phân tích dự án)
 
 Lệnh này quét dự án, phát hiện stack, tìm domain, chia chúng thành các nhóm và tạo prompt.
@@ -267,7 +283,8 @@ node claudeos-core-tools/plan-installer/index.js
 - `domain-groups.json` — các nhóm domain cho Pass 1
 - `pass1-backend-prompt.md` / `pass1-frontend-prompt.md` — prompt phân tích
 - `pass2-prompt.md` — prompt merge
-- `pass3-prompt.md` — prompt tạo (được bọc bằng directive `staging-override.md` — xem ghi chú Step 6)
+- `pass3-prompt.md` — template prompt Pass 3 với block "Read Once, Extract Facts" Phase 1 được thêm vào đầu (Rules A–E). Pipeline tự động chia Pass 3 thành nhiều stage lúc runtime; template này dùng cho từng stage.
+- `pass3-context.json` — slim project summary (< 5 KB, xây sau Pass 2) mà prompt Pass 3 ưu tiên hơn `pass2-merged.json` đầy đủ (v2.1.0)
 - `pass4-prompt.md` — prompt L4 memory scaffolding (v2.0.0; dùng cùng `staging-override.md` cho ghi rule `60.memory/`)
 
 Bạn có thể kiểm tra các file này để xác minh độ chính xác phát hiện trước khi tiếp tục.
@@ -322,16 +339,35 @@ cat claudeos-core/generated/pass2-prompt.md \
 
 **Xác minh:** `claudeos-core/generated/pass2-merged.json` phải tồn tại với 9+ top-level key.
 
-#### Step 6: Pass 3 — Tạo toàn bộ tài liệu
+#### Step 6: Pass 3 — Tạo toàn bộ tài liệu (chia thành nhiều stage)
+
+**Lưu ý v2.1.0:** Pass 3 **luôn chạy ở chế độ split** bởi pipeline tự động. Mỗi stage là một lời gọi `claude -p` riêng biệt với context window mới, nên tràn output do tích lũy không thể xảy ra về mặt cấu trúc bất kể kích thước dự án. Template `pass3-prompt.md` được lắp ráp theo từng stage với một directive `STAGE:` chỉ cho Claude biết tập con file nào cần phát ra. Với chế độ thủ công, đường đơn giản nhất vẫn là đưa toàn bộ template và để Claude tạo mọi thứ trong một lời gọi — nhưng điều này chỉ đáng tin cậy trên dự án nhỏ (≤5 domain). Cho dự án lớn hơn, hãy dùng `npx claudeos-core init` để split runner xử lý điều phối stage.
+
+**Chế độ lời gọi đơn (chỉ cho dự án nhỏ, ≤5 domain):**
 
 ```bash
 cat claudeos-core/generated/pass3-prompt.md \
   | claude -p --dangerously-skip-permissions
 ```
 
-**Xác minh:** `CLAUDE.md` phải tồn tại ở thư mục gốc dự án, và marker `claudeos-core/generated/pass3-complete.json` phải được ghi.
+**Chế độ từng stage (khuyến nghị cho mọi kích thước dự án):**
+
+Pipeline tự động chạy các stage sau. Danh sách stage:
+
+| Stage | Ghi | Ghi chú |
+|---|---|---|
+| `3a` | `pass3a-facts.md` (fact sheet đã chắt lọc 5–10 KB) | Đọc `pass2-merged.json` một lần; stage sau tham chiếu file này |
+| `3b-core` | `CLAUDE.md`, `standard/` chung, `.claude/rules/` chung | File xuyên dự án; không output đặc thù domain |
+| `3b-1..N` | `standard/60.domains/*.md` đặc thù domain + rule domain | Batch ≤15 domain mỗi stage (tự động chia ở ≥16 domain) |
+| `3c-core` | `guide/` (9 file), `skills/00.shared/MANIFEST.md`, orchestrator `skills/*/` | Skill chung và tất cả guide hướng người dùng |
+| `3c-1..N` | Sub-skill domain dưới `skills/20.frontend-page/scaffold-page-feature/` | Batch ≤15 domain mỗi stage |
+| `3d-aux` | `database/`, `mcp-guide/` | Kích thước cố định, không phụ thuộc số domain |
+
+Cho dự án 1–15 domain, điều này mở rộng thành 4 stage (`3a`, `3b-core`, `3c-core`, `3d-aux` — không chia batch). Cho 16–30 domain, mở rộng thành 8 stage (`3b` và `3c` mỗi cái chia thành 2 batch). Xem [Tự Động Mở Rộng Theo Kích Thước Dự Án](#tự-động-mở-rộng-theo-kích-thước-dự-án) để có bảng đầy đủ.
+
+**Xác minh:** `CLAUDE.md` phải tồn tại ở thư mục gốc dự án, và marker `claudeos-core/generated/pass3-complete.json` phải được ghi. Ở chế độ split, marker chứa `mode: "split"` và một mảng `groupsCompleted` liệt kê mọi stage đã hoàn thành — logic partial-marker dùng thông tin này để resume từ stage đúng sau khi crash thay vì bắt đầu lại từ `3a` (sẽ nhân đôi chi phí token).
 
-> **Lưu ý (v2.0.0):** Pass 3 ghi các file rule vào `claudeos-core/generated/.staged-rules/` trước, vì chính sách sensitive-path của Claude Code chặn ghi trực tiếp vào `.claude/`. Pipeline tự động (`npx claudeos-core init`) xử lý việc di chuyển tự động. Nếu bạn chạy bước này thủ công, bạn cần tự di chuyển cây staging: `mv claudeos-core/generated/.staged-rules/* .claude/rules/` (giữ nguyên subpath).
+> **Lưu ý staging:** Pass 3 ghi các file rule vào `claudeos-core/generated/.staged-rules/` trước vì chính sách sensitive-path của Claude Code chặn ghi trực tiếp vào `.claude/`. Pipeline tự động xử lý việc di chuyển sau mỗi stage. Nếu bạn chạy một stage thủ công, bạn cần tự di chuyển cây staged: `mv claudeos-core/generated/.staged-rules/* .claude/rules/` (giữ nguyên subpath).
 
 #### Step 7: Pass 4 — Memory scaffolding
 
@@ -340,7 +376,9 @@ cat claudeos-core/generated/pass4-prompt.md \
   | claude -p --dangerously-skip-permissions
 ```
 
-**Xác minh:** `claudeos-core/memory/` phải chứa 4 file (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`), `.claude/rules/60.memory/` phải chứa 4 file rule, `claudeos-core/plan/50.memory-master.md` phải tồn tại, và `CLAUDE.md` giờ phải có mục `## Memory (L4)` được append. Marker: `claudeos-core/generated/pass4-memory.json`.
+**Xác minh:** `claudeos-core/memory/` phải chứa 4 file (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`), `.claude/rules/60.memory/` phải chứa 4 file rule, và `CLAUDE.md` giờ phải có mục `## Memory (L4)` được append. Marker: `claudeos-core/generated/pass4-memory.json`.
+
+> **Gap-fill v2.1.0:** Pass 4 cũng đảm bảo `claudeos-core/skills/00.shared/MANIFEST.md` tồn tại. Nếu Pass 3c bỏ sót (có thể xảy ra ở các dự án ít skill vì template stack `pass3.md` liệt kê `MANIFEST.md` là mục tiêu tạo mà không đánh dấu REQUIRED), gap-fill tạo stub tối thiểu để `.claude/rules/50.sync/03.skills-sync.md` luôn có tham chiếu hợp lệ. Idempotent: bỏ qua nếu file đã có nội dung thực (>20 ký tự).
 
 > **Lưu ý:** Nếu `claude -p` lỗi hoặc thiếu `pass4-prompt.md`, pipeline tự động sẽ fallback về scaffold tĩnh qua `lib/memory-scaffold.js` (có dịch qua Claude khi `--lang` khác tiếng Anh). Fallback tĩnh chỉ chạy bên trong `npx claudeos-core init` — chế độ thủ công yêu cầu Pass 4 thành công.
 
@@ -396,31 +434,42 @@ ls .claude/rules/*/
 ```
 npx claudeos-core init
     │
-    ├── [1] npm install                    ← Dependencies (~10s)
-    ├── [2] Cấu trúc thư mục               ← Tạo folder (~1s)
-    ├── [3] plan-installer (Node.js)       ← Quét dự án (~5s)
+    ├── [1] npm install                        ← Dependencies (~10s)
+    ├── [2] Cấu trúc thư mục                   ← Tạo folder (~1s)
+    ├── [3] plan-installer (Node.js)           ← Quét dự án (~5s)
     │       ├── Tự phát hiện stack (multi-stack aware)
     │       ├── Trích domain list (tag: backend/frontend)
     │       ├── Chia thành domain group (theo kiểu)
+    │       ├── Xây pass3-context.json (slim summary, v2.1.0)
     │       └── Chọn prompt theo stack (theo kiểu)
     │
-    ├── [4] Pass 1 × N  (claude -p)       ← Phân tích code sâu (~2-8min)
+    ├── [4] Pass 1 × N  (claude -p)            ← Phân tích code sâu (~2-8min)
     │       ├── ⚙️ Backend group → prompt backend
     │       └── 🎨 Frontend group → prompt frontend
     │
-    ├── [5] Pass 2 × 1  (claude -p)       ← Merge phân tích (~1min)
-    │       └── Tổng hợp TẤT CẢ kết quả Pass 1 (backend + frontend)
+    ├── [5] Pass 2 × 1  (claude -p)            ← Merge phân tích (~1min)
+    │       └── Tổng hợp TẤT CẢ kết quả Pass 1 vào pass2-merged.json
     │
-    ├── [6] Pass 3 × 1  (claude -p)       ← Tạo mọi thứ (~3-5min)
-    │       └── Prompt kết hợp (mục tiêu backend + frontend)
+    ├── [6] Pass 3 (split mode, v2.1.0)        ← Tạo mọi thứ
+    │       │
+    │       ├── 3a     × 1  (claude -p)        ← Trích xuất fact (~5-10min)
+    │       │       └── Đọc pass2-merged.json một lần → pass3a-facts.md
+    │       │
+    │       ├── 3b-core × 1  (claude -p)       ← CLAUDE.md + standard/rules chung
+    │       ├── 3b-1..N × N  (claude -p)       ← Standard/rules domain (≤15 domain/batch)
+    │       │
+    │       ├── 3c-core × 1  (claude -p)       ← Guides + skill chung + MANIFEST.md
+    │       ├── 3c-1..N × N  (claude -p)       ← Sub-skill domain (≤15 domain/batch)
+    │       │
+    │       └── 3d-aux  × 1  (claude -p)       ← Stub database/ + mcp-guide/
     │
-    ├── [7] Pass 4 × 1  (claude -p)       ← Memory scaffolding (~30s)
-    │       ├── Khởi tạo memory/ (decision-log, failure-patterns, …)
+    ├── [7] Pass 4 × 1  (claude -p)            ← Memory scaffolding (~30s-5min)
+    │       ├── Seed memory/ (decision-log, failure-patterns, …)
     │       ├── Tạo rules 60.memory/
     │       ├── Append mục "Memory (L4)" vào CLAUDE.md
-    │       └── Xây dựng plan 50.memory-master.md
+    │       └── Gap-fill: đảm bảo skills/00.shared/MANIFEST.md tồn tại (v2.1.0)
     │
-    └── [8] Xác minh                       ← Tự chạy health checker
+    └── [8] Xác minh                           ← Tự chạy health checker
 ```
 
 ### Tại sao 4 Pass?
@@ -429,9 +478,17 @@ npx claudeos-core init
 
 **Pass 2** merge tất cả kết quả Pass 1 thành phân tích thống nhất: pattern chung (100% share), pattern đa số (50%+ share), pattern đặc thù domain, anti-pattern theo mức độ nghiêm trọng và các mối quan tâm cross-cutting (naming, security, DB, testing, logging, performance). Kết quả backend và frontend được merge cùng nhau.
 
-**Pass 3** nhận phân tích đã merge và tạo toàn bộ hệ sinh thái file (CLAUDE.md, rules, standards, skills, guides). Nó không bao giờ đọc mã nguồn — chỉ đọc JSON phân tích. Ở chế độ multi-stack, prompt tạo kết hợp cả mục tiêu backend và frontend để cả hai bộ standard đều được tạo trong một pass.
+**Pass 3** (split mode, v2.1.0) nhận phân tích đã merge và tạo toàn bộ hệ sinh thái file (CLAUDE.md, rules, standards, skills, guides) qua nhiều lời gọi `claude -p` tuần tự. Insight quan trọng là tràn output do tích lũy không thể dự đoán từ kích thước input: Pass 3 lời-gọi-đơn hoạt động tốt trên dự án 2 domain và thất bại nhất quán ở ~5 domain, và ranh giới thất bại thay đổi tùy theo mức độ dài dòng của mỗi file. Split mode né hoàn toàn vấn đề này — mỗi stage bắt đầu với context window mới và ghi một tập con file có giới hạn. Tính nhất quán xuyên stage (vốn là lợi thế chính của phương pháp lời-gọi-đơn) được bảo tồn bởi `pass3a-facts.md`, một fact sheet đã chắt lọc 5–10 KB mà mọi stage sau tham chiếu.
+
+Template prompt Pass 3 cũng bao gồm **block Phase 1 "Read Once, Extract Facts"** với năm rule ràng buộc thêm khối lượng output:
 
-**Pass 4** scaffold L4 Memory layer: các file kiến thức team bền vững (decision-log, failure-patterns, compaction policy, auto-rule-update) cộng với rules `60.memory/` chỉ dẫn các session tương lai khi nào và cách đọc/ghi các file đó. Memory layer là thứ giúp Claude Code tích lũy bài học qua các session thay vì phải khám phá lại mỗi lần. Khi `--lang` khác tiếng Anh, nội dung fallback tĩnh được dịch qua Claude trước khi ghi.
+- **Rule A** — Tham chiếu bảng fact; không đọc lại `pass2-merged.json`.
+- **Rule B** — Ghi file idempotent (bỏ qua nếu target đã có nội dung thực), giúp Pass 3 có thể chạy lại an toàn sau khi gián đoạn.
+- **Rule C** — Tính nhất quán xuyên file được đảm bảo qua bảng fact như single source of truth.
+- **Rule D** — Output cô đọng: một dòng (`[WRITE]`/`[SKIP]`) giữa các lần ghi file, không nhắc lại bảng fact, không echo nội dung file.
+- **Rule E** — Kiểm tra idempotent theo batch: một `Glob` lúc bắt đầu PHASE 2 thay vì gọi `Read` từng target.
+
+**Pass 4** scaffold L4 Memory layer: các file kiến thức team bền vững (decision-log, failure-patterns, compaction policy, auto-rule-update) cộng với rules `60.memory/` chỉ dẫn các session tương lai khi nào và cách đọc/ghi các file đó. Memory layer là thứ giúp Claude Code tích lũy bài học qua các session thay vì phải khám phá lại mỗi lần. Khi `--lang` khác tiếng Anh, nội dung fallback tĩnh được dịch qua Claude trước khi ghi. v2.1.0 thêm gap-fill cho `skills/00.shared/MANIFEST.md` phòng trường hợp Pass 3c bỏ sót.
 
 ---
 
@@ -459,23 +516,30 @@ your-project/
 │   │   ├── pass1-backend-prompt.md    ← Prompt phân tích backend
 │   │   ├── pass1-frontend-prompt.md   ← Prompt phân tích frontend (nếu phát hiện)
 │   │   ├── pass2-prompt.md            ← Prompt merge
-│   │   ├── pass3-prompt.md            ← Prompt tạo (kết hợp)
+│   │   ├── pass2-merged.json          ← Output Pass 2 (chỉ Pass 3a tiêu thụ)
+│   │   ├── pass3-context.json         ← Slim summary (< 5 KB) cho Pass 3 (v2.1.0)
+│   │   ├── pass3-prompt.md            ← Template prompt Pass 3 (block Phase 1 được thêm trước)
+│   │   ├── pass3a-facts.md            ← Fact sheet được ghi bởi Pass 3a, đọc bởi 3b/3c/3d (v2.1.0)
 │   │   ├── pass4-prompt.md            ← Prompt memory scaffolding (v2.0.0)
-│   │   ├── pass3-complete.json        ← Marker hoàn thành Pass 3 (bỏ qua khi resume)
+│   │   ├── pass3-complete.json        ← Marker hoàn thành Pass 3 (split mode: bao gồm groupsCompleted, v2.1.0)
 │   │   ├── pass4-memory.json          ← Marker hoàn thành Pass 4 (bỏ qua khi resume)
+│   │   ├── rule-manifest.json         ← Index file cho công cụ xác minh
+│   │   ├── sync-map.json              ← Mapping Plan ↔ disk (rỗng ở v2.1.0; giữ lại để tương thích sync-checker)
+│   │   ├── stale-report.json          ← Kết quả xác minh tổng hợp
 │   │   ├── .i18n-cache-<lang>.json    ← Cache bản dịch (`--lang` khác tiếng Anh)
 │   │   └── .staged-rules/             ← Thư mục staging tạm cho ghi `.claude/rules/` (tự động di chuyển + dọn)
-│   ├── standard/                      ← Coding standards (15-19 file)
+│   ├── standard/                      ← Coding standards (15-19 file + theo domain ở 60.domains/)
 │   │   ├── 00.core/                   ← Tổng quan, kiến trúc, naming
 │   │   ├── 10.backend-api/            ← API pattern (theo stack)
 │   │   ├── 20.frontend-ui/            ← Frontend pattern (nếu phát hiện)
 │   │   ├── 30.security-db/            ← Security, DB schema, utilities
 │   │   ├── 40.infra/                  ← Config, logging, CI/CD
 │   │   ├── 50.verification/           ← Build verification, testing
+│   │   ├── 60.domains/                ← Standard theo domain (ghi bởi Pass 3b-N, v2.1.0)
 │   │   └── 90.optional/               ← Convention tùy chọn (mở rộng theo stack)
-│   ├── skills/                        ← Skills scaffold CRUD
+│   ├── skills/                        ← Skills scaffold CRUD/page
+│   │   └── 00.shared/MANIFEST.md      ← Single source of truth cho skill đã đăng ký
 │   ├── guide/                         ← Onboarding, FAQ, troubleshooting (9 file)
-│   ├── plan/                          ← Master plans (backup/restore)
 │   ├── database/                      ← DB schema, hướng dẫn migration
 │   ├── mcp-guide/                     ← Hướng dẫn tích hợp MCP server
 │   └── memory/                        ← L4: kiến thức team (4 file) — commit các file này
@@ -489,12 +553,14 @@ your-project/
 
 Mọi file standard đều bao gồm ví dụ đúng ✅, ví dụ sai ❌, và bảng tóm tắt rule — tất cả đều được trích xuất từ pattern code thực tế của bạn, không phải template chung chung.
 
+> **Lưu ý v2.1.0:** `claudeos-core/plan/` không còn được tạo nữa. Master plan là backup nội bộ mà Claude Code không tiêu thụ lúc runtime, và việc tổng hợp chúng trong Pass 3 là nguyên nhân chính gây tràn output. Dùng `git` để backup/restore thay thế. Các dự án upgrade từ v2.0.x có thể xóa an toàn thư mục `claudeos-core/plan/` hiện có.
+
 ### Đề xuất gitignore
 
 **Nên commit** (kiến thức team — có mục đích chia sẻ):
 - `CLAUDE.md` — entry point của Claude Code
 - `.claude/rules/**` — rules tự động load
-- `claudeos-core/standard/**`, `skills/**`, `guide/**`, `database/**`, `mcp-guide/**`, `plan/**` — tài liệu được tạo
+- `claudeos-core/standard/**`, `skills/**`, `guide/**`, `database/**`, `mcp-guide/**`, `plan/**` — tài liệu được tạo (lưu ý: `plan/**` không còn được tạo ở v2.1.0)
 - `claudeos-core/memory/**` — lịch sử quyết định, failure pattern, đề xuất rule
 
 **KHÔNG commit** (build artifact có thể tạo lại):
@@ -510,14 +576,38 @@ Thư mục `generated/` chứa JSON phân tích (`pass1-*.json`, `pass2-merged.j
 
 ## Tự Động Mở Rộng Theo Kích Thước Dự Án
 
-| Kích thước | Domain | Số lần Pass 1 | Tổng `claude -p` | Thời gian ước tính |
+Split mode của Pass 3 mở rộng số stage theo số domain. Việc chia batch kích hoạt ở 16 domain để giữ output mỗi stage dưới ~50 file, là khoảng an toàn thực nghiệm cho `claude -p` trước khi tràn output do tích lũy.
+
+| Kích thước | Domain | Số stage Pass 3 | Tổng `claude -p` | Thời gian ước tính |
 |---|---|---|---|---|
-| Nhỏ | 1–4 | 1 | 4 (Pass 1 + 2 + 3 + 4) | ~5–6min |
-| Vừa | 5–8 | 2 | 5 | ~8–9min |
-| Lớn | 9–16 | 3–4 | 6–7 | ~12–13min |
-| Rất lớn | 17+ | 5+ | 8+ | ~18min+ |
+| Nhỏ | 1–4 | 4 (`3a`, `3b-core`, `3c-core`, `3d-aux`) | 7 (Pass 1 + 2 + 4 stage Pass 3 + Pass 4) | ~10–15 phút |
+| Vừa | 5–15 | 4 | 8–9 | ~25–45 phút |
+| Lớn | 16–30 | **8** (3b, 3c mỗi cái chia thành 2 batch) | 11–12 | **~60–105 phút** |
+| Rất lớn | 31–45 | 10 | 13–14 | ~100–150 phút |
+| Siêu lớn | 46–60 | 12 | 15–16 | ~150–200 phút |
+| Cực lớn | 61+ | 14+ | 17+ | 200 phút+ |
+
+Công thức số stage (khi chia batch): `1 (3a) + 1 (3b-core) + N (3b-1..N) + 1 (3c-core) + N (3c-1..N) + 1 (3d-aux) = 2N + 4`, với `N = ceil(totalDomains / 15)`.
 
-Pass 4 (memory scaffolding) thêm khoảng ~30s lên trên các pass phân tích. Với dự án multi-stack (ví dụ Java + React), domain backend và frontend được đếm cộng lại. Dự án 6 backend + 4 frontend = 10 tổng, mở rộng như "Lớn".
+Pass 4 (memory scaffolding) thêm khoảng ~30 giây đến 5 phút lên trên tùy thuộc vào việc chạy tạo qua Claude hay fallback tĩnh. Với dự án multi-stack (ví dụ Java + React), domain backend và frontend được đếm cộng lại. Dự án 6 backend + 4 frontend = 10 tổng = tier Vừa.
+
+### Thực tế production: admin frontend 18 domain (2026-04-20)
+
+Một admin frontend React 19 + Vite 6 + TypeScript với 18 domain và 6 domain group hoàn thành end-to-end trong **102 phút với 101 file được tạo**. Phân bổ stage:
+
+| Stage | File | Thời gian | File/phút |
+|---|---|---|---|
+| `3a` (trích xuất fact) | 1 (`pass3a-facts.md`) | 8m 44s | — |
+| `3b-core` (CLAUDE.md + chung) | 24 | 22m 10s | 1.1 |
+| `3b-1` (15 domain) | 30 | 10m 6s | **3.0** |
+| `3b-2` (3 domain) | 6 | 4m 34s | 1.3 |
+| `3c-core` (guide + chung) | 11 | 8m 31s | 1.3 |
+| `3c-1` (15 domain) | 8 | 5m 11s | **1.5** |
+| `3c-2` (3 domain) | 3 | 3m 50s | 0.8 |
+| `3d-aux` (database + mcp) | 3 | 2m 52s | 1.0 |
+| Pass 4 | 12 | 5m 36s | 2.1 |
+
+Throughput cao rõ rệt ở các stage domain theo batch (3b-1: 3.0 file/phút vs. 3b-core: 1.1 file/phút) vì các stage context mới được hưởng lợi từ các pattern chặt chẽ, lặp lại cho từng domain. Xác minh toàn xanh: `plan-validator`, `sync-checker`, `content-validator`, `pass-json-validator` — 0 lỗi tràn, 0 file bị cắt.
 
 ---
 
@@ -543,11 +633,11 @@ node claudeos-core-tools/sync-checker/index.js
 
 | Công cụ | Chức năng |
 |---|---|
-| **manifest-generator** | Tạo JSON metadata (rule-manifest, sync-map, plan-manifest); index 7 thư mục bao gồm `memory/` (`totalMemory` trong summary) |
-| **plan-validator** | So sánh block `<file>` Master Plan với disk — 3 chế độ: check, refresh, restore |
-| **sync-checker** | Phát hiện file chưa đăng ký (trên disk nhưng không có trong plan) và entry orphan — bao phủ 7 thư mục (thêm `memory/` ở v2.0.0) |
+| **manifest-generator** | Tạo JSON metadata (`rule-manifest.json`, `sync-map.json`, khởi tạo `stale-report.json`); index 7 thư mục bao gồm `memory/` (`totalMemory` trong summary). v2.1.0: `plan-manifest.json` không còn được tạo vì master plan đã bị loại bỏ. |
+| **plan-validator** | Xác minh block `<file>` master plan với disk cho các dự án vẫn còn `claudeos-core/plan/` (trường hợp upgrade legacy). v2.1.0: bỏ qua tạo `plan-sync-status.json` khi `plan/` vắng mặt hoặc rỗng — `stale-report.json` vẫn ghi một no-op pass. |
+| **sync-checker** | Phát hiện file chưa đăng ký (trên disk nhưng không có trong plan) và entry orphan — bao phủ 7 thư mục (thêm `memory/` ở v2.0.0). Thoát sạch khi `sync-map.json` không có mapping nào (trạng thái mặc định của v2.1.0). |
 | **content-validator** | Kiểm tra chất lượng 9 mục — file rỗng, thiếu ví dụ ✅/❌, mục bắt buộc, cộng với toàn vẹn scaffold L4 memory (ngày heading decision-log, trường bắt buộc failure-pattern, parse nhận biết fence) |
-| **pass-json-validator** | Xác minh cấu trúc JSON Pass 1–4 cộng với marker hoàn thành `pass3-complete.json` và `pass4-memory.json` |
+| **pass-json-validator** | Xác minh cấu trúc JSON Pass 1–4 cộng với marker hoàn thành `pass3-complete.json` (shape split-mode, v2.1.0) và `pass4-memory.json` |
 
 ---
 
@@ -584,7 +674,7 @@ Các folder này được loại trừ rõ ràng qua mục `DO NOT Read` trong r
 
 | Folder | Lý do loại trừ |
 |---|---|
-| `claudeos-core/plan/` | Master Plan backup (~340KB). Dùng `npx claudeos-core refresh` để sync. |
+| `claudeos-core/plan/` | Master Plan backup từ các dự án legacy (v2.0.x và trước đó). Không tạo ở v2.1.0. Nếu có mặt, Claude Code sẽ không tự động load — chỉ đọc theo yêu cầu. |
 | `claudeos-core/generated/` | JSON metadata build, prompt, Pass marker, translation cache, `.staged-rules/`. Không dùng cho coding. |
 | `claudeos-core/guide/` | Hướng dẫn onboarding cho con người. |
 | `claudeos-core/mcp-guide/` | Tài liệu MCP server. Không dùng cho coding. |
@@ -616,7 +706,12 @@ npx claudeos-core health
 ### Khi Docs Bị Hỏng
 
 ```bash
-# Khôi phục mọi thứ từ Master Plan
+# Khuyến nghị v2.1.0: dùng git để khôi phục (vì master plan không còn
+# được tạo nữa). Commit tài liệu được tạo thường xuyên để có thể rollback
+# từng file cụ thể mà không cần tạo lại:
+git checkout HEAD -- .claude/rules/ claudeos-core/
+
+# Legacy (dự án v2.0.x vẫn còn claudeos-core/plan/):
 npx claudeos-core restore
 ```
 
@@ -643,8 +738,13 @@ npx claudeos-core memory propose-rules
 #   Tính confidence (sigmoid trên weighted evidence × anchor multiplier)
 #   Ghi proposal vào memory/auto-rule-update.md (KHÔNG tự động áp dụng)
 #   Confidence ≥ 0.70 đáng xem xét nghiêm túc; nếu accept → sửa rule + log quyết định
+
+# v2.1.0: `memory --help` giờ route tới help subcommand (trước đây hiển thị top-level)
+npx claudeos-core memory --help
 ```
 
+> **Fix v2.1.0:** `memory score` không còn để lại dòng `importance` trùng lặp sau lần chạy đầu (trước đây dòng được tự chấm điểm được thêm ở trên trong khi dòng nguyên bản bị bỏ lại bên dưới). Marker summary Stage 1 của `memory compact` giờ là markdown list item đúng định dạng (`- _Summarized on ..._`) nên render sạch và được parse lại đúng ở các lần compact sau.
+
 Khi nào ghi vào memory (Claude làm theo yêu cầu, nhưng bạn cũng có thể sửa thủ công):
 - **`decision-log.md`** — append entry mới bất cứ khi nào bạn chọn giữa các pattern cạnh tranh, chọn thư viện, định nghĩa convention team, hoặc quyết định KHÔNG làm gì đó. Chỉ append; không bao giờ sửa entry lịch sử.
 - **`failure-patterns.md`** — append vào **lần xuất hiện thứ hai** của lỗi lặp lại hoặc nguyên nhân không hiển nhiên. Lỗi lần đầu không cần entry.
@@ -707,19 +807,22 @@ Bạn có thể dùng ClaudeOS-Core để tạo rule cho dự án, rồi dùng E
 Không. Nó chỉ tạo `CLAUDE.md`, `.claude/rules/`, và `claudeos-core/`. Code hiện có của bạn không bao giờ bị sửa.
 
 **Q: Chi phí là bao nhiêu?**
-Nó gọi `claude -p` 4–8 lần (Pass 1 × N + Pass 2 + Pass 3 + Pass 4). Nằm trong mức sử dụng Claude Code bình thường. Khi `--lang` khác tiếng Anh, đường fallback tĩnh có thể gọi thêm vài `claude -p` để dịch; kết quả được cache trong `claudeos-core/generated/.i18n-cache-<lang>.json` nên các lần chạy sau dùng lại.
+Nó gọi `claude -p` vài lần qua 4 pass. Ở split mode v2.1.0, chỉ riêng Pass 3 đã mở rộng thành 4–14+ stage tùy theo kích thước dự án (xem [Tự Động Mở Rộng](#tự-động-mở-rộng-theo-kích-thước-dự-án)). Một dự án nhỏ điển hình (1–15 domain) dùng tổng cộng 8–9 lời gọi `claude -p`; dự án 18 domain dùng 11; dự án 60 domain dùng 15–17. Mỗi stage chạy với context window mới — chi phí token mỗi lời gọi thực ra thấp hơn Pass 3 lời-gọi-đơn, vì không stage nào phải giữ toàn bộ cây file trong một context. Khi `--lang` khác tiếng Anh, đường fallback tĩnh có thể gọi thêm vài `claude -p` để dịch; kết quả được cache trong `claudeos-core/generated/.i18n-cache-<lang>.json` nên các lần chạy sau dùng lại. Vẫn nằm trong mức sử dụng Claude Code bình thường.
+
+**Q: Pass 3 split mode là gì và tại sao được thêm ở v2.1.0?**
+Trước v2.1.0, Pass 3 thực hiện một lời gọi `claude -p` đơn phải phát ra toàn bộ cây file được tạo (`CLAUDE.md`, standards, rules, skills, guides — thường 30–60 file) trong một response. Điều này hoạt động trên dự án nhỏ nhưng luôn gặp lỗi `Prompt is too long` do tích lũy output ở ~5 domain. Lỗi không thể dự đoán từ kích thước input — nó phụ thuộc vào mức độ dài dòng của mỗi file được tạo, và có thể ập đến cùng một dự án một cách không ổn định. Split mode né vấn đề này về cấu trúc: Pass 3 được chia thành các stage tuần tự (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`), mỗi cái là một lời gọi `claude -p` riêng với context window mới. Tính nhất quán xuyên stage được bảo tồn bởi `pass3a-facts.md`, fact sheet đã chắt lọc 5–10 KB mà mọi stage sau tham chiếu thay vì đọc lại `pass2-merged.json`. Marker `pass3-complete.json` mang mảng `groupsCompleted` để crash trong `3c-2` resume từ `3c-2` (không phải từ `3a`), tránh chi phí token gấp đôi. Đã xác minh thực nghiệm lên tới 18 domain × 101 file × 102 phút với 0 tràn — xem [Tự Động Mở Rộng](#tự-động-mở-rộng-theo-kích-thước-dự-án) cho phân tích production thực tế.
 
 **Q: Tôi có nên commit các file được tạo vào Git không?**
 Có, khuyến nghị. Team của bạn có thể chia sẻ cùng standard Claude Code. Hãy xem xét thêm `claudeos-core/generated/` vào `.gitignore` (JSON phân tích có thể tạo lại).
 
 **Q: Còn dự án mixed-stack (ví dụ Java backend + React frontend)?**
-Được hỗ trợ hoàn toàn. ClaudeOS-Core tự phát hiện cả hai stack, gắn tag domain là `backend` hoặc `frontend`, và dùng prompt phân tích theo stack cho mỗi cái. Pass 2 merge mọi thứ, và Pass 3 tạo cả standard backend và frontend trong một pass.
+Được hỗ trợ hoàn toàn. ClaudeOS-Core tự phát hiện cả hai stack, gắn tag domain là `backend` hoặc `frontend`, và dùng prompt phân tích theo stack cho mỗi cái. Pass 2 merge mọi thứ, và Pass 3 tạo cả standard backend và frontend qua các split stage — domain backend rơi vào một số batch 3b/3c, domain frontend vào các batch khác, tất cả đều tham chiếu cùng `pass3a-facts.md` để có tính nhất quán.
 
 **Q: Nó có hoạt động với monorepo Turborepo / pnpm workspaces / Lerna không?**
 Có. ClaudeOS-Core phát hiện `turbo.json`, `pnpm-workspace.yaml`, `lerna.json`, hoặc `package.json#workspaces` và tự động quét file `package.json` của sub-package để tìm dependency framework/ORM/DB. Quét domain bao phủ pattern `apps/*/src/` và `packages/*/src/`. Chạy từ root monorepo.
 
 **Q: Chạy lại thì chuyện gì xảy ra?**
-Nếu kết quả Pass 1/2 trước đó tồn tại, một prompt tương tác cho bạn chọn: **Continue** (tiếp tục từ chỗ dừng) hoặc **Fresh** (xóa tất cả và bắt đầu lại). Dùng `--force` để bỏ qua prompt và luôn bắt đầu mới. Pass 3 luôn chạy lại. Các phiên bản trước có thể được khôi phục từ Master Plan.
+Nếu kết quả Pass 1/2 trước đó tồn tại, một prompt tương tác cho bạn chọn: **Continue** (tiếp tục từ chỗ dừng) hoặc **Fresh** (xóa tất cả và bắt đầu lại). Dùng `--force` để bỏ qua prompt và luôn bắt đầu mới. Ở split mode v2.1.0, resume Pass 3 hoạt động ở mức độ stage — nếu lần chạy crash trong `3c-2`, `init` tiếp theo resume từ `3c-2` thay vì bắt đầu lại từ `3a` (sẽ nhân đôi chi phí token). Marker `pass3-complete.json` ghi `mode: "split"` cộng với mảng `groupsCompleted` để điều khiển logic này.
 
 **Q: NestJS có template riêng hay dùng của Express?**
 NestJS dùng template `node-nestjs` chuyên dụng với các danh mục phân tích đặc thù NestJS: decorator `@Module`, `@Injectable`, `@Controller`, Guards, Pipes, Interceptors, DI container, pattern CQRS, và `Test.createTestingModule`. Dự án Express dùng template `node-express` riêng biệt.
@@ -746,10 +849,16 @@ Pipeline tự động (`npx claudeos-core init`) có static fallback: nếu `cla
 Xem mục [Bảo Trì Memory Layer](#bảo-trì-memory-layer-v200) ở trên. Phiên bản ngắn: `compact` chạy chính sách 4 giai đoạn (tóm tắt cũ, merge trùng, bỏ importance thấp cũ, áp dụng giới hạn 400 dòng); `score` xếp hạng lại `failure-patterns.md` theo importance (frequency × recency); `propose-rules` nổi bật candidate rule addition từ failure lặp lại vào `auto-rule-update.md` (không tự động áp dụng — xem và accept/reject thủ công).
 
 **Q: Tại sao `--force` (hoặc chế độ "fresh" resume) xóa `.claude/rules/`?**
-v2.0.0 thêm ba silent-failure guard cho Pass 3 (Guard 3 bao phủ hai biến thể output không đầy đủ: H2 cho `guide/` và H1 cho `standard/skills/plan`). Guard 1 ("partial staged-rules move") và Guard 3 ("incomplete output — missing/empty guide files or missing standard sentinel / empty skills / empty plan") không phụ thuộc vào rule hiện có, nhưng Guard 2 ("zero rules detected") thì có — nó kích hoạt khi Claude bỏ qua directive `staging-override.md` và thử ghi trực tiếp vào `.claude/` (nơi chính sách sensitive-path của Claude Code chặn). Rule cũ từ lần chạy trước sẽ khiến Guard 2 false-negative — nên `--force`/`fresh` xóa `.claude/rules/` để đảm bảo phát hiện sạch. **Sửa rule thủ công sẽ bị mất** dưới `--force`/`fresh`; hãy backup trước nếu cần.
+v2.0.0 thêm ba silent-failure guard cho Pass 3 (Guard 3 bao phủ hai biến thể output không đầy đủ: H2 cho `guide/` và H1 cho `standard/skills`). Guard 1 ("partial staged-rules move") và Guard 3 ("incomplete output — missing/empty guide files or missing standard sentinel / empty skills") không phụ thuộc vào rule hiện có, nhưng Guard 2 ("zero rules detected") thì có — nó kích hoạt khi Claude bỏ qua directive `staging-override.md` và thử ghi trực tiếp vào `.claude/` (nơi chính sách sensitive-path của Claude Code chặn). Rule cũ từ lần chạy trước sẽ khiến Guard 2 false-negative — nên `--force`/`fresh` xóa `.claude/rules/` để đảm bảo phát hiện sạch. **Sửa rule thủ công sẽ bị mất** dưới `--force`/`fresh`; hãy backup trước nếu cần. (Lưu ý v2.1.0: Guard 3 H1 không còn kiểm tra `plan/` vì master plan không còn được tạo.)
 
 **Q: `claudeos-core/generated/.staged-rules/` là gì và tại sao tồn tại?**
-Chính sách sensitive-path của Claude Code từ chối ghi trực tiếp vào `.claude/` từ subprocess `claude -p` (ngay cả với `--dangerously-skip-permissions`). v2.0.0 đi vòng bằng cách cho prompt Pass 3/4 chuyển hướng mọi ghi `.claude/rules/` vào thư mục staging; orchestrator Node.js (không chịu chính sách đó) sau đó di chuyển cây staged vào `.claude/rules/` sau mỗi pass. Điều này trong suốt với người dùng — thư mục được tự tạo, tự dọn, và tự di chuyển. Nếu lần chạy trước crash giữa chừng di chuyển, lần chạy sau xóa staging dir trước khi thử lại.
+Chính sách sensitive-path của Claude Code từ chối ghi trực tiếp vào `.claude/` từ subprocess `claude -p` (ngay cả với `--dangerously-skip-permissions`). v2.0.0 đi vòng bằng cách cho prompt Pass 3/4 chuyển hướng mọi ghi `.claude/rules/` vào thư mục staging; orchestrator Node.js (không chịu chính sách đó) sau đó di chuyển cây staged vào `.claude/rules/` sau mỗi pass. Điều này trong suốt với người dùng — thư mục được tự tạo, tự dọn, và tự di chuyển. Nếu lần chạy trước crash giữa chừng di chuyển, lần chạy sau xóa staging dir trước khi thử lại. Ở split mode v2.1.0, stage runner di chuyển staged rules vào `.claude/rules/` sau mỗi stage (không chỉ cuối cùng), nên crash giữa Pass 3 vẫn để lại rule của các stage đã hoàn thành trước đó tại chỗ.
+
+**Q: Tôi có thể chạy Pass 3 thủ công thay vì `npx claudeos-core init` không?**
+Có cho dự án nhỏ (≤5 domain) — hướng dẫn thủ công lời-gọi-đơn ở [Step 6](#step-6-pass-3--tạo-toàn-bộ-tài-liệu-chia-thành-nhiều-stage) vẫn hoạt động. Cho dự án lớn hơn bạn nên dùng `npx claudeos-core init` vì split runner là cái điều phối thực thi từng stage với context mới, xử lý chia batch ở ≥16 domain, ghi shape marker `pass3-complete.json` đúng (`mode: "split"` + `groupsCompleted`), và di chuyển staged rules giữa các stage. Tái tạo điều phối đó bằng tay có thể được nhưng mệt mỏi. Nếu bạn có lý do chạy stage thủ công (ví dụ: debug một stage cụ thể), bạn có thể template `pass3-prompt.md` với directive `STAGE:` phù hợp và đưa cho `claude -p` trực tiếp — nhưng nhớ di chuyển `.staged-rules/` sau mỗi stage và tự cập nhật marker.
+
+**Q: Dự án của tôi là upgrade từ v2.0.x và có thư mục `claudeos-core/plan/` hiện hữu. Tôi phải làm gì?**
+Không cần gì cả — công cụ v2.1.0 bỏ qua `plan/` khi nó vắng mặt hoặc rỗng, và `plan-validator` vẫn xử lý các dự án legacy có thư mục `plan/` đã điền để tương thích ngược. Bạn có thể xóa an toàn `claudeos-core/plan/` nếu không cần master plan backup (git history dù sao cũng là backup tốt hơn). Nếu giữ `plan/`, chạy `npx claudeos-core init` sẽ không cập nhật nó — nội dung mới không được tổng hợp vào master plan ở v2.1.0. Công cụ xác minh xử lý sạch cả hai trường hợp.
 
 ---
 
@@ -772,7 +881,7 @@ pass-prompts/templates/
 └── python-flask/            # Python / Flask (Blueprint, app factory, Jinja2)
 ```
 
-`plan-installer` tự phát hiện các stack của bạn, rồi lắp ráp prompt theo kiểu. NestJS, Vue/Nuxt, Vite SPA và Flask mỗi cái dùng template chuyên dụng với danh mục phân tích đặc thù framework (ví dụ: `@Module`/`@Injectable`/Guards cho NestJS; `<script setup>`/Pinia/useFetch cho Vue; client-side routing/`VITE_` env cho Vite; Blueprint/`app.factory`/Flask-SQLAlchemy cho Flask). Cho dự án multi-stack, `pass1-backend-prompt.md` và `pass1-frontend-prompt.md` riêng biệt được tạo, trong khi `pass3-prompt.md` kết hợp mục tiêu tạo của cả hai stack. Pass 4 dùng template chung `common/pass4.md` (memory scaffolding) bất kể stack.
+`plan-installer` tự phát hiện các stack của bạn, rồi lắp ráp prompt theo kiểu. NestJS, Vue/Nuxt, Vite SPA và Flask mỗi cái dùng template chuyên dụng với danh mục phân tích đặc thù framework (ví dụ: `@Module`/`@Injectable`/Guards cho NestJS; `<script setup>`/Pinia/useFetch cho Vue; client-side routing/`VITE_` env cho Vite; Blueprint/`app.factory`/Flask-SQLAlchemy cho Flask). Cho dự án multi-stack, `pass1-backend-prompt.md` và `pass1-frontend-prompt.md` riêng biệt được tạo, trong khi `pass3-prompt.md` kết hợp mục tiêu tạo của cả hai stack. Ở v2.1.0, template Pass 3 được thêm `common/pass3-phase1.md` (block "Read Once, Extract Facts" với Rules A–E) vào đầu trước khi được cắt theo từng stage split-mode. Pass 4 dùng template chung `common/pass4.md` (memory scaffolding) bất kể stack.
 
 ---
 
@@ -842,7 +951,11 @@ my-monorepo/                    ← Chạy ở đây: npx claudeos-core init
 
 **"Pass 3 produced CLAUDE.md and rules but N/9 guide files are missing or empty" (v2.0.0)** — Guard 3 (H2) kích hoạt: Claude bị cắt giữa chừng sau khi viết CLAUDE.md + rules nhưng trước khi hoàn thành (hoặc bắt đầu) mục `claudeos-core/guide/` (mong đợi 9 file). Cũng kích hoạt trên file chỉ có BOM hoặc chỉ có whitespace (heading đã viết nhưng body bị cắt). Không có guard này, completion marker vẫn được ghi, để `guide/` trống vĩnh viễn ở các lần chạy sau. Marker KHÔNG được ghi ở đây, nên lần chạy `init` tiếp theo retry Pass 3 từ cùng kết quả Pass 2. Nếu cứ lặp lại, chạy lại với `npx claudeos-core init --force` để tạo lại từ đầu.
 
-**"Pass 3 finished but the following required output(s) are missing or empty" (v2.0.0)** — Guard 3 (H1) kích hoạt: Claude bị cắt SAU `claudeos-core/guide/` nhưng trước (hoặc trong lúc) `claudeos-core/standard/`, `claudeos-core/skills/`, hoặc `claudeos-core/plan/`. Yêu cầu: (a) `standard/00.core/01.project-overview.md` tồn tại và không rỗng (sentinel được ghi bởi mọi prompt Pass 3 của mọi stack), (b) `skills/` có ≥1 `.md` không rỗng, (c) `plan/` có ≥1 `.md` không rỗng. `database/` và `mcp-guide/` bị loại trừ có chủ đích (một số stack tạo ra 0 file hợp lệ). Đường khôi phục như Guard 3 (H2): chạy lại `init`, hoặc `--force` nếu lỗi vẫn tiếp diễn.
+**"Pass 3 finished but the following required output(s) are missing or empty" (v2.0.0, cập nhật v2.1.0)** — Guard 3 (H1) kích hoạt: Claude bị cắt SAU `claudeos-core/guide/` nhưng trước (hoặc trong lúc) `claudeos-core/standard/` hoặc `claudeos-core/skills/`. Yêu cầu: (a) `standard/00.core/01.project-overview.md` tồn tại và không rỗng (sentinel được ghi bởi mọi prompt Pass 3 của mọi stack), (b) `skills/` có ≥1 `.md` không rỗng. `database/` và `mcp-guide/` bị loại trừ có chủ đích (một số stack tạo ra 0 file hợp lệ). `plan/` không còn được kiểm tra kể từ v2.1.0 (master plan đã bị loại bỏ). Đường khôi phục như Guard 3 (H2): chạy lại `init`, hoặc `--force` nếu lỗi vẫn tiếp diễn.
+
+**"Pass 3 split stage crashed partway through (v2.1.0)"** — Khi một trong các split stage (ví dụ: `3b-1`, `3c-2`) lỗi giữa chừng, marker mức stage KHÔNG được ghi, nhưng các stage đã hoàn thành ĐƯỢC ghi trong `pass3-complete.json.groupsCompleted`. Lần chạy `init` tiếp theo đọc mảng này và resume từ stage chưa hoàn thành đầu tiên, bỏ qua mọi công việc đã hoàn thành trước đó. Bạn không cần làm gì thủ công — chỉ cần chạy lại `npx claudeos-core init`. Nếu resume cứ lỗi ở cùng stage, kiểm tra `claudeos-core/generated/pass3-prompt.md` tìm nội dung bị lỗi, rồi thử `--force` để khởi động lại đầy đủ. Shape `pass3-complete.json` (`mode: "split"`, `groupsCompleted: [...]`) ổn định; một marker thiếu hoặc lỗi sẽ khiến toàn bộ Pass 3 chạy lại từ `3a`.
+
+**"Pass 3 stale marker (shape mismatch) — treating as incomplete" (v2.1.0)** — Một `pass3-complete.json` từ lần chạy lời-gọi-đơn pre-v2.1.0 đang được diễn giải theo luật split-mode mới. Kiểm tra shape tìm `mode: "split"` và mảng `groupsCompleted`; nếu thiếu, marker được coi là partial và Pass 3 chạy lại ở split mode. Nếu bạn upgrade từ v2.0.x, điều này xảy ra một lần là mong đợi — lần chạy tiếp theo sẽ ghi shape marker đúng. Không cần hành động.
 
 **"pass2-merged.json exists but is malformed or incomplete (<5 top-level keys), re-running" (v2.0.0)** — Log thông tin, không phải lỗi. Khi resume, `init` giờ parse và validate `pass2-merged.json` (yêu cầu ≥5 top-level key, phản chiếu ngưỡng `INSUFFICIENT_KEYS` của `pass-json-validator`). Skeleton `{}` hoặc JSON lỗi từ lần chạy crash trước tự động bị xóa và Pass 2 chạy lại. Không cần hành động thủ công — pipeline tự chữa. Nếu cứ lặp lại, kiểm tra `claudeos-core/generated/pass2-prompt.md` và retry với `--force`.
 
@@ -865,7 +978,7 @@ my-monorepo/                    ← Chạy ở đây: npx claudeos-core init
 - **Template stack mới** — Ruby/Rails, Go (Gin/Fiber/Echo), PHP (Laravel/Symfony), Rust (Axum/Actix), Svelte/SvelteKit, Remix
 - **Tích hợp IDE** — VS Code extension, IntelliJ plugin
 - **Template CI/CD** — ví dụ GitLab CI, CircleCI, Jenkins (GitHub Actions đã có — xem `.github/workflows/test.yml`)
-- **Độ phủ test** — Mở rộng test suite (hiện tại 489 test trên 24 file test bao phủ scanner, phát hiện stack, domain grouping, plan parsing, tạo prompt, CLI selector, phát hiện monorepo, phát hiện Vite SPA, công cụ xác minh, L4 memory scaffold, xác thực resume Pass 2, Pass 3 Guards 1/2/3 (sentinel H1 + empty-file nhận biết BOM H2 + unlink marker cũ nghiêm ngặt), xác thực nội dung marker Pass 4 + độ nghiêm ngặt unlink marker cũ, guard env-skip dịch + fail-fast sớm + CI workflow, di chuyển staged-rules, fallback dịch lang-aware, và cấu trúc template AI Work Rules)
+- **Độ phủ test** — Mở rộng test suite (hiện tại 563 test trên 29 file test bao phủ scanner, phát hiện stack, domain grouping, plan parsing, tạo prompt, CLI selector, phát hiện monorepo, phát hiện Vite SPA, công cụ xác minh, L4 memory scaffold, xác thực resume Pass 2, Pass 3 Guards 1/2/3 (sentinel H1 + empty-file nhận biết BOM H2 + unlink marker cũ nghiêm ngặt), chia batch split-mode Pass 3, resume partial-marker Pass 3 (v2.1.0), xác thực nội dung marker Pass 4 + độ nghiêm ngặt unlink marker cũ + gap-fill scaffoldSkillsManifest (v2.1.0), guard env-skip dịch + fail-fast sớm + CI workflow, di chuyển staged-rules, fallback dịch lang-aware, suite regression loại bỏ master plan (v2.1.0), regression định dạng memory score/compact (v2.1.0), và cấu trúc template AI Work Rules)
 
 Xem [`CONTRIBUTING.md`](./CONTRIBUTING.md) để có danh sách đầy đủ các khu vực, code style, commit convention, và hướng dẫn từng bước để thêm template stack mới.