@shanyucoder/flowgrid 0.1.11 → 0.1.12

package/engines/spec/lib/audit-interaction-cases.mjs

@@ -0,0 +1,185 @@
+/**
+ * Two-step audit for bundle interactionCases (see harness/docs/extracts/agent-design-context.md).
+ */
+
+function countMutationActions(design) {
+  const actions = design?.actions
+  if (!Array.isArray(actions)) return 0
+  return actions.filter((a) => a && (a.executionContract || a.apiRef)).length
+}
+
+export function interactionCasesComplexityTriggers(bundle) {
+  const design = bundle?.design ?? {}
+  const statuses = design?.stateMatrix?.recordStatuses
+  const statusCount = Array.isArray(statuses) ? statuses.length : 0
+  const mutations = countMutationActions(design)
+  const scenarios = bundle?.userStories?.scenarios
+  const scenarioCount = Array.isArray(scenarios) ? scenarios.length : 0
+  const listOnly =
+    design?.codegen?.profile === 'list' ||
+    String(bundle?.gen?.codegen?.profile || '') === 'list'
+
+  return {
+    complex:
+      statusCount >= 3 ||
+      mutations >= 2 ||
+      (!listOnly && scenarioCount >= 4) ||
+      Boolean(design?.stateMatrix?.behaviors?.length >= 3),
+    statusCount,
+    mutations,
+    scenarioCount,
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} bundle parsed bundle YAML
+ * @param {{ addGap: Function, addConfirm: Function, addWarning: Function }} hooks
+ */
+export function auditInteractionCases(bundle, hooks) {
+  const { addGap, addConfirm, addWarning } = hooks
+  const ic = bundle?.interactionCases
+  const { complex, statusCount, mutations } = interactionCasesComplexityTriggers(bundle)
+
+  if (ic == null) {
+    if (!complex) return
+    addConfirm(
+      'CONFIRM_INTERACTION_CASES_POLICY',
+      'interactionCases',
+      'Screen has complex state/actions — declare interactionCases (IC-* + sequenceDiagram)?',
+      [
+        '(Recommended) Yes — set interactionCases.policy: required and items[]',
+        'No — simple screen (set interactionCases.policy: skip + skipReason)',
+        'Other — note in qa/',
+      ],
+      0,
+    )
+    return
+  }
+
+  const policy = ic.policy
+  if (policy === 'skip') {
+    if (!String(ic.skipReason || '').trim()) {
+      addWarning(
+        'INTERACTION_CASES_SKIP_NO_REASON',
+        'interactionCases.skipReason',
+        'interactionCases.policy is skip but skipReason is empty.',
+        'Declare skipReason explaining why L2 sequences are not needed.',
+      )
+    }
+    return
+  }
+
+  const items = Array.isArray(ic.items) ? ic.items : []
+
+  if (policy === 'required' && items.length === 0) {
+    addGap(
+      'INTERACTION_CASES_ITEMS_MISSING',
+      'critical',
+      'interactionCases.items',
+      'interactionCases.policy is required but items[] is empty.',
+      'Add at least one IC-* item with description and sequenceDiagram.',
+    )
+    return
+  }
+
+  if (items.length === 0) return
+
+  const actionIds = new Set(
+    (bundle?.design?.actions || [])
+      .map((a) => a?.id)
+      .filter(Boolean),
+  )
+  const statuses = new Set(bundle?.design?.stateMatrix?.recordStatuses || [])
+
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i]
+    const base = `interactionCases.items[${i}]`
+    if (!item?.id) {
+      addGap(
+        'INTERACTION_CASES_MISSING_ID',
+        'critical',
+        `${base}.id`,
+        'Interaction case missing id (use IC-*).',
+        'Declare id: IC-SUBMIT-HAPPY',
+      )
+    } else if (!/^IC-[A-Z0-9][A-Z0-9-]*$/i.test(String(item.id))) {
+      addWarning(
+        'INTERACTION_CASES_ID_FORMAT',
+        `${base}.id`,
+        `Interaction case id "${item.id}" should match IC-* pattern.`,
+        'Rename to IC-<DOMAIN>-<CASE> (e.g. IC-SUBMIT-409).',
+      )
+    }
+    if (!String(item?.title || '').trim()) {
+      addGap(
+        'INTERACTION_CASES_MISSING_TITLE',
+        'critical',
+        `${base}.title`,
+        'Interaction case missing title.',
+        'Add short title for reviewers and agents.',
+      )
+    }
+    if (!String(item?.description || '').trim()) {
+      addGap(
+        'INTERACTION_CASES_MISSING_DESCRIPTION',
+        'critical',
+        `${base}.description`,
+        'Interaction case missing description (user case prose).',
+        'Describe user steps and expected UI/API feedback.',
+      )
+    }
+    const seq = String(item?.sequenceDiagram || '')
+    if (!seq.includes('sequenceDiagram')) {
+      addGap(
+        'INTERACTION_CASES_MISSING_SEQUENCE',
+        'critical',
+        `${base}.sequenceDiagram`,
+        'Interaction case missing Mermaid sequenceDiagram.',
+        'Add sequenceDiagram with alt/else for error paths when applicable.',
+      )
+    } else if (!/alt\s+/i.test(seq) && complex) {
+      addWarning(
+        'INTERACTION_CASES_NO_ALT',
+        `${base}.sequenceDiagram`,
+        'Sequence diagram has no alt/else block — recommend at least one error branch.',
+        'Model validation, 409, or timeout with alt/else.',
+      )
+    }
+    const actionId = item?.links?.actionId
+    if (actionId && actionIds.size && !actionIds.has(actionId)) {
+      addWarning(
+        'INTERACTION_CASES_UNKNOWN_ACTION',
+        `${base}.links.actionId`,
+        `links.actionId "${actionId}" not found in design.actions.`,
+        'Align with an existing action id or add the action.',
+      )
+    }
+    const st = item?.links?.recordStatus
+    if (st && statuses.size && !statuses.has(st)) {
+      addWarning(
+        'INTERACTION_CASES_UNKNOWN_STATUS',
+        `${base}.links.recordStatus`,
+        `links.recordStatus "${st}" not in stateMatrix.recordStatuses.`,
+        `Use one of: ${[...statuses].join(', ')}`,
+      )
+    }
+  }
+
+  if (policy === 'required' && mutations >= 2 && items.length < mutations) {
+    addWarning(
+      'INTERACTION_CASES_FEW_ITEMS',
+      'interactionCases.items',
+      `Only ${items.length} interaction case(s) for ${mutations} mutation action(s).`,
+      'Consider one IC-* per critical mutation path (happy + conflict).',
+    )
+  }
+
+  if (complex && !policy) {
+    addWarning(
+      'INTERACTION_CASES_POLICY_UNSET',
+      'interactionCases.policy',
+      'interactionCases present but policy not set to required or skip.',
+      'Set policy: required or policy: skip with skipReason.',
+    )
+  }
+}

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

