Skip to content

docs: add architecture audit with scored assessment and refactoring roadmap#2445

Open
SatoryKono wants to merge 1 commit intomainfrom
codex/conduct-architectural-code-review-and-refactoring-plan-7d6htn
Open

docs: add architecture audit with scored assessment and refactoring roadmap#2445
SatoryKono wants to merge 1 commit intomainfrom
codex/conduct-architectural-code-review-and-refactoring-plan-7d6htn

Conversation

@SatoryKono
Copy link
Owner

Motivation

  • Provide a reproducible baseline architecture audit covering src/bioetl, tests/architecture and active documentation, so future changes can be measured against a concrete scorecard.
  • Surface high‑risk areas and an actionable, prioritized refactoring roadmap to reduce technical debt and improve maintainability.

Description

  • Add a new audit document docs/99-archive/reports/architecture-audit-2026-03-03/00-audit-baseline.md containing an executive summary, verification log, a 10‑category weighted scorecard and an integrated project score.
  • Documented findings using RFC‑2119 severity levels (Critical/Moderate/Informational) and provided concrete recommendations (RF-001..RF-006) with module‑level actions, risks, mitigations and done‑criteria.
  • Included suggested KPIs and tests to monitor architecture drift and an expected score uplift model after implementing key refactors.

Testing

  • Ran the full architecture suite with uv run python -m pytest tests/architecture/ -q, which is mostly green but reports 1 failing test tests/architecture/test_documentation_sync.py::test_no_legacy_kebab_pipeline_ids_in_active_docs due to docs/exports/full-documentation-no-plans-reports-skills.merged.md.
  • Ran focused suites uv run python -m pytest tests/architecture/test_layer_dependencies.py tests/architecture/test_di_compliance.py tests/architecture/test_naming_conventions.py tests/architecture/test_medallion_invariants.py -q and uv run python -m pytest tests/architecture/test_code_metrics.py -q, all of which passed.
  • Pre-commit checks surfaced unrelated baseline issues (missing pip-audit executable, markdown formatting adjustment and VCR filename policy violations) which do not block the audit content but should be addressed separately.

Codex Task

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant