Add reuse-surface report gaps resolver

workplans/ACTIVITY-WP-0013-reuse-surface-report-gaps-resolver.md

@@ -0,0 +1,78 @@
+---
+id: ACTIVITY-WP-0013
+type: workplan
+title: "Reuse Surface Report Gaps Resolver"
+domain: custodian
+repo: activity-core
+status: finished
+owner: codex
+topic_slug: activity-core
+created: "2026-06-18"
+updated: "2026-06-18"
+state_hub_workstream_id: "01e68dfd-b146-4aef-a575-2d3b178ca5c2"
+---
+
+# Reuse Surface Report Gaps Resolver
+
+Implement the R2 handoff from kaizen-agentic (`bffa224c`) so the
+`reuse_surface_report_gaps` shell context source populates
+`context.gaps` for the Coulomb daily registry hygiene sweep.
+
+## Register Shell Resolver Query
+
+```task
+id: ACTIVITY-WP-0013-T01
+status: done
+priority: high
+state_hub_task_id: "a6e1fc5c-7b42-436d-914e-4d605cb6f329"
+```
+
+Add a dedicated reuse-surface context resolver module and register
+`reuse_surface_report_gaps` on the `shell` resolver path while preserving
+the existing kaizen shell query behavior.
+
+## Implement Batch And Signal Semantics
+
+```task
+id: ACTIVITY-WP-0013-T02
+status: done
+priority: high
+state_hub_task_id: "229cf285-8388-471d-95fd-08400db1553e"
+```
+
+Load the Coulomb rollout roster, select active repos with a persisted
+round-robin cursor, resolve repo roots from State Hub host paths, run
+`reuse-surface report gaps --format json`, and emit gap records for the
+enabled registry hygiene signals.
+
+## Cover Required And Optional Failure Modes
+
+```task
+id: ACTIVITY-WP-0013-T03
+status: done
+priority: high
+state_hub_task_id: "85b5c7d4-40e1-4945-8ada-1dff2363c194"
+```
+
+Ensure missing required dependencies fail visibly while optional resolver
+sources bind an empty `context.gaps` list. Add unit coverage for fixture
+rollout data, mocked CLI JSON, resolver binding, and `hygiene_signal`
+rule gating.
+
+## Smoke Real Coulomb Rollout
+
+```task
+id: ACTIVITY-WP-0013-T04
+status: done
+priority: medium
+state_hub_task_id: "6a5446ed-b4ec-4693-b508-65415571d834"
+```
+
+Run a live resolver smoke against
+`/home/worsch/coulomb-loop/loops/registry-hygiene/rollout.yaml` using a
+temporary round-robin cursor. The real active rollout produced five gaps,
+including one for `reuse-surface` with `hygiene_signal: stale_sbom`.
+The smoke supplied `reuse_surface_bin:
+/home/worsch/reuse-surface/.venv/bin/reuse-surface` and
+`runner_host: bnt-lap001`; the worker environment or definition params must
+provide equivalent values before enabling the production sweep.