@shanyucoder/flowgrid 0.1.11 → 0.1.13

package/engines/spec/lib/audit-interaction-cases.mjs

@@ -0,0 +1,186 @@
+/**
+ * Two-step audit for bundle interactionCases (invoked only from audit-bundle-gaps on *.bundle.yaml).
+ * See harness/docs/extracts/agent-design-context.md — do not run against ir/spec or ir/design.
+ */
+
+function countMutationActions(design) {
+  const actions = design?.actions
+  if (!Array.isArray(actions)) return 0
+  return actions.filter((a) => a && (a.executionContract || a.apiRef)).length
+}
+
+export function interactionCasesComplexityTriggers(bundle) {
+  const design = bundle?.design ?? {}
+  const statuses = design?.stateMatrix?.recordStatuses
+  const statusCount = Array.isArray(statuses) ? statuses.length : 0
+  const mutations = countMutationActions(design)
+  const scenarios = bundle?.userStories?.scenarios
+  const scenarioCount = Array.isArray(scenarios) ? scenarios.length : 0
+  const listOnly =
+    design?.codegen?.profile === 'list' ||
+    String(bundle?.gen?.codegen?.profile || '') === 'list'
+
+  return {
+    complex:
+      statusCount >= 3 ||
+      mutations >= 2 ||
+      (!listOnly && scenarioCount >= 4) ||
+      Boolean(design?.stateMatrix?.behaviors?.length >= 3),
+    statusCount,
+    mutations,
+    scenarioCount,
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} bundle parsed bundle YAML
+ * @param {{ addGap: Function, addConfirm: Function, addWarning: Function }} hooks
+ */
+export function auditInteractionCases(bundle, hooks) {
+  const { addGap, addConfirm, addWarning } = hooks
+  const ic = bundle?.interactionCases
+  const { complex, statusCount, mutations } = interactionCasesComplexityTriggers(bundle)
+
+  if (ic == null) {
+    if (!complex) return
+    addConfirm(
+      'CONFIRM_INTERACTION_CASES_POLICY',
+      'interactionCases',
+      'Screen has complex state/actions — declare interactionCases (IC-* + sequenceDiagram)?',
+      [
+        '(Recommended) Yes — set interactionCases.policy: required and items[]',
+        'No — simple screen (set interactionCases.policy: skip + skipReason)',
+        'Other — note in qa/',
+      ],
+      0,
+    )
+    return
+  }
+
+  const policy = ic.policy
+  if (policy === 'skip') {
+    if (!String(ic.skipReason || '').trim()) {
+      addWarning(
+        'INTERACTION_CASES_SKIP_NO_REASON',
+        'interactionCases.skipReason',
+        'interactionCases.policy is skip but skipReason is empty.',
+        'Declare skipReason explaining why L2 sequences are not needed.',
+      )
+    }
+    return
+  }
+
+  const items = Array.isArray(ic.items) ? ic.items : []
+
+  if (policy === 'required' && items.length === 0) {
+    addGap(
+      'INTERACTION_CASES_ITEMS_MISSING',
+      'critical',
+      'interactionCases.items',
+      'interactionCases.policy is required but items[] is empty.',
+      'Add at least one IC-* item with description and sequenceDiagram.',
+    )
+    return
+  }
+
+  if (items.length === 0) return
+
+  const actionIds = new Set(
+    (bundle?.design?.actions || [])
+      .map((a) => a?.id)
+      .filter(Boolean),
+  )
+  const statuses = new Set(bundle?.design?.stateMatrix?.recordStatuses || [])
+
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i]
+    const base = `interactionCases.items[${i}]`
+    if (!item?.id) {
+      addGap(
+        'INTERACTION_CASES_MISSING_ID',
+        'critical',
+        `${base}.id`,
+        'Interaction case missing id (use IC-*).',
+        'Declare id: IC-SUBMIT-HAPPY',
+      )
+    } else if (!/^IC-[A-Z0-9][A-Z0-9-]*$/i.test(String(item.id))) {
+      addWarning(
+        'INTERACTION_CASES_ID_FORMAT',
+        `${base}.id`,
+        `Interaction case id "${item.id}" should match IC-* pattern.`,
+        'Rename to IC-<DOMAIN>-<CASE> (e.g. IC-SUBMIT-409).',
+      )
+    }
+    if (!String(item?.title || '').trim()) {
+      addGap(
+        'INTERACTION_CASES_MISSING_TITLE',
+        'critical',
+        `${base}.title`,
+        'Interaction case missing title.',
+        'Add short title for reviewers and agents.',
+      )
+    }
+    if (!String(item?.description || '').trim()) {
+      addGap(
+        'INTERACTION_CASES_MISSING_DESCRIPTION',
+        'critical',
+        `${base}.description`,
+        'Interaction case missing description (user case prose).',
+        'Describe user steps and expected UI/API feedback.',
+      )
+    }
+    const seq = String(item?.sequenceDiagram || '')
+    if (!seq.includes('sequenceDiagram')) {
+      addGap(
+        'INTERACTION_CASES_MISSING_SEQUENCE',
+        'critical',
+        `${base}.sequenceDiagram`,
+        'Interaction case missing Mermaid sequenceDiagram.',
+        'Add sequenceDiagram with alt/else for error paths when applicable.',
+      )
+    } else if (!/alt\s+/i.test(seq) && complex) {
+      addWarning(
+        'INTERACTION_CASES_NO_ALT',
+        `${base}.sequenceDiagram`,
+        'Sequence diagram has no alt/else block — recommend at least one error branch.',
+        'Model validation, 409, or timeout with alt/else.',
+      )
+    }
+    const actionId = item?.links?.actionId
+    if (actionId && actionIds.size && !actionIds.has(actionId)) {
+      addWarning(
+        'INTERACTION_CASES_UNKNOWN_ACTION',
+        `${base}.links.actionId`,
+        `links.actionId "${actionId}" not found in design.actions.`,
+        'Align with an existing action id or add the action.',
+      )
+    }
+    const st = item?.links?.recordStatus
+    if (st && statuses.size && !statuses.has(st)) {
+      addWarning(
+        'INTERACTION_CASES_UNKNOWN_STATUS',
+        `${base}.links.recordStatus`,
+        `links.recordStatus "${st}" not in stateMatrix.recordStatuses.`,
+        `Use one of: ${[...statuses].join(', ')}`,
+      )
+    }
+  }
+
+  if (policy === 'required' && mutations >= 2 && items.length < mutations) {
+    addWarning(
+      'INTERACTION_CASES_FEW_ITEMS',
+      'interactionCases.items',
+      `Only ${items.length} interaction case(s) for ${mutations} mutation action(s).`,
+      'Consider one IC-* per critical mutation path (happy + conflict).',
+    )
+  }
+
+  if (complex && !policy) {
+    addWarning(
+      'INTERACTION_CASES_POLICY_UNSET',
+      'interactionCases.policy',
+      'interactionCases present but policy not set to required or skip.',
+      'Set policy: required or policy: skip with skipReason.',
+    )
+  }
+}

