@shanyucoder/flowgrid 0.1.0

package/harness/fe/skills/test/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: test
+description: /test — Playwright E2E from tests-hub plan YAML (FE only).
+disable-model-invocation: true
+---
+
+# /test
+
+**Owner:** bộ test (`--type=fe`)
+
+```bash
+flowgrid testcase:gen:dry --tests-docs=/path/to/tests-hub --docs-root=/path/to/docs-hub -- --id TC-…
+flowgrid testcase:gen --tests-docs=/path/to/tests-hub --docs-root=/path/to/docs-hub -- --id TC-…
+```
+
+Use `FLOWGRID_TESTS_DOC` (or `--tests-docs`) when the tests hub is not local.
+Use `FLOWGRID_DOCS_ROOT` for docs evidence. Route Functions/W-* evidence through
+bộ docs, and symbols or call graphs for repo X through the Platform DNA-wired
+`codegraph-<repo-key>` server for checkout X. Never use a workspace-parent
+graph or ask the member to hand-edit MCP configuration.
+
+## Accelerators (optional)
+
+```text
+if local ArtifactGraph available: recommend/check generation allowlist (this repo)
+else: local deterministic search, then run flowgrid testcase:gen directly
+```
+
+ArtifactGraph never follows `FLOWGRID_DOCS_ROOT` / `FLOWGRID_TESTS_DOC`; plan
+YAML and docs evidence flow only through those bộ test pointers.
+
+Assign one stable `runId` at run start. If ArtifactGraph is missing, complete
+the local fallback, count successful file reads and exact raw bytes read into
+context, then emit exactly one `flowgrid.missing-optional` JSON event for the
+`runId` + `artifactgraph` pair. Deduplicate retries. Validate against
+`.cursor/schemas/flowgrid-test/missing-optional-event.schema.json`; report only actual
+`fileReads` and `contextBytes`, never estimated token or savings claims.

package/harness/fe/skills/unit/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: unit
+description: /unit — unit test generation from codegen manifests via bộ code.
+disable-model-invocation: true
+---
+
+# /unit
+
+**Owner:** bộ code (`--type=fe`)
+
+```bash
+npm run codegen:unit:dry -- --id W-AD-AUTH-001
+npm run codegen:unit -- --id W-AD-AUTH-001
+
+# Fallback direct CLI if wrappers missing:
+flowgrid unit-gen:dry --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
+flowgrid unit-gen --adapter=nuxt4 --docs-root=/path/to/docs-hub -- --id W-AD-AUTH-001
+flowgrid unit-registry --adapter=nuxt4
+```
+
+You MUST run the codegen script (`npm run codegen:unit` or `flowgrid unit-gen`) FIRST to generate the skeleton and basic implementation from IR, before attempting to fill in any gaps, implement logic, or add missing tests manually.
+
+Requires a prior codegen manifest under the docs hub `generated/` folder (when applicable).
+`--docs-root` / `FLOWGRID_DOCS_ROOT` is the canonical registry/IR pointer;
+local ArtifactGraph never replaces it.
+
+## Docs Root Resolution
+
+1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
+   registry/IR pointer for locating codegen manifests.
+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/registry/gen →
+`FLOWGRID_DOCS_ROOT`; symbols/call-graph for repo X → Platform DNA-wired
+`codegraph-<repo-key>`. Never workspace-parent graphs or member-edited MCP.
+Local ArtifactGraph is allowlist/tag hints for this repo only.
+
+`dotnet-line` is not supported by these separate unit commands: its primary
+`gen` pass already bundles generated test source.
+
+## Accelerators (optional)
+
+```text
+if local ArtifactGraph available: recommend/check the FE repo's unit-gen allowlist
+else: run flowgrid unit-gen directly
+```
+
+Missing ArtifactGraph never blocks unit generation. Complete the direct,
+deterministic bộ code fallback first, then follow
+`.cursor/rules/flowgrid-code-optional-integrations.mdc` for once-per-run telemetry.

