@shanyucoder/flowgrid 0.1.5 → 0.1.9

package/harness/docs/skills/qa-resolve/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: qa-resolve
 extractBundle: docs-hub
-description: EXCLUSIVE /qa-resolve — close one qa/open file. Prompt is QA id + solution. Do not use for full-screen grill or first-time /spec.
+description: EXCLUSIVE /qa-resolve — append answer + close one qa/<id>.yaml. Prompt is QA id + solution. Do not use for full-screen grill or first-time /spec.
 disable-model-invocation: true
 ---
 
@@ -10,14 +10,14 @@ disable-model-invocation: true
 
 # /qa-resolve — Close One Open QA
 
-**When:** Member provides `QA-<page-id>-NNNN` (or `QA-<feature.id>-NNNN`) **along with** an explicit decision/solution.
+**When:** Member provides `HOTEL-LIST_0001` (or legacy `QA-<page-id>-NNNN`) **along with** an explicit decision/solution.
 
 **Not this skill:**
 - Unknown answers needing brainstorming → `/grill-bqa` / `/grill-dev` / `/grill-docs` / `/api-spec`
 - FE delta without an existing QA file → `/update-spec`
 - Portal/BE sync without closing QA files → `/api-update`
 
-**Extract:** `.cursor/extracts/qa-inbox.md`
+**Extract:** `.cursor/extracts/qa-inbox.md` · `qa-team.md`
 
 ---
 
@@ -25,8 +25,8 @@ disable-model-invocation: true
 
 | Read (whole file) | Write | NEVER do |
 |---|---|---|
-| `qa/open/<id>.yaml` | Patch `target.path` only | Read generated `*.md` as SSOT |
-| Target bundle **or** `01-backend-spec.yaml` (entire file) | Delete QA file after patch | Author `openQuestions` |
+| `qa/<id>.yaml` (legacy: `qa/open/<id>.yaml`) | Patch `target.path` only | Read generated `*.md` as SSOT |
+| Target bundle **or** `01-backend-spec.yaml` (entire file) | **Append** `updates[]` — never delete prior lines | Author `openQuestions` |
 | `ir/design.yaml` — ONLY to locate field if `at` is a design pointer | `flowgrid split` after patch | Full-screen rewrite (use `/spec`) |
 
 ---
@@ -41,10 +41,10 @@ disable-model-invocation: true
 
 ## Rule: Resolving the QA File
 
-- **[MANDATORY]** Step 1: Locate `qa/open/<id>.yaml`. If missing, glob `qa/open/QA-*-NNNN.yaml` matching `id:`.
-  - Zero matches → **STOP**, list available `qa/open/` IDs to user.
+- **[MANDATORY]** Step 1: Locate `qa/<id>.yaml`. If missing, glob `qa/*` and legacy `qa/*` matching `id:`.
+  - Zero matches → **STOP**, list available QA ids to user.
   - Multiple matches → **STOP**, prompt user to clarify which file to close.
-- **[MANDATORY]** Step 2: Read `target.path`, `target.at`, `kind`, `skill`, and `question` from the QA file.
+- **[MANDATORY]** Step 2: Read `target.path`, `target.at`, `kind`, `skill`, and latest `question` from `updates[]` (or legacy `question` field).
 
 ---
 
@@ -60,9 +60,10 @@ disable-model-invocation: true
 
 - **[MANDATORY]** Post-patch execution:
   1. Write solution into field at `target.at` (replacing `#missing_info` / empty / placeholder).
-  2. Remove this ID from `#missing_info QA-…`, `#tech-debt:QA-…`, and all tag lists.
-  3. **Delete** `qa/open/<id>.yaml`.
+  2. Remove this ID from `#missing_info QA-…`, `#tech-debt:QA-…`, `#missing_info <id>`, and all tag lists.
+  3. **Same file:** Append `updates[]` entry `kind: answer`, `at` now (`YYYYMMDD HH:mm`), `text` = solution; set `status: closed`.
   4. Run `flowgrid split` / `pnpm docs:split` so `ir/spec.yaml` Q&A removes this ID.
+  5. Remind `flowgrid render` to refresh `qa/index.md`.
 - **[MANDATORY]** Preserve existing error matrices (`onSuccess` / `onCommonError` / `onSpecificError`, `#err:*`) unless solution specifically alters those fields.
 
 ---
@@ -84,8 +85,8 @@ disable-model-invocation: true
 
 ## Verification Checklist
 
-- [ ] Read `qa/open/<id>.yaml`; patched only `target.path` field.
+- [ ] Read `qa/<id>.yaml`; patched only `target.path` field.
 - [ ] Solution sourced strictly from user prompt (or single AskQuestion turn).
