Work Order Management — CODITECT Impact Analysis

Classification: Internal — Architecture Decision Support Date: 2026-02-13

Integration Architecture

The Work Order (WO) system maps to CODITECT as a control plane subsystem — it does not process application data but governs the lifecycle of change control records that gate all mutations to validated systems.

Placement: The WO engine sits between the Agent Orchestrator and the Compliance Engine. Every agent-initiated change (code generation, configuration modification, document update) must be wrapped in a WO before execution against regulated targets.

Agent Orchestrator → WO Engine → Compliance Engine → State Store
                         ↑                ↓
                    Approval Gates    Audit Trail

Control Plane integration points:

Task Classifier maps incoming agent tasks to WO types (automation, external, manual) and determines regulatory classification.
Checkpoint Manager maps directly to WO approval gates — System Owner/QA approvals become mandatory checkpoints in the agent execution loop.
Pattern Selector uses WO dependency graphs to choose between chaining (sequential WOs) and orchestrator-workers (parallel independent WOs).

Data Plane integration points:

Agent Workers create and transition linked WOs as they execute subtasks.
IDE Shell surfaces WO status, approval requirements, and dependency state to developers.
Job Plans map to agent execution plans — tools, experience requirements, and credentials flow from the WO resource graph into agent capability matching.

Multi-Tenancy & Isolation

Strategy: Row-level security (RLS) + tenant_id foreign key.

Every WO table includes a tenant_id column with PostgreSQL RLS policies ensuring tenants never see cross-tenant data. This aligns with CODITECT's existing PostgreSQL state store strategy.

ALTER TABLE work_orders ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON work_orders
  USING (tenant_id = current_setting('app.tenant_id')::UUID);

Isolation levels:

WO data: Row-level (tenant_id). Shared schema, tenant-specific data.
Resource graph: Tenant-scoped (each tenant has own assets, tools, persons, experience ratings).
Approval chains: Tenant-scoped. Each tenant defines own System Owner and QA roles.
Job plan templates: Tenant-specific with optional shared library (platform-managed baseline templates).
Audit trail: Tenant-isolated, append-only. Cross-tenant audit queries prohibited at database level.

Risk: PM/Calibration automation schedules must be tenant-scoped. A shared scheduler could leak schedule metadata across tenants if not properly isolated. Mitigation: per-tenant scheduler partitions with independent cron configurations.

Compliance Surface

FDA 21 CFR Part 11

Requirement	WO System Mapping	Implementation
§11.10(a) Validation	WO lifecycle gates IQ/OQ/PQ delivery	Job Plan includes validation protocol references
§11.10(b) Record integrity	Append-only audit trail, no UPDATE/DELETE	Database triggers + RLS prevent modification
§11.10(c) Record retention	Immutable `wo_audit_trail` table	Archival policy configurable per tenant
§11.10(d) System access	WO role-based assignment (Assigner/Assignee)	RBAC with tenant-scoped role definitions
§11.10(e) Audit trail	Every status change, field change, approval logged	`wo_audit_trail` with actor, timestamp, reason
§11.50 Signature manifestations	`wo_approvals` with `signature_hash`, `signed_at`	Cryptographic hash of approver + timestamp + WO state
§11.70 Signature linking	Signature bound to WO version	`wo_approvals.wo_version` links to `work_orders.version`

Auditability hooks: Every WO state mutation emits an event to the Event Bus, enabling real-time compliance monitoring dashboards. The Compliance Engine subscribes to these events and can halt execution if policy violations are detected.

E-signature support: The approval workflow requires electronic signatures that include: signer identity (authenticated), timestamp (server-authoritative), meaning of signature (role: system_owner, qa), and linkage to the signed record (WO id + version hash).

HIPAA

WOs that reference PHI-containing systems (EHR integrations) must include:

Minimum necessary access principle applied to Job Plan credentials.
BAA references in external/vendor WOs.
Encryption status validation for data paths in WO detail fields.

SOC 2

WO lifecycle provides Change Management evidence (CC8.1).
Approval chains provide Segregation of Duties evidence.
Audit trail provides Monitoring evidence (CC7.2).
Schedule actuals provide Availability capacity planning data.

Observability

Signal	Source	Integration
Traces	WO state transitions, approval workflows, dependency resolution	OTEL spans: `wo.transition`, `wo.approval`, `wo.dependency.check`
Metrics	WO throughput, cycle time, approval latency, blocked duration	Prometheus: `wo_transitions_total`, `wo_cycle_time_seconds`, `wo_blocked_duration_seconds`
Logs	Audit trail entries, validation failures, escalations	Structured JSON logs to ELK/Loki with `wo_id`, `tenant_id`, `actor_id` correlation
Alerts	Approval SLA breach, dependency deadlock, compliance violation	Grafana alerting: `wo_approval_sla_breach`, `wo_dependency_cycle_detected`

Key dashboard panels:

WO funnel: draft → pending → assigned → in_progress → completed → closed (with drop-off rates)
Master WO progress: % linked WOs completed, critical path highlighting
Resource utilization: persons, tools, experience capacity vs. demand
Compliance health: first-pass approval rate, audit finding frequency

Multi-Agent Orchestration Fit

The WO system maps cleanly to CODITECT's five workflow patterns:

