UAT: ADR compliance script references non-existent ADR-002 and ADR-007 — checks wrong architectural decisions #4057

New issue

Open

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

freemo commented

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

Owner

Bug Report

What was tested: The scripts/check-adr-compliance.py script and its nox -e adr_compliance session

Expected behavior:
The ADR compliance script should verify compliance with the actual ADRs documented in docs/adr/. The script should reference real ADR numbers and check the rules those ADRs define.

Actual behavior:
The script scripts/check-adr-compliance.py references ADR-002 and ADR-007 in its docstring and function names, but these ADR numbers do NOT correspond to the actual ADRs in the project:

ADR-002 in the script is described as "Asyncio Concurrency Model" — but the actual docs/adr/ADR-002-namespace-system.md is the Namespace System. There is no "Asyncio Concurrency Model" ADR.
ADR-007 in the script is described as "Repository Pattern for Persistence" — but the actual docs/adr/ADR-007-decision-tree-and-correction.md is the Decision Tree and Correction ADR. There is no "Repository Pattern" ADR.

The script is checking rules for ADRs that don't exist, while the actual ADRs (ADR-001 Layered Architecture, ADR-003 Dependency Injection, ADR-004 Data Validation, ADR-025 Observability) are not checked at all.

Evidence:

# From scripts/check-adr-compliance.py:
"""
ADR-002: Asyncio Concurrency Model
  - Async functions should use 'async def', not threading
  ...
ADR-007: Repository Pattern for Persistence
  - Database access only through repository classes
  ...
"""

# But actual docs/adr/ADR-002-namespace-system.md is:
# title: Namespace System

# And actual docs/adr/ADR-007-decision-tree-and-correction.md is:
# title: Decision Tree and Correction

Steps to reproduce:

# Check what ADR-002 actually is
head -5 docs/adr/ADR-002-namespace-system.md
# title: Namespace System

# Check what ADR-007 actually is
head -5 docs/adr/ADR-007-decision-tree-and-correction.md
# title: Decision Tree and Correction

# Run the compliance script
python scripts/check-adr-compliance.py
# It "passes" but is checking the wrong things

Impact:

The nox -e adr_compliance session gives false confidence — it passes but is not checking any real ADR rules
The actual critical ADRs (ADR-001 layer boundaries, ADR-003 DI patterns, ADR-004 validation, ADR-025 logging) are not verified
Developers and CI see "ADR compliance checks passed" but the real ADRs are not being enforced

Fix:
Rewrite scripts/check-adr-compliance.py to check the actual ADRs:

ADR-001 (Layered Architecture): Check that domain modules don't import from infrastructure/presentation; check that CLI doesn't import from infrastructure
ADR-003 (Dependency Injection): Check that domain modules don't import dependency_injector
ADR-004 (Data Validation): Check that data crossing layer boundaries uses Pydantic models
ADR-025 (Observability): Check that modules use structlog not stdlib logging

Metadata

Branch: fix/adr-compliance-script-wrong-adrs
Commit Message: fix(ci): correct ADR compliance script to check actual ADR numbers and rules
Milestone: Backlog
Parent Epic: #2810

Subtasks

Remove references to non-existent ADR-002 (Asyncio) and ADR-007 (Repository Pattern)
Add ADR-001 layer boundary checks (domain ↛ infrastructure, CLI ↛ infrastructure)
Add ADR-003 check (domain modules must not import dependency_injector)
Add ADR-025 check (modules must use structlog, not stdlib logging)
Update nox session docstring to reflect actual checks
Verify script passes after fixing the underlying violations

Definition of Done

scripts/check-adr-compliance.py references only real ADR numbers from docs/adr/
Script checks rules that match the actual ADR content
nox -e adr_compliance catches real violations when they exist
Script passes only when actual ADR rules are followed
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.5.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

