@shanyucoder/flowgrid 0.1.5 → 0.1.8

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

@@ -20,7 +20,7 @@ When executing any skill (`/spec`, `/grill`, `/grill-bqa`, etc.):
 3. **NO RAM CACHING:** All persistent changes **[MANDATORY]** immediately written via `{{FLOWGRID_WRITE_TOOL}}`. Never hold uncommitted state in chat/RAM. When a grill proposal is not yet confirmed → discuss directly in chat thread. **[STRICTLY FORBIDDEN]** to create temporary `*-proposal.md` files or overwrite product SSOT prior to explicit confirmation.
 4. **ZERO BUSINESS HALLUCINATION:** Ground data strictly from (1) User prompt and (2) ArtifactGraph registry. **[STRICTLY FORBIDDEN]** to invent fields, validations, database structures, or flows. Missing information must remain empty or be tagged `#missing_info`. No unprompted guessing.
 5. **GRILL HARD GATE:** ArtifactGraph re-check → micro-scope → provide structured recommendation (`(Recommended)`) → **STOP and prompt Member**. **[STRICTLY FORBIDDEN]** to write to SSOT before explicit user confirmation.
-6. **DSL / COMMON:** Human lead decides common promotions. The agent only executes `/common`, `/common-spec`, `/docs-mark`, or confirmation post-grill. `/spec` strictly consumes common definitions. **[STRICTLY FORBIDDEN]** to invent or overwrite common libraries spontaneously.
+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).

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

@@ -6,7 +6,7 @@ alwaysApply: false
 
 # Team Flow — Spec
 
-Active commands: `/spec`, `/grill-bqa`, `/grill-dev`, `/grill-docs`, `/update-spec`, `/update-spec-legacy` — one per session.
+Active commands: `/spec`, `/grill-bqa`, `/grill-dev`, `/grill-docs`, `/update-spec` — one per session.
 
 > [!CRITICAL] MANDATORY AGENT INSTRUCTION
 > You MUST read and strictly enforce all guidelines in the target skill's `SKILL.md` file before starting any step in this pipeline.
@@ -18,18 +18,17 @@ Active commands: `/spec`, `/grill-bqa`, `/grill-dev`, `/grill-docs`, `/update-sp
 | `/grill-dev` | `.cursor/skills/grill-dev/SKILL.md` |
 | `/grill-docs` | `.cursor/skills/grill-docs/SKILL.md` |
 | `/update-spec` | `.cursor/skills/update-spec/SKILL.md` |
-| `/update-spec-legacy` | `.cursor/skills/update-spec-legacy/SKILL.md` |
 | Grill metadata rules | `.cursor/rules/team-flow-grill.mdc` |
 
 Shared: resolve skill `extractBundle` → `.cursor/extracts/extract-registry.docs.json` (e.g. `bqa-grill`, `dev-grill`, `grill-docs`).
 
 ## Pipeline
 
-1. **`/spec`** — `*.bundle.yaml` design v1 + testcase round 1. Per-zone: DSL/registry → bundle; gaps → `#needs-component` / `#needs-ui` + `flowgrid-ux-common` proposals → `AskQuestion`. No `gen` / `codegen`.
+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.
 2. **`/grill-bqa`** — UI, acceptance, breadcrumb, delete rules.
 3. **`/grill-dev`** — codegen-ready bundle + `tags`; emit bộ code FE dry-run handoff.
 4. **`/grill-docs`** — optional reconcile when BQA↔Dev contradict.
-5. **`/update-spec`** / **`/update-spec-legacy`** — controlled delta + `#update:*` (not full rewrite).
+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.
 
 - Render: `docs_render` / `flowgrid render` (pnpm fallback during transition)

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

@@ -12,6 +12,8 @@ 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).
+
 ---
 
 ## Rule: Pre-Scan Mode Selection (AskQuestion Wizard)

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

@@ -1,6 +1,6 @@
 ---
 name: api
-description: EXCLUSIVE /api — Backend Router ONLY. Immediately routes to /api-spec or /api-integration without generating gross files.
+description: EXCLUSIVE /api — Backend Router ONLY. Immediately routes to /api-spec, /api-update, or /grill-api-spec without generating gross files.
 disable-model-invocation: true
 ---
 
@@ -18,14 +18,13 @@ disable-model-invocation: true
 
   | Condition | Route to |
   |---|---|
