@shanyucoder/flowgrid 0.1.9 → 0.1.11

package/harness/docs/rules/docs-hub.mdc

@@ -19,7 +19,7 @@ only.
 2. Use `flowgrid_docs_get_element` for one ID.
 3. Use `flowgrid_docs_deps_of` and `flowgrid_docs_dependents_of` for reference impact.
 4. Run `flowgrid_docs_orphans` and `flowgrid_docs_validate_links` before claiming completeness.
-5. Use `flowgrid_docs_business_processes` before reading all journey files.
+5. Use `flowgrid_docs_user_flows` before reading all journey files.
 
 Do not require bộ docs for architecture work: if the MCP is unavailable, inspect
 the repository Markdown directly or explain how to run project-local setup.

package/harness/docs/rules/flowgrid-process.mdc

@@ -1,5 +1,5 @@
 ---
-description: FlowGrid bộ process — business process trace and impact review (opt-in)
+description: FlowGrid bộ process — business-process-trace (brownfield) and impact review (opt-in)
 alwaysApply: false
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: adopt
-description: "/adopt — Scan legacy repositories and generate a high-level index mapping catalog & common candidates at root."
+description: "/adopt — Scan legacy repositories and generate a high-level index mapping catalog, user flows (incl. cross-surface), and common candidates at root."
 disable-model-invocation: true
 extractBundle: architecture-core
 ---
@@ -14,6 +14,8 @@ extractBundle: architecture-core
 
 **Handoff SSOT spec:** Sau adopt, member drill [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) — Phase 0 → `/legacy /spec` per `W-*` (không nhảy thẳng bundle không có ID trong inventory).
 
+**Inventory template:** `.cursor/extracts/tpl-adoption-inventory.md` — section layout + **user-flow placement tiers** (cross-surface → `architecture/03-user-flows/`).
+
 ---
 
 ## Rule: Pre-Scan Mode Selection (AskQuestion Wizard)
@@ -71,16 +73,35 @@ extractBundle: architecture-core
   - **Surfaces**: Application and channel names (Admin Portal, Customer Web, Gateway…)
   - **Modules (`CMP-*`)**: Primary feature groups (Auth, Orders, Profile…)
   - **Screens (`W-*`) & APIs (`API-*`)**: UI screens + API endpoints with legacy file paths (`ID → Legacy File Path`)
-  - **Cross-Flow Candidates (`FLOW-*`)**: Business flows spanning multiple screens or services
+  - **User flows (`FLOW-*`)**: Multi-step business journeys — **classify every candidate** (see Rule: User flow discovery)
   - **Common Candidates (`CMN-UI-*`, `CMN-API-*`, `CMN-DTO-*`)**: (If Common Analysis mode selected)
 
 ---
 
+## Rule: User flow discovery (incl. cross-surface)
+
+- **[MANDATORY]** Section **4. User flows (`FLOW-*`)** in `adoption-inventory.md` is **not optional** when the legacy scan finds any journey that spans **more than one screen** or **more than one deployable app/repo** in one business outcome.
+- **[MANDATORY]** For each `FLOW-*`, assign a **placement tier** (target path in the **new** docs hub after `/legacy /user-flow`):
+
+| Tier | Label | List under inventory subsection | New hub path |
+| --- | --- | --- | --- |
+| **A** | Cross-surface / org catalog | `### A — Cross-surface (org catalog)` | `architecture/03-user-flows/FLOW-*.md` |
+| **B** | Surface-shared | `### B — Shared on one surface` | `surfaces/<surface>/common/user-flows/FLOW-*.md` |
+| **C** | Module / cluster | `### C — Module or cluster scope` | `surfaces/.../CMP-*/common/user-flows/` (or `…/<NN>/common/user-flows/`) |
+| **D** | (omit) | — | Single `W-*` only — **no** `FLOW-*` |
+
+- **[MANDATORY]** Each `FLOW-*` bullet MUST state: **surfaces + CMPs involved**, **ordered steps** (`W-*` / `API-*` or legacy route names), **legacy evidence paths** (routers, orchestrators, saga/worker, shared tokens), **tier A/B/C**.
+- **[MANDATORY]** **Cross-surface (tier A)** examples: checkout/payment across customer web + admin ops; partner webhook + internal portal; SSO/login handoff across two SPAs in different legacy repos; order fulfillment touching warehouse API + customer notification app.
+- **[STRICTLY FORBIDDEN]** Listing only `W-*`/`API-*` while ignoring obvious multi-app journeys (tier A/B/C) — Tier 2 audit (`/legacy /user-flow`) depends on this index.
+
+---
+
 ## Rule: ID Standardization
 
+- **[MANDATORY]** Follow `.cursor/extracts/product-id-convention.md` — declare `surfaceCode` per surface; `CMP-{SURF}-{DOMAIN}-{NN}`, `W-{SURF}-{DOMAIN}-{NN}`, `API-{SURF}-{DOMAIN}-{NN}` (duplicate capability across surfaces ⇒ distinct IDs).
 - **[MANDATORY]** All items MUST use standardized IDs: `CMP-*`, `W-*`, `API-*`, `FLOW-*`, `CMN-UI-*`, `CMN-API-*`, `CMN-DTO-*`.
 - **[MANDATORY]** Every ID MUST map to its corresponding legacy file or directory path.
-  - ✅ `W-AD-AUTH-001: Login → admin-fe/src/pages/Login.tsx`
+  - ✅ `W-ADM-AUTH-01: Login → admin-fe/src/pages/Login.tsx`
   - ✅ `CMN-UI-001: Filter Toolbar → duplicated in admin-fe/src/pages/Orders.tsx, Users.tsx`
 
 ---
@@ -96,15 +117,25 @@ extractBundle: architecture-core
 - **Admin Portal** (`surfaces/admin`) → Legacy repo: `admin-fe`
 
 ## 2. Modules Catalog (`CMP-*`)
-- **CMP-ADM-001**: Auth & Identity Management → Legacy: `admin-fe/src/modules/auth/`
+- **CMP-ADM-AUTH-01**: Auth & Identity Management → Legacy: `admin-fe/src/modules/auth/`
 
 ## 3. Screens & API Function Inventory (`W-*`, `API-*`)
-### Admin Portal (`surfaces/admin/CMP-ADM-001`)
-- **W-AD-AUTH-001**: Login → Legacy: `admin-fe/src/pages/Login.tsx`
+### Admin Portal (`surfaces/admin/CMP-ADM-AUTH-01`)
+- **W-ADM-AUTH-01**: Login → Legacy: `admin-fe/src/pages/Login.tsx`
 - **API-ADM-AUTH-01**: Auth Services → Legacy: `auth-service/src/controllers/AuthController.java`
 
-## 4. Cross-Flow Candidates (`FLOW-*`)
-- **FLOW-checkout**: Checkout & Payment Flow → across `CMP-ADM-002` & `CMP-CUS-001`
+## 4. User flows (`FLOW-*`)
+
+### A — Cross-surface (org catalog) → `architecture/03-user-flows/`
+- **FLOW-checkout**: Checkout & payment — Surfaces: `customer-web` (`CMP-CUS-CART-01`), `admin` (`CMP-ADM-ORD-01`) — Steps: cart `W-CUS-CART-01` → pay `API-CUS-PAY-01` → ops `W-ADM-ORD-01` — Legacy: `customer-fe/src/routes/checkout/*`, `admin-fe/src/pages/Orders.tsx`, `payment-svc/...` — Tier: **A**
+
+### B — Shared on one surface → `surfaces/<surface>/common/user-flows/`
+- **FLOW-onboard-admin**: Admin onboarding — Surface: `admin` only — CMPs: `CMP-ADM-AUTH-01`, `CMP-ADM-USR-01` — Steps: … — Legacy: … — Tier: **B**
+
+### C — Module / cluster scope → `…/CMP-*/common/user-flows/`
+- **FLOW-password-reset**: Reset password — Surface: `admin` — CMP: `CMP-ADM-AUTH-01` — Steps: … — Legacy: … — Tier: **C**
+
+> If no multi-step journeys found, write: `_(none detected — screen-only inventory in §3)_`
 
 ## 5. Common Catalog Candidates (Anti-Copy-Paste Guard)
 > **Purpose**: Reuse for specs and code of new features / spec updates.
@@ -122,12 +153,12 @@ extractBundle: architecture-core
 
 ### ⚠️ Whole Page Duplication Warnings
 > **Note**: Do not create `CMN-*` for full pages. Recommend consolidating into a single polymorphic spec (`mode: create | edit`).
-- **W-AD-USER-001 (Create User)** & **W-AD-USER-002 (Edit User)**: 95% identical → *Recommendation: Consolidate into single Form Spec `CMP-ADM-USER-FORM`*
+- **W-ADM-USR-01 (Create User)** & **W-ADM-USR-02 (Edit User)**: 95% identical → *Recommendation: Consolidate into single Form Spec `CMP-ADM-USR-FORM`*
 
 ---
 ## 6. Handoff Usage Guide
-- `/legacy /spec W-AD-AUTH-001` — spec a legacy screen (MUST reuse CMN-* if applicable)
-- `/legacy /business-process FLOW-checkout` — map a legacy flow
+- `/legacy /spec W-ADM-AUTH-01` — spec a legacy screen (MUST reuse CMN-* if applicable)
+- `/legacy /user-flow FLOW-checkout` — map a legacy flow
 ```
 
 ---
@@ -138,5 +169,6 @@ extractBundle: architecture-core
 - [ ] Audit script run; index checked or gaps reported.
 - [ ] `adoption-inventory.md` created directly at workspace root.
 - [ ] All items use standardized `CMP-*`, `W-*`, `API-*`, `FLOW-*`, `CMN-*` IDs.
+- [ ] Section 4 lists user flows with tier **A/B/C** when multi-step/cross-app journeys exist; tier **A** cross-surface rows are explicit.
 - [ ] Common Catalog Candidates listed with source files if Common mode selected.
 - [ ] Anti-Copy-Paste Guard enforced for new spec/code.

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

@@ -28,7 +28,7 @@ Shared extracts: `api-spec-sync.md`, `spec-evolution.md`, `entity-relationship.m
 
 ## Rule: ID Resolution & Folder Location
 
-- **[MANDATORY]** If an ID is provided (e.g. `CMP-ADM-000-001`, `W-AD-AUTH-001`) → use `flowgrid_docs_route` or glob to resolve to `…/api/<seq>/01-backend-spec.yaml`. Do NOT force user to provide full filesystem path.
+- **[MANDATORY]** If an ID is provided (e.g. `CMP-ADM-AUTH-01-001`, `W-ADM-AUTH-01`) → use `flowgrid_docs_route` or glob to resolve to `…/api/<seq>/01-backend-spec.yaml`. Do NOT force user to provide full filesystem path.
 - **[MANDATORY]** Trio lives under `api/<seq>/` — never adjacent to `*.bundle.yaml`.
 - Common APIs: `…/common/yaml/<slug>/01-backend-spec.yaml` (one trio per API).
 

package/harness/docs/skills/background-logic/SKILL.md

@@ -19,7 +19,7 @@ extractBundle: architecture-core
 ## Rule: When to Use /background-logic
 
 - **[MANDATORY]** Use this skill when:
-  1. A `FLOW-*` business process has established UI steps but requires background automation (e.g. dispatching Zalo/SMS notifications upon booking creation, auto-cancelling orders after 15 minutes of non-payment).
+  1. A `FLOW-*` user flow has established UI steps but requires background automation (e.g. dispatching Zalo/SMS notifications upon booking creation, auto-cancelling orders after 15 minutes of non-payment).
   2. Existing background logic needs updating (changing dispatch channels, modifying filtering conditions, adjusting retry policies, updating storage buckets).
   3. Auditing background tasks for comprehensive error scenarios, retry strategies, and idempotency guarantees.
 - **[STRICTLY FORBIDDEN]** Do NOT use this skill to edit UI screen specifications (use `/update-spec`) or author new APIs (use `/api-spec`).

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

