@lucapimenta/copy-chief-black 1.0.0

package/framework/.aios-core/copy-chief/orchestration/helix-orchestrator.js

@@ -0,0 +1,403 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { OfferScanner } = require('./offer-scanner');
+
+const OfferPhase = {
+  IDLE: 'idle',
+  RESEARCH: 'research',
+  BRIEFING: 'briefing',
+  PRODUCTION: 'production',
+  REVIEW: 'review',
+  DELIVERED: 'delivered',
+};
+
+const CRASH_THRESHOLD_MINUTES = 30;
+
+const AGENT_MAP = {
+  vox: { file: 'vox.md', model: 'sonnet', title: 'VOC Researcher' },
+  cipher: { file: 'cipher.md', model: 'sonnet', title: 'Ads Miner' },
+  atlas: { file: 'atlas.md', model: 'opus', title: 'HELIX Briefer' },
+  echo: { file: 'echo.md', model: 'opus', title: 'VSL Director' },
+  forge: { file: 'forge.md', model: 'sonnet', title: 'LP Builder' },
+  scout: { file: 'scout.md', model: 'sonnet', title: 'Creative Producer' },
+  blade: { file: 'blade.md', model: 'sonnet', title: 'Email Producer' },
+  hawk: { file: 'hawk.md', model: 'sonnet', title: 'Copy Critic' },
+  sentinel: { file: 'sentinel.md', model: 'sonnet', title: 'Gate Keeper' },
+};
+
+const WORKFLOW_MAP = {
+  [OfferPhase.RESEARCH]: 'research-pipeline',
+  [OfferPhase.BRIEFING]: 'briefing-pipeline',
+  [OfferPhase.PRODUCTION]: 'production-pipeline',
+  [OfferPhase.REVIEW]: 'review-pipeline',
+};
+
+const ROUTING_TABLE = {
+  [OfferPhase.IDLE]: {
+    nextWorkflow: 'research-pipeline',
+    suggestedAgent: 'vox',
+    action: 'start_research',
+    message: 'Oferta em IDLE. Iniciar Research Pipeline com Vox.',
+  },
+  [OfferPhase.RESEARCH]: {
+    nextWorkflow: 'research-pipeline',
+    suggestedAgent: 'vox',
+    action: 'continue_research',
+    message: 'Research em andamento. Continuar Research Pipeline.',
+  },
+  [OfferPhase.BRIEFING]: {
+    nextWorkflow: 'briefing-pipeline',
+    suggestedAgent: 'atlas',
+    action: 'continue_briefing',
+    message: 'Briefing em andamento. Continuar HELIX Briefing com Atlas.',
+  },
+  [OfferPhase.PRODUCTION]: {
+    nextWorkflow: 'production-pipeline',
+    suggestedAgent: 'echo',
+    action: 'continue_production',
+    message: 'Production em andamento. Continuar Production Pipeline.',
+  },
+  [OfferPhase.REVIEW]: {
+    nextWorkflow: 'review-pipeline',
+    suggestedAgent: 'hawk',
+    action: 'continue_review',
+    message: 'Review em andamento. Hawk validando deliverables.',
+  },
+  [OfferPhase.DELIVERED]: {
+    nextWorkflow: null,
+    suggestedAgent: null,
+    action: 'show_summary',
+    message: 'Oferta entregue. Selecionar próxima oferta.',
+  },
+};
+
+class HelixOrchestrator {
+  constructor(ecosystemRoot, options = {}) {
+    if (!ecosystemRoot || typeof ecosystemRoot !== 'string') {
+      throw new Error('ecosystemRoot is required and must be a string');
+    }
+
+    this.ecosystemRoot = ecosystemRoot;
+    this.options = {
+      debug: false,
+      agentsDir: path.join(process.env.HOME, '.claude', 'agents'),
+      workflowsDir: path.join(ecosystemRoot, 'squads', 'copy-chief', 'workflows'),
+      ...options,
+    };
+
+    this.scanner = new OfferScanner(ecosystemRoot, { debug: this.options.debug });
+  }
+
+  orchestrate(context = {}) {
+    const result = {
+      timestamp: new Date().toISOString(),
+      offers: [],
+      activeOffer: null,
+      routing: null,
+      warnings: [],
+    };
+
+    try {
+      // Step 1: Scan all offers
+      const allOffers = this.scanner.scanAll();
+      result.offers = allOffers.map(o => ({
+        name: o.name,
+        niche: o.niche,
+        relativePath: o.relativePath,
+        phase: o.state?.workflow_phase || 'idle',
+        gatesStatus: this._summarizeGates(o.state?.gates),
+        mecanismoState: o.state?.mecanismo?.state || 'undefined',
+      }));
+
+      // Step 2: Detect active offer
+      const activeOffers = this.scanner.scanActive();
+      if (activeOffers.length > 0) {
+        // Pick the most recently updated active offer
+        const sorted = activeOffers.sort((a, b) => {
+          const aTime = a.state?.last_updated ? new Date(a.state.last_updated).getTime() : 0;
+          const bTime = b.state?.last_updated ? new Date(b.state.last_updated).getTime() : 0;
+          return bTime - aTime;
+        });
+        result.activeOffer = sorted[0];
+      } else if (context.offerPath) {
+        // User specified an offer
+        result.activeOffer = this.scanner.getOffer(context.offerPath);
+      }
+
+      // Step 3: Route
+      if (result.activeOffer) {
+        const offerState = this.detectOfferState(result.activeOffer.path);
+        result.routing = this.routeByState(offerState, context);
+
+        // Step 4: Crash detection
+        const crashInfo = this._detectCrash(offerState);
+        if (crashInfo.isCrash) {
+          result.warnings.push(`Possível crash detectado: última atualização há ${crashInfo.minutesSince} min`);
+          result.routing.crashDetected = true;
+        }
+      } else {
+        // No active offer — suggest starting one
+        const idleOffers = allOffers.filter(o => !o.state || o.state.workflow_phase === 'idle');
+        result.routing = {
+          action: 'select_offer',
+          message: `Nenhuma oferta ativa. ${idleOffers.length} ofertas em IDLE disponíveis.`,
+          availableOffers: idleOffers.map(o => o.relativePath),
+        };
+      }
+    } catch (error) {
+      result.routing = {
+        action: 'error',
+        message: `Orchestration failed: ${error.message}`,
+      };
+      this._log(`Orchestration error: ${error.message}`);
+    }
+
+    return result;
+  }
+
+  detectOfferState(offerPath) {
+    const helixStatePath = path.join(offerPath, 'helix-state.yaml');
+    const mecanismoPath = path.join(offerPath, 'mecanismo-unico.yaml');
+
+    const state = {
+      offer: path.basename(offerPath),
+      offerPath,
+      phase: OfferPhase.IDLE,
+      gates: { research: false, briefing: false, production: false },
+      mecanismo: { state: 'undefined' },
+      lastUpdated: null,
+      hasResearch: false,
+      hasBriefings: false,
+      hasProduction: false,
+    };
+
+    // Read helix-state.yaml
+    if (fs.existsSync(helixStatePath)) {
+      try {
+        const content = fs.readFileSync(helixStatePath, 'utf8');
+        const helixState = yaml.load(content);
+
+        state.phase = helixState?.workflow_phase || OfferPhase.IDLE;
+        state.lastUpdated = helixState?.last_updated || null;
+
+        if (helixState?.gates) {
+          state.gates.research = helixState.gates.research === true || helixState.gates.research === 'passed';
+          state.gates.briefing = helixState.gates.briefing === true || helixState.gates.briefing === 'passed';
+          state.gates.production = helixState.gates.production === true || helixState.gates.production === 'passed';
+        }
+      } catch (e) {
+        this._log(`Failed to read helix-state: ${e.message}`);
+      }
+    }
+
+    // Read mecanismo-unico.yaml
+    if (fs.existsSync(mecanismoPath)) {
+      try {
+        const content = fs.readFileSync(mecanismoPath, 'utf8');
+        const mecanismo = yaml.load(content);
+        state.mecanismo.state = mecanismo?.state || mecanismo?.status || 'draft';
+        state.mecanismo.mupName = mecanismo?.mup?.name || null;
+        state.mecanismo.musName = mecanismo?.mus?.name || null;
+      } catch (e) {
+        this._log(`Failed to read mecanismo: ${e.message}`);
+      }
+    }
+
+    // Check directory existence
+    state.hasResearch = fs.existsSync(path.join(offerPath, 'research'));
+    state.hasBriefings = fs.existsSync(path.join(offerPath, 'briefings'));
+    state.hasProduction = fs.existsSync(path.join(offerPath, 'production'));
+
+    return state;
+  }
+
+  routeByState(offerState, context = {}) {
+    const phase = offerState.phase;
+    const baseRouting = ROUTING_TABLE[phase] || ROUTING_TABLE[OfferPhase.IDLE];
+
+    const routing = {
+      ...baseRouting,
+      offer: offerState.offer,
+      offerPath: offerState.offerPath,
+      phase,
+      gates: offerState.gates,
+      mecanismo: offerState.mecanismo,
+    };
+
+    // Special case: Research gates passed → advance to briefing
+    if (phase === OfferPhase.RESEARCH && offerState.gates.research) {
+      routing.nextWorkflow = 'briefing-pipeline';
+      routing.suggestedAgent = 'atlas';
+      routing.action = 'start_briefing';
+      routing.message = 'Research PASSED. Iniciar HELIX Briefing com Atlas.';
+    }
+
+    // Special case: Briefing gates passed → check mecanismo
+    if (phase === OfferPhase.BRIEFING && offerState.gates.briefing) {
+      const mecState = offerState.mecanismo.state;
+      if (mecState === 'validated' || mecState === 'approved' || mecState === 'VALIDATED' || mecState === 'APPROVED') {
+        routing.nextWorkflow = 'production-pipeline';
+        routing.suggestedAgent = 'echo';
+        routing.action = 'start_production';
+        routing.message = 'Briefing PASSED + Mecanismo APPROVED. Iniciar Production Pipeline.';
+      } else {
+        routing.nextWorkflow = null;
+        routing.suggestedAgent = 'atlas';
+        routing.action = 'validate_mecanismo';
+        routing.message = `Briefing PASSED mas Mecanismo em "${mecState}". Validar mecanismo antes de produzir.`;
+        routing.blocked = true;
+        routing.blockReason = 'mecanismo_not_validated';
+      }
+    }
+
+    // Special case: Production gates passed → review
+    if (phase === OfferPhase.PRODUCTION && offerState.gates.production) {
+      routing.nextWorkflow = 'review-pipeline';
+      routing.suggestedAgent = 'hawk';
+      routing.action = 'start_review';
+      routing.message = 'Production PASSED. Iniciar Review com Hawk.';
+    }
+
+    // Add agent info
+    if (routing.suggestedAgent && AGENT_MAP[routing.suggestedAgent]) {
+      routing.agentInfo = AGENT_MAP[routing.suggestedAgent];
+    }
+
+    // Add workflow path
+    if (routing.nextWorkflow) {
+      routing.workflowPath = path.join(
+        this.options.workflowsDir,
+        `${routing.nextWorkflow}.yaml`
+      );
+    }
+
+    return routing;
+  }
+
+  detectAllOffers() {
+    return this.scanner.scanAll();
+  }
+
+  handleSessionResume(option, offerPath) {
+    switch (option) {
+      case 'continue':
+        return {
+          action: 'continue',
+          offer: this.scanner.getOffer(offerPath),
+          message: 'Continuando de onde parou.',
+        };
+      case 'review':
+        return {
+          action: 'review',
+          offer: this.scanner.getOffer(offerPath),
+          message: 'Revise o estado e escolha o próximo passo.',
+        };
+      case 'restart':
+        return {
+          action: 'restart',
+          offer: this.scanner.getOffer(offerPath),
+          message: 'Reiniciando fase atual.',
+        };
+      case 'discard':
+        return {
+          action: 'discard',
+          message: 'Estado descartado. Selecione uma oferta.',
+        };
+      default:
+        return {
+          action: 'unknown',
+          message: `Opção desconhecida: ${option}`,
+        };
+    }
+  }
+
+  formatRoutingContext(orchestrationResult) {
+    const r = orchestrationResult;
+    const lines = [];
+
+    lines.push('<helix-routing>');
+    lines.push(`<timestamp>${r.timestamp}</timestamp>`);
+
+    // Offers summary
+    lines.push('<offers>');
+    for (const offer of r.offers) {
+      lines.push(`  <offer name="${offer.name}" niche="${offer.niche}" phase="${offer.phase}" gates="${offer.gatesStatus}" mecanismo="${offer.mecanismoState}" />`);
+    }
+    lines.push('</offers>');
+
+    // Active offer + routing
+    if (r.activeOffer) {
+      lines.push(`<active-offer>${r.activeOffer.relativePath}</active-offer>`);
+    }
+
+    if (r.routing) {
+      lines.push('<routing>');
+      lines.push(`  <action>${r.routing.action}</action>`);
+      lines.push(`  <message>${r.routing.message}</message>`);
+      if (r.routing.nextWorkflow) {
+        lines.push(`  <workflow>${r.routing.nextWorkflow}</workflow>`);
+      }
+      if (r.routing.suggestedAgent) {
+        lines.push(`  <agent>${r.routing.suggestedAgent}</agent>`);
+      }
+      if (r.routing.blocked) {
+        lines.push(`  <blocked reason="${r.routing.blockReason}" />`);
+      }
+      lines.push('</routing>');
+    }
+
+    // Warnings
+    if (r.warnings.length > 0) {
+      lines.push('<warnings>');
+      for (const w of r.warnings) {
+        lines.push(`  <warning>${w}</warning>`);
+      }
+      lines.push('</warnings>');
+    }
+
+    lines.push('</helix-routing>');
+    return lines.join('\n');
+  }
+
+  _detectCrash(offerState) {
+    if (!offerState.lastUpdated) {
+      return { isCrash: false };
+    }
+
+    const lastUpdated = new Date(offerState.lastUpdated);
+    const now = new Date();
+    const minutesSince = Math.floor((now - lastUpdated) / (1000 * 60));
+
+    return {
+      isCrash: minutesSince > CRASH_THRESHOLD_MINUTES && offerState.phase !== OfferPhase.IDLE && offerState.phase !== OfferPhase.DELIVERED,
+      minutesSince,
+      lastUpdated: offerState.lastUpdated,
+    };
+  }
+
+  _summarizeGates(gates) {
+    if (!gates) return 'none';
+    const passed = [];
+    if (gates.research === true || gates.research === 'passed') passed.push('R');
+    if (gates.briefing === true || gates.briefing === 'passed') passed.push('B');
+    if (gates.production === true || gates.production === 'passed') passed.push('P');
+    return passed.length > 0 ? passed.join('+') : 'none';
+  }
+
+  _log(message) {
+    if (this.options.debug) {
+      console.log(`[HelixOrchestrator] ${message}`);
+    }
+  }
+}
+
+module.exports = {
+  HelixOrchestrator,
+  OfferPhase,
+  AGENT_MAP,
+  WORKFLOW_MAP,
+  ROUTING_TABLE,
+};

