Add workplans WP-0017..0019: coverage campaign, plan-check loop, Forgejo automation + telemetry

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

workplans/REUSE-WP-0018-plan-check-consumption-loop.md

@@ -0,0 +1,192 @@
+---
+id: REUSE-WP-0018
+type: workplan
+title: "plan-check: close the consumption loop for capability reuse"
+domain: infotech
+repo: reuse-surface
+status: proposed
+owner: claude-code
+topic_slug: helix-forge
+created: "2026-07-06"
+updated: "2026-07-06"
+---
+
+# plan-check: close the consumption loop for capability reuse
+
+The registry is write-mostly: nothing nudges an agent planning work in a
+sibling repo to query the federated index before building. The State Hub has a
+`request_capability` / `list_capability_requests` flow, but it is not bridged
+to reuse-surface data. This workplan adds the **query-before-build** step to
+the ecosystem: a `plan-check` command that matches a draft workplan or intent
+text against federated capabilities, wired into every repo's session protocol,
+with a two-way bridge to State Hub capability requests.
+
+This is the highest-leverage coherence mechanism: it is what stops 61 repos
+from independently reinventing the same thing.
+
+**Depends on REUSE-WP-0017** for meaningful match rates — plan-check against a
+mostly-empty index produces noise and erodes trust. T01–T03 (design +
+implementation) can proceed in parallel with the coverage campaign; the
+ecosystem rollout (T05) waits for coverage.
+
+## Proposed CLI surface
+
+```bash
+# Match a draft workplan against the federated index
+reuse-surface plan-check workplans/XXX-WP-0042-something.md
+
+# Free-text intent
+reuse-surface plan-check --intent "parse invoices from email and file evidence"
+
+# Agent-consumable output
+reuse-surface plan-check --format json workplans/XXX-WP-0042.md
+
+# Record the outcome (feeds R-axis evidence, WP-0019)
+reuse-surface plan-check ... --record-outcome reused|extended|new
+```
+
+**Verdict classes per match:** `reuse` (capability covers the need — link it),
+`extend` (close scope — extend instead of duplicating), `new` (no match —
+proceed, optionally file a capability request). Output includes capability id,
+maturity vector, owning repo, and consumer guidance.
+
+## Design principles
+
+1. **Deterministic core, LLM assist optional** — keyword/scope/relation
+   matching against index rows works without llm-connect; semantic matching
+   via llm-connect improves recall when available (same optional-backend
+   pattern as WP-0016).
+2. **Advisory, not blocking** — plan-check informs; it never vetoes a
+   workplan. Adoption comes from usefulness plus protocol convention, not
+   gates.
+3. **One line in the session protocol** — sibling integration is a single
+   instruction in the shared `.claude/rules/` template: run plan-check before
+   creating a workplan. No per-repo bespoke wiring.
+4. **Every check is a data point** — plan-check invocations and recorded
+   outcomes are the raw material for reuse telemetry (WP-0019-T04).
+
+## Dependencies
+
+| Dependency | Owner | Notes |
+|---|---|---|
+| REUSE-WP-0017 coverage | reuse-surface | rollout gate for T05 |
+| federated.yaml freshness | reuse-surface | improved by WP-0019 auto-recompose |
+| llm-connect | llm-connect | optional semantic matching backend |
+| State Hub capability-request API | state-hub | `request_capability`, `list_capability_requests` |
+| .claude/rules template propagation | the-custodian / repo-seed | mechanism for T05 rollout |
+
+---
+
+## Design Matching Semantics And Verdict Model
+
+```task
+id: REUSE-WP-0018-T01
+status: todo
+priority: high
+```
+
+Design doc `specs/PlanCheck.md`:
+
+- Input model: workplan file (frontmatter + body) vs free intent text
+- Match pipeline: token/keyword scoring over id, name, scope, guidance →
+  relation expansion → optional llm-connect semantic rerank
+- Verdict thresholds and tie-breaking (maturity vector as rank signal:
+  prefer higher D/A when scopes tie)
+- JSON output schema (`schemas/plan-check-result.schema.json`)
+- Outcome-recording format (append-only JSONL under `registry/telemetry/`,
+  schema shared with WP-0019-T04)
+
+## Implement Deterministic plan-check
+
+```task
+id: REUSE-WP-0018-T02
+status: todo
+priority: high
+```
+
+- `reuse_surface/plan_check.py` + CLI command per T01 spec, no-LLM path
+- Reads `registry/indexes/federated.yaml` (fall back to local index; warn on
+  stale `updated`)
+- Markdown report for TTY; `--format json` for agents
+- Pytest: fixture index with known reuse/extend/new cases; workplan-file and
+  intent-text inputs
+
+## Add llm-connect Semantic Rerank
+
+```task
+id: REUSE-WP-0018-T03
+status: todo
+priority: medium
+```
+
+- Optional rerank/expansion stage via `LLM_CONNECT_URL` (reuse
+  `llm_bridge.py`); schema-constrained JSON, graceful skip when unset
+- Confidence surfaced per match; deterministic matches always listed first
+- Pytest with mocked llm-connect (valid + malformed responses)
+
+## Bridge State Hub Capability Requests
+
+```task
+id: REUSE-WP-0018-T04
+status: todo
+priority: medium
+```
+
+Two directions:
+
+- **new → request:** on a `new` verdict, offer (`--file-request` /
+  interactive prompt) to create a State Hub capability request with the
+  intent text and searched terms
+- **request → gap:** `report gaps` gains a section listing open State Hub
+  capability requests with no matching federated capability (HTTP against
+  `http://127.0.0.1:8000`, degrade gracefully offline)
+- Matched requests can be marked resolved with a pointer to the capability id
+
+## Ecosystem Rollout: Session-Protocol Integration
+
+```task
+id: REUSE-WP-0018-T05
+status: wait
+priority: high
+```
+
+Blocked on WP-0017 coverage (index must be worth querying). 
+
+- Draft the one-line convention for the shared session-protocol/workplan
+  rules: *"Before creating a workplan, run `reuse-surface plan-check` on the
+  draft and record the verdict in the workplan frontmatter
+  (`reuse_check: reuse|extend|new — <capability-id?>`)"*
+- Coordinate propagation with the-custodian rules template mechanism
+  (fix-consistency / repo-seed) — send State Hub message to custodian agent
+- Add `reuse_check` frontmatter to this repo's workplan convention as the
+  reference implementation
+
+## Docs, CI, SCOPE
+
+```task
+id: REUSE-WP-0018-T06
+status: todo
+priority: low
+```
+
+- `tools/README.md` command reference; `docs/RegistryFederation.md` consumer
+  section; `SCOPE.md` "What Is Possible Now"
+- CI: informational `plan-check --intent "smoke test" --format json` run
+- Gap-analysis note: consumption loop status flips from missing to shipped
+
+---
+
+## Acceptance
+
+- [ ] `plan-check` returns reuse/extend/new verdicts for workplan files and intent text, with and without llm-connect
+- [ ] JSON output validates against the published schema
+- [ ] `new` verdicts can file State Hub capability requests; `report gaps` lists unmatched open requests
+- [ ] Session-protocol convention drafted and propagation agreed with the-custodian
+- [ ] reuse-surface itself records `reuse_check` in new workplans (dogfood)
+
+## Out of scope
+
+- Blocking/gating workplan creation on plan-check results
+- Reuse telemetry aggregation and R-axis evidence (WP-0019)
+- Embedding-based matching (llm-connect rerank only)
+- Editing sibling repos' rules files directly (owned by template propagation)