[codex] audit CI, security, and state docs

.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "ci"
+      include: "scope"

.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Create venv
+        run: |
+          python -m venv .venv_BatLLM
+      - name: Install dependencies
+        run: |
+          . .venv_BatLLM/bin/activate
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt
+          python -m pip install pytest pylint
+      - name: Compile sources
+        run: |
+          . .venv_BatLLM/bin/activate
+          python -m compileall .
+      - name: Run tests
+        run: |
+          . .venv_BatLLM/bin/activate
+          python run_tests.py
+      - name: Run pylint
+        if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12' }}
+        run: |
+          . .venv_BatLLM/bin/activate
+          pylint src run_batllm.py run_game_analyzer.py create_release_bundles.py create_homebrew_formula.py

.github/workflows/dependency-review.yml

@@ -0,0 +1,20 @@
+name: Dependency review
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Review dependency changes
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high

.github/workflows/pip-audit.yml

@@ -0,0 +1,28 @@
+name: Python dependency audit
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "17 4 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  pip-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - name: Audit requirements
+        uses: pypa/gh-action-pip-audit@v1.1.0
+        with:
+          inputs: requirements.txt

PR_BODY.md

@@ -0,0 +1,38 @@
+## Summary
+
+This PR implements the confirmed high-confidence improvements from the BatLLM audit:
+
+- adds a repository security policy;
+- adds Dependabot for Python and GitHub Actions dependencies;
+- adds PR-time dependency review;
+- adds scheduled and PR-time Python dependency auditing with `pip-audit`;
+- adds a cross-platform Python CI matrix for Linux, macOS, and Windows;
+- documents the single runtime-state invariant: installed application files are read-only and mutable state belongs under `BATLLM_HOME` or the platform app-data equivalent;
+- adds a maintainer audit checklist for launchers, configuration, sessions, Ollama lifecycle, and release checks.
+
+## Rationale
+
+The audit found that BatLLM has several operational surfaces: source launchers, analyzer launchers, Homebrew packaging, release bundles, mutable configuration, saved sessions, and local Ollama orchestration. This makes repository hygiene and state-location consistency critical.
+
+This PR is deliberately additive. It avoids speculative refactors where source-level verification is required, but it establishes the CI/security/doc baseline needed before deeper changes such as entry-point consolidation, `pyproject.toml` migration, and state-path refactoring.
+
+## Verification
+
+Expected checks:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python run_tests.py
+python -m compileall .
+pylint src run_batllm.py run_game_analyzer.py create_release_bundles.py create_homebrew_formula.py
+pip-audit -r requirements.txt
+```
+
+## Follow-up work
+
+- Convert runtime configuration writes to use `BATLLM_HOME` everywhere.
+- Add migration logic for repository-relative historical config.
+- Collapse launchers onto canonical installed entry points.
+- Add `pyproject.toml` after confirming package/module names under `src/`.
+- Add tests for path handling, missing Ollama, non-responsive Ollama, subprocess timeouts, and session migration.

PR_TITLE.txt

@@ -0,0 +1 @@
+Harden CI, dependency security, and runtime state documentation

SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the current `main` branch and the most recent tagged release.
+
+## Reporting a vulnerability
+
+Report suspected vulnerabilities privately. Do not open a public issue containing exploit details, secrets, local paths, or reproduction data that may expose a user system.
+
+Include:
+
+- affected BatLLM version or commit;
+- operating system and Python version;
+- installation method;
+- whether Ollama was installed system-wide, through Homebrew, or manually;
+- minimal reproduction steps;
+- relevant logs with secrets, local usernames, and paths redacted.
+
+## Security-relevant areas
+
+BatLLM interacts with a local Ollama service, reads and writes local configuration, stores sessions, and invokes launch scripts. Reports involving path traversal, unsafe subprocess use, unexpected writes outside the configured application directory, dependency compromise, or unintended disclosure of local files should be treated as security relevant.

STATUS.md

@@ -1,6 +1,6 @@
 # BatLLM Status
 
-Last updated: 2026-05-23
+Last updated: 2026-05-29 01:52
 
 BatLLM is a Python/Kivy research, education, and game project for exploring AI-mediated play, prompt quality, LLM behaviour, and local-model workflows. The repository currently contains a playable local desktop game, a standalone read-only Game Analyzer, local Ollama lifecycle and model-management helpers routed through `modelito`, release-bundle tooling, Homebrew formula generation, generated API reference artefacts, and maintained user/developer documentation.
 
@@ -12,7 +12,7 @@ The project should remain practical, critical, and educational. Destructive or e
 
 - Python: `>=3.10` and `<3.13` enforced by the launcher compatibility helper.
 - Main UI framework: Kivy `2.3.1` plus KivyMD `1.2.0`.
-- LLM/runtime integration: Ollama through `modelito==1.4.0` and `ollama==0.5.3`.
+- LLM/runtime integration: Ollama through `modelito==1.4.0` and `ollama>=0.5.11`.
 - Default shipped model: `smollm2` with first-run `last_served_model` intentionally blank.
 - Repository version: `0.3.6`.
 
@@ -46,6 +46,7 @@ python run_batllm.py
 python run_game_analyzer.py
 ```
 
+
 ### Test Runner
 
 ```bash
@@ -56,6 +57,20 @@ python run_tests.py full
 
 `run_tests.py full` requires `.venv_BatLLM` and may start/stop a real local Ollama service. Use it only when local Ollama state is safe to exercise.
 
+## 2026-05-29: CI, Security, And Documentation Merge
+
+- Fast-forwarded the audit-driven branch into `main`; the repository now includes the CI, dependency-security, and documentation artefacts listed below.
+- Updated `requirements.txt` and `packaging/homebrew/requirements.txt` to require the audited minimum versions:
+	- `ollama>=0.5.11` (fixes PYSEC-2025-145)
+	- `requests>=2.33.0` (fixes CVE-2026-25645)
+	- `pytest>=9.0.3` (fixes CVE-2025-71176)
+- Added `.github/dependabot.yml`, `.github/workflows/dependency-review.yml`, and `.github/workflows/pip-audit.yml`; `.github/workflows/ci.yml` now creates `.venv_BatLLM` before installing dependencies and running tests.
+- Added repository and docs-site security guidance in `SECURITY.md` and `docs/SECURITY.md`.
+- Added `docs/STATE_AND_INSTALLATION.md` and `docs/MAINTAINER_AUDIT_CHECKLIST.md` for audit support and maintainer reference.
+- Retained the audit bundle artefacts and helper script at the repository root for traceability: `batllm-audit-pr.patch`, `batllm-audit-pr-overlay.zip`, `batllm-pr-implementation/`, and `scripts/apply_audit_pr.sh`.
+- Dependency Review workflow requires enabling the GitHub Dependency Graph in repository settings for full support.
+- All other project state, architecture, and documentation remain as previously described.
+
 ### Useful Environment Variables
 
 - `BATLLM_HOME`: redirects mutable config and saved-session data away from the repository or package install location.
@@ -166,10 +181,12 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins
 - `VERSION`: active repository version (`0.3.6`).
 - `requirements.txt`: root development/runtime dependency pins.
 - `pytest.ini`: pytest path and discovery configuration.
-- `.github/workflows/`: CI and Homebrew tap publication workflows.
+- `.github/workflows/`: CI, dependency-review, pip-audit, multiplatform, and Homebrew tap publication workflows; `.github/dependabot.yml` tracks dependency updates.
 - `run_batllm.py`: main application launcher.
 - `run_game_analyzer.py`: standalone Game Analyzer launcher.
 - `run_tests.py`: cross-platform core/full test runner.
+- `SECURITY.md` and `docs/SECURITY.md`: repository and docs-site security guidance.
+- `docs/STATE_AND_INSTALLATION.md` and `docs/MAINTAINER_AUDIT_CHECKLIST.md`: audit support and maintainer checklist documents.
 - `src/`: application, game, analyzer, utility, and test source.
 - `src/app.kv` and `src/view/*.kv`: Kivy layout definitions.
 - `src/assets/`: images, prompts, sounds, and system instructions.
@@ -181,6 +198,7 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins
 - `src/view/`: Kivy screen classes and UI helpers.
 - `docs/`: maintained user/developer docs, screenshots, diagrams, and generated API docs.
 - `packaging/homebrew/`: Homebrew distribution docs and pinned formula requirements.
+- `batllm-audit-pr.patch`, `batllm-audit-pr-overlay.zip`, `batllm-pr-implementation/`, and `scripts/apply_audit_pr.sh`: audit bundle artefacts and helper script retained for traceability.
 - `tools/ollama_mock_server.py`: local mock server for Ollama integration smoke tests.
 
 ## Documentation State
@@ -191,6 +209,9 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins
 - `docs/ROADMAP.md` describes 1.0 local desktop hardening and 2.0 networked-play direction using current `0.3.x` line wording.
 - `docs/RELEASE_CRITERIA_1_0.md` defines CI, reliability, UX, bundle, and documentation gates for a future 1.0 candidate.
 - `docs/CHANGELOG.md` keeps active unreleased notes on the `0.x` hold and draft 1.0 notes.
+- `SECURITY.md` is the repository security policy, and `docs/SECURITY.md` mirrors that guidance for the published docs site.
+- `docs/STATE_AND_INSTALLATION.md` summarises the current installation and repository state used by the audit bundle.
+- `docs/MAINTAINER_AUDIT_CHECKLIST.md` records the maintainer checklist for the audit/security update.
 - `docs/index.html` is the static project showcase served by GitHub Pages from branch `main` and path `/docs`.
 - `docs/.nojekyll` keeps GitHub Pages from applying Jekyll processing to the static documentation tree.
 - `docs/FIRST_RUN_RELEASE_CHECKLIST.md` and `docs/UI_UNIFICATION_PLAN_1_0.md` remain release-preparation references.
@@ -199,6 +220,11 @@ This status update followed a repository-wide audit on 2026-05-09. The audit ins
 
 ## Tests And Verification Status
 
+### 2026-05-29 Merge Validation
+
+- No automated tests were rerun for the fast-forward merge to `main`; the branch only added dependency-floor, workflow, and documentation files.
+- The validation record below remains the latest executed test evidence for the repository state.
+
 ### Latest Commands Run For This Audit (2026-05-23 Bug Fix Audit)
 
 - Repository-wide source read: all Python files in `src/`, root launchers, `tools/`, `scripts/`, CI workflows, `requirements.txt`, `pytest.ini`, `.pylintrc`, and packaging files read and cross-referenced by three parallel agents.
@@ -293,4 +319,4 @@ The previous status report recorded these successful checks from the same releas
 - Design the 2.0 server contract before adding web or repository-backed prompt/game sharing.
 - Add broader tests for malformed model responses, slow startup, missing models, session compatibility, analyzer edge cases, and packaged first-run behaviour.
 
-Last updated: 2026-05-23
+Last updated: 2026-05-29 01:52