@shanyucoder/flowgrid 0.1.0

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

@@ -0,0 +1,29 @@
+---
+name: legacy
+description: /legacy — Skill Modifier: Shifts source of truth from modern platform to legacy system repositories (legacy archaeology). Used in conjunction with other skills (e.g. /legacy /spec).
+disable-model-invocation: true
+---
+
+# /legacy — Legacy Context Modifier
+
+**Skill Modifier:** When a member uses `/legacy` alongside another specialized skill (e.g., `/legacy /spec`, `/legacy /overview`, `/legacy /business-process`), the Agent MUST enforce the following behavioral shifts.
+
+## Behavioral Shifts (Context Shift)
+
+1. **Shift Source of Truth:**
+   - INSTEAD OF reading modern active repositories (`core-repos.local.json` or legacy `platform-repos.local.json`), the Agent MUST resolve paths from `legacy-repos.local.json` and conduct analysis directly against legacy codebases and documentation.
+
+2. **Archaeology & 2-Tier Audit Mode:**
+   - Do NOT invent novel business logic or assumptions. Your role is strictly "archaeological" — extract, map, and document what ACTUALLY exists in the legacy system.
+   - **Tier 1 (Page / API Detail — `/legacy /spec`)**: 
+     - ONLY audit internal page/API scope: Check **missing Validation** (field validation rules, max length, format regex...) and **Local Security** (e.g. Laravel `@csrf`, Auth guard/middleware on route, input sanitization).
+     - Do NOT perform cross-system end-to-end vulnerability audits at this level.
+   - **Tier 2 (Cross-Flow / Business Process — `/legacy /business-process`, Module, Surface)**:
+     - Audit **End-to-End Business Flow Gaps**: Check data/status misalignment between Step 1 (Screen 1) and Step 2 (Screen 2), orphan APIs/steps, broken flow steps, and missing rollback/confirmation handling on failure.
+
+3. **Metadata Updates (When Applicable):**
+   - For design artifacts (such as YAML bundles produced by `/spec`), apply appropriate legacy metadata (e.g. `specOrigin: legacy`) per guidelines in the base skill.
+   - Always reference `legacy.dynamics.yaml` rather than default structures when specified by the base skill.
+
+**Operational Mechanics (For Agent):**
+This modifier HAS NO independent workflow. It represents supplementary constraints that override or activate "legacy"-specific instructions defined inside the primary `SKILL.md` file (such as `/spec`, `/module`).

package/harness/common/skills/ui-proposal/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: ui-proposal
+extractBundle: ux-common
+description: /ui-proposal — analyze and propose UI gaps after DSL mapping; does not replace /spec or /update-spec.
+disable-model-invocation: true
+---
+
+> [!CRITICAL] MANDATORY PRE-FLIGHT
+> **[MANDATORY]** Re-read this `SKILL.md` via file-read. Do not rely on memory.
+> **[MANDATORY]** Follow rule `flowgrid-ux-common.mdc` (flow, output template, CMN IDs).
+> **[MANDATORY]** Load checklists from `.cursor/extracts/ux-common-patterns.md` (`extractBundle: ux-common`).
+
+# /ui-proposal — UI gap analysis
+
+**Owner:** Common harness.
+
+## Use when
+
+- Member or agent needs **analysis or proposals** for UI affordances (breadcrumb, filters, delete flow, disabled reasons, …) that are **not** mapped in DSL or are under-specified.
+- Supplement `/spec` zone brainstorm — **do not** write bundles on behalf of `/spec` or `/update-spec`.
+
+## Out of scope
+
+| Need | Route |
+|------|--------|
+| Full bundle | `/spec` |
+| Delta bundle | `/update-spec` |
+| Codegen / production UI | `/prototype` or FE skills |

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

@@ -0,0 +1,31 @@
+# Agent execution protocol (bộ docs)
+
+> Canonical **physical interlocks** (full Vietnamese CRITICAL wording):
+> `SSOT_AGENT_PROTOCOL.md` and host `AGENTS.md`.
+>
+> This extract is a short pointer for skills. **Do not** treat the bullets below
+> as a static Verification Checklist for every skill.
+
+## Path / task SSOT
+
+```text
+surfaces/<surface>/CMP-*/<slug>/     # no modules/ segment
+
+```
+
+## Seven interlocks (must follow SSOT_AGENT_PROTOCOL.md)
+
+1. **PRE-FLIGHT:** First action = `{{FLOWGRID_READ_TOOL}}` / read target `SKILL.md`. Never memory.
+4. **NO RAM CACHING:** Durable results → disk immediately. Prior file = next input.
+5. **ZERO BUSINESS HALLUCINATION:** Data only from User prompt or ArtifactGraph. Gaps → AskQuestion (MUST include "Log as Tech Debt" option); if member selects "Log as Tech Debt" → `qa/open/QA-<page-id>-NNNN.yaml` + `#missing_info QA-…`. No invented business fields.
+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.
+
+## Order
+
+```text
+{{FLOWGRID_READ_TOOL}} SKILL.md
+  → durable writes immediately (No RAM)
+  → AskQuestion or qa/open + grill Confirm before SSOT fill
+  → common/DSL only when human-gated
+```

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

@@ -0,0 +1,71 @@
+# Architecture core (arc42 × C4 × Product)
+
+SSOT entry: [`start-now`](../../platform/guide/start-now.md) · [`SYSTEM-DOC-STRUCTURE`](../../platform/guide/SYSTEM-DOC-STRUCTURE.md).
+People / tree: [`platform/guide/start-now.md`](../../platform/guide/start-now.md) · [`SYSTEM-DOC-STRUCTURE.md`](../../platform/guide/SYSTEM-DOC-STRUCTURE.md)
+
+## Operating model (business view)
+
+`overview` → `operational areas` (Admin/Workforce/Shop-floor/Plant) → `business surfaces` → `module` → `function` · optional `FLOW-*`.
+
+Personas/actors and interaction channels are mapped to operational areas. Runtime Portal/Client/API/Gateway remain C4 Containers.
+
+## Layer meaning
+
+- `overview`: PURE business document written in user language. Details personas, business purpose, and operational areas (no internal system tech specs).
+- `surface`: who does what on which channel. Contains Page/UI technical specs (Layout, Component State) and single-API data schemas. NO system-level architecture (backend config, DB schemas).
+- `module`: a cohesive business capability inside a surface.
+- `function`: screen or API detail and contract.
+- `journey`: runtime flow across systems.
+- `Common`: shared scope at the **lowest shared folder** (module/cluster `common/`, then surface, then `surfaces/common`). See `.cursor/extracts/common-scope.md`.
+- `API`: container or contract detail, not a surface.
+
+## Content standards
+
+| Layer | Prose | Diagrams / DB / sequence |
+|-------|-------|---------------------------|
+| Overview · Operational area · Surface · Common · Module+ | **arc42** spirit | **C4** |
+| Function | **C4** | **C4** |
+
+No **dynamics** wording on new trees — use **flow** / `FLOW-*` / `/journey`.
+
+## Technical layers
+
+1. **arc42** — TOC under `architecture/01`…`12` (*why*) — team: prefer §01 + §07 active; rest stub OK
+2. **C4 views** — IDs inside chapters (*what*)
+3. **Product** — `CMP-*` / `W-*` / `API-*` under `surfaces/` hoặc `overview/` (*detail*)
+
+## ID rules
+
+| Prefix | Path | Notes |
+|--------|------|-------|
+| `LND-*` `CTX-*` | `architecture/03-context/` | Overview / landscape + context |
+| `CTR-*` | `architecture/07-deployment/` | (Deprecated in public contract except for deployment) |
+| `FLOW-*` | `architecture/06-runtime/journeys/` | Curated flows (~10–20%) |
+| `DEP-*` | `architecture/07-deployment/` | Optional stub |
+| `ADR-*` | `architecture/09-decisions/` | Not `shared/adr` (redirect) |
+| `CMP-*` `W-*` `API-*` | `surfaces/` hoặc `overview/` | **Do not rename for arc42** |
+
+Not product journeys: `_legacy.dynamics*` · `SC-*`/`TC-*` · `/business-process-trace` (brownfield; `/flow-trace` deprecated alias).
+
+## Format
+
+- Architecture chapters + CMP README: **MD + Mermaid only**
+- YAML only under `surfaces/**/code/`
+- Prefer `sequenceDiagram` (flows) / `flowchart` (CTX/CTR) — **avoid Mermaid `C4Context`**
+- Deployment: stub unless placement matters
+- Reader UX: `vitepress-mermaid-renderer` (zoom/pan) + `vitepress-plugin-mermaid`
+- **No** Mermaid MCP required
+
+## Journey criteria (write when ≥1)
+
+Cross ≥2 systems · hard to understand / regress · slow onboard · core domain.
+Not every agile story.
+
+## Forbidden
+
+- API schemas / UI DSL in `architecture/`
+- Personas or detailed user use-cases in `architecture/` (Architecture is purely technical)
+- Backend load balancers, internal database schemas, or routing internals in `overview/` or `surfaces/`
+- Duplicating Code under `05`
+- AI inventing full prod DEP topology
+- IcePanel/Lucid as SSOT

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

@@ -0,0 +1,15 @@
+# ArtifactGraph — docs hooks
+
+- 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`,
+  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`.
+- Run docs/spec commands only when the current repo explicitly allowlists them.
+- For legacy archaeology, run parity checks and resolve parity drift with member A/B/C.
+- Architecture ID / C4 work stays in bộ docs; ArtifactGraph indexes this repo's
+  registries only and does not wire CodeGraph or follow workspace maps.
+- Promote accepted canonical registry changes here, then rebuild the local index.
+- Keep `/spec`, grill, dynamics, and other docs phase skills owned by the docs repo.

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

@@ -0,0 +1,10 @@
+# ArtifactGraph — parity and context-orphan
+
+- `parity-drift`: create/edit/API labels, validation, type, or empty policies
+  disagree. Present A/B/C and remember the member-confirmed canon.
+- `context-orphan`: an action uses data outside the screen's displayed data
+  scope. Warn only; do not turn it into a confirmation gate.
+- Run `artifactgraph_parity_check` locally and send only unresolved structured
+  findings in a cloud slice.
+
+> **Glossary note:** `context-orphan` ≠ `/context` doc layer; parity `surfaces[]` ≠ Surfaces navigation layer.

package/harness/docs/extracts/business-process-trace.md

@@ -0,0 +1,66 @@
+# Business process trace — step template
+
+Brownfield/cross-system process evidence. Prefer skill **`/business-process-trace`**.
+Curated product journeys: **`/journey`** → `architecture/06-runtime/journeys/` (`FLOW-*`).
+
+## Sections only
+
+`# title` · `## Steps` · `## Diagram` (one mermaid) · `## Gaps` (optional)
+
+## Step types
+
+```
+page [{system}] {route}
+api [{system}] {METHOD} {path}
+call [{from} → {to}] {METHOD} {path} — note
+persist [{system}] {table/model}
+job [{system}] dispatch({ClassName})
+event [{system}] {EventName}
+listener [{system}] {ListenerName}
+command [{system}] {CommandName}
+mail [{system}] template: {relative/path}
+```
+
+Systems: use repo/product ids from evidence. Map roots:
+
+| Step id | Checkout map |
+|---------|----------------|
+| `[mairy-fullsco]`, `[portal]`, `[api]`, … (no `legacy-` prefix) | `platform-repos.local.json` |
+| `[legacy-erp]`, other `legacy-*` | `legacy-repos.local.json` |
+
+Never invent sibling paths. Ambiguous keys → ask or Gaps. Cross-repo with
+missing map/key → Gaps + `/configure-repo-maps` (then `platform-dna codegraph:wire`).
+
+Progressive read only the needed `projects.<id>.root` — no full JSON dump.
+
+## Missing optional accelerators
+
+CodeGraph and other MCP accelerators are optional. Continue with targeted local
+search/read. For each run/optional pair, emit one
+`flowgrid.missing-optional` event (`@platform/flowgrid-process`) after fallback completes. Measure successful
+file reads and exact raw context bytes; deduplicate retries and do not estimate
+tokens. Contract: `.cursor/schemas/flowgrid-process/missing-optional-event.schema.json`.
+
+## Example shape (verify in code)
+
+```markdown
+# Survey notification
+
+## Steps
+1. page [mairy-fullsco] `/admin/surveys/create`
+2. api [mairy-backend] `POST /api/admin/surveys`
+3. call [mairy-backend → mairy-scenario] `POST /api/sync/survey`
+4. job [mairy-backend] `dispatch(SendSurveyThankYouMail)`
+5. mail [mairy-backend] `template: resources/views/emails/survey/thank-you.blade.php`
+
+## Diagram
+\`\`\`mermaid
+sequenceDiagram
+  ...
+\`\`\`
+
+## Gaps
+- Cross-repo hop to [legacy-erp] needs root — run `/configure-repo-maps`
+```
+
+No UI colors/layout. After a curated promote: write/link under `architecture/06-runtime/journeys/` via `/journey`.

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

