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