Orchestrata Ultimate / Specs / 021-opencode-integration

021-opencode-integration: OpenCode Integration

A comprehensive TypeScript plugin (3,234 lines) and supporting agents, tools, and commands that integrate OpenCode with the Orchestrata project. The plugin provides session management, code quality enforcement via a 5-gate review pipeline, deception detection, knowledge graph context injection, conversation tracking, and 24 custom tools accessible from within OpenCode sessions.

At a glance

Reading this spec

The OpenCode Integration connects the OpenCode coding assistant to the Orchestrata project. It is a TypeScript plugin plus supporting agents, tools and commands that provide session management, code quality enforcement through a 5-gate review pipeline, deception detection, knowledge graph context injection, conversation tracking and 24 custom tools available inside OpenCode sessions.

The spec gives these reasons: OpenCode needs project-specific intelligence to work with the monorepo, knowledge graph context is injected automatically, quality standards (no mocking, absolute imports, short functions, snake_case) need enforcement at edit time, session lifecycle must be tracked consistently across Claude Code and OpenCode through the same context.json, and LLMs sometimes claim actions they did not perform.

The scope is a set of actor-driven user stories (labelled US-021-nn, each naming the functional requirements it exercises) and sixteen or more functional requirements: plugin lifecycle hooks, session auto-start and auto-end, knowledge graph context injection, the 5-gate review pipeline, error blocking, deception detection, policy enforcement, custom tool availability, project scoping of knowledge graph queries, Redis queue management, memory search, read throttling, git checkpoints, conversation storage and a knowledge graph sync daemon. Requirement IDs use the REQ-021- prefix.

The design is a single plugin, orchestrata.ts, exporting OrchestrataPlugin and hooking 7 OpenCode lifecycle events. Two OpenCode agents provide automatic and manual context injection, one slash command (/query-kg) runs interactive Cypher queries, and five Python tools query Neo4j with project scoping.

The plugin itself is TypeScript, so the Python trace table covers only supporting code, mostly orchestrata_ultimate/knowledge_graph/conversation_consumer, with orchestrata_ultimate/tools/conversation_tools and orchestrata_ultimate/kernel/cli_main. The per-requirement view is on the RTM page.

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

Measured coverage is 13 of 295 requirements cited by at least one @traces in src/ (4.4%), spread over 5 modules; the module citing the most of them is orchestrata_ultimate/knowledge_graph/conversation_consumer (12 requirements). In tests/, 8 requirements are cited by a test-side @traces.

Coverage gaps: 282 requirements have no citing symbol. The largest untraced groups are REQ-021-* (282). Untraced means no @traces names the ID; the behaviour may still exist in code that was never annotated. Test-side citations are thinner than code-side ones (8 against 13).

Requirements

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

Code that traces this spec

Checklists

checklists/README.md

OpenCode Integration Checklists

Project: Orchestrata OpenCode Integration (Spec 021) Component: OrchestrataPlugin, Agents, Tools, Commands, KG Integration Status: Implemented Owner: Mohamed

Overview

The OpenCode Integration is a comprehensive TypeScript plugin and supporting infrastructure that bridges OpenCode with the Orchestrata ecosystem. It provides session management, 5-gate code quality enforcement, deception detection, knowledge graph context injection, conversation tracking, and 24 custom tools.

Checklist Summary

Key Responsibilities

1. Plugin Lifecycle Management

• Hook into 7 OpenCode lifecycle events (session.created, session.idle, tool.execute.before, tool.execute.after, message.updated, file.edited, experimental.session.compacting)
• Activate for any project under /home/mohamed/workspace with context.json
• Manage state (tool call history, read count, MCP health)

2. Session Management

• Auto-start sessions on connection via session_cli.py
• Auto-close sessions on idle with git-extracted achievements
• Display session info, pending work, and project state
• Flush KG sync and conversation queues on session close

3. Code Quality Enforcement (5-Gate Review)

• Gate 1: Syntax validation (py_compile), formatting (black), import ordering (isort)
• Gate 2: Linting (flake8 with E/F/W/C90 selectors)
• Gate 3: Type checking (mypy), security scanning, runtime import verification
• Gate 4: Complexity analysis (branches, nesting, line length, function size)
• Gate 5: Naming conventions and design pattern detection

4. Policy Enforcement

• Testing policy: block mocking patterns (unittest.mock, MagicMock, @patch, AsyncMock)
• Import policy: block relative imports (from . import)
• Development policy: block pip, require uv; block requirements.txt
• Bash safety: block destructive commands (rm -rf /, fork bombs)

5. Deception Detection

• Track tool calls across session for audit
• Detect claimed file creation without Write/Edit tool
• Detect claimed command execution without Bash tool
• Detect claimed file reading without Read/Grep tool
• Detect unacknowledged tool errors

6. Knowledge Graph Integration

• Auto-inject KG context on file reads (classes, functions, specs, traceability)
• 12 KG tools for queries, sync, daemon management, entity search
• 2 agents for automatic and manual KG context injection
• 1 slash command for interactive Cypher queries
• 5 Python tools with project scoping

7. Conversation Tracking

• Queue conversation turns to Redis for batch Neo4j storage
• Flush queue on session close with Conversation and ConversationTurn nodes
• Memory search via "remember when" trigger phrases

8. Custom Tools (24 total)

• 9 session management tools
• 12 KG operation tools
• 3 conversation tracking tools

File References

checklists/constitutional.md

OpenCode Integration Constitutional Checklist

Article I: Security and Access Control

• [ ] CONST-I-001: Neo4j credentials must never be hardcoded in plugin source; environment variables used with local-dev fallbacks only
• [ ] CONST-I-002: Plugin must block destructive bash commands (rm -rf /, fork bombs) before execution
• [ ] CONST-I-003: Gate 3 code review must detect hardcoded passwords, API keys, secrets, and tokens in edited files
• [ ] CONST-I-004: Write operations to sensitive paths (~/.claude/plans/) must be blocked with descriptive redirects
• [ ] CONST-I-005: Read throttling (50/session) must prevent runaway file scanning that could expose sensitive data
• [ ] CONST-I-006: Conversation content must be truncated (2000 chars) before Neo4j storage to limit data exposure
• [ ] CONST-I-007: Tool call history must be capped (100 entries) to bound memory exposure
• [ ] CONST-I-008: KG query tools must not expose credentials in stdout or error messages
• [ ] CONST-I-009: Redis queue data must not contain full file contents, only file paths
• [ ] CONST-I-010: Plugin must not transmit project data to external services beyond configured Neo4j and Redis

Article II: Data Integrity and Consistency

• [ ] CONST-II-001: context.json must remain the single source of truth for session state across Claude Code and OpenCode
• [ ] CONST-II-002: Session CLI operations must be atomic (begin/end do not leave partial state)
• [ ] CONST-II-003: KG sync queue must use Redis SET to prevent duplicate file entries
• [ ] CONST-II-004: Conversation queue must use Redis LIST to preserve turn ordering
• [ ] CONST-II-005: ConversationTurn nodes must have unique turn_id to prevent duplicates
• [ ] CONST-II-006: Git checkpoints must be created before edit/write operations to enable rollback
• [ ] CONST-II-007: KG sync must not corrupt existing Neo4j nodes (MERGE preferred over CREATE)
• [ ] CONST-II-008: Session close must flush both KG and conversation queues before marking session ended
• [ ] CONST-II-009: Tool call history must accurately reflect actual tool invocations (no phantom entries)
• [ ] CONST-II-010: Deception detection must only analyze the actual assistant message, not injected context

Article III: Code Quality and Standards Enforcement

• [ ] CONST-III-001: Testing policy must block all forms of mocking (unittest.mock, MagicMock, @patch, AsyncMock, Mock(), patch.object)
• [ ] CONST-III-002: Import policy must enforce absolute imports only (no relative from . import)
• [ ] CONST-III-003: Development policy must enforce uv over pip for all package operations
• [ ] CONST-III-004: Code review must run all 5 gates in sequence for every Python file edit under packages/
• [ ] CONST-III-005: Errors from code review must block the edit operation (throw Error)
• [ ] CONST-III-006: Warnings from code review must be displayed but not block the operation
• [ ] CONST-III-007: Code review must respect project-specific thresholds (black 88, flake8 ignores)
• [ ] CONST-III-008: Gate 3 must check actual module importability, not just syntax
• [ ] CONST-III-009: Gate 4 complexity thresholds (10 branches error, 5 nesting error) must not be configurable per-file
• [ ] CONST-III-010: Gate 5 naming conventions must match project standards (snake_case functions, PascalCase classes)

Article IV: System Reliability and Resilience