@@ -0,0 +1,8 @@
+# Codegen readiness (bộ code)
+
+Before `/prototype` or `flowgrid gen`:
+
+- `ir/design.yaml` exists after `flowgrid split`
+- `gen.codegen.profile` set (`list`, `create`, `auth`, `admin-crud`, …)
+- `entity` / `module` populated when profile requires them
+- Run `flowgrid gen:dry` on the FE repo; fix gaps via `/grill-dev` on the docs hub

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

@@ -0,0 +1,65 @@
+# 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.
+
+Numeric function folders stay numeric (`01/02/03/`). The only non-numeric directory names under a `CMP-*` are `common/` and the `CMP-*` id itself.
+
+## 1. Who uses it? → where `common/` lives
+
+Walk consumers (functions / clusters / modules / surfaces). Place `common/` **next to their lowest common ancestor (LCA)**.
+
+| Consumers | Write here |
+|-----------|------------|
+| One function only | **No `common/`.** Keep rules on that function’s `*.bundle.yaml`. |
+| ≥2 functions in the **same cluster** (same numeric prefix, e.g. all under `CMP-…/02/`) | `surfaces/<surface>/<CMP-id>/02/common/` |
+| ≥2 clusters **inside one module** | `surfaces/<surface>/<CMP-id>/common/` |
+| ≥2 modules on **one surface** | `surfaces/<surface>/common/` |
+| ≥2 surfaces | `surfaces/common/` |
+
+**Cluster** = first numeric segment under the module (`02/`, `03/`, …) when the module uses hierarchical IDs. Deeper share (only `02/01/*`) → `…/02/01/common/`.
+
+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)
+```
+
+## 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.
+
+If the same pattern already exists at a **narrower** `common/`, **reuse it** (reference `#pattern` / `#reuse-api`). Promote to a wider `common/` only when the user confirms **new consumers outside** that folder.
+
+## 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/`
+
+Same walk for `patterns/` Markdown.
+
+## 4. Business process (`FLOW-*`)
+
+| Scope of the flow | File |
+|-------------------|------|
+| Org / cross-surface / “hero” catalog | `architecture/03-business-process/FLOW-*.md` (MCP `flowgrid_docs_business_processes`) |
+| Many modules, one surface | `surfaces/<surface>/common/processes/FLOW-*.md` |
+| Whole module, several clusters | `surfaces/<surface>/<CMP-id>/common/processes/FLOW-*.md` |
+| One cluster / submodule only | `surfaces/<surface>/<CMP-id>/<NN>/common/processes/FLOW-*.md` |
+
+Do **not** drop `FLOW-*.md` beside a single `W-*` bundle. Do **not** write module-internal flows only under `architecture/03-business-process/` (optional **link** from the catalog to the product path).
+
+`/db-erd` and `/cross-service` use the **same** `common/` LCA (`common/db-erd.md`, `common/cross-service.md`), not a second invented folder name.
+
+## 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
+- `Surfaces/Common` mixed case when the hub uses `surfaces/`

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

@@ -0,0 +1,22 @@
+# bộ docs — phase hooks
+
+bộ docs is an optional index over Markdown owned by the configured docs repo.
+In consumer repos, that root comes from machine-local `FLOWGRID_DOCS_ROOT`; never
+inspect the current FE/BE/tests repo as if it were the docs hub.
+
+```text
+(1) flowgrid_docs_layout / flowgrid_docs_route / flowgrid_docs_list_ids — narrow scope
+(2) flowgrid_docs_get_element — canonical file and targeted excerpt
+(3) flowgrid_docs_deps_of / flowgrid_docs_dependents_of — reference impact
+(4) flowgrid_docs_orphans / flowgrid_docs_validate_links — catalog health
+```
+
+Use `FLOW-*` and `flowgrid_docs_journeys` for journeys. Keep ADRs in the configured
+arc42 decision home and code-level IDs in the target hub's product tree.
+
+If bộ docs is not connected, continue with targeted Markdown inspection at the
+explicit docs root. To wire it locally from another repo:
+
+```bash
+flowgrid init --location=local --docs-root=/absolute/path/to/docs-hub --yes
+```

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

@@ -0,0 +1,45 @@
+{
+  "version": 1,
+  "package": "@platform/flowgrid-docs",
+  "bundles": {
+    "architecture-core": [
+      ".cursor/extracts/architecture-core.md",
+      ".cursor/extracts/tpl-arc42-chapter.md",
+      ".cursor/extracts/tpl-module.md",
+      ".cursor/extracts/tpl-deployment.md",
+      ".cursor/extracts/tpl-adr.md",
+      ".cursor/extracts/tpl-cross-cutting.md",
+      ".cursor/extracts/common-scope.md"
+    ],
+    "docs-hub": [
+      ".cursor/extracts/docs-phase-hooks.md",
+      ".cursor/extracts/agent-execution-protocol.md",
+      ".cursor/extracts/qa-inbox.md"
+    ],
+    "spec-requirement": [
+      ".cursor/extracts/spec-requirement.md",
+      ".cursor/extracts/agent-execution-protocol.md",
+      ".cursor/extracts/common-scope.md"
+    ],
+    "spec-core": [
+      ".cursor/extracts/spec-core.md",
+      ".cursor/extracts/common-scope.md"
+    ],
+    "bqa-grill": [
+      ".cursor/extracts/grill/validation.md",
+      ".cursor/extracts/agent-execution-protocol.md"
+    ],
+    "dev-grill": [
+      ".cursor/extracts/codegen/readiness.md",
+      ".cursor/extracts/docs-mark-detect.md"
+    ],
+    "grill-docs": [
+      ".cursor/extracts/grill-docs-reconcile.md",
+      ".cursor/extracts/grill/validation.md"
+    ],
+    "update-spec": [
+      ".cursor/extracts/update-spec-delta.md",
+      ".cursor/extracts/qa-inbox.md"
+    ]
+  }
+}

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

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "package": "@platform/flowgrid-process",
+  "bundles": {
+    "business-process-trace": [
+      ".cursor/extracts/business-process-trace.md"
+    ],
+    "flow-trace": [
+      ".cursor/extracts/business-process-trace.md"
+    ]
+  }
+}

package/harness/docs/extracts/grill/validation.md

