@shanyucoder/flowgrid 0.1.0

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

@@ -0,0 +1,21 @@
+# ArtifactGraph — backend hooks
+
+- Resolve endpoint, DTO, API, data, and business-rule tags from the current BE
+  repo's local index only.
+- **Before creating a new BE spec**, run `artifactgraph_api_reuse_check` to detect
+  existing routes across product surfaces. If a match is found without `#reuse-api`,
+  emit `DUPLICATE_API_ROUTE` warning and ask member A/B/C before proceeding.
+- Use `#reuse-api` tag on specs that intentionally reuse an existing common/sibling
+  route. Use `#call-external` for third-party integrations (OAuth, SMS, Payment, Webhook).
+  Use `#cross-service` / `#cross-entity-service` for multi-aggregate orchestration.
+  Use `#derived-data` for computed fields not stored on the entity.
+- Run BE dry generation before write generation when both keys exist.
+- **Code size discipline:** Enforce `platform-code-size.mdc` (~200 lines/file, ~20 lines/func). Automatically split services, DTOs, and handlers during bộ code generation.
+- Full product registry remains in docs; ArtifactGraph does not infer or follow
+  a docs checkout.
+- Architecture ID / C4 lookups go to bộ docs (`FLOWGRID_DOCS_ROOT`). Symbol /
+  call-graph lookups go to the target repo's `codegraph-<key>` MCP — Platform
+  DNA owns that auto-wire, not ArtifactGraph.
+- Promote canonical registry changes in docs; keep only BE-local
+  allowlists/templates in the BE repo.
+- Leave `/spec`, `/api-spec`, `/unit`, and `/test` phase skills product-owned.

package/harness/be/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/be/skills/api/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: api
+description: /api — backend API generation through bộ code BE adapters.
+disable-model-invocation: true
+---
+
+# /api — Backend API
+
+**Owner:** bộ code (`--type=be`)  
+**Adapters:** `fastapi` · `laravel` · `dotnet-integration` · `nestjs`
+
+## Generate
+
+```bash
+npm run codegen:api:dry -- --spec /path/to/api/01/01-backend-spec.yaml
+npm run codegen:api -- --spec /path/to/api/01/01-backend-spec.yaml
+npm run codegen:api -- --spec /path/to/api/01/01-backend-spec.yaml --force
+npm run codegen:api:unit:dry -- --spec /path/to/api/01/01-backend-spec.yaml
+
+# Fallback direct CLI if wrappers missing:
+flowgrid api-gen:dry --adapter=fastapi -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-gen --adapter=fastapi -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-gen --adapter=fastapi -- --spec /path/to/api/01/01-backend-spec.yaml --force
+flowgrid api-unit-gen:dry --adapter=fastapi -- --spec /path/to/api/01/01-backend-spec.yaml
+
+flowgrid api-gen:dry --adapter=laravel -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-gen --adapter=laravel -- --spec /path/to/api/01/01-backend-spec.yaml
+
+flowgrid api-unit-gen:dry --adapter=laravel -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-registry --adapter=laravel
+flowgrid api-unit-registry --adapter=laravel
+
+# Laravel adapter (PHP): use `flowgrid api-gen` / `flowgrid api-unit-gen` from repo root.
+
+flowgrid api-gen:dry --adapter=nestjs -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-unit-gen:dry --adapter=nestjs -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-registry --adapter=nestjs
+```
+
+BE never reads `ir/design.yaml` or `ir/spec.yaml`. `--id CMP-*` globs every `01-backend-spec.yaml` under that module (`…/api/<seq>/`) and generates them in order (stop on first failure). `--spec <dir>` does the same.
+
+FE models (not this skill): `flowgrid contract-gen:dry -- --spec /path/to/ir/design.yaml` on the **FE** lane.
+
+## Docs Root Resolution
+
+1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
+   pointer for locating `01-backend-spec.yaml`.
+2. If `FLOWGRID_DOCS_ROOT` is **not** set, fall back to Platform DNA
+   configuration (`platform-dna`) to resolve the docs hub path.
+   Platform DNA discovery is slower and more error-prone, so always prefer
+   an explicit `FLOWGRID_DOCS_ROOT` when available.
+
+## Route
+
+Architecture/C4 → bộ docs (`FLOWGRID_DOCS_ROOT`); IR via explicit `--spec` /
+`FLOWGRID_DOCS_ROOT` when configured — never ArtifactGraph as the docs
+bridge. This-repo conventions → local CodeGraph if present; other repo X →
+only Platform DNA-wired `codegraph-<key>`. ArtifactGraph = local allowlist
+hints only.
+
+The selected backend repository is the only write target. Never infer a sibling
+docs hub or frontend checkout. Never Write `ir/*` or `*.bundle.yaml` on the docs hub;
+missing `codegen.profile` on **01-backend-spec.yaml** → STOP, hand off to docs `/grill-api-spec`.
+
+Laravel supports the detected `modules-v1` profile only. FastAPI requires an
+explicit Python runtime or target virtual environment.
+
+`dotnet-integration` requires the .NET 8 SDK (`FLOWGRID_DOTNET`, then
+`dotnet`) and supports the pilot-specific `mes-downtime` profile. Its API pass
+already emits test source; it has no separate API unit-generation engine.
+
+FastAPI generates all nested module entities, with flat `entities` and legacy
+`codegen.entity` compatibility. Code and unit manifests retain SHA-256
+ownership: identical and unmodified managed files are safe, while unmanaged or
+locally modified files block the whole batch. Inspect dry-run statuses before
+using `--force`, which explicitly overwrites conflicts. Ambiguous global
+endpoints in a multi-entity spec are not shared across entities; the generator
+warns and uses entity-local CRUD defaults.
+
+## Review requirements
+
+- Replace generated auth/authorization placeholders with project policy.
+- Verify validation, resources/presenters, transactions and error mapping.
+- Run backend tests and `/business-impact-review` for risky changes.
+
+## Accelerators (optional)
+
+```text
+if ArtifactGraph available: allowlist/recommend API generation
+else: execute bộ code adapter directly
+
+if CodeGraph available for this checkout (`codegraph-<key>`): inspect existing module conventions/callers
+else: targeted repository search — never a workspace-parent graph
+else: targeted repository search and reads
+```
+
+Missing accelerators never block API generation. Complete each documented
+direct or targeted-local fallback first, then follow
+`.cursor/rules/flowgrid-code-optional-integrations.mdc` for deduplicated
+once-per-run-and-optional telemetry with observed metrics only.
+
+## Translation Rule (i18n)
+Always wrap static text with native framework i18n helpers (e.g. `__('key')`, `_localizer["key"]`, `i18n.t('key')`).
+- **[MANDATORY]** Read the `i18n` block from `ir/design.yaml`.
+- **[MANDATORY]** Automatically generate or update the corresponding translation locale files (`.json` for NodeJS/PHP/Python, or `.resx` for .NET).
+- **[STRICTLY FORBIDDEN]** Do NOT return unlocalized static raw error messages without an i18n wrapper.
+
+## Profile Handling Behavior
+**[CRITICAL INTERLOCK]** AI MUST NOT rewrite code from scratch. The CLI command `flowgrid api-gen` (Script Engine) MUST run first to emit the foundation scaffolding. Depending on `gen.codegen.profile`, AI reads the scaffolded base and enriches the targeted logic:
+- **`profile: auth`**: Inject authentication logic (Login, JWT token, bcrypt password hashing).
+- **`profile: select-item`**: Streamline into a lightweight selection list returning `id`, `name`/`label` for dropdown components.
+- **`profile: setting`**: Adapt scaffold to read/write static Key-Value configurations or JSON store.
+- **`profile: free`**: Implement domain-specific requirements according to the spec's `summary` / `purpose`.
+- **`profile: export`**: Implement large-dataset retrieval and file export generation (CSV/Excel).
+- **`profile: import`**: Implement file upload parsing, bulk validation, and batch insert.
+- **`profile: dashboard-stats`**: Implement aggregation queries, grouping data to return statistical metrics.