@@ -10,7 +10,7 @@ Common technical bundles (`common/yaml`, `*.bundle.yaml` under `surfaces/.../com
 
 | Need | Use |
 |------|-----|
-| Cross-flow product doc | `common/processes/FLOW-*.md` |
+| Cross-flow product doc | `common/user-flows/FLOW-*.md` |
 | Shared UX/business rules | `/common` → `common/patterns/*.md` |
 | UI patterns (delete flow, badges, flat design, …) | FE **base** + `flowgrid-ux-common.mdc` during `/spec` / grill |
 | New shared component / codegen template | [custom-base](../../../docs/workflows/custom-base.md) → `build-template-code` |

package/harness/docs/skills/cross-service/SKILL.md

@@ -18,7 +18,7 @@ extractBundle: architecture-core
 
 - **[MANDATORY]** Use when a flow crosses a service, system, or boundary: sync RPC, async messaging, event-driven handoffs, retries, idempotency, integration contracts.
 - **[STRICTLY FORBIDDEN]** Do NOT use for internal code execution paths inside a single service — that belongs in architecture internals.
-- **[STRICTLY FORBIDDEN]** Do NOT use for business action flows on a surface → use `/business-process`.
+- **[STRICTLY FORBIDDEN]** Do NOT use for business action flows on a surface → use `/user-flow`.
 - **[STRICTLY FORBIDDEN]** Do NOT use for runtime journey narratives focusing on user/system step order across the whole product → use `/journey`.
 
 ---

package/harness/docs/skills/db-erd/SKILL.md

@@ -10,7 +10,7 @@ extractBundle: architecture-core
 
 # /db-erd — Business Data Model (ERD)
 
-**Phase:** **0 Architecture** — sau `/overview`, `/module`, `/business-process` khi có entity/bảng mới. **Trước** `/spec` leaf.
+**Phase:** **0 Architecture** — sau `/overview`, `/module`, `/user-flow` khi có entity/bảng mới. **Trước** `/spec` leaf.
 
 **Hub SSOT:** [architecture-data.md](../../../docs/workflows/architecture-data.md)
 

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

@@ -21,6 +21,8 @@ SSOT flow: `docs/workflows/grill-and-human-review.md` · close checklist: `docs/
 
   | Gap context | Route to |
   | --- | --- |
+  | Overview / surface / CMP `index.md` PRD sections | `/grill-hub-prd` |
+  | Sổ rủi ro quota / hạn mức / peak | `/risk-register` |
   | UI acceptance, copy, validation, UX affordance | `/grill-bqa` |
   | `bundle.gen`, codegen profile, `#gen:*`, endpoint `action` on `01` | `/grill-dev` |
   | BQA ↔ Dev contradiction on same bundle | `/grill-docs` |

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

@@ -0,0 +1,38 @@
+---
+name: grill-hub-prd
+description: EXCLUSIVE /grill-hub-prd — PRD sections on overview, surface, CMP index.md. Audit-first like grill-bqa.
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool.
+
+# /grill-hub-prd — Hub PRD validation
+
+**Targets:** `overview/index.md`, `overview/operational-areas/*.md`, `surfaces/<surface>/index.md`, `surfaces/.../CMP-*/index.md`.
+
+**Extracts:** `tpl-overview-prd.md`, `tpl-surface-prd.md`, `tpl-module.md`.
+
+---
+
+## Rule: Audit interlock
+
+- **[MANDATORY]** Run `flowgrid audit hub-prd <path-to.md>` before editing.
+- **[MANDATORY]** Fix all `gaps[]`; resolve `warnings[]` via patch or `AskQuestion` (Recommended / Other / Log as Tech Debt → `qa/` per `qa-authoring.md`).
+- **[MANDATORY]** Re-run audit until `totalGaps === 0` or gaps deferred to `qa/*.yaml`.
+- **[STRICTLY FORBIDDEN]** Author Personas tables or Success metrics on hub — KPI/persona ngoài hub.
+
+---
+
+## Rule: Missing information (Law 2)
+
+- **≤5 gaps:** `AskQuestion` one at a time, ≥3 options.
+- **≥10 gaps:** STOP — Plan Mode / phased doc offloading.
+
+---
+
+## Verification
+
+- [ ] English headings: Goals, Background, Scope (prose = `contentLocale` from `docs-hub.locale.yaml`).
+- [ ] No bracket placeholders `[...]` for sign-off.
+- [ ] `flowgrid audit hub-prd` clean or qa defer documented.

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

@@ -1,6 +1,6 @@
 ---
 name: module
-description: EXCLUSIVE /module — Handles business modules (CMP-*). DO NOT output fake Markdown reports.
+description: EXCLUSIVE /module — Handles business modules (CMP-{SURF}-{DOMAIN}-{NN}). DO NOT output fake Markdown reports.
 disable-model-invocation: true
 extractBundle: architecture-core
 ---
@@ -11,11 +11,14 @@ extractBundle: architecture-core
 
 # /module — Business Module (CMP-*)
 
-**Template:** `.cursor/extracts/tpl-module.md` (includes **Out of scope** + **Depends on**).
+**Template:** `templates/project-skeleton/surfaces/_module-index.template.md` → `surfaces/<surface>/CMP-*/index.md` (extract: `tpl-module.md`).
 
-**Target Paths:**
-- Module folder: `surfaces/[Surface]/[CMP-ID]/`
-- Main doc: `surfaces/[Surface]/[CMP-ID]/README.md` or `[CMP-ID].md` (team convention — MD only)
+- **[MANDATORY]** Sections: **Goals**, **Scope**, **Features overview**, **Depends on** — English headings; prose in `contentLocale`.
+- **[MANDATORY]** After edit: `flowgrid audit hub-prd surfaces/.../CMP-*/index.md` or `/grill-hub-prd`.
+
+**Target paths:**
+- Module folder: `surfaces/<surface>/CMP-<NN>-<slug>/`
+- Hub doc: `index.md` only (not README) — MD hub for grill/audit
 
 ---
 
@@ -30,7 +33,7 @@ extractBundle: architecture-core
 ## Rule: Common Scope for `/module … common`
 
 - **[MANDATORY]** When called with `common` modifier:
-  - Default: `surfaces/[Surface]/[CMP-ID]/common/` (`patterns/`, `yaml/`, `processes/`).
+  - Default: `surfaces/[Surface]/[CMP-ID]/common/` (`patterns/`, `user-flows/`).
   - If user names a cluster (e.g. `02`, draft `2-*`) → `…/[CMP-ID]/02/common/` (or deeper if sub-prefix specified).
   - **[STRICTLY FORBIDDEN]** Do NOT create `surfaces/[Surface]/common` from `/module` — that scope requires `/surfaces`.
 

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

@@ -14,15 +14,16 @@ extractBundle: architecture-core
 
 ---
 
-## Rule: arc42 §1 content
+## Rule: PRD sections (English keys)
 
-- **[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.
+- **[MANDATORY]** `overview/index.md` from `templates/project-skeleton/overview/index.md`: **Goals**, **Background**, **Scope** (in/out bullets), operational-areas table, see-also links. Extract: `tpl-overview-prd.md`.
+- **[MANDATORY]** Each `overview/operational-areas/<slug>.md` from `operational-areas/_template.md`: **Scope**, module links, related user flows.
+- **[STRICTLY FORBIDDEN]** Personas tables or Success metrics on hub — defer outside hub or bundle `userStories`.
+- **[MANDATORY]** After edit: `flowgrid audit hub-prd overview/index.md` (or operational/surface path) — zero gaps or `/grill-hub-prd`.
 
-## Rule: Content Boundary
+## Rule: Content boundary
 
-- **[MANDATORY]** Overview MUST be a pure business document written in user domain language: personas, operational areas, high-level system purpose.
+- **[MANDATORY]** Overview is business prose in hub `contentLocale`; section titles stay English.
 - **[STRICTLY FORBIDDEN]** Do NOT include technical details (database schemas, cloud infrastructure configurations, internal routing mechanisms).
 - **[MANDATORY]** When mentioning 3rd-party systems, use business names only (e.g. "Payment Gateway"), not technical specifications or protocols.
 

package/harness/docs/skills/risk-register/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: risk-register
+description: /risk-register — Maintain architecture/11-risks/risk-register.md (quota, limits vs peak need).
+disable-model-invocation: true
+---
+
+# /risk-register — Sổ rủi ro tổng hợp
+
+**SSOT:** `architecture/11-risks/risk-register.md`  
+**Template:** `harness/docs/extracts/tpl-risk-register.md`
+
+**Khi dùng:** Rủi ro **không gắn một màn** — hạn mức email/SMS/API, license, SLA vendor, capacity cao điểm.
+
+---
+
+## Rule: Audit interlock
+
+- **[MANDATORY]** `flowgrid audit risks architecture/11-risks/risk-register.md` trước/sau sửa.
+- **[MANDATORY]** Mỗi dòng: so sánh **Hạn mức** vs **Nhu cầu** → **Chênh lệch** → **Ảnh hưởng** → **Phương án**.
+- **[STRICTLY FORBIDDEN]** Ghi `risks:` trên `*.bundle.yaml` — SSOT chỉ file này.
+
+## Rule: AskQuestion (Law 2)
+
+Thiếu số (quota, peak): wizard ≥3 options (Recommended / Other / Tech debt → `qa/`).
+
+## Verification
+
+- [ ] Ít nhất một rủi ro thật (không chỉ RISK-EXAMPLE).
+- [ ] Audit `risks` trên register: gaps = 0 hoặc defer qa.

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

@@ -62,7 +62,7 @@ Hub: [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) · extract `
   - `<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.
-    - `warnings[]` → **quality hints only** (missing `successMetrics`/`nonGoals`, summary placeholders) — fix when info exists; **does not** block split.
+    - `warnings[]` → **quality hints** (`scopeIn`, `nonGoals`, `nfr`, `userFlows`, placeholders) — fix when info exists; **does not** block split. Rủi ro → `/risk-register` only (`WARN_BUNDLE_RISKS_FORBIDDEN` if `risks:` on bundle).
     - `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`)
@@ -85,9 +85,10 @@ Hub: [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) · extract `
 
 ## Rule: Target / ID Resolution
 
+- **[MANDATORY]** Product IDs per `product-id-convention.md` (`surfaceCode`, `CMP-{SURF}-{DOMAIN}-{NN}`, `W-{SURF}-{DOMAIN}-{NN}`).
 - **[MANDATORY]** Resolve screen ID, module ID, slug, or Draft ID before generating any file.
   - Draft ID `1-1-2` → pad each segment → `01/01/02/`
-  - Bundle ID: module prefix + padded segments, e.g. `CMP-ADM-002` + `02-01-02` → `page-id: cmp-adm-002-02-01-02`
+  - Bundle ID: module prefix + padded segments, e.g. `CMP-ADM-ORD-01` + `02-01-02` → `page-id: cmp-adm-ord-01-02-01-02`
 - **[MANDATORY]** Search for input `.md` file at resolved path. If found, read it as primary requirement source — do NOT say "I cannot hallucinate" or ask user for input that is already present.
 - **[STRICTLY FORBIDDEN]** Do NOT demand full filesystem path from user when ID or slug is given.
 
@@ -152,7 +153,7 @@ Each zone turn — **in order**:
 
 ### 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/`.
+- **[RECOMMENDED]** Fill `scopeIn`, `nonGoals`, `userFlows`, `nfr` when PO/BA có thông tin. Rủi ro dự án → **`/risk-register`** (`architecture/11-risks/risk-register.md`), never `risks:` on bundle.
 - **[MANDATORY]** Replace template `[placeholder]` brackets in `summary` / metrics / non-goals before handoff grill.
 
 ### Rule: User Stories (`userStories`)
@@ -268,6 +269,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.
-- [ ] `successMetrics` / `nonGoals` filled or consciously omitted (not left as template brackets).
+- [ ] PRD fields (`scopeIn`, `nonGoals`, `userFlows`, `nfr`) filled or deferred via `qa/` (no template brackets). Rủi ro không trên bundle.
 - [ ] `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/surfaces/SKILL.md

@@ -16,6 +16,7 @@ extractBundle: architecture-core
 
 ## Rule: Target Resolution
 
+- **[MANDATORY]** On create: set `surfaceCode` (2–4 uppercase letters) in `surfaces/<slug>/index.md` frontmatter — SSOT for all `CMP-*` / `W-*` / `API-*` on this channel (`product-id-convention.md`).
 - **[MANDATORY]** Use `flowgrid_docs_route` or `flowgrid_docs_get_element` (or glob) to resolve the target surface directory under `surfaces/[Surface Name]/`.
 - **[STRICTLY FORBIDDEN]** Do NOT confuse an API with a surface. APIs belong to architecture containers or function-level API contracts.
 
@@ -31,7 +32,9 @@ extractBundle: architecture-core
 
 ## Rule: Overview Alignment
 
-- **[MANDATORY]** When authoring a surface overview, describe: target actors, their actions, interaction channels, and assigned business responsibilities. Keep descriptions in business terms rather than technical architecture.
+- **[MANDATORY]** When creating or updating a surface hub, copy `templates/project-skeleton/surfaces/_surface-index.template.md` → `surfaces/<surface>/index.md` (**Goals**, **Background**, **Scope**, CMP table, user-flow links, features overview). Extract: `tpl-surface-prd.md`.
+- **[MANDATORY]** Before handoff: `flowgrid audit hub-prd surfaces/<surface>/index.md` — zero gaps or `/grill-hub-prd`.
+- **[MANDATORY]** Describe actors, channels, and business responsibilities in plain language (no infra detail).
 - **[MANDATORY]** Surface technical boundary: UI layout, component states, props, single-API data schemas specific to that screen.
 - **[STRICTLY FORBIDDEN]** Do NOT include system-level architecture details (backend server configuration, load balancers, database schemas) in surface documentation.
 

package/harness/docs/skills/{business-process → user-flow}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: business-process
-description: /business-process (or /flow) — Models business action flows (actor + surface + action + outcome) as FLOW-*.
+name: user-flow
+description: /user-flow — Luồng người dùng (FLOW-*) trên surfaces.
 disable-model-invocation: true
 extractBundle: architecture-core
 ---
@@ -8,11 +8,11 @@ extractBundle: architecture-core
 > [!CRITICAL] MANDATORY PRE-FLIGHT
 > **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
 
-# /business-process (Alias: /flow)
+# /user-flow
 
 **Mindset:** Model the process by **business actions on surfaces**, not by repository or service topology.
 
-**Template:** `architecture/03-business-process/FLOW-template.md` (or surfaces `common/processes/FLOW-*.md`) — include **Success metrics** and **Non-goals** in §1 when information exists.
+**Template:** `architecture/03-user-flows/FLOW-template.md` (or `**/common/user-flows/FLOW-*.md`) — **Non-goals** in §1 when information exists (KPI ngoài hub).
 
 ---
 
@@ -36,8 +36,8 @@ extractBundle: architecture-core
 ## Rule: Target Path Resolution
 
 - **[MANDATORY]** Resolve placement path via `.cursor/extracts/common-scope.md` §4.
-  - Surface-level: `surfaces/**/common/processes/FLOW-*.md`
-  - Architecture-level: `architecture/03-business-process/`
+  - Surface-level: `surfaces/**/common/user-flows/FLOW-*.md`
+  - Architecture-level: `architecture/03-user-flows/`
 - **[STRICTLY FORBIDDEN]** Do NOT use an unstandardized path like `[Target Path]/Common/Business processes`.
 
 ---
@@ -59,7 +59,7 @@ extractBundle: architecture-core
 
 ### When co-activated with `/architecture`:
 - **[MANDATORY]** Focus on technical `sequenceDiagram` for entire long-running flow: backend services, DB interactions, cronjobs, external APIs, 3rd-party handshakes.
-- Placement: `architecture/03-business-process/`.
+- Placement: `architecture/03-user-flows/`.
 
 ---
 
@@ -93,7 +93,7 @@ extractBundle: architecture-core
 
 - **[MANDATORY]** If `adoption-inventory.md` does NOT exist at workspace root → STOP: *"Run `/docs-hub /adopt` first."*
 - **[MANDATORY]** If file exists: look up `FLOW-*` candidates and map legacy module/screens. Write with `legacy-` prefix (e.g. `legacy-FLOW-checkout.md`).
-- **[MANDATORY - CROSS-FLOW LEGACY AUDIT]**: When analyzing legacy business processes (`/legacy /business-process`), Agent **MUST PROACTIVELY AUDIT END-TO-END FLOW GAPS**:
+- **[MANDATORY - CROSS-FLOW LEGACY AUDIT]**: When analyzing legacy user flows (`/legacy /user-flow`), Agent **MUST PROACTIVELY AUDIT END-TO-END FLOW GAPS**:
   - Compare Data Output at Step $N$ (e.g., Screen 1 / API 1) with Input expectations at Step $N+1$ (e.g., Screen 2 / API 2) to identify schema or status misalignments.
   - Flag orphan steps/APIs (not attached to any valid flow step) or processes lacking Confirmation / Rollback / Idempotency handling on failure.
   - Tag issues with `[LEGACY_FLOW_GAP]` and generate Open Questions for member resolution.

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

@@ -13,7 +13,7 @@ disable-model-invocation: true
 | `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` |
+| Cross-flow | `common/user-flows/FLOW-*.md` |
 
 **If a member invokes `/gen-common`:** STOP — explain deprecation; continue with `/prototype` (`gen:dry` → `gen`) when `grillStatus.dev: done`.
 

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

@@ -14,7 +14,7 @@ disable-model-invocation: true
 
 ## Target / ID Resolution Rule
 
-- User prompt MAY specify screen ID, function ID, or slug (e.g. `W-AD-AUTH-001`, `login`).
+- User prompt MAY specify screen ID, function ID, or slug (e.g. `W-ADM-AUTH-01`, `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).

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

