@shanyucoder/flowgrid 0.1.0

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

@@ -0,0 +1,33 @@
+# Module README template
+
+Path: `surfaces/<surface>/CMP-{NN}-{slug}/index.md` — **MD only** (yaml under `<function-slug>/code/`).
+
+```markdown
+# CMP-{NN} — Name
+
+Lead-assigned module. **This README is MD-only** (no YAML).
+
+Owns …
+
+| | |
+|--|--|
+| **ID** | `CMP-{NN}` |
+| **Business Process** | Module/cluster: `…/common/processes/FLOW-…`. Catalog: [`architecture/03-business-process/`](/architecture/03-business-process/) |
+| **Functions** | `<function-slug>`, … |
+| **Screens** | `W-…` |
+| **APIs** | `API-…` |
+
+\`\`\`mermaid
+flowchart LR
+  CMP[CMP-{NN}]
+  W[W-…]
+  API[API-…]
+  CMP --> W
+  CMP --> API
+\`\`\`
+
+## Code paths
+
+- [`<function-slug>/code/W-…/`](./<function-slug>/code/W-…/)
+- [`<function-slug>/code/API-…/`](./<function-slug>/code/API-…/)
+```

package/harness/docs/extracts/update-spec-delta.md

@@ -0,0 +1,5 @@
+# Update spec delta (/update-spec)
+
+Patch bundle only (delta). Emit `#update:*` tags, bump `specRevision`, run `flowgrid split` + `flowgrid check`.
+
+Full rewrite → `/spec`. QA inbox closure → `/qa-resolve`.

package/harness/docs/rules/agent-compliance.mdc

@@ -0,0 +1,26 @@
+---
+description: Enforce physical interlocks for all bộ docs skills
+alwaysApply: true
+---
+
+# Agent Deep Compliance — Physical Interlocks
+
+> [!CRITICAL]
+> These are **PHYSICAL INTERLOCKS**, not reminders or optional suggestions.
+> Synchronized with `AGENTS.md` + `SSOT_AGENT_PROTOCOL.md`.
+> **[STRICTLY FORBIDDEN]** Do NOT use this rule list as a static Verification Checklist in place of dynamic TODOs derived from each `SKILL.md` Workflow + Accelerators.
+
+When executing any skill (`/spec`, `/grill`, `/grill-bqa`, etc.):
+
+1. **PRE-FLIGHT:** FIRST action is **[MANDATORY]**: invoke tool `{{FLOWGRID_READ_TOOL}}` on the target `SKILL.md` under `{{FLOWGRID_AGENT_DIR}}/skills/`. **[STRICTLY FORBIDDEN]** to rely on memory or previous context.
+2. **SESSION MAX-LENGTH & WORKLOAD GATE (5 / 10 RULE):** Immediately evaluate task workload/audit gaps against session token limits.
+   - **Small Scope (≤5 items):** Inline chat thread checklist & single-question wizard.
+   - **Buffer Scope (6–9 items):** Permitted in chat ONLY if single-turn scalar string/label fills.
+   - **Large Scope (≥10 items, multi-screen/cross-repo, OR audit script with ≥10 gaps):** **[MANDATORY HARD STOP IN CHAT]**. Author host plan artifact (Antigravity `implementation_plan.md` in brain dir, Cursor Plan Mode / `plan.md`, Claude/Windsurf plan scratchpad). Partition into Phases (3–5 items/phase). Offload completed state to disk immediately at phase boundaries and reload fresh state in subsequent phases.
+3. **NO RAM CACHING:** All persistent changes **[MANDATORY]** immediately written via `{{FLOWGRID_WRITE_TOOL}}`. Never hold uncommitted state in chat/RAM. When a grill proposal is not yet confirmed → discuss directly in chat thread. **[STRICTLY FORBIDDEN]** to create temporary `*-proposal.md` files or overwrite product SSOT prior to explicit confirmation.
+4. **ZERO BUSINESS HALLUCINATION:** Ground data strictly from (1) User prompt and (2) ArtifactGraph registry. **[STRICTLY FORBIDDEN]** to invent fields, validations, database structures, or flows. Missing information must remain empty or be tagged `#missing_info`. No unprompted guessing.
+5. **GRILL HARD GATE:** ArtifactGraph re-check → micro-scope → provide structured recommendation (`(Recommended)`) → **STOP and prompt Member**. **[STRICTLY FORBIDDEN]** to write to SSOT before explicit user confirmation.
+6. **DSL / COMMON:** Human lead decides common promotions. The agent only executes `/common`, `/common-spec`, `/docs-mark`, or confirmation post-grill. `/spec` strictly consumes common definitions. **[STRICTLY FORBIDDEN]** to invent or overwrite common libraries spontaneously.
+7. **ISOLATION:** Execute strictly within the invoked skill scope. **[STRICTLY FORBIDDEN]** to merge sibling features or output fake Markdown reports when YAML contracts are required.
+
+**Path SSOT:** `surfaces/<surface>/CMP-*/<slug>/` (NO `modules/` segment).

