Release readiness plan

This plan closes the six blockers between the current code and a public 1.0 release. It also brings the general documentation and the four harness plugins into one release model.

Release target

• Public release: 1.0, MIT, Python 3.10 or newer.
• One product version used by the CLI, knowledge service, plugin manifests, packages, and docs.
• No public benchmark endpoint. Benchmarks are replicated locally from documented commands and local model servers.
• The four plugins share one architecture, one capability contract, and one behavior test suite. Host adapters only translate host APIs.

Current evidence baseline

• 442 tests pass; 57 environment-gated tests are skipped in the default run.
• SQLite and PostgreSQL 16 pass the knowledge contract. MySQL and MariaDB dialect contracts pass against a local MariaDB 10.5; CI runs MySQL 8.4 and MariaDB 11.4 service containers.
• v6 regression: 96/96 cells, 48/48 Auwai + Knowledge at 64/64, coverage 1.00, all parseable.
• Workflow probes: 256 agents at p99 192-261 ms on one SQLite service; 512 agents at p99 385-580 ms; findings and claims 12,800 each; facts stable.
• Local wheel install and release smoke pass on Python 3.10, 3.11, and 3.13.
• make lint, make doctor, make docs-check, and the plugin parity suite pass.

Blocker 1: versioned packaging and clean install

Work

1. Add a single VERSION source, for example auwai/version.py or VERSION. Use it in: - auwai --version; - knowledge_service health and startup output; - plugin manifests and generated bundles; - package metadata and docs.
2. Add pyproject.toml. - Distribution name: auwai-kernel (the CLI remains auwai). - requires-python = ">=3.10", MIT, README, classifiers. - Console entry point: auwai = auwai:main. - Package the kernel modules, schema/, SKILL.md, and references. - Keep ./auwai as the checkout wrapper for contributors.
3. Add optional extras, kept separate from the zero-dependency core: - postgres: psycopg[binary]; - mysql: PyMySQL; - queues: Redis, RabbitMQ, and Kafka clients.
4. Add build and release commands to Makefile: - make dist: wheel, sdist, plugin zip/tar bundles, SHA256SUMS; - make install-test: fresh venv, install wheel, run auwai doctor, index a fixture, run a full-read smoke, start the service; - make plugin-install-test: install each plugin into a temporary home.
5. Add a release workflow on v* tags: - build artifacts; - test the wheel in a clean Python 3.10 and 3.13 environment; - attach wheel, sdist, plugin bundles, checksums, and changelog; - publish only after the CI matrix is green.
6. Add auwai --version and auwai doctor --release output with version, schema version, Python, SQLite/FTS5, and plugin version.

Acceptance

• A clean machine with Python 3.10 or 3.13 installs the wheel and runs: auwai --version, auwai doctor, auwai index, auwai fullread plan, and a local knowledge-service smoke.
• The installed version and the plugin versions match.
• The checkout wrapper still works for contributors.
• No package installs optional database or queue clients unless requested.

Blocker 2: security review and deployment hardening

Work

1. Write docs/40-operations/security.md: - assets: source, findings, claims, facts, tokens, database; - trust boundaries: agent, plugin, MCP server, knowledge service, database, reverse proxy; - attacker capabilities: malicious repo, compromised agent, stolen token, network peer, malicious payload; - mitigations and residual risks.
2. Deployment guide: - bind the service to 127.0.0.1 by default; - require TLS at a reverse proxy for any non-loopback deployment; - token scopes and repository allowlists; - database user permissions and backups; - --backlog, request limits, timeouts, and log retention; - service user and filesystem permissions.
3. Security tests: - unauthenticated and wrong-token requests; - repo-scope bypass and cross-repo reads; - anonymous mode must be explicit; - token comparison and rotation; - malformed sync payloads, oversized payloads, and invalid event kinds; - path traversal in citation and chunk identifiers; - secret redaction, including multiline keys and private keys; - SQL injection probes through filters; - plugin hook command injection and raw-read policy vectors; - denial-of-service bounds for facts, findings, claims, and jobs.
4. Dependency and supply-chain checks: - core remains standard-library only; - optional extras are pinned and audited; - release artifacts are checksummed; - CI runs a dependency and license check.
5. Security sign-off checklist in the release ticket: - no critical or high findings; - medium findings documented with an owner; - deployment guide tested against a TLS reverse proxy.

