mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
docs(release): 3.1 release narrative + gate-discipline changelog (cp-fhq3)
Version strings already landed at 3.1.0 on origin/main (manifests + CHANGELOG [3.1.0] entry); CLI version comes from the v3.1.0 git tag via goreleaser, not a static file. This track adds the release documentation on top of that: - CHANGELOG.md: rewrite the [3.1.0] entry to lead with the gate-discipline story (native Go gate + workflow parity, verdict-gate distinct-family + author exclusion, skill canonicalization) and ground Added/Changed/Fixed in the real v3.0.1..main history. - docs/3.1.md (NEW): release narrative companion to docs/3.0.md — what 3.1 adds (installable images + Day-2 ops) and the gate-discipline headline; measured install-smoke figure (41/0); tag-cut status with TODO-INTEGRATE. - README.md: add "What 3.1 adds" → docs/3.1.md to the docs nav. Install one-liners + Day-2 ops doc already present on main; left intact.
This commit is contained in:
Boden Fuller
+20
-4
@@ -9,17 +9,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
## [3.1.0] - 2026-06-08
|
||||
|
||||
AgentOps 3.1 is the **packaging-and-gate-discipline** minor on top of the hookless 3.0 core. The headline is not a new feature — it is that the release pipeline itself became the product. Three things hardened together: the **release gate moved native** (the inline bash checks were ported to a single Go gate that the pre-push hook runs as the release authority, with workflow-parity enforcement so a check can't pass locally while drifting in CI); **close-admission tightened** (the verdict gate now counts distinct validator *families* with author exclusion, so a self-graded "looks good" no longer admits a close); and the **skill corpus was canonicalized** (ghost skills materialized into the tree, registries/counts regenerated from one source, and bundled image copies forced back to byte identity with that source). On top of that discipline, the three IMAGE-CORE recipes (Claude / Codex / Gemini-AGY) ship as real, smoke-proven install paths. See [docs/3.1.md](docs/3.1.md) for the release narrative.
|
||||
|
||||
### Added
|
||||
|
||||
- **Installable image artifacts for the 3.1 runtime set.** Claude Code now has a dedicated marketplace installer wrapper, Codex keeps the native plugin curl installer, and Gemini/Antigravity now has a curl installer that validates and installs `images/gemini` through `agy plugin`.
|
||||
- **Day-2 install operations are productized.** Added operator guidance for install, update, backup, permission repair, recovery, and escalation across Claude, Codex, and Gemini/AGY.
|
||||
- **Installer smoke proof covers all three image paths.** The install smoke suite now checks the Claude, Codex, and Gemini/AGY one-liners without invoking vendor runtimes.
|
||||
- **Installable image artifacts for the 3.1 runtime set.** Claude Code now has a dedicated marketplace installer wrapper, Codex keeps the native plugin curl installer, and Gemini/Antigravity now has a curl installer that validates and installs `images/gemini` through `agy plugin`. The three documented one-liners are in [README §Install](README.md#install); the recipes are materialized as `images/{claude,codex,gemini}/` (each with a manifest, `README.md`, and `verify.sh`).
|
||||
- **Day-2 install operations are productized.** Added [docs/install-day2-ops.md](docs/install-day2-ops.md) — operator guidance for install, update, backup, permission repair, recovery, and escalation across Claude, Codex, and Gemini/AGY (the AT&O "make Day-2 part of the product, not an afterthought" doctrine).
|
||||
- **Installer smoke proof covers all three image paths.** `tests/install/test-install-smoke.sh` checks the Claude, Codex, and Gemini/AGY one-liners without invoking vendor runtimes (measured: 41 passed, 0 failed).
|
||||
- **Claude installer release-pinning.** `scripts/install-claude.sh` now accepts `--ref <ref>` (or `AGENTOPS_INSTALL_REF`) to pin the marketplace source to a tagged release (e.g. `v3.1.0`), reaching parity with `install-agy.sh`.
|
||||
- **Claude image version guard.** `images/claude/verify.sh` now asserts `.claude-plugin/plugin.json` declares the expected release version (default `3.1.0`, override via `AGENTOPS_EXPECTED_VERSION`), so a stale-version drift in the marketplace manifest fails the gate.
|
||||
- **`ao skills resolve` — MECE corpus audit** (`c9c3e2706`). Reports skill overlap and coverage gaps so the corpus can be kept mutually-exclusive / collectively-exhaustive.
|
||||
- **`ao refinery` backstop daemon** (`cba058c6a`, ag-qidx) — a refinery surface for the gate/registry regen path, with a `cli-skills-map` regenerated for it.
|
||||
- **Go gate workflow coverage + parity reporting** (`390695b65`, `281d46d34`, `283e60e78`) — the gate now reports which CI workflows back each check and *requires* workflow parity, so a locally-green check that has drifted out of CI fails the gate.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Pre-push gate flipped to the native Go gate** (`c97efcc36` PB2, `efbcf7e90`, `ca9366ccb`) — the inline bash checks were ported to native Go checks (`643e7ade1`, `b720a72cd`, `bcaae4b02`, `5b93b4814`, `6814e377c` — PB1 batches) and the pre-push hook now runs `ao gate check` as the release authority. Local validation is the routine shipping path; GitHub Actions is an optional/manual backstop.
|
||||
- **Push-to-main cockpit doctrine** (`d90ff1d09`, `0f501beae`, `a023dc4df`) — workflow rewritten for push-to-main with a concurrency-scoped push lock (`push-serial.sh`); dead merge-machinery scripts deleted.
|
||||
- **Local validation is the release authority** (`3d4fc1299`, `ac5664c56`, ag-3l86) — local-CI made viable as a DSR fallback when GitHub Actions quota is exhausted.
|
||||
- **Skill corpus canonicalized + triggers added.** 4 ghost `codebase-*` skills materialized into the tree and registered across catalog surfaces (`dd34f8688`, `584701af8`, `61421cdb9`, `0580f7303`, `cp-801l`); explicit "Use-when" triggers added to weak-trigger skills (`5cdd8e792`, `5895422cd`, `e0932310d`); `using-ntm` renamed to `using-atm` (`5c4e7f07a`); 2026-06-10 operational lessons encoded into 4 canonical skills (`d286a5fc2`).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Gemini image bundle drift.** Refreshed the bundled Gemini/AGY `SKILL.md` copies so `images/gemini/verify.sh` again proves byte identity against the canonical source corpus.
|
||||
- **Verdict gate now enforces distinct families + author exclusion** (`cp-verdict-gate-family-author-enforcement-icb6`, `d6576b359`, `94181cc89`, `9c1398671`) — `council_judge` counted files, not distinct validator families, and did not exclude the author; a self-graded verdict could admit a close (LAW-3 gap). The gate now requires cross-family verdicts and excludes the author.
|
||||
- **Removed Claude `--print` probes from headless paths** (`267f378a0`, `dee7a3502`, ag-eli0) — the headless checks and the team-runner path no longer shell out to `claude --print` (LAW 0 compliance).
|
||||
- **Distribution install contract aligned** (`29b919f92`) — the `agentops-core.distribution-install-update` canary was failing on main; the contract was realigned so `claude plugin update` and the install/update path stay green.
|
||||
- **Gemini image bundle drift** (`3e0f8f4e8`, `0e5d07211`) — refreshed the bundled Gemini/AGY `SKILL.md` copies so `images/gemini/verify.sh` proves byte identity against the canonical source corpus. The residual `validate` and `vibing-with-ntm` drift left by the 2026-06-10 4-skill lesson encoding was resynced so both `images/gemini/verify.sh` and `scripts/validate-agy-plugin.sh` pass byte-identity.
|
||||
- **Skill-auditor pass-1 gated on heal-strict** (`dbc2a6466`); post-merge skill lint drift repaired (`f784d2842`).
|
||||
|
||||
## [3.0.1] - 2026-05-25
|
||||
|
||||
|
||||
@@ -155,6 +155,6 @@ ao metrics health # flywheel health
|
||||
|
||||
## Docs & contributing
|
||||
|
||||
[What 3.0 is](docs/3.0.md) · [docs index](docs/documentation-index.md) · [newcomer guide](docs/newcomer-guide.md) · [architecture](docs/ARCHITECTURE.md) · [FAQ](docs/FAQ.md) · built on the [12-factor doctrine](https://12factoragentops.com).
|
||||
[What 3.1 adds](docs/3.1.md) · [What 3.0 is](docs/3.0.md) · [docs index](docs/documentation-index.md) · [newcomer guide](docs/newcomer-guide.md) · [architecture](docs/ARCHITECTURE.md) · [FAQ](docs/FAQ.md) · built on the [12-factor doctrine](https://12factoragentops.com).
|
||||
|
||||
Contributing: [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) (agents: read [AGENTS.md](AGENTS.md), track work with `bd`). License: Apache-2.0.
|
||||
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
# AgentOps 3.1: ship the loop, prove the gate
|
||||
|
||||
> **3.1 is a minor on top of [3.0](3.0.md).** The 3.0 north star is unchanged — AgentOps is the in-session operating loop plus the context compiler that feeds it. Read [3.0.md](3.0.md) first for *what AgentOps is*. This page covers *what 3.1 adds*: the loop becomes **installable** for three runtimes, and the **release gate itself becomes the product**. When this page and 3.0 disagree on the core thesis, 3.0 wins; this page only extends it.
|
||||
|
||||
AgentOps 3.1 does not add a new practice. It does two things to the 3.0 core:
|
||||
|
||||
1. **Makes it installable** — the three IMAGE-CORE recipes (Claude, Codex, Gemini/Antigravity) ship as real, documented, smoke-proven install paths, with Day-2 operations (update, backup, permission repair, recovery, escalation) treated as part of the product.
|
||||
2. **Makes the gate the authority** — the release pipeline that produces AgentOps was itself hardened: a native Go gate with workflow-parity enforcement, a verdict gate that requires cross-family validation with author exclusion, and a skill corpus canonicalized from one source of truth.
|
||||
|
||||
The through-line: **3.0 named the loop; 3.1 productized the loop and the discipline that ships it.**
|
||||
|
||||
---
|
||||
|
||||
## The gate-discipline story (the real headline)
|
||||
|
||||
The biggest change in 3.1 is invisible in `ao --version` but load-bearing for everyone who ships through it. Three gates tightened together.
|
||||
|
||||
### The release gate moved native
|
||||
|
||||
In 3.0 the pre-push gate was a sheaf of inline bash checks. In 3.1 those checks were ported to a single native **Go gate** (`ao gate check`), and the pre-push hook runs it as the **release authority**. Local validation is the routine shipping path; GitHub Actions is an optional/manual backstop, not the gate of record. This matters because the project repeatedly hit GitHub Actions quota exhaustion — the local gate keeps shipping viable without it (the DSR fallback).
|
||||
|
||||
The gate doesn't just run checks; it enforces **workflow parity**. Each check reports which CI workflow backs it, and a check that is green locally but has drifted out of CI **fails the gate**. A check that has no enforcing workflow is not a gate — it's an orphan. 3.1 makes that distinction mechanical.
|
||||
|
||||
### Close-admission tightened: distinct families, author excluded
|
||||
|
||||
The 3.0 verdict gate had a hole (LAW-3 gap): `council_judge` counted *files*, not distinct validator *families*, and did not exclude the author. Two verdict files from the same model — or a verdict written by the same agent that did the work — could admit a close. A self-graded "looks good" was enough.
|
||||
|
||||
3.1 closes it. A close now requires verdicts from **distinct validator families** with the **author excluded**. The gate can no longer trust a self-declaration. This is the close-admission discipline: work isn't done because the worker says so; it's done when an independent, cross-family verdict says so.
|
||||
|
||||
### The skill corpus canonicalized
|
||||
|
||||
3.1 forces the skill corpus to have a single source of truth. Ghost skills (referenced but not materialized) were brought into the tree; registries, counts, and catalog surfaces were regenerated from that source; and bundled image copies were forced back to **byte identity** with the canonical `skills/<slug>/SKILL.md`. The image verifiers (`images/{claude,gemini,codex}/verify.sh`) prove that identity on every release, so a stale bundled copy can't silently drift from the skill the docs describe.
|
||||
|
||||
A related compliance fix landed here: the headless and team-runner paths no longer shell out to `claude --print` (LAW 0).
|
||||
|
||||
---
|
||||
|
||||
## Installable: the three one-liners
|
||||
|
||||
The three IMAGE-CORE recipes are materialized in the repo as `images/claude/`, `images/codex/`, and `images/gemini/` — each with a manifest (`manifest.json` / `plugin.json`), a `README.md` citing the `control-plane/IMAGE-CORE.md` spec, and a `verify.sh`. Each has a documented install path:
|
||||
|
||||
```bash
|
||||
# Claude Code — marketplace plugin
|
||||
claude plugin marketplace add boshu2/agentops
|
||||
claude plugin install agentops@agentops-marketplace
|
||||
|
||||
# Codex CLI — native plugin curl installer (macOS/Linux/WSL)
|
||||
curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-codex.sh | bash
|
||||
|
||||
# Gemini / Antigravity (AGY) — validates and installs images/gemini via `agy plugin`
|
||||
curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-agy.sh | bash
|
||||
```
|
||||
|
||||
The full Install section, including the Windows variants and the optional `ao` CLI, is in the [README](../README.md#install).
|
||||
|
||||
**The install gate (3.1 acceptance):** a fresh machine can install AgentOps 3.1 for any of the three vendors via one of these documented one-liners. The install smoke suite proves all three paths without invoking the vendor runtimes:
|
||||
|
||||
```
|
||||
$ bash tests/install/test-install-smoke.sh
|
||||
Results: 41 passed, 0 failed
|
||||
```
|
||||
|
||||
(Figures above are measured from `origin/main` at the 3.1 cut.)
|
||||
|
||||
### Day-2 operations are part of the product
|
||||
|
||||
Per the AT&O doctrine — *install, update, backup, permission, recovery, and escalation paths are part of the product, not afterthoughts* — 3.1 ships [docs/install-day2-ops.md](install-day2-ops.md): operator guidance for each of those six paths across Claude, Codex, and Gemini/AGY. Installing is step one; staying installed and recovering cleanly is the rest of the product.
|
||||
|
||||
---
|
||||
|
||||
## What 3.1 does NOT change
|
||||
|
||||
- **The 3.0 thesis stands.** AgentOps is still the in-session loop plus the compounding `.agents/` corpus. No new methodology; 3.1 is composition and packaging, not invention.
|
||||
- **Still hookless by default.** The default install registers zero hooks; skills + the `ao` CLI + the local gate drive the lifecycle.
|
||||
- **Still no daemon, scheduler, or hosted control plane.** Out-of-session orchestration remains the substrate's job (NTM/ATM + MCP + managed-agents). The in-session loop is the zero-dependency sovereignty floor.
|
||||
- **State stays in `.agents/`.** No telemetry, no cloud, portable across model and harness.
|
||||
|
||||
---
|
||||
|
||||
## Cutting the release
|
||||
|
||||
`ao --version` is injected at build time from the **git tag** via goreleaser ldflags (`-X main.version={{ .Version }}`, see `.goreleaser.yml`). There is no static version file — the `v3.1.0` git tag is what makes the CLI report `3.1.0`, and it drives the goreleaser Homebrew/release assets. The plugin manifests (`.claude-plugin`, `.agy-plugin`, `.codex-plugin`, `images/gemini/plugin.json`) are already at `3.1.0` on `main`; cutting the `v3.1.0` tag is the single load-bearing release step that turns this into a shipped 3.1.
|
||||
|
||||
> **Tag-cut status:** the 3.1 content is fully landed on `main` (all four plugin manifests at `3.1.0`, CHANGELOG, docs, installers, smoke-proven). The remaining external step is the `v3.1.0` git-tag cut + goreleaser release-asset/Homebrew publication, gated on GitHub Actions quota (the goreleaser release workflow). The local cockpit gate is the release authority for the landed content; tag publication is the one downstream action the release owner performs when Actions quota returns.
|
||||
|
||||
---
|
||||
|
||||
*Canonical references: [3.0.md](3.0.md) (the north star) · [CHANGELOG](../CHANGELOG.md) · [install-day2-ops.md](install-day2-ops.md) · [README §Install](../README.md#install) · `images/{claude,codex,gemini}/` (the materialized recipes)*
|
||||
+20
-4
@@ -9,17 +9,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
## [3.1.0] - 2026-06-08
|
||||
|
||||
AgentOps 3.1 is the **packaging-and-gate-discipline** minor on top of the hookless 3.0 core. The headline is not a new feature — it is that the release pipeline itself became the product. Three things hardened together: the **release gate moved native** (the inline bash checks were ported to a single Go gate that the pre-push hook runs as the release authority, with workflow-parity enforcement so a check can't pass locally while drifting in CI); **close-admission tightened** (the verdict gate now counts distinct validator *families* with author exclusion, so a self-graded "looks good" no longer admits a close); and the **skill corpus was canonicalized** (ghost skills materialized into the tree, registries/counts regenerated from one source, and bundled image copies forced back to byte identity with that source). On top of that discipline, the three IMAGE-CORE recipes (Claude / Codex / Gemini-AGY) ship as real, smoke-proven install paths. See [docs/3.1.md](docs/3.1.md) for the release narrative.
|
||||
|
||||
### Added
|
||||
|
||||
- **Installable image artifacts for the 3.1 runtime set.** Claude Code now has a dedicated marketplace installer wrapper, Codex keeps the native plugin curl installer, and Gemini/Antigravity now has a curl installer that validates and installs `images/gemini` through `agy plugin`.
|
||||
- **Day-2 install operations are productized.** Added operator guidance for install, update, backup, permission repair, recovery, and escalation across Claude, Codex, and Gemini/AGY.
|
||||
- **Installer smoke proof covers all three image paths.** The install smoke suite now checks the Claude, Codex, and Gemini/AGY one-liners without invoking vendor runtimes.
|
||||
- **Installable image artifacts for the 3.1 runtime set.** Claude Code now has a dedicated marketplace installer wrapper, Codex keeps the native plugin curl installer, and Gemini/Antigravity now has a curl installer that validates and installs `images/gemini` through `agy plugin`. The three documented one-liners are in [README §Install](README.md#install); the recipes are materialized as `images/{claude,codex,gemini}/` (each with a manifest, `README.md`, and `verify.sh`).
|
||||
- **Day-2 install operations are productized.** Added [docs/install-day2-ops.md](docs/install-day2-ops.md) — operator guidance for install, update, backup, permission repair, recovery, and escalation across Claude, Codex, and Gemini/AGY (the AT&O "make Day-2 part of the product, not an afterthought" doctrine).
|
||||
- **Installer smoke proof covers all three image paths.** `tests/install/test-install-smoke.sh` checks the Claude, Codex, and Gemini/AGY one-liners without invoking vendor runtimes (measured: 41 passed, 0 failed).
|
||||
- **Claude installer release-pinning.** `scripts/install-claude.sh` now accepts `--ref <ref>` (or `AGENTOPS_INSTALL_REF`) to pin the marketplace source to a tagged release (e.g. `v3.1.0`), reaching parity with `install-agy.sh`.
|
||||
- **Claude image version guard.** `images/claude/verify.sh` now asserts `.claude-plugin/plugin.json` declares the expected release version (default `3.1.0`, override via `AGENTOPS_EXPECTED_VERSION`), so a stale-version drift in the marketplace manifest fails the gate.
|
||||
- **`ao skills resolve` — MECE corpus audit** (`c9c3e2706`). Reports skill overlap and coverage gaps so the corpus can be kept mutually-exclusive / collectively-exhaustive.
|
||||
- **`ao refinery` backstop daemon** (`cba058c6a`, ag-qidx) — a refinery surface for the gate/registry regen path, with a `cli-skills-map` regenerated for it.
|
||||
- **Go gate workflow coverage + parity reporting** (`390695b65`, `281d46d34`, `283e60e78`) — the gate now reports which CI workflows back each check and *requires* workflow parity, so a locally-green check that has drifted out of CI fails the gate.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Pre-push gate flipped to the native Go gate** (`c97efcc36` PB2, `efbcf7e90`, `ca9366ccb`) — the inline bash checks were ported to native Go checks (`643e7ade1`, `b720a72cd`, `bcaae4b02`, `5b93b4814`, `6814e377c` — PB1 batches) and the pre-push hook now runs `ao gate check` as the release authority. Local validation is the routine shipping path; GitHub Actions is an optional/manual backstop.
|
||||
- **Push-to-main cockpit doctrine** (`d90ff1d09`, `0f501beae`, `a023dc4df`) — workflow rewritten for push-to-main with a concurrency-scoped push lock (`push-serial.sh`); dead merge-machinery scripts deleted.
|
||||
- **Local validation is the release authority** (`3d4fc1299`, `ac5664c56`, ag-3l86) — local-CI made viable as a DSR fallback when GitHub Actions quota is exhausted.
|
||||
- **Skill corpus canonicalized + triggers added.** 4 ghost `codebase-*` skills materialized into the tree and registered across catalog surfaces (`dd34f8688`, `584701af8`, `61421cdb9`, `0580f7303`, `cp-801l`); explicit "Use-when" triggers added to weak-trigger skills (`5cdd8e792`, `5895422cd`, `e0932310d`); `using-ntm` renamed to `using-atm` (`5c4e7f07a`); 2026-06-10 operational lessons encoded into 4 canonical skills (`d286a5fc2`).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Gemini image bundle drift.** Refreshed the bundled Gemini/AGY `SKILL.md` copies so `images/gemini/verify.sh` again proves byte identity against the canonical source corpus.
|
||||
- **Verdict gate now enforces distinct families + author exclusion** (`cp-verdict-gate-family-author-enforcement-icb6`, `d6576b359`, `94181cc89`, `9c1398671`) — `council_judge` counted files, not distinct validator families, and did not exclude the author; a self-graded verdict could admit a close (LAW-3 gap). The gate now requires cross-family verdicts and excludes the author.
|
||||
- **Removed Claude `--print` probes from headless paths** (`267f378a0`, `dee7a3502`, ag-eli0) — the headless checks and the team-runner path no longer shell out to `claude --print` (LAW 0 compliance).
|
||||
- **Distribution install contract aligned** (`29b919f92`) — the `agentops-core.distribution-install-update` canary was failing on main; the contract was realigned so `claude plugin update` and the install/update path stay green.
|
||||
- **Gemini image bundle drift** (`3e0f8f4e8`, `0e5d07211`) — refreshed the bundled Gemini/AGY `SKILL.md` copies so `images/gemini/verify.sh` proves byte identity against the canonical source corpus. The residual `validate` and `vibing-with-ntm` drift left by the 2026-06-10 4-skill lesson encoding was resynced so both `images/gemini/verify.sh` and `scripts/validate-agy-plugin.sh` pass byte-identity.
|
||||
- **Skill-auditor pass-1 gated on heal-strict** (`dbc2a6466`); post-merge skill lint drift repaired (`f784d2842`).
|
||||
|
||||
## [3.0.1] - 2026-05-25
|
||||
|
||||
|
||||
Reference in New Issue
Block a user