Migrate SYSTEM and AGENTS-{WORKFLOW,CI,CODEX,RUNTIME} into docs owners,
retarget consumers, rewrite the split gate, and craft-densify AGENTS,
README, PRODUCT, and GOALS under the documentation authority graph.
Co-authored-by: Cursor <cursoragent@cursor.com>
Audit of root files found five drift classes, each verified against the
executable source before fixing:
- AGENTS.md claimed Codex twins are never regenerated; regen-all.sh /
codex-sync.sh auto-refresh parity twins (bespoke/pointer stay manual,
per AGENTS-CODEX.md). Fixed both the registries line and the project
structure map.
- AGENTS-WORKFLOW.md referenced the missing docs/QUICKSTART.md and carried
a near-verbatim duplicate Session Completion checklist; deduped to the
canonical Landing the Plane section.
- AGENTS-RUNTIME.md listed sync-skill-counts.sh targets that the script
does not touch (README.md, docs/SKILLS.md, docs/ARCHITECTURE.md,
using-agentops/SKILL.md); replaced with the script's real surface.
- PROGRAM.md: hooks/** (directory no longer exists) removed from mutable
scope; ao autodev commands annotated + fixed with -tags legacy (the
command surface is archived behind the legacy build tag — verified
'autodev validate' returns valid:true with the tag); BEADS_DIR=$PWD/_beads
corrected to $(ao beads dir); 'tracked in bd' -> br.
- MEMORY.md: removed empty Last Session header; updated the bd-era Tracker
Skew entry to the br reality; marked the ao codex ensure-start/stop
pattern superseded (deprecated shims per AGENTS-RUNTIME.md).
The agent-ergonomics pass landed conventions (capabilities/robot-docs
introspection, --json everywhere, error-teaches, flag-typo hints) but
nothing in the repo's guiding contracts pointed future autodev/evolve
cycles at them. Add GOALS.md Directive 13 codifying the contract, and a
PROGRAM.md decision-policy line so a slice that touches an `ao` CLI
surface is held to it.
Mirrors the directive shape of GOALS.md #12 (convention directive with a
Steer line). Introspection surfaces: 0 → 2 documented as standard.
Reframe the autodev contract around the operating loop: BDD-shaped
intent, vertical slices mapped to one Given/When/Then, first-failing-test
discipline, the 7-row conflict-free wave check, bounded-context and
domain-purity rules, and ratchet-gated capture. Adds a domain/ports/
adapters go test to the validation bundle.
The --scope head default (5dbe1e6d) uses `git show --name-only`
instead of `git diff --name-only`. The test mock only handled
diff, causing a false-negative on go build failure detection.
Wire the Wave 2 generator into the INGEST stage's parallel finding-generator
fanout. The existing runFindingGenerator wrapper already enforces the
2-minute per-source budget (RFC §253) via context.WithTimeout; no new
machinery needed.
Changes:
- cli/internal/overnight/ingest.go: append the external-watchlist generator
to findingGenerators(). Reuses defaultFindingGeneratorTimeout (2 min) and
the existing goroutine-per-generator fanout.
- PROGRAM.md: add .agents/dream/external-watchlist.yaml to Mutable Scope
when Dream is the active command, making the operator-managed source's
ownership explicit alongside the broader .agents/** rule.
- cli/internal/overnight/stages_test.go: update GeneratorSidecarCount
assertion in TestRunIngest_FindingGeneratorEmitsRealSidecarCandidates
from 1 to 2 (mine-findings + external-watchlist soft-success when no
watchlist.yaml exists).
Verification:
- cd cli && go test ./internal/overnight/... ./internal/rpi/... -> all PASS
- bash scripts/check-contract-compatibility.sh -> 0 failures
boshu