@tailor-platform/erp-kit 0.5.1 → 0.7.0

package/src/commands/app/progress/log.ts

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ProgressInput, ProgressEntry } from "../../../progress/schema";
+import { type CommandResult, success, failure } from "../../lib/command-result";
+import { getGitContext } from "./git-context";
+
+export function runProgressLog(jsonInput: string, dryRun: boolean, cwd: string): CommandResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(jsonInput);
+  } catch {
+    return failure("Invalid JSON input");
+  }
+
+  const inputResult = ProgressInput.safeParse(parsed);
+  if (!inputResult.success) {
+    const issues = inputResult.error.issues
+      .map((i) => `${i.path.join(".")}: ${i.message}`)
+      .join(", ");
+    return failure(`Invalid progress input: ${issues}`);
+  }
+
+  const enriched = {
+    ...inputResult.data,
+    timestamp: new Date().toISOString(),
+    git: getGitContext(cwd),
+  };
+
+  const entryResult = ProgressEntry.safeParse(enriched);
+  if (!entryResult.success) {
+    const issues = entryResult.error.issues
+      .map((i) => `${i.path.join(".")}: ${i.message}`)
+      .join(", ");
+    return failure(`Invalid progress entry after enrichment: ${issues}`);
+  }
+
+  const line = JSON.stringify(entryResult.data);
+  console.log(line);
+
+  if (dryRun) {
+    return success();
+  }
+
+  const erpKitDir = path.join(cwd, ".erp-kit");
+  fs.mkdirSync(erpKitDir, { recursive: true });
+  fs.appendFileSync(path.join(erpKitDir, "progress.jsonl"), line + "\n", "utf-8");
+
+  return success();
+}

package/src/commands/app/progress/progress.test.ts

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { runProgressLog } from "./log";
+import { runProgressSchema } from "./schema-cmd";
+
+function makeTmpApp(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "progress-test-"));
+  execFileSync("git", ["init"], { cwd: dir });
+  execFileSync("git", ["config", "user.email", "test@test.com"], { cwd: dir });
+  execFileSync("git", ["config", "user.name", "test"], { cwd: dir });
+  execFileSync("git", ["commit", "--allow-empty", "-m", "init"], { cwd: dir });
+  return dir;
+}
+
+describe("runProgressLog", () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("creates .erp-kit/progress.jsonl and appends a valid entry", () => {
+    tmpDir = makeTmpApp();
+    const input = JSON.stringify({
+      v: 1,
+      sessionId: "s1",
+      prompt: "test prompt",
+      event: "note",
+      data: { message: "test", tags: [] },
+    });
+
+    const result = runProgressLog(input, false, tmpDir);
+    expect(result.exitCode).toBe(0);
+
+    const logFile = path.join(tmpDir, ".erp-kit", "progress.jsonl");
+    expect(fs.existsSync(logFile)).toBe(true);
+
+    const lines = fs.readFileSync(logFile, "utf-8").trim().split("\n");
+    expect(lines).toHaveLength(1);
+
+    const entry = JSON.parse(lines[0]) as Record<string, unknown>;
+    expect(entry.sessionId).toBe("s1");
+    expect(entry.timestamp).toBeDefined();
+    expect(entry.git).toBeDefined();
+    expect(entry.conversation).toEqual([]);
+  });
+
+  it("appends multiple entries", () => {
+    tmpDir = makeTmpApp();
+    const input1 = JSON.stringify({
+      v: 1,
+      sessionId: "s1",
+      prompt: "test prompt",
+      event: "note",
+      data: { message: "first", tags: [] },
+    });
+    const input2 = JSON.stringify({
+      v: 1,
+      sessionId: "s1",
+      prompt: "test prompt",
+      event: "note",
+      data: { message: "second", tags: [] },
+    });
+
+    runProgressLog(input1, false, tmpDir);
+    runProgressLog(input2, false, tmpDir);
+
+    const logFile = path.join(tmpDir, ".erp-kit", "progress.jsonl");
+    const lines = fs.readFileSync(logFile, "utf-8").trim().split("\n");
+    expect(lines).toHaveLength(2);
+  });
+
+  it("rejects invalid JSON", () => {
+    tmpDir = makeTmpApp();
+    const result = runProgressLog("not json", false, tmpDir);
+    expect(result.exitCode).toBe(1);
+  });
+
+  it("rejects invalid schema (missing prompt)", () => {
+    tmpDir = makeTmpApp();
+    const input = JSON.stringify({
+      v: 1,
+      sessionId: "s1",
+      event: "note",
+      data: { message: "x", tags: [] },
+    });
+    const result = runProgressLog(input, false, tmpDir);
+    expect(result.exitCode).toBe(1);
+  });
+
+  it("dry-run does not write to file", () => {
+    tmpDir = makeTmpApp();
+    const input = JSON.stringify({
+      v: 1,
+      sessionId: "s1",
+      prompt: "test prompt",
+      event: "note",
+      data: { message: "test", tags: [] },
+    });
+
+    const result = runProgressLog(input, true, tmpDir);
+    expect(result.exitCode).toBe(0);
+
+    const logFile = path.join(tmpDir, ".erp-kit", "progress.jsonl");
+    expect(fs.existsSync(logFile)).toBe(false);
+  });
+});
+
+describe("runProgressSchema", () => {
+  it("outputs valid JSON Schema", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    const result = runProgressSchema();
+
+    expect(result.exitCode).toBe(0);
+    expect(spy).toHaveBeenCalledOnce();
+
+    const schema = JSON.parse(String(spy.mock.calls[0]?.[0])) as Record<string, unknown>;
+    expect(schema).toHaveProperty("anyOf");
+
+    spy.mockRestore();
+  });
+});

