PR: Feature/markdown reference guardrail

.babelrc.json

@@ -1,3 +1,3 @@
 {
-	"presets": ["@wordpress/babel-preset-default"]
+	"presets": [ "@wordpress/babel-preset-default" ]
 }

.devcontainer/devcontainer.json

@@ -34,8 +34,8 @@
 				"[php]": {
 					"editor.defaultFormatter": "bmewburn.vscode-intelephense-client"
 				},
-				"eslint.validate": ["javascript", "javascriptreact"],
-				"stylelint.validate": ["css", "scss", "postcss"],
+				"eslint.validate": [ "javascript", "javascriptreact" ],
+				"stylelint.validate": [ "css", "scss", "postcss" ],
 				"files.associations": {
 					"*.php": "php",
 					"*.html": "html"
@@ -49,7 +49,7 @@
 		}
 	},
 
-	"forwardPorts": [8080, 8443, 3306],
+	"forwardPorts": [ 8080, 8443, 3306 ],
 
 	"postCreateCommand": "npm ci && composer install",
 

.eslintrc.js

@@ -0,0 +1,35 @@
+module.exports = {
+	root: true,
+	env: {
+		browser: true,
+		node: true,
+		es2021: true,
+		jest: true, // Add Jest global variables
+	},
+	extends: [
+		'plugin:jest/recommended',
+		'plugin:jest/style',
+		'eslint:recommended',
+		'prettier',
+	],
+	plugins: [ 'jest' ],
+	overrides: [
+		{
+			files: [ 'tests/**/*.js' ],
+			env: {
+				jest: true,
+			},
+			globals: {
+				jest: 'readonly',
+				describe: 'readonly',
+				it: 'readonly',
+				test: 'readonly',
+				beforeAll: 'readonly',
+				afterAll: 'readonly',
+				beforeEach: 'readonly',
+				afterEach: 'readonly',
+				expect: 'readonly',
+			},
+		},
+	],
+};

.github/__tests__/README.md

@@ -0,0 +1,8 @@
+# README for Test Helpers
+
+This folder contains shared test helpers for Jest and Playwright.
+
+- Place all shared test helpers here.
+- Add new helpers as needed for test consistency.
+
+See `.github/instructions/jest-tests.instructions.md` for Jest usage and conventions.

.github/__tests__/test-helper.js

@@ -0,0 +1,33 @@
+/**
+ * Shared test helpers for Jest and Playwright
+ *
+ * Use for common setup, teardown, and utility functions across JS and E2E tests.
+ *
+ * - Use TestLogger for consistent logging
+ * - Use retryOperation for async retries
+ * - Add Playwright helpers for block theme E2E
+ */
+
+const TestLogger = require('../.github/tests/test-logger');
+const { retryOperation } = require('../scripts/utils/test-utils');
+
+// Example: Playwright helper for theme activation
+async function activateTheme(page, themeSlug) {
+  await page.goto('/wp-admin/themes.php');
+  await page.click(`button[aria-label="Activate ${themeSlug}"]`);
+}
+
+// Example: Playwright helper for block rendering
+async function renderBlock(page, blockName) {
+  await page.goto('/wp-admin/post-new.php');
+  await page.click('button[aria-label="Add block"]');
+  await page.type('input[placeholder="Search for a block"]', blockName);
+  await page.click(`button[aria-label="${blockName}"]`);
+}
+
+module.exports = {
+  TestLogger,
+  retryOperation,
+  activateTheme,
+  renderBlock,
+};

.github/agents/a11y.agent.md

@@ -3,6 +3,10 @@ description: "Block Theme Accessibility Expert — WCAG-aligned guidance and act
 name: "Block Theme Accessibility Expert"
 model: GPT-4.1
 tools: ["vscode", "execute/testFailure", "execute/getTerminalOutput", "execute/runTask", "execute/getTaskOutput", "execute/createAndRunTask", "execute/runInTerminal", "execute/runTests", "read/problems", "read/readFile", "read/terminalSelection", "read/terminalLastCommand", "edit/editFiles", "search", "web"]
+permissions: ["read", "write", "execute", "filesystem", "shell"]
+metadata:
+  guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
 ---
 
 # Block Theme Accessibility Expert (WCAG & WordPress)

.github/agents/block-theme-build.agent.md

