## What
Remediates verified staleness from the 2026-06-03 doc audit of root
governance/product docs + the key `docs/` cluster. Two systemic rot
patterns drove almost every finding: **skill-count drift** (73/78/~80 vs
truth 82) and **hooks references that survived the 3.0 hookless
teardown**.
All fixes independently verified against `cli/**`, `scripts/**`,
`.github/workflows/validate.yml`, and `skills/**`.
## Changes (by bead)
| Bead | Sev | Fix |
|---|---|---|
| ag-swi1 | CRIT | `newcomer-guide.md`: removed hooks-as-runtime-layer
framing (3.0 ships zero hooks); 5→4 layers; fixed dead
`scripts/install-dev-hooks.sh` ref; reframed hooks as opt-in via
`hooks-authoring` skill |
| ag-99xv | CRIT | `index.md`: skill count 73→82. **The "broken catalog
link" was a false positive** — `docs/skills/catalog.md` is generated at
build by `gen_skill_pages.py`; link left unchanged |
| ag-xa2b | CRIT | `cli-skills-map.md`: removed 5 phantom skills
(`pr-plan`, `pr-retro`, `update`, `readme`, `oss-docs`) an agent could
mis-invoke. Deep hooks-decoupling of this file (title, "Hook Callers"
column, "Hooks → Commands" section) **decomposed to a follow-up** —
half-editing leaves it internally inconsistent |
| ag-w4t8 | CRIT | `AGENTS-CI.md`: dropped retired advisory rows
`practice-citations` (RETIRED 2026-05-19) and
`factory-claim-ledger-strict` (no such job; references nonexistent file)
|
| ag-bcl4 | HIGH | `index.md` + `documentation-index.md`: counts → 82,
**and extended `sync-skill-counts.sh`** to cover both call-sites so the
count self-heals and CI (`validate-doc-release.sh` → `sync --check`)
catches future drift — the durable fix, not just retyping the number |
| ag-p7zg | HIGH | `CLAUDE.md`: aligned Ship-phase pre-push command to
`scripts/pre-push-gate.sh --fast`, matching `AGENTS-WORKFLOW.md` |
| ag-y5ii | MED | `documentation-index.md`: dropped stale "hooks" from
the how-it-works description |
## Deferred (filed as follow-up beads, not in this PR)
- PRODUCT.md "April 2026 Claude Code source analysis" reframe — product
positioning, operator's call
- Full hooks-decoupling of `cli-skills-map.md` — structural rework,
needs its own verification
- `bd worktree create --branch` syntax is wrong in
CLAUDE.md/AGENTS-WORKFLOW.md (needs a positional name) — discovered this
session
- `validate-bd-closeout-contract.sh` requires `bd dolt push` conditional
wording in AGENTS.md that the AGENTS split dropped (pre-existing main
red, local-only gate)
- Second-wave sweep of the remaining ~80 `docs/` files (ag-bz8n)
## Verification
- `scripts/sync-skill-counts.sh --check` → clean (both new call-sites
covered)
- `scripts/validate-cli-skills-map.sh` → PASS
- `tests/docs/validate-doc-release.sh` → PASS
- No residual `hooks/` / `hooks.json` runtime refs in
`newcomer-guide.md`
- All referenced paths exist (`skills/hooks-authoring/`,
`scripts/pre-push-gate.sh`)
Closes-scenario: ag-lk80#staleness-fixes
Bounded-context: BC1-Corpus
Evidence: docs/index.md
## 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
docs/INDEX.md (contract catalog) and docs/index.md (MkDocs landing) shared the
same case-folded name on case-insensitive filesystems, leaving the working tree
in a phantom-modified state and breaking contract-compatibility-gate when the
script read whichever file the OS resolved at run time.
Resolves TASK-1 + TASK-2 of .agents/plans/2026-04-26-resolve-docs-index-case-collision.md:
- Move catalog content from HEAD:docs/INDEX.md into docs/documentation-index.md
- Repoint contract validators (scripts/check-contract-compatibility.sh,
scripts/contract-orphans-allowlist.txt) and their tests at the new path
- Update navigation references across README.md, AGENTS.md, CLAUDE.md, and the
docs/ tree (newcomer-guide, CONTRIBUTING, CI-CD, plans/, positioning/,
templates/, contract examples)
- Replace stale docs/README.md mentions in CLAUDE.md / AGENTS.md / repo-execution
profile example with docs/index.md (the actual MkDocs landing)
Verification:
- bash scripts/check-contract-compatibility.sh -> 0 failures, 24 contracts catalogued
- bash tests/scripts/test-contract-compatibility-gate.sh -> 7/7 PASS (verified pre-rebase)
- bash tests/skills/test-repo-native-orchestration.sh -> 28/28 PASS (verified pre-rebase)
- git ls-files | awk casefold-dup scan -> empty
TASK-3 (casefold-collision guard script) and TASK-4 (worktree disposition) from
the plan remain to be done in a follow-up.
Addresses a batch of documentation improvements identified in a full-docs
audit. The goal is to reduce newcomer friction from dead links and missing
canonical references, and to give skill/plugin authors explicit pages for
hooks, schemas, and version migration that were previously implied only by
source code.
Navigation fixes:
- docs/INDEX.md and docs/newcomer-guide.md pointed to the wrong path for
the CLI reference (cli/commands.md vs. the real cli/docs/COMMANDS.md).
Replace with the canonical github URL so both mkdocs and raw-GitHub
readers land on the file.
- INDEX.md Getting Started section now opens with a "pick your path"
router so evaluators, installers, contributors, and upgraders don't
have to triangulate across three overlapping entry points.
- Link docs/getting-started/index.md from INDEX.md (was previously
orphaned) and add an "Install verification" block pointing at ao doctor.
New pages:
- docs/HOOKS.md: user-facing orientation covering lifecycle events,
install/uninstall, customization env vars, and common failure modes,
pointing to cli/docs/HOOKS.md for the deep technical reference.
- docs/SCHEMAS.md: catalog of every JSON Schema under schemas/ and
lib/schemas/, grouped by manifest vs. runtime artifact vs. internal
contract, with validation commands.
- docs/UPGRADING.md: action-required version migration guide. Seeds
Unreleased (2.38.x) and 2.37.x sections covering strict delegation,
--no-lifecycle -> --no-scaffold rename, Olympus bridge removal,
swarm-evidence schema enforcement, and pre-mortem gate tightening.
Reference quality:
- GLOSSARY.md: 11 new terms (.agents/, MEMORY.md, Compact/PreCompact,
Compile, Context Window, Discovery, Dream/Overnight Run alias,
Flywheel Health, Harvest, Holdout, RPI Phase, Session Lifecycle).
- troubleshooting.md: three new failure-mode sections (pre-mortem gate,
go-test-precommit block, context-window compaction recovery).
- CONTRIBUTING.md: escalates the sync-skill-counts.sh requirement from
an easily-missed sentence to a bold callout with CI-failure rationale.
mkdocs.yml: registers the three new pages in nav so they're reachable
from the published site and pass strict build.
Validation:
- tests/docs/validate-links.sh: 1553 links checked, 0 broken.
- tests/docs/validate-doc-release.sh: PASS.
- scripts/docs-build.sh --check: new docs introduce 0 warnings (the
single remaining preexisting warning about index.md is out of scope).
## 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>
Bo