Align AgentOps around its operations-layer identity (#1051)

Executes docs/plans/2026-08-07-agentops-operations-layer-alignment.md:
AgentOps is the operations layer for agentic engineering; the federated
integration graph is the topology, the semantic work-and-proof protocol
is the contract, and RPI is the standard one-experiment traversal.

Retires the ao flywheel command family and all knowledge-flywheel
product state, tombstones the seven-move operating-loop workflow,
narrows ao init and the .agents state writers to declared destinations,
renames the core architecture page to rpi-traversal.md with a
compatibility redirect, aligns AGENTS.md, 25 skills, public and package
copy, regenerates every owned projection, and strengthens the
conformance gates with planted-negative proofs.

Both the alignment subject and the follow-up gate-bookkeeping commit
carry fresh author-distinct validation PASS verdicts with empty
not_checked scope.

Test-Removal-Reason: dead knowledge-flywheel and session-store surfaces were deleted with their tests (operations-layer alignment)

Author: boshu2

.claude-plugin/marketplace.json

@@ -5,13 +5,13 @@
     "email": "fullerbt@users.noreply.github.com"
   },
   "metadata": {
-    "description": "Fresh-context validation for coding-agent work: one behavior, one bounded experiment, one independent verdict.",
+    "description": "The operations layer for agentic engineering: portable skills and evidence contracts connecting intent, coding agents, software factories, and independent judgment.",
     "version": "3.5.0"
   },
   "plugins": [
     {
       "name": "agentops",
-      "description": "Fresh-context validation for coding-agent work: one behavior, one bounded experiment, one independent verdict.",
+      "description": "The operations layer for agentic engineering: portable skills and evidence contracts connecting intent, coding agents, software factories, and independent judgment.",
       "version": "3.5.0",
       "source": "./",
       "author": {

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentops",
   "version": "3.5.0",
-  "description": "Fresh-context validation for coding-agent work: shape one behavior, run one bounded experiment, and persist an independent verdict.",
+  "description": "The operations layer for agentic engineering: portable skills and evidence contracts connecting intent, coding agents, software factories, and independent judgment.",
   "author": {
     "name": "Boden Fuller",
     "email": "fullerbt@users.noreply.github.com"
@@ -10,12 +10,12 @@
   "repository": "https://github.com/boshu2/agentops",
   "license": "Apache-2.0",
   "keywords": [
+    "operations-layer",
     "devops",
     "vibe-coding",
     "shift-left",
     "validation",
     "coding-agents",
-    "knowledge-flywheel",
     "pre-mortem",
     "vibe-check",
     "workflow",

.codex-plugin/plugin.json

@@ -1,12 +1,12 @@
 {
   "name": "agentops",
   "version": "3.5.0",
-  "description": "Fresh-context validation for coding-agent work: shape one behavior, run one bounded experiment, and persist an independent verdict.",
+  "description": "The operations layer for agentic engineering: portable skills and evidence contracts connecting intent, coding agents, software factories, and independent judgment.",
   "skills": "./skills-codex",
   "interface": {
     "displayName": "AgentOps",
-    "shortDescription": "Fresh-context validation for coding-agent work.",
-    "longDescription": "AgentOps helps Codex shape one behavior, run one bounded implementation experiment, validate the exact result from fresh context, and persist a durable verdict. Git, CI, retries, queues, and delivery remain caller-owned.",
+    "shortDescription": "The operations layer for agentic engineering.",
+    "longDescription": "AgentOps connects intent, coding agents, software factories, context sources, and independent judgment through portable skills and evidence contracts. Codex shapes one behavior, runs one bounded implementation experiment, validates the exact result from fresh context, and can persist a durable verdict. Git, CI, retries, queues, and delivery remain caller-owned.",
     "developerName": "AgentOps",
     "category": "Productivity",
     "capabilities": [

.codex/agentops-bootstrap.md

@@ -25,7 +25,6 @@ When skills reference tools you don't have, substitute your equivalent tools:
 - Announce: "I've read the [Skill Name] skill and I'm using it to [purpose]"
 - Skills with checklists require `update_plan` todos for each item
 - NEVER skip mandatory workflows (brainstorming before coding, TDD, systematic debugging)
-- At the end of a Codex work session, run `~/.codex/agentops/.codex/agentops-codex session-end` to execute flywheel close-loop.
 
 **Skills location:**
 - AgentOps skills: ~/.codex/agentops/skills/

.codex/agentops-codex

@@ -295,69 +295,10 @@ function runUseSkill(skillName) {
 }
 
 function runSessionEnd() {
-    // Codex doesn't consume Claude plugin hooks.json, so this provides an equivalent
-    // end-of-session close-loop entrypoint.
-    const repoRootResult = spawnSync('git', ['rev-parse', '--show-toplevel'], {
-        encoding: 'utf8'
-    });
-
-    const repoRoot = repoRootResult.status === 0
-        ? repoRootResult.stdout.trim()
-        : process.cwd();
-
-    function commandExists(cmd) {
-        const check = spawnSync('sh', ['-lc', `command -v ${cmd} >/dev/null 2>&1`], { cwd: repoRoot });
-        return check.status === 0;
-    }
-
-    function runAo(args) {
-        const localBin = path.join(repoRoot, 'bin', 'ao');
-        if (fs.existsSync(localBin)) {
-            return spawnSync(localBin, args, { cwd: repoRoot, encoding: 'utf8' });
-        }
-
-        const localCliDir = path.join(repoRoot, 'cli');
-        const localGoMod = path.join(localCliDir, 'go.mod');
-        if (fs.existsSync(localGoMod) && commandExists('go')) {
-            return spawnSync('go', ['run', './cmd/ao', ...args], {
-                cwd: localCliDir,
-                encoding: 'utf8'
-            });
-        }
-
-        if (commandExists('ao')) {
-            return spawnSync('ao', args, { cwd: repoRoot, encoding: 'utf8' });
-        }
-
-        return { status: 127, stderr: 'ao CLI not found' };
-    }
-
-    let closeLoop = runAo(['flywheel', 'close-loop', '--quiet']);
-    if (closeLoop.status !== 0 && closeLoop.stderr && closeLoop.stderr.includes('unknown flag: --quiet')) {
-        closeLoop = runAo(['flywheel', 'close-loop']);
-    }
-
-    if (closeLoop.status === 0) {
-        console.log('Codex session-end close-loop complete.');
-        return;
-    }
-
-    // Mirror hook failure logging behavior.
-    try {
-        const aoDir = path.join(repoRoot, '.agents', 'ao');
-        fs.mkdirSync(aoDir, { recursive: true });
-        const logPath = path.join(aoDir, 'hook-errors.log');
-        const ts = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
-        fs.appendFileSync(logPath, `${ts} CODEX_SESSION_END_FAIL: ao flywheel close-loop\n`, 'utf8');
-    } catch (error) {
-        // Best-effort logging; still print command failure details below.
-    }
-
-    console.log('ao flywheel close-loop failed during Codex session-end.');
-    if (closeLoop.stderr) {
-        console.log(closeLoop.stderr.trim());
-    }
-    process.exit(1);
+    // The knowledge-flywheel close-loop was retired with the ao flywheel
+    // command family; session-end is now an explicit no-op kept for
+    // compatibility with existing Codex session hooks.
+    console.log('Codex session-end: nothing to do (the flywheel close-loop was retired).');
 }
 
 // Main CLI
@@ -383,7 +324,7 @@ switch (command) {
         console.log('  agentops-codex bootstrap              # Run complete bootstrap with all skills');
         console.log('  agentops-codex use-skill <skill-name> # Load a specific skill');
         console.log('  agentops-codex find-skills            # List all available skills');
-        console.log('  agentops-codex session-end            # Codex equivalent of Stop hook close-loop');
+        console.log('  agentops-codex session-end            # Compatibility no-op (close-loop retired)');
         console.log('');
         console.log('Examples:');
         console.log('  agentops-codex bootstrap');

.goreleaser.yml

@@ -44,7 +44,7 @@ brews:
   - name: agentops
     directory: Formula
     homepage: https://github.com/boshu2/agentops
-    description: Knowledge Flywheel CLI for AI-assisted development
+    description: Optional AgentOps CLI for deterministic repository checks and evidence linking
     license: Apache-2.0
     install: |
       bin.install "ao"

.opencode/plugins/agentops.js

@@ -6,7 +6,7 @@
  *   2. tool.execute.before — Guard task tool crash (sst/opencode#13933)
  *   3. tool.definition — Enrich task + skill tool descriptions for Devstral
  *   4. command.execute.before — Redirect slashcommand skill calls to skill tool
- *   5. tool.execute.after — Audit log all tool calls to .agents/audit/
+ *   5. tool.execute.after — Audit log all tool calls to .agents/scratch/opencode-audit/
  *   6. shell.env — Inject CLI paths (bd, ao, gt, cass) into shell environment
  *   7. experimental.session.compacting — Preserve AgentOps context through compaction
  */
@@ -85,7 +85,7 @@ export const AgentOpsPlugin = async ({ client, directory }) => {
   const cliPathDirs = findCliPaths(homeDir);
 
   // Audit log helper
-  const auditDir = path.join(directory || process.cwd(), '.agents', 'audit');
+  const auditDir = path.join(directory || process.cwd(), '.agents', 'scratch', 'opencode-audit');
   const getAuditPath = () => {
     const date = new Date().toISOString().slice(0, 10);
     return path.join(auditDir, `${date}-opencode.jsonl`);
@@ -163,7 +163,7 @@ ${toolMapping}
     'complexity', 'knowledge', 'bug-hunt', 'doc', 'handoff', 'learn',
     'release', 'product', 'quickstart', 'trace', 'inbox', 'recover',
     'evolve', 'codex-team', 'beads', 'standards', 'inject', 'extract',
-    'forge', 'provenance', 'ratchet', 'flywheel', 'update', 'using-agentops'
+    'forge', 'provenance', 'ratchet', 'update', 'using-agentops'
   ];
 
   return {

AGENTS.md

@@ -2,7 +2,13 @@
 
 Detailed workflow mechanics: [docs/agent-workflow-reference.md](docs/agent-workflow-reference.md).
 
-AgentOps turns one explicit intent into one independently judged experiment:
+AgentOps is the operations layer for agentic engineering: a portable semantic
+integration and judgment layer that connects intent, coding agents, software
+factories, context sources, and independent validation without taking
+ownership of their state or delivery lifecycle. The topology is a
+federated integration graph; the interoperability contract is the
+semantic work-and-proof protocol; the standard path through the graph is one
+RPI traversal:
 
 ```text
 RPI -> Plan -> Implement -> fresh Validate -> report and stop
@@ -50,6 +56,22 @@ what the caller does next.
 - Do not run `ao session bootstrap`, lookup, or archive commands as startup
   ritual. The `ao` CLI is an explicit repository tool, not a session runtime.
 
+## Federated source authority
+
+The integration graph is federated: AgentOps cites source identities and never
+absorbs their authority.
+
+| Information | Authority | AgentOps treatment |
+|---|---|---|
+| Work, status, dependencies, close reasons | Beads or the caller's tracker | Query directly; never build a second work index. |
+| Source content and delivery history | Git and repository policy | Bind exact content when useful; a commit or merge never implies semantic PASS. |
+| Past agent sessions | CASS | Retrieve cited episodes on demand; search output is evidence, not policy. |
+| Curated cross-session memory | CM or a caller-selected memory system | Retrieve by explicit need with provenance and freshness. |
+| Runtime execution | NTM, Gas City, Agent Mail, cloud agents, or another selected factory | Read and report native state; runtime completion is never validation. |
+| Checks and test output | The executable that produced them | Store factual receipts; a fresh context judges meaning. |
+| Requested proof | `.agents/ao/` | Persist only for a caller request or declared consumer. |
+| Disposable and derived local state | `.agents/scratch/`, `.agents/projections/` | Rebuild or expire; never treat as authority (ADR-0016). |
+
 ## Source precedence
 
 1. live executable behavior and generated projections from their declared source;
@@ -71,7 +93,7 @@ Edit source owners and regenerate projections through the owning command.
   `scripts/check-skill-python-ratchet.sh`; tests keep their documented
   exemption). Grandfathered Python is migration debt, not precedent.
 
-## Core loop
+## Standard RPI traversal
 
 1. **Plan once.** Resolve the existing bead or caller intent and shape one
    active behavior there. Acceptance, non-goals, scope, and the first useful
@@ -117,8 +139,10 @@ rollback, and release policy.
 
 Premortem, Postmortem, Council, and genie skills are caller-selected judgment
 strategies. NTM, Agent Mail, Gas City, swarms, and other factory tools are
-optional adapters. Optional strategies and adapters never become core
-dependencies or lifecycle authorities.
+optional adapters. Context miners (CASS, CM, recon tooling) are context
+sources. Strategies, adapters, factories, and context sources are peer nodes
+in the federated graph whose native state AgentOps reads but never owns; none
+becomes a core dependency or lifecycle authority.
 
 A selected factory's internal control plane is operated only through that
 factory's own doors: its coordinator (for Gas City, the Mayor via mail), its
@@ -141,7 +165,7 @@ AgentOps work ownership.
 
 | Trigger | Canonical owner |
 |---|---|
-| Core loop or evidence-contract change | `docs/architecture/operating-loop.md`, `schemas/*.schema.json` |
+| RPI traversal or evidence-contract change | `docs/architecture/rpi-traversal.md`, `schemas/*.schema.json` |
 | CLI command or flag | `cli/cmd/ao/`, then generated `cli/docs/COMMANDS.md` |
 | Skill behavior or inventory | `skills/<slug>/SKILL.md`, generated `docs/SKILL-ROUTER.md` |
 | Codex projection | `docs/contracts/codex-skill-api.md`, `skills-codex-overrides/catalog.json` |

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+
+- The `ao flywheel` command family (`status`, `compare`) and the whole live
+  knowledge-flywheel product surface: `cli/internal/flywheelapp`, the
+  flywheel-only metric helpers and types, the `flywheel` build-profile bit,
+  the `flywheel-compounding` gate scripts, and the `flywheel:` config block
+  (existing config files still parse; the key is ignored). AgentOps no longer
+  computes or reports knowledge-compounding state (`COMPOUNDING`, `DECAYING`,
+  escape velocity). Invoking `ao flywheel` now fails with a migration pointer
+  (see `docs/MIGRATION.md`). Learning remains an optional off-path consumer of
+  durable verdicts via the `learn` skill. The compatibility baseline records
+  the family as intentionally `retired` rather than freezing the old product
+  claim.
+
 ### Added
 
 - Between-releases release-path smoke: `.github/workflows/release-path-smoke.yml`

GOALS.md

@@ -2,8 +2,9 @@
 
 ## Product outcome
 
-AgentOps makes one coding-agent experiment independently inspectable without
-taking over the consumer's engineering system.
+AgentOps is the operations layer for agentic engineering: it makes one
+coding-agent experiment independently inspectable without taking over the
+consumer's engineering system.
 
 The canonical outcome is: