Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate / Specs / 026-compliance

026-compliance: Compliance Volk (U:Cp)

ComplianceVolk (alias U:Cp, role "Compliance") is a deterministic volk that runs after U:Qa completes. It executes a 7-step pipeline that scans @traces decorators from source and test code, loads requirements from the Neo4j knowledge graph, generates a Requirements Traceability Matrix (RTM), syncs code nodes back to the KG, checks design-vs-code compliance, persists the RTM to disk and the KG, and produces a compliance report with coverage % and compliance % metrics.

At a glance

Item Value
Spec directory specs/026-compliance/
Status line in the spec Implemented
Requirement IDs defined 35
With a @traces citation in src/ 35 (100.0%)
With a @traces citation in tests/ 0 (0.0%)
Tracked files 6
RTM page 026-compliance

Reading this spec

The Compliance Volk (alias U:Cp, role Compliance) is a deterministic agent that runs after the QA Volk completes. It executes a 7-step pipeline that scans @traces decorators in source and test code, loads requirements from the Neo4j knowledge graph, generates a Requirements Traceability Matrix (RTM), syncs code nodes back to the graph and checks the design against the code. It exists so that traceability between requirements and implementation is verified automatically after every code generation cycle, design drift is detected before delivery, and the RTM is saved for audit without manual effort. The step is deterministic on purpose: no LLM inference enters governance decisions.

The scope is five user stories: automated RTM generation, design-versus-code compliance check, code sync to the knowledge graph and RTM persistence to the graph (priority 1), and a human-readable compliance report (priority 2). Requirement IDs use the REQ-026- prefix. The spec has a terminology table covering RTM, TraceInfo, RTMReport, ValidationReport, ComplianceResult and RTMSnapshot.

The design decisions are that ComplianceVolk extends BaseVolk, routes CXP packets on the subject compliance to an internal pipeline, and keeps all heavy logic in _pipeline.py as pure functions with no shared state. The graph connection is created lazily, and failure is non-fatal: the pipeline degrades gracefully. The response is a CXP packet to the human with coverage and compliance metrics. The RTM is saved under the project docs as JSON and markdown and as an RTMSnapshot node in Neo4j.

In the code, the work is in orchestrata_ultimate/agents/volks/compliance/_pipeline and orchestrata_ultimate/agents/volks/compliance/volk, with orchestrata_ultimate/core/traceability_utils behind them. The per-requirement view is on the RTM page.

The spec's status line reads Implemented. It tracks 6 files and defines 35 requirement IDs. The full text follows below.

Measured coverage is 35 of 35 requirements cited by at least one @traces in src/ (100.0%), spread over 3 modules; the module citing the most of them is orchestrata_ultimate/agents/volks/compliance/_pipeline (24 requirements). In tests/, 0 requirements are cited by a test-side @traces.

Coverage gaps: none on the citation measure, every requirement has at least one citing src/ symbol. Test-side citations are thinner than code-side ones (0 against 35).

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