package/harness/be/skills/api-unit/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: api-unit
+description: /unit — backend API unit test generation via bộ code BE adapters.
+disable-model-invocation: true
+---
+
+# /unit — Backend API Unit Tests
+
+**Owner:** bộ code (`--type=be`)
+**Adapters:** `fastapi` · `laravel` · `nestjs`
+
+> `dotnet-integration` emits test source during its primary API pass; it has no
+> separate unit-generation engine.
+
+## Generate
+
+```bash
+npm run codegen:api:unit:dry -- --spec /path/to/api/01/01-backend-spec.yaml
+npm run codegen:api:unit -- --spec /path/to/api/01/01-backend-spec.yaml
+
+# Fallback direct CLI if wrappers missing:
+flowgrid api-unit-gen:dry --adapter=fastapi -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-unit-gen --adapter=fastapi -- --spec /path/to/api/01/01-backend-spec.yaml
+
+flowgrid api-unit-gen:dry --adapter=laravel -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-unit-gen --adapter=laravel -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-unit-registry --adapter=laravel
+
+flowgrid api-unit-gen:dry --adapter=nestjs -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-unit-gen --adapter=nestjs -- --spec /path/to/api/01/01-backend-spec.yaml
+flowgrid api-unit-registry --adapter=nestjs
+```
+
+You MUST run the codegen script (`npm run codegen:api:unit` or
+`flowgrid api-unit-gen`) FIRST to generate the test skeleton from the backend
+spec, before attempting to fill in gaps or add missing tests manually.
+
+Requires a prior `01-backend-spec.yaml` under the docs hub API folder.
+
+## Docs Root Resolution
+
+1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
+   registry/IR pointer for locating `01-backend-spec.yaml`.
+2. If `FLOWGRID_DOCS_ROOT` is **not** set, fall back to Platform DNA
+   configuration (`platform-dna`) to resolve the docs hub path.
+   Platform DNA discovery is slower and more error-prone, so always prefer
+   an explicit `FLOWGRID_DOCS_ROOT` when available.
+
+## Route
+
+Architecture/C4 → bộ docs (`FLOWGRID_DOCS_ROOT`); spec via explicit `--spec` /
+`FLOWGRID_DOCS_ROOT` when configured — never ArtifactGraph as the docs
+bridge. This-repo conventions → local CodeGraph if present; other repo X →
+only Platform DNA-wired `codegraph-<key>`. ArtifactGraph = local allowlist
+hints only.
+
+## Review requirements
+
+- Verify generated tests cover all endpoints in `01-backend-spec.yaml`.
+- Replace generated auth/mock placeholders with project-specific fixtures.
+- Run backend test suite to confirm generated tests pass.
+
+## Accelerators (optional)
+
+```text
+if ArtifactGraph available: allowlist/recommend API unit generation
+else: execute bộ code adapter directly
+
+if CodeGraph available for this checkout (`codegraph-<key>`): inspect existing test conventions
+else: targeted repository search — never a workspace-parent graph
+```
+
+Missing accelerators never block unit generation. Complete each documented
+direct or targeted-local fallback first, then follow
+`.cursor/rules/flowgrid-code-optional-integrations.mdc` for deduplicated
+once-per-run-and-optional telemetry with observed metrics only.

