@shanyucoder/flowgrid 0.1.5 → 0.1.8

package/harness/fe/skills/grill-prototype/SKILL.md

@@ -1,41 +1,67 @@
 ---
 name: grill-prototype
-description: /grill-prototype — FE grill gate before /prototype generation.
+description: /grill-prototype — UI checklist grill AFTER /prototype (mock boundary, testIds, copy). gen:dry runs inside /prototype session, not here.
 disable-model-invocation: true
 ---
 
-# /grill-prototype
+# /grill-prototype — UI checklist (post-prototype)
 
-**Owner:** bộ code · optional local ArtifactGraph allowlist check before dry-gen.
+**Owner:** bộ code FE · **When:** After `/prototype` session has run `gen:dry` → `gen` and filled HANDOFF slots — **before** demo, `/test`, or `/wire`.
+
+**Not this skill:** `flowgrid gen:dry` gate — that runs at the **start** of `/prototype` ([team-flow-prototype.mdc](../rules/team-flow-prototype.mdc)). This skill audits the **built** UI against docs IR.
+
+---
 
 ## Target / ID Resolution Rule
 
-- User prompt MAY specify a screen ID, function ID, or slug (e.g. `W-AD-AUTH-001`, `login`).
-- **Read the entire `ir/design.yaml`** on the screen leaf (`…/CMP-*/<NN…>/ir/design.yaml`) before dry-gen. Do not skim keys from a feature bundle. Do **not** use `01-backend-spec.yaml` as FE input.
-- Docs hub is **read-only**. Dry-gen failure (missing design / `codegen.profile`) → STOP; do not patch docs.
-- After dry-gen, HANDOFF `#needs-component` is filled in `/prototype` using the FE shadcn skill when `components.json` exists (primitives via `shadcn add`, `Mo*` composed — see `/prototype`). Surface/module commons must already exist via `/gen-common`.
-- Do NOT demand full surface/module filesystem paths from the user if an ID is given.
+- User prompt MAY specify screen ID, function ID, or slug (e.g. `W-AD-AUTH-001`, `login`).
+- **Read the entire `ir/design.yaml`** on the screen leaf (`…/CMP-*/<NN…>/ir/design.yaml`). Do **not** use `01-backend-spec.yaml` as FE input.
+- Docs hub is **read-only**. Do not patch `*.bundle.yaml` or `ir/*`.
+- Compare route + rendered UI to `ir/design.yaml` (actions, validation copy, states, testIds).
+- Shared UI from **FE base** + `registries/design.registry.json` (`registry:sync`) — not `/gen-common` (deprecated).
+- Do NOT demand full filesystem paths if an ID is given.
+
+---
+
+## Rule: Checklist (mandatory dimensions)
+
+Work through in order; fix **only** in FE repo when issue is clear. Otherwise list open issues (Vietnamese) for `/test` or a new `/prototype` session.
+
+1. **Spec parity:** happy path, validation messages (VI), loading / empty / error states.
+2. **Mock boundary:** no real backend; mocks match `apiRef` / contract shape; pagination ≥2 pages when spec lists.
+3. **Registry / shell:** DataListPage or profile shell reuse where IR expects; composables (`#composable:`) used for shared list/filter logic when registered.
+4. **testIds:** `E2E-TESTIDS` / testcase `testIds.required` ⊆ DOM (`data-testid`).
+5. **Auth bypass:** documented for local prototype (if applicable).
+6. **Layout / copy:** Vietnamese UI copy; icons/labels vs common UX rules (`flowgrid-ux-common.mdc`).
 
-```text
-if local ArtifactGraph available: check the FE repo's allowlist for genDry
-else: npm run codegen:dry -- --id …
-```
+**[STRICTLY FORBIDDEN]** Run Playwright/Vitest bulk suites — audit + spot-check only.
+
+**Extracts (when present):** verify-gate, common-ui-spec, portal-test-readiness.
+
+---
 
 ## Docs Root Resolution
 
-1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
-   pointer for locating `ir/design.yaml`.
-2. If `FLOWGRID_DOCS_ROOT` is **not** set, fall back to Platform DNA
-   configuration (`platform-dna`) to resolve the docs hub path.
-   Platform DNA discovery is slower and more error-prone, so always prefer
-   an explicit `FLOWGRID_DOCS_ROOT` when available.
+1. `FLOWGRID_DOCS_ROOT` (non-empty) → canonical pointer for `ir/design.yaml`.
+2. Else Platform DNA (`platform-dna`) — slower; prefer explicit env.
+
+Architecture IDs → bộ docs; symbols in other repos → `codegraph-<key>` only.
+
+Optional: local ArtifactGraph allowlist hint — never blocks checklist. Telemetry: `flowgrid-code-optional-integrations.mdc` once per run.
 
