v1.0.0 definition of done

This page says what VegaDūta 1.0.0 promises, what it does not, the rules that apply from 1.0.0 on, and the checklist a release candidate must pass. It is written before the release so the release can be judged against it. Where a statement is a new commitment rather than a description of today's behaviour, it is marked New in 1.0; those are the points the project lead signs off (section 5). Everything else points at the file that already holds the rule.

Where this page and the code disagree, the code wins and this page is corrected. Status when this page was written: 2026-10-22, after v0.1.9 was published. 1.0.0 is not scheduled; it is released when section 4 is complete, not on a date.

1. What 1.0.0 promises, and what it does not

Promises. The core path works as documented and its public surfaces follow the stability contract in section 2: the chat turn, tenancy, authentication, approvals, workflows, knowledge, audit, MCP and A2A (security, tenancy, chat, providers, agents, guardrails, approval, workflow, knowledge, audit, mcp, mcpserver; list from repository structure), deployed with any of the three install tiers (personal/Lite, Full, Kubernetes) on the platforms below. An install from 0.1.9 upgrades to 1.0.0 with its data.

Platforms 1.0.0 is verified on: Windows (Setup app, scripts/vegaduta.ps1), macOS (Setup app .dmg, scripts/vegaduta), Linux (install.sh, scripts/vegaduta), each with Docker Compose v2; Kubernetes through the Helm umbrella chart (kind; a real cluster is not part of the gate).

Personal edition. 1.0.0 ships a lean personal edition (requested by the maintainer on 2026-10-22): the same jar and image, with one setting, app.edition.tier (personal, lite, full), that switches features off at start-up in the personal tier. In personal, billing and payments, the Slack, Discord, Teams and X channels, the A2A directory and MCP server exposure, the platform operator console (the LLM-pool console stays), SCIM and template moderation, cloud speech (Sarvam, ElevenLabs), realtime voice share and demo media are off, and the console hides their controls and answers 404 on their routes. Lite and Full behave exactly as before. No module is removed, no Flyway migration changes and no entity is dropped. A separate personal assembly or image is not part of 1.0.0. The design and work packages are in the plan merged as a lighter, faster personal install; the implementation is open as pull request #101 and is not part of any release yet. It is a requested 1.0.0 item, so it is in the release only if every box under "Personal edition" in section 4 has its evidence.

Spring Boot 4.1 and Spring AI 2.0 (in 1.0.0 if its exit criterion is met; decided 2026-10-22). The platform runs on Spring Boot 3.5 today. The migration (ADR-0012 phases 2 and 3) is open as draft pull request #99. It touches every module. The lead decided on 2026-10-22 that it is part of 1.0.0, on one condition: it ships only if the exit criterion below is met on the release candidate. If it is not met in time, it stays on the roadmap and ships in a later release. The exit criterion is that all of these hold:

1. the full core mvn verify is green;
2. the boot check (scripts/ci/boot-check.sh) passes on every deployable shape (api, jobs, worker and the migrate-only run), against an empty database and against a database upgraded from 0.1.9;
3. no new critical or high vulnerability appears in the image scans compared with the same commit on Spring Boot 3.5;
4. it has soaked: a staging or personal stack ran the release candidate for a stated period (at least seven days of use, recorded in the readiness report) with no regression.

If any item is missing, the answer is "out of 1.0.0" and the evidence gathered so far goes to the pull request.

Does not promise (these stay preview; the release notes name them again):

Area	State at 1.0.0	Source
reliability, devices, payments, agents-studio demo and face, voice menus, documentgen, codeintel, sdlc, brief, sharing	preview: thinner tests, may move or change without the deprecation period	repository structure, "Early / niche"
services/piece-host	preview, off by default, not called against a real service	README
Java Agent SDK (io.vegaduta:*)	0.x; @Experimental APIs may change; japicmp is still skipped (japicmp.skip=true) although 0.1.0 is published, so no compatibility check runs yet	SDK docs, sdk/java/pom.xml
Python Agent SDK (vegaduta-agent)	alpha classifier; stays 0.x unless the lead decides otherwise (open decision A)	README
macOS/Windows Setup binaries	unsigned or ad-hoc signed, no notarization	releasing.md
Spring Boot 4 / Spring AI 2	in 1.0.0 only if the candidate criterion above is met; otherwise a later release	ROADMAP.md

