Skip to content

docs: add the steering trio (STEERING.md, ADR.md, root CLAUDE.md) - #1

Merged
jonathanstokes merged 1 commit into
mainfrom
docs/steering-trio
Aug 4, 2026
Merged

docs: add the steering trio (STEERING.md, ADR.md, root CLAUDE.md)#1
jonathanstokes merged 1 commit into
mainfrom
docs/steering-trio

Conversation

@jonathanstokes

Copy link
Copy Markdown
Contributor

Summary

Adds durable engineering context in three files with distinct jobs: docs/STEERING.md describes what the system is (boundaries, patterns, constraints) and points into architecture.md rather than duplicating it; docs/ADR.md records four long-standing decisions with the alternatives that lost and why; CLAUDE.md at the repo root carries the working rules an agent or contributor needs on every change. None of these ship to PyPI - they are not in the wheel's package dir or on the sdist include list, so they exist only in the git tree.

Changes

  • docs/STEERING.md: purpose, scope and boundaries, owned paths, four patterns with canonical code examples, six measurable constraints, pointers, and the infrastructure picture
  • docs/ADR.md: ADR-0001 committed protobuf bindings with the coupled runtime pin, ADR-0002 fully offline test suite behind a single lazy hid import, ADR-0003 USB HID as the only transport, ADR-0004 the domain model lands additively on the unchanged protocol layer
  • CLAUDE.md: dev/test commands, the import-safety rule, the bindings/pin rule, the keyed-edit rule, evidence-bearing docstrings, the RX-thread invariant, and a Do-not list for the genuinely dangerous surfaces (Updater, cloud, unattended IR probing)

Test plan

  • Full offline suite passes (323 passed, 3 skipped)
  • Every relative link target in the three files resolves
  • Every cited code symbol verified to exist (switch_scene, set_bypass, read_preset, set_param, FakeTransport, open_device, _open_unconnected)
  • Publishing claim checked against releasing.md (token-based, not trusted publishing - corrected before this PR)

Durable engineering context split three ways: docs/STEERING.md describes what
the system is (boundaries, patterns, constraints) and points into
architecture.md rather than duplicating it; docs/ADR.md records four
long-standing decisions with their real alternatives (committed proto
bindings, the offline-only suite, USB HID as the only transport, the additive
domain model); CLAUDE.md at the root carries the working rules. None of these
ship to PyPI - they exist only in the git tree.
@jonathanstokes
jonathanstokes merged commit 9600fca into main Aug 4, 2026
4 checks passed
@jonathanstokes
jonathanstokes deleted the docs/steering-trio branch August 4, 2026 04:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant