New scripts and updates to instructions to remove references

Author: ashleyshaw

.github/agents/a11y.agent.md

@@ -193,9 +193,3 @@ Block theme accessibility rests on the **POUR** model:
 - [ ] Reduced motion respected
 
 ---
-
-## References
-
-- **Theme Accessibility Handbook** — WordPress Theme Handbook on accessibility readiness and requirements.
-- **Learn WordPress Accessibility Lesson** — fundamentals for theme accessibility basics.
-- **WCAG (W3C)** — global accessibility standard underpinning these requirements.

.github/agents/reporting.agent.md

@@ -773,15 +773,6 @@ async function runLighthouse() {
 - Keep comparison baselines and project updates in their dedicated subfolders
 - Archive or rotate older files instead of deleting unless policy requires
 
-## References
-
-- Agent index: `.github/agents/agent.md`
-- Instructions: `.github/instructions/reporting.instructions.md`
-- Script: `scripts/reporting.agent.js`
-- Tests: `tests/agents/reporting.agent.test.js`
-- Workflow: `.github/workflows/agent-reporting.yml`
-- Logs: `logs/` (per-category subfolders)
-
 ## Summary
 
 ✅ Each report type has defined structure and location

.github/copilot-tasks.md

@@ -7,7 +7,6 @@ audience: AI Assistants, Developers
 date: 2025-12-01
 ---
 
-
 > **Status**: ✅ All audit remediation tasks completed (21/21)
 
 ## 1. Missing Files

.github/instructions/README.md

@@ -21,6 +21,8 @@ This directory lists the instruction files that guide Copilot and contributors w
 - Treat this file as a directory index, not a source of standards.
 - Link to topic-specific instructions rather than re-stating them.
 - Keep file names and paths up to date when instructions move or are added.
+- Actively prevent circular reference loops: remove any `## References` or `## See Also` sections (or similar headings) from individual instruction files and keep their metadata limited to `custom-instructions.md` and `_index.instructions.md`.
+- Run `scripts/clean-github-references.js` from the repo root before updating `.github` instruction files so that those sections are purged consistently and only the clean hierarchy remains.
 
 ## Detailed Guidance
 
@@ -57,9 +59,4 @@ See the file list below for topic coverage. Open the relevant `*.instructions.md
 
 - Confirm links resolve to existing files in `.github/instructions/`.
 - Run `rg --files .github/instructions` to ensure the index reflects current contents.
-
-## References
-
-- [../custom-instructions.md](../custom-instructions.md)
-- [./instructions.instructions.md](./instructions.instructions.md)
-- [../agents/agent.md](../agents/agent.md)
+- After editing instructions, rerun `node scripts/fix-instruction-references.js` and `scripts/clean-github-references.js` to enforce the allowed metadata and ensure no "References" or "See Also" blocks reappear.

.github/instructions/_index.instructions.md

@@ -49,12 +49,4 @@ _index.instructions.md (Tier 2 navigator)
 *.instructions.md topic files (Tier 3 subjects)
 ```
 - Tier 3 files should only reference `custom-instructions.md` and `_index.instructions.md` in their metadata.
-- Keep other links in body sections such as `## See Also`, `## Examples`, or `## Resources` so the metadata graph stays clean.
-- Document new instruction files and any path changes here to keep the catalog accurate.
-
-## See Also
-- [Custom AI Instructions](../custom-instructions.md)
-- [AGENTS.md](../../AGENTS.md)
-- [Block Theme Build Agent spec](../agents/block-theme-build.agent.md)
-- [Block Theme Build & E2E workflow](../workflows/block-theme-build-and-e2e.yml)
-- [Instruction authoring guide](./instructions.instructions.md)
+- Keep other links in body sections such as `

.github/instructions/a11y.instructions.md

@@ -47,9 +47,3 @@ Apply these instructions whenever adding or modifying markup, patterns, template
 - Manual: keyboard navigation (Tab/Shift+Tab/Esc) and visible focus.
 - Screen readers: spot-check with VoiceOver/NVDA for form labels and landmarks.
 - Quick checklist: semantic HTML and headings, visible focus, sufficient contrast, labelled form controls, ARIA only when necessary.
-
-## References
-
-- [WordPress Accessibility Handbook](https://make.wordpress.org/accessibility/handbook/)
-- [./html-markup.instructions.md](./html-markup.instructions.md)
-- [./block-theme-development.instructions.md](./block-theme-development.instructions.md)

.github/instructions/agent-spec.instructions.md

@@ -90,11 +90,3 @@ Use this instruction file when drafting or reviewing any `.agent.md` in `.github
 - [ ] Three validation tasks cover typical, edge, and failure cases.
 - [ ] Observability requirements (logs/reports) are included.
 - [ ] Changelog updated and references (prompt/script/tests/workflow) are accurate.
-
-## References
-
-- [../agents/template.agent.md](../agents/template.agent.md)
-- [../agents/agent.md](../agents/agent.md)
-- [./instructions.instructions.md](./instructions.instructions.md)
-- [./copilot-ai-agent.instructions.md](./copilot-ai-agent.instructions.md)
-- [../workflows/block-theme-build-and-e2e.yml](../workflows/block-theme-build-and-e2e.yml)

.github/instructions/block-theme-development.instructions.md

@@ -360,12 +360,3 @@ Add `.editorconfig` for consistent indentation and formatting.
 - Run `npm run lint`, `npm run test`, and `npm run build` before merging changes.
 - Validate block comments in templates/parts and pattern metadata headers.
 - Check `theme.json` changes against the WordPress schema (e.g., VS Code schema validation).
-
-## References
-
-- [./theme-json.instructions.md](./theme-json.instructions.md)
-- [./wpcs-php.instructions.md](./wpcs-php.instructions.md)
-- [./javascript.instructions.md](./javascript.instructions.md)
-- [./wpcs-css.instructions.md](./wpcs-css.instructions.md)
-- [./html-markup.instructions.md](./html-markup.instructions.md)
-- [../custom-instructions.md](../custom-instructions.md)

.github/instructions/copilot-ai-agent.instructions.md

@@ -613,13 +613,3 @@ npm run lint -- --verbose
 - Run `npm run lint`, `npm run test`, `npm audit`, and `npm run coverage` when applicable.
 - Ensure reports and logs are stored under `logs/` and `.github/reports/` with ISO-dated filenames.
 - Verify naming and folder usage against `naming-conventions.instructions.md` and `FOLDER_STRUCTURE.md`.
-
-## References
-
-- [../custom-instructions.md](../custom-instructions.md)
-- [./reporting.instructions.md](./reporting.instructions.md)
-- [./naming-conventions.instructions.md](./naming-conventions.instructions.md)
-- [../../docs/GOVERNANCE.md](../../docs/GOVERNANCE.md)
-- [../../docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
-- [../../docs/FOLDER_STRUCTURE.md](../../docs/FOLDER_STRUCTURE.md)
-- [../../docs/LOGGING.md](../../docs/LOGGING.md)

.github/instructions/generate-theme.instructions.md

@@ -862,12 +862,3 @@ As an AI agent guiding theme generation:
 6. **Guide post-generation** setup and next steps
 
 **Remember:** Mustache variables are simple string replacements. Your job is to collect valid values and pass them to the generator script. The script handles the actual replacement process.
-
-## References
-
-- [GENERATE_THEME.md](../../docs/GENERATE_THEME.md) - Complete generator system documentation
-- [generate-theme.prompt.md](../prompts/generate-theme.prompt.md) - User-facing generation prompt
-- [generate-theme.agent.md](../agents/generate-theme.agent.md) - Agent specification
-- [theme-json.instructions.md](./theme-json.instructions.md) - theme.json configuration guide
-- [theme-config.schema.json](../schemas/theme-config.schema.json) - JSON Schema for validation
-- [theme-config.template.json](../../theme-config.template.json) - Template config file