Pipeline Nowcast Spec

interface NowcastInput {
  pipeline: {
    deals: Array<{ amount: number; probability: number; stage: string; closeDate: string }>;
    targetCoverage: number; // default 3.0x
  };
  activity: {
    activities: Array<{ type: string; outcome: string; startDate: string }>;
    targetPerDealPerWeek: number; // default 2
    dealCount: number;
  };
  agentVelocity: {
    messages: Array<{ type: string; createdAt: number }>;
    plansCompleted: number;
    blockersOpen: number;
  };
  commissioning: {
    features: Array<{ name: string; currentLevel: number; forecastLevel: number }>;
  };
  predictions: {
    entries: Array<{ confidenceScore: number; accuracyScore: number | null; status: string }>;
    evidence: Array<PredictionEvidence>; // evidence ledger entries
    maturity: Array<PredictionMaturity>; // per-prediction maturity state
  };
  config?: {
    weights?: Partial<SignalWeights>;
    decayHalfLifeDays?: number;
    thresholds?: { onTrack?: number; warning?: number };
  };
}

interface NowcastResult {
  result: {
    composite: number; // 0-1
    status: "on_track" | "warning" | "critical";
    signals: NowcastSignal[]; // per-signal breakdown
    topRisk: string; // highest-variance signal name
    topMomentum: string; // most-improving signal name
  };
  metadata: {
    algorithm: "pipeline-nowcast";
    version: string;
    executionTimeMs: number;
    signalCount: number;
  };
  reasoning: string[];
  confidence: number; // 0-1 based on signal coverage
  recommendations: {
    status: "on_track" | "warning" | "critical";
    actions: string[];
    signalsNeedingAttention: string[];
  };
}

interface NowcastSignal {
  name: string;
  score: number; // 0-1 normalized
  weight: number; // configured weight
  variance: number; // (actual - forecast) / forecast
  trend: "improving" | "stable" | "declining";
  freshness: number; // 0-1 decay factor
}

export const PIPELINE_NOWCAST = {
  PIPELINE_WEIGHT: 0.35,
  ACTIVITY_WEIGHT: 0.25,
  AGENT_VELOCITY_WEIGHT: 0.15,
  COMMISSIONING_WEIGHT: 0.15,
  PREDICTION_WEIGHT: 0.1,
  DECAY_HALF_LIFE_DAYS: 14,
  ON_TRACK_THRESHOLD: 0.7,
  WARNING_THRESHOLD: 0.4,
  MIN_SIGNALS_FOR_CONFIDENCE: 3,
  TARGET_PIPELINE_COVERAGE: 3.0,
  TARGET_ACTIVITY_PER_DEAL_WEEK: 2,
} as const;

interface PredictionEvidence {
  predictionId: string; // links to prediction-database.md row
  signalType: "internal" | "market" | "resolution";
  dataPoint: string; // what was measured
  value: number; // the measurement
  source: string; // where it came from
  timestamp: string; // ISO 8601
  direction: "strengthens" | "weakens" | "neutral";
  convictionDelta: number; // how much this moved the score (-1 to +1)
}

interface PredictionMaturity {
  level: "L0_stated" | "L1_instrumented" | "L2_tracked" | "L3_tested" | "L4_resolved";
  evidenceCount: number;
  lastUpdated: string;
  convictionHistory: Array<{ score: number; date: string; reason: string }>;
}

interface StateTransition {
  featureId: string; // commissioning dashboard row
  fromLevel: number; // 0-4
  toLevel: number; // 0-4
  timestamp: string; // ISO 8601
  evidence: string; // what proved the transition
  agent: string; // who/what triggered it
}