diff --git a/workplans/REUSE-WP-0017-capability-coverage-campaign.md b/workplans/REUSE-WP-0017-capability-coverage-campaign.md new file mode 100644 index 0000000..f0f325b --- /dev/null +++ b/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 `~//` | + +## 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..`), 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`) diff --git a/workplans/REUSE-WP-0018-plan-check-consumption-loop.md b/workplans/REUSE-WP-0018-plan-check-consumption-loop.md new file mode 100644 index 0000000..82cf6a1 --- /dev/null +++ b/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 — `)"* +- 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) diff --git a/workplans/REUSE-WP-0019-forgejo-automation-and-telemetry.md b/workplans/REUSE-WP-0019-forgejo-automation-and-telemetry.md new file mode 100644 index 0000000..a3654ba --- /dev/null +++ b/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 --to ` + 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)