@tailor-platform/erp-kit 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @tailor-platform/erp-kit
 
+## 0.6.0
+
+### Minor Changes
+
+- 0cb94dc: - Add manufacturing module with BOM, work orders, and production tracking
+  - Add story test case sync-check and stub generation for `erp-kit test` command
+  - Update workspace creation instructions and deployment steps in skills
+
+### Patch Changes
+
+- 0cb94dc: - Fix relative shared imports to use package self-reference for consistent module resolution
+  - Fix priority calibration in requirements review skill to improve accuracy
+  - Fix severity validation in module-2 requirements review skill
+  - Update module-4-plan-review skill and regenerate .agents/skills
+
 ## 0.5.1
 
 ### Patch Changes

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 import { arg, defineCommand, runMain } from "politty";
 import { z } from "zod";
 import chalk from "chalk";
-import fs, { existsSync, readFileSync, readdirSync } from "node:fs";
+import fs, { existsSync, globSync, readFileSync, readdirSync } from "node:fs";
 import path, { basename, dirname, join, relative, resolve } from "node:path";
 import { execFile, execSync } from "node:child_process";
 import fg from "fast-glob";
@@ -452,11 +452,12 @@ const MODULE_PATHS = {
 	}
 };
 const APP_PATHS = {
-	storySegment: "story",
+	tests: { stories: "backend/src/tests/stories" },
 	docs: {
 		resolver: "docs/resolver",
 		actors: "docs/actors",
 		businessFlow: "docs/business-flow",
+		story: "story",
 		screen: "docs/screen"
 	}
 };
@@ -492,7 +493,14 @@ function appComposeCategories(root) {
 		exclusions: [/\.test\.ts$/, /^index\.ts$/]
 	}];
 }
