Migrating from 2.x to 3.0

3.0 hardens gherkin-ai for team and CI use. Most projects need no changes: every gherkin-ai.config.json produced by 2.x versions that we tested validates unchanged. The breaking changes below matter mostly to automation and to MCP users.

Start by running:

ghk upgrade             # what this project needs, as a report; asks before changing anything
ghk auth status         # which provider, model and credential will be used

Assisted upgrade (ghk upgrade)

ghk upgrade checks the project against everything in this guide:

With --apply, or after you confirm interactively, it:

1. creates the branch ghk-upgrade-v<version> (or the one given with --branch). It refuses to run on a dirty working tree unless you pass --force;
2. writes the automatic config fixes;
3. regenerates every feature;
4. deletes files from the previous generation that are no longer generated, but only if their checksum in .ghe/inventory.json proves they were never edited. Other leftovers are listed for review; --prune deletes them too;
5. with --commit, commits on that branch.

Items marked [manual] (CI files, MCP clients, credentials) are reported with a hint and are never edited. ghk upgrade --check exits with code 4 while required changes are pending. --cli also checks the npm registry for a newer CLI. --json prints the full report.

To validate the configuration layers on their own: ghk config validate.

Credentials and login

LLM configuration

• New providers: openai-compatible, azure-openai (now implemented), bedrock, gemini (now implemented), vertex. See ENTERPRISE.md §2.
• The default Anthropic model is now claude-opus-5-5 (previously claude-3-opus-20240229). Pin a model with llm.model if you need a different one.
• LLM_PROVIDER, LLM_MODEL and LLM_BASE_URL still work. You can also set them in any config layer under llm.
• Requests now time out (llm.timeoutMs, default 120 s). Transport retries are no longer nested, so the worst case is maxRetries + 1 attempts instead of 9.
• Secrets in prompts are redacted before sending.

Exit codes and output

• Exit codes follow a fixed table (2 usage, 3 config, 4 gate, 5 policy, 6 provider, 7 drift). In 2.x almost every failure was 1. Update CI scripts that compare against 1. Most should check for non-zero instead.
• --json now guarantees one JSON document on stdout. In 2.x it only silenced the logger. It works before or after the command name.
• Errors are reported as messages with hints. Stack traces only appear with --verbose.
• The CLI no longer writes ./.ghe/logs/execution.log.jsonl on every run. Set logging.file to keep a log file.
• lint and converge accept --threshold. converge --strict is accepted but deprecated, because the threshold is always enforced.

Workspace handling

• --project <dir> no longer creates the directory, except for ghk init. A typo now exits with code 2.
• In CI or with --yes, the CLI no longer switches silently into the first sub-project it finds. Pass --project.
• --help, config, auth, login, stacks and mcp never prompt or change directory.

Agent-driven writes

• ghk autopilot is now a dry run by default, like verify. Add --apply to write files.
• With --apply, both verify --auto-fix and autopilot refuse to run:
  • in CI, unless you pass --allow-unattended-writes (or set policy.allowUnattendedWrites);
  • on main or master, unless you pass --force-branch (or configure policy.protectedBranches).
• File paths returned by the model that point outside the workspace are dropped.
• Every file goes through the agent firewall (ENTERPRISE.md §14). Files it does not ALLOW are saved as .ghe/patches/<file>.proposed instead of being written. This covers secrets and .env*, .ghkgovernance.yaml, an existing gherkin-ai.config.json, CI workflows, migrations, infrastructure and package.json, plus anything listed in policy.firewall.
• .ghkgovernance.yaml is still read, and its allowedPaths are now enforced. In 2.x only protectedPaths and requireHumanApprovalOn were checked, so an existing file may now block writes outside allowedPaths. Its protectedPaths and requireHumanApprovalOn feed the firewall too. Without a policy, the whole workspace is writable except the built-in denied and approval paths.

Delivery risk

ghk quality, ghk autopilot and the MCP risk tool use the rebuilt risk engine:

• it scores the git change set, not only the specs, across six weighted dimensions with evidence;
• the fixed architecture-drift baseline of 30 is gone;
• scores and levels therefore differ from 2.x.

The scorecard keeps blastRadius, testStrength, securitySensitivity, architectureDrift, overallRiskScore, riskLevel, requiresHumanApproval and factors, and adds basis, changedFiles, dimensions and approvalThreshold. Set the approval level with policy.risk.requireApprovalAt. New command: ghk risk.

Test sandbox

verify --docker now runs in the stack's toolchain image:

• without network access by default;
• with memory, CPU and process limits;
• with all capabilities dropped and a read-only root filesystem.

Tests that download dependencies need --docker-network bridge, or sandbox.network: "bridge". The image and limits can be set in sandbox.*.

MCP server

• The server is rebuilt on @modelcontextprotocol/sdk. Tool names are unchanged, except:
  • run_cli_login was removed.
  • run_cli_agent_log only records actions. Use run_cli_agent_log_list to read them.
  • run_cli_audit no longer accepts clear.
• Read-only by default. Tools that write files need "mcp": { "allowWrite": true } in the config. run_cli_verify and run_cli_autopilot additionally need GHK_ALLOW_DESTRUCTIVE=true. Tools that are not enabled are not listed.
• generate_contracts is now classified as read-only. It returns contracts and does not write them.
• Re-run ghk mcp install, so the client configuration pins the package version.

Web Studio

Open the URL printed by ghk web. It contains a session token, and API calls without the token are rejected. autopilot and --apply cannot be run from the browser.

Plugins

config.plugins is validated. Both ["my-plugin"] (2.x) and { "load": ["my-plugin"] } work. When plugins.allow is set, only listed plugins load. The undocumented beforeGenerate/afterGenerate hook manager (core/hooks) was removed; use the GherkinAIPlugin interface.

Telemetry and audit

.gherkin-ai/audit.log (plain text) is replaced by .gherkin-ai/audit.jsonl (structured JSON lines). Telemetry is written for every command, locally only. Disable it with telemetry.enabled: false or GHK_TELEMETRY_DISABLED=true.

Generated code

Every stack now renders the same kernel from the feature (aggregate, unit tests, HTTP contract test where there is an API, pending BDD steps bound to the .feature file) and is built and tested in CI. Generated projects are complete, buildable projects rather than loose snippets, so regenerate into a clean directory or branch and review the diff: many paths moved.

Runtime kernel. Every backend also gets the runtime kernel (RUNTIME-KERNEL.md):

• PostgreSQL persistence with idempotent commands and an outbox;
• a RabbitMQ relay and an inbox consumer with a dead-letter queue;
• sagas;
• OpenTelemetry trace propagation.

Its integration tests are excluded from the default test command and run with the stack's integration command, for example npm run test:integration or mvn verify -Pintegration, given DATABASE_URL and AMQP_URL.

Frontend API clients send a W3C traceparent header. Pass traceparent: false (Dart: traceparent: () => null) to disable it, or a function to propagate an existing trace. Cross-origin deployments must allow the header in CORS.

AWS CDK (./infrastructure) is generated when infrastructure.awsCdk is true, or by default when stack.messaging is SQS or SNS.

Identifiers are derived from the feature name with diacritics removed (Creación de Pedidos → CreacionDePedidos). To choose a shorter name, tag the feature with @aggregate:Pedido (or @aggregate(Pedido)); every generator then emits PedidoAggregate, CreatePedidoCommand, pedido.aggregate.ts and so on. Localized features (# language: es) are parsed as Gherkin. Command names come from identifiers quoted in When steps ("CreateOrderCommand" → CreateOrder) or, for English features, from the step's verb; otherwise a single Process<Feature> command is generated.

Generated toolchains target currently supported runtimes: Node 24 for frontends, .NET 8, Java 17, Python 3.12, Go 1.22, PHP 8.3, Ruby 3.3, Elixir 1.17. The CLI itself requires Node.js 22.12 or later (Node 20 is end-of-life).