package/harness/fe/skills/wire/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: wire
+description: /wire — replace prototype mocks with real API wiring (bộ code FE lane).
+disable-model-invocation: true
+---
+
+# /wire
+
+**Owner:** bộ code (`--type=fe`)
+
+Use after `/prototype` when tags/handoff mark `#wire-only` or real API integration is required.
+Keep generation through bộ code adapters; resolve canonical docs evidence
+through `FLOWGRID_DOCS_ROOT` and do not invent sibling layout.
+
+## Docs Root Resolution
+
+1. If `FLOWGRID_DOCS_ROOT` is set (non-empty), use it as the canonical
+   pointer for resolving IR/handoff evidence.
+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
+
+IR/handoff via `FLOWGRID_DOCS_ROOT`; architecture IDs via bộ docs
+(`FLOWGRID_DOCS_ROOT`); BE/FE symbols via per-repo `codegraph-<key>`; ArtifactGraph
+local tags only. Never workspace-parent graphs or member-edited MCP.
+
+## Accelerators (optional)
+
+```text
+if local ArtifactGraph available: local FE tags/allowlist slice for wire readiness
+else: model review from scoped HANDOFF + registry evidence
+```
+
+Missing ArtifactGraph never blocks wiring. Complete the scoped model fallback
+first, then follow `.cursor/rules/flowgrid-code-optional-integrations.mdc` for
+once-per-run telemetry with observed metrics only.
+
+## Pre-wire (tests hub)
+
+- **[MANDATORY]** Resolve **tests-docs** (`FLOWGRID_TESTS_DOC`) and **e2e-root** (FE `tests/e2e` or project convention).
+- **[MANDATORY]** `flowgrid cases:gate --strict` on TC YAML for the screen being wired (when gate is enabled for the team).
+
+## Post-wire (audit đầu ra)
+
+- **[MANDATORY]** After mocks are removed and real API is connected, run:
+
+```bash
+flowgrid audit e2e --e2e-root <playwright-dir> --tests-docs "$FLOWGRID_TESTS_DOC" --screen <W-*>
+```
+
+Optional: pass explicit `cases/**/TC-*.yaml` paths instead of `--tests-docs`.
+
+- Parse JSON: `missingInPlaywright`, `matrixRowsUncovered`, `orphanTestCases`, `orphanSpecs`, `gaps[]`.
+- **[MANDATORY]** Fix or defer every `critical` / `warning` gap before marking wire done; log deferrals in `qa/open` if team policy allows.
+- **[RECOMMENDED]** `flowgrid audit fe-be <bundle.yaml>` when integration exposed contract drift.
+
+Ref: `docs/references/skills/wire.md` · engine `engines/spec/lib/audit-e2e-coverage.mjs`.

package/harness/shared/AGENTS.md