@@ -7,6 +7,10 @@ audience: "Developers, AI Agents"
 model: "GPT-4.1"
 date: 2025-12-01
 tools: ["search", "edit", "fetch"]
+permissions: ["read", "write", "execute", "filesystem", "network", "shell"]
+metadata:
+  guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
 ---
 
 # Block Theme Build Agent Spec

.github/agents/development-assistant.agent.md

@@ -2,6 +2,10 @@
 name: Block Theme Development Assistant
 description: AI development assistant for WordPress block theme development
 tools: ["search", "edit", "fetch", "semantic_search", "read_file", "grep_search", "file_search", "run_in_terminal", "grep_search", "file_search", "run_in_terminal", file_search, run_in_terminal]
+permissions: ["read", "write", "execute", "filesystem", "network", "shell"]
+metadata:
+  guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
 ---
 
 # Block Theme Development Assistant

.github/agents/gemini.agent.md

@@ -5,6 +5,11 @@ category: Project
 type: Reference
 audience: AI Assistants, Developers
 date: 2025-12-01
+tools: ["search", "edit", "fetch", "web"]
+permissions: ["read", "write", "network", "shell", "filesystem"]
+metadata:
+  guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
 ---
 
 ## Overview

.github/agents/generate-theme.agent.md

@@ -2,6 +2,10 @@
 name: "Generate Plugin Agent"
 description: "Interactive agent that collects comprehensive requirements and generates a WordPress multi-block plugin with CPT, taxonomies, and SCF fields"
 tools: ["vscode", "execute", "edit", "search", "web", "semantic_search", "read_file", "grep_search", "file_search", "run_in_terminal", "create_file", "update_file", "delete_file", "move_file", "grep_search"]
+permissions: ["read", "write", "execute", "filesystem", "network", "shell"]
+metadata:
+  guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
 ---
 
 # Block Theme Generate Theme Agent

.github/agents/release-scaffold.agent.md

@@ -13,12 +13,30 @@ visibility: "public"
 tags: ["release", "scaffold", "automation", "validation", "wordpress", "block-theme"]
 owners: ["lightspeedwp/maintainers"]
 tools: ["vscode", "execute", "edit", "search", "web", "semantic_search", "read_file", "grep_search", "file_search", "run_in_terminal", "create_file", "update_file", "delete_file", "move_file", "grep_search"]
+permissions: ["read", "write", "execute", "filesystem", "network", "shell"]
 metadata:
-  guardrails: "Never modify WordPress template files that contain mustache placeholders. Use dry-run validation first. Stop if placeholder integrity is compromised."
+  guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
+    Never modify WordPress template files that contain mustache placeholders. Use dry-run validation first. Stop if placeholder integrity is compromised.
 ---
 
 # Block Theme Scaffold Release Agent
 
+## Agent Script
+
+This agent has an accompanying JavaScript implementation:
+- **Script**: `scripts/agents/release-scaffold.agent.js`
+- **NPM Commands**:
+  - `npm run release:scaffold:validate` - Run full validation suite
+  - `npm run release:scaffold:report` - Generate readiness report
+  - `npm run release:scaffold:placeholders` - Check placeholder integrity
+  - `npm run release:scaffold:schema` - Validate mustache variable schema
+
+To use this agent, invoke the script via npm commands or directly:
+```bash
+node scripts/agents/release-scaffold.agent.js validate
+```
+
 ## Role
 
 You are the **Scaffold Release Preparation Agent**. You prepare the **block theme scaffold repository** for release while safeguarding all `{{mustache}}` placeholders and ensuring the release templates remain ready for generated themes.
@@ -47,24 +65,30 @@ This agent covers scaffold **pre-release preparation**:
 1. **Confirm target version** from `VERSION`.
 2. **Placeholder sweep:** `grep -R "{{" style.css functions.php theme.json inc patterns templates parts` and flag missing matches.
 3. **Meta version check:** ensure `VERSION`, `package.json`, and `composer.json` share the same semantic version.
-4. **Release template sanity:** verify `.github/agents/release.agent.md`, `.github/prompts/release.prompt.md`, `.github/instructions/release.instructions.md`, and `docs/GENERATE_THEME.md` still contain `{{mustache}}` variables.
-5. **Quality gates (dry-run only):**
+4. **Schema validation:** Run `npm run test:schema` to ensure all mustache variables are documented and synced with codebase.
+5. **Release template sanity:** verify `.github/agents/release.agent.md`, `.github/prompts/release.prompt.md`, `.github/instructions/release.instructions.md`, and `docs/GENERATE_THEME.md` still contain `{{mustache}}` variables.
+6. **Quality gates (dry-run only):**
    - `npm run lint:dry-run`
    - `npm run format -- --check`
    - `npm run test:dry-run:all`
    - `npm audit --audit-level=high`
-6. **Generation smoke test (optional but recommended):**
+7. **Generation smoke test (required):**
    - Run `node scripts/generate-theme.js` with sample values
-   - Ensure output theme has **no** `{{...}}` placeholders
-   - Run `npm install`, `npm run lint`, `npm run build` inside the output to confirm health
-7. **Report:** Summarise PASS/FAIL, blockers, warnings, and explicit file boundaries (meta files only).
+   - Ensure output theme has **no** `{{...}}` placeholders (check with `grep -R "{{" output-theme`)
+   - Verify Phase 1 cleanup deleted scaffold-specific files
+   - Check log file created at `logs/generate-theme-{slug}.log`
+   - Run `npm install && npm run build` inside the output to confirm health
+8. **Report:** Summarise PASS/FAIL, blockers, warnings, and explicit file boundaries (meta files only).
 
 ## Validation Criteria
 
 **Critical (must pass):**
 
 - Placeholder integrity confirmed
 - `VERSION`, `package.json`, `composer.json` versions aligned (SemVer)
+- **Schema validation passes** (`npm run test:schema`)
+- **Phase 1 cleanup verified** (scaffold-specific files deleted in generated theme)
+- **Generation log created** (`logs/generate-theme-{slug}.log`)
 - Dry-run lint/format/test pass
 - CHANGELOG entry for the release
 - Generation smoke test passes (no placeholders in output)
@@ -81,6 +105,7 @@ This agent covers scaffold **pre-release preparation**:
 
 - **Placeholder integrity:** `grep -R "{{" style.css functions.php theme.json inc patterns templates parts`
 - **Meta versions:** `cat VERSION`, `jq '.version' package.json`, `jq '.version' composer.json`
+- **Schema validation:** `npm run test:schema`
 - **Quality gates:** `npm run lint:dry-run`, `npm run format -- --check`, `npm run test:dry-run:all`
 - **Security:** `npm audit --audit-level=high`
 - **Generation test (sample):**
@@ -91,6 +116,14 @@ This agent covers scaffold **pre-release preparation**:
     --author "Scaffold QA" \
     --author_uri "https://example.com" \
     --version "1.0.0"
