[AUTO-ARCH] Status: Architecture Report (Cycle 1) #8075

New issue

Closed

opened 2026-04-13 03:24:16 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-13 03:24:16 +00:00

Owner

[AUTO-ARCH] Architecture Supervisor — Cycle 1 Status

Date: Mon Apr 13, 2026
Model: anthropic/claude-sonnet-4-6
Session Tag: [AUTO-ARCH]

🏛️ Architecture Overview

The CleverAgents platform follows Clean Architecture with strict layer boundaries. This cycle focuses on documenting the four known architecture violations as ADRs so that implementers have authoritative guidance for remediation.

📋 Known Violations Reviewed

Issue	Title	Severity	ADR Planned
#8058	Resource handlers import infrastructure directly	🔴 High (Clean Arch violation)	ADR-049
#8059	plan_id type mismatch between lifecycle and context services	🔴 High (data integrity risk)	ADR-050
#8061	PlanLifecycleService is 2,600+ lines (violates 500-line limit)	🟡 Medium (maintainability)	ADR-051
#8063	ResourceHandler protocol diverges from spec	🔴 High (spec-first violation)	ADR-052

📝 ADRs Created This Cycle

ADR	Title	Status	Change Type
ADR-049	SandboxGateway: Domain-Layer Sandbox Abstraction	Proposed	Major — new interface
ADR-050	Plan Identifier Canonicalization (ULID-first)	Proposed	Major — cross-service contract
ADR-051	PlanLifecycleService Decomposition	Proposed	Major — structural refactor
ADR-052	ResourceHandler Protocol Reconciliation	Proposed	Major — spec/code alignment

All four ADRs are major changes requiring human review and approval before implementation.

🔍 Architectural Decisions Made

SandboxGateway pattern — Domain layer must depend on a SandboxGateway protocol, not SandboxManager directly. Infrastructure provides the concrete implementation, wired via DI.
ULID-first plan IDs — All services must accept ULID strings as plan identifiers. Integer DB surrogate IDs are an infrastructure concern only.
Phase-based service decomposition — PlanLifecycleService should be split into ActionService, StrategizeService, ExecuteService, ApplyService, plus shared PlanValidationService and PlanEventService.
Spec-authoritative handler protocol — The ResourceHandler protocol in code must match the specification. The spec's sandbox-parameter design is preferred; the current BoundResource approach should be evaluated and either adopted into spec or reverted.

⏭️ Next Cycle Actions

Monitor PR reviews for ADR-049 through ADR-052
Check for new spec ambiguities from implementers
Verify no new architecture violations have been introduced
Update tracking issue with ADR acceptance status

Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architecture-pool-supervisor

## [AUTO-ARCH] Architecture Supervisor — Cycle 1 Status **Date:** Mon Apr 13, 2026 **Model:** anthropic/claude-sonnet-4-6 **Session Tag:** [AUTO-ARCH] --- ## 🏛️ Architecture Overview The CleverAgents platform follows Clean Architecture with strict layer boundaries. This cycle focuses on documenting the four known architecture violations as ADRs so that implementers have authoritative guidance for remediation. --- ## 📋 Known Violations Reviewed | Issue | Title | Severity | ADR Planned | |-------|-------|----------|-------------| | #8058 | Resource handlers import infrastructure directly | 🔴 High (Clean Arch violation) | ADR-049 | | #8059 | plan_id type mismatch between lifecycle and context services | 🔴 High (data integrity risk) | ADR-050 | | #8061 | PlanLifecycleService is 2,600+ lines (violates 500-line limit) | 🟡 Medium (maintainability) | ADR-051 | | #8063 | ResourceHandler protocol diverges from spec | 🔴 High (spec-first violation) | ADR-052 | --- ## 📝 ADRs Created This Cycle | ADR | Title | Status | Change Type | |-----|-------|--------|-------------| | ADR-049 | SandboxGateway: Domain-Layer Sandbox Abstraction | Proposed | Major — new interface | | ADR-050 | Plan Identifier Canonicalization (ULID-first) | Proposed | Major — cross-service contract | | ADR-051 | PlanLifecycleService Decomposition | Proposed | Major — structural refactor | | ADR-052 | ResourceHandler Protocol Reconciliation | Proposed | Major — spec/code alignment | All four ADRs are **major changes** requiring human review and approval before implementation. --- ## 🔍 Architectural Decisions Made 1. **SandboxGateway pattern** — Domain layer must depend on a `SandboxGateway` protocol, not `SandboxManager` directly. Infrastructure provides the concrete implementation, wired via DI. 2. **ULID-first plan IDs** — All services must accept ULID strings as plan identifiers. Integer DB surrogate IDs are an infrastructure concern only. 3. **Phase-based service decomposition** — `PlanLifecycleService` should be split into `ActionService`, `StrategizeService`, `ExecuteService`, `ApplyService`, plus shared `PlanValidationService` and `PlanEventService`. 4. **Spec-authoritative handler protocol** — The `ResourceHandler` protocol in code must match the specification. The spec's `sandbox`-parameter design is preferred; the current `BoundResource` approach should be evaluated and either adopted into spec or reverted. --- ## ⏭️ Next Cycle Actions - Monitor PR reviews for ADR-049 through ADR-052 - Check for new spec ambiguities from implementers - Verify no new architecture violations have been introduced - Update tracking issue with ADR acceptance status --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architecture-pool-supervisor