@@ -0,0 +1,169 @@
+# {{FLOWGRID_AGENT_LABEL}} Workspace Rules — bộ docs Physical Interlocks
+
+> [!CRITICAL]
+> These are **PHYSICAL INTERLOCKS**, not casual checklist reminders.
+> Generated at `flowgrid init` for agent `{{FLOWGRID_AGENT_ID}}` → `{{FLOWGRID_AGENT_DIR}}/{{FLOWGRID_OVERLAY_FILE}}`.
+> Synchronized with `SSOT_AGENT_PROTOCOL.md`.
+> Any violation of these laws → run **FAILED**. Chat-only "done" = **STRICTLY REJECTED**.
+>
+> **[STRICTLY FORBIDDEN]** Do NOT use the list below as a static Verification Checklist in place of dynamic workflow steps derived from `SKILL.md`.
+> The checklist **MUST** be derived from the active skill's **Workflow + Accelerators** — never static or copy-pasted.
+
+**Path SSOT:** `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment)  
+**Task tracking:** Checklist in chat thread (≤5 items) or implementation plan artifact / Plan Mode (large tasks). **DO NOT** create physical `TODO.md` files in the repository.  
+**Skill root:** `{{FLOWGRID_AGENT_DIR}}/skills/<name>/SKILL.md`  
+**Tools:** read=`{{FLOWGRID_READ_TOOL}}` · write=`{{FLOWGRID_WRITE_TOOL}}`
+
+---
+
+## LAW 1 — CRITICAL RULE FOR PRE-FLIGHT CHECK
+
+In any thread (new or continuing), whenever a user requests to run a skill or feature, the **MANDATORY FIRST ACTION** is to invoke `{{FLOWGRID_READ_TOOL}}` directly on the target `SKILL.md` to load the current standards.
+
+**STRICTLY FORBIDDEN** to rely on speculative memory or context from prior turns.
+
+Without first invoking `{{FLOWGRID_READ_TOOL}}` on `SKILL.md` → **FORBIDDEN** to generate plans, YAML files, or any product artifacts.
+
+---
+
+## LAW 2 — CRITICAL RULE FOR TASK TRACKING & SESSION TOKEN HORIZON (Anti Flat-Check & Compaction Protection)
+
+**Objective:** Prevent incomplete delivery, superficial checking, and session max-length token overflow (auto-compaction/truncation).
+
+Immediately after Pre-flight, the agent **MUST** evaluate the total workload (including gaps from audit scripts, user questions, and action items) against the **Session Max-Length Horizon**:
+
+### Workload & Token Safeguard Gate (The 5 / 10 Threshold Rule)
+1. **Small Scope (≤5 items, single screen/API):**
+   - Accumulates < 30k trajectory tokens — well within safe single-session limits.
+   - List dynamic checklist (`- [ ]`) directly in the **chat thread**.
+   - Check off items (`[x]`) with concrete file/diff evidence as each completes.
+   - Execute wizard questions one at a time directly in the chat thread.
+2. **Buffer Scope (6–9 items):**
+   - Permitted in chat ONLY if items are isolated, single-turn scalar string/label fills without deep file re-reading.
+   - If items involve structural changes or multi-file dependencies → MUST escalate to an implementation plan.
+3. **Large Scope (≥10 items, multi-screen/cross-repo, OR audit script outputs extensive gaps):**
+   - **MANDATORY HARD STOP IN CHAT:** Strictly forbidden from dumping all items into the active chat session, which guarantees single-turn truncation and session auto-compaction.
+   - **Environment Plan Gate:** Author a structured implementation plan using the host environment's plan mechanism:
+     - **Antigravity:** `implementation_plan.md` in `<appDataDir>/brain/<conversation-id>/`.
+     - **Cursor:** Plan Mode / Plan document / `plan.md`.
+     - **Claude Code / Windsurf / Others:** Structured plan artifact or scratchpad (`plan.md` / `implementation_plan.md`).
+     - **Repository Cleanliness:** Regardless of host agent, **NEVER** commit temporary plan scratchpads into the production codebase repo.
+   - **Phase Slicing:** Partition workload into discrete **Phases** (each phase capped at 3–5 items).
+   - **Phase Boundary & Context Offloading:** At the completion of each phase, immediately write persistent physical files to disk. For the next phase, load fresh state from disk instead of accumulating verbose conversation history, insulating the workflow against context loss.
+
+**Question Protocol (mandatory in both chat thread and implementation plan):**
+
+- Every question **MUST** be explicitly numbered (`Question 1`, `Question 2`, etc.).
+- Every question **MUST** provide **≥3 options**: (1) Concrete choice labeled `(Recommended)`, (2) `Other` (free text input), and (3) `Log as Tech Debt (Pending)`.
+- **Chat Wizards (Small Scope):** Render one question at a time, awaiting user response before proceeding.
+- **Implementation Plans (Large Scope):** Consolidate numbered questions within their respective phases in the plan document.
+
+**CRITICAL — Physical File Policy:**
+
+- **STRICTLY FORBIDDEN** to create a physical `TODO.md` file inside the target repository.
+- **STRICTLY FORBIDDEN** to merely copy the static "Verification Checklist" from the end of `SKILL.md`.
+- Each Workflow step = one checklist item. Each Accelerator branch = one `if available / else fallback` entry.
+- **STRICTLY FORBIDDEN** to combine steps, batch check-off items, or output static generic checklists.
+
+The verification checklist at the bottom of a skill serves only to audit evidence against derived steps — never as the checklist source itself.
+
+---
+
+## LAW 3 — CRITICAL RULE FOR EXECUTION (Plan Before Write)
+
+**STRICTLY FORBIDDEN** to batch actions together without planning. **STRICTLY FORBIDDEN** to create redundant standalone plan files (`*-plan.md`).
+
+---
+
+## LAW 4 — CRITICAL RULE — PHYSICAL OUTPUT IMMEDIATELY (No RAM Caching)
+
+Whenever the agent generates a persistent result, it **MUST NOT** retain it solely in RAM or chat context.
+
+**MANDATORY TO USE TOOL `{{FLOWGRID_WRITE_TOOL}}` TO WRITE PHYSICAL FILES IMMEDIATELY.**
+
+Physical output of step N = Physical input of step N+1.
+
+**Exception:** Unconfirmed Grill proposals remain on the **Chat Thread**. After member confirmation → update product SSOT and **Artifact Registry** directly.
+
+---
+
+## LAW 5 — CRITICAL RULE FOR DATA ORIGIN (Zero Business Hallucination)
+
+The agent is permitted to populate specifications from strictly **2 sources**:
+
+1. User prompt
+2. History / evidence in ArtifactGraph Registry
+
+**STRICTLY FORBIDDEN** to invent fields, validations, database columns, flows, or domain tags.
+
+Any missing detail **MUST** remain empty or be tagged `#missing_info` and deferred to `/grill`.
+
+---
+
+## LAW 6 — CRITICAL RULE FOR GRILL PROCESS (Hard Confirmation Gate)
+
+When inspecting `#missing_info` or gaps, Grill **MUST** follow 4 steps:
+
+1. **Re-check ArtifactGraph** (if available) — other members may have committed updates.
+2. **Micro-scoping:** Isolate strictly the missing block/field. Do not alter settled sections.
+3. **Proposal:** Present via **wizard form** in the **Chat Thread** — one question at a time with ≥3 options (Recommended, Other, Tech Debt). Never create physical proposal files.
+4. **Hard Confirmation Gate:** The agent is **STRICTLY FORBIDDEN** from overwriting product files unilaterally. The agent **MUST** pause and await member confirmation. Only after explicit confirmation is the agent permitted to write to SSOT.
+
+---
+
+## LAW 7 — CRITICAL RULE FOR DSL REGISTRY (Human-Dictated)
+
+Human leads are the **exclusive authority** for establishing and updating DSL/Common standards.
+
+The agent has **NO AUTHORITY** to unilaterally decide what constitutes "Common".
+
+The agent acts strictly as a clerk, permitted to register or update DSL/Common in only **3** passive cases:
+
+1. User explicitly invokes `/common` or `/common-spec`.
+2. User explicitly invokes `/docs-mark` to record rules or tags.
+3. User explicitly confirms a `/grill` proposal.
+
+In standard `/spec` runs, the sole duty is to **consume existing common definitions**.
+
+**STRICTLY FORBIDDEN** to invent or overwrite common/DSL definitions without authorization.
+
+---
+
+## LAW 8 — CRITICAL RULE FOR ARTIFACTGRAPH MCP & CROSS-REPO ROUTING
+
+**1. Boundaries & Ownership:**
+- ArtifactGraph manages solely `artifactgraph.json`, `registries/*.json`, `templates`, and `lexicon/` within the current repository.
+- It does **NOT** manage Architecture Markdown (owned by bộ docs), Code Generators (owned by bộ code/bộ test), or Symbol Indexes (owned by CodeGraph).
+
+**2. Cross-Repo Routing:**
+- **STRICTLY FORBIDDEN** to use ArtifactGraph for broad cross-repo scanning or entire workspace graphs. Route by ownership:
+  - Architecture ID / C4 path → Delegate to **bộ docs** (`FLOWGRID_DOCS_ROOT`).
+  - IR / registry / generation → Delegate to **Owning Kit** (`FLOWGRID_DOCS_ROOT`, `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`).
+  - Symbol / Call-graph lookups for repo X → Use **CodeGraph MCP** for repo X (`codegraph-<key>`).
+
+**3. Protocol for MCP Usage:**
+- **Status & Rebuild:** Use `artifactgraph_status`. If stale, call `artifactgraph_rebuild`.
+- **Analyze:** Prioritize `artifactgraph_analyze`, `artifactgraph_grill_check`, or `artifactgraph_parity_check`.
+- **Remember:** Only use `artifactgraph_remember` AFTER member confirms options during Grill.
+- **Handoff:** Use `artifactgraph_allowlist_check` + `artifactgraph_recommend_command` to retrieve permitted commands; hand off to corresponding kit/script. Never run `artifactgraph_gen`.
+- **Cloud Prompt:** Send `cloudPromptSlice` only for unresolved work items.
+- **Setup:** If indices are missing, direct member to run `artifactgraph init` with the appropriate `--type=`.
+
+---
+
+## Mandatory Lock Sequence
+
+```text
+{{FLOWGRID_READ_TOOL}} SKILL.md
+  → For every persistent result: {{FLOWGRID_WRITE_TOOL}} IMMEDIATELY (No RAM)
+  → Data source: User | ArtifactGraph only; tag gaps with #missing_info
+  → Grill: 4-step protocol + STOP for Confirmation before writing SSOT
+  → Common/DSL: only via /common|/common-spec|/docs-mark|Confirm
+```
+
+## Isolation & Fake Reports Policy
+
+- **MANDATORY** to execute **strictly one** skill as requested by the user. **STRICTLY FORBIDDEN** to merge sibling skills.
+- **STRICTLY FORBIDDEN** to generate fake Markdown reports when the skill requires YAML/bundle output.
+
+Full wording: `SSOT_AGENT_PROTOCOL.md` (located in `{{FLOWGRID_AGENT_DIR}}/`).

