@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/docs/04-reference/commands.md

@@ -1,105 +1,134 @@
-[← Docs Home](../README.md) · [Reference](./)
-
-# Reference · Commands — Bảng đầy đủ (Command Catalog)
-
-> 31 slash command, gom theo phase pipeline. Chi tiết cơ chế từng bước → [Pipeline Steps](../02-concepts/pipeline-steps/).
-
-Mọi lệnh chạy chung một **Gate** (model check → target → context-loader → checkpoint). Xem [Khung chung](../02-concepts/pipeline-steps/README.md#khung-chung-mọi-command-common-gate).
-
----
-
-## 0 · Setup & Foundation
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/setup-ai-first` | Dự án trống/có code | `.agent/`, `.claude/`, `project-context.yaml`, `CLAUDE.md` | Admin/Lead |
-| `/generate-architecture` | config + tài liệu (`--from`) + code | `architecture.md` (SSOT kiến trúc, theo tier) | SA/Lead |
-
-## 1 · Discovery
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/define-product` | Ý tưởng (+Figma) | `product-definition/*.md` (8 chặng) | PO |
-
-## 2 · Specification (PRD)
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-prd` | product-definition | PRD draft | PO |
-| `/refine-prd` | PRD | Findings 3 lăng kính DEV/SA/PO | PO+SA+Dev |
-| `/review-context` (PRD) | PRD | Findings P0–P5 → `Status: approved` | PO |
-
-## 3 · Design-Spec (chỉ FE/App)
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-design-spec` | PRD approved + Figma | `design-spec/*.md` | PO/PM |
-
-## 4 · BDD
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-bdd` | PRD approved (+design-spec) | `bdd/**/*.feature` | PO |
-| `/review-context` (BDD) | `.feature` | Findings B1–B6 → `@trace.status: approved` | PO/Dev |
-
-## 5 · Tech-Docs
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-tech-docs` | BDD approved + entity catalog | `tech-docs/{TICKET}-tech-design.md` | SA |
-| `/review-tech-docs` | tech-design | Findings đa chiều + ký T7 | SA/Lead |
-
-## 6 · Code
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-code` | `.feature` approved + tech-design | Code + `.trace/*.tsv` | Dev |
-| `/review-code` | Code | Findings (read-only) | Dev/Lead |
-| `/fix-bug` | Bug report | Fix + regression test | Dev |
-| `/map-testids` | UI code | testid map (FE) | Dev |
-| `/debug` | Mô tả lỗi | Phân tích (read-only) | Dev |
-
-## 7 · Dev self-test
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/dev-gen-test` | Code + `.feature` | Bộ self-test | Dev |
-| `/dev-run-test` | Self-test | Kết quả + cột `dev_selftest` | Dev |
-| `/dev-smoke-test` | Service/app đang chạy | Kết quả smoke tại chỗ | Dev |
-
-## 8 · QC Automation
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md` | QA |
-| `/qc-plan` | Analysis | `TEST_PLAN.md` (rủi ro) | QA |
-| `/qc-design-test` | Plan | `test-cases/*.Test.md` | QA |
-| `/qc-review` | Test case/script | 🛑 Cổng review | QA |
-| `/qc-run-test` | `.Test.md` reviewed | Script Playwright + `qc_status` | QA |
-| `/qc-report` | Kết quả run | Report + evidence + product-gap | QA |
-
-## 9 · Quality & Trace
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/validate-traces` | `.trace/*.tsv` + spec/code/test | Ma trận coverage (read-only) | Dev/QA/Lead |
-| `/generate-spec-manifest` | Specs | Mục lục spec cho agent ngoài | SA/Lead |
-
-## 10 · Feedback & Ops
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/report-bug` | Lỗi phát hiện | `feedback/bug-reports/` (spec-anchored) | Tester/QC |
-| `/propose-scenario` | Scenario thiếu | `feedback/bdd-proposals/` | Tester/QC |
-| `/learn` | Định hướng lặp lại | `project-lessons.md` | Tất cả |
-| `/sync` | (umbrella) | Pull + submodule + nổi feedback + Living Docs | Lead |
-| `/update-framework` | — | Sync bản npm mới | Lead |
-
----
-
-## Ký hiệu trạng thái trong report
-
-- 🛑 checkpoint (dừng, chờ `Y`) · 🔒 gate trạng thái (chặn downstream) · ⚪ read-only
-- ⚠️ cảnh báo mềm (không chặn) · ✅ pass · ❌ fail
-
-→ [Trace Schema](trace-schema.md) · [Modules](modules.md) · [Configuration](configuration.md) · [Model Selection](model-selection.md)
+[← Docs Home](../README.md) · [Reference](./)
+
+# Reference · Commands — Bảng đầy đủ (Command Catalog)
+
+> 32 slash command, gom theo phase pipeline. Chi tiết cơ chế từng bước → [Pipeline Steps](../02-concepts/pipeline-steps/).
+
+Mọi lệnh chạy chung một **Gate** (model check → target → context-loader → checkpoint). Xem [Khung chung](../02-concepts/pipeline-steps/README.md#khung-chung-mọi-command-common-gate).
+
+---
+
+## 0 · Setup & Foundation
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/setup-ai-first` | Dự án trống/có code | `.agent/`, `.claude/`, `project-context.yaml`, `CLAUDE.md` | Admin/Lead |
+| `/generate-architecture` | config + tài liệu (`--from`) + code | `architecture.md` (SSOT kiến trúc, theo tier) | SA/Lead |
+
+## 1 · Discovery
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/define-product` | Ý tưởng (+Figma) | `product-definition/*.md` (8 chặng) | PO |
+
+## 2 · Specification (PRD)
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-prd` | product-definition | PRD draft **mới** | PO |
+| `/extend-prd` | **PRD đã có** + `feedback/prd-change-requests/` | PRD v+1 (UC/AC/BR nối tiếp, `Status → draft`) | PO |
+| `/refine-prd` | PRD | Findings 3 lăng kính DEV/SA/PO | PO+SA+Dev |
+| `/review-context` (PRD) | PRD | Findings P0–P5 → `Status: approved` | PO |
+
+> **Chọn lệnh nào cho PRD:**
+> - PRD **chưa tồn tại** → `/generate-prd` (từ discovery). Nó **từ chối chạy** nếu file đã có.
+> - PRD đã có, muốn **thêm** UC/AC/BR mới → `/extend-prd`. Đánh số **nối tiếp**, ghi **add-only** kèm guard sau-ghi, tăng version + changelog nêu rõ scope.
+> - PRD đã có, muốn **sửa vấn đề** đã soi ra → `/refine-prd` → Review Board → `--resume`.
+>
+> `/refine-prd` **không** thêm được yêu cầu mới (nó tự cấm đụng section ngoài findings). `/generate-prd` **không** dùng lại được trên PRD đã có (sẽ mất changelog + đánh số lại BR → hỏng `@trace.business_rules` trong BDD đã sinh).
+
+## 3 · Design-Spec (chỉ FE/App)
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-design-spec` | PRD approved + Figma | `design-spec/*.md` | PO/PM |
+
+## 4 · BDD
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-bdd` | PRD approved (+design-spec) | `bdd/**/*.feature` | PO |
+| `/review-context` (BDD) | `.feature` | Findings B1–B6 → `@trace.status: approved` | PO/Dev |
+
+## 5 · Tech-Docs
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-tech-docs` | BDD approved + entity catalog | `tech-docs/{TICKET}-tech-design.md` | SA |
+| `/review-tech-docs` | tech-design | Findings đa chiều + ký T7 | SA/Lead |
+
+## 6 · Code
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-code` | `.feature` approved + tech-design | Code + `.trace/*.tsv` | Dev |
+| `/review-code` | Code | Findings (read-only) | Dev/Lead |
+| `/fix-bug` | Bug report | Fix + regression test | Dev |
+| `/map-testids` | UI code | testid map (FE) | Dev |
+| `/debug` | Mô tả lỗi | Phân tích (read-only) | Dev |
+
+## 7 · Dev self-test
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/dev-gen-test` | Code + `.feature` | Bộ self-test | Dev |
+| `/dev-run-test` | Self-test | Kết quả + cột `dev_selftest` | Dev |
+| `/dev-smoke-test` | Service/app đang chạy | Kết quả smoke tại chỗ | Dev |
+
+## 8 · QC Automation
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md` | QA |
+| `/qc-plan` | Analysis | `TEST_PLAN.md` (rủi ro) | QA |
+| `/qc-design-test` | Plan | `test-cases/*.Test.md` | QA |
+| `/qc-review` | Test case/script | 🛑 Cổng review | QA |
+| `/qc-run-test` | `.Test.md` reviewed | Script Playwright + `qc_status` | QA |
+| `/qc-report` | Kết quả run | Report + evidence + product-gap | QA |
+
+## 9 · Quality & Trace
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/validate-traces` | `.trace/*.tsv` + spec/code/test | Ma trận coverage · `trace-report.json` · **`trace-history.jsonl`** (append) · đếm hàng đợi | Dev/QA/Lead |
+| `/validate-traces --realign-prd-version {UC}` | cờ ⓘ `PRD_STALE_REF` | Sửa **chỉ dòng `@trace.*`** — không đụng logic | Dev |
+| `/validate-traces --realign-techdoc-revision {UC}` | cờ ⓘ `TECHDOC_STALE_REF` | như trên | Dev |
+| `/generate-spec-manifest` | Specs | Mục lục spec cho agent ngoài | SA/Lead |
+
+## 10 · Feedback & Ops
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/report-bug` | Lỗi phát hiện | `feedback/bug-reports/` (spec-anchored) | Tester/QC |
+| `/propose-scenario` | Scenario thiếu | **A:** `feedback/bdd-proposals/` → `/generate-bdd` chèn · **B:** `feedback/prd-change-requests/` → PO chạy `/extend-prd` | Tester/QC |
+| `/learn` | Định hướng lặp lại | `project-lessons.md` | Tất cả |
+| `/sync` | (umbrella) | Pull + submodule + nổi feedback + Living Docs | Lead |
+| `/update-framework` | — | Sync bản npm mới | Lead |
+
+---
+
+## Ký hiệu trạng thái trong report
+
+- 🛑 checkpoint (dừng, chờ `Y`) · 🔒 gate trạng thái (chặn downstream) · ⚪ read-only
+- ⚠️ cảnh báo mềm (không chặn) · ✅ pass · ❌ fail
+- 🔴 cờ **chặn PR** — `SEAM_UNWIRED` · `STUB_UNRESOLVED` · `ORPHANED` · `TRACE_ORPHAN`. Build xanh + test từng-UC xanh **không** đủ để bỏ qua chúng.
+- 🟠 cờ drift **không chặn PR** — `PRD_DRIFT` · `BDD_DRIFT` · `TECHDOC_DRIFT` · `FE_TECHDOC_DRIFT` · `TECHDOC_STALE_VS_BDD` · `DESIGNSPEC_DRIFT` · `DESIGNSPEC_STALE_VS_BDD`. *"Code chưa theo kịp spec"*, khác *"code đang hỏng"*. **Hết cờ 🔴 ≠ sạch.**
+- ⓘ cờ **không phải lỗi** — `PRD_STALE_REF` · `TECHDOC_STALE_REF` (version lệch nhưng changelog không nêu UC này → chỉ con trỏ cũ) · `SEAM_PENDING` · `STUB_PENDING` (owner chưa gen).
+
+---
+
+## CLI maintenance (không phải slash command)
+
+Chạy qua `npx @educa-corp/sdd-framework <flag>`. Tất cả **dry-run mặc định** — thêm `--apply` để thực thi.
+
+| Flag | Việc |
+|------|------|
+| `--init` | Cài/nâng cấp `.agent/` + shortcut `.claude/commands/`. Backup file bạn đã sửa sang `.agent/.overwritten-*/` và liệt kê ra |
+| `--migrate-bdd-platform` | `bdd/*.feature` phẳng → `bdd/{platform}/`. Báo `OCCUPIED` / `LOST SPEC` thay vì đoán |
+| `--migrate-specs` | Bố cục artifact-type-first cũ (`specs/prd/`, `specs/bdd/`) → feature-package |
+| `--rename-prd-files` | `prd.md` → `{TICKET-ID}-{prd-slug}.md` |
+| `--help` | Danh sách đầy đủ |
+
+Trong repo framework: `npm run build` (assemble template + chạy self-check) · `npm run self-check` (chỉ kiểm contract trace).
+
+→ [Trace Schema](trace-schema.md) · [Modules](modules.md) · [Configuration](configuration.md) · [Model Selection](model-selection.md)

package/docs/04-reference/configuration.md

@@ -1,94 +1,146 @@
-[← Reference](./) · [Concepts › Architecture](../02-concepts/architecture.md)
-
-# Reference · Configuration
-
-> Hai file cấu hình chính. `/update-framework` **không** đụng chúng — đây là nội dung của bạn.
-
----
-
-## 1. `project-context.yaml`
-
-**Single source of truth** cho paths/mode/routing. Nằm ở `.agent/project-context.yaml`, sinh từ `templates/project-context.yaml` qua token substitution khi init. Mọi workflow đọc file này để biết **WHERE** tìm mọi thứ.
-
-### Cấu trúc chính
-
-```yaml
-project:
-  name: "..."
-  description: "..."
-
-paths:
-  specs_dir: "specs"                 # gốc mọi spec artifact
-  trace_dir: ".trace"                # trace state .tsv
-  qc_dir: "docs"                     # working docs của QC
-  qc_skills_dir: ".agent/skills/qc"  # nơi qc-* nạp skill (override sang repo QC riêng)
-  refinement_dir: ".agent/review"    # findings review
-
-setup:
-  mode: single | umbrella
-  spec_source: "..."                 # (umbrella) spec repo dùng chung
-
-services:                            # (multi/umbrella) map domain → service
-  # dạng phẳng: {domain}: { path, module }
-  # dạng map-theo-platform: {domain}: { web: {path,module}, app: {...}, system: {...} }
-
-conventions:
-  build_command: "..."               # lệnh build verify (≤3 retry)
-  test_command: "..."
-
-tech_stack:
-  database: "..."                    # vd PostgreSQL
-```
-
-### Bố cục feature-package (path resolution)
-
-Mọi artifact của một feature nằm chung `specs/{domain}/{prd-slug}/`:
-
-```
-specs/{domain}/{prd-slug}/
-├── {TICKET-ID}-{prd-slug}.md          # PRD (file .md duy nhất ở gốc)
-├── bdd/{web|app|system}/*.feature     # BDD
-├── tech-docs/{TICKET-ID}-tech-design.md
-└── design-spec/{TICKET-ID}*.md        # FE/App
-.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv
-```
-
-- `{domain}` = segment đầu sau `specs_dir`.
-- `{prd-slug}` = segment kế tiếp (folder feature-package) — **không** phải folder cha trực tiếp của file lồng sâu.
-
----
-
-## 2. `CLAUDE.md` (phân tầng)
-
-Instruction cho AI agent — AI *follow* file này thay vì *invent*.
-
-| Tầng | Nội dung |
-|------|----------|
-| **root** `CLAUDE.md` | Luật chung dự án/umbrella |
-| **overlay** `{service}/CLAUDE.md` | §2 kiến trúc & thứ tự layer & package strategy · §3 coding standards · §5 error handling — **theo stack** |
-
-> Service overlay **thắng** root khi mâu thuẫn. context-loader nạp cả hai, đặt ở **cuối** context (Lost-in-the-Middle: "follow style này").
-
----
-
-## 3. Single vs Umbrella
-
-| | Single | Umbrella |
-|---|--------|----------|
-| `setup.mode` | `single` | `umbrella` |
-| Spec ở đâu | Cùng repo | **Spec repo dùng chung** (`spec_source`) |
-| Code ở đâu | Cùng repo | Service submodule (chỉ code + tooling) |
-| Trace/feedback/findings | Cùng repo | Trong spec repo (một nơi authoritative) |
-| Đồng bộ | — | `/sync` (pull + submodule + nổi feedback + Living Docs) |
-
-Khi `spec_source` được đặt, **mọi** PRD/BDD/tech-doc/design-spec/`.trace`/`.agent/review`/`feedback` route về spec repo — vì đều là **artifact liên team**.
-
----
-
-## Không bị ghi đè khi update
-
-`/update-framework` ghi đè `.agent/commands|steps|hooks|rules|templates|skills|modules` nhưng **giữ nguyên**: `CLAUDE.md`, `project-context.yaml`, `domain-knowledge/`, `.trace/`.
-
----
-
-→ [Architecture › Configuration](../02-concepts/architecture.md#configuration-2-file) · [Modules](modules.md)
+[← Reference](./) · [Concepts › Architecture](../02-concepts/architecture.md)
+
+# Reference · Configuration
+
+> Hai file cấu hình chính. `/update-framework` **không** đụng chúng — đây là nội dung của bạn.
+
+---
+
+## 1. `project-context.yaml`
+
+**Single source of truth** cho paths/mode/routing. Nằm ở `.agent/project-context.yaml`, sinh từ `templates/project-context.yaml` qua token substitution khi init. Mọi workflow đọc file này để biết **WHERE** tìm mọi thứ.
+
+### Cấu trúc chính
+
+```yaml
+project:
+  name: "..."
+  description: "..."
+
+paths:
+  specs_dir: "specs"                 # gốc mọi spec artifact
+  trace_dir: ".trace"                # trace state .tsv
+  qc_dir: "docs"                     # working docs của QC
+  qc_skills_dir: ".agent/skills/qc"  # nơi qc-* nạp skill (override sang repo QC riêng)
+  refinement_dir: ".agent/review"    # findings review
+
+setup:
+  mode: single | umbrella
+  spec_source: "..."                 # (umbrella) spec repo dùng chung
+
+services:                            # (multi/umbrella) map domain → service
+  # dạng phẳng: {domain}: { path, module }
+  # dạng map-theo-platform: {domain}: { web: {path,module}, app: {...}, system: {...} }
+
+conventions:
+  build_command: "..."               # lệnh build verify (≤3 retry)
+  test_command: "..."
+
+tech_stack:
+  database: "..."                    # vd PostgreSQL
+```
+
+### Bố cục feature-package (path resolution)
+
+Mọi artifact của một feature nằm chung `specs/{domain}/{prd-slug}/`:
+
+```
+specs/{domain}/{prd-slug}/
+├── {TICKET-ID}-{prd-slug}.md          # PRD (file .md duy nhất ở gốc)
+├── bdd/{web|app|system}/*.feature     # BDD — subfolder platform LUÔN có
+├── tech-docs/{TICKET-ID}-tech-design.md   # MỘT doc gộp cho cả PRD
+├── design-spec/{TICKET-ID}*.md        # FE/App
+└── changelog/{TICKET-ID}-{prd-slug}.changelog.md   # chỉ tạo khi changelog vượt 5 version
+.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv   # MỘT sổ / UC × platform (24 cột)
+.trace/{domain}/{prd-slug}/_seams.tsv               # sổ seam/stub — nguồn 2 cờ 🔴 chặn PR
+.trace/trace-report.json                            # snapshot cho panel — GHI ĐÈ mỗi lần chạy
+.trace/trace-history.jsonl                          # nhật ký append-only — PHẢI commit
+```
+
+- `{domain}` = segment đầu sau `specs_dir`.
+- `{prd-slug}` = segment kế tiếp (folder feature-package) — **không** phải folder cha trực tiếp của file lồng sâu.
+- **Segment `{platform}` không optional** — mọi mode, kể cả umbrella. `web` và `system` của cùng một UC là hai file khác nhau; bỏ segment thì chúng va tên và **ghi đè nhau**. Trace tách theo platform nên bố cục spec phải khớp.
+  *Project còn ở bố cục phẳng: `npx @educa-corp/sdd-framework --migrate-bdd-platform` (dry-run mặc định).*
+
+---
+
+## 2. `CLAUDE.md` (phân tầng)
+
+Instruction cho AI agent — AI *follow* file này thay vì *invent*.
+
+| Tầng | Nội dung |
+|------|----------|
+| **root** `CLAUDE.md` | Luật chung dự án/umbrella |
+| **overlay** `{service}/CLAUDE.md` | §2 kiến trúc & thứ tự layer & package strategy · §3 coding standards · §5 error handling — **theo stack** |
+
+> Service overlay **thắng** root khi mâu thuẫn. context-loader nạp cả hai, đặt ở **cuối** context (Lost-in-the-Middle: "follow style này").
+
+---
+
+## 3. Single vs Umbrella
+
+| | Single | Umbrella |
+|---|--------|----------|
+| `setup.mode` | `single` | `umbrella` |
+| Spec ở đâu | Cùng repo | **Spec repo dùng chung** (`spec_source`) |
+| Code ở đâu | Cùng repo | Service submodule (chỉ code + tooling) |
+| Trace/feedback/findings | Cùng repo | Trong spec repo (một nơi authoritative) |
+| Đồng bộ | — | `/sync` (pull + submodule + nổi feedback + Living Docs) |
+
+Khi `spec_source` được đặt, **mọi** PRD/BDD/tech-doc/design-spec/`.trace`/`.agent/review`/`feedback` route về spec repo — vì đều là **artifact liên team**.
+
+---
+
+## Vùng nào bị ghi đè khi update
+
+`.agent/` là **mirror sinh ra**: `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện**.
+
+| Đường dẫn | Sửa được? | Vì sao |
+|---|:---:|---|
+| `CLAUDE.md` | ✅ | ngoài `.agent/` |
+| `.agent/project-context.yaml` | ✅ | file **duy nhất trong `.agent/`** có guard: chỉ tạo nếu chưa tồn tại |
+| `.agent/project-lessons.md` · `.agent/review/` | ✅ | không nằm trong `core/` nên nâng cấp không đụng |
+| `specs/domain-knowledge/` · `.trace/` · `feedback/` | ✅ | ngoài `.agent/` |
+| `.agent/commands` `steps` `rules` `skills` `hooks` `templates` `modules` | ❌ | copy từ repo framework, **ghi đè mỗi lần nâng cấp** |
+
+**Nếu bạn đã sửa gì trong vùng ❌** — từ v0.4.2 `--init` tự cứu:
+
+- bản cũ copy sang `.agent/.overwritten-{version}-{YYYYMMDD}/` (giữ nguyên cây thư mục)
+- danh sách file bị ghi đè in ra ngay sau bước cài
+- `.agent/.install-manifest.json` ghi hash của **đúng những gì lần cài trước đã viết** — nhờ đó lệnh phân biệt được *bạn sửa file* với *framework tự đổi file giữa hai version* (một phép so nội dung thuần sẽ flag cả hai và báo oan hàng chục file mỗi lần nâng cấp)
+
+Thêm vào `.gitignore` của project:
+
+```gitignore
+.agent/.overwritten-*/
+.agent/.install-manifest.json
+.trace-mirror/          # bản sao cho panel VS Code — sinh lại được
+.living-docs/           # report gộp — sinh lại được  (đặt trong .gitignore của spec repo)
+```
+
+> ### ⚠️ `.trace/` **KHÔNG** được gitignore
+>
+> Đây là chỗ dễ mất dữ liệu nhất trong toàn framework.
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}` (`.trace/`) | **AUTHORITATIVE** — `.tsv` + `trace-history.jsonl`. **Không regenerate được** | **PHẢI commit** |
+> | `.trace-mirror/` | bản sao cho panel VS Code | gitignore |
+> | `.living-docs/` | report gộp | gitignore |
+>
+> **Trước v0.4.3 cả hai cùng tên `.trace`.** Khi dev mở thẳng spec repo làm workspace thì hai đường dẫn **bằng nhau** — và `/sync` (bản cũ) gợi ý gitignore theo **tên**, không theo vai trò. Làm theo là **mất sổ gốc, im lặng**: máy vẫn chạy, dashboard vẫn có số; chỉ người thứ hai clone về mới phát hiện, và lúc đó lịch sử đã mất vĩnh viễn.
+>
+> **Kiểm dự án đang chạy:**
+> ```bash
+> git -C {spec_source} check-ignore .trace    # trả về kết quả = ĐANG DÍNH
+> ```
+> Dính thì gỡ dòng khớp `.trace` khỏi `.gitignore` rồi `git add -f .trace && git commit`.
+> Từ v0.4.3 `/sync` Step 4b tự kiểm và báo động 🔴 nếu phát hiện.
+
+> Muốn thay đổi **bền vững** thì sửa trong repo framework rồi phát hành. Tuỳ biến riêng của một project thuộc về `CLAUDE.md`, `.agent/project-context.yaml`, hoặc `.agent/project-lessons.md` — cả ba đều không bị ghi đè. Ranh giới đầy đủ: `.agent/README.md`.
+>
+> **Template `.feature`/PRD không cấu hình được.** Skeleton được `{{include}}` nướng cứng vào file lệnh lúc build, nên sửa `.agent/templates/` **không có tác dụng** (và sẽ bị ghi đè). Đổi cấu trúc artifact = sửa `templates/*` trong repo framework rồi `npm run build`. Chi tiết: `.agent/templates/README.md`.
+
+---
+
+→ [Architecture › Configuration](../02-concepts/architecture.md#configuration-2-file) · [Modules](modules.md)