-function testCaseCategories(root) {
+function appTestCaseCategories(root) {
+	return {
+		name: "story-test-case",
+		docPattern: `${root}/*/${APP_PATHS.docs.businessFlow}/*/${APP_PATHS.docs.story}/*.md`,
+		testDir: APP_PATHS.tests.stories
+	};
+}
+function moduleTestCaseCategories(root) {
 	return [{
 		name: "command-test-case",
 		docPattern: `${root}/*/${MODULE_PATHS.docs.commands}/*.md`,
@@ -536,7 +544,7 @@ function buildCheckTargets(config) {
 			glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/README.md`,
 			schemaKey: "business-flow"
 		}, {
-			glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/${APP_PATHS.storySegment}/*.md`,
+			glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/${APP_PATHS.docs.story}/*.md`,
 			schemaKey: "story"
 		}, {
 			glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.screen}/*.md`,
@@ -742,9 +750,9 @@ function parseItDescriptionsFromTest(content) {
 function toCamelCase(pascalCase) {
 	return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
 }
-async function runTestCaseSyncCheck(root, cwd) {
+async function runModuleTestCaseSyncCheck(root, cwd) {
 	const errors = [];
-	const categories = testCaseCategories(root);
+	const categories = moduleTestCaseCategories(root);
 	for (const category of categories) {
 		const docPaths = await fg(category.docPattern, { cwd });
 		for (const docPath of docPaths) {
@@ -780,15 +788,57 @@ async function runTestCaseSyncCheck(root, cwd) {
 	}
 	return errors;
 }
+function resolveStoryTestPath(docPath, testDir) {
+	const match = /^(.+)\/docs\/business-flow\/([^/]+)\/story\/([^/]+)\.md$/.exec(docPath);
+	if (!match) return null;
+	const [, appPath, flow, name] = match;
+	return `${appPath}/${testDir}/${flow}/${name}.test.ts`;
+}
+async function runAppTestCaseSyncCheck(appRoot, cwd) {
+	const errors = [];
+	const config = appTestCaseCategories(appRoot);
+	const docPaths = await fg(config.docPattern, { cwd });
+	for (const docPath of docPaths) {
+		const docFullPath = path.join(cwd, docPath);
+		const docTestCases = parseTestCasesFromDoc(fs.readFileSync(docFullPath, "utf-8"));
+		if (docTestCases.length === 0) continue;
+		const testPath = resolveStoryTestPath(docPath, config.testDir);
+		if (!testPath) continue;
+		const testFullPath = path.join(cwd, testPath);
+		if (!fs.existsSync(testFullPath)) continue;
+		const itDescriptions = parseItDescriptionsFromTest(fs.readFileSync(testFullPath, "utf-8"));
+		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;
+}
 //#endregion
 //#region src/commands/sync-check.ts
 async function runSyncCheck(config, cwd) {
 	const sourceResult = await runSourceSyncCheck(config, cwd);
 	if (config.modulesRoot) {
-		const testCaseErrors = await runTestCaseSyncCheck(config.modulesRoot, cwd);
+		const testCaseErrors = await runModuleTestCaseSyncCheck(config.modulesRoot, cwd);
 		sourceResult.errors.push(...testCaseErrors);
-		sourceResult.exitCode = sourceResult.errors.length > 0 ? 1 : 0;
 	}
+	if (config.appRoot) {
+		const storyErrors = await runAppTestCaseSyncCheck(config.appRoot, cwd);
+		sourceResult.errors.push(...storyErrors);
+	}
+	sourceResult.exitCode = sourceResult.errors.length > 0 ? 1 : 0;
 	return sourceResult;
 }
 function formatSyncCheckReport(result) {
@@ -1092,10 +1142,22 @@ describe("${name}", () => {
     expect(resolver.default.name).toBe("${name}");
   });
 });
+`;
+	} },
+	storyTest: { render: (name, testCases) => {
+		return `import { describe, expect, inject, it } from "vitest";
+import { createGraphQLClient } from "@/tests/utils/graphql-client";
+
+describe("${name}", () => {
+  const graphQLClient = createGraphQLClient(inject("url"), inject("token"));
+
+${testCases.map((tc) => `  it("${tc}", async () => {\n    // TODO: implement\n  });`).join("\n\n")}
+});
 `;
 	} }
 };
-function renderStub(type, name) {
+function renderStub(type, name, testCases) {
+	if (type === "storyTest") return templates.storyTest.render(name, testCases);
 	return templates[type].render(name);
 }
 //#endregion
@@ -1121,6 +1183,9 @@ function generateResolverStub(resolverName) {
 function generateResolverTestStub(resolverName) {
 	return renderStub("resolverTest", resolverName);
 }
+function generateStoryTestStub(name, testCases) {
+	return renderStub("storyTest", name, testCases);
+}
 //#endregion
 //#region src/generator/scaffold.ts
 function copyTemplateDir(srcDir, destDir, replacements, placeholderFiles) {
@@ -1314,7 +1379,7 @@ function resolveDocPath(type, name, modulePath) {
 	if (type === "story") {
 		const parts = name.split("/");
 		if (parts.length !== 2) throw new Error(`Story name must be "<flow>/<story>" (e.g., "onboarding/admin--create-user")`);
-		return path.join(modulePath, APP_PATHS.docs.businessFlow, parts[0], APP_PATHS.storySegment, `${parts[1]}.md`);
+		return path.join(modulePath, APP_PATHS.docs.businessFlow, parts[0], APP_PATHS.docs.story, `${parts[1]}.md`);
 	}
 	if (MODULE_DIR_MAP[type]) return path.join(modulePath, MODULE_DIR_MAP[type], `${name}.md`);
 	if (APP_DIR_MAP[type]) return path.join(modulePath, APP_DIR_MAP[type], `${name}.md`);
@@ -1540,19 +1605,16 @@ function parseExceptionHandlingFromRaw(markdown) {
 function runGenerateAppCode(appPath) {
 	const appName = path.basename(appPath);
 	scaffoldAppBoilerplate(appPath, appName);
+	generateResolverStubs(appPath, appName);
+	generateStoryTestStubs(appPath, appName);
+	return 0;
+}
+function generateResolverStubs(appPath, appName) {
 	const docsDir = path.join(appPath, "docs", "resolver");
-	const resolverDir = path.join(appPath, "backend", "src", "resolvers");
-	if (!fs.existsSync(docsDir)) {
-		console.log(`No docs/resolver/ directory found — skipping resolver generation`);
-		console.log(`Generated boilerplate for ${appName}`);
-		return 0;
-	}
+	if (!fs.existsSync(docsDir)) return;
 	const mdFiles = fs.readdirSync(docsDir).filter((f) => f.endsWith(".md"));
-	if (mdFiles.length === 0) {
-		console.log(`No resolver docs found — skipping resolver generation`);
-		console.log(`Generated boilerplate for ${appName}`);
-		return 0;
-	}
+	if (mdFiles.length === 0) return;
+	const resolverDir = path.join(appPath, "backend", "src", "resolvers");
 	fs.mkdirSync(resolverDir, { recursive: true });
 	let generated = 0;
 	for (const file of mdFiles) {
@@ -1570,8 +1632,26 @@ function runGenerateAppCode(appPath) {
 			console.log(`  scaffolded ${path.relative(appPath, testFile)}`);
 		}
 	}
-	console.log(`Scaffolded ${generated} resolver(s) for ${appName}`);
-	return 0;
+	if (generated > 0) console.log(`Scaffolded ${generated} resolver(s) for ${appName}`);
+}
+function generateStoryTestStubs(appPath, appName) {
+	const storyDocs = globSync(path.join(appPath, "docs/business-flow/*/story/*.md"));
+	let generated = 0;
+	for (const storyDocPath of storyDocs) {
+		const testCases = parseTestCasesFromDoc(fs.readFileSync(storyDocPath, "utf-8"));
+		if (testCases.length === 0) continue;
+		const match = /\/docs\/business-flow\/([^/]+)\/story\/([^/]+)\.md$/.exec(storyDocPath);
+		if (!match) continue;
+		const [, flow, storyName] = match;
+		const testDir = path.join(appPath, APP_PATHS.tests.stories, flow);
+		const testFile = path.join(testDir, `${storyName}.test.ts`);
+		if (fs.existsSync(testFile)) continue;
+		fs.mkdirSync(testDir, { recursive: true });
+		fs.writeFileSync(testFile, generateStoryTestStub(storyName, testCases));
+		console.log(`  scaffolded ${path.relative(appPath, testFile)}`);
+		generated++;
+	}
+	if (generated > 0) console.log(`Scaffolded ${generated} story test(s) for ${appName}`);
 }
 //#endregion
 //#region src/shared/uuidv5.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
   "license": "MIT",
   "bin": {

package/skills/erp-kit-app-5-impl-backend/SKILL.md

@@ -90,7 +90,10 @@ For each resolver, check whether its spec (`docs/resolver/*.md`) documents error
 
 Do not directly mutate module-owned tables via Kysely — always use module commands.
 
+After resolvers are done, implement the story integration test stubs generated in Phase 1b (`backend/src/tests/stories/`). Each stub has `it()` descriptions from the story doc's `## Test Cases`. Use the scaffolded GraphQL client and `inject("url")` / `inject("token")` to call resolvers. Run `pnpm test:integration` and `pnpm erp-kit app sync-check` to verify.
+
 > **Parallelize if possible:** Dispatch one agent per resolver. Each agent writes only to its own files:
+>
 > - `src/resolvers/<resolverName>.ts`
 > - `src/executors/<resolverName>.ts`
 >
@@ -107,10 +110,10 @@ Do not directly mutate module-owned tables via Kysely — always use module comm
 
 Frontend implementation requires a deployed backend (for GraphQL schema generation). Prompt the user to:
 
-1. Create a workspace and configure `.env` (including `TAILOR_PLATFORM_WORKSPACE_ID`)
-2. Run `pnpm deploy` and `pnpm generate`
-3. Run `pnpm seed` if seed data was created
-4. Retrieve OAuth2 client ID via `tailor-sdk oauth2client get default --json` for frontend `.env`
+1. Create a workspace via `tailor-sdk workspace create --name <NAME> --region <us-west|asia-northeast>` and configure `.env` (including `TAILOR_PLATFORM_WORKSPACE_ID`)
+2. Run `pnpm run deploy` and `pnpm run generate`
+3. Run `pnpm run seed` if seed data was created
+4. Retrieve OAuth2 client ID via `tailor-sdk oauth2client get default --json --env-file-if-exists .env` for frontend `.env`
 
 Wait for the user to confirm deployment is complete before proceeding.
 

package/skills/erp-kit-app-7-impl-review/SKILL.md

@@ -63,7 +63,7 @@ cd <APP_ROOT>/frontend && pnpm lint && pnpm typecheck && pnpm build
 erp-kit app sync-check -p <APP_ROOT>/..
 ```
 
-Report pass/fail for each check. `sync-check` detects missing resolver implementations and orphaned docs, so groups A-C agents can skip file-existence checks and focus on content parity.
+Report pass/fail for each check. `sync-check` detects missing resolver implementations, orphaned docs, and story doc ↔ integration test case mismatches, so groups A-C agents can skip file-existence checks and focus on content parity.
 
 ## Step 3: Aggregate Results
 

package/skills/erp-kit-module-6-impl-review/SKILL.md

@@ -31,35 +31,57 @@ Define shared context for all agents:
 
 Verify at least `MODEL_DOCS`, `COMMAND_DOCS`, or `QUERY_DOCS` is non-empty. If no docs exist, stop with: "No docs found for module <MODULE_NAME>."
 
-## Step 2: Dispatch Agents (parallelize if possible)
+## Step 2: Dispatch Agents (parallelize ALL agents in a single message)
 
-Launch 3 Agent tool calls in parallel — one per domain (model, command, query).
-Each agent receives: MODULE_NAME, all relevant doc/code/test file paths for its domain.
-Each agent runs all parity perspectives (doc→code, error, doc→test) internally and returns: structured JSON per [references/impl-parity-report-format.md](references/impl-parity-report-format.md).
-If a doc or code directory is empty, the agent reports "no files found" and skips.
+Split each parity check into its own agent, then further split by file batches when there are many files. Target **~5 agents per domain** (model, command, query) for maximum parallelism. Launch **ALL agents in a single message** — do NOT wait for one domain to finish before starting another.
 
-| Agent | Domain  | Prompt Templates                                                                                                                                                                                                                                                                   | Inputs                                                              |
-| ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| 1     | Model   | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)                                                                                                                                                                                                         | MODEL_DOCS, MODEL_CODE                                              |
-| 2     | Command | [references/command-doc-code-parity.md](references/command-doc-code-parity.md), [references/command-error-implementation-parity.md](references/command-error-implementation-parity.md), [references/command-doc-test-parity.md](references/command-doc-test-parity.md)               | COMMAND_DOCS, COMMAND_CODE, COMMAND_TEST_CODE, ERROR_DEFS           |
-| 3     | Query   | [references/query-doc-code-parity.md](references/query-doc-code-parity.md), [references/query-error-implementation-parity.md](references/query-error-implementation-parity.md), [references/query-doc-test-parity.md](references/query-doc-test-parity.md)                         | QUERY_DOCS, QUERY_CODE, QUERY_TEST_CODE, ERROR_DEFS                |
+If a doc or code directory is empty, skip that agent entirely.
+
+### Splitting Strategy
+
+1. **Each parity check type = separate agent** (never combine different check types in one agent)
+2. **File batching**: If a check has more than 5 doc files, split docs into batches of 3-5 files each. Each batch becomes its own agent running the same check type on a subset of files.
+3. **Corresponding code/test files**: When batching by doc files, include only the matching code and test files for those specific docs (match by filename stem, e.g., `docs/commands/createFoo.md` → `command/createFoo.ts` + `command/createFoo.test.ts`).
+
+### Agent Table
+
+| Check Type | Domain  | Prompt Template                                                                                            | Inputs per agent                                                     |
+| ---------- | ------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| M-1        | Model   | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)                                 | MODEL_DOCS (batch), MODEL_CODE (matching)                            |
+| C-1        | Command | [references/command-doc-code-parity.md](references/command-doc-code-parity.md)                              | COMMAND_DOCS (batch), COMMAND_CODE (matching)                        |
+| C-2        | Command | [references/command-error-implementation-parity.md](references/command-error-implementation-parity.md)      | COMMAND_DOCS (batch), COMMAND_CODE (matching), ERROR_DEFS            |
+| C-3        | Command | [references/command-doc-test-parity.md](references/command-doc-test-parity.md)                              | COMMAND_DOCS (batch), COMMAND_TEST_CODE (matching)                   |
+| Q-1        | Query   | [references/query-doc-code-parity.md](references/query-doc-code-parity.md)                                 | QUERY_DOCS (batch), QUERY_CODE (matching)                            |
+| Q-2        | Query   | [references/query-error-implementation-parity.md](references/query-error-implementation-parity.md)          | QUERY_DOCS (batch), QUERY_CODE (matching), ERROR_DEFS               |
+| Q-3        | Query   | [references/query-doc-test-parity.md](references/query-doc-test-parity.md)                                 | QUERY_DOCS (batch), QUERY_TEST_CODE (matching)                      |
+
+### Batching Example
+
+If a module has 8 command docs: split into 3 batches (3+3+2). Each batch spawns 3 agents (C-1, C-2, C-3) → 9 command agents total. If it has 4 command docs: no batching needed, 3 agents (C-1, C-2, C-3).
+
+For model docs: if 6 models → 2 batches (3+3) → 2 agents (M-1 × 2). If 3 models → 1 agent.
+
+### Agent Dispatch
 
 For each agent:
 
-1. Read ALL prompt template files listed for that agent
+1. Read the prompt template file for that check type
 2. Replace `{{MODULE_NAME}}` with the resolved module name
-3. Replace `{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{QUERY_CODE}}`, `{{COMMAND_TEST_CODE}}`, `{{QUERY_TEST_CODE}}`, `{{ERROR_DEFS}}` with the actual file paths
-4. Combine the templates into a single prompt and dispatch the agent
+3. Replace template placeholders (`{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{QUERY_CODE}}`, `{{COMMAND_TEST_CODE}}`, `{{QUERY_TEST_CODE}}`, `{{ERROR_DEFS}}`) with the actual file paths **for this batch only**
+4. Dispatch the agent with the filled prompt
+
+**IMPORTANT**: Launch ALL agents across ALL domains in a single parallel message. Do not serialize by domain.
 
 ## Step 3: Aggregate Results
 
 After ALL agents return:
 
 1. Collect the JSON results from each agent
-2. Merge all `gaps[]` arrays into a single list
-3. Merge all `inconsistencies[]` arrays into a single list
-4. Deduplicate: if two gaps share the same `source + target + check`, keep only one
-5. Calculate totals across all summaries
+2. **Merge batches**: If a check type was split across multiple batches (e.g., C-1 batch 1 + C-1 batch 2), merge their `gaps[]` and `inconsistencies[]` into a single result per check type
+3. Merge all `gaps[]` arrays across all check types into a single list
+4. Merge all `inconsistencies[]` arrays into a single list
+5. Deduplicate: if two gaps share the same `source + target + check`, keep only one
+6. Calculate totals across all summaries
 
 ## Step 4: Severity Validation
 

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";
 
@@ -35,15 +36,24 @@ describe("appComposeCategories", () => {
   });
 });
 
-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" });

package/src/commands/lib/discovery.ts

@@ -52,7 +52,15 @@ export function appComposeCategories(root: string): CategoryConfig[] {
   ];
 }
 
-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",
@@ -94,7 +102,7 @@ export function buildCheckTargets(config: {
         schemaKey: "business-flow",
       },
       {
-        glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/${APP_PATHS.storySegment}/*.md`,
+        glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/${APP_PATHS.docs.story}/*.md`,
         schemaKey: "story",
       },
       { glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.screen}/*.md`, schemaKey: "screen" },

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-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,7 +146,7 @@ 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",
     );
@@ -169,10 +169,88 @@ 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("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);
+  });
+});