Orchestrata Ultimate / Specs / 003-intent

003-intent: Intent Broker (U:Intents)

The Intent Broker (U:Intents) processes natural language intents from users, parses them into structured data, validates them against Prolog governance policies, routes them to appropriate Volks, manages intent lifecycle, history, templates, and multi-intent workflows.

At a glance

Item	Value
Spec directory	`specs/003-intent/`
Status line in the spec	Complete
Requirement IDs defined	396
With a `@traces` citation in `src/`	290 (73.2%)
With a `@traces` citation in `tests/`	15 (3.8%)
Tracked files	8
RTM page	003-intent

Reading this spec

The Intent Broker (U:Intents) is the bridge between human natural language and the structured tasks that agents work on. It takes a natural-language intent from a user, parses it into structured data, validates it against Prolog governance policies, routes it to the appropriate Volk, and then tracks the intent through its lifecycle.

The scope is a set of user stories covering intent parsing from natural language, structured intent extraction, validation via Prolog, routing to Volks (all four critical), lifecycle management (high), and history and replay, templates and patterns, multi-intent workflows and monitoring (medium). The requirements use the REQ-003- prefix.

The design decisions in the overview are NLP parsing that extracts an action verb and a target noun, Prolog validation for governance compliance, routing to a Volk based on the action and target, and session-based isolation of intents and history. Reusable templates and workflow orchestration cover complex multi-step operations.

In the code, the intent logic sits in the orchestrator package. The largest tracers are orchestrata_ultimate/orchestrator/intent_types, orchestrata_ultimate/orchestrator/intent_history, orchestrata_ultimate/orchestrator/intent_workflow, orchestrata_ultimate/orchestrator/intent_validator and orchestrata_ultimate/orchestrator/intent_template. The per-requirement view is on the RTM page.

The spec's status line reads Complete. It tracks 8 files and defines 396 requirement IDs. The full text follows below.

Measured coverage is 290 of 396 requirements cited by at least one @traces in src/ (73.2%), spread over 38 modules; the module citing the most of them is orchestrata_ultimate/orchestrator/intent_types (42 requirements). In tests/, 15 requirements are cited by a test-side @traces.