HAL9000 commented

2026-04-13 03:40:24 +00:00

Author

Owner

Cycle 1 Update — Worker [AUTO-ARCH-1] Complete

Time: 2026-04-13T03:40 UTC

✅ Worker Completed

Worker [AUTO-ARCH-1] has successfully:

Created branch auto-arch-1/adr-049-052-violations
Written all four ADR files to docs/adr/
Committed and pushed the branch
Opened PR #8122: #8122

📄 ADRs Written

ADR	File	Status
ADR-049	`docs/adr/ADR-049-sandbox-gateway-domain-abstraction.md`	Proposed
ADR-050	`docs/adr/ADR-050-plan-identifier-canonicalization.md`	Proposed
ADR-051	`docs/adr/ADR-051-plan-lifecycle-service-decomposition.md`	Proposed
ADR-052	`docs/adr/ADR-052-lifecycle-coverage-step-integrity.md`	Proposed

⚠️ Label Note

The needs feedback label does not exist in the repository. A comment has been added to PR #8122 requesting the team create and apply it. The PR should not be merged until all four ADRs have been reviewed and voted on.

⏭️ Next Cycle (in ~30 minutes)

Check PR #8122 for review comments
Scan for new architecture violations or spec ambiguities
Update ADR status if any votes have been cast

Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architecture-pool-supervisor

## Cycle 1 Update — Worker [AUTO-ARCH-1] Complete **Time:** 2026-04-13T03:40 UTC ### ✅ Worker Completed Worker [AUTO-ARCH-1] has successfully: 1. Created branch `auto-arch-1/adr-049-052-violations` 2. Written all four ADR files to `docs/adr/` 3. Committed and pushed the branch 4. Opened PR #8122: https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/8122 ### 📄 ADRs Written | ADR | File | Status | |-----|------|--------| | ADR-049 | `docs/adr/ADR-049-sandbox-gateway-domain-abstraction.md` | Proposed | | ADR-050 | `docs/adr/ADR-050-plan-identifier-canonicalization.md` | Proposed | | ADR-051 | `docs/adr/ADR-051-plan-lifecycle-service-decomposition.md` | Proposed | | ADR-052 | `docs/adr/ADR-052-lifecycle-coverage-step-integrity.md` | Proposed | ### ⚠️ Label Note The `needs feedback` label does not exist in the repository. A comment has been added to PR #8122 requesting the team create and apply it. The PR should not be merged until all four ADRs have been reviewed and voted on. ### ⏭️ Next Cycle (in ~30 minutes) - Check PR #8122 for review comments - Scan for new architecture violations or spec ambiguities - Update ADR status if any votes have been cast --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architecture-pool-supervisor