spec-lite 1.6.0 → 1.7.1

package/README.md

@@ -128,6 +128,9 @@ Tạo `.specs/integrations/{slug}/tech.md` sau khi `spec.md` được approve. C
 #### `/spec-test [number]`
 Tạo `.specs/integrations/{slug}/test.md` sau khi `spec.md` được approve. Chạy bởi **QC**, **song song / độc lập** với `/spec-tech` — cả hai chỉ phụ thuộc `spec.md`. Mechanical derive Test Scenarios + Test Cases từ frd.md (Flow → TS, US/AC → Functional TC, VR → positive + negative, FAC → E2E TC, NFR → Non-functional TC, DM → Data & Migration TC), priority deterministic. Cascade lên `feature/{F-XXX}/test-design.md` qua Changes blocks. Gate: integration phải có `features:` non-empty (component-thuần không áp dụng).
 
+#### `/spec-test-exec [F-XXX]`
+Sinh **bundle test-executions** (bản thực thi) cho một feature từ `test-design.md`. Layer EXECUTION — `test-design.md` là **source of truth**, skill đọc-xuống một chiều (không cascade, không sửa test-design), inherit `TC-F*` nguyên văn. Output: cycle bundle `.specs/test-executions/{F-XXX}-{slug}/{NNN}-{cycle-slug}/` (plane 2 tầng, ephemeral per chu kỳ test). Sinh tới 6 doc theo scope×harness — `func-manual`/`func-auto`, `e2e-manual`/`e2e-auto`, `nfr`, `dm` (nfr/dm bỏ nếu rỗng); team chọn harness theo kỹ năng. KHÔNG versioned. Feature-level, chạy sau khi có test-design (không thuộc per-integration pipeline).
+
 #### `/plan`
 Tạo `plan.md` và `todo.md` từ `spec.md` + `tech.md`.
 
@@ -177,9 +180,12 @@ Migrate **main artifact** lỗi thời lên structure mới (mọi main type). T
 | `/spec-new` | `.specs/integrations/{slug}/spec.md` |
 | `/spec-tech` | `.specs/integrations/{slug}/tech.md` |
 | `/spec-test` | `.specs/integrations/{slug}/test.md`, cascade: `feature/{F-XXX}/test-design.md` |
+| `/spec-test-exec` | `.specs/test-executions/{F-XXX}-*/{NNN}-*/test-exec-*.md` (derived từ test-design) |
 | `/plan` | `.specs/integrations/{slug}/plan.md`, `todo.md` |
 | `/build` | *(implements tasks từ `plan.md`/`todo.md`)* |
 | `/review-integration` | *(findings report — không tạo file)* |
 | `/review-everything` | `.specs/integrations/{NNN}-{slug}/review-findings.md` *(qua /spec-new)* |
 
 Feature artifacts (`frd.md`) ở greenfield có thể author trước bằng `/spec-frd`, hoặc mọc dần qua **cascade proposals** từ integrations (`/spec-new` fallback). Component artifacts (`crd.md`/`cdd.md`) ở greenfield chỉ mọc qua cascade — không có skill author trực tiếp (`/spec-frd` chỉ reference component, không tạo crd/cdd).
