@tailor-platform/erp-kit 0.2.2 → 0.4.0

package/skills/erp-kit-app-6-impl-frontend/references/pages.md

@@ -31,27 +31,7 @@ Key points:
 
 - Two-column `Layout`: detail on left, actions on right
 - `useParams()` to get entity ID from route
-- `DescriptionCard` from `@tailor-platform/app-shell` for key-value fields:
-
-```tsx
-<DescriptionCard
-  data={resource}
-  title="Overview"
-  columns={3}
-  fields={[
-    { key: "name", label: "Name", meta: { copyable: true } },
-    {
-      key: "status",
-      label: "Status",
-      type: "badge",
-      meta: { badgeVariantMap: { ACTIVE: "success" } },
-    },
-    { key: "createdAt", label: "Created At", type: "date", meta: { dateFormat: "medium" } },
-  ]}
-/>
-```
-
-Field types: `"text"` (default), `"badge"`, `"money"`, `"date"`, `"link"`, `"address"`, `"reference"`, `"divider"`
+- `DescriptionCard` from `@tailor-platform/app-shell` for key-value fields. Refer to existing examples in the codebase for props and field type usage.
 
 ### Form Pattern
 
@@ -59,8 +39,11 @@ Create and edit forms share the same structure:
 
 - **React Hook Form + Zod** for validation with `zodResolver`
 - **urql `useMutation`** for GraphQL mutations
-- **Cache invalidation**: pass `additionalTypenames` to the mutation context so urql invalidates related queries (e.g., `createUser(values, { additionalTypenames: ["User"] })`)
-- **Toast notifications**: use `useToast` from `@tailor-platform/app-shell` (sonner-based, `Toaster` is built into AppShell) for success/error feedback
+- **Cache invalidation**: pass `additionalTypenames` to the mutation context so urql invalidates related queries after create/edit/delete. Without this, list pages will show stale data.
+  ```ts
+  createUser(values, { additionalTypenames: ["User"] })
+  ```
+- **Toast notifications**: `useToast` from `@/hooks/use-toast`. `toast.error()` accepts `CombinedError` directly (e.g., `toast.error(result.error)`)
 - **Navigate `".."`** to go back to list after success
 - Edit form pre-fills `defaultValues` from existing entity via fragment
 
@@ -81,6 +64,14 @@ Create and edit forms share the same structure:
 - **Required: Yes** → `.min(1, "Field is required")` (string) / `.positive()` (number)
 - **Required: No** → `.optional()`
 
+#### Empty String Handling for Optional Fields
+
+React Hook Form defaults text inputs to `""`. For optional fields (e.g., `parentId`), convert empty strings to `undefined` before submitting to avoid backend errors. Use `||` not `??` — empty string is not nullish:
+
+```ts
+parentId: values.parentId || undefined,
+```
+
 ### Shared Component Patterns
 
 #### Fragment Collocation
@@ -117,13 +108,9 @@ const UserQuery = graphql(
 
 #### App.tsx
 
-- `AuthGuard`: implement yourself, pass via `guardComponent` prop. AuthProvider shows it automatically when `!isReady || !isAuthenticated`, so the guard only needs to render a sign-in UI — no state checks needed inside it
-- `GraphQLProvider`: pass `authClient.fetch` directly to urql's `fetch` option and `authClient.getAppUri()` for the URL
-- `useAuth()` returns `{ isAuthenticated, isReady, login, logout }` directly (not nested in `authState`)
-- Built-in `me` query returns the current user's `User` record — use it instead of writing a custom resolver for profile info
+Refer to existing examples in the codebase for `AuthGuard`, `GraphQLProvider`, auth client setup, and sidebar configuration.
+
 - Required env vars: `VITE_TAILOR_APP_URL`, `VITE_TAILOR_CLIENT_ID`
-- Auth client: create once in `src/lib/auth-client.ts` using `createAuthClient({ appUri, clientId })`
-- Sidebar: use `SidebarGroup` + `SidebarItem` for custom ordering
 
 #### Module-level page.tsx (required)
 
@@ -141,20 +128,3 @@ Every page component must:
 
 1. Be the **default export** of `page.tsx`
 2. Set `appShellPageProps` with at least `meta.title`
-
-#### Common imports
-
-```tsx
-import {
-  Layout,
-  Link,
-  useParams,
-  useNavigate,
-  type AppShellPageProps,
-} from "@tailor-platform/app-shell";
-import { useQuery, useMutation } from "urql";
-import { graphql, type FragmentOf, readFragment } from "@/graphql";
-import { useForm } from "react-hook-form";
-import { zodResolver } from "@hookform/resolvers/zod";
-import { z } from "zod";
-```

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

@@ -21,7 +21,7 @@ Define shared context for all agents:
 - `APP_NAME`: basename of APP_ROOT
 - `RESOLVER_DOCS`: glob `<APP_ROOT>/docs/resolver/*.md`
 - `SCREEN_DOCS`: glob `<APP_ROOT>/docs/screen/*.md`
-- `BACKEND_RESOLVERS`: glob `<APP_ROOT>/backend/src/modules/*/resolvers/*.ts`
+- `BACKEND_RESOLVERS`: glob `<APP_ROOT>/backend/src/resolvers/*.ts`
 - `BACKEND_EXECUTORS`: glob `<APP_ROOT>/backend/executors/*.ts`
 - `BACKEND_MODULES`: `<APP_ROOT>/backend/src/modules.ts`
 - `BACKEND_CONFIG`: `<APP_ROOT>/backend/tailor.config.ts`
@@ -50,16 +50,17 @@ For agents 1-3:
 3. Replace doc/code path placeholders with the actual file paths
 4. Dispatch the agent with the filled prompt
 
-For agent 4 (build verification):
+For agent 4 (build & sync verification):
 
-Run build checks inline:
+Run build checks and source-doc sync check inline:
 
 ```bash
 cd <APP_ROOT>/backend && pnpm lint && pnpm typecheck
 cd <APP_ROOT>/frontend && pnpm lint && pnpm typecheck && pnpm build
+erp-kit app sync-check -p <APP_ROOT>/..
 ```
 
-Report pass/fail for each check.
+Report pass/fail for each check. `sync-check` detects missing resolver implementations and orphaned docs, so agents 1-3 can skip file-existence checks and focus on content parity.
 
 ## Step 3: Aggregate Results
 
@@ -109,13 +110,14 @@ Render the aggregated results as markdown:
 
 ---
 
-### 4. Build Verification
+### 4. Build & Sync Verification
 
-| Check | Backend | Frontend |
-| ----- | ------- | -------- |
-| Lint  |         |          |
-| Types |         |          |
-| Build | N/A     |          |
+| Check      | Backend | Frontend |
+| ---------- | ------- | -------- |
+| Lint       |         |          |
+| Types      |         |          |
+| Build      | N/A     |          |
+| Sync-check |         | N/A      |
 
 (Populated from agent 4 results)
 
@@ -158,7 +160,7 @@ Render the aggregated results as markdown:
 | Resolver Doc → Code Coverage |        | X/Y checks passed |
 | Screen Doc → Code Coverage   |        | X/Y checks passed |
 | Module Wiring Consistency    |        | X/Y checks passed |
-| Build Verification           |        | pass / fail       |
+| Build & Sync Verification    |        | pass / fail       |
 
 ### 8. Recommendations
 

package/skills/erp-kit-app-7-impl-review/references/resolver-doc-code-parity.md

@@ -28,7 +28,7 @@ From each resolver doc, extract:
 
 ## Extraction: Backend Code
 
-From each resolver file (`src/modules/*/resolvers/*.ts`), extract:
+From each resolver file (`src/resolvers/*.ts`), extract:
 
 - Resolver name (from `createResolver()` call or filename)
 - Module command called (import path and function name)
@@ -42,28 +42,27 @@ From each executor file (`executors/*.ts`), extract:
 
 ## Parity Checks
 
-| Check ID             | Question                                                        |
-| -------------------- | --------------------------------------------------------------- |
-| resolver_impl_exists | Does a backend resolver file exist for each resolver doc?       |
-| command_reference    | Does the resolver code call the correct module command?         |
-| input_coverage       | Does the resolver handle all documented input parameters?       |
-| error_handling       | Does the resolver handle all documented error scenarios?        |
-| return_shape         | Does the resolver return the documented output shape?           |
-| executor_exists      | Does an executor exist for each module that has event handlers? |
-| no_direct_mutation   | Does the resolver avoid directly mutating module-owned tables?  |
+| Check ID           | Question                                                        |
+| ------------------ | --------------------------------------------------------------- |
+| command_reference  | Does the resolver code call the correct module command?         |
+| input_coverage     | Does the resolver handle all documented input parameters?       |
+| error_handling     | Does the resolver handle all documented error scenarios?        |
+| return_shape       | Does the resolver return the documented output shape?           |
+| executor_exists    | Does an executor exist for each module that has event handlers? |
+| no_direct_mutation | Does the resolver avoid directly mutating module-owned tables?  |
+
+File existence checks (`resolver_impl_exists`) are handled by `erp-kit app sync-check` in the build verification step. This agent focuses on content parity only.
 
 ### How to Check
 
-1. For each resolver doc, find the corresponding code file by name
-2. Verify the code imports and calls the documented module command
-3. Check that `context.input.*` accesses match documented inputs
-4. Check that error `switch` cases cover all documented error codes
-5. Verify return value structure matches documentation
-6. Check executors re-export module event handlers without custom logic
+1. For each resolver doc that has a corresponding code file, verify the code imports and calls the documented module command
+2. Check that `context.input.*` accesses match documented inputs
+3. Check that error `switch` cases cover all documented error codes
+4. Verify return value structure matches documentation
+5. Check executors re-export module event handlers without custom logic
 
 ## Common Gap Patterns
 
-- **Missing resolver file**: Doc exists but no code file
 - **Wrong command**: Code calls a different module command than documented
 - **Missing input handling**: Doc specifies an input parameter not accessed in code
 - **Missing error cases**: Error scenario in doc not handled in code's switch

package/skills/erp-kit-app-shared/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: erp-kit-app-shared
+description: Shared references for erp-kit app skills. Not invoked directly — referenced by erp-kit-app-1 through erp-kit-app-7.
+---
+
+# erp-kit-app-shared
+
+Canonical reference files shared across app skills. Individual skills reference these instead of maintaining their own copies.
+
+## References
+
+- [Schema constraints](references/schema-constraints.md) — H1 heading rules and validation constraints enforced by `erp-kit app check`
+- [Naming conventions](references/naming-conventions.md) — File and heading naming patterns for all doc types
+- [Link format reference](references/link-format-reference.md) — Canonical doc-to-doc link formats across tiers
+- [Resolver classification](references/resolver-classification.md) — Custom vs built-in resolver decision table and operation mapping

package/skills/erp-kit-app-shared/references/link-format-reference.md

@@ -0,0 +1,13 @@
+# Link Format Reference
+
+Canonical link formats used across all documentation tiers.
+
+## Doc-to-Doc Links
+
+| From          | To            | Format                              |
+| ------------- | ------------- | ----------------------------------- |
+| Business Flow | Story         | `./story/<actor>--<name>.md`        |
+| Business Flow | Actor         | `../../actors/<actor>.md`           |
+| Actor         | Business Flow | `../business-flow/<flow>/README.md` |
+| Story         | Screen        | `../../../screen/<screen>.md`       |
+| Story         | Resolver      | `../../../resolver/<name>.md`       |

package/skills/erp-kit-app-shared/references/naming-conventions.md

@@ -0,0 +1,21 @@
+# Naming Conventions
+
+## File Naming
+
+| Doc Type | Pattern                              | Example                          |
+| -------- | ------------------------------------ | -------------------------------- |
+| Actor    | kebab-case                           | `sales-representative.md`        |
+| Flow     | kebab-case directory                 | `employee-onboarding/README.md`  |
+| Story    | `<actor>--<story-name>.md`           | `admin--create-user.md`          |
+| Screen   | kebab-case, noun-focused             | `supplier-list.md`               |
+| Resolver | camelCase action-verb                | `createSupplierInvitation.md`    |
+
+## Heading Conventions
+
+See [schema-constraints.md](schema-constraints.md) for H1 heading rules enforced by `erp-kit app check`.
+
+Additional conventions:
+
+- Story heading: Title Case of story name after `--` prefix (e.g., `admin--create-user.md` → `# Create User`)
+- Screen heading: Title Case of filename slug
+- Resolver heading: camelCase matching filename

package/skills/erp-kit-app-shared/references/resolver-classification.md

@@ -0,0 +1,23 @@
+# Resolver Classification
+
+## Custom vs Built-in
+
+| Category             | Description                                                                        | Implementation                                                               |
+| -------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| **Custom resolvers** | Mutations that call module commands (create, update, activate, deactivate, assign) | Write `createResolver()` files                                               |
+| **Built-in queries** | List and get operations for reading data                                           | Handled automatically by `gqlOperations: "query"` in config — no code needed |
+
+Prefer built-in queries over custom resolvers for list/get operations where possible.
+
+## Operation → Resolver Mapping
+
+| Flow Operation       | Resolver Type | Naming Pattern         |
+| -------------------- | ------------- | ---------------------- |
+| Create/Add entity    | Mutation      | `create<Entity>`       |
+| Update/Modify entity | Mutation      | `update<Entity>`       |
+| Delete/Remove entity | Mutation      | `delete<Entity>`       |
+| Activate entity      | Mutation      | `activate<Entity>`     |
+| Deactivate entity    | Mutation      | `deactivate<Entity>`   |
+| Assign X to Y        | Mutation      | `assign<X>To<Y>`       |
+| Submit/Approve       | Mutation      | `submit<Entity>` etc.  |
+| View/List/Get        | Query         | Built-in (no resolver) |

package/skills/erp-kit-app-shared/references/schema-constraints.md

@@ -0,0 +1,25 @@
+# Schema Constraints
+
+Rules enforced by `erp-kit app check`. **Never recommend changes that violate them.**
+
+## H1 Heading Rules
+
+| Doc Type      | H1 Rule                                              | Example                                                  |
+| ------------- | ---------------------------------------------------- | -------------------------------------------------------- |
+| README.md     | Must be `# README` (literal)                         | `# README`                                               |
+| Actor         | Slug must match filename                             | `admin.md` → `# Admin`, `sales-rep.md` → `# Sales Rep`  |
+| Business Flow | Kebab-case matching folder name (`[a-zA-Z0-9_\-]+`)  | `employee-onboarding/README.md` → `# employee-onboarding` |
+| Story         | Slug matches filename after actor prefix removal     | `admin--create-user.md` → `# Create User`               |
+
+## Requirements Structure
+
+The `## Industry Context` section contains `### Target Industry` and `### Domain Terminology` subsections. Requirements are bare list items under `### Domain Terminology` — do **not** add a separate `## Requirements` heading.
+
+## Naming Conventions
+
+- Files: kebab-case (e.g., `sales-representative.md`)
+- Business flow H1 headings are kebab-case — do **not** flag them as inconsistent with title-case actor headings. They follow different schemas.
+
+## Validation Notes
+
+- `app check` outputs "No matching files found" for doc types that don't exist yet (e.g., stories at Tier 2, screens at Tier 3). This is expected.

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

@@ -5,7 +5,7 @@ description: Create ERP module requirements and feature documentation. Use when
 
 # Module Requirements Workflow
 
-Collaborative workflow for creating ERP module requirements. Uses parallel agents for research, then human validates and decides scope.
+Autonomous workflow for creating ERP module requirements. Uses parallel agents for research, then automatically decides scope based on recommendations.
 
 ## Workflow
 
@@ -22,7 +22,7 @@ Define shared context for all agents:
 - `DOMAIN`: the business domain (e.g., "inventory management", "purchasing")
 - `OTHER_MODULES`: glob `<MODULES_ROOT>/*/README.md` (to understand existing module landscape)
 
-Ask the user for the MODULE_NAME and DOMAIN if not provided.
+Infer MODULE_NAME and DOMAIN from the current working directory or argument context. If insufficient, use the module's README or directory name.
 
 ## Step 2: Dispatch Agents (parallelize if possible)
 
@@ -63,16 +63,14 @@ For each feature:
 - **Recommendation:** `Include` or `Skip`
 - **Why:** reasoning for the recommendation
 
-Then ask the user: "推薦を変更したい機能はありますか？"
-
-The final feature set becomes the union of all `Include` features. Iterate until the user approves.
+The final feature set becomes the union of all `Include` features. Proceed with the recommended scope.
 
 ## Step 4: Create — Agent per feature
 
 First, scaffold the module if it doesn't exist:
 
 ```bash
-erp-kit scaffold --modules-root <MODULES_ROOT> module <module-name>
+erp-kit module init <module-name> <MODULES_ROOT>/<module-name>
 ```
 
 Then, for each `Include` feature, launch an Agent:
@@ -96,19 +94,15 @@ pnpm run module:doc:check
 
 ## Step 5: Review
 
-User reviews generated feature docs and may request changes.
-
-**Split detection**: If a feature covers multiple distinct workflows, split into separate feature files.
+**Split detection**: If a feature covers multiple distinct workflows, split into separate feature files automatically.
 
-**Iteration pattern:**
+**Auto-split pattern:**
 
-1. User identifies issue (e.g., "X is too broad, split it")
+1. Detect features that cover multiple distinct workflows
 2. Create new feature file for split-out content
 3. Remove split content from original file
 4. Update README.md feature list if needed
 
-Continue iterating until user approves.
-
 # Framework Schemas Reference
 
 Schemas are bundled in `@tailor-platform/erp-kit`.

package/skills/erp-kit-module-1-requirements/references/feature-doc.md

@@ -14,7 +14,7 @@ Write a feature documentation file for the {{FEATURE_NAME}} feature.
 1. Read existing feature docs in `{{MODULES_ROOT}}/{{MODULE_NAME}}/docs/features/` for style reference
 2. Scaffold the file:
    ```bash
-   erp-kit scaffold --modules-root {{MODULES_ROOT}} feature {{MODULE_NAME}} {{FEATURE_SLUG}}
+   erp-kit module generate doc feature {{FEATURE_SLUG}} -p {{MODULES_ROOT}}/{{MODULE_NAME}}
    ```
 3. Fill in the scaffolded file following the structure below
 

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

@@ -52,7 +52,14 @@ After ALL agents return:
 2. Merge all `issues[]` arrays into a single list
 3. Merge all `recommendations[]` arrays into a single list
 4. Calculate totals across all summaries
-5. Render the final report below
+5. **Classify severity** — for each non-pass finding, the router assigns a severity based on the finding's `status`, `check`, and `detail`:
+   - `critical`: fundamental design flaw, missing required capability, boundary violation — blocks progress
+   - `major`: significant gap that will likely cause downstream issues — should fix
+   - `nit`: cosmetic, stylistic, or minor improvement — does NOT block the review
+6. **Determine verdict**:
+   - **APPROVED**: zero `critical` and zero `major` findings (nits only, or all pass)
+   - **NEEDS CHANGES**: one or more `critical` or `major` findings
+7. Render the final report below
 
 ## Report Format
 
@@ -100,11 +107,20 @@ Render the aggregated results as markdown:
 
 ### 5. Recommendations
 
-Numbered list of actionable fixes, grouped by priority:
+Numbered list of actionable fixes, grouped by severity:
 
-1. Critical boundary issues (highest priority)
-2. Best practice violations
-3. Improvement suggestions
+1. `critical` — boundary issues, fundamental design flaws (must fix)
+2. `major` — best practice violations, missing capabilities (should fix)
+3. `nit` — cosmetic, stylistic, minor improvements (informational only)
+
+### 6. Verdict
+
+**Verdict: APPROVED / NEEDS CHANGES**
+
+- If APPROVED with nits: "Review passed. The following nits are informational and do not block progress:" followed by the nit list.
+- If NEEDS CHANGES: "Review requires changes. Fix all critical and major issues, then re-run the review."
+
+Severity counts: `critical: N, major: N, nit: N`
 
 ## References
 

package/skills/erp-kit-module-2-requirements-review/references/requirements-report-format.md

@@ -23,3 +23,22 @@ A numbered list of actionable suggestions, grouped by priority:
 ### Summary
 
 A summary table with aggregate counts: total checks, passed, failed, warned.
+
+## Router-Level Severity and Verdict
+
+The router (SKILL.md Step 3) assigns severity to each non-pass finding after collecting all agent results. Agents do NOT assign severity — they only report `status` and `detail`.
+
+The router classifies each finding as:
+
+| Severity   | Meaning                                                                                     | Examples                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `critical` | Blocks progress — fundamental design flaw, missing required capability, or boundary violation | Missing entity ownership, overlapping CRUD with another module, broken state machine      |
+| `major`    | Should fix — will likely cause issues downstream but not a design blocker                    | Missing standard ERP state, unclear dependency direction, incomplete business rules       |
+| `nit`      | Nice to have — cosmetic, stylistic, or minor improvement suggestion                         | Naming convention preference, optional field suggestion, documentation wording improvement |
+
+Verdict rule:
+
+- **APPROVED**: zero `critical` and zero `major` findings (nits only, or all pass)
+- **NEEDS CHANGES**: one or more `critical` or `major` findings
+
+When verdict is APPROVED with nits, list the nits as informational notes — they do NOT block the review.

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

@@ -33,22 +33,20 @@ Use the extraction rules from:
 - [references/command-extraction.md](references/command-extraction.md) — write operations, business rules, error scenarios, process flows
 - [references/query-extraction.md](references/query-extraction.md) — read operations, lookups, aggregations, conversions
 
-Present consolidated plan to user:
+Produce consolidated plan:
 
 - Models to create (with fields, relationships, states)
 - Commands to create (with business rules, error scenarios)
 - Queries to create (with inputs, outputs)
 
-Wait for user approval.
-
 ## Step 3: Scaffold & Populate
 
-After approval, scaffold using `erp-kit` CLI:
+Scaffold using `erp-kit` CLI. **Names must be PascalCase** (see [naming convention](references/naming.md)):
 
 ```bash
-erp-kit scaffold --modules-root <MODULES_ROOT> model <module-name> <model-name>
-erp-kit scaffold --modules-root <MODULES_ROOT> command <module-name> <command-name>
-erp-kit scaffold --modules-root <MODULES_ROOT> query <module-name> <query-name>
+erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>
+erp-kit module generate doc command CommandName -p <MODULES_ROOT>/<module-name>
+erp-kit module generate doc query QueryName -p <MODULES_ROOT>/<module-name>
 ```
 
 Fill in the scaffolded docs with details from the extraction in Step 2.
@@ -103,5 +101,5 @@ pnpm run module:doc:check
 
 ## References
 
-- [Command naming convention](references/naming.md)
+- [Naming convention (PascalCase files + command verbs)](references/naming.md)
 - [Module structure](../erp-kit-module-shared/references/structure.md)

package/skills/erp-kit-module-3-plan/references/naming.md

@@ -1,4 +1,18 @@
-# Command Naming Convention
+# Naming Convention
+
+## Doc File Names — PascalCase
+
+Documentation files under `docs/models/`, `docs/commands/`, and `docs/queries/` **must** use PascalCase. The code generator derives the camelCase command/query name by lowercasing the first character of the file name.
+
+| Doc type | File name format  | Example file       | Derived name    |
+| -------- | ----------------- | ------------------ | --------------- |
+| Model    | `{Entity}.md`     | `Product.md`       | —               |
+| Command  | `{VerbEntity}.md` | `CreateProduct.md` | `createProduct` |
+| Query    | `{VerbEntity}.md` | `GetProduct.md`    | `getProduct`    |
+
+**Never use kebab-case** (`create-product.md`) — the generator will produce a broken name (`create-product`).
+
+## Command Naming Convention
 
 Commands use imperative `{verb}{Entity}` format. Use this canonical verb vocabulary when scaffolding commands.
 

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

@@ -57,7 +57,14 @@ After ALL agents return:
 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
-6. Render the final report below
+6. **Classify severity** — for each non-pass gap and inconsistency, the router assigns a severity based on the finding's `check`, `status`, and `detail`:
+   - `critical`: missing required doc, fundamental parity break — blocks progress
+   - `major`: incomplete coverage, missing business rules — should fix
+   - `nit`: minor naming inconsistency, optional improvement — does NOT block the review
+7. **Determine verdict**:
+   - **APPROVED**: zero `critical` and zero `major` findings (nits only, or all pass)
+   - **NEEDS CHANGES**: one or more `critical` or `major` findings
+8. Render the final report below
 
 ## Report Format
 
@@ -146,11 +153,20 @@ Render the aggregated results as markdown:
 
 ### 8. Recommendations
 
-Numbered list of actionable fixes, grouped by priority:
+Numbered list of actionable fixes, grouped by severity:
 
-1. Create missing docs (highest priority)
-2. Add missing business rules / error scenarios
-3. Resolve inconsistencies
+1. `critical` — missing required docs, fundamental parity gaps (must fix)
+2. `major` — missing business rules, incomplete error scenarios (should fix)
+3. `nit` — minor naming inconsistencies, optional improvements (informational only)
+
+### 9. Verdict
+
+**Verdict: APPROVED / NEEDS CHANGES**
+
+- If APPROVED with nits: "Review passed. The following nits are informational and do not block progress:" followed by the nit list.
+- If NEEDS CHANGES: "Review requires changes. Fix all critical and major issues, then re-run the review."
+
+Severity counts: `critical: N, major: N, nit: N`
 
 ## References
 

package/skills/erp-kit-module-4-plan-review/references/parity-report-format.md

@@ -50,3 +50,18 @@ Cross-cutting issues found during the check that don't fit a single gap entry (e
 ### summary
 
 Aggregate counts. `total_checks = passed + failed + skipped`.
+
+## Router-Level Severity and Verdict
+
+The router (SKILL.md Step 3) assigns severity to each non-pass finding after collecting all agent results. Agents do NOT assign severity — they only report `status` and `detail`.
+
+The router classifies each finding as:
+
+- `critical`: blocks progress — missing required doc, fundamental design mismatch
+- `major`: should fix — incomplete coverage, unclear mapping, missing business rules
+- `nit`: nice to have — minor naming inconsistency, optional doc improvement, cosmetic issue
+
+Verdict rule:
+
+- `APPROVED`: zero `critical` and zero `major` findings (nits only, or all pass)
+- `NEEDS_CHANGES`: one or more `critical` or `major` findings

package/skills/erp-kit-module-5-impl/SKILL.md

@@ -17,7 +17,7 @@ Implement features in modules using Test-Driven Development with per-item agent
 ## Workflow
 
 ```
-SETUP → DB MODELS (agents) → GENERATE → COMMANDS (agents) → QUERIES (agents) → EXPORT → VERIFY
+SETUP → GENERATE → DB MODELS (agents) → COMMANDS (agents) → QUERIES (agents) → EXPORT → VERIFY
 ```
 
 ## Step 1: Setup
@@ -32,7 +32,17 @@ Define shared context:
 
 Verify at least one doc type exists. If none, stop with: "No docs found for module <MODULE_NAME>. Run steps 1-4 first."
 
-## Step 2: DB Models — Agent per model
+## Step 2: Generate Code from Docs
+
+Run generation first to create `.generated.ts` files (error classes, permission definitions, command/query shells) before implementing any code:
+
+```bash
+erp-kit module generate code -p <MODULES_ROOT>/<module>
+```
+
+Never edit these generated files.
+
+## Step 3: DB Models — Agent per model
 
 **Read [models rules](references/models.md) and [db-relations rules](references/db-relations.md) before dispatching.**
 
@@ -51,14 +61,6 @@ After all model agents complete, run:
 pnpm generate
 ```
 
-## Step 3: Generate Code from Docs
-
-```bash
-erp-kit module generate code --root <root> <module>
-```
-
-Generated `.generated.ts` files provide: error classes, permission definitions, and command/query shells. Never edit these files.
-
 ## Step 4: Commands — Agent per command
 
 **Read [commands rules](../erp-kit-module-shared/references/commands.md) and [testing rules](../erp-kit-module-shared/references/testing.md) before dispatching.**

package/skills/erp-kit-module-5-impl/references/generated-code.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Run `erp-kit module generate code --root <modules-dir> <module-name>` to generate deterministic `.generated.ts` files from command and query documentation.
+Run `erp-kit module generate code -p <modules-dir>/<module-name>` to generate deterministic `.generated.ts` files from command and query documentation.
 
 ## What gets generated
 
@@ -21,7 +21,7 @@ Run `erp-kit module generate code --root <modules-dir> <module-name>` to generat
 1. Write command/query docs (skills 1-3)
 2. Write db models (skill 4, step 2)
 3. Run `pnpm generate` for kysely types
-4. Run `erp-kit module generate code --root <root> <module>`
+4. Run `erp-kit module generate code -p <root>/<module>`
 5. Implement business logic in `.ts` files importing from `.generated.ts`
 
 ## What you still write by hand