## Bug Report **What was tested:** The `scripts/check-adr-compliance.py` script and its `nox -e adr_compliance` session **Expected behavior:** The ADR compliance script should verify compliance with the actual ADRs documented in `docs/adr/`. The script should reference real ADR numbers and check the rules those ADRs define. **Actual behavior:** The script `scripts/check-adr-compliance.py` references **ADR-002** and **ADR-007** in its docstring and function names, but these ADR numbers do NOT correspond to the actual ADRs in the project: - **ADR-002** in the script is described as "Asyncio Concurrency Model" — but the actual `docs/adr/ADR-002-namespace-system.md` is the **Namespace System**. There is no "Asyncio Concurrency Model" ADR. - **ADR-007** in the script is described as "Repository Pattern for Persistence" — but the actual `docs/adr/ADR-007-decision-tree-and-correction.md` is the **Decision Tree and Correction** ADR. There is no "Repository Pattern" ADR. The script is checking rules for ADRs that don't exist, while the actual ADRs (ADR-001 Layered Architecture, ADR-003 Dependency Injection, ADR-004 Data Validation, ADR-025 Observability) are not checked at all. **Evidence:** ```python # From scripts/check-adr-compliance.py: """ ADR-002: Asyncio Concurrency Model - Async functions should use 'async def', not threading ... ADR-007: Repository Pattern for Persistence - Database access only through repository classes ... """ # But actual docs/adr/ADR-002-namespace-system.md is: # title: Namespace System # And actual docs/adr/ADR-007-decision-tree-and-correction.md is: # title: Decision Tree and Correction ``` **Steps to reproduce:** ```bash # Check what ADR-002 actually is head -5 docs/adr/ADR-002-namespace-system.md # title: Namespace System # Check what ADR-007 actually is head -5 docs/adr/ADR-007-decision-tree-and-correction.md # title: Decision Tree and Correction # Run the compliance script python scripts/check-adr-compliance.py # It "passes" but is checking the wrong things ``` **Impact:** - The `nox -e adr_compliance` session gives false confidence — it passes but is not checking any real ADR rules - The actual critical ADRs (ADR-001 layer boundaries, ADR-003 DI patterns, ADR-004 validation, ADR-025 logging) are not verified - Developers and CI see "ADR compliance checks passed" but the real ADRs are not being enforced **Fix:** Rewrite `scripts/check-adr-compliance.py` to check the actual ADRs: 1. **ADR-001 (Layered Architecture)**: Check that domain modules don't import from infrastructure/presentation; check that CLI doesn't import from infrastructure 2. **ADR-003 (Dependency Injection)**: Check that domain modules don't import `dependency_injector` 3. **ADR-004 (Data Validation)**: Check that data crossing layer boundaries uses Pydantic models 4. **ADR-025 (Observability)**: Check that modules use `structlog` not stdlib `logging` --- ## Metadata - **Branch**: `fix/adr-compliance-script-wrong-adrs` - **Commit Message**: `fix(ci): correct ADR compliance script to check actual ADR numbers and rules` - **Milestone**: Backlog - **Parent Epic**: #2810 ## Subtasks - [ ] Remove references to non-existent ADR-002 (Asyncio) and ADR-007 (Repository Pattern) - [ ] Add ADR-001 layer boundary checks (domain ↛ infrastructure, CLI ↛ infrastructure) - [ ] Add ADR-003 check (domain modules must not import dependency_injector) - [ ] Add ADR-025 check (modules must use structlog, not stdlib logging) - [ ] Update nox session docstring to reflect actual checks - [ ] Verify script passes after fixing the underlying violations ## Definition of Done - [ ] `scripts/check-adr-compliance.py` references only real ADR numbers from `docs/adr/` - [ ] Script checks rules that match the actual ADR content - [ ] `nox -e adr_compliance` catches real violations when they exist - [ ] Script passes only when actual ADR rules are followed - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.5.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 a new dependency

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

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

freemo added the

Points

label

2026-04-06 09:43:08 +00:00

freemo referenced this issue

2026-04-06 09:46:12 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

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