docs: add governance compliance and pre-commit validation guidance by ashleyshaw · Pull Request #1509 · lightspeedwp/.github

ashleyshaw · 2026-08-04T17:48:42Z

Linked issues

Relates to #1489

Summary

Documents the AI governance compliance system and pre-commit validation requirements in AGENTS.md and CONTRIBUTING.md. Explains how governance hooks work, integration steps, and cost benefits.

Changes

AGENTS.md (+131 lines): New "AI Governance Compliance" section
- Pre-commit validation details
- Merge-time governance validation
- ESLint shell script exclusion
- Governance violation recovery procedures
- Cost-benefit analysis
CONTRIBUTING.md (+25 lines): Pre-commit validation guidance for Claude Code users
- What gets validated
- How it works
- Manual execution
- Cost benefit

Documentation Sections

AGENTS.md Updates

Pre-Commit Validation hook details
Integration via Claude Code UserPromptSubmit
Merge-time governance validation
ESLint configuration rationale
Governance violation recovery
Cost-benefit analysis (60-70% token reduction)

CONTRIBUTING.md Updates

Pre-commit validation section in Branching & Development
Link to full governance docs in AGENTS.md

Pre-commit hook: commit 5600ad1 (in PR chore: add pre-commit validation hook for PR template compliance #1508)
ESLint config fix: commit e028d13 (already merged via PR chore: exclude shell scripts from ESLint linting #1495)
Regex fix: commit 555b80e (already merged via PR fix: correct regex syntax in governance hook for linked-issues detection #1494)

Changelog

Changed

AGENTS.md: Add comprehensive AI Governance Compliance section explaining pre-commit and merge-time validation (Relates to fix: PR #1488 governance validation hook has regex bug + process workflow gaps #1489)
CONTRIBUTING.md: Add pre-commit validation guidance for Claude Code users (Relates to fix: PR #1488 governance validation hook has regex bug + process workflow gaps #1489)

Checklist (Global DoD / PR)

All AC met and demonstrated
Code quality verified (documentation)
Linked issues: Relates to fix: PR #1488 governance validation hook has regex bug + process workflow gaps #1489
Documentation accurate and complete
Links to related code and processes

Shell scripts in the hooks/ directory are not JavaScript and should not be linted by ESLint. Add hooks/** to the ignore patterns so ESLint doesn't attempt to process them. This prevents linting failures on portable shell scripts like hooks/pr-checklist-validator.sh and hooks/pr-merge-governance-validator.sh Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Document pre-commit and merge-time governance safeguards: - Pre-commit validation hook (hooks/pr-checklist-validator.sh) - Merge-time validation (hooks/pr-merge-governance-validator.sh) - ESLint configuration for shell scripts - Governance violation recovery procedures - Cost-benefit analysis of pre-commit validation Relates to #1489 (governance validation improvements) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Document the pre-commit validation hook for Claude Code users: - Explains what gets validated (branch naming, template sections) - How to run the hook manually - Cost-benefit of pre-commit validation - Link to full governance docs in AGENTS.md Relates to #1489 (governance validation improvements) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

coderabbitai · 2026-08-04T17:48:56Z

Warning

Review limit reached

@ashleyshaw, you've reached your PR review limit, so we couldn't start this review.

Next review available in:39 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 1573cdce-dcda-4aa1-8c09-480d8bd14f55

📥 Commits

Reviewing files that changed from the base of the PR and between d3447e5 and 30b60f1.

📒 Files selected for processing (14)

AGENTS.md
CONTRIBUTING.md
docs/AGENT_CREATION.md
docs/AGENT_STANDARDS.md
docs/AI_REFERENCES_STANDARDS.md
docs/COOKBOOKS_STANDARDS.md
docs/HOOKS_STANDARDS.md
docs/HUSKY_PRECOMMITS.md
docs/INSTRUCTIONS_STANDARDS.md
docs/PLUGINS_STANDARDS.md
docs/PROMPTS_STANDARDS.md
docs/SKILLS_STANDARDS.md
docs/WORKFLOWS_STANDARDS.md
eslint.config.cjs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-08-04T17:49:14Z

📄 README Validation

✅ All README checks passed.

Check	Result
✅ Frontmatter	Passed
✅ Structure	Passed

github-actions · 2026-08-04T17:49:19Z

⏱️ Aging and SLA annotation

Age: 0 day(s)
SLA state: Within SLA
Thresholds: warn at 7 days, breach at 14 days
Last updated: 2026-08-04T17:49:18.514Z

Maintained by project-meta-sync workflow.

github-actions · 2026-08-04T17:49:24Z

🎨 Mermaid Diagram Validation

❌ One or more Mermaid diagram checks failed.

Check	Result
✅ Syntax	Passed
❌ Accessibility	Failed
✅ Colour Contrast	Passed

mergify · 2026-08-04T17:51:06Z

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

Queue this pull request

github-actions · 2026-08-04T17:51:53Z

🔍 Reviewer Summary for PR #1509

CI Status: ✅ success
Files changed: 3
Risk Distribution: 0 critical, 0 high, 0 medium, 3 low

Recommendations

Ready to proceed pending human review

Copilot

Pull request overview

This PR updates repository documentation to explain the AI governance compliance system (pre-commit-style validation and merge-time checks) and how contributors can run or integrate the validation hooks.

Changes:

Add an “AI Governance Compliance” section to AGENTS.md describing pre-push validation, merge-time governance, recovery steps, and cost/benefit.
Add CONTRIBUTING.md guidance for Claude Code users on running/configuring the checklist validator.
Update eslint.config.cjs to ignore hooks/** (note: this is a non-doc change and appears inconsistent with the PR’s stated “docs-only” scope).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
AGENTS.md	Adds governance compliance documentation covering pre-push validation and merge-time checks.
CONTRIBUTING.md	Adds contributor-facing instructions for configuring/running the checklist validator.
eslint.config.cjs	Adds `hooks/**` to ESLint ignore patterns (non-documentation change).

Suppressed comments (1)

CONTRIBUTING.md:95

These bullets still read as if the hook runs by default. Tweaking the wording to “once configured” makes the behaviour clearer and aligns with the note that .claude/settings.json is local.

 - Runs automatically via Claude Code's UserPromptSubmit hook
- Integration via `.claude/settings.json` (local, not committed)
- Provides real-time feedback before push

ashleyshaw · 2026-08-04T21:45:31Z

+
+### Pre-Commit Validation (Before Push)
+
+The `hooks/pr-checklist-validator.sh` hook validates every commit attempt via Claude Code's UserPromptSubmit hook.


Updated AGENTS.md line 278 to clarify the validator is optional and must be manually configured via .claude/settings.json, not automatic.
🤖 Addressed by Claude Code

ashleyshaw · 2026-08-04T21:45:33Z


+**Pre-Commit Validation (Claude Code Users):**
+
+If you're using Claude Code, the pre-commit validation hook will automatically check your branch name and PR template compliance:


Updated CONTRIBUTING.md lines 84 and 93 to clarify the hook is optional and only runs if manually configured via .claude/settings.json.
🤖 Addressed by Claude Code

ashleyshaw · 2026-08-04T21:45:34Z

 "website/dist/**", // Migrated from .eslintignore
 "website/node_modules/**", // Migrated from .eslintignore
 "projects/active/**", // Project documentation and deliverables (excluded from linting)
+ "hooks/**", // Shell scripts and portable hooks (not JavaScript)


Removed the duplicate eslint.config.cjs change since it was already merged in PR #1495. This PR now contains only documentation updates as intended.
🤖 Addressed by Claude Code

Address Copilot review feedback: - AGENTS.md line 278: Clarify UserPromptSubmit hook is optional, not automatic - CONTRIBUTING.md lines 84 & 93: Emphasize hook requires manual configuration - Remove duplicate eslint.config.cjs change (already merged in PR #1495) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Use proper YAML frontmatter for flowchart config and indent accessibility attributes. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

GitHub's renderer requires inline accTitle/accDescr, not YAML frontmatter. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Add missing accTitle and accDescr to Mermaid diagram in docs/WORKFLOWS_STANDARDS.md. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Add accTitle and accDescr attributes to all Mermaid diagrams across documentation standards files to improve accessibility and compliance with diagram labeling best practices. Fixed diagrams: - AGENT_STANDARDS.md: 2 diagrams - AI_REFERENCES_STANDARDS.md: 2 diagrams - COOKBOOKS_STANDARDS.md: 2 diagrams - INSTRUCTIONS_STANDARDS.md: 2 diagrams - PLUGINS_STANDARDS.md: 2 diagrams - SKILLS_STANDARDS.md: 2 diagrams Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

- Added missing accTitle and accDescr to 6 Mermaid diagrams - Fixed malformed accDescr formatting (removed incorrect {} wrappers) - Affected files: AGENT_CREATION.md, HOOKS_STANDARDS.md, HUSKY_PRECOMMITS.md, PROMPTS_STANDARDS.md - All 12 docs files now have complete accessibility attributes on all diagrams Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Add accTitle and accDescr to three code examples (diagrams 3, 4, 5) in COOKBOOKS_STANDARDS.md. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Add missing accTitle and accDescr to all Mermaid diagrams across the repository to fix validation checks. Scanned and fixed diagrams in: - .github/ documentation and project files - instructions/ folder - vendor documentation in agents/ - Root-level README files and scripts This unblocks PR #1509 governance validation PR. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* docs: add Mermaid accessibility attributes repository-wide Add missing accTitle and accDescr to all Mermaid diagrams across the repository to fix validation checks. Scanned and fixed diagrams in: - .github/ documentation and project files - instructions/ folder - vendor documentation in agents/ - Root-level README files and scripts This unblocks PR #1509 governance validation PR. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * fix: correct Mermaid indentation in cookbook examples Fix indentation of accTitle/accDescr to match diagram content indentation level. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

ashleyshawand others added 3 commits August 4, 2026 16:23

github-actionsBot added status:needs-review Awaiting code review type:chore Chore / small hygiene change priority:normal Default priority area:documentation Docs & guides labels Aug 4, 2026

github-actionsBot added lang:md Markdown content/docs type:documentation Documentation meta:needs-changelog Requires a changelog entry before merge labels Aug 4, 2026

ashleyshaw mentioned this pull request Aug 4, 2026
fix: PR #1488 governance validation hook has regex bug + process workflow gaps #1489
Open
30 tasks

ashleyshaw enabled auto-merge (squash) August 4, 2026 18:10

ashleyshaw self-assigned this Aug 4, 2026

ashleyshaw requested a lite review from Copilot August 4, 2026 18:20

ashleyshaw added this to the v1.0 milestone Aug 4, 2026

Copilotstarted reviewing on behalf of ashleyshaw August 4, 2026 18:21 View session

CopilotAI reviewed Aug 4, 2026
View reviewed changes

ashleyshawand others added 7 commits August 4, 2026 23:44

fix: correct Mermaid diagram accessibility syntax
18586d5
Use proper YAML frontmatter for flowchart config and indent accessibility attributes. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

fix: use GitHub-compatible Mermaid accessibility syntax
ef20d38
GitHub's renderer requires inline accTitle/accDescr, not YAML frontmatter. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

fix: add accessibility attributes to workflow diagram
c69efcc
Add missing accTitle and accDescr to Mermaid diagram in docs/WORKFLOWS_STANDARDS.md. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

fix: add missing Mermaid accessibility to cookbook diagrams 3-5
30b60f1
Add accTitle and accDescr to three code examples (diagrams 3, 4, 5) in COOKBOOKS_STANDARDS.md. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

This was referenced Aug 4, 2026
feat: add AI feedback PR review validation workflow #1517
Closed
feat: add AI feedback PR review validation workflow #1526
Merged

ashleyshaw closed this in #1526 Aug 4, 2026

auto-merge was automatically disabled August 4, 2026 22:16
Pull request was closed

This was referenced Aug 4, 2026
docs: add Mermaid accessibility attributes repository-wide #1530
Merged
Repository-wide Mermaid accessibility compliance #1532
Open

Navigation Menu

Uh oh!

docs: add governance compliance and pre-commit validation guidance - #1509

docs: add governance compliance and pre-commit validation guidance#1509
ashleyshaw wants to merge 10 commits into
developfrom
chore/exclude-shells-scripts-from-eslint

ashleyshaw commented Aug 4, 2026

Uh oh!

coderabbitaiBot commented Aug 4, 2026•
edited
Loading

Review limit reached

Uh oh!

github-actionsBot commented Aug 4, 2026

Uh oh!

github-actionsBot commented Aug 4, 2026

Uh oh!

github-actionsBot commented Aug 4, 2026

Uh oh!

mergifyBot commented Aug 4, 2026

Uh oh!

github-actionsBot commented Aug 4, 2026

Uh oh!

CopilotAI left a comment

Uh oh!

ashleyshawAug 4, 2026

Uh oh!

ashleyshawAug 4, 2026

Uh oh!

ashleyshawAug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		### Pre-Commit Validation (Before Push)

		The `hooks/pr-checklist-validator.sh` hook validates every commit attempt via Claude Code's UserPromptSubmit hook.


		Pre-Commit Validation (Claude Code Users):

		If you're using Claude Code, the pre-commit validation hook will automatically check your branch name and PR template compliance:

Uh oh!

Conversation

ashleyshaw commented Aug 4, 2026

Linked issues

Summary

Changes

Documentation Sections

AGENTS.md Updates

CONTRIBUTING.md Updates

Related

Changelog

Changed

Checklist (Global DoD / PR)

Uh oh!

coderabbitaiBot commented Aug 4, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

github-actionsBot commented Aug 4, 2026

📄 README Validation

Uh oh!

github-actionsBot commented Aug 4, 2026

⏱️ Aging and SLA annotation

Uh oh!

github-actionsBot commented Aug 4, 2026

🎨 Mermaid Diagram Validation

Uh oh!

mergifyBot commented Aug 4, 2026

Uh oh!

github-actionsBot commented Aug 4, 2026

🔍 Reviewer Summary for PR #1509

Recommendations

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

ashleyshawAug 4, 2026

Choose a reason for hiding this comment

Uh oh!

ashleyshawAug 4, 2026

Choose a reason for hiding this comment

Uh oh!

ashleyshawAug 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitaiBot commented Aug 4, 2026•
edited
Loading