@shanyucoder/flowgrid 0.1.11 → 0.1.13

package/harness/shared/rules/flowgrid-code-optional-integrations.mdc

@@ -1,15 +1,15 @@
 ---
-description: bộ code-owned fallback and telemetry for optional integrations
+description: code repo-owned fallback and telemetry for optional integrations
 alwaysApply: true
 ---
 
-# bộ code optional integrations
+# code repo optional integrations
 
 ArtifactGraph and CodeGraph are optional accelerators. Their absence or
-unavailability must never abort a bộ code-owned generation, dry-run,
+unavailability must never abort a code repo-owned generation, dry-run,
 validation, or review.
 
-Full cross-repo routing (architecture → bộ docs, IR → pointer roots, symbols →
+Full cross-repo routing (architecture → docs hub, IR → pointer roots, symbols →
 per-repo `codegraph-<key>`) lives in `cross-repo-index-routing.mdc`.
 
 ## Docs registry hub
@@ -20,11 +20,11 @@ per-repo `codegraph-<key>`) lives in `cross-repo-index-routing.mdc`.
 - ArtifactGraph in an FE/BE repo indexes that repo only; it does **not** follow
   `FLOWGRID_DOCS_ROOT` and must not be used as the bridge to docs.
 - Use ArtifactGraph only for local allowlist/tag hints. Missing local
-  ArtifactGraph never changes where bộ code reads canonical docs input.
-- bộ docs, when installed as a consumer, uses its separate `FLOWGRID_DOCS_ROOT`
+  ArtifactGraph never changes where code repo reads canonical docs input.
+- docs hub, when installed as a consumer, uses its separate `FLOWGRID_DOCS_ROOT`
   pointer for architecture ID/path queries — never CodeGraph for C4.
 - CodeGraph, when used, must be the Platform DNA-wired `codegraph-<repo-key>`
-  for that checkout. bộ code never writes those MCP entries itself. Missing
+  for that checkout. code repo never writes those MCP entries itself. Missing
   or unindexed checkouts fall back and emit telemetry; never invent a graph or
   `codegraph init` a workspace parent.
 

package/harness/tests/rules/cross-repo-index-routing.mdc

@@ -5,7 +5,7 @@ alwaysApply: true
 
 # Cross-repo index routing
 
-- Architecture IDs and Functions/W-* paths belong to bộ docs through `FLOWGRID_DOCS_ROOT`.
+- Architecture IDs and Functions/W-* paths belong to docs hub through `FLOWGRID_DOCS_ROOT`.
   Never use CodeGraph as the architecture index.
 - Test plans use `FLOWGRID_TESTS_DOC`; docs evidence uses
   `FLOWGRID_DOCS_ROOT`; IR/registry/generation follows its owning pointer such as

package/harness/tests/rules/flowgrid-test-optional-accelerators.mdc

@@ -1,9 +1,9 @@
 ---
-description: bộ test optional accelerator fallback and event contract
+description: tests hub optional accelerator fallback and event contract
 alwaysApply: true
 ---
 
-# bộ test optional accelerators
+# tests hub optional accelerators
 
 ArtifactGraph accelerates coverage and search but is never required. When it is
 missing or fails, continue with deterministic local coverage/search. Assign one
@@ -13,7 +13,7 @@ stable `runId` per run and emit exactly one `flowgrid.missing-optional` event pe
 ArtifactGraph is local-only: in this repo it indexes this repo's own data
 (taxonomy/coverage hints) and never follows `FLOWGRID_DOCS_ROOT` or
 `FLOWGRID_TESTS_DOC`. Canonical docs/tests-hub evidence always flows through
-those bộ test pointers, never through ArtifactGraph.
+those tests hub pointers, never through ArtifactGraph.
 
 Events must conform to
 `.cursor/schemas/flowgrid-test/missing-optional-event.schema.json`. Metrics count only

package/harness/tests/rules/plans-docs-first.mdc

@@ -6,8 +6,8 @@ alwaysApply: false
 
 # Plans — docs-first
 
-- **Rule / acceptance SSOT = docs hub.** Tests hub chỉ `refs.rule` (id + link). Không copy nội dung rule vào YAML để “sửa cho tiện”.
-- Grill thấy **scope hở / rule mơ hồ** → handoff docs (`/update-spec`, grill-docs). **Không** vá bằng testcase.
-- Chỉ thêm/sửa `TC-*` khi docs đã rõ và thiếu **bao phủ** (`coverage`).
-- YAML = máy (gen Playwright). MD = member đọc đối chiếu docs.
-- Chi tiết: `landscape/NOTE-testing-architecture.md`.
+- **Rule / acceptance SSOT = docs hub.** Tests hub only `refs.rule` (id + link). Do not copy rule content into YAML for convenience edits.
+- When grill finds **open scope / vague rules** → hand off to docs (`/update-spec`, grill-docs). Do **not** patch via testcase.
+- Add or edit `TC-*` only when docs are clear and **coverage** is missing.
+- YAML = machine (Playwright gen). MD = member reads against docs.
+- Details: `landscape/NOTE-testing-architecture.md`.

package/harness/tests/skills/grill-testcase/SKILL.md

@@ -10,11 +10,11 @@ disable-model-invocation: true
 
 # /grill-testcase
 
-**Owner:** bộ test (`--type=tests`)
+**Owner:** tests hub (`--type=tests`)
 
-Audit plans only. Spec holes hand off to docs-hub `/update-spec` or `/grill-bqa` (bộ docs), never invent acceptance. **[MANDATORY]** When handing off, you MUST output a comprehensive gap report in the Chat Thread formatted as a complete, ready-to-use prompt starting with `/docs-hub` (e.g., `/docs-hub /update-spec [details...]`). This prompt must detail exactly what business rules or coverage are missing, enabling the user to copy-paste it directly to run the docs-hub skill.
+Audit plans only. Spec holes hand off to docs-hub `/update-spec` or `/grill-bqa` (docs hub), never invent acceptance. **[MANDATORY]** When handing off, you MUST output a comprehensive gap report in the Chat Thread formatted as a complete, ready-to-use prompt starting with `/docs-hub` (e.g., `/docs-hub /update-spec [details...]`). This prompt must detail exactly what business rules or coverage are missing, enabling the user to copy-paste it directly to run the docs-hub skill.
 
-Route Functions/W-* evidence through bộ docs and symbol/call-graph evidence
+Route Functions/W-* evidence through docs hub and symbol/call-graph evidence
 for repo X through its Platform DNA-wired `codegraph-<repo-key>` server. Use
 `FLOWGRID_DOCS_ROOT` / `FLOWGRID_TESTS_DOC` for pointer evidence; never build or
 query a workspace-parent graph.
@@ -47,7 +47,7 @@ else: local deterministic coverage/search over targeted plan/docs evidence
 ```
 
 ArtifactGraph indexes this tests hub only; spec-hole handoffs go to docs-hub
-`/update-spec` (bộ docs), not through ArtifactGraph.
+`/update-spec` (docs hub), not through ArtifactGraph.
 
 Use one stable `runId` per run. When ArtifactGraph is missing, finish the local
 fallback before emitting exactly one `flowgrid.missing-optional` event for that

package/harness/tests/skills/scenario/SKILL.md

@@ -9,11 +9,11 @@ disable-model-invocation: true
 
 # /scenario
 
-**Owner:** bộ test (`--type=tests`)
+**Owner:** tests hub (`--type=tests`)
 
 Author cross-flow scenarios (SC) on the current tests hub. Design rules stay on the docs hub.
 
-Scenarios test a **user flow** (`FLOW-*`) that spans multiple screens (`W-*`) or modules. They mirror the docs FLOW file **after** bộ docs LCA `common/` placement (not a flat `common/` tree).
+Scenarios test a **user flow** (`FLOW-*`) that spans multiple screens (`W-*`) or modules. They mirror the docs FLOW file **after** docs hub LCA `common/` placement (not a flat `common/` tree).
 
 ## Output Rules
 
@@ -29,7 +29,7 @@ Scenarios test a **user flow** (`FLOW-*`) that spans multiple screens (`W-*`) or
 ## Target / ID Resolution Rule
 
 - **[MANDATORY]** Agent MUST locate the **`FLOW-*.md`** file on the docs hub (`FLOWGRID_DOCS_ROOT`) via `flowgrid_docs_route` / `flowgrid_docs_get_element` / glob. Filenames are `FLOW-…md`, not `flow-*`.
-- Search in this order (same LCA as bộ docs `common-scope.md`):
+- Search in this order (same LCA as docs hub `common-scope.md`):
   1. `surfaces/<surface>/<CMP-id>/<NN>/common/user-flows/FLOW-*.md` (cluster)
   2. `surfaces/<surface>/<CMP-id>/common/user-flows/FLOW-*.md` (module)
   3. `surfaces/<surface>/common/user-flows/FLOW-*.md` (surface)

package/harness/tests/skills/testcase/SKILL.md

@@ -11,7 +11,7 @@ disable-model-invocation: true
 
 # /testcase — E2E Test Case Authoring (Tests Hub)
 
-**Owner:** bộ test (`--type=tests`). Design rules stay on docs hub. Playwright generation is FE `/test`.
+**Owner:** tests hub (`--type=tests`). Design rules stay on docs hub. Playwright generation is FE `/test`.
 
 ---
 
@@ -79,7 +79,7 @@ disable-model-invocation: true
 ## Rule: Route Cross-Repo Evidence
 
 - **[MANDATORY]** Route evidence by owner:
-  - Functions/`W-*` → bộ docs
+  - Functions/`W-*` → docs hub
   - Plan/docs → `FLOWGRID_TESTS_DOC` / `FLOWGRID_DOCS_ROOT`
   - Symbols for repo X → `codegraph-<repo-key>` (Platform DNA-wired server)
 - **[STRICTLY FORBIDDEN]** Never query one workspace-wide graph. Never hand-edit MCP config.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shanyucoder/flowgrid",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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. |
@@ -97,7 +98,7 @@ Authoring (`/spec`, grill-*) still **writes** `*.bundle.yaml`, then split.
 
 ### UX affordance ↔ `userStories` (before `pnpm spec:split`)
 
-| Design / audit signal | Business layer (`userStories` → `ir/spec.yaml`) |
+| Design / audit signal | `flowgrid audit spec` on **bundle**; `userStories` / `interactionCases` authored on bundle → split copies to `ir/spec.yaml` |
 |----------------------|--------------------------------------------------|
 | `design.nav.breadcrumb`, `CONFIRM_UX_BREADCRUMB_*` | Scenario **Initial Load** + scenario **Affordances UX**; AC deep link |
 | `spec.ui.list.filters`, `CONFIRM_UX_FILTER_*` | Scenario **Initial Load** / **Affordances UX**; AC empty “no results” |
@@ -109,14 +110,20 @@ Authoring (`/spec`, grill-*) still **writes** `*.bundle.yaml`, then split.
 
 **Không** chỉ ghi tech vào `design.actions` — stakeholder đọc `ir/spec.yaml` / rendered MD phải thấy cùng hành vi.
 
+### SSOT loop (agents + members) — English
+
+**Write:** `*.bundle.yaml` only → `flowgrid split` → `flowgrid render`.  
+**Read-only:** `ir/spec.yaml`, `ir/design.yaml`, `ir/generated/*` (review **`ir/generated/spec.md`** on VitePress).  
+**Fix gaps:** `/update-spec` on bundle — not IR edits, not `spec:merge`. Extract: `ir-read-only.md`.
+
 | Artifact | Đọc bởi | Nội dung |
 |----------|---------|----------|
-| `*.bundle.yaml` | **Ghi** `/spec`, grill-*; **đọc cả file** `/testcase`, `/grill-testcase` | Đầy đủ spec+gen+design+`userStories`; tests hub read-only |
-| `ir/design.yaml` | **Đọc cả file** — grill-*, FE `/prototype`, codegen | Tech sau split; `api` chiếu từ 01. |
-| `ir/spec.yaml` | VitePress + stakeholder | Business page + requirements/acceptance. Không id/tag/bind. `"Q&A"`. Không stub `legacy` rỗng. |
+| `*.bundle.yaml` | **Ghi** `/spec`, `/update-spec`, grill-*; **đọc cả file** `/testcase`, `/grill-testcase` | Đầy đủ spec+gen+design+`userStories`; tests hub read-only |
+| `ir/design.yaml` | **Chỉ đọc** — grill-*, FE `/prototype`, codegen | Split output; **không sửa file** |
+| `ir/spec.yaml` | **Chỉ đọc** — agent/stakeholder mirror | Business prose sau split; **không sửa file** |
 | `…/api/<seq>/01-backend-spec.yaml` | BE `/api`, `openapi_gen`, **author API** | Tech BE — SSOT duy nhất cho endpoint |
 | `ir/generated/data-model.md` | BA/lead/BE review | Bảng/cột theo `schema` (multi-table); sinh từ `ir/design.yaml` |
-| `ir/generated/spec.md` · `ir/generated/api.md` | BA/QA/Dev review (VitePress) | Render từ `ir/spec.yaml` + `01`; hướng dẫn API: [tpl-api-contract.md](./tpl-api-contract.md) |
+| `ir/generated/spec.md` · `ir/generated/design.md` · `ir/generated/api.md` | BA/QA/Dev review (VitePress) — **chỉ đọc** | Render từ split; sửa → bundle + `/update-spec` + split + render |
 
 Không còn `ir/legacy.yaml`. `legacy:` trên `ir/spec.yaml` chỉ khi có evidence thật.
 

package/templates/shared/default-layout.ejs

@@ -7,6 +7,13 @@
   const hasStories = !!spec.userStories;
   const hasNfr = spec.nfr && String(spec.nfr).trim();
   const hasUserFlows = spec.userFlows && String(spec.userFlows).trim();
+  const icBlock = spec.interactionCases;
+  const icItems = icBlock && Array.isArray(icBlock.items) ? icBlock.items : [];
+  const hasInteractionCases =
+    icBlock &&
+    (icBlock.policy === 'skip' ||
+      icItems.length > 0 ||
+      (icBlock.policy === 'required' && icItems.length === 0));
   const qaOpen = spec['Q&A'] && String(spec['Q&A']).trim();
   const hasEntities = spec.entities && (Array.isArray(spec.entities) ? spec.entities.length : true);
   const pageSections = spec.sections || spec.design?.sections || [];
@@ -34,8 +41,9 @@
   if (hasNonGoals) addToc('Out of scope', 'scope-out');
   if (hasStories) addToc('User stories & requirements', 'user-stories--screen-journey');
   addToc('Data & integrations / API', 'data-integrations');
-  if (hasUserFlows) addToc('User flows', 'user-flows');
+  if (hasUserFlows) addToc('Linked user flows (FLOW)', 'user-flows');
   if (hasNfr) addToc('Non-functional (NFR)', 'nfr');
+  if (hasInteractionCases) addToc('Interaction cases', 'interaction-cases');
   if (hasState) addToc('State & permissions matrix', 'state--permission-matrix');
   if (hasListColumns) addToc('List columns', 'list-columns');
   if (hasListExtras) addToc('Filters & pagination', 'list-filters-pagination');
@@ -213,7 +221,11 @@ Backend contract: `api/<seq>/01-backend-spec.yaml` on the same function leaf (no
 <% } %>
 
 <% if (hasUserFlows) { %>
-## User flows {#user-flows}
+## Linked user flows (FLOW) {#user-flows}
+
+Use product journey docs (`FLOW-*.md`) — include §6 sequence. Convention per line:
+
+`FLOW-<id> — role: entry|step-N-*|exit — screens: W-* … (this leaf)`
 
 <%= spec.userFlows %>
 
@@ -226,6 +238,39 @@ Backend contract: `api/<seq>/01-backend-spec.yaml` on the same function leaf (no
 
 <% } %>
 
+<% if (hasInteractionCases) { %>
+## Interaction cases {#interaction-cases}
+
+<% if (icBlock.policy === 'skip') { %>
+_Screen interaction sequences skipped:_ <%= icBlock.skipReason || '(no reason given)' %>
+
+<% } else { %>
+> Sequence diagrams: [design.md](./design.md) (generated). Authoring: `interactionCases` on `*.bundle.yaml`.
+
+<% for (const item of icItems) { %>
+### <%= item.id || 'IC-?' %> {#<%= String(item.id || 'ic').toLowerCase() %>}
+
+<% if (item.title) { %>**<%= item.title %>**
+
+<% } %>
+<% if (item.description) { %>
+<%= item.description %>
+
+<% } %>
+<% if (item.links && typeof item.links === 'object') { %>
+| Link | Value |
+| --- | --- |
+<% for (const [k, v] of Object.entries(item.links)) { %>
+| `<%= k %>` | <%= v %> |
+<% } %>
+
+<% } %>
+[View sequence diagram](./design.md#<%= String(item.id || 'ic').toLowerCase() %>)
+
+<% } %>
+<% } %>
+<% } %>
+
 <%
   const page = {
     nav: spec.nav || spec.design?.nav,

package/templates/shared/feature.bundle.yaml

@@ -26,7 +26,35 @@ nonGoals: |
   - [VD: không export Excel tại màn list — defer QA/debt]
 
 userFlows: |
-  - [Luồng người dùng — link FLOW-* trong architecture/03-user-flows hoặc common/user-flows]
+  - FLOW-checkout — role: step-3-ops — screens: W-ADM-ORD-01 (this leaf)
+  # Journey SSOT: FLOW-*.md (§6 sequenceDiagram) — read via userFlows before codegen
+
+# Optional — màn nhiều state / case trên một W-* (L2). Không thay FLOW-*.md.
+# interactionCases:
+#   policy: required
+#   items:
+#     - id: IC-SUBMIT-HAPPY
+#       title: "Lưu từ DRAFT"
+#       description: |
+#         User bấm Lưu; form hợp lệ; chuyển trạng thái.
+#       links:
+#         actionId: btn_save_record
+#         recordStatus: DRAFT
+#       sequenceDiagram: |
+#         sequenceDiagram
+#           actor U as User
+#           participant W as [W-ADM-ORD-01]
+#           U->>W: Submit
+#     - id: IC-SUBMIT-409
+#       title: "Conflict"
+#       description: |
+#         Optimistic lock conflict — giữ form, reload.
+#       links:
+#         actionId: btn_save_record
+#       sequenceDiagram: |
+#         sequenceDiagram
+#           U->>W: Submit
+#           W-->>U: 409 message
 
 nfr: |
   - **Hiệu năng:** [VD: danh sách < 2s với 10k bản ghi — phân trang server]