Skip to content

The Spec Growth Engine: Spec-Anchored, Code-Coupled, Drift-Enforced Architecture for AI-Assisted Software Development

🕒 Published (v1): 2026-06-25 13:51 UTC · Source: Arxiv · link

Why this paper was selected

Spec-anchored coding agent architecture tackling context explosion and drift; directly applicable to long-session agent harnesses

Ask a follow-up

Open an assistant pre-loaded with this paper's context.

💬 Ask ChatGPT✦ Ask Claude

TL;DR

The Spec Growth Engine is a lightweight framework for AI-assisted software development that addresses two structural failure modes: context explosion (agents reasoning over entire repositories) and silent spec-code drift (specifications becoming stale as code evolves). It enforces spec-code alignment via a machine-readable spec graph, a scoped context assembler (Spine), and a blocking drift gate that makes divergence a merge error rather than a discipline problem.

Problem

AI coding agents produce brittle outputs because (1) unscoped context degrades generation quality as fill increases—models retrieve worst from the middle of long contexts, with one benchmark showing a drop from 29% to 3% accuracy as the window grows from 32K to 256K tokens—and (2) spec-code drift is invisible to linters and CI, so agents guided by stale specifications compound errors at machine speed. Existing approaches are either spec-first (specs discarded post-generation, e.g., AWS Kiro) or spec-as-source (fragile single source of truth, e.g., MDA); neither enforces living, code-coupled specifications.

Method

The engine has five interlocking components:

Spec Graph: Every architectural entity is a SPEC.md node at one of four C4 levels (system → container → component → code). Each node has a contract (outward-visible: interfaces, invariants, acceptance criteria) and a design (inward-only: implementation approach). Ownership edges form a tree; dependency edges form a DAG, one-hop only.

Spine Context Assembler: For a working node \(N\), the context bundle is: $\(\text{Context}(N) = \text{RootInvariants} + \text{SpineContracts}(\text{root} \to N) + N.\text{fullSpec} + \text{Contracts}(\text{deps}(N)) + N.\text{ownCode}\)$ Sibling components, dependency internals, and transitive dependencies are excluded. The assembler traverses the graph deterministically; it never free-searches the repository.

Drift Validator: Derives an Intent Graph from SPEC.md files and an Evidence Graph from static code analysis (imports, exports, routes, tests). Hard errors that block merge include orphan code, undeclared dependencies, and contract bypasses. The coding agent emits a spec delta in the same commit; the human reviews only contract-level changes.

Governance Gates: Three levels keyed to blast radius—HARD (human approval: root invariant or contract change), SOFT (async human review: additive contract), AUTO (engine decides: internal design, refactoring).

Capability Registry: A horizontal DRY axis; agents query cap:<name> before implementing, preventing duplicate implementations across teams.

Growth is governed by six rules (Behaviour, Decomposition, Dependency, Boundary, Internal Design, C4 Promotion) that prescribe the minimal coupled artifact set for each change class. A two-layer ordering rule mandates that Layer-1 invariants (persistence, security, external integrations) are specified in ARCHITECTURE.md before any feature slice, and Layer-2 features grow as hardest-first vertical slices.

Key Contributions

  • Spec Graph with contract/design separation at every C4 level, materialised as per-node SPEC.md files plus a transversal ARCHITECTURE.md.
  • Spine context assembler that bounds agent context to the ownership path plus one-hop dependency contracts, directly applying Parnas information hiding to agent context.
  • Blocking drift gate that makes spec-code divergence a structural impossibility rather than a process discipline problem.
  • Two-layer growth protocol (hardest-first vertical slices over a pre-specified invariant floor) that prevents both breadth-first faking and silent under-architecture.
  • Capability Registry for architecture-level DRY enforcement across parallel development streams.
  • Six deterministic growth rules that prescribe minimal artifact movement per change class, bounding blast radius and keeping most changes in the AUTO gate.

Results

The paper is a framework/design proposal with no empirical benchmark results reported. Evidence cited is from prior literature: - Models drop from 29% to 3% accuracy on a long software-engineering benchmark as context window grows from 32K to 256K tokens (cited as motivation for the Spine). - "Context rot" (quality degradation with input length) and worst retrieval from the middle of long contexts are cited from prior research. - A practitioner rule of thumb: quality degrades past ~40% context fill (explicitly noted as a heuristic, not a proven threshold).

No ablations, user studies, or comparative measurements of the Spec Growth Engine itself are presented.

Limitations

  • No empirical evaluation; all claims about effectiveness are architectural arguments supported by cited prior work, not measurements of the framework in use.
  • Requires tooling investment: the drift validator, context assembler, and Capability Registry must be implemented and integrated into CI/CD—the paper describes architecture, not a released artifact.
  • The framework assumes a static spec graph that accurately reflects intent; the quality of the system depends on the Human Architect and Planner Agent correctly capturing contracts upfront.
  • Hardest-first ordering requires accurate difficulty estimation before implementation begins, which may itself require significant domain knowledge.
  • The one-hop dependency context restriction could be insufficient for cross-cutting changes that genuinely require awareness of distant components.
  • Spec Kit and Tessl comparisons note that agents frequently ignore detailed instructions; the paper asserts the drift gate eliminates reliance on agent compliance, but this is unverified.

Relevance to Agentic AI / LLM Agents

This paper directly addresses a core failure mode of agentic coding systems: unbounded context degrades LLM output quality, and agents operating without spec-code coupling accumulate architectural debt at machine speed. The Spine's deterministic context scoping is a concrete, implementable answer to the open problem of how to give an agent exactly the right context for a bounded task—relevant to any multi-agent system that decomposes work across components. The governance gate model (AUTO/SOFT/HARD keyed to blast radius) is a practical instantiation of human-in-the-loop oversight for agentic systems, addressing when to involve humans without defaulting to full human review. The four-actor model (Human Architect, Planner Agent, Coding Agent, Engine) is a clean reference architecture for role separation in multi-agent software development pipelines.