6.6.6

May 25, 2026 · 11 packages · 31 unique changes · 12 release entries

appsbundlesintegrationslibsmodules

This release affects the contracts, integrations, sharedLibs, solutions familyies.

Run contractspec connect adoption resolve --family contracts to see how it impacts your project.

Release summaries

builder-agent-lanes-finalization
Finalize Builder agent-lane release communication for canonical execution-lane persistence, alias-only metadata, diagnostics surfaces, precision-tool gating, and background-agent lifecycle evidence.
maintainer
Builder release artifacts now document canonical lane-key persistence, alias metadata, precision-tool readiness, background-agent lifecycle evidence, and safe JSON terminal/workbench surfaces.
agent
Agent operators can use shorthand Builder lane entry points while replay, readiness, and workbench state continue to key off canonical execution lanes.
integrator
Integrations can display `sourceAlias` for human traceability without branching contracts, generated manifests, or replay decisions on alias names.
builder-first-class-v2-alias-modes
Expose Builder first-class v2 alias-to-canonical lane metadata without minting new execution-lane keys.
maintainer
Maintainers can verify that Builder v2 user-facing aliases remain metadata over canonical execution-lane keys.
integrator
Integrators reading `contractspec builder modes --json` can map `ultrawork`, `ulw`, and `ralphone` to their canonical persisted lane keys.
builder-parallel-sessions
Add Builder parallel session metadata and collision-resistant local run ids.
maintainer
Builder production run state now records session metadata and default local run ids include entropy so same-root parallel starts do not collide.
integrator
Builder CLI run, plan, status, cancel, resume, and handoff flows can validate a session id while list can filter by session id for safer multi-agent operation.
customer
Multiple local Builder sessions can run side by side without accidentally sharing the same durable run directory.
builder-production-harness
Ship the CLI-first Builder production harness with real Codex/opencode-go provider paths, durable run controls, richer workbench summaries, and Builder config extensions.
maintainer
Builder production runs now have durable lifecycle controls, provider invocation evidence, resume/cancel/handoff state, and config-schema support for provider command and safety defaults.
integrator
Codex and opencode-go integrations expose parsing and receipt helpers for real CLI JSON output while preserving deterministic dry-run behavior.
builder-production-workflow
Add the CLI-first Builder production workflow with Codex planning gates, opencode-go completion routing, durable run evidence, and workbench run-state summaries.
maintainer
Builder now has a typed production profile and durable CLI run artifacts that align the Builder, execution-lanes, Connect, and module-bundle spec packs.
integrator
Integrators can configure the `codex-opencode-go` Builder profile with Codex frontier roles, opencode-go executor routing, and GPT-5.5 quality gates.
builder-specs-pack-v0
Add the Builder specs-pack V0 dry-run surface for safe external zip/folder import, deterministic analysis, readiness reporting, and CLI implementation planning without repository writes.
maintainer
Builder now has a typed V0 specs-pack contract and runtime dry-run path for external product-intent packs.
agent
Coding agents can use `contractspec builder pack plan --dry-run --json` as a source-ref-preserving handoff before implementation.
integrator
Hosts can consume specs-pack import, analysis, readiness, and implementation-plan types without enabling unsafe apply behavior.
builder-tmux-orchestrator
Builder tmux workbench orchestrator with multi-agent, multi-model local execution using codex/opencode CLI tools.
maintainer
The builder tmux workbench now supports profile-driven multi-agent orchestration. Use `--profile codex-opencode-go` to spawn dedicated panes per role (planner, architect, executor, verifier, critic) with automatic provider routing and pane recovery.
integrator
New `LanePaneOrchestrator` and `TmuxLaneRuntimeStore` classes implement `LaneRuntimeStore` interface for tmux-backed persistence. Context sharing via `.contractspec/builder/lane-contexts/` and auto-recovery up to 3 retries per pane.
builder-tmux-terminal
Add first-class Builder tmux CLI commands for durable interactive terminal sessions, including doctor, start, attach, send, capture, status, and stop flows.
agent
Builder users can now run REPLs, debuggers, TUIs, dev servers, and local agent sessions in named tmux sessions through the main CLI.
cli-help-uniformity
Uniformize ContractSpec CLI root and subcommand help so public command discovery stays category grouped and complete.
maintainer
Maintainers get tests and docs that keep root command registration and nested help rendering aligned as command families are added.
customer
CLI users see complete root help and category-grouped subcommand help for command families such as Connect, Intelligence, and Changelog.
cli-onboard-guided-adoption
Add a CLI-first onboarding workflow that reuses Connect adoption guidance, models guided onboarding through the surface runtime, generates managed AGENTS/USAGE guides, and exposes the same onboarding tracks through the CLI MCP surface and docs entrypoints.
maintainer
Maintainers get a single onboarding catalog and planner that powers CLI output, managed repo guides, Connect-compatible evidence, and the CLI MCP onboarding resources.
integrator
Integrators can bootstrap OSS adoption with track-aware guidance for contracts, UI design, knowledge, AI agents, and learning journeys without inventing a second Builder or Connect model.
customer
CLI users can run `contractspec onboard` to generate repo-local AGENTS/USAGE guidance, get recommended examples and next commands, and query the same onboarding information through MCP.
connect-hook-exit
Ensure successful Connect CLI hook actions terminate after completion.
maintainer
Maintainers can run `bun run contractspec:connect:gate` without successful Connect hook child processes staying alive on open runtime handles.
integrator
Host integrations invoking `contractspec connect hook contracts-spec before-file-edit --stdin --json` now receive the verdict and process exit promptly after successful verification.
contract-intelligence-first-slice
First Contract Intelligence slice for repo-default analyze/export/import/reconcile/adopt dry-run workflows, with script-safe discovery and integrity output contracts.
maintainer
Contract Intelligence provides repo-default analyze/export/import/reconcile/adopt dry-run workflows with script-safe discovery and integrity output contracts.
integrator
Integrators can use dry-run analyze, export, import, reconcile, and adopt workflows with script-safe discovery and integrity output contracts.
agent
Agents can use Contract Intelligence dry-run workflows for repo analysis, portfolio centralization, and contract adoption with safe discovery and integrity outputs.

