feat(tools/discourse): add a read-only Discourse topic bridge - #1755

Summary

• Add the first implementation for #307: a stdlib-only, read-only magpie-discourse topic view <id|url> [--max-posts N] command for structured forum context.
• Read the requested post stream in batches of at most 20, preserve HTML bodies and reply relationships, and fail explicitly on missing posts or malformed responses.
• Include workspace, inventory and specification integration. Declare contract:mail-archive with Coverage: partial; this is not yet a complete/selectable archive backend.

Proposed delivery plan

We intend to deliver the broader issue as separate, independently useful PRs.
Each includes its implementation, tests and required documentation/integration.
The sequence and details remain open to maintainer feedback.

Only PR1 is implemented here.
Skill integration, mega-topic pagination and response-byte/total-duration budgets remain follow-up design work.

Type of change

• Tool / bridge
• Python package
• Documentation

Test plan

• 279 mocked package tests, including native short-link precedence, explicit bare non-ASCII ID errors, ASCII-only IDs/post numbers, encoded and Unicode slugs, and canonical URL round trips; ruff check, ruff format check and mypy pass.
• Repository integration: vendor-neutrality-score 42, skill-and-tool-validator 493, dev 277, spec-validator 87 and spec-inventory 31 pass; 930 total, no skips.
• Full prek run --all-files --verbose, including offline lychee and all four workspace hooks: 40 hooks passed; 51 workspace members, 9,440 passed, 361 conditional skips, 4 deselected and 26 passing subtests.
• Magpie checklist for both review follow-up commits: A-E pass, 0 blocking and 0 advisory items.
• Historical local zizmor 1.30.1 offline scan (2026-10-23): no unsuppressed findings. Workflow files are unchanged in this correction; the scan was not repeated. API-dependent online audits were unavailable without a GitHub token and are not claimed as run.
• Historical anonymous CLI smoke test, 2026-10-20: topic 183261, 3 GETs, 45 unique HTML posts, boolean body markers and truncated: true. No forum writes. This input-validation follow-up uses mocked HTTP; the earlier live smoke test is retained as historical evidence.
• Conditional workspace skips and the absent optional Claude CLI are recorded separately; skipped checks are not counted as passes.
• These local results apply to the audited commit eee77046 on the existing e6e5c2e feature baseline; they are not a full test run on the latest upstream main.
• Static merge check against upstream main 27268f28 is clean; the merged tree was not tested.
• Checks for older PR heads do not establish CI success for eee77046; updated-head GitHub CI will be assessed separately.

RFC-AI-0004 compliance

• Sandbox: network reach declared; adopters allow their configured forum host.
• Vendor neutrality: vendor-specific behavior stays in the partial adapter.
• Write-access discipline: GET only, including redirects.
• Privacy LLM: no model calls; callers establish visibility and apply existing privacy approval before sending content to a model.

Linked issues

Refs #307.
This first slice does not close the broader request.

Notes for reviewers

• Numeric topic/post URLs follow Discourse's native route precedence: /t/2026/42 reads topic 2026 and /t/42/7 reads topic 42. Normal slug generation rejects numeric-only slugs. Topic IDs and post numbers use ASCII digits; Unicode slugs remain supported. See the Discourse routes and slug generation.
• Bare non-ASCII numeric IDs fail before URL parsing with an explicit ASCII-digit requirement. URL routing and Unicode slug support are unchanged. Encoded numeric-slug cases have mocked coverage, without a live-forum verification.
• Every response post requires a string cooked body, including posts beyond the output cap. Explicit empty strings, whitespace and placeholders are preserved; missing/null/invalid bodies fail the whole read.
• body_hidden relays the optional boolean cooked_hidden marker, defaulting to false. It is independent of hidden; false proves neither original text nor public visibility.
• Missing requested posts fail immediately after their batch, without later requests, retries or partial success. Duplicate stream IDs are rejected. Self-consistent empty results remain valid.
• Messages follow forum stream order, which can differ from chronological archive order. truncated means only the post-count limit; it is not a byte or total-time budget. Mega topics without an ordinary ID stream are explicitly unsupported.
• Credentials stay within the configured HTTPS origin and forum path. API usernames must be ASCII; keys must encode as latin-1. Paths use one strict UTF-8 decode; encoded separators, remaining percent escapes and ambiguous paths are refused. Configured base paths must percent-encode Unicode and spaces.
• The output does not classify visibility or prove content is public. No skills, sandbox configuration, existing version numbers or CHANGELOG are changed.

AI disclosure

AI-generated PR description.
Claude Code assisted the initial prototype; Codex (GPT-6) assisted revisions, tests, validation and PR preparation.
The author has manually reviewed the implementation and all follow-up fixes through eee77046 and takes responsibility for this contribution.