boshu
287c2797eb
F4 stamped the embedded pawl bundle with a deterministic content hash; this surfaces it in
`ao pawl doctor` so the landed!=installed class (an installed ao silently running OLD pawl scripts —
it bit this very session) is diagnosable.
THE DESIGN IS THE LESSON. Two cross-family codex refutes killed the obvious implementation:
round 1 — I hashed any repo containing scripts/pawl-*.sh and reported STALE. A stranger repo with
same-named files would be falsely failed.
round 2 — I gated that on "identity markers" (the verdict schema + pawls contract). Codex refuted
again, correctly: FILE PRESENCE IS NOT IDENTITY. Every marker is attacker-controlled and
spoofable, so no marker list can ever make it safe.
The real fix is not a better marker list — it is a TRUST BOUNDARY. A staleness FAILURE must never be
asserted against a repo the binary does not trust. So:
- trusted dogfood path (untrustedRoot == "", i.e. the ao binary lives inside the checkout — the ONE
trust decision the whole pawl surface is built on): the LIVE scripts run in place, so there is
nothing to compare and nothing to warn about;
- untrusted/installed path: surface the stamp INFORMATIONALLY (so the operator can diagnose
landed!=installed themselves and rebuild), and assert NO verdict about a repo we cannot trust.
This is the honest feature, not a weaker one: the diagnostic signal is preserved while doctor cannot
be weaponized into failing on an untrusted tree.
Tests: TestPawlBundleStaleness — dogfood surfaces the stamp and never says STALE; an untrusted repo
is never reported STALE *whatever it contains*, including a repo that SPOOFS every identity marker a
naive check might have used.
Claude-Session: https://claude.ai/code/session_01RDWPYn4ZS2SyBkcBvAM18u
ao — AgentOps CLI
ao is the local verification membrane and durable bookkeeper for agent work.
It turns a committed change into an independently checked verdict and records
that verdict in a hash-chained provenance ledger: no verdict means not done.
The default binary intentionally exposes the membrane/bookkeeper spine from
ADR-0012.
Experimental corpus/flywheel commands are restorable with the flywheel build
tag; retired factory/orchestration commands are restorable with legacy.
Install
go install github.com/boshu2/agentops/cli/cmd/ao@latest
One live path
From a repository root:
ao quick-start
ao session bootstrap
ao beads tracker
ao beads ready
git add .
git commit -m "fix: first validated change"
ao verify my-first-change
ao gate check --fast --scope head
ao quick-start creates the local readiness seed. ao session bootstrap
orients the agent. ao beads tracker reports the selected BR/BD backend, and
all tracker consumers use that same selection. ao verify obtains and records
the first independent verdict. The gate is the final pre-push windshield.
Default surfaces
| Surface | Purpose |
|---|---|
ao capabilities |
Recursive, versioned machine contract for the live command tree |
ao quick-start |
Seed a repository and print the one live first-verdict path |
ao beads |
Resolve and operate through the selected tracker |
ao pawl / ao verify |
Independent review and commit-bound verdict |
ao gate / ao validate |
Deterministic release checks and verdict-as-exit-code validation |
ao provenance |
Append, inspect, export, and verify the hash-chained ledger |
ao session |
Session bootstrap and closeout bookkeeping |
ao goals / ao claim |
Intent, fitness, ownership, and evidence bindings |
ao skills |
Inspect the checked-in skill contracts |
Machine consumers should begin with ao capabilities. Global output formats
are closed to table, json, and yaml; a leaf-local flag with the same name
retains its local meaning.
Build variants
go build ./cmd/ao
go build -tags flywheel ./cmd/ao
go build -tags legacy ./cmd/ao
go build -tags 'flywheel legacy' ./cmd/ao
Run ../scripts/verify-buildtags.sh from this directory's parent to prove all
variants compile and that the default executable membership remains focused.