RELEASE_CHECKLIST.md

# Release Checklist

## Local Qualification: 2026-09-13

Status: release candidate, not approved for a general production launch.

- 215 local automated tests cover ERP/CRM evidence checks, concurrent advisor-memory writers
  and live-connection policy preservation with a configured secret provider.
- Codex plugin validation and all 11 changed skill validations pass.
- The new ERP/CRM skill and updated SQL performance advisor skill validate.
- ERP/CRM coverage includes 13 review profiles and 43 catalog checks;
  invalid, cross-system, cross-version, stale and conflicting evidence are tested.
  Dataverse trace and Salesforce plan collectors have protocol tests; real
  customer-tenant qualification and exhaustive vendor certification are not implied.
- Dependency audit reports zero known vulnerabilities.
- A standalone archive with a dependency lockfile and SHA-256 is generated by
  `npm run release:package`; its contents are checked against the 128-file budget.
- Dependency installation from an extracted archive succeeds with `npm ci --ignore-scripts`.
- PostgreSQL 18 live EXPLAIN smoke succeeds; constant queries must not generate
  fabricated index findings or fixed cost estimates.
- Windows/Linux Node 22/24 CI is configured; hosted matrix execution is still pending.
- Isolated Codex install/update, clean installed-runtime invocation, live SQL Server
  plan capture/error cleanup and a PostgreSQL measured benchmark fixture pass locally.
- Audit concurrency, memory concurrency, interrupted SQLite transaction recovery,
  checked legacy import and database-profile scope guards are tested.

Launch gates still open:

- Current source includes scoped advisory-case persistence, reviewed outcomes,
  repeated benchmark checks and release-bound qualification receipts. Recorded
  approval references are not authenticated signatures or execution authorization.
- Aivana GmbH is the user-specified publisher with website www.aivana-gmbh.ai.
  Published privacy and terms URLs could not be verified and remain launch blockers.
- Plugin Eval found missing legal URLs, skill-trigger warnings and static text-budget
  pressure. Its local-folder estimate is not measured Codex usage or a runtime score.

- Exercise installation and skill invocation in a clean Codex profile on a second
  machine, including dependency setup and plugin updates.
- Qualify additional SQL Server versions/authentication modes beyond the locally
  tested Windows-authenticated SQL Server instance.
- Validate provider authentication, permissions, sampling and API versions in
  real Dataverse/Salesforce customer tenants. Other vendors currently use imports.
- Production readiness without deployment credentials intentionally fails:
  live-connection enforcement and migration signing are not configured in this checkout.
- Advanced advisor scores and predictions are predominantly deterministic heuristics;
  public claims must distinguish these from measured results and trained AI models.
- Public marketplace submission, release version/tag, and publication are pending.

## Optional live write rehearsal

Use `npm run release:qualify -- --live-postgres --live-write-rehearsal`
or `npm run release:qualify -- --live-sqlserver --live-write-rehearsal`.
`--live-write-rehearsal` must accompany `--live-postgres` and/or `--live-sqlserver`;
both engine flags may be supplied together. Use authorized connection settings.
The rehearsal runs synthetic INSERT, UPDATE and DELETE rollback checks plus
constraint failure recovery checks in isolated sessions, using temporary tables
only. It does not write customer tables, authorize production migrations, or
qualify backup/restore procedures. Keep unexecuted checks `not_run` until evidence
from the actual run is available.

Local qualification on 2026-09-13 activated `pg_stat_statements` 1.12 on PostgreSQL
18 in database `postgres`, with an explicitly authorized restart. The installed
plugin collected live statistics successfully. Other installations still require
their own preflight; no automatic restart, statistics reset or preload overwrite.

## Isolated migration workflow

Add `--live-migration-workflow` to one or both live-engine flags on an authorized
test instance with database-create/drop permission. A random disposable database
is created per engine. The installed plugin must reject absent, invalid and
tampered signatures before any executeSql call, apply a valid index, roll it back,
and report actual SQL failures without claiming success. Independent catalog and
fixture-row comparisons verify the result. Cleanup drops only the created database,
without forced connection termination; interrupted runs can require manual cleanup.

