@shanyucoder/flowgrid 0.1.0

package/harness/tests/rules/flowgrid-test-optional-accelerators.mdc

@@ -0,0 +1,21 @@
+---
+description: bộ test optional accelerator fallback and event contract
+alwaysApply: true
+---
+
+# bộ test optional accelerators
+
+ArtifactGraph accelerates coverage and search but is never required. When it is
+missing or fails, continue with deterministic local coverage/search. Assign one
+stable `runId` per run and emit exactly one `flowgrid.missing-optional` event per
+`runId` + optional pair, after fallback completes; deduplicate all retries.
+
+ArtifactGraph is local-only: in this repo it indexes this repo's own data
+(taxonomy/coverage hints) and never follows `FLOWGRID_DOCS_ROOT` or
+`FLOWGRID_TESTS_DOC`. Canonical docs/tests-hub evidence always flows through
+those bộ test pointers, never through ArtifactGraph.
+
+Events must conform to
+`.cursor/schemas/flowgrid-test/missing-optional-event.schema.json`. Metrics count only
+successful file reads and exact raw bytes read into context as `fileReads` and
+`contextBytes`. Never estimate tokens, reads, bytes, or savings.

package/harness/tests/rules/plans-docs-first.mdc

@@ -0,0 +1,13 @@
+---
+description: Plans docs-first — rule SSOT in docs hub; no TC→docs sync
+globs: cases/**/*,scenarios/**/*,suites/**/*
+alwaysApply: false
+---
+
+# Plans — docs-first
+
+- **Rule / acceptance SSOT = docs hub.** Tests hub chỉ `refs.rule` (id + link). Không copy nội dung rule vào YAML để “sửa cho tiện”.
+- Grill thấy **scope hở / rule mơ hồ** → handoff docs (`/update-spec`, grill-docs). **Không** vá bằng testcase.
+- Chỉ thêm/sửa `TC-*` khi docs đã rõ và thiếu **bao phủ** (`coverage`).
+- YAML = máy (gen Playwright). MD = member đọc đối chiếu docs.
+- Chi tiết: `landscape/NOTE-testing-architecture.md`.

package/harness/tests/skills/grill-testcase/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: grill-testcase
+description: /grill-testcase — audit E2E plan YAML/MD on the tests hub.
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /grill-testcase
+
+**Owner:** bộ test (`--type=tests`)
+
+Audit plans only. Spec holes hand off to docs-hub `/update-spec` or `/grill-bqa` (bộ docs), never invent acceptance. **[MANDATORY]** When handing off, you MUST output a comprehensive gap report in the Chat Thread formatted as a complete, ready-to-use prompt starting with `/docs-hub` (e.g., `/docs-hub /update-spec [details...]`). This prompt must detail exactly what business rules or coverage are missing, enabling the user to copy-paste it directly to run the docs-hub skill.
+
+Route Functions/W-* evidence through bộ docs and symbol/call-graph evidence
+for repo X through its Platform DNA-wired `codegraph-<repo-key>` server. Use
+`FLOWGRID_DOCS_ROOT` / `FLOWGRID_TESTS_DOC` for pointer evidence; never build or
+query a workspace-parent graph.
+
+## Target / ID Resolution Rule
+
+- User prompt MAY specify a screen ID, module ID, or short slug (e.g. `W-AD-AUTH-001`, `CMP-ADM-000`, `login`).
+- **[MANDATORY]** Agent MUST use `flowgrid_docs_route` or `flowgrid_docs_get_element` (or glob search under `FLOWGRID_DOCS_ROOT` / `surfaces/...`) to resolve target paths.
+- **[MANDATORY]** Read the entire function **`*.bundle.yaml`** (sibling of `ir/`). Cross-reference plans against bundle `userStories`, `acceptanceCriteria`, `spec.ui`, and `design.*` — not split IR files.
+- If scenarios/acceptance are thin or missing → hand off docs-hub `/update-spec` or `/spec` (paste-ready prompt). Do not patch bundle from tests hub.
+- **[STRICTLY FORBIDDEN]** Do NOT read generated `*.md`.
+- If auditing **SC-***, the YAML/MD path MUST mirror the docs `FLOW-*.md` (cluster/module/surface `common/processes/` or `architecture/03-business-process/`). Flag `scenarios/auth/…` or `common/` leftovers.
+
+## Audit Rules
+
+- **[MANDATORY]** Run **`flowgrid cases:gate --strict --docs-root $FLOWGRID_DOCS_ROOT`** before sign-off (replaces ad-hoc check + audit only).
+- **[MANDATORY]** Per-file spot check: `flowgrid audit testcase <TC.yaml> --bundle <resolved.bundle.yaml>` when fixing one file.
+- Cross-flow SC: `flowgrid audit scenario <SC.md> --tests-docs <FLOWGRID_TESTS_DOC>`
+- **Audit Coverage against Scenarios & testMatrix:** **[MANDATORY]** Cross-reference test cases with `userStories.scenarios`, validation inventory, and `design.actions` in the **bundle** (consume `bundleCrossGaps` from audit JSON).
+  - Ensure that every scenario defined in the design has corresponding test cases and that all `acceptance` criteria are verified.
+  - **[MANDATORY]** Verify that the test case contains a comprehensive `testMatrix` covering: `positive_boundary`, `negative_length/format`, `negative_duplicate`, `concurrency_double_submit`, and `network_interruption`. Flag plans that only test the happy path as incomplete coverage.
+- **Check Business Descriptions:** **[MANDATORY]** When auditing plans, ensure that `description` or `story` fields are present, detailed, and align with the element `meaning` / `purpose`. Flag plans that have sparse 1-liners or lack clear business context and expected outcomes. Advise the user or authoring agent to provide richer business logic.
+- **Check YAML Syntax Integrity:** **[MANDATORY]** Ensure YAML files do not contain raw JavaScript expressions embedded as values (e.g., `"a".repeat(256)`) without being properly wrapped in single quotes. If you spot JS expressions that would cause a YAML parser to crash (`Unexpected scalar at node end`), flag them immediately.
+
+## Accelerators (optional)
+
+```text
+if local ArtifactGraph available: taxonomy/coverage/gap slice from this tests hub
+else: local deterministic coverage/search over targeted plan/docs evidence
+```
+
+ArtifactGraph indexes this tests hub only; spec-hole handoffs go to docs-hub
+`/update-spec` (bộ docs), not through ArtifactGraph.
+
+Use one stable `runId` per run. When ArtifactGraph is missing, finish the local
+fallback before emitting exactly one `flowgrid.missing-optional` event for that
+`runId` + `artifactgraph`; retries must not emit again. Conform to
+`.cursor/schemas/flowgrid-test/missing-optional-event.schema.json` and include only
+actual successful `fileReads` and exact raw `contextBytes`, never estimates.

package/harness/tests/skills/scenario/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: scenario
+description: /scenario — author cross-flow E2E scenario YAML/MD on the tests hub.
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /scenario
+
+**Owner:** bộ test (`--type=tests`)
+
+Author cross-flow scenarios (SC) on the current tests hub. Design rules stay on the docs hub.
+
+Scenarios test a **business process** (`FLOW-*`) that spans multiple screens (`W-*`) or modules. They mirror the docs FLOW file **after** bộ docs LCA `common/` placement (not a flat `common/` tree).
+
+## Output Rules
+
+- **Rich Business Descriptions:** **[MANDATORY]** When generating YAML scenarios, you MUST provide a detailed `description` (or `story`) field. Do not leave them empty or write sparse 1-liners.
+- Explain the **Business Context**: Why does this cross-flow exist? What is the real-world process?
+- Outline the **Expected Outcome**: Detail what the end-to-end user journey should achieve.
+- Include metadata like `priority`, `status`, `module`, and `tags` if available.
+- **[MANDATORY]** Frontmatter MUST list every `W-*` touched by the journey: `screens: [W-…, W-…]` (keep legacy `screen:` for primary screen if needed).
+- **[MANDATORY]** After authoring, run `flowgrid audit scenario <SC file> --tests-docs <hub>` (or `FLOWGRID_TESTS_DOC`); fix `SC_SCREEN_NO_TC` gaps with `cases/**/TC-*.yaml` or `coverage_deferred` + `QA-*` per screen.
+- **Valid YAML Syntax:** **[MANDATORY]** Do NOT write raw JavaScript expressions directly into YAML values. If you need a long string, wrap the exact code expression entirely in single quotes (e.g., `value: '"a".repeat(256)'`).
+- **Concise Naming Convention:** **[MANDATORY]** The `id` must be short (e.g., `SC-CHK-01`). The `title` MUST be extremely short and concise (limit 15-20 characters, e.g., `Guest Checkout`, `Refund Flow`). Put long explanations into `description`, not `title` or `id`.
+
+## Target / ID Resolution Rule
+
+- **[MANDATORY]** Agent MUST locate the **`FLOW-*.md`** file on the docs hub (`FLOWGRID_DOCS_ROOT`) via `flowgrid_docs_route` / `flowgrid_docs_get_element` / glob. Filenames are `FLOW-…md`, not `flow-*`.
+- Search in this order (same LCA as bộ docs `common-scope.md`):
+  1. `surfaces/<surface>/<CMP-id>/<NN>/common/processes/FLOW-*.md` (cluster)
+  2. `surfaces/<surface>/<CMP-id>/common/processes/FLOW-*.md` (module)
+  3. `surfaces/<surface>/common/processes/FLOW-*.md` (surface)
+  4. `surfaces/common/processes/FLOW-*.md` (cross-surface product common)
+  5. `architecture/03-business-process/FLOW-*.md` (org catalog only)
+- **Strict:** Only author a scenario if that `FLOW-*.md` exists. Missing FLOW or thin business rules → hand off to docs-hub `/business-process` or `/update-spec`, do not invent SC. **[MANDATORY]** When handing off, you MUST output a comprehensive gap report (formatted as a complete, ready-to-use prompt starting with `/docs-hub`) detailing exactly what flows or business rules are missing, so the user can copy-paste it directly to run the docs-hub skill.
+- **[STRICTLY FORBIDDEN]** Do not treat `common/yaml/` or `common/patterns/` as scenario sources.
+
+## Directory Mirroring Rule (Docs SSOT)
+
+Mirror the FLOW file path onto the tests hub. Strip **only** these prefixes:
+
+| Docs FLOW path | Tests hub |
+|----------------|-----------|
+| `surfaces/<rest>/common/processes/FLOW-checkout.md` | `scenarios/<rest>/common/processes/FLOW-checkout/SC-*.yaml` |
+| `architecture/03-business-process/FLOW-checkout.md` | `scenarios/architecture/03-business-process/FLOW-checkout/SC-*.yaml` |
+
+Examples:
+
+- Docs `surfaces/admin/CMP-ADM-002/02/common/processes/FLOW-checkout.md` → `scenarios/admin/CMP-ADM-002/02/common/processes/FLOW-checkout/SC-*.yaml`
+- Docs `surfaces/admin/CMP-ADM-002/common/processes/FLOW-onboard.md` → `scenarios/admin/CMP-ADM-002/common/processes/FLOW-onboard/SC-*.yaml`
+
+Do **not** flatten to `scenarios/auth/…`. Do **not** use `common/` (legacy). Keep numeric cluster folders (`02/`) in the tests path.
+
+## Accelerators (optional)
+
+```text
+if local ArtifactGraph available: taxonomy/coverage/gap hints from this tests hub
+else: local deterministic coverage/search from scoped plan + docs evidence
+```
+
+ArtifactGraph on the tests hub uses `--type=common,test` and indexes this repo only. Docs-hub FLOW/design evidence comes through explicit docs references, never through ArtifactGraph.

