Skip to content

v2.41.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 15 May 02:37
· 824 commits to main since this release
v2.41.0
eb119f4

brew update && brew upgrade agentops · bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh) · checksums · verify provenance

Highlights

AgentOps v2.41.0 is the typed-BC-ports-load-bearing release. It completes the 14-port bounded-context inventory begun in the v2.40 cycle and makes the ports operationally load-bearing on the /evolve autonomous loop — not just scaffolding. Every /evolve cycle's read path now flows through typed Go interfaces (CorpusReaderPort Step 0, CIStatusPort Step 1.5, LoopReaderPort cycle-history wrapper) instead of untyped gh/ao lookup/inline jq shell-outs.

The release also ships 10 new ao subcommands that expose each typed port through the operator-facing CLI: ao loop history/append/verify, ao ci latest/recent, ao corpus inject/capture, ao operator record/list, ao harness status, ao gate run, ao citation verify, and ao claim bind/list. The cycle-shape used to land each of these is captured as a reusable template in docs/learnings/2026-05-13-cli-wiring-cycle-shape.md.

Three mechanical release-readiness gates now ship in the /validation, /evolve, and /post-mortem skills so the failure mode that produced this release — declaring "ready to tag" without running the full pre-push gate or regenerating CLI docs after a flag removal — cannot recur silently. STEP 1.7.5 of /validation auto-detects release context (branch name pattern or explicit flag) and refuses to recommend /release until scripts/pre-push-gate.sh (full, not --fast), scripts/ci-local-release.sh, and scripts/generate-cli-reference.sh cleanliness all pass. /evolve teardown on a release-shaped branch now emits an explicit pre-release checklist instead of recommending /release. /post-mortem closure-integrity now WARNs when a closed bead's acceptance text names a gate that the close-note doesn't confirm green.

A 448-line dead-code sweep removes defrag.SweepOscillatingGoals and its 5 helpers, the --oscillation-sweep CLI flag, and 9 corresponding tests (soc-1q1x path 1) — the function read for a target field that no production cycle has ever populated. Companion cleanup: 43 additional staticcheck U1000 findings cleared across cli/ over multiple cycles.

