@tailor-platform/erp-kit 0.5.1 → 0.7.0

package/src/modules/manufacturing/docs/models/ManufacturingCostSummary.md

@@ -0,0 +1,66 @@
+# ManufacturingCostSummary
+
+## Description
+
+ManufacturingCostSummary stores the planned-versus-actual cost view for one production order without taking ownership of journal posting. It owns the frozen release-time baseline, accumulated actual material or resource evidence, variance-line classification, review lifecycle, and downstream settlement-acknowledgment traceability that gates final administrative close.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> COLLECTING: releaseProductionOrder
+    COLLECTING --> COLLECTING: recordInventoryIssueOutcome
+    COLLECTING --> PENDING_VARIANCE_REVIEW: technicallyCompleteProductionOrder
+    PENDING_VARIANCE_REVIEW --> VARIANCE_REVIEWED: reviewManufacturingCostSummary
+    PENDING_VARIANCE_REVIEW --> COLLECTING: reopenProductionOrder
+    VARIANCE_REVIEWED --> COLLECTING: reopenProductionOrder
+    VARIANCE_REVIEWED --> SETTLED: recordManufacturingCostSettlementAcknowledgment
+```
+
+### Command Definitions
+
+- [releaseProductionOrder](../commands/ReleaseProductionOrder.md) - Create the frozen planned baseline when the order is released.
+- [recordInventoryIssueOutcome](../commands/RecordInventoryIssueOutcome.md) - Apply inventory-valued material issue outcomes to actual cost accumulation.
+- [technicallyCompleteProductionOrder](../commands/TechnicallyCompleteProductionOrder.md) - Move the summary into variance-review status when execution is frozen.
+- [reviewManufacturingCostSummary](../commands/ReviewManufacturingCostSummary.md) - Recalculate and approve the final variance breakdown.
+- [reopenProductionOrder](../commands/ReopenProductionOrder.md) - Return the summary to active collection when execution is resumed.
+- [recordManufacturingCostSettlementAcknowledgment](../commands/RecordManufacturingCostSettlementAcknowledgment.md) - Persist downstream settlement evidence and unlock order close.
+
+### Query Definitions
+
+- [getManufacturingCostSummary](../queries/GetManufacturingCostSummary.md) - Retrieve one production order cost summary with planned, actual, and variance data.
+- [listManufacturingCostSummariesByStatus](../queries/ListManufacturingCostSummariesByStatus.md) - List summaries waiting for review or settlement queues.
+
+### Models
+
+- ManufacturingCostSummary
+- ManufacturingCostLine
+- CostVarianceLine
+- ManufacturingCostSettlementRecord
+
+### Invariants
+
+- Every production order owns exactly one manufacturing cost summary.
+- The planned material, labor, machine, and overhead baseline is frozen at release and never recomputed from later master-data changes.
+- Actual material cost enters the summary only through the named inventory-owned outcome contract after inventory valuation is final.
+- `PENDING_VARIANCE_REVIEW` and `VARIANCE_REVIEWED` summaries belong only to production orders that have already reached `TECHNICALLY_COMPLETE`.
+- `VARIANCE_REVIEWED` requires an explicit reviewer action and a frozen variance breakdown.
+- `SETTLED` requires a valid downstream acknowledgment whose order, summary, and currency match the reviewed handoff.
+- `COLLECTING` is the only state that accepts new actual cost accumulation from execution evidence.
+- If execution is reopened after review, the summary must return to `COLLECTING` rather than accumulating against a settled baseline.
+- Variance classification must keep at least `MATERIAL_PRICE`, `MATERIAL_USAGE`, `LABOR_RATE`, `LABOR_EFFICIENCY`, `MACHINE_RATE`, `MACHINE_EFFICIENCY`, `SCRAP`, and `YIELD` distinct.
+
+### Relationships
+
+- **Belongs To ProductionOrder**: summary lifecycle is subordinate to one [ProductionOrder](./ProductionOrder.md).
+- **Consumes WorkOrder evidence**: actual labor, machine, quantity, and scrap signals originate from [WorkOrder](./WorkOrder.md) execution.
+- **Consumes InventoryIssueOutcomeEvent**: actual material cost arrives from the named inventory-owned issue valuation contract.
+- **Consumes settlement acknowledgment**: the reviewed handoff is settled through the named `ManufacturingCostSettlementAcknowledgment` contract from downstream accounting or financial close.
+- **References WorkCenter and BOM snapshots**: planned baseline uses released [WorkCenter](./WorkCenter.md) rates and [BillOfMaterial](./BillOfMaterial.md) component assumptions.
+- **References coa-management**: reviewed variance lines carry downstream account references from coa-management for settlement handoff.

package/src/modules/manufacturing/docs/models/ProductionOrder.md

@@ -0,0 +1,76 @@
+# ProductionOrder
+
+## Description
+
+ProductionOrder is the manufacturing control document that turns one planning decision into executable shop-floor work. It owns the produced item, planned quantity and dates, company or site scope, released snapshots of BOM and routing content, execution rollup from work orders, and the lifecycle that governs release, completion, technical completion, reopening, and administrative close.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> DRAFT: createProductionOrder
+    DRAFT --> DRAFT: updateProductionOrder
+    DRAFT --> RELEASED: releaseProductionOrder
+    DRAFT --> CANCELLED: cancelProductionOrder
+    RELEASED --> DRAFT: unreleaseProductionOrder
+    RELEASED --> RELEASED: rescheduleProductionOrder
+    RELEASED --> IN_PROGRESS: startWorkOrder
+    RELEASED --> CANCELLED: cancelProductionOrder
+    IN_PROGRESS --> IN_PROGRESS: reportWorkOrderProgress
+    IN_PROGRESS --> COMPLETED: completeProductionOrder
+    COMPLETED --> TECHNICALLY_COMPLETE: technicallyCompleteProductionOrder
+    TECHNICALLY_COMPLETE --> IN_PROGRESS: reopenProductionOrder
+    TECHNICALLY_COMPLETE --> CLOSED: closeProductionOrder
+```
+
+### Command Definitions
+
+- [createProductionOrder](../commands/CreateProductionOrder.md) - Create a draft production request with planning data.
+- [updateProductionOrder](../commands/UpdateProductionOrder.md) - Revise mutable draft planning fields before release.
+- [releaseProductionOrder](../commands/ReleaseProductionOrder.md) - Freeze BOM and routing, create work orders, and open execution.
+- [unreleaseProductionOrder](../commands/UnreleaseProductionOrder.md) - Return a released order to draft when no execution evidence exists.
+- [rescheduleProductionOrder](../commands/RescheduleProductionOrder.md) - Move planned dates on a released order before execution starts.
+- [cancelProductionOrder](../commands/CancelProductionOrder.md) - Abandon the order before meaningful execution makes cancellation invalid.
+- [completeProductionOrder](../commands/CompleteProductionOrder.md) - Mark physical production complete after final reporting and receipt handoff.
+- [technicallyCompleteProductionOrder](../commands/TechnicallyCompleteProductionOrder.md) - Freeze execution and move the linked cost summary into review.
+- [reopenProductionOrder](../commands/ReopenProductionOrder.md) - Re-enable controlled execution after a technically complete or reviewed state.
+- [closeProductionOrder](../commands/CloseProductionOrder.md) - Perform final administrative close once the linked cost summary is settled.
+
+### Query Definitions
+
+- [getProductionOrder](../queries/GetProductionOrder.md) - Retrieve one production order with snapshots, progress, and closeout status.
+- [listProductionOrdersByStatus](../queries/ListProductionOrdersByStatus.md) - List production orders for planning, execution, or closeout queues.
+
+### Models
+
+- ProductionOrder
+- ProductionOrderMaterialRequirement
+- ProductionOrderBomSnapshot
+- ProductionOrderRoutingSnapshot
+- ProductionOrderCostBaseline
+
+### Invariants
+
+- Every production order belongs to exactly one company and one execution site.
+- The ordered item must be an ACTIVE manufacturable item and planned quantity must remain greater than zero.
+- BOM and routing references selected at release must belong to the same company and site scope as the production order.
+- Orders in `RELEASED`, `IN_PROGRESS`, `COMPLETED`, `TECHNICALLY_COMPLETE`, or `CLOSED` always carry immutable BOM and routing snapshots.
+- `CANCELLED` and `CLOSED` orders reject further shop-floor execution updates.
+- Entering `COMPLETED` requires the final output-reporting and receipt-handoff evidence required by policy.
+- Entering `TECHNICALLY_COMPLETE` requires that no additional execution, rescheduling, or material issue is still expected.
+- Entering `CLOSED` requires the linked [ManufacturingCostSummary](./ManufacturingCostSummary.md) to be in `SETTLED`.
+
+### Relationships
+
+- **References Item (cross-module)**: the produced item is an [Item](../../../item-management/docs/models/Item.md).
+- **Belongs To Company and Site**: execution scope is defined by [Company](../../../organization/docs/models/Company.md) and [Site](../../../organization/docs/models/Site.md).
+- **Snapshots BillOfMaterial**: release freezes one [BillOfMaterial](./BillOfMaterial.md) version and exploded component requirements.
+- **Snapshots Routing**: release freezes one [Routing](./Routing.md) revision and operation plan.
+- **Has Many WorkOrders**: released routing operations materialize into [WorkOrder](./WorkOrder.md) records.
+- **Owns One ManufacturingCostSummary**: cost collection and variance review are tracked in [ManufacturingCostSummary](./ManufacturingCostSummary.md).

