From ef053b58b431de7cecd2a03f534d0757293a0234 Mon Sep 17 00:00:00 2001 From: krahd Date: Sat, 9 May 2026 14:15:14 -0300 Subject: [PATCH] Sanitise status and release gate docs --- STATUS.md | 109 +++++++++-------------------------- docs/RELEASE_CRITERIA_1_0.md | 8 ++- 2 files changed, 33 insertions(+), 84 deletions(-) diff --git a/STATUS.md b/STATUS.md index 43397e2..5f46cb3 100644 --- a/STATUS.md +++ b/STATUS.md @@ -1,6 +1,6 @@ # BatLLM Status -Last updated: 2026-05-08 20:35 +Last updated: 2026-05-09 14:13 ## Project Purpose @@ -77,91 +77,38 @@ The codebase is currently aligned on `modelito==1.4.0` and now uses structured r ## Recent Changes -- Warmup timeout wiring completed across config defaults, service CLI, and Ollama config UI. -- Structured readiness path uses `ensure_model_ready_detailed()` and checks `ReadinessResult.success` in UI flows. -- Saved-session payload now includes `llm_metadata`; analyzer now exposes this in a dedicated `Model` inspector tab. -- Focused test coverage added for warmup timeout persistence and readiness success/failure handling. -- Homebrew packaging test collection fixed by ensuring repo-root path bootstrap happens before repo-root imports. -- Root `requirements.txt` now includes `requests==2.32.4` to remain a superset of Homebrew runtime requirements. -- Legacy start/stop UI test updated to match the warmup-timeout argument now passed at service start. -- Repaired a reintroduced import-order regression in `src/tests/test_homebrew_packaging.py` and `src/tests/test_multiplatform_support.py` so pytest collection remains stable. -- Ran packaging smoke validation for release bundles and Homebrew formula generation. -- Hardened the same two test modules to use dynamic post-bootstrap imports so formatter/isort reordering cannot reintroduce collection-time import failures. -- Added `src/util/packaging_smoke.py` plus `validate_packaging_smoke.py` for a unified packaging smoke-validation command. -- Added `src/tests/test_packaging_smoke.py` and contributor docs for the new packaging smoke command. -- Hardened `src/llm/service.py` stop logic so force-kill escalation only applies to Ollama processes that BatLLM has already terminated, reducing the risk of touching unrelated listeners. -- Added targeted regression tests for the stop-service race/kill path in `src/tests/test_multiplatform_support.py`. -- Extended `src/util/packaging_smoke.py` with an opt-in installer smoke mode that extracts the current-platform release bundle, executes `install-batllm.*`, and verifies the expected `.venv_BatLLM` Python executable. -- Added installer-smoke helper coverage in `src/tests/test_packaging_smoke.py`. -- Documented the installer smoke command path in `docs/CONTRIBUTING.md`. -- Added an opt-in Homebrew install-level smoke mode in `src/util/packaging_smoke.py` that performs install/test/uninstall through a temporary local tap, compatible with current Homebrew policy. -- Updated `docs/CONTRIBUTING.md` and `packaging/homebrew/README.md` to document the local-tap requirement for Homebrew install smoke. -- Regenerated generated API docs under `docs/code/` with `doxygen docs/code/dox_config.properties`. -- Narrowed `src/llm/service.py` startup orchestration by delegating the no-config path directly to `modelito.start_service()` instead of falling back to the local startup branch. -- Added regression coverage in `src/tests/test_multiplatform_support.py` for the no-config startup delegation path. -- Narrowed default-path service-state orchestration by delegating `inspect_service_state(None)` directly to `modelito.inspect_service_state(None)`. -- Hardened Homebrew install smoke to report a clear error when `brew` is unavailable on `PATH`. -- Added regression coverage for the new service-state delegation path and missing-`brew` handling. -- Ran a comprehensive repository audit pass across working tree state, core documentation, source and packaging scripts, and automated verification commands. -- Updated `docs/code/dox_config.properties` `PROJECT_NUMBER` from `0.2.3` to `0.3.4` and regenerated `docs/code/` so generated API docs match the current repository version. -- Fixed `run_tests.py` import-order and module-resolution issues so `python run_tests.py full` now works from the repository root without ad-hoc `PYTHONPATH` setup. -- Completed the live-Ollama gated smoke next step via `python run_tests.py full`. -- Replaced home-screen overlay TODO markers with an explicit rationale so the workaround is documented and tracked without ambiguous TODO debt. -- Removed debug-only prompt-history prints from `src/view/home_screen.py`. -- Updated `docs/UI_UNIFICATION_PLAN_1_0.md` with explicit 1.0 status per workstream (done versus deferred to 1.1). -- Added `v1.0.0` release notes in `docs/CHANGELOG.md` and reset `Unreleased` to an empty placeholder. -- Bumped repository version metadata to `1.0.0` (`VERSION`, Doxygen `PROJECT_NUMBER`) and regenerated `docs/code/`. -- Fixed import-order regressions in all three root entry scripts (`run_batllm.py`, `run_game_analyzer.py`, `run_tests.py`) by inserting `src/` on `sys.path` before importing `util.compat`. -- Enabled GitHub branch protection on `main` with required checks (`Multiplatform Validation / test`, `Multiplatform Validation / homebrew`, `Multiplatform Validation / smoke`), strict up-to-date enforcement, required conversation resolution, and one required approving review. -- Bumped repository version metadata back to `0.3.5` so the project remains on the `0.x` line pending maintainer testing. -- Made explicit-platform install-command resolution deterministic in `src/llm/service.py` while preserving modelito delegation for runtime auto-detection. -- Repaired reintroduced import-order regressions in the root launchers (`run_batllm.py`, `run_game_analyzer.py`, `run_tests.py`) so `src/` path bootstrap happens before importing `util.compat`. -- Updated `.github/workflows/multiplatform.yml` Homebrew job environment to use the same headless Kivy/PYTHONPATH settings as other CI jobs. -- Relaxed `src/tests/smoke_llm_payload.py` health-check assertion for mock-only CI runs where service state can be running with `installed=False` and an empty version string. +- Release-preparation work is functionally complete for the automatable path: release bundles build, Homebrew formula generation works, and packaging smoke validation passes. +- The repository remains on version `0.3.5`; the earlier `1.0.0` notes are retained only as draft reference material and are not the active release line. +- Root launchers and `run_tests.py` were stabilised so repository-root execution works without ad-hoc `PYTHONPATH` setup. +- `src/llm/service.py` now keeps explicit install-command mapping deterministic for tests while preserving modelito runtime auto-detection when no platform override is supplied. +- `.github/workflows/multiplatform.yml` is aligned with the Homebrew dry-run job's headless Kivy/PYTHONPATH requirements. +- Mock-Ollama smoke coverage now tolerates the expected CI state where the service can be reachable with `installed=False` and no version string. +- GitHub branch protection on `main` now uses the live required check names published by GitHub Actions: `ubuntu-latest`, `windows-latest`, `macos-latest`, `Homebrew dry-run`, and `Smoke: Ollama integration`. +- Maintained release documents were updated to reflect the current `0.x` hold pending manual maintainer sign-off. ## Tests And Verification Status -Executed in this work session: +Recent verified commands: -- `pytest -q src/tests/test_ollama_config_screen_logic.py src/tests/test_multiplatform_support.py src/tests/test_game_analyzer.py` -> `57 passed` -- `pytest -q src/tests/test_homebrew_packaging.py` -> `7 passed` -- `pytest -q` -> `138 passed, 2 skipped` -- `python create_release_bundles.py` -> generated all expected archives under `dist/releases/`. +- `python run_tests.py full` -> core smoke `4 passed`; full suite `153 passed`; live-Ollama lifecycle start/stop verified. +- `pytest -q` -> `151 passed, 2 skipped`. +- `pytest -q src/tests/test_homebrew_packaging.py` -> `7 passed`. +- `pytest -q src/tests/test_multiplatform_support.py::test_install_command_for_current_platform_is_platform_specific src/tests/test_ollama_config_screen_logic.py::test_build_ollama_install_command_is_platform_specific src/tests/test_homebrew_packaging.py` -> `9 passed`. +- `python create_release_bundles.py` -> generated expected platform and source archives under `dist/releases/`. - `python create_homebrew_formula.py --create-worktree-archive /tmp/BatLLM-homebrew-source.tar.gz --formula-out /tmp/batllm.rb` -> completed successfully and wrote `/tmp/batllm.rb`. -- `pytest -q src/tests/test_packaging_smoke.py` -> `4 passed` -- `python validate_packaging_smoke.py --skip-homebrew` -> `Packaging smoke validation passed.` - `python validate_packaging_smoke.py` -> `Packaging smoke validation passed.` -- `pytest -q` -> `142 passed, 2 skipped` -- `pytest -q src/tests/test_multiplatform_support.py` -> `29 passed` -- `pytest -q src/tests/test_packaging_smoke.py src/tests/test_multiplatform_support.py` -> `36 passed` - `python validate_packaging_smoke.py --run-installer-smoke` -> `Packaging smoke validation passed.` -- `python create_homebrew_formula.py --create-worktree-archive /tmp/BatLLM-homebrew-source.tar.gz --formula-out /tmp/batllm.rb && brew install/test/uninstall via temporary local tap` -> completed successfully. -- `pytest -q src/tests/test_packaging_smoke.py src/tests/test_multiplatform_support.py` -> `37 passed` - `python validate_packaging_smoke.py --skip-release-bundles --skip-homebrew --run-homebrew-install-smoke --homebrew-install-timeout 1800` -> `Packaging smoke validation passed.` -- `doxygen docs/code/dox_config.properties` -> completed successfully; regenerated `docs/code/` HTML/LaTeX outputs. -- `pytest -q src/tests/test_multiplatform_support.py src/tests/test_packaging_smoke.py` -> `38 passed` -- `pytest -q` -> `149 passed, 2 skipped` -- `pytest -q src/tests/test_multiplatform_support.py src/tests/test_packaging_smoke.py` -> `40 passed` -- `pytest -q` -> `151 passed, 2 skipped` -- `pytest -q src/tests/test_homebrew_packaging.py src/tests/test_packaging_smoke.py` -> `16 passed` -- `python -m py_compile run_batllm.py run_game_analyzer.py run_tests.py create_release_bundles.py create_homebrew_formula.py validate_packaging_smoke.py src/llm/service.py src/util/packaging_smoke.py` -> completed successfully (no syntax errors) -- `doxygen docs/code/dox_config.properties` -> completed successfully after updating `PROJECT_NUMBER` to `0.3.4` -- `python run_tests.py full` -> core smoke `4 passed`; full suite with live-Ollama gating `153 passed`; runner successfully started and stopped local Ollama through `llm.service`. -- `/Users/tom/devel/ml-llm/llm/BatLLM/.venv_BatLLM/bin/python create_release_bundles.py` -> generated source and platform release archives under `dist/releases/`. -- `/Users/tom/devel/ml-llm/llm/BatLLM/.venv_BatLLM/bin/python create_homebrew_formula.py --create-worktree-archive /tmp/BatLLM-homebrew-source.tar.gz --formula-out /tmp/batllm.rb` -> completed successfully and wrote `/tmp/batllm.rb`. -- `/Users/tom/devel/ml-llm/llm/BatLLM/.venv_BatLLM/bin/python -m pytest -q src/tests/test_homebrew_packaging.py` -> `7 passed`. -- `/Users/tom/devel/ml-llm/llm/BatLLM/.venv_BatLLM/bin/python run_tests.py full` -> core smoke `4 passed`; full suite `153 passed`; live-Ollama lifecycle start/stop verified. -- `/Users/tom/devel/ml-llm/llm/BatLLM/.venv_BatLLM/bin/python -m pytest -q` -> `151 passed, 2 skipped`. -- `doxygen docs/code/dox_config.properties` -> completed successfully with `DOXYGEN_EXIT:0`; regenerated HTML/LaTeX docs for version `0.3.5`. -- `gh api -X PUT repos/krahd/BatLLM/branches/main/protection --input ...` -> completed successfully; protection now enforces required checks and review policy on `main`. -- `gh api repos/krahd/BatLLM/branches/main/protection` -> completed successfully; verified active protection settings. -- `/Users/tom/devel/ml-llm/llm/BatLLM/.venv_BatLLM/bin/python -m pytest -q src/tests/test_multiplatform_support.py::test_install_command_for_current_platform_is_platform_specific src/tests/test_ollama_config_screen_logic.py::test_build_ollama_install_command_is_platform_specific src/tests/test_homebrew_packaging.py` -> `9 passed`. -- `/Users/tom/devel/ml-llm/llm/BatLLM/.venv_BatLLM/bin/python -m py_compile run_batllm.py run_game_analyzer.py run_tests.py src/llm/service.py` -> completed successfully (no syntax errors). +- `python -m py_compile run_batllm.py run_game_analyzer.py run_tests.py create_release_bundles.py create_homebrew_formula.py validate_packaging_smoke.py src/llm/service.py src/util/packaging_smoke.py` -> completed successfully (no syntax errors). +- `doxygen docs/code/dox_config.properties` -> completed successfully; generated docs align with version `0.3.5`. +- `gh api repos/krahd/BatLLM/branches/main/protection` -> verified the live required-check configuration on `main`. + +This PR is documentation-only; no additional code execution was required for the STATUS sanitisation itself. ## Known Issues, Risks, And Limitations - `src/llm/service.py` still owns BatLLM-specific overlay logic and timeout policy; avoid re-expanding it into a generic provider abstraction already handled by `modelito`. -- Homebrew install-level smoke now depends on temporary local tap setup because current Homebrew rejects direct file-based formula installs outside a tap. +- Homebrew install-level smoke depends on temporary local tap setup because current Homebrew rejects direct file-based formula installs outside a tap. - First-run checklist execution is complete for command-level macOS validation but still requires manual Linux and Windows first-run pass/sign-off. ## Recurring Tasks @@ -173,16 +120,16 @@ Executed in this work session: ## Pending Tasks - Complete manual first-run checklist execution on Linux and Windows hosts and update `docs/FIRST_RUN_RELEASE_CHECKLIST.md` sign-off to fully complete. -- Final maintainer release actions: freeze scope on release branch, rerun required CI checks, and tag a `0.x` release candidate (`v0.3.5`) when external gates are complete. +- Final maintainer release actions: freeze scope on a release branch, rerun required CI checks, and tag `v0.3.5` only after the manual platform sign-offs are complete. ## Next Steps — Remaining Before Tagging v0.3.5 -Implemented from the previous cycle in this session: +Automatable release-preparation work already completed: -1. Criterion 3 UX gaps addressed for 1.0 tracking: overlay workaround documented, debug print removed, and UI unification workstreams marked done/deferred in `docs/UI_UNIFICATION_PLAN_1_0.md`. -2. Criterion 5 documentation/versioning addressed: draft `v1.0.0` notes are kept as non-released reference only; active repository versioning is `0.3.5`; Doxygen metadata and generated API docs are aligned to `0.3.5`. -3. Release-signoff command set executed locally: release bundles built, Homebrew formula rendered, Homebrew packaging tests passed, full test suite and `run_tests.py full` passed. -4. Criterion 1 branch-protection gate completed: required checks and review/conversation rules are now enforced on `main`. +1. Release-bundle creation, Homebrew formula rendering, packaging smoke checks, and full automated test coverage have been exercised successfully. +2. Active repository versioning, Doxygen metadata, and maintained release documents are aligned on `0.3.5` rather than a `1.0` tag. +3. Branch protection on `main` now uses the live GitHub Actions check names and strict up-to-date enforcement. +4. Launcher, runtime-install, and mock-smoke regressions identified during CI review have been fixed and revalidated. Remaining external maintainer actions (not fully automatable from this workspace): @@ -201,4 +148,4 @@ Remaining external maintainer actions (not fully automatable from this workspace --- -Last updated: 2026-05-08 20:35 +Last updated: 2026-05-09 14:13 diff --git a/docs/RELEASE_CRITERIA_1_0.md b/docs/RELEASE_CRITERIA_1_0.md index 53cb4f2..0abf576 100644 --- a/docs/RELEASE_CRITERIA_1_0.md +++ b/docs/RELEASE_CRITERIA_1_0.md @@ -10,9 +10,11 @@ A 1.0 candidate is ready only when all sections below are complete. Required checks on `main` pull requests: -- `Multiplatform Validation / test` -- `Multiplatform Validation / homebrew` -- `Multiplatform Validation / smoke` +- `ubuntu-latest` +- `windows-latest` +- `macos-latest` +- `Homebrew dry-run` +- `Smoke: Ollama integration` Required workflow expectations: