Skip to content

v0.3 adoption plan — external-review response (2026-07-17)

Scope: the next two releases (0.3.0a4 = UX/adoption, 0.3.0b1 = pilot evidence). Every item below traces to the 2026-07-17 external review of the 0.3.0a3 repository. Grounding was measured against the live CLI, not impressions; measured facts are marked [measured].

R3 — Human-readable aoi status (0.3.0a4, highest value/effort ratio)

[measured] aoi status today prints a raw JSON object (chief lease fields first). An operator or coding agent scanning for "who owns what, what is stuck" gets neither.

  • Default output becomes a compact human summary per active task: owner, current blocker (open needs-user / stale checkpoint / expired claims), last recorded evidence (category + boundary first line), declared next action, and open risks. One task = ~6 lines.
  • --json keeps the exact current payload (no schema change, no consumer breakage). INDEX.md rendering reuses the same summarizer.
  • Acceptance: a new user can answer "who owns X / why is it stuck / what happens next" from bare aoi status in one screen.

R4 — Reduce ceremony on the mini path (0.3.0a4)

[measured] start-mini requires 12 arguments; finish-mini requires 4. The three-interaction promise (start → work → finish) holds for CLI call count but each call is a wall of required prose, and two known gates silently escalate a mini task into full ceremony:

  1. Exact-command hash binding trips on byte trivia. The ARISE audit measured 4 of 81 packets cancelled purely on trailing-newline / bytes-vs-string mismatches in exact_command binding (part of a 22% ceremony tax). Fix: normalize command text at BOTH bind and verify time (strip trailing whitespace, canonical newline) — one code path, additive.
  2. Checkpoint staleness blocks Stop mid-mini. For an open mini task, the Stop gate should accept the mini's own start metadata as the checkpoint until first material mutation.
  3. Argument diet: derive --token/--intent/--validation defaults from the mini objective when omitted (explicit values always win). Target: start-mini usable with 6 arguments.
  4. Acceptance: a 1–3 file fix completes with start-mini → edits → finish-mini, zero additional lifecycle commands, demonstrated in the quickstart.

R1 — Five-minute quickstart (0.3.0a4, docs + one command)

README's onboarding prompt is agent-first and trust-heavy; there is no page showing before/after states, expected output, and a clean exit.

  • docs/quickstart.md: fresh repo → install (pinned ==0.3.0a4) → aoi codex-init/claude-init → exact expected output blocks → one mini task end to end (using the R4 slim path) → full removal.
  • Removal today is undocumented manual surgery. Add aoi offboard (Chief-fenced): removes the hook wiring it installed, leaves .aoi/ as an inert archive (or --purge-state with explicit confirmation), prints what it removed. Uninstall = aoi offboard + pip uninstall aoi-orgware.
  • Acceptance: a timer run of the quickstart by someone who has never used AOI lands under five minutes, and offboard leaves git status clean.

R5 — Stable pilot pin (0.3.0a4, docs + policy)

  • README/quickstart pin exact versions (aoi-orgware==0.3.0a4) everywhere; no instruction ever says "latest".
  • Declare a support statement in README: pilots pin one version; alphas may change CLI surfaces between releases; CHANGELOG is the upgrade contract. (ARISE precedent: pinned 0.2.1 wheel by commit — document that pattern.)

R2 — Reproducible single-agent vs AOI demo (0.3.0b1, biggest effort)

pilot.py already implements the A/B protocol (VARIANTS = {"single", "aoi"} with paired task groups, environment matching, metrics/telemetry/ questionnaire capture, and refusal of nested projects). What is missing is a public, runnable instance and published numbers.

  • New public repo aoi-pilot-demo: a small, self-contained Python service with a seeded defect set and two scripted tasks (bug-fix, feature+tests).
  • Run the pilot protocol both ways × N seeds; publish wall-time, token spend, rework count, unresolved errors, and human interventions — including the runs where AOI does NOT win. The honesty is the marketing.
  • Gate: do not cite the demo in README until the numbers exist. AOI's own alpha disclaimer ("has not established general superiority") stays until this data says otherwise.

Carried-in fixes (0.3.0a4)

  • Flaky test_chief_contender_waits_behind_acquired_holder ordering (separate fix session already running).
  • Latent defect found by the typing pass: commands/resource.py rollback reads receipt.get("plan").get(...) before the isinstance guard in the same or chain — a receipt missing plan raises AttributeError instead of the intended binding error. Reorder with preserved semantics + test.
  • evidence_artifacts.py reachable-None on archive_member (currently relies on AttributeError→except flow): add the explicit guard the typing pass documented.

Sequencing

  1. 0.3.0a4: R3 → R4 → R1 → R5 + carried-in fixes (each lands with tests; R1 docs last since it demonstrates the R4 slim path).
  2. 0.3.0b1: R2 demo repo + published pilot numbers; first beta tag only after the demo runs reproduce.