Migration guide

Preserve canonical execution-lane keys
Required
Keep persisted Builder state and generated release artifacts keyed by canonical execution-lane values.
1. Store coordinated parallel execution as `team.coordinated` even when invoked through `ultrawork`, `ulw`, or background-agent surfaces.
2. Store persistent completion loops as `complete.persistent` even when invoked through `ralphone`.
3. Persist the invoking shorthand only as alias metadata such as `sourceAlias`.
4. Treat tool diagnostics, tmux, and workbench status/cancel/attach JSON as evidence surfaces rather than additional lane keys.
Adopt Builder production lifecycle controls
Existing `builder run --dry-run` flows continue to work; operators can now use doctor, resume, cancel, status, handoff, agents, and modes commands.
1. Run `contractspec builder doctor` before live provider runs.
2. Use `contractspec builder status --run-id <runId>` and `contractspec builder handoff --run-id <runId>` to inspect durable run state.
3. Configure optional `.contractsrc.json > builder.providerCommands`, `smokeTestMode`, and `safety` defaults when local command paths or policies differ from defaults.
Adopt the codex-opencode-go Builder profile
Use `.contractsrc.json > builder.executionProfile` when enabling production Builder runs.
1. Run `contractspec init --preset builder-hybrid` for hybrid defaults.
2. Use `contractspec builder run "<goal>" --dry-run` to inspect generated run evidence before live provider checks.
3. Configure Codex subscription auth and OpenCode Go model access before removing `--dry-run`.
Use Builder specs-pack dry-runs for external product-intent packs
Import and analyze external specs packs before asking agents to implement them.
1. Run `contractspec builder pack import <zip-or-folder> --json` to validate the pack shape.
2. Run `contractspec builder pack analyze <zip-or-folder> --json` to inspect layers, requirements, ambiguities, and readiness.
3. Run `contractspec builder pack plan <zip-or-folder> --dry-run --json` before `$ralph` or `$team` implementation.
Use `contractspec onboard` as the primary OSS onboarding flow
The CLI now provides a first-class onboarding command that should replace ad hoc “quickstart + create one spec” repo bootstraps.
When: When documentation, scripts, or internal runbooks still point contributors directly to `contractspec create` as the first repo-local step.
1. Run `contractspec onboard` at the repo root to generate or update the managed `AGENTS.md` and `USAGE.md` sections.
2. Use `contractspec onboard <track...>` to focus onboarding on one or more tracks such as `knowledge` or `ai-agents`.
3. Use `--example <key>` when you want the command to create a lightweight example stub under `.contractspec/examples/`.
Include the new `usage-md` setup target in setup automation
`contractspec init` can now create or merge a managed `USAGE.md` section in addition to `AGENTS.md`.
When: When custom setup wrappers or tests enumerate setup targets explicitly.
1. Add `usage-md` anywhere setup target lists are pinned manually.
2. Treat `USAGE.md` as the human-facing repo onboarding document and `AGENTS.md` as the AI-operator document.

