@shanyucoder/flowgrid 0.1.5 → 0.1.9

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",
@@ -14,10 +15,15 @@
     "docs-hub": [
       ".cursor/extracts/docs-phase-hooks.md",
       ".cursor/extracts/agent-execution-protocol.md",
-      ".cursor/extracts/qa-inbox.md"
+      ".cursor/extracts/qa-inbox.md",
+      ".cursor/extracts/qa-team.md"
     ],
     "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 +33,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 +47,7 @@
     ],
     "update-spec": [
       ".cursor/extracts/update-spec-delta.md",
+      ".cursor/extracts/wire-spec-feedback.md",
       ".cursor/extracts/qa-inbox.md"
     ]
   }

package/harness/docs/extracts/qa-inbox.md

@@ -7,28 +7,37 @@ There is **no** `openQuestions` on YAML. Gaps use **AskQuestion** in the skill s
 AskQuestion: MUST include your Recommended options AND an explicit "Log as Tech Debt (Pending)" option. (The UI automatically provides the 3rd "Other" option). **STOP**.
 
 - Member picks A/B/C (Recommended) → write that fact into the real spec field (`design`, `01`, …).
-- Member picks **Log as Tech Debt (Pending)** → create a QA file (below). Do not invent the answer.
+- Member picks **Log as Tech Debt (Pending)** → create **one** `qa/<SHORT>_NNNN.yaml` with first `updates[]` line `kind: question`. Do not invent the answer.
 - Member picks **Other** and types a decision → write that text into the spec field.
 
 ## When to create a file
 
-1. Read `page-id` on the feature bundle / `ir/spec.yaml` (or `feature.id` on a backend `01`). Legacy bundles may still have `id`.
-2. Glob `qa/open/QA-<id>-*.yaml`. Next seq = max `NNNN` + 1, pad 4 digits. First file → `0001`.
-3. Write `qa/open/QA-<id>-NNNN.yaml` from `.flowgrid/templates/qa-item.yaml`.
-4. Point the spec field at the **same** id: `#missing_info QA-<id>-NNNN` and/or `#tech-debt:QA-<id>-NNNN` and/or `pendingTechDebt[].id`.
-5. `flowgrid split` — `ir/spec.yaml` gets `"Q&A": QA-…-0001, QA-…-0002`.
+**[MANDATORY]** Read whole `.flowgrid/templates/qa-item.yaml` + `.flowgrid/templates/qa-authoring.md` before writing.
+
+1. Pick **SHORT** slug (stable) — see `suggestQaShort(W-*)` in authoring doc.
+2. Next id: glob `qa/<SHORT>_*.yaml` **or** `nextQaId(hub, SHORT)` (`engines/docs/lib/qa-item.mjs`).
+3. Copy golden template → `qa/<SHORT>_NNNN.yaml`:
+   - `schema: flowgrid-qa-item/v1`
+   - `id` = basename; `status: open`; `target.path` + `target.at`; `screen` / `bundleId` / `skill` / `kind`
+4. First `updates[]`: `at` = `YYYYMMDD HH:mm` (`formatQaAt`), `kind: question`, `text` = open question.
+5. Point spec: `#missing_info <id>` / `#tech-debt:<id>` on `target.at`.
+6. `flowgrid split` — `ir/spec.yaml` Q&A lists open ids.
+
+Optional: `validateQaItem` / schema `templates/schemas/qa-item.schema.json`.
 
 ## Close (`/qa-resolve`)
 
-Prompt: `/qa-resolve QA-<page-id>-NNNN` plus the **solution** on the following lines.
+Prompt: `/qa-resolve <id>` plus **solution** on following lines.
+
+Append `kind: answer` to **same file**; patch bundle/01; `status: closed`; gỡ tags; `flowgrid split`.
 
-That is Confirm — do **not** AskQuestion again. Skill patches `target.path`, deletes this file, gỡ tag / `pendingTechDebt`, `flowgrid split` (and `openapi:gen` if 01).
+## Review (team)
 
