fix: enforce V3 architecture ownership boundaries

[EvanProgramming]

Closes #227.

Core modules could import the openkyrozen.interfaces package root without failing the architecture check. Reject the root and its descendants for absolute, relative, aliased and function-local imports, while retaining existing adapter, legacy-import and cycle checks. Accept a fixture source root and handle imports in the top-level package initializer without crashing.

Document one owner, existing components, permitted dependencies and authority boundaries for all fourteen requirements R236–R249. The ownership contract links the later V3 implementations and distinguishes them from current V2 behavior; it adds no placeholder services or runtime migrations.

Validation

• Python 3.12: make test — all 523 tests passed, including real browser integrations, in isolated temporary state.
• Python 3.12 and 3.13: all 13 checker fixture tests passed.
• make check (including Go tests), make lint, make docs-check, and git diff --check passed.
• Fresh independent review of the follow-up found no remaining Critical, Important or Minor findings.
• Both commits are GPG signed and verified locally and by GitHub. Latest-head Python 3.12 core, Python 3.13 full-suite/agent-acceptance, and build CI passed.

Review fixes

All three Codex findings were reproduced before changes and fixed in the shared checker:

• Recognize typing.TYPE_CHECKING while preserving runtime else imports.
• Traverse import-time compound bodies (try/else/finally, with, loops, match, classes), excluding deferred function bodies.
• Trace concrete named re-exports, aliased modules and re-export chains; honor literal __all__ for wildcard imports and terminate circular origin traversal. Allowed contract re-exports remain valid.

Regressions caught 14 failures for the original findings, then two additional alias/__all__ edge cases identified by independent review; all now pass. No paid provider calls were used.

Compatibility and security

Existing check() and script callers retain the repository default. The change strengthens static dependency enforcement; provider/tool execution, configuration, storage and credentials are unchanged. Static import checking does not prove semantic authority or cover dynamic imports; those contracts remain assigned to the linked implementation issues. No paid provider calls were used.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 3f22836c-e545-4530-870a-7addb16dbb5d

📥 Commits

Reviewing files that changed from the base of the PR and between 5d2c491 and 506d8c4.

📒 Files selected for processing (4)

• docs/architecture.md
• docs/superpowers/plans/2026-10-07-v3-issue-227.md
• scripts/check_architecture.py
• tests/test_architecture_checker.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The architecture checker now accepts a configurable package root and analyzes imports, re-exports, and import-time cycles. Documentation maps V3 subsystem ownership and dependency boundaries, distinguishes planned capabilities from current behavior, and links the issue plan.

Changes

Architecture boundaries

Layer / File(s)	Summary
Checker behavior and regression coverage scripts/check_architecture.py, tests/test_architecture_checker.py	The checker scans the supplied root, reports root-relative paths, and resolves import targets and re-export origins for policy and cycle checks. Temporary-package tests cover import rules, allowed dependencies, type-checking branches, compound statements, and re-exports.
V3 ownership and dependency guidance docs/architecture.md, docs/superpowers/plans/2026-10-07-v3-issue-227.md, docs/index.md	The architecture documentation assigns owners and authority boundaries for R236–R249 and describes dependency rules and checker limits. The plan records implementation, verification, and delivery requirements. The index links to the plan.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 506d8

No concrete issue requiring a fix before merge was established.

Security Architecture Review

Security architecture risk: ⚪ Minimal · up to 506d8

The checker strengthens import-boundary enforcement without executing the source it analyzes. The ownership documentation explicitly separates future behavior from current capabilities. No material security risk introduced or worsened by this PR was identified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The changed executable scope is local source analysis under the invoking process's filesystem permissions. Contributor-controlled source becomes parser input rather than tool-execution authority. The fixture caller uses a temporary directory, and the inspected production acceptance and delegation name matches do not establish a call into the checker.

Trust Boundaries and Controls

• observed — Core adapter restrictions apply to imports throughout the AST, including function-local imports; cycle detection separately excludes deferred bodies and recognized type-only branches. Static analysis is explicitly not an authorization proof and does not cover dynamic imports, dynamically assigned exports, or injected callables.

Resilience and Maintainability Implications

• observed — Re-export traversal stops repeated module/name bindings, and dependency traversal tracks visiting and completed modules to report cycles. Analysis state is local to each call, with no persisted transition to recover or roll back. The CLI converts detected violations into failure rather than reporting success.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.79% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 2 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Issue #227 requires an ownership contract and enforced package boundaries. docs/architecture.md maps one owner, existing components, authority limits, and later implementation links for R236–R249. I…
Out of Scope Changes check	✅ Passed	The documentation records the ownership contract and verification scope for issue #227. The checker changes and regression tests enforce the requested architecture boundaries. The temporary-root optio…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: enforcing V3 architecture ownership boundaries through checker updates and related documentation.

Full details: Docstring Coverage

Explanation

Docstring coverage is 15.79% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 2 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-07T13:27:04.057443Z	5d2c491	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5d2c49142b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".