@shanyucoder/flowgrid 0.1.8 → 0.1.10

package/engines/docs/vitepress/config.ts

@@ -115,7 +115,7 @@ function getOverviewSidebar(root: string, docsDir: string, prefix: string) {
 }
 
 function getBusinessProcessSidebarItems(root: string, prefix: string) {
-  const processDir = path.join(root, prefix.replace(/^\//, ''), '03-business-process')
+  const processDir = path.join(root, prefix.replace(/^\//, ''), '03-user-flows')
   if (!fs.existsSync(processDir)) return []
   try {
     const entries = fs.readdirSync(processDir, { withFileTypes: true })
@@ -129,7 +129,7 @@ function getBusinessProcessSidebarItems(root: string, prefix: string) {
         title = markdownNavText(entry.name, content) || nameWithoutExt
         items.push({
           text: title,
-          link: `${prefix}/03-business-process/${nameWithoutExt}`
+          link: `${prefix}/03-user-flows/${nameWithoutExt}`
         })
       }
     }
@@ -399,10 +399,10 @@ export default () => {
               { text: '01 Introduction', link: `${archPrefix}/01-introduction/` },
               { text: '02 Constraints', link: `${archPrefix}/02-constraints/` },
               {
-                text: '03 Business Processes',
+                text: '03 Luồng người dùng',
                 collapsed: true,
                 items: [
-                  { text: 'Catalog', link: `${archPrefix}/03-business-process/` },
+                  { text: 'Catalog', link: `${archPrefix}/03-user-flows/` },
                   ...getBusinessProcessSidebarItems(projectRoot, archPrefix),
                 ],
               },

package/engines/spec/lib/audit-bundle-gaps.mjs

@@ -546,12 +546,12 @@ function auditBundleContent(rawText, filePath, pageType) {
   // Quality warnings (non-blocking — does not affect totalGaps for structure)
   // =========================================================================
 
-  if (!has(rawText, 'successMetrics:')) {
+  if (!has(rawText, 'scopeIn:')) {
     addWarning(
-      'WARN_NO_SUCCESS_METRICS',
-      'successMetrics',
-      'successMetrics not declared — add when PO has measurable or qualitative targets.',
-      'Declare successMetrics: | with 1–3 bullets (see bundle-authoring.md).'
+      'WARN_NO_SCOPE_IN',
+      'scopeIn',
+      'scopeIn not declared — generated spec.md missing “Trong phạm vi” (PRD in-scope).',
+      'Declare scopeIn: | with bullets for what this screen/feature includes.'
     );
   }
 
@@ -559,8 +559,39 @@ function auditBundleContent(rawText, filePath, pageType) {
     addWarning(
       'WARN_NO_NON_GOALS',
       'nonGoals',
-      'nonGoals not declared — clarify out-of-scope for this screen/phase.',
-      'Declare nonGoals: | with explicit non-scope bullets.'
+      'nonGoals not declared — generated spec.md missing “Ngoài phạm vi” (PRD out-of-scope).',
+      'Declare nonGoals: | with explicit out-of-scope bullets.'
+    );
+  }
+
+  if (!has(rawText, 'nfr:')) {
+    addWarning(
+      'WARN_NO_NFR',
+      'nfr',
+      'nfr not declared — generated spec.md missing non-functional section (perf/security).',
+      'Declare nfr: | or link architecture/08-cross-cutting in prose.'
+    );
+  }
+
+  const multiScreen =
+    has(rawText, 'nextScreenOnSuccess') ||
+    has(rawText, 'contextualAction') ||
+    has(rawText, 'sourceScreen:');
+  if (multiScreen && !has(rawText, 'userFlows:')) {
+    addWarning(
+      'WARN_NO_USER_FLOWS',
+      'userFlows',
+      'Màn có handoff / multi-screen nhưng chưa khai báo luồng người dùng (userFlows).',
+      'Declare userFlows: | — link FLOW-* hoặc mô tả journey ngắn.'
+    );
+  }
+
+  if (has(rawText, 'risks:')) {
+    addWarning(
+      'WARN_BUNDLE_RISKS_FORBIDDEN',
+      'risks',
+      'Rủi ro không ghi trên feature bundle — SSOT chỉ `architecture/11-risks/risk-register.md`.',
+      'Xóa key `risks:` khỏi bundle; thêm dòng vào risk-register.md (`RISK-*`). Dùng `/risk-register`.'
     );
   }
 

package/engines/spec/lib/audit-flow-gaps.mjs

@@ -2,8 +2,8 @@
 
 /**
  * audit-flow-gaps.mjs
- * Zero-dependency static audit script for FlowGrid Business Process markdown files (FLOW-*.md).
- * Ensures 100% adherence to the 6-section business process standard and background logic rules.
+ * Zero-dependency static audit script for FlowGrid User flow markdown files (FLOW-*.md).
+ * Ensures 100% adherence to the 6-section user flow standard and background logic rules.
  */
 
 import fs from 'fs';

package/engines/spec/lib/bundle-schema.mjs

@@ -12,8 +12,10 @@ export const BUNDLE_META_KEYS = [
   'status',
   'owner',
   'summary',
-  'successMetrics',
+  'scopeIn',
   'nonGoals',
+  'userFlows',
+  'nfr',
   'userStories',
   'specOrigin',
   'grillStatus'

package/engines/spec/lib/open-qa.mjs

@@ -2,11 +2,20 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { parse } from 'yaml'
 
-/** Walk up from a bundle dir to the docs hub (`qa/open` or `architecture/`). */
+function qaDirHasFiles(qaDir) {
+  if (!existsSync(qaDir)) return false
+  for (const name of readdirSync(qaDir)) {
+    if (/\.ya?ml$/i.test(name)) return true
+    if (name === 'open' && existsSync(path.join(qaDir, 'open'))) return true
+  }
+  return existsSync(path.join(qaDir, 'index.md'))
+}
+
+/** Walk up from a bundle dir to the docs hub (`qa/` or `architecture/`). */
 export function findDocsHubRoot(fromDir) {
   let dir = path.resolve(fromDir)
   for (let i = 0; i < 40; i++) {
-    if (existsSync(path.join(dir, 'qa', 'open')) || existsSync(path.join(dir, 'architecture'))) {
+    if (existsSync(path.join(dir, 'architecture')) || qaDirHasFiles(path.join(dir, 'qa'))) {
       return dir
     }
     const parent = path.dirname(dir)
@@ -16,32 +25,73 @@ export function findDocsHubRoot(fromDir) {
   return null
 }
 
-export function openQaCsv(hubRoot, bundleId) {
-  return getOpenQaDetails(hubRoot, bundleId).csv
+function listQaYamlPaths(hubRoot) {
+  const qaDir = path.join(hubRoot, 'qa')
+  const paths = []
+  if (!existsSync(qaDir)) return paths
+  for (const name of readdirSync(qaDir)) {
+    if (/\.ya?ml$/i.test(name)) paths.push(path.join(qaDir, name))
+  }
+  const openDir = path.join(qaDir, 'open')
+  if (existsSync(openDir)) {
+    for (const name of readdirSync(openDir)) {
+      if (/\.ya?ml$/i.test(name)) paths.push(path.join(openDir, name))
+    }
+  }
+  return paths
+}
+
+function qaAppliesToBundle(doc, stem, bundleId, bundlePath) {
+  if (stem.startsWith(`QA-${bundleId}-`)) return true
+  if (doc?.screen && String(doc.screen) === bundleId) return true
+  const tp = doc?.target?.path
+  if (tp && bundlePath) {
+    const base = path.basename(bundlePath)
+    if (String(tp).includes(base)) return true
+  }
+  return false
+}
+
+function isOpenQa(doc) {
+  if (doc?.status === 'closed') return false
+  if (doc?.status === 'open') return true
+  if (doc?.resolution) return false
+  return true
+}
+
+function questionLine(doc) {
+  if (typeof doc?.question === 'string' && doc.question.trim()) {
+    return doc.question.trim().split('\n')[0]
+  }
+  const updates = Array.isArray(doc?.updates) ? doc.updates : []
+  const q = updates.find((u) => u?.kind === 'question')
+  if (q?.text) return String(q.text).trim().split('\n')[0]
+  const last = updates[updates.length - 1]
+  if (last?.text) return String(last.text).trim().split('\n')[0]
+  return ''
+}
+
+export function openQaCsv(hubRoot, bundleId, bundlePath = '') {
+  return getOpenQaDetails(hubRoot, bundleId, bundlePath).csv
 }
 
-export function getOpenQaDetails(hubRoot, bundleId) {
+export function getOpenQaDetails(hubRoot, bundleId, bundlePath = '') {
   if (!hubRoot || !bundleId) return { csv: '', techDebt: [] }
-  const openDir = path.join(hubRoot, 'qa', 'open')
-  if (!existsSync(openDir)) return { csv: '', techDebt: [] }
-  const prefix = `QA-${bundleId}-`
   const ids = []
   const techDebt = []
-  for (const name of readdirSync(openDir)) {
-    if (!/\.ya?ml$/i.test(name)) continue
-    const stem = name.replace(/\.ya?ml$/i, '')
-    if (!stem.startsWith(prefix)) continue
-    let id = stem
-    let kind = ''
-    let question = ''
+  for (const full of listQaYamlPaths(hubRoot)) {
+    const stem = path.basename(full).replace(/\.ya?ml$/i, '')
+    let doc = {}
     try {
-      const parsed = parse(readFileSync(path.join(openDir, name), 'utf8'))
-      if (parsed && typeof parsed.id === 'string' && parsed.id.trim()) id = parsed.id.trim()
-      if (parsed && typeof parsed.kind === 'string') kind = parsed.kind
-      if (parsed && typeof parsed.question === 'string') question = parsed.question.trim().split('\n')[0]
+      doc = parse(readFileSync(full, 'utf8')) ?? {}
     } catch {
-      /* filename */
+      continue
     }
+    if (!isOpenQa(doc)) continue
+    if (!qaAppliesToBundle(doc, stem, bundleId, bundlePath)) continue
+    const id = typeof doc.id === 'string' && doc.id.trim() ? doc.id.trim() : stem
+    const kind = typeof doc.kind === 'string' ? doc.kind : ''
+    const question = questionLine(doc)
     ids.push(id)
     if (kind === 'tech-debt') {
       techDebt.push({ id, status: 'open', summary: question })
@@ -57,7 +107,7 @@ const QA_FIELD = 'Q&A'
 /** Set or remove `Q&A` on a business spec object (comma-separated ids). */
 export function applyOpenQaField(spec, bundlePath, bundleId) {
   const hub = findDocsHubRoot(path.dirname(path.resolve(bundlePath)))
-  const qa = getOpenQaDetails(hub, bundleId)
+  const qa = getOpenQaDetails(hub, bundleId, bundlePath)
   if (qa.csv) spec[QA_FIELD] = qa.csv
   else delete spec[QA_FIELD]
   if (qa.techDebt && qa.techDebt.length > 0) spec.pendingTechDebt = qa.techDebt

package/engines/testcase/runners/lib/resolve-hub-id.mjs

@@ -138,7 +138,7 @@ function absUnder(root, rel) {
 }
 
 function findFlowMarkdown(docsRoot, id) {
-  const catalog = path.join(docsRoot, 'architecture', '03-business-process', `${id}.md`)
+  const catalog = path.join(docsRoot, 'architecture', '03-user-flows', `${id}.md`)
   if (existsSync(catalog)) return catalog
   const hits = []
   const walk = (dir) => {
@@ -150,7 +150,7 @@ function findFlowMarkdown(docsRoot, id) {
         walk(p)
         continue
       }
-      if (ent.name === `${id}.md` && p.split(path.sep).join('/').includes('/common/processes/')) {
+      if (ent.name === `${id}.md` && p.split(path.sep).join('/').includes('/common/user-flows/')) {
         hits.push(p)
       }
     }
@@ -206,7 +206,7 @@ export function resolveHubId(repoRoot, id, mode = 'testcase') {
     const docsRoot = getDocsRoot()
     const md = findFlowMarkdown(docsRoot, id)
     if (!md) {
-      throw new Error(`Unknown FLOW ${id} — expected architecture/03-business-process/${id}.md or …/common/processes/${id}.md`)
+      throw new Error(`Unknown FLOW ${id} — expected architecture/03-user-flows/${id}.md or …/common/user-flows/${id}.md`)
     }
     notes.push(`flow markdown: ${path.relative(repoRoot, md)}`)
     return { kind: 'flow', id, paths: [md], notes }

package/harness/common/skills/legacy/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # /legacy — Legacy Context Modifier
 
-**Skill Modifier:** When a member uses `/legacy` alongside another specialized skill (e.g., `/legacy /spec`, `/legacy /overview`, `/legacy /business-process`), the Agent MUST enforce the following behavioral shifts.
+**Skill Modifier:** When a member uses `/legacy` alongside another specialized skill (e.g., `/legacy /spec`, `/legacy /overview`, `/legacy /user-flow`), the Agent MUST enforce the following behavioral shifts.
 
 ## Behavioral Shifts (Context Shift)
 
@@ -18,7 +18,7 @@ disable-model-invocation: true
    - **Tier 1 (Page / API Detail — `/legacy /spec`)**: 
      - ONLY audit internal page/API scope: Check **missing Validation** (field validation rules, max length, format regex...) and **Local Security** (e.g. Laravel `@csrf`, Auth guard/middleware on route, input sanitization).
      - Do NOT perform cross-system end-to-end vulnerability audits at this level.
-   - **Tier 2 (Cross-Flow / Business Process — `/legacy /business-process`, Module, Surface)**:
+   - **Tier 2 (Cross-Flow / User flow — `/legacy /user-flow`, Module, Surface)**:
      - Audit **End-to-End Business Flow Gaps**: Check data/status misalignment between Step 1 (Screen 1) and Step 2 (Screen 2), orphan APIs/steps, broken flow steps, and missing rollback/confirmation handling on failure.
 
 3. **Metadata Updates (When Applicable):**

package/harness/docs/extracts/agent-execution-protocol.md

@@ -17,7 +17,7 @@ surfaces/<surface>/CMP-*/<slug>/     # no modules/ segment
 
 1. **PRE-FLIGHT:** First action = `{{FLOWGRID_READ_TOOL}}` / read target `SKILL.md`. Never memory.
 4. **NO RAM CACHING:** Durable results → disk immediately. Prior file = next input.
-5. **ZERO BUSINESS HALLUCINATION:** Data only from User prompt or ArtifactGraph. Gaps → AskQuestion (MUST include "Log as Tech Debt" option); if member selects "Log as Tech Debt" → `qa/open/QA-<page-id>-NNNN.yaml` + `#missing_info QA-…`. No invented business fields.
+5. **ZERO BUSINESS HALLUCINATION:** Data only from User prompt or ArtifactGraph. Gaps → AskQuestion (MUST include "Log as Tech Debt" option); if member selects "Log as Tech Debt" → `qa/<SHORT>_NNNN.yaml` + `#missing_info QA-…`. No invented business fields.
 6. **GRILL HARD GATE:** AG re-check → micro-scope → propose → **STOP for Confirm** before product SSOT write.
 7. **HUMAN DSL:** Common/DSL only via `/common`, `/docs-mark`, custom-base, or grill Confirm. `/spec` consumes only (no `common/yaml`).
 
@@ -26,6 +26,6 @@ surfaces/<surface>/CMP-*/<slug>/     # no modules/ segment
 ```text
 {{FLOWGRID_READ_TOOL}} SKILL.md
   → durable writes immediately (No RAM)
-  → AskQuestion or qa/open + grill Confirm before SSOT fill
+  → AskQuestion or qa + grill Confirm before SSOT fill
   → common/DSL only when human-gated
 ```

package/harness/docs/extracts/api-codegen-readiness.md

@@ -29,6 +29,6 @@ flowgrid render
 
 ## Still missing after grill?
 
-`#tech-debt:QA-*` + `qa/open/` — or `/qa-resolve`. Do not ship silent gaps.
+`#tech-debt:QA-*` + `qa/` — or `/qa-resolve`. Do not ship silent gaps.
 
 Registry: BE checkout `registries/codegen.registry.json` (after `registry:sync`).

package/harness/docs/extracts/api-spec-sync.md

@@ -28,7 +28,7 @@ Path: `…/common/yaml/<slug>/01-backend-spec.yaml` — same trio rules, scan be
 
 ## Missing facts
 
-AskQuestion (Recommended / Other / Tech Debt) → `qa/open/QA-*` — **no** `openQuestions` in YAML.
+AskQuestion (Recommended / Other / Tech Debt) → `qa/*` — **no** `openQuestions` in YAML.
 
 ## Field rename guard
 

package/harness/docs/extracts/call-external.md

@@ -10,7 +10,7 @@ Hashtag only (via `/api-spec`, `/grill-api-spec`, `/api-update`) — **not** a s
 ## Rules
 
 - Never edit `ir/design.yaml` for external contract detail.
-- No invented secrets — AskQuestion or `qa/open/`.
+- No invented secrets — AskQuestion or `qa/`.
 - Grill: timeout/retry/idempotency must be explicit before `api-gen`.
 
 Hub: `docs/references/skills/call-external.md`.

package/harness/docs/extracts/common-scope.md

@@ -25,7 +25,7 @@ Inside every `common/`:
 ```text
 common/
   patterns/          ← /common Markdown (BA/QA rules)
-  processes/         ← module/cluster FLOW-*.md (not architecture catalog)
+  user-flows/        ← module/cluster FLOW-*.md (Luồng người dùng; not architecture catalog)
 ```
 
 Optional: `data-model/`, `integrations/`, `db-erd.md`, `cross-service.md` at the same LCA (see skills `/db-erd`, `/cross-service`).
@@ -38,20 +38,20 @@ If the same pattern already exists at a **narrower** `common/`, **reuse it** (re
 
 ## 3. Consume order (`/spec`, `/grill-*`, `/api-spec`)
 
-From the function folder, walk **up** and read the **nearest** `common/patterns/*.md` (and FLOW under `processes/` when relevant). Do not author duplicate YAML CMN bundles.
+From the function folder, walk **up** and read the **nearest** `common/patterns/*.md` (and FLOW under `user-flows/` when relevant). Do not author duplicate YAML CMN bundles.
 
 Same walk for `patterns/` Markdown.
 
-## 4. Business process (`FLOW-*`)
+## 4. Luồng người dùng (`FLOW-*`)
 
 | Scope of the flow | File |
 |-------------------|------|
-| Org / cross-surface / “hero” catalog | `architecture/03-business-process/FLOW-*.md` (MCP `flowgrid_docs_business_processes`) |
-| Many modules, one surface | `surfaces/<surface>/common/processes/FLOW-*.md` |
-| Whole module, several clusters | `surfaces/<surface>/<CMP-id>/common/processes/FLOW-*.md` |
-| One cluster / submodule only | `surfaces/<surface>/<CMP-id>/<NN>/common/processes/FLOW-*.md` |
+| Org / cross-surface / “hero” catalog | `architecture/03-user-flows/FLOW-*.md` (MCP `flowgrid_docs_user_flows`) |
+| Many modules, one surface | `surfaces/<surface>/common/user-flows/FLOW-*.md` |
+| Whole module, several clusters | `surfaces/<surface>/<CMP-id>/common/user-flows/FLOW-*.md` |
+| One cluster / submodule only | `surfaces/<surface>/<CMP-id>/<NN>/common/user-flows/FLOW-*.md` |
 
-Do **not** drop `FLOW-*.md` beside a single `W-*` bundle. Do **not** write module-internal flows only under `architecture/03-business-process/` (optional **link** from the catalog to the product path).
+Do **not** drop `FLOW-*.md` beside a single `W-*` bundle. Do **not** write module-internal flows only under `architecture/03-user-flows/` (optional **link** from the catalog to the product path).
 
 `/db-erd` and `/cross-service` use the **same** `common/` LCA (`common/db-erd.md`, `common/cross-service.md`), not a second invented folder name.
 

package/harness/docs/extracts/design-leaf-signoff.md

@@ -4,12 +4,12 @@ Hub SSOT: `docs/workflows/design-leaf-signoff.md` — **không** engine gate.
 
 ## Rubric 6 mục (lead/BA)
 
-1. `flowgrid audit spec <bundle> --type <profile>` — `gaps[]` xử lý; `confirms[]` chốt hoặc `qa/open`.
+1. `flowgrid audit spec <bundle> --type <profile>` — `gaps[]` xử lý; `confirms[]` chốt hoặc `qa`.
 2. VitePress `ir/generated/spec.md` (+ `data-model.md`) — stories, list columns, AC không placeholder.
 3. Spot 2–3 scenario ↔ `design.actions` / validation messages VI.
 4. `api/.../01-backend-spec.yaml` ↔ `ir/design.yaml` apiRef; `audit fe-be` nếu có BE.
 5. `grillStatus.dev: done` (theo flow); `gen:dry` pass; `bundle.gen` đầy đủ.
-6. `qa/open` rỗng hoặc debt đã accept.
+6. `qa` rỗng hoặc debt đã accept.
 
 Optional: **Data model** — `db-erd` LCA + `design.sections[].db` / `spec.entities` (xem hub `architecture-data.md`). `/grill-prototype` SSOT issues; `registry:sync` trên FE standard base.
 

package/harness/docs/extracts/extract-registry.docs.json

@@ -15,7 +15,8 @@
     "docs-hub": [
       ".cursor/extracts/docs-phase-hooks.md",
       ".cursor/extracts/agent-execution-protocol.md",
-      ".cursor/extracts/qa-inbox.md"
+      ".cursor/extracts/qa-inbox.md",
+      ".cursor/extracts/qa-team.md"
     ],
     "spec-requirement": [
       ".cursor/extracts/spec-requirement.md",

package/harness/docs/extracts/qa-inbox.md

@@ -7,28 +7,37 @@ There is **no** `openQuestions` on YAML. Gaps use **AskQuestion** in the skill s
 AskQuestion: MUST include your Recommended options AND an explicit "Log as Tech Debt (Pending)" option. (The UI automatically provides the 3rd "Other" option). **STOP**.
 
 - Member picks A/B/C (Recommended) → write that fact into the real spec field (`design`, `01`, …).
-- Member picks **Log as Tech Debt (Pending)** → create a QA file (below). Do not invent the answer.
+- Member picks **Log as Tech Debt (Pending)** → create **one** `qa/<SHORT>_NNNN.yaml` with first `updates[]` line `kind: question`. Do not invent the answer.
 - Member picks **Other** and types a decision → write that text into the spec field.
 
 ## When to create a file
 
-1. Read `page-id` on the feature bundle / `ir/spec.yaml` (or `feature.id` on a backend `01`). Legacy bundles may still have `id`.
-2. Glob `qa/open/QA-<id>-*.yaml`. Next seq = max `NNNN` + 1, pad 4 digits. First file → `0001`.
-3. Write `qa/open/QA-<id>-NNNN.yaml` from `.flowgrid/templates/qa-item.yaml`.
-4. Point the spec field at the **same** id: `#missing_info QA-<id>-NNNN` and/or `#tech-debt:QA-<id>-NNNN` and/or `pendingTechDebt[].id`.
-5. `flowgrid split` — `ir/spec.yaml` gets `"Q&A": QA-…-0001, QA-…-0002`.
+**[MANDATORY]** Read whole `.flowgrid/templates/qa-item.yaml` + `.flowgrid/templates/qa-authoring.md` before writing.
+
+1. Pick **SHORT** slug (stable) — see `suggestQaShort(W-*)` in authoring doc.
+2. Next id: glob `qa/<SHORT>_*.yaml` **or** `nextQaId(hub, SHORT)` (`engines/docs/lib/qa-item.mjs`).
+3. Copy golden template → `qa/<SHORT>_NNNN.yaml`:
+   - `schema: flowgrid-qa-item/v1`
+   - `id` = basename; `status: open`; `target.path` + `target.at`; `screen` / `bundleId` / `skill` / `kind`
+4. First `updates[]`: `at` = `YYYYMMDD HH:mm` (`formatQaAt`), `kind: question`, `text` = open question.
+5. Point spec: `#missing_info <id>` / `#tech-debt:<id>` on `target.at`.
+6. `flowgrid split` — `ir/spec.yaml` Q&A lists open ids.
+
+Optional: `validateQaItem` / schema `templates/schemas/qa-item.schema.json`.
 
 ## Close (`/qa-resolve`)
 
-Prompt: `/qa-resolve QA-<page-id>-NNNN` plus the **solution** on the following lines.
+Prompt: `/qa-resolve <id>` plus **solution** on following lines.
+
+Append `kind: answer` to **same file**; patch bundle/01; `status: closed`; gỡ tags; `flowgrid split`.
 
-That is Confirm — do **not** AskQuestion again. Skill patches `target.path`, deletes this file, gỡ tag / `pendingTechDebt`, `flowgrid split` (and `openapi:gen` if 01).
+## Review (team)
 
-Unknown answer → grill / `/api-spec`, not this extract.
+`/qa-review <id>` → append `kind: review` to **same file** — see `qa-team.md`.
 
 ## Do not block grill
 
-`grillStatus` may be `done` while `qa/open/` still has files. Short `summary` prose is member review, not a QA file unless **keys** are missing.
+`grillStatus` may be `done` while `status: open` QA files exist.
 
 ## Not this folder
 

package/harness/docs/extracts/qa-team.md

@@ -0,0 +1,32 @@
+# QA — one file, append timeline (docs hub)
+
+Hub: `docs/workflows/qa-team.md`.
+
+## File naming
+
+`qa/<SHORT>_<NNNN>.yaml` — e.g. `HOTEL-LIST_0001.yaml`. Next index: glob same prefix, max NNNN + 1.
+
+`id` inside file = basename without `.yaml`.
+
+## Rules
+
+1. **One case = one file** for life of that question thread.
+2. **`updates[]` append-only** — `at` as `YYYYMMDD HH:mm`, `kind`: question | answer | review | note.
+3. **`qa/index.md`** is render-only catalog — do not put business log in index.
+4. **needs-change:** append `kind: review` with text; set `status: open`; do **not** create a second file.
+
+## Open (Tech Debt)
+
+Template: `.flowgrid/templates/qa-item.yaml` · rules: `qa-authoring.md` · `schema: flowgrid-qa-item/v1`.
+
+Create file + first update `kind: question`. Tag field: `#missing_info <id>` / `#tech-debt:<id>`.
+
+## /qa-resolve
+
+Append `kind: answer` with user solution text; patch `target.path` / `target.at`; remove QA tags from spec; `status: closed`; `flowgrid split`.
+
+## /qa-review
+
+Append `kind: review` only. If needs-change, `status: open`.
+
+Legacy `qa/` paths: migrate to flat `qa/<id>.yaml` when touching old hubs.

package/harness/docs/extracts/spec-core.md

@@ -2,7 +2,7 @@
 
 `/common` writes `common/patterns/*.md` at the LCA from `common-scope.md`.
 
-Cross-flow: `common/processes/FLOW-*.md`.
+Cross-flow: `common/user-flows/FLOW-*.md`.
 
 **Deprecated:** `/common-spec`, `common/yaml`, `/gen-common`, `/grill-common-spec`.
 

package/harness/docs/extracts/spec-evolution.md

@@ -14,7 +14,7 @@ Set `breaking: true`; require re-grill (`/grill-api-spec` or `/grill-dev`) befor
 
 ## Deferred work
 
-Use `pendingTechDebt[]` with `id: QA-<feature.id>-NNNN` + matching `qa/open/` file — not prose in `requirements`.
+Use `pendingTechDebt[]` with `id: QA-<feature.id>-NNNN` + matching `qa/` file — not prose in `requirements`.
 
 ## OpenAPI
 

package/harness/docs/extracts/spec-prd-lite.md

@@ -1,19 +1,17 @@
 # Leaf bundle ↔ PRD lite (map for /spec)
 
-| PRD section | Bundle / IR |
+| PRD section | Bundle key → `ir/generated/spec.md` |
 | --- | --- |
-| Problem / goals | `summary` bullets (business_goals, stakeholders, user_journey, context) |
-| Success metrics | `successMetrics` (optional) |
-| Non-goals | `nonGoals` (optional) |
-| Users / persona | `userStories.primary.asA` + link `overview/` persona |
-| User stories + AC | `userStories.scenarios`, `acceptanceCriteria` |
-| Functional scope | `spec.requirements`, `design.sections`, `design.actions` |
-| API | `api/<seq>/01-backend-spec.yaml` — **not** `spec.api` |
-| Tech / codegen | `gen`, `grill-dev` — not in first `/spec` pass |
-| Open questions | `qa/open/QA-*.yaml` |
+| Goals / background | `summary` |
+| In scope | `scopeIn` |
+| Out of scope | `nonGoals` |
+| Features & requirements | `userStories` + `design.*` (render sections) |
+| User flows | `userFlows` (+ FLOW-* docs) |
+| Data & API | `entities` + links `data-model.md` / `api.md` / `01` |
+| NFR | `nfr` |
+| Risks | **Chỉ** `architecture/11-risks/risk-register.md` — không key trên bundle |
+| Open questions | `qa/*.yaml` → `Q&A` + Phụ lục |
 
-**Author path:** `.flowgrid/templates/feature.bundle.yaml` + `bundle-authoring.md` only. **`design-spec.yaml` deprecated.**
-
-**BA deliverable:** `ir/generated/spec.md` (TOC, overview, metrics, non-goals) after `flowgrid split` + `flowgrid render`.
+**BA deliverable:** `flowgrid split` + `flowgrid render` → `ir/generated/spec.md` (TOC PRD). Audit: `WARN_NO_SCOPE_IN`, `WARN_NO_NON_GOALS`, `WARN_NO_NFR`, `WARN_NO_USER_FLOWS` (when handoff). Rủi ro: `/risk-register` + `audit risks` (không `risks:` trên bundle).
 
 **Profile trim:** list → giữ Initial Load, Affordances (nếu có), Exceptions; bỏ scenario form nếu không có `ui.form`. create/detail tương tự — không copy 6 scenario khi không áp dụng.

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`