package/src/modules/manufacturing/docs/models/Routing.md

@@ -0,0 +1,58 @@
+# Routing
+
+## Description
+
+Routing defines the ordered manufacturing process used to build one produced item or item family. It owns operation sequencing, standard setup and run assumptions, work-center assignment, operator instructions, and the revision that production orders later freeze into executable work orders.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createRouting
+    Draft --> Draft: updateRouting
+    Draft --> Active: activateRouting
+    Active --> Inactive: deactivateRouting
+```
+
+### Command Definitions
+
+- [createRouting](../commands/CreateRouting.md) - Create a draft routing for one manufactured item or scope.
+- [updateRouting](../commands/UpdateRouting.md) - Revise operation order, instructions, and work-center assignments while mutable.
+- [activateRouting](../commands/ActivateRouting.md) - Validate ordered operations and make the routing eligible for production-order release.
+- [deactivateRouting](../commands/DeactivateRouting.md) - Remove the routing from future selection without mutating released snapshots.
+
+### Query Definitions
+
+- [getRouting](../queries/GetRouting.md) - Retrieve one routing revision with ordered operations.
+- [listRoutingsByItem](../queries/ListRoutingsByItem.md) - List routing revisions available for one parent item and scope.
+
+### Models
+
+- Routing
+- RoutingOperation
+
+### Invariants
+
+- Every routing belongs to one company and targets one manufactured item or item family within an optional site scope.
+- The produced item must be ACTIVE and manufacturable when the routing is activated.
+- A draft or active routing contains at least one operation with a unique sequence number inside the routing.
+- Standard setup and run time values are always zero or greater.
+- Each operation references a work center that is valid for the same company and effective scope.
+- An active routing must not reference an inactive work center.
+- Active routing operations may only reference ACTIVE work centers.
+- Revisions for future orders may be created or activated without mutating any routing snapshot already frozen onto released production orders.
+- Deterministic sequencing is part of the routing definition in the initial scope, so operations execute in one ordered path rather than parallel branches.
+
+### Relationships
+
+- **References Item (cross-module)**: the produced parent item is an [Item](../../../item-management/docs/models/Item.md).
+- **Has Many RoutingOperations**: ordered step definitions live under the routing aggregate.
+- **References WorkCenter**: each operation is assigned to one [WorkCenter](./WorkCenter.md).
+- **Referenced By ProductionOrder**: [ProductionOrder](./ProductionOrder.md) snapshots one routing revision at release.
+- **Materializes Into WorkOrder**: released operation snapshots become [WorkOrder](./WorkOrder.md) records.

package/src/modules/manufacturing/docs/models/WorkCenter.md

@@ -0,0 +1,56 @@
+# WorkCenter
+
+## Description
+
+WorkCenter represents the machine, line, cell, or labor pool where routing operations are planned and executed. It owns scope, capacity assumptions, calendar reference, standard labor or machine rates, and the optional overhead-absorption rule that manufacturing snapshots onto released orders.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createWorkCenter
+    Draft --> Draft: updateWorkCenter
+    Draft --> Active: activateWorkCenter
+    Active --> Active: updateWorkCenter
+    Active --> Inactive: deactivateWorkCenter
+    Inactive --> Active: activateWorkCenter
+```
+
+### Command Definitions
+
+- [createWorkCenter](../commands/CreateWorkCenter.md) - Create a draft work center with scope, capacity, and rate definitions.
+- [updateWorkCenter](../commands/UpdateWorkCenter.md) - Revise mutable master data, capacity assumptions, and overhead policy.
+- [activateWorkCenter](../commands/ActivateWorkCenter.md) - Validate readiness and move the work center into executable use.
+- [deactivateWorkCenter](../commands/DeactivateWorkCenter.md) - Prevent future routing or execution use while preserving history.
+
+### Query Definitions
+
+- [getWorkCenter](../queries/GetWorkCenter.md) - Retrieve one work center with cost and capacity context.
+- [listWorkCentersBySite](../queries/ListWorkCentersBySite.md) - List work centers available at one site or scoped facility.
+
+### Models
+
+- WorkCenter
+
+### Invariants
+
+- Work-center code is unique inside its company and effective site scope.
+- Capacity assumptions are always positive and expressed in one consistent planning unit.
+- An active work center must have the calendar, status, and cost fields required by release and execution flows.
+- Labor and machine rate assumptions are always zero or greater.
+- `overheadAbsorptionMethod` may be unset, but when set it must be one of `PERCENT_OF_LABOR_COST`, `PERCENT_OF_MACHINE_COST`, or `FIXED_AMOUNT_PER_GOOD_UNIT`.
+- `overheadAbsorptionCurrency` is required whenever the overhead method is `FIXED_AMOUNT_PER_GOOD_UNIT`.
+- Changes to work-center rates or overhead rules never mutate cost baselines already snapshotted on released production orders.
+
+### Relationships
+
+- **Belongs To Company and Site**: execution scope is constrained by [Company](../../../organization/docs/models/Company.md) and [Site](../../../organization/docs/models/Site.md).
+- **Referenced By Routing**: [Routing](./Routing.md) operations assign work to one work center.
+- **Referenced By WorkOrder**: released operation snapshots preserve work-center context on [WorkOrder](./WorkOrder.md).
+- **Feeds ManufacturingCostSummary**: labor, machine, and overhead assumptions roll into [ManufacturingCostSummary](./ManufacturingCostSummary.md).