-  | No `01-backend-spec.yaml` + Portal-backed | `/api-spec` |
-  | No `01-backend-spec.yaml` + webhook/partner/no FE (`base: none`) | `/api-integration` |
+  | No `01-backend-spec.yaml` (portal-backed or BE-only / webhook / partner) | `/api-spec` |
   | 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` or `/grill-integration-spec` (per `source.kind`) |
+  | 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) |
 
-- **[MANDATORY]** Locate `01-backend-spec.yaml` under: `…/api/<seq>/` (screen leaf), `…/common/yaml/<slug>/`, or `…/integrations/…/api/<seq>/`.
+- **[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.
 - PHPUnit coverage: NOT routed here — use `/unit-be` directly.
 

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 > [!CRITICAL] MANDATORY PRE-FLIGHT
 > **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
-> **[MANDATORY]** Read template `.flowgrid/templates/backend-api.bundle.yaml` BEFORE generating any YAML.
+> **[MANDATORY]** Read `.flowgrid/templates/backend-api.yaml`, `.flowgrid/templates/tpl-api-contract.md`, and `.cursor/extracts/api-contract.md` BEFORE generating any YAML.
 > If missing → STOP: *"Template missing. Run `flowgrid init`."*
 > **[MANDATORY]** Read entire `ir/design.yaml` first (actions + nested items with `apiRefs`). If `ir/` is missing, read `*.bundle.yaml`.
 
@@ -22,9 +22,9 @@ Hashtag extracts: `#call-external` → `call-external.md`; `#cross-entity-servic
 
 ## Rule: Audit Interlock
 
-- **[MANDATORY]** Always run static audit first: `flowgrid audit api <target-api.bundle.yaml>`.
+- **[MANDATORY]** After drafting or updating `01-backend-spec.yaml`, run `flowgrid audit api <path-to-01-backend-spec.yaml>`.
   - ✅ Consume JSON gap report to fix issues or trigger AskQuestion wizard (≥3 options).
-  - ❌ Do not skip audit and proceed to authoring directly.
+  - ❌ Do not hand off without audit on the `01` file. Do **not** use `flowgrid check` on `01` (`check` is bundle IR only).
 
 ---
 
@@ -94,7 +94,7 @@ Hashtag extracts: `#call-external` → `call-external.md`; `#cross-entity-servic
     api/01/
       01-backend-spec.yaml   ← VALID YAML (double-quote all colons)
       02-openapi.yaml
-      03-mock-data.yaml
+      03-mock.yaml
   ```
 - **[MANDATORY]** Common APIs → LCA `common/yaml/<component-slug>/`.
 - **[MANDATORY]** One `01-backend-spec.yaml` = one module + one primary entity. Never dump every screen API into one file.
@@ -102,12 +102,24 @@ Hashtag extracts: `#call-external` → `call-external.md`; `#cross-entity-servic
 
 ---
 
+## Rule: BE-only / external channel (no portal FE)
+
+Use the **same** skill (`/api-spec`) and same trio layout when there is no portal screen (`feature.source.base: none`, webhooks, partner/public APIs).
+
+- **[MANDATORY]** Place contract trio under a normal surface leaf, e.g. `surfaces/<external-surface>/<provider>/<slug>/api/<seq>/` (dedicated surface for partner/webhook channel — not a separate skill).
+- **[MANDATORY]** Set `feature.source.kind`, `base: none`, `integrationRefs[]` (or equivalent refs), empty `portalRefs`, `contexts.portalLayout: none`, and `contexts.auth` (API key / HMAC / OAuth).
+- **[MANDATORY]** Domain tags: `#webhook-inbound`, `#webhook-outbound`, `#partner-api`, `#public-api`, `#call-external`, `#err:*` (include `#err:signature-invalid`, `#err:rate-limit`, `#err:unauthorized` when relevant).
+- **[MANDATORY]** Scan sibling `…/api/<seq>/` and surface `common/yaml/` before creating new endpoints; reuse via `#reuse-api` when applicable.
+- **[STRICTLY FORBIDDEN]** Do not invent HMAC secrets or partner validation logic; use AskQuestion or `qa/open/` tech debt.
+
+---
+
 ## Rule: YAML Syntax Safety
 
 - **[MANDATORY]** All strings containing `:` must be double-quoted.
   - ✅ `summary: "Create: New Employee Registration"`
   - ❌ `summary: Create: New Employee Registration`
-- **[MANDATORY]** Run `flowgrid check --spec …/api/01/01-backend-spec.yaml` before handoff.
+- **[MANDATORY]** Run `flowgrid api:check --spec …/api/01/01-backend-spec.yaml` before handoff.
 - **[MANDATORY]** Domain tags only (`#call-external`, `#cross-entity-service`, `#err:*`). No `#gen:*` or `codegen` block from this skill.
 
 ---
@@ -133,4 +145,5 @@ Hashtag extracts: `#call-external` → `call-external.md`; `#cross-entity-servic
 - [ ] All new endpoints use explicit action URI suffixes.
 - [ ] `#err:*` tags applied per endpoint nature (not-found + IDOR on `{id}`, validation on POST/PUT, etc.).
 - [ ] Strings with `:` in YAML are double-quoted. No `.md` written directly.
