# Public Release Readiness

Date: 2026-06-30

## Current Read

CodeAlmanac's local Python implementation has public-beta gate coverage. Clean
wheel install, current-head wheel/sdist package rehearsal, real Codex ingest,
real Claude ingest, real Codex app-server harness dogfood, real Claude SDK
harness dogfood, real non-toy source-shape ingest, real sync, and final viewer
browser proof now have evidence. Slice 93 also aligns GitHub CI, package-check,
disabled publish placeholders, and issue/PR templates with the Python/PyPI
surface.

The gate audit in `docs/python-port/public-beta-gate-audit.md` is the current
release-readiness checkpoint. Slice 70 passed the remaining lifecycle
prompt-quality dogfood and fixed the user-state path issue it exposed. Slice 71
reran current-head package/install proof after that change. Remaining
public-release work is release operations: PyPI credentials, version/changelog,
and the human publish decision.

## Public Beta Gate

| Area | Required Evidence |
|---|---|
| Fresh install | Build a wheel, install it into a clean environment, run `codealmanac --help`, `init`, `search`, `show`, `health`, `serve`, and `jobs` without relying on editable checkout state. |
| Package metadata | Wheel metadata includes README and Apache-2.0 license text; package data includes server assets, manual files, and prompts. |
| Public docs | `README.md` describes only the Python `codealmanac` local surface: no Node/npm install path, no `almanac` alias, no hosted dashboard happy path. |
| Release guide | `RELEASE.md` describes the Python/PyPI release path, clean artifact install smoke, and no npm/Node release flow. |
| GitHub automation | GitHub workflows and templates use Python 3.12, uv, pytest, ruff, package build, `twine check`, and PyPI language, with no npm/Node/npx automation path. |
| Local wiki read path | A new repo can initialize, search, show a page, inspect topics, run health, and serve the local viewer. |
| Lifecycle write path | Real Codex or Claude ingest writes useful wiki changes under the configured Almanac root and leaves readable `jobs logs`. |
| Sync path | A synthetic and a real local transcript can be discovered, claimed, ingested, and skipped on a second run. |
| Safety | Lifecycle runs reject non-wiki mutations, preserve dirty app files, and record harness events before terminal errors. |
| Viewer | Browser dogfood checks desktop and mobile routes for overview, page, topic, search, file refs, and no horizontal overflow. |
| Contract guards | Tests reject hosted verbs, compatibility aliases, public SDK/MCP modules, and stale README install language. |
| Release command | `codealmanac update --check` reports a coherent package-manager plan from non-editable pip and uv-tool installs. |

## Stop Doing

- Do not add hosted verbs, login/connect/upload, SDK, MCP, or aliases.
- Do not add a frontend build step until the static viewer becomes the harder
  path.
- Do not add more provider transports for parity. Codex app-server is now the
  default Codex path because normalized harness event completeness is required;
  further transport work should answer a concrete product gap.
- Do not add a source pool or candidate object without a concrete product
  workflow that needs it.

## Evidence So Far

- Slice 56 passed clean wheel install from a built wheel, package metadata and
  package-data inspection, public README contract tests, and local read/viewer
  smoke checks.
- Slice 57 passed real Codex ingest through `IngestWorkflow` and
  `CodexCliHarnessAdapter` in an isolated temp repo. The first run exposed
  broken page links from over-eager entity wikilinking. Prompt/manual guidance
  now forbids unresolved page links, and the second real Codex run produced a
  health-clean page for the same source shape.
- Slice 57 also removed default empty-topic health noise from newly initialized
  starter wikis.
- Slice 58 passed real Claude ingest through `IngestWorkflow` and
  `ClaudeCliHarnessAdapter` in an isolated temp repo. The run produced a
  health-clean page, updated topics, and left readable public CLI `jobs logs`,
  `search`, `show`, and `health --json` output.
- Slice 59 passed real foreground sync against a temp Codex transcript. Sync
  discovered the transcript, started a real Claude-backed ingest, advanced the
  ledger to done, skipped the same transcript as unchanged on the second
  status run, and left public CLI `sync status`, `jobs logs`, `jobs show`,
  `search`, `show`, and `health --json` output readable.
- Slice 60 passed browser-harness proof over a live temp `serve` instance.
  Overview, page, topic, search, and file-reference routes rendered in desktop
  Chrome with no horizontal overflow, and the mobile `390x844` page route also
  rendered without horizontal overflow.