package/harness/be/skills/grill-api/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: grill-api
+description: /grill-api — audit generated FastAPI/Laravel/Nest API before integration.
+disable-model-invocation: true
+---
+
+# /grill-api
+
+Run after `npm run codegen:api:dry` / `flowgrid api-gen:dry` and after implementation.
+
+**Owner:** bộ code (`--type=be`). Docs hub is **read-only**.
+
+## Target / ID Resolution Rule
+
+- User prompt MAY specify a function ID, API slug, or short name (e.g. `API-AUTH-001`, `login`, `CMP-ADM-009`).
+- Agent MUST resolve **`…/api/<seq>/01-backend-spec.yaml`** via `FLOWGRID_DOCS_ROOT` or `flowgrid_docs_route` (screen leaf `CMP-*/<NN…>/api/<seq>/`, or `common/yaml/<slug>/`, or `integrations/…/api/<seq>/`).
+- **Read the entire `01-backend-spec.yaml`**. Do **not** use `ir/design.yaml` or `ir/spec.yaml` as BE contract.
+- Compare generated routes/code against that 01 file. Missing 01 → STOP, hand off to docs `/grill-api-spec`.
+- Do NOT demand full filesystem paths from the user if an ID is given.
+
+## Docs Root Resolution
+
+1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
+   pointer for locating `01-backend-spec.yaml`.
+2. If `FLOWGRID_DOCS_ROOT` is **not** set, fall back to Platform DNA
+   configuration (`platform-dna`) to resolve the docs hub path.
+   Platform DNA discovery is slower and more error-prone, so always prefer
+   an explicit `FLOWGRID_DOCS_ROOT` when available.
+
+Check:
+
+- Routes/methods/statuses match `01-backend-spec.yaml` (action-suffix paths).
+- AuthZ and tenant scope use trusted context.
+- Validation does not accept request-bag noise.
+- Null/empty/error semantics remain distinct.
+- Writes are transaction-safe; async retries are idempotent.
+- Generated placeholders are replaced before ship.
+
+## Accelerators (optional)
+
+```text
+if ArtifactGraph available: local contract/tag/parity hints only
+else: scoped contract-to-code comparison
+
+if codegraph-<repo-key> for this checkout: callers/routes/jobs/listeners
+else: targeted repository search
+
+architecture IDs / C4 → bộ docs (FLOWGRID_DOCS_ROOT), never CodeGraph
+```
+
+Missing accelerators never block the grill. Complete each scoped model or
+targeted-local fallback first, then follow
+the remainder of this skill.
+
+## Translation Rule (i18n)
+Always wrap static text with native framework i18n helpers (e.g. `__('key')`, `_localizer["key"]`, `i18n.t('key')`).
+- **[MANDATORY]** Read the `i18n` block from `ir/design.yaml`.
+- **[MANDATORY]** Automatically generate or update the corresponding translation locale files (`.json` for NodeJS/PHP/Python, or `.resx` for .NET).
+- **[STRICTLY FORBIDDEN]** Do NOT return unlocalized static raw error messages without an i18n wrapper.
+
+## Profile Handling Behavior
+**[CRITICAL INTERLOCK]** AI MUST NOT rewrite code from scratch. The CLI command `flowgrid api-gen` (Script Engine) MUST run first to emit the foundation scaffolding. Depending on `gen.codegen.profile`, AI reads the scaffolded base and enriches the targeted logic:
+- **`profile: auth`**: Inject authentication logic (Login, JWT token, bcrypt password hashing).
+- **`profile: select-item`**: Streamline into a lightweight selection list returning `id`, `name`/`label` for dropdown components.
+- **`profile: setting`**: Adapt scaffold to read/write static Key-Value configurations or JSON store.
+- **`profile: free`**: Implement domain-specific requirements according to the spec's `summary` / `purpose`.
+- **`profile: export`**: Implement large-dataset retrieval and file export generation (CSV/Excel).
+- **`profile: import`**: Implement file upload parsing, bulk validation, and batch insert.
+- **`profile: dashboard-stats`**: Implement aggregation queries, grouping data to return statistical metrics.

package/harness/be/skills/grill-api-unit/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: grill-api-unit
+description: /grill-unit — BE grill gate before /unit API test generation.
+disable-model-invocation: true
+---
+
+# /grill-unit
+
+**Owner:** bộ code · audit gate before BE unit test generation.
+
+Run after `npm run codegen:api:unit:dry` / `flowgrid api-unit-gen:dry` and
+before committing generated test code.
+
+## Target / ID Resolution Rule
+
+- User prompt MAY specify a function ID, API slug, or short name (e.g. `API-AUTH-001`, `login`, `CMP-ADM-009`).
+- Agent MUST resolve **`…/api/<seq>/01-backend-spec.yaml`** via `FLOWGRID_DOCS_ROOT` or `flowgrid_docs_route`.
+- **Read the entire `01-backend-spec.yaml`**. Do **not** use `ir/design.yaml` or `ir/spec.yaml` as BE contract.
+- Compare generated unit tests against that 01 file. Missing 01 → STOP, hand off to docs `/grill-api-spec`.
+- Do NOT demand full filesystem paths from the user if an ID is given.
+
+## Docs Root Resolution
+
+1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
+   pointer for locating `01-backend-spec.yaml`.
+2. If `FLOWGRID_DOCS_ROOT` is **not** set, fall back to Platform DNA
+   configuration (`platform-dna`) to resolve the docs hub path.
+   Platform DNA discovery is slower and more error-prone, so always prefer
+   an explicit `FLOWGRID_DOCS_ROOT` when available.
+
+## Check
+
+```text
+if local ArtifactGraph available: check the BE repo's allowlist for apiUnitGenDry
+else: npm run codegen:api:unit:dry -- --spec …
+```
+
+- Generated test files match endpoints in `01-backend-spec.yaml`.
+- Auth/tenant fixtures use trusted project context, not generated stubs.
+- Mock dependencies are properly scoped and isolated.
+- Edge cases (null/empty/error) have distinct assertions.
+- Async/retry tests are idempotent.
+
+## Accelerators (optional)
+
+```text
+if ArtifactGraph available: local contract/tag/parity hints only
+else: scoped spec-to-test comparison
+
+if codegraph-<repo-key> for this checkout: callers/routes/existing test patterns
+else: targeted repository search
+
+architecture IDs / C4 → bộ docs (FLOWGRID_DOCS_ROOT), never CodeGraph
+```
+
+Missing accelerators never block the grill. Complete each scoped model or
+targeted-local fallback first, then follow the remainder of this skill.

