feat: Add telemetry instrumentation for release validation and metrics orchestration

.github/agentic-workflows/release.agent.js

@@ -23,6 +23,10 @@
 import fs from "fs";
 import path from "path";
 import { execSync } from "child_process";
+import {
+  createTelemetryClient,
+} from "../../scripts/telemetry/telemetry-client.js";
+import { EVENT_SCHEMAS } from "../../scripts/telemetry/event-schemas.js";
 
 // ============================================================================
 // Configuration
@@ -68,6 +72,12 @@ class ReleaseAgent {
     this.workflowId = `${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
     this.log = [];
     this.decisions = {};
+
+    // Initialize telemetry client
+    this.telemetry = createTelemetryClient({
+      eventSchemas: EVENT_SCHEMAS,
+    });
+    this.validationStartTime = null;
   }
 
   // ========================================================================
@@ -477,6 +487,21 @@ Respond with JSON:
 
   async execute() {
     try {
+      // Emit: release.validation.started
+      this.validationStartTime = Date.now();
+      this.telemetry.emit('release.validation.started', {
+        safe: {
+          component: 'release-agent',
+          version: '1.0.0',
+          trigger: this.dryRun ? 'dry-run' : 'manual'
+        },
+        restricted: {
+          repositoryName: this.getRepositoryName(),
+          changelogPath: CHANGELOG_FILE,
+          versionFile: VERSION_FILE
+        }
+      });
+
       // Step 1: Initialize & Pre-flight
       await this.initialize();
 
@@ -486,12 +511,43 @@ Respond with JSON:
       // Steps 3-9: Safety Gates
       const gatesPass = await this.runSafetyGates();
       if (!gatesPass) {
+        // Emit: release.gate.failure
+        this.telemetry.emit('release.gate.failure', {
+          safe: {
+            component: 'release-agent',
+            gateName: 'safety-gates',
+            failureReason: 'One or more safety gates failed',
+            recoverable: false
+          },
+          restricted: {
+            repositoryName: this.getRepositoryName(),
+            changelogPath: CHANGELOG_FILE,
+            errorDetails: 'Safety gates validation failed'
+          }
+        });
         throw new Error("❌ One or more safety gates failed. Release aborted.");
       }
 
       // Step 10: Report & Cleanup
       await this.report();
 
+      // Emit: release.validation.completed
+      const validationDuration = Date.now() - this.validationStartTime;
+      this.telemetry.emit('release.validation.completed', {
+        safe: {
+          component: 'release-agent',
+          version: this.nextVersion,
+          validationDuration,
+          gatesPassed: 7,
+          warningCount: 0
+        },
+        restricted: {
+          repositoryName: this.getRepositoryName(),
+          changelogPath: CHANGELOG_FILE,
+          validationResults: JSON.stringify(this.decisions)
+        }
+      });
+
       console.log("\n✅ MVP Workflow Complete!\n");
       console.log("Next Steps:");
       console.log("1. Review the generated report");
@@ -502,7 +558,39 @@ Respond with JSON:
     } catch (error) {
       console.error(`\n❌ Workflow Failed: ${error.message}\n`);
       this.addLog(`Error: ${error.message}`);
+
+      // Emit: release.gate.failure for unexpected errors
+      if (!error.message.includes('safety gates')) {
+        this.telemetry.emit('release.gate.failure', {
+          safe: {
+            component: 'release-agent',
+            gateName: 'execution',
+            failureReason: 'Unexpected error during release',
+            recoverable: false
+          },
+          restricted: {
+            repositoryName: this.getRepositoryName(),
+            errorDetails: error.message,
+            stackTrace: error.stack
+          }
+        });
+      }
+
       throw error;
+    } finally {
+      // Flush telemetry data
+      await this.telemetry.flush();
+    }
+  }
+
+  getRepositoryName() {
+    try {
+      // Get repository name from git remote
+      const remote = execSync('git remote get-url origin', { encoding: 'utf-8' }).trim();
+      const match = remote.match(/github\.com[:/](.+?)(?:\.git)?$/);
+      return match ? match[1] : 'unknown/unknown';
+    } catch (_e) {
+      return 'unknown/unknown';
     }
   }
 }

.github/instructions/file-organisation.instructions.md

@@ -90,10 +90,32 @@ projects, or plugin bundles.
 | `skills/` | Self-contained skills. | Each skill uses `SKILL.md`; assets stay inside the skill folder. |
 | `workflows/` | Portable agentic workflows. | GitHub Actions stay in `.github/workflows/`. |
 
+## Repository Scripts Location (CRITICAL)
+
+**ALL scripts belong in `scripts/` at the root, NOT in `.github/scripts/`.**
+
+| Script Type | Correct Location | WRONG Location |
+| --- | --- | --- |
+| Repository automation scripts | `scripts/automation/` | ❌ `.github/scripts/automation/` |
+| Metrics collection scripts | `scripts/metrics/` | ❌ `.github/scripts/metrics/` |
+| Telemetry scripts | `scripts/telemetry/` | ❌ `.github/scripts/telemetry/` |
+| Release scripts | `scripts/release/` | ❌ `.github/scripts/release/` |
+| Validation scripts | `scripts/validation/` | ❌ `.github/scripts/validation/` |
+| Badge generation scripts | `scripts/badges/` | ❌ `.github/scripts/badges/` |
+| **ONLY EXCEPTION:** Website browser scripts | `.github/website/src/scripts/` | ✅ Correct location for browser-specific code |
+
+**Rules:**
+- `.github/` is for GitHub-native governance files only (templates, workflows, configs)
+- All executable scripts belong in `scripts/` with appropriate subfolders
+- The ONLY exception is `.github/website/src/scripts/` for website browser code
+- When in doubt, check existing script locations in `scripts/` directory
+- Never create new scripts under `.github/scripts/` - this path should not exist
+
 ## File Type Mapping
 
 | File Type | Canonical Location | Rule |
 | --- | --- | --- |
+| **Repository scripts** | `scripts/{category}/` | **ALWAYS root `scripts/`, never `.github/scripts/`** |
 | Repo GitHub workflow | `.github/workflows/` | Keep executable GitHub Actions here. |
 | Portable agentic workflow | `workflows/` | Use for tool-neutral AI processes. |
 | Repo community-health file | `.github/` | Keep issue, PR, support, security, and governance files in place. |