Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

A-26003: SVA Constraint Framework Design

title: SVA Constraint Framework Design date: 2026-03-02 tags:

A-26003: SVA Constraint Framework Design

Problem Statement

Smallest Viable Architecture (SVA) is the governing design principle across 14+ ADRs, three consultant prompts, and the requirements engineering glossary. Yet it has never been formally defined in its own ADR. The result: three consultant prompts define SVA constraints with incompatible numbering, ADRs reference constraint IDs that don’t match any consultant, and there is no litmus test to validate SVA compliance consistently.

Current State: Three Incompatible Constraint Sets

Constraint conceptLocal AI (C1-C4)DevOps (C1-C4)Hybrid (C1-C5)
Non-CLI/non-GitOps workflowC1C1C2
Not runnable locallyC2C2—
Vendor lock-in——C1
Unversionable artifactsC3C3C3
Unjustified orchestrationC4C4C4
Scalability limits——C5

Inconsistency Evidence in ADRs

The Missing Constraint

The changelog self-filtering plan (misc/plan/implemented/plan_20260228_changelog_self_filtering_warning.md) exposed a critical gap. The original plan proposed extending validate_commit_msg.py with 4 functions, 1 dataclass, and 13 tests to show changelog filtering warnings at commit time. This plan satisfied all existing C1-C4 constraints:

Yet it was correctly rejected during implementation because generate_changelog.py --verbose already provided the exact functionality. The plan would have duplicated filtering logic across two scripts. No existing constraint captured this violation.

Approach Evaluation

Design Methodology

Rather than reshuffling existing constraints, we derive the canonical set from established engineering principles:

  1. GitOps — declarative, version-controlled, automated infrastructure

  2. Twelve-Factor App — methodology for building SaaS (Heroku, 2011)

  3. UNIX Philosophy — do one thing well, compose via standard interfaces (McIlroy, 1978)

  4. YAGNI / XP — You Ain’t Gonna Need It (Beck, 1999)

  5. SRE Principles — operational simplicity, capacity planning (Google, 2016)

  6. ISO 29148 — requirements engineering (verifiability, traceability)

  7. DRY — Don’t Repeat Yourself (Hunt & Thomas, 1999)

  8. IEEE 1016 — software design descriptions (replaceability)

Canonical C1-C6 Framework

C1: Automation-First Operation

C2: Vendor Portability

C3: Git-Native Traceability

C4: Proportional Complexity

C5: Reuse Before Invention

C6: Bounded Scalability

Design Note: “Runnable Locally” (old local C2)

Intentionally dropped as a universal constraint. “Runs on CPU or consumer VRAM” is a deployment context specific to the local AI consultant’s scope, not a universal architectural principle. The hybrid consultant correctly omitted it. For the local AI consultant, this remains part of the P_raw scoring (local stack suitability assessment), not a penalty deduction. A cloud-first team should not be penalized for choosing cloud-native components.

Taxonomy Design

New CanonicalLocal AI (old)DevOps (old)Hybrid (old)Notes
C1: Automation-FirstC1C1C2Numbering shifted in hybrid
C2: Vendor Portability— (implicit in production_focus)— (implicit)C1Elevated from implicit to formal
C3: Git-Native TraceabilityC3C3C3Consistent across all variants
C4: Proportional ComplexityC4C4C4Broadened from “orchestration layers” to all disproportionate complexity
C5: Reuse Before Invention———New. Closes the duplicate-logic gap
C6: Bounded Scalability——C5Carried from hybrid
~~“Not runnable locally”~~C2C2—Dropped. Deployment context, not universal principle

Key Insights

The Changelog Self-Filtering Warning Pivot

Original plan: Extend validate_commit_msg.py with a ChangelogWarning dataclass, _matches_exclude_pattern(), _find_matching_pattern(), check_changelog_exclusions(), and _print_changelog_warnings() — plus 13 tests.

Actual solution: Single post-commit hook entry: bash -c 'uv run --active tools/scripts/generate_changelog.py --verbose HEAD~1..HEAD'

ConstraintOriginal PlanPost-commit Hook
C1: Automation-FirstPassPass
C2: Vendor PortabilityPassPass
C3: Git-Native TraceabilityPassPass
C4: Proportional ComplexityFAIL — 4 functions + 1 dataclass + 13 tests for an informational warningPass — zero new code
C5: Reuse Before InventionFAIL — _matches_exclude_pattern duplicates generate_changelog.py filtering logicPass — reuses existing tool with --verbose flag
C6: Bounded ScalabilityPassPass

Result: Old C1-C4 framework: 0 violations (would approve the wrong plan). New C1-C6 framework: 2 violations (correctly flags it). This validates C5 as the critical missing constraint.

Additional ADR Validation

References

Analyses
A-26002: Agentic OS, Tiered Cognitive Memory, and Package-Driven Infrastructure
Analyses
A-26004: Hook Stage Assignment Rationale