@shanyucoder/flowgrid 0.1.4 → 0.1.8

package/harness/docs/skills/grill-common-spec/SKILL.md

@@ -1,43 +1,18 @@
 ---
 name: grill-common-spec
-description: EXCLUSIVE /grill-common-spec — Use this to audit and verify technical common bundles before code generation.
+description: DEPRECATED — no common YAML bundles to grill. Route to /grill-bqa on function bundles or /common for pattern MD.
 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-common-spec — DEPRECATED
 
-# /grill-common-spec — Common Bundle Audit
+There is no `common/yaml` + IR grill path on the docs hub anymore.
 
-**Target Path:** `<LCA>/common/yaml/<slug>/<slug>.bundle.yaml` (see `.cursor/extracts/common-scope.md`).
+| Gap | Route |
+|-----|--------|
+| Function screen/API spec | `/grill-bqa` · `/grill-dev` on `*.bundle.yaml` |
+| Shared rule prose | `/common` (patterns Markdown) |
+| UI affordance / pattern | `flowgrid-ux-common.mdc` + `/grill-bqa` |
+| Registry / template drift | [custom-base](../../../docs/workflows/custom-base.md) |
 
----
-
-## Rule: Audit Checks
-
-- **[MANDATORY]** Verify `schema` is set (e.g. `portal-feature-bundle/v1` or appropriate surface schema).
-- **[MANDATORY]** Verify `design.shell.tag` reflects the target platform:
-  - Web Portal → `#shell: DataListPage`
-  - WinForms → `#shell: KioskCheckIn`
-  - Gateway → `#shell: OtAdapter`
-- **[MANDATORY]** Verify `spec.principles` and `spec.acceptance` are detailed enough to drive test cases and codegen.
-- **[MANDATORY]** Verify `design.patterns` and referenced middlewares point to valid, existing items.
-- **[STRICTLY FORBIDDEN]** Do NOT "fix" a module-common bundle by copying it to surface `common/`.
-
----
-
-## Rule: Output
-
-- **[STRICTLY FORBIDDEN]** Do NOT output new files from this skill.
-- **[MANDATORY]** If issues are found → inform user + suggest fixes, or fix directly in `.bundle.yaml` if instructed.
-- **[MANDATORY]** If bundle passes → instruct user: run `flowgrid split -- <path>` (must emit `ir/design.yaml`), then bộ code FE `/gen-common`.
-- **[STRICTLY FORBIDDEN]** Do NOT send BE `/api` a common FE bundle.
-
----
-
-## Verification Checklist
-
-- [ ] `schema` field set correctly.
-- [ ] `design.shell.tag` aligned with target surface type.
-- [ ] `spec.principles` and `spec.acceptance` are substantive.
-- [ ] All `design.patterns` / middleware references are valid and exist.
+**If invoked:** STOP — do not load `surfaces/common/yaml`.

package/harness/docs/skills/grill-dev/SKILL.md

@@ -8,7 +8,7 @@ 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 entire `ir/design.yaml`. If `ir/` is missing, read entire `*.bundle.yaml`. NEVER filter partial keys.
-> **[MANDATORY]** Expect `grillStatus.bqaOpen: done` (or `bqaFacts`) before starting.
+> **[MANDATORY]** Expect `grillStatus.bqaOpen: done` before starting. Do **not** start if only `bqaFacts` is set — finish `/grill-bqa` Step B first.
 
 # /grill-dev — Dev / Codegen Grill
 
@@ -30,11 +30,12 @@ disable-model-invocation: true
 
 ## Rule: Audit Interlock with Page Type
 
-- **[MANDATORY]** Before grilling, run: `flowgrid audit spec <bundle> --type <profile>`.
+- **[MANDATORY]** Before grilling, run: `flowgrid audit spec <bundle> --type <profile>`. Treat `warnings[]` as non-blocking; nudge BQA via handoff if summary still has `[placeholder]` brackets.
+- **[MANDATORY]** After `bundle.gen` patch: `flowgrid split` + `flowgrid render` (FE uses `ir/design.yaml`; BA PDF path uses `ir/generated/spec.md`).
   - `<profile>` lấy từ `gen.codegen.profile` đã xác nhận (list | create | detail | admin-crud | auth | ...).
   - Nếu profile chưa set → hỏi member xác định profile trước, KHÔNG chạy audit với `--type unknown`.
-  - Script output `gaps[]` + `confirms[]` (includes `UX_*` / `CONFIRM_UX_*` affordance — see `flowgrid-ux-common.mdc`).
-  - Agent patches structural `gaps[]`; UX confirms → wizard with `(Recommended)` from audit output.
+  - Script output `gaps[]` + `confirms[]` (`CONFIRM_UX_*`, **`CONFIRM_DB_*`** — `db-audit-wizard.md`).
+  - Agent patches structural `gaps[]`; UX/DB confirms → wizard; BE drift → `/api-update` then re-audit.
 
 ---
 
@@ -120,7 +121,7 @@ disable-model-invocation: true
 
 ## Rule: API Reuse & Explicit Suffix
 
-- **[MANDATORY]** Scan `common/yaml/` (LCA) + sibling `…/api/<seq>/` for existing `01` files. If found → tag `#reuse-api` + `reuseFrom` on page action/item; skip new trio.
+- **[MANDATORY]** Scan sibling `…/api/<seq>/` (+ shared `01` on function leaf when present) for existing endpoints. If found → tag `#reuse-api` + `reuseFrom` on page action/item; skip new trio. Do not scan deprecated `common/yaml`.
 - **[MANDATORY]** All endpoint paths MUST use explicit suffixes: `/create`, `/{id}/update`, `/{id}/duplicate`, `/{id}/delete`, `/{id}/detail`.
 
 ---
@@ -155,7 +156,7 @@ disable-model-invocation: true
 
 - bộ code FE dry pass → `/prototype`
 - BQA↔Dev conflict → `/grill-docs`
-- Legacy fact gap → `/update-spec-legacy`
+- Legacy fact gap → `/legacy /spec` or `/update-spec` (legacy evidence delta)
 - Confirmed common promote → `/docs-mark` (same session or before `/prototype`)
 
 ---

package/harness/docs/skills/grill-docs/SKILL.md

@@ -39,6 +39,13 @@ disable-model-invocation: true
 
 ---
 
+## Rule: Audit interlock (sau reconcile)
+
+- **[MANDATORY]** After any bundle patch that touches `design.*`, `userStories`, `bundle.gen`, or `api` refs: run `flowgrid audit spec <bundle> --type <pageType>` (same profile rules as `/grill-dev`). Resolve `CONFIRM_DB_*` via `db-audit-wizard.md` before handoff.
+  - Patch structural `gaps[]`; defer remainder via `qa/open/` per Law 2.
+  - Address `warnings[]` when reconcile changes business prose (`summary`, `successMetrics`, `nonGoals`, `userStories`).
+  - ❌ Do not hand off FE until audit has been re-run post-reconcile.
+
 ## Rule: Codegen Gate
 
 - **[MANDATORY]** `bundle.gen.codegen.profile` (+ entity/module when required) MUST be set.
@@ -55,8 +62,8 @@ disable-model-invocation: true
 2. Reconcile common patterns (BQA flows ↔ Dev `#pattern`, `#split-hook:` tags).
 3. Reconcile `#reuse-api` on page actions/items (no duplicate `api/<seq>/` for reused APIs).
 4. Verify codegen gate: `bundle.gen.codegen.profile` set correctly.
-5. Write/fix `bundle.gen` → `flowgrid_docs_bundle_split` → `docs_render`.
-6. Handoff ID/path + recommendation to bộ code FE.
+5. Write/fix `bundle.gen` → `flowgrid audit spec` → `flowgrid_docs_bundle_split` → `docs_render`.
+6. Handoff ID/path + recommendation to bộ code FE (`gen:dry` on FE repo).
 
 ---
 
@@ -76,4 +83,4 @@ disable-model-invocation: true
 
 - [ ] Conflicts reconciled in `*.bundle.yaml`, or deferred with `qa/open/QA-…`. No `openQuestions`.
 - [ ] `bundle.gen.codegen.profile` present and correct.
-- [ ] `flowgrid split` succeeded with zero errors.
+- [ ] `flowgrid audit spec` re-run after reconcile; `flowgrid split` succeeded with zero errors.

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

@@ -11,9 +11,11 @@ extractBundle: architecture-core
 
 # /module — Business Module (CMP-*)
 
+**Template:** `.cursor/extracts/tpl-module.md` (includes **Out of scope** + **Depends on**).
+
 **Target Paths:**
 - Module folder: `surfaces/[Surface]/[CMP-ID]/`
-- Main doc: `surfaces/[Surface]/[CMP-ID]/[CMP-ID].md`
+- Main doc: `surfaces/[Surface]/[CMP-ID]/README.md` or `[CMP-ID].md` (team convention — MD only)
 
 ---
 

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

@@ -23,9 +23,10 @@ One generator: **OpenAPI 3.0.3** from `01-backend-spec.yaml`. Merge/UI stays `op
   # Or from docs hub root (all 01-backend-spec.yaml under surfaces):
   flowgrid openapi_gen
   # Validate only:
-  flowgrid check --spec …/01-backend-spec.yaml
+  flowgrid api:check --spec …/01-backend-spec.yaml
   ```
 - **[MANDATORY]** After generation: run `flowgrid openapi_render` to merge fragments into `docs/openapi/api.yaml`.
+- **[MANDATORY]** After contract change: run `flowgrid render` on docs hub so leaf `ir/generated/api.md` matches `01` for BA/Dev review (see `tpl-api-contract.md`).
 
 ---
 

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

@@ -10,10 +10,16 @@ extractBundle: architecture-core
 
 # /overview — Operational Areas Overview
 
-**Target Paths:** `overview/operational-areas/[Admin operations | Workforce operations | …]`
+**Target Paths:** `overview/index.md`, `overview/operational-areas/<slug>.md` (copy from hub template `operational-areas/_template.md` on greenfield init).
 
 ---
 
+## Rule: arc42 §1 content
+
+- **[MANDATORY]** `overview/index.md`: goals, stakeholders table, top 5 quality goals, persona summaries, product-level in/out scope, success metrics, link to operational areas.
+- **[MANDATORY]** Each operational area file: personas, in/out scope, area metrics, `CMP-*` links, non-goals — per `_template.md`.
+- **[RECOMMENDED]** Trước spec leaf lớn: overview + area đã có persona id mà `userStories.primary.asA` tham chiếu.
+
 ## Rule: Content Boundary
 
 - **[MANDATORY]** Overview MUST be a pure business document written in user domain language: personas, operational areas, high-level system purpose.

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)
@@ -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/open` 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.
 
 ---
 
@@ -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/open` + `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.