package/harness/shared/SSOT_AGENT_PROTOCOL.md

@@ -0,0 +1,167 @@
+# SSOT Agent Protocol — Physical Interlocks (bộ docs)
+
+> [!CRITICAL]
+> These are **PHYSICAL INTERLOCKS**, not casual reminders.
+> Any violation of these laws → run **FAILED**. Chat-only "done" = **STRICTLY REJECTED**.
+>
+> Path SSOT: `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment).
+
+---
+
+## LAW 1 — CRITICAL RULE FOR PRE-FLIGHT CHECK
+
+**Objective:** Eliminate refusal to read original specification files.
+
+In any thread (new or continuing), whenever a user requests to run a skill or feature, the **MANDATORY FIRST ACTION** is to invoke `{{FLOWGRID_READ_TOOL}}` (or equivalent read tool) directly on the target `SKILL.md` to load the current standards.
+
+**STRICTLY FORBIDDEN** to rely on speculative memory or context from prior turns.
+
+Without first invoking `{{FLOWGRID_READ_TOOL}}` on `SKILL.md` → **FORBIDDEN** to generate plans, YAML files, or any product artifacts.
+
+---
+
+## LAW 2 — CRITICAL RULE FOR TASK TRACKING & SESSION TOKEN HORIZON (Anti Flat-Check & Compaction Protection)
+
+**Objective:** Prevent incomplete delivery, superficial checking, and session max-length token overflow (auto-compaction/truncation).
+
+Immediately after Pre-flight, the agent **MUST** evaluate the total workload (including gaps from audit scripts, user questions, and action items) against the **Session Max-Length Horizon**:
+
+### Workload & Token Safeguard Gate (The 5 / 10 Threshold Rule)
+1. **Small Scope (≤5 items, single screen/API):**
+   - Accumulates < 30k trajectory tokens — well within safe single-session limits.
+   - List dynamic checklist (`- [ ]`) directly in the **chat thread**.
+   - Check off items (`[x]`) with concrete file/diff evidence as each completes.
+   - Execute wizard questions one at a time directly in the chat thread.
+2. **Buffer Scope (6–9 items):**
+   - Permitted in chat ONLY if items are isolated, single-turn scalar string/label fills without deep file re-reading.
+   - If items involve structural changes or multi-file dependencies → MUST escalate to an implementation plan.
+3. **Large Scope (≥10 items, multi-screen/cross-repo, OR audit script outputs extensive gaps):**
+   - **MANDATORY HARD STOP IN CHAT:** Strictly forbidden from dumping all items into the active chat session, which guarantees single-turn truncation and session auto-compaction.
+   - **Environment Plan Gate:** Author a structured implementation plan using the host environment's plan mechanism:
+     - **Antigravity:** `implementation_plan.md` in `<appDataDir>/brain/<conversation-id>/`.
+     - **Cursor:** Plan Mode / Plan document / `plan.md`.
+     - **Claude Code / Windsurf / Others:** Structured plan artifact or scratchpad (`plan.md` / `implementation_plan.md`).
+     - **Repository Cleanliness:** Regardless of host agent, **NEVER** commit temporary plan scratchpads into the production codebase repo.
+   - **Phase Slicing:** Partition workload into discrete **Phases** (each phase capped at 3–5 items).
+   - **Phase Boundary & Context Offloading:** At the completion of each phase, immediately write persistent physical files to disk. For the next phase, load fresh state from disk instead of accumulating verbose conversation history, insulating the workflow against context loss.
+
+**Question Protocol (mandatory in both chat thread and implementation plan):**
+
+- Every question **MUST** be explicitly numbered (`Question 1`, `Question 2`, etc.).
+- Every question **MUST** provide **≥3 options**: (1) Concrete choice labeled `(Recommended)`, (2) `Other` (free text input), and (3) `Log as Tech Debt (Pending)`.
+- **Chat Wizards (Small Scope):** Render one question at a time, awaiting user response before proceeding.
+- **Implementation Plans (Large Scope):** Consolidate numbered questions within their respective phases in the plan document.
+
+**CRITICAL — Physical File Policy:**
+
+- **STRICTLY FORBIDDEN** to create a physical `TODO.md` file inside the target repository.
+- **STRICTLY FORBIDDEN** to merely copy the static "Verification Checklist" from the end of `SKILL.md`.
+- Each Workflow step = one checklist item. Each Accelerator branch = one `if available / else fallback` entry.
+- **STRICTLY FORBIDDEN** to combine steps, batch check-off items, or output static generic checklists.
+
+The verification checklist at the bottom of a skill serves only to audit evidence against derived steps — never as the checklist source itself.
+
+---
+
+## LAW 3 — CRITICAL RULE FOR EXECUTION (Plan Before Write)
+
+**Objective:** Prevent raw unvalidated generation directly in RAM.
+
+**STRICTLY FORBIDDEN** to batch actions together without planning. **STRICTLY FORBIDDEN** to create redundant standalone plan files (`*-plan.md`).
+
+---
+
+## LAW 4 — CRITICAL RULE — PHYSICAL OUTPUT IMMEDIATELY (No RAM Caching)
+
+**Objective:** Eliminate context truncation and loss of state.
+
+Whenever the agent generates a persistent result (plan, proposal, bundle, step summary), it **MUST NOT** retain it solely in RAM or chat context.
+
+**MANDATORY** to write physical files immediately using the appropriate tool.
+
+Physical output of step N = Physical input of step N+1 (read from disk, do not rely on memory).
+
+---
+
+## LAW 5 — CRITICAL RULE FOR DATA ORIGIN (Zero Business Hallucination)
+
+**Objective:** Forbid inventing business logic when prompt information is missing.
+
+The agent is permitted to populate specifications from strictly **2 sources**:
+
+1. User prompt
+2. Evidence from ArtifactGraph Registry (when MCP is available)
+
+**STRICTLY FORBIDDEN** to invent fields, validations, database columns, flows, or domain tags.
+
+Any missing detail **MUST** remain empty or be tagged `#missing_info` and deferred to `/grill`.
+
+---
+
+## LAW 6 — CRITICAL RULE FOR GRILL PROCESS (Hard Confirmation Gate)
+
+**Objective:** Restrict grilling to localized analysis; prevent unapproved scope creep.
+
+When inspecting `#missing_info` or gaps, Grill **MUST** follow 4 steps:
+
+1. **Re-check ArtifactGraph** (if available) — other members may have committed updates.
+2. **Micro-scoping:** Isolate strictly the missing block/field. Do not alter settled sections.
+3. **Proposal:** Present via **wizard form** in the **Chat Thread** — one question at a time with ≥3 options (Recommended, Other, Tech Debt).
+4. **Hard Confirmation Gate:** Wait for member confirmation in chat. Only after explicit confirmation is the agent permitted to update product SSOT (`.bundle.yaml`) and Artifact Registry.
+
+---
+
+## LAW 7 — CRITICAL RULE FOR DSL REGISTRY (Human-Dictated)
+
+**Objective:** Prevent unauthorized modifications to Common and DSL assets.
+
+Human leads are the **exclusive authority** for establishing and updating DSL/Common standards.
+
+The agent has **NO AUTHORITY** to unilaterally decide what constitutes "Common".
+
+The agent acts strictly as a clerk, permitted to register or update DSL/Common in only **3** passive cases:
+
+1. User explicitly invokes `/common` or `/common-spec`.
+2. User explicitly invokes `/docs-mark` to record rules or tags.
+3. User explicitly confirms a `/grill` proposal.
+
+In standard `/spec` runs, the sole duty is to **consume existing common definitions**.
+
+**STRICTLY FORBIDDEN** to invent or overwrite common/DSL definitions without authorization.
+
+---
+
+## LAW 8 — CRITICAL RULE FOR ARTIFACTGRAPH MCP & CROSS-REPO ROUTING
+
+**1. Boundaries & Ownership:**
+- ArtifactGraph manages solely `artifactgraph.json`, `registries/*.json`, `templates`, and `lexicon/` within the current repository.
+- It does **NOT** manage Architecture Markdown (owned by bộ docs), Code Generators (owned by bộ code/bộ test), or Symbol Indexes (owned by CodeGraph).
+
+**2. Cross-Repo Routing:**
+- **STRICTLY FORBIDDEN** to use ArtifactGraph for broad cross-repo scanning or entire workspace graphs. Route by ownership:
+  - Architecture ID / C4 path → Delegate to **bộ docs** (`FLOWGRID_DOCS_ROOT`).
+  - IR / registry / generation → Delegate to **Owning Kit** (`FLOWGRID_DOCS_ROOT`, `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`).
+  - Symbol / Call-graph lookups for repo X → Use **CodeGraph MCP** for repo X (`codegraph-<key>`).
+
+**3. Protocol for MCP Usage:**
+- **Status & Rebuild:** Use `artifactgraph_status`. If stale, call `artifactgraph_rebuild`.
+- **Analyze:** Prioritize `artifactgraph_analyze`, `artifactgraph_grill_check`, or `artifactgraph_parity_check`.
+- **Remember:** Only use `artifactgraph_remember` AFTER member confirms options during Grill.
+- **Handoff:** Use `artifactgraph_allowlist_check` + `artifactgraph_recommend_command` to retrieve permitted commands; hand off to corresponding kit/script. Never run `artifactgraph_gen`.
+- **Cloud Prompt:** Send `cloudPromptSlice` only for unresolved work items.
+- **Setup:** If indices are missing, direct member to run `artifactgraph init` with the appropriate `--type=`.
+
+---
+
+## Mandatory Lock Sequence for Each Skill Run
+
+```text
+1) {{FLOWGRID_READ_TOOL}} SKILL.md                          → Law 1
+2) Derive dynamic checklist                                 → Law 2
+3) Write immediately upon producing durable results (No RAM) → Law 4
+4) Sourced exclusively from User | ArtifactGraph; tag gaps   → Law 5
+5) Grill: 4-step protocol + STOP for Confirmation           → Law 6
+6) Common/DSL: only via /common|/common-spec|/docs-mark|Confirm → Law 7
+```
+
+Host overlay Antigravity: see `AGENTS.md` (synchronized Laws 1–8).

package/harness/shared/rules/flowgrid-code-optional-integrations.mdc

@@ -0,0 +1,53 @@
+---
+description: bộ code-owned fallback and telemetry for optional integrations
+alwaysApply: true
+---
+
+# bộ code optional integrations
+
+ArtifactGraph and CodeGraph are optional accelerators. Their absence or
+unavailability must never abort a bộ code-owned generation, dry-run,
+validation, or review.
+
+Full cross-repo routing (architecture → bộ docs, IR → pointer roots, symbols →
+per-repo `codegraph-<key>`) lives in `cross-repo-index-routing.mdc`.
+
+## Docs registry hub
+
+- FE reads canonical IR/registries from the member-selected docs repo through
+  `FLOWGRID_DOCS_ROOT` (written from `--docs-root` at init). Never infer a
+  sibling checkout.
+- ArtifactGraph in an FE/BE repo indexes that repo only; it does **not** follow
+  `FLOWGRID_DOCS_ROOT` and must not be used as the bridge to docs.
+- Use ArtifactGraph only for local allowlist/tag hints. Missing local
+  ArtifactGraph never changes where bộ code reads canonical docs input.
+- bộ docs, when installed as a consumer, uses its separate `FLOWGRID_DOCS_ROOT`
+  pointer for architecture ID/path queries — never CodeGraph for C4.
+- CodeGraph, when used, must be the Platform DNA-wired `codegraph-<repo-key>`
+  for that checkout. bộ code never writes those MCP entries itself. Missing
+  or unindexed checkouts fall back and emit telemetry; never invent a graph or
+  `codegraph init` a workspace parent.
+
+For each optional integration that cannot be used:
+
+1. Continue the owned workflow with its documented deterministic validation or
+   direct adapter fallback. Where judgment is required, use the documented
+   model fallback; where repository evidence is required, use targeted local
+   search and file reads.
+2. Complete the fallback before emitting telemetry. Do not emit an absence
+   event before or instead of the fallback.
+3. Emit exactly one event for each `(runId, optional)` pair, including across
+   retries. Deduplicate repeated discovery or connection failures in the same
+   run.
+4. Validate the event against
+   `.cursor/schemas/flowgrid-code/missing-optional-event.schema.json`.
+5. Set `event` to `flowgrid.missing-optional`, `package` to
+   `@platform/flowgrid-code`, and name the unavailable optional as `ArtifactGraph`
+   or `CodeGraph`.
+6. Report the fallback actually completed and the actual failure reason.
+   `metrics.fileReads` is the number of successful fallback file reads and
+   `metrics.contextBytes` is the total UTF-8 bytes those reads added to
+   context. Start both counters at zero, increment from observed operations,
+   and never estimate, predict, or copy planned values.
+
+Use one stable, non-empty `runId` for the entire owned command or agent run.