-- [ ] `flowgrid check` passed with zero errors.
+- [ ] `flowgrid api:check --spec …/01-backend-spec.yaml` passed.
+- [ ] `flowgrid render` (or hub render script) so `ir/generated/api.md` is current for reviewers.

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

@@ -40,8 +40,8 @@ Shared extracts: `api-spec-sync.md`, `spec-evolution.md`, `entity-relationship.m
    - `#reuse-api` actions → do NOT create a new `01`.
    - Do NOT treat projected `design.api` as BE SSOT.
 2. **[MANDATORY]** Diff requirements, endpoints, acceptance vs `01-backend-spec.yaml`.
-3. **[MANDATORY]** Patch `01-backend-spec.yaml` (+ `03-mock-data.yaml` if samples change).
-4. **[MANDATORY]** Run: `flowgrid check --spec …/01-backend-spec.yaml` → `flowgrid openapi_gen --spec …/01-backend-spec.yaml` (writes sibling `02`).
+3. **[MANDATORY]** Patch `01-backend-spec.yaml` (+ `03-mock.yaml` if samples change).
+4. **[MANDATORY]** Run: `flowgrid api:check --spec …/01-backend-spec.yaml` → `flowgrid openapi_gen --spec …/01-backend-spec.yaml` (writes sibling `02`).
 5. **[MANDATORY]** Bump `feature.version` + add `changeLog` entry.
 6. **[STRICTLY FORBIDDEN]** Never hand-edit `02-openapi.yaml` as SSOT. Never write `.md` directly.
 