Coverage gaps: 106 requirements have no citing symbol. The largest untraced groups are REQ-003-US-009 (20), REQ-003-US-001 (19), REQ-003-US-004 (16). Untraced means no @traces names the ID; the behaviour may still exist in code that was never annotated. Test-side citations are thinner than code-side ones (15 against 290).

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-003-US-001-001`	yes	Parse simple action statements ("create a file named test.py")	none
`REQ-003-US-001-002`	yes	Parse compound statements ("read config.yaml and update database")	none
`REQ-003-US-001-003`	yes	Extract action verbs (read, write, delete, execute, query)	2
`REQ-003-US-001-004`	yes	Extract target nouns (file, code, database, api, system)	2
`REQ-003-US-001-005`	yes	Identify parameters (file names, values, options)	6
`REQ-003-US-001-006`	yes	Recognize constraints (permissions, limits, conditions)	3
`REQ-003-US-001-007`	yes	Handle ambiguous intents with clarification requests	3
`REQ-003-US-001-008`	yes	Support multi-language input (English primary)	1
`REQ-003-US-001-009`	yes	Parse incomplete sentences with context	3
`REQ-003-US-001-010`	yes	Handle typos and grammatical errors gracefully	1
`REQ-003-US-001-011`	yes	Create `IntentParser` class in `src/session/intent_parser.py`	2
`REQ-003-US-001-012`	yes	Implement NLP tokenization (use spaCy or nltk)	7
`REQ-003-US-001-013`	yes	Create action verb dictionary (READ, WRITE, DELETE, EXECUTE, QUERY)	3
`REQ-003-US-001-014`	yes	Create target noun dictionary (FILE, CODE, DATABASE, API, SYSTEM)	2
`REQ-003-US-001-015`	yes	Implement parameter extraction using named entity recognition	14
`REQ-003-US-001-016`	yes	Create constraint parser for conditional expressions	3
`REQ-003-US-001-017`	yes	Implement ambiguity detection algorithm	7
`REQ-003-US-001-018`	yes	Create clarification question generator	2
`REQ-003-US-001-019`	yes	Add multi-language support framework	1
`REQ-003-US-001-020`	yes	Implement context-aware parsing using session state	10
`REQ-003-US-001-021`	yes	Add spell-checking and auto-correction	1
`REQ-003-US-001-022`	yes	Create parser configuration file	none
`REQ-003-US-001-023`	yes	Implement parser caching for performance	3
`REQ-003-US-001-024`	yes	Add parser telemetry and metrics	2
`REQ-003-US-001-025`	yes	Create parser test fixtures	none
`REQ-003-US-001-026`	yes	Unit test: Parse "create file test.py" → Intent(action=WRITE, target=FILE)	none
`REQ-003-US-001-027`	yes	Unit test: Parse "read config.yaml" → Intent(action=READ, target=FILE)	none
`REQ-003-US-001-028`	yes	Unit test: Parse "delete database records" → Intent(action=DELETE, target=DATABASE)	none
`REQ-003-US-001-029`	yes	Unit test: Parse "execute deploy script" → Intent(action=EXECUTE, target=SYSTEM)	none
`REQ-003-US-001-030`	yes	Unit test: Parse "query API for users" → Intent(action=QUERY, target=API)	none
`REQ-003-US-001-031`	yes	Integration test: Parse with missing parameters triggers clarification	2
`REQ-003-US-001-032`	yes	Integration test: Parse ambiguous intent returns multiple candidates	6
`REQ-003-US-001-033`	yes	Performance test: Parse 1000 intents in <100ms average	none
`REQ-003-US-001-034`	yes	Edge case test: Handle empty input gracefully	2
`REQ-003-US-001-035`	yes	Edge case test: Handle very long input (>1000 chars)	1
`REQ-003-US-001-040`	yes	`IntentVocabulary` supports runtime-extensible keyword→category	5
`REQ-003-US-001-041`	yes	`IntentVocabulary.default()` seeds work_type/action/target/priority	4
`REQ-003-US-001-042`	yes	DCG-grammar parsing backend — `intent_grammar.pl`	4
`REQ-003-US-001-043`	yes	Cascade fallback — `NLIntentClassifier.classify` tries the Prolog	4
`REQ-003-US-001-044`	yes	Category→workflow mapping — `WorkflowMapper.workflow_for` maps a	4
`REQ-003-US-001-045`	yes	`IntentEvaluator.evaluate` computes a confidence score and flags	6
`REQ-003-US-001-046`	yes	NER-sourced `resource_path`/`assigned_volk` — the classifier	5
`REQ-003-US-001-047`	yes	`IntentVocabulary.to_dict`/`from_dict` round-trip for	3
`REQ-003-US-001-048`	yes	Grammar-tier classifications carry confidence ~0.9;	3
`REQ-003-US-001-049`	yes	`NLIntentClassifier.to_intent` bridges a `ClassifiedIntent` to a	2
`REQ-003-US-001-050`	yes	Stem-normalized lexicon matching — `intent_grammar.pl`	none
`REQ-003-US-001-051`	yes	Stem-collision gate — `lexicon_stem_collision/3`	none
`REQ-003-US-001-052`	yes	Decisive-over-generic work-type resolution — a work-type	none
`REQ-003-US-001-053`	yes	`IntentVocabulary.generic_verbs` declares the	none
`REQ-003-US-001-054`	yes	Expanded default vocabulary — every `WorkType` and every	none
`REQ-003-US-001-065`	yes	Majority-vote work-type resolution — when a sentence names	none
`REQ-003-US-001-055`	yes	Committed accuracy corpora — `tests/orchestrator/data/	none
`REQ-003-US-001-060`	yes	`IntentNormalizer.normalize(text, context)` rewrites a	4
`REQ-003-US-001-061`	yes	Normalization never blocks classification — any provider	2
`REQ-003-US-001-062`	yes	The sentence the grammar actually parsed is recorded on	2
`REQ-003-US-001-063`	yes	`NLIntentClassifier.classify_async`,	2
`REQ-003-US-001-064`	yes	Identical `(text, context)` returns the identical	1
`REQ-003-US-001-066`	yes	The normalizer prompt is chosen by measurement against	none
`REQ-003-US-001-067`	yes	A normalization must be GROUNDED — the rewrite shares	3
`REQ-003-US-001-068`	yes	Every verdict carries the evidence behind it — which	1
`REQ-003-US-001-070`	yes	A QUESTION must not auto-dispatch work, however	1
`REQ-003-US-001-069`	no	Confidence must be GRADED before it is calibrated.	none
`REQ-003-US-002-001`	yes	Intent data model defined with all required fields	3
`REQ-003-US-002-002`	yes	Intent serialization to JSON	5
`REQ-003-US-002-003`	yes	Intent deserialization from JSON	2
`REQ-003-US-002-004`	yes	Intent validation schema (Pydantic)	2
`REQ-003-US-002-005`	yes	Required fields enforced (id, action, target, requester)	2
`REQ-003-US-002-006`	yes	Optional fields supported (parameters, constraints, metadata)	none
`REQ-003-US-002-007`	yes	Intent versioning for schema evolution	5
`REQ-003-US-002-008`	yes	Intent immutability after creation	none
`REQ-003-US-002-009`	yes	Intent comparison and equality checks	none
`REQ-003-US-002-010`	yes	Intent hashing for deduplication	1
`REQ-003-US-002-011`	yes	Create `Intent` dataclass in `src/session/models.py`	1
`REQ-003-US-002-012`	yes	Define `IntentAction` enum (READ, WRITE, DELETE, EXECUTE, QUERY)	1
`REQ-003-US-002-013`	yes	Define `IntentTarget` enum (FILE, CODE, DATABASE, API, SYSTEM)	1
`REQ-003-US-002-014`	yes	Define `IntentStatus` enum (PENDING, VALIDATED, EXECUTING, COMPLETED, FAILED)	1
`REQ-003-US-002-015`	yes	Implement `to_json()` method	5
`REQ-003-US-002-016`	yes	Implement `from_json()` class method	2
`REQ-003-US-002-017`	yes	Create Pydantic schema `IntentSchema`	1
`REQ-003-US-002-018`	yes	Implement field validation rules	1
`REQ-003-US-002-019`	yes	Add schema versioning with `__version__` field	5
`REQ-003-US-002-020`	yes	Implement `__eq__()` and `__hash__()` methods	1
`REQ-003-US-002-021`	yes	Create intent builder pattern for complex intents	2
`REQ-003-US-002-022`	yes	Add intent factory methods for common patterns	1
`REQ-003-US-002-023`	yes	Implement intent copying with modifications	2
`REQ-003-US-002-024`	yes	Create intent diff function for comparison	1
`REQ-003-US-002-025`	yes	Add intent migration for schema changes	2
`REQ-003-US-002-026`	yes	Unit test: Create intent with required fields succeeds	1
`REQ-003-US-002-027`	yes	Unit test: Create intent without required fields raises validation error	1
`REQ-003-US-002-028`	yes	Unit test: Serialize intent to JSON and back preserves data	7
`REQ-003-US-002-029`	yes	Unit test: Invalid JSON raises deserialization error	2
`REQ-003-US-002-030`	yes	Unit test: Intent with invalid action raises validation error	1
`REQ-003-US-002-031`	yes	Unit test: Intent with invalid target raises validation error	1
`REQ-003-US-002-032`	yes	Unit test: Two identical intents are equal	none
`REQ-003-US-002-033`	yes	Unit test: Two different intents are not equal	none
`REQ-003-US-002-034`	yes	Unit test: Intent hash is consistent across runs	1
`REQ-003-US-002-035`	yes	Integration test: Intent versioning supports v1 and v2 schemas	2
`REQ-003-US-003-001`	yes	All intents validated against Prolog rules before routing	15
`REQ-003-US-003-002`	yes	Validation checks action permissions	4
`REQ-003-US-003-003`	yes	Validation checks target access rights	4
`REQ-003-US-003-004`	yes	Validation checks parameter constraints	1
`REQ-003-US-003-005`	yes	Validation enforces rate limits	2
`REQ-003-US-003-006`	yes	Validation checks requester identity	2
`REQ-003-US-003-007`	yes	Validation supports custom rules per target	2
`REQ-003-US-003-008`	yes	Failed validation returns detailed reason	4
`REQ-003-US-003-009`	yes	Validation results cached for performance	3
`REQ-003-US-003-010`	yes	Validation logging for audit trail	2
`REQ-003-US-003-011`	yes	Create `IntentValidator` class in `src/session/intent_validator.py`	1
`REQ-003-US-003-012`	yes	Implement Prolog query builder for intent validation	5
`REQ-003-US-003-013`	yes	Create Prolog predicate `validate_intent/4` in `prolog/intent.pl`	1
`REQ-003-US-003-014`	yes	Create Prolog predicate `can_perform_action/3`	1
`REQ-003-US-003-015`	yes	Create Prolog predicate `has_target_access/3`	1
`REQ-003-US-003-016`	yes	Create Prolog predicate `check_parameter_constraints/2`	1
`REQ-003-US-003-017`	yes	Create Prolog predicate `check_rate_limit/2`	2
`REQ-003-US-003-018`	yes	Create Prolog predicate `verify_requester/2`	1
`REQ-003-US-003-019`	yes	Implement validation result cache with TTL	2
`REQ-003-US-003-020`	yes	Add validation telemetry and metrics	1
`REQ-003-US-003-021`	yes	Create validation error types	3
`REQ-003-US-003-022`	yes	Implement validation logging to audit trail	2
`REQ-003-US-003-023`	yes	Add validation bypass for emergency operations (with approval)	1
`REQ-003-US-003-024`	yes	Create validation rule testing framework	none
`REQ-003-US-003-025`	yes	Implement validation policy hot-reload	6
`REQ-003-US-003-026`	yes	Unit test: Valid intent passes validation	1
`REQ-003-US-003-027`	yes	Unit test: Intent with unauthorized action fails validation	1
`REQ-003-US-003-028`	yes	Unit test: Intent with inaccessible target fails validation	1
`REQ-003-US-003-029`	yes	Unit test: Intent with invalid parameters fails validation	1
`REQ-003-US-003-030`	yes	Unit test: Intent exceeding rate limit fails validation	1
`REQ-003-US-003-031`	yes	Unit test: Intent from unknown requester fails validation	1
`REQ-003-US-003-032`	yes	Integration test: Validation queries Prolog successfully	1
`REQ-003-US-003-033`	yes	Integration test: Validation result cached and reused	none
`REQ-003-US-003-034`	yes	Integration test: Validation logging creates audit entry	1
`REQ-003-US-003-035`	yes	Performance test: Validate 1000 intents in <50ms average	1
`REQ-003-US-004-001`	yes	Intent routed to correct Volk based on action and target	10
`REQ-003-US-004-002`	yes	Routing rules defined in Prolog	1
`REQ-003-US-004-003`	yes	Multi-Volk routing supported for complex intents	2
`REQ-003-US-004-004`	yes	Load balancing across multiple instances of same Volk	none
`REQ-003-US-004-005`	yes	Routing failure triggers fallback logic	2
`REQ-003-US-004-006`	yes	Routing respects Volk availability	2
`REQ-003-US-004-007`	yes	Routing respects Volk capacity	none
`REQ-003-US-004-008`	yes	Routing logged for observability	1
`REQ-003-US-004-009`	yes	Routing metrics tracked (latency, success rate)	1
`REQ-003-US-004-010`	yes	Routing supports priority-based dispatch	5
`REQ-003-US-004-011`	yes	Create `IntentRouter` class in `src/session/intent_router.py`	2
`REQ-003-US-004-012`	yes	Implement routing decision logic	3
`REQ-003-US-004-013`	yes	Create Prolog predicate `route_intent/3` in `prolog/intent.pl`	1
`REQ-003-US-004-014`	yes	Create Prolog predicate `volk_can_handle/3`	none
`REQ-003-US-004-015`	yes	Create routing table configuration	none
`REQ-003-US-004-016`	yes	Implement multi-Volk routing for complex intents	1
`REQ-003-US-004-017`	yes	Add load balancing algorithm (round-robin, least-loaded)	none
`REQ-003-US-004-018`	yes	Implement fallback routing on failure	2
`REQ-003-US-004-019`	yes	Add Volk availability checking	2
`REQ-003-US-004-020`	yes	Add Volk capacity checking (queue size, CPU)	1
`REQ-003-US-004-021`	yes	Create routing telemetry and metrics	1
`REQ-003-US-004-022`	yes	Implement routing logging	2
`REQ-003-US-004-023`	yes	Add priority queue for high-priority intents	1
`REQ-003-US-004-024`	yes	Create routing rule testing framework	none
`REQ-003-US-004-025`	yes	Implement routing policy hot-reload	2
`REQ-003-US-004-026`	yes	Unit test: FILE/READ intent routed to VizInt	none
`REQ-003-US-004-027`	yes	Unit test: CODE/WRITE intent routed to VizInt	none
`REQ-003-US-004-028`	yes	Unit test: DATABASE/QUERY intent routed to Architect	none
`REQ-003-US-004-029`	yes	Unit test: SYSTEM/EXECUTE intent routed to Orchestrator	none
`REQ-003-US-004-030`	yes	Unit test: Complex intent routed to multiple Volks	none
`REQ-003-US-004-031`	yes	Integration test: Routing queries Prolog successfully	none
`REQ-003-US-004-032`	yes	Integration test: Load balancing distributes work evenly	none
`REQ-003-US-004-033`	yes	Integration test: Fallback routing activates on failure	none
`REQ-003-US-004-034`	yes	Integration test: Unavailable Volk not selected	none
`REQ-003-US-004-035`	yes	Performance test: Route 1000 intents in <20ms average	none
`REQ-003-US-004-100`	yes	`PipelineKernelClient` implements the gateway's `send_packet(CXPPacket)` kernel-client interface backed by the local `PipelineRunner`, so the gateway can dispatch intents without an out-of-process gRPC kernel	3
`REQ-003-US-004-101`	yes	`send_packet` runs the full agent pipeline only for packets addressed to `U:Cx` with subject `"intent"`, generating a thread ID when the packet has none, and returns `False` for any other packet (not handled)	1
`REQ-003-US-004-102`	yes	`_run_pipeline` and the workflow-control facade publish their lifecycle events as SPEC-001 `PipelineEvent`s — `event_type` drawn from the `PipelineEventType` taxonomy (`specs/001-kernel/pipeline-event-type-addendum.md`, REQ-006-031): `pipeline.intent` at run start, `pipeline.stage` per stage result, `pipeline.complete` on finish (success or failure, discriminated by `data.success` / `data.error`), and `pipeline.paused` / `pipeline.resumed` / `pipeline.cancelled` from pause/resume/cancel — serialized via the shared `PipelineEvent.to_payload()` and broadcast in-process on `pipeline.<thread_id>` through the gateway-injected `broadcast` callable. No bespoke event names; no parallel Redis stream. (Amended 2026-08-05 — pipeline-event convergence, `plans/pipeline-event-convergence-design.md`; supersedes the pre-convergence `pipeline.start`/`pipeline.error` vocabulary and the dead `pipeline:events` fallback.)	2
`REQ-003-US-005-001`	yes	Intent lifecycle states defined (PENDING, VALIDATED, EXECUTING, COMPLETED, FAILED)	2
`REQ-003-US-005-002`	yes	State transitions tracked with timestamps	3
`REQ-003-US-005-003`	yes	Invalid state transitions prevented	3
`REQ-003-US-005-004`	yes	State change events published	none
`REQ-003-US-005-005`	yes	Lifecycle history stored for audit	2
`REQ-003-US-005-006`	yes	Failed intents marked with error details	1
`REQ-003-US-005-007`	yes	Completed intents marked with results	none
`REQ-003-US-005-008`	yes	Lifecycle queries supported (get all EXECUTING intents)	1
`REQ-003-US-005-009`	yes	Lifecycle statistics calculated (completion rate, avg duration)	none
`REQ-003-US-005-010`	yes	Lifecycle visualization available	1
`REQ-003-US-005-011`	yes	Define `IntentStatus` enum with all states	1
`REQ-003-US-005-012`	yes	Add status field to `Intent` dataclass	1
`REQ-003-US-005-013`	yes	Add timestamp fields (created_at, validated_at, completed_at)	none
`REQ-003-US-005-014`	yes	Implement state transition validation	1
`REQ-003-US-005-015`	yes	Create state machine for valid transitions	1
`REQ-003-US-005-016`	yes	Implement `transition_to()` method with validation	1
`REQ-003-US-005-017`	yes	Add event publisher for state changes	none
`REQ-003-US-005-018`	yes	Create lifecycle history table in storage	2
`REQ-003-US-005-019`	yes	Implement lifecycle query methods	5
`REQ-003-US-005-020`	yes	Add error details field for FAILED state	none
`REQ-003-US-005-021`	yes	Add result field for COMPLETED state	none
`REQ-003-US-005-022`	yes	Create lifecycle statistics calculator	none
`REQ-003-US-005-023`	yes	Implement lifecycle dashboard data provider	none
`REQ-003-US-005-024`	yes	Add lifecycle telemetry and metrics	none
`REQ-003-US-005-025`	yes	Create lifecycle visualization endpoints	1
`REQ-003-US-005-026`	yes	Unit test: New intent starts in PENDING state	1
`REQ-003-US-005-027`	yes	Unit test: PENDING → VALIDATED transition succeeds	none
`REQ-003-US-005-028`	yes	Unit test: VALIDATED → EXECUTING transition succeeds	none
`REQ-003-US-005-029`	yes	Unit test: EXECUTING → COMPLETED transition succeeds	none
`REQ-003-US-005-030`	yes	Unit test: EXECUTING → FAILED transition succeeds	none
`REQ-003-US-005-031`	yes	Unit test: Invalid transition (PENDING → COMPLETED) raises error	2
`REQ-003-US-005-032`	yes	Unit test: State change publishes event	none
`REQ-003-US-005-033`	yes	Integration test: Lifecycle history stores all transitions	2
`REQ-003-US-005-034`	yes	Integration test: Query returns all EXECUTING intents	1
`REQ-003-US-005-035`	yes	Integration test: Statistics calculate completion rate correctly	none
`REQ-003-US-006-001`	yes	All intents stored in persistent history	2
`REQ-003-US-006-002`	yes	History searchable by requester, action, target, date	1
`REQ-003-US-006-003`	yes	History filterable by status, priority	2
`REQ-003-US-006-004`	yes	Intent replay creates new intent with same parameters	1
`REQ-003-US-006-005`	yes	Replay validates intent again before execution	2
`REQ-003-US-006-006`	yes	Replay supports batch operations	1
`REQ-003-US-006-007`	yes	History pagination for large result sets	4
`REQ-003-US-006-008`	yes	History export to JSON/CSV	2
`REQ-003-US-006-009`	yes	History retention policy configurable	2
`REQ-003-US-006-010`	yes	History privacy controls (redact sensitive data)	2
`REQ-003-US-006-011`	yes	Create `IntentHistory` class in `src/session/intent_history.py`	1
`REQ-003-US-006-012`	yes	Implement history storage backend (JSON file or database)	2
`REQ-003-US-006-013`	yes	Add `store_intent()` method	1
`REQ-003-US-006-014`	yes	Add `search_intents()` method with filters	1
`REQ-003-US-006-015`	yes	Add `get_intent_by_id()` method	1
`REQ-003-US-006-016`	yes	Add `replay_intent()` method	1
`REQ-003-US-006-017`	yes	Implement batch replay for multiple intents	1
`REQ-003-US-006-018`	yes	Add pagination support (page size, offset)	4
`REQ-003-US-006-019`	yes	Create export methods (to_json, to_csv)	2
`REQ-003-US-006-020`	yes	Implement retention policy (delete old intents)	1
`REQ-003-US-006-021`	yes	Add privacy redaction for sensitive fields	1
`REQ-003-US-006-022`	yes	Create history index for fast queries	none
`REQ-003-US-006-023`	yes	Add history compaction for space efficiency	1
`REQ-003-US-006-024`	yes	Implement history migration for schema changes	none
`REQ-003-US-006-025`	yes	Create history backup and restore	2
`REQ-003-US-006-026`	yes	Unit test: Store intent creates history entry	1
`REQ-003-US-006-027`	yes	Unit test: Search by requester returns matching intents	1
`REQ-003-US-006-028`	yes	Unit test: Search by action returns matching intents	1
`REQ-003-US-006-029`	yes	Unit test: Search by date range returns matching intents	1
`REQ-003-US-006-030`	yes	Unit test: Replay intent creates new intent with same data	1
`REQ-003-US-006-031`	yes	Unit test: Replay validates intent before execution	1
`REQ-003-US-006-032`	yes	Integration test: History stores 10000 intents successfully	2
`REQ-003-US-006-033`	yes	Integration test: Search with pagination returns correct pages	1
`REQ-003-US-006-034`	yes	Integration test: Export to JSON preserves all data	1
`REQ-003-US-006-035`	yes	Performance test: Search 10000 intents in <200ms	1
`REQ-003-US-007-001`	yes	Intent templates defined for common patterns	1
`REQ-003-US-007-002`	yes	Templates support parameter substitution	1
`REQ-003-US-007-003`	yes	Templates validated at definition time	1
`REQ-003-US-007-004`	yes	Template library searchable by name and description	4
`REQ-003-US-007-005`	yes	Custom templates creatable by users	2
`REQ-003-US-007-006`	yes	Templates exportable and importable	2
`REQ-003-US-007-007`	yes	Template versioning supported	1
`REQ-003-US-007-008`	yes	Templates composable (template A uses template B)	5
`REQ-003-US-007-009`	yes	Template preview shows expanded intent	none
`REQ-003-US-007-010`	yes	Template usage tracked for analytics	none
`REQ-003-US-007-011`	yes	Create `IntentTemplate` class in `src/session/intent_template.py`	1
`REQ-003-US-007-012`	yes	Define template schema with placeholders	1
`REQ-003-US-007-013`	yes	Implement parameter substitution engine	1
`REQ-003-US-007-014`	yes	Create template library storage	4
`REQ-003-US-007-015`	yes	Add predefined templates (create_file, read_config, deploy_app)	1
`REQ-003-US-007-016`	yes	Implement template search by name/description	2
`REQ-003-US-007-017`	yes	Add `create_custom_template()` method	1
`REQ-003-US-007-018`	yes	Implement template export to JSON	2
`REQ-003-US-007-019`	yes	Implement template import from JSON	1
`REQ-003-US-007-020`	yes	Add template versioning with `__version__` field	none
`REQ-003-US-007-021`	yes	Implement template composition (nested templates)	4
`REQ-003-US-007-022`	yes	Create template preview generator	none
`REQ-003-US-007-023`	yes	Add template usage tracking	none
`REQ-003-US-007-024`	yes	Implement template analytics dashboard	1
`REQ-003-US-007-025`	yes	Create template validation framework	1
`REQ-003-US-007-026`	yes	Unit test: Create template with placeholders succeeds	1
`REQ-003-US-007-027`	yes	Unit test: Substitute parameters expands template correctly	none
`REQ-003-US-007-028`	yes	Unit test: Template validation catches invalid syntax	1
`REQ-003-US-007-029`	yes	Unit test: Search templates by name returns matches	1
`REQ-003-US-007-030`	yes	Unit test: Create custom template stores successfully	1
`REQ-003-US-007-031`	yes	Unit test: Export template to JSON and import preserves data	2
`REQ-003-US-007-032`	yes	Integration test: Use template to create 100 intents	none
`REQ-003-US-007-033`	yes	Integration test: Composed template expands nested templates	1
`REQ-003-US-007-034`	yes	Integration test: Template preview shows correct output	none
`REQ-003-US-007-035`	yes	Integration test: Template usage analytics track invocations	none
`REQ-003-US-008-001`	yes	Workflow defined as sequence of intents	2
`REQ-003-US-008-002`	yes	Workflow execution follows dependency order	2
`REQ-003-US-008-003`	yes	Workflow supports parallel execution of independent intents	2
`REQ-003-US-008-004`	yes	Workflow handles intent failures gracefully (retry, rollback, continue)	3
`REQ-003-US-008-005`	yes	Workflow state persisted across restarts	2
`REQ-003-US-008-006`	yes	Workflow cancellation supported	1
`REQ-003-US-008-007`	yes	Workflow progress tracking available	2
`REQ-003-US-008-008`	yes	Workflow conditional branching supported	1
`REQ-003-US-008-009`	yes	Workflow loops supported (with max iterations)	1
`REQ-003-US-008-010`	yes	Workflow results aggregated and returned	1
`REQ-003-US-008-011`	yes	Create `IntentWorkflow` class in `src/session/intent_workflow.py`	1
`REQ-003-US-008-012`	yes	Define workflow schema with intent list	3
`REQ-003-US-008-013`	yes	Implement dependency graph builder	1
`REQ-003-US-008-014`	yes	Create workflow executor with topological sort	2
`REQ-003-US-008-015`	yes	Add parallel execution engine using asyncio	1
`REQ-003-US-008-016`	yes	Implement failure handling strategies (retry, rollback, continue)	2
`REQ-003-US-008-017`	yes	Add workflow state persistence	1
`REQ-003-US-008-018`	yes	Implement workflow cancellation	1
`REQ-003-US-008-019`	yes	Create workflow progress tracker	1
`REQ-003-US-008-020`	yes	Add conditional branching support (if/else)	1
`REQ-003-US-008-021`	yes	Implement loop support with max iterations	1
`REQ-003-US-008-022`	yes	Create workflow result aggregator	4
`REQ-003-US-008-023`	yes	Add workflow visualization (DAG diagram)	1
`REQ-003-US-008-024`	yes	Implement workflow telemetry and metrics	none
`REQ-003-US-008-025`	yes	Create workflow testing framework	none
`REQ-003-US-008-026`	yes	Unit test: Create workflow with 3 sequential intents	1
`REQ-003-US-008-027`	yes	Unit test: Execute workflow completes all intents in order	1
`REQ-003-US-008-028`	yes	Unit test: Parallel intents execute concurrently	1
`REQ-003-US-008-029`	yes	Unit test: Failed intent triggers retry strategy	1
`REQ-003-US-008-030`	yes	Unit test: Workflow state persists across restarts	1
`REQ-003-US-008-031`	yes	Unit test: Workflow cancellation stops execution	1
`REQ-003-US-008-032`	yes	Integration test: Workflow with 10 intents completes successfully	1
`REQ-003-US-008-033`	yes	Integration test: Conditional branching selects correct path	1
`REQ-003-US-008-034`	yes	Integration test: Loop executes correct number of iterations	1
`REQ-003-US-008-035`	yes	Performance test: Execute workflow with 100 intents in <10 seconds	1
`REQ-003-US-009-001`	yes	Intent metrics collected (count, latency, success rate)	17
`REQ-003-US-009-002`	yes	Metrics broken down by action, target, requester	2
`REQ-003-US-009-003`	yes	Real-time metrics dashboard available	none
`REQ-003-US-009-004`	yes	Metrics exportable to monitoring systems (Prometheus, Grafana)	none
`REQ-003-US-009-005`	yes	Alerting on metric thresholds (high failure rate, high latency)	none
`REQ-003-US-009-006`	yes	Metrics retention configurable	none
`REQ-003-US-009-007`	yes	Metrics aggregation by time window (1min, 5min, 1hour)	1
`REQ-003-US-009-008`	yes	Historical metrics queryable	3
`REQ-003-US-009-009`	yes	Metrics API for programmatic access	3
`REQ-003-US-009-010`	yes	Metrics visualization with charts and graphs	none
`REQ-003-US-009-011`	yes	Create `IntentMetrics` class in `src/session/intent_metrics.py`	1
`REQ-003-US-009-012`	yes	Implement metrics collector (count, latency, errors)	6
`REQ-003-US-009-013`	yes	Add metrics breakdown by dimensions (action, target, requester)	none
`REQ-003-US-009-014`	yes	Create metrics storage backend (in-memory + persistent)	8
`REQ-003-US-009-015`	yes	Implement real-time metrics aggregation	none
`REQ-003-US-009-016`	yes	Add Prometheus exporter for metrics	1
`REQ-003-US-009-017`	yes	Create metrics dashboard using Grafana	none
`REQ-003-US-009-018`	yes	Implement alerting rules (failure rate >5%, latency >1s)	4
`REQ-003-US-009-019`	yes	Add metrics retention policy (keep 30 days)	1
`REQ-003-US-009-020`	yes	Implement time window aggregation (1min, 5min, 1hour)	none
`REQ-003-US-009-021`	yes	Create historical metrics query API	1
`REQ-003-US-009-022`	yes	Add metrics visualization endpoints	none
`REQ-003-US-009-023`	yes	Implement metrics export (JSON, CSV)	2
`REQ-003-US-009-024`	yes	Create metrics telemetry pipeline	2
`REQ-003-US-009-025`	yes	Add metrics documentation	none
`REQ-003-US-009-026`	yes	Unit test: Metrics collector increments count correctly	none
`REQ-003-US-009-027`	yes	Unit test: Metrics collector records latency correctly	none
`REQ-003-US-009-028`	yes	Unit test: Metrics collector tracks errors correctly	none
`REQ-003-US-009-029`	yes	Unit test: Metrics breakdown by action returns correct data	none
`REQ-003-US-009-030`	yes	Unit test: Time window aggregation calculates correct averages	none
`REQ-003-US-009-031`	yes	Integration test: Prometheus scrapes metrics successfully	none
`REQ-003-US-009-032`	yes	Integration test: Dashboard displays real-time metrics	none
`REQ-003-US-009-033`	yes	Integration test: Alert triggers on high failure rate	none
`REQ-003-US-009-034`	yes	Integration test: Historical query returns correct data	1
`REQ-003-US-009-035`	yes	Performance test: Metrics collection overhead <1ms per intent	none
`REQ-003-US-010-001`	yes	Intent requester identity verified	1
`REQ-003-US-010-002`	yes	Intent authentication using tokens or credentials	3
`REQ-003-US-010-003`	yes	Intent authorization checked via Prolog policies	5
`REQ-003-US-010-004`	yes	Intent encryption for sensitive data in transit	none
`REQ-003-US-010-005`	yes	Intent signing to prevent tampering	none
`REQ-003-US-010-006`	yes	Intent audit logging for security events	11
`REQ-003-US-010-007`	yes	Intent injection prevention (SQL, command, path traversal)	3
`REQ-003-US-010-008`	yes	Intent rate limiting per requester	2
`REQ-003-US-010-009`	yes	Intent blacklist for malicious patterns	4
`REQ-003-US-010-010`	yes	Intent security monitoring and anomaly detection	2
`REQ-003-US-010-011`	yes	Create `IntentSecurity` class in `src/session/intent_security.py`	1
`REQ-003-US-010-012`	yes	Implement requester identity verification	3
`REQ-003-US-010-013`	yes	Add authentication using JWT tokens	1
`REQ-003-US-010-014`	yes	Implement authorization check via Prolog	3
`REQ-003-US-010-015`	yes	Create Prolog predicate `authorize_intent/3`	none
`REQ-003-US-010-016`	yes	Add encryption for sensitive intent parameters	none
`REQ-003-US-010-017`	yes	Implement intent signing using HMAC	none
`REQ-003-US-010-018`	yes	Create security audit logger	14
`REQ-003-US-010-019`	yes	Implement injection prevention filters (SQL, command, path)	2
`REQ-003-US-010-020`	yes	Add rate limiting per requester (10 intents/minute)	1
`REQ-003-US-010-021`	yes	Create intent blacklist (regex patterns)	3
`REQ-003-US-010-022`	yes	Implement security monitoring and anomaly detection	1
`REQ-003-US-010-023`	yes	Add security telemetry and metrics	3
`REQ-003-US-010-024`	yes	Create security incident response workflow	2
`REQ-003-US-010-025`	yes	Implement security policy hot-reload	4
`REQ-003-US-010-026`	yes	Unit test: Valid requester identity passes verification	1
`REQ-003-US-010-027`	yes	Unit test: Invalid requester identity fails verification	1
`REQ-003-US-010-028`	yes	Unit test: Valid JWT token passes authentication	1
`REQ-003-US-010-029`	yes	Unit test: Invalid JWT token fails authentication	1
`REQ-003-US-010-030`	yes	Unit test: Authorized intent passes authorization check	1
`REQ-003-US-010-031`	yes	Unit test: Unauthorized intent fails authorization check	1
`REQ-003-US-010-032`	yes	Unit test: Intent with sensitive data is encrypted	none
`REQ-003-US-010-033`	yes	Unit test: Intent signature verification succeeds	none
`REQ-003-US-010-034`	yes	Unit test: SQL injection attempt blocked	1
`REQ-003-US-010-035`	yes	Unit test: Rate limit exceeded blocks intent	1
`REQ-003-US-010-036`	yes	Integration test: Security audit log records all events	1
`REQ-003-US-010-037`	yes	Integration test: Anomaly detection flags suspicious intent	1
`REQ-003-US-010-038`	yes	Performance test: Security checks add <10ms overhead	none
`REQ-003-US-010-039`	yes	Security test: Penetration testing finds no vulnerabilities	2
`REQ-003-US-010-040`	yes	Security test: Compliance audit passes all checks	2
`REQ-003-FR24-001`	yes	`session pipeline run <intent>` runs the full agent pipeline (via `PipelineRunner.run`) for a natural-language intent, honoring `--work-type`, `--has-ui`, and `--thread-id`, printing per-stage status/duration/artifact counts, and exiting non-zero when the pipeline does not succeed	3
`REQ-003-FR24-002`	yes	`session pipeline status <thread_id>` reports the checkpointed stages and resumable-artifact count for a thread from the real `kernel.pipeline_checkpoint.PipelineCheckpoint` store, degrading to "no checkpoint found" (exit 1) when the store is unavailable or the thread has no checkpoint	5
`REQ-003-FR24-003`	yes	`session pipeline resume <thread_id>` reconstructs completed stages from the checkpoint store and re-enters `PipelineRunner` from the first incomplete stage (deriving the remaining stage order from `--work-type`/`--has-ui`), reusing already-checkpointed stage outputs rather than re-invoking them	15
`REQ-003-FR24-004`	yes	`session pipeline list` lists recent pipeline runs from the `pipeline_output` directory with per-run stage and artifact counts, reporting "No pipeline runs found" when the directory is missing or empty	1
`REQ-003-FR24-100`	yes	`PipelineRunner` carries a submitted intent through its full stage sequence to completion, returning per-stage results and the produced artifacts, and the completed run's record reaches the knowledge graph (review work type is the shortest such path: `U:Qa` → `U:Cp`)	none
`REQ-003-FR24-101`	yes	The `analysis` work type routes through the `U:Cx` → `U:BA` → `U:Cp` agent sequence, in that order	none
`REQ-003-FR24-102`	yes	The `documentation` work type routes through the `U:Cx` → `U:Do` → `U:Cp` agent sequence, engaging the Documentor volk	none
`REQ-003-FR24-103`	yes	A pipeline run logs its work to the session work log, so a completed run is recoverable from session state and not only from pipeline output	none
`REQ-003-FR24-104`	yes	An unrecognised work-type string is rejected at submission with `ValueError` rather than dispatched to an undefined stage sequence	none
`REQ-003-FR24-105`	yes	A stage that exceeds its timeout is recorded as `FAILED` carrying the timeout error message; the run reports the failure instead of hanging	none
`REQ-003-FR24-106`	yes	A stage naming an agent alias that resolves to no registered volk fails with a clear alias-resolution error rather than a bare attribute or key error	none

