feat(ci): gate live-hooks reintroduction in docs/ (ag-rryf #doc-hooks-drift-gate) (#713)

## What

Adds `scripts/check-doc-hooks-drift.sh` — a CI regression guard that
fails when a **live-facing** doc reintroduces a live hooks runtime after
the 3.0 hookless teardown:

- `hooks/hooks.json` (retired manifest), a `hooks/<name>.sh` runtime
path,
- `ao hooks` (not a registered command — verified absent from
`cli/cmd/ao/`),
- a bare `session-{start,end,autostart}*.sh` hook-file ref

…unless the **same line** hedges it as hookless / opt-in / historical /
removed / a git-hook. Companion to `sync-skill-counts.sh` (skill-count
drift) and `check-hookless-cold-start.sh` (fixed-list cold-start gate).

## Scope (and why the exclusions)

`docs/` **minus** surfaces that legitimately/archivally name hooks:
- **archival history** — `CHANGELOG.md`, `releases/`, `learnings/`,
`plans/`, `adr/`, `convergence/`, `sovereignty-proof/` (document the
past / the removal itself)
- **opt-in subsystem** — `contracts/` (hooks-authoring opt-in specs),
`runbooks/` (diagnostic enumeration), `code-map/` (point-in-time audits)

The gate keeps the onboarding / operator / architecture narrative
hookless.

## Also: finishes the ag-t1ca residue the gate flags

The ag-t1ca de-hooking missed 8 live-facing lines (gate caught them);
each is reframed:
- stale `ao hooks` command/smoke refs → removed / `ao doctor`
(`cli-skills-map`, `UPGRADING`, `release-e2e-checklist`,
`contracts/release-readiness`)
- present-tense hooks-as-rules → CI gates (`strategic-direction`)
- hook-runtime mentions → `ao curate constrain` / opt-in framing
(`curation-pipeline`, `leverage-points`, `SCHEMAS` legacy-manifest
label, `workflows/session-lifecycle`)

## Verification

- `scripts/check-doc-hooks-drift.sh` → PASS on this branch (FAILed on
all 8 before the reframes)
- `tests/scripts/check-doc-hooks-drift.bats` → 8/8 (positive /
negative×3 / hedge×2 / exclusion / no-docs error)
- `shellcheck` clean · `markdownlint` 0 errors (9 docs) ·
`validate-cli-skills-map.sh` PASS · `generate-ci-jobs-table.sh --check`
PASS · existing `check-hookless-cold-start.sh` still green
- Wired into `validate.yml` lint/contracts (gated on docs/ci/shell
changes) + auto-run via the bats suite

Closes-scenario: ag-rryf#doc-hooks-drift-gate
Bounded-context: BC2-Validation
Evidence: scripts/check-doc-hooks-drift.sh
This commit is contained in:
Bo
2026-06-03 22:38:26 -04:00
committed by GitHub
parent 72219bed2c
commit e74d8899fd
12 changed files with 205 additions and 13 deletions
+1 -1
View File
@@ -512,7 +512,7 @@ research + plan validated code learnings + next work
| Progress template | `.claude/templates/claude-progress.json` | Session state template |
| Feature template | `.claude/templates/feature-list.json` | Feature tracking template |
| Intent router | `.claude/skills/intent-router.md` | Natural language routing |
| Session autostart | `.claude/hooks/session-autostart.sh` | Auto-show context |
| Session autostart (opt-in) | `.claude/hooks/session-autostart.sh` | Auto-show context — AgentOps ships none; author one via the hooks-authoring skill |
| Session start cmd | `.claude/commands/session-start.md` | Manual session start |
| Session end cmd | `.claude/commands/session-end.md` | Manual session end |
| Progress update cmd | `.claude/commands/progress-update.md` | Manual progress update |