package/harness/common/extracts/artifact-graph.md

@@ -0,0 +1,23 @@
+# Artifact graph — load per phase
+
+Extract bundles: `.cursor/extracts/extract-registry.json`
+
+Path root: `base-docs Code / `--id``
+
+| Phase | Primary artifacts | Do not load |
+|-------|-------------------|-------------|
+| legacy-spec | write `base-docs/surfaces/**/code/**`, Code `*.bundle.yaml` | gen, ir/spec, codegen/* |
+| /spec | `*.bundle.yaml` (spec + design), template | legacy/* |
+| bqa-grill | `ir/design.yaml`, `ir/legacy.yaml` ui slice, common bundles, `review` | ir/spec gen fields, legacy source |
+| dev-grill | `ir/design`, `ir/legacy`, write `gen` / ir/spec | legacy source, models/ |
+| grill-with-docs | bundle + ir/* reconcile | legacy source, archaeology |
+| portal:gen | **`ir/spec.yaml`** | bundle, legacy, design |
+| docs:render | **`*.bundle.yaml`** | — |
+| prototype | **`ir/spec.yaml`** + HANDOFF | legacy IR |
+| /test | `*.test.yaml`, ir/spec testIds | legacy-api-migration |
+| /unit | ir/spec + `{function}/generated/unit.manifest.json` | legacy/* |
+| /model | ir/spec entities + project-config | trace full |
+| /grill-api | legacy/api-migration | models/ |
+| update-spec-legacy | trace slice + bundle.legacy patch | macro legacy read |
+
+Generated output: `{function}/generated/` (HANDOFF, manifests) — cạnh bundle, không trong `ir/`.

package/harness/common/extracts/artifactgraph-hooks-core.md

@@ -0,0 +1,17 @@
+# ArtifactGraph — core hooks
+
+1. Check local status/index before artifact work.
+2. Analyze or grill locally; ask the member to confirm ambiguous decisions.
+3. **API reuse check (BE/docs):** Run `artifactgraph_api_reuse_check` before creating
+   a new spec. If `found: true` → add `#reuse-api` to the spec (agent applies tag, no gate).
+   `grill_check` also detects duplicates and suggests `#reuse-api` via `draftTags`.
+4. Show `askUser[]` — A/B/C for **grill** and **parity-drift** only.
+   `context-orphan` = warn only, not a gate.
+5. Run only allowlisted generation commands.
+6. Send only unresolved `cloudPromptSlice` content to cloud models.
+7. Promote canonical registries in the docs repo. In FE/BE/tests, promote only
+   repo-local allowlists/templates.
+8. Rebuild and remember confirmed decisions.
+
+The docs repo is registry SSOT. ArtifactGraph never owns registry payloads and
+never follows another toolkit's cross-repo pointer.

package/harness/common/extracts/artifactgraph-phase-hooks.md

@@ -0,0 +1,106 @@
+# Artifactgraph — phase hooks (local-first DSL)
+
+> Used by skill `/artifactgraph` and phase skills. Grill **confirm = local + member**, not cloud.  
+> **SSOT:** product repo `registries/*.json` + `codegen/templates` (+ skills/docs). MCP only **indexes** + runs **allowlisted** gen.
+
+## DSL loop (every lane: FE · BE · unit · e2e · docs)
+
+```text
+(1) Read tags + MCP index (rebuild from product registries)
+(2) artifactgraph_api_reuse_check — trước khi tạo spec mới BE/docs (check trùng route)
+(3) artifactgraph_gen <commandKey>  — local template/script
+(4) Still #needs-* / HANDOFF missing mẫu?
+      → member A/B/C and/or cloudPromptSlice (thiếu only)
+(5) Member OK → promote registry + hbs **in product repo** (not inside MCP)
+(6) artifactgraph_rebuild + remember → lần sau reuse tag + gen
+```
+
+| Lane | Local gen keys (`artifactgraph.json`) | After review promote (product git) |
+|------|----------------------------------------|------------------------------------|
+| **docs** (spec phase) | `specSplit`, `specSplitAll`, `docsRender`, `docsRenderCommon` | Tag chuẩn trên bundle/`ir` — reuse FE/unit/e2e |
+| **fe** | `genDry`, `gen` | `design` / `common` registry + Mo* templates + `platform-code-size.mdc` |
+| **be** (api repo) | `genDry`, `gen` (stack laravel/…) | BE codegen registry + templates + `platform-code-size.mdc` |
+| **unit** | `unitGenDry`, `unitGen` | `unit-test` registry |
+| **e2e** | `testcaseGenDry`, `testcaseGen` | `e2e-test` registry (`{spec}` = testcase path) |
+| **lifecycle** | `lifecycleSync` | `page-lifecycle` registry |
+
+Cloud **không** viết registry. Promote = docs `DESIGN-REGISTRY-PROMOTION` / `UNIT-REGISTRY-PROMOTION` / e2e docs + skill `/docs-mark`.
+
+## Shared protocol (every artifact skill)
+
+1. Run `artifactgraph init` once in the current product repo, then use
+   `artifactgraph_status`; project-local MCP is the default.
+2. **Local:** `artifactgraph_analyze` or `artifactgraph_grill_check`; after legacy also **`artifactgraph_parity_check`**.
+3. **API reuse check (BE/docs):** Run `artifactgraph_api_reuse_check` before creating
+   a new spec.
+   - `found: true` → route exists → add `#reuse-api` to the spec (no gate, agent applies tag)
+   - `found: false` → safe to proceed with new spec
+   - `grill_check` also detects duplicates via indexed routes → suggests `#reuse-api` in `draftTags`
+5. On confirm: `artifactgraph_remember` (`kind=grill|parity`).
+6. Gen only via `artifactgraph_gen` allowlisted keys; else documented `pnpm` fallback.
+7. Still missing implementation → **`cloudPromptSlice` only** — never full registries/templates.
+8. After implement: **promote in product repo** → `registryValidate` / lane registry cmds → `artifactgraph_rebuild`.
+
+## Per skill
+
+### `/spec`
+
+- Local: gắn tag chuẩn từ index (shell/common/unit/e2e đã học); `specSplit` / `docsRender` via MCP.
+- Confirm blocks when `specOrigin` is **not** legacy.
+- Cloud: only unknown domain rules in `cloudPromptSlice`.
+- **Không** `portal:gen` app ở phase này (trừ khi skill nói rõ dry gate).
+
+### `/api-spec` · `/api-integration-spec`
+
+- **Pre-flight:** `artifactgraph_api_reuse_check({ path, method })` trước khi viết spec.
+  - `found: true` → add `#reuse-api` vào spec; không cần tạo spec mới.
+  - `found: false` → proceed spec creation.
+- Local: `artifactgraph_grill_check` sau khi draft spec — phát hiện `duplicate-api-route` và suggest `#reuse-api` qua `draftTags`.
+- Cloud: only domain-specific API contract rules.
+
+### `/dev-grill-docs` · `/bqa-grill-docs` · `/grill-with-docs`
+
+- **Pre-flight:** `artifactgraph_grill_check` — bao gồm `duplicate-api-route` detection.
+- Local: trace + bundle; **`parity_check`**.
+- Cloud: only ambiguous Mo* naming with no registry alias.
+
+### `/update-spec` · `/update-api-spec`
+
+- **Pre-flight:** `artifactgraph_api_reuse_check` nếu spec có API routes mới.
+- Local: `artifactgraph_analyze` sau khi sửa — phát hiện gaps mới phát sinh.
+
+### `/prototype` · `/prototype-handoff`
+
+- Local: `artifactgraph_gen` `gen`; Mo* already in design registry → wire only.
+- Cloud: **only** `#needs-component` / `#needs-ui` slots with no file.
+
+### `/unit`
+
+- Local: `artifactgraph_suggest_tags` (lane `be` / `fe`) + `artifactgraph_gen` `unitGen`.
+
+### `/test`
+
+- Local: taxonomy testcase (`artifactgraph/lexicon/testcase-taxonomy.en.txt`) + `artifactgraph_gen` `testcaseGen`.
+
+### `/docs-mark`
+
+- Local: `suggest_tags` → update spec/registry → `artifactgraph_rebuild`.
+
+## Summary table
+
+| Skill | Local MCP pre-flight | Allowed gen command | Cloud prompt rule |
+|---|---|---|---|
+| `/spec` | `analyze`, `api_reuse_check` | `specSplit`, `docsRender` | `cloudPromptSlice` only |
+| `/api-spec` | `api_reuse_check`, `grill_check` | `specSplit` | Domain rules only |
+| `/grill-*` | `grill_check`, `parity_check` | — | Ambiguous Mo* names only |
+| `/prototype` | `analyze` | `genDry`, `gen` | `#needs-component` slots only |
+| `/unit` | `suggest_tags` | `unitGenDry`, `unitGen` | Unit pattern gaps only |
+| `/test` | `suggest_tags` | `testcaseGenDry`, `testcaseGen` | Scenario logic only |
+| `/docs-mark` | `suggest_tags`, `rebuild` | — | None |
+
+## Checklist for promote
+
+- [ ] Write registry JSON in product repo
+- [ ] Add templates if missing
+- [ ] Run `artifactgraph_rebuild`
+- [ ] Next session reuses new tag automatically

package/harness/common/extracts/core/agent-discipline.md

@@ -0,0 +1,8 @@
+# Agent Discipline (Portal phases)
+
+Project alwaysApply rules and spec/contract win on conflict.
+
+- State assumptions; ask when unclear; prefer simpler approaches.
+- Minimum code for the request; no speculative features or abstractions.
+- Surgical edits only; match existing style; do not refactor unrelated code.
+- Define verifiable success criteria; run scoped verification before claiming done.

package/harness/common/extracts/docs-mark-detect.md

@@ -0,0 +1,48 @@
+# Docs-mark — grill detection
+
+> Used by docs grill / FE grill skills. Grill **flags** and **asks member** — does not auto-tag.
+
+## Grill spec signals — logic
+
+| Signal | Suspected kind | Ask member |
+|--------|----------------|------------|
+| Endpoint mô tả payment/webhook/MES/ERP | `#call-external` | A local B `#call-external` C defer |
+| 2 entity độc lập, 1 flow sync | `#cross-entity-service` | A relationship B cross-entity C split APIs |
+| Field/response key không có trên `ir/spec.yaml` entities | `#derived-data` | A add to contract B `#derived-data` C remove |
+| Tag có nhưng thiếu block (`externalCalls`, `services`, `derivedData`) | validation fail | Fix via `/docs-mark` |
+| `commonRefs` trỏ registry `planned` | HANDOFF debt | Implement or defer in `openQuestions` |
+
+## Grill spec signals — UI & codegen
+
+| Signal | Suspected kind | Ask member |
+|--------|----------------|------------|
+| Column `render: custom` / `component:` set | `#needs-component: cell-{key}:MoXxx` | A) Mo local B) common C) defer |
+| Fuzzy widget (drawer vs sheet, chip vs badge) | `#ui:` / `#needs-ui:` | Member chọn canonical |
+| `#needs-component` but Mo* exists elsewhere | promote common-ui | A) copy local B) design registry C) defer |
+| `#needs-ui` → design registry `planned` | HANDOFF | Implement `/prototype` or defer |
+
+## Member prompt template
+
+```text
+[GRILL-MARK] {short finding}
+File/spec: {ref}
+
+Chọn:
+A) Giữ local — no mark
+B) {suggested tag} — update spec + registry
+C) Defer — ghi openQuestions, không block gate
+```
+
+If member chooses **B** → run `/docs-mark` in the same session.
+
+## Grill spec signals — API reuse (Section L hashtags)
+
+| Signal | Suspected kind | Ask member |
+|--------|----------------|------------|
+| `artifactgraph_api_reuse_check` finds existing route for same path+method | `#reuse-api` | Agent adds `#reuse-api` to spec (no gate) |
+| Endpoint calls payment/webhook/OAuth/SMS/MES/ERP system | `#call-external` | A local B `#call-external` C defer |
+| 2 bounded-context entities in single synchronous flow | `#cross-service` / `#cross-entity-service` | A single service B cross-service C split APIs |
+| Response field không có trên `ir/spec.yaml` entities | `#derived-data` | A add to entity B `#derived-data` C remove |
+| `DUPLICATE_API_ROUTE` gap in grill_check output | add `#reuse-api` | Agent adds `#reuse-api` to current spec |
+
+**Rule:** If 2 specs define the exact same URI path+method without `#reuse-api`, ArtifactGraph emits `DUPLICATE_API_ROUTE` gap (`severity: warn`, `draftTags: ['#reuse-api']`). Agent adds the tag to resolve — no member gate needed.