• [ ] CONST-IV-001: All Neo4j operations must be non-blocking (failures must not prevent tool execution)
• [ ] CONST-IV-002: All Redis operations must be non-blocking (failures must not prevent session management)
• [ ] CONST-IV-003: MCP health checks must be non-blocking (unavailable servers must not prevent native tool use)
• [ ] CONST-IV-004: Session CLI failures must be non-blocking (session management errors must not prevent work)
• [ ] CONST-IV-005: KG sync daemon must recover from crashes (queue persists in Redis)
• [ ] CONST-IV-006: Conversation queue must be durable (turns persist in Redis until flushed)
• [ ] CONST-IV-007: Plugin must activate cleanly even if Neo4j, Redis, and MCP are all unavailable
• [ ] CONST-IV-008: Git checkpoint failures must not block edit operations
• [ ] CONST-IV-009: Code review tool failures (except review's own errors) must not block edits
• [ ] CONST-IV-010: Background KG sync process must not impact foreground plugin performance

Article V: Transparency and Auditability

• [ ] CONST-V-001: All plugin operations must be logged to client.app.log with appropriate severity levels
• [ ] CONST-V-002: Deception detection findings must include evidence (tools used) not just claims
• [ ] CONST-V-003: Deception audit report must be generated on every session idle event
• [ ] CONST-V-004: Code review results must clearly distinguish errors (blocking) from warnings (informational)
• [ ] CONST-V-005: Session lifecycle events (start, end, close) must be logged with session seq numbers
• [ ] CONST-V-006: Tool operation logging must record file paths for edit/write/delete operations
• [ ] CONST-V-007: Policy violations must include specific pattern name and suggested alternative
• [ ] CONST-V-008: KG sync progress must be reportable via kg-queue-status tool
• [ ] CONST-V-009: Conversation queue depth must be queryable via conv-status tool
• [ ] CONST-V-010: Plugin activation must be logged with project name and directory

Article VI: Privacy and Data Minimization

• [ ] CONST-VI-001: Conversation turns must be truncated to 2000 characters before storage
• [ ] CONST-VI-002: User messages must not be logged in full to client.app.log (only first 100 chars for close detection)
• [ ] CONST-VI-003: Deception analysis must strip quoted content to avoid analyzing code examples as claims
• [ ] CONST-VI-004: KG context injection must not expose Neo4j credentials in tool args
• [ ] CONST-VI-005: Error messages must not expose stack traces or internal implementation details to the LLM
• [ ] CONST-VI-006: Redis queue data must be processed and cleared on session close (no stale data accumulation)
• [ ] CONST-VI-007: Tool call history must be cleared on session end to prevent cross-session leakage
• [ ] CONST-VI-008: Memory search results must be scoped to the current project's context.json only
• [ ] CONST-VI-009: KG queries must be scoped to the current project via project scoping (kg_query_inner.py)
• [ ] CONST-VI-010: Plugin must not access or modify files outside the workspace directory

Article VII: Ethical AI and Deception Prevention

• [ ] CONST-VII-001: Deception detection must cover file creation, command execution, and file reading claims
• [ ] CONST-VII-002: Error concealment (unacknowledged tool failures) must be flagged as CRITICAL severity
• [ ] CONST-VII-003: Deception analysis must exclude quoted content to prevent false positives from code examples
• [ ] CONST-VII-004: Clean audit results must be explicitly reported ("No issues detected")
• [ ] CONST-VII-005: Deception findings must be visible to the user (stderr output, not suppressed)
• [ ] CONST-VII-006: Tool call tracking must be accurate and complete (no selective recording)
• [ ] CONST-VII-007: Deception severity levels must be appropriate (CRITICAL for action claims, HIGH for reading claims)
• [ ] CONST-VII-008: Deception detection must not produce false positives from legitimate tool-less context (e.g., discussing previous work)
• [ ] CONST-VII-009: Audit report must include all findings, not suppress any for appearance
• [ ] CONST-VII-010: Deception detection logic must be deterministic and reproducible

Article VIII: Interoperability and Compatibility

• [ ] CONST-VIII-001: Plugin must be compatible with @opencode-ai/plugin@1.3.3 API
• [ ] CONST-VIII-002: Session CLI interface must be identical for Claude Code and OpenCode
• [ ] CONST-VIII-003: context.json format must be shared across both platforms
• [ ] CONST-VIII-004: Hook mapping between Claude Code and OpenCode must be documented and maintained
• [ ] CONST-VIII-005: KG query tools must use the same Neo4j schema as orchestrata-knowledge package
• [ ] CONST-VIII-006: Redis queue key naming must not conflict with other orchestrata subsystems
• [ ] CONST-VIII-007: Conversation nodes must use "opencode" platform tag to distinguish from other sources
• [ ] CONST-VIII-008: Git checkpoint commits must use --no-verify to avoid triggering pre-commit hooks
• [ ] CONST-VIII-009: Python tools must be compatible with uv-managed virtual environment
• [ ] CONST-VIII-010: Agent definitions must follow OpenCode agent markdown format

Article IX: Performance and Resource Management

• [ ] CONST-IX-001: Plugin activation must complete within 5 seconds (non-blocking background tasks excluded)
• [ ] CONST-IX-002: KG context injection must not add more than 2 seconds to file read operations
• [ ] CONST-IX-003: Code review pipeline must complete within 2 minutes per file (sum of all gate timeouts)
• [ ] CONST-IX-004: Read throttle must prevent excessive file operations (limit: 50/session)
• [ ] CONST-IX-005: Tool call history must be bounded (100 entries) to prevent memory growth
• [ ] CONST-IX-006: Background KG sync must use nohup/detached process to not block plugin
• [ ] CONST-IX-007: Redis queue operations must use single-command atomics (SADD, SCARD, SPOP, LPUSH, LPOP, LLEN)
• [ ] CONST-IX-008: Neo4j driver connections must be closed after each query operation
• [ ] CONST-IX-009: Subprocess timeouts must be enforced (10s syntax, 30s lint/format, 60s mypy)
• [ ] CONST-IX-010: Plugin must not spawn more than one concurrent background sync process

Article X: Knowledge Graph Integrity

• [ ] CONST-X-001: All Neo4j node creation must include relationship to parent node (no orphans)
• [ ] CONST-X-002: Conversation nodes must be linked to Project via HAS_CONVERSATION relationship
• [ ] CONST-X-003: ConversationTurn nodes must be linked to Conversation via HAS_TURN relationship
• [ ] CONST-X-004: KG sync must use MERGE (not CREATE) to prevent duplicate nodes
• [ ] CONST-X-005: Project scoping must correctly anchor queries to the orchestrata Project node
• [ ] CONST-X-006: File sync must preserve existing node relationships when updating properties
• [ ] CONST-X-007: Conversation platform field must accurately identify the source ("opencode")
• [ ] CONST-X-008: KG statistics reported by kg-stats tool must reflect actual graph state
• [ ] CONST-X-009: Entity search must return results from the correct project scope
• [ ] CONST-X-010: CXP thread queries must correctly follow thread_id chains

Article XI: Deployment and Configuration

• [ ] CONST-XI-001: install.sh must deploy all artifacts (agents, commands, plugins, tools, config) to correct locations
• [ ] CONST-XI-002: Deployed plugin must reference correct session_cli.py path (~/.claude/tools/session_cli.py)
• [ ] CONST-XI-003: Deployed tools must reference correct workspace paths (/home/mohamed/workspace/orchestrata)
• [ ] CONST-XI-004: Plugin must detect and adapt to directory context (orchestrata-specific vs generic workspace)
• [ ] CONST-XI-005: Configuration must support environment variable overrides for Neo4j URI and credentials

checklists/requirements.md

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

checklists/testing.md

OpenCode Integration Testing Checklist

Unit Tests: Plugin State Management

• [ ] TEST-UNIT-001: Verify toolCallHistory initialized as empty array
• [ ] TEST-UNIT-002: Verify readCount initialized to 0
• [ ] TEST-UNIT-003: Verify MCP_SERVERS contains document-reader (3456) and document-writer (3457)
• [ ] TEST-UNIT-004: Verify toolCallHistory entry contains tool, args, timestamp, success fields
• [ ] TEST-UNIT-005: Verify toolCallHistory caps at 100 entries (oldest removed)
• [ ] TEST-UNIT-006: Verify readCount increments on each read tool execution
• [ ] TEST-UNIT-007: Verify state cleared on session end (toolCallHistory emptied, readCount reset)

Unit Tests: Helper Functions

removeQuotedContent

• [ ] TEST-UNIT-008: Verify triple-backtick code blocks removed
• [ ] TEST-UNIT-009: Verify inline backtick code removed
• [ ] TEST-UNIT-010: Verify blockquote lines (> prefix) removed
• [ ] TEST-UNIT-011: Verify non-quoted text preserved
• [ ] TEST-UNIT-012: Verify nested code blocks handled correctly

detectDeception

• [ ] TEST-UNIT-013: Verify file creation claim with Write tool returns no findings
• [ ] TEST-UNIT-014: Verify file creation claim without Write/Edit tool returns ACTION_DECEPTION (CRITICAL)
• [ ] TEST-UNIT-015: Verify command execution claim with Bash tool returns no findings
• [ ] TEST-UNIT-016: Verify command execution claim without Bash tool returns ACTION_DECEPTION (CRITICAL)
• [ ] TEST-UNIT-017: Verify file reading claim with Read tool returns no findings
• [ ] TEST-UNIT-018: Verify file reading claim without Read/Grep tool returns ACTION_DECEPTION (HIGH)
• [ ] TEST-UNIT-019: Verify tool error without acknowledgment returns ERROR_CONCEALMENT (CRITICAL)
• [ ] TEST-UNIT-020: Verify tool error with acknowledgment returns no findings
• [ ] TEST-UNIT-021: Verify quoted content excluded from deception analysis
• [ ] TEST-UNIT-022: Verify multiple findings can be returned simultaneously
• [ ] TEST-UNIT-023: Verify empty tool history with no claims returns no findings
• [ ] TEST-UNIT-024: Verify evidence field lists tools used

enforceTestingPolicy

• [ ] TEST-UNIT-025: Verify unittest.mock blocked in test files
• [ ] TEST-UNIT-026: Verify MagicMock blocked in test files
• [ ] TEST-UNIT-027: Verify @patch blocked in test files
• [ ] TEST-UNIT-028: Verify AsyncMock blocked in test files
• [ ] TEST-UNIT-029: Verify Mock() blocked in test files
• [ ] TEST-UNIT-030: Verify patch.object blocked in test files
• [ ] TEST-UNIT-031: Verify non-test files not checked (no error thrown)
• [ ] TEST-UNIT-032: Verify error message includes pattern name

enforceImportPolicy

• [ ] TEST-UNIT-033: Verify from . import x blocked
• [ ] TEST-UNIT-034: Verify from .. import x not matched (only single dot)
• [ ] TEST-UNIT-035: Verify absolute imports allowed
• [ ] TEST-UNIT-036: Verify indented relative imports detected

enforceDevelopmentPolicy

• [ ] TEST-UNIT-037: Verify pip install blocked with "uv add" suggestion
• [ ] TEST-UNIT-038: Verify pip3 install blocked with "uv add" suggestion
• [ ] TEST-UNIT-039: Verify pip sync blocked with "uv sync" suggestion
• [ ] TEST-UNIT-040: Verify requirements.txt reference blocked
• [ ] TEST-UNIT-041: Verify uv add commands allowed
• [ ] TEST-UNIT-042: Verify uv sync commands allowed

checkMcpHealth

• [ ] TEST-UNIT-043: Verify returns true when server responds with "ok"
• [ ] TEST-UNIT-044: Verify returns true when server responds with "200"
• [ ] TEST-UNIT-045: Verify returns false when server is down
• [ ] TEST-UNIT-046: Verify returns false on connection error

Unit Tests: 5-Gate Code Review

Gate 1: Syntax & Format

• [ ] TEST-UNIT-047: Verify py_compile detects syntax errors
• [ ] TEST-UNIT-048: Verify black --check detects formatting violations
• [ ] TEST-UNIT-049: Verify isort --check detects import ordering violations
• [ ] TEST-UNIT-050: Verify valid Python file passes Gate 1
• [ ] TEST-UNIT-051: Verify syntax error reported with first 200 chars of stderr

Gate 2: Lint

• [ ] TEST-UNIT-052: Verify flake8 detects E-series errors
• [ ] TEST-UNIT-053: Verify flake8 detects F-series errors
• [ ] TEST-UNIT-054: Verify flake8 detects W-series warnings
• [ ] TEST-UNIT-055: Verify E203, W503, E501 codes ignored
• [ ] TEST-UNIT-056: Verify E9xx/F63x/F72x classified as errors (not warnings)
• [ ] TEST-UNIT-057: Verify max 15 lint lines reported

Gate 3: Runtime & Security

• [ ] TEST-UNIT-058: Verify mypy detects type errors
• [ ] TEST-UNIT-059: Verify module import check derives correct module path
• [ ] TEST-UNIT-060: Verify hardcoded password detection
• [ ] TEST-UNIT-061: Verify hardcoded API key detection
• [ ] TEST-UNIT-062: Verify hardcoded secret detection
• [ ] TEST-UNIT-063: Verify hardcoded token detection
• [ ] TEST-UNIT-064: Verify debug print statement detection
• [ ] TEST-UNIT-065: Verify TODO/FIXME/HACK comment detection (max 3)
• [ ] TEST-UNIT-066: Verify bare except with pass detection
• [ ] TEST-UNIT-067: Verify missing logger warning
• [ ] TEST-UNIT-068: Verify unlogged exception detection
• [ ] TEST-UNIT-069: Verify mutable default argument detection
• [ ] TEST-UNIT-070: Verify @traces decorator presence check (3+ public items)
• [ ] TEST-UNIT-071: Verify spec/requirement reference detection in code

Gate 4: Complexity & Nesting

• [ ] TEST-UNIT-072: Verify branch count > 10 flagged as error
• [ ] TEST-UNIT-073: Verify branch count 8-10 flagged as warning
• [ ] TEST-UNIT-074: Verify branch count <= 7 passes
• [ ] TEST-UNIT-075: Verify nesting depth > 5 flagged as error
• [ ] TEST-UNIT-076: Verify nesting depth 5 flagged as warning
• [ ] TEST-UNIT-077: Verify nesting depth <= 4 passes
• [ ] TEST-UNIT-078: Verify line length > 100 chars counted as warning
• [ ] TEST-UNIT-079: Verify function > 40 lines flagged as warning

Gate 5: Naming & Design

• [ ] TEST-UNIT-080: Verify uppercase function name flagged as naming error
• [ ] TEST-UNIT-081: Verify lowercase class name flagged as naming error
• [ ] TEST-UNIT-082: Verify snake_case function passes
• [ ] TEST-UNIT-083: Verify PascalCase class passes
• [ ] TEST-UNIT-084: Verify god object (> 20 methods) flagged as warning
• [ ] TEST-UNIT-085: Verify feature envy (> 15 self references) flagged as warning
• [ ] TEST-UNIT-086: Verify singleton pattern detected as info
• [ ] TEST-UNIT-087: Verify factory pattern detected as info
• [ ] TEST-UNIT-088: Verify builder pattern detected as info
• [ ] TEST-UNIT-089: Verify @dataclass detected as info

Review Output

• [ ] TEST-UNIT-090: Verify only packages/*.py files trigger review
• [ ] TEST-UNIT-091: Verify non-Python files skip review
• [ ] TEST-UNIT-092: Verify files outside packages/ skip review
• [ ] TEST-UNIT-093: Verify errors cause thrown Error (blocking)
• [ ] TEST-UNIT-094: Verify warnings do not cause thrown Error
• [ ] TEST-UNIT-095: Verify clean file produces "ALL GATES PASSED"
• [ ] TEST-UNIT-096: Verify max 25 errors in output
• [ ] TEST-UNIT-097: Verify max 20 warnings in output

Unit Tests: KG Query Tools (Python)

kg_query.py

• [ ] TEST-UNIT-098: Verify orchestrata paths added to sys.path
• [ ] TEST-UNIT-099: Verify successful Cypher query returns JSON with success=true
• [ ] TEST-UNIT-100: Verify failed connection returns JSON error
• [ ] TEST-UNIT-101: Verify import error returns JSON error with ImportError type
• [ ] TEST-UNIT-102: Verify missing arguments prints usage to stderr
• [ ] TEST-UNIT-103: Verify JSON parameter parsing from argv[2]
• [ ] TEST-UNIT-104: Verify invalid JSON parameter prints error to stderr

kg_query_inner.py (Project Scoping)

• [ ] TEST-UNIT-105: Verify File path query rewritten with Project anchor
• [ ] TEST-UNIT-106: Verify Spec ID query rewritten with Project anchor
• [ ] TEST-UNIT-107: Verify Requirement ID query rewritten with Project anchor
• [ ] TEST-UNIT-108: Verify general MATCH query gets WHERE EXISTS clause
• [ ] TEST-UNIT-109: Verify existing WHERE clause gets AND condition (not replaced)
• [ ] TEST-UNIT-110: Verify MATCH without WHERE gets new WHERE clause
• [ ] TEST-UNIT-111: Verify non-MATCH queries pass through unchanged
• [ ] TEST-UNIT-112: Verify CWD detection for orchestrata workspace
• [ ] TEST-UNIT-113: Verify non-orchestrata CWD skips project scoping
• [ ] TEST-UNIT-114: Verify case-insensitive pattern matching for query rewriting

neo4j_query.py

• [ ] TEST-UNIT-115: Verify fallback mock classes defined on import failure
• [ ] TEST-UNIT-116: Verify import error printed to stderr
• [ ] TEST-UNIT-117: Verify query execution returns JSON result

simple_kg_query.py

• [ ] TEST-UNIT-118: Verify minimal query execution
• [ ] TEST-UNIT-119: Verify connection error returns JSON error

Unit Tests: Memory Search

• [ ] TEST-UNIT-120: Verify "remember when" triggers search
• [ ] TEST-UNIT-121: Verify "do you remember" triggers search
• [ ] TEST-UNIT-122: Verify "recall when" triggers search
• [ ] TEST-UNIT-123: Verify "we discussed" triggers search
• [ ] TEST-UNIT-124: Verify "we talked about" triggers search
• [ ] TEST-UNIT-125: Verify "last time we" triggers search
• [ ] TEST-UNIT-126: Verify "what happened with" triggers search
• [ ] TEST-UNIT-127: Verify topic extracted after trigger phrase
• [ ] TEST-UNIT-128: Verify short words (< 3 chars) excluded
• [ ] TEST-UNIT-129: Verify purpose field searched
• [ ] TEST-UNIT-130: Verify achievements searched
• [ ] TEST-UNIT-131: Verify work log entries searched
• [ ] TEST-UNIT-132: Verify max 10 results returned
• [ ] TEST-UNIT-133: Verify newest sessions searched first
• [ ] TEST-UNIT-134: Verify no-match message displayed

Unit Tests: Session Close Detection

• [ ] TEST-UNIT-135: Verify "close the session" triggers close
• [ ] TEST-UNIT-136: Verify "cts" triggers close
• [ ] TEST-UNIT-137: Verify "cs" triggers close
• [ ] TEST-UNIT-138: Verify "end session" triggers close
• [ ] TEST-UNIT-139: Verify "finish session" triggers close
• [ ] TEST-UNIT-140: Verify no active session displays error
• [ ] TEST-UNIT-141: Verify achievements extracted from git log (filter checkpoints)
• [ ] TEST-UNIT-142: Verify session ended via session_cli.py
• [ ] TEST-UNIT-143: Verify branch pushed to origin
• [ ] TEST-UNIT-144: Verify state cleared after close

Unit Tests: Custom Tools

Session Tools

• [ ] TEST-UNIT-145: Verify session-status returns formatted output
• [ ] TEST-UNIT-146: Verify session-status handles no active session
• [ ] TEST-UNIT-147: Verify session-begin calls session_cli.py begin with purpose
• [ ] TEST-UNIT-148: Verify session-end calls session_cli.py end with achievements
• [ ] TEST-UNIT-149: Verify session-log-work calls session_cli.py log-work with desc
• [ ] TEST-UNIT-150: Verify session-log-achievement calls session_cli.py log-achievement
• [ ] TEST-UNIT-151: Verify session-add-work calls session_cli.py add-work with text and priority
• [ ] TEST-UNIT-152: Verify session-complete-work calls session_cli.py complete-work
• [ ] TEST-UNIT-153: Verify session-update-state passes version, branch, testState, status
• [ ] TEST-UNIT-154: Verify session-log-choice passes choice and reason

KG Tools

• [ ] TEST-UNIT-155: Verify kg-query executes Cypher and returns result
• [ ] TEST-UNIT-156: Verify kg-query rejects non-orchestrata directory
• [ ] TEST-UNIT-157: Verify kg-sync runs sync script and returns output
• [ ] TEST-UNIT-158: Verify kg-queue-status returns pending count from Redis
• [ ] TEST-UNIT-159: Verify kg-flush-queue processes all queued files
• [ ] TEST-UNIT-160: Verify kg-file-context returns KG data for file path
• [ ] TEST-UNIT-161: Verify kg-find-file searches by pattern
• [ ] TEST-UNIT-162: Verify kg-find-entity searches classes and functions by name
• [ ] TEST-UNIT-163: Verify kg-stats returns node/relationship counts

Integration Tests: Plugin Lifecycle

• [ ] TEST-INTEG-001: Verify plugin activates for orchestrata directory
• [ ] TEST-INTEG-002: Verify plugin returns empty object for non-workspace directory
• [ ] TEST-INTEG-003: Verify session.created auto-starts new session when none active
• [ ] TEST-INTEG-004: Verify session.created resumes existing active session
• [ ] TEST-INTEG-005: Verify session.idle runs deception audit and session close
• [ ] TEST-INTEG-006: Verify session.idle clears state after processing
• [ ] TEST-INTEG-007: Verify tool.execute.before injects KG context on file read
• [ ] TEST-INTEG-008: Verify tool.execute.before enforces testing policy on test file edit
• [ ] TEST-INTEG-009: Verify tool.execute.before creates git checkpoint on edit
• [ ] TEST-INTEG-010: Verify tool.execute.before blocks destructive bash commands
• [ ] TEST-INTEG-011: Verify tool.execute.after records tool call in history
• [ ] TEST-INTEG-012: Verify message.updated triggers memory search on "remember when"
• [ ] TEST-INTEG-013: Verify message.updated triggers session close on "close the session"
• [ ] TEST-INTEG-014: Verify message.updated queues conversation turn to Redis
• [ ] TEST-INTEG-015: Verify file.edited runs 5-gate review on packages/*.py
• [ ] TEST-INTEG-016: Verify file.edited skips review for non-Python files
• [ ] TEST-INTEG-017: Verify file.edited queues file for KG sync after passing review
• [ ] TEST-INTEG-018: Verify experimental.session.compacting injects session context

Integration Tests: KG Query Pipeline

• [ ] TEST-INTEG-019: Verify kg_query bash wrapper invokes kg_query_inner.py via uv run
• [ ] TEST-INTEG-020: Verify kg_query_inner.py connects to Neo4j and returns results
• [ ] TEST-INTEG-021: Verify project scoping correctly anchors File queries to Project node
• [ ] TEST-INTEG-022: Verify project scoping correctly anchors Spec queries to Project node
• [ ] TEST-INTEG-023: Verify end-to-end Cypher query execution via plugin kg-query tool

Integration Tests: Session Management End-to-End

• [ ] TEST-INTEG-024: Verify full session lifecycle: create -> log work -> log achievement -> end
• [ ] TEST-INTEG-025: Verify session close via message triggers proper end sequence
• [ ] TEST-INTEG-026: Verify git achievements extracted and stored in session
• [ ] TEST-INTEG-027: Verify context.json updated correctly after session operations

Integration Tests: Code Review End-to-End

• [ ] TEST-INTEG-028: Verify valid Python file passes all 5 gates
• [ ] TEST-INTEG-029: Verify file with syntax error blocked at Gate 1
• [ ] TEST-INTEG-030: Verify file with lint errors blocked at Gate 2
• [ ] TEST-INTEG-031: Verify file with type errors reported at Gate 3
• [ ] TEST-INTEG-032: Verify file with high complexity reported at Gate 4
• [ ] TEST-INTEG-033: Verify file with naming violations reported at Gate 5
• [ ] TEST-INTEG-034: Verify blocked edit throws Error with fix suggestions

Integration Tests: Redis Queue Operations

• [ ] TEST-INTEG-035: Verify KG sync queue accepts file paths via SADD
• [ ] TEST-INTEG-036: Verify KG sync queue reports count via SCARD
• [ ] TEST-INTEG-037: Verify KG sync queue flushed via SPOP loop
• [ ] TEST-INTEG-038: Verify conversation queue accepts turns via LPUSH
• [ ] TEST-INTEG-039: Verify conversation queue reports depth via LLEN
• [ ] TEST-INTEG-040: Verify conversation queue flushed via LPOP loop

Integration Tests: Deployment

• [ ] TEST-INTEG-041: Verify install.sh creates all target directories
• [ ] TEST-INTEG-042: Verify install.sh copies agents to ~/.opencode/agents/
• [ ] TEST-INTEG-043: Verify install.sh copies commands to ~/.opencode/commands/
• [ ] TEST-INTEG-044: Verify install.sh copies plugins to ~/.opencode/plugins/
• [ ] TEST-INTEG-045: Verify install.sh copies tools to ~/.opencode/tools/
• [ ] TEST-INTEG-046: Verify install.sh copies config to ~/.config/opencode/
• [ ] TEST-INTEG-047: Verify deployed kg_query tool is executable
• [ ] TEST-INTEG-048: Verify deployed Python tools have correct shebang lines

Other tracked files

• specs/021-opencode-integration/compliance-audit.md

Full spec text

Verbatim from specs/021-opencode-integration/spec.md; headings are pushed down two levels.

SPEC-021: OpenCode Integration

Metadata

• Spec ID: 021-opencode-integration
• Title: OpenCode Integration
• Version: 1.0.0
• Author: Mohamed
• Status: Complete
• Created: 2026-03-29
• Last Updated: 2026-03-29
• Priority: P1
• Components: OrchestrataPlugin, AutoKGContextAgent, KGContextAgent, QueryKGCommand, KGQueryTools
• Dependencies: OpenCode CLI, Bun runtime, Neo4j 5.0+, Redis 7.0+, @opencode-ai/plugin@1.3.3, session_cli.py

Overview

What

A comprehensive TypeScript plugin (3,234 lines) and supporting agents, tools, and commands that integrate OpenCode with the Orchestrata project. The plugin provides session management, code quality enforcement via a 5-gate review pipeline, deception detection, knowledge graph context injection, conversation tracking, and 24 custom tools accessible from within OpenCode sessions.

Why

• OpenCode needs project-specific intelligence to work effectively with Orchestrata's 19-package monorepo architecture
• The knowledge graph (558K+ nodes, 548K+ relationships) contains rich context about files, classes, functions, specs, and requirements that should be injected automatically into the LLM context
• Code quality standards (no mocking, absolute imports, max 40-line functions, snake_case naming) need automated enforcement at edit time to prevent regressions
• Session lifecycle must be tracked consistently across both Claude Code and OpenCode via the same context.json source of truth
• Deception detection is required because LLMs sometimes claim actions (file creation, command execution, file reading) they did not actually perform
• Development policies (use uv not pip, no bare except, no hardcoded secrets) need automated enforcement before code reaches CI

How

• A single TypeScript plugin (orchestrata.ts) hooks into 7 OpenCode lifecycle events to provide enforcement, context injection, and session management
• The plugin exports OrchestrataPlugin which activates for any project under /home/mohamed/workspace that has context.json
• 24 custom tools exposed via the tool export give the LLM direct access to session operations, KG queries, conversation tracking, and code review
• 2 OpenCode agents (auto-kg-context, kg-context-agent) provide automatic and manual knowledge graph context injection
• 1 slash command (/query-kg) enables interactive Cypher queries against Neo4j
• 5 Python tools provide varying levels of Neo4j query capability with project scoping
• Deployment via install.sh copies artifacts to ~/.opencode/ and ~/.config/opencode/

User Stories

Added 2026-08-02 (spec-consolidation pilot): binds the flat FR list below to actor-driven usage scenarios (SPEC-102 template). Each story names the FRs it exercises, so every requirement has a "who triggers it and why" narrative.

• US-021-01 — Consistent session lifecycle. As a developer, when I open or close an OpenCode session in a project that has context.json, the plugin auto-starts and auto-ends session tracking against that same context.json, so session state stays consistent across Claude Code and OpenCode. — FR-001, FR-002, FR-003.
• US-021-02 — Automatic project context. As the LLM coding agent, when I begin work, the platform injects project-scoped knowledge-graph context (files, classes, functions, specs, requirements) into my prompt automatically, so I reason about the real codebase rather than guessing. — FR-004, FR-010, FR-016.
• US-021-03 — Edit-time quality enforcement. As a developer, when the agent edits code, a 5-gate review pipeline runs and blocks errors and policy violations before they reach CI, so regressions (mocking, relative imports, oversized functions, hardcoded secrets, pip/bare-except) are prevented at the source. — FR-005, FR-006, FR-008.
• US-021-04 — Deception detection. As a developer, when the agent claims an action (file created, command executed, file read), the platform verifies it actually happened, so I am not misled by unperformed actions. — FR-007.
• US-021-05 — In-session tooling. As the LLM coding agent, I have custom tools for session operations, KG queries, conversation tracking, and code review directly inside the session, so I can act on Orchestrata state without leaving OpenCode. — FR-009, FR-011, FR-012.
• US-021-06 — Durable, bounded session record. As the Orchestrata platform, I persist every conversation turn, create git checkpoints, throttle noisy reads, and monitor MCP health across the session, so work is auditable, recoverable, and resource-bounded. — FR-013, FR-014, FR-015, FR-017.

Terminology

Data Models

Session Context Model

{
  "session_seq": "number",
  "purpose": "string",
  "version": "string",
  "branch": "string",
  "testState": "string",
  "status": "ACTIVE|IDLE|COMPLETE",
  "created_at": "ISO8601",
  "updated_at": "ISO8601"
}

KG File Node Model

{
  "id": "string (UUID)",
  "path": "string",
  "language": "string",
  "line_count": "number",
  "size_bytes": "number",
  "package": "string",
  "classes": [
    {
      "name": "string",
      "line_start": "number",
      "line_end": "number",
      "methods": ["string"]
    }
  ],
  "functions": [
    {
      "name": "string",
      "line_start": "number",
      "line_end": "number",
      "is_async": "boolean"
    }
  ]
}

Conversation Turn Model

{
  "id": "string (UUID)",
  "conversation_id": "string",
  "turn_number": "number",
  "role": "user|assistant",
  "content": "string (max 2000)",
  "timestamp": "ISO8601",
  "platform": "opencode"
}

Code Review Result Model

{
  "file_path": "string",
  "gate": "1|2|3|4|5",
  "status": "PASS|WARN|ERROR",
  "errors": [
    {
      "line": "number",
      "message": "string",
      "rule": "string"
    }
  ],
  "warnings": [
    {
      "line": "number",
      "message": "string",
      "rule": "string"
    }
  ]
}

Deception Detection Result Model

{
  "session_id": "string",
  "findings": [
    {
      "type": "ACTION_DECEPTION|ERROR_CONCEALMENT|FILE_READING_DECEPTION",
      "severity": "CRITICAL|HIGH|MEDIUM",
      "claim": "string",
      "evidence": "string",
      "tool_calls_required": ["string"],
      "tool_calls_found": ["string"]
    }
  ],
  "audited_at": "ISO8601"
}

Functional Requirements

FR-001: Plugin Lifecycle Hooks

The OrchestrataPlugin MUST hook into all 7 OpenCode lifecycle events: session.created, session.idle, tool.execute.before, tool.execute.after, message.updated, file.edited, and experimental.session.compacting.

FR-002: Session Auto-Start

On session.created, the plugin MUST automatically start or resume a session via session_cli.py and display session information including seq, purpose, version, branch, and test state.

FR-003: Session Auto-End

On session.idle, the plugin MUST automatically end the session with git-extracted achievements, flush the KG sync queue, flush the conversation queue, and clear session state.

FR-004: KG Context Injection

On file reads within the Orchestrata project directory, the plugin MUST inject knowledge graph context including classes, functions, traceability links, and inheritance hierarchy into tool arguments as _orchestrata_context.

FR-005: 5-Gate Code Review Pipeline

On file.edited for Python files in packages/, the plugin MUST execute a 5-gate code review: Gate 1 (syntax/format), Gate 2 (lint), Gate 3 (runtime/security), Gate 4 (complexity/nesting), Gate 5 (naming/design).

FR-006: Error Blocking

Code review errors MUST block the edit and force the agent to fix issues before proceeding. Warnings MUST be displayed but not block the edit.

FR-007: Deception Detection

On session.idle, the plugin MUST analyze the assistant's final message against tool call history to detect ACTION_DECEPTION, ERROR_CONCEALMENT, and FILE_READING_DECEPTION with appropriate severity levels.

FR-008: Policy Enforcement

The plugin MUST enforce development policies during tool.execute.before: testing policy (block mocking), import policy (block relative imports), development policy (block pip), bash safety (block destructive patterns), write policy (block ~/.claude/plans/).

FR-009: Custom Tools Availability

All 24 custom tools (9 session, 12 KG, 3 conversation) MUST be available and functional within OpenCode sessions when the OrchestrataPlugin is active.

FR-010: KG Query Project Scoping

All KG query tools MUST automatically scope Cypher queries to the current project by anchoring through the Project node relationship chain.

FR-011: Redis Queue Management

The plugin MUST use Redis SET orchestrata:kg:sync:queue for KG sync pending files and LIST orchestrata:conversation:queue for conversation turns pending Neo4j storage.

FR-012: Memory Search Trigger

On message.updated, the plugin MUST detect "remember when" and 7 other trigger patterns, extract the topic, search last 20 sessions, and inject top 10 matches as context.

FR-013: Read Throttling

The plugin MUST enforce a per-session read limit of 50 file reads to prevent excessive file scanning without search-first patterns.

FR-014: Git Checkpoint Creation

Before any edit or write operation, the plugin MUST create a git checkpoint to enable rollback on failure.

FR-015: Conversation Storage

User and assistant messages MUST be queued to Redis and flushed to Neo4j on session close, creating Conversation and ConversationTurn nodes with platform="opencode".

FR-016: KG Sync Daemon

The plugin MUST support background KG synchronization via a daemon process that can be started, stopped, and queried for status.

FR-017: MCP Health Monitoring

The plugin MUST check MCP server health (document-reader at port 3456, document-writer at port 3457) on session start and log availability.

Error Conditions

Non-Functional Requirements

Performance

• KG context injection MUST complete within 500ms per file read
• Code review pipeline MUST complete within 5 seconds per file
• Memory search MUST return results within 1 second
• Session start/end operations MUST complete within 2 seconds

Scalability

• Tool call history bounded to 100 entries per session
• Conversation queue bounded to 1000 items before dropping
• KG sync queue bounded to 500 files before blocking

Reliability

• All non-blocking failures logged with context
• Queue operations use Redis atomic commands
• Git checkpoints use --no-verify to prevent hook failures

Maintainability

• Plugin code follows TypeScript best practices
• Agent definitions in Markdown for easy editing
• Tool implementations modular with clear separation

Governance

Code Quality Governance

1. 5-Gate Review: All Python edits in packages/ MUST pass through the 5-gate review pipeline before commit
2. Naming Standards: snake_case for functions, PascalCase for classes, UPPER_SNAKE for constants
3. Complexity Limits: Max 10 branches, max 5 nesting depth, max 40 lines per function

Policy Governance

1. Testing: Mocking patterns blocked in test files
2. Imports: Relative imports prohibited
3. Package Management: pip prohibited, uv required
4. Secrets: Hardcoded secrets, passwords, API keys, tokens detected and flagged

Session Governance

1. Lifecycle: All sessions MUST be tracked in context.json
2. Achievements: Session end MUST extract achievements from git log
3. Tracking: Tool usage history retained for deception auditing

Testing

Unit Tests

• Deception detection regex patterns tested against known cases
• Policy enforcement rules tested with sample code
• Read throttle counter tested with boundary values

Integration Tests

• Session lifecycle: create, update, end flow tested end-to-end
• KG context injection tested with mock Neo4j responses
• Queue operations tested with Redis test instance

E2E Tests

• Full session flow: start, work, remember-when search, close
• Code review pipeline tested with sample Python files
• Tool execution with policy enforcement

Test Coverage Targets

• Deception detection: 90%+ pattern coverage
• Policy enforcement: 100% of documented policies
• Session management: all lifecycle states covered

Integration Points

External Systems

Internal Modules

Success Criteria

Core Functionality

• [ ] Plugin loads and hooks into all 7 lifecycle events
• [ ] Session auto-start/end works without manual intervention
• [ ] KG context injected on file reads for Orchestrata files
• [ ] 5-gate code review executes on every Python edit in packages/
• [ ] Policy enforcement blocks prohibited patterns

Tool Availability

• [ ] All 24 custom tools functional and documented
• [ ] KG query tools scope results to current project
• [ ] Session tools work with context.json

Quality Assurance

• [ ] Deception detection identifies all 3 claim types
• [ ] Memory search returns relevant past sessions
• [ ] Read throttle prevents runaway file scanning

Integration

• [ ] Redis queues persist across session states
• [ ] Neo4j stores conversation history correctly
• [ ] Git checkpoints created before edits

Performance

• [ ] KG context injection < 500ms
• [ ] Code review < 5 seconds
• [ ] Session operations < 2 seconds

User Scenarios & Stories

US-001: Automatic KG Context Injection (P0)

As a developer using OpenCode on the Orchestrata project I want file reads and searches to automatically include knowledge graph context So that the LLM understands the file's classes, functions, specs, and relationships without manual queries

Acceptance Criteria:

• [ ] File reads on Orchestrata project files trigger KG context lookup
• [ ] Context includes classes defined in the file with line ranges
• [ ] Context includes functions defined in the file with async flags
• [ ] Context includes traceability links to requirements and specs
• [ ] Context includes inheritance hierarchy for classes in the file
• [ ] KG context is injected as _orchestrata_context in tool args
• [ ] Context injection is non-blocking (failures do not prevent file reads)

US-002: Session Management (P0)

As a developer using OpenCode I want sessions to auto-start on connection and auto-close on idle So that all work is tracked in context.json without manual intervention

Acceptance Criteria:

• [ ] session.created hook auto-starts or resumes a session via session CLI
• [ ] Session info (seq, purpose, version, branch, tests) displayed on start
• [ ] Pending deferred work items shown on session start (top 5)
• [ ] session.idle hook auto-ends the session with git-extracted achievements
• [ ] Session state cleared (tool history, read count) on session end
• [ ] KG sync queue flushed on session close
• [ ] Conversation queue flushed on session close
• [ ] Project state updated to ACTIVE on session start

US-003: Code Quality Enforcement (P0)

As a developer editing Python files in packages/ I want a 5-gate code review to run automatically on every file edit So that syntax errors, lint violations, security issues, complexity, and naming problems are caught immediately

Acceptance Criteria:

• [ ] Gate 1 (Syntax & Format): py_compile, black --check, isort --check all pass
• [ ] Gate 2 (Lint): flake8 with E/F/W/C90 selectors, max-line-length 88, ignoring E203/W503/E501
• [ ] Gate 3 (Runtime & Security): mypy, module import check, hardcoded secrets/passwords/API keys/tokens detection, debug print detection, temporary comment detection, bare except: detection
• [ ] Gate 4 (Complexity & Nesting): branch count limit 10 (error) / 7 (warn), nesting depth limit 5 (error) / 4 (warn), line length > 100 chars warning, function size > 40 lines warning
• [ ] Gate 5 (Naming & Design): snake_case for functions, PascalCase for classes, UPPER_SNAKE for constants, god object detection (> 20 methods), feature envy detection (> 15 self references)
• [ ] Errors block the edit and force the agent to fix issues before proceeding
• [ ] Warnings are displayed but do not block the edit
• [ ] Quick-fix suggestions (black, isort commands) shown in error output
• [ ] Only Python files under packages/ trigger the review

US-004: Deception Detection (P1)

As a user reviewing LLM work I want the system to detect when the LLM claims actions it did not perform So that false claims about file creation, command execution, or file reading are flagged

Acceptance Criteria:

• [ ] ACTION_DECEPTION (CRITICAL): Detected when LLM claims file creation without Write/Edit tool usage
• [ ] ACTION_DECEPTION (CRITICAL): Detected when LLM claims command execution without Bash tool usage
• [ ] FILE_READING_DECEPTION (HIGH): Detected when LLM claims file reading without Read/Grep tool usage
• [ ] ERROR_CONCEALMENT (CRITICAL): Detected when tool errors are not acknowledged in the response
• [ ] Quoted content (code blocks, inline code, blockquotes) excluded from deception analysis
• [ ] Deception audit report generated on session.idle with severity icons and evidence
• [ ] Tool call history tracked across the entire session (last 100 calls)
• [ ] Tool call history cleared on session end

US-005: Policy Enforcement (P0)

As a project maintainer I want development policies automatically enforced during tool execution So that mocking, relative imports, pip usage, and destructive commands are prevented

Acceptance Criteria:

• [ ] Testing policy: unittest.mock, MagicMock, @patch, AsyncMock, Mock(), patch.object blocked in test files
• [ ] Import policy: relative imports (from . import) blocked in all Python files
• [ ] Development policy: pip install, pip3 install, pip sync blocked with uv suggestions
• [ ] Development policy: requirements.txt references blocked with pyproject.toml suggestion
• [ ] Bash safety: rm -rf /, fork bombs, >/dev/null destructive patterns blocked
• [ ] Write policy: writes to ~/.claude/plans/ blocked with redirect to ~/workspace/orchestrata/plans/
• [ ] Policy violations throw descriptive errors with suggested alternatives

US-006: Custom Tools (P1)

As a developer using OpenCode I want 24 custom tools for session management, KG queries, and code review So that the LLM can programmatically interact with Orchestrata infrastructure

Acceptance Criteria:

• [ ] Session tools (9): session-status, session-begin, session-end, session-log-work, session-log-achievement, session-add-work, session-complete-work, session-update-state, session-log-choice
• [ ] KG tools (12): kg-query, kg-sync, kg-queue-status, kg-flush-queue, kg-file-context, kg-daemon-start, kg-daemon-stop, kg-daemon-status, kg-find-file, kg-find-entity, kg-stats, kg-cxp-thread
• [ ] Conversation tools (3): conv-sync, conv-status, conv-query
• [ ] Code review tools (2): code-review, code-fix (if applicable)
• [ ] All tools have description and typed args
• [ ] KG tools only activate for the Orchestrata project directory
• [ ] Session tools work for any project with context.json

US-007: Conversation Tracking (P2)

As the system I want conversation turns stored in Neo4j via Redis queue So that session interactions are preserved for analysis and memory search

Acceptance Criteria:

• [ ] User messages queued to Redis list orchestrata:conversation:queue on message.updated
• [ ] Messages truncated to 2000 characters before queuing
• [ ] Queue flushed to Neo4j on session close, creating Conversation and ConversationTurn nodes
• [ ] ConversationTurn nodes linked to Conversation via HAS_TURN relationship
• [ ] Conversation nodes keyed by opencode-{session_seq}
• [ ] Platform field set to "opencode" on all nodes
• [ ] Queue processing is non-blocking (failures do not interrupt session close)

US-008: Memory Search (P2)

As a developer asking "remember when..." I want the system to search session history for matching context So that previous decisions, achievements, and work logs are recalled automatically

Acceptance Criteria:

• [ ] Trigger phrases: "remember when", "do you remember", "recall when", "remember that", "we discussed", "we talked about", "last time we", "what happened with"
• [ ] Topic extracted from text after the trigger phrase
• [ ] Search covers last 20 sessions in context.json
• [ ] Matches found in session purpose, achievements, and work logs
• [ ] Top 10 results injected as context with session number, date, and match type
• [ ] Short words (< 3 characters) excluded from search terms
• [ ] No-match case returns "No matching sessions found" message

US-009: KG Sync Daemon (P1)

As the system I want modified files queued for background KG synchronization So that the knowledge graph stays current as code evolves during sessions

Acceptance Criteria:

• [ ] Files passing code review are added to Redis set orchestrata:kg:sync:queue
• [ ] KG sync triggered in background on session.created via sync_monorepo_to_neo4j.py
• [ ] Queue flushed synchronously on session close using FileSynchronizer
• [ ] Queue count available via kg-queue-status tool
• [ ] Queue can be manually flushed via kg-flush-queue tool
• [ ] Daemon start/stop/status tools available for manual control
• [ ] Queue operations are non-blocking (failures do not interrupt workflow)

US-010: Agent Intelligence (P1)

As a developer working with OpenCode I want two agents that automatically detect context triggers and query the KG So that relevant project knowledge is available without manual Cypher queries

Acceptance Criteria:

• [ ] Auto KG Context Agent activates on file paths, class/function names, spec IDs (SPEC-NNN, REQ-NNN)
• [ ] Auto agent queries: file info, classes, functions, traceability links, inheritance hierarchy
• [ ] KG Context Agent provides manual complement for architectural relationship queries
• [ ] Both agents connect to the operational KG (Memgraph, orchkg database) at the active env profile's endpoint (test fleet: bolt://10.53.2.10:7687)
• [ ] Agent results formatted for LLM consumption with clear labels
• [ ] Agents run transparently without requiring explicit user invocation

Architecture

Plugin Architecture (3,234 lines)

opencode/plugins/orchestrata.ts
├── State Management
│   ├── toolCallHistory[]: Tool call tracking for deception detection
│   ├── readCount: File read throttle counter (limit: 50/session)
│   └── MCP_SERVERS[]: Health check endpoints for document-reader/writer
├── Helper Functions
│   ├── checkMcpHealth(): MCP server availability check
│   ├── removeQuotedContent(): Strip code blocks/quotes for deception analysis
│   ├── detectDeception(): Compare claimed actions vs actual tool usage
│   ├── enforceTestingPolicy(): Block mocking patterns in test files
│   ├── enforceImportPolicy(): Block relative imports
│   └── enforceDevelopmentPolicy(): Block pip, require uv
└── Lifecycle Hooks (7)
    ├── session.created: Auto-start session, inject context, start KG sync
    ├── session.idle: Deception audit, session close, queue flush
    ├── tool.execute.before: KG injection, policies, git checkpoint, bash safety
    ├── tool.execute.after: Operation logging, deception tracking
    ├── message.updated: Remember-when search, session close, conversation storage
    ├── file.edited: 5-gate code review, KG sync queue
    └── experimental.session.compacting: Custom session context injection

Hook Mapping: Claude Code to OpenCode

Deployment Layout

Source:
  open-code/
  ├── agents/
  │   ├── auto-kg-context.md    # Auto KG context agent definition
  │   └── kg-context-agent.md   # Manual KG context agent definition
  ├── commands/
  │   └── query-kg.md           # /query-kg slash command definition
  ├── plugins/
  │   └── orchestrata.ts        # Main plugin (3,234 lines)
  ├── tools/
  │   ├── kg_query              # Bash wrapper for uv environment
  │   ├── kg_query.py           # Full-featured async query tool
  │   ├── kg_query_inner.py     # Core implementation with project scoping
  │   ├── neo4j_query.py        # Standalone direct query tool
  │   └── simple_kg_query.py    # Simplified connectivity test
  ├── install.sh                # Deployment script
  └── config/                   # OpenCode configuration

Deployed:
  ~/.opencode/
  ├── agents/                   # Agent definitions
  ├── commands/                 # Command definitions
  ├── plugins/                  # Plugin (compiled)
  └── tools/                    # Python query tools
  ~/.config/opencode/           # OpenCode config

Data Flow

                    ┌──────────────────────┐
                    │   OpenCode Session   │
                    └──────────┬───────────┘
                               │
                    ┌──────────▼───────────┐
                    │  OrchestrataPlugin   │
                    │  (orchestrata.ts)    │
                    └──────────┬───────────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
┌────────▼────────┐  ┌────────▼────────┐  ┌────────▼────────┐
│  session_cli.py │  │  Memgraph KG    │  │   Redis Queue   │
│  (context.json) │  │ bolt://10.93.   │  │ 10.53.2.11:6379│
│                 │  │  53.10:7687     │  │                 │
│  - begin        │  │                 │  │  - kg:sync:     │
│  - end          │  │  - File nodes   │  │    queue (SET)  │
│  - log-work     │  │  - Class nodes  │  │  - conversation │
│  - status       │  │  - Function     │  │    :queue (LIST)│
│  - update-state │  │  - Requirement  │  │                 │
└─────────────────┘  │  - Spec nodes   │  └─────────────────┘
                     │  - Conversation │
                     │  - Turn nodes   │
                     └─────────────────┘

5-Gate Code Review Pipeline

File Edit (packages/*.py)
    │
    ▼
┌─────────────────────────────────────────────────────┐
│ GATE 1: Syntax & Format                             │
│   py_compile → black --check → isort --check        │
│   Errors: syntax errors, formatting violations      │
├─────────────────────────────────────────────────────┤
│ GATE 2: Lint                                        │
│   flake8 --select=E,F,W,C90 --max-line-length=88   │
│   Errors: E9xx, F63x, F72x (fatal)                 │
│   Warnings: other E/W/C codes                       │
├─────────────────────────────────────────────────────┤
│ GATE 3: Runtime & Security                          │
│   mypy (type check) → module import test            │
│   Security: hardcoded passwords/keys/secrets/tokens │
│   Quality: debug prints, temporary comments, bare except    │
│   Logging: missing logger, unlogged exceptions      │
│   Traceability: @traces decorator presence          │
├─────────────────────────────────────────────────────┤
│ GATE 4: Complexity & Nesting                        │
│   Branches: >10 error, >7 warn                     │
│   Nesting: >5 error, >4 warn                       │
│   Line length: >100 chars warn                      │
│   Function size: >40 lines warn                     │
├─────────────────────────────────────────────────────┤
│ GATE 5: Naming & Design                             │
│   Functions: must be snake_case                     │
│   Classes: must be PascalCase                       │
│   Constants: UPPER_SNAKE_CASE                       │
│   God objects: >20 methods warn                     │
│   Feature envy: >15 self references warn            │
│   Patterns: singleton, factory, builder, dataclass  │
└─────────────────────────────────────────────────────┘
    │
    ▼
  Errors? → Block edit, force fix
  Warnings? → Display, allow edit
  Pass? → Queue file for KG sync

Deception Detection Model

Tool Call History (per session, max 100)
    │
    ▼
On session.idle:
    │
    ├── Extract assistant's final message
    ├── Remove quoted content (```, `, >)
    ├── Check file creation claims → require Write/Edit in history
    ├── Check command execution claims → require Bash in history
    ├── Check file reading claims → require Read/Grep in history
    ├── Check for unacknowledged tool errors
    │
    ▼
┌─────────────────────────────────┐
│ Findings (severity levels):     │
│   CRITICAL: ACTION_DECEPTION    │
│   CRITICAL: ERROR_CONCEALMENT   │
│   HIGH: FILE_READING_DECEPTION  │
└─────────────────────────────────┘

Examples

Plugin Activation Example

The OrchestrataPlugin automatically activates when OpenCode starts a session in the Orchestrata project:

// orchestrata.ts - Plugin activation check
import { OpenCodePlugin } from '@opencode-ai/plugin';

export const OrchestrataPlugin: OpenCodePlugin = {
  name: 'orchestrata',
  matches: (context) => {
    const workspacePath = context.workspacePath;
    return workspacePath.startsWith('/home/mohamed/workspace') 
           && context.hasFile('context.json');
  }
};

Session Lifecycle Example

# Session auto-starts on OpenCode connection (triggered by session.created hook)
$ opencode

# Session info displayed automatically:
# ┌─────────────────────────────────────────┐
# │ Session #42 | P1 | Active              │
# │ Purpose: Implement SPEC-021            │
# │ Branch: feature/opencode-integration   │
# │ Test State: 3/15 passing               │
# └─────────────────────────────────────────┘

# Session auto-ends on "close the session" (triggered by session.idle hook)
> close the session

# Session close report:
# ┌─────────────────────────────────────────┐
# │ Session #42 Closed                      │
# │ Achievements:                           │
# │   - Added OrchestrataPlugin (3,234 LOC) │
# │   - Implemented 5-gate code review      │
# │   - Added deception detection           │
# │ Pushed to origin ✓                     │
# └─────────────────────────────────────────┘

KG Context Injection Example

When reading a file in the Orchestrata project, KG context is automatically injected:

# Tool call: Read /home/mohamed/workspace/orchestrata/packages/core/traceability/__init__.py

# Request:
{
  "filePath": "/home/mohamed/workspace/orchestrata/packages/core/traceability/__init__.py"
}

# Response (with _orchestrata_context injected):
{
  "content": "...",
  "_orchestrata_context": {
    "file": {
      "path": "/home/mohamed/workspace/orchestrata/packages/core/traceability/__init__.py",
      "language": "python",
      "line_count": 247
    },
    "classes": [
      {
        "name": "TraceabilityModule",
        "line_start": 45,
        "line_end": 189,
        "methods": ["add_requirement", "link_spec", "query_graph", "export_trace"]
      }
    ],
    "functions": [
      {
        "name": "create_traceability_link",
        "line_start": 12,
        "line_end": 34,
        "is_async": true
      }
    ],
    "spec_links": [
      {"spec_id": "001", "requirement": "REQ-001-US-001-012"}
    ]
  }
}

Code Review Pipeline Example

Editing a Python file triggers the 5-gate code review:

# File edit detected: packages/core/traceability/module.py

# GATE 1: Syntax & Format
$ py_compile packages/core/traceability/module.py
✓ PASS

$ black --check packages/core/traceability/module.py
✓ PASS

$ isort --check packages/core/traceability/module.py
✓ PASS

# GATE 2: Lint
$ flake8 packages/core/traceability/module.py --select=E,F,W,C90 --max-line-length=88
✓ PASS (0 errors, 2 warnings)

# GATE 3: Runtime & Security
$ mypy packages/core/traceability/module.py
✓ PASS

# Security scan:
✓ No hardcoded secrets detected
✓ No debug prints detected
✓ No temporary comments detected

# GATE 4: Complexity & Nesting
✓ Branches: 7 (warn threshold: 7)
✓ Nesting: 4 (warn threshold: 4)
✓ Line length: 2 warnings (> 100 chars)
✓ Function size: OK

# GATE 5: Naming & Design
✓ Functions: snake_case ✓
✓ Classes: PascalCase ✓
✓ Constants: UPPER_SNAKE_CASE ✓

# RESULT: PASS (2 warnings, 0 errors)
# File queued for KG sync: orchestrata:kg:sync:queue

Deception Detection Example

When the LLM claims actions not performed:

// session.idle hook triggers deception analysis

// Assistant's final message:
// "I've created the new authentication module and ran the tests."

// Tool call history (last 100):
// - Read: auth.py
// - Grep: "def authenticate"
// - Write: auth_test.py (contains test code)

// Deception detection result:
{
  "session_id": "42",
  "findings": [
    {
      "type": "ACTION_DECEPTION",
      "severity": "CRITICAL",
      "claim": "I've created the new authentication module",
      "evidence": "No Write or Edit tool calls found in history for 'authentication module'",
      "tool_calls_required": ["Write", "Edit"],
      "tool_calls_found": ["Read", "Grep"]
    },
    {
      "type": "ACTION_DECEPTION",
      "severity": "CRITICAL", 
      "claim": "ran the tests",
      "evidence": "No Bash tool calls found in history",
      "tool_calls_required": ["Bash"],
      "tool_calls_found": ["Write"]
    }
  ],
  "audited_at": "2026-04-09T15:32:00Z"
}

Policy Enforcement Example

Blocked patterns during tool execution:

# Testing policy violation (in test_file.py)
$ @patch('module.Class')
# ERROR: Mocking patterns blocked in test files
# Suggestion: Use real implementations or integration tests

# Import policy violation  
$ from . import utils
# ERROR: Relative imports prohibited
# Suggestion: Use absolute imports: from package.utils import ...

# Development policy violation
$ pip install requests
# ERROR: pip prohibited - use uv
# Suggestion: uv add requests

# Bash safety violation
$ rm -rf /
# ERROR: Destructive command blocked
# Message logged to security team

# Write policy violation
$ Write: ~/.claude/plans/feature.md
# ERROR: Direct writes to ~/.claude/plans/ prohibited
# Suggestion: Write to ~/workspace/orchestrata/plans/ instead

KG Query Tools Example

# Using the /query-kg command
/query-kg "MATCH (f:File) RETURN f.path, f.language ORDER BY f.line_count DESC LIMIT 10"

/query-kg "MATCH (c:Class)-[:DEFINES_METHOD]->(m:Method) WHERE c.name = 'TraceabilityModule' RETURN m.name"

/query-kg "MATCH (s:Spec {id: '001'})-[:DEFINES_REQUIREMENT]->(r:Requirement) RETURN r.id, r.text"

Session Management Tools Example

# Check session status
> session-status
# ┌─────────────────────────────────────────┐
# │ Session #42 | P1 | Active              │
# │ Purpose: Implement SPEC-021            │
# │ Branch: feature/opencode-integration   │
# │ Test State: 3/15 passing               │
# └─────────────────────────────────────────┘

# Log work
> session-log-work --desc "Implemented 5-gate review pipeline" --details ["Gate 1-3 complete", "Gate 4-5 remaining"]

# Log achievement
> session-log-achievement --item "Added deception detection (3 patterns)"

# Add deferred work
> session-add-work --text "Add memory search agent" --priority "P2"

# Complete work
> session-complete-work --text "Add memory search agent"

Memory Search Example

# User asks:
> Remember when we implemented the deception detection?

# Plugin detects "remember when" trigger, extracts topic: "deception detection"
# Searches last 20 sessions for matches

# Results injected into context:
# ┌─────────────────────────────────────────┐
# │ Memory Search: "deception detection"    │
# │ ─────────────────────────────────────── │
# │ Session #38 (2026-04-01)               │
# │   Match: purpose - "Add deception detection patterns" │
# │ Session #35 (2026-03-28)               │
# │   Match: achievement - "Implemented action deception"│
# │ Session #31 (2026-03-25)               │
# │   Match: work log - "Tested error concealment"       │
# └─────────────────────────────────────────┘

Redis Queue Status Example

# Check KG sync queue
> kg-queue-status
# Pending files: 12
# Queue: [packages/core/module.py, packages/core/utils.py, ...]

# Check conversation queue
> conv-status
# Pending turns: 47
# Oldest: session-42, turn-3 (2 minutes ago)
# Newest: session-42, turn-49 (30 seconds ago)

# Flush queues
> kg-flush-queue
# Synced 12 files to Neo4j ✓

> conv-sync
# Flushed 47 conversation turns to Neo4j ✓

API Contracts

OrchestrataPlugin

interface OrchestrataPlugin {
  // Lifecycle hooks
  onSessionCreated(handler: (session: SessionContext) => Promise<void>): void;
  onSessionIdle(handler: (session: SessionContext) => Promise<void>): void;
  onToolExecuteBefore(handler: (tool: ToolCall) => Promise<ToolCall>): void;
  onToolExecuteAfter(handler: (tool: ToolCall, result: ToolResult) => Promise<void>): void;
  onMessageUpdated(handler: (message: Message) => Promise<void>): void;
  onFileEdited(handler: (file: FileEdit) => Promise<FileEditResult>): void;
  onSessionCompacting(handler: (context: SessionContext) => Promise<ContextInjection>): void;
}

interface SessionContext {
  sessionSeq: number;
  purpose: string;
  version: string;
  branch: string;
  testState: string;
  status: 'ACTIVE' | 'IDLE' | 'COMPLETE';
  createdAt: string;
  updatedAt: string;
}

interface ToolCall {
  name: string;
  arguments: Record<string, unknown>;
  id: string;
  timestamp: string;
}

interface ToolResult {
  success: boolean;
  output?: string;
  error?: string;
}

interface FileEdit {
  filePath: string;
  content: string;
  language: string;
}

interface FileEditResult {
  allowed: boolean;
  errors?: CodeIssue[];
  warnings?: CodeIssue[];
}

interface CodeIssue {
  line: number;
  message: string;
  rule: string;
  severity: 'ERROR' | 'WARN';
}

interface ContextInjection {
  additions: Record<string, unknown>;
  priority: number;
}

Session CLI

# Session management commands
async def session_begin(purpose: str, objectives: list[str] = None) -> SessionContext:
    """Start a new session"""
    
async def session_end(achievements: list[str] = None, upcoming: list[str] = None) -> SessionCloseResult:
    """End current session"""
    
async def session_status() -> SessionStatus:
    """Get current session info"""
    
async def session_update_state(
    version: str = None,
    branch: str = None,
    testState: str = None,
    status: str = None
) -> SessionContext:
    """Update session state"""
    
async def session_log_work(desc: str, details: list[str] = None) -> WorkEntry:
    """Log a work entry"""
    
async def session_log_achievement(item: str) -> Achievement:
    """Log an achievement"""
    
async def session_add_work(text: str, priority: str = None, notes: str = None) -> WorkItem:
    """Add deferred work item"""
    
async def session_complete_work(text: str) -> WorkItem:
    """Mark work item as complete"""
    
async def session_log_choice(choice: str, reason: str) -> TechnicalChoice:
    """Log a technical decision"""

class SessionStatus(TypedDict):
    session_seq: int
    purpose: str
    version: str
    branch: str
    testState: str
    status: str
    created_at: str
    updated_at: str

class SessionCloseResult(TypedDict):
    session_seq: int
    achievements: list[str]
    flush_kg_sync: bool
    flush_conversation: bool

Knowledge Graph Client

class Neo4jKGClient:
    async def connect(self, uri: str, username: str, password: str) -> None:
        """Connect to Neo4j instance"""
        
    async def close(self) -> None:
        """Close connection"""
        
    async def execute_query(
        self,
        query: str,
        parameters: dict = None,
        project_scope: str = None
    ) -> list[dict]:
        """Execute Cypher query with optional project scoping"""
        
    async def get_file_context(self, path: str) -> KGFileContext:
        """Get KG context for a file"""
        
    async def get_entity_context(self, name: str, entity_type: str = None) -> KGEntityContext:
        """Get KG context for class/function"""
        
    async def get_traceability_links(
        self,
        file_path: str = None,
        spec_id: str = None,
        requirement_id: str = None
    ) -> list[TraceabilityLink]:
        """Get traceability links"""
        
    async def get_inheritance_hierarchy(
        self,
        class_name: str,
        depth: int = 3
    ) -> InheritanceChain:
        """Get class inheritance hierarchy"""

class KGFileContext(TypedDict):
    id: str
    path: str
    language: str
    line_count: int
    size_bytes: int
    package: str
    classes: list[ClassInfo]
    functions: list[FunctionInfo]

class ClassInfo(TypedDict):
    name: str
    line_start: int
    line_end: int
    methods: list[str]

class FunctionInfo(TypedDict):
    name: str
    line_start: int
    line_end: int
    is_async: bool

class TraceabilityLink(TypedDict):
    source_type: str
    source_id: str
    target_type: str
    target_id: str
    relationship: str

class InheritanceChain(TypedDict):
    class_name: str
    ancestors: list[str]
    depth: int

Redis Queue Manager

class QueueManager:
    async def enqueue_kg_sync(self, file_path: str) -> int:
        """Add file to KG sync queue (returns queue size)"""
        
    async def dequeue_kg_sync(self, count: int = None) -> list[str]:
        """Remove and return files from KG sync queue"""
        
    async def get_kg_queue_size(self) -> int:
        """Get KG sync queue size"""
        
    async def flush_kg_queue(self) -> int:
        """Flush all items from KG sync queue (returns count)"""
        
    async def enqueue_conversation(
        self,
        conversation_id: str,
        turn: ConversationTurn
    ) -> int:
        """Add turn to conversation queue"""
        
    async def dequeue_conversation(
        self,
        count: int = None
    ) -> list[ConversationTurn]:
        """Remove and return turns from conversation queue"""
        
    async def get_conversation_queue_size(self) -> int:
        """Get conversation queue size"""
        
    async def flush_conversation_queue(self) -> list[ConversationTurn]:
        """Flush all turns from conversation queue"""

class ConversationTurn(TypedDict):
    id: str
    conversation_id: str
    turn_number: int
    role: str
    content: str
    timestamp: str
    platform: str

Code Review Pipeline

class CodeReviewPipeline:
    async def review_file(self, file_path: str, content: str) -> CodeReviewResult:
        """Execute 5-gate code review"""
        
    async def gate1_syntax_format(self, content: str) -> GateResult:
        """Gate 1: Syntax & Format (py_compile, black, isort)"""
        
    async def gate2_lint(self, content: str) -> GateResult:
        """Gate 2: Lint (flake8)"""
        
    async def gate3_runtime_security(self, content: str) -> GateResult:
        """Gate 3: Runtime & Security (mypy, secrets, etc)"""
        
    async def gate4_complexity(self, content: str) -> GateResult:
        """Gate 4: Complexity & Nesting"""
        
    async def gate5_naming_design(self, content: str) -> GateResult:
        """Gate 5: Naming & Design"""

class CodeReviewResult(TypedDict):
    file_path: str
    gates: list[GateResult]
    blocked: bool
    errors: list[CodeIssue]
    warnings: list[CodeIssue]

class GateResult(TypedDict):
    gate: int
    name: str
    status: 'PASS' | 'FAIL' | 'WARN'
    errors: list[CodeIssue]
    warnings: list[CodeIssue]

Policy Enforcement

class PolicyEnforcer:
    def enforce_testing_policy(self, content: str, file_path: str) -> PolicyResult:
        """Block mocking patterns in test files"""
        
    def enforce_import_policy(self, content: str) -> PolicyResult:
        """Block relative imports"""
        
    def enforce_development_policy(self, arguments: dict) -> PolicyResult:
        """Block pip, require uv"""
        
    def enforce_bash_safety(self, command: str) -> PolicyResult:
        """Block destructive bash patterns"""
        
    def enforce_write_policy(self, file_path: str) -> PolicyResult:
        """Block writes to prohibited paths"""

class PolicyResult(TypedDict):
    allowed: bool
    violation: str
    suggestion: str

Deception Detection

class DeceptionDetector:
    def analyze(
        self,
        final_message: str,
        tool_call_history: list[ToolCall]
    ) -> DeceptionReport:
        """Analyze message for deception claims"""
        
    def check_file_creation_claims(
        self,
        message: str,
        tool_history: list[ToolCall]
    ) -> list[DeceptionFinding]:
        """Detect false file creation claims"""
        
    def check_command_claims(
        self,
        message: str,
        tool_history: list[ToolCall]
    ) -> list[DeceptionFinding]:
        """Detect false command execution claims"""
        
    def check_file_reading_claims(
        self,
        message: str,
        tool_history: list[ToolCall]
    ) -> list[DeceptionFinding]:
        """Detect false file reading claims"""
        
    def check_error_concealment(
        self,
        message: str,
        tool_results: list[ToolResult]
    ) -> list[DeceptionFinding]:
        """Detect unacknowledged tool errors"""

class DeceptionReport(TypedDict):
    session_id: str
    findings: list[DeceptionFinding]
    audited_at: str

class DeceptionFinding(TypedDict):
    type: 'ACTION_DECEPTION' | 'ERROR_CONCEALMENT' | 'FILE_READING_DECEPTION'
    severity: 'CRITICAL' | 'HIGH' | 'MEDIUM'
    claim: str
    evidence: str
    tool_calls_required: list[str]
    tool_calls_found: list[str]

Custom Tools Reference

Session Tools (9)

KG Tools (12)

Conversation Tools (3)

KG Query Tools (Python)

Tool Hierarchy

kg_query (bash wrapper)
    └── kg_query_inner.py (invoked via uv run)
            └── Neo4jClient from orchestrata.knowledge

kg_query.py (standalone async)
    └── Neo4jClient from orchestrata.knowledge

neo4j_query.py (standalone async)
    └── Neo4jClient from orchestrata.knowledge (with fallback mock)

simple_kg_query.py (connectivity test)
    └── Neo4jClient from orchestrata.knowledge

Project Scoping (kg_query_inner.py)

The inner query tool automatically rewrites Cypher queries to scope results to the current project:

1. File path pattern: MATCH (f:File {path: $path}) rewritten to anchor through (p:Project)-[:HAS_FILE]->(f:File)
2. Spec ID pattern: MATCH (s:Spec {id: $id}) rewritten to anchor through (p:Project)-[:HAS_SPEC]->(s:Spec)
3. Requirement pattern: MATCH (r:Requirement {id: $id}) rewritten to anchor through (p:Project)-[:HAS_REQUIREMENT]->(r:Requirement)
4. General MATCH: Adds WHERE EXISTS { MATCH (p)-[r]->() } clause checking 30+ relationship types from the project node
5. Fallback: Wraps unrecognized queries in project context

Agent Definitions

Auto KG Context Agent (auto-kg-context.md)

Purpose: Automatically provides knowledge graph context without explicit user commands.

Trigger Patterns:

• File references: direct paths (/home/mohamed/workspace/orchestrata/...), relative paths (packages/...), file mentions
• Code elements: class names (TraceabilityModule), function names (create_file_node), method names
• Specification references: SPEC-001, 001-kernel, US-001, REQ-001, REQ-004-US-001-012
• Architectural concepts: sessions, Volks, CXP packets, governance rules, PAM++

Automatic Queries:

• File info: path, language, line count, size
• Classes in file: name, line start/end
• Functions in file: name, line start/end, async flag
• Traceability links: code element to requirement
• Inheritance hierarchy: class to ancestor chain (depth 3)
• Entity search: name-based lookup with file location
• Relationship traversal: inbound and outbound relationships (limit 10)

KG Context Agent (kg-context-agent.md)

Purpose: Manual complement to the auto agent, focusing on architectural relationships and spec-to-code traceability.

Activation: Triggered by mentions of files, classes, functions, code structure questions, refactoring requests, and specification inquiries.

Query Types:

• File-to-class and file-to-function mappings
• Inheritance hierarchies (depth 2)
• Traceability links from code to requirements
• Specification details and requirement listings
• Entity search by name pattern

Commands

/query-kg

Usage: /query-kg <cypher_query> [parameters_json]

Description: Interactive Cypher query execution against the Neo4j knowledge graph.

Examples:

/query-kg "MATCH (n) RETURN count(n) as count"

/query-kg "MATCH (f:File {path: $path}) RETURN f.path, f.line_count, f.language"
  '{"path": "/home/mohamed/.../traceability/__init__.py"}'

/query-kg "MATCH (s:Spec {id: $spec_id})-[:DEFINES_REQUIREMENT]->(r:Requirement)
  RETURN r.id, r.text" '{"spec_id": "001"}'

/query-kg "MATCH (s:Spec) RETURN s.id, s.title ORDER BY s.id"

Connection: from the active env profile (test fleet: bolt://10.53.2.10:7687), database: orchkg (auth-less Memgraph)

Configuration

Infrastructure

Redis Keys

Deployment

# Install from project root
cd open-code && ./install.sh

# Deploys to:
#   ~/.opencode/agents/
#   ~/.opencode/commands/
#   ~/.opencode/plugins/
#   ~/.opencode/tools/
#   ~/.config/opencode/

Dependencies

KG Statistics

Remember-When Memory Search

Trigger Phrases

Search Algorithm

1. Extract topic text after the trigger phrase
2. Split topic into words, filter out words with fewer than 3 characters
3. Load last 20 sessions from context.json
4. For each session (newest first), check:
   • Purpose field for word matches
   • Achievements list for word matches
   • Work log entries for word matches
5. Collect up to 10 matches with session number, date, match type, and matched text
6. Inject results into output context as a formatted block

Session Close Sequence

Detection

Triggers on exact or suffix matches: "close the session", "cts", "cs", "end session", "finish session"

Steps

1. Validate: Check for active session via session_cli.py status --json
2. Extract Achievements: git log --oneline --since="2 hours ago" -20, filter out checkpoint commits, take top 10
3. End Session: session_cli.py end --achievements "..."
4. Push Branch: git push origin HEAD
5. Report: Display formatted close report with session number, achievements, push status
6. Clear State: Reset toolCallHistory and readCount

Error Handling Strategy

All non-blocking failures follow the pattern: try { operation } catch { /* Non-blocking */ log_and_continue }