@@ -77,6 +77,6 @@ Shared extracts: `api-spec-sync.md`, `spec-evolution.md`, `entity-relationship.m
 
 - [ ] Target is `…/api/<seq>/01-backend-spec.yaml` (or `common/yaml/<slug>/`), not a `01` on the FE leaf.
 - [ ] `01` patched; `02` regenerated via `openapi:gen` (not hand-edited).
-- [ ] Gates passed: `flowgrid check` + `flowgrid openapi_gen`.
+- [ ] Gates passed: `flowgrid api:check --spec …/01` + `flowgrid openapi_gen` + `flowgrid render` (refresh `ir/generated/api.md`).
 - [ ] `changeLog` + `feature.version` bumped.
 - [ ] No `.md` written directly. No `openQuestions` in YAML.

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

@@ -22,7 +22,7 @@ extractBundle: architecture-core
   | Product overview / operational areas | `/overview` |
   | Business/interaction surfaces | `/surfaces` |
   | Common UX/UI rules (Markdown) | `/common` |
-  | Common technical bundles for codegen (YAML) | `/common-spec` / `/grill-common-spec` |
+  | Shared UI templates / registry on FE base | [custom-base](../../../docs/workflows/custom-base.md) · `/build-template-code` |
   | Module / CMP box | `/module` |
   | Screen / API detail | `/spec` |
   | Where it runs / Infrastructure | `/deployment` |

package/harness/docs/skills/business-process/SKILL.md

@@ -12,6 +12,8 @@ extractBundle: architecture-core
 
 **Mindset:** Model the process by **business actions on surfaces**, not by repository or service topology.
 
+**Template:** `architecture/03-business-process/FLOW-template.md` (or surfaces `common/processes/FLOW-*.md`) — include **Success metrics** and **Non-goals** in §1 when information exists.
+
 ---
 
 ## Rule: Audit Interlock

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

@@ -1,6 +1,6 @@
 ---
 name: common
-description: EXCLUSIVE /common — Use this to define common business rules, UX/UI rules, and patterns for a Surface as Markdown documentation. DO NOT use this to generate YAML technical bundles (use /common-spec for that).
+description: EXCLUSIVE /common — Markdown rules under common/patterns/ (and cross-flow context). DO NOT author common/yaml or gen-common (deprecated).
 disable-model-invocation: true
 ---
 
@@ -35,7 +35,7 @@ Markdown rules for a **named scope** (cluster / module / surface / global). Not
 - **[MANDATORY]** Use clear, non-technical language geared towards Business / QA / Dev alignment.
 - **[MANDATORY]** Define rules based on surface type when applicable (e.g. Kiosk UI rules differ from Web Portal rules).
 - **[STRICTLY FORBIDDEN]** Do NOT output fake i18n tables or framework prose. Focus on actual rules (e.g. "Confirm dialog must always block background").
-- **[STRICTLY FORBIDDEN]** Do NOT generate YAML bundles here — use `/common-spec` for codegen bundles.
+- **[STRICTLY FORBIDDEN]** Do NOT generate `common/yaml`, CMN bundles, or invoke `/gen-common` / `/common-spec` (deprecated). UI patterns are enforced via FE base + `flowgrid-ux-common.mdc`; new templates → [custom-base](../../../docs/workflows/custom-base.md).
 
 ---
 

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

@@ -1,55 +1,18 @@
 ---
 name: common-spec
-extractBundle: spec-core
-description: EXCLUSIVE /common-spec — Use this to define common technical bundles (YAML) for a Surface for Codegen. DO NOT output Markdown files.
+description: DEPRECATED — common no longer uses YAML bundles on the docs hub. Use /common (Markdown) or custom-base.
 disable-model-invocation: true
 ---
 
-> [!CRITICAL] MANDATORY PRE-FLIGHT
-> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
-> **[MANDATORY]** Read `.cursor/extracts/common-scope.md` first to resolve the LCA path.
+# /common-spec — DEPRECATED
 
-# /common-spec — Common Technical Bundle (YAML)
+Common technical bundles (`common/yaml`, `*.bundle.yaml` under `surfaces/.../common`) are **no longer** part of the product workflow.
 
-**Target Path:** `<LCA>/common/yaml/<slug>/<slug>.bundle.yaml` (LCA from `common-scope.md`).
+| Need | Use |
+|------|-----|
+| Cross-flow product doc | `common/processes/FLOW-*.md` |
+| Shared UX/business rules | `/common` → `common/patterns/*.md` |
+| UI patterns (delete flow, badges, flat design, …) | FE **base** + `flowgrid-ux-common.mdc` during `/spec` / grill |
+| New shared component / codegen template | [custom-base](../../../docs/workflows/custom-base.md) → `build-template-code` |
 
-**Gate:** Only use when user explicitly invokes `/common-spec` or confirmed a grill proposal to promote common.
-
----
-
-## Rule: Platform-Agnostic Generation
-
-- **[MANDATORY]** Use `design.shell.tag` to match target surface type:
-  - Web Portal → `#shell: DataListPage`
-  - WinForms Kiosk → `#shell: KioskCheckIn`
-  - Gateway → `#shell: OtAdapter`
-- **[MANDATORY]** Populate `spec.clients` if applicable.
-- **[RECOMMENDED]** For known Web patterns (e.g. `confirm-dialog`): ask if user wants to inherit from seed template in `templates/project-skeleton/surfaces/common/yaml/`.
-- **[MANDATORY]** For non-Web surfaces → generate new bundle tailored to that requirement. Do NOT force Web template inheritance.
-
----
-
-## Rule: Output
-
-- **[MANDATORY]** Output MUST be `.bundle.yaml`. Do NOT write `.md` directly.
-- **[MANDATORY]** All strings containing `:` must be double-quoted.
-- **[MANDATORY]** After writing: instruct user to run `flowgrid split -- <path>` (must emit `ir/design.yaml`), then `flowgrid render`. Run `flowgrid split --check` to verify.
-- **[STRICTLY FORBIDDEN]** Do NOT send BE `/api` a common FE bundle. bộ code → FE `/gen-common` only.
-
----
-
-## Workflow
-
-1. Read `common-scope.md`. Identify consumers → one LCA `common/yaml/<slug>/`.
-   - Example module-local: `surfaces/admin/CMP-ADM-002/common/yaml/confirm-dialog/confirm-dialog.bundle.yaml`
-2. Generate `.bundle.yaml` using `portal-feature-bundle/v1` schema.
-3. Instruct user: `flowgrid split -- <path>` → `flowgrid render`.
-
----
-
-## Verification Checklist
-
-- [ ] LCA resolved from `common-scope.md`; path correctly scoped.
-- [ ] `design.shell.tag` matches target surface type.
-- [ ] `.bundle.yaml` output only (no `.md`). YAML strings with `:` are double-quoted.
-- [ ] `flowgrid split --check` passes (emits `ir/design.yaml`).
+**If invoked:** STOP and redirect — do not author `common/yaml` or run `flowgrid split` for CMN bundles.

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

@@ -10,16 +10,33 @@ extractBundle: architecture-core
 
 # /db-erd — Business Data Model (ERD)
 
+**Phase:** **0 Architecture** — sau `/overview`, `/module`, `/business-process` khi có entity/bảng mới. **Trước** `/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.
+
 ---
 
 ## Rule: Modeling Approach
 
 - **[MANDATORY]** Use Mermaid `erDiagram`. Start from business entities and domain data ownership — NOT from a raw repository schema dump.
 - **[MANDATORY]** Place shared entities in the common scope when reused by multiple surfaces or modules.
+- **[MANDATORY]** Document per entity: business name, owning `CMP-*` / surface, primary key, main attributes (not every UI-only field).
 - **[STRICTLY FORBIDDEN]** Do NOT use this skill as a per-repository ORM/schema export unless the repository boundary strictly represents the actual data boundary.
+- **[STRICTLY FORBIDDEN]** Do NOT author per-screen `db:` bindings here — that is `/spec` (Phase 1).
+
+---
+
+## Rule: Phase 0 sequence
+
+1. Confirm LCA with `common-scope.md` (same as `/common` patterns).
+2. Read existing `db-erd.md` at wider LCA if any — extend, do not fork duplicate ER.
+3. Write/update `<LCA>/common/db-erd.md`.
+4. Optional: link entities in `common/data-model/index.md` (prose / `#derived-data` only).
 
 ---
 
@@ -27,3 +44,12 @@ VitePress/publish menu label: **`db-erd`** (not the H1 heading).
 
 - **[MANDATORY]** Reference source mappings from `legacy-repos.local.json`.
 - **[MANDATORY]** Map legacy schema to the business data model and entity ownership.
+
+---
+
+## Verification Checklist
+
+- [ ] LCA path correct; single `db-erd.md` at that level.
+- [ ] Mermaid `erDiagram` renders; entities have owner module/surface.
+- [ ] Main relationships and cardinality documented.
+- [ ] No per-screen column inventory (deferred to `/spec`).

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

@@ -1,46 +1,52 @@
 ---
 name: grill
-description: /grill — General discovery/gap-fill grill before authoring any skill. Routes to the correct specialized grill.
+description: /grill — Gap router only. Routes to specialized grill skills; never authors SSOT inline.
 disable-model-invocation: true
 ---
 
 > [!CRITICAL] MANDATORY PRE-FLIGHT
 > **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
 
-# /grill — Discovery & Gap Fill Router
+# /grill — Discovery & Gap Router
 
-**Mindset:** Discovery and resolution of ambiguity — not authoring. Route to the correct specialized grill.
+**Mindset:** Surface **gaps / orphans / misalignment** — route to one specialized grill. **Not** authoring, **not** multi-phase product planning.
+
+SSOT flow: `docs/workflows/grill-and-human-review.md` · close checklist: `docs/workflows/gates.md#close-one-function`.
 
 ---
 
 ## Rule: Routing Logic
 
-- **[MANDATORY]** Route based on what is unclear or incomplete:
-
-  | Context | Route to |
-  |---|---|
-  | UI/UX acceptance, copy, layout gaps | `/grill-bqa` |
-  | Codegen tags, API contracts, `bundle.gen` | `/grill-dev` |
-  | Backend API spec trio (Portal FE exists) | `/grill-api-spec` |
-  | Integration contract (webhook/partner/no FE) | `/grill-integration-spec` |
-  | Architecture-level design (services, C4) | `/architecture-grill` |
-  | Common YAML bundle audit | `/grill-common-spec` |
-  | Doc hub content quality | `/grill-docs` |
-
-- **[STRICTLY FORBIDDEN]** Do NOT use `/grill` as a catch-all that attempts to resolve all gaps inline — always route to the specialized grill for that domain.
+- **[MANDATORY]** Pick **one** row — then run that skill in a **new focused session** when possible:
+
+  | Gap context | Route to |
+  | --- | --- |
+  | 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` |
+  | `01-backend-spec.yaml` contract (portal or `base: none`) | `/grill-api-spec` |
+  | Generated BE routes/code vs `01` | `/audit-api` (BE repo) |
+  | Prototype / mock boundary / testIds before ship UI | `/grill-prototype` |
+  | `TC-*.yaml` plan, matrix, trace bundle (tests-docs hub) | `/grill-testcase` |
+  | Playwright `*.spec.ts` ↔ TC ↔ PO (after `/test` green) | `/grill-test` |
+  | Unit tests (FE or BE lane) | `/grill-unit` or `/grill-api-unit` |
+  | Architecture / C4 / cross-service boundary | `/architecture-grill` |
+  | Shared rule Markdown (`common/patterns`) | `/common` — not YAML grill |
+
+- **[STRICTLY FORBIDDEN]** Resolve all domains in one `/grill` chat.
+- **[STRICTLY FORBIDDEN]** Use `/grill-docs` for first-pass spec — only **reconcile** after `/grill-bqa` + `/grill-dev`.
 
 ---
 
 ## Rule: Missing Information Protocol
 
-- **[MANDATORY]** All discovered gaps → trigger `AskQuestion` wizard per specialized skill guidelines. Present one question at a time with **≥3 options**.
-- **[MANDATORY]** After member answers → route to the appropriate specialized skill.
-- **[STRICTLY FORBIDDEN]** Do NOT invent business rules, API contracts, or UI copy during general grill.
+- **[MANDATORY]** Delegate AskQuestion wizard to the target skill (≥3 options, Law 2 hard stop at ≥10 gaps).
+- **[STRICTLY FORBIDDEN]** Invent business rules, API contracts, or UI copy in the router.
 
 ---
 
 ## Verification Checklist
 
-- [ ] Identified correct specialized grill for the gap type.
-- [ ] Gaps surfaced via AskQuestion wizard (≥3 options).
-- [ ] Routed to correct specialized skill with gap context.
+- [ ] Exactly one specialized grill chosen for the reported gap type.
+- [ ] Member told which audit CLI the target skill will run (`audit spec`, `cases:gate`, `audit e2e`, `audit api`, …).
+- [ ] No SSOT files authored from this router.

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

@@ -1,15 +1,13 @@
 ---
 name: grill-api
-description: >-
-  /grill-api — Discovery router for backend API grill. Routes to /grill-api-spec
-  (Portal-backed) or /grill-integration-spec (webhook/partner/no FE) based on source.kind.
+description: /grill-api — docs-hub router to /grill-api-spec only. BE code audit uses /audit-api on API repo.
 disable-model-invocation: true
 ---
 
 > [!CRITICAL] MANDATORY PRE-FLIGHT
 > **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
 
-# /grill-api — Backend Grill Router
+# /grill-api — Contract grill router (docs hub)
 
 ---
 
@@ -20,7 +18,7 @@ disable-model-invocation: true
   | Context | Route to |
   |---|---|
   | `feature.source.base` is Portal | `/grill-api-spec` |
-  | `feature.source.base: none` / webhook / partner | `/grill-integration-spec` |
+  | `feature.source.base: none` / webhook / partner | `/grill-api-spec` |
 
-- **[MANDATORY]** If `01-backend-spec.yaml` does not exist yet → run `/api-spec` or `/api-integration` first.
+- **[MANDATORY]** If `01-backend-spec.yaml` does not exist yet → run `/api-spec` first.
 - **[STRICTLY FORBIDDEN]** Do NOT attempt to audit the API contract from within this routing skill — delegate immediately.

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

@@ -1,57 +1,77 @@
 ---
 name: grill-api-spec
-description: EXCLUSIVE /grill-api-spec — ONLY for auditing backend API contracts under surfaces/ (Portal FE backed). DO NOT generate Markdown reports.
+description: EXCLUSIVE /grill-api-spec — audit backend API contracts under surfaces/. DO NOT generate Markdown reports.
 disable-model-invocation: true
 ---
 
 > [!CRITICAL] MANDATORY PRE-FLIGHT
 > **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
-> **[MANDATORY]** Read entire `ir/design.yaml`. If `ir/` is missing, read entire `*.bundle.yaml`.
+> **[MANDATORY]** Read `.cursor/extracts/api-codegen-readiness.md`, `api-codegen-tags.md`, `verify-gate.md`, and `api-contract.md`.
+> **[MANDATORY]** When `feature.source.base` ≠ `none`: read entire `ir/design.yaml`. If `ir/` is missing, read entire `*.bundle.yaml`.
+> **[MANDATORY]** When `feature.source.base: none` (webhook/partner/public API, no portal FE): do **not** use `ir/design.yaml` as BE contract — audit `01-backend-spec.yaml` only.
 
-# /grill-api-spec — API Contract Audit (Portal FE)
+# /grill-api-spec — API Contract Audit
 
 After `/api-spec`. Before bộ code BE `/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`, `agent-discipline.md`, `verify-gate.md`
+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`
 
 ---
 
 ## Rule: Scope
 
-- **[MANDATORY]** Audit `…/api/<seq>/01-backend-spec.yaml`; never a `01` directly on the function slug leaf itself.
+- **[MANDATORY]** Audit `…/api/<seq>/01-backend-spec.yaml` under any surface path (`surfaces/<surface>/…/api/<seq>/`, including dedicated external-channel surfaces).
 - **[STRICTLY FORBIDDEN]** No BQA 3-Pillars reports. No framework code snippets. No writing `ir/*`.
 
 ---
 
 ## Rule: Audit Steps
 
+**Portal-backed (`feature.source.base` ≠ `none`):**
+
 - **[MANDATORY]** Step 1 — Reuse check: `#reuse-api` actions/items must have NO extra trio; `reuseFrom` must point to an existing `01`.
 - **[MANDATORY]** Step 2 — Cross-check requirements vs endpoints, entities, permissions, validations, errors.
-- **[MANDATORY]** Step 3 — Engineering & Error hashtag audit:
-  - Verify `#call-external`, `#cross-service`, `#cross-entity-service`, `#derived-data`.
-  - `#tech-debt:*` MUST be `#tech-debt:QA-<feature.id>-NNNN` with a matching file in `qa/open/`.
-  - Endpoint error storming: `{id}` routes → `#err:not-found` (404) + `#err:idor-violation` (403); POST/PUT → `#err:validation` (422); authed routes → `#err:permission-denied` (403).
-- **[MANDATORY]** Step 4 — Enrich `01` with: `codegen.profile|entity|module`, `api.endpoints[].action`, `#gen:*` tags, `approval`.
-- **[MANDATORY]** Step 5 — Run gates:
-  - `flowgrid check --spec surfaces/<surface>/CMP-*/<NN…>/api/<seq>/01-backend-spec.yaml`
-  - `flowgrid openapi_gen --spec …/01-backend-spec.yaml`
-  - `flowgrid openapi_render`
-- **[MANDATORY]** Only ask member for product decisions; resolve technical gaps from codebase/Portal evidence.
+- **[MANDATORY]** Step 3 — Engineering & Error hashtag audit (`#call-external`, `#tech-debt:QA-*`, error storming matrix).
+- **[MANDATORY]** Step 4 — Enrich `01` with `codegen.profile|entity|module`, `api.endpoints[].action`, `#gen:*`, `approval`.
+
+**BE-only / external channel (`feature.source.base: none`):**
+
+- **[MANDATORY]** Authentication, `securitySchemes`, idempotency keys, retry policies, non-CRUD actions.
+- **[MANDATORY]** Enrich with `#gen:*`, `#manual-service`, `#call-external`, `codegen.profile|entity|module`, `endpoints[].action`.
+- **[MANDATORY]** Partner/webhook error tags: `#err:signature-invalid`, `#err:rate-limit`, `#err:unauthorized` where applicable.
 
 ---
 
