Add riptide-assess skill: deterministic guided-sim risk assessment for Solana programs

skills/riptide-assess-skill/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Riptide
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills/riptide-assess-skill/README.md

@@ -0,0 +1,96 @@
+# Riptide Assess — Solana protocol risk-assessment skill
+
+A Claude Code skill that turns a Solana program repo into a reproducible
+risk assessment, backed by deterministic guided LiteSVM simulations of the real
+on-chain program.
+
+## Overview
+
+Founders shipping to mainnet, and the auditors reviewing them, need risk
+evidence that someone else can reproduce — not a vibe, not a one-off script that
+only ran on one laptop. Riptide answers that need by running **deterministic,
+guided LiteSVM simulations against the real program `.so`**: it constructs the
+external account bytes the program reads (oracle prices, attestations), drives
+the protocol's actual lifecycle under an exogenous stress swept over a declared,
+fixed-seed region, and records where the deciding metric moves. The output is an
+`assessment.md` / `assessment.json` plus an evidence pack and the exact commands
+to reproduce every figure.
+
+This is **simulation evidence over a declared region — not an audit signoff**,
+not formal verification, and not a mainnet prediction.
+
+## What it does
+
+One agent-led flow, **Detect → Scope → Setup → Run → Surface → Assess**:
+
+- **Detect** the protocol family (lending, AMM, perps, LST, stablecoin) from
+  semantics, source, and IDL evidence.
+- **Scope** what the guided sim must handle via the A–F trigger taxonomy — typed
+  enum/struct args, oracle-account byte construction, third-party (liquidator /
+  keeper) actors, multi-instruction sequences, dynamic `remaining_accounts`, CPI
+  bootstrapping — then ask at most three scoped questions.
+- **Setup** the project-owned Rust sim crate: author the adapter, generate the
+  crate, and fill the `TODO(setup)` seams with deterministic facts.
+- **Run** the fixed-seed sweep declared in `[sim.sweep]` — smoke first, then the
+  full sweep.
+- **Surface** the cartography root (`campaign-summary.json`,
+  `risk-surface.json`, `retention-manifest.json`) the assessment reads.
+- **Assess** — render `assessment.md` + `assessment.json` (plus an executive
+  brief), with a non-negotiable honesty discipline enforced as runtime gates
+  (positive control, real-program execution, determinism).
+
+## Install
+
+If `riptide --help` fails, install the CLI via the public installer — this works
+from any directory (idempotent, safe to re-run):
+
+```bash
+curl -fsSL https://riptide.run/install | sh
+```
+
+This skill also bundles an equivalent `install.sh` at its package root (it wraps
+the same installer); run `bash install.sh` only from within the skill's own
+directory.
+
+**Riptide is NOT on npm** — do not `npm i riptide`. The CLI scaffolds a
+project-owned Rust crate that builds against a vendored runtime (no separate
+engine binary), so the host needs:
+
+- `rustup` / `cargo` + `rustc`
+- `node >= 20` and `npm`
+- the Solana SBF toolchain (`cargo-build-sbf`, via the Anza/Solana install)
+
+Verify before doing anything else:
+
+```bash
+riptide --version     # expect v0.12.0 or newer
+riptide doctor        # static health check of the environment + adapter
+```
+
+## Structure
+
+```
+riptide-assess-skill/
+├── skill/
+│   ├── SKILL.md                 # Router: mission, prerequisites, CLI surface, flow
+│   ├── detect-and-scope.md      # Detect the family + the A–F trigger taxonomy
+│   ├── setup.md                 # Adapter, sim crate, deterministic setup seams
+│   ├── run-and-assess.md        # Run → Surface → Assess
+│   ├── family-library.md        # Per-family personas, invariants, stress scenarios
+│   ├── authoring-patterns.md    # Oracle bytes, third-party dispatch, sweep scaffold
+│   ├── honesty.md               # The non-negotiable honesty discipline + gates
+│   ├── worst-case-playbook.md   # Per-archetype worst case to hunt
+│   └── resources.md             # References + file index
+├── examples/
+│   └── assessment-input.json    # Example AssessmentInputs shape
+├── install.sh                   # Riptide CLI bootstrap (idempotent)
+├── README.md                    # This file
+└── LICENSE                      # MIT
+```
+
+The router (`skill/SKILL.md`) keeps the entry gate and the CLI surface inline,
+and links each step to its focused file for progressive disclosure.
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

skills/riptide-assess-skill/examples/assessment-input.json