package/harness/tests/skills/test-api/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: test-api
+description: /test-api — author api-e2e TC YAML + Playwright request specs (partner/webhook hooks).
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this `SKILL.md` via file-read tool.
+> **[MANDATORY]** Integration contract SSOT on docs-hub: `surfaces/integrations/`, `01-backend-spec` — skills `/api-integration`, `/grill-integration-spec`.
+
+# /test-api — API hook E2E (tests-docs + codegen)
+
+**Owner:** tests-docs hub (`genType: api-e2e`). **Not** UI Page Object lane — use `/testcase` + `testcase:gen` for portal E2E.
+
+---
+
+## When to use
+
+- Webhook inbound/outbound, partner Open API, export hooks **without** portal steps in the same TC file.
+- Cross-flow **SC-*** that spans UI + API: author **two** TC files (UI `genType: e2e` + API `genType: api-e2e`) under the same scenario.
+
+---
+
+## Author TC YAML
+
+- **[MANDATORY]** `schemaVersion: 2`, `genType: api-e2e`, `refs.screen` matching `API-*`.
+- **[MANDATORY]** `api.baseUrlEnv` (CI env) + `api.baseURL` fallback; optional `api.defaultHeaders`.
+- **[MANDATORY]** `apiSteps[]`: `method`, `path`, `expectStatus`, optional `body`, `headers`, `expectJson`, `expectBodyContains`.
+- **[MANDATORY]** Human `steps[]` + `testMatrix` (same gate as UI TC).
+- Mirror path: `cases/.../integrations/.../TC-*.yaml` aligned with docs integration leaf.
+
+Template: `harness/tests/templates/TC.example-api.yaml`.
+
+Audit: `flowgrid audit testcase <TC.yaml> --bundle <integration.bundle.yaml>` when bundle exists on docs hub.
+
+---
+
+## Generate Playwright (request)
+
+```bash
+flowgrid testcase:gen:api --testcase cases/.../TC-PARTNER-EXPORT.yaml
+flowgrid testcase:gen:api:dry --id TC-PARTNER-EXPORT
+flowgrid testcase:gen:api --all   # every genType api-e2e in hub
+```
+
+Env: `FLOWGRID_TESTS_DOC`, `FLOWGRID_API_TEST_BASE_URL` (or custom `api.baseUrlEnv`).
+
+Output (e2e-root): `tests/api-e2e/<module>/<TC-id>.api.spec.ts` — run with Playwright project that includes `tests/api-e2e/**`.
+
+---
+
+## After gen
+
+- Fix auth (HMAC, rotating tokens) in generated spec or TC `headers` — do not commit secrets; use env in CI.
+- Hybrid UI → API: run UI spec first (or fixture API) then API spec; share `orderId` via `process.env` / `test.info().attach` / storageState as team convention.
+- Postman/Newman collections remain optional; link via TC tag `contract-postman` (no FlowGrid gen yet).
+
+---
+
+## Related
+
+- Author plan: `/testcase` (UI), `/scenario` (SC-*)
+- Grill hub: `/grill-testcase`
+- Docs SSOT: `/api-integration`, `/grill-integration-spec`
+- UI E2E after skeleton: `/test` + `testcase:gen`

package/harness/tests/skills/testcase/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: testcase
+description: /testcase — author E2E plan YAML/MD on the tests hub (not Playwright).
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+> **[MANDATORY]** Read the entire function **`*.bundle.yaml`** (sibling of `ir/` on docs hub) BEFORE authoring any test case. Do not split-read `ir/spec.yaml` + `ir/design.yaml` for coverage traceability.
+
+# /testcase — E2E Test Case Authoring (Tests Hub)
+
+**Owner:** bộ test (`--type=tests`). Design rules stay on docs hub. Playwright generation is FE `/test`.
+
+---
+
+## Rule: Audit Interlock & Workload Threshold (Law 2)
+
+- **[MANDATORY]** Always run static audit first: `flowgrid audit testcase <cases/.../TC-*.yaml> --bundle <function.bundle.yaml>` (bundle path = same leaf you read for SSOT).
+- **[MANDATORY]** Every new TC file MUST declare **`schemaVersion: 2`** and pass `flowgrid cases:check` (JSON Schema) plus audit (matrix facets).
+  - ✅ Consume JSON gap report to fix coverage gaps.
+  - **Threshold Interlock (Law 2):**
+    - **Small Scope (≤5 missing testcases/gaps):** Resolve inline in chat thread.
+    - **Large Scope (≥10 missing testcases/gaps):** **[MANDATORY HARD STOP IN CHAT]**. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 testcases per phase) with disk offloading at boundaries.
+  - ❌ Do not skip audit and proceed to authoring directly.
+
+---
+
+## Rule: Bundle SSOT (read)
+
+- **[MANDATORY]** Resolve the function leaf via `flowgrid_docs_route` / glob → read **`…/<slug>.bundle.yaml`** (exactly one bundle per function folder).
+- **[MANDATORY]** Trace coverage from bundle: `userStories` (top-level), `acceptanceCriteria`, `spec.ui`, `design.sections`, `design.actions`, `design.stateMatrix`.
+- **[MANDATORY]** If bundle missing or `userStories.scenarios` / `acceptanceCriteria` empty → **STOP**; hand off `/docs-hub /update-spec` or `/spec` (paste-ready gap prompt). Do NOT invent tests.
+- **[MANDATORY]** If `flowgrid check` / split:check fails on that bundle → hand off docs-hub to reconcile bundle ↔ `ir/*` before testcase grill.
+- **[STRICTLY FORBIDDEN]** Write docs hub (`ir/*`, `*.bundle.yaml`). Do NOT use generated `*.md` as SSOT.
+
+**Codegen / Playwright** still consume **`ir/design.yaml`** on FE repo after split; bundle is the **authoring** SSOT for test design.
+
+---
+
+## Rule: ID Resolution
+
+- **[MANDATORY]** Use `flowgrid_docs_route` or `flowgrid_docs_get_element` (or glob under `FLOWGRID_DOCS_ROOT` / `surfaces/…`) to resolve target paths from ID or slug.
+- **[STRICTLY FORBIDDEN]** Do NOT demand full filesystem path from user when ID or slug is given.
+
+---
+
+## Rule: Directory Mirroring (Docs SSOT)
+
+- **[MANDATORY]** Mirror function folder: `cases/<relative-path>/TC-*.yaml`.
+  - ✅ `surfaces/admin/CMP-ADM-002/02/01/login/` → `cases/admin/CMP-ADM-002/02/01/login/TC-*.yaml`
+  - ❌ `cases/admin/auth/W-…` — invented path not matching docs structure.
+- Cross-flow plans → `/scenario` (mirror `common/processes/FLOW-*` or `architecture/03-business-process/FLOW-*`).
+
+---
+
+## Rule: Test Case Content Requirements & Equivalence Partitioning (testMatrix)
+
+- **[MANDATORY]** Root field **`schemaVersion: 2`** on every `TC-*.yaml` (release gate SSOT).
+- **[MANDATORY]** Populate **`traceability`** (`bundleScreen`, `bundleScenarios[]` slugs, `acceptanceRefs[]` as `AC-01`…, `actionRefs[]` as `btn_*`) from bundle before grill sign-off — required for `cases:gate --strict`.
+- **[MANDATORY]** Map cases to `userStories.scenarios`, field `validation`, and `design.actions` from the **bundle** (whole file).
+- **[MANDATORY]** Every test case file MUST declare a structured `testMatrix` covering:
+  1. `positive_boundary`: Minimum / maximum valid lengths and ranges.
+  2. `negative_length` / `negative_format`: Under min, over max, and regex pattern violations with expected localized error messages.
+  3. `negative_duplicate`: Server-side remote uniqueness violation (expected 409).
+  4. `concurrency_double_submit`: Immediate button disablement and idempotency check.
+  5. `network_interruption` / `exception`: Offline banner and form state preservation.
+- **[MANDATORY]** Consult `meaning` + `purpose` fields of UI elements when writing step descriptions and test data.
+- **[MANDATORY]** `description` / `story` field MUST be rich — explain business context, real-world scenario, expected outcome from user perspective.
+  - ✅ Multi-sentence description covering why case exists + what user should experience.
+  - ❌ Single-liner `"Test login form"`.
+- **[MANDATORY]** `id`: short (e.g. `TC-AUTH-01`). `title`: max 15-20 characters (e.g. `Valid Login`, `Empty Email`). All long explanations belong in `description`.
+- **[MANDATORY]** Include: `priority`, `status`, `module`, `tags`, verification of `userStories.acceptance` criteria.
+- **[MANDATORY]** YAML test data must be valid YAML — no raw JavaScript expressions (e.g. `"a".repeat(256)` → write the actual repeated string or wrap in single quotes).
+
+---
+
+## Rule: Route Cross-Repo Evidence
+
+- **[MANDATORY]** Route evidence by owner:
+  - Functions/`W-*` → bộ docs
+  - Plan/docs → `FLOWGRID_TESTS_DOC` / `FLOWGRID_DOCS_ROOT`
+  - Symbols for repo X → `codegraph-<repo-key>` (Platform DNA-wired server)
+- **[STRICTLY FORBIDDEN]** Never query one workspace-wide graph. Never hand-edit MCP config.
+
+---
+
+## Verification Checklist
+
+- [ ] Audit script run; all coverage gaps resolved or gap report generated for docs hub.
+- [ ] Function `*.bundle.yaml` read in full (not partial slices).
+- [ ] All `userStories.scenarios` covered by corresponding test cases.
+- [ ] Equivalence Partitioning & Boundary Value Analysis `testMatrix` declared (min/max boundary, regex failure, duplicate 409, double-submit lock, offline preservation).
+- [ ] Scenario markdown (`SC-*.md`) formatted with IEEE 29119 Boundary Analysis Table & Gherkin BDD.
+- [ ] `meaning` + `purpose` used for step descriptions.
+- [ ] `id` short; `title` ≤20 chars; `description` is rich and business-meaningful.
+- [ ] YAML syntax valid — no JS expressions in test data values.
+- [ ] Directory structure mirrors docs SSOT path exactly.

