fix(ci): resolve anchor validation and extend experiments test coverage

Fix link_checker _text_to_anchor to match GitHub slugger behavior by
replacing each space individually instead of collapsing consecutive
whitespace. This resolves broken #security--compliance-patterns and
#monitoring--maintenance-patterns anchor validation.

Add 23 new tests covering experiments/README.md: pattern spec compliance,
Mermaid diagram validation, code block syntax, link integrity, and
examples index consistency. Add experimental_pattern_parser.py utility.

Fix notify-failure job: add issues:write permission and upgrade
actions/github-script from v6 to v7.

Add /xaudit-experiments slash command prompt for manual LLM-powered
deep audits of the experiments directory.

Author: PaulDuvall

.claude/prompts/xaudit-experiments.md

@@ -0,0 +1,36 @@
+Audit and fix the experiments/ directory (experiments/README.md, experiments/NOTES.md, and all experiments/examples/**/README.md plus their supporting files). Run these checks in parallel, then fix what you find:
+
+1. Runnable code audit: For every fenced code block (python, bash, yaml, json), verify:
+   - Python: imports exist in stdlib/PyPI, function signatures match real APIs, class definitions are syntactically valid. Flag datetime.utcnow(), Pydantic v1 syntax, and other deprecated calls.
+   - Bash: commands and flags are real (no fabricated CLI options). Verify referenced file paths (e.g., scripts/promote-test.sh, .ai/hooks/protect-golden.sh) exist on disk where claimed.
+   - YAML: valid syntax, correct GitHub Actions schema (uses: keys reference real actions at current major versions), Docker Compose v2 syntax (not v1 version: key).
+   - Mermaid: valid diagram syntax (matching graph/sequenceDiagram/flowchart keywords, balanced brackets, no dangling edges).
+   Prioritize anything that would fail if copy-pasted.
+
+2. Pattern spec compliance (against pattern-spec.md): Each pattern in experiments/README.md must have:
+   - Two-word Title Case name (per naming rules)
+   - Maturity, Description, Related Patterns fields
+   - At least one implementation section
+   - An Anti-pattern section
+   - All Related Patterns hyperlinked with working anchors
+   Flag any pattern missing required sections or violating naming rules.
+
+3. Internal consistency:
+   - Cross-check the experiments/examples/README.md index against actual subdirectories in experiments/examples/ (flag missing or extra entries).
+   - Verify that file references in any README (e.g., "see scripts/promote-test.sh") match actual filenames on disk.
+   - Check that Mermaid diagram node labels match the pattern names used in prose and the reference table.
+
+4. Link integrity: Verify every internal anchor link resolves correctly. Apply GitHub's anchor generation rules:
+   - lowercase, spaces to hyphens, strip punctuation except hyphens
+   - special chars like & are omitted (not double-dash)
+   - duplicate anchors get -1, -2 suffixes
+   Flag any broken anchor references.
+
+5. Security review of examples: In all Python, Bash, and YAML files under experiments/examples/:
+   - No hardcoded credentials, tokens, or API keys
+   - Shell scripts quote variables and validate inputs
+   - File operations check for path traversal (no unsanitized user input in open()/os.path.join())
+   - Claims of read-only or network_mode: none are actually enforced in the code/config
+   - File permission claims (e.g., chmod 444) match what the scripts actually set
+
+For each issue found, fix it directly in the file rather than just reporting it. After all fixes, provide a summary grouped by check category with file:line references.

.github/workflows/deploy-pages.yml

@@ -25,7 +25,7 @@ jobs:
         uses: actions/configure-pages@v4
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           path: '.'
 

.github/workflows/pattern-validation.yml

@@ -316,12 +316,14 @@ jobs:
   notify-failure:
     runs-on: ubuntu-latest
     name: Notify on Failure
+    permissions:
+      issues: write
     needs: [pattern-compliance, readme-accuracy, link-validation, example-validation, dependency-validation, diagram-validation, yaml-readme-sync]
     if: failure() && github.event_name == 'push' && github.ref == 'refs/heads/main'
-    
+
     steps:
     - name: Create Issue on Failure
-      uses: actions/github-script@v6
+      uses: actions/github-script@v7
       with:
         script: |
           const title = `Pattern Validation Failed - ${new Date().toISOString().split('T')[0]}`;

README.md

@@ -1268,6 +1268,8 @@ git worktree remove ../agent-tests
 **Shared Memory & Coordination**
 
 ```python
+import fcntl
+
 # Agent coordination with shared knowledge
 class AgentMemory:
     def record_learning(self, agent_id, key, value):
@@ -1760,15 +1762,15 @@ Combine with [Event Automation](#event-automation) to auto-load the right rules
 FILE_PATH="$TOOL_INPUT_FILE_PATH"
 LOADED_RULES=""
 
-if echo "$FILE_PATH" | rg -q "(\\.env|credentials|secrets|auth/)"; then
+if echo "$FILE_PATH" | grep -Eq "(\\.env|credentials|secrets|auth/)"; then
   LOADED_RULES="$LOADED_RULES .ai/rules/security/"
 fi
 
-if echo "$FILE_PATH" | rg -q "(api/|routes/|controllers/)"; then
+if echo "$FILE_PATH" | grep -Eq "(api/|routes/|controllers/)"; then
   LOADED_RULES="$LOADED_RULES .ai/rules/development/api-design.md"
 fi
 
-if echo "$FILE_PATH" | rg -q "(tests?/|spec/|\\.test\\.|\\.spec\\.)"; then
+if echo "$FILE_PATH" | grep -Eq "(tests?/|spec/|\\.test\\.|\\.spec\\.)"; then
   LOADED_RULES="$LOADED_RULES .ai/rules/development/testing.md"
 fi
 

examples/atomic-decomposition/task-decomposer.py

@@ -10,7 +10,7 @@
 import argparse
 import sys
 from datetime import datetime
-from typing import List, Dict, Any, Set
+from typing import Any
 from dataclasses import dataclass, asdict
 from pathlib import Path
 
@@ -20,15 +20,15 @@ class TaskContract:
     id: str
     name: str
     description: str
-    inputs: Dict[str, str]
-    outputs: Dict[str, str]
-    side_effects: List[str]
+    inputs: dict[str, str]
+    outputs: dict[str, str]
+    side_effects: list[str]
     estimated_hours: float
-    dependencies: List[str]
-    acceptance_criteria: List[str]
-    agent_requirements: List[str]
+    dependencies: list[str]
+    acceptance_criteria: list[str]
+    agent_requirements: list[str]
 
-    def validate_atomic(self) -> List[str]:
+    def validate_atomic(self) -> list[str]:
         """Validate that task meets atomic criteria."""
         violations = []
 
@@ -62,7 +62,7 @@ def __init__(self):
         self.min_hours = 0.5
         self.task_counter = 0
 
-    def decompose_feature(self, feature_description: str) -> List[TaskContract]:
+    def decompose_feature(self, feature_description: str) -> list[TaskContract]:
         """
         Decompose a feature into atomic tasks.
         
@@ -84,7 +84,7 @@ def decompose_feature(self, feature_description: str) -> List[TaskContract]:
         else:
             return self._decompose_generic(feature_description)
 
-    def _decompose_authentication(self, description: str) -> List[TaskContract]:
+    def _decompose_authentication(self, description: str) -> list[TaskContract]:
         """Decompose authentication system into atomic tasks."""
         tasks = []
 
@@ -204,7 +204,7 @@ def _decompose_authentication(self, description: str) -> List[TaskContract]:
 
         return tasks
 
-    def _decompose_payment(self, description: str) -> List[TaskContract]:
+    def _decompose_payment(self, description: str) -> list[TaskContract]:
         """Decompose payment processing into atomic tasks."""
         tasks = []
 
@@ -263,7 +263,7 @@ def _decompose_payment(self, description: str) -> List[TaskContract]:
 
         return tasks
 
-    def _decompose_dashboard(self, description: str) -> List[TaskContract]:
+    def _decompose_dashboard(self, description: str) -> list[TaskContract]:
         """Decompose dashboard feature into atomic tasks."""
         tasks = []
 
@@ -296,7 +296,7 @@ def _decompose_dashboard(self, description: str) -> List[TaskContract]:
 
         return tasks
 
-    def _decompose_generic(self, description: str) -> List[TaskContract]:
+    def _decompose_generic(self, description: str) -> list[TaskContract]:
         """Generic decomposition for unknown features."""
         tasks = []
 
@@ -326,7 +326,7 @@ def _next_task_id(self) -> str:
         self.task_counter += 1
         return f"task-{self.task_counter:03d}"
 
-    def validate_decomposition(self, tasks: List[TaskContract]) -> Dict[str, Any]:
+    def validate_decomposition(self, tasks: list[TaskContract]) -> dict[str, Any]:
         """Validate entire task decomposition for atomicity."""
         validation_report = {
             "total_tasks": len(tasks),
@@ -366,7 +366,7 @@ def validate_decomposition(self, tasks: List[TaskContract]) -> Dict[str, Any]:
 
         return validation_report
 
-    def optimize_for_parallelization(self, tasks: List[TaskContract]) -> List[TaskContract]:
+    def optimize_for_parallelization(self, tasks: list[TaskContract]) -> list[TaskContract]:
         """Analyze and suggest optimizations for better parallelization."""
         optimized_tasks = []
 
@@ -384,7 +384,7 @@ def optimize_for_parallelization(self, tasks: List[TaskContract]) -> List[TaskCo
 
         return optimized_tasks
 
-    def generate_execution_plan(self, tasks: List[TaskContract], num_agents: int = 3) -> Dict[str, Any]:
+    def generate_execution_plan(self, tasks: list[TaskContract], num_agents: int = 3) -> dict[str, Any]:
         """Generate execution plan for parallel agents."""
         # Simple topological sort for dependency ordering
         dependencies = {task.id: task.dependencies for task in tasks}

examples/guided-refactoring/quality-metrics.py

@@ -10,14 +10,14 @@
 import sys
 from datetime import datetime
 from pathlib import Path
-from typing import Dict, Any
+from typing import Any
 
 class QualityMetrics:
     def __init__(self, source_dir: str = "src"):
         self.source_dir = source_dir
         self.metrics_file = Path("quality_metrics.json")
 
-    def measure_complexity(self) -> Dict[str, Any]:
+    def measure_complexity(self) -> dict[str, Any]:
         """Measure cyclomatic complexity using radon."""
         try:
             result = subprocess.run(
@@ -50,7 +50,7 @@ def measure_complexity(self) -> Dict[str, Any]:
         except (subprocess.CalledProcessError, FileNotFoundError):
             return {"error": "radon not available"}
 
-    def measure_coverage(self) -> Dict[str, Any]:
+    def measure_coverage(self) -> dict[str, Any]:
         """Measure test coverage using coverage.py."""
         try:
             # Run tests with coverage
@@ -76,7 +76,7 @@ def measure_coverage(self) -> Dict[str, Any]:
         except (subprocess.CalledProcessError, FileNotFoundError):
             return {"error": "coverage not available"}
 
-    def measure_duplication(self) -> Dict[str, Any]:
+    def measure_duplication(self) -> dict[str, Any]:
         """Measure code duplication using pylint."""
         try:
             result = subprocess.run(
@@ -99,7 +99,7 @@ def measure_duplication(self) -> Dict[str, Any]:
         except (subprocess.CalledProcessError, FileNotFoundError, json.JSONDecodeError):
             return {"error": "pylint not available"}
 
-    def measure_maintainability(self) -> Dict[str, Any]:
+    def measure_maintainability(self) -> dict[str, Any]:
         """Measure maintainability index using radon."""
         try:
             result = subprocess.run(
@@ -136,7 +136,7 @@ def _grade_maintainability(self, mi_score: float) -> str:
         elif mi_score >= 25: return "D"
         else: return "F"
 
-    def collect_all_metrics(self) -> Dict[str, Any]:
+    def collect_all_metrics(self) -> dict[str, Any]:
         """Collect all quality metrics."""
         return {
             "timestamp": datetime.now().isoformat(),
@@ -201,7 +201,7 @@ def measure_improvement(self):
         # Calculate and display improvements
         self._display_improvements(baseline, current)
 
-    def _display_improvements(self, baseline: Dict, current: Dict):
+    def _display_improvements(self, baseline: dict, current: dict):
         """Display improvement comparison."""
         print("\n📊 Refactoring Impact Analysis")
         print("=" * 50)
@@ -246,7 +246,7 @@ def _display_improvements(self, baseline: Dict, current: Dict):
         print(f"\n✅ Metrics collected at: {current['timestamp']}")
         print(f"📁 Data saved to: {self.metrics_file}")
 
-    def _print_metrics_summary(self, metrics: Dict):
+    def _print_metrics_summary(self, metrics: dict):
         """Print a summary of current metrics."""
         print("\n📊 Current Quality Metrics")
         print("=" * 30)

examples/issue-generation/issue-generator.py

@@ -11,15 +11,15 @@
 import sys
 from datetime import datetime
 from pathlib import Path
-from typing import List, Dict, Any
+from typing import Any
 
 class KanbanIssueGenerator:
     def __init__(self):
         self.max_task_hours = 8
         self.min_task_hours = 2
         self.templates_dir = Path("kanban-templates")
 
-    def generate_feature_issues(self, feature_description: str, platform: str = "github") -> List[Dict[str, Any]]:
+    def generate_feature_issues(self, feature_description: str, platform: str = "github") -> list[dict[str, Any]]:
         """
         Generate Kanban-ready issues for a feature request.
         
@@ -51,7 +51,7 @@ def generate_feature_issues(self, feature_description: str, platform: str = "git
 
         return issues
 
-    def _create_epic_issue(self, feature_description: str, platform: str) -> Dict[str, Any]:
+    def _create_epic_issue(self, feature_description: str, platform: str) -> dict[str, Any]:
         """Create an epic-level issue for the feature."""
         template = self._load_template("epic", platform)
 
@@ -84,7 +84,7 @@ def _create_epic_issue(self, feature_description: str, platform: str) -> Dict[st
 
         return self._apply_platform_format(epic, platform)
 
-    def _break_down_feature(self, feature_description: str, platform: str) -> List[Dict[str, Any]]:
+    def _break_down_feature(self, feature_description: str, platform: str) -> list[dict[str, Any]]:
         """Break down feature into Kanban-optimized stories (4-8 hours each)."""
 
         # Example breakdown for "Password reset via email"
@@ -95,7 +95,7 @@ def _break_down_feature(self, feature_description: str, platform: str) -> List[D
         else:
             return self._generic_breakdown(feature_description, platform)
 
-    def _password_reset_breakdown(self, platform: str) -> List[Dict[str, Any]]:
+    def _password_reset_breakdown(self, platform: str) -> list[dict[str, Any]]:
         """Specific breakdown for password reset feature."""
         stories = [
             {
@@ -196,7 +196,7 @@ def _password_reset_breakdown(self, platform: str) -> List[Dict[str, Any]]:
 
         return [self._apply_platform_format(story, platform) for story in stories]
 
-    def _dashboard_breakdown(self, platform: str) -> List[Dict[str, Any]]:
+    def _dashboard_breakdown(self, platform: str) -> list[dict[str, Any]]:
         """Breakdown for dashboard features."""
         stories = [
             {
@@ -239,7 +239,7 @@ def _dashboard_breakdown(self, platform: str) -> List[Dict[str, Any]]:
 
         return [self._apply_platform_format(story, platform) for story in stories]
 
-    def _generic_breakdown(self, feature_description: str, platform: str) -> List[Dict[str, Any]]:
+    def _generic_breakdown(self, feature_description: str, platform: str) -> list[dict[str, Any]]:
         """Generic breakdown for unknown features."""
         stories = [
             {
@@ -288,7 +288,7 @@ def _generic_breakdown(self, feature_description: str, platform: str) -> List[Di
 
         return [self._apply_platform_format(story, platform) for story in stories]
 
-    def _generate_technical_tasks(self, feature_description: str, platform: str) -> List[Dict[str, Any]]:
+    def _generate_technical_tasks(self, feature_description: str, platform: str) -> list[dict[str, Any]]:
         """Generate supporting technical tasks."""
         tasks = [
             {
@@ -337,7 +337,7 @@ def _generate_technical_tasks(self, feature_description: str, platform: str) ->
 
         return [self._apply_platform_format(task, platform) for task in tasks]
 
-    def _apply_platform_format(self, issue: Dict[str, Any], platform: str) -> Dict[str, Any]:
+    def _apply_platform_format(self, issue: dict[str, Any], platform: str) -> dict[str, Any]:
         """Apply platform-specific formatting."""
         if platform == "github":
             return self._format_for_github(issue)
@@ -348,7 +348,7 @@ def _apply_platform_format(self, issue: Dict[str, Any], platform: str) -> Dict[s
         else:
             return issue
 
-    def _format_for_github(self, issue: Dict[str, Any]) -> Dict[str, Any]:
+    def _format_for_github(self, issue: dict[str, Any]) -> dict[str, Any]:
         """Format issue for GitHub Issues API."""
         github_issue = {
             "title": issue["title"],
@@ -364,7 +364,7 @@ def _format_for_github(self, issue: Dict[str, Any]) -> Dict[str, Any]:
 
         return github_issue
 
-    def _format_for_jira(self, issue: Dict[str, Any]) -> Dict[str, Any]:
+    def _format_for_jira(self, issue: dict[str, Any]) -> dict[str, Any]:
         """Format issue for JIRA API."""
         return {
             "fields": {
@@ -380,7 +380,7 @@ def _format_for_jira(self, issue: Dict[str, Any]) -> Dict[str, Any]:
             }
         }
 
-    def _format_for_azure(self, issue: Dict[str, Any]) -> Dict[str, Any]:
+    def _format_for_azure(self, issue: dict[str, Any]) -> dict[str, Any]:
         """Format issue for Azure DevOps API."""
         return {
             "op": "add",
@@ -394,15 +394,15 @@ def _format_for_azure(self, issue: Dict[str, Any]) -> Dict[str, Any]:
             }
         }
 
-    def _load_template(self, template_type: str, platform: str) -> Dict[str, Any]:
+    def _load_template(self, template_type: str, platform: str) -> dict[str, Any]:
         """Load issue template from file."""
         template_file = self.templates_dir / f"{template_type}-template.json"
         if template_file.exists():
             with open(template_file) as f:
                 return json.load(f)
         return {}
 
-    def validate_kanban_readiness(self, issues: List[Dict[str, Any]]) -> List[str]:
+    def validate_kanban_readiness(self, issues: list[dict[str, Any]]) -> list[str]:
         """Validate that issues meet Kanban flow criteria."""
         warnings = []