UAT: ADR-001 Compliance Gap — No automated import-linter or architecture test enforcement in CI pipeline #4056

New issue

Open

opened 2026-04-06 09:40:44 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 09:40:44 +00:00

Owner

Metadata

Branch: feat/adr-001-import-linter-enforcement
Commit Message: feat(ci): add import-linter architecture enforcement for ADR-001 compliance
Milestone: (none — see backlog note below)
Parent Epic: #2810

Bug Report

What was tested: ADR-001 (Layered Architecture) compliance enforcement mechanisms

Expected behavior (from ADR-001 Compliance section):
ADR-001 explicitly states:

"Import linting: CI rules enforce that domain modules never import from infrastructure or presentation. Ruff custom rules or import-linter configuration checks are run on every commit."
"Architecture tests: Dedicated test suite verifying layer dependency rules using static analysis (e.g., import-linter or custom AST checks)."

Actual behavior:
There is NO automated enforcement of layer dependency rules in the CI pipeline:

No import-linter configuration — No .importlinter file exists in the repository
No import-linter dependency — import-linter is not listed in pyproject.toml dev dependencies
No architecture test suite — No dedicated test files verify layer dependency rules
The existing ADR compliance script is inadequate — scripts/check-adr-compliance.py only checks ADR-002 (Asyncio) and ADR-007 (Repository Pattern) — neither of which are real ADR numbers in this project (ADR-002 is the Namespace System, ADR-007 is Decision Tree). The script does NOT check the critical ADR-001 layer boundary rules.
No Ruff custom rules — The pyproject.toml Ruff configuration does not include any custom rules for layer boundary enforcement

Evidence of the gap:
Because there is no enforcement, actual violations exist in the codebase:

CLI layer imports directly from Infrastructure layer (7 violation sites found)
Application layer services import SQLAlchemy directly (4 violation sites found)
These violations would have been caught immediately if import-linter were configured

Steps to reproduce:

# Verify no import-linter config exists
ls .importlinter 2>/dev/null || echo "No .importlinter file"

# Verify no import-linter in dependencies
grep "import-linter" pyproject.toml || echo "Not in dependencies"

# Verify the compliance script checks wrong ADRs
cat scripts/check-adr-compliance.py | grep "ADR-00"
# Shows ADR-002 and ADR-007 — neither match actual ADR numbers in docs/adr/

Impact:

Layer boundary violations accumulate silently without automated detection
The architecture degrades over time as developers unknowingly bypass the hexagonal architecture
The ADR-001 compliance guarantee is a false promise — it states CI enforcement exists but it does not

Proposed Fix:

Add import-linter to dev dependencies in pyproject.toml

Create .importlinter configuration file with contracts:

[importlinter]
root_package = cleveragents

[importlinter:contract:domain-independence]
name = Domain layer must not import from infrastructure or presentation
type = forbidden
source_modules = cleveragents.domain
forbidden_modules = cleveragents.infrastructure | cleveragents.cli | cleveragents.tui

[importlinter:contract:presentation-no-infrastructure]
name = Presentation layer must not import from infrastructure
type = forbidden
source_modules = cleveragents.cli | cleveragents.tui
forbidden_modules = cleveragents.infrastructure

Add nox -e architecture_check session that runs lint-imports
Include architecture check in the default nox sessions
Fix the existing scripts/check-adr-compliance.py to reference correct ADR numbers and check actual ADR-001 layer rules

Subtasks

