AOI v0.3 development plan

Status: active development plan, 2026-07-16

AOI v0.3 is an evidence-first release line. It must reduce governance overhead, finish the dependency-boundary work already under way, and make package and evaluation claims reproducible. It is not a vehicle for adding more governance vocabulary.

The first pre-release artifact is 0.3.0a1. Alpha artifacts may prove that a mechanism works; they must not claim that AOI is generally better than a strong single agent or a conventional supervisor.

Product thesis

AOI should be the smallest auditable layer that prevents expensive coordination failures which a simpler workflow does not prevent. A feature belongs in v0.3 only when it does at least one of the following:

• removes mechanical lifecycle work without weakening an evidence gate;
• makes ownership, state publication, or recovery measurably more reliable;
• creates an executable comparison against a simpler topology;
• reduces a module boundary that is currently difficult to reason about; or
• turns a release or compatibility statement into a machine-checked fact.

Release outcomes

O1 — Low-risk work has a short, fail-closed path

A one-to-three-file mini task should require three AOI interactions:

1. start-mini;
2. one or more explicit add-verification records; and
3. finish-mini.

finish-mini may automate claim release, delivery disposition, checkpointing, and closure. It must not execute a verifier, invent evidence, promote an inference, or bypass the existing close gate.

start-mini provides only best-effort rollback for ordinary Python exceptions. Hard process termination is a separate recovery problem; neither the mini path nor atomic-temporary cleanup is a multi-file transaction.

Acceptance:

• the fast path accepts only an open mini task with one canonical claim over one to three repo:file locks, a current plan/config/worktree, no packets or jobs, and an integrity-v1 passing close-qualifying verification;
• all semantic preflight failures leave state bytes unchanged;
• none, local-only, and pushed delivery retain their current integrity rules, including remote-ref verification for pushed work; the fast-path receipt additionally requires a full 40–64-hex pushed commit ID so retries cannot reinterpret a short prefix;
• a recoverable I/O interruption never leaves a done task with an active claim or stale checkpoint;
• an equivalent manual mini lifecycle remains supported; and
• the completed task passes scoped doctor and has no bound session.

O2 — The CLI becomes a composition root

New command bodies may not be added to aoi_orgware.cli. Existing bodies are removed in bounded, behavior-preserving slices with import-boundary tests.

Extraction order:

1. status/resume/index views;
2. verification lifecycle;
3. external jobs;
4. packet lifecycle;
5. terminal task lifecycle;
6. doctor and onboarding seams.

harnesslib.py is a separate migration axis. It will first retain compatibility re-exports, then split atomic I/O, platform/path locking, task persistence, claims, checkpoints/index, Chief authority, and legacy import. Command and domain modules must never import the CLI composition root.

The initial AST ratchet covers every module under commands/. Codex and Claude hook adapters are a documented temporary exception because they still lazily import CLI services; 0.3.0a2 must replace those reverse imports or reduce them under an exact, non-growing module-pair allowlist before the boundary claim is expanded beyond command modules.

Acceptance:

• an AST-based dependency test rejects reverse imports into cli;
• a ratcheted allowlist prevents new local cmd_* bodies in cli;
• each extraction keeps parser, JSON, ordering, size, and recovery contracts byte-compatible where those bytes are already public state or output; and
• new behavior tests live outside the existing tests/test_cli.py monolith.

O3 — Published artifacts have one version and one evidence chain

The package version is PEP 440 0.3.0a1, with one source consumed by Hatch, runtime imports, CLI output, wheel metadata, and release validation. A tag is a verified mirror of that version, not a second version source.

Acceptance:

• Linux and Windows unit jobs cover Python 3.11, 3.12, and 3.13;
• CI builds one wheel and one sdist, runs strict metadata checks, and installs each artifact without source-tree PYTHONPATH assistance;
• all three console scripts resolve from the installed artifact;
• packaged policy, client skills, and pilot resources are present;
• release jobs publish the already-tested artifacts instead of rebuilding; and
• the tag, changelog section, artifact metadata, checksums, and runtime version agree before publishing.

Ruff, type checking, and branch coverage become blocking only after a clean baseline is recorded. The initial coverage threshold is the measured baseline rounded down, never an aspirational number invented for this document.

O4 — Reliability claims match the tests that actually ran