ID Done Requirement Traced by
REQ-026-001 no ComplianceVolk.process() routes packets with subject compliance_check to _handle_compliance(); all other subjects return None 1
REQ-026-002 no _handle_compliance() calls _extract_packet_fields(), _run_pipeline(), and _build_response() in sequence 1
REQ-026-003 no _run_pipeline() executes all 7 pipeline steps in order: scan_traces → load_requirements → generate_rtm → sync_code → check_compliance → persist_rtm → _calculate_results 1
REQ-026-004 no WorkStatus transitions from PENDING to IN_PROGRESS on packet receipt and to RESOLVED on pipeline completion 3
REQ-026-005 no The volk summary string is updated with PASS/FAIL status plus coverage and compliance percentages on completion 2
REQ-026-006 no scan_traces(src_dir, tests_dir) scans @traces decorators in Python files under src_dir and tests_dir using orchestrata.core.traceability_utils.scan_traces 9
REQ-026-007 no Scanning is skipped for any directory that does not exist (os.path.isdir check); no exception is raised 1
REQ-026-008 no Trace records from both src_dir and tests_dir are merged into a single list 1
REQ-026-009 no If scan raises an exception, an empty list is returned and the error is logged at WARNING level 1
REQ-026-010 no load_requirements(kg_store, task_summary) fetches requirements from the KG via kg_store.get_requirements(slug) 2
REQ-026-011 no If kg_store is None, load_requirements returns an empty list immediately without attempting a KG call 1
REQ-026-012 no KG requirement dicts are converted to Requirement dataclass instances with id, description, story_id, and spec_id fields 2
REQ-026-013 no If the KG call raises an exception, an empty list is returned and the error is logged at WARNING level 1
REQ-026-014 no generate_rtm(traces, requirements, task_summary) calls orchestrata.core.traceability_utils.generate_rtm with trace list, requirement list, and project slug 3
REQ-026-015 no If generation raises an exception, None is returned and the error is logged at WARNING level 1
REQ-026-016 no On success, RTM validation metrics (verified, missing, orphan, coverage %) are logged at INFO level 1
REQ-026-017 no sync_code(kg_store, task_summary, trace_records) converts each TraceInfo to a dict via to_dict() if available, then calls kg_store.sync_code(slug, dicts) 1
REQ-026-018 no If kg_store is None, sync_code returns immediately without action 1
REQ-026-019 no If the KG call raises an exception, the error is logged at WARNING level and execution continues 1
REQ-026-020 no check_compliance(kg_store, task_summary) calls kg_store.check_compliance(slug) and returns the ComplianceResult 1
REQ-026-021 no If kg_store is None, check_compliance returns None immediately 1
REQ-026-022 no On success, compliance metrics (compliance %, missing count, extra count) are logged at INFO level 1
REQ-026-023 no If the KG call raises an exception, None is returned and the error is logged at WARNING level 1
REQ-026-024 no persist_rtm(kg_store, rtm_report, session_id, project_dir) calls _save_rtm_to_disk and _save_rtm_to_kg in sequence 1
REQ-026-025 no If rtm_report is None, persist_rtm returns an empty dict immediately 1
REQ-026-026 no _save_rtm_to_disk calls orchestrata.core.traceability_utils.save_rtm targeting <project_dir>/docs/ 3
REQ-026-027 no _save_rtm_to_kg creates an RTMSnapshot with unique ID ("rtm-" + uuid4().hex[:8]) and calls kg_store.close_session() 1
REQ-026-028 no If session_id is empty or kg_store is None, the KG snapshot write is skipped without error 1
REQ-026-029 no _calculate_results extracts coverage_pct from rtm_report.validation.coverage_percent and compliance_pct from compliance_result.compliance_pct; both default to 0.0 if unavailable 3
REQ-026-030 no passed is True when coverage_pct >= compliance_threshold (default 0.0) 1
REQ-026-031 no build_report_lines() produces a list of strings with RTM Coverage, Design Compliance, RTM Files, and Result sections 4
REQ-026-032 no The completed report string is appended to self.output_artifacts 1
REQ-026-033 no _init_kg() imports and constructs KGDesignStore only on first call; subsequent calls are no-ops when kg_store is already set 1
REQ-026-034 no If KGDesignStore construction raises any exception, kg_store is set to None and the error is logged at WARNING level 1
REQ-026-035 no _task_slug(task_summary) converts task_summary to lowercase, replaces all non-word/non-hyphen characters with hyphens, strips leading/trailing hyphens, and truncates to 50 characters 1

Code that traces this spec

Module Symbols Requirements
orchestrata_ultimate/agents/volks/compliance/_pipeline 10 24
orchestrata_ultimate/agents/volks/compliance/volk 15 11
orchestrata_ultimate/core/traceability_utils 12 3

Checklists

checklists/constitutional.md

Compliance Volk Constitutional Checklist

Determinism and Governance Integrity
Safety and Non-Interference
Transparency and Auditability
Graceful Degradation

checklists/requirements.md

The requirement list above comes from this file; 0 of 35 checkbox items are ticked.

checklists/testing.md

Compliance Volk Testing Checklist

Volk Instantiation
CXP Packet Routing
Pipeline — Trace Scanning
Pipeline — Requirements Loading
Pipeline — RTM Generation
Pipeline — Code Sync
Pipeline — Compliance Check
Pipeline — RTM Persistence
Coverage and Compliance Extraction
Pass/Fail Threshold Logic
Report Building
Task Slug
Payload Construction

Other tracked files

Full spec text

Verbatim from specs/026-compliance/spec.md; headings are pushed down two levels.

SPEC-026: Compliance Volk (U:Cp)

Metadata

Overview

What

