# rederive

If you are an agent setting rederive up or running its loop for a user: fetch and follow
https://rederive.ai/prompt.md — it is the whole workflow, written for you, including the verification
discipline (expected values are never hand-authored; a failed gate is a finding, not retry-fodder; the
toolkit is immutable from your seat).

> Replace npm dependencies with code you own — checked against tests the AI never saw. rederive rebuilds the
> npm packages you depend on as small, verified, zero-dependency copies in your repo, and checks code — yours or
> AI-written — against held-back tests. Each part gets a contract: a language-neutral spec (SIR, the spec format)
> plus held-back tests ("held-out oracle") whose expected answers come from running the original package or a
> chosen reference, never from whoever writes the replacement. Held back means hidden from the AI builders while
> they build; afterwards the tests ship with the package, fingerprinted (hashed), so anyone can re-generate them
> from the original and confirm nothing changed. Each part is built more than once by isolated AI builds; if
> independent builds disagree, the spec left room for guessing and gets tightened. Agreement is not the test of
> correctness — the held-back tests are. Since SIR v0.5 one contract serves JavaScript, TypeScript and Rust, all
> graded against the same held-back tests. `rdv check` (the rdv checker, rederive's command-line tool) re-runs
> every check offline, free, with no AI; tampering is caught two ways at once: behavior fails the held-back tests,
> and the content hash mismatches. Best fit today: small, self-contained packages (string, number, date, URL,
> parsing and formatting helpers, including abandoned ones); network/file-system packages are JavaScript only;
> native add-ons and large frameworks are not yet supported; anything that can't be verified is reported and
> left in place. rederive re-derives its own verifier (42/42 parts — JavaScript and TypeScript for all 42, Rust
> for 38; 67,976 cross-language comparisons, zero disagreements) as the bundle `@rederive/rederive-core`, which
> lives in the rederive repo at `selfhost/core/rederive-core` (not published to npm) and which its own `rdv`
> verifies. Open source, Apache-2.0, by Apilify Inc.

## Setup

- [Agent setup prompt](https://rederive.ai/prompt.md): install → zero-footprint demo in a temp directory →
  ask before touching the project → `rdv init . --dry-run` → `--yes` → choose verify / re-derive / preflight /
  build → run → report
- CLIs (Node ≥ 18): `npm i -g rederive@^0.5 sir-factory@^0.5`. rdv, sir-factory and the plugin keep major.minor equal to
  the SIR spec version they target (0.5.x ↔ SIR v0.5): `rdv --version` and `sir-factory --version` both print 0.5.x,
  and a 0.4.x on either is an older release to upgrade, not a different loop.
- Toolchains are the user's own: TypeScript variants need `typescript` (tsc) and `@types/node` resolvable from the
  project; Rust variants need `cargo`. `rdv check` halts with an install hint rather than skip a language.
- Claude Code plugin: `/plugin marketplace add rederive/rederive` then `/plugin install rederive@rederive`
  (skills: tools, sir-verify, greenfield-quorum, preflight; role agents: sir-decomposer, sir-reemitter-cr,
  sir-unit-runner). The older `sir@sir-toolkit` plugin is legacy (pre-0.5).
- The v0.5 loop in one line: `sir-decomposer` (sighted, once) → `sir-factory prepare` → N blind `sir-reemitter-cr` per
  language → `sir-factory grade --round N` → `sir-factory pack-v05`. sir-factory never calls a model; the agent spawns
  the emitters. Step 4b of prompt.md spells it out.
- No global install: run the verifier as `npx -p rederive rdv <command>` (the npm package named `rdv` is unrelated)
- First run, zero footprint: in a temp directory, `npm i @rederive/colors`, `rdv check node_modules/@rederive/colors --lang js` (`--lang` checks only the
  languages this machine has a toolchain for; the rest are reported NOT CHECKED),
  change one character under its `src/`, and check again — it fails. Nothing in the user's project changes.
- Set up a project (ask the user first): `rdv init . --dry-run` to see the plan, then `rdv init . --yes` (without
  a TTY a bare `rdv init` writes nothing)
- See how many packages npm really installed: `npx -p rederive rdv audit`
- Gate dependency adds in a PR: `npx -p rederive rdv guard <base-lock> <head-lock> --reporter github` (RED = an install
  hook on a non-established package); as an Action, `rederive/dep-guard@v1` (https://github.com/rederive/dep-guard)

## Tools (all of them: https://rederive.ai/tools.html)

- SIR review GitHub Action: `uses: rederive/sir-review@v1` after `actions/checkout@v4` with `fetch-depth: 0`. A plain-English
  review of SIR contract changes in pull requests. It fails on a Stop: a tested change with no test change, or a rewritten
  hidden answer. Its own code is the selfhost-verified review-core.
  [Marketplace](https://github.com/marketplace/actions/sir-review)
- Any other CI: `npx -p rederive rdv review --base origin/main`. It exits 1 on a Stop; `--format summary|github|json`
  changes the output.
- Editors: the VS Code extension `rederive.sir-lang` ([VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=rederive.sir-lang),
  [Open VSX](https://open-vsx.org/extension/rederive/sir-lang)). For any LSP editor, run `rdv lsp --stdio`
  ([setup](https://github.com/rederive/rederive/blob/main/editors/README.md)).

## Specification

- [SIR Schema (normative, v0.5)](https://raw.githubusercontent.com/rederive/sir-spec/main/SIR_SCHEMA.md): the
  language-neutral contract format — kinds, the firewall, oracles, fidelity variants, effect seams, carried data,
  the concurrency layer, and v0.5's primary + per-language files, the `sir-canonical-v1` vector encoding, the js
  envelope extension, and how a verifier calls and judges an artifact (§23c)
- [sir-spec repo](https://github.com/rederive/sir-spec): canonical home, versioned, evidence-cited
- [Narrative spec with worked examples](https://rederive.ai/spec.html)

## Source & packages

- [rederive (the rdv verifier CLI)](https://github.com/rederive/rederive) — npm: `rederive`
- [sir-factory (the build orchestrator)](https://github.com/rederive/sir-factory) — npm: `sir-factory`
- The Claude Code plugin `rederive@rederive` (sir-verify, greenfield-quorum and preflight skills, role agents)
  ships from the [rederive repo](https://github.com/rederive/rederive)
- [sir-toolkit](https://github.com/rederive/sir-toolkit) — legacy plugin and methodology docs (pre-0.5), kept for reference

## Commitments

- [The rederive Promise](https://rederive.ai/promise.html): never paywall verification, never cripple the open
  core, never retroactively relicense; the format carries no patent assertion against conforming implementations