@shanyucoder/flowgrid 0.1.9 → 0.1.10

package/harness/docs/extracts/tpl-module.md

@@ -1,45 +1,14 @@
-# Module README template
+# Module index template
 
-Path: `surfaces/<surface>/CMP-{NN}-{slug}/index.md` — **MD only** (yaml under `<function-slug>/code/`).
+Path: `surfaces/<surface>/CMP-{NN}-{slug}/index.md` — **MD only**.
 
-```markdown
-# CMP-{NN} — Name
+Copy from: `templates/project-skeleton/surfaces/_module-index.template.md`
 
-Lead-assigned module. **This README is MD-only** (no YAML).
+Required sections (English keys — `flowgrid audit hub-prd`):
 
-Owns …
+- `## Goals` {#goals}
+- `## Scope` {#scope} — In scope / Out of scope
+- `## Features overview` {#features-overview}
+- `## Depends on` {#depends-on}
 
-## Out of scope (module)
-
-- [Chức năng / CMP khác giữ SSOT — không copy bundle vào module này]
-- [Hạ tầng / deployment — `architecture/`]
-
-## Depends on
-
-| ID / artifact | Lý do |
-| --- | --- |
-| `CMP-…` / `FLOW-…` | [Upstream data hoặc quy trình] |
-| `API-…` | [Contract reuse — link `01-backend-spec`] |
-
-| | |
-|--|--|
-| **ID** | `CMP-{NN}` |
-| **Business Process** | Module/cluster: `…/common/processes/FLOW-…`. Catalog: [`architecture/03-business-process/`](/architecture/03-business-process/) |
-| **Functions** | `<function-slug>`, … |
-| **Screens** | `W-…` |
-| **APIs** | `API-…` |
-
-\`\`\`mermaid
-flowchart LR
-  CMP[CMP-{NN}]
-  W[W-…]
-  API[API-…]
-  CMP --> W
-  CMP --> API
-\`\`\`
-
-## Code paths
-
-- [`<function-slug>/code/W-…/`](./<function-slug>/code/W-…/)
-- [`<function-slug>/code/API-…/`](./<function-slug>/code/API-…/)
-```
+Prose: `docs-hub.locale.yaml` → `contentLocale`. No Personas / Success metrics tables on hub.

package/harness/docs/extracts/tpl-overview-prd.md

@@ -0,0 +1,11 @@
+# Overview PRD headings (English keys — audit hub-prd)
+
+Required on `overview/index.md`:
+
+- `## Goals` {#goals}
+- `## Background` {#background}
+- `## Scope` {#scope} with in-scope / out-of-scope bullets
+
+Prose language: `docs-hub.locale.yaml` → `contentLocale` (BCP-47 tag, e.g. `vi`, `en`, `ja`).
+
+Forbidden hub sections: Personas tables, Success metrics (manage outside hub).

package/harness/docs/extracts/tpl-risk-register.md

@@ -0,0 +1,28 @@
+# Risk register — format (SSOT duy nhất)
+
+**File:** `architecture/11-risks/risk-register.md`  
+**Không** có `risks:` trên `*.bundle.yaml` — audit spec báo `WARN_BUNDLE_RISKS_FORBIDDEN` nếu còn key đó.
+
+## Table: one row = one risk
+
+| ID | Type | Description | Limit | Need | Gap | Impact | Mitigation | Status |
+
+- **ID:** `RISK-<TOPIC>-<NNN>`
+- **Limit / Need:** counts + units (e.g. `500 emails/day` vs `~700 emails/day` peak)
+- **Gap:** `+200 (~40%)` or equivalent
+- **Status:** `Open` | `Watching` | `Closed` | `Accepted` (prose may use hub `contentLocale`)
+
+Ví dụ đầy đủ: xem dòng `RISK-QUOTA-EMAIL-001` trong skeleton `risk-register.md`.
+
+## Quick stats (top of file)
+
+Member cập nhật tay (tổng mở, có chênh quota, đã có phương án).
+
+## VitePress
+
+Trang MD trong Architecture → 11 Risks → **risk-register** (không render từ feature).
+
+## Audit & skill
+
+- `flowgrid audit risks architecture/11-risks/risk-register.md`
+- `/risk-register`

package/harness/docs/extracts/tpl-surface-prd.md

@@ -0,0 +1,7 @@
+# Surface index — English section keys
+
+Template: `templates/project-skeleton/surfaces/_surface-index.template.md`
+
+Required: `## Goals`, `## Background`, `## Scope`, CMP table, user flow links.
+
+Content: language from `docs-hub.locale.yaml` (`contentLocale`).

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

@@ -127,7 +127,7 @@ extractBundle: architecture-core
 ---
 ## 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 /user-flow FLOW-checkout` — map a legacy flow
 ```
 
 ---

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

@@ -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`)
@@ -152,7 +152,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 +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.
-- [ ] `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

@@ -31,7 +31,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/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

@@ -26,7 +26,7 @@ query a workspace-parent graph.
 - **[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-002/02/common/user-flows/FLOW-checkout.md` → `scenarios/admin/CMP-ADM-002/02/common/user-flows/FLOW-checkout/SC-*.yaml`
+- Docs `surfaces/admin/CMP-ADM-002/common/user-flows/FLOW-onboard.md` → `scenarios/admin/CMP-ADM-002/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

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

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

@@ -20,28 +20,28 @@ coverage_plan:
 Scenario thuộc **CMP-01-auth** · Tính năng năng lực **CAP-AUTH-001**.  
 Quy tắc chi tiết và schema cơ sở dữ liệu tham chiếu tại **Docs Hub** (cite ID: `spec.yaml`).
 
-| Thuộc tính | Giá trị |
-|---|---|
+| Attribute | Value |
+| --- | --- |
 | **Scenario ID** | `SC-EXAMPLE` |
 | **Module** | `CMP-01-auth` |
-| **Bề mặt (Surface)** | `admin` |
-| **Màn hình (Screen)** | `W-AD-AUTH-001` (`/admin/records/create`) |
-| **Mức độ ưu tiên** | `High` |
+| **Surface** | `admin` |
+| **Screen** | `W-AD-AUTH-001` (`/admin/records/create`) |
+| **Priority** | `High` |
 
-## 1. Bối Cảnh Nghiệp Vụ & Phân Tích Rủi Ro (Business Context & Risk Analysis)
+## 1. Business context & risk analysis
 
 Màn hình khởi tạo hồ sơ là cửa ngõ dữ liệu tài chính của khách hàng. Nếu bỏ sót kiểm tra trùng mã hoặc không xử lý chặn click đúp (double-submit), hệ thống sẽ tạo các bản ghi rác gây xung đột số liệu doanh thu và vi phạm tính toàn vẹn dữ liệu kế toán.
 
-## 2. Hành Vi Chuẩn BDD (Behavior: Given / When / Then)
+## 2. BDD behavior (Given / When / Then)
 
 - **Given (Tiền điều kiện):** Người dùng đăng nhập thành công với vai trò Quản trị viên (`ADMIN`), tài khoản có quyền `records.create`, và chưa tồn tại bản ghi nào có mã `REC-2026-001` trong cơ sở dữ liệu.
 - **When (Thao tác):** Người dùng nhập đầy đủ các trường thông tin hợp lệ (mã hồ sơ, tên hồ sơ, chọn gói dịch vụ) và nhấn nút "Lưu & Xác Nhận".
 - **Then (Hậu điều kiện):** Hệ thống khóa nút để tránh gửi trùng lặp, gửi request kèm header `X-Idempotency-Key`, tạo mới bản ghi thành công trong bảng `records`, hiển thị Toast thông báo màu xanh và điều hướng sang màn hình chi tiết `W-ADM-DETAIL-01`.
 
-## 3. Ma Trận Test Phân Hoạch Tương Đương & Phân Tích Giá Trị Biên (Equivalence Partitioning & Boundary Test Matrix - IEEE 29119)
+## 3. Equivalence & boundary test matrix
 
-| Mã Case (Case ID) | Khía Cạnh Kiểm Thử (Facet) | Dữ Liệu Đầu Vào (Input Data) | Kết Quả Mong Đợi (Expected Outcome) | HTTP Status & UI State | Tự Động Hóa (Automation Case) |
-|---|---|---|---|---|---|
+| Case ID | Facet | Input | Expected outcome | HTTP & UI | Automation case |
+| --- | --- | --- | --- | --- | --- |
 | **TC-VAL-01** | `positive_boundary` (Biên tối thiểu) | `code: "REC01"` (5 chars), `name: "Hồ sơ A"` | Form hợp lệ, gửi dữ liệu thành công | `HTTP 200` · Toast Success xanh | `TC-EXAMPLE-VALID` |
 | **TC-VAL-02** | `positive_boundary` (Biên tối đa) | `code: "REC-2026-MAXIMUM-001"` (20 chars) | Form hợp lệ, gửi dữ liệu thành công | `HTTP 200` · Toast Success xanh | `TC-EXAMPLE-VALID` |
 | **TC-VAL-03** | `negative_length` (Dưới độ dài min) | `code: "REC"` (3 chars) | Chặn submit, báo lỗi inline dưới ô nhập | `Client Error` · "Độ dài từ 5 đến 20 ký tự" | `TC-EXAMPLE-INVALID` |
@@ -50,10 +50,10 @@ Màn hình khởi tạo hồ sơ là cửa ngõ dữ liệu tài chính của kh
 | **TC-ACT-06** | `concurrency_double_submit` | Click nút "Lưu" liên tục 2 lần trong 100ms | Nút khóa disabled tức thì, chỉ 1 request gửi đi | `UI Locked` · Không tạo 2 bản ghi trùng | `TC-EXAMPLE-CONCURRENCY` |
 | **TC-SYS-07** | `network_interruption` (Mất mạng) | Ngắt kết nối mạng ngay khi gửi request | Hiện banner cảnh báo mất kết nối, giữ nguyên dữ liệu form | `Network Banner` · Form state preserved | `TC-EXAMPLE-OFFLINE` |
 
-## 4. Bao Phủ Rủi Ro & Khía Cạnh Chất Lượng (Quality Dimensions Coverage)
+## 4. Quality dimensions coverage
 
-| Khía Cạnh (Dimension) | Mức Độ Bao Phủ | Ghi Chú Đảm Bảo Chất Lượng |
-|---|---|---|
+| Dimension | Coverage | Notes |
+| --- | --- | --- |
 | **Happy Path & Workflow** | 100% | Toàn bộ luồng khởi tạo đến xem chi tiết hoàn tất |
 | **Boundary Value Analysis** | 100% | Kiểm thử đầy đủ tại ngưỡng min-1, min, max, max+1 |
 | **Data Integrity & Concurrency** | 100% | Kiểm tra unique mã hồ sơ qua async DB & chặn double-click |
@@ -75,10 +75,10 @@ stateDiagram-v2
   ChuyenTrangChiTiet --> [*]
 ```
 
-## 5. Danh Sách Test Cases Chi Tiết (Test Cases Mapping)
+## 5. Test case mapping
 
-| Mã Case (ID) | Khía Cạnh | Mức Độ Ưu Tiên | Thư Mục Test Hub |
-|---|---|---|---|
+| Case ID | Facets | Priority | Tests hub path |
+| --- | --- | --- | --- |
 | `TC-EXAMPLE-VALID` | happy, boundary | Critical | `cases/admin/CMP-01-auth/01/create/` |
 | `TC-EXAMPLE-INVALID` | validation, boundary | High | `cases/admin/CMP-01-auth/01/create/` |
 | `TC-EXAMPLE-DUPLICATE` | concurrency, remote_unique | High | `cases/admin/CMP-01-auth/01/create/` |

package/lexicon/registry-tags.en.txt

@@ -127,7 +127,7 @@ PII / Sensitive / Masked
 K. Business architecture — process hierarchy & synonyms
 ================================================================================
 Business Capability
-Business Process
+User flow
 End-to-End Flow / E2E Flow
 Use Case
 Scenario
@@ -138,7 +138,7 @@ Cross-Service Flow / Service Orchestration / Service Choreography
 Saga Flow / Distributed Transaction
 Domain Workflow / Event Flow / Command Flow
 #process: business-capability
-#process: business-process
+#process: user-flow
 #process: e2e-flow
 #process: use-case
 #process: scenario

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shanyucoder/flowgrid",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Unified Local MCP Toolkit (Graph, DNA, Docs, Test, Codegen)",
   "type": "module",
   "main": "./dist/index.js",

package/templates/project-skeleton/architecture/03-business-process/index.md

@@ -0,0 +1,3 @@
+# Deprecated path
+
+Use [`../03-user-flows/`](../03-user-flows/) for new hubs. Files here are legacy copies only.