Final review fixes: guard the logs resolution, narrow the swallow, settle the surface tiers

[pedro-pscunha]

The final pre-publish review. Eleven findings, all reproduced against the code before
anything changed, all applied, none rejected. Seven commits, each one finding or one
group of them.

The logs signal could go quiet, twice

AGENTS.md and the permanent 0.1.0 changelog entry both promise that a release moving the
private opentelemetry._logs costs the logs signal and nothing else: import guideme
still works and traces are untouched. Two things made that false.

The guard was narrower than the promise. resolve_logs caught ImportError around the
deferred import, then read SeverityNumber.INFO, SeverityNumber.WARN and called
get_logger twice outside it, at module scope through LOGS = resolve_logs(). Against a
module that imports cleanly and has lost a member:

import guideme FAILED: AttributeError: type object '...' has no attribute 'INFO'

Every read of that API now happens inside the one guard, which catches ImportError,
AttributeError and TypeError. The same probe after:

import guideme OK; guideme.telemetry.LOGS is None
events("log") refused: ConfigError: ... needs the OpenTelemetry logs API, and
opentelemetry-api 1.44.0 has none at opentelemetry._logs. ...

The swallow was wider than its docstring. Logs._emit wrapped the private LogRecord
constructor and logger.emit in one except Exception: pass, while the docstring scoped
it to a sink that raises. With a LogRecord that no longer takes event_name, an
events("log") ask produced zero span events, zero log records and no error — the "records
that silently go nowhere" the refusal in GuideBuilder.events exists to prevent:

events("log") accepted
span events: []
log records: 0
nothing raised

resolve_logs now builds one throwaway record with the five keywords _emit uses, so a
constructor change is found where absence is already representable, and _emit builds its
record before the try. The same drift after:

resolve_logs() -> False
events("log") refused LOUDLY: ConfigError: ...

The probe still succeeds against the installed 1.44.0, so today's behaviour is unchanged and
the tracing suite still asserts on real exported log records.

The documents disagreed about guideme.question

docs/design.md told callers to import Question from guideme.question; AGENTS.md and
the README said the supported surface was __all__ plus guideme.api and guideme.policy,
everything else private. The recorded reason for keeping Question out — that no public
signature returns it — was false: noul, choose, choose_among, score, score_levels
and all three .detail() methods return Question subclasses, and tests/test_live.py
imports it from that module.

Settled by naming guideme.question in the second tier, not by growing __all__. The tier
already carries the same major-bump promise, so the contradiction closes without touching the
33-name export list, and the README now documents Question where a caller meets it, with
the dict invariance reason an annotation actually needs it for.

The rest

ask's docstring	listed "two runtime keys collide" under its ConfigError. It never raises it: choose_among does, at question-construction time. Clause removed, choose_among says it from the other side.
CHANGELOG.md	said ApiKey "has no __str__". It has one, returning ApiKey(***). That entry ships in the sdist and is permanent once uploaded.
docs/observability.md	called opentelemetry._logs "the public logs API", the opposite of AGENTS.md and of the premise the deferred import rests on.
ConfigError docstring	named one events(...) trigger, not the other: an installed opentelemetry-api with no logs API.
ci.yml	the lock-comparison program left its heredoc for scripts/resolved_vs_lock.py, so ruff, pyright strict and pylint check it. Behaviour proven unchanged both ways: unchanged it prints "nothing in the lock has a newer release today"; with a stale certifi substituted into the text it reads out of git, "1 resolved newer than the lock: certifi".
cross-origin redirect	api/client.py rests on httpx dropping the authorization header when a redirect changes origin, and only the same-origin case was tested. A second HTTPServer on its own port now makes the hop cross origins. The comment names httpx's carve-out: a direct same-host http → https upgrade keeps the header deliberately.
invalid events(...)	three documents promised the refusal and nothing tested it.
release.yml	has never executed, and the tag that starts it is immutable, so a first-run defect burns v0.1.0. workflow_dispatch now runs build — the whole gate plus uv build — and publish is gated on github.event_name == 'push', a fact about how the run started rather than an input, a branch or a variable anyone can set. No dispatched run can reach PyPI.

Tests

The ceiling is 43 test functions and the suite was at it. It still is: two more
configuration-mistake parameters and a third redirect arrangement, no new function.
162 passed, 2 deselected, up from 158.

Both new configuration cases were mutation-proved against the unfixed code: with the probe
removed from resolve_logs the drift case fails on telemetry.LOGS is None; with the
EVENT_MODES check removed the unknown-mode case fails DID NOT RAISE ConfigError.

Readings recorded under ## Apply (final) in the assumptions file, including the explicit
correction of the false rationale in ## Apply (docs).

🤖 Generated with Claude Code