@jaimevalasek/aioson 1.7.0 → 1.8.0

package/src/handoff-contract.js

@@ -0,0 +1,363 @@
+'use strict';
+
+/**
+ * handoff-contract — machine-verified agent output contracts.
+ *
+ * Each agent role declares what it must produce before the workflow
+ * allows handoff to the next stage. This catches incomplete agent
+ * sessions early instead of discovering missing artifacts later.
+ */
+
+const path = require('node:path');
+const { readFileSafe, fileExists } = require('./preflight-engine');
+
+// Contract definitions per agent stage
+const CONTRACTS = {
+  setup: {
+    artifacts: ['.aioson/context/project.context.md'],
+    gates: [],
+    contextUpdates: []
+  },
+  product: {
+    artifacts: (targetDir, state) => {
+      if (state.mode === 'feature' && state.featureSlug) {
+        return [`.aioson/context/prd-${state.featureSlug}.md`];
+      }
+      return ['.aioson/context/prd.md'];
+    },
+    gates: [],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  analyst: {
+    artifacts: (targetDir, state) => {
+      if (state.mode === 'feature' && state.featureSlug) {
+        return [
+          `.aioson/context/requirements-${state.featureSlug}.md`,
+          `.aioson/context/spec-${state.featureSlug}.md`
+        ];
+      }
+      return ['.aioson/context/discovery.md'];
+    },
+    gates: ['A'], // Gate A must be approved
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  architect: {
+    artifacts: ['.aioson/context/architecture.md'],
+    gates: ['B'],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  'ux-ui': {
+    artifacts: ['.aioson/context/ui-spec.md'],
+    gates: ['B'],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  pm: {
+    artifacts: (targetDir, state) => {
+      // @pm owns implementation-plan only for MEDIUM features (AC-SDLC-16)
+      if (state.mode === 'feature' && state.featureSlug && state.classification === 'MEDIUM') {
+        return [`.aioson/context/implementation-plan-${state.featureSlug}.md`];
+      }
+      return [];
+    },
+    gates: [],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  orchestrator: {
+    artifacts: ['.aioson/context/parallel'],
+    gates: [],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  dev: {
+    artifacts: [],
+    gates: ['C'],
+    contextUpdates: ['.aioson/context/project-pulse.md', '.aioson/context/dev-state.md']
+  },
+  tester: {
+    artifacts: [],
+    gates: [],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  pentester: {
+    artifacts: (targetDir, state) => {
+      if (state.mode === 'feature' && state.featureSlug) {
+        return [`.aioson/context/security-findings-${state.featureSlug}.json`];
+      }
+      return [];
+    },
+    gates: [],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  qa: {
+    artifacts: [],
+    gates: ['D'],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  committer: {
+    artifacts: [],
+    gates: [],
+    contextUpdates: []
+  }
+};
+
+async function readSecurityFindings(findingsPath) {
+  try {
+    const content = await readFileSafe(findingsPath);
+    if (!content) return { ok: false, reason: 'empty_file' };
+    const data = JSON.parse(content);
+    return {
+      ok: true,
+      reviewContract: data.review_contract && typeof data.review_contract === 'object'
+        ? data.review_contract
+        : null,
+      findings: Array.isArray(data.findings) ? data.findings : []
+    };
+  } catch {
+    return { ok: false, reason: 'invalid_json' };
+  }
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function validateReviewContract(reviewContract) {
+  const missing = [];
+
+  if (!reviewContract || typeof reviewContract !== 'object') {
+    return ['review_contract'];
+  }
+
+  for (const field of ['scope_mode', 'evidence_policy', 'findings_artifact_path']) {
+    if (!isNonEmptyString(reviewContract[field])) {
+      missing.push(field);
+    }
+  }
+
+  if (
+    reviewContract.target_mode === 'app_target' &&
+    !isNonEmptyString(reviewContract.target_scope)
+  ) {
+    missing.push('target_scope');
+  }
+
+  return missing;
+}
+
+function getFindingIdentifier(finding) {
+  if (isNonEmptyString(finding?.id)) return finding.id.trim();
+  if (isNonEmptyString(finding?.finding_id)) return finding.finding_id.trim();
+  return 'unknown-finding';
+}
+
+async function resolveArtifacts(contract, targetDir, state) {
+  const raw = typeof contract.artifacts === 'function'
+    ? contract.artifacts(targetDir, state)
+    : contract.artifacts;
+  return raw.map((p) => path.join(targetDir, p));
+}
+
+function parseFrontmatterValue(markdown, key) {
+  const fmMatch = String(markdown || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return null;
+  for (const line of fmMatch[1].split(/\r?\n/)) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const currentKey = line.slice(0, idx).trim();
+    if (currentKey !== key) continue;
+    return line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+  }
+  return null;
+}
+
+async function resolveClassification(targetDir, state) {
+  const explicit = isNonEmptyString(state?.classification) ? state.classification.trim().toUpperCase() : null;
+  if (explicit) return explicit;
+  const contextPath = path.join(targetDir, '.aioson', 'context', 'project.context.md');
+  const content = await readFileSafe(contextPath);
+  const inferred = parseFrontmatterValue(content, 'classification');
+  return isNonEmptyString(inferred) ? inferred.trim().toUpperCase() : null;
+}
+
+async function checkGateApproval(targetDir, gateLetter, slug) {
+  const specPath = slug
+    ? path.join(targetDir, '.aioson', 'context', `spec-${slug}.md`)
+    : path.join(targetDir, '.aioson', 'context', 'spec.md');
+  const content = await readFileSafe(specPath);
+  if (!content) {
+    if (!slug) return { ok: true, reason: 'project_mode_without_spec' };
+    return { ok: false, reason: 'spec_missing' };
+  }
+
+  const gateNames = { A: 'requirements', B: 'design', C: 'plan', D: 'execution' };
+  const gateName = gateNames[gateLetter];
+
+  // Parse frontmatter
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return { ok: false, reason: 'no_frontmatter' };
+
+  const fm = {};
+  for (const line of fmMatch[1].split(/\r?\n/)) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const val = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+    if (key) fm[key] = val;
+  }
+
+  // Check explicit gate field
+  const gateVal = fm[`gate_${gateName}`] || fm[`gate${gateLetter}`] || fm[`gate_${gateLetter}`];
+  if (gateVal && gateVal.toLowerCase() === 'approved') {
+    return { ok: true };
+  }
+
+  // Check phase_gates JSON
+  if (fm.phase_gates) {
+    try {
+      const parsed = JSON.parse(fm.phase_gates.replace(/'/g, '"'));
+      if (parsed[gateName] === 'approved') return { ok: true };
+    } catch {
+      // ignore
+    }
+  }
+
+  // Check content for gate approval lines
+  const gateLineRe = new RegExp(`gate\\s+${gateLetter}[^:]*:\\s*approved`, 'i');
+  if (gateLineRe.test(content)) {
+    return { ok: true };
+  }
+
+  // Gate D: also accept QA sign-off section with PASS verdict
+  if (gateLetter === 'D') {
+    if (content.includes('## QA Sign-off')) {
+      const passMatch = content.match(/\*\*Verdict:\*\*\s*(PASS)/i);
+      if (passMatch) {
+        return { ok: true };
+      }
+    }
+  }
+
+  return { ok: false, reason: `gate_${gateName}_not_approved` };
+}
+
+async function validateHandoffContract(targetDir, state, stageName) {
+  const contract = CONTRACTS[stageName];
+  if (!contract) {
+    // Unknown stage — allow pass-through
+    return { ok: true, stage: stageName, missing: [] };
+  }
+
+  const missing = [];
+  const classification = await resolveClassification(targetDir, state);
+
+  // 1. Artifacts
+  const artifactPaths = await resolveArtifacts(contract, targetDir, state);
+  for (const p of artifactPaths) {
+    if (!(await fileExists(p))) {
+      missing.push(`missing artifact: ${path.relative(targetDir, p)}`);
+    }
+  }
+
+  // 2. Gates
+  for (const gateLetter of contract.gates) {
+    const gateCheck = await checkGateApproval(targetDir, gateLetter, state.featureSlug);
+    if (!gateCheck.ok) {
+      missing.push(`gate ${gateLetter} not approved (${gateCheck.reason})`);
+    }
+  }
+
+  // 3. Context updates (soft check — just warn if completely missing)
+  for (const p of contract.contextUpdates) {
+    const abs = path.join(targetDir, p);
+    if (!(await fileExists(abs))) {
+      missing.push(`missing context file: ${p} (recommended)`);
+    }
+  }
+
+  // 4. Security findings check — qa stage only
+  // Blocks on open high/critical findings with recommended_gate_status=block.
+  if (stageName === 'qa' && state.featureSlug) {
+    const findingsPath = path.join(
+      targetDir,
+      `.aioson/context/security-findings-${state.featureSlug}.json`
+    );
+    const requiresFindingsArtifact = state.mode === 'feature' && classification === 'MEDIUM';
+    if (!(await fileExists(findingsPath))) {
+      if (requiresFindingsArtifact) {
+        missing.push(`missing artifact: ${path.relative(targetDir, findingsPath)} (required for MEDIUM Gate D security audit)`);
+      }
+    } else {
+      const envelope = await readSecurityFindings(findingsPath);
+      if (!envelope || envelope.ok === false) {
+        missing.push(
+          `security: invalid findings artifact in ${path.relative(targetDir, findingsPath)} (${envelope?.reason || 'invalid_json'})`
+        );
+      } else {
+        const reviewContractMissing = validateReviewContract(envelope.reviewContract);
+        if (reviewContractMissing.length > 0) {
+          missing.push(
+            `security: invalid review_contract in ${path.relative(targetDir, findingsPath)} (missing: ${reviewContractMissing.join(', ')})`
+          );
+        } else {
+          const blockers = envelope.findings.filter(
+            (f) =>
+              (f.status === 'open' || f.status === 'needs_validation') &&
+              f.recommended_gate_status === 'block' &&
+              (f.severity === 'high' || f.severity === 'critical')
+          );
+          if (blockers.length > 0) {
+            missing.push(
+              `security: ${blockers.length} unresolved high/critical finding(s) blocking gate: ${blockers.map((f) => getFindingIdentifier(f)).join(', ')}`
+            );
+          }
+        }
+      }
+    }
+  }
+
+  // Only hard-block on artifacts and gates; context updates are warnings unless
+  // we are in strict mode. For now, treat everything as blocking to harden handoffs.
+  const hardBlockers = missing.filter((m) => !m.includes('(recommended)'));
+
+  return {
+    ok: hardBlockers.length === 0,
+    stage: stageName,
+    missing: hardBlockers,
+    warnings: missing.filter((m) => m.includes('(recommended)'))
+  };
+}
+
+function formatContractError(result) {
+  const lines = [
+    `[Handoff Contract BLOCKED]`,
+    `Stage: @${result.stage}`,
+    '',
+    'Missing deliverables:',
+    ...result.missing.map((m) => `  - ${m}`)
+  ];
+  if (result.warnings.length > 0) {
+    lines.push('', 'Warnings:');
+    lines.push(...result.warnings.map((w) => `  - ${w}`));
+  }
+  lines.push('', 'Complete these items before finishing the stage.');
+  return lines.join('\n');
+}
+
+// Returns pending blocking revisions for the active feature (or [] for legacy features).
+// Safe to call when dossier feature dir does not exist — returns [] silently.
+async function getBlockingRevisions(targetDir, featureSlug) {
+  if (!featureSlug) return [];
+  try {
+    const { getBlockingRevisions: getBlockers } = require('./dossier/revision-store');
+    const ctxDir = path.join(targetDir, '.aioson', 'context');
+    return await getBlockers({ slug: featureSlug, contextDir: ctxDir });
+  } catch {
+    return [];
+  }
+}
+
+module.exports = {
+  validateHandoffContract,
+  formatContractError,
+  getBlockingRevisions,
+  CONTRACTS
+};

package/src/handoff-validator.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const { readAgentManifest, canAgentPerform } = require('./agent-manifests');
+
+async function validateHandoffProtocol(targetDir, protocol) {
+  const errors = [];
+  if (!protocol || typeof protocol !== 'object') {
+    return { ok: false, errors: ['Missing handoff protocol payload'] };
+  }
+
+  const toAgentId = protocol.to && protocol.to.agent_id ? String(protocol.to.agent_id).trim() : '';
+  const requiredCapability = protocol.to && protocol.to.capability_required
+    ? String(protocol.to.capability_required).trim()
+    : '';
+
+  if (protocol.to && typeof protocol.to === 'object' && !toAgentId) {
+    errors.push('Missing to.agent_id in handoff protocol');
+  }
+
+  if (toAgentId) {
+    const toManifest = await readAgentManifest(targetDir, toAgentId);
+    if (!toManifest) {
+      errors.push(`Agent ${toAgentId} has no capability manifest`);
+    } else if (requiredCapability && !canAgentPerform(toManifest, requiredCapability)) {
+      errors.push(`Agent ${toAgentId} does not declare capability ${requiredCapability}`);
+    }
+  }
+
+  const validation = protocol.validation && typeof protocol.validation === 'object'
+    ? protocol.validation
+    : {};
+
+  if (validation.handoff_contract_ok === false) {
+    errors.push('Handoff contract validation failed');
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors
+  };
+}
+
+module.exports = {
+  validateHandoffProtocol
+};

package/src/harness/circuit-breaker.js

@@ -0,0 +1,135 @@
+const fs = require('fs');
+
+/**
+ * Circuit Breaker para o AIOSON — Módulo Puro
+ * Estados: CLOSED | OPEN | HALF_OPEN
+ * Persistência: progress.json
+ */
+class CircuitBreaker {
+  constructor(contractPath, progressPath) {
+    this.contractPath = contractPath;
+    this.progressPath = progressPath;
+    this.contract = null;
+    this.progress = null;
+  }
+
+  /**
+   * Carrega os arquivos de contrato e progresso do disco.
+   * Se o progresso estiver corrompido, tenta recuperar ou cria novo.
+   */
+  async load() {
+    try {
+      this.contract = JSON.parse(fs.readFileSync(this.contractPath, 'utf8'));
+    } catch (err) {
+      throw new Error(`[CircuitBreaker] Falha ao carregar contrato: ${err.message}`);
+    }
+
+    try {
+      if (fs.existsSync(this.progressPath)) {
+        this.progress = JSON.parse(fs.readFileSync(this.progressPath, 'utf8'));
+      } else {
+        this.progress = this._createInitialProgress();
+      }
+    } catch (err) {
+      // Recuperação em caso de JSON corrompido
+      console.warn(`[CircuitBreaker] Progress corrompido, recriando...`);
+      this.progress = this._createInitialProgress();
+    }
+  }
+
+  /**
+   * Verifica se uma nova iteração é permitida.
+   * Retorna { allowed: boolean, reason: string|null }
+   */
+  check() {
+    if (!this.progress || !this.contract) return { allowed: true, reason: null };
+
+    const { circuit_state, iterations, consecutive_errors } = this.progress;
+    const { max_steps, error_streak_limit } = this.contract.governor;
+
+    if (circuit_state === 'OPEN') {
+      return { allowed: false, reason: 'circuit_open' };
+    }
+
+    if (max_steps > 0 && iterations >= max_steps) {
+      return { allowed: false, reason: 'max_steps_reached' };
+    }
+
+    if (error_streak_limit > 0 && consecutive_errors >= error_streak_limit) {
+      return { allowed: false, reason: 'error_streak_limit_reached' };
+    }
+
+    return { allowed: true, reason: null };
+  }
+
+  /**
+   * Registra um sucesso no loop.
+   * Reseta erros consecutivos e pode fechar o circuit se estiver HALF_OPEN.
+   */
+  async recordSuccess() {
+    this.progress.consecutive_errors = 0;
+    this.progress.iterations += 1;
+    this.progress.last_updated = new Date().toISOString();
+    this.progress.ready_for_done_gate = true;
+
+    if (this.progress.circuit_state === 'HALF_OPEN') {
+      this.progress.circuit_state = 'CLOSED';
+      this.progress.status = 'in_progress';
+    }
+
+    await this._save();
+  }
+
+  /**
+   * Registra um erro no loop.
+   * Incrementa erros consecutivos e abre o circuit se atingir limites.
+   */
+  async recordError(reason) {
+    this.progress.consecutive_errors += 1;
+    this.progress.last_error = reason;
+    this.progress.last_updated = new Date().toISOString();
+    this.progress.ready_for_done_gate = false;
+
+    const { error_streak_limit, max_steps } = this.contract.governor;
+
+    if (error_streak_limit > 0 && this.progress.consecutive_errors >= error_streak_limit) {
+      this.progress.circuit_state = 'OPEN';
+      this.progress.status = 'circuit_open';
+      this.progress.last_error = `error_streak_limit_reached: ${reason}`;
+    } else if (max_steps > 0 && this.progress.iterations >= max_steps) {
+      this.progress.circuit_state = 'OPEN';
+      this.progress.status = 'circuit_open';
+      this.progress.last_error = `max_steps_reached: ${reason}`;
+    }
+
+    await this._save();
+  }
+
+  _createInitialProgress() {
+    return {
+      feature: this.contract ? this.contract.feature : 'unknown',
+      phase: 1,
+      status: 'in_progress',
+      completed_steps: [],
+      last_error: null,
+      session_count: 1,
+      last_updated: new Date().toISOString(),
+      circuit_state: 'CLOSED',
+      iterations: 0,
+      consecutive_errors: 0,
+      ready_for_done_gate: false
+    };
+  }
+
+  async _save() {
+    fs.writeFileSync(this.progressPath, JSON.stringify(this.progress, null, 2), 'utf8');
+  }
+
+  getState() {
+    return this.progress ? this.progress.circuit_state : 'CLOSED';
+  }
+}
+
+module.exports = {
+  createCircuitBreaker: (contractPath, progressPath) => new CircuitBreaker(contractPath, progressPath)
+};