## What
New CI gate `validate-skill-body-refs` (T1) that scans the **inline-code
prose** of every `SKILL.md` + `references/*.md` (under `skills/` and
`skills-codex/`) for `` `ao <command>` `` / `` `ao <command> --flag` ``
tokens and validates each against the **live `ao` help tree**.
This is the systemic fix for oracle gap #3:
`validate-skill-cli-snippets.sh` only inspects fenced/`ao`-leading
snippets, so a stale command/flag named inside an inline code span
mid-sentence (e.g. `` `ao schedule` `` , `` `ao context assemble` ``)
regenerated after every CLI rename. This gate is the **complement** of
the snippet gate — together they cover both fenced snippets and prose.
## How the gate works
- Builds a robust live command tree: `ao capabilities` (authoritative
top-level) + recursive grouped-help subcommand parse (handles `ao
goals`' category-grouped help that the standard "Available Commands:"
parser misses) + command aliases (`quickstart` → `quick-start`) +
per-command flags.
- Only validates `ao` refs inside inline `` `code` `` spans — bare-prose
English ("if ao available", "ao not installed") is never treated as a
command, eliminating false positives while still catching the genuine
(always backtick-quoted) stale refs.
- Justified historical refs skip via an inline marker (`Superseded` /
`Historical` / `removed in` / `retained for history` / `(historical)`)
on the line/file, or `scripts/skill-body-refs-allowlist.txt`.
## Prose sweep (what made main pass)
The gate detected genuine stale refs on main; swept them to keep the
gate green:
- `ao context assemble` → `ao lookup` (8 sites — the command was never
built; `ao lookup` is the real co-cited replacement)
- `ao cite` → `ao metrics cite`
- `ao worktree gc` → `git worktree prune` (4 sites — `ao worktree` never
existed)
- `ao hooks` removal note → reworded to "removed in 3.0" (matches the
`removed in` historical marker)
## Allowlist contents
- `skills/standards/references/cli-wireup-template.md` — illustrative
naming template (deliberately names `ao loop-history` / `ao loop write`
/ `ao loop tail` as good/bad examples + future placeholders)
- `skills/release/references/release-notes.md`,
`skills-codex/release/references/release-notes.md` — historical
changelog prose (e.g. `ao daemon status` from the daemon era)
## Wiring
- `.github/workflows/validate.yml` — new T1 job + `summary.needs` +
`validate-pr-evidence-claims.needs` + summary echo (65 jobs)
- `docs/contracts/ci-jobs.yaml` — manifest entry (keeps
`validate-ci-policy-parity` green)
- `AGENTS-CI.md` — regenerated via `scripts/generate-ci-jobs-table.sh
--write`
- `tests/scripts/validate-skill-body-refs.bats` — 6 cases (clean pass,
stale-cmd fail, stale-flag fail, historical-marker skip, bare-prose
ignore, committed-tree pass)
## Verification (local, green)
- `bash scripts/validate-skill-body-refs.sh` → exit 0
- `scripts/validate-ci-policy-parity.sh` → PASS (65 rows)
- `scripts/validate-skill-cli-snippets.sh` → passed (no regression)
- `scripts/check-codex-parity-drift.sh` +
`validate-codex-generated-artifacts.sh --scope worktree` → passed (codex
hashes regenerated for the 6 edited skills only)
- `bats tests/scripts/validate-skill-body-refs.bats` → 6/6 ok
- `shellcheck scripts/validate-skill-body-refs.sh` → clean
- `markdownlint` on changed docs → clean
Closes-scenario: ag-4x8#body-ref-gate
Bounded-context: BC1-Corpus
Evidence: scripts/validate-skill-body-refs.sh
#275's billboard refactor thinned process-skill SKILL.md files and moved
detail into references/, but the validate contracts still grepped SKILL.md.
skill-lint + smoke-test: relax content-presence checks in crank/implement/
post-mortem/swarm validate.sh to scan the skill as a unit (SKILL.md +
references/); structural/identity checks stay SKILL.md-only. test-first-smoke
updated to match relocated SPEC/TEST WAVE + Step 0/4 headings.
skill-lint line caps: trim flywheel 310 -> 286 (cap 300), using-agentops
261 -> 239 (cap 250) by removing redundant prose, no content lost.
skill-integrity: link 3 orphaned references (crank/branch-isolation,
validation/flags + release-readiness-gates).
codex parity: regenerate stale skills-codex source hashes (77 skills).
Local: run-all.sh PASS, heal.sh --strict clean, smoke-test PASS.
Adds a 2400-char aggregate budget for skills-codex/*/SKILL.md `description:`
fields in tests/skills/test-token-budgets.sh, then trims each skill's description
to fit (catalog now 2146/2400). Both Claude and Codex SKILL.md descriptions
are kept in sync; codex .agentops-generated.json hashes regenerated.
Adds --repair-shape to scripts/audit-codex-hooks.sh: when ~/.codex/hooks.json
is missing or in legacy-flat shape, rewrites it from hooks/codex-hooks.json
with the active plugin_root (read from .agentops-codex-install.json) and
backs up any prior file. Covered by new test_repairs_legacy_flat_shape.
Memory decay (4 .agents/ files) bumped by the SessionStart inject hook.
* chore: preserve harvest praxis worktree state
* Release v2.39.0
* fix(tests): align next-work schema test with widened type enum
Commit ed35c47f added `docs` and `chore` to the script's VALID_TYPES,
but tests/scripts/check-next-work-schema-rows.bats:42 still used
`type:"docs"` as its supposed-to-be-rejected example, so the test
now passes through the validator — `bats-tests` has been red on
main since.
Switch the rejected-type example to `finding`, which is still
outside the enum and is also the canonical example cited in the
script's own header comment ("type=finding ... caught at push time").
Local: 11/11 in tests/scripts/check-next-work-schema-rows.bats pass.
* docs: capture finding generator postmortem (#157)
* fix(rpi): sort verdicts deterministically in context and status helpers (#158)
BuildPhaseContext and JoinVerdicts iterated the verdicts map directly,
producing non-deterministic output across runs. Sort keys before
rendering so prompt injection and status logs are reproducible.
Closes council finding W-7 (context-orchestration-leverage batch). The
related buildHandoffContext path was already fixed to delegate to
FormatVerdicts (which sorts); this completes the remaining helpers.
- cli/internal/rpi/status.go: sort keys in JoinVerdicts
- cli/internal/rpi/phased_context.go: sort keys in BuildPhaseContext
- tests: replace "ordering not deterministic" waivers with exact-order
asserts and add a 50-run stability check
https://claude.ai/code/session_01Qw4bZvXUNuLs8Rp1j1homB
Co-authored-by: Claude <noreply@anthropic.com>
* fix(codex): audit noisy hook injections (#159)
* docs: add competitive radar (#160)
* feat(agents): harden operator control plane (#161)
* docs(discovery): plan agents control plane hardening
* feat(agents): harden operator control plane
* Release v2.39.0
* fix(tests): align next-work schema test with widened type enum
Commit ed35c47f added `docs` and `chore` to the script's VALID_TYPES,
but tests/scripts/check-next-work-schema-rows.bats:42 still used
`type:"docs"` as its supposed-to-be-rejected example, so the test
now passes through the validator — `bats-tests` has been red on
main since.
Switch the rejected-type example to `finding`, which is still
outside the enum and is also the canonical example cited in the
script's own header comment ("type=finding ... caught at push time").
Local: 11/11 in tests/scripts/check-next-work-schema-rows.bats pass.
* docs: capture finding generator postmortem (#157)
* fix(rpi): sort verdicts deterministically in context and status helpers (#158)
BuildPhaseContext and JoinVerdicts iterated the verdicts map directly,
producing non-deterministic output across runs. Sort keys before
rendering so prompt injection and status logs are reproducible.
Closes council finding W-7 (context-orchestration-leverage batch). The
related buildHandoffContext path was already fixed to delegate to
FormatVerdicts (which sorts); this completes the remaining helpers.
- cli/internal/rpi/status.go: sort keys in JoinVerdicts
- cli/internal/rpi/phased_context.go: sort keys in BuildPhaseContext
- tests: replace "ordering not deterministic" waivers with exact-order
asserts and add a 50-run stability check
https://claude.ai/code/session_01Qw4bZvXUNuLs8Rp1j1homB
Co-authored-by: Claude <noreply@anthropic.com>
* fix(codex): audit noisy hook injections (#159)
* docs: add competitive radar (#160)
* fix(merge): drop unused AgentsDoctorError ref and prune allowlist entries without production refs
---------
Co-authored-by: Claude <noreply@anthropic.com>
* refactor(cli): go cli quality discovery batch (gc-bridge, json contracts, leaf-help smoke) (#162)
* docs: add go cli quality discovery plan
* fix(cli): harden gc bridge version parsing
* docs(go): align complexity policy with gates
* docs(cli): classify command surface
* fix(cli): enforce json output contracts
* feat(cli): expand completion coverage
* refactor(cli): pilot badge options writer
* refactor(cli): inject contradict output writer
* refactor(cli): inject notebook update writer
* fix(cli): enable gc runtime smoke coverage
* fix(cli): align gc bridge with gascity v1
* Release v2.39.0
* fix(tests): align next-work schema test with widened type enum
Commit ed35c47f added `docs` and `chore` to the script's VALID_TYPES,
but tests/scripts/check-next-work-schema-rows.bats:42 still used
`type:"docs"` as its supposed-to-be-rejected example, so the test
now passes through the validator — `bats-tests` has been red on
main since.
Switch the rejected-type example to `finding`, which is still
outside the enum and is also the canonical example cited in the
script's own header comment ("type=finding ... caught at push time").
Local: 11/11 in tests/scripts/check-next-work-schema-rows.bats pass.
* docs: capture finding generator postmortem (#157)
* fix(rpi): sort verdicts deterministically in context and status helpers (#158)
BuildPhaseContext and JoinVerdicts iterated the verdicts map directly,
producing non-deterministic output across runs. Sort keys before
rendering so prompt injection and status logs are reproducible.
Closes council finding W-7 (context-orchestration-leverage batch). The
related buildHandoffContext path was already fixed to delegate to
FormatVerdicts (which sorts); this completes the remaining helpers.
- cli/internal/rpi/status.go: sort keys in JoinVerdicts
- cli/internal/rpi/phased_context.go: sort keys in BuildPhaseContext
- tests: replace "ordering not deterministic" waivers with exact-order
asserts and add a 50-run stability check
https://claude.ai/code/session_01Qw4bZvXUNuLs8Rp1j1homB
Co-authored-by: Claude <noreply@anthropic.com>
* fix(codex): audit noisy hook injections (#159)
* docs: add competitive radar (#160)
* feat(agents): harden operator control plane (#161)
* docs(discovery): plan agents control plane hardening
* feat(agents): harden operator control plane
* Release v2.39.0
* fix(tests): align next-work schema test with widened type enum
Commit ed35c47f added `docs` and `chore` to the script's VALID_TYPES,
but tests/scripts/check-next-work-schema-rows.bats:42 still used
`type:"docs"` as its supposed-to-be-rejected example, so the test
now passes through the validator — `bats-tests` has been red on
main since.
Switch the rejected-type example to `finding`, which is still
outside the enum and is also the canonical example cited in the
script's own header comment ("type=finding ... caught at push time").
Local: 11/11 in tests/scripts/check-next-work-schema-rows.bats pass.
* docs: capture finding generator postmortem (#157)
* fix(rpi): sort verdicts deterministically in context and status helpers (#158)
BuildPhaseContext and JoinVerdicts iterated the verdicts map directly,
producing non-deterministic output across runs. Sort keys before
rendering so prompt injection and status logs are reproducible.
Closes council finding W-7 (context-orchestration-leverage batch). The
related buildHandoffContext path was already fixed to delegate to
FormatVerdicts (which sorts); this completes the remaining helpers.
- cli/internal/rpi/status.go: sort keys in JoinVerdicts
- cli/internal/rpi/phased_context.go: sort keys in BuildPhaseContext
- tests: replace "ordering not deterministic" waivers with exact-order
asserts and add a 50-run stability check
https://claude.ai/code/session_01Qw4bZvXUNuLs8Rp1j1homB
Co-authored-by: Claude <noreply@anthropic.com>
* fix(codex): audit noisy hook injections (#159)
* docs: add competitive radar (#160)
* fix(merge): drop unused AgentsDoctorError ref and prune allowlist entries without production refs
---------
Co-authored-by: Claude <noreply@anthropic.com>
* fix(merge): resolve conflicts by taking PR's refactored contradict/codex_runtime, main's overnight test schema
---------
Co-authored-by: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Create docs/skills-decision-tree.md as the single source of truth for
"which skill do I need?". Replace duplicate tables in harvest SKILL.md,
knowledge-activation SKILL.md, and skills-codex mirrors with a pointer
link. Add INDEX.md entry.
Four files used to carry the same table; future edits now go in one
place. Quickstart already surfaces the individual skills under its
GIT=false + GLOBAL_AGENTS=true branch, so it does not need the
expanded reference — it is the entry point, not the index.
Closes na-pmx1.7.
Mirrors the decision table added to harvest/compile on 2026-04-15. Makes
the full onboarding chain (harvest → compile → dream → activate)
explicit so new users can answer "which skill do I need next?" from the
activation SKILL.md alone.
Closes na-pmx1.4.
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.
Bo