-## Rule: Missing Information
+## Rule: Gates
+
+Run from docs hub cwd (or pass `--docs-root`); paths relative to docs hub:
+
+**Deterministic audit (lượng):**
+
+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.
 
-- **[MANDATORY]** Unknown facts → `AskQuestion` wizard, one question at a time, ≥3 options: (1) Recommended, (2) Other, (3) "Log as Tech Debt".
-- **[STRICTLY FORBIDDEN]** No `openQuestions` in YAML. No inventing endpoint logic.
+**Contract toolchain:**
+
+3. `flowgrid api:check --spec <path-to-01-backend-spec.yaml>`
+4. `flowgrid openapi_gen --spec <same-01>`
+5. `flowgrid openapi_render`
+
+Re-run steps 1–5 after patching `01` until audit gaps are resolved or logged as `#tech-debt:QA-*`.
+
+- **[STRICTLY FORBIDDEN]** Do **not** run `flowgrid check` on `01-backend-spec.yaml` — `flowgrid check` is for `*.bundle.yaml` IR sync only.
 
 ---
 
 ## Verification Checklist
 
-- [ ] `#reuse-api` actions have no extra trio; `reuseFrom` points to existing `01`.
-- [ ] Target: `01-backend-spec.yaml` under `…/api/<seq>/` or `…/common/yaml/<slug>/`.
-- [ ] Error matrix: `{id}` → 404 + 403 IDOR; POST/PUT → 422; global via OpenAPI `$ref`.
-- [ ] `#gen:*` + `action` populated on new `01` files.
-- [ ] Gates executed: `flowgrid check` + `openapi:gen` + `openapi:render` exit 0.
-- [ ] `approval.status` updated on new `01` YAML.
+- [ ] Target: `01-backend-spec.yaml` under `…/api/<seq>/`.
+- [ ] Portal-backed: `#reuse-api` + error matrix; BE-only: auth + idempotency + retry + `#call-external`.
+- [ ] `audit api` (+ `audit fe-be` when portal bundle present) consumed; no silent structural gaps.
+- [ ] Gates: `api:check` + `openapi_gen` + `openapi_render` exit 0.
+- [ ] `approval.status` updated on `01` YAML.
+- [ ] No `openQuestions` in YAML; no `.md` written directly.
+
+## Handoff
+
+- `approval.status: approved` → bộ code BE `/api` with `--spec …/01-backend-spec.yaml`

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

@@ -26,17 +26,30 @@ disable-model-invocation: true
 
 ---
 
+## Rule: Audit Interlock (`flowgrid audit spec`)
+
+- **[MANDATORY]** Before Step A: run `flowgrid audit spec <*.bundle.yaml> --type <pageType>`.
+  - `<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`).
+- **[MANDATORY]** After any bundle patch in Step A or B: **re-run** `flowgrid audit spec` until structural `gaps[]` empty or deferred via `qa/open/QA-<bundle.id>-NNNN.yaml`.
+- **[RECOMMENDED]** Resolve `warnings[]` (placeholders, missing metrics/non-goals) when BQA has answers; sync `userStories` if UX copy changed.
+- **[MANDATORY]** After reconcile: `flowgrid split` + `flowgrid render` — stakeholder review uses `ir/generated/spec.md`.
+- **[STRICTLY FORBIDDEN]** Skip audit and rely on manual zone review only.
+
+---
+
 ## Rule: Missing Information / Gap Handling & Workload Threshold (Law 2)
 
 - **[MANDATORY]** For `#missing_info` / open gaps: re-check ArtifactGraph → micro-scope → evaluate total gap volume:
   - **Small Scope (≤5 questions):** `AskQuestion` wizard in chat thread — **one question at a time**, **≥3 options**: (1) `(Recommended)`, (2) `Other` (free text), (3) `Log as Tech Debt (Pending)`.
   - **Large Scope (≥10 gaps):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 gaps per phase) with disk offloading at boundaries.
