This is the record of an abcd-managed repository

abcdBetav0.16.2 · 2026-11-06

Development record

SOTA Per Intent

principlesota-per-intent

The rule. Every intent declares the current state of the art for the capability it promises: the alternatives that already exist and each one's rough maturity. From that declaration the intent recommends exactly one of three paths, and each path has its own gate:

  1. Build on the SOTA alternative — adopt the existing tool/library. Because this adds a dependency, it is a hard stop: the user must approve before adoption. (This is the standing new-dependency gate, now reached through the SOTA declaration rather than at go get time.)
  2. Build a basic native version, seam for SOTA later — a minimal internal solution that achieves the intent now, designed so the SOTA alternative can be plugged in later behind a seam. This path proceeds without a stop — its licence to skip approval is precisely that it keeps adoption open. The seam must be real, not asserted.
  3. Bespoke, no swap possible — the SOTA alternative cannot be used now and cannot be plugged in later either (no viable seam). This is a hard stop: the user reviews to decide how much complexity the permanent internal solution should carry. A merely deferred seam is still path 2; path 3 is only for a genuine commitment to a permanent bespoke solution.

The load-bearing idea: the SOTA alternative always stays on the table. A native build earns its way past the approval gate by keeping the option to adopt open (path 2); the only way to close that option (path 3) is a decision the user makes deliberately, having chosen the complexity level.

Why. prefer-sota makes SOTA the default bar and supplies the fit-challenge that stops "it's SOTA" from laundering a preference violation. This principle is what that verdict produces at the intent boundary: a written, per-intent record of where the field is, and a decision that is honest about which of the three postures the intent takes. It closes two failure modes at once. Silent over-adoption — pulling in a heavy dependency without the user weighing it — is blocked by gate 1. Silent lock-in — building a bespoke thing that quietly forecloses ever adopting the better external tool — is blocked by gate 3; the default, path 2, is abcd's house pattern (a native floor with an easy opt-in to a superior backend, per adr-22 / adr-26), and it is allowed to proceed because the seam keeps the field's best answer reachable. The declaration also ages well: maturity is rough and dated, so a path-2 intent can be revisited when the SOTA alternative matures enough to be worth adopting.

Bounds.

  • The SOTA declaration is per intent and rough — existing alternatives + a coarse maturity read (e.g. experimental / usable / mature / de-facto standard), not a survey. It is the input to the path choice, not a deliverable of its own.
  • Path 2 is the default and the only stop-free path, and only while the seam is genuine. If, during build, the seam turns out not to be viable, the intent has become path 3 — stop and take the complexity decision to the user; never quietly harden a bespoke solution that can no longer adopt SOTA.
  • Gate 1 and the standing "new dependency ⇒ ask first" rule are the same gate; this principle routes the dependency decision through the SOTA declaration so the user approves with the alternatives and maturities in front of them.
  • A path-2 seam is a design constraint, not a promise to build the adapter now: the adapter lands only when a phase consumes it ([wired or it isn't done]), but the interface must not foreclose it.

Scope. A propagated default, like prefer-sota: it holds for every abcd-managed repo as one of the opinionated conventions abcd installs, and its home in a managed repo is the marked working-conventions section abcd writes into AGENTS.md. abcd's own record carries the normative statement here.

Composes with. prefer-sota (the adversary→verdict protocol that produces the SOTA read this principle declares); script-first-mvp and one-canonical-primitive (what a good path-2 native floor looks like); loud-staging (a path-2 build says loudly what is basic-now-vs-SOTA-later); verifier-selects-gates-decide (gates 1 and 3 are the human's decision, not the recommender's).

Promotion. MVP: this principle plus a ## SOTA section in the intent template (the alternatives + maturity + the path-1/2/3 recommendation), carried in intents/README.md and brief/04-surfaces/05-intent.md. Discipline: an intent_sota record-lint gate that a promoted intent must carry a non-empty ## SOTA declaration naming a path, with gate 1 / gate 3 intents blocked from plan/ship until an approval or complexity-decision receipt is recorded — promoted to a discipline-kind intent when the mechanical gate is built.

mentions2