quality: strict typing + full docstring coverage across the package

[cnewkirk]

Summary

A typing + documentation quality pass over the whole hueman package. No runtime behavior changes.

• mypy --strict is now clean (0 errors across 19 source files; was 139 errors in 12 files). [tool.mypy] strict = true is added to pyproject.toml so it stays enforced, with mypy, types-requests, and types-PyYAML added to the dev extras.
• Docstring coverage is 100%: every module, class, function, and method — including private helpers and __init__s — has a Google-style docstring matching the existing house style in sun.py (122 were missing). Docstrings were written against the code, documenting contracts (BLOCKED plan semantics, debounce/override behavior, timeslot wrap rules, YAML coercion quirks) rather than restating it.
• Typing style is uniform modern 3.10+: builtin generics, X | None unions, collections.abc imports, from __future__ import annotations everywhere. Zero # type: ignore; only 3 cast() calls, all at genuine JSON boundaries with explanatory comments.

Behavior safety

This package drives a live daemon, so the pass was constrained to zero behavior change:

• New assert x is not None narrowing sits only where the old code immediately dereferenced the same value (the failure mode changes from AttributeError to AssertionError; under python -O it is byte-for-byte the old behavior).
• The few "restructures" (typed locals, an early return, two loop-variable renames) were each traced to exact runtime no-ops in review.
• No test files touched: the identical pre-existing suite passes, 307/307.

Verification

• mypy --strict --no-incremental hueman/ → Success: no issues found in 19 source files
• pytest -q → 307 passed
• AST audit → 0 missing docstrings package-wide
• Independent reviewer pass over the full diff: no Critical/Important findings; the minor consistency nits it raised are fixed in this branch.

🤖 Generated with Claude Code