Skip to content

ADR-0001: A sanctioned lane in Principle II for quickfix and small changes

Date: 2026-10-03 Status: accepted Superseded by: — Spec: SPEC-164 (decisions D2, D3, D8, D9, D11, D12, D14 in specs/164-proportional-ceremony-fast-lane/decisions.md)

Context

Constitution Principle II ("Spec-Driven Development", .specify/memory/constitution.md) requires a SPEC-NNN before any implementation begins, and its violation test is "implementation begins without a corresponding SPEC-NNN file". It has no exemption. /vt-d-quickfix already implements changes without a spec, so it breaks Principle II today, and nothing names or limits that.

SPEC-164 adds a second spec-less path for small changes. Its Wave 0 measurement (specs/164-proportional-ceremony-fast-lane/observed-case.md) took one small bug through the full workflow: 48 h from filing to merge, 14 invocations of 9 workflow skills, for a change of 2 code files. For a small feature, the full workflow adds /vt-d-spec-from-requirements, /vt-d-shape, /vt-d-2-plan and the plan gate on top of that.

A spec-less path has one known failure shape: a vague exemption becomes the bypass. In the current workflow, a run with no spec skips the gate-critical spec-compliance-reviewer silently, so leaving the spec out costs less than writing one.

Alternatives Considered

Option A: Amend Principle II with a sanctioned lane covering quickfix and small changes

  • Pro: states honestly which work runs without a spec, and closes quickfix's unsanctioned gap at the same time.
  • Pro: one boundary for one class of work, stated in one place.
  • Con: a constitution change; the exemption needs an exit test a run can fail, or it becomes the bypass.

Option B: The lane writes a minimal stub spec, and Principle II stays as written

  • Pro: no constitution change.
  • Con: ceremony posing as compliance; a spec-compliance review against a stub gives a green gate that proves nothing.

Option C: Exempt the new lane only

  • Pro: a smaller amendment.
  • Con: quickfix stays unregulated, so two rules govern one class of spec-less work.

Decision

Option A (owner, SPEC-164 D2). Principle II gains a subsection, "Sanctioned lane", as a MINOR amendment 1.1.0 → 1.2.0 (D8):

  • Three levels, one boundary. /vt-d-quickfix class quickfix (trivial) ↔ class small-change (not spec-worthy, within the bound) ↔ the full workflow (spec-worthy). The boundary is stated only in Principle II; skills link to it.
  • The bound is at most 5 changed code or test files, workflow records not counted (D12). It is provisional and is re-evaluated once 5 small-change lane records exist (D11). It is stated once, as a machine-readable marker that tooling reads.
  • The exit test, which a run can fail: (a) every lane run writes its own lane record; (b) before review, the class is re-checked against the actual diff, and a diff beyond the bound — or a record that declares the change architectural — escalates to /vt-d-spec-from-requirements; (c) no gate-critical reviewer is skipped silently: spec compliance runs with the lane record as a stand-in spec, and the review gate records that it did (D3); (d) /vt-d-5-finalize fails a gate for a branch with no spec, no lane record and no open bug (D9), and a branch that carries both a spec and a lane record (D10).

Consequences

Positive

  • Quickfix becomes sanctioned work with a stated limit instead of an unnamed exception.
  • Leaving out the spec is no longer cheaper than using the lane: a spec-less gate without a record fails at finalize.
  • The bound is calibrated from real lane runs, not from VTD's uncalibrated "≥10 files".

Negative and residual risks

  • The control acts through finalize only. The finalize rule (R9) runs where validate-review-gate.sh runs today, in /vt-d-5-finalize, not in CI. A branch that goes build → review → PR without finalize is not checked. A CI check is a follow-up spec, because it would reach every PR in the repository (D14).
  • An override down to quickfix is unchecked. A developer can classify a larger change as quickfix; that class never reaches review, so the diff re-check does not run for it.
  • The provisional bound of 5 files comes from one observed case and may be wrong in either direction until it is recalibrated.

Implementation Notes

  • The amendment carries exactly one marker line, <!-- lane-bound: files=5 status=provisional -->. SPEC-164's lane-detect.sh bound parses it, and zero or two markers are an error.
  • Follow-ups inside SPEC-164 (Tasks 5–10): the lane-record schema in intake/quick-fixes/README.md, plugins/vt-base/bin/lane-detect.sh, quickfix's small-change class, the dev-start pointer row, the stand-in in workflow-4-review and implementation-orchestrator, and rule R9 in validate-review-gate.sh.
  • Follow-up outside SPEC-164: a CI check that runs R9 on PR branches (D14).