Acceptance

• Security tests pass on SQLite and PostgreSQL.
• The service refuses non-loopback anonymous deployment unless explicitly allowed.
• The deployment guide has a working TLS reverse-proxy example.
• A written sign-off records residual risks.

Blocker 3: upgrade migrations for SQLite, PostgreSQL, MySQL, and MariaDB

Work

1. Add a formal schema-version layer to the knowledge service: - schema_migrations(version, name, applied_at, checksum); - a migration runner with --migrate, --check, and --migration-lock; - service startup refuses an unknown newer schema and names the required migration.
2. Convert the current ad hoc changes into named migrations: - 0001_initial; - 0002_claims; - 0003_fact_identity (fact_key, revision, timestamps, unique index); - 0004_agent_instruction_coverage if the coverage rule needs a schema marker.
3. SQLite: - use a table rebuild for changes that SQLite cannot alter in place; - preserve facts, findings, claims, reads, and sync events; - test a copy of a pre-v8 v6 knowledge database.
4. PostgreSQL: - add columns and indexes transactionally; - test upgrade from a pre-v8 schema with real facts and reads; - add a migration lock for multiple service processes.
5. MySQL and MariaDB: - use bounded VARCHAR keys and compatible index prefixes; - test upgrade from a pre-v8 schema; - verify the end and start quoting path.
6. Local ledger migrations: - add a schema_version meta key to .auwai/auwai.sqlite; - test old ledgers with facts, findings, reads, and sessions; - keep one database per repository and refuse a mismatched root.
7. Add a migration test harness: - create an old schema fixture for each backend; - seed facts, findings, claims, reads, and sync events; - run the new service; - compare row counts, current facts, coverage, and claims; - run the migration twice to prove idempotence; - restore a backup and verify rollback.

Acceptance

• Pre-v8 SQLite, PostgreSQL, MySQL, and MariaDB databases upgrade without data loss.
• Re-running migrations is a no-op.
• A failed migration leaves the database at its prior version.
• --check reports pending migrations without writing.

Blocker 4: one plugin architecture across all harnesses

Contract

"Identical function" means all four plugins expose:

• the same canonical Auwai skill and command text;
• the same MCP tool names, schemas, and behavior;
• the same knowledge-service default (sync --pull before, sync after);
• the same session and author environment (AUWAI_SESSION_ID, AUWAI_AGENT_ID);
• the same hook policy for session start, prompt nudge, raw-read denial, and stop sync;
• the same version and capability manifest.

Host-specific UI or install layout may differ. Behavior may not.

Architecture

