AgentOps' 55-skill catalog contained overlapping entry points, stale
routes and descriptions that could lose meaningful guidance in the Codex
projection. This change consolidates 21 roots into existing owners,
leaving 34 distinct skills and a generated, task-oriented menu. README
documents every retired name and its replacement.
Planning now establishes observable behavior in the caller's existing
intent, using proportional Given/When/Then examples and domain language.
Implementation and final validation carry those same examples forward.
Original adaptations informed by Matt Pocock's engineering skills
strengthen existing owners rather than adding a new workflow. Routine
edits need no mandatory plan, coverage report, mutation exercise or
learning artifact.
Codex retains complete source descriptions and translates explicit-only
invocation policy. All descriptions fit the existing 180-character
limit; the root instructions retain their 250-line limit. Generated
catalogs, projections, routers, moved references/helpers and their live
consumers are updated together. RPI remains explicitly selected.
Validation passed: projection/conformance checks, the local aggregate
(10 passed; one existing optional-directory skip), and exact-commit CI
covering the complete gate registry, Bats, Go build/vet/race/coverage,
Windows and security. A fresh author-distinct reviewer passed all
acceptance criteria over the complete 573-path subject at
aa642a55d6, including the installed-link
and protected-backup changes. Review findings were repaired and
revalidated. Existing ranker goldens are regression checks, not
model-quality measurements. A fixed six-case fresh-context pilot
supplied an exact candidate menu: three of four targeted cases loaded
expected guidance, a simple refactor selected no skill, and both
no-skill controls selected none. No wrong owner was selected. This pilot
preceded final wording repairs for existing ranker/context limits; it
does not establish installed automatic activation, coding benefit or
savings. No live coding task was run in that pilot.
> **Residues closed on the caller's merge instruction** (`499d916a6`):
the round-2 findings were the same failure shape — round-1 repairs
patched cited lines instead of sweeping the class — so this commit
sweeps each file whole: every remaining SATURATED-row-append site in
skill-eval now routes to RUNBOOK retirement, the human-only-skills
*description* is runtime-conditional, premortem's "(MEASURED)" label is
gone, SKILL-API's context table carries all 25 rows and the enforcement
table gains `disable-model-invocation`, and the fixture-identity claim
is stated precisely (probe id, honesty note, and control arm are the
only differing fields — as the acceptance permits). Post-sweep:
validators, full Go suite, 68/68 gates, goldens + headroom bats green,
projections current, gemini in sync. Merging per Bo's instruction.
## What
Train 1 of the accepted [instrument-panel
roadmap](docs/plans/2026-08-26-instrument-panel-roadmap.md) (intent
landed at `986a4feaf`): the measurement substrate, the skill-context
diet, and the retrieval-eval contract. Three worktree-isolated lanes,
each independently validated by a fresh context, plus one integration
commit. 103 files, +5,510/−76.
**L1 — measurement substrate** (`instrument/measurement-substrate`)
- Gate `skill.probe-headroom` (advisory, Fast|Full): answers the
question `skill.probe-coverage` cannot — not "does a probe result exist"
but "could one have existed at all". The rule, ported to Go
(`cli/internal/probeheadroom` + `cli/cmd/probe-headroom` behind a thin
check script — the witness-crosscheck pattern, **no new `ao` root
command**): control arm ≥ 0.75 with ≥ 2 usable reps at ≥ 2 effort levels
⇒ SATURATED (void row, not an honest null); UNMEASURED outranks it;
treatment-silent ⇒ FLOOR; else SEPARATED. RED first: both committed
fixture pairs read `INERT` to everything else in the repo; the failing
separation test predates the implementation, and a bats negative-control
swaps fixture bytes and asserts the gate flips.
- **First reading on real data: 7 of 11 historical probe groups are
SATURATED** — including both `validate-not-proven` runs. Those INERT
rows were never honest nulls; they were void. The 0/12 ledger number now
argues itself.
- Declared denominator for probe-coverage:
`scripts/.skill-probe-denominator-exclusions`, fail-closed parser (entry
without an argument, stale slug, or duplicate ⇒ exit 2). One entry
(`goals`, a pure alias-of `fitness`). Net effect deliberately zero (0/12
→ 0/12: alias left, `one-way-door` entered) — the gain is a declared
number, not a better-looking one.
- Re-landed from the recovered clean-room commit (`9872483bd`),
re-validated against *current* main: `skill-eval` (defers saturation to
the gate id; its shell scripts dropped, not shipped — ratchet intent),
`route`, `one-way-door`, premortem reversibility check, council
`caller_challenge` (schema + validator, per the agent-core boundary that
the panel may challenge, never overrule).
**L4 — context diet** (`instrument/context-diet`)
- `disable-model-invocation: true` on 4 human-only skills (key verified
verbatim against Anthropic's docs). The plan guessed 35 candidates; the
graph said otherwise — 23 carry `user-invocable: true`, and 19 of those
are excluded on cited evidence (rpi consumes
anti-ceremony/implement/plan/validate; workflow scripts reach others;
`goals` is a live migration tombstone). The exclusion evidence is
retained in the lane report.
- One router skill (`human-only-skills`) — the single always-loaded
description that replaces four; it hints, never fires.
- `.out-of-scope/` formalized with this week's three refusals
(checked-in knowledge corpus; ee self-improvement loops; whole-skill A/B
as the measurement unit), each citing its evidence.
- Deterministic proof, no model eval: before/after bytes of
always-loaded description load reported in the lane summary.
**L5 — retrieval-eval contract** (`instrument/retrieval-contract`, lane
verdict PASS 10/10)
- `AGENTS.md` federated row now names **ee (eidetic-engine)** as a
concrete caller-selected memory system — consume, never build; symlink
intact.
- `schemas/pack-quality-expectations.v1.schema.json` + 4 routing goldens
+ `scripts/check-routing-probe-goldens.sh` graded against `ao skills
find`, wired as an **advisory** nightly job. Zero goldens is a failing
state — no new zero-denominator green.
- **The instrument caught a real miss on day one — and its own
prescription fixed it.** Golden `rq-04` expects `validate` for "judge
whether this finished change is actually proven before I merge it"; at
authoring, `ao skills find` ranked the *forbidden* `premortem` first and
`validate` nowhere in six natural phrasings. The pointer-wording-first
repair (validate's description gained the caller's own words: finished,
proven, verdict, merge) now ranks it #1 at 0.333; grader 6/6, and the
golden pins the repair — a description regression reopens it.
## Integration
`regen-all.sh` once over the merged lanes (catalog 52 → 56, four new
codex twins, mesh, router, manifests); `skills/route/SKILL.md`
catalog/router links became prose repo-root references (the projected
twin cannot resolve `../catalog.json` — this was both the
portable-conformance failure and the sole broken doc link);
`codex-portable-conformance.bats` pin 52 → 56.
## Evidence
- `cd cli && go build ./... && go vet ./... && go test ./...` exit 0 ·
`ao gate check --full` **68/68** · four skill validators PASS ·
probe-headroom / routing-goldens / probe-coverage bats PASS ·
`regen-all.sh --check` all current.
- Per-lane fresh validators re-ran every suite on detached content; L5
PASS; L1/L4 NOT_PROVEN solely on the projection-regen clause reserved
for integration (their remaining acceptance observed green), settled
above. Cross-family (Codex) review of the integrated diff recorded in
the session report.
- Two disclosed scope stretches accepted at integration: a one-line
`.gitignore` entry mirroring the witness-crosscheck precedent, and the
probe LEDGER.md fact-correction L1's own change made necessary (noted
for Train 2's L2, which owns that file next).
## Cross-family review (Codex, fresh context)
Round 1: **FAIL** — two blockers (the RED fixtures didn't isolate the
control arm; the goldens grader was red where the plan's acceptance says
green) and eight majors (contract contradictions in the re-landed
skills, a converter-substitution false claim in the codex router twin,
two overreaching `.out-of-scope` entries, stale SKILL-API counts). All
repaired in one bounded round (`db68935a3`): fixtures now byte-identical
outside the control arm, the routing miss actually fixed rather than
tolerated, every cited contradiction reconciled at the source and
re-projected. Post-repair: full Go suite exit 0, `gate check --full`
68/68, all validators and probe/goldens bats green, projections current,
gemini byte-identity restored. Focused re-check verdict recorded in the
session report.
## Follow-ups (Train 2, already planned)
Seeded-defect probes for the judgment spine (every ledger row citing a
passing headroom pre-screen) and the gate-hardening pair
(`Gate-Loosen-Reason` tightening ratchet; mechanical
grounding-validation over evidence docs). Plus, surfaced by this train:
a latent `valid_keys`/schema divergence in `validate-skill-schema.sh`
(two keys the schema defines are absent from the script's allowlist —
pre-existing).
> **Review findings closed.** The re-check's residue (`perl -pibak`
bundled-cluster bypass) is applied in `2675bb383`: the perl alternation
accepts any non-space run after the in-place flag, a new FIRE bats
proves the deny, 48/48 policy-dispatch bats green, codex twins
regenerated. Merging on Bo's instruction.
## What
Five semantic lanes from the 2026-08-23 estate audit, each implemented
in an isolated worktree and independently validated by a fresh context,
plus one integration-fixup commit.
**1. Goals: the zero-denominator green is dead** (`estate/goals-honest`)
`GOALS.md` lost its Gates table in the 07-14 cut, so `ao goals validate`
reported `Valid: true` with `GoalCount: 0` in the release smoke on every
push. Now: zero parsed goals ⇒ `Valid: false` with an actionable error
(RED test first); `GOALS.md` carries a real 6-row Gates table whose
every `Check` was executed via `ao goals measure` before shipping;
`goals-affects-files.yaml` pruned of dead ids; the smoke asserts
`goal_count ≥ 1`. Two of the eight fitness properties
(behavior-before-activity, stop-boundary) have no executable check yet —
disclosed in GOALS.md rather than faked.
**2. Front door: the contract file gets a map** (`estate/front-door`)
`AGENTS.md` had zero build/test commands and zero layout — the Go
mechanics lived only in `.claude/rules/go.md`, which Codex (the declared
default runtime) never loads. Added a terse "Repository map and
mechanics" section; compressed the architecture-poetry opener to plain
language; README opens with what-it-does, the maintainer binary install
moved to `docs/install-day2-ops.md`, and the quickstart now ends with an
invitation to open an issue with your verdict. Deleted the dead
`.claude/CLAUDE-base.md` + `build-claude.py` pipeline (zero consumers
since June). `CLAUDE.md` remains a symlink to `AGENTS.md`.
**3. Hooks: first policy that guards the user's invariant**
(`estate/hooks-invariant`)
All four shipped policies guarded this repo's own artifacts. New
`core.verdicts:hand-edit` denies Edit/Write/Bash hand-writes into
`.agents/ao/verdicts/**` — verdicts are content-addressed evidence
written only by the validate flow. RED committed before GREEN
(`d264682c0`); bats prove deny on hand-writes and allow on reads,
intents, and the sanctioned `validate.py` writer. The lane shipped with
in-place editors disclosed as un-matched; the cross-family review
treated that as a blocker and the gap is closed in this PR (see below).
**4. bdd-foundry stops instructing dead commands**
(`estate/workflows-fix`)
The R4 phase told agents to run `ao yield emit`; Phase 5 said pull
holdouts via `ao scenario`; comments cited `ao membrane derive-checks` —
all tombstoned, so R4 failed on every run. Emission is dropped per the
tombstone's guidance (observation stays in the workflow result), Phase 5
grades in-run ground truth plus any caller-supplied register scenarios,
and the lane's initially-overreaching "there is no external holdout
register" wording was caught by its validator and corrected in
integration. Bonus: `workflow-scripts-syntax.yml` globbed the gitignored
`.claude/workflows/` (matched nothing in CI since inception) — now
checks the tracked `workflows/` tree.
**5. Docs honesty: retired vocabulary stops reading as live**
(`estate/docs-honesty`)
`intel_scope` removed from all 24 source SKILL.md + fixture + template +
tutorial (declared by half the corpus, read by zero Go); the schema
keeps accepting it for old-shape third-party skills but now
self-describes as deprecated. `docs/SKILL-API.md` no longer presents
`INTEL`/flywheel/forge/push/ratchet as live.
`docs/knowledge-flywheel.md` states design-vs-implemented truthfully.
ADR-0014's dead link fixed. 25 drifted `images/gemini/skills/` copies
re-synced byte-identical per that bundle's own README contract. All
codex projections regenerated once at integration (`regen-all.sh
--check` passes).
## Evidence
- `cd cli && go test ./...` exit 0 · 4 skill validators PASS ·
`policy-dispatch.bats` + `cross-runtime-hook-baseline.bats` PASS ·
`check-doc-hooks-drift` + `check-hookless-cold-start` PASS ·
`validate-goal-count` PASS · `node --check` on all 8 workflow scripts
PASS · `regen-all.sh --check` PASS
- From repo root: `ao goals validate --json` → `valid: true, goal_count:
6`; from a wrong cwd it now fails closed instead of reporting green.
- Each lane branch carries its own commits; merge commits preserve the
lane structure. Fresh per-lane validators re-ran every suite themselves;
the one FAIL each (workflows wording, cross-lane doc fallout) was fixed
in the integration commit, not waived.
## Cross-family review (Codex, fresh context)
First pass: **FAIL** with one blocker — the new verdict guard explicitly
excluded in-place editors, so `sed -i` silently mutated digest-named
evidence (dispatcher probe returned exit 0). Repaired in `f53945c26`
(one bounded round): three FIRE bats observed RED before the matcher
landed (in-place sed, in-place perl, file deletion), two negative bats
prove reads never fire; policy rationale and SKILL.md updated; codex
twins regenerated; 47/47 bats green. Everything else in the first pass
was affirmed (goals behavior, symlink/build bar, zero retired verbs in
workflows, byte-identical gemini copies, current projections). Focused
re-check: blocker confirmed closed via the dispatcher probe; one regex
corner (`perl -pibak`, header note above) stopped the loop under the
spiral rule.
## Follow-ups (not in this PR)
- `workflows/bdd-foundry.js` `SKILL` constant points at
`skills/behavior-first-planning/SKILL.md`, which was retired in v3.3 —
every phase prompt references a dead path (pre-existing). Needs a design
call: restore the phase discipline inline or repoint honestly.
- Verdict-guard: the noclobber override redirect (`>|`) remains the one
disclosed unmatched write shape.
- `docs/UPGRADING.md` note for third parties still declaring
`intel_scope` (schema accepts, nothing reads).
Migrate SYSTEM and AGENTS-{WORKFLOW,CI,CODEX,RUNTIME} into docs owners,
retarget consumers, rewrite the split gate, and craft-densify AGENTS,
README, PRODUCT, and GOALS under the documentation authority graph.
Co-authored-by: Cursor <cursoragent@cursor.com>
- docs/contracts/codex-skill-api.md: source of truth for Codex runtime
skill structure, frontmatter, discovery paths, multi-agent primitives
- scripts/validate-codex-api-conformance.sh: checks generated codex
skills against actual Codex API (baseline: 12 failures, 124 refs)
- Add contract to docs/INDEX.md
Bo