package/src/commands/app/progress/schema-cmd.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { ProgressInput } from "../../../progress/schema";
+import type { CommandResult } from "../../lib/command-result";
+import { success } from "../../lib/command-result";
+
+export function runProgressSchema(): CommandResult {
+  const jsonSchema = z.toJSONSchema(ProgressInput);
+  console.log(JSON.stringify(jsonSchema, null, 2));
+  return success();
+}

package/src/commands/check.test.ts

@@ -13,14 +13,14 @@ describe("buildCheckTargets", () => {
     ]);
   });
 
-  it("generates app targets when appRoot is set", () => {
-    const targets = buildCheckTargets({ modulesRoot: undefined, appRoot: "apps" });
-    expect(targets[0].glob).toBe("apps/[a-zA-Z]*/README.md");
+  it("generates app-compose targets when appRoot is set", () => {
+    const targets = buildCheckTargets({ modulesRoot: undefined, appRoot: "apps/myapp" });
+    expect(targets[0].glob).toBe("apps/myapp/README.md");
     expect(targets).toHaveLength(6);
   });
 
   it("generates both when both roots are set", () => {
-    const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: "examples" });
+    const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: "examples/app1" });
     expect(targets).toHaveLength(11);
   });
 

package/src/commands/generate-doc.ts

@@ -48,7 +48,7 @@ export function resolveDocPath(
       modulePath,
       APP_PATHS.docs.businessFlow,
       parts[0],
-      APP_PATHS.storySegment,
+      APP_PATHS.docs.story,
       `${parts[1]}.md`,
     );
   }

package/src/commands/lib/discovery.test.ts

@@ -2,7 +2,8 @@ import { describe, it, expect } from "vitest";
 import {
   moduleCategories,
   appComposeCategories,
-  testCaseCategories,
+  moduleTestCaseCategories,
+  appTestCaseCategories,
   buildCheckTargets,
 } from "./discovery";
 