-Canonical IR/registries come from `FLOWGRID_DOCS_ROOT`; ArtifactGraph does
-not follow that pointer. Architecture IDs → bộ docs (`FLOWGRID_DOCS_ROOT`); symbols
-in other repos → `codegraph-<key>` only.
+Do not execute flowgrid docs scripts (`split`, `render`) from the FE repo.
+
+---
+
+## Handoff
+
+- **Pass:** route, spec + testcase paths, testIds status, `#wire-only` list → `/test` or team demo.
+- **Fail / gaps:** open issues (VI) → fix in `/prototype` scope or `/update-spec` on docs hub if SSOT wrong.
+
+---
 
-Missing ArtifactGraph never blocks the grill. Complete the deterministic dry
-generation fallback first, then follow
-`.cursor/rules/flowgrid-code-optional-integrations.mdc` for once-per-run telemetry.
+## Verification Checklist
 
-Do not execute flowgrid docs scripts from the FE repo.
+- [ ] `/prototype` already produced scaffold + mock boundary for this `W-*`.
+- [ ] Full `ir/design.yaml` read; checklist dimensions addressed or deferred with reason.
+- [ ] No docs-hub YAML edits; no Playwright/Vitest regression run.

package/harness/fe/skills/grill-test/SKILL.md

@@ -1,32 +1,90 @@
 ---
 name: grill-test
-description: /grill-test — FE grill gate before Playwright generation.
+description: /grill-test — E2E traceability audit after /test (TC YAML ↔ PO ↔ Playwright). No bulk regen.
 disable-model-invocation: true
 ---
 
-# /grill-test
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+> **[MANDATORY]** Run only after `/test` — Playwright specs exist and scoped `test:e2e` is green (or failures are documented with root cause).
 
-**Owner:** bộ test (`--type=fe`)
+# /grill-test — E2E Traceability Audit (FE repo)
 
-After `/test`. Plan YAML remains on the tests hub (`/grill-testcase`).
+**Owner:** bộ test (`--type=fe`). Plan SSOT stays on tests-docs hub — grill plans with `/grill-testcase`, not here.
 
-Route Functions/W-* evidence through bộ docs, plans/docs through
-`FLOWGRID_TESTS_DOC` / `FLOWGRID_DOCS_ROOT`, and repo-X symbols through its
-Platform DNA-wired `codegraph-<repo-key>` server. Never substitute the current
-repo index for another checkout or initialize a workspace-parent graph.
+**Mindset:** Audit only — **no** fixing production code like `/test`, **no** bulk `testcase:gen` regen.
 
-## Accelerators (optional)
+---
+
+## Rule: Load Policy
+
+| Read | Do not |
+| --- | --- |
+| Matching `TC-*.yaml` on tests-docs hub (`FLOWGRID_TESTS_DOC`) | Invent scenarios missing from TC |
+| Screen `*.bundle.yaml` + `ir/design.yaml` (`testIds`, actions) | Use generated `ir/generated/*.md` as SSOT |
+| Page Objects + `*.spec.ts` under **e2e-root** | Backend / unit tests |
+
+---
+
+## Rule: Audit Interlock (gates)
+
+From FE repo cwd (flags: `docs/references/audit-commands.md` on docs hub):
+
+1. **[MANDATORY]** `flowgrid audit e2e --id <TC-id> --tests-docs "$FLOWGRID_TESTS_DOC" --e2e-root <e2eRoot>`  
+   (or `--screen W-*` / path to `TC-*.yaml` when batching).
+2. Consume JSON: orphan specs, missing TC rows, `testIds` gaps — **patch list only**, do not rewrite specs inline without member confirm.
+
+Re-run `audit e2e` after `/test` fixes before sign-off.
+
+---
+
+## Rule: Traceability Matrix (4-way)
+
+Build a gap table for the scoped TC(s):
+
+| Column | Source |
+| --- | --- |
+| Requirement / AC | bundle `userStories` / `acceptanceCriteria` |
+| Plan | `TC-*.yaml` `steps[]`, `testMatrix`, `refs` |
+| Automation | PO methods + `*.spec.ts` |
+| UI hooks | `testIds.required` in `ir/design.yaml` ↔ PO ↔ DOM |
+
+- **[MANDATORY]** Every `testMatrix` facet claimed in TC must appear in spec or be deferred with `QA-*` on docs hub.
+- **[MANDATORY]** Required `#e2e:*` semantic tags on bundle/TC must be exercised in spec (or flagged gap).
+- **[STRICTLY FORBIDDEN]** Raw `getByTestId` / CSS / xpath in `*.spec.ts` — PO layer only.
+
+---
+
+## Rule: Branching (no scope creep)
+
+| Gap type | Handoff |
+| --- | --- |
+| Missing `*.spec.ts`, PO, or `testId` on UI | `/test` |
+| TC plan thin / wrong business logic vs bundle | tests-hub `/grill-testcase` or docs `/update-spec` (paste-ready prompt) |
+| Post-wire real API vs plan (status, matrix facet) | tests-hub `/grill-testcase` · extract `wire-test-handoff.md` |
+| Spec/design missing acceptance | docs `/update-spec` or `/grill-bqa` |
+| Full convergence (e2e + fe-be + scenario) after wire | `/grill-wire` (audit chain; not a substitute for fixing specs here) |
+
+- **[STRICTLY FORBIDDEN]** Do not run `/wire`, `/api`, or Vitest from this skill.
+
+---
+
+## Rule: Workload Threshold (Law 2)
+
+- **≤5 gaps:** list in chat + optional AskQuestion (≥3 options) for defer vs fix now.
+- **≥10 gaps:** **hard stop** — implementation plan by phase (3–5 items/phase); member runs `/test` per phase.
+
+---
+
+## Verification Checklist
 
