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

- `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
state_hub_task_id: "9040505a-238e-4815-ae1a-8c5f8c12afa9"
```

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

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
state_hub_task_id: "c232a669-b263-4978-a8b1-3721b8bfaa68"
```

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

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