Skip to content

[Phase 3] Integrate the linter into the compliance audit (informational) + org-repo import consistency #645

Closed

Description

@don-petry

Story

As a compliance-audit maintainer,
I want wire the structural linter into the Standards Sync compliance scan and add a cross-repo import-consistency check, both informational,
so that structural drift and broken canonical-import links are surfaced org-wide each audit cycle without blocking any repo.

Acceptance Criteria

  1. aw-standards-sync.sh runs scripts/agents-md-lint.sh against each scanned repo's AGENTS.md and records structural findings in the summary issue as a clearly-labelled informational (non-blocking) section — no PRs are opened and no CI is failed on structural findings in this phase.
  2. A cross-repo import-consistency check verifies each downstream repo's AGENTS.md correctly references/imports the canonical petry-projects/.github AGENTS.md, and reports mismatches informationally.
  3. Repos missing AGENTS.md entirely remain handled by the existing presence check with no regression; the linter runs only when the file exists.
  4. The new behavior is covered by bats tests with mocked gh/API calls (no network), consistent with the existing standards-sync test style, and shellcheck --severity=warning -x stays clean.
  5. The summary issue labels structural findings as informational and links to docs/initiatives/agents-md-validation.md.

Tasks / Subtasks

Dev Notes

  • aw-standards-sync.sh already enumerates active repos, fetches template content via the contents API (base64-decoded), loops REQUIRED_FILES checking 200/404, applies security settings, and accumulates summary_rows into a final issue — extend that flow; do NOT restructure it.
  • Keep structural findings strictly informational this phase: append to the summary issue only; do not add them to the missing_files/PR path and do not fail the workflow (the discussion mandates starting non-blocking).
  • Presence check must not regress: only run the linter for repos where the AGENTS.md contents fetch returns content; a 404 stays on the existing missing-file path.
  • The canonical import target is petry-projects/.github/AGENTS.md; a compliant downstream AGENTS.md references it (see this repo's AGENTS.md lines 3-4 as the reference shape). Report, do not auto-fix, in this phase.
  • Standards Sync runs monthly (first-Monday guard) with a 30-minute timeout in .github/workflows/standards-sync.yml — the added per-repo linting must stay within that budget; the linter is pure shell so cost is negligible.
  • Follow the existing standards-sync test approach (mock gh/API, no network) — mirror the style used by other scripts' bats suites in tests/.

Project Structure Notes

Edits to scripts/aw-standards-sync.sh; new tests under tests/ mirroring existing standards-sync-style suites. No workflow trigger changes to .github/workflows/standards-sync.yml.

References

  • scripts/aw-standards-sync.sh
  • .github/workflows/standards-sync.yml
  • AGENTS.md
  • scripts/run-bats.sh

Likely target surface

  • scripts/aw-standards-sync.sh
  • tests/agents_md_audit.bats (new)

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

Activity

  1. don-petry commented on Sep 1, 2026

    @don-petry
    ContributorAuthor

    Dev-Lead Implementation Plan

    Issue: #645 — [Phase 3] Integrate the linter into the compliance audit (informational) + org-repo import consistency

    Target reconciliation

    The story references aw-standards-sync.sh, which in this org lives in petry-projects/.github-private (it is vendored here only as the git-ignored .dev-lead/ mirror and cannot produce a tracked change in this repo). In petry-projects/.github the tracked, bats-covered org-wide compliance scan that already fetches each repo's AGENTS.md (base64-decoded via the contents API) and emits a summary is scripts/compliance-audit.sh (check_agents_md). Phase 2's linter (scripts/agents-md-lint.sh) and rule set (scripts/lib/agents-md-rules.json) also live here, so Phase 3 is wired into compliance-audit.sh — matching the issue title ("integrate the linter into the compliance audit") and keeping the change tracked and testable in this repo.

    Scope

    Run the structural linter over each scanned repo's AGENTS.md (only when it exists) and surface its findings — including the downstream org-import-consistency rule — as a clearly-labelled informational, non-blocking section of the audit summary that opens no issues and never fails the run.

    Implementation Checklist

    • scripts/compliance-audit.sh: source the (sourceable) scripts/agents-md-lint.sh pure helpers
    • Add pure agents_md_lint_scope_for_repo (.github → canonical, else downstream, so the canonical file is exempt from the org-import rule)
    • Add record_agents_md_structural_findings — writes decoded content to a temp file, runs amdl_lint, appends findings to a separate structural accumulator (never FINDINGS_FILE, so no issues / umbrella / non-zero exit)
    • Extend check_agents_md to call the recorder only when AGENTS.md content is present (404 stays on the existing missing-agents-md presence path — no regression); existing org-ref error finding unchanged
    • Add append_structural_findings_summary — appends an informational section to the summary labelled non-blocking with a link to docs/initiatives/agents-md-validation.md
    • Wire the accumulator init + summary append into main()

    Tests to Write (test/scripts/compliance-audit/agents-md-structural-lint.bats, no network)

    • agents_md_lint_scope_for_repo returns canonical for .github, downstream otherwise
    • recorder records nothing for a structurally-valid AGENTS.md; records the hierarchy finding for a skipped-heading file
    • recorder records org-repo-import-consistency for a downstream file with no back-link, but NOT for the canonical .github scope
    • recorder is a no-op on empty content (linter only runs when the file exists)
    • check_agents_md (with stubbed gh_api): 404 → missing-agents-md in FINDINGS_FILE and zero structural findings; present-but-invalid → structural finding recorded but FINDINGS_FILE has no new blocking finding
    • append_structural_findings_summary emits the informational label + the docs/initiatives/agents-md-validation.md link; renders findings when present and a clean note when absent

    Test Command

    bats --print-output-on-failure test/scripts/compliance-audit/

  2. don-petry commented on Sep 1, 2026

    @don-petry
    ContributorAuthor

    Dev-Lead: Implementation Complete

    Target note

    The story names aw-standards-sync.sh, which in this org lives in petry-projects/.github-private (vendored here only as the git-ignored .dev-lead/ mirror, so it cannot produce a tracked change in petry-projects/.github). In this repo the tracked, bats-covered org-wide compliance scan that already fetches each repo's AGENTS.md (base64-decoded via the contents API) and emits a summary is scripts/compliance-audit.sh (check_agents_md). Phase 2's linter (scripts/agents-md-lint.sh) and rule set (scripts/lib/agents-md-rules.json) also live here, so Phase 3 was wired into compliance-audit.sh — matching the issue title ("integrate the linter into the compliance audit") and keeping the change tracked, testable, and PR-able in this repo. This was flagged in the plan comment above.

    Plan Execution

    Test Results

    $ bats --print-output-on-failure test/scripts/compliance-audit/agents-md-structural-lint.bats
    1..13
    ok 1 scope for the .github repo is canonical
    ok 2 scope for any downstream repo is downstream
    ok 3 a structurally-valid downstream AGENTS.md records no structural findings
    ok 4 a skipped-heading AGENTS.md records the heading-hierarchy finding
    ok 5 a downstream AGENTS.md with no org back-link records org-repo-import-consistency
    ok 6 the canonical (.github) scope is exempt from org-repo-import-consistency
    ok 7 empty content records nothing (linter runs only when the file exists)
    ok 8 a missing AGENTS.md (404) files missing-agents-md and runs no linter
    ok 9 a present-but-invalid AGENTS.md records a structural finding without a blocking finding
    ok 10 the summary section is labelled informational and links to the rule-set doc
    ok 11 with no structural findings the summary states everything is valid
    ok 12 structural findings are rendered as a table row keyed by repo and rule
    ok 13 a literal pipe in a finding message is escaped so the table cell is not split
    
    $ bats test/scripts/compliance-audit/     # full suite
    202 ok · 0 failures
    
    $ shellcheck --severity=warning -x scripts/compliance-audit.sh   # CLEAN
    $ bash .dev-lead/scripts/dev-lead-lint.sh                        # all checks passed
    

    Files Changed

    • scripts/compliance-audit.sh: source the structural linter; add agents_md_lint_scope_for_repo, record_agents_md_structural_findings, and append_structural_findings_summary; extend check_agents_md to run the linter when the file exists; init the accumulator and append the informational summary section in main() (+108 lines)
    • test/scripts/compliance-audit/agents-md-structural-lint.bats (new): 13 tests, no network

    Notes

    • Strictly non-blocking: structural findings live in a dedicated accumulator (agents-md-structural.tsv), never in FINDINGS_FILE — they open no issues, never join the umbrella, and never change the exit code.
    • No presence-check regression: a 404 returns on the existing missing-agents-md path before the linter is reached; the linter runs only on present content. The existing blocking agents-md-missing-org-ref finding is left intact (removing it would be a breaking change); the linter's org-repo-import-consistency rule adds an additional informational import-consistency surface.
    • Follow-up (out of scope): the equivalent wiring for the .github-private aw-standards-sync.sh (summary-issue + PR model) belongs in that repo and cannot be delivered from a petry-projects/.github PR. The linter and rule set it would consume already live here.
  3. added a commit that references this issue on Sep 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions