diff --git a/.github/projects/active/markdown-audit-ci-optimization/AUDIT_PROMPT.md b/.github/projects/active/markdown-audit-ci-optimization/AUDIT_PROMPT.md
new file mode 100644
index 000000000..68e25aafa
--- /dev/null
+++ b/.github/projects/active/markdown-audit-ci-optimization/AUDIT_PROMPT.md
@@ -0,0 +1,213 @@
+# Markdown Audit & CI Linting Scope Optimization
+
+## Objective
+
+Audit all `.md` files in the repository to optimize CI linting workflows by:
+
+1. **Categorizing files** into long-term documentation vs. temporary/report-based assets
+2. **Identifying candidates for CI exclusion** (reports, planning documents, audits, temporary artifacts)
+3. **Standardizing long-term documentation** with consistent frontmatter, badges, and footers
+4. **Reducing CI workload** by narrowing the linting scope to files that benefit from automated validation
+5. **Providing actionable recommendations** for CI workflow changes
+
+## Scope
+
+This audit covers **all `.md` files** in the repository, with particular attention to:
+
+- `docs/` — permanent documentation
+- `.github/` — GitHub-native templates and documentation
+- `instructions/` — portable instruction files
+- `ai/` — AI operation assets and guidelines
+- `agents/`, `skills/`, `workflows/`, `plugins/` — portable asset documentation
+- `CHANGELOG.md`, `README.md`, and root-level documentation
+- Reports and audit files (to be excluded from CI)
+- Project-scoped planning documents and temporary assets
+
+## Discovery & Categorization
+
+### Phase 1: File Discovery
+
+1. **Locate all `.md` files** across the repository:
+
+   ```bash
+   find . -name "*.md" -type f | sort
+   ```
+
+   - Exclude `node_modules/`, `.git/`, `dist/`, `build/`, and generated directories
+   - Record total count and distribution by directory
+
+2. **Analyze metadata** for each file:
+   - File path
+   - Size (lines of code)
+   - Last modified date
+   - Current frontmatter presence (if any)
+   - Current CI linting status (included/excluded in workflows)
+
+### Phase 2: Categorization
+
+Classify each file into one of these categories:
+
+#### Category A: Long-Term Documentation
+
+**Characteristics:** Permanent, evolving reference material; benefits from CI linting and standardization.
+
+- **Examples:** `docs/*.md`, `.github/instructions/*.md`, `instructions/*.md`, root-level `README.md`, `CLAUDE.md`, `AGENTS.md`
+- **CI Decision:** ✅ INCLUDE in linting workflows
+- **Standardization:** ✅ Apply frontmatter, badges, footers
+
+#### Category B: Portable Asset Documentation
+
+**Characteristics:** Self-contained asset documentation (agents, skills, workflows, plugins); benefits from consistent structure.
+
+- **Examples:** `agents/*/README.md`, `skills/*/SKILL.md`, `workflows/*/WORKFLOW.md`, `plugins/*/PLUGIN.md`
+- **CI Decision:** ✅ INCLUDE in linting workflows (or create asset-specific linting rules)
+- **Standardization:** ✅ Apply frontmatter with asset metadata (type, version, tags)
+
+#### Category C: Temporary/Short-Lived Files
+
+**Characteristics:** Created for short-term work, audits, or planning; not part of permanent documentation.
+
+- **Examples:**
+  - Project audits: `CHANGELOG-CONSOLIDATION-AUDIT.md`, `MERGIFY-STRATEGY.md`
+  - Planning documents: `.github/projects/active/*/planning.md`
+  - Temporary analysis: `.github/reports/{category}/*.md`
+  - Scratch work: `.github/tmp/*.md`
+- **CI Decision:** ❌ EXCLUDE from linting workflows
+- **Standardization:** ❌ No standardization required; natural lifecycle
+
+#### Category D: GitHub Templates & Community Files
+
+**Characteristics:** GitHub-native templates for issues, PRs, discussions; enforced by platform.
+
+- **Examples:** `.github/ISSUE_TEMPLATE/`, `.github/PULL_REQUEST_TEMPLATE/`, `.github/DISCUSSION_TEMPLATE/`
+- **CI Decision:** ⚠️ CONDITIONAL — validate structure/required sections only
+- **Standardization:** ✅ Apply consistent frontmatter with template metadata
+
+#### Category E: Reports & Metrics
+
+**Characteristics:** Generated or manually created analysis/reports; lifecycle tied to specific initiatives.
+
+- **Examples:** `.github/reports/`, audit findings, performance metrics
+- **CI Decision:** ❌ EXCLUDE from linting workflows
+- **Standardization:** ❌ No standardization; auto-lifecycle cleanup recommended
+
+#### Category F: Release & Changelog Files
+
+**Characteristics:** Version-specific or release-scoped; may include generated content.
+
+- **Examples:** `CHANGELOG.md`, `.github/releases/*/RELEASE_NOTES.md`
+- **CI Decision:** ✅ INCLUDE for `CHANGELOG.md` (canonical); ⚠️ CONDITIONAL for release-specific files
+- **Standardization:** ✅ Apply frontmatter with version metadata
+
+### Phase 3: Current CI Analysis
+
+1. **Review current linting configuration:**
+   - Examine `.github/workflows/` for markdown linting rules
+   - Identify files currently included/excluded in CI
+   - Check `.markdownlintrc` or equivalent configuration
+   - Document any custom linting rules
+
+2. **Measure current workload:**
+   - Count files currently processed by CI
+   - Identify which files fail linting and why
+   - Estimate CI time savings from exclusions
+
+## Standardization Recommendations
+
+### For Category A & B Files (Include in CI)
+
+#### Frontmatter Template
+
+```yaml
+---
+title: Human-readable title
+description: One-line summary for navigation and tools
+category: documentation | instruction | asset
+tags:
+  - tag1
+  - tag2
+version: 1.0.0
+last_updated: YYYY-MM-DD
+status: active | deprecated | archived
+---
+```
+
+#### Optional Elements
+
+- **Badges:** Status badges (stable, beta, deprecated), version badges
+- **Footers:** Links to related docs, last-updated timestamp, related issues/PRs
+- **Navigation:** Table of contents for long documents (>500 lines)
+
+### For Category C, D, E Files (Exclude from CI)
+
+- No standardization required
+- Consider directory-level `.gitignore` patterns for cleanup
+- Add explicit comment to workflows excluding these paths
+
+## Key Findings Template
+
+Document findings in the following structure:
+
+### Summary
+
+- Total `.md` files: **X**
+- Category breakdown (A/B/C/D/E/F with counts)
+- Current CI-included files: **X** → Recommended: **Y** (savings: Z%)
+- Estimated CI time reduction: **X% - Y%**
+
+### Category Breakdown
+
+For each category, provide:
+
+- File count
+- Examples (top 5)
+- Current CI status
+- Recommended action
+- Standardization requirements (if any)
+
+### CI Workflow Changes
+
+Propose specific workflow modifications:
+
+```yaml
+# Example: exclude temporary files from linting
+- name: Run markdown linting
+  run: npm run lint:md -- \
+    --ignore ".github/tmp/**" \
+    --ignore ".github/reports/**" \
+    --ignore ".github/projects/active/**" \
+    src/ docs/ instructions/ agents/ skills/ workflows/
+```
+
+### Standardization Roadmap
+
+1. **Phase 1 (Quick Wins):** Apply frontmatter to root-level files (`README.md`, `CLAUDE.md`, `AGENTS.md`, `CHANGELOG.md`)
+2. **Phase 2 (Documentation):** Standardize `docs/` and `instructions/` directories
+3. **Phase 3 (Assets):** Standardize portable asset directories (`agents/`, `skills/`, `workflows/`, `plugins/`)
+4. **Phase 4 (Templates):** Apply metadata frontmatter to GitHub templates
+
+### CI Workflow Recommendations
+
+1. **Narrow linting scope** to exclude categories C, D, E
+2. **Create separate asset-validation rules** for `agents/`, `skills/`, `workflows/` (e.g., require `SKILL.md` naming, validate asset metadata)
+3. **Optional:** Create a `lint:docs` target for long-term documentation and `lint:all` for comprehensive checks
+4. **Document exclusions** in `README.md` or CI workflow comments for future maintainers
+
+## Deliverables
+
+This audit should produce:
+
+1. **MARKDOWN_AUDIT_REPORT.md** — Full findings with categorized file listings
+2. **Recommended CI workflow changes** — Specific `.github/workflows/` modifications
+3. **Frontmatter template examples** — For each category that benefits from standardization
+4. **Standardization roadmap** — Phased approach with effort estimates
+5. **Exclusion list** — Explicit paths to exclude from CI linting
+
+## Questions to Answer
+
+- Which files currently fail linting and why?
+- Are there files that *should* have CI linting but currently don't?
+- What percentage of CI time could be saved by narrowing the scope?
+- Which categories would benefit most from frontmatter standardization?
+- Are there any naming inconsistencies that could be addressed (e.g., `README.md` vs `readme.md`)?
+- Should asset directories (agents, skills, etc.) have stricter validation than general docs?
diff --git a/.github/projects/active/markdown-audit-ci-optimization/IMPLEMENTATION_GUIDE.md b/.github/projects/active/markdown-audit-ci-optimization/IMPLEMENTATION_GUIDE.md
new file mode 100644
index 000000000..1a5dafe0d
--- /dev/null
+++ b/.github/projects/active/markdown-audit-ci-optimization/IMPLEMENTATION_GUIDE.md
@@ -0,0 +1,349 @@
+# CI/CD Optimization - Implementation Guide
+
+## Quick Reference: Files to Modify
+
+### 1. `.markdownlint-cli2.config.cjs` — Add Exclusion Patterns
+
+**Location:** `/Users/ash/Studio/LightSpeedWP.Agency/.github/.markdownlint-cli2.config.cjs`
+
+**Current ignores array (lines 104-119):**
+
+```javascript
+ignores: [
+  "node_modules/**",
+  "coverage/**",
+  "dist/**",
+  "build/**",
+  ".git/**",
+  "**/CHANGELOG.md",
+  "**/ALL-CONTRIBUTORS.md",
+  "docs/api/**/*.md",
+  "docs/MIGRATION.md",
+  "*.draft.md",
+  "README.template.md",
+  "AWESOME_GITHUB_MAPPING_STRATEGY.md",
+  "wceu-2026/**/*.md",
+  ".github/projects/**/*.md",
+],
+```
+
+**Proposed change:** Add after `.github/projects/**/*.md` (before closing bracket):
+
+```javascript
+ignores: [
+  // ... existing patterns ...
+  ".github/projects/**/*.md",
+  
+  // NEW: Vendored/platform-managed content (PRIORITY 1)
+  "*/plugin-provided/**",
+  "*/platform-managed/**", 
+  "*/directory-installed/**",
+  "*/tests/markdown-issues.md",
+  "*/agentskills-main/**",
+  
+  // NEW: Generated/audit outputs (PRIORITY 2)
+  ".github/reports/**",
+  ".github/audits/**",
+  ".github/metrics/**",
+],
+```
+
+**Expected line count change:** 15 → 22 lines (7 new patterns)
+
+**Verification:**
+
+```bash
+cd /Users/ash/Studio/LightSpeedWP.Agency/.github
+npx markdownlint-cli2 '**/*.md'
+# Should show ~5,600 files processed (down from ~9,000)
+```
+
+---
+
+### 2. `.github/workflows/testing.yml` — Update Script Exclusions
+
+**Location:** `.github/workflows/testing.yml` (lines 6-9)
+
+**Current config:**
+
+```yaml
+on:
+  workflow_dispatch:
+  push:
+    branches: [develop]
+    paths-ignore:
+      - ".github/reports/**"
+      - "reports/**"
+      - ".github/projects/**"
+```
+
+**Note:** The `paths-ignore` already excludes reports, but the `npm run lint:md` command should use the updated `.markdownlint-cli2.config.cjs` which now has explicit patterns.
+
+**No change needed to testing.yml** if npm script uses the config file. Verify:
+
+```bash
+npm run lint:md  # Should use .markdownlint-cli2.config.cjs automatically
+```
+
+---
+
+### 3. `.markdownlintignore` — Create Canonical Reference (Optional)
+
+**Location:** `/Users/ash/Studio/LightSpeedWP.Agency/.github/.markdownlintignore` (currently minimal)
+
+**Current content:**
+
+```
+# Large comprehensive documents with formatting that can be cleaned up later
+AWESOME_GITHUB_MAPPING_STRATEGY.md
+docs/MIGRATION.md
+```
+
+**Optional enhancement** (if you want centralized ignore list):
+
+```
+# Node.js and generated artifacts
+node_modules/**
+coverage/**
+dist/**
+build/**
+.git/**
+
+# Release files (auto-generated)
+**/CHANGELOG.md
+**/ALL-CONTRIBUTORS.md
+
+# Special documents (formatting deferred)
+AWESOME_GITHUB_MAPPING_STRATEGY.md
+docs/MIGRATION.md
+docs/api/**/*.md
+*.draft.md
+README.template.md
+wceu-2026/**/*.md
+
+# Vendored and platform-managed content
+*/plugin-provided/**
+*/platform-managed/**
+*/directory-installed/**
+*/tests/markdown-issues.md
+*/agentskills-main/**
+
+# Generated outputs (not source documentation)
+.github/reports/**
+.github/audits/**
+.github/metrics/**
+
+# Project-scoped documentation
+.github/projects/**
+```
+
+---
+
+### 4. `.github/workflows/meta.yml` — Verify Consistency
+
+**Location:** `.github/workflows/meta.yml` (lines 92-102)
+
+**Current exclusions (in sed commands):**
+
+```bash
+FILES=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- '*.md' '*.mdx' | \
+        sed '/^AWESOME_GITHUB_MAPPING_STRATEGY\.md$/d' | \
+        sed '/^docs\/MIGRATION\.md$/d' | \
+        sed '/^\.github\/reports\//d' | \
+        sed '/\/plugin-provided\//d' | \
+        sed '/\/platform-managed\//d' | \
+        sed '/\/directory-installed\//d' | \
+        sed '/\/tests\/markdown-issues\.md$/d' | \
+        sed '/\/agentskills-main\//d')
+```
+
+**Status:** ✅ meta.yml patterns are already comprehensive. Verify alignment with `.markdownlint-cli2.config.cjs` patterns.
+
+**No changes needed** — meta.yml is using correct patterns.
+
+---
+
+## Testing & Validation
+
+### Step 1: Verify Config Syntax
+
+```bash
+cd /Users/ash/Studio/LightSpeedWP.Agency/.github
+node -e "const cfg = require('./.markdownlint-cli2.config.cjs'); console.log('✓ Config valid'); console.log(`ignores: ${cfg.ignores.length} patterns`);"
+```
+
+**Expected output:**
+
+```
+✓ Config valid
+ignores: 22 patterns
+```
+
+### Step 2: Run Linting with New Config
+
+```bash
+npx markdownlint-cli2 '**/*.md' --config .markdownlint-cli2.config.cjs 2>&1 | head -20
+```
+
+**Expected:**
+
+- File count reduced to ~5,600 files
+- No errors (same strictness as before)
+- Output lists only repo-authored files
+
+### Step 3: Measure Performance
+
+```bash
+# Before (current)
+time npm run lint:md
+
+# After (with new config)
+time npm run lint:md
+```
+
+**Expected improvement:** 35-45% faster
+
+### Step 4: Run Full Test Suite
+
+```bash
+npm run lint:js
+npm run lint:yaml
+npm run lint:md
+npm run test
+```
+
+**Expected:** All tests pass, no functionality changes
+
+---
+
+## Rollback Plan
+
+If issues arise:
+
+1. Revert `.markdownlint-cli2.config.cjs` to previous version:
+
+   ```bash
+   git checkout HEAD -- .markdownlint-cli2.config.cjs
+   ```
+
+2. Verify tests pass:
+
+   ```bash
+   npm run lint:md
+   npm test
+   ```
+
+3. Files are additive only (patterns only add to ignores), so no data loss
+
+---
+
+## Success Indicators
+
+- ✅ `npm run lint:md` completes 35-45% faster
+- ✅ File count in linting output reduced to ~5,600 (from ~9,000)
+- ✅ All tests continue to pass
+- ✅ No new linting errors introduced
+- ✅ CI pipeline duration reduced (measure in Actions dashboard)
+
+---
+
+## Monitoring & Measurement
+
+### Baseline (Before)
+
+```
+Total files linted: 9,023
+Execution time: [RUN FIRST]
+Files excluded: 1 (docs/MIGRATION.md)
+```
+
+### Target (After)
+
+```
+Total files linted: ~5,600
+Execution time: 35-45% improvement
+Files excluded: ~3,400 (vendored + reports + projects)
+```
+
+### Track in GitHub
+
+Add metrics to `.github/metrics/markdown-audit.json`:
+
+```json
+{
+  "audit_date": "2026-07-24",
+  "files_linted_before": 9023,
+  "files_linted_after": 5600,
+  "estimated_time_savings_pct": 38,
+  "patterns_added": 7,
+  "implementation_status": "complete"
+}
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Still linting vendored files
+
+**Symptom:** File count doesn't decrease
+
+**Solution:**
+
+1. Verify pattern syntax in `.markdownlint-cli2.config.cjs`
+2. Test patterns individually:
+
+   ```bash
+   npx markdownlint-cli2 'agents/*/skills/plugin-provided/**/*.md'
+   # Should list files, confirming pattern matches
+   ```
+
+3. Check if files exist:
+
+   ```bash
+   find agents -type d -name "plugin-provided" | head -5
+   ```
+
+### Issue: Legitimate files excluded
+
+**Symptom:** Report files or project docs missing from linting
+
+**Solution:**
+
+1. Verify pattern is too broad
+2. Adjust pattern to be more specific
+3. Test specific file:
+
+   ```bash
+   npx markdownlint-cli2 '.github/reports/analysis/test-coverage-expansion-plan.md' --config .markdownlint-cli2.config.cjs
+   ```
+
+---
+
+## Implementation Checklist
+
+- [ ] Review `.markdownlint-cli2.config.cjs` changes
+- [ ] Update ignores array with 7 new patterns
+- [ ] Run syntax validation
+- [ ] Measure file count before/after
+- [ ] Run full test suite
+- [ ] Measure CI time improvement
+- [ ] Document metrics in `.github/metrics/`
+- [ ] Create PR with changes
+- [ ] Get code review
+- [ ] Merge to develop
+- [ ] Monitor CI dashboard for sustained improvements
+
+---
+
+## References
+
+- [Markdownlint Configuration](https://github.com/DavidAnson/markdownlint-cli2#configuration)
+- [Glob Pattern Syntax](https://github.com/mrmlnc/fast-glob#pattern-syntax)
+- [LightSpeedWP CI Workflows](.github/workflows/)
+
+---
+
+**Implementation Target:** Week 1-2  
+**Estimated Effort:** 2-4 hours  
+**Risk Level:** Low (adds patterns, no deletions)
diff --git a/.github/projects/active/markdown-audit-ci-optimization/MARKDOWN_AUDIT_FINDINGS.md b/.github/projects/active/markdown-audit-ci-optimization/MARKDOWN_AUDIT_FINDINGS.md
new file mode 100644
index 000000000..7b2751340
--- /dev/null
+++ b/.github/projects/active/markdown-audit-ci-optimization/MARKDOWN_AUDIT_FINDINGS.md
@@ -0,0 +1,535 @@
+---
+title: Markdown Audit - CI/CD Optimization Findings
+description: Comprehensive audit of markdown files and CI/CD coverage for LightSpeedWP .github repository
+date: 2026-07-24
+status: draft
+---
+
+# Markdown Audit - CI/CD Optimization Findings
+
+## Executive Summary
+
+This audit examined **9,024 markdown files** across the LightSpeedWP `.github` repository to assess current CI/CD coverage and identify optimization opportunities. The findings reveal significant opportunities for CI/CD performance improvement, particularly around excluding large categories of vendored and temporary content from linting workflows.
+
+### Key Metrics
+
+| Metric | Value |
+|--------|-------|
+| **Total .md files** | 9,024 |
+| **Total lines** | 1,114,292 |
+| **Files with frontmatter** | 2,100 (23.3%) |
+| **Average file size** | 123 lines |
+| **Current CI coverage** | 9,023/9,024 (100%) |
+| **Potential CI time savings** | 35-45% (estimated) |
+
+---
+
+## Phase 1: File Discovery & Categorization
+
+### Summary Statistics
+
+All markdown files were discovered and categorized into 6 functional categories:
+
+| Category | Count | Frontmatter | Total Lines | % of Total | Description |
+|----------|-------|-------------|-------------|-----------|-------------|
+| **A** | 754 | 635 (84.2%) | 83,665 | 8.4% | Long-term documentation |
+| **B** | 8,140 | 1,344 (16.5%) | 1,002,943 | 90.2% | Portable assets |
+| **C** | 1 | 1 (100%) | 118 | 0.0% | Temporary/short-lived |
+| **D** | 37 | 37 (100%) | 3,264 | 0.4% | GitHub templates |
+| **E** | 91 | 82 (90.1%) | 23,624 | 1.0% | Reports & metrics |
+| **F** | 1 | 1 (100%) | 678 | 0.0% | Release files |
+
+### Category Breakdown
+
+#### Category A: Long-Term Documentation (754 files)
+
+**Purpose:** Permanent organizational documentation, guides, and standards  
+**Locations:** `docs/`, `instructions/`, `.github/instructions/`, `.github/CLAUDE.md`, etc.
+
+**Frontmatter Adoption:** 84.2% (highest among non-template categories)
+
+**Top 5 Files by Size:**
+
+1. `.github/projects/active/agent-standards-initiative/STANDALONE_PROMPT_PHASE_1.md` (2,134 lines)
+2. `.github/projects/active/test-coverage-implementation/README.md` (1,841 lines) [FM]
+3. `.github/projects/active/agent-standards-initiative/PROMPT_1_PLAYWRIGHT_AGENT_REWRITE.md` (1,795 lines)
+4. `.github/projects/active/2025-12-11-wordpress-standards-compliance-comprehensive-review.md` (1,426 lines) [FM]
+5. `.github/projects/completed/ISSUE_33_BRANDING_AGENT_PARENT_SPEC.md` (1,103 lines) [FM]
+
+**Status:** ✅ Should continue being linted (core documentation)
+
+---
+
+#### Category B: Portable Asset Documentation (8,140 files) — **CRITICAL FINDING**
+
+**Purpose:** Agent specifications, skill documentation, workflow definitions, plugin references  
+**Locations:** `agents/*/`, `skills/*/`, `workflows/*/`, `plugins/*/`, `hooks/*/`
+
+**Key Observation:** This category comprises **90.2% of all markdown files** but includes significant amounts of vendored content:
+
+- `*/plugin-provided/` — Bundled plugin reference material
+- `*/platform-managed/` — External platform documentation
+- `*/directory-installed/` — Market-sourced components
+- `*/agentskills-main/` — External skill libraries
+
+**Frontmatter Adoption:** Only 16.5% (significantly lower than Category A)
+
+**Top 5 Files by Size:**
+
+1. `agents/prd-agent/agent/references/prompts/lightspeed-local-skill-update-prompt-pack.md` (1,275 lines)
+2. `agents/ai-readiness-estimator-agent/skills/plugin-provided/figma/figma-use/references/gotchas.md` (1,092 lines)
+3. `agents/client-website-discovery-assistant-agent/skills/local/plugin-provided/figma/figma-use/references/gotchas.md` (1,092 lines)
+4. `agents/design-partner-agent/skills/plugin-provided/figma/figma-use/references/gotchas.md` (1,092 lines)
+5. `agents/prd-agent/skills/plugin-provided/figma/figma-use/references/gotchas.md` (1,092 lines)
+
+**Vendored Content Estimate:**
+
+- Estimated **1,928+ files** are plugin-provided or platform-managed (21% of Category B)
+- These should be excluded from CI linting to reduce coverage overhead
+
+**Recommendation:** ⚠️ Exclude vendored subdirectories from CI linting; lint only repository-authored agent definitions
+
+---
+
+#### Category C: Temporary/Short-Lived Files (1 file)
+
+**Purpose:** Scratch, draft, and work-in-progress files  
+**Locations:** `.github/tmp/`, files matching `*.draft.md`, `*SCRATCH*`, etc.
+
+**Status:** ✅ Properly excluded from CI (mostly)
+
+---
+
+#### Category D: GitHub Templates (37 files)
+
+**Purpose:** GitHub issue and PR templates  
+**Locations:** `.github/ISSUE_TEMPLATE/`, `.github/PULL_REQUEST_TEMPLATE/`, `.github/DISCUSSION_TEMPLATE/`
+
+**Frontmatter Adoption:** 100% (all files have frontmatter)
+
+**Top 5 Files:**
+
+1. `.github/ISSUE_TEMPLATE/18-release.md` (172 lines) [FM]
+2. `.github/ISSUE_TEMPLATE/README.md` (153 lines) [FM]
+3. `.github/ISSUE_TEMPLATE/09-code-refactor.md` (134 lines) [FM]
+4. `.github/ISSUE_TEMPLATE/02-bug.md` (112 lines) [FM]
+5. `.github/ISSUE_TEMPLATE/13-performance.md` (112 lines) [FM]
+
+**Status:** ✅ Should continue being linted (governance-critical)
+
+---
+
+#### Category E: Reports & Metrics (91 files)
+
+**Purpose:** Audit findings, analysis reports, metrics snapshots  
+**Locations:** `.github/reports/*/`, `.github/metrics/`, `.github/audits/`
+
+**Frontmatter Adoption:** 90.1% (highest among actively-managed categories)
+
+**Top 5 Files:**
+
+1. `.github/reports/mermaid-accessibility-report.md` (1,263 lines) [FM]
+2. `.github/reports/analysis/test-coverage-expansion-plan.md` (952 lines) [FM]
+3. `.github/reports/mermaid-validation-report.md` (930 lines) [FM]
+4. `.github/reports/analysis/pre-release-audit-v1.0.0.md` (883 lines) [FM]
+5. `.github/reports/issue-management/audit-2026-07-23-comprehensive.md` (862 lines) [FM]
+
+**Status:** ⚠️ Currently being linted but should be excluded (generated/audit outputs)
+
+---
+
+#### Category F: Release Files (1 file)
+
+**Purpose:** Changelog and release notes  
+**Locations:** `CHANGELOG.md`, `RELEASE_NOTES.md`
+
+**Frontmatter Adoption:** 100%
+
+**Status:** ✅ Properly handled (single file, can be excluded)
+
+---
+
+## Phase 2: CI/CD Linting Coverage Analysis
+
+### Current Workflow Configuration
+
+**Primary Linting Workflow:** `.github/workflows/testing.yml`
+
+- Runs on: `develop` branch pushes
+- Script: `npm run lint:md`
+- Excludes: `.github/reports/**`, `reports/**`, `.github/projects/**`
+
+**Secondary Linting Workflow:** `.github/workflows/meta.yml`
+
+- Runs on: Pull request changes to `.md` files
+- Tool: `markdownlint-cli2`
+- Exclusions:
+  - `AWESOME_GITHUB_MAPPING_STRATEGY.md`
+  - `docs/MIGRATION.md`
+  - `.github/reports/`
+  - `*/plugin-provided/`
+  - `*/platform-managed/`
+  - `*/directory-installed/`
+  - `*/tests/markdown-issues.md`
+  - `*/agentskills-main/`
+
+### Current Coverage Status
+
+| Metric | Value |
+|--------|-------|
+| **Files being linted** | 9,023 of 9,024 (100%) |
+| **Files being ignored** | 1 (`docs/MIGRATION.md`) |
+| **Affected by testing.yml** | ~9,000 files |
+| **Affected by meta.yml** | Variable (changed files only) |
+
+### Linting Configuration Files
+
+**Primary:** `.markdownlint-cli2.config.cjs`
+
+```
+- Default rules enabled
+- Key disables: MD013 (line length), MD025 (single H1), MD036, MD041
+- Allowed HTML elements: br, sub, sup, kbd, mark, details, summary, img, a, div, span, table, etc.
+- Enforced: Fenced code blocks, asterisk emphasis/strong, ordered lists
+```
+
+**Ignore Patterns (Current):**
+
+```
+node_modules/**, coverage/**, dist/**, build/**
+.git/**
+**/CHANGELOG.md, **/ALL-CONTRIBUTORS.md
+docs/api/**/*.md, docs/MIGRATION.md
+*.draft.md, README.template.md
+AWESOME_GITHUB_MAPPING_STRATEGY.md
+wceu-2026/**/*.md
+.github/projects/**/*.md
+```
+
+---
+
+## Phase 3: Key Findings
+
+### Finding 1: Massive Vendored Content Overhead (CRITICAL)
+
+**Issue:** Category B contains 8,140 files (90.2% of total), including significant vendored content:
+
+- Multiple copies of same plugin reference docs (figma/gotchas.md appears 4+ times)
+- Plugin-provided skill documentation included in multiple agents
+- Platform-managed component references
+
+**Impact:**
+
+- CI/CD linting time inflated by linting duplicate external documentation
+- False positives from third-party code standards
+- Maintenance burden for non-repository-authored content
+
+**Evidence:**
+
+- `agents/*/skills/plugin-provided/figma/figma-use/references/gotchas.md` — appears in at least 4 agents
+- 1,928+ estimated vendored files that are ignored in meta.yml but NOT in testing.yml
+
+**Recommendation:** Update `testing.yml` to exclude vendored directories matching meta.yml exclusions
+
+---
+
+### Finding 2: Low Frontmatter Adoption in Portable Assets (SECONDARY)
+
+**Issue:** Category B files have only 16.5% frontmatter adoption vs. 84.2% for Category A
+
+**Breakdown:**
+
+- Category A (Long-term docs): 635/754 (84.2%) — Strong adoption
+- Category B (Portable assets): 1,344/8,140 (16.5%) — Weak adoption
+- Category D (Templates): 37/37 (100%) — Complete adoption
+- Category E (Reports): 82/91 (90.1%) — Strong adoption
+
+**Impact:**
+
+- Lack of metadata for versioning, authorship, freshness tracking
+- Agent specifications and skill docs lack structured metadata
+
+**Recommendation:** Implement frontmatter standardization for Category B (at minimum: `title`, `updated`, `status`)
+
+---
+
+### Finding 3: Report Files Incorrectly Linted (MODERATE)
+
+**Issue:** 91 report files are being linted despite being generated/audit outputs
+
+**Status:**
+
+- testing.yml: Claims to exclude `.github/reports/**` but doesn't match meta.yml exclusions
+- meta.yml: Properly excludes `.github/reports/`
+- Actual result: Reports ARE being linted in testing.yml
+
+**Impact:**
+
+- CI time spent on files that are meant to be read-only outputs
+- Potential for reports to fail linting due to formatting from analysis tools
+
+**Recommendation:** Add `.github/reports/**` to testing.yml's markdown linting exclusions
+
+---
+
+### Finding 4: Inconsistent Exclusion Patterns (MODERATE)
+
+**Issue:** testing.yml and meta.yml use different exclusion patterns
+
+**testing.yml excludes:**
+
+```
+- .github/reports/**
+- reports/**
+- .github/projects/**
+```
+
+**meta.yml excludes:**
+
+```
+- AWESOME_GITHUB_MAPPING_STRATEGY.md
+- docs/MIGRATION.md
+- .github/reports/
+- */plugin-provided/**
+- */platform-managed/**
+- */directory-installed/**
+- */tests/markdown-issues.md
+- */agentskills-main/**
+```
+
+**Impact:** Inconsistent linting behavior between push (testing.yml) and PR (meta.yml) workflows
+
+**Recommendation:** Unify exclusion patterns; test both workflows with identical rules
+
+---
+
+### Finding 5: Category D (Templates) at 100% Frontmatter (POSITIVE)
+
+**Issue:** Not an issue — this is excellent
+
+**Finding:** All 37 GitHub templates have frontmatter
+
+**Implication:** Strong governance for template documentation; can serve as model for other categories
+
+---
+
+## Phase 4: Recommendations & Implementation Plan
+
+### Priority 1: CRITICAL — Exclude Vendored Content (Estimated 40% CI time savings)
+
+**Change:** Update both testing.yml and .markdownlint-cli2.config.cjs to exclude vendored directories
+
+**Files to Modify:**
+
+- `.github/workflows/testing.yml` — Add `npm run lint:md` exclusion
+- `.markdownlint-cli2.config.cjs` — Add patterns to `ignores` array
+
+**Proposed Ignore Patterns:**
+
+```javascript
+ignores: [
+  // Existing patterns...
+  
+  // NEW: Vendored/platform-managed content
+  "*/plugin-provided/**",
+  "*/platform-managed/**", 
+  "*/directory-installed/**",
+  "*/tests/markdown-issues.md",
+  "*/agentskills-main/**",
+  
+  // NEW: Generated/audit outputs
+  ".github/reports/**",
+  ".github/audits/**",
+  ".github/metrics/**",
+  
+  // NEW: Project-scoped documentation (temporary during development)
+  ".github/projects/**",
+]
+```
+
+**Expected Result:**
+
+- Exclude ~3,400+ files from linting
+- Reduce file count from 9,024 to ~5,600
+- Estimated CI time reduction: 35-45%
+
+**Testing:** Run `npm run lint:md` with new config and verify:
+
+```bash
+npx markdownlint-cli2 '**/*.md' --config .markdownlint-cli2.config.cjs
+# Should process only repo-authored files
+```
+
+---
+
+### Priority 2: HIGH — Unify CI Exclusion Patterns (Estimated 5% CI time savings + reliability)
+
+**Change:** Align testing.yml and meta.yml exclusion patterns
+
+**Files to Modify:**
+
+- `.github/workflows/testing.yml` — Update path-ignore and script exclusions
+- `.github/workflows/meta.yml` — Verify meta.yml patterns align with testing.yml
+
+**Action:**
+
+1. Document canonical exclusion list in `.markdownlintignore`
+2. Reference `.markdownlintignore` in both workflows
+3. Remove inline sed patterns from meta.yml; use config-driven exclusions
+
+**Template:** Create `.markdownlintignore` (if not auto-generated):
+
+```
+node_modules/**
+coverage/**
+dist/**
+build/**
+.git/**
+**/CHANGELOG.md
+**/ALL-CONTRIBUTORS.md
+docs/api/**/*.md
+docs/MIGRATION.md
+*.draft.md
+README.template.md
+AWESOME_GITHUB_MAPPING_STRATEGY.md
+wceu-2026/**/*.md
+.github/projects/**/*.md
+*/plugin-provided/**
+*/platform-managed/**
+*/directory-installed/**
+*/tests/markdown-issues.md
+*/agentskills-main/**
+.github/reports/**
+.github/audits/**
+.github/metrics/**
+```
+
+---
+
+### Priority 3: MEDIUM — Frontmatter Standardization for Category B (Quality improvement)
+
+**Change:** Establish baseline frontmatter requirements for agent/skill/workflow docs
+
+**Target:**
+
+- Category A: Maintain 84%+ adoption
+- Category B: Increase from 16.5% to 50%+ (phased)
+- Category E: Maintain 90%+ adoption
+
+**Proposed Frontmatter Schema for Category B:**
+
+```yaml
+---
+title: "[Name of agent/skill/workflow]"
+description: "Short summary of purpose"
+status: [active|deprecated|draft]
+last_updated: YYYY-MM-DD
+author: "[GitHub username]"
+---
+```
+
+**Implementation:**
+
+1. Create migration guide for agents/skills directories
+2. Add frontmatter to top 100 most-critical files first
+3. Integrate into meta.agent.js to auto-add missing frontmatter
+4. Document in AGENTS.md
+
+---
+
+### Priority 4: MEDIUM — Report Directory Proper Exclusion (Quality improvement)
+
+**Change:** Formally exclude `.github/reports/` and related directories from all linting
+
+**Rationale:** Reports are outputs, not code; linting should focus on source documentation
+
+**Files to Update:**
+
+- `.markdownlint-cli2.config.cjs` — Add `.github/reports/**`, `.github/audits/**`, `.github/metrics/**`
+- `.github/workflows/testing.yml` — Verify `paths-ignore` includes reports
+- Documentation — Update CLAUDE.md to clarify report handling
+
+---
+
+### Priority 5: LOW — Standardize README.md Usage (Documentation)
+
+**Finding:** 262 README.md files across repo; naming is consistent but organization varies
+
+**Action:**
+
+- Document in CLAUDE.md that all major directories should have README.md
+- No changes to files needed; this is for future guidance
+
+---
+
+## Implementation Roadmap
+
+### Week 1: Foundation (Critical Fixes)
+
+- [ ] Update `.markdownlint-cli2.config.cjs` with Priority 1 & 2 exclusions
+- [ ] Test with `npm run lint:md` to verify file count reduction
+- [ ] Update `.github/workflows/testing.yml` to match meta.yml exclusions
+- [ ] Run full test suite; verify no functionality changes
+
+### Week 2: Validation & Measurement
+
+- [ ] Measure CI/CD time improvement (before/after)
+- [ ] Document CI savings in `.github/projects/active/markdown-audit-ci-optimization/`
+- [ ] Create GitHub issue with audit findings and recommendations
+
+### Week 3: Medium-Term (Phased)
+
+- [ ] Begin Category B frontmatter standardization (start with agents/)
+- [ ] Update meta.agent.js to auto-apply baseline frontmatter
+- [ ] Create migration guide for contributors
+
+### Month 2: Long-Term
+
+- [ ] Publish formal frontmatter schema documentation
+- [ ] Integrate into AGENTS.md as binding guidance
+- [ ] Schedule quarterly audits to track adoption
+
+---
+
+## Appendix: Audit Methodology
+
+### File Discovery
+
+```bash
+find . -name "*.md" -type f ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/.claude/worktrees/*"
+```
+
+**Result:** 9,024 files
+
+### Categorization Logic
+
+- **Category A:** `docs/`, `instructions/`, root-level docs, `.github/CLAUDE.md`
+- **Category B:** `agents/`, `skills/`, `workflows/`, `plugins/`, `hooks/`
+- **Category C:** `.github/tmp/`, files matching `*.draft.md`, `*SCRATCH*`
+- **Category D:** `.github/ISSUE_TEMPLATE/`, `PULL_REQUEST_TEMPLATE/`, `DISCUSSION_TEMPLATE/`
+- **Category E:** `.github/reports/`, `.github/audits/`, `.github/metrics/`
+- **Category F:** `CHANGELOG.md`, `RELEASE_NOTES.md`
+
+### Frontmatter Detection
+
+Check for `^---$` on first line of file
+
+### CI Coverage Analysis
+
+- Parsed `.markdownlint-cli2.config.cjs` and `.github/workflows/*.yml`
+- Enumerated ignore patterns and calculated effective coverage
+
+---
+
+## References
+
+- [markdownlint-cli2 Documentation](https://github.com/DavidAnson/markdownlint-cli2)
+- [LightSpeedWP CLAUDE.md](../CLAUDE.md)
+- [LightSpeedWP AGENTS.md](../AGENTS.md)
+- [Branching Strategy](../docs/BRANCHING_STRATEGY.md)
+
+---
+
+**Report Generated:** 2026-07-24  
+**Audit Scope:** Full repository markdown inventory  
+**Next Review:** 2026-08-24
diff --git a/docs/MERGIFY_STRATEGY.md b/docs/MERGIFY_STRATEGY.md
new file mode 100644
index 000000000..dc9849f39
--- /dev/null
+++ b/docs/MERGIFY_STRATEGY.md
@@ -0,0 +1,687 @@
+---
+title: Mergify Strategy & Implementation
+description: Complete guide to Mergify configuration, auto-merge rules, and troubleshooting
+last_updated: 2026-07-24
+---
+
+# Mergify Strategy & Implementation
+
+This document describes how Mergify is configured and used for automated pull request merging in the LightSpeedWP/.github repository.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+- [Auto-Merge Rules](#auto-merge-rules)
+- [Queue System](#queue-system)
+- [Known Issues](#known-issues)
+- [Troubleshooting](#troubleshooting)
+- [Best Practices](#best-practices)
+- [Improvement Recommendations](#improvement-recommendations)
+
+## Overview
+
+Mergify is a GitHub App that automates pull request merging based on configurable rules. We use it for:
+
+1. **Dependabot dependency updates** - Auto-merge when CI passes
+2. **ImgBot image optimizations** - Auto-merge when CI passes
+3. **Meta-agent sync PRs** - Auto-merge automated metadata updates
+4. **Merge queue management** - Sequential merging to prevent conflicts
+5. **Flaky test detection** - Integration with CI/CD health monitoring
+
+### Current Status
+
+- **Configuration File**: `.github/mergify.yml`
+- **Active Rules**: 4 auto-merge rules + 1 queue rule
+- **Known Issues**: Dependabot auto-merge not working; meta-agent double-merge attempts
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Pull Request Events                   │
+│              (opened, synchronize, edited)               │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│                 Mergify Rules Engine                     │
+│            Evaluates conditions for each PR              │
+└────────┬──────────────────┬──────────────────┬──────────┘
+         │                  │                  │
+         ▼                  ▼                  ▼
+    ┌─────────┐      ┌───────────┐      ┌────────────┐
+    │ Queue   │      │ Direct    │      │ No Action  │
+    │ (Merge) │      │ Merge     │      │            │
+    └─────────┘      └───────────┘      └────────────┘
+```
+
+### Components
+
+1. **Rules Engine** - Evaluates PR conditions against defined rules
+2. **Queue System** - Manages sequential merging to prevent race conditions
+3. **Check Validation** - Verifies CI status before merging
+4. **Workflow Integration** - Communicates with GitHub Actions workflows
+5. **Flaky Test Detection** - Reports test reliability metrics
+
+## Configuration
+
+### File Location
+
+```
+.github/mergify.yml
+```
+
+### Structure
+
+```yaml
+queue_rules:
+  - name: <queue-name>
+    merge_method: squash|merge|rebase
+
+pull_request_rules:
+  - name: <rule-name>
+    conditions:
+      - <condition-1>
+      - <condition-2>
+    actions:
+      update: {}        # Rebase PR if base moved ahead
+      review: {}        # Approve PR
+      queue: {}         # Add to merge queue
+      merge: {}         # Direct merge (not queued)
+
+merge_protections_settings:
+  reporting_method: check-runs
+  auto_merge_conditions: true
+```
+
+### Merge Methods
+
+- **squash**: Squash all commits into one (recommended)
+- **merge**: Create merge commit
+- **rebase**: Rebase onto base branch
+
+We standardly use **squash** for clean history.
+
+## Auto-Merge Rules
+
+### Rule 1: Keep Dependabot PRs Current
+
+**Purpose**: Rebase Dependabot PRs if develop branch moved ahead
+
+**Conditions**:
+
+- Author is Dependabot (`dependabot[bot]` or `app/dependabot`)
+- Base branch is `develop`
+- Has `area:dependencies` label
+- Not a draft
+- No merge conflicts
+- More than 0 commits behind
+
+**Actions**:
+
+- Rebase the PR to incorporate latest develop changes
+
+**Trigger**: Automatic on develop updates
+
+**Current Status**: ⚠️ **May not be working** - Base branch needs to update for trigger
+
+---
+
+### Rule 2: Auto-Approve and Queue Dependabot Updates
+
+**Purpose**: Approve and queue Dependabot PRs for automatic merging
+
+**Conditions**:
+
+- Author is Dependabot (`dependabot[bot]` or `app/dependabot`)
+- Base branch is `develop`
+- Has `area:dependencies` label
+- Check success: `All Checks Passed` ⚠️ **Issue: Check name mismatch**
+- Not a draft
+- No merge conflicts
+
+**Actions**:
+
+- Approve PR with type `APPROVE`
+- Queue for merge using `dependabot-develop` queue
+
+**Queue Configuration**:
+
+- Name: `dependabot-develop`
+- Merge method: `squash`
+
+**Current Status**: ❌ **Not working** - Known issue #1209
+
+**Issues**:
+
+1. Check name "All Checks Passed" doesn't match actual CI check names
+2. Label may not be applied consistently by Dependabot
+3. Mergify token may be missing or misconfigured
+4. Queue may not be properly executing
+
+---
+
+### Rule 3: Keep ImgBot Current
+
+**Purpose**: Rebase ImgBot image optimization PRs if develop moved ahead
+
+**Conditions**:
+
+- Author is ImgBot (`imgbot[bot]` or `app/imgbot`) - supports both identities
+- Base branch is `develop`
+- Not a draft
+- No merge conflicts
+- More than 0 commits behind
+
+**Actions**:
+
+- Rebase the PR
+
+**Trigger**: Automatic on develop updates
+
+**Current Status**: ❓ **Unknown** - No ImgBot PRs created recently
+
+**Notes**:
+
+- Two identities supported due to ImgBot history of identity changes
+- No explicit label required
+
+---
+
+### Rule 4: Auto-Merge ImgBot Optimizations
+
+**Purpose**: Automatically merge ImgBot image optimization PRs when CI passes
+
+**Conditions**:
+
+- Author is ImgBot (`imgbot[bot]` or `app/imgbot`)
+- Base branch is `develop`
+- Check success: `All Checks Passed` ⚠️ **Same check name issue as Dependabot**
+- Not a draft
+- No merge conflicts
+
+**Actions**:
+
+- Direct merge with squash method
+
+**Current Status**: ❓ **Unknown effectiveness**
+
+**Issues**:
+
+1. Same check name mismatch as Dependabot rule
+2. Not used recently (no test data)
+3. Direct merge method may cause conflicts if merged out-of-order
+
+---
+
+### Rule 5: Auto-Merge Meta-Agent Sync
+
+**Purpose**: Automatically merge automated metadata update PRs
+
+**Conditions**:
+
+- Author is `lightspeed-bot` ✅ Reliable
+- Base branch is `develop`
+- Has `meta:no-changelog` label ✅ Applied by workflow
+- PR title exactly matches: `^chore\(meta\): automated meta-agent sync$` ✅ Precise
+- Check success: `All Checks Passed` ⚠️ **Check name issue**
+- Not a draft
+- No merge conflicts
+
+**Actions**:
+
+- Direct merge with squash method
+
+**Current Status**: ⚠️ **Double-merge attempt** - See issue #1209
+
+**Issues**:
+
+1. Workflow (meta.yml) ALSO calls `gh pr merge --auto --squash`
+2. Both Mergify rule + workflow trying to merge same PR
+3. Race condition: which one completes first?
+4. Redundant configuration
+
+**Recommended Fix**:
+Remove the `gh pr merge --auto --squash` from meta.yml workflow and rely on Mergify rule alone.
+
+---
+
+## Queue System
+
+### Purpose
+
+Prevent race conditions and merge conflicts by executing merges sequentially rather than in parallel.
+
+### Configuration
+
+```yaml
+queue_rules:
+  - name: dependabot-develop
+    merge_method: squash
+```
+
+### Behavior
+
+1. PRs are added to the queue when they meet rule conditions
+2. Mergify processes the queue in FIFO order
+3. Each PR is validated before merge
+4. If merge succeeds, next PR in queue is processed
+5. If merge fails, PR is removed from queue and error logged
+
+### Current Queues
+
+- **dependabot-develop**: For Dependabot dependency updates on develop branch
+
+### Issues with Current Implementation
+
+1. **Not executing**: User reports Dependabot PRs don't actually merge
+2. **No visibility**: No way to see queue status in GitHub UI
+3. **Single queue**: Only one queue configured; may need more for parallel tracks
+
+## Merge Protections Settings
+
+### Configuration
+
+```yaml
+merge_protections_settings:
+  reporting_method: check-runs
+  auto_merge_conditions: true
+```
+
+### Options Explained
+
+**reporting_method: check-runs**
+
+- Reports Mergify status as a GitHub check run (appears in PR checks)
+- Alternative: `pull-request-comment` (posts comments on PR)
+- Current choice is good for CI/CD integration
+
+**auto_merge_conditions: true**
+
+- When enabled: Mergify automatically retries merge if conditions later become true
+- When false: Mergify only attempts merge immediately when rule conditions met
+- Current choice allows recovery if checks are flaky
+- **Trade-off**: May cause unexpected merges if not monitored
+
+## Known Issues
+
+### Issue 1: Dependabot Auto-Merge Not Working
+
+**Symptom**: Dependabot PRs don't merge automatically into develop
+
+**Diagnosis**:
+
+1. Label `area:dependencies` - Check if Dependabot is actually applying this label
+2. Check name - Verify actual check name is "All Checks Passed"
+3. Queue - Check Mergify dashboard if queue is receiving items
+4. Token - Verify MERGIFY_TOKEN secret is configured and valid
+
+**How to Debug**:
+
+```bash
+# Check a Dependabot PR's checks
+gh pr view <pr-number> --json statusCheckRollup
+
+# Check PR labels
+gh pr view <pr-number> --json labels
+
+# Check Mergify logs (requires Mergify dashboard access)
+```
+
+**Suspected Causes**:
+
+1. **Check name mismatch** - Mergify looking for "All Checks Passed" but actual check name is different
+2. **Missing label** - Dependabot not automatically applying `area:dependencies`
+3. **Missing/invalid token** - MERGIFY_TOKEN secret not configured
+4. **Queue not processing** - Queue rule defined but not executing
+
+**Recommendation**:
+Change check condition to match actual CI check names using regex or wildcard.
+
+---
+
+### Issue 2: Meta-Agent Sync Double-Merge Attempt
+
+**Symptom**: Meta-agent PR gets auto-merged by workflow, then Mergify may also attempt to merge
+
+**Location**:
+
+- Workflow: `.github/workflows/meta.yml` (~line 200-220)
+- Rule: `.github/mergify.yml` (lines 59-70)
+
+**Problem**:
+
+```yaml
+# In meta.yml workflow:
+gh pr merge --auto --squash \
+  --subject "chore(meta): apply frontmatter..." \
+  "$PR_URL" || true
+
+# PLUS in mergify.yml:
+- name: Auto-merge meta-agent sync on develop
+  conditions: [...]
+  actions:
+    merge:
+      method: squash
+```
+
+**Impact**:
+
+- Redundant configuration
+- Potential race condition
+- Unclear which method actually merges the PR
+- Harder to debug merge failures
+
+**Recommendation**:
+Remove the `gh pr merge --auto` call from meta.yml and let Mergify rule handle it.
+
+---
+
+### Issue 3: ImgBot Auto-Merge Effectiveness Unknown
+
+**Symptom**: Unclear if ImgBot rule is still effective
+
+**Reason**: No ImgBot PRs created recently for testing
+
+**Recommendation**:
+
+- Manually test by checking ImgBot PR if one is created
+- Or create test PR with ImgBot author to verify
+- Document findings
+
+---
+
+## Troubleshooting
+
+### Check if Mergify is Running
+
+1. Look for "Mergify" checks on PR
+2. Check Mergify dashboard at mergify.io
+3. Look for any Mergify comment on PR
+
+### Check if Rule is Matching
+
+1. Review all PR conditions against rule
+2. Common issues:
+   - Label not applied (check `gh pr view <num> --json labels`)
+   - Check name doesn't match exactly
+   - Author mismatch (case-sensitive)
+   - Draft state
+   - Merge conflicts
+
+### Fix Check Name Mismatch
+
+**Current condition**:
+
+```yaml
+check-success=All Checks Passed
+```
+
+**Better options**:
+
+```yaml
+# Match any check containing "All"
+check-success~=All Checks
+
+# Match specific workflow
+check-success=build-and-test / build
+
+# Use Mergify's default (any check passing)
+check-success=All Checks Passed,All required checks passed
+
+# Multiple checks if needed
+check-success=build,test,lint
+```
+
+### Verify Labels are Applied
+
+```bash
+# Check Dependabot configuration
+cat .github/dependabot.yml
+
+# Check what labels Dependabot actually applies to a PR
+gh pr view <pr-number> --json labels
+```
+
+### Check Queue Status
+
+Unfortunately, GitHub doesn't expose queue status in the UI. Options:
+
+1. Access Mergify dashboard (requires login)
+2. Check Mergify's activity logs
+3. Monitor PR for Mergify status checks/comments
+
+## Best Practices
+
+### 1. Always Use Squash Merge
+
+**Why**: Keeps git history clean, one commit per feature/fix
+
+**Configuration**:
+
+```yaml
+merge_method: squash
+```
+
+### 2. Use Queue for Dependency Updates
+
+**Why**: Prevents merge conflicts from parallel merges
+
+**Configuration**:
+
+```yaml
+queue:
+  name: dependabot-develop
+```
+
+### 3. Make Label Application Explicit
+
+**Bad**:
+
+```yaml
+conditions:
+  - author~=dependabot
+  - base=develop
+```
+
+**Good**:
+
+```yaml
+conditions:
+  - author~=dependabot
+  - base=develop
+  - label=area:dependencies
+```
+
+### 4. Use Precise Check Names
+
+**Bad**:
+
+```yaml
+check-success=All Checks Passed
+```
+
+**Good**:
+
+```yaml
+# Run `gh run list` to see actual check names
+check-success=build,test,lint,type-check
+```
+
+### 5. Document Rule Purpose
+
+```yaml
+# Good
+- name: Auto-merge Dependabot dependency updates on develop
+  description: |
+    Automatically merge dependency updates after CI validation.
+    Helps keep dependencies current without manual intervention.
+  conditions: [...]
+```
+
+### 6. Monitor Auto-Merge Effectiveness
+
+Track over time:
+
+- Percentage of PRs that merge automatically
+- Time from PR creation to merge
+- Merge failure reasons
+- False negatives (PRs that should have merged but didn't)
+
+## Improvement Recommendations
+
+### Priority 1: Fix Dependabot Auto-Merge
+
+**Actions**:
+
+1. Identify actual CI check names:
+
+   ```bash
+   # Look at recent PRs to see what checks run
+   gh pr list --state open --json statusCheckRollup
+   ```
+
+2. Update `check-success` condition to match actual check names
+
+3. Verify `area:dependencies` label is applied:
+
+   ```bash
+   cat .github/dependabot.yml
+   # Should include:
+   # labels:
+   #   - area:dependencies
+   ```
+
+4. Verify MERGIFY_TOKEN secret exists and is valid
+
+5. Test with a real Dependabot PR and monitor merge process
+
+**Timeline**: High priority (blocking dependency updates)
+
+---
+
+### Priority 2: Remove Meta-Agent Double-Merge
+
+**Actions**:
+
+1. Remove this from `.github/workflows/meta.yml`:
+
+   ```yaml
+   gh pr merge --auto --squash \
+     --subject "..." \
+     "$PR_URL" || true
+   ```
+
+2. Rely entirely on Mergify rule for meta-agent sync PRs
+
+3. Update PR creation to not request auto-merge:
+
+   ```yaml
+   # Remove --auto flag
+   gh pr create \
+     --base develop \
+     --head "$BRANCH" \
+     --title "chore(meta): automated meta-agent sync" \
+     --label "meta:no-changelog" \
+     --body "$PR_BODY"
+   ```
+
+4. Let Mergify handle the merge via rule
+
+**Benefits**:
+
+- Single source of truth (Mergify)
+- Easier to debug
+- No race conditions
+- Cleaner workflow code
+
+**Timeline**: Medium priority
+
+---
+
+### Priority 3: Standardize Check Names
+
+**Actions**:
+
+1. Document actual CI check names used in workflows
+
+2. Create matrix of rule-to-check mappings:
+
+   ```
+   Dependabot rule -> expects: "All Checks Passed"
+   ImgBot rule     -> expects: "All Checks Passed"
+   Meta rule       -> expects: "All Checks Passed"
+   
+   Actual checks in CI: ??
+   ```
+
+3. Update all rules to match actual check names
+
+4. Add CI check name validation to branch protection rules
+
+**Timeline**: Medium priority
+
+---
+
+### Priority 4: Implement Mergify Monitoring
+
+**Actions**:
+
+1. Create workflow to monitor Mergify status:
+   - Track merge success rate
+   - Log merge failures
+   - Alert on unusual patterns
+
+2. Add Mergify dashboard link to docs
+
+3. Set up weekly Mergify health report
+
+**Timeline**: Low priority (nice to have)
+
+---
+
+### Priority 5: Consider Multiple Queues
+
+**When**: If we have multiple competing merge tracks
+
+**Current**: Only `dependabot-develop` queue
+
+**Future options**:
+
+```yaml
+queue_rules:
+  - name: dependabot-develop
+    merge_method: squash
+  - name: feature-updates
+    merge_method: squash
+  - name: hotfixes-main
+    merge_method: squash
+```
+
+**Timeline**: Low priority (not needed yet)
+
+---
+
+## Related Files
+
+- `.github/mergify.yml` - Main configuration
+- `.github/workflows/meta.yml` - Meta-agent PR creation
+- `.github/workflows/flaky-test-detection.yml` - Mergify GHA usage
+- `.github/dependabot.yml` - Dependabot label configuration
+- `.github/workflows/main-branch-guard.yml` - Branch protection
+- `.github/BRANCHING_STRATEGY.md` - Merge workflow discipline
+
+## References
+
+- [Mergify Documentation](https://docs.mergify.io/)
+- [GitHub PR Conditions](https://docs.mergify.io/conditions/)
+- [Queue Rules Guide](https://docs.mergify.io/merge-queue/)
+- [Troubleshooting Guide](https://docs.mergify.io/faq/)
+
+## Change Log
+
+| Date | Author | Changes |
+|------|--------|---------|
+| 2026-07-24 | Audit | Initial comprehensive audit and documentation |