@shanyucoder/flowgrid 0.1.10 → 0.1.12

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/architecture-core.md

@@ -36,6 +36,8 @@ No **dynamics** wording on new trees — use **flow** / `FLOW-*` / `/journey`.
 
 ## ID rules
 
+**Product IDs (global):** `product-id-convention.md` — `surfaceCode` on each surface; `CMP-{SURF}-{DOMAIN}-{NN}`, `W-{SURF}-{DOMAIN}-{NN}`, `API-{SURF}-{DOMAIN}-{NN}`.
+
 | Prefix | Path | Notes |
 |--------|------|-------|
 | `LND-*` `CTX-*` | `architecture/03-context/` | Overview / landscape + context |

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

@@ -10,7 +10,9 @@
       ".cursor/extracts/tpl-deployment.md",
       ".cursor/extracts/tpl-adr.md",
       ".cursor/extracts/tpl-cross-cutting.md",
-      ".cursor/extracts/common-scope.md"
+      ".cursor/extracts/common-scope.md",
+      ".cursor/extracts/tpl-adoption-inventory.md",
+      ".cursor/extracts/product-id-convention.md"
     ],
     "docs-hub": [
       ".cursor/extracts/docs-phase-hooks.md",
@@ -25,11 +27,15 @@
       ".cursor/extracts/design-leaf-signoff.md",
       ".cursor/extracts/db-audit-wizard.md",
       ".cursor/extracts/agent-execution-protocol.md",
-      ".cursor/extracts/common-scope.md"
+      ".cursor/extracts/common-scope.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/common-scope.md",
+      ".cursor/extracts/product-id-convention.md",
+      ".cursor/extracts/agent-design-context.md"
     ],
     "bqa-grill": [
       ".cursor/extracts/grill/validation.md",
@@ -39,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/extracts/product-id-convention.md

@@ -0,0 +1,58 @@
+# Product ID convention (global SSOT)
+
+English **structure**; prose locale is separate (`contentLocale`).
+
+## Why surface code is mandatory
+
+IDs are **globally unique** across the docs hub (CLI `--id`, registries, tests mirror). The same capability on two channels (e.g. Login on admin vs customer) MUST be two IDs. Path `surfaces/<slug>/` alone is not enough when referencing without a path.
+
+## Surface code (`surfaceCode`)
+
+- Declare on every `surfaces/<slug>/index.md` frontmatter: `surfaceCode: ADM` (2–4 uppercase letters).
+- Register once per channel; reuse the **same token** in every `CMP-*` / `W-*` / `API-*` / `UI-*` on that surface.
+- Folder slug stays human (`admin`, `customer-web`); **IDs embed `surfaceCode`**, not the slug.
+
+| Surface folder | Example `surfaceCode` |
+| --- | --- |
+| `surfaces/admin` | `ADM` |
+| `surfaces/customer-web` | `CUS` |
+| `surfaces/workforce-app` | `WRK` |
+
+## Patterns
+
+| Kind | Pattern | Example |
+| --- | --- | --- |
+| Module (folder name) | `CMP-{SURF}-{DOMAIN}-{NN}` | `CMP-ADM-AUTH-01` |
+| Screen | `W-{SURF}-{DOMAIN}-{NN}` | `W-ADM-AUTH-01` |
+| API | `API-{SURF}-{DOMAIN}-{NN}` | `API-ADM-AUTH-01` |
+| UI code leaf | `UI-{SURF}-{DOMAIN}-{NN}` | `UI-ADM-EMPTY-01` |
+| User flow | `FLOW-{slug}` | `FLOW-checkout` (no surface — scope in doc body) |
+| Common | `CMN-UI-*` / `CMN-API-*` / `CMN-DTO-*` | No surface prefix |
+
+- `{SURF}` = `surfaceCode` (2–4 chars).
+- `{DOMAIN}` = short capability token (`AUTH`, `ORD`, `CART`, `USR`, …).
+- `{NN}` = two digits `01`–`99` per domain on that surface (pad with zero).
+
+## Module folder = global module ID
+
+`surfaces/<slug>/CMP-ADM-AUTH-01/` — folder name **equals** global `CMP-*` id (tooling SSOT).
+
+## Bundle / path slug (lowercase)
+
+`CMP-ADM-ORD-01` + draft `02-01-02` → `page-id: cmp-adm-ord-01-02-01-02` (lowercase, same tokens).
+
+## Hierarchical CLI alias
+
+Lowercase path encoding: `cmp-adm-auth-01-01-01-01` (= module + numeric segments under `CMP-*`).
+
+## Same business name, two surfaces
+
+- Admin login: `W-ADM-AUTH-01`
+- Customer login: `W-CUS-AUTH-01`  
+Shared spec → `CMN-*` or explicit cross-reference; **never** one `W-*` for both.
+
+## Forbidden
+
+- `W-AUTH-01` without `{SURF}` (collision risk).
+- Mixed tokens on one surface (`W-AD-*` vs `W-ADM-*`) — pick one `surfaceCode` and stick to it.
+- Renaming IDs for arc42-only refactors (see `architecture/02-constraints`).

package/harness/docs/extracts/spec-requirement.md

@@ -6,4 +6,4 @@ Required business keys when info exists: `summary`, `userStories` (+ `screenAcce
 
 After patch: `flowgrid split` → `flowgrid render` → BA reads `ir/generated/spec.md` (not hand-written `.md`).
 
-Path SSOT: `surfaces/<surface>/CMP-*/<NN…>/` — resolve IDs with `flowgrid_docs_route` on consumer repo.
+Path SSOT: `surfaces/<surface>/CMP-*/<NN…>/` — resolve IDs with `flowgrid_docs_route` on consumer repo. ID shape: `product-id-convention.md`.

package/harness/docs/extracts/tpl-adoption-inventory.md

@@ -0,0 +1,32 @@
+# Adoption inventory — section template (`adoption-inventory.md`)
+
+Workspace root SSOT after `/adopt`. English **IDs**; prose may follow hub `contentLocale` later. ID shape: `product-id-convention.md` (`surfaceCode`, `CMP|W|API-{SURF}-{DOMAIN}-{NN}`).
+
+## Required sections
+
+1. **Surfaces** — channel / app → legacy repo path  
+2. **Modules (`CMP-*`)** — feature groups → legacy module folder  
+3. **Screens & APIs (`W-*`, `API-*`)** — leaf functions → legacy file paths  
+4. **User flows (`FLOW-*`)** — see placement tiers below (mandatory when scan finds multi-step / cross-app journeys)  
+5. **Common catalog (`CMN-*`)** — only if Common Analysis mode  
+6. **Handoff** — `/legacy /spec`, `/legacy /user-flow`
+
+## User flow placement (maps to new docs hub)
+
+| Tier | When to list | Target path after `/legacy /user-flow` |
+| --- | --- | --- |
+| **A — Cross-surface / org** | Same journey touches **≥2 surfaces** or **≥2 CMP owners** (checkout admin→customer, ops→partner API, SSO handoff) | `architecture/03-user-flows/FLOW-*.md` |
+| **B — Surface shared** | Journey shared by **≥2 modules** on **one** surface | `surfaces/<surface>/common/user-flows/FLOW-*.md` |
+| **C — Module / cluster** | Journey stays inside **one CMP** (or one cluster `CMP-*/NN/`) | `surfaces/<surface>/<CMP>/common/user-flows/FLOW-*.md` or `…/<CMP>/<NN>/common/user-flows/` |
+| **D — Not a FLOW** | Single screen CRUD, one API call | Document only `W-*` / `API-*` — **do not** invent `FLOW-*` |
+
+Each `FLOW-*` line MUST include:
+
+- **Surfaces / CMPs involved** (e.g. `admin`, `CMP-ADM-ORD-01`, `customer-web`, `CMP-CUS-CART-01`)
+- **Screen/API steps** (ordered `W-*` / `API-*` refs or legacy route names)
+- **Legacy evidence** (router guards, saga classes, shared session keys, event names — file paths)
+- **Suggested tier** (A / B / C)
+
+## Legacy scan hints (cross-surface)
+
+Look for: redirect chains across subdomains/apps, shared `orderId`/`session` in multiple repos, BPM/orchestrator, “checkout” spanning cart (FE) + payment (API) + notification (worker), duplicate route names in 2+ legacy apps for one business journey.

package/harness/docs/extracts/tpl-module.md

@@ -1,6 +1,6 @@
 # Module index template
 
-Path: `surfaces/<surface>/CMP-{NN}-{slug}/index.md` — **MD only**.
+Path: `surfaces/<surface>/CMP-{SURF}-{DOMAIN}-{NN}/index.md` — **MD only** (`product-id-convention.md`).
 
 Copy from: `templates/project-skeleton/surfaces/_module-index.template.md`
 

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

@@ -23,4 +23,4 @@ When executing any skill (`/spec`, `/grill`, `/grill-bqa`, etc.):
 6. **DSL / COMMON:** Human lead decides common promotions. The agent only executes `/common` (Markdown patterns), `/docs-mark`, custom-base handoff, or confirmation post-grill. `/spec` consumes patterns + FE base via `flowgrid-ux-common.mdc`. **[STRICTLY FORBIDDEN]** `common/yaml`, `/common-spec`, `/gen-common`.
 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).
+**Path SSOT:** `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment). **IDs:** `product-id-convention.md` (`surfaceCode` + `CMP|W|API-{SURF}-{DOMAIN}-{NN}`).

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

@@ -1,6 +1,6 @@
 ---
 name: adopt
-description: "/adopt — Scan legacy repositories and generate a high-level index mapping catalog & common candidates at root."
+description: "/adopt — Scan legacy repositories and generate a high-level index mapping catalog, user flows (incl. cross-surface), and common candidates at root."
 disable-model-invocation: true
 extractBundle: architecture-core
 ---
@@ -14,6 +14,8 @@ extractBundle: architecture-core
 
 **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).
 