-- **[MANDATORY]** If member selects "Log as Tech Debt" → create `qa-inbox.md` entry. Close later with `/qa-resolve`.
+- **[MANDATORY]** If member selects "Log as Tech Debt" → create `qa/open/QA-<bundle.id>-NNNN.yaml`. Close later with `/qa-resolve`.
 - **[STRICTLY FORBIDDEN]** Never write `openQuestions` in YAML. Never silently overwrite settled SSOT without explicit confirmation.
 
 ---
 
-## Rule: UI Error Handling (3 Outcomes)
+## Rule: UI Error Handling (4-tier outcomes)
 
 - **[MANDATORY]** Every user action / API call in `design.yaml` MUST have the 6-block Action Flow and 4-tier outcomes documented:
   1. `preconditions`: UI validity, record status, RBAC permissions, disabled reason.
@@ -81,18 +94,19 @@ disable-model-invocation: true
 ## Workflow
 
 **Step A — fact-lock** (`grillStatus.bqaFacts`):
-1. Compare `design.zones/behavior/actions` vs `legacy.ui` vs common UI; cross-check affordances via `flowgrid-ux-common.mdc` when DSL tags exist but behavior is thin.
-2. Audit business focus (summary, requirements, CSS, error flows).
-3. Cross-check common patterns.
-4. Audit UI error handling flows (all 3 outcomes per action).
-5. Patch bundle → `flowgrid split`.
-6. Set `grillStatus.bqaFacts: done`.
+1. Run `flowgrid audit spec <bundle> --type <pageType>`; patch structural `gaps[]`.
+2. Compare `design.zones/behavior/actions` vs `legacy.ui` vs common UI; cross-check affordances via `flowgrid-ux-common.mdc` when DSL tags exist but behavior is thin.
+3. Audit business focus (summary, requirements, CSS, error flows).
+4. Cross-check common patterns.
+5. Audit UI error handling flows (4-tier outcomes per action).
+6. Patch bundle → re-run audit spec → `flowgrid split`.
+7. Set `grillStatus.bqaFacts: done`.
 
 **Step B — member wizard** (`grillStatus.bqaOpen`):
