@lucapimenta/copy-chief-black 1.0.0

package/framework/.aios-core/core/synapse/diagnostics/collectors/consistency-collector.js

@@ -0,0 +1,357 @@
+'use strict';
+
+/**
+ * Consistency Collector — Copy Chief BLACK Edition
+ *
+ * Cross-validates system state for inconsistencies across 4 checks:
+ *
+ * 1. Bracket consistency — hook-metrics.json bracket is a known valid value
+ * 2. Agent consistency — active-agents.json IDs match known agents in core-config.yaml
+ * 3. Timestamp consistency — hook-metrics.json and active-agents.json are <10min apart
+ * 4. Config consistency — core-config.yaml is parseable and has required top-level sections
+ *
+ * @module core/synapse/diagnostics/collectors/consistency-collector
+ * @version 2.0.0
+ * @adapted Copy Chief BLACK (from Synkra AIOS Core SYN-14)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const yaml = require('js-yaml');
+
+const HOME = os.homedir();
+
+/** Maximum acceptable age gap between metrics files (ms). */
+const MAX_TIMESTAMP_GAP_MS = 10 * 60 * 1000; // 10 minutes
+
+/** Valid bracket values. */
+const VALID_BRACKETS = ['FRESH', 'MODERATE', 'DEPLETED', 'CRITICAL'];
+
+/** Required top-level sections in core-config.yaml. */
+const REQUIRED_CONFIG_SECTIONS = ['project', 'agents', 'quality_gates', 'synapse', 'paths'];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Safely read and parse a JSON file.
+ * @param {string} filePath
+ * @returns {object|null}
+ */
+function _safeReadJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Safely read and parse a YAML file.
+ * @param {string} filePath
+ * @returns {object|null}
+ */
+function _safeReadYaml(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return yaml.load(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Individual checks
+// ---------------------------------------------------------------------------
+
+/**
+ * Check 1: Bracket consistency.
+ * The bracket value in hook-metrics.json must be one of the 4 valid values.
+ *
+ * @param {object|null} hookData - Parsed hook-metrics.json
+ * @returns {{ name: string, status: string, detail: string }}
+ */
+function _checkBracket(hookData) {
+  if (!hookData) {
+    return {
+      name: 'bracket-consistency',
+      status: 'WARN',
+      detail: 'hook-metrics.json not found — cannot verify bracket',
+    };
+  }
+
+  const bracket = hookData.bracket;
+  if (VALID_BRACKETS.includes(bracket)) {
+    return {
+      name: 'bracket-consistency',
+      status: 'PASS',
+      detail: `bracket "${bracket}" is valid`,
+    };
+  }
+
+  return {
+    name: 'bracket-consistency',
+    status: 'FAIL',
+    detail: `bracket "${bracket || 'undefined'}" is not one of: ${VALID_BRACKETS.join(', ')}`,
+  };
+}
+
+/**
+ * Check 2: Agent consistency.
+ * Active agents in active-agents.json must be registered in core-config.yaml agents section.
+ *
+ * @param {object|null} activeAgents - Parsed active-agents.json
+ * @param {object|null} coreConfig - Parsed core-config.yaml
+ * @returns {{ name: string, status: string, detail: string }}
+ */
+function _checkAgents(activeAgents, coreConfig) {
+  if (!activeAgents) {
+    return {
+      name: 'agent-consistency',
+      status: 'WARN',
+      detail: 'active-agents.json not found — no active agents',
+    };
+  }
+
+  if (!coreConfig || !coreConfig.agents) {
+    return {
+      name: 'agent-consistency',
+      status: 'WARN',
+      detail: 'core-config.yaml agents section missing — cannot validate',
+    };
+  }
+
+  const activeIds = Object.keys(activeAgents);
+  if (activeIds.length === 0) {
+    return {
+      name: 'agent-consistency',
+      status: 'PASS',
+      detail: 'no active agents (idle session)',
+    };
+  }
+
+  const knownAgents = Object.keys(coreConfig.agents);
+  const unknown = activeIds.filter(id => !knownAgents.includes(id));
+
+  if (unknown.length === 0) {
+    return {
+      name: 'agent-consistency',
+      status: 'PASS',
+      detail: `${activeIds.length} active agent(s) all registered: ${activeIds.join(', ')}`,
+    };
+  }
+
+  return {
+    name: 'agent-consistency',
+    status: 'FAIL',
+    detail: `unknown agent(s) in active-agents.json: ${unknown.join(', ')} (not in core-config.yaml)`,
+  };
+}
+
+/**
+ * Check 3: Timestamp consistency.
+ * active-agents.json activation timestamps vs hook-metrics.json timestamp
+ * should be within MAX_TIMESTAMP_GAP_MS (agent activated -> hook ran soon after).
+ *
+ * @param {object|null} activeAgents - Parsed active-agents.json
+ * @param {object|null} hookData - Parsed hook-metrics.json
+ * @returns {{ name: string, status: string, detail: string }}
+ */
+function _checkTimestamps(activeAgents, hookData) {
+  if (!activeAgents || !hookData) {
+    return {
+      name: 'timestamp-consistency',
+      status: 'WARN',
+      detail: 'missing metrics file(s) — cannot check timestamp alignment',
+    };
+  }
+
+  const hookTs = hookData.timestamp ? new Date(hookData.timestamp).getTime() : null;
+  if (!hookTs) {
+    return {
+      name: 'timestamp-consistency',
+      status: 'WARN',
+      detail: 'hook-metrics.json has no timestamp field',
+    };
+  }
+
+  // Find the most recent agent activation
+  const activeIds = Object.keys(activeAgents);
+  if (activeIds.length === 0) {
+    return {
+      name: 'timestamp-consistency',
+      status: 'PASS',
+      detail: 'no active agents to compare',
+    };
+  }
+
+  let latestActivation = 0;
+  let latestAgent = null;
+  for (const id of activeIds) {
+    const ts = activeAgents[id].activatedAt || 0;
+    if (ts > latestActivation) {
+      latestActivation = ts;
+      latestAgent = id;
+    }
+  }
+
+  if (latestActivation === 0) {
+    return {
+      name: 'timestamp-consistency',
+      status: 'WARN',
+      detail: 'active-agents.json entries have no activatedAt timestamps',
+    };
+  }
+
+  // hook-metrics updates every prompt, agent activates once — hook should be >= agent
+  const gapMs = Math.abs(hookTs - latestActivation);
+  const gapSec = Math.round(gapMs / 1000);
+
+  if (gapMs <= MAX_TIMESTAMP_GAP_MS) {
+    return {
+      name: 'timestamp-consistency',
+      status: 'PASS',
+      detail: `hook-metrics vs @${latestAgent} activation: ${gapSec}s apart (within ${MAX_TIMESTAMP_GAP_MS / 60000}min)`,
+    };
+  }
+
+  return {
+    name: 'timestamp-consistency',
+    status: 'WARN',
+    detail: `hook-metrics vs @${latestAgent} activation: ${gapSec}s apart (exceeds ${MAX_TIMESTAMP_GAP_MS / 60000}min threshold — stale session?)`,
+  };
+}
+
+/**
+ * Check 4: Config consistency.
+ * core-config.yaml must be parseable and contain required sections.
+ *
+ * @param {object|null} coreConfig - Parsed core-config.yaml (null = parse failed)
+ * @param {string} configPath - Path used for error message
+ * @returns {{ name: string, status: string, detail: string }}
+ */
+function _checkConfig(coreConfig, configPath) {
+  if (!fs.existsSync(configPath)) {
+    return {
+      name: 'config-consistency',
+      status: 'FAIL',
+      detail: `core-config.yaml not found at ${configPath}`,
+    };
+  }
+
+  if (!coreConfig) {
+    return {
+      name: 'config-consistency',
+      status: 'FAIL',
+      detail: 'core-config.yaml exists but failed to parse (invalid YAML)',
+    };
+  }
+
+  const missing = REQUIRED_CONFIG_SECTIONS.filter(section => !coreConfig[section]);
+  if (missing.length === 0) {
+    const agentCount = coreConfig.agents ? Object.keys(coreConfig.agents).length : 0;
+    return {
+      name: 'config-consistency',
+      status: 'PASS',
+      detail: `all required sections present, ${agentCount} agents registered`,
+    };
+  }
+
+  return {
+    name: 'config-consistency',
+    status: 'FAIL',
+    detail: `missing required sections: ${missing.join(', ')}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main collector
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect cross-system consistency checks.
+ *
+ * @param {string} projectRoot - Absolute path to copywriting-ecosystem root
+ * @returns {{
+ *   name: string,
+ *   status: string,
+ *   data: {
+ *     available: boolean,
+ *     checks: Array<{ name: string, status: string, detail: string }>,
+ *     score: number,
+ *     maxScore: number
+ *   },
+ *   message: string
+ * }}
+ */
+function collectConsistencyMetrics(projectRoot) {
+  const hookData = _safeReadJson(
+    path.join(projectRoot, '.synapse', 'metrics', 'hook-metrics.json')
+  );
+  const activeAgents = _safeReadJson(
+    path.join(HOME, '.claude', 'session-state', 'active-agents.json')
+  );
+  const configPath = path.join(HOME, '.claude', '.aios-core', 'core-config.yaml');
+  const coreConfig = _safeReadYaml(configPath);
+
+  const checks = [];
+  let score = 0;
+  const maxScore = 4;
+
+  const bracketCheck = _checkBracket(hookData);
+  checks.push(bracketCheck);
+  if (bracketCheck.status === 'PASS') score++;
+
+  const agentCheck = _checkAgents(activeAgents, coreConfig);
+  checks.push(agentCheck);
+  if (agentCheck.status === 'PASS') score++;
+
+  const tsCheck = _checkTimestamps(activeAgents, hookData);
+  checks.push(tsCheck);
+  if (tsCheck.status === 'PASS') score++;
+
+  const configCheck = _checkConfig(coreConfig, configPath);
+  checks.push(configCheck);
+  if (configCheck.status === 'PASS') score++;
+
+  // Overall status: any FAIL = FAIL, any WARN = WARN, else OK
+  const hasFail = checks.some(c => c.status === 'FAIL');
+  const hasWarn = checks.some(c => c.status === 'WARN');
+  const status = hasFail ? 'FAIL' : hasWarn ? 'WARN' : 'OK';
+
+  const failCount = checks.filter(c => c.status === 'FAIL').length;
+  const warnCount = checks.filter(c => c.status === 'WARN').length;
+
+  let message;
+  if (status === 'OK') {
+    message = `${score}/${maxScore} checks passed`;
+  } else {
+    const parts = [];
+    if (failCount > 0) parts.push(`${failCount} fail`);
+    if (warnCount > 0) parts.push(`${warnCount} warn`);
+    message = `${score}/${maxScore} checks passed (${parts.join(', ')})`;
+  }
+
+  return {
+    name: 'consistency',
+    status,
+    data: {
+      available: true,
+      checks,
+      score,
+      maxScore,
+    },
+    message,
+  };
+}
+
+module.exports = {
+  collectConsistencyMetrics,
+  MAX_TIMESTAMP_GAP_MS,
+  VALID_BRACKETS,
+  REQUIRED_CONFIG_SECTIONS,
+};

package/framework/.aios-core/core/synapse/diagnostics/collectors/hook-collector.js

@@ -0,0 +1,254 @@
+'use strict';
+
+/**
+ * Hook Collector — Copy Chief BLACK Edition
+ *
+ * Reads heartbeat files from ~/.claude/.hook-health/ to report the health
+ * status of each wired hook in the Copy Chief BLACK ecosystem.
+ *
+ * Heartbeat files are written by hooks themselves via writeHeartbeat()
+ * (from copy-chief/health/checks/hooks-heartbeat.js pattern).
+ * Each file: { last_success, last_error, last_error_message, error_count, total_runs }
+ *
+ * Staleness threshold: >30min since last success = STALE (WARN).
+ * Absence of heartbeat dir: WARN (hooks may not be instrumented).
+ *
+ * @module core/synapse/diagnostics/collectors/hook-collector
+ * @version 2.0.0
+ * @adapted Copy Chief BLACK (from Synkra AIOS Core SYN-13)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const HOME = os.homedir();
+
+/** Path to hook heartbeat directory. */
+const HEARTBEAT_DIR = path.join(HOME, '.claude', '.hook-health');
+
+/** Stale threshold — hooks not seen in this window are flagged as stale. */
+const STALE_THRESHOLD_MS = 30 * 60 * 1000; // 30 minutes
+
+/**
+ * Read a single heartbeat file safely.
+ * @param {string} filePath
+ * @returns {object|null}
+ */
+function _readHeartbeat(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compute a per-hook status from its heartbeat data.
+ *
+ * @param {string} hookName - Hook name (filename without .json)
+ * @param {object|null} data - Parsed heartbeat data
+ * @param {number} now - Current timestamp in ms
+ * @returns {{
+ *   hookName: string,
+ *   status: 'OK' | 'WARN' | 'FAIL' | 'UNKNOWN',
+ *   lastSuccess: string|null,
+ *   lastError: string|null,
+ *   errorCount: number,
+ *   totalRuns: number,
+ *   stale: boolean,
+ *   ageMs: number,
+ *   detail: string
+ * }}
+ */
+function _evaluateHook(hookName, data, now) {
+  if (!data) {
+    return {
+      hookName,
+      status: 'UNKNOWN',
+      lastSuccess: null,
+      lastError: null,
+      errorCount: 0,
+      totalRuns: 0,
+      stale: false,
+      ageMs: 0,
+      detail: 'heartbeat file unreadable or corrupt',
+    };
+  }
+
+  const lastSuccessTs = data.last_success ? new Date(data.last_success).getTime() : 0;
+  const ageMs = lastSuccessTs > 0 ? now - lastSuccessTs : Infinity;
+  const stale = ageMs > STALE_THRESHOLD_MS;
+  const errorCount = data.error_count || 0;
+  const totalRuns = data.total_runs || 0;
+
+  let status = 'OK';
+  let detail;
+
+  if (errorCount > 0 && lastSuccessTs === 0) {
+    // Never succeeded — only errors
+    status = 'FAIL';
+    detail = `${errorCount} error(s), never succeeded. Last: ${data.last_error_message || 'unknown'}`;
+  } else if (stale && lastSuccessTs === 0) {
+    status = 'WARN';
+    detail = 'never fired successfully';
+  } else if (stale) {
+    status = 'WARN';
+    const ageMin = Math.round(ageMs / 60000);
+    detail = `stale — last success ${ageMin}min ago`;
+  } else if (errorCount > 0) {
+    status = 'WARN';
+    const ageMin = lastSuccessTs > 0 ? Math.round(ageMs / 60000) : null;
+    detail = `${errorCount} recent error(s)${ageMin !== null ? `, last success ${ageMin}min ago` : ''}`;
+  } else {
+    const ageMin = Math.round(ageMs / 60000);
+    detail = `healthy, last success ${ageMin}min ago (${totalRuns} total runs)`;
+  }
+
+  return {
+    hookName,
+    status,
+    lastSuccess: data.last_success || null,
+    lastError: data.last_error || null,
+    errorCount,
+    totalRuns,
+    stale,
+    ageMs: ageMs === Infinity ? -1 : ageMs,
+    detail,
+  };
+}
+
+/**
+ * Collect hook heartbeat data from ~/.claude/.hook-health/.
+ *
+ * @param {string} _projectRoot - Unused (hooks are global, not per-project)
+ * @returns {{
+ *   name: string,
+ *   status: string,
+ *   data: {
+ *     available: boolean,
+ *     heartbeatDir: string,
+ *     hooks: Array,
+ *     totalHooks: number,
+ *     healthyCount: number,
+ *     warnCount: number,
+ *     failCount: number,
+ *     staleCount: number
+ *   },
+ *   message: string
+ * }}
+ */
+function collectHookHeartbeats(_projectRoot) {
+  const now = Date.now();
+
+  if (!fs.existsSync(HEARTBEAT_DIR)) {
+    return {
+      name: 'hooks',
+      status: 'WARN',
+      data: {
+        available: false,
+        heartbeatDir: HEARTBEAT_DIR,
+        hooks: [],
+        totalHooks: 0,
+        healthyCount: 0,
+        warnCount: 0,
+        failCount: 0,
+        staleCount: 0,
+      },
+      message: `Heartbeat directory not found at ${HEARTBEAT_DIR} — hooks may not be instrumented`,
+    };
+  }
+
+  let files;
+  try {
+    files = fs.readdirSync(HEARTBEAT_DIR).filter(f => f.endsWith('.json'));
+  } catch (err) {
+    return {
+      name: 'hooks',
+      status: 'WARN',
+      data: {
+        available: false,
+        heartbeatDir: HEARTBEAT_DIR,
+        hooks: [],
+        totalHooks: 0,
+        healthyCount: 0,
+        warnCount: 0,
+        failCount: 0,
+        staleCount: 0,
+      },
+      message: `Cannot read heartbeat directory: ${err.message}`,
+    };
+  }
+
+  if (files.length === 0) {
+    return {
+      name: 'hooks',
+      status: 'WARN',
+      data: {
+        available: true,
+        heartbeatDir: HEARTBEAT_DIR,
+        hooks: [],
+        totalHooks: 0,
+        healthyCount: 0,
+        warnCount: 0,
+        failCount: 0,
+        staleCount: 0,
+      },
+      message: 'No hook heartbeat files found — hooks have not fired yet this session',
+    };
+  }
+
+  const hooks = files.map(file => {
+    const hookName = file.replace('.json', '');
+    const filePath = path.join(HEARTBEAT_DIR, file);
+    const data = _readHeartbeat(filePath);
+    return _evaluateHook(hookName, data, now);
+  });
+
+  // Sort: FAIL first, then WARN, then OK
+  hooks.sort((a, b) => {
+    const order = { FAIL: 0, WARN: 1, UNKNOWN: 2, OK: 3 };
+    return (order[a.status] ?? 4) - (order[b.status] ?? 4);
+  });
+
+  const totalHooks = hooks.length;
+  const failCount = hooks.filter(h => h.status === 'FAIL').length;
+  const warnCount = hooks.filter(h => h.status === 'WARN').length;
+  const healthyCount = hooks.filter(h => h.status === 'OK').length;
+  const staleCount = hooks.filter(h => h.stale).length;
+
+  const status = failCount > 0 ? 'FAIL' : warnCount > 0 ? 'WARN' : 'OK';
+
+  let message;
+  if (status === 'OK') {
+    message = `${totalHooks} hook(s) healthy`;
+  } else {
+    const parts = [];
+    if (failCount > 0) parts.push(`${failCount} failing`);
+    if (warnCount > 0) parts.push(`${warnCount} warn`);
+    if (staleCount > 0) parts.push(`${staleCount} stale`);
+    message = `${healthyCount}/${totalHooks} healthy (${parts.join(', ')})`;
+  }
+
+  return {
+    name: 'hooks',
+    status,
+    data: {
+      available: true,
+      heartbeatDir: HEARTBEAT_DIR,
+      hooks,
+      totalHooks,
+      healthyCount,
+      warnCount,
+      failCount,
+      staleCount,
+    },
+    message,
+  };
+}
+
+module.exports = {
+  collectHookHeartbeats,
+  HEARTBEAT_DIR,
+  STALE_THRESHOLD_MS,
+};

package/framework/.aios-core/core/synapse/diagnostics/collectors/manifest-collector.js

@@ -0,0 +1,82 @@
+/**
+ * Manifest Collector — Validates manifest integrity vs. domain files.
+ *
+ * Checks:
+ * - Every domain in manifest has a corresponding file
+ * - Every domain file in .synapse/ has a manifest entry
+ *
+ * @module core/synapse/diagnostics/collectors/manifest-collector
+ * @version 1.0.0
+ * @created Story SYN-13
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseManifest } = require('../../domain/domain-loader');
+
+/**
+ * Collect manifest integrity data.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{ entries: Array<{ domain: string, inManifest: string, fileExists: boolean, status: string }>, orphanedFiles: string[] }}
+ */
+function collectManifestIntegrity(projectRoot) {
+  const synapsePath = path.join(projectRoot, '.synapse');
+  const manifestPath = path.join(synapsePath, 'manifest');
+  const entries = [];
+  const orphanedFiles = [];
+
+  // Parse manifest
+  const manifest = parseManifest(manifestPath);
+
+  // Check each domain in manifest has a file
+  for (const [_domainName, domainConfig] of Object.entries(manifest.domains)) {
+    const fileName = domainConfig.file;
+    const domainFilePath = path.join(synapsePath, fileName);
+    const fileExists = fs.existsSync(domainFilePath);
+
+    const stateInfo = domainConfig.state || 'unknown';
+    const triggers = [];
+    if (domainConfig.agentTrigger) triggers.push(`trigger=${domainConfig.agentTrigger}`);
+    if (domainConfig.workflowTrigger) triggers.push(`trigger=${domainConfig.workflowTrigger}`);
+    if (domainConfig.alwaysOn) triggers.push('ALWAYS_ON');
+
+    entries.push({
+      domain: fileName,
+      inManifest: `${stateInfo}${triggers.length ? ', ' + triggers.join(', ') : ''}`,
+      fileExists,
+      status: fileExists ? 'PASS' : 'FAIL',
+    });
+  }
+
+  // Check for orphaned domain files (files not in manifest)
+  const manifestFileNames = new Set(
+    Object.values(manifest.domains).map((d) => d.file),
+  );
+
+  try {
+    const allFiles = fs.readdirSync(synapsePath);
+    const domainFiles = allFiles.filter((f) => {
+      // Skip known non-domain files
+      if (f === 'manifest' || f === '.gitignore' || f.startsWith('.')) return false;
+      // Skip directories
+      const stat = fs.statSync(path.join(synapsePath, f));
+      if (stat.isDirectory()) return false;
+      return true;
+    });
+
+    for (const file of domainFiles) {
+      if (!manifestFileNames.has(file)) {
+        orphanedFiles.push(file);
+      }
+    }
+  } catch (_) {
+    // .synapse/ not readable
+  }
+
+  return { entries, orphanedFiles };
+}
+
+module.exports = { collectManifestIntegrity };