ComplianceVolk (alias U:Cp, role "Compliance") is a deterministic volk that runs after U:Qa completes. It executes a 7-step pipeline that scans @traces decorators from source and test code, loads requirements from the Neo4j knowledge graph, generates a Requirements Traceability Matrix (RTM), syncs code nodes back to the KG, checks design-vs-code compliance, persists the RTM to disk and the KG, and produces a compliance report with coverage % and compliance % metrics.

Why
How

Terminology

Term Definition
RTM Requirements Traceability Matrix — cross-reference of requirements to implementing code
TraceInfo Dataclass from capturing annotation data: spec, story, reqs, module, class_name, method, file_path, line_number
Requirement Dataclass from representing a single requirement with id, description, story_id, spec_id, priority, category
RTMReport Dataclass from containing entries list, ValidationReport, generated_at, and project slug
ValidationReport Dataclass tracking verified, missing, and orphan requirement IDs plus coverage_percent
ComplianceResult Dataclass from with missing_classes, extra_classes, and compliance_pct
RTMSnapshot Dataclass from persisted as a Neo4j node linked to the session
KGDesignStore Neo4j-backed design store from orchestrata.knowledge.kg_design; provides get_design_classes, sync_code_nodes, create_rtm_snapshot, get_requirements
Task slug URL-safe lowercase string derived from task_summary; used as project identifier in KG lookups
Design compliance Ratio of expected classes (from KG design nodes) that exist in code, expressed as a percentage
Coverage % Percentage of requirements that have at least one annotation pointing to them
Orphan trace A annotation referencing a requirement ID that does not exist in the loaded requirements
Deterministic volk A volk that produces the same output for the same inputs; makes no LLM calls

Package Layout

File Responsibilities
File Responsibility
volk.py ComplianceVolk class, CXP packet routing, pipeline orchestration, report building, module-level helpers
_pipeline.py Pure helper functions: scan_traces, load_requirements, generate_rtm, sync_code, check_compliance, persist_rtm, _calculate_results, and their private sub-functions
__init__.py Module docstring declaring the package

User Scenarios & Stories

US-001: Automated RTM Generation (P1)

As a CodeDirector pipeline I want the compliance step to generate an RTM automatically after U:Qa completes So that traceability coverage is verified without manual effort

Acceptance Criteria:

US-002: Design-vs-Code Compliance Check (P1)

As a governance system I want design classes specified in the KG to be verified against actual code So that design drift is detected before delivery

Acceptance Criteria:

US-003: Code Sync to Knowledge Graph (P1)

As the knowledge graph I want scanned trace records to be synced as code nodes after each compliance run So that the KG reflects the current state of the implementation

Acceptance Criteria:

US-004: RTM Persistence to KG (P1)

As an audit trail I want RTM snapshots persisted as Neo4j nodes linked to the session So that historical compliance metrics are queryable over time

Acceptance Criteria:

US-005: Human-Readable Compliance Report (P2)

As a developer I want a formatted compliance report in the CXP response artifact So that I can read coverage and compliance status at a glance

Acceptance Criteria:

Data Models

CXP Inbound Packet (ComplianceVolk.process)
Field Type Required Description
project_dir string yes Absolute path to project root; src/ and tests/ sub-dirs are derived from this
task_summary string yes Human-readable task description; converted to slug for KG lookups
session_id string no Current session ID; used to link RTMSnapshot to Neo4j session node
CXP Outbound Packet (ComplianceVolk.response)
Field Type Description
passed bool True if coverage_pct >= compliance_threshold (default 0.0)
coverage_pct float Percentage of requirements with at least one trace annotation
compliance_pct float Percentage of design classes present in code
rtm_files dict Mapping of file type ("json", "markdown") to absolute path
missing_classes list[str] Classes found in KG design nodes but absent in code
missing_requirements list[str] Requirement IDs with no trace annotation
project_dir string Echo of input project_dir
task_summary string Echo of input task_summary
TraceInfo (from orchestrata.core.traceability_utils)
Field Type Description
spec_id str Specification ID the trace points to
story_id str User story ID
requirement_ids list[str] Requirement IDs covered by this annotation
module_path str Python module path
class_name str Name of the annotated class or blank string
method_name str Name of the annotated method or blank string
file_path str Absolute path to the source file
line_number int Line number of the annotation
Requirement (from orchestrata.core.traceability_utils)
Field Type Description
uid str Requirement identifier matching REQ-NNN-NNN pattern
description str Human-readable requirement text
story_id str Parent user story ID
spec_id str Parent specification ID
priority str Requirement priority (default "NORMAL")
category str Requirement category tag
RTMReport (from orchestrata.core.traceability_utils)
Field Type Description
list[dict] RTM entry dicts with req_id, trace list, status
ValidationReport | None Aggregated coverage metrics
str ISO 8601 timestamp of generation
str Project slug
ValidationReport (from orchestrata.core.traceability_utils)
Field Type Description
verified_ids list[str] Requirement IDs with at least one trace
missing_ids list[str] Requirement IDs with no trace
orphan_ids list[str] Traced requirement IDs not in loaded requirements
duplicate_ids dict[str, list[str]] Requirement IDs traced more than once
coverage_percent float (property) Percentage of verified requirements
ComplianceResult (from orchestrata.knowledge.kg_design)
Field Type Description
list[str] Class names in KG design but absent in code
list[str] Class names in code not present in KG design
float Percentage of design classes present in code
RTMSnapshot (from orchestrata.knowledge.kg_design)
Field Type Description
uid str Unique snapshot ID ("rtm-" + 8 hex chars)
coverage_pct float RTM coverage percentage at snapshot time
verified_count int Number of verified requirements
total_count int Total requirements (verified + missing)
missing_count int Number of missing requirements
orphan_count int Number of orphan trace annotations