package/src/modules/manufacturing/docs/models/WorkOrder.md

@@ -0,0 +1,63 @@
+# WorkOrder
+
+## Description
+
+WorkOrder is the operation-level execution record created from a released production-order routing snapshot. It owns one executable step, its work-center context, planned and actual quantities, actual time, pause or exception history, and the execution lifecycle that drives progress rollup, inventory handoff, and cost accumulation.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING: releaseProductionOrder
+    PENDING --> IN_PROGRESS: startWorkOrder
+    IN_PROGRESS --> IN_PROGRESS: reportWorkOrderProgress
+    IN_PROGRESS --> PAUSED: pauseWorkOrder
+    PAUSED --> IN_PROGRESS: resumeWorkOrder
+    IN_PROGRESS --> COMPLETE: completeWorkOrder
+    PENDING --> CANCELLED: cancelProductionOrder
+```
+
+### Command Definitions
+
+- [startWorkOrder](../commands/StartWorkOrder.md) - Start execution on one released work order.
+- [pauseWorkOrder](../commands/PauseWorkOrder.md) - Pause an in-progress work order with an exception reason.
+- [resumeWorkOrder](../commands/ResumeWorkOrder.md) - Resume a paused work order without losing prior history.
+- [reportWorkOrderProgress](../commands/ReportWorkOrderProgress.md) - Record partial quantities, time, scrap, and execution notes.
+- [completeWorkOrder](../commands/CompleteWorkOrder.md) - Finish the operation and emit required completion handoffs.
+- [cancelProductionOrder](../commands/CancelProductionOrder.md) - Cascade cancellation to pending work orders when the parent order is cancelled before execution.
+
+### Query Definitions
+
+- [getWorkOrder](../queries/GetWorkOrder.md) - Retrieve one work order with execution evidence and handoff status.
+- [listWorkOrdersByProductionOrder](../queries/ListWorkOrdersByProductionOrder.md) - List work orders under one production order in sequence order.
+- [listWorkOrdersByWorkCenter](../queries/ListWorkOrdersByWorkCenter.md) - List work orders assigned to one work center across production orders for bottleneck review.
+
+### Models
+
+- WorkOrder
+- WorkOrderExecutionEvent
+
+### Invariants
+
+- Every work order belongs to exactly one production order and one released routing-operation snapshot.
+- Every work order is created from a single sequential routing operation within the parent production order.
+- `plannedQuantity`, `completedQuantity`, `scrapQuantity`, and captured time values are always zero or greater.
+- A work order may move to `IN_PROGRESS` only while its parent production order is in an execution-capable state.
+- A work order in `PAUSED` preserves prior execution evidence and can resume without resetting accumulated quantities or time.
+- Completing a later sequential work order before its required predecessor is done is invalid unless the routing snapshot explicitly allows it.
+- Receipt and scrap handoffs must carry the production-order and work-order references that preserve manufacturing traceability.
+- `COMPLETE` and `CANCELLED` work orders reject further execution reporting.
+
+### Relationships
+
+- **Belongs To ProductionOrder**: each work order is created under one [ProductionOrder](./ProductionOrder.md).
+- **References Routing and WorkCenter snapshots**: executable operation context comes from released [Routing](./Routing.md) and [WorkCenter](./WorkCenter.md) data.
+- **Emits ManufacturingReceiptHandoff**: completion reporting sends the named receipt contract to inventory.
+- **Emits ManufacturingScrapHandoff**: scrap reporting sends the named scrap contract to inventory.
+- **Feeds ManufacturingCostSummary**: actual time, quantity, and scrap roll up into [ManufacturingCostSummary](./ManufacturingCostSummary.md).

package/src/modules/manufacturing/docs/queries/DetectBillOfMaterialCircularReference.md

@@ -0,0 +1,39 @@
+# DetectBillOfMaterialCircularReference
+
+## Overview
+
+DetectBillOfMaterialCircularReference checks whether adding or activating a manufactured-child component would introduce a direct or indirect loop in the BOM graph.
+
+## Business Rules
+
+- Company scope and both item references are required.
+- The query traverses only manufactured-child BOM references.
+- The result returns whether a loop exists and the detected item path when one is found.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive company and item references] --> B[Traverse manufactured-child BOM graph]
+    B --> C{Loop found?}
+    C -->|Yes| D[Return loop path]
+    C -->|No| E[Return no circular reference]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_SCOPE_REQUIRED**: Company scope was not provided.
+- **ITEM_REFERENCE_REQUIRED**: Parent or child item reference is missing.
+
+## Test Cases
+
+- detects a direct BOM loop
+- detects an indirect BOM loop across multiple subassemblies
+- returns no loop when the graph is acyclic
+- scopes detection to the requested company
+- returns error when parent or child reference is missing
+- returns error when company scope is missing

package/src/modules/manufacturing/docs/queries/ExplodeBillOfMaterial.md

@@ -0,0 +1,56 @@
+# ExplodeBillOfMaterial
+
+## Overview
+
+ExplodeBillOfMaterial expands one BOM version into recursive component requirements for planners and engineers who need to inspect multi-level demand on a specific effectivity date.
+
+## Business Rules
+
+- BOM reference is required.
+- Effectivity date is required so the query can resolve the root BOM semantics and any lower-level active child BOM versions consistently.
+- The explosion must apply the released BOM `bomType` semantics: `MANUFACTURE` preserves make-item boundaries while still showing lower-level demand, `PHANTOM` flattens child lines into the nearest non-phantom parent path, and `KIT` expands to issue-only component demand without routing or work-order context for the kit parent.
+- Recursive expansion may only use child BOM versions that are active and effective on the requested date within the same company and applicable site scope.
+- The response returns an exploded tree or list with component item references, cumulative required quantities, unit-of-measure context, explosion depth, and the source BOM path used to derive each requirement.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive BOM reference and effectivity date] --> B[Load root BOM version]
+    B --> C{BOM found and effective on date?}
+    C -->|No| D[Return BOM_NOT_FOUND or BOM_NOT_EFFECTIVE_ON_DATE]
+    C -->|Yes| E[Walk component lines recursively]
+    E --> F{Manufactured child requires lower-level BOM?}
+    F -->|Yes| G[Resolve active child BOM for date and scope]
+    G --> H[Apply MANUFACTURE PHANTOM or KIT explosion semantics]
+    F -->|No| H
+    H --> I[Accumulate exploded component requirements]
+    I --> J[Return exploded structure]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BOM_REFERENCE_REQUIRED**: BOM reference was not provided.
+- **EFFECTIVITY_DATE_REQUIRED**: Effectivity date was not provided.
+- **BOM_NOT_FOUND**: Requested BOM version does not exist.
+- **BOM_NOT_EFFECTIVE_ON_DATE**: The requested BOM version is not valid on the specified effectivity date.
+- **CHILD_BOM_NOT_RESOLVED**: A manufactured child item required recursive expansion but no active effective child BOM could be resolved.
+- **BOM_CIRCULAR_REFERENCE_DETECTED**: The explosion encountered a direct or indirect circular BOM reference.
+
+## Test Cases
+
+- explodes a multi-level manufacture BOM into recursive component requirements
+- flattens phantom subassemblies into the nearest non-phantom parent path
+- expands a kit BOM into component issue requirements without work-order context for the kit parent
+- resolves lower-level child BOM versions using the requested effectivity date
+- returns cumulative quantities and source BOM path metadata for exploded components
+- returns error when the BOM reference is missing
+- returns error when the effectivity date is missing
+- returns error when the root BOM is not found
+- returns error when the root BOM is not effective on the requested date
+- returns error when a required lower-level child BOM cannot be resolved
+- returns error when the explosion detects a circular BOM reference

package/src/modules/manufacturing/docs/queries/GetBillOfMaterial.md

@@ -0,0 +1,37 @@
+# GetBillOfMaterial
+
+## Overview
+
+GetBillOfMaterial returns one BOM version with its component lines, effectivity window, scope, and status so planners and engineers can inspect the exact production recipe.
+
+## Business Rules
+
+- BOM reference is required.
+- The query returns draft, active, or inactive versions.
+- Component lines are returned in their maintained sequence order.
+- The response includes `bomType`, scope, effectivity, and default-selection flags.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive BOM reference] --> B[Load BOM and component lines]
+    B --> C{BOM found?}
+    C -->|No| D[Return BOM_NOT_FOUND]
+    C -->|Yes| E[Return BOM detail]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BOM_NOT_FOUND**: Requested BOM version does not exist.
+
+## Test Cases
+
+- returns a BOM with component lines when found
+- returns draft BOM versions when requested
+- returns inactive BOM versions when requested
+- returns error when the BOM does not exist

package/src/modules/manufacturing/docs/queries/GetManufacturingCostSummary.md

@@ -0,0 +1,39 @@
+# GetManufacturingCostSummary
+
+## Overview
+
+GetManufacturingCostSummary returns one production order's cost baseline, actual accumulation, variance breakdown, and settlement-review status for supervisors or finance reviewers.
+
+## Business Rules
+
+- Cost-summary or production-order reference is required.
+- The query returns collecting, pending-review, reviewed, or settled summaries.
+- The response includes planned versus actual totals and variance lines by category.
+- Reviewed and settled summaries include reviewer or acknowledgment traceability.
+- Each variance line retains its mapped downstream variance-account reference.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive summary or production-order reference] --> B[Load cost summary and variance lines]
+    B --> C{Summary found?}
+    C -->|No| D[Return COST_SUMMARY_NOT_FOUND]
+    C -->|Yes| E[Return cost summary detail]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_SUMMARY_NOT_FOUND**: Requested cost summary does not exist.
+
+## Test Cases
+
+- returns a collecting cost summary with planned and actual totals
+- returns a reviewed cost summary with variance lines
+- returns a settled cost summary with acknowledgment traceability
+- returns variance lines with downstream account references
+- returns error when the cost summary does not exist

package/src/modules/manufacturing/docs/queries/GetProductionOrder.md

@@ -0,0 +1,37 @@
+# GetProductionOrder
+
+## Overview
+
+GetProductionOrder returns one production order with planning fields, release snapshots, work-progress rollup, and closeout status so planners and supervisors can inspect a single order end to end.
+
+## Business Rules
+
+- Production-order reference is required.
+- The query returns any lifecycle status.
+- The response includes selected or snapshotted BOM and routing context, quantity rollups, and linked cost-summary status.
+- Child work-order summary data may be embedded for execution visibility.
+- The returned snapshot should preserve the exact BOM type, routing revision, and production-state context that were in force for the order.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive production-order reference] --> B[Load order, snapshots, and rollups]
+    B --> C{Order found?}
+    C -->|No| D[Return PRODUCTION_ORDER_NOT_FOUND]
+    C -->|Yes| E[Return production-order detail]
+```
+
+## External Dependencies
+
+- [GetManufacturingCostSummary](./GetManufacturingCostSummary.md) - Cost status may be embedded in the response.
+
+## Error Scenarios
+
+- **PRODUCTION_ORDER_NOT_FOUND**: Requested production order does not exist.
+
+## Test Cases
+
+- returns a production order with material requirements, work orders, and cost summary when found
+- returns a production order with no cost summary when none exists
+- returns error when the production order does not exist

