boshu2__agentops/docs/MIGRATION.md

Cathedral Cut migration

AgentOps now owns one small product boundary:

RPI charter -> Plan if needed -> Implement and check -> fresh Validate -> finish

(The 3.0 through 3.6 releases stopped after one validation; ADR-0017 added the bounded repair phase.)

Known defects can be repaired directly and an approach can change within the accepted outcome, scope and real allowance. The caller owns changes to that acceptance, new allowances, scheduling, trackers, Git and delivery. Deterministic repository checks stay under ao gate check; semantic judgment is the Validate skill.

Removed responsibilities

Removed command or surface	Surviving alternative
ao pawl	Invoke the Validate skill for one independent semantic verdict.
ao plan-pawl	Invoke premortem when the caller wants an advisory plan challenge.
ao validate	Use the Validate skill; use ao gate check only for deterministic checks.
ao land	Use the repository's Git or CI delivery process.
ao done, ao close	Report the result to the caller; AgentOps does not close work.
ao governor, ao converge	The caller decides whether to start a new invocation or revision.
ao yield	Observe throughput in the selected runtime or external system.
ao claim, ao next-work	Use the caller's tracker or substrate directly.
ao state, ao reconcile	Inspect the bead or caller intent, derived subject manifest, verdict, and generic provenance as read-only evidence.
ao worktree	Use Git directly.
ao membrane	Record observations as Validate findings or generic provenance.
ao crank	Call an executor directly or use the optional dispatch_once adapter.
ao constraint	Encode accepted mechanical policy in repository-owned linters or checks; AgentOps no longer promotes findings into blocking state.
ao skills edit	Edit canonical skills/<slug>/ sources directly; use normal repository Git policy outside ao.
ao goals trace	Inspect current goal/scenario artifacts directly; the retired directive-to-bead lifecycle chain has no replacement.
ao inject	Use optional Memory recall over caller-owned, authorized context sources; there is no replacement CLI retrieval controller.
ao session memory	Use caller-authored ao session handoff evidence or maintain repository memory through the caller's own policy.
ao config models	Model-tier configuration was removed; nothing consumed it. Model choice belongs to the caller's runtime. Existing models: config sections still parse and are ignored.
ao verify	Use the Validate skill for semantic judgment and ao gate check for deterministic checks. Delete any ao verify init pre-push ratchet from .git/hooks/pre-push (restore pre-push.agentops-orig if one was set aside); ao verify init --remove no longer exists, and git push --no-verify bypasses a stale hook once.
ao flywheel	The CLI surface remains retired; existing flywheel: config sections still parse and are ignored. Optional Memory and Learn skills can review useful episodes and curate topic pages. They do not automatically compute compounding or claim benefit without later work.
ao eval	The offline eval surface was retired unconsumed (no gate, workflow, or script ran it); use a repository-selected evaluator and record the result as generic ao provenance evidence.
ao redact	Its only declared caller (the compile skill's render-write) never existed. Use owner-authorized disclosure review before storage; removing or replacing this command does not authorize reading restricted sources.

These names are no longer registered commands. Invoking one fails as an unknown command (exit 1) and prints the matching replacement pointer from the table above; nothing forwards to old code or mutates old state.

Other 3.2 bookkeeping and knowledge verbs (ao beads, ao agents, ao canon, ao ci, ao citation, ao findings, ao forge, ao knowledge, ao mcp, ao metrics, ao notebook, ao patterns, ao pool, ao ratchet, ao registry, ao scope, ao sessions, ao wiki) were pruned from the default build without tombstones. They have no replacement inside AgentOps; use the caller's own tools, ao gate check for deterministic checks, or generic ao provenance records.

Config file location

~/.agentops/config.yaml and ./.agentops/config.yaml moved to ~/.agents/ao/config.yaml and ./.agents/ao/config.yaml. The legacy paths are still read as a fallback for this release (with a deprecation warning on stderr) when no file exists at the new path; move the file to silence the warning:

mkdir -p ~/.agents/ao && mv ~/.agentops/config.yaml ~/.agents/ao/config.yaml

Skills

• plan now contains the useful behavior from discovery, behavior-first-planning, and goal-design.
• swarm and crank are optional caller-selected dispatch adapters, not lifecycle authorities.
• memory offers optional recall, mining and topic curation; learn is a compatible mining entrypoint for authorized episodes, including corrections and failures. Neither is a required lifecycle phase.
• Canonical mortem names are premortem and postmortem. Hyphenated and underscored variants were removed.
• beads-br and beads-bv were removed from the bundle. This repository uses native BD for work authority; BR is a different implementation, not a fallback. Beads Viewer is optional advice over an explicitly refreshed BD export.

Verdicts and identity

When persistence is requested, verdict.v2 binds acceptance and a deterministic subject-manifest.v1 to distinct declared author and validator context identities. Freshness is an attested trust fact, not cryptographic proof of process isolation. New CDLC proof uses caller-selected protected external non-Git storage, with atomic content-addressed verdict writes when requested. Preserve existing .agents/ evidence under owner policy. Missing destination routing is not permission to fall back to repository storage (ADR-0016).

Historical Pawl, queue, claim, landing, and lifecycle artifacts remain inert evidence. They no longer influence phase sequencing, verdict validity, or CLI outcomes.

Install migration

AgentOps 3.3 supports three install paths: npx skills@latest add boshu2/agentops --all -g (universal across coding agents), runtime plugins for Claude Code and Codex (managed bundles that update with the release), and one canonical checkout plus source symlinks for users who edit skills or contribute:

git clone https://github.com/boshu2/agentops.git ~/.local/share/agentops
cd ~/.local/share/agentops
ao skills link --dry-run
ao skills link

The 3.x curl installers (scripts/install.sh, install-claude.sh, install-codex.sh, install-agy.sh, install-opencode.sh, and install-codex.ps1) are tombstones: they refuse to install and print the supported paths. Internal helpers (install-codex-plugin.sh, install-codex-native-skills.sh) were deleted.

If you switch from a plugin to source links, remove the runtime plugin through that runtime before linking the checkout so only one corpus is visible:

• Claude Code: claude plugin uninstall agentops@agentops-marketplace, then claude plugin marketplace remove agentops-marketplace.
• Codex: codex plugin remove agentops@agentops-marketplace, then codex plugin marketplace remove agentops-marketplace. (Older Codex without the plugin verb: remove ~/.codex/plugins/cache/agentops-marketplace and ~/.codex/.agentops-codex-install.json, then remove the AgentOps plugin enable entry from ~/.codex/config.toml.)
• Gemini/Antigravity: agy plugin disable agentops-core-gemini, then agy plugin uninstall agentops-core-gemini.

ao skills link refuses to replace real directories and foreign links. Resolve each reported conflict deliberately; never delete a user-owned skill merely to make the counts match. Use ao skills unlink to remove only links that point into the current checkout.

Optional runtimes

NTM, Agent Mail, Gas City, councils, and model-specific executors remain caller-selected adapters or strategies. None is a hard dependency of RPI, Plan, Implement, or Validate, and none may translate its own attempts, leases, queues, or delivery state into AgentOps correctness state.