Functional Requirements

Pipeline Orchestration
Step 1 — Trace Scanning
Step 2 — Requirements Loading
Step 3 — RTM Generation
Step 4 — Code Sync
Step 5 — Compliance Check
Step 6 — RTM Persistence
Step 7 — Report Production
KG Lazy Initialisation
Task Slug

Error Conditions and Edge Cases

ID Condition Behaviour
ERR-001 KG unavailable at init kg_store is set to None; steps 2, 4, 5, 6 skip KG calls
ERR-002 src_dir or tests_dir directory absent Directory scan skipped; zero-item list merged
ERR-003 KG returns zero-item requirements RTM generated with all traces classified as orphans
ERR-004 RTM generation raises exception persist_step returns zero-item dict; coverage_pct = 0.0
ERR-005 Compliance check raises exception compliance_result is None; compliance_pct = 0.0
ERR-006 project_dir blank string Derived src_dir and tests_dir are relative paths; scans find nothing
ERR-007 session_id blank string KG RTM snapshot write skipped
ERR-008 compliance_threshold = 0.0 (default) passed = True regardless of coverage
ERR-009 RTM has no validation RTM Coverage section omitted from report
ERR-010 ComplianceResult is None Design Compliance section omitted from report
ERR-011 Trace scan raises exception Zero-item trace list returned; error logged at WARNING
ERR-012 KG requirements fetch raises exception Zero-item requirements list returned; error logged at WARNING
ERR-013 Code sync to KG raises exception Sync skipped; error logged at WARNING; pipeline continues

API Contracts

ComplianceVolk.process()
def process(self, packet: CXPPacket) -> CXPPacket | None:
    """
    Process a CXP compliance packet.
    
    Args:
        packet: CXPPacket with subject='compliance', payload containing
                project_dir (str), task_summary (str), session_id (str, optional)
    
    Returns:
        CXPPacket addressed to HUMAN with compliance results, or None if
        packet subject is not 'compliance'
    """
scan_traces()
def scan_traces(src_dir: str, tests_dir: str) -> list[TraceInfo]:
    """
    Scan for @traces decorators in source and test files.
    
    Args:
        src_dir: Absolute path to source directory
        tests_dir: Absolute path to tests directory
    
    Returns:
        List of TraceInfo dataclass instances
    """
load_requirements()
def load_requirements(kg_store: KGDesignStore | None) -> list[Requirement]:
    """
    Load requirements from Neo4j knowledge graph.
    
    Args:
        kg_store: KGDesignStore instance or None
    
    Returns:
        List of Requirement dataclass instances
    """
generate_rtm()
def generate_rtm(
    traces: list[TraceInfo],
    requirements: list[Requirement],
    project_slug: str
) -> RTMReport | None:
    """
    Generate Requirements Traceability Matrix.
    
    Args:
        traces: List of trace annotations from code
        requirements: List of requirements from KG
        project_slug: URL-safe project identifier
    
    Returns:
        RTMReport with traceability matrix, or None on failure
    """

Non-Functional Requirements

Performance
Reliability
Determinism

Technical Design

Architecture

ComplianceVolk extends BaseVolk with the following design:

Key Interfaces
ComplianceVolk Public API
class ComplianceVolk(BaseVolk):
    alias: str = "U:Cp"
    role: str = "Compliance"
    
    def __init__(self, compliance_threshold: float = 0.0):
        """Initialize ComplianceVolk with optional compliance threshold."""
        
    def process(self, packet: CXPPacket) -> CXPPacket | None:
        """Route compliance packets through the 7-step pipeline."""
        
    @property
    def summary(self) -> str:
        """Return compliance status summary."""
Pipeline Helper Functions (_pipeline.py)
def scan_traces(src_dir: str, tests_dir: str) -> list[TraceInfo]:
    """Scan @traces decorators in source and test files."""
    
def load_requirements(kg_store: KGDesignStore | None) -> list[Requirement]:
    """Load requirements from Neo4j knowledge graph."""
    
def generate_rtm(traces: list[TraceInfo], 
                 requirements: list[Requirement], 
                 project_slug: str) -> RTMReport | None:
    """Generate Requirements Traceability Matrix."""
    
def sync_code(traces: list[TraceInfo], 
              kg_store: KGDesignStore | None) -> None:
    """Sync trace records as code nodes to KG."""
    
def check_compliance(project_slug: str, 
                     kg_store: KGDesignStore | None) -> ComplianceResult | None:
    """Check design-vs-code compliance via KG."""
    
def persist_rtm(rtm_report: RTMReport | None, 
                session_id: str, 
                kg_store: KGDesignStore | None) -> dict[str, str]:
    """Persist RTM to disk and KG."""
    
def _calculate_results(validation_report: ValidationReport | None, 
                       compliance_result: ComplianceResult | None) -> dict[str, float]:
    """Calculate coverage and compliance percentages."""
Integration Points
Integration Direction Interface
U:Qa (QA Volk) Upstream trigger U:Qa sends compliance packet on task completion
orchestrata.core.traceability_utils Import TraceInfo, Requirement, RTMReport, ValidationReport, build_rtm_report, find_py_files, extract_trace_info
orchestrata.knowledge.kg_design.KGDesignStore Import (lazy) get_design_classes, sync_code_nodes, create_rtm_snapshot, get_requirements
Neo4j (via KGDesignStore) Write RTMSnapshot node, code sync nodes
Disk (project docs/) Write rtm.json, rtm.md
CXP Integration

ComplianceVolk participates in the CXP protocol as follows:

  1. Inbound: Receives CXPPacket with subject="compliance", containing project_dir, task_summary, and optional session_id
  2. Processing: Routes to internal 7-step pipeline
  3. Outbound: Sends CXPPacket to recipient="HUMAN" with compliance_report in artifacts, passed/coverage_pct/compliance_pct in payload

The response packet is addressed to HUMAN, not back to U:Qa, because compliance results are a human-visible deliverable. U:Ox may intercept the packet for audit purposes.

Examples

Example 1: Basic Compliance Check

Input CXP Packet:

{
  "recipient": "U:Cp",
  "subject": "compliance",
  "payload": {
    "project_dir": "/home/user/project",
    "task_summary": "Implement user authentication",
    "session_id": "session-abc123"
  }
}

Output Response:

{
  "recipient": "HUMAN",
  "subject": "compliance",
  "payload": {
    "passed": true,
    "coverage_pct": 85.5,
    "compliance_pct": 92.3,
    "rtm_files": {
      "json": "/home/user/project/docs/rtm.json",
      "markdown": "/home/user/project/docs/rtm.md"
    },
    "missing_classes": ["UserManager"],
    "missing_requirements": ["REQ-026-003", "REQ-026-007"]
  }
}
Example 2: Graceful Degradation (KG Unavailable)

Scenario: Neo4j is down

Result: Pipeline completes with degraded metrics:

Example 3: Zero-File Project

Input: project_dir with no Python files

Output:

Security

Authentication & Authorization
Input Validation
Audit Logging
Data Privacy

Governance

Compliance Monitoring
Quality Gates
Operational Controls
Change Management

Success Criteria

Pipeline Execution
RTM Generation
Design Compliance
KG Integration
Report Production
Determinism
Error Handling

Testing

