5.5.0

Apr 21, 2026 · 37 packages · 34 unique changes · 8 release entries

appsbundlesintegrationslibsmodules

Release summaries

adoption-engine-and-authoring-targets
Add a family-aware ContractSpec Adoption Engine, expand contract authoring targets across CLI and VS Code tooling, and refresh release-facing schema and policy artifacts for downstream workspaces.
maintainer
Maintainers get a shared adoption catalog and resolver, Connect adoption hooks, MCP exposure for reuse decisions, expanded authoring-target coverage, and updated static policy artifacts.
integrator
Integrators can resolve existing workspace or ContractSpec OSS surfaces before adding new implementations, and can scaffold more contract families from the CLI and VS Code extension.
customer
Customer workspaces gain setup-managed adoption guidance, Connect `adoption sync/resolve` flows, stronger runtime-import and deprecated-monolith guardrails, and updated bundled schemas in the published CLI entrypoint.
builder-v3-control-plane-rollout
Introduce the Builder v3 control plane as a governed authoring layer over external execution providers.
maintainer
Builder v3 now has a governed contract, runtime, and provider surface that keeps authoring, readiness, and export orchestration aligned across the package stack.
integrator
Integrators can compose managed, local, and hybrid runtime modes with Builder workbench/mobile-review modules and provider adapters for Codex, Claude Code, Gemini, Copilot, STT, and local models.
customer
Builder operators now get a unified workbench and mobile-review experience across provider routing, readiness, export approval, and omnichannel control flows.
connect-spec-alignment-april-2026
Implement ContractSpec Connect as a first-class spec, runtime, and CLI workflow.
maintainer
Connect is now a governed repo surface with CLI commands, workspace services, and versioned docs that keep risky edits, review packets, and replay artifacts aligned.
integrator
Integrators can enable `.contractsrc.json > connect`, emit local context/plan/verdict artifacts, and route adapter-facing review or replay flows through the shared workspace services.
agent
Coding-agent surfaces now have a first-class Connect workflow for context packs, plan packets, mutation verdicts, review packets, and replay/eval evidence instead of relying on ad hoc governance prose.
contract-dx-first-slice
Improve app-config, theme, and feature authoring with explicit validation APIs, first-class theme discovery and scaffolding, and key-based app-config generation across contracts, workspace tooling, and the CLI.
maintainer
Maintainers can rely on authored validators for app-config, theme, and feature specs instead of shallow per-surface checks, and can scaffold theme specs directly from the CLI.
integrator
Integrators get a stable `defineTheme` authoring path, new theme and feature validation helpers, and key-based app-config DTOs and templates across shared tooling.
customer
CLI users can now run `contractspec create theme`, and validation catches more app-config, theme, and feature mistakes before publish or CI promotion.
forms-layout-input-groups
Add FormSpec layout hints, semantic field rendering, and portable text/textarea input-group addons.
maintainer
Maintainers can express richer FormSpec layout and field chrome without embedding renderer-specific UI.
integrator
Integrators can render contract forms with semantic legends, descriptions, errors, grid rows, colspans, and input addons through driver slots.
customer
Contract-driven forms can now present dense multi-column layouts and input adornments while preserving accessible field semantics.
theme-tailwind-bridge
Add ThemeSpec light/dark modes and a design-system Tailwind bridge for CSS variables, presets, CSS text, and OKLCH color pass-through.
maintainer
Maintainers can keep ThemeSpec as the source of truth while exposing Tailwind variables and runtime theme modes from the design-system package.
integrator
Integrators can resolve ThemeSpec tokens for light or dark mode, consume a Tailwind preset, or serialize CSS text without adding a required generation step.
customer
Product surfaces can use ThemeSpec-backed light/dark themes with OKLCH colors while keeping existing Tailwind semantic classes such as `bg-primary` and `text-foreground`.
typed-result-system
Add a canonical typed result system for ContractSpec success and failure propagation across operations, workflows, jobs, server adapters, MCP, GraphQL, and React clients.
maintainer
Maintainers can declare operation, workflow, and job result catalogs and have runtime registries enforce custom success and failure outcomes.
integrator
Integrators get consistent result mapping for REST, NextResponse, Nest-compatible filters/interceptors, GraphQL extensions, MCP tool errors, and React client parsing.
customer
Product surfaces can rely on consistent success metadata, retry hints, field issues, and Problem Details-style errors across API, job, workflow, and frontend boundaries.
versioning-release-system
Add versioning-backed release capsules, generated patch notes, and guided upgrade flows.
maintainer
Release communication is now generated from versioning-backed release capsules and enforced on release branches.
integrator
Guided upgrade plans and agent prompts now come from generated upgrade manifests instead of ad hoc prose.
customer
Web changelog consumers can prefer generated release manifests while older package changelogs remain supported as fallback.

Deprecations

- `FieldSpec.wrapper.orientation` remains supported but should be replaced by `FieldSpec.layout.orientation` in new specs.
- Prefer `ContractSpecError`, `createContractError`, and `contractFail` from `@contractspec/lib.contracts-spec/results`; `@contractspec/lib.error` remains as a compatibility bridge for existing `AppError` users.
- The standalone release domain under `@contractspec/lib.contracts-spec/release` is deprecated in favor of versioning-owned release metadata.

Migration guide

Enable the new Connect adoption engine in workspace config
ContractSpec workspaces can now opt into family-aware reuse guidance and local catalog sync through `connect.adoption`.
When: When a workspace uses `contractspec init --preset connect`, Connect hooks, or custom `.contractsrc.json` management.
1. Add or review `.contractsrc.json > connect.adoption`.
2. Run `contractspec connect adoption sync --json` to mirror the local catalog.
3. Route uncertain reuse decisions through `contractspec connect adoption resolve --family <family> --stdin`.
Use the expanded authoring-target surface in CLI and VS Code flows
Shared workspace discovery and IDE/CLI create flows now recognize additional contract families beyond the original core set.
When: When using `contractspec create`, VS Code create commands, or custom authoring-target integrations.
1. Use the new create targets for capability, policy, translation, visualization, job, agent, product-intent, harness scenario, and harness suite scaffolds where appropriate.
2. Update any custom file-name or directory assumptions to rely on shared authoring-target helpers instead of hard-coded extensions.
Enable ContractSpec Connect in the workspace config
Turn on the Connect adapter flow before relying on task-scoped context, review, replay, or evaluation artifacts.
When: When a workspace wants coding-agent gating, local review packets, or replay/eval evidence tied to file and command mutations.
1. Add or merge a `connect` section in `.contractsrc.json` with `enabled: true` and the storage paths that should hold Connect artifacts.
2. Route risky edits or shell execution through `contractspec connect plan` and `contractspec connect verify` so decisions, review packets, and replay bundles are captured.
3. Use the generated docs and exported agentpacks metadata so downstream agent tooling sees the same Connect contract surface as the CLI.
Update custom app-config DTO callers to key-based refs
Shared app-config authoring DTOs and templates now use `key`-based spec references instead of older `name`-based helper fields.
When: When custom tooling imports `AppBlueprintSpecData`, `AppConfigMappingData`, or related route reference DTOs from workspace or bundle packages.
1. Replace `name` fields with `key` for app-config spec references.
2. Replace `guardName` and `experimentName` with `guardKey` and `experimentKey` in route DTOs.
3. Keep versions as semver strings rather than numeric literals.
Adopt `defineTheme(...)` for new theme specs
Theme authoring now has a canonical helper and authored-validator support.
When: When creating or refreshing theme specs used by generators, docs, or CI validation.
1. Import `defineTheme` from `@contractspec/lib.contracts-spec/themes`.
2. Prefer `defineTheme({...})` for new theme specs, while keeping existing `ThemeSpec` object literals valid.
3. Add `validateThemeSpec` or `assertThemeSpecValid` to CI or publish-time checks where theme correctness matters.
Keep existing forms as-is
Existing forms continue to render without changes.
1. No migration is required for forms that do not use the new layout or addon fields.
Use FormSpec layout hints for dense forms
New multi-column forms should use `FormSpec.layout`, `group.layout`, and `field.layout.colSpan`.
1. Add `layout.columns` at form or group level.
2. Use `field.layout.colSpan` for fields that should expand across columns.
Use input-group addons for text fields
New input addons should use `inputGroup.addons` on text and textarea fields.
1. Add `inputGroup.addons` to text or textarea field specs.
2. Resolve icon keys in the host driver through the `InputGroupIcon` slot.
Prefer contracts-spec result primitives for new error handling
Replace new uses of `AppError` with `ContractSpecError` or `contractFail`; existing `AppError` consumers can convert to a compatible problem shape with `appErrorToProblem`.
1. Import new result helpers from `@contractspec/lib.contracts-spec/results`.
2. Keep existing `AppError` consumers until they are touched for feature work.
3. Use `appErrorToProblem` when a compatibility conversion is needed.
Add .release.yaml companions for changesets
Published release changesets now require a structured release capsule.
When: When preparing release branches, publish workflows, or release communication bundles.
1. Create `.changeset/<slug>.release.yaml` next to each published changeset.
2. Record customer impact, migration notes, validation commands, and evidence in the release capsule.
3. Run `contractspec release build` before `contractspec release check --strict`.