Also not promised: an LTS line (1.0 is supported like any minor, section 3), a hosted service, an SLA, or response times (SUPPORT.md says "no guaranteed response time").

2. The stability contract

From 1.0.0 the surfaces below are the public API in the semver.org sense (rule 1: declare the public API). Anything not listed, including internal Java packages under com.agenticai.*, undocumented configuration, the console's own routes, and database tables, is internal and may change in any release.

Surface	What is covered	How it is enforced
REST API under /api, /v1, /mcp	every operation in docs/api/openapi.json that is not marked preview: paths, verbs, operationId, required inputs, success bodies, enums, types, auth scheme	scripts/ci/openapi-breaking.mjs (rules: path-removed, operation-removed, operation-id-changed, parameter-required, request-body-required, request-property-required, request-media-type-removed, response-body-removed, response-property-removed, enum-narrowed, type-changed); allowlist entries need a reason and a CHANGELOG line
Not covered by that gate, still covered by the promise	the exact 2xx code, 4xx/5xx bodies beyond the shared Error schema, permission requirements (x-permissions), header and webhook formats, paging and idempotency conventions	review; OpenApiConventionsTest; list in API documentation, "Known limits". New in 1.0: a change to any of these that breaks a documented client counts as breaking
Events	webhook envelope and X-VegaDuta-Signature, SSE streams, docs/api/asyncapi.json	node scripts/docs/asyncapi.mjs --check (spec: asyncapi.json)
Generated clients sdk/typescript, sdk/python	regenerated from the spec; same contract as the REST API	node sdk/generate.mjs --check
Java / Python Agent SDKs	not covered at 1.0.0 (section 1). When one reaches 1.0.0 it gets its own tag and the rules of section 3	japicmp (SDK_JAPICMP_BASELINE) for Java
Helm	value keys of charts/vegaduta and the per-service charts as documented in deploy/helm/README.md; chart version equals the release version	scripts/ci/helm-package.sh, helm-validate.sh. New in 1.0: removing or renaming a documented values key is breaking
Compose	variable names in deploy/compose/.env.example, profile names (rag tools workspace for Lite; temporal events jobs observability tracing voice rl code-intel builder sandbox tools browser for Full), overlay file names, service names the docs mention	make compose-validate; New in 1.0 as a promise
Launcher CLI	the commands and flags printed by scripts/vegaduta help (up personal down status logs doctor secrets backup restore upgrade restart make-admin models seed-demo) and the Setup app flags (--dir --tier --version --repo --release-url --release-sha256 --from --port --documents --browser --extras --list-extras --no-browser --yes --dry-run). scripts/vegaduta.ps1 has no models or seed-demo; that gap is a known limit, not a promise	tests/install, installer.yml
Configuration	Spring properties and environment variables in configuration and the generated reference; defaults, meaning and type	gen-config-reference.py --check catches undocumented new properties
Database	Flyway migrations are forward-only; a released migration is never edited, renamed or renumbered; Flyway versions are one namespace across controlplane/ and tenant/; out-of-order: true stays on, so migrations stay additive	scripts/ci/flyway-lint.sh
Persisted identifiers	agentic-ai stays in: Java packages com.agenticai.*, Maven groupId, Keycloak realm and theme agentic-ai, database names, Flyway history. Also the key prefixes vdak_ and vmcp_ and the APP_ENCRYPTION_KEY format (base64 of 32 bytes, identical in every core shape)	AGENTS.md "Naming" and rule 5

Not covered: the web console's look, copy and routes; log text; metrics names (New in 1.0: metrics and trace attribute names are covered only where docs/ lists them); the contents of examples/; Terraform reference modules under infra/ (reference material, versioned with the repository, not a stable module interface).

3. Semver, deprecation, upgrades, support

