Skip to content

fix(docs): remove prohibited references: frontmatter field from 9 READMEs#527

Merged
ashleyshaw merged 12 commits into
developfrom
feat/readme-compliance-fixes
May 28, 2026
Merged

fix(docs): remove prohibited references: frontmatter field from 9 READMEs#527
ashleyshaw merged 12 commits into
developfrom
feat/readme-compliance-fixes

Conversation

@ashleyshaw
Copy link
Copy Markdown
Member

Summary

  • Removes the prohibited references: frontmatter field from 9 README files (CLAUDE.md explicitly forbids this field — use inline links or a ## Cross-References section instead)
  • Adds missing required frontmatter fields (owners, status, stability, domain) to files that were incomplete
  • Removes 13 duplicate footer blocks appended to root README.md by a prior automation run
  • Fixes scripts/README.md double --- separator and adds missing file_type, title, domain, stability, status fields

Files changed

File Changes
README.md Remove references:, add owners/status, strip 13 duplicate footers
.github/README.md Remove references:, add status
.github/agents/README.md Remove references:, add owners/status
.github/instructions/README.md Remove references:, add owners/status
.github/metrics/README.md Remove references:, add owners/status/stability/domain, update last_updated
.github/schemas/README.md Remove references:, add owners/status
.schemas/README.md Remove references:, add owners/status
profile/README.md Remove references:, add status
scripts/README.md Remove references:, fix double ---, add file_type/title/domain/stability/status

Notes

  • All cross-references from the removed references: blocks already exist as inline links in each file's body — no information lost
  • scripts/README.md had a structural bug (two consecutive --- delimiters after the frontmatter block) that is now fixed
  • The footer duplication in README.md was caused by repeated automated footer injection

Test plan

  • grep -r '^references:' . --include="README.md" | grep -v node_modules returns no results
  • npm run validate:frontmatter passes
  • npm run lint:md passes on all changed files
  • Root README.md renders cleanly in GitHub preview (no duplicate footers)

https://claude.ai/code/session_01Ukh7BPcSJQcr3zwA6QqqCV


Generated by Claude Code

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 28, 2026

Review Change Stack

Warning

Review limit reached

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

More reviews will be available in 19 minutes and 22 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

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.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: df697bde-bacb-4b19-826d-e6719822f80b

📥 Commits

Reviewing files that changed from the base of the PR and between 2efbe30 and 5fc8189.

⛔ Files ignored due to path filters (1)
  • .schemas/README.md is excluded by !.schemas/**
📒 Files selected for processing (12)
  • .github/README.md
  • .github/agents/README.md
  • .github/instructions/README.md
  • .github/metrics/README.md
  • .github/schemas/README.md
  • .lycheeignore
  • CHANGELOG.md
  • README.md
  • docs/MIGRATION.md
  • profile/README.md
  • scripts/README.md
  • tests/README.md
📝 Walkthrough

Walkthrough

Repository-wide metadata governance restructure: all nine README files transitioned to a standardised frontmatter schema by removing the deprecated references: field and introducing owners, domain, stability, and status; PR template link paths corrected; migration documentation expanded; link checker rules enhanced.

Changes

Metadata Governance and Documentation Restructure

Layer / File(s) Summary
Frontmatter metadata standardization across repository
.github/README.md, .github/agents/README.md, .github/instructions/README.md, .github/metrics/README.md, .github/schemas/README.md, README.md, profile/README.md, scripts/README.md
All nine README files updated to a consistent metadata schema: version and last_updated incremented to 2026-05-28; deprecated references: field removed; new fields owners, domain, stability, and status added or reorganised; existing maintainer and author values retained.
Documentation content and link corrections
.github/README.md, README.md, profile/README.md, scripts/README.md
Reference section removed from .github/README.md; contributor instruction links updated to consolidated plugin-structure.instructions.md paths; PR template copy commands corrected from .github/PULL_REQUEST_TEMPLATE.md to .github/pull_request_template.md; footer blocks deduplicated and replaced with concise attribution and issue/discussion prompts; relative paths and social links adjusted in profile README.
CI configuration and migration documentation
.lycheeignore, CHANGELOG.md, docs/MIGRATION.md
.lycheeignore expanded to exclude social platforms and LightSpeed organisational domains; CHANGELOG.md records frontmatter governance corrections; docs/MIGRATION.md extended with comprehensive "Portable AI Plugin Restructure Migrations" section documenting completed migrations, required link updates, pending items, and asset placement rules.

Sequence Diagram(s)

No sequence diagrams generated. The changes are primarily metadata standardisation, documentation updates, and link corrections—none involve multi-component interactions, API flows, or control flow changes that would benefit from sequencing visualisation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

  • lightspeedwp/.github#100: Frontmatter governance and references field validation work directly connected to this PR's metadata cleanup.
  • lightspeedwp/.github#415: Parallel restructure effort updating .github/README.md instruction paths and metadata as part of portable AI plugin restructure closeout.
  • lightspeedwp/.github#53: PR template link corrections in this PR align with template file edits adding risk assessment and testing sections.

Suggested labels

type:documentation, documentation

Suggested reviewers

  • krugazul
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Description check ❓ Inconclusive The PR description covers the key changes, affected files, and rationale, though it lacks detailed risk assessment and testing instructions as required by the template. Expand the description to include a formal Risk Assessment section with Risk Level, Potential Impact, and Mitigation Steps, plus detailed 'How to Test' instructions beyond the test plan checklist.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title directly and concisely describes the main change: removing a prohibited references: frontmatter field from 9 README files.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/readme-compliance-fixes

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 and usage tips.

@github-actions github-actions Bot added status:needs-review Awaiting code review type:feature Feature or enhancement priority:normal Default priority area:documentation Docs & guides area:scripts Scripts & tooling lang:md Markdown content/docs type:chore Chore / small hygiene change type:bug Bug or defect meta:needs-changelog Requires a changelog entry before merge labels May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 10

Recommendations

  • Ready to proceed pending human review

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

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

Code Review

This pull request removes the prohibited references: frontmatter field from several README files across the repository to comply with governance rules, adds missing required frontmatter fields (such as owners, status, stability, and domain), and cleans up duplicate footer blocks in the root README.md. Feedback on these changes includes addressing a duplicate last_updated frontmatter key in .github/metrics/README.md and documenting migration maps and notes in a central /docs/MIGRATION.md file to ensure contributors can easily follow migration rules.

Comment thread .github/metrics/README.md Outdated
Comment on lines +13 to +14
status: "active"
last_updated: "2026-05-28"
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.

medium

The frontmatter key 'last_updated' is defined twice in this file (on line 4 and line 14). Duplicate keys in YAML frontmatter can cause parsing issues. Please remove the duplicate key.

Suggested change
status: "active"
last_updated: "2026-05-28"
status: "active"

Comment thread .schemas/README.md
authors: ["Codex"]
license: "GPL-3.0"
tags: ["schemas", "ai-ops", "plugin-restructure"]
owners: ["LightSpeed Team"]
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.

medium

To ensure contributors can follow the migration rules mentioned in this README, please document the migration maps and notes in a central '/docs/MIGRATION.md' file.

References
  1. Document migration maps and notes in a central '/docs/MIGRATION.md' file to ensure contributors can follow migration rules mentioned in README files across the repository.

Comment thread .github/agents/README.md
authors: ["Codex"]
license: "GPL-3.0"
tags: ["agents", "github-boundary", "ai-ops"]
owners: ["LightSpeed Team"]
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.

medium

To ensure contributors can follow the migration rules mentioned in this README, please document the migration maps and notes in a central '/docs/MIGRATION.md' file.

References
  1. Document migration maps and notes in a central '/docs/MIGRATION.md' file to ensure contributors can follow migration rules mentioned in README files across the repository.

authors: ["Codex"]
license: "GPL-3.0"
tags: ["instructions", "github-boundary", "ai-ops"]
owners: ["LightSpeed Team"]
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.

medium

To ensure contributors can follow the migration rules mentioned in this README, please document the migration maps and notes in a central '/docs/MIGRATION.md' file.

References
  1. Document migration maps and notes in a central '/docs/MIGRATION.md' file to ensure contributors can follow migration rules mentioned in README files across the repository.

@github-actions github-actions Bot removed type:feature Feature or enhancement type:chore Chore / small hygiene change labels May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 10

Recommendations

  • Ready to proceed pending human review

@github-actions github-actions Bot added the type:feature Feature or enhancement label May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 10

Recommendations

  • Ready to proceed pending human review

@github-actions github-actions Bot removed the type:feature Feature or enhancement label May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 10

Recommendations

  • Ready to proceed pending human review

@github-actions github-actions Bot added the type:feature Feature or enhancement label May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 11

Recommendations

  • Ready to proceed pending human review

@github-actions github-actions Bot removed the type:feature Feature or enhancement label May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 11

Recommendations

  • Ready to proceed pending human review

@ashleyshaw ashleyshaw marked this pull request as ready for review May 28, 2026 15:55
@chatgpt-codex-connector
Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@github-actions github-actions Bot added type:feature Feature or enhancement and removed type:feature Feature or enhancement labels May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 12

Recommendations

  • Ready to proceed pending human review

@coderabbitai coderabbitai Bot requested a review from krugazul May 28, 2026 16:09
@coderabbitai coderabbitai Bot added the type:documentation Documentation label May 28, 2026
ashleyshaw and others added 6 commits May 28, 2026 18:29
…ked URLs

Removes two auto-generated duplicate footer blocks from .github/README.md
(added by readme-regen workflow) that contained stale lsx-demo-theme links.
Adds .lycheeignore to exclude Twitter/X and LinkedIn from lychee link checks —
both domains block automated HTTP clients and cause spurious lint-and-links
failures.

https://claude.ai/code/session_01Ukh7BPcSJQcr3zwA6QqqCV
Adds LightSpeed organisation external domains (lightspeedwp.agency, lsx.design,
lightspeedwp.github.io, lsdev.biz) to the lychee exclusion list. These are
first-party external websites that may have transient availability issues or
redirect chains that cause false-positive lychee failures in CI.

https://claude.ai/code/session_01Ukh7BPcSJQcr3zwA6QqqCV
Documents completed migrations (.github/instructions/ → instructions/,
agents/, schemas/), the pending plugin-structure.instructions.md move,
and a quick-reference file placement table so contributors can follow
the governance rules without hunting through CLAUDE.md.

Bumps version to v0.2.3, last_updated 2026-05-28.

https://claude.ai/code/session_01Ukh7BPcSJQcr3zwA6QqqCV
Lychee regex-matches each ignore line as a substring. The previous patterns
used trailing slashes (e.g. https://lightspeedwp.agency/) which did not match
bare domain URLs (https://lightspeedwp.agency) in profile/README.md badge
links. Drop trailing slashes so each pattern covers both the root URL and all
sub-paths.

https://claude.ai/code/session_01Ukh7BPcSJQcr3zwA6QqqCV
@ashleyshaw ashleyshaw force-pushed the feat/readme-compliance-fixes branch from 77fade2 to b1d1920 Compare May 28, 2026 16:29
@github-actions github-actions Bot added type:feature Feature or enhancement area:tests Test suites & harnesses type:documentation Documentation and removed type:documentation Documentation documentation labels May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 13

Recommendations

  • Ready to proceed pending human review

…e exclusion

Angle-bracket wrapping (<https://...>) is not valid in lychee's .lycheeignore —
each line must be a plain URL or regex. The angle brackets prevented every
ignore pattern from matching, causing lychee to attempt all external URLs.

Also adds https://github.com/lightspeedwp/lsx-demo-theme to cover the
auto-generated readme-regen footer in scripts/README.md which links to that
repo's contributors page.

https://claude.ai/code/session_01Ukh7BPcSJQcr3zwA6QqqCV
@github-actions github-actions Bot removed type:feature Feature or enhancement type:documentation Documentation labels May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 13

Recommendations

  • Ready to proceed pending human review

@github-actions github-actions Bot added the type:feature Feature or enhancement label May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 13

Recommendations

  • Ready to proceed pending human review

@github-actions github-actions Bot removed the type:feature Feature or enhancement label May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 13

Recommendations

  • Ready to proceed pending human review

@ashleyshaw ashleyshaw force-pushed the feat/readme-compliance-fixes branch from 7e81917 to 5fc8189 Compare May 28, 2026 16:47
@github-actions github-actions Bot added the type:feature Feature or enhancement label May 28, 2026
@github-actions
Copy link
Copy Markdown
Contributor

🔍 Reviewer Summary for PR #527

CI Status:success
Files changed: 13

Recommendations

  • Ready to proceed pending human review

@ashleyshaw ashleyshaw merged commit a5998cc into develop May 28, 2026
14 checks passed
@ashleyshaw ashleyshaw deleted the feat/readme-compliance-fixes branch May 28, 2026 16:49
ashleyshaw pushed a commit that referenced this pull request May 28, 2026
#527

.lychee.toml sets scheme = ["https", "http"] so lychee only checks
external URLs, not relative file paths. This prevents false-positive
failures when linked README files are planned-but-not-yet-created.

CHANGELOG updated to document .lycheeignore addition and MIGRATION.md
content from PR #527.

https://claude.ai/code/session_01Ukh7BPcSJQcr3zwA6QqqCV
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:documentation Docs & guides area:scripts Scripts & tooling area:tests Test suites & harnesses lang:md Markdown content/docs meta:needs-changelog Requires a changelog entry before merge priority:normal Default priority status:needs-review Awaiting code review type:bug Bug or defect type:feature Feature or enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants