@shanyucoder/flowgrid 0.1.10 → 0.1.12

package/engines/docs/lib/render-design-markdown.mjs

@@ -0,0 +1,56 @@
+/**
+ * ir/generated/design.md — interaction case sequence diagrams only (from ir/design.yaml).
+ */
+import path from 'node:path'
+
+function stripMermaidFence(text) {
+  const t = String(text ?? '').trim()
+  const m = t.match(/^```(?:mermaid)?\s*([\s\S]*?)```$/m)
+  if (m) return m[1].trim()
+  return t
+}
+
+/**
+ * @param {object} design ir/design.yaml shape
+ * @param {{ pageId?: string, title?: string }} meta
+ */
+export function renderDesignMarkdown(design, meta = {}) {
+  const items = design?.interactionCases?.items
+  if (!Array.isArray(items) || !items.length) return null
+
+  const lines = []
+  lines.push(`# Design sequences — ${meta.pageId || design.id || 'screen'}`)
+  lines.push('')
+  if (meta.title) {
+    lines.push(`> ${meta.title}`)
+    lines.push('')
+  }
+  lines.push(
+    '> Generated from `ir/design.yaml` (`interactionCases`). Prose: [spec.md](./spec.md#interaction-cases). Do not edit this file.',
+  )
+  lines.push('')
+
+  for (const item of items) {
+    const id = item?.id || 'IC-UNKNOWN'
+    lines.push(`## ${id} {#${id.toLowerCase()}}`)
+    lines.push('')
+    const body = stripMermaidFence(item.sequenceDiagram)
+    if (!body.includes('sequenceDiagram')) {
+      lines.push('```mermaid')
+      lines.push(body)
+      lines.push('```')
+    } else {
+      lines.push('```mermaid')
+      lines.push(body)
+      lines.push('```')
+    }
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+export function irGeneratedDesignMarkdownPath(bundleFile) {
+  const dir = path.dirname(path.resolve(bundleFile))
+  return path.join(dir, 'ir', 'generated', 'design.md')
+}

package/engines/docs/lib/screen-to-flows-index.mjs

@@ -0,0 +1,121 @@
+/**
+ * Reverse index: W-* screen id → FLOW-* ids (from bundle userFlows + FLOW markdown traceability).
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+const SCREEN_ID_RE = /W-[A-Z0-9][\w-]*/gi
+
+function addLink(map, screenId, flowId) {
+  const flow = normalizeFlowToken(flowId)
+  if (!screenId || !flow) return
+  if (!map.has(screenId)) map.set(screenId, new Set())
+  map.get(screenId).add(flow)
+}
+
+function normalizeFlowToken(raw) {
+  const m = raw.match(/FLOW-[A-Z0-9][\w-]*/i)
+  if (!m) return null
+  const tail = m[0].slice(5)
+  return `FLOW-${tail}`
+}
+
+/** Parse bullets from userFlows block text (YAML literal or list lines). */
+export function parseUserFlowsText(text) {
+  const links = []
+  if (!text || !text.trim()) return links
+  for (const line of text.split('\n')) {
+    const trimmed = line.replace(/^\s*-\s*/, '').trim()
+    if (!/FLOW-/i.test(trimmed)) continue
+    const flowId = normalizeFlowToken(trimmed)
+    if (!flowId) continue
+    const screens = []
+    const screensPart = trimmed.match(/screens:\s*(.+)/i)?.[1] ?? trimmed
+    for (const sm of screensPart.match(SCREEN_ID_RE) ?? []) screens.push(sm)
+    links.push({ flowId, screenIds: screens })
+  }
+  return links
+}
+
+function extractUserFlowsFromBundleFile(raw) {
+  const block = raw.match(/^userFlows:\s*\|\s*\n([\s\S]*?)(?=^[a-zA-Z][\w.-]*:|\s*$)/m)?.[1]
+  if (block) return parseUserFlowsText(block)
+  const inline = raw.match(/^userFlows:\s*(.+)$/m)?.[1]
+  if (inline) return parseUserFlowsText(inline)
+  const listBlock = raw.match(/^userFlows:\s*\n((?:\s+-\s+.+\n?)+)/m)?.[1]
+  if (listBlock) return parseUserFlowsText(listBlock)
+  return []
+}
+
+function walkBundleFiles(docsRoot, onBundle) {
+  const roots = [
+    path.join(docsRoot, 'surfaces'),
+    path.join(docsRoot, 'product'),
+  ]
+  const visit = (dir) => {
+    if (!fs.existsSync(dir)) return
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (ent.name.startsWith('.') || ent.name === 'node_modules') continue
+      const p = path.join(dir, ent.name)
+      if (ent.isDirectory()) visit(p)
+      else if (ent.name.endsWith('.bundle.yaml')) onBundle(p)
+    }
+  }
+  for (const r of roots) visit(r)
+}
+
+function walkFlowMarkdown(docsRoot, onFile) {
+  const catalog = path.join(docsRoot, 'architecture/03-user-flows')
+  if (fs.existsSync(catalog)) {
+    for (const n of fs.readdirSync(catalog)) {
+      if (n.startsWith('FLOW-') && n.endsWith('.md')) onFile(path.join(catalog, n))
+    }
+  }
+  const walk = (dir) => {
+    if (!fs.existsSync(dir)) return
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (ent.name.startsWith('.') || ent.name === 'node_modules') continue
+      const p = path.join(dir, ent.name)
+      if (ent.isDirectory()) {
+        if (ent.name === 'user-flows' && path.basename(dir) === 'common') {
+          for (const n of fs.readdirSync(p)) {
+            if (n.startsWith('FLOW-') && n.endsWith('.md')) onFile(path.join(p, n))
+          }
+        }
+        walk(p)
+      }
+    }
+  }
+  walk(path.join(docsRoot, 'surfaces'))
+}
+
+/**
+ * @returns {Record<string, string[]>} screenToFlows sorted flow ids per W-*
+ */
+export function buildScreenToFlows(docsRoot) {
+  const map = new Map()
+
+  walkBundleFiles(docsRoot, (bundlePath) => {
+    const raw = fs.readFileSync(bundlePath, 'utf8')
+    for (const { flowId, screenIds } of extractUserFlowsFromBundleFile(raw)) {
+      for (const sid of screenIds) addLink(map, sid, flowId)
+    }
+  })
+
+  walkFlowMarkdown(docsRoot, (flowPath) => {
+    const flowId = path.basename(flowPath, '.md')
+    const body = fs.readFileSync(flowPath, 'utf8')
+    for (const sid of body.match(SCREEN_ID_RE) ?? []) addLink(map, sid, flowId)
+  })
+
+  const out = {}
+  for (const [screen, flows] of map) {
+    out[screen] = [...flows].sort((a, b) => a.localeCompare(b))
+  }
+  return out
+}
+
+export function linkedFlowsForScreen(docsRoot, screenId, screenToFlows) {
+  const idx = screenToFlows ?? buildScreenToFlows(docsRoot)
+  return idx[screenId] ?? []
+}

package/engines/docs/vitepress/surfaces-nav.mjs

@@ -93,6 +93,7 @@ export function leafGeneratedNavNodes(leafDir, toHref) {
   const specMd = path.join(leafDir, 'ir', 'generated', 'spec.md')
   const dmMd = path.join(leafDir, 'ir', 'generated', 'data-model.md')
   const apiMd = path.join(leafDir, 'ir', 'generated', 'api.md')
+  const designMd = path.join(leafDir, 'ir', 'generated', 'design.md')
   const nodes = []
   if (existsSync(specMd)) {
     nodes.push({
@@ -112,6 +113,12 @@ export function leafGeneratedNavNodes(leafDir, toHref) {
       link: toHref(apiMd),
     })
   }
+  if (existsSync(designMd)) {
+    nodes.push({
+      text: 'Design sequences',
+      link: toHref(designMd),
+    })
+  }
   return nodes
 }
 

package/engines/spec/lib/audit-bundle-gaps.mjs

@@ -20,6 +20,7 @@
 import fs from 'fs';
 import path from 'path';
 import { parse } from 'yaml';
+import { auditInteractionCases } from './audit-interaction-cases.mjs';
 import { auditUxAffordance } from './audit-ux-affordance.mjs';
 import { auditDbTables, resolveBackendSpecForBundle } from './audit-db-tables.mjs';
 
@@ -581,11 +582,10 @@ function auditBundleContent(rawText, filePath, pageType) {
     addWarning(
       'WARN_NO_USER_FLOWS',
       'userFlows',
-      'Màn có handoff / multi-screen nhưng chưa khai báo luồng người dùng (userFlows).',
-      'Declare userFlows: | — link FLOW-* hoặc mô tả journey ngắn.'
+      'Screen has handoff / multi-screen navigation but userFlows is not declared.',
+      'Declare userFlows: | — FLOW-<id> — role: … — screens: W-* (this leaf).'
     );
   }
-
   if (has(rawText, 'risks:')) {
     addWarning(
       'WARN_BUNDLE_RISKS_FORBIDDEN',
@@ -618,6 +618,18 @@ function auditBundleContent(rawText, filePath, pageType) {
     );
   }
 
+  // =========================================================================
+  // Interaction cases (L2) — two-step confirm + item keys
+  // =========================================================================
+
+  let bundleParsed = {};
+  try {
+    bundleParsed = parse(rawText) ?? {};
+  } catch {
+    /* keep empty */
+  }
+  auditInteractionCases(bundleParsed, { addGap, addConfirm, addWarning });
+
   // =========================================================================
   // Result
   // =========================================================================

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

@@ -0,0 +1,185 @@
+/**
+ * Two-step audit for bundle interactionCases (see harness/docs/extracts/agent-design-context.md).
+ */
+
+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/audit-legacy-gaps.mjs

@@ -42,6 +42,16 @@ function auditLegacyInventory(inventoryPath, targetId) {
 
   const rawText = fs.readFileSync(inventoryPath, 'utf8');
 
+  if (targetId?.startsWith('FLOW-') && !/##\s+4\.\s+User flows/i.test(rawText)) {
+    addGap(
+      'ADOPT_MISSING_USER_FLOW_SECTION',
+      'warning',
+      'adoption-inventory.md#user-flows',
+      'Inventory has no "## 4. User flows" section — cross-surface FLOW-* may be missing.',
+      'Re-run /adopt with user-flow discovery; see tpl-adoption-inventory.md (tiers A/B/C).'
+    );
+  }
+
   if (targetId) {
     if (!rawText.includes(targetId)) {
       addGap(

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/engines/testcase/_staging-from-portal/runners/README.md

@@ -4,10 +4,10 @@ Reads **plans** from sibling `base-tests/` → writes `tests/e2e/` on this FE re
 
 ```bash
 pnpm testcase:gen:dry --id TC-LOGIN-VALID
-pnpm testcase:gen --id W-AD-AUTH-001
+pnpm testcase:gen --id W-ADM-AUTH-01
 pnpm testcase:gen --id smoke
-pnpm testcase:gen --testcase ../base-tests/cases/W-AD-AUTH-001/TC-LOGIN-VALID.yaml
-pnpm testcase:gen --feature W-AD-AUTH-001   # all TC-* under cases/{id}/
+pnpm testcase:gen --testcase ../base-tests/cases/W-ADM-AUTH-01/TC-LOGIN-VALID.yaml
+pnpm testcase:gen --feature W-ADM-AUTH-01   # all TC-* under cases/{id}/
 ```
 
 Author/edit plans on **base-tests** (`/testcase`), not on this code repo.

package/engines/testcase/_staging-from-portal/runners/generate.mjs

@@ -37,8 +37,8 @@ function parseArgs(argv) {
 
   if (!options.testcase && !options.feature && !options.id) {
     throw new Error(
-      'Usage: pnpm testcase:gen --id W-AD-AUTH-001|TC-LOGIN-VALID|smoke|CMP-01|SC-LOGIN\n' +
-        '       pnpm testcase:gen --testcase <path> | --feature W-AD-AUTH-001  (screen under base-tests/cases)',
+      'Usage: pnpm testcase:gen --id W-ADM-AUTH-01|TC-LOGIN-VALID|smoke|CMP-ADM-AUTH-01|SC-LOGIN\n' +
+        '       pnpm testcase:gen --testcase <path> | --feature W-ADM-AUTH-01  (screen under base-tests/cases)',
     )
   }
 

package/engines/testcase/_staging-from-portal/runners/lib/read-testcase.mjs

@@ -145,7 +145,7 @@ export async function readTestcaseFile(testcasePath, opts = {}) {
 /**
  * List TC-*.yaml under base-tests/cases/{screenId}/ (prefer --id).
  * @param {string} root FE repo root
- * @param {string} screenId e.g. W-AD-AUTH-001
+ * @param {string} screenId e.g. W-ADM-AUTH-01
  */
 export async function listFeatureTestcases(root, screenId) {
   const testsRoot = resolveProjectRoot(root, 'base-tests')

package/engines/testcase/runners/README.md

@@ -4,10 +4,10 @@ Reads **plans** from the tests hub → writes `tests/e2e/` in the FE project.
 
 ```bash
 pnpm testcase:gen:dry --id TC-LOGIN-VALID
-pnpm testcase:gen --id W-AD-AUTH-001
+pnpm testcase:gen --id W-ADM-AUTH-01
 pnpm testcase:gen --id smoke
-pnpm testcase:gen --testcase "$FLOWGRID_TESTS_DOC/cases/W-AD-AUTH-001/TC-LOGIN-VALID.yaml"
-pnpm testcase:gen --feature W-AD-AUTH-001   # all TC-* under cases/{id}/
+pnpm testcase:gen --testcase "$FLOWGRID_TESTS_DOC/cases/W-ADM-AUTH-01/TC-LOGIN-VALID.yaml"
+pnpm testcase:gen --feature W-ADM-AUTH-01   # all TC-* under cases/{id}/
 ```
 
 Author/edit plans in the **tests hub** (`/testcase`), not in the code project.

package/engines/testcase/runners/generate.mjs

@@ -51,8 +51,8 @@ function parseArgs(argv) {
 
   if (!options.testcase && !options.feature && !options.id && !options.all) {
     throw new Error(
-      'Usage: pnpm testcase:gen --id W-AD-AUTH-001|TC-LOGIN-VALID|smoke|CMP-01|SC-LOGIN\n' +
-        '       pnpm testcase:gen --testcase <path> | --feature W-AD-AUTH-001  (screen under tests hub cases/)\n' +
+      'Usage: pnpm testcase:gen --id W-ADM-AUTH-01|TC-LOGIN-VALID|smoke|CMP-ADM-AUTH-01|SC-LOGIN\n' +
+        '       pnpm testcase:gen --testcase <path> | --feature W-ADM-AUTH-01  (screen under tests hub cases/)\n' +
         '       pnpm testcase:gen --all\n' +
         '       Optional: --tests-docs <hub> or FLOWGRID_TESTS_DOC',
     )

package/engines/testcase/runners/lib/read-testcase.mjs

@@ -158,7 +158,7 @@ export async function readTestcaseFile(testcasePath, opts = {}) {
 /**
  * List TC-*.yaml under the tests hub cases/{screenId}/ (prefer --id).
  * @param {string} root FE repo root
- * @param {string} screenId e.g. W-AD-AUTH-001
+ * @param {string} screenId e.g. W-ADM-AUTH-01
  */
 export async function listFeatureTestcases(root, screenId) {
   const testsRoot = process.env.FLOWGRID_TESTS_DOC ? path.resolve(process.env.FLOWGRID_TESTS_DOC) : resolveProjectRoot(root, 'tests')

package/engines/testcase/runners/lib/resolve-hub-id.mjs

@@ -263,8 +263,8 @@ export function resolveHubId(repoRoot, id, mode = 'testcase') {
     return { kind: 'code', id, paths: [spec], notes, codeDir }
   }
 
-  // Module (e.g. CMP-ADM-001) → all code children
-  if (/^[A-Z]+-[A-Z]+-\d{3}$/i.test(id)) {
+  // Module (e.g. CMP-ADM-AUTH-01) → all code children
+  if (/^CMP-[A-Z0-9]+(?:-[A-Z0-9]+)+$/i.test(id)) {
     const { index: docsIdx } = getDocs()
     const cmp = (docsIdx.modules || []).find(
       (c) => c.id === id || c.id.startsWith(id) || (c.slug && id.toLowerCase().includes(c.slug)),
@@ -319,6 +319,6 @@ export function resolveHubId(repoRoot, id, mode = 'testcase') {
   }
 
   throw new Error(
-    `Unrecognized id "${id}". Use W-|API-|UI-|FLOW-|DEP-|TC-|SC-* or hierarchical ID (e.g. cmp-adm-001-01-01), or module ID (CMP-ADM-001), or suite id (smoke, regression-auth).`,
+    `Unrecognized id "${id}". Use W-|API-|UI-|FLOW-|DEP-|TC-|SC-* or hierarchical ID (e.g. cmp-adm-auth-01-01-01), or module ID (CMP-ADM-AUTH-01), or suite id (smoke, regression-auth).`,
   )
 }

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

@@ -12,7 +12,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`).
+- User prompt MAY specify a function ID, API slug, or short name (e.g. `API-AUTH-001`, `login`, `CMP-ADM-DEMO-01`).
 - 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`.

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

@@ -13,7 +13,7 @@ before committing generated test code.
 
 ## Target / ID Resolution Rule
 
-- User prompt MAY specify a function ID, API slug, or short name (e.g. `API-AUTH-001`, `login`, `CMP-ADM-009`).
+- User prompt MAY specify a function ID, API slug, or short name (e.g. `API-AUTH-001`, `login`, `CMP-ADM-DEMO-01`).
 - Agent MUST resolve **`…/api/<seq>/01-backend-spec.yaml`** via `FLOWGRID_DOCS_ROOT` or `flowgrid_docs_route`.
 - **Read the entire `01-backend-spec.yaml`**. Do **not** use `ir/design.yaml` or `ir/spec.yaml` as BE contract.
 - Compare generated unit tests against that 01 file. Missing 01 → STOP, hand off to docs `/grill-api-spec`.