## What
Operator-authorized (Bo, 2026-06-02). Strips the remaining **Gas City**
(`gastown`) coupling from AgentOps and reconciles the **split-doctrine
state** on `main` that the #672–#676 post-mortem flagged: canonical docs
(#676) said NTM+MCP+managed-agents while user-facing docs still
described Gas City as the reference substrate.
The out-of-session substrate is now uniformly **NTM** (local tmux swarm)
+ **MCP** (`ao mcp serve`, shipped) + **managed-agents** (`ao agent`).
AgentOps adopts a substrate; it owns none. Closes **ag-124p** (and
resolves **ag-h93p** — the claude.json gc-hook decouple).
## Deleted (load-bearing surfaces, per the bead's verified scope)
- `packs/agentops/` (the reference City) + root `city.toml`
- `skills/using-gc` + `skills-codex/using-gc` (+
`tests/scripts/using-gc-skill.bats`)
- `gc prime/nudge/mail/hook` wiring in `cli/hooks/claude.json` → now
hookless, matching 3.0 doctrine
## Doc sweep (the split-doctrine fix the post-mortem required)
- **README.md, docs/MIGRATION-3.0.md, docs/dependencies.md,
docs/activation-profiles.md** re-narrated to the substrate trio (the
four files the verdict named)
- AGENTS.md / CLAUDE.md substrate bullets; `dream` skill (+codex twin)
retirement pointer; `shared` / `agent-native` / `using-agentops`
cross-refs; skill-dispositions, context-map, sku-catalog, google-sre
convergence map
## Regenerated derived surfaces
Skill counts (81→80), `registry.json`, `skills/catalog.json`,
context-map, skill-domain-map, codex hashes (14) + manifest, SKILL-TIERS
— all via the generators, validated drift-free.
## Scope boundaries / follow-ups
- **`cli/internal/doctor/fix_bridges.go`** still carries a gc-bridge
detector/fixer subsystem. Out of the bead's verified scope; degrades
gracefully (stat-checks, returns empty when `gc`/`city.toml` absent);
removing it is a test-backed Go change → **follow-up bead**.
- **CLAUDE.md "Gas City bridge — REMOVED"** note kept intentionally:
it's an anti-re-coupling record, not substrate-framing.
- The local-only **bd-closeout** pre-push check (not in CI) is a
pre-existing gap on `main` (its AGENTS.md has no `bd dolt push` line) —
untouched here.
- `thesis-stability` gate FAIL, if present, is the pre-existing
README/PRODUCT/GOALS tagline drift, unrelated to this PR (my
README/PRODUCT edits are the dependency table + skill-count numbers, not
the tagline).
## Verification
`go build ./...` + `go vet` green · skill schema (80/80) + integrity
(heal --strict clean) + lint suite (0 fail) + codex parity green ·
sku-catalog & context-map drift gates green · zero broken markdown links
to deleted paths.
Closes-scenario: ag-124p#gc-coupling-strip
Bounded-context: BC5-Runtime
Evidence: docs/MIGRATION-3.0.md
## What
Builds the GC on-ramp for AgentOps 3.0: a `using-gc` skill that guides
agents on the `gc` (Gas City) CLI exactly like the `bd` protocol guides
them, plus a complete, accurate tool-dependency declaration. **Additive
— no existing behavior changed.**
THE MODEL (operator): "use gc like we use bd" — skills GUIDE agents on
the gc workflow; `ao` does NOT wrap gc. gc is a guided out-of-session
dependency, same as bd.
## Changes
1. **New skill `skills/using-gc/`** — agent-facing guide to running
AgentOps on Gas City, mirroring the bd-protocol style. Covers the gc
primitives (City/`city.toml`, Rig, Pack, Agent, Order, Formula, mayor +
refinery), the end-to-end workflow (`gc start` → `gc rig add` → the
mayor-driven dispatch loop: `bd ready` → `gc sling <rig>/refinery
<bead>` → worker runs `ao rpi <bead>`), cron `exec` Orders for
maintenance (`ao compile`/`ao maturity`), and is HONEST about the
order-auto-dispatch gap (no per-fire var-binding → dispatch is
mayor-driven today; order-auto-dispatch is an upstream-GC item,
soc-5jwah). References the real pack at `packs/agentops/` and
`docs/3.0.md`. Two reference docs + a `.feature` (linked +
`@covered-by:` a new bats test).
2. **Complete dependency declaration** — derived from `ao doctor` tool
checks (`ao`, `awk`, `bash`, `bd`, `cass`, `gc`, `git`, `tmux`) +
`scripts/install*.sh` + the shared fallback table. Classified REQUIRED
(ao, git, runtime), TRACKING (bd + Dolt), ORCHESTRATION (gc,
out-of-session), PR/CI (gh), BUILD-FROM-SOURCE (go), UTILITIES (jq, rg,
curl, openssl, sha256sum, tmux, cass). Landed in: `docs/dependencies.md`
(canonical detail, catalogued in documentation-index), a README
"Requirements" section (summary), and the expanded
`skills/shared/SKILL.md` fallback table (now includes gc, gh, go, jq,
rg).
3. **Fixed stale `using-agentops/SKILL.md:212`** — the runtime-mode `gc`
row described the DELETED `runtime=gc` auto-executor ("ao rpi
auto-selects gc executor", "gc event bus"). Reframed to the mayor-driven
reference City: gc dispatches whole `ao rpi`/`ao evolve` loops; there is
no in-CLI `runtime=gc` mode.
4. **Brief gc pointer** in repo `CLAUDE.md` + `AGENTS.md` near the bd
section, pointing to the using-gc skill (no skill content duplicated).
## Gates (all green locally)
- `sync-skill-counts.sh`: 80→81 total, 9→10 internal — PASS, verified
consistent.
- `validate-context-map-drift`: regenerated
docs/contracts/context-map.md — matches.
- Codex twin `skills-codex/using-gc/` created (`$skill` notation, no
Claude primitives); registered across the 4 catalog surfaces;
`regen-codex-hashes.sh` clean; `audit-codex-parity` PASS; 81 codex
artifacts.
- `generate-registry.sh` (81 skills) — up to date.
- skill-domain-map disposition added (BC5 Runtime) + regenerated golden
— matches; registry-drift narrative counts fixed (80→81).
- plugin-load-test (no symlinks — references copied), skill-schema
(81/81), skill-frontmatter (81/81), skill-dependency-check, heal.sh
--strict (clean), scenario-test-linkage (PASS, new .feature linked via
bats), markdownlint (0 errors), doc-release-gate (PASS).
- New bats test `tests/scripts/using-gc-skill.bats` (5/5).
- Codex description aggregate budget bumped 2700→2800 (catalog grew to
81; same precedent as the 2600→2700 bump when expert-council landed).
- `cd cli && go build && go vet && go test ./cmd/ao/` green (embedded
using-agentops copy synced via `make sync-hooks`).
Closes-scenario: ag-p4p#gc-onramp
Bounded-context: BC5-Runtime
Evidence: skills/using-gc/SKILL.md
## What
New file: `skills/shared/references/cross-harness-skill-parity.md` (155
lines) + 1-line References-list entry in `skills/shared/SKILL.md`.
Codifies: a skill must carry the same **intent, knowledge, BDD/Gherkin,
and observable behavior** across Claude Code and Codex. Only the
*implementation* adapts. `audit-codex-parity.sh` green is
necessary-not-sufficient — a trimmed baseline is invisible to the audit.
## Why
The audit script enforces structural drift against the established
baseline, but if that baseline was itself a trimmed copy (9 of 19
reference files, omitting whole mechanisms like
convergence/healing/hypothesis tracking), the audit silently approves
the gap. This actually happened with the codex evolve skill (soc-y5vh.8
retro). The rule wasn't captured anywhere a future agent would find
before re-trimming.
## Sibling pattern
Follows `skills/swarm/references/shared-checkout-discipline.md` (PR
#333) shape.
## Fitness-delta
| Metric | Before | After |
|---|---|---|
| shared references | 51 | 52 |
| knowledge-parity rules anchored | 0 | 1 |
| codex frontmatter strictness rule | 0 | 1 |
| legitimate-vs-defect implementation adaptations table | 0 | 5 rows |
## Validation
- pre-push-gate.sh --fast: **passed (44 skipped)**
## Closes
Closes-scenario: soc-1wsr#knowledge-parity-rule
Evidence: skills/shared/references/cross-harness-skill-parity.md
## Provenance
Sources (2 anchored):
`.agents/learnings/2026-05-16-cross-harness-skill-parity.md` +
`.agents/learnings/2026-05-10-codex-frontmatter-is-strict-name-description.md`.
Narrower cross-harness-only scope (the other 3 'cross-vendor bucket'
learnings belong to different clusters: cross-vendor-duel-converges →
/council, claude-app-default-readonly → already in docs/contracts/,
cli-command-dual-generator → already CI-encoded).
Co-authored-by: Codex <codex@example.invalid>
## What
Mirrors `docs/learnings/2026-05-13-substring-sed-rename-overreach.md`
(from /evolve cycle 126) into `skills/shared/references/` so any skill
(/evolve, /crank, /refactor, /standards) can reference the pre-rename
checklist.
## Why
The substring-overreach rule was authored from a real cycle-126 bug
(`QueueClaim → QueueLease` sed caught 5 unrelated identifiers). It's
promoted in docs/learnings/ but no skill references it. Putting the
mirror in skills/shared/ makes it available cross-skill.
## Sibling pattern
Follows `skills/swarm/references/shared-checkout-discipline.md` (PR
#333) shape: Worked example → The Rule → Worked Pattern (bash) →
Anti-pattern Signal → When This Matters Most → See Also.
## Fitness-delta
| Metric | Before | After |
|---|---|---|
| shared references | 50 | 51 |
| pre-rename checklists cross-skill | 0 | 1 |
| worked rename anti-pattern examples | 0 | 4 |
## Validation
- pre-push-gate.sh --fast: **passed (43 skipped)**
## Closes
Closes-scenario: soc-sqof#cross-skill-mirror
Evidence: skills/shared/references/substring-rename-overreach.md
## Provenance
Cluster #5 of 2026-05-18 Track-C mining pass.
Co-authored-by: Codex <codex@example.invalid>
#275's billboard refactor thinned process-skill SKILL.md files and moved
detail into references/, but the validate contracts still grepped SKILL.md.
skill-lint + smoke-test: relax content-presence checks in crank/implement/
post-mortem/swarm validate.sh to scan the skill as a unit (SKILL.md +
references/); structural/identity checks stay SKILL.md-only. test-first-smoke
updated to match relocated SPEC/TEST WAVE + Step 0/4 headings.
skill-lint line caps: trim flywheel 310 -> 286 (cap 300), using-agentops
261 -> 239 (cap 250) by removing redundant prose, no content lost.
skill-integrity: link 3 orphaned references (crank/branch-isolation,
validation/flags + release-readiness-gates).
codex parity: regenerate stale skills-codex source hashes (77 skills).
Local: run-all.sh PASS, heal.sh --strict clean, smoke-test PASS.
Adds a 2400-char aggregate budget for skills-codex/*/SKILL.md `description:`
fields in tests/skills/test-token-budgets.sh, then trims each skill's description
to fit (catalog now 2146/2400). Both Claude and Codex SKILL.md descriptions
are kept in sync; codex .agentops-generated.json hashes regenerated.
Adds --repair-shape to scripts/audit-codex-hooks.sh: when ~/.codex/hooks.json
is missing or in legacy-flat shape, rewrites it from hooks/codex-hooks.json
with the active plugin_root (read from .agentops-codex-install.json) and
backs up any prior file. Covered by new test_repairs_legacy_flat_shape.
Memory decay (4 .agents/ files) bumped by the SessionStart inject hook.
CI failures from PR #150's first push:
1. codex-runtime-sections (validate-codex-generated-artifacts step)
"shared: manifest generated_hash drift detected"
"shared: marker generated_hash drift detected"
Cycle 7 edited skills-codex/shared/references/strict-delegation-contract.md
without regenerating the manifest hash. Ran scripts/regen-codex-hashes.sh
which updated hashes for 1 skill (shared).
2. bats-tests (tests/scripts/evolve-coverage-delta.bats)
The "parser uses the same regex anchors as the script" assertion grepped
the script for a literal regex string, but the test's escaping of the
literal didn't survive bats's preprocessor — the assertion failed even
though the script's regex was correct.
Replaced with an awk-based assertion that just confirms the script's
coverage extraction line still includes "grep -oE" + "coverage:" + the
"?%" anchor fragment. Robust against unrelated whitespace/quote shape
changes; still catches a regression that drops the % suffix.
Verified locally: full bats tests/scripts/*.bats and tests/hooks/*.bats
suites green; validate-codex-generated-artifacts.sh passes.
Codex DAG steps in skills-codex/ should use Codex's \$skill invocation
syntax, not Claude's Skill() tool form. The shared
strict-delegation-contract.md mirror still carried 12 Skill() references,
flagged by the vibe judge on 2026-04-19.
Rewrites in skills-codex/shared/references/strict-delegation-contract.md:
- Skill(skill="<name>", ...) → \$<skill> <args> (matches converter.sh's
rule: s/Skill\(skill="([^"]+)"...)/$1 \$2/)
- Three concrete examples in the Positive Pattern section now show
\$discovery, \$crank, \$validation invocations (not Skill(skill=...))
- Anti-Pattern section talks about Codex sub-agent spawns (not Agent())
since that's the closest Codex equivalent
- Anti-Pattern table renames "Skill() vs Agent()" → "Codex sub-agents
vs \$<skill> invocations" with corresponding cell updates
Verification:
- skills/shared/references/strict-delegation-contract.md (Claude variant)
is unchanged — still uses Skill() syntax which is correct for Claude
- bash scripts/audit-codex-parity.sh → passed
- bash skills/heal-skill/scripts/heal.sh --strict → clean
Closes the council-finding next-work item:
"Sweep skills-codex/ DAG bodies for Skill() to \$skill notation"
doc-release-gate was failing because skills/rpi/SKILL.md and siblings link
to .agents/learnings/2026-04-19-orchestrator-compression-anti-pattern.md
which lived only in a local gitignored dir. Force-add the file (other
learnings in .agents/learnings/ are force-added too).
codex-runtime-sections was failing because skills-codex/shared/SKILL.md
was edited in 2385dbd4 to link the strict-delegation contract but the
manifest hash wasn't regenerated. Run scripts/regen-codex-hashes.sh.
Also force-add .agents/learnings/2026-04-19-quick-strict-delegation-70min-meta-change.md
(referenced from the 2026-04-19 post-mortem report; same ignored-dir issue).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## doc-release-gate (link validation)
- tests/docs/validate-links.sh: fix canonical-path assignment bug where
inline `|| fallback` never fires if the outer $() assignment itself
does not fail. Rewrite as explicit if-else so mkdocs-generated paths
(docs/skills/*.md, docs/cli/*.md) resolve correctly in CI environments
where those directories don't exist on disk.
## skill-lint + skill-integrity + go-build (TestSkillContract_ReferencesLinkedInSKILLMD)
- Add strict-delegation-contract.md link to skills/shared/SKILL.md and
skills-codex/shared/SKILL.md Reference Documents sections (heal.sh
--strict requires every references/*.md to be linked in its SKILL.md).
- Extend tests/skills/lint-skills.sh regex to support ../shared/references/
paths in addition to skills/<name>/references/ — matches heal.sh behavior.
## markdownlint
- Disable MD030 (list-marker-space) in .markdownlint.json. Material theme
grid-cards syntax uses 3 spaces after `-` which is standard for multi-line
items; markdownlint default of 1 space conflicts. 61 violations → 0.
## contract-compatibility-gate + smoke-test (next-work parity)
- .agents/rpi/next-work.jsonl: fix invalid enum values for the
2026-04-19-rpi-dag-hardening entry. Type "enhancement" → "process-improvement",
source values normalized to valid enum (council-finding, retro-learning,
backlog-processing).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Docs site — boshu2.github.io/agentops
- Replace Jekyll minima with MkDocs Material (slate dark palette default)
- Landing hero scoped to .landing-hero (no gradient bleed on inner pages)
- Section landings (getting-started, architecture, reference, contracts, levels) with narrative ledes
- Generate skill catalog + per-skill pages from skills/*/SKILL.md at build
- Generate CLI reference from cli/docs/ at build (fails build on missing source)
- Fix every internal link via one-shot migration (scripts/migrations/2026-04-19-fix-docs-links.py)
- Wire mkdocs build --strict into pre-push gate (Check 25a)
- Replace .github/workflows/pages.yml with .github/workflows/docs.yml (actions/deploy-pages)
- README + docs/CONTRIBUTING updated with docs-build toolchain on-ramp
- tests/docs/validate-links.sh patched to understand mkdocs-generated paths
## RPI orchestrator strict-delegation contract
- Strict sub-skill delegation is now the default for /rpi, /discovery, /validation. No --full flag — always on.
- Canonical contract in skills/shared/references/strict-delegation-contract.md (plus Codex mirror)
- Forged learning with detection phrases + corrective actions (ao-inject-ready)
- Rename --no-lifecycle -> --no-scaffold in /discovery (Claude + Codex) with deprecation alias through v2.40.0
- Harden inline-work hotspots with orchestrator-owned markers in /crank STEPS 3a.3, 6.5, 8.7 + Inline Work Policy footer
- Flag consistency: --auto and --interactive scopes documented; --complexity syntax formalized
- CHANGELOG [Unreleased] documents + scaffolds; runtime hook enforcement explicitly deferred
## fix(hooks): go-test-precommit skips when no Go files staged
- Previously ran go vet + go build unconditionally, blocking non-Go commits when Go toolchain was missing or at a different version
- Now checks staged diff and exits cleanly if no *.go or go.{mod,sum,work} files are staged
- Applied to both hooks/ (source) and cli/embedded/hooks/ (synced)
Provenance: full RPI lifecycle with strict delegation at every phase boundary (Phase 1 Skill(discovery) -> Phase 2 Skill(crank) -> Phase 3 Skill(validation) -> Skill(vibe), Skill(post-mortem), Skill(retro)).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Inspired by patterns discovered in Claude Code's npm source map leak:
- Add hook failure budget to lib/hook-helpers.sh (MAX_CONSECUTIVE_HOOK_FAILURES=3,
configurable via AGENTOPS_HOOK_FAILURE_CAP) — prevents runaway hook loops
- Add metadata.stability field (experimental|stable) to skill frontmatter schema
with heal.sh validation (H010) and skill-conventions documentation
- Add quality-signals.sh hook detecting repeated prompts and correction patterns,
logging to .agents/signals/session-quality.jsonl with defined schema
- Document orchestration-as-prompt as a first-class pattern in shared references,
linked from crank, swarm, evolve, rpi skills with codex parity
The regen-codex-hashes.sh auto-copy feature copied reference files
containing Claude-specific primitives (TeamCreate, backend-claude-teams)
into codex skills, causing parity audit failures. Revert the script
change and remove all auto-copied files. Keep only the reviewer-config
example that was intentionally created.
- Auto-copy references to skills-codex in regen-codex-hashes.sh
- Add line-count check and codex parity step to plan template
- Add --fast-path flag to plan Flags table
- Create reviewer-config-example.md for council
- Major rewrite of vs-gsd.md (GSD v1.27 is no longer lightweight)
- Moderate update of vs-compound-engineer.md (ideation, refresh, 10 runtimes)
- Add BF1/BF2/BF4 bug-finding level selection to implement, post-mortem, validation
- Delete orphaned backend-claude-teams.md from council, research, shared, swarm
- Remove dead references from research/SKILL.md, shared/SKILL.md
- Remove dead converter sed rule for backend-claude-teams.md rename
- Add Reference Documents section to swarm/SKILL.md
- Update swarm validate.sh to check only backend-codex-subagents
- plan/scripts/validate.sh: stop grepping for TaskList/TaskCreate,
check for generic task tracking instead
- swarm/scripts/validate.sh: stop grepping for TeamDelete, check for
generic cleanup patterns instead
- converter: rewrite top-level .md files (not just subdirectory .md),
fixes shared/validation-contract.md (was 12 Claude refs, now 0)
- Regen all 54 codex skills
- Full sweep: 0 Claude primitives across all codex files
Reference .md files in skills-codex/ were copied verbatim from source,
bypassing all converter rewrite rules. Now .md files in references/,
scripts/, and other subdirs are processed through codex_rewrite_text()
during passthrough copy.
Empirically validated: Codex agent confirms 0 Claude primitives in
converted reference files (was 107). Remaining gap: crank/swarm
orchestration patterns need full Codex-native rewrites (not converter
fixes) — tracked separately.
Validated with: codex exec -s read-only (gpt-5.4)
Bo