@shanyucoder/flowgrid 0.1.11 → 0.1.13

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

@@ -0,0 +1,136 @@
+# 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** | `bundle.design.stateMatrix` | YAML on bundle → split | Machine state/button matrix |
+| **L4** | `bundle.design` + `01` | YAML on bundle → `ir/design.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
+          ...
+```
+
+**Author here only** — on `feature.bundle.yaml`. **`flowgrid split`** partitions:
+
+- prose (`description`, `policy`, …) → `ir/spec.yaml` → render `spec.md`
+- `sequenceDiagram` per item → `ir/design.yaml` → render `design.md`
+
+**Codegen read order for L2:** read split/render output (`design.md` + `stateMatrix` / `actions` on `ir/design.yaml`) — do not author L2 on IR.
+
+**Not FLOW** for L2 timelines.
+
+---
+
+## 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`)
+
+**Target file:** always **`*.bundle.yaml`** on the function leaf — **not** `ir/spec.yaml`, `ir/design.yaml`, or `ir/generated/*`.
+
+`engines/spec/lib/audit-bundle-gaps.mjs` parses the **bundle** and runs `auditInteractionCases(bundle)` (plus UX/DB/userFlows warnings). Patch findings on the **bundle**, then `split` → `render`.
+
+**Step 1 — policy confirm** when screen is complex and `interactionCases` missing on the **bundle**:
+
+- 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` |
+
+**SSOT loop:** Review **`ir/generated/spec.md`** (read-only) → gaps → **`/update-spec`** patches **`*.bundle.yaml`** → `split` → `render`. Never edit `ir/spec.yaml`, `ir/design.yaml`, or generated MD. See **`ir-read-only.md`**. No routine `spec:merge`.
+
+---
+
+
+## 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,16 @@
       ".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",
+      ".cursor/extracts/ir-read-only.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",
+      ".cursor/extracts/ir-read-only.md"
     ],
     "bqa-grill": [
       ".cursor/extracts/grill/validation.md",
@@ -43,7 +47,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",
@@ -51,6 +56,7 @@
     ],
     "update-spec": [
       ".cursor/extracts/update-spec-delta.md",
+      ".cursor/extracts/ir-read-only.md",
       ".cursor/extracts/wire-spec-feedback.md",
       ".cursor/extracts/qa-inbox.md"
     ]

package/harness/docs/extracts/ir-read-only.md

@@ -0,0 +1,42 @@
+# IR & generated markdown — read-only (SSOT = bundle)
+
+## Authoring SSOT (incl. L1/L2 added for agents)
+
+**Write on `*.bundle.yaml` only** — then `split` materializes IR:
+
+| Field | On bundle | After `split` (read-only) |
+| --- | --- | --- |
+| `userFlows`, `nfr`, `interactionCases` (full block) | top-level on bundle | partitioned → `ir/spec.yaml` + `ir/design.yaml` |
+| `design.stateMatrix`, `design.actions`, sections | `design:` on bundle | `ir/design.yaml` |
+
+**Never** create or edit `interactionCases` / `userFlows` first on `ir/spec.yaml` or `ir/design.yaml`. There is no separate IR authoring path for those fields.
+
+## Write path (single loop)
+
+1. **Author / patch** `*.bundle.yaml` on the function leaf (`/spec`, `/grill-*`, `/update-spec`, `/api-spec` for `01` only).
+2. **`flowgrid audit spec <bundle.yaml>`** — UX, DB, `userFlows`, **`interactionCases`** (`CONFIRM_INTERACTION_CASES_POLICY`), state/action checks all run on the **bundle file**, never on `ir/*`.
+3. **`flowgrid split`** → regenerates `ir/spec.yaml` + `ir/design.yaml` from bundle.
+4. **`flowgrid render`** → regenerates `ir/generated/*.md` for VitePress.
+
+**Do not** use `spec:merge` / `flowgrid merge` to “fix” review findings — patch the **bundle**, then split (+ render).
+
+## Read-only (agents and members)
+
+| Path | Role |
+| --- | --- |
+| `ir/spec.yaml` | Split output — business prose mirror. **Read only.** |
+| `ir/design.yaml` | Split output — tech IR. **Read only.** |
+| `ir/generated/spec.md` | **Primary human review** (VitePress). **Read only.** |
+| `ir/generated/design.md` | L2 sequence diagrams (render). **Read only.** |
+| `ir/generated/data-model.md`, `api.md` | Review helpers. **Read only.** |
+
+**[STRICTLY FORBIDDEN]** `Write` / patch on any `ir/*` or `ir/generated/*` file.
+
+## Review → fix loop
+
+1. Member runs docs site build (VitePress) and reads **`ir/generated/spec.md`** (and linked `design.md` / `api.md` when relevant).
+2. Gaps, typos, scope, stories, `interactionCases`, NFR → **`/update-spec`** (or `/spec` if greenfield rewrite).
+3. Agent patches **`*.bundle.yaml` only** → audit → split → render.
+4. Re-open VitePress page to confirm.
+
+Downstream codegen (`/prototype`, `/grill-dev`) **reads** `ir/design.yaml` (and ACP reads `ir/generated/design.md` for L2) — still **never writes** IR.

package/harness/docs/rules/agent-compliance.mdc

@@ -1,5 +1,5 @@
 ---
-description: Enforce physical interlocks for all bộ docs skills
+description: Enforce physical interlocks for all docs hub skills
 alwaysApply: true
 ---
 
@@ -24,3 +24,7 @@ When executing any skill (`/spec`, `/grill`, `/grill-bqa`, etc.):
 7. **ISOLATION:** Execute strictly within the invoked skill scope. **[STRICTLY FORBIDDEN]** to merge sibling features or output fake Markdown reports when YAML contracts are required.
 
 **Path SSOT:** `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment). **IDs:** `product-id-convention.md` (`surfaceCode` + `CMP|W|API-{SURF}-{DOMAIN}-{NN}`).
+
+**Harness language:** Agent instructions in `harness/**/skills` and `harness/**/rules` are **English**. Member-facing product prose (bundle summaries, UI copy) follows `docs-hub.locale.yaml` / `/spec` — not the skill language.
+
+**Docs hub IR:** SSOT write = **`*.bundle.yaml`** → `flowgrid split` → `flowgrid render`. **`ir/spec.yaml`**, **`ir/design.yaml`**, and **`ir/generated/*`** are **read-only** for agents and members; review fixes → **`/update-spec`** on the bundle (`ir-read-only.md`).

package/harness/docs/rules/docs-hub.mdc

@@ -1,12 +1,12 @@
 ---
-description: bộ docs MCP — arc42/C4 docs index; opt-in skill use
+description: docs hub MCP — arc42/C4 docs index; opt-in skill use
 alwaysApply: false
 ---
-# docs-hub (bộ docs)
+# docs-hub (docs hub)
 
 Use `/docs-hub` for targeted ID, dependency, link, journey, and chapter queries.
 
-The docs repo owns architecture/product Markdown. bộ docs indexes and validates
+The docs repo owns architecture/product Markdown. docs hub indexes and validates
 only.
 
 - In docs: `FLOWGRID_DOCS_ROOT` points to the current docs repo.
@@ -21,14 +21,14 @@ only.
 4. Run `flowgrid_docs_orphans` and `flowgrid_docs_validate_links` before claiming completeness.
 5. Use `flowgrid_docs_user_flows` before reading all journey files.
 
-Do not require bộ docs for architecture work: if the MCP is unavailable, inspect
+Do not require docs hub for architecture work: if the MCP is unavailable, inspect
 the repository Markdown directly or explain how to run project-local setup.
 
 ## Index routing
 
 Cross-repo index is per-repo, never one giant parent-workspace graph:
 
-- Architecture ID / C4 path → bộ docs (`FLOWGRID_DOCS_ROOT`). Never CodeGraph for
+- Architecture ID / C4 path → docs hub (`FLOWGRID_DOCS_ROOT`). Never CodeGraph for
   architecture Markdown.
 - IR / registry / generation → pointer kits when present
   (`FLOWGRID_DOCS_ROOT`, `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`).
@@ -40,7 +40,7 @@ Cross-repo index is per-repo, never one giant parent-workspace graph:
 - ArtifactGraph stays local-only; it is never a shared index for other repos.
 
 ArtifactGraph is optional. If `@platform/artifactgraph` is not configured,
-unavailable, or fails, bộ docs must continue with targeted local search and
+unavailable, or fails, docs hub must continue with targeted local search and
 scoped Markdown reads; the missing optional must never abort the run. Assign one
 stable `runId` per run. Count each successful fallback file read and its exact
 raw byte length. After the fallback completes, emit exactly one

package/harness/docs/rules/flowgrid-process.mdc

@@ -1,9 +1,9 @@
 ---
-description: FlowGrid bộ process — business-process-trace (brownfield) and impact review (opt-in)
+description: FlowGrid process hub — business-process-trace (brownfield) and impact review (opt-in)
 alwaysApply: false
 ---
 
-# FlowGrid bộ process
+# FlowGrid process hub
 
 - `/business-process-trace`: observed brownfield process through code/evidence.
 - `/business-impact-review`: read-only vertical × horizontal blast-radius review.
@@ -14,11 +14,11 @@ alwaysApply: false
 Checkout routing (`cross-repo-index.mdc`): `legacy-*` →
 `legacy-repos.local.json`; other system ids → `platform-repos.local.json`.
 Ambiguous or missing keys → ask / Gaps + `/configure-repo-maps` — never invent
-paths. FlowGrid bộ process does not write cross-repo CodeGraph MCP entries.
+paths. FlowGrid process hub does not write cross-repo CodeGraph MCP entries.
 
-CodeGraph, bộ docs and ArtifactGraph are optional accelerators; route them per
+CodeGraph, docs hub and ArtifactGraph are optional accelerators; route them per
 repo/intent as defined in `cross-repo-index.mdc` (architecture →
-bộ docs, IR/registry → pointer kits, symbols of repo X → `codegraph-<key>` for
+docs hub, IR/registry → pointer kits, symbols of repo X → `codegraph-<key>` for
 X). Missing tools must fall back to targeted local search/model analysis and
 explicit residual gaps. Per run/optional pair, count actual successful file reads and raw context
 bytes, then emit exactly one `flowgrid.missing-optional` event conforming to

package/harness/docs/rules/team-flow-grill.mdc

@@ -1,5 +1,5 @@
 ---
-description: bộ docs grill metadata — list/form/detail profiles
+description: docs hub grill metadata — list/form/detail profiles
 globs: surfaces/**
 alwaysApply: false
 ---

package/harness/docs/rules/team-flow-spec.mdc

@@ -1,5 +1,5 @@
 ---
-description: bộ docs docs spec/grill/update workflow
+description: docs hub docs spec/grill/update workflow
 globs: surfaces/**, legacy-dynamics/**
 alwaysApply: false
 ---
@@ -24,12 +24,12 @@ Shared: resolve skill `extractBundle` → `.cursor/extracts/extract-registry.doc
 
 ## Pipeline
 
-1. **`/spec`** — `*.bundle.yaml` only (`feature.bundle.yaml` template; not `design-spec.yaml`). Include `successMetrics` / `nonGoals` when known. Per-zone: DSL/registry → bundle; `audit spec` `gaps[]` + non-blocking `warnings[]`. BA deliverable: `ir/generated/spec.md` after split+render. No `gen` / `codegen` in first pass.
+1. **`/spec`** — **write** `*.bundle.yaml` only → `split` → `render`. **Read-only:** `ir/spec.yaml`, `ir/design.yaml`, `ir/generated/*` (see `ir-read-only.md`). BA reviews **`ir/generated/spec.md`** on VitePress; gaps → **`/update-spec`** (not direct IR edits, not `spec:merge`). No `gen` / `codegen` in first pass.
 2. **`/grill-bqa`** — UI, acceptance, breadcrumb, delete rules.
-3. **`/grill-dev`** — codegen-ready bundle + `tags`; emit bộ code FE dry-run handoff.
+3. **`/grill-dev`** — codegen-ready bundle + `tags`; emit FE code repo dry-run handoff.
 4. **`/grill-docs`** — optional reconcile when BQA↔Dev contradict.
-5. **`/update-spec`** — controlled delta + `#update:*` (legacy trace → `/legacy /spec` hoặc delta legacy trong cùng skill; not full rewrite).
-6. **`/prototype`** — FE-lane handoff only after bộ code dry-run passes.
+5. **`/update-spec`** — controlled delta + `#update:*` (legacy trace → `/legacy /spec` or legacy delta in the same skill; not full rewrite).
+6. **`/prototype`** — FE-lane handoff only after code repo dry-run passes.
 
 - Render: `docs_render` / `flowgrid render` (pnpm fallback during transition)
 - **[STRICTLY FORBIDDEN]** Do NOT build UI prototypes, backend implementations, live APIs, or full E2E/unit tests during the spec/grill phase.

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

@@ -12,7 +12,7 @@ extractBundle: architecture-core
 
 **Audit Interlock:** Run `flowgrid audit legacy <target-id>`. Consume JSON gap report to verify mapping or prompt member if index is missing.
 
-**Handoff SSOT spec:** Sau adopt, member drill [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) — Phase 0 → `/legacy /spec` per `W-*` (không nhảy thẳng bundle không có ID trong inventory).
+**Handoff SSOT spec:** After adopt, member drills [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) — Phase 0 → `/legacy /spec` per `W-*` (do not jump straight to a bundle whose ID is not in the inventory).
 
 **Inventory template:** `.cursor/extracts/tpl-adoption-inventory.md` — section layout + **user-flow placement tiers** (cross-surface → `architecture/03-user-flows/`).
 

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

@@ -22,7 +22,7 @@ disable-model-invocation: true
   | Portal specs changed / merge deferred child functions | `/api-update` |
   | BE-only requirement (no FE contract change) | `/api-update --be-only` |
   | Spec exists but not codegen-ready / `approval.status` not `approved` | `/grill-api-spec` |
-  | `approval.status: approved` + explicit implement request | bộ code BE `/api` (switch to BE repo skill — NOT this skill) |
+  | `approval.status: approved` + explicit implement request | BE code repo `/api` (switch to BE repo skill — NOT this skill) |
 
 - **[MANDATORY]** Locate `01-backend-spec.yaml` under: `…/api/<seq>/` (screen leaf), `…/common/yaml/<slug>/`, or any surface leaf dedicated to external-channel APIs.
 - **[STRICTLY FORBIDDEN]** Do NOT skip `/grill-api-spec` for new features, cross-portal, or legacy-derived contracts.
@@ -35,5 +35,5 @@ Doc: `docs/operational/TEAM-AI-BACKEND-WORKFLOW.md`
 ## Verification Checklist
 
 - [ ] Checked `01-backend-spec.yaml` presence, `approval.status`, and `feature.source.kind`.
-- [ ] Correctly routed to contract skills vs bộ code BE `/api`.
+- [ ] Correctly routed to contract skills vs BE code repo `/api`.
 - [ ] Did NOT generate any content from this routing skill.

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/build-templates/SKILL.md

@@ -9,7 +9,7 @@ disable-model-invocation: true
 
 # /build-templates — Codebase Scanning & Template Scaffolding
 
-**Purpose:** Synchronize Docs Hub (bộ docs) with actual FE/BE codebase reality by scanning code and scaffolding customized `.ejs` templates.
+**Purpose:** Synchronize Docs Hub (docs hub) with actual FE/BE codebase reality by scanning code and scaffolding customized `.ejs` templates.
 
 ---
 

package/harness/docs/skills/call-external/SKILL.md

@@ -10,7 +10,7 @@ disable-model-invocation: true
 
 # #call-external — Third-Party Integration Tag
 
-Used from: `/api-spec`, `/grill-api-spec`, and bộ code BE `/api` when this hashtag is present.
+Used from: `/api-spec`, `/grill-api-spec`, and BE code repo `/api` when this hashtag is present.
 
 ---
 

package/harness/docs/skills/cross-entity-service/SKILL.md

@@ -10,7 +10,7 @@ disable-model-invocation: true
 
 # #cross-entity-service — Cross-Aggregate Orchestration Tag
 
-Used from: `/api-spec`, `/grill-api-spec`, and bộ code BE `/api` when this hashtag is present.
+Used from: `/api-spec`, `/grill-api-spec`, and BE code repo `/api` when this hashtag is present.
 
 ---
 

package/harness/docs/skills/db-erd/SKILL.md

@@ -10,14 +10,14 @@ extractBundle: architecture-core
 
 # /db-erd — Business Data Model (ERD)
 
-**Phase:** **0 Architecture** — sau `/overview`, `/module`, `/user-flow` khi có entity/bảng mới. **Trước** `/spec` leaf.
+**Phase:** **0 Architecture** — after `/overview`, `/module`, `/user-flow` when new entities/tables appear. **Before** any `/spec` leaf.
 
 **Hub SSOT:** [architecture-data.md](../../../docs/workflows/architecture-data.md)
 
 **Target Path:** `<LCA>/common/db-erd.md` — LCA resolved from `.cursor/extracts/common-scope.md`.
 VitePress/publish menu label: **`db-erd`** (not the H1 heading).
 
-**Handoff:** Design `/spec` đọc file này; chi tiết cột → `design.sections[].db` + `spec.entities` — **không** duplicate full ER trên bundle.
+**Handoff:** Design `/spec` reads this file; column detail → `design.sections[].db` + `spec.entities` — do **not** duplicate the full ER on the bundle.
 
 ---
 

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

@@ -22,7 +22,7 @@ SSOT flow: `docs/workflows/grill-and-human-review.md` · close checklist: `docs/
   | Gap context | Route to |
   | --- | --- |
   | Overview / surface / CMP `index.md` PRD sections | `/grill-hub-prd` |
-  | Sổ rủi ro quota / hạn mức / peak | `/risk-register` |
+  | Consolidated risk register (quota / limits / peak) | `/risk-register` |
   | UI acceptance, copy, validation, UX affordance | `/grill-bqa` |
   | `bundle.gen`, codegen profile, `#gen:*`, endpoint `action` on `01` | `/grill-dev` |
   | BQA ↔ Dev contradiction on same bundle | `/grill-docs` |

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

@@ -12,7 +12,7 @@ disable-model-invocation: true
 
 # /grill-api-spec — API Contract Audit
 
-After `/api-spec`. Before bộ code BE `/api`. No code implementation on docs hub.
+After `/api-spec`. Before BE code repo `/api`. No code implementation on docs hub.
 
 Shared extracts: `spec-evolution.md`, `api-spec-sync.md`, `entity-relationship.md`, `api-codegen-readiness.md`, `api-codegen-tags.md`, `call-external.md`, `agent-discipline.md`, `verify-gate.md`
 
@@ -46,7 +46,7 @@ Shared extracts: `spec-evolution.md`, `api-spec-sync.md`, `entity-relationship.m
 
 Run from docs hub cwd (or pass `--docs-root`); paths relative to docs hub:
 
-**Deterministic audit (lượng):**
+**Deterministic audit (quantitative):**
 
 1. `flowgrid audit api <path-to-01-backend-spec.yaml>` — consume `gaps[]` / `confirms[]` on the contract.
 2. When portal-backed and sibling `*.bundle.yaml` exists: `flowgrid audit fe-be <bundle.yaml>` — `apiRef` ↔ `01` parity.
@@ -74,4 +74,4 @@ Re-run steps 1–5 after patching `01` until audit gaps are resolved or logged a
 
 ## Handoff
 
-- `approval.status: approved` → bộ code BE `/api` with `--spec …/01-backend-spec.yaml`
+- `approval.status: approved` → BE code repo `/api` with `--spec …/01-backend-spec.yaml`

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

@@ -22,13 +22,13 @@ disable-model-invocation: true
 | Read (whole file) | Write | NEVER Read |
 |---|---|---|
 | **`ir/design.yaml`** (UI inventory, copy, visual, actions) | After Confirm: patch `*.bundle.yaml` → `pnpm spec:split` | Generated `*.md` |
-| **`ir/spec.yaml`** (requirements/acceptance prose — only when auditing) | | `bundle.gen` |
+| **`ir/spec.yaml`** (prose mirror after split — read for BQA review; **audit CLI stays on bundle**) | | `bundle.gen` |
 
 ---
 
 ## Rule: Audit Interlock (`flowgrid audit spec`)
 
-- **[MANDATORY]** Before Step A: run `flowgrid audit spec <*.bundle.yaml> --type <pageType>`.
+- **[MANDATORY]** Before Step A: run `flowgrid audit spec <*.bundle.yaml> --type <pageType>` (never `ir/spec.yaml` / `ir/design.yaml`).
   - `<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`).

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

@@ -21,10 +21,28 @@ disable-model-invocation: true
 
 ## Rule: Load Policy
 
-| Read (whole file) | Write | NEVER Read |
+**IR is read-only** (`ir-read-only.md`). Writes go to **`*.bundle.yaml`** (+ `01` for endpoints), then **split**.
+
+| Read (whole file) | Write | NEVER write |
 |---|---|---|
-| **`ir/design.yaml`** (layout, ui, projected api, entities, codegen, tags) | `bundle.gen` on `*.bundle.yaml` → `pnpm spec:split` | `ir/spec.yaml` prose, generated `*.md` |
-| **`api/<seq>/01-backend-spec.yaml`** (endpoint action/path) | endpoint `action` / path on **01** only — NOT `bundle.spec.api` | |
+| **`ir/design.yaml`** (tech SSOT after split) | `bundle.gen` on `*.bundle.yaml` → `flowgrid split` | `ir/spec.yaml`, `ir/design.yaml`, `ir/generated/*` |
+| **`ir/generated/design.md`** — L2 mermaid when `interactionCases.policy: required` (ACP only) | | |
+| **`api/<seq>/01-backend-spec.yaml`** | `action` / path on **01** only — NOT `bundle.spec.api` | |
+
+ACP fields (`userFlows`, `nfr`, `interactionCases`) are **authored on the bundle**; after split, read mirrors on `ir/*` — still **never write** IR.
+
+---
+
+## 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.
 
 ---
 
@@ -32,21 +50,21 @@ disable-model-invocation: true
 
 - **[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)
 
@@ -154,7 +172,7 @@ disable-model-invocation: true
 
 ## Handoff
 
-- bộ code FE dry pass → `/prototype`
+- FE code repo dry pass → `/prototype`
 - BQA↔Dev conflict → `/grill-docs`
 - Legacy fact gap → `/legacy /spec` or `/update-spec` (legacy evidence delta)
 - Confirmed common promote → `/docs-mark` (same session or before `/prototype`)

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

@@ -63,7 +63,7 @@ disable-model-invocation: true
 3. Reconcile `#reuse-api` on page actions/items (no duplicate `api/<seq>/` for reused APIs).
 4. Verify codegen gate: `bundle.gen.codegen.profile` set correctly.
 5. Write/fix `bundle.gen` → `flowgrid audit spec` → `flowgrid_docs_bundle_split` → `docs_render`.
-6. Handoff ID/path + recommendation to bộ code FE (`gen:dry` on FE repo).
+6. Handoff ID/path + recommendation to FE code repo (`gen:dry` on FE repo).
 
 ---
 
@@ -75,7 +75,7 @@ disable-model-invocation: true
 
 ## Handoff
 
-→ `/prototype` after bộ code FE dry-run passes.
+→ `/prototype` after FE code repo dry-run passes.
 
 ---
 

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

@@ -20,7 +20,7 @@ disable-model-invocation: true
 - **[MANDATORY]** Run `flowgrid audit hub-prd <path-to.md>` before editing.
 - **[MANDATORY]** Fix all `gaps[]`; resolve `warnings[]` via patch or `AskQuestion` (Recommended / Other / Log as Tech Debt → `qa/` per `qa-authoring.md`).
 - **[MANDATORY]** Re-run audit until `totalGaps === 0` or gaps deferred to `qa/*.yaml`.
-- **[STRICTLY FORBIDDEN]** Author Personas tables or Success metrics on hub — KPI/persona ngoài hub.
+- **[STRICTLY FORBIDDEN]** Author Personas tables or Success metrics on hub — KPI/persona belong off-hub.
 
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: openapi
-description: /openapi — generate 02-openapi.yaml from 01-backend-spec.yaml on the docs hub (bộ docs).
+description: /openapi — generate 02-openapi.yaml from 01-backend-spec.yaml on the docs hub (docs hub).
 disable-model-invocation: true
 ---
 
@@ -9,7 +9,7 @@ disable-model-invocation: true
 
 # /openapi — OpenAPI YAML (docs hub)
 
-**Owner:** bộ docs (`--type=docs`). OpenAPI is a **docs artifact**, not bộ code.
+**Owner:** docs hub (`--type=docs`). OpenAPI is a **docs artifact**, not code repo.
 
 One generator: **OpenAPI 3.0.3** from `01-backend-spec.yaml`. Merge/UI stays `openapi:render` + Redocly bundle.
 
@@ -34,5 +34,5 @@ One generator: **OpenAPI 3.0.3** from `01-backend-spec.yaml`. Merge/UI stays `op
 
 - **[MANDATORY]** If fragment is too thin (error $refs, missing examples): patch **`01-backend-spec.yaml`** and regenerate.
 - **[STRICTLY FORBIDDEN]** Do NOT hand-edit `02-openapi.yaml` as SSOT.
-- **[STRICTLY FORBIDDEN]** Do NOT run bộ code `--type=docs` or `nestjs --openapi`. Do NOT invent a second generator per stack.
+- **[STRICTLY FORBIDDEN]** Do NOT run code repo `--type=docs` or `nestjs --openapi`. Do NOT invent a second generator per stack.
 - **[STRICTLY FORBIDDEN]** BE `/api` generates implementation code from the contract — it does NOT own OpenAPI YAML.