REUSE-WP-0018 T01/T02/T04/T06: plan-check deterministic matching + State Hub bridge

T01: specs/PlanCheck.md design doc, plan-check-result.schema.json and
reuse-event.schema.json (the latter shared with WP-0019's reuse telemetry).

T02: reuse_surface/plan_check.py + 'reuse-surface plan-check' CLI command.
Deterministic token-Jaccard matching against registry/indexes/federated.yaml
(reuses overlaps.py's TOKEN_RE rather than a second scoring method), with
reuse/extend/new verdicts, markdown and --format json output, staleness
warning, and --record-outcome JSONL telemetry.

T04: reuse_surface/statehub_bridge.py bridges plan-check 'new' verdicts to
State Hub capability requests (--file-request) and surfaces open requests
with no matching capability (report gaps --check-capability-requests, opt-in
to stay offline-safe). Verified against the live local State Hub API;
status field (not catalog_entry_id presence) is the correct open/closed
signal, and the list endpoint needs a longer timeout than the health check
(~7s observed with 5 rows).

T06: docs (tools/README.md, RegistryFederation.md, SCOPE.md,
IntentScopeGapAnalysis.md priority 29) and an informational CI smoke step.

T03 (LLM rerank) not started -- llm-connect isn't running on this
workstation. T05 (ecosystem rollout) remains blocked: WP-0017 has drafted
entries for all 61 repos but they're still local-only pending its own T05
push/publish pass, so the federated index isn't yet worth rolling out
plan-check as ecosystem convention.

16 new tests, all mocked -- no network calls in the default test run.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

tools/README.md

@@ -51,6 +51,28 @@ reuse-surface overlaps
 reuse-surface overlaps --threshold 0.35
 ```
 
+### plan-check
+
+Query-before-build check (REUSE-WP-0018): match a draft workplan or a free
+intent against the federated capability index before starting new work.
+Deterministic token matching against `registry/indexes/federated.yaml`;
+advisory only — never blocks workplan creation. See `specs/PlanCheck.md`.
+
+```bash
+reuse-surface plan-check workplans/XXX-WP-0042-something.md
+reuse-surface plan-check --intent "parse invoices and file evidence"
+reuse-surface plan-check --intent "..." --format json
+reuse-surface plan-check --intent "..." --record-outcome reused
+reuse-surface plan-check --intent "..." --file-request --requesting-domain infotech
+```
+
+`reuse|extend|new` verdict from `--reuse-threshold`/`--extend-threshold`
+(defaults 0.45/0.22). `--record-outcome` appends to
+`registry/telemetry/plan-check-events.jsonl` (schema shared with
+REUSE-WP-0019's reuse telemetry). `--file-request` files a State Hub
+capability request on a `new` verdict (requires the hub reachable at
+`127.0.0.1:8000`; degrades gracefully offline).
+
 ### catalog
 
 Generate human-readable catalog artifacts (UC-RS-018).
@@ -110,8 +132,14 @@ Run the service locally: `REUSE_SURFACE_TOKEN=dev-token reuse-surface serve`
 reuse-surface report gaps
 reuse-surface report gaps --format json
 reuse-surface report gaps --roster registry/federation/local-repo-roster.yaml
+reuse-surface report gaps --check-capability-requests
 ```
 
+`--check-capability-requests` (REUSE-WP-0018-T04) also lists open State Hub
+capability requests with no matching federated capability; requires the hub
+reachable at `127.0.0.1:8000` and degrades gracefully (prints "skipped") when
+it isn't. Off by default so `report gaps` stays fast and offline-safe.
+
 Workstation roster report: publish blockers, empty scaffolds, seed-ready repos,
 and local index owner stubs pending dedup.