Semver (New in 1.0, applying semver.org to section 2). - Patch 1.y.Z: bug and security fixes; no new migration that cannot run on a 1.y.* database; no behaviour change a documented surface would notice. - Minor 1.Y.0: additive changes (new endpoints, optional parameters, response fields, values keys, config properties, Flyway migrations, commands); deprecations (semver rule 7: deprecating needs a minor). - Major X.0.0: the only release that removes or incompatibly changes a section 2 surface. Clients must ignore response fields they do not know (API deprecation policy already says so). - Pre-releases 1.0.0-rc.N follow semver rule 9 and the pre-release path in releasing.md (exact version tag only; never latest). - One version number per platform release: core, web, console images, charts, generated clients and Setup app all carry it. The Java and Python Agent SDKs version on their own tags (sdk-vX.Y.Z, pysdk-vX.Y.Z).

Deprecation. Today: REST routes get @ApiDeprecated, Deprecation/Sunset/Link headers, deprecated: true and x-sunset in the spec, a ### Deprecated CHANGELOG entry and at least 180 days notice (ApiDeprecationPolicyTest); DEPRECATION.md allows removal after the sunset date in any release before 1.0.0. New in 1.0, for every section 2 surface (the REST part is written into DEPRECATION.md under "Stability from 1.0.0" by pull request #103, effective with the release): 1. A deprecation is announced in a minor release: CHANGELOG ### Deprecated, the docs page of the surface, and (REST) the headers above; config keys and Helm values log a startup warning. 2. A deprecated item keeps working for the rest of the major line and for at least 180 days. Removal happens only in the next major and is listed under ### Removed. DEPRECATION.md says "next major release" for 1.x; the 0.x rule ("any release after the sunset date") stays until 1.0.0. 3. A security fix may shorten this; the CHANGELOG says why (as DEPRECATION.md already allows). 4. A renamed key or variable keeps the old name as an alias for the deprecation period. 5. Preview items (section 1) may change in any release, but the CHANGELOG still lists the change. 6. A new major is not released sooner than 12 months after the previous one (open decision B).

Supported upgrade paths (New in 1.0).

From	To	Promise
0.1.9	1.0.0	direct; data preserved; tested before release (section 4)
0.1.0 to 0.1.8	1.0.0	upgrade to 0.1.9 first; not tested directly
1.x	any later 1.y, y > x	direct; skipping minors is allowed and tested for the first minor and the latest
1.x	2.0	from the last 1.x only; the 2.0 notes say which
any	an earlier version	not supported; restore the backup taken before the upgrade

Mechanics that already exist: scripts/vegaduta upgrade --version X.Y.Z takes a backup first and aborts when that fails (--no-backup skips it); Flyway runs when core starts (Helm: a pre-upgrade migrate Job); the launcher prints the rollback (upgrade --version <previous> --no-backup, then restore <backup>). Downgrading the images without restoring the database is not supported: migrations are forward-only and a newer schema may not satisfy an older release. Keep APP_ENCRYPTION_KEY and back it up with the database.

Support window (New in 1.0, extends SECURITY.md and SUPPORT.md). - The latest 1.Y receives bug and security fixes. The previous 1.Y-1 receives critical fixes for three months after the next minor ships (the table SECURITY.md already has, now in force because "before 1.0, only the latest release and main" ends). - The last 1.Y after 2.0 ships gets security fixes and critical bug fixes for at least 12 months. There is no LTS branch. - Security reports follow SECURITY.md: acknowledge within 3 working days, assess within 10, fix critical and high normally within 30 days, advisory when a fixed release exists. - Images carry fixes by a new patch release; a release is not published while a fixable critical vulnerability is in any image (the grype gate in release.yml, only-fixed: true).

4. Release checklist

The release agent works through this list on the release candidate commit and records each box in the readiness report (section 5). A box is checked only with evidence; "compiled", "unit-tested", and "run on a stack" are different words (AGENTS.md rule 11) and the report uses them exactly.

Findings - [ ] Zero open blocker and zero open major findings from the readiness audit. - [ ] Every open minor finding is listed under ### Known issues in the ## [1.0.0] section of CHANGELOG.md (the release notes come from that section), each with a workaround or a fixed-in target.

CI and release workflow - [ ] CI OK and CodeQL OK are green on the exact commit that is tagged (the verify job refuses anything else); make gates passes locally on it. - [ ] release.yml is run on v1.0.0-rc.1 (it has no dry-run input; the pre-release tag is the dry run: only the exact version tag is pushed and latest does not move) and produces every asset in the table in releasing.md: 17 images + omnibus on amd64 and arm64, charts (OCI and .tgz), both source tarballs, Setup .dmg, Windows zip, Linux and macOS binaries, SHA256SUMS, signatures, provenance, SBOMs. The asset list is compared with the table file by file. - [ ] The signature, checksum and provenance commands in SECURITY.md "Verifying releases" succeed on the rc assets. - [ ] Nothing merged to main between the final tag and the published release (agent coordination rule 3). v0.1.9 was published on 2026-10-22, before this list starts.

Install and upgrade (each line states: real machine, container, or simulation) - [ ] Fresh install, personal tier, on Windows with the Setup zip: real machine or VM. A container or a PowerShell dry run does not satisfy this line. - [ ] Fresh install on macOS with the .dmg and with install.sh: real machine. - [ ] Fresh install on Linux with install.sh, Lite and Full: real machine or VM. - [ ] Helm umbrella install and helm test on kind. - [ ] Upgrade from 0.1.9 on each tier: create data on 0.1.9 (tenant, agent, a conversation, a stored provider key), scripts/vegaduta upgrade --version 1.0.0 (Helm: helm upgrade), confirm the data and the stored key are intact, then run the documented rollback and confirm the 0.1.9 backup restores. - [ ] Every deployable shape boots against an empty database and against the upgraded database: api (app), jobs, worker, and the migrate-only run, including scripts/ci/boot-check.sh. Logs are kept. - [ ] End-to-end smoke is green on the Compose stack (e2e.yml, default specs plus the install journey: sign up, first admin, one chat turn through the mock provider).

Personal edition (requested for 1.0.0; every box needs its evidence) - [ ] The edition contract exists and is tested: app.edition.tier and the per-feature escape hatches (app.edition.features.<name>.enabled) behave as documented; EditionWiringTest and EditionClosureRulesTest (a gated bean is injected only by beans gated by the same feature, or optionally) pass on the merged tree. Level: unit-tested on the whole reactor. - [ ] GET /api/public/status carries the additive edition object (tier, billingEnabled, authMode, features); the OpenAPI spec, SDK clients and consumer contracts are regenerated and openapi-breaking.mjs reports no breaking change. Evidence: the regenerated docs/api/openapi.json, SDK and contract files, and the gate passing. Level: compiled and unit-tested. - [ ] Lite and Full are unchanged: with the tier unset, lite or full, every feature is on, the whole existing core suite passes, and scripts/ci/boot-check.sh boots the real jar with the default profile set (api, jobs, worker, migrate). Level: a full mvn verify in core/ plus the boot check on a real jar. - [ ] Personal boots lean: boot-check.sh boots the real jar with SPRING_PROFILES_ACTIVE=security,knowledge,graph-memory,personal, no gated bean is created (checked from the bean list), and the override path works (APP_EDITION_TIER unset with billing-enabled=true on personal). Level: booted (the real jar); today's boot check does not use the personal profile set, so the boot-check script changes first. - [ ] The console follows one edition signal: gated controls are hidden and gated routes return a real 404 in personal and are byte-for-byte unchanged otherwise (proxy.js test), the Playwright personal project is green, and the console warns when its edition differs from core's /api/public/status. Level: vitest, plus the Playwright personal project run against a live stack; a project that was only written and linted does not satisfy this box. - [ ] Measured, not promised. Start-up time and bean count are measured on the same machine before and after the edition work, on the published 0.1.9 jar and on the release candidate (launcher start to healthy console, idle laptop, images present, fresh database, at least three alternating runs each), and published in the readiness report. The reference numbers and the target are in "Personal start-up: measured and proposed target" below. No start-up gain is claimed that is not in that table. - [ ] No Flyway migration touched (flyway-lint.sh), no ArchUnit baseline grown or refrozen, no new network hop on the chat path, and the maintainer has answered the plan's open decisions (team and members pages, /usage, platform-admin allowlist, cloud speech default, public share links, remaining channels, x402, the OpenAI-compatible API). - [ ] Docs match: docs/personal-mode.md, docs/configuration.md and the generated config reference describe the edition setting and each gated feature; the CHANGELOG [1.0.0] section lists what personal no longer includes and how to switch each feature back on.

