@shanyucoder/flowgrid 0.1.8 → 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/qa-item.mjs

@@ -0,0 +1,91 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Ajv2020 from 'ajv/dist/2020.js'
+import { parse } from 'yaml'
+
+export const QA_ITEM_SCHEMA_ID = 'flowgrid-qa-item/v1'
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..')
+
+let compiledValidator = null
+
+function loadSchema() {
+  const schemaPath = path.join(packageRoot, 'templates/schemas/qa-item.schema.json')
+  return JSON.parse(readFileSync(schemaPath, 'utf8'))
+}
+
+/**
+ * @param {Date} [date]
+ * @returns {string} YYYYMMDD HH:mm
+ */
+export function formatQaAt(date = new Date()) {
+  const d = date
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  const h = String(d.getHours()).padStart(2, '0')
+  const min = String(d.getMinutes()).padStart(2, '0')
+  return `${y}${m}${day} ${h}:${min}`
+}
+
+/**
+ * @param {string} screen e.g. W-HOTEL-LIST
+ */
+export function suggestQaShort(screen) {
+  const s = String(screen ?? '').trim()
+  if (!s) return 'QA'
+  if (/^W-/i.test(s)) return s.slice(2).toUpperCase()
+  return s.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '').toUpperCase()
+}
+
+/**
+ * @param {string} hubRoot
+ * @param {string} shortSlug e.g. HOTEL-LIST
+ * @returns {string} four-digit sequence
+ */
+export function nextQaSequence(hubRoot, shortSlug) {
+  const qaDir = path.join(path.resolve(hubRoot), 'qa')
+  const prefix = `${shortSlug}_`
+  let max = 0
+  const scan = (dir) => {
+    if (!existsSync(dir)) return
+    for (const name of readdirSync(dir)) {
+      if (!name.toLowerCase().startsWith(prefix.toLowerCase())) continue
+      const m = name.match(/_(\d{4})\.ya?ml$/i)
+      if (m) max = Math.max(max, Number.parseInt(m[1], 10))
+    }
+  }
+  scan(qaDir)
+  scan(path.join(qaDir, 'open'))
+  return String(max + 1).padStart(4, '0')
+}
+
+/**
+ * @param {string} hubRoot
+ * @param {string} shortSlug
+ */
+export function nextQaId(hubRoot, shortSlug) {
+  return `${shortSlug}_${nextQaSequence(hubRoot, shortSlug)}`
+}
+
+/**
+ * @param {unknown} doc parsed YAML object
+ * @returns {{ ok: true } | { ok: false, errors: import('ajv').ErrorObject[] }}
+ */
+export function validateQaItem(doc) {
+  if (!compiledValidator) {
+    compiledValidator = new Ajv2020({ allErrors: true }).compile(loadSchema())
+  }
+  const ok = compiledValidator(doc)
+  if (ok) return { ok: true }
+  return { ok: false, errors: compiledValidator.errors ?? [] }
+}
+
+/**
+ * @param {string} filePath
+ */
+export function validateQaItemFile(filePath) {
+  const doc = parse(readFileSync(filePath, 'utf8'))
+  return validateQaItem(doc)
+}

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/lib/render-qa-list.mjs

@@ -4,10 +4,23 @@ import { parse } from 'yaml'
 
 export const QA_LIST_FILE = 'qa/index.md'
 