@@ -0,0 +1,9 @@
+# Grill validation (bộ docs)
+
+Deterministic gates before marking a bundle grill-approved:
+
+- `flowgrid split` / `flowgrid check` on the target `*.bundle.yaml`
+- `flowgrid render` when human-readable spec must be reviewed
+- Page type / `codegen.profile` must match skill workflow (`/grill-bqa`, `/grill-dev`)
+
+Do not write SSOT until the member confirms grill recommendations in chat.

package/harness/docs/extracts/grill-docs-reconcile.md

@@ -0,0 +1,5 @@
+# Grill docs reconcile (/grill-docs)
+
+Use only when **BQA and Dev grills disagree** on the same bundle. Reconcile in chat, then patch bundle + `flowgrid split`.
+
+Not a substitute for `/grill-bqa` or `/grill-dev` alone.

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

@@ -0,0 +1,36 @@
+# QA inbox — deferred questions (docs hub)
+
+There is **no** `openQuestions` on YAML. Gaps use **AskQuestion** in the skill session.
+
+## Wizard (always)
+
+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 **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`.
+
+## Close (`/qa-resolve`)
+
+Prompt: `/qa-resolve QA-<page-id>-NNNN` plus the **solution** on the following lines.
+
+That is Confirm — do **not** AskQuestion again. Skill patches `target.path`, deletes this file, gỡ tag / `pendingTechDebt`, `flowgrid split` (and `openapi:gen` if 01).
+
+Unknown answer → grill / `/api-spec`, not this extract.
+
+## 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.
+
+## Not this folder
+
+- ADR → `architecture/09-decisions`
+- Lasting product risk → `architecture/11-risks`

package/harness/docs/extracts/risk-classes.md

@@ -0,0 +1,69 @@
+# Risk classes checklist
+
+Use with [SKILL.md](SKILL.md). Tick each class against the vertical + horizontal maps.
+
+## AuthZ / IDOR
+
+- [ ] Resource by id checked against current tenant (`storeId` / `hotel_id` from trusted source)
+- [ ] Body/query `store_id` cannot switch store context for another hotel
+- [ ] Admin/batch skip of ownership is intentional and not reachable from store UI JWT
+- [ ] Report/filter/list-by-ids rejects foreign ids (404), not only empty data
+
+## Request bag / contract
+
+- [ ] ID lists use **named keys** (`ids`, `arrId`, `survey_ids`, `scenarioList`) — not bare `[1,2]` → `0=1`
+- [ ] `$request->all()` / `query()` not treated as “array of business ids”
+- [ ] Middleware `merge` fields (`store_id`, `storeId`, …) stripped or unused when parsing id lists
+- [ ] Allowlist vs denylist clear for context keys vs business keys
+
+**Context denylist (typical after ScenarioAuthentication):**  
+`store_id`, `storeId`, `service_id`, `serviceId`, `m_service_id`, `isAdmin`, `apiKey`, pagination/date noise if normalizing “all numbers”.
+
+**ID allowlist (prefer):**  
+`ids`, `arrId`, `survey_ids`, `scenario_ids`, `scenarioList`
+
+## Trust boundary / proxy
+
+- [ ] Upstream 404 stays 404 (or explicit not-found JSON), not 200 + empty Resource
+- [ ] FE `throwError` / `createError` aligned with real HTTP status
+- [ ] JWT/`attributes` preferred over client-supplied tenant ids
+
+## Over-broad parse
+
+- [ ] No “every positive int in the array is an id” unless array is already allowlisted
+- [ ] CSV/string explode paths do not swallow unrelated query params
+
+## Null / empty
+
+- [ ] Missing model → 404 vs empty collection semantics documented
+- [ ] `whereIn([], …)` / empty id list behavior safe (no accidental match-all)
+- [ ] Optional relations null-safe before property access
+
+## Error collapsing
+
+- [ ] Distinct failures keep distinct outcomes (authZ 404 ≠ relation-exists ≠ server error)
+- [ ] Controller does not always return one business message when helper returns `true` for multiple reasons
+
+## Hardcode / magic
+
+- [ ] No production hardcode of hotel/store/survey/scenario ids
+- [ ] Magic status/codes named or constanted when added
+
+## Async / Jobs / Events
+
+- [ ] Job payload carries needed tenant/service context (or reloads safely)
+- [ ] Job path does not assume HTTP middleware ran (`merge`, `attributes->storeId`)
+- [ ] Retries are idempotent for writes/deletes
+- [ ] Failed pre-check cannot leave partial side effects
+- [ ] `dispatch` callers listed in horizontal table
+
+## Business rules
+
+- [ ] Relation/existence gates: false positive and false negative both considered
+- [ ] Delete/update constraints still correct after ownership changes
+- [ ] Soft-deleted rows excluded/included as product intends
+
+## Data / transactions
+
+- [ ] Multi-step delete/update atomic where required
+- [ ] Soft delete vs force delete consistency with “exists” checks

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

@@ -0,0 +1,5 @@
+# Common spec core (/common-spec)
+
+Emit **YAML bundles** under `surfaces/…/common/yaml/` — never hand-write `ir/generated/*.md`.
+
+After edits: `flowgrid split` → `flowgrid render`.

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

@@ -0,0 +1,5 @@
+# Spec requirement (/spec)
+
+Author **bundle YAML only** on the docs hub. Markdown under `ir/generated/` is produced by `flowgrid render`.
+
+Path SSOT: `surfaces/<surface>/CMP-*/<NN…>/` — resolve IDs with `flowgrid_docs_route` when on a consumer repo.

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

@@ -0,0 +1,23 @@
+# ADR template
+
+Path: `architecture/09-decisions/ADR-{NNN}-{slug}.md` (or section in index)
+
+```markdown
+# ADR-{NNN} — Title
+
+| Field | Value |
+|-------|-------|
+| Status | proposed / accepted / superseded |
+| Date | YYYY-MM-DD |
+| Deciders | |
+
+## Context
+
+## Decision
+
+## Consequences
+
+## Related
+
+- CMP-*, CTR-*, FLOW-*, …
+```

package/harness/docs/extracts/tpl-arc42-chapter.md

@@ -0,0 +1,29 @@
+# arc42 chapter stub
+
+Path: `architecture/{NN}-{slug}/index.md`  
+`status: stub | active`
+
+## Sections
+
+```markdown
+# {NN} — {Title}
+
+status: stub
+
+## Purpose
+
+One short paragraph (*why* this chapter exists).
+
+## Content
+
+TBD — fill when active.
+
+## Out of scope
+
+What belongs in other chapters / các module/bề mặt khác.
+
+## See also
+
+- Related chapter links
+- Related IDs (`CTX-*`, `FLOW-*`, …)
+```

package/harness/docs/extracts/tpl-cross-cutting.md

@@ -0,0 +1,24 @@
+# Cross-cutting stub
+
+Path: `architecture/08-cross-cutting/{topic}.md` or sections under index.
+
+```markdown
+# {Topic} (e.g. Security)
+
+| Field | Value |
+|-------|-------|
+| Owner | TBD |
+| Status | stub |
+
+## Intent
+
+One paragraph.
+
+## Approach
+
+TBD — link ADR / CMP / FLOW when known.
+
+## Out of scope
+
+Product UI DSL, full OpenAPI, test plans (`base-tests`).
+```

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

@@ -0,0 +1,23 @@
+# Deployment stub — DEP-* (optional)
+
+Path: `architecture/07-deployment/`  
+Only write a real diagram when **placement** matters. Default = short stub.
+
+## Sections
+
+`# DEP-* — title` · 2–5 lines prose · optional `## Diagram` · `## Notes` (no secrets)
+
+## Stub example
+
+```markdown
+# DEP-local — Local developer layout
+
+status: stub
+
+Local WSL / Docker-compose style layout for platform bases.
+Prod/staging topology: TBD (do not invent).
+
+## Notes
+
+- No secrets; no local-machine handbook in this repo
+```