Three low-severity **ag-lk80** post-mortem papercuts, one chore arc
(single rollback semantic).
## 1. ASCII-diagram skill-count drift guard — `sync-skill-counts.sh`
`docs/agentops-system-map.md` and `docs/agentops-brief.md` hardcode the
skill count inside box-drawing borders whose column widths are
alignment-sensitive. `patch_file` deliberately won't auto-rewrite them
(a digit-width change, e.g. `99→100`, silently breaks the box). Added
the sanctioned **tolerant check**: every `<N> [shared] skills` token
must equal the on-disk skill TOTAL, else FAIL so a human re-pads the
box. Closes the drift class auto-patch left open. Works in both
`--check` and apply modes (reuses the existing `errors` counter).
## 2. `bd hooks` commit noise — not repo-actionable
The help-text dumped on every commit comes from `.git/hooks/*`
bd-installed shims (**local, untracked git state**) — fixable only by a
bd-tool change or a local `bd hooks` reinstall, nothing committable in
agentops. Documented as resolved-here-not-applicable (the dump even
appears in this PR's own commit step).
## 3. Drop dead `hooks/` scan — `check-agents-write-surfaces.sh`
`hooks/` doesn't exist post-3.0-teardown, so the `[[ -d hooks ]]` scan
was a guaranteed no-op. Removed it + its comment. **Kept**
`writer["hooks"]` — `hooks` remains a valid *opt-in* writer-surface
label per `docs/contracts/agents-write-surfaces.md` (only the dead
directory scan was vestigial, not the classifier vocabulary).
## Verification
- `sync-skill-counts.sh --check` → PASS; guard FAILs on an injected
`82→99` drift (confirmed it bites)
- `check-agents-write-surfaces.sh` → PASS (68 referenced subdirs, all
documented); **24/24 bats green**
- `shellcheck` clean on both scripts
Closes-scenario: ag-c4wn#lk80-papercuts
Bounded-context: BC2-Validation
Evidence: scripts/sync-skill-counts.sh
## What
Verified-clean subset of the second-wave counts/misc bead (ag-j4tw).
- **GLOSSARY.md:170** "ships 66 shared skills" → 82, and **extended
`sync-skill-counts.sh`** to cover the call-site so it self-heals and CI
catches future drift (same gate pattern as ag-bcl4).
- **test-architecture-debt-analysis.md:3** hardcoded Mac path
`/Users/fullerbt/…/cli/cmd/ao/` → repo-relative `cli/cmd/ao/`.
## Verify-first dropped FALSE POSITIVES
Applying the session's recurring lesson (audit agents over-flag):
- ENV-VARS `COUNCIL_EXPLORER_MODEL/TIMEOUT`, `COUNCIL_R2_TIMEOUT` are
**live** (consumed by `skills/council/`, not `cli/` — the audit only
grepped cli/).
- `MEMRL_MODE` exists (3 files); `rg-optimized.md:70` is blank; ROADMAP
"hookless S2–S5" is a real follow-on; `ao inject` is live.
## Still open (ag-j4tw stays open)
- agentops-brief.md / agentops-system-map.md counts are entangled in
**hook-diagram lines** → handle with ag-t1ca.
- TESTING.md `tests/hooks/` (hooks) + testing-skills.md
`tests/_quarantine/claude-code` → `tests/claude-code` (larger path
rework).
## Verification
- `scripts/sync-skill-counts.sh --check` → clean (GLOSSARY now covered)
Closes-scenario: ag-j4tw#counts-glossary
Bounded-context: BC2-Validation
Evidence: docs/GLOSSARY.md
## 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
Squash merge PR #546. Local evidence: doc-release, smoke, snapshot gate, pre-push Bats, snapshot Bats, structural gates, and pre-push --fast passed. PR GitHub Actions were blocked in runner setup by GitHub codeload/action download failures before repository code executed. Snapshot records current corpus as DECAYING rather than preserving stale compounding evidence.
Replace four-layer model (bookkeeping/validation/primitives/flows) with
three product layers that map to the CDLC loop: Context Compiler,
Validation Gates, Knowledge Flywheel. Update sync-skill-counts.sh
patterns to match the new PRODUCT.md heading format.
Bo