@tailor-platform/erp-kit 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
   "license": "MIT",
   "bin": {
@@ -33,24 +33,18 @@
     "zod": "4.3.6"
   },
   "devDependencies": {
-    "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@tailor-platform/function-types": "0.8.2",
-    "@tailor-platform/sdk": "1.25.2",
     "@types/mdast": "^4.0.4",
     "@types/node": "^25.1.0",
     "@typescript-eslint/parser": "^8.57.0",
     "eslint": "10.0.3",
-    "kysely": "0.28.11",
     "tsdown": "0.21.3",
     "typescript": "^5.7.3",
     "vitest": "^4.0.0",
     "@tailor-platform/eslint-config": "0.0.1"
   },
   "peerDependencies": {
-    "@tailor-platform/function-kysely-tailordb": "0.1.3",
     "@tailor-platform/function-types": "0.8.2",
-    "@tailor-platform/sdk": "1.25.2",
-    "kysely": "0.28.11"
+    "@tailor-platform/sdk": "1.25.4"
   },
   "engines": {
     "node": ">=24"
@@ -63,9 +57,6 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:primitives": "vitest run src/modules/primitives/",
-    "test:user-management": "vitest run src/modules/user-management/",
-    "test:shared": "vitest run src/modules/shared/",
     "mock:start": "node dist/cli.mjs mock start",
     "mock:validate": "node dist/cli.mjs mock validate",
     "doc:gen": "POLITTY_DOCS_UPDATE=true vitest run src/cli.doc.test.ts",

package/skills/erp-kit-app-1-requirements/SKILL.md

@@ -10,7 +10,7 @@ Create Tier 1-2 documentation: Requirements, Actors, and Business Flows.
 ## Workflow Phases
 
 ```
-GATHER → CLARIFY → CREATE → VALIDATE
+GATHER → CLARIFY → CREATE → STORY EXTRACTION → VALIDATE
 ```
 
 ### Phase 1: Gather
@@ -61,7 +61,9 @@ erp-kit app generate doc business-flow {FLOW_NAME} -p {APP_ROOT}/{APP_NAME}
     README.md                                ← Tier 1 (from app init)
     docs/
       actors/{actor-name}.md                 ← Tier 2 (from generate doc actors)
-      business-flow/{flow-name}/README.md    ← Tier 2 (from generate doc business-flow)
+      business-flow/{flow-name}/
+        README.md                              ← Tier 2 (from generate doc business-flow)
+        story/{actor}--{story-name}.md         ← Tier 2 (from Phase 3b story extraction)
 ```
 
 **Schema constraints:** See [erp-kit-app-shared/references/schema-constraints.md](../erp-kit-app-shared/references/schema-constraints.md) for H1 heading rules, naming conventions, and requirements structure.
@@ -70,7 +72,32 @@ erp-kit app generate doc business-flow {FLOW_NAME} -p {APP_ROOT}/{APP_NAME}
 
 **Business flow `## Stories` section:**
 
-At Tier 2, story files do not exist yet. Use `- TBD` as a placeholder to avoid broken link violations. Replace with actual story links in `/erp-kit-app-3-plan`.
+Use `- TBD` as a placeholder during flow creation. These will be replaced with actual story links in Phase 3b below.
+
+### Phase 3b: Story Extraction
+
+After creating business flows, extract and create story documentation.
+
+1. **Collect** all business flow docs: glob `<APP_ROOT>/docs/business-flow/*/README.md`
+2. **Dispatch story extraction agents** — one Agent per business flow (parallelize if possible). Each agent:
+   - Reads the prompt template from [references/story-extraction.md](references/story-extraction.md)
+   - Replace `{{APP_NAME}}` with the resolved app name
+   - Replace `{{ACTOR_DOCS}}` with the actor doc file paths
+   - Replace `{{BUSINESS_FLOW_DOCS}}` with ONLY the single business flow doc for that agent
+   - Dispatch the agent with the filled prompt
+
+3. **Scaffold & populate** story docs from agent results:
+
+```bash
+# For each story identified
+erp-kit app generate doc story <flow>/<actor>--<story> -p {APP_ROOT}/{APP_NAME}
+```
+
+4. **Link stories** in business flow READMEs: replace `- TBD` placeholders in each flow's `## Stories` section with actual links:
+
+```markdown
+- [Story Title](./story/<actor>--<story-name>.md)
+```
 
 ### Phase 4: Validate
 
@@ -87,6 +114,7 @@ See [schema-constraints.md](../erp-kit-app-shared/references/schema-constraints.
 | `requirements.yml`  | 1    | `README.md`                           |
 | `actors.yml`        | 2    | `docs/actors/<name>.md`               |
 | `business-flow.yml` | 2    | `docs/business-flow/<flow>/README.md` |
+| `story.yml`         | 2    | `docs/business-flow/<flow>/story/<actor>--<name>.md` |
 
 ## Next Step
 

package/skills/{erp-kit-app-3-plan → erp-kit-app-1-requirements}/references/story-extraction.md

@@ -6,12 +6,6 @@ App: {{APP_NAME}}
 Actor docs: {{ACTOR_DOCS}}
 Business flow docs: {{BUSINESS_FLOW_DOCS}}
 
-## Available Modules
-
-The following modules are available in erp-kit. Use this to determine whether a story needs custom resolvers or can rely on built-in queries.
-
-{{MODULE_OVERVIEW}}
-
 ## Instructions
 
 1. Read ALL actor docs at the paths above
@@ -55,10 +49,10 @@ For each story, extract:
 
 ### Resolver Classification
 
-For each story, determine using the module overview:
+For each story, determine:
 
-- **Needs resolvers**: Story involves create/update/delete operations → mark as `- TBD` for resolvers
-- **Read-only**: Story only views/lists data and built-in queries suffice → mark as `None` for resolvers
+- **Needs resolvers**: Story involves create/update/delete operations → mark as `TBD` for resolvers
+- **Read-only**: Story only views/lists data → mark as `None` for resolvers
 
 ## Naming Convention
 

package/skills/erp-kit-app-2-requirements-review/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: erp-kit-app-2-requirements-review
-description: Review requirements quality and documentation consistency for app-compose applications. Use after creating Tier 1-2 documentation (requirements, actors, business-flow) with erp-kit-app-1-requirements.
+description: Review requirements quality and documentation consistency for applications. Use after creating Tier 1-2 documentation (requirements, actors, business-flow) with erp-kit-app-1-requirements.
 ---
 
 # Requirements Review
 
-Review **requirements quality** and **documentation consistency** for an app-compose application's Tier 1-2 documentation.
+Review **requirements quality** and **documentation consistency** for an application's Tier 1-2 documentation.
 
 ## When to Use
 
@@ -22,12 +22,13 @@ Define shared context for all agents:
 - `APP_README`: `<APP_ROOT>/README.md`
 - `BUSINESS_FLOW_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/README.md`
 - `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actors/*.md`
+- `STORY_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/story/*.md`
 
 Verify at least `APP_README` exists. If not, stop with: "No application README found at <APP_ROOT>. Run erp-kit-app-1-requirements first."
 
 ## Step 2: Dispatch Agents (parallelize if possible)
 
-Launch 2 Agent tool calls in parallel — one per review concern.
+Launch 3 Agent tool calls in parallel — one per review concern.
 Each agent receives: APP_NAME, relevant doc file paths.
 Each agent returns: structured markdown per [references/requirements-report-format.md](references/requirements-report-format.md).
 
@@ -35,13 +36,15 @@ Each agent returns: structured markdown per [references/requirements-report-form
 | ----- | ------------------------------------------------------------------------------------ | ------------------------------------------ |
 | 1     | [references/best-practices-check.md](references/best-practices-check.md)             | APP_README, ACTOR_DOCS, BUSINESS_FLOW_DOCS |
 | 2     | [references/boundary-consistency-check.md](references/boundary-consistency-check.md) | APP_README, ACTOR_DOCS, BUSINESS_FLOW_DOCS |
+| 3     | [references/story-quality-check.md](references/story-quality-check.md)               | APP_README, ACTOR_DOCS, BUSINESS_FLOW_DOCS, STORY_DOCS |
 
 For each agent:
 
 1. Read the prompt template file
 2. Replace `{{APP_NAME}}` with the resolved app name
 3. Replace `{{APP_README}}`, `{{ACTOR_DOCS}}`, `{{BUSINESS_FLOW_DOCS}}` with the actual file paths
-4. Dispatch the agent with the filled prompt
+4. Replace `{{STORY_DOCS}}` with the story doc file paths (agent 3 only)
+5. Dispatch the agent with the filled prompt
 
 ## Step 3: Aggregate & Validate
 
@@ -52,7 +55,18 @@ After ALL agents return:
 3. Merge all `recommendations[]` arrays into a single list
 4. **Filter out** any recommendation that would violate `erp-kit app check` schema constraints (e.g., title-casing business flow H1 headings)
 5. Calculate totals across all summaries
-6. Render the final report below
+
+## Step 4: Priority Validation
+
+Subagents tend to over-classify. Before rendering the report, re-evaluate every non-pass finding:
+
+- **"Is this even this application's responsibility?"** — If the concern belongs to a module or is out of scope, drop it from the report
+- **"Does this block proceeding to planning?"** → `critical`
+- **"Will this force Tier 3-4 rework (stories, screens, resolvers)?"** → `high`
+- **"Is this a quality improvement with no rework risk?"** → `medium`
+- All no → `low`, regardless of subagent label
+
+## Step 5: Render Report
 
 ## Report Format
 
@@ -82,14 +96,24 @@ Render the aggregated results as markdown:
 
 ---
 
-### 3. Summary
+### 3. Story Quality
+
+| Story/Flow | Check | Status | Detail |
+| ---------- | ----- | ------ | ------ |
+
+(Populated from agent 3 issues)
+
+---
+
+### 4. Summary
 
 | Aspect                    | Status | Details           |
 | ------------------------- | ------ | ----------------- |
 | Best Practices            |        | X/Y checks passed |
 | Documentation Consistency |        | X/Y checks passed |
+| Story Quality             |        | X/Y checks passed |
 
-### 4. Recommendations
+### 5. Recommendations
 
 Numbered list of actionable fixes, grouped by priority:
 

package/skills/erp-kit-app-2-requirements-review/references/best-practices-check.md

@@ -19,7 +19,7 @@ This review targets Tier 1-2 documentation only. Stories (`## Stories` section i
 
 1. Read the application README at the path above
 2. Read ALL actor docs and business flow docs at the paths above
-3. **Web search** app-compose and ERP application best practices (actor modeling, business flow design, user journey patterns)
+3. **Web search** ERP application best practices (actor modeling, business flow design, user journey patterns)
 4. Evaluate whether the Tier 1-2 documentation follows best practices
 5. **Verify** that none of your recommendations would violate the schema constraints above
 6. Return results as markdown per the Output Format section

package/skills/erp-kit-app-2-requirements-review/references/story-quality-check.md

@@ -0,0 +1,67 @@
+# Story Quality Check
+
+## Context
+
+App: {{APP_NAME}}
+Actor docs: {{ACTOR_DOCS}}
+Business flow docs: {{BUSINESS_FLOW_DOCS}}
+Story docs: {{STORY_DOCS}}
+
+## Instructions
+
+1. Read ALL actor docs at the paths above
+2. Read ALL business flow docs at the paths above
+3. Read ALL story docs at the paths above
+4. Validate story quality against the checks below
+5. Return results per the report format at the bottom
+
+## Checks
+
+### Story-to-Flow Parity
+
+For each business flow:
+- Every flow must have at least one story
+- Every story must map to exactly one flow (via its directory location)
+- The `## Stories` section in each flow README must link to all stories in its `story/` directory
+- No broken links in `## Stories` sections
+
+### Naming Conventions
+
+- Story filename must follow `<actor>--<story-name>.md` pattern (double-dash separator)
+- Actor slug in filename must match an existing actor doc
+- Story name portion must be kebab-case
+
+### Content Completeness
+
+For each story:
+- Must have scenario patterns (non-empty)
+- Must have preconditions and postconditions
+- Must have screen references (can be TBD at this stage)
+- Must have resolver classification (TBD for mutations, None for read-only)
+
+### Actor Consistency
+
+- Actor referenced in story filename must exist in `docs/actors/`
+- Actor referenced in story content must match the filename actor
+
+## Output Format
+
+Return findings as structured markdown:
+
+### Issues
+
+For each issue found:
+
+- **Check:** which check failed
+- **Scope:** which file/story/flow is affected
+- **Severity:** critical / high / medium / low
+- **Detail:** what's wrong and how to fix it
+
+### Summary
+
+| Check | Passed | Failed | Total |
+| ----- | ------ | ------ | ----- |
+| Story-to-Flow Parity | | | |
+| Naming Conventions | | | |
+| Content Completeness | | | |
+| Actor Consistency | | | |

package/skills/erp-kit-app-3-plan/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: erp-kit-app-3-plan
-description: Create Tier 3-4 documentation (stories, screens, resolvers) by breaking down business flows. Use after completing requirements review with erp-kit-app-2-requirements-review.
+description: Create Tier 3-4 documentation (screens, resolvers) by breaking down business flows and existing stories. Use after completing requirements review with erp-kit-app-2-requirements-review.
 ---
 
 # Business Flow Breakdown to Stories, Screens, and Resolvers
 
-Convert Tier 2 business flows into Tier 3 (stories, screens) and Tier 4 (resolvers) documentation using parallel extraction agents.
+Convert Tier 2 business flows and stories into Tier 3 (screens) and Tier 4 (resolvers) documentation using parallel extraction agents.
 
 ## When to Use
 
@@ -20,6 +20,7 @@ Tier 1-2 documentation must exist:
 - `README.md` (requirements)
 - `docs/actors/*.md` (actor definitions)
 - `docs/business-flow/*/README.md` (business workflows)
+- `docs/business-flow/<flow>/story/<actor>--<name>.md` (story definitions)
 
 ## Step 1: Setup
 
@@ -29,45 +30,55 @@ Define shared context for all agents:
 - `APP_NAME`: basename of APP_ROOT
 - `BUSINESS_FLOW_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/README.md`
 - `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actors/*.md`
+- `STORY_DOCS`: glob `<APP_ROOT>/docs/business-flow/*/story/*.md`
 - `MODULE_OVERVIEW`: output of `erp-kit doc modules`
 
 Verify at least `BUSINESS_FLOW_DOCS` is non-empty. If no business flow docs exist, stop with: "No business flow docs found under <APP_ROOT>/docs/. Run erp-kit-app-1-requirements first."
 
+Verify at least `STORY_DOCS` is non-empty. If no story docs exist, stop with: "No story docs found. Run erp-kit-app-1-requirements first to create stories."
+
 Collect module overview:
 
 ```bash
 erp-kit doc modules
 ```
 
-This returns each module's name, overview, command/query/model counts, and dependencies. Save the full output as `MODULE_OVERVIEW` — all three agents receive it.
+This returns each module's name, overview, command/query/model counts, and dependencies. Save the full output as `MODULE_OVERVIEW` — both agents receive it.
+
+> **Sync barrier:** `MODULE_OVERVIEW` must be collected before dispatching agents.
 
 ## Step 2: Dispatch Agents (parallelize if possible)
 
-Launch 3 Agent tool calls in parallel — one per extraction concern.
-Each agent receives: APP_NAME, relevant doc file paths, and MODULE_OVERVIEW.
+For each business flow in BUSINESS_FLOW_DOCS, launch 2 Agent tool calls in parallel — one per extraction concern.
+
+Each agent pair receives: APP_NAME, ACTOR_DOCS, the single business flow's STORY_DOCS, MODULE_OVERVIEW, and only that flow's BUSINESS_FLOW_DOC (singular).
 
-| Agent | Prompt Template                                                        | Inputs                                                    |
-| ----- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
-| 1     | [references/story-extraction.md](references/story-extraction.md)       | APP_NAME, ACTOR_DOCS, BUSINESS_FLOW_DOCS, MODULE_OVERVIEW |
-| 2     | [references/screen-extraction.md](references/screen-extraction.md)     | APP_NAME, ACTOR_DOCS, BUSINESS_FLOW_DOCS, MODULE_OVERVIEW |
-| 3     | [references/resolver-extraction.md](references/resolver-extraction.md) | APP_NAME, ACTOR_DOCS, BUSINESS_FLOW_DOCS, MODULE_OVERVIEW |
+| Agent | Prompt Template                                                        |
+| ----- | ---------------------------------------------------------------------- |
+| A     | [references/screen-extraction.md](references/screen-extraction.md)     |
+| B     | [references/resolver-extraction.md](references/resolver-extraction.md) |
 
 For each agent:
 
 1. Read the prompt template file
 2. Replace `{{APP_NAME}}` with the resolved app name
-3. Replace `{{ACTOR_DOCS}}`, `{{BUSINESS_FLOW_DOCS}}` with the actual file paths
-4. Replace `{{MODULE_OVERVIEW}}` with the output from `erp-kit doc modules`
-5. Dispatch the agent with the filled prompt
+3. Replace `{{ACTOR_DOCS}}` with the actor doc file paths
+4. Replace `{{BUSINESS_FLOW_DOCS}}` with ONLY the single business flow doc for this iteration
+5. Replace `{{STORY_DOCS}}` with ONLY the stories under this flow's `story/` directory
+6. Replace `{{MODULE_OVERVIEW}}` with the output from `erp-kit doc modules`
+7. Dispatch the agent with the filled prompt
+
+With N business flows, this produces N × 2 parallel agents.
 
 ## Step 3: Aggregate & Present Plan
 
 After ALL agents return:
 
-1. Collect extraction results from each agent
-2. Present consolidated plan to user:
-   - Stories to create (with actor, flow, scenario patterns)
-   - Screens to create (with type, fields, actions)
+1. Collect extraction results from each agent, grouped by business flow
+2. **Deduplicate screens**: Screens referenced by multiple flows should appear once — merge field lists and story references
+3. Present consolidated plan to user:
+   - Existing stories (from STORY_DOCS, for reference)
+   - Screens to create (deduplicated, with type, fields, actions)
    - Resolvers to create (with operation type, module mapping)
 ## Step 4: Resolve Module Gaps
 
@@ -88,9 +99,6 @@ For resolvers that reference erp-kit modules, use `MODULE_OVERVIEW` as the sourc
 Scaffold using `erp-kit` CLI:
 
 ```bash
-# Tier 3: Stories
-erp-kit app generate doc story <flow>/<actor>--<story> -p {APP_ROOT}/{APP_NAME}
-
 # Tier 3: Screens
 erp-kit app generate doc screen <screen-name> -p {APP_ROOT}/{APP_NAME}
 
@@ -100,12 +108,6 @@ erp-kit app generate doc resolver <resolver-name> -p {APP_ROOT}/{APP_NAME}
 
 Fill scaffolded docs with details from agent extraction results.
 
-**After creating stories**, replace `- TBD` placeholders in the `## Stories` section of each business flow README with actual links:
-
-```markdown
-- [Story Title](./story/<actor>--<story-name>.md)
-```
-
 **After creating resolvers**, replace `- TBD` placeholders in the `## Resolvers` section of each story with actual links:
 
 ```markdown
@@ -126,11 +128,10 @@ See [erp-kit-app-shared/references/naming-conventions.md](../erp-kit-app-shared/
 
 ## Schema Reference
 
-| Schema         | Tier | Output Path                                          |
-| -------------- | ---- | ---------------------------------------------------- |
-| `story.yml`    | 3    | `docs/business-flow/<flow>/story/<actor>--<name>.md` |
-| `screen.yml`   | 3    | `docs/screen/<name>.md`                              |
-| `resolver.yml` | 4    | `docs/resolver/<name>.md`                            |
+| Schema         | Tier | Output Path               |
+| -------------- | ---- | ------------------------- |
+| `screen.yml`   | 3    | `docs/screen/<name>.md`   |
+| `resolver.yml` | 4    | `docs/resolver/<name>.md` |
 
 ## Common Patterns
 
@@ -144,7 +145,7 @@ See [erp-kit-app-shared/references/naming-conventions.md](../erp-kit-app-shared/
 
 ## Tips
 
-- One business flow typically produces 3-8 stories
+- Stories are created in step 1 (erp-kit-app-1-requirements) — this step consumes them
 - Stories should be completable in a single user session
 - Screens can be shared across multiple stories
 - Prefer built-in queries over custom resolvers for simple list/get operations

package/skills/erp-kit-app-3-plan/references/resolver-extraction.md

@@ -5,6 +5,7 @@
 App: {{APP_NAME}}
 Actor docs: {{ACTOR_DOCS}}
 Business flow docs: {{BUSINESS_FLOW_DOCS}}
+Story docs: {{STORY_DOCS}}
 
 ## Available Modules
 
@@ -22,8 +23,9 @@ erp-kit doc module <module-name> command <command-name>
 
 1. Read ALL actor docs at the paths above
 2. Read ALL business flow docs at the paths above
-3. Identify GraphQL resolvers needed for each business flow, using the module overview and `erp-kit doc module <name> command` for detail
-4. Return results as a structured markdown report
+3. Read ALL story docs at the paths above
+4. Identify GraphQL resolvers needed for each business flow and story, using the module overview and `erp-kit doc module <name> command` for detail
+5. Return results as a structured markdown report
 
 ## Extraction Rules
 
@@ -32,9 +34,12 @@ erp-kit doc module <module-name> command <command-name>
 For each business flow step that modifies data:
 
 1. Identify the operation type (create, update, delete, approve, etc.)
-2. Map to a resolver name using camelCase action-verb convention
-3. Identify the module command the resolver will call. If no erp-kit module covers the domain, flag it as a module gap.
-4. Extract inputs, outputs, and error scenarios
+2. Determine if the operation needs a resolver:
+   - If the operation is a **scheduled job, cron task, webhook handler, or system-triggered process** that doesn't expose a GraphQL endpoint → mark the story's Resolvers section as `N/A — <reason>` (e.g., `N/A — background job`). No resolver doc is needed.
+   - Otherwise, continue to step 3.
+3. Map to a resolver name using camelCase action-verb convention
+4. Identify the module command the resolver will call. If no erp-kit module covers the domain, flag it as a module gap.
+5. Extract inputs, outputs, and error scenarios
 
 ### Operation → Resolver Mapping
 

package/skills/erp-kit-app-3-plan/references/screen-extraction.md

@@ -5,6 +5,7 @@
 App: {{APP_NAME}}
 Actor docs: {{ACTOR_DOCS}}
 Business flow docs: {{BUSINESS_FLOW_DOCS}}
+Story docs: {{STORY_DOCS}}
 
 ## Available Modules
 
@@ -22,9 +23,10 @@ erp-kit doc module <module-name> model <model-name>
 
 1. Read ALL actor docs at the paths above
 2. Read ALL business flow docs at the paths above
-3. Identify screens needed for each business flow
-4. For screens that display or edit module entities, use `erp-kit doc module <name> model` to understand the entity's domain
-5. Return results as a structured markdown report
+3. Read ALL story docs at the paths above
+4. Identify screens needed for each business flow and story
+5. For screens that display or edit module entities, use `erp-kit doc module <name> model` to understand the entity's domain
+6. Return results as a structured markdown report
 
 ## Extraction Rules
 

package/skills/erp-kit-app-4-plan-review/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: erp-kit-app-4-plan-review
-description: Review parity between Tier 2 (business flows, actors) and Tier 3-4 (stories, screens, resolvers). Use after creating plan documentation with erp-kit-app-3-plan to validate completeness.
+description: Review parity between Tier 2 (business flows, actors, stories) and Tier 3-4 (screens, resolvers). Use after creating plan documentation with erp-kit-app-3-plan to validate completeness.
 ---
 
 # Documentation Parity Review
 
-Review **documentation consistency** across Tier 2, 3, and 4 documentation.
+Review **documentation consistency** across Tier 2 (business flows, actors, stories), Tier 3 (screens), and Tier 4 (resolvers) documentation.
 
 ## When to Use
 
@@ -24,30 +24,35 @@ Define shared context for all agents:
 - `SCREEN_DOCS`: glob `<APP_ROOT>/docs/screen/*.md`
 - `ACTOR_DOCS`: glob `<APP_ROOT>/docs/actors/*.md`
 - `RESOLVER_DOCS`: glob `<APP_ROOT>/docs/resolver/*.md`
+- `MODULE_METADATA`: run `pnpm erp-kit doc modules --format json` and capture the JSON output. This provides authoritative module names, commands, queries, models, and dependencies for validation.
 
 Verify at least `BUSINESS_FLOW_DOCS` is non-empty. If no business flow docs exist, stop with: "No business flow docs found under <APP_ROOT>/docs/."
 
 ## Step 2: Dispatch Agents (parallelize if possible)
 
-Launch 5 Agent tool calls in parallel — one per parity check.
-Each agent receives: APP_NAME, relevant doc file paths.
+Dispatch agents in parallel — one per item in each group. All groups are dispatched simultaneously.
+
+Each agent receives: APP_NAME and the relevant doc file paths for its item.
 Each agent returns: structured JSON per [references/parity-report-format.md](references/parity-report-format.md).
 If a doc directory is empty, the agent reports "no docs found" and skips.
 
-| Agent | Prompt Template                                                                      | Inputs                         |
-| ----- | ------------------------------------------------------------------------------------ | ------------------------------ |
-| 1     | [references/business-flow-story-parity.md](references/business-flow-story-parity.md) | BUSINESS_FLOW_DOCS, STORY_DOCS |
-| 2     | [references/actor-flow-parity.md](references/actor-flow-parity.md)                   | ACTOR_DOCS, BUSINESS_FLOW_DOCS |
-| 3     | [references/story-screen-parity.md](references/story-screen-parity.md)               | STORY_DOCS, SCREEN_DOCS        |
-| 4     | [references/story-resolver-parity.md](references/story-resolver-parity.md)           | STORY_DOCS, RESOLVER_DOCS      |
-| 5     | [references/orphan-detection.md](references/orphan-detection.md)                     | ALL doc paths                  |
+| Group | Prompt Template                                                                      | Per-item scope             | Inputs per agent                              |
+| ----- | ------------------------------------------------------------------------------------ | -------------------------- | --------------------------------------------- |
+| A     | [references/business-flow-story-parity.md](references/business-flow-story-parity.md) | One per business flow      | Single BUSINESS_FLOW_DOC + its STORY_DOCS     |
+| B     | [references/actor-flow-parity.md](references/actor-flow-parity.md)                   | One per actor              | Single ACTOR_DOC + all BUSINESS_FLOW_DOCS     |
+| C     | [references/story-screen-parity.md](references/story-screen-parity.md)               | One per story              | Single STORY_DOC + all SCREEN_DOCS            |
+| D     | [references/story-resolver-parity.md](references/story-resolver-parity.md)           | One per story              | Single STORY_DOC + all RESOLVER_DOCS + MODULE_METADATA |
+| E     | [references/orphan-detection.md](references/orphan-detection.md)                     | One global agent           | ALL doc paths + MODULE_METADATA               |
 
 For each agent:
 
 1. Read the prompt template file
 2. Replace `{{APP_NAME}}` with the resolved app name
-3. Replace doc path placeholders with the actual file paths
-4. Dispatch the agent with the filled prompt
+3. Replace doc path placeholders with the actual file paths for that item
+4. Replace `{{MODULE_METADATA}}` with the JSON output (Group D and E agents only)
+5. Dispatch the agent with the filled prompt
+
+With F flows, A actors, and S stories, this produces F + A + S + S + 1 parallel agents.
 
 ## Step 3: Aggregate Results
 
@@ -56,7 +61,7 @@ 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
+4. Deduplicate: if two agents report the same gap (same `source + target + check`), keep only one
 5. Calculate totals across all summaries
 6. Render the final report below
 

package/skills/erp-kit-app-4-plan-review/references/orphan-detection.md

@@ -8,6 +8,7 @@ Story docs: {{STORY_DOCS}}
 Screen docs: {{SCREEN_DOCS}}
 Actor docs: {{ACTOR_DOCS}}
 Resolver docs: {{RESOLVER_DOCS}}
+Module metadata (JSON): {{MODULE_METADATA}}
 
 ## Instructions
 
@@ -38,6 +39,7 @@ For each doc, record all outgoing link targets (resolved to actual file paths).
 | orphan_screens   | Are there screens not referenced by any story?       |
 | orphan_actors    | Are there actors not participating in any flow?      |
 | orphan_resolvers | Are there resolvers not referenced by any story?     |
+| invalid_module_ref | Do resolvers reference modules or commands/queries that don't exist in installed modules? |
 
 ### How to Check
 
@@ -45,6 +47,7 @@ For each doc, record all outgoing link targets (resolved to actual file paths).
 2. **Orphan screens**: For each file in SCREEN_DOCS, check if any story doc links to it. If no story references it, it is an orphan.
 3. **Orphan actors**: For each file in ACTOR_DOCS, check if any business flow README links to it AND the actor doc links to at least one flow. If neither condition is met, it is an orphan.
 4. **Orphan resolvers**: For each file in RESOLVER_DOCS, check if any story doc links to it. If no story references it, it is an orphan.
+5. **Invalid module references**: Parse MODULE_METADATA JSON. For each resolver doc, extract the module and command/query it calls. Verify the module name exists in MODULE_METADATA and the command/query name appears in that module's `docs.command` or `docs.query` array. Report any mismatches.
 
 ## Common Gap Patterns