-Unknown answer → grill / `/api-spec`, not this extract.
+`/qa-review <id>` → append `kind: review` to **same file** — see `qa-team.md`.
 
 ## Do not block grill
 
-`grillStatus` may be `done` while `qa/open/` still has files. Short `summary` prose is member review, not a QA file unless **keys** are missing.
+`grillStatus` may be `done` while `status: open` QA files exist.
 
 ## Not this folder
 

package/harness/docs/extracts/qa-team.md

@@ -0,0 +1,32 @@
+# QA — one file, append timeline (docs hub)
+
+Hub: `docs/workflows/qa-team.md`.
+
+## File naming
+
+`qa/<SHORT>_<NNNN>.yaml` — e.g. `HOTEL-LIST_0001.yaml`. Next index: glob same prefix, max NNNN + 1.
+
+`id` inside file = basename without `.yaml`.
+
+## Rules
+
+1. **One case = one file** for life of that question thread.
+2. **`updates[]` append-only** — `at` as `YYYYMMDD HH:mm`, `kind`: question | answer | review | note.
+3. **`qa/index.md`** is render-only catalog — do not put business log in index.
+4. **needs-change:** append `kind: review` with text; set `status: open`; do **not** create a second file.
+
+## Open (Tech Debt)
+
+Template: `.flowgrid/templates/qa-item.yaml` · rules: `qa-authoring.md` · `schema: flowgrid-qa-item/v1`.
+
+Create file + first update `kind: question`. Tag field: `#missing_info <id>` / `#tech-debt:<id>`.
+
+## /qa-resolve
+
+Append `kind: answer` with user solution text; patch `target.path` / `target.at`; remove QA tags from spec; `status: closed`; `flowgrid split`.
+
+## /qa-review
+
+Append `kind: review` only. If needs-change, `status: open`.
+
+Legacy `qa/` paths: migrate to flat `qa/<id>.yaml` when touching old hubs.

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/` 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/*.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`.

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

@@ -20,7 +20,7 @@ When executing any skill (`/spec`, `/grill`, `/grill-bqa`, etc.):
 3. **NO RAM CACHING:** All persistent changes **[MANDATORY]** immediately written via `{{FLOWGRID_WRITE_TOOL}}`. Never hold uncommitted state in chat/RAM. When a grill proposal is not yet confirmed → discuss directly in chat thread. **[STRICTLY FORBIDDEN]** to create temporary `*-proposal.md` files or overwrite product SSOT prior to explicit confirmation.
 4. **ZERO BUSINESS HALLUCINATION:** Ground data strictly from (1) User prompt and (2) ArtifactGraph registry. **[STRICTLY FORBIDDEN]** to invent fields, validations, database structures, or flows. Missing information must remain empty or be tagged `#missing_info`. No unprompted guessing.
 5. **GRILL HARD GATE:** ArtifactGraph re-check → micro-scope → provide structured recommendation (`(Recommended)`) → **STOP and prompt Member**. **[STRICTLY FORBIDDEN]** to write to SSOT before explicit user confirmation.
-6. **DSL / COMMON:** Human lead decides common promotions. The agent only executes `/common`, `/common-spec`, `/docs-mark`, or confirmation post-grill. `/spec` strictly consumes common definitions. **[STRICTLY FORBIDDEN]** to invent or overwrite common libraries spontaneously.
+6. **DSL / COMMON:** Human lead decides common promotions. The agent only executes `/common` (Markdown patterns), `/docs-mark`, custom-base handoff, or confirmation post-grill. `/spec` consumes patterns + FE base via `flowgrid-ux-common.mdc`. **[STRICTLY FORBIDDEN]** `common/yaml`, `/common-spec`, `/gen-common`.
 7. **ISOLATION:** Execute strictly within the invoked skill scope. **[STRICTLY FORBIDDEN]** to merge sibling features or output fake Markdown reports when YAML contracts are required.
 
 **Path SSOT:** `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment).

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

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

package/harness/docs/schemas/flowgrid-docs/qa-item.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://platform.local/schemas/flowgrid-docs/qa-item.schema.json",
+  "title": "FlowGrid QA inbox item",
+  "type": "object",
+  "required": ["schema", "id", "status", "target", "updates"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "flowgrid-qa-item/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Z0-9][A-Z0-9._-]*_\\d{4}$"
+    },
+    "screen": { "type": "string" },
+    "bundleId": { "type": "string" },
+    "status": { "type": "string", "enum": ["open", "closed"] },
+    "kind": {
+      "type": "string",
+      "enum": ["customer", "choice", "tech-debt", "integration", "coverage"]
+    },
+    "skill": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "target": {
+      "type": "object",
+      "required": ["path", "at"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string" },
+        "at": { "type": "string" }
+      }
+    },
+    "options": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["label"],
+        "properties": {
+          "label": { "type": "string" },
+          "recommended": { "type": "boolean" }
+        }
+      }
+    },
+    "updates": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/update" }
+    }
+  },
+  "$defs": {
+    "update": {
+      "type": "object",
+      "required": ["at", "kind", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "at": { "type": "string", "pattern": "^\\d{8} \\d{2}:\\d{2}$" },
+        "by": { "type": "string" },
+        "kind": { "type": "string", "enum": ["question", "answer", "review", "note"] },
+        "text": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

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

@@ -12,6 +12,8 @@ extractBundle: architecture-core
 
 **Audit Interlock:** Run `flowgrid audit legacy <target-id>`. Consume JSON gap report to verify mapping or prompt member if index is missing.
 
+**Handoff SSOT spec:** Sau adopt, member drill [spec-ssot-prep.md](../../../docs/workflows/spec-ssot-prep.md) — Phase 0 → `/legacy /spec` per `W-*` (không nhảy thẳng bundle không có ID trong inventory).
+
 ---
 
 ## Rule: Pre-Scan Mode Selection (AskQuestion Wizard)

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

@@ -1,6 +1,6 @@
 ---
 name: api
-description: EXCLUSIVE /api — Backend Router ONLY. Immediately routes to /api-spec or /api-integration without generating gross files.
+description: EXCLUSIVE /api — Backend Router ONLY. Immediately routes to /api-spec, /api-update, or /grill-api-spec without generating gross files.
 disable-model-invocation: true
 ---
 
@@ -18,14 +18,13 @@ disable-model-invocation: true
 
   | Condition | Route to |
   |---|---|
-  | No `01-backend-spec.yaml` + Portal-backed | `/api-spec` |
-  | No `01-backend-spec.yaml` + webhook/partner/no FE (`base: none`) | `/api-integration` |
+  | No `01-backend-spec.yaml` (portal-backed or BE-only / webhook / partner) | `/api-spec` |
   | Portal specs changed / merge deferred child functions | `/api-update` |
   | BE-only requirement (no FE contract change) | `/api-update --be-only` |
-  | Spec exists but not codegen-ready / `approval.status` not `approved` | `/grill-api-spec` or `/grill-integration-spec` (per `source.kind`) |
+  | Spec exists but not codegen-ready / `approval.status` not `approved` | `/grill-api-spec` |
   | `approval.status: approved` + explicit implement request | bộ code BE `/api` (switch to BE repo skill — NOT this skill) |
 
-- **[MANDATORY]** Locate `01-backend-spec.yaml` under: `…/api/<seq>/` (screen leaf), `…/common/yaml/<slug>/`, or `…/integrations/…/api/<seq>/`.
+- **[MANDATORY]** Locate `01-backend-spec.yaml` under: `…/api/<seq>/` (screen leaf), `…/common/yaml/<slug>/`, or any surface leaf dedicated to external-channel APIs.
 - **[STRICTLY FORBIDDEN]** Do NOT skip `/grill-api-spec` for new features, cross-portal, or legacy-derived contracts.
 - PHPUnit coverage: NOT routed here — use `/unit-be` directly.
 

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

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

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

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

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

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

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

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

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

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