package/harness/tests/templates/SC.example.md

@@ -0,0 +1,86 @@
+---
+id: SC-EXAMPLE
+module: CMP-01-auth
+surface: admin
+screen: W-AD-AUTH-001
+screens:
+  - W-AD-AUTH-001
+rules:
+  - RUL-00-example
+coverage_plan:
+  - happy
+  - boundary
+  - validation
+  - concurrency
+  - security
+---
+
+# SC-EXAMPLE — Xác Thực & Khởi Tạo Hồ Sơ Khách Hàng
+
+Scenario thuộc **CMP-01-auth** · Tính năng năng lực **CAP-AUTH-001**.  
+Quy tắc chi tiết và schema cơ sở dữ liệu tham chiếu tại **Docs Hub** (cite ID: `spec.yaml`).
+
+| Thuộc tính | Giá trị |
+|---|---|
+| **Scenario ID** | `SC-EXAMPLE` |
+| **Module** | `CMP-01-auth` |
+| **Bề mặt (Surface)** | `admin` |
+| **Màn hình (Screen)** | `W-AD-AUTH-001` (`/admin/records/create`) |
+| **Mức độ ưu tiên** | `High` |
+
+## 1. Bối Cảnh Nghiệp Vụ & Phân Tích Rủi Ro (Business Context & Risk Analysis)
+
+Màn hình khởi tạo hồ sơ là cửa ngõ dữ liệu tài chính của khách hàng. Nếu bỏ sót kiểm tra trùng mã hoặc không xử lý chặn click đúp (double-submit), hệ thống sẽ tạo các bản ghi rác gây xung đột số liệu doanh thu và vi phạm tính toàn vẹn dữ liệu kế toán.
+
+## 2. Hành Vi Chuẩn BDD (Behavior: Given / When / Then)
+
+- **Given (Tiền điều kiện):** Người dùng đăng nhập thành công với vai trò Quản trị viên (`ADMIN`), tài khoản có quyền `records.create`, và chưa tồn tại bản ghi nào có mã `REC-2026-001` trong cơ sở dữ liệu.
+- **When (Thao tác):** Người dùng nhập đầy đủ các trường thông tin hợp lệ (mã hồ sơ, tên hồ sơ, chọn gói dịch vụ) và nhấn nút "Lưu & Xác Nhận".
+- **Then (Hậu điều kiện):** Hệ thống khóa nút để tránh gửi trùng lặp, gửi request kèm header `X-Idempotency-Key`, tạo mới bản ghi thành công trong bảng `records`, hiển thị Toast thông báo màu xanh và điều hướng sang màn hình chi tiết `W-ADM-DETAIL-01`.
+
+## 3. Ma Trận Test Phân Hoạch Tương Đương & Phân Tích Giá Trị Biên (Equivalence Partitioning & Boundary Test Matrix - IEEE 29119)
+
+| Mã Case (Case ID) | Khía Cạnh Kiểm Thử (Facet) | Dữ Liệu Đầu Vào (Input Data) | Kết Quả Mong Đợi (Expected Outcome) | HTTP Status & UI State | Tự Động Hóa (Automation Case) |
+|---|---|---|---|---|---|
+| **TC-VAL-01** | `positive_boundary` (Biên tối thiểu) | `code: "REC01"` (5 chars), `name: "Hồ sơ A"` | Form hợp lệ, gửi dữ liệu thành công | `HTTP 200` · Toast Success xanh | `TC-EXAMPLE-VALID` |
+| **TC-VAL-02** | `positive_boundary` (Biên tối đa) | `code: "REC-2026-MAXIMUM-001"` (20 chars) | Form hợp lệ, gửi dữ liệu thành công | `HTTP 200` · Toast Success xanh | `TC-EXAMPLE-VALID` |
+| **TC-VAL-03** | `negative_length` (Dưới độ dài min) | `code: "REC"` (3 chars) | Chặn submit, báo lỗi inline dưới ô nhập | `Client Error` · "Độ dài từ 5 đến 20 ký tự" | `TC-EXAMPLE-INVALID` |
+| **TC-VAL-04** | `negative_format` (Sai regex ký tự) | `code: "rec_code_@!"` (chữ thường, ký tự lạ) | Chặn submit, báo lỗi inline dưới ô nhập | `Client Error` · "Chỉ gồm chữ in hoa, số và gạch" | `TC-EXAMPLE-INVALID` |
+| **TC-VAL-05** | `negative_duplicate` (Trùng lặp DB) | `code: "REC-EXISTING-001"` (đã có trong DB) | Server từ chối, highlight viền đỏ ô mã | `HTTP 409` · Toast Cảnh báo trùng lặp | `TC-EXAMPLE-DUPLICATE` |
+| **TC-ACT-06** | `concurrency_double_submit` | Click nút "Lưu" liên tục 2 lần trong 100ms | Nút khóa disabled tức thì, chỉ 1 request gửi đi | `UI Locked` · Không tạo 2 bản ghi trùng | `TC-EXAMPLE-CONCURRENCY` |
+| **TC-SYS-07** | `network_interruption` (Mất mạng) | Ngắt kết nối mạng ngay khi gửi request | Hiện banner cảnh báo mất kết nối, giữ nguyên dữ liệu form | `Network Banner` · Form state preserved | `TC-EXAMPLE-OFFLINE` |
+
+## 4. Bao Phủ Rủi Ro & Khía Cạnh Chất Lượng (Quality Dimensions Coverage)
+
+| Khía Cạnh (Dimension) | Mức Độ Bao Phủ | Ghi Chú Đảm Bảo Chất Lượng |
+|---|---|---|
+| **Happy Path & Workflow** | 100% | Toàn bộ luồng khởi tạo đến xem chi tiết hoàn tất |
+| **Boundary Value Analysis** | 100% | Kiểm thử đầy đủ tại ngưỡng min-1, min, max, max+1 |
+| **Data Integrity & Concurrency** | 100% | Kiểm tra unique mã hồ sơ qua async DB & chặn double-click |
+| **Security & RBAC** | 100% | Kiểm soát phân quyền nút bấm theo ma trận trạng thái |
+| **Fault Tolerance & Resilience** | 100% | Xử lý mất mạng giữ dữ liệu, xử lý timeout không resubmit trùng |
+
+```mermaid
+stateDiagram-v2
+  [*] --> NhapLieu: Mở form tạo mới (DRAFT)
+  NhapLieu --> KiemTraHopLe: Nhấn "Lưu & Xác Nhận"
+  KiemTraHopLe --> BaoLoiInline: Dữ liệu sai biên / format / thiếu trường
+  BaoLoiInline --> NhapLieu: Người dùng sửa lỗi
+  KiemTraHopLe --> KhoaGiaoDien: Hợp lệ (Lock double-submit)
+  KhoaGiaoDien --> GuiApiServer: Dispatch POST + X-Idempotency-Key
+  GuiApiServer --> TrungLap409: Mã hồ sơ đã tồn tại
+  TrungLap409 --> NhapLieu: Highlight ô mã & hiển thị cảnh báo
+  GuiApiServer --> ThanhCong200: Tạo mới thành công
+  ThanhCong200 --> ChuyenTrangChiTiet: Toast xanh + redirect W-ADM-DETAIL-01
+  ChuyenTrangChiTiet --> [*]
+```
+
+## 5. Danh Sách Test Cases Chi Tiết (Test Cases Mapping)
+
+| Mã Case (ID) | Khía Cạnh | Mức Độ Ưu Tiên | Thư Mục Test Hub |
+|---|---|---|---|
+| `TC-EXAMPLE-VALID` | happy, boundary | Critical | `cases/admin/CMP-01-auth/01/create/` |
+| `TC-EXAMPLE-INVALID` | validation, boundary | High | `cases/admin/CMP-01-auth/01/create/` |
+| `TC-EXAMPLE-DUPLICATE` | concurrency, remote_unique | High | `cases/admin/CMP-01-auth/01/create/` |
+| `TC-EXAMPLE-CONCURRENCY` | interaction, double_submit | High | `cases/admin/CMP-01-auth/01/create/` |
+| `TC-EXAMPLE-OFFLINE` | reliability, offline_resilience | Medium | `cases/admin/CMP-01-auth/01/create/` |

package/harness/tests/templates/TC.example-api.yaml

@@ -0,0 +1,45 @@
+schemaVersion: 2
+id: TC-EXAMPLE-PARTNER-EXPORT
+title: Partner export hook
+summary: Ví dụ — đối tác đọc export API sau khi đơn đã sẵn sàng.
+story: |
+  Given đơn ORD-EXAMPLE-001 đã được portal xử lý
+  When đối tác gọi GET export
+  Then payload trả về trạng thái ready
+genType: api-e2e
+feature: partner-example
+coverage: [happy, authorization]
+refs:
+  screen: API-EXAMPLE-EXPORT-001
+  scenario: SC-EXAMPLE
+  module: CMP-INT-EXAMPLE
+  api: integration.partner.export
+api:
+  baseUrlEnv: FLOWGRID_API_TEST_BASE_URL
+  baseURL: http://localhost:3000
+  defaultHeaders:
+    Accept: application/json
+apiSteps:
+  - id: partner-export
+    method: GET
+    path: /api/v1/integrations/example/export/ORD-EXAMPLE-001
+    headers:
+      Authorization: Bearer ${PARTNER_TOKEN}
+    expectStatus: 200
+    expectJson:
+      orderId: ORD-EXAMPLE-001
+      status: ready
+testMatrix:
+  - facet: positive_boundary
+    description: Export trả 200 và status ready
+    expected:
+      status: 200
+steps:
+  - Partner gọi GET export với token hợp lệ
+  - Hệ thống trả JSON orderId và status
+tags: [integration, partner-api, webhook]
+automation: automated
+dimensions:
+  business: [workflow]
+  technical: [api]
+  quality: [security]