Upgrade steps

Wire adoption-aware Connect hooks in consumer environments
assisted
The consumer plugin and Connect CLI now expose adoption-aware hook events in addition to contracts-spec review hooks.
Packages: @contractspec/lib.contracts-spec, @contractspec/module.workspace, @contractspec/bundle.workspace, @contractspec/bundle.library, @contractspec/app.cli-contractspec, vscode-contractspec, contractspec, @contractspec/lib.knowledge, @contractspec/biome-config, @contractspec/app.cursor-marketplace
1. Install or reference the `contractspec-adoption` marketplace/plugin assets where Connect hooks are consumed.
2. Use `contractspec connect hook adoption before-file-edit|before-shell-execution|after-file-edit --stdin` in host hook wiring.
Prefer higher-level runtime package entrypoints in imports
manual
Generated Biome policy artifacts now flag deprecated monolith usage and obvious deep runtime entrypoint imports.
Packages: @contractspec/lib.contracts-spec, @contractspec/module.workspace, @contractspec/bundle.workspace, @contractspec/bundle.library, @contractspec/app.cli-contractspec, vscode-contractspec, contractspec, @contractspec/lib.knowledge, @contractspec/biome-config, @contractspec/app.cursor-marketplace
1. Replace `@contractspec/lib.contracts` imports with `@contractspec/lib.contracts-spec` plus the appropriate split runtime package.
2. Prefer package-level runtime entrypoints such as `@contractspec/lib.contracts-runtime-server-mcp` when they already expose the required surface.
Adopt the Builder v3 control-plane packages
assisted
Wire provider/runtime integrations through the governed Builder v3 workbench and mobile-review surfaces.
Packages: @contractspec/lib.contracts-spec, @contractspec/lib.builder-spec, @contractspec/lib.provider-spec, @contractspec/lib.builder-runtime, @contractspec/lib.mobile-control, @contractspec/lib.provider-runtime, @contractspec/module.builder-workbench, @contractspec/module.mobile-review, @contractspec/integration.runtime, @contractspec/integration.runtime.managed, @contractspec/integration.runtime.local, @contractspec/integration.runtime.hybrid, @contractspec/integration.builder-telegram, @contractspec/integration.builder-voice, @contractspec/integration.builder-whatsapp, @contractspec/integration.provider.codex, @contractspec/integration.provider.claude-code, @contractspec/integration.provider.gemini, @contractspec/integration.provider.copilot, @contractspec/integration.provider.stt, @contractspec/integration.provider.local-model
1. Install the Builder v3 contracts and runtime packages alongside the provider integrations you intend to expose in the authoring surface.
2. Use the Builder workbench and mobile-review modules as the host UI surfaces instead of building separate readiness or export orchestration shells.
3. Validate managed, local, and hybrid runtime mode selection plus provider routing before promoting the control-plane workflow to operators.
Adopt the Connect CLI workflow
manual
Use the built-in Connect commands instead of custom local wrappers for risky file or command mutations.
Packages: @contractspec/lib.contracts-spec, @contractspec/bundle.workspace, @contractspec/app.cli-contractspec, @contractspec/bundle.library, agentpacks
1. Initialize the workspace with `contractspec connect init --scope workspace`.
2. Use `contractspec connect context`, `plan`, and `verify` to capture task context and mutation verdicts before edits or shell execution.
3. Keep replay and evaluation artifacts under `.contractspec/connect/` so review and audit flows can consume the same evidence bundle.
Use the authored validators for contract setup and CI
assisted
Prefer the package-level validators over shallow AST checks for the three upgraded surfaces.
Packages: @contractspec/lib.contracts-spec, @contractspec/module.workspace, @contractspec/bundle.workspace, @contractspec/app.cli-contractspec
1. Use `validateBlueprint` or `assertBlueprintValid` for app-config specs.
2. Use `validateThemeSpec` or `assertThemeSpecValid` for theme specs.
3. Use `validateFeatureSpec` or `assertFeatureSpecValid` for feature specs before registry installation or release review.
Adopt the new theme authoring target across workspace tools
manual
Shared workspace discovery and the CLI now treat `theme` as a first-class authored surface.
Packages: @contractspec/lib.contracts-spec, @contractspec/module.workspace, @contractspec/bundle.workspace, @contractspec/app.cli-contractspec
1. Use `.theme.ts` files and `defineTheme(...)` for new theme specs.
2. Update any custom create flows or discovery logic to include the `theme` authoring target where needed.
Use FormSpec layout hints for dense forms
manual
Replace renderer-specific row wrappers with portable column and colspan metadata.
Packages: @contractspec/lib.contracts-spec, @contractspec/lib.contracts-runtime-client-react, @contractspec/lib.design-system, @contractspec/lib.ui-kit-web, @contractspec/lib.ui-kit
1. Add `layout.columns` at form or group level.
2. Use `field.layout.colSpan` for fields that should expand across columns.
3. Use `group.legendI18n` when a section needs a semantic legend.
Use serializable input-group addons
manual
Add text or icon addon descriptors to text and textarea fields.
Packages: @contractspec/lib.contracts-spec, @contractspec/lib.contracts-runtime-client-react, @contractspec/lib.design-system, @contractspec/lib.ui-kit-web, @contractspec/lib.ui-kit
1. Add `inputGroup.addons` to text or textarea field specs.
2. Resolve icon keys in the host driver through the `InputGroupIcon` slot.
Use ThemeSpec as the Tailwind theme source
assisted
Resolve ThemeSpec tokens for the active mode and feed them to the Tailwind preset or CSS serializer.
Packages: @contractspec/lib.contracts-spec, @contractspec/lib.design-system
1. Keep existing `tokens` as the default/light-compatible token bag.
2. Add `modes.dark.tokens` when a dark-mode overlay is needed.
3. Use `themeSpecToTailwindPreset` for config-based Tailwind usage or `themeSpecToTailwindCss` when an app wants an importable CSS artifact.
Declare operation-specific success and failure outcomes
assisted
Use `defineResultCatalog`, `standardSuccess`, `standardErrors`, `success`, and `failure` from `@contractspec/lib.contracts-spec/results` when an operation, workflow, or job needs custom codes.
Packages: @contractspec/lib.contracts-spec, @contractspec/lib.contracts-runtime-server-rest, @contractspec/lib.contracts-runtime-server-graphql, @contractspec/lib.contracts-runtime-server-mcp, @contractspec/lib.contracts-runtime-client-react, @contractspec/lib.jobs, @contractspec/lib.error
1. Keep raw handler returns for ordinary `OK` responses.
2. Use `contractAccepted`, `contractQueued`, `contractNoContent`, or `contractPartial` for non-default success outcomes.
3. Throw `createContractError` or return `contractFail` for known failures with typed args.
4. Declare custom success codes in `spec.results.success` or `io.success`, and custom failures in `spec.results.errors` or `io.errors`.
Use canonical result mappers in adapters and clients
assisted
Route transport boundaries through the new result helpers while preserving raw success compatibility by default.
Packages: @contractspec/lib.contracts-spec, @contractspec/lib.contracts-runtime-server-rest, @contractspec/lib.contracts-runtime-server-graphql, @contractspec/lib.contracts-runtime-server-mcp, @contractspec/lib.contracts-runtime-client-react, @contractspec/lib.jobs, @contractspec/lib.error
1. Use `OperationSpecRegistry.executeResult` in adapters that need success metadata or typed failures.
2. Set REST `resultEnvelope: true` only when clients should receive `{ ok, data }` success envelopes.
3. Enable GraphQL `resultExtensions` only when the server integration publishes collected success metadata.
4. Use React runtime parser/hooks to normalize REST, GraphQL, MCP, workflow, and job responses into `ContractResult`.
Scaffold release capsule companions
manual
Add release capsules for changesets and include validation evidence.
Packages: @contractspec/lib.contracts-spec, @contractspec/bundle.workspace, @contractspec/app.cli-contractspec, @contractspec/app.web-landing
1. Run `contractspec release init` for new release work.
2. Keep `.changeset/*.md` and `.changeset/*.release.yaml` together in the same PR.
3. Use `contractspec release brief` or `contractspec upgrade prompt` to generate maintainer, customer, and agent guidance.
Use generated release manifests in tooling
assisted
Prefer generated release artifacts for changelog and upgrade flows.
Packages: @contractspec/lib.contracts-spec, @contractspec/bundle.workspace, @contractspec/app.cli-contractspec, @contractspec/app.web-landing
1. Run `contractspec release build` to populate `generated/releases/`.
2. Point changelog or upgrade tooling at `generated/releases/manifest.json` and `generated/releases/upgrade-manifest.json`.

