Skip to content

Sanitise STATUS and align release gate docs #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
krahd merged 1 commit into from
May 9, 2026
Merged

Sanitise STATUS and align release gate docs #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 28 additions & 81 deletions STATUS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# BatLLM Status

Last updated: 2026-05-08 20:35
Last updated: 2026-05-09 14:13

## Project Purpose

Expand Down Expand Up @@ -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
Expand All @@ -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):

Expand All @@ -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
8 changes: 5 additions & 3 deletions docs/RELEASE_CRITERIA_1_0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
Loading