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>

schemas/plan-check-result.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://reuse-surface.local/schemas/plan-check-result.schema.json",
+  "title": "PlanCheckResult",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["query", "verdict", "top_score", "matches"],
+  "properties": {
+    "query": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "text"],
+      "properties": {
+        "source": {"type": "string", "enum": ["workplan", "intent"]},
+        "text": {"type": "string", "minLength": 1},
+        "workplan_id": {"type": ["string", "null"]},
+        "workplan_path": {"type": ["string", "null"]}
+      }
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["reuse", "extend", "new"]
+    },
+    "top_score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "matches": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "score", "kind"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^capability\\.[a-z0-9]+(\\.[a-z0-9-]+)+$"
+          },
+          "score": {"type": "number", "minimum": 0, "maximum": 1},
+          "vector": {"type": ["string", "null"]},
+          "owner": {"type": ["string", "null"]},
+          "summary": {"type": ["string", "null"]},
+          "kind": {
+            "type": "string",
+            "enum": ["deterministic", "llm", "related"]
+          }
+        }
+      }
+    },
+    "federated_index_updated": {"type": ["string", "null"]},
+    "federated_index_stale_warning": {"type": ["string", "null"]}
+  }
+}

schemas/reuse-event.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://reuse-surface.local/schemas/reuse-event.schema.json",
+  "title": "ReuseEvent",
+  "description": "One line of registry/telemetry/plan-check-events.jsonl, or one POST /v1/reuse-events body (REUSE-WP-0019-T04). Shared schema so plan-check's local fallback and the hub's telemetry store never diverge.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ts", "consumer_repo", "verdict", "source"],
+  "properties": {
+    "ts": {"type": "string", "format": "date-time"},
+    "consumer_repo": {"type": "string", "minLength": 1},
+    "capability_id": {
+      "type": ["string", "null"],
+      "pattern": "^capability\\.[a-z0-9]+(\\.[a-z0-9-]+)+$"
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["reuse", "extend", "new"]
+    },
+    "outcome": {
+      "type": ["string", "null"],
+      "enum": ["reused", "extended", "new", "skipped", null]
+    },
+    "source": {
+      "type": "string",
+      "enum": ["plan-check", "manual", "hub"]
+    }
+  }
+}