@@ -0,0 +1,56 @@
+{
+  "_comment": "Example AssessmentInputs for `riptide assess <guided-sim-root> --input examples/assessment-input.json`. The skill authors a file like this from what the detect/scope/run steps established. All fields are optional — omitted fields are derived deterministically from the guided-sim cartography root. Adapt the values to your protocol; do not ship these placeholders verbatim.",
+  "protocol": {
+    "name": "example-lending"
+  },
+  "verdict": "needs_guided_sim",
+  "riskPlan": {
+    "protocol_class": "over-collateralized lending",
+    "target_claim": "Lenders do not accrue bad debt while the collateral price stays within the declared drop band and liquidation can keep pace.",
+    "p0_flows": [
+      "deposit_collateral",
+      "borrow",
+      "liquidate"
+    ],
+    "p1_flows": [
+      "repay",
+      "withdraw_collateral"
+    ],
+    "expected_failure_modes": [
+      "collateral price drop outruns permissioned liquidation, leaving under-collateralized debt the protocol absorbs as lender bad debt"
+    ],
+    "guided_sim_boundaries": [
+      "collateral_price_drop_bps swept across the declared region; the bad-debt onset is read from the risk surface, not asserted",
+      "liquidation is a third-party action dispatched by a keeper persona; the oracle is a hand-constructed Pyth PriceUpdateV2 crashed in place"
+    ],
+    "known_coverage_limits": [
+      "interest accrual over long horizons is out of the swept region",
+      "cross-program liquidation routes are not modeled in this campaign"
+    ]
+  },
+  "coverage": [
+    {
+      "priority": "P0",
+      "flow": "Collateral-crash liquidation race",
+      "status": "covered by guided sim",
+      "evidence_tier": "guided sim",
+      "commands": [
+        "riptide sim run .riptide/sim --flows 20 --out .riptide/sim/artifacts/crash",
+        "riptide sim surface .riptide/sim/artifacts/crash --sim .riptide/sim"
+      ],
+      "artifacts": [
+        ".riptide/sim/artifacts/crash/guided-sim-run.json"
+      ],
+      "notes": "Bad-debt onset emerges from the swept collateral_price_drop_bps axis; positive control fires the invariant beyond the onset."
+    },
+    {
+      "priority": "P1",
+      "flow": "Cross-program liquidation routes",
+      "status": "out of scope",
+      "evidence_tier": "none",
+      "commands": [],
+      "artifacts": [],
+      "notes": "No deterministic local fixtures for the external venues; named as a scope boundary, not silently skipped."
+    }
+  ]
+}

skills/riptide-assess-skill/install.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# riptide-assess — Riptide CLI bootstrap.
+#
+# Installs the Riptide CLI if `riptide` is not already on your PATH, then
+# verifies it. Idempotent: safe to re-run.
+#
+# Riptide runs deterministic guided simulations of Solana programs. `riptide
+# sim generate` scaffolds a project-owned Rust crate that builds against the
+# vendored runtime, so there is no separate engine binary to manage — but you
+# do need the build toolchain below.
+#
+# Prerequisites the installer expects (Linux; macOS may work, untested):
+#   - rustup / cargo + rustc
+#   - node >= 20 and npm
+#   - the Solana SBF toolchain (cargo-build-sbf, via the Anza/Solana install)
+# Riptide is NOT published to npm — do not `npm i riptide`.
+
+set -euo pipefail
+
+if command -v riptide >/dev/null 2>&1; then
+  echo "riptide already installed: $(riptide --version 2>/dev/null || echo '(version check failed)')"
+  exit 0
+fi
+
+echo "riptide not found on PATH — installing via the public installer..."
+echo "(needs cargo + node + the Solana SBF toolchain; Riptide is not on npm)"
+curl -fsSL https://riptide.run/install | sh
+
+# The installer drops a launcher into \$HOME/.local/bin.
+if ! command -v riptide >/dev/null 2>&1; then
+  case ":${PATH}:" in
+    *":${HOME}/.local/bin:"*) : ;;
+    *)
+      echo ""
+      echo "riptide installed, but \$HOME/.local/bin is not on your PATH. Add it:"
+      echo "  export PATH=\"\$HOME/.local/bin:\$PATH\""
+      echo "then re-open your shell (or 'source' your shell rc) and re-run this script."
+      exit 1
+      ;;
+  esac
+fi
+
+echo ""
+riptide --version
+echo "riptide is ready. Next: riptide doctor"

