Orchestrata Ultimate › Plans › semantic_graph_qa_results_latest

Semantic Graph Q&A Results (Latest: Hybrid Vector + Keyword + Module Graph)

Source: plans/semantic_graph_qa_results_latest.md at 8a2cb42ad · last changed 2026-08-19 · first committed 2026-07-08 · 864 lines.

Prose pending.

Plan text

Semantic Graph Q&A Results (Latest: Hybrid Vector + Keyword + Module Graph)

Model: mistralai/codestral-embed-2505 | Reranker: cohere/rerank-4-pro | Project: orchestrata-ultimate

Average keyword coverage: 72% Low-quality answers (<50%): 16/100

Q1: Why must the Gateway never serve HTML, JS, or CSS?

Category: Architecture & Design Keywords: gateway, never, serve, html Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:1-50 — # AGENTS.md — Guide for AI Coding Agents > Read this before executing any step of the execution plan. > ## ⛔ CRITICAL — NEVER use pytest-xdist (-n / --dist) > pytest -n auto (xdist) deadlocks this suite (~78% stall) and is banned. > Run tests ONLY via the supported runners: > - python scripts/run_tests.py — primary: infra check + safety gates + batched executor (~7 min) >...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:586-635 — bash python scripts/start_test_services.py # Start all services python scripts/start_test_services.py --status # Check only (exit 0 even if down) python scripts/start_test_services.py --json # JSON report python scripts/start_test_services.py --skip kernel,gateway # Skip services scripts/run_tests.py auto-starts all services before tests. Use `--skip-services kern...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:631-680 — 2. VizInt bridge connects to gateway — The browser's WebSocketBridge connects via localStorage.setItem('vizint.gateway.url', ...) for E2E test dynamic port configuration. 3. gRPC kernel is out-of-process — Gateway connects to kernel via gRPC on port 50053. If unreachable, logs clear warning and falls back to PipelineKernelClient. 4. Three-tier gRPC logging — Unconfigured → INF...

Q2: How does VizInt UI communicate with the Gateway if they run on different ports?

Category: Architecture & Design Keywords: vizint, communicate, gateway, different, ports Coverage: 60%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:1-50 — # AGENTS.md — Guide for AI Coding Agents > Read this before executing any step of the execution plan. > ## ⛔ CRITICAL — NEVER use pytest-xdist (-n / --dist) > pytest -n auto (xdist) deadlocks this suite (~78% stall) and is banned. > Run tests ONLY via the supported runners: > - python scripts/run_tests.py — primary: infra check + safety gates + batched executor (~7 min) >...
/home/mohamed/workspace/orchestrata-ultimate-architecture/architecture/integration-architecture.md:1-50 — # Integration Architecture — CheetahClaws + VizInt + Gateway + Agents > Date: 2026-06-26 > Specs: SPEC-050 (CheetahClaws), SPEC-016 (VizInt), SPEC-014 (Gateway), SPEC-003 (Intent) > Components: UltimateTUI, MultiAgentCoordinator, GovernanceBridge, UltimateTUIHandler, PipelineRunner --- ## Complete System Architecture ```mermaid graph TB subgraph "User Interfaces (Layer 5)" ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:586-635 — ### The real bridge The browser side is vizint-ui/bridge/websocket-bridge.js — a JSON-RPC 2.0 client over a real WebSocket (request/response correlation, subscriptions, auth-first connect, auto-reconnect). There is no test variant: e2e tests import('/bridge/websocket-bridge.js') inside page.evaluate() and point it at the live gateway, exactly as the production UI does. The gateway closes ...

Q3: What is the exact port and protocol for each service: VizInt UI, Gateway, Kernel, Redis, Neo4j?

Category: Architecture & Design Keywords: exact, port, protocol, service, vizint, gateway, kernel, redis Coverage: 88%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:1-50 — # AGENTS.md — Guide for AI Coding Agents > Read this before executing any step of the execution plan. > ## ⛔ CRITICAL — NEVER use pytest-xdist (-n / --dist) > pytest -n auto (xdist) deadlocks this suite (~78% stall) and is banned. > Run tests ONLY via the supported runners: > - python scripts/run_tests.py — primary: infra check + safety gates + batched executor (~7 min) >...
/home/mohamed/workspace/orchestrata-ultimate-architecture/README.md:1-50 — # Orchestrata Ultimate A spec-driven, multi-agent software-engineering system where a human states an intent and autonomous volks (specialist agents) collaborate to design, build, verify, and document real software on real LLMs. > Vision: Turn natural-language intent into production-ready, tested, > traceable code — with human oversight, not human labor. --- ## 1. What is Orchestrata U...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:541-590 — REDIS_HOST=10.92.53.10 REDIS_PORT=6379 NEO4J_URI=bolt://10.92.53.11:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=«redacted» **Loading is automatic** via `.envrc` + direnv. If direnv is unavailable, run:bash export $(cat .env | grep -v '^#' | xargs) **Code must read from env vars with localhost fallback:** python # Correct — tests and source REDIS_HOST = os.environ.get("REDIS_HOST",...

Q4: Why is the gRPC kernel required to be out-of-process from the Gateway?

Category: Architecture & Design Keywords: grpc, kernel, required, process, gateway Coverage: 80%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/orchestrator/pipeline_kernel.py:1-50 — """Pipeline Kernel Client — bridges Gateway → PipelineRunner. Implements the same send_packet(CXPPacket) interface as GRPCClient so the gateway can dispatch intents from the VizInt UI to the local PipelineRunner instead of requiring an out-of-process gRPC kernel. When the gateway is running without a gRPC endpoint, it falls back to this in-process client which runs the full agent pipelin...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:631-680 — 2. VizInt bridge connects to gateway — The browser's WebSocketBridge connects via localStorage.setItem('vizint.gateway.url', ...) for E2E test dynamic port configuration. 3. gRPC kernel is out-of-process — Gateway connects to kernel via gRPC on port 50053. If unreachable, logs clear warning and falls back to PipelineKernelClient. 4. Three-tier gRPC logging — Unconfigured → INF...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/agents/kernel_handler.py:1-50 — """Packet handler that drives the volk engine for the live CXP gRPC kernel. agents/runtime_main.py starts a :class:CXPServer for the out-of-process kernel (the agent-runtime service). This module builds the packet_handler that the server invokes for each received packet: it boots a :class:~orchestrata_ultimate.kernel.pipeline.PipelineRunner (all 9 volks on a real Postman) **on...

Q5: What is the fallback when the gRPC kernel is unreachable?

Category: Architecture & Design Keywords: fallback, grpc, kernel, unreachable Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/gateway/server.py:541-590 — GRPCClientConfig, ) kernel_client = GRPCClient( config=GRPCClientConfig(host=host, port=port) ) await kernel_client.connect() # gRPC channels connect lazily: connect() alone never proves # the kernel is actually serving. Verify wit...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/gateway/server.py:496-545 — load_governance_rules(bridge) return PolicyEngine(prolog_client=GovernancePrologClient(bridge)) self._rpc.set_policy_engine_factory(_make_policy_engine) logger.info("Governance PolicyEngine factory registered") # Admin token gating volk.register/deregister (unset -> admin ops denied). self._rpc.set_admin_token(self._config.admin_token) ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/gateway/rpc.py:226-275 — evaluator: An IntentEvaluator instance. """ self._orchestrator.set_evaluator(evaluator) def set_pipeline_client(self, client: Any) -> None: """Inject the in-process pipeline kernel client used as a fallback when no live volk kernel is reachable. Wired into the orchestrator handler (orchestrator.intent -> pipeline stage events)...

Q6: Why are hardcoded service IPs and ports forbidden in this codebase?

Category: Architecture & Design Keywords: hardcoded, service, ports, forbidden, codebase Coverage: 80%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:1-50 — # AGENTS.md — Guide for AI Coding Agents > Read this before executing any step of the execution plan. > ## ⛔ CRITICAL — NEVER use pytest-xdist (-n / --dist) > pytest -n auto (xdist) deadlocks this suite (~78% stall) and is banned. > Run tests ONLY via the supported runners: > - python scripts/run_tests.py — primary: infra check + safety gates + batched executor (~7 min) >...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:541-590 — REDIS_HOST=10.92.53.10 REDIS_PORT=6379 NEO4J_URI=bolt://10.92.53.11:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=«redacted» **Loading is automatic** via `.envrc` + direnv. If direnv is unavailable, run:bash export $(cat .env | grep -v '^#' | xargs) **Code must read from env vars with localhost fallback:** python # Correct — tests and source REDIS_HOST = os.environ.get("REDIS_HOST",...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/cxp/endpoint_config.py:1-50 — """Single source of truth for CXP gRPC endpoint configuration. Ports are read from the environment (ultimately from .env) at call time, with no hardcoded numeric default anywhere — a missing port raises rather than silently falling back, so the port lives in exactly one place and cannot drift between the kernel, the dispatcher, the harness, and the deployment manifests. Host values are *...

Q7: How does the project enforce the rule against `except: pass` and `except Exception: pass`?

Category: Architecture & Design Keywords: project, enforce, rule, against, except, pass, exception Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/faq/bare-except-handlers.md:1-13 — --- title: How does the project enforce the rule against bare exception handlers? description: Enforcement mechanism for the ban on silent exception handlers. --- # How does the project enforce the rule against bare exception handlers? The rule against except: pass and except Exception: pass is enforced in two places: 1. Static review: `src/orchestrata_ultimate/verification/review/check...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/faq/silent-exception-handlers.md:1-8 — --- title: What is the rule about silent exception handlers? description: The project rule that forbids swallowing exceptions. --- # What is the rule about silent exception handlers? Never use except: pass or except Exception: pass. Every exception handler must either log the actual error with context or re-raise the exception. This rule is checked by `verification/review/checks_structure.py...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/agents/volks/codedirector/review_checks.py:676-725 — (r"from\s+unittest\s+import\s+mock", "unittest import mock"), (r"Mock\s*(", "Mock() instantiation"), (r"MagicMock\s*(", "MagicMock() instantiation"), (r"AsyncMock\s*(", "AsyncMock() instantiation"), (r"@\s*(mock.)?patch\s*(", "@patch decorator"), (r"mocker.(patch|spy|stub|mock)\s*(", "pytest-mock usage"), (r"create_autospec\s*(", "create_autospec()"), (r"pat...

Q8: What is the three-tier gRPC logging policy for the Gateway?

Category: Architecture & Design Keywords: three, tier, grpc, logging, policy, gateway Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:631-680 — 2. VizInt bridge connects to gateway — The browser's WebSocketBridge connects via localStorage.setItem('vizint.gateway.url', ...) for E2E test dynamic port configuration. 3. gRPC kernel is out-of-process — Gateway connects to kernel via gRPC on port 50053. If unreachable, logs clear warning and falls back to PipelineKernelClient. 4. Three-tier gRPC logging — Unconfigured → INF...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/CODEBASE_MAP_FULL.md:2746-2795 — src/orchestrata_ultimate/gateway/exceptions.py:14: class ConnectionLifecycleError(GatewayError) src/orchestrata_ultimate/gateway/exceptions.py:18: class RPCError(GatewayError) src/orchestrata_ultimate/gateway/exceptions.py:26: def init(self, message: str, rpc_code: int=-32603) -> None src/orchestrata_ultimate/gateway/exceptions.py:41: class RingBufferError(GatewayError) src/orchestrata_ultimat...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/kernel/audit/logger.py:271-320 — }, duration_ms=duration_ms, ) await self.log(entry) @traces(spec="001", story="US-008", reqs=["REQ-008-002"]) async def log_policy_query( self, session_id: str, volk_id: str, query: str, result: str, cached: bool, correlation_id: str | None = None, duration_ms: int | None = None, ) ...

Q9: How does the Gateway health check authenticate instead of bypassing auth?