Pattern	WO Mapping	Example
Prompt Chaining	Sequential linked WOs with dependencies	WO1 (remove from prod) → WO2 (build workstation) → WO3 (vendor install)
Routing	WO source classification → handler selection	Automation WOs → PM agent, External → Vendor agent, Manual → Assignment agent
Parallelization	Independent linked WOs executed concurrently	User account setup ∥ documentation updates (no dependency)
Orchestrator-Workers	Master WO orchestrates linked WO agents	Master WO agent dispatches workers per linked WO
Evaluator-Optimizer	Compliance validation loop on WO completion	Generate → Validate against 21 CFR Part 11 → Fix → Revalidate

Checkpoint mapping:

Architecture decisions → WO creation approval (should we do this change?)
Compliance gates → WO approval gates (System Owner + QA sign-off)
Security findings → Credential/access review in Job Plan
Blockers → WO blocked status with dependency resolution

Circuit breaker mapping: If a linked WO agent fails repeatedly (e.g., vendor availability issues), the circuit breaker opens, the WO transitions to blocked, and the Master WO agent is notified to reassess the execution plan.

Advantages

Regulatory compliance is structural, not bolted on. The WO system enforces audit trails and approval gates at the data model level — agents cannot bypass compliance because it's embedded in every state transition.
Resource graph enables intelligent agent capability matching. The pre-entered experience ratings and tool availability data give CODITECT's orchestrator concrete information for assigning agent workers to WO tasks — matching required skills to available capacity.
Master/Linked WO hierarchy maps perfectly to orchestrator-workers pattern. No impedance mismatch between the domain model and the execution model.
Schedule actuals create a learning loop. Historical duration data from completed WOs feeds into future scheduling estimates, enabling progressively more accurate timeline predictions.
Multi-source origination aligns with CODITECT's event-driven architecture. Automation, external, and manual sources are naturally modeled as distinct event producers.

Gaps & Risks

Gap/Risk	Severity	Mitigation
No conflict resolution for concurrent WO edits	High	Implement optimistic locking (version column + conditional UPDATE). Already in schema but not enforced at application layer.
Dependency deadlock detection	High	WO dependency graph can form cycles if manually created. Need DAG validation on dependency creation.
Credential management in Job Plans	Critical	Storing account credentials in `job_plans.credentials` JSONB is a security risk. Must integrate with vault (HashiCorp Vault / GCP Secret Manager).
PM schedule scaling	Medium	Large tenants with thousands of instruments will generate high WO volume from automation. Need batch creation and bulk lifecycle management APIs.
Vendor WO coordination	Medium	External vendor actions are inherently async and unpredictable. Need timeout policies and escalation paths for stalled vendor WOs.
Partial Master WO completion	Medium	What happens when some linked WOs complete but one is blocked indefinitely? Need partial completion policies and business rules.
Experience rating staleness	Low	Certifications expire. Need automated expiration checks before WO assignment.

Integration Patterns

Adapter: WO ↔ Agent Orchestrator

// src/adapters/wo-orchestrator.adapter.ts

export interface WOOrchestratorAdapter {
  /** Maps an agent task to a WO creation request */
  taskToWorkOrder(task: AgentTask): CreateWORequest;
  
  /** Maps WO dependency graph to agent execution plan */
  dependencyGraphToExecutionPlan(masterWoId: string): ExecutionPlan;
  
  /** Maps WO approval requirements to agent checkpoints */
  approvalToCheckpoint(approval: WOApproval): AgentCheckpoint;
  
  /** Maps WO resource requirements to agent capability query */
  jobPlanToCapabilityQuery(jobPlan: JobPlan): CapabilityQuery;
  
  /** Receives agent completion signal, transitions WO status */
  onAgentComplete(woId: string, result: AgentResult): Promise<WorkOrder>;
  
  /** Receives agent failure signal, transitions WO to blocked */
  onAgentFailure(woId: string, error: AgentError): Promise<WorkOrder>;
}

Adapter: WO ↔ Compliance Engine

// src/adapters/wo-compliance.adapter.ts

export interface WOComplianceAdapter {
  /** Validates WO state transition against regulatory rules */
  validateTransition(wo: WorkOrder, newStatus: WOStatus): ComplianceResult;
  
  /** Generates audit event for compliance monitoring */
  emitAuditEvent(entry: AuditEntry): Promise<void>;
  
  /** Checks if all required approvals are collected with valid signatures */
  validateApprovals(woId: string): Promise<ApprovalValidationResult>;
  
  /** Generates compliance evidence package for WO closure */
  generateEvidencePackage(masterWoId: string): Promise<EvidencePackage>;
}

Event Schema

// src/events/wo.events.ts

export type WOEvent = 
  | { type: 'wo.created'; payload: { woId: string; masterWoId: string | null; source: WOSource; regulatory: boolean } }
  | { type: 'wo.status_changed'; payload: { woId: string; from: WOStatus; to: WOStatus; actorId: string; reason: string } }
  | { type: 'wo.approved'; payload: { woId: string; approverId: string; role: string; signatureHash: string } }
  | { type: 'wo.blocked'; payload: { woId: string; reason: string; blockedBy: string | null } }
  | { type: 'wo.completed'; payload: { woId: string; actualHours: number; evidenceIds: string[] } }
  | { type: 'wo.master_progress'; payload: { masterWoId: string; completedCount: number; totalCount: number; criticalPath: string[] } };

Integration Architecture​

Multi-Tenancy & Isolation​

Compliance Surface​

FDA 21 CFR Part 11​

HIPAA​

SOC 2​

Observability​

Multi-Agent Orchestration Fit​

Advantages​

Gaps & Risks​

Integration Patterns​

Adapter: WO ↔ Agent Orchestrator​

Adapter: WO ↔ Compliance Engine​

Event Schema​