-- [ ] QA file deleted; `pendingTechDebt` + `#missing_info` references removed for this ID.
+- [ ] Appended `kind: answer`; `status: closed`; tags removed for this ID.
 - [ ] `flowgrid split` executed; `ir/spec.yaml` Q&A reflects closed status.
 - [ ] Did not author `openQuestions` or `bundle.spec.api`.

package/harness/docs/skills/qa-review/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: qa-review
+description: /qa-review — append review line on qa/<id>.yaml (team).
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Read `.cursor/extracts/qa-team.md` and hub `docs/workflows/qa-team.md`.
+
+# /qa-review — Review QA timeline (team)
+
+**Owner:** docs hub (`--type=Document` or consumer `FLOWGRID_DOCS_ROOT`)
+
+**When:** After `/qa-resolve` appended `kind: answer`; senior checks decision quality and spec patch.
+
+**Not this skill:** First answer + patch (`/qa-resolve`); silent spec edits (`/update-spec` without review note).
+
+---
+
+## Input
+
+- `HOTEL-LIST_0001` (or legacy `QA-<page-id>-NNNN`)
+- Optional: reviewer id + verdict in user prompt
+
+---
+
+## Steps
+
+1. Read **whole** `qa/<id>.yaml` (legacy: `qa/` or same basename under `qa/`).
+2. Read **whole** target `*.bundle.yaml` or `01-backend-spec.yaml` at `target.path`; verify field at `target.at` matches latest `kind: answer` text.
+3. **Append only** to `updates[]` (never edit or delete prior lines):
+   - `at`: now (`YYYYMMDD HH:mm`)
+   - `by`: reviewer
+   - `kind`: `review`
+   - `text`: `approved: …` or `needs-change: …` (substantive notes)
+4. If `needs-change` in text → set `status: open` on **same file** (middle fixes spec + `/qa-resolve` or append another `answer` later).
+5. Remind: `flowgrid render` to refresh `qa/index.md`.
+
+---
+
+## Verification
+
+- [ ] File exists; timeline append-only.
+- [ ] Review notes substantive for `needs-change`.
+- [ ] No invented business beyond comparing answer vs spec.

package/harness/docs/skills/spec/SKILL.md

@@ -7,8 +7,9 @@ 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 `.flowgrid/templates/feature.bundle.yaml` + `.flowgrid/templates/bundle-authoring.md` BEFORE generating any YAML.
+> **[MANDATORY]** Read `.flowgrid/templates/feature.bundle.yaml` + `.flowgrid/templates/bundle-authoring.md` BEFORE generating any YAML. **Do NOT** use `design-spec.yaml` (deprecated).
 > If templates are missing → STOP: *"Template missing. Run `flowgrid init` to generate templates."*
+> **Extract:** `spec-ssot-prep.md`, `spec-prd-lite.md`, `db-audit-wizard.md`, `design-leaf-signoff.md`.
 > Physical interlocks: `AGENTS.md` + `SSOT_AGENT_PROTOCOL.md` (Laws 1–7). Chat-only done = **FAILED**.
 
 # /spec — Function detail (design)
@@ -25,7 +26,7 @@ disable-model-invocation: true
   - **Small Scope (≤5 gaps):** Run `AskQuestion` wizard — **one question at a time**, **≥3 options**: (1) `(Recommended)`, (2) Alternative, (3) `Log as Tech Debt (Pending)`. Show next question only after member answers current one.
   - **Large Scope (≥10 gaps OR multi-screen scope):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into Phases (3–5 questions/fields per phase) to prevent session token overflow.
   - ❌ Never invent, assume, or silently skip missing fields.
-- **[MANDATORY]** If member chooses "Log as Tech Debt" → create `qa/open/QA-<page-id>-NNNN.yaml` + tag `#missing_info QA-…`. Do not block on it.
+- **[MANDATORY]** If member chooses "Log as Tech Debt" → read `.flowgrid/templates/qa-item.yaml` + `qa-authoring.md`; create `qa/<SHORT>_NNNN.yaml` (`schema: flowgrid-qa-item/v1`) + tag `#missing_info <id>`. Do not block on it.
 - **[RECOMMENDED]** Brainstorm business text (context, input, output, screen descriptions) proactively in Vietnamese for Non-tech audience — do not wait to be told.
 
 ---
@@ -44,14 +45,29 @@ disable-model-invocation: true
 
 ---
 
