@contractspec/lib.contracts 1.56.1 → 1.58.0

package/dist/docs/tech/lifecycle-stage-system.docblock.js

@@ -1,17 +1,376 @@
-import { registerDocBlocks } from "../registry.js";
-
-//#region src/docs/tech/lifecycle-stage-system.docblock.ts
-const tech_lifecycle_stage_system_DocBlocks = [{
-	id: "docs.tech.lifecycle-stage-system",
-	title: "ContractSpec Lifecycle Stage System – Technical Design",
-	summary: "This document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.",
-	kind: "reference",
-	visibility: "public",
-	route: "/docs/tech/lifecycle-stage-system",
-	tags: ["tech", "lifecycle-stage-system"],
-	body: "## ContractSpec Lifecycle Stage System – Technical Design\n\nThis document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.\n\n---\n\n### 1. Architecture Overview\n\n```\n┌──────────────────────┐\n│ @contractspec/lib.lifecycle  │  Types, enums, helpers (pure data)\n└───────────┬──────────┘\n            │\n┌───────────▼──────────┐    ┌───────────────────────────┐\n│ modules/lifecycle-   │    │ modules/lifecycle-advisor  │\n│ core (detection)     │    │ (guidance & ceremonies)    │\n└───────────┬──────────┘    └───────────┬───────────────┘\n            │                           │\n            ├────────────┬──────────────┤\n            ▼            ▼              ▼\n  Adapters: analytics, intent, questionnaires\n            │\n┌───────────▼──────────┐\n│ bundles/lifecycle-   │  Managed service for Studio\n│ managed              │  (REST handlers, AI agent)     │\n└───────────┬──────────┘\n            │\n  ContractSpec Studio surfaces\n  (web/mobile APIs, CLI, docs)\n```\n\n- **Libraries** provide shared vocabulary.\n- **Modules** encapsulate logic, accepting adapters to avoid environment-specific code.\n- **Bundles** compose modules, register agents/events, and expose APIs for Studio.\n- **Apps** (web-landing, future Studio views) consume bundle APIs; they do not reimplement logic. For web-landing we now resolve `@contractspec/bundle.studio` and `@contractspec/lib.database-studio` directly from their `packages/.../src` folders via `tsconfig` path aliases so Prisma stays on the server build and Turbopack no longer pulls the prebundled `dist` artifacts into client chunks.\n\n---\n\n### 2. Core Library (`@contractspec/lib.lifecycle`)\n\n- Stage enum (0–6) with metadata (`question`, `signals`, `traps`).\n- Axes types (`ProductPhase`, `CompanyPhase`, `CapitalPhase`).\n- `LifecycleSignal` (source, metric, value, timestamp).\n- `LifecycleMetricSnapshot` (aggregated numbers).\n- `LifecycleMilestone`, `LifecycleAction`, `LifecycleAssessment` interfaces.\n- Utility helpers:\n  - `formatStageSummary(stage, assessment)`\n  - `rankStageCandidates(scores)`\n\nThe library exports **no runtime dependencies** so it can be imported from apps, modules, and bundles alike.\n\n---\n\n### 3. Lifecycle Core Module\n\n**Location:** `packages/modules/lifecycle-core/`\n\n#### Components\n1. **StageSignalCollector**\n   - Accepts adapter interfaces:\n     - `AnalyticsAdapter` (pulls metrics from `@contractspec/lib.analytics` or fixture streams).\n     - `IntentAdapter` (hooks into `@contractspec/lib.observability` intent detectors or logs).\n     - `QuestionnaireAdapter` (loads JSON questionnaires and responses).\n   - Produces normalized `LifecycleSignal[]`.\n\n2. **StageScorer**\n   - Weighted scoring model:\n     - Base weight per stage (reflecting expected maturity).\n     - Feature weights (retention, revenue, team size, qualitative feedback).\n     - Confidence computed via variance of contributing signals.\n   - Supports pluggable scoring matrices via JSON config.\n   - Accepts sparse metric snapshots; the orchestrator sanitizes metrics to numeric-only records before persisting assessments so downstream analytics stay consistent.\n\n3. **LifecycleOrchestrator**\n   - Coordinates collectors + scorer.\n   - Returns `LifecycleAssessment` with:\n     - `stage`, `confidence`, `axisSnapshot`, `signalsUsed`.\n     - Recommended focus areas (high-level categories only).\n   - Emits events (internally) when stage confidence crosses thresholds (consumed later by bundle).\n\n4. **LifecycleMilestonePlanner**\n   - Loads `milestones-catalog.json` (no DB).\n   - Filters upcoming milestones per stage + axis.\n   - Tracks completion using provided IDs (caller persists).\n\n#### Data Files\n- `configs/stage-weights.json`\n- `configs/milestones-catalog.json`\n- `questionnaires/stage-readiness.json`\n\n#### Extension Hooks\n- All adapters exported as TypeScript interfaces.\n- Implementations for analytics/intent can live in bundles or apps without modifying module code.\n\n---\n\n### 4. Lifecycle Advisor Module\n\n**Location:** `packages/modules/lifecycle-advisor/`\n\n#### Components\n1. **LifecycleRecommendationEngine**\n   - Consumes `LifecycleAssessment`.\n   - Maps gaps to `LifecycleAction[]` using rule tables (`stage-playbooks.ts`).\n   - Supports override hooks for customer-specific rules.\n\n2. **ContractSpecLibraryRecommender**\n   - Maintains mapping from stage → recommended libraries/modules/bundles.\n   - Returns prioritized list with rationale and adoption prerequisites.\n\n3. **LifecycleCeremonyDesigner**\n   - Provides textual/structural data for ceremonies (title, copy, animation cues, soundtrack references).\n   - Ensures low-tech friendly instructions (clear copy, undo guidance).\n\n4. **AI Hooks**\n   - Defines prompt templates and tool manifests for lifecycle advisor agents (consumed by bundles).\n   - Keeps actual LLM integration outside module.\n\n---\n\n### 5. Managed Bundle (`lifecycle-managed`)\n\n**Responsibilities**\n- Wire modules together.\n- Provide HTTP/GraphQL handlers (exact transport optional).\n- Register LifecycleAdvisorAgent via `@contractspec/lib.ai-agent`.\n- LifecycleAdvisorAgent meta: domain `operations`, owners `team-lifecycle`, stability `experimental`, tags `guide/lifecycle/ops` so ops tooling can route incidents quickly.\n- Emit lifecycle events through `@contractspec/lib.bus` + `@contractspec/lib.analytics`.\n- Integrate with `contractspec-studio` packages:\n  - Use Studio contracts for authentication/tenant context (without accessing tenant DBs).\n  - Store assessments in Studio-managed storage abstractions (in-memory or file-based for now).\n\n**APIs**\n- `POST /lifecycle/assessments`: Accepts metrics + optional questionnaire answers. Returns `LifecycleAssessment`.\n- `GET /lifecycle/playbooks/:stage`: Returns stage playbook + ceremonies.\n- `POST /lifecycle/advise`: Invokes LifecycleAdvisorAgent with context.\n\n**Events**\n- `LifecycleAssessmentCreated`\n- `LifecycleStageChanged`\n- `LifecycleGuidanceConsumed`\n\n---\n\n### 6. Library Enhancements\n\n| Library | Enhancement |\n| --- | --- |\n| `@contractspec/lib.analytics` | Lifecycle metric collectors, helper to emit stage events, adapter implementation used by `StageSignalCollector`. |\n| `@contractspec/lib.evolution` | Accepts `LifecycleContext` when ranking spec anomalies/suggestions. |\n| `@contractspec/lib.growth` | Stage-specific experiment templates + guardrails referencing lifecycle enums. |\n| `@contractspec/lib.observability` | Lifecycle KPI pipeline definitions (drift detection, regression alerts). |\n\nEach enhancement must import stage types from `@contractspec/lib.lifecycle`.\n\n---\n\n### 7. Feature Flags & Progressive Delivery\n\n- Add new flags in progressive-delivery library:\n  - `LIFECYCLE_DETECTION_ALPHA`\n  - `LIFECYCLE_ADVISOR_ALPHA`\n  - `LIFECYCLE_MANAGED_SERVICE`\n- Bundles/modules should check flags before enabling workflows.\n- Flags referenced in docs + Studio UI to avoid accidental exposure.\n\n---\n\n### 8. Analytics & Telemetry\n\n- Events defined in analytics library; consumed by bundle/app:\n  - `lifecycle_assessment_run`\n  - `lifecycle_stage_changed`\n  - `lifecycle_guidance_consumed`\n- Observability pipeline includes:\n  - Composite lifecycle health metric (weighted sum of KPIs).\n  - Drift detection comparing stage predictions over time.\n  - Alert manager recipes for regression (e.g., PMF drop).\n\n---\n\n### 9. Testing Strategy\n\n1. **Unit**\n   - StageScorer weight matrix.\n   - RecommendationEngine mapping.\n   - Library recommender stage coverage.\n\n2. **Contract**\n   - Adapters: ensure mock adapters satisfy interfaces.\n   - Bundles: ensure HTTP handlers respect request/response contracts even without persistence.\n\n3. **Integration**\n   - CLI example runs detection + guidance end-to-end on fixture data.\n   - Dashboard example renders assessments, verifying JSON structures remain stable.\n\n---\n\n### 10. Implementation Checklist\n\n- [ ] Documentation (product, tech, ops, user).\n- [ ] Library creation (`@contractspec/lib.lifecycle`).\n- [ ] Modules (`lifecycle-core`, `lifecycle-advisor`).\n- [ ] Bundle (`lifecycle-managed`) + Studio wiring.\n- [ ] Library enhancements (analytics/evolution/growth/observability).\n- [ ] Examples (CLI + dashboard).\n- [ ] Feature flags + telemetry.\n- [ ] Automated tests + fixtures.\n\nKeep this document in sync as modules evolve. When adding new stages or axes, update `@contractspec/lib.lifecycle` first, then cascade to adapters, then refresh docs + Studio copy.*** End Patch*** End Patch\n\n\n"
-}];
-registerDocBlocks(tech_lifecycle_stage_system_DocBlocks);
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/docs/tech/lifecycle-stage-system.docblock.ts
+var tech_lifecycle_stage_system_DocBlocks = [
+  {
+    id: "docs.tech.lifecycle-stage-system",
+    title: "ContractSpec Lifecycle Stage System \u2013 Technical Design",
+    summary: "This document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/lifecycle-stage-system",
+    tags: ["tech", "lifecycle-stage-system"],
+    body: `## ContractSpec Lifecycle Stage System \u2013 Technical Design
+
+This document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.
+
+---
+
+### 1. Architecture Overview
+
+\`\`\`
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502 @contractspec/lib.lifecycle  \u2502  Types, enums, helpers (pure data)
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+            \u2502
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502 modules/lifecycle-   \u2502    \u2502 modules/lifecycle-advisor  \u2502
+\u2502 core (detection)     \u2502    \u2502 (guidance & ceremonies)    \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+            \u2502                           \u2502
+            \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+            \u25BC            \u25BC              \u25BC
+  Adapters: analytics, intent, questionnaires
+            \u2502
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502 bundles/lifecycle-   \u2502  Managed service for Studio
+\u2502 managed              \u2502  (REST handlers, AI agent)     \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+            \u2502
+  ContractSpec Studio surfaces
+  (web/mobile APIs, CLI, docs)
+\`\`\`
+
+- **Libraries** provide shared vocabulary.
+- **Modules** encapsulate logic, accepting adapters to avoid environment-specific code.
+- **Bundles** compose modules, register agents/events, and expose APIs for Studio.
+- **Apps** (web-landing, future Studio views) consume bundle APIs; they do not reimplement logic. For web-landing we now resolve \`@contractspec/bundle.studio\` and \`@contractspec/lib.database-studio\` directly from their \`packages/.../src\` folders via \`tsconfig\` path aliases so Prisma stays on the server build and Turbopack no longer pulls the prebundled \`dist\` artifacts into client chunks.
+
+---
+
+### 2. Core Library (\`@contractspec/lib.lifecycle\`)
+
+- Stage enum (0\u20136) with metadata (\`question\`, \`signals\`, \`traps\`).
+- Axes types (\`ProductPhase\`, \`CompanyPhase\`, \`CapitalPhase\`).
+- \`LifecycleSignal\` (source, metric, value, timestamp).
+- \`LifecycleMetricSnapshot\` (aggregated numbers).
+- \`LifecycleMilestone\`, \`LifecycleAction\`, \`LifecycleAssessment\` interfaces.
+- Utility helpers:
+  - \`formatStageSummary(stage, assessment)\`
+  - \`rankStageCandidates(scores)\`
+
+The library exports **no runtime dependencies** so it can be imported from apps, modules, and bundles alike.
+
+---
+
+### 3. Lifecycle Core Module
+
+**Location:** \`packages/modules/lifecycle-core/\`
+
+#### Components
+1. **StageSignalCollector**
+   - Accepts adapter interfaces:
+     - \`AnalyticsAdapter\` (pulls metrics from \`@contractspec/lib.analytics\` or fixture streams).
+     - \`IntentAdapter\` (hooks into \`@contractspec/lib.observability\` intent detectors or logs).
+     - \`QuestionnaireAdapter\` (loads JSON questionnaires and responses).
+   - Produces normalized \`LifecycleSignal[]\`.
+
+2. **StageScorer**
+   - Weighted scoring model:
+     - Base weight per stage (reflecting expected maturity).
+     - Feature weights (retention, revenue, team size, qualitative feedback).
+     - Confidence computed via variance of contributing signals.
+   - Supports pluggable scoring matrices via JSON config.
+   - Accepts sparse metric snapshots; the orchestrator sanitizes metrics to numeric-only records before persisting assessments so downstream analytics stay consistent.
+
+3. **LifecycleOrchestrator**
+   - Coordinates collectors + scorer.
+   - Returns \`LifecycleAssessment\` with:
+     - \`stage\`, \`confidence\`, \`axisSnapshot\`, \`signalsUsed\`.
+     - Recommended focus areas (high-level categories only).
+   - Emits events (internally) when stage confidence crosses thresholds (consumed later by bundle).
+
+4. **LifecycleMilestonePlanner**
+   - Loads \`milestones-catalog.json\` (no DB).
+   - Filters upcoming milestones per stage + axis.
+   - Tracks completion using provided IDs (caller persists).
+
+#### Data Files
+- \`configs/stage-weights.json\`
+- \`configs/milestones-catalog.json\`
+- \`questionnaires/stage-readiness.json\`
+
+#### Extension Hooks
+- All adapters exported as TypeScript interfaces.
+- Implementations for analytics/intent can live in bundles or apps without modifying module code.
+
+---
+
+### 4. Lifecycle Advisor Module
+
+**Location:** \`packages/modules/lifecycle-advisor/\`
+
+#### Components
+1. **LifecycleRecommendationEngine**
+   - Consumes \`LifecycleAssessment\`.
+   - Maps gaps to \`LifecycleAction[]\` using rule tables (\`stage-playbooks.ts\`).
+   - Supports override hooks for customer-specific rules.
+
+2. **ContractSpecLibraryRecommender**
+   - Maintains mapping from stage \u2192 recommended libraries/modules/bundles.
+   - Returns prioritized list with rationale and adoption prerequisites.
+
+3. **LifecycleCeremonyDesigner**
+   - Provides textual/structural data for ceremonies (title, copy, animation cues, soundtrack references).
+   - Ensures low-tech friendly instructions (clear copy, undo guidance).
 
-//#endregion
-export { tech_lifecycle_stage_system_DocBlocks };
+4. **AI Hooks**
+   - Defines prompt templates and tool manifests for lifecycle advisor agents (consumed by bundles).
+   - Keeps actual LLM integration outside module.
+
+---
+
+### 5. Managed Bundle (\`lifecycle-managed\`)
+
+**Responsibilities**
+- Wire modules together.
+- Provide HTTP/GraphQL handlers (exact transport optional).
+- Register LifecycleAdvisorAgent via \`@contractspec/lib.ai-agent\`.
+- LifecycleAdvisorAgent meta: domain \`operations\`, owners \`team-lifecycle\`, stability \`experimental\`, tags \`guide/lifecycle/ops\` so ops tooling can route incidents quickly.
+- Emit lifecycle events through \`@contractspec/lib.bus\` + \`@contractspec/lib.analytics\`.
+- Integrate with \`contractspec-studio\` packages:
+  - Use Studio contracts for authentication/tenant context (without accessing tenant DBs).
+  - Store assessments in Studio-managed storage abstractions (in-memory or file-based for now).
+
+**APIs**
+- \`POST /lifecycle/assessments\`: Accepts metrics + optional questionnaire answers. Returns \`LifecycleAssessment\`.
+- \`GET /lifecycle/playbooks/:stage\`: Returns stage playbook + ceremonies.
+- \`POST /lifecycle/advise\`: Invokes LifecycleAdvisorAgent with context.
+
+**Events**
+- \`LifecycleAssessmentCreated\`
+- \`LifecycleStageChanged\`
+- \`LifecycleGuidanceConsumed\`
+
+---
+
+### 6. Library Enhancements
+
+| Library | Enhancement |
+| --- | --- |
+| \`@contractspec/lib.analytics\` | Lifecycle metric collectors, helper to emit stage events, adapter implementation used by \`StageSignalCollector\`. |
+| \`@contractspec/lib.evolution\` | Accepts \`LifecycleContext\` when ranking spec anomalies/suggestions. |
+| \`@contractspec/lib.growth\` | Stage-specific experiment templates + guardrails referencing lifecycle enums. |
+| \`@contractspec/lib.observability\` | Lifecycle KPI pipeline definitions (drift detection, regression alerts). |
+
+Each enhancement must import stage types from \`@contractspec/lib.lifecycle\`.
+
+---
+
+### 7. Feature Flags & Progressive Delivery
+
+- Add new flags in progressive-delivery library:
+  - \`LIFECYCLE_DETECTION_ALPHA\`
+  - \`LIFECYCLE_ADVISOR_ALPHA\`
+  - \`LIFECYCLE_MANAGED_SERVICE\`
+- Bundles/modules should check flags before enabling workflows.
+- Flags referenced in docs + Studio UI to avoid accidental exposure.
+
+---
+
+### 8. Analytics & Telemetry
+
+- Events defined in analytics library; consumed by bundle/app:
+  - \`lifecycle_assessment_run\`
+  - \`lifecycle_stage_changed\`
+  - \`lifecycle_guidance_consumed\`
+- Observability pipeline includes:
+  - Composite lifecycle health metric (weighted sum of KPIs).
+  - Drift detection comparing stage predictions over time.
+  - Alert manager recipes for regression (e.g., PMF drop).
+
+---
+
+### 9. Testing Strategy
+
+1. **Unit**
+   - StageScorer weight matrix.
+   - RecommendationEngine mapping.
+   - Library recommender stage coverage.
+
+2. **Contract**
+   - Adapters: ensure mock adapters satisfy interfaces.
+   - Bundles: ensure HTTP handlers respect request/response contracts even without persistence.
+
+3. **Integration**
+   - CLI example runs detection + guidance end-to-end on fixture data.
+   - Dashboard example renders assessments, verifying JSON structures remain stable.
+
+---
+
+### 10. Implementation Checklist
+
+- [ ] Documentation (product, tech, ops, user).
+- [ ] Library creation (\`@contractspec/lib.lifecycle\`).
+- [ ] Modules (\`lifecycle-core\`, \`lifecycle-advisor\`).
+- [ ] Bundle (\`lifecycle-managed\`) + Studio wiring.
+- [ ] Library enhancements (analytics/evolution/growth/observability).
+- [ ] Examples (CLI + dashboard).
+- [ ] Feature flags + telemetry.
+- [ ] Automated tests + fixtures.
+
+Keep this document in sync as modules evolve. When adding new stages or axes, update \`@contractspec/lib.lifecycle\` first, then cascade to adapters, then refresh docs + Studio copy.*** End Patch*** End Patch
+
+
+`
+  }
+];
+registerDocBlocks(tech_lifecycle_stage_system_DocBlocks);
+export {
+  tech_lifecycle_stage_system_DocBlocks
+};

package/dist/docs/tech/llm/llm-integration.docblock.d.ts

@@ -1,7 +1,8 @@
-import { DocBlock } from "@contractspec/lib.contracts/docs";
-
-//#region src/docs/tech/llm/llm-integration.docblock.d.ts
-
-declare const tech_llm_integration_DocBlocks: DocBlock[];
-//#endregion
-export { tech_llm_integration_DocBlocks };
+/**
+ * DocBlock: LLM Integration
+ *
+ * Documentation for ContractSpec's LLM integration features.
+ */
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+export declare const tech_llm_integration_DocBlocks: DocBlock[];
+//# sourceMappingURL=llm-integration.docblock.d.ts.map

package/dist/docs/tech/llm/llm-integration.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-integration.docblock.d.ts","sourceRoot":"","sources":["../../../../src/docs/tech/llm/llm-integration.docblock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAGjE,eAAO,MAAM,8BAA8B,EAAE,QAAQ,EA2UpD,CAAC"}