@shanyucoder/flowgrid 0.1.9 → 0.1.10

package/engines/docs/lib/audit-hub-prd.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+/**
+ * PRD hub Markdown audit — section titles must be English (structureLocale: en).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PLACEHOLDER_RE = /\[[^\]]{4,}\]/;
+
+function hubKind(filePath) {
+  const norm = filePath.split(path.sep).join('/');
+  if (norm.endsWith('overview/index.md')) return 'overview';
+  if (norm.endsWith('_surface-index.template.md')) return 'surface';
+  if (norm.endsWith('_module-index.template.md')) return 'module';
+  if (/\/surfaces\/[^/]+\/index\.md$/.test(norm) && !norm.includes('/CMP-')) return 'surface';
+  if (/\/CMP-[^/]+\/index\.md$/.test(norm)) return 'module';
+  if (norm.includes('/operational-areas/') && norm.endsWith('.md')) return 'operational';
+  return 'unknown';
+}
+
+function hasEnglishGoals(text) {
+  return /##\s+Goals\b/i.test(text);
+}
+function hasEnglishBackground(text) {
+  return /##\s+Background\b/i.test(text);
+}
+function hasEnglishScope(text) {
+  return /##\s+Scope\b/i.test(text);
+}
+
+export function auditHubPrdContent(rawText, filePath) {
+  const gaps = [];
+  const warnings = [];
+  const kind = hubKind(filePath);
+
+  function addGap(code, fieldPath, message, suggestedFix) {
+    gaps.push({ code, severity: 'critical', path: fieldPath, message, suggestedFix });
+  }
+  function addWarning(code, fieldPath, message, suggestedFix) {
+    warnings.push({ code, path: fieldPath, message, suggestedFix });
+  }
+
+  const needsGoals = kind === 'overview' || kind === 'surface' || kind === 'module';
+  const needsBackground = kind === 'overview' || kind === 'surface';
+  const needsScope = kind !== 'unknown';
+
+  if (needsGoals && !hasEnglishGoals(rawText)) {
+    addGap(
+      'HUB_MISSING_GOALS',
+      'section.goals',
+      'Missing `## Goals` (English section key).',
+      'Add ## Goals {#goals} with business bullets (prose in contentLocale).'
+    );
+  }
+
+  if (needsBackground && !hasEnglishBackground(rawText)) {
+    addGap(
+      'HUB_MISSING_BACKGROUND',
+      'section.background',
+      'Missing `## Background`.',
+      'Add ## Background {#background}.'
+    );
+  }
+
+  if (needsScope && !hasEnglishScope(rawText)) {
+    addGap(
+      'HUB_MISSING_SCOPE',
+      'section.scope',
+      'Missing `## Scope`.',
+      'Add ## Scope {#scope} with In scope / Out of scope bullets.'
+    );
+  }
+
+  if (/##\s+Mục tiêu/i.test(rawText) || /##\s+Bối cảnh/i.test(rawText) || /##\s+Phạm vi/i.test(rawText)) {
+    addWarning(
+      'HUB_VI_SECTION_TITLE',
+      'section.locale',
+      'Vietnamese section titles detected — use English keys (Goals, Background, Scope).',
+      'Rename headings to English; keep Vietnamese in body only.'
+    );
+  }
+
+  if (kind === 'module' && !/Features overview|Goals/i.test(rawText)) {
+    addWarning(
+      'HUB_MODULE_FEATURES_THIN',
+      'section.features',
+      'Module index missing Features overview / Goals.',
+      'Add ## Features overview and link function folders.'
+    );
+  }
+
+  if (PLACEHOLDER_RE.test(rawText)) {
+    addWarning(
+      'HUB_PLACEHOLDER',
+      'body',
+      'Template placeholders `[...]` remain.',
+      'Replace with real copy in contentLocale before sign-off.'
+    );
+  }
+
+  if (/##\s+Personas/i.test(rawText) || /Success metrics/i.test(rawText)) {
+    addWarning(
+      'HUB_DEPRECATED_SECTION',
+      'body',
+      'Personas or Success metrics sections — not SSOT on hub.',
+      'Remove or manage outside hub.'
+    );
+  }
+
+  return {
+    target: filePath,
+    hubKind: kind,
+    structureLocale: 'en',
+    totalGaps: gaps.length,
+    totalWarnings: warnings.length,
+    gaps,
+    warnings,
+  };
+}
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.log('Usage: node engines/docs/lib/audit-hub-prd.mjs <path-to-hub.md>');
+  process.exit(0);
+}
+
+const targetFile = path.resolve(process.cwd(), args[0]);
+if (!fs.existsSync(targetFile)) {
+  console.error(JSON.stringify({ error: `File not found: ${targetFile}` }));
+  process.exit(1);
+}
+
+const rawText = fs.readFileSync(targetFile, 'utf8');
+console.log(JSON.stringify(auditHubPrdContent(rawText, targetFile), null, 2));

package/engines/docs/lib/audit-risks-catalog.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+/**
+ * Audit risk SSOT: architecture/11-risks/risk-register.md (member register)
+ * or legacy short catalog on index.md.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function isRiskRegister(filePath) {
+  return path.basename(filePath) === 'risk-register.md';
+}
+
+export function auditRisksCatalogContent(rawText, filePath) {
+  const gaps = [];
+  const warnings = [];
+  const register = isRiskRegister(filePath);
+
+  function addGap(code, fieldPath, message, suggestedFix) {
+    gaps.push({ code, severity: 'warning', path: fieldPath, message, suggestedFix });
+  }
+  function addWarning(code, fieldPath, message, suggestedFix) {
+    warnings.push({ code, path: fieldPath, message, suggestedFix });
+  }
+
+  const hasRiskCol = /\|\s*Rủi ro\s*\|/i.test(rawText) || /\|\s*Mô tả\s*\|/i.test(rawText);
+  const hasTable =
+    /\|\s*Risk\s*\|/i.test(rawText) ||
+    /\|\s*ID\s*\|/i.test(rawText) ||
+    hasRiskCol;
+
+  if (!hasTable) {
+    addGap(
+      'RISK_CATALOG_NO_TABLE',
+      'risks.table',
+      register
+        ? 'Chưa có bảng sổ rủi ro (risk register).'
+        : 'Chưa có bảng rủi ro (cột Risk/Rủi ro + Phương án).',
+      register
+        ? 'Dùng template risk-register.md: cột Hạn mức, Nhu cầu, Chênh lệch.'
+        : 'Thêm bảng markdown hoặc link sang risk-register.md.'
+    );
+  }
+
+  if (register) {
+    const needCols = [
+      { re: /\bLimit\b/i, code: 'RISK_REG_MISSING_LIMIT_COL', label: 'Limit' },
+      { re: /\bNeed\b/i, code: 'RISK_REG_MISSING_NEED_COL', label: 'Need' },
+      { re: /\bGap\b/i, code: 'RISK_REG_MISSING_GAP_COL', label: 'Gap' },
+      { re: /Mitigation/i, code: 'RISK_REG_MISSING_MITIGATION_COL', label: 'Mitigation' },
+    ];
+    for (const col of needCols) {
+      if (!col.re.test(rawText)) {
+        addGap(
+          col.code,
+          'riskRegister.columns',
+          `Thiếu cột «${col.label}» trong bảng risk register.`,
+          `Thêm cột ${col.label} để so sánh quota/hạn mức với nhu cầu peak.`
+        );
+      }
+    }
+
+    const hasRiskId = /RISK-[A-Z0-9_-]+/i.test(rawText);
+    if (!hasRiskId) {
+      addWarning(
+        'RISK_REG_NO_ID',
+        'riskRegister.ids',
+        'Chưa có mã RISK-* trong sổ (chỉ placeholder mẫu?).',
+        'Thêm ít nhất một dòng rủi ro thật với mã RISK-….'
+      );
+    }
+
+    const rows = rawText.match(/^\|[^|]+\|[^|]+\|[^|]+\|/gm) || [];
+    const dataRows = rows.filter(
+      (r) => !r.includes('---') && !/^\|\s*[-:]+\s*\|/.test(r) && !/^\|\s*Mã\s*\|/i.test(r)
+    );
+    const realRows = dataRows.filter((r) => /RISK-/i.test(r) && !/RISK-EXAMPLE/i.test(r));
+    if (hasTable && realRows.length < 1) {
+      addWarning(
+        'RISK_REG_EMPTY',
+        'riskRegister.rows',
+        'Sổ rủi ro chưa có dòng nghiệp vụ (ngoài ví dụ RISK-EXAMPLE).',
+        'Thêm rủi ro thật — vd. quota email, rate limit API, license.'
+      );
+    }
+  } else {
+    const rows = rawText.match(/^\|[^|]+\|[^|]+\|/gm) || [];
+    const dataRows = rows.filter((r) => !r.includes('---') && !/^\|\s*[-:]+\s*\|/.test(r));
+    if (hasTable && dataRows.length < 2) {
+      addWarning(
+        'RISK_CATALOG_EMPTY',
+        'risks.rows',
+        'Bảng rủi ro chưa có dòng nghiệp vụ (chỉ header).',
+        'Ưu tiên điền architecture/11-risks/risk-register.md.'
+      );
+    }
+    if (!/risk-register\.md/i.test(rawText)) {
+      addWarning(
+        'RISK_INDEX_NO_REGISTER_LINK',
+        'risks.index',
+        'index.md chưa trỏ sang risk-register.md.',
+        'Link [risk-register.md](./risk-register.md) là SSOT member.'
+      );
+    }
+  }
+
+  if (/\[(?:\.\.\.|TBD|Tên|VD:)/i.test(rawText)) {
+    addWarning(
+      'RISK_PLACEHOLDER',
+      'body',
+      'Còn placeholder template trong file rủi ro.',
+      'Điền rủi ro thật hoặc defer qa/.'
+    );
+  }
+
+  return {
+    target: filePath,
+    documentKind: register ? 'risk-register' : 'risks-index',
+    totalGaps: gaps.length,
+    totalWarnings: warnings.length,
+    gaps,
+    warnings,
+  };
+}
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.log(
+    'Usage: node engines/docs/lib/audit-risks-catalog.mjs <architecture/11-risks/risk-register.md|index.md>'
+  );
+  process.exit(0);
+}
+
+const targetFile = path.resolve(process.cwd(), args[0]);
+if (!fs.existsSync(targetFile)) {
+  console.error(JSON.stringify({ error: `File not found: ${targetFile}` }));
+  process.exit(1);
+}
+
+const rawText = fs.readFileSync(targetFile, 'utf8');
+console.log(JSON.stringify(auditRisksCatalogContent(rawText, targetFile), null, 2));

package/engines/docs/lib/docs-hub-locale.mjs

@@ -0,0 +1,100 @@
+import * as fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'yaml';
+
+/** Headings / YAML keys / audit anchors — always English. */
+export const STRUCTURE_LOCALE = 'en';
+
+/** @param {string} [code] @param {string} [fallback] */
+export function normalizeContentLocale(code, fallback = 'vi') {
+  const s = String(code ?? '').trim();
+  if (!s) return fallback;
+  return s.replace(/\s+/g, '-').toLowerCase();
+}
+
+/**
+ * @param {{ text: Function, isCancel: Function, cancel: Function }} clack
+ * @returns {Promise<string>}
+ */
+export async function promptDocsContentLocale(clack) {
+  const { text, isCancel, cancel } = clack;
+  const ans = await text({
+    message:
+      'Member prose locale for document spec + test documents (BCP-47 tag, e.g. vi, en, ja — keys/headings stay English):',
+    defaultValue: 'vi',
+    placeholder: 'vi',
+  });
+  if (isCancel(ans)) {
+    cancel('Cancelled.');
+    process.exit(0);
+  }
+  return normalizeContentLocale(ans, 'vi');
+}
+
+/**
+ * @param {string} docsRootAbs
+ * @param {{ structureLocale: string, contentLocale: string }} locales
+ */
+export function writeDocsHubLocaleManifest(docsRootAbs, locales) {
+  const file = path.join(docsRootAbs, 'docs-hub.locale.yaml');
+  const body = `# SSOT — structureLocale is always en (headings/keys). Prose follows contentLocale.\nstructureLocale: ${locales.structureLocale}\ncontentLocale: ${locales.contentLocale}\n`;
+  fs.writeFileSync(file, body, 'utf8');
+}
+
+/** English section labels for tests-docs render (never translated per locale). */
+export const TESTS_HUB_HEADINGS_EN = {
+  home: 'Home',
+  cases: 'Test cases',
+  scenarios: 'Scenarios',
+  plans: 'Test plans',
+  preconditions: 'Preconditions',
+  steps: 'Steps',
+  expected: 'Expected results',
+  traceability: 'Traceability (docs SSOT)',
+  testMatrix: 'Test matrix (equivalence)',
+  crossRefDocs: 'Docs hub cross-reference',
+  technical: 'Technical details',
+  testData: 'Test data',
+  coverage: 'Coverage',
+};
+
+/**
+ * @param {string} testsRootAbs
+ * @param {{ structureLocale: string, contentLocale: string }} locales
+ */
+export function writeTestsHubLocaleCatalog(testsRootAbs, locales) {
+  const catalogDir = path.join(testsRootAbs, 'catalog');
+  if (!fs.existsSync(catalogDir)) {
+    fs.mkdirSync(catalogDir, { recursive: true });
+  }
+  const file = path.join(catalogDir, 'locale.yaml');
+  const lines = [
+    '# SSOT — headings are English; TC prose in YAML follows contentLocale.',
+    `structureLocale: ${locales.structureLocale}`,
+    `contentLocale: ${locales.contentLocale}`,
+    'headings:',
+    ...Object.entries(TESTS_HUB_HEADINGS_EN).map(([k, v]) => `  ${k}: ${v}`),
+  ];
+  fs.writeFileSync(file, `${lines.join('\n')}\n`, 'utf8');
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} [docsRootRel]
+ */
+export function loadDocsHubLocale(projectRoot, docsRootRel) {
+  const rel = docsRootRel || process.env.FLOWGRID_DOCS_ROOT || 'docs';
+  const manifest = path.join(path.resolve(projectRoot), rel, 'docs-hub.locale.yaml');
+  if (!fs.existsSync(manifest)) {
+    return { structureLocale: STRUCTURE_LOCALE, contentLocale: 'vi' };
+  }
+  try {
+    const data = parse(fs.readFileSync(manifest, 'utf8')) ?? {};
+    return {
+      structureLocale: data.structureLocale || STRUCTURE_LOCALE,
+      contentLocale: normalizeContentLocale(data.contentLocale, 'vi'),
+    };
+  } catch {
+    return { structureLocale: STRUCTURE_LOCALE, contentLocale: 'vi' };
+  }
+}

package/engines/docs/lib/render-bundle-markdown.mjs

@@ -6,6 +6,7 @@ import { renderSpecMarkdown } from './render-spec-markdown.mjs'
 import { renderDataModelMarkdown } from './render-data-model-markdown.mjs'
 import { renderApiSummaryMarkdown } from './render-api-summary-markdown.mjs'
 import { resolveBackendSpecForBundle } from '../../spec/lib/audit-db-tables.mjs'
+import { loadDocsHubLocale } from './docs-hub-locale.mjs'
 
 /**
  * Flatten bundle → spec shape (tests / fallback). Prefer ir/spec.yaml for site MD.
@@ -17,7 +18,11 @@ export function bundleToSpecShape(bundle) {
     status: bundle.status,
     owner: bundle.owner,
     summary: bundle.summary ?? bundle.review?.summary,
-    userStories: bundle.userStories ?? bundle.spec?.userStories
+    scopeIn: bundle.scopeIn,
+    nonGoals: bundle.nonGoals,
+    userFlows: bundle.userFlows,
+    nfr: bundle.nfr,
+    userStories: bundle.userStories ?? bundle.spec?.userStories,
   }
   return {
     ...meta,
@@ -158,11 +163,13 @@ export async function writeIrSpecMarkdownFile(specFile, mdOut, context = {}) {
   const design = existsSync(designFile) ? parse(await readFile(designFile, 'utf8')) ?? {} : {}
   const specShape = mergeDesignIntoSpecForRender(spec, design)
   const projectRoot = context.projectRoot ?? process.cwd()
+  const { contentLocale: docsContentLocale } = loadDocsHubLocale(projectRoot)
   const markdown = renderIrSpecMarkdown(specShape, {
     testcases: [],
     output: { specFile: path.basename(mdOut), testcasesDir: 'testcases' },
     devAppBaseUrl: context.devAppBaseUrl ?? '',
     projectRoot,
+    docsContentLocale,
   })
   await mkdir(path.dirname(mdOut), { recursive: true })
   await writeFile(mdOut, markdown, 'utf8')

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/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/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/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.