veritas-kanban/docs/V6-COMPATIBILITY-AND-RELEASE-POLICY.md

Veritas Kanban v6 Compatibility And Release Policy

This policy defines supported v6.1.2 combinations, harness evidence, release channels, and rollback limits. The machine-readable harness record at GET /api/config/harness-compatibility is authoritative for exact capability digests, fixture revisions, and the current host's live state.

Documentation freshness: 2026-08-24 for Veritas Kanban 6.1.2.

Harness Support Tiers

Tier	Meaning	Dispatch consequence
Certified	Installed version/build, profile, runtime manifest, probe revision, capabilities, and deterministic fixtures match passing evidence.	Allowed when all requested controls are supported.
Configured	The explicit executable adapter is enabled and ready, but current certification evidence is absent.	Allowed with a warning unless policy requires certification.
Detected	The executable is installed but the built-in profile is disabled.	Not selected automatically.
Degraded	Installation, authentication, compatibility, policy, or certification evidence is unhealthy or stale.	Enabled profiles block before attempt creation.
Unsupported	No safe executable adapter or current-platform contract exists.	Always blocks before attempt creation.

Settings, vk doctor --json, API diagnostics, telemetry, and dispatch must use these same definitions. Provider-name shortcuts and implicit OpenClaw fallback are incompatible with v6.

Compatibility Matrix

Component	Supported v6 combination	Detection/evidence	Fail-closed boundary
Server, web, shared, CLI, MCP, desktop	All release packages are exactly 6.1.2.	Package manifests, /api/health.version, vk --version, MCP metadata, desktop bundle/update metadata.	Mixed release packages are unsupported for publication.
Public API	REST API remains v1 at /api/v1, with /api compatibility aliases where documented.	X-API-Version, OpenAPI/reference docs, CLI/MCP smoke.	Unknown API versions or incompatible auth fail before mutation.
Buzz Agent	Buzz v0.4.24 commit 710ed9fff57878a1d69f809b80a6ee0416c53fc4; buzz-agent 0.1.0; ACP v1.	Exact initialize identity, capability digest, probe revision, composed Buzz fixtures.	Unknown build, buzz-acp, resume, HTTP/SSE MCP, or capability drift blocks.
Buzz relay integration	Buzz v0.4.24; NIP-11, NIP-29, NIP-42; optional NIP-43 membership.	Pinned relay compatibility evidence, signed query/event fixtures, mapping state.	Host/TLS drift, unsafe URL, bad signature, identity mismatch, replay, or disabled mapping blocks.
Grok Build	v0.2.111 build 94172f2aa4e5; generic ACP v1.	Exact version/build and x.ai capability handshake.	Unknown version, approval bypass, leader/plugin/endpoint injection, or unsupported controls blocks.
Codex CLI	Explicit codex-cli adapter with exact runtime probe.	codex --version, codex login status, runtime manifest.	Missing adapter evidence or requested unsupported controls blocks.
Codex SDK	@openai/codex-sdk 0.144.3.	SDK import plus Codex authentication and runtime manifest.	Missing SDK/authentication or unsupported controls blocks.
Codex app-server	codex-cli 0.145.0, upstream commit 25af12f7e61572b0bc18ddb1008be543b91519b0.	Generated v2 schemas, exact version, remote control disabled, deterministic and optional live smoke.	Schema drift, remote control, inherited plugins/apps/hooks/browser/computer tools, or unsandboxed shell method blocks.
Claude Code	2.1.218 (Claude Code).	Version, auth status, agent discovery, stream fixtures, optional live smoke.	Permission bypass, inherited config/plugins, unsupported lifecycle request, bad stream, or missing authoritative result blocks.
GitHub Copilot CLI	v1.0.74 public-preview ACP; tag commit 2b809c84e87dbcc88f897cb4f3fb97c43b77af95.	Version and ACP initialize handshake; authentication remains provider-managed.	Version drift, broad allow, remote/plugin/config injection, or unsupported controls blocks.
Hermes Agent	v2026.7.7.2 one-shot process adapter.	hermes --version and allowlisted boot authentication.	Resume/follow-up remains unsupported.
OpenClaw	v2026.6.11 gateway adapter.	Gateway health, runtime manifest, explicit operator tool policy.	Missing sessions_spawn/sessions_send, unknown evidence, or unsupported task controls blocks.
macOS desktop	macOS arm64 signed/notarized app with bundled 6.1.2 server/web.	Bundle version, signature, Gatekeeper, stapling, /api/health.version, update metadata.	Mixed bundle/runtime, failed readiness, signature, or metadata checks blocks stable publication.
Linux/Windows desktop	Unsigned preview artifacts only.	Cross-platform packaging workflows.	Not a supported stable install or update channel.
Desktop SQLite/profile	Existing v5.2.5 workspace upgraded in place after a complete backup.	Data/profile counts, integrity check, startup normalization, board/runtime smoke.	Competing writers, unsafe filesystem, failed migration, or missing recovery evidence blocks acceptance.

Certification And Invalidation

Deterministic conformance runs reset a seeded fixture for each repetition and persist harness-conformance-result/v1. Certification is invalidated when the provider version/build, profile digest, runtime probe revision, transport version, capability digest, fixture revision, or required policy changes.

Credential-gated live smoke is supplemental. It may prove authentication and one bounded inference on the exact build, but it cannot override a deterministic failure. If credentials, subscription, quota, binary, or upstream service are unavailable, the live tier and evidence must say so.

The credential-free Buzz release gate is:

pnpm test:buzz:compatibility

Provider-specific opt-in smoke commands are documented in Agent Providers.

Security And Authority Boundaries

• Veritas owns tasks, attempts, worktrees, launch manifests, approvals, credentials, run tools, causal events, and completion.
• Providers own only their documented transport and native session identifiers.
• Buzz communication owns signed relay delivery, not task completion.
• Credentials enter a provider only through an allowlisted boot-authentication key or a run-scoped brokered call. Raw values are never release evidence.
• Required filesystem, process, environment, network, MCP, tool, approval, budget, and lifecycle controls must be supported by current runtime evidence. Advisory controls may proceed with an attributed warning.
• Run-scoped network policy resolves and pins allowed destinations, routes governed traffic through the egress gateway, enforces protocol, host, port, HTTP method, and normalized path rules, and records redacted decision evidence. Direct or unverifiable network paths fail closed when enforcement is required.

Release Channels

Channel	Purpose	Promotion gate
dev	Local packaged testing and controlled development metadata.	Local build and smoke only; never promoted to users.
beta	Prerelease candidate testing.	Full CI, deterministic harness suites, unsigned desktop packaging, migration and runtime smoke, documented blockers.
stable	Supported macOS arm64 release.	Merged release PR, annotated tag, published release, signed/notarized assets, checksums, updater metadata, downloaded-app launch, and live Homebrew validation.

Linux and Windows preview artifacts do not become stable merely because their packaging workflows pass.

Version Negotiation

1. The server, web, CLI, MCP, shared library, and desktop release versions must be identical.
2. CLI and MCP write smoke compares the local package version with /api/health.version. Unreviewed skew is unsupported.
3. A provider upgrade invalidates its old support record even when the provider name is unchanged.
4. Desktop local mode uses one bundled server/web payload from the same release commit.
5. A stale web/PWA client must refresh before writing. v6 does not queue offline API writes.

Rollback Policy

Asset	Supported rollback	Limit
macOS app bundle	Reinstall the previous signed release or correct updater metadata.	Safe only when current data/profile records remain compatible with the older app.
Bundled server/web	Roll back with the complete app bundle.	Never mix payloads from different commits.
Self-hosted server	Install the prior release and restore the pre-upgrade backup when required.	No automatic destructive schema down-migration promise.
Desktop SQLite/profile	Restore the stopped-writer v5.2.5 backup.	Do not copy over a live database or treat app downgrade as data rollback.
Provider profile	Disable the changed profile or restore reviewed v5 configuration from backup.	Do not re-enable an ambiguous legacy profile or bypass support evidence.
Buzz connection	Disable trigger rules, mapping, and adapter while retaining audits and local Squad Chat data.	Veritas does not delete remote Buzz events or write imported definitions back.

Follow v6 Upgrade, Install, Remote, And Admin Guide and Migration Recovery for the concrete recovery path.