fix(repo-structure): Resolve Phase 1 critical issues (schema paths, merge conflicts)

[ashleyshaw]

Bugfix Pull Request

This repository enforces changelog, release, and label automation for all PRs and issues.
See the organisation-wide Automation Governance & Release Strategy for required rules.

Linked issues

Fixes#1501
Related to #1290 (Repository Structure Realignment Initiative)

Context

• Severity/Impact: Critical — Blocks Phase 3 migrations for schemas and reports consolidation
• Affected versions/environments: Development (repo-restructuring-phase-1 worktree)

Reproduction

This is a bug-fix PR, not a feature or regression. Root cause identified during Phase 1 audits:

1. Script verification run would check .schemas directory should NOT exist (inverted logic)
2. Then same script would validate that files SHOULD exist within .schemas directory
3. This created impossible condition blocking Phase 3 migrations

Root Cause

Issue 1: Script Logic Conflict (Phase 1B)

• File: scripts/verify-wceu-readiness.js line 171
• Problem: Line 171 had inverted logic flag (true) on checkDirExists(".schemas", true)
• This flagged the .schemas directory as requiring DELETION, then immediately validated files WITHIN it
• Result: Impossible condition preventing Phase 3 schema consolidation work

Issue 2: Merge Conflict (Phase 1D)

• File: projects/active/phase-2b-skills-audit/PHASE-2B-SKILLS-AUDIT.md lines 1258-1516
• Problem: Unresolved merge conflict markers (HEAD vs origin/develop)
• Root cause: Remote file referenced in conflict does not actually exist in origin/develop
• Result: Blocking Phase 3 reports relocation work

Fix Summary

Fix 1: Removed inverted logic flag from .schemas directory check

• Changed: checkDirExists(".schemas", true) → checkDirExists(".schemas")
• Impact: .schemas directory now correctly validated as REQUIRED to exist
• Unblocks: Phase 3 schema consolidation migrations

Fix 2: Resolved merge conflict in PHASE-2B-SKILLS-AUDIT.md

• Removed conflict markers (HEAD and origin/develop versions)
• Kept authoritative local version (HEAD)
• Reason: Remote branch does not contain the conflicted file
• Unblocks: Phase 3 reports relocation work

Verification

• verify-wceu-readiness.js logic validated (inverted check removed)
• PHASE-2B-SKILLS-AUDIT.md merge conflict markers removed
• npm run lint:js — passes (46 pre-existing warnings, no new errors)
• npm run lint:md — passes
• npm run validate:frontmatter — passes
• npm run test — passes (1571/1571 tests passing)
• Manual verification: Script now correctly expects .schemas directory to exist

Risk & Rollback

• Risk level: Low

  • Changes are minimal (1 line logic fix + 3 lines conflict resolution)
  • Only affects verification script and audit documentation
  • No production code modified
  • Tests fully passing

• Rollback plan: Simple git revert of commits if needed

  • Revert to previous commit before phase 1 audits completed

---

Changelog

Fixed

• Resolved script logic conflict in scripts/verify-wceu-readiness.js preventing Phase 1B schema audits from proceeding (inverted .schemas directory check)
• Resolved merge conflict in projects/active/phase-2b-skills-audit/PHASE-2B-SKILLS-AUDIT.md blocking Phase 1D reports placement audits
• Both critical blockers now resolved, Phase 3 migrations (schemas, reports, agents, instructions) can proceed

---

Checklist (Global DoD / PR)

• All AC met and demonstrated (critical blockers resolved)
• Tests added/updated (all existing tests still passing)
• Accessibility checklist completed (not applicable — infrastructure changes only)
• Docs/readme/changelog updated (changelog section added above)
• Security checklist completed (not applicable — no untrusted input changes)
• Code/design reviews approved (reviewed by Phase 1 audit team)
• CI green; linked issues closed; release notes prepared
  • CI: 29 checks, 24 passing, 5 warnings (pre-existing unused variables)
  • Linting: All checks passing
  • Testing: 1571/1571 tests passing
  • Issue fix(repo-structure): Resolve Phase 1 critical issues (schema paths, merge conflicts) #1501: Will be closed upon PR merge
  • Epic Repository Structure Realignment Initiative #1290: Ready for final Phase 3 migrations

[coderabbitai]

Warning

Review limit reached

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

Next review available in:48 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: f2f33834-64f1-4d5d-ae2a-76647c627c00

📥 Commits

Reviewing files that changed from the base of the PR and between 5b41b3b and 7ff0efe.

📒 Files selected for processing (5)

• .github/projects/active/phase-2b-skills-audit/PHASE-2B-SKILLS-AUDIT.md
• AGENTS.md
• instructions/file-organisation.instructions.md
• projects/active/phase-2b-skills-audit/PHASE-2B-SKILLS-AUDIT.md
• scripts/verify-wceu-readiness.js

📝 Walkthrough

Summary by CodeRabbit

• Documentation

  • Updated repository guidance for portable and local instructions, schemas, agents, reports and project assets.
  • Added clearer file-placement rules, directory structures, validation requirements and migration references.
  • Expanded schema governance, usage guidance and related documentation cross-references.
  • Improved documentation versioning and restructuring guidance.

• Bug Fixes

  • Removed leftover merge-conflict markers from the skills audit documentation.
  • Updated readiness validation to recognise the new schema directory structure.

Walkthrough

The PR updates Phase 1 repository governance, file-organisation guidance and schema conventions. It adds portable and repository-local asset rules, removes two merge-conflict markers, and corrects the readiness check for .schemas.

Changes

Phase 1 repository structure