-function listOpenYaml(openDir) {
+function listQaYamlFiles(qaDir) {
+  if (!existsSync(qaDir)) return []
+  const out = []
+  for (const name of readdirSync(qaDir)) {
+    if (!/\.ya?ml$/i.test(name)) continue
+    if (name === 'index.yaml') continue
+    out.push(path.join(qaDir, name))
+  }
+  return out.sort()
+}
+
+function listLegacyOpenYaml(qaDir) {
+  const openDir = path.join(qaDir, 'open')
   if (!existsSync(openDir)) return []
   return readdirSync(openDir)
-    .filter((n) => /^QA-.*\.ya?ml$/i.test(n))
+    .filter((n) => /\.ya?ml$/i.test(n))
+    .map((n) => path.join(openDir, n))
     .sort()
 }
 
@@ -16,41 +29,126 @@ function oneLine(text) {
   return String(text).trim().split(/\n/)[0].trim()
 }
 
+function escapeCell(s) {
+  return String(s ?? '')
+    .replace(/\|/g, '\\|')
+    .replace(/\n/g, ' ')
+    .trim()
+}
+
+function lastUpdate(doc) {
+  const updates = Array.isArray(doc?.updates) ? doc.updates : []
+  if (updates.length) return updates[updates.length - 1]
+  return null
+}
+
+function summaryFromDoc(doc) {
+  const last = lastUpdate(doc)
+  if (last?.text) return oneLine(last.text)
+  if (doc?.question) return oneLine(doc.question)
+  if (doc?.resolution?.summary) return oneLine(doc.resolution.summary)
+  return oneLine(doc?.kind) || '—'
+}
+
+function lastAt(doc) {
+  const last = lastUpdate(doc)
+  if (last?.at) return String(last.at)
+  if (doc?.resolution?.decidedAt) return String(doc.resolution.decidedAt)
+  return '—'
+}
+
+function isOpen(doc) {
+  if (doc?.status === 'closed') return false
+  if (doc?.status === 'open') return true
+  if (doc?.resolution) return false
+  return true
+}
+
 /**
- * Always write qa/index.md (empty body when no qa/open files).
+ * @param {string} full — absolute path to yaml
+ * @param {string} linkName — basename for markdown link
+ */
+function catalogRow(full, linkName) {
+  let id = linkName.replace(/\.ya?ml$/i, '')
+  let screen = ''
+  let kind = ''
+  let summary = ''
+  let lastAtStr = '—'
+  let state = 'open'
+  try {
+    const doc = parse(readFileSync(full, 'utf8')) ?? {}
+    if (doc.id) id = String(doc.id)
+    if (doc.screen) screen = String(doc.screen)
+    if (doc.kind) kind = String(doc.kind)
+    summary = summaryFromDoc(doc)
+    lastAtStr = lastAt(doc)
+    state = isOpen(doc) ? 'open' : 'closed'
+  } catch {
+    /* still list */
+  }
+
+  const relLink = full.includes(`${path.sep}open${path.sep}`)
+    ? `open/${linkName}`
+    : linkName
+
+  return {
+    id,
+    link: `[${id}](${relLink})`,
+    state,
+    screen: screen || '—',
+    lastAt: lastAtStr,
+    summary: summary || kind || '—',
+    sortKey: `${lastAtStr}\t${id}`,
+  }
+}
+
+/**
+ * Always write qa/index.md — catalog table only (SSOT = per-id YAML files).
  */
 export function writeQaList(root = process.cwd()) {
   const hub = path.resolve(root)
   const qaDir = path.join(hub, 'qa')
-  const openDir = path.join(qaDir, 'open')
   mkdirSync(qaDir, { recursive: true })
 
-  const lines = ['# QA', '', '_Sinh bởi `flowgrid render`. Đóng bằng `/qa-resolve`._', '']
-  const files = listOpenYaml(openDir)
-  if (!files.length) {
-    lines.push('_Không có câu hỏi mở._', '')
+  const seen = new Set()
+  const rows = []
+  for (const full of [...listQaYamlFiles(qaDir), ...listLegacyOpenYaml(qaDir)]) {
+    const name = path.basename(full)
+    if (seen.has(name)) continue
+    seen.add(name)
+    rows.push(catalogRow(full, name))
+  }
+  rows.sort((a, b) => a.sortKey.localeCompare(b.sortKey))
+
+  const lines = [
+    '# QA — catalog',
+    '',
+    '_Sinh bởi `flowgrid render` — **chỉ trạng thái + link**. Nội dung SSOT: một file YAML / mã QA._',
+    '',
+    'Workflow: [qa-team.md](../workflows/qa-team.md) · `/qa-resolve` · `/qa-review`',
+    '',
+    '| Mã | Status | Screen | Cập nhật cuối | Tóm tắt |',
+    '| --- | --- | --- | --- | --- |',
+  ]
+
+  if (!rows.length) {
+    lines.push('| _—_ | _empty_ | — | — | Không có QA file |', '')
   } else {
-    for (const name of files) {
-      const full = path.join(openDir, name)
-      let id = name.replace(/\.ya?ml$/i, '')
-      let kind = ''
-      let question = ''
-      try {
-        const doc = parse(readFileSync(full, 'utf8')) ?? {}
-        if (doc.id) id = String(doc.id)
-        if (doc.kind) kind = String(doc.kind)
-        question = oneLine(doc.question)
-      } catch {
-        /* list the file anyway */
-      }
-      const bits = [`[${id}](open/${name})`]
-      if (kind) bits.push(kind)
-      if (question) bits.push(question)
-      lines.push(`- ${bits.join(' — ')}`)
+    for (const r of rows) {
+      lines.push(
+        `| ${r.link} | ${escapeCell(r.state)} | ${escapeCell(r.screen)} | ${escapeCell(r.lastAt)} | ${escapeCell(r.summary)} |`,
+      )
     }
     lines.push('')
   }
 
+  lines.push(
+    '## Đọc timeline',
+    '',
+    'Mở file YAML — đọc `updates[]` từ trên xuống (append-only). Không copy full log vào index.',
+    '',
+  )
+
   const out = path.join(hub, ...QA_LIST_FILE.split('/'))
   writeFileSync(out, lines.join('\n'))
   return out