+
+Ngoài `main/` và `integrations/`, còn plane thứ ba **`.specs/test-executions/`** (execution layer): bundle thực thi *derived* từ `test-design.md` qua `/spec-test-exec`, đánh số per-feature 2 tầng (`{F-XXX}-{slug}/{NNN}-{cycle-slug}/`), ephemeral per chu kỳ test, không versioned. Xem `conventions.md` §8.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-lite",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Spec-driven development kit for Claude Code",
   "type": "module",
   "bin": {

package/skills/archive/SKILL.md

@@ -1,116 +1,125 @@
 ---
 name: archive
-description: Archive một integration từ .specs/integrations sang .specs/archive. Dùng khi một integration đã hoàn thành hoặc không còn active và cần được lưu trữ ra khỏi thư mục làm việc chính.
+description: Archive một integration hoặc một test-execution (cycle bundle / feature group) sang .specs/archive/ — namespaced theo loại (.specs/archive/integrations/ và .specs/archive/test-executions/). Dùng khi integration đã hoàn thành hoặc một chu kỳ test đã xong và cần dọn ra khỏi thư mục làm việc chính.
 ---
 
 # archive
 
 ## Overview
 
-Di chuyển một integration từ `.specs/integrations/` sang `.specs/archive/` để dọn dẹp thư mục làm việc chính trong khi vẫn giữ nguyên toàn bộ nội dung integration đó.
+Di chuyển một artifact bundle ra khỏi thư mục làm việc sang `.specs/archive/`, giữ nguyên nội dung. Hỗ trợ **hai plane**:
+
+- **Integration**: `.specs/integrations/{id}-{slug}/` → `.specs/archive/integrations/{id}-{slug}/`
+- **Test execution**: `.specs/test-executions/{F-XXX}-{slug}/{NNN}-{cycle-slug}/` → `.specs/archive/test-executions/{F-XXX}-{slug}/{NNN}-{cycle-slug}/`
+  - Đơn vị archive = **cycle bundle** (một chu kỳ test xong) hoặc **cả feature group** (`{F-XXX}-{slug}/`) khi feature retire.
+
+`.specs/archive/` được **namespace theo loại** (`integrations/` + `test-executions/`) để không trộn lẫn hai plane. Cấu trúc nguồn được giữ nguyên dưới subfolder loại (test-exec giữ 2 tầng feature-group → cycle-bundle).
 
 ## When to Use
 
-- Integration đã hoàn thành (Done) và không cần active nữa
-- Integration bị cancel hoặc deferred vô thời hạn
-- Muốn dọn dẹp `.specs/integrations/` khỏi các integration cũ
+- Integration đã hoàn thành (Done) / cancel / deferred vô thời hạn.
+- Một **chu kỳ test** (cycle bundle test-exec) đã chạy xong, muốn lưu kết quả ra khỏi working set.
+- Feature retire → archive cả feature group test-executions của nó.
+- Dọn dẹp `.specs/integrations/` hoặc `.specs/test-executions/` khỏi bundle cũ.
 
 ## When NOT to Use
 
-- Integration đang In Progress → chưa nên archive
-- Muốn xóa hoàn toàn → đừng archive, thao tác thủ công sau khi confirm với team
+- Integration đang In Progress → chưa nên archive.
+- Cycle test đang chạy dở (Test Result chưa xong) → chưa archive.
+- Muốn xóa hoàn toàn → đừng archive, thao tác thủ công sau khi confirm với team.
 
 ---
 
 ## Process
 
-### Bước 1: Kiểm tra thư mục archive
+### Bước 1: Chuẩn bị thư mục archive
 
-Kiểm tra `.specs/archive/` đã tồn tại chưa.
+`.specs/archive/` chứa subfolder theo loại. **Tạo lazy** — chỉ tạo subfolder loại nào khi thực sự archive item thuộc loại đó:
 
-**Nếu chưa tồn tại** → tạo thư mục `.specs/archive/`.
-
-**Nếu đã tồn tại** → tiếp tục.
+- Archive integration → đảm bảo `.specs/archive/integrations/` tồn tại (tạo nếu chưa).
+- Archive test-execution → đảm bảo `.specs/archive/test-executions/` tồn tại (tạo nếu chưa).
 
 ---
 
-### Bước 2: Liệt kê integrations
-
-Quét `.specs/integrations/` để tìm tất cả các integration (mỗi integration là một thư mục con).
+### Bước 2: Liệt kê archivable từ cả hai plane
 
-**Nếu không có integration nào:**
+Quét `.specs/integrations/` và `.specs/test-executions/`. Hiển thị danh sách **chia section theo plane, đánh số liên tục**:
 
 ```
-Không có integration nào trong .specs/integrations/.
-```
-
-Dừng lại.
-
-**Nếu có integrations**, hiển thị danh sách dạng numbered list, kèm trạng thái nếu đọc được từ `spec.md` (frontmatter `status` hoặc heading):
-
-```
-Integrations trong .specs/integrations/:
+Archivable:
 
+Integrations (.specs/integrations/):
   [1]  001-user-authentication      (approved)
-  [2]  002-payment-integration      (draft)
-  [3]  003-notification-service     (done)
-  [4]  004-admin-panel              (in-progress)
+  [2]  003-notification-service     (done)
+
+Test executions (.specs/test-executions/):
+  [3]  F-012-bulk-import / 001-regression
+  [4]  F-012-bulk-import / 002-release-2.0
+  [5]  F-012-bulk-import            (cả feature group — gồm 001, 002)
+  [6]  F-031-checkout / 001-smoke
 
-Chọn số thứ tự integration để archive (hoặc nhập nhiều số cách nhau bởi dấu cách, ví dụ: 1 3):
+Chọn số để archive (nhiều số cách nhau bởi dấu cách, ví dụ: 1 3):
 ```
 
-Với mỗi integration, cố gắng đọc `spec.md` để lấy status. Nếu không đọc được thì bỏ qua phần status.
+- **Integration**: mỗi `{id}-{slug}/` là 1 dòng. Cố đọc `spec.md` frontmatter `status` để hiển thị (bỏ qua nếu không đọc được).
+- **Test execution**: mỗi **cycle bundle** `{F-XXX}-{slug}/{NNN}-{cycle-slug}/` là 1 dòng (qualified tên feature group). **Thêm 1 dòng cho cả feature group** `{F-XXX}-{slug}/` để archive trọn gói.
+- Cả hai plane rỗng → `Không có gì để archive trong .specs/integrations/ và .specs/test-executions/.` → dừng.
 
 ---
 
 ### Bước 3: Xác nhận
 
-Sau khi user chọn, hiển thị xác nhận trước khi di chuyển:
+Hiển thị source → **namespaced dest** trước khi di chuyển:
 
 ```
-Sẽ archive các integration sau:
+Sẽ archive:
 
-  .specs/integrations/001-user-authentication/  →  .specs/archive/001-user-authentication/
-  .specs/integrations/003-notification-service/ →  .specs/archive/003-notification-service/
+  .specs/integrations/001-user-authentication/
+    →  .specs/archive/integrations/001-user-authentication/
+
+  .specs/test-executions/F-012-bulk-import/001-regression/
+    →  .specs/archive/test-executions/F-012-bulk-import/001-regression/
 
 Xác nhận? (yes/no)
 ```
 
-Nếu user không confirm → hủy, không làm gì.
+- Nếu user chọn **cả feature group** lẫn một cycle con của nó → cảnh báo trùng, chỉ giữ feature group (archive group bao trọn cycle).
+- Không confirm → hủy, không làm gì.
 
 ---
 
 ### Bước 4: Di chuyển
 
-Với mỗi integration đã được confirm:
+Với mỗi item đã confirm, di chuyển **giữ nguyên cấu trúc nguồn** dưới subfolder loại:
+
+- Integration: `.specs/integrations/{id}-{slug}/` → `.specs/archive/integrations/{id}-{slug}/`
+- Cycle bundle: `.specs/test-executions/{F-XXX}-{slug}/{NNN}-{cycle-slug}/` → `.specs/archive/test-executions/{F-XXX}-{slug}/{NNN}-{cycle-slug}/` (tạo feature group dưới archive nếu chưa có).
+- Feature group: `.specs/test-executions/{F-XXX}-{slug}/` → `.specs/archive/test-executions/{F-XXX}-{slug}/`.
 
-- Di chuyển toàn bộ thư mục `.specs/integrations/{slug}/` sang `.specs/archive/{slug}/`
-- Giữ nguyên toàn bộ cấu trúc thư mục và file bên trong
+Sau khi di chuyển cycle bundle, nếu feature group nguồn **rỗng** (không còn cycle nào) → xóa thư mục feature group rỗng ở `.specs/test-executions/` cho gọn.
 
-Nếu `.specs/archive/{slug}/` đã tồn tại (trùng tên) → cảnh báo:
+**No-overwrite guard:** nếu dest đã tồn tại → cảnh báo và **bỏ qua** item đó (không ghi đè frozen record):
 
 ```
-⚠ .specs/archive/001-user-authentication/ đã tồn tại. Bỏ qua integration này để tránh ghi đè.
+⚠ .specs/archive/test-executions/F-012-bulk-import/001-regression/ đã tồn tại. Bỏ qua để tránh ghi đè.
 ```
 
-Và bỏ qua integration đó, tiếp tục với các integration còn lại.
+Tiếp tục với các item còn lại.
 
 ---
 
 ### Bước 5: Kết quả
 
-Thông báo kết quả:
-
 ```
 ✓ Đã archive:
-  .specs/archive/001-user-authentication/
-  .specs/archive/003-notification-service/
+  .specs/archive/integrations/001-user-authentication/
+  .specs/archive/test-executions/F-012-bulk-import/001-regression/
 
-{nếu có lỗi}
+{nếu có}
 ⚠ Bỏ qua (đã tồn tại):
-  .specs/archive/005-foo/
+  .specs/archive/test-executions/F-031-checkout/001-smoke/
 
-.specs/integrations/ hiện còn {N} integration(s).
+Còn lại: {N} integration(s), {M} test-execution cycle(s).
 ```
 
 ---
@@ -119,7 +128,9 @@ Thông báo kết quả:
 
 Trước khi di chuyển:
 
-- [ ] `.specs/archive/` đã tồn tại (tạo nếu chưa có)
-- [ ] User đã chọn ít nhất 1 integration
-- [ ] User đã confirm trước khi di chuyển
-- [ ] Không ghi đè nếu slug đã tồn tại trong `.specs/archive/`
+- [ ] Subfolder loại tương ứng (`.specs/archive/integrations/` hoặc `.specs/archive/test-executions/`) đã tồn tại (tạo lazy nếu chưa).
+- [ ] User đã chọn ít nhất 1 item.
+- [ ] User đã confirm; trùng feature-group ⨯ cycle-con đã dedupe.
+- [ ] Cấu trúc nguồn giữ nguyên dưới subfolder loại (test-exec giữ 2 tầng).
+- [ ] Không ghi đè nếu dest đã tồn tại.
+- [ ] Feature group nguồn rỗng sau khi archive cycle → dọn thư mục rỗng.

package/skills/artifact-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: artifact-audit
-description: Audit MAIN artifacts trong .specs/main/ xem có lỗi thời so với template không (chỉ main artifacts — prd/domain/sad/frd/fdd/test-design/crd/cdd; integration artifacts ngoài scope). So `template_version` của artifact với `template_version` hiện tại đọc thẳng từ template (.claude/templates/). Versioned khớp → up-to-date, lệch → out-dated (in vX → vY). Artifact thiếu version (sinh trước versioning) → đối chiếu structure với template: khớp thì stamp version, lệch thì flag out-dated. KHÔNG tự migrate — chỉ stamp khi chắc chắn khớp + báo cáo. Nhận tùy chọn 1 hay nhiều main type làm scope (vd `frd`, `frd,crd`); không có arg → audit mọi main type.
+description: Audit MAIN artifacts trong .specs/main/ xem có lỗi thời so với template không (chỉ main artifacts — prd/domain/sad/frd/fdd/test-design/selector-contract/crd/cdd; integration artifacts ngoài scope). So `template_version` của artifact với `template_version` hiện tại đọc thẳng từ template (.claude/templates/). Versioned khớp → up-to-date, lệch → out-dated (in vX → vY). Artifact thiếu version (sinh trước versioning) → đối chiếu structure với template: khớp thì stamp version, lệch thì flag out-dated. KHÔNG tự migrate — chỉ stamp khi chắc chắn khớp + báo cáo. Nhận tùy chọn 1 hay nhiều main type làm scope (vd `frd`, `frd,crd`); không có arg → audit mọi main type.
 ---
 
 # artifact-audit
@@ -9,7 +9,7 @@ description: Audit MAIN artifacts trong .specs/main/ xem có lỗi thời so v
 
 Trả lời một câu hỏi: **main artifact nào trong `.specs/main/` đã lỗi thời so với template mới nhất?**
 
-> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `test-design`, `crd`, `cdd` — đều nằm dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt` dưới `.specs/integrations/`) **không** thuộc scope của skill này — chúng là ephemeral và immutable sau khi `done`, không audit/migrate theo version.
+> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `test-design`, `selector-contract`, `crd`, `cdd` — đều nằm dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt` dưới `.specs/integrations/`) **không** thuộc scope của skill này — chúng là ephemeral và immutable sau khi `done`, không audit/migrate theo version.
 
 Cơ chế (xem `conventions.md` §7 Template Versioning):
 - **Nguồn sự thật** = `template_version` trong frontmatter template đang cài (`.claude/templates/...`). Đọc thẳng lúc chạy — không manifest, không cache.
