feat(markdown-reference-guardrail): enforce heading-based *.instructions.md link checks, update docs, and add latest audit report

- Restricts forbidden *.instructions.md link checks to ## References/See Also headings in scripts/check-markdown-references.js
- Updates screenshot.png.md to comply with new guardrail
- Adds README.md and _index.instructions.md to .github/instructions/
- Includes only the latest audit report (2025-12-15-154025-frontmatter-audit.csv) per reporting policy
- All tests and checks pass

Author: ashleyshaw

.github/instructions/README.md

@@ -0,0 +1,64 @@
+---
+title: Instructions Directory
+description: Developer and AI instruction files
+category: Project
+type: Index
+audience: Developers, AI Assistants
+date: 2025-12-01
+applyTo: ".github/instructions/README.md"
+---
+
+# Development Instructions
+
+You are an instruction index curator. Follow our block theme scaffold documentation map to route Copilot to the right instruction sets. Avoid duplicating standards here—link to the dedicated instruction files instead.
+
+## Overview
+
+This directory lists the instruction files that guide Copilot and contributors working on the block theme scaffold. Use it to discover the right topic-specific instructions; it does not replace the detailed guidance in each file.
+
+## General Rules
+
+- 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 the individual instruction files and keep their metadata limited to `custom-instructions.md` and `_index.instructions.md`. Do not add a `references` field back into the frontmatter—mention links inline or in narrative guidance instead.
+- Run `scripts/clean-github-references.js` from the repo root before updating `.github` instruction files. The script now scans every Markdown file under the repo, so the docs tree (not only `.github`) stays free of those sections and the hierarchy remains clean.
+- After editing Markdown references anywhere—especially under `docs/` or within README files—run `npm run check:markdown-references` to catch any remaining `## References` or `## See Also` headings that still link to `.instructions.md`.
+
+## Detailed Guidance
+
+See the file list below for topic coverage. Open the relevant `*.instructions.md` file for the full rules, examples, validation steps, and references.
+
+## Files
+
+**Core Development Standards:**
+
+- **a11y.instructions.md** - Comprehensive accessibility standards (WCAG 2.2 AA)
+- **block-theme-development.instructions.md** - Block theme development guidelines
+- **html-markup.instructions.md** - HTML markup and template standards
+- **i18n.instructions.md** - Internationalization and localization standards
+- **javascript.instructions.md** - JavaScript, React, and JSDoc standards
+- **wpcs-css.instructions.md** - CSS/SCSS coding standards
+- **wpcs-php.instructions.md** - WordPress PHP coding standards
+
+**Specialized Guidelines:**
+
+- **theme-json.instructions.md** - Theme.json configuration and design systems
+- **security-nonce.instructions.md** - WordPress nonce implementation patterns
+- **naming-conventions.instructions.md** - File and code naming standards
+- **reporting.instructions.md** - Report generation and management
+- **copilot-ai-agent.instructions.md** - AI agent workflows and rules
+- **generate-theme.instructions.md** - Theme generation instructions
+
+## Examples
+
+- Use `wpcs-php.instructions.md` when editing PHP or adding new hooks.
+- Open `theme-json.instructions.md` before modifying design tokens or global styles.
+- Reference `reporting.instructions.md` when generating lint/test reports.
+
+## Validation
+
+- Confirm links resolve to existing files in `.github/instructions/`.
+- Run `rg --files .github/instructions` to ensure the index reflects current contents.
+- 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.
+- Run `npm run check:markdown-references` whenever you touch Markdown references anywhere so the script can expose stray `.instructions.md` links inside those headings before committing.

.github/instructions/_index.instructions.md

@@ -0,0 +1,31 @@
+---
+title: Instructions Index
+description: Master reference for repository-specific guidance and dynamic discovery of instruction files.
+category: Project
+type: Index
+audience: Developers, AI Assistants
+date: 2025-12-08
+applyTo: ".github/instructions/_index.instructions.md"
+---
+
+# Block Theme Scaffold Instruction Map
+
+This file guides contributors and agents to the most relevant rules in this directory. The index leans on a dynamic discovery pattern (`*.instructions.md`) so that every properly named instruction file is found automatically; keep the glob in mind when adding new guidance, and avoid redundant static lists that can drift out of sync.
+
+## Priority Guidance
+
+Highlight the instructions you find yourself referencing the most in this repository:
+
+- `block-theme-development.instructions.md` – block-theme-first patterns, theme scaffolding, and template best practices.
+- `theme-json.instructions.md` – design tokens, global styles, and theme configuration via `theme.json`.
+- `copilot-ai-agent.instructions.md` – how agents and Copilot should behave while touching the codebase.
+- `generate-theme.instructions.md` – rules for regenerating the scaffold while preserving Mustache placeholders.
+- `wpcs-php.instructions.md`, `wpcs-css.instructions.md`, and `javascript.instructions.md` – WordPress coding standards for PHP, CSS/SCSS, and JS.
+- `a11y.instructions.md` – accessibility guardrails for block themes.
+- `reporting.instructions.md` and `security-nonce.instructions.md` – reporting conventions and nonce handling workstreams.
+
+## Dynamic Discovery (`*.instructions.md`)
+
+This directory relies on the glob `*.instructions.md` to surface every instruction file, keeping the index up to date without manual edits. New instruction files that follow this naming convention are automatically collected, so you only need to add them once. When reorganizing or renaming files, re-run `rg --files .github/instructions '*.instructions.md'` to confirm the pattern still matches every intended document.
+
+To keep everything tidy, avoid `## References` or `## See Also` sections in the individual instruction files and let the glob-driven index do the cross-linking. When you add or touch any instruction file, run `npm run check:markdown-references` and `scripts/clean-github-references.js` to ensure the directory stays free of forbidden reference headings while honoring the dynamic index pattern.

.github/reports/analysis/2025-12-15-154025-frontmatter-audit.csv

@@ -0,0 +1,15 @@
+File,Reference Count,References,Circular,Recommendation
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/AGENTS.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/CHANGELOG.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/CONTRIBUTING.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/DEVELOPMENT.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/ISSUES_REPORT.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/README.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/SECURITY.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/SUPPORT.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/docs/GENERATE_THEME.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/docs/RELEASE_PROCESS.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/docs/RELEASE_PROCESS_SCAFFOLD.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/docs/plans/2025-12-12-generator-logging-schema-cleanup-design.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/screenshot.png.md",0,"",NO,OK
+"/Users/ash/Studio/tour-operator/wp-content/themes/block-theme-scaffold/scripts/__tests__/test-audit/test.md",5,"file1.md; file2.md; file3.md; file4.md; file5.md",NO,REVIEW

screenshot.png.md

@@ -51,7 +51,5 @@ convert -size 1200x900 xc:#f0f0f0 -pointsize 48 -gravity center \
   -annotate +0+0 "{{theme_name}}" screenshot.png
 ```
 
-## References
-
 - [WordPress Theme Handbook - Theme Structure](https://developer.wordpress.org/themes/core-concepts/theme-structure/)
 - [Theme Review Handbook - Required Files](https://make.wordpress.org/themes/handbook/review/required/)

scripts/check-markdown-references.js

@@ -4,47 +4,76 @@ const fs = require('fs');
 const path = require('path');
 
 const root = path.resolve(__dirname, '..');
-const sectionsRegex = /## (?:See Also(?: [^\n]*)?|References)[\s\S]*?(?=\n## |$)/g;
-const instructionLinkRegex = /_index\.instructions\.md/;
-const ignoredDirs = ['node_modules', 'vendor', '.git', 'build', 'dist'];
+const ignoredDirs = new Set([
+  '.git',
+  'node_modules',
+  'vendor',
+  'tmp',
+  'public',
+  'dist',
+  'build',
+  '.archive',
+]);
+const headingPattern = /^## (See Also|References)\b/i;
 
-function getMarkdownFiles(dir) {
+/**
+ * List markdown files recursively, skipping ignored directories.
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function listMarkdownFiles(dir) {
   return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
     const resolved = path.join(dir, entry.name);
+
     if (entry.isDirectory()) {
-      if (ignoredDirs.includes(entry.name)) {
+      if (ignoredDirs.has(entry.name)) {
         return [];
       }
-      return getMarkdownFiles(resolved);
+      return listMarkdownFiles(resolved);
     }
+
     if (entry.isFile() && entry.name.endsWith('.md')) {
       return [resolved];
     }
+
     return [];
   });
 }
 
-let violationsFound = false;
+let findings = 0;
 
-getMarkdownFiles(root).forEach((filePath) => {
+listMarkdownFiles(root).forEach((filePath) => {
   const content = fs.readFileSync(filePath, 'utf8');
-  const sections = content.match(sectionsRegex);
-
-  if (sections) {
-    sections.forEach((section) => {
-      if (instructionLinkRegex.test(section)) {
-        violationsFound = true;
-        console.error(
-          `❌ Violation in ${path.relative(process.cwd(), filePath)}: Found link to '.instructions.md' in a 'References' or 'See Also' section.`
-        );
-      }
-    });
+  const lines = content.split('\n');
+  let inHeading = false;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    if (headingPattern.test(trimmed)) {
+      inHeading = true;
+      continue;
+    }
+
+    if (inHeading && trimmed.startsWith('## ')) {
+      inHeading = false;
+    }
+
+    if (inHeading && line.includes('.instructions.md')) {
+      findings += 1;
+      const relativePath = path.relative(process.cwd(), filePath);
+      // console.log(`${relativePath}:${i + 1}: ${trimmed}`);
+    }
   }
 });
 
-if (violationsFound) {
-  console.error('\nPlease remove these references to maintain a clean hierarchy.');
-  process.exit(1);
+if (findings > 0) {
+  // console.error(
+  //   `Found ${findings} Markdown reference link(s) to .instructions.md under References/See Also headings.`
+  // );
+  process.exitCode = 1;
+} else {
+  // console.log('✅ No invalid markdown references found.');
 }
-
-console.log('✅ No invalid markdown references found.');