@shanyucoder/flowgrid 0.1.9 → 0.1.11

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/audit-legacy-gaps.mjs

@@ -42,6 +42,16 @@ function auditLegacyInventory(inventoryPath, targetId) {
 
   const rawText = fs.readFileSync(inventoryPath, 'utf8');
 
+  if (targetId?.startsWith('FLOW-') && !/##\s+4\.\s+User flows/i.test(rawText)) {
+    addGap(
+      'ADOPT_MISSING_USER_FLOW_SECTION',
+      'warning',
+      'adoption-inventory.md#user-flows',
+      'Inventory has no "## 4. User flows" section — cross-surface FLOW-* may be missing.',
+      'Re-run /adopt with user-flow discovery; see tpl-adoption-inventory.md (tiers A/B/C).'
+    );
+  }
+
   if (targetId) {
     if (!rawText.includes(targetId)) {
       addGap(

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/testcase/_staging-from-portal/runners/README.md

@@ -4,10 +4,10 @@ Reads **plans** from sibling `base-tests/` → writes `tests/e2e/` on this FE re
 
 ```bash
 pnpm testcase:gen:dry --id TC-LOGIN-VALID
-pnpm testcase:gen --id W-AD-AUTH-001
+pnpm testcase:gen --id W-ADM-AUTH-01
 pnpm testcase:gen --id smoke
-pnpm testcase:gen --testcase ../base-tests/cases/W-AD-AUTH-001/TC-LOGIN-VALID.yaml
-pnpm testcase:gen --feature W-AD-AUTH-001   # all TC-* under cases/{id}/
+pnpm testcase:gen --testcase ../base-tests/cases/W-ADM-AUTH-01/TC-LOGIN-VALID.yaml
+pnpm testcase:gen --feature W-ADM-AUTH-01   # all TC-* under cases/{id}/
 ```
 
 Author/edit plans on **base-tests** (`/testcase`), not on this code repo.

package/engines/testcase/_staging-from-portal/runners/generate.mjs

@@ -37,8 +37,8 @@ function parseArgs(argv) {
 
   if (!options.testcase && !options.feature && !options.id) {
     throw new Error(
-      'Usage: pnpm testcase:gen --id W-AD-AUTH-001|TC-LOGIN-VALID|smoke|CMP-01|SC-LOGIN\n' +
-        '       pnpm testcase:gen --testcase <path> | --feature W-AD-AUTH-001  (screen under base-tests/cases)',
+      'Usage: pnpm testcase:gen --id W-ADM-AUTH-01|TC-LOGIN-VALID|smoke|CMP-ADM-AUTH-01|SC-LOGIN\n' +
+        '       pnpm testcase:gen --testcase <path> | --feature W-ADM-AUTH-01  (screen under base-tests/cases)',
     )
   }
 

package/engines/testcase/_staging-from-portal/runners/lib/read-testcase.mjs

@@ -145,7 +145,7 @@ export async function readTestcaseFile(testcasePath, opts = {}) {
 /**
  * List TC-*.yaml under base-tests/cases/{screenId}/ (prefer --id).
  * @param {string} root FE repo root
- * @param {string} screenId e.g. W-AD-AUTH-001
+ * @param {string} screenId e.g. W-ADM-AUTH-01
  */
 export async function listFeatureTestcases(root, screenId) {
   const testsRoot = resolveProjectRoot(root, 'base-tests')

package/engines/testcase/runners/README.md

@@ -4,10 +4,10 @@ Reads **plans** from the tests hub → writes `tests/e2e/` in the FE project.
 
 ```bash
 pnpm testcase:gen:dry --id TC-LOGIN-VALID
-pnpm testcase:gen --id W-AD-AUTH-001
+pnpm testcase:gen --id W-ADM-AUTH-01
 pnpm testcase:gen --id smoke
-pnpm testcase:gen --testcase "$FLOWGRID_TESTS_DOC/cases/W-AD-AUTH-001/TC-LOGIN-VALID.yaml"
-pnpm testcase:gen --feature W-AD-AUTH-001   # all TC-* under cases/{id}/
+pnpm testcase:gen --testcase "$FLOWGRID_TESTS_DOC/cases/W-ADM-AUTH-01/TC-LOGIN-VALID.yaml"
+pnpm testcase:gen --feature W-ADM-AUTH-01   # all TC-* under cases/{id}/
 ```
 
 Author/edit plans in the **tests hub** (`/testcase`), not in the code project.

package/engines/testcase/runners/generate.mjs

@@ -51,8 +51,8 @@ function parseArgs(argv) {
 
   if (!options.testcase && !options.feature && !options.id && !options.all) {
     throw new Error(
-      'Usage: pnpm testcase:gen --id W-AD-AUTH-001|TC-LOGIN-VALID|smoke|CMP-01|SC-LOGIN\n' +
-        '       pnpm testcase:gen --testcase <path> | --feature W-AD-AUTH-001  (screen under tests hub cases/)\n' +
+      'Usage: pnpm testcase:gen --id W-ADM-AUTH-01|TC-LOGIN-VALID|smoke|CMP-ADM-AUTH-01|SC-LOGIN\n' +
+        '       pnpm testcase:gen --testcase <path> | --feature W-ADM-AUTH-01  (screen under tests hub cases/)\n' +
         '       pnpm testcase:gen --all\n' +
         '       Optional: --tests-docs <hub> or FLOWGRID_TESTS_DOC',
     )

package/engines/testcase/runners/lib/read-testcase.mjs

@@ -158,7 +158,7 @@ export async function readTestcaseFile(testcasePath, opts = {}) {
 /**
  * List TC-*.yaml under the tests hub cases/{screenId}/ (prefer --id).
  * @param {string} root FE repo root
- * @param {string} screenId e.g. W-AD-AUTH-001
+ * @param {string} screenId e.g. W-ADM-AUTH-01
  */
 export async function listFeatureTestcases(root, screenId) {
   const testsRoot = process.env.FLOWGRID_TESTS_DOC ? path.resolve(process.env.FLOWGRID_TESTS_DOC) : resolveProjectRoot(root, 'tests')

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 }
@@ -263,8 +263,8 @@ export function resolveHubId(repoRoot, id, mode = 'testcase') {
     return { kind: 'code', id, paths: [spec], notes, codeDir }
   }
 
-  // Module (e.g. CMP-ADM-001) → all code children
-  if (/^[A-Z]+-[A-Z]+-\d{3}$/i.test(id)) {
+  // Module (e.g. CMP-ADM-AUTH-01) → all code children
+  if (/^CMP-[A-Z0-9]+(?:-[A-Z0-9]+)+$/i.test(id)) {
     const { index: docsIdx } = getDocs()
     const cmp = (docsIdx.modules || []).find(
       (c) => c.id === id || c.id.startsWith(id) || (c.slug && id.toLowerCase().includes(c.slug)),
@@ -319,6 +319,6 @@ export function resolveHubId(repoRoot, id, mode = 'testcase') {
   }
 
   throw new Error(
-    `Unrecognized id "${id}". Use W-|API-|UI-|FLOW-|DEP-|TC-|SC-* or hierarchical ID (e.g. cmp-adm-001-01-01), or module ID (CMP-ADM-001), or suite id (smoke, regression-auth).`,
+    `Unrecognized id "${id}". Use W-|API-|UI-|FLOW-|DEP-|TC-|SC-* or hierarchical ID (e.g. cmp-adm-auth-01-01-01), or module ID (CMP-ADM-AUTH-01), or suite id (smoke, regression-auth).`,
   )
 }

package/harness/be/skills/audit-api/SKILL.md

@@ -12,7 +12,7 @@ Run after `npm run codegen:api:dry` / `flowgrid api-gen:dry` and after implement
 
 ## Target / ID Resolution Rule
 
-- User prompt MAY specify a function ID, API slug, or short name (e.g. `API-AUTH-001`, `login`, `CMP-ADM-009`).
+- User prompt MAY specify a function ID, API slug, or short name (e.g. `API-AUTH-001`, `login`, `CMP-ADM-DEMO-01`).
 - Agent MUST resolve **`…/api/<seq>/01-backend-spec.yaml`** via `FLOWGRID_DOCS_ROOT` or `flowgrid_docs_route` (screen leaf `CMP-*/<NN…>/api/<seq>/`, or `common/yaml/<slug>/`, or external-channel surface `…/api/<seq>/`).
 - **Read the entire `01-backend-spec.yaml`**. Do **not** use `ir/design.yaml` or `ir/spec.yaml` as BE contract.
 - Compare generated routes/code against that 01 file. Missing 01 → STOP, hand off to docs `/grill-api-spec`.

package/harness/be/skills/grill-api-unit/SKILL.md

@@ -13,7 +13,7 @@ before committing generated test code.
 
 ## Target / ID Resolution Rule
 
-- User prompt MAY specify a function ID, API slug, or short name (e.g. `API-AUTH-001`, `login`, `CMP-ADM-009`).
+- User prompt MAY specify a function ID, API slug, or short name (e.g. `API-AUTH-001`, `login`, `CMP-ADM-DEMO-01`).
 - Agent MUST resolve **`…/api/<seq>/01-backend-spec.yaml`** via `FLOWGRID_DOCS_ROOT` or `flowgrid_docs_route`.
 - **Read the entire `01-backend-spec.yaml`**. Do **not** use `ir/design.yaml` or `ir/spec.yaml` as BE contract.
 - Compare generated unit tests against that 01 file. Missing 01 → STOP, hand off to docs `/grill-api-spec`.

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/architecture-core.md

@@ -36,6 +36,8 @@ No **dynamics** wording on new trees — use **flow** / `FLOW-*` / `/journey`.
 
 ## ID rules
 
+**Product IDs (global):** `product-id-convention.md` — `surfaceCode` on each surface; `CMP-{SURF}-{DOMAIN}-{NN}`, `W-{SURF}-{DOMAIN}-{NN}`, `API-{SURF}-{DOMAIN}-{NN}`.
+
 | Prefix | Path | Notes |
 |--------|------|-------|
 | `LND-*` `CTX-*` | `architecture/03-context/` | Overview / landscape + context |

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/extract-registry.docs.json

@@ -10,7 +10,9 @@
       ".cursor/extracts/tpl-deployment.md",
       ".cursor/extracts/tpl-adr.md",
       ".cursor/extracts/tpl-cross-cutting.md",
-      ".cursor/extracts/common-scope.md"
+      ".cursor/extracts/common-scope.md",
+      ".cursor/extracts/tpl-adoption-inventory.md",
+      ".cursor/extracts/product-id-convention.md"
     ],
     "docs-hub": [
       ".cursor/extracts/docs-phase-hooks.md",
@@ -25,11 +27,13 @@
       ".cursor/extracts/design-leaf-signoff.md",
       ".cursor/extracts/db-audit-wizard.md",
       ".cursor/extracts/agent-execution-protocol.md",
-      ".cursor/extracts/common-scope.md"
+      ".cursor/extracts/common-scope.md",
+      ".cursor/extracts/product-id-convention.md"
     ],
     "spec-core": [
       ".cursor/extracts/spec-core.md",
-      ".cursor/extracts/common-scope.md"
+      ".cursor/extracts/common-scope.md",
+      ".cursor/extracts/product-id-convention.md"
     ],
     "bqa-grill": [
       ".cursor/extracts/grill/validation.md",

package/harness/docs/extracts/product-id-convention.md

@@ -0,0 +1,58 @@
+# Product ID convention (global SSOT)
+
+English **structure**; prose locale is separate (`contentLocale`).
+
+## Why surface code is mandatory
+
+IDs are **globally unique** across the docs hub (CLI `--id`, registries, tests mirror). The same capability on two channels (e.g. Login on admin vs customer) MUST be two IDs. Path `surfaces/<slug>/` alone is not enough when referencing without a path.
+
+## Surface code (`surfaceCode`)
+
+- Declare on every `surfaces/<slug>/index.md` frontmatter: `surfaceCode: ADM` (2–4 uppercase letters).
+- Register once per channel; reuse the **same token** in every `CMP-*` / `W-*` / `API-*` / `UI-*` on that surface.
+- Folder slug stays human (`admin`, `customer-web`); **IDs embed `surfaceCode`**, not the slug.
+
+| Surface folder | Example `surfaceCode` |
+| --- | --- |
+| `surfaces/admin` | `ADM` |
+| `surfaces/customer-web` | `CUS` |
+| `surfaces/workforce-app` | `WRK` |
+
+## Patterns
+
+| Kind | Pattern | Example |
+| --- | --- | --- |
+| Module (folder name) | `CMP-{SURF}-{DOMAIN}-{NN}` | `CMP-ADM-AUTH-01` |
+| Screen | `W-{SURF}-{DOMAIN}-{NN}` | `W-ADM-AUTH-01` |
+| API | `API-{SURF}-{DOMAIN}-{NN}` | `API-ADM-AUTH-01` |
+| UI code leaf | `UI-{SURF}-{DOMAIN}-{NN}` | `UI-ADM-EMPTY-01` |
+| User flow | `FLOW-{slug}` | `FLOW-checkout` (no surface — scope in doc body) |
+| Common | `CMN-UI-*` / `CMN-API-*` / `CMN-DTO-*` | No surface prefix |
+
+- `{SURF}` = `surfaceCode` (2–4 chars).
+- `{DOMAIN}` = short capability token (`AUTH`, `ORD`, `CART`, `USR`, …).
+- `{NN}` = two digits `01`–`99` per domain on that surface (pad with zero).
+
+## Module folder = global module ID
+
+`surfaces/<slug>/CMP-ADM-AUTH-01/` — folder name **equals** global `CMP-*` id (tooling SSOT).
+
+## Bundle / path slug (lowercase)
+
+`CMP-ADM-ORD-01` + draft `02-01-02` → `page-id: cmp-adm-ord-01-02-01-02` (lowercase, same tokens).
+
+## Hierarchical CLI alias
+
+Lowercase path encoding: `cmp-adm-auth-01-01-01-01` (= module + numeric segments under `CMP-*`).
+
+## Same business name, two surfaces
+
+- Admin login: `W-ADM-AUTH-01`
+- Customer login: `W-CUS-AUTH-01`  
+Shared spec → `CMN-*` or explicit cross-reference; **never** one `W-*` for both.
+
+## Forbidden
+
+- `W-AUTH-01` without `{SURF}` (collision risk).
+- Mixed tokens on one surface (`W-AD-*` vs `W-ADM-*`) — pick one `surfaceCode` and stick to it.
+- Renaming IDs for arc42-only refactors (see `architecture/02-constraints`).

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-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/*.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/spec-requirement.md

@@ -6,4 +6,4 @@ Required business keys when info exists: `summary`, `userStories` (+ `screenAcce
 
 After patch: `flowgrid split` → `flowgrid render` → BA reads `ir/generated/spec.md` (not hand-written `.md`).
 
-Path SSOT: `surfaces/<surface>/CMP-*/<NN…>/` — resolve IDs with `flowgrid_docs_route` on consumer repo.
+Path SSOT: `surfaces/<surface>/CMP-*/<NN…>/` — resolve IDs with `flowgrid_docs_route` on consumer repo. ID shape: `product-id-convention.md`.

package/harness/docs/extracts/tpl-adoption-inventory.md

@@ -0,0 +1,32 @@
+# Adoption inventory — section template (`adoption-inventory.md`)
+
+Workspace root SSOT after `/adopt`. English **IDs**; prose may follow hub `contentLocale` later. ID shape: `product-id-convention.md` (`surfaceCode`, `CMP|W|API-{SURF}-{DOMAIN}-{NN}`).
+
+## Required sections
+
+1. **Surfaces** — channel / app → legacy repo path  
+2. **Modules (`CMP-*`)** — feature groups → legacy module folder  
+3. **Screens & APIs (`W-*`, `API-*`)** — leaf functions → legacy file paths  
+4. **User flows (`FLOW-*`)** — see placement tiers below (mandatory when scan finds multi-step / cross-app journeys)  
+5. **Common catalog (`CMN-*`)** — only if Common Analysis mode  
+6. **Handoff** — `/legacy /spec`, `/legacy /user-flow`
+
+## User flow placement (maps to new docs hub)
+
+| Tier | When to list | Target path after `/legacy /user-flow` |
+| --- | --- | --- |
+| **A — Cross-surface / org** | Same journey touches **≥2 surfaces** or **≥2 CMP owners** (checkout admin→customer, ops→partner API, SSO handoff) | `architecture/03-user-flows/FLOW-*.md` |
+| **B — Surface shared** | Journey shared by **≥2 modules** on **one** surface | `surfaces/<surface>/common/user-flows/FLOW-*.md` |
+| **C — Module / cluster** | Journey stays inside **one CMP** (or one cluster `CMP-*/NN/`) | `surfaces/<surface>/<CMP>/common/user-flows/FLOW-*.md` or `…/<CMP>/<NN>/common/user-flows/` |
+| **D — Not a FLOW** | Single screen CRUD, one API call | Document only `W-*` / `API-*` — **do not** invent `FLOW-*` |
+
+Each `FLOW-*` line MUST include:
+
+- **Surfaces / CMPs involved** (e.g. `admin`, `CMP-ADM-ORD-01`, `customer-web`, `CMP-CUS-CART-01`)
+- **Screen/API steps** (ordered `W-*` / `API-*` refs or legacy route names)
+- **Legacy evidence** (router guards, saga classes, shared session keys, event names — file paths)
+- **Suggested tier** (A / B / C)
+
+## Legacy scan hints (cross-surface)
+
+Look for: redirect chains across subdomains/apps, shared `orderId`/`session` in multiple repos, BPM/orchestrator, “checkout” spanning cart (FE) + payment (API) + notification (worker), duplicate route names in 2+ legacy apps for one business journey.

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-{SURF}-{DOMAIN}-{NN}/index.md` — **MD only** (`product-id-convention.md`).
 
-```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/agent-compliance.mdc

@@ -23,4 +23,4 @@ When executing any skill (`/spec`, `/grill`, `/grill-bqa`, etc.):
 6. **DSL / COMMON:** Human lead decides common promotions. The agent only executes `/common` (Markdown patterns), `/docs-mark`, custom-base handoff, or confirmation post-grill. `/spec` consumes patterns + FE base via `flowgrid-ux-common.mdc`. **[STRICTLY FORBIDDEN]** `common/yaml`, `/common-spec`, `/gen-common`.
 7. **ISOLATION:** Execute strictly within the invoked skill scope. **[STRICTLY FORBIDDEN]** to merge sibling features or output fake Markdown reports when YAML contracts are required.
 
-**Path SSOT:** `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment).
+**Path SSOT:** `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment). **IDs:** `product-id-convention.md` (`surfaceCode` + `CMP|W|API-{SURF}-{DOMAIN}-{NN}`).