package/engines/spec/lib/bundle-ir.mjs

@@ -20,6 +20,7 @@ import {
 import { applyOpenQaField } from './open-qa.mjs'
 import { applyDesignApiFrom01 } from './hydrate-design-api.mjs'
 import { isPlaceholderLegacy, projectBusinessPage } from './project-business-layout.mjs'
+import { applyInteractionCasesToIr } from './interaction-cases.mjs'
 
 export function bundlePageId(bundle) {
   const v = bundle?.['page-id'] ?? bundle?.pageId ?? bundle?.id
@@ -39,6 +40,12 @@ export function buildIrFromBundle(bundle) {
   const pageId = bundlePageId(bundle)
   const legacy = { id: pageId, ...(bundle.legacy ?? {}) }
   const design = buildDesignIr(bundle, designSpec, gen)
+  if (bundle.interactionCases != null) {
+    delete spec.interactionCases
+    applyInteractionCasesToIr(spec, design, bundle.interactionCases)
+  } else if (spec.interactionCases) {
+    delete spec.interactionCases
+  }
 
   return { spec, legacy, design, designSpec, gen }
 }

package/engines/spec/lib/bundle-schema.mjs

@@ -15,6 +15,7 @@ export const BUNDLE_META_KEYS = [
   'scopeIn',
   'nonGoals',
   'userFlows',
+  'interactionCases',
   'nfr',
   'userStories',
   'specOrigin',

package/engines/spec/lib/interaction-cases.mjs

@@ -0,0 +1,46 @@
+/**
+ * Split bundle interactionCases → ir/spec (prose) + ir/design (sequenceDiagram only).
+ */
+
+/**
+ * @param {unknown} interactionCases
+ * @returns {{ specPart: object|null, designPart: object|null }}
+ */
+export function partitionInteractionCasesForIr(interactionCases) {
+  if (!interactionCases || typeof interactionCases !== 'object') {
+    return { specPart: null, designPart: null }
+  }
+  const { policy, skipReason, items } = interactionCases
+  const specPart = {
+    ...(policy != null ? { policy } : {}),
+    ...(skipReason != null && String(skipReason).trim() ? { skipReason } : {}),
+    items: Array.isArray(items)
+      ? items.map((item) => {
+          if (!item || typeof item !== 'object') return item
+          const { id, title, description, links } = item
+          return { id, title, description, links }
+        })
+      : [],
+  }
+  const designItems = Array.isArray(items)
+    ? items
+        .filter((item) => item && typeof item === 'object' && item.sequenceDiagram)
+        .map(({ id, sequenceDiagram }) => ({ id, sequenceDiagram }))
+    : []
+  const designPart = designItems.length ? { items: designItems } : null
+  return { specPart, designPart }
+}
+
+/**
+ * @param {Record<string, unknown>} spec
+ * @param {Record<string, unknown>} design
+ * @param {unknown} interactionCases from bundle
+ */
+export function applyInteractionCasesToIr(spec, design, interactionCases) {
+  const { specPart, designPart } = partitionInteractionCasesForIr(interactionCases)
+  if (!specPart && !designPart) return
+  if (specPart && (specPart.policy || specPart.skipReason || specPart.items?.length)) {
+    spec.interactionCases = specPart
+  }
+  if (designPart) design.interactionCases = designPart
+}

package/engines/spec/split-bundle.mjs

@@ -34,7 +34,7 @@ async function main() {
         const mdRel = mdOut ? path.relative(process.cwd(), mdOut) : null
         const genDir = mdOut ? path.dirname(mdOut) : null
         const extra = genDir
-          ? ['data-model.md', 'api.md']
+          ? ['data-model.md', 'api.md', 'design.md']
               .filter((name) => fs.existsSync(path.join(genDir, name)))
               .map((name) => path.relative(process.cwd(), path.join(genDir, name)))
           : []

package/harness/be/adapters/dotnet-integration/skills/framework-rules-be/SKILL.md

@@ -8,9 +8,9 @@ disable-model-invocation: true
 
 **Owner:** Platform DNA (`--type=be|monolith --be-adapter=dotnet-integration`)
 
-.NET integration host · bộ code grill/gen first when applicable.
+.NET integration host · code repo grill/gen first when applicable.
 
-## Gen trước (code)
+## Gen first (code)
 
 1. Prefer codegen / existing templates before free-form scaffolding
 2. AI fills gaps only — do not duplicate generated surfaces

package/harness/be/adapters/fastapi/skills/framework-rules-be/SKILL.md

@@ -8,11 +8,11 @@ disable-model-invocation: true
 
 **Owner:** Platform DNA (`--type=be|monolith --be-adapter=fastapi`)
 
-FastAPI · modular packages · bộ code grill/gen first.
+FastAPI · modular packages · code repo grill/gen first.
 
-## Gen trước (code)
+## Gen first (code)
 
-1. bộ code `gen` / repo shim from IR already grilled
+1. code repo `gen` / repo shim from IR already grilled
 2. AI only fills `#needs-*` / gaps not yet in `registries/`
 3. Do not hand-write boilerplate codegen already covers
 

package/harness/be/adapters/laravel/skills/framework-rules-be/SKILL.md

@@ -8,11 +8,11 @@ disable-model-invocation: true
 
 **Owner:** Platform DNA (`--type=be|monolith --be-adapter=laravel`)
 
-Laravel · `nwidart/laravel-modules` (modules-v1) · bộ code grill/gen first.
+Laravel · `nwidart/laravel-modules` (modules-v1) · code repo grill/gen first.
 
-## Gen trước (code)
+## Gen first (code)
 
-1. bộ code `gen` / repo shim from IR already grilled
+1. code repo `gen` / repo shim from IR already grilled
 2. AI only fills `#needs-*` / gaps not yet in registries
 3. Do not hand-write module scaffolding codegen already covers
 

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

@@ -1,12 +1,12 @@
 ---
 name: api
-description: /api — backend API generation through bộ code BE adapters.
+description: /api — backend API generation through BE code repo adapters.
 disable-model-invocation: true
 ---
 
 # /api — Backend API
 
-**Owner:** bộ code (`--type=be`)  
+**Owner:** code repo (`--type=be`)  
 **Adapters:** `fastapi` · `laravel` · `dotnet-integration` · `nestjs`
 
 ## Generate
@@ -52,7 +52,7 @@ FE models (not this skill): `flowgrid contract-gen:dry -- --spec /path/to/ir/des
 
 ## Route
 
-Architecture/C4 → bộ docs (`FLOWGRID_DOCS_ROOT`); IR via explicit `--spec` /
+Architecture/C4 → docs hub (`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
@@ -87,7 +87,7 @@ warns and uses entity-local CRUD defaults.
 
 ```text
 if ArtifactGraph available: allowlist/recommend API generation
-else: execute bộ code adapter directly
+else: execute code repo adapter directly
 
 if CodeGraph available for this checkout (`codegraph-<key>`): inspect existing module conventions/callers
 else: targeted repository search — never a workspace-parent graph

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

@@ -1,12 +1,12 @@
 ---
 name: api-unit
-description: /unit — backend API unit test generation via bộ code BE adapters.
+description: /unit — backend API unit test generation via BE code repo adapters.
 disable-model-invocation: true
 ---
 
 # /unit — Backend API Unit Tests
 
-**Owner:** bộ code (`--type=be`)
+**Owner:** code repo (`--type=be`)
 **Adapters:** `fastapi` · `laravel` · `nestjs`
 
 > `dotnet-integration` emits test source during its primary API pass; it has no
@@ -48,7 +48,7 @@ Requires a prior `01-backend-spec.yaml` under the docs hub API folder.
 
 ## Route
 
-Architecture/C4 → bộ docs (`FLOWGRID_DOCS_ROOT`); spec via explicit `--spec` /
+Architecture/C4 → docs hub (`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
@@ -64,7 +64,7 @@ hints only.
 
 ```text
 if ArtifactGraph available: allowlist/recommend API unit generation
-else: execute bộ code adapter directly
+else: execute code repo adapter directly
 
 if CodeGraph available for this checkout (`codegraph-<key>`): inspect existing test conventions
 else: targeted repository search — never a workspace-parent graph

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

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Run after `npm run codegen:api:dry` / `flowgrid api-gen:dry` and after implementation.
 
-**Owner:** bộ code (`--type=be`). Docs hub is **read-only**.
+**Owner:** code repo (`--type=be`). Docs hub is **read-only**.
 
 ## Target / ID Resolution Rule
 
@@ -36,7 +36,7 @@ Check:
 - Writes are transaction-safe; async retries are idempotent.
 - Generated placeholders are replaced before ship.
 
-**CLI (lượng):** `flowgrid audit api` on `01`; when portal bundle exists → `flowgrid audit fe-be` on sibling `*.bundle.yaml`.
+**CLI (quantitative):** `flowgrid audit api` on `01`; when portal bundle exists → `flowgrid audit fe-be` on sibling `*.bundle.yaml`.
 
 ## Accelerators (optional)
 
@@ -47,7 +47,7 @@ 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
+architecture IDs / C4 → docs hub (FLOWGRID_DOCS_ROOT), never CodeGraph
 ```
 
 Missing accelerators never block the audit. Complete each scoped model or

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # /grill-unit
 
-**Owner:** bộ code · audit gate before BE unit test generation.
+**Owner:** code repo · 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.
@@ -50,7 +50,7 @@ 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
+architecture IDs / C4 → docs hub (FLOWGRID_DOCS_ROOT), never CodeGraph
 ```
 
 Missing accelerators never block the grill. Complete each scoped model or

package/harness/common/rules/artifactgraph.mdc

@@ -14,9 +14,9 @@ alwaysApply: false
 
 ## Cross-repo routing
 
-- Architecture ID / C4 → bộ docs (`FLOWGRID_DOCS_ROOT`), not CodeGraph and not
+- Architecture ID / C4 → docs hub (`FLOWGRID_DOCS_ROOT`), not CodeGraph and not
   ArtifactGraph.
-- IR / registry / generation → bộ code / bộ test pointers
+- IR / registry / generation → code repo / tests hub pointers
   (`FLOWGRID_DOCS_ROOT`, `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`).
 - Symbol / call-graph of repo X → `codegraph-<key>` MCP for checkout X.
 - ArtifactGraph is local-only: never follow those pointers, never read repo

package/harness/common/rules/cross-repo-index.mdc

@@ -9,13 +9,13 @@ Do not merge every repository into a single workspace graph (the parent folder
 must never be indexed). "Cross-repo" means a skill/rule knows how to reach the
 **correct per-repo index**, one repository at a time.
 
-**Owner:** Platform DNA. FlowGrid harness rules (bộ docs, bộ process, …) install this same
+**Owner:** Platform DNA. FlowGrid harness rules (docs hub, process hub, …) install this same
 filename only when DNA is absent, so a destination never carries duplicate
 `alwaysApply` routing rules under different names.
 
 Route by intent:
 
-- Need an architecture ID or C4 path -> bộ docs MCP (`FLOWGRID_DOCS_ROOT`). Never
+- Need an architecture ID or C4 path -> docs hub MCP (`FLOWGRID_DOCS_ROOT`). Never
   CodeGraph for architecture Markdown.
 - Need IR / registry / generation -> the pointer kit
   (`FLOWGRID_DOCS_ROOT`, `FLOWGRID_DOCS_ROOT`, `FLOWGRID_TESTS_DOC`).

package/harness/common/rules/platform-code-size.mdc

@@ -8,17 +8,17 @@ alwaysApply: false
 
 Soft limits — split in the same PR when exceeded.
 
-| Vượt ~200 dòng/file | Tách | Gợi ý Tag DSL (`/docs-mark`) |
+| Exceeds ~200 lines/file | Split | Suggest Tag DSL (`/docs-mark`) |
 |---------------------|------|------------------------------|
-| Page `.vue` | Composable + sub-component | `#needs-component: sub-{name}:MoXxx` hoặc `#common-ui` |
+| Page `.vue` | Composable + sub-component | `#needs-component: sub-{name}:MoXxx` or `#common-ui` |
 | Composable | `useXxxForm`, `useXxxList`, … | `#common-ui` / `#needs-ui` |
-| Service / store | File theo aggregate; action phức tạp → service | `#cross-service` / `#cross-entity-service` / `#needs-service` |
+| Service / store | File per aggregate; complex action → service | `#cross-service` / `#cross-entity-service` / `#needs-service` |
 | E2E spec | Page Object + helper | `#e2e-test` bundle split |
 
-| Vượt ~20 dòng/function | Tách | Gợi ý Tag DSL (`/docs-mark`) |
+| Exceeds ~20 lines/function | Split | Suggest Tag DSL (`/docs-mark`) |
 |------------------------|------|------------------------------|
 | Submit handler | `buildPayload`, `validateBeforeSubmit`, `handleApiError` | `#needs-service` / local helper |
 | Map/transform | Pure helpers / computed | `#derived-data` |
 
 No padding files with blank lines. Component split: `platform-component-split.mdc`.
-Khi file/function chạm ngưỡng vượt giới hạn, AI Agent cần chủ động đề xuất gán tag tương ứng (thông qua `/docs-mark`) và cập nhật registry (`registries/design.registry.json` hoặc `registries/common.registry.json`) để tái sử dụng sau này.
+When a file or function hits an exceed threshold, the agent should proactively propose the matching tag (via `/docs-mark`) and update the registry (`registries/design.registry.json` or `registries/common.registry.json`) for reuse later.

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

@@ -6,7 +6,7 @@ alwaysApply: false
 
 # Harness State
 
-- `feature_list.json` — scope, không tự đánh done khi chưa verify
-- `progress.md` — handoff session tiếp theo
-- `registries/page-lifecycle.registry.json` + `base-docs/platform/toolchain/PAGE-LIFECYCLE.md` — stage cao nhất từng route; `portal:gen` / `portal:remove` / `portal:lifecycle sync` tự cập nhật
-- Khi command public cập nhật phase, ghi rõ: command, file đã đổi, verify đã chạy/chưa chạy, blocker còn lại.
+- `feature_list.json` — scope; do not mark done without verification
+- `progress.md` — handoff for the next session
+- `registries/page-lifecycle.registry.json` + `base-docs/platform/toolchain/PAGE-LIFECYCLE.md` — highest stage per route; `portal:gen` / `portal:remove` / `portal:lifecycle sync` update automatically
+- When a public command updates phase, record clearly: command, files changed, verify run or not, remaining blockers.

package/harness/common/skills/business-impact-review/SKILL.md

@@ -90,7 +90,7 @@ if CodeGraph available: changed symbols + callers + call graph — for repo X us
   open repo's index; unindexed repo → report `cd <root> && codegraph init`
 else: targeted repository search/read
 
-if bộ docs available: map process steps to CMP/CTR/FLOW docs via FLOWGRID_DOCS_ROOT
+if docs hub available: map process steps to CMP/CTR/FLOW docs via FLOWGRID_DOCS_ROOT
   (never CodeGraph for architecture Markdown)
 else: repository conventions/search
 

package/harness/common/skills/configure-repo-maps/SKILL.md

@@ -55,6 +55,6 @@ legacy ERP at D:\legacy\erp, key legacy-erp
 ## After Write
 
 1. Compare with `.flowgrid/config.json` (init SSOT): `flowgrid repo-maps check`.
-2. If paths conflict with init/harness MCP: `flowgrid repo-maps align` (member chốt từng hub `docs` / `tests`).
+2. If paths conflict with init/harness MCP: `flowgrid repo-maps align` (member confirms each hub `docs` / `tests`).
 3. One-way refresh from config: `flowgrid repo-maps sync --from-config` then `flowgrid harness sync`.
 4. Optional CodeGraph: `platform-dna codegraph:wire` · `codegraph init` per checkout.

package/harness/common/skills/docs-mark/SKILL.md

@@ -31,13 +31,13 @@ fallbacks.
 | UI | `registries/design.registry.json` | `#needs-component:` `#needs-ui:` `#shell:` |
 | Logic | `registries/common.registry.json` | `#common:*` `#needs-common:*` |
 
-Executable registry validation is **bộ code FE** (or product scripts on the
+Executable registry validation is **FE code repo** (or product scripts on the
 FE checkout). On docs hub:
 
 ```text
 if ArtifactGraph available:
   artifactgraph_allowlist_check(registryValidate|commonRegistry)
-  artifactgraph_recommend_command → hand off to bộ code FE
+  artifactgraph_recommend_command → hand off to FE code repo
 else:
   note pending FE registry validate; do not invent local shell fallbacks
 ```
@@ -58,8 +58,8 @@ else:
 
 ## Handoff
 
-bộ code FE / product: `flowgrid gen:dry` (or repo shim) after marks change,
-when that lane is available. Missing bộ code is a pending handoff, not a
+FE code repo / product: `flowgrid gen:dry` (or repo shim) after marks change,
+when that lane is available. Missing code repo is a pending handoff, not a
 docs failure.
 
 ## Compatibility