@@ -44,6 +44,7 @@ Type của main artifact resolve theo **filename**. Mỗi type map tới đúng
 | `frd.md` | frd | `main/feature/frd-template.md` |
 | `fdd.md` | fdd | `main/feature/fdd-template.md` |
 | `test-design.md` | test-design | `main/feature/test-design-template.md` |
+| `selector-contract.md` | selector-contract | `main/feature/selector-contract-template.md` |
 | `crd.md` | crd | `main/component/crd-template.md` |
 | `cdd.md` | cdd | `main/component/cdd-template.md` |
 

package/skills/artifact-migrate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: artifact-migrate
-description: Migrate MAIN artifact trong .specs/main/ lên structure template mới nhất (chỉ main artifacts — prd/domain/sad/frd/fdd/test-design/crd/cdd; integration artifacts ngoài scope). Tự chạy /artifact-audit (classify-only, scoped) để phát hiện out-dated, rồi áp delta từ block `migrations` của template — add section thiếu, remove section deprecated, update format section (vd ASCII→Mermaid) — set template_version = current. Tương tác: confirm add/remove/update, hỏi carry-over khi rename, section nội dung mới thì interview hoặc NEEDS_CLARIFY (không bịa). Single-artifact, KHÔNG cascade. Nhận tùy chọn 1 main artifact (path); không có arg → quét mọi main artifact, migrate từng cái có confirm + skip.
+description: Migrate MAIN artifact trong .specs/main/ lên structure template mới nhất (chỉ main artifacts — prd/domain/sad/frd/fdd/test-design/selector-contract/crd/cdd; integration artifacts ngoài scope). Tự chạy /artifact-audit (classify-only, scoped) để phát hiện out-dated, rồi áp delta từ block `migrations` của template — add section thiếu, remove section deprecated, update format section (vd ASCII→Mermaid) — set template_version = current. Tương tác: confirm add/remove/update, hỏi carry-over khi rename, section nội dung mới thì interview hoặc NEEDS_CLARIFY (không bịa). Single-artifact, KHÔNG cascade. Nhận tùy chọn 1 main artifact (path); không có arg → quét mọi main artifact, migrate từng cái có confirm + skip.
 ---
 
 # artifact-migrate
@@ -9,7 +9,7 @@ description: Migrate MAIN artifact trong .specs/main/ lên structure template m
 
 Đưa một main artifact (hoặc toàn bộ main artifacts) **lỗi thời** lên đúng structure của template mới nhất, rồi cập nhật `template_version`. Đây là vế **fix** đối xứng với `/artifact-audit` (vế **detect**).
 
-> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `test-design`, `crd`, `cdd` — đều dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt`) **không** thuộc scope — ephemeral + immutable sau `done`, không migrate theo version.
+> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `test-design`, `selector-contract`, `crd`, `cdd` — đều dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt`) **không** thuộc scope — ephemeral + immutable sau `done`, không migrate theo version.
 
 Cơ chế (xem `conventions.md` §7 Template Versioning):
 - **Required section hiện tại** = body `##` headings của template (deterministic theo level; `###` = instance).
@@ -34,7 +34,7 @@ Cơ chế (xem `conventions.md` §7 Template Versioning):
 
 Resolve type của main artifact theo **filename** (giống `/artifact-audit`). Mỗi type map tới đúng một template tại `.claude/templates/...`:
 
-`prd.md`→`main/prd-template.md` · `domain.md`→`main/domain-template.md` · `sad.md`→`main/sad-template.md` · `frd.md`→`main/feature/frd-template.md` · `fdd.md`→`main/feature/fdd-template.md` · `test-design.md`→`main/feature/test-design-template.md` · `crd.md`→`main/component/crd-template.md` · `cdd.md`→`main/component/cdd-template.md`
+`prd.md`→`main/prd-template.md` · `domain.md`→`main/domain-template.md` · `sad.md`→`main/sad-template.md` · `frd.md`→`main/feature/frd-template.md` · `fdd.md`→`main/feature/fdd-template.md` · `test-design.md`→`main/feature/test-design-template.md` · `selector-contract.md`→`main/feature/selector-contract-template.md` · `crd.md`→`main/component/crd-template.md` · `cdd.md`→`main/component/cdd-template.md`
 
 **Chỉ main artifacts.** Integration artifacts (`spec`/`tech`/`test`/`plan`/`todo`/`techdebt`) ngoài scope → bỏ qua. File không khớp map → cũng bỏ qua.
 