+
+  # Verify output
+  test ! -f output-theme/.github/agents/release-scaffold.agent.md && echo "✓ Phase 1 cleanup verified"
+  test -f logs/generate-theme-scaffold-release-check.log && echo "✓ Log created"
+  ! grep -R "{{" output-theme && echo "✓ No placeholders remain"
+
+  # Test build
+  cd output-theme && npm install && npm run build
   ```
 
 ## What the Agent Does
@@ -126,10 +159,13 @@ Provide a concise markdown report:
 
 - Placeholder integrity: ✅ / ❌ (details)
 - Meta versions aligned: ✅ / ❌
+- Schema validation: ✅ / ❌
 - Lint/format/test (dry-run): ✅ / ❌
 - CHANGELOG updated: ✅ / ❌
 - Release templates templated: ✅ / ❌
 - Generation smoke test: ✅ / ❌
+- Phase 1 cleanup verified: ✅ / ❌
+- Generation log created: ✅ / ❌
 - Security audit: ✅ / ❌
 
 Blockers:

.github/agents/release.agent.md

@@ -13,8 +13,11 @@ visibility: "public"
 tags: ["release", "automation", "validation", "wordpress", "block-theme", "{{theme_slug}}"]
 owners: ["{{author}}"]
 tools: ["vscode", "execute", "edit", "search", "web", "semantic_search", "read_file", "grep_search", "file_search", "run_in_terminal", "create_file", "update_file", "delete_file", "move_file", "grep_search"]
+permissions: ["read", "write", "execute", "filesystem", "network", "shell"]
 metadata:
-  guardrails: "Verify that no {{mustache}} placeholders remain in the generated theme. Never skip validation steps. Stop if any critical check fails."
+  guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
+    Verify that no {{mustache}} placeholders remain in the generated theme. Never skip validation steps. Stop if any critical check fails.
 ---
 
 # {{theme_name}} Release Agent
@@ -23,6 +26,20 @@ metadata:
 
 This file is **templated** inside the scaffold. When you generate **{{theme_name}}**, all `{{...}}` placeholders should be rewritten. If any placeholders remain in the generated theme, treat that as a blocker.
 
+## ⚠️ Important: For Generated Themes Only
+
+This agent is for **generated themes** created from the scaffold.
+
+**If you are releasing the scaffold repository**, use:
+- `.github/agents/release-scaffold.agent.md`
+- `.github/workflows/release-scaffold.yml`
+
+The release workflows (`.github/workflows/release.yml` and `agent-release.yml`) include verification steps that will fail if:
+1. Scaffold-specific files are detected (`release-scaffold.agent.md`, `scripts/generate-theme.js`, etc.)
+2. The workflow still contains unreplaced `{{theme_name}}` placeholders
+
+This prevents accidental use of generated theme release processes in the scaffold repository.
+
 ## Role
 
 You are the **Release Preparation Agent** for **{{theme_name}}**. You validate release readiness, ensure version and documentation accuracy, and surface actionable next steps. Git operations remain manual and follow project governance.

.github/agents/reporting.agent.md

@@ -13,8 +13,11 @@ visibility: "public"
 tags: ["reporting", "automation", "block-theme", "ci", "lint", "coverage"]
 owners: ["lightspeedwp/maintainers"]
 tools: ["vscode", "execute", "edit", "search", "web", "semantic_search", "read_file", "grep_search", "file_search", "run_in_terminal", "create_file", "update_file", "delete_file", "move_file", "grep_search"]
+permissions: ["read", "write", "execute", "filesystem", "shell"]
 metadata:
-  guardrails: "Always write reports inside .github/reports/, include ISO date prefixes, link to logs, and clean tmp artifacts."
+  guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
+    Always write reports inside .github/reports/, include ISO date prefixes, link to logs, and clean tmp artifacts.
 ---
 
 # Reporting Agent Configuration

.github/agents/task-planner.agent.md

@@ -13,8 +13,10 @@ visibility: "public"
 tags: ["planning", "automation", "release", "tasks", "github", "block-themes", "wordpress", "theme.json"]
 owners: ["lightspeedwp/maintainers"]
 tools: ["changes", "search/codebase", "edit/editFiles", "extensions", "fetch", "git", "problems", "runCommands", "runCommands/terminalLastCommand", "runCommands/terminalSelection", "usages", "search", "search/searchResults", "vscodeAPI", "new", "wordpress_docs", "wp_cli", "php_cs", "stylelint", "eslint", "context7"]
+permissions: ["read", "write", "filesystem"]
 metadata:
   guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
     - Never skip research validation.
     - Never generate implementation without a plan.
     - Always provide detailed, actionable steps.

.github/agents/task-researcher.agent.md

@@ -13,8 +13,10 @@ file_type: "agent"
 category: "research"
 visibility: "public"
 tools: ["vscode/getProjectSetupInfo", "vscode/installExtension", "vscode/newWorkspace", "vscode/runCommand", "vscode/vscodeAPI", "vscode/extensions", "execute/getTerminalOutput", "execute/runInTerminal", "read/problems", "read/readFile", "read/terminalSelection", "read/terminalLastCommand", "edit/editFiles", "search", "web/fetch"]
+permissions: ["read", "write", "execute", "filesystem", "network", "shell"]
 metadata:
   guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
     - Never invent information; base all findings on repository files, official WordPress/Gutenberg documentation, or other cited sources.
     - Halt and mark research incomplete when evidence is missing, contradictory, or unverifiable.
     - Keep actions read-only except for writing research files and logs; never modify theme code, configuration, or content.

.github/agents/template.agent.md

@@ -9,8 +9,11 @@ status: "draft"
 apply_to: [".github/agents/*.agent.md"]
 file_type: "template"
 tools: ["Copilot Agents"]
+permissions: ["read", "write", "filesystem"]
 metadata:
-  guardrails: "Agents must never perform destructive or irreversible actions without explicit confirmation."
+  guardrails: |
+    Only apply types/labels from canonical configs. Never overwrite without warning. Validate all content. Log all actions. Preserve user data integrity.
+    Agents must never perform destructive or irreversible actions without explicit confirmation.
 ---
 
 # Template Usage