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-0017-capability-coverage-campaign.md

@@ -0,0 +1,190 @@
+---
+id: REUSE-WP-0017
+type: workplan
+title: "Capability coverage campaign: seed or explicitly close all empty scaffolds"
+domain: infotech
+repo: reuse-surface
+status: proposed
+owner: claude-code
+topic_slug: helix-forge
+created: "2026-07-06"
+updated: "2026-07-06"
+---
+
+# Capability coverage campaign: seed or explicitly close all empty scaffolds
+
+The federation infrastructure is complete (61/61 repos established and
+hub-registered, WP-0014/0015), but **51 of 61 roster repos publish zero
+capabilities**. The federated index carries 24 capabilities, concentrated in a
+handful of custodian-core repos. A registry that answers most queries with
+"nothing found" trains agents to stop querying — content coverage is the
+prerequisite for the consumption loop (REUSE-WP-0018) and the automation loop
+(REUSE-WP-0019).
+
+**Goal:** every roster repo either publishes ≥1 capability entry or carries an
+explicit, machine-readable `no-reusable-capability` marker with a rationale.
+"Empty" becomes informative instead of ambiguous.
+
+**Baseline:** 10/61 repos with ≥1 capability; 51 empty scaffolds; 7 seed-ready
+(gap report 2026-07-06).
+**Target:** 0 ambiguous scaffolds; coverage ratio surfaced in `report gaps`
+and CI.
+
+## Approach
+
+1. **Classify before drafting.** Sweep the 51 empty scaffolds and bucket each:
+   `has-capability` (draft entries) vs `no-capability` (mark explicitly —
+   experiments, forks, canon/docs-only repos, probes).
+2. **Draft with existing tooling.** `reuse-surface establish --discover` +
+   llm-connect per repo produces first-pass entries at honest low maturity
+   (typically D1–D2 / A0–A1); no invented evidence.
+3. **Human review gate.** Drafts land as branches/commits flagged for review;
+   nothing publishes to the federated index without a human pass (same pattern
+   as CUST-WP-0050 repo classification).
+4. **Publish + recompose.** After review: publish-check, hub state refresh,
+   `federation compose`, catalog/graph regeneration.
+
+## Dependencies
+
+| Dependency | Owner | Notes |
+|---|---|---|
+| llm-connect | llm-connect | drafting backend for `establish --discover` |
+| local-repo-roster.yaml | reuse-surface | 61-repo roster, sweep source of truth |
+| .repo-classification.yaml | the-custodian | classification signals for the no-capability bucket |
+| config-atlas publish fix | config-atlas | 303 publish blocker (T06) |
+| Sibling repo write access | Bernd | drafts commit into sibling checkouts at `~/<slug>/` |
+
+## Design decisions
+
+- **`no-capability` marker format:** a `registry/NO_CAPABILITIES.md` file with
+  frontmatter (`reason`, `reviewed`, `revisit`) in the sibling repo, plus a
+  `capability_status: none` field in the roster row. `report gaps` treats
+  marked repos as resolved, not empty.
+- **Honest maturity floor:** first-pass entries never claim above D2/A2/C2/R1
+  without cited on-disk evidence (WP-0016 evidence gates apply).
+- **Batch execution:** repos are processed in cohorts of ~10 via
+  `/ralph-workplan`; each cohort ends with validate + gap-report delta.
+
+---
+
+## Extend Gap Report And Roster For Explicit No-Capability Status
+
+```task
+id: REUSE-WP-0017-T01
+status: todo
+priority: high
+```
+
+- Add `capability_status: has | none | pending` to roster schema and
+  `local-repo-roster.yaml` handling (default `pending` for empty scaffolds)
+- `report gaps`: split "Empty scaffolds" into "Unclassified" and
+  "Explicitly none (n)"; add a coverage ratio headline
+  (`repos with capabilities or explicit none / total`)
+- Define `registry/NO_CAPABILITIES.md` template in `templates/`
+- Pytest coverage for both report paths
+
+## Classification Sweep Of The 51 Empty Scaffolds
+
+```task
+id: REUSE-WP-0017-T02
+status: todo
+priority: high
+```
+
+- For each empty-scaffold repo: read INTENT/SCOPE/README + top-level layout,
+  bucket `has-capability` vs `no-capability` with a one-line rationale
+- Output: `history/2607xx-coverage-classification.md` table (repo, bucket,
+  rationale, candidate capability ids for the has bucket)
+- Cross-check against `.repo-classification.yaml` where available
+- **Human review checkpoint:** Bernd confirms the bucket split before T03/T04
+
+## Mark No-Capability Repos
+
+```task
+id: REUSE-WP-0017-T03
+status: wait
+priority: medium
+```
+
+Blocked on T02 review. For each confirmed `no-capability` repo:
+
+- Write `registry/NO_CAPABILITIES.md` from template into the sibling checkout
+- Set `capability_status: none` in the roster
+- Commit in sibling repo with a uniform message referencing this workplan
+
+## Draft Capability Entries For Has-Capability Repos
+
+```task
+id: REUSE-WP-0017-T04
+status: wait
+priority: high
+```
+
+Blocked on T02 review. In cohorts of ~10 repos:
+
+- `reuse-surface establish --discover` with llm-connect per repo
+- Manual tightening: id namespace (`capability.<domain>.<verb>`), scope
+  boundary, honest vectors, relations to existing federated capabilities
+- `reuse-surface validate` + `overlaps` check per cohort (no duplicate
+  semantics vs the existing 24)
+- Drafts committed in sibling repos, flagged for human review; roster
+  `capability_status: has`
+
+## Human Review And Publish Pass
+
+```task
+id: REUSE-WP-0017-T05
+status: wait
+priority: high
+```
+
+- Bernd reviews drafted entries per cohort (maturity honesty, scope, ids)
+- After approval: sibling repos push; `establish --publish-check` per repo;
+  hub registrations refreshed where raw URLs changed
+- `reuse-surface federation compose` + catalog + graph regeneration in this repo
+
+## Fix config-atlas Publish Blocker
+
+```task
+id: REUSE-WP-0017-T06
+status: todo
+priority: medium
+```
+
+- Diagnose the 303 on the config-atlas raw index URL (same block class as the
+  earlier state-hub/feature-control issue)
+- Note: likely interacts with the Gitea→Forgejo host transition
+  (REUSE-WP-0019-T01); if the new Forgejo raw URL scheme fixes it, record that
+  and close here
+- Target: 61/61 publish pass
+
+## Closeout: Coverage Metrics, Docs, SCOPE Update
+
+```task
+id: REUSE-WP-0017-T07
+status: wait
+priority: low
+```
+
+- `report gaps` shows 0 unclassified scaffolds; record final coverage ratio
+- Update `SCOPE.md` Current State (capability count, coverage), regenerate
+  `docs/CapabilityCatalog.md`, graph, search catalog
+- `history/` milestone note; progress event + fix-consistency
+
+---
+
+## Acceptance
+
+- [ ] Every roster repo is `has` or `none` — zero `pending`
+- [ ] All `none` repos carry a reviewed `registry/NO_CAPABILITIES.md`
+- [ ] Federated index capability count reflects the seeded entries; 0 collision warnings
+- [ ] 61/61 publish pass (config-atlas unblocked)
+- [ ] Coverage ratio visible in `report gaps` and CI output
+- [ ] No entry claims maturity without on-disk evidence citations
+
+## Out of scope
+
+- Consumption/plan-check tooling (REUSE-WP-0018)
+- Forgejo webhooks/automation (REUSE-WP-0019)
+- Maturity promotions beyond honest first-pass levels
+- Multi-domain federation (all entries remain `helix_forge`)

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)