package/skills/plan/SKILL.md

@@ -85,6 +85,7 @@ Load:
 
 - `.specs/integrations/{slug}/spec.md` — Requirements, Acceptance Criteria (ghi chú số AC và IDs)
 - `.specs/integrations/{slug}/tech.md` — Technical Design, Interface Changes, Data Model Changes, Implementation Notes
+- `.specs/main/feature/{F-XXX}-*/selector-contract.md` — cho mỗi feature có UI trong frontmatter `features` (nếu tồn tại): danh sách `data-testid` mà FE task PHẢI gắn (nguồn chung để test auto bám vào)
 - `.specs/main/domain.md` — Entities và Business Rules liên quan
 
 Surface tóm tắt để planning-and-task-breakdown có đủ context:
@@ -97,6 +98,7 @@ CONTEXT CHO PLANNING:
 - Yêu cầu chính: {tóm tắt từ spec.md — 2-4 bullet}
 - Acceptance Criteria: {tổng số AC — list IDs theo nhóm Feature/Component như spec.md}
 - Thay đổi kỹ thuật: {modules, data model, interfaces từ tech.md}
+- Selector contract (testid FE phải gắn): {tổng testid theo feature có UI, hoặc "—" nếu không có}
 - Shared entities liên quan: {từ domain.md}
 
 ASSUMPTIONS:
@@ -112,6 +114,8 @@ ASSUMPTIONS:
 
 Invoke `planning-and-task-breakdown` với context đã load. Skill đó sẽ thực hiện: dependency graph, slicing, write tasks. Output phải theo **Output Format** định nghĩa bên dưới — không dùng format mặc định của `planning-and-task-breakdown`.
 
+**Ràng buộc từ selector-contract (nếu feature có UI):** mỗi FE task (build/sửa component UI) PHẢI gắn đúng các `data-testid` khai trong `selector-contract.md` của feature tương ứng — đó là nguồn chung để e2e-auto/func-auto bám vào (`conventions.md` §3.3). Task `Verification` nên có checklist item "`data-testid {…}` hiện diện trong DOM". KHÔNG tự đặt testid lệch quy ước; brownfield có thể cần task **bổ sung testid còn thiếu** vào component cũ để đạt full coverage theo contract.
+
 ---
 
 ## Output Format
@@ -146,4 +150,5 @@ Nếu trong quá trình breakdown phát hiện delta cần cập nhật `sad.md`
 - [ ] plan.md có section **Dependency Graph**
 - [ ] Mỗi task có đủ: Mục tiêu / depends / Các bước / Verification
 - [ ] Không viết code trong suốt quá trình
+- [ ] Nếu feature có UI: FE task gắn `data-testid` theo `selector-contract.md` (Verification kiểm testid hiện diện); brownfield gap → task bổ sung testid còn thiếu
 - [ ] plan.md + todo.md (integration) KHÔNG mang `template_version` (versioning chỉ cho main artifacts)

package/skills/spec-brownfield-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-brownfield-feature
-description: Discover features từ code, generate frd.md + fdd.md cho từng feature, điền Feature Index vào prd.md. Phải chạy /spec-brownfield-component trước vì fdd.md tham chiếu C-XXX từ Component Index.
+description: Discover features từ code, generate frd.md + fdd.md (+ selector-contract.md nếu feature có UI) cho từng feature, điền Feature Index vào prd.md. Phải chạy /spec-brownfield-component trước vì fdd.md tham chiếu C-XXX từ Component Index.
 ---
 
 # spec-brownfield-feature
