@shanyucoder/flowgrid 0.1.5 → 0.1.9

package/engines/testcase/runners/lib/write-files.mjs

@@ -1,13 +1,20 @@
 import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
+import {
+  DEFAULT_E2E_ROOT_REL,
+  E2E_ROOT_DIR_PARTS,
+  API_E2E_ROOT_DIR_PARTS,
+} from '../../../shared/flowgrid-e2e-root.mjs'
 
-export const E2E_OUTPUT_ROOT = path.join('tests', 'e2e')
+export const E2E_OUTPUT_ROOT = path.join(...E2E_ROOT_DIR_PARTS)
+export const API_E2E_OUTPUT_ROOT = path.join(...API_E2E_ROOT_DIR_PARTS)
+export { DEFAULT_E2E_ROOT_REL }
 
 /**
  * Preflight every output path before any write or dry-run result is produced.
  *
  * A target is accepted only when, lexically (without following symlinks), it
- * resolves strictly beneath `<root>/tests/e2e`. Rejected: absolute paths,
+ * resolves strictly beneath `<root>/tests/e2e` or `<root>/tests/api-e2e`. Rejected: absolute paths,
  * `..` traversal, targets outside `tests/e2e` (including sibling prefixes
  * such as `tests/e2e-evil`), existing symlink ancestors that could redirect
  * the write, and existing targets that are not regular files.
@@ -17,9 +24,28 @@ export const E2E_OUTPUT_ROOT = path.join('tests', 'e2e')
  * @param {string} root project root
  * @param {{ relativePath: string }[]} outputs
  */
-export async function preflightOutputPaths(root, outputs) {
+function allowedAbsRoots(resolvedRoot, allowedRelRoots) {
+  const rels =
+    allowedRelRoots?.length
+      ? allowedRelRoots
+      : [E2E_OUTPUT_ROOT, API_E2E_OUTPUT_ROOT]
+  return rels.map((rel) => path.join(resolvedRoot, rel.replace(/\//g, path.sep)))
+}
+
+function isUnderCodegenTree(resolvedRoot, absolutePath, allowedRelRoots) {
+  return allowedAbsRoots(resolvedRoot, allowedRelRoots).some(
+    (base) => absolutePath === base || absolutePath.startsWith(base + path.sep),
+  )
+}
+
+/**
+ * @param {string} root
+ * @param {{ relativePath: string }[]} outputs
+ * @param {{ allowedRelRoots?: string[] }} [opts]
+ */
+export async function preflightOutputPaths(root, outputs, opts = {}) {
   const resolvedRoot = path.resolve(root)
-  const e2eRoot = path.join(resolvedRoot, E2E_OUTPUT_ROOT)
+  const allowedLabel = (opts.allowedRelRoots ?? [E2E_OUTPUT_ROOT, API_E2E_OUTPUT_ROOT]).join(', ')
   const errors = []
 
   for (const { relativePath } of outputs) {
@@ -31,22 +57,22 @@ export async function preflightOutputPaths(root, outputs) {
     }
     if (path.isAbsolute(relativePath)) {
       errors.push(
-        `output ${label}: absolute paths are not allowed — use a path relative to the project root, under ${E2E_OUTPUT_ROOT}/`,
+        `output ${label}: absolute paths are not allowed — use a path relative to the project root, under: ${allowedLabel}`,
       )
       continue
     }
 
     if (relativePath.split(/[\\/]+/).includes('..')) {
       errors.push(
-        `output ${label}: ".." traversal is not allowed — outputs must stay under ${E2E_OUTPUT_ROOT}/`,
+        `output ${label}: ".." traversal is not allowed — outputs must stay under: ${allowedLabel}`,
       )
       continue
     }
 
     const absolutePath = path.resolve(resolvedRoot, relativePath)
-    if (!absolutePath.startsWith(e2eRoot + path.sep)) {
+    if (!isUnderCodegenTree(resolvedRoot, absolutePath, opts.allowedRelRoots)) {
       errors.push(
-        `output ${label}: resolves outside ${E2E_OUTPUT_ROOT}/ — generated files must live beneath <projectRoot>/${E2E_OUTPUT_ROOT}` +
+        `output ${label}: resolves outside allowed codegen trees (${allowedLabel})` +
           ' (check module/testcase ids used to build output paths)',
       )
       continue
@@ -108,7 +134,9 @@ async function findUnsafePathComponent(resolvedRoot, absolutePath) {
  * @param {{ dryRun?: boolean, force?: boolean }} options
  */
 export async function writeOutputs(root, outputs, options = {}) {
-  await preflightOutputPaths(root, outputs)
+  await preflightOutputPaths(root, outputs, {
+    allowedRelRoots: options.allowedRelRoots,
+  })
 
   const written = []
   const skipped = []

package/harness/agents/antigravity/rules/antigravity-mcp.mdc

@@ -0,0 +1,12 @@
+---
+description: Google Antigravity IDE — FlowGrid MCP (mcp_config.json under .antigravity)
+alwaysApply: false
+---
+# Antigravity IDE + FlowGrid
+
+- Workspace harness: **`.antigravity/`** (Antigravity IDE hardcodes this path; it does **not** fall back to `.agents/`).
+- MCP config: **`.antigravity/mcp_config.json`** (not `mcp.json`).
+- Server name: `flowgrid` → `bin/flowgrid-mcp.mjs` from the FlowGrid package used at `flowgrid init`.
+- Skills: **`.antigravity/skills/<name>/SKILL.md`**; rules: **`.antigravity/rules/`.
+- Re-sync: `flowgrid harness sync --agent=antigravity`.
+- **Gemini CLI / VS Code** use **`.agents/`** — select **Gemini (CLI / extension)** in init (`--agent=gemini`).

package/harness/agents/gemini/rules/gemini-mcp.mdc

@@ -0,0 +1,11 @@
+---
+description: Gemini CLI / extension — FlowGrid MCP (mcp.json under .agents)
+alwaysApply: false
+---
+# Gemini + FlowGrid
+
+- Workspace harness: **`.agents/`** (open Agent Skills standard; Gemini CLI, VS Code Gemini extension, tools compatible with `.agents` / `.agent`).
+- MCP config: **`.agents/mcp.json`** (server `flowgrid` → `bin/flowgrid-mcp.mjs` from the FlowGrid package used at `flowgrid init`).
+- Skills: **`.agents/skills/<name>/SKILL.md`**; rules: **`.agents/rules/`.
+- Re-sync: `flowgrid harness sync --agent=gemini`.
+- **Antigravity IDE** uses a separate folder — select **Google Antigravity IDE** in init (`--agent=antigravity` → `.antigravity/`), not this profile.

package/harness/agents/gemini_antigravity/rules/antigravity-mcp.mdc

@@ -1,10 +1,12 @@
 ---
-description: Antigravity — FlowGrid MCP wiring (mcp_config.json)
+description: DEPRECATED — use gemini or antigravity agent profiles
 alwaysApply: false
 ---
-# Antigravity + FlowGrid
+# Deprecated combined profile
 
-- MCP config file: `.agents/mcp_config.json` (not `mcp.json`).
-- Server name: `flowgrid` → `bin/flowgrid-mcp.mjs` from the FlowGrid package used at `flowgrid init`.
-- Skills live under `.agents/skills/`; rules under `.agents/rules/`.
-- Re-sync after config changes: `flowgrid harness sync --agent=gemini_antigravity`.
+`gemini_antigravity` was split:
+
+- **Gemini CLI / VS Code** → `flowgrid harness sync --agent=gemini` → `.agents/`
+- **Antigravity IDE** → `flowgrid harness sync --agent=antigravity` → `.antigravity/`
+
+Update `.flowgrid/config.json` `agents` and re-run init or harness sync.

package/harness/be/skills/{grill-api → audit-api}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: grill-api
-description: /grill-api — audit generated FastAPI/Laravel/Nest API before integration.
+name: audit-api
+description: /audit-api — audit generated BE routes/code against 01-backend-spec.yaml before wire.
 disable-model-invocation: true
 ---
 
-# /grill-api
+# /audit-api — BE implementation vs contract
 
 Run after `npm run codegen:api:dry` / `flowgrid api-gen:dry` and after implementation.
 
@@ -13,7 +13,7 @@ Run after `npm run codegen:api:dry` / `flowgrid api-gen:dry` and after implement
 ## Target / ID Resolution Rule
 
 - User prompt MAY specify a function ID, API slug, or short name (e.g. `API-AUTH-001`, `login`, `CMP-ADM-009`).
-- Agent MUST resolve **`…/api/<seq>/01-backend-spec.yaml`** via `FLOWGRID_DOCS_ROOT` or `flowgrid_docs_route` (screen leaf `CMP-*/<NN…>/api/<seq>/`, or `common/yaml/<slug>/`, or `integrations/…/api/<seq>/`).
+- Agent MUST resolve **`…/api/<seq>/01-backend-spec.yaml`** via `FLOWGRID_DOCS_ROOT` or `flowgrid_docs_route` (screen leaf `CMP-*/<NN…>/api/<seq>/`, or `common/yaml/<slug>/`, or external-channel surface `…/api/<seq>/`).
 - **Read the entire `01-backend-spec.yaml`**. Do **not** use `ir/design.yaml` or `ir/spec.yaml` as BE contract.
 - Compare generated routes/code against that 01 file. Missing 01 → STOP, hand off to docs `/grill-api-spec`.
 - Do NOT demand full filesystem paths from the user if an ID is given.
@@ -36,6 +36,8 @@ Check:
 - Writes are transaction-safe; async retries are idempotent.
 - Generated placeholders are replaced before ship.
 
+**CLI (lượng):** `flowgrid audit api` on `01`; when portal bundle exists → `flowgrid audit fe-be` on sibling `*.bundle.yaml`.
+
 ## Accelerators (optional)
 
 ```text
@@ -48,9 +50,8 @@ else: targeted repository search
 architecture IDs / C4 → bộ docs (FLOWGRID_DOCS_ROOT), never CodeGraph
 ```
 
-Missing accelerators never block the grill. Complete each scoped model or
-targeted-local fallback first, then follow
-the remainder of this skill.
+Missing accelerators never block the audit. Complete each scoped model or
+targeted-local fallback first, then follow the remainder of this skill.
 
 ## Translation Rule (i18n)
 Always wrap static text with native framework i18n helpers (e.g. `__('key')`, `_localizer["key"]`, `i18n.t('key')`).

package/harness/common/extracts/artifact-graph.md

@@ -17,7 +17,7 @@ Path root: `base-docs Code / `--id``
 | /test | `*.test.yaml`, ir/spec testIds | legacy-api-migration |
 | /unit | ir/spec + `{function}/generated/unit.manifest.json` | legacy/* |
 | /model | ir/spec entities + project-config | trace full |
-| /grill-api | legacy/api-migration | models/ |
-| update-spec-legacy | trace slice + bundle.legacy patch | macro legacy read |
+| /audit-api | legacy/api-migration | models/ |
+| /update-spec | trace slice + bundle.legacy patch | macro legacy read (dùng `/legacy /spec` khi re-adopt) |
 
 Generated output: `{function}/generated/` (HANDOFF, manifests) — cạnh bundle, không trong `ir/`.

package/harness/common/extracts/artifactgraph-phase-hooks.md

@@ -28,7 +28,7 @@ Cloud **không** viết registry. Promote = docs `DESIGN-REGISTRY-PROMOTION` / `
 
 ## Shared protocol (every artifact skill)
 
-1. Run `artifactgraph init` once in the current product repo, then use
+1. Run `flowgrid init` once in the current product repo, then use
    `artifactgraph_status`; project-local MCP is the default.
 2. **Local:** `artifactgraph_analyze` or `artifactgraph_grill_check`; after legacy also **`artifactgraph_parity_check`**.
 3. **API reuse check (BE/docs):** Run `artifactgraph_api_reuse_check` before creating
@@ -50,7 +50,7 @@ Cloud **không** viết registry. Promote = docs `DESIGN-REGISTRY-PROMOTION` / `
 - Cloud: only unknown domain rules in `cloudPromptSlice`.
 - **Không** `portal:gen` app ở phase này (trừ khi skill nói rõ dry gate).
 
-### `/api-spec` · `/api-integration-spec`
+### `/api-spec`
 
 - **Pre-flight:** `artifactgraph_api_reuse_check({ path, method })` trước khi viết spec.
   - `found: true` → add `#reuse-api` vào spec; không cần tạo spec mới.

package/harness/common/extracts/docs-mark-detect.md

@@ -8,7 +8,7 @@
 |--------|----------------|------------|
 | Endpoint mô tả payment/webhook/MES/ERP | `#call-external` | A local B `#call-external` C defer |
 | 2 entity độc lập, 1 flow sync | `#cross-entity-service` | A relationship B cross-entity C split APIs |
-| Field/response key không có trên `ir/spec.yaml` entities | `#derived-data` | A add to contract B `#derived-data` C remove |
+| Field/response key không có trên `ir/design.yaml` (`entities` / `sections[].db`) hoặc `01-backend-spec.yaml` `modules[].entities` | `#derived-data` | A add to contract B `#derived-data` C remove |
 | Tag có nhưng thiếu block (`externalCalls`, `services`, `derivedData`) | validation fail | Fix via `/docs-mark` |
 | `commonRefs` trỏ registry `planned` | HANDOFF debt | Implement or defer in `openQuestions` |
 
@@ -42,7 +42,7 @@ If member chooses **B** → run `/docs-mark` in the same session.
 | `artifactgraph_api_reuse_check` finds existing route for same path+method | `#reuse-api` | Agent adds `#reuse-api` to spec (no gate) |
 | Endpoint calls payment/webhook/OAuth/SMS/MES/ERP system | `#call-external` | A local B `#call-external` C defer |
 | 2 bounded-context entities in single synchronous flow | `#cross-service` / `#cross-entity-service` | A single service B cross-service C split APIs |
-| Response field không có trên `ir/spec.yaml` entities | `#derived-data` | A add to entity B `#derived-data` C remove |
+| Response field không có trên `01` entity fields / `ir/design` `db.field` | `#derived-data` | A add to `01` B `#derived-data` C remove |
 | `DUPLICATE_API_ROUTE` gap in grill_check output | add `#reuse-api` | Agent adds `#reuse-api` to current spec |
 
 **Rule:** If 2 specs define the exact same URI path+method without `#reuse-api`, ArtifactGraph emits `DUPLICATE_API_ROUTE` gap (`severity: warn`, `draftTags: ['#reuse-api']`). Agent adds the tag to resolve — no member gate needed.

package/harness/common/extracts/entity-relationship.md

@@ -0,0 +1,23 @@
+# Entity & relationships — SSOT map
+
+Dùng khi grill-api-spec / codegen handoff `#manual-action:` (Eloquent relationships, joins).
+
+## Ba nguồn (không trùng vai)
+
+| Layer | Artifact | Nội dung |
+|-------|----------|----------|
+| Phase 0 | `<LCA>/common/db-erd.md` | ER tổng, ownership, cardinality — skill `/db-erd` |
+| Design | `ir/design.yaml` | `entities`, `relationships`, `sections[].db` (column binding) |
+| BE contract | `api/<seq>/01-backend-spec.yaml` | `modules[].entities[].fields`, quan hệ codegen |
+
+Workflow: [architecture-data.md](../../../docs/workflows/architecture-data.md) (repo hub).
+
+## Quy tắc sync
+
+- Thêm bảng/entity **mới** → cập nhật **db-erd** (Phase 0) trước khi mở rộng `01`.
+- Quan hệ runtime (belongsTo, hasMany, …) → khớp cardinality trong ERD; chi tiết ORM trong Action theo `01` + ERD.
+- Field chỉ search/compute → `#derived-data` (`common/data-model/derived-data.md`), không fake FK trên ERD.
+
+## Handoff codegen
+
+Khi tag `#manual-action:relationships`: đọc ERD + `01` module entity list; implement relationship trên model/Action — không invent entity name lệch ERD.

package/harness/common/rules/flowgrid-ux-common.mdc

@@ -5,7 +5,7 @@ alwaysApply: true
 
 # UX proposals (global)
 
-**DSL and bundle SSOT:** `/spec`, `/update-spec`, `design.registry.json`, `gen-common`. Do not replace spec authoring with the checklist extract.
+**DSL and bundle SSOT:** `/spec`, `/update-spec`, `design.registry.json`, FE base components. Do not replace spec authoring with the checklist extract.
 
 ## When this applies
 
@@ -16,8 +16,8 @@ Prompt analysis, UI proposals, affordance review. **Primary:** `/spec` per-zone
 1. Map DSL/registry first (`#shell:`, `#pattern:`, `#ui:`, `#widget:`, generated CMN).
 2. On match → codegen/wire only; no redundant YAML/spec.
 3. Unmapped, missing DSL, or UI not recognized as a pattern → read **`.cursor/extracts/ux-common-patterns.md`**; apply matching **Recognize** / **Propose** sections.
-4. **`flowgrid audit spec`** — patch `UX_*` gaps in bundle; `CONFIRM_UX_*` → `AskQuestion` using audit `(Recommended)` options.
-5. Stable cross-project pattern → `gen-common`; never hand-duplicate common IR.
+4. **`flowgrid audit spec`** — patch `UX_*` gaps; `CONFIRM_UX_*` → `AskQuestion`. **`CONFIRM_DB_*`** (`category: db`) → same wizard rules — see `db-audit-wizard.md`.
+5. Stable cross-project pattern → already in FE base or [custom-base](../../../docs/workflows/custom-base.md); never author `common/yaml` on the hub.
 
 | Situation | Action |
 |-----------|--------|

package/harness/common/skills/configure-repo-maps/SKILL.md

@@ -54,5 +54,7 @@ legacy ERP at D:\legacy\erp, key legacy-erp
 
 ## After Write
 
-1. Run `platform-dna codegraph:wire` (when utilizing Cursor + CodeGraph).
-2. For checkouts lacking `.codegraph/`: `cd <root> && codegraph init`.
+1. Compare with `.flowgrid/config.json` (init SSOT): `flowgrid repo-maps check`.
+2. If paths conflict with init/harness MCP: `flowgrid repo-maps align` (member chốt từng hub `docs` / `tests`).
+3. One-way refresh from config: `flowgrid repo-maps sync --from-config` then `flowgrid harness sync`.
+4. Optional CodeGraph: `platform-dna codegraph:wire` · `codegraph init` per checkout.

package/harness/docs/extracts/agent-execution-protocol.md

@@ -17,15 +17,15 @@ surfaces/<surface>/CMP-*/<slug>/     # no modules/ segment
 
 1. **PRE-FLIGHT:** First action = `{{FLOWGRID_READ_TOOL}}` / read target `SKILL.md`. Never memory.
 4. **NO RAM CACHING:** Durable results → disk immediately. Prior file = next input.
-5. **ZERO BUSINESS HALLUCINATION:** Data only from User prompt or ArtifactGraph. Gaps → AskQuestion (MUST include "Log as Tech Debt" option); if member selects "Log as Tech Debt" → `qa/open/QA-<page-id>-NNNN.yaml` + `#missing_info QA-…`. No invented business fields.
+5. **ZERO BUSINESS HALLUCINATION:** Data only from User prompt or ArtifactGraph. Gaps → AskQuestion (MUST include "Log as Tech Debt" option); if member selects "Log as Tech Debt" → `qa/<SHORT>_NNNN.yaml` + `#missing_info QA-…`. No invented business fields.
 6. **GRILL HARD GATE:** AG re-check → micro-scope → propose → **STOP for Confirm** before product SSOT write.
-7. **HUMAN DSL:** Common/DSL only via `/common`, `/common-spec`, `/docs-mark`, or grill Confirm. `/spec` consumes only.
+7. **HUMAN DSL:** Common/DSL only via `/common`, `/docs-mark`, custom-base, or grill Confirm. `/spec` consumes only (no `common/yaml`).
 
 ## Order
 
 ```text
 {{FLOWGRID_READ_TOOL}} SKILL.md
   → durable writes immediately (No RAM)
-  → AskQuestion or qa/open + grill Confirm before SSOT fill
+  → AskQuestion or qa + grill Confirm before SSOT fill
   → common/DSL only when human-gated
 ```

package/harness/docs/extracts/api-codegen-readiness.md

@@ -0,0 +1,34 @@
+# API codegen readiness (`/grill-api-spec`)
+
+Stop handoff to `api-gen` until `01` passes below.
+
+## Required on `01`
+
+| Field / block | Notes |
+|---------------|--------|
+| `codegen.profile` | e.g. `crud-standard`, `list`, `command-stub` — see registry |
+| `codegen.module` / `codegen.entity` | Match `modules[].entities[]` primary |
+| `api.endpoints[].action` | Aligns with path suffix (`search`, `create`, …) |
+| `approval.status` | Team policy: `approved` before production `api-gen` |
+
+## Gates (docs hub cwd)
+
+```text
+flowgrid audit api <01>
+flowgrid audit fe-be <bundle.yaml>    # portal-backed only
+flowgrid api:check --spec <01>
+flowgrid openapi_gen --spec <01>
+flowgrid openapi_render
+flowgrid render
+```
+
+## `/api-spec` vs `/grill-api-spec`
+
+- `/api-spec`: domain tags `#err:*`, `#call-external`, URI rules — **no** `#gen:*` / full codegen block.
+- `/grill-api-spec`: adds `#gen:*`, `approval`, codegen completeness.
+
+## Still missing after grill?
+
+`#tech-debt:QA-*` + `qa/` — or `/qa-resolve`. Do not ship silent gaps.
+
+Registry: BE checkout `registries/codegen.registry.json` (after `registry:sync`).

package/harness/docs/extracts/api-codegen-tags.md

@@ -0,0 +1,30 @@
+# API `#gen:*` tags (grill-api-spec)
+
+Apply on **`01-backend-spec.yaml`** (endpoint `tags[]` or root `tags` per registry). `/api-update` does **not** add `#gen:*` — grill only.
+
+## Common tags (Laravel registry mirror)
+
+| Tag | Typical use |
+|-----|-------------|
+| `#gen:module` | Scaffold module shell |
+| `#gen:crud` | CRUD controller/service bundle |
+| `#gen:model-tenant` / `#gen:model-platform` | Entity model scope |
+| `#gen:test-module` | Module-level test stub |
+| `#gen:test-unit` | Unit tests per endpoint policy |
+| `#gen:select-items` | Dropdown/list helper endpoints |
+| `#gen:action-<name>` | Custom action pipeline |
+
+## Domain (non-gen)
+
+| Tag | When |
+|-----|------|
+| `#call-external` | Outbound HTTP + `externalCalls[]` |
+| `#cross-entity-service` | `services[]` multi-aggregate |
+| `#manual-service` | Hand-written service block |
+| `#err:*` | Error storming (also on `errorStorming`) |
+
+## Verify
+
+After tagging: `api-gen:dry -- --spec <01>` on BE repo with `FLOWGRID_DOCS_ROOT` set.
+
+Do not invent tags absent from `codegen.registry.json` without member approval.

package/harness/docs/extracts/api-contract.md

@@ -0,0 +1,43 @@
+# API contract — đọc/ghi (agent digest)
+
+Hub SSOT: `templates/shared/tpl-api-contract.md` (sau init: `.flowgrid/templates/tpl-api-contract.md`).
+
+## SSOT
+
+| Ghi | Đọc review |
+|-----|------------|
+| `api/<seq>/01-backend-spec.yaml` | `ir/generated/api.md` (sau `flowgrid render`) |
+| `02-openapi.yaml` | Gen only — sửa `01` + `openapi_gen` |
+| `ir/design.yaml` `apiRefs` | Portal FE — **không** input BE codegen |
+
+Mẫu `01`: `.flowgrid/templates/backend-api.yaml`. **Không** dùng `backend-api.bundle.yaml` cho contract mới.
+
+## Trio
+
+```text
+api/<seq>/01-backend-spec.yaml
+api/<seq>/02-openapi.yaml
+api/<seq>/03-mock.yaml          # optional — stub: api-03-mock.stub.yaml
+```
+
+## OpenAPI chain (sau mỗi sửa `01`)
+
+```text
+flowgrid api:check --spec …/01
+flowgrid openapi_gen --spec …/01
+flowgrid openapi_render
+flowgrid render
+```
+
+**Forbidden:** `flowgrid check` on `01`; hand-edit `02` as SSOT; `nestjs --openapi` on docs hub.
+
+## Portal vs BE-only
+
+- `base` ≠ `none` → read `ir/design.yaml` for `/api-spec`; `audit fe-be` + `audit api`.
+- `base: none` → **`01` only** for contract; `audit api` only.
+
+## Reuse
+
+`#reuse-api` + `reuseFrom` on design action — **no** new `api/<seq>/` folder.
+
+Workflow hub: `docs/workflows/backend.md`.

package/harness/docs/extracts/api-spec-sync.md

@@ -0,0 +1,35 @@
+# API spec sync — portal ↔ `01`
+
+Dùng với `/api-spec`, `/api-update`, `/grill-api-spec`.
+
+## `/api-update` modes
+
+| Mode | Trigger | Allowed |
+|------|---------|---------|
+| `portal-sync` (default) | Portal đổi `ir/design.yaml` | Diff design → patch `01` (+ `03-mock.yaml`); regen `02` |
+| `be-only` | `--be-only` | `beOnlyRequirements`, internal validation — **no** breaking FE contract |
+
+## Portal-sync steps
+
+1. Read full `ir/design.yaml` — `apiRefs`, `#reuse-api`, `reuseFrom` (ignore projected `design.api` as SSOT).
+2. Diff vs `01-backend-spec.yaml` (endpoints, DTO, errors, entities).
+3. Patch `01` (+ mock if samples change); **never** hand-edit `02`.
+4. `api:check` → `openapi_gen` → bump `feature.version` + `changeLog[]`.
+5. `flowgrid render` → refresh `ir/generated/api.md`.
+6. Handoff: `/grill-api-spec` (codegen tags, `approval`).
+
+## `#reuse-api`
+
+Action marked reuse → **do not** create duplicate trio; pointer must resolve to existing `01`.
+
+## Common APIs
+
+Path: `…/common/yaml/<slug>/01-backend-spec.yaml` — same trio rules, scan before new endpoint on leaf.
+
+## Missing facts
+
+AskQuestion (Recommended / Other / Tech Debt) → `qa/*` — **no** `openQuestions` in YAML.
+
+## Field rename guard
+
+**Forbidden:** rename API fields only to match FE convenience without member decision.

package/harness/docs/extracts/artifactgraph-hooks-docs.md

@@ -3,7 +3,7 @@
 - Treat this docs repo as the canonical full registry/parity hub (`surfaces/...`).
 - Use path hints from `registries/docs-index.json` when available.
 - Use local vocabulary suggestions for specs and documentation marks.
-- Before `/api-spec`, `/api-integration-spec`, `/grill-with-docs`, or `/bqa-grill-docs`,
+- Before `/api-spec`, `/grill-with-docs`, or `/bqa-grill-docs`,
   run `artifactgraph_api_reuse_check` to validate route uniqueness across product surfaces.
   Docs hub is SSOT — if a route already exists in a sibling surface, apply `#reuse-api`
   or document the divergence in `openQuestions`.

package/harness/docs/extracts/call-external.md

@@ -0,0 +1,16 @@
+# `#call-external` — outbound integrations
+
+Hashtag only (via `/api-spec`, `/grill-api-spec`, `/api-update`) — **not** a standalone slash skill.
+
+## On `01` only
+
+- Add `externalCalls[]` entry: `id`, `provider`, `direction`, `trigger`, `timeoutMs`, `retry`, `idempotency`, `secrets` refs.
+- Tag endpoint: `#call-external` in `tags[]` or `errorStorming`.
+
+## Rules
+
+- Never edit `ir/design.yaml` for external contract detail.
+- No invented secrets — AskQuestion or `qa/`.
+- Grill: timeout/retry/idempotency must be explicit before `api-gen`.
+
+Hub: `docs/references/skills/call-external.md`.

package/harness/docs/extracts/common-scope.md

@@ -1,6 +1,8 @@
 # Common + FLOW placement (lowest shared folder)
 
-Agents MUST pick **one** `common/` using the **lowest folder that every consumer already shares**. Do not invent extra `common/` trees. `/spec` only **consumes**; create/update common only via `/common`, `/common-spec`, or `/module … common` after the user named the scope.
+Agents MUST pick **one** `common/` using the **lowest folder that every consumer already shares**. Do not invent extra `common/` trees. `/spec` only **consumes**; create/update common Markdown only via `/common` (or `/module … common`) after the user named the scope.
+
+**No `common/yaml` on new hubs** — UI patterns live in the FE base + `flowgrid-ux-common.mdc`; new codegen templates → custom-base (`build-template-code`).
 
 Numeric function folders stay numeric (`01/02/03/`). The only non-numeric directory names under a `CMP-*` are `common/` and the `CMP-*` id itself.
 
@@ -23,10 +25,11 @@ Inside every `common/`:
 ```text
 common/
   patterns/          ← /common Markdown (BA/QA rules)
-  yaml/<slug>/       ← /common-spec *.bundle.yaml
   processes/         ← module/cluster FLOW-*.md (not architecture catalog)
 ```
 
+Optional: `data-model/`, `integrations/`, `db-erd.md`, `cross-service.md` at the same LCA (see skills `/db-erd`, `/cross-service`).
+
 ## 2. Ambiguous scope
 
 If the prompt does not name consumers, **stop and ask** (propose the LCA from the table). Do not default to `surfaces/common` or to a random function folder.
@@ -35,12 +38,7 @@ If the same pattern already exists at a **narrower** `common/`, **reuse it** (re
 
 ## 3. Consume order (`/spec`, `/grill-*`, `/api-spec`)
 
-From the function folder, walk **up** and use the **nearest** hit. Do not skip a module `common/` to copy into surface `common/`.
-
-1. `…/<CMP>/<cluster…>/common/yaml/` (nearest ancestor `common/`)
-2. `…/<CMP>/common/yaml/`
-3. `surfaces/<surface>/common/yaml/`
-4. `surfaces/common/yaml/`
+From the function folder, walk **up** and read the **nearest** `common/patterns/*.md` (and FLOW under `processes/` when relevant). Do not author duplicate YAML CMN bundles.
 
 Same walk for `patterns/` Markdown.
 
@@ -60,6 +58,7 @@ Do **not** drop `FLOW-*.md` beside a single `W-*` bundle. Do **not** write modul
 ## 5. Forbidden
 
 - Creating `common/` from `/spec`
-- Textual slugs in the path (`auth/`, `cluster-name/`) except `common/` and `yaml/<bundle-slug>/`
-- Duplicate copies of the same bundle at two LCA levels
+- `common/yaml/`, `/common-spec`, `/gen-common`, `/grill-common-spec` on new hubs
+- Textual slugs in the path (`auth/`, `cluster-name/`) except `common/` and bundle slugs under function leaves
+- Duplicate copies of the same rule at two LCA levels
 - `Surfaces/Common` mixed case when the hub uses `surfaces/`

package/harness/docs/extracts/db-audit-wizard.md

@@ -0,0 +1,45 @@
+# DB audit — grill /spec AskQuestion wizard
+
+> Source: `flowgrid audit spec` → `confirms[]` where `category: db` and codes `CONFIRM_DB_*`.
+> Agent **MUST NOT** silently pick DB mappings — run wizard like `CONFIRM_UX_*`.
+
+## When
+
+- `/spec` after audit (existing bundle or mid-authoring)
+- `/grill-bqa` Step B, `/grill-dev`, `/grill-docs` after `audit spec` re-run
+- Law 2: ≤5 `CONFIRM_DB_*` in one chat batch → one question at a time; ≥10 total gaps+confirms → Plan Mode
+
+## Member prompt template
+
+```text
+[GRILL-DB] {short finding}
+Path: {confirm.path}
+Question: {confirm.question}
+
+Chọn (khớp option audit):
+A) {options[0]}  ← (Recommended) when defaultRecommend === 0
+B) {options[1]}
+C) Log as Tech Debt (Pending)  — or option[2] if audit lists it
+```
+
+After answer → patch bundle (`spec.entities`, `design.sections[].db`, `design.dataModel`, or handoff `/api-update` for `01`) → **re-run** `flowgrid audit spec`.
+
+## Code → action map
+
+| Code | Member chọn (Recommended) thường là |
+|------|-------------------------------------|
+| `CONFIRM_DB_SPEC_ENTITIES` | Điền `spec.entities[]` khớp ERD |
+| `CONFIRM_DB_MULTI_TABLE_OVERVIEW` | `design.dataModel.tables[]` per table |
+| `CONFIRM_DB_MULTI_TABLE_ENTITIES` | Bổ sung entity cho bảng phụ |
+| `CONFIRM_DB_REQUIRED_MAPPING` | Thêm `db.schema` + `db.field` |
+| `CONFIRM_DB_PARTIAL_BINDING` | Hoàn thiện schema+field hoặc `#derived-data` |
+| `CONFIRM_DB_BIND_CONFLICT` | Tách `bind.field` hoặc DTO nested trên 01 |
+| `CONFIRM_DB_LIST_COLUMN_STORAGE` | `columns[].db` hoặc `#derived-data` |
+| `CONFIRM_DB_BE_TABLE_DRIFT` / `CONFIRM_DB_BE_FIELD_DRIFT` | `/api-update` hoặc sửa design `db` |
+| `CONFIRM_DB_BE_SPEC_MISSING` | Author `01` trước grill-dev |
+
+## Review artifact
+
+Sau split: `ir/generated/data-model.md` (multi-table). BA đọc cùng wizard — không thay `confirms[]`.
+
+Extracts: `architecture-data.md` (workflow) · `tpl-screen-data-model.md` (author template).

package/harness/docs/extracts/derived-data.md

@@ -0,0 +1,18 @@
+# `#derived-data` — API & design
+
+Fields **computed / search-only** — not persisted FK on ERD.
+
+## Where to mark
+
+| Layer | How |
+|-------|-----|
+| Design | List column / bind without `db.field`; tag `#derived-data` on item/column |
+| BE `01` | Field in response/DTO without table column — document in endpoint purpose or `technicalMarks` |
+
+Prose: `surfaces/common/data-model/derived-data.md` (skeleton) · bundle [tpl-screen-data-model.md](../../../templates/shared/tpl-screen-data-model.md).
+
+## Audit
+
+`flowgrid audit spec` may suggest `#derived-data` when column has no `db` mapping.
+
+Do not add fake `modules.entities.fields` for pure UI computed values unless API truly returns them.

package/harness/docs/extracts/design-leaf-signoff.md

@@ -0,0 +1,16 @@
+# Design leaf sign-off (voluntary)
+
+Hub SSOT: `docs/workflows/design-leaf-signoff.md` — **không** engine gate.
+
+## Rubric 6 mục (lead/BA)
+
+1. `flowgrid audit spec <bundle> --type <profile>` — `gaps[]` xử lý; `confirms[]` chốt hoặc `qa`.
+2. VitePress `ir/generated/spec.md` (+ `data-model.md`) — stories, list columns, AC không placeholder.
+3. Spot 2–3 scenario ↔ `design.actions` / validation messages VI.
+4. `api/.../01-backend-spec.yaml` ↔ `ir/design.yaml` apiRef; `audit fe-be` nếu có BE.
+5. `grillStatus.dev: done` (theo flow); `gen:dry` pass; `bundle.gen` đầy đủ.
+6. `qa` rỗng hoặc debt đã accept.
+
+Optional: **Data model** — `db-erd` LCA + `design.sections[].db` / `spec.entities` (xem hub `architecture-data.md`). `/grill-prototype` SSOT issues; `registry:sync` trên FE standard base.
+
+Ghi nhận: `Design sign-off: <page-id> | reviewer | date | 6/6` (PR/chat — không bắt buộc field YAML).