Category: Architecture & Design Keywords: gateway, health, check, authenticate, instead, bypassing, auth Coverage: 43%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/gateway/handlers/auth.py:1-50 — """Auth RPC handler -- authenticate. Implements SPEC-014 auth.authenticate method. """ from typing import Any from orchestrata_ultimate.core.base.traces import traces from orchestrata_ultimate.gateway.auth import TokenAuthenticator from orchestrata_ultimate.gateway.config import GatewayConfig from orchestrata_ultimate.gateway.exceptions import AuthenticationError from orchestrata_ultimate.gatew...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/gateway/auth_handler.py:136-185 — """Handle JSON-RPC 2.0 authentication message. Args: websocket: The websockets connection object. conn_id: Connection identifier. data: Parsed JSON-RPC message dict. config: Gateway configuration. auth: Token authenticator — the SAME validator the WSMessage AUTH path uses. This path previously fabricated a user id and returne...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:586-635 — ### The real bridge The browser side is vizint-ui/bridge/websocket-bridge.js — a JSON-RPC 2.0 client over a real WebSocket (request/response correlation, subscriptions, auth-first connect, auto-reconnect). There is no test variant: e2e tests import('/bridge/websocket-bridge.js') inside page.evaluate() and point it at the live gateway, exactly as the production UI does. The gateway closes ...

Q10: What is the PID file protocol for long-running services?

Category: Architecture & Design Keywords: file, protocol, long, running, services Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:586-635 — bash python scripts/start_test_services.py # Start all services python scripts/start_test_services.py --status # Check only (exit 0 even if down) python scripts/start_test_services.py --json # JSON report python scripts/start_test_services.py --skip kernel,gateway # Skip services scripts/run_tests.py auto-starts all services before tests. Use `--skip-services kern...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:226-275 — | Neo4j | bolt://10.92.53.11:7687 | neo4j-db | The single source of truth is .env at the repo root, loaded automatically via .envrc + direnv (AGENTS.md:469-483). tests/conftest.py:33-35 loads .env with override=True before any test imports, then fast-fails if any of these are missing or empty (tests/conftest.py:42-54): ``` REDIS_HOST REDIS_PORT NEO4J_URI NEO4J_USE...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:46-95 — ### Service Management Protocols | Protocol | Pattern | |----------|---------| | PID file | Write on start, validate with os.kill(pid, 0) | | Health check | Application-level (e.g. gateway.ping RPC), not just port | | Readiness | Wait for health check response, not just TCP accept | | Graceful shutdown | SIGTERM → drain 10s → SIGKILL → cleanup PID | | Idempotent start | Check PID + port + he...

Q11: Why must readiness wait for an application-level health check rather than just TCP accept?

Category: Architecture & Design Keywords: readiness, wait, application, level, health, check, rather, just Coverage: 88%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:46-95 — ### Service Management Protocols | Protocol | Pattern | |----------|---------| | PID file | Write on start, validate with os.kill(pid, 0) | | Health check | Application-level (e.g. gateway.ping RPC), not just port | | Readiness | Wait for health check response, not just TCP accept | | Graceful shutdown | SIGTERM → drain 10s → SIGKILL → cleanup PID | | Idempotent start | Check PID + port + he...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/gateway/http_surface.py:46-86 — @app.get("/health") @traces(spec="014", story="US-009", reqs=["REQ-014-136"]) async def health() -> dict[str, Any]: return {"status": "alive"} @app.get("/ready") @traces(spec="014", story="US-009", reqs=["REQ-014-140"]) async def ready(response: Response) -> dict[str, Any]: # Gateway-level readiness first — if the WS server has not started, # report...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/gateway/http_surface.py:1-50 — """Gateway HTTP surface — /health, /ready, /metrics. The gateway is a WebSocket server; SPEC-014 FR-021 additionally requires a small HTTP surface for liveness/readiness probes (k8s/load-balancer friendly) and Prometheus metrics scraping. This module builds that FastAPI app and serves it alongside the WS server. It reuses the existing postman.health HealthChecker (real Redis/Neo4j...

Q12: What is the graceful shutdown sequence for services?

Category: Architecture & Design Keywords: graceful, shutdown, sequence, services Coverage: 75%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:226-275 — | Neo4j | bolt://10.92.53.11:7687 | neo4j-db | The single source of truth is .env at the repo root, loaded automatically via .envrc + direnv (AGENTS.md:469-483). tests/conftest.py:33-35 loads .env with override=True before any test imports, then fast-fails if any of these are missing or empty (tests/conftest.py:42-54): ``` REDIS_HOST REDIS_PORT NEO4J_URI NEO4J_USE...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:586-635 — bash python scripts/start_test_services.py # Start all services python scripts/start_test_services.py --status # Check only (exit 0 even if down) python scripts/start_test_services.py --json # JSON report python scripts/start_test_services.py --skip kernel,gateway # Skip services scripts/run_tests.py auto-starts all services before tests. Use `--skip-services kern...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:46-95 — ### Service Management Protocols | Protocol | Pattern | |----------|---------| | PID file | Write on start, validate with os.kill(pid, 0) | | Health check | Application-level (e.g. gateway.ping RPC), not just port | | Readiness | Wait for health check response, not just TCP accept | | Graceful shutdown | SIGTERM → drain 10s → SIGKILL → cleanup PID | | Idempotent start | Check PID + port + he...

Q13: How is idempotent start implemented for test services?

Category: Architecture & Design Keywords: idempotent, start, implemented, test, services Coverage: 80%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:586-635 — bash python scripts/start_test_services.py # Start all services python scripts/start_test_services.py --status # Check only (exit 0 even if down) python scripts/start_test_services.py --json # JSON report python scripts/start_test_services.py --skip kernel,gateway # Skip services scripts/run_tests.py auto-starts all services before tests. Use `--skip-services kern...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:226-275 — | Neo4j | bolt://10.92.53.11:7687 | neo4j-db | The single source of truth is .env at the repo root, loaded automatically via .envrc + direnv (AGENTS.md:469-483). tests/conftest.py:33-35 loads .env with override=True before any test imports, then fast-fails if any of these are missing or empty (tests/conftest.py:42-54): ``` REDIS_HOST REDIS_PORT NEO4J_URI NEO4J_USE...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:46-95 — ### Service Management Protocols | Protocol | Pattern | |----------|---------| | PID file | Write on start, validate with os.kill(pid, 0) | | Health check | Application-level (e.g. gateway.ping RPC), not just port | | Readiness | Wait for health check response, not just TCP accept | | Graceful shutdown | SIGTERM → drain 10s → SIGKILL → cleanup PID | | Idempotent start | Check PID + port + he...

Q14: What action is taken when a port is in use by a foreign process?

Category: Architecture & Design Keywords: action, taken, port, foreign, process Coverage: 60%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:271-320 — | Foreign process detection | Refuses to start if port is in use without matching PID file | | Log file | /tmp/orchestrata-gateway.log (append-only, ready for logrotate) | #### Usage ```bash # Check + start + verify all services (parallel, idempotent) python scripts/start_test_services.py # Check only — never starts, exits 0 even if services are down python scripts/start_test_services...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/governance/resource_access.py:46-95 — story="US-PGOV-004", reqs=[ "REQ-007-FR4-002", "REQ-007-US-004-001", ], ) async def check_file_access(self, actor: str, path: str, mode: str) -> AccessResult: """Check if actor can access a file path with given mode.""" # Reject modes that are not well-formed Prolog atoms. These would # either corrupt the Prolog query or ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/governance/resource_access.py:91-140 — try: allowed = self._prolog_client.bridge.query_bool( f"may_access_network('{actor}', '{domain}', {port})" ) return AccessResult( allowed=allowed, resource=f"{domain}:{port}", mode="connect", reason="prolog_policy" if allowed else "prolog_denied", policy_appli...

Q15: Why must `subprocess.DEVNULL` never be used for service logs?

Category: Architecture & Design Keywords: subprocess, devnull, never, used, service, logs Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:586-635 — bash python scripts/start_test_services.py # Start all services python scripts/start_test_services.py --status # Check only (exit 0 even if down) python scripts/start_test_services.py --json # JSON report python scripts/start_test_services.py --skip kernel,gateway # Skip services scripts/run_tests.py auto-starts all services before tests. Use `--skip-services kern...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/drivers/qwen_driver.py:181-230 — created = await asyncio.to_thread(_scan_source_files, self.workspace) if not created: _logger.warning("No source files created") return False, output or "No files generated" for f in created: _logger.info("Wrote %s", f) _logger.info("Generated %d files", len(created)) return True, output or f"Created {len(created)} file...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/core/threading/test_executor.py:136-185 — PTE_COV_PART_LOG=<path> to append one line per batch child. """ log_path = os.environ.get("PTE_COV_PART_LOG", "") if not log_path: return parts = glob.glob(f".coverage.pid{pid}.") first_test = next((a for a in cmd if a.startswith("tests/")), "?") with contextlib.suppress(OSError): with open(log_path, "a", encoding="utf-8") as fh: fh.wri...

Q16: What does `SessionController.begin()` do automatically regarding unclosed sessions?

Category: Session Lifecycle & CLI Keywords: sessioncontroller, begin, automatically, regarding, unclosed, sessions Coverage: 67%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_CLI_IMPROVEMENTS.md:1-50 — # Session CLI Reference > Note: This document supersedes all previous session CLI documentation. The system described here is the current SessionController in src/orchestrata_ultimate/session/session.py. Any references to scripts/session_cli.py or src/orchestrata_ultimate/core/session.py are for a legacy system that is no longer used. ## Quick Start ```python from orchestrata_ul...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_MANAGEMENT.md:1-50 — # Session Management System ## Overview The Orchestrata Ultimate project uses a session management system built around SessionController in src/orchestrata_ultimate/session/session.py. It tracks work progress, achievements, and handoff data across sessions using context.json (source of truth), context.md (human-readable view), and context.history.md (archived sessions). ## Core Files ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/session/controller/_core.py:136-185 — self._active: SessionRecord | None = None self._lock = threading.Lock() @property @traces(spec="006", story="US-003", reqs=["REQ-006-US-003-001"]) def active_session(self) -> SessionRecord | None: """Get currently active session (thread-safe).""" with self._lock: return self._active @traces( spec="006", story="US-001", ...

Q17: What are the five checklist items validated by `SessionController.validate_and_end()`?

Category: Session Lifecycle & CLI Keywords: five, checklist, items, validated, sessioncontroller, validate_and_end Coverage: 50%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_MANAGEMENT.md:46-95 — choice="Used Pydantic BaseModel over dataclass", reason="Better validation and JSON serialization", ) # 5. Set handoff data for the next session ctrl.set_handoff( decisions=["Switched to janus-swi for Prolog"], blockers=["Neo4j container IP may change after reboot"], active_work=["Porting orchestrata-postman tier 2"], key_files=["src/orchestrata_ultimate/postman/router.py"...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:136-185 — # Set handoff data for next session ctrl.set_handoff( decisions=["Switched to janus-swi for Prolog"], blockers=["Neo4j container IP may change after reboot"], active_work=["Porting orchestrata-postman tier 2"], key_files=["src/orchestrata_ultimate/postman/router.py"], cmds=["python scripts/run_tests.py tests/postman/ --skip-gates"], alerts=["Redis DB isolation requires wor...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/session/controller/_core.py:451-500 — self.ctx.update_session( latest.seq, length=latest.length, achievements=latest.achievements, ) return latest return None def _validate_checklist(self) -> list[str]: """Validate session checklist and return list of failures.""" failures = [] if self._active is None: ...

Q18: How does `SessionController.end()` handle git commits and tags?

Category: Session Lifecycle & CLI Keywords: sessioncontroller, handle, commits, tags Coverage: 75%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_CLI_IMPROVEMENTS.md:46-95 — | log_artifact(filepath, line_count, summary) | Log a file that was created or modified. | | log_choice(choice, reason) | Log a technical decision. | | log_achievement(item) | Append a single achievement string. | ### Handoff & Goals | Method | Purpose | |--------|---------| | set_handoff(decisions, blockers, active_work, key_files, cmds, alerts) | Set handoff data for the next session. ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:136-185 — # Set handoff data for next session ctrl.set_handoff( decisions=["Switched to janus-swi for Prolog"], blockers=["Neo4j container IP may change after reboot"], active_work=["Porting orchestrata-postman tier 2"], key_files=["src/orchestrata_ultimate/postman/router.py"], cmds=["python scripts/run_tests.py tests/postman/ --skip-gates"], alerts=["Redis DB isolation requires wor...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_MANAGEMENT.md:136-184 — 4. Commits the CHANGELOG.md update: git commit -m "Update CHANGELOG.md for session NNN" 5. Creates annotated git tag: session-NNN-YYYY-MM-DD-HHMM 6. Pushes the tag to origin: git push origin session-NNN-... end() does NOT: - Commit your code changes - Push code commits to origin - Run tests or validate checklist (use validate_and_end() for that) ## Session Numbering Session number...

Q19: What is the difference between `end()` and `validate_and_end()`?

Category: Session Lifecycle & CLI Keywords: difference, between, validate_and_end Coverage: 67%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:136-185 — # Set handoff data for next session ctrl.set_handoff( decisions=["Switched to janus-swi for Prolog"], blockers=["Neo4j container IP may change after reboot"], active_work=["Porting orchestrata-postman tier 2"], key_files=["src/orchestrata_ultimate/postman/router.py"], cmds=["python scripts/run_tests.py tests/postman/ --skip-gates"], alerts=["Redis DB isolation requires wor...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_CLI_IMPROVEMENTS.md:46-95 — | log_artifact(filepath, line_count, summary) | Log a file that was created or modified. | | log_choice(choice, reason) | Log a technical decision. | | log_achievement(item) | Append a single achievement string. | ### Handoff & Goals | Method | Purpose | |--------|---------| | set_handoff(decisions, blockers, active_work, key_files, cmds, alerts) | Set handoff data for the next session. ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_MANAGEMENT.md:46-95 — choice="Used Pydantic BaseModel over dataclass", reason="Better validation and JSON serialization", ) # 5. Set handoff data for the next session ctrl.set_handoff( decisions=["Switched to janus-swi for Prolog"], blockers=["Neo4j container IP may change after reboot"], active_work=["Porting orchestrata-postman tier 2"], key_files=["src/orchestrata_ultimate/postman/router.py"...

Q20: What shell command starts a session?

Category: Session Lifecycle & CLI Keywords: shell, command, starts, session Coverage: 50%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/session/cli/lifecycle.py:1-50 — # mypy: ignore-errors """Session lifecycle commands (begin, work, end, resume, summary) for the CLI.""" from future import annotations import sys from collections.abc import Sequence from pathlib import Path from typing import TYPE_CHECKING import click from orchestrata_ultimate.core.base.traces import traces from orchestrata_ultimate.session.models import default_ai_model if TYPE_CHECKIN...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/session/cli/lifecycle.py:46-95 — for obj in session.objectives: click.echo(f" - {obj}") @click.command() @click.argument("desc") @click.option( "--detail", "details", multiple=True, help="Detail bullet (can be repeated)." ) @click.pass_context @traces(spec="006", story="FR-018", reqs=["REQ-006-FR18-005"]) def work(ctx: click.Context, desc: str, details: tuple[str, ...]) -> None: """Log work in the c...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:91-140 — Do NOT run these commands on every turn — only on the first interaction of a new session. --- ## ⚡ Mandatory Startup Checklist (Every Session) Before writing or running any code, verify these items. They are not optional. 1. Infrastructure is configured via .env — Read incus/README.md to understand container setup. Never assume Redis/Neo4j are on localhost. Never hardcode Incus...

Q21: How do you set handoff data for the next session via the CLI?

Category: Session Lifecycle & CLI Keywords: handoff, data, next, session Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/session/cli/lifecycle.py:136-185 — @click.pass_context @traces(spec="006", story="FR-018", reqs=["REQ-006-FR18-005"]) def handoff( ctx: click.Context, decisions: tuple[str, ...], blockers: tuple[str, ...], active_work: tuple[str, ...], key_files: tuple[str, ...], cmds: tuple[str, ...], alerts: tuple[str, ...], ) -> None: """Set handoff data for the next session.""" root = ctx.obj["root"] fro...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:136-185 — # Set handoff data for next session ctrl.set_handoff( decisions=["Switched to janus-swi for Prolog"], blockers=["Neo4j container IP may change after reboot"], active_work=["Porting orchestrata-postman tier 2"], key_files=["src/orchestrata_ultimate/postman/router.py"], cmds=["python scripts/run_tests.py tests/postman/ --skip-gates"], alerts=["Redis DB isolation requires wor...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_CLI_IMPROVEMENTS.md:46-95 — | log_artifact(filepath, line_count, summary) | Log a file that was created or modified. | | log_choice(choice, reason) | Log a technical decision. | | log_achievement(item) | Append a single achievement string. | ### Handoff & Goals | Method | Purpose | |--------|---------| | set_handoff(decisions, blockers, active_work, key_files, cmds, alerts) | Set handoff data for the next session. ...

Q22: What happens to old sessions in `context.md` during `end()`?

Category: Session Lifecycle & CLI Keywords: happens, sessions, context, during Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_CLI_IMPROVEMENTS.md:46-95 — | log_artifact(filepath, line_count, summary) | Log a file that was created or modified. | | log_choice(choice, reason) | Log a technical decision. | | log_achievement(item) | Append a single achievement string. | ### Handoff & Goals | Method | Purpose | |--------|---------| | set_handoff(decisions, blockers, active_work, key_files, cmds, alerts) | Set handoff data for the next session. ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_MANAGEMENT.md:91-140 — ### Goal-Driven Sessions python from orchestrata_ultimate.session.session import SessionController from orchestrata_ultimate.session.models import GoalCriterion ctrl = SessionController(".") # Set a goal with exit criteria ctrl.set_goal( statement="Port orchestrata-postman tier 2", criteria=[ GoalCriterion(id="tests", description="All tests pass", status="pending"), ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:136-185 — # Set handoff data for next session ctrl.set_handoff( decisions=["Switched to janus-swi for Prolog"], blockers=["Neo4j container IP may change after reboot"], active_work=["Porting orchestrata-postman tier 2"], key_files=["src/orchestrata_ultimate/postman/router.py"], cmds=["python scripts/run_tests.py tests/postman/ --skip-gates"], alerts=["Redis DB isolation requires wor...

Q23: Where does the session CHANGELOG get updated?

Category: Session Lifecycle & CLI Keywords: session, changelog, updated Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_CLI_IMPROVEMENTS.md:46-95 — | log_artifact(filepath, line_count, summary) | Log a file that was created or modified. | | log_choice(choice, reason) | Log a technical decision. | | log_achievement(item) | Append a single achievement string. | ### Handoff & Goals | Method | Purpose | |--------|---------| | set_handoff(decisions, blockers, active_work, key_files, cmds, alerts) | Set handoff data for the next session. ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:181-230 — 2. Pushes commits to origin: git push origin <current_branch> 3. Updates context.md and context.json with session data 4. Archives old sessions to context.history.md (keeps last 3 in context.md) 5. Updates CHANGELOG.md under [Unreleased] section (categorized: Added/Fixed/Removed/Changed) 6. Commits the CHANGELOG.md update: git commit -m "Update CHANGELOG.md for session NNN" 7. Create...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/session/controller/_changelog.py:46-95 — "Features": "Added", "Added": "Added", "Fix": "Fixed", "Fixed": "Fixed", "Refactor": "Changed", "Perf": "Changed", "Performance": "Changed", } @traces(spec="020", story="US-001", reqs=["REQ-020-020"]) def _update_changelog(self, session: SessionRecord) -> bool: """Update CHANGELOG.md with session achievements. Ca...

Q24: What is the session git tag format?

Category: Session Lifecycle & CLI Keywords: session, format Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_MANAGEMENT.md:136-184 — 4. Commits the CHANGELOG.md update: git commit -m "Update CHANGELOG.md for session NNN" 5. Creates annotated git tag: session-NNN-YYYY-MM-DD-HHMM 6. Pushes the tag to origin: git push origin session-NNN-... end() does NOT: - Commit your code changes - Push code commits to origin - Run tests or validate checklist (use validate_and_end() for that) ## Session Numbering Session number...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/session/controller/_git.py:91-140 — # Push to current branch branch = self._current_branch() if branch: push = subprocess.run( ["git", "push", "origin", branch], cwd=self.root, capture_output=True, text=True, env=_git_env(runtime_env), ) if push.retur...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/session/controller/_git.py:136-185 — # Format: session-XXX-YYYY-MM-DD-HHMM tag_name = f"session-{session.seq:03d}-{session.when.strftime('%Y-%m-%d-%H%M')}" tag_message = f"Session {session.seq:03d}: {session.purpose}" runtime_env = os.environ if env is None else dict(env) try: result = subprocess.run( ["git", "tag", "-a", tag_name, "-m", tag_message], ...

Q25: Why is it mandatory to log work, artifacts, choices, and handoff before ending?

Category: Session Lifecycle & CLI Keywords: mandatory, work, artifacts, choices, handoff, before, ending Coverage: 86%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_MANAGEMENT.md:46-95 — choice="Used Pydantic BaseModel over dataclass", reason="Better validation and JSON serialization", ) # 5. Set handoff data for the next session ctrl.set_handoff( decisions=["Switched to janus-swi for Prolog"], blockers=["Neo4j container IP may change after reboot"], active_work=["Porting orchestrata-postman tier 2"], key_files=["src/orchestrata_ultimate/postman/router.py"...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_CLI_IMPROVEMENTS.md:46-95 — | log_artifact(filepath, line_count, summary) | Log a file that was created or modified. | | log_choice(choice, reason) | Log a technical decision. | | log_achievement(item) | Append a single achievement string. | ### Handoff & Goals | Method | Purpose | |--------|---------| | set_handoff(decisions, blockers, active_work, key_files, cmds, alerts) | Set handoff data for the next session. ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:136-185 — # Set handoff data for next session ctrl.set_handoff( decisions=["Switched to janus-swi for Prolog"], blockers=["Neo4j container IP may change after reboot"], active_work=["Porting orchestrata-postman tier 2"], key_files=["src/orchestrata_ultimate/postman/router.py"], cmds=["python scripts/run_tests.py tests/postman/ --skip-gates"], alerts=["Redis DB isolation requires wor...

Q26: What is the repository pattern abstraction used to hide Bolt details?

Category: Semantic Graph & RAG Keywords: repository, pattern, abstraction, used, hide, bolt, details Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/README.md:91-140 — ### 3.4 VizInt Command Center Browser-based dashboard with 31+ gadgets across 5 subsystems, bridged to the Gateway via tui.* RPC methods. ### 3.5 Governance & PAM++ A Prolog policy engine enforces rules on every file operation: - No hardcoded IPs or ports. - No except: pass. - No test mocks or stubs. - Architecture boundary checks. - Compliance gate before any merge. ### 3.6 Session Syste...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:1-50 — # Semantic Graph — RAG / GraphRAG backend The semantic_graph package provides a repository-pattern abstraction over a vector + property graph store. It is designed for multi-project RAG: source-code chunks, markdown documentation, and runtime entities are embedded, indexed, and linked so that agents can retrieve context by semantic similarity and graph traversal rather than by grepping files. ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:46-95 — │ ┌───────────────┐ ┌───────────────┐ ┌─────────────────────────┐ │ │ │ VectorStore │ │ GraphStore │ │ retrieve(...) │ │ │ │ add_chunks │ │ upsert_* │ │ 1. vector search │ │ │ │ search_similar│ │ get_neighbors │ │ 2. graph expansion │ │ │ └───────────────┘ └───────────────┘ │ 3. GraphRAGContext │ │ │ └───...

Q27: What are the two embedding backends in `semantic_graph/embedders.py`?