Upgrade Notes

  • CLI breaking-ish change: ao defrag --oscillation-sweep is removed. The flag was unused in production; downstream scripts that pass it will now error. If you depended on the report's Oscillation JSON field, it is also removed from DefragReport. The function never returned non-empty results in practice (see soc-1q1x analysis).
  • New typed-port CLI surface: 10 new ao subcommands are operator-facing and emit one JSON record per line. See cli/docs/COMMANDS.md for the full surface. The new commands route through typed BC port interfaces, so consumers get a stable shape independent of the on-disk file format.
  • Release-readiness gates are now mechanical: if you invoke /validation, /evolve, or /post-mortem on a release-shaped branch (release/*, v*-prep, v*-evolve-run, v[0-9]+.[0-9]+*), the new STEP 1.7.5 fires. Pass --skip-release-gates to bypass when running these skills on a release-shaped branch for non-release purposes.
  • The /release skill now requires the local CI parity gate (scripts/ci-local-release.sh) to pass before proceeding — --skip-checks does not skip this gate (changed in the v2.40.0 release cycle, hardened in v2.41).

At a Glance

Product Area Added Changed Fixed Removed
BC Ports (BC1–BC4) 4 0 0 0
Operator-facing CLI (ao) 11 1 0 1
Release-Readiness Gates (skills) 3 0 0 0
/evolve Read-Path Wire-up 1 3 0 0
Validation + Closure Integrity 1 0 1 0
Dead-Code Sweep 0 0 0 2
Internal: DDD/Hex Rescope Arc 0 1 0 0
Internal: Learnings Catalog 4 0 0 0

Product Areas

BC Ports — 14/14 Production-Complete

  • Added: FactoryAdmissionPort (13th BC port, soc-2klg.1) + productionFactoryAdmission pair adapter.
  • Added: ClaimEvidencePort (14th BC port, soc-2klg.2) + productionClaimEvidence.
  • Added: CycleEntry.StartedAt + Title fields (soc-ckc4) — ports widening + writer-side round-trip.
  • All 14 ports follow the <port>.go + inmemory_<port>.go + inmemory_<port>_test.go triplet with compile-time var _ XPort = (*InMemoryX)(nil) assertions as drift guards.

Operator-facing CLI (ao) Surface

  • Added: ao loop history (cycle 144 — first ao subcommand wired through a productionX adapter)
  • Added: ao ci latest/recent (cycle 145 — productionCIStatus)
  • Added: ao corpus inject (cycle 146 — productionCorpusReader; closes soc-y5vh.5)
  • Added: ao operator record/list (cycle 147 — template-applied 1st of 7)
  • Added: ao harness status (cycle 148)
  • Added: ao gate run (cycle 149)
  • Added: ao corpus capture (cycle 150 — BC1 R/W pair complete on CLI)
  • Added: ao loop append (cycle 151 — BC3 R/W pair complete on CLI)
  • Added: ao citation verify (cycle 152 — BC1 round-trip)
  • Added: ao claim bind/list (cycle 153 — 10th adapter CLI-exposed)
  • Added: ao loop verify — cycle-history integrity audit using cycle-161 widening
  • Removed: ao defrag --oscillation-sweep flag + DefragReport.Oscillation JSON field (soc-1q1x path 1)

Release-Readiness Gates (Skills)

  • Added: /validation STEP 1.7.5 — mandatory release-readiness gates with auto-detected release context, three gates (full pre-push, ci-local-release, generate-cli-reference cleanliness check), refusal to recommend /release until all pass. Codex parity synced.
  • Added: /evolve release-context teardown checklist — explicit unchecked pre-release checklist replaces the /release recommendation when the loop runs on a release-shaped branch.
  • Added: /post-mortem Acceptance-Text vs Delivered Drift audit — closure-integrity check that WARNs when a closed bead's acceptance language names a gate the close-note doesn't confirm green.

/evolve Read-Path Wire-up

  • Added: scripts/evolve-read-cycle-history.sh — wrapper around ao loop history for skill scripts.
  • Changed: Step 0 prior-knowledge retrieval routes through BC1 CorpusReaderPort via ao corpus inject (was: ao lookup).
  • Changed: Step 1.5 healing-first classifier routes through BC2 CIStatusPort via ao ci recent --limit 1 (was: inline gh run list).
  • Changed: oscillation counters in references/oscillation.md and references/fitness-scoring.md migrated to the wrapper (was: inline jq over raw JSONL).

Validation + Closure Integrity

  • Added: .agents/operator/ write-surface entry in docs/contracts/agents-write-surfaces.md (BC4 OperatorPort durable-intent log).
  • Added: Gap 3 (loop-closure) bats coverage in tests/scripts/check-three-gap-supergate.bats — 3 new tests (PASS / goals-validate FAIL / flywheel-proof SKIP). Suite: 15 → 18 tests.
  • Fixed: three-gap-supergate goals-validate sub-gate — pre-clean /tmp/ao-sg before go build -o /tmp/ao-sg so Go doesn't refuse to overwrite a non-object file. Caught by ao goals measure (1 failing → 0 failing).

Dead-Code Sweep

  • Removed: defrag.SweepOscillatingGoals + 5 helpers + CountAlternations + CycleRecord + OscillationResult + OscillatingGoal types + DefragReport.Oscillation field + defragOscillationSweep flag + 9 tests (soc-1q1x path 1, 17 / 465 ratio).
  • Removed: 43 additional staticcheck U1000 findings across cli/ (multiple cycles 156–159 sweeping soc-k083 backlog).

Internal: DDD/Hex Rescope Arc + Learnings Catalog

  • Changed: 13-cycle DDD/hex rescope arc closed; phase-1 complete + phase-2 retrospective (docs/rescope/2026-05-13-ddd-hex-architecture-rescope.md).
  • Added: BC-ports phase-2 narrowness post-mortem (docs/learnings/2026-05-13-bc-ports-narrowness-postmortem.md).
  • Added: empirical /loop context-drift study over 87+ cycles (docs/learnings/2026-05-13-loop-context-drift-87-cycle-observation.md).
  • Added: CLI-wiring cycle-shape template (docs/learnings/2026-05-13-cli-wiring-cycle-shape.md).
  • Added: learnings catalog README + when-to-add rubric.

See Also

  • Full per-commit detail: CHANGELOG.md (entries [2.41.0])
  • Release audit trail: docs/releases/2026-05-14-v2.41.0-audit.md
  • v2.40.0 notes: docs/releases/2026-05-13-v2.40.0-notes.md
Full changelog

Added

  • BC ports — 14/14 production-complete. FactoryAdmissionPort (13th, soc-2klg.1) + productionFactoryAdmission (cycle 139–140) and ClaimEvidencePort (14th, soc-2klg.2) + productionClaimEvidence (cycle 141–142) land the last two BC4 ports, closing the 14-port BC inventory begun in the v2.40.0 cycle. Each port follows the <port>.go + inmemory_<port>.go + inmemory_<port>_test.go triplet plus a productionX production adapter, with compile-time interface assertions as drift guards.
  • 10 typed-port-backed ao subcommands — operator-facing CLI now exposes every BC port that needs a script-side surface: ao loop history (productionLoopReader, cycle 144, slice 1 of soc-y5vh.5), ao ci latest/recent (productionCIStatus, cycle 145, slice 2), ao corpus inject (productionCorpusReader, cycle 146, slice 3; closes soc-y5vh.5), ao operator record/list (cycle 147 — template-applied 1st of 7), ao harness status (cycle 148), ao gate run (cycle 149), ao corpus capture (cycle 150, BC1 R/W pair complete on CLI), ao loop append (cycle 151, BC3 R/W pair complete on CLI), ao citation verify (cycle 152, BC1 round-trip), ao claim bind/list (cycle 153, 10th adapter CLI-exposed). Establishes a reusable cycle-shape captured in docs/learnings/2026-05-13-cli-wiring-cycle-shape.md.
  • ao loop verify — audits .agents/evolve/cycle-history.jsonl integrity via the typed BC3 LoopReaderPort (uses cycle-161 widening). Operator-facing health check on the loop ledger.
  • CycleEntry.StartedAt + Title fields (soc-ckc4, ports widening at cycle 161 + writer-side round-trip at cycle 162). Enables the ao loop verify audit and richer downstream consumers of the cycle ledger.
  • BC3 LoopReaderPort operator wrapper — scripts/evolve-read-cycle-history.sh provides recent [N] / latest / range START END modes around ao loop history, replacing inline tail/awk/jq shell-outs over the raw .agents/evolve/cycle-history.jsonl (soc-y5vh.4). Three migrated callsites: skills/evolve/references/convergence-mechanics.md Mechanism 1, skills/evolve/references/oscillation.md oscillation counter, and skills/evolve/references/fitness-scoring.md Oscillation Detection block (soc-lghj).
  • Supergate Gap 3 (loop-closure) bats coverage — tests/scripts/check-three-gap-supergate.bats extended with three tests (happy-path PASS, goals-validate FAIL, flywheel-proof SKIP) using a PATH-shimmed go that produces a controlled /tmp/ao-sg (soc-wxh5.3). Suite goes 15 → 18 tests; closes the cycle-63 Gap 3 deferral.
  • Mandatory STEP 1.7.5 release-readiness gates in /validation — auto-detects release context from branch name (release/*, v*-prep, v*-evolve-run, v\d+\.\d+*) or --release-context flag and requires scripts/pre-push-gate.sh (full, not --fast), scripts/ci-local-release.sh, and scripts/generate-cli-reference.sh cleanliness check when CLI surface changed. Validation refuses to recommend /release until all three pass. Codex parity synced.
  • /evolve teardown pre-release checklist — when the loop runs on a release-shaped branch, the teardown report emits an explicit unchecked checklist (regen CLI docs, full pre-push, ci-local-release.sh, optional smoke run) instead of recommending /release. The handoff artifact carries the checklist verbatim; "ready to tag" means boxes checked, not cycles green.
  • Acceptance-Text vs Delivered Drift audit in /post-mortem closure-integrity check — for each closed child, parses the bead Acceptance: section, extracts named gates, and WARNs when the close-note does not confirm the gate ran green. Catches the failure mode where a bead's acceptance language drifts from delivered evidence (origin: cycle 182 soc-w6vh.4).
  • .agents/operator/ write-surface contract entry — docs/contracts/agents-write-surfaces.md now documents the BC4 OperatorPort durable-intent log (allowlist + classification row, lifecycle=rolling, writer=cli).

Changed

  • /evolve Step 0 prior-knowledge retrieval now routes through the typed BC1 CorpusReaderPort (cli/cmd/ao/corpus_reader_adapter.go, cycle 112 productionCorpusReader) via ao corpus inject instead of the legacy ao lookup shell-out (soc-y5vh.1). Skill text in skills/evolve/SKILL.md and skills-codex/evolve/SKILL.md synced; codex hashes regenerated.
  • /evolve Step 1.5 healing-first classifier now routes through the typed BC2 CIStatusPort (cli/cmd/ao/ci_status_adapter.go, cycle 117 productionCIStatus) via ao ci recent --limit 1 instead of an inline gh run list --workflow validate.yml --json conclusion (soc-y5vh.2). Both callsites (skills/evolve/SKILL.md + skills/evolve/references/convergence-mechanics.md) updated in lockstep. Zero remaining inline gh shell-outs in /evolve's hot read path.
  • cli/cmd/ao coverage floor raised back to 76 % in scripts/check-cmd-ao-coverage.sh after real statement coverage climbed to 76.1 % (23553/30953) on the v2.41-evolve-run baseline (soc-wxh5.1). The cycle-60 recalibration to 75 % is reversed.
  • /evolve session-state refresh at Step 0 so the dormancy gate stays correct after long-running cycles harvest follow-ups (cycle 171 retrospective fix).
  • /release skill refactor — moved Examples + Troubleshooting + the non-HEAD cut-version logic into references/release-workflow-detail.md to bring SKILL.md back under the tier=execution size limit. Behavioral surface unchanged; cycle 169 post-mortem restoration commit restored Examples and Troubleshooting after the initial extraction.

Fixed

  • three-gap-supergate goals-validate sub-gate — scripts/check-three-gap-supergate.sh now rm -f /tmp/ao-sg before go build -o /tmp/ao-sg. Go refuses to overwrite a non-object file at the build-output path, so any prior process that wrote a non-binary to /tmp/ao-sg (including the bats-test shim go) would otherwise wedge the gate. The bats teardown in tests/scripts/check-three-gap-supergate.bats also cleans /tmp/ao-sg to remove test pollution. Caught by ao goals measure (1 failing → 0 failing) — first validation that the new STEP 1.7.5 mechanical gate works on real drift.

Removed

  • Dead defrag.SweepOscillatingGoals function and all callers (soc-1q1x path 1). The function read .agents/evolve/cycle-history.jsonl for entries with a target field; zero entries have ever had one in production, so callers (runCompileDefrag, runDefragPhases, runDreamDefragPreview) always got empty results. Net removal: 6 files, 17 insertions / 465 deletions — SweepOscillatingGoals + 5 helpers + CountAlternations + CycleRecord + OscillationResult + OscillatingGoal types + DefragReport.Oscillation field + defragOscillationSweep flag + --oscillation-sweep CLI flag + 9 tests. Build green; 11924 tests pass.
  • 43 dead-code findings swept from cli/ — across multiple cycles (156 cleared 10 staticcheck U1000 findings, 157 swept 18 more, 158 swept 10 more, 159 swept 5 more from soc-k083). Closes long-standing static-analysis backlog; LoadCycleHistory deletion (cycle 156) was the canonical example of the dead-code pattern that soc-1q1x later applied to oscillation-sweep.

Internal

  • DDD/Hex architecture rescope arc — 13 cycles closed. Phase-1 complete + phase-2 retrospective (docs/rescope/2026-05-13-ddd-hex-architecture-rescope.md); test-architecture-debt analysis reconciled to deletions; BC ports phase-2 narrowness post-mortem captured (docs/learnings/2026-05-13-bc-ports-narrowness-postmortem.md).
  • Learnings catalog hygiene — README + when-to-add rubric (cycle 134), empirical /loop context-drift study over 87+ cycles (cycle 135), BC-ports wire-up arc retrospective (cycle 122), CLI-wiring cycle-shape template (cycles 144–146), substring sed-rename overreach warning.
  • Contract drift resolution — soc-5yuy drift #5 resolved via audit; cli-skills-map.md refreshed to 70 generated CLI command headings for v2.41-prep BC-arc commands.

Full Changelog: v2.40.0...v2.41.0

Assets 12
Loading