## What
Adds **integrator** to agentpod-spec.v1's function enum {planner,
generator, oracle, scribe}. It is **merge-execution**: takes
Oracle-passed green PRs and integrates them to main
(rebase/update-branch, CI-shepherd, serialize, keep-trunk-green,
revert-on-red) — distinct from the Oracle (*decides* to merge) and the
Orchestrator (*schedules* pods). Maps to RoleWorker; cannot fold into
Oracle (RoleVerifier never-edits) or Orchestrator (control-plane
injection boundary).
## Decided by quorum
2-of-3 cross-model, 2026-06-06 (derivation: msg #160; the gap surfaced
when a human-driven refiner drained ~36 PRs this session and it was
clearly a distinct full-time role):
- **Codex: REVISE→add, mechanics-only** · **agy: APPROVE** · **Claude:
author-recused.**
Two quorum-mandated guardrails encoded in the doc:
1. **Mechanics-only** (Codex): semantic conflict-resolution that changes
code re-enters the Generator/Oracle gate — integrator is never a
privileged post-verdict author path.
2. **Circuit-breaker** (agy): bound merge/revert + rebase loops (max
retries, halt-on-thrash) so a misbehaving integrator can't thrash trunk
/ burn CI.
Docs-only (RBAC stays roles.go; no schemas/ change, consistent with #766
PROPOSAL scope). Spine-role implication (the-agent-factory.md gains an
Integrator role) flagged for the spine owner.
Bounded-context: BC4-Factory
Evidence: docs/architecture/agentpod-swarmjob-schema.proposal.md
## What
Makes the Brownian-Ratchet rule **R3 — "no learning without a
constraint"** self-enforcing. Previously it was prose only
(`docs/architecture/operating-loop.md` promotion table: *"Must never
regress → add a validation gate"*): a learning could be promoted to a
durable maturity tier without ever compiling into a gate/test/rule. The
mechanism existed (`cli/internal/ratchet/`) but R3 was a manual operator
decision with no check.
## How
`scripts/check-ratchet-r3-constraint.sh` scans the learnings corpus and
flags any **durable-tier** learning
(`candidate`/`established`/`canonical`/`stable`/`promoted`) that cites
**no constraint** — a `scripts/`/`.github/workflows/` gate, a
`_test.go`/`tests/` reference, a `skills/**/SKILL.md` step, or a
`constraint:`/`enforced_by:` frontmatter field. Provisional learnings
are exempt (still forming).
- **Warn-first → blocking**, mirroring the ratchet's own warn-then-fail
ladder: warn-only by default (exit 0); `--strict` or
`RATCHET_R3_BLOCKING=true` makes the same gaps blocking (exit 1).
## Why a script, not a CI path-filter gate
`.agents/learnings/**` is **gitignored** (0 tracked). A CI path-filter
gate on it would be dead-by-design — the exact reason the
`learning-coherence` CI job was retired (2026-05-19). So R3 runs at
ratchet/flywheel time against the **live local corpus**; the script's
own correctness is gated in CI by the committed bats test
(`tests/scripts/*.bats` runs in `validate.yml`).
## Verification
- `tests/scripts/check-ratchet-r3-constraint.bats` — 11 hermetic tests
on a synthetic fixture (warn-first, --strict, env-var parity,
provisional exemption, empty-field rejection, gate/test/SKILL citation
forms, count accuracy). All pass.
- `shellcheck` clean.
- Dry-run against the real local corpus: 639 scanned, 7 durable-tier, 5
flagged — warn-only, exit 0 (honest; does not break on existing corpus).
Closes-scenario: ag-maaa#r3-constraint-gate
Bounded-context: BC1-Corpus
Evidence: tests/scripts/check-ratchet-r3-constraint.bats
## What
New doc `docs/architecture/agentpod-swarmjob-schema.proposal.md` — the
**schema-level design** for one-way-door #2 (`ag-egpu.1`). It
operationalizes the two deltas the architecture spine
`docs/architecture/the-agent-factory.md` (`ag-yv25`, cross-model
reviewed 2026-06-05) names for door #2: (a) AgentPod-spec +
SwarmJob-spec on the bead, (b) watch/event surface.
**PROPOSAL only** — no schema in `schemas/` changes, no migration. The
doc is the artifact the council ratifies before `ag-v1xk` / `ag-xanm` /
`ag-7dnb` code against the API.
## Supersedes PR #765
My first attempt (#765) branched ~80 commits behind and added a
competing `the-agent-factory.md`, colliding with the canonical spine
that already landed on main. This PR is re-homed to a non-colliding
path, **defers to the spine** for architecture, and aligns to its
vocabulary (AgentPod / SwarmJob / Oracle / anti-affine / Volume-tier).
Closing #765 in favor of this.
## Design (additive, reuses not forks)
- **agentpod-spec.v1** = `worker-spec.v1` (already a Pod template) **+**
`function` (Planner/Generator/Oracle/Scribe — product layer, not RBAC
churn) + `anti_affinity.model_family` (the membrane as a scheduling
constraint) + `volume_tier`.
- **swarm-job.v1** = typed Pod composition on a bead + a **cost-law
derivation rule** (reversible bead → 1 Generator + 1 Oracle pre-check;
one-way-door bead → ≥2 anti-affine Oracles = real quorum). Makes the ≤12
cap a schema field.
- **`bead.*` events** = additive enum on `watch-event.v1`
(`additionalProperties:true`, non-breaking) so the reconcile controller
watches bead state instead of polling `bd ready`.
## Decisions for council (in-doc)
1. AgentPod/SwarmJob binding: bead **metadata projection** (rec,
reversible) vs. first-class `bead.v1` field.
2. SwarmJob **beside** (rec) vs. merged with
`swarm-evidence`/`orchestration-result` (input vs. output contracts).
3. `bead.*` emitter: **`bd` write-path** (rec, crash-safe) vs. `ao` Dolt
tail.
4. `function` is product-layer only; `roles.go` RBAC unchanged.
## Evidence
- New doc: `docs/architecture/agentpod-swarmjob-schema.proposal.md` (158
lines, PROPOSAL-stamped).
- Reconciles:
`schemas/{worker-spec.v1,watch-event.v1,bead.v1,quest.v1,remote-compute-target}.schema.json`.
Advances ag-egpu.1; does **not** close it (closes on council
ratification — gated). Do not auto-merge.
Bounded-context: BC5-Runtime
Evidence: docs/architecture/agentpod-swarmjob-schema.proposal.md
## What
Closes the partial in Google-SRE convergence **point #8** (`ag-wrom`):
AgentOps already ran work at several autonomy levels (human-in-loop
in-session → substrate dispatch → bounded `autodev`) but the progression
was *implicit* — nothing named the rungs, stated what each may mutate,
or defined the evidence that earns a promotion. Implicit autonomy is how
a probabilistic agent quietly acquires more authority than its track
record justifies.
Adds `docs/architecture/autonomy-ladder.md`:
- **The invariant every rung obeys** — non-deterministic reasoning core
wrapped by a deterministic enforcement boundary (CI gates +
ports-and-adapters + ratchet) the agent can't bypass. The ladder moves
the *leash*, never relaxes the *boundary*. L4 code passes the same CI as
L0 code.
- **L0–L4 rungs** mapped to AgentOps' real dispatch vocabulary, with
human posture / acts-before-review / may-merge per rung.
- **Promotion gates** — per-lane, revocable, gated on
statistically-significant success vs Golden data at the
Bronze/Silver/Gold tier.
- **Demotion** — auto-downgrade on risk (the L3→L2 analog of Google's
de-escalation) + the unconditional Red Button.
- **Hard ceilings** — no rung confers authority over
external/secrets/schema/deletion/strategic-fork/merge-beyond-contract;
those stay draft-and-queue at every level.
- Honest divergence stated: AgentOps autonomy is **build-time** (code +
`.agents/` corpus), not run-time production ops — which is why L4 is
delegated to a substrate, not shipped (ADR-0009).
Wires it into the architecture index card grid + `mkdocs.yml` nav, and
flips convergence point #8 from ⚠️ partial to ✅ encoded (tally 9/1/1).
## Evidence
Closes-scenario: ag-wrom#autonomy-ladder
Bounded-context: BC1-Corpus
Evidence: markdownlint-cli2 PASS on all 3 changed docs; all cross-links
verified to resolve (operating-loop, canonical-loop-model,
fungibility-charter, google-sre, ADR-0009 in-docs relative; CLAUDE.md +
skills/autodev as GitHub URLs per repo convention for out-of-docs
targets); new page registered in mkdocs nav for `mkdocs build --strict`.
## What
Canonizes the **agent-factory architecture spine** — the foundational
document that guides the build. AgentOps as a Kubernetes-style control
plane for the first *stochastic, untrusted* workload (AI agents).
- **`docs/architecture/the-agent-factory.md`** — thesis, control/data
plane, the **AgentPod / SwarmJob / Volume** compute model, **Roles ×
Primitives** (RBAC × canon function × primitive — naming the
verification role the **Oracle**), the **one-way / two-way door
register**, the **cost law** (tokens follow reversibility), the honest
boundaries, and the dependency-ordered build sequence.
- **`docs/architecture/the-agent-factory.feature`** — the architecture
fitness functions (`@enforced` vs `@to-build`).
- **`GOALS.md`** — North Stars now lead with the **verification
membrane**; the knowledge flywheel demoted to the compounding layer
beneath it.
## Why this is wave 1 of `ag-yv25`
This is the **canonize** wave. Fitness gates (wave 2) and the keystone
wiring (wave 3) remain open under the epic. The build proceeds
foundation-up: `ag-o2tc` (HA store) → `ag-egpu` (workload-object API) →
`ag-v1xk` (reconcile controller) → scheduler / self-healing.
## Review provenance (dogfood)
Reviewed *through the membrane* across **three cross-model council
passes** (Opus 4.8 + gpt-5.5): the architecture verdict, the Pod-model
debate (converged on AgentPod), and the final whole-spine pass — **both
vendors endorse**. Verified against the kernel (`liveness.Disjoint`,
`quorum.CheckSignificantAction`, the `roleCapabilities` matrix). Per
`liveness.SignificantActionDocCanonization`, canonizing this doc is
itself a membrane-gated action.
Closes-scenario: ag-yv25#canonize-spine
Bounded-context: BC5-Runtime
Evidence: .agents/council/2026-06-05-verdict-the-agent-factory.md,
.agents/council/2026-06-05-debate-pod-model.md,
.agents/council/2026-06-05-verdict-final-spine.md
## What
Two bounded doctrine-reconciliation slices (one coherent arc):
**ag-88y5** — the out-of-session dispatch unit is the `/rpi`·`/evolve`
**skill**, not the `ao rpi`/`ao evolve` CLI. Per the 3.0
skills-are-the-runtime thesis (using-ntm #693 already frames it this
way), re-narrate the **live** doctrine surfaces so the substrate spawns
an agent that *runs the /rpi skill* over a bead:
- docs/3.0.md, docs/architecture/canonical-loop-model.md,
docs/runbooks/nightly-evolution.md
- skills/using-agentops, skills/agent-native,
skills/domain/references/factory.md
Historical surfaces (MIGRATION-3.0, ADR-0009, release notes) +
CLI-reference left as-is; the actual `ao rpi`/`ao evolve` CLI removal is
the **ag-iowf** epic (live automation callers — overnight-evolve,
release-smoke — must migrate first).
**ag-ogp5** — drop the 4 docs still asserting Gas City as THE reference
substrate → NTM+MCP+managed-agents:
- docs/ARCHITECTURE.md, docs/SCHEMAS.md,
docs/contracts/agents-write-surfaces.md,
docs/patterns/completion-notifications.md (Pattern C)
The ~37 historical/illustrative GC refs are intentionally retained (per
ag-ogp5 scope).
## Verification
regen-all --check, embedded-sync, heal --strict, registry-drift,
codex-rpi-contract, codex-artifacts --scope head — all green.
Closes-scenario: ag-88y5#docs-skills-dispatch-reframe
Bounded-context: BC4-Factory
Evidence: docs/3.0.md
## What
The **doctrine slice** of the ACFS-prune (operator-authorized
2026-06-02). Re-narrates AgentOps's out-of-session story.
**Kept (the sovereignty floor — unchanged):** AgentOps = the in-session
loop + compounding context; ships no daemon/scheduler/overnight-runner;
delegates out-of-session execution to a *swappable substrate*. The
in-session/out-of-session boundary and the "substrate owns
when/where/who-supervises/coordination" split stay.
**Changed (the reference substrate):** Gas City → the adopted ACFS trio
— **NTM** (local tmux swarm) + **MCP** (`ao mcp serve`, shipped) +
**managed-agents** (`ao agent`). "AgentOps IS a Gas City reference
config" → "AgentOps adopts NTM+MCP+managed-agents; it still owns no
core, it just doesn't own or reference Gas City." This is the
deep-dive's "adopt the substrate, don't own it."
## Changes (7 files, +25 / −120)
- `docs/3.0.md` — substrate table row; replaced the "Gas City reference
City" section with "Running the loop out of session" (the three
substrate options); Olympus comparison rows; sovereignty-floor line
- `docs/architecture/canonical-loop-model.md` — Factory-driver framing,
ASCII diagram, boundary table, dispatch paragraph
- `docs/cdlc.md`, `docs/architecture/fungibility-charter.md` — substrate
one-liners
- **deleted** `docs/architecture/gc-posture.md` + reconciled its 4
inbound links (both index files, documentation-index,
fungibility-charter)
## Scope boundaries
- **ADR-0009 left historical** — decision records are immutable; it
records the *then*-rationale.
- **`thesis-stability` not tripped** — that gate guards the product
thesis (README/PRODUCT/GOALS), not the substrate detail. (Its current
FAIL is pre-existing README/PRODUCT/GOALS tagline drift, unrelated to
this PR.)
- **Follow-up `ag-124p`** (separate PR): the code/config strip —
`packs/agentops` + `city.toml` + `skills/using-gc` +
`cli/hooks/claude.json` gc-wiring.
## Note
This is outward-facing doctrine — opened for your review rather than
auto-merged. PR #5 this session; you authorized continuing past the
scope ceiling for the prune.
Closes-scenario: ag-vg40#substrate-renarration
Bounded-context: BC1-Corpus
Evidence: docs/3.0.md
Codifies the AgentOps 3.0 fungibility doctrine — implicit in the
primitives but contradicted by 2.x surfaces — into a single charter at
`docs/architecture/fungibility-charter.md`.
## The six commitments
1. **Default RPI mode is single-model** — the session's model runs every
phase; multi-model is opt-in.
2. **Any agent can claim any bead** — no role gating; `bd
ready`/`--claim` already enforce this.
3. **Stateless agent assumption** — agents are interchangeable consumers
of the `.agents/` corpus; no agent owns a domain or carries
irreplaceable state.
4. **Universal init prompt is standard** — every spawn runs `ao session
bootstrap` (shipped, vuu6.25).
5. **Death is normal; recovery is automatic** — `ao beads stale-claims`
+ `ao beads resume` (shipped) make dead-agent recovery operational.
6. **Specialization is opt-in** —
`--mixed`/`--pool=N`/`--diverse`/`--codex` exist but are never the
default.
Each commitment names the shipped primitive that implements it, so the
doctrine is honest (the risk-gate from the bead: do not land doctrine
ahead of primitives — vuu6.25 closed, the stale-claims primitive lives
in `cli/cmd/ao/beads_stale.go`/`beads_resume.go` on main).
## Cross-references / discoverability
- `docs/architecture/operating-loop.md` — See also (acceptance: charter
referenced from the spine)
- `docs/architecture/index.md` — card
- `docs/documentation-index.md` — catalogue line
- `mkdocs.yml` — added to nav under Architecture
Docs-only, no code, scope-only diff (5 files, +105 / -0).
README/PRODUCT.md positioning rewrite is out of scope here (separate
slice soc-vuu6.30 + the CI citation gate); this PR lands the charter
artifact itself.
Closes-scenario: soc-vuu6.29#fungibility-charter
Bounded-context: BC5-Runtime
Evidence: docs/architecture/fungibility-charter.md
## Summary
Adds the canonical **GC posture / boundary doc** — the page a one-liner
like "Gas City is the reference substrate" points at.
- `docs/architecture/gc-posture.md` (new): states GC is **one opt-in,
swappable adapter behind AgentOps's ports** (not the runtime AgentOps
runs inside); the hexagon points the right way — AgentOps core owns the
ports, GC satisfies the out-of-session Factory-driver role.
- **Guardrail (hard limit):** never register AgentOps state (corpus,
bd/Dolt, ratchet) as a **GC-managed-city resource**; rationale = the
Olympus ~**1,478**-flap incident (attributed as the stated Olympus
rationale, not an AgentOps-measured in-repo metric).
- **Sovereignty:** GC is local/self-hostable; AgentOps-on-GC preserves
**"no cloud required."**
- Registered in `docs/documentation-index.md` and the
`docs/architecture/index.md` grid. Built as a non-nav architecture page
like its siblings `canonical-loop-model.md` / `operating-loop.md`
(mkdocs `--strict` green).
## Scope
Docs-only, single coherent arc (`docs/**` + `tests/**`). No `cli/**`, no
skill changes, no release edits. Single squash-revert rollback.
## Test plan
- [x] `bats tests/scripts/test-gc-posture-doc.bats` — written first
(failed for the right reason: doc absent), now green (6/6). Asserts
adapter-behind-ports, opt-in + swappable, the managed-city guardrail +
`1,478`, the `no cloud required` + self-hostable/local sovereignty line,
and the documentation-index link.
- [x] `mkdocs build --strict` — passed.
- [x] `ao autodev validate --file ../PROGRAM.md --json` — `valid: true`.
Closes-scenario: soc-7blko#gc-posture
Bounded-context: BC2-doctrine
Evidence: tests/scripts/test-gc-posture-doc.bats
## Summary
Hookless AgentOps 3.0 ships no SessionStart/Stop hooks, but several
cold-start surfaces still named hook scripts as live context-injectors —
misleading a fresh agent into expecting auto-injection. This is a pure
doc/skill reconciliation pass (BC1 Corpus); **no command logic
changed**.
- **Scenario 1 (orientation reachable without a hook):** `CLAUDE.md` +
`AGENTS.md` Zero-Context startup now name the explicit orientation
command — `ao session bootstrap` → `ao inject` / `ao corpus inject
--query "<topic>"`. `AGENTS.md` drops the stale "when soc-vuu6.25 lands
/ until then" hedge: bootstrap shipped in PR #390 (soc-vuu6.25 is
closed).
- **Scenario 2 (no doc/skill promises hook-provided context):**
`docs/architecture/primitive-chains.md` Chain 6,
`skills/session-bootstrap/SKILL.md` (+ codex twin), and
`docs/newcomer-guide.md` no longer present hook scripts as active
surfaces; remaining hook mentions are reframed opt-in (author via the
`hooks-authoring` skill). New `scripts/check-hookless-cold-start.sh` +
bats lock the regression.
- **Scenario 3 (each removed hook accounted for):** a disposition table
in `primitive-chains.md` maps each removed hook *behavior* (context
injection, end-of-session curation, standards surfacing, validation
reminders) → an explicit replacement or "confirmed noise".
## Design notes
- The new gate rides the existing `bats tests/scripts/*.bats` CI lane
(no new `validate.yml` job, per plan). It scans a **fixed** list of
cold-start surfaces and flags any `hooks/<name>.sh` path presented
without an opt-in/historical hedge — deliberately *not* a broad
`docs/`+`skills/` grep (release notes / `hooks-authoring` / scope guards
legitimately name hook paths).
- `CLAUDE.md` is **hand-maintained**: `build-claude.py` is vestigial
(its `--check` reports STALE on clean `main` and it's absent from CI),
so `CLAUDE.md` was edited directly rather than regenerated — running the
generator would have clobbered it.
- Scenario-3's disposition was folded into the `primitive-chains.md`
Chain 6 reframe rather than a new doc (co-located, no catalogue-gate or
mkdocs-nav churn).
- Scope held tight: broader hook-taxonomy drift in `primitive-chains.md`
(Terminology Ledger / Audit Snapshot "7 hook event sections") and the
out-of-scope `CLAUDE.md:145` `session-pr-counter.sh`
(workflow-discipline, soc-waxr) are left for follow-up beads.
## Test plan
- [x] `bash scripts/check-hookless-cold-start.sh` → PASS (5 surfaces)
- [x] `bats tests/scripts/check-hookless-cold-start.bats` → 5/5
- [x] `shellcheck scripts/check-hookless-cold-start.sh` → clean
- [x] `bash scripts/audit-codex-parity.sh --skill session-bootstrap` →
passed
- [x] `bash skills/heal-skill/scripts/heal.sh --strict` → clean
- [x] `cd cli && make sync-hooks` → no embedded drift
- [x] `bash scripts/validate-agents-split.sh` → PASS (99 lines)
- [x] `markdownlint --config .markdownlint.json` on changed files →
clean
- [x] No Go changes (build/test unaffected)
Closes-scenario: soc-qh2g1#hookless-cold-start
Bounded-context: BC1-Corpus
Evidence: bash scripts/check-hookless-cold-start.sh; bats
tests/scripts/check-hookless-cold-start.bats
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
## What
Flips the docs/3.0.md **"Hooks audited for noise"** acceptance box from
`[ ]` to `[x]`. The 7 noise-injector hooks were **deleted outright**
across `soc-e2ju0` S1–S3 (they were value-negative: A/B Δ=0) — not
flipped to opt-in. 46 hooks remain, all gates or bounded adapters, none
a noise-injector.
## Changes
- **docs/3.0.md** — acceptance box `[ ]` → `[x]`; note now states the 7
noise-injectors were deleted (S1–S3), 46 hooks remain. The "Every
AgentOps bead worked or closed" box intentionally left `[ ]`. The
doctrine "default install works with zero hooks" line and the S2–S5
follow-on note are untouched (S4 default-install is not done yet).
- **docs/architecture/hook-noise-audit.md** — summary reframed: original
53-hook audit (14 gate / 25 bounded-adapter / 14 noise) → current
46-hook reality (20 gate / 26 bounded-adapter / **0 noise**). The 14
"noise" entries split into 7 true noise-injectors (deleted) + 7
conditional injectors (reclassified as gates). Noise-injector table →
all 7 deleted with their stage; gates list 14→20 (`go-vet-post-edit`
removed — it was deleted, not a surviving gate); bounded-adapters 25→26;
resolution note replaces the pending follow-on.
- **docs/3.0-readiness.md** — hooks box `[ ]` → `[x]`; net 4/6 → 5/6
boxes met; W3 row and remaining-work refreshed.
- **docs/documentation-index.md** — audit one-liner refreshed (no longer
implies noise-injectors exist).
- **skills/hooks-authoring/SKILL.md** — added a hookless-first
guardrail: hooks are gates/bounded-adapters, never noise-injectors.
Codex artifact + manifest source_hash regenerated for this skill only.
## Gates (all green)
- `validate-hooks-doc-parity.sh` — PASS
- `validate-codex-generated-artifacts.sh` — PASS (was failing on the
SKILL.md edit; fixed via scoped hash regen)
- `check-codex-parity-drift.sh` — PASS; `audit-codex-parity.sh --skill
hooks-authoring` — PASS
- `markdownlint` on all 6 touched md — PASS
- `heal.sh --strict skills/hooks-authoring` — clean
- Deleted-hook grep on docs/3.0.md + docs/HOOKS.md — empty (only
historical mentions remain in the audit doc)
Closes-scenario: soc-cul67#hookless-docs
Bounded-context: BC1-Corpus
Evidence: docs/3.0.md
## Summary
Deletes `commit-review-gate` — a value-negative noise-injector. Despite
its name it never blocked: it always exited 0 and injected the staged
diff + a "SELF-REVIEW" prompt on every `git commit` (A/B showed Δ=0).
Hookless S3 of the go-hookless epic (`soc-e2ju0`).
The "+7 conditional injectors" the original audit grouped with it were
reclassified as kept-gates (they speak only on a real violation) — **out
of scope, not deleted**. S3 removes only `commit-review-gate`.
## Changes
- **Hook scripts:** `git rm` of `hooks/commit-review-gate.sh` +
`cli/embedded/hooks/commit-review-gate.sh`
- **Go runtime:** removed `runCommitReviewHook` managed-backend + its
exclusive helpers (`gitOutput`, `countDiffFiles`, `hookCountLines`,
`firstLines`, `redactSensitiveDiff` + credential regexes) and the
now-dead `TestHooksRunRedactsSensitiveDiff` test
- **Manifests:** pruned from `hooks/hooks.json`,
`hooks/codex-hooks.json`, `registry.json`,
`hook-lease-classification.v1.json` (lease-inventory regenerated)
- **Codex handler count 15 → 14:** assertions in
`test-runtime-codex-smoke.sh` + `test-codex-native-install.sh`, plus
require-handler arrays in `install-codex-plugin.sh` /
`install-codex.ps1` / `test-codex-native-install.sh` /
`audit-codex-hooks.sh`
- **Test blocks:** removed commit-review @test blocks from
`test-hooks.bats`/`.sh`, `hook-output-schema.bats`,
`hook-stdin-contracts.bats`, the eval fixture, and
manifest-runtime-contracts
- **Docs:** `HOOKS.md`, `software-factory.md`, `how-it-works.md`,
`update-principles.md`, `SDK-INVENTORY.md`; `hook-noise-audit.md`
records the S3 deletion (46 hooks remaining)
- **Drive-by:** fixed pre-existing stale `length == 20` assertions in
`test-audit-codex-hooks.sh` (codex bundle is 14 post-delete; this test
is not CI-gated and was already failing on main)
## Verification (all green)
`check-hook-lease-inventory` · `validate-hooks-doc-parity` ·
`check-hook-port-replacements` · `validate-hook-preflight` ·
`generate-registry --check` · `smoke-test` · `test-runtime-codex-smoke`
(33/0) · `bats tests/hooks/*.bats tests/scripts/pre-push-gate.bats`
(297/0) · `test-agentops-contract-canaries` (failures=0, incl
pre-push-gate-governance + runtime-smoke-matrix) ·
`test-codex-native-install` · `test-audit-codex-hooks` (4/4) · `go
build/vet/test ./cmd/ao/`
Diff stat: 30 files, +26 / −569 (deletion-heavy, as expected).
Closes-scenario: soc-vpmzg#rm-commit-review-gate
Bounded-context: BC5-Runtime
Evidence: docs/contracts/hook-lease-inventory.md
## What
Hookless epic S2 (`soc-khev6`): delete the `standards-injector`
PreToolUse hook and **fully retire** its dedicated CI gate.
`standards-injector` is a value-negative noise-injector — it injects
language standards on every Edit/Write regardless of relevance (A/B Δ=0,
per `docs/architecture/hook-noise-audit.md`). The replacement is the
`standards` skill, read on demand: a PRODUCT surface, not hook magic.
## Teardown (all of it)
- **Hook + tests:** `git rm hooks/standards-injector.sh`, its embedded
copy, and `tests/hooks/standards-injector.bats`.
- **Manifests:** pruned the Edit + Write entries from `hooks/hooks.json`
and `hooks/codex-hooks.json`, dropping the now-empty matcher groups.
**Codex native handlers 17 → 15** (two entries removed, not one — Edit
retains `codex-parity-warn.sh`, Write group dropped).
- **CI gate retired:** removed the `standards-injector-completeness` job
from `validate.yml` + both `needs:` lists
(`validate-pr-evidence-claims`, `summary`) + the summary echo; `git rm`
the check script + its bats; removed from `ci-jobs.yaml` manifest and
regenerated `AGENTS-CI.md`; removed from `pre-push-gate.sh` + its bats
stub.
- **Codex test assertions (the S1 bite):** `test-runtime-codex-smoke.sh`
and `test-codex-native-install.sh` length `17 → 15`; removed
`standards-injector.sh` from the require-handlers array.
- **Shared iterators:** pruned the `@test`/section blocks from
`test-hooks.bats`, `hook-output-schema.bats`,
`hook-stdin-contracts.bats`, `test-hook-chain.sh`,
`test-hook-lifecycle.sh`, `test-hooks.sh`, and the eval fixture
`hook-context-value-smoke.sh`.
- **Other surfaces:** `validate-hook-preflight.sh`,
`install-codex-plugin.sh`, `install-codex.ps1` owned-script lists;
`hooks_test.go` (swapped synthetic name to a live hook);
`context_compiler.go` port doc comment.
- **Regen:** hook-lease classification + inventory, registry, embedded
sync.
- **Docs:** `HOOKS.md`, `hook-noise-audit.md` (records S2 deletion),
`ENV-VARS.md` (`AGENTOPS_STANDARDS_*` vars), `LOOP-BUDGET.md`,
`cli-skills-map.md`, `software-factory.md`, `SDK-INVENTORY.md`.
## Verify (all green locally)
`check-hook-lease-inventory`, `validate-hooks-doc-parity`,
`check-hook-port-replacements`, `validate-hook-preflight`,
`generate-registry --check`, `validate-ci-policy-parity`,
`tests/smoke-test.sh` (codex smoke + native install),
`test-runtime-codex-smoke.sh`, the 3 bats hook suites, `go
build/vet/test`. `grep standards-injector validate.yml
ci-local-release.sh` → empty.
Diff stat: 39 files, +32 / -1045 (deletion-heavy, as expected for a
teardown).
Closes-scenario: soc-khev6#rm-standards-injector
Bounded-context: BC5-Runtime
Evidence: docs/contracts/hook-lease-inventory.md
## What
Empirical ground-truth inventory of the AgentOps runtime hexagonal seam
(`cli/internal/ports` + adapters), taken 2026-05-23 against `main`.
Read-only analysis bead — adds one doc + one catalog line, NO code
changes.
Grounds the adapter backlog for epic **soc-zvhsl** so the
adapter-building beads (soc-rg5z0 WorkspacePort, soc-ebgjk TrackerPort,
soc-21mrg loop-state, soc-vzyhn corpus) execute against a precise plan.
Every claim cites a real `file:line`.
## Headline counts
- **26** declared port interfaces
- **18** have a real (non-in-memory) adapter
- **8** have no conforming adapter (in-memory-only or
signature-mismatched)
- **git: 35** direct `exec.Command("git", ...)` callsites; **bd: 10** —
reached without a port
## Key corrections to the prior survey
- The epic survey's "21 ports, only `storage_fs` is real" is **stale**:
26 interfaces, 18 real adapters (16 `production*` in `cmd/ao` from
compile-cycles 112/113, plus 3 in `cli/internal/wiki/`, plus
`storage_fs`).
- Required-7 (`check-hook-port-replacements.sh`): **3 real**
(EventBus/GateRunner/Harness), **4 in-memory-only**
(Closeout/ContextCompiler/SafetyPolicy/Workspace).
- `.agentops/loop-state.json` (cited in soc-21mrg) **does not exist** —
the real loop-state gap is the *frozen* RPI supervisor lane
(`rpi_loop_supervisor.go:1007-1139`); the evolve lane is already behind
the port.
- Corpus adapters are real but the **flywheel core**
(compile/mine/grow/defrag) bypasses them.
## Recommended adapter build order
1. WorkspacePort → `workspace_git` (soc-rg5z0, P1) — 35 git callsites,
port not even constructed
2. IssueTracker → bd adapter (soc-ebgjk, P1) — zero impls today; widen
to read paths
3. Corpus reader/writer adoption in flywheel core (soc-vzyhn, P2) —
migration not greenfield
4. Loop-state atomic adapter for the *live* lane (soc-21mrg, P2) —
resolve lane question first
Closes-scenario: soc-upwor#port-audit
Bounded-context: BC5-Runtime
Evidence: docs/architecture/hexagon-port-realness-audit.md
Docs-match-reality fix (same bug class as the W1 reconciliation). The
doc implied Codex is hookless *because it lacks a hook surface* —
contradicting its own top Note ("Codex supports native hooks"),
docs/HOOKS.md (Codex CLI 0.115.0+ native hooks; 0.128.0 same PreToolUse
schema as Claude), and hooks/codex-hooks.json (wires the same scripts
under `--with-hooks`).
- **Intro:** Codex CLI (0.115.0+) *does* expose native hooks; AgentOps
installs hookless **by default for portability**; the Codex **Desktop**
app has no `~/.codex` hook surface. Lifecycle path works hooks-or-not.
- **Runtime Modes table:** hook-capable row includes Codex CLI 0.115.0+
`--with-hooks`; fallback detection reframed to "no native-hook profile
installed (Desktop, or CLI installed hookless)".
Now consistent with the top Note + HOOKS.md. Surfaced when this doc
caused a wrong answer about Codex hook capability.
NOTE: claude-review infra-red (weekly limit, resets May 25) —
operator-authorized bypass when sole red.
Closes-scenario: soc-isewi#codex-cli-has-hooks
Bounded-context: BC5-Runtime
Evidence: docs/architecture/codex-hookless-lifecycle.md
W3 of the 3.0 reconciliation. Classifies every hook against
docs/3.0.md's *'hooks must not inject random noise'* criterion.
**docs/architecture/hook-noise-audit.md (NEW):** 53 hooks → **14 GATE ·
25 BOUNDED-ADAPTER · 14 NOISE-INJECTOR**. 39/53 (74%) already meet the
3.0 criterion.
**Key finding:** the 14 noise-injectors push `additionalContext` into
the prompt on every matching event regardless of relevance
(standards-injector; commit-review-gate — misnamed, never blocks;
edit-knowledge-surface; research/context nudges; …). All already honor
per-hook disable flags but are on-by-default. Top-4 verdicts verified
directly (grep: no deny/exit-2 + unconditional additionalContext), not
just from the audit swarm.
**Scope:** this PR is the **audit** (analysis). The behavior change —
flipping the 14 to opt-in-default so the default experience is quiet —
is **soc-e2ju0** (operator-confirmed audit-only here). W4 marks the
docs/3.0.md acceptance box accordingly.
NOTE: claude-review infra-red (weekly limit, resets May 25) —
operator-authorized bypass when sole red.
Closes-scenario: soc-6zihw#hook-noise-audit
Bounded-context: BC5-Runtime
Evidence: docs/architecture/hook-noise-audit.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
docs.yml runs `mkdocs build --strict`, which aborts on any warning. Seven
links from cdlc.md and operating-loop.md pointed at repo-root, .agents/,
and skills/ files outside the mkdocs docs/ source tree, producing 7 → 0
strict warnings once converted. Uses absolute github.com/boshu2/agentops
blob URLs, the same pattern already used in documentation-index.md.
Clears the Deploy Docs workflow, red on main for the last 2 runs.
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.
Introduce the CDLC operating loop as the execution discipline that runs
through the existing DDD/hexagonal seams, refactor 15 process skills to
billboard shape per the agreed tier line caps, and land the DDD frontmatter
v2 backfill (consumes/produces/context_rel) that was in flight on this
branch.
Doctrine + templates:
- docs/architecture/operating-loop.md: operational spine (BDD intent ->
vertical slices -> conflict-free wave -> bead acceptance -> evidence)
- docs/templates/intent-issue.md: BDD-shaped intent issue template
- docs/templates/slice-validation.md: per-slice validation plan template
- docs/cdlc.md: new section linking the conceptual seven phases to the
operating loop; operating-loop.md added to companion docs
- docs/templates/README.md + docs/documentation-index.md: catalog updates
- GOALS.md Directive #12: BDD intent + vertical slice decomposition gate
- .agents/research/2026-05-15-cdlc-dojo-doctrine.md (gitignored, local-only):
compact doctrine source for the maintainer
Process-skill sweep (15 skills):
- "Loop position" section added to: rpi, discovery, plan, implement, crank,
validation, brainstorm, pre-mortem, council, swarm, autodev, post-mortem,
forge, retro, vibe.
- Billboard refactor: bulk procedural content extracted from SKILL.md to
per-skill references/*.md for discovery, validation, implement, crank,
swarm, post-mortem, vibe (5,632 -> 3,205 SKILL.md lines, -43%, with
every new references/*.md linked back from its SKILL.md per the repo
gate).
- Restored ACT.3/ACT.4 sections in post-mortem after the billboard pass to
keep validate-next-work-contract-parity.sh green.
Validation:
- tests/skills/lint-skills.sh: all 15 PASS within declared tier caps
- scripts/audit-codex-parity.sh: PASS for all 15
- scripts/validate-next-work-contract-parity.sh: PASS
- scripts/pre-push-gate.sh --fast: PASS (0 failures, 50 skipped)
- cli/embedded mirror synced via 'cd cli && make sync-hooks'
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three architecture documents that complete the encoded DDD+Hexagonal
shape:
- docs/architecture/ports-and-adapters.md — one-page overview with
the inner-hexagon definition, primary (driving) and secondary
(driven) adapter inventories, the three ports (PacketRepository,
IssueTracker, LLMClient), an ASCII hexagon diagram, and a 4-step
"How to add a new adapter" recipe.
- docs/adr/ADR-0001-ddd-hexagonal-adoption.md — Nygard-style ADR
recording the decision to encode the architecture (with Cockburn
2005, Evans 2003, and the four mechanical-enforcement mechanisms
laid out in this epic).
- docs/architecture/primitive-chains.md — adds a "Hexagonal seams"
section pointing at the new domain/ports/adapters tree.
- docs/documentation-index.md — links the two new docs (the
Wave 2 context-map link stays put).
mkdocs build --strict passes.
Issue #9 of the DDD+Hexagonal v1 plan.
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>
Rename the athena skill to compile — a descriptive name that communicates
what it actually does. Extend with Karpathy's LLM Knowledge Bases architecture:
- New compile phase: LLM reads raw .agents/ artifacts and produces interlinked
markdown wiki at .agents/compiled/ with index.md, log.md, backlinks
- New lint phase: detects contradictions, orphan pages, stale claims, coverage gaps
- Pluggable compute backend via AGENTOPS_COMPILE_RUNTIME (ollama|claude|openai)
- Hash-based incremental compilation (only recompile changed sources)
- compile.sh engine with security fixes (no shell injection, path traversal guard)
- Full rename across 93 files: skills, docs, CLI, tests, hooks, scripts, codex
Existing Mine → Grow → Defrag cycle preserved as phases within the larger
compile workflow. No vector DB — compiled wiki IS the retrieval layer.
Fix right-side │ border alignment in box diagrams. Three fix types:
- Trailing space adjustment for border alignment
- Box border widening for content that exceeded width
- Bottom border dash count matching top border
Bo