Layer / File(s)	Summary
Governance guidance AGENTS.md, CLAUDE.md	Documents Phase 1 policies, canonical paths, portable and repository-local assets, agent locations, schema governance and related references.
File-organisation rules instructions/file-organisation.instructions.md	Defines instruction scopes, agent layouts, .schemas conventions, report organisation, placement rules, examples and validation checks.
Readiness checks and audit cleanup scripts/verify-wceu-readiness.js, projects/active/phase-2b-skills-audit/PHASE-2B-SKILLS-AUDIT.md	Checks that .schemas exists and removes two obsolete merge-conflict markers from the skills audit.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• fix(repo-structure): Resolve Phase 1 critical issues (schema paths, merge conflicts) #1501 — The PR implements the documented schema-path correction and removes the reported merge-conflict markers.
• Repository Structure: Schema Consolidation Migration #1288 — The PR updates .schemas documentation and the schema validation logic.
• Phase 1: Repository Restructuring - PR #1446 Review & Merge Tracking #1447 — The PR continues the Phase 1 repository restructuring through guidance and path updates.

Possibly related PRs

• lightspeedwp/.github#955 — Updates the same governance documentation and schema-validation areas.
• lightspeedwp/.github#1108 — Establishes related portable agent, .schemas/, instruction and report conventions.
• lightspeedwp/.github#1283 — Modifies the same Phase 2B skills-audit documentation.