-7. AskQuestion for remaining gaps (batches ≤5).
-8. Apply member decisions to bundle.
-9. Set `grillStatus.bqaOpen: done`.
-10. User runs `docs_render` / `flowgrid render`.
+8. AskQuestion for remaining `confirms[]` / BQA gaps (batches ≤5).
+9. Apply member decisions to bundle → re-run `flowgrid audit spec`.
+10. Set `grillStatus.bqaOpen: done`.
+11. User runs `docs_render` / `flowgrid render`.
 
 ---
 
@@ -112,7 +126,8 @@ disable-model-invocation: true
 
 - [ ] Load policy complied (did not load codegen, legacy source code, or generated `*.md`).
 - [ ] Step A completed with `grillStatus.bqaFacts: done` before Step B.
-- [ ] Every action/API call in `design.yaml` has all 3 error outcomes (Success + CommonError + SpecificError).
+- [ ] `flowgrid audit spec` run before Step A, after patches, and before handoff to `/grill-dev`.
+- [ ] Every action/API call in `design.yaml` has 4-tier outcomes (success, business, security, system).
 - [ ] `summary` is 100% Non-tech; `spec.requirements` covers Validations, State Machine, Permissions, Edge Cases.
 - [ ] All gaps used AskQuestion wizard + member confirm (or `QA-*` pointer). No `openQuestions` in YAML.
 - [ ] `grillStatus.bqaOpen: done` after this pass.