Code that traces this spec

Module	Symbols	Requirements
`orchestrata_ultimate/agents/intent_adapter`	2	2
`orchestrata_ultimate/core/protocols/decoupling`	8	4
`orchestrata_ultimate/infra/redis_state`	2	2
`orchestrata_ultimate/kernel/cli_main`	3	1
`orchestrata_ultimate/kernel/pipeline`	3	1
`orchestrata_ultimate/kernel/pipeline_checkpoint`	8	2
`orchestrata_ultimate/knowledge_graph/temporal`	1	5
`orchestrata_ultimate/orchestrator/ambiguity_resolver`	13	7
`orchestrata_ultimate/orchestrator/fact_graph`	1	1
`orchestrata_ultimate/orchestrator/fact_manager`	4	1
`orchestrata_ultimate/orchestrator/fact_store`	1	1
`orchestrata_ultimate/orchestrator/graph_audit`	27	14
`orchestrata_ultimate/orchestrator/intent_broker`	15	7
`orchestrata_ultimate/orchestrator/intent_broker_factory`	1	1
`orchestrata_ultimate/orchestrator/intent_classifier`	25	13
`orchestrata_ultimate/orchestrator/intent_enums`	1	1
`orchestrata_ultimate/orchestrator/intent_history`	18	37
`orchestrata_ultimate/orchestrator/intent_lifecycle`	9	15
`orchestrata_ultimate/orchestrator/intent_metrics`	28	12
`orchestrata_ultimate/orchestrator/intent_normalizer`	7	5
`orchestrata_ultimate/orchestrator/intent_parser`	14	14
`orchestrata_ultimate/orchestrator/intent_results`	8	9
`orchestrata_ultimate/orchestrator/intent_router`	8	13
`orchestrata_ultimate/orchestrator/intent_security`	14	26
`orchestrata_ultimate/orchestrator/intent_template`	18	27
`orchestrata_ultimate/orchestrator/intent_types`	15	42
`orchestrata_ultimate/orchestrator/intent_validator`	6	30
`orchestrata_ultimate/orchestrator/intent_vocabulary`	8	3
`orchestrata_ultimate/orchestrator/intent_workflow`	20	33
`orchestrata_ultimate/orchestrator/nlp`	28	7
`orchestrata_ultimate/orchestrator/parameter_extractor`	8	5
`orchestrata_ultimate/orchestrator/pipeline_kernel`	6	3
`orchestrata_ultimate/orchestrator/pipeline_router`	4	4
`orchestrata_ultimate/orchestrator/pipeline_runner`	8	6
`orchestrata_ultimate/orchestrator/policy_registry`	10	5
`orchestrata_ultimate/session/cli/pipeline`	5	4
`orchestrata_ultimate/verification/orchestration/coordinator`	1	1
`orchestrata_ultimate/verification/protocols/verification_cxp`	1	1

