traverse-framework / traverse-framework/registry

Publish capability: core.risk-band (risk score band from structured signals)

Open
#497 0 comments 0 reactions 0 assignees View on GitHub
enhancement good first issue help wanted no-spec-needed
Dominant language
Rust
Stars
1
Forks
1
Avg merge
1h 17m
Merged PRs (30d)
217

Description

## Why

Agent pipelines accumulate structured risk signals (velocity, device reputation bucket, amount, country mismatch flags). `uncertainty.score` is for coverage/pending fractions — different domain. We need a **business risk band** capability: deterministic score → band, so the agent proposes signals and the capability/runtime decides the band.

## One-PR ask

Publish **`core.risk-band@1.0.0`**:

**Inputs:**
- `signals`: object with numeric/boolean fields under a fixed schema you document, e.g. amount, velocity_1h, country_mismatch, device_reputation (0..1), prior_chargebacks — keep the v1 signal set small and frozen in the contract
- `weights`: versioned weights object aligning to those signals (caller-supplied; capability does not fetch)
- `bands`: ordered thresholds e.g. low/medium/high with max_score cutoffs
- `policy_version`: string

**Outputs:**
- `score`: number (document 0–100 or 0–1000)
- `band`: string (from bands)
- `policy_version`: string
- `contributions`: array of `{ "signal", "weighted" }` (deterministic)
- `ok`: boolean
- `reason_code`: e.g. `ok` | `invalid_weights` | `invalid_bands` | `missing_signal`

**Behavior:** Weighted sum (or documented formula), clamp, map to band. Missing required signal or invalid bands → fail closed.

Follow [`CONTRIBUTING.md`](https://github.com/traverse-framework/registry/blob/main/CONTRIBUTING.md) and [`capabilities/README.md`](https://github.com/traverse-framework/registry/blob/main/capabilities/README.md) publish checklist.

- Include `capability-src/` with real Rust tests meeting registry coverage gates (`functions` 100%, lines/regions ≥ 95%)
- Use `traverse-cli capability publish` (or the documented scaffold) so `artifact.digest` / `artifact.url` survive
- Declare `authoring.method` (`human` or `llm-assisted`)
- Ensure every `use_cases[].persona_ref` resolves (scaffold personas if needed)
- Run `bash scripts/ci/pre_pr_check.sh ` before opening
- One capability per PR; branch from `origin/main`, not another `publish/*` branch

**Apps are not ready — publish the capability only.** No app wiring, no demo product surface.

## Out of scope

- ML models / embeddings / free-text risk narratives
- Overlap with `uncertainty.score` semantics
- Case management / ticketing side effects

## Done when

- CI green; published in next index
- Tests: low/medium/high bands, missing signal fail closed, contribution trace stable

## Host / deps notes

**Pure WASM.** No connector, no model, no network. Distinct from `uncertainty.score`.

## Labels

`help wanted` · `good first issue` · `enhancement` · `no-spec-needed`

Contributor guide

Open the contributing guide

Research direction

Read CONTRIBUTING.md and capabilities/README.md, then inspect the documented scaffold or run traverse-cli capability publish to understand the expected layout. Add the capability and real Rust tests under capability-src/, covering the listed band, missing-signal, and contribution-trace cases. Run bash scripts/ci/pre_pr_check.sh ; done means CI is green and the capability is published with its required metadata and artifact fields.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, wasm
Domain
backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.