Public Beta Gate Audit
Date: 2026-06-30
Verdict#
CodeAlmanac's local Python implementation has public-beta gate coverage. Slice 70 ran the remaining real lifecycle dogfood pass against a non-toy project source shape and fixed the user-state path issue it exposed. Slice 71 reran current-head package/install proof after that change. Slice 93 aligned GitHub CI, package-check, disabled publish placeholders, and issue/PR templates with the Python/PyPI surface. Slice 138 reran current-head package/install proof after the default rich Codex and Claude harnesses were dogfooded. Remaining work is release operations: PyPI credentials, versioning, changelog, and the human publish decision.
Gate Audit#
| Area | Status | Evidence | Remaining Risk |
|---|---|---|---|
| Fresh install | Ready | Slice 71 built current-head wheel and sdist artifacts into /tmp/codealmanac-release-slice71, installed each into clean uv-managed Python 3.12.9 environments, and ran installed codealmanac --help, init, search, show, topics, health, jobs, sync status, doctor, serve, and update --check. Slice 138 repeated that proof from current dev HEAD with 0.1.0.dev0 wheel and sdist artifacts under /tmp/codealmanac-release-slice138; both clean uv-managed Python 3.12.9 installs passed installed CLI smoke and wrote registry state under isolated ~/.codealmanac/. |
No current implementation blocker; final publish still needs the human release decision. |
| Package metadata | Ready | Slice 71 ran uv build, uvx twine check, wheel metadata inspection, sdist inspection, and package-data assertions for README, Apache-2.0 license metadata, license file, server assets, manual files, prompts, and core/paths.py. Slice 138 reran uv build, twine check, and package-data inspection from current dev HEAD; wheel metadata reported name codealmanac, version 0.1.0.dev0, Requires-Python: >=3.12, Apache-2.0, README text with ~/.codealmanac/, and expected server/manual/prompt/setup resources. |
No current implementation blocker; re-run if package metadata changes before publish. |
| Public docs | Ready with guard | tests/test_public_contract.py rejects Node/npm install language, almanac aliases, hosted dashboard language, absorb, stale README examples, and old ~/.almanac user-state language. Slices 64-66 dogfooded README scaffold, quickstart, and lifecycle source examples. Slice 70 documents ~/.codealmanac/ as the user state root. |
Future docs edits must keep the public-contract guard current. |
| Release guide | Ready with guard | Slice 62 replaced the npm release guide with the Python/PyPI release flow and added public-contract tests rejecting npm release commands. | Final publish still needs the human release decision and PyPI credentials. |
| GitHub automation | Ready with guard | Slice 93 replaced Node/npm CI with Python 3.12 plus uv, pytest, ruff, CLI smoke, and diff hygiene. Package check now runs uv build --out-dir dist and uvx twine check dist/*. The disabled publish workflow names future PyPI policy instead of npm tokens, and GitHub templates ask for Python/CodeAlmanac details. |
The publish workflow remains intentionally disabled until PyPI credentials, Trusted Publishing, and release provenance are decided. |
| Local wiki read path | Ready | Slice 61 clean-installed artifacts ran init, search, show, topics, health, jobs, sync status, doctor, and serve. Slices 64 and 65 dogfooded the README init/search/read path in fresh temp repos. Slice 138 repeated installed wheel/sdist CLI smoke and served /api/overview plus /assets/viewer/main.js. |
No current blocker; rerun clean install smoke only if package metadata, README, prompts, manual resources, server assets, or installed behavior changes before publishing. |
| Lifecycle write path | Ready | Slice 57 ran real Codex ingest and fixed prompt/manual guidance after broken wikilinks. Slice 58 ran real Claude ingest and produced a health-clean wiki page with readable jobs logs. Slice 70 ran real Claude-backed codealmanac ingest against a focused temp repo containing 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 136 ran the default real Codex app-server harness through IngestWorkflow, fixed blank text-delta handling, and reran to a done run with clean health. Slice 137 ran the default real Claude SDK harness through IngestWorkflow, produced release-package-smoke.md, recorded normalized provider/tool/context events, and left health clean. |
More real-project dogfood will keep improving prompts, but no current implementation blocker remains for public beta. |
| Sync path | Ready | Slice 59 discovered a real temp Codex transcript, claimed it, ran real Claude-backed ingest, advanced the ledger, skipped unchanged transcript content on the second status run, and left CLI readback readable. | More transcript-provider diversity can improve confidence later, but the required local sync path has evidence. |
| Safety | Ready | Ingest/garden workflow tests, lifecycle mutation policy tests, harness failure-log tests, and slice 54 dogfood prove non-wiki mutation rejection, dirty app file preservation, and harness event recording before terminal errors. | Continue testing any new lifecycle writer or mutation path against the same safety invariant. |
| Viewer | Ready | Slice 60 browser-harness checked live serve desktop overview, page, topic, search, and file routes plus mobile page route with no horizontal overflow. |
Future visual changes still require browser-harness. |
| Contract guards | Ready | Public-contract tests reject hosted verbs, compatibility aliases, public SDK/MCP modules, stale README install language, stale release guide language, stale next-agent brief slice numbers, and old user-state path language. They also pin AppConfig() default registry/config paths under ~/.codealmanac/. |
Keep adding contract tests when a product boundary becomes user-visible. |
| Release command | Ready | Slice 48 dogfooded non-editable pip and uv-tool installs. codealmanac update --check reports package-manager plans, and editable/source installs refuse mutation with a local development fix. Slice 138 installed wheel and sdist artifacts and observed update --check --json returning status: "ready" with a uv-tool foreground update command. |
Scheduled update automation remains intentionally out of scope until notifier cadence, dismissal, and release-channel policy exist. |
Next Release Work#
- Choose the release version and changelog.
- Confirm PyPI credentials and publish ownership.
- Rerun package/install smoke if any package data, README, prompt, manual, or server asset changes before publishing.