Repository navigation
Closed
Labels
Description
Story
As a compliance-audit maintainer,
I want implement a deterministic shell linter that validates a single AGENTS.md file against the Phase 1 rule set,
so that any repo's AGENTS.md can be checked for structural drift with zero LLM cost and reproducible output.
Acceptance Criteria
- A new shell script (e.g. scripts/agents-md-lint.sh) accepts an AGENTS.md path and validates required section presence, valid Markdown heading hierarchy (exactly one H1, no skipped heading levels), and cross-reference integrity (relative links and referenced files such as CLAUDE.md / SKILL.md resolve).
- All checks are driven by the Phase 1 rule-set data file, not hardcoded, so rule changes need no code edits.
- The linter emits deterministic, severity-tagged, machine-readable findings and defaults to informational mode (exit 0 / never fails the caller); a mode flag can switch it to failing (exit nonzero) for later phases.
- Pure classification/parse helpers are sourceable and covered by bats tests with fixtures — a structurally-valid AGENTS.md plus one fixture per failure mode (missing required section, skipped heading level, dangling cross-reference); tests use no network.
- shellcheck --severity=warning -x passes for the new script, and the new bats test file is registered in the lint.yml bats job via scripts/run-bats.sh.
Tasks / Subtasks
- Implement scripts/agents-md-lint.sh with sourceable helpers that read the rule-set file and classify each structural check (AC: Addressing PR comments #1, Add multi-agent isolation strategy using git worktrees #2)
- Implement the informational/failing mode flag and machine-readable, severity-tagged output (AC: Add coding standards & principles section to AGENTS.md #3)
- Add tests/fixtures/agents-md/ fixtures: one valid file and one per failure mode (AC: Add workflow, environment, and orchestration guidance #4)
- Write a bats test exercising the pure helpers over the fixtures (no network) and register it in lint.yml's run-bats.sh list (AC: Add workflow, environment, and orchestration guidance #4, Add stacked PR strategy and Epic-level workflow guidance #5)
- Confirm shellcheck --severity=warning -x is clean (AC: Add stacked PR strategy and Epic-level workflow guidance #5)
Dev Notes
- Follow the repo's established pattern of sourceable pure classification helpers exercised by pure bats tests with synthetic fixtures — see tests/template_stub_drift.bats (setup sources the script; asserts over inputs; no network).
- The lint.yml shellcheck job runs
find scripts -name '*.sh' -exec shellcheck --severity=warning -x {} +, so the new script must be clean under that. - The bats job invokes scripts/run-bats.sh with an explicit file list; add the new test file there — run-bats.sh tolerates a not-yet-present file with a ::warning:: so the list can be added in the same PR.
- Keep the linter self-contained and file-path-in / findings-out: it must NOT enumerate repos or hit the network (that is the audit integration's job in Phase 3). This keeps it unit-testable and reusable by both the audit and the local CI self-check.
- Cross-reference integrity should resolve relative links/paths against the AGENTS.md's own directory; treat http(s) links and pure '#anchor' references as out of scope for existence checks (mirrors how the repo's own validators skip URLs/anchors).
Project Structure Notes
New scripts/agents-md-lint.sh alongside other scripts/*.sh; new tests/agents_md_lint.bats and tests/fixtures/agents-md/ alongside existing fixtures (tests/fixtures/). Registered in .github/workflows/lint.yml.
References
- tests/template_stub_drift.bats
- scripts/run-bats.sh
- .github/workflows/lint.yml
- scripts/initiative-planner/validate-plan.py
Likely target surface
scripts/agents-md-lint.sh (new)tests/agents_md_lint.bats (new).github/workflows/lint.yml
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: #644 — [Phase 2] Build the standalone AGENTS.md structural linter
Scope
Implement a deterministic, self-contained shell linter (
scripts/agents-md-lint.sh) that validates a single AGENTS.md file against the Phase 1 rule set (scripts/lib/agents-md-rules.json), with sourceable pure helpers, machine-readable severity-tagged findings, and an informational (default, exit 0) vs. failing (exit nonzero) mode flag.Repo-reality notes
The issue's Dev Notes reference
tests/template_stub_drift.bats,scripts/run-bats.sh, and.github/workflows/lint.yml, which do not exist in this repo. The faithful equivalents here are:--severity=warning -xis already enforced onscripts/**/*.shby theci.ymlShellCheck job (auto-covers the new script).*-tests.ymlworkflow (e.g.agents-md-rules-tests.yml); the new bats file is registered by adding a siblingagents-md-lint-tests.yml.Implementation Checklist
scripts/agents-md-lint.sh— sourceable pure helpers (heading extraction, single-H1, heading-hierarchy, fenced-closure, link classification, slugify, cross-reference resolution, section-presence, canonical detection) + guardedmainthat reads the rule-set JSON and dispatches checks by rule id/element/leveltests/fixtures/agents-md/—valid/(+ a resolvable sibling file) and one fixture per failure mode:missing-section/,skipped-heading/,dangling-xref/.github/workflows/agents-md-lint-tests.yml— installs bats+jq and runs the new bats file (registers it in CI).markdownlint-cli2.yaml— ignoretests/fixtures/**so intentionally-malformed fixtures don't fail the Lint jobTests to Write
tests/agents_md_lint.bats— sources the script (guarded main) and exercises each pure helper over the fixtures (no network), plusmainin informational mode (exit 0) and failing mode (exit nonzero on a required-rule failure, exit 0 on valid)Test Command
bats tests/agents_md_lint.bats(plusshellcheck --severity=warning -x scripts/agents-md-lint.shandbash .dev-lead/scripts/dev-lead-lint.sh)don-petry commentedon Sep 1, 2026
Dev-Lead: issue #644 implementation failed — will retry
The engine failed (
engine-error— e.g. a timeout or transient engine error). This was attempt 1 of 3; dev-lead will retry automatically. You can also re-apply thedev-leadlabel to retry now.engine-errorLast 40 lines of engine output (redacted)
don-petry commentedon Sep 1, 2026
Dev-Lead Implementation Plan
Issue: #644 — [Phase 2] Build the standalone AGENTS.md structural linter
Scope
Build a deterministic, zero-LLM-cost shell linter (
scripts/agents-md-lint.sh) that validates a single AGENTS.md against the Phase 1 rule set (scripts/lib/agents-md-rules.json) — driven by that data file, with sourceable pure helpers, machine-readable severity-tagged findings, and an informational (exit 0) / failing (exit nonzero) mode flag.Repo-convention note
The issue references
lint.yml+scripts/run-bats.sh; those are org-template names. This repo actually runs shellcheck overscripts/**/*.shinci.yml's ShellCheck job (auto-covers the new script) and gates bats via per-feature*-tests.ymlworkflows. AGENTS.md structural validation already has.github/workflows/agents-md-rules-tests.yml, so the new bats file will be registered there (its natural, cohesive home) rather than inventinglint.yml.Implementation Checklist
scripts/agents-md-lint.sh(new) — sourceable pure helpers (slugify, heading extraction ignoring code fences, single-H1, heading-hierarchy, cross-reference integrity, fenced-code closure, section-presence, org-import, rule-level lookup) +BASH_SOURCE-guardedmainagents-md-rules.json, dispatch by rule id, tag each finding with the rule'slevel(severity) and honorapplies_to--mode informational(default, always exit 0) /--mode failing(exit nonzero only onrequired-level findings); machine-readable TSV findingstests/fixtures/agents-md/— valid file + one fixture per failure mode (missing required section, skipped heading level, dangling cross-reference)tests/agents_md_lint.bats(new) — source the helpers, assert over fixtures, no network.github/workflows/agents-md-rules-tests.yml— register the new bats file + add trigger paths for the script/test/fixturesTests to Write
Test Command
bats tests/agents_md_lint.bats(full:bats tests/), plusbash .dev-lead/scripts/dev-lead-lint.sh(shellcheck)don-petry commentedon Sep 1, 2026
Dev-Lead: Implementation Complete
Phase 2 standalone AGENTS.md structural linter is implemented, rule-set-driven, bats-tested, and CI-registered.
Plan Execution
scripts/agents-md-lint.sh— sourceable pure helpers (amdl_slugify,amdl_extract_headings[ignores code fences],amdl_check_single_h1,amdl_check_heading_hierarchy,amdl_check_fenced_code_closure,amdl_check_cross_references,amdl_check_section_present,amdl_check_org_import,amdl_rule_level) +BASH_SOURCE-guarded CLI (amdl_main)amdl_lintreads each rule's id/level/element/applies_to fromscripts/lib/agents-md-rules.jsonviajqand dispatches by id; findings are tagged with the rule's ownlevel— re-tagging required↔recommended needs no code edit (AC Addressing PR comments #1, Add multi-agent isolation strategy using git worktrees #2)--mode informational(default, always exit 0) /--mode failing(exit 1 only on arequiredfinding;recommendednever fails); machine-readable deterministic TSVseverity<TAB>rule_id<TAB>line<TAB>message(AC Add coding standards & principles section to AGENTS.md #3)tests/fixtures/agents-md/—valid.md(+CLAUDE.mdxref target) plus one fixture per failure mode:missing-section.md,skipped-heading.md,dangling-xref.md(AC Add workflow, environment, and orchestration guidance #4)tests/agents_md_lint.bats— 24 tests sourcing the helpers + driving the CLI over the fixtures, no network (AC Add workflow, environment, and orchestration guidance #4)shellcheck --severity=warning -xis clean (AC Add stacked PR strategy and Epic-level workflow guidance #5)Deviation from the issue's file names (documented in the plan)
The issue references
lint.yml+scripts/run-bats.sh; those are org-template names and do not exist in this repo's CI. This repo runs shellcheck overscripts/**/*.shinci.yml's ShellCheck job (auto-covers the new script) and gates bats via per-feature*-tests.ymlworkflows. I therefore registeredtests/agents_md_lint.batsin the existing.github/workflows/agents-md-rules-tests.yml— the cohesive home for AGENTS.md structural validation — and added trigger paths for the new script, test, and fixtures. Also excluded the deliberately-malformed fixtures from**/*.mdmarkdownlint via.markdownlint-cli2.yamlignoresso the CI Lint job stays green.Test Results
Sample deterministic output (
--mode informational, exit 0):Files Changed
scripts/agents-md-lint.sh(new): the standalone, zero-token structural linter — sourceable pure helpers + rule-set-driven CLI.tests/agents_md_lint.bats(new): 24 pure/CLI tests over synthetic fixtures, no network.tests/fixtures/agents-md/{valid,missing-section,skipped-heading,dangling-xref,CLAUDE}.md(new): one valid file + one per failure mode + an xref target..github/workflows/agents-md-rules-tests.yml: run the new bats file and add trigger paths for the script/test/fixtures..markdownlint-cli2.yaml: ignoretests/fixtures/agents-md/**(fixtures are intentionally malformed).Notes
http(s)/scheme URLs and out-of-file#anchortargets are skipped for existence checks.applies_tois honored:org-repo-import-consistency(downstream) is skipped under the default--scope canonicaland applied with--scope downstream.feat: implement issue #644 — [Phase 2] Build the standalone AGENTS.md…