@tailor-platform/erp-kit 0.2.1 → 0.2.2

package/skills/erp-kit-module-6-impl-review/references/command-doc-code-parity.md

@@ -0,0 +1,92 @@
+# Command Doc → Command Code Parity Check
+
+## Context
+
+Module: {{MODULE_NAME}}
+Command docs: {{COMMAND_DOCS}}
+Command code: {{COMMAND_CODE}}
+
+## Instructions
+
+1. Read ALL command docs at the paths above
+2. Read ALL command code files at the paths above
+3. For each command doc, extract business rules, process flow branches, input/output types
+4. For each command code file, extract validation logic, branching paths, input interface, return type
+5. Run every parity check below against each command
+6. Return results as JSON per the Output Format section
+
+## Extraction: Command Docs
+
+From each command doc, extract:
+
+- **Business rules**: numbered validation rules
+- **Process flow**: branches from mermaid flowchart (decision nodes and their paths)
+- **Input fields**: documented input parameters
+- **Output type**: documented return structure
+- **State transitions**: any status changes performed
+
+## Extraction: Command Code
+
+From each command code file (`command/*.ts`, excluding `*.test.ts` and `*.generated.ts`), extract:
+
+- **Validation logic**: if/guard checks that enforce business rules
+- **Branching paths**: if/else, early returns, switch statements
+- **Input interface**: exported `interface ...Input` fields
+- **Return type**: `ok(...)` / `err(...)` structure
+- **Generated shell**: existence of corresponding `.generated.ts` file
+
+## Implementation Pattern Reference
+
+See [commands.md](commands.md) for the canonical implementation patterns:
+
+- `run` function + generated shell pattern
+- Custom fields (generic CF) usage rules
+- State transition `from` parameter pattern
+- Return format conventions
+
+## Parity Checks
+
+For each command:
+
+| Check ID                | Question                                                |
+| ----------------------- | ------------------------------------------------------- |
+| business_rule_impl      | Is each documented business rule implemented in code?   |
+| process_flow_alignment  | Do code branches match documented process flow?         |
+| input_type_coverage     | Does input interface include all documented inputs?     |
+| return_type_accuracy    | Does return type match documented output?               |
+| generated_shell_pattern | Does command export `run` with a `.generated.ts` shell? |
+| input_interface_export  | Is the input interface exported?                        |
+| jsdoc_present           | Does the `run` function have a JSDoc comment?           |
+
+### How to Check
+
+1. List all business rules from command doc
+2. Find corresponding validation/guard in command code
+3. Trace each process flow branch to a code path
+4. Compare input interface fields with doc input fields
+5. Verify `.generated.ts` file exists and imports `run`
+6. Check return type wraps result in object (`{ entity }`)
+
+## Common Gap Patterns
+
+- **Unimplemented business rules**: Rule in doc but no validation code
+- **Missing process branches**: Flowchart branch not in code logic
+- **Missing generated shell**: No `.generated.ts` file for command
+- **Input mismatch**: Doc input fields not in interface
+- **Return format mismatch**: Code returns raw entity instead of `{ entity }`
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "command-doc-code-parity",
+  "module": "{{MODULE_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.

package/skills/erp-kit-module-6-impl-review/references/command-doc-test-parity.md

@@ -0,0 +1,93 @@
+# Command Doc → Test Coverage Parity Check
+
+## Context
+
+Module: {{MODULE_NAME}}
+Command docs: {{COMMAND_DOCS}}
+Test code: {{TEST_CODE}}
+
+## Instructions
+
+1. Read ALL command docs at the paths above
+2. Read ALL test code files at the paths above
+3. For each command doc, extract process flow branches, error scenarios, and idempotent paths
+4. For each test file, extract test case descriptions and assertions
+5. Run every parity check below against each command
+6. Return results as JSON per the Output Format section
+
+## Extraction: Command Docs
+
+From each command doc, extract:
+
+### Process Flow Branches
+
+From the mermaid flowchart, identify each decision node and its outcomes:
+
+- Decision: "Entity exists?" → Yes path, No path
+- Decision: "Status valid?" → Valid path, Invalid path
+- Each terminal node = one expected test case
+
+### Error Scenarios
+
+From the Error Scenarios table:
+
+- Error code + condition = one expected error test case
+
+### Idempotent Paths
+
+From the process flow, identify "already exists → return existing" patterns:
+
+- These need explicit test cases
+
+## Extraction: Test Code
+
+From each test file (`command/*.test.ts`), extract:
+
+- **Test descriptions**: `it("...")` or `test("...")` strings
+- **Error assertions**: checks for specific error types/codes
+- **Happy path tests**: tests that verify successful outcomes
+- **Fixture usage**: which fixtures are used
+
+See [testing.md](testing.md) for canonical testing patterns.
+
+## Parity Checks
+
+For each command:
+
+| Check ID              | Question                                                   |
+| --------------------- | ---------------------------------------------------------- |
+| process_flow_coverage | Does each branch in process flow have a test case?         |
+| error_scenario_tests  | Does each documented error scenario have a test assertion? |
+| happy_path_tests      | Are success paths tested?                                  |
+| idempotent_path_tests | If doc shows "already exists → return", is this tested?    |
+
+### How to Check
+
+1. Count process flow branches from command doc flowchart
+2. Count test cases in corresponding test file
+3. Map each branch to a test case by description/assertion
+4. Identify any branches without corresponding tests
+
+## Common Gap Patterns
+
+- **Uncovered process branches**: Flowchart branch has no test
+- **Missing error tests**: Error scenario has no assertion
+- **Missing idempotent tests**: "Return existing" path untested
+- **Missing edge cases**: Boundary conditions not tested
+- **Test without doc branch**: Test exists but doesn't map to documented flow (potential doc gap)
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "command-doc-test-parity",
+  "module": "{{MODULE_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.

package/skills/erp-kit-module-6-impl-review/references/error-implementation-parity.md

@@ -0,0 +1,95 @@
+# Error Implementation Parity Check
+
+## Context
+
+Module: {{MODULE_NAME}}
+Command docs: {{COMMAND_DOCS}}
+Error definitions: {{ERROR_DEFS}}
+Command code: {{COMMAND_CODE}}
+Test code: {{TEST_CODE}}
+
+## Instructions
+
+1. Read ALL command docs at the paths above
+2. Read the error definitions file at the path above
+3. Read ALL command code files at the paths above
+4. Read ALL test code files at the paths above
+5. For each documented error scenario, trace through generated class → command return → test assertion
+6. Run every parity check below
+7. Return results as JSON per the Output Format section
+
+## Extraction: Command Docs
+
+From each command doc's Error Scenarios section, extract:
+
+- **Error code**: e.g. `ENTITY_NOT_FOUND`
+- **Condition**: when this error is returned
+- **Expected class name**: derived from error code (PascalCase + `Error` suffix)
+
+## Extraction: Error Definitions
+
+From `lib/errors.generated.ts`, extract:
+
+- **Error class names**: exported error classes
+- **Error codes**: the code constant in each class
+- **Error message patterns**: message templates
+
+See [errors.md](errors.md) for error generation patterns.
+
+## Extraction: Command Code
+
+From each command file (`command/*.ts`, excluding `*.test.ts` and `*.generated.ts`), extract:
+
+- **Error imports**: which error classes are imported from `../lib/errors.generated`
+- **Error returns**: `return err(new XError(...))` statements
+- **Error codes used**: which error codes appear in the code
+
+## Extraction: Test Code
+
+From each test file (`command/*.test.ts`), extract:
+
+- **Error assertions**: tests that check for specific error types or codes
+- **Error test descriptions**: test names that reference error scenarios
+
+## Parity Checks
+
+For each error scenario documented in command docs:
+
+| Check ID              | Question                                                                                                                                     |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| error_class_generated | Does the error class exist in `errors.generated.ts`?                                                                                         |
+| error_code_accuracy   | Does the generated error code equal `{MODULE_PREFIX}_{DOC_CODE}`? The generator prefixes doc codes with the module name in UPPER_SNAKE_CASE. |
+| error_returned        | Does the command code return this error via `err(new XError(...))`?                                                                          |
+| error_import          | Does the command code import the error class from `errors.generated`?                                                                        |
+| error_test_exists     | Does a test case assert this error scenario?                                                                                                 |
+
+### How to Check
+
+1. List all error codes from command docs
+2. Verify each has a generated class in `errors.generated.ts`
+3. Check command code imports and returns the error
+4. Check test file has an assertion for this error
+
+## Common Gap Patterns
+
+- **Missing error class**: Error code in doc but no generated class (re-run `erp-kit module generate code`)
+- **Error not returned**: Generated class exists but command code doesn't return it
+- **Error not imported**: Command uses inline error instead of generated class
+- **Missing error test**: Error is returned in code but no test asserts it
+- **Error code mismatch**: Doc code differs from generated/code code
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "error-implementation-parity",
+  "module": "{{MODULE_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.

package/skills/{erp-kit-module-5-impl-review → erp-kit-module-6-impl-review}/references/errors.md

