@shanyucoder/flowgrid 0.1.5 → 0.1.9

package/harness/tests/extracts/wire-test-handoff.md

@@ -0,0 +1,37 @@
+# Wire phase — tests-hub handoff
+
+When **FE `/wire` or `/grill-wire`** finds plan gaps (real API behaviour, status codes, matrix facets), fix on **tests-docs** — not on FE repo.
+
+Hub: `docs/workflows/wire.md#gap-loop` · FE extract: `harness/fe/extracts/wire-audit-loop.md`.
+
+## Triggers from wire audits
+
+| Signal | Tests action |
+|--------|----------------|
+| `audit e2e` `matrixRowsUncovered` for post-wire facet | Extend `TC-*.yaml` `testMatrix` + `steps[]` (real API, no mock) |
+| New error path seen on wire (409, 422 field) | Add negative TC row; mirror bundle `#err:*` |
+| `SC_SCREEN_NO_TC` after wire | `/testcase` under `cases/...` or update `SC-*.yaml` |
+| Plan still describes mock-only setup | Set lifecycle / steps for **wire** runtime; remove mock-only `setup` notes |
+
+## Grill sequence
+
+1. Read full `*.bundle.yaml` on docs (post `/update-spec` if spec changed).
+2. Patch `cases/**/TC-*.yaml` — `traceability`, `testMatrix`, `refs`.
+3. `flowgrid cases:check`
+4. `flowgrid audit testcase <TC.yaml> --bundle <bundle>`
+5. `flowgrid cases:gate --strict --docs-root $FLOWGRID_DOCS_ROOT`
+6. `flowgrid cases:render` (hub 5174)
+7. `/grill-testcase` sign-off for scope
+
+## Back to FE
+
+```text
+testcase:gen --id TC-*   # e2e-root
+/test → scoped test:e2e (post-wire)
+/grill-test → audit e2e
+/grill-wire → full convergence chain
+```
+
+## Spec hole (not test-only)
+
+If AC/UX wrong → paste `/docs-hub /update-spec …` — do not invent business rules on tests hub.

package/harness/tests/skills/grill-testcase/SKILL.md

@@ -6,6 +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 `.cursor/extracts/tests-verify-gate.md`, `testcase-plan.md`, and the mode extract matching scope: `grill-screen-tc.md` (one `W-*`), `grill-scenario-flow.md` (`SC-*`), `grill-api-hook.md` (`genType: api-e2e`). After FE wire gaps: also `wire-test-handoff.md`.
 
 # /grill-testcase
 

package/harness/tests/skills/test-api/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 > [!CRITICAL] MANDATORY PRE-FLIGHT
 > **[MANDATORY]** Re-read this `SKILL.md` via file-read tool.
-> **[MANDATORY]** Integration contract SSOT on docs-hub: `surfaces/integrations/`, `01-backend-spec` — skills `/api-integration`, `/grill-integration-spec`.
+> **[MANDATORY]** Contract SSOT on docs-hub: `…/api/<seq>/01-backend-spec.yaml` — `/api-spec` then `/grill-api-spec`.
 
 # /test-api — API hook E2E (tests-docs + codegen)
 
@@ -27,11 +27,11 @@ disable-model-invocation: true
 - **[MANDATORY]** `api.baseUrlEnv` (CI env) + `api.baseURL` fallback; optional `api.defaultHeaders`.
 - **[MANDATORY]** `apiSteps[]`: `method`, `path`, `expectStatus`, optional `body`, `headers`, `expectJson`, `expectBodyContains`.
 - **[MANDATORY]** Human `steps[]` + `testMatrix` (same gate as UI TC).
-- Mirror path: `cases/.../integrations/.../TC-*.yaml` aligned with docs integration leaf.
+- Mirror path: `cases/.../<module>/.../TC-*.yaml` aligned with docs API leaf on the same surface.
 
-Template: `harness/tests/templates/TC.example-api.yaml`.
+Template: hub `_templates/TC.example-api.yaml` or `harness/tests/templates/TC.example-api.yaml`.
 