The a1 baseline covered many state-machine failures and several subprocess races, but did not establish process-kill crash consistency, power-loss durability, or live Codex/Claude integration. The current a2 worktree implements parent-released subprocess races, exact process-termination observation points, and atomic-temporary recovery. The deterministic Chief, claim, and packet-arm workers now pause at the actual state-lock acquisition boundary. Passing local runs are development receipts; release evidence still requires the complete Linux/Windows CI receipts.

Required v0.3 resilience lanes:

• barrier-controlled lock linearizability for Chief acquisition, overlapping claims, and one-time packet arms;
• process termination before replace and after replace/before directory fsync;
• concurrent reader visibility of only complete old or new JSON generations;
• an explicit orphan-temporary-file policy with doctor or recovery behavior;
• installed-wheel lifecycle smoke in a fresh repository; and
• scheduled live-client smoke receipts, reported separately from fixture replay.

Process-kill tests may support a process-crash consistency claim. They may not be described as proof of power-loss durability.

Current implementation status, not yet an a2 receipt:

• released-process harnesses gate the actual state-lock boundary for Chief acquisition, overlapping exact claims, and one-time packet-arm consumption;
• process termination can be injected after temporary fsync and after publication but before directory fsync;
• reader tests distinguish atomic visibility from availability: successful raw reads must be complete old or new JSON, while managed reads may transiently fail closed on replacement identity drift or native-Windows sharing;
• selected checkpoint/state/index interruptions have explicit retry or rebuild assertions; and
• doctor plus recover-temporaries implement live-writer exclusion, exact residue classification, ambiguity with zero ordinary deletion, and interrupted-cleanup retry. Recovery requires the normal canonical NUL state lock, and every state-tree residue deletion requires an under-lock config reload and the current Chief;
• automatic chief-acquire accepts only an existing private regular nlink=1 canonical NUL state lock. It takes that lock, revalidates the config binding, and accepts only a complete layout or the exact existing-NUL interrupted prefix before publishing first-Chief authority;
• missing or empty locks, every state-lock alias, every root aoi.toml alias, and all other linked or ambiguous bootstrap objects fail closed with zero automatic bootstrap mutation on POSIX and Windows. They require offline/manual recovery; and
• bounded exact pre-link state-lock temporaries may remain inert only within an otherwise exact existing-NUL interrupted prefix. They are untouched until authenticated cleanup. A pre-link root-config temporary is non-stranding but remains outside .aoi/ recovery as manual audit/cleanup residue.

This is not yet the complete finish-mini persistence-boundary matrix, the Linux/Windows a2 receipt set, live-client evidence, or power-loss proof. Repo-external credential temporaries, published-but-orphaned credentials, obsolete takeover credentials, and custom credential roots also remain outside recover-temporaries; stale tuples fail authorization, but secret-at-rest audit and cleanup are an a2 follow-up.

Future roadmap, not implemented: a versioned C→S bootstrap protocol would fix the lock order as stable root-scoped bootstrap lease → project state lock for all cooperating AOI actors. An ownership ledger would record only inodes and empty directories newly created by that attempt. Rollback would run in reverse order only for exact identity with unchanged payload, and would never chmod or delete a pre-existing entry. This is neither current behavior nor current evidence, and it would not by itself cover non-cooperating same-user mutation, process-crash recovery, or power-loss durability.

O5 — AOI is compared with both simpler alternatives

The current closed-alpha-v2 A/C pilot remains frozen as an onboarding and feasibility protocol. It is not silently widened to accept supervisor records.

v0.3 adds a separate versioned triad protocol with commands equivalent to eval-init, eval-validate, and eval-summary. It may reuse the pilot's strict schema, privacy scanning, atomic publication, missingness, and descriptive statistics primitives, but it owns a new contract.

The triad protocol records:

• a SHA-bound study manifest and analysis plan;
• frozen task manifests, baselines, external oracles, and assignments;
• A: one strong agent;
• B: a conventional supervisor plus specialists; and
• C: AOI governance with an explicitly recorded topology.

When the study claims a governance effect, B and C must use the same agent, model, tool, topology, and time budgets. If C selects topology adaptively, the result is a whole-system comparison instead.

The initial corpus contains at least two frozen tasks in each of five workload classes: tightly coupled work, independently investigable work, cross-lane contract mismatch, delayed external work, and repeated workflow pain. Each task/variant cell receives at least three independent runs. All planned failed, timed-out, and abandoned runs remain in the denominator.

Before assignment, the study manifest must set numeric total wall-clock, token, and cost ceilings; a per-run timeout; the maximum tolerated infrastructure- failure fraction; and preregistered early-stop conditions for safety, budget exhaustion, or infeasibility. Early stopping never removes planned cells from the denominator. A bounded feasibility stop must publish the assignment ledger, completed/missing cells, stop reason, budget consumed, and no-effectiveness- claim marker.

Release of v0.3 is not conditional on AOI winning. A negative result is valid. Any superiority or non-inferiority claim additionally requires a preregistered minimum effect, cost ceiling, power analysis, external-oracle outcome, and complete denominator.

Milestones

0.3.0a1 — foundations

• canonical PEP 440 version source;
• Python 3.13 and installed-artifact CI;
• status/resume/index extraction and dependency ratchets;
• finish-mini contract and behavior tests;
• this plan and matching changelog/release documentation.

Exit evidence: full unit suite, package build and isolated install smoke, targeted fast-path tests, and scoped doctor fixtures. No effectiveness claim.

0.3.0a2 — resilience and executable evaluation

Status: in progress. Reliability implementation is present; passing cross-platform receipts, the executable triad protocol, and the frozen corpus remain open.

• deterministic concurrency and process-crash suites;
• orphan-temp policy and recovery/doctor implementation;
• repo-external Chief credential-residue audit and cleanup policy;
• triad-v1 manifests, validator, summary, privacy rules, and canary fixtures;
• first frozen public task corpus.

Exit evidence: Linux and Windows resilience receipts, schema canaries for pass, fail, timeout, abandonment, control drift, missing telemetry, and privacy leaks.

0.3.0rc1 — external reproduction

• complete planned triad runs or an explicit bounded feasibility result;
• independently rebuilt sanitized summary;
• second-operator reproduction on at least one task per workload class;
• finalized migration, rollback, release manifest, and artifact provenance.

Exit evidence: exact public manifests and aggregates. Claims remain scoped to the recorded corpus, models, runtimes, resource contracts, and missingness.

Outcome-to-milestone map

Outcome	a1 foundation	a2 executable proof	rc1 release closure
O1 fast path	command, receipt, preflight and retry tests	process-fault matrix across each persistence boundary	second-operator mini lifecycle from installed artifact
O2 boundaries	status extraction and command AST ratchet	verification/jobs/packets plus filesystem primitive split	terminal/doctor/hook seams and documented remaining harness facade
O3 release truth	canonical version and artifact build/install gate	pinned release toolchain baseline and provenance manifest	automated tag-SHA check and publication of the exact tested artifacts
O4 resilience	honest evidence labels and installed-artifact smoke	deterministic races, crash matrix, reader visibility and orphan-temp policy	Linux/Windows receipts plus separately labeled live-client smoke
O5 evaluation	frozen A/C compatibility and triad design	executable schemas, canaries and public frozen corpus	completed planned cells or the preregistered bounded-feasibility output

Ruff, type, and branch-coverage baselines are recorded in a2. They become blocking for rc1 only where the baseline is clean or an explicit ratchet can be enforced without grandfathering new violations.

Final 0.3.0 promotion gate

The final version is cut only after rc1 artifacts pass the complete Linux and Windows matrix, wheel/sdist installation and fresh-repository lifecycle smoke, tag-SHA/version/checksum verification, migration and rollback rehearsal, and independent reproduction of the published evaluation or feasibility summary. Every required cell and failure remains accounted for. Open P0/P1 defects, unbounded study spend, missing primary oracle outcomes, or an artifact rebuilt after verification block promotion.

Explicit non-goals

• launching or choosing an LLM provider;
• claiming hard sandbox or zero-trust isolation;
• adding governance concepts without a measured failure they address;
• making every task multi-agent;
• retroactively inventing 0.2.x tags or releases;
• treating fixture hook replay as live runtime evidence; or
• treating more records, agents, or detected incidents as proof of avoided failures.

Decision log

• The version line is 0.3 because the work changes CLI, release, and evaluation contracts. A 0.2.3 patch would misrepresent that scope.
• The first artifact uses 0.3.0a1; a bare 0.3.0 would be a final Python package version even if prose called it alpha.
• The A/C pilot stays compatible. The A/B/C study receives a distinct schema so old records do not change meaning.
• Verification remains explicit in the mini fast path. Automation removes clerical transitions, not the evidence boundary.
• Architecture, usability, and evidence progress are independent gates. A cleaner module tree alone does not establish product value.