@@ -6,5 +6,5 @@ Errors are **generated** from command/query documentation into `lib/errors.gener
 
 - Every error code in `docs/commands/*.md` has a corresponding class in `lib/errors.generated.ts`
 - Command implementations import errors from `../lib/errors.generated`
-- Error codes in code match documented codes exactly
+- Generated error codes are prefixed with the module name (e.g., doc code `UNIT_NOT_FOUND` becomes `PRIMITIVES_UNIT_NOT_FOUND`)
 - If errors are missing, re-run `erp-kit module generate code`

package/skills/erp-kit-module-6-impl-review/references/impl-parity-report-format.md

@@ -0,0 +1,52 @@
+# Implementation Parity Report Format
+
+All implementation parity check agents return results in this JSON structure.
+
+## Schema
+
+```json
+{
+  "check_type": "<one of: model-doc-code-parity, command-doc-code-parity, error-implementation-parity, command-doc-test-parity>",
+  "module": "<module-name>",
+  "gaps": [
+    {
+      "source": "<source doc or code path>",
+      "target": "<target code or doc path, or 'missing'>",
+      "check": "<check_id from the agent's parity checks table>",
+      "status": "pass | fail | skip",
+      "detail": "<human-readable description of the finding>"
+    }
+  ],
+  "inconsistencies": [
+    {
+      "type": "<inconsistency type, e.g. type_mismatch, missing_description>",
+      "location": "<source vs target description>",
+      "detail": "<human-readable description>"
+    }
+  ],
+  "summary": {
+    "total_checks": 0,
+    "passed": 0,
+    "failed": 0,
+    "skipped": 0
+  }
+}
+```
+
+## Field Reference
+
+### gaps[]
+
+One entry per parity check performed. `status` is:
+
+- `pass`: doc and code are consistent
+- `fail`: gap or mismatch found
+- `skip`: target code/doc missing or empty, check could not run
+
+### inconsistencies[]
+
+Cross-cutting issues found during the check that don't fit a single gap entry (e.g., type mismatches, naming violations, missing descriptions across multiple files).
+
+### summary
+
+Aggregate counts. `total_checks = passed + failed + skipped`.

package/skills/erp-kit-module-6-impl-review/references/model-doc-code-parity.md

@@ -0,0 +1,80 @@
+# Model Doc → Model Code Parity Check
+
+## Context
+
+Module: {{MODULE_NAME}}
+Model docs: {{MODEL_DOCS}}
+Model code: {{MODEL_CODE}}
+
+## Instructions
+
+1. Read ALL model docs at the paths above
+2. Read ALL model code files at the paths above
+3. For each model doc, extract fields, types, required/optional, relationships, state transitions, and descriptions
+4. For each model code file, extract `createEntityType()` fields, status enums, foreign keys, and `.description()` calls
+5. Run every parity check below against each model
+6. Return results as JSON per the Output Format section
+
+## Extraction: Model Docs
+
+From each model doc, extract:
+
+- **Fields**: name, type, required vs optional
+- **Relationships**: foreign key fields and their target entities
+- **State transitions**: status enum values from state diagrams
+- **Constraints**: uniqueness, validation rules
+- **Descriptions**: field-level descriptions
+
+## Extraction: Model Code
+
+From each model code file (`db/*.ts`), extract:
+
+- **Fields**: in `createEntityType()` or equivalent
+- **Status enums**: base statuses + additional statuses
+- **Foreign keys**: references to other entity types
+- **Descriptions**: `.description()` calls on fields
+
+## Parity Checks
+
+For each model:
+
+| Check ID           | Question                                                         |
+| ------------------ | ---------------------------------------------------------------- |
+| field_coverage     | Does code include all fields from model doc?                     |
+| type_accuracy      | Do field types in code match doc specification?                  |
+| required_fields    | Are required fields enforced (no default, not nullable)?         |
+| relationship_impl  | Are foreign key fields implemented for documented relationships? |
+| state_transitions  | Does status enum include all documented states?                  |
+| field_descriptions | Do `.description()` calls match doc field descriptions?          |
+
+### How to Check
+
+1. List all fields from model doc
+2. Find corresponding field in `createEntityType()` code
+3. Compare type, required/optional, description
+4. Check status enum values against state diagram
+5. Verify foreign key fields exist for all documented relationships
+
+## Common Gap Patterns
+
+- **Missing fields**: Doc specifies field but not in code
+- **Type mismatches**: Doc says string, code uses number
+- **Missing status values**: State diagram shows state not in enum
+- **Missing relationships**: Doc shows FK but not implemented
+- **Missing descriptions**: Doc has field description but no `.description()`
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "model-doc-code-parity",
+  "module": "{{MODULE_NAME}}",
+  "gaps": [...],
+  "inconsistencies": [...],
+  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
+}
+```
+
+See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.

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

@@ -1,6 +1,6 @@
 ---
 name: erp-kit-module-shared
-description: Shared references for erp-kit module skills. Not invoked directly — referenced by erp-kit-module-1 through erp-kit-module-5.
+description: Shared references for erp-kit module skills. Not invoked directly — referenced by erp-kit-module-1 through erp-kit-module-6.
 ---
 
 # erp-kit-module-shared

package/skills/erp-kit-module-shared/references/commands.md

@@ -177,7 +177,7 @@ const units = await db
 
 ## Implementation Considerations
 
-- **Error handling**: Use `ok()` / `err()` from `shared/internal` — do not throw
+- **Error handling**: Use `ok()` / `err()` from `shared` — do not throw
 - **Validation**: Check referenced entities exist before operating, return `err()` if not found
 
 ## Conventions

package/skills/erp-kit-module-shared/references/errors.md

@@ -10,25 +10,28 @@ Errors are **generated** from command/query documentation. Do not write `lib/err
 
 ## Naming convention (in docs)
 
-- Error code: `SCREAMING_SNAKE_CASE` (e.g., `DUPLICATE_SKU`)
+- Error code in docs: `SCREAMING_SNAKE_CASE` (e.g., `DUPLICATE_SKU`)
 - Generated class name: PascalCase + `Error` suffix (e.g., `DuplicateSkuError`)
+- Generated error code string: `{MODULE_PREFIX}_{DOC_CODE}` (e.g., `ITEM_MANAGEMENT_DUPLICATE_SKU`)
 - Generated via `createDomainError()` with contextual message
 
+The generator automatically prefixes error codes with the module name in `UPPER_SNAKE_CASE` to ensure uniqueness across modules. You only write the short code in docs; the prefix is added at generation time.
+
 ## Error category naming rules
 
 Use the **entity name** (not business-domain abbreviations) in error codes. Codes should be self-describing and consistent across modules.
 
-| Category          | Pattern                                 | Example                              |
-| ----------------- | --------------------------------------- | ------------------------------------ |
-| Not found         | `{ENTITY}_NOT_FOUND`                    | `UNIT_NOT_FOUND`, `ITEM_NOT_FOUND`   |
-| Duplicate         | `DUPLICATE_{FIELD}`                     | `DUPLICATE_SKU`, `DUPLICATE_BARCODE` |
-| Inactive / locked | `{FIELD}_LOCKED` or `{ENTITY}_INACTIVE` | `UOM_LOCKED`                         |
-| Invalid state     | `INVALID_{WHAT}`                        | `INVALID_STATE_TRANSITION`           |
-| No-op             | `NO_FIELDS_TO_UPDATE`                   | `NO_FIELDS_TO_UPDATE`                |
+| Category          | Pattern                                 | Doc example                | Generated code example                     |
+| ----------------- | --------------------------------------- | -------------------------- | ------------------------------------------ |
+| Not found         | `{ENTITY}_NOT_FOUND`                    | `UNIT_NOT_FOUND`           | `PRIMITIVES_UNIT_NOT_FOUND`                |
+| Duplicate         | `DUPLICATE_{FIELD}`                     | `DUPLICATE_SKU`            | `ITEM_MANAGEMENT_DUPLICATE_SKU`            |
+| Inactive / locked | `{FIELD}_LOCKED` or `{ENTITY}_INACTIVE` | `UOM_LOCKED`               | `PRODUCT_MANAGEMENT_UOM_LOCKED`            |
+| Invalid state     | `INVALID_{WHAT}`                        | `INVALID_STATE_TRANSITION` | `USER_MANAGEMENT_INVALID_STATE_TRANSITION` |
+| No-op             | `NO_FIELDS_TO_UPDATE`                   | `NO_FIELDS_TO_UPDATE`      | `PRODUCT_MANAGEMENT_NO_FIELDS_TO_UPDATE`   |
 
 ### Cross-module foreign key errors
 
-When a command validates an entity from another module (e.g., item-management checking that a Unit from primitives exists), use `{ENTITY}_NOT_FOUND` — the same pattern as same-module not-found errors. The error code reflects what's missing, not where it lives.
+When a command validates an entity from another module (e.g., item-management checking that a Unit from primitives exists), use `{ENTITY}_NOT_FOUND` — the same pattern as same-module not-found errors. Each module gets its own prefixed code (e.g., both `PRIMITIVES_UNIT_NOT_FOUND` and `ITEM_MANAGEMENT_UNIT_NOT_FOUND` can coexist).
 
 ### Idempotent error policy