Upgrade steps

Use builder execution profiles for multi-agent workbenches
assisted
Pass `--profile codex-opencode-go` to `contractspec builder tmux workbench` to enable multi-agent orchestration with dynamic model routing.
Packages: @lssm-tech/app.cli-contractspec
1. contractspec builder tmux workbench --profile codex-opencode-go --task 'Your task here'
2. Panes auto-close when done; review artifacts in `.contractspec/builder/tmux-state/`
Configure local builder runtime mode
assisted
Set `builder.runtimeMode: "local"` in `.contractsrc.json` to use local CLI providers (codex, opencode) instead of managed API mode.
Packages: @lssm-tech/app.cli-contractspec
1. Edit `.contractsrc.json` and set `builder.runtimeMode` to `"local"`
2. Set `aiProvider` to `"ollama"` and `aiModel` to `"codellama"` for local inference
3. Or use `"codex"` / `"opencode"` CLI tools directly via `--provider`
Verify Builder agent-lane metadata and diagnostics
manual
Validate that aliases, diagnostics, tool capability manifests, and background-agent evidence remain additive and replay-safe.
Packages: @lssm-tech/app.cli-contractspec, @lssm-tech/lib.builder-spec, @lssm-tech/lib.builder-runtime, @lssm-tech/lib.contracts-spec, @lssm-tech/lib.execution-lanes
1. Run CLI blackbox coverage for Builder aliases, tools doctor/diagnostics, background-agent status/cancel/attach, and tmux/workbench JSON output.
2. Confirm AST rewrite and workspace rename plans require Connect review before writes.
3. Confirm degraded LSP, AST-Grep, and prebuild adapters block unsafe write plans with receipts.
Inspect Builder alias metadata
manual
Use `contractspec builder modes --json` to confirm aliases are entrypoint metadata, not persisted lane keys.
Packages: @lssm-tech/app.cli-contractspec
1. Run `contractspec builder modes --json`.
2. Verify `team.coordinated` lists `ultrawork` and `ulw` in `sourceAliases`.
3. Verify `complete.persistent` lists `ralphone` in `sourceAliases`.
Scope parallel Builder operators with session ids
assisted
Pass `--session-id` and optionally `--parallel-group-id` when running several Builder agents against one workspace root.
Packages: @lssm-tech/app.cli-contractspec, @lssm-tech/lib.builder-runtime
1. Keep using `--run-id` as the durable primary key for exact resume, cancel, status, and handoff operations.
2. Add `--session-id` to fail closed when a command is accidentally pointed at another operator's run.
3. Use `contractspec builder runs list --session-id <id>` to inspect one operator session.
Verify Builder production harness
manual
Confirm durable run state, provider receipts, and workbench summaries are generated from the same run directory.
Packages: @lssm-tech/app.cli-contractspec, @lssm-tech/lib.builder-runtime, @lssm-tech/integration.provider-codex, @lssm-tech/integration.provider-opencode-go, @lssm-tech/module.builder-workbench, @lssm-tech/lib.contracts-spec
1. Run `contractspec builder run "<goal>" --dry-run --run-id builder-smoke`.
2. Inspect `.contractspec/builder/runs/builder-smoke/run-state.json`, `events.ndjson`, provider receipts, and `readiness-report.json`.
3. Confirm workbench consumers render provider sessions, receipts, blockers, readiness, cancellation, resume metadata, and next actions from the run summary.
Verify Builder production workflow artifacts
manual
Production runs write state to `.contractspec/builder/runs/<runId>/`.
Packages: @lssm-tech/app.cli-contractspec, @lssm-tech/lib.builder-runtime, @lssm-tech/lib.contracts-spec, @lssm-tech/integration.provider-codex, @lssm-tech/integration.provider-opencode-go, @lssm-tech/module.builder-workbench, @lssm-tech/bundle.workspace, @lssm-tech/app.api-library
1. Check `run-state.json`, `context-pack.json`, `plan-pack.json`, `completion-ledger.json`, provider receipts, Connect review packets, test output, and readiness report.
2. Surface the same run state through `summarizeBuilderProductionRunForWorkbench`.
Verify Builder specs-pack dry-run behavior
auto
Confirm import/analyze/plan stay read-only and preserve source references.
Packages: @lssm-tech/app.cli-contractspec, @lssm-tech/lib.builder-spec, @lssm-tech/lib.builder-runtime
1. Run the Builder runtime specs-pack tests.
2. Run the Builder CLI pack tests.
3. Confirm non-dry-run `builder pack implement` fails closed.
Use Builder tmux sessions for interactive terminal work
manual
Replace ad hoc terminal windows with named Builder tmux sessions when a workflow needs durable interactive state.
Packages: @lssm-tech/app.cli-contractspec
1. Run `contractspec builder tmux doctor` to verify tmux availability.
2. Start a session with `contractspec builder tmux start --session builder-debug -- <command>`.
3. Use `send`, `capture`, `attach`, and `stop` to operate the session from automation or a human terminal.
Use grouped CLI help for command discovery
auto
Prefer `contractspec --help` and `<command> --help` as the complete category-grouped command index.
Packages: @lssm-tech/app.cli-contractspec
1. Run `contractspec --help` to see public command families grouped by category.
2. Run `contractspec <command> --help` for nested commands with the same grouped renderer.
Route onboarding through the existing Connect adoption layer
assisted
The onboarding flow now syncs and consults the existing adoption catalog before recommending new surfaces.
Packages: @lssm-tech/app.cli-contractspec, @lssm-tech/bundle.workspace, @lssm-tech/bundle.library
1. Use `contractspec connect adoption sync` to refresh the local adoption catalog outside the onboarding command when needed.
2. Prefer `contractspec connect adoption resolve --family <family> --stdin` for custom tooling that needs the same reuse recommendations.
Use CLI MCP onboarding resources instead of hardcoded prompts
manual
The CLI MCP surface now exposes onboarding tracks, rendered artifacts, and next-command suggestions.
Packages: @lssm-tech/app.cli-contractspec, @lssm-tech/bundle.workspace, @lssm-tech/bundle.library
1. Read `onboarding://tracks` and `onboarding://track/{id}` for the canonical onboarding catalog.
2. Call `onboarding_suggestTracks`, `onboarding_renderArtifacts`, and `onboarding_nextCommand` for repo-specific planning and guide rendering.
Use Contract Intelligence dry-run workflows
assisted
Use analyze/export/import/reconcile/adopt dry-run workflows with script-safe discovery and integrity output contracts. Apply requires future ContractSpec Connect review and replay evidence.
Packages: @lssm-tech/app.cli-contractspec
1. Run `contractspec intelligence analyze --dry-run` for repo analysis.
2. Run `contractspec intelligence export --dry-run` for default exports with path-line-hash redaction.
3. Run `contractspec intelligence import --dry-run` for safe import preview.
4. Run `contractspec intelligence reconcile --dry-run` for contract reconciliation.
5. Run `contractspec intelligence adopt --dry-run` for adoption preview.
6. Keep apply operations disabled until Connect review is implemented.

Unique release changes

- Add the CLI-first Builder production workflow with Codex planning gates, opencode-go completion routing, durable run evidence, and workbench run-state summaries.
8 packages · 8 occurrences
- Production runs write state to `.contractspec/builder/runs/<runId>/`.
8 packages · 8 occurrences
- Use `.contractsrc.json > builder.executionProfile` when enabling production Builder runs.
8 packages · 8 occurrences
- Confirm durable run state, provider receipts, and workbench summaries are generated from the same run directory.
6 packages · 6 occurrences
- Existing `builder run --dry-run` flows continue to work; operators can now use doctor, resume, cancel, status, handoff, agents, and modes commands.
6 packages · 6 occurrences
- Ship the CLI-first Builder production harness with real Codex/opencode-go provider paths, durable run controls, richer workbench summaries, and Builder config extensions.
6 packages · 6 occurrences
- Finalize Builder agent-lane release communication for canonical execution-lane persistence, alias-only metadata, diagnostics surfaces, precision-tool gating, and background-agent lifecycle evidence.
5 packages · 5 occurrences
- Keep persisted Builder state and generated release artifacts keyed by canonical execution-lane values.
5 packages · 5 occurrences
- Validate that aliases, diagnostics, tool capability manifests, and background-agent evidence remain additive and replay-safe.
5 packages · 5 occurrences
- `contractspec init` can now create or merge a managed `USAGE.md` section in addition to `AGENTS.md`.
3 packages · 3 occurrences
- Add a CLI-first onboarding workflow that reuses Connect adoption guidance, models guided onboarding through the surface runtime, generates managed AGENTS/USAGE guides, and exposes the same onboarding tracks through the CLI MCP surface and docs entrypoints.
3 packages · 3 occurrences
- Add the Builder specs-pack V0 dry-run surface for safe external zip/folder import, deterministic analysis, readiness reporting, and CLI implementation planning without repository writes.
3 packages · 3 occurrences
- Confirm import/analyze/plan stay read-only and preserve source references.
3 packages · 3 occurrences
- Import and analyze external specs packs before asking agents to implement them.
3 packages · 3 occurrences
- The CLI MCP surface now exposes onboarding tracks, rendered artifacts, and next-command suggestions.
3 packages · 3 occurrences
- The CLI now provides a first-class onboarding command that should replace ad hoc “quickstart + create one spec” repo bootstraps.
3 packages · 3 occurrences
- The onboarding flow now syncs and consults the existing adoption catalog before recommending new surfaces.
3 packages · 3 occurrences
- Add Builder parallel session metadata and collision-resistant local run ids.
2 packages · 2 occurrences
- Pass `--session-id` and optionally `--parallel-group-id` when running several Builder agents against one workspace root.
2 packages · 2 occurrences
- Add first-class Builder tmux CLI commands for durable interactive terminal sessions, including doctor, start, attach, send, capture, status, and stop flows.
1 packages · 1 occurrences
- Builder tmux workbench orchestrator with multi-agent, multi-model local execution using codex/opencode CLI tools.
1 packages · 1 occurrences
- Ensure successful Connect CLI hook actions terminate after completion.
1 packages · 1 occurrences
- Expose Builder first-class v2 alias-to-canonical lane metadata without minting new execution-lane keys.
1 packages · 1 occurrences
- First Contract Intelligence slice for repo-default analyze/export/import/reconcile/adopt dry-run workflows, with script-safe discovery and integrity output contracts.
1 packages · 1 occurrences
- Pass `--profile codex-opencode-go` to `contractspec builder tmux workbench` to enable multi-agent orchestration with dynamic model routing.
1 packages · 1 occurrences
- Prefer `contractspec --help` and `<command> --help` as the complete category-grouped command index.
1 packages · 1 occurrences
- Replace ad hoc terminal windows with named Builder tmux sessions when a workflow needs durable interactive state.
1 packages · 1 occurrences
- Set `builder.runtimeMode: "local"` in `.contractsrc.json` to use local CLI providers (codex, opencode) instead of managed API mode.
1 packages · 1 occurrences
- Uniformize ContractSpec CLI root and subcommand help so public command discovery stays category grouped and complete.
1 packages · 1 occurrences
- Use `contractspec builder modes --json` to confirm aliases are entrypoint metadata, not persisted lane keys.
1 packages · 1 occurrences
- Use analyze/export/import/reconcile/adopt dry-run workflows with script-safe discovery and integrity output contracts. Apply requires future ContractSpec Connect review and replay evidence.
1 packages · 1 occurrences

Impacted packages

@lssm-tech/app.api-library
Layer: apps · 3 changes
@lssm-tech/app.cli-contractspec
Layer: apps · 2 changes
@lssm-tech/bundle.library
Layer: bundles · 5 changes
@lssm-tech/bundle.workspace
Layer: bundles · 5 changes
@lssm-tech/integration.provider-codex
Layer: integrations · 3 changes
@lssm-tech/integration.provider-opencode-go
Layer: integrations · 3 changes
@lssm-tech/lib.builder-runtime
Layer: libs · 3 changes
@lssm-tech/lib.builder-spec
Layer: libs · 3 changes
@lssm-tech/lib.contracts-spec
Layer: libs · 3 changes
@lssm-tech/lib.execution-lanes
Layer: libs · 3 changes
@lssm-tech/module.builder-workbench
Layer: modules · 3 changes