Skip to content

ADR-003: Autonomy is a Three-Position Spectrum, Not a Fixed Level

Example from HELIX’s own docs. This generated page comes from docs/helix/. Use it to see the method in practice; start with the artifact-type catalog for reusable templates. Historical plans and reports may describe retired architecture.

Source identity (from 02-design/adr/ADR-003-autonomy-spectrum.md):

ddx:
  id: ADR-003
  authoring:
    home: repo
  depends_on:
    - helix.prd
    - FEAT-011

ADR-003: Autonomy is a Three-Position Spectrum, Not a Fixed Level

DateStatusDecidersRelatedConfidence
2026-05-24ProposedHELIX maintainersFEAT-011, TD-011, PRDHigh

Context

AspectDescription
ProblemA max-autonomy “one-shot a working app” build showed HELIX needs a governed way to say how much a runtime should pause for human confirmation. The low/medium/high vocabulary already existed in action guidance, but its governing feature and design had been removed, leaving the policy dangling and unauditable.
Current StateThe PRD defines autonomy as a controllable spectrum and prohibits flattening the seven-activity loop into one prompt. Nothing records why the spectrum has three positions, how the active level is resolved, or what a high-autonomy run may never do.
RequirementsHELIX defines a fixed vocabulary, deterministic resolution order, and two invariants: no level passes a hard stop, and no level skips a required activity. The policy remains runtime-neutral and requires no runtime-specific configuration.

Decision

We adopt a three-position autonomy spectrum — low, medium, high, default medium — that controls checkpoint density only. The level changes how often a workflow pauses for confirmation; it never changes which activities run or whether a hard stop is honored.

We fix the resolution precedence as: per-invocation override → the autonomy: block in .helix.yml → runtime default (medium). The marker’s autonomy: block is the sole project-policy source; governing-artifact frontmatter is not in the chain. The autonomy signal lives only in runtime-neutral artifacts. CLAUDE.md and runtime-specific instruction files are explicitly excluded from the chain.

We bind two invariants to every level:

  • Hard stop — true higher/equal-authority contradictions, unauthorized destructive actions, and human-only decisions stop the workflow at any level. High autonomy raises the pause threshold, never the stop floor.
  • Never collapse the loop — autonomy changes pause frequency, not the seven-activity loop. A high-autonomy run executes the same activities a low-autonomy run would.

At high, a workflow additionally infers concern selection when none is declared, recording the inference as an assumption rather than pausing to ask.

Key Points: three fixed positions | precedence chain is override → marker autonomy: → default, excludes artifact frontmatter and CLAUDE.md | checkpoint density only | hard stop + never-collapse-loop invariants | high autonomy infers concerns

Alternatives

OptionProsConsEvaluation
Single fixed behavior (always-ask or always-autonomous)Simplest to describeContradicts the PRD spectrum goal; unusable for both learning and one-shot contextsRejected: PRD requires a spectrum
Numeric/continuous slider (0–100)Fine-grainedNo meaningful semantics per value; impossible to test deterministically; invites per-step bikesheddingRejected: three positions are testable and sufficient
New vocabulary (ask-first/guided/yolo)EvocativeForks the existing low/medium/high already used in input.md, creating driftRejected: reuse the established vocabulary
Store autonomy in CLAUDE.md / runtime configConvenient per-runtimeBreaks runtime-neutrality (PRD R-4); same project would behave differently across runtimesRejected: signal must be runtime-neutral
Three positions, precedence chain, two invariantsReuses existing vocab, testable, runtime-neutral, auditableRequires restoring FEAT-011/TD-011 and re-blessing CONTRACT-002Selected: smallest governed policy that satisfies the PRD

Consequences

TypeImpact
PositiveThe autonomy policy is governed, auditable, and testable.
PositiveThe same project behaves identically across runtimes because the signal is runtime-neutral.
PositiveHigh autonomy becomes safe to use: the hard-stop and never-collapse-loop invariants bound what it may do.
PositiveConcern inference at high autonomy turns the previously inert concerns library into a default behavior.
NegativeEvery action that can pause must resolve the level at bootstrap — a small recurring authoring cost.
NeutralHELIX still ships no execution engine; the runtime supplies the agency the policy describes.

Risks

RiskProbImpactMitigation
“More autonomy” is read as “skip activities”MHFR-5 never-collapse-loop invariant stated in FEAT-011, TD-011, skill, and here
Autonomy signal leaks into CLAUDE.mdMMPrecedence chain explicitly excludes it; runtime-neutrality is a PRD-measured metric
Inferred concerns diverge from real needsMMInference recorded as an assumption; alignment review flags drift
High autonomy bypasses a true contradictionLHHard-stop invariant applies at every level; tested via the workflow-coverage harness

Validation

Success MetricReview Trigger
No dangling FEAT-011 / TD-011 references remainAny action or contract still cites a missing autonomy artifact
Active level resolves deterministically by the precedence chainAn action resolves autonomy from CLAUDE.md or a runtime config
High-autonomy runs infer concerns and still honor hard stopsA high-autonomy run overwrites concerns.md or passes a hard stop
Every required activity runs at every levelA high-autonomy run skips an activity or flattens the loop

References

Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
artifacts/adr/ADR-003-autonomy-spectrum.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:43c113f1…d3ee464b

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifacts/adr/ADR-003-autonomy-spectrum/",
        "digest": {
          "alg": "sha256",
          "value": "43c113f190ae036f8cd263a86a011392f8f229fe5a8658a1d6d4722ad3ee464b"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "xH8GsK8tkVIT_9Gbg0bV0Hcuqbuh98t5IEZ3lvMkBxCLcnc3rRMps1Nt4NQbxKU4sG3K2E_qNfOIq0VCigJCAw",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}