Checklists

`checklists/README.md`

Intent Broker (U:Intents) Checklists

Project Overview

Project: Orchestrator-AI Intent Broker (Spec 003)
Component: U:Intents (Intent Broker)
Repository: orchestrata/implementation
Status: Specification Phase

Purpose

The Intent Broker (U:Intents) is responsible for interpreting user and agent requests, transforming natural language into structured, actionable intents, and routing them to appropriate Volks while enforcing governance policies.

Core Responsibilities

Intent Parsing: Extract structured intent data from natural language
Intent Validation: Verify intents against Prolog governance policies
Intent Routing: Direct validated intents to appropriate Volks
Lifecycle Management: Track intent states from creation to completion
History & Replay: Maintain intent history for auditing and replay
Security & Access: Enforce access control and prevent injection attacks

Intent Structure

@dataclass
class Intent:
    id: str
    action: IntentAction  # READ, WRITE, DELETE, EXECUTE, QUERY
    target: IntentTarget  # FILE, CODE, DATABASE, API, SYSTEM
    parameters: Dict[str, Any]
    constraints: List[str]
    requester: str  # User or Volk ID
    status: IntentStatus  # PENDING, VALIDATED, EXECUTING, COMPLETED, FAILED
    created_at: datetime
    validated_at: Optional[datetime]
    completed_at: Optional[datetime]

