PaperlayerView exact revision on arXiv

Source-linked AI summary

Implementing the Spec Growth Engine: Preventing Spec-Code Divergence, and Growing the Spec with Agents

Hartwig Grabowski

arXiv:2610.11725v1cs.SE

TL;DR

The paper addresses how to determine whether a specification graph and its codebase agree, and how agents can grow that specification toward a goal. It implements separate deterministic-checking and agent-run layers, then lays out eighteen project-running configurations; its design claim is that autonomous runs depend on the deterministic instance that measures them.

  • Problem

    The paper addresses how to determine deterministically whether a specification graph and codebase agree, including imports, file ownership, test evidence, and changes that break relied-on promises.

    Source: §1 · p. 1

  • Method

    The implementation separates a model-free deterministic layer for checking divergence from a second layer where agents grow the specification and code in rounds under a deterministic run rule.

    Source: §1 · p. 2

  • Results

    The paper describes eighteen ways to run a project, formed by combining three independent autonomy switches with two ways of laying the project's floor.

    Source: §1 · p. 2

  • Takeaways & Limitations

    An autonomous run is worth only as much as the deterministic instance that measures it afterwards.

    Source: §1 · p. 2

    The implementation does not include an early-stop run that asks before coding when a specification has an open request or an unaccepted HARD change.

    Source: §3.3 · p. 10

Abstract

from arXiv · show

The Spec Growth Engine anchors AI-assisted software development in a graph of specifications that the code is coupled to. This paper describes its implementation, which serves two tasks and keeps them apart as two layers. The first layer prevents spec-code divergence: a deterministic engine validates the spec graph, compares it with the code's import graph, earns a node's verified status from recorded test evidence, and classifies every change by what it can break -- without calling a model. The second layer grows the spec with agents: an intent author, a planner and a coder, each played by its own model, extend the graph in rounds, and a deterministic rule decides after each round whether the run goes on. How much of the human's judgement is delegated is set by three independent switches -- a draft gate, a delegation for breaking changes, and the run mode -- which, with two ways of laying a project's floor, give eighteen ways to run a project. We describe each of them, the gates, requests and waivers through which agents and the human communicate, and the spectrum of operation from entirely manual work to an unsupervised run whose decisions the human reviews afterwards. Throughout, one claim holds the design together: an autonomous run is worth only as much as the deterministic instance that measures it.

1 Introduction

This paper implements the Spec Growth Engine and separates deterministic prevention of spec-code divergence from agent-led growth of the specification. It describes a model-free checking layer and a second layer in which agents work toward a goal under a deterministic run rule.

1 Introduction

  • The deterministic layer checks graph-code agreement, including declared imports, file ownership, test evidence for completed nodes, and whether changes break promises consumers rely on.The implementation also describes a deterministic floor with structural validation, drift detection, earned status, and change classification.Source: §1 · pp. 1–2
  • For a given goal, agents write node intents, specifications, and code, while a decision after each round determines whether the goal is met, work continues, or a human is needed.The paper describes an engine, command-line interface, and graphical cockpit developed and tested through agent runs on small, concrete tasks.Source: §1 · p. 1
  • The two tasks remain separate: divergence checking must be reproducible and use no model, while agent-led specification growth depends on model-based judgment and rests on the first layer.The first layer can be used on its own by a person with a text editor and the gate.Source: §1 · p. 2
  • Three independent autonomy switches, combined with two ways of laying a project's floor, form eighteen ways to run a project.The switches govern distinct aspects of delegated judgment rather than a single autonomy ladder.Source: §1 · p. 2
  • The run driver lets agents work in rounds, with an unsupervised mode in which a reviewer model decides in the human's place and the human reviews every decision afterwards.The paper also identifies decision requests and waivers as communication channels that grant agents no authority by themselves.Source: §1 · p. 2

2 The Engine

The engine separates model-free measurement of specifications and code from agent-driven growth. Its deterministic floor checks consistency and change risk, while requests, waivers, and independent autonomy switches govern how human judgment enters the process.

2.1 Two Layers, Six Roles

  • Layer 1 comprises per-node SPEC.md files, shared ARCHITECTURE.md, engine records, and a gate that reads them; each model-backed role has its own endpoint, while the engine calls no model.Six roles operate the engine; four call a model, and the human is always a person. A run can use one model for everything or a different model per role.Source: §2.1 · p. 2

2.2 The Deterministic Floor

  • The deterministic floor checks graph structure and code-import drift, and verified status requires recorded passing test evidence for acceptance criteria with no open waiver.The floor runs offline and deterministically, and can refuse a drifting commit as a pre-commit hook.Source: §2.2 · p. 3

2.3 Gates: SOFT and HARD

  • The engine classifies each specification change by gate and affected consumers; because invariant changes cannot be reliably read as tightening or widening, any invariant change counts as breaking.Only a pure addition to provides is provably additive, and the strictest reason sets the gate.Source: §2.3 · pp. 3–4

2.4 Requests and Waivers

  • Decision requests record proposals that exceed an asker’s authority, while waivers record typed, time-limited permissions to deviate; neither grants permission by itself.Only the human grants a waiver, with an owner and expiry; expired waivers block the gate.Source: §2.4 · p. 5

2.5 Three Switches

  • Human judgment is delegated through three independent switches: who authors intent, who reviews drafts, and whether H′ may accept certain pending HARD changes.The draft gate stops at D2; the delegation applies only to specified migrated breaking changes and still requires human confirmation or overruling.Source: §2.5 · pp. 5–6

2.6 Eighteen Ways to Run a Project

  • Two project floors—guided or bare—combine with the switches to give eighteen ways to run a project, with the table distinguishing when the human is asked.The draft gate does not apply during runs, and unsupervised mode requires delegation; hand-written specifications with the gate provide a nineteenth way requiring no model key.Source: §2.6 · pp. 6, 8, Table 3 · p. 7

3 Operation: From by Hand to Unsupervised

The engine supports a spectrum from manual work to unsupervised runs, with each step delegating more authorship or judgment while retaining the same floor. Agents work in rounds, and deterministic checks and rules—not an agent’s claim of completion—measure progress and decide whether a run continues.

3 Operation: From by Hand to Unsupervised

  • Each step toward unsupervised operation delegates more authorship or judgment, but the floor still runs and blocks at every step.The spectrum ranges from work done by hand to an unsupervised run.Source: §3 · p. 8, Figure 2 · p. 8

3.1 By Hand

  • In the by-hand mode, a person creates and edits specifications; the gate checks drift and evidence, and a pre-commit hook blocks commits that drift.The engine records human acceptance of HARD changes; this is described as the smallest complete use of the method and costs nothing.Source: §3.1 · pp. 8–9

3.2 With Help: from Intent to Spec

  • With planner help, human intents drive specification drafts whose code globs follow ownership-path layout invariants, while revisions preserve unmentioned content and show a change set.Intents become node growth history; revision notes explain changes separately, while compaction and cockpit warnings address repeated prose and missing promised operations.Source: §3.2 · p. 9

3.3 An Agent Run

  • In agent runs, the intent author works through engine commands, and after each session the engine measures the floor before H′ checks the goal and a deterministic rule decides whether to continue.H′ identifies missing goal statements and what awaits a human decision; it must account for prior-round gaps before naming new ones.Source: §3.3 · p. 9
  • A run distinguishes waiting for a human decision from being blocked, and a human can run the floor-and-goal check without starting an agent session.The check reports done, gaps, asking, red, or unchecked; asking includes matters awaiting the human, so done means nothing remains waiting.Source: §3.3 · pp. 9–10

3.4 Unsupervised

  • In unsupervised runs, H′ answers requests and decides delegated HARD changes between rounds, while uncertain requests remain open for the human.H′’s answers are recorded, and the human must later accept or reject them; rejection blocks the gate until the work is taken back.Source: §3.4 · p. 11

3.5 Setting Up a Project

  • Projects can be set up in any directory, with setup answers recorded so the same floor can be laid elsewhere; model roles use explicit per-role configuration without fallback.The configuration file specifies each role’s endpoint, key, and model, and agent roles also specify a harness; invalid or missing settings are reported before a run starts.Source: §3.5 · p. 11

4 Example: A Number-Guessing Game

The walkthrough follows a number-guessing game from a green project floor through goal checks and specification revisions, then compares supervised and unsupervised agent runs on the same goal. The checks expose gaps and keep runs from claiming completion while a human decision or review remains outstanding.

4 Example: A Number-Guessing Game

  • The initial floor comprised a Python game component, six invariants, and a human-approved twelve-behavior goal; the build passed 43 tests and the gate passed.The two drafted components were classified as new components, or SOFT changes.Source: §4 · p. 12
  • Three gaps remained after a green floor and 43 passing tests: two invariants tests would not catch and one behavior missing from a contract.The gaps were named against TASK.md and located to the relevant specification lines.Source: §4 · p. 12
  • A revision closed the three goal-check gaps in game.cli’s saved specification, after which the coder corrected code and tests to match its revised prompt contract.The build and gate then passed over 46 tests.Source: §4 · pp. 12–13
  • A third goal check returned DONE with no gap over 47 tests after a revision added seeded variation and narrowed repeatability to runs with the same explicit seed.The second check had identified that a fixed default could pass without showing the secret varied.Source: §4 · p. 13
  • A compaction from 55 to 50 lines kept every promised operation but was classified HARD because changed contract text used by game.cli counts as broken.The human reviewed the before-and-after pairs and did not save the compaction.Source: §4 · p. 14

Unsupervised.

  • In the supervised run, a request about the human-owned container left one behavior on hold, so the run stopped ASKING despite no named goal gap.The behavior worked and had a test, but depended on the open request.Source: §4 · p. 14
  • The unsupervised run ended UNCHECKED when the goal check hit the provider output limit; a later check returned ASKING because a delegated acceptance awaited human review.The growth record preserved the in-round decision and the goal check surfaced it to the human.Source: Unsupervised · p. 15
  • Both agent runs stopped short of DONE at human decision or review boundaries, despite driving the real program through TASK.md and leaving no gap for H′ to name.The same goal produced graphs with two, three, and four components; the runs exposed engine weaknesses that were fixed afterward.Source: Unsupervised · p. 15
Loading 2610.11725v1…