docs(research): hal0 × ODS field study — comparison, observed install, adoption plan

[thinmintdev]

Summary

Adds docs/research/ods-field-study-2026-09/: a source-level comparison of Osmantic ODS (v2.6.0 line, 21f4b3a) and hal0 (108b366), a journal of a sandbox install of ODS, all 106 open hal0 issues triaged against ODS's code, and a ranked port ledger in waves. The HTML is self-contained (nine domain reports and install screenshots embedded); the reports and journal are also committed as Markdown so they diff and cite cleanly. Nothing is acted on in this PR; it is a research note in the docs/research/ convention, for the maintainers to decide on. Headline findings it records: the approvals endpoints execute gated tools with auth removed on a LAN-open default bind (ODS's stateless signed-cookie module is a near-verbatim fix); hal0-Max's coder pick is the model family ODS's fleet tests found broken on unified-memory backends and needs a verdict on real hardware; ODS ships no MCP while hal0 already has most of a user-added MCP registry; ODS's two-file extension model is verified and translated into a manifest.toml → hal0-ext@<id> quadlet proposal.

Risk grade

• low — docs only, internal refactor, or behaviour-preserving fix
• med — user-facing change, new code path, or non-trivial refactor
• high — anything touching the §14.1 high-risk surfaces below

Touched surfaces

• API (src/hal0/api/)
• Auth / sessions (src/hal0/auth/, login routes, middleware)
• Slots / dispatch (src/hal0/slots/, slot_state, /v1/load|unload)
• Models / capabilities (src/hal0/capabilities/, model_meta, model_fit)
• Installer (installer/, systemd units)
• Updater (src/hal0/updater/, hal0.releases.v1 manifest)
• Board chat / MCP admin (src/hal0/api/routes/board_chat.py, src/hal0/mcp/admin.py)
• Config / schema (src/hal0/config/, pydantic models)
• UI (ui/src/, Playwright specs)
• Docs (docs/, CONTRIBUTING.md)
• CI / release (.github/workflows/, release.yml)

§14.1 high-risk surfaces

• Unauthenticated board routes — any new /v1/board/* or MCP endpoint exposed without auth middleware (KB-1 / §1 deny-by-default)
• AUTONOMOUS_WRITE_TOOLS — additions to the write set in src/hal0/mcp/admin.py (board-chat auto-actions)
• Installer / updater RCE-class — shell-out, downloads, signature verification, manifest parsing, privilege changes

None touched. The study documents that src/hal0/api/routes/approvals.py runs gated tools unauthenticated, but this PR does not change any route.

Rollback

Rollback: revert the single commit, or delete docs/research/ods-field-study-2026-09/. No code, config, or CI is touched.

Test tiers run

• α unit (make test) — passed in CI on a9d7c96 (the python (3.12) job, ~28 min). A local run in the authoring sandbox (4 vCPU shared with a running ODS stack) did not complete inside the session's time budget; CI is the authority for this docs-only PR.
• β integration (make test-integration) — not applicable to a docs-only change.
• γ release-gate (make release-test) — not required (low risk); the γ-suite (chromium) job ran and passed on this head regardless.

Notes for reviewers

• Only docs/research/ods-field-study-2026-09/** is added (HTML ≈ 3 MB because screenshots are embedded as data URIs; the Markdown reports are the reviewable text).
• No operator host names or LAN addresses: the install ran in an ephemeral sandbox; the hostname vm and the /home/ods paths in the journal are the sandbox's.
• The study's ADR remarks were corrected against CHANGELOG.md (chore: gitignore docs/internal/ and untrack 84 internal docs #638: ADR texts live in the gitignored internal tree); the remaining drift it flags is the CLAUDE.md vs ARCHITECTURE.md disagreement about whether docs/adr/ is the record.
• All checks green on a9d7c96: CodeQL, ui, sunset, python (3.12), γ-suite (chromium), detect, and the three analyzers; engine-gate skipped (no engine paths touched).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ntx2XQ8VhpG78MLxpWXDZR