docs(code): docstrings that lag the code — cost.py's card fallback and rsi_telemetry's summary line #1099

Problem

agentdescent/cost.py tells a reader the opposite of what docs/cost.md now
says after #1085: two docstrings in the module assert that the loop records each
rollout's usage on the evidence card, and no in-tree producer does.

• cost.py:155-161 (Cost.from_cards): "The loop already records one proposing
  rollout's usage on each card, so the diff's price is the sum over the cards
  that justify it." The two producer sites build a card without either field
  (evolution.py:4362-4381, async_evolve.py:998-1012); the third is a smoke
  helper (meta.py:870). EvidenceCard.cost_tokens / cost_wallclock are
  defaults (evolvable.py:237-238) that nothing writes.
• cost.py:35-39 (module docstring): "…the policy falls back to the cost the
  contributing EvidenceCards recorded, which is what the loop already
  collects. aggregator._decide does not fill diff_cost yet, so the card
  fallback is what every in-tree caller takes today." The second sentence is
  right and policies.py:150-155 states it correctly; the first is the false
  claim.

Consequence: the person most likely to build on the fallback reads the module,
not the page, and is told the cost is already there — which is exactly the
reading that makes require_cost=True look safe. In-tree the fallback is
Cost(), unknown, and a run with require_cost=True defers every candidate the
inner gate accepted (cost.py:357-365).

Measured at 09492927 with the producers' card shape (cost_tokens=0,
cost_wallclock=0.0): Cost.from_cards([card]).known is False;
CostPolicy(inner, require_cost=True).accept(ctx) returns
accept=False, category="cost-unknown", defer=True; the same gate with
reference_quality_per_cost=0.05 or min_gain_per_1k_tokens=1.0 accepts the
candidate with status="unknown".

Scope

• Correct Cost.from_cards's docstring and the fallback sentence in the module
  docstring: no in-tree producer fills the card cost fields, so the fallback is
  unknown on a normal run, and a caller that wants a priced diff passes
  MergeContext.diff_cost = Cost.from_usage(usage).
• One changelog fragment. Docstrings only — no behaviour change, no test
  surface change.

Non-goals

• Recording one rollout's usage on the card at the producer sites. That is the
  real fix and it is T3 for the reason docs(cost): the card cost fallback is always unknown in-tree — say so and warn about require_cost #1085 records: Usage is one shared
  Meter across workers, so per-rollout attribution is racy.
• Changing Cost.from_cards or CostPolicy behaviour, or the page text that
  docs(cost): the card cost fallback is always unknown in-tree — say so and warn about require_cost #1085 landed.

Acceptance

• grep -n "already records one proposing rollout" agentdescent/cost.py → no
  match, and the module docstring's fallback sentence says the fallback is
  unknown in-tree and names Cost.from_usage as the caller's route.
• python -m pytest -q tests/test_cost_per_accepted.py tests/test_cost_aware_selection.py
  → green; python -m tools.gen_api_docs --check → up to date;
  python -m tools.changelog_fragments check → passes with one new fragment.

Written-by: AgentDescent Dev-4 findings, found while writing #1085; filed by AgentDescent Lead.

Second line, same class (#1097 advisory read)

agentdescent/rsi_telemetry.py:111 — the _is_secret_key docstring's summary line still says "True when a whole component of key names a credential (#1070)", while the body directly under it (:113-118) and the code (:126-127, the len(parts) == 1 suffix branch) also match a one-word suffix. The summary lags the rule it introduces.

Measured at the #1097 tip c390e7ae: _is_secret_key("PGPASSWORD") and _is_secret_key("s3secretkey") are True, _is_secret_key("token_count") and _is_secret_key("secrets_scanned") are False — i.e. the body of the docstring is right and only the first line is stale.

That is a one-line correction in a file this issue already has to open, so it rides here rather than as its own card. Still docstrings only: no behaviour change, no new test surface (the acceptance rows for the predicate already exist in tests/test_span_redaction.py).

Acceptance (added)

• sed -n '110,118p' agentdescent/rsi_telemetry.py states the whole-component rule and the one-word suffix rule in the summary line, matching :126-127.