Repository navigation
Closed
Labels
Description
Story
As a org standards maintainer,
I want track structural-check false positives across audit cycles and provide a documented, human-gated promotion to a blocking check,
so that the check only becomes enforcing once proven low-false-positive, addressing the adversarial false-positive risk.
Acceptance Criteria
- The audit summary issue records, per cycle, the count of structural findings and any confirmed false positives, so two consecutive clean cycles are observable from the issue history.
- docs/initiatives/agents-md-validation.md documents the promotion gate: informational becomes blocking only after 2 consecutive audit cycles with zero confirmed false positives AND explicit maintainer sign-off (never automatic).
- The mechanism to flip to blocking is a discrete, reviewable change (switch the linter to failing mode / add the required status check) that is gated behind the documented criteria; this story delivers the mechanism and documentation, not the promotion decision.
- The story does not itself enable blocking; the actual flip remains a human decision recorded against the documented criteria.
- Per-cycle structural finding counts and each false-positive determination are recorded durably and tamper-evidently — an append-only, committed cycle log (e.g. under docs/initiatives/) rather than only an editable summary issue — and every false-positive confirmation names the maintainer who made it, so the 'two consecutive clean cycles' claim is independently auditable and its baseline record is immutable.
Tasks / Subtasks
- Extend the audit summary output to record per-cycle structural finding counts and confirmed false positives (AC: Addressing PR comments #1)
- Document the promotion gate and sign-off requirement in docs/initiatives/agents-md-validation.md (AC: Add multi-agent isolation strategy using git worktrees #2)
- Provide the discrete blocking-mode toggle (failing-mode flag / required-check wiring) but leave it disabled pending the gate (AC: Add coding standards & principles section to AGENTS.md #3, Add workflow, environment, and orchestration guidance #4)
- Add an append-only, committed per-cycle log capturing finding counts + false-positive determinations, each attributed to a named maintainer (AC: Addressing PR comments #1, Add stacked PR strategy and Epic-level workflow guidance #5)
Dev Notes
- The promotion decision is human-gated by design — the discussion mandates promoting to blocking only after 2 audit cycles of zero false positives; encode the criteria and the toggle, but never auto-enable.
- Reuse Story 3's informational summary section as the per-cycle record; add explicit finding/false-positive counts so 'two clean cycles' is auditable from issue history.
- The failing-mode flag added to the linter in Story 2 is the toggle point; flipping the local CI check (Story 4) to a required status check is the branch-protection side of promotion — document both, enable neither in this story.
- This mirrors the repo's convention that activation/enforcement is a deliberate human decision, consistent with the initiative-planner's inert-until-human-activates pattern.
- Guard the promotion gate against reward-hacking: the 'zero false positives over 2 cycles' inputs must not live only in an editable issue. Persist per-cycle counts and false-positive calls to an append-only committed log and attribute each false-positive confirmation to a named maintainer, so a clean-cycle claim cannot be fabricated by silently editing or suppressing findings.
Project Structure Notes
Doc edits to docs/initiatives/agents-md-validation.md and summary-output edits in scripts/aw-standards-sync.sh; the toggle stays disabled. No branch-protection change is applied here.
References
- docs/initiatives/idea-to-initiative-pipeline.md
- scripts/aw-standards-sync.sh
- .github/workflows/lint.yml
Likely target surface
docs/initiatives/agents-md-validation.md (new/edit)scripts/aw-standards-sync.sh
Story prepared by the BMAD Scrum Master (Bob) for epic #642. Status: ready-for-dev.
Activity
don-petry commentedon Sep 7, 2026
Dev-Lead Implementation Plan
Issue: #647 — [Phase 4] Promotion mechanism: informational to blocking after two clean audit cycles
Scope
Deliver the human-gated informational → blocking promotion mechanism and its documentation for the AGENTS.md structural check — per-cycle finding counts surfaced in the audit summary, an append-only committed cycle log attributing every false-positive determination to a named maintainer, and a discrete (disabled) blocking toggle gated behind the documented 2-clean-cycle + maintainer-sign-off criteria. The story enables nothing.
Implementation Checklist
docs/initiatives/agents-md-validation.md— expand §4 to fully document the promotion gate, the discrete toggle points (linter--mode failing+ required-status-check side), the append-only cycle-log procedure, maintainer sign-off, and that neither side is enabled here (AC Add multi-agent isolation strategy using git worktrees #2, Add coding standards & principles section to AGENTS.md #3, Add workflow, environment, and orchestration guidance #4)docs/initiatives/agents-md-validation-cycle-log.md(new) — append-only, committed per-cycle log; header states append-only/tamper-evident/attribution rules; table columns Cycle · Structural findings · Confirmed false positives · Details · Determined by (maintainer) · Clean? (AC Addressing PR comments #1, Add stacked PR strategy and Epic-level workflow guidance #5)scripts/agents-md-cycle-log.sh(new, pure) —validate(every recorded determination names a maintainer; counts are integers) andeligibility(are the last N cycles clean?) subcommands; reports only, never promotes (AC Add workflow, environment, and orchestration guidance #4, Add stacked PR strategy and Epic-level workflow guidance #5)scripts/compliance-audit.sh— extendappend_structural_findings_summaryto record the per-cycle structural finding count and link the append-only cycle log + promotion gate, so clean cycles are observable from issue history (AC Addressing PR comments #1)scripts/lib/agents-md-rules.json— add apromotion.cycle_logpointer to the committed log path (keeps the data file the single source of truth; additive, non-breaking).github/workflows/agents-md-rules-tests.yml— register the new cycle-log script/log/test paths and bats fileTests to Write
tests/agents_md_cycle_log.bats(new) — clean streak detected; a dirty cycle breaks the streak; missing maintainer failsvalidate;eligibilitynever signals auto-promotion and always states sign-off is still requiredtest/scripts/compliance-audit/agents-md-structural-lint.bats— assert the summary now emits the per-cycle structural finding count and links the cycle logTest Command
bats test/scripts/compliance-audit/ tests/agents_md_cycle_log.bats tests/test_agents_md_rules_config.bats tests/agents_md_lint.bats(plusbash .dev-lead/scripts/dev-lead-lint.sh)don-petry commentedon Sep 7, 2026
Dev-Lead: Implementation Complete
Plan Execution
docs/initiatives/agents-md-validation.md§4 (→ §4.1–4.3): the two-part promotion gate (2 consecutive clean cycles and explicit maintainer sign-off, never automatic), the append-only cycle-log chain of custody, the discrete toggle (delivered, armed nowhere), and a maintainer promotion checklist (AC Add multi-agent isolation strategy using git worktrees #2, Add coding standards & principles section to AGENTS.md #3, Add workflow, environment, and orchestration guidance #4)docs/initiatives/agents-md-validation-cycle-log.md— the append-only, committed per-cycle log; ships inert (no cycles recorded → not promotion-eligible), with append-only + named-maintainer attribution rules (AC Addressing PR comments #1, Add stacked PR strategy and Epic-level workflow guidance #5)scripts/agents-md-cycle-log.sh— pure, bats-testedvalidate(every determination names a maintainer; integer counts;Clean?consistent) andeligibility(reports the clean-cycle precondition; never promotes) (AC Add workflow, environment, and orchestration guidance #4, Add stacked PR strategy and Epic-level workflow guidance #5)scripts/compliance-audit.shappend_structural_findings_summaryto record the per-cycle structural finding count and link the append-only cycle log + promotion gate, so clean cycles are observable from issue history (AC Addressing PR comments #1)promotion.cycle_log+ disabledpromotion.toggle(enabled: false) toscripts/lib/agents-md-rules.json— the data file stays the single source of truth (AC Add coding standards & principles section to AGENTS.md #3, Add workflow, environment, and orchestration guidance #4).github/workflows/agents-md-rules-tests.ymlTest Results
Full run: 271 bats pass, 0 failures across
test/scripts/compliance-audit/,tests/test_agents_md_rules_config.bats,tests/agents_md_lint.bats,tests/agents_md_cycle_log.bats.bash .dev-lead/scripts/dev-lead-lint.shpasses (shellcheck clean); yamllint clean on the workflow.Files Changed
docs/initiatives/agents-md-validation.md: promotion gate fully documented (§4.1–4.3); status → Phase 4; references updateddocs/initiatives/agents-md-validation-cycle-log.md(new): append-only committed cycle log, inert on mergescripts/agents-md-cycle-log.sh(new): pure reader/validator for the cycle log; never promotesscripts/compliance-audit.sh: per-cycle structural finding count + cycle-log pointer in the audit summaryscripts/lib/agents-md-rules.json:promotion.cycle_log+ disabledpromotion.toggletest/scripts/compliance-audit/agents-md-structural-lint.bats: +5 tests (per-cycle count, cycle-log link, counter helper)tests/agents_md_cycle_log.bats(new): 12 contract tests for validate/eligibility.github/workflows/agents-md-rules-tests.yml: CI wiring for the new artifactsNotes
promotion.default_severitystaysinformational,promotion.toggle.enabledisfalse, and no branch-protection change is applied. The committed cycle log records zero cycles, soagents-md-cycle-log.sh eligibility … 2reportsclean-cycles-met=false. The flip remains a deliberate, human-gated decision recorded against the documented criteria.scripts/aw-standards-sync.sh, but Phase 3 wired the structural linter intoscripts/compliance-audit.sh(the live audit), so the per-cycle summary change landed there, consistent with the existing Phase 3 integration.feat: implement issue #647 — [Phase 4] Promotion mechanism: informati…