@tailor-platform/erp-kit 0.4.0 → 0.5.0

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

@@ -0,0 +1,73 @@
+# 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.
+
+## Canonical Verbs
+
+| Verb               | Meaning                                             | Example                  |
+| ------------------ | --------------------------------------------------- | ------------------------ |
+| `create`           | Insert new entity                                   | `createItem`             |
+| `update`           | Modify existing entity fields                       | `updateItem`             |
+| `delete`           | Permanently remove entity (hard delete)             | `deleteItem`             |
+| `activate`         | Enable entity (inactive → active)                   | `activateUnit`           |
+| `deactivate`       | Soft-disable entity (active → inactive, reversible) | `deactivateUnit`         |
+| `reactivate`       | Re-enable after deactivation                        | `reactivateItem`         |
+| `assign...To...`   | Create a relationship between entities              | `assignRoleToUser`       |
+| `remove...From...` | Remove a relationship between entities              | `removeItemFromTaxonomy` |
+| `revoke...From...` | Remove permission/right (RBAC/security domain only) | `revokeRoleFromUser`     |
+| `set`              | Configure a singular value or reference             | `setBaseCurrency`        |
+| `move`             | Change position or parent in a hierarchy            | `moveTaxonomyNode`       |
+| `log`              | Append-only audit/event record                      | `logAuditEvent`          |
+
+## Choosing the Right Verb
+
+- **`delete` vs `deactivate`**: Use `delete` only for permanent removal. Use `deactivate` for soft-disable where the record is preserved.
+- **`remove...From...` vs `revoke...From...`**: Use `revoke` only in security/RBAC contexts (permissions, roles). Use `remove` for all other relationship unlinking.
+- **`assign...To...`**: Always use `assign` to create relationships, never `add...To...`.
+- **`activate` vs `reactivate`**: Use `reactivate` when the command specifically re-enables a previously deactivated entity and the distinction matters for business logic. Otherwise use `activate`.
+
+## Banned Verbs
+
+Do not use these — use the canonical alternative instead:
+
+| Banned                  | Use instead               |
+| ----------------------- | ------------------------- |
+| `archive` / `unarchive` | `deactivate` / `activate` |
+| `disable` / `enable`    | `deactivate` / `activate` |
+| `add...To...`           | `assign...To...`          |
+| `unlink`                | `remove...From...`        |
+
+## Domain-Specific Verbs
+
+If a feature requires a verb not in this table and the domain experts use it naturally (e.g., `approve`, `reject`, `cancel`, `close`, `submit`), it can be used. Document the rationale in the command doc.
+
+## Feature Operation → Command Name
+
+| Feature Operation    | Expected Command Doc | Notes                          |
+| -------------------- | -------------------- | ------------------------------ |
+| "Create X" / "Add X" | `createX`            | Never `addX`                   |
+| "Update X"           | `updateX`            |                                |
+| "Delete X"           | `deleteX`            | Hard delete only               |
+| "Deactivate X"       | `deactivateX`        | Soft-disable (reversible)      |
+| "Activate X"         | `activateX`          | Enable entity                  |
+| "Reactivate X"       | `reactivateX`        | Re-enable after deactivation   |
+| "Set default X"      | `setDefaultX`        | Singular value/reference       |
+| "Assign X to Y"      | `assignXToY`         | Never `addXToY`                |
+| "Remove X from Y"    | `removeXFromY`       | Generic relationship unlinking |
+| "Revoke X from Y"    | `revokeXFromY`       | RBAC/security domain only      |
+| "Move X"             | `moveX`              | Hierarchy position change      |
+| "Log X"              | `logX`               | Append-only audit/event        |

package/skills/erp-kit-module-3-update-plan/references/query-extraction.md