-```text
-if local ArtifactGraph available: recommend/check testcase gen (this repo)
-else: local deterministic search, then flowgrid testcase:gen:dry …
-```
+- [ ] Scoped `test:e2e` green or documented root cause.
+- [ ] `flowgrid audit e2e` run with `--tests-docs` + `--e2e-root`; gaps addressed or handed off.
+- [ ] Matrix TC ↔ bundle ↔ PO ↔ spec file complete for scope.
+- [ ] `#e2e:*` and `testIds.required` checked.
+- [ ] No bulk regen; no backend changes.
+- [ ] Pass → recommend lifecycle promote (`test` → `wire` per team policy); after real API wire run `/grill-wire` for fe-be/scenario gates.
 
-ArtifactGraph never follows `FLOWGRID_DOCS_ROOT` / `FLOWGRID_TESTS_DOC`; plan
-YAML and docs evidence flow only through those bộ test pointers.
+## Related
 
-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.
+- Before: `/test` · Plan grill: `/grill-testcase` · Workflow: `docs/workflows/test.md`

package/harness/fe/skills/grill-wire/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: grill-wire
+description: /grill-wire — post-wire convergence audits (e2e, fe-be, scenario) and handoff to update-spec / grill-testcase.
+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 `.cursor/extracts/wire-audit-loop.md` and hub `docs/workflows/wire.md#wire-gates`.
+
+# /grill-wire — Wire Convergence Audit (FE repo)
+
+**Owner:** bộ code (`--type=fe`)
+
+**Mindset:** Audit and gap routing only — **no** bulk `/wire` implementation, **no** `/test` fixes inline unless member explicitly runs `/test` in same session.
+
+Use **after** `/wire` (or when validating wire scope before sign-off): real API connected, production mocks removed, auth restored.
+
+---
+
+## Rule: Load Policy
+
+| Read | Do not |
+| --- | --- |
+| `FLOWGRID_DOCS_ROOT` → scoped `*.bundle.yaml`, `ir/design.yaml` | Edit bundle or `01` from FE repo |
+| `FLOWGRID_TESTS_DOC` → `cases/**/TC-*.yaml` for `--screen W-*` | Invent TC steps |
+| Playwright under **e2e-root** | Use `ir/generated/*.md` as SSOT |
+
+---
+
+## Rule: Audit Interlock (mandatory chain)
+
+From FE repo (flags: `docs/references/audit-commands.md` on docs hub):
+
+1. **[MANDATORY]** `flowgrid audit e2e --e2e-root <e2eRoot> --tests-docs "$FLOWGRID_TESTS_DOC" --screen <W-*>`  
+   (or `--id TC-*` / paths to `TC-*.yaml`).
+2. **[MANDATORY]** When bundle has `apiRef` / portal BE:  
+   `flowgrid audit fe-be <bundle.yaml> [--backend-spec …/01-backend-spec.yaml]`.
+3. **[MANDATORY]** When any `SC-*` references this screen:  
+   `flowgrid audit scenario <SC.yaml> --tests-docs "$FLOWGRID_TESTS_DOC"`.
+
+Parse JSON; list every `critical` / `warning` with code and suggested handoff.
+
+Re-run full chain after downstream lanes fix gaps.
+
+---
+
+## Rule: Branching (loop back)
+
+| Gap type | Handoff |
+| --- | --- |
+| `missingInPlaywright`, PO, `testIds`, post-wire assertion | `/test` → `/grill-test` |
+| Plan vs real API (status, validation, matrix facet) | tests-hub `/grill-testcase` — output paste-ready `/docs-hub` prompt if spec hole |
+| UX/spec/AC wrong vs observed behaviour | docs-hub `/update-spec` (paste-ready prompt per `grill-testcase` rule) |
+| `FEBE_*`, wrong endpoint/field on `01` | docs-hub `/api-update` → BE `/audit-api` → member re-runs `/wire` |
+| `SC_SCREEN_NO_TC` | tests-hub `/testcase` or `/scenario` |
+| Defer only | `qa/open` + team policy |
+
+- **[STRICTLY FORBIDDEN]** Close `#update:*` / `#wire-only` here — only `/wire` after spec merge confirms.
+- **[STRICTLY FORBIDDEN]** Run `/api` codegen or full product regression from this skill.
+
+---
+
+## Rule: Workload Threshold (Law 2)
+
+- **≤5 gaps:** table in chat + AskQuestion (≥3 options) defer vs fix lane.
+- **≥10 gaps:** hard stop — phased plan (spec batch → test batch → wire re-audit).
+
+---
+
+## Verification Checklist
+
+- [ ] Scoped post-wire `test:e2e` green or documented root cause.
+- [ ] `audit e2e` + `audit fe-be` (+ `audit scenario` if SC) run with correct env pointers.
+- [ ] Every gap has owner lane or `QA-*` defer.
+- [ ] No docs-hub writes from FE repo.
+- [ ] Pass → wire sign-off line per `wire.md#wire-signoff`; recommend `/grill-test` if e2e audit was batch-only.
+
+## Related
+
+- Implement: `/wire` · Matrix detail: `/grill-test` · Workflow: `docs/workflows/wire.md`