Intent Actions

READ: Retrieve information or data
WRITE: Create or modify resources
DELETE: Remove resources
EXECUTE: Run operations or workflows
QUERY: Search or filter data

Intent Targets

FILE: File system operations
CODE: Code generation or modification
DATABASE: Data storage operations
API: External service interactions
SYSTEM: System-level operations

Checklist Summary

Checklist	Total Items	Progress
Requirements	250+	0%
Constitutional	220+	0%
Testing	330+	0%
TOTAL	800+	0%

Performance Targets

Metric	Target	Rationale
Intent Parsing	<100ms	Real-time user experience
Intent Validation	<50ms	Quick policy checks
Intent Routing	<20ms	Fast Volk dispatch
History Query	<200ms	Acceptable for audit
Throughput	1000 intents/sec	High-volume support

Architecture Integration

Dependencies

Prolog Interface: Intent validation rules
CXP Protocol: Intent-to-packet conversion
Postman (U:PS): Intent delivery to Volks
Session Manager: Intent context tracking

Data Flow

User Input → Intent Parser → Intent Validator (Prolog) → Intent Router → Postman → Target Volk
     ↓             ↓                  ↓                        ↓              ↓
  History      Templates          Policies              Queue          Execution

Usage Guidelines

For Developers

Start with Requirements: Review requirements.md for user stories
Check Constitutional Compliance: Verify against constitutional.md
Plan Tests: Use testing.md as test specification
Mark Progress: Check boxes [x] as items are completed
Commit Regularly: Update checklists with code commits

For Reviewers

Verify Completeness: Ensure all checkboxes are addressed
Test Coverage: Confirm tests match checklist items
Constitutional Review: Validate compliance with all 11 articles
Performance Validation: Check against performance targets

For Project Managers

Track Progress: Monitor completion percentages
Identify Blockers: Find unchecked items with dependencies
Plan Sprints: Group checklist items into sprints
Report Status: Use checklist completion for stakeholder updates

Checklist Update Process

Review checklist before starting work
Check items [x] as they are completed
Commit changes with meaningful messages
Update totals in this README
Document deviations if requirements change

Compliance Notes

All Intent Broker implementation MUST:

Store intent facts in Prolog (Article II)
Use absolute imports only (Article III)
Test with real Prolog, no mocking (Article VII)
Use uv for dependencies (Article VIII)
Verify all operations (Article IX)
Follow constitutional governance (Article X)

Contact & Escalation

Author: Mohamed
Architecture Questions: Refer to orchestrata/ARCHITECTURE.md
Governance Issues: Escalate to U:Ox (Orchestrator)
Technical Blockers: Document in specs/003-intent/BLOCKERS.md

Last Updated: 2026-01-15
Checklist Version: 1.0
Status: Initial Specification

`checklists/constitutional.md`

Intent Broker Constitutional Compliance Checklist

Spec: 003-intent
Component: U:Intents (Intent Broker)
Status: Specification Phase

Overview

This checklist ensures the Intent Broker (U:Intents) component complies with all 11 articles of the Orchestrata Constitution. Each article includes specific compliance requirements and verification steps.

Total Compliance Items: 220+ checkboxes

Article I: Separation of Concerns

Principle: Each Volk has a single, well-defined responsibility

Compliance Requirements

[ ] Intent Broker handles ONLY intent parsing, validation, and routing
[ ] Intent Broker does NOT execute intents (delegates to Volks)
[ ] Intent Broker does NOT generate code (delegates to VizInt)
[ ] Intent Broker does NOT make architectural decisions (delegates to Architect)
[ ] Intent Broker does NOT manage deployments (delegates to Orchestrator)
[ ] Intent Broker interface clearly defines its scope
[ ] Intent Broker rejects out-of-scope requests
[ ] Intent Broker documentation clarifies boundaries
[ ] Intent Broker escalates ambiguous scope questions to Orchestrator
[ ] Intent Broker metrics track scope violations

Implementation Verification

[ ] IntentBroker class has single responsibility (SRP)
[ ] No code generation logic in Intent Broker
[ ] No deployment logic in Intent Broker
[ ] No architectural decision logic in Intent Broker
[ ] Clear separation between parsing, validation, routing
[ ] Each sub-component has dedicated class
[ ] Integration tests verify delegation to correct Volks
[ ] Scope violation tests raise appropriate errors
[ ] Documentation includes scope boundaries diagram
[ ] Code review checklist includes scope validation

Article II: Prolog as Source of Truth

Principle: All governance rules, ownership, and policies are defined in Prolog

Compliance Requirements

[ ] Intent validation rules stored in Prolog (prolog/intent.pl)
[ ] Intent routing rules stored in Prolog
[ ] Intent authorization policies stored in Prolog
[ ] Intent rate limits stored in Prolog
[ ] Intent access control stored in Prolog
[ ] Volk capability mappings stored in Prolog
[ ] Intent lifecycle rules stored in Prolog
[ ] Intent security policies stored in Prolog
[ ] ALL policy decisions query Prolog (no hardcoded rules)
[ ] Policy changes require ONLY Prolog updates (no code changes)

Implementation Verification

[ ] prolog/intent.pl file exists with all predicates
[ ] validate_intent/4 predicate implemented
[ ] route_intent/3 predicate implemented
[ ] authorize_intent/3 predicate implemented
[ ] check_rate_limit/2 predicate implemented
[ ] can_perform_action/3 predicate implemented
[ ] has_target_access/3 predicate implemented
[ ] volk_can_handle/3 predicate implemented
[ ] No validation logic in Python (only Prolog queries)
[ ] No routing logic in Python (only Prolog queries)
[ ] Integration tests verify Prolog queries work
[ ] Prolog rule changes update behavior without code changes
[ ] Documentation includes Prolog schema reference
[ ] Code review checklist includes Prolog-first validation

Prolog Schema

% Intent validation
validate_intent(Action, Target, Requester, Result).

% Intent routing
route_intent(Action, Target, Volk).
volk_can_handle(Volk, Action, Target).

% Authorization
authorize_intent(Requester, Action, Target).
can_perform_action(Requester, Action, Target).
has_target_access(Requester, Target, Permission).

% Rate limiting
check_rate_limit(Requester, Allowed).
rate_limit(Requester, MaxPerMinute).

% Security policies
intent_blacklist(Pattern, Reason).
injection_pattern(Type, Pattern).

Article III: Absolute Imports Only

Principle: All imports use absolute paths from project root

Compliance Requirements

[ ] All imports use from src.session.intent_parser import ...
[ ] NO relative imports (from .parser import ...)
[ ] NO parent directory imports (from ..utils import ...)
[ ] Import statements verified by linter
[ ] Import errors caught in CI/CD
[ ] Documentation shows correct import examples
[ ] Code templates use absolute imports
[ ] Migration guide for relative to absolute imports
[ ] Pre-commit hook checks import style
[ ] Import violations block PR merge

Implementation Verification

[ ] All .py files use absolute imports
[ ] Flake8/Pylint configured to catch relative imports
[ ] CI/CD fails on relative import detection
[ ] Pre-commit hook added for import checking
[ ] Code review checklist includes import validation
[ ] Documentation updated with import guidelines
[ ] Example code uses absolute imports
[ ] Test files use absolute imports
[ ] No from . import patterns in codebase
[ ] No from .. import patterns in codebase

Article IV: CXP Protocol Compliance

Principle: All inter-Volk communication uses CXP packets

Compliance Requirements

[ ] Intent-to-CXP conversion implemented
[ ] CXP packets include all intent metadata
[ ] CXP headers populated correctly (TO, FROM, THREAD_ID, SUBJECT)
[ ] CXP packet validation before sending
[ ] CXP delivery status tracked
[ ] CXP acknowledgment received
[ ] CXP error handling implemented
[ ] CXP retry logic for failed deliveries
[ ] CXP packet logging for audit
[ ] CXP metrics tracked (delivery time, success rate)

Implementation Verification

[ ] intent_to_cxp() function implemented
[ ] CXP packet structure includes intent data
[ ] CXP headers populated from intent fields
[ ] CXP packet validator runs before send
[ ] CXP delivery tracking stored in database
[ ] CXP acknowledgment handler implemented
[ ] CXP error handler with retry logic
[ ] CXP packet logger writes to audit trail
[ ] CXP metrics collector tracks all packets
[ ] Integration tests verify end-to-end CXP flow

Article V: Dependency Injection

Principle: All dependencies injected via constructor, not hardcoded

Compliance Requirements

[ ] IntentBroker receives dependencies via constructor
[ ] IntentParser injected (not instantiated internally)
[ ] IntentValidator injected
[ ] IntentRouter injected
[ ] PrologInterface injected
[ ] IntentHistory injected
[ ] IntentMetrics injected
[ ] IntentSecurity injected
[ ] Configuration injected (not read from global state)
[ ] NO hardcoded singletons or global state

Implementation Verification

[ ] IntentBroker.__init__() accepts all dependencies
[ ] Type hints for all injected dependencies
[ ] Dependency injection container configured
[ ] Factory pattern for complex object creation
[ ] NO global variables in Intent Broker
[ ] NO module-level configuration reading
[ ] Unit tests inject mock dependencies
[ ] Integration tests inject real dependencies
[ ] Dependency injection documentation updated
[ ] Code review checklist includes DI validation

Article VI: Async-First Design

Principle: All I/O operations are asynchronous

Compliance Requirements

[ ] Intent parsing is async (async def parse_intent())
[ ] Intent validation is async (Prolog queries via async)
[ ] Intent routing is async
[ ] Intent history storage is async
[ ] Intent metrics collection is async
[ ] CXP packet sending is async
[ ] NO blocking I/O in hot paths
[ ] Async context managers for resource cleanup
[ ] Proper async error handling (try/except in async)
[ ] Async timeouts configured

Implementation Verification

[ ] All public methods are async def
[ ] Prolog queries use asyncio.run_in_executor() or async driver
[ ] File I/O uses aiofiles
[ ] Network I/O uses asyncio or aiohttp
[ ] Database I/O uses async driver (asyncpg, motor)
[ ] NO time.sleep() calls (use asyncio.sleep())
[ ] NO blocking HTTP calls (use aiohttp)
[ ] Async context managers for resources (async with)
[ ] Timeout decorators on all async methods
[ ] Integration tests verify async behavior

Article VII: Real Testing Only (No Mocking)

Principle: Tests use real implementations, not mocks

Compliance Requirements

[ ] Intent Broker tests use real Prolog instance
[ ] Intent validation tests query real Prolog
[ ] Intent routing tests use real routing logic
[ ] Intent history tests use real storage backend
[ ] NO mock.Mock() in Intent Broker tests
[ ] NO unittest.mock.patch() in Intent Broker tests
[ ] Test fixtures provide real test data
[ ] Integration tests use real Volks (in containers)
[ ] Performance tests use real workloads
[ ] Test documentation explains no-mocking policy

Implementation Verification

[ ] Zero imports of unittest.mock in test files
[ ] Zero imports of mock package in test files
[ ] Test fixtures create real Prolog instance
[ ] Test fixtures create real storage backend
[ ] Integration tests run in containers (Incus/Docker)
[ ] Performance tests measure real latency
[ ] CI/CD runs tests with real dependencies
[ ] Test failure analysis uses real stack traces
[ ] Code review checklist includes no-mocking check
[ ] Documentation explains testing philosophy

Article VIII: UV Package Manager

Principle: Use UV for all dependency management

Compliance Requirements

[ ] pyproject.toml lists all Intent Broker dependencies
[ ] uv sync installs dependencies
[ ] NO pip install commands in documentation
[ ] NO requirements.txt files
[ ] UV lockfile committed to version control
[ ] CI/CD uses uv for installation
[ ] Documentation shows uv add commands
[ ] Development guide uses uv
[ ] Pre-commit hook checks for pip usage
[ ] UV version pinned in CI/CD

Implementation Verification

[ ] pyproject.toml includes all dependencies
[ ] uv.lock file exists and is up-to-date
[ ] CI/CD script uses uv sync
[ ] Documentation replaced pip with uv
[ ] No requirements.txt in repository
[ ] Pre-commit hook detects pip usage
[ ] Development guide updated with UV commands
[ ] UV version documented in README
[ ] Code review checklist includes UV check
[ ] Migration guide from pip to UV provided

Article IX: Verification Before Claims

Principle: Never claim success without executing and verifying

Compliance Requirements

[ ] Intent validation returns verified result (not assumed)
[ ] Intent routing confirms delivery before returning
[ ] Intent execution waits for Volk acknowledgment
[ ] Intent completion verified via status check
[ ] NO "should work" language in logs or responses
[ ] All success messages based on actual verification
[ ] Errors reported with actual failure details
[ ] Timeouts fail explicitly (not assumed success)
[ ] Rollback verified after failure
[ ] Audit logs reflect actual state (not intended state)

Implementation Verification

[ ] Validation method waits for Prolog response
[ ] Routing method waits for CXP acknowledgment
[ ] Execution method polls for completion status
[ ] Success responses include verification timestamp
[ ] Log messages use definitive language ("validated", "routed")
[ ] Error messages include actual error details
[ ] Timeout handler marks intent as FAILED
[ ] Rollback handler verifies cleanup completed
[ ] Audit logger writes after verification
[ ] Code review checklist includes verification check

Article X: Constitutional Governance

Principle: All Volks follow constitutional principles

Compliance Requirements

[ ] Intent Broker adheres to all 11 articles
[ ] Constitutional violations logged and escalated
[ ] Governance rules enforced via Prolog
[ ] Compliance audits run regularly
[ ] Compliance reports generated
[ ] Non-compliant intents rejected
[ ] Compliance metrics tracked
[ ] Compliance training for developers
[ ] Compliance checklist in PR template
[ ] Compliance documentation maintained

Implementation Verification

[ ] All articles have compliance checks
[ ] Compliance violations trigger alerts
[ ] Prolog rules enforce constitutional policies
[ ] Compliance audit script runs in CI/CD
[ ] Compliance report generated monthly
[ ] PR template includes compliance checklist
[ ] Developer onboarding includes compliance training
[ ] Documentation links to constitution
[ ] Code review includes compliance validation
[ ] Compliance metrics dashboard available

Article XI: Observability and Auditability

Principle: All operations are logged and traceable

Compliance Requirements

[ ] Intent parsing logged with input and output
[ ] Intent validation logged with decision and reason
[ ] Intent routing logged with target Volk
[ ] Intent execution logged with start and end times
[ ] Intent failures logged with error details
[ ] Logs include correlation IDs (intent ID, thread ID)
[ ] Logs structured (JSON) for machine parsing
[ ] Logs sent to centralized logging system
[ ] Logs retained per compliance requirements
[ ] Audit trail queryable for forensics

Implementation Verification

[ ] All methods log entry and exit
[ ] Logger includes correlation ID in all messages
[ ] Logs use structured format (JSON)
[ ] Log messages include all relevant context
[ ] Error logs include full stack trace
[ ] Logs sent to centralized system (ELK, Splunk)
[ ] Log retention policy configured (90 days)
[ ] Audit query API implemented
[ ] Compliance audit script queries logs
[ ] Log dashboard shows all operations

Summary

Total Compliance Items: 220+

Article	Checkboxes	Compliance
Article I: Separation of Concerns	20	0%
Article II: Prolog as Source of Truth	25	0%
Article III: Absolute Imports Only	20	0%
Article IV: CXP Protocol Compliance	20	0%
Article V: Dependency Injection	20	0%
Article VI: Async-First Design	20	0%
Article VII: Real Testing Only	20	0%
Article VIII: UV Package Manager	20	0%
Article IX: Verification Before Claims	20	0%
Article X: Constitutional Governance	20	0%
Article XI: Observability and Auditability	15	0%

Total Compliance Progress: 0/220+ (0%)

Last Updated: 2026-01-15
Author: Mohamed
Status: Initial Specification

`checklists/requirements.md`

The requirement list above comes from this file; 395 of 396 checkbox items are ticked.

`checklists/testing.md`

Intent Broker Testing Checklist

Spec: 003-intent
Component: U:Intents (Intent Broker)
Status: Specification Phase

Overview

This checklist defines comprehensive testing requirements for the Intent Broker (U:Intents) component. All tests follow the no-mocking policy and use real implementations.

Total Test Cases: 330+ checkboxes

Unit Tests (120+ tests)

IntentParser Tests (30 tests)

File: tests/test_intent_parser.py

Basic Parsing Tests

[ ] Test parse simple READ action ("read file test.py")
[ ] Test parse simple WRITE action ("create file test.py")
[ ] Test parse simple DELETE action ("delete file test.py")
[ ] Test parse simple EXECUTE action ("run script deploy.sh")
[ ] Test parse simple QUERY action ("search for users")
[ ] Test parse FILE target ("read file config.yaml")
[ ] Test parse CODE target ("generate function calculate")
[ ] Test parse DATABASE target ("query database users")
[ ] Test parse API target ("call API endpoint /users")
[ ] Test parse SYSTEM target ("check system status")

Parameter Extraction Tests

[ ] Test extract file name parameter ("read file test.py" → filename="test.py")
[ ] Test extract file path parameter ("read file /etc/config.yaml")
[ ] Test extract multiple parameters ("create file test.py with content 'hello'")
[ ] Test extract numeric parameters ("query database limit 100")
[ ] Test extract boolean parameters ("deploy app with force true")
[ ] Test extract list parameters ("read files test.py, config.yaml")
[ ] Test extract nested parameters ("create file in directory src/")
[ ] Test missing parameters trigger clarification
[ ] Test ambiguous parameters trigger clarification
[ ] Test invalid parameters raise validation error

Constraint Parsing Tests

[ ] Test parse permission constraint ("read file if authorized")
[ ] Test parse time constraint ("execute at 10:00")
[ ] Test parse condition constraint ("update if version > 1.0")
[ ] Test parse limit constraint ("query maximum 100 results")
[ ] Test parse multiple constraints
[ ] Test constraint validation
[ ] Test constraint conflict detection
[ ] Test constraint precedence rules
[ ] Test constraint override policies
[ ] Test constraint inheritance

IntentValidator Tests (30 tests)

File: tests/test_intent_validator.py

Validation Success Tests

[ ] Test valid READ intent passes validation
[ ] Test valid WRITE intent passes validation
[ ] Test valid DELETE intent passes validation
[ ] Test valid EXECUTE intent passes validation
[ ] Test valid QUERY intent passes validation
[ ] Test intent with authorized requester passes
[ ] Test intent with accessible target passes
[ ] Test intent with valid parameters passes
[ ] Test intent within rate limit passes
[ ] Test intent with valid constraints passes

Validation Failure Tests

[ ] Test unauthorized action fails validation
[ ] Test inaccessible target fails validation
[ ] Test invalid parameters fail validation
[ ] Test rate limit exceeded fails validation
[ ] Test unknown requester fails validation
[ ] Test blacklisted pattern fails validation
[ ] Test SQL injection attempt fails validation
[ ] Test command injection attempt fails validation
[ ] Test path traversal attempt fails validation
[ ] Test malformed intent fails validation

Prolog Integration Tests

[ ] Test validation queries Prolog correctly
[ ] Test Prolog response parsed correctly
[ ] Test Prolog error handled gracefully
[ ] Test Prolog timeout handled
[ ] Test Prolog connection failure handled
[ ] Test validation result cached correctly
[ ] Test cache hit reduces latency
[ ] Test cache invalidation works
[ ] Test cache TTL expires correctly
[ ] Test validation logging records all decisions

IntentRouter Tests (30 tests)

File: tests/test_intent_router.py

Basic Routing Tests

[ ] Test FILE/READ routes to VizInt
[ ] Test FILE/WRITE routes to VizInt
[ ] Test CODE/WRITE routes to VizInt
[ ] Test DATABASE/QUERY routes to Architect
[ ] Test SYSTEM/EXECUTE routes to Orchestrator
[ ] Test API/QUERY routes to Architect
[ ] Test complex intent routes to multiple Volks
[ ] Test routing respects Prolog rules
[ ] Test routing uses correct Volk alias
[ ] Test routing creates CXP packet correctly

Load Balancing Tests