package/harness/docs/rules/docs-hub.mdc

@@ -0,0 +1,54 @@
+---
+description: bộ docs MCP — arc42/C4 docs index; opt-in skill use
+alwaysApply: false
+---
+# docs-hub (bộ docs)
+
+Use `/docs-hub` for targeted ID, dependency, link, journey, and chapter queries.
+
+The docs repo owns architecture/product Markdown. bộ docs indexes and validates
+only.
+
+- In docs: `FLOWGRID_DOCS_ROOT` points to the current docs repo.
+- In FE/BE/tests consumer installs: `FLOWGRID_DOCS_ROOT` points to an explicit docs
+  checkout selected by the member. Never infer `../base-docs`.
+- Consumer installs sync only `/docs-hub` + this lightweight rule; architecture
+  authoring skills stay in docs.
+
+1. Use `flowgrid_docs_layout`, `flowgrid_docs_route`, or `flowgrid_docs_list_ids` to narrow scope.
+2. Use `flowgrid_docs_get_element` for one ID.
+3. Use `flowgrid_docs_deps_of` and `flowgrid_docs_dependents_of` for reference impact.
+4. Run `flowgrid_docs_orphans` and `flowgrid_docs_validate_links` before claiming completeness.
+5. Use `flowgrid_docs_business_processes` before reading all journey files.
+
+Do not require bộ docs for architecture work: if the MCP is unavailable, inspect
+the repository Markdown directly or explain how to run project-local setup.
+
+## Index routing
+
+Cross-repo index is per-repo, never one giant parent-workspace graph:
+
+- Architecture ID / C4 path → bộ docs (`FLOWGRID_DOCS_ROOT`). Never CodeGraph for
+  architecture Markdown.
+- IR / registry / generation → pointer kits when present
+  (`FLOWGRID_DOCS_ROOT`, `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`).
+- Symbol / call-graph for repo `X` → CodeGraph MCP for `X`
+  (`codegraph-<key>`, `--project-root` = checkout of `X`). Platform DNA wires
+  those servers from machine-local maps (`platform-repos.local.json`,
+  `legacy-repos.local.json`); members must not hand-edit `.cursor/mcp.json` for
+  that. Re-run `platform-dna codegraph:wire` to refresh.
+- ArtifactGraph stays local-only; it is never a shared index for other repos.
+
+ArtifactGraph is optional. If `@platform/artifactgraph` is not configured,
+unavailable, or fails, bộ docs must continue with targeted local search and
+scoped Markdown reads; the missing optional must never abort the run. Assign one
+stable `runId` per run. Count each successful fallback file read and its exact
+raw byte length. After the fallback completes, emit exactly one
+`flowgrid.missing-optional` JSON event per `runId` + optional pair conforming to
+`.cursor/schemas/flowgrid-docs/missing-optional-event.schema.json`; deduplicate
+retries. Report only actual `fileReads` and `contextBytes`, never token estimates.
+
+## Links and Paths Rule
+
+- **Strictly Use Relative Links:** All Markdown files (`*.md`) and rule/guide documents MUST use relative paths for referencing other files (e.g. `[link](overview/personas.md)` or `[spec.yaml](../../templates/shared/spec.yaml)`).
+- **Never Use Absolute Paths:** Do not use absolute filesystem paths (such as `/home/...` or `file:///...`) under any circumstances, as they break when team members check out the repo on different machines.

package/harness/docs/rules/flowgrid-process.mdc