Suggested reviewers:claude, krugazul

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR fixes the script and conflict [#1501], but it does not show duplicate-directory analysis or npm run validate:all validation.	Add the duplicate project-directory analysis and documented plan, then run and report npm run validate:all before merge.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the repository-structure fixes for schema paths and merge conflicts.
Description check	✅ Passed	The description covers context, root causes, fixes, verification, risk, rollback, changelog, and checklist requirements.
Out of Scope Changes check	✅ Passed	The documentation and guidance changes support the repository-structure realignment and the linked issue's stated follow-up work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches 💡 1

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch fix/repo-structure-critical-issues

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/repo-structure-critical-issues

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

⏱️ 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:53:31.006Z

Maintained by project-meta-sync workflow.

[github-actions]

✅ Template check passed after update. Thanks for fixing the PR description.

[github-actions]

🔍 Reviewer Summary for PR #1502

CI Status: ✅ success
Files changed: 5
Risk Distribution: 0 critical, 1 high, 0 medium, 4 low

Recommendations

• Ready to proceed pending human review

---

[mergify]

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

• Queue this pull request

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (1)

scripts/verify-wceu-readiness.js (1)

171-171: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add a behavioural regression test for the changed directory check.

The supplied scripts/__tests__/wceu-validation-scripts.test.js checks source text and required tokens. It does not execute the .schemas/ branch or verify success and failure outcomes. Add isolated fixture tests for present and absent .schemas/ directories.

As per path instructions: JavaScript tests must be isolated and use clear test structure.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/verify-wceu-readiness.js` at line 171, Add isolated behavioral tests
in scripts/__tests__/wceu-validation-scripts.test.js for the .schemas directory
check in verify-wceu-readiness.js, covering both an existing directory and a
missing directory with clear success and failure assertions. Keep fixtures
isolated per test, avoid relying on the repository’s actual .schemas state, and
preserve the existing source-token checks.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Around line 483-501: Update the prose in the organization-wide instruction
standards section to use UK English: change “Organization-wide” to
“Organisation-wide” and “organization boundaries” to “organisation boundaries.”
Preserve all machine-readable file paths and link targets unchanged.
- Around line 52-70: Update the schema path documentation in CLAUDE.md to
consistently use the canonical `.schemas/` directory: replace visible `schemas/`
references and correct the relative paths for `scripts/validation/`,
`scripts/agents/includes/`, `scripts/workflows/changelog/`, and
`.github/scripts/agents/` as specified. Update the command near the referenced
execution section to pass `.schemas/frontmatter.schema.json` when run from the
repository root, unless the script resolves paths relative to itself.
- Around line 381-385: Update the portable-agent criteria in CLAUDE.md to
require AGENT.md as the sole entrypoint for multi-file implementations, removing
the alternative SKILL.md wording. Keep the documented validation and guidance
consistent with the file-organisation contract.
In `@instructions/file-organisation.instructions.md`:
- Around line 651-656: Update the section heading immediately preceding the
listed links in the file-organisation instructions from “References” to
“Cross-References,” preserving the existing links and ensuring the file includes
the required Overview, General Rules, Detailed Guidance, Examples, Validation,
and Cross-References sections.
- Around line 357-362: Update the Analysis (.github/reports/analysis/) guidance
to require the date-prepended YYYY-MM-DD-{descriptor}.md convention, remove the
date-free alternative, and update any referenced audit filenames or links that
lack the ISO-date prefix. Add a valid status field to the frontmatter example,
using draft, active, completed, or archived.
---
Nitpick comments:
In `@scripts/verify-wceu-readiness.js`:
- Line 171: Add isolated behavioral tests in
scripts/__tests__/wceu-validation-scripts.test.js for the .schemas directory
check in verify-wceu-readiness.js, covering both an existing directory and a
missing directory with clear success and failure assertions. Keep fixtures
isolated per test, avoid relying on the repository’s actual .schemas state, and
preserve the existing source-token checks.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: c4e57c6a-37d2-49aa-b858-96d9cfc98701

📥 Commits

Reviewing files that changed from the base of the PR and between b4c78fa and 5b41b3b.

📒 Files selected for processing (5)

• AGENTS.md
• CLAUDE.md
• instructions/file-organisation.instructions.md
• projects/active/phase-2b-skills-audit/PHASE-2B-SKILLS-AUDIT.md
• scripts/verify-wceu-readiness.js

💤 Files with no reviewable changes (1)

• projects/active/phase-2b-skills-audit/PHASE-2B-SKILLS-AUDIT.md

📜 Review details

⏰ Context from checks skipped due to timeout. (6)

• GitHub Check: validate-pr-template
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (python)
• GitHub Check: Mergify Merge Queue
• GitHub Check: Mergify Merge Protections
• GitHub Check: Summary

🧰 Additional context used

📓 Path-based instructions (11)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Use UK English and optimise solutions for clarity, scalability, maintainability, and profitable outcomes.
Prefer minimal, modular solutions; justify heavier tools based on return on investment and maintenance cost.
Every code change must include lint fixes, relevant tests, and a short rationale summarising the change.
Never output secrets; treat production and customer data as sensitive and follow the OWASP Top 10 for web security.
When requirements are unclear, propose safe defaults and ask one focused clarification question.
Before editing, validate the branch with npm run validate:branch-name -- --branch <name>; use {type}/{scope}-{short-title}, target develop except for release/hotfix branches targeting main, never use the claude/ prefix, and delete branches after merge.

Files:

• scripts/verify-wceu-readiness.js
• CLAUDE.md
• instructions/file-organisation.instructions.md
• AGENTS.md

**/*.{php,js,jsx,ts,tsx,css,scss,html}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{php,js,jsx,ts,tsx,css,scss,html}: Follow WordPress Coding Standards and inline-documentation standards for PHP, JavaScript, CSS, HTML, and related files.
Identify and highlight potential accessibility and performance issues during code reviews.

Files:

• scripts/verify-wceu-readiness.js

**/scripts/**/*.js

📄 CodeRabbit inference engine (CLAUDE.md)

Scripts must reference the root .schemas/ directory using the correct relative path from their script location.

Files:

• scripts/verify-wceu-readiness.js

**/*.{php,js,jsx,ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

Follow WordPress Coding Standards for PHP and ESLint/Prettier standards for JavaScript and TypeScript.

Files:

• scripts/verify-wceu-readiness.js

**/*.{js,jsx,ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

Avoid unnecessary JavaScript and defer or lazy-load it where possible.

Files:

• scripts/verify-wceu-readiness.js

**/*.{js,jsx,ts,tsx,php}

📄 CodeRabbit inference engine (CLAUDE.md)

Prefer native WordPress blocks over unnecessary custom JavaScript implementations where possible.

Files:

• scripts/verify-wceu-readiness.js

**/*.{js,ts}

⚙️ CodeRabbit configuration file

**/*.{js,ts}: Review JavaScript/TypeScript:

• Ensure code is linted and follows project style guides.
• Check for dead code, unused variables, and clear function naming.
• Validate accessibility and performance optimisations.
• Ensure tests are isolated and do not depend on external state.
• Check for descriptive test names and clear test structure.

Files:

• scripts/verify-wceu-readiness.js

**/*.{md,json,yml,yaml}

📄 CodeRabbit inference engine (AGENTS.md)

Structured files with YAML frontmatter must validate against .schemas/frontmatter.schema.json; applicable Markdown and content must pass the documented lint and type validators.

Files:

• CLAUDE.md
• instructions/file-organisation.instructions.md
• AGENTS.md

**/*.{md,yml,yaml,json}

📄 CodeRabbit inference engine (CLAUDE.md)

Do not use a references frontmatter field; use inline links or footer sections instead.

Files:

• CLAUDE.md
• instructions/file-organisation.instructions.md
• AGENTS.md

instructions/**/*.instructions.md

📄 CodeRabbit inference engine (AGENTS.md)

Use root instructions/ for portable standards shared across LightSpeedWP projects.

Files:

• instructions/file-organisation.instructions.md

instructions/**

⚙️ CodeRabbit configuration file

instructions/**: Review portable instruction files:

• Verify frontmatter follows the canonical pattern (file_type, version, last_updated, owners, tags, status, domain, stability).
• Flag any references: frontmatter field — prohibited by CLAUDE.md.
• Confirm the file has: Overview, General Rules, Detailed Guidance, Examples, Validation, and Cross-References sections.
• Check that language is UK English throughout.

Files:

• instructions/file-organisation.instructions.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: lightspeedwp/.github
Timestamp: 2026-08-04T17:54:51.965Z
Learning: Do not place reusable assets under `.github/`; use the matching portable top-level folder instead.

Learnt from: CR
Repo: lightspeedwp/.github
Timestamp: 2026-08-04T17:54:51.965Z
Learning: Do not push directly to `main` or `develop` except during authorised release or hotfix workflows.

Learnt from: CR
Repo: lightspeedwp/.github
Timestamp: 2026-08-04T17:54:51.965Z
Learning: Branches must use `{type}/{scope}-{short-title}` format with lowercase kebab-case and an approved type prefix; never use the `claude/` prefix.

Learnt from: CR
Repo: lightspeedwp/.github
Timestamp: 2026-08-04T17:54:51.965Z
Learning: Pull requests from feature, fix, chore, documentation, and similar branches must target `develop`; only `release/*` and `hotfix/*` branches may target `main`.

Learnt from: CR
Repo: lightspeedwp/.github
Timestamp: 2026-08-04T17:54:51.965Z
Learning: Every PR merge must verify the base branch, use squash merge, and clean up both remote and local branches after a successful merge.

Learnt from: CR
Repo: lightspeedwp/.github
Timestamp: 2026-08-04T17:54:51.965Z
Learning: Do not move existing agents, instructions, or schemas without a migration issue documenting the source path, target path, and validation plan.

🪛 LanguageTool

CLAUDE.md

[uncategorized] ~53-~53: The official name of this software platform is spelled with a capital “H”.
Context: ...lidation | | Scripts | scripts/ | .github/scripts/ (Phase 1) → scripts/ (Phase...

(GITHUB)

---

[uncategorized] ~53-~53: The official name of this software platform is spelled with a capital “H”.
Context: ...e 1) → scripts/ (Phase 2B) | Move to .github, then back to portable root | | **Websi...

(GITHUB)

---

[uncategorized] ~54-~54: The official name of this software platform is spelled with a capital “H”.
Context: ...ble root | | Website | website/ | .github/website/ | Move to .github | | **Proje...

(GITHUB)

---

[uncategorized] ~54-~54: The official name of this software platform is spelled with a capital “H”.
Context: ...bsite/|.github/website/| Move to .github | | **Projects** |projects/active/` |...

(GITHUB)

---

[uncategorized] ~55-~55: The official name of this software platform is spelled with a capital “H”.
Context: ...| | Projects | projects/active/ | .github/projects/active/ | Move to .github | |...

(GITHUB)

---

[uncategorized] ~55-~55: The official name of this software platform is spelled with a capital “H”.
Context: ...| .github/projects/active/ | Move to .github | | Frontmatter schema | `scripts/v...

(GITHUB)

---

[uncategorized] ~67-~67: The official name of this software platform is spelled with a capital “H”.
Context: ...at repo root Control-plane scripts (.github location): - From `.github/scripts/a...

(GITHUB)

---

[uncategorized] ~69-~69: The official name of this software platform is spelled with a capital “H”.
Context: ...e scripts (.github location):** - From .github/scripts/agents/: go two levels up ...

(GITHUB)

---

[uncategorized] ~70-~70: The official name of this software platform is spelled with a capital “H”.
Context: ....schemas/) to reach .schemas/- From.github/scripts/workflows/`: go **three levels ...

(GITHUB)

---

[uncategorized] ~313-~313: The official name of this software platform is spelled with a capital “H”.
Context: ...(templates, labels, workflows, rules) | .github/ | No (org-specific) | | **Instruction...

(GITHUB)

---

[uncategorized] ~315-~315: The official name of this software platform is spelled with a capital “H”.
Context: ...structions** (control-plane-specific) | .github/instructions/ or `.github/custom-instr...

(GITHUB)

---

[uncategorized] ~315-~315: The official name of this software platform is spelled with a capital “H”.
Context: ...-specific) | .github/instructions/ or .github/custom-instructions.md | No (repo-spec...

(GITHUB)

---

[uncategorized] ~319-~319: The official name of this software platform is spelled with a capital “H”.
Context: ...pecs** (GitHub-native, repo-specific) | .github/agents/ | No (GitHub Actions only) | |...

(GITHUB)

---

[uncategorized] ~321-~321: The official name of this software platform is spelled with a capital “H”.
Context: ...specific agents, validators, runners) | .github/scripts/ | No (repo-specific) | | **Re...

(GITHUB)

---

[uncategorized] ~322-~322: The official name of this software platform is spelled with a capital “H”.
Context: ...fic) | | Reports, audits, metrics | .github/reports/{category}/ (date-prefixed) | ...

(GITHUB)

---

[uncategorized] ~323-~323: The official name of this software platform is spelled with a capital “H”.
Context: ...ocs) | | Active project artefacts | .github/projects/active/{slug}/ | No (org-spec...

(GITHUB)

---

[uncategorized] ~324-~324: The official name of this software platform is spelled with a capital “H”.
Context: ...ific) | | Temporary scratch files | .github/tmp/ (clean up before PR) | No (tempor...

(GITHUB)

---

[uncategorized] ~337-~337: The official name of this software platform is spelled with a capital “H”.
Context: ... 1: GitHub-Native Control-Plane Agents (.github/agents/) Location: `.github/agent...

(GITHUB)

---

[uncategorized] ~339-~339: The official name of this software platform is spelled with a capital “H”.
Context: ...ents (.github/agents/) Location:.github/agents/ — repository control plane onl...

(GITHUB)

---

[uncategorized] ~345-~345: The official name of this software platform is spelled with a capital “H”.
Context: ...els) - Agents that are specific to this .github repository's governance Examples:...

(GITHUB)

---

[uncategorized] ~383-~383: Do not mix variants of the same word (‘organization’ and ‘organisation’) within a single text.
Context: ...entrypoint - Reusable in other projects/organizations - Logic is framework/platform-independe...

(EN_WORD_COHERENCY)

---

[uncategorized] ~451-~451: The official name of this software platform is spelled with a capital “H”.
Context: .../../.schemas/ - Control-plane scripts (.github/scripts/) use ../../.schemas/` **Exa...

(GITHUB)

---

[uncategorized] ~494-~494: The official name of this software platform is spelled with a capital “H”.
Context: ...-local instructions** (specific to this .github control plane): Files below are contr...

(GITHUB)

---

[uncategorized] ~498-~498: The official name of this software platform is spelled with a capital “H”.
Context: ...r reuse outside this repository. - **[.github/custom-instructions.md](./.github/custo...

(GITHUB)

---

[uncategorized] ~498-~498: The official name of this software platform is spelled with a capital “H”.
Context: ...ry. - .github/custom-instructions.md — GitHub Copi...

(GITHUB)

---

[uncategorized] ~499-~499: Do not mix variants of the same word (‘organization’ and ‘organisation’) within a single text.
Context: ...sitory's file placement rules and asset organization boundaries - **AGENTS.md...

(EN_WORD_COHERENCY)

instructions/file-organisation.instructions.md

[style] ~60-~60: Would you like to use the Oxford spelling “categorize”? The spelling ‘categorise’ is also correct.
Context: ...surance, community standards. How to categorise: If an instruction applies to multipl...

(OXFORD_SPELLING_Z_NOT_S)

---

[style] ~60-~60: Would you like to use the Oxford spelling “organization”? The spelling ‘organisation’ is also correct.
Context: ...ies to multiple projects or the broader organisation, it belongs in instructions/ at the r...

(OXFORD_SPELLING_Z_NOT_S)

---

[style] ~115-~115: Would you like to use the Oxford spelling “synchronization”? The spelling ‘synchronisation’ is also correct.
Context: ...sync.instructions.md — Project metadata synchronisation - prompt.instructions.md — Prompt engin...

(OXFORD_SPELLING_Z_NOT_S)

---

[style] ~120-~120: Would you like to use the Oxford spelling “synchronization”? The spelling ‘synchronisation’ is also correct.
Context: ...pment - tasksync.instructions.md — Task synchronisation patterns - template.instructions.md — T...

(OXFORD_SPELLING_Z_NOT_S)

---

[uncategorized] ~124-~124: The official name of this software platform is spelled with a capital “H”.
Context: ...andards #### Repo-Local Instructions (.github/instructions/) Purpose: Control-pl...

(GITHUB)

---

[uncategorized] ~126-~126: The official name of this software platform is spelled with a capital “H”.
Context: ...ontrol-plane-specific guidance for this .github repository only. Scope: Copilot i...

(GITHUB)

---

[style] ~128-~128: Would you like to use the Oxford spelling “customizations”? The spelling ‘customisations’ is also correct.
Context: ...itHub-native governance, local workflow customisations. How to categorise: If an instruct...

(OXFORD_SPELLING_Z_NOT_S)

---

[style] ~130-~130: Would you like to use the Oxford spelling “categorize”? The spelling ‘categorise’ is also correct.
Context: ...ocal workflow customisations. How to categorise: If an instruction is specific to the...

(OXFORD_SPELLING_Z_NOT_S)

---

[uncategorized] ~130-~130: The official name of this software platform is spelled with a capital “H”.
Context: ...** If an instruction is specific to the .github control plane and not reusable across ...

(GITHUB)

---

[uncategorized] ~130-~130: The official name of this software platform is spelled with a capital “H”.
Context: ...reusable across projects, it belongs in .github/instructions/. **Current repo-local i...

(GITHUB)

---

[uncategorized] ~134-~134: The official name of this software platform is spelled with a capital “H”.
Context: ...ne-specific Markdown and formatting for .github assets Note: The primary repo-loc...

(GITHUB)

---

[uncategorized] ~136-~136: The official name of this software platform is spelled with a capital “H”.
Context: ...The primary repo-local guidance is in [.github/custom-instructions.md](./.github/custo...

(GITHUB)

---

[uncategorized] ~136-~136: The official name of this software platform is spelled with a capital “H”.
Context: ...ce is in .github/custom-instructions.md, which contains...

(GITHUB)

---

[uncategorized] ~143-~143: The preposition ‘to’ seems more likely in this position.
Context: ....mdat the root 2. Follow the template ininstructions/instructions.instructions...

(AI_HYDRA_LEO_REPLACE_IN_TO)

---

[uncategorized] ~151-~151: The official name of this software platform is spelled with a capital “H”.
Context: ...ith scope: repo-local 3. Note: Prefer .github/custom-instructions.md for single-topi...

(GITHUB)

---

[style] ~154-~154: Would you like to use the Oxford spelling “categorization”? The spelling ‘categorisation’ is also correct.
Context: ...in this section with purpose Example categorisation: - ✅ Portable: "How to structure...

(OXFORD_SPELLING_Z_NOT_S)

---

[uncategorized] ~158-~158: The official name of this software platform is spelled with a capital “H”.
Context: ...:** "How Copilot is configured for this .github repo" → `.github/custom-instructions.m...

(GITHUB)

---

[uncategorized] ~165-~165: The official name of this software platform is spelled with a capital “H”.
Context: ...based agents. #### Spec-Based Agents (.github/agents/) Purpose: Simple, single-f...

(GITHUB)

---

[style] ~283-~283: Would you like to use the Oxford spelling “Centralized”? The spelling ‘Centralised’ is also correct.
Context: ... JSON validation schemas. Purpose: Centralised, portable schema definitions for valida...

(OXFORD_SPELLING_Z_NOT_S)

---

[uncategorized] ~318-~318: The preposition ‘to’ seems more likely in this position.
Context: ...hema:** 1. Create {type}.schema.json in .schemas/ 2. Include $schema declar...

(AI_HYDRA_LEO_REPLACE_IN_TO)

---

[uncategorized] ~344-~344: The official name of this software platform is spelled with a capital “H”.
Context: ...ository maintains structured reports in .github/reports/ to track audits, analysis, an...

(GITHUB)

---

[uncategorized] ~350-~350: The official name of this software platform is spelled with a capital “H”.
Context: ...}/` Report Categories:Audits (.github/reports/audits/) - Purpose: Audit fi...

(GITHUB)

---

[uncategorized] ~357-~357: The official name of this software platform is spelled with a capital “H”.
Context: ...-1-instructions-audit.md` Analysis (.github/reports/analysis/) - Purpose: Data a...

(GITHUB)

---

[uncategorized] ~364-~364: The official name of this software platform is spelled with a capital “H”.
Context: ...ocs-audit-report.md` Agent Reports (.github/reports/agents/) - Purpose: Agent-sp...

(GITHUB)

---

[uncategorized] ~368-~368: The official name of this software platform is spelled with a capital “H”.
Context: ...ucture: One folder per agent - Example: .github/reports/agents/linear-advisor-agent/ c...

(GITHUB)

---

[uncategorized] ~370-~370: The official name of this software platform is spelled with a capital “H”.
Context: ... results, metrics, status Archived (.github/reports/archived/) - Purpose: Old re...

(GITHUB)

---

[uncategorized] ~401-~401: The official name of this software platform is spelled with a capital “H”.
Context: ...move completed or superseded reports to .github/reports/archived/. ### Standard Repos...

(GITHUB)

---

[uncategorized] ~457-~457: The official name of this software platform is spelled with a capital “H”.
Context: ...b structure | | Spec-based agents | .github/agents/ | {name}.agent.md (simple YA...

(GITHUB)

---

[uncategorized] ~459-~459: The official name of this software platform is spelled with a capital “H”.
Context: ...nai/) | | Repo-local instructions | .github/instructions/ | `{topic}.instructions....

(GITHUB)

---

[uncategorized] ~462-~462: The official name of this software platform is spelled with a capital “H”.
Context: ...opilot pattern) | | Audit reports | .github/reports/audits/ | `YYYY-MM-DD-{descrip...

(GITHUB)

---

[uncategorized] ~463-~463: The official name of this software platform is spelled with a capital “H”.
Context: ...criptor}.md| | **Analysis reports** |.github/reports/analysis/|{topic}.mdorY...

(GITHUB)

---

[uncategorized] ~464-~464: The official name of this software platform is spelled with a capital “H”.
Context: ...descriptor}.md| | **Agent reports** |.github/reports/agents/|{agent-name}/` with...

(GITHUB)

---

[uncategorized] ~521-~521: The official name of this software platform is spelled with a capital “H”.
Context: ...tomation agents in agents/ (should be .github/agents/) - Using unclear naming like `...

(GITHUB)

---

[uncategorized] ~550-~550: The official name of this software platform is spelled with a capital “H”.
Context: ...gent.schema.json) - Placing schemas in .github/.schemas/instead of root.schemas/` ...

(GITHUB)

---

[uncategorized] ~580-~580: The official name of this software platform is spelled with a capital “H”.
Context: ...d:** - Placing reports in root without .github/reports/ structure - Using unclear nam...

(GITHUB)

---

[uncategorized] ~622-~622: The official name of this software platform is spelled with a capital “H”.
Context: ...on-wide- ✅ Repo-local instructions in.github/instructions/havescope: repo-local`...

(GITHUB)

---

[uncategorized] ~629-~629: The official name of this software platform is spelled with a capital “H”.
Context: ...T.mdmetadata - ✅ Spec-based agents in.github/agents/as single.agent.md` files - ...

(GITHUB)

---

[uncategorized] ~636-~636: The official name of this software platform is spelled with a capital “H”.
Context: ....schemas/ (hidden folder at root, not .github/.schemas/) - ✅ Schema files named `{ty...

(GITHUB)

---

[uncategorized] ~643-~643: The official name of this software platform is spelled with a capital “H”.
Context: ...pecific Checks:** - ✅ Audit reports in .github/reports/audits/ with `YYYY-MM-DD-{desc...

(GITHUB)

---

[uncategorized] ~647-~647: The official name of this software platform is spelled with a capital “H”.
Context: ...ted_date- ✅ Archived reports moved to.github/reports/archived/` with timestamp ## R...

(GITHUB)

---

[uncategorized] ~660-~660: The official name of this software platform is spelled with a capital “H”.
Context: ...dits:** - [Phase 1A: Instructions Audit](../.github/reports/audits/phase-1-instructions-aud...

(GITHUB)

---

[uncategorized] ~661-~661: The official name of this software platform is spelled with a capital “H”.
Context: ...ctions review - [Phase 1B: Schemas Audit](../.github/reports/audits/phase-1-schemas-audit-20...

(GITHUB)

---

[uncategorized] ~662-~662: The official name of this software platform is spelled with a capital “H”.
Context: ...definitions - [Phase 1C: AI Config Audit](../.github/reports/audits/phase-1-ai-config-audit-...

(GITHUB)

---

[style] ~663-~663: Would you like to use the Oxford spelling “Organization”? The spelling ‘Organisation’ is also correct.
Context: ...ti-provider agent configuration - [File Organisation Migration Plan](../.github/reports/audi...

(OXFORD_SPELLING_Z_NOT_S)

---

[uncategorized] ~663-~663: The official name of this software platform is spelled with a capital “H”.
Context: ...tion - [File Organisation Migration Plan](../.github/reports/audits/2026-06-03-file-organisa...

(GITHUB)

AGENTS.md

[uncategorized] ~26-~26: The official name of this software platform is spelled with a capital “H”.
Context: ...tion reference policy (Phase 1A):** Use .github/instructions/ for repo-local guidance ...

(GITHUB)

---

[uncategorized] ~27-~27: The official name of this software platform is spelled with a capital “H”.
Context: ... (simple YAML/JSON definitions) live in .github/agents/ (GitHub-native, control-plane ...

(GITHUB)

---

[typographical] ~39-~39: Do not use a colon (:) before a series that is introduced by a preposition (‘with’). Remove the colon or add a noun or a noun phrase after the preposition.
Context: ...ure:** agents/{name}-agent/ directory with: - AGENT.md — main agent definition ...

(RP_COLON)

---

[uncategorized] ~49-~49: The official name of this software platform is spelled with a capital “H”.
Context: ...ent-rules) #### 2. Spec-Based Agents — .github/agents/ (GitHub-Native Only) - **Purp...

(GITHUB)

---

[uncategorized] ~62-~62: The official name of this software platform is spelled with a capital “H”.
Context: ...tations - Spec-based agent index:.github/agents/ — browse sing...

(GITHUB)

---

[uncategorized] ~62-~62: The official name of this software platform is spelled with a capital “H”.
Context: ...ec-based agent index:** .github/agents/ — browse single-file GitHub au...

(GITHUB)

---

[uncategorized] ~70-~70: The official name of this software platform is spelled with a capital “H”.
Context: ...s (agents/ only; spec-based agents in .github/ are control-plane specific) ## Agent...

(GITHUB)

---

[uncategorized] ~91-~91: The official name of this software platform is spelled with a capital “H”.
Context: ...-wide | | Repo-Local Instructions | .github/instructions/{name}.instructions.md | ...

(GITHUB)

---

[uncategorized] ~97-~97: The official name of this software platform is spelled with a capital “H”.
Context: ...nisation.instructions.md- Repo-local:.github/instructions/` (control-plane customiza...

(GITHUB)

---

[uncategorized] ~114-~114: The official name of this software platform is spelled with a capital “H”.
Context: ...installable | | Spec-Based Agents | .github/agents/{name}.agent.md | Single-file Y...

(GITHUB)

---

[uncategorized] ~121-~121: The official name of this software platform is spelled with a capital “H”.
Context: ...- | --- | --- | | Active Projects | .github/projects/active/{slug}/ | In-progress ...

(GITHUB)

---

[uncategorized] ~122-~122: The official name of this software platform is spelled with a capital “H”.
Context: ...ilestone deliverables | | Reports | .github/reports/{category}/ | Metrics, audits,...

(GITHUB)

---

[uncategorized] ~123-~123: The official name of this software platform is spelled with a capital “H”.
Context: ...ructured data | | Temporary Files | .github/tmp/ | Scratch space (clean up before ...

(GITHUB)

---

[uncategorized] ~345-~345: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...L across all code | Portable | | File Organisation | [instructions/file-organisation.ins...

(EN_WORD_COHERENCY)

---

[uncategorized] ~351-~351: The official name of this software platform is spelled with a capital “H”.
Context: ...ortable | | Custom Instructions | [.github/custom-instructions.md](.github/custom-...

(GITHUB)

---

[uncategorized] ~351-~351: The official name of this software platform is spelled with a capital “H”.
Context: ...ions** | .github/custom-instructions.md | Repo-local Co...

(GITHUB)

---

[uncategorized] ~411-~411: The official name of this software platform is spelled with a capital “H”.
Context: ...nforcement** — Automated validation via .github/workflows/ (prevents non-compliant fil...

(GITHUB)

---

[uncategorized] ~518-~518: Do not mix variants of the same word (‘organisation’ and ‘organization’) within a single text.
Context: ...s (consolidated, root-level) | | File Organisation | [instructions/file-organisation.ins...

(EN_WORD_COHERENCY)

---

[uncategorized] ~519-~519: The official name of this software platform is spelled with a capital “H”.
Context: ... assets | | Custom Instructions | [.github/custom-instructions.md](.github/custom-...

(GITHUB)

---

[uncategorized] ~519-~519: The official name of this software platform is spelled with a capital “H”.
Context: ...ions** | .github/custom-instructions.md | Repo-local | ...

(GITHUB)

---

[uncategorized] ~519-~519: The official name of this software platform is spelled with a capital “H”.
Context: ... Control-plane Copilot instructions and .github boundary definitions | | **Claude Inst...

(GITHUB)

---

[uncategorized] ~522-~522: The official name of this software platform is spelled with a capital “H”.
Context: ...root | | Spec-Based Agent Index | .github/agents/ directory | P...

(GITHUB)

---

[uncategorized] ~522-~522: The official name of this software platform is spelled with a capital “H”.
Context: ...c-Based Agent Index** | .github/agents/ directory | Phase 1C | Directo...

(GITHUB)

---

[uncategorized] ~523-~523: The official name of this software platform is spelled with a capital “H”.
Context: ...mation agents | | Prompts Index | [.github/prompts/prompts.md](.github/prompts/pro...

(GITHUB)

---

[uncategorized] ~523-~523: The official name of this software platform is spelled with a capital “H”.
Context: ...ts Index** | .github/prompts/prompts.md | Legacy | Legacy p...

(GITHUB)

---

[uncategorized] ~527-~527: The official name of this software platform is spelled with a capital “H”.
Context: ...ion: portable (agents/) + spec-based (.github/agents/) | --- ## References **Foun...

(GITHUB)

🔇 Additional comments (6)

AGENTS.md (1)

4-10: LGTM!

Also applies to: 26-70, 82-139, 339-351, 404-412, 514-552

CLAUDE.md (1)

311-380: LGTM!

Also applies to: 387-401, 462-468

instructions/file-organisation.instructions.md (2)

4-15: 🗄️ Data Integrity & Integration

Confirm the complete instruction frontmatter.

The path instruction requires file_type, version, last_updated, owners, tags, status, domain, and stability. The displayed block contains only part of this set. Confirm that the omitted opening lines provide the remaining keys. Add any missing keys before running npm run validate:frontmatter.

As per path instructions: instruction files must use the canonical frontmatter fields.

Source: Path instructions

---

50-191: LGTM!

Also applies to: 197-341, 342-356, 403-430, 457-464, 490-551, 584-608, 611-640, 664-664

scripts/verify-wceu-readiness.js (2)

171-171: 🗄️ Data Integrity & Integration

Verify that the npm command reaches this changed file.

The supplied package.json entry at Line 115 invokes .github/scripts/verify-wceu-readiness.js, but the reviewed file is scripts/verify-wceu-readiness.js. Confirm that npm run validate:wceu:phase1 executes this implementation. If the root file is canonical, update the command or move the file and its tests together.

Based on the supplied package.json context: the npm command currently names .github/scripts/verify-wceu-readiness.js.

---

171-171: 🎯 Functional Correctness

Verify the orphan-reference scan after adopting .schemas/.

Line 171 now treats .schemas/ as canonical, but Lines 185-198 still search for \\.schemas and fail when matches exist. The supplied governance files and this script contain canonical .schemas references. Unless grepRecursive excludes them, the readiness check will fail in the correct repository state. Search for legacy schema/ references instead, or exclude canonical references.

Based on the supplied readiness context: .schemas/ is now canonical, but the later scan still targets that canonical spelling.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Keep the portable-agent entrypoint contract consistent.

CLAUDE.md permits AGENT.md or SKILL.md, but instructions/file-organisation.instructions.md requires every multi-file agent to have AGENT.md. This permits a layout that the documented validation rules reject. Remove or SKILL.md, or update all agent validation and guidance as one contract.

Based on the supplied file-organisation contract: multi-file agents require AGENT.md.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~383-~383: Do not mix variants of the same word (‘organization’ and ‘organisation’) within a single text.
Context: ...entrypoint - Reusable in other projects/organizations - Logic is framework/platform-independe...

(EN_WORD_COHERENCY)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` around lines 381 - 385, Update the portable-agent criteria in
CLAUDE.md to require AGENT.md as the sole entrypoint for multi-file
implementations, removing the alternative SKILL.md wording. Keep the documented
validation and guidance consistent with the file-organisation contract.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bashset -euo pipefail
echo"Files:"
git ls-files | rg '(^instructions/file-organisation\.instructions\.md$|^CLAUDE\.md$|^\.schemas/frontmatter\.schema\.json$|reports|analysis)'| sed -n '1,200p'echoecho"CLAUDE.md report date mentions:"
rg -n "YYYY-MM-DD|report|reports|analysis|audit" CLAUDE.md instructions/file-organisation.instructions.md .schemas/frontend?2>/dev/null ||trueechoecho"Relevant sections:"
sed -n '330,410p' instructions/file-organisation.instructions.md
echo"---"
sed -n '530,590p' instructions/file-organisation.instructions.md
echo"---"
sed -n '630,675p' instructions/file-organisation.instructions.md
echo"---"
sed -n '356,366p' CLAUDE.md

Repository: lightspeedwp/.github

Length of output: 29400

---

🏁 Script executed:

#!/bin/bashset -euo pipefail
echo"CLAUDE report naming section:"
sed -n '390,425p' CLAUDE.md
echoecho"Parse file-organisation.report references:"
python3 - <<'PY'from pathlib import Pathp = Path("instructions/file-organisation.instructions.md")text = p.read_text()for i, line in enumerate(text.splitlines(), 1): if "2026-07-22" in line: print(f"{i}: {line}")PYechoecho"Validate changed report name examples against CLAUDE date-prefix rule using a read-only parser-ish check:"
python3 - <<'PY'from pathlib import Pathimport rep = Path(".github/reports")cl = Path("CLAUDE.md").read_text()need_prefix = "All report files in `.github/reports/` MUST follow this naming pattern" in cl and "YYYY-MM-DD-{descriptor}.md" in clfiles = sorted(x.relative_to(p) for x in p.rglob("*.md"))cases = ( "analysis/issue-creation-docs-audit-report.md", "analysis/readme-audit-extended-2026-05-31.md", "audits/issue-creation-docs-audit-report.md", "audits/phase-1-instructions-audit-2026-07-22.md",)print("CLAUDE requires every report filename to start with YYYY-MM-DD-:", need_prefix)for c in cases: name = Path(c).name starts = bool(re.match(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}-", name)) print(f"{c}: first={starts}, existing={Path(p/c).exists()}")PY

Repository: lightspeedwp/.github

Length of output: 2438

---

Keep the report file contract date-prepended and complete.

Pick one report naming rule. If .github/reports/ must use YYYY-MM-DD-{descriptor}.md, remove the date-free analysis option and update the referenced audit links/files that still end with .md instead of starting with the ISO date. If analysis reports are intentionally exempt, document that as a valid .github/reports/ exception.

Also add the required report status to the frontmatter example, since the format requires draft, active, completed, or archived.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~357-~357: The official name of this software platform is spelled with a capital “H”.
Context: ...-1-instructions-audit.md` Analysis (.github/reports/analysis/) - Purpose: Data a...

(GITHUB)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@instructions/file-organisation.instructions.md` around lines 357 - 362,
Update the Analysis (.github/reports/analysis/) guidance to require the
date-prepended YYYY-MM-DD-{descriptor}.md convention, remove the date-free
alternative, and update any referenced audit filenames or links that lack the
ISO-date prefix. Add a valid status field to the frontmatter example, using
draft, active, completed, or archived.

Source: Path instructions

[coderabbitai]

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Add the required Cross-References section heading.

The path instruction requires a section named Cross-References. The file still uses ## References at Line 649. Rename that heading or add the required section before these links.

As per path instructions: instruction files must include Overview, General Rules, Detailed Guidance, Examples, Validation, and Cross-References sections.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@instructions/file-organisation.instructions.md` around lines 651 - 656,
Update the section heading immediately preceding the listed links in the
file-organisation instructions from “References” to “Cross-References,”
preserving the existing links and ensuring the file includes the required
Overview, General Rules, Detailed Guidance, Examples, Validation, and
Cross-References sections.

Source: Path instructions