Add import-linter to dev dependencies in pyproject.toml
Create .importlinter configuration with layer boundary contracts
Add architecture_check nox session that runs lint-imports
Fix scripts/check-adr-compliance.py to check correct ADR numbers and actual ADR-001 rules
Add architecture check to default nox sessions (or at minimum to CI pipeline)
Fix existing layer violations before enabling enforcement (see related issues)
Tests (Behave): Add scenarios verifying architecture enforcement runs correctly
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
nox -e architecture_check runs lint-imports and passes
Layer boundary violations are caught automatically on every commit
scripts/check-adr-compliance.py references correct ADR numbers and checks ADR-001 layer rules
CI pipeline includes architecture enforcement step
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.7.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `feat/adr-001-import-linter-enforcement` - **Commit Message**: `feat(ci): add import-linter architecture enforcement for ADR-001 compliance` - **Milestone**: *(none — see backlog note below)* - **Parent Epic**: #2810 ## Bug Report **What was tested:** ADR-001 (Layered Architecture) compliance enforcement mechanisms **Expected behavior (from ADR-001 Compliance section):** ADR-001 explicitly states: > "**Import linting**: CI rules enforce that `domain` modules never import from `infrastructure` or `presentation`. Ruff custom rules or import-linter configuration checks are run on every commit." > "**Architecture tests**: Dedicated test suite verifying layer dependency rules using static analysis (e.g., `import-linter` or custom AST checks)." **Actual behavior:** There is NO automated enforcement of layer dependency rules in the CI pipeline: 1. **No `import-linter` configuration** — No `.importlinter` file exists in the repository 2. **No `import-linter` dependency** — `import-linter` is not listed in `pyproject.toml` dev dependencies 3. **No architecture test suite** — No dedicated test files verify layer dependency rules 4. **The existing ADR compliance script is inadequate** — `scripts/check-adr-compliance.py` only checks ADR-002 (Asyncio) and ADR-007 (Repository Pattern) — neither of which are real ADR numbers in this project (ADR-002 is the Namespace System, ADR-007 is Decision Tree). The script does NOT check the critical ADR-001 layer boundary rules. 5. **No Ruff custom rules** — The `pyproject.toml` Ruff configuration does not include any custom rules for layer boundary enforcement **Evidence of the gap:** Because there is no enforcement, actual violations exist in the codebase: - CLI layer imports directly from Infrastructure layer (7 violation sites found) - Application layer services import SQLAlchemy directly (4 violation sites found) - These violations would have been caught immediately if import-linter were configured **Steps to reproduce:** ```bash # Verify no import-linter config exists ls .importlinter 2>/dev/null || echo "No .importlinter file" # Verify no import-linter in dependencies grep "import-linter" pyproject.toml || echo "Not in dependencies" # Verify the compliance script checks wrong ADRs cat scripts/check-adr-compliance.py | grep "ADR-00" # Shows ADR-002 and ADR-007 — neither match actual ADR numbers in docs/adr/ ``` **Impact:** - Layer boundary violations accumulate silently without automated detection - The architecture degrades over time as developers unknowingly bypass the hexagonal architecture - The ADR-001 compliance guarantee is a false promise — it states CI enforcement exists but it does not **Proposed Fix:** 1. Add `import-linter` to dev dependencies in `pyproject.toml` 2. Create `.importlinter` configuration file with contracts: ```ini [importlinter] root_package = cleveragents [importlinter:contract:domain-independence] name = Domain layer must not import from infrastructure or presentation type = forbidden source_modules = cleveragents.domain forbidden_modules = cleveragents.infrastructure | cleveragents.cli | cleveragents.tui [importlinter:contract:presentation-no-infrastructure] name = Presentation layer must not import from infrastructure type = forbidden source_modules = cleveragents.cli | cleveragents.tui forbidden_modules = cleveragents.infrastructure ``` 3. Add `nox -e architecture_check` session that runs `lint-imports` 4. Include architecture check in the default nox sessions 5. Fix the existing `scripts/check-adr-compliance.py` to reference correct ADR numbers and check actual ADR-001 layer rules ## Subtasks - [ ] Add `import-linter` to dev dependencies in `pyproject.toml` - [ ] Create `.importlinter` configuration with layer boundary contracts - [ ] Add `architecture_check` nox session that runs `lint-imports` - [ ] Fix `scripts/check-adr-compliance.py` to check correct ADR numbers and actual ADR-001 rules - [ ] Add architecture check to default nox sessions (or at minimum to CI pipeline) - [ ] Fix existing layer violations before enabling enforcement (see related issues) - [ ] Tests (Behave): Add scenarios verifying architecture enforcement runs correctly - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - `nox -e architecture_check` runs `lint-imports` and passes - Layer boundary violations are caught automatically on every commit - `scripts/check-adr-compliance.py` references correct ADR numbers and checks ADR-001 layer rules - CI pipeline includes architecture enforcement step - All nox stages pass - Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added the

labels

2026-04-06 09:41:03 +00:00

freemo added a new dependency

2026-04-06 09:41:05 +00:00

#2810 Epic: CI Quality Gates Restoration — Restore All 11 CI Jobs to Passing on Master