@shanyucoder/flowgrid 0.1.5 → 0.1.9

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/<SHORT>_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" → copy from `.flowgrid/templates/qa-item.yaml` per `qa-authoring.md`; create `qa/<SHORT>_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.

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

@@ -1,43 +1,18 @@
 ---
 name: grill-common-spec
-description: EXCLUSIVE /grill-common-spec — Use this to audit and verify technical common bundles before code generation.
+description: DEPRECATED — no common YAML bundles to grill. Route to /grill-bqa on function bundles or /common for pattern MD.
 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 — DEPRECATED
 
-# /grill-common-spec — Common Bundle Audit
+There is no `common/yaml` + IR grill path on the docs hub anymore.
 
-**Target Path:** `<LCA>/common/yaml/<slug>/<slug>.bundle.yaml` (see `.cursor/extracts/common-scope.md`).
+| Gap | Route |
+|-----|--------|
+| Function screen/API spec | `/grill-bqa` · `/grill-dev` on `*.bundle.yaml` |
+| Shared rule prose | `/common` (patterns Markdown) |
+| UI affordance / pattern | `flowgrid-ux-common.mdc` + `/grill-bqa` |
+| Registry / template drift | [custom-base](../../../docs/workflows/custom-base.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.
+**If invoked:** STOP — do not load `surfaces/common/yaml`.

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

@@ -8,7 +8,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 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.
+> **[MANDATORY]** Expect `grillStatus.bqaOpen: done` before starting. Do **not** start if only `bqaFacts` is set — finish `/grill-bqa` Step B first.
 
 # /grill-dev — Dev / Codegen Grill
 
@@ -30,11 +30,12 @@ disable-model-invocation: true
 
 ## Rule: Audit Interlock with Page Type
 
-- **[MANDATORY]** Before grilling, run: `flowgrid audit spec <bundle> --type <profile>`.
+- **[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`.
-  - 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.
+  - 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.
 
 ---
 
@@ -53,7 +54,7 @@ disable-model-invocation: true
   → **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`.
+  - ✅ If member selects "Log as Tech Debt" → create `qa/<SHORT>_NNNN.yaml`; maintain `grillStatus.dev: pending`.
   - ❌ Do NOT set `grillStatus.dev: done` until profile + entity/module + endpoint actions are all verified and confirmed.
 
 ---
@@ -120,7 +121,7 @@ disable-model-invocation: true
 
 ## 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]** Scan sibling `…/api/<seq>/` (+ shared `01` on function leaf when present) for existing endpoints. If found → tag `#reuse-api` + `reuseFrom` on page action/item; skip new trio. Do not scan deprecated `common/yaml`.
 - **[MANDATORY]** All endpoint paths MUST use explicit suffixes: `/create`, `/{id}/update`, `/{id}/duplicate`, `/{id}/delete`, `/{id}/detail`.
 
 ---
@@ -155,7 +156,7 @@ disable-model-invocation: true
 
 - bộ code FE dry pass → `/prototype`
 - BQA↔Dev conflict → `/grill-docs`
-- Legacy fact gap → `/update-spec-legacy`
+- Legacy fact gap → `/legacy /spec` or `/update-spec` (legacy evidence delta)
 - Confirmed common promote → `/docs-mark` (same session or before `/prototype`)
 
 ---

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

@@ -39,6 +39,13 @@ disable-model-invocation: true
 
 ---
 
+## Rule: Audit interlock (sau reconcile)
+
+- **[MANDATORY]** After any bundle patch that touches `design.*`, `userStories`, `bundle.gen`, or `api` refs: run `flowgrid audit spec <bundle> --type <pageType>` (same profile rules as `/grill-dev`). Resolve `CONFIRM_DB_*` via `db-audit-wizard.md` before handoff.
+  - Patch structural `gaps[]`; defer remainder via `qa/` per Law 2.
+  - Address `warnings[]` when reconcile changes business prose (`summary`, `successMetrics`, `nonGoals`, `userStories`).
+  - ❌ Do not hand off FE until audit has been re-run post-reconcile.
+
 ## Rule: Codegen Gate
 
 - **[MANDATORY]** `bundle.gen.codegen.profile` (+ entity/module when required) MUST be set.
@@ -55,8 +62,8 @@ disable-model-invocation: true
 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.
+5. Write/fix `bundle.gen` → `flowgrid audit spec` → `flowgrid_docs_bundle_split` → `docs_render`.
+6. Handoff ID/path + recommendation to bộ code FE (`gen:dry` on FE repo).
 
 ---
 
@@ -74,6 +81,6 @@ disable-model-invocation: true
 
 ## Verification Checklist
 
-- [ ] Conflicts reconciled in `*.bundle.yaml`, or deferred with `qa/open/QA-…`. No `openQuestions`.
+- [ ] Conflicts reconciled in `*.bundle.yaml`, or deferred with `qa/<SHORT>_…`. No `openQuestions`.
 - [ ] `bundle.gen.codegen.profile` present and correct.
-- [ ] `flowgrid split` succeeded with zero errors.
+- [ ] `flowgrid audit spec` re-run after reconcile; `flowgrid split` succeeded with zero errors.

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

@@ -11,9 +11,11 @@ extractBundle: architecture-core
 
 # /module — Business Module (CMP-*)
 
+**Template:** `.cursor/extracts/tpl-module.md` (includes **Out of scope** + **Depends on**).
+
 **Target Paths:**
 - Module folder: `surfaces/[Surface]/[CMP-ID]/`
-- Main doc: `surfaces/[Surface]/[CMP-ID]/[CMP-ID].md`
+- Main doc: `surfaces/[Surface]/[CMP-ID]/README.md` or `[CMP-ID].md` (team convention — MD only)
 
 ---
 

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

@@ -23,9 +23,10 @@ One generator: **OpenAPI 3.0.3** from `01-backend-spec.yaml`. Merge/UI stays `op
   # Or from docs hub root (all 01-backend-spec.yaml under surfaces):
   flowgrid openapi_gen
   # Validate only:
-  flowgrid check --spec …/01-backend-spec.yaml
+  flowgrid api:check --spec …/01-backend-spec.yaml
   ```
 - **[MANDATORY]** After generation: run `flowgrid openapi_render` to merge fragments into `docs/openapi/api.yaml`.
+- **[MANDATORY]** After contract change: run `flowgrid render` on docs hub so leaf `ir/generated/api.md` matches `01` for BA/Dev review (see `tpl-api-contract.md`).
 
 ---
 

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

@@ -10,10 +10,16 @@ extractBundle: architecture-core
 
 # /overview — Operational Areas Overview
 
-**Target Paths:** `overview/operational-areas/[Admin operations | Workforce operations | …]`
+**Target Paths:** `overview/index.md`, `overview/operational-areas/<slug>.md` (copy from hub template `operational-areas/_template.md` on greenfield init).
 
 ---
 
+## Rule: arc42 §1 content
+
+- **[MANDATORY]** `overview/index.md`: goals, stakeholders table, top 5 quality goals, persona summaries, product-level in/out scope, success metrics, link to operational areas.
+- **[MANDATORY]** Each operational area file: personas, in/out scope, area metrics, `CMP-*` links, non-goals — per `_template.md`.
+- **[RECOMMENDED]** Trước spec leaf lớn: overview + area đã có persona id mà `userStories.primary.asA` tham chiếu.
+
 ## Rule: Content Boundary
 
 - **[MANDATORY]** Overview MUST be a pure business document written in user domain language: personas, operational areas, high-level system purpose.