Signatures bind SQL, engine, database, schema, actor, profile, environment and
expiry. They prove artifact integrity, not verified human approval or IdP identity.
Only scoped lab index operations are enabled. `productionMigrationQualification`
remains `not_run` and `productionQualified` remains false after these tests.

## Optional real-tenant qualification

### Pilot acceptance protocol

Before a pilot, record the customer's permission, exact system/version/customization
scope, workload ID, agreed control definition and groups, and the release archive
SHA256. Use a nonproduction or otherwise explicitly authorized read-only data path.
Record a manual diagnosis baseline and target completion time before measuring the
advisor. Do not reconstruct a favorable baseline after seeing the results.

For every case, retain input references, tool failures/retries, elapsed human time,
review corrections and outcome (confirmed/false_positive/inconclusive). Count all
attempts, including blocked or inconclusive cases. Confirm only after both technical
and business checks pass at verification and follow-up. Compare completion time and
false-positive/correction rates against the predeclared baseline. Do not turn the
synthetic database fixture into a claim of customer ROI or market validation.

Stop on scope/permission breaches, mismatched business results or unexpected writes.
Publish only aggregate, authorized results with sample sizes and limitations. The
protocol is implemented as a documented pilot procedure; no real pilot is claimed.

### Tenant collection

Run `npm run release:qualify -- --live-dataverse` or `--live-salesforce` only with
authorized access to the actual tenant context. Keep external tenant tests
`not_run` until actual tenant evidence is available; local fixtures and protocol
tests do not qualify these gates. Do not invent URLs or credentials.
In addition to collector URL, SYSTEM_ID and ACCESS_TOKEN,
set the matching CODEXDB_DATAVERSE_ or CODEXDB_SALESFORCE_ prefix with PRODUCT_VERSION,
ENVIRONMENT and API_VERSION. Dataverse also requires SLO_MS; Salesforce requires
QUALIFICATION_SOQL for a nonexecuting explain request. These runs read one bounded
page and prove only that collection path, not full vendor certification. No tenant
collection is attempted without its explicit flag.

Do not manufacture receipts for external gates. `release_qualification_matrix`
requires the candidate archive SHA256 and rejects wrong-release, stale or duplicate
receipts. Its eight gates remain on hold until actual evidence is supplied.

## Deployment Checklist

- [ ] `npm install` completes on a clean checkout.
- [ ] `npm test` passes.
- [ ] Repository root contains `.codex-plugin/plugin.json` for marketplace scanning.
- [ ] `node --test tests/submission-artifact.test.js` validates the required root manifest and the 128-file submission limit.
- [ ] `node --test tests/release-contracts.test.js` validates autonomous and AI USP contracts.
- [ ] `npm audit --audit-level=moderate` passes.
- [ ] `npm run readiness` has no unexpected blockers.
- [ ] Production environments set `CODEXDB_REQUIRE_LIVE_CONNECTION=true`.
- [ ] Migration signing key is configured outside source control.
- [ ] PostgreSQL or SQL Server connection is configured for live evidence.
- [ ] Optional Prometheus, Grafana, pgvector, and Neo4j connectors are configured when used.
- [ ] `runtime/tool-contracts.json` matches the shipped disruptive USP tools.
- [ ] `demos/enterprise-ai-usp-scenarios.json` covers marketplace demo flows.
- [ ] `demos/KILLER_DEMOS.md` covers the four curated headline demos.
- [ ] `node --test tests/killer-demos.test.js` validates demo commands and expected decisions.
- [ ] `MARKETING.md` includes positioning, ICP, personas, USP matrix, competitive framing, listing copy, FAQ, packaging narrative, and launch blurb.
- [ ] `demos/SALES_PLAYBOOK.md` includes discovery, qualification, demo flow, objection handling, follow-up email, and pilot success criteria.
- [ ] `node --test tests/marketing-docs.test.js` validates marketing and sales coverage.
- [ ] Secrets are redacted in tool output and audit logs.
- [ ] Release notes in `CHANGELOG.md` match the shipped version.