package/harness/tests/templates/TC.example.yaml

@@ -0,0 +1,127 @@
+schemaVersion: 2
+id: TC-EXAMPLE-VALID
+title: Example flow with valid input should succeed
+summary: Ví dụ — luồng hợp lệ đi đến trạng thái thành công.
+story: |
+  Given điều kiện đầu vào hợp lệ và người dùng có quyền
+  When thực hiện thao tác nhập liệu và nhấn lưu
+  Then hệ thống tạo mới thành công và chuyển trạng thái
+refs:
+  module: CMP-01-auth
+  surface: admin
+  scenario: SC-EXAMPLE
+  example: EX-EXAMPLE-01
+  screen: W-AD-AUTH-001
+coverage: [happy, boundary, validation, concurrency, exception]
+priority: high
+automation: automated
+tags: [smoke, e2e, ui, unit]
+dimensions:
+  business: [workflow]
+  technical: [ui, api]
+  quality: [reliability, security]
+
+preconditions:
+  - "User logged in with role 'ADMIN'"
+  - "No pre-existing record with code 'REC-2026-001'"
+
+# BẢNG MA TRẬN TEST PHÂN HOẠCH TƯƠNG ĐƯƠNG & PHÂN TÍCH GIÁ TRỊ BIÊN (TEST MATRIX)
+testMatrix:
+  - caseId: TC-VAL-01
+    facet: "positive_boundary"
+    description: "Nhập đúng giá trị biên tối thiểu (min boundary: 5 chars)"
+    input:
+      record_code: "REC01"
+      record_name: "Hồ sơ chuẩn A"
+      service_level: "STANDARD"
+    expected:
+      valid: true
+      status: 200
+      feedback: "Lưu hồ sơ thành công"
+
+  - caseId: TC-VAL-02
+    facet: "positive_boundary"
+    description: "Nhập đúng giá trị biên tối đa (max boundary: 20 chars)"
+    input:
+      record_code: "REC-2026-MAXIMUM-001"
+      record_name: "Hồ sơ chuẩn B"
+      service_level: "STANDARD"
+    expected:
+      valid: true
+      status: 200
+
+  - caseId: TC-VAL-03
+    facet: "negative_length"
+    description: "Nhập dưới độ dài tối thiểu (< 5 chars)"
+    input:
+      record_code: "REC"
+    expected:
+      valid: false
+      errorField: "record_code"
+      errorMessage: "Độ dài mã hồ sơ bắt buộc từ 5 đến 20 ký tự"
+
+  - caseId: TC-VAL-04
+    facet: "negative_format"
+    description: "Nhập sai định dạng regex (chứa ký tự đặc biệt hoặc chữ thường)"
+    input:
+      record_code: "rec_code_@!"
+    expected:
+      valid: false
+      errorField: "record_code"
+      errorMessage: "Mã hồ sơ chỉ được gồm chữ in hoa, chữ số và ký tự gạch (- _)"
+
+  - caseId: TC-VAL-05
+    facet: "negative_duplicate"
+    description: "Nhập mã đã tồn tại trong DB (remote unique violation)"
+    input:
+      record_code: "REC-EXISTING-001"
+    expected:
+      valid: false
+      status: 409
+      errorField: "record_code"
+      errorMessage: "Mã hồ sơ này đã tồn tại trên hệ thống. Vui lòng chọn mã khác."
+
+  - caseId: TC-ACT-06
+    facet: "concurrency_double_submit"
+    description: "Giả lập nhấn nút lưu liên tục 2 lần trong 100ms"
+    action: "double_click"
+    expected:
+      buttonDisabled: true
+      singleRequestSent: true
+      duplicatedCreated: false
+
+  - caseId: TC-SYS-07
+    facet: "network_interruption"
+    description: "Mất kết nối mạng khi đang gửi dữ liệu"
+    action: "simulate_offline"
+    expected:
+      bannerVisible: true
+      formDataPreserved: true
+
+steps:
+  - "Truy cập màn hình tạo mới theo URL hoặc Menu"
+  - "Nhập các trường dữ liệu theo bảng testMatrix"
+  - "Nhấn nút Lưu & Xác nhận"
+  - "Kiểm tra thông báo và trạng thái DOM tương ứng"
+
+expected: Success state is visible or appropriate error message is rendered
+postcondition:
+  - "Clean up test record if created successfully"
+feature: example-slug
+genType: e2e
+route:
+  path: /example
+  auth: guest
+testIds:
+  required:
+    - "fld_record_code"
+    - "fld_record_name"
+    - "btn_save_record"
+
+# Fill when bundle is available (required for `flowgrid cases:gate --strict`).
+traceability:
+  bundleScreen: W-AD-AUTH-001
+  bundleScenarios: []
+  acceptanceRefs: []
+  actionRefs:
+    - btn_save_record