+## Rule: SSOT prep drill (custom-base · adopt · legacy)
+
+Hub: [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) · extract `spec-ssot-prep.md`.
+
+- **[MANDATORY]** Before first leaf on a **custom/maintain** project: confirm **custom-base** (`build-template-code`) or **standard** `registry:sync` — agent must map `#ui:` / `#shell:` from real `design.registry.json`, not invent `#needs-component`.
+- **[MANDATORY]** **Brownfield workspace:** `/adopt` + `audit legacy` on inventory **before** `/legacy /spec` on any `W-*` (see `/legacy` modifier below).
+- **[MANDATORY]** When `adoption-inventory.md` exists at workspace root: read **Section 5 (Common Catalog Candidates)** on every `/spec` and `/legacy /spec` — inherit `CMN-*`; **STRICTLY FORBIDDEN** copy-paste legacy files into new bundles.
+- **Greenfield hub mới (no legacy):** skip `/adopt`; prep = nhánh A/B only.
+
+---
+
 ## Rule: Audit Interlock
 
 - **[MANDATORY]** If bundle file already exists: run `flowgrid audit spec <path-to-bundle.yaml> --type <pageType>` first.
   - `<pageType>` = page type đã xác định ở bước trên (list | create | detail | admin-crud | auth | ...).
   - Script output:
     - `gaps[]` → required fields missing → Agent patches bundle directly.
-    - `confirms[]` → optional / UX (`category: ux`, codes `UX_*`, `CONFIRM_UX_*`) → AskQuestion; `(Recommended)` must match audit option text or `flowgrid-ux-common` checklist proposals.
-    - Summary fields: `uxAffordanceGaps`, `uxAffordanceConfirms`.
+    - `warnings[]` → **quality hints only** (missing `successMetrics`/`nonGoals`, summary placeholders) — fix when info exists; **does not** block split.
+    - `confirms[]` → AskQuestion wizard (one question at a time, ≥3 options):
+      - UX: `category: ux`, `UX_*`, `CONFIRM_UX_*` — `flowgrid-ux-common.mdc`
+      - **DB:** `category: db`, `CONFIRM_DB_*` — `.cursor/extracts/db-audit-wizard.md` (entities, multi-table, `db` vs `01`, `#derived-data`)
+    - `warnings[]` → agent-only hints (metrics, placeholders); DB issues should appear as `CONFIRM_DB_*`, not silent fixes.
+    - Summary fields: `uxAffordanceGaps`, `uxAffordanceConfirms`, `totalWarnings`, `dbTables.dbConfirms`.
   - **Threshold Interlock (Law 2):** If audit script outputs ≥10 gaps + confirms, HALT chat wizard immediately → create an implementation plan / Plan Mode document partitioned into sequential phases.
   - ❌ Do not skip audit and proceed to authoring directly.
   - ❌ Do not run audit without `--type` parameter.
@@ -90,10 +106,10 @@ disable-model-invocation: true
 1. Confirm `CMP-*` exists and `CTR-*` is identified — otherwise stop for lead/owner.
 2. Detect page type from prompt or existing bundle's `codegen.profile`.
 3. Run audit: `flowgrid audit spec <bundle> --type <pageType>` (if bundle exists).
-4. Process audit output: fill `gaps[]` directly; ask member about `confirms[]` via wizard.
+4. Process audit output: fill `gaps[]` directly; **`confirms[]` (UX + DB)** → `AskQuestion` wizard per `db-audit-wizard.md` / `flowgrid-ux-common.mdc`.
 5. **Zone-based multi-turn authoring** (see rule below): chia page thành zones, phân tích từng zone trong turn riêng.
 6. Write/update `*.bundle.yaml` with `specOrigin: requirement`.
-7. Apply **existing** common/DSL extracts (consume only — promote via `/common-spec`).
+7. Apply **DSL/registry** + `flowgrid-ux-common.mdc` (FE base patterns — no `common/yaml` / gen-common).
 8. Run `pnpm docs:split -- <bundle>` → `pnpm docs:render` (design MD only).
 9. Update `.harness/progress.md`.
 10. Handoff → `/testcase` from acceptance criteria.
@@ -111,7 +127,7 @@ disable-model-invocation: true
 Each zone turn — **in order**:
 
 1. Announce zone name (e.g. `Zone CONTENT: toolbar + table`).
-2. **DSL / registry pass:** Match controls to `design.registry.json` (when present), common catalog, `#shell:`, `#pattern:`, `#ui:`, `#widget:`. Write matched structure into `*.bundle.yaml` for this zone.
+2. **DSL / registry pass:** Match controls to **`registries/design.registry.json` on the FE checkout** (`flowgrid registry:sync`: `#ui`, Mo*, `#composable: use*`, helpers). Use `#shell:`, `#pattern:`, `#ui:`, `#widget:` — not authored on docs hub. Write matched structure into `*.bundle.yaml` for this zone.
 3. **Unmapped structure:** Shadcn primitive → `#ui: <Primitive>`. ≥2 domain structural blocks → `#needs-component: MoBlockName`. Unknown widget → `#needs-ui:` (never invent primitive names). See **Common Pattern Resolution** below.
 4. **Affordance gaps** (still unmapped or thin spec): apply **`flowgrid-ux-common.mdc`** + `.cursor/extracts/ux-common-patterns.md` — only **Recognize / Propose** checklist items that apply; use the rule’s proposal output format. No open-ended UX brainstorming.
 5. **Member decisions:** `confirms[]` from audit + any checklist-derived proposals → `AskQuestion` wizard — one question at a time, ≥3 options: `(Recommended)` = top structured proposal from steps 3–4, Alternative, `Log as Tech Debt (Pending)` (Law 2).