-Audit: `flowgrid audit testcase <TC.yaml> --bundle <integration.bundle.yaml>` when bundle exists on docs hub.
+Audit: `flowgrid audit testcase <TC.yaml> --bundle <*.bundle.yaml>` when bundle exists on docs hub.
 
 ---
 
@@ -53,7 +53,15 @@ Output (e2e-root): `tests/api-e2e/<module>/<TC-id>.api.spec.ts` — run with Pla
 
 - Fix auth (HMAC, rotating tokens) in generated spec or TC `headers` — do not commit secrets; use env in CI.
 - Hybrid UI → API: run UI spec first (or fixture API) then API spec; share `orderId` via `process.env` / `test.info().attach` / storageState as team convention.
-- Postman/Newman collections remain optional; link via TC tag `contract-postman` (no FlowGrid gen yet).
+## Newman / Postman (optional)
+
+- **[MANDATORY]** FlowGrid SSOT remains `TC-*.yaml` (`api-e2e`) — Newman does **not** replace plan or `cases:gate`.
+- Store partner collections under e.g. `integrations/postman/`; CI: `newman run … -e …`.
+- Tag TC: `contract-postman`; document collection path in `description`.
+- Use Newman when: partner-owned collection, heavy pre-request scripts, or contractual replay — **in addition to** Playwright gen for traceability.
+- Grill cross-flow: same `SC-*` may list UI `TC` (e2e) + API `TC` (api-e2e) — `audit scenario` must cover both screens/API refs.
+
+Extract: `.cursor/extracts/grill-api-hook.md`.
 
 ---
 
@@ -61,5 +69,5 @@ Output (e2e-root): `tests/api-e2e/<module>/<TC-id>.api.spec.ts` — run with Pla
 
 - Author plan: `/testcase` (UI), `/scenario` (SC-*)
 - Grill hub: `/grill-testcase`
-- Docs SSOT: `/api-integration`, `/grill-integration-spec`
+- Docs SSOT: `/api-spec`, `/grill-api-spec`
 - UI E2E after skeleton: `/test` + `testcase:gen`

package/harness/tests/skills/testcase/SKILL.md

@@ -7,6 +7,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 the entire function **`*.bundle.yaml`** (sibling of `ir/` on docs hub) BEFORE authoring any test case. Do not split-read `ir/spec.yaml` + `ir/design.yaml` for coverage traceability.
+> **[MANDATORY]** Read `.cursor/extracts/testcase-plan.md` and golden `TC.example.yaml` from hub `_templates/` (after init) or package `harness/tests/templates/`.
 
 # /testcase — E2E Test Case Authoring (Tests Hub)
 
@@ -91,8 +92,9 @@ disable-model-invocation: true
 - [ ] Function `*.bundle.yaml` read in full (not partial slices).
 - [ ] All `userStories.scenarios` covered by corresponding test cases.
 - [ ] Equivalence Partitioning & Boundary Value Analysis `testMatrix` declared (min/max boundary, regex failure, duplicate 409, double-submit lock, offline preservation).
-- [ ] Scenario markdown (`SC-*.md`) formatted with IEEE 29119 Boundary Analysis Table & Gherkin BDD.
+- [ ] Cross-flow: `refs.scenario` points to existing `SC-*`; per-screen TC still authored via `/testcase` (optional review prose: `SC.example.md` pattern).
 - [ ] `meaning` + `purpose` used for step descriptions.
 - [ ] `id` short; `title` ≤20 chars; `description` is rich and business-meaningful.
 - [ ] YAML syntax valid — no JS expressions in test data values.
 - [ ] Directory structure mirrors docs SSOT path exactly.
+- [ ] `flowgrid cases:render` run so `TC-*.md` exposes steps, testMatrix table, and traceability for QA.

package/harness/tests/templates/TC.example-api.yaml

@@ -1,6 +1,6 @@
 schemaVersion: 2
 id: TC-EXAMPLE-PARTNER-EXPORT
-title: Partner export hook
+title: Partner export
 summary: Ví dụ — đối tác đọc export API sau khi đơn đã sẵn sàng.
 story: |
   Given đơn ORD-EXAMPLE-001 đã được portal xử lý
@@ -38,7 +38,13 @@ steps:
   - Partner gọi GET export với token hợp lệ
   - Hệ thống trả JSON orderId và status
 tags: [integration, partner-api, webhook]
+# contract-postman: integrations/postman/partner-export.json  # optional Newman — see grill-api-hook extract
 automation: automated
+traceability:
+  bundleScreen: API-EXAMPLE-EXPORT-001
+  bundleScenarios: []
+  acceptanceRefs: []
+  actionRefs: []
 dimensions:
   business: [workflow]
   technical: [api]

package/harness/tests/templates/TC.example.yaml

@@ -1,7 +1,10 @@
 schemaVersion: 2
 id: TC-EXAMPLE-VALID
-title: Example flow with valid input should succeed
+title: Valid create flow
 summary: Ví dụ — luồng hợp lệ đi đến trạng thái thành công.
+description: |
+  Member tạo hồ sơ mới với dữ liệu hợp lệ theo ma trận positive_boundary.
+  Kỳ vọng: lưu thành công, thông báo rõ, không mất dữ liệu khi lỗi mạng tạm thời.
 story: |
   Given điều kiện đầu vào hợp lệ và người dùng có quyền
   When thực hiện thao tác nhập liệu và nhấn lưu

package/harness/tests/templates/tpl-testcase-plan.md