@@ -152,6 +152,16 @@ Convert mỗi rule sang **human-readable diễn đạt** (không copy regex ho
 
 **Auto-assign Rule ID** `VR-F{NNN}-{seq}` cho mỗi rule extract được — tăng dần toàn feature, không reset theo field. Sub-rule phức tạp → tách flat thành nhiều rule riêng, mỗi cái 1 ID.
 
+**4f. Selector-contract — define ĐẦY ĐỦ từ flows (chỉ feature có UI):**
+
+**KHÔNG harvest** testid rời rạc từ code. Code brownfield thường gắn testid **thiếu / không nhất quán** → harvest sẽ chép lại đúng cái thiếu đó, vĩnh viễn dưới coverage. Thay vào đó **define contract ĐẦY ĐỦ từ User Flows** (Bước 4a) theo quy ước `{feature-slug}-{element}[-{qualifier}]` (`conventions.md` §3.3) — **giống hệt greenfield**: mỗi bước tương tác/assert trong flow → một row testid. Contract là **trạng thái đích** (full coverage, đặt tên nhất quán), không phải ảnh chụp hiện trạng.
+
+Hệ quả brownfield: code hiện tại nhiều khả năng **chưa gắn đủ** các testid này → đó là **việc implement** khi feature được chạm qua integration sau (`/spec-new` → `/plan` → `/build`: FE task gắn / bổ sung testid theo contract). Đây là gap *implementation*, KHÔNG phải câu hỏi clarify — contract tự nó đã đầy đủ.
+
+(Tùy chọn) đối chiếu nhanh với `data-testid`/`getByTestId` đã có trong code để ước lượng gap còn bao nhiêu — nhưng testid nào lệch quy ước thì **code sửa theo contract**, KHÔNG phải contract chiều theo code.
+
+Chỉ feature có **UI flows**. Feature thuần backend → bỏ qua, KHÔNG tạo selector-contract.
+
 **Quan trọng — flag cho BA review:**
 - Rule trong code có thể **thiếu** (validation chỉ chạy ở 1 layer, không cover hết) → list những field xuất hiện trong US nhưng không có validation → mark `NEEDS_CLARIFY`.
 - Rule trong code có thể **lệch business intent** → toàn bộ Verification Rules section nên có header note: *"Rules dưới đây reverse-engineer từ code hiện tại. BA cần review và confirm có match business intent không."*
@@ -206,8 +216,14 @@ Với mỗi feature, generate 2 files dùng templates tương ứng:
 - Orchestration: retry / timeout / fallback nếu detect được
 - Cross-component invariants: transaction boundaries nếu detect được
 
+**`selector-contract.md`** — testid contract (dùng `.claude/templates/main/feature/selector-contract-template.md`) — **chỉ feature có UI flows**:
+- Bảng Testid Contract từ Bước 4f: `testid | Element | Flow › Step | Interaction`. **Define ĐẦY ĐỦ từ flows** theo quy ước (KHÔNG harvest từng cái từ code).
+- Contract là trạng thái đích full-coverage — gap "code chưa gắn đủ" là việc implement sau, **KHÔNG** mark NEEDS_CLARIFY trong contract.
+- Thuần mô tả: KHÔNG track trạng thái implementation, KHÔNG chứa locator thô (xem template).
+
 **Nguyên tắc:**
 - fdd.md là **file mỏng** — chỉ mô tả tương tác giữa components, không lặp nội dung từ crd.md / cdd.md
+- selector-contract chỉ tạo cho feature có UI; feature backend-only → bỏ qua
 - Mọi phần không detect được → NEEDS_CLARIFY, không bịa
 
 ---
@@ -225,9 +241,9 @@ Sẽ tạo {N} features ({2N} files):
 Ghi tất cả? [y] hoặc review từng file trước [r]:
 ```
 
-**Stamp `template_version`:** frontmatter mỗi `frd.md`/`fdd.md` lấy `template_version` từ template tương ứng (xem `conventions.md` §7).
+**Stamp `template_version`:** frontmatter mỗi `frd.md`/`fdd.md`/`selector-contract.md` lấy `template_version` từ template tương ứng (xem `conventions.md` §7).
 
-**Change History:** Append entry vào section `## Change History` cuối mỗi `frd.md`/`fdd.md` vừa ghi (theo `conventions.md` §5.5):
+**Change History:** Append entry vào section `## Change History` cuối mỗi `frd.md`/`fdd.md`/`selector-contract.md` vừa ghi (theo `conventions.md` §5.5):
 
 ```markdown
 ### {YYYY-MM-DD} — manual — create
@@ -309,5 +325,6 @@ grep "NEEDS_CLARIFY" để tìm và fill in khi có thêm context.
 - [ ] Feature không có tests → AC section có NEEDS_CLARIFY rõ ràng
 - [ ] Verification Rules: rule reverse-engineer từ code đã đánh dấu source; field thiếu validation đã NEEDS_CLARIFY; không chứa regex/code/error message
 - [ ] prd.md Feature Index đã được update
-- [ ] Mỗi frd.md/fdd.md có `template_version` copy từ template tương ứng
+- [ ] Feature có UI: `selector-contract.md` đã **define ĐẦY ĐỦ từ flows** theo quy ước (full coverage, KHÔNG harvest rời rạc; neo Flow › Step; KHÔNG track implementation/locator); feature backend-only → KHÔNG tạo
+- [ ] Mỗi frd.md/fdd.md/selector-contract.md có `template_version` copy từ template tương ứng
 - [ ] NEEDS_CLARIFY items được list đầy đủ trong summary

package/skills/spec-frd/SKILL.md

@@ -22,8 +22,9 @@ Skill này là cặp greenfield đối xứng với `/spec-brownfield-feature` (
 - ✅ *Reference* component frd phụ thuộc (Components Used) + ghi component cần-nhưng-chưa-có như **candidate**.
 - ✅ Nếu feature mục tiêu là feature mới chưa có trong Index → **register một row vào `prd.md > Features`** (side-effect hợp lệ lên prd).
 - ✅ **Cascade vocabulary lên `domain.md`** (Bước 4b — pha *mô tả hệ thống*/WHAT): glossary term + **định nghĩa entity đầy đủ** (attributes). `Owner` của entity để `TBD` cho `/spec-sad` điền ở pha *thiết kế hệ thống* (HOW). BA duyệt trước khi ghi. Đây là điểm khác với phiên bản trước (`/spec-frd` từng không đụng domain) — vocabulary sinh ra ở feature-authoring time nên seed luôn, thay vì để domain rỗng tới integration đầu tiên.
+- ✅ **Derive `selector-contract.md`** (Bước 4c — chỉ khi feature có UI flows): skeleton testid từ User Flows theo quy ước. Thuần **cơ học** (không interview nặng), DEV/QC tinh chỉnh sau. KHÁC `fdd`/`test-design` ở dưới: nó chỉ là phép chiếu cơ học của flows BA vừa viết, không cần tư duy design/test của role khác.
 - ❌ KHÔNG tạo/sửa `crd.md`/`cdd.md` — component artifacts ra đời ở integration time qua `/spec-new` cascade.
-- ❌ KHÔNG tạo `fdd.md` (inter-component design) hay `test-design.md` (test) — để skill/role khác lo.
+- ❌ KHÔNG tạo `fdd.md` (inter-component design) hay `test-design.md` (test) — để skill/role khác lo. (`selector-contract.md` thì CÓ — xem ✅ trên.)
 - ❌ KHÔNG carve component / quyết `Owner` của shared entity (để `/spec-sad`/`/spec-new`); KHÔNG đổi status feature đã có; KHÔNG đụng sad.
 
 ## When to Use
@@ -247,6 +248,20 @@ BA quyết **định nghĩa entity** (WHAT); `Owner` để `/spec-sad` cascade b
 
 ---
 
+### Bước 4c: Derive selector-contract (testid skeleton từ flows)
+
+Selector-contract derive **thuần cơ học** từ User Flows (Bước 3 Phần 2) — không phải business decision như VR, không cần interview. Mục tiêu: seed một skeleton `data-testid` để DEV (gắn lúc code) + QC (viết POM lúc test) có **nguồn chung** ngay từ frd-time → drift bất khả thi. Xem `conventions.md` §3.3 > `selector-contract.md`.
+
+**Điều kiện sinh:** chỉ khi User Flows có **bước tương tác UI** (user click/fill/select hoặc cần assert kết quả trên màn). Feature thuần backend / không UI → **bỏ qua, KHÔNG tạo file** (không có e2e-auto/func-auto UI test thì không cần testid).
+
+**Cách derive:** rà mỗi bước trong flow; bước nào user **tương tác** (click/fill/select) hoặc test cần **assert** trên UI → một row:
+- `testid` theo quy ước `{feature-slug}-{element}[-{qualifier}]` (`conventions.md` §3.3).
+- `Element` = mô tả control; `Flow › Step` = neo về đúng bước (`{Flow N} › "{nhãn bước}"`); `Interaction` = `action`/`assert`/`nav`.
+
+Đây là **skeleton mô tả** — chỉ liệt kê element flow nêu rõ; element mơ hồ / list động / element QC cần thêm để DEV-QC tinh chỉnh sau (section Notes). KHÔNG track trạng thái implementation, KHÔNG chứa locator thô. Surface ở Bước 5/6 để user duyệt cùng draft frd.
+
+---
+
 ### Bước 5: Write — sinh draft
 
 Dùng `.claude/templates/main/feature/frd-template.md` làm skeleton, điền nội dung từ interview.
@@ -259,6 +274,7 @@ Hiển thị **toàn bộ draft** cho user — chưa ghi file. Kèm:
 - danh sách component candidate (nếu có) và VR còn `TBD`;
 - **Open Questions** còn mở (câu hỏi clarify + component candidate) để BA xác nhận hoặc giải quyết trước khi save;
 - **danh sách domain vocabulary đề xuất** (Bước 4b): glossary term mới + định nghĩa shared entity (`Owner: TBD`), để BA duyệt trước khi cascade lên `domain.md`.
+- **selector-contract skeleton** (Bước 4c, nếu feature có UI flows): bảng testid derive cơ học từ flows, để user liếc qua (DEV/QC tinh chỉnh sau — không phải quyết định của BA).
 
 #### Verification Rules — quy ước sinh
 
@@ -280,6 +296,7 @@ Hiển thị **toàn bộ draft** cho user — chưa ghi file. Kèm:
 > - Verification Rules đã confirm với BA chưa (không còn TBD ngoài ý muốn)?
 > - Components Used đúng chưa? Component candidate (nếu có) có hợp lý để chuyển cho /spec-sad không?
 > - Glossary term / định nghĩa shared entity đề xuất cascade lên domain đã đúng chưa? (term có phải vocabulary nghiệp vụ thật, entity có đáng là shared không, attributes đủ chưa?)
+> - Selector-contract skeleton (nếu có) đã khớp các bước tương tác UI trong flows chưa? (testid đúng quy ước, neo đúng Flow › Step)
 
 Chỉ ghi file sau khi user confirm. Yêu cầu chỉnh → cập nhật draft → hỏi lại.
 
@@ -336,13 +353,17 @@ Append **một** Change History entry vào `domain.md`, operation = `manual` (au
 
 (Nếu domain.md đang là skeleton create lần đầu thì entry vẫn `manual`/`update` — file đã được `/spec-prd` scaffold với operation `create` từ trước.) Atomic với 7a: domain cascade fail → rollback cả frd. `Owner` của entity do `/spec-sad`/`/spec-new` cascade bổ sung sau (HOW phase) qua `[MODIFY Owner]`.
 
-**7c. KHÔNG đụng gì khác.** Không đổi status của các feature *đã có* (frd tồn tại ≠ integration bắt đầu; marker "→ frd.md tồn tại" derive từ file existence). Không thêm component vào Index (chỉ candidate). Không carve component / không tự quyết `Owner` của shared entity. Không tạo crd/cdd/fdd/test-design. Không đụng sad.
+**7e. (Chỉ khi Bước 4c có sinh selector-contract)** Ghi `.specs/main/feature/{F-XXX}-{slug}/selector-contract.md` từ `.claude/templates/main/feature/selector-contract-template.md` — status `draft`, `template_version` copy từ template, `feature_id: F-XXX`. Điền bảng Testid Contract từ skeleton derive ở Bước 4c. Append Change History entry operation = `manual` / `create` ("Initial testid skeleton derive từ frd User Flows"). Atomic với 7a — fail thì rollback cả frd. Re-derive về sau khi flows đổi đi qua `/spec-new`.
+
+**7c. KHÔNG đụng gì khác.** Không đổi status của các feature *đã có* (frd tồn tại ≠ integration bắt đầu; marker "→ frd.md tồn tại" derive từ file existence). Không thêm component vào Index (chỉ candidate). Không carve component / không tự quyết `Owner` của shared entity. Không tạo crd/cdd/fdd/test-design (selector-contract thì có — xem 7e). Không đụng sad.
 
 **7d. Thông báo kết quả:**
 
 ```
 ✓ .specs/main/feature/{F-XXX}-{slug}/frd.md đã được tạo (status: draft)
 
+{nếu feature có UI flows} ✓ selector-contract.md đã tạo (skeleton testid từ flows — DEV gắn lúc code, QC dùng lúc viết POM)
+
 {nếu có} Domain cascade (pha mô tả hệ thống):
   - Glossary: +{N} term
   - Shared Entities: +{N} entity (định nghĩa đầy đủ; Owner TBD — chờ /spec-sad gán ở pha thiết kế)
@@ -401,6 +422,7 @@ Bước tiếp theo:
 - [ ] Components Used reference C-XXX có sẵn; component mới ghi candidate + surface cho /spec-sad
 - [ ] Nếu register feature mới: prd Features có row [NEW] + Change History entry; status feature đã có KHÔNG đổi
 - [ ] Domain cascade (nếu có vocabulary mới, đã BA confirm): Glossary term ghi đủ định nghĩa; Shared Entity ghi đủ definition + attributes với `Owner: TBD` (KHÔNG tự gán C-XXX); domain.md có Change History entry operation = `manual`
-- [ ] KHÔNG tạo crd/cdd/fdd/test-design; KHÔNG carve component / gán Owner entity; KHÔNG đụng sad
+- [ ] Nếu feature có UI flows: `selector-contract.md` đã derive (skeleton testid từ flows, quy ước tên `{slug}-{element}` đúng, neo Flow › Step, KHÔNG track implementation / locator thô); feature thuần backend không UI → KHÔNG tạo
+- [ ] KHÔNG tạo crd/cdd/fdd/test-design (selector-contract là ngoại lệ — derive cơ học); KHÔNG carve component / gán Owner entity; KHÔNG đụng sad
 - [ ] Change History entry (frd) operation = `manual` (luôn `create`)
 - [ ] User đã confirm trước khi ghi file