1. Create extensions/plugin_common/core/: - SKILL.md; - commands/*.md; - agents/auwai-reader.md; - mcp.json template with all 17 tools; - hooks.json with canonical events; - hook.py, one policy engine used by every host; - capabilities.json with the required feature set.
2. Add one capacities manifest per host: - extensions/claude-code/adapter.json; - extensions/codex/adapter.json; - extensions/hermes/adapter.json; - extensions/opencode/adapter.json. Each maps canonical events and paths to host APIs.
3. Generate all four bundles from the shared core: - extend scripts/build_harness_plugins.py; - one VERSION and one capabilities.json; - no hand-copied skill or command files; - generated headers and checksums.
4. Add a unified installer: - python3 scripts/install_plugin.py --harness <name> --scope user|project; - --check, --remove, --dry-run; - same environment variables and knowledge defaults on every host.
5. Host adapters: - Claude Code: native plugin manifest, hooks, commands, agent, MCP. - Codex: native plugin manifest, skill, commands, agent, MCP. The adapter must use a Codex version with a working pre-tool hook. If the current Codex build cannot enforce the guard, the plugin is not release ready for that build; either require a newer Codex or provide a supported wrapper that enforces the same decision. Do not ship an advisory guard as "identical". - Hermes: native plugin and shell-hook bridge, same policy engine. - OpenCode: native plugin guard and MCP, plus skill/command/agent equivalents where the host supports them. If OpenCode lacks a native surface, implement the equivalent command/tool in the plugin API rather than dropping the capability.
6. Add tests/test_plugin_parity.py: - compare skill hash and command set across all four bundles; - compare MCP tool names, schemas, and descriptions; - feed the same hook payload vectors to every adapter and assert identical allow, deny, nudge, and sync decisions; - compare environment defaults, version, and capability manifest; - install each plugin into a temporary home/project and validate the host manifest; - run the same CLI/MCP smoke against each installed plugin.
7. Publish a generated capability matrix in docs/40-operations/plugins.md. A missing required capability fails the release gate; it is not a footnote.

Acceptance

• make plugins is deterministic and produces four bundles with the same canonical skill, commands, MCP tools, env defaults, and hook decisions.
• Parity tests pass for all four hosts.
• The hook decision vectors are identical, including the raw-read denial and stop-sync paths.
• No bundle contains hand-edited copies of shared files.
• A plugin installed from the release artifact passes the same smoke test as the checkout bundle.

Blocker 5: local benchmarking, no public endpoints

Decision

Auwai will not publish or depend on a public benchmark endpoint. All benchmarking is local and reproducible.

Work

1. Remove public endpoint defaults from benchmark scripts: - run_case_study_v6.py, evidence_v6.py, and related runners must require AUWAI_BENCH_URL or --endpoint; - fail with a clear message if no local endpoint is configured; - remove public benchmark hostnames from scripts, fixtures, and docs except as historical notes that are explicitly marked.
2. Add docs/70-benchmarks/local-replication.md: - prerequisites: Python, SQLite/FTS5, optional local model server; - supported local protocol shapes: Anthropic Messages, OpenAI Chat, OpenAI Responses; - model examples and context-window settings; - fixture repositories and where to place them; - exact commands for the v6 matrix, workflow suites, ledger tests, and CLI probes; - environment variables and config examples; - expected durations and hardware notes; - scoring, summarize_v6.py, rubric_audit.py, and the hard gates; - troubleshooting: model not found, queueing, context limits, protocol mismatches.
3. Add a deterministic local/mock mode: - a mock OpenAI/Anthropic server that replays recorded fixture answers; - used by CI for plumbing and parser tests; - never presented as a model-quality benchmark.
4. Add benchmarks/local/run_v6.sh and benchmarks/local/run_workflows.sh: - all arguments explicit, no hidden public host; - print the endpoint and model before running; - refuse to start without a local endpoint.
5. Update V6-PLAN.md, CASE_STUDY_V6.md, and WORKFLOW_BENCHMARKS.md to describe local replication and remove any instruction that implies a hosted benchmark service.
6. Add a docs test: - fail if benchmark scripts or docs contain a public benchmark hostname; - fail if a benchmark command depends on a network endpoint without a local override.

Acceptance

• A new user can run a local benchmark from the documented commands with no Auwai-hosted endpoint.
• CI runs the deterministic mock path without network.
• The docs name the model, endpoint shape, fixtures, expected gates, and failure modes.
• No public benchmark hostname is a default or requirement.

Blocker 6: CI on clean runners

Work

1. Make the existing ci.yml a required matrix: - Python 3.10, 3.11, 3.12, 3.13; - make lint, make doctor, full unit suite; - core install from the built wheel.
2. Add storage jobs with service containers: - PostgreSQL 16; - MySQL 8.4; - MariaDB 11.4; - run the backend contract tests and migration tests with the correct URLs.
3. Add plugin jobs: - build all four bundles; - run parity tests and hook decision vectors; - validate generated manifests; - install into temporary homes where the host CLI is available; - run a mock host smoke where it is not.
4. Add packaging jobs: - build wheel and sdist; - install into a clean venv on Python 3.10 and 3.13; - run auwai --version, doctor, index, and a local-service smoke; - verify plugin version equality.
5. Add docs jobs: - Markdown link check; - local-benchmark no-public-endpoint check; - capability matrix check; - CHANGELOG.md version check.
6. Add a release workflow: - triggered by v* tags; - requires all required checks; - builds checksummed artifacts; - creates the GitHub release; - publishes no artifact if a gate fails.
7. Protect the release branch: - required checks from all jobs; - no direct release without the tag workflow.

Acceptance

• A clean checkout passes every required job.
• The external storage jobs run on every pull request, not only manually.
• The wheel install job does not use the source checkout.
• The tag workflow reproduces the release artifacts and checksums.

General documentation update

Update these pages as part of the release, not after it:

• README.md: current status, version, install from release, plugin matrix, local benchmark link, security link.
• docs/README.md: release-readiness and local-benchmark links.
• docs/40-operations/install.md: wheel install, checkout install, optional extras.
• docs/40-operations/plugins.md: generated capability matrix, identical behavior contract, Codex hook support, OpenCode surface.
• docs/40-operations/knowledge-service.md: current API, findings, claims, fact versioning, sessions, backlog, migrations, TLS.
• docs/40-operations/security.md: threat model and deployment checklist.
• docs/50-development/contributing.md: release, CI, plugin generation, docs checks.
• docs/50-development/release.md: version bump, tag, artifacts, checksums.
• docs/70-benchmarks/*: local replication, no public endpoint, mock mode, current results.
• docs/60-roadmap/release-readiness.md: this plan.
• CHANGELOG.md: one 1.0 entry and migration notes.

Stale statements to remove or correct:

• "PostgreSQL was not live-tested."
• "OpenCode Go returns 402" as a current limitation.
• "Codex guard hook is included but not enforced" as an accepted final state.
• Any benchmark instruction that points at a public host.

Add a docs check for private or public benchmark hostnames. Historical results may name a host only when clearly marked historical and without a runnable command.

Sequencing

Phases 2, 4, and 5 can run in parallel. The likely critical path is packaging and plugin parity, not the core reading engine.

Release gate

Ship 1.0 only when all are true:

• [x] Clean wheel install on Python 3.10 and 3.13.
• [x] auwai --version, doctor, index, full-read, and local service smoke pass.
• [x] All four plugin bundles verify and pass parity tests.
• [x] No plugin has an advisory-only guard; Codex and OpenCode meet the same decision vectors. Codex requires the host /hooks trust review.
• [x] make lint, full unit suite, and all four storage backends pass.
• [x] Pre-v8 migration tests pass on all four storage backends. MySQL and MariaDB dialect coverage is local; CI runs the 8.4 and 11.4 images.
• [x] Security checklist signed; no critical or high findings.
• [x] Local benchmark replication is documented and runs without a public host.
• [x] CI is green on a clean checkout; release workflow builds checksummed artifacts. The Auwai main run passed every required job, including the macOS FSEvents job and the clean wheel installs.
• [x] README, install, plugins, knowledge service, security, benchmarks, and changelog reflect the released version.
• [x] v6 regression still reports 96/96 and 48/48 Auwai cells at 64/64.

Risks and rollback

• Packaging layout risk: the scripts are top-level modules. Use a package mapping that preserves imports; test the installed wheel, not only the checkout.
• Plugin parity risk: a host may not expose a pre-tool hook. Treat that as a release blocker for that host, not as a documentation caveat.
• Migration risk: SQLite table rebuilds and MySQL index prefixes can fail. Test on copies, back up first, and make the runner resumable.
• Documentation drift: generate the capability matrix and plugin manifests; do not hand-edit copies.
• Benchmark drift: require explicit local endpoints; add a CI grep for public benchmark hosts.
• Rollback: keep the previous wheel, plugin bundles, and database backups; the migration runner refuses downgrades and reports the exact required version.