@educa-corp/sdd-framework 0.1.0

package/commands/generate-tech-docs.tmpl

@@ -0,0 +1,252 @@
+# /generate-tech-docs — Sinh Tài liệu Thiết kế Kỹ thuật (một doc gộp per-PRD)
+
+> **Mô hình phạm vi:** MỘT tài liệu thiết kế kỹ thuật cho mỗi **PRD**, không phải
+> per-UC — một blueprint **full-stack, gộp** (backend API/data/DB **và** client
+> component/state/integration trong một file, nối bằng sequence diagram xuyên
+> tầng) để bất kỳ dev nào đọc là implement được cả feature.
+>
+> **Tech lead trỏ lệnh vào (các) file BDD cụ thể cần thiết kế lúc này** — một file,
+> hoặc một batch nhỏ (vd `system/` + `web/` + `app/` của cùng một UC). Lệnh chỉ nạp
+> **đúng các file đó** (giữ context nhỏ) rồi ghi/mở rộng tài liệu tech-design duy
+> nhất của PRD. Chạy lại cho (các) file BDD kế tiếp thì doc **lớn dần** — mỗi lần
+> chạy là **append**, không bao giờ regenerate toàn bộ. Lệnh KHÔNG tự gom mọi BDD
+> của PRD (sẽ nổ context).
+
+## Gate
+{{include:steps/gate.md}}
+
+*Với lệnh này, `$ARGUMENTS` là **input BDD tech lead chọn tường minh** — một hay nhiều path `.feature` và/hoặc UC-id (cách nhau bằng khoảng trắng), KHÔNG phải cả PRD để glob. Phân giải mỗi tham số thành một `.feature` (Gate Bước 1: `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature`), gom vào `input_features` (batch), và suy `{domain}` + `{prd-slug}` + `{TICKET-ID}` từ (các) path khớp — tất cả PHẢI cùng một PRD. Output là doc gộp **duy nhất** của PRD; lần chạy này chỉ thiết kế (các) UC có trong `input_features`.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Bước 0 — Phân giải batch đầu vào (file mà tech lead trỏ vào)
+
+1. Parse `$ARGUMENTS` thành danh sách feature tech lead chọn. Mỗi token là một path `.feature` hoặc một UC-id; phân giải mỗi cái thành file thật (Gate Bước 1). Danh sách này là `input_features` — **batch được thiết kế trong lần chạy này**. **Đừng** mở rộng nó bằng cách glob BDD anh em; chỉ nạp đúng các file này.
+2. **Phân giải định danh từ header, KHÔNG từ tên file.** Với mỗi feature đọc `# @trace.prd` → `{TICKET-ID}` và `# @trace.id` → `{UC-ID}` (cả hai không chứa slug và là chuẩn; TICKET-ID như `FEAT-01-2` có dấu gạch, và slug/title của một UC có thể khác nhau theo platform — vd `…-UC3-sua-cau-bo-qua` (system) vs `…-UC3-sua-cau-quay-lai-bo-qua` (web), nên **đừng bao giờ** parse tên file bằng chuỗi). `{domain}` + `{prd-slug}` lấy từ path (Gate Bước 1). Gom batch thành các UC theo `@trace.id`, để cùng một UC trên system/web/app là **một** UC. Lấy **title** chuẩn của mỗi UC từ PRD (không phải title feature riêng theo platform).
+   **Guard cùng-PRD:** nếu `@trace.prd` khác nhau trong batch → DỪNG: *"Các file thuộc PRD khác nhau ({list}). Chạy /generate-tech-docs mỗi PRD một lần."*
+3. **Cảnh báo mềm cỡ batch (không chặn):** nếu `input_features` có **hơn 5** file:
+   ```
+   ⚠️  {N} file BDD trong một lần chạy. Batch lớn nạp nhiều context hơn và có thể
+       làm giảm chất lượng thiết kế. Cân nhắc chia nhỏ (vd theo UC, hoặc theo platform).
+       Tiếp tục với cả {N}? (Y/N)
+   ```
+   Y → tiếp tục với tất cả · N → để tech lead chạy lại với ít file hơn.
+4. Với mỗi feature trong batch, đọc header + body: `@trace.service`, `@trace.module`, `@trace.platform`, `@trace.bdd_version`, `@trace.status`, `@trace.api_source`, UC id, các scenario (`SC{n}`), và business rule được tham chiếu (`BR{m}`).
+5. Xác định **các platform có trong batch** — cái này quyết định lần chạy sinh ra gì:
+   - feature `system/` → sinh/mở rộng các section **backend** (§2–§4.4, §6–§8) cho UC của nó.
+   - feature `web/` và/hoặc `app/` → sinh/mở rộng block **client §4.5** cho platform đó, và thêm flow của platform đó vào lane **§5** (5.B/5.C).
+   - batch không có feature client → không có việc §4.5 lần này (lần chạy sau trỏ vào BDD `web/`·`app/` sẽ append).
+   - **batch không có feature `system/` (PRD chỉ client):** **đừng** bịa BE contract. §4.1 chỉ liệt kê các endpoint mà client **tiêu thụ** (external / bên thứ ba / của team khác / existing), reverse-document từ mệnh đề Then của client BDD + PRD và đánh dấu "consumed (external)"; nếu feature không gọi mạng → §4 = "N/A — client-only, không backend". §4.5.4 map tới bất cứ gì §4.1 liệt kê (hoặc không có).
+   - Ghi `@trace.bdd_version` dưới dạng **map theo platform** (vd `system=1.5, web=1.9`) từ chính `@trace.bdd_version` của mỗi feature — đừng làm phẳng về một số.
+6. Đường dẫn output — doc **duy nhất** của PRD:
+   ```
+   {paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md
+   ```
+   *(Không có `{UC-ID}` và không có hậu tố `-{platform}` — một doc gộp per-PRD lớn dần qua các lần chạy.)*
+
+Lưu `input_features`, `platforms_present`, danh sách scenario theo từng UC, và `output_path`.
+
+---
+
+## Bước 1 — Chế độ Fresh vs Append
+
+Kiểm tra `output_path` đã tồn tại chưa.
+
+- **Chưa tồn tại → chế độ FRESH.** Tạo doc từ template, chỉ điền (các) UC trong `input_features`. (Section của các UC không thuộc batch này giữ placeholder `{…}` / được thêm ở lần chạy sau.)
+- **Đã tồn tại → chế độ APPEND.** Doc là tăng dần — không bao giờ regenerate từ đầu (sẽ đè mất chỉnh tay và sign-off của reviewer). Đọc bảng **§10 UC Coverage** và **Changelog** hiện có → `covered_ucs`. Với mỗi UC trong `input_features`, phân loại:
+  - **UC mới** (không có trong `covered_ucs`) → **thêm** các section của nó: sequence diagram §5 mới **đúng lane platform** (5.A/5.B/5.C, đánh số sau cái cuối cùng hiện có *trong lane đó*); với §4.5 — nếu **platform** này mới với doc → nhóm `### 4.5 — {platform}` mới, ngược lại thêm sub-block `§4.5.1.x {Screen} — {UC}` + row vào §4.5.6 dùng chung của nhóm platform đó (đừng lặp nhóm); row mới ở §3/§4.3/§8/§9. Rồi cập nhật §10 (row khoá theo platform×SC) và thêm một row Changelog.
+  - **UC đã phủ được trỏ lại** (có trong `covered_ucs`) → đây là refresh/mở rộng có chủ đích (vd tech lead giờ trỏ vào BDD `web/` của một UC mà backend đã thiết kế, hoặc BDD bump version). Xác nhận trước khi đụng nội dung có sẵn:
+    ```
+    ↻ {UC-ID} đã có trong {TICKET-ID}-tech-design.md.
+      Lần chạy này sẽ {thêm block client {platform} (§4.5) | refresh cho BDD v{new}}.
+      Cập nhật các section của UC này? (Y = merge/mở rộng · N = bỏ qua UC này)
+    ```
+    Y → merge (thêm platform/§ còn thiếu hoặc refresh phần đã đổi, giữ nguyên prose không liên quan) · N → bỏ qua UC đó.
+
+Lưu `mode` (`fresh` | `append`) và, theo từng UC của batch, hành động của nó (`add-new` | `extend-platform` | `refresh` | `skip`). Nếu mọi UC đều `skip` → báo "không có gì để làm" và dừng.
+
+---
+
+## Bước 2 — Cổng Chất lượng (mọi feature nguồn)
+
+Với **mỗi** feature BDD trong scope:
+
+1. Tìm `{paths.refinement_dir}/{uc-id}-{platform}-review-bdd-findings.yaml` — `{platform}` = `@trace.platform` của chính feature này (đọc ở Bước 0). Findings là **per (UC × platform)**: mỗi `.feature` của từng platform được review vào file riêng, nên kiểm đúng file khớp feature **này** — không phải của platform anh em (feature `system` phải được gác bởi findings `system`, không phải `web`).
+   - **Thiếu** → cảnh báo mềm (không chặn):
+     ```
+     ⚠️  /review-context chưa chạy cho {uc-id}.feature.
+     Khuyến nghị: chạy /review-context {feature-file} trước để kiểm chất lượng BDD.
+     ```
+   - **Có** → kiểm các finding critical chưa xử lý với `status: "pending"`. Nếu có → **DỪNG** và in (các) feature vi phạm:
+     ```
+     ❌ Cổng Chất lượng thất bại — {feature-file}
+     Còn finding BDD critical chưa xử lý.
+     Chạy: /review-context --fix {feature-file}   ← auto-fix những gì có thể
+     Rồi: /review-context --resume {feature-file}
+     Rồi chạy lại: /generate-tech-docs {đúng các feature file đó}
+     ```
+2. Đọc `# @trace.status:` của feature (tín hiệu duyệt chuẩn). Nếu feature nào ≠ `approved` → cảnh báo mềm (đồng bộ generate-code / qc-analyze): *"BDD {uc-id} chưa approved (@trace.status: {status}) — tech design dựng từ BDD chưa chốt có thể phải làm lại. Tiếp tục? (Y/N)"*.
+
+Cổng này chỉ chạy cho `input_features` (batch) — không bao giờ quét BDD ngoài cái tech lead trỏ vào.
+
+---
+
+## Bước 3 — Điều kiện tiên quyết Client (chỉ khi batch có feature `web/` hoặc `app/`)
+
+Các block client §4.5 (phân cấp component, map Figma → design-system, hình dạng state, test selector) được **suy ra** từ design spec. Định vị nó:
+
+- **Design Spec** — `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}*.md`.
+  - **Tìm thấy** → nạp; Screen Specs / Component Inventory / Screen States của nó cấp cho §4.5 và mô hình state client ở §4.5.3.
+  - **Không thấy** → cảnh báo mềm (không chặn cứng — các section backend vẫn giá trị đầy đủ, và §4.5 có thể draft chỉ-text từ client BDD, đánh dấu degraded):
+    ```
+    ⚠️  Không tìm thấy design-spec cho {TICKET-ID}. §4.5 (map UI component, tham chiếu
+        Figma, test selector) sẽ được draft chỉ từ BDD và đánh dấu
+        "[DRAFT — no design-spec]". Chạy /generate-design-spec trước để đủ độ trung thực.
+        Tiếp tục? (Y/N)
+    ```
+
+Cũng nạp, khi có, catalog Figma component (`figma-components/{module}.md`) và design token (đã nạp bởi context-loader Bước 6-B/6-C) để ưu tiên component trong catalog ở §4.5.1/§4.5.2 và token thật ở §4.5.5.
+
+> **Lưu ý:** vì BE và FE giờ nằm trong **cùng** một tài liệu, không còn cổng "BE contract phải tồn tại trước" — backend contract (§4) và client design (§4.5) được sinh cùng nhau. §4.5.4 vẫn yêu cầu mỗi client service method map tới một endpoint **thật** khai báo ở §4.1 (đừng bịa endpoint).
+
+---
+
+## Bước 4 — Kiểm tra Brownfield
+
+Đọc `@trace.api_source` ở header mỗi feature của batch, và kiểm bảng Metadata của PRD tìm `| **API Source** | existing |`.
+
+| Giá trị | Chế độ |
+|-------|------|
+| `existing` | **Reverse-document** — API đã tồn tại; mô tả as-is, ghi chú gap so với BDD, không thiết kế mới |
+| vắng / khác | **Greenfield** — thiết kế API từ scenario |
+
+Lưu `active_mode`. Nếu `reverse-document`, nạp appendix "Existing API Contract" từ PRD làm input cho §4.
+
+---
+
+## CHECKPOINT — Kế hoạch Tech Design
+
+Trước khi sinh, hiện kế hoạch và chờ **Y** rõ ràng:
+
+```
+Kế hoạch Tech Design — {TICKET-ID}  (doc full-stack / PRD)
+──────────────────────────────────────────────────────
+PRD        : {TICKET-ID} — {feature title}
+Chế độ     : {Fresh (doc mới) | Append (mở rộng doc có sẵn)}
+Batch      : {M} file feature lần này:
+               - {input_features[0]}  ({platform} · UC{n} · {add-new|extend-platform|refresh})
+               - {…}
+Service    : {trace.service}      Module: {trace.module}
+Platform   : {các platform trong batch}
+Chế độ API : {Reverse-document (API existing) | Greenfield (thiết kế mới)}
+Scenario   : {N} scenario trong batch
+BDD ver    : {bdd_version lớn nhất trong batch}
+Design-spec: {đã nạp | ⚠️ thiếu (§4.5 degraded) | n/a — batch không có feature client}
+UC của doc : đã phủ → {covered_ucs hoặc "chưa (doc mới)"};  lần này → {batch UCs}
+Output     : {output_path}   ({tạo | mở rộng})
+
+Section sẽ {sinh | thêm} cho batch này:
+  {backend (system trong batch): §1–§4.4, §6–§8}
+  {client  (web/app trong batch): §4.5 cho {platform}}
+  §5  Key Flows — {N} sequence diagram trong lane platform (5.A system/5.B web/5.C app), mỗi cái tiêu đề "platform · SC"
+  §9  Design Decisions (row mới) · §10 UC Coverage (khoá theo platform×SC) · §11 Cross-cutting · Changelog
+──────────────────────────────────────────────────────
+Tiếp tục? (Y/N)
+```
+
+Chờ "Y" rõ ràng.
+
+---
+
+## Sinh
+
+Ghi/mở rộng `{output_path}` dùng template dưới đây, chỉ sinh **nội dung cho (các) UC** trong `input_features`. Điền các placeholder `{…}` liên quan và xoá các comment hướng dẫn khi làm.
+
+- Section **Backend** (§2–§4.4, §6–§8) đến từ feature `system/` trong batch (hoặc, brownfield, từ contract existing của PRD).
+- Block **Client** §4.5 đến từ feature `web/`·`app/` trong batch + design-spec. Dùng **cùng** giá trị test-id giữa web/app cho cùng một element logic (chỉ khác attribute theo platform).
+- **§5 Key Flows** — một mermaid sequence diagram cho mỗi scenario của batch, participant trải mọi tầng (client component → service → API → external API → DB). **Gom theo lane platform** (5.A system · 5.B web · 5.C app) và đặt tiêu đề mỗi diagram bằng **platform · SC** (vd `web · UC1-SC1`) — vì `{UC}-SC{N}` chỉ độc nhất trong (UC × platform): `system UC1-SC1` và `web UC1-SC1` là hai scenario khác nhau. Đừng bao giờ ghi trơ `UC1-SC1`. Chỉ tạo lane cho platform có BDD.
+- **§1/§2** (Overview/Actors, Architecture) là cấp PRD: viết ở lần chạy đầu; các lần sau chỉ mở rộng nếu batch thêm actor/integration thật sự mới.
+- **§10 UC Coverage** — một row UC (có cột Platforms) + bảng con coverage-scenario khoá theo **(platform, SC)** — mỗi platform×SC một row, vì cùng số SC ở platform khác nhau là scenario khác nhau. Đây là mỏ neo mà chế độ APPEND đọc. Luôn cập nhật nó cho (các) UC/platform của batch.
+
+**Chế độ APPEND (doc đã tồn tại):** **đừng** viết lại section có sẵn. Chèn diagram §5 của UC batch **vào đúng lane platform** (5.A/5.B/5.C, đánh số sau cái cuối trong lane đó, tiêu đề `platform · SC`), các row mới ở §3/§4.3/§8/§9; với §4.5 — platform mới → nhóm `### 4.5 — {platform}` mới, ngược lại thêm sub-block `§4.5.1.x {Screen} — {UC}` + row vào §4.5.6 dùng chung của nhóm (không lặp nhóm); rồi cập nhật §10 (row khoá theo platform×SC) và thêm một row Changelog. Bump `@trace.revision` và làm mới `@trace.ucs` / `@trace.platforms` ở header, và cập nhật entry của platform vừa đụng trong map `@trace.bdd_version` (vd set `web=2.0`, giữ nguyên `system`).
+
+{{include:templates/tech-design.template.md}}
+
+---
+
+## Self-Review Gate — REFUTE trước khi ghi *(bắt buộc; chạy cả Fresh lẫn Append)*
+
+Trước khi finalize/append doc, **tự phản biện bản nháp** qua 4 cổng dưới — không phải "sinh rồi tin", mà "sinh rồi ĐỐI CHIẾU với ngữ cảnh rộng hơn + khai GAP tường minh". Nguyên tắc nền: **Completeness ≠ Coverage** — "mọi SC được map" là *cần*, KHÔNG *đủ*; trung thành với lát BDD trước mặt không phải là đúng khi nó chỉ là một lát cắt. Cổng nào không đạt → **sửa, hoặc khai `[GAP]` / `[ASSUMPTION: {owner} confirm]` ngay tại chỗ trong doc** — TUYỆT ĐỐI không bỏ trắng, không bịa lặng.
+
+**Cổng 1 — RECONCILE (đối chiếu chéo, đọc-ngược CÓ GIỚI HẠN).**
+Đọc-ngược **bounded** — chỉ 3 nguồn này, KHÔNG kéo toàn bộ BDD của PRD (giữ batch nhỏ):
+- **PRD Business Rules** của UC → mọi BR có được §3/§4/§5 phản ánh? Nguồn/sự kiện nào BR yêu cầu mà doc thiếu → thêm, hoặc `[GAP]`.
+- **core-entities.md** → mỗi enum/trạng thái doc dùng có **producer** (ai sinh ra giá trị)? Mỗi cột/field có **writer** (luồng nào set)? Enum mồ côi / cột không writer → sửa hoặc flag.
+- **Seam UC anh em cùng domain** (chỉ endpoint/entity giao nhau) → không định nghĩa lại contract đã có ở UC khác; không tự mâu thuẫn enum mình vừa viết trong chính doc này.
+
+**Cổng 2 — GAP-or-FLAG (trung thực, không bịa).**
+Cần một type/giá trị/policy (auth, config, event, error code) mà **không có nguồn** → **không** chép hình dạng ở boundary, **không** bịa: ghi `[GAP]` hoặc `[ASSUMPTION: {owner} confirm]`. Nếu doc định thiết kế endpoint/flow mà **BDD không định nghĩa nghiệp vụ** (design vượt BDD) → khai GAP + escalate, đừng âm thầm hợp thức hoá.
+
+**Cổng 3 — CATALOG (không hard-code).**
+Literal & constant rải rác như luật → gom lại: **generic envelope** (đừng typed-per-thing khi PRD-BR đã đưa hợp đồng chung) + bảng catalog (vd `signal_type × source`) + constants **đặt tên**. Fail nếu còn hằng số/enum inline chưa vào catalog.
+
+**Cổng 4 — CROSS-SERVICE & COMPLETENESS.**
+- **Ranh giới:** không kéo định danh **nội bộ** service khác vào lookup của mình — dùng abstraction tầng mình. Tương tác 2 service: nói rõ **bên nào own dedup/ordering** + có **ack path** + cross-field invariant.
+
+  > **Thuật ngữ (đọc nhanh):**
+  > - **dedup** (khử trùng) — cùng một event/message tới **≥2 lần** thì chỉ được xử lý **một** lần (thường qua *idempotency key*). Thiếu → cộng đôi, ghi đôi.
+  > - **ordering** (thứ tự) — event tới **đúng trình tự** phát ra; nếu có thể tới lệch thì chốt: bên nào sắp lại, hay bên nhận phải **chịu được** lệch. Thiếu → state sai (vd "hết hạn" xử lý trước "tạo mới").
+  > - **ack path** (đường xác nhận) — bên nhận xử lý xong **báo lại** bên gửi ("đã nhận/đã xử lý") để bên gửi ngừng gửi lại. Thiếu → mất event, hoặc gửi lại vô hạn.
+  > - **cross-field invariant** — ràng buộc phải **luôn đúng** giữa nhiều field/entity (vd `tổng các phần = tổng`, `trạng thái = paid ⇒ paid_at ≠ null`).
+- **Không happy-only:** mỗi API/flow phải **xét đủ** nhánh happy + partial + error + rollback, kể cả khi BDD chỉ tả happy. Thiết kế nhánh lỗi **từ nguồn** (PRD-BR về xử lý thất bại · pattern rollback ở CLAUDE.md §2 · chuyển-trạng-thái entity ở core-entities). Chi tiết nào **không suy được từ nguồn** (error code/shape của service khác, quyết định retry-hay-fail…) → **khai `[GAP]`, KHÔNG bịa** (Cổng 2). *Bắt buộc CÓ nhánh lỗi ≠ bịa NỘI DUNG nhánh lỗi.*
+- **Đủ chi tiết hàm:** hàm cốt lõi tả **điều kiện chọn / nhánh / kết quả**, không dừng ở tên hàm + sequence-diagram.
+
+**Ghi sổ + cổng chặn (bắt buộc khi có GAP).** Mỗi `[GAP: Gn]`/`[ASSUMPTION: An]` khai inline PHẢI có đúng **một** dòng ở **§12 GAP Register** (không marker mồ côi), gán:
+- **Loại**: `nội tại` (BE tự quyết) · `cross-service` (team/partner khác — đóng qua T7 sign-off) · `spec-defect` (BDD/PRD sai → escalate PO, xem Conflict register dưới).
+- **Severity**: 🔴 `blocker` (code bắt buộc phải có mới đúng) · 🟢 `non-blocker` (đoán tạm chạy được, cần confirm). Nhãn GAP/ASSUMPTION **không** tự quyết severity — một ASSUMPTION vẫn có thể là blocker.
+- **Owner** phải confirm + **Status** = `open`.
+
+Nếu §12 còn **≥1 🔴 blocker `open`** → set `@trace.status: in-review` (KHÔNG để `approved`) — `generate-code` bị chặn tới khi đóng hết blocker. (Cùng pattern design-spec giữ `draft` khi còn ❌ Missing.) Nếu 0 ẩn số → §12 ghi "Không có", đừng bịa dòng.
+
+> **Conflict register:** nếu BDD **mâu thuẫn** một invariant kiến trúc (CLAUDE.md §2 / core-entities) → ghi vào §9 Design Decisions như **conflict cần PO sửa `.feature`** (và một dòng §12 loại `spec-defect`), KHÔNG tự quyết, KHÔNG lặng chép.
+
+> **Guardrail nguồn:** 4 cổng này phản chiếu `project-lessons` **L-012** (nếu project có) — nạp ở context-loader Bước 6.7 như ràng buộc cứng, sống sót qua `/update-framework`. Cổng ở đây là lớp framework; L-012 là lớp project-local; cả hai cùng hiệu lực. `/review-tech-docs` **T8/T9** bắt lại ở cổng review nếu gen bỏ lọt.
+
+Ghi số `[GAP]`/`[ASSUMPTION]` đã khai vào report Output.
+
+---
+
+## Công bố — chia sẻ doc (umbrella + spec repo dùng chung)
+
+Nếu `paths.tech_docs_dir` phân giải **dưới `setup.spec_source`** (vd `{spec_source}/specs/{domain}/{prd-slug}/tech-docs`), doc được ghi **bên trong spec submodule**. Công bố nó (commit 2 tầng) để cả team đọc qua `/sync` — tech design gộp per-PRD này là blueprint liên team (API contract cho BE, client design cho FE/App):
+
+```bash
+cd {spec_source}
+git add {output_path}                   # {TICKET-ID}-tech-design.md
+git commit -m "docs({TICKET-ID}): full-stack technical design ({mode})"
+git push origin {spec_branch}           # branch teammate theo dõi trong .gitmodules
+cd -
+git add {spec_source} && git commit -m "chore: bump spec pointer ({TICKET-ID} tech design)"
+```
+
+Nếu `tech_docs_dir` là **local** — tức không có `setup.spec_source` (single-repo, hoặc một BE repo đa-service thuần không có spec module dùng chung) — bỏ qua bước này; không cần publish liên-repo.
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/generate-tech-docs hoàn tất — {TICKET-ID}  (tech design full-stack, {mode})
+File: {output_path}
+Lần này: {UC/platform của batch đã thiết kế}   |   Doc giờ phủ: {mọi UC trong §10}
+Self-review: {n} [GAP]/[ASSUMPTION] đã khai   ← resolve/confirm với owner trước khi /review-tech-docs
+Next: /review-tech-docs {output_path}
+      ← cần SA/Lead review trước khi sinh code
+      → nếu sống trong spec repo dùng chung: commit + push spec submodule (xem Công bố ở trên) để teammate đọc qua /sync
+      → sau khi approved:
+          BE → /generate-code {system .feature}
+          FE → /generate-code {web|app .feature} --phase=integration   (wire API thật theo §4.5.4 của doc này)
+```