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

---
id: REUSE-WP-0018
type: workplan
title: "plan-check: close the consumption loop for capability reuse"
domain: infotech
repo: reuse-surface
status: active
owner: claude-code
topic_slug: helix-forge
created: "2026-07-06"
updated: "2026-07-06"
state_hub_workstream_id: "cd8683ff-6e6c-4f6c-a62f-565bd55113ea"
---

# 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: done
priority: high
state_hub_task_id: "c7b3407a-2b9d-46ba-ae9c-7ab12235f0ba"
```

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: done
priority: high
state_hub_task_id: "24911d0e-41bc-4c8c-a39a-7dc8ec65d8c6"
```

Implemented in `reuse_surface/plan_check.py` + `plan-check` CLI command:

- Reuses `overlaps.py`'s `TOKEN_RE`/Jaccard approach rather than a second
  scoring method (per spec §4)
- Reads `registry/indexes/federated.yaml`, falls back to the local index,
  warns when the composed index is >14 days stale
- Markdown (TTY default) and `--format json` (validated against
  `schemas/plan-check-result.schema.json`)
- 11 pytest cases: verdict thresholds, workplan-file parsing, intent-text
  parsing, tie-window vector ranking, staleness warning, CLI wiring
- `--record-outcome` appends to `registry/telemetry/plan-check-events.jsonl`
  per the shared `schemas/reuse-event.schema.json` (WP-0019-T04 will post the
  same shape to the hub)

## Add llm-connect Semantic Rerank

```task
id: REUSE-WP-0018-T03
status: todo
priority: medium
state_hub_task_id: "9040505a-238e-4815-ae1a-8c5f8c12afa9"
```

**Not started** — `llm-connect` is not running on this workstation
(same gap noted in REUSE-WP-0017-T04's drafting cohorts). Deterministic
`plan-check` (T02) is fully usable without it; this task adds the optional
rerank on top when a backend is available.

- 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: done
priority: medium
state_hub_task_id: "8249dca7-18ca-4150-9671-ca87e6a5ad88"
```

Implemented in `reuse_surface/statehub_bridge.py` against the live local
State Hub HTTP API (`http://127.0.0.1:8000`, confirmed reachable):

- **new → request:** `plan-check --file-request` files a State Hub
  capability request (`POST /capability-requests/`) on a `new` verdict
- **request → gap:** `report gaps --check-capability-requests` lists open
  requests (`GET /capability-requests/`, filtered on `status` — a request
  can carry a `catalog_entry_id` while still `requested`/routed, so status
  is the correct open/closed signal, not `catalog_entry_id` presence).
  Opt-in flag so `report gaps` stays fast and offline-safe by default
- Both degrade to `None`/graceful-skip when the hub is unreachable; neither
  ever blocks the primary command
- List endpoint observed taking ~7s in production with only 5 rows; uses a
  20s timeout distinct from the 5s health-check timeout
- 5 pytest cases with the hub client fully mocked (never hits the network
  in the default test run)
- **Not done:** marking matched requests resolved with a pointer to the
  capability id — deferred, no current caller needs it yet

## Ecosystem Rollout: Session-Protocol Integration

```task
id: REUSE-WP-0018-T05
status: wait
priority: high
state_hub_task_id: "c232a669-b263-4978-a8b1-3721b8bfaa68"
```

Blocked on WP-0017 coverage reaching the *published* federated index, not
just local drafts. WP-0017-T04 has drafted entries for all 61 roster repos
(coverage 61/61 locally), but those commits are still local-only in each
sibling repo pending WP-0017-T05's human review and push — `federated.yaml`
still only carries the original 24 entries. Re-check this gate once
WP-0017-T05 pushes and recomposes.

- 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: done
priority: low
state_hub_task_id: "ff0a91eb-cc41-487b-b726-8c2f84860399"
```

- `tools/README.md` command reference for `plan-check` and
  `report gaps --check-capability-requests`; `docs/RegistryFederation.md`
  "Query before building" consumer section; `SCOPE.md` "What Is Possible Now"
- CI: informational `plan-check --intent "smoke test" --format json` run
  added to `.gitea/workflows/ci.yml`
- `docs/IntentScopeGapAnalysis.md`: priority 29 added, marked **Partial**
  (T02/T04 shipped; T03/T05 remain open — not flipped fully to "shipped"
  since the ecosystem rollout hasn't happened yet)

---

## Acceptance

- [x] `plan-check` returns reuse/extend/new verdicts for workplan files and intent text (without llm-connect — T03 rerank not built, not available on this workstation)
- [x] JSON output validates against the published schema
- [x] `new` verdicts can file State Hub capability requests; `report gaps` lists unmatched open requests
- [ ] Session-protocol convention drafted and propagation agreed with the-custodian (blocked, see T05)
- [ ] reuse-surface itself records `reuse_check` in new workplans (dogfood) — deferred to T05 rollout

## 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)