feat(docs): tiered AGENTS.md split — orientation + 4 siblings (soc-vuu6.3 #agents-md-tiered-split)#387
Merged
Merged
Conversation
…-vuu6.3 #agents-md-tiered-split) 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: - AGENTS.md (97 lines): orientation, source-of-truth precedence, install instructions, quick reference, pointer table to the siblings, deprecation footer mapping old anchors to new homes. - AGENTS-WORKFLOW.md (292 lines): how work flows — Workflow phases, Branch + PR shape, Multi-agent discipline, Provenance, Doctrine altitudes, Source layer, CI tiers, Local Pre-Push Checklist, Releasing, Landing the Plane, bd Issue Tracking, Session Completion. - AGENTS-CI.md (127 lines): what CI checks — intro, Advisory Job Triage SLAs, DEFERRED Hardening matrix, generated CI Jobs and What They Check table (67 rows), Nightly Workflow Jobs. - AGENTS-CODEX.md (52 lines): CLI Skill-Map Refresh + Codex Skill Maintenance. - AGENTS-RUNTIME.md (59 lines): Canonical Root and Worktrees + Key Constraints Agents Must Follow. Plus mechanical enforcement: new scripts/validate-agents-split.sh + CI gate validate-agents-split (14 checks: AGENTS.md exists, <=250 lines, each sibling exists, bidirectional links). Wired into validate.yml needs arrays and the summary echo; registered in docs/contracts/ci-jobs.yaml. Also: scripts/generate-ci-jobs-table.sh AGENTS_PATH default flipped from AGENTS.md to AGENTS-CI.md (the table now lives there); 67-row table regenerated. Deferred to follow-up beads: - Operating-loop ASCII spine (docs/architecture/operating-loop.md 12-line flowchart prefix) — separate authoring exercise orthogonal to the split. - "Spawning an agent? Run ao session bootstrap" wiring to a real command — currently a soft reference to soc-vuu6.25. Fitness delta: cold-start orientation budget 580 → 97 lines (-83%). Total docs in split: 580 → 627 lines (+47 lines for sibling pointers and deprecation footer — the overhead cost of the split contract). Sibling pattern: CI gate shape follows scripts/check-finding-registry.sh. Manifest entry follows established validate-* row shape in ci-jobs.yaml. Test coverage note: bats coverage for validate-agents-split.sh added in a follow-up commit on this branch to keep this primary refactor reviewable. Closes-scenario: soc-vuu6.3#agents-md-tiered-split Bounded-context: BC1-Corpus Evidence: scripts/validate-agents-split.sh Evidence: AGENTS.md Evidence: AGENTS-WORKFLOW.md Evidence: AGENTS-CI.md Evidence: AGENTS-CODEX.md Evidence: AGENTS-RUNTIME.md Evidence: .github/workflows/validate.yml Evidence: docs/contracts/ci-jobs.yaml
…ats-coverage) 7 cases: pass-baseline, missing-AGENTS.md, over-250-lines, missing-sibling, missing-forward-link, missing-back-link, exactly-250-lines-edge. Sibling pattern: matches tests/scripts/validate-sovereignty-proof-citations.bats shape — throwaway repo + synthesized fixtures + one branch per case. Pairs with the primary refactor commit on this branch per docs/contracts/update-principles.md Principle 2.
boshu2
added a commit
that referenced
this pull request
May 22, 2026
…tors (soc-2gd6 #eval-hard-fails) (#402) ## Why The v2.42.0 release gate (`scripts/ci-local-release.sh`) was red on 8 evals. The 3 score-0/near-0 hard fails are all **eval-staleness behind legitimate recent refactors** — verified, not gaming or security weakening. Operator decision: update eval to match source of truth (executable > contract). | Eval | Was | Cause | Fix | |---|---|---|---| | `hook-manifest-command-counts` | 0 | `session-pr-counter.sh` (PR #362) is the legit 37th hook script; eval hardcoded 43/36 | bump expected counts 43→44, 36→37 | | `push-worktree landing-plane` | 0.14 | #387 tiered-AGENTS split moved "Landing the Plane" to `AGENTS-WORKFLOW.md` (+ dropped 2 lines) | redirect eval target `AGENTS.md`→`AGENTS-WORKFLOW.md` + restore the 2 dropped policy lines | | `security-toolchain ci-soft-gate-policy` | 0 | gate is intentionally **HARD** (no `continue-on-error`); job already runs `security-gate.sh --mode quick` + uploads artifacts | drop the stale `continue-on-error` requirement (security stays HARD) | **Security note:** `security-toolchain-gate` stays a HARD blocking gate. Only the stale "soft gate" assertion was removed from the eval; the actual scan + artifact upload + summary-blocking are unchanged. ## How tested - hook-manifest jq → `hook-manifest-counts-ok` - security smoke `ci-policy` → `security-toolchain-ci-policy-ok` - all 7 landing-plane strings present in `AGENTS-WORKFLOW.md` - shellcheck clean on edited smoke ## Scope honesty This fixes the 3 **hard** fails only. The release gate still has **5 minor evals (0.71–0.99)** + the **vil/release-smoke** lane — a separate remediation, deliberately NOT in this PR (no green-washing). Sibling pattern: same "update eval to match legitimately-changed source of truth" move as the cli-command-surface canary bumps in #396/#397. Fitness: release-gate eval hard-fails 3 → 0. Closes-scenario: soc-2gd6#eval-hard-fails Bounded-context: BC4-Validation Evidence: evals/agentops-core/fixtures/security-toolchain-governance-smoke.sh
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
AGENTS.mdAGENTS-WORKFLOW.mdAGENTS-CI.mdAGENTS-CODEX.mdAGENTS-RUNTIME.mdMechanical enforcement
scripts/validate-agents-split.sh— 14 checks: AGENTS.md exists, ≤250 lines, each sibling exists, bidirectional links.validate-agents-split(required) — wired intovalidate.ymlneeds:arrays + summary echo +docs/contracts/ci-jobs.yamlmanifest.scripts/generate-ci-jobs-table.shAGENTS_PATHdefault flipped fromAGENTS.mdtoAGENTS-CI.md; 67-row table regenerated.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
docs/architecture/operating-loop.md12-line flowchart prefix; orthogonal authoring task.ao session bootstrapreferenced in AGENTS.md but blocked on soc-vuu6.25.Verification
Sibling patterns
CI gate shape follows
scripts/check-finding-registry.sh. Manifest entry follows the validate-* row shape. Bats fixtures matchtests/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