diff --git a/CHANGELOG.md b/CHANGELOG.md index 0185195..97ba0d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,127 @@ ## [Unreleased] +## [0.5.0] — 2026-04-27 + +Theme: oracle-gated agent pipelines + restored formal-method backstops + +mutation testing as a hard signal. The agent-first pillar (CLI + MCP + +LSP) now has a documented oracle-driven workflow (Mythos slop-hunt), an +external-coverage consumer (witness coverage), and a 16-shard mutation +matrix that surfaced and killed ~125 surviving mutants across the core +crate. Verus and Rocq verification jobs are fully restored, the +dashboard's variant scoping is coherent across all eight relevant +handlers, and `rivet docs check` no longer silently passes on +non-rivet markdown that drifted into a scanned directory. + +### Added + +- **README rewrite + `rivet quickstart`** — new oracle-gated 10-step + walk-through (`rivet docs quickstart` or the `rivet quickstart` + alias). Each step has a deterministic oracle command + expected + output so an AI agent can follow the doc autonomously. README now + leads with the three-pillar synthesis (typed atoms, oracle-gated + agents, agent-first form factor) instead of a feature list. +- **Mythos slop-hunt agent pipeline** — `scripts/mythos/{rank,discover,validate,emit}.md` + + `HOWTO.md`. Four-prompt audit adapted from Anthropic's red-team + scaffold. Hunts dead code, duplicate parsers, and untraceable + modules. Excision-primary / trace-interpretive oracle. (#205) +- **Agent-pipelines schema block** — `agent-pipelines:` per-schema + declaration of which oracles apply, how to rank gaps, and what + closure routing applies. Surfaced through `rivet pipelines list` / + `rivet pipelines show` / `rivet close-gaps`. (#205) +- **CoverageStore** — typed witness-coverage consumer for external + coverage-evidence files. Lets `rivet validate` and `rivet coverage` + ingest tarpaulin/llvm-cov-style evidence as first-class artifacts + with module digests, run metadata, and per-module summaries. (#208) +- **Variant scoping for 8 dashboard handlers** — + `?variant=` query parameter is now honoured uniformly across + `/artifacts`, `/coverage`, `/stpa`, `/matrix`, `/stats`, `/graph`, + `/source`, and `/diagnostics`. Closes the incoherence flagged in the + PR #215 audit. (#223) +- **Docs warn-or-allowlist** — `rivet docs check` now surfaces non-rivet + markdown files that drifted into a scanned directory under + `rivet.yaml: docs:`. Default is `warn`; `rivet.yaml: + docs-check.allowlist` flips specific paths back to silent. Resolves + Task #56 — files like vendor docs no longer break the gate but no + longer hide either. (#224) +- **10 new Playwright rendering-invariant tests** — coverage of the + full route surface, with explicit `.svg-viewer` wrap pins, mermaid + inline-render assertions, and graph-route timeouts validated. (#215) + +### Changed + +- **Mutation testing — 16-shard `rivet-core` matrix, 30 s timeout** — + CI now shards the rivet-core mutation run across 16 jobs with a 30 s + per-mutant timeout (down from 90 s). The shard reduction surfaced + ~125 previously-untested mutants; PR #218 + #221 added ~64 new tests + to kill them across `embed`, `reqif`, `validate`, `commits`, + `coverage_evidence`, `compliance`, `convergence`, `links`, and + `store`. Net effect: mutation run is faster *and* the kill rate is + higher. (#218, #221) +- **Verus verification fully restored** — corrected `vstd` lemma paths + after upstream rename, replaced `matches!` macros with `is` + operators, fixed `lemma_div_multiples_vanish` invocation, added + `#[trigger]` annotations to backlink-symmetry / reachable-in + quantifiers, eliminated mid-quantifier in multi-step reachable case, + cast nat→int in `lemma_div_is_ordered`. 15 specs proven. (#212) +- **Rocq proofs fully restored** — restored `Validation.v` import, + replaced every `Admitted.` with a real proof. Schema and validation + semantics now machine-checked end-to-end. (#210) + +- **Serve middleware preserves response status** — + `wrap_full_page` was unconditionally rewriting downstream + 4xx/5xx responses to 200. Status is now preserved through the + full-page wrapper so `/artifacts/UNKNOWN-999` correctly returns + HTTP 404, etc. (#213) +- **Dashboard `/embed/*` route mounting** — moved under `Router::nest` + so the embed routes inherit the same middleware stack as the rest of + the dashboard (auth, layout-wrap exclusion, CSP). (#218) + +### Fixed + +- **Playwright suite green (384 passed)** — closed the remaining 8 + dashboard test failures (description-mermaid wrap, graph-render + timeout, source-browser cross-reference, doc-linkage reverse index, + variant-banner persistence). (#211, #213, #215, #217, #220) +- **Graph-route per-test timeout** — bumped 30 s → 60 s for slow CI + runners; the layout engine occasionally exceeded the old budget on + the larger test fixture. (#214) +- **`cargo fmt` drift** in mutation-test additions cleaned up. (#219) +- **CI**: Kani PR-smoke wiring, mutation shard config, Verus log + upload. (#209) + +### Tests + +- **+10 Playwright rendering-invariant tests** — pin the + `.svg-viewer` wrap, mermaid inline rendering, and graph-route + timeouts. (#215) +- **+~64 rivet-core unit tests** killing surviving mutants across + `embed`, `reqif`, `validate`, `commits`, `coverage_evidence`, + `compliance`, `convergence`, `links`, `store`. (#218, #221) +- **CoverageStore unit + integration tests** — round-trip + summary + invariants on witness coverage. (#208) + +### Distribution + +- **Workspace version bump** to `0.5.0` in `Cargo.toml`. The + `rivet-cli`, `rivet-core`, and `etch` crates inherit via + `version.workspace = true`. +- **VS Code extension** `vscode-rivet/package.json` bumped to `0.5.0`. +- **npm root package** `@pulseengine/rivet` bumped to `0.5.0`. Platform + package versions are filled in by the `release-npm.yml` workflow on + tag. + +### Status (v0.5.x in flight) + +- **Variant tooling** — six open product questions tracked in + `.rivet/mythos/variant-matrix-design.md` (matrix emission, t-wise + sampling, attribute-schema scope, audit cardinality, CLI + ergonomics, dashboard interplay). +- **Formal-method gaps** — three documented gaps in Verus coverage + (variant solver completeness, salsa incremental fixpoint, ReqIF + round-trip). The larger gale-style differential-testing bar is + a follow-up release item. + ## [0.4.3] — 2026-04-23 ### `rivet variant` — build-system query surface and solve debugger diff --git a/Cargo.lock b/Cargo.lock index ab5d16c..ba93d0c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -972,7 +972,7 @@ dependencies = [ [[package]] name = "etch" -version = "0.4.3" +version = "0.5.0" dependencies = [ "petgraph 0.7.1", ] @@ -2698,7 +2698,7 @@ dependencies = [ [[package]] name = "rivet-cli" -version = "0.4.3" +version = "0.5.0" dependencies = [ "anyhow", "axum", @@ -2725,7 +2725,7 @@ dependencies = [ [[package]] name = "rivet-core" -version = "0.4.3" +version = "0.5.0" dependencies = [ "anyhow", "criterion", diff --git a/Cargo.toml b/Cargo.toml index e30dd29..7bd5d2a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -7,7 +7,7 @@ members = [ ] [workspace.package] -version = "0.4.3" +version = "0.5.0" authors = ["PulseEngine "] edition = "2024" license = "Apache-2.0" diff --git a/README.md b/README.md index 4074e05..ed38792 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,13 @@ # Rivet -Evidence as Code — the audit substrate for AI-assisted engineering +Typed knowledge graph + oracle-gated agents + agent-first form factor — the audit substrate for AI-assisted engineering   [![CI](https://github.com/pulseengine/rivet/actions/workflows/ci.yml/badge.svg)](https://github.com/pulseengine/rivet/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/pulseengine/rivet/branch/main/graph/badge.svg)](https://codecov.io/gh/pulseengine/rivet) ![Rust](https://img.shields.io/badge/Rust-CE422B?style=flat-square&logo=rust&logoColor=white&labelColor=1a1b27) -![YAML](https://img.shields.io/badge/YAML-654FF0?style=flat-square&logoColor=white&labelColor=1a1b27) -![STPA](https://img.shields.io/badge/STPA-654FF0?style=flat-square&logoColor=white&labelColor=1a1b27) -![ASPICE](https://img.shields.io/badge/ASPICE-654FF0?style=flat-square&logoColor=white&labelColor=1a1b27) ![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue?style=flat-square&labelColor=1a1b27)   @@ -28,184 +25,150 @@   -Spar parses. Etch renders. Meld fuses. **Rivet binds.** - -**Rivet: because AI agents still don't remember why.** The faster AI agents produce code, the more it matters to prove *why* each line exists — and AI systems reliably fail to maintain the traceability that ISO 26262, DO-178C, and the EU AI Act require. Rivet keeps the chain from requirement to test to evidence as YAML in git — machine-readable, agent-writable, validated in CI, provenance-stamped on every mutation, and reviewed by a human in the pull request. Today rivet dogfoods 219+ artifacts across 27 schemas (STPA, ASPICE, ISO/PAS 8800, IEC 61508, IEC 62304, DO-178C, EN 50128, EU AI Act, GSN), backed by 27 Kani BMC harnesses and 324 Playwright end-to-end tests — see **[docs/what-is-rivet.md](docs/what-is-rivet.md)** for the frame, the per-situation playbook, and explicit limits. - -## Features - -- **Schema-driven validation** — artifact types, link types, cardinality, traceability rules -- **STPA + STPA-Sec** — full safety and security analysis with 15+ artifact types -- **ASPICE V-model** — stakeholder→system→software→verification traceability chain -- **Eclipse SCORE** — 40+ artifact types from the SCORE metamodel -- **Dashboard** — `rivet serve` with filter/sort/pagination, graph, STPA hierarchy, print mode -- **LSP server** — `rivet lsp` with diagnostics, hover, go-to-definition, completions (salsa incremental) -- **VS Code extension** — embedded dashboard, live validation, Cmd+K search -- **HTML export** — static site with STPA, graph, documents, matrix, coverage -- **Gherkin export** — `rivet export --gherkin` generates .feature files from acceptance criteria -- **Self-contained binary** — HTMX, Mermaid, fonts bundled; works offline -- **Cross-repo linking** — `rivet sync` with external project references -- **Baseline scoping** — `rivet validate --baseline v0.1.0` for version-scoped validation -- **AI agent support** — `rivet init --agents` generates AGENTS.md (25+ tools) -- **ReqIF 1.2** — import/export for DOORS, Polarion, codebeamer interchange -- **235+ Playwright E2E tests** — full route coverage with CI integration - -## Quick Start +> **Spar parses. Etch renders. Meld fuses. Rivet binds.** +> +> Rivet is a git-native, schema-driven artifact store with a CLI, an LSP, +> a dashboard, and an MCP server. Agents write the artifacts; mechanical +> oracles gate them; humans review the diff in the pull request. + +## Why rivet + +Three patterns landed in public over the same six-week window: Karpathy's +LLM Wiki (knowledge compounds), Anthropic's red-team agent scaffold +(verification mechanically gates), and the typed-traceability lineage +that ASPICE / DOORS / sphinx-needs settled decades ago (audit reads the +result). Each pillar in isolation reproduces a known failure mode — the +wiki that drifted into fiction, the test suite green on stale +assumptions, the traceability matrix nobody consults. Run the three +together and the failure modes cancel. See +[*Three patterns colliding*](https://pulseengine.eu/blog/three-patterns-colliding/) +for the synthesis. + +Rivet is the typed-traceability pillar realised as one Rust binary with +three driving surfaces (CLI, MCP server, LSP backend) so an AI agent can +pick whichever one fits. Every artifact is provenance-stamped on every +mutation; every commit must carry the typed trailer that ties it back to +a requirement; every change has to survive `rivet validate` before the +PR review even starts. The same one binary serves the dashboard the +human reads, the LSP the editor uses, and the MCP tools the agent calls. + +This is not an audit-after-the-fact tool. The point is that the agent +*authors* against the typed schema while the oracle is firing — so the +evidence is born compliant instead of being reverse-engineered later. + +## Install ```bash -# Install +# From source (recommended while pre-1.0) cargo install --path rivet-cli -# Initialize a project -rivet init --preset dev - -# Validate artifacts -rivet validate - -# Start the dashboard -rivet serve +# Or from a release tag +curl -L https://github.com/pulseengine/rivet/releases/download/v0.5.0/rivet-x86_64-unknown-linux-gnu.tar.gz | tar xz -# Start with live reload on file changes -rivet serve --watch - -# Show artifact stats -rivet stats - -# Generate AGENTS.md for AI coding agents -rivet init --agents +# Or via npm (for `npx @pulseengine/rivet mcp` in MCP clients) +npm install -g @pulseengine/rivet ``` -## Dashboard +## 30-second demo ```bash -rivet serve --port 3000 +rivet init --preset dev # 1. scaffold rivet.yaml + schemas/ + artifacts/ +rivet add requirement -t "DB write returns ack" --asil B # 2. add a typed atom +rivet validate # 3. oracle: PASS (no diagnostics) +rivet serve --port 3099 # 4. dashboard at http://localhost:3099 +rivet docs quickstart # 5. 10-step embedded guide w/ oracles ``` -The dashboard provides: -- Artifact list with filter/sort/pagination -- Traceability graph (Etch layout engine) -- STPA + STPA-Sec hierarchy with filter bar -- Coverage matrix -- Document viewer with `[[ID]]` wiki-links -- Source browser with artifact cross-references -- Validation diagnostics with severity filtering -- Cmd+K global search -- Print mode (`?print=1`) - -## VS Code Extension - -The `vscode-rivet` extension provides: -- LSP client with real-time diagnostics (squiggly lines on broken links) -- Hover info (artifact title, type, description) -- Go-to-definition (click artifact ID → jump to YAML source) -- Completions (artifact IDs, link types from schema) -- Embedded dashboard as a WebView panel +For a longer walk-through with copy-pasteable steps and an oracle on +each one, run `rivet quickstart` (added in v0.5.0). -```bash -cd vscode-rivet && npm install && npm run compile -``` +## What's in here -## How It Works +`rivet-core` is the validation, schema, and salsa-incremental store +library. `rivet-cli` is the binary — CLI commands, the axum+HTMX +dashboard, the LSP server, the MCP server, and the `close-gaps` / +`pipelines` agent-driven oracle commands. `etch` is the layout engine +behind the traceability graph. `vscode-rivet` is the editor extension. +`schemas/` ships 28 built-in domain schemas (STPA, STPA-Sec, ASPICE 4.0, +Eclipse SCORE, ISO/PAS 8800, IEC 61508, IEC 62304, DO-178C, EN 50128, +GSN safety cases, EU AI Act, AADL, supply-chain, dev). `proofs/rocq/` +and `rivet-core/src/verus_specs.rs` carry the formal-method backstops; +`scripts/mythos/` is the agent-driven slop-hunt pipeline. -1. **Define schemas** — YAML files declaring artifact types, link types, field constraints -2. **Write artifacts** — YAML files with typed, linked lifecycle artifacts -3. **Validate** — Rivet checks link integrity, required fields, cardinality, traceability rules +## Built-in docs -``` -rivet.yaml # Project config -schemas/ - common.yaml # Base link types (satisfies, verifies, ...) - stpa.yaml # STPA methodology (10 types, 7 rules) - stpa-sec.yaml # STPA-Sec adversarial analysis (5 types) - aspice.yaml # ASPICE V-model (14 types, 10 rules) - cybersecurity.yaml # ISO 21434 / ASPICE SEC.1-4 (10 types) - score.yaml # Eclipse SCORE metamodel (40+ types) - dev.yaml # Lightweight dev tracking (3 types) - aadl.yaml # AADL architecture (3 types) -artifacts/ # Your lifecycle artifacts -safety/stpa/ # STPA analysis files -safety/stpa-sec/ # STPA-Sec security analysis -docs/ # Documents with {{artifact:ID}} embeds -``` - -## Adapters - -- **generic-yaml** — canonical format with explicit `type` and `links` -- **stpa-yaml** — STPA analysis files (losses, hazards, UCAs, control structure) -- **aadl** — AADL architecture via spar (direct `.aadl` parsing or JSON) -- **reqif** — ReqIF 1.2 XML for ALM tool interchange -- **needs-json** — sphinx-needs JSON export import -- **WASM components** — custom format adapters via WIT interface - -## CLI Commands - -| Command | Purpose | -|---------|---------| -| `rivet validate` | Check link integrity, coverage, required fields | -| `rivet list` | List artifacts with type/status/search filters | -| `rivet stats` | Show artifact counts by type | -| `rivet serve` | Start the interactive dashboard | -| `rivet lsp` | Start the LSP server (for editors) | -| `rivet add` | Create a new artifact with auto-generated ID | -| `rivet link` | Add a link between artifacts | -| `rivet modify` | Update artifact fields | -| `rivet remove` | Remove an artifact | -| `rivet batch` | Atomic multi-mutation from a YAML file | -| `rivet export` | Generate HTML, ReqIF, YAML, or Gherkin output | -| `rivet import-results` | Import from JUnit XML or sphinx-needs JSON | -| `rivet impact` | Show change impact analysis | -| `rivet coverage` | Show traceability coverage | -| `rivet matrix` | Compute traceability matrix | -| `rivet sync` | Sync external project dependencies | -| `rivet commits` | Check commit-to-artifact traceability | -| `rivet init` | Initialize a new project or generate AGENTS.md | - -## Architecture - -``` -rivet-core/ # Library: model, store, links, schema, validation, adapters, LSP DB -rivet-cli/ # Binary: CLI commands, axum+HTMX dashboard, LSP server -etch/ # Graph layout engine (Sugiyama, compound, orthogonal routing) -vscode-rivet/ # VS Code extension (LSP client, WebView dashboard) -schemas/ # Built-in domain schemas (8 schemas) -``` - -## Dogfooding - - -Rivet tracks its own development — 709 artifacts across 19 types, validated on every commit. +`rivet docs` lists every embedded topic; `rivet docs ` prints the +content. The whole reference manual ships in the binary — no docs site +to drift, and the LSP serves the same text on hover. ```bash -$ rivet validate -Result: PASS (0 warnings) - -$ rivet stats - requirement 36 - design-decision 39 - feature 80 - hazard 18 - uca 57 - sec-loss 5 - sec-hazard 6 - ... - TOTAL 447 +rivet docs # list topics +rivet docs cli # CLI command reference +rivet docs schema/stpa # STPA schema reference +rivet docs --grep variant # search across all docs +rivet quickstart # 10-step oracle-gated walk-through ``` -## Development - -```bash -cargo build # Build -cargo test --all # 500+ tests -cargo clippy -- -D warnings # Lint -cargo fmt # Format -rivet validate # Self-validate -cd tests/playwright && npx playwright test # 235+ E2E tests -``` +## For agents + +- **MCP server** — `rivet mcp` exposes the artifact graph as typed + tools (query, add, modify, link, unlink, remove, validate). Wire it + into Claude Code, Cursor, or any MCP-aware client. `npx @pulseengine/rivet mcp` + for clients that prefer node binaries over rust toolchains. +- **LSP server** — `rivet lsp` runs over stdio with diagnostics, hover, + go-to-definition, and completions on artifact YAML. The VS Code + extension is the reference client. +- **Slop-hunt pipeline** — `scripts/mythos/` is a four-prompt + agent-driven audit (`rank` → `discover` → `validate` → `emit`) that + finds dead code, duplicate parsers, and untraceable modules in any + rivet-managed project. Adapted from Anthropic's red-team scaffold. +- **Agent pipelines** — `rivet pipelines list` / `rivet close-gaps` + read the `agent-pipelines:` block in each schema and walk the + oracle → rank → close-by-link → emit-trailer loop the agent runs. + +## Status + +- **CI**: `rivet validate`, `cargo clippy --workspace -- -D warnings`, + `cargo test --workspace`, `rivet docs check`, Playwright (33 spec + files), Kani (28 BMC harnesses), Verus, Rocq, mutation testing + (16-shard rivet-core). +- **Self-hosted dashboard**: rendered to https://pulseengine.eu/reports/rivet/ + on every push to `main`. +- **Release**: see [CHANGELOG.md](CHANGELOG.md). Current line is the + v0.5.0 series — Mythos pipeline + witness-coverage consumer + variant + scoping coherence + restored Verus & Rocq + 16-shard mutation testing. + +### In flight (honest list) + +- **Variant tooling** carries six open product questions (matrix + emission, t-wise sampling, attribute schema scope, audit cardinality, + CLI ergonomics, dashboard interplay) tracked under + `.rivet/mythos/variant-matrix-design.md` and the v0.5.x backlog. +- **Formal-verification gaps**: Verus has 15 proven specs and three + documented gaps (variant solver completeness, salsa incremental + fixpoint, ReqIF round-trip). Rocq covers schema and validation + semantics; the larger gale-style differential-testing bar is a + follow-up release item. +- **Schema coverage**: 28 schemas ship; STPA-AI and supply-chain + schemas are still soft-launched and may shift before 1.0. + +## Contributing + +Read [AGENTS.md](AGENTS.md) for the project conventions and +[CLAUDE.md](CLAUDE.md) for the commit-traceability trailer rules +(every commit touching `rivet-core/src/` or `rivet-cli/src/` must carry +`Implements: REQ-NNN` / `Refs: FEAT-NNN` / `Verifies: REQ-NNN` / +`Fixes: REQ-NNN`, or `Trace: skip` for chore/style/ci/docs/build). ## License Apache-2.0 +## Contact + +[github.com/pulseengine](https://github.com/pulseengine) · +[pulseengine.eu](https://pulseengine.eu) + ---
diff --git a/npm/package.json b/npm/package.json index 9315a15..bf56e6e 100644 --- a/npm/package.json +++ b/npm/package.json @@ -1,6 +1,6 @@ { "name": "@pulseengine/rivet", - "version": "0.4.2", + "version": "0.5.0", "description": "Rivet — SDLC traceability, validation, and MCP server for safety-critical systems (ISO 26262, DO-178C, ASPICE, STPA)", "main": "index.js", "bin": { diff --git a/rivet-cli/src/docs.rs b/rivet-cli/src/docs.rs index 84ad489..7038d08 100644 --- a/rivet-cli/src/docs.rs +++ b/rivet-cli/src/docs.rs @@ -53,6 +53,13 @@ struct DocTopic { } const TOPICS: &[DocTopic] = &[ + // ── Getting started ──────────────────────────────────────────────── + DocTopic { + slug: "quickstart", + title: "10-step oracle-gated quickstart", + category: "Getting started", + content: QUICKSTART_DOC, + }, // ── Reference topics ─────────────────────────────────────────────── DocTopic { slug: "artifact-format", @@ -2135,3 +2142,5 @@ With the `supply-chain-dev` bridge: https://in-toto.io/ "# ); + +const QUICKSTART_DOC: &str = include_str!("quickstart.md"); diff --git a/rivet-cli/src/main.rs b/rivet-cli/src/main.rs index 9021506..e911fe6 100644 --- a/rivet-cli/src/main.rs +++ b/rivet-cli/src/main.rs @@ -518,6 +518,13 @@ enum Command { fix: bool, }, + /// Print the 10-step oracle-gated quickstart (alias for `rivet docs quickstart`). + Quickstart { + /// Output format: "text" (default) or "json" + #[arg(short, long, default_value = "text")] + format: String, + }, + /// Generate .rivet/agent-context.md from current project state Context, @@ -1451,6 +1458,9 @@ fn run(cli: Cli) -> Result { } return cmd_docs(topic.as_deref(), *list, grep.as_deref(), format, *context); } + if let Command::Quickstart { format } = &cli.command { + return cmd_docs(Some("quickstart"), false, None, format, 2); + } if let Command::Context = &cli.command { return cmd_context(&cli); } @@ -1467,6 +1477,7 @@ fn run(cli: Cli) -> Result { match &cli.command { Command::Init { .. } | Command::Docs { .. } + | Command::Quickstart { .. } | Command::Context | Command::CommitMsgCheck { .. } | Command::Lsp diff --git a/rivet-cli/src/quickstart.md b/rivet-cli/src/quickstart.md new file mode 100644 index 0000000..ee581e0 --- /dev/null +++ b/rivet-cli/src/quickstart.md @@ -0,0 +1,250 @@ +# Quickstart — 10 oracle-gated steps + +Each step has a **goal**, the **commands** to run, and an **oracle**: +a deterministic command + expected output that proves the step succeeded. +Copy-paste each block top-to-bottom; an AI agent can follow this end-to-end +without supervision because every step is mechanically checkable. + +> The walk-through assumes a fresh empty directory. Substitute paths as +> needed; the oracles still hold. + +--- + +## 1. Install + version check + +**Goal**: get the `rivet` binary on your PATH. + +```bash +cargo install --path rivet-cli +# or: npm install -g @pulseengine/rivet +# or: download a release tarball from +# https://github.com/pulseengine/rivet/releases +``` + +**Oracle**: + +```bash +rivet --version +``` + +Expected: a line of the form `rivet 0.5.0` (or higher). Non-zero exit +means the binary is not on PATH. + +--- + +## 2. Initialise an empty project + +**Goal**: scaffold `rivet.yaml` + `schemas/` + `artifacts/` + `docs/`. + +```bash +mkdir my-project && cd my-project +rivet init --preset dev +``` + +**Oracle**: + +```bash +test -f rivet.yaml && test -d artifacts && test -d docs && echo OK +``` + +Expected: `OK`. The `dev` preset wires the lightweight `requirement` / +`design-decision` / `feature` types so you can validate without committing +to a full ASPICE or STPA shape on day one. + +--- + +## 3. Add a typed artifact + +**Goal**: write one valid requirement. + +```bash +cat > artifacts/sample.yaml <<'EOF' +artifacts: + - id: REQ-001 + type: requirement + title: Database write returns acknowledgement + status: draft + description: > + The system shall return an acknowledgement record within 50 ms of + a successful database write. +EOF +``` + +**Oracle**: + +```bash +rivet list --type requirement --format json | grep -q '"id": "REQ-001"' && echo OK +``` + +Expected: `OK`. The artifact is now in the typed store and queryable. + +--- + +## 4. Validate — no diagnostics + +**Goal**: prove the artifact survives the schema engine. + +```bash +rivet validate +``` + +**Oracle**: + +```bash +rivet validate --format json | grep -q '"result": "PASS"' && echo OK +echo "exit=$?" +``` + +Expected: `OK` and `exit=0`. A non-PASS result means the schema rejected +something — the JSON output lists every diagnostic. + +--- + +## 5. List the typed artifact + +**Goal**: confirm the typed query surface works. + +```bash +rivet list --type requirement +``` + +**Oracle**: + +```bash +rivet list --type requirement --format json \ + | grep -E '"id":\s*"REQ-001"' \ + && echo OK +``` + +Expected: `OK` and a row showing `REQ-001 | requirement | …`. + +--- + +## 6. Add a second artifact + a typed link + +**Goal**: write a feature that satisfies the requirement, with a typed +`satisfies` link from feature → requirement. + +```bash +cat >> artifacts/sample.yaml <<'EOF' + - id: FEAT-001 + type: feature + title: Async write-ack pipeline + status: draft + links: + - type: satisfies + target: REQ-001 +EOF +``` + +**Oracle**: + +```bash +rivet list --format json \ + | grep -q '"id": "FEAT-001"' \ + && rivet validate --format json | grep -q '"result": "PASS"' \ + && echo OK +``` + +Expected: `OK`. Both artifacts are present, the link target resolves, and +validation still passes. + +--- + +## 7. Re-run validate — link target resolves + +**Goal**: prove the typed link is honoured by the validator. + +```bash +rivet validate +``` + +**Oracle**: + +```bash +rivet validate --format json \ + | python3 -c "import json,sys; d=json.load(sys.stdin); \ + assert d['result']=='PASS', d; \ + assert d.get('error_count',0)==0, d; print('OK')" +``` + +Expected: `OK`. If you change `target: REQ-001` to a typo like +`target: REQ-999`, this oracle will fail with a broken-link diagnostic — +that's the loudness contract. + +--- + +## 8. Start the dashboard + +**Goal**: serve the typed graph over HTTP for human review. + +```bash +rivet serve --port 3099 & +SERVE_PID=$! +sleep 1 +``` + +**Oracle**: + +```bash +curl -fsS -o /dev/null -w "%{http_code}\n" http://localhost:3099/artifacts +# expect: 200 +kill "$SERVE_PID" +``` + +Expected: `200`. The dashboard renders the artifact list, the +traceability graph, the coverage matrix, and the document viewer. Open +http://localhost:3099 in a browser to see it; press `Cmd+K` for the +global search. + +--- + +## 9. (Optional) Run the slop-hunt agent pipeline + +**Goal**: try the four-prompt agent-driven audit on a rivet-managed repo. + +```bash +ls scripts/mythos/ # if you cloned the rivet repo +``` + +The four prompts (`rank.md`, `discover.md`, `validate.md`, `emit.md`) are +designed to run inside a Claude Code session against any rivet-managed +project. The HOWTO walks through the workflow: + +```bash +rivet docs --grep mythos +``` + +**Oracle** (when run inside a Claude Code session): + +```bash +test -f .rivet/mythos/ranking.json && echo OK +``` + +Expected: `OK` — the rank step writes `ranking.json` with one entry per +source file, scored 1–5 for slop likelihood. See +`scripts/mythos/HOWTO.md` for the full pipeline. + +--- + +## 10. Where to go next + +```bash +rivet docs # list every embedded topic +rivet docs cli # CLI command reference +rivet docs schema/stpa # STPA schema deep-dive +rivet docs schema/aspice # ASPICE 4.0 V-model schema +rivet docs commit-traceability # git-trailer rules for compliance +rivet docs formal-verification # Kani / Verus / Rocq strategy +rivet docs cross-repo # multi-repo linking +rivet mcp # start the MCP server for AI agents +rivet lsp # start the LSP server for editors +``` + +For the larger picture — three-pillar synthesis, why agents need typed +schemas and oracle gates together — read +[*Three patterns colliding*](https://pulseengine.eu/blog/three-patterns-colliding/). + +For the per-situation playbook (compliance lineage, ASPICE, STPA-Sec, +EU AI Act) read `docs/what-is-rivet.md` in this repo or +`rivet docs schemas-overview` from any rivet install. diff --git a/vscode-rivet/package.json b/vscode-rivet/package.json index 37aafb5..81a4c08 100644 --- a/vscode-rivet/package.json +++ b/vscode-rivet/package.json @@ -3,7 +3,7 @@ "displayName": "Rivet SDLC", "description": "SDLC artifact traceability with live validation, hover info, and embedded dashboard", "publisher": "pulseengine", - "version": "0.4.3", + "version": "0.5.0", "license": "MIT", "repository": { "type": "git",