Spring Boot 4.1 and Spring AI 2.0 (candidate; the lead decides in or out, section 1) - [x] Decision recorded: in 1.0.0, decided by the lead on 2026-10-22, on the condition that every box below has its evidence. If a box is still open when the other criteria are met, the lead decides again whether to wait or to ship 1.0.0 on Spring Boot 3.5 and move the migration to a later release; the remaining boxes of this block are then marked "not applicable" and the pull request stays a draft. - [ ] The full mvn verify in core/ is green on the merged tree (all modules, ArchUnit baselines not grown, Flyway lint unchanged). Level: unit- and integration-tested. - [ ] scripts/ci/boot-check.sh boots the real jar for api, jobs, worker and migrate-only against an empty database and against a database upgraded from 0.1.9; logs kept. Level: booted. - [ ] Image scans (grype and trivy) show no new critical or high finding against the same commit on Spring Boot 3.5; the two tables are in the readiness report. - [ ] Soak: the release candidate ran on a staging or personal stack for the period agreed with the lead (at least seven days of real use), with no regression and no unexplained restart. Level: run on a stack. - [ ] The generated OpenAPI document and the SDKs are unchanged, or the change passes openapi-breaking.mjs; the CHANGELOG [1.0.0] section lists the upgrade notes for operators.

Security - [ ] Grype and Trivy over every shipped image of the rc: no critical or high, or each remaining finding has an entry with a reason and date in .grype.yaml and is named in Known issues. The release gate checks only fixable criticals, so highs are a manual step. - [ ] bash scripts/ci/secret-scan.sh is clean; SECURITY.md names a monitored contact (contact@cdandlc.com) and private vulnerability reporting is on (checked with gh api repos/CD-LC/vegaduta/private-vulnerability-reporting; it is on today).

Documentation - [ ] make docs-build (mkdocs --strict) passes with no warning; scripts/ci/docs-link-check.sh reports 0 broken links. - [ ] The install pages match the code: every command, flag, variable and port on getting-started.md, installation.md, deploy/README.md, deploy/helm/README.md and the README was run or checked against scripts/vegaduta help, vegaduta-setup --help, .env.example and docs/configuration.md. gen-config-reference.py --check passes. - [ ] ROADMAP.md statuses are true, docs/api/DEPRECATION.md and SECURITY.md/SUPPORT.md carry the section 3 rules, and this page stays linked from the Maintainers navigation (mkdocs.yml) and docs/README.md. - [ ] The repository is configured the way the docs say it is: the maintainers team exists, the main ruleset described in branch protection exists (today it does not), and the settings listed in repository setup are on. Checked with the gh api commands on those pages, output kept.

Versions - [ ] One version everywhere, checked by script: core/pom.xml (0.1.0-SNAPSHOT today, so info.version in docs/api/openapi.json follows it), web/package.json, sdk/typescript and sdk/python manifests (0.1.0 today), the chart version and appVersion stamped by helm-package.sh (source files say 0.2.0 / 0.1.0), the Setup app buildVersion, VEGADUTA_VERSION in the tarball's .env.example. The Java and Python Agent SDKs show a version that matches the status in section 1. - [ ] CHANGELOG.md has ## [1.0.0] - <date>, empty ## [Unreleased], a ### Deprecated and ### Removed list (possibly empty), upgrade notes for operators, and Known issues.

Personal start-up: measured and proposed target

Measured on 2026-10-22 on one Apple Silicon laptop (Docker Desktop, host Ollama, qwen3.5:4b), images already present, fresh database, three alternating runs of each build, machine load 4 to 10 (so not idle), timed from the launcher start to a healthy console:

Build	Median to healthy console	Range	Core healthy
published 0.1.9	51 s	39.5 to 55.4 s	30.5 s
main with pull requests #82 to #85 merged	27.8 s	22.9 to 28.7 s	22.6 s

A warm restart of core to healthy takes 22 s. The 0.1.9 core image stores the application jar twice (315 MB compressed each, 774 MB uncompressed); #85 fixes that for the next release. This is one machine and one model host, so the numbers show direction and size, not a promise for other hardware.

