Skip to content

PR: Frontmatter Validation – Repair Incorrect or Missing Markdown Frontmatter in Workflow Docs #100

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ashleyshaw merged 2 commits into from
Nov 17, 2025
Merged

PR: Frontmatter Validation – Repair Incorrect or Missing Markdown Frontmatter in Workflow Docs #100

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7d32f65
fix: update frontmatter to comply with validation schema
claude Nov 17, 2025
771215e
chore: update .gitignore to ignore node_modules in subdirectories
claude Nov 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 21 additions & 10 deletions .github/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
description: "Central hub for all shared GitHub templates, Copilot instructions, workflow automation, labeling systems, and community health files across the LightSpeed WordPress organisation"
version: "3.0"
last_updated: "2025-10-24"
file_type: "documentation"
owners:
- LightSpeed Team
tags:
Expand All @@ -13,16 +14,26 @@ tags:
- labeling
- ai
references:
- ./custom-instructions.md
- ./agents/agent.md
- ./prompts/prompts.md
- ./chatmodes/chatmodes.md
- ../AGENTS.md
- ./automation/AUTOMATION_GOVERNANCE.md
- ./automation/labels.yml
- ./automation/labeler.yml
- ./instructions/coding-standards.instructions.md
- ../CONTRIBUTING.md
- path: ./custom-instructions.md
description: Custom instructions for AI agents
- path: ./agents/agent.md
description: Main agents index
- path: ./prompts/prompts.md
description: Prompts index
- path: ./chatmodes/chatmodes.md
description: Chatmodes index
- path: ../AGENTS.md
description: Organization-wide agents documentation
- path: ./automation/AUTOMATION_GOVERNANCE.md
description: Automation governance policies
- path: ./automation/labels.yml
description: Label definitions
- path: ./automation/labeler.yml
description: Labeler configuration
- path: ./instructions/coding-standards.instructions.md
description: Coding standards instructions
- path: ../CONTRIBUTING.md
description: Contribution guidelines
---
LightSpeed Organisation .github Community Health Repository
==========================================================
Expand Down
2 changes: 1 addition & 1 deletion .github/agents/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ author: "LightSpeed"
maintainer: "Ash Shaw"
description: "Comprehensive directory of all GitHub automation agents, their workflows, tests, and related resources."
tags: ["lightspeed","agents","automation","workflows","github-actions"]
type: "documentation"
file_type: "documentation"
---

## 🚀 Quick Start
Expand Down
14 changes: 9 additions & 5 deletions .github/reporting/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,17 @@ author: 'LightSpeed'
maintainer: 'Ash Shaw'
description: 'Central location for generated reports, metrics outputs, and analytics artifacts across LightSpeed repositories.'
tags: ['reporting', 'metrics', 'analytics', 'artifacts', 'automation']
type: 'documentation'
file_type: 'documentation'
category: 'infrastructure'
references:
- '../metrics/README.md'
- '../metrics/metrics.config.json'
- '../agents/metrics.agent.md'
- '../../docs/BRANDING.md'
- path: '../metrics/README.md'
description: 'Metrics collection configuration and documentation'
- path: '../metrics/metrics.config.json'
description: 'Master configuration for metrics collection'
- path: '../agents/metrics.agent.md'
description: 'Metrics agent specification'
- path: '../../docs/BRANDING.md'
description: 'Branding guidelines and automation'
---

# LightSpeed Reporting Directory
Expand Down
2 changes: 1 addition & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Dependencies
/node_modules
node_modules/
/vendor

# Build directories
Expand Down
31 changes: 20 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,28 @@ title: "LightSpeed Community Health & Automation Repository"
description: "Central hub for LightSpeed organization's community health files, automation standards, label management, governance documentation, and org-wide resources for GitHub usage and contribution."
version: "2.0"
last_updated: "2025-10-24"
file_type: "documentation"

@coderabbitai coderabbitai Bot Nov 17, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

Critical: Frontmatter validation error on root README.md blocks merge.

Pipeline validation fails on the file_type field with error: tag "file_type" must be string. This is a critical blocker for the root repository README.

Root documentation files are essential; validation must pass before merge. The error appears across all files in this PR, suggesting a systemic schema issue rather than a per-file problem.

Required action: Inspect the frontmatter schema definition (.github/automation/front-matter.schema.json or equivalent) to determine:

  1. Expected type for file_type field (string, array, object, or enum)
  2. Any allowed values or patterns
  3. Whether the schema definition needs updating or the field values need correction

Use the verification script provided in .github/agents/README.md comment to inspect the schema.

I need to verify this critical validation error claim. Let me search the codebase for the schema definition and check the actual frontmatter:


---

🏁 Script executed:

```shell
#!/bin/bash
# Find schema files related to frontmatter validation
find .github -name "*schema*" -o -name "*frontmatter*" | head -20

Length of output: 811

🏁 Script executed:

#!/bin/bash
# Check the actual README.md frontmatter (first 50 lines)
head -50 README.md

Length of output: 2951

🏁 Script executed:

#!/bin/bash
# Search for validation rules or pipeline configuration
find .github -type f \( -name "*.yml" -o -name "*.yaml" -o -name "*.json" \) | xargs grep -l "file_type" 2>/dev/null | head -10

Length of output: 0

🏁 Script executed:

#!/bin/bash
# Look for any validation scripts or automation agents
find .github/agents -type f -name "*.md" -o -name "*.js" -o -name "*.ts" 2>/dev/null | head -10

Length of output: 509

I need to inspect the schema definitions and validation workflow to understand the actual validation rule:


---

🏁 Script executed:

```shell
#!/bin/bash
# Inspect the frontmatter schema definitions
echo "=== /github/automation/front-matter.schema.json ==="
cat .github/automation/front-matter.schema.json | head -100

Length of output: 473

🏁 Script executed:

#!/bin/bash
# Inspect the alternative schema file
echo "=== .github/automation/schemas/frontmatter.schema.json ==="
cat .github/automation/schemas/frontmatter.schema.json | head -100

Length of output: 541

🏁 Script executed:

#!/bin/bash
# Check the frontmatter validation workflow
echo "=== .github/workflows/frontmatter-validation.yml ==="
cat .github/workflows/frontmatter-validation.yml | head -80

Length of output: 1990

🏁 Script executed:

#!/bin/bash
# Verify all 9 reference paths exist in the repository
echo "Checking reference paths from README.md:"
paths=(
  ".github/custom-instructions.md"
  ".github/agents/agent.md"
  ".github/prompts/prompts.md"
  ".github/chatmodes/chatmodes.md"
  "AGENTS.md"
  "DOCS.md"
  "CONTRIBUTING.md"
  "GOVERNANCE.md"
  "AUTOMATION_GOVERNANCE.md"
)

for p in "${paths[@]}"; do
  if [ -f "$p" ]; then
    echo "✓ $p"
  else
    echo "✗ $p (NOT FOUND)"
  fi
done

Length of output: 256

I found critical issues. Let me check the npm validation code and the frontmatter directory structure:


---

🏁 Script executed:

```shell
#!/bin/bash
# Check if schemas/frontmatter directory exists and what files are there
ls -la schemas/frontmatter/ 2>/dev/null || echo "schemas/frontmatter/ not found at root"

Length of output: 629

🏁 Script executed:

#!/bin/bash
# Look for validation code that might define file_type rules
find . -name "*.js" -o -name "*.ts" | xargs grep -l "file_type" 2>/dev/null | head -10

Length of output: 323

🏁 Script executed:

#!/bin/bash
# Check if AUTOMATION_GOVERNANCE.md exists anywhere or under different paths
find . -name "*AUTOMATION*" -o -name "*governance*" -iname "*automation*" 2>/dev/null | grep -i md

Length of output: 73

🏁 Script executed:

#!/bin/bash
# Search for any reference to the missing file in the codebase
rg "AUTOMATION_GOVERNANCE" -i 2>/dev/null | head -20

Length of output: 2367

Found the issue! The file exists but the reference path is wrong. Let me check the actual schema and validation logic:


---

🏁 Script executed:

```shell
#!/bin/bash
# Check the comprehensive schema in schemas/frontmatter/
echo "=== schemas/frontmatter/frontmatter.schema.json (first 200 lines) ==="
head -200 schemas/frontmatter/frontmatter.schema.json

Length of output: 9233

🏁 Script executed:

#!/bin/bash
# Check the validation code
echo "=== schemas/frontmatter/validate.js ==="
cat schemas/frontmatter/validate.js | head -150

Length of output: 3935

🏁 Script executed:

#!/bin/bash
# Check the schema tests for file_type
echo "=== Check tests for file_type ==="
grep -n "file_type" schemas/frontmatter/tests/schema.test.js -C 3

Length of output: 2052

Let me verify if "documentation" is a valid file_type value in the schema:


---

🏁 Script executed:

```shell
#!/bin/bash
# Search for all defined file_type const values in schema
echo "=== All file_type const values in schema ==="
grep -o '"const": "[^"]*"' schemas/frontmatter/frontmatter.schema.json | sort | uniq

Length of output: 532

🏁 Script executed:

#!/bin/bash
# Check if "documentation" is mentioned anywhere in the schema
grep -i "documentation" schemas/frontmatter/frontmatter.schema.json

Length of output: 971

Fix broken reference path in README.md frontmatter.

The reference path "AUTOMATION_GOVERNANCE.md" (line 26) should be "./.github/automation/AUTOMATION_GOVERNANCE.md" to correctly resolve to the actual file location. The file exists but the relative path in the frontmatter references section is incorrect.

🤖 Prompt for AI Agents 
In README.md around lines 6 to 6, the frontmatter reference path is
incorrect—replace "AUTOMATION_GOVERNANCE.md" with the correct relative path
"./.github/automation/AUTOMATION_GOVERNANCE.md" so the frontmatter links resolve
to the actual file location.

maintainer: "LightSpeed Team"
tags: ["community-health", "automation", "governance", "labels", "workflows", "ai", "copilot"]
ai_references:
- ".github/custom-instructions.md"
- ".github/agents/agent.md"
- ".github/prompts/prompts.md"
- ".github/chatmodes/chatmodes.md"
- "AGENTS.md"
related_docs:
- "DOCS.md"
- "CONTRIBUTING.md"
- "GOVERNANCE.md"
- "AUTOMATION_GOVERNANCE.md"
references:
- path: ".github/custom-instructions.md"
description: "Custom instructions for AI agents"
- path: ".github/agents/agent.md"
description: "Main agents index"
- path: ".github/prompts/prompts.md"
description: "Prompts index"
- path: ".github/chatmodes/chatmodes.md"
description: "Chatmodes index"
- path: "AGENTS.md"
description: "Organization-wide agents documentation"
- path: "DOCS.md"
description: "Documentation index"
- path: "CONTRIBUTING.md"
description: "Contribution guidelines"
- path: "GOVERNANCE.md"
description: "Governance policies"
- path: "AUTOMATION_GOVERNANCE.md"
description: "Automation governance policies"
---

# 🏠 LightSpeed Community Health & Automation Repository
Expand Down
18 changes: 12 additions & 6 deletions docs/BRANDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,18 @@ tags: ['branding', 'automation', 'documentation', 'badges', 'emojis', 'workflows
file_type: 'documentation'
category: 'docs'
references:
- '../.github/automation/badges.schema.yml'
- '../.github/automation/emoji.schema.yml'
- '../.github/automation/footers.yml'
- '../.github/automation/front-matter.schema.json'
- '../.github/workflows/branding.yml'
- '../.github/agents/branding.agent.js'
- path: '../.github/automation/badges.schema.yml'
description: 'Badge schema configuration'
- path: '../.github/automation/emoji.schema.yml'
description: 'Emoji schema configuration'
- path: '../.github/automation/footers.yml'
description: 'Footer templates configuration'
- path: '../.github/automation/front-matter.schema.json'
description: 'Frontmatter schema definition'
- path: '../.github/workflows/branding.yml'
description: 'Branding automation workflow'
- path: '../.github/agents/branding.agent.js'
description: 'Branding agent implementation'
Comment on lines 10 to +24

@coderabbitai coderabbitai Bot Nov 17, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Quote inconsistency in frontmatter file_type field; standardize across all documentation files.

Line 10 uses single quotes: file_type: 'documentation', while other files use double quotes: file_type: "documentation". YAML accepts both, but consistency improves maintainability and may prevent schema validation issues if the validator is strict about quote style.

Standardize to double quotes across all documentation files (.github/agents/README.md, .github/README.md, .github/reporting/README.md, README.md, and docs/BRANDING.md) for consistency.

Apply this diff:

-file_type: 'documentation'
+file_type: "documentation"

Alternatively, if double quotes are enforced by schema, ensure all files use them.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
file_type: 'documentation'
category: 'docs'
references:
- '../.github/automation/badges.schema.yml'
- '../.github/automation/emoji.schema.yml'
- '../.github/automation/footers.yml'
- '../.github/automation/front-matter.schema.json'
- '../.github/workflows/branding.yml'
- '../.github/agents/branding.agent.js'
- path: '../.github/automation/badges.schema.yml'
description: 'Badge schema configuration'
- path: '../.github/automation/emoji.schema.yml'
description: 'Emoji schema configuration'
- path: '../.github/automation/footers.yml'
description: 'Footer templates configuration'
- path: '../.github/automation/front-matter.schema.json'
description: 'Frontmatter schema definition'
- path: '../.github/workflows/branding.yml'
description: 'Branding automation workflow'
- path: '../.github/agents/branding.agent.js'
description: 'Branding agent implementation'
file_type: "documentation"
category: 'docs'
references:
- path: '../.github/automation/badges.schema.yml'
description: 'Badge schema configuration'
- path: '../.github/automation/emoji.schema.yml'
description: 'Emoji schema configuration'
- path: '../.github/automation/footers.yml'
description: 'Footer templates configuration'
- path: '../.github/automation/front-matter.schema.json'
description: 'Frontmatter schema definition'
- path: '../.github/workflows/branding.yml'
description: 'Branding automation workflow'
- path: '../.github/agents/branding.agent.js'
description: 'Branding agent implementation'
🤖 Prompt for AI Agents 
In docs/BRANDING.md around lines 10 to 24 the frontmatter uses single quotes for
file_type (file_type: 'documentation'); update this to use double quotes
(file_type: "documentation") to match the project's convention and the other
listed docs (.github/agents/README.md, .github/README.md,
.github/reporting/README.md, README.md). Make the same replacement in those
files if any still use single quotes, and re-run a quick search (e.g., grep) to
ensure all documentation frontmatter file_type fields consistently use double
quotes.

---

# Branding Agent — Spec (develop)
Expand Down
Loading