@contractspec/lib.contracts 1.44.0 → 1.44.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/dist/app-config/contracts.d.ts +50 -50
  2. package/dist/app-config/events.d.ts +27 -27
  3. package/dist/app-config/lifecycle-contracts.d.ts +54 -54
  4. package/dist/docs/tech/lifecycle-stage-system.docblock.js +1 -1
  5. package/dist/integrations/docs/integrations.docblock.js +1 -1
  6. package/dist/integrations/openbanking/contracts/accounts.d.ts +66 -66
  7. package/dist/integrations/openbanking/contracts/balances.d.ts +34 -34
  8. package/dist/integrations/openbanking/contracts/transactions.d.ts +48 -48
  9. package/dist/integrations/openbanking/models.d.ts +55 -55
  10. package/dist/integrations/operations.d.ts +102 -102
  11. package/dist/knowledge/operations.d.ts +66 -66
  12. package/dist/onboarding-base.d.ts +29 -29
  13. package/package.json +14 -5
package/dist/app-config/lifecycle-contracts.d.ts CHANGED
@@ -3,50 +3,50 @@ import { OperationSpec } from "../operations/operation.js";
3
3
  import { OperationSpecRegistry } from "../operations/registry.js";
4
4
  import "../operations/index.js";
5
5
  import "../index.js";
6
- import * as _contractspec_lib_schema156 from "@contractspec/lib.schema";
6
+ import * as _contractspec_lib_schema467 from "@contractspec/lib.schema";
7
7
  import { SchemaModel } from "@contractspec/lib.schema";
8
8
 
9
9
  //#region src/app-config/lifecycle-contracts.d.ts
