boshu2__agentops/docs/architecture/go-cli.md

Go CLI architecture

The ao binary supplies deterministic repository checks, evidence inspection, and operational utilities. Semantic judgment belongs to a fresh native reviewer; the Validate skill is optional guidance for that review. Git, delivery, retries, work ownership, and continuation belong to the caller. This page maps an active command from CLI input to effect and result.

Composition model (the one production model)

There is exactly one composition root: cli/cmd/ao. Each command file registers its command on the package-global rootCmd in init(); main.go → Execute() runs the assembled tree. Exactly one late init() pass finishes assembly — zz_args_policy.go, whose zz prefix orders it after the command files so the whole tree exists when it runs:

• zz_args_policy.go — assigns an explicit Args policy to every runnable command and installs the unknown-subcommand guard on non-runnable parents, so ao <parent> <typo> fails with exit 1 instead of printing help.

Retired verbs need no init() and no registration. removed_command_hint.go holds a data-driven map of removed commands and, at execute time, turns the resulting cobra "unknown command" error into a replacement hint pointing at docs/MIGRATION.md. Removed commands are not registered; that error-plus-hint is the whole mechanism.

The registered tree is the production tree: there is no runtime pruning, no hidden build-tag variant, and no parallel root builder. (The experimental internal/cliapp.BuildRoot composition path was deleted in the post-Cathedral Cut cleanup; internal/clicontract remains the contract carrier.)

Every command family is a module: presentation lives in cli/internal/commands/<family> (each returns a fresh *cobra.Command plus a clicontract.CommandContract), and cmd/ao/<family>_composition.go (or <family>_module.go) is the thin glue that wires it onto rootCmd. A module receives all of its host wiring — output mode, verbosity, dry-run, project root, clock, version string, and flag-error enrichment — through the single shared clicontract.HostOptions seam. No family declares its own seam struct or passes host funcs positionally, and no module reaches for a direct host effect (os, os/exec, time.Now); the drift guards in cmd/ao/carveout_regression_test.go pin all of this.

The tree is intentionally two-tiered, and both tiers are production shapes — not an unfinished carve-out:

• Four families run the full hexagonal stack, module → service → adapters. capabilities, config, doctor, and gate each own a focused application-service package (for example cli/internal/gate) and push effects behind small consumer-owned ports implemented in cli/internal/adapters/<family>. These are the families with real domain logic or external effects worth isolating.
• The other twelve families run module → app-seam. demo, gc, goals, init, provenance, quick-start, robot-docs, session, skills, status, version, and workflows call a focused app package directly through the host seams and carry no dedicated adapters layer, because they have no effect boundary that a port would earn. Adding an adapters tier to an app-seam family is a deliberate non-goal until that family grows an effect worth isolating.

Published surface

The published spine is pinned by cmd/ao/default_spine_test.go (plus completion and help, which cobra synthesizes):

capabilities config demo doctor gate gc goals init provenance quick-start robot-docs session skills status version workflows

ao capabilities emits the machine-readable contract; cli/docs/COMMANDS.md is generated by scripts/generate-cli-reference.sh. TestHermeticBinaryMatchesSourceSurface proves the built binary matches the source-registered tree, and tests always build ao from the subject source — never a prebuilt cli/bin/ao.

Gate system

ao gate check executes the deterministic check registry:

• Check definitions: cli/internal/gates/ (IDs, tiers, match globs, backing scripts) with per-check logic under cli/internal/gates/checks/.
• Execution: cli/internal/gate (application service) via cli/internal/adapters/gate.
• Backing scripts are trusted repository policy under scripts/; caller intent is never interpolated into shell execution.

A gate PASS is a deterministic fact, not a semantic verdict.

Evidence contracts and the judgment boundary

• schemas/verdict.v2.schema.json and schemas/subject-manifest.v1.schema.json declare the evidence contracts (see docs/SCHEMAS.md).
• A fresh reviewer is the semantic author of verdict.v2, whether reviewing directly or using the optional Validate skill. The ao provenance evidence leaves compute subject identity and structurally verify and atomically store a supplied judgment through internal/evidence, reusing internal/verdictcheck canonical/strict primitives. Evidence helper version 1 requires explicit existing non-Git roots for storage, with no configuration lookup or workspace fallback. The caller resolves CDLC routing; internal/evidencepath supplies the shared explicit-root guard.
• Python reference/schema checks live under skills/validate/tests and are developer tests, not installed runtime dependencies. Evidence leaves attach their actual contracts to the provenance family; optional relationship records remain separate from exact-subject mechanics.
• ao status is a read-only evidence inspector: it structurally verifies stored verdict artifacts (digest binding, canonical form, PASS scope rules) but never writes verdicts and never converts check success into semantic PASS. Evidence references are reported as declared strings; ao status does not resolve or digest-bind their targets. By default it reads the working directory's .agents/ao. To inspect existing external evidence, use ao status --evidence-root /path/to/evidence --json (or -o yaml for the same report). The shared evidencepath guard requires an existing non-Git root and checks active Git environment storage bindings. Only intents/sha256 and verdicts/sha256 are inspected; evidence directory and file symlinks are excluded. Invalid explicit roots fail without fallback or writes. Corrupt artifacts remain excluded and reported, and not_checked continues to disclose the limits of structural inspection.

The Learn seat (off-path)

The in-repo measurement surface (the former eval command family) was retired unconsumed — no gate, workflow, or script ran it (see docs/MIGRATION.md). Learn remains an optional, off-path consumer of authorized episodes and other evidence: the learn skill can update reviewed external topic pages under the Memory contract. No blind TTL or per-session lesson is required. Rubric projections are still leak-guarded by schemas/outcomes-rubric.v1.schema.json (internal/evalsubstrate), and true holdout rubrics live in the external measurement register, not this repo. Measurement, when a repository wants it, belongs to a repository-selected evaluator whose results are recorded as generic provenance evidence.

Related pages

• RPI traversal
• Component map
• Ports and adapters
• Migration map