@@ -10,7 +10,7 @@ disable-model-invocation: true
 
 ## Artifact & Target ID Resolution Rule
 
-- User prompt MAY specify a screen ID, function ID, or slug (e.g. `W-AD-AUTH-001`, `login`).
+- User prompt MAY specify a screen ID, function ID, or slug (e.g. `W-ADM-AUTH-01`, `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).
 - 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`.
@@ -18,7 +18,7 @@ disable-model-invocation: true
 
 ```text
 surfaces/<surface>/CMP-*/<NN…>/ir/design.yaml
-# e.g. …/CMP-ADM-009/01/01/01/ir/design.yaml
+# e.g. …/CMP-ADM-DEMO-01/01/01/01/ir/design.yaml
 ```
 
 Read the **entire** `ir/design.yaml` (script + agent inspection). Do not filter keys from `*.bundle.yaml`. **`ir/spec.yaml`** is business prose only.
@@ -47,12 +47,12 @@ only.
 ## Workflow
 
 ```bash
-npm run codegen:dry -- --id W-AD-AUTH-001
-npm run codegen -- --id W-AD-AUTH-001
+npm run codegen:dry -- --id W-ADM-AUTH-01
+npm run codegen -- --id W-ADM-AUTH-01
 
 # Fallback direct CLI if wrappers missing:
-flowgrid gen:dry --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
-flowgrid gen --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
+flowgrid gen:dry --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-ADM-AUTH-01
+flowgrid gen --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-ADM-AUTH-01
 
 flowgrid gen:dry --adapter=nextjs -- --spec ir/design.yaml
 flowgrid gen --adapter=nextjs -- --spec ir/design.yaml

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

@@ -9,12 +9,12 @@ disable-model-invocation: true
 **Owner:** bộ code (`--type=fe`)
 
 ```bash
-npm run codegen:unit:dry -- --id W-AD-AUTH-001
-npm run codegen:unit -- --id W-AD-AUTH-001
+npm run codegen:unit:dry -- --id W-ADM-AUTH-01
+npm run codegen:unit -- --id W-ADM-AUTH-01
 
 # Fallback direct CLI if wrappers missing:
-flowgrid unit-gen:dry --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
-flowgrid unit-gen --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
+flowgrid unit-gen:dry --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-ADM-AUTH-01
+flowgrid unit-gen --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-ADM-AUTH-01
 flowgrid unit-registry --adapter=nuxt4
 ```
 

package/harness/shared/SSOT_AGENT_PROTOCOL.md

@@ -4,7 +4,7 @@
 > These are **PHYSICAL INTERLOCKS**, not casual reminders.
 > Any violation of these laws → run **FAILED**. Chat-only "done" = **STRICTLY REJECTED**.
 >
-> Path SSOT: `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment).
+> Path SSOT: `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment). Product IDs: `product-id-convention.md` (`surfaceCode`, `CMP-{SURF}-{DOMAIN}-{NN}`, `W-{SURF}-{DOMAIN}-{NN}`).
 
 ---
 

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

@@ -4,7 +4,7 @@ Hub SSOT: `docs/workflows/test.md#grill-scenario-flow`.
 
 ## Scope
 
