@shanyucoder/flowgrid 0.1.8 → 0.1.10

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/schemas/flowgrid-docs/qa-item.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://platform.local/schemas/flowgrid-docs/qa-item.schema.json",
+  "title": "FlowGrid QA inbox item",
+  "type": "object",
+  "required": ["schema", "id", "status", "target", "updates"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "flowgrid-qa-item/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Z0-9][A-Z0-9._-]*_\\d{4}$"
+    },
+    "screen": { "type": "string" },
+    "bundleId": { "type": "string" },
+    "status": { "type": "string", "enum": ["open", "closed"] },
+    "kind": {
+      "type": "string",
+      "enum": ["customer", "choice", "tech-debt", "integration", "coverage"]
+    },
+    "skill": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "target": {
+      "type": "object",
+      "required": ["path", "at"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string" },
+        "at": { "type": "string" }
+      }
+    },
+    "options": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["label"],
+        "properties": {
+          "label": { "type": "string" },
+          "recommended": { "type": "boolean" }
+        }
+      }
+    },
+    "updates": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/update" }
+    }
+  },
+  "$defs": {
+    "update": {
+      "type": "object",
+      "required": ["at", "kind", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "at": { "type": "string", "pattern": "^\\d{8} \\d{2}:\\d{2}$" },
+        "by": { "type": "string" },
+        "kind": { "type": "string", "enum": ["question", "answer", "review", "note"] },
+        "text": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

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/api-spec/SKILL.md

@@ -110,7 +110,7 @@ Use the **same** skill (`/api-spec`) and same trio layout when there is no porta
 - **[MANDATORY]** Set `feature.source.kind`, `base: none`, `integrationRefs[]` (or equivalent refs), empty `portalRefs`, `contexts.portalLayout: none`, and `contexts.auth` (API key / HMAC / OAuth).
 - **[MANDATORY]** Domain tags: `#webhook-inbound`, `#webhook-outbound`, `#partner-api`, `#public-api`, `#call-external`, `#err:*` (include `#err:signature-invalid`, `#err:rate-limit`, `#err:unauthorized` when relevant).
 - **[MANDATORY]** Scan sibling `…/api/<seq>/` and surface `common/yaml/` before creating new endpoints; reuse via `#reuse-api` when applicable.
-- **[STRICTLY FORBIDDEN]** Do not invent HMAC secrets or partner validation logic; use AskQuestion or `qa/open/` tech debt.
+- **[STRICTLY FORBIDDEN]** Do not invent HMAC secrets or partner validation logic; use AskQuestion or `qa/` tech debt.
 
 ---
 

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

@@ -66,7 +66,7 @@ Shared extracts: `api-spec-sync.md`, `spec-evolution.md`, `entity-relationship.m
 
 ## Done Criteria
 
-- Portal delta in `01`; or if deferred: `pendingTechDebt` with `id: QA-<feature.id>-NNNN` + `qa/open/` file.
+- Portal delta in `01`; or if deferred: `pendingTechDebt` with `id: QA-<feature.id>-NNNN` + `qa/` file.
 - `source.portalRefs` current.
 - `changeLog` + version bumped.
 - Handoff: `/grill-api-spec {slug}` (re-run gates + codegen tags).

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-bqa/SKILL.md

@@ -32,7 +32,7 @@ disable-model-invocation: true
   - `<pageType>` from `gen.codegen.profile` when set; else infer from prompt (list | create | detail | auth | admin-crud | …) — same table as `docs/workflows/grill-and-human-review.md`.
   - If profile unknown → AskQuestion to lock profile **before** audit (do not use `--type unknown`).
 - **[MANDATORY]** Consume `gaps[]` (patch bundle) and `confirms[]` (AskQuestion with `(Recommended)` from audit): `CONFIRM_UX_*` + **`CONFIRM_DB_*`** (`db-audit-wizard.md`).
-- **[MANDATORY]** After any bundle patch in Step A or B: **re-run** `flowgrid audit spec` until structural `gaps[]` empty or deferred via `qa/open/QA-<bundle.id>-NNNN.yaml`.
+- **[MANDATORY]** After any bundle patch in Step A or B: **re-run** `flowgrid audit spec` until structural `gaps[]` empty or deferred via `qa/<SHORT>_NNNN.yaml`.
 - **[RECOMMENDED]** Resolve `warnings[]` (placeholders, missing metrics/non-goals) when BQA has answers; sync `userStories` if UX copy changed.
 - **[MANDATORY]** After reconcile: `flowgrid split` + `flowgrid render` — stakeholder review uses `ir/generated/spec.md`.
 - **[STRICTLY FORBIDDEN]** Skip audit and rely on manual zone review only.
@@ -44,7 +44,7 @@ disable-model-invocation: true
 - **[MANDATORY]** For `#missing_info` / open gaps: re-check ArtifactGraph → micro-scope → evaluate total gap volume:
   - **Small Scope (≤5 questions):** `AskQuestion` wizard in chat thread — **one question at a time**, **≥3 options**: (1) `(Recommended)`, (2) `Other` (free text), (3) `Log as Tech Debt (Pending)`.
   - **Large Scope (≥10 gaps):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 gaps per phase) with disk offloading at boundaries.
-- **[MANDATORY]** If member selects "Log as Tech Debt" → create `qa/open/QA-<bundle.id>-NNNN.yaml`. Close later with `/qa-resolve`.
+- **[MANDATORY]** If member selects "Log as Tech Debt" → copy from `.flowgrid/templates/qa-item.yaml` per `qa-authoring.md`; create `qa/<SHORT>_NNNN.yaml`. Close later with `/qa-resolve`.
 - **[STRICTLY FORBIDDEN]** Never write `openQuestions` in YAML. Never silently overwrite settled SSOT without explicit confirmation.
 
 ---

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

@@ -54,7 +54,7 @@ disable-model-invocation: true
   → **Proactively brainstorm** logical suggestions from business context in Vietnamese (e.g. login page → suggest `module: auth, entity: user`).
   - **Small Scope (≤5 questions):** Trigger `AskQuestion` wizard — **one question at a time**, ≥3 options: (1) `(Recommended)`, (2) `Other` (free text), (3) `Log as Tech Debt (Pending)`. Wait for member answer before showing next question.
   - **Large Scope (≥10 gaps/endpoints):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 endpoints/gaps per phase) with disk offloading at boundaries.
-  - ✅ If member selects "Log as Tech Debt" → create `qa/open/QA-<bundle.id>-NNNN.yaml`; maintain `grillStatus.dev: pending`.
+  - ✅ If member selects "Log as Tech Debt" → create `qa/<SHORT>_NNNN.yaml`; maintain `grillStatus.dev: pending`.
   - ❌ Do NOT set `grillStatus.dev: done` until profile + entity/module + endpoint actions are all verified and confirmed.
 
 ---

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

@@ -42,7 +42,7 @@ 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.
+  - Patch structural `gaps[]`; defer remainder via `qa/` 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.
 
@@ -81,6 +81,6 @@ disable-model-invocation: true
 
 ## Verification Checklist
 
-- [ ] Conflicts reconciled in `*.bundle.yaml`, or deferred with `qa/open/QA-…`. No `openQuestions`.
+- [ ] Conflicts reconciled in `*.bundle.yaml`, or deferred with `qa/<SHORT>_…`. No `openQuestions`.
 - [ ] `bundle.gen.codegen.profile` present and correct.
 - [ ] `flowgrid audit spec` re-run after reconcile; `flowgrid split` succeeded with zero errors.

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/qa-resolve/SKILL.md

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

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

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

package/harness/docs/skills/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

@@ -26,7 +26,7 @@ disable-model-invocation: true
   - **Small Scope (≤5 gaps):** Run `AskQuestion` wizard — **one question at a time**, **≥3 options**: (1) `(Recommended)`, (2) Alternative, (3) `Log as Tech Debt (Pending)`. Show next question only after member answers current one.
   - **Large Scope (≥10 gaps OR multi-screen scope):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into Phases (3–5 questions/fields per phase) to prevent session token overflow.
   - ❌ Never invent, assume, or silently skip missing fields.
-- **[MANDATORY]** If member chooses "Log as Tech Debt" → create `qa/open/QA-<page-id>-NNNN.yaml` + tag `#missing_info QA-…`. Do not block on it.
+- **[MANDATORY]** If member chooses "Log as Tech Debt" → read `.flowgrid/templates/qa-item.yaml` + `qa-authoring.md`; create `qa/<SHORT>_NNNN.yaml` (`schema: flowgrid-qa-item/v1`) + tag `#missing_info <id>`. Do not block on it.
 - **[RECOMMENDED]** Brainstorm business text (context, input, output, screen descriptions) proactively in Vietnamese for Non-tech audience — do not wait to be told.
 
 ---
@@ -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/update-spec/SKILL.md

@@ -27,7 +27,7 @@ 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`. Production code → NOT this skill.
+- **[STRICTLY FORBIDDEN]** Full rewrite → `/spec`. Close `qa` item → `/qa-resolve`. Production code → NOT this skill.
 - **[MANDATORY]** Legacy re-mine / trace lại từ code cũ: dùng **`/legacy /spec`** (adopt lại) hoặc **`/update-spec`** với delta `legacy` / `legacyEvidence` + `#update:*` — **không** skill riêng.
 
 ---
@@ -37,7 +37,7 @@ Doc hub: `platform/toolchain/UPDATE-SPEC-FLOW.md` · `platform/toolchain/FEATURE
 - **[MANDATORY]** Gaps or ambiguity regarding delta scope, evaluate total gap volume:
   - **Small Scope (≤5 questions):** Trigger `AskQuestion` wizard — one question at a time, **≥3 options**: (1) `(Recommended)`, (2) `Other`, (3) `Log as Tech Debt (Pending)`.
   - **Large Scope (≥10 gaps):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 gaps per phase) with disk offloading at boundaries.
-  - ✅ If "Log as Tech Debt" is selected → create `qa/open/` entry; do not invent business data.
+  - ✅ If "Log as Tech Debt" is selected → create `qa/` entry; do not invent business data.
   - ❌ Never invent delta scope or novel business fields without explicit user confirmation.
 - Path SSOT: `surfaces/<surface>/CMP-*/<slug>/` — NO `modules/` segment.
 

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/extracts/wire-audit-loop.md

@@ -47,7 +47,7 @@ Re-run **entire chain** after fixes in any lane (code, plan, or spec).
 | 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 |
+| Intentional defer | docs | `qa` + `QA-*` / `coverage_deferred` on SC |
 
 **Forbidden:** patch `ir/*` or `01` from FE repo; invent AC on tests hub; skip `audit e2e` because manual QA passed.
 

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-wire/SKILL.md

@@ -54,7 +54,7 @@ Re-run full chain after downstream lanes fix gaps.
 | UX/spec/AC wrong vs observed behaviour | docs-hub `/update-spec` (paste-ready prompt per `grill-testcase` rule) |
 | `FEBE_*`, wrong endpoint/field on `01` | docs-hub `/api-update` → BE `/audit-api` → member re-runs `/wire` |
 | `SC_SCREEN_NO_TC` | tests-hub `/testcase` or `/scenario` |
-| Defer only | `qa/open` + team policy |
+| Defer only | `qa` + team policy |
 
 - **[STRICTLY FORBIDDEN]** Close `#update:*` / `#wire-only` here — only `/wire` after spec merge confirms.
 - **[STRICTLY FORBIDDEN]** Run `/api` codegen or full product regression from this skill.