package/framework/.aios-core/copy-chief/orchestration/lock-manager.js

@@ -0,0 +1,301 @@
+'use strict';
+
+/**
+ * Lock Manager
+ *
+ * File-based distributed locking for multi-terminal safety.
+ * Adapted from Synkra's lock-manager.js for the Copy Chief ecosystem.
+ *
+ * Lock files live at ~/.claude/.lock/{resource}.lock.yaml
+ * Schema: { owner, pid, resource, acquired_at, ttl_ms, purpose }
+ *
+ * @module lock-manager
+ * @version 1.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const LOCK_DIR = path.join(process.env.HOME, '.claude', '.lock');
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const RETRY_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 1000;
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Convert a resource name to a safe lock file name.
+ * Replaces path separators and spaces with underscores.
+ */
+function resourceToFileName(resource) {
+  return resource.replace(/[/\\:\s]+/g, '_') + '.lock.yaml';
+}
+
+/**
+ * Absolute path to the lock file for a resource.
+ */
+function lockFilePath(resource) {
+  fs.mkdirSync(LOCK_DIR, { recursive: true });
+  return path.join(LOCK_DIR, resourceToFileName(resource));
+}
+
+/**
+ * Read a lock file safely. Returns null if missing or corrupt.
+ */
+function readLock(resource) {
+  const filePath = lockFilePath(resource);
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return yaml.load(fs.readFileSync(filePath, 'utf8')) || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Write a lock file atomically.
+ */
+function writeLock(resource, lockData) {
+  const filePath = lockFilePath(resource);
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, yaml.dump(lockData, { lineWidth: 120, noRefs: true }), 'utf8');
+  fs.renameSync(tmp, filePath);
+}
+
+/**
+ * Delete a lock file. Swallows errors.
+ */
+function deleteLock(resource) {
+  try {
+    fs.unlinkSync(lockFilePath(resource));
+  } catch (_) {}
+}
+
+/**
+ * Check whether a process with the given PID is still alive.
+ * Uses POSIX signal 0 (does not actually send a signal).
+ * Returns false on any error (process gone or permission denied).
+ */
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Check whether a lock is stale.
+ * A lock is stale when its TTL has expired OR its owner PID is no longer alive.
+ */
+function isStale(lockData) {
+  if (!lockData) return true;
+
+  const acquiredAt = new Date(lockData.acquired_at).getTime();
+  const ttl = lockData.ttl_ms || DEFAULT_TTL_MS;
+  const now = Date.now();
+
+  if (now - acquiredAt > ttl) return true;
+  if (lockData.pid && !isPidAlive(lockData.pid)) return true;
+
+  return false;
+}
+
+/**
+ * Sleep for ms milliseconds.
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Current ISO timestamp.
+ */
+function now() {
+  return new Date().toISOString();
+}
+
+// ─── Core API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Acquire a lock on a resource.
+ *
+ * Will retry up to RETRY_ATTEMPTS times if the resource is already locked
+ * (and the lock is not stale). Stale locks are forcibly removed before
+ * attempting acquisition.
+ *
+ * @param {string} resource - Logical resource name (e.g. 'florayla-dispatch-queue')
+ * @param {string} owner - Owner identifier (e.g. agent handle or session id)
+ * @param {object} [options]
+ * @param {number} [options.ttl_ms] - Lock TTL in ms (default: 5 minutes)
+ * @param {string} [options.purpose] - Human-readable reason for the lock
+ * @returns {{ acquired: boolean, reason?: string, lock?: object }}
+ */
+async function acquire(resource, owner, options = {}) {
+  const ttl = options.ttl_ms || DEFAULT_TTL_MS;
+  const purpose = options.purpose || '';
+
+  for (let attempt = 1; attempt <= RETRY_ATTEMPTS; attempt++) {
+    const existing = readLock(resource);
+
+    if (existing) {
+      if (isStale(existing)) {
+        // Remove stale lock and proceed
+        deleteLock(resource);
+      } else if (existing.owner === owner) {
+        // Same owner re-acquiring (refresh TTL)
+        existing.acquired_at = now();
+        existing.ttl_ms = ttl;
+        writeLock(resource, existing);
+        return { acquired: true, lock: existing };
+      } else {
+        // Locked by a different, live owner
+        if (attempt < RETRY_ATTEMPTS) {
+          await sleep(RETRY_DELAY_MS);
+          continue;
+        }
+        return {
+          acquired: false,
+          reason: `Resource '${resource}' locked by '${existing.owner}' (PID ${existing.pid})`,
+        };
+      }
+    }
+
+    // Slot is free — create lock
+    const lockData = {
+      owner,
+      pid: process.pid,
+      resource,
+      acquired_at: now(),
+      ttl_ms: ttl,
+      purpose,
+    };
+
+    try {
+      writeLock(resource, lockData);
+      return { acquired: true, lock: lockData };
+    } catch (err) {
+      if (attempt < RETRY_ATTEMPTS) {
+        await sleep(RETRY_DELAY_MS);
+        continue;
+      }
+      return { acquired: false, reason: `Failed to write lock file: ${err.message}` };
+    }
+  }
+
+  return { acquired: false, reason: 'Exceeded retry attempts' };
+}
+
+/**
+ * Release a lock on a resource.
+ *
+ * Only releases if the current lock owner matches the provided owner.
+ *
+ * @param {string} resource
+ * @param {string} owner
+ * @returns {{ released: boolean, reason?: string }}
+ */
+function release(resource, owner) {
+  const existing = readLock(resource);
+
+  if (!existing) {
+    return { released: true, reason: 'Lock did not exist (already released)' };
+  }
+
+  if (existing.owner !== owner) {
+    return {
+      released: false,
+      reason: `Cannot release: lock owned by '${existing.owner}', not '${owner}'`,
+    };
+  }
+
+  deleteLock(resource);
+  return { released: true };
+}
+
+/**
+ * Check whether a resource is currently locked (by any live owner).
+ *
+ * @param {string} resource
+ * @returns {boolean}
+ */
+function isLocked(resource) {
+  const existing = readLock(resource);
+  if (!existing) return false;
+  if (isStale(existing)) {
+    deleteLock(resource);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Remove all stale lock files from the lock directory.
+ *
+ * @returns {{ cleaned: number, errors: string[] }}
+ */
+function cleanupStale() {
+  const errors = [];
+  let cleaned = 0;
+
+  let files;
+  try {
+    fs.mkdirSync(LOCK_DIR, { recursive: true });
+    files = fs.readdirSync(LOCK_DIR).filter((f) => f.endsWith('.lock.yaml'));
+  } catch (err) {
+    return { cleaned: 0, errors: [`Cannot read lock dir: ${err.message}`] };
+  }
+
+  for (const file of files) {
+    const filePath = path.join(LOCK_DIR, file);
+    try {
+      const content = yaml.load(fs.readFileSync(filePath, 'utf8'));
+      if (isStale(content)) {
+        fs.unlinkSync(filePath);
+        cleaned++;
+      }
+    } catch (err) {
+      // Corrupt lock file — remove it
+      try {
+        fs.unlinkSync(filePath);
+        cleaned++;
+      } catch (e2) {
+        errors.push(`Failed to remove ${file}: ${e2.message}`);
+      }
+    }
+  }
+
+  return { cleaned, errors };
+}
+
+/**
+ * Get full information about a lock without modifying it.
+ *
+ * @param {string} resource
+ * @returns {{ locked: boolean, stale: boolean, lock: object|null }}
+ */
+function getLockInfo(resource) {
+  const existing = readLock(resource);
+  if (!existing) {
+    return { locked: false, stale: false, lock: null };
+  }
+  const stale = isStale(existing);
+  return { locked: !stale, stale, lock: existing };
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  acquire,
+  release,
+  isLocked,
+  cleanupStale,
+  getLockInfo,
+  // Constants (exposed for callers that need custom TTLs)
+  DEFAULT_TTL_MS,
+  LOCK_DIR,
+};