Fix twelve Client API spec divergences and add a conformance guard

[barkz]

What

Fixes the twelve Client API calls that diverged from Glean's published OpenAPI
spec, and adds the guard that stops it happening again.

Spec diffed against: 0.9.0, source commit 0fef9ef.

Why they were invisible

_mock_response is keyed on the same path strings the live client posts to. A
wrong path was wrong consistently, so nothing disagreed and all 1,151 tests
passed while twelve commands would have failed against a real tenant.

The fixes

Paths

Was	Now
/getdocumentpermissions + {documentSpec:{id}}	/getdocpermissions + {documentId}
/announcements/create	/createannouncement
/announcements/delete	/deleteannouncement
/createpin	/pin

Methods and parameter location — /tools/list is a GET with an optional
toolNames query param, not a POST. listverifications takes count in the
query string. _post gained optional method and query arguments for these;
mock and local dispatch stay keyed on the bare path, so offline behaviour is
unchanged.

Bodies — arguments→parameters, email→emailIds[],
documentSpec→documentSpecs[], agentId→agent_id, query→name, and
/feedback now sends {event, trackingTokens[]} with THUMBS_UP/DOWN mapping to
the spec's UPVOTE/DOWNVOTE, free text moving to manualFeedbackInfo.comments,
and category kept as the separate enum it is.

Two product decisions

• /announcements.list is removed. Glean documents only create, update and
  delete — nothing backs a list. A command that can only 404 is worse than no
  command.
• /pins.create keeps --url by resolving it to a document id through
  /getdocuments before pinning, since the API pins by id against a list of
  queries. --doc-id was added to skip the round trip.

The guard

tests/test_spec_conformance.py reads client.py with ast and asserts every
path and method it calls exists in the spec. It handles f-string paths
(f"/debug/{datasource}/status"), agent_run passing a variable, and
{group} vs {groupName}.

The suite must stay offline, so it compares against a committed manifest
(tests/spec_manifest.json, ~7 KB) generated by
tools/refresh_spec_manifest.py — the only file here that touches the network.
It needs PyYAML, which is tooling only: neither the package nor the tests
import it, so zero runtime dependencies still holds and the zipapp is unchanged
(verified: 150 KB, nothing from tools/ or tests/ leaks in).

The new scheduled spec-drift workflow runs the refresher with --check
weekly. It is separate from release.yml on purpose — a Glean spec update is an
external event and shouldn't fail an unrelated PR.

Verified by regression injection. Reintroducing each defect class makes the
guard fail with an actionable message:

wrong path    -> client: POST /getdocumentpermissions
wrong method  -> client: POST /tools/list (spec allows GET)
invented path -> client: POST /announcements/list

It found a thirteenth item

/indexemployeelist — flagged as uncertain in the August audit. The spec
declares it with no operation, so it is neither present nor absent. The manifest
now records declared-but-undocumented paths separately, and a self-cleaning test
fails if Glean documents it again, which is the signal to drop the exception.

Notes

• One pre-existing test was passing for the wrong reason: the /people mock test
  sent {"email": ...}, the mock read nothing, and person(None) happened to
  return the person it asserted on. It now asserts the response echoes the
  address requested.
• Eleven existing assertions encoded the old, wrong shapes and now encode the
  contract.

Tests

1,151 → 1,173, including the first coverage of _post's live path — the
method and query-string handling had none, which is exactly how those two
divergences survived. Confirmed with a socket guard that all 1,173 make zero
network calls.

🤖 Generated with Claude Code