Category: Semantic Graph & RAG Keywords: embedding, backends, semantic_graph, embedders Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/embedders.py:1-50 — """Embedding backends for the semantic graph. Provides a small protocol plus two concrete implementations: * :class:OpenRouterEmbedder - cloud embeddings via OpenRouter (Codestral). * :class:SentenceTransformerEmbedder - local GPU embeddings via sentence-transformers (Qwen3-Embedding, etc.). Both expose the same async interface so ingestion code does not need to know which backend is ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:136-185 — 4. Detect any existing vector index dimension. Storage primitives: - upsert_entities / upsert_relationships — plain graph writes. - add_chunks — lazily creates the HNSW vector index on first call, then merges chunks. - search_similar — calls Memgraph's vector_search.search query module. - get_neighbors — variable-length traversal up to depth 10. - retrieve — vector search followe...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:586-601 — | src/orchestrata_ultimate/semantic_graph/interfaces.py | VectorStore, GraphStore, SemanticGraph protocols | | src/orchestrata_ultimate/semantic_graph/config.py | SemanticGraphConfig.from_env() | | src/orchestrata_ultimate/semantic_graph/exceptions.py | Exception hierarchy | | src/orchestrata_ultimate/semantic_graph/embedders.py | OpenRouterEmbedder, SentenceTransformerEmbedder...

Q28: Why does the Memgraph adapter use chunk-label and vector-index isolation in tests?

Category: Semantic Graph & RAG Keywords: memgraph, adapter, chunk, label, vector, index, isolation, tests Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_memgraph_adapter.py:46-95 — Measured root cause (2026-07-21): the old function-scoped fixture gave every test its own chunk label, so connect()'s schema DDL -- CREATE INDEX ON :<label>(id) (2,514ms) + CREATE INDEX ON :<label> (235ms) + CREATE CONSTRAINT <label>_id (135ms) -- ran ~2.9s per test x 50 tests, because Memgraph's index build scans the whole vertex store even for an empty la...
/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_ingestion.py:46-95 — @pytest.fixture def openrouter_embedder(openrouter_server: str) -> OpenRouterEmbedder: """OpenRouter embedder pointing at the local test server.""" return OpenRouterEmbedder( api_key="test-key", base_url=openrouter_server, ) @pytest.fixture def openrouter_reranker(rerank_server: str) -> OpenRouterReranker: """OpenRouter reranker pointing at the local test server."...
/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_memgraph_adapter.py:1-50 — """Integration tests for MemgraphSemanticGraph. Uses the real Memgraph Incus container configured via MEMGRAPH_URI in .env. Each test isolates data with a test_id prefix and cleans up after itself. Under the session-shared vector index (see _shared_memgraph_graph), per-test cleanup deletes ONLY entities, never chunks: physically deleting a node that is part of the shared native vector index m...

Q29: What bug was fixed in `_all_vector_indexes()` regarding label strings?

Category: Semantic Graph & RAG Keywords: fixed, _all_vector_indexes, regarding, label, strings Coverage: 60%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/adapters/memgraph.py:361-410 — with driver.session() as session: session.run(cypher).consume() logger.info( "Creating vector index %s with dimension %s", self._config.vector_index_name, dimension, ) await self._execute_with_reconnect(_create, max_storage_retries=20) await self._wait_for_vector_index() self._vector_index_dime...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/CODEBASE_MAP_FULL.md:6481-6530 — src/orchestrata_ultimate/semantic_graph/adapters/memgraph.py:284: def _add(driver: Any, chunk: Chunk) -> None src/orchestrata_ultimate/semantic_graph/adapters/memgraph.py:308: async def _load_vector_index_dimension(self) -> None src/orchestrata_ultimate/semantic_graph/adapters/memgraph.py:314: async def _vector_index_info(self) -> dict[str, Any] | None src/orchestrata_ultimate/semantic_graph/adapt...
/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_memgraph_adapter.py:631-680 — ) graph = MemgraphSemanticGraph(config) connected = await graph.connect() if not connected: raise RuntimeError("Memgraph container is not reachable") try: # Create a 3-dimensional index. await graph.add_chunks( [ Chunk( id=_eid(test_id, "c3"), content="three", embedding=[1.0, 0.0, 0.0] ), ...

Q30: What happens when a dimension mismatch is detected on an existing vector index?

Category: Semantic Graph & RAG Keywords: happens, dimension, mismatch, detected, existing, vector, index Coverage: 71%

/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_memgraph_adapter.py:991-1040 — config = SemanticGraphConfig( backend="memgraph", uri=memgraph_config.uri, username="test-user", password=«redacted» ) graph = MemgraphSemanticGraph(config) assert await graph.connect() is True async def test_upsert_empty_entities_and_relationships( memgraph_graph: MemgraphSemanticGraph, ) -> None: await memgraph_graph.upsert_entities([])...
/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_memgraph_adapter.py:631-680 — ) graph = MemgraphSemanticGraph(config) connected = await graph.connect() if not connected: raise RuntimeError("Memgraph container is not reachable") try: # Create a 3-dimensional index. await graph.add_chunks( [ Chunk( id=_eid(test_id, "c3"), content="three", embedding=[1.0, 0.0, 0.0] ), ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_memgraph_adapter.py:586-635 — ] ) await memgraph_graph.upsert_relationships( [ Relationship(id=r1, type="KNOWS", source_id=e1, target_id=e2), ] ) entities, relationships = await memgraph_graph.get_neighbors(e1, depth=1) alice = next(e for e in entities if e.id == e1) assert "Person" in alice.labels rel = next(r for r in relationships if r.id == r1) assert rel....

Q31: How does the HA controller discover the current Memgraph MAIN node?

Category: Semantic Graph & RAG Keywords: controller, discover, current, memgraph, main, node Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:1-50 — # Memgraph HA Cluster This document describes the three-node Memgraph Community high-availability cluster used by orchestrata-ultimate for the semantic graph / RAG backend. It covers how the cluster was created, how replication works, how failover and autofailback work, and how to operate it. > Deployment status (2026-07-11): the memgraph-1/2/3 + memgraph-ha > controller cluster descri...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/main_discovery.py:1-50 — """Client-side discovery of the current Memgraph MAIN data-instance bolt URI. Reproducibility plan Phase R3: no writer may pin a specific data-instance address (bolt://10.92.53.123:7687 etc) because Raft failover moves MAIN between the orchgraph-data-* instances — a restart once failed MAIN over from instance_2 (10.92.53.123) to instance_1 (10.92.53.128) and every hardcode...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/main_discovery.py:91-140 — uri = _resolve_via_controller(controller_url) if uri: return uri uris_raw = active_env.get("MEMGRAPH_URIS", "") coordinator_uris = [u.strip() for u in uris_raw.split(",") if u.strip()] if coordinator_uris: uri = _resolve_via_coordinators(coordinator_uris) if uri: return uri fallback = active_env.get("MEMGRAPH_URI", "") i...

Q32: What is the vector index name, dimension, and metric for the orchestrata-ultimate Codestral chunks?

Category: Semantic Graph & RAG Keywords: vector, index, name, dimension, metric, orchestrata, ultimate, codestral Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:316-365 — python scripts/ingest_orchestrata_ultimate.py ``` It reads OPENROUTER_API_KEY, connects via the HA controller, clears the configured chunk label, ingests .py, .pyi, and .md files under src/orchestrata_ultimate, then ingests extra documentation roots (AGENTS.md, README.md, docs/, architecture/, design/, selected plans/), links chunks to modules, and runs sample verification q...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/CODEBASE_MAP_FULL.md:6526-6575 — src/orchestrata_ultimate/semantic_graph/adapters/memory.py:17: def _cosine_similarity(a: list[float], b: list[float]) -> float src/orchestrata_ultimate/semantic_graph/adapters/memory.py:29: class InMemorySemanticGraph src/orchestrata_ultimate/semantic_graph/adapters/memory.py:37: def init(self, config: SemanticGraphConfig | None=None) -> None src/orchestrata_ultimate/semantic_graph/adapters/me...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:136-185 — 4. Detect any existing vector index dimension. Storage primitives: - upsert_entities / upsert_relationships — plain graph writes. - add_chunks — lazily creates the HNSW vector index on first call, then merges chunks. - search_similar — calls Memgraph's vector_search.search query module. - get_neighbors — variable-length traversal up to depth 10. - retrieve — vector search followe...

Q33: What reranker model is used for the orchestrata-ultimate semantic graph?

Category: Semantic Graph & RAG Keywords: reranker, model, used, orchestrata, ultimate, semantic, graph Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/rerankers.py:1-50 — """Reranking backend for semantic graph retrieval. Uses OpenRouter's rerank endpoint with Cohere rerankers to reorder candidate chunks by relevance to a query. """ from future import annotations import logging import httpx from orchestrata_ultimate.semantic_graph.exceptions import VectorSearchError from orchestrata_ultimate.semantic_graph.models import Chunk logger = logging.getLogger(__...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:586-601 — | src/orchestrata_ultimate/semantic_graph/interfaces.py | VectorStore, GraphStore, SemanticGraph protocols | | src/orchestrata_ultimate/semantic_graph/config.py | SemanticGraphConfig.from_env() | | src/orchestrata_ultimate/semantic_graph/exceptions.py | Exception hierarchy | | src/orchestrata_ultimate/semantic_graph/embedders.py | OpenRouterEmbedder, SentenceTransformerEmbedder...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/CODEBASE_MAP_FULL.md:6616-6665 — src/orchestrata_ultimate/semantic_graph/ha_controller.py:572: def _status_dict(self) -> dict[str, Any] src/orchestrata_ultimate/semantic_graph/ingestion.py:59: def _extract_query_terms(query: str, max_terms: int) -> list[str] src/orchestrata_ultimate/semantic_graph/ingestion.py:70: def _add(term: str) -> None src/orchestrata_ultimate/semantic_graph/ingestion.py:87: def _reciprocal_rank_fusion(rank...

Q34: How many chunks were ingested for the orchestrata-ultimate project?

Category: Semantic Graph & RAG Keywords: many, chunks, were, ingested, orchestrata, ultimate, project Coverage: 57%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:271-320 — ### 5.1 Factory python from orchestrata_ultimate.semantic_graph.repository import create_semantic_graph graph = create_semantic_graph() await graph.connect() ### 5.2 Ingest a project ```python from pathlib import Path from orchestrata_ultimate.semantic_graph.adapters.memgraph import MemgraphSemanticGraph from orchestrata_ultimate.semantic_graph.embedders import OpenRouterEmbedder from ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:316-365 — python scripts/ingest_orchestrata_ultimate.py ``` It reads OPENROUTER_API_KEY, connects via the HA controller, clears the configured chunk label, ingests .py, .pyi, and .md files under src/orchestrata_ultimate, then ingests extra documentation roots (AGENTS.md, README.md, docs/, architecture/, design/, selected plans/), links chunks to modules, and runs sample verification q...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/CODEBASE_MAP_FULL.md:6616-6665 — src/orchestrata_ultimate/semantic_graph/ha_controller.py:572: def _status_dict(self) -> dict[str, Any] src/orchestrata_ultimate/semantic_graph/ingestion.py:59: def _extract_query_terms(query: str, max_terms: int) -> list[str] src/orchestrata_ultimate/semantic_graph/ingestion.py:70: def _add(term: str) -> None src/orchestrata_ultimate/semantic_graph/ingestion.py:87: def _reciprocal_rank_fusion(rank...

Q35: What property tags every chunk with its project for multi-project support?

Category: Semantic Graph & RAG Keywords: property, tags, every, chunk, project, multi, support Coverage: 57%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:361-410 — ### 6.2 Node labels #### Chunk (and project-specific sub-labels) The base label is configurable (MEMGRAPH_CHUNK_LABEL). Ingestion scripts can use distinct labels so multiple embedding models and projects coexist. | Property | Type | Meaning | |----------|------|---------| | id | string | Deterministic chunk identifier (path:start:end or hashed) | | content | string | Raw chunk text |...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/ingestion.py:1-50 — """Source-code ingestion into a semantic graph. Chunks source files, embeds the chunks, and stores them as vector-indexed nodes. Each chunk carries a project_id so one graph can host multiple projects without collision. """ from future import annotations import logging import math import mimetypes import re from pathlib import Path from typing import Any from orchestrata_ultimate.seman...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:406-455 — Uniqueness constraint: Entity.id IS UNIQUE. ### 6.3 Relationship types | Type | Source | Target | Meaning | |------|--------|--------|---------| | BELONGS_TO | Chunk | Module | Chunk is part of a module/package | | MENTIONS | Chunk | Entity | Chunk text references the entity | | REFERENCES | Entity | Entity | Generic semantic reference | | HAS_STORY | Spec | Story | Spe...

Q36: What is the `Embedder` protocol interface?

Category: Semantic Graph & RAG Keywords: embedder, protocol, interface Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/embedders.py:1-50 — """Embedding backends for the semantic graph. Provides a small protocol plus two concrete implementations: * :class:OpenRouterEmbedder - cloud embeddings via OpenRouter (Codestral). * :class:SentenceTransformerEmbedder - local GPU embeddings via sentence-transformers (Qwen3-Embedding, etc.). Both expose the same async interface so ingestion code does not need to know which backend is ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:181-230 — Embedder is a protocol. Two implementations are provided: - OpenRouterEmbedder — cloud embeddings via OpenRouter. Default model mistralai/codestral-embed-2505 (1536 dims). Batches requests and preserves order by index. - SentenceTransformerEmbedder — local GPU embeddings via sentence-transformers. Default model Qwen/Qwen3-Embedding-0.6B (1024 dims). Uses CUDA when available, ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_architecture_twin.py:406-455 — defensive contract check in _embed_and_store (the real OpenRouterEmbedder already enforces this contract itself, so it cannot be driven through that check; this proves the twin's own guard fires for a differently-behaved Embedder implementation).""" dimension = 4 async def embed( self, texts: list[str], prompt_type: str = "document" ) -> list[list[floa...

Q37: How does `OpenRouterEmbedder` handle out-of-order provider responses?

Category: Semantic Graph & RAG Keywords: openrouterembedder, handle, order, provider, responses Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/faq/openrouter-out-of-order.md:1-8 — --- title: How does OpenRouterEmbedder handle out-of-order provider responses? description: Explanation of how the embedder preserves input order when providers return shuffled results. --- # How does OpenRouterEmbedder handle out-of-order provider responses? OpenRouterEmbedder.embed() sends batches to OpenRouter and handles out-of-order provider responses by sorting the response items by th...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/embedders.py:181-230 — except KeyError as exc: raise VectorSearchError( f"OpenRouter embeddings response missing 'data': {data}" ) from exc # Sort by index to preserve input order; some providers return results # out of order under load. indexed = sorted( ((item.get("index", 0), item["embedding"]) for item in items), key=lam...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/embedders.py:91-140 — self._timeout = timeout self._batch_size = max(1, batch_size) self._max_tokens_per_batch = max(1, max_tokens_per_batch) @property def dimension(self) -> int: return self._dimension async def embed( self, texts: list[str], prompt_type: str = "document" ) -> list[list[float]]: """Embed texts via OpenRouter in bounded batches.""" ...

Q38: Why is `SentenceTransformerEmbedder` loaded lazily?

Category: Semantic Graph & RAG Keywords: sentencetransformerembedder, loaded, lazily Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/embedders.py:181-230 — except KeyError as exc: raise VectorSearchError( f"OpenRouter embeddings response missing 'data': {data}" ) from exc # Sort by index to preserve input order; some providers return results # out of order under load. indexed = sorted( ((item.get("index", 0), item["embedding"]) for item in items), key=lam...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/embedders.py:271-304 — return model.encode(texts, **kwargs) embeddings = await anyio.to_thread.run_sync(_encode) return [list(vector) for vector in embeddings] def _load_model(self) -> Any: """Lazy-load the sentence-transformers model.""" if self._model is None: from sentence_transformers import SentenceTransformer device = self._device ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/embedders.py:226-275 — """Initialize the embedder. Args: model_name: Hugging Face model identifier or local path. dimension: Expected vector dimension. device: Torch device ("cuda", "cpu", etc.). None picks CUDA when available. query_prompt: Prompt prefix for prompt_type="query". None uses ``prompt_name="...

Q39: What is the default Qwen embedding model and dimension?

Category: Semantic Graph & RAG Keywords: default, qwen, embedding, model, dimension Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/embedders.py:181-230 — except KeyError as exc: raise VectorSearchError( f"OpenRouter embeddings response missing 'data': {data}" ) from exc # Sort by index to preserve input order; some providers return results # out of order under load. indexed = sorted( ((item.get("index", 0), item["embedding"]) for item in items), key=lam...
/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_embedders.py:226-240 — try: embeddings = await embedder.embed(["hello"], prompt_type="query") assert len(embeddings) == 1 finally: assert embedder._model is not None embedder._model.prompts = original_prompts else: embeddings = await embedder.embed(["hello"], prompt_type="query") assert len(embeddings) == 1 async def test_qwen_dimensio...
/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_embedders.py:46-95 — ) _qwen_model_cache[key] = embedder._load_model() return _qwen_model_cache[key] @pytest.fixture def qwen_model() -> Iterator[Any]: """Yield the cached Qwen model.""" yield _load_qwen_model() @pytest.fixture def qwen_embedder(qwen_model: object) -> SentenceTransformerEmbedder: """Return a Qwen embedder that reuses the session-loaded model.""" embedder = Sente...

Q40: How does the ingestion script verify retrieval quality after indexing?

Category: Semantic Graph & RAG Keywords: ingestion, script, verify, retrieval, quality, after, indexing Coverage: 71%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:541-590 — ``` Current result (verified 2026-07-08): 156 passed, 0 failed, 96% total coverage, every semantic_graph source file ≥90%. --- ## 9. Known issues and follow-ups ### OpenRouter token limits during doc ingestion Large markdown directories can produce batches whose total token count exceeds OpenRouter's request limit, even when the batch is only 64 chunks. The embedder needs token-aware bat...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:316-365 — python scripts/ingest_orchestrata_ultimate.py ``` It reads OPENROUTER_API_KEY, connects via the HA controller, clears the configured chunk label, ingests .py, .pyi, and .md files under src/orchestrata_ultimate, then ingests extra documentation roots (AGENTS.md, README.md, docs/, architecture/, design/, selected plans/), links chunks to modules, and runs sample verification q...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/semantic-graph.md:271-320 — ### 5.1 Factory python from orchestrata_ultimate.semantic_graph.repository import create_semantic_graph graph = create_semantic_graph() await graph.connect() ### 5.2 Ingest a project ```python from pathlib import Path from orchestrata_ultimate.semantic_graph.adapters.memgraph import MemgraphSemanticGraph from orchestrata_ultimate.semantic_graph.embedders import OpenRouterEmbedder from ...

Q41: Why is `pytest-xdist` banned for this project?

Category: Testing & Quality Keywords: pytest, xdist, banned, project Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:1-50 — # AGENTS.md — Guide for AI Coding Agents > Read this before executing any step of the execution plan. > ## ⛔ CRITICAL — NEVER use pytest-xdist (-n / --dist) > pytest -n auto (xdist) deadlocks this suite (~78% stall) and is banned. > Run tests ONLY via the supported runners: > - python scripts/run_tests.py — primary: infra check + safety gates + batched executor (~7 min) >...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:1-50 — # Development & Testing Workflow — orchestrata-ultimate This document describes how to develop, lint, test, and dogfood the orchestrata-ultimate codebase. It is derived directly from the project's own rules (AGENTS.md, CLAUDE.md, KIMI-PROCESS.md), its tooling (scripts/), its hooks (.claude/), and its test configuration (tests/conftest.py, pyproject.toml). Every command and `file:l...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:46-95 — - scripts/run_tests_threadpool.py — low-level batched runner without infrastructure checks. Used by run_tests.py internally. ### Batching Architecture The threadpool runner batches test modules into max_workers groups. Each group runs as a single pytest subprocess: ``` 978 modules → 4 batches of ~244 modules → 4 subprocesses Worker 0: tests/agents/ tests/core/ ... (244 modul...

Q42: What are the two supported test runners?

Category: Testing & Quality Keywords: supported, test, runners Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:1-50 — # AGENTS.md — Guide for AI Coding Agents > Read this before executing any step of the execution plan. > ## ⛔ CRITICAL — NEVER use pytest-xdist (-n / --dist) > pytest -n auto (xdist) deadlocks this suite (~78% stall) and is banned. > Run tests ONLY via the supported runners: > - python scripts/run_tests.py — primary: infra check + safety gates + batched executor (~7 min) >...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:1-50 — # Development & Testing Workflow — orchestrata-ultimate This document describes how to develop, lint, test, and dogfood the orchestrata-ultimate codebase. It is derived directly from the project's own rules (AGENTS.md, CLAUDE.md, KIMI-PROCESS.md), its tooling (scripts/), its hooks (.claude/), and its test configuration (tests/conftest.py, pyproject.toml). Every command and `file:l...
/home/mohamed/workspace/orchestrata-ultimate-architecture/README.md:136-185 — - Real infrastructure in tests. - Function-scope fixtures with test_id isolation. - Per-file coverage ≥90%. - Batched parallel runner (pytest-xdist is banned because it deadlocks this suite). --- ## 4. Supported LLMs | Provider | Models | Backend | |----------|--------|---------| | DeepSeek | v4-pro, v4-flash | Native API | | Claude | sonnet, opus | Claude CLI (OAuth) | | Kimi | k2.7-code, ...

Q43: What is the minimum per-file coverage required by the Definition of Done?

Category: Testing & Quality Keywords: minimum, file, coverage, required, definition, done Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/faq/coverage-requirement.md:1-14 — --- title: What is the minimum per-file coverage required by the Definition of Done? description: Per-file coverage requirement for Orchestrata Ultimate. --- # What is the minimum per-file coverage required by the Definition of Done? Every source file created or modified must have ≥90% line coverage before it is considered done. Coverage is measured per file with: ```bash uv run pytest test...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:631-680 — 2. VizInt bridge connects to gateway — The browser's WebSocketBridge connects via localStorage.setItem('vizint.gateway.url', ...) for E2E test dynamic port configuration. 3. gRPC kernel is out-of-process — Gateway connects to kernel via gRPC on port 50053. If unreachable, logs clear warning and falls back to PipelineKernelClient. 4. Three-tier gRPC logging — Unconfigured → INF...
/home/mohamed/workspace/orchestrata-ultimate-architecture/README.md:136-185 — - Real infrastructure in tests. - Function-scope fixtures with test_id isolation. - Per-file coverage ≥90%. - Batched parallel runner (pytest-xdist is banned because it deadlocks this suite). --- ## 4. Supported LLMs | Provider | Models | Backend | |----------|--------|---------| | DeepSeek | v4-pro, v4-flash | Native API | | Claude | sonnet, opus | Claude CLI (OAuth) | | Kimi | k2.7-code, ...

Q44: What does rule T2 forbid regarding `os.environ` in ported tests?

Category: Testing & Quality Keywords: rule, forbid, regarding, environ, ported, tests Coverage: 83%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:676-725 — When a test fails, fix the CODE — never fake the test green. A test written to assert correct behaviour may fail because the source is wrong. The response is to fix the source code (per the spec — the file's @traces reqs and specs/<n>-*, which are authoritative over both current code and tests), keeping the test asserting the correct result. If the correct behaviour is a genuine desi...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:1081-1130 — ### Test Porting Strategy (applies to ALL tiers) IMPORTANT: Orchestrata has 408 test files with ~8,600 test functions. These tests MUST be ported alongside the source code, but they require significant transformation to comply with ultimate's test standards. Orchestrata's tests have isolation violations that BREAK parallel execution. **Do NOT blindly copy tests — each file needs ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:3601-3650 — ### Step 173: 🚪 Orchestrator Gate Check bash cd /home/mohamed/workspace/orchestrata-ultimate && python -c " from orchestrata_ultimate.orchestrator import * print('ORCHESTRATOR OK') " --- ### Step 173b: Port Tier 2 test files (with isolation transformations) Goal: Port test files for governance, postman, kernel, orchestrator — heaviest transformation tier. Actions: 1. Copy test...

Q45: Why must fixtures be function-scope rather than module or class scope?

Category: Testing & Quality Keywords: fixtures, function, scope, rather, module, class Coverage: 83%

/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:1081-1130 — ### Test Porting Strategy (applies to ALL tiers) IMPORTANT: Orchestrata has 408 test files with ~8,600 test functions. These tests MUST be ported alongside the source code, but they require significant transformation to comply with ultimate's test standards. Orchestrata's tests have isolation violations that BREAK parallel execution. **Do NOT blindly copy tests — each file needs ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:91-140 — The threadpool/streaming runners avoid this by running one module per subprocess serially-within-module and only borrowing a bounded slot for Redis DB selection; they do not use xdist's work-stealing scheduler. The harmless ORCHESTRATA_WORKER_SLOT env var is therefore intentionally allowed even though the -n/--dist flags are banned (.claude/hooks/no-xdist.sh:9-10, `test_executo...
/home/mohamed/workspace/orchestrata-ultimate-architecture/tests/semantic_graph/test_memgraph_adapter.py:46-95 — Measured root cause (2026-07-21): the old function-scoped fixture gave every test its own chunk label, so connect()'s schema DDL -- CREATE INDEX ON :<label>(id) (2,514ms) + CREATE INDEX ON :<label> (235ms) + CREATE CONSTRAINT <label>_id (135ms) -- ran ~2.9s per test x 50 tests, because Memgraph's index build scans the whole vertex store even for an empty la...

Q46: What is the `isolation` fixture used for?

Category: Testing & Quality Keywords: isolation, fixture, used Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:766-815 — # Must pass under parallel isolation (batched executor — NEVER xdist/-n auto): python scripts/run_tests.py tests// --skip-gates ``` ### General Test Rules - No mocking — real implementations only (no unittest.mock, MagicMock, AsyncMock, patch) - No stubs or fakes — no FakeX, StubX, DummyX classes; use real infrastructure - No monkeypatch — pass config/parameters ex...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:271-320 — | Foreign process detection | Refuses to start if port is in use without matching PID file | | Log file | /tmp/orchestrata-gateway.log (append-only, ready for logrotate) | #### Usage ```bash # Check + start + verify all services (parallel, idempotent) python scripts/start_test_services.py # Check only — never starts, exits 0 even if services are down python scripts/start_test_services...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:1126-1175 — T4. Remove ALL global/module-level mutable state: ```python # BEFORE (orchestrata — shared state pollutes parallel workers): _prolog_cleanup_counter = 0 _redis_healthy = None _LOADED_MODULES = {} # AFTER: Move to fixtures or remove entirely. # If state must be cached, use a fixture with appropriate scope. @pytest.fixture(scope="session") def _infra_health(): """Read-only health check — O...

Q47: How are Redis keys isolated per worker in tests?

Category: Testing & Quality Keywords: redis, keys, isolated, worker, tests Coverage: 80%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:46-95 — - scripts/run_tests_threadpool.py — low-level batched runner without infrastructure checks. Used by run_tests.py internally. ### Batching Architecture The threadpool runner batches test modules into max_workers groups. Each group runs as a single pytest subprocess: ``` 978 modules → 4 batches of ~244 modules → 4 subprocesses Worker 0: tests/agents/ tests/core/ ... (244 modul...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/core/threading/test_executor.py:1-50 — # mypy: ignore-errors """Parallel test executor using ThreadPoolManager + batched subprocess. Design (per architecture/THREADPOOL-PARALLEL-TESTING.md): The ThreadPoolExecutor is the thread pool (Section 2.1). Each thread dispatches ONE pytest subprocess that runs a batch of modules. Instead of one subprocess per test MODULE (978 subprocesses, ~24 min), modules are batched into ``max_w...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/THREADPOOL_TEST_INSTRUCTIONS.md:91-140 — |--------|--------------------------|-------------------| | Parallelism | pytest plugin (internal) | ThreadPoolExecutor + subprocess | | Workers | auto (CPU count) | Configurable max_workers (default 4) | | Isolation | pytest-xdist worker processes | One subprocess per test module/path | | Redis DB isolation | gw0 → db0, gw1 → db1 | Injects ORCHESTRATA_WORKER_SLOT=gw<N env var so fixtu...

Q48: What is the real-Prolog fixture pattern for test isolation?

Category: Testing & Quality Keywords: real, prolog, fixture, pattern, test, isolation Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:676-725 — When a test fails, fix the CODE — never fake the test green. A test written to assert correct behaviour may fail because the source is wrong. The response is to fix the source code (per the spec — the file's @traces reqs and specs/<n>-*, which are authoritative over both current code and tests), keeping the test asserting the correct result. If the correct behaviour is a genuine desi...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:1171-1220 — **T7. Use `test_id` for ALL database operations:**python # BEFORE (orchestrata — global data pollution): session.run("CREATE (n:Document {name: 'test'})") # AFTER (ultimate — isolated by test_id): def test_neo4j(isolation, neo4j_session): node_id = isolation.create_test_node_id("Document") neo4j_session.run( "CREATE (n:Document {id: $id, test_id: $tid, name: 'test'})", ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:856-905 — @pytest.fixture def prolog_engine(): """Per-test Prolog engine — no global singleton.""" try: from pyswip import Prolog engine = Prolog() yield engine except ImportError: pytest.skip("pyswip not available") 6. Apply standard import translation to all ported code **Verify:**bash cd /home/mohamed/workspace/orchestrata...

Q49: Why are mocks, stubs, fakes, and monkeypatch forbidden?

Category: Testing & Quality Keywords: mocks, stubs, fakes, monkeypatch, forbidden Coverage: 80%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/TEST_REVIEW_PROCESS.md:181-230 — bash git add tests/<module>/ src/orchestrata_ultimate/<module>/ git status git diff --cached --stat # git commit -m "<module>: tests and coverage >=90%" ## Absolute Rules (Non-Negotiable) 1. NO fake classes — class Fake*, class Mock*, class Stub* are forbidden in tests. 2. NO mocking — unittest.mock, mock.patch, MagicMock are forbidden. 3. NO monkeypatching — `monk...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:766-815 — # Must pass under parallel isolation (batched executor — NEVER xdist/-n auto): python scripts/run_tests.py tests// --skip-gates ``` ### General Test Rules - No mocking — real implementations only (no unittest.mock, MagicMock, AsyncMock, patch) - No stubs or fakes — no FakeX, StubX, DummyX classes; use real infrastructure - No monkeypatch — pass config/parameters ex...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:91-140 — The threadpool/streaming runners avoid this by running one module per subprocess serially-within-module and only borrowing a bounded slot for Redis DB selection; they do not use xdist's work-stealing scheduler. The harmless ORCHESTRATA_WORKER_SLOT env var is therefore intentionally allowed even though the -n/--dist flags are banned (.claude/hooks/no-xdist.sh:9-10, `test_executo...

Q50: What are the four blocking safety gates run before tests?

Category: Testing & Quality Keywords: four, blocking, safety, gates, before, tests Coverage: 83%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:1-50 — # AGENTS.md — Guide for AI Coding Agents > Read this before executing any step of the execution plan. > ## ⛔ CRITICAL — NEVER use pytest-xdist (-n / --dist) > pytest -n auto (xdist) deadlocks this suite (~78% stall) and is banned. > Run tests ONLY via the supported runners: > - python scripts/run_tests.py — primary: infra check + safety gates + batched executor (~7 min) >...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:1-50 — # Development & Testing Workflow — orchestrata-ultimate This document describes how to develop, lint, test, and dogfood the orchestrata-ultimate codebase. It is derived directly from the project's own rules (AGENTS.md, CLAUDE.md, KIMI-PROCESS.md), its tooling (scripts/), its hooks (.claude/), and its test configuration (tests/conftest.py, pyproject.toml). Every command and `file:l...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/CODEBASE_MAP.md:1126-1175 — - tests/scripts/test_ast_gen_protocol.py — Tests for the AST tool's gen-protocol generator (Protocol/ABC/impl). - tests/scripts/test_ast_gen_serde.py — Tests for the AST tool's gen-serde subcommand: an emitter that generates - tests/scripts/test_ast_gen_skeleton.py — Tests for the AST tool's gen-skeleton generator — the build-factory - tests/scripts/test_ast_gen_volk.py — Tests...

Q51: What is the source monorepo path and how many packages does it contain?

Category: Porting & AST Keywords: source, monorepo, path, many, packages, contain Coverage: 50%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:271-320 — #### serialize — Extract full AST from a Python codebase to JSON ```bash # Serialize orchestrata-ultimate (single package) python scripts/serialize_codebase_ast.py serialize \ --source src/orchestrata_ultimate \ --name orchestrata-ultimate \ --output plans/ast-ultimate.json # Serialize orchestrata monorepo (26 packages) python scripts/serialize_codebase_ast.py serialize \ --so...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/standards/architecture.md:1-29 — # Orchestrata Ultimate Architecture Overview ## High-Level Design - Monorepo to Single Package Port: 122K LOC from 26 packages to src/orchestrata_ultimate/ using Python 3.14+, uv manager. - Core Components: Agents (volks), CXP protocol, Providers (LLM adapters), Kernel (event bus, registry), Orchestrator (intent parsing), Knowledge Graph (Neo4j), Session/Memory management, Gateway (WebS...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:901-950 — memory/ # Hot/cold store, embeddings gateway/ # WebSocket, RPC, auth plugin/ # Plugin loader, registry, SDK verification/ # Test traceability, constraints, autofix integrations/ # CheetahClaws, Todoist exceptions/ # Exception hierarchy tests/ ...

Q52: What is the target package path for the ported code?

Category: Porting & AST Keywords: target, package, path, ported, code Coverage: 80%

/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:1-50 — # Implementation Plan: Port Orchestrata → Orchestrata-Ultimate ## Executive Summary Port ~119,000 LOC (net) from orchestrata's 26 packages into orchestrata-ultimate's single-package structure. Keep ultimate's core/ infrastructure (observability, error handling, threading, exceptions). Replace all stubs with real implementations. This plan survived 13 rounds of adversarial review (124 issues rai...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:1666-1715 — --- ### Step 54: Port cost_tracker.py and rate_limiter.py Source: $SRC/orchestrata-provider/src/orchestrata/provider/ Destination: $ULT/providers/ Actions: 1. Copy both, apply standard import translation Verify: python -c "from orchestrata_ultimate.providers.cost_tracker import *; from orchestrata_ultimate.providers.rate_limiter import *; print('OK')" --- ### Step 55: P...
/home/mohamed/workspace/orchestrata-ultimate-architecture/architecture/current-to-target-mapping.md:181-230 — |---|---|---| | verification/review/ | Code review engine (7 files) | Ported (Tier 1.5) | Not yet ported (Tier 2.2b in current plan): - verification/constraints/, checkpoints/, proofs/, autofix/, edge_cases/ - verification/agents/, orchestration/, session/ - 6+ more verification subdirectories --- ## Layer 4: Orchestration ### Kernel — stub only | Current Location | Cont...

Q53: What is the purpose of `scripts/serialize_codebase_ast.py`?

Category: Porting & AST Keywords: purpose, scripts, serialize_codebase_ast Coverage: 67%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/AST_COMPARISON_ENGINE.md:1-50 — # AST Comparison Engine > Location: scripts/serialize_codebase_ast.py (1,315 LOC) > Full tools reference: plans/tools_useful_to_plan.md (20 scripts documented) The core analysis tool for porting orchestrata (26-package monorepo, 122K LOC) into orchestrata-ultimate (single package). Produces the JSON data that powers the 238-step execution plan. --- ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:406-455 — Wraps orchestrata_ultimate.domaingen.{parse_ontology,generate_code,render_ontology} (domaingen.py:32-53). --out is required unless --render-ttl is given (domaingen.py:49-50). Dependencies rdflib>=7.6.0 and jinja2>=3.1.6 are in pyproject.toml:46-47. ### AST serializer / comparison engine scripts/serialize_codebase_ast.py is the source-of-truth porting tool, with three subcomman...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:271-320 — #### serialize — Extract full AST from a Python codebase to JSON ```bash # Serialize orchestrata-ultimate (single package) python scripts/serialize_codebase_ast.py serialize \ --source src/orchestrata_ultimate \ --name orchestrata-ultimate \ --output plans/ast-ultimate.json # Serialize orchestrata monorepo (26 packages) python scripts/serialize_codebase_ast.py serialize \ --so...

Q54: How many classes are in the orchestrata source AST?

Category: Porting & AST Keywords: many, classes, orchestrata, source Coverage: 75%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/AST_COMPARISON_ENGINE.md:46-95 — | Functions | Same as methods but module-level | | Class Variables | Name, type annotation, default, ClassVar flag | | Imports | Module path, imported names, from-style, relative, level | | Inheritance Graph | Resolved: class qualified name -> list of base qualified names | | Dependency Graph | Module path -> list of imported module paths | Monorepo mode (--monorepo): Sc...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/ast-query.md:46-95 — ``` Relative paths are resolved against the project root (located by walking up for plans/ast-ultimate.json or pyproject.toml), the package's source root, or the current working directory — so ASTQuery() works from anywhere inside the repo. Passing compare_path (a deep-comparison JSON) unlocks the comparison helpers described below. Indexes over classes, methods, and modules are built laz...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:451-500 — python scripts/sync_ast_to_neo4j.py stats # Verify python scripts/sync_ast_to_neo4j.py verify --project orchestrata-ultimate ``` Connection via env vars: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD in .env. --- ## Plans Directory | File | Size | What | |------|------|------| | plans/execution-plan.md | 4,615 lines | 224-step execution plan (4 adversarial review rounds) | | `plans/impl...

Q55: What is the three-pass class pairing algorithm in the deep compare tool?

Category: Porting & AST Keywords: three, pass, class, pairing, algorithm, deep, compare, tool Coverage: 75%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/AST_COMPARISON_ENGINE.md:46-95 — | Functions | Same as methods but module-level | | Class Variables | Name, type annotation, default, ClassVar flag | | Imports | Module path, imported names, from-style, relative, level | | Inheritance Graph | Resolved: class qualified name -> list of base qualified names | | Dependency Graph | Module path -> list of imported module paths | Monorepo mode (--monorepo): Sc...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:271-320 — #### serialize — Extract full AST from a Python codebase to JSON ```bash # Serialize orchestrata-ultimate (single package) python scripts/serialize_codebase_ast.py serialize \ --source src/orchestrata_ultimate \ --name orchestrata-ultimate \ --output plans/ast-ultimate.json # Serialize orchestrata monorepo (26 packages) python scripts/serialize_codebase_ast.py serialize \ --so...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:316-365 — #### How the pairing works internally ``` pair_classes(ultimate_index, orchestrata_index, class_mappings, name_transforms) -> Pass 1: For each entry in class_mappings (e.g., "BaseVolk": "BaseAgent"), look up both classes in their indexes. Create pair. -> Pass 2: For each remaining unmatched orchestrata class, check if ultimate has a class with the same name. Create ...

Q56: What is the readiness classification for ported classes?

Category: Porting & AST Keywords: readiness, classification, ported, classes Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/AST_COMPARISON_ENGINE.md:91-140 — For every orchestrata class not yet paired, checks if ultimate has a class with the identical name. Example: CircuitBreaker, Node, EventBus. Pass 3 — Regex transforms (2 patterns in name_transforms): json [ {"pattern": "Volk$", "replacement": "Agent"}, {"pattern": "^I([A-Z]\\w*)", "replacement": "\\1Protocol"} ] Applies each regex to the orchestrata class name and checks if...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:316-365 — #### How the pairing works internally ``` pair_classes(ultimate_index, orchestrata_index, class_mappings, name_transforms) -> Pass 1: For each entry in class_mappings (e.g., "BaseVolk": "BaseAgent"), look up both classes in their indexes. Create pair. -> Pass 2: For each remaining unmatched orchestrata class, check if ultimate has a class with the same name. Create ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/AST_COMPARISON_ENGINE.md:271-320 — decorators: list[str] # ["abstractmethod"] class_vars: list[ClassVarInfo] functions: list[FunctionInfo] # module-level functions imports: list[ImportInfo] module: str # "orchestrata.core.interfaces" names: list[str] # ["IComponent", "IVolk"] inheritance_graph: dict[str, list[str]] dependency_graph: dict[str, list[str]...

Q57: What is the standard import translation from `orchestrata.core.interfaces`?

Category: Porting & AST Keywords: standard, import, translation, orchestrata, core, interfaces Coverage: 83%

/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:91-140 — | orchestrata.orchestrator.* | orchestrata_ultimate.orchestrator.* | New package | | orchestrata.knowledge.* | orchestrata_ultimate.knowledge_graph.* | Replace graph.py stub | | orchestrata.session.* | orchestrata_ultimate.session.* | New package | | orchestrata.memory.* | orchestrata_ultimate.memory.* | New package | | orchestrata.gateway.* | orchestrata_ultimate.gateway.* | R...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/core/interfaces/components.py:1-33 — """ Core component interfaces for Orchestrata. This module is a thin alias layer: the canonical definitions (kernel, postman, orchestrator, and state-manager protocols, plus the forward-reference sentinels used to break circular dependencies) live in :mod:orchestrata_ultimate.core.protocols.components and are re-exported here under their historical names to preserve the public API. """ from ty...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/core/interfaces/__init__.py:1-50 — """ Core component interfaces for Orchestrata. These interfaces define the contract for all core components in the system. All components must implement these interfaces to ensure compatibility. This package is a re-export facade. The definitions live in domain submodules and are re-exported here to preserve the historical public API: * :mod:orchestrata_ultimate.core.interfaces.base — foundat...

Q58: What is the standard import translation from `orchestrata.volks.<role>`?

Category: Porting & AST Keywords: standard, import, translation, orchestrata, volks, role Coverage: 83%

/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:91-140 — | orchestrata.orchestrator.* | orchestrata_ultimate.orchestrator.* | New package | | orchestrata.knowledge.* | orchestrata_ultimate.knowledge_graph.* | Replace graph.py stub | | orchestrata.session.* | orchestrata_ultimate.session.* | New package | | orchestrata.memory.* | orchestrata_ultimate.memory.* | New package | | orchestrata.gateway.* | orchestrata_ultimate.gateway.* | R...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:4411-4460 — | orchestrata.core.infra_config | orchestrata_ultimate.core.config.infra | | orchestrata.core.base.entity | orchestrata_ultimate.core.domain.domain_entity | | orchestrata.core.base | orchestrata_ultimate.core.domain | | orchestrata.core.redis_factory | orchestrata_ultimate.core.redis | | orchestrata.core.lru_cache | orchestrata_ultimate.core.cache | | `orchestrata.core.monitori...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/class-mapping.json:1-50 — { "metadata": { "description": "Semantic mapping for deep AST comparison: orchestrata → orchestrata-ultimate", "source": "plans/implementation-plan.md (13 rounds of adversarial review)", "created": "2026-04-10" }, "class_mappings": { "BaseVolk": "BaseAgent", "BaseEntity": "DomainEntity", "AnalystVolk": "AnalystAgent", "SeniorDevVolk": "SeniorDevAgent", "Junior...

Q59: How are dynamic string literal imports handled during porting?

Category: Porting & AST Keywords: dynamic, string, literal, imports, handled, during, porting Coverage: 86%

/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:46-95 — -e 's/from orchestrata.core.state./from orchestrata_ultimate.core.state./g' \ -e 's/from orchestrata.core.monitoring/from orchestrata_ultimate.core.metrics/g' \ -e 's/from orchestrata.volks./from orchestrata_ultimate.agents.volks./g' \ -e 's/from orchestrata.agents.volks./from orchestrata_ultimate.agents.volks./g' \ -e 's/from orchestrata.provider./from orchestrata_ultimate.p...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:91-140 — | orchestrata.orchestrator.* | orchestrata_ultimate.orchestrator.* | New package | | orchestrata.knowledge.* | orchestrata_ultimate.knowledge_graph.* | Replace graph.py stub | | orchestrata.session.* | orchestrata_ultimate.session.* | New package | | orchestrata.memory.* | orchestrata_ultimate.memory.* | New package | | orchestrata.gateway.* | orchestrata_ultimate.gateway.* | R...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:2881-2930 — ### Sub-phase 2.3: Governance (Steps 125–137) --- ### Step 125: Prepare governance/ for real implementation Actions: 1. Keep $ULT/governance/__init__.py 2. The stub pam.py stays until Step 137 gate confirms real code works --- ### Step 126: Port policy_engine.py Source: $SRC/orchestrata-governance/src/orchestrata/governance/policy_engine.py Destination: `$ULT/governance/po...

Q60: What is the default value rule for `os.environ["REDIS_HOST"]`?

Category: Porting & AST Keywords: default, value, rule, environ, redis_host Coverage: 60%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/core/redis_factory.py:1-50 — """Thread-safe Redis client factory for Python 3.14t (free-threaded). Provides centralized construction of sync and async Redis clients with proper connection pooling for GIL-free environments. Sync clients use BlockingConnectionPool (thread-safe checkout). Async clients use redis.asyncio.ConnectionPool (asyncio serializes). Usage: from orchestrata_ultimate.core.redis_factory import ( ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:226-275 — Critical fix — infra_config.py lines 112-116: ```python # Before (crashes without env vars): REDIS_HOST = os.environ["REDIS_HOST"] # After (safe defaults): REDIS_HOST = os.environ.get("REDIS_HOST", "localhost") REDIS_PORT = int(os.environ.get("REDIS_PORT", "6379")) NEO4J_URI = os.environ.get("NEO4J_URI", "bolt://localhost:7687") NEO4J_USER = os.environ.get("NEO4J_USERNAME", "neo4j") NEO4J_PASSWO...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:496-545 — --- ### Step 15: Port infra_config.py to core/config/infra.py Goal: Port infrastructure configuration with safe environment variable defaults. Source: $SRC/orchestrata-core/src/orchestrata/core/infra_config.py Destination: $ULT/core/config/infra.py Actions: 1. bash cp $SRC/orchestrata-core/src/orchestrata/core/infra_config.py $ULT/core/config/infra.py 2. Apply...

Q61: What are the connection env vars for Neo4j?

Category: Knowledge Graph & Neo4j Keywords: connection, vars, neo4j Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/constants.py:1-46 — """Knowledge Graph configuration constants.""" import os # Spec: 008 - Knowledge Graph # Neo4j connection defaults. # The URI is built from NEO4J_HOST / NEO4J_PORT when NEO4J_URI is not set so # that no full connection URI literal appears in source. _NEO4J_HOST: str = os.environ.get("NEO4J_HOST", "localhost") _NEO4J_PORT: str = os.environ.get("NEO4J_PORT", "7687") NEO4J_URI: str = os.environ.ge...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/core/neo4j_factory.py:1-50 — """Neo4j driver factory. Creates sync or async Neo4j drivers from environment configuration. Real drivers only — no in-memory or fake fallbacks. """ from future import annotations import os from collections.abc import Mapping from typing import Any from neo4j import AsyncGraphDatabase, Auth, GraphDatabase, basic_auth # Sentinel for connections that are EXPLICITLY unauthenticated (e.g. Mem...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:541-590 — REDIS_HOST=10.92.53.10 REDIS_PORT=6379 NEO4J_URI=bolt://10.92.53.11:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=«redacted» **Loading is automatic** via `.envrc` + direnv. If direnv is unavailable, run:bash export $(cat .env | grep -v '^#' | xargs) **Code must read from env vars with localhost fallback:** python # Correct — tests and source REDIS_HOST = os.environ.get("REDIS_HOST",...

Q62: What is the `Neo4jSyncer` class responsible for?

Category: Knowledge Graph & Neo4j Keywords: neo4jsyncer, class, responsible Coverage: 67%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/sync.py:1-50 — # mypy: ignore-errors """Neo4jSyncer — sync serialized AST JSON into Neo4j knowledge graph. 12 node types, 18 relationship types, nodes-first-edges-second pattern. """ from future import annotations import logging import os from pathlib import Path from typing import Any from orchestrata_ultimate.core.base.traces import traces from orchestrata_ultimate.core.graph import GraphRepositoryConf...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/session-and-kg-sync.md:1-50 — # Knowledge-Graph Sync & Session Tooling This document covers two related changes landed in commit c831b88c: 1. Extended Neo4jSyncer AST-to-Neo4j sync (richer Project/Module nodes plus real Package→Module and Module→Class/Function/Method edges). 2. Session tooling that auto-detects a project root and auto-creates the session/context files on start. Both are grounded in the a...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/CODEBASE_MAP_FULL.md:316-365 — /home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/context_pack/frame.py:83: class LinkedEntity /home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/context_pack/frame.py:102: class RequestFrame /home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/context_pack...

Q63: How many node types and relationship types does the Neo4j sync engine use?

Category: Knowledge Graph & Neo4j Keywords: many, node, types, relationship, neo4j, sync, engine Coverage: 86%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/sync.py:1-50 — # mypy: ignore-errors """Neo4jSyncer — sync serialized AST JSON into Neo4j knowledge graph. 12 node types, 18 relationship types, nodes-first-edges-second pattern. """ from future import annotations import logging import os from pathlib import Path from typing import Any from orchestrata_ultimate.core.base.traces import traces from orchestrata_ultimate.core.graph import GraphRepositoryConf...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/session-and-kg-sync.md:1-50 — # Knowledge-Graph Sync & Session Tooling This document covers two related changes landed in commit c831b88c: 1. Extended Neo4jSyncer AST-to-Neo4j sync (richer Project/Module nodes plus real Package→Module and Module→Class/Function/Method edges). 2. Session tooling that auto-detects a project root and auto-creates the session/context files on start. Both are grounded in the a...
/home/mohamed/workspace/orchestrata-ultimate-architecture/architecture/architecture-remediation/2026-04-07-architecture-remediation/2026-04-07-class-level-design.md:406-455 — Resolves: Neo4j abstraction gap — Redis has 6 ports but Neo4j had only IAuditPort. The existing IKnowledgeGraph protocol in knowledge/interfaces.py is already well-designed; this port mirrors it in core/ports/ for architectural symmetry. Source of truth: knowledge/interfaces.py::IKnowledgeGraph (6 async methods), knowledge/types_nodes.py::Node (7 fields), `knowledge/types_enums...

Q64: What is the nodes-first-edges-second pattern in the sync engine?

Category: Knowledge Graph & Neo4j Keywords: nodes, first, edges, second, pattern, sync, engine Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/session-and-kg-sync.md:1-50 — # Knowledge-Graph Sync & Session Tooling This document covers two related changes landed in commit c831b88c: 1. Extended Neo4jSyncer AST-to-Neo4j sync (richer Project/Module nodes plus real Package→Module and Module→Class/Function/Method edges). 2. Session tooling that auto-detects a project root and auto-creates the session/context files on start. Both are grounded in the a...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/sync.py:1-50 — # mypy: ignore-errors """Neo4jSyncer — sync serialized AST JSON into Neo4j knowledge graph. 12 node types, 18 relationship types, nodes-first-edges-second pattern. """ from future import annotations import logging import os from pathlib import Path from typing import Any from orchestrata_ultimate.core.base.traces import traces from orchestrata_ultimate.core.graph import GraphRepositoryConf...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/sync.py:226-275 — # Phase 1: Nodes (packages, modules, classes, functions, methods, params) nodes_created = self._sync_packages(project, packages) nodes_created += self._sync_modules(project, ast_data.get("modules", [])) nodes_created += self._sync_classes(project, ast_data.get("modules", [])) nodes_created += self._sync_functions(project, ast_data.get("modules", [])) ...

Q65: How does the codebase prevent Neo4j `CREATE` without `test_id`?

Category: Knowledge Graph & Neo4j Keywords: codebase, prevent, neo4j, create, without, test_id Coverage: 83%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/PROPOSED_DIAGNOSTIC_TOOLS.md:46-95 — - Cleanup query: MATCH (n {test_id: $test_id}) DETACH DELETE n SUSPECTED INTERFERENCE: - 12 other tests create Project nodes with name "orchestrata" - _build_monorepo_context queries: MATCH (proj:Project {name: 'orchestrata'}) RECOMMENDED FIX: 1. Add retry logic for EntityNotFound in Neo4jClient._execute() 2. Or make _build_monorepo_context accept an optional test_id filter ``` --- #...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/DIAGNOSTIC_PLAYBOOK.md:91-140 — ``` Ask these questions: 1. Does the fixture clean up after itself? 2. Is the cleanup scoped to function, class, or session? 3. Does cleanup use a unique ID (like test_id) or delete globally? 4. Could two parallel tests interfere through this fixture? --- ## Step 5: Check External Service Constraints (2 minutes) If the test uses Neo4j, Redis, or another service, check for constraints: ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/PROPOSED_DIAGNOSTIC_TOOLS.md:226-253 — Fixture used: neo4j_client (function scope, cleanup: DETACH DELETE by test_id) Suspect tests: 12 other tests create Project nodes with name "orchestrata" Recommendation: Add retry logic or filter queries by test_id -------------------------------------------------------------------- ``` --- ## Implementation Priority | Tool | Effort | Impact | Priority | |------|--------|--------|----------| |...

Q66: What command verifies knowledge graph connectivity?

Category: Knowledge Graph & Neo4j Keywords: command, verifies, knowledge, graph, connectivity Coverage: 60%

/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:3736-3785 — Verify: python -c "from orchestrata_ultimate.knowledge_graph.search import *; print('OK')" --- ### Step 182: Port kg_design.py, schema.py, relationships.py Actions: Copy all three, translate Verify: python -c "from orchestrata_ultimate.knowledge_graph.kg_design import *; print('OK')" --- ### Step 183: Port type modules Source: types.py, types_nodes.py, types_enums.py, no...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/kernel/cli_main.py:856-905 — @traces(spec="000", story="US-007", reqs=["REQ-000-062"]) def log() -> None: """Show governance decision history.""" click.echo("No governance decisions found") @governance.command() @traces(spec="000", story="US-007", reqs=["REQ-000-064"]) def policies() -> None: """List active governance policies.""" click.echo("No governance policies loaded") # ── VERIFY COMMAND ────────────...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/session/cli/kg.py:1-50 — # mypy: ignore-errors """Knowledge graph sync command and query group for the session CLI.""" from future import annotations import json import sys from typing import TYPE_CHECKING import click from orchestrata_ultimate.core.base.traces import traces if TYPE_CHECKING: from orchestrata_ultimate.session.kg_context import KnowledgeGraphContext from orchestrata_ultimate.session.kg_syn...

Q67: Where is the single source of truth for service IPs and ports?

Category: Knowledge Graph & Neo4j Keywords: single, source, truth, service, ports Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:226-275 — | Neo4j | bolt://10.92.53.11:7687 | neo4j-db | The single source of truth is .env at the repo root, loaded automatically via .envrc + direnv (AGENTS.md:469-483). tests/conftest.py:33-35 loads .env with override=True before any test imports, then fast-fails if any of these are missing or empty (tests/conftest.py:42-54): ``` REDIS_HOST REDIS_PORT NEO4J_URI NEO4J_USE...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:1-50 — # AGENTS.md — Guide for AI Coding Agents > Read this before executing any step of the execution plan. > ## ⛔ CRITICAL — NEVER use pytest-xdist (-n / --dist) > pytest -n auto (xdist) deadlocks this suite (~78% stall) and is banned. > Run tests ONLY via the supported runners: > - python scripts/run_tests.py — primary: infra check + safety gates + batched executor (~7 min) >...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:541-590 — REDIS_HOST=10.92.53.10 REDIS_PORT=6379 NEO4J_URI=bolt://10.92.53.11:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=«redacted» **Loading is automatic** via `.envrc` + direnv. If direnv is unavailable, run:bash export $(cat .env | grep -v '^#' | xargs) **Code must read from env vars with localhost fallback:** python # Correct — tests and source REDIS_HOST = os.environ.get("REDIS_HOST",...

Q68: What is the default Neo4j URI fallback if env var is missing?

Category: Knowledge Graph & Neo4j Keywords: default, neo4j, fallback, missing Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/gateway/config.py:46-95 — SPEC-099 (P0): a deploy that forgets to set JWT_SECRET must not silently accept the well-known "dev-secret" default -- anyone who knows that default could then forge valid tokens. The default is permitted only in a recognized dev/test context (see :func:_dev_secret_allowed); anywhere else, a missing/default secret is a startup error naming the fix. Raises: ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/core/neo4j_factory.py:1-50 — """Neo4j driver factory. Creates sync or async Neo4j drivers from environment configuration. Real drivers only — no in-memory or fake fallbacks. """ from future import annotations import os from collections.abc import Mapping from typing import Any from neo4j import AsyncGraphDatabase, Auth, GraphDatabase, basic_auth # Sentinel for connections that are EXPLICITLY unauthenticated (e.g. Mem...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/constants.py:1-46 — """Knowledge Graph configuration constants.""" import os # Spec: 008 - Knowledge Graph # Neo4j connection defaults. # The URI is built from NEO4J_HOST / NEO4J_PORT when NEO4J_URI is not set so # that no full connection URI literal appears in source. _NEO4J_HOST: str = os.environ.get("NEO4J_HOST", "localhost") _NEO4J_PORT: str = os.environ.get("NEO4J_PORT", "7687") NEO4J_URI: str = os.environ.ge...

Q69: How are test_id-based cleanups performed in Neo4j tests?

Category: Knowledge Graph & Neo4j Keywords: test_id, based, cleanups, performed, neo4j, tests Coverage: 67%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/PROPOSED_DIAGNOSTIC_TOOLS.md:46-95 — - Cleanup query: MATCH (n {test_id: $test_id}) DETACH DELETE n SUSPECTED INTERFERENCE: - 12 other tests create Project nodes with name "orchestrata" - _build_monorepo_context queries: MATCH (proj:Project {name: 'orchestrata'}) RECOMMENDED FIX: 1. Add retry logic for EntityNotFound in Neo4jClient._execute() 2. Or make _build_monorepo_context accept an optional test_id filter ``` --- #...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/SESSION_CONTEXT.md:1-50 — # Session Context — 2026-04-28 > Purpose: Capture the full state of the project so work can resume after a context window reset. > Last action: Tagged v1.0.0, pushed to GitLab. Stage 2 complete. > Next decision needed: Define Stage 3 (CI/CD hardening, deployment, or performance). --- ## 1. Current Status | Phase | Status | Notes | |-------|--------|-------| | Stage 2: Syntax Erro...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/core/standards.py:136-185 — 32. Tests present and correct. Clear assertions. No false positives. NO MOCKING — test real behavior only. 32b. TEST CLEANUP: Use tmp_path pytest fixture for temporary files. 32c. NO MONKEY-PATCHING: Use real error conditions, not method replacement. --- Traceability --- 33. TRACEABILITY: Every class and every public function MUST have a @traces(spec=..., story=..., reqs=[...]) decorato...

Q70: What is the relationship between `sync_ast_to_neo4j.py` and `knowledge_graph/sync.py`?

Category: Knowledge Graph & Neo4j Keywords: relationship, between, sync_ast_to_neo4j, knowledge_graph, sync Coverage: 60%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/session-and-kg-sync.md:1-50 — # Knowledge-Graph Sync & Session Tooling This document covers two related changes landed in commit c831b88c: 1. Extended Neo4jSyncer AST-to-Neo4j sync (richer Project/Module nodes plus real Package→Module and Module→Class/Function/Method edges). 2. Session tooling that auto-detects a project root and auto-creates the session/context files on start. Both are grounded in the a...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/CODEBASE_MAP_FULL.md:361-410 — /home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/server.py:22: async def _serve() -> None /home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/server.py:45: def main(argv: list[str] | None=None) -> None /home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/sy...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/knowledge_graph/sync.py:1-50 — # mypy: ignore-errors """Neo4jSyncer — sync serialized AST JSON into Neo4j knowledge graph. 12 node types, 18 relationship types, nodes-first-edges-second pattern. """ from future import annotations import logging import os from pathlib import Path from typing import Any from orchestrata_ultimate.core.base.traces import traces from orchestrata_ultimate.core.graph import GraphRepositoryConf...

Q71: What is the renamed class for `BaseVolk` in the target codebase?

Category: Agents & Volks Keywords: renamed, class, basevolk, target, codebase Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/faq/basevolk-rename.md:1-8 — --- title: What is the renamed class for BaseVolk in the target codebase? description: Mapping from the old BaseVolk class to the new BaseAgent class. --- # What is the renamed class for BaseVolk in the target codebase? The BaseVolk class from the source orchestrata monorepo is renamed to BaseAgent in orchestrata-ultimate. This is part of the broader rename where all *Volk classe...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:4411-4460 — | orchestrata.core.infra_config | orchestrata_ultimate.core.config.infra | | orchestrata.core.base.entity | orchestrata_ultimate.core.domain.domain_entity | | orchestrata.core.base | orchestrata_ultimate.core.domain | | orchestrata.core.redis_factory | orchestrata_ultimate.core.redis | | orchestrata.core.lru_cache | orchestrata_ultimate.core.cache | | `orchestrata.core.monitori...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/class-mapping.json:1-50 — { "metadata": { "description": "Semantic mapping for deep AST comparison: orchestrata → orchestrata-ultimate", "source": "plans/implementation-plan.md (13 rounds of adversarial review)", "created": "2026-04-10" }, "class_mappings": { "BaseVolk": "BaseAgent", "BaseEntity": "DomainEntity", "AnalystVolk": "AnalystAgent", "SeniorDevVolk": "SeniorDevAgent", "Junior...

Q72: What is the base class for agents: Pydantic BaseModel or dataclass?

Category: Agents & Volks Keywords: base, class, agents, pydantic, basemodel, dataclass Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/agents/volks/base.py:1-50 — # mypy: ignore-errors """Base agent class. Inherits from Pydantic BaseModel for validation, serialization, and identity. """ from future import annotations import logging import re from datetime import UTC, datetime from pathlib import Path from typing import TYPE_CHECKING, Any from uuid import UUID, uuid4 from pydantic import BaseModel, ConfigDict, Field, PrivateAttr from orchestrata_ult...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:136-185 — | ConciergeVolk | ConciergeAgent | Rename | | ComplianceVolk | ComplianceAgent | Rename | | OrchestrationKernel | OrchestrataKernel | Replace ultimate's stub | | PolicyEngine | GovernanceEngine | Replace ultimate's stub | | Neo4jClient | Neo4jGraph | Replace ultimate's stub | | ProviderManager | ProviderManager | Replace ultimate's stub | | VolkRuntime/Pool/Registry | `Ag...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:2026-2075 — raise RuntimeError(f"{self.alias}: postman not set — cannot send") return await self._postman.aroute(packet) async def emit_event(self, event_type: str, payload: dict | None = None) -> None: """Emit a system event via CXP. Wired to EventBus in Tier 2.""" if self.postman is not None and payload is not None: from orchestrata...

Q73: How many role volks are being ported?

Category: Agents & Volks Keywords: many, role, volks, being, ported Coverage: 60%

/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:316-365 — Port agents base: volks/base.py → merge into BaseAgent (CXPMixin pattern). Source clarification: Some volks exist in BOTH orchestrata-agents/volks/ (inline) AND as separate packages (orchestrata-<role>/). Port from the separate packages — they're the canonical, most complete versions. senior_dev.py is an exception: it only exists in orchestrata-agents/volks/senior_dev.py (no sep...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:2206-2255 — 1. Copy volk.py and _pipeline.py, apply standard import translation 2. Rename ComplianceVolk → ComplianceAgent Verify: python -c "from orchestrata_ultimate.agents.volks.compliance.volk import ComplianceAgent; print('OK')" --- ### Step 84: Port concierge volk Source: $SRC/orchestrata-concierge/src/orchestrata/volks/concierge/ Destination: $ULT/agents/volks/concierge/ **Ac...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:271-320 — ### Tier 1: Agents That Talk and Think (~37,000 LOC) Goal: Agents make real LLM calls, coordinate via CXP. Done when: ultimate intent "write tests for X" produces real LLM output in <30s. #### 1.1: CXP Protocol (9,525 LOC, skip gRPC) Port: packet.py, json_serializer.py, exceptions.py, headers.py, payload.py, threads.py, validator.py. Skip: proto/, grpc_client.py, grpc_server.py, binary...

Q74: What is the import translation for `orchestrata.volks.analyst.volk`?

Category: Agents & Volks Keywords: import, translation, orchestrata, volks, analyst, volk Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:91-140 — | orchestrata.orchestrator.* | orchestrata_ultimate.orchestrator.* | New package | | orchestrata.knowledge.* | orchestrata_ultimate.knowledge_graph.* | Replace graph.py stub | | orchestrata.session.* | orchestrata_ultimate.session.* | New package | | orchestrata.memory.* | orchestrata_ultimate.memory.* | New package | | orchestrata.gateway.* | orchestrata_ultimate.gateway.* | R...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:2116-2165 — Why here: codedirector/volk.py:6 has from orchestrata.agents.swarm.coordinator import _is_source_file (top-level import). codedirector/implementation.py:7 imports SwarmCoordinator. Both are hard dependencies — CodeDirector cannot import without swarm. --- ### Step 80: Port analyst volk Source: $SRC/orchestrata-analyst/src/orchestrata/volks/analyst/ (volk.py, parsers.py, prompt...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:4411-4460 — | orchestrata.core.infra_config | orchestrata_ultimate.core.config.infra | | orchestrata.core.base.entity | orchestrata_ultimate.core.domain.domain_entity | | orchestrata.core.base | orchestrata_ultimate.core.domain | | orchestrata.core.redis_factory | orchestrata_ultimate.core.redis | | orchestrata.core.lru_cache | orchestrata_ultimate.core.cache | | `orchestrata.core.monitori...

Q75: What pattern replaces ABC interfaces in the target codebase?

Category: Agents & Volks Keywords: pattern, replaces, interfaces, target, codebase Coverage: 80%

/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:136-185 — | ConciergeVolk | ConciergeAgent | Rename | | ComplianceVolk | ComplianceAgent | Rename | | OrchestrationKernel | OrchestrataKernel | Replace ultimate's stub | | PolicyEngine | GovernanceEngine | Replace ultimate's stub | | Neo4jClient | Neo4jGraph | Replace ultimate's stub | | ProviderManager | ProviderManager | Replace ultimate's stub | | VolkRuntime/Pool/Registry | `Ag...
/home/mohamed/workspace/orchestrata-ultimate-architecture/architecture/architecture-remediation/2026-04-07-architecture-remediation/2026-04-07-class-level-design.md:1756-1805 — │ ├── IGraphPort (core/ports/graph.py) ★ NEW — mirrors knowledge/interfaces.py::IKnowledgeGraph ├── IGraphQueryPort (core/ports/graph_query.py) ★ NEW — mirrors knowledge/interfaces.py::IQueryEngine ├── IGraphTemporalPort (core/ports/graph_temporal.py) ★ NEW — mirrors knowledge/interfaces.py::ITemporalManager ├── ICodeAnalysisPort (core/ports/code_analysis.py) ★ NEW — m...
/home/mohamed/workspace/orchestrata-ultimate-architecture/architecture/modular-monolith.md:46-95 — | Exceptions | Full exception hierarchy | | Domain entities | DomainEntity, Node | The critical insight: Protocol definitions are currently scattered across the codebase: - core/protocols.py — core protocols - agents/protocols.py — agent protocols - postman/interfaces.py — 1,358 LOC of postman ABCs - governance/interfaces.py — governance ABCs - verification/ types scattered across s...

Q76: What is the `CXPMixin` used for in `BaseAgent`?

Category: Agents & Volks Keywords: cxpmixin, used, baseagent Coverage: 67%

/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/implementation-plan.md:136-185 — | ConciergeVolk | ConciergeAgent | Rename | | ComplianceVolk | ComplianceAgent | Rename | | OrchestrationKernel | OrchestrataKernel | Replace ultimate's stub | | PolicyEngine | GovernanceEngine | Replace ultimate's stub | | Neo4jClient | Neo4jGraph | Replace ultimate's stub | | ProviderManager | ProviderManager | Replace ultimate's stub | | VolkRuntime/Pool/Registry | `Ag...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:1981-2030 — Destination: $ULT/agents/constraints.py Actions: 1. Copy, apply standard import translation Verify: python -c "from orchestrata_ultimate.agents.constraints import *; print('OK')" --- ### Step 77: Create CXPMixin and merge into BaseAgent Goal: Add CXP communication methods to BaseAgent via CXPMixin. File: $ULT/agents/base_agent.py Actions: 1. Read current `$ULT/...
/home/mohamed/workspace/orchestrata-ultimate-architecture/plans/execution-plan.md:2026-2075 — raise RuntimeError(f"{self.alias}: postman not set — cannot send") return await self._postman.aroute(packet) async def emit_event(self, event_type: str, payload: dict | None = None) -> None: """Emit a system event via CXP. Wired to EventBus in Tier 2.""" if self.postman is not None and payload is not None: from orchestrata...

Q77: What is the `agents/lifecycle.py` module responsible for?

Category: Agents & Volks Keywords: agents, lifecycle, module, responsible Coverage: 0%

Q78: How are agents created and configured according to sample search results?

Category: Agents & Volks Keywords: agents, created, configured, according, sample, search, results Coverage: 0%

Q79: What is the difference between `agents/swarm` and `agents/volks`?

Category: Agents & Volks Keywords: difference, between, agents, swarm, volks Coverage: 0%

Q80: What design decision replaced the 26-package monorepo with a single package?

Category: Agents & Volks Keywords: design, decision, replaced, package, monorepo, single Coverage: 0%

Q81: What does CXP stand for and what are its main components?

Category: CXP & Protocols Keywords: stand, main, components Coverage: 0%

Q82: What is a `CXPPacket`?

Category: CXP & Protocols Keywords: cxppacket Coverage: 0%

Q83: Where is the protobuf definition located?

Category: CXP & Protocols Keywords: protobuf, definition, located Coverage: 0%

Q84: What is the role of the CXP serializer?

Category: CXP & Protocols Keywords: role, serializer Coverage: 0%

Q85: How does the CXP dispatcher route packets?

Category: CXP & Protocols Keywords: dispatcher, route, packets Coverage: 0%

Q86: What Incus container runs Redis?

Category: Infrastructure & Deployment Keywords: incus, container, runs, redis Coverage: 0%

Q87: What Incus container runs Neo4j?

Category: Infrastructure & Deployment Keywords: incus, container, runs, neo4j Coverage: 0%

Q88: What command starts all four test services in parallel?

Category: Infrastructure & Deployment Keywords: command, starts, four, test, services, parallel Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:46-95 — ### Service Management Protocols | Protocol | Pattern | |----------|---------| | PID file | Write on start, validate with os.kill(pid, 0) | | Health check | Application-level (e.g. gateway.ping RPC), not just port | | Readiness | Wait for health check response, not just TCP accept | | Graceful shutdown | SIGTERM → drain 10s → SIGKILL → cleanup PID | | Idempotent start | Check PID + port + he...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/development-and-testing.md:226-275 — | Neo4j | bolt://10.92.53.11:7687 | neo4j-db | The single source of truth is .env at the repo root, loaded automatically via .envrc + direnv (AGENTS.md:469-483). tests/conftest.py:33-35 loads .env with override=True before any test imports, then fast-fails if any of these are missing or empty (tests/conftest.py:42-54): ``` REDIS_HOST REDIS_PORT NEO4J_URI NEO4J_USE...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:541-590 — REDIS_HOST=10.92.53.10 REDIS_PORT=6379 NEO4J_URI=bolt://10.92.53.11:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=«redacted» **Loading is automatic** via `.envrc` + direnv. If direnv is unavailable, run:bash export $(cat .env | grep -v '^#' | xargs) **Code must read from env vars with localhost fallback:** python # Correct — tests and source REDIS_HOST = os.environ.get("REDIS_HOST",...

Q89: How do you check service status without failing if services are down?

Category: Infrastructure & Deployment Keywords: check, service, status, without, failing, services, down Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:586-635 — bash python scripts/start_test_services.py # Start all services python scripts/start_test_services.py --status # Check only (exit 0 even if down) python scripts/start_test_services.py --json # JSON report python scripts/start_test_services.py --skip kernel,gateway # Skip services scripts/run_tests.py auto-starts all services before tests. Use `--skip-services kern...
/home/mohamed/workspace/orchestrata-ultimate-architecture/AGENTS.md:46-95 — ### Service Management Protocols | Protocol | Pattern | |----------|---------| | PID file | Write on start, validate with os.kill(pid, 0) | | Health check | Application-level (e.g. gateway.ping RPC), not just port | | Readiness | Wait for health check response, not just TCP accept | | Graceful shutdown | SIGTERM → drain 10s → SIGKILL → cleanup PID | | Idempotent start | Check PID + port + he...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/postman/health.py:91-140 — async def check_neo4j(self) -> dict[str, Any]: """Check Neo4j connection.""" try: from orchestrata_ultimate.core.graph import ( GraphRepositoryConfig, create_async_graph_repository, ) repo = create_async_graph_repository( GraphRepositoryConfig( uri=self._neo4j_uri ...

Q90: What is the Memgraph HA cluster composed of?

Category: Infrastructure & Deployment Keywords: memgraph, cluster, composed Coverage: 67%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:1-50 — # Memgraph HA Cluster This document describes the three-node Memgraph Community high-availability cluster used by orchestrata-ultimate for the semantic graph / RAG backend. It covers how the cluster was created, how replication works, how failover and autofailback work, and how to operate it. > Deployment status (2026-07-11): the memgraph-1/2/3 + memgraph-ha > controller cluster descri...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:136-185 — system library without this. 5. Enable and start memgraph.service. --- ## 4. How replication works Memgraph Community replication is single MAIN, many REPLICAs. The MAIN node accepts writes; replicas replay a stream of deltas from MAIN. ### 4.1 Replication setup The HA controller issues the following Cypher commands after selecting a MAIN: 1. On each replica candidate: ```cypher SE...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:406-413 — | incus/memgraph-cluster-launch.sh | Launch 3 data nodes + HA controller | | incus/memgraph-node-launch.sh | Launch or start one Memgraph data node | | incus/memgraph-launch.sh | Launch a standalone single-node Memgraph | | src/orchestrata_ultimate/semantic_graph/ha_controller.py | HA controller core | | src/orchestrata_ultimate/semantic_graph/ha_controller_cli.py | HA controller CLI / s...

Q91: What is the Memgraph HA controller URL?

Category: Infrastructure & Deployment Keywords: memgraph, controller Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:361-410 — # Comma-separated coordinator bolt URIs -- main_discovery.resolve_main() # probes these with SHOW INSTANCES to find the MAIN data instance directly. MEMGRAPH_URIS=neo4j://:7691,neo4j://:7691,neo4j://:7691 # Legacy HTTP controller URL -- leave blank; orchgraph has none. MEMGRAPH_HA_CONTROLLER_URL= ``` If Incus reassigns IPs after a host r...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:271-320 — ## 7. HA controller HTTP API The controller exposes a small FastAPI app. | Endpoint | Method | Response | |----------|--------|----------| | /status | GET | Full cluster status including node health | | /main | GET | {"main": "<current-main-name>", "uri": "bolt://<current-main-host>:7687"} -- MAIN is dynamic; never pin a name/host from this shape | | /failover | POST | Force a failover ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:46-95 — ## 2. Cluster layout > Historical snapshot — this cluster was decommissioned 2026-07-10. The > table and MAIN/REPLICA roles below are a point-in-time record, not the live > topology. Never treat a container name here as "the" MAIN — see the status > callout at the top of this document. | Container | Role (as of 2026-07-08, historical) | Bolt URI | Replication address | |-----------|------|-...

Q92: Why did the standalone `memgraph-db` container need to be restarted during this work?

Category: Infrastructure & Deployment Keywords: standalone, memgraph, container, need, restarted, during, work Coverage: 43%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:91-140 — | incus/memgraph-launch.sh | Create a standalone single-node Memgraph (separate) | ### 3.2 Creating the cluster from scratch bash ./incus/memgraph-cluster-launch.sh This script (incus/memgraph-cluster-launch.sh:1) performs the following steps: 1. Launch memgraph-1, memgraph-2, and memgraph-3 via memgraph-node-launch.sh. 2. Collect the Incus-assigned IP for each node. 3. L...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:46-95 — ## 2. Cluster layout > Historical snapshot — this cluster was decommissioned 2026-07-10. The > table and MAIN/REPLICA roles below are a point-in-time record, not the live > topology. Never treat a container name here as "the" MAIN — see the status > callout at the top of this document. | Container | Role (as of 2026-07-08, historical) | Bolt URI | Replication address | |-----------|------|-...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/semantic_graph/adapters/memgraph.py:766-815 — WHERE c.id IS NOT NULL AND c.chunk_id IS NULL AND NOT (c)-[:DERIVED_FROM]->() DETACH DELETE c """).consume() await self._execute_with_reconnect(_delete) return len(stale) async def _drop_vector_index(self) -> None: """Drop the native vector index...

Q93: What command launches a Memgraph container from the project?

Category: Infrastructure & Deployment Keywords: command, launches, memgraph, container, project Coverage: 60%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:406-413 — | incus/memgraph-cluster-launch.sh | Launch 3 data nodes + HA controller | | incus/memgraph-node-launch.sh | Launch or start one Memgraph data node | | incus/memgraph-launch.sh | Launch a standalone single-node Memgraph | | src/orchestrata_ultimate/semantic_graph/ha_controller.py | HA controller core | | src/orchestrata_ultimate/semantic_graph/ha_controller_cli.py | HA controller CLI / s...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:46-95 — ## 2. Cluster layout > Historical snapshot — this cluster was decommissioned 2026-07-10. The > table and MAIN/REPLICA roles below are a point-in-time record, not the live > topology. Never treat a container name here as "the" MAIN — see the status > callout at the top of this document. | Container | Role (as of 2026-07-08, historical) | Bolt URI | Replication address | |-----------|------|-...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/memgraph-ha-cluster.md:91-140 — | incus/memgraph-launch.sh | Create a standalone single-node Memgraph (separate) | ### 3.2 Creating the cluster from scratch bash ./incus/memgraph-cluster-launch.sh This script (incus/memgraph-cluster-launch.sh:1) performs the following steps: 1. Launch memgraph-1, memgraph-2, and memgraph-3 via memgraph-node-launch.sh. 2. Collect the Incus-assigned IP for each node. 3. L...

Q94: How is the wiki.js instance accessed?

Category: Infrastructure & Deployment Keywords: wiki, instance, accessed Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/faq/wiki-js-access.md:1-14 — --- title: How is the wiki.js instance accessed? description: URLs and access methods for the shared knowledge wiki. --- # How is the wiki.js instance accessed? The shared knowledge wiki is a Wiki.js instance running in an Incus container: - Human UI: http://172.16.0.26:3000 - GraphQL API: http://172.16.0.26:3000/graphql - Git repository: ~/workspace/knowledge-wiki Agents use the...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/wiki-integration.md:1-50 — # Wiki Integration — Shared Knowledge Wiki The project is integrated with a shared knowledge wiki at ~/workspace/knowledge-wiki. The wiki is powered by Wiki.js (human UI + GraphQL API) and backed by a local Git repository. It is designed to be readable and writable by multiple agents — Kimi, Claude, DeepSeek, OpenCode, and humans — using a small set of CLIs. This document describes the wik...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/wiki-integration.md:91-140 — Wiki.js GraphQL API so pages appear in the human UI. Configuration is read from ~/.wiki-cli/config.toml or environment variables: bash WIKI_URL=http://172.16.0.26:3000 WIKI_USER=admin@knowledge.local WIKI_PASS=admin123! ### Commands ```bash # List all pages wiki list # Get a page wiki get home wiki get infrastructure/memgraph-cluster # Search pages by path/title/description wiki sea...

Q95: What is the wiki graph indexer built on?

Category: Infrastructure & Deployment Keywords: wiki, graph, indexer, built Coverage: 75%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/wiki-integration.md:181-230 — project:<slug>. --- ## 6. Graph indexer — wiki → Memgraph The indexer at ~/workspace/knowledge-wiki/graph-indexer/indexer.py walks the wiki markdown files and writes a typed knowledge graph into the Memgraph HA cluster. This lets agents query the wiki structurally ("what decisions depend on the Memgraph service?") and semantically (via the RAG pipeline). ### 6.1 Node labels | Label | Ke...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/wiki-integration.md:1-50 — # Wiki Integration — Shared Knowledge Wiki The project is integrated with a shared knowledge wiki at ~/workspace/knowledge-wiki. The wiki is powered by Wiki.js (human UI + GraphQL API) and backed by a local Git repository. It is designed to be readable and writable by multiple agents — Kimi, Claude, DeepSeek, OpenCode, and humans — using a small set of CLIs. This document describes the wik...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/wiki-integration.md:361-382 — wiki-kimi validate wiki-kimi index ``` 6. Update agents/shared-handoff.md if transferring work. 7. Log the artifact and end the session with session end. 8. Commit and push knowledge-wiki to GitLab. --- ## 11. File index | File | Purpose | |------|---------| | ~/workspace/knowledge-wiki/wiki-cli/wiki_cli/cli.py | wiki CLI | | `~/workspace/knowledge-wiki/wiki-cli/wiki_cli/cli...

Q96: What is the rule about silent exception handlers?

Category: Code Standards & Patterns Keywords: rule, about, silent, exception, handlers Coverage: 100%

/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/faq/silent-exception-handlers.md:1-8 — --- title: What is the rule about silent exception handlers? description: The project rule that forbids swallowing exceptions. --- # What is the rule about silent exception handlers? Never use except: pass or except Exception: pass. Every exception handler must either log the actual error with context or re-raise the exception. This rule is checked by `verification/review/checks_structure.py...
/home/mohamed/workspace/orchestrata-ultimate-architecture/docs/faq/bare-except-handlers.md:1-13 — --- title: How does the project enforce the rule against bare exception handlers? description: Enforcement mechanism for the ban on silent exception handlers. --- # How does the project enforce the rule against bare exception handlers? The rule against except: pass and except Exception: pass is enforced in two places: 1. Static review: `src/orchestrata_ultimate/verification/review/check...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/verification/review/checks_structure.py:181-230 — def _is_stub_body(body: list[ast.stmt]) -> bool: """Return True if the function body is a stub. A stub is a method that only contains: - docstrings - pass statements - logging calls - local variable assignments - return statements with constructor calls (no external function calls) If there's an await or external function/method call, it's doing real work. ""...

Q97: Why is `os.environ["X"]` forbidden in favor of `os.environ.get("X", default)`?

Category: Code Standards & Patterns Keywords: environ, forbidden, favor, default Coverage: 50%

/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/verification/review/checks_safety.py:91-140 — """Check 30c: CONFIG -- bare os.environ["X"] subscript reads. Reading os.environ["X"] raises KeyError when the variable is unset (fresh checkout, CI), which is the most common config-time crash. Env reads MUST use os.environ.get("X", default) so a sensible fallback applies (see standards rule 30/30c and the AGENTS.md table). Args: filepath: Absolut...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/verification/review/checks_safety.py:46-95 — lines: list[str], ) -> list[Issue]: """Check 30: SECURITY -- eval/exec, hardcoded secrets. Args: filepath: Absolute path to the file. tree: Parsed AST module. lines: File lines. Returns: List of security issues found. """ issues: list[Issue] = [] rel_name = os.path.basename(filepath) for node in ast.walk(tree): if ( ...
/home/mohamed/workspace/orchestrata-ultimate-architecture/src/orchestrata_ultimate/gateway/config.py:46-95 — SPEC-099 (P0): a deploy that forgets to set JWT_SECRET must not silently accept the well-known "dev-secret" default -- anyone who knows that default could then forge valid tokens. The default is permitted only in a recognized dev/test context (see :func:_dev_secret_allowed); anywhere else, a missing/default secret is a startup error naming the fix. Raises: ...

Q98: What is the factory pattern used for external services?

Category: Code Standards & Patterns Keywords: factory, pattern, used, external, services Coverage: 0%

Q99: What is the UUID-prefixed resource pattern for tests?

Category: Code Standards & Patterns Keywords: uuid, prefixed, resource, pattern, tests Coverage: 0%

Q100: What is the project's policy on dismissing test failures?

Category: Code Standards & Patterns Keywords: project, policy, dismissing, test, failures Coverage: 0%

Semantic Graph Q&A Results (Latest: Hybrid Vector + Keyword + Module Graph)

Plan text

Semantic Graph Q&A Results (Latest: Hybrid Vector + Keyword + Module Graph)

Q1: Why must the Gateway never serve HTML, JS, or CSS?

Q2: How does VizInt UI communicate with the Gateway if they run on different ports?

Q3: What is the exact port and protocol for each service: VizInt UI, Gateway, Kernel, Redis, Neo4j?

Q4: Why is the gRPC kernel required to be out-of-process from the Gateway?

Q5: What is the fallback when the gRPC kernel is unreachable?

Q6: Why are hardcoded service IPs and ports forbidden in this codebase?

Q7: How does the project enforce the rule against except: pass and except Exception: pass?

Q8: What is the three-tier gRPC logging policy for the Gateway?

Q9: How does the Gateway health check authenticate instead of bypassing auth?

Q10: What is the PID file protocol for long-running services?

Q11: Why must readiness wait for an application-level health check rather than just TCP accept?

Q12: What is the graceful shutdown sequence for services?

Q13: How is idempotent start implemented for test services?

Q14: What action is taken when a port is in use by a foreign process?

Q15: Why must subprocess.DEVNULL never be used for service logs?

Q16: What does SessionController.begin() do automatically regarding unclosed sessions?

Q17: What are the five checklist items validated by SessionController.validate_and_end()?

Q18: How does SessionController.end() handle git commits and tags?

Q19: What is the difference between end() and validate_and_end()?

Q20: What shell command starts a session?

Q21: How do you set handoff data for the next session via the CLI?

Q22: What happens to old sessions in context.md during end()?

Q23: Where does the session CHANGELOG get updated?

Q24: What is the session git tag format?

Q25: Why is it mandatory to log work, artifacts, choices, and handoff before ending?

Q26: What is the repository pattern abstraction used to hide Bolt details?

Q27: What are the two embedding backends in semantic_graph/embedders.py?

Q28: Why does the Memgraph adapter use chunk-label and vector-index isolation in tests?

Q29: What bug was fixed in _all_vector_indexes() regarding label strings?

Q30: What happens when a dimension mismatch is detected on an existing vector index?

Q31: How does the HA controller discover the current Memgraph MAIN node?

Q32: What is the vector index name, dimension, and metric for the orchestrata-ultimate Codestral chunks?

Q33: What reranker model is used for the orchestrata-ultimate semantic graph?

Q34: How many chunks were ingested for the orchestrata-ultimate project?

Q35: What property tags every chunk with its project for multi-project support?

Q36: What is the Embedder protocol interface?

Q37: How does OpenRouterEmbedder handle out-of-order provider responses?

Q38: Why is SentenceTransformerEmbedder loaded lazily?

Q39: What is the default Qwen embedding model and dimension?

Q40: How does the ingestion script verify retrieval quality after indexing?

Q41: Why is pytest-xdist banned for this project?

Q42: What are the two supported test runners?

Q43: What is the minimum per-file coverage required by the Definition of Done?

Q44: What does rule T2 forbid regarding os.environ in ported tests?

Q45: Why must fixtures be function-scope rather than module or class scope?

Q46: What is the isolation fixture used for?

Q47: How are Redis keys isolated per worker in tests?

Q48: What is the real-Prolog fixture pattern for test isolation?

Q49: Why are mocks, stubs, fakes, and monkeypatch forbidden?

Q50: What are the four blocking safety gates run before tests?

Q51: What is the source monorepo path and how many packages does it contain?

Q52: What is the target package path for the ported code?

Q53: What is the purpose of scripts/serialize_codebase_ast.py?

Q54: How many classes are in the orchestrata source AST?

Q55: What is the three-pass class pairing algorithm in the deep compare tool?

Q56: What is the readiness classification for ported classes?

Q57: What is the standard import translation from orchestrata.core.interfaces?

Q58: What is the standard import translation from orchestrata.volks.<role>?

Q59: How are dynamic string literal imports handled during porting?

Q60: What is the default value rule for os.environ["REDIS_HOST"]?

Q61: What are the connection env vars for Neo4j?

Q62: What is the Neo4jSyncer class responsible for?

Q63: How many node types and relationship types does the Neo4j sync engine use?

Q64: What is the nodes-first-edges-second pattern in the sync engine?

Q65: How does the codebase prevent Neo4j CREATE without test_id?

Q66: What command verifies knowledge graph connectivity?

Q67: Where is the single source of truth for service IPs and ports?

Q68: What is the default Neo4j URI fallback if env var is missing?

Q69: How are test_id-based cleanups performed in Neo4j tests?

Q70: What is the relationship between sync_ast_to_neo4j.py and knowledge_graph/sync.py?

Q71: What is the renamed class for BaseVolk in the target codebase?

Q72: What is the base class for agents: Pydantic BaseModel or dataclass?

Q73: How many role volks are being ported?

Q74: What is the import translation for orchestrata.volks.analyst.volk?

Q75: What pattern replaces ABC interfaces in the target codebase?

Q76: What is the CXPMixin used for in BaseAgent?

Q77: What is the agents/lifecycle.py module responsible for?

Q7: How does the project enforce the rule against `except: pass` and `except Exception: pass`?

Q15: Why must `subprocess.DEVNULL` never be used for service logs?

Q16: What does `SessionController.begin()` do automatically regarding unclosed sessions?

Q17: What are the five checklist items validated by `SessionController.validate_and_end()`?

Q18: How does `SessionController.end()` handle git commits and tags?

Q19: What is the difference between `end()` and `validate_and_end()`?

Q22: What happens to old sessions in `context.md` during `end()`?

Q27: What are the two embedding backends in `semantic_graph/embedders.py`?

Q29: What bug was fixed in `_all_vector_indexes()` regarding label strings?

Q36: What is the `Embedder` protocol interface?

Q37: How does `OpenRouterEmbedder` handle out-of-order provider responses?

Q38: Why is `SentenceTransformerEmbedder` loaded lazily?

Q41: Why is `pytest-xdist` banned for this project?

Q44: What does rule T2 forbid regarding `os.environ` in ported tests?

Q46: What is the `isolation` fixture used for?

Q53: What is the purpose of `scripts/serialize_codebase_ast.py`?

Q57: What is the standard import translation from `orchestrata.core.interfaces`?

Q58: What is the standard import translation from `orchestrata.volks.<role>`?

Q60: What is the default value rule for `os.environ["REDIS_HOST"]`?

Q62: What is the `Neo4jSyncer` class responsible for?

Q65: How does the codebase prevent Neo4j `CREATE` without `test_id`?

Q70: What is the relationship between `sync_ast_to_neo4j.py` and `knowledge_graph/sync.py`?

Q71: What is the renamed class for `BaseVolk` in the target codebase?

Q74: What is the import translation for `orchestrata.volks.analyst.volk`?

Q76: What is the `CXPMixin` used for in `BaseAgent`?

Q77: What is the `agents/lifecycle.py` module responsible for?

Q79: What is the difference between `agents/swarm` and `agents/volks`?

Q82: What is a `CXPPacket`?

Q92: Why did the standalone `memgraph-db` container need to be restarted during this work?

Q97: Why is `os.environ["X"]` forbidden in favor of `os.environ.get("X", default)`?