popeye-cli 1.10.0 → 2.1.0

package/src/pipeline/gate-engine.ts

@@ -0,0 +1,347 @@
+/**
+ * Gate Engine — pure deterministic state machine for the pipeline.
+ * No side effects. Reads artifacts and check results, never executes anything.
+ * All 14 phases with specific required artifacts and checks per phase.
+ */
+
+import type {
+  PipelinePhase,
+  PipelineState,
+  ArtifactType,
+  ArtifactEntry,
+  GateCheckType,
+} from './types.js';
+
+// ─── Gate Definition ─────────────────────────────────────
+
+export interface GateDefinition {
+  phase: PipelinePhase;
+  requiredArtifacts: ArtifactType[];
+  requiredChecks: GateCheckType[];
+  consensusThreshold?: number;
+  minReviewers?: number;
+  allowedTransitions: PipelinePhase[];
+  failTransition: PipelinePhase;
+}
+
+export interface GateResult {
+  phase: PipelinePhase;
+  pass: boolean;
+  score?: number;
+  blockers: string[];
+  missingArtifacts: ArtifactType[];
+  failedChecks: GateCheckType[];
+  consensusScore?: number;
+  timestamp: string;
+}
+
+// ─── Gate Definitions Map ────────────────────────────────
+
+const GATE_DEFINITIONS: Record<PipelinePhase, GateDefinition> = {
+  INTAKE: {
+    phase: 'INTAKE',
+    requiredArtifacts: ['master_plan', 'repo_snapshot', 'constitution'],
+    requiredChecks: [],
+    allowedTransitions: ['CONSENSUS_MASTER_PLAN'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  CONSENSUS_MASTER_PLAN: {
+    phase: 'CONSENSUS_MASTER_PLAN',
+    requiredArtifacts: ['master_plan', 'consensus'],
+    requiredChecks: [],
+    consensusThreshold: 0.95,
+    minReviewers: 2,
+    allowedTransitions: ['ARCHITECTURE'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  ARCHITECTURE: {
+    phase: 'ARCHITECTURE',
+    requiredArtifacts: ['architecture', 'repo_snapshot'],
+    requiredChecks: [],
+    allowedTransitions: ['CONSENSUS_ARCHITECTURE'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  CONSENSUS_ARCHITECTURE: {
+    phase: 'CONSENSUS_ARCHITECTURE',
+    requiredArtifacts: ['architecture', 'consensus'],
+    requiredChecks: [],
+    consensusThreshold: 0.95,
+    minReviewers: 2,
+    allowedTransitions: ['ROLE_PLANNING'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  ROLE_PLANNING: {
+    phase: 'ROLE_PLANNING',
+    requiredArtifacts: ['role_plan'],
+    requiredChecks: [],
+    allowedTransitions: ['CONSENSUS_ROLE_PLANS'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  CONSENSUS_ROLE_PLANS: {
+    phase: 'CONSENSUS_ROLE_PLANS',
+    requiredArtifacts: ['role_plan', 'consensus'],
+    requiredChecks: [],
+    consensusThreshold: 0.95,
+    minReviewers: 2,
+    allowedTransitions: ['IMPLEMENTATION'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  IMPLEMENTATION: {
+    phase: 'IMPLEMENTATION',
+    requiredArtifacts: ['repo_snapshot'],
+    requiredChecks: [],
+    allowedTransitions: ['QA_VALIDATION'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  QA_VALIDATION: {
+    phase: 'QA_VALIDATION',
+    requiredArtifacts: ['qa_validation'],
+    requiredChecks: ['test'],
+    allowedTransitions: ['REVIEW'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  REVIEW: {
+    phase: 'REVIEW',
+    requiredArtifacts: ['review_decision', 'repo_snapshot'],
+    requiredChecks: [],
+    allowedTransitions: ['AUDIT'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  AUDIT: {
+    phase: 'AUDIT',
+    requiredArtifacts: ['audit_report'],
+    requiredChecks: [],
+    allowedTransitions: ['PRODUCTION_GATE'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  PRODUCTION_GATE: {
+    phase: 'PRODUCTION_GATE',
+    requiredArtifacts: ['production_readiness'],
+    requiredChecks: ['build', 'test', 'lint', 'typecheck'],
+    allowedTransitions: ['DONE'],
+    failTransition: 'RECOVERY_LOOP',
+  },
+  RECOVERY_LOOP: {
+    phase: 'RECOVERY_LOOP',
+    requiredArtifacts: ['rca_report'],
+    requiredChecks: [],
+    allowedTransitions: [
+      'INTAKE', 'CONSENSUS_MASTER_PLAN', 'ARCHITECTURE',
+      'CONSENSUS_ARCHITECTURE', 'ROLE_PLANNING', 'CONSENSUS_ROLE_PLANS',
+      'IMPLEMENTATION', 'QA_VALIDATION', 'REVIEW', 'AUDIT',
+      'PRODUCTION_GATE', 'STUCK',
+    ],
+    failTransition: 'STUCK',
+  },
+  DONE: {
+    phase: 'DONE',
+    requiredArtifacts: ['release_notes', 'deployment', 'rollback'],
+    requiredChecks: [],
+    allowedTransitions: [],
+    failTransition: 'DONE', // terminal
+  },
+  STUCK: {
+    phase: 'STUCK',
+    requiredArtifacts: ['stuck_report'],
+    requiredChecks: [],
+    allowedTransitions: [],
+    failTransition: 'STUCK', // terminal
+  },
+};
+
+/** Ordered phase sequence for linear progression */
+const PHASE_SEQUENCE: PipelinePhase[] = [
+  'INTAKE',
+  'CONSENSUS_MASTER_PLAN',
+  'ARCHITECTURE',
+  'CONSENSUS_ARCHITECTURE',
+  'ROLE_PLANNING',
+  'CONSENSUS_ROLE_PLANS',
+  'IMPLEMENTATION',
+  'QA_VALIDATION',
+  'REVIEW',
+  'AUDIT',
+  'PRODUCTION_GATE',
+  'DONE',
+];
+
+// ─── Gate Engine ─────────────────────────────────────────
+
+export class GateEngine {
+  /** Get gate definition for a specific phase */
+  getGateDefinition(phase: PipelinePhase): GateDefinition {
+    return GATE_DEFINITIONS[phase];
+  }
+
+  /**
+   * Evaluate whether a phase's gate passes.
+   *
+   * Args:
+   *   phase: The phase to evaluate.
+   *   pipeline: Current pipeline state.
+   *   options: Optional checks like constitution verification.
+   */
+  evaluateGate(
+    phase: PipelinePhase,
+    pipeline: PipelineState,
+    options?: { constitutionValid?: boolean; constitutionReason?: string },
+  ): GateResult {
+    const gateDef = GATE_DEFINITIONS[phase];
+    const blockers: string[] = [];
+    const missingArtifacts: ArtifactType[] = [];
+    const failedChecks: GateCheckType[] = [];
+
+    // Constitution verification (v1.1) — applied to all gates after INTAKE
+    if (options?.constitutionValid === false) {
+      blockers.push(options.constitutionReason ?? 'Constitution verification failed');
+    }
+
+    // Check required artifacts exist
+    for (const requiredType of gateDef.requiredArtifacts) {
+      const hasArtifact = pipeline.artifacts.some(
+        (a) => a.type === requiredType && a.phase === phase,
+      );
+      if (!hasArtifact) {
+        missingArtifacts.push(requiredType);
+        blockers.push(`Missing artifact: ${requiredType}`);
+      }
+    }
+
+    // Check required check results
+    const phaseChecks = pipeline.gateChecks[phase] ?? [];
+    for (const requiredCheck of gateDef.requiredChecks) {
+      const checkResult = phaseChecks.find((c) => c.check_type === requiredCheck);
+      if (!checkResult) {
+        failedChecks.push(requiredCheck);
+        blockers.push(`Missing check result: ${requiredCheck}`);
+      } else if (checkResult.status === 'fail') {
+        failedChecks.push(requiredCheck);
+        blockers.push(`Check failed: ${requiredCheck} (exit code ${checkResult.exit_code})`);
+      }
+    }
+
+    // Check consensus threshold for consensus phases
+    let consensusScore: number | undefined;
+    if (gateDef.consensusThreshold !== undefined) {
+      const consensusArtifact = findLatestConsensusForPhase(pipeline, phase);
+      if (consensusArtifact) {
+        consensusScore = parseConsensusScore(pipeline, phase);
+        if (consensusScore !== undefined && consensusScore < gateDef.consensusThreshold) {
+          blockers.push(
+            `Consensus score ${consensusScore.toFixed(2)} below threshold ${gateDef.consensusThreshold}`,
+          );
+        }
+      } else {
+        blockers.push('No consensus packet found');
+      }
+    }
+
+    // Check audit status for post-audit phases
+    if (phase === 'PRODUCTION_GATE') {
+      const auditArtifact = pipeline.artifacts.find(
+        (a) => a.type === 'audit_report',
+      );
+      if (!auditArtifact) {
+        blockers.push('Audit report required before production gate');
+      }
+    }
+
+    const pass = blockers.length === 0;
+
+    return {
+      phase,
+      pass,
+      blockers,
+      missingArtifacts,
+      failedChecks,
+      consensusScore,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /** Get the next phase after a successful gate */
+  getNextPhase(
+    current: PipelinePhase,
+    _gateResult: GateResult,
+  ): PipelinePhase {
+    const currentIndex = PHASE_SEQUENCE.indexOf(current);
+    if (currentIndex === -1 || currentIndex >= PHASE_SEQUENCE.length - 1) {
+      return 'DONE';
+    }
+    return PHASE_SEQUENCE[currentIndex + 1];
+  }
+
+  /** Check if a transition between two phases is allowed */
+  canTransition(
+    from: PipelinePhase,
+    to: PipelinePhase,
+    pipeline: PipelineState,
+  ): { allowed: boolean; blockers: string[] } {
+    const gateDef = GATE_DEFINITIONS[from];
+    const blockers: string[] = [];
+
+    if (!gateDef.allowedTransitions.includes(to)) {
+      blockers.push(`Transition from ${from} to ${to} is not allowed`);
+    }
+
+    // Verify gate passes before transition
+    const gateResult = this.evaluateGate(from, pipeline);
+    if (!gateResult.pass) {
+      blockers.push(...gateResult.blockers);
+    }
+
+    return {
+      allowed: blockers.length === 0,
+      blockers,
+    };
+  }
+
+  /** Get the ordered phase sequence */
+  getPhaseSequence(): PipelinePhase[] {
+    return [...PHASE_SEQUENCE];
+  }
+
+  /** Get phase index in the sequence (for progress tracking) */
+  getPhaseIndex(phase: PipelinePhase): number {
+    return PHASE_SEQUENCE.indexOf(phase);
+  }
+}
+
+/** Factory function */
+export function createGateEngine(): GateEngine {
+  return new GateEngine();
+}
+
+// ─── Helpers ─────────────────────────────────────────────
+
+function findLatestConsensusForPhase(
+  pipeline: PipelineState,
+  phase: PipelinePhase,
+): ArtifactEntry | undefined {
+  return pipeline.artifacts
+    .filter((a) => a.type === 'consensus' && a.phase === phase)
+    .sort((a, b) => b.timestamp.localeCompare(a.timestamp))[0];
+}
+
+/**
+ * Extract consensus score from pipeline gate results.
+ * The score is stored by consensus phase handlers after running consensus.
+ * Falls back to reading from the consensus artifact's stored data.
+ */
+function parseConsensusScore(
+  pipeline: PipelineState,
+  phase: PipelinePhase,
+): number | undefined {
+  // Look up stored score from gateResults (set by consensus phase handlers)
+  const gateResult = pipeline.gateResults[phase];
+  if (gateResult?.score !== undefined) {
+    return gateResult.score;
+  }
+
+  // Fallback: check consensusScore field
+  if (gateResult?.consensusScore !== undefined) {
+    return gateResult.consensusScore;
+  }
+
+  return undefined;
+}

package/src/pipeline/index.ts

@@ -0,0 +1,82 @@
+/**
+ * Pipeline module — re-exports all public APIs.
+ */
+
+// Core types
+export type {
+  PipelinePhase,
+  PipelineRole,
+  PipelineState,
+  PipelineResult,
+  ArtifactType,
+  ArtifactRef,
+  ArtifactEntry,
+  PlanPacket,
+  ConsensusPacket,
+  ReviewerVote,
+  RCAPacket,
+  AuditFinding,
+  AuditReport,
+  RepoSnapshot,
+  GateCheckResult,
+  ResolvedCommands,
+  ChangeRequest,
+} from './types.js';
+
+export {
+  PipelinePhaseSchema,
+  PipelineRoleSchema,
+  createDefaultPipelineState,
+} from './types.js';
+
+// Orchestrator
+export { runPipeline, resumePipeline } from './orchestrator.js';
+export type { PipelineOptions } from './orchestrator.js';
+
+// Gate Engine
+export { createGateEngine, GateEngine } from './gate-engine.js';
+export type { GateDefinition, GateResult } from './gate-engine.js';
+
+// Artifact Manager
+export { createArtifactManager, ArtifactManager } from './artifact-manager.js';
+
+// Repo Snapshot
+export { generateRepoSnapshot, diffSnapshots } from './repo-snapshot.js';
+
+// Command Resolver
+export { resolveCommands, detectProjectType } from './command-resolver.js';
+
+// Check Runner
+export { runCheck, runAllChecks, runPlaceholderScan, runStartCheck, runEnvCheck } from './check-runner.js';
+
+// Packet Builders
+export { buildPlanPacket, buildConsensusPacket, buildRCAPacket, buildAuditReport } from './packets/index.js';
+
+// Skill Loader
+export { createSkillLoader, SkillLoader } from './skill-loader.js';
+
+// Consensus Runner
+export { createConsensusRunner, ConsensusRunner } from './consensus/consensus-runner.js';
+
+// Migration
+export { migrateToPipelineState, needsPipelineMigration, toLegacyPhase } from './migration.js';
+
+// Constitution (v1.1)
+export { computeConstitutionHash, createConstitutionArtifact, verifyConstitution } from './constitution.js';
+
+// Artifact Validators (v1.1)
+export { validateArtifactCompleteness, getValidatableArtifactTypes } from './artifact-validators.js';
+export type { ValidationResult } from './artifact-validators.js';
+
+// Change Request (v1.1)
+export { buildChangeRequest, routeChangeRequest, formatChangeRequest } from './change-request.js';
+
+// Role Execution Adapter (v1.1)
+export { buildRoleExecutionContext, executeWithRoleContext, buildAllRoleContexts } from './role-execution-adapter.js';
+export type { RoleExecutionContext } from './role-execution-adapter.js';
+
+// Consensus Packet Builder (v1.1 weighted scoring)
+export { computeConsensusScore } from './packets/consensus-packet-builder.js';
+
+// Phase types
+export type { PhaseContext, PhaseResult } from './phases/index.js';

package/src/pipeline/migration.ts

@@ -0,0 +1,91 @@
+/**
+ * State Migration — bridges old 3-phase workflow to new pipeline state.
+ * Auto-triggered on load when pipelinePhase is missing from state.
+ */
+
+import type { PipelinePhase, PipelineState, PipelineRole } from './types.js';
+import { createDefaultPipelineState } from './types.js';
+import type { ProjectState, WorkflowPhase } from '../types/workflow.js';
+
+// ─── Phase Mapping ───────────────────────────────────────
+
+const LEGACY_PHASE_MAP: Record<string, PipelinePhase> = {
+  plan: 'INTAKE',
+  execution: 'IMPLEMENTATION',
+  complete: 'DONE',
+};
+
+/** Convert legacy WorkflowPhase to PipelinePhase */
+export function toPipelinePhase(legacyPhase: WorkflowPhase): PipelinePhase {
+  return LEGACY_PHASE_MAP[legacyPhase] ?? 'INTAKE';
+}
+
+/** Convert PipelinePhase back to legacy WorkflowPhase */
+export function toLegacyPhase(pipelinePhase: PipelinePhase): WorkflowPhase {
+  switch (pipelinePhase) {
+    case 'INTAKE':
+    case 'CONSENSUS_MASTER_PLAN':
+    case 'ARCHITECTURE':
+    case 'CONSENSUS_ARCHITECTURE':
+    case 'ROLE_PLANNING':
+    case 'CONSENSUS_ROLE_PLANS':
+      return 'plan';
+    case 'IMPLEMENTATION':
+    case 'QA_VALIDATION':
+    case 'REVIEW':
+    case 'AUDIT':
+    case 'PRODUCTION_GATE':
+    case 'RECOVERY_LOOP':
+      return 'execution';
+    case 'DONE':
+    case 'STUCK':
+      return 'complete';
+  }
+}
+
+// ─── Migration ───────────────────────────────────────────
+
+/** Migrate a legacy ProjectState to include PipelineState */
+export function migrateToPipelineState(state: ProjectState): PipelineState {
+  const pipeline = createDefaultPipelineState();
+
+  // Map legacy phase
+  pipeline.pipelinePhase = toPipelinePhase(state.phase);
+
+  // Derive active roles from language
+  pipeline.activeRoles = deriveActiveRoles(state.language);
+
+  return pipeline;
+}
+
+/** Check if a state object needs pipeline migration */
+export function needsPipelineMigration(state: unknown): boolean {
+  return !(state as Record<string, unknown>).pipeline;
+}
+
+// ─── Role Derivation ─────────────────────────────────────
+
+function deriveActiveRoles(language: string): PipelineRole[] {
+  const baseRoles: PipelineRole[] = [
+    'DISPATCHER', 'ARCHITECT', 'REVIEWER', 'ARBITRATOR',
+    'DEBUGGER', 'AUDITOR', 'JOURNALIST', 'RELEASE_MANAGER',
+    'QA_TESTER',
+  ];
+
+  switch (language) {
+    case 'fullstack':
+    case 'all':
+      return [
+        ...baseRoles,
+        'DB_EXPERT', 'BACKEND_PROGRAMMER', 'FRONTEND_PROGRAMMER',
+        'WEBSITE_PROGRAMMER', 'UI_UX_SPECIALIST',
+      ];
+    case 'python':
+    case 'typescript':
+      return [...baseRoles, 'BACKEND_PROGRAMMER'];
+    case 'website':
+      return [...baseRoles, 'WEBSITE_PROGRAMMER', 'MARKETING_EXPERT', 'SOCIAL_EXPERT'];
+    default:
+      return [...baseRoles, 'BACKEND_PROGRAMMER'];
+  }
+}