docs(destale): wave 2 + ratchet — all live docs off retired tech (age-docs-staleness-remediation-cko)

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>
This commit is contained in:
Boden Fuller
2026-06-17 10:23:02 -04:00
parent 72283a5d1a
commit 7e447c02b5
52 changed files with 398 additions and 288 deletions
+1 -1
View File
@@ -12,7 +12,7 @@ tree.
| First repo setup | `ao quick-start` | `/quickstart`, then `/rpi "a small goal"` |
| Small, obvious change | [Quick Fix](quick-fix.md) | `/implement`, then `/vibe --quick recent` |
| New feature or broad change | [Complete Cycle](complete-cycle.md) | `/rpi "goal"` or `/plan` -> `/crank <epic-id>` |
| Existing tracked backlog | `ao reconcile --json`, then `bd ready` | `/implement <issue-id>` or `/crank <epic-id>` |
| Existing tracked backlog | `ao reconcile --json`, then `BEADS_DIR=$PWD/_beads br ready` | `/implement <issue-id>` or `/crank <epic-id>` |
| Review-only checkpoint | `/council validate this PR` | `/vibe recent` before merge |
| Terminal-native operation | `ao factory start --goal "goal"` | `ao rpi phased "goal"` and `ao rpi status` |
+29 -13
View File
@@ -20,18 +20,23 @@ Just describe what you want:
| "What should I work on?" | Shows status, suggests next task |
| "Where was I?" | Shows last session, current state, blockers |
### Option 2: Software Factory Lane (Recommended in Codex)
### Option 2: Software Factory Lane (Recommended)
The primary delivery path is the **operating loop**
([`docs/architecture/operating-loop.md`](../architecture/operating-loop.md)):
`ao session bootstrap` → `ao inject` → the seven-move loop →
`ao gate check --fast --scope head` → push to `main`.
```bash
# Start session with a goal-time briefing when possible
# Orient: standard startup report + decay-ranked prior context
ao session bootstrap
ao inject
# Optional: build a bounded goal-time briefing when the corpus supports it
ao factory start --goal "fix auth startup"
# Run the delivery lane
/rpi "fix auth startup"
# or: ao rpi phased "fix auth startup"
# Monitor long-running phased work
ao rpi status
# Drive the work through the operating loop, landing slices with the gate
ao gate check --fast --scope head
# End session
ao codex stop
@@ -40,9 +45,15 @@ ao codex stop
ao codex status
```
`ao factory start` keeps the operator lane explicit: build a bounded briefing if
the corpus can support it, run Codex startup, then move into RPI. The lower
level lifecycle commands still exist when you want direct control.
`ao session bootstrap` + `ao inject` are the explicit startup path (3.0 is
hookless — nothing auto-injects orientation). `ao factory start` keeps the
operator lane explicit: build a bounded briefing if the corpus can support it,
then drive the operating loop.
> **`/rpi` and `ao rpi` are load-bearing LEGACY, not the live path.** The phased
> RPI loop (`/rpi "fix auth startup"`, `ao rpi phased`, `ao rpi status`) still
> compiles and is the one-turn executor referenced below, but new work is driven
> through the operating loop above — not routed through the RPI loop.
### Option 3: Dream Compounding Run
@@ -484,9 +495,14 @@ cp .claude/templates/feature-list.json .
---
## Integration with RPI Workflow
## Integration with RPI Workflow (legacy executor)
For complex features, use the phased RPI flow:
> The phased RPI flow is the **load-bearing legacy** one-turn executor, not the
> primary navigation. Drive new work through the operating loop
> ([`docs/architecture/operating-loop.md`](../architecture/operating-loop.md));
> reach for RPI only when a turn explicitly needs the phased executor.
For complex features, the phased RPI flow runs:
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