@shanyucoder/flowgrid 0.1.5 → 0.1.8

package/engines/spec/lib/audit-e2e-coverage.mjs

@@ -9,6 +9,9 @@ import fs from 'fs';
 import path from 'path';
 import { parse } from 'yaml';
 import { resolveTestsDocsRoot } from '../../shared/flowgrid-tests-docs.mjs';
+import { resolveFlowgridContext } from '../../shared/resolve-flowgrid-context.mjs';
+import { playwrightScanRoots } from '../../shared/e2e-output-layout.mjs';
+import { resolveHubId } from '../../testcase/runners/lib/resolve-hub-id.mjs';
 
 const TC_ID_PATTERN = /^TC-[A-Z0-9][A-Z0-9-]*$/;
 const DESCRIBE_TC_RE = /test\.describe\s*\(\s*['"](TC-[^'"]+)['"]/g;
@@ -42,7 +45,21 @@ function walkFiles(root, onFile) {
 /**
  * @param {string} testsRoot
  */
-export function scanPlaywrightTests(testsRoot) {
+function mergeScanState(into, from) {
+  for (const rec of from.specFiles) {
+    if (!into.specFiles.includes(rec)) into.specFiles.push(rec);
+  }
+  for (const [tcId, files] of from.tcIdToFiles.entries()) {
+    const list = into.tcIdToFiles.get(tcId) ?? [];
+    for (const f of files) {
+      if (!list.includes(f)) list.push(f);
+    }
+    into.tcIdToFiles.set(tcId, list);
+  }
+  for (const id of from.referencedTcIds) into.referencedTcIds.add(id);
+}
+
+function scanPlaywrightTestsSingle(testsRoot) {
   const specFiles = [];
   const tcIdToFiles = new Map();
 
@@ -77,6 +94,10 @@ export function scanPlaywrightTests(testsRoot) {
 
   const referencedTcIds = new Set(tcIdToFiles.keys());
 
+  return buildScanResult(specFiles, tcIdToFiles, referencedTcIds);
+}
+
+function buildScanResult(specFiles, tcIdToFiles, referencedTcIds) {
   return {
     specFiles,
     specFileCount: specFiles.length,
@@ -92,6 +113,22 @@ export function scanPlaywrightTests(testsRoot) {
   };
 }
 
+/**
+ * @param {string | string[]} testsRootOrRoots
+ */
+export function scanPlaywrightTests(testsRootOrRoots) {
+  const roots = Array.isArray(testsRootOrRoots) ? testsRootOrRoots : [testsRootOrRoots];
+  const existing = roots.filter((r) => r && fs.existsSync(r));
+  if (!existing.length) {
+    return buildScanResult([], new Map(), new Set());
+  }
+  let merged = scanPlaywrightTestsSingle(existing[0]);
+  for (let i = 1; i < existing.length; i++) {
+    mergeScanState(merged, scanPlaywrightTestsSingle(existing[i]));
+  }
+  return merged;
+}
+
 /**
  * @param {string} casesRoot
  * @param {{ screen?: string }} [filter]
@@ -150,11 +187,12 @@ function addGap(gaps, code, severity, fieldPath, message, suggestedFix) {
 }
 
 /**
- * @param {{ tcDocuments: Array<{ path: string; id: string; screen: string | null; matrix: unknown[] }>; e2eRoot: string; strict?: boolean; strictMatrix?: boolean }} opts
+ * @param {{ tcDocuments: Array<{ path: string; id: string; screen: string | null; matrix: unknown[] }>; e2eRoot?: string; e2eScanRoots?: string[]; strict?: boolean; strictMatrix?: boolean }} opts
  */
 export function auditE2eCoverage(opts) {
-  const { tcDocuments, e2eRoot, strict = false, strictMatrix = false } = opts;
-  const pw = scanPlaywrightTests(e2eRoot);
+  const { tcDocuments, e2eRoot, e2eScanRoots, strict = false, strictMatrix = false } = opts;
+  const scanRoots = e2eScanRoots ?? (e2eRoot ? [e2eRoot] : []);
+  const pw = scanPlaywrightTests(scanRoots);
   const gaps = [];
   const missingInPlaywright = [];
   const matrixRowsUncovered = [];
@@ -268,21 +306,21 @@ export function auditE2eCoverage(opts) {
 }
 
 function parseCliArgs(argv) {
-  let e2eRoot = null;
-  let testsDocs = null;
+  const ctx = resolveFlowgridContext({ argv });
+  let e2eRoot = ctx.e2eRoot;
+  let testsDocs = ctx.testsDocs;
   let screen = null;
   let strict = false;
   let strictMatrix = false;
+  let hubId = null;
   const tcFiles = [];
 
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--e2e-root' && argv[i + 1]) {
-      e2eRoot = path.resolve(process.cwd(), argv[++i]);
-    } else if (a === '--tests-docs' && argv[i + 1]) {
-      testsDocs = path.resolve(process.cwd(), argv[++i]);
-    } else if (a === '--screen' && argv[i + 1]) {
-      screen = argv[++i];
+  for (let i = 0; i < ctx.argv.length; i++) {
+    const a = ctx.argv[i];
+    if (a === '--screen' && ctx.argv[i + 1]) {
+      screen = ctx.argv[++i];
+    } else if (a === '--id' && ctx.argv[i + 1]) {
+      hubId = ctx.argv[++i];
     } else if (a === '--strict') {
       strict = true;
       strictMatrix = true;
@@ -291,22 +329,32 @@ function parseCliArgs(argv) {
     } else if (a === '--help' || a === '-h') {
       return { help: true };
     } else if (!a.startsWith('-')) {
-      tcFiles.push(path.resolve(process.cwd(), a));
+      tcFiles.push(path.resolve(ctx.projectRoot, a));
     }
   }
 
-  return { e2eRoot, testsDocs, screen, strict, strictMatrix, tcFiles };
+  return {
+    e2eRoot,
+    testsDocs,
+    screen,
+    strict,
+    strictMatrix,
+    tcFiles,
+    hubId,
+    projectRoot: ctx.projectRoot,
+  };
 }
 
 function printUsage() {
   console.log(
     [
-      'Usage: node engines/spec/lib/audit-e2e-coverage.mjs --e2e-root <playwright-dir> [options]',
-      '       flowgrid audit e2e --e2e-root <dir> --tests-docs <tests-hub> [--screen W-*]',
-      '       flowgrid audit e2e --e2e-root <dir> <TC-*.yaml> [more…]',
+      'Usage: flowgrid audit e2e [--id TC-*|W-*|suite] [options]',
+      '       flowgrid audit e2e <TC-*.yaml> [more…]',
       '',
       'Options:',
-      '  --tests-docs   Tests hub (TC YAML); or set FLOWGRID_TESTS_DOC',
+      '  --e2e-root     Playwright scan root (default: config/MCP FLOWGRID_E2E_ROOT)',
+      '  --tests-docs   Tests hub (TC YAML); or FLOWGRID_TESTS_DOC / config',
+      '  --id           Resolve TC YAML via tests hub index (TC-*, screen W-*, suite)',
       '  --screen W-*   Filter TC docs by refs.screen',
       '  --strict       Treat missing TC spec + matrix gaps as critical',
       '  --strict-matrix  Require each testMatrix row signal in Playwright text',
@@ -327,19 +375,27 @@ if (parsed.help) {
   process.exit(0);
 }
 
-if (!parsed.e2eRoot) {
-  console.error(JSON.stringify({ error: '--e2e-root is required (Playwright specs directory)' }));
-  process.exit(1);
-}
-
-if (!fs.existsSync(parsed.e2eRoot)) {
-  console.error(JSON.stringify({ error: `e2e-root not found: ${parsed.e2eRoot}` }));
+const e2eScanRoots = playwrightScanRoots(parsed.projectRoot, parsed.e2eRoot).filter((r) =>
+  fs.existsSync(r),
+);
+if (!e2eScanRoots.length) {
+  console.error(
+    JSON.stringify({
+      error:
+        'No e2e scan directory found — set frontend/backend.e2eRoot, FLOWGRID_E2E_ROOT, or pass --e2e-root',
+    }),
+  );
   process.exit(1);
 }
 
 let tcDocuments = [];
 try {
-  if (parsed.tcFiles.length) {
+  if (parsed.hubId) {
+    const resolved = resolveHubId(parsed.projectRoot, parsed.hubId, 'testcase');
+    for (const f of resolved.paths) {
+      tcDocuments.push(loadTcDocument(f));
+    }
+  } else if (parsed.tcFiles.length) {
     for (const f of parsed.tcFiles) {
       if (!fs.existsSync(f)) {
         console.error(JSON.stringify({ error: `TC file not found: ${f}` }));
@@ -352,7 +408,7 @@ try {
     if (!testsDocs) {
       console.error(
         JSON.stringify({
-          error: 'Provide --tests-docs, FLOWGRID_TESTS_DOC, or explicit TC-*.yaml paths',
+          error: 'Provide --id, --tests-docs, FLOWGRID_TESTS_DOC, or explicit TC-*.yaml paths',
         }),
       );
       process.exit(1);
@@ -370,10 +426,12 @@ try {
 
 const report = auditE2eCoverage({
   tcDocuments,
-  e2eRoot: parsed.e2eRoot,
+  e2eScanRoots,
+  e2eRoot: e2eScanRoots[0],
   strict: parsed.strict,
   strictMatrix: parsed.strictMatrix,
 });
+report.e2eScanRoots = e2eScanRoots;
 if (parsed.testsDocs ?? resolveTestsDocsRoot()) {
   report.testsDocs = parsed.testsDocs ?? resolveTestsDocsRoot();
 }

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

@@ -12,6 +12,8 @@ export const BUNDLE_META_KEYS = [
   'status',
   'owner',
   'summary',
+  'successMetrics',
+  'nonGoals',
   'userStories',
   'specOrigin',
   'grillStatus'
@@ -36,7 +38,8 @@ export const DESIGN_LAYOUT_KEYS = [
   'behavior',
   'actions',
   'deviations',
-  'i18n'
+  'i18n',
+  'dataModel'
 ]
 
 /**

package/engines/spec/split-bundle.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import fs from 'node:fs'
 import path from 'node:path'
 import { checkSplitBundle, splitBundleFile } from './lib/bundle-ir.mjs'
 import { writeBundleMarkdownFile } from '../docs/lib/render-bundle-markdown.mjs'
@@ -30,7 +31,16 @@ async function main() {
       } else {
         const { irDir } = await splitBundleFile(resolved)
         const mdOut = await writeBundleMarkdownFile(resolved)
-        const mdNote = mdOut ? ` + ${path.relative(process.cwd(), mdOut)}` : ' (no MD; missing ir/spec.yaml)'
+        const mdRel = mdOut ? path.relative(process.cwd(), mdOut) : null
+        const genDir = mdOut ? path.dirname(mdOut) : null
+        const extra = genDir
+          ? ['data-model.md', 'api.md']
+              .filter((name) => fs.existsSync(path.join(genDir, name)))
+              .map((name) => path.relative(process.cwd(), path.join(genDir, name)))
+          : []
+        const mdNote = mdRel
+          ? ` + ${mdRel}${extra.length ? ` + ${extra.join(' + ')}` : ''}`
+          : ' (no MD; missing ir/spec.yaml)'
         console.log(`spec:split: ${path.relative(process.cwd(), resolved)} → ${path.relative(process.cwd(), irDir)}/${mdNote}`)
       }
     } catch (error) {

package/engines/testcase/runners/generate-api.mjs

@@ -2,33 +2,34 @@ import path from 'node:path'
 
 import Handlebars from 'handlebars'
 
-import { listFeatureTestcases, readTestcaseFile } from './lib/read-testcase.mjs'
+import { readTestcaseFile } from './lib/read-testcase.mjs'
 import { buildApiTestcaseContext, isApiE2eTestcase } from './lib/api-plan.mjs'
 import { renderTemplate } from './lib/render.mjs'
 import { writeOutputs } from './lib/write-files.mjs'
 import { resolveHubId, resolveProjectRoot, loadTestsIndex } from './lib/resolve-hub-id.mjs'
-import { extractTestsDocsFlag, ENV_TESTS_DOC } from '../../shared/flowgrid-tests-docs.mjs'
+import { ENV_TESTS_DOC } from '../../shared/flowgrid-tests-docs.mjs'
+import {
+  bootstrapTestcaseRun,
+  applyApiOutputLayout,
+} from './lib/bootstrap-context.mjs'
 
-const root = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+const boot = bootstrapTestcaseRun(process.argv.slice(2))
+const root = boot.ctx.projectRoot
+const codegenLayout = boot.layout
 
 Handlebars.registerHelper('json', (value) => JSON.stringify(value, null, 2))
 
 function parseArgs(argv) {
-  const { argv: stripped, testsDocs } = extractTestsDocsFlag(argv)
-  if (testsDocs) {
-    process.env[ENV_TESTS_DOC] = testsDocs
-  }
-
   const options = { dryRun: false, force: false, testcase: null, feature: null, id: null, all: false }
 
-  for (let i = 0; i < stripped.length; i++) {
-    const arg = stripped[i]
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
     if (arg === '--dry-run' || arg === '--dry') options.dryRun = true
     else if (arg === '--force') options.force = true
     else if (arg === '--all') options.all = true
-    else if (arg === '--testcase') options.testcase = stripped[++i]
-    else if (arg === '--feature') options.feature = stripped[++i]
-    else if (arg === '--id') options.id = stripped[++i]
+    else if (arg === '--testcase') options.testcase = argv[++i]
+    else if (arg === '--feature') options.feature = argv[++i]
+    else if (arg === '--id') options.id = argv[++i]
     else if (!arg.startsWith('-') && !options.testcase && !options.feature && !options.id && !options.all) {
       options.testcase = arg
     }
@@ -55,12 +56,14 @@ async function generateOne(testcasePath, options) {
   }
 
   const ctx = buildApiTestcaseContext(testcase, testcaseFile)
+  applyApiOutputLayout(ctx, codegenLayout)
   const specContent = await renderTemplate('api.spec.ts.hbs', ctx)
   const outputs = [{ relativePath: ctx.outputs.spec, content: specContent }]
 
   const { written, skipped } = await writeOutputs(root, outputs, {
     dryRun: options.dryRun,
     force: options.force,
+    allowedRelRoots: codegenLayout.allowedRelRoots,
   })
 
   console.log(`testcase-gen:api id=${ctx.testcaseId} module=${ctx.module}`)
@@ -76,13 +79,13 @@ async function generateOne(testcasePath, options) {
 }
 
 async function main() {
-  const options = parseArgs(process.argv.slice(2))
+  const options = parseArgs(boot.argv)
   const paths = []
 
   if (options.all) {
-    const testsRoot = process.env[ENV_TESTS_DOC]
-      ? path.resolve(process.env[ENV_TESTS_DOC])
-      : resolveProjectRoot(root, 'tests')
+    const testsRoot = boot.ctx.testsDocs
+      ?? (process.env[ENV_TESTS_DOC] ? path.resolve(process.env[ENV_TESTS_DOC]) : null)
+      ?? resolveProjectRoot(root, 'tests')
     const index = loadTestsIndex(testsRoot)
     for (const [id, rel] of Object.entries(index.codeIds || {})) {
       if (id.startsWith('TC-')) paths.push(path.resolve(testsRoot, rel))
@@ -91,12 +94,9 @@ async function main() {
     paths.push(path.resolve(root, options.testcase))
   } else if (options.feature || options.id) {
     const hubId = options.id ?? options.feature
-    const resolved = await resolveHubId(root, hubId)
-    if (resolved.kind === 'testcase') {
-      paths.push(resolved.absPath)
-    } else if (resolved.kind === 'feature' || resolved.kind === 'screen') {
-      const list = await listFeatureTestcases(resolved.absPath, { repoRoot: root })
-      paths.push(...list)
+    const resolved = resolveHubId(root, hubId, 'testcase')
+    if (resolved.paths?.length) {
+      paths.push(...resolved.paths)
     } else {
       throw new Error(`Could not resolve --id ${hubId} to testcase(s)`)
     }

package/engines/testcase/runners/generate.mjs

@@ -9,9 +9,14 @@ import { renderTemplate } from './lib/render.mjs'
 import { resolveSemanticPlan } from './lib/semantic-plan.mjs'
 import { writeOutputs } from './lib/write-files.mjs'
 import { resolveHubId, resolveProjectRoot, loadTestsIndex } from './lib/resolve-hub-id.mjs'
-import { extractTestsDocsFlag, ENV_TESTS_DOC } from '../../shared/flowgrid-tests-docs.mjs'
+import {
+  bootstrapTestcaseRun,
+  applyUiOutputLayout,
+} from './lib/bootstrap-context.mjs'
 
-const root = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+const boot = bootstrapTestcaseRun(process.argv.slice(2))
+const root = boot.ctx.projectRoot
+const codegenLayout = boot.layout
 
 Handlebars.registerHelper('eq', (a, b) => a === b)
 Handlebars.registerHelper('and', (a, b) => a && b)
@@ -29,21 +34,16 @@ Handlebars.registerHelper('pascalCase', (value) => {
 })
 
 function parseArgs(argv) {
-  const { argv: stripped, testsDocs } = extractTestsDocsFlag(argv)
-  if (testsDocs) {
-    process.env[ENV_TESTS_DOC] = testsDocs
-  }
-
   const options = { dryRun: false, force: false, testcase: null, feature: null, id: null, all: false }
 
-  for (let i = 0; i < stripped.length; i++) {
-    const arg = stripped[i]
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
     if (arg === '--dry-run' || arg === '--dry') options.dryRun = true
     else if (arg === '--force') options.force = true
     else if (arg === '--all') options.all = true
-    else if (arg === '--testcase') options.testcase = stripped[++i]
-    else if (arg === '--feature') options.feature = stripped[++i]
-    else if (arg === '--id') options.id = stripped[++i]
+    else if (arg === '--testcase') options.testcase = argv[++i]
+    else if (arg === '--feature') options.feature = argv[++i]
+    else if (arg === '--id') options.id = argv[++i]
     else if (!arg.startsWith('-') && !options.testcase && !options.feature && !options.id && !options.all) {
       options.testcase = arg
     }
@@ -65,6 +65,7 @@ async function generateOne(testcasePath, options) {
   const { testcase, spec, testcaseFile, specFile } = await readTestcaseFile(testcasePath, { repoRoot: root })
   const ctx = buildTestcaseContext(testcase, spec, testcaseFile)
   ctx.specFile = specFile
+  applyUiOutputLayout(ctx, codegenLayout)
 
   const semantic = await resolveSemanticPlan(root, testcase)
   ctx.useSemanticFixture = semantic.useSemanticFixture
@@ -84,7 +85,8 @@ async function generateOne(testcasePath, options) {
 
   const { written, skipped } = await writeOutputs(root, outputs, {
     dryRun: options.dryRun,
-    force: options.force
+    force: options.force,
+    allowedRelRoots: codegenLayout.allowedRelRoots,
   })
 
   console.log(`testcase-gen: id=${ctx.testcaseId} module=${ctx.module}`)
@@ -104,12 +106,12 @@ async function generateOne(testcasePath, options) {
 }
 
 async function main() {
-  const options = parseArgs(process.argv.slice(2))
+  const options = parseArgs(boot.argv)
 
   if (options.all) {
-    const testsRoot = process.env.FLOWGRID_TESTS_DOC
-      ? path.resolve(process.env.FLOWGRID_TESTS_DOC)
-      : resolveProjectRoot(root, 'tests')
+    const testsRoot = boot.ctx.testsDocs
+      ?? (process.env.FLOWGRID_TESTS_DOC ? path.resolve(process.env.FLOWGRID_TESTS_DOC) : null)
+      ?? resolveProjectRoot(root, 'tests')
     const index = loadTestsIndex(testsRoot)
     const paths = []
     for (const [id, rel] of Object.entries(index.codeIds || {})) {

package/engines/testcase/runners/lib/bootstrap-context.mjs

@@ -0,0 +1,44 @@
+import { resolveFlowgridContext, flowgridContextToEnv } from '../../../shared/resolve-flowgrid-context.mjs';
+import { codegenOutputLayout } from '../../../shared/e2e-output-layout.mjs';
+import { extractTestsDocsFlag, ENV_TESTS_DOC } from '../../../shared/flowgrid-tests-docs.mjs';
+
+/**
+ * Resolve project/tests/e2e pointers and apply FLOWGRID_* env before testcase engines run.
+ * @param {string[]} argv raw process argv slice (after command name)
+ */
+export function bootstrapTestcaseRun(argv) {
+  const { argv: afterTestsFlag, testsDocs: testsFromFlag } = extractTestsDocsFlag(argv);
+  const ctx = resolveFlowgridContext({ argv: afterTestsFlag });
+  if (testsFromFlag) {
+    ctx.testsDocs = testsFromFlag;
+  }
+  Object.assign(process.env, flowgridContextToEnv(ctx));
+  if (ctx.testsDocs) {
+    process.env[ENV_TESTS_DOC] = ctx.testsDocs;
+  }
+  const layout = codegenOutputLayout(ctx.projectRoot, ctx.e2eRoot, {
+    projectType: ctx.config?.type,
+  });
+  return { ctx, layout, argv: ctx.argv };
+}
+
+/**
+ * @param {import('../../../shared/e2e-output-layout.mjs').codegenOutputLayout} layout
+ * @param {{ outputs: { pageObject: string, spec: string }, module: string, pageClassName: string, testcaseId: string }} ctx
+ */
+export function applyUiOutputLayout(ctx, layout) {
+  ctx.outputs = {
+    pageObject: `${layout.uiPrefix}/pages/${ctx.module}/${ctx.pageClassName}.ts`,
+    spec: `${layout.uiPrefix}/${ctx.module}/${ctx.testcaseId}.spec.ts`,
+  };
+}
+
+/**
+ * @param {{ outputs: { spec: string }, module: string, testcaseId: string }} ctx
+ * @param layout
+ */
+export function applyApiOutputLayout(ctx, layout) {
+  ctx.outputs = {
+    spec: `${layout.apiPrefix}/${ctx.module}/${ctx.testcaseId}.api.spec.ts`,
+  };
+}

package/engines/testcase/runners/lib/write-files.mjs

@@ -1,13 +1,20 @@
 import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
+import {
+  DEFAULT_E2E_ROOT_REL,
+  E2E_ROOT_DIR_PARTS,
+  API_E2E_ROOT_DIR_PARTS,
+} from '../../../shared/flowgrid-e2e-root.mjs'
 
-export const E2E_OUTPUT_ROOT = path.join('tests', 'e2e')
+export const E2E_OUTPUT_ROOT = path.join(...E2E_ROOT_DIR_PARTS)
+export const API_E2E_OUTPUT_ROOT = path.join(...API_E2E_ROOT_DIR_PARTS)
+export { DEFAULT_E2E_ROOT_REL }
 
 /**
  * Preflight every output path before any write or dry-run result is produced.
  *
  * A target is accepted only when, lexically (without following symlinks), it
- * resolves strictly beneath `<root>/tests/e2e`. Rejected: absolute paths,
+ * resolves strictly beneath `<root>/tests/e2e` or `<root>/tests/api-e2e`. Rejected: absolute paths,
  * `..` traversal, targets outside `tests/e2e` (including sibling prefixes
  * such as `tests/e2e-evil`), existing symlink ancestors that could redirect
  * the write, and existing targets that are not regular files.
@@ -17,9 +24,28 @@ export const E2E_OUTPUT_ROOT = path.join('tests', 'e2e')
  * @param {string} root project root
  * @param {{ relativePath: string }[]} outputs
  */
-export async function preflightOutputPaths(root, outputs) {
+function allowedAbsRoots(resolvedRoot, allowedRelRoots) {
+  const rels =
+    allowedRelRoots?.length
+      ? allowedRelRoots
+      : [E2E_OUTPUT_ROOT, API_E2E_OUTPUT_ROOT]
+  return rels.map((rel) => path.join(resolvedRoot, rel.replace(/\//g, path.sep)))
+}
+
+function isUnderCodegenTree(resolvedRoot, absolutePath, allowedRelRoots) {
+  return allowedAbsRoots(resolvedRoot, allowedRelRoots).some(
+    (base) => absolutePath === base || absolutePath.startsWith(base + path.sep),
+  )
+}
+
+/**
+ * @param {string} root
+ * @param {{ relativePath: string }[]} outputs
+ * @param {{ allowedRelRoots?: string[] }} [opts]
+ */
+export async function preflightOutputPaths(root, outputs, opts = {}) {
   const resolvedRoot = path.resolve(root)
-  const e2eRoot = path.join(resolvedRoot, E2E_OUTPUT_ROOT)
+  const allowedLabel = (opts.allowedRelRoots ?? [E2E_OUTPUT_ROOT, API_E2E_OUTPUT_ROOT]).join(', ')
   const errors = []
 
   for (const { relativePath } of outputs) {
@@ -31,22 +57,22 @@ export async function preflightOutputPaths(root, outputs) {
     }
     if (path.isAbsolute(relativePath)) {
       errors.push(
-        `output ${label}: absolute paths are not allowed — use a path relative to the project root, under ${E2E_OUTPUT_ROOT}/`,
+        `output ${label}: absolute paths are not allowed — use a path relative to the project root, under: ${allowedLabel}`,
       )
       continue
     }
 
     if (relativePath.split(/[\\/]+/).includes('..')) {
       errors.push(
-        `output ${label}: ".." traversal is not allowed — outputs must stay under ${E2E_OUTPUT_ROOT}/`,
+        `output ${label}: ".." traversal is not allowed — outputs must stay under: ${allowedLabel}`,
       )
       continue
     }
 
     const absolutePath = path.resolve(resolvedRoot, relativePath)
-    if (!absolutePath.startsWith(e2eRoot + path.sep)) {
+    if (!isUnderCodegenTree(resolvedRoot, absolutePath, opts.allowedRelRoots)) {
       errors.push(
-        `output ${label}: resolves outside ${E2E_OUTPUT_ROOT}/ — generated files must live beneath <projectRoot>/${E2E_OUTPUT_ROOT}` +
+        `output ${label}: resolves outside allowed codegen trees (${allowedLabel})` +
           ' (check module/testcase ids used to build output paths)',
       )
       continue
@@ -108,7 +134,9 @@ async function findUnsafePathComponent(resolvedRoot, absolutePath) {
  * @param {{ dryRun?: boolean, force?: boolean }} options
  */
 export async function writeOutputs(root, outputs, options = {}) {
-  await preflightOutputPaths(root, outputs)
+  await preflightOutputPaths(root, outputs, {
+    allowedRelRoots: options.allowedRelRoots,
+  })
 
   const written = []
   const skipped = []

package/harness/agents/antigravity/rules/antigravity-mcp.mdc

@@ -0,0 +1,12 @@
+---
+description: Google Antigravity IDE — FlowGrid MCP (mcp_config.json under .antigravity)
+alwaysApply: false
+---
+# Antigravity IDE + FlowGrid
+
+- Workspace harness: **`.antigravity/`** (Antigravity IDE hardcodes this path; it does **not** fall back to `.agents/`).
+- MCP config: **`.antigravity/mcp_config.json`** (not `mcp.json`).
+- Server name: `flowgrid` → `bin/flowgrid-mcp.mjs` from the FlowGrid package used at `flowgrid init`.
+- Skills: **`.antigravity/skills/<name>/SKILL.md`**; rules: **`.antigravity/rules/`.
+- Re-sync: `flowgrid harness sync --agent=antigravity`.
+- **Gemini CLI / VS Code** use **`.agents/`** — select **Gemini (CLI / extension)** in init (`--agent=gemini`).

package/harness/agents/gemini/rules/gemini-mcp.mdc

@@ -0,0 +1,11 @@
+---
+description: Gemini CLI / extension — FlowGrid MCP (mcp.json under .agents)
+alwaysApply: false
+---
+# Gemini + FlowGrid
+
+- Workspace harness: **`.agents/`** (open Agent Skills standard; Gemini CLI, VS Code Gemini extension, tools compatible with `.agents` / `.agent`).
+- MCP config: **`.agents/mcp.json`** (server `flowgrid` → `bin/flowgrid-mcp.mjs` from the FlowGrid package used at `flowgrid init`).
+- Skills: **`.agents/skills/<name>/SKILL.md`**; rules: **`.agents/rules/`.
+- Re-sync: `flowgrid harness sync --agent=gemini`.
+- **Antigravity IDE** uses a separate folder — select **Google Antigravity IDE** in init (`--agent=antigravity` → `.antigravity/`), not this profile.

package/harness/agents/gemini_antigravity/rules/antigravity-mcp.mdc

@@ -1,10 +1,12 @@
 ---
-description: Antigravity — FlowGrid MCP wiring (mcp_config.json)
+description: DEPRECATED — use gemini or antigravity agent profiles
 alwaysApply: false
 ---
-# Antigravity + FlowGrid
+# Deprecated combined profile
 
-- MCP config file: `.agents/mcp_config.json` (not `mcp.json`).
-- Server name: `flowgrid` → `bin/flowgrid-mcp.mjs` from the FlowGrid package used at `flowgrid init`.
-- Skills live under `.agents/skills/`; rules under `.agents/rules/`.
-- Re-sync after config changes: `flowgrid harness sync --agent=gemini_antigravity`.
+`gemini_antigravity` was split:
+
+- **Gemini CLI / VS Code** → `flowgrid harness sync --agent=gemini` → `.agents/`
+- **Antigravity IDE** → `flowgrid harness sync --agent=antigravity` → `.antigravity/`
+
+Update `.flowgrid/config.json` `agents` and re-run init or harness sync.

package/harness/be/skills/{grill-api → audit-api}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: grill-api
-description: /grill-api — audit generated FastAPI/Laravel/Nest API before integration.
+name: audit-api
+description: /audit-api — audit generated BE routes/code against 01-backend-spec.yaml before wire.
 disable-model-invocation: true
 ---
 
-# /grill-api
+# /audit-api — BE implementation vs contract
 
 Run after `npm run codegen:api:dry` / `flowgrid api-gen:dry` and after implementation.
 
@@ -13,7 +13,7 @@ Run after `npm run codegen:api:dry` / `flowgrid api-gen:dry` and after implement
 ## 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>/`).
+- 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 external-channel surface `…/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.
@@ -36,6 +36,8 @@ 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`.
+
 ## Accelerators (optional)
 
 ```text
@@ -48,9 +50,8 @@ 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.
+Missing accelerators never block the audit. 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')`).