package/src/modules/manufacturing/docs/queries/GetRouting.md

@@ -0,0 +1,39 @@
+# GetRouting
+
+## Overview
+
+GetRouting returns one routing revision with ordered operations, standard times, work-center assignments, and lifecycle status.
+
+## Business Rules
+
+- Routing reference is required.
+- Company scope is required when routing codes are only unique within a company.
+- The query returns draft, active, or inactive routings.
+- Operations are returned in sequence order with instruction and work-center context.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive routing reference and scope] --> B[Load routing and operations]
+    B --> C{Routing found?}
+    C -->|No| D[Return ROUTING_NOT_FOUND]
+    C -->|Yes| E[Return routing detail]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ROUTING_NOT_FOUND**: Requested routing does not exist.
+- **COMPANY_SCOPE_REQUIRED**: Company scope was not provided when needed to resolve the routing.
+
+## Test Cases
+
+- returns a routing with ordered operations when found
+- returns inactive routing revisions when requested
+- returns routing data for the requested company scope
+- returns error when the routing does not exist
+- returns error when company scope is not provided

package/src/modules/manufacturing/docs/queries/GetWorkCenter.md

@@ -0,0 +1,35 @@
+# GetWorkCenter
+
+## Overview
+
+GetWorkCenter returns one work center with scope, capacity, calendar context, rate assumptions, overhead policy, and lifecycle status.
+
+## Business Rules
+
+- Work-center reference is required.
+- The query returns draft, active, or inactive work centers.
+- Capacity, rate, and overhead fields are returned exactly as currently configured.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive work-center reference] --> B[Load work-center detail]
+    B --> C{Work center found?}
+    C -->|No| D[Return WORK_CENTER_NOT_FOUND]
+    C -->|Yes| E[Return work-center detail]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **WORK_CENTER_NOT_FOUND**: Requested work center does not exist.
+
+## Test Cases
+
+- returns a work center when found
+- returns inactive work centers when requested
+- returns error when the work center does not exist

package/src/modules/manufacturing/docs/queries/GetWorkOrder.md

@@ -0,0 +1,38 @@
+# GetWorkOrder
+
+## Overview
+
+GetWorkOrder returns one work order with operation context, status, quantity rollups, actual time, pause history, and handoff evidence.
+
+## Business Rules
+
+- Work-order reference is required.
+- The query returns any lifecycle status.
+- Execution-event history may be returned in chronological order.
+- The response includes parent production-order reference and work-center context.
+- The response should preserve the routed operation sequence, current status, and recorded handoff evidence for the work order.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive work-order reference] --> B[Load work order and execution events]
+    B --> C{Work order found?}
+    C -->|No| D[Return WORK_ORDER_NOT_FOUND]
+    C -->|Yes| E[Return work-order detail]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **WORK_ORDER_NOT_FOUND**: Requested work order does not exist.
+
+## Test Cases
+
+- returns a work order with execution history when found
+- returns paused work orders with prior pause data
+- returns a work order with handoff evidence and parent order context
+- returns error when the work order does not exist