Repository navigation
Closed
Labels
Description
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
- 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.
- 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.
- Repos missing AGENTS.md entirely remain handled by the existing presence check with no regression; the linter runs only when the file exists.
- 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.
- The summary issue labels structural findings as informational and links to docs/initiatives/agents-md-validation.md.
Tasks / Subtasks
- Fetch each repo's AGENTS.md content in aw-standards-sync.sh (reuse the existing contents-API pattern) and run the linter on it when present (AC: Addressing PR comments #1, Add coding standards & principles section to AGENTS.md #3)
- Add the org-repo import-consistency check comparing downstream AGENTS.md against the canonical reference (AC: Add multi-agent isolation strategy using git worktrees #2)
- Append an informational structural-findings section to the summary issue with a link to the rule-set doc (AC: Addressing PR comments #1, Add stacked PR strategy and Epic-level workflow guidance #5)
- Add bats coverage with mocked gh/API for the linter integration and import check (AC: Add workflow, environment, and orchestration guidance #4)
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.shtests/agents_md_audit.bats (new)
Story prepared by the BMAD Scrum Master (Bob) for epic #642. Status: ready-for-dev.
Activity
don-petry commentedon Sep 1, 2026
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 inpetry-projects/.github-private(it is vendored here only as the git-ignored.dev-lead/mirror and cannot produce a tracked change in this repo). Inpetry-projects/.githubthe tracked, bats-covered org-wide compliance scan that already fetches each repo'sAGENTS.md(base64-decoded via the contents API) and emits a summary isscripts/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 intocompliance-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.shpure helpersagents_md_lint_scope_for_repo(.github→canonical, elsedownstream, so the canonical file is exempt from the org-import rule)record_agents_md_structural_findings— writes decoded content to a temp file, runsamdl_lint, appends findings to a separate structural accumulator (neverFINDINGS_FILE, so no issues / umbrella / non-zero exit)check_agents_mdto call the recorder only when AGENTS.md content is present (404 stays on the existingmissing-agents-mdpresence path — no regression); existing org-ref error finding unchangedappend_structural_findings_summary— appends an informational section to the summary labelled non-blocking with a link todocs/initiatives/agents-md-validation.mdmain()Tests to Write (
test/scripts/compliance-audit/agents-md-structural-lint.bats, no network)agents_md_lint_scope_for_reporeturns canonical for.github, downstream otherwiseorg-repo-import-consistencyfor a downstream file with no back-link, but NOT for the canonical.githubscopecheck_agents_md(with stubbedgh_api): 404 →missing-agents-mdin FINDINGS_FILE and zero structural findings; present-but-invalid → structural finding recorded but FINDINGS_FILE has no new blocking findingappend_structural_findings_summaryemits the informational label + thedocs/initiatives/agents-md-validation.mdlink; renders findings when present and a clean note when absentTest Command
bats --print-output-on-failure test/scripts/compliance-audit/don-petry commentedon Sep 1, 2026
Dev-Lead: Implementation Complete
Target note
The story names
aw-standards-sync.sh, which in this org lives inpetry-projects/.github-private(vendored here only as the git-ignored.dev-lead/mirror, so it cannot produce a tracked change inpetry-projects/.github). In this repo the tracked, bats-covered org-wide compliance scan that already fetches each repo'sAGENTS.md(base64-decoded via the contents API) and emits a summary isscripts/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 intocompliance-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
scripts/agents-md-lint.shpure helpers intocompliance-audit.shagents_md_lint_scope_for_repo(.github→canonical, elsedownstream— canonical file exempt from the org-import rule) (AC Add multi-agent isolation strategy using git worktrees #2)record_agents_md_structural_findings— runsamdl_lintover decoded content, appends to a separate accumulator, neverFINDINGS_FILE(no issues / umbrella / non-zero exit) (AC Addressing PR comments #1)check_agents_mdto lint only when AGENTS.md content is present; the 404 stays on the existingmissing-agents-mdpath, existing org-ref error unchanged (AC Add coding standards & principles section to AGENTS.md #3)append_structural_findings_summary— informational, non-blocking section linking todocs/initiatives/agents-md-validation.md, with pipe-escaping so rule-regex messages don't split the table (AC Addressing PR comments #1, Add stacked PR strategy and Epic-level workflow guidance #5)main()shellcheck --severity=warning -xclean (AC Add workflow, environment, and orchestration guidance #4)Test Results
Files Changed
scripts/compliance-audit.sh: source the structural linter; addagents_md_lint_scope_for_repo,record_agents_md_structural_findings, andappend_structural_findings_summary; extendcheck_agents_mdto run the linter when the file exists; init the accumulator and append the informational summary section inmain()(+108 lines)test/scripts/compliance-audit/agents-md-structural-lint.bats(new): 13 tests, no networkNotes
agents-md-structural.tsv), never inFINDINGS_FILE— they open no issues, never join the umbrella, and never change the exit code.missing-agents-mdpath before the linter is reached; the linter runs only on present content. The existing blockingagents-md-missing-org-reffinding is left intact (removing it would be a breaking change); the linter'sorg-repo-import-consistencyrule adds an additional informational import-consistency surface..github-privateaw-standards-sync.sh(summary-issue + PR model) belongs in that repo and cannot be delivered from apetry-projects/.githubPR. The linter and rule set it would consume already live here.feat: implement issue #645 — [Phase 3] Integrate the linter into the …