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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
REUSE-WP-0018	workplan	plan-check: close the consumption loop for capability reuse	infotech	reuse-surface	ready	claude-code	helix-forge	2026-07-06	2026-07-06	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

# 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

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

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

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

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

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

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)