Surfaces the methodology site at the top of the README (newcomer line)
and removes the dead `boshu2.github.io/agentops/` link from the docs row
— that Pages site was unbuilt (`status: null`) and has now been
disabled, so 12factoragentops.com is the canonical home. The doctrine
link in that row already points there.
## What
`/dream` is **retired** — `skills/dream/SKILL.md` frontmatter: *"Retired
pointer — out-of-session compounding moved to the substrate (NTM + MCP +
managed-agents)."* The README still presented it as a live skill in two
places:
1. Skills table row `| /evolve · /dream | … |` — dropped `/dream`, kept
`/evolve` with an accurate one-line description.
2. "The corpus needs hygiene" limitation — dropped `/dream`, leaving `ao
defrag` + `ao maturity` (the in-tree hygiene surfaces).
Substrate-delegated compounding is already covered by the "In session
vs. out of session" paragraph.
## Scope
Narrow + cosmetic per the bead (ag-7vy): README only. The deeper
`/dream` doc reconciliation across `docs/**` is explicitly out of scope
(separate daemon-prose arc).
## Evidence
- `grep -c "/dream" README.md` → `0`
- `markdownlint -c .markdownlint.json README.md` → PASS
Closes-scenario: ag-7vy#dream-readme-scrub
Bounded-context: BC1-Corpus
Evidence: grep /dream README.md == 0; markdownlint PASS
## What
Restore the two Windows PowerShell install one-liners to README.md that
#754 ("tighten the README") abbreviated to comment fragments:
- `irm
https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-codex.ps1
| iex`
- `irm
https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-ao.ps1
| iex`
Restored in #754's tightened comment style (no prose re-expansion;
+5/-2).
## Why (queue-wide trunk red)
The executable distribution canary
`evals/agentops-core/distribution-install-update.json`
(`public-install-docs-current`, lines 117/119) asserts README.md
contains those **exact** strings via `artifact_contains`. #754 removed
them, so the canary now **fails on main** → **`contracts-sync` (full
9-suite) is red on every open PR** (confirmed on #755, whose own change
is clean). Source-of-truth precedence (per CLAUDE.md): the narrative
README must satisfy the executable contract.
ag-5uau. Unblocks #755 and any other PR red on contracts-sync.
## Validation
- Both exact canary strings now present (`grep -F` = 1 each); diff is
README-only (+5/-2); markdownlint clean.
- CI `contracts-sync` here is the authoritative check — it runs the
actual `distribution-install-update` canary.
## Note
Restoring required install commands to satisfy the declared contract;
#754's prose cuts elsewhere are untouched. If Windows install was meant
to be de-documented, the alternative is updating the canary instead —
flagged in ag-5uau. Not self-merged (cross-model quorum bus down).
Closes-scenario: ag-5uau#readme-install-oneliners
Bounded-context: BC2-Validation
Evidence: README.md
Replaces the See It Work hero with the final cut: real Claude Code
commands (/discovery → /crank → /validate --mixed), each followed by a
readable proof of its result (bead graph, sub-agent waves, live Claude +
Codex verdict), then the AgentOps card. Honest (real footage, synthetic
public demo, no PII). Source + reproducible rig in personal-site
assets/hero/.
## What
Drops dead `ao evolve` command references from agent-facing docs. The
`ao evolve` CLI was deleted in #724 (ag-llni); these docs still pointed
agents at it.
- `AGENTS.md` / `CLAUDE.md` / `README.md` / `docs/dependencies.md`: the
substrate-loop line `` `ao rpi`/`ao evolve` loop `` → keeps the **live**
`` `ao rpi` `` and drops the **dead** `` `ao evolve` ``.
- `README.md` quickstart: removed the dead `ao evolve --max-cycles 1`
example (loop is now the `/evolve` skill; `ao rpi phased` already covers
terminal lifecycle).
- In-session skill refs (`/rpi`, `/evolve`) preserved — those exist.
## Scope (ag-354d slice 1 of N)
Agent-facing docs only. **Excluded:** gate-protected plan docs
(`docs/reference/agentops-domain-evolution-{bdd,plan}.md`, hexagonal-map
— `check-agentops-domain-evolution-plan.sh` requires the literal);
obsolete runner scripts (coupled, separate slice); cron-template
(already done in #724).
## Gate
`markdownlint`: 0 errors on all 4 files. The 5 local pre-push-gate reds
(`test-fixture parity gc-stale-worktrees`, `worktree
disposition`/canonical-root-dirty, `corpus freshness` 7d snapshot,
goals-validate, CMDAO-surface) are **pre-existing/non-diff** — same set
SageHarbor classified in PR #730/#69; a docs-only change touches none of
those surfaces. CHANGELOG-sync + link-integrity passed.
Closes-scenario: ag-354d#doc-refs
Bounded-context: BC5-Runtime
Evidence: README.md
Adds the See It Work hero: a ~12s designed montage of **real Claude Code
+ Codex sessions** running the AgentOps loop end to end — discovery →
research → plan → crank → validate → `/council --mixed` (Claude + Codex)
→ merge — with stage labels, tick-tock pacing, and the CTA.
- Real terminal footage, label-matched per stage, banner/email redacted.
- gif autoplays inline (3.7M); full-resolution mp4 linked.
- Source + recorder are reproducible (personal-site assets/hero/).
Temporarily removes the loop-hero hero and the ao-demo CLI gif from the
README while the demo video is reworked to be skills-forward (live
in-session Claude + Codex) and faster. Assets stay in docs/assets/.
Replaces the See It Work hero with a real Claude Code session running
the **full delivery loop end to end** — research → plan → implement →
validate — on a demo repo. It reads `server.js`, finds the naive rate
limiter, plans the fix, **actually edits the file** (adds a time window
+ `Retry-After`), and validates with `node --check`, ending on
'Confirmed fixed' plus an honest note about the remaining unpruned-map
limitation.
- Real session, real tool calls, real correct fix. Sped 3× from a ~2-min
live run → 40s.
- Welcome-banner email/org **redacted**.
- `loop-hero` shipped as gif (README autoplay, 1.6M) + mp4 + webm.
- Moves the existing `ao demo` CLI gif down into the **The ao CLI**
section (loop = the work, CLI = the tool).
**Left unmerged for Bo's final look before it's public.**
Adds a scripted vhs recording of the real `ao` CLI to the README's "See
It Work" section (previously text-only, no demo asset).
- `ao --help` → knowledge flywheel badge → `ao demo --quick` value loop
- GIF autoplays inline on GitHub; mp4 alongside for download/reuse
- Real CLI output; only keystrokes scripted
Only touches README.md + docs/assets/.
## 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
Squash merge PR #546. Local evidence: doc-release, smoke, snapshot gate, pre-push Bats, snapshot Bats, structural gates, and pre-push --fast passed. PR GitHub Actions were blocked in runner setup by GitHub codeload/action download failures before repository code executed. Snapshot records current corpus as DECAYING rather than preserving stale compounding evidence.
## 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
Lands the honest AgentOps 3.0 doctrine so the repo's narrative matches
the shipped code: the daemon is **deleted**, AgentOps is the
**in-session** agent operating loop + context compiler, and
out-of-session orchestration is delegated to a substrate (the reference
**Gas City City** or **Olympus**).
## What landed
- **`docs/3.0.md`** (north star, rewritten): in-session-only identity;
honest GC reference-City section — dispatch is **mayor-driven** today,
order-auto-dispatch is a labeled **GC-upstream maturity gap**
(`soc-5jwah`), not turnkey; two reference implementations table
(AgentOps-on-GC has **no** daemon; Olympus **kept** its daemon because
it is a sovereign product); e2e-proof evidence cited.
- **`docs/architecture/canonical-loop-model.md`** (new): one loop body,
two drivers, one inner tick, one config. Evolve (in-session,
AgentOps-shipped) vs Factory (out-of-session, substrate-owned);
crank/swarm placed as in-session steps.
- **`docs/adr/ADR-0009-daemon-deletion-in-session-only.md`** (new,
Accepted): the daemon-deletion decision — DELETE-not-deprecate rationale
(AgentOps has no core to protect; Olympus kept its daemon because it's
sovereign), the rejected *deprecate-keep-standalone* alternative, the
sovereignty tradeoff (always-on requires GC), the e2e GC dispatch gap.
References `soc-j7a5q`.
- **`skills/domain/references/`**: loop-family vocabulary (loop, evolve,
factory, rpi, autodev, context-compiler) as 6 entries + INDEX rows +
SKILL.md links.
- **README**: "Two ways to use it" reframed to **in-session vs
out-of-session**; deleted-command prose (`ao daemon` / `ao schedule` /
`ao overnight`) reframed to in-session + GC reference.
- **`packs/agentops`**: dispatch relabeled mayor-driven;
order-auto-dispatch GC-upstream gap (`soc-5jwah`) called out in
`bead-dispatch.toml`, `rpi-dispatch.toml`, and `FINALIZE-NOTES.md`. `gc
config show --validate` still exits 0.
- Reconciled stale `agentopsd` prose in `skills/scope` +
`skills/session-bootstrap`.
## Gates
- `heal.sh --strict`: clean
- doc-release gate: succeeded (link validation PASS, 0 broken)
- `gc config show --validate --city .`: exit 0
- markdownlint: 0 errors
- `generate-registry.sh --check`: up to date
- codex parity (domain): passed
- `go build ./...`: success
**Do not merge** — the operator reviews `docs/3.0.md` before tagging.
Closes-scenario: soc-j7a5q#3.0-honest-doctrine
Bounded-context: BC1-Corpus
Evidence: .agents/discovery/2026-05-24-gvkj6-e2e-proof.md
W0 of the 3.0 reconciliation (operator-ratified). Grounds the repo
before reconciliation work.
- **docs/3.0.md (NEW)** — single source of truth: the SDLC↔CDLC loop
(BDD/Gherkin planning → tests → bounded build through ports → both-ends
behavior+contract validation → feedback → ratchet), the
BDD/DDD/Hexagonal/TDD waist, context density, and a precise
hookless-first explanation (hooks = quiet adapters, not
noise-injectors). + 3.0-ready acceptance + non-goals.
- Woven into README, PRODUCT.md, GOALS.md, CLAUDE.md,
docs/documentation-index.md, mkdocs.yml nav.
Pure grounding: no code, no bead closes, no features. Links verified;
additions-only.
NOTE: claude-review infra-red (weekly limit, resets May 25) —
operator-authorized bypass when sole red.
Closes-scenario: soc-25sgs#3.0-north-star
Bounded-context: BC1-Corpus
Evidence: docs/3.0.md
Manual line-by-line de-slop on residual tells after 4dda7ea1.
- Removed the 'durable value isnt in the tool — its in the corpus'
formula → 'is the .agents/ corpus you build, not the tool that builds
it'
- 18 emdashes recast → semicolons / colons / parens / split sentences
(clause-joins, appositive lists, term-definitions, table-cell glosses)
- Code-block example emdash (line 34) kept
Prose-only: no links changed, no technical claims altered. grep confirms
zero prose emdashes + zero slop formulas.
NOTE: claude-review infra-red (weekly limit, resets May 25) —
operator-authorized bypass when sole red.
Closes-scenario: soc-sgrdc#readme-deslop2
Bounded-context: BC1-Corpus
Evidence: README.md
Operator correction (2026-05-22): *"behavior science is not the spine.
fix the headline."* PR #416 over-rotated — it led the README + PRODUCT
headlines with behavior-shaping and the doctrine doc called itself "the
spine." The spine is the SDLC control plane / operating loop;
behavior-shaping is a complementary lens.
- README.md lead: restored to SDLC-control-plane framing;
behavior-shaping removed from the headline
- PRODUCT.md Mission: restored to wiki-for-agents + corpus-moat + CDLC;
behavior-shaping removed from the lead
- docs/architecture/behavior-shaping-environment.md: demoted to "a
behavioral lens — NOT the product's spine; the spine is the operating
loop"; heading "Why this is the spine" → "Why the lens is useful"
Content kept as a lens (doctrine doc, domain vocab, GOALS directive
#14); only the spine/headline positioning is corrected.
How tested: diff 4/4 balanced swaps (no collateral); sync-skill-counts
no drift; doctrine-doc links resolve.
NOTE: claude-review will be infra-red (weekly limit, resets May 25) —
operator-authorized bypass when sole red.
Closes-scenario: soc-e92s1#headline-not-spine
Bounded-context: BC1-Corpus
Evidence: README.md
soc-tk1d behavior-science frame, **surface 3/4**. Surgical reposition
(not a rewrite): lead the outward framing with behavior shaping as the
*how* — 'arrange the environment + reinforce the behaviors you agree on'
— keeping the 'SDLC control plane' category + 'sovereignty, not
features' bet.
- README.md lead: opens with the behavior-shaping mechanism + doctrine
link; preserves harness list, .agents/ state, per-phase model mixing
- PRODUCT.md Mission: leads with the ABC model + doctrine link;
corpus-as-moat + CDLC kept
Reviewer note: claude-review is rate-limited, so I ran the adversarial
pass myself — doctrine link resolves, 4 AOP-CLAIM markers untouched,
skill-counts no drift, validate-doc-links clean, no substance dropped.
Fitness: behavior-science surfaces 2/4 → 3/4.
Closes-scenario: soc-wub1y#reposition-behavior-shaping
Bounded-context: BC1-Corpus
Evidence: README.md
## Summary
- Cut AI-slop opener (aphorisms, methodology laundry lists, "shovel"
metaphor, "Independent 3-judge audit" overclaim) and in-cell italic
slogans across the README hero, See It Work, SDLC/CDLC, What AgentOps
Gives You, Why not Notion, Why Context Needs a Lifecycle, Quick Start,
Two ways to use it, and Labs sections.
- Restructure: move **See It Work** above **Install** so the demo isn't
buried under platform-specific install scripts; merge **SDLC Control
Plane, CDLC Mechanism** and **Why Context Needs a Lifecycle** into one
philosophy section (**Why context is the lifecycle**), with the SE→Agent
mapping table leading; add a **Limitations** section (5 honest bullets).
- Swap the first transcript demo from `ao rpi` (CLI) to `/research`
(skill) so the corpus-loading value — citing prior decisions, planning
rules, and learnings — lands visually in the first example.
- Integrate the 4 upstream wording softenings from #389 / f7cc505a
(autonomous → bounded; synthetic-fake-executor disclaimer; "the factory
executes the queue").
- Net 348 lines → 334 lines. All five `AOP-CLAIM` markers preserved.
## Test plan
- [x] `bash scripts/check-factory-claim-ledger.sh --strict` → PASS
- [x] `bash scripts/check-docs-learning-references.sh` → PASS
- [x] Skill-count claim verified: `ls skills/ | wc -l` = 80 (matches
"around eighty as of 2026-05-20")
- [ ] CI validate.yml passes (65 jobs)
- [ ] `claude-code-review` automation gate green
Closes-scenario: soc-x0au#readme-deslop
Bounded-context: BC1-corpus
Evidence: README.md
* docs(readme): lead with problem/solution and the executable-spec chain
* feat(skills): add expert-council — adversarial persona council
Named domain-expert personas duel via the dueling-idea-wizards route (verdict -> 0-1000 cross-scoring -> reveal -> score matrix). judgment tier. Slated for absorption into council --mode=debate per soc-ml4l.
* docs(council): add council-modes.feature acceptance spec for soc-ml4l
* refactor(council): formalize brainstorm/debate/verdict mode taxonomy
Refactor `council` into the three-mode taxonomy settled by the 2026-05-17
cross-vendor taxonomy duel (soc-ml4l). `--mode` selects one of exactly three
deliberation patterns — brainstorm (diverge), debate (contend), verdict
(converge); verdict is the default. `--focus`/`--depth`/`--runtime`/`--roster`
are orthogonal knobs, never modes.
- New `references/modes.md` — full taxonomy, mode-invariant lifecycle
(convene/brief/deliberate/synthesize/record), knob aliases.
- Rename the `--debate` flag (a verdict intensifier) to `--adversarial`;
the word `debate` now names the contend mode. `debate-protocol.md` ->
`adversarial-protocol.md`.
- Absorb `expert-council` as `--mode=debate`: move `dueling-route.md` into
`council/references/`; `expert-council` is now a 1-release thin alias ->
`/council --mode=debate`.
- `research` verb folds into brainstrom (`--focus=research`); `validate`
stays a verdict alias.
- Sync codex twins, SKILL-TIERS, using-agentops catalog, validate.sh
behavioral checks, codex hashes.
Acceptance: every scenario in council/references/council-modes.feature holds.
---------
Co-authored-by: Codex <codex@example.invalid>
Rescope PRACTICE.md into PRACTICE-REGISTRY.md: it now owns only the
practice-slug lineage registry, not product positioning or CDLC doctrine.
Update all references (schema, validate-practice-citations.sh, bats test,
architecture-terms.md, documentation-index.md, aggregate.go comment).
Introduce the Context Density Rule as a canonical domain concept: every
high-value context token carries intent, boundary, evidence, decision,
constraint, or next action. New domain entry context-density-rule.md (+
codex mirror). Thread the BDD/Gherkin + DDD + Hexagonal + TDD narrow waist
through cdlc.md, README.md, PRODUCT.md, GOALS.md, and the rpi/domain/
post-mortem skills. Sync codex artifacts.
Followup to 28fd87ad. Two gates would have failed in CI:
1. validate-codex-override-coverage.sh required a Codex twin for every
source skill — added skills-codex/domain/ (SKILL.md + prompt.md +
references/*.md mirroring skills/domain/references/) and registered
it in skills-codex-overrides/catalog.json as wave=catalog-parity,
treatment=parity_only (matches the standards skill precedent).
2. sync-skill-counts.sh did not cover two count strings:
- README.md "74 skills load automatically via hooks" → 75
- PRODUCT.md "74 checked-in Codex artifacts" → 75 (Codex twin now exists)
Gates re-verified locally:
- validate-codex-override-coverage.sh: passed for 75 cataloged skill(s)
- audit-codex-parity.sh: passed
- skills/heal-skill --strict: clean
- validate-skill-schema.sh: 75/75 pass
- regen-codex-hashes.sh: all hashes up to date
* fix(reconcile): backfill README claim anchors (Wave 1A — soc-2ie9k)
Add markers for 5 ledger rows previously orphaned by soc-nybd README rewrite.
Validator scripts/check-factory-claim-ledger.sh now exits 0.
* feat(reconcile): extend claim ledger to Wave-0 comparison docs (Wave 1B — soc-s805h)
Add anchors plus ledger rows for the Wave-0-refreshed comparison docs that
lacked coverage: competitive-radar.md, vs-everything-claude-code.md, and
vs-tons-of-skills.md. Validator scripts/check-factory-claim-ledger.sh stays
at exit 0.
trust-factory.md and wiki-for-agents.md are Wave-0-shipped but live outside
the validator's hardcoded source set. Coverage there is deferred to Wave
1C/1D, where the source-set widening is in scope; details captured in
.agents/crank/SHARED_TASK_NOTES.md.
* feat(reconcile): extend ledger source-set to Wave-0 docs (Wave 1B follow-up — soc-s805h)
Add docs/trust-factory.md and docs/wiki-for-agents.md to the validator's
collect_repo_sources() set so the issue's listed Files: line is fully covered.
Add markers + ledger rows for AOP-CLAIM-TRUST-FACTORY-FIVE-STEP-PRIMITIVE
and AOP-CLAIM-WIKI-FOR-AGENTS-CORPUS-COMPILATION.
The ledger JSON diff is large because jq normalized inline `source` keys
to multi-line — semantics unchanged.
Validator scripts/check-factory-claim-ledger.sh exits 0.
* ci(reconcile): wire factory-claim-ledger validator as advisory job (Wave 1C — soc-lmww1)
Adds `factory-claim-ledger-strict (advisory)` job to .github/workflows/validate.yml:
- runs `bash scripts/check-factory-claim-ledger.sh` via continue-on-error: true
- emits {run_id, pr_number, verdict, surfaces_touched, timestamp} JSON observation
- publishes observation as workflow artifact (not committed to repo)
- merged_anyway / ledger_updated backfill is Wave 1E concern, documented in-job
Also adds `tests/integration/test-factory-claim-ledger-ci-job.sh` to lock in the
job shape (T1-T6 contract assertions) for Wave 1E to invert when promoting to
blocking.
Validator stays at exit 0 on this branch.
* docs(reconcile): document operator workflow for claim ledger (Wave 1D — soc-4ou2q)
Add an Operator Workflow section to the factory-claim-ledger contract doc
covering all five closed enums (validation_level, release_posture,
evidence_status, authority_state, promotion_state), how to add/update/retire
claim rows, what each --strict failure mode means in operator terms, and a
worked example using AOP-CLAIM-TRUST-FACTORY-FIVE-STEP-PRIMITIVE.
Also update the Source Set list to include docs/trust-factory.md and
docs/wiki-for-agents.md (added in Wave 1B follow-up).
Validator: PASS. mkdocs build --strict: exit 0.
* ci(reconcile): wire factory-claim-ledger-strict into summary + AGENTS parity (Wave 1C followup — soc-lmww1)
The Wave 1C commit (82260e97) added the factory-claim-ledger-strict
advisory job to validate.yml but skipped two parity surfaces:
- summary.needs did not list it, so the aggregator never waited for it
and AGENTS↔workflow set-diff parity (validate-ci-policy-parity.sh)
flagged drift.
- AGENTS.md "CI Jobs" + "Advisory Job Triage SLAs" tables had no
matching row, so the validator's blocking/non-blocking set diff
reported the new job as a workflow-only addition.
Fix:
- validate.yml: add factory-claim-ledger-strict to summary.needs and to
the summary echo block. The job stays advisory because of its own
step-level continue-on-error: true.
- AGENTS.md: add it to the prose non-blocking list (line 72) and both
the SLA table and the CI Jobs table — the SLA table sets a 14d
triage SLA and explicitly defers blocking promotion to Wave 1E.
Validated:
- bash scripts/validate-ci-policy-parity.sh -> PASS (46 jobs;
6 non-blocking)
- bash scripts/test-ci-deterministic-gates.sh -> 4/4 pass
- bash tests/integration/test-factory-claim-ledger-ci-job.sh -> 6/6 pass
- bash scripts/check-factory-claim-ledger.sh -> PASS
* fix(eval): bump pre-push-gate-governance bats count 50->51 after ce9d42f8
Commit ce9d42f8 (fix(pre-push): keep fast two-pass advisory scoped) added
a 51st BATS test ("pre-push-gate.sh --fast two-pass keeps pass 2 fast and
skips evals for non-eval changes") but did not update the contract-canary
expectation in evals/agentops-core/pre-push-gate-governance.json, which
still pinned "1..50". Result: agentops-core.pre-push-gate-governance
canary failed locally with:
pre-push-bats-suite: stdout does not contain "1..50"
bats tests/scripts/pre-push-gate.bats reports 1..51 with all tests
passing, so the count is correct; the eval pin just needs to track it.
Validated:
- bats tests/scripts/pre-push-gate.bats -> 51/51 pass, "1..51" first line
- bash scripts/pre-push-gate.sh --fast -> Pass 1 PASSED, Pass 2 PASSED
- contract canaries gate flips from FAIL -> ok
* docs(positioning): wave 1 — README hero rewrite to wiki framing (soc-nybd)
Apply the locked decisions D1–D10 from the positioning doc-sweep packet:
- D1 headline: "A wiki for your agents. Built so you own the moat."
- D2 wiki-framing opener; D3 moat statement + "shovel" anchor
- D4 non-positioning ("AgentOps is not a coding harness")
- D5 receipts block (timestamped 2026-05-04 stable snapshot)
- D6 enterprise-pattern statement (pattern claim, no company names)
- D7 "What if the labs ship this natively?" section before Contributing
- D8 Notion vs AgentOps comparison table (7 rows)
- D9 SE → Context translation table (11 rows) replacing prior SDLC/CDLC table
- D10 line budget: 420 → 295 lines
Drops: intra-page nav bar, Validate/Nightly badges (stars retained),
"Competitive Positioning" section, 12-Factor Doctrine 4-tier table (now
single sentence linking 12factoragentops.com), mermaid diagram, AOP-CLAIM
markers, cross-runtime <details> block.
Forward references to docs/wiki-for-agents.md and docs/trust-factory.md
will resolve when Wave 4 lands those new files.
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md
Epic: soc-9xn0
* docs(positioning): wave 2 — strategic doc alignment to wiki framing (soc-ylp9, soc-rnbf, soc-x3b6, soc-b1r3)
Align PRODUCT.md, GOALS.md, docs/index.md, docs/agentops-brief.md with
the README's locked positioning thesis.
PRODUCT.md (soc-ylp9):
- Mission opener: wiki framing replaces "keeps the books / compiles the
context / compounds the corpus"
- "What the Product Actually Is" leads with wiki framing before four-layer model
- New "What if the labs ship this natively?" section (D7 verbatim with
"Anthropic's Managed Agents")
- Evidence section timestamped: corpus wipe on 2026-05-07, durability fix
tracked in soc-rv5p
- Cross-links to docs/trust-factory.md (forward to Wave 4)
- last_reviewed: 2026-05-06 → 2026-05-07
GOALS.md (soc-rnbf):
- Lede: "A wiki for your agents — repo-native, version-controlled,
mechanically maintained"
- New North Star: "The wiki maintains itself: every session contributes to
.agents/ by default"
- New directive #11: corpus durability (tag corpus-state, soc-rv5p)
- All 10 prior directives preserved
docs/index.md (soc-x3b6):
- Hero rebuilt: D1 headline + subhead + D2 wiki framing + D3 italicized
moat + "AgentOps is the shovel. Start digging."
- mkdocs hero buttons (Install / See It Work / GitHub) preserved
- Body sections unchanged
docs/agentops-brief.md (soc-b1r3):
- Opener swapped to D2 + D3 (wiki framing + shovel anchor)
- New "What if the labs ship this natively?" paragraph (D7 verbatim)
- See-also forward links to docs/trust-factory.md, docs/wiki-for-agents.md
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md
Epic: soc-9xn0
* docs(comparisons): wave 3 — comparison surface refresh + 2 new lane docs
Refresh 3 existing comparison docs to current competitive state and add
2 new comparison docs covering volume-marketplace and cross-harness lanes.
Refresh:
- competitive-radar.md (soc-33kk): 7-competitor lane table, 6 differentiators
(persistent corpus, off-API daemon, multi-model council, model-independent
phase routing, context-engineering vocabulary, honest empirical disclosure),
5-lane segmentation, last_reviewed → 2026-05-07
- vs-compound-engineer.md (soc-al8s): CE current state (37 skills/51 agents/
7-phase/10-target), new model-independent phase routing row, last_reviewed
added
- vs-superpowers.md (soc-zhig): Anthropic marketplace fact, 29K+ stars, wiki
framing in cross-session memory section (25-year-old idea), last_reviewed
added
NEW:
- vs-tons-of-skills.md (soc-fmkw): volume-marketplace lane comparison —
Tons-of-Skills (425 plugins, 2,810 skills, 200 agents, CCPI grading) vs
AgentOps as different categories. 90 lines.
- vs-everything-claude-code.md (soc-jhtu): cross-harness-parity lane
comparison — everything-claude-code (48 subagents, 182 skills, 5-runtime
DRY parity) vs AgentOps's per-phase model routing. Includes credibility-
move flag on the unverified 140K+ stars / 21K+ forks claim. 181 lines.
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md, council
research at .agents/council/2026-05-07-research-readme-positioning.md
Epic: soc-9xn0
* docs(positioning): wave 4 — bridge docs + index update (soc-momx, soc-envj, soc-e031)
Two new bridge documents that complete the positioning surface, plus the
documentation index update to make all 4 new docs reachable.
NEW docs/trust-factory.md (soc-momx, 112 lines, 854 words):
The 5-step trust-factory primitive (Identity → Reproducibility → Evaluation
→ Evidence → Recovery) mapped to AgentOps mechanisms. Bridge document for
engineering leads in regulated environments who think in trust-factory
vocabulary already. Pairs with the wiki framing as the alternative buyer
view.
NEW docs/wiki-for-agents.md (soc-envj, 93 lines, 824 words):
Standalone wiki framing — "wikis aren't new, the novel part is making the
discipline mechanical so it actually happens." Uses the D8 Notion comparison
table verbatim, covers the .agents/ directory layout, and explains why most
wikis fail (write-tax + bitrot) and how AgentOps inverts the pattern.
docs/documentation-index.md (soc-e031):
- Added "Bridge / framing docs" sub-list under Four Product Layers with
trust-factory.md and wiki-for-agents.md (visible above the fold)
- Added vs-tons-of-skills.md and vs-everything-claude-code.md to existing
Comparisons section (alphabetical with other vs-* entries)
- 222 → 226 entries; 309 → 316 lines
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md
Epic: soc-9xn0
* docs(positioning): wave 5 — body doc cross-links + light framing align (soc-igqq, soc-chkd, soc-cout)
Light touch on three linked body docs to align with the wiki framing
without restructuring their substance.
docs/cdlc.md (soc-igqq):
- Lede leads with "Software engineering took 50 years..." + the 11-row
SE→Context translation table (D9 verbatim)
- "CDLC" acronym deferred to body intro after the table establishes the
concept (acronym kept in 11+ body uses)
- Companion docs section cross-links to wiki-for-agents.md, trust-factory.md
- 248 → 273 lines
docs/the-science.md (soc-chkd):
- Practitioner-facing pointer under TL;DR: "see [Trust Factory]" +
"[A wiki for your agents]"
- Companion docs section
- 671 → 678 lines, science content intact
docs/positioning/devops-for-vibe-coding.md (soc-cout):
- Primary tagline → wiki framing ("A wiki for your agents — built so you
own the moat"); secondary recast as DevOps-lineage tagline
- Category line acknowledges DevOps lineage as historical, not category label
- Date 2026-01-31 → 2026-05-07; version 1.2.0 → 1.3.0
- Cross-link to ../wiki-for-agents.md
- DevOps argument preserved (14 DevOps mentions intact, 6-differentiators
table untouched)
- 343 → 351 lines
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md
Epic: soc-9xn0
* docs(positioning): wave 6 — fix mkdocs --strict link warnings (soc-uc3w)
The wave 4 bridge docs and wave 3 competitive-radar refresh used relative
links that escape the mkdocs docs/ tree:
- ../README.md and ../PRODUCT.md cross-links → switched to absolute
https://github.com/boshu2/agentops/blob/main/{README,PRODUCT}.md
(matches existing docs/documentation-index.md convention)
- ../../.agents/council/ research link → demoted to plain-text path
reference (the .agents/ tree is gitignored runtime state, not a
publishable doc surface)
Verified: scripts/docs-build.sh --check now exits 0 with "OK: mkdocs
build --strict passed". Five strict-mode warnings cleared.
Wave 6 validation results (12-item checklist):
- mkdocs --strict: PASS
- competitive-freshness: PASS (8/8 docs ≤45 days)
- README ≤ 300: 295 lines
- D1-D10 visible across README, PRODUCT, GOALS, docs/index, docs/agentops-brief, docs/wiki-for-agents
- Cross-links: README→{wiki-for-agents, trust-factory}, PRODUCT→{trust-factory, wiki-for-agents}
- New comparison docs (vs-tons-of-skills, vs-everything-claude-code) exist
and are linked from competitive-radar.md and documentation-index.md
- "operational discipline" residues are historical-only (release notes,
origin-story, devops-for-vibe-coding messaging hierarchy)
Note: ao goals measure shows ambient fails unrelated to this sweep — the
tool is cwd-sensitive and reports "No such file or directory" for scripts
that exist (separate bug, not introduced by this work).
Source: .agents/discovery/2026-05-07-positioning-doc-sweep.md
Epic: soc-9xn0
* docs(positioning): add assurance profile for agent factory rigor
* docs(positioning): frame goals as reconcile setpoints
* chore(scripts): suppress SC2034 on bd_out — set by run_capture via name-ref
Drive-by fix needed to push crank/soc-sx99 — pre-push shellcheck flagged
bd_out as unused in test-rpi-surface-smoke.sh, but it is set indirectly by
run_capture's name-ref pattern. Adds a targeted shellcheck disable comment.
Operator polish: name the bookkeeping primitive explicitly as a
4th compounding layer alongside context compilation, validation gates, and
the knowledge flywheel.
Headline upgrade:
- "AgentOps compiles and compounds the context that feeds your software factory"
→ "AgentOps keeps the books, compiles the context, and compounds the corpus
that feeds your software factory" (three verbs name three primitives)
Body:
- New explicit naming: "automates the bookkeeping agents do not reliably do
for themselves — attempts, decisions, citations, verdicts, handoffs, learnings"
- The four layers are now: bookkeeping, context compilation, validation gates,
knowledge flywheel.
- Dream reframed: "Dream is the scheduled overnight mode of the flywheel"
(not a peer product).
- "One substrate, three operator surfaces" → "One factory, three operator
surfaces, four compounding layers" (the substrate IS a factory).
- Mirrored across PRODUCT.md, AGENTS.md, CLAUDE.md preamble, README.md hero,
docs/strategic-direction.md.
Operator polish on top of the just-shipped substrate-leads thesis. Tightens
voice and adds an Assurance Posture section that names the operating
discipline without overclaiming certifications.
Headline:
- "AgentOps is a context compiler that feeds your software factory" →
"AgentOps compiles and compounds the context that feeds your software
factory" (verb-led, more active; "the substrate the supermodel plugs
into" relegated from headline to body).
Body:
- New value-prop paragraph: "the highest-leverage input to coding agents
is context: what the system knows, what it has tried, what failed, what
the codebase decided, and what gates must hold."
- "One substrate, four surfaces" → "One substrate, three operator surfaces,
one enforcement layer" (cleaner separation: surfaces are for humans,
hooks are policy).
- "TSMC-efficiency for code" → "factory-grade throughput for code"
(accessible, not brand-specific).
- "Humans drop in or out" → "Humans choose the posture" (more deliberate).
- Lineage demoted with note: "users do not need that vocabulary to
understand the product."
NEW: Assurance Posture section (PRODUCT.md) — names the constrained-
environment habits (local-first control, context as a boundary, evidence
by default, policy gates over advice, variable autonomy, constrained-
network fit) WITHOUT making certification claims. Explicit caveat:
"Formal deployment into classified, export-controlled, or safety-critical
environments still requires the local authority's security controls,
model approvals, supply-chain process, and accreditation work."
Also tracked as a Known Product Gap: "High-assurance profile is not yet
formalized." Honest framing: posture exists, accreditation surface does
not.
Mirrored across:
- AGENTS.md, CLAUDE.md preamble: matching one-paragraph form
- README.md hero: matching headline
- docs/strategic-direction.md: lineage spine matched
- skills/quickstart/SKILL.md, skills-codex/quickstart/SKILL.md (parity sync;
hashes regenerated via scripts/regen-codex-hashes.sh)
Additive extension on top of the council-consolidated thesis (8/8 WARN
verdict, .agents/council/2026-05-07-validate-positioning-thesis-report.md).
Operator-confirmed in this session: the sovereignty/corpus framing was right
about *what the durable asset is*, but didn't surface *what the durable
asset is for* — autonomous high-throughput operation against the operator's
own repo, with humans able to drop in or stay out at whatever cadence fits.
PRODUCT.md changes:
- Mission ¶1: "context compiler that feeds your software factory" (both/and,
not either/or — sovereignty AS the substrate, software factory AS the telos)
- Mission ¶2: DevOps → DevSecOps; explicit goals → product → program emergence
layer named (the structure that lets the system run autonomously at the
human's chosen cadence)
- Mission ¶3: surfaces upgraded from three to four — plugin + CLI + hooks +
scheduling daemon (matching the user's lived phrasing)
- Mission ¶4: in-the-loop / on-the-loop human framing appended to sovereignty
paragraph
- Mission ¶5 (Lineage): field-lineage attribution added — lessons from
high-stakes regulated environments + open-source community around Gas Town
beads and Ralph loops (the fresh-context-per-worker pattern /crank waves
implement)
- Vision section: TSMC-efficiency aspiration named explicitly — autonomous
high throughput against a defined process, operator at exception boundaries
README.md hero: same upgrade, single paragraph form for the hero slot.
AGENTS.md, CLAUDE.md preamble: matching one-paragraph + one-sentence forms.
Constraints honored:
- Per operator decision: cite "high-stakes regulated environments" instead
of "U.S. Intelligence Community" (sector-agnostic, NDA-safe).
- Per operator decision: TSMC analogy retained explicitly (concrete and
defensible — high-throughput automated manufacturing with human exception
handling).
- No fabricated stats. No new comparison docs. Factory's Missions still
cited as convergent, not derived-from.
Propagate the council-consolidated positioning thesis across the doc tree.
8/8 cross-vendor council verdict (.agents/council/2026-05-07-validate-positioning-thesis-report.md)
identified the substrate-leads framing as the durable 24-month thesis;
plugin-not-API was a 12-month wedge that contradicted the existing strategic
bet ("Knowledge is the moat. AgentOps isn't.").
Canonical thesis (now propagated):
AgentOps is a context compiler — the substrate the supermodel plugs into.
It encodes the DevOps SDLC as the CDLC, plus the operating practices of
multi-agent work: isolated context, stigmergic coordination, planner/
implementer/validator separation. Validation gates, the knowledge flywheel,
and the schedulable dream daemon are outputs of the compiler, not peer
products. The bet is sovereignty, not features.
Surface changes:
- PRODUCT.md: Mission section (substrate-leads thesis); "What the Product
Actually Is" reframed as "one substrate, three surfaces / three outputs";
Strategic Bet expanded with sovereignty answer (cross-runtime corpus,
local sovereignty, operator workflow encoding); new dedicated Lineage
section (Knowledge OS → Olympus → AgentOps → Mt. Olympus); compound-
engineering / software-factories / Greenfield 2003 named lineage; 12-factor
parallel-not-derived callout; Meadows promoted from footnote.
- README.md: hero replaced with substrate-leads framing; scheduling
reference link surfaced.
- AGENTS.md: top-level positioning blurb updated.
- CLAUDE.md: new "What this is" preamble with one-sentence thesis.
- cli/docs/HOOKS.md: CASS clarified as AgentOps-internal terminology
(not external prior art); inspired by Olympus.
- docs/strategic-direction.md: lineage hierarchy spine added under the
consolidation decision; industry parallels named as convergent.
- docs/cdlc.md: Meadows leverage-point hierarchy was already integrated;
no edit needed (worker verified existing prose covers it).
Constraints honored (per pre-mortem R1, R2, council verdict):
- No new docs/comparisons/ files created (existing vs-compound-engineer.md
referenced by link only).
- Factory's Missions / Luke / Factory AI not cited explicitly (operator
decision: internalize the planner/implementer/validator framing, don't
attribute).
- No fabricated corpus stats (sx99.9 owns that slice).
Closes soc-sx99.3.
User correction surfaced during this crank: AgentOps explicitly positions
against EveryInc's Compound Engineer and a comparison doc exists at
docs/comparisons/vs-compound-engineer.md, but neither README nor PRODUCT.md
cross-linked it. Readers familiar with "compound-engineering" parlance
landed on top-level docs and couldn't find the contrast.
- README.md comparison table: Compound Engineer row gains an inline
([vs.](docs/comparisons/vs-compound-engineer.md)) reference next to the
upstream link.
- PRODUCT.md mission section: lineage call-out under the canonical-contract
blockquote pointing readers to the in-depth comparison.
- PRODUCT.md "See Also" section: dedicated bullet describing what the
comparison covers (in-scope vs. out-of-scope distinctions).
Closes soc-sx99.11.
Closes soc-yjzp.9 (workbench A/B counter-stat) by publishing the empirical
result instead of a placeholder positive number, and lands the Wave 1 doc
honesty pivot from the epic soc-sx99 strategic audit.
# Empirical result (soc-yjzp.9)
ao eval run --baseline-mode=both produced Δ=+0.0000 across 12 workbench
cases (skill-on 12/12, skill-off 12/12). At v1 task difficulty (off-by-one
bugs, simple validators, basic SQLi) the AgentOps hook layer is non-
differentiating — the substrate doesn't surface skill value at this floor.
The honest publishable line is the zero, not a fabricated positive number.
Substrate v2 (realistic agent task difficulty) is roadmap; that's a
multi-week design effort tracked in plan-2026-05-04, not a yjzp.9-sized
bead. Counter-stat artifact tracked at
evals/workbench/results/2026-05-06-yjzp9-counterstat.json.
# Doc honesty pivot (soc-sx99 Wave 1)
Strategic audit at .agents/research/2026-05-07-agentops-strategic-positioning.md
found 5 audit-pivot-re-audit cycles in 6 weeks with byte-identical "remaining
gap" wording across PRODUCT.md versions. Operator-confirmed decisions:
- PRODUCT.md: drop the unsupported "4,940 learnings, 1,195 patterns, 40
planning rules" line (no on-disk corpus reconciles, including the user
vault). Replace with qualitative claim. Cite Δ=+0.0000 with substrate
framing in the Anthropic Managed Agents Outcomes row. Reframe pattern-
to-skill row as deferred (synthesis layer; .agents/skill-drafts/ does
not exist on disk despite earlier "review-only draft generation" claim).
- GOALS.md: three-gap contract proof table reframed. Gap 1 stays
Currently Enforcing (hook-preflight, go-vet-clean, go-complexity-
ceiling, security-gate, contract-compatibility). Gap 2 + 3 split:
scripts that go green in CI/pre-push stay enforcing; flywheel-
compounding (long-cycle, corpus-state by design), flywheel-proof
(cross-session evidence), compile-freshness, goals-validate,
wiring-closure move to a Roadmap column with "declared, not yet
enforced" framing. Honesty rule documented above the table.
- README.md: hero reframed to "context compiler + validation harness
with cross-runtime skill packaging. The daemon is the always-on
dream." Surfaces the schedulable daemon (already shipped via
ao schedule + ao daemon + nightly.yml + the user's headless dream/
evolution sessions) as a co-equal flagship rather than a power-user
feature.
- docs/comparisons/competition-rpi-memory-pipelines.md: Outcomes row
matches the new PRODUCT.md framing.
# Why this lands together
Per the recurrence finding (f-2026-05-07-positioning-audit-cycle-
recurrence): filing more beads to fix the gaps without dropping the
overpromised claims first is what produces the audit cycle. The claim
removal precedes the gap-fill work. soc-sx99 epic Waves 2 (daemon
surfacing recipe pack) and 3 (gap-filler jobs: feedback-loop --drain,
pattern filename repair) follow as separate PRs.
# Verification
bash tests/docs/validate-doc-release.sh: PASS
# Cross-references
- Closes: soc-yjzp.9
- Epic: soc-sx99 (this is Wave 1, doc honesty)
- Research: .agents/research/2026-05-07-agentops-strategic-positioning.md
- Finding: f-2026-05-07-positioning-audit-cycle-recurrence (registered)
- Related: soc-x7hy (MemRL signal strengthening, filed earlier today)
Replace "bookkeeping, validation, primitives, and flows" with the three
product layers (Context Compiler, Validation Gates, Knowledge Flywheel) in
core docs, README skills table, and comparison docs. Adds three-layer
comparison tables to all 5 vs-*.md files and a navigation section to
documentation-index.md.
Replace four-layer model (bookkeeping/validation/primitives/flows) with
three product layers that map to the CDLC loop: Context Compiler,
Validation Gates, Knowledge Flywheel. Update sync-skill-counts.sh
patterns to match the new PRODUCT.md heading format.
Merge Cross-Vendor Operating Layer, Why DevOps, and The Lineage into
one 24-line section. SDLC→CDLC table maps all 7 phases to AgentOps
surfaces. Links to docs/cdlc.md for the full treatment.
Reframe AgentOps as a "context compiler" across README, docs/index.md, and
PRODUCT.md — replacing "operational discipline" / "local operating layer" with
context-first language aligned to the Context Development Life Cycle (CDLC).
Add context_comprehension eval dimension (schema + Go types + validation) with
a deterministic eval suite and shell fixture that scores SKILL.md structural
quality (steps, flags, examples, output spec, length).
Add SkillLoadEvent to the citation pipeline so ao inject --for=<skill> records
a skill_loaded CitationEvent via ratchet.RecordCitation, closing the gap
between "what context was loaded" and "how the session went."
Wire quality-signal corrections from hooks/quality-signals.sh into the flywheel
close-loop so user corrections reduce utility of loaded skills, completing the
observe → adapt feedback loop.
Ref: soc-hsef, Debois CDLC talk (AI Engineer 2026)
Bo