@@ -28,22 +29,31 @@ describe("moduleCategories", () => {
 
 describe("appComposeCategories", () => {
   it("produces resolver category", () => {
-    const cats = appComposeCategories("apps");
+    const cats = appComposeCategories("apps/myapp");
     expect(cats).toHaveLength(1);
     expect(cats[0].name).toBe("resolver");
-    expect(cats[0].docPattern).toBe("apps/*/docs/resolver/*.md");
+    expect(cats[0].docPattern).toBe("apps/myapp/docs/resolver/*.md");
   });
 });
 
-describe("testCaseCategories", () => {
+describe("moduleTestCaseCategories", () => {
   it("produces command and query test case categories", () => {
-    const cats = testCaseCategories("modules");
+    const cats = moduleTestCaseCategories("modules");
     expect(cats).toHaveLength(2);
     expect(cats[0].testDir).toBe("command");
     expect(cats[1].testDir).toBe("query");
   });
 });
 
+describe("appTestCaseCategories", () => {
+  it("produces story test case category with correct pattern", () => {
+    const cats = appTestCaseCategories("apps");
+    expect(cats.name).toBe("story-test-case");
+    expect(cats.docPattern).toBe("apps/*/docs/business-flow/*/story/*.md");
+    expect(cats.testDir).toBe("backend/src/tests/stories");
+  });
+});
+
 describe("buildCheckTargets", () => {
   it("builds module check targets", () => {
     const targets = buildCheckTargets({ modulesRoot: "modules" });
@@ -59,16 +69,14 @@ describe("buildCheckTargets", () => {
   });
 
   it("builds app check targets", () => {
-    const targets = buildCheckTargets({ appRoot: "apps" });
+    const targets = buildCheckTargets({ appRoot: "apps/myapp" });
     expect(targets).toHaveLength(6);
     expect(targets.map((t) => t.schemaKey)).toContain("screen");
-    expect(targets.find((t) => t.schemaKey === "screen")!.glob).toBe(
-      "apps/[a-zA-Z]*/docs/screen/*.md",
-    );
+    expect(targets.find((t) => t.schemaKey === "screen")!.glob).toBe("apps/myapp/docs/screen/*.md");
   });
 
   it("builds both when both roots provided", () => {
-    const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: "apps" });
+    const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: "apps/myapp" });
     expect(targets).toHaveLength(11);
   });
 });

package/src/commands/lib/discovery.ts

@@ -45,14 +45,22 @@ export function appComposeCategories(root: string): CategoryConfig[] {
   return [
     {
       name: "resolver",
-      sourcePattern: `${root}/*/backend/src/resolvers/*.ts`,
-      docPattern: `${root}/*/${APP_PATHS.docs.resolver}/*.md`,
+      sourcePattern: `${root}/backend/src/resolvers/*.ts`,
+      docPattern: `${root}/${APP_PATHS.docs.resolver}/*.md`,
       exclusions: [/\.test\.ts$/, /^index\.ts$/],
     },
   ];
 }
 
-export function testCaseCategories(root: string): TestCaseCategoryConfig[] {
+export function appTestCaseCategories(root: string): TestCaseCategoryConfig {
+  return {
+    name: "story-test-case",
+    docPattern: `${root}/*/${APP_PATHS.docs.businessFlow}/*/${APP_PATHS.docs.story}/*.md`,
+    testDir: APP_PATHS.tests.stories,
+  };
+}
+
+export function moduleTestCaseCategories(root: string): TestCaseCategoryConfig[] {
   return [
     {
       name: "command-test-case",
@@ -87,18 +95,18 @@ export function buildCheckTargets(config: {
   if (config.appRoot) {
     const a = config.appRoot;
     targets.push(
-      { glob: `${a}/[a-zA-Z]*/README.md`, schemaKey: "app" },
-      { glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.actors}/*.md`, schemaKey: "actors" },
+      { glob: `${a}/README.md`, schemaKey: "app" },
+      { glob: `${a}/${APP_PATHS.docs.actors}/*.md`, schemaKey: "actors" },
       {
-        glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/README.md`,
+        glob: `${a}/${APP_PATHS.docs.businessFlow}/*/README.md`,
         schemaKey: "business-flow",
       },
       {
-        glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/${APP_PATHS.storySegment}/*.md`,
+        glob: `${a}/${APP_PATHS.docs.businessFlow}/*/${APP_PATHS.docs.story}/*.md`,
         schemaKey: "story",
       },
-      { glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.screen}/*.md`, schemaKey: "screen" },
-      { glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.resolver}/*.md`, schemaKey: "resolver" },
+      { glob: `${a}/${APP_PATHS.docs.screen}/*.md`, schemaKey: "screen" },
+      { glob: `${a}/${APP_PATHS.docs.resolver}/*.md`, schemaKey: "resolver" },
     );
   }
 

package/src/commands/lib/paths.ts

@@ -11,12 +11,14 @@ export const MODULE_PATHS = {
 } as const;
 
 export const APP_PATHS = {
-  // Subdirectory name within docs/business-flow/<flow>/story/
-  storySegment: "story",
+  tests: {
+    stories: "backend/src/tests/stories",
+  },
   docs: {
     resolver: "docs/resolver",
     actors: "docs/actors",
     businessFlow: "docs/business-flow",
+    story: "story",
     screen: "docs/screen",
   },
 } as const;

package/src/commands/lib/sync-check-source.test.ts

@@ -104,7 +104,7 @@ describe("runSourceSyncCheck", () => {
     fs.writeFileSync(path.join(srcDir, "myResolver.ts"), "export {}");
     fs.writeFileSync(path.join(docDir, "myResolver.md"), "# MyResolver");
 
-    const result = await runSourceSyncCheck({ appRoot: "apps" }, tmpDir);
+    const result = await runSourceSyncCheck({ appRoot: "apps/app1" }, tmpDir);
     expect(result.exitCode).toBe(0);
     expect(result.summary.totalSources).toBe(1);
   });

package/src/commands/lib/sync-check-source.ts

@@ -3,7 +3,12 @@ import fg from "fast-glob";
 import { moduleCategories, appComposeCategories, type CategoryConfig } from "./discovery";
 
 export interface CheckError {
-  type: "missing-doc" | "orphaned-doc" | "missing-test-case" | "extra-test-case";
+  type:
+    | "missing-doc"
+    | "orphaned-doc"
+    | "missing-test-case"
+    | "extra-test-case"
+    | "missing-test-file";
   category: string;
   sourcePath?: string;
   docPath?: string;

package/src/commands/lib/sync-check-tests.test.ts

@@ -3,7 +3,7 @@ import os from "node:os";
 import fs from "node:fs";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { parseTestCasesFromDoc, parseItDescriptionsFromTest } from "../parse-doc-test-cases";
-import { runTestCaseSyncCheck } from "./sync-check-tests";
+import { runModuleTestCaseSyncCheck, runAppTestCaseSyncCheck } from "./sync-check-tests";
 
 describe("parseTestCasesFromDoc", () => {
   it("extracts test cases from ## Test Cases section", () => {
@@ -67,7 +67,7 @@ describe("createProduct", () => {
   });
 });
 
-describe("runTestCaseSyncCheck", () => {
+describe("runModuleTestCaseSyncCheck", () => {
   let tmpDir: string;
 
   beforeEach(() => {
@@ -94,7 +94,7 @@ describe("runTestCaseSyncCheck", () => {
       'describe("createOrder", () => { it("creates order", async () => {}); });',
     );
 
-    const errors = await runTestCaseSyncCheck("modules", tmpDir);
+    const errors = await runModuleTestCaseSyncCheck("modules", tmpDir);
     expect(errors).toContainEqual(
       expect.objectContaining({
         type: "missing-test-case",
@@ -120,7 +120,7 @@ describe("runTestCaseSyncCheck", () => {
       'describe("createOrder", () => { it("creates order", async () => {}); it("extra case", async () => {}); });',
     );
 
-    const errors = await runTestCaseSyncCheck("modules", tmpDir);
+    const errors = await runModuleTestCaseSyncCheck("modules", tmpDir);
     expect(errors).toContainEqual(
       expect.objectContaining({
         type: "extra-test-case",
@@ -146,13 +146,36 @@ describe("runTestCaseSyncCheck", () => {
       'describe("createOrder", () => { it("creates order", async () => {}); it("validates input", async () => {}); });',
     );
 
-    const errors = await runTestCaseSyncCheck("modules", tmpDir);
+    const errors = await runModuleTestCaseSyncCheck("modules", tmpDir);
     const tcErrors = errors.filter(
       (e) => e.type === "missing-test-case" || e.type === "extra-test-case",
     );
     expect(tcErrors).toHaveLength(0);
   });
 
+  it("reports missing-test-file when test file does not exist", async () => {
+    const docDir = path.join(tmpDir, "modules", "foo", "docs", "commands");
+    const testDir = path.join(tmpDir, "modules", "foo", "command");
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.mkdirSync(testDir, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(docDir, "CreateOrder.md"),
+      "# CreateOrder\n\n## Test Cases\n\n- creates order\n- validates input\n",
+    );
+    fs.writeFileSync(path.join(testDir, "createOrder.ts"), "export {}");
+    // No createOrder.test.ts file
+
+    const errors = await runModuleTestCaseSyncCheck("modules", tmpDir);
+    expect(errors).toContainEqual(
+      expect.objectContaining({
+        type: "missing-test-file",
+        category: "command-test-case",
+        expectedBasename: "createOrder.test.ts",
+      }),
+    );
+  });
+
   it("skips test-case check when doc has no Test Cases section", async () => {
     const docDir = path.join(tmpDir, "modules", "foo", "docs", "commands");
     const testDir = path.join(tmpDir, "modules", "foo", "command");
@@ -169,10 +192,108 @@ describe("runTestCaseSyncCheck", () => {
       'describe("createOrder", () => { it("creates order", async () => {}); });',
     );
 
-    const errors = await runTestCaseSyncCheck("modules", tmpDir);
+    const errors = await runModuleTestCaseSyncCheck("modules", tmpDir);
     const tcErrors = errors.filter(
       (e) => e.type === "missing-test-case" || e.type === "extra-test-case",
     );
     expect(tcErrors).toHaveLength(0);
   });
 });
+
+describe("runAppTestCaseSyncCheck", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sync-check-story-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function setupStoryFixture(storyName: string, storyContent: string, testContent: string) {
+    const flow = "item-lifecycle";
+    const storyDir = path.join(tmpDir, "apps", "my-app", "docs", "business-flow", flow, "story");
+    const testDir = path.join(tmpDir, "apps", "my-app", "backend", "src", "tests", "stories", flow);
+    fs.mkdirSync(storyDir, { recursive: true });
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(path.join(storyDir, `${storyName}.md`), storyContent);
+    fs.writeFileSync(path.join(testDir, `${storyName}.test.ts`), testContent);
+  }
+
+  it("reports missing-test-case when story doc has case not in test", async () => {
+    setupStoryFixture(
+      "admin--create-item",
+      "# Create Item\n\n## Test Cases\n\n- creates item\n- validates input\n",
+      'describe("admin--create-item", () => { it("creates item", async () => {}); });',
+    );
+
+    const errors = await runAppTestCaseSyncCheck("apps", tmpDir);
+    expect(errors).toContainEqual(
+      expect.objectContaining({
+        type: "missing-test-case",
+        category: "story-test-case",
+        expectedBasename: "validates input",
+      }),
+    );
+  });
+
+  it("reports extra-test-case when test has case not in story doc", async () => {
+    setupStoryFixture(
+      "admin--create-item",
+      "# Create Item\n\n## Test Cases\n\n- creates item\n",
+      'describe("admin--create-item", () => { it("creates item", async () => {}); it("extra case", async () => {}); });',
+    );
+
+    const errors = await runAppTestCaseSyncCheck("apps", tmpDir);
+    expect(errors).toContainEqual(
+      expect.objectContaining({
+        type: "extra-test-case",
+        category: "story-test-case",
+        expectedBasename: "extra case",
+      }),
+    );
+  });
+
+  it("returns no errors when story doc and test match", async () => {
+    setupStoryFixture(
+      "admin--create-item",
+      "# Create Item\n\n## Test Cases\n\n- creates item\n- validates input\n",
+      'describe("admin--create-item", () => { it("creates item", async () => {}); it("validates input", async () => {}); });',
+    );
+
+    const errors = await runAppTestCaseSyncCheck("apps", tmpDir);
+    expect(errors).toHaveLength(0);
+  });
+
+  it("reports missing-test-file when story test file does not exist", async () => {
+    const flow = "item-lifecycle";
+    const storyDir = path.join(tmpDir, "apps", "my-app", "docs", "business-flow", flow, "story");
+    fs.mkdirSync(storyDir, { recursive: true });
+    // No test file created
+    fs.writeFileSync(
+      path.join(storyDir, "admin--create-item.md"),
+      "# Create Item\n\n## Test Cases\n\n- creates item\n- validates input\n",
+    );
+
+    const errors = await runAppTestCaseSyncCheck("apps", tmpDir);
+    expect(errors).toContainEqual(
+      expect.objectContaining({
+        type: "missing-test-file",
+        category: "story-test-case",
+        expectedBasename: "admin--create-item.test.ts",
+      }),
+    );
+  });
+
+  it("skips when story doc has no Test Cases section", async () => {
+    setupStoryFixture(
+      "admin--view-items",
+      "# View Items\n\n## Scenario Patterns\n\n- Browse items\n",
+      'describe("admin--view-items", () => { it("some test", async () => {}); });',
+    );
+
+    const errors = await runAppTestCaseSyncCheck("apps", tmpDir);
+    expect(errors).toHaveLength(0);
+  });
+});

package/src/commands/lib/sync-check-tests.ts

@@ -2,16 +2,16 @@ import path from "node:path";
 import fs from "node:fs";
 import fg from "fast-glob";
 import { parseTestCasesFromDoc, parseItDescriptionsFromTest } from "../parse-doc-test-cases";
-import { testCaseCategories } from "./discovery";
+import { moduleTestCaseCategories, appTestCaseCategories } from "./discovery";
 import type { CheckError } from "./sync-check-source";
 
 function toCamelCase(pascalCase: string): string {
   return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
 }
 
-export async function runTestCaseSyncCheck(root: string, cwd: string): Promise<CheckError[]> {
+export async function runModuleTestCaseSyncCheck(root: string, cwd: string): Promise<CheckError[]> {
   const errors: CheckError[] = [];
-  const categories = testCaseCategories(root);
+  const categories = moduleTestCaseCategories(root);
 
   for (const category of categories) {
     const docPaths = await fg(category.docPattern, { cwd });
@@ -31,7 +31,16 @@ export async function runTestCaseSyncCheck(root: string, cwd: string): Promise<C
       const testPath = path.join(modulePath, category.testDir, testFileName);
       const testFullPath = path.join(cwd, testPath);
 
-      if (!fs.existsSync(testFullPath)) continue;
+      if (!fs.existsSync(testFullPath)) {
+        errors.push({
+          type: "missing-test-file",
+          category: category.name,
+          docPath,
+          sourcePath: testPath,
+          expectedBasename: testFileName,
+        });
+        continue;
+      }
 
       const testContent = fs.readFileSync(testFullPath, "utf-8");
       const itDescriptions = parseItDescriptionsFromTest(testContent);
@@ -67,3 +76,72 @@ export async function runTestCaseSyncCheck(root: string, cwd: string): Promise<C
 
   return errors;
 }
+
+function resolveStoryTestPath(docPath: string, testDir: string): string | null {
+  const regex = /^(.+)\/docs\/business-flow\/([^/]+)\/story\/([^/]+)\.md$/;
+  const match = regex.exec(docPath);
+  if (!match) return null;
+  const [, appPath, flow, name] = match;
+  return `${appPath}/${testDir}/${flow}/${name}.test.ts`;
+}
+
+export async function runAppTestCaseSyncCheck(appRoot: string, cwd: string): Promise<CheckError[]> {
+  const errors: CheckError[] = [];
+  const config = appTestCaseCategories(appRoot);
+  const docPaths = await fg(config.docPattern, { cwd });
+
+  for (const docPath of docPaths) {
+    const docFullPath = path.join(cwd, docPath);
+    const docContent = fs.readFileSync(docFullPath, "utf-8");
+    const docTestCases = parseTestCasesFromDoc(docContent);
+
+    if (docTestCases.length === 0) continue;
+
+    const testPath = resolveStoryTestPath(docPath, config.testDir);
+    if (!testPath) continue;
+
+    const testFullPath = path.join(cwd, testPath);
+    if (!fs.existsSync(testFullPath)) {
+      errors.push({
+        type: "missing-test-file",
+        category: config.name,
+        docPath,
+        sourcePath: testPath,
+        expectedBasename: path.basename(testPath),
+      });
+      continue;
+    }
+
+    const testContent = fs.readFileSync(testFullPath, "utf-8");
+    const itDescriptions = parseItDescriptionsFromTest(testContent);
+
+    const docSet = new Set(docTestCases);
+    const testSet = new Set(itDescriptions);
+
+    for (const docCase of docSet) {
+      if (!testSet.has(docCase)) {
+        errors.push({
+          type: "missing-test-case",
+          category: config.name,
+          docPath,
+          sourcePath: testPath,
+          expectedBasename: docCase,
+        });
+      }
+    }
+
+    for (const testCase of testSet) {
+      if (!docSet.has(testCase)) {
+        errors.push({
+          type: "extra-test-case",
+          category: config.name,
+          docPath,
+          sourcePath: testPath,
+          expectedBasename: testCase,
+        });
+      }
+    }
+  }
+
+  return errors;
+}