Completes the staleness epic. 42 P2/P3 files converged to current truth
(bd→br, gascity/gt-sling/mayor→NTM+Agent Mail, daemon→substrate, hooks→hookless,
CI-authoritative→push-to-main local Go gate); GLOSSARY's 18 dead skills/* links
repaired to ../skills/<name>/SKILL.md (19 links, 0 broken); contracts/runbooks
that freeze retired-system nouns bannered RETIRED/HISTORICAL rather than rewritten.
Adds the Arc-7 ratchet — scripts/check-docs-no-retired-tech.sh — which scans all
live docs (260) for retired-subsystem commands/phrases and fails on regression.
A doc opts out by carrying a RETIRED/HISTORICAL/SUPERSEDED banner (or being an
ADR / migration / upgrade / index doc), and lines that describe a removal are not
flagged. Running it caught 12 stale refs the deep-read sweep missed — a
"CI is the authoritative gate" cluster (agentops-brief, primitive-chains,
INCIDENT-RUNBOOK, knowledge-flywheel, philosophy, software-factory), stale
hook-smoke in release-e2e-checklist, and GasCity descriptors in
contracts/index + SCHEMAS + strategic-direction — now fixed. Gate: PASS.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## 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
**Wave 1 of the orchestration-substrate cascade rip** (soc-2rtm0). The
full cascade (daemon + dream/overnight + schedule/plans/watch + gc-glue
+ factory) is ~50K LOC across deeply-entangled packages — far past one
reviewable PR. Per the bead's slice directive and the recon map's
serial-by-wave verdict, this ships as sequential PRs by wave. **This is
the factory wave** (the only cleanly-disjoint slice — no KEEP-feature
entanglement).
## What this retires (operator-confirmed FULL factory retire)
**Go command surface** (no external non-test caller — clean delete):
- `cmd/ao/factory.go`, `factory_admit.go`, `factory_pilot.go`,
`factory_admission_adapter.go` (+ all tests)
- `internal/ports/factory_admission.go` +
`inmemory_factory_admission.go` (+ test) — the port was only wired to
the daemon by the deleted production adapter
- severed factory flag save/restore + command-tree assertions from
`cobra_commands_test.go` / `testutil_test.go`
**Contract corpus** (scripts, schemas, contract docs, runbooks,
fixtures, tests):
- `scripts/check-factory-{admission,claim-ledger,yield-ledger}.sh`
- `schemas/factory-{admission,work-order,yield}.v1.schema.json`
- `docs/contracts/factory-{admission,claim-ledger,yield-ledger}.*`
-
`docs/runbooks/{factory-manual-merge,daemon-factory-admission,cloud-frontier-pilot}.md`
- `tests/e2e/factory-operator-canary.sh`,
`tests/integration/test-factory-claim-ledger-ci-job.sh`,
`tests/scripts/test-factory-admission-contracts.py`,
`tests/fixtures/factory-*`
- orphaned `aggregate-observation-log` subsystem (script + integration
test + fixtures) — its only data source was the deleted
`factory-claim-ledger-strict` CI job
**CI / generated reconciliation:**
- removed 3 factory jobs from `validate.yml` (+ both `needs:` arrays +
verdict echoes); removed entries from `ci-jobs.yaml`; regenerated
`AGENTS-CI.md` (63 jobs)
- removed factory gate-ids from `GOALS.md`; trimmed
`contracts-structural-floor` factory references
- regenerated `registry.json` (177→174 CLI commands), `COMMANDS.md` (−70
lines), `cli-skills-map.md` (73→72 headings)
- updated `cli-command-surface-matrix` canary spec + fixture counts
(`top=72 sub=194 all=266`); scrubbed deleted-file links from
`documentation-index.md`, `SCHEMAS.md`, `contracts/index.md`,
`agentopsd-control-plane.md`, `insert-schema-practices.py`
## Deliberately left for the daemon-carve wave
Daemon-owned factory job types (`factory.admission`,
`factory.local-pilot`) and the `agentopsd` routing-policy schema remain
— they belong to `internal/daemon/` and retire when the daemon does.
## Gates verified green locally
`gofmt`/`go build`/`go vet`, full Go test (**11830 pass**),
`validate-ci-policy-parity`, `contract-compatibility`,
`contracts-structural-floor`, `registry --check`, `doc-release` (0
broken links), `smoke-test`, `json-flag-consistency` (0 errors),
**`contract-canaries` (failures=0)**, codex-hashes, `pre-push-gate.bats`
(55).
Diff: 66 files changed, ~16 insertions / ~5680 deletions.
Closes-scenario: soc-2rtm0#cascade-rip
Bounded-context: BC5-Runtime
Evidence: .agents/discovery/2026-05-24-rip-caller-map.md
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).
Boden Fuller