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).
Ship the Cathedral Cut on the 3.x line with the intentional semver deviation documented for v3.3.0. Includes the complete release rebadge, release-gate artifacts, removed-command tombstones, and a legacy config read fallback that preserves existing settings when saving the new canonical path.\n\nValidated by the full local Go/release suite and all required GitHub checks on head 78027b009c.
Retire the 3.x plugin curl/PowerShell installers as tombstones, delete the
plugin-cache helpers, and rewire CI/doctor/conformance onto the canonical
checkout + ao skills link path. Keep install-bd and the opt-in operator scripts.
Co-authored-by: Cursor <cursoragent@cursor.com>
## Why
Every PR since #906 has run red on the same 5 checks (correctness
ubuntu+windows, go-gate-shadow, security, summary) — #906 and #907 both
merged with identical red sets. A permanently-red backstop is worse than
none: a real regression is invisible in the noise. This PR fixes every
class and makes green the expected state again.
## What (three commits)
**Wave 1 — the four red check classes** (each verified by running the CI
job's own command):
- **correctness/bats (138 CI-only failures, ~6 env mismatches)**: pawl
verdict-edge fail-closed fires without a trusted `ao` on PATH →
`PAWL_EDGE_FAIL_OPEN=1` on the bats step (the 3 fail-closed regression
suites opt back out); gtimeout probe crashing setup() on Linux; gawk \\"
bracket-expression warning corrupting jq assertions; ripgrep missing on
runners; teardown/skip-path exit codes; taxonomy fixture missing the
now-required observations field.
- **go-gate-shadow (8 full-gate failures → 0)**: #906 landed without a
heal/regen pass — pre/post-mortem pointer skills missing
`hexagonal_role`; codex twins/hashes drift; shrink-only grandfather
lists; evolve SKILL.md referencing 3 deleted scripts;
@covered-by/allowlist conflicts; 3 go.lint findings.
- **security (BLOCKED_HIGH → PASS)**: 3 false positives suppressed
per-finding with justification (gosec G122 on the dev-time arch checker;
2 semgrep mis-traces).
- **correctness/windows**: tests set HOME but Go os.UserHomeDir() reads
USERPROFILE on Windows → cross-platform setHome helper.
**Wave 2 — 18 residual bats failures across 13 files**, each first
proven identical on pristine origin/main (differential run) before
fixing. Content drift (README golden-path literal, discovery references,
bootstrap↔install-bd wiring, pawl-review reachability via council, rpi
helper-rung tokens), validator regressions (validate-codex-rpi-contract
resolver routing, em-loop labels, goal-design fixture), and stale tests
updated only where provably behind a deliberate change (catalog
schema_version pin 1→2, SHA-pinned action regex, retired perf scenario,
drained dangler pin 2→0, tagged-ao test build).
**Commit 3**: the `ao skills unlink` train that landed on main mid-work
re-reddened security with the same semgrep value-struct FP — suppressed
like its skills_link sibling.
## Verification (rebased onto current main tip)
- `ao gate check --full`: **92/93 pass, 0 fail** (1 expected AP7 skip)
- `security-gate.sh --mode quick`: **PASS**
- `go vet` clean; **11,878 Go tests green** (149 packages)
- All 13 wave-2 bats suites **0 not-ok**; CI-sim (no-ao PATH) bats clean
on wave-1 suites
- Windows fix verified via GOOS=windows build+vet (needs the
windows-latest job for final confirmation)
**Acceptance: this PR's own validate.yml run going green.**
Bead: age-htrqp
---------
Co-authored-by: boshu <241868352+boshu2@users.noreply.github.com>
Installers now prove their claims before printing success: the installed
skill directory count, the manifest count `ao doctor` reads, and the
recorded metadata skill_count must all agree, the config-enable entry
must be present, and a sentinel skill must be readable. On any mismatch
the installer exits nonzero naming the delta instead of declaring
victory over a broken state.
Root cause of the audit's "install metadata says 66 skills but manifest
says 62": install-codex-plugin.sh counted on-disk SKILL.md directories
(66) and wrote that into install metadata, while `ao doctor`
(ReadCodexManifestSkillCount) reads the manifest's package_count and
falls back to len(skills[]) = 62 (implementation rows only) when
package_count is absent/stale. The two numbers came from independent
sources with nothing reconciling them. The new self-test computes the
count doctor will use (package_count, else len(skills[])) and refuses to
report success unless disk == manifest == metadata — closing the gap at
the true source rather than papering over it.
- install-codex-plugin.sh: manifest_doctor_count() mirrors doctor;
selftest_codex_plugin() enforces the three-way count identity + config
+ sentinel; success line -> "Verify it worked: restart Codex, /plan".
- install-opencode.sh: AGENTOPS_BUNDLE_ROOT local-source mode (offline);
self-test on linked-vs-source count + plugin link + sentinel.
- install.sh: AGENTOPS_BUNDLE_ROOT local-source mode; orchestrator
self-test tail; fix empty-array expansion under set -u on bash 3.2
(reachable now that local-source mode runs this path offline).
- install-agy.sh: self-test on plugin registration + sentinel skill.
- tests/scripts/installer-selftest.bats: offline coverage incl. the
seeded 66-vs-62 stale-manifest fixture that must fail, and a legacy
no-package_count-but-consistent manifest that must pass (doctor parity).
.ps1 parity (install-codex.ps1/install-ao.ps1) deferred: same latent
divergence exists but no pwsh on the dev host to verify; shipping
untested Windows installer code would undercut the first-run-trust goal.
Swarm: 8 tasks across 2 waves, TDD on all Go changes.
HIGH fixes:
- rpi serve --run-id now matches 12-hex IDs (was misclassifying as goals)
- cherry-pick-wave.sh: pattern validation + prefix-scoped rm fallback
- -o flag contract: rename local --output to --output-dir/--output-file
on defrag, memory, context_assemble (stops shadowing root format flag)
MEDIUM fixes:
- defrag --json now emits JSON (was printing text unconditionally)
- Remove dead promote-anti-patterns from doctor suggestions
- Pin install scripts to tagged releases instead of mutable main
- Add ao doctor + skill-lint CI jobs to validate.yml
- Add learning coherence quality gate script
Process:
- Drain 7 unconsumed next-work.jsonl entries (0% → 100% resolution)
- 192 lines of new tests (TDD: test-first across all Go changes)
Bo