Unique release changes

- Introduce the Builder v3 control plane as a governed authoring layer over external execution providers.
21 packages · 21 occurrences
- Wire provider/runtime integrations through the governed Builder v3 workbench and mobile-review surfaces.
21 packages · 21 occurrences
- Add a canonical typed result system for ContractSpec success and failure propagation across operations, workflows, jobs, server adapters, MCP, GraphQL, and React clients.
7 packages · 7 occurrences
- Add a family-aware ContractSpec Adoption Engine, expand contract authoring targets across CLI and VS Code tooling, and refresh release-facing schema and policy artifacts for downstream workspaces.
7 packages · 7 occurrences
- ContractSpec workspaces can now opt into family-aware reuse guidance and local catalog sync through `connect.adoption`.
7 packages · 7 occurrences
- Generated Biome policy artifacts now flag deprecated monolith usage and obvious deep runtime entrypoint imports.
7 packages · 7 occurrences
- Prefer `ContractSpecError`, `createContractError`, and `contractFail` from `@contractspec/lib.contracts-spec/results`; `@contractspec/lib.error` remains as a compatibility bridge for existing `AppError` users.
7 packages · 7 occurrences
- Replace new uses of `AppError` with `ContractSpecError` or `contractFail`; existing `AppError` consumers can convert to a compatible problem shape with `appErrorToProblem`.
7 packages · 7 occurrences
- Route transport boundaries through the new result helpers while preserving raw success compatibility by default.
7 packages · 7 occurrences
- Shared workspace discovery and IDE/CLI create flows now recognize additional contract families beyond the original core set.
7 packages · 7 occurrences
- The consumer plugin and Connect CLI now expose adoption-aware hook events in addition to contracts-spec review hooks.
7 packages · 7 occurrences
- Use `defineResultCatalog`, `standardSuccess`, `standardErrors`, `success`, and `failure` from `@contractspec/lib.contracts-spec/results` when an operation, workflow, or job needs custom codes.
7 packages · 7 occurrences
- `FieldSpec.wrapper.orientation` remains supported but should be replaced by `FieldSpec.layout.orientation` in new specs.
5 packages · 5 occurrences
- Add FormSpec layout hints, semantic field rendering, and portable text/textarea input-group addons.
5 packages · 5 occurrences
- Add text or icon addon descriptors to text and textarea fields.
5 packages · 5 occurrences
- Existing forms continue to render without changes.
5 packages · 5 occurrences
- New input addons should use `inputGroup.addons` on text and textarea fields.
5 packages · 5 occurrences
- New multi-column forms should use `FormSpec.layout`, `group.layout`, and `field.layout.colSpan`.
5 packages · 5 occurrences
- Replace renderer-specific row wrappers with portable column and colspan metadata.
5 packages · 5 occurrences
- Add release capsules for changesets and include validation evidence.
4 packages · 4 occurrences
- Add versioning-backed release capsules, generated patch notes, and guided upgrade flows.
4 packages · 4 occurrences
- Implement ContractSpec Connect as a first-class spec, runtime, and CLI workflow.
4 packages · 4 occurrences
- Improve app-config, theme, and feature authoring with explicit validation APIs, first-class theme discovery and scaffolding, and key-based app-config generation across contracts, workspace tooling, and the CLI.
4 packages · 4 occurrences
- Prefer generated release artifacts for changelog and upgrade flows.
4 packages · 4 occurrences
- Prefer the package-level validators over shallow AST checks for the three upgraded surfaces.
4 packages · 4 occurrences
- Published release changesets now require a structured release capsule.
4 packages · 4 occurrences
- Shared app-config authoring DTOs and templates now use `key`-based spec references instead of older `name`-based helper fields.
4 packages · 4 occurrences
- Shared workspace discovery and the CLI now treat `theme` as a first-class authored surface.
4 packages · 4 occurrences
- The standalone release domain under `@contractspec/lib.contracts-spec/release` is deprecated in favor of versioning-owned release metadata.
4 packages · 4 occurrences
- Theme authoring now has a canonical helper and authored-validator support.
4 packages · 4 occurrences
- Turn on the Connect adapter flow before relying on task-scoped context, review, replay, or evaluation artifacts.
4 packages · 4 occurrences
- Use the built-in Connect commands instead of custom local wrappers for risky file or command mutations.
4 packages · 4 occurrences
- Add ThemeSpec light/dark modes and a design-system Tailwind bridge for CSS variables, presets, CSS text, and OKLCH color pass-through.
2 packages · 2 occurrences
- Resolve ThemeSpec tokens for the active mode and feed them to the Tailwind preset or CSS serializer.
2 packages · 2 occurrences

Impacted packages

@contractspec/app.cli-contractspec
Layer: apps · 5 changes
@contractspec/app.cursor-marketplace
Layer: apps · 5 changes
@contractspec/app.web-landing
Layer: apps · 5 changes
@contractspec/bundle.library
Layer: bundles · 3 changes
@contractspec/bundle.workspace
Layer: bundles · 5 changes
@contractspec/integration.builder-telegram
Layer: integrations · 2 changes
@contractspec/integration.builder-voice
Layer: integrations · 2 changes
@contractspec/integration.builder-whatsapp
Layer: integrations · 2 changes
@contractspec/integration.provider.claude-code
Layer: integrations · 2 changes
@contractspec/integration.provider.codex
Layer: integrations · 2 changes
@contractspec/integration.provider.copilot
Layer: integrations · 2 changes
@contractspec/integration.provider.gemini
Layer: integrations · 2 changes
@contractspec/integration.provider.local-model
Layer: integrations · 2 changes
@contractspec/integration.provider.stt
Layer: integrations · 2 changes
@contractspec/integration.runtime
Layer: integrations · 2 changes
@contractspec/integration.runtime.hybrid
Layer: integrations · 2 changes
@contractspec/integration.runtime.local
Layer: integrations · 2 changes
@contractspec/integration.runtime.managed
Layer: integrations · 2 changes
@contractspec/lib.builder-runtime
Layer: libs · 2 changes
@contractspec/lib.builder-spec
Layer: libs · 2 changes
@contractspec/lib.contracts-runtime-client-react
Layer: libs · 5 changes
@contractspec/lib.contracts-runtime-server-graphql
Layer: libs · 5 changes
@contractspec/lib.contracts-runtime-server-mcp
Layer: libs · 5 changes
@contractspec/lib.contracts-runtime-server-rest
Layer: libs · 5 changes
@contractspec/lib.contracts-spec
Layer: libs · 5 changes
@contractspec/lib.design-system
Layer: libs · 2 changes
@contractspec/lib.error
Layer: libs · 5 changes
@contractspec/lib.jobs
Layer: libs · 5 changes
@contractspec/lib.knowledge
Layer: libs · 5 changes
@contractspec/lib.mobile-control
Layer: libs · 2 changes
@contractspec/lib.provider-runtime
Layer: libs · 2 changes
@contractspec/lib.provider-spec
Layer: libs · 2 changes
@contractspec/lib.ui-kit
Layer: libs · 7 changes
@contractspec/lib.ui-kit-web
Layer: libs · 7 changes
@contractspec/module.builder-workbench
Layer: modules · 2 changes
@contractspec/module.mobile-review
Layer: modules · 2 changes
@contractspec/module.workspace
Layer: modules · 5 changes