Skip to content

ADR-075: Architecture State Forensic Diagnostic & Baseline Acceptance

Status

Accepted

Date

2026-09-19

Context

Brownfield and evolving codebases often suffer from architectural drift—a gap between documented architectural intent (in READMEs, wikis, or historical ADRs) and actual runtime implementation.

Existing discovery mechanisms in CAS captured high-level conversational summaries and text documents, but lacked fine-grained empirical reconstruction directly from source manifests, workflow configurations, AST symbol graphs, and import dependencies.

Furthermore, automatic mutation of the validated baseline risked poisoning architectural truth with speculative or contradictory representations.

Decision

We adopt the Architecture State Forensic Diagnostic (CAS-ARCH-STATE v0.1) with the following core architectural decisions:

  1. Four-Pillar Architecture State Package: Reconstruction outputs are partitioned into a dedicated structure under knowledge/projects/<project>/architecture-state/:
  2. model/: intermediate architecture-state.yaml and partitioned YAML files (systems.yaml, containers.yaml, components.yaml, dependencies.yaml, flows.yaml, controls.yaml, evidence.yaml).
  3. views/: 5 C4-inspired Markdown views (system-context.md, containers.md, components.md, architecture-flow.md, governance-controls.md).
  4. diagrams/: Mermaid .mmd diagrams for system context and container boundaries.
  5. diagnostic/: Forensic reports (evidence-report.md, contradictions.md, unknowns.md, coverage.md).

  6. ARCHITECTURE.md: Consolidated single-file architectural digest.

  7. Zero Uninvited Root Writes: ARCHITECTURE.md is strictly contained within the knowledge layer by default; it is only mirrored to <target-dir>/ARCHITECTURE.md when the explicit --publish-root flag is supplied.

  8. Standard-Library Python AST Extraction: For Python targets, extraction utilizes Python's built-in ast module to guarantee zero heavy binary dependencies. Polyglot targets utilize regex and manifest parsers.

  9. Non-Blocking Contradiction Auditing: Discrepancies between documented intent and empirical code do not abort execution; conflicting nodes are flagged with status: contradictory and confidence: low, and cataloged in contradictions.md.

  10. Human-in-the-Loop Baseline Promotion Gate: Discovered states remain in status: discovered until an architect explicitly promotes the state via uv run cas state baseline promote --project <project>, freezing a point-in-time snapshot under knowledge/projects/<project>/baseline/.

Consequences

Positive

  • Reconstructs accurate, evidence-backed architectural views directly from code repositories.
  • Detects ghost services and shadow components without halting diagnostic pipelines.
  • Preserves governance baseline integrity through explicit human review gates.
  • Emits clean, version-controllable Markdown and Mermaid artifacts.

Negative

  • Initial v0.1 AST extraction depth is tailored to Python standard library; other languages require AST grammar additions in future iterations.