@shanyucoder/flowgrid 0.1.8 → 0.1.9

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

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

@@ -10,7 +10,7 @@
 | 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` |
+| Open questions | `qa/*.yaml` |
 
 **Author path:** `.flowgrid/templates/feature.bundle.yaml` + `bundle-authoring.md` only. **`design-spec.yaml` deprecated.**
 

package/harness/docs/schemas/flowgrid-docs/qa-item.schema.json

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

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

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

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

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

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

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

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

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

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

@@ -42,7 +42,7 @@ disable-model-invocation: true
 ## Rule: Audit interlock (sau reconcile)
 
 - **[MANDATORY]** After any bundle patch that touches `design.*`, `userStories`, `bundle.gen`, or `api` refs: run `flowgrid audit spec <bundle> --type <pageType>` (same profile rules as `/grill-dev`). Resolve `CONFIRM_DB_*` via `db-audit-wizard.md` before handoff.
-  - Patch structural `gaps[]`; defer remainder via `qa/open/` per Law 2.
+  - Patch structural `gaps[]`; defer remainder via `qa/` per Law 2.
   - Address `warnings[]` when reconcile changes business prose (`summary`, `successMetrics`, `nonGoals`, `userStories`).
   - ❌ Do not hand off FE until audit has been re-run post-reconcile.
 
@@ -81,6 +81,6 @@ disable-model-invocation: true
 
 ## Verification Checklist
 
-- [ ] Conflicts reconciled in `*.bundle.yaml`, or deferred with `qa/open/QA-…`. No `openQuestions`.
+- [ ] Conflicts reconciled in `*.bundle.yaml`, or deferred with `qa/<SHORT>_…`. No `openQuestions`.
 - [ ] `bundle.gen.codegen.profile` present and correct.
 - [ ] `flowgrid audit spec` re-run after reconcile; `flowgrid split` succeeded with zero errors.

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

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

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

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

package/harness/docs/skills/spec/SKILL.md

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

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

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

package/harness/fe/extracts/wire-audit-loop.md

@@ -47,7 +47,7 @@ Re-run **entire chain** after fixes in any lane (code, plan, or spec).
 | Business/spec/UX wrong vs what API actually returns | docs hub | `/update-spec` (paste-ready `/docs-hub` prompt) |
 | `01` / OpenAPI wrong; BE field/status codes | docs hub | `/api-update` → BE `/audit-api` → re-wire |
 | SC screen uncovered | tests-docs | `/testcase` or `/scenario` + `audit scenario` |
-| Intentional defer | docs | `qa/open` + `QA-*` / `coverage_deferred` on SC |
+| Intentional defer | docs | `qa` + `QA-*` / `coverage_deferred` on SC |
 
 **Forbidden:** patch `ir/*` or `01` from FE repo; invent AC on tests hub; skip `audit e2e` because manual QA passed.
 

package/harness/fe/skills/grill-wire/SKILL.md

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

package/harness/fe/skills/wire/SKILL.md

@@ -56,7 +56,7 @@ flowgrid audit e2e --e2e-root <playwright-dir> --tests-docs "$FLOWGRID_TESTS_DOC
 Optional: pass explicit `cases/**/TC-*.yaml` paths instead of `--tests-docs`.
 
 - Parse JSON: `missingInPlaywright`, `matrixRowsUncovered`, `orphanTestCases`, `orphanSpecs`, `gaps[]`.
-- **[MANDATORY]** Fix or defer every `critical` / `warning` gap before marking wire done; log deferrals in `qa/open` if team policy allows.
+- **[MANDATORY]** Fix or defer every `critical` / `warning` gap before marking wire done; log deferrals in `qa` if team policy allows.
 - **[MANDATORY]** Portal leaf with `apiRef`: `flowgrid audit fe-be <bundle.yaml>`.
 - **[MANDATORY]** When `SC-*` covers screen: `flowgrid audit scenario <SC.yaml> --tests-docs "$FLOWGRID_TESTS_DOC"`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shanyucoder/flowgrid",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Unified Local MCP Toolkit (Graph, DNA, Docs, Test, Codegen)",
   "type": "module",
   "main": "./dist/index.js",

package/templates/project-skeleton/qa/README.md

@@ -1,11 +1,7 @@
-# QA inbox (docs hub)
+# QA inbox
 
-Open customer / choice / tech-debt questions live here — **not** in `*.bundle.yaml`.
+One file per case: `qa/<SHORT>_0001.yaml`.
 
-- One file per open issue: `qa/open/QA-<bundle.id>-NNNN.yaml`
-- `bundle.id` is the screen leaf id from `/spec` (e.g. `cmp-adm-002-02-01-02`)
-- Sequence is **per screen** (`0001`, `0002`, …). Different screens never share a counter.
-- Close with **`/qa-resolve QA-<bundle.id>-NNNN`** plus the decision (skill deletes the file).
+After `flowgrid init`, copy from `.flowgrid/templates/qa-item.yaml` and follow `.flowgrid/templates/qa-authoring.md`.
 
-Template: `.flowgrid/templates/qa-item.yaml`  
-Rules: `.cursor/extracts/qa-inbox.md`
+Append-only `updates[]` · `flowgrid render` refreshes `index.md`.

package/templates/schemas/qa-item.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://platform.local/schemas/flowgrid-docs/qa-item.schema.json",
+  "title": "FlowGrid QA inbox item",
+  "type": "object",
+  "required": ["schema", "id", "status", "target", "updates"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "flowgrid-qa-item/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Z0-9][A-Z0-9._-]*_\\d{4}$",
+      "description": "Same as filename without .yaml — SHORT_NNNN"
+    },
+    "screen": {
+      "type": "string",
+      "description": "W-* or bundle page-id for humans and split matching"
+    },
+    "bundleId": {
+      "type": "string",
+      "description": "Legacy QA-<bundleId>-NNNN prefix; optional when screen/target.path enough"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["open", "closed"]
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["customer", "choice", "tech-debt", "integration", "coverage"]
+    },
+    "skill": {
+      "type": "string",
+      "description": "Skill that opened the gap — spec, grill-dev, api-spec, …"
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "target": {
+      "type": "object",
+      "required": ["path", "at"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Repo-relative path to bundle or 01-backend-spec.yaml"
+        },
+        "at": {
+          "type": "string",
+          "description": "YAML pointer — field gets #missing_info <id> until resolve"
+        }
+      }
+    },
+    "options": {
+      "type": "array",
+      "description": "Optional AskQuestion options captured when opening (audit trail)",
+      "items": {
+        "type": "object",
+        "required": ["label"],
+        "properties": {
+          "label": { "type": "string" },
+          "recommended": { "type": "boolean" }
+        }
+      }
+    },
+    "updates": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/update" }
+    }
+  },
+  "$defs": {
+    "update": {
+      "type": "object",
+      "required": ["at", "kind", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "at": {
+          "type": "string",
+          "pattern": "^\\d{8} \\d{2}:\\d{2}$",
+          "description": "YYYYMMDD HH:mm (team TZ)"
+        },
+        "by": { "type": "string" },
+        "kind": {
+          "type": "string",
+          "enum": ["question", "answer", "review", "note"]
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/templates/shared/bundle-authoring.md

@@ -303,13 +303,14 @@ actions:
 
 YAML only per schema. No explanation. No markdown.
 
-## Questions: AskQuestion wizard or hub `qa/open/`
+## Questions: AskQuestion wizard or hub `qa/`
 
 Do **not** write `openQuestions` anywhere. Schema/render không còn field này.
 
 - Member trả lời **ngay:** AskQuestion (options + Recommended + **Other**) → **STOP** → ghi field thật.
-- Member chọn **Other** mà **chưa quyết:** `.cursor/extracts/qa-inbox.md` → `qa/open/QA-<bundle.id>-NNNN.yaml`. Đóng sau bằng **`/qa-resolve <id>` + giải pháp**.
-- `grillStatus` có thể `done` khi vẫn còn file QA.
+- Member chọn **Log as Tech Debt:** copy `.flowgrid/templates/qa-item.yaml` — quy tắc field/timeline: **`qa-authoring.md`** · extract `qa-inbox.md`.
+- Đóng sau bằng **`/qa-resolve <id>` + giải pháp** (append `kind: answer`, `status: closed`).
+- `grillStatus` có thể `done` khi vẫn còn file QA `status: open`.
 
 ## YAML Syntax & Escaping Rules
 
@@ -318,7 +319,7 @@ Do **not** write `openQuestions` anywhere. Schema/render không còn field này.
 
 ## ir/spec.yaml vs ir/design.yaml
 
-`pnpm spec:split` ghi hai file. FlowGrid bộ docs grill **không** đọc `ir/*` khi author — chỉ bundle. Split ghi `"Q&A":` trên **`ir/spec.yaml`** (id `QA-<bundle.id>-NNNN` cách nhau bởi `, `) từ `qa/open/` — không nhét list vào bundle.
+`pnpm spec:split` ghi hai file. FlowGrid bộ docs grill **không** đọc `ir/*` khi author — chỉ bundle. Split ghi `"Q&A":` trên **`ir/spec.yaml`** (id `QA-<bundle.id>-NNNN` cách nhau bởi `, `) từ `qa/` — không nhét list vào bundle.
 
 Downstream (UI gen, API gen, testcase) đọc **chỉ `ir/design.yaml`**. Thiếu file = split/spec chưa xong. Story/copy chưa đủ thì **bổ sung design** (bundle.gen + split), không đọc `ir/spec.yaml`. `ir/spec.yaml` chỉ văn mô tả + `legacy` + `qa` (id treo).
 

package/templates/shared/ir-spec.yaml

@@ -14,5 +14,5 @@ actors: []
 requirements: []
 acceptance: []
 
-# Filled by spec:split from qa/open/QA-<id>-NNNN.yaml (comma-separated). Omit when none.
+# Filled by spec:split from qa/<SHORT>_NNNN.yaml (comma-separated). Omit when none.
 # "Q&A": QA-role-domain-function-0001, QA-role-domain-function-0002

package/templates/shared/qa-authoring.md

@@ -0,0 +1,78 @@
+# flowgrid-qa-item/v1 — authoring rules (QA inbox)
+
+Hub template: `.flowgrid/templates/qa-item.yaml` (sau `flowgrid init`) · Workflow: `docs/workflows/qa-team.md`
+
+## File naming
+
+| Part | Rule | Example |
+|------|------|---------|
+| **SHORT** | Slug màn/module, ổn định, `A-Z0-9` + `-` | `HOTEL-LIST`, `ADM-AUTH` |
+| **NNNN** | Tăng dần theo SHORT (0001…) | `0001`, `0002` |
+| **Path** | `qa/<SHORT>_<NNNN>.yaml` | `qa/HOTEL-LIST_0001.yaml` |
+| **id** | **Bắt buộc** = basename không `.yaml` | `HOTEL-LIST_0001` |
+
+Legacy id `QA-<page-id>-NNNN` vẫn đọc được — file mới dùng `<SHORT>_NNNN`.
+
+Gợi ý SHORT từ `W-HOTEL-LIST` → `HOTEL-LIST` (bỏ prefix `W-`). Team có thể chọn slug module cố định (vd. `ADM-AUTH` cho nhiều màn auth).
+
+## Top-level fields
+
+| Key | Required | Purpose |
+|-----|----------|---------|
+| `schema` | yes | Luôn `flowgrid-qa-item/v1` |
+| `id` | yes | Khớp tên file |
+| `status` | yes | `open` \| `closed` |
+| `target.path` | yes | Bundle hoặc `01-backend-spec.yaml` (repo-relative) |
+| `target.at` | yes | Pointer field — gắn `#missing_info <id>` / `#tech-debt:<id>` |
+| `updates` | yes | Timeline append-only (≥1 dòng) |
+| `screen` | khuyến nghị | `W-*` hoặc `page-id` — catalog + split |
+| `bundleId` | khi legacy | `page-id` bundle để `Q&A` trên `ir/spec.yaml` |
+| `kind` | khuyến nghị | `customer` \| `choice` \| `tech-debt` \| `integration` \| `coverage` |
+| `skill` | khuyến nghị | Skill mở gap: `spec`, `grill-dev`, `api-spec`, … |
+| `options` | optional | Copy options AskQuestion khi mở (audit) |
+| `tags` | optional | Mirror tag đã gắn trên spec |
+
+## `updates[]` (append-only)
+
+**Không** sửa/xóa dòng cũ. Chỉ **thêm** cuối mảng.
+
+| `kind` | Ai / khi |
+|--------|----------|
+| `question` | Mở QA (Log Tech Debt) — **dòng đầu** |
+| `answer` | `/qa-resolve` — sau khi patch `target.at` |
+| `review` | `/qa-review` — `approved:` hoặc `needs-change:` |
+| `note` | Ghi chú, không đổi spec |
+
+| `at` | Format **bắt buộc** | `20260930 08:00` (YYYYMMDD HH:mm) |
+| `by` | Member / role | `ba-lead`, `middle-dev` |
+| `text` | Nội dung | Block `\|` multiline |
+
+### Vòng đời status
+
+- Mở file: `status: open`, `updates[0].kind: question`
+- `/qa-resolve`: append `answer`, `status: closed`, gỡ tag trên spec
+- `/qa-review` + `needs-change`: append `review`, **`status: open`** lại (cùng file)
+
+## Agent workflow (mở QA)
+
+1. Đọc **whole** `.flowgrid/templates/qa-item.yaml` + file này.
+2. Chọn SHORT (team convention hoặc từ `screen`).
+3. `nextQaId(hub, SHORT)` hoặc glob `qa/<SHORT>_*.yaml` → max NNNN + 1.
+4. Copy template → `qa/<SHORT>_<NNNN>.yaml`; set `id`, `target`, `at` now, `updates[0]`.
+5. Patch spec: `#missing_info <id>` trên field `target.at`.
+6. `flowgrid split` + `flowgrid render`.
+
+## Agent output
+
+- **YAML only** khi tạo/sửa QA file — không markdown giải thích trong repo.
+- Quote string có `:`; multiline dùng `|`.
+
+## Không dùng QA file cho
+
+- ADR → `architecture/09-decisions`
+- Risk dài hạn → `architecture/11-risks`
+- `openQuestions` trên bundle — **cấm**
+
+## Schema
+
+Validate (optional CI): `templates/schemas/qa-item.schema.json` · `flowgrid` test `validateQaItem`.

package/templates/shared/qa-item.yaml

@@ -1,15 +1,36 @@
-# Copy to qa/open/QA-<bundle.id>-NNNN.yaml — do not leave this file in qa/open/.
-id: QA-cmp-adm-002-02-01-02-0001
-kind: customer # customer | choice | tech-debt
-skill: spec # spec | grill-bqa | grill-dev | grill-docs | api-spec | api-update
+# flowgrid-qa-item/v1 — Authoring: qa-authoring.md · Hub: docs/workflows/qa-team.md
+# Copy to qa/<SHORT>_NNNN.yaml (id = basename without .yaml). Append-only updates[].
+
+schema: flowgrid-qa-item/v1
+id: HOTEL-LIST_0001
+screen: W-HOTEL-LIST
+bundleId: cmp-adm-000-01-01
+status: open
+kind: tech-debt
+skill: spec
+tags:
+  - "#missing_info HOTEL-LIST_0001"
 target:
-  path: surfaces/<surface>/CMP-*/<NN…>/<slug>.bundle.yaml
-  at: design.zones.main.items.title.purpose
-question: |
-  What is still unknown?
-options: []
-# - id: a
-#   text: Option A
-#   recommended: true
-# - id: other
-#   text: Member supplies copy
+  path: surfaces/<surface>/CMP-*/<slug>.bundle.yaml
+  at: design.sections.main.items.filter_timezone.purpose
+options:
+  - label: "(Recommended) Theo timezone property"
+    recommended: true
+  - label: Theo locale user
+updates:
+  - at: "20260930 08:00"
+    by: <member-id>
+    kind: question
+    text: |
+      Filter timezone lấy theo property hay user locale?
+# Append only — never delete or rewrite prior lines:
+#  - at: "20260930 10:00"
+#    by: ba-lead
+#    kind: answer
+#    text: |
+#      Theo property TZ; label UTC+7 trên UI.
+#  - at: "20261001 08:00"
+#    by: senior
+#    kind: review
+#    text: |
+#      needs-change: thêm AC khi property chưa set TZ.

package/templates/shared/tpl-api-contract.md

@@ -112,7 +112,7 @@ Skill: `/openapi` · Redoc/Swagger UI: `openapi_build_ui` (tùy hub).
 
 - Chuỗi có `:` → bọc `"..."`.
 - Chạy `flowgrid api:check` trước handoff.
-- Thiếu fact → AskQuestion hoặc `qa/open/` — **không** `openQuestions` trong YAML.
+- Thiếu fact → AskQuestion hoặc `qa/` — **không** `openQuestions` trong YAML.
 
 ---