Proposed target (not yet agreed, not yet measured on an idle machine): the console is healthy within 60 s of the launcher start on an idle laptop with the images present. Compose start budget: at least 5 times that target, that is at least 300 s, so a slower or loaded machine does not make Compose give up while core is still booting (on 0.1.8 with a loaded machine core needed 299 s and a 270 s budget gave up; see the plan). Core's start_period in deploy/compose/personal.yml is 600 s today, which is 10 times the target. The lead agrees or changes both numbers before the release candidate; the readiness report then measures against them.

5. Sign-off and evidence

• Signs off: the project lead (MAINTAINERS.md lists one lead and no area maintainers; if area maintainers are named before the release, each signs for their area). The release agent prepares the evidence and dispatches release.yml; it does not sign off. One person pushes the tag.
• Evidence: docs/maintainers/release-readiness-1.0.0.md (to be created by the release agent), committed with the release commit. It has one row per checkbox above: result, date, machine (real, container or simulation), the command run, and a link to a CI run or a stored log. Local log directories are not durable; the logs that back a box are attached to the release draft or the CI run.
• Decision record: the lead's sign-off, the accepted exceptions and the open decisions below are recorded at the end of that report and in the agent-coordination.md log.

Open decisions for the lead (defaults in brackets): A. Version of the Java and Python Agent SDKs at the 1.0.0 platform release [stay 0.x/preview]. B. Minimum gap between majors [12 months] and post-2.0 support [12 months]. C. Whether destructive migrations (-- gated:contract: DROP TABLE, DROP COLUMN, SET NOT NULL) are allowed in 1.x at all [no: only in a major, or for a data-protection fix]. D. Upgrade sources tested directly [0.1.9 only]. E. Spring Boot 4.1 and Spring AI 2.0: decided 2026-10-22: in 1.0.0, if every box of its block in section 4 is checked, including the soak. Still open: the soak length [7 days of use in the draft; the lead may shorten it for a release candidate, for example to 72 hours of continuous run plus 7 days of the maintainer's own use after the tag, if the criteria otherwise pass]. F. The personal start-up target and the Compose start budget [60 s to a healthy console on an idle laptop with images present; budget at least 5 times that].

6. Sources

Comparable projects and norms. Fetched or searched 2026-10-22; wording is paraphrased. - Semantic Versioning 2.0.0: https://semver.org/spec/v2.0.0.html - LangChain and LangGraph release policy (breaking changes only in majors; deprecated features work through the whole 1.x line; maintenance of at least 1 year after the next major): https://docs.langchain.com/oss/python/release-policy - Semantic Kernel 1.0 (no further breaking changes to non-experimental features; stable, preview and alpha packages): https://devblogs.microsoft.com/semantic-kernel/semantic-kernel-v1-0-1-has-arrived-to-help-you-build-agents/ - n8n 1.0 (semantic versioning adopted, breaking changes collected in a migration guide): https://blog.n8n.io/n8n-version-1/, https://docs.n8n.io/1-0-migration-checklist - Dify 1.0 (back up, migrate, then upgrade): https://docs.dify.ai/development/migration/migrate-to-v1 - Langflow release notes (install a new version separately, export flows first): https://docs.langflow.org/release-notes - OpenHands 1.0 (rebuilt on an SDK; the project's own migration note): https://openhands.dev/blog/the-path-to-openhands-v1 - Kubernetes deprecation policy (GA not removed within a major; beta 9 months or 3 releases; alpha any time): https://kubernetes.io/docs/reference/using-api/deprecation-policy/ - Spring Boot supported versions (minor 12 months, major 3 years, deprecate when feasible): https://github.com/spring-projects/spring-boot/wiki/Supported-Versions - Keycloak upgrading guide (review every upgrading guide between your version and the target): https://www.keycloak.org/docs/latest/upgrading/ - Flyway rolling back (undo is no substitute for backup; roll forward in production): https://documentation.red-gate.com/fd/rolling-back-138347144.html - Helm chart conventions (SemVer 2): https://helm.sh/docs/chart_best_practices/conventions/ - In this repository: docs/maintainers/releasing.md, releasing-sdk.md, docs/api/README.md, docs/api/DEPRECATION.md, docs/repository-structure.md, docs/engineering/FLYWAY-VERSIONING.md, docs/operations/README.md, deploy/README.md, deploy/helm/README.md, SECURITY.md, SUPPORT.md, GOVERNANCE.md, AGENTS.md, scripts/ci/openapi-breaking.mjs.