AGENTS.md Specification Alignment & Automated Structural Validation

[don-petry]

Summary

Add a deterministic structural validator for AGENTS.md to the org's existing compliance-audit framework (scripts/aw-standards-sync.sh), so the canonical petry-projects/.github AGENTS.md and its downstream copies stay structurally aligned with the evolving AAIF/agents.md spec, and cross-repo drift is caught before it silently degrades agent behavior across the 30+ tools that parse the file.

Source: discussion #534. Related umbrella idea: cross-repo standards drift detection (idea #341) — this initiative is a concrete instantiation.

Scope (structural, not semantic)

Per the discussion's adversarial rebuttal, the validator targets ONLY stable structural elements — section presence, heading hierarchy, cross-reference integrity, and org-repo import consistency — never semantic content. It starts informational (non-blocking) and is promoted to blocking only after two clean audit cycles plus explicit maintainer sign-off.

Approach (phased)

1. Phase 1 — Derive a documented, machine-readable structural rule set from the stable subset of the AAIF spec.
2. Phase 2 — Build the standalone shell linter (rule-set driven, bats-tested).
3. Phase 3 — Wire it into the Standards Sync compliance audit (informational) + local canonical-AGENTS.md CI self-check.
4. Phase 4 — Provide the human-gated informational→blocking promotion mechanism.

Success metrics (measurable)

• The structural check runs against the AGENTS.md of 100% of active, non-archived org repos each Standards Sync cycle, reported in the audit summary issue.
• The local CI self-check annotates/fails on 100% of structurally-invalid canonical AGENTS.md pull requests once live, verified by fixture-based negative tests (observable proxy for 'no invalid AGENTS.md reaches main undetected').
• Cross-repo import-consistency findings are surfaced for every downstream repo that fails to reference the canonical org-level AGENTS.md.
• Promotion to a blocking check is achieved only after 2 consecutive audit cycles with zero confirmed false positives.

Cost cap / budget bound

The linter is pure, deterministic shell — zero LLM/token cost. It runs inside the existing monthly Standards Sync workflow (30-minute timeout) and the existing per-PR lint.yml job; the initiative adds no new scheduled runs and no new paid infrastructure. Any per-repo linter invocation is bounded by the existing standards-sync run.

Untracked prerequisites

• A captured snapshot of the current AAIF/agents.md structural spec (the stable subset of section and heading-hierarchy rules) to derive the v1 rule set from — the upstream spec is external and evolving, and is not tracked as a GitHub issue. Captured as part of Phase 1.

---

Planned from idea discussion #534 by the BMAD Scrum Master initiative-planner. Inert until a maintainer adds initiative:auto.