@@ -124,8 +140,24 @@ Each zone turn — **in order**:
 
 ## Rule: Content Requirements per Section
 
+### Rule: Data model (read Phase 0 ERD, write screen detail)
+
+- **[MANDATORY]** Before authoring `db:` on any control: walk LCA per `common-scope.md` and **read** `common/db-erd.md` if present. If entity/table is new and ERD missing → **handoff** `/db-erd` (Phase 0), do not invent schema names silently.
+- **[MANDATORY]** Fill `spec.entities` / `spec.relationships` with the **subset** of ER entities this screen reads/writes (prose + names aligned with ERD).
+- **[MANDATORY]** Persisted fields: on `design.sections[]` items (and list columns when stored): `bind.field` + `db.schema` + `db.field`; `enumMapping` when UI enum maps DB codes.
+- **[MANDATORY]** List columns: `key` consistent with `bind.field`; computed-only columns → document `#derived-data` (see `common/data-model/derived-data.md`), no fake `db`.
+- **[STRICTLY FORBIDDEN]** Empty `entities: []` while form/list has multiple persisted `db.field` without QA defer.
+- **Authoring detail:** [bundle-authoring.md § Data model](../../../templates/shared/bundle-authoring.md#data-model--phase-0-erd-vs-screen-detail) · [tpl-screen-data-model.md](../../../templates/shared/tpl-screen-data-model.md) (multi-table).
+- **Sau split:** `ir/generated/data-model.md` cho review. **Audit:** `CONFIRM_DB_*` → member wizard; sau chốt → re-audit. BE SSOT: `01` khớp `db` (drift → `/api-update`).
+
+### Rule: Summary extensions (PRD lite)
+- **[MANDATORY]** `summary` bullets: business_goals, stakeholders, user_journey, context (input/output), optional solution.
+- **[RECOMMENDED]** When PO/BA có thông tin: fill `successMetrics` and `nonGoals` (multiline `|` bullets) — product-level metrics còn ở `overview/`.
+- **[MANDATORY]** Replace template `[placeholder]` brackets in `summary` / metrics / non-goals before handoff grill.
+
 ### Rule: User Stories (`userStories`)
 - **[MANDATORY]** Generate complete `primary` (asA, iWant, soThat), `contextAndHandoff`, `scenarios` (5 core + **6th “Affordances UX”** when delete/filter/breadcrumb/disabled/import apply), `acceptanceCriteria` (include UX AC lines from template when applicable).
+- **[MANDATORY]** **Profile trim:** do not keep all 6 template scenarios on every page — drop form/background scenarios when profile has no `ui.form` / no async; keep Affordances UX only when audit UX or delete/filter/breadcrumb applies.
 - **[MANDATORY]** After resolving audit `UX_*` gaps or `CONFIRM_UX_*` answers: mirror behavior in `userStories` (use `suggestedStoryPatch` from audit JSON when present).
 - **[MANDATORY]** `contextAndHandoff.screenAccess` MUST be one of: `directRoute` | `sidebarMenu` | `contextualAction`.
 - **[MANDATORY]** 5 scenarios: (1) Initial data load, (2) Input entry & Form validation errors, (3) Successful submission, (4) Exception handling / UI error states, (5) Background operations (if applicable). All descriptive texts generated for user consumption MUST be in clear Vietnamese.
@@ -183,13 +215,13 @@ Each zone turn — **in order**:
 
 ## Rule: Common Pattern Resolution (DSL consume)
 
-- **[MANDATORY]** Before authoring each zone: scan upward `common/yaml/` (function → module → cluster → surface → global); read `templates/shared/patterns/*.pattern.yaml`; match `design.registry.json` when the FE checkout pointer exists.
+- **[MANDATORY]** Before authoring each zone: read LCA `common/patterns/*.md` when present (skill `/common`); read `templates/shared/patterns/*.pattern.yaml`; match `design.registry.json` on the FE checkout when the pointer exists.
 - **[MANDATORY]** Tag from structural cues only (never invented business fields):
   - `>8 columns` → `#split-hook:columns`; `>3 filters` → `#split-hook:filters`; export → `#split-hook:export`; form >6 fields → `#split-hook:form-sections`
   - `≥2 domain structural blocks` → `#needs-component: MoBlockName` (NOT shadcn primitives)
   - Delete → `#pattern: delete-flow`; list/table → `#pattern: CRUD`; confirm/overwrite → `common-confirm-dialog`
 - **[MANDATORY]** Inject resolved patterns into `design.patterns[]` and zone `items[]` with `#ui:` / `#widget:` as applicable.
-- **[STRICTLY FORBIDDEN]** Tag shadcn primitives as `#needs-component`. Duplicate full common IR into the screen bundle when DSL already covers the widget.
+- **[STRICTLY FORBIDDEN]** Tag shadcn primitives as `#needs-component`. Duplicate CMN YAML/IR into the screen bundle (common YAML path is deprecated).
 
 ---
 
@@ -236,5 +268,6 @@ Each zone turn — **in order**:
 - [ ] UX gap questions used checklist-backed `(Recommended)` options (`flowgrid-ux-common.mdc`), not open brainstorming.
 - [ ] `userStories` scenarios/AC reflect UX affordances patched in `design` (incl. audit `suggestedStoryPatch`).
 - [ ] YAML strings with `:` or `[]` are double-quoted. No `.md` written by hand.
-- [ ] `pnpm docs:split` + `pnpm docs:render` run with zero errors; rendered `spec.md` verified clean of raw YAML dumps.
+- [ ] `successMetrics` / `nonGoals` filled or consciously omitted (not left as template brackets).
+- [ ] `pnpm docs:split` + `pnpm docs:render` run with zero errors; `ir/generated/spec.md` has TOC + overview sections.
 - [ ] Handoff → `/testcase` created.

package/harness/docs/skills/update-spec/SKILL.md

@@ -27,7 +27,8 @@ Doc hub: `platform/toolchain/UPDATE-SPEC-FLOW.md` · `platform/toolchain/FEATURE
 ## Rule: Scope Boundaries
 
 - **[MANDATORY]** Scope: patch bundle (delta only); emit `#update:*` tags; bump `specRevision`; run `flowgrid split/check`.
-- **[STRICTLY FORBIDDEN]** Full rewrite → `/spec`. Close `qa/open` item → `/qa-resolve`. Legacy re-mine → `/update-spec-legacy`. Production code → NOT this skill.
+- **[STRICTLY FORBIDDEN]** Full rewrite → `/spec`. Close `qa` item → `/qa-resolve`. Production code → NOT this skill.
+- **[MANDATORY]** Legacy re-mine / trace lại từ code cũ: dùng **`/legacy /spec`** (adopt lại) hoặc **`/update-spec`** với delta `legacy` / `legacyEvidence` + `#update:*` — **không** skill riêng.
 
 ---
 
@@ -36,7 +37,7 @@ Doc hub: `platform/toolchain/UPDATE-SPEC-FLOW.md` · `platform/toolchain/FEATURE
 - **[MANDATORY]** Gaps or ambiguity regarding delta scope, evaluate total gap volume:
   - **Small Scope (≤5 questions):** Trigger `AskQuestion` wizard — one question at a time, **≥3 options**: (1) `(Recommended)`, (2) `Other`, (3) `Log as Tech Debt (Pending)`.
   - **Large Scope (≥10 gaps):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 gaps per phase) with disk offloading at boundaries.
-  - ✅ If "Log as Tech Debt" is selected → create `qa/open/` entry; do not invent business data.
+  - ✅ If "Log as Tech Debt" is selected → create `qa/` entry; do not invent business data.
   - ❌ Never invent delta scope or novel business fields without explicit user confirmation.
 - Path SSOT: `surfaces/<surface>/CMP-*/<slug>/` — NO `modules/` segment.
 
@@ -45,6 +46,7 @@ Doc hub: `platform/toolchain/UPDATE-SPEC-FLOW.md` · `platform/toolchain/FEATURE
 ## Rule: Patch Guardrails
 
 - **[MANDATORY]** Patch minimal YAML sections in **bundle** only (not `ir/*`).
+- **[MANDATORY]** When the delta touches scope or acceptance: update `summary`, `successMetrics`, or `nonGoals` if PO changed goals/out-of-scope; sync `userStories` / AC.
 - **[MANDATORY]** When the delta touches `design.actions`, `design.sections`, or `spec.ui` (list/form/detail, filters, row actions): run the **UX ↔ userStories** checklist in `templates/shared/bundle-authoring.md` — sync `userStories.scenarios` / `acceptanceCriteria` prose when behavior or affordances change (do not leave business story stale).
 - **[MANDATORY]** Before split/merge: run `flowgrid audit spec <bundle.yaml> --type <pageType>` and resolve or explicitly defer `UX_*` / gap codes; do not hand off FE/tests with a fresh structural delta and no re-audit.
 - **[MANDATORY]** Preserve error matrices: when patching actions/API endpoints, ensure `onSuccess`, `onCommonError`, `onSpecificError` + `#err:*` tags are preserved and updated accordingly.
@@ -69,6 +71,7 @@ Doc hub: `platform/toolchain/UPDATE-SPEC-FLOW.md` · `platform/toolchain/FEATURE
 8. `flowgrid_docs_bundle_check` / `flowgrid split --check -- <bundle>` (fallback: `pnpm docs:check`).
 9. User runs `docs_render` / `flowgrid render` (fallback: `pnpm docs:render`).
 10. Follow-up per patch type: handoff FE `/prototype` or `/grill-dev` / `/grill-bqa`; if API contract changed → `/api-update` before `openapi:gen`.
+11. When delta originated from wire/`audit fe-be` on FE: read `.cursor/extracts/wire-spec-feedback.md`; after merge handoff tests-hub `/grill-testcase` then FE `/wire` or `/grill-wire`.
 
 ---
 

package/harness/fe/extracts/wire-audit-loop.md

@@ -0,0 +1,72 @@
+# Wire — audit loop & handoff (FE repo)
+
+Hub: `docs/workflows/wire.md#wire-gates` · Implement: `/wire` · Verify-only: `/grill-wire`.
+
+## Preconditions (do not skip)
+
+```bash
+flowgrid doctor
+flowgrid cases:gate --strict --docs-root "$FLOWGRID_DOCS_ROOT"   # when team policy
+# Pre-wire: scoped test:e2e green (mocks) — see tests-hub plan lifecycle
+```
+
+Env: `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`, e2e-root (`tests/e2e` or config `frontend.e2eRoot`).
+
+## Post-wire audit chain (order)
+
+Run from **FE repo** cwd after `/wire` code changes:
+
+```bash
+# 1) Plan ↔ Playwright (mandatory)
+flowgrid audit e2e --e2e-root <dir> --tests-docs "$FLOWGRID_TESTS_DOC" --screen <W-*>
+
+# 2) Contract parity (portal leaf with apiRef)
+flowgrid audit fe-be "$FLOWGRID_DOCS_ROOT/surfaces/.../<slug>.bundle.yaml" \
+  [--backend-spec .../api/.../01-backend-spec.yaml]
+
+# 3) Cross-flow (when SC lists this screen)
+flowgrid audit scenario "$FLOWGRID_DOCS_ROOT/scenarios/.../SC-*.yaml" --tests-docs "$FLOWGRID_TESTS_DOC"
+```
+
+Consume JSON fields:
+
+| Audit | Keys / codes | Meaning |
+|-------|----------------|---------|
+| `e2e` | `missingInPlaywright`, `matrixRowsUncovered`, `orphanSpecs`, `orphanTestCases`, `gaps[]` | TC ↔ PO ↔ spec |
+| `fe-be` | `FEBE_*` | `apiRef` / DTO ↔ `01` |
+| `scenario` | `SC_SCREEN_NO_TC` | SC `screens[]` without plan |
+
+Re-run **entire chain** after fixes in any lane (code, plan, or spec).
+
+## Gap → skill (no silent patches)
+
+| Finding | Owner repo | Skill / command |
+|---------|------------|-----------------|
+| Missing/wrong `*.spec.ts`, PO, `testId`, post-wire assertion | FE | `/test` → `/grill-test` |
+| TC plan thin, wrong AC, missing `testMatrix` facet for **real API** behaviour | tests-docs | `/grill-testcase` · patch `TC-*.yaml` · `cases:gate` |
+| Business/spec/UX wrong vs what API actually returns | docs hub | `/update-spec` (paste-ready `/docs-hub` prompt) |
+| `01` / OpenAPI wrong; BE field/status codes | docs hub | `/api-update` → BE `/audit-api` → re-wire |
+| SC screen uncovered | tests-docs | `/testcase` or `/scenario` + `audit scenario` |
+| Intentional defer | docs | `qa` + `QA-*` / `coverage_deferred` on SC |
+
+**Forbidden:** patch `ir/*` or `01` from FE repo; invent AC on tests hub; skip `audit e2e` because manual QA passed.
+
+## Loop: wire → spec → test → wire
+
+```text
+/wire (FE)
+  → audit e2e + fe-be (+ scenario)
+  → gap?
+       spec/UX     → docs /update-spec → split/render → FE re-prototype or continue wire
+       contract    → docs /api-update → BE deploy → /wire
+       plan        → tests /grill-testcase → cases:gate → testcase:gen → /test → /grill-test
+  → re-run audit chain until sign-off (wire.md#wire-signoff)
+```
+
+Lifecycle: promote route registry `test` → `wire` when team uses page lifecycle (`artifacts/code.md`).
+
+## Sign-off snippet
+
+```text
+Wire audit OK: <W-*> | audit e2e: no critical | fe-be: clear | scenario: clear/deferred
+```

package/harness/fe/extracts/wire-phase.md

@@ -0,0 +1,45 @@
+# Wire phase — agent digest (FE repo)
+
+Hub SSOT: `docs/workflows/wire.md` · Skill: `harness/fe/skills/wire/SKILL.md`.
+
+## When
+
+After `/grill-prototype` pass, BE `/audit-api` (or tracked issues), tests `cases:gate --strict` for scope, pre-wire E2E green.
+
+## Resolve docs
+
+1. `FLOWGRID_DOCS_ROOT` (mandatory preferred)
+2. Else platform-dna pointer — slower
+
+Never invent IR; read `ir/design.yaml` + bundle via docs route.
+
+## `/wire` order (Portal)
+
+1. models ↔ real API
+2. services/* ($apiFetch, parseApiData)
+3. composables
+4. pages/components + 422 validation map
+5. Remove **production** mocks — keep test-only mocks
+6. Restore auth/RBAC (from grill-prototype handoff)
+7. Clear `#wire-only` / resolved `#update:*` when done
+
+## Post-wire audits (mandatory)
+
+```bash
+flowgrid audit e2e --e2e-root <dir> --tests-docs "$FLOWGRID_TESTS_DOC" --screen <W-*>
+flowgrid audit fe-be <bundle.yaml>   # portal screens
+```
+
+Optional: `audit scenario` when SC covers screen.
+
+Fix gaps → see **`wire-audit-loop.md`** (`/test`, `/grill-test`, `/grill-testcase`, `/update-spec`, `/api-update`). Sign-off audit → `/grill-wire`.
+
+## Forbidden
+
+- Wire without `FLOWGRID_TESTS_DOC` when team uses gate
+- Skip `audit e2e` because manual QA passed
+- Patch `01` from FE repo — use `/api-update` on docs hub
+
+## BE-only / API hook
+
+No FE `/wire` — use `testcase:gen:api`, Newman optional, BE integration tests.

package/harness/fe/rules/platform-design-vocabulary.mdc

@@ -6,7 +6,7 @@ alwaysApply: false
 
 # Design vocabulary
 
-SSOT: `registries/design.registry.json` · validate with `flowgrid registry`.
+SSOT: `registries/design.registry.json` (refresh: `flowgrid registry:sync`) · validate: `flowgrid registry`.
 
 ## Hashtags (grill → `tags:`)
 

package/harness/fe/rules/team-flow-prototype.mdc

@@ -6,7 +6,7 @@ alwaysApply: false
 
 # Team Flow — Prototype
 
-Active: `/prototype` · `/grill-prototype` — **một** command / session.
+Active: `/prototype` và `/grill-prototype` — **hai** session (prototype trước, grill-prototype sau).
 
 | Command | Skill |
 |---------|-------|
@@ -20,11 +20,15 @@ bộ docs (`FLOWGRID_DOCS_ROOT`); never CodeGraph for C4/architecture.
 
 ## Thứ tự
 
-0. `/gen-common --surface=…` rồi `/gen-common --module=CMP-…` nếu hub có `common/` — gen molecule/shell dùng chung trước.
-1. Quét `#needs-component` / custom-render tags — chỉ tạo component còn thiếu.
-2. `npm run codegen -- --id W-…` (hoặc MCP `gen`) — đọc `…/code/{W-…}/generated/HANDOFF.md`.
+0. Docs hub `common/` = `processes/` + `patterns/` (Markdown) — tham chiếu nghiệp vụ; **không** gen-common.
+1. `npm run codegen:dry` rồi `npm run codegen -- --id W-…` (hoặc MCP `gen`) — đọc `…/code/{W-…}/generated/HANDOFF.md`.
+2. Quét `#needs-component` — implement từ FE base + shadcn; template/registry mới → `docs/workflows/custom-base.md` (toolkit SSOT).
 3. Vá slot · auth bypass · gap; **không** sửa YAML business trên hub khi prototype.
 
+## Sau prototype
+
+4. Session mới: `/grill-prototype` — checklist UI (design.md bước 6); không chạy `gen:dry` lại trừ khi đổi IR.
+
 - Source: grill-approved hub `ir/design.yaml`
 - Real UI; mock chỉ API boundary
 - **Không** backend thật — `/wire` thay mock

package/harness/fe/skills/gen-common/SKILL.md

@@ -1,93 +1,20 @@
 ---
 name: gen-common
-description: >-
-  /gen-common — generate shared UI from bộ docs common specs before
-  /prototype. Covers surface common (surfaces/<surface>/common) and
-  module common (surfaces/<surface>/CMP-*/common). Use when
-  bootstrapping DataListPage, MoStatusChip, or CMP-level shared widgets.
+description: DEPRECATED — common UI is shipped in the FE base; use custom-base for new templates. Do not invoke.
 disable-model-invocation: true
 ---
 
