Bo
d043390a0a
Resolves every spellbreaking finding (the blocker + all 13 majors) from the 3.3.0 release-readiness audit ([docs/audits/release-readiness-3.3-2026-07-20.md](docs/audits/release-readiness-3.3-2026-07-20.md), included in this PR). ## Finding → fix map **CLI self-documentation (M1–M3)** - **M1** `ao robot-docs` prescribed removed `ao inject` → line removed from the canonical agent workflow; `inject` added to the removed-command hint table **and** the MIGRATION.md map (drift test `TestRemovedVerbsHaveMigrationRows` enforces the pair). - **M2** `ao config --help` documented ~14 env vars for removed subsystems (RPI/Dream/Council/tiers) → help text and the `--show` env panel pruned to the 5 vars the binary consumes; mirrored list in `internal/config` pruned identically. - **M3** `ao flywheel status` read only legacy `.agents/<section>` while `ao doctor fix` migrates learnings to canonical `.agents/ao/learnings` → new `quality.KnowledgeSectionDirs` dual-roots every knowledge reader (tier counts, new/stale artifacts, retros, health delta, utility, loop metrics, retrievable-citation stats — plus the golden-signals readers `ComputeResearchClosure`/`ComputeReuseConcentration` that the fresh verification pass caught as missed). Sandbox-proven twice: a learning existing only under `.agents/ao/learnings` appears in all metrics, and a research file only under `.agents/ao/research` flips closure from `starved/0` to `unmined/1 orphan`. **Release story (M4–M6)** - **M4** CHANGELOG `[3.3.0]` omitted post-07-17 surfaces → folded in `ao eval` (#921), default-build `ao flywheel`, the PreToolUse policy engine, and the #919 cleanup; date moved to 2026-07-20; `docs/CHANGELOG.md` re-synced (changelog.sync gate green). - **M5** MIGRATION.md attributed `ao eval` to a nonexistent "3.4" → now "returned in 3.3". - **M6** four release surfaces claimed a 50-skill corpus vs 48 everywhere real → all counts now 48 (CHANGELOG ×2, docs/3.3.md, release-notes page ×2). **Install story (M7 — product decision by Bo)** npx first (universal — installs into all coding agents), **plugins for Claude Code/Codex encouraged**, checkout + `ao skills link` as the source-tracked/contributor path; curl installers stay tombstones. Harmonized across README, UPGRADING, install-day2-ops, MIGRATION, 3.3.md, CHANGELOG, the release-notes page, all six installer tombstone messages (`install.sh` + claude/codex/agy/opencode/`codex.ps1`), and the site's CLI page. All "legacy migration-only / not the recommended path" plugin branding removed. **Docs site (B1, M8–M12)** - **B1** generated site CLI page instructed a tombstoned curl installer, nonexistent `ao rpi phased`, and wrong skills dir → `emit_index()` rewritten to the real install menu + a quickstart of commands that exist; semantic loop correctly attributed to skills. - **M8** deploy workflow's `--strict` contradicted mkdocs.yml's declared non-strict policy and aborted the build → flag dropped (lychee + validate-links.sh own link checking). - **M9** site banner said "AgentOps 2.x" → now 3.3. - **M10** ~176 internal files (audits/plans/handoffs/… + TEMP scratch doc) published and dominated search → `exclude_docs` extended; built site verified free of them; search index 4,751 → 2,444 entries. - **M11/M12** newcomer-guide skill links and all six SCHEMAS.md links 404'd on the site → absolute GitHub URLs (resolve on both GitHub and the site). The fresh verification pass found the same class on `docs/contracts/index.md` (nav-listed), `docs/contracts/corpus-learning-seam.md`, `docs/templates/slice-validation.md`, and five `docs/architecture/gas-city-factory.md` links into now-excluded `docs/audits/` — all repointed to absolute GitHub URLs. - Also from the verification pass: robot-docs exit-code table no longer says "bead claimed" (removed concept), and the docs.yml comment now cites the link checker that actually runs (`tests/docs/validate-links.sh` via doc-release checks) instead of lychee. **Skills corpus (M13)** - rch skill instructed 5 nonexistent scripts + 8 nonexistent reference files as recovery steps → pruned to the 7 real references; the wire-level `printf | rch` probe replaces the phantom `protocol_test.sh`; codex twin regenerated (parity gates green). ## Verification - `go vet` clean; **full test suite 60/60 packages pass** (includes the new-shape flywheel/quality/config tests and the inject↔MIGRATION drift test). - **`ao gate check --full --scope worktree`: 67/67 pass, 0 warnings** over this exact change set (changelog sync, shellcheck on the edited installer, skill mesh + codex parity, manifests/schema/triggers, provenance chain). - `scripts/regen-all.sh --check`: all generated projections current. - Rebuilt binary re-exercised: `robot-docs` clean, `ao inject` tombstone live, config help clean, flywheel sandbox proof above. - `mkdocs build` exit 0; warnings 84 → 46 (remainder is the accepted out-of-tree-link class per mkdocs.yml's declared policy). - Fresh-context adversarial verification workflow over all four fix groups (results in session log). ## Known residuals (deliberately out of scope) - `ao config models` subcommand still renders tier config (its two env vars ARE consumed; `COUNCIL_CLAUDE_MODEL` in its display list is not — follow-up). - Same-class single-rooted readers off the flywheel path: `learning.coherence` gate glob (`.agents/learnings/**` only), `quality.CountConstraints`, config `Paths` defaults feeding eval sandbox deny-lists. - `scripts/docs-build.sh` still uses `--strict` with its own allowlist (not wired into any workflow or gate). - Audit minors 1–8 (rc fallback version string, `config --show` legacy-fallback display, `ao init` vs doctor layout, doctor's `ao beads dir` hint, dead `tracker:` key in the example config, doc-skill phantom scripts, ROADMAP dead links, documentation-index root links).
2.9 KiB
AgentOps 3.3: The Cathedral Cut
AgentOps 3.2 tried to make validation inescapable by owning the path around it.
That turned a useful trust boundary into a control plane: retries, queues, work
claims, Git admission, landing, closure, budgets, and delivery accumulated around
one fresh-context review. The result was correct-looking gridlock. Validation
often took longer than implementation, and moving main repeatedly invalidated
expensive proof.
Version 3.3 removes that control plane.
RPI -> Plan -> Implement -> fresh Validate -> durable verdict -> report and stop
What AgentOps owns
- one behavior with explicit normal and edge acceptance;
- one bounded implementation experiment;
- deterministic identity for the exact candidate content;
- one independent semantic judgment from fresh context;
- one durable, content-addressed verdict with checked and unchecked scope.
What the caller owns
The caller decides whether to revise, retry, re-plan, schedule, assign, commit, push, merge, release, or abandon the candidate. Existing repository Git and CI policy remains authoritative. Optional councils, genies, NTM, Agent Mail, Gas City, and swarm adapters may help, but none can change the core sequence or strengthen a verdict.
Skills
The load-bearing core is rpi, plan, implement, and validate. learn is an
optional later analysis of verdict collections. Discovery, behavior-first
planning, and goal design were folded into Plan. Crank and controller/delivery
skills were removed. Canonical mortem names are premortem and postmortem.
The corpus is 48 metadata-owned skills; beyond the core and learn, the rest
are specialist strategies and optional adapters. Their metadata is the source
for the generated registry, router, graph, counts, and runtime projections. The release audit reads every canonical SKILL.md and
runs the strict deep auditor over the entire corpus.
CLI
The retained ao CLI supplies ordinary deterministic checks, inspection,
generic provenance records, goal measurement, session handoff, and skill
discovery/linking. Removed lifecycle commands have inert, non-mutating
tombstones for this release. Semantic validation lives in the Validate skill;
ao gate check proves deterministic repository facts only.
Installation
Three supported paths:
npx skills add boshu2/agentops --all -g— universal; installs the skills into all your coding agents at once.- Runtime plugins for Claude Code and Codex — managed bundles that update with the release.
- One canonical checkout plus
ao skills link— source-tracked symlinks for users who edit skills or contribute. The command links that checkout into the portable skill root and every detected runtime without overwriting foreign skills.
The 3.x curl installer scripts are refusing tombstones. See Install and day-2 operations and the migration guide.