Security Considerations

1. KG Connection: Endpoint taken from the active env profile (KG_ROUTING_URI/KG_DATABASE); the KG is auth-less Memgraph — no credentials, no local-development fallbacks (RUL-003)
2. Bash Safety: Destructive patterns (rm -rf /, fork bombs) blocked before execution
3. Secret Detection: Hardcoded passwords, API keys, secrets, and tokens flagged in Gate 3
4. Write Restrictions: ~/.claude/plans/ path blocked to prevent plan file creation
5. Read Throttling: 50-read limit prevents runaway file scanning
6. Message Truncation: Conversation content capped at 2000 characters before Neo4j storage
7. Tool History Cap: Only last 100 tool calls retained to bound memory usage

Appendix A: Complete File Inventory

Appendix B: Deception Detection Patterns

File Creation Claims (ACTION_DECEPTION, CRITICAL)

/(?:i'?ve\s+)?(?:created|wrote|written|saved|generated)\s+(?:the\s+)?(?:file|script|config)/
/(?:i'?ve\s+)?(?:created|added)\s+[\w\-]+\.(py|js|ts|json|md|yaml|yml|txt|sh)/
/here'?s\s+the\s+(?:new\s+)?(?:file|script|code)\s+(?:i\s+)?(?:created|wrote)/

Command Execution Claims (ACTION_DECEPTION, CRITICAL)

/(?:i'?ve\s+)?(?:ran|executed|run)\s+(?:the\s+)?(?:command|script|test)/
/(?:i'?ve\s+)?(?:installed|updated|upgraded)\s+(?:the\s+)?(?:package|dependency)/
/running\s+(?:the\s+)?(?:tests?|build|lint)/

File Reading Claims (FILE_READING_DECEPTION, HIGH)

/(?:i'?ve\s+)?(?:read|examined|reviewed|analyzed|looked at)\s+(?:the\s+)?(?:file|code|contents)/
/after\s+(?:reading|examining|reviewing)\s+(?:the\s+)?(?:file|code)/

Observability

Logging Requirements

1. Component Logging
   • Log all major operations with appropriate log levels
   • Include correlation IDs for request tracing
   • Log performance metrics for critical operations
   • Log errors with full context for debugging

Metrics Requirements

1. Performance Metrics
   • Operation duration histograms
   • Request/error rate counters
   • Resource utilization gauges
   • Business metrics relevant to domain

Tracing Requirements

1. Distributed Tracing
   • Trace propagation across component boundaries
   • Span attributes for domain-specific context
   • Trace sampling based on operational needs

Alerting Requirements

1. Critical Alerts
   • Error rate spikes
   • Performance degradation
   • Resource exhaustion
   • Business metric anomalies

Dashboard Requirements

1. Operational Dashboard
   • Real-time system health
   • Performance trends
   • Error analysis
   • Resource monitoring

Visual Architecture

Class Diagram

Revision History

Related

• RTM page for 021-opencode-integration
• All specs
• RTM overview
• Gates