-# /gen-common — Shared UI before /prototype
+# /gen-common — DEPRECATED
 
-**Owner:** bộ code (`--type=fe`) · Adapters: `nuxt4` | `nextjs`  
-Not synced for `dotnet-line`.
+**Removed from product workflow.** Shared molecules (list page, status chip, delete flow, …) live in the **FE base**; affordances are enforced via `flowgrid-ux-common.mdc` during `/spec` and grill.
 
-Skill is **`/gen-common`**, not `/common` — `common` is the docs folder name (and there are three of them).
+| Old step | Use instead |
+|----------|-------------|
+| `common/yaml` + `flowgrid gen-common` | FE base components + `design.registry.json` |
+| New Mo* / adapter templates | [custom-base workflow](../../../docs/workflows/custom-base.md) → `build-template-code` |
+| Cross-scope business rules | `/common` → `common/patterns/*.md` |
+| Cross-flow | `common/processes/FLOW-*.md` |
 
-| Scope | Docs path | Flag |
-|-------|-----------|------|
-| Platform | `surfaces/common` | `--surface=common` |
-| Surface | `surfaces/<surface>/common` | `--surface=admin-web` |
-| Module | `surfaces/<surface>/<CMP-*>/common` | `--module=CMP-ADM-009` |
+**If a member invokes `/gen-common`:** STOP — explain deprecation; continue with `/prototype` (`gen:dry` → `gen`) when `grillStatus.dev: done`.
 
