a9504a8a62
docs: cut root AGENTS siblings and densify retain contracts
...
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 >
2026-07-14 17:39:11 -04:00
5dfe1c9194
feat(docs): tiered AGENTS.md split — orientation + 4 siblings (soc-vuu6.3 #agents-md-tiered-split) ( #387 )
...
## Summary
Split the 580-line monolithic AGENTS.md into five tiered files so
cold-start sessions pay ≤250 lines for orientation, with operational
detail one hop away.
| File | Lines | Owner area |
|---|---:|---|
| `AGENTS.md` | 97 | Orientation + Quick Reference + sibling pointer
table + 1-release deprecation footer |
| `AGENTS-WORKFLOW.md` | 292 | Workflow phases · Branch/PR shape ·
Multi-agent discipline · Provenance · Doctrine altitudes · Local
Pre-Push · Releasing · Landing the Plane · bd Tracking · Session
Completion |
| `AGENTS-CI.md` | 127 | CI intro · Advisory Triage SLAs · DEFERRED
Hardening matrix · CI Jobs table (67 rows) · Nightly |
| `AGENTS-CODEX.md` | 52 | CLI Skill-Map Refresh + Codex Skill
Maintenance |
| `AGENTS-RUNTIME.md` | 59 | Canonical Root and Worktrees + Key
Constraints |
## Mechanical enforcement
- `scripts/validate-agents-split.sh` — 14 checks: AGENTS.md exists, ≤250
lines, each sibling exists, bidirectional links.
- CI gate `validate-agents-split` (required) — wired into `validate.yml`
`needs:` arrays + summary echo + `docs/contracts/ci-jobs.yaml` manifest.
- `scripts/generate-ci-jobs-table.sh` `AGENTS_PATH` default flipped from
`AGENTS.md` to `AGENTS-CI.md`; 67-row table regenerated.
- 7-case bats coverage at `tests/scripts/validate-agents-split.bats`.
## Fitness delta
Cold-start orientation budget: **580 → 97 lines (-83%)**. Total docs
across the split: 580 → 627 lines (+47 lines of sibling pointers and
deprecation footer — the overhead of the contract).
## Deferred to follow-up beads
- **Operating-loop ASCII spine** — `docs/architecture/operating-loop.md`
12-line flowchart prefix; orthogonal authoring task.
- **Universal init prompt wiring** — `ao session bootstrap` referenced
in AGENTS.md but blocked on soc-vuu6.25.
## Verification
```bash
bash scripts/validate-agents-split.sh
# validate-agents-split: scanned 14 checks
# PASS — AGENTS.md (97 lines) + 4 siblings, links bidirectional.
bats tests/scripts/validate-agents-split.bats
# 1..7 (all pass)
bash tests/docs/validate-doc-release.sh
# PASS: doc-release gate succeeded
bash scripts/validate-ci-policy-parity.sh
# CI_JOBS_TABLE: PASS (67 rows)
```
## Sibling patterns
CI gate shape follows `scripts/check-finding-registry.sh`. Manifest
entry follows the validate-* row shape. Bats fixtures match
`tests/scripts/validate-sovereignty-proof-citations.bats`.
Closes-scenario: soc-vuu6.3#agents-md-tiered-split
Bounded-context: BC1-Corpus
Evidence: AGENTS.md
Evidence: AGENTS-WORKFLOW.md
Evidence: AGENTS-CI.md
Evidence: AGENTS-CODEX.md
Evidence: AGENTS-RUNTIME.md
Evidence: scripts/validate-agents-split.sh
Evidence: tests/scripts/validate-agents-split.bats
Evidence: .github/workflows/validate.yml
Evidence: docs/contracts/ci-jobs.yaml
2026-05-21 01:05:02 +00:00
boshu