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>

docs/IntentScopeGapAnalysis.md

@@ -202,9 +202,11 @@ See §4 and archived workplans `workplans/archived/`.
 | 26 | Federated ID deduplication | Per-owner removal from reuse-surface index | **Closed** (WP-0015-T02) |
 | 27 | Planning analytics + standardization | Gap report or standardization tracker | **Partial** — gap report shipped (T03); tracker deferred |
 | 28 | Registry maintenance automation | Interactive `maintain` + `--auto` with llm-connect | **Closed** (WP-0016) |
+| 29 | Consumption loop (query-before-build) | `plan-check` command + State Hub capability-request bridge | **Partial** — deterministic matching (T02) and the request bridge (T04) shipped; LLM semantic rerank (T03) and ecosystem session-protocol rollout (T05) remain open, T05 gated on REUSE-WP-0017 coverage reaching the *published* federated index, not just local drafts |
 
 **Workplan:** `workplans/REUSE-WP-0016-interactive-registry-maintain.md` (priority 28);
-`workplans/REUSE-WP-0015-federation-polish-and-planning-analytics.md` (25–27)  
+`workplans/REUSE-WP-0015-federation-polish-and-planning-analytics.md` (25–27);
+`workplans/REUSE-WP-0018-plan-check-consumption-loop.md` (priority 29)  
 **Assessment:** `history/2026-06-16-intent-scope-assessment.md`
 
 **Follow-up docs:**
@@ -235,4 +237,5 @@ See §4 and archived workplans `workplans/archived/`.
 | 2026-06-16 | WP-0014 closed priority 18; 60 workstation repos |
 | 2026-06-16 | **SCOPE refresh + full INTENT success-criteria mapping**; priorities 25–27 proposed |
 | 2026-06-16 | Assessment persisted; **REUSE-WP-0015** created for priorities 25–27 |
-| 2026-06-16 | **REUSE-WP-0016** closed priority 28 (interactive `maintain`, `--auto`, templates) |
+| 2026-06-16 | **REUSE-WP-0016** closed priority 28 (interactive `maintain`, `--auto`, templates) |
+| 2026-07-07 | **REUSE-WP-0018** partially closed priority 29 (`plan-check` deterministic matching + State Hub capability-request bridge; LLM rerank and ecosystem rollout remain open) |

docs/RegistryFederation.md

@@ -297,6 +297,23 @@ Register published raw index URLs on the hub, or enable a `url` source in
 endpoint requires a token. Agents without sibling repo clones can discover
 capabilities from the hub or from HTTP sources plus the local index.
 
+### Query before building (`plan-check`)
+
+Before drafting a new workplan, run `reuse-surface plan-check` (REUSE-WP-0018)
+against a draft workplan file or a free-text intent. It matches your intent
+against `registry/indexes/federated.yaml` and returns a `reuse | extend | new`
+verdict — advisory only, never a gate:
+
+```bash
+reuse-surface plan-check workplans/XXX-WP-NNNN-something.md
+reuse-surface plan-check --intent "parse invoices and file evidence"
+```
+
+On a `new` verdict, `--file-request` bridges the gap to a State Hub
+capability request so other domains can see the unmet need; `report gaps
+--check-capability-requests` surfaces open requests with no matching
+federated capability. See `specs/PlanCheck.md` for the full design.
+
 ## Relation graphs
 
 ```bash