package/harness/fe/skills/prototype/SKILL.md

@@ -12,7 +12,8 @@ disable-model-invocation: true
 
 - User prompt MAY specify a screen ID, function ID, or slug (e.g. `W-AD-AUTH-001`, `login`).
 - Agent MUST use `--id` or resolve `surfaces/<surface>/CMP-*/<NN…>/ir/design.yaml` via `FLOWGRID_DOCS_ROOT` or `flowgrid_docs_route` (same leaf as the bundle; API trio is sibling `api/<seq>/`, not this file).
-- Prerequisite: `/gen-common` when `surfaces/<surface>/common` (or `CMP-*/common`) exists — generate shared molecules/shells **before** this skill.
+- Shared UI (list shell, chips, delete flow, …) is **already in the FE base** — do not run `/gen-common` (deprecated).
+- `surfaces/…/common/` on the docs hub is **Markdown only** (`processes/FLOW-*.md`, `patterns/`) — read for context; never codegen from `common/yaml`.
 - Do NOT demand full filesystem paths from the user if an ID is given.
 
 ```text
@@ -60,7 +61,7 @@ flowgrid gen --adapter=dotnet-line -- --spec ir/design.yaml
 flowgrid registry --adapter=dotnet-line
 ```
 
-You MUST run `/gen-common` for this surface (then `--module=CMP-…` if the module has `common/yaml`) when those trees exist, then run the codegen script (`npm run codegen` or `flowgrid gen`) FIRST to generate the skeleton from **design IR**, before filling gaps **in the FE repo only**.
+Run the codegen script (`npm run codegen` or `flowgrid gen`) FIRST to generate the skeleton from **design IR**, before filling gaps **in the FE repo only**. New domain `Mo*` → compose from base + shadcn; registry gaps → [custom-base](../../../docs/workflows/custom-base.md) (`build-template-code`), not docs-hub common YAML.
 
 ## Shadcn/ui skill (FE repo only)
 

package/harness/fe/skills/wire/SKILL.md

@@ -8,6 +8,8 @@ disable-model-invocation: true
 
 **Owner:** bộ code (`--type=fe`)
 
+> **[MANDATORY]** Read `.cursor/extracts/wire-phase.md`, `.cursor/extracts/wire-audit-loop.md`, and hub `docs/workflows/wire.md` (wire cycle) before wiring.
+
 Use after `/prototype` when tags/handoff mark `#wire-only` or real API integration is required.
 Keep generation through bộ code adapters; resolve canonical docs evidence
 through `FLOWGRID_DOCS_ROOT` and do not invent sibling layout.
@@ -55,6 +57,9 @@ Optional: pass explicit `cases/**/TC-*.yaml` paths instead of `--tests-docs`.
 
 - Parse JSON: `missingInPlaywright`, `matrixRowsUncovered`, `orphanTestCases`, `orphanSpecs`, `gaps[]`.
 - **[MANDATORY]** Fix or defer every `critical` / `warning` gap before marking wire done; log deferrals in `qa/open` if team policy allows.
-- **[RECOMMENDED]** `flowgrid audit fe-be <bundle.yaml>` when integration exposed contract drift.
+- **[MANDATORY]** Portal leaf with `apiRef`: `flowgrid audit fe-be <bundle.yaml>`.
+- **[MANDATORY]** When `SC-*` covers screen: `flowgrid audit scenario <SC.yaml> --tests-docs "$FLOWGRID_TESTS_DOC"`.
+
+Gap routing (spec / plan / code): see `.cursor/extracts/wire-audit-loop.md`. Audit-only pass → `/grill-wire`.
 
-Ref: `docs/references/skills/wire.md` · engine `engines/spec/lib/audit-e2e-coverage.mjs`.
+Ref: `docs/references/skills/wire.md` · `/grill-wire` · engine `engines/spec/lib/audit-e2e-coverage.mjs`.

package/harness/shared/AGENTS.md

@@ -119,7 +119,7 @@ The agent has **NO AUTHORITY** to unilaterally decide what constitutes "Common".
 
 The agent acts strictly as a clerk, permitted to register or update DSL/Common in only **3** passive cases:
 
-1. User explicitly invokes `/common` or `/common-spec`.
+1. User explicitly invokes `/common` (Markdown patterns only — not `/common-spec`, deprecated).
 2. User explicitly invokes `/docs-mark` to record rules or tags.
 3. User explicitly confirms a `/grill` proposal.
 
@@ -147,7 +147,7 @@ In standard `/spec` runs, the sole duty is to **consume existing common definiti
 - **Remember:** Only use `artifactgraph_remember` AFTER member confirms options during Grill.
 - **Handoff:** Use `artifactgraph_allowlist_check` + `artifactgraph_recommend_command` to retrieve permitted commands; hand off to corresponding kit/script. Never run `artifactgraph_gen`.
 - **Cloud Prompt:** Send `cloudPromptSlice` only for unresolved work items.
-- **Setup:** If indices are missing, direct member to run `artifactgraph init` with the appropriate `--type=`.
+- **Setup:** If indices are missing, direct member to run `flowgrid init` with the appropriate project type.
 
 ---
 
@@ -158,7 +158,7 @@ In standard `/spec` runs, the sole duty is to **consume existing common definiti
   → For every persistent result: {{FLOWGRID_WRITE_TOOL}} IMMEDIATELY (No RAM)
   → Data source: User | ArtifactGraph only; tag gaps with #missing_info
   → Grill: 4-step protocol + STOP for Confirmation before writing SSOT
-  → Common/DSL: only via /common|/common-spec|/docs-mark|Confirm
+  → Common/DSL: only via /common|/docs-mark|Confirm|custom-base (no common/yaml)
 ```
 
 ## Isolation & Fake Reports Policy

package/harness/shared/SSOT_AGENT_PROTOCOL.md

@@ -121,7 +121,7 @@ The agent has **NO AUTHORITY** to unilaterally decide what constitutes "Common".
 
 The agent acts strictly as a clerk, permitted to register or update DSL/Common in only **3** passive cases:
 
-1. User explicitly invokes `/common` or `/common-spec`.
+1. User explicitly invokes `/common` (Markdown patterns — `/common-spec` deprecated).
 2. User explicitly invokes `/docs-mark` to record rules or tags.
 3. User explicitly confirms a `/grill` proposal.
 
@@ -149,7 +149,7 @@ In standard `/spec` runs, the sole duty is to **consume existing common definiti
 - **Remember:** Only use `artifactgraph_remember` AFTER member confirms options during Grill.
 - **Handoff:** Use `artifactgraph_allowlist_check` + `artifactgraph_recommend_command` to retrieve permitted commands; hand off to corresponding kit/script. Never run `artifactgraph_gen`.
 - **Cloud Prompt:** Send `cloudPromptSlice` only for unresolved work items.
-- **Setup:** If indices are missing, direct member to run `artifactgraph init` with the appropriate `--type=`.
+- **Setup:** If indices are missing, direct member to run `flowgrid init` with the appropriate project type.
 
 ---
 
@@ -161,7 +161,7 @@ In standard `/spec` runs, the sole duty is to **consume existing common definiti
 3) Write immediately upon producing durable results (No RAM) → Law 4
 4) Sourced exclusively from User | ArtifactGraph; tag gaps   → Law 5
 5) Grill: 4-step protocol + STOP for Confirmation           → Law 6
-6) Common/DSL: only via /common|/common-spec|/docs-mark|Confirm → Law 7
+6) Common/DSL: only via /common|/docs-mark|Confirm|custom-base — no common/yaml → Law 7
 ```
 
 Host overlay Antigravity: see `AGENTS.md` (synchronized Laws 1–8).

package/harness/tests/extracts/grill-api-hook.md

@@ -0,0 +1,69 @@
+# Grill — API hook (`genType: api-e2e`)
+
+Hub SSOT: `docs/workflows/test.md#grill-api-hook` · artifact: `docs/artifacts/tests-docs.md#api-hook-tc`.
+
+## Prerequisites (docs hub)
+
+- `api/<seq>/01-backend-spec.yaml` — `/api-spec`, `/grill-api-spec`, `approval` per policy
+- Partner/webhook: `feature.source.base: none` — **no** portal bundle as contract SSOT
+- Portal + hook: separate docs leaves — UI `W-*` + API `API-*`
+
+## Plan (tests-docs) — `/test-api`
+
+- `schemaVersion: 2`, `genType: api-e2e`, `refs.screen: API-*`
+- `api.baseUrlEnv` + `api.baseURL` fallback
+- `apiSteps[]`: method, path, expectStatus, body/headers, expectJson
+- Human `steps[]` + `testMatrix` (auth 401/403, 404, 422, 409 as applicable)
+- Template: `TC.example-api.yaml`
+- Mirror path aligned with API leaf on docs surface
+
+## Grill plan (same hub rules)
+
+```text
+flowgrid audit testcase <TC-api.yaml> --bundle <bundle.yaml>   # when portal-linked
+flowgrid cases:check
+/grill-testcase  # include api-e2e TC in gate batch
+cases:gate --strict --docs-root $FLOWGRID_DOCS_ROOT
+cases:render
+```
+
+Contract drift → docs `/api-update` — not patch `01` from tests hub.
+
+## Playwright `request` (FlowGrid gen)
+
+```text
+flowgrid testcase:gen:api --testcase cases/…/TC-….yaml
+# output: <e2eRoot>/tests/api-e2e/<module>/<TC-id>.api.spec.ts
+```
+
+Env: `FLOWGRID_API_TEST_BASE_URL` or custom `api.baseUrlEnv`. Secrets via CI env only.
+
+Run: Playwright project including `tests/api-e2e/**` (FE or BE repo per `e2eRoot`).
+
+**After gen:** fix HMAC/signing in spec or TC headers — no committed secrets.
+
+## Newman / Postman (optional, outside gen)
+
+Use when partner delivers collection, complex pre-request scripts, or contract sign-off via Postman.
+
+| Item | Practice |
+|------|----------|
+| Location | `integrations/postman/` or team folder — **not** SSOT replacing `TC-*.yaml` |
+| TC link | Tag `contract-postman` on YAML; note collection path in `description` |
+| CI | `newman run collection.json -e env.json` — separate job from Playwright |
+| SSOT | Still author `api-e2e` TC for gate/trace; Newman = execution mirror or partner replay |
+
+Do **not** expect `testcase:gen:api` to emit Newman today.
+
+## Hybrid SC (UI + hook)
+
+Two TC files, same `refs.scenario`:
+
+1. `genType: e2e` — creates data in UI (store `orderId` in env/fixture)
+2. `genType: api-e2e` — partner GET export with `${orderId}` in path
+
+Grill: `audit scenario` + both TC types in gate.
+
+## BE unit/integration
+
+Webhook signature, idempotency, DLQ → BE repo tests (pytest/Jest) — **supplement** not replace tests-docs plan.

package/harness/tests/extracts/grill-scenario-flow.md

@@ -0,0 +1,39 @@
+# Grill — scenario flow dài (`SC-*` + nhiều màn)
+
+Hub SSOT: `docs/workflows/test.md#grill-scenario-flow`.
+
+## Scope
+
+- Docs **`FLOW-*.md`** exists (Phase 0 / business-process) — **no SC without FLOW**
+- Tests: `scenarios/<mirror>/FLOW-<name>/SC-*.yaml` with `screens: [W-*, W-*, …]`
+- **Per screen touched:** at least one `cases/…/TC-*.yaml` OR documented defer (`coverage_deferred` + `QA-*` on docs)
+
+## Author
+
+1. `/scenario` — rich `description`/`story`, all `screens[]` listed
+2. For **each** `W-*` in journey: `/testcase` under that leaf mirror path (`refs.scenario: SC-*`)
+3. Long flow ≠ one giant TC file — **one TC per screen** (or per major step) linked by same `refs.scenario`
+
+## Grill sequence
+
+1. `flowgrid audit scenario scenarios/…/SC-*.yaml --tests-docs $FLOWGRID_TESTS_DOC`
+2. Fix `SC_SCREEN_NO_TC` — add `TC-*.yaml` per screen OR defer with `QA-*` (docs hub)
+3. Per TC: `audit testcase --bundle` for that screen's bundle
+4. `/grill-testcase` scoped to **all TC under scenario** + `cases:gate --strict`
+5. `cases:render` — walkthrough SC folder + each `TC-*.md`
+
+## Cross-flow automation
+
+| Pattern | Plan | Gen / run |
+|---------|------|-----------|
+| Sequential UI | Multiple `TC` same `SC`, `genType: e2e` | Separate specs; CI `dependsOn` or ordered job |
+| UI then API hook | `TC` e2e + `TC` api-e2e same `SC` | `testcase:gen` + `testcase:gen:api`; pass `orderId` via env between jobs |
+| API-only journey | `TC` api-e2e only | `testcase:gen:api` |
+
+## Sign-off
+
+- [ ] `audit scenario` no unresolved `SC_SCREEN_NO_TC` (or accepted QA)
+- [ ] Each screen's TC passed `cases:gate --strict` traceability
+- [ ] SC `screens[]` matches docs FLOW touchpoints (spot vs `FLOW-*.md`)
+
+Handoff thin FLOW → `/docs-hub /business-process` or `/update-spec` — not tests hub.

package/harness/tests/extracts/grill-screen-tc.md

@@ -0,0 +1,40 @@
+# Grill — một màn chức năng (`W-*`)
+
+Hub SSOT: `docs/workflows/test.md#grill-single-screen`.
+
+## Scope
+
+- **One** function leaf on docs: `surfaces/…/<slug>.bundle.yaml`
+- **One** mirror folder: `cases/…/<slug>/TC-*.yaml` (`genType: e2e`)
+- Optional: multiple `TC-*.yaml` per screen (smoke + regression) — **union** `testMatrix` facets per screen at gate
+
+## Grill sequence (tests-docs)
+
+1. Read **entire** `*.bundle.yaml` (not split IR).
+2. `/testcase` or patch existing `TC-*.yaml` — `traceability`, `testMatrix`, `testIds.required`.
+3. `flowgrid cases:check`
+4. `flowgrid audit testcase cases/…/TC-*.yaml --bundle surfaces/…/*.bundle.yaml`
+5. `flowgrid cases:render` — QA reads `TC-*.md` on VitePress **5174**
+6. `/grill-testcase` — consume `cases:gate --strict --docs-root $FLOWGRID_DOCS_ROOT`
+
+## Sign-off checklist (plan)
+
+- [ ] Every `userStories.scenarios` slug in `traceability.bundleScenarios[]` (strict)
+- [ ] Every material `AC-*` in `traceability.acceptanceRefs[]`
+- [ ] Actions with outcomes in `traceability.actionRefs[]`
+- [ ] Facet union on screen: boundary, negative, duplicate 409, double-submit, offline (per policy)
+- [ ] `testIds.required` ⊆ bundle/design `ui.testIds` after split
+- [ ] Gap business → paste `/docs-hub /update-spec` — do not invent AC on tests hub
+
+## Automation (e2e-root, after gate)
+
+```text
+testcase:gen --id TC-*  (or --testcase)
+/test → scoped test:e2e green
+/grill-test → audit e2e --tests-docs --e2e-root
+/grill-wire → audit e2e + fe-be (+ scenario) on FE after wire
+```
+
+Wire loop back to plan: `wire-test-handoff.md`.
+
+**Forbidden:** `/grill-test` before plan gate; edit `TC-*.md` by hand.

package/harness/tests/extracts/testcase-gen-cli.md

