[Phase 1] Define the AGENTS.md structural rule set and spec-alignment reference

[don-petry]

Story

As a org standards maintainer,
I want define a documented, machine-readable structural rule set derived from the stable subset of the AAIF AGENTS.md spec,
so that the linter validates against a single, reviewable source of truth instead of hardcoded or contested assumptions.

Acceptance Criteria

1. A reference doc at docs/initiatives/agents-md-validation.md documents the initiative scope, the stable structural elements to be validated (single H1 title, heading-hierarchy validity, cross-reference integrity, org-repo import consistency), and the informational-to-blocking promotion criteria.
2. A machine-readable rule-set data file (e.g. a JSON under scripts/lib/) enumerates each structural check and tags every rule as either 'required' or 'recommended', so recommended items are reported but never fail the check.
3. The rule set explicitly scopes OUT semantic/content checks; only structural elements are covered, matching the discussion's adversarial rebuttal.
4. The doc restates the epic's measurable success metrics and the zero-token cost bound so downstream stories inherit them, and cross-links discussion 💡 AGENTS.md Specification Alignment & Automated Validation #534 and idea 💡 Cross-Repo Standards Drift Detection via Multi-Repo Analysis #341.

Tasks / Subtasks

• Draft docs/initiatives/agents-md-validation.md capturing scope, the stable structural elements, and the promotion gate (AC: Addressing PR comments #1, Add workflow, environment, and orchestration guidance #4)
• Capture the AAIF/agents.md spec snapshot used to derive the stable rule subset (record source + date in the doc) (AC: Addressing PR comments #1, Add coding standards & principles section to AGENTS.md #3)
• Create the machine-readable rule-set data file enumerating checks, each tagged required vs recommended (AC: Add multi-agent isolation strategy using git worktrees #2, Add coding standards & principles section to AGENTS.md #3)
• Document the informational-to-blocking promotion criteria (2 clean cycles + maintainer sign-off) (AC: Addressing PR comments #1)

Dev Notes

• Home: keep the rule set DATA-DRIVEN (a config file the linter reads) so the evolving spec can be updated without code changes — this is the key design constraint given the spec is young and moving.
• The framework this initiative extends is the compliance audit in scripts/aw-standards-sync.sh, which today only checks file PRESENCE (200 vs 404) against templates in petry-projects/.github, not structural validity.
• The canonical source-of-truth is petry-projects/.github/AGENTS.md; downstream repos extend it and link back — e.g. this repo's AGENTS.md lines 3-4 reference the canonical file. That link is the basis for the later org-repo import-consistency check.
• docs/initiatives/ already holds initiative writeups (e.g. idea-to-initiative-pipeline.md); follow that format and location.
• Do NOT enumerate a contested 'required sections' list as hard-required — the exact required-vs-recommended split is an open question (see open_questions); start with structurally-stable rules marked 'required' (single H1, valid hierarchy, resolvable cross-references) and leave section-presence items 'recommended' until confirmed.

Project Structure Notes

New doc under docs/initiatives/; new rule-set data file under scripts/lib/ (co-located with other shared config like scripts/lib/consumer-manifest.json). No code changes in this story.

References

• scripts/aw-standards-sync.sh
• docs/initiatives/idea-to-initiative-pipeline.md
• AGENTS.md
• scripts/lib/consumer-manifest.json

Likely target surface

• docs/initiatives/agents-md-validation.md (new)
• scripts/lib/agents-md-rules.json (new)

Story prepared by the BMAD Scrum Master (Bob) for epic #642. Status: ready-for-dev.