@@ -0,0 +1,75 @@
+# Template — Testcase plan (`TC-*.yaml`)
+
+**Mục đích:** SSOT **kế hoạch** kiểm thử (hub tests-docs) → `cases:render` → **user case** trên VitePress (port **5174**) → `testcase:gen` → Playwright (e2e-root).
+
+**Workflow:** [docs/workflows/test.md](../../../docs/workflows/test.md) · Artifact: [docs/artifacts/tests-docs.md](../../../docs/artifacts/tests-docs.md).
+
+---
+
+## Ai đọc gì
+
+| Ai | Đọc | Ghi |
+|----|-----|-----|
+| BA / PO | Docs hub `ir/generated/spec.md` (AC, scenarios) | Không sửa `TC-*.yaml` |
+| QA | Tests hub `TC-*.md` (sau render) + YAML SSOT | `/testcase`, `/scenario` |
+| Dev FE | `TC-*.md` + `ir/design.yaml` (`testIds`) | `/test`, `/grill-test` |
+| Dev BE | `TC` `genType: api-e2e` + docs `01` | `/test-api` |
+
+**Không** sửa tay `TC-*.md` — chỉnh YAML → `flowgrid cases:render`.
+
+---
+
+## Path mirror
+
+```text
+docs: surfaces/<surface>/CMP-*/<NN…>/<slug>/*.bundle.yaml
+tests: cases/<surface>/CMP-*/<NN…>/<slug>/TC-*.yaml
+```
+
+Cross-flow: `scenarios/.../FLOW-<name>/SC-*.yaml` mirror `FLOW-*.md` trên docs.
+
+---
+
+## Golden file
+
+Copy shape từ `harness/tests/templates/TC.example.yaml` (sau init tests hub: `.flowgrid/` hoặc package harness path).
+
+Bắt buộc:
+
+- `schemaVersion: 2`
+- `story` / `description` (ngữ cảnh nghiệp vụ)
+- `testMatrix[]` — facet: `positive_boundary`, `negative_length`, `negative_format`, `negative_duplicate`, `concurrency_double_submit`, `network_interruption`
+- `steps[]` — chuỗi bước QA (string hoặc machine step)
+- `traceability` — `bundleScreen`, `bundleScenarios[]`, `acceptanceRefs[]`, `actionRefs[]` (cho `cases:gate --strict`)
+- `testIds.required` — khớp bundle/design sau split
+- `genType: e2e` | `api-e2e`
+
+---
+
+## Trước khi author
+
+1. Đọc **cả** `*.bundle.yaml` trên docs leaf — không chỉ IR.
+2. Bundle thiếu story/AC → STOP → `/update-spec` trên docs hub.
+3. `flowgrid audit testcase <TC> --bundle <bundle>` sau draft.
+
+## Gate release
+
+```text
+flowgrid cases:check
+flowgrid cases:render
+flowgrid cases:gate --strict --docs-root $FLOWGRID_DOCS_ROOT
+```
+
+---
+
+## Grill — chọn mode
+
+| Mode | Extract / workflow |
+|------|-------------------|
+| Một màn `W-*` | `extracts/grill-screen-tc.md` · [test.md#grill-single-screen](../../../docs/workflows/test.md#grill-single-screen) |
+| Flow dài `SC-*` | `extracts/grill-scenario-flow.md` · [test.md#grill-scenario-flow](../../../docs/workflows/test.md#grill-scenario-flow) |
+| API hook | `/test-api` · `extracts/grill-api-hook.md` · Playwright `testcase:gen:api` (+ Newman tùy chọn) |
+
+## Excel UAT
+
+Excel deliverable **xuất sau** YAML/MD chốt — không SSOT ngược. Xem tests-docs § Excel.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shanyucoder/flowgrid",
-  "version": "0.1.5",
+  "version": "0.1.9",
   "description": "Unified Local MCP Toolkit (Graph, DNA, Docs, Test, Codegen)",
   "type": "module",
   "main": "./dist/index.js",

package/stacks/fastapi.json

@@ -45,6 +45,7 @@
     ]
   },
   "registries": [
+    "registries/be-capabilities.registry.json",
     "registries/codegen.registry.json",
     "registries/unit-test.registry.json",
     "registries/common.registry.json"

package/stacks/laravel.json

@@ -42,6 +42,7 @@
   },
   "registries": [
     "registries/codegen.registry.json",
+    "registries/be-capabilities.registry.json",
     "registries/unit-test.registry.json"
   ],
   "gapSources": [

package/stacks/nestjs.json

@@ -0,0 +1,72 @@
+{
+  "stack": "nestjs",
+  "mode": "brownfield",
+  "commands": {
+    "genDry": [
+      "flowgrid",
+      "api-gen:dry",
+      "--",
+      "--spec",
+      "{spec}"
+    ],
+    "gen": [
+      "flowgrid",
+      "api-gen",
+      "--",
+      "--spec",
+      "{spec}"
+    ],
+    "unitGenDry": [
+      "flowgrid",
+      "api-unit-gen:dry",
+      "--",
+      "--spec",
+      "{spec}"
+    ],
+    "unitGen": [
+      "flowgrid",
+      "api-unit-gen",
+      "--",
+      "--spec",
+      "{spec}"
+    ],
+    "registryValidate": [
+      "flowgrid",
+      "api-registry"
+    ]
+  },
+  "registries": [
+    "registries/be-capabilities.registry.json",
+    "registries/nest-codegen.registry.json",
+    "registries/nest-unit-test.registry.json"
+  ],
+  "gapSources": [
+    "**/generated/HANDOFF.md",
+    "**/generated/UNIT-HANDOFF.md",
+    "**/generated/codegen.manifest.json"
+  ],
+  "specRoots": [],
+  "templates": {
+    "root": "adapters/nestjs/nestgen/templates",
+    "engine": "handlebars",
+    "note": "SSOT in FlowGrid package; product registries at repo root"
+  },
+  "dsl": {
+    "ssot": "product-repo",
+    "lanes": {
+      "be": {
+        "registries": ["registries/nest-codegen.registry.json"],
+        "genKeys": ["genDry", "gen"],
+        "needsTags": ["#needs-endpoint", "#needs-dto"]
+      },
+      "unit": {
+        "registries": ["registries/nest-unit-test.registry.json"],
+        "genKeys": ["unitGenDry", "unitGen"],
+        "needsTags": ["#needs-unit-test"]
+      }
+    }
+  },
+  "vocabularies": {
+    "registryTags": "artifactgraph/lexicon/registry-tags.en.txt"
+  }
+}

package/stacks/nextjs-nest.json

@@ -38,6 +38,7 @@
   },
   "registries": [
     "registries/design.registry.json",
+    "registries/be-capabilities.registry.json",
     "registries/nest-codegen.registry.json",
     "registries/contract-field.registry.json"
   ],

package/stacks/nuxt4-nest.json

@@ -48,6 +48,7 @@
     "registries/design.registry.json",
     "registries/unit-test.registry.json",
     "registries/e2e-test.registry.json",
+    "registries/be-capabilities.registry.json",
     "registries/nest-codegen.registry.json",
     "registries/contract-field.registry.json"
   ],

package/templates/project-skeleton/architecture/03-business-process/FLOW-template.md

@@ -15,6 +15,8 @@ status: "draft"
 
 * **Bối cảnh kích hoạt (Trigger Context):** [Mô tả hoàn cảnh hoặc sự kiện nào khiến quy trình này diễn ra. Ví dụ: Khách hàng yêu cầu đặt hàng, hoặc quản trị viên khởi tạo chiến dịch khuyến mãi...]
 * **Mục tiêu kinh doanh (Business Goal):** [Giá trị kinh doanh hoặc bài toán mà quy trình này giải quyết...]
+* **Chỉ số thành công (Success metrics):** [Đo được nếu có — VD: thời gian xử lý, tỷ lệ lỗi, SLA phản hồi]
+* **Phạm vi không làm (Non-goals):** [Quy trình/phase này cố ý không bao gồm — tránh trùng FLOW khác]
 * **Ma trận Vai trò & Quyền hạn (Role & Permission Matrix):**
   | Tác nhân (Actor) | Vai trò trong Quy trình | Quyền hạn trên Màn hình |
   | :--- | :--- | :--- |

package/templates/project-skeleton/overview/index.md

@@ -1,2 +1,68 @@
-# Product Overview
-Welcome to the product overview.
+---
+status: draft
+owner: product-team
+---
+
+# Product overview (arc42 §1 — Introduction & Goals)
+
+Tài liệu **sản phẩm** cho toàn docs hub: *vì sao* hệ thống tồn tại, *ai* dùng, *phạm vi* operational area. Chi tiết màn/API → `surfaces/`; kiến trúc kỹ thuật → `architecture/`.
+
+## Mục tiêu (Goals)
+
+1. **Giá trị nghiệp vụ** — [Một đoạn: bài toán chính product giải quyết.]
+2. **Đối tượng phục vụ** — [Vai trò / operational area chính.]
+3. **Nguyên tắc sản phẩm** — [VD: một SSOT docs, trace `W-*` / `API-*`, grill trước codegen.]
+
+## Stakeholders
+
+| Vai trò | Mục đích đọc overview |
+| --- | --- |
+| PO / BA | Phạm vi, persona, operational area |
+| Dev / QA | Boundary module, link `CMP-*` |
+| Leadership | Goals + success metrics cấp product |
+
+## Top quality goals (arc42)
+
+| # | Thuộc tính | Mục tiêu (đo được nếu có) |
+| --- | --- | --- |
+| 1 | Khả dụng | [VD: uptime SLA nội bộ] |
+| 2 | Bảo mật | [VD: RBAC trên admin portal] |
+| 3 | Khả năng mở rộng | [VD: multi-tenant / module mới không phá SSOT] |
+| 4 | Khả năng bảo trì | [VD: spec bundle + split + audit] |
+| 5 | Trải nghiệm | [VD: affordance UX portal chuẩn] |
+
+## Personas (tóm tắt)
+
+- **[Persona A]** — [Một câu: nhu cầu chính trên surface nào.]
+- **[Persona B]** — […]
+
+Leaf `userStories.primary.asA` **tham chiếu** persona ở đây (không copy persona dài trên từng màn).
+
+## Phạm vi & không làm (product-level)
+
+**In scope (overview):**
+
+- [Operational area / surface được document trong hub này]
+
+**Non-goals (product-level):**
+
+- [VD: không mô tả hạ tầng chi tiết — xem `architecture/`]
+- [VD: không thay quy trình UAT Excel deliverable — xem tests-docs]
+
+## Success metrics (product-level)
+
+- [Chỉ số đo được cấp product — VD: thời gian onboard member đọc SSOT, % leaf có audit sạch trước test lane]
+
+## Operational areas
+
+Mỗi area một file dưới `overview/operational-areas/` — dùng [`_template.md`](./operational-areas/_template.md).
+
+| Area | File |
+| --- | --- |
+| [Tên area] | `operational-areas/<slug>.md` |
+
+## See also
+
+- Surfaces SSOT: `surfaces/`
+- Architecture: `architecture/01-introduction/`
+- Workflow Design: `platform` hoặc `docs/workflows/design.md` (khi publish site)

package/templates/project-skeleton/overview/operational-areas/_template.md

@@ -0,0 +1,37 @@
+---
+id: OA-TEMPLATE
+title: "Tên operational area"
+status: draft
+surfaces: ["admin-web"]
+---
+
+# Operational area: [Tên]
+
+**Mục đích:** [Một đoạn — bối cảnh vận hành: ai làm việc gì, trên kênh nào.]
+
+## Personas trong area
+
+| Persona | Mô tả ngắn | Surface chính |
+| --- | --- | --- |
+| [VD: Nhân viên vận hành] | [Nhu cầu] | `admin-web` |
+
+## Phạm vi nghiệp vụ
+
+- **In scope:** [Quy trình / module thuộc area]
+- **Out of scope:** [Chuyển sang area khác hoặc phase sau]
+
+## Success metrics (area)
+
+- [Metric 1 — đo được]
+- [Metric 2]
+
+## Liên kết module
+
+| CMP | Mô tả |
+| --- | --- |
+| `CMP-XX-…` | [Boundary một dòng] |
+
+## Non-goals
+
+- [Không document chi tiết deployment — `architecture/07-deployment/`]
+- [Không duplicate FLOW kỹ thuật — `architecture/03-business-process/`]

package/templates/project-skeleton/qa/README.md

@@ -1,11 +1,7 @@
-# QA inbox (docs hub)
+# QA inbox
 
-Open customer / choice / tech-debt questions live here — **not** in `*.bundle.yaml`.
+One file per case: `qa/<SHORT>_0001.yaml`.
 
-- One file per open issue: `qa/open/QA-<bundle.id>-NNNN.yaml`
-- `bundle.id` is the screen leaf id from `/spec` (e.g. `cmp-adm-002-02-01-02`)
-- Sequence is **per screen** (`0001`, `0002`, …). Different screens never share a counter.
-- Close with **`/qa-resolve QA-<bundle.id>-NNNN`** plus the decision (skill deletes the file).
+After `flowgrid init`, copy from `.flowgrid/templates/qa-item.yaml` and follow `.flowgrid/templates/qa-authoring.md`.
 
-Template: `.flowgrid/templates/qa-item.yaml`  
-Rules: `.cursor/extracts/qa-inbox.md`
+Append-only `updates[]` · `flowgrid render` refreshes `index.md`.

package/templates/project-skeleton/surfaces/common/data-model/index.md

@@ -1,6 +1,14 @@
 # Data model
 
-Shared domain notes (MD). Entity detail for a feature still belongs in that feature’s Code bundle `spec.entities`.
+Shared domain notes (MD) — **bổ trợ** ERD; không thay `common/db-erd.md`.
+
+| Artifact | Vai trò |
+|----------|---------|
+| [`../db-erd.md`](../db-erd.md) | **ERD tổng** (Phase 0, skill `/db-erd`) — Mermaid, entity, ownership |
+| File này + topics | Policy prose (`#derived-data`, journey links) |
+| Leaf `*.bundle.yaml` | **Chi tiết màn:** `spec.entities` + `design.sections[].db` → `ir/design.yaml` |
+
+Workflow: [architecture-data.md](/docs/workflows/architecture-data.md) (path hub khi publish).
 
 ## Topics
 
@@ -9,7 +17,7 @@ Shared domain notes (MD). Entity detail for a feature still belongs in that feat
 ## Journeys vs ER
 
 Runtime sequences live under [`architecture/06-runtime/journeys/`](/architecture/06-runtime/) (`FLOW-*`).  
-When a journey persists data, **link** the relevant entity here or in the owning `CMP-*/code` bundle — **do not** paste ER diagrams into every sequence.
+When a journey persists data, **link** the entity in **`db-erd.md`** — **do not** paste ER diagrams into every sequence or every bundle.
 
 | Journey | Data notes |
 |---------|------------|

package/templates/schemas/qa-item.schema.json

@@ -0,0 +1,98 @@
+{
+  "$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}$",
+      "description": "Same as filename without .yaml — SHORT_NNNN"
+    },
+    "screen": {
+      "type": "string",
+      "description": "W-* or bundle page-id for humans and split matching"
+    },
+    "bundleId": {
+      "type": "string",
+      "description": "Legacy QA-<bundleId>-NNNN prefix; optional when screen/target.path enough"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["open", "closed"]
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["customer", "choice", "tech-debt", "integration", "coverage"]
+    },
+    "skill": {
+      "type": "string",
+      "description": "Skill that opened the gap — spec, grill-dev, api-spec, …"
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "target": {
+      "type": "object",
+      "required": ["path", "at"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Repo-relative path to bundle or 01-backend-spec.yaml"
+        },
+        "at": {
+          "type": "string",
+          "description": "YAML pointer — field gets #missing_info <id> until resolve"
+        }
+      }
+    },
+    "options": {
+      "type": "array",
+      "description": "Optional AskQuestion options captured when opening (audit trail)",
+      "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}$",
+          "description": "YYYYMMDD HH:mm (team TZ)"
+        },
+        "by": { "type": "string" },
+        "kind": {
+          "type": "string",
+          "enum": ["question", "answer", "review", "note"]
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/templates/shared/api-03-mock.stub.yaml

@@ -0,0 +1,14 @@
+# Copy to api/<seq>/03-mock.yaml when prototype/wire needs samples (optional).
+version: 1
+feature: feature-slug
+endpoints:
+  feature.search:
+    samples:
+      - status: 200
+        description: "List success — replace with realistic payload"
+        body:
+          data: []
+          meta:
+            page: 1
+            perPage: 20
+            total: 0

package/templates/shared/backend-api.bundle.yaml

@@ -1,3 +1,6 @@
+# LEGACY: portal-feature-bundle with nested spec.api — do NOT use for new 01 files.
+# New API contract SSOT: api/<seq>/01-backend-spec.yaml from backend-api.yaml + tpl-api-contract.md
+
 schema: portal-feature-bundle/v1
 id: role-domain-function
 title: Feature API

package/templates/shared/backend-api.yaml

@@ -1,3 +1,7 @@
+# SSOT shape for api/<seq>/01-backend-spec.yaml (NOT the screen bundle).
+# Authoring guide: tpl-api-contract.md · Sample only — copy/adapt per leaf.
+# Portal screen bundle: feature.bundle.yaml — do NOT embed spec.api here.
+
 feature:
   id: feature-slug
   title: Feature Title

package/templates/shared/be-capabilities.registry.base.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "description": "BE base capabilities (auth, exceptions, shared helpers) indexed for DSL / ArtifactGraph. flowgrid registry:sync",
+  "capabilities": {},
+  "middleware": [],
+  "exceptionHandlers": [],
+  "helpers": []
+}