@@ -0,0 +1,57 @@
+# testcase:gen / cases:* — CLI (agent)
+
+Run from **code repo** (e2e-root) unless noted. Tests plan lives on `FLOWGRID_TESTS_DOC`.
+
+## Hub-only (tests-docs cwd or any cwd)
+
+| Command | Purpose |
+|---------|---------|
+| `flowgrid cases:check` | JSON Schema v2 on `cases/**/TC-*.yaml` |
+| `flowgrid cases:render` | YAML → `TC-*.md` (QA user case) |
+| `flowgrid cases:coverage` | Spec ↔ plan coverage report |
+| `flowgrid cases:gate [--strict] [--docs-root …]` | Release gate + bundle trace |
+| `flowgrid tests:publish` | Catalog publish (when enabled) |
+
+## UI E2E codegen (`genType: e2e`)
+
+| Command | Notes |
+|---------|--------|
+| `flowgrid testcase:gen --id <W-*\|TC-*\|CMP-*\|SC-*\|smoke>` | Resolve hub index |
+| `flowgrid testcase:gen --testcase cases/…/TC-*.yaml` | Explicit path on hub |
+| `flowgrid testcase:gen --feature <W-*>` | All TC under screen folder |
+| `flowgrid testcase:gen --all` | Every `e2e` TC on hub |
+| `flowgrid testcase:gen:dry` | Adds `--dry-run` |
+| Flags: `--force`, `--tests-docs <path>`, `--dry-run` | |
+
+**Output (typical FE):** `<e2eRoot>/tests/e2e/...` — Page Object + `*.spec.ts`.
+
+**Before gen:** `cases:gate --strict` (team policy) · `portal:gen` testIds on UI.
+
+## API hook codegen (`genType: api-e2e`)
+
+| Command | Notes |
+|---------|--------|
+| `flowgrid testcase:gen:api --testcase cases/…/TC-*.yaml` | Requires `apiSteps[]` |
+| `flowgrid testcase:gen:api --id TC-*` | |
+| `flowgrid testcase:gen:api --all` | All `api-e2e` on hub |
+| `flowgrid testcase:gen:api:dry` | Dry-run |
+
+**Output:** `<e2eRoot>/tests/api-e2e/<module>/<TC-id>.api.spec.ts`
+
+**Env:** `FLOWGRID_API_TEST_BASE_URL` or `api.baseUrlEnv` on TC.
+
+## Audit (cross-repo)
+
+```text
+flowgrid audit testcase <TC.yaml> --bundle <docs/*.bundle.yaml>
+flowgrid audit scenario <SC.yaml> --tests-docs $FLOWGRID_TESTS_DOC
+flowgrid audit e2e --id TC-* --tests-docs … --e2e-root …
+```
+
+## Common mistakes
+
+- `testcase:gen` on `api-e2e` TC → use `testcase:gen:api`
+- SSOT path `testcases/*.yaml` next to code → wrong; hub is `cases/**`
+- Gen before `cases:render` → QA reviews stale MD
+
+Hub scripts after init often: `pnpm cases:render`, `pnpm testcase:gen` (aliases vary).

package/harness/tests/extracts/testcase-plan.md

@@ -0,0 +1,29 @@
+# Testcase plan — agent digest
+
+Full guide: `harness/tests/templates/tpl-testcase-plan.md` · Hub SSOT: `docs/artifacts/tests-docs.md`.
+
+## Write / read
+
+| Ghi | Đọc team |
+|-----|----------|
+| `cases/**/TC-*.yaml` | `flowgrid cases:render` → `TC-*.md` (VitePress **5174**) |
+| Bundle on docs | `FLOWGRID_DOCS_ROOT` — **read entire** `*.bundle.yaml` for `/testcase` |
+
+## Required on TC (v2)
+
+`schemaVersion: 2` · `testMatrix` facets · `steps` · `traceability` · `testIds.required` · `genType: e2e|api-e2e`
+
+## Gates
+
+```text
+flowgrid cases:check
+flowgrid audit testcase <TC> --bundle <bundle>
+flowgrid cases:gate --strict --docs-root $FLOWGRID_DOCS_ROOT
+flowgrid cases:render
+```
+
+## Forbidden
+
+- Edit `TC-*.md` by hand
+- Author TC when bundle stories/AC empty (handoff `/update-spec`)
+- `cases/` path not mirroring `surfaces/…`

package/harness/tests/extracts/tests-verify-gate.md

@@ -0,0 +1,29 @@
+# Tests hub — verify gates
+
+## Plan release (`cases:gate --strict`)
+
+Requires `FLOWGRID_DOCS_ROOT` + `FLOWGRID_TESTS_DOC`.
+
+```text
+flowgrid cases:check
+flowgrid cases:gate --strict --docs-root $FLOWGRID_DOCS_ROOT
+```
+
+Checks: schema v2, audit testcase, bundle `traceability`, per-screen `testMatrix` facet union, optional scenario coverage.
+
+## Per-file spot
+
+```text
+flowgrid audit testcase cases/.../TC-*.yaml --bundle surfaces/.../*.bundle.yaml
+flowgrid audit scenario scenarios/.../SC-*.yaml --tests-docs $FLOWGRID_TESTS_DOC
+```
+
+## After YAML change
+
+Always `flowgrid cases:render` before QA review on site.
+
+## E2E (e2e-root, separate)
+
+`testcase:gen` → `/test` green → `/grill-test` → `flowgrid audit e2e` (policy).
+
+Workflow: `docs/workflows/test.md` · close leaf: `docs/workflows/gates.md` step 3–4, 7–8.