@@ -0,0 +1,25 @@
+---
+description: FlowGrid bộ process — business process trace and impact review (opt-in)
+alwaysApply: false
+---
+
+# FlowGrid bộ process
+
+- `/business-process-trace`: observed brownfield process through code/evidence.
+- `/business-impact-review`: read-only vertical × horizontal blast-radius review.
+- `/configure-repo-maps`: NL → `platform-repos.local.json` / `legacy-repos.local.json`
+  (merge-by-key; handoff when cross-repo maps are empty).
+- `/flow-trace`: deprecated redirect to `/business-process-trace`.
+
+Checkout routing (`cross-repo-index.mdc`): `legacy-*` →
+`legacy-repos.local.json`; other system ids → `platform-repos.local.json`.
+Ambiguous or missing keys → ask / Gaps + `/configure-repo-maps` — never invent
+paths. FlowGrid bộ process does not write cross-repo CodeGraph MCP entries.
+
+CodeGraph, bộ docs and ArtifactGraph are optional accelerators; route them per
+repo/intent as defined in `cross-repo-index.mdc` (architecture →
+bộ docs, IR/registry → pointer kits, symbols of repo X → `codegraph-<key>` for
+X). Missing tools must fall back to targeted local search/model analysis and
+explicit residual gaps. Per run/optional pair, count actual successful file reads and raw context
+bytes, then emit exactly one `flowgrid.missing-optional` event conforming to
+`.cursor/schemas/flowgrid-process/missing-optional-event.schema.json` (`@platform/flowgrid-process`). Never estimate token savings.

package/harness/docs/rules/team-flow-grill.mdc

@@ -0,0 +1,31 @@
+---
+description: bộ docs grill metadata — list/form/detail profiles
+globs: surfaces/**
+alwaysApply: false
+---
+
+# Team Flow — Grill
+
+For `/grill-bqa`, `/grill-dev`, `/grill-docs` on docs-hub product bundles.
+
+## Ownership
+
+- `api` = BE contract · `ui.list|form|detail` = FE page · `ui.validationMessages` = shared copy
+- `ui.filters|columns|testIds`, `codegen`, `tags` = dev-grill / portal-gen
+
+## Minimum by profile
+
+**List:** `columns`, `filters`, `rowActions`/`bulkActions` when present — structured keys.
+
+**Form:** field `key`, `label`, `type`, `widget`; `validation` + `messages` or `ui.validationMessages`; `source` on selects.
+
+**Detail:** `header`, `sections`, `actions` — structured, not prose blob.
+
+## Decisions
+
+- Prose → `summary`, `requirements`, `acceptance`
+- Validation copy → `ui.validationMessages` + `form.fields[].messages` — no triple duplicate
+- UI affordance gaps (delete result dialog, breadcrumb, filters, disabled reasons, …) → `flowgrid-ux-common.mdc` + `.cursor/extracts/ux-common-patterns.md` when touched; `(Recommended)` in AskQuestion must follow that rule
+- Missing validation messages → block `/prototype`
+
+Skill extract: `bqa-grill` · `dev-grill` · `grill-docs`

package/harness/docs/rules/team-flow-harness-state.mdc

@@ -0,0 +1,16 @@
+---
+description: Harness state files — progress, tasks, and session handoff
+globs: .harness/**/*
+alwaysApply: false
+---
+
+# Harness State
+
+SSOT for run tracking lives under `.harness/` (not `.agents/tasks/`).
+
+- `feature_list.json` — scope; do not mark done without verify.
+- `progress.md` — handoff for the next session.
+- `registries/page-lifecycle.registry.json` + `base-docs/platform/toolchain/PAGE-LIFECYCLE.md` — highest stage per route when present; `portal:gen` / `portal:remove` / `portal:lifecycle sync` update these.
+- When a public command updates phase, record: command, files changed, verify ran or not, remaining blockers.
+
+Host overlays (Antigravity `AGENTS.md`, Cursor always-apply rules) point here; they must not invent a second task tracker.

package/harness/docs/rules/team-flow-spec.mdc