-- Docs **`FLOW-*.md`** exists (Phase 0 / business-process) — **no SC without FLOW**
+- Docs **`FLOW-*.md`** exists (Phase 0 / user-flow) — **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)
 
@@ -36,4 +36,4 @@ Hub SSOT: `docs/workflows/test.md#grill-scenario-flow`.
 - [ ] 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.
+Handoff thin FLOW → `/docs-hub /user-flow` or `/update-spec` — not tests hub.

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

@@ -21,12 +21,12 @@ query a workspace-parent graph.
 
 ## Target / ID Resolution Rule
 
-- User prompt MAY specify a screen ID, module ID, or short slug (e.g. `W-AD-AUTH-001`, `CMP-ADM-000`, `login`).
+- User prompt MAY specify a screen ID, module ID, or short slug (e.g. `W-ADM-AUTH-01`, `CMP-ADM-AUTH-01`, `login`).
 - **[MANDATORY]** Agent MUST use `flowgrid_docs_route` or `flowgrid_docs_get_element` (or glob search under `FLOWGRID_DOCS_ROOT` / `surfaces/...`) to resolve target paths.
 - **[MANDATORY]** Read the entire function **`*.bundle.yaml`** (sibling of `ir/`). Cross-reference plans against bundle `userStories`, `acceptanceCriteria`, `spec.ui`, and `design.*` — not split IR files.
 - If scenarios/acceptance are thin or missing → hand off docs-hub `/update-spec` or `/spec` (paste-ready prompt). Do not patch bundle from tests hub.
 - **[STRICTLY FORBIDDEN]** Do NOT read generated `*.md`.