- Slice 61 passed final package rehearsal. Built wheel and sdist artifacts,
  inspected metadata/package data, installed both into clean Python 3.12.9
  environments, ran installed CLI smoke checks for `init`, `search`, `show`,
  `topics`, `health`, `jobs`, `sync status`, `doctor`, and `serve`, and
  confirmed Python 3.11 is rejected by `requires-python`.
- Slice 61 also updated package metadata to SPDX `Apache-2.0` plus
  `license-files = ["LICENSE.md"]`, removing the setuptools license-table
  deprecation warning.
- Slice 62 replaced the stale npm release guide with the Python/PyPI release
  guide, added PyPI-facing project metadata, verified wheel/sdist metadata with
  `twine check`, and extended public-contract tests so npm release commands do
  not return.
- Slice 63 fixed a real local dogfood hygiene bug: `doctor` and read commands
  no longer create a derived-only `almanac/index.db` for a registered workspace
  whose configured root has not been built. Registry status, root discovery,
  and index opening now require source wiki markers rather than directory
  existence.
- Slice 64 corrected the public README's scaffold tree after live `init`
  dogfood showed it mixed initialized wiki source files with later runtime
  state. The README now separates init-created source files from derived
  `index.db`/`jobs/` state, and public-contract tests guard the distinction.
- Slice 65 dogfooded the README quickstart in a fresh temp repo. The old
  `search "auth"` example returned zero results after `init`; the quickstart
  now searches `getting`, which returns the starter `getting-started` page.
- Slice 66 checked README lifecycle examples against the source abstraction.
  The local-file ingest example now uses `README.md`, which resolves as a real
  file in this repo, while the GitHub PR shorthand remains parser/source
  supported.
- Slice 67 made the next-agent brief an executable continuation contract.
  Public-contract tests now require the brief's current-state section to track
  the newest `docs/python-port/slice-N-*.md` file.
- Slice 68 audited every public beta gate in
  `docs/python-port/public-beta-gate-audit.md` and added a public-contract
  test that forces the audit to cover every row in the release gate table.
- Slice 69 reran current-head package rehearsal. Wheel and sdist artifacts
  passed `twine check`, metadata/package-data inspection, clean Python 3.12.9
  installs, installed CLI smoke, live `serve` HTTP checks, and installed
  `update --check`.
- Slice 70 ran real Claude-backed `codealmanac ingest` against a focused temp
  repo containing CodeAlmanac source-runtime, filesystem adapter, ingest
  workflow, prompt, and live-agreement files. It created
  `source-runtime-flow.md`, left health clean, and produced readable job logs.
- Slice 70 also moved default user/global state from `~/.almanac/` to
  `~/.codealmanac/`, while preserving the repo wiki root as `almanac/`.
- Slice 71 reran current-head package proof after the slice 70 state-path and
  README changes. Wheel and sdist artifacts passed `twine check`, package
  inspection confirmed the updated README/state-root metadata and package data,
  clean Python 3.12.9 installs passed installed CLI smoke, `serve` HTTP checks
  passed, and both artifacts wrote registry state under `~/.codealmanac/`.
- Slice 136 ran the default real Codex app-server harness through
  `IngestWorkflow`. The first run exposed whitespace-only text deltas from the
  real app-server; the provider edge now drops blank deltas before constructing
  `HarnessEvent`, and the rerun finished `done`, created a page, search found
  it, and health was clean.
- Slice 137 ran the default real Claude SDK harness through `IngestWorkflow`.
  The run used real HOME/Claude auth with a temp registry and temp repo,
  finished `ingest-20260701163930-cf193a0e` as `done`, created
  `release-package-smoke.md`, search found the page, health was clean, and the
  normalized event stream included provider session, text, text deltas, tool
  use/results, context usage, warning, and done.
- Slice 138 reran current-head package proof after the default rich harnesses
  were dogfooded. `uv build` produced `0.1.0.dev0` wheel and sdist artifacts,
  `twine check` passed, package inspection found expected metadata/resources,
  clean uv-managed Python 3.12.9 installs from both artifacts passed installed
  CLI smoke, `serve` returned `/api/overview`, and both smokes wrote registry
  state under isolated `~/.codealmanac/`.

## Next Useful Pressure Tests

1. Prepare release operations: version/changelog, PyPI credentials, and human
   publish decision.
2. Rerun package/install smoke again only if metadata, README, prompts, manual,
   server assets, or installed behavior change before publishing.