@@ -0,0 +1,36 @@
+---
+description: bộ docs docs spec/grill/update workflow
+globs: surfaces/**, legacy-dynamics/**
+alwaysApply: false
+---
+
+# Team Flow — Spec
+
+Active commands: `/spec`, `/grill-bqa`, `/grill-dev`, `/grill-docs`, `/update-spec`, `/update-spec-legacy` — one per session.
+
+> [!CRITICAL] MANDATORY AGENT INSTRUCTION
+> You MUST read and strictly enforce all guidelines in the target skill's `SKILL.md` file before starting any step in this pipeline.
+
+| Command | Skill |
+|---------|-------|
+| `/spec` | `.cursor/skills/spec/SKILL.md` |
+| `/grill-bqa` | `.cursor/skills/grill-bqa/SKILL.md` |
+| `/grill-dev` | `.cursor/skills/grill-dev/SKILL.md` |
+| `/grill-docs` | `.cursor/skills/grill-docs/SKILL.md` |
+| `/update-spec` | `.cursor/skills/update-spec/SKILL.md` |
+| `/update-spec-legacy` | `.cursor/skills/update-spec-legacy/SKILL.md` |
+| Grill metadata rules | `.cursor/rules/team-flow-grill.mdc` |
+
+Shared: resolve skill `extractBundle` → `.cursor/extracts/extract-registry.docs.json` (e.g. `bqa-grill`, `dev-grill`, `grill-docs`).
+
+## Pipeline
+
+1. **`/spec`** — `*.bundle.yaml` design v1 + testcase round 1. Per-zone: DSL/registry → bundle; gaps → `#needs-component` / `#needs-ui` + `flowgrid-ux-common` proposals → `AskQuestion`. No `gen` / `codegen`.
+2. **`/grill-bqa`** — UI, acceptance, breadcrumb, delete rules.
+3. **`/grill-dev`** — codegen-ready bundle + `tags`; emit bộ code FE dry-run handoff.
+4. **`/grill-docs`** — optional reconcile when BQA↔Dev contradict.
+5. **`/update-spec`** / **`/update-spec-legacy`** — controlled delta + `#update:*` (not full rewrite).
+6. **`/prototype`** — FE-lane handoff only after bộ code dry-run passes.
+
+- Render: `docs_render` / `flowgrid render` (pnpm fallback during transition)
+- **[STRICTLY FORBIDDEN]** Do NOT build UI prototypes, backend implementations, live APIs, or full E2E/unit tests during the spec/grill phase.

package/harness/docs/schemas/flowgrid-docs/backend-api.schema.json

@@ -0,0 +1,175 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://platform.local/schemas/flowgrid-docs/backend-api.schema.json",
+  "title": "FlowGrid docs backend API spec",
+  "type": "object",
+  "required": ["feature", "modules", "api"],
+  "properties": {
+    "feature": {
+      "type": "object",
+      "required": ["id", "title"],
+      "properties": {
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "status": { "type": "string" },
+        "version": { "type": "string" },
+        "source": { "type": "object" }
+      }
+    },
+    "changeLog": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "summary"],
+        "properties": {
+          "id": { "type": "string" },
+          "source": { "type": "string" },
+          "summary": { "type": "string" },
+          "impact": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "breaking": { "type": "boolean" }
+        }
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "summary"],
+        "properties": {
+          "id": { "type": "string" },
+          "summary": { "type": "string" },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "contexts": {
+      "type": "object",
+      "properties": {
+        "portalLayout": { "type": "string" },
+        "routePrefixes": { "type": "object" },
+        "actors": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "modules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string" },
+          "purpose": { "type": "string" },
+          "entities": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name", "mode"],
+              "properties": {
+                "name": { "type": "string" },
+                "table": { "type": "string" },
+                "mode": { "enum": ["Platform", "Tenant", "Pivot"] },
+                "aggregateRoot": { "type": "boolean" },
+                "fields": { "type": "array" },
+                "relationships": { "type": "array" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "api": {
+      "type": "object",
+      "required": ["endpoints"],
+      "properties": {
+        "endpoints": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "method", "path", "purpose"],
+            "properties": {
+              "id": { "type": "string" },
+              "module": { "type": "string" },
+              "method": { "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"] },
+              "path": { "type": "string" },
+              "purpose": { "type": "string" },
+              "reusedBy": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "auth": { "type": "object" },
+              "query": { "type": "object" },
+              "request": {},
+              "response": {},
+              "tags": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "externalCallRefs": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "serviceRefs": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "externalCalls": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "provider", "direction", "purpose", "service"],
+        "properties": {
+          "id": { "type": "string" },
+          "provider": { "type": "string" },
+          "direction": { "enum": ["outbound", "inbound-webhook"] },
+          "trigger": { "type": "string" },
+          "purpose": { "type": "string" },
+          "service": { "type": "string" },
+          "timeoutMs": { "type": "integer" },
+          "retry": { "type": "object" },
+          "idempotency": { "type": "object" },
+          "secrets": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "services": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "class", "reason", "entities"],
+        "properties": {
+          "id": { "type": "string" },
+          "class": { "type": "string" },
+          "reason": { "type": "string" },
+          "alternativesConsidered": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "entities": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "requests": { "type": "object" },
+    "responses": { "type": "object" },
+    "implementationPlan": { "type": "object" }
+  }
+}

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

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