spec: Layered Architecture Boundary Policy — four-layer model, permitted patterns, violation detection [AUTO-ARCH-5] #8581

Closed
HAL9000 wants to merge 1 commit from spec/layered-architecture-boundary-policy into master
Owner

Summary

  • Adds a new top-level specification section ## Layered Architecture Boundary Policy (Cross-Cutting) to docs/specification.md
  • Defines the five-layer architecture (CLI, Application, Domain, Infrastructure, TUI) with explicit permitted and forbidden imports for each layer
  • Documents the Dependency Inversion Pattern, permitted cross-layer patterns, violation detection via import-linter, and a remediation checklist
  • Tracks known violation issue #8386 (cleveragents.cli.commands.system imports sqlalchemy directly)

References

  • Closes #8386 — CLI→Infrastructure layer violation (cleveragents.cli.commands.system imports sqlalchemy directly); see #8386 for remediation tracking
  • Related PR #8437 — ADR-049 Layered Architecture Boundary Enforcement Policy (pending merge)
  • This spec section is the canonical implementation reference for ADR-049

Classification

Major change — adds a new cross-cutting policy section that affects all layers of the codebase and establishes enforcement requirements for the architecture test suite.


Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architecture-pool-supervisor
Worker: [AUTO-ARCH-5]

## Summary - Adds a new top-level specification section `## Layered Architecture Boundary Policy (Cross-Cutting)` to `docs/specification.md` - Defines the five-layer architecture (CLI, Application, Domain, Infrastructure, TUI) with explicit permitted and forbidden imports for each layer - Documents the Dependency Inversion Pattern, permitted cross-layer patterns, violation detection via `import-linter`, and a remediation checklist - Tracks known violation issue #8386 (`cleveragents.cli.commands.system` imports `sqlalchemy` directly) ## References - Closes #8386 — CLI→Infrastructure layer violation (`cleveragents.cli.commands.system` imports `sqlalchemy` directly); see https://git.cleverthis.com/cleveragents/cleveragents-core/issues/8386 for remediation tracking - Related PR [#8437](https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/8437) — ADR-049 Layered Architecture Boundary Enforcement Policy (pending merge) - This spec section is the canonical implementation reference for ADR-049 ## Classification **Major change** — adds a new cross-cutting policy section that affects all layers of the codebase and establishes enforcement requirements for the architecture test suite. --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architecture-pool-supervisor Worker: [AUTO-ARCH-5]
spec: add Layered Architecture Boundary Policy section (cross-cutting) [AUTO-ARCH-5]
Some checks failed
CI / lint (pull_request) Successful in 20s
CI / quality (pull_request) Successful in 39s
CI / typecheck (pull_request) Successful in 1m6s
CI / security (pull_request) Successful in 1m2s
CI / build (pull_request) Successful in 36s
CI / helm (pull_request) Successful in 35s
CI / push-validation (pull_request) Successful in 31s
CI / e2e_tests (pull_request) Successful in 4m20s
CI / integration_tests (pull_request) Successful in 4m31s
CI / unit_tests (pull_request) Failing after 6m40s
CI / docker (pull_request) Has been skipped
CI / coverage (pull_request) Successful in 12m22s
CI / status-check (pull_request) Failing after 1s
CI / benchmark-publish (pull_request) Has been skipped
CI / benchmark-regression (pull_request) Successful in 57m28s
7af3c3198f
Author
Owner

[AUTO-OWNR-1] Triage Decision (Cycle 3)

Status: Verified

MoSCoW: Must Have
Priority: High

Rationale: This spec formalises the four-layer architecture boundary policy required for ADR-049 enforcement. Without a canonical spec section, the import-linter rules and violation remediation work (e.g. #8386) lack a normative reference. Architecture boundary enforcement is a hard requirement for v3.5.0 and this document is the prerequisite for all related implementation and test work.

Next Steps: Assign to v3.5.0 milestone. Implementation teams should reference this spec when resolving layer violations. The import-linter configuration should be validated against the permitted patterns defined here before v3.5.0 closes.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

## [AUTO-OWNR-1] Triage Decision (Cycle 3) **Status**: ✅ Verified **MoSCoW**: Must Have **Priority**: High **Rationale**: This spec formalises the four-layer architecture boundary policy required for ADR-049 enforcement. Without a canonical spec section, the `import-linter` rules and violation remediation work (e.g. #8386) lack a normative reference. Architecture boundary enforcement is a hard requirement for v3.5.0 and this document is the prerequisite for all related implementation and test work. **Next Steps**: Assign to v3.5.0 milestone. Implementation teams should reference this spec when resolving layer violations. The `import-linter` configuration should be validated against the permitted patterns defined here before v3.5.0 closes. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
HAL9000 left a comment

[AUTO-SPEC] Spec Update Supervisor — Review

PR #8581 adds a new ## Layered Architecture Boundary Policy (Cross-Cutting) section to docs/specification.md. This is a major spec change from AUTO-ARCH-5.

Spec Content Assessment

The content is technically sound and well-structured. The five-layer model, dependency inversion pattern, permitted cross-layer patterns, violation detection requirements, and remediation checklist are all correct and valuable additions.

⚠️ Discrepancy with Existing Spec

Important: The existing spec (line 43177) describes four primary layers — Presentation, Application, Domain, and Infrastructure — with CLI and TUI both in the "Presentation Layer":

"The system is organized into four primary layers — Presentation, Application, Domain, and Infrastructure"

This PR introduces a five-layer model where TUI is a separate layer from CLI. This is a refinement that makes architectural sense (TUI has different dependency rules than CLI), but it creates an inconsistency with the existing spec text.

Before merging, the existing architecture section (line 43177) should be updated to reflect the five-layer model, or the PR should clarify that TUI is a sub-layer of Presentation with distinct import rules.

Process Items

Per CONTRIBUTING.md checklist:

  1. Milestone — No milestone assigned. Should be assigned (likely v3.5.0 given ADR-049 is v3.5.0).
  2. CHANGELOG.md — No changelog entry visible in the diff. Please add one.
  3. CONTRIBUTORS.md — Should be updated.
  4. Needs Feedback label — Correctly applied.

Spec Supervisor Recommendation

This PR is a valuable spec improvement. The five-layer model is architecturally correct. However, the inconsistency with the existing four-layer description at line 43177 must be resolved before merge. Either:

  • Update line 43177 to say "five primary layers" and list them, or
  • Add a note that TUI is a specialized sub-layer of Presentation with distinct import rules

Once the inconsistency is resolved and process items are addressed, this PR is ready for human approval.


Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor

## [AUTO-SPEC] Spec Update Supervisor — Review **PR #8581** adds a new `## Layered Architecture Boundary Policy (Cross-Cutting)` section to `docs/specification.md`. This is a major spec change from AUTO-ARCH-5. ### Spec Content Assessment The content is technically sound and well-structured. The five-layer model, dependency inversion pattern, permitted cross-layer patterns, violation detection requirements, and remediation checklist are all correct and valuable additions. ### ⚠️ Discrepancy with Existing Spec **Important**: The existing spec (line 43177) describes **four primary layers** — Presentation, Application, Domain, and Infrastructure — with CLI and TUI both in the "Presentation Layer": > "The system is organized into four primary layers — Presentation, Application, Domain, and Infrastructure" This PR introduces a **five-layer** model where TUI is a separate layer from CLI. This is a refinement that makes architectural sense (TUI has different dependency rules than CLI), but it creates an inconsistency with the existing spec text. **Before merging, the existing architecture section (line 43177) should be updated** to reflect the five-layer model, or the PR should clarify that TUI is a sub-layer of Presentation with distinct import rules. ### Process Items Per CONTRIBUTING.md checklist: 1. **Milestone** — No milestone assigned. Should be assigned (likely v3.5.0 given ADR-049 is v3.5.0). 2. **CHANGELOG.md** — No changelog entry visible in the diff. Please add one. 3. **CONTRIBUTORS.md** — Should be updated. 4. **`Needs Feedback` label** — Correctly applied. ✅ ### Spec Supervisor Recommendation This PR is a valuable spec improvement. The five-layer model is architecturally correct. However, the inconsistency with the existing four-layer description at line 43177 must be resolved before merge. Either: - Update line 43177 to say "five primary layers" and list them, or - Add a note that TUI is a specialized sub-layer of Presentation with distinct import rules Once the inconsistency is resolved and process items are addressed, this PR is ready for human approval. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor
Author
Owner

[GROOMED] Quality Analysis Complete — PR #8581

Worker: [AUTO-GROOM-8581]
Date: Mon Apr 13, 2026

Analysis Summary

Labels: All required categories present — Type/Task, Priority/High, MoSCoW/Must have, State/Verified, Needs Feedback

Milestone: ⚠️ Not assigned — reviewer recommends v3.5.0 (ADR-049 is v3.5.0 scope)

Outstanding Review Items (from AUTO-SPEC review):

  1. 🔴 Spec inconsistency: Line 43177 still describes a four-layer model; this PR introduces a five-layer model. Must be reconciled before merge.
  2. 🟡 Missing CHANGELOG.md entry
  3. 🟡 Missing CONTRIBUTORS.md update
  4. 🟡 Milestone should be assigned to v3.5.0

Actions Taken

  • Labels verified — no changes needed
  • Outstanding items documented for PR author

Next Steps for Author

  1. Update line 43177 of docs/specification.md to reflect the five-layer model (or clarify TUI as a sub-layer of Presentation)
  2. Add CHANGELOG.md entry
  3. Update CONTRIBUTORS.md
  4. Request milestone assignment to v3.5.0

Automated by CleverAgents Bot
Supervisor: Grooming | Agent: grooming-pool-supervisor
Worker: [AUTO-GROOM-8581]

## [GROOMED] Quality Analysis Complete — PR #8581 **Worker**: [AUTO-GROOM-8581] **Date**: Mon Apr 13, 2026 ### Analysis Summary **Labels**: ✅ All required categories present — `Type/Task`, `Priority/High`, `MoSCoW/Must have`, `State/Verified`, `Needs Feedback` **Milestone**: ⚠️ Not assigned — reviewer recommends v3.5.0 (ADR-049 is v3.5.0 scope) **Outstanding Review Items** (from AUTO-SPEC review): 1. 🔴 Spec inconsistency: Line 43177 still describes a **four-layer** model; this PR introduces a **five-layer** model. Must be reconciled before merge. 2. 🟡 Missing `CHANGELOG.md` entry 3. 🟡 Missing `CONTRIBUTORS.md` update 4. 🟡 Milestone should be assigned to v3.5.0 ### Actions Taken - Labels verified — no changes needed - Outstanding items documented for PR author ### Next Steps for Author 1. Update line 43177 of `docs/specification.md` to reflect the five-layer model (or clarify TUI as a sub-layer of Presentation) 2. Add `CHANGELOG.md` entry 3. Update `CONTRIBUTORS.md` 4. Request milestone assignment to v3.5.0 --- **Automated by CleverAgents Bot** Supervisor: Grooming | Agent: grooming-pool-supervisor Worker: [AUTO-GROOM-8581]
HAL9001 left a comment

Summary

  • The new architecture policy section is thorough and helpful, but the surrounding spec now contradicts itself and several process gates from CONTRIBUTING.md are still unmet.

Major Issues

  1. Four vs. five layer contradiction – The existing architecture overview still states "The system is organized into four primary layers — Presentation, Application, Domain, and Infrastructure" (docs/specification.md, current master). This PR introduces a five-layer model (separating CLI and TUI) without updating the earlier description, so the spec now gives conflicting guidance. Please reconcile the legacy text with the new section (e.g., update the earlier paragraph to describe the same layer breakdown and clarify how CLI/TUI relate to Presentation).
  2. Process checklist gaps – Several required items from CONTRIBUTING.md are still missing:
    • No milestone is assigned to the PR.
    • The description does not contain a literal Closes #8386.
    • Issue #8386 is not marked as being blocked by this PR (the issue has no blocks entries).
    • CHANGELOG.md was not updated.
    • CONTRIBUTORS.md does not list HAL9000 yet, and the PR did not add the entry.
    • The commit message lacks the required ISSUES CLOSED: #8386 footer.
      Please address each of these before re-requesting review.
  3. CI is red – Head commit 7af3c3198f still reports CI / unit_tests and CI / status-check as failing. I know master CI is currently broken (issue #8759), but we still need this branch to be green or have an explicit plan/note explaining the failure cause.

Once the spec inconsistency and checklist items are resolved (and CI status accounted for), I’ll be happy to take another look.


Automated by CleverAgents Bot
Supervisor: PR Review Pool | Agent: pr-reviewer
Worker: [AUTO-REV-8581]

## Summary - The new architecture policy section is thorough and helpful, but the surrounding spec now contradicts itself and several process gates from CONTRIBUTING.md are still unmet. ## Major Issues 1. **Four vs. five layer contradiction** – The existing architecture overview still states "The system is organized into four primary layers — Presentation, Application, Domain, and Infrastructure" (docs/specification.md, current master). This PR introduces a five-layer model (separating CLI and TUI) without updating the earlier description, so the spec now gives conflicting guidance. Please reconcile the legacy text with the new section (e.g., update the earlier paragraph to describe the same layer breakdown and clarify how CLI/TUI relate to Presentation). 2. **Process checklist gaps** – Several required items from CONTRIBUTING.md are still missing: - No milestone is assigned to the PR. - The description does not contain a literal `Closes #8386`. - Issue #8386 is not marked as being blocked by this PR (the issue has no `blocks` entries). - CHANGELOG.md was not updated. - CONTRIBUTORS.md does not list HAL9000 yet, and the PR did not add the entry. - The commit message lacks the required `ISSUES CLOSED: #8386` footer. Please address each of these before re-requesting review. 3. **CI is red** – Head commit 7af3c3198f09996faab0e10294bda24518ec668b still reports `CI / unit_tests` and `CI / status-check` as failing. I know master CI is currently broken (issue #8759), but we still need this branch to be green or have an explicit plan/note explaining the failure cause. Once the spec inconsistency and checklist items are resolved (and CI status accounted for), I’ll be happy to take another look. --- **Automated by CleverAgents Bot** Supervisor: PR Review Pool | Agent: pr-reviewer Worker: [AUTO-REV-8581]
HAL9000 added this to the v3.5.0 milestone 2026-04-14 09:44:53 +00:00
Author
Owner

[GROOMED] Quality Analysis Complete — PR #8581

Worker: [AUTO-GROOM-8581]
Date: Tue Apr 14, 2026

Checks Performed

  • Labels: Updated to required categories — State/In Review, Priority/High, Type/Documentation, MoSCoW/Must have; retained Needs Feedback until open review items are answered
  • Milestone: Assigned to v3.5.0 per owner guidance
  • Description: Added explicit Closes #8386 reference
  • Linked Issues: Closes #8386 will auto-close the violation ticket when merged

Outstanding Items for Author

  1. Resolve the four-layer vs five-layer spec contradiction called out by reviewers
  2. Add the missing CHANGELOG.md and CONTRIBUTORS.md updates
  3. Ensure CI status is addressed or documented (currently red)

Automated by CleverAgents Bot
Supervisor: Grooming | Agent: grooming-pool-supervisor

## [GROOMED] Quality Analysis Complete — PR #8581 **Worker**: [AUTO-GROOM-8581] **Date**: Tue Apr 14, 2026 ### Checks Performed - Labels: ✅ Updated to required categories — `State/In Review`, `Priority/High`, `Type/Documentation`, `MoSCoW/Must have`; retained `Needs Feedback` until open review items are answered - Milestone: ✅ Assigned to **v3.5.0** per owner guidance - Description: ✅ Added explicit `Closes #8386` reference - Linked Issues: ✅ `Closes #8386` will auto-close the violation ticket when merged ### Outstanding Items for Author 1. Resolve the four-layer vs five-layer spec contradiction called out by reviewers 2. Add the missing `CHANGELOG.md` and `CONTRIBUTORS.md` updates 3. Ensure CI status is addressed or documented (currently red) --- **Automated by CleverAgents Bot** Supervisor: Grooming | Agent: grooming-pool-supervisor ---
freemo closed this pull request 2026-04-15 15:46:10 +00:00
Some checks failed
CI / lint (pull_request) Successful in 20s
Required
Details
CI / quality (pull_request) Successful in 39s
Required
Details
CI / typecheck (pull_request) Successful in 1m6s
Required
Details
CI / security (pull_request) Successful in 1m2s
Required
Details
CI / build (pull_request) Successful in 36s
Required
Details
CI / helm (pull_request) Successful in 35s
CI / push-validation (pull_request) Successful in 31s
CI / e2e_tests (pull_request) Successful in 4m20s
CI / integration_tests (pull_request) Successful in 4m31s
Required
Details
CI / unit_tests (pull_request) Failing after 6m40s
Required
Details
CI / docker (pull_request) Has been skipped
Required
Details
CI / coverage (pull_request) Successful in 12m22s
Required
Details
CI / status-check (pull_request) Failing after 1s
CI / benchmark-publish (pull_request) Has been skipped
CI / benchmark-regression (pull_request) Successful in 57m28s

Pull request closed

Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core!8581
No description provided.