@shanyucoder/flowgrid 0.1.12 → 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.12",
+  "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

@@ -98,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” |
@@ -110,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/tpl-runtime-sequence.md

@@ -1,56 +0,0 @@
----
-page-id: W-XXX-DOMAIN-01
-title: "Runtime sequence — <feature title>"
-status: draft
----
-
-# Runtime sequence — `<page-id>`
-
-> SSOT for **tech review** (BE/FE). Journey context: link `FLOW-*` from bundle `userFlows`.  
-> Authoring: `ir/runtime-sequence.md` or `api/<seq>/02-runtime-sequence.md` — not this generated copy.
-
-## Scope
-
-- **In this diagram:** …
-- **Out of scope:** …
-
-## Preconditions & state
-
-| State / gate | Rule |
-| --- | --- |
-| e.g. `DRAFT` | User may edit until submit |
-
-## Sequence
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor U as User
-    participant W as [W-XXX-DOMAIN-01]
-    participant API as [API-XXX-DOMAIN-01]
-    participant Svc as DomainService
-    participant DB as Database
-
-    U->>W: Open screen
-    W->>API: Load (GET …)
-    API->>Svc: fetch
-    Svc->>DB: query
-    DB-->>Svc: rows
-    Svc-->>API: DTO
-    API-->>W: 200 + body
-    W-->>U: Render
-
-    alt Validation error
-        API-->>W: 422 field errors
-        W-->>U: Inline messages
-    else Conflict
-        API-->>W: 409
-        W-->>U: Toast + stay
-    end
-```
-
-## Traceability
-
-| Step | Endpoint / action | Tables / events |
-| --- | --- | --- |
-| 1 | `endpoints[].id` … | … |