@shanyucoder/flowgrid 0.1.0

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

@@ -0,0 +1,46 @@
+---
+name: grill
+description: /grill — General discovery/gap-fill grill before authoring any skill. Routes to the correct specialized grill.
+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
+
+**Mindset:** Discovery and resolution of ambiguity — not authoring. Route to the correct specialized grill.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## 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.

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

@@ -0,0 +1,26 @@
+---
+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.
+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
+
+---
+
+## Rule: Routing
+
+- **[MANDATORY]** Check `feature.source.kind` in `…/api/<seq>/01-backend-spec.yaml` to determine routing:
+
+  | Context | Route to |
+  |---|---|
+  | `feature.source.base` is Portal | `/grill-api-spec` |
+  | `feature.source.base: none` / webhook / partner | `/grill-integration-spec` |
+
+- **[MANDATORY]** If `01-backend-spec.yaml` does not exist yet → run `/api-spec` or `/api-integration` 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

@@ -0,0 +1,57 @@
+---
+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.
+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`.
+
+# /grill-api-spec — API Contract Audit (Portal FE)
+
+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`
+
+---
+
+## Rule: Scope
+
+- **[MANDATORY]** Audit `…/api/<seq>/01-backend-spec.yaml`; never a `01` directly on the function slug leaf itself.
+- **[STRICTLY FORBIDDEN]** No BQA 3-Pillars reports. No framework code snippets. No writing `ir/*`.
+
+---
+
+## Rule: Audit Steps
+
+- **[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.
+
+---
+
+## Rule: Missing Information
+
+- **[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.
+
+---
+
+## 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.

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

@@ -0,0 +1,119 @@
+---
+name: grill-bqa
+extractBundle: bqa-grill
+description: EXCLUSIVE /grill-bqa — ONLY for BA/BQA UI acceptance criteria. Gaps use AskQuestion in-session; do not persist openQuestions in YAML. DO NOT trigger for dev codegen tags.
+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` + `ir/spec.yaml`. If `ir/` is missing, read entire `*.bundle.yaml`.
+
+# /grill-bqa — Spec Validation (BQA / UI)
+
+**Mindset:** Spec Validation + Decision Resolution — **not** domain archaeology. Do NOT author `design.zones[].items[]` or `spec.ui.list|form` from scratch; `/spec` already populated inventory when info existed.
+
+**Extracts:** `extractBundle: bqa-grill` → `.cursor/extracts/grill/validation.md`
+
+---
+
+## Rule: Load Policy
+
+| 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` |
+
+---
+
+## 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`.
+- **[STRICTLY FORBIDDEN]** Never write `openQuestions` in YAML. Never silently overwrite settled SSOT without explicit confirmation.
+
+---
+
+## Rule: UI Error Handling (3 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.
+  2. `interactionControl`: `preventDoubleSubmit: true`, loading text, confirm dialog.
+  3. `payloadTransformation`: Trimming, sanitation, type casting.
+  4. `executionContract`: Idempotency key, timeout, optimistic locking.
+  5. `outcomes`:
+     - **`onSuccess` (200/201):** Action feedback, state transition, toast/modal, navigation, background trigger.
+     - **`onBusinessErrors` (422/409):** Inline field error placement (`errors: {field: [msg]}`) and duplicate warnings.
+     - **`onSecurityErrors` (401/403):** Session expiry and IDOR safety redirect.
+     - **`onSystemErrors` (500/504/Offline):** Gateway timeout lock, offline data preservation banner.
+- **[STRICTLY FORBIDDEN]** Do NOT skip documenting error outcomes or concurrency protection, even for "simple" forms.
+
+---
+
+## Rule: Business & Stakeholder Audit (Step A)
+
+- **[MANDATORY]** Audit these 6 dimensions before proceeding:
+  1. `summary` tells business story in 100% Non-tech language (Arc42 style: goals, user scenarios).
+  2. `validation` depth: Reject specs that only declare `required: true` without prototype format, boundary limits, or explicit localized error copy.
+  3. `stateMatrix`: Declares UI editability and button visibility across record lifecycles and user roles.
+  4. `actions`: All mutations declare preconditions, double-submit protection, payload transformation, and 4-tier outcomes.
+  5. `custom UI blocks`: If a section does NOT map to a standard base component / Shadcn primitive, verify it has explicit dimension boundaries, color tokens, typography metrics, and micro-interaction states. Reject vague custom UI placeholders.
+  6. CSS properties (font-size, exact colors) are NOT in feature spec unless they are explicit Design System overrides.
+- **[MANDATORY]** Cross-check common patterns: walk up from function → nearest `common/patterns/` → module → surface → `surfaces/common/patterns/` (per `common-scope.md`).
+- **[MANDATORY]** Set `grillStatus.bqaFacts: done` after Step A completes.
+- **[STRICTLY FORBIDDEN]** Do NOT run Step B wizard before `grillStatus.bqaFacts: done`.
+
+---
+
+## Rule: Proactive Member Wizard (Step B)
+
+- **[MANDATORY]** AskQuestion wizard for remaining gaps — one question at a time, ≥3 options per question.
+- **[PROACTIVE BRAINSTORMING INTERLOCK]**: When member inputs are brief or missing boundary rules, the Agent MUST NOT ask open-ended questions like "How should this be validated?". Instead, synthesize realistic candidate validations (e.g. `(Recommended): phone_vn with 10 digits and duplicate DB check`) as selectable options.
+- **[MANDATORY]** UI affordance gaps (not validation): apply `flowgrid-ux-common.mdc` + `.cursor/extracts/ux-common-patterns.md`; `(Recommended)` = top checklist-based proposal — same as `/spec` zone pipeline.
+- **[MANDATORY]** After member picks named option or writes "Other with text" → apply to `design` / `spec.ui` / `userStories` / `acceptanceCriteria` — **not** `bundle.review` alone.
+- **[MANDATORY]** `bundle.review` is a BA scratchpad during grill; it does **not** split to `ir/*`. Any settled behavior, copy, or AC must land in `userStories`, `acceptanceCriteria`, `design.*`, or `spec.ui` before split.
+- **[MANDATORY]** Set `grillStatus.bqaOpen: done` when all answers or QA pointer files are on disk. Leftover `#missing_info` with `QA-…` id is allowed (does not block).
+
+---
+
+## 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`.
+
+**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`.
+
+---
+
+## Out of Scope
+
+- **[STRICTLY FORBIDDEN]** `codegen`, `gen`, `ui.filters/columns`, `portal:gen`, implement UI.
+
+---
+
+## Handoff
+
+→ `/grill-dev`
+
+---
+
+## Verification Checklist
+
+- [ ] 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).
+- [ ] `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.
+- [ ] Bundle split + docs render executed with zero errors.

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

@@ -0,0 +1,43 @@
+---
+name: grill-common-spec
+description: EXCLUSIVE /grill-common-spec — Use this to audit and verify technical common bundles before code generation.
+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-common-spec — Common Bundle Audit
+
+**Target Path:** `<LCA>/common/yaml/<slug>/<slug>.bundle.yaml` (see `.cursor/extracts/common-scope.md`).
+
+---
+
+## Rule: Audit Checks
+
+- **[MANDATORY]** Verify `schema` is set (e.g. `portal-feature-bundle/v1` or appropriate surface schema).
+- **[MANDATORY]** Verify `design.shell.tag` reflects the target platform:
+  - Web Portal → `#shell: DataListPage`
+  - WinForms → `#shell: KioskCheckIn`
+  - Gateway → `#shell: OtAdapter`
+- **[MANDATORY]** Verify `spec.principles` and `spec.acceptance` are detailed enough to drive test cases and codegen.
+- **[MANDATORY]** Verify `design.patterns` and referenced middlewares point to valid, existing items.
+- **[STRICTLY FORBIDDEN]** Do NOT "fix" a module-common bundle by copying it to surface `common/`.
+
+---
+
+## Rule: Output
+
+- **[STRICTLY FORBIDDEN]** Do NOT output new files from this skill.
+- **[MANDATORY]** If issues are found → inform user + suggest fixes, or fix directly in `.bundle.yaml` if instructed.
+- **[MANDATORY]** If bundle passes → instruct user: run `flowgrid split -- <path>` (must emit `ir/design.yaml`), then bộ code FE `/gen-common`.
+- **[STRICTLY FORBIDDEN]** Do NOT send BE `/api` a common FE bundle.
+
+---
+
+## Verification Checklist
+
+- [ ] `schema` field set correctly.
+- [ ] `design.shell.tag` aligned with target surface type.
+- [ ] `spec.principles` and `spec.acceptance` are substantive.
+- [ ] All `design.patterns` / middleware references are valid and exist.

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

@@ -0,0 +1,172 @@
+---
+name: grill-dev
+extractBundle: dev-grill
+description: EXCLUSIVE /grill-dev — ONLY for engineering codegen tags and bundle.gen. DO NOT trigger for BQA, BA, or UI design grills.
+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`. NEVER filter partial keys.
+> **[MANDATORY]** Expect `grillStatus.bqaOpen: done` (or `bqaFacts`) before starting.
+
+# /grill-dev — Dev / Codegen Grill
+
+**Scope:** Author `bundle.gen` + `api/<seq>/01-backend-spec.yaml` only. No prose, no BQA reports, no framework code snippets.
+
+**Doc hub:** `platform/toolchain/PORTAL-CODEGEN.md`
+**Extracts:** `extractBundle: dev-grill` → `codegen/readiness.md`, `platform-mark-detect.md`
+
+---
+
+## Rule: Load Policy
+
+| Read (whole file) | Write | NEVER Read |
+|---|---|---|
+| **`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` | |
+
+---
+
+## Rule: Audit Interlock with Page Type
+
+- **[MANDATORY]** Before grilling, run: `flowgrid audit spec <bundle> --type <profile>`.
+  - `<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`.
+  - Script output `gaps[]` + `confirms[]` (includes `UX_*` / `CONFIRM_UX_*` affordance — see `flowgrid-ux-common.mdc`).
+  - Agent patches structural `gaps[]`; UX confirms → wizard with `(Recommended)` from audit output.
+
+---
+
+## Rule: Zone-Based Grill (chống Lost-in-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.
+
+## Rule: Missing Information / Hard Gate & Workload Threshold (Law 2)
+
+- **[MANDATORY]** If `gen.codegen.profile` is missing, OR `entity`/`module` is empty for list/create/admin-crud/auth/change-password, OR sibling `01` endpoints lack `action` + path suffix:
+  → **Proactively brainstorm** logical suggestions from business context in Vietnamese (e.g. login page → suggest `module: auth, entity: user`).
+  - **Small Scope (≤5 questions):** Trigger `AskQuestion` wizard — **one question at a time**, ≥3 options: (1) `(Recommended)`, (2) `Other` (free text), (3) `Log as Tech Debt (Pending)`. Wait for member answer before showing next question.
+  - **Large Scope (≥10 gaps/endpoints):** **[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 endpoints/gaps per phase) with disk offloading at boundaries.
+  - ✅ If member selects "Log as Tech Debt" → create `qa/open/QA-<bundle.id>-NNNN.yaml`; maintain `grillStatus.dev: pending`.
+  - ❌ Do NOT set `grillStatus.dev: done` until profile + entity/module + endpoint actions are all verified and confirmed.
+
+---
+
+## Rule: Codegen Profile Mapping
+
+- **[MANDATORY]** Use correct profile per page type:
+
+| profile | Pages | Next.js output |
+|---|---|---|
+| `auth` | login, forgot, reset | `src/app/(auth)/…` — no admin chrome |
+| `change-password` | change password (logged-in) | `src/app/(dashboard)/…` |
+| `public` | marketing / other public | `src/app/(public)/…` |
+| `not-found` | 404 | `src/app/not-found.tsx` |
+| `error` | 503 / error | `src/app/error.tsx` |
+| `list` / `create` / `admin-crud` | admin CRUD | `src/app/(dashboard)/…` |
+
+- **[STRICTLY FORBIDDEN]** Never use `create` for auth pages. `auth` covers login/forgot/reset.
+
+---
+
+## Rule: bundle.gen Required Fields
+
+- **[MANDATORY]** `bundle.gen` MUST contain:
+  ```yaml
+  gen:
+    codegen:
+      profile: "auth"   # or list | create | admin-crud | public | not-found | error | change-password
+      entity: ""
+      module: ""
+    tags:
+      - "#gen:test-schema"
+      - "#gen:test-service"
+    ui:
+      filters: []
+      columns: []
+      composition: null
+      testIds: null
+  ```
+- **[MANDATORY]** Tags by profile: `list` → `#gen:test-schema` + `#gen:test-service`; `create` → `#gen:test-validation`.
+
+---
+
+## Rule: UI Component & Registry
+
+- **[MANDATORY]** Before tagging `#needs-component`, match widget against `design.registry` and existing `#ui:` tags.
+  - Shadcn primitive → `#ui: <Primitive>` (FE installs via `shadcn add`).
+  - Unknown widget → `#needs-ui:` or prompt member. Never invent an arbitrary shadcn component name.
+  - ≥2 **domain** structural blocks → `#needs-component: MoBlockName`.
+  - **[STRICTLY FORBIDDEN]** Do NOT tag shadcn primitives (`Dialog`, `Button`, `Table`) as `#needs-component`.
+- **[MANDATORY]** Pages with ≥3 levels of nested UI (Page → Tab → Card → Sub-table) → suggest `#use-store` (Pinia/Zustand).
+- **[MANDATORY]** Forms MUST be extracted as independent SPA components. `ui.form` must be properly defined; do NOT merge form layout into page shell.
+
+---
+
+## Rule: Hashtag & Error Verification
+
+- **[MANDATORY]** Verify and apply these tags from `ir/design.yaml` evidence:
+  - Domain: `#call-external`, `#cross-service`, `#cross-entity-service`, `#derived-data`, `#tech-debt:*`
+  - Errors: `#err:validation`, `#err:idor-violation`, `#err:not-found`, `#err:permission-denied`
+  - Code-size: `#split-hook:columns` (>8 cols), `#split-hook:filters` (>3 filters), `#split-hook:export`, `#split-hook:form-sections` (>6 fields)
+
+---
+
+## Rule: API Reuse & Explicit Suffix
+
+- **[MANDATORY]** Scan `common/yaml/` (LCA) + sibling `…/api/<seq>/` for existing `01` files. If found → tag `#reuse-api` + `reuseFrom` on page action/item; skip new trio.
+- **[MANDATORY]** All endpoint paths MUST use explicit suffixes: `/create`, `/{id}/update`, `/{id}/duplicate`, `/{id}/delete`, `/{id}/detail`.
+
+---
+
+## Rule: Common Candidates Review
+
+- **[MANDATORY]** After scanning columns/toolbar/filters/composables, present a **Common Candidates** summary table (in Vietnamese) to member. Provide selectable options (A/B/C). Record confirmed common promotions via `artifactgraph_remember` (when available).
+- `render: custom` → `#needs-component: cell-{key}:MoXxx` or matching Mo* in design registry.
+- Repeating logic (export, auth) → ask for `#common:` / `#needs-common:`.
+
+---
+
+## Rule: Done Gate
+
+- **[MANDATORY]** Set `grillStatus.dev: done` ONLY when ALL are satisfied:
+  1. `gen.codegen.profile` is set (double-quoted string).
+  2. `entity` + `module` are non-empty (for list/create/admin-crud/auth/change-password/public).
+  3. Sibling `01` endpoint `action` + path suffix are explicitly set.
+- **[MANDATORY]** When bundle actions carry `executionContract.apiRef`, run `flowgrid audit fe-be <bundle.yaml> [--backend-spec …/01-backend-spec.yaml]` after `/api-update`; fix `FEBE_*` before `grillStatus.dev: done`.
+- **[MANDATORY]** Run `flowgrid_docs_bundle_split` after editing bundle; user runs `docs_render`.
+- **[MANDATORY]** If ArtifactGraph is available: call `artifactgraph_allowlist_check(commandKey=genDry)` then `artifactgraph_recommend_command`. Do NOT execute code generation in docs hub.
+
+---
+
+## Out of Scope
+
+- **[STRICTLY FORBIDDEN]** No BQA 3-Pillars reports, no framework code (FastAPI, Pydantic, Axios, i18n), no UX prose, no full E2E, no `portal:gen` execution.
+
+---
+
+## Handoff
+
+- bộ code FE dry pass → `/prototype`
+- BQA↔Dev conflict → `/grill-docs`
+- Legacy fact gap → `/update-spec-legacy`
+- Confirmed common promote → `/docs-mark` (same session or before `/prototype`)
+
+---
+
+## Verification Checklist
+
+- [ ] `grillStatus.bqaOpen: done` confirmed before starting.
+- [ ] `bundle.gen.codegen.profile` set with correct profile per page type.
+- [ ] `gen.ui`: `filters`, `columns`, `composition`, `testIds` all present (empty arrays OK).
+- [ ] Profile-specific gen tags applied (`#gen:test-schema`, `#gen:test-service`, `#gen:test-validation`).
+- [ ] `#err:*` tags applied for each endpoint's nature (IDOR on `{id}`, validation on POST/PUT).
+- [ ] UI components: `#ui:` for primitives, `#needs-component:` for domain Mo* blocks only.
+- [ ] `grillStatus.dev: done` set only with profile + entity/module + endpoint actions confirmed.
+- [ ] Bundle split run with zero errors; no `bundle.spec.api` authored.

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

@@ -0,0 +1,79 @@
+---
+name: grill-docs
+extractBundle: grill-docs
+description: EXCLUSIVE /grill-docs — ONLY for reconciling BQA vs Dev conflicts. DO NOT trigger for standalone /grill-dev or /grill-bqa.
+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` + `ir/spec.yaml`. Never cherry-pick keys from `*.bundle.yaml`.
+
+# /grill-docs — Reconcile BQA ↔ Dev Conflicts + Codegen Gate
+
+**Purpose:** Merge and reconcile contradictions between BQA business requirements and Dev technical specifications. Do NOT author page inventory from scratch.
+
+| Skill | Owns |
+|---|---|
+| `/grill-bqa` | UI layout, copy, acceptance criteria — NO API/DB debates |
+| `/grill-dev` | DB tables, API routes, codegen tags — NO BQA business rules |
+| `/grill-docs` | Reconciles contradictions between BOTH above |
+
+---
+
+## Rule: Load Policy
+
+| Read (whole file) | Write | NEVER Read |
+|---|---|---|
+| **`ir/design.yaml`** | Patch `*.bundle.yaml` → `pnpm spec:split` | Generated `*.md` |
+| **`ir/spec.yaml`** (prose vs tech conflicts) | | |
+
+---
+
+## Rule: Missing Information / Conflict Resolution
+
+- **[MANDATORY]** Conflicts → `AskQuestion` wizard — one question at a time, **≥3 options**: (1) Recommended, (2) Other, (3) "Log as Tech Debt".
+  - ✅ Member picks → author the spec. "Log as Tech Debt" → create QA file + pointer.
+  - ❌ No `openQuestions` left on the bundle.
+- **[MANDATORY]** Deferred gaps from `qa-inbox.md` → resolve using `/qa-resolve`, NOT this skill.
+
+---
+
+## Rule: Codegen Gate
+
+- **[MANDATORY]** `bundle.gen.codegen.profile` (+ entity/module when required) MUST be set.
+  - Login/forgot/reset → `auth` (NOT `create`).
+  - ❌ If missing or wrong → do NOT set `grillStatus.full: done`. Report and hand back to `/grill-dev`.
+- **[MANDATORY]** After bundle is reconciled: `flowgrid_docs_bundle_split` → `docs_render`.
+- **[RECOMMENDED]** If ArtifactGraph is available: use `artifactgraph_allowlist_check` + `artifactgraph_recommend_command` for `genDry`; never execute FE generation here.
+
+---
+
+## Workflow
+
+1. Resolve spec ↔ legacyEvidence ↔ design conflicts in bundle via AskQuestion wizard.
+2. Reconcile common patterns (BQA flows ↔ Dev `#pattern`, `#split-hook:` tags).
+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_docs_bundle_split` → `docs_render`.
+6. Handoff ID/path + recommendation to bộ code FE.
+
+---
+
+## Out of Scope
+
+- **[STRICTLY FORBIDDEN]** No legacy source archaeology. No UI/API implementation. No `ir/*` direct writes.
+
+---
+
+## Handoff
+
+→ `/prototype` after bộ code FE dry-run passes.
+
+---
+
+## Verification Checklist
+
+- [ ] Conflicts reconciled in `*.bundle.yaml`, or deferred with `qa/open/QA-…`. No `openQuestions`.
+- [ ] `bundle.gen.codegen.profile` present and correct.
+- [ ] `flowgrid split` succeeded with zero errors.

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

@@ -0,0 +1,51 @@
+---
+name: grill-integration-spec
+description: EXCLUSIVE /grill-integration-spec — ONLY for auditing backend integration contracts under surfaces/integrations/. 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.
+
+# /grill-integration-spec — Integration Contract Audit
+
+After `/api-integration`. Before bộ code BE `/api`. No code on docs hub.
+
+Shared extracts: `api-integration-spec.md`, `api-codegen-readiness.md`, `api-codegen-tags.md`, `call-external.md`, `entity-relationship.md`, `agent-discipline.md`, `verify-gate.md`
+
+---
+
+## Rule: Goal & Scope
+
+- **[MANDATORY]** Contract must be sufficient to implement webhook and partner APIs.
+- **[MANDATORY]** OpenAPI `securitySchemes` and mock definitions must match `01-backend-spec.yaml`.
+- **[MANDATORY]** Codegen-ready: `flowgrid check` + `flowgrid openapi_gen` / `openapi:render` must pass.
+- **[STRICTLY FORBIDDEN]** Do NOT use `ir/design.yaml` as BE input (integrations usually have no FE IR).
+- **[STRICTLY FORBIDDEN]** No BQA reports, no framework code snippets, no writing `ir/*`.
+
+---
+
+## Rule: Workflow Steps
+
+- **[MANDATORY]** Step 1: Resolve `surfaces/integrations/<provider>/<slug>/api/<seq>/01-backend-spec.yaml`. Never a `01` directly on the slug leaf.
+- **[MANDATORY]** Step 2: Audit authentication, `securitySchemes`, idempotency keys, retry policies, and non-CRUD actions.
+- **[MANDATORY]** Step 3: Enrich `01` with codegen tags (`#gen:*`, `#manual-service`, `#call-external`), `codegen.profile|entity|module`, and `endpoints[].action`.
+- **[MANDATORY]** Step 4: Run gates:
+  - `flowgrid check --spec surfaces/integrations/<provider>/<slug>/api/<seq>/01-backend-spec.yaml`
+  - `flowgrid openapi_gen --spec …/01-backend-spec.yaml`
+  - `flowgrid openapi_render`
+- **[MANDATORY]** Step 5: Set `approval.status: reviewed` (or `approved`) in YAML.
+
+---
+
+## Verification Checklist
+
+- [ ] Target: `01-backend-spec.yaml` under `…/integrations/…/api/<seq>/`.
+- [ ] Auth + idempotency keys + retry policy verified and populated.
+- [ ] Gates executed: `api:check` + `openapi:gen` + `openapi:render` exit 0.
+- [ ] `approval.status` set to `reviewed` or `approved`.
+- [ ] No `openQuestions` in YAML; no `.md` written directly.
+
+## Handoff
+
+- `approval.status: approved` → bộ code `--type=be` `/api` with `--spec …/01-backend-spec.yaml`

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

@@ -0,0 +1,58 @@
+---
+name: module
+description: EXCLUSIVE /module — Handles business modules (CMP-*). DO NOT output fake Markdown reports.
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+> **[MANDATORY]** Path SSOT: `surfaces/<surface>/CMP-*/` — NO `modules/` segment.
+
+# /module — Business Module (CMP-*)
+
+**Target Paths:**
+- Module folder: `surfaces/[Surface]/[CMP-ID]/`
+- Main doc: `surfaces/[Surface]/[CMP-ID]/[CMP-ID].md`
+
+---
+
+## Rule: ID Resolution
+
+- **[MANDATORY]** When a CMP ID or module name is provided → use `flowgrid_docs_route` or glob to resolve to `surfaces/[Surface]/[CMP-ID]/`. Do NOT demand the full path from the user.
+- **[MANDATORY]** Sub-folder IDs (function/sub-module) MUST use pure numeric hierarchical segments (e.g. `01/01/02/`). NO textual slugs in sub-folder path segments.
+- VitePress/publish menu uses **Document Code** (e.g. `SPEC-PORTAL-AUTH-00`) as menu text, not the H1 heading.
+
+---
+
+## Rule: Common Scope for `/module … common`
+
+- **[MANDATORY]** When called with `common` modifier:
+  - Default: `surfaces/[Surface]/[CMP-ID]/common/` (`patterns/`, `yaml/`, `processes/`).
+  - If user names a cluster (e.g. `02`, draft `2-*`) → `…/[CMP-ID]/02/common/` (or deeper if sub-prefix specified).
+  - **[STRICTLY FORBIDDEN]** Do NOT create `surfaces/[Surface]/common` from `/module` — that scope requires `/surfaces`.
+
+---
+
+## Rule: Common Scope by Breadth
+
+- Module-wide share only → `CMP-*/common/`.
+- Cluster-only share → `CMP-*/NN/common/`.
+- Do NOT create a wider common scope than necessary.
+- Refer to `.cursor/extracts/common-scope.md` for LCA resolution.
+
+---
+
+## Modifier: `/legacy`
+
+- **[MANDATORY]** If `adoption-inventory.md` is missing at workspace root → STOP: *"Run `/docs-hub /adopt` first."*
+- **[MANDATORY]** If file exists: look up CMP ID → get legacy file path → write `surfaces/[Surface]/[CMP-ID]/legacy-module.md`.
+- **[STRICTLY FORBIDDEN]** Do NOT read `adoption-inventory.md` for Greenfield commands.
+
+---
+
+## Verification Checklist
+
+- [ ] CMP ID resolved to `surfaces/[Surface]/[CMP-ID]/`.
+- [ ] Main module doc `[CMP-ID].md` created or updated.
+- [ ] No textual slugs in numeric sub-folder paths.