@tailor-platform/erp-kit 0.3.0 → 0.4.0

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-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,9 +63,7 @@ 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
 
@@ -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-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,17 +33,15 @@ 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. **Names must be PascalCase** (see [naming convention](references/naming.md)):
+Scaffold using `erp-kit` CLI. **Names must be PascalCase** (see [naming convention](references/naming.md)):
 
 ```bash
 erp-kit module generate doc model ModelName -p <MODULES_ROOT>/<module-name>

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-6-impl-review/SKILL.md

@@ -59,7 +59,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 implementation of documented feature, broken doc-code contract — blocks progress
+   - `major`: incomplete implementation, missing test case for documented business rule — should fix
+   - `nit`: minor naming difference, optional JSDoc, cosmetic issue — 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
 
@@ -171,13 +178,20 @@ Render the aggregated results as markdown:
 
 ### 10. Recommendations
 
-Numbered list of actionable fixes, grouped by priority:
+Numbered list of actionable fixes, grouped by severity:
 
-1. Add missing model fields/states (highest priority)
-2. Implement missing business rules
-3. Define missing error classes (re-run `erp-kit module generate code -p <path>`)
-4. Add missing test cases
-5. Fix inconsistencies
+1. `critical` — missing model fields/states, broken doc-code contract (must fix)
+2. `major` — missing business rules, incomplete test coverage (should fix)
+3. `nit` — minor naming differences, optional JSDoc, cosmetic issues (informational only)
+
+### 11. 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-6-impl-review/references/impl-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 implementation of documented feature, broken contract between doc and code
+- `major`: should fix — incomplete implementation, missing test case for documented business rule
+- `nit`: nice to have — minor naming difference, optional JSDoc improvement, cosmetic code style 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-shared/SKILL.md

@@ -7,6 +7,10 @@ description: Shared references for erp-kit module skills. Not invoked directly
 
 Canonical reference files shared across module skills. Individual skills reference these instead of maintaining their own copies.
 
+## Design Philosophy
+
+Modules are intentionally simple. Each module is a thin layer of domain logic over the database — avoid introducing unnecessary abstractions, deep inheritance hierarchies, or complex patterns. Over-engineering is actively harmful: it makes modules harder to understand, test, and maintain. When in doubt, choose the straightforward approach. A few lines of duplicated code is better than a premature abstraction.
+
 ## References
 
 - [Module structure](references/structure.md)

package/src/commands/app/index.ts

@@ -4,8 +4,9 @@ import { defineCommand, arg } from "politty";
 import { runCheck } from "../check";
 import { runSyncCheck, formatSyncCheckReport } from "../sync-check";
 import { runGenerateDoc, APP_DOC_TYPES, type DocType } from "../generate-doc";
-import { runGenerateAppCode } from "../../generator/generate-code";
+import { runGenerateAppCode } from "../../generator/generate-app-code";
 import { runInitAppWithReadme } from "../init-module";
+import { executeCommand, success, silentFailure } from "../lib/command-result";
 
 const cwd = process.cwd();
 
@@ -20,9 +21,11 @@ const checkCommand = defineCommand({
   name: "check",
   description: "Validate app docs against schemas",
   args: pathArgs,
-  run: async (args) => {
-    const exitCode = await runCheck({ appRoot: args.path }, cwd);
-    process.exit(exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const exitCode = await runCheck({ appRoot: args.path }, cwd);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -30,10 +33,12 @@ const syncCheckCommand = defineCommand({
   name: "sync-check",
   description: "Validate source <-> doc correspondence",
   args: pathArgs,
-  run: async (args) => {
-    const result = await runSyncCheck({ appRoot: args.path }, cwd);
-    console.log(formatSyncCheckReport(result));
-    process.exit(result.exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const result = await runSyncCheck({ appRoot: args.path }, cwd);
+      console.log(formatSyncCheckReport(result));
+      return result.exitCode === 0 ? success() : silentFailure(result.exitCode);
+    });
   },
 });
 
@@ -50,9 +55,11 @@ const initCommand = defineCommand({
       description: "Parent directory where the app will be created",
     }),
   }),
-  run: async (args) => {
-    const exitCode = await runInitAppWithReadme(args.name, args.dir, cwd);
-    process.exit(exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const exitCode = await runInitAppWithReadme(args.name, args.dir, cwd);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -69,9 +76,11 @@ const docCommand = defineCommand({
       description: "Item name (required for most types)",
     }),
   }),
-  run: async (args) => {
-    const exitCode = await runGenerateDoc(args.type as DocType, args.name, args.path, cwd);
-    process.exit(exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const exitCode = await runGenerateDoc(args.type as DocType, args.name, args.path, cwd);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -80,9 +89,11 @@ const codeCommand = defineCommand({
   description: "Generate boilerplate source files from docs",
   args: pathArgs,
   run: (args) => {
-    const appPath = path.resolve(cwd, args.path);
-    const exitCode = runGenerateAppCode(appPath);
-    process.exit(exitCode);
+    return executeCommand(() => {
+      const appPath = path.resolve(cwd, args.path);
+      const exitCode = runGenerateAppCode(appPath);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 

package/src/commands/check.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { buildCheckTargets } from "./check";
+import { buildCheckTargets } from "./lib/discovery";
 
 describe("buildCheckTargets", () => {
   it("generates module targets when modulesRoot is set", () => {

package/src/commands/check.ts

@@ -1,41 +1,8 @@
 import { runMdschema } from "../mdschema";
 import { ALL_SCHEMAS } from "../schemas";
-export interface CheckTarget {
-  glob: string;
-  schemaKey: string;
-}
-
-export function buildCheckTargets(config: {
-  modulesRoot?: string;
-  appRoot?: string;
-}): CheckTarget[] {
-  const targets: CheckTarget[] = [];
-
-  if (config.modulesRoot) {
-    const m = config.modulesRoot;
-    targets.push(
-      { glob: `${m}/[a-zA-Z]*/docs/features/*.md`, schemaKey: "feature" },
-      { glob: `${m}/[a-zA-Z]*/docs/commands/*.md`, schemaKey: "command" },
-      { glob: `${m}/[a-zA-Z]*/docs/models/*.md`, schemaKey: "model" },
-      { glob: `${m}/[a-zA-Z]*/docs/queries/*.md`, schemaKey: "query" },
-      { glob: `${m}/[a-zA-Z]*/README.md`, schemaKey: "module" },
-    );
-  }
+import { buildCheckTargets } from "./lib/discovery";
 
-  if (config.appRoot) {
-    const a = config.appRoot;
-    targets.push(
-      { glob: `${a}/[a-zA-Z]*/README.md`, schemaKey: "app" },
-      { glob: `${a}/[a-zA-Z]*/docs/actors/*.md`, schemaKey: "actors" },
-      { glob: `${a}/[a-zA-Z]*/docs/business-flow/*/README.md`, schemaKey: "business-flow" },
-      { glob: `${a}/[a-zA-Z]*/docs/business-flow/*/story/*.md`, schemaKey: "story" },
-      { glob: `${a}/[a-zA-Z]*/docs/screen/*.md`, schemaKey: "screen" },
-      { glob: `${a}/[a-zA-Z]*/docs/resolver/*.md`, schemaKey: "resolver" },
-    );
-  }
-
-  return targets;
-}
+export type { CheckTarget } from "./lib/discovery";
 
 export async function runCheck(
   config: { modulesRoot?: string; appRoot?: string },

package/src/commands/doc/index.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { defineCommand, arg } from "politty";
+import { executeCommand, success, silentFailure } from "../lib/command-result";
+import { runDocModules } from "./modules";
+import { runDocModule } from "./module";
+import { runDocSearch } from "./search";
+
+const formatArg = arg(z.enum(["text", "json"]).default("text"), {
+  alias: "f",
+  description: "Output format (text or json)",
+});
+
+const modulesCommand = defineCommand({
+  name: "modules",
+  description: "List all modules with capabilities overview",
+  args: z.object({
+    format: formatArg,
+  }),
+  run: (args) => {
+    return executeCommand(() => {
+      const exitCode = runDocModules(args.format);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
+  },
+});
+
+const moduleCommand = defineCommand({
+  name: "module",
+  description: "Show documentation for a specific module",
+  args: z.object({
+    name: arg(z.string(), {
+      positional: true,
+      description: "Module name",
+    }),
+    type: arg(z.string().optional(), {
+      positional: true,
+      description: "Doc type (command, query, model, feature)",
+    }),
+    docName: arg(z.string().optional(), {
+      positional: true,
+      description: "Doc name",
+    }),
+    format: formatArg,
+  }),
+  run: (args) => {
+    return executeCommand(() => {
+      const exitCode = runDocModule(args.name, args.type, args.docName, args.format);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
+  },
+});
+
+const searchCommand = defineCommand({
+  name: "search",
+  description: "Search across all module documentation",
+  args: z.object({
+    query: arg(z.string(), {
+      positional: true,
+      description: "Search query",
+    }),
+    type: arg(z.string().optional(), {
+      alias: "t",
+      description: "Filter by doc type (command, query, model, feature, readme)",
+    }),
+    format: formatArg,
+  }),
+  run: (args) => {
+    return executeCommand(() => {
+      const exitCode = runDocSearch(args.query, args.type, args.format);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
+  },
+});
+
+export const docCommand = defineCommand({
+  name: "doc",
+  description: "Browse module documentation",
+  subCommands: {
+    modules: modulesCommand,
+    module: moduleCommand,
+    search: searchCommand,
+  },
+});