@@ -0,0 +1,59 @@
+# Query Extraction
+
+## Context
+
+Module: {{MODULE_NAME}}
+Feature docs: {{FEATURE_DOCS}}
+
+## Instructions
+
+Read ALL feature docs and extract read-only query definitions.
+
+1. Read ALL feature docs at the paths above
+2. For each feature, identify read operations needed by external consumers
+3. For each read operation, extract:
+   - Query name (following naming convention)
+   - Input parameters
+   - Output shape
+   - Business logic (filtering, aggregation, conversion)
+
+## Query Identification
+
+Queries are read-only operations for external consumers. Look for:
+
+- **Lookups**: "Get X by Y", "Find X where Z"
+- **Conversions**: "Convert X to Y", "Calculate X"
+- **Aggregations**: "Total X", "Count X by Y"
+- **Listings**: "List all X", "List X by status"
+
+See [CQRS read rule](../../erp-kit-module-shared/references/commands.md#command-side-reads-cqrs-separation) for when to use queries vs command-side reads.
+
+## Naming Convention
+
+| Operation           | Query Name               |
+| ------------------- | ------------------------ |
+| Get single entity   | `get{Entity}`            |
+| List by status      | `list{Status}{Entities}` |
+| List all            | `list{Entities}`         |
+| Search with filters | `search{Entities}`       |
+| Calculate/convert   | `calculate{Result}`      |
+| Aggregate           | `get{Aggregate}`         |
+
+## Output Format
+
+Return your extraction as a structured markdown report:
+
+### Queries
+
+For each query:
+
+#### <queryName>
+
+- **Source features:** list of feature files
+- **Inputs:**
+
+| Param | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+
+- **Output:** type (single/list/aggregate) and shape description
+- **Business logic:** description of filtering, aggregation, or transformation

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

@@ -57,92 +57,33 @@ 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. **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
+## Step 4: Severity Validation
 
-Render the aggregated results as markdown:
+Subagents tend to over-classify. Before rendering the report, re-evaluate every non-pass finding:
 
-### Feature Parity Review Report
-
-**Module:** <MODULE_NAME>
-
----
-
-### 1. Feature → Command Coverage
-
-| Feature | Scenarios | Required Commands | Documented Commands | Gap |
-| ------- | --------- | ----------------- | ------------------- | --- |
-
-(Populated from agent 1 gaps where check is `command_existence`)
-
----
-
-### 2. Feature → Query Coverage
-
-| Feature | Read Operations | Required Queries | Documented Queries | Gap |
-| ------- | --------------- | ---------------- | ------------------ | --- |
-
-(Populated from agent 2 gaps where check is `query_existence`)
-
----
-
-### 3. Feature → Model Coverage
-
-| Feature | Required Models | Documented Models | Gap |
-| ------- | --------------- | ----------------- | --- |
+- **"Is this a real gap or a design choice?"** — If the feature intentionally omits a command/query/model (e.g., handled by another module, deferred to a later phase, or covered by a generic mechanism), drop it from the report
+- **"Does the feature doc explicitly require this?"** — Only flag gaps for capabilities the feature doc actually specifies. Do not invent requirements the feature does not mention
+- **"Does this block implementation?"** → `critical`
+- **"Will this cause rework during implementation?"** → `major`
+- All no → `nit`, regardless of subagent label
 
-(Populated from agent 3 gaps where check is `model_existence`)
+## Step 5: Determine Verdict
 
----
-
-### 4. Test Case → Business Rule Mapping
-
-| Feature | Test Case | Covered by Command | Status |
-| ------- | --------- | ------------------ | ------ |
-
-(Populated from agent 1 gaps where check is `business_rule_coverage`)
-
----
-
-### 5. Missing Documentation
-
-#### Missing Command Docs
-
-| Feature | Expected Command | Purpose |
-| ------- | ---------------- | ------- |
+- **APPROVED**: zero `critical` and zero `major` findings (nits only, or all pass)
+- **NEEDS CHANGES**: one or more `critical` or `major` findings
 
-#### Missing Query Docs
+## Step 6: Render Report
 
-| Feature | Expected Query | Purpose |
-| ------- | -------------- | ------- |
+Render the aggregated results as markdown (after severity validation):
 
-#### Missing Model Docs
-
-| Feature | Expected Model | Purpose |
-| ------- | -------------- | ------- |
-
-(Populated from all agents' gaps where status is `fail`)
-
----
-
-### 6. Inconsistencies
-
-| Type | Location | Issue |
-| ---- | -------- | ----- |
+### Feature Parity Review Report
 
-(Populated from all agents' `inconsistencies[]`)
+**Module:** <MODULE_NAME>
 
 ---
 
-### 7. Summary
+### 1. Summary
 
 | Aspect                      | Status | Details           |
 | --------------------------- | ------ | ----------------- |
@@ -151,7 +92,7 @@ Render the aggregated results as markdown:
 | Feature → Model Coverage    |        | X/Y checks passed |
 | Command → Model Consistency |        | X/Y checks passed |
 
-### 8. Recommendations
+### 2. Recommendations
 
 Numbered list of actionable fixes, grouped by severity:
 
@@ -159,7 +100,7 @@ Numbered list of actionable fixes, grouped by severity:
 2. `major` — missing business rules, incomplete error scenarios (should fix)
 3. `nit` — minor naming inconsistencies, optional improvements (informational only)
 
-### 9. Verdict
+### 3. Verdict
 
 **Verdict: APPROVED / NEEDS CHANGES**
 

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

@@ -105,6 +105,7 @@ pnpm generate   # Regenerate types if models changed
 pnpm lint       # Check code style
 pnpm typecheck  # Verify TypeScript types
 pnpm test       # Run all tests
+pnpm run module:doc:sync-check # Verify docs compliance
 ```
 
 ## References

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

@@ -23,32 +23,33 @@ Define shared context for all agents:
 - `COMMAND_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/commands/*.md`
 - `MODEL_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/db/*.ts`
 - `COMMAND_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/command/*.ts` (exclude `*.test.ts` and `*.generated.ts`)
-- `TEST_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/command/*.test.ts`
+- `COMMAND_TEST_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/command/*.test.ts`
+- `QUERY_DOCS`: glob `<MODULES_ROOT>/<MODULE_NAME>/docs/queries/*.md`
+- `QUERY_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/query/*.ts` (exclude `*.test.ts` and `*.generated.ts`)
+- `QUERY_TEST_CODE`: glob `<MODULES_ROOT>/<MODULE_NAME>/query/*.test.ts`
 - `ERROR_DEFS`: `<MODULES_ROOT>/<MODULE_NAME>/lib/errors.generated.ts`
 
-Verify at least `MODEL_DOCS` or `COMMAND_DOCS` is non-empty. If no docs exist, stop with: "No docs found for module <MODULE_NAME>."
+Verify at least `MODEL_DOCS`, `COMMAND_DOCS`, or `QUERY_DOCS` is non-empty. If no docs exist, stop with: "No docs found for module <MODULE_NAME>."
 
 ## Step 2: Dispatch Agents (parallelize if possible)
 
-Launch 4 Agent tool calls in parallel — one per parity check.
-Each agent receives: MODULE_NAME, relevant doc/code file paths.
-Each agent returns: structured JSON per [references/impl-parity-report-format.md](references/impl-parity-report-format.md).
+Launch 3 Agent tool calls in parallel — one per domain (model, command, query).
+Each agent receives: MODULE_NAME, all relevant doc/code/test file paths for its domain.
+Each agent runs all parity perspectives (doc→code, error, doc→test) internally and returns: structured JSON per [references/impl-parity-report-format.md](references/impl-parity-report-format.md).
 If a doc or code directory is empty, the agent reports "no files found" and skips.
-Otherwise, query each sequentially.
 
-| Agent | Prompt Template                                                                        | Inputs                                            |
-| ----- | -------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| 1     | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)             | MODEL_DOCS, MODEL_CODE                            |
-| 2     | [references/command-doc-code-parity.md](references/command-doc-code-parity.md)         | COMMAND_DOCS, COMMAND_CODE                        |
-| 3     | [references/error-implementation-parity.md](references/error-implementation-parity.md) | COMMAND_DOCS, ERROR_DEFS, COMMAND_CODE, TEST_CODE |
-| 4     | [references/command-doc-test-parity.md](references/command-doc-test-parity.md)         | COMMAND_DOCS, TEST_CODE                           |
+| Agent | Domain  | Prompt Templates                                                                                                                                                                                                                                                                   | Inputs                                                              |
+| ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| 1     | Model   | [references/model-doc-code-parity.md](references/model-doc-code-parity.md)                                                                                                                                                                                                         | MODEL_DOCS, MODEL_CODE                                              |
+| 2     | Command | [references/command-doc-code-parity.md](references/command-doc-code-parity.md), [references/command-error-implementation-parity.md](references/command-error-implementation-parity.md), [references/command-doc-test-parity.md](references/command-doc-test-parity.md)               | COMMAND_DOCS, COMMAND_CODE, COMMAND_TEST_CODE, ERROR_DEFS           |
+| 3     | Query   | [references/query-doc-code-parity.md](references/query-doc-code-parity.md), [references/query-error-implementation-parity.md](references/query-error-implementation-parity.md), [references/query-doc-test-parity.md](references/query-doc-test-parity.md)                         | QUERY_DOCS, QUERY_CODE, QUERY_TEST_CODE, ERROR_DEFS                |
 
 For each agent:
 
-1. Read the prompt template file
+1. Read ALL prompt template files listed for that agent
 2. Replace `{{MODULE_NAME}}` with the resolved module name
-3. Replace `{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{TEST_CODE}}`, `{{ERROR_DEFS}}` with the actual file paths
-4. Dispatch the agent with the filled prompt
+3. Replace `{{MODEL_DOCS}}`, `{{COMMAND_DOCS}}`, `{{QUERY_DOCS}}`, `{{MODEL_CODE}}`, `{{COMMAND_CODE}}`, `{{QUERY_CODE}}`, `{{COMMAND_TEST_CODE}}`, `{{QUERY_TEST_CODE}}`, `{{ERROR_DEFS}}` with the actual file paths
+4. Combine the templates into a single prompt and dispatch the agent
 
 ## Step 3: Aggregate Results
 
@@ -59,124 +60,45 @@ 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. **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
+## Step 4: Severity Validation
 
-Render the aggregated results as markdown:
+Subagents tend to over-classify. Before rendering the report, re-evaluate every non-pass finding:
 
-### Implementation Parity Review Report
-
-**Module:** <MODULE_NAME>
-
----
-
-### 1. Model Doc → Model Code Coverage
-
-| Model Doc | Fields Documented | Fields Implemented | Gap |
-| --------- | ----------------- | ------------------ | --- |
-
-(Populated from agent 1 gaps where check is `field_coverage`)
-
----
-
-### 2. Model State Transitions
-
-| Model | Documented States | Implemented States | Gap |
-| ----- | ----------------- | ------------------ | --- |
-
-(Populated from agent 1 gaps where check is `state_transitions`)
-
----
-
-### 3. Command Doc → Command Code Coverage
-
-| Command Doc | Business Rules | Implemented | Gap |
-| ----------- | -------------- | ----------- | --- |
-
-(Populated from agent 2 gaps where check is `business_rule_impl`)
-
----
-
-### 4. Error Scenario Implementation
-
-| Command Doc | Error Code | Generated in errors.generated.ts | Returned in command | Test assertion |
-| ----------- | ---------- | -------------------------------- | ------------------- | -------------- |
-
-(Populated from agent 3 gaps)
+- **"Is this actually documented as a requirement?"** — If the doc does not explicitly specify the field, state, or behavior, drop it from the report. Do not invent requirements the documentation does not mention
+- **"Is this a framework convention, not a doc gap?"** — If the finding is about generated shells, boilerplate, or patterns that the framework handles automatically, drop it
+- **"Does this break the doc-code contract?"** → `critical` (missing implementation of documented feature, missing model fields/states)
+- **"Will this cause rework or missed behavior?"** → `major` (incomplete business rule implementation, missing test for documented scenario)
+- All no → `nit`, regardless of subagent label (minor naming difference, optional JSDoc, cosmetic issue)
 
----
-
-### 5. Process Flow → Test Coverage
-
-| Command Doc | Process Flow Branches | Test Cases | Gap |
-| ----------- | --------------------- | ---------- | --- |
-
-(Populated from agent 4 gaps where check is `process_flow_coverage`)
-
----
-
-### 6. Implementation Pattern Compliance
-
-| Command | Generated Shell | Input Interface Exported | JSDoc Present |
-| ------- | --------------- | ------------------------ | ------------- |
-
-(Populated from agent 2 gaps where check is `generated_shell_pattern`, `input_interface_export`, `jsdoc_present`)
-
----
-
-### 7. Missing Implementation
+## Step 5: Determine Verdict
 
-#### Missing in Model Code
+- **APPROVED**: zero `critical` and zero `major` findings (nits only, or all pass)
+- **NEEDS CHANGES**: one or more `critical` or `major` findings
 
-| Model Doc | Missing Item | Type | Doc Reference |
-| --------- | ------------ | ---- | ------------- |
+## Step 6: Render Report
 
-#### Missing in Command Code
+Render the aggregated results as markdown (after severity validation):
 
-| Command Doc | Missing Item | Type | Doc Reference |
-| ----------- | ------------ | ---- | ------------- |
-
-#### Missing Error Classes
-
-| Command Doc | Error Code | Expected Class |
-| ----------- | ---------- | -------------- |
-
-#### Missing Tests
-
-| Command Doc | Missing Test Case | Doc Reference |
-| ----------- | ----------------- | ------------- |
-
-(Populated from all agents' gaps where status is `fail`)
-
----
-
-### 8. Inconsistencies
-
-| Type | Location | Issue |
-| ---- | -------- | ----- |
+### Implementation Parity Review Report
 
-(Populated from all agents' `inconsistencies[]`)
+**Module:** <MODULE_NAME>
 
 ---
 
-### 9. Summary
+### 1. Summary
 
-| Aspect                        | Status | Details           |
-| ----------------------------- | ------ | ----------------- |
-| Model Doc → Code Coverage     |        | X/Y checks passed |
-| Command Doc → Code Coverage   |        | X/Y checks passed |
-| Error Scenario Implementation |        | X/Y checks passed |
-| Test Coverage                 |        | X/Y checks passed |
+| Aspect                              | Status | Details           |
+| ----------------------------------- | ------ | ----------------- |
+| Model Doc → Code Coverage           |        | X/Y checks passed |
+| Command Doc → Code Coverage         |        | X/Y checks passed |
+| Command Error Implementation        |        | X/Y checks passed |
+| Command Test Coverage               |        | X/Y checks passed |
+| Query Doc → Code Coverage           |        | X/Y checks passed |
+| Query Error Implementation          |        | X/Y checks passed |
+| Query Test Coverage                 |        | X/Y checks passed |
 
-### 10. Recommendations
+### 2. Recommendations
 
 Numbered list of actionable fixes, grouped by severity:
 
@@ -184,7 +106,7 @@ Numbered list of actionable fixes, grouped by severity:
 2. `major` — missing business rules, incomplete test coverage (should fix)
 3. `nit` — minor naming differences, optional JSDoc, cosmetic issues (informational only)
 
-### 11. Verdict
+### 3. Verdict
 
 **Verdict: APPROVED / NEEDS CHANGES**
 

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

@@ -4,7 +4,7 @@
 
 Module: {{MODULE_NAME}}
 Command docs: {{COMMAND_DOCS}}
-Test code: {{TEST_CODE}}
+Test code: {{COMMAND_TEST_CODE}}
 
 ## Instructions
 

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

@@ -1,4 +1,4 @@
-# Error Implementation Parity Check
+# Command Error Implementation Parity Check
 
 ## Context
 
@@ -6,7 +6,7 @@ Module: {{MODULE_NAME}}
 Command docs: {{COMMAND_DOCS}}
 Error definitions: {{ERROR_DEFS}}
 Command code: {{COMMAND_CODE}}
-Test code: {{TEST_CODE}}
+Test code: {{COMMAND_TEST_CODE}}
 
 ## Instructions
 
@@ -84,7 +84,7 @@ Return a JSON object:
 
 ```json
 {
-  "check_type": "error-implementation-parity",
+  "check_type": "command-error-implementation-parity",
   "module": "{{MODULE_NAME}}",
   "gaps": [...],
   "inconsistencies": [...],

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

@@ -6,7 +6,7 @@ All implementation parity check agents return results in this JSON structure.
 
 ```json
 {
-  "check_type": "<one of: model-doc-code-parity, command-doc-code-parity, error-implementation-parity, command-doc-test-parity>",
+  "check_type": "<one of: model-doc-code-parity, command-doc-code-parity, command-error-implementation-parity, command-doc-test-parity, query-doc-code-parity, query-error-implementation-parity, query-doc-test-parity>",
   "module": "<module-name>",
   "gaps": [
     {

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

@@ -0,0 +1,110 @@
+# Query Doc → Query Code Parity Check
+
+## Context
+
+Module: {{MODULE_NAME}}
+Query docs: {{QUERY_DOCS}}
+Query code: {{QUERY_CODE}}
+
+## Instructions
+
+1. Read ALL query docs at the paths above
+2. Read ALL query code files at the paths above
+3. For each query doc, extract business rules, process flow branches, input/output types
+4. For each query code file, extract validation logic, branching paths, input interface, return type
+5. Run every parity check below against each query
+6. Return results as JSON per the Output Format section
+
+## Extraction: Query Docs
+
+From each query doc, extract:
+
+- **Business rules**: lookup/filter behavior, nullability, permission requirements, scope handling
+- **Process flow**: branches from mermaid flowchart (decision nodes and their paths)
+- **Input fields**: documented input parameters
+- **Output type**: documented return structure (nullable single entity, paginated list, etc.)
+- **External dependencies**: other queries or APIs called
+
+## Extraction: Query Code
+
+From each query code file (`query/*.ts`, excluding `*.test.ts` and `*.generated.ts`), extract:
+
+- **Validation logic**: permission checks, scope checks, input validation guards
+- **Branching paths**: if/else, early returns, scope filtering
+- **Input interface**: exported `interface ...Input` fields
+- **Return type**: `ok(...)` / `err(...)` structure
+- **Generated shell**: existence of corresponding `.generated.ts` file
+- **Pagination**: use of `PaginationInput`, `buildPaginatedResult`, limit+1 pattern
+
+## Implementation Pattern Reference
+
+Queries follow a `run` + generated shell pattern similar to commands:
+
+- **Signature**: `async function run(db: ReadonlyDB<DB>, input: InputType, ctx?: QueryContext)`
+- **ReadonlyDB**: queries use `ReadonlyDB<DB>` (not `DB`), enforcing read-only access
+- **QueryContext**: optional, contains `actorId`, `permissions`, `companyId` for authorization
+- **Generated shell**: `export const myQuery = defineQuery(run);` in `.generated.ts`
+- **Return format**: wrap in object with descriptive keys (`{ entity }`, `{ items, hasNextPage }`)
+- **Nullable results**: simple get queries return `null` when not found (not an error)
+
+### Query Categories
+
+1. **Simple Get**: single lookup by ID, return entity or null
+2. **Search/Filter**: dynamic filters, pagination, scope restriction
+3. **List**: join across tables, optional filters, pagination
+4. **Transform**: call other queries, apply business logic (e.g., currency conversion)
+
+## Parity Checks
+
+For each query:
+
+| 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 query export `run` with a `.generated.ts` shell?         |
+| input_interface_export  | Is the input interface exported?                              |
+| permission_check        | Are documented permission requirements enforced in code?      |
+| scope_authorization     | Is documented scope handling (company vs global) implemented? |
+| pagination_pattern      | If documented as paginated, does code use pagination helpers? |
+| null_handling           | Does code return null for not-found as documented?            |
+
+### How to Check
+
+1. List all business rules from query doc
+2. Find corresponding validation/guard in query 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 with descriptive keys
+7. Verify permission checks match documented requirements
+8. Verify scope filtering matches documented scope handling
+
+## 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 query
+- **Input mismatch**: Doc input fields not in interface
+- **Return format mismatch**: Code returns raw value instead of `{ entity }`
+- **Missing permission check**: Doc requires permission but code doesn't check
+- **Missing scope filter**: Doc describes scope restriction but code doesn't apply
+- **Pagination mismatch**: Doc describes paginated query but code lacks pagination
+
+## Output Format
+
+Return a JSON object:
+
+```json
+{
+  "check_type": "query-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.