-- If auditing **SC-***, the YAML/MD path MUST mirror the docs `FLOW-*.md` (cluster/module/surface `common/processes/` or `architecture/03-business-process/`). Flag `scenarios/auth/…` or `common/` leftovers.
+- If auditing **SC-***, the YAML/MD path MUST mirror the docs `FLOW-*.md` (cluster/module/surface `common/user-flows/` or `architecture/03-user-flows/`). Flag `scenarios/auth/…` or `common/` leftovers.
 
 ## Audit Rules
 

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

@@ -13,7 +13,7 @@ disable-model-invocation: true
 
 Author cross-flow scenarios (SC) on the current tests hub. Design rules stay on the docs hub.
 
-Scenarios test a **business process** (`FLOW-*`) that spans multiple screens (`W-*`) or modules. They mirror the docs FLOW file **after** bộ docs LCA `common/` placement (not a flat `common/` tree).
+Scenarios test a **user flow** (`FLOW-*`) that spans multiple screens (`W-*`) or modules. They mirror the docs FLOW file **after** bộ docs LCA `common/` placement (not a flat `common/` tree).
 
 ## Output Rules
 
@@ -30,12 +30,12 @@ Scenarios test a **business process** (`FLOW-*`) that spans multiple screens (`W
 
 - **[MANDATORY]** Agent MUST locate the **`FLOW-*.md`** file on the docs hub (`FLOWGRID_DOCS_ROOT`) via `flowgrid_docs_route` / `flowgrid_docs_get_element` / glob. Filenames are `FLOW-…md`, not `flow-*`.
 - Search in this order (same LCA as bộ docs `common-scope.md`):
-  1. `surfaces/<surface>/<CMP-id>/<NN>/common/processes/FLOW-*.md` (cluster)
-  2. `surfaces/<surface>/<CMP-id>/common/processes/FLOW-*.md` (module)
-  3. `surfaces/<surface>/common/processes/FLOW-*.md` (surface)
-  4. `surfaces/common/processes/FLOW-*.md` (cross-surface product common)
-  5. `architecture/03-business-process/FLOW-*.md` (org catalog only)
-- **Strict:** Only author a scenario if that `FLOW-*.md` exists. Missing FLOW or thin business rules → hand off to docs-hub `/business-process` or `/update-spec`, do not invent SC. **[MANDATORY]** When handing off, you MUST output a comprehensive gap report (formatted as a complete, ready-to-use prompt starting with `/docs-hub`) detailing exactly what flows or business rules are missing, so the user can copy-paste it directly to run the docs-hub skill.
+  1. `surfaces/<surface>/<CMP-id>/<NN>/common/user-flows/FLOW-*.md` (cluster)
+  2. `surfaces/<surface>/<CMP-id>/common/user-flows/FLOW-*.md` (module)
+  3. `surfaces/<surface>/common/user-flows/FLOW-*.md` (surface)
+  4. `surfaces/common/user-flows/FLOW-*.md` (cross-surface product common)
+  5. `architecture/03-user-flows/FLOW-*.md` (org catalog only)
+- **Strict:** Only author a scenario if that `FLOW-*.md` exists. Missing FLOW or thin business rules → hand off to docs-hub `/user-flow` or `/update-spec`, do not invent SC. **[MANDATORY]** When handing off, you MUST output a comprehensive gap report (formatted as a complete, ready-to-use prompt starting with `/docs-hub`) detailing exactly what flows or business rules are missing, so the user can copy-paste it directly to run the docs-hub skill.
 - **[STRICTLY FORBIDDEN]** Do not treat `common/yaml/` or `common/patterns/` as scenario sources.
 
 ## Directory Mirroring Rule (Docs SSOT)
@@ -44,13 +44,13 @@ Mirror the FLOW file path onto the tests hub. Strip **only** these prefixes:
 
 | Docs FLOW path | Tests hub |
 |----------------|-----------|
-| `surfaces/<rest>/common/processes/FLOW-checkout.md` | `scenarios/<rest>/common/processes/FLOW-checkout/SC-*.yaml` |
-| `architecture/03-business-process/FLOW-checkout.md` | `scenarios/architecture/03-business-process/FLOW-checkout/SC-*.yaml` |
+| `surfaces/<rest>/common/user-flows/FLOW-checkout.md` | `scenarios/<rest>/common/user-flows/FLOW-checkout/SC-*.yaml` |
+| `architecture/03-user-flows/FLOW-checkout.md` | `scenarios/architecture/03-user-flows/FLOW-checkout/SC-*.yaml` |
 
 Examples:
 
-- Docs `surfaces/admin/CMP-ADM-002/02/common/processes/FLOW-checkout.md` → `scenarios/admin/CMP-ADM-002/02/common/processes/FLOW-checkout/SC-*.yaml`
-- Docs `surfaces/admin/CMP-ADM-002/common/processes/FLOW-onboard.md` → `scenarios/admin/CMP-ADM-002/common/processes/FLOW-onboard/SC-*.yaml`
+- Docs `surfaces/admin/CMP-ADM-ORD-01/02/common/user-flows/FLOW-checkout.md` → `scenarios/admin/CMP-ADM-ORD-01/02/common/user-flows/FLOW-checkout/SC-*.yaml`
+- Docs `surfaces/admin/CMP-ADM-ORD-01/common/user-flows/FLOW-onboard.md` → `scenarios/admin/CMP-ADM-ORD-01/common/user-flows/FLOW-onboard/SC-*.yaml`
 
 Do **not** flatten to `scenarios/auth/…`. Do **not** use `common/` (legacy). Keep numeric cluster folders (`02/`) in the tests path.
 

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

@@ -49,9 +49,9 @@ disable-model-invocation: true
 ## Rule: Directory Mirroring (Docs SSOT)
 
 - **[MANDATORY]** Mirror function folder: `cases/<relative-path>/TC-*.yaml`.
-  - ✅ `surfaces/admin/CMP-ADM-002/02/01/login/` → `cases/admin/CMP-ADM-002/02/01/login/TC-*.yaml`
+  - ✅ `surfaces/admin/CMP-ADM-ORD-01/02/01/login/` → `cases/admin/CMP-ADM-ORD-01/02/01/login/TC-*.yaml`
   - ❌ `cases/admin/auth/W-…` — invented path not matching docs structure.
-- Cross-flow plans → `/scenario` (mirror `common/processes/FLOW-*` or `architecture/03-business-process/FLOW-*`).
+- Cross-flow plans → `/scenario` (mirror `common/user-flows/FLOW-*` or `architecture/03-user-flows/FLOW-*`).
 
 ---