5.4.0

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.

builder-v3-control-plane-rollout

Introduce the Builder v3 control plane as a governed authoring layer over external execution providers.

connect-spec-alignment-april-2026

Implement ContractSpec Connect as a first-class spec, runtime, and CLI workflow.

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.

versioning-release-system

Add versioning-backed release capsules, generated patch notes, and guided upgrade flows.

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`.

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.

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.

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.

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.

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`.

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.

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.

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.

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.

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.

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.

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.

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`.