@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/steps/report-footer.md

@@ -1,102 +0,0 @@
-# Report Footer — Định dạng output chuẩn cho mọi lệnh
-
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
-
-## Status Badge
-
-Chọn một theo kết quả:
-- `✅ Complete` — mọi bước thành công, không có vấn đề
-- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
-- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
-
-## Output Artifacts
-
-Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({mô tả ngắn})
-  {created|updated} {file-path} ({mô tả ngắn})
-```
-
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
-
-## Pipeline Position
-
-In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
-để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
-
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
-
-Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
-
-| Phase | Commands |
-|-------|----------|
-| Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` (PRD) |
-| Design Spec | `/generate-design-spec` |
-| BDD | `/generate-bdd` · `/review-context` (BDD) |
-| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
-| Code | `/generate-code` · `/review-code` |
-| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
-| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
-| Trace Audit | `/validate-traces` |
-
-Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
-
-**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
-**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
-
-## Gợi ý lệnh tiếp theo
-
-Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
-
-| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
-| /extend-prd             | `/refine-prd {prd-file}` (soi phần vừa thêm) rồi `/review-context {prd-file}` → PO duyệt → `/generate-bdd` **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}` |
-| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
-| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
-| /map-testids            | `/qc-design-test {UC-ID}` (QC dựng Page Object từ contract §4.5.6 vừa ghi) |
-| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
-| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
-| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
-| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
-| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
-| /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | **Cờ 🔴 trước (chặn PR):** SEAM_UNWIRED → nối binding sang class thật, xoá/thay stub · STUB_UNRESOLVED → `/generate-code {owner_uc}` (lấp logic tại chỗ + xoá hàm song song) · ORPHANED/TRACE_ORPHAN → quyết định thủ công (xoá code+test, đưa scenario trở lại `.feature`, hoặc sửa `sc_id` của tag). **Rồi:** DRIFT/UNTRACKED → `/generate-code {UC-ID}` · BDD_DRIFT → `/generate-code {feature-file}` · tech-doc lỗi thời vs BDD → `/generate-tech-docs` → `/review-tech-docs` · PRD drift → `/generate-bdd {prd-file}` · GAP → `/dev-gen-test {UC-ID}`. **Chỉ tạo PR khi mọi cờ 🔴 = 0** |
-| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
-| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
-| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |
-| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
-| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
-
-Định dạng footer như sau:
-```
----
-Status   : {badge}
-{khối Output Artifacts}
-Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {lệnh gợi ý kèm ví dụ tham số}
-```
-*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*

package/steps/review-fanout.md

@@ -1,159 +0,0 @@
-# Review Fan-Out toàn diện + Hội tụ về độ đầy đủ
-
-**Vì sao có cái này:** Một lượt review đơn không bao giờ liệt kê hết mọi vấn đề cùng lúc — model
-dừng ở mức "đủ" findings, nên mỗi vòng review sau lại lòi ra vấn đề *mới*
-(đập chuột chũi). Quy trình này ép review **hội tụ trong một lần chạy lệnh**:
-fan out song song theo các chiều review, rồi lặp một critic độ-đầy-đủ cho tới khi một
-vòng không sinh thêm gì mới, *trước khi* ghi file findings.
-
-Lệnh gọi cung cấp hai thứ bắt buộc + hai tuỳ chọn:
-- **DIMENSIONS** — danh sách các chiều review để fan out
-  (`/refine-prd` → 3 lăng kính; `/review-context` → các P-check hoặc B-check).
-- **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
-- **GRANULARITY** *(tuỳ chọn, mặc định `auto`)* — `auto`: chọn độ mịn fan-out theo bảng ngưỡng kích thước ở Phase 1 (hành vi cũ). `per-uc`: **LUÔN** fan-out theo từng UC, **bỏ qua ngưỡng** — dùng cho review cần độ đầy đủ cao (`/refine-prd` truyền cái này để lần đầu đã quét sâu). Lệnh không truyền → `auto` → hành vi không đổi.
-- **CHANGED_SCOPE** *(tuỳ chọn)* — danh sách UC/section đã thay đổi (review **delta**). Nếu được truyền, Phase 1 chỉ fan-out trên các phạm vi này + PRD-global; Phase 2 critic vẫn quét **toàn doc** làm lưới an toàn. Không truyền → quét toàn bộ như thường.
-
-> **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
-> quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
-> sub-agent. Chạy các check của lệnh trực tiếp trên section đã giới hạn và trả về findings.
-
----
-
-## Phase 1 — Quét dimension song song
-
-**Bao nhiêu sub-agent:** *số lượng* agent không phải là đòn bẩy độ đầy đủ — bề rộng được
-cố định bởi taxonomy DIMENSION (thêm agent vào cùng một dimension chỉ tìm lại cùng vấn đề),
-còn *độ sâu* thuộc về vòng lặp critic ở Phase 2.
-
-**Nếu `GRANULARITY = per-uc`:** **bỏ qua bảng ngưỡng dưới đây**, luôn dùng độ mịn **DIMENSION × phạm vi UC** (kể cả PRD nhỏ) — đảm bảo quét sâu, không bỏ sót ngay lần đầu. (Cái giá: nhiều agent hơn cho PRD nhỏ — chấp nhận để lần đầu đầy đủ.)
-
-**Nếu `GRANULARITY = auto`** (mặc định): chọn **độ mịn fan-out** theo kích thước target, tái dùng ngưỡng của `steps/spawn-agent.md`:
-
-| Kích thước target | Độ mịn | Số agent |
-|-------------|-------------|-------------|
-| ≤ 3 UC **và** ≤ 300 dòng | một agent cho mỗi DIMENSION trên cả file | = số dimension |
-| > 3 UC **hoặc** > 300 dòng | một agent cho mỗi **DIMENSION × phạm vi UC** (các UC + một phạm vi PRD-global), gom batch để vừa giới hạn agent | `dimensions × (UCs + 1)`, có cap (xem dưới) |
-
-Độ mịn lớn hơn giữ context của mỗi sub-agent nhỏ và quét nó vét cạn trên một
-UC duy nhất — chính là điều ngăn bỏ sót trên các PRD lớn.
-
-> **Các section global (không thuộc UC) — bắt buộc ở chế độ `DIMENSION × UC`.** Mỗi agent per-UC chỉ
-> thấy một UC, nên các section toàn-PRD không thuộc UC nào (scope, success metric,
-> problem statement, terminology, glossary, changelog) sẽ không được quét. Khi nào
-> fan out theo UC, cũng phải thêm một phạm vi **"PRD-global"** (các section không thuộc UC, finding nhận
-> `uc_id: ""`) bên cạnh danh sách UC. Nên số agent tự nhiên là `dimensions × (UCs + 1)`.
-> (Không cần ở chế độ whole-file — ở đó mỗi agent đã thấy các section global rồi.)
-
-### Agent cap — gom batch các UC khi fan-out quá rộng
-
-`dimensions × (UCs + 1)` có thể bùng nổ trên PRD lớn (vd 6 check × (8 UC + 1) = 54
-agent). Giới hạn mỗi wave ở **`AGENT_CAP = 12`** agent và gom batch các phạm vi UC cho vừa:
-
-1. Dựng danh sách phạm vi = `[UC1, UC2, …, UCn, PRD-global]` (độ dài `UCs + 1`).
-   - **Nếu `CHANGED_SCOPE` được truyền (review delta):** danh sách phạm vi = `[các UC trong CHANGED_SCOPE] + [PRD-global]` (chỉ các UC đã đổi + global), KHÔNG phải tất cả UC. Số agent tụt theo đó.
-2. Tính số-phạm-vi-mỗi-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
-   - Nếu `groups ≥ UCs + 1` → không cần batch, chạy một agent cho mỗi `DIMENSION × scope`.
-   - Else chia danh sách phạm vi thành `groups` bucket liền kề kích thước xấp xỉ bằng nhau
-     (giữ `PRD-global` ở bucket riêng nếu vừa; nếu không thì gắn vào bucket cuối).
-     Mỗi agent khi đó xử lý **một DIMENSION trên một bucket UC**.
-3. Kích thước wave kết quả = `dimensions × groups ≤ AGENT_CAP`.
-
-Một agent đã batch review nhiều UC cùng lúc — vẫn giới hạn chặt hơn nhiều so với cả
-file, nên độ phủ vẫn cao. `AGENT_CAP` là núm chỉnh duy nhất; tăng nếu host cho phép
-concurrency nhiều hơn, giảm để tiết kiệm token. Chế độ whole-file (≤ 3 UC) không bao giờ chạm cap.
-
-Spawn các sub-agent đã chọn bằng Agent tool (gửi trong một message duy nhất để chúng
-chạy đồng thời). Mỗi sub-agent nhận một **context window mới** và quét phạm vi của nó
-chỉ qua **một** dimension duy nhất — độ phủ sâu hơn một session phải tung hứng mọi
-dimension cùng lúc (tránh lost-in-the-middle).
-
-Template prompt cho sub-agent (điền vào các ngoặc):
-
-```
-You are a {DIMENSION_NAME} reviewer. Read the full target file at {target_file}.
-Scope: review ONLY through the {DIMENSION_NAME} lens/check — {DIMENSION_DESCRIPTION}.
-Be exhaustive: scan every section, every UC, every AC/BR/scenario. Do not stop early.
-Project context (terminology, entities, architecture):
-{slim_context — banned terms, canonical entities, layer order, domains}
-
-Return a JSON array of findings, each:
-{ "dimension": "{DIMENSION_NAME}", "severity": "critical|major|minor",
-  "section": "...", "uc_id": "...", "quote": "<verbatim ≤120 chars>",
-  "finding": "...", "suggestion": "...", "auto_fixable": true|false }
-Return [] if this dimension is clean. Return ONLY the JSON array.
-```
-
-Gom mảng findings của mọi sub-agent vào một danh sách hợp nhất `ALL_FINDINGS`.
-
----
-
-## Phase 2 — Vòng lặp hội tụ critic độ-đầy-đủ
-
-Đây là bước chống đập-chuột-chũi. Lặp cho tới khi **hai vòng liên tiếp thêm 0 finding
-mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
-
-> **Lưu ý delta:** kể cả khi `CHANGED_SCOPE` giới hạn Phase 1 vào các UC đã đổi, completeness-critic ở Phase 2 **vẫn đọc TOÀN bộ doc** — đây là lưới an toàn bắt các vấn đề mà một fix ở UC đã đổi có thể làm lộ ra ở chỗ khác.
-
-1. Spawn một sub-agent **completeness-critic** bằng Agent tool. Cho nó:
-   - toàn bộ target file (`{target_file}`),
-   - danh sách findings đã ghi nhận dưới dạng **slim JSON** — chỉ 3 fields cốt lõi
-     đủ để critic nhận ra trùng lặp (không cần `quote`, `suggestion`, `auto_fixable`, `severity`):
-     ```json
-     [
-       { "uc_id": "...", "section": "...", "finding": "..." },
-       ...
-     ]
-     ```
-     Nếu `ALL_FINDINGS` vượt 60 items, rút gọn `finding` xuống còn 80 ký tự đầu mỗi item.
-   - cùng slim context (banned terms, canonical entities, layer order, domains).
-   Prompt nó:
-   ```
-   Here is a document and a list of issues already found. Read the WHOLE document.
-   List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
-   contradictions, missing edge/negative paths, coverage holes, terminology drift,
-   structural omissions, and any issue that a fix to an existing finding would expose.
-   ALSO flag ROLE-BOUNDARY / altitude violations (you are NOT limited to adding detail):
-   content sitting in the WRONG section — detailed mechanism (retry counts, timeouts, flag
-   names/owners, error branches) written INSIDE an acceptance criterion or a scope line
-   instead of the Business Rule/Logic section; an AC that merely restates its referenced BR
-   (same content, converged); a term definition crammed into In/Out Scope. For these, the
-   suggestion must be to MOVE the detail to its proper section (AC keeps only the observable
-   outcome + BR ref) — NOT to delete it, and NOT to add more detail.
-   Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
-   nothing new.
-   ```
-2. Thêm bất kỳ finding thực sự mới (chưa có trong `ALL_FINDINGS`) vào danh sách.
-3. Nếu vòng này trả 0 finding mới → tăng bộ đếm dry-round; ngược lại reset về 0.
-4. Dừng khi bộ đếm dry-round đạt 2, hoặc sau tổng cộng 3 vòng.
-
-Ghi lại `convergence_rounds` (số vòng critic đã chạy) cho report.
-
----
-
-## Phase 3 — Dedup, giải quyết xung đột, merge
-
-Các sub-agent chạy **mù với nhau** (độc lập = độ phủ đa dạng). Chúng không bao giờ
-trao đổi hay điều hoà giữa chúng — mọi xử lý trùng/xung đột diễn ra **ở đây trong
-orchestrator**, nơi thấy toàn bộ tập findings.
-
-1. **Khử trùng lặp** `ALL_FINDINGS`: hai finding là trùng nếu cùng nhắm tới cùng
-   `section` + `uc_id` và mô tả cùng một vấn đề gốc. Giữ cái có `suggestion`
-   phong phú hơn; nếu khác nhau về severity, giữ severity **cao hơn**.
-2. **Giải quyết xung đột** — nhóm các finding còn lại theo `section` + `uc_id` và kiểm tra
-   mâu thuẫn (hai finding có `suggestion` không thể cùng áp dụng, hoặc đề xuất sửa ngược nhau cho cùng một chỗ):
-   - Nếu hai đề xuất có thể **merge** thành một bản sửa mạch lạc → merge thành một finding duy nhất.
-   - Nếu chúng **loại trừ lẫn nhau** → phát ra **một** finding nêu cả hai phương án
-     và set `auto_fixable: false` với `status: "needs_discussion"` (PRD) /
-     `status: "pending"` (review) để con người chọn — không bao giờ âm thầm bỏ một bên.
-   - Nếu một finding bị **vô hiệu** bởi finding khác (vd một finding cấu trúc nói một section
-     bị thiếu, nhưng một finding khác trích dẫn nội dung từ chính section đó) → bỏ cái không hợp lệ.
-3. **Sắp xếp** theo severity (critical → major → minor), rồi theo thứ tự `section` trong file.
-4. **Gán ID ổn định** `F001, F002, …` theo thứ tự đã sắp đó.
-5. Map `dimension` của mỗi finding vào field schema của lệnh
-   (`lens` cho `/refine-prd`; `check_id` cho `/review-context`).
-6. Ghi **một** file findings duy nhất theo FINDINGS SCHEMA mà lệnh định nghĩa.
-
-Trong report cuối của lệnh, thêm một dòng:
-```
-Convergence: {convergence_rounds} vòng critic — file findings đã đầy đủ; chạy lại sẽ lòi ra 0 vấn đề mới.
-```

package/steps/spawn-agent.md

@@ -1,129 +0,0 @@
-# Pattern điều phối Sub-Agent
-
-Dùng bởi các lệnh nặng khi target vượt ngưỡng phức tạp.
-Session chính trở thành một **orchestrator nhẹ** — chỉ điều phối.
-Mỗi đơn vị công việc chạy trong sub-agent riêng với context window mới.
-
----
-
-## Ngưỡng phức tạp
-
-| Tín hiệu | Ngưỡng | Hành động |
-|--------|-----------|--------|
-| Số UC trong PRD | > 3 UC | spawn 1 agent cho mỗi UC |
-| Độ dài PRD | > 300 dòng | spawn agent bất kể số UC |
-
-Nếu vượt **một trong hai** ngưỡng → chuyển sang chế độ orchestration.
-
----
-
-## Các bước của Orchestrator (session chính)
-
-### Bước A — Dựng context gọn
-
-Chỉ trích xuất những gì sub-agent cần — KHÔNG truyền nguyên CLAUDE.md hay nguyên business-dictionary:
-
-```json
-{
-  "project_name": "{project.name}",
-  "tech_stack": {
-    "language":       "{tech_stack.language}",
-    "framework":      "{tech_stack.framework}",
-    "build_tool":     "{tech_stack.build_tool}",
-    "test_framework": "{tech_stack.test_framework}",
-    "database":       "{tech_stack.database}",
-    "module":         "{tech_stack.module}"
-  },
-  "conventions": {
-    "build_command":  "{conventions.build_command}",
-    "commit_format":  "{conventions.commit_format}"
-  },
-  "paths": {
-    "specs_dir":     "{paths.specs_dir}",
-    "trace_dir":     "{paths.trace_dir}",
-    "tech_docs_dir": "{paths.tech_docs_dir}"
-  },
-  "architecture_summary": "<3-5 gạch đầu dòng: thứ tự layer + quy tắc chính>",
-  "domains": ["{domain1}", "{domain2}"],
-  "banned_terms": ["{term1}", "{term2}"]
-}
-```
-
-### Bước B — Trích danh sách UC
-
-Quét PRD target tìm các heading `#### {TICKET-ID}-UC{N}:`.
-Dựng list: `[ { uc_id, uc_name, line_start, line_end } ]`
-
-### Bước C — Công bố kế hoạch
-
-```
-Phát hiện độ phức tạp cao — {N} UC / {L} dòng trong {prd_file}
-Đang spawn {N} sub-agent (1 cho mỗi UC)...
-  Agent 1 → {TICKET-ID}-UC1: {tên UC}
-  Agent 2 → {TICKET-ID}-UC2: {tên UC}
-  ...
-```
-
-### Bước D — Spawn một sub-agent cho mỗi UC
-
-Dựng payload và gọi Agent tool cho từng UC:
-
-```json
-{
-  "_agent_mode": true,
-  "command":         "generate-bdd",
-  "uc_id":           "{TICKET-ID}-UC{N}",
-  "target_file":     "{đường dẫn tuyệt đối tới PRD hoặc feature file}",
-  "uc_section":      { "line_start": {N}, "line_end": {N} },
-  "context":         { "<context gọn từ Bước A>" },
-  "active_platform": "{web|app|system — platform orchestrator đã chọn ở Platform Selection}",
-  "design_coverage": { "<Screen States + AC-UI behavioral orchestrator đã trích ở 'Design Spec — Gate & Load' (B1); rỗng nếu BE / không có design-spec>" }
-}
-```
-
-> **Truyền state orchestrator đã phân giải (quan trọng):** orchestrator (session chính) đã chạy các Guard + chọn platform + nạp design-spec MỘT LẦN *trước* khi spawn. Phải kèm `active_platform` và `design_coverage` vào payload để sub-agent áp đúng (đặc biệt phủ Screen States + AC-UI cho FE/App). KHÔNG kèm → sub-agent sinh BDD thiếu phần design (PRD lớn mất B1).
-
-> **Phạm vi lệnh**: Chỉ `/generate-bdd` khởi động chế độ orchestration. `/generate-code` và `/dev-gen-test` có thể chạy như sub-agent (chúng tôn trọng `_agent_mode: true` từ Gate Bước 0), nhưng không spawn thêm sub-agent — phạm vi của chúng vốn đã là một UC duy nhất.
-
-Serialize JSON này và truyền làm `$ARGUMENTS` khi gọi lệnh sub-agent.
-
-### Bước E — Thu thập và merge kết quả
-
-Mỗi sub-agent trả về:
-```json
-{
-  "uc_id":         "{TICKET-ID}-UC{N}",
-  "files_created": ["path/to/file1", "path/to/file2"],
-  "status":        "success | error",
-  "errors":        []
-}
-```
-
-Merge vào một report duy nhất (theo định dạng report-footer.md).
-Nếu có sub-agent lỗi → liệt kê rõ ràng và đề xuất chạy lại riêng UC đó.
-
----
-
-## Điểm vào của Sub-Agent (các lệnh được gọi)
-
-Khi `gate.md Bước 0` phát hiện `_agent_mode: true`:
-
-1. Parse toàn bộ payload từ `$ARGUMENTS`
-2. **Bỏ qua context-loader.md** — dùng trực tiếp `payload.context`
-3. **Chỉ giới hạn ở `payload.uc_id`** — không xử lý các UC khác trong file
-4. Chỉ đọc section PRD giữa `payload.uc_section.line_start` và `line_end`
-5. **Dùng state orchestrator đã phân giải:** `active_platform` = `payload.active_platform`; `design_coverage` = `payload.design_coverage`. **KHÔNG chạy lại** các Guard (PRD approved / Design-Spec) hay tự nạp lại design-spec / hỏi platform — orchestrator đã làm một lần ở session chính.
-6. Thực thi logic thường của lệnh cho riêng UC này (dùng `design_coverage` từ payload để phủ Screen States + AC-UI)
-7. Trả về JSON kết quả có cấu trúc (định dạng Bước E ở trên)
-
----
-
-## Tiết kiệm Context Window
-
-| Chế độ | Nạp gì mỗi session |
-|------|------------------------|
-| Single session (≤ 3 UC) | Full context + full PRD + tất cả UC |
-| Orchestrator | Context gọn + chỉ các heading UC |
-| Mỗi sub-agent | Context gọn + **chỉ 1 section UC** |
-
-PRD càng lớn, mức tiết kiệm trên mỗi sub-agent càng nhiều.