package/harness/shared/schemas/flowgrid-code/missing-optional-event.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://platform.local/schemas/flowgrid-code/missing-optional-event.schema.json",
+  "title": "FlowGrid bộ code missing optional dependency event",
+  "description": "Emitted once per FlowGrid bộ code run and missing optional dependency, after the owned fallback completes.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "event",
+    "package",
+    "runId",
+    "optional",
+    "reason",
+    "fallback",
+    "metrics"
+  ],
+  "properties": {
+    "event": {
+      "const": "flowgrid.missing-optional"
+    },
+    "package": {
+      "const": "@platform/flowgrid-code"
+    },
+    "runId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "optional": {
+      "type": "string",
+      "enum": [
+        "ArtifactGraph",
+        "CodeGraph"
+      ]
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1
+    },
+    "fallback": {
+      "type": "string",
+      "minLength": 1
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "fileReads",
+        "contextBytes"
+      ],
+      "properties": {
+        "fileReads": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "contextBytes": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/harness/tests/extracts/artifactgraph-hooks-test.md

@@ -0,0 +1,13 @@
+# ArtifactGraph — test hooks
+
+- Use the installed testcase taxonomy for scenario, coverage, and dimension
+  suggestions on the current tests repo's own plans only.
+- Resolve known E2E bundles from the current product index (local).
+- Full product registry/IR remains in docs. bộ test reads cross-repo evidence
+  through `FLOWGRID_DOCS_ROOT` / `FLOWGRID_TESTS_DOC`; ArtifactGraph does not
+  follow those pointers.
+- 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.
+- Run testcase generation only when the current repo allowlists it.
+- Keep `/testcase` and `/grill-testcase` phase skills owned by the test repo.

package/harness/tests/extracts/plans/readiness.md

@@ -0,0 +1,14 @@
+# Tests hub plans readiness
+
+**Who:** `/testcase`, `/grill-testcase`  
+**Not:** FE `/test` Playwright gen
+
+## Gate
+
+1. [ ] Design `W-*` / rules / acceptance tồn tại trên **docs hub** (SSOT)
+2. [ ] `surface` → `CMP-*` (module) → `SC-*` (GWT + examples + coverage_plan)
+3. [ ] Mỗi `TC-*` dùng `coverage[]` (không `type`); refs + bridge FE đủ gen
+4. [ ] `registries/tests-index.json` cập nhật
+5. [ ] `flowgrid cases:gate --strict --docs-root $FLOWGRID_DOCS_ROOT` (schema + audit + bundle trace + SC coverage) · `pnpm cases:render` (MD member VI)
+6. [ ] Grill: không còn `spec_hole` mở; coverage_gap đã xử lý hoặc backlog có chủ
+7. [ ] Handoff FE chỉ sau grill-testcase OK

package/harness/tests/rules/cross-repo-index-routing.mdc

@@ -0,0 +1,24 @@
+---
+description: Route cross-repo evidence to the owning per-repo index
+alwaysApply: true
+---
+
+# Cross-repo index routing
+
+- Architecture IDs and Functions/W-* paths belong to bộ docs through `FLOWGRID_DOCS_ROOT`.
+  Never use CodeGraph as the architecture index.
+- Test plans use `FLOWGRID_TESTS_DOC`; docs evidence uses
+  `FLOWGRID_DOCS_ROOT`; IR/registry/generation follows its owning pointer such as
+  `FLOWGRID_DOCS_ROOT`.
+- For symbols or call graphs in repo X, call the Platform DNA-wired
+  `codegraph-<repo-key>` MCP whose `--project-root` is checkout X. Never query
+  the index of the currently open repo for another repo.
+- Cross-index MCP entries come from Platform DNA using
+  `platform-repos.local.json` / `legacy-repos.local.json`. Do not ask members to
+  hand-edit `.cursor/mcp.json`, and never commit machine-local roots.
+- Only use a checkout-specific CodeGraph server when that checkout exists and
+  already has `.codegraph/`. If it is not indexed, report:
+  `cd <root> && codegraph init`.
+- Never initialize or scan a workspace parent. Keep one CodeGraph index per
+  repo. ArtifactGraph remains local to the current repo and is never a shared
+  docs or cross-repo index.