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>
Session/direnv BEADS_DIR was hijacking ResolveLedger in ratchet and
quickstart cancel tests, failing the full pre-push race suite.
Implements: age-k430i
Co-authored-by: Cursor <cursoragent@cursor.com>
Migrate SYSTEM and AGENTS-{WORKFLOW,CI,CODEX,RUNTIME} into docs owners,
retarget consumers, rewrite the split gate, and craft-densify AGENTS,
README, PRODUCT, and GOALS under the documentation authority graph.
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>
Ban CLAIMS of proven/automatic knowledge compounding (unproven — ADR-0004,
ADR-0011) and hookless-3.0-violating 'session hooks' language (docs/3.0.md,
ADR-0009) from user-facing CLI strings + seed/template assets. The claims kept
regrowing (#907, FU4 diet commit) because nothing gated them.
- docs/contracts/forbidden-claims.yaml: seeded lexicon (regex + rationale +
allowed_contexts). Tight patterns require an automatic/every-session qualifier
so the conditional escape-velocity model and the 'flywheel' subsystem name are
NOT banned; the honest 'whether the corpus compounds is unproven' never matches.
- scripts/check-honest-voice.sh: scans cli/cmd + cli/internal Go (excl. *_test.go)
+ seed/template assets; honest-voice:allow suppression; exit 1 naming
phrase+file+line+rationale. Registered contract.honest-voice in the Go gate
registry (Fast|Full, blocking) routed on cli/**, the lexicon, and self-ref.
- cli/cmd/ao/seed.go: sweep — rewrote the stale 'ao init --hooks / session hooks /
knowledge compounds automatically' next-steps + decision-record template to
honest hookless phrasing.
- tests/scripts/check-honest-voice.bats: proves fail on a seeded phrase, pass on
the current tree, suppression, test-file exclusion, and the flywheel/conditional
false-positive guard.
ao quick-start --dry-run now prints a per-artifact file plan (CLAUDE.md,
GOALS.md, .gitignore, .agents/**, beads init) naming create/append/skip/
skipped for each, with a preview of the first line for append actions, and
guarantees zero filesystem writes. Re-running the full (non-verbose) flow
against an already-initialized repo collapses the ceremony to a short
"Already set up — nothing changed" summary + readiness checklist + single
Next line, reusing the existing diet rendering helpers.
Adds three L2 tests: dry-run leaves the tree byte-identical (fs snapshot),
the plan names every artifact with correct actions/previews, and a second
full run summarizes as a noop. All 45 existing quickstart tests and the
full cmd/ao suite (7501 tests) stay green; no COMMANDS.md/registry regen
needed (verified via generate-cli-reference.sh --check and
regen-changed-scope.sh --check).
Default `ao quick-start` output was ~3 screens (double banner, 4-step LIVE
PATH block, a philosophy quote, and a full readiness table). Builds on #907
(command-string correctness) with a PRESENTATION + TAILORING pass:
- Default is now a single-screen diet (<=40 lines): a one-line completion
header, a Created summary (GOALS.md marked "template — edit me"), a compact
readiness checklist, environment-tailored golden paths, exactly one Next
action (/plan) + one docs link (docs/first-value-path.md), and the tightened
first-verdict close. The ASCII banner and the "Stateful environment..."
quote are gone from the default.
- Golden paths are filtered by exec.LookPath: br/gt/codex/agy paths render only
when their binary resolves here; an absent core tool (br) collapses to one
short enable line instead of a run-this block. Skill paths (/plan) always fine.
- --verbose restores the full step-by-step long form for anyone who wants it.
Tests (L2, PATH fixtures via t.Setenv + t.TempDir):
TestQuickStart_OutputOneScreen (<=40 lines, one Next, no banner/quote),
TestQuickStart_GoldenPathsResolveInEnv (every rendered run-this argv[0]
resolves; absent tools omitted), TestQuickStart_GoldenPaths_AbsentToolEnableLine,
TestQuickStart_VerboseKeepsLongForm. Existing #907 guards
(AllAOCommandsResolve / NoRemovedCommands / journey tombstones) still pass.
Add the uninstall/rollback twin for `ao skills link`: `ao skills unlink`
removes exactly the live-tier symlinks link minted — those whose target
resolves into this repo's skills/ tree — across every installed runtime
(~/.claude, ~/.codex, ~/.gemini, ~/.cursor, ~/.pi). Idempotent and
non-destructive: foreign symlinks pointing elsewhere and real directories
(a foreign corpus such as jsm) are reported as foreign and never removed;
stale owned links (skill since removed from the repo) are still cleaned up.
Supports --dest, --dry-run (persistent), and --json, mirroring skills link.
Document the uninstall path in docs/install-day2-ops.md: per-runtime plugin/
skill removal (Claude, Codex, AGY, OpenCode), `brew uninstall agentops`,
`ao skills unlink` for clone-linked skills, and an explicit 'what is kept'
note that .agents/ and quick-start artifacts (CLAUDE.md block, GOALS.md) are
user-owned data the uninstall deliberately never touches.
Regenerate the affected command-surface projections (COMMANDS.md, cli-surface
.{json,md}, the eval surface matrix + smoke fixture). The matrix/smoke counts
also absorb pre-existing origin/main drift (checked-in expected sub=120 vs
actual tree 112); regen brings them to the truthful 113 (112 + unlink).
Tests (L2 round-trip, t.TempDir): RemovesOnlyOwnLinks (foreign symlink + real
dir survive), DryRunWritesNothing, Idempotent, MissingDestIsNoop,
RemovesStaleOwnedLink, EmptySrcFailsClosed, ResilientAcrossDests.
ao doctor manufactured doubt on a fresh install: optional-dep absence and
"you haven't run a session yet" states rendered as warnings, a P1 failure-mode
flagged the optional `br` CLI as required, and repo-only checks emitted
warnings whose fixes were repo-relative scripts (heal.sh, refresh-codex-local.sh)
unrunnable outside a clone.
- Tag every legacy check with an audience (installed-user | repo-dev). Outside
an agentops clone, collapse the repo-dev group (skill hygiene, codex sync,
stale refs, plugin manifest, binary freshness) to a single info line.
- Add a non-failing "info" status; reframe not-started-yet / optional states
(no sessions, no index, no learnings, absent gt/bd/codex/reviewers) as info,
never warnings — they no longer count toward the pass/total tally or degrade
the result.
- Add Check.Fix carrying a remediation runnable from the reader's context
(ao/br/brew/npm/curl/URL), never a repo-relative script.
- Severity honesty: fm-cli-config-missing-required-cli treats only `git` as
universally required; `br` is required solely inside a clone. Optional deps
render as "optional — enables X". Retire fm-cli-config-optional-codex-cli-absent
(a P3 that failed every codex-less install; redundant with the Codex CLI info
line) so a pristine install exits success.
- Fix grammar: "1 learnings" -> "1 learning".
- --json report/Check shapes stay backward compatible (audience/fix are additive
omitempty fields; no field removed or renamed).
Tests: registry audience coverage, installed-user fix-string allowlist,
pristine-install-green (no above-info warning, no repo-relative script, no
optional dep labeled required), repo-dev collapse, and git-only/br-in-repo
required-CLI behavior.
## Summary
A fresh-install UX audit found `ao` emitting commands that do not exist
in the default binary. Verified live by building the CLI and running `ao
quick-start` in a fresh temp git repo with a sandboxed HOME.
- **repo_readiness**: `bd init` → tracker-agnostic `br init --prefix
<prefix> (or bd init --prefix <prefix>)` (product supports both; br
leads for guidance consistency). Dropped the hooks/program/schedule
readiness items — they advertised archived machinery (hookless 3.0,
ADR-0009/0012: `ao init --hooks`, `ao autodev init`, `ao init
--with-schedule`). Replaced literal unexpanded `$product`/`$readme`
actions with real next steps. Tracking presence check now also
recognizes a br `_beads` ledger.
- **CLAUDE.md seed section**: rewrote the "Knowledge Flywheel" block
("session hooks extract learnings", "knowledge compounds automatically",
`ao flywheel status`) to the hookless operating-loop story. Old markers
kept as legacy so re-seeding never duplicates the section.
- **quick-start**: `ao beads ready` (never existed) → `ao beads exec
ready`.
- **root help**: advertised `ao lookup`, which is pruned from the
default spine → `ao verify`.
- **doctor**: br install hint pointed end users at an AGENTS.md their
repos do not have → beads_rust URL + `ao beads dir`.
- **bridge**: deleted dead `FactoryRecommendedCommands` (`ao factory
start --goal`, `ao orchestrate status`).
## Guard
`cli/cmd/ao/advertised_commands{,_test}.go`: extracts every `ao ...`
string from user-facing output (readiness actions, quick-start golden
paths, seeded CLAUDE.md, starter pack, root/quick-start help) and
resolves each against the cobra tree **pruned to the production spine**
— the existing "Stale References" doctor check missed these because the
test binary keeps archived commands registered. Stricter than
`cobra.Find`: group commands reject positional args masquerading as
subcommands (`ao beads ready`), and unknown flags fail (`ao init
--with-schedule`).
## Verification
- `go build` / `go vet` / `golangci-lint` clean; `go test` green (7802
in the four touched packages; full cmd/ao suite green)
- Sandboxed-HOME UAT: every command printed by `ao quick-start` answers
`--help` without "unknown command"
- Pre-push cockpit gate: 31/31 fast/head checks pass (after regen of the
CLI command-surface matrix)
Co-authored-by: boshu <241868352+boshu2@users.noreply.github.com>
Bo