Add an --all-docs mode to check-doc-skill-refs.sh that scans the union of the
pinned doctrine files PLUS the full LIVE docs/** set (scripts/lib/docs-scope.sh),
ratcheted by a new filename-pinned shrink baseline
(scripts/.docs-skill-refs-baseline). Two-way ratchet: a non-baselined live doc
with a dead `/skill` ref FAILS; a baselined file that no longer offends FAILS
demanding a prune. Detection stays slash-syntax + headings only (never bare
skill names). Default (no-flag) behavior is byte-identical.
docs/SKILL-ROUTER.md (the curated router) is covered by --all-docs (a live
docs/** file, never baselined) so a dead ref there FAILS strict, without
perturbing the byte-identical default doc count.
seed.go docs.skill-refs row: Match widened to docs/** + the baseline + the lib;
Args set to [--all-docs --strict]. Burn-down (long-tail only): repointed retired
`/retro`->/post-mortem, `/vibe`->/validate, `/ratchet`->/flywheel,
`/research-multi`->/research, `/implement-wave`->/crank, and reworded the
retired `/dream` across 13 docs/levels + docs/workflows + docs/philosophy
pages, then pruned them from the baseline (91 -> 78 offenders). Owner-locked
pages (comparisons/getting-started/positioning) stay baselined.
Bats twin tests/scripts/check-doc-skill-refs-all-docs.bats covers all the modes.
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
Final slice of the **ag-lk80 doc-staleness epic**. Verified against the
repo.
**ag-ph6h remainder** (local-model / retired-infra framing):
- philosophy.md — "Local 8B (ollama)" Tier-1 caveated as
**optional/user-supplied** (AgentOps ships no model host); "/dream … Gas
City substrate" → out-of-session substrate (NTM + MCP + managed-agents).
- local-compute-routing.md — added a "**Design draft — NOT
implemented**" banner (the local-scout/local-review lanes don't exist as
skills; no local model host); bumped last-reviewed.
**ag-j4tw remainder** (dead test paths):
- testing-skills.md — `tests/_quarantine/claude-code` →
`tests/claude-code` (11 refs; verified that's the real dir with the
skill-test scripts).
- TESTING.md — removed/redirected 9 `tests/hooks/*.bats` refs (dir gone;
3.0 ships no hook scripts) → `tests/scripts/*.bats`; kept the real
git-hooks "Local Hooking" section.
## Verification
- `tests/hooks`=0, `tests/_quarantine/claude-code`=0 in the docs
- markdownlint → 0 errors; `validate-links.sh` → 0 broken (2903 checked)
Closes the last two open children of ag-lk80.
Closes-scenario: ag-ph6h#local-model
Closes-scenario: ag-j4tw#dead-test-paths
Bounded-context: BC1-Corpus
Evidence: docs/philosophy.md
Reframe two stale 2.x hook references in `docs/philosophy.md` to the
AgentOps 3.0 hookless model. Philosophy intact; only the stale hook
framing is corrected.
## Reframes
1. **"What This Is Not" (line 85)** — `the discipline enforced by the
hooks` → `the discipline enforced in CI`, plus an explicit sentence:
AgentOps 3.0 is hookless (skills + CLI guide the workflow, CI is the
authoritative gate); hooks are opt-in, author-it-yourself via the
`hooks-authoring` skill, never installed by default.
2. **"The Validated Thesis" (line 94)** — `10/12 \`ao doctor\` checks
passing with full 7/7 hook coverage` → `10/12 \`ao doctor\` checks
passing, with the full CI gate suite green`.
## Gates (all green)
- forbidden-phrase grep (`ao hooks install|hooks are the
architecture|hooks fire on every`): empty
- markdownlint `docs/philosophy.md`: clean
- mkdocs `--strict`: exit 0
- doc-release gate (`tests/docs/validate-doc-release.sh`): PASS
- diff stat: 1 file, +2 -2
Closes-scenario: ag-pgp#hookless-philosophy
Bounded-context: BC1-Corpus
Evidence: docs/philosophy.md
* docs(positioning): add assurance profile for agent factory rigor
* docs(positioning): frame goals as reconcile setpoints
* chore(scripts): suppress SC2034 on bd_out — set by run_capture via name-ref
Drive-by fix needed to push crank/soc-sx99 — pre-push shellcheck flagged
bd_out as unused in test-rpi-surface-smoke.sh, but it is set indirectly by
run_capture's name-ref pattern. Adds a targeted shellcheck disable comment.
The vertical `│` and corner `┘` on the "Better next session" loop sat
at column 70, one past "Gates" (which ends at column 69). The diagram
visually hung off the right edge.
Moved both to column 69 so the loop closes directly under the "s" of
"Gates". Rebalanced the horizontal fill (22 `─` before text, 21 after)
to preserve loop text centering.
Replaces the original 5-principles framing with the validated context
compiler thesis. Covers: environment problem, flywheel loop, .agents/
as universal format, tiered model, Brownian ratchet, and the Karpathy
bookkeeping insight. 98 lines, evidence-backed.
Five-month retrospective distilled into docs/philosophy.md (five validated
principles for building with coding agents) and a personal observations
section in the README. Links added to INDEX.md and README footer.
boshu