-Run **surface** first, then **module**, then `/prototype` for screens.
-
-## IR
-
-```text
-…/common/yaml/<slug>/ir/design.yaml   # tech — Read entire file
-…/common/yaml/<slug>/ir/spec.yaml     # prose only — do not gen from this
-```
-
-Read the **entire** `ir/design.yaml`. Missing design → STOP, hand off to docs `/common-spec` + `flowgrid split` (do not invent yaml). Prose-only `common/processes` (FLOW) is not `/gen-common` input. Thin design is OK for tokens; do not page-gen common IRs.
-
-**Docs hub is read-only.** Never Write common bundles/`ir/*` on the docs hub.
-
-Do **not** run `flowgrid gen --id common-list-page`. Page gen skips all three common trees.
-
-## Docs Root Resolution
-
-1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
-   pointer for locating common IR (`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.
-
-## Workflow
-
-```bash
-npm run codegen:common:dry -- --surface=admin-web --json
-npm run codegen:common -- --surface=admin-web
-npm run codegen:common:dry -- --module=CMP-ADM-009 --json
-npm run codegen:common -- --module=CMP-ADM-009
-
-# Fallback:
-flowgrid gen-common:dry --adapter=nextjs --docs-root=/path/to/docs -- --surface=admin-web --json
-flowgrid gen-common --adapter=nextjs --docs-root=/path/to/docs -- --module=CMP-ADM-009
-flowgrid gen-common:dry -- --id common-status-chip --surface=admin-web
-```
-
-`common-gen` is an alias of `gen-common`.
-
-1. Choose scope (`--surface` xor `--module`, or `--surface=… --all-modules`). Do not guess when several surfaces exist.
-2. Dry `--json`. Kinds: `tokens` / `policy` / `molecule` / `shell` / `flow`.
-3. Write stubs + upsert `registries/common.registry.json`. Keep existing files unless `--force`.
-4. Implement `action: implement` from **`ir/design.yaml`** (tokens/policy as constraints). shadcn compose when `components.json` exists.
-5. Surface emit → molecules/organisms. Module emit → `src/components/modules/<cmp-…>/` (namespaced, no overwrite of surface shells).
-6. Re-run dry until emit entries are `implemented`.
-7. `/prototype` for `CMP-*` screens.
-
-## Kind handling
-
-| Kind | Emit? | Agent |
-|------|-------|--------|
-| `tokens` / `policy` | no | Apply while implementing others |
-| `molecule` | yes | Compose primitive → molecule |
-| `shell` | yes | After `dependsOn` molecules |
-| `flow` | sometimes | delete-flow wires ConfirmDialog; import-csv emits `MoImportCsv` |
-| `skip` | no | Backend folders (`common-api`, `backend-core-services`) |
-
-## Do not
-
-- Page-gen common IRs or invent routes from them.
-- Copy platform `surfaces/common` over a surface overlay that already exists.
-- Emit module widgets onto surface paths (`DataListPage`, `MoStatusChip`).
-- Rewrite unrelated feature screens here.
-
-## Translation Rule
-Luôn bọc text tĩnh bằng i18n helper native của framework. 
-- Đọc block `i18n` từ `ir/design.yaml`.
-- Tự động sinh/cập nhật file ngôn ngữ tương ứng (`.json` cho FE/NodeJS, hoặc `.resx` cho Dotnet). 
-- KHÔNG viết gộp ngôn ngữ lên giao diện (ví dụ không dùng `login / đăng nhập`).
+CLI `flowgrid gen-common` may still exist for legacy repos; do not document new hubs against it.