package/steps/trace-mirror.md

@@ -1,53 +0,0 @@
-# Làm mới panel mirror của Living Docs *(local)*
-
-> **Hai vị trí, HAI TÊN KHÁC NHAU — đọc trước khi sửa gì ở đây.**
->
-> | Đường dẫn | Vai trò | Git |
-> |---|---|---|
-> | `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`. Không regenerate được. | **PHẢI commit** |
-> | `./.trace-mirror/` ở gốc workspace hiện tại | **MIRROR** — bản sao tiện cho panel VS Code. Sinh lại được bất cứ lúc nào. | **Luôn gitignore** |
->
-> Trước v0.4.3 cả hai đều tên `.trace`, nên một luật gitignore theo tên có thể **xoá sạch sổ gốc**
-> khi dev mở thẳng spec repo làm workspace (lúc đó hai path bằng nhau). Hai tên khác nhau làm
-> luật git đọc được bằng mắt và **không còn ca nhập nhằng nào**: `.trace-mirror/` không bao giờ
-> commit, `.trace/` không bao giờ gitignore.
-
-## Khi nào CÓ mirror
-
-Mirror chỉ tồn tại khi **`{paths.trace_dir}` nằm NGOÀI workspace hiện tại** — panel đọc từ workspace đang mở nên cần một bản sao ở đây.
-
-| Tình huống | `{paths.trace_dir}` | Có mirror? |
-|---|---|---|
-| Single-service | `./.trace` — **trong** workspace | ❌ Không. Panel đọc thẳng `.trace/trace-report.json`. Bỏ qua cả file này. |
-| Dev mở thẳng **spec repo** | `./.trace` — **trong** workspace | ❌ Không. Như trên. |
-| Umbrella + `spec_source`, dev đứng ở umbrella hoặc service submodule | `{spec_source}/.trace` — **ngoài** workspace | ✅ Có |
-| Umbrella legacy (không `spec_source`) | `.trace` theo từng service | ✅ Có |
-
-Quy tắc một dòng: **phân giải `panel_mirror = ./.trace-mirror` ở gốc workspace hiện tại; nếu `{paths.trace_dir}` đã nằm trong workspace này thì bỏ qua toàn bộ bước mirror.**
-
----
-
-Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
-
-**Khi `setup.spec_source` được đặt (trace gộp — trường hợp phổ biến):**
-`{paths.trace_dir}` phân giải về `{spec_source}/.trace` — vị trí authoritative duy nhất.
-Lệnh này chạy từ `service_root`, nên thao tác ghi là **liên-repo vào spec submodule**;
-commit/push spec submodule cho lần cập nhật trace (giống như `feedback/`).
-
-1. Phân giải `panel_mirror = ./.trace-mirror` tại **gốc workspace hiện tại**.
-2. Nếu `{paths.trace_dir}` **không** nằm trong workspace hiện tại, copy mỗi
-   `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{UC-ID}-{platform}.tsv` (tạo thư mục; ghi đè).
-   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang ở
-   **cột `service` (cột 23)** của chính từng row, do `/generate-bdd` ghi từ `@trace.service`.
-3. **KHÔNG copy `trace-history.jsonl`.** Nó là dữ liệu tích luỹ, không phải thứ sinh lại được —
-   nhân bản nó ra một thư mục gitignore là tạo hai lịch sử lệch nhau rồi mất bản thật.
-
-**Legacy (không có `spec_source` — trace theo service):**
-Copy mỗi `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{service-name}/{UC-ID}-{platform}.tsv`
-(namespace theo `active_service`).
-
-Cách này giữ panel Living Docs của workspace đang mở luôn mới **giữa các lần sync** — nó chỉ là
-một **mirror tiện lợi cục bộ**. File `trace-report.json` đã merge (canonical, trong
-`{spec_source}/.living-docs/`) được build lại bởi `/sync` hoặc `/validate-traces`. Với các lệnh
-được orchestrate, làm việc này một lần trong orchestrator sau khi tất cả sub-agent trả về — không phải
-bên trong từng sub-agent.

