@contractspec/module.lifecycle-core 1.56.1 → 1.58.0

package/dist/index.js

@@ -1,6 +1,428 @@
-import { StageSignalCollector } from "./collectors/signal-collector.js";
-import { StageScorer } from "./scoring/stage-scorer.js";
-import { LifecycleMilestonePlanner } from "./planning/milestone-planner.js";
-import { LifecycleOrchestrator } from "./orchestrator/lifecycle-orchestrator.js";
+// @bun
+// src/collectors/signal-collector.ts
+import {
+  CapitalPhase,
+  CompanyPhase,
+  ProductPhase
+} from "@contractspec/lib.lifecycle";
+var DEFAULT_AXES = {
+  product: ProductPhase.Sketch,
+  company: CompanyPhase.Solo,
+  capital: CapitalPhase.Bootstrapped
+};
 
-export { LifecycleMilestonePlanner, LifecycleOrchestrator, StageScorer, StageSignalCollector };
+class StageSignalCollector {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  async collect(input = {}) {
+    const axes = {
+      ...DEFAULT_AXES,
+      ...input.axes ?? {}
+    };
+    const metricsSnapshots = [];
+    const aggregatedSignals = [...input.signals ?? []];
+    const questionnaireAnswers = {
+      ...input.questionnaireAnswers ?? {}
+    };
+    if (input.metrics) {
+      metricsSnapshots.push(input.metrics);
+    }
+    if (this.options.analyticsAdapter) {
+      const result = await this.options.analyticsAdapter.fetch();
+      if (result.axes)
+        Object.assign(axes, result.axes);
+      if (result.metrics)
+        metricsSnapshots.push(result.metrics);
+      if (result.signals)
+        aggregatedSignals.push(...result.signals);
+    }
+    if (this.options.questionnaireAdapter) {
+      const result = await this.options.questionnaireAdapter.fetch();
+      if (result.axes)
+        Object.assign(axes, result.axes);
+      if (result.signals)
+        aggregatedSignals.push(...result.signals);
+      Object.assign(questionnaireAnswers, result.answers);
+    }
+    if (this.options.intentAdapter) {
+      const result = await this.options.intentAdapter.fetch();
+      if (result.signals)
+        aggregatedSignals.push(...result.signals);
+    }
+    const metrics = mergeMetricSnapshots(metricsSnapshots);
+    return {
+      axes,
+      metrics,
+      signals: dedupeSignals(aggregatedSignals),
+      questionnaireAnswers: Object.keys(questionnaireAnswers).length ? questionnaireAnswers : undefined
+    };
+  }
+}
+var mergeMetricSnapshots = (snapshots) => snapshots.reduce((acc, snapshot) => {
+  Object.entries(snapshot ?? {}).forEach(([key, value]) => {
+    if (value !== undefined && value !== null) {
+      acc[key] = value;
+    }
+  });
+  return acc;
+}, {});
+var dedupeSignals = (signals) => {
+  const seen = new Set;
+  return signals.filter((signal) => {
+    if (!signal.id)
+      return true;
+    if (seen.has(signal.id))
+      return false;
+    seen.add(signal.id);
+    return true;
+  });
+};
+// src/scoring/stage-scorer.ts
+import {
+  LIFECYCLE_STAGE_META,
+  LifecycleStage
+} from "@contractspec/lib.lifecycle";
+// src/data/stage-weights.json
+var stage_weights_default = {
+  Exploration: {
+    base: 0.35,
+    metrics: {
+      activeUsers: { weight: 0.3, direction: "lte", threshold: 5 },
+      customerCount: { weight: 0.2, direction: "lte", threshold: 3 },
+      teamSize: { weight: 0.1, direction: "lte", threshold: 3 }
+    },
+    signalKinds: {
+      qualitative: 0.4,
+      metric: 0.1
+    }
+  },
+  ProblemSolutionFit: {
+    base: 0.4,
+    metrics: {
+      activeUsers: { weight: 0.2, direction: "gte", threshold: 5 },
+      customerCount: { weight: 0.2, direction: "gte", threshold: 3 }
+    },
+    signalKinds: {
+      qualitative: 0.3,
+      event: 0.1
+    }
+  },
+  MvpEarlyTraction: {
+    base: 0.45,
+    metrics: {
+      activeUsers: { weight: 0.25, direction: "gte", threshold: 25 },
+      weeklyActiveUsers: {
+        weight: 0.25,
+        direction: "gte",
+        threshold: 20
+      },
+      retentionRate: { weight: 0.2, direction: "gte", threshold: 0.25 }
+    },
+    signalKinds: {
+      metric: 0.15,
+      event: 0.1
+    }
+  },
+  ProductMarketFit: {
+    base: 0.5,
+    metrics: {
+      retentionRate: {
+        weight: 0.35,
+        direction: "gte",
+        threshold: 0.45
+      },
+      monthlyRecurringRevenue: {
+        weight: 0.25,
+        direction: "gte",
+        threshold: 1e4
+      },
+      customerCount: { weight: 0.2, direction: "gte", threshold: 30 }
+    },
+    signalKinds: {
+      metric: 0.15,
+      event: 0.1
+    }
+  },
+  GrowthScaleUp: {
+    base: 0.55,
+    metrics: {
+      retentionRate: { weight: 0.2, direction: "gte", threshold: 0.55 },
+      monthlyRecurringRevenue: {
+        weight: 0.3,
+        direction: "gte",
+        threshold: 50000
+      },
+      teamSize: { weight: 0.15, direction: "gte", threshold: 15 }
+    },
+    signalKinds: {
+      event: 0.2,
+      metric: 0.15
+    }
+  },
+  ExpansionPlatform: {
+    base: 0.6,
+    metrics: {
+      monthlyRecurringRevenue: {
+        weight: 0.35,
+        direction: "gte",
+        threshold: 150000
+      },
+      customerCount: { weight: 0.2, direction: "gte", threshold: 100 },
+      teamSize: { weight: 0.15, direction: "gte", threshold: 40 }
+    },
+    signalKinds: {
+      event: 0.2,
+      milestone: 0.1
+    }
+  },
+  MaturityRenewal: {
+    base: 0.6,
+    metrics: {
+      monthlyRecurringRevenue: {
+        weight: 0.25,
+        direction: "gte",
+        threshold: 250000
+      },
+      teamSize: { weight: 0.15, direction: "gte", threshold: 80 },
+      burnMultiple: { weight: 0.2, direction: "lte", threshold: 1.5 }
+    },
+    signalKinds: {
+      event: 0.2,
+      milestone: 0.15
+    }
+  }
+};
+
+// src/scoring/stage-scorer.ts
+var DEFAULT_WEIGHTS = stage_weights_default;
+
+class StageScorer {
+  weights;
+  constructor(weights = DEFAULT_WEIGHTS) {
+    this.weights = weights;
+  }
+  score(input) {
+    const kindStrength = evaluateSignalKinds(input.signals);
+    const scores = Object.values(LifecycleStage).filter(isStageValue).map((stage) => {
+      const stageName = LifecycleStage[stage];
+      const config = this.weights[stageName] ?? { base: 0.5 };
+      let score = config.base ?? 0.5;
+      let contributions = 0;
+      const totalPossible = Object.keys(config.metrics ?? {}).length + Object.keys(config.signalKinds ?? {}).length || 1;
+      const supportingSignals = [];
+      if (config.metrics) {
+        Object.entries(config.metrics).forEach(([metricKey, metricConfig]) => {
+          const value = input.metrics[metricKey];
+          if (value === undefined || value === null)
+            return;
+          if (passesThreshold(value, metricConfig)) {
+            score += metricConfig.weight;
+            contributions += 1;
+            supportingSignals.push(`metric:${metricKey}`);
+          } else {
+            score += metricConfig.weight * 0.25;
+          }
+        });
+      }
+      if (config.signalKinds) {
+        Object.entries(config.signalKinds).forEach(([kind, weight]) => {
+          const strength = kindStrength[kind] ?? 0;
+          if (strength > 0 && typeof weight === "number") {
+            score += weight;
+            contributions += 1;
+            supportingSignals.push(`signal:${kind}`);
+          }
+        });
+      }
+      score = clamp(score, 0, 1.25);
+      const confidence = clamp(contributions / totalPossible, 0.1, 1);
+      return {
+        stage,
+        score,
+        confidence,
+        supportingSignals
+      };
+    });
+    return scores.sort((a, b) => {
+      if (b.score === a.score) {
+        return b.confidence - a.confidence;
+      }
+      return b.score - a.score;
+    });
+  }
+}
+var passesThreshold = (value, config) => {
+  const direction = config.direction ?? "gte";
+  if (direction === "gte") {
+    return value >= config.threshold;
+  }
+  return value <= config.threshold;
+};
+var clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+var evaluateSignalKinds = (signals) => signals.reduce((acc, signal) => {
+  const key = signal.kind ?? "unknown";
+  acc[key] = (acc[key] ?? 0) + (signal.weight ?? 1);
+  return acc;
+}, {});
+var isStageValue = (value) => typeof value === "number" && (value in LIFECYCLE_STAGE_META);
+// src/orchestrator/lifecycle-orchestrator.ts
+import {
+  LIFECYCLE_STAGE_META as LIFECYCLE_STAGE_META2,
+  LifecycleStage as LifecycleStage2
+} from "@contractspec/lib.lifecycle";
+
+class LifecycleOrchestrator {
+  collector;
+  scorer;
+  planner;
+  constructor(options) {
+    this.collector = options.collector;
+    this.scorer = options.scorer;
+    this.planner = options.milestonePlanner;
+  }
+  async run(input) {
+    const collected = await this.collector.collect(input);
+    const scorecard = this.scorer.score({
+      metrics: collected.metrics,
+      signals: collected.signals
+    });
+    const top = scorecard[0] ?? fallbackScore();
+    const meta = LIFECYCLE_STAGE_META2[top.stage];
+    return {
+      stage: top.stage,
+      confidence: top.confidence,
+      axes: collected.axes,
+      signals: collected.signals,
+      metrics: toMetricRecord(collected.metrics),
+      gaps: meta.focusAreas.slice(0, 3),
+      focusAreas: meta.focusAreas,
+      scorecard,
+      generatedAt: new Date().toISOString()
+    };
+  }
+  getUpcomingMilestones(stage, completedMilestoneIds = [], limit = 5) {
+    if (!this.planner)
+      return [];
+    return this.planner.getUpcoming(stage, completedMilestoneIds, limit);
+  }
+}
+var fallbackScore = () => ({
+  stage: LifecycleStage2.Exploration,
+  score: 0.3,
+  confidence: 0.3,
+  supportingSignals: []
+});
+var toMetricRecord = (snapshot) => Object.entries(snapshot ?? {}).reduce((acc, [key, value]) => {
+  if (typeof value === "number") {
+    acc[key] = value;
+  }
+  return acc;
+}, {});
+// src/data/milestones-catalog.json
+var milestones_catalog_default = [
+  {
+    id: "stage0-problem-statement",
+    stage: 0,
+    category: "product",
+    title: "Write the pain statement",
+    description: "Capture the clearest description of the top problem in the customer\u2019s own words.",
+    priority: 1,
+    actionItems: [
+      "Interview at least 5 ideal customers",
+      "Synthesize quotes into a one-page brief"
+    ]
+  },
+  {
+    id: "stage1-prototype-loop",
+    stage: 1,
+    category: "product",
+    title: "Prototype feedback loop",
+    description: "Ship a clickable prototype and gather 3 rounds of feedback.",
+    priority: 2,
+    actionItems: [
+      "Create a low-fidelity prototype",
+      "Schedule standing feedback calls"
+    ]
+  },
+  {
+    id: "stage2-activation",
+    stage: 2,
+    category: "operations",
+    title: "Activation checklist",
+    description: "Define the minimum steps required for a new user to succeed.",
+    priority: 1,
+    actionItems: [
+      "Document onboarding flow",
+      "Instrument activation analytics"
+    ]
+  },
+  {
+    id: "stage3-retention-narrative",
+    stage: 3,
+    category: "product",
+    title: "Retention narrative",
+    description: "Create the before/after story that proves why users stay.",
+    priority: 2,
+    actionItems: [
+      "Interview 3 retained users",
+      "Publish a one-pager with concrete metrics"
+    ]
+  },
+  {
+    id: "stage4-growth-loop",
+    stage: 4,
+    category: "growth",
+    title: "Install a growth loop",
+    description: "Stand up a repeatable acquisition \u2192 activation \u2192 referral motion.",
+    priority: 1,
+    actionItems: [
+      "Define loop metrics",
+      "Assign owners for each stage",
+      "Review weekly"
+    ]
+  },
+  {
+    id: "stage5-platform-blueprint",
+    stage: 5,
+    category: "product",
+    title: "Platform blueprint",
+    description: "Align on APIs, integrations, and governance for partners.",
+    priority: 2,
+    actionItems: [
+      "Create integration scoring rubric",
+      "Publish partner onboarding checklist"
+    ]
+  },
+  {
+    id: "stage6-renewal-ops",
+    stage: 6,
+    category: "operations",
+    title: "Renewal operating rhythm",
+    description: "Decide whether to optimize, reinvest, or sunset each major surface.",
+    priority: 1,
+    actionItems: [
+      "Hold quarterly renewal review",
+      "Document reinvestment bets"
+    ]
+  }
+];
+
+// src/planning/milestone-planner.ts
+class LifecycleMilestonePlanner {
+  milestones;
+  constructor(customCatalog) {
+    this.milestones = customCatalog ?? milestones_catalog_default;
+  }
+  getUpcoming(stage, completedIds = [], limit = 5) {
+    const completedSet = new Set(completedIds);
+    return this.milestones.filter((milestone) => milestone.stage === stage && !completedSet.has(milestone.id)).sort((a, b) => a.priority - b.priority).slice(0, limit);
+  }
+}
+export {
+  StageSignalCollector,
+  StageScorer,
+  LifecycleOrchestrator,
+  LifecycleMilestonePlanner
+};