10
10
  declare const CreateTenantConfigDraftCommand: OperationSpec<SchemaModel<{
11
11
  tenantId: {
12
- type: _contractspec_lib_schema156.FieldType<string, string>;
12
+ type: _contractspec_lib_schema467.FieldType<string, string>;
13
13
  isOptional: false;
14
14
  };
15
15
  appId: {
16
- type: _contractspec_lib_schema156.FieldType<string, string>;
16
+ type: _contractspec_lib_schema467.FieldType<string, string>;
17
17
  isOptional: false;
18
18
  };
19
19
  blueprintName: {
20
- type: _contractspec_lib_schema156.FieldType<string, string>;
20
+ type: _contractspec_lib_schema467.FieldType<string, string>;
21
21
  isOptional: false;
22
22
  };
23
23
  blueprintVersion: {
24
- type: _contractspec_lib_schema156.FieldType<number, number>;
24
+ type: _contractspec_lib_schema467.FieldType<number, number>;
25
25
  isOptional: false;
26
26
  };
27
27
  environment: {
28
- type: _contractspec_lib_schema156.FieldType<string, string>;
28
+ type: _contractspec_lib_schema467.FieldType<string, string>;
29
29
  isOptional: true;
30
30
  };
31
31
  fromVersion: {
32
- type: _contractspec_lib_schema156.FieldType<number, number>;
32
+ type: _contractspec_lib_schema467.FieldType<number, number>;
33
33
  isOptional: true;
34
34
  };
35
35
  createdBy: {
36
- type: _contractspec_lib_schema156.FieldType<string, string>;
36
+ type: _contractspec_lib_schema467.FieldType<string, string>;
37
37
  isOptional: false;
38
38
  };
39
39
  }>, SchemaModel<{
40
40
  version: {
41
- type: _contractspec_lib_schema156.FieldType<number, number>;
41
+ type: _contractspec_lib_schema467.FieldType<number, number>;
42
42
  isOptional: false;
43
43
  };
44
44
  status: {
45
- type: _contractspec_lib_schema156.FieldType<string, string>;
45
+ type: _contractspec_lib_schema467.FieldType<string, string>;
46
46
  isOptional: false;
47
47
  };
48
48
  createdAt: {
49
- type: _contractspec_lib_schema156.FieldType<Date, string>;
49
+ type: _contractspec_lib_schema467.FieldType<Date, string>;
50
50
  isOptional: false;
51
51
  };
52
52
  }>, {
@@ -55,32 +55,32 @@ declare const CreateTenantConfigDraftCommand: OperationSpec<SchemaModel<{
55
55
  }[]>;
56
56
  declare const PromoteTenantConfigToPreviewCommand: OperationSpec<SchemaModel<{
57
57
  tenantId: {
58
- type: _contractspec_lib_schema156.FieldType<string, string>;
58
+ type: _contractspec_lib_schema467.FieldType<string, string>;
59
59
  isOptional: false;
60
60
  };
61
61
  appId: {
62
- type: _contractspec_lib_schema156.FieldType<string, string>;
62
+ type: _contractspec_lib_schema467.FieldType<string, string>;
63
63
  isOptional: false;
64
64
  };
65
65
  version: {
66
- type: _contractspec_lib_schema156.FieldType<number, number>;
66
+ type: _contractspec_lib_schema467.FieldType<number, number>;
67
67
  isOptional: false;
68
68
  };
69
69
  promotedBy: {
70
- type: _contractspec_lib_schema156.FieldType<string, string>;
70
+ type: _contractspec_lib_schema467.FieldType<string, string>;
71
71
  isOptional: false;
72
72
  };
73
73
  }>, SchemaModel<{
74
74
  version: {
75
- type: _contractspec_lib_schema156.FieldType<number, number>;
75
+ type: _contractspec_lib_schema467.FieldType<number, number>;
76
76
  isOptional: false;
77
77
  };
78
78
  status: {
79
- type: _contractspec_lib_schema156.FieldType<string, string>;
79
+ type: _contractspec_lib_schema467.FieldType<string, string>;
80
80
  isOptional: false;
81
81
  };
82
82
  warnings: {
83
- type: _contractspec_lib_schema156.FieldType<string, string>;
83
+ type: _contractspec_lib_schema467.FieldType<string, string>;
84
84
  isOptional: true;
85
85
  isArray: true;
86
86
  };
@@ -90,44 +90,44 @@ declare const PromoteTenantConfigToPreviewCommand: OperationSpec<SchemaModel<{
90
90
  }[]>;
91
91
  declare const PublishTenantConfigCommand: OperationSpec<SchemaModel<{
92
92
  tenantId: {
93
- type: _contractspec_lib_schema156.FieldType<string, string>;
93
+ type: _contractspec_lib_schema467.FieldType<string, string>;
94
94
  isOptional: false;
95
95
  };
96
96
  appId: {
97
- type: _contractspec_lib_schema156.FieldType<string, string>;
97
+ type: _contractspec_lib_schema467.FieldType<string, string>;
98
98
  isOptional: false;
99
99
  };
100
100
  version: {
101
- type: _contractspec_lib_schema156.FieldType<number, number>;
101
+ type: _contractspec_lib_schema467.FieldType<number, number>;
102
102
  isOptional: false;
103
103
  };
104
104
  environment: {
105
- type: _contractspec_lib_schema156.FieldType<string, string>;
105
+ type: _contractspec_lib_schema467.FieldType<string, string>;
106
106
  isOptional: true;
107
107
  };
108
108
  publishedBy: {
109
- type: _contractspec_lib_schema156.FieldType<string, string>;
109
+ type: _contractspec_lib_schema467.FieldType<string, string>;
110
110
  isOptional: false;
111
111
  };
112
112
  changeSummary: {
113
- type: _contractspec_lib_schema156.FieldType<string, string>;
113
+ type: _contractspec_lib_schema467.FieldType<string, string>;
114
114
  isOptional: true;
115
115
  };
116
116
  }>, SchemaModel<{
117
117
  version: {
118
- type: _contractspec_lib_schema156.FieldType<number, number>;
118
+ type: _contractspec_lib_schema467.FieldType<number, number>;
119
119
  isOptional: false;
120
120
  };
121
121
  status: {
122
- type: _contractspec_lib_schema156.FieldType<string, string>;
122
+ type: _contractspec_lib_schema467.FieldType<string, string>;
123
123
  isOptional: false;
124
124
  };
125
125
  previousVersion: {
126
- type: _contractspec_lib_schema156.FieldType<number, number>;
126
+ type: _contractspec_lib_schema467.FieldType<number, number>;
127
127
  isOptional: true;
128
128
  };
129
129
  publishedAt: {
130
- type: _contractspec_lib_schema156.FieldType<Date, string>;
130
+ type: _contractspec_lib_schema467.FieldType<Date, string>;
131
131
  isOptional: false;
132
132
  };
133
133
  }>, {
@@ -136,40 +136,40 @@ declare const PublishTenantConfigCommand: OperationSpec<SchemaModel<{
136
136
  }[]>;
137
137
  declare const RollbackTenantConfigCommand: OperationSpec<SchemaModel<{
138
138
  tenantId: {
139
- type: _contractspec_lib_schema156.FieldType<string, string>;
139
+ type: _contractspec_lib_schema467.FieldType<string, string>;
140
140
  isOptional: false;
141
141
  };
142
142
  appId: {
143
- type: _contractspec_lib_schema156.FieldType<string, string>;
143
+ type: _contractspec_lib_schema467.FieldType<string, string>;
144
144
  isOptional: false;
145
145
  };
146
146
  toVersion: {
147
- type: _contractspec_lib_schema156.FieldType<number, number>;
147
+ type: _contractspec_lib_schema467.FieldType<number, number>;
148
148
  isOptional: false;
149
149
  };
150
150
  environment: {
151
- type: _contractspec_lib_schema156.FieldType<string, string>;
151
+ type: _contractspec_lib_schema467.FieldType<string, string>;
152
152
  isOptional: true;
153
153
  };
154
154
  rolledBackBy: {
155
- type: _contractspec_lib_schema156.FieldType<string, string>;
155
+ type: _contractspec_lib_schema467.FieldType<string, string>;
156
156
  isOptional: false;
157
157
  };
158
158
  reason: {
159
- type: _contractspec_lib_schema156.FieldType<string, string>;
159
+ type: _contractspec_lib_schema467.FieldType<string, string>;
160
160
  isOptional: false;
161
161
  };
162
162
  }>, SchemaModel<{
163
163
  newVersion: {
164
- type: _contractspec_lib_schema156.FieldType<number, number>;
164
+ type: _contractspec_lib_schema467.FieldType<number, number>;
165
165
  isOptional: false;
166
166
  };
167
167
  status: {
168
- type: _contractspec_lib_schema156.FieldType<string, string>;
168
+ type: _contractspec_lib_schema467.FieldType<string, string>;
169
169
  isOptional: false;
170
170
  };
171
171
  rolledBackFrom: {
172
- type: _contractspec_lib_schema156.FieldType<number, number>;
172
+ type: _contractspec_lib_schema467.FieldType<number, number>;
173
173
  isOptional: false;
174
174
  };
175
175
  }>, {
@@ -178,22 +178,22 @@ declare const RollbackTenantConfigCommand: OperationSpec<SchemaModel<{
178
178
  }[]>;
179
179
  declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
180
180
  tenantId: {
181
- type: _contractspec_lib_schema156.FieldType<string, string>;
181
+ type: _contractspec_lib_schema467.FieldType<string, string>;
182
182
  isOptional: false;
183
183
  };
184
184
  appId: {
185
- type: _contractspec_lib_schema156.FieldType<string, string>;
185
+ type: _contractspec_lib_schema467.FieldType<string, string>;
186
186
  isOptional: false;
187
187
  };
188
188
  }>, SchemaModel<{
189
189
  versions: {
190
190
  type: SchemaModel<{
191
191
  meta: {
192
- type: _contractspec_lib_schema156.FieldType<Record<string, unknown>, Record<string, unknown>>;
192
+ type: _contractspec_lib_schema467.FieldType<Record<string, unknown>, Record<string, unknown>>;
193
193
  isOptional: false;
194
194
  };
195
195
  config: {
196
- type: _contractspec_lib_schema156.FieldType<Record<string, unknown>, Record<string, unknown>>;
196
+ type: _contractspec_lib_schema467.FieldType<Record<string, unknown>, Record<string, unknown>>;
197
197
  isOptional: false;
198
198
  };
199
199
  }>;
@@ -203,35 +203,35 @@ declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
203
203
  transitions: {
204
204
  type: SchemaModel<{
205
205
  tenantId: {
206
- type: _contractspec_lib_schema156.FieldType<string, string>;
206
+ type: _contractspec_lib_schema467.FieldType<string, string>;
207
207
  isOptional: false;
208
208
  };
209
209
  appId: {
210
- type: _contractspec_lib_schema156.FieldType<string, string>;
210
+ type: _contractspec_lib_schema467.FieldType<string, string>;
211
211
  isOptional: false;
212
212
  };
213
213
  fromStatus: {
214
- type: _contractspec_lib_schema156.FieldType<string, string>;
214
+ type: _contractspec_lib_schema467.FieldType<string, string>;
215
215
  isOptional: false;
216
216
  };
217
217
  toStatus: {
218
- type: _contractspec_lib_schema156.FieldType<string, string>;
218
+ type: _contractspec_lib_schema467.FieldType<string, string>;
219
219
  isOptional: false;
220
220
  };
221
221
  version: {
222
- type: _contractspec_lib_schema156.FieldType<number, number>;
222
+ type: _contractspec_lib_schema467.FieldType<number, number>;
223
223
  isOptional: false;
224
224
  };
225
225
  timestamp: {
226
- type: _contractspec_lib_schema156.FieldType<Date, string>;
226
+ type: _contractspec_lib_schema467.FieldType<Date, string>;
227
227
  isOptional: false;
228
228
  };
229
229
  actor: {
230
- type: _contractspec_lib_schema156.FieldType<string, string>;
230
+ type: _contractspec_lib_schema467.FieldType<string, string>;
231
231
  isOptional: false;
232
232
  };
233
233
  reason: {
234
- type: _contractspec_lib_schema156.FieldType<string, string>;
234
+ type: _contractspec_lib_schema467.FieldType<string, string>;
235
235
  isOptional: true;
236
236
  };
237
237
  }>;
@@ -241,26 +241,26 @@ declare const ListTenantConfigVersionsQuery: OperationSpec<SchemaModel<{
241
241
  }>, undefined>;
242
242
  declare const GetTenantConfigVersionQuery: OperationSpec<SchemaModel<{
243
243
  tenantId: {
244
- type: _contractspec_lib_schema156.FieldType<string, string>;
244
+ type: _contractspec_lib_schema467.FieldType<string, string>;
245
245
  isOptional: false;
246
246
  };
247
247
  appId: {
248
- type: _contractspec_lib_schema156.FieldType<string, string>;
248
+ type: _contractspec_lib_schema467.FieldType<string, string>;
249
249
  isOptional: false;
250
250
  };
251
251
  version: {
252
- type: _contractspec_lib_schema156.FieldType<number, number>;
252
+ type: _contractspec_lib_schema467.FieldType<number, number>;
253
253
  isOptional: false;
254
254
  };
255
255
  }>, SchemaModel<{
256
256
  version: {
257
257
  type: SchemaModel<{
258
258
  meta: {
259
- type: _contractspec_lib_schema156.FieldType<Record<string, unknown>, Record<string, unknown>>;
259
+ type: _contractspec_lib_schema467.FieldType<Record<string, unknown>, Record<string, unknown>>;
260
260
  isOptional: false;
261
261
  };
262
262
  config: {
263
- type: _contractspec_lib_schema156.FieldType<Record<string, unknown>, Record<string, unknown>>;
263
+ type: _contractspec_lib_schema467.FieldType<Record<string, unknown>, Record<string, unknown>>;
264
264
  isOptional: false;
265
265
  };
266
266
  }>;
package/dist/docs/tech/lifecycle-stage-system.docblock.js CHANGED
@@ -9,7 +9,7 @@ const tech_lifecycle_stage_system_DocBlocks = [{
9
9
  visibility: "public",
10
10
  route: "/docs/tech/lifecycle-stage-system",
11
11
  tags: ["tech", "lifecycle-stage-system"],
12
- 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-contractspec-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"
12
+ 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"
13
13
  }];
14
14
  registerDocBlocks(tech_lifecycle_stage_system_DocBlocks);
15
15
 
package/dist/integrations/docs/integrations.docblock.js CHANGED
@@ -85,7 +85,7 @@ The manager attempts providers in priority order (environment first, then cloud
85
85
 
86
86
  ## Studio persistence (ContractSpec Studio)
87
87
 
88
- ContractSpec Studio persists tenant \`IntegrationConnection\` records in Postgres (Prisma model \`IntegrationConnection\` in \`@contractspec/lib.database-contractspec-studio\`) and exposes a platform-admin management surface (see the Studio platform admin panel).
88
+ ContractSpec Studio persists tenant \`IntegrationConnection\` records in Postgres (Prisma model \`IntegrationConnection\` in \`@contractspec/lib.database-studio\`) and exposes a platform-admin management surface (see the Studio platform admin panel).
89
89
  `
90
90
  }];
91
91
  registerDocBlocks(tech_contracts_integrations_DocBlocks);