+**Inventory template:** `.cursor/extracts/tpl-adoption-inventory.md` — section layout + **user-flow placement tiers** (cross-surface → `architecture/03-user-flows/`).
+
 ---
 
 ## Rule: Pre-Scan Mode Selection (AskQuestion Wizard)
@@ -71,16 +73,35 @@ extractBundle: architecture-core
   - **Surfaces**: Application and channel names (Admin Portal, Customer Web, Gateway…)
   - **Modules (`CMP-*`)**: Primary feature groups (Auth, Orders, Profile…)
   - **Screens (`W-*`) & APIs (`API-*`)**: UI screens + API endpoints with legacy file paths (`ID → Legacy File Path`)
-  - **Cross-Flow Candidates (`FLOW-*`)**: Business flows spanning multiple screens or services
+  - **User flows (`FLOW-*`)**: Multi-step business journeys — **classify every candidate** (see Rule: User flow discovery)
   - **Common Candidates (`CMN-UI-*`, `CMN-API-*`, `CMN-DTO-*`)**: (If Common Analysis mode selected)
 
 ---
 
+## Rule: User flow discovery (incl. cross-surface)
+
+- **[MANDATORY]** Section **4. User flows (`FLOW-*`)** in `adoption-inventory.md` is **not optional** when the legacy scan finds any journey that spans **more than one screen** or **more than one deployable app/repo** in one business outcome.
+- **[MANDATORY]** For each `FLOW-*`, assign a **placement tier** (target path in the **new** docs hub after `/legacy /user-flow`):
+
+| Tier | Label | List under inventory subsection | New hub path |
+| --- | --- | --- | --- |
+| **A** | Cross-surface / org catalog | `### A — Cross-surface (org catalog)` | `architecture/03-user-flows/FLOW-*.md` |
+| **B** | Surface-shared | `### B — Shared on one surface` | `surfaces/<surface>/common/user-flows/FLOW-*.md` |
+| **C** | Module / cluster | `### C — Module or cluster scope` | `surfaces/.../CMP-*/common/user-flows/` (or `…/<NN>/common/user-flows/`) |
+| **D** | (omit) | — | Single `W-*` only — **no** `FLOW-*` |
+
+- **[MANDATORY]** Each `FLOW-*` bullet MUST state: **surfaces + CMPs involved**, **ordered steps** (`W-*` / `API-*` or legacy route names), **legacy evidence paths** (routers, orchestrators, saga/worker, shared tokens), **tier A/B/C**.
+- **[MANDATORY]** **Cross-surface (tier A)** examples: checkout/payment across customer web + admin ops; partner webhook + internal portal; SSO/login handoff across two SPAs in different legacy repos; order fulfillment touching warehouse API + customer notification app.
+- **[STRICTLY FORBIDDEN]** Listing only `W-*`/`API-*` while ignoring obvious multi-app journeys (tier A/B/C) — Tier 2 audit (`/legacy /user-flow`) depends on this index.
+
+---
+
 ## Rule: ID Standardization
 
+- **[MANDATORY]** Follow `.cursor/extracts/product-id-convention.md` — declare `surfaceCode` per surface; `CMP-{SURF}-{DOMAIN}-{NN}`, `W-{SURF}-{DOMAIN}-{NN}`, `API-{SURF}-{DOMAIN}-{NN}` (duplicate capability across surfaces ⇒ distinct IDs).
 - **[MANDATORY]** All items MUST use standardized IDs: `CMP-*`, `W-*`, `API-*`, `FLOW-*`, `CMN-UI-*`, `CMN-API-*`, `CMN-DTO-*`.
 - **[MANDATORY]** Every ID MUST map to its corresponding legacy file or directory path.
-  - ✅ `W-AD-AUTH-001: Login → admin-fe/src/pages/Login.tsx`
+  - ✅ `W-ADM-AUTH-01: Login → admin-fe/src/pages/Login.tsx`
   - ✅ `CMN-UI-001: Filter Toolbar → duplicated in admin-fe/src/pages/Orders.tsx, Users.tsx`
 
 ---
@@ -96,15 +117,25 @@ extractBundle: architecture-core
 - **Admin Portal** (`surfaces/admin`) → Legacy repo: `admin-fe`
 
 ## 2. Modules Catalog (`CMP-*`)
-- **CMP-ADM-001**: Auth & Identity Management → Legacy: `admin-fe/src/modules/auth/`
+- **CMP-ADM-AUTH-01**: Auth & Identity Management → Legacy: `admin-fe/src/modules/auth/`
 
 ## 3. Screens & API Function Inventory (`W-*`, `API-*`)
-### Admin Portal (`surfaces/admin/CMP-ADM-001`)
-- **W-AD-AUTH-001**: Login → Legacy: `admin-fe/src/pages/Login.tsx`
+### Admin Portal (`surfaces/admin/CMP-ADM-AUTH-01`)
+- **W-ADM-AUTH-01**: Login → Legacy: `admin-fe/src/pages/Login.tsx`
 - **API-ADM-AUTH-01**: Auth Services → Legacy: `auth-service/src/controllers/AuthController.java`
 
-## 4. Cross-Flow Candidates (`FLOW-*`)
-- **FLOW-checkout**: Checkout & Payment Flow → across `CMP-ADM-002` & `CMP-CUS-001`
+## 4. User flows (`FLOW-*`)
+
+### A — Cross-surface (org catalog) → `architecture/03-user-flows/`
+- **FLOW-checkout**: Checkout & payment — Surfaces: `customer-web` (`CMP-CUS-CART-01`), `admin` (`CMP-ADM-ORD-01`) — Steps: cart `W-CUS-CART-01` → pay `API-CUS-PAY-01` → ops `W-ADM-ORD-01` — Legacy: `customer-fe/src/routes/checkout/*`, `admin-fe/src/pages/Orders.tsx`, `payment-svc/...` — Tier: **A**
+
+### B — Shared on one surface → `surfaces/<surface>/common/user-flows/`
+- **FLOW-onboard-admin**: Admin onboarding — Surface: `admin` only — CMPs: `CMP-ADM-AUTH-01`, `CMP-ADM-USR-01` — Steps: … — Legacy: … — Tier: **B**
+
+### C — Module / cluster scope → `…/CMP-*/common/user-flows/`
+- **FLOW-password-reset**: Reset password — Surface: `admin` — CMP: `CMP-ADM-AUTH-01` — Steps: … — Legacy: … — Tier: **C**
+
+> If no multi-step journeys found, write: `_(none detected — screen-only inventory in §3)_`
 
 ## 5. Common Catalog Candidates (Anti-Copy-Paste Guard)
 > **Purpose**: Reuse for specs and code of new features / spec updates.
@@ -122,11 +153,11 @@ extractBundle: architecture-core
 
 ### ⚠️ Whole Page Duplication Warnings
 > **Note**: Do not create `CMN-*` for full pages. Recommend consolidating into a single polymorphic spec (`mode: create | edit`).
-- **W-AD-USER-001 (Create User)** & **W-AD-USER-002 (Edit User)**: 95% identical → *Recommendation: Consolidate into single Form Spec `CMP-ADM-USER-FORM`*
+- **W-ADM-USR-01 (Create User)** & **W-ADM-USR-02 (Edit User)**: 95% identical → *Recommendation: Consolidate into single Form Spec `CMP-ADM-USR-FORM`*
 
 ---
 ## 6. Handoff Usage Guide
-- `/legacy /spec W-AD-AUTH-001` — spec a legacy screen (MUST reuse CMN-* if applicable)
+- `/legacy /spec W-ADM-AUTH-01` — spec a legacy screen (MUST reuse CMN-* if applicable)
 - `/legacy /user-flow FLOW-checkout` — map a legacy flow
 ```
 
@@ -138,5 +169,6 @@ extractBundle: architecture-core
 - [ ] Audit script run; index checked or gaps reported.
 - [ ] `adoption-inventory.md` created directly at workspace root.
 - [ ] All items use standardized `CMP-*`, `W-*`, `API-*`, `FLOW-*`, `CMN-*` IDs.
+- [ ] Section 4 lists user flows with tier **A/B/C** when multi-step/cross-app journeys exist; tier **A** cross-surface rows are explicit.
 - [ ] Common Catalog Candidates listed with source files if Common mode selected.
 - [ ] Anti-Copy-Paste Guard enforced for new spec/code.

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/api-update/SKILL.md

@@ -28,7 +28,7 @@ Shared extracts: `api-spec-sync.md`, `spec-evolution.md`, `entity-relationship.m
 
 ## Rule: ID Resolution & Folder Location
 
-- **[MANDATORY]** If an ID is provided (e.g. `CMP-ADM-000-001`, `W-AD-AUTH-001`) → use `flowgrid_docs_route` or glob to resolve to `…/api/<seq>/01-backend-spec.yaml`. Do NOT force user to provide full filesystem path.
+- **[MANDATORY]** If an ID is provided (e.g. `CMP-ADM-AUTH-01-001`, `W-ADM-AUTH-01`) → use `flowgrid_docs_route` or glob to resolve to `…/api/<seq>/01-backend-spec.yaml`. Do NOT force user to provide full filesystem path.
 - **[MANDATORY]** Trio lives under `api/<seq>/` — never adjacent to `*.bundle.yaml`.
 - Common APIs: `…/common/yaml/<slug>/01-backend-spec.yaml` (one trio per API).
 

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

@@ -1,6 +1,6 @@
 ---
 name: module
-description: EXCLUSIVE /module — Handles business modules (CMP-*). DO NOT output fake Markdown reports.
+description: EXCLUSIVE /module — Handles business modules (CMP-{SURF}-{DOMAIN}-{NN}). DO NOT output fake Markdown reports.
 disable-model-invocation: true
 extractBundle: architecture-core
 ---

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`)
@@ -85,9 +85,10 @@ Hub: [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) · extract `
 
 ## Rule: Target / ID Resolution
 
+- **[MANDATORY]** Product IDs per `product-id-convention.md` (`surfaceCode`, `CMP-{SURF}-{DOMAIN}-{NN}`, `W-{SURF}-{DOMAIN}-{NN}`).
 - **[MANDATORY]** Resolve screen ID, module ID, slug, or Draft ID before generating any file.
   - Draft ID `1-1-2` → pad each segment → `01/01/02/`
-  - Bundle ID: module prefix + padded segments, e.g. `CMP-ADM-002` + `02-01-02` → `page-id: cmp-adm-002-02-01-02`
+  - Bundle ID: module prefix + padded segments, e.g. `CMP-ADM-ORD-01` + `02-01-02` → `page-id: cmp-adm-ord-01-02-01-02`
 - **[MANDATORY]** Search for input `.md` file at resolved path. If found, read it as primary requirement source — do NOT say "I cannot hallucinate" or ask user for input that is already present.
 - **[STRICTLY FORBIDDEN]** Do NOT demand full filesystem path from user when ID or slug is given.
 
@@ -148,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`)
@@ -268,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/surfaces/SKILL.md

@@ -16,6 +16,7 @@ extractBundle: architecture-core
 
 ## Rule: Target Resolution
 
+- **[MANDATORY]** On create: set `surfaceCode` (2–4 uppercase letters) in `surfaces/<slug>/index.md` frontmatter — SSOT for all `CMP-*` / `W-*` / `API-*` on this channel (`product-id-convention.md`).
 - **[MANDATORY]** Use `flowgrid_docs_route` or `flowgrid_docs_get_element` (or glob) to resolve the target surface directory under `surfaces/[Surface Name]/`.
 - **[STRICTLY FORBIDDEN]** Do NOT confuse an API with a surface. APIs belong to architecture containers or function-level API contracts.
 

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/grill-prototype/SKILL.md

@@ -14,7 +14,7 @@ disable-model-invocation: true
 
 ## Target / ID Resolution Rule
 
-- User prompt MAY specify screen ID, function ID, or slug (e.g. `W-AD-AUTH-001`, `login`).
+- User prompt MAY specify screen ID, function ID, or slug (e.g. `W-ADM-AUTH-01`, `login`).
 - **Read the entire `ir/design.yaml`** on the screen leaf (`…/CMP-*/<NN…>/ir/design.yaml`). Do **not** use `01-backend-spec.yaml` as FE input.
 - Docs hub is **read-only**. Do not patch `*.bundle.yaml` or `ir/*`.
 - Compare route + rendered UI to `ir/design.yaml` (actions, validation copy, states, testIds).