skills/riptide-assess-skill/skill/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: riptide-assess
+description: >-
+  Assess a Solana program with Riptide — run deterministic, guided LiteSVM
+  simulations against the real on-chain program to produce a risk assessment
+  with reproducible evidence. Use when the user says "assess my protocol", "is
+  my protocol safe", "run Riptide on this", "give me a risk assessment", or
+  "riptide-assess", or points you at an Anchor/Solana lending, AMM, perps,
+  liquid-staking, or stablecoin repo and wants one agent-led flow from program
+  source to an assessment report. Detects the protocol family, scopes what the
+  guided sim must handle (typed args, Pyth/Switchboard oracle-account bytes,
+  liquidator/keeper actors, multi-instruction sequences), authors and runs the
+  sim, then returns assessment evidence and exact rerun commands.
+user-invocable: true
+---
+
+# riptide-assess
+
+Riptide runs **deterministic guided simulations** of Solana programs to produce
+a **risk assessment** backed by reproducible evidence. This skill is the single
+front door: point it at a Solana program repo, answer at most three scoped
+questions, and it detects the protocol family, authors a project-owned Rust
+simulation crate that drives the program's real `.so` under stress, runs it over
+a declared fixed-seed sweep, and emits an assessment (`assessment.md` +
+`assessment.json`) plus an executive brief — with the exact commands to
+reproduce every figure.
+
+There is one execution path: a **guided simulation**. The agent authors the
+adapter, sim crate, personas, flows, and invariants — the user does not.
+
+The outcome is an `assessment.md` / `assessment.json` plus an evidence pack and
+the **exact rerun commands** over a declared, fixed-seed region. This is
+**simulation evidence over a declared region — not an audit signoff**, not
+formal verification, and not a mainnet prediction. Hold that boundary in every
+claim you make.
+
+## First Contact / Prerequisites (auto-install)
+
+If `riptide --help` fails, the CLI is not installed. Install it with the command
+below — **it works from any directory**. You are running inside the user's
+program repo, not the skill folder, so do not rely on a bare `install.sh` path:
+
+```bash
+curl -fsSL https://riptide.run/install | sh
+```
+
+The skill also bundles an `install.sh` at the root of its package that wraps this
+same installer; use it only if you have `cd`'d into the skill's own directory.
+Both are idempotent — safe to re-run.
+
+**Riptide is NOT on npm** — do not `npm i riptide`. The CLI scaffolds a
+project-owned Rust crate that builds against a vendored runtime (there is no
+separate engine binary), so the host needs:
+
+- `rustup` / `cargo` + `rustc`
+- `node >= 20` and `npm`
+- the Solana SBF toolchain (`cargo-build-sbf`, via the Anza/Solana install)
+
+Confirm the install before doing anything else:
+
+```bash
+riptide --version     # expect v0.12.0 or newer
+riptide doctor        # static health check of the environment + adapter
+```
+
+## How To Run (the CLI surface)
+
+Use **only** these commands. Never invent flags or subcommands.
+
+- `riptide init` — scaffold a thin `.riptide/` bootstrap in the target repo.
+- `riptide readiness <dir> [--json]` — read-only repo classification check.
+- `riptide doctor` — static adapter/environment health check.
+- `riptide sim generate --adapter <adapter.toml>` — scaffold the project-owned
+  guided-sim crate (`.riptide/sim`).
+- `riptide sim refresh --adapter <adapter.toml> --dir .riptide/sim` — regenerate
+  builders after IDL changes without overwriting hand-authored flows.
+- `riptide sim run <sim-dir> [--iterations N] [--flows N] [--seed HEX] --out <dir>`
+  — execute the sweep; reads `[sim.sweep]` from `Riptide.toml`.
+- `riptide sim surface <artifact-dir> --sim <sim-dir>` — build the cartography
+  root (campaign-summary.json + risk-surface.json + retention-manifest.json).
+- `riptide sim lint <sim-dir>` — validate the sim manifest.
+- `riptide sim review <artifact-dir>` — review a run's retained evidence.
+- `riptide sim fork` / `riptide sim debug` — fork-cache and debug helpers.
+- `riptide review <guided-sim-root>` — root reviewer over a surfaced root.
+- `riptide assess <guided-sim-root> [--input <json>] [--brief] [--html|--pdf]`
+  — ingest a surfaced root and emit the assessment.
+
+The parameter sweep lives in the `[sim.sweep]` block of
+`.riptide/sim/Riptide.toml` — it is configuration, **not** a CLI flag. Do not
+pass the sweep on the command line; `riptide sim run` reads it from the TOML.
+
+## The flow — routing
+
+Detect → Scope → Setup → Run → Surface → Assess. Work in one continuous session.
+Each step's depth lives in a focused file:
+
+1. **Detect the protocol family and scope what the guided sim must handle** (the
+   full A–F trigger taxonomy + the three scoped questions) →
+   [detect-and-scope.md](./detect-and-scope.md)
+2. **Author the adapter, generate the sim crate, fill the setup seams, author
+   flows + the sweep** →
+   [setup.md](./setup.md)
+3. **Run, surface, and assess** (smoke → full sweep → cartography root → final
+   render) →
+   [run-and-assess.md](./run-and-assess.md)
+
+Supporting depth:
+
+- **Family library** — the recurring personas, invariants, and stress scenarios
+  per protocol family; consult the detected family's entry during Scope before
+  designing the campaign →
+  [family-library.md](./family-library.md)
+- **Authoring patterns (guided sim)** — the library code to wire when triggers
+  fire (oracle-account construction, third-party dispatch, the sweep scaffold) →
+  [authoring-patterns.md](./authoring-patterns.md)
+- **Honesty Discipline (non-negotiable — read this)** — the 7 honesty rules, the
+  three runtime-enforced gates, and fail-fast/file-an-issue guidance →
+  [honesty.md](./honesty.md)
+- **Worst-case playbook** — per-archetype worst case to hunt, axis to sweep,
+  deciding invariant/metric, signal trap, honest framing →
+  [worst-case-playbook.md](./worst-case-playbook.md)
+- **References + file index** →
+  [resources.md](./resources.md)