@shanyucoder/flowgrid 0.1.4 → 0.1.8

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

@@ -19,7 +19,7 @@ surfaces/<surface>/CMP-*/<slug>/     # no modules/ segment
 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.
 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
 

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/open/` — 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/open/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/open/`.
+- 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/open`.
+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/open` 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).

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

@@ -4,6 +4,7 @@
   "bundles": {
     "architecture-core": [
       ".cursor/extracts/architecture-core.md",
+      ".cursor/extracts/spec-ssot-prep.md",
       ".cursor/extracts/tpl-arc42-chapter.md",
       ".cursor/extracts/tpl-module.md",
       ".cursor/extracts/tpl-deployment.md",
@@ -18,6 +19,10 @@
     ],
     "spec-requirement": [
       ".cursor/extracts/spec-requirement.md",
+      ".cursor/extracts/spec-prd-lite.md",
+      ".cursor/extracts/spec-ssot-prep.md",
+      ".cursor/extracts/design-leaf-signoff.md",
+      ".cursor/extracts/db-audit-wizard.md",
       ".cursor/extracts/agent-execution-protocol.md",
       ".cursor/extracts/common-scope.md"
     ],
@@ -27,11 +32,13 @@
     ],
     "bqa-grill": [
       ".cursor/extracts/grill/validation.md",
+      ".cursor/extracts/db-audit-wizard.md",
       ".cursor/extracts/agent-execution-protocol.md"
     ],
     "dev-grill": [
       ".cursor/extracts/codegen/readiness.md",
-      ".cursor/extracts/docs-mark-detect.md"
+      ".cursor/extracts/docs-mark-detect.md",
+      ".cursor/extracts/db-audit-wizard.md"
     ],
     "grill-docs": [
       ".cursor/extracts/grill-docs-reconcile.md",
@@ -39,6 +46,7 @@
     ],
     "update-spec": [
       ".cursor/extracts/update-spec-delta.md",
+      ".cursor/extracts/wire-spec-feedback.md",
       ".cursor/extracts/qa-inbox.md"
     ]
   }

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

@@ -1,5 +1,9 @@
-# Common spec core (/common-spec)
+# Common on docs hub (Markdown only)
 
-Emit **YAML bundles** under `surfaces/…/common/yaml/` — never hand-write `ir/generated/*.md`.
+`/common` writes `common/patterns/*.md` at the LCA from `common-scope.md`.
 
-After edits: `flowgrid split` → `flowgrid render`.
+Cross-flow: `common/processes/FLOW-*.md`.
+
+**Deprecated:** `/common-spec`, `common/yaml`, `/gen-common`, `/grill-common-spec`.
+
+UI affordances: FE base + `flowgrid-ux-common.mdc`. Prep drill: `spec-ssot-prep.md` (registry / adopt / custom-base) before leaf `/spec`. New shared codegen: custom-base `build-template-code`.

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

@@ -0,0 +1,21 @@
+# Spec evolution — version & changelog
+
+Applies to **`01-backend-spec.yaml`** (`/api-update`) and **`*.bundle.yaml`** (`/update-spec`).
+
+## On every material patch
+
+- Bump `feature.version` (semver policy team).
+- Append `changeLog[]` entry: `id`, `summary`, `impact[]`, `breaking: bool`.
+- Portal sync: refresh `feature.source.portalRefs` / `syncedAt` when design linkage changes.
+
+## Breaking changes
+
+Set `breaking: true`; require re-grill (`/grill-api-spec` or `/grill-dev`) before codegen.
+
+## Deferred work
+
+Use `pendingTechDebt[]` with `id: QA-<feature.id>-NNNN` + matching `qa/open/` file — not prose in `requirements`.
+
+## OpenAPI
+
+Contract change on `01` → always regen `02` — never patch `02` as source.

package/harness/docs/extracts/spec-prd-lite.md

@@ -0,0 +1,19 @@
+# Leaf bundle ↔ PRD lite (map for /spec)
+
+| PRD section | Bundle / IR |
+| --- | --- |
+| Problem / goals | `summary` bullets (business_goals, stakeholders, user_journey, context) |
+| Success metrics | `successMetrics` (optional) |
+| Non-goals | `nonGoals` (optional) |
+| Users / persona | `userStories.primary.asA` + link `overview/` persona |
+| User stories + AC | `userStories.scenarios`, `acceptanceCriteria` |
+| Functional scope | `spec.requirements`, `design.sections`, `design.actions` |
+| API | `api/<seq>/01-backend-spec.yaml` — **not** `spec.api` |
+| Tech / codegen | `gen`, `grill-dev` — not in first `/spec` pass |
+| Open questions | `qa/open/QA-*.yaml` |
+
+**Author path:** `.flowgrid/templates/feature.bundle.yaml` + `bundle-authoring.md` only. **`design-spec.yaml` deprecated.**
+
+**BA deliverable:** `ir/generated/spec.md` (TOC, overview, metrics, non-goals) after `flowgrid split` + `flowgrid render`.
+
+**Profile trim:** list → giữ Initial Load, Affordances (nếu có), Exceptions; bỏ scenario form nếu không có `ui.form`. create/detail tương tự — không copy 6 scenario khi không áp dụng.

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

@@ -1,5 +1,9 @@
 # Spec requirement (/spec)
 
-Author **bundle YAML only** on the docs hub. Markdown under `ir/generated/` is produced by `flowgrid render`.
+Author **`*.bundle.yaml` only** — template: `.flowgrid/templates/feature.bundle.yaml` + `bundle-authoring.md`. **Do not** author `design-spec.yaml` (deprecated).
 
-Path SSOT: `surfaces/<surface>/CMP-*/<NN…>/` — resolve IDs with `flowgrid_docs_route` when on a consumer repo.
+Required business keys when info exists: `summary`, `userStories` (+ `screenAccess`), optional `successMetrics`, `nonGoals`. See `spec-prd-lite.md` for PRD map.
+
+After patch: `flowgrid split` → `flowgrid render` → BA reads `ir/generated/spec.md` (not hand-written `.md`).
+
+Path SSOT: `surfaces/<surface>/CMP-*/<NN…>/` — resolve IDs with `flowgrid_docs_route` on consumer repo.

package/harness/docs/extracts/spec-ssot-prep.md

@@ -0,0 +1,25 @@
+# Spec SSOT prep drill (hub)
+
+SSOT workflow: `docs/workflows/spec-ssot-prep.md`
+
+## Trước `/spec` hoặc `/legacy /spec`
+
+| Nhánh | Lệnh / skill | Bắt buộc khi |
+|-------|----------------|--------------|
+| A Standard | FE `registry:sync` sau init | Greenfield default base |
+| B Custom | `build-template-code` ([custom-base](../../../docs/workflows/custom-base.md)) | Stack lệch template |
+| C Brownfield | `/adopt` → `audit legacy` | Có legacy repos; `/legacy /spec` |
+
+Brownfield + custom: **C → B** (hoặc B đã có) → Phase 0 → leaf spec.
+
+## Trên session spec
+
+1. Inventory: `/legacy` → bắt buộc `adoption-inventory.md`; greenfield → đọc Section 5 CMN **nếu file tồn tại** (workspace brownfield).
+2. Không copy-paste legacy file — `CMN-*` + DSL/registry.
+3. `audit spec` → `gaps[]` patch; `CONFIRM_UX_*` + `CONFIRM_DB_*` → AskQuestion (`db-audit-wizard.md`).
+4. `split` + `render` → `ir/generated/spec.md`, `data-model.md`.
+
+## STOP prompts
+
+- `/legacy /spec` without inventory → *Run `/adopt` first.*
+- Custom stack without registry build → *Complete custom-base prep before spec.*

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

@@ -9,6 +9,18 @@ Lead-assigned module. **This README is MD-only** (no YAML).
 
 Owns …
 
+## Out of scope (module)
+
+- [Chức năng / CMP khác giữ SSOT — không copy bundle vào module này]
+- [Hạ tầng / deployment — `architecture/`]
+
+## Depends on
+
+| ID / artifact | Lý do |
+| --- | --- |
+| `CMP-…` / `FLOW-…` | [Upstream data hoặc quy trình] |
+| `API-…` | [Contract reuse — link `01-backend-spec`] |
+
 | | |
 |--|--|
 | **ID** | `CMP-{NN}` |

package/harness/docs/extracts/verify-gate.md

@@ -0,0 +1,33 @@
+# Verify gates — API lane (quick)
+
+Run from docs hub (`FLOWGRID_DOCS_ROOT` or cwd).
+
+## Contract
+
+```text
+flowgrid audit api …/01-backend-spec.yaml
+flowgrid audit fe-be …/*.bundle.yaml     # if portal leaf
+flowgrid api:check --spec …/01
+```
+
+## OpenAPI + site
+
+```text
+flowgrid openapi_gen --spec …/01
+flowgrid openapi_render
+flowgrid render
+```
+
+## Not valid on `01`
+
+- `flowgrid check` — bundle/IR only.
+
+## BE repo (after grill)
+
+```text
+flowgrid api-gen:dry --adapter=<stack> -- --spec …/01
+```
+
+Exit non-zero → fix `01` or grill tags; do not patch generated BE as SSOT.
+
+Hub checklist: `docs/workflows/backend.md` · `docs/workflows/gates.md` step 5.

package/harness/docs/extracts/wire-spec-feedback.md

@@ -0,0 +1,31 @@
+# Wire discoveries → /update-spec or /api-update
+
+When **wire** or **`audit fe-be`** on FE exposes spec/contract drift, patch on **docs hub** — then loop test + wire.
+
+## Choose lane
+
+| Drift | Skill | Notes |
+|-------|-------|-------|
+| UX copy, AC, actions, validation message on UI | `/update-spec` | Patch bundle; `#update:*`; `audit spec`; split |
+| Endpoint, schema, status code on `01` | `/api-update` | Then `audit api`, `openapi:gen`, BE `/audit-api` |
+| Both | `/update-spec` + `/api-update` in order (contract first if BE blocks UX) |
+
+## update-spec guardrails (wire context)
+
+- `featureStatus: wire` → set `need-update` when delta applied.
+- Do **not** clear `#update:*` on bundle — `/wire` clears after implementation confirms.
+- After split/render: handoff FE `/wire` or `/prototype` if UI structure changed; tests-hub `/grill-testcase` if AC/matrix changed.
+
+## Paste-ready prompt shape (from grill-wire / grill-testcase)
+
+```text
+/docs-hub /update-spec
+
+Screen: <W-*>
+Delta: <what wire/API proved wrong>
+Bundle path: surfaces/.../<slug>.bundle.yaml
+Sections: <userStories | design.actions | onSpecificError | ...>
+Evidence: audit fe-be FEBE_* / staging response / E2E failure
+```
+
+Full delta rules: `update-spec-delta.md` · skill `harness/docs/skills/update-spec/SKILL.md`.