popeye-cli 1.10.0 → 2.1.0

package/src/pipeline/orchestrator.ts

@@ -0,0 +1,322 @@
+/**
+ * Pipeline Orchestrator — top-level loop driving pipeline from any phase
+ * to completion. Implements deterministic transition logic (P0-A).
+ *
+ * Key rule: requires_phase_rewind_to ONLY takes effect after RECOVERY_LOOP
+ * completes successfully. Any failure from any non-recovery phase always
+ * goes to RECOVERY_LOOP first.
+ *
+ * v1.1: Constitution verification, CR-based phase routing, gateResult merge,
+ *       and RCA rewind support.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type {
+  PipelinePhase,
+  PipelineState,
+  PipelineResult,
+  RCAPacket,
+} from './types.js';
+import { createDefaultPipelineState } from './types.js';
+import { createGateEngine } from './gate-engine.js';
+import type { GateResult } from './gate-engine.js';
+import { createArtifactManager } from './artifact-manager.js';
+import { createSkillLoader } from './skill-loader.js';
+import { createConsensusRunner } from './consensus/consensus-runner.js';
+import { verifyConstitution } from './constitution.js';
+
+import {
+  runIntake,
+  runConsensusMasterPlan,
+  runArchitecture,
+  runConsensusArchitecture,
+  runRolePlanning,
+  runConsensusRolePlans,
+  runImplementation,
+  runQaValidation,
+  runReview,
+  runAudit,
+  runProductionGate,
+  runRecoveryLoop,
+  runDone,
+  runStuck,
+} from './phases/index.js';
+import type { PhaseContext, PhaseResult } from './phases/index.js';
+import type { ProjectState } from '../types/workflow.js';
+import type { ConsensusConfig } from '../types/consensus.js';
+
+// ─── Types ───────────────────────────────────────────────
+
+export interface PipelineOptions {
+  projectDir: string;
+  state: ProjectState;
+  consensusConfig?: Partial<ConsensusConfig>;
+  /** User steering, upgrade context, or resume instructions */
+  additionalContext?: string;
+  onPhaseStart?: (phase: PipelinePhase) => void;
+  onPhaseComplete?: (phase: PipelinePhase, result: PhaseResult) => void;
+  onProgress?: (message: string) => void;
+}
+
+// ─── Phase Dispatch Map ──────────────────────────────────
+
+const PHASE_HANDLERS: Record<PipelinePhase, (ctx: PhaseContext) => Promise<PhaseResult>> = {
+  INTAKE: runIntake,
+  CONSENSUS_MASTER_PLAN: runConsensusMasterPlan,
+  ARCHITECTURE: runArchitecture,
+  CONSENSUS_ARCHITECTURE: runConsensusArchitecture,
+  ROLE_PLANNING: runRolePlanning,
+  CONSENSUS_ROLE_PLANS: runConsensusRolePlans,
+  IMPLEMENTATION: runImplementation,
+  QA_VALIDATION: runQaValidation,
+  REVIEW: runReview,
+  AUDIT: runAudit,
+  PRODUCTION_GATE: runProductionGate,
+  RECOVERY_LOOP: runRecoveryLoop,
+  DONE: runDone,
+  STUCK: runStuck,
+};
+
+/** Phases after which we check for pending CRs */
+const CR_CHECK_PHASES: Set<PipelinePhase> = new Set(['REVIEW', 'AUDIT']);
+
+// ─── Orchestrator ────────────────────────────────────────
+
+/** Run the full pipeline from current phase to completion */
+export async function runPipeline(options: PipelineOptions): Promise<PipelineResult> {
+  const {
+    projectDir,
+    state,
+    consensusConfig,
+    additionalContext,
+    onPhaseStart,
+    onPhaseComplete,
+    onProgress,
+  } = options;
+
+  // Initialize pipeline state if needed
+  const pipeline: PipelineState = (state as unknown as { pipeline?: PipelineState }).pipeline
+    ?? createDefaultPipelineState();
+
+  // Persist user guidance in pipeline state so it survives resume
+  if (additionalContext && !pipeline.sessionGuidance) {
+    pipeline.sessionGuidance = additionalContext;
+  }
+
+  // Create context dependencies
+  const gateEngine = createGateEngine();
+  const artifactManager = createArtifactManager(projectDir);
+  const skillLoader = createSkillLoader(projectDir);
+  const consensusRunner = createConsensusRunner(projectDir, consensusConfig);
+
+  // Ensure docs structure
+  artifactManager.ensureDocsStructure();
+
+  const context: PhaseContext = {
+    state,
+    pipeline,
+    projectDir,
+    skillLoader,
+    artifactManager,
+    gateEngine,
+    consensusRunner,
+  };
+
+  let phase = pipeline.pipelinePhase;
+  let failedPhase: PipelinePhase | null = null;
+
+  // ─── Main Loop ───────────────────────────────────────
+  while (phase !== 'DONE' && phase !== 'STUCK') {
+    onPhaseStart?.(phase);
+    onProgress?.(`Pipeline phase: ${phase}`);
+
+    // Execute the current phase
+    const handler = PHASE_HANDLERS[phase];
+    if (!handler) {
+      return {
+        success: false,
+        finalPhase: phase,
+        artifacts: pipeline.artifacts,
+        recoveryIterations: pipeline.recoveryCount,
+        error: `No handler for phase: ${phase}`,
+      };
+    }
+
+    let result: PhaseResult;
+    try {
+      result = await handler(context);
+    } catch (err) {
+      result = {
+        phase,
+        success: false,
+        artifacts: [],
+        message: 'Phase handler threw an exception',
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+
+    onPhaseComplete?.(phase, result);
+
+    // v1.1: Verify constitution integrity before evaluating gate
+    const constitutionCheck = verifyConstitution(pipeline, projectDir);
+
+    // Evaluate gate with constitution verification result
+    const gateResult = gateEngine.evaluateGate(phase, pipeline, {
+      constitutionValid: constitutionCheck.valid,
+      constitutionReason: constitutionCheck.reason,
+    });
+
+    // v1.1: Merge gate result with any pre-existing phase data (preserves consensus scores)
+    mergeGateResult(pipeline, phase, gateResult);
+
+    if (gateResult.pass) {
+      // ─── PASS ────────────────────────────────────────
+
+      // v1.1: Check for pending CRs after REVIEW/AUDIT — route to consensus before continuing
+      if (CR_CHECK_PHASES.has(phase)) {
+        const crRoute = getNextCRRoute(pipeline);
+        if (crRoute) {
+          onProgress?.(`CR ${crRoute.cr_id} routing to ${crRoute.target_phase}`);
+          phase = crRoute.target_phase;
+          pipeline.pipelinePhase = phase;
+          continue;
+        }
+      }
+
+      if (phase === 'RECOVERY_LOOP') {
+        // Recovery succeeded. RCA may specify rewind target.
+        const rca = getLatestRCA(pipeline, projectDir);
+        if (rca?.requires_phase_rewind_to) {
+          phase = rca.requires_phase_rewind_to;
+        } else {
+          // Retest the phase that failed
+          phase = failedPhase ?? 'QA_VALIDATION';
+        }
+        failedPhase = null;
+      } else {
+        // Normal progression
+        phase = gateEngine.getNextPhase(phase, gateResult);
+      }
+    } else {
+      // ─── FAIL ────────────────────────────────────────
+      if (pipeline.recoveryCount >= pipeline.maxRecoveryIterations) {
+        phase = 'STUCK';
+      } else {
+        failedPhase = phase;
+        pipeline.failedPhase = phase;
+        phase = 'RECOVERY_LOOP';
+        pipeline.recoveryCount++;
+      }
+    }
+
+    // Update pipeline phase in state
+    pipeline.pipelinePhase = phase;
+    onProgress?.(`Transitioning to: ${phase}`);
+  }
+
+  // ─── Terminal State ────────────────────────────────────
+  // Run the terminal phase handler (DONE or STUCK)
+  if (phase === 'DONE' || phase === 'STUCK') {
+    const terminalHandler = PHASE_HANDLERS[phase];
+    if (terminalHandler) {
+      try {
+        await terminalHandler(context);
+      } catch {
+        // Best-effort for terminal phases
+      }
+    }
+  }
+
+  return {
+    success: phase === 'DONE',
+    finalPhase: phase,
+    artifacts: pipeline.artifacts,
+    recoveryIterations: pipeline.recoveryCount,
+    error: phase !== 'DONE'
+      ? `Pipeline stuck after ${pipeline.recoveryCount} recovery iterations`
+      : undefined,
+  };
+}
+
+/** Resume pipeline from saved state */
+export async function resumePipeline(options: PipelineOptions): Promise<PipelineResult> {
+  // Resume is the same as run — it picks up from pipeline.pipelinePhase
+  return runPipeline(options);
+}
+
+// ─── Helpers ─────────────────────────────────────────────
+
+/**
+ * Merge gate engine result with existing phase data in gateResults.
+ * Preserves score/consensusScore stored by consensus phase handlers
+ * while updating pass/blockers from the gate engine.
+ */
+function mergeGateResult(
+  pipeline: PipelineState,
+  phase: PipelinePhase,
+  gateResult: GateResult,
+): void {
+  const existing = pipeline.gateResults[phase];
+  if (existing?.score !== undefined || existing?.consensusScore !== undefined) {
+    // Preserve consensus scores from the phase handler
+    pipeline.gateResults[phase] = {
+      ...gateResult,
+      score: existing.score ?? gateResult.score,
+      consensusScore: existing.consensusScore ?? gateResult.consensusScore,
+    };
+  } else {
+    pipeline.gateResults[phase] = gateResult;
+  }
+}
+
+/**
+ * Find the next pending change request that needs routing.
+ * Returns the first 'proposed' CR and marks it as 'approved' (routed).
+ */
+function getNextCRRoute(
+  pipeline: PipelineState,
+): { cr_id: string; target_phase: PipelinePhase } | undefined {
+  const pending = pipeline.pendingChangeRequests;
+  if (!pending) return undefined;
+
+  const nextCR = pending.find((cr) => cr.status === 'proposed');
+  if (!nextCR) return undefined;
+
+  // Mark as approved (it has been routed to the consensus phase)
+  nextCR.status = 'approved';
+
+  return {
+    cr_id: nextCR.cr_id,
+    target_phase: nextCR.target_phase,
+  };
+}
+
+/**
+ * Read the latest RCA packet from stored artifacts.
+ * Parses the JSON artifact file to extract rewind targets.
+ */
+function getLatestRCA(
+  pipeline: PipelineState,
+  projectDir: string,
+): RCAPacket | undefined {
+  const rcaArtifacts = pipeline.artifacts
+    .filter((a) => a.type === 'rca_report' && a.content_type === 'json')
+    .sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+
+  if (rcaArtifacts.length === 0) return undefined;
+
+  // Read the latest RCA artifact from disk
+  const latest = rcaArtifacts[0];
+  const rcaPath = join(projectDir, latest.path);
+  if (!existsSync(rcaPath)) return undefined;
+
+  try {
+    const content = readFileSync(rcaPath, 'utf-8');
+    const parsed = JSON.parse(content) as RCAPacket;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}

package/src/pipeline/packets/audit-report-builder.ts

@@ -0,0 +1,47 @@
+/**
+ * Audit Report Builder — constructs structured AuditReports
+ * with auto-computed status, risk score, and recovery flag (P2-1).
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import type { ArtifactRef, AuditFinding, AuditReport } from '../types.js';
+
+export interface BuildAuditReportArgs {
+  repoSnapshot: ArtifactRef;
+  findings: AuditFinding[];
+}
+
+/** Severity weights for risk score calculation */
+const SEVERITY_WEIGHTS: Record<string, number> = {
+  P0: 40,
+  P1: 20,
+  P2: 8,
+  P3: 2,
+};
+
+export function buildAuditReport(args: BuildAuditReportArgs): AuditReport {
+  const { repoSnapshot, findings } = args;
+
+  const hasBlockingFindings = findings.some((f) => f.blocking);
+  const overallStatus = hasBlockingFindings ? 'FAIL' : 'PASS';
+
+  // Risk score: sum of severity weights, capped at 100
+  const rawScore = findings.reduce((sum, f) => sum + (SEVERITY_WEIGHTS[f.severity] ?? 0), 0);
+  const systemRiskScore = Math.min(100, rawScore);
+
+  // Recovery needed if any blocking P0/P1 findings
+  const recoveryRequired = findings.some(
+    (f) => f.blocking && (f.severity === 'P0' || f.severity === 'P1'),
+  );
+
+  return {
+    audit_id: randomUUID(),
+    timestamp: new Date().toISOString(),
+    repo_snapshot: repoSnapshot,
+    overall_status: overallStatus,
+    findings,
+    system_risk_score: systemRiskScore,
+    recovery_required: recoveryRequired,
+  };
+}

package/src/pipeline/packets/consensus-packet-builder.ts

@@ -0,0 +1,112 @@
+/**
+ * Consensus Packet Builder — aggregates reviewer votes into a ConsensusPacket.
+ * Auto-computes consensus result (score, approval) and final status.
+ * v1.1: Added confidence-weighted scoring.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import type {
+  ArtifactRef,
+  ReviewerVote,
+  ConsensusPacket,
+} from '../types.js';
+
+export interface ConsensusRules {
+  threshold: number;
+  quorum: number;
+  min_reviewers: number;
+}
+
+export interface BuildConsensusPacketArgs {
+  planPacketRef: ArtifactRef;
+  votes: ReviewerVote[];
+  rules: ConsensusRules;
+  arbitratorResult?: {
+    decision: string;
+    merged_patch?: string;
+    artifact_ref?: ArtifactRef;
+  };
+}
+
+/** Vote weight mapping: APPROVE=1.0, CONDITIONAL=0.5, REJECT=0.0 */
+const VOTE_WEIGHTS: Record<string, number> = {
+  'APPROVE': 1.0,
+  'CONDITIONAL': 0.5,
+  'REJECT': 0.0,
+};
+
+/**
+ * Compute both simple and confidence-weighted consensus scores.
+ *
+ * Simple score: approve count / total votes (backward compat).
+ * Weighted score: each vote's weight (APPROVE=1, CONDITIONAL=0.5, REJECT=0)
+ * multiplied by voter confidence, then averaged by total confidence.
+ * If any vote has blocking_issues, weighted_score is forced to 0.
+ */
+export function computeConsensusScore(
+  votes: ReviewerVote[],
+): { score: number; weighted_score: number } {
+  if (votes.length === 0) return { score: 0, weighted_score: 0 };
+
+  // Simple score (backward compat): approve ratio
+  const approvedCount = votes.filter((v) => v.vote === 'APPROVE').length;
+  const score = approvedCount / votes.length;
+
+  // Weighted score: confidence-weighted vote values
+  let totalWeight = 0;
+  let weightedSum = 0;
+  for (const v of votes) {
+    const w = v.confidence;
+    weightedSum += (VOTE_WEIGHTS[v.vote] ?? 0) * w;
+    totalWeight += w;
+  }
+  const rawWeighted = totalWeight > 0 ? weightedSum / totalWeight : 0;
+
+  // Override: any vote with blocking_issues forces weighted_score to 0
+  const hasBlockingIssues = votes.some((v) => v.blocking_issues.length > 0);
+
+  return {
+    score,
+    weighted_score: hasBlockingIssues ? 0 : rawWeighted,
+  };
+}
+
+export function buildConsensusPacket(args: BuildConsensusPacketArgs): ConsensusPacket {
+  const { planPacketRef, votes, rules, arbitratorResult } = args;
+
+  const { score, weighted_score } = computeConsensusScore(votes);
+  const approved = score >= rules.threshold && votes.length >= rules.quorum;
+
+  let finalStatus: 'APPROVED' | 'REJECTED' | 'ARBITRATED';
+  if (arbitratorResult) {
+    finalStatus = 'ARBITRATED';
+  } else if (approved) {
+    finalStatus = 'APPROVED';
+  } else {
+    finalStatus = 'REJECTED';
+  }
+
+  return {
+    metadata: {
+      packet_id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      plan_packet_id: planPacketRef.artifact_id,
+    },
+    plan_packet_reference: planPacketRef,
+    reviewer_votes: votes,
+    consensus_rules: {
+      threshold: rules.threshold,
+      quorum: rules.quorum,
+      min_reviewers: rules.min_reviewers,
+    },
+    consensus_result: {
+      approved,
+      score,
+      weighted_score,
+      participating_reviewers: votes.length,
+    },
+    arbitrator_result: arbitratorResult,
+    final_status: finalStatus,
+  };
+}

package/src/pipeline/packets/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Re-exports all packet builders.
+ */
+
+export { buildPlanPacket } from './plan-packet-builder.js';
+export type { BuildPlanPacketArgs } from './plan-packet-builder.js';
+
+export { buildConsensusPacket } from './consensus-packet-builder.js';
+export type { BuildConsensusPacketArgs, ConsensusRules } from './consensus-packet-builder.js';
+
+export { buildRCAPacket } from './rca-packet-builder.js';
+export type { BuildRCAPacketArgs } from './rca-packet-builder.js';
+
+export { buildAuditReport } from './audit-report-builder.js';
+export type { BuildAuditReportArgs } from './audit-report-builder.js';

package/src/pipeline/packets/plan-packet-builder.ts

@@ -0,0 +1,52 @@
+/**
+ * Plan Packet Builder — deterministic construction of PlanPackets.
+ * Auto-generates packet_id, timestamp, auto-increments version.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import type {
+  PipelinePhase,
+  PipelineRole,
+  ArtifactRef,
+  DependencyEdge,
+  Constraint,
+  PlanPacket,
+} from '../types.js';
+
+export interface BuildPlanPacketArgs {
+  phase: PipelinePhase;
+  submittedBy: PipelineRole;
+  masterPlanRef: ArtifactRef;
+  constitutionRef: ArtifactRef;
+  repoSnapshotRef: ArtifactRef;
+  proposedArtifacts: ArtifactRef[];
+  acceptanceCriteria: string[];
+  dependencies: DependencyEdge[];
+  constraints: Constraint[];
+  openQuestions?: string[];
+  /** Override version (defaults to 1) */
+  version?: number;
+}
+
+export function buildPlanPacket(args: BuildPlanPacketArgs): PlanPacket {
+  return {
+    metadata: {
+      packet_id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      phase: args.phase,
+      submitted_by: args.submittedBy,
+      version: args.version ?? 1,
+    },
+    references: {
+      master_plan: args.masterPlanRef,
+      constitution: args.constitutionRef,
+      repo_snapshot: args.repoSnapshotRef,
+    },
+    proposed_artifacts: args.proposedArtifacts,
+    acceptance_criteria: args.acceptanceCriteria,
+    artifact_dependencies: args.dependencies,
+    constraints: args.constraints,
+    open_questions: args.openQuestions,
+  };
+}

package/src/pipeline/packets/rca-packet-builder.ts

@@ -0,0 +1,38 @@
+/**
+ * RCA Packet Builder — constructs Root Cause Analysis packets
+ * with explicit phase rewind routing (P1-3).
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import type { PipelinePhase, RCAPacket } from '../types.js';
+
+export interface BuildRCAPacketArgs {
+  incidentSummary: string;
+  symptoms: string[];
+  rootCause: string;
+  responsibleLayer: string;
+  originPhase: PipelinePhase;
+  governanceGap: string;
+  correctiveActions: string[];
+  prevention: string;
+  rewindTo?: PipelinePhase;
+  requiresConsensusOn?: PipelinePhase[];
+}
+
+export function buildRCAPacket(args: BuildRCAPacketArgs): RCAPacket {
+  return {
+    rca_id: randomUUID(),
+    timestamp: new Date().toISOString(),
+    incident_summary: args.incidentSummary,
+    symptoms: args.symptoms,
+    root_cause: args.rootCause,
+    responsible_layer: args.responsibleLayer,
+    origin_phase: args.originPhase,
+    governance_gap: args.governanceGap,
+    corrective_actions: args.correctiveActions,
+    prevention: args.prevention,
+    requires_phase_rewind_to: args.rewindTo,
+    requires_consensus_on: args.requiresConsensusOn,
+  };
+}

package/src/pipeline/phases/architecture.ts

@@ -0,0 +1,73 @@
+/**
+ * ARCHITECTURE phase — create system architecture + explicit contracts.
+ * Uses ARCHITECT skill via executePrompt().
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { PhaseContext, PhaseResult } from './phase-context.js';
+import { successResult, failureResult } from './phase-context.js';
+import { generateRepoSnapshot, createSnapshotArtifact } from '../repo-snapshot.js';
+
+export async function runArchitecture(context: PhaseContext): Promise<PhaseResult> {
+  const { pipeline, artifactManager, skillLoader, projectDir } = context;
+  const artifacts = [];
+
+  try {
+    // 1. Load architect skill
+    const architectSkill = skillLoader.loadSkill('ARCHITECT');
+
+    // 2. Read approved master plan
+    const masterPlanArtifact = pipeline.artifacts.find((a) => a.type === 'master_plan');
+    let masterPlanContent = '';
+    if (masterPlanArtifact) {
+      const fullPath = join(projectDir, masterPlanArtifact.path);
+      if (existsSync(fullPath)) {
+        masterPlanContent = readFileSync(fullPath, 'utf-8');
+      }
+    }
+
+    // 3. Generate architecture via Claude
+    const { executePrompt } = await import('../../adapters/claude.js');
+    const architecturePrompt = [
+      architectSkill.systemPrompt,
+      '',
+      '## Master Plan',
+      masterPlanContent,
+      '',
+      '## Instructions',
+      'Create the system architecture document covering:',
+      '- System topology & boundaries',
+      '- API contracts (endpoints, methods, request/response)',
+      '- Auth model and security assumptions',
+      '- Data ownership boundaries',
+      '- Env var list',
+      '- Repo layout blueprint',
+      '- Error handling strategy',
+    ].join('\n');
+
+    const result = await executePrompt(architecturePrompt);
+    const architectureDoc = result.response;
+
+    // 4. Store architecture artifact
+    const archEntry = artifactManager.createAndStoreText(
+      'architecture',
+      architectureDoc,
+      'ARCHITECTURE',
+    );
+    artifacts.push(archEntry);
+
+    // 5. Generate fresh repo snapshot
+    const snapshot = await generateRepoSnapshot(projectDir);
+    const snapshotEntry = createSnapshotArtifact(snapshot, artifactManager, 'ARCHITECTURE');
+    artifacts.push(snapshotEntry);
+    pipeline.latestRepoSnapshot = artifactManager.toArtifactRef(snapshotEntry);
+
+    pipeline.artifacts.push(...artifacts);
+    return successResult('ARCHITECTURE', artifacts, 'Architecture document created');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error';
+    return failureResult('ARCHITECTURE', 'Architecture creation failed', message);
+  }
+}