Skip to content

fix: enforce V3 architecture ownership boundaries #269

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
EvanProgramming merged 2 commits into from
Oct 8, 2026
Merged

fix: enforce V3 architecture ownership boundaries #269

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5d2c491
fix: enforce V3 architecture ownership boundaries
EvanProgramming Oct 7, 2026
506d8c4
fix: close architecture review import-check gaps
EvanProgramming Oct 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,73 @@ Azure, Bedrock, Perplexity and Ollama transports retain their existing contracts
The Go UI splits its model, startup, events, update/input handling, navigation,
settings, layout and views inside the same package and Bubble Tea model.

## V3 subsystem ownership contract

This contract covers [V3 foundation issue #227](https://github.com/EvanProgramming/OpenKyrozen/issues/227),
requirements R236–R249. Each row names one package owner, not a new class to scaffold.
The existing components are the migration starting points on V2; the linked issues
implement the V3 behavior. In particular, native AgentEngine execution, separate
Working/Strategic Plans, typed provider responses and typed runtime events are
future work, not capabilities delivered by this ownership change.

| Requirement / subsystem | Package owner and existing components | Responsibility and authority boundary | V3 implementation |
| --- | --- | --- | --- |
| R236 AgentEngine | `agent`: `runtime.AgentRuntime`, turn phases in `preparation`, `action_rounds`, `completion` | Sole foreground model/tool loop coordinator; calls provider, planning and executor contracts. Does not translate provider wire formats or bypass authorization. | [#238](https://github.com/EvanProgramming/OpenKyrozen/issues/238) |
| R237 PlanningService | `tasks`: `engine.TaskManager`, `models`, `ports.TaskStore`; `agent.planner` currently bridges textual plans | Owns Working Plan and Strategic Plan transitions, validation and completion evidence. Working Plans are mutable; Strategic Plans require user approval and material revisions require reapproval. Storage persists transitions; the engine requests them. | [#241](https://github.com/EvanProgramming/OpenKyrozen/issues/241), [#242](https://github.com/EvanProgramming/OpenKyrozen/issues/242), [#245](https://github.com/EvanProgramming/OpenKyrozen/issues/245), [#246](https://github.com/EvanProgramming/OpenKyrozen/issues/246) |
| R238 ToolRegistry | `tools`: `manifest.ToolRegistry`, `ToolManifest`, `registry`, `adapters.ToolAdapters` | Owns definitions, schemas, metadata and executor registration. Supplies the catalog to providers and execution; registration or discovery never grants permission. Extend this registry rather than adding a competing catalog. | [#232](https://github.com/EvanProgramming/OpenKyrozen/issues/232) |
| R239 ToolExecutor | `agent`: `executor`, `types.ExecutionReceipt` | Owns authorized invocation and receipts. Uses registry definitions, security decisions and bound tool implementations; denied or failed calls cannot become successful effects. Does not own permission policy or plan transitions. | [#233](https://github.com/EvanProgramming/OpenKyrozen/issues/233), [#236](https://github.com/EvanProgramming/OpenKyrozen/issues/236) |
| R240 SecurityPolicy | `security`: `capabilities`, `tool_policy`, `permissions`, `permission_gate` | Owns capability and approval authorization. Effective permissions stay within configured, session and delegated bounds; model output, routing advice and catalog entries cannot approve a call. The executor enforces the decision. | [#261](https://github.com/EvanProgramming/OpenKyrozen/issues/261) |
| R241 ProviderAdapter | `providers`: `base.LLMProvider`, provider transport modules, `factory`, `calls` | Owns native request/response translation, streaming and provider errors. Receives conversation/tool contracts; returns model results and usage. Never executes model-requested tools or mutates plans. | [#228](https://github.com/EvanProgramming/OpenKyrozen/issues/228), [#229](https://github.com/EvanProgramming/OpenKyrozen/issues/229), [#230](https://github.com/EvanProgramming/OpenKyrozen/issues/230), [#231](https://github.com/EvanProgramming/OpenKyrozen/issues/231) |
| R242 ContextManager | `agent`: `models.AgentSession`, `context`, `compaction.ContextState` | Owns active conversation representation and compaction. Uses provider token/usage information and plan snapshots; preserves call/result identity and active plans. Does not promote memories or independently change plan state. | [#247](https://github.com/EvanProgramming/OpenKyrozen/issues/247), [#248](https://github.com/EvanProgramming/OpenKyrozen/issues/248) |
| R243 Task/Plan Store | `persistence`: `tasks.TasksRepository`, `events.EventsRepository`, `store.EventStore`, `database` | Owns durable task/plan records and revision events. Implements feature-owned storage ports and atomic writes/migrations. PlanningService owns transition semantics; storage cannot infer user approval or completion from prose. | [#244](https://github.com/EvanProgramming/OpenKyrozen/issues/244), [#264](https://github.com/EvanProgramming/OpenKyrozen/issues/264) |
| R244 RoutingService | `routing`: `router`, `policy`, `models`, `choices` | Owns model/provider/reasoning/resource selection. Reads provider capabilities, complexity and resource bounds; returns a routing decision. Cannot grant capabilities, invoke tools or mark tasks complete. | [#251](https://github.com/EvanProgramming/OpenKyrozen/issues/251) |
| R245 SubagentManager | `agent`: `subagents.SubAgentManager`, `delegation`, `delegation_runtime` | Owns child orchestration, budgets, isolation and lifecycle. Uses the shared engine/executor and security bounds; child authority can only narrow parent authority. Results require evidence/review before parent acceptance. | [#254](https://github.com/EvanProgramming/OpenKyrozen/issues/254), [#258](https://github.com/EvanProgramming/OpenKyrozen/issues/258) |
| R246 MemoryService | `memory`: `service.MemoryBank`, `retrieval`, `claims`, `ports` | Owns retrieval/storage semantics and scoped claims. Uses injected SQLite/vector ports; Chroma remains derived. Retrieved content is evidence/context, never execution authority or an approved plan. | [#252](https://github.com/EvanProgramming/OpenKyrozen/issues/252) |
| R247 LearningService | `learning`: `engine.LearningEngine`, `dispatcher`, evidence/evaluation/promotion modules | Owns post-turn evidence, evaluation and promotion. Uses memory, skill and storage contracts; promotion requires evidence. Learning cannot change foreground execution authority or approve its own tool calls. | [#253](https://github.com/EvanProgramming/OpenKyrozen/issues/253) |
| R248 Jev/System One | `routing`: `system_one`, `decision_assist`, `transport`, `kev` | Advisory only: proposes routing/ranking/review choices within RoutingService. Never owns execution authority, permission approval, plan acceptance or completion. Remote/local transports stay behind injected boundaries. | [#251](https://github.com/EvanProgramming/OpenKyrozen/issues/251) |
| R249 Interfaces | `interfaces`: CLI, TUI JSONL, web REST/SSE and MCP adapters; `tui` renders the Go client | Consume/render runtime events and submit user input, approvals and cancellation. Do not implement model/tool loops, plan transitions or completion rules. Typed event migration replaces existing surface shapes through explicit adapters. | [#255](https://github.com/EvanProgramming/OpenKyrozen/issues/255), [#256](https://github.com/EvanProgramming/OpenKyrozen/issues/256) |

### Dependency direction and enforcement

`app.bootstrap` is the composition root: it constructs concrete adapters and injects
feature services, callbacks and ports. Existing method binding is retained during
migration; it is not a license to move semantic decisions into presentation code.
Interfaces call the runtime/service contracts; feature code emits events through
`agent.ports.EventSink` and requests approval through `Approval`, rather than importing
interface implementations. Concrete provider, tool, SQLite, vector and routing
transports remain behind the injected boundaries.

Permitted feature dependencies follow the responsibilities above: `agent` coordinates
`tasks`, `tools` catalog/model contracts, `security`, provider contracts, `routing`,
`memory` and `learning`; `tasks` owns its models/storage ports; `memory` owns memory
models/storage/vector ports; `learning` consumes memory, skill and storage contracts.
Shared persistence models are allowed; concrete repositories belong at composition.
`tools` uses security/contracts and adapter-specific libraries inside adapter modules;
`providers` uses provider configuration/contracts and SDKs inside transport modules;
`routing` reads provider metadata and security/resource bounds; `persistence` implements
storage without importing interfaces or coordinating agent execution. New dependencies
must preserve these authority limits and avoid import-time cycles.

`scripts/check_architecture.py` enforces the existing static import policy across
`agent`, `tasks`, `memory` and `learning`: no legacy root implementation imports, no
interface package-root or descendant imports, and no listed concrete adapters or
external adapter libraries. Absolute and relative imports are checked, including
function-local imports and concrete adapters reached through statically named import
re-exports (including aliased and chained re-exports). Existing entry adapters (`memory.vector`, `learning.worker`
and `learning.benchmark`) retain their explicit exemption from core adapter bans.
Import-time statement bodies (including branches, try/else/finally, with, loops,
match and class bodies) contribute cycle edges. Function bodies and type-only
`TYPE_CHECKING` / `typing.TYPE_CHECKING` branches do not; their runtime `else`
branches still do. `check(root=...)` accepts a temporary source root for
regressions; `check()` and the script entry point still check this repository.

This is a static import guard, not an authority proof: it does not inspect dynamic
imports, dynamically assigned exports, injected callables or every semantic
dependency listed above. Runtime safety
and ownership tests remain necessary. Each linked implementation issue must extend
contract/authority tests as it migrates behavior; this issue does not claim the whole
V3 architecture is already implemented.

## Ports and durable data

The inbound chat contract is
Expand Down
1 change: 1 addition & 0 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ This index covers the current product guides, developer references, and dated en
- [Development guide](development.md) and [contributor guide](../CONTRIBUTING.md) cover setup, layout, checks, and pull requests.
- [Reports index](reports.md) explains the dates, scope, and limits of recorded audits, validation runs, and benchmarks.
- [Modular refactor validation](modular-refactor-validation.md), [production audit](production-audit-2026-10-04.md), [shipping audit](production-shipping-audit-2026-10-04.md), and [self-learning audit](self-learning-audit-2026-10-03.md) preserve historical evidence.
- [V3 architecture ownership plan](superpowers/plans/2026-10-07-v3-issue-227.md) records the scoped implementation and verification for issue #227.
- Machine-readable audit receipts and benchmark inputs remain beside their corresponding reports under `docs/` and `docs/benchmarks/`.

The repository's [English overview](../README.md) links here. Technical guides are maintained in English; README translations provide localized entry points.
59 changes: 59 additions & 0 deletions docs/superpowers/plans/2026-10-07-v3-issue-227.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# V3 issue #227: subsystem ownership and architecture boundaries

Issue: https://github.com/EvanProgramming/OpenKyrozen/issues/227
Base: f8eeb4bb5bd0d35f315620cf597142a9962682b2 (main)
Branch: Evan/v3-227-architecture

## Contract

Complete R236–R249 by documenting one package owner, existing implementation,
permitted dependencies, and authority boundary for each subsystem. These are V3
contracts; subsequent linked issues implement the new engine, typed events,
provider contracts and plan semantics. Do not create placeholder services or
claim those later implementations are complete.

## Task 1: checker regression and fix

1. Add temporary-package unittest fixtures for absolute/relative interface root
and descendant imports, allowed imports, concrete/external adapters, legacy
imports, runtime cycles and TYPE_CHECKING exclusions.
2. Demonstrate the interface-root bypass against the unchanged checker.
3. Add `check(root: Path = ROOT)` and use root-relative scanning/diagnostics.
4. Reject the exact interface namespace and descendants in the existing shared
guard. Keep existing check() callers and adapter/cycle rules working.
5. Run focused checker tests on Python 3.12 and 3.13 and the real package check.

## Task 2: ownership contract

Extend docs/architecture.md with all fourteen requirement IDs, package owners,
existing component pointers, implementation issue links and authority limits.
Document composition/injection, core-to-adapter rules and the limits of static
import checking. Preserve the distinction between current V2 behavior and V3
contracts, including mutable Working Plans and approved Strategic Plans.

## Task 3: verification and delivery

Run focused architecture tests, make test, make check, make lint and make
docs-check using the supported dependency-equipped Python 3.12 environment.
Run checker fixtures with Python 3.13 as well. Capture failures and determine
whether they predate this diff; blocked validation is not a pass.
Obtain a fresh independent review of the whole diff and resolve material
findings. Commit only scoped files with GPG signing and verify the signature.
Push the issue branch, create and attach one PR with coverage/evidence and
compatibility/security notes. Check CI. Stop; do not merge or start another issue.

## Review focus

Absolute and relative import resolution, package __init__ cases, default callers,
fixture isolation, retained cycle/legacy/adapter checks, accurate current-versus-
planned ownership, all R236–R249 covered. No paid provider calls or runtime data.

## Review follow-up: PR #269

Reproduce and fix all three verified Codex findings: qualified type-checking
guards, missing import-time compound bodies, and concrete named adapter re-exports.
Preserve runtime else branches, deferred function bodies and allowed contract
re-exports. Test aliased/chained re-exports and cycle termination without executing
application modules. Run fixtures on both supported Python versions and the full
browser suite/checks, obtain independent review, then push a signed follow-up
commit and resolve the three original review threads with evidence. Do not merge.
Loading
Loading