## What
Prepares the **v3.3.0** release cut (last shipped tag: `v3.2.0`,
2026-07-03). No tag and no GitHub release are created here — tagging is
gated on the live GC canary and the operator's go.
- **Changelog reframe.** The `[3.3.0]` headline now leads with the
deliberate subtraction of the guardrail cathedral (strict verbose step
contracts, enforcement gates, injection hooks, command tombstones,
retired lifecycle surfaces, the heavy out-of-session orchestration
layer) — removed because that scaffolding degrades frontier-class models
rather than helping them. What remains is the judgment-boundary
membrane: caller-owned intent, one fresh independent validation, durable
verdicts, pinned provenance. Subtraction is git-concrete: `cli/internal`
packages **79 → 43**; reference orchestrator **~29k lines → ~1,300-line
thin pack** (one commit removed 29,418 lines for 1,334).
- **Post-07-17 delta folded in:** Gas City factory pack (preview) —
official checksummed GC/Beads binaries fetched by the installer (no
compile), mayor-driven door (human attach or agent drive via mail/sling)
with heartbeat shepherd, the `using-gc` mayor-orchestration skill +
four-layer visibility doctrine, rig-scoped dispatch intake, three
disclosed upstream v1.3.5 defects (#4586, the cross-store claim fix,
gastownhall/gascity#3985) with the preview→supported promotion criteria,
and plan/premortem ground-truth routing.
- **Version bump:** source fallback `3.3.0-rc → 3.3.0`
(`cli/cmd/ao/main.go`); plugin manifests were already `3.3.0`. Adds a
release-guard test asserting the fallback carries no pre-release marker
(resolves audit minor 1).
- **Release-gate fix:** trimmed the `using-gc` skill description (195 →
117 prose chars) to satisfy the 180-char budget — a blocker that landed
with the GC arc — and regenerated its Codex/Gemini/pack projections.
## Recommended version: **v3.3.0**
`v3.3.0` was an in-progress RC (`main.go` at `3.3.0-rc`, plugin
manifests at `3.3.0`, changelog `[3.3.0]` drafted) that was never
tagged; the GC pack + loop doctrine landed on the RC line. This cut
finalizes it.
## Go / No-Go checklist (deterministic bar:
docs/audits/release-readiness-3.3-2026-07-20.md +
docs/runbooks/release-process.md)
| # | Criterion | Status | Evidence |
|---|---|---|---|
| 1 | `go build ./...` | PASS | exit 0 |
| 2 | `go vet ./...` | PASS | exit 0 |
| 3 | Full Go test suite (`go test ./... -count=1`) | PASS | 63 packages
`ok`, 0 FAIL |
| 4 | Cathedral Cut conformance (`check-cathedral-cut-conformance.py`) |
PASS | "Cathedral Cut conformance: PASS" |
| 5 | Skill-mesh drift (`generate-skill-mesh.py --check`) | PASS | "up
to date (48 skills)" |
| 6 | Derived-artifact drift (`make regen-check`) | PASS | "All
generated projections are current." |
| 7 | Docs + release-doc gate (`make docs-check`) | PASS | CLI ref
current; 395 links, 0 broken; skill count 48; release freeze intact |
| 8 | `ao gate check --full` | PASS* | 66/67 pass. Sole fail =
`workflow.install-drift`, a worktree-local symlink artifact (tracked
`workflows/` is byte-identical to origin/main; passes in a clean CI
clone — the audit's 67/67) |
| 9 | Fast release gate (`ci-local-release.sh --quick`) | PASS | "LOCAL
CI QUICK SANITY PASSED": 44/44 install-surface smoke, 33/33 release
smoke, init smoke |
| 10 | Skill token budgets / lint | PASS | 100 budgets pass (fixed
`using-gc` 195→117 prose) |
| 11 | Install story smoke | PASS | README/MIGRATION document `ao skills
link`; all 6 curl installers are refusing tombstones; `ao version` runs;
npx-first |
| 12 | Plugin manifest ↔ corpus parity | PASS | manifests carry 48
skills, 0 drift |
| 13 | Version bump applied to owners | PASS | `main.go` 3.3.0-rc→3.3.0;
manifests already 3.3.0 |
| 14 | Changelog updated + synced | PASS | `CHANGELOG.md` ==
`docs/CHANGELOG.md` (changelog.sync gate) |
| 15 | Command/test pairing gate | PASS | main.go bump paired with
`version_test.go` release-guard test |
| 16 | Full release gate (`ci-local-release.sh`: race + security + SBOM
+ readiness) | PASS | "LOCAL CI PASSED [102s]"; release-artifact
manifest resolved `v3.3.0` |
\* `workflow.install-drift` is an environment artifact of running the
gate inside a nested worktree whose `.claude/workflows/` symlinks
resolve to the primary checkout. It is not release content: `git diff
origin/main -- workflows/` is empty, and the check passes in a fresh CI
checkout (audit reported 67/67 at origin/main).
## Operator items (require a human or a live tag — NOT attempted here)
- **Live GC canary** on the next official Gas City pin — the
preview→supported promotion gate.
- **Git tag `v3.3.0` + goreleaser publish** — gated on the canary and
operator go.
- **Docs-site publish** (mkdocs pipeline) — separate from this cut.
No tag. No release.
## Outcome
Ships AgentOps 3.3 as a thin native Gas City pack and removes the
accidental second orchestration control plane.
- Removes the custom GC delivery command/package, packet/schema family,
feeder/program engine, reducer/order, reliability registry, Beads
capability mirror, and fork-baseline runtime checks (about 29k deleted
lines).
- Retains six bounded adapters for pinned toolchain materialization,
clean bootstrap, native sling/status/doctor invocation, bead-isolated
worktrees, moving-main PR delivery, and teardown.
- Uses official Gas City and Beads behavior as the state owners, with
required OTEL configuration.
- Preserves Fable Mayor/Refiner, Sol-high planning and fresh validation,
Terra-high default implementation, Opus-medium overflow, and
support-only Luna.
- Supports automatic Refiner merge after hosted CI or a manual-review
toggle without locking `main`.
## Evidence
- Exact official GC: `8ffc009ded781a2ada2077f3a29bd712b2def0bf`
- Exact official BD: `8e4e59d39f3459a43cf21a3236a13eca4dd874f7`
- Full pinned native boundary: 9/9 passed in 114.047s
- Exact source-bead route replay: passed in 98.051s
- Release replay: manifest integrity, thin tests and both pack lints,
generated projections, contract compatibility, Bats contract,
ShellCheck, test-removal ratchet, and `go test ./...` all passed
- Fresh independent semantic verdict: PASS (Sol-high)
- Exact delivered head: `e805f0e26ce21c2eae9e720f57fff2a705f3185b`
- Subject manifest:
`8554d065076f70d0e639ca353409d2a75dca7ac01e4cb65cb4a118e98c0770fc`
- Verdict:
`3f89376b675de854832f38b46ccfa7ad7ca54079ffde578769c33e1f118c68c1`
## Release boundary
After this PR merges, the release qualification runs one fresh mixed
Terra/Opus canary from merged `main`, with at most one external repair
and one terminal retry. No live city repairs itself.
The only known local fast-gate exception is `workflow.install-drift`:
the installed workflow symlink resolves to the separate dirty primary
checkout, outside this candidate. All candidate-owned gates passed.
## Summary
- bind the GC 3.3 bead-native workflow: Fable Mayor, fresh Sol-high plan
and validation, Terra-high default or Opus-medium overflow
implementation, Luna support-only
- add the bounded one-shot graph feeder, strict packet/worktree
identity, semantic terminalization, and model-free protected delivery
sweep
- make official Gas City v1.3.5 plus Beads v1.1.0 bootstrap repeatable,
disable unstable event propulsion/hooks, and prove quiescent teardown
## Reliability boundaries
- no Gas City self-repair loop, daemon, private scheduler, model
fallback, or main mutex
- semantic completion is independent of delivery; protected
PR/CI/rebase/merge is deterministic and moving-main aware
- event hooks are disabled because 3.3 uses explicit program admission
and cooldown delivery; native controller bead observation remains active
## Evidence
- full local release CI PASS at
.agents/releases/local-ci/20260722T113355Z
- two pristine standalone-clone cycles with official GC v1.3.5 8ffc009d
and BD v1.1.0 8e4e59d: repeat bootstrap, exact rig Dolt context, absent
event hooks, bounded events, enabled sealed delivery, and delayed
zero-process teardown
- fresh independent Sol-high pre-delivery binding PASS over exact head
e8c1253b40
- binding verdict SHA-256:
4f8d81811cd5b2eb35159c98159db2f8917d3ef54167f3c0d59d8378de14b2d1
## Tracker
Beads: age-gc-scope-failclosed-release-gktia.2
The one bounded mixed-provider live canary remains a post-merge release
gate; this PR does not claim final 3.3 release readiness before that
proof.
## Summary
- replace the unreachable Python factory lifecycle with an optional
typed Go delivery reducer
- make Beads the delivery lifecycle authority with deterministic
moving-main successor epochs
- add native Git/worktree, PR, hosted-check, auto-merge, landing, and
cold-replay boundaries
- retire obsolete v1 role/factory schemas and preserve the pinned
historical capability harness
## Validation
- fresh Sol-high PASS over exact 43-path manifest
ec6a2a4bf0b180782411b1ae4afd4a2ad8384129ff037ce8c119480317626b02
- go test ./...
- go test -race ./internal/gcadapter/delivery
- go vet ./...
- scripts/check-gc-executor.sh
- GC 3.3 schema, migration, provenance, factory-doctor, and bootstrap
gates
Bead: age-gc-scope-failclosed-release-gktia.1
## Outcome
Adds the bounded GC33-6 delivery slice outside core ao: a separately
built crash-only reducer, strict admission certificate binding,
immutable handoff and branch/PR receipts, native graph.v2 formulas,
one-step disabled Order glue, and one centralized stock claim wrapper.
Semantic bead: ag-agentops-33-gc-refinery-4km81.7 (closed after
independent validation).
Binding PASS:
d3ac5a566e0f5197814e2dbcf04d0540849f58636ed8bb49a0faca7d6af94639 over
manifest
155a089b4b461bda61a7f1ad1987c66f5755ac7c5628aa648e70740be2580a5a.
## Verification
- Full cli Go suite: PASS (2,887 tests)
- Focused race-enabled reducer suite: PASS
- GC factory/executor Python contracts: PASS
- Full executor gate: PASS (123 Python + 25 Bats)
- Exact official GC v1.3.5 pack lint and no-start discovery: PASS
- Cold replay: exactly one delivery, branch, and PR; six emitted
artifacts validate against shipped schemas
- Production Go surface: 922 lines, under 3,000 tripwire
## Boundaries
No ao command, core port, default install, live city, real
Git/forge/CI/merge adapter, daemon, scheduler, or factory.py import.
Real adapters and delivery completion remain GC33-7.
Walks every registered command Short/Long/Example plus quick-start printed
output, extracts advertised "ao ..." strings, and resolves each against the
assembled rootCmd (aliases included; Example fields get full group-descent).
Guards the defect class the 3.3 release audit fixed by hand: user-facing
output advertising a retired command.
Workflows get the skills treatment (operator decision): canonical source
in the product tree, installed by a product verb, Claude-only labeled as
such.
**What moves:** all seven Claude workflow scripts + README migrate from
force-added exceptions inside the gitignored `.claude/` to a tracked
top-level `workflows/` (sibling of `skills/`) — the four existing
conveyors plus `audit-dimensions`, `verify-fixes`, `implement-wave`:
three thin, args-parameterized orchestration conveyors extracted from
this session's hand-rolled waves, contract-reviewed, and smoke-proven
through the real Workflow runtime (the smoke caught two contract gaps
static review could not: an `export default` wrapper the runtime never
invokes, and args arriving as a JSON string — both fixed, string-args
tolerance now built in).
**New verb:** `ao workflows link` / `unlink` mirror `ao skills link`
semantics — dry-run `--json`, refuse to replace real files or foreign
links, unlink only checkout-owned links — targeting the project-local
`.claude/workflows/` where Claude Code resolves named workflows
(`--into` overrides). Checkout identity reuses the skillsapp marker
discipline, fail-closed. Claude-only runtime adapter, same doctrine as
the Codex-only `skills-codex/`.
**Legacy surfaces repointed:** `install-workflows.sh` (user-global $HOME
installer), `check-workflow-drift.sh` + gate comment,
`check-bdd-foundry-markers.sh`; spine allowlist + YAML-probe excuse +
go-cli.md spine region gain the workflows group; COMMANDS.md,
cli-surface projections, and surface-count fixture regenerated; new
tests carry per-command git-env scrubbing (test-isolation ratchet back
at baseline).
**Built BY the workflow being canonized** — `implement-wave`
orchestrated its own canonization: two disjoint-ownership lanes plus a
seam-checking verifier that ran the real binary's link → resolve →
unlink cycle in the live tree (both lanes RESOLVED). The lanes correctly
*refused* to self-approve their command into the spine invariants and
handed integration three flagged edits instead.
**Expected local gate note:** `workflow.install-drift` correctly FAILS
on machines whose user-global `~/.claude/workflows` links still point at
the old location — that is the transition it exists to catch. CI stays
green (absent→skip). **Post-merge operator step:** `cd ~/dev/agentops &&
git pull && bash scripts/install-workflows.sh`.
**Verified:** full suite 63/63 pkgs; golangci-lint clean; `gate check
--full` over this range = 66/67 with only the documented install-drift
environment finding; workflows smoke-run evidence in session logs.
Wave 4 (residue) of the new-user happy-path arc. Three scoped
implementer lanes + fresh adversarial verifier (4 RESOLVED; 1 INCOMPLETE
= stale generated projections, closed in integration).
**Doctor**: the dev-version detector now reuses the Binary Freshness
resolution — a from-source build matching its checkout is healthy (a
novice building from source can finally see `ao doctor` exit 0);
findings fire only on genuine drift, shadowed duplicate `ao` binaries,
or an informational from-source note outside any checkout. `ao doctor
diff` gains `--only` so the fix-plan preview can be scoped the way
remediation text implies.
**Config**: the dead `ao config models` surface is removed end-to-end
(lane re-verified zero consumers before deleting; `--show` proven
byte-identical before/after; removed-child hint + MIGRATION row;
existing `models:` config sections still parse and are ignored).
**Dual-root stragglers**: learning-coherence gate globs,
`quality.CountConstraints`, and the eval sandbox corpus deny-list now
cover canonical `.agents/ao/<section>` alongside legacy roots.
**Doc-link hygiene**: the strict docs-link backstop's allowlist was 100%
stale (53/53 entries referenced Cathedral-Cut-deleted docs) — refreshed
to 10 verified accepted-class entries; ROADMAP dead links fixed;
documentation-index generator emits GitHub URLs for repo-root targets;
doc-skill references instruct only shipped scripts; codex twins +
CLI-surface projections + surface-count fixture regenerated.
**Deferred by design**: the `3.3.0-rc` fallback version bump belongs
inside the v3.3.0 tag-cut commit.
**Verified**: full suite 61/61 pkgs (2825 tests); golangci-lint clean;
`ao gate check --full` 67/67 over this range; Test-Removal-Reason
trailer covers the 6 deliberately deleted models tests.
Wave 2 of the new-user happy-path fixes (fresh-eyes novice test).
**Edge 4 — doctor sub-surfaces contradicted each other.** Remediation,
`next_steps`, and robot-triage's `recommended_command` now instruct
`--fix` only when a fixer can actually act — non-fixable findings name
their real manual action (including the detect-only bridges class the
verifier caught as the same lie one level up). `ao doctor health`
reports every severity bucket present (it omitted P1 — the worst
actually present). `ao doctor diff` renders an explicit read-only fix
plan (would auto-fix vs manual action) instead of a findings copy. `ao
doctor explain` is now a superset of the finding's triage entry.
**Edge 6 — `ao config --show` rendered config for commands that don't
exist.** `rpi.*` and `dream.*` no longer serialize in human or JSON
output (struct fields retained `json:"-"` pending a follow-up removal
once nothing references them). `AGENTOPS_NO_SC` had zero behavioral
consumers (evidence: rg over all non-test cli/ — only config
plumbing/display) — undocumented and removed from the env panel; the
field stays parseable so existing config files don't error.
**Edge 8 — legacy-config gaslighting.** With only
`~/.agentops/config.yaml` present, `--show` used to print the
deprecation warning and then claim the new path was "(not found)" and
values came "(from flag)". It now shows the actually-read path labeled
"(deprecated location)" with correct attribution.
**Edge 7 — `ao beads` bare error.** The whole pruned 3.2 bookkeeping
family gets point-of-failure migration hints; a new guard test proves no
hinted verb is a live command (the `eval` trap: pruned in 3.2, returned
live in 3.3).
**Process:** three scoped implementers (disjoint files) + fresh
adversarial verifier. The verifier refuted two lanes as incomplete
(recommended-command layer, stale cmd/ao config tests asserting the old
defect) — closed in integration before this PR.
**Verified:** full suite 61/61 pkgs; golangci-lint clean; `ao gate check
--full` 67/67 over this range; per-fix RED→GREEN sandbox repros in the
workflow logs.
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).
Collapse the four drifted cmd/ao host-seam shapes into one shared
clicontract.HostOptions consumed by all 17 command modules; delete the
positional-func and bespoke-struct seams and the doctor GlobalOptions bundle.
- clicontract/host.go: single HostOptions union (OutputMode/Verbose/Verbosef/
DryRun/ProjectRoot/GoalsPath/LedgerPath/Version/Now/EnrichFlagErr), one shared
WriteJSON (byte-identical to the three deleted copies), one shared ExitError
(Label field preserves doctor's stderr surfacing; gate stays silent).
- config_module.go + doctor_module.go: package-level module/service singletons
-> newConfigCommand()/newDoctorCommand() constructors; 7 allowlist rows removed.
- carveout_regression_test.go: three AST drift guards (shared seam type / no
direct host effects / no module-service singleton vars), each RED-proven.
- docs/architecture/go-cli.md: document the intentional two-tier shape (5 full
hexagonal, 12 app-seam); drop the stale opportunistic-extraction sentence.
Zero behavior change: ao -o json capabilities byte-identical; full suite +
-shuffle=on -count=2 green; 0 lint issues; gate check --full 67/67.
Finish line of the cmd/ao carve-out arc (age-a-plus-report-card-ieyp2.14).
Changes NO command behavior — tests, guard, and allowlist only.
- Add TestPackageVarsAreAllowlisted (carveout_regression_test.go): parses every
cmd/ao non-test .go file with go/ast and fails on any package-level var that is
not on testdata/package-var-allowlist.json, and on any stale allowlist entry.
Keyed by name+file. Locks the finish-line state: after 12 family carves the only
legitimate package globals are the root spine + its 5 persistent-flag targets,
host-resident module/command wiring, const-like data maps, the ldflags version
string, and one documented test seam (testProjectDir).
- testdata/package-var-allowlist.json: 24 entries, each with a one-line reason.
- Bounded-purpose comments on executeCommand and resetCommandState documenting
that they save/restore ONLY still-existing root spine state — carved families
own their flag state constructor-scoped in internal/commands/<family>.
No dead vars found to delete: all 24 cmd/ao package vars are live. Harness was
already root-only after prior waves (saves only dryRun/verbose/output/jsonFlag/
cfgFile). RED proof: a scratch `var sneaky string` in group_json.go trips the new
guard; removed before commit.
The command module is a thin Cobra presentation seam; internal/flywheelapp owns
the filesystem and clock effects and preserves the internal/evidence
(ratchet.LoadCitations) dependency. flywheel status/compare surface and
capabilities are byte-identical.
Move the version command out of package main into internal/commands/version.
version reads only build/runtime metadata (a pure effect), so it needs no app
seam; the build-time version string and the global -o/--output mode are host
seams injected by the composition. Unlike the other W3 families, version
carries a real CommandContract that newVersionCommand attaches to the command
tree, so the capabilities surface is byte-preserved.
The build-time `version` string var stays in package main (the ldflags target
`main.version`, shared by capabilities, doctor, and rootCmd.Version). The
command-behavior tests move to the module (constructing it directly); the
root-wiring tests (`version` var default, root registration, `ao --version`
flag) stay in package main because the module does not own that wiring.
Test-Removal-Reason: TestVersion_CommandExists removed; its Use/GroupID
assertions are preserved as version module TestModule_CommandAttributes.
Test-Removal-Reason: TestVersion_DevVersionDefault removed; it duplicated the
version-string assertion now covered by version module
TestVersion_ExecuteOutputContainsVersionString.
Move the init command out of package main into internal/commands/init,
delegating the working-directory resolution and directory creation to the new
internal/initapp seam. The dry-run selection is a host seam injected by the
composition from the global --dry-run flag; the module performs no direct
filesystem effect.
Move the demo command out of package main into internal/commands/demo. Demo
renders static explanatory text and performs no effect, so it needs no app
seam; the render helpers and constructor-scoped --quick/--concepts flags live
in the module. demoQuick and demoConcepts package globals die; the shared
resetCommandState test helper drops its references to them (cobra flag reset
still covers the live command instance).
Move the session evidence commands (bootstrap, rehydrate) out of package
main into internal/commands/session, delegating filesystem effects to the
new internal/sessionapp seam. The session parent command now lives in the
module; the optional `ao session handoff` writer stays in package main and
is attached to the module-built parent by newSessionCommand.
sessionBootstrapJSON and rehydrateJSON package globals die; flag state is
constructor-scoped in the module. The combined
TestHandoffAndRehydratePreserveCallerTextWithoutLifecycleState is split: the
handoff-writer assertions stay in cmd/ao as
TestHandoffPreservesCallerTextWithoutLifecycleState; the rehydrate read side
moves to the module as TestRehydrateReadsCallerAuthoredBrief plus the
preserved TestRehydrateJSONEmptyStateEmitsEmptyObject and
TestSessionBootstrapOnlyReportsLocalOrientation.
Test-Removal-Reason: TestHandoffAndRehydratePreserveCallerTextWithoutLifecycleState removed; its handoff-writer coverage is preserved in cmd/ao and its rehydrate coverage relocated to the session module (net +2 tests).
Remove fully-dead Go CLI packages and orphan files per the independently
validated keep/delete/extract manifest (docs/audits/gocli-dead-weight-manifest-2026-07-19.md).
D1 already extracted the two live slices (constraint-index -> internal/constraintindex,
RedactBytes -> internal/redact), leaving internal/search and internal/llm as pure
dead remainder with zero production importers.
Deleted whole packages: internal/search, internal/llm, internal/notebook
(sole importer was search/inject_run.go), internal/reviewerhealth,
internal/adapters/reviewerhealth (both reachable only via the orphan
cmd/ao/reviewer_health_composition.go), internal/canon and internal/vibecheck
(empty-package TestMain husks).
Deleted orphan cmd/ao helper files: reviewer_health_composition.go,
advertised_commands.go, shell_quote.go, beads_json_compat.go, template_detect.go,
federation.go (each entry symbol appeared in exactly one file; no cobra command
wired; command surface projections regenerate unchanged).
Deleted the 12 dead internal/ports groups (agent_mail, ci_status, citation,
context_compiler, corpus_reader, corpus_writer, finding_compiler dead portion +
inmemory_finding_compiler, finding_recurrence, freshness_policy, harness, llm.go,
wiki_index) with zero external ports.X references. finding_compiler.go is a
PARTIAL keep: DetectorReplayResult and DetectorPrecisionEvidence stay (the
Precision field type forces the transitive keep; DetectorReplayResult is consumed
by the surviving constraint-index slice). gate_runner.go, inmemory_gate_runner.go,
frontmatter_codec.go, and doc.go are untouched keeps.
EXCLUDED (live, do not delete): internal/evidence + the flywheel compute block,
live via the aliased import ratchet "…/internal/evidence" in flywheel_metrics.go.
Regenerated command-surface projections (cli/docs/COMMANDS.md,
docs/cli-surface.{json,md}, evals/agentops-core/cli-command-surface-matrix.json,
evals cli-command-surface-smoke.sh) via their owning commands
(generate-cli-reference.sh, regen-command-surfaces.sh,
check-cmdao-surface-parity.sh --write-surface); no drift — the deleted files
carried no command surface.
Pruned stale FILENAME-pinned entries (deleted files only, list-shrinks-only) from
scripts/.atomic-write-grandfather (llm/review.go, llm/session_writer.go,
search/findings_ops.go) and scripts/.jsonl-scanner-grandfather (notebook/notebook.go,
search/{index,learnings,search_cass,sessions}.go).
go build ./... && go vet ./... && go test ./... green (2587 tests).
go list -deps ./cmd/... contains none of the deleted packages.
ao gate check --full: 67 checks, 67 pass (after ratchet-baseline pruning).
Test-Removal-Reason: Every deleted *_test.go file was the test of code deleted in this same commit as dead weight per the validated dead-weight manifest (no live production consumer). Covers all removed tests under internal/search, internal/llm, internal/notebook, internal/reviewerhealth, internal/adapters/reviewerhealth, internal/canon, internal/vibecheck, internal/ports (the 12 dead groups + inmemory_finding_compiler + finding_compiler_shadow), and cmd/ao (template_detect, federation). No behavioral test coverage was lost — the subjects under test no longer exist.
Follow-ups on the bead-native Gas City factory (#917) plus the durable
fix for the recurring core.bare corruption class
(age-cmdao-core-bare-pollution-ek8v, recurred 2026-07-18).
## GC factory hardening (7 commits)
- crash-replayable bead transitions; program/refinery recovery
reconciliation
- ordered rejection recovery; rescope fenced on source closure
- guarded direct rescope dispatch and successor reduction
- ship the managed Gas City template
## core.bare / git-env test isolation
- New `cli/internal/testsupport.ScrubGitDiscoveryEnv()` called from
`TestMain` in all 11 packages whose tests shell out to git (cmd/ao,
adapters/gate, archcheck, canon, doctor, eval, gates, goals, paths,
quality, vibecheck). Mechanism reproduced: hook-injected `GIT_DIR` at a
linked worktree gitdir redirects fixture `git init` into the SHARED
.git/config (`core.bare=true`). Complements #922 (per-helper scrubs +
hygiene gate) with package-wide process-level scrubbing.
- Unit tests pin the scrub behavior and the var list; convention
documented in both go.md standards (codex twin regenerated).
- Verified under a hostile hook-shaped env against a decoy repo: suites
green, decoy and real repo untouched.
## Merge reconciliation
- Adopted main's hermetic `aoBinary` (build-from-source flag matrix;
supersedes the equivalent fix made independently here).
- Repaired the auto-merge-corrupted
`skills-codex/.agentops-manifest.json` by reset + `regen-all.sh` (check
passes clean).
Full `go test ./...`: 49 packages ok, rc=0.
Registers the fully-built-but-never-wired eval module into the CLI spine
and repairs its one real instrument bug. Three commits, RPI-shaped: wire
+ fix, drift guards + docs, fixture counts.
## What
- **`ao eval` joins the spine** (cmd/ao/eval_composition.go):
deterministic suite runs, run-record
compare/baseline/scorecard/coverage, locked Tasks, holdout scenarios,
suite A/B verdicts with power-derived n-required, and the holdout-safe
Outcomes projection. This is the operating contract's *Learn* seat — a
read/measure consumer of evidence. It reports numbers and owns no retry,
scheduling, promotion, or lifecycle authority. The retired Aliases/Bench
seats stay nil and their subcommands are omitted.
- **Instrument bug fixed**: both scenario-ab arms were corpus-denied at
runtime — the with-gold treatment was only a prompt injection through
the retired `ao lookup`, so the A/B silently guaranteed a zero delta.
Treatment is now environment-shaped: the with-gold arm runs with the
corpus readable, the control arm stays sandbox-confined (the fail-closed
empty-deny guard is untouched), and judges are always corpus-denied.
- **Schema drift guards**: a run record persisted by the production
writer must validate against eval-run.v1.schema.json (and the minimal
suite against eval-suite.v1.schema.json) — closing the same silent-fork
class the verdict.v2 golden corpus closed.
- **Hermetic test builds hardened**: keep the real HOME's Go caches
(TestMain isolation was forcing module re-downloads) and skip VCS
stamping.
- docs/architecture/go-cli.md gains the eval section; MIGRATION.md notes
`ao eval`'s return; COMMANDS.md, cli-surface, and surface counts
regenerated; new leaves carry honest allowlist reasons; new cmd/ao L2
tests drive eval run/compare/help through the full production wiring.
## Evidence
- Full cli suite 2,801 green; race green on cmd/ao + the eval island;
vet clean
- Full-tier gate: 65/66 on the penultimate commit; the single failure
(surface counts) is the final fixture commit, re-verified PASS
standalone — no other check reads those fixtures
- Fresh independent validation (Codex, frozen subject 86022a3c6, clean
tree at start and end): **OVERALL PASS**, 6/6 — including a live
end-to-end `ao eval run` producing a passing run record
- Rubric-relocation decision honored: true holdout rubrics live in the
external measurement register; the repo keeps only leak-guarded
projections
Fixes the three gremlins observed 2026-07-18 (bead
age-gate-scripts-worktree-gitdir-p62wo):
1. **Gate scripts broke under hook env from linked worktrees** (#919
regression): new scripts/lib/repo-root.sh (GIT_*-scrubbed resolution,
BASH_SOURCE anchor, worktree-correct) swept across 32 scripts. Proof:
this PR's own push ran the pre-push gates from a linked worktree and
passed.
2. **core.bare=true recurrence**: mechanism proven (leaked GIT_DIR +
no-arg git init --bare rewrites the SHARED config); writer traced with
high confidence to a live Gas City city process (concrete suspect:
gascity cmd_rig_test.go runGitInTest, unscrubbed env + no-arg init
--bare — fork-side fix filed separately). Defense: new
always.git-config-hygiene gate fails fast on core.bare/test identities
with the repair command inline (--self-test proves fail-closed).
3. **Test/test@test.com identity leak**: writer convicted — our own
pre-push chain leaked GIT_DIR into go test, whose helpers wrote the
shared config via git -C (mechanism proven). Cut at both ends:
validate-go-fast scrubs env for children; every test git-helper set-site
scrubs; check-test-isolation gains a WARN-ratchet rule (baseline 3 →
FAIL at 0).
Gates: shellcheck rc=0 across 36 scripts; go build/vet clean;
655+379+149 tests; hygiene self-test; both originally-failing validators
pass under the repro env.
Completes the Go CLI migration: one composition model, no tombstones, no
dead packages, hermetic tests, and a cross-language verdict contract
corpus. Net −88k lines.
## What
- **Tombstones + prune deleted**: the 21 registered 'Removed in the
Cathedral Cut' stubs, `zzz_default_spine.go`'s runtime prune, and the
~30 registered-but-pruned legacy command families are gone. The
registered tree IS the production tree; retired verbs fail with exit 1 +
a data-driven replacement hint pointing at docs/MIGRATION.md (now
covering nested verbs). Non-runnable parents reject unknown subcommands
instead of printing help with exit 0.
- **~35 unreachable packages deleted** (cliapp, canon, pawl-era verdict
parser, pool, harvest, knowledge, wiki engine, vibecheck, cli/embedded,
…) after import analysis + script/CI consumer verification. Retained
with named consumers: archcheck (arch gate scripts), eval island (rubric
schema drift guards), drwitness/drrebuild (witness-crosscheck).
- **Composition decision recorded**: single cmd/ao root +
internal/commands/<family> modules + clicontract; the never-adopted
cliapp.BuildRoot is removed. New overview: docs/architecture/go-cli.md
(repairs two broken links).
- **Hermetic tests**: flag_matrix_test.go builds the exec'd binary from
package source — the stale cli/bin/ao failure class is closed;
TestHermeticBinaryMatchesSourceSurface pins source↔binary
correspondence.
- **Verdict contract consolidated**: verification extracted from
status.go into cli/internal/verdictcheck; 19-case golden corpus
(tests/fixtures/verdict-contract) runs through Go + Python + JSON schema
via blocking gate `contract.verdict-corpus`. One divergence closed
(empty-string context ids now rejected by all three).
- **Fossil guard chains retired**: embedded-sync (mirror had zero
importers), retired-family compat baselines, dead
go_cli_compatibility.bats, stale gate globs/grandfather entries.
## Evidence
- Full-tier deterministic gate: **66/66 PASS** on the rebased tip (fresh
source-built binary)
- cli suite 2,795 tests green; race suite green on touched packages; vet
+ pinned golangci-lint clean
- Cathedral Cut conformance PASS; CLI reference/surface projections
regenerated and checked
- Independent cross-family validation (fresh Codex context, frozen SHA):
5/6 claims CONFIRMED; 6th NOT_PROVEN only due to sandbox networking (its
cached rerun of the same suite passed)
- Test-count decrease is deliberate and carried by a Test-Removal-Reason
trailer
## Summary
Closes the findings from the v3.3.0 release-viability audit of main.
**Surface truth (High):** `ao constraint`, `ao goals trace`, `ao session
memory`, and `ao skills edit` are production tombstones but
docs/cli-surface.md documented them as `public-tested`/`covered` (the
test binary keeps constraint live, and the generated doc reflected the
test build). Added `deprecated` allowlist rows, dropped the stale
constraint-subcommand rows, regrouped constraint with its tombstone
peers in the default spine, regenerated both surface projections, and
added `TestCathedralCutTombstonesSurvivePruning` pinning the invariant
that every Cathedral Cut verb keeps an executable tombstone.
**Installer hardening (Medium):** `install-bd.sh` now fails closed when
no published checksum exists for a release asset (explicit `--no-verify`
overrides), and the curl|bash path verifies the fetched
`installer-common.sh` against a pinned SHA-256 before sourcing it
(drift-guarded by a new install-bd.bats test).
**Docs (Medium/Low):** UPGRADING.md no longer links the MIGRATION-3.0.md
file the Cathedral Cut deleted; CHANGELOG 3.3.0 `### Removed` now names
`yield`, `constraint`, and the 3.2 `verify` front door and links the
MIGRATION.md map.
**Gate scripts (Low):** flywheel/provenance gate scripts build `ao` into
`mktemp -d` scratch dirs instead of fixed world-known /tmp paths
(symlink/TOCTOU on shared hosts).
**Bonus (surfaced by the push gate):** `scripts/lib/preamble.sh`
mis-resolved REPO_ROOT under git hook env (GIT_DIR without
GIT_WORK_TREE), which made `go.cli-architecture` refuse every
worktree-origin push touching `cli/cmd/ao/**`. Fixed by scrubbing the
hook-injected discovery env around the rev-parse.
## Validation
- `go build && go vet && go test ./...`: 5,085 tests green,
golangci-lint clean
- `ao gate check --fast`: 27/27 pass, including under simulated hook env
- bats install-bd suite 6/6 incl. new pin drift test; shellcheck clean
on all touched scripts
- markdownlint clean; doc-release gate passes; tombstone exit codes
verified on the built binary
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.
## Summary
- replace removed nightly retrieval commands with the maintained smoke
fixture and focused retrieval coverage
- repair Windows smoke, workflow/actionlint, skill projections,
installer fixtures, and stale Cathedral Cut tests
- refactor verdict validation below the complexity budget while
preserving its error contract
- incorporate the pending cross-runtime hook projection already
represented in the repository manifest
## Validation
- `go test -race -shuffle=on ./...`
- full Bats suite: 874/874 passed
- `scripts/ci-local-release.sh --quick`
- `ao gate check --full --json --workflow-coverage
--require-workflow-parity`: 65/65
- `ao gate check --fast --json`: 43/43
This PR repairs the common causes represented by open nightly issues
#900, #901, #903, #909, #910, and #912. Those issues will be closed only
after the corresponding workflows pass on `main`.
---------
Co-authored-by: boshu <241868352+boshu2@users.noreply.github.com>
Co-authored-by: Test <test@test.com>
Follow-up to the evidence-store move: the project and home config now resolve
at .agents/ao/config.yaml (config.go, gateway, doctor cliconfig fixes, help
text), the Claude hook-manifest probe reads ~/.agents/ao/hooks.json, and the
cc-hooks guardrail telemetry default AGENTOPS_HOME falls back to ~/.agents/ao.
The tracked tracker-pin config moved via git mv with a narrow gitignore
negation (.agents/ stays untracked except ao/config.yaml). The .agentops/
directory no longer exists and nothing in the repo writes to it.
Co-authored-by: Cursor <cursoragent@cursor.com>
Intent snapshots and verdict artifacts now default to
.agents/ao/{intents,verdicts}/sha256/ so all session/evidence state lives
under .agents/ as the single agent-state root. Updates validate.py defaults,
ao init/status/demo, the cathedral conformance probe, craft_score.py digest
resolution, and every doc/skill mention. Existing artifacts migrated in
place; .agentops/ retains only the tracked project config.yaml.
Co-authored-by: Cursor <cursoragent@cursor.com>
Bo