[ ] Test round-robin load balancing works
[ ] Test least-loaded load balancing works
[ ] Test load balancing distributes evenly
[ ] Test unavailable Volk skipped in rotation
[ ] Test overloaded Volk skipped in selection
[ ] Test load metrics tracked correctly
[ ] Test capacity checks performed
[ ] Test queue size influences selection
[ ] Test CPU usage influences selection
[ ] Test priority routing overrides load balancing

Fallback and Error Tests

[ ] Test fallback routing on primary failure
[ ] Test secondary Volk selected correctly
[ ] Test tertiary Volk selected if needed
[ ] Test routing failure marked correctly
[ ] Test routing retry logic works
[ ] Test routing timeout handled
[ ] Test routing to non-existent Volk fails gracefully
[ ] Test routing logs all decisions
[ ] Test routing metrics tracked
[ ] Test routing error reported to requester

Intent Lifecycle Tests (30 tests)

File: tests/test_intent_lifecycle.py

State Transition Tests

[ ] Test intent starts in PENDING state
[ ] Test PENDING → VALIDATED transition succeeds
[ ] Test VALIDATED → EXECUTING transition succeeds
[ ] Test EXECUTING → COMPLETED transition succeeds
[ ] Test EXECUTING → FAILED transition succeeds
[ ] Test PENDING → FAILED transition (validation failure)
[ ] Test invalid transition PENDING → COMPLETED fails
[ ] Test invalid transition VALIDATED → PENDING fails
[ ] Test invalid transition COMPLETED → EXECUTING fails
[ ] Test state transition publishes event

Timestamp Tests

[ ] Test created_at set on intent creation
[ ] Test validated_at set on validation success
[ ] Test completed_at set on completion
[ ] Test timestamps in chronological order
[ ] Test timestamp precision (milliseconds)
[ ] Test timestamp timezone (UTC)
[ ] Test duration calculated correctly
[ ] Test timeout detected based on timestamps
[ ] Test stale intent detection
[ ] Test intent expiry based on age

Status Query Tests

[ ] Test query all PENDING intents
[ ] Test query all EXECUTING intents
[ ] Test query all COMPLETED intents
[ ] Test query all FAILED intents
[ ] Test query by requester ID
[ ] Test query by action type
[ ] Test query by target type
[ ] Test query by date range
[ ] Test query with pagination
[ ] Test query performance (<100ms)

Integration Tests (80+ tests)

Prolog Integration Tests (20 tests)

File: tests/integration/test_prolog_intent.py

Validation Integration

[ ] Test validate_intent/4 predicate with real Prolog
[ ] Test can_perform_action/3 predicate
[ ] Test has_target_access/3 predicate
[ ] Test check_rate_limit/2 predicate
[ ] Test authorize_intent/3 predicate
[ ] Test validation with complex rules
[ ] Test validation with nested rules
[ ] Test validation with rule updates (hot-reload)
[ ] Test validation error handling
[ ] Test validation performance (1000 queries <50ms)

Routing Integration

[ ] Test route_intent/3 predicate with real Prolog
[ ] Test volk_can_handle/3 predicate
[ ] Test routing with multiple candidates
[ ] Test routing with no candidates
[ ] Test routing with priority rules
[ ] Test routing with capacity constraints
[ ] Test routing with custom rules
[ ] Test routing rule updates (hot-reload)
[ ] Test routing error handling
[ ] Test routing performance (1000 queries <20ms)

CXP Protocol Integration Tests (20 tests)

File: tests/integration/test_intent_cxp.py

Packet Conversion Tests

[ ] Test intent_to_cxp() creates valid packet
[ ] Test CXP packet includes all intent data
[ ] Test CXP headers populated correctly
[ ] Test CXP packet serializes to JSON
[ ] Test CXP packet deserializes from JSON
[ ] Test CXP packet validation succeeds
[ ] Test CXP packet with invalid header fails validation
[ ] Test CXP packet with missing field fails validation
[ ] Test CXP packet size within limits
[ ] Test CXP packet compression works

Delivery Integration Tests

[ ] Test CXP packet delivered to Postman
[ ] Test delivery tracking updated
[ ] Test delivery acknowledgment received
[ ] Test delivery failure handled
[ ] Test delivery retry succeeds
[ ] Test delivery timeout triggers failure
[ ] Test delivery to multiple Volks succeeds
[ ] Test delivery logging works
[ ] Test delivery metrics tracked
[ ] Test end-to-end intent delivery (<200ms)

History and Replay Tests (20 tests)

File: tests/integration/test_intent_history.py

History Storage Tests

[ ] Test intent stored in history
[ ] Test history persisted to disk
[ ] Test history survives restart
[ ] Test 10000 intents stored successfully
[ ] Test history storage performance
[ ] Test history compression works
[ ] Test history retention policy applied
[ ] Test old intents deleted correctly
[ ] Test history backup created
[ ] Test history restored from backup

History Query Tests

[ ] Test search by requester ID
[ ] Test search by action type
[ ] Test search by target type
[ ] Test search by date range
[ ] Test search with multiple filters
[ ] Test search with pagination (page 1, 2, 3)
[ ] Test search performance (10000 intents <200ms)
[ ] Test export to JSON
[ ] Test export to CSV
[ ] Test import from JSON

Workflow Integration Tests (20 tests)

File: tests/integration/test_intent_workflow.py

Sequential Workflow Tests

[ ] Test workflow with 3 sequential intents
[ ] Test workflow executes in correct order
[ ] Test workflow waits for each intent completion
[ ] Test workflow state persists across restarts
[ ] Test workflow cancellation stops execution
[ ] Test workflow failure handling
[ ] Test workflow retry on failure
[ ] Test workflow rollback on failure
[ ] Test workflow logging tracks all steps
[ ] Test workflow metrics track duration

Parallel Workflow Tests

[ ] Test workflow with 3 parallel intents
[ ] Test parallel intents execute concurrently
[ ] Test parallel workflow completes faster
[ ] Test parallel workflow waits for all completions
[ ] Test parallel workflow handles partial failures
[ ] Test workflow with mixed serial/parallel steps
[ ] Test workflow dependency graph correct
[ ] Test workflow visualization generated
[ ] Test workflow performance (100 intents <10s)
[ ] Test workflow stress test (1000 intents)

Contract Tests (40 tests)

Intent Schema Tests (20 tests)

File: tests/contract/test_intent_schema.py

Required Fields Tests

[ ] Test intent with all required fields valid
[ ] Test intent without ID fails validation
[ ] Test intent without action fails validation
[ ] Test intent without target fails validation
[ ] Test intent without requester fails validation
[ ] Test intent without created_at fails validation
[ ] Test intent with empty ID fails validation
[ ] Test intent with empty requester fails validation
[ ] Test intent with null action fails validation
[ ] Test intent with null target fails validation

Field Type Tests

[ ] Test action must be IntentAction enum
[ ] Test target must be IntentTarget enum
[ ] Test status must be IntentStatus enum
[ ] Test created_at must be datetime
[ ] Test parameters must be dict
[ ] Test constraints must be list
[ ] Test invalid action value fails
[ ] Test invalid target value fails
[ ] Test invalid status value fails
[ ] Test invalid timestamp format fails

CXP Packet Schema Tests (20 tests)

File: tests/contract/test_cxp_schema.py

Header Validation Tests

[ ] Test CXP packet with all headers valid
[ ] Test packet without TO header fails
[ ] Test packet without FROM header fails
[ ] Test packet without THREAD_ID fails
[ ] Test packet without SUBJECT fails
[ ] Test packet with invalid TO format fails
[ ] Test packet with invalid FROM format fails
[ ] Test packet with empty THREAD_ID fails
[ ] Test packet with null SUBJECT fails
[ ] Test packet header case-insensitive

Body Validation Tests

[ ] Test packet body includes intent data
[ ] Test packet body serializable to JSON
[ ] Test packet body deserializable from JSON
[ ] Test packet body size within limits (<10KB)
[ ] Test packet body compression optional
[ ] Test packet body with large data handled
[ ] Test packet body with binary data fails
[ ] Test packet body with special chars handled
[ ] Test packet body schema versioned
[ ] Test packet body backward compatible

Performance Tests (60+ tests)

Latency Tests (20 tests)

File: tests/performance/test_intent_latency.py

Parsing Latency Tests

[ ] Test parse single intent <100ms (p50)
[ ] Test parse single intent <200ms (p95)
[ ] Test parse single intent <500ms (p99)
[ ] Test parse 100 intents average <100ms
[ ] Test parse complex intent <150ms
[ ] Test parse with parameters <120ms
[ ] Test parse with constraints <130ms
[ ] Test parse ambiguous intent <200ms
[ ] Test parse cache hit <10ms
[ ] Test parse cold start <500ms

Validation Latency Tests

[ ] Test validate single intent <50ms (p50)
[ ] Test validate single intent <100ms (p95)
[ ] Test validate single intent <200ms (p99)
[ ] Test validate 100 intents average <50ms
[ ] Test validate with Prolog query <60ms
[ ] Test validate cache hit <5ms
[ ] Test validate complex rules <80ms
[ ] Test validate authorization <40ms
[ ] Test validate rate limit <30ms
[ ] Test validate cold start <200ms

Throughput Tests (20 tests)

File: tests/performance/test_intent_throughput.py

Intent Processing Throughput

[ ] Test process 1000 intents/sec sustained
[ ] Test process 5000 intents/sec burst
[ ] Test process 10000 intents total <10s
[ ] Test throughput scales linearly with CPUs
[ ] Test throughput maintained under load
[ ] Test throughput with concurrent requests
[ ] Test throughput with backpressure
[ ] Test throughput recovery after spike
[ ] Test throughput degradation threshold
[ ] Test throughput monitoring accuracy

Query Throughput

[ ] Test 1000 Prolog queries/sec
[ ] Test 1000 history queries/sec
[ ] Test 1000 routing decisions/sec
[ ] Test query throughput with caching
[ ] Test query throughput without caching
[ ] Test query throughput with connection pool
[ ] Test query concurrency limit
[ ] Test query queue management
[ ] Test query timeout handling
[ ] Test query retry overhead

Scalability Tests (20 tests)

File: tests/performance/test_intent_scalability.py

Horizontal Scalability

[ ] Test 2 Intent Broker instances handle 2x load
[ ] Test 4 instances handle 4x load
[ ] Test 8 instances handle 8x load
[ ] Test load balancing across instances
[ ] Test instance failure handled gracefully
[ ] Test new instance added dynamically
[ ] Test instance removed dynamically
[ ] Test shared state consistency
[ ] Test distributed caching works
[ ] Test cross-instance metrics aggregated

Data Volume Scalability

[ ] Test 10000 intents in history queryable
[ ] Test 100000 intents in history queryable
[ ] Test 1000000 intents in history queryable
[ ] Test history query performance stable
[ ] Test history storage size reasonable
[ ] Test history cleanup maintains performance
[ ] Test history indexing speeds queries
[ ] Test history sharding by date
[ ] Test history archival to cold storage
[ ] Test history restore from archive

