@shanyucoder/flowgrid 0.1.0

package/harness/docs/schemas/flowgrid-process/missing-optional-event.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://platform.local/schemas/flowgrid-process/missing-optional-event.schema.json",
+  "title": "FlowGrid bộ process missing optional accelerator event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "event",
+    "package",
+    "runId",
+    "optional",
+    "reason",
+    "fallback",
+    "metrics"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1.0.0" },
+    "event": { "const": "flowgrid.missing-optional" },
+    "package": { "const": "@platform/flowgrid-process" },
+    "runId": { "type": "string", "minLength": 1 },
+    "optional": { "type": "string", "minLength": 1 },
+    "reason": {
+      "enum": ["not-configured", "unavailable", "invocation-failed"]
+    },
+    "fallback": {
+      "enum": ["targeted-local-search", "model-analysis"]
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fileReads", "contextBytes"],
+      "properties": {
+        "fileReads": { "type": "integer", "minimum": 0 },
+        "contextBytes": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,140 @@
+---
+name: adopt
+description: "/adopt — Scan legacy repositories and generate a high-level index mapping catalog & common candidates at root."
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /adopt — Legacy Adoption Index & Common Discovery
+
+**Audit Interlock:** Run `flowgrid audit legacy <target-id>`. Consume JSON gap report to verify mapping or prompt member if index is missing.
+
+---
+
+## Rule: Pre-Scan Mode Selection (AskQuestion Wizard)
+
+- **[MANDATORY]** At the start of `/adopt`, the Agent **MUST** prompt the Member via `AskQuestion` wizard (or read from command flags) to select the scan mode:
+  - **Option 1 (Recommended):** `(Recommended) Scan Index + Analyze & Propose Common Catalog (Auto-detect code duplication, propose Common UI/API/DTO candidates to prevent copy-pasting in new system)`
+  - **Option 2:** `Index Only (Basic adoption-inventory.md mapping)`
+
+---
+
+## Rule: Purpose & Output
+
+- **[MANDATORY]** Output: single `adoption-inventory.md` file created directly at workspace root.
+- **[MANDATORY]** Content: clean bullet-point index mapping surfaces, modules, screens, APIs to legacy file paths.
+- **[MANDATORY when Common Mode selected]**: Include **Common Catalog Candidates (`CMN-*`)** section capturing duplicated code/UI patterns caused by legacy copy-pasting habits.
+- **[STRICTLY FORBIDDEN]** Do NOT generate full spec details, diagrams, or tables inside inventory file. This is a reference index & common catalog map.
+
+---
+
+## Rule: Common Discovery & Anti-Copy-Paste Guard
+
+- **[MANDATORY when Common Mode selected]**: During legacy code scan across routers, controllers, view components, and services, the Agent **MUST analyze and detect duplicate patterns**:
+  1. **UI Commons (`CMN-UI-*`)**: UI patterns duplicated across screens (e.g. Search Filter Toolbar, Bulk Action Bar, Status Badge Pill, Confirmation Modal, DateRangePicker, Address Cascader...).
+  2. **API/Service Commons (`CMN-API-*`)**: Controller/Service logic duplicated across endpoints (e.g. Audit Logging Interceptor, Paging/Sorting Wrapper, Excel Export Engine, Custom Exception Handler, JWT Token Resolver...).
+  3. **DTO/Data Commons (`CMN-DTO-*`)**: Duplicated DTOs/Entities (e.g. BaseAuditableEntity, AddressDTO, UserSessionHeader, StandardApiResponse...).
+- **[ANTI-COPY-PASTE GUARD - NEW DEVELOPMENT]**:
+  - Legacy code remains untouched unless explicitly requested.
+  - When creating new specs or developing new features (`/spec`, `/codegen`), **STRICTLY FORBIDDEN to copy-paste legacy code/specs into isolated new files**.
+  - Agent & Member **MUST reference and inherit `CMN-*` entries from the Common Catalog** to author reusable Common Specs and Common Code for the new project.
+- **[EXCEPTION - WHOLE PAGE DUPLICATION HANDLER]**:
+  - If 2 or more page files are near-identical whole-file copies (e.g. `CreateUser.tsx` vs `EditUser.tsx` or duplicated CRUD forms):
+  - ❌ **DO NOT CREATE a `CMN-*` ID for an entire page** (building a common component for a full page is over-engineered anti-pattern).
+  - ✅ **LOG A WARNING** in `adoption-inventory.md` under `### Whole Page Duplication Warnings`.
+  - Recommend combining them into a single polymorphic spec (`mode: create | edit`) during `/spec` authoring.
+
+---
+
+## Rule: Common Implementation Plan & Execution Pipeline
+
+- **[MANDATORY when Common Candidates volume is high (≥5 items)]**:
+  - Agent **MUST** create a `common-plan.md` at workspace root, partitioning all `CMN-*` items into **manageable execution Phases (3–5 common candidates per phase)** for member approval.
+- **[3-Step Standard Execution Pipeline per Common Candidate]**:
+  - For each approved `CMN-*` item in the plan, Agent executes a closed-loop 3-step pipeline:
+    1. **Step 1: Common Spec (`common-spec`)**: Generate standardized Spec document (`common/specs/CMN-*.yaml` or `.md`), defining Props, Inputs/Outputs, Exception handling, and DSL Contract.
+    2. **Step 2: Common Code Generation (`codegen common`)**: Generate production code inside the new project's shared/common directory (`shared/components/`, `shared/services/`, `shared/utils/`).
+    3. **Step 3: DSL Registration**: Register `CMN-*` into FlowGrid DSL Registry. When generating specs or code for any future screen using this feature, Codegen Engine **automatically links & imports Common Code** without code duplication.
+
+---
+
+## Rule: Scan Sources
+
+- **[MANDATORY]** Read repo list from `legacy-repos.local.json` (or `core-repos.local.json` / `platform-repos.local.json`).
+- **[MANDATORY]** If called with scope (e.g. `/adopt "Customer App"` or `/adopt admin-fe`) → scan only that app/module.
+- **[MANDATORY]** Scan: Router, Controllers, View/Page Components, Service Interfaces to extract:
+  - **Surfaces**: Application and channel names (Admin Portal, Customer Web, Gateway…)
+  - **Modules (`CMP-*`)**: Primary feature groups (Auth, Orders, Profile…)
+  - **Screens (`W-*`) & APIs (`API-*`)**: UI screens + API endpoints with legacy file paths (`ID → Legacy File Path`)
+  - **Cross-Flow Candidates (`FLOW-*`)**: Business flows spanning multiple screens or services
+  - **Common Candidates (`CMN-UI-*`, `CMN-API-*`, `CMN-DTO-*`)**: (If Common Analysis mode selected)
+
+---
+
+## Rule: ID Standardization
+
+- **[MANDATORY]** All items MUST use standardized IDs: `CMP-*`, `W-*`, `API-*`, `FLOW-*`, `CMN-UI-*`, `CMN-API-*`, `CMN-DTO-*`.
+- **[MANDATORY]** Every ID MUST map to its corresponding legacy file or directory path.
+  - ✅ `W-AD-AUTH-001: Login → admin-fe/src/pages/Login.tsx`
+  - ✅ `CMN-UI-001: Filter Toolbar → duplicated in admin-fe/src/pages/Orders.tsx, Users.tsx`
+
+---
+
+## Output Structure Format
+
+```markdown
+# Core Adoption Inventory (Legacy Scan & Common Catalog)
+
+> **Scan Date**: YYYY-MM-DD | **Sources Config**: `legacy-repos.local.json` | **Common Analysis**: [Enabled / Disabled]
+
+## 1. Surfaces
+- **Admin Portal** (`surfaces/admin`) → Legacy repo: `admin-fe`
+
+## 2. Modules Catalog (`CMP-*`)
+- **CMP-ADM-001**: Auth & Identity Management → Legacy: `admin-fe/src/modules/auth/`
+
+## 3. Screens & API Function Inventory (`W-*`, `API-*`)
+### Admin Portal (`surfaces/admin/CMP-ADM-001`)
+- **W-AD-AUTH-001**: Login → Legacy: `admin-fe/src/pages/Login.tsx`
+- **API-ADM-AUTH-01**: Auth Services → Legacy: `auth-service/src/controllers/AuthController.java`
+
+## 4. Cross-Flow Candidates (`FLOW-*`)
+- **FLOW-checkout**: Checkout & Payment Flow → across `CMP-ADM-002` & `CMP-CUS-001`
+
+## 5. Common Catalog Candidates (Anti-Copy-Paste Guard)
+> **Purpose**: Reuse for specs and code of new features / spec updates.
+
+### UI Commons (`CMN-UI-*`)
+- **CMN-UI-001**: Advanced Search & Filter Toolbar → Duplicated in: `admin-fe/src/pages/Orders.tsx`, `Users.tsx`
+- **CMN-UI-002**: Confirm Action Modal → Duplicated in: `admin-fe/src/components/*`
+
+### API & Service Commons (`CMN-API-*`)
+- **CMN-API-001**: Paging Response & Dynamic Sorting Wrapper → Duplicated in: `OrderController.java`, `UserController.java`
+- **CMN-API-002**: Audit Logging Interceptor → Duplicated in: `auth-service`, `order-service`
+
+### DTO & Data Commons (`CMN-DTO-*`)
+- **CMN-DTO-001**: Base Auditable & Soft-Delete Entity → Duplicated across 8 Entities
+
+### ⚠️ Whole Page Duplication Warnings
+> **Note**: Do not create `CMN-*` for full pages. Recommend consolidating into a single polymorphic spec (`mode: create | edit`).
+- **W-AD-USER-001 (Create User)** & **W-AD-USER-002 (Edit User)**: 95% identical → *Recommendation: Consolidate into single Form Spec `CMP-ADM-USER-FORM`*
+
+---
+## 6. Handoff Usage Guide
+- `/legacy /spec W-AD-AUTH-001` — spec a legacy screen (MUST reuse CMN-* if applicable)
+- `/legacy /business-process FLOW-checkout` — map a legacy flow
+```
+
+---
+
+## Verification Checklist
+
+- [ ] AskQuestion wizard triggered for mode selection (Index Only vs Index + Common Discovery).
+- [ ] Audit script run; index checked or gaps reported.
+- [ ] `adoption-inventory.md` created directly at workspace root.
+- [ ] All items use standardized `CMP-*`, `W-*`, `API-*`, `FLOW-*`, `CMN-*` IDs.
+- [ ] Common Catalog Candidates listed with source files if Common mode selected.
+- [ ] Anti-Copy-Paste Guard enforced for new spec/code.

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

@@ -0,0 +1,40 @@
+---
+name: api
+description: EXCLUSIVE /api — Backend Router ONLY. Immediately routes to /api-spec or /api-integration without generating gross files.
+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]** Check for `01-backend-spec.yaml`, `approval.status`, and `feature.source.kind` before routing.
+
+# /api — Backend Router
+
+---
+
+## Rule: Routing Table
+
+- **[MANDATORY]** Always delegate — never generate content directly from this skill:
+
+  | 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` |
+  | 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`) |
+  | `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>/`.
+- **[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.
+
+Doc: `docs/operational/TEAM-AI-BACKEND-WORKFLOW.md`
+
+---
+
+## Verification Checklist
+
+- [ ] Checked `01-backend-spec.yaml` presence, `approval.status`, and `feature.source.kind`.
+- [ ] Correctly routed to contract skills vs bộ code BE `/api`.
+- [ ] Did NOT generate any content from this routing skill.

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

@@ -0,0 +1,110 @@
+---
+name: api-integration
+description: EXCLUSIVE /api-integration — ONLY for backend integration contracts (partner APIs, webhooks). DO NOT merge multiple integrations into single markdown files.
+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.
+
+# /api-integration — Integration Contract (no Portal FE)
+
+Shared extracts: `api-integration-spec.md`, `entity-relationship.md`, `call-external.md`, `agent-discipline.md`, `verify-gate.md`
+
+---
+
+## Rule: When to Use (vs `/api-spec`)
+
+- **[MANDATORY]** Use `/api-integration` for: inbound/outbound webhooks, REST APIs exported to partners/3rd parties, public APIs with dedicated versioning, reverse-engineering legacy handlers or provider OpenAPI specs.
+- **[STRICTLY FORBIDDEN]** If a Portal FE spec exists for the same user journey → use `/api-spec`, not this command.
+
+---
+
+## Rule: Audit Interlock
+
+- **[MANDATORY]** If an integration bundle already exists: run an audit before making modifications.
+  - ✅ Check for existing endpoints under `surfaces/integrations/` using `flowgrid_docs_route` or glob search before authoring a new contract trio.
+  - ❌ Never re-define routes that already exist; link and reuse them.
+
+---
+
+## Rule: Missing Information Handling & Workload Threshold (Law 2)
+
+- **[MANDATORY]** When signature verification, retry policy, or retention policy is unknown, evaluate total missing volume:
+  - **Small Scope (≤5 questions):** Trigger `AskQuestion` wizard — one question at a time, **≥3 options**: (1) `(Recommended)`, (2) `Other` (free text), (3) `Log as Tech Debt (Pending)`.
+  - **Large Scope (≥10 gaps/endpoints):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 endpoints/gaps per phase) with disk offloading at boundaries.
+  - ✅ If "Log as Tech Debt" is selected → create `qa/open/QA-<feature.id>-NNNN.yaml`. Set `integrationBacklog[]` (NOT portal `pendingTechDebt`).
+  - ❌ Never write `openQuestions` in YAML. Never invent HMAC secrets or partner-specific validation logic.
+
+---
+
+## Rule: Folder Structure
+
+- **[MANDATORY]** Every integration contract must be placed under:
+  ```
+  surfaces/integrations/<provider>/<slug>/api/<seq>/
+  ├── 01-backend-spec.yaml    # feature.source.kind + integrationRefs (tech SSOT)
+  ├── 02-openapi.yaml         # generated by: flowgrid openapi_gen --spec <01>
+  └── 03-mock-data.yaml
+  ```
+- **[MANDATORY]** One `01` = one primary domain entity. Never dump all provider actions into one single file.
+- **[STRICTLY FORBIDDEN]** Never write `.md` directly. Never combine multiple integrations into one gross monolithic file.
+
+---
+
+## Rule: Explicit URI Naming
+
+- **[MANDATORY]** All integration endpoints MUST use explicit action suffixes:
+  - Inbound webhook: `POST /api/v1/integrations/<provider>/webhook`
+  - Inbound event action: `POST /api/v1/integrations/<provider>/{id}/sync` (or `/receive`)
+  - Outbound partner API: `POST /…/create`, `PUT /…/{id}/update`
+- **[STRICTLY FORBIDDEN]** Never use ambiguous RESTful routes lacking explicit action semantics.
+
+---
+
+## Rule: Integration Error Handling
+
+- **[MANDATORY]** Document explicit error responses using `#err:*` tags for:
+  - `#err:unauthorized` — invalid API key / expired token
+  - `#err:signature-invalid` — HMAC signature mismatch on webhook
+  - `#err:rate-limit` — partner throttling limit reached
+  - `#err:validation` — malformed payload
+  - `#err:system` — internal processing failure
+- **[RECOMMENDED]** Global errors (500/503/401) → delegate to OpenAPI `$ref` schemas; do NOT duplicate across each endpoint.
+- **[MANDATORY]** Provide partner-facing error code mappings in both `01-backend-spec.yaml` and `02-openapi.yaml`.
+
+---
+
+## Rule: YAML & Tagging
+
+- **[MANDATORY]** Configure: `feature.source.kind`, `base: none`, `integrationRefs[]`, empty `portalRefs`, `contexts.portalLayout: none`, and `contexts.auth` (API key / HMAC / OAuth).
+- **[MANDATORY]** Use domain tags only: `#webhook-inbound`, `#webhook-outbound`, `#partner-api`, `#public-api`, `#call-external`, `#err:*`.
+- **[STRICTLY FORBIDDEN]** No `codegen`, no `#gen:*`, no `approval` beyond `draft` — specialized grill handles those downstream.
+- **[MANDATORY]** All strings with `:` in YAML must be double-quoted.
+
+---
+
+## Workflow
+
+1. Configure source metadata: `feature.source.kind`, `base: none`, `integrationRefs[]`.
+2. Scan `surfaces/integrations/` for existing endpoints; apply reuse if found.
+3. Set `contexts.portalLayout: none`; document `contexts.auth`.
+4. Inventory events/endpoints from provider documentation or legacy source — mark `inferredFromCode` in `notes`.
+5. Specify entities, idempotency keys, deduplication, and raw payload retention policies in `decisions` / `beOnlyRequirements`.
+6. Author `api.endpoints` with explicit action URIs.
+7. Apply integration error storming `#err:*` tags.
+8. Run `flowgrid openapi_gen --spec …/api/<seq>/01-backend-spec.yaml` → generates `02-openapi.yaml`.
+9. Author mock data (representative webhook payload JSON + acknowledgement response).
+10. Run AskQuestion wizard for unresolved unknowns (signature, retry, retention).
+11. Update `.harness/progress.md`.
+
+---
+
+## Verification Checklist
+
+- [ ] Folder structure: contract trio located under `surfaces/integrations/<provider>/<slug>/api/<seq>/`.
+- [ ] `01-backend-spec.yaml`, `02-openapi.yaml`, `03-mock-data.yaml` all generated and populated.
+- [ ] Partner-facing error codes and `#err:*` tags fully documented.
+- [ ] Explicit URI action suffixes strictly applied.
+- [ ] No `.md` authored directly. No gross monolithic files created.
+- [ ] All YAML strings containing `:` are double-quoted.

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

@@ -0,0 +1,136 @@
+---
+name: api-spec
+description: EXCLUSIVE /api-spec — ONLY for authoring backend API contract YAML trio per function slug under surfaces/. DO NOT merge multiple modules into single markdown files.
+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.
+> 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`.
+
+# /api-spec — Backend API Contract
+
+**SSOT:** `…/api/<seq>/01-backend-spec.yaml` only. Do **not** write `bundle.spec.api`.
+
+Shared extracts: `spec-evolution.md`, `api-spec-sync.md`, `entity-relationship.md`, `derived-data.md`, `agent-discipline.md`, `verify-gate.md`.
+
+Hashtag extracts: `#call-external` → `call-external.md`; `#cross-entity-service` → `cross-entity-service.md`.
+
+---
+
+## Rule: Audit Interlock
+
+- **[MANDATORY]** Always run static audit first: `flowgrid audit api <target-api.bundle.yaml>`.
+  - ✅ Consume JSON gap report to fix issues or trigger AskQuestion wizard (≥3 options).
+  - ❌ Do not skip audit and proceed to authoring directly.
+
+---
+
+## Rule: Missing Information Handling & Workload Threshold (Law 2)
+
+- **[MANDATORY]** When API facts are unknown or ambiguous, evaluate total missing volume:
+  - **Small Scope (≤5 questions):** Trigger `AskQuestion` wizard — one question at a time, **≥3 options**: (1) `(Recommended)`, (2) `Other` (free text), (3) `Log as Tech Debt (Pending)`.
+  - **Large Scope (≥10 gaps/endpoints):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 endpoints/gaps per phase) with disk offloading at boundaries.
+  - ✅ If member selects "Log as Tech Debt" → create `qa-inbox.md` entry `QA-<feature.id>-NNNN`. Set `pendingTechDebt[].id` to same ID.
+  - ❌ Never write `openQuestions` in YAML. Do not invent endpoint logic.
+
+---
+
+## Rule: API Reuse (Search Before Creating)
+
+- **[MANDATORY]** Before creating any new contract trio, scan in hierarchical order:
+  1. Sibling screens on this `CMP-*`: `surfaces/<surface>/CMP-*/<NN…>/api/<seq>/`
+  2. LCA `common/yaml/` (cluster → module → surface → global)
+  3. Other modules on the same surface
+- **[MANDATORY]** If existing `01-backend-spec.yaml` is found for this action: tag `#reuse-api` + `reuseFrom: <path>` on the **page action/item** in `ir/design.yaml`. Do NOT duplicate the contract.
+- **[STRICTLY FORBIDDEN]** Do NOT create `api/<seq>/` folders for `#reuse-api` actions.
+- **[STRICTLY FORBIDDEN]** Do NOT run `openapi:gen` for reused APIs. If every action is `#reuse-api` → zero `api/` folders created.
+- Only author a new trio for **NEW unique** `apiRefs` with no existing `01`.
+
+---
+
+## Rule: Middleware Injection
+
+- **[MANDATORY]** Before authoring: scan `surfaces/<surface>/common/yaml/` and `surfaces/common/yaml/` for common middlewares (auth, rate-limit).
+  - ✅ If found: inject `#middleware: <id>` on endpoint; do not duplicate logic.
+  - ❌ Never duplicate middleware logic in individual endpoint specs.
+
+---
+
+## Rule: Explicit URI Naming
+
+- **[MANDATORY]** All endpoints MUST use explicit action suffixes:
+  - `POST /api/v1/…/create`
+  - `PUT /api/v1/…/{id}/update`
+  - `POST /api/v1/…/{id}/duplicate`
+  - `DELETE /api/v1/…/{id}/delete`
+  - `GET /api/v1/…/{id}/detail`
+  - `GET /api/v1/…/list` or `/search`
+- **[STRICTLY FORBIDDEN]** Never use ambiguous RESTful paths without action suffixes (e.g. bare `PUT /users/{id}`).
+
+---
+
+## Rule: Endpoint Error Storming
+
+- **[MANDATORY]** Apply `#err:*` tags based on endpoint nature:
+  - Endpoint with `{id}` parameter → MUST have `#err:not-found` (404) + `#err:idor-violation` (403 TENANT_IDOR_VIOLATION).
+  - Form submit (POST/PUT) → MUST have `#err:validation` (422) with explicit field rules.
+  - Permission-checked route → MUST have `#err:permission-denied` (403 PERMISSION_DENIED).
+  - Conflict/duplicate actions → MUST have `#err:conflict` (409 RESOURCE_DUPLICATE / STATE_INVALID).
+  - Public/master-data routes with `auth: false` → omit IDOR/auth errors.
+- **[RECOMMENDED]** Global errors (`401`, `503`, `500`) → handled by OpenAPI `$ref: '#/components/responses/…'`; do NOT duplicate per-endpoint.
+
+---
+
+## Rule: Folder Structure
+
+- **[MANDATORY]** Function API trio placed AT the leaf alongside FE bundle:
+  ```
+  surfaces/<surface>/CMP-*/01/01/01/
+    <slug>.bundle.yaml
+    ir/design.yaml / ir/spec.yaml
+    api/01/
+      01-backend-spec.yaml   ← VALID YAML (double-quote all colons)
+      02-openapi.yaml
+      03-mock-data.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.
+- **[STRICTLY FORBIDDEN]** Never write `.md` directly. Never combine multiple modules/screens into one gross monolithic file.
+
+---
+
+## 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]** Domain tags only (`#call-external`, `#cross-entity-service`, `#err:*`). No `#gen:*` or `codegen` block from this skill.
+
+---
+
+## Workflow
+
+1. Identify feature group, module prefix, Platform/Tenant, aggregates, and pivot M-N relationships.
+2. List every action/item from `ir/design.yaml` with `apiRefs` or `#reuse-api`.
+3. Scan sibling + common APIs; apply reuse or create new trio.
+4. Apply explicit URI action suffixes.
+5. Apply error storming `#err:*` per endpoint nature.
+6. Run `flowgrid openapi_gen --spec …/api/<seq>/01-backend-spec.yaml` to generate `02-openapi.yaml`.
+7. AskQuestion wizard for any unresolved unknowns.
+8. Update `.harness/progress.md`.
+
+---
+
+## Verification Checklist
+
+- [ ] Audit script run; all gaps resolved or wizard triggered.
+- [ ] Every action/item is either `#reuse-api + reuseFrom` or has new `api/<seq>/` trio.
+- [ ] No duplicate trio created for reused APIs.
+- [ ] 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.

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

@@ -0,0 +1,82 @@
+---
+name: api-update
+description: EXCLUSIVE /api-update — ONLY for updating/syncing backend contract under surfaces/ when Portal spec changes or BE-only requirements update. DO NOT generate Markdown reports.
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /api-update — Portal Sync & BE-Only Updates
+
+No Laravel code. No `codegen` / `#gen:*` — grill adds those after sync.
+
+Shared extracts: `api-spec-sync.md`, `spec-evolution.md`, `entity-relationship.md`, `derived-data.md`, `agent-discipline.md`
+
+---
+
+## Rule: Modes
+
+- **[MANDATORY]** Select the correct mode from user prompt:
+
+  | Mode | Prompt | Action |
+  |---|---|---|
+  | `portal-sync` (default) | `/api-update <ID or path>` | Diff portal `ir/design.yaml` → patch `01` (+ mock); **regen** `02` via `openapi:gen` |
+  | `be-only` | `/api-update <ID or path> --be-only` | Only `beOnlyRequirements`, `derivedData`, internal validation — do NOT change FE contract |
+
+---
+
+## Rule: ID Resolution & Folder Location
+
+- **[MANDATORY]** If an ID is provided (e.g. `CMP-ADM-000-001`, `W-AD-AUTH-001`) → use `flowgrid_docs_route` or glob to resolve to `…/api/<seq>/01-backend-spec.yaml`. Do NOT force user to provide full filesystem path.
+- **[MANDATORY]** Trio lives under `api/<seq>/` — never adjacent to `*.bundle.yaml`.
+- Common APIs: `…/common/yaml/<slug>/01-backend-spec.yaml` (one trio per API).
+
+---
+
+## Rule: Portal-Sync Workflow
+
+1. **[MANDATORY]** Read entire `ir/design.yaml` (page actions/items, `apiRefs`, `#reuse-api`, `reuseFrom`).
+   - `#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`).
+5. **[MANDATORY]** Bump `feature.version` + add `changeLog` entry.
+6. **[STRICTLY FORBIDDEN]** Never hand-edit `02-openapi.yaml` as SSOT. Never write `.md` directly.
+
+---
+
+## Rule: Missing Information / Unknown Facts
+
+- **[MANDATORY]** External integrations or unknowns → trigger `AskQuestion` wizard, presenting ≥3 options: (1) Recommended, (2) Other, (3) "Log as Tech Debt (Pending)".
+  - ✅ "Log as Tech Debt" → create `qa-inbox.md` entry; close later with `/qa-resolve`.
+  - ❌ Never write `openQuestions` in YAML.
+- Export/import/custom → add endpoint stub + `pendingTechDebt.expectedWhenDone` if not merging this session.
+
+---
+
+## Rule: Guardrails
+
+- **[STRICTLY FORBIDDEN]** Do NOT split slug folder for child functions in the same bounded context.
+- **[STRICTLY FORBIDDEN]** Do NOT rename API fields for FE convenience.
+- **[STRICTLY FORBIDDEN]** No BQA reports, no framework code snippets.
+
+---
+
+## Done Criteria
+
+- Portal delta in `01`; or if deferred: `pendingTechDebt` with `id: QA-<feature.id>-NNNN` + `qa/open/` file.
+- `source.portalRefs` current.
+- `changeLog` + version bumped.
+- Handoff: `/grill-api-spec {slug}` (re-run gates + codegen tags).
+
+---
+
+## Verification Checklist
+
+- [ ] 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`.
+- [ ] `changeLog` + `feature.version` bumped.
+- [ ] No `.md` written directly. No `openQuestions` in YAML.

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

@@ -0,0 +1,57 @@
+---
+name: architecture
+description: /architecture — Routes to child architecture skills based on layer. DO NOT invent topology.
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+> **[MANDATORY]** Use `flowgrid_docs_route`, `flowgrid_docs_list_ids`, or glob search to resolve target path before authoring.
+
+# /architecture — Architecture Router
+
+---
+
+## Rule: Layer → Child Skill Routing
+
+- **[MANDATORY]** Route based on the layer being authored:
+
+  | Layer | Child Skill |
+  |---|---|
+  | 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` |
+  | Module / CMP box | `/module` |
+  | Screen / API detail | `/spec` |
+  | Where it runs / Infrastructure | `/deployment` |
+  | Architectural decisions | `/decision` |
+  | Architecture grill / interview | `/grill` / `/architecture-grill` |
+
+---
+
+## Rule: Architecture vs Business Spec Boundary
+
+- **[MANDATORY]** Architecture = PURELY technical: system topology, internal services, cronjobs, database infrastructure, long cross-cutting technical flows.
+- **[STRICTLY FORBIDDEN]** `architecture/01-introduction` MUST NOT repeat Personas or detailed user use-cases. Mention user entry point lightly then jump to technical system composition.
+- **[STRICTLY FORBIDDEN]** API endpoints and contracts belong to Function detail (`/spec`, `/api-spec`), NOT architecture.
+- **[MANDATORY]** Treat Surfaces as business interaction surfaces (e.g. Admin Portal, Customer Web), not repositories or software projects.
+- **[MANDATORY]** Product Code (`W-*` / `API-*`) stays in `surfaces/<surface>/CMP-*/<slug>/code/`.
+
+---
+
+## Rule: Diagrams
+
+- **[MANDATORY]** Format: MD + Mermaid (`flowchart` or `sequenceDiagram`).
+- **[MANDATORY]** Every Mermaid diagram MUST explicitly model error paths and exception handling (e.g. Redirect on 401/403 IDOR, validation fail states).
+- **[MANDATORY]** Deployment diagrams → C4 `DEP-*` only when physical placement matters. Use a stub by default if placement is not confirmed.
+- One concern per edit.
+
+---
+
+## Verification Checklist
+
+- [ ] Used `flowgrid_docs_route` or `flowgrid_docs_get_element` to locate target element.
+- [ ] Routed to correct child skill.
+- [ ] Architecture boundary respected (no Personas, no UI copy, no API contracts).

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

@@ -0,0 +1,29 @@
+---
+name: architecture-grill
+description: /architecture-grill — Specialized architecture interview/grill for higher-level design; prefer /grill for general layer discovery.
+disable-model-invocation: true
+extractBundle: architecture-core
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
+
+# /architecture-grill — Architecture Interview & Gap Fill
+
+**Scope:** Higher-level design — business flows, context boundaries, and data models above the `Functions` layer.
+
+---
+
+## Rule: When to Use
+
+- **[MANDATORY]** Use `/architecture-grill` when conducting interviews at the architecture level: system boundaries, service responsibilities, data ownership, cross-cutting decisions.
+- **[RECOMMENDED]** For general layer discovery (determining which specific skill to use) → use `/grill` instead.
+
+---
+
+## Rule: Missing Information Handling
+
+- **[MANDATORY]** For any architecture gaps → trigger `AskQuestion` wizard, presenting one question at a time with ≥3 options: (1) Recommended, (2) Alternative, (3) "Log as Tech Debt".
+- **[STRICTLY FORBIDDEN]** Do NOT invent system topology, service ownership, or data models without explicit user confirmation.
+
+**Target Paths:** Applied across architecture layers above `Functions`.