package/templates/README.md

@@ -1,47 +0,0 @@
-# templates/ — build-time skeletons
-
-> **Nếu bạn đang mở thư mục này ở `.agent/templates/` trong một project: sửa file ở đây KHÔNG có tác dụng.**
-
-## Vì sao
-
-Các skeleton trong thư mục này được `{{include}}` **nướng cứng vào file lệnh lúc `npm run build`**:
-
-```
-templates/feature.template
-      ↓ {{include:templates/feature.template}}  ← bin/build.js, thay thế văn bản lúc build
-commands/generate-bdd.md
-      ↓ copy vào core/ → mirror sang .agent/
-.agent/commands/generate-bdd.md        ← LỆNH THẬT SỰ CHẠY (đã chứa sẵn skeleton)
-.agent/templates/feature.template      ← bản tham khảo, KHÔNG lệnh nào đọc
-```
-
-Không lệnh nào đọc một path template lúc chạy. `paths.feature_template` / `paths.prd_template` từng tồn tại trong `project-context.yaml` nhưng chưa bao giờ có tác dụng — đã được gỡ bỏ (xem `GAPS.md` G9).
-
-**Thêm nữa:** `.agent/` là vùng bị ghi đè. `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện** (`bin/index.js` → `copyDirRecursive`, không có existence check, không backup). File duy nhất được giữ lại là `.agent/project-context.yaml`. Nên mọi chỉnh sửa ở `.agent/templates/` sẽ **biến mất im lặng** ở lần nâng cấp kế tiếp.
-
-## Muốn đổi cấu trúc artifact sinh ra thì làm gì
-
-Sửa file trong **repo framework** rồi build lại:
-
-```bash
-# trong repo sdd-framework
-vim templates/feature.template          # hoặc prd.template.md, tech-design.template.md, …
-npm run build                           # inline lại vào commands/*.md + core/ + .agent/
-```
-
-Rồi phát hành version mới; project chạy `/update-framework` để nhận.
-
-## File nào ở đây đi vào đâu
-
-| Template | Được include vào | Trở thành |
-|---|---|---|
-| `feature.template` | `commands/generate-bdd.tmpl` | mỗi file `.feature` |
-| `prd.template.md` | `commands/generate-prd.tmpl` | mỗi PRD |
-| `tech-design.template.md` | `commands/generate-tech-docs.tmpl` | tech-doc gộp / PRD |
-| `design-spec.template.md` | `commands/generate-design-spec.tmpl` | design-spec / platform |
-| `architecture.template.md` | `commands/generate-architecture.tmpl` | tài liệu kiến trúc |
-| `product-definition.template.md` | `commands/define-product.tmpl` | product definition |
-| `platform-guide.template.md` | (tham khảo) | — |
-| `project-context.yaml` | **không** include — được copy thẳng làm file config khởi tạo | `.agent/project-context.yaml` |
-
-> Lưu ý `project-context.yaml` là ngoại lệ duy nhất: nó **được** copy ra làm file thật của project, và **được bảo vệ** khỏi ghi đè khi nâng cấp (chỉ tạo nếu chưa tồn tại).