Test Infrastructure
Key Test Scenarios
  1. Volk instantiation: alias, role, default threshold, initial status, zero-item artifacts
  2. CXP routing: compliance subject returns packet; unknown subject returns None
  3. Pipeline with zero-item project_dir: completes without crash, returns 0.0 coverage
  4. to_task_slug: special characters, truncation, lowercase
  5. build_report / build_rtm_markdown: None inputs, missing attributes
  6. _calculate_results: with and without RTM, with and without compliance result
  7. persist_rtm: correct field mapping from report dict
  8. Threshold logic: passed = True when coverage >= threshold

Definition of Done

Visual Architecture

Class Diagram

Diagram source shown as text: Mermaid could not parse it (Error: Parse error on line 15:).

classDiagram-direction LR
    class ArchitectAgent {
        $agent_type: ClassVar[str] = 'U:Ar'
        ---
        +__init__(model: str = 'claude-3-5-haiku', agent_name: str = '')
        +async analyze_impact(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async design_solution(requirements: dict[str, Any]): dict[str, Any]
        +async review_architecture(architecture: dict[str, Any]): dict[str, Any]
    }
    class BaseAgent <<pydantic>> {
        -model: str = Field(default='claude-3-5-haiku', description='Model identifier for the agent', min_length=1, strict=True)
        -agent_id: str = Field(default='', description='Unique agent identifier', strict=True)
        -agent_name: str = Field(default='', description='Human-readable agent name', strict=True)
        $agent_type: ClassVar[str] = 'U:Base'
        $_instance_counters: ClassVar[dict[str, int]] = {}
        ---
        {@classmethod} +validate_model(v: str): str
        +__init__(**data: Any): None
        #_generate_unique_id(): str
        +model_post_init(__context: Any): None
        +async receive_message(message: Any, sender: str | None = None): Any
    }
    class CodeDirectorAgent {
        $agent_type: ClassVar[str] = 'U:Cd'
        ---
        +__init__(model: str = 'claude-3-5-sonnet', agent_name: str = '')
        +async execute_edit(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async review_code(code: str, requirements: dict[str, Any]): dict[str, Any]
        +async implement_feature(spec: dict[str, Any]): dict[str, Any]
    }
    class QualityAssuranceAgent {
        $agent_type: ClassVar[str] = 'U:Qa'
        ---
        +__init__(model: str = 'claude-3-5-sonnet', agent_name: str = '')
        +async review_edit(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async run_tests(test_suite: str): dict[str, Any]
        +async audit_security(code: str): dict[str, Any]
    }
    class UserExperienceAgent {
        $agent_type: ClassVar[str] = 'U:Ux'
        ---
        +__init__(model: str = 'claude-3-5-haiku', agent_name: str = '')
        +async review_ux(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async design_ui(requirements: dict[str, Any]): dict[str, Any]
        +async evaluate_accessibility(ui: dict[str, Any]): dict[str, Any]
    }
    BaseAgent <|-- ArchitectAgent
    BaseModel <|-- BaseAgent
    BaseAgent <|-- CodeDirectorAgent
    BaseAgent <|-- QualityAssuranceAgent
    BaseAgent <|-- UserExperienceAgent

Dependencies

Dependency Version Purpose
orchestrata-core workspace TraceInfo, Requirement, RTMReport, ValidationReport, build_rtm_report
orchestrata-agents workspace BaseVolk, CXPPacket, CXP_PROTOCOL_VERSION
orchestrata-knowledge workspace KGDesignStore, ComplianceResult, RTMSnapshot
Python >=3.14 Free-threaded runtime

Observability

Logging Requirements
  1. Component Logging
    • Log all major operations with appropriate log levels
    • Include correlation IDs for request tracing
    • Log performance metrics for critical operations
    • Log errors with full context for debugging
Metrics Requirements
  1. Performance Metrics
    • Operation duration histograms
    • Request/error rate counters
    • Resource utilization gauges
    • Business metrics relevant to domain
Tracing Requirements
  1. Distributed Tracing
    • Trace propagation across component boundaries
    • Span attributes for domain-specific context
    • Trace sampling based on operational needs
Alerting Requirements
  1. Critical Alerts
    • Error rate spikes
    • Performance degradation
    • Resource exhaustion
    • Business metric anomalies
Dashboard Requirements
  1. Operational Dashboard
    • Real-time system health
    • Performance trends
    • Error analysis
    • Resource monitoring

Revision History

Version Date Author Changes
1.0.0 2026-04-04 Mohamed Initial spec — documents implemented package