workplans/REUSE-WP-0019-forgejo-automation-and-telemetry.md

@@ -0,0 +1,179 @@
+---
+id: REUSE-WP-0019
+type: workplan
+title: "Forgejo-native federation automation and reuse telemetry"
+domain: infotech
+repo: reuse-surface
+status: proposed
+owner: claude-code
+topic_slug: helix-forge
+created: "2026-07-06"
+updated: "2026-07-06"
+---
+
+# Forgejo-native federation automation and reuse telemetry
+
+Federation compose is on-demand and the hub serves whatever was last composed;
+roster sweeps are manual; reliability evidence is structural (CI exists) rather
+than observed (someone reused it and it worked). This workplan makes the
+registry **live** (event-driven recompose) and **evidence-backed** (reuse
+telemetry feeding the R axis).
+
+**Platform constraint:** the forge is transitioning **Gitea → Forgejo**. All
+new automation attaches to Forgejo (webhooks, Forgejo Actions, API tokens) —
+nothing new is built against Gitea. Existing raw URLs
+(`https://gitea.coulomb.social/...`) and `.gitea/workflows/` must migrate or
+be made host-agnostic. Forgejo is Gitea-API-compatible, so migration is mostly
+host/path configuration, but every hardcoded `gitea.` reference is a liability.
+
+**Depends on:** REUSE-WP-0017 (content worth refreshing), REUSE-WP-0018-T01
+telemetry schema (shared). Closes SCOPE "not possible yet" item *automatic hub
+refresh* and moves reliability evidence beyond structural.
+
+## Design principles
+
+1. **Host-agnostic first** — a single `forge_base_url` configuration
+   (env/config + hub setting) replaces hardcoded hosts; the Forgejo cutover
+   becomes a one-line change per surface.
+2. **Webhook triggers, compose stays pull-based** — the webhook only marks the
+   hub's composed index stale and triggers recompose from published raw URLs;
+   no push-parsing of payloads into registry state.
+3. **Degrade to schedule** — if webhooks are unavailable, a scheduled Forgejo
+   Actions job recomposes on an interval; freshness is monitored either way.
+4. **Telemetry is append-only and low-ceremony** — reuse events are JSONL
+   facts (who consumed what, when, outcome); aggregation derives `reused_by`
+   relations and R-axis evidence citations, never hand-edited.
+
+## Dependencies
+
+| Dependency | Owner | Notes |
+|---|---|---|
+| Forgejo instance + admin | Bernd / infra | webhook config, org-level token, Actions runners |
+| Gitea→Forgejo cutover plan | infra | final hostname, raw URL scheme, redirect window |
+| Hub deployment (reuse.coulomb.social) | reuse-surface / railiance | new endpoint + config rollout |
+| REUSE-WP-0018-T01 | reuse-surface | shared telemetry/outcome schema |
+| plan-check adoption | ecosystem | telemetry volume comes from WP-0018-T05 rollout |
+
+---
+
+## Forge Host Abstraction And URL Migration Inventory
+
+```task
+id: REUSE-WP-0019-T01
+status: todo
+priority: high
+```
+
+- Inventory every hardcoded `gitea.coulomb.social` / `.gitea/` reference:
+  `sources.yaml` (60 raw URLs), hub registrations, establish/publish-check
+  defaults, docs, templates, CI workflows
+- Introduce `REUSE_SURFACE_FORGE_BASE_URL` (env + hub config); derive raw
+  index URLs from `{base}/{org}/{repo}/raw/{branch}/registry/indexes/capabilities.yaml`
+- Migration command: `reuse-surface federation migrate-host --from <old> --to <new>`
+  rewriting sources.yaml + hub registrations via the hub API
+- Check whether the config-atlas 303 (WP-0017-T06) is a symptom of the host
+  transition; coordinate findings
+- Tests: URL derivation, migrate-host dry-run
+
+## Hub Recompose Endpoint And Webhook Receiver
+
+```task
+id: REUSE-WP-0019-T02
+status: todo
+priority: high
+```
+
+- Hub service (`reuse_surface/serve`): `POST /v1/recompose` (token-auth) —
+  marks index stale and triggers recompose from registered raw URLs
+- `POST /v1/webhooks/forgejo`: validates Forgejo webhook signature
+  (`X-Forgejo-Signature`, secret from env), accepts push events, triggers
+  recompose only when the pushed commits touch `registry/indexes/`
+- Debounce/coalesce concurrent triggers; `GET /v1/federated` gains
+  `composed_at` + `stale` fields
+- Extend `specs/FederationHubAPI.md`; pytest with signed fixture payloads
+
+## Forgejo Webhook Rollout And Scheduled Fallback
+
+```task
+id: REUSE-WP-0019-T03
+status: wait
+priority: medium
+```
+
+Blocked on T02 deploy and Forgejo instance availability.
+
+- Org-level Forgejo webhook (single config, all repos) → hub
+  `/v1/webhooks/forgejo`, push events only
+- Fallback: Forgejo Actions scheduled workflow (cron) in this repo calling
+  `POST /v1/recompose`; also serves repos during any Gitea-remnant window
+- Migrate this repo's CI `.gitea/workflows/ci.yml` → `.forgejo/workflows/ci.yml`
+  (Forgejo Actions; verify runner labels); document the pattern for siblings
+- Verify end-to-end: index change in a sibling repo → hub `composed_at`
+  advances without manual compose
+
+## Reuse Telemetry Store And Recording
+
+```task
+id: REUSE-WP-0019-T04
+status: todo
+priority: medium
+```
+
+- Implement the shared schema from WP-0018-T01: reuse events
+  `{ts, consumer_repo, capability_id, verdict, outcome?, source: plan-check|manual|hub}`
+- Hub: `POST /v1/reuse-events` (token-auth) + local JSONL fallback when hub
+  unreachable; `GET /v1/reuse-events?capability_id=` for aggregation
+- `plan-check --record-outcome` (WP-0018) posts here; manual
+  `reuse-surface record-reuse` for retroactive facts
+- Privacy/scope: repo slugs and capability ids only — no code, no secrets
+
+## Telemetry Aggregation Into R-Axis Evidence
+
+```task
+id: REUSE-WP-0019-T05
+status: wait
+priority: medium
+```
+
+Blocked on T04 plus initial event volume.
+
+- `reuse-surface report reuse`: per-capability consumer counts, outcomes,
+  last-used; feeds `reused_by` relation suggestions via the WP-0016
+  maintain/patch pipeline (evidence-gated, never silent promotion)
+- Maturity standard note: what observed-reuse evidence counts toward R2/R3+
+  (`specs/CapabilityMaturityStandard.md` amendment)
+- Catalog + graph surface consumer counts
+
+## Freshness Monitoring, Docs, SCOPE
+
+```task
+id: REUSE-WP-0019-T06
+status: todo
+priority: low
+```
+
+- `reuse-surface stats`: hub `composed_at` age + stale flag; CI informational
+  check warns when the hub index is older than N days
+- `docs/RegistryFederation.md` + `docs/deploy/reuse-kubernetes.md`: webhook
+  setup, recompose endpoint, Forgejo token handling (route credentials per
+  credential-routing rules — no secrets in repo)
+- `SCOPE.md`: flip "automatic hub refresh" to possible; update federation
+  posture
+
+---
+
+## Acceptance
+
+- [ ] No hardcoded forge host in code or sources.yaml; `migrate-host` tested
+- [ ] Push to a sibling repo's `registry/indexes/` recomposes the hub index without manual action (webhook), with scheduled fallback in place
+- [ ] This repo's CI runs on Forgejo Actions (`.forgejo/workflows/`)
+- [ ] Reuse events recordable via hub API and CLI; `report reuse` aggregates them
+- [ ] R-axis evidence rules for observed reuse documented in the maturity standard
+- [ ] Hub freshness visible (`composed_at`, stale flag) in API and stats
+
+## Out of scope
+
+- Operating the Forgejo instance or the Gitea→Forgejo data migration itself
+- Multi-replica/Postgres hub posture (separate managed-platform track)
+- Blocking CI gates on registry freshness in sibling repos
+- ActivityPub/Forgejo-native federation features (our federation layer stays raw-URL based)