Handbook
Autonomy levels (the ladder)
Public source of truth: blueprints/sdlc/methodologies/forge/AUTONOMY-LEVELS.md (handbook: https://blueprints.forgesdlc.com/sdlc--methodologies-forge-autonomy-levels.html). This file is the PoC maintainer copy; edit the…
Updated
Public source of truth: blueprints/sdlc/methodologies/forge/AUTONOMY-LEVELS.md (handbook: https://blueprints.forgesdlc.com/sdlc--methodologies-forge-autonomy-levels.html). This file is the PoC maintainer copy; edit the blueprint page first, then sync here if needed.
Autonomy is not binary. Levels are theoretically unbounded; this ladder gives a meaningful, testable progression. Each level is defined by its unit of autonomous delivery, what stays fixed, and where humans gate.
| Level | Autonomous unit | What stays fixed | Human gate |
|---|---|---|---|
| L0 Assisted | Suggestions only | Everything | Continuous |
| L1 Function | One method/function to a given signature/contract | Architecture, API, tests | Approve branch/merge |
| L2 Change-set | Multi-function / multi-file defect fix or small change, no rearchitecture | Architecture, public contracts | Accept acceptance criteria + merge |
| L3 Use-case slice | End-to-end user-visible flow inside one existing app (UI + logic + data + tests) | Existing architecture, single platform | Intent + acceptance in; review out |
| L4 Feature/component | Capability across modules; may add a component within existing architecture; cross-repo, one platform | Platform, major architecture | ADR + release gate |
| L5 Subsystem w/ local arch evolution | Introduces patterns/refactors within a platform | Platform boundary | Architecture decision escalation |
| L6 Product increment | Multi-repo, multi-service on a single cloud/platform | Cloud/platform choice | Go/no-go |
| L7 Multi-cloud / multi-platform solution (max - 1) | A whole engineered solution spanning clouds/platforms | Business framing | Strategic checkpoints |
| L8 (max) Autonomous problem solving | Frames a business/humanity problem and composes L7 solutions as puzzle pieces | Nothing but the goal | Mission definition only |
Where this PoC sits
The PoC implements L1, L2 change-set, and L3 use-case slice autonomy. L4+ is post-v1 vision.
L2 enforcement
L2 runs declare level: L2 and execute ordered patch units (one file per
unit in the PoC). The assay gate requires two or more distinct changed files
in the aggregated proof before a multi-file item is accepted.
L3 enforcement
L3 runs declare level: L3 and execute layered patch units (logic, docs,
UI). The assay gate requires two or more distinct layers, cross-layer
file evidence (.py and non-.py), and E2E verification recorded in
the proof (Playwright via verify-docs-health-l3.py).
Assay sub-levels (L1.1–L4.3)
Runs and campaign items may declare a sublevel (e.g. L2.2) in addition to
the parent level. When final_status == pass, assay_gate._check_sublevel
enforces distinct evidence per id. Unknown ids or sub-levels that do not belong
to the declared parent level fail the assay.
Canonical ids match KNOWN_SUBLEVELS in
src/forge_dark_factory/assay_gate.py.
See also tests/test_assay_gate.py and
Reliability sign-off.
| Sub-level | Parent | Evidence enforced on pass |
|---|---|---|
| L1.1 | L1 | provided_test_files declared; none of those paths appear in changed_files |
| L1.2 | L1 | At least one agent-authored test file in changed_files (test_*, *_test.py, or under tests/) |
| L1.3 | L1 | unit_count >= 2 (function units) |
| L2.1 | L2 | hunk_shapes for ≥2 files, all same shape; no behavior-test files in changed_files |
| L2.2 | L2 | failing_test_before recorded (pre-existing red test before the fix) |
| L2.3 | L2 | acceptance_criteria list present; at least one new/changed test file |
| L3.1 | L3 | target_repo is a sandbox path (matches sandbox_targets, default sandbox) |
| L3.2 | L3 | target_repo declared and not in the sandbox allowlist |
| L3.3 | L3 | Migration file in changed_files; non-empty rollback_note on the run record |
| L3.4 | L3 | campaign_passing_items >= 2 (L3.x-passing items in the campaign) |
| L4.1 | L4 | adr_recorded and release_gate_recorded both true |
| L4.2 | L4 | Changed files span ≥2 distinct repo prefixes; submodule_pointer_commit recorded |
| L4.3 | L4 | Non-empty adr_signed_ref (signed ADR reference) |
Parent-level gates still apply: L2 requires ≥2 distinct changed files; L3 requires
≥2 layers, cross-layer .py + non-.py files, and a registered E2E runner in
tests_run (allowlist: playwright, run-l3-e2e, verify-docs-health-l3, …).
How a level is enforced
- A run declares its target level (and optional sublevel).
- The Assay gate for that level is what must pass before the change is
considered done (see
forge/forge.config.yamlcore evidence:tests_pass,acceptance_criteria_met,risks_reviewed). - Higher levels do not skip lower-level gates; they add gates.
Honest boundary at 4GB local + no cloud
Fully cloud-free autonomy above L1 is not realistic on a ~4GB local model: planning, architecture, and ambiguity exceed small-model capability. The realistic operating mode is local-first with ROI-gated escalation to a larger model or a human at pivots. The escalation rate is a tracked metric that should fall over time as capability cards and deterministic scaffolds improve. See ROUTING.md.