kontextual-engine/docs/first-release-readiness.md

# First Release Readiness

Date: 2026-05-14

Target posture: `0.1.0` controlled preview. This release can be good to go
when it is honest, reproducible, observable, and recoverable. It does not need
to pretend to be a full ECM or certified CMIS repository.

## Release Scope

In scope:

- native asset registry, metadata, relationship, retrieval, transformation,
  workflow, service API, blob, S3-backend, and observability foundations,
- profiled CMIS Browser Binding subset for controlled integrations,
- OpenCMIS selected baseline for `repository-type` and `object-content`,
- explicit unsupported flags for out-of-scope CMIS capabilities,
- State Hub registered workplans and evidence documents.

Out of scope for `0.1.0`:

- AtomPub and Web Services bindings,
- full CMIS SQL, checkout/checkin/PWC, policy mutation, retention/hold,
  renditions, and broad filing mutation,
- full ECM/records-management semantics,
- formal CMIS certification claim.

## Go / No-Go Gates

| Area | Gate | Current state |
| --- | --- | --- |
| CMIS read-side contract | Query, navigation, relationship, ACL, and change-token contracts are release-stable or explicitly waived. | `KONT-WP-0016` implemented locally; full release verification still required. |
| Tests | Full suite passes in the project venv. | `.venv/bin/python -m pytest -q` passed: `166 passed`, `15 skipped`; advisory performance drift warnings recorded. |
| CMIS evidence | OpenCMIS selected baseline completes with no unexpected findings. | `run-20260513T223537Z` completed; only local HTTP warning remains. |
| Transport | Released CMIS access points are served behind HTTPS. | Required deployment gate; local loopback warning is accepted only for harness runs. |
| Capability honesty | Scorecard, unsupported catalog, and examples match behavior. | Updated for `appendContentStream` and WP-0016 read-side contract; final doc review required. |
| Packaging | Version, dependencies, optional extras, and install smoke are checked. | `pyproject.toml` is already `0.1.0`; build/install smoke still required. |
| Configuration | Storage backend, S3 settings, local blob path, and environment defaults are documented. | Existing docs cover backends; release runbook should point to them. |
| Data safety | Blob cleanup, backups, restore path, and migration posture are documented. | Cleanup exists; backup/restore release notes still needed. |
| Security | Actor headers, access-point profiles, secrets, and dependency/license review are done. | Profile model exists; release security review still required. |
| Operations | Health checks, logs, performance history, and known warnings are documented. | Health and performance monitor exist; release runbook still needed. |
| State | State Hub consistency check passes after release docs/workplan updates. | Passed after WP-0015 registration. |

## Known Accepted Limitations

- CMIS Browser Binding is the supported external CMIS protocol surface.
- CMIS multifiling remains projection-only.
- CMIS append is implemented as whole-object append through deduplicating
  representation storage; chunk-level blob composition is deferred.
- Local OpenCMIS loopback runs warn about HTTP. This must not be carried into
  production-facing access points.
- Performance drift warnings from pytest are advisory unless repeated under a
  quiet system baseline; the current run flagged several CMIS API tests.

## Release Procedure

1. Run `.venv/bin/python -m pytest -q`.
2. Run the OpenCMIS selected baseline through `guide-board` and persist the
   evidence document.
3. Run State Hub consistency check and ensure workplans are registered.
4. Run packaging smoke: build wheel/sdist and import `kontextual_engine` from a
   clean install.
5. Review security/configuration: HTTPS termination, profile exposure, secrets,
   local/S3 blob backend settings, and dependency licenses.
6. Update `CHANGELOG.md` or release notes with capabilities, known limitations,
   and accepted warnings.
7. Tag the release only after the gates above are green or explicitly waived.

## Release Decision

The current foundation is close to a controlled `0.1.0` preview. With the
`KONT-WP-0016` read-side contract settled locally, the remaining release work is
mainly discipline around repeatable verification, packaging, deployment
posture, and clearly documented limits.