@@ -20,6 +20,7 @@ import {
 import { applyOpenQaField } from './open-qa.mjs'
 import { applyDesignApiFrom01 } from './hydrate-design-api.mjs'
 import { isPlaceholderLegacy, projectBusinessPage } from './project-business-layout.mjs'
+import { applyInteractionCasesToIr } from './interaction-cases.mjs'
 
 export function bundlePageId(bundle) {
   const v = bundle?.['page-id'] ?? bundle?.pageId ?? bundle?.id
@@ -39,6 +40,12 @@ export function buildIrFromBundle(bundle) {
   const pageId = bundlePageId(bundle)
   const legacy = { id: pageId, ...(bundle.legacy ?? {}) }
   const design = buildDesignIr(bundle, designSpec, gen)
+  if (bundle.interactionCases != null) {
+    delete spec.interactionCases
+    applyInteractionCasesToIr(spec, design, bundle.interactionCases)
+  } else if (spec.interactionCases) {
+    delete spec.interactionCases
+  }
 
   return { spec, legacy, design, designSpec, gen }
 }

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

@@ -15,6 +15,7 @@ export const BUNDLE_META_KEYS = [
   'scopeIn',
   'nonGoals',
   'userFlows',
+  'interactionCases',
   'nfr',
   'userStories',
   'specOrigin',

package/engines/spec/lib/interaction-cases.mjs

@@ -0,0 +1,46 @@
+/**
+ * Split bundle interactionCases → ir/spec (prose) + ir/design (sequenceDiagram only).
+ */
+
+/**
+ * @param {unknown} interactionCases
+ * @returns {{ specPart: object|null, designPart: object|null }}
+ */
+export function partitionInteractionCasesForIr(interactionCases) {
+  if (!interactionCases || typeof interactionCases !== 'object') {
+    return { specPart: null, designPart: null }
+  }
+  const { policy, skipReason, items } = interactionCases
+  const specPart = {
+    ...(policy != null ? { policy } : {}),
+    ...(skipReason != null && String(skipReason).trim() ? { skipReason } : {}),
+    items: Array.isArray(items)
+      ? items.map((item) => {
+          if (!item || typeof item !== 'object') return item
+          const { id, title, description, links } = item
+          return { id, title, description, links }
+        })
+      : [],
+  }
+  const designItems = Array.isArray(items)
+    ? items
+        .filter((item) => item && typeof item === 'object' && item.sequenceDiagram)
+        .map(({ id, sequenceDiagram }) => ({ id, sequenceDiagram }))
+    : []
+  const designPart = designItems.length ? { items: designItems } : null
+  return { specPart, designPart }
+}
+
+/**
+ * @param {Record<string, unknown>} spec
+ * @param {Record<string, unknown>} design
+ * @param {unknown} interactionCases from bundle
+ */
+export function applyInteractionCasesToIr(spec, design, interactionCases) {
+  const { specPart, designPart } = partitionInteractionCasesForIr(interactionCases)
+  if (!specPart && !designPart) return
+  if (specPart && (specPart.policy || specPart.skipReason || specPart.items?.length)) {
+    spec.interactionCases = specPart
+  }
+  if (designPart) design.interactionCases = designPart
+}

package/engines/spec/split-bundle.mjs

@@ -34,7 +34,7 @@ async function main() {
         const mdRel = mdOut ? path.relative(process.cwd(), mdOut) : null
         const genDir = mdOut ? path.dirname(mdOut) : null
         const extra = genDir
-          ? ['data-model.md', 'api.md']
+          ? ['data-model.md', 'api.md', 'design.md']
               .filter((name) => fs.existsSync(path.join(genDir, name)))
               .map((name) => path.relative(process.cwd(), path.join(genDir, name)))
           : []

package/harness/docs/extracts/agent-design-context.md

@@ -0,0 +1,124 @@
+# Agent design context (L1 FLOW · L2 interactionCases · NFR · ACP)
+
+**Status:** Implemented — `interactionCases`, split/render, audit, ACP skills, `screenToFlows`, MCP `linkedFlows` / `flowgrid_docs_user_flows?id=`.
+
+**See also:** `product-id-convention.md`. BE runtime-sequence diagram layer is a future phase (not L1/L2).
+
+---
+
+## Problem
+
+Agents often read only `*.bundle.yaml` + `ir/design.yaml` and miss three independent axes:
+
+| Axis | SSOT | Agent gap |
+| --- | --- | --- |
+| **L1 Journey (cross-screen)** | `FLOW-*.md` (Markdown only) | No enforced read before codegen on `W-*` |
+| **L2 Interaction (one screen)** | `interactionCases` on bundle + `stateMatrix` / `actions` | No timeline diagram per branch (409, double-submit, …) |
+| **NFR overlay** | `bundle.nfr` + `architecture/08-*` links | NFR treated as appendix, not constraint |
+
+**Sequence diagrams at the right layer materially improve codegen quality.**
+
+---
+
+## Layer model
+
+| Layer | SSOT | Format | Question answered |
+| --- | --- | --- | --- |
+| **L1** | `FLOW-*` · `common/user-flows/` | MD + **§6 `sequenceDiagram`** | Where the user goes across screens |
+| **L2** | `interactionCases` on bundle (optional) | YAML → split | One `W-*`: cases + per-case sequence |
+| **L3** | `design.stateMatrix` | YAML | Machine state/button matrix |
+| **L4** | bundle + `ir/design.yaml` + `01` | YAML | Fields, actions, apiRef, outcomes |
+| **NFR** | `bundle.nfr` | MD bullets | Constraints on all cases |
+
+**Do not** put L2 single-screen branches into FLOW MD. **Do not** require L2 on trivial list-only GET screens.
+
+---
+
+## L1 ↔ leaf link: `userFlows` on bundle
+
+```yaml
+userFlows: |
+  - FLOW-checkout — role: step-3-ops — screens: W-ADM-ORD-01 (this leaf)
+```
+
+| Token | Agent use |
+| --- | --- |
+| `FLOW-*` | Open FLOW MD SSOT |
+| `role` | Focus §4 stage |
+| `screens` + `(this leaf)` | Filter journey to current screen |
+
+Resolve FLOW paths: `architecture/03-user-flows/<FLOW>.md`, `surfaces/**/common/user-flows/<FLOW>.md`.
+
+**Discovery:** `flowgrid_docs_route("W-…")` → `linkedFlows[]`; index `registries/docs-index.json` → `screenToFlows`.
+
+---
+
+## L2: `interactionCases` on bundle
+
+Authoring SSOT: `feature.bundle.yaml` (not separate FLOW files).
+
+```yaml
+interactionCases:
+  policy: required | skip
+  skipReason: ""   # required when policy: skip
+  items:
+    - id: IC-SUBMIT-409
+      title: ...
+      description: ...
+      sequenceDiagram: |
+        sequenceDiagram
+          ...
+```
+
+**Split:** prose → `ir/spec.yaml` → `ir/generated/spec.md` (§ Interaction cases); diagrams only → `ir/design.yaml` → `ir/generated/design.md`.
+
+**Codegen read order for L2:** `spec.md` prose + `design.md` mermaid + `stateMatrix` / `actions` — not FLOW.
+
+---
+
+## Agent context package (ACP) — read before codegen
+
+For target leaf `W-*`:
+
+1. **`userFlows`** → each **`FLOW-*.md`** (§3–§4 for this screen, **§6 sequence**).
+2. **`bundle.nfr`** (+ linked `architecture/08-cross-cutting/*` when cited).
+3. **`ir/generated/design.md`** when `interactionCases.policy: required` (after split + render).
+4. **`ir/design.yaml`** + **`01-backend-spec.yaml`**.
+5. Then patch `bundle.gen` / run gen.
+
+**Chat checklist:** FLOW ids read · NFR read · L2 design.md yes/no.
+
+**Skills:** `/spec` (declare `userFlows` when cross-screen); `/grill-dev`, `/prototype`, `/api-spec` (ACP); `/user-flow` (author FLOW + §6, trace `W-*` in §5).
+
+---
+
+## Audit (`flowgrid audit spec`)
+
+**Step 1 — policy confirm** when screen is complex and `interactionCases` missing:
+
+- Emit `CONFIRM_INTERACTION_CASES_POLICY` in `confirms[]`.
+- Options: **(Recommended) required** — set `policy: required` + `items[]`; **skip** — `policy: skip` + `skipReason`; **Other** (free text).
+
+**Step 2 — item validation** when `policy: required` or `items.length > 0`:
+
+- Each item needs `id`, `title`, `description`, `sequenceDiagram`.
+- Optional `links.actionId`, `links.recordStatus`, `links.scenario`.
+
+Skip step 1 when `interactionCases.policy: skip` is already declared.
+
+---
+
+## VitePress (member review)
+
+| Page | Source |
+| --- | --- |
+| Spec | `ir/generated/spec.md` |
+| Linked flows | Rendered from `userFlows` |
+| Design sequences | `ir/generated/design.md` |
+| API | `ir/generated/api.md` |
+
+---
+
+## One-line summary
+
+**L1:** `/user-flow` → `FLOW-*.md` + §6; leaf links via **`userFlows`**. **NFR:** mandatory read before design/API. **L2:** **`interactionCases`** on bundle → `spec.md` + `design.md`; never in FLOW.

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

@@ -28,12 +28,14 @@
       ".cursor/extracts/db-audit-wizard.md",
       ".cursor/extracts/agent-execution-protocol.md",
       ".cursor/extracts/common-scope.md",
-      ".cursor/extracts/product-id-convention.md"
+      ".cursor/extracts/product-id-convention.md",
+      ".cursor/extracts/agent-design-context.md"
     ],
     "spec-core": [
       ".cursor/extracts/spec-core.md",
       ".cursor/extracts/common-scope.md",
-      ".cursor/extracts/product-id-convention.md"
+      ".cursor/extracts/product-id-convention.md",
+      ".cursor/extracts/agent-design-context.md"
     ],
     "bqa-grill": [
       ".cursor/extracts/grill/validation.md",
@@ -43,7 +45,8 @@
     "dev-grill": [
       ".cursor/extracts/codegen/readiness.md",
       ".cursor/extracts/docs-mark-detect.md",
-      ".cursor/extracts/db-audit-wizard.md"
+      ".cursor/extracts/db-audit-wizard.md",
+      ".cursor/extracts/agent-design-context.md"
     ],
     "grill-docs": [
       ".cursor/extracts/grill-docs-reconcile.md",

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

@@ -18,6 +18,10 @@ Shared extracts: `spec-evolution.md`, `api-spec-sync.md`, `entity-relationship.m
 
 Hashtag extracts: `#call-external` → `call-external.md`; `#cross-entity-service` → `cross-entity-service.md`.
 
+## Agent context (ACP) before `01`
+
+Per **`agent-design-context.md`**: (1) `userFlows` → `FLOW-*.md` §6 (`flowgrid_docs_user_flows` / `flowgrid_docs_route`); (2) `bundle.nfr`; (3) `ir/generated/design.md` if `interactionCases.policy: required`; (4) `ir/design.yaml` + `01`. Print checklist: FLOW · NFR · L2.
+
 ---
 
 ## Rule: Audit Interlock

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

@@ -28,25 +28,38 @@ disable-model-invocation: true
 
 ---
 
+## Rule: Agent context (ACP) before codegen
+
+Per **`agent-design-context.md`** — read **before** patching `bundle.gen` / codegen:
+
+1. **`userFlows`** → each linked **`FLOW-*.md`** (§3–§4 for this `W-*`, **§6 sequence**).
+2. **`bundle.nfr`** (+ linked `architecture/08` if cited).
+3. **`ir/generated/design.md`** when `interactionCases.policy: required` (after `split` + `render`).
+4. Then **`ir/design.yaml`** + **`01`**.
+
+Print checklist in chat: FLOW ids read · NFR read · L2 design.md yes/no.
+
+---
+
 ## Rule: Audit Interlock with Page Type
 
 - **[MANDATORY]** Before grilling, run: `flowgrid audit spec <bundle> --type <profile>`. Treat `warnings[]` as non-blocking; nudge BQA via handoff if summary still has `[placeholder]` brackets.
 - **[MANDATORY]** After `bundle.gen` patch: `flowgrid split` + `flowgrid render` (FE uses `ir/design.yaml`; BA PDF path uses `ir/generated/spec.md`).
-  - `<profile>` lấy từ `gen.codegen.profile` đã xác nhận (list | create | detail | admin-crud | auth | ...).
-  - Nếu profile chưa set → hỏi member xác định profile trước, KHÔNG chạy audit với `--type unknown`.
+  - `<profile>` comes from confirmed `gen.codegen.profile` (list | create | detail | admin-crud | auth | ...).
+  - If profile is unset → ask the member to confirm profile first; do **not** run audit with `--type unknown`.
   - Script output `gaps[]` + `confirms[]` (`CONFIRM_UX_*`, **`CONFIRM_DB_*`** — `db-audit-wizard.md`).
   - Agent patches structural `gaps[]`; UX/DB confirms → wizard; BE drift → `/api-update` then re-audit.
 
 ---
 
-## Rule: Zone-Based Grill (chống Lost-in-Middle)
+## Rule: Zone-Based Grill (avoid lost-in-the-middle)
 
-- **[MANDATORY]** Grill theo zone, KHÔNG grill toàn bộ bundle 1 lần.
-- **[MANDATORY]** Chia bundle thành zones linh động theo nội dung thực:
-  - Mỗi turn grill 1 zone: đọc zone data → phân tích chất (logic, consistency, cross-field gaps) → bổ sung/sửa.
-  - Nếu zone quá lớn → chia nhỏ tiếp.
-- **[MANDATORY]** Script check **lượng** (field có/không). Agent check **chất** (nội dung chuẩn, hợp logic, gaps giữa fields).
-- **[STRICTLY FORBIDDEN]** Gửi all-in-one rồi bỏ sót giữa.
+- **[MANDATORY]** Grill by zone; do **not** grill the entire bundle in one pass.
+- **[MANDATORY]** Split the bundle into zones based on actual content:
+  - One zone per turn: read zone data → analyze quality (logic, consistency, cross-field gaps) → patch.
+  - If a zone is too large → subdivide further.
+- **[MANDATORY]** Script checks **quantity** (field present or not). Agent checks **quality** (correct content, logic, cross-field gaps).
+- **[STRICTLY FORBIDDEN]** Single all-in-one pass that drops items in the middle.
 
 ## Rule: Missing Information / Hard Gate & Workload Threshold (Law 2)
 

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

@@ -9,7 +9,7 @@ disable-model-invocation: true
 > **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. **STRICTLY FORBIDDEN** to rely on memory.
 > **[MANDATORY]** Read `.flowgrid/templates/feature.bundle.yaml` + `.flowgrid/templates/bundle-authoring.md` BEFORE generating any YAML. **Do NOT** use `design-spec.yaml` (deprecated).
 > If templates are missing → STOP: *"Template missing. Run `flowgrid init` to generate templates."*
-> **Extract:** `spec-ssot-prep.md`, `spec-prd-lite.md`, `db-audit-wizard.md`, `design-leaf-signoff.md`.
+> **Extract:** `spec-ssot-prep.md`, `spec-prd-lite.md`, `db-audit-wizard.md`, `design-leaf-signoff.md`, `agent-design-context.md`.
 > Physical interlocks: `AGENTS.md` + `SSOT_AGENT_PROTOCOL.md` (Laws 1–7). Chat-only done = **FAILED**.
 
 # /spec — Function detail (design)
@@ -62,7 +62,7 @@ Hub: [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) · extract `
   - `<pageType>` = page type đã xác định ở bước trên (list | create | detail | admin-crud | auth | ...).
   - Script output:
     - `gaps[]` → required fields missing → Agent patches bundle directly.
-    - `warnings[]` → **quality hints** (`scopeIn`, `nonGoals`, `nfr`, `userFlows`, placeholders) — fix when info exists; **does not** block split. Rủi ro → `/risk-register` only (`WARN_BUNDLE_RISKS_FORBIDDEN` if `risks:` on bundle).
+    - `warnings[]` → **quality hints** (`scopeIn`, `nonGoals`, `nfr`, `userFlows`, placeholders) — fix when info exists; **does not** block split. Risks → `/risk-register` only (`WARN_BUNDLE_RISKS_FORBIDDEN` if `risks:` on bundle).
     - `confirms[]` → AskQuestion wizard (one question at a time, ≥3 options):
       - UX: `category: ux`, `UX_*`, `CONFIRM_UX_*` — `flowgrid-ux-common.mdc`
       - **DB:** `category: db`, `CONFIRM_DB_*` — `.cursor/extracts/db-audit-wizard.md` (entities, multi-table, `db` vs `01`, `#derived-data`)
@@ -149,11 +149,14 @@ Each zone turn — **in order**:
 - **[MANDATORY]** List columns: `key` consistent with `bind.field`; computed-only columns → document `#derived-data` (see `common/data-model/derived-data.md`), no fake `db`.
 - **[STRICTLY FORBIDDEN]** Empty `entities: []` while form/list has multiple persisted `db.field` without QA defer.
 - **Authoring detail:** [bundle-authoring.md § Data model](../../../templates/shared/bundle-authoring.md#data-model--phase-0-erd-vs-screen-detail) · [tpl-screen-data-model.md](../../../templates/shared/tpl-screen-data-model.md) (multi-table).
-- **Sau split:** `ir/generated/data-model.md` cho review. **Audit:** `CONFIRM_DB_*` → member wizard; sau chốt → re-audit. BE SSOT: `01` khớp `db` (drift → `/api-update`).
+- **After split:** `ir/generated/data-model.md` for review. **Audit:** `CONFIRM_DB_*` → member wizard; re-audit after confirm. BE SSOT: `01` must match `db` (drift → `/api-update`).
 
 ### Rule: Summary extensions (PRD lite)
 - **[MANDATORY]** `summary` bullets: business_goals, stakeholders, user_journey, context (input/output), optional solution.
-- **[RECOMMENDED]** Fill `scopeIn`, `nonGoals`, `userFlows`, `nfr` when PO/BA có thông tin. Rủi ro dự án → **`/risk-register`** (`architecture/11-risks/risk-register.md`), never `risks:` on bundle.
+- **[RECOMMENDED]** Fill `scopeIn`, `nonGoals`, `userFlows`, `nfr` when PO/BA provide facts. Complex single-screen flows → `interactionCases` (L2) or resolve audit `CONFIRM_INTERACTION_CASES_POLICY`. Project risks → **`/risk-register`**, never `risks:` on bundle.
+- **[MANDATORY]** `userFlows:` bullets link **`FLOW-*`** (`FLOW-id — role: … — screens: W-* (this leaf)`). Journey sequence lives in **`FLOW-*.md` §6** — not in bundle.
+- **[RECOMMENDED]** Multi-state / multi-case on **one screen:** optional top-level **`interactionCases`** (`policy`, `items[]` with `IC-*`, `description`, `sequenceDiagram`) — see `agent-design-context.md`. After split: prose → `spec.md`, diagrams → `design.md`.
+- **[MANDATORY]** Consume `confirms[]` **`CONFIRM_INTERACTION_CASES_POLICY`** from audit — set `policy: required` or `policy: skip` + `skipReason`.
 - **[MANDATORY]** Replace template `[placeholder]` brackets in `summary` / metrics / non-goals before handoff grill.
 
 ### Rule: User Stories (`userStories`)
@@ -269,6 +272,6 @@ Each zone turn — **in order**:
 - [ ] UX gap questions used checklist-backed `(Recommended)` options (`flowgrid-ux-common.mdc`), not open brainstorming.
 - [ ] `userStories` scenarios/AC reflect UX affordances patched in `design` (incl. audit `suggestedStoryPatch`).
 - [ ] YAML strings with `:` or `[]` are double-quoted. No `.md` written by hand.
-- [ ] PRD fields (`scopeIn`, `nonGoals`, `userFlows`, `nfr`) filled or deferred via `qa/` (no template brackets). Rủi ro không trên bundle.
+- [ ] PRD fields (`scopeIn`, `nonGoals`, `userFlows`, `nfr`) filled or deferred via `qa/` (no template brackets). No project risks on bundle (`/risk-register` only).
 - [ ] `pnpm docs:split` + `pnpm docs:render` run with zero errors; `ir/generated/spec.md` has TOC + overview sections.
 - [ ] Handoff → `/testcase` created.

package/harness/docs/skills/user-flow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: user-flow
-description: /user-flow — Luồng người dùng (FLOW-*) trên surfaces.
+description: /user-flow — Author cross-surface user journeys (FLOW-*.md) on the docs hub.
 disable-model-invocation: true
 extractBundle: architecture-core
 ---
@@ -12,7 +12,9 @@ extractBundle: architecture-core
 
 **Mindset:** Model the process by **business actions on surfaces**, not by repository or service topology.
 
-**Template:** `architecture/03-user-flows/FLOW-template.md` (or `**/common/user-flows/FLOW-*.md`) — **Non-goals** in §1 when information exists (KPI ngoài hub).
+**Template:** `architecture/03-user-flows/FLOW-template.md` (or `**/common/user-flows/FLOW-*.md`) — **Non-goals** in §1 when information exists (out-of-hub KPIs).
+
+**Leaf link:** Bundles reference this file via `userFlows:` (`FLOW-* — role — screens`). Agents read FLOW **before** codegen (`agent-design-context.md`). **Do not** put single-screen multi-state cases here — use bundle `interactionCases` (L2).
 
 ---
 

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

@@ -1,12 +1,12 @@
 ---
 name: prototype
-description: /prototype — UI from FLOWGRID_DOCS_ROOT ir/design.yaml with mock API via bộ code.
+description: /prototype — UI from FLOWGRID_DOCS_ROOT ir/design.yaml with mock API via the FE code repo.
 disable-model-invocation: true
 ---
 
 # /prototype — UI Prototype (Mock API Boundary)
 
-**Owner:** bộ code (`--type=fe`) · Adapters: `nuxt4` | `nextjs` | `dotnet-line`
+**Owner:** FE code repo (`--type=fe`) · Adapters: `nuxt4` | `nextjs` | `dotnet-line`
 
 ## Artifact & Target ID Resolution Rule
 
@@ -23,6 +23,17 @@ surfaces/<surface>/CMP-*/<NN…>/ir/design.yaml
 
 Read the **entire** `ir/design.yaml` (script + agent inspection). Do not filter keys from `*.bundle.yaml`. **`ir/spec.yaml`** is business prose only.
 
+## Agent context (ACP) before gen
+
+Per **`agent-design-context.md`** (resolve `W-*` via `flowgrid_docs_route` → `linkedFlows[]`):
+
+1. **`userFlows` / linked `FLOW-*.md`** — §6 sequence for journey context.
+2. **`bundle.nfr`** (from bundle or `ir/spec.yaml` mirror).
+3. **`ir/generated/design.md`** when `interactionCases.policy: required`.
+4. Then **`ir/design.yaml`**.
+
+Print checklist in chat: FLOW ids read · NFR · L2 design.md yes/no.
+
 **Docs hub is read-only for this skill.** Never Write/patch `*.bundle.yaml`, `ir/*`, or any file under `FLOWGRID_DOCS_ROOT`. Missing `ir/design.yaml`, empty `codegen.profile`, or `flowgrid gen` failure → **STOP**, quote the CLI error, hand off to docs-hub `/grill-dev` (or `/spec`). Do not invent SSOT to make gen pass. Login/forgot/reset must be `codegen.profile: auth` (not `create`) or gen writes `(dashboard)`.
 
 Do not invent sibling docs-hub paths. Pass `FLOWGRID_DOCS_ROOT` or `--docs-root`.
@@ -38,7 +49,7 @@ Do not invent sibling docs-hub paths. Pass `FLOWGRID_DOCS_ROOT` or `--docs-root`
 
 ## Route
 
-Architecture/C4 → bộ docs (`FLOWGRID_DOCS_ROOT`); IR/registry/gen →
+Architecture/C4 → docs hub (`FLOWGRID_DOCS_ROOT`); IR/registry/gen →
 `FLOWGRID_DOCS_ROOT`; symbols/call-graph for repo X → Platform DNA-wired
 `codegraph-<repo-key>`. Never workspace-parent graphs, sibling-path inference,
 or member-edited MCP. Local ArtifactGraph is allowlist/tag hints for this repo
@@ -75,7 +86,7 @@ For each HANDOFF / `#needs-component: Mo…` after gen:
 4. Re-run `flowgrid gen` so slots bind to the new file.
 5. Dotnet-line / no `components.json`: skip this section; do not invent React/shadcn APIs.
 
-Do not copy the shadcn skill into bộ docs. Do not author `#ui:` tags from memory if `shadcn search` can name the registry item.
+Do not copy the shadcn skill into the docs hub. Do not author `#ui:` tags from memory if `shadcn search` can name the registry item.
 
 `dotnet-line` requires the .NET 8 SDK (`FLOWGRID_DOTNET`, then `dotnet`) and
 is limited to the pilot-specific `kiosk-check-in` profile. Its main pass also
@@ -88,14 +99,15 @@ if local ArtifactGraph available: recommend/check the FE repo's allowlisted gen
 else: run flowgrid gen:dry / gen directly
 
 Missing ArtifactGraph never blocks prototype generation. Complete the direct,
-deterministic bộ code fallback first, then follow
+deterministic FE-repo fallback first, then follow
 `.cursor/rules/flowgrid-code-optional-integrations.mdc` for once-per-run telemetry.
 ```
 
-Docs render / `spec:split` remain flowgrid / bộ docs handoffs.
+Docs render / `spec:split` remain flowgrid / docs-hub handoffs.
 
 ## Translation Rule
-Luôn bọc text tĩnh bằng i18n helper native của framework. 
-- Đọc block `i18n` từ `ir/design.yaml`.
-- Tự động sinh/cập nhật file ngôn ngữ tương ứng (`.json` cho FE/NodeJS, hoặc `.resx` cho Dotnet). 
-- KHÔNG viết gộp ngôn ngữ lên giao diện (ví dụ không dùng `login / đăng nhập`).
+
+- Wrap all static UI copy with the framework’s native i18n helper.
+- Read the `i18n` block from `ir/design.yaml`.
+- Generate or update locale files (`.json` for FE/Node, `.resx` for dotnet-line).
+- Do **not** hard-code mixed languages in UI (e.g. avoid `login / đăng nhập` in one string).

package/package.json

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

package/templates/shared/bundle-authoring.md

@@ -10,7 +10,8 @@ Hub: `docs/templates/feature.bundle.yaml` · split: `pnpm spec:split`
 | `summary` | Phải trình bày dạng bullet. Bắt buộc có các tiêu đề (chuẩn Arc42 business): **mục tiêu nghiệp vụ** (business_goals), **các bên liên quan** (stakeholders), **kịch bản người dùng** (user_journey), **bối cảnh** (description, input liên kết cross-page/module, output) và **cách giải quyết** (tùy chọn). Mục đích để 100% Non-tech Stakeholder hiểu và duyệt. |
 | `scopeIn` | **Khuyến nghị** — trong phạm vi màn/phase (PRD). Audit `WARN_NO_SCOPE_IN`. |
 | `nonGoals` | **Khuyến nghị** — ngoài phạm vi màn/phase (PRD). Audit `WARN_NO_NON_GOALS`. |
-| `userFlows` | **Khuyến nghị** — link `FLOW-*` (`03-user-flows` / `common/user-flows`) hoặc journey ngắn. Audit `WARN_NO_USER_FLOWS` khi multi-screen. |
+| `userFlows` | **Recommended** — `FLOW-* — role: … — screens: W-* (this leaf)`; agents read linked `FLOW-*.md` §6 before codegen (`agent-design-context.md`). |
+| `interactionCases` | **Optional L2** — `policy` + `items[]` (`IC-*`, `description`, `sequenceDiagram`); split → `spec.md` + `ir/generated/design.md`. Audit `CONFIRM_INTERACTION_CASES_POLICY`. |
 | `nfr` | **Khuyến nghị** — hiệu năng, bảo mật. Audit `WARN_NO_NFR`. |
 | _(rủi ro)_ | **Không** khai báo trên bundle. SSOT: `architecture/11-risks/risk-register.md` — `/risk-register`. Key `risks:` → audit `WARN_BUNDLE_RISKS_FORBIDDEN`. |
 | `userStories` | **Khối User Stories chuyên sâu cho màn hình:** `primary`, `contextAndHandoff` (+ `screenAccess`), `scenarios` (5 kịch bản chuẩn + **scenario thứ 6 “Affordances UX”** khi màn có delete/filter/breadcrumb/disabled/import — xem `feature.bundle.yaml`), `acceptanceCriteria` (kèm checkbox UX khi áp dụng). **Split:** `pnpm spec:split` copy nguyên khối sang `ir/spec.yaml` (business prose); **không** tự sinh từ `design` — Agent phải cập nhật `userStories` khi bổ sung DSL/`#needs-component`/audit `UX_*`. Render → `## User Stories & Screen Journey` trong Markdown. |