Security Tests (30+ tests)

Injection Prevention Tests (10 tests)

File: tests/security/test_intent_injection.py

[ ] Test SQL injection attempt blocked ("'; DROP TABLE users; --")
[ ] Test command injection blocked ("file.txt; rm -rf /")
[ ] Test path traversal blocked ("../../etc/passwd")
[ ] Test LDAP injection blocked (")(uid=))(|(uid=*")
[ ] Test XSS injection blocked ("")
[ ] Test code injection blocked ("import('os').system('ls')")
[ ] Test JSON injection blocked ('{"key": "\"}", "admin": true}')
[ ] Test XML injection blocked ("")
[ ] Test NoSQL injection blocked ('{"$gt": ""}')
[ ] Test injection logging records all attempts

Access Control Tests (10 tests)

File: tests/security/test_intent_access.py

[ ] Test unauthorized requester blocked
[ ] Test valid requester allowed
[ ] Test requester with limited permissions blocked from privileged action
[ ] Test requester token validated
[ ] Test expired token rejected
[ ] Test invalid token rejected
[ ] Test token refresh works
[ ] Test token revocation prevents access
[ ] Test role-based access control enforced
[ ] Test access logging records all attempts

Rate Limiting Tests (10 tests)

File: tests/security/test_intent_rate_limit.py

[ ] Test rate limit enforced (10 intents/minute)
[ ] Test rate limit exceeded blocks request
[ ] Test rate limit resets after window
[ ] Test rate limit per requester enforced
[ ] Test rate limit bypass for admin
[ ] Test rate limit distributed across instances
[ ] Test rate limit metrics tracked
[ ] Test rate limit alert triggered
[ ] Test rate limit backoff implemented
[ ] Test rate limit configuration reloaded

Summary

Total Test Cases: 330+

Test Category	Test Count	Priority
Unit Tests	120	P0
Integration Tests	80	P0
Contract Tests	40	P1
Performance Tests	60	P1
Security Tests	30	P0

Test Coverage Target: 95% line coverage, 90% branch coverage

Test Execution Time Target: <5 minutes for full suite

Test Stability Target: <1% flakiness rate

Test Infrastructure

Required Test Dependencies

[ ] pytest with asyncio plugin
[ ] Real Prolog instance (SWI-Prolog)
[ ] Real Redis instance (for caching)
[ ] Real PostgreSQL instance (for history)
[ ] Test data generators
[ ] Performance monitoring tools
[ ] Security scanning tools
[ ] Coverage reporting tools

Test Fixtures

[ ] prolog_instance fixture (session scope)
[ ] redis_instance fixture (session scope)
[ ] postgres_instance fixture (session scope)
[ ] intent_broker fixture (function scope)
[ ] sample_intents fixture (1000 test intents)
[ ] test_requester fixture (authenticated)
[ ] test_volks fixture (mock Volk instances)
[ ] test_config fixture (test configuration)

CI/CD Integration

[ ] All tests run in CI/CD pipeline
[ ] Tests run on every commit
[ ] Tests run on every PR
[ ] Performance tests run nightly
[ ] Security tests run weekly
[ ] Coverage reports published
[ ] Test results archived
[ ] Flaky tests quarantined

Last Updated: 2026-01-15
Author: Mohamed
Status: Initial Specification

Other tracked files

specs/003-intent/compliance-audit.md
specs/003-intent/prompt.md
specs/003-intent/review-2026-03-25.md

Full spec text

Verbatim from specs/003-intent/spec.md; headings are pushed down two levels.

SPEC-003: Intent Broker (U:Intents)

Metadata

Spec ID: 003-intent
Title: Intent Broker
Alias: U:Intents, U:Ox (Orchestrator)
Author: Mohamed
Status: Complete
Created: 2026-01-15
Last Updated: 2026-01-19
Priority: P0
Components: Intent Parser, Intent Validator, Intent Router

Overview

What

Why

Bridge between human natural language and agent structured tasks
Central intent validation and routing
Intent lifecycle tracking and history
Reusable intent templates and patterns
Workflow orchestration for complex multi-step operations

How

NLP parsing with action verb and target noun extraction
Prolog validation for governance compliance
Intent routing based on action/target to appropriate Volk
Session-based intent isolation and history

User Scenarios & Stories

US-001: Intent Parsing from Natural Language (Critical)

As a user I want to express my intent in natural language So that the system understands what I want

Acceptance Criteria:

Parse simple action statements ("create a file named test.py")
Parse compound statements ("read config.yaml and update database")
Extract action verbs (READ, WRITE, DELETE, EXECUTE, QUERY)
Extract target nouns (FILE, CODE, DATABASE, API, SYSTEM)
Identify parameters (file names, values, options)
Recognize constraints (permissions, limits, conditions)
Handle ambiguous intents with clarification requests
Parse incomplete sentences with context
Handle typos and grammatical errors
Parse 1000 intents in <100ms average

US-002: Structured Intent Extraction (Critical)

As a developer I want to represent intents as structured data So that they can be validated and routed programmatically

Acceptance Criteria:

Intent data model with all required fields
JSON serialization/deserialization
Pydantic validation schema
Required fields: id, action, target, requester
Optional fields: parameters, constraints, metadata
Intent versioning for schema evolution
Intent immutability after creation
Intent comparison and hashing for deduplication

US-003: Intent Validation via Prolog (Critical)

As a governance enforcer I want to validate intents against Prolog policies So that only authorized actions are performed

Acceptance Criteria:

All intents validated before routing
Validation checks action permissions
Validation checks target access rights
Validation checks parameter constraints
Validation enforces rate limits
Validation checks requester identity
Failed validation returns detailed reason
Validation results cached for performance
Validate 1000 intents in <50ms average

US-004: Intent Routing to Volks (Critical)

As an Intent Broker I want to route validated intents to appropriate Volks So that work is distributed correctly

Acceptance Criteria:

Route based on action and target
Routing rules defined in Prolog
Multi-Volk routing for complex intents
Load balancing across Volk instances
Routing failure triggers fallback
Respect Volk availability and capacity
Priority-based dispatch
Route 1000 intents in <20ms average

US-005: Intent Lifecycle Management (High)

As a system administrator I want to track intent lifecycle states So that I can monitor progress and debug failures

Acceptance Criteria:

States: PENDING, VALIDATED, EXECUTING, COMPLETED, FAILED
State transitions tracked with timestamps
Invalid state transitions prevented
State change events published
Lifecycle history stored for audit
Failed intents marked with error details
Completed intents marked with results
Lifecycle statistics (completion rate, avg duration)

US-006: Intent History and Replay (Medium)

As a developer I want to review and replay past intents So that I can reproduce issues

Acceptance Criteria:

All intents stored in persistent history
Search by requester, action, target, date
Filter by status, priority
Intent replay creates new intent with same parameters
Replay validates intent again before execution
Batch replay support
History pagination
Export to JSON/CSV

US-007: Intent Templates and Patterns (Medium)

As a user I want to use intent templates So that I can work more efficiently

Acceptance Criteria:

Templates for common patterns
Parameter substitution support
Template validation at definition
Searchable template library
Custom user templates
Template versioning
Template composition
Template preview

US-008: Multi-Intent Workflows (Medium)

As a user I want to chain intents into workflows So that I can execute complex operations

Acceptance Criteria:

Workflow as sequence of intents
Dependency order execution
Parallel execution of independent intents
Failure handling (retry, rollback, continue)
Workflow state persistence
Workflow cancellation
Progress tracking
Conditional branching and loops
Execute 100 intents in <10 seconds

US-009: Intent Monitoring and Metrics (High)

As a system administrator I want to monitor intent processing So that I can ensure performance

Acceptance Criteria:

Intent metrics: count, latency, success rate
Breakdown by action, target, requester
Real-time metrics dashboard
Prometheus/Grafana export
Alerting on thresholds
Metrics retention policy
Historical queries

US-010: Intent Security and Access Control (Critical)

As a security officer I want to secure intents So that unauthorized actions are prevented

Acceptance Criteria:

Requester identity verification
Authentication using tokens/credentials
Authorization via Prolog policies
Encryption for sensitive data
Intent signing to prevent tampering
Security audit logging
Injection prevention (SQL, command, path)
Rate limiting per requester
Intent blacklist for malicious patterns

Functional Requirements

See checklists/requirements.md for 250+ detailed requirements.

Intent Data Model

class Intent:
    id: str                       # Unique identifier
    action: IntentAction          # READ, WRITE, DELETE, etc.
    target: IntentTarget          # FILE, CODE, DATABASE, etc.
    requester: str                # Who submitted
    parameters: Dict[str, Any]    # Action parameters
    constraints: List[Constraint] # Limitations
    status: IntentStatus          # PENDING, VALIDATED, etc.
    created_at: datetime
    updated_at: datetime

Technical Design

Architecture

┌─────────────────────────────────────────────────────────┐
│              U:Intents - Intent Broker                   │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Intent    │  │   Intent    │  │   Intent    │     │
│  │   Parser    │  │   Validator │  │   Router    │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
│         │                │                │             │
│  ┌──────┴──────┐  ┌──────┴──────┐  ┌──────┴──────┐     │
│  │   Intent    │  │   Intent    │  │   Workflow  │     │
│  │   History   │  │   Templates │  │   Engine    │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
├─────────────────────────────────────────────────────────┤
│  Prolog (Validation)  │  Redis (State)  │  Neo4j (History)│
└─────────────────────────────────────────────────────────┘

Intent Actions

class IntentAction(Enum):
    READ = "read"
    WRITE = "write"
    DELETE = "delete"
    EXECUTE = "execute"
    QUERY = "query"
    CREATE = "create"
    UPDATE = "update"

Intent Targets

class IntentTarget(Enum):
    FILE = "file"
    CODE = "code"
    DATABASE = "database"
    API = "api"
    SYSTEM = "system"
    CONFIG = "config"

Integration Points

Component	Integration
orchestrata-kernel	Volk discovery and routing
orchestrata-governance	Prolog validation
orchestrata-cxp	Intent packet transmission
orchestrata-session	Session-scoped intents
orchestrata-knowledge	Intent history storage

Success Criteria

Parsing: Handle 90%+ of natural language inputs
Validation: <50ms average validation time
Routing: <20ms average routing time
Accuracy: 99%+ correct routing decisions
Security: Zero unauthorized intent executions

Dependencies

orchestrata-core (enums, interfaces)
orchestrata-kernel (Volk registry)
orchestrata-governance (Prolog validation)
orchestrata-cxp (packet format)
orchestrata-session (intent isolation)

Revision History

Date	Version	Author	Changes
2026-03-07	1.0	Mohamed	Initial specification