Bo
e74d8899fd
## 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
Workflow Guide
Which workflow should I use? Find the right one in seconds.
Golden Paths
Use these as the default user journeys before reaching for the full decision tree.
| Situation | Start with | Continue with |
|---|---|---|
| First repo setup | ao quick-start |
/quickstart, then /rpi "a small goal" |
| Small, obvious change | Quick Fix | /implement, then /vibe --quick recent |
| New feature or broad change | Complete Cycle | /rpi "goal" or /plan -> /crank <epic-id> |
| Existing tracked backlog | ao reconcile --json, then bd 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 |
Decision Tree
| I want to... | Use this workflow | Complexity | Key Skills |
|---|---|---|---|
| Fix a simple bug or make a quick change | Quick Fix | Low | /implement |
| Investigate and fix a hard bug | Debug Cycle | Medium | /bug-hunt, /implement, /retro |
| Build a new feature end-to-end | Complete Cycle | High | /research, /plan, /crank, /vibe |
| Deploy infrastructure changes | Infrastructure Deployment | High | /plan, /implement, /vibe |
| Work across multiple domains at once | Multi-Domain | High | /plan, /swarm |
| Validate research assumptions before planning | Assumption Validation | Medium | /research |
| Understand a new codebase or extract patterns | Knowledge Synthesis | Medium | /research, /knowledge-activation |
| Run a retrospective after completing work | Post-Work Retro | Low | /retro, /post-mortem |
| Improve system quality over time | Continuous Improvement | Medium | /retro, /vibe |
| Manage a session from start to finish | Session Lifecycle | Low | (natural language) |
| Coordinate N autonomous workers without a leader | Meta-Observer Pattern | High | /swarm |
Workflows
Quick Fix
When to use: Simple, low-risk changes to 1-2 files with an obvious solution. Complexity: Low (10-30 min, single session) Key skills: /implement
Debug Cycle
When to use: Production incidents, intermittent failures, performance issues, or integration bugs with unknown root cause. Complexity: Medium-High (1-3 hours, 1-3 sessions) Key skills: /bug-hunt, /implement, /retro
Complete Cycle
When to use: New features, complex multi-file changes, or architectural work that needs full Research-Plan-Implement-Validate-Learn phases. Complexity: High (2-4 hours, 2-4 sessions) Key skills: /research, /plan, /crank, /vibe, /retro
Infrastructure Deployment
When to use: Infrastructure deployments that need validation gates, reality checks, and tracer bullets at every phase. Complexity: High (multi-session) Key skills: /plan, /implement, /vibe
Multi-Domain
When to use: Work spanning multiple domains simultaneously (backend + frontend + infra, technical + personal tracking). Complexity: High (multi-session) Key skills: /plan, /swarm
Assumption Validation
When to use: Before planning, to verify that research findings match reality (APIs exist, images available, operators behave as expected). Complexity: Medium Key skills: /research
Knowledge Synthesis
When to use: Onboarding to a new codebase, creating comprehensive docs, extracting patterns from multiple implementations. Complexity: Medium (30-60 min, single session) Key skills: /research, /knowledge-activation
Post-Work Retro
When to use: After completing significant work, to capture learnings and identify improvements. Complexity: Low Key skills: /retro, /post-mortem
Continuous Improvement
When to use: Periodic reviews (weekly/monthly), after milestones, technical debt reduction, or pattern refinement. Complexity: Medium (ongoing, periodic) Key skills: /retro, /vibe
Session Lifecycle
When to use: Managing any working session from start to finish -- starting work, resuming context, wrapping up. Complexity: Low (use natural language) Key skills: Just talk naturally; commands are optional.
Meta-Observer Pattern
When to use: Coordinating N autonomous workers through shared memory (stigmergy) without central orchestration. Complexity: High (advanced, multi-session) Key skills: /swarm Deep dive: meta-observer/ (pattern guide, examples, showcase)
Flowchart
Start here
|
v
Is it a simple, obvious fix? ----YES----> Quick Fix
|
NO
|
v
Is something broken? ----YES----> Debug Cycle
|
NO
|
v
Am I deploying infrastructure? ----YES----> Infrastructure Deployment
|
NO
|
v
Does it span multiple domains? ----YES----> Multi-Domain
|
NO
|
v
Am I building something new? ----YES----> Complete Cycle
|
NO
|
v
Am I trying to understand code/patterns? ----YES----> Knowledge Synthesis
|
NO
|
v
Am I wrapping up or improving? ----YES----> Post-Work Retro / Continuous Improvement