Known limitations
Codifix v2.1.0 is the current stable release. It is a breaking major release: databases migrate in place and bundle v1 imports remain supported, but v1 clients, direct API integrations, and configuration need review before an upgrade.
Read the v2.1.0 release notes and Update guide before changing a production install.
v2 compatibility targets
| Surface | v2 expectation |
|---|---|
| CLI | Current documented core commands and --json shapes are the public surface. Removed v1 spellings are migration notes only. |
| HTTP API | Operations marked x-stability: core in the running OpenAPI document are the integration boundary. Control-plane operations marked internal can evolve. |
| Database | Migrations are append-only; applied migrations are not edited. |
| Bundles | New exports use deterministic schema v2; schema v1 imports remain supported. |
| MCP | Read-only query, global search, resume, resource, and prompt tools remain adapters over the service API. |
| Packages | Debian amd64/arm64, Homebrew, macOS Intel/Apple Silicon, and Windows x86_64 are release targets. |
Advanced surfaces
Windows 2.1.0 packages are a preview of client/operator tools. They do not bundle the complete native PostgreSQL/PDS/Pi stack or establish full Windows parity. Publication does not upgrade existing installations.
| Surface | Limitation |
|---|---|
| Loop automation | Approval-gated by design; risky actions stop for human review. |
| Code graph UI | Falls back to a flat 2D canvas renderer without WebGL; depends on extraction coverage for each repository. |
| Eval research workflows | Release claims still require reviewed held-out suites and a passing gate. |
| Demo web UI | Uses browser-local sample data and is not a live backend. |
Breaking changes from v1
- Cap'n Proto endpoints and config keys are gone; live clients use
/ws. memory automation flushbecamecodifix watcher flush,codifix capture taskbecamecodifix capture, andcodifix dev initbecamecodifix dev.memory setupwas removed in favour ofcodifix wizard./v1/stats,/v1/offline/pending, and the browser auth-token handoff were removed; several loop and activity routes were consolidated.- Authenticated principals now determine durable authorship.
--writer-idand[writer]remain advisory labels. - Authorization uses explicit permission sets. Role names remain convenient presets, not an ordinal authorization ladder.
Upgrade checklist
Before upgrading:
codifix status --project <project-slug>
codifix doctor
pg_dump "$DATABASE_URL" > codifix-before-upgrade.sqlAfter upgrading:
codifix service restart-all
codifix doctor
codifix health
codifix status --project <project-slug>
codifix upgrade --dry-runThe service embeds append-only migrations through 0084 and applies pending ones
at startup. Do not run an older binary against a migrated database. After new
writes, preserve accepted work and recover forward rather than restoring a
stale database as authority. Review codifix upgrade --dry-run before refreshing
repo-local skills. Restart only the selected installation, not unrelated areas.
Read Operations, Doctor and health, or Update.