diff --git a/README.md b/README.md index faeb768..6745f13 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # Rivet -SDLC traceability for safety-critical systems +Evidence as Code — the audit substrate for AI-assisted engineering   @@ -30,9 +30,7 @@ Spar parses. Etch renders. Meld fuses. **Rivet binds.** -Rivet is a schema-driven SDLC artifact manager for safety-critical systems. It keeps requirements, architecture, design, test specifications, and safety analysis artifacts as YAML files in git — then validates link integrity, traceability coverage, and completeness rules against mergeable schemas. - -No database, no external service, just text files and a fast Rust CLI. +**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 diff --git a/docs/what-is-rivet.md b/docs/what-is-rivet.md new file mode 100644 index 0000000..73dc685 --- /dev/null +++ b/docs/what-is-rivet.md @@ -0,0 +1,374 @@ +# 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. rivet keeps the chain from requirement to test to +evidence as YAML in git — machine-readable, agent-writable, validated +in CI. v0.4.1 extends that: every artifact can be authored by an +MCP-connected agent, cross-verified by rivet's schema engine, and +reviewed by a human in the pull request — all three in the same +commit. + +This document is the frame, the per-situation playbook, and an +explicit list of things rivet is *not*. Every capability below is +something you can verify today in the current tree unless it is +marked **(planned for v0.5.0)** or **(in progress)**. + +--- + +## 1. The frame: Evidence as Code + +Sphinx-Needs calls itself *Engineering as Code*. That framing assumes +a human author and a doc-as-code publishing pipeline. Good frame — +for human-authored workflows. + +rivet's centre of gravity is different. The assumption is that **AI +agents draft the artifacts** — requirements, hazards, design +decisions, test specs, variant bindings — and a human **reviews the +diff in a pull request**. That shift changes the tool's job: + +- Every artifact carries a **provenance record**: human vs ai vs + ai-assisted, which model, which session, when, reviewed by whom. +- Every change must survive **machine validation** before it counts + as evidence: link integrity, cardinality, schema rules, + s-expression constraints, variant consistency. +- The change surface is **git-native**, so the PR review *is* the + approval step — not a separate workflow in a separate tool. +- Agents read and mutate the evidence graph through a typed + interface, not a screen-scrape. + +That is what rivet is: a git-native, schema-driven evidence store +with an LSP, a dashboard, an MCP server, and formal-verification +scaffolding. AI agents author, humans cross-verify, the same PR +carries both. + +--- + +## 2. What rivet is (one paragraph) + +rivet is a **git-native, schema-driven artifact store** with a +**CLI**, an **LSP server**, a **dashboard** (`rivet serve`), and an +**MCP server** (`rivet mcp`) that exposes the artifact graph to AI +agents as typed tools. It ships 27 schemas covering STPA, STPA-Sec, +ASPICE 4.0, Eclipse SCORE, ISO/PAS 8800, IEC 61508, IEC 62304, +DO-178C, EN 50128, GSN safety cases, and the EU AI Act — plus the +cross-schema bridges between them. It imports ReqIF 1.2, JUnit XML, +and sphinx-needs JSON. It exports ReqIF, HTML, Zola, Gherkin, and +generic YAML. Validation runs on a salsa-backed incremental engine; +every mutation stamps AI provenance. The core validation rules are +backed by 27 Kani bounded-model-checking harnesses, Verus specs, +Rocq proofs, and 324 Playwright end-to-end tests across 28 spec +files. + +--- + +## 3. Who rivet is for + +- **Safety-critical teams with a compliance standard.** ISO 26262 + (via IEC 61508), DO-178C, EN 50128, IEC 62304, ISO/PAS 8800, or the + EU AI Act — there is a schema in `schemas/` that is at least a + starting point. See + [docs/design/polarion-reqif-fidelity.md](design/polarion-reqif-fidelity.md) + for a field-by-field audit of what survives ReqIF interchange. + +- **Rust and embedded teams running AI pair-programming.** rivet is + written in Rust and dogfoods itself: 219+ artifacts across + requirements, features, design decisions, hazards, UCAs, tests, and + verifications. If Claude Code, Cursor, or Gemini already write your + code, `rivet mcp` and `rivet stamp` are the point where the + *evidence* survives the session. + +- **ASPICE programs that want a free alternative to Polarion for + traceability.** rivet cannot replace Polarion's live collaborative + editing — but for the traceability graph, ReqIF export, and + coverage reporting, `rivet validate && rivet export --format reqif` + produces audit evidence from a git repo in seconds. + +- **AI platform teams building agentic-SDLC workflows.** The + `provenance` field captures `created-by`, `model`, `session-id`, + `timestamp`, and `reviewed-by` on every artifact. `rivet stamp` + writes them in a shape that passes schema validation. + +--- + +## 4. The use-case palette + +rivet's schema system is domain-agnostic, so the same tool gets used +differently per situation. What follows is a per-situation playbook: +*what question is answered*, *what the AI does*, *what the human +reviews*. + +### 4.1 Test-driven development (TDD) + +- **Question.** For a given requirement, does a test exist that + verifies it, and did it pass in the last run? +- **Artifacts.** `requirement`, `test-case`, `test-run`, `verifies` + link, `test-result` with pass/fail + timestamp. +- **AI does.** Writes the test, then `rivet import-results --format + junit results.xml` stamps the run into the graph. Proposes + `verifies` links through the `rivet_link` MCP tool. +- **Human reviews.** The PR — code change and new `verifies` link in + one diff. + +### 4.2 ASPICE process tracking + +- **Question.** For each ASPICE process step (SWE.1 through SWE.6, + SYS.2 through SYS.5, SUP.*), are the required work products present + and correctly linked? +- **Artifacts.** The `aspice` schema ships 14 artifact types matching + ASPICE 4.0 V-model. +- **AI does.** Generates SWE.4 `sw-unit-verification-result` entries + from `rivet import-results --format junit` output. Drafts + `sw-architecture` records from source files via `rivet discover` + **(planned for v0.5.0)**. +- **Human reviews.** Whether the generated artifacts represent the + real work — in a PR, before they become evidence. An assessor still + signs the final report. +- **Today.** A dogfood project ships **268 ASPICE artifacts at 97% + coverage**. + +### 4.3 ISO 26262 / STPA safety analysis + +- **Question.** For each identified hazard, is there a traceable UCA, + a controller constraint, and a loss scenario? +- **Artifacts.** 34 hazards, 62 UCAs, 62 controller constraints live + in rivet's own STPA dogfood (`safety/stpa/`), plus the STPA-Sec + adversarial extension (`safety/stpa-sec/`) and a tool-qualification + STPA (`safety/stpa/tool-qualification.yaml`). +- **AI does.** Proposes new UCAs from a scenario description using + the four UCA categories (not-providing / providing / wrong-timing / + wrong-duration). `rivet validate` runs cross-rule consistency. +- **Human reviews.** The safety engineer signs off on the UCA + taxonomy and controller-constraint derivation. +- **Limit.** No `iso-26262.yaml` schema yet — today you combine + `iec-61508.yaml` (ISO 26262 derives from it) with STPA and the + safety-case schema. A dedicated ISO 26262 work-product schema is + **planned for v0.5.0**. + +### 4.4 Requirements engineering + +- **Question.** For each requirement: what design satisfies it, what + feature realises it, what test verifies it, is the chain complete? +- **Artifacts.** The `REQ → DD → FEAT → TEST` chain with `rivet + coverage` and `rivet matrix`. `rivet validate --baseline v0.4.0` + limits the view to artifacts frozen at a given release. +- **AI does.** Drafts requirements from user intent, proposes the + decomposition tree, emits `satisfies` / `refines` / `verifies` + links. +- **Human reviews.** The semantic correctness of the decomposition. + rivet guarantees structural integrity only. + +### 4.5 Variant / Product Line Engineering + +- **Question.** For a given variant (feature configuration), which + requirements, tests, and hazards apply — and is the variant + constraint-satisfiable? +- **Artifacts.** `feature-model.yaml` (the feature tree), + `variant-config.yaml` (selections), `binding.yaml` (feature → + artifact links). See `examples/variant/`. +- **AI does.** Proposes variant bindings from user-stated preferences + and queries the graph in s-expression — `(and (= type "requirement") + (has-tag "stpa"))` — using the `forall`, `exists`, `reachable-from`, + `reachable-to` predicates in the evaluator. +- **Human reviews.** Whether the feature-model constraints encode the + real product-line rules. + +### 4.6 LLM-assisted code review and authoring + +- **Question.** Can my AI agent read the trace graph and propose + mutations that rivet server-side-validates before I accept them? +- **Artifacts.** All of them, through MCP. +- **AI does.** Calls 15 MCP tools: `rivet_list`, `rivet_get`, + `rivet_query`, `rivet_stats`, `rivet_coverage`, `rivet_schema`, + `rivet_embed`, `rivet_add`, `rivet_modify`, `rivet_link`, + `rivet_unlink`, `rivet_remove`, `rivet_validate`, + `rivet_snapshot_capture`, `rivet_reload`. +- **Human reviews.** The MCP audit log (`rivet mcp` writes every + mutation call as JSONL to the project directory) plus the git diff. + +### 4.7 Provenance and AI attestation + +- **Question.** Which AI session authored which artifact, which model + produced it, did a human approve it? +- **Artifacts.** Every artifact carries an optional `provenance` + block: `created-by` (human / ai / ai-assisted), `model`, + `session-id`, `timestamp`, `reviewed-by`. +- **AI does.** `rivet stamp --created-by ai-assisted --model + claude-opus-4-7` on every touch. A PostToolUse hook in + `.claude/settings.json` automates this. +- **Human reviews.** The stamp record in the PR. Missing or stale + provenance is a review smell. +- **Why it matters.** EU AI Act Article 12 requires "logging of + events over the lifecycle"; ISO/PAS 8800 carries an equivalent + runtime-evidence requirement. + +### 4.8 Cross-tool interop + +- **Question.** Can I use rivet as an AI-querying and validation + layer over an existing Polarion, Jira, or DOORS deployment? +- **Artifacts.** `rivet import` from ReqIF 1.2 (DOORS, Polarion, + codebeamer) and sphinx-needs JSON. +- **Exports.** ReqIF, HTML, Zola (multi-project via `--prefix`), + Gherkin (`rivet export --gherkin` writes `.feature` files from + acceptance criteria), generic YAML. +- **Limit.** Direct Polarion REST integration is **planned for + v0.5.0**. + [docs/design/polarion-reqif-fidelity.md](design/polarion-reqif-fidelity.md) + is the field-by-field audit of what the two paths can and cannot + carry. + +### 4.9 Safety case assembly (GSN) + +- **Question.** Is there an explicit argument — goal, strategy, + solution, context, assumption — that links claims to evidence? +- **Artifacts.** `schemas/safety-case.yaml` (GSN 3 community + standard) plus cross-schema bridges to STPA and EU AI Act in + `schemas/safety-case-stpa.bridge.yaml` and + `schemas/safety-case-eu-ai-act.bridge.yaml`. +- **AI does.** Drafts goal / strategy / solution nodes from + requirements, hazards, and test evidence. +- **Human reviews.** The safety engineer signs off on the argument + structure. rivet checks that every node references something real. + +### 4.10 Tool qualification (TCL / TQL) + +- **Question.** Is rivet itself qualified as a development tool for + my certification context (ISO 26262-8 §11, DO-178C §12.2, IEC + 62304 §8.4)? +- **Artifacts.** `safety/stpa/tool-qualification.yaml` — rivet's own + STPA-based tool-confidence analysis at TCL 1. Dogfood, and also a + template you can copy. +- **AI does.** Proposes tool-impact analyses for new rivet features. +- **Human reviews.** The tool user signs off on TCL assignment. +- **Limit.** A full qualification kit (tool operational requirements, + verification procedure, qualification report) is **planned for + v0.5.0**. + +### 4.11 Spec-driven development + +- **Question.** Does my code meet the declared constraints in the + spec artifacts? +- **Artifacts.** The s-expression evaluator + (`rivet-core/src/sexpr_eval.rs`) supports `forall`, `exists`, + `has-tag`, `has-link-type`, `reachable-from`, `reachable-to`, + arithmetic, equality, and boolean ops. Constraints live in the + schema next to the artifact type they constrain. +- **AI does.** Writes code; runs `rivet validate` to check that the + declared constraint language is satisfied. +- **Human reviews.** The constraint in the schema, not the artifact. + Once reviewed, it re-applies to every artifact of that type + forever. + +--- + +## 5. Human vs AI split — explicit + +| Task | Human | AI agent | +|---|---|---| +| Author a requirement | reviews and approves the PR | drafts YAML from user intent via `rivet_add` | +| Link artifacts | reviews `satisfies` / `verifies` / `refines` edges in the diff | proposes links via `rivet_link` | +| Validation | runs `rivet validate` locally before PR | receives structured diagnostics via `rivet_validate` | +| Coverage reports | reads the dashboard at `rivet serve` | embeds `{{coverage}}` in generated docs via `rivet_embed` | +| Variant check | reads PASS/FAIL on `rivet validate --variant` | generates variant bindings from feature preferences | +| Provenance | reviews the `provenance` block in the stamp | calls `rivet stamp` on every touch (or PostToolUse hook) | +| Compliance export | signs the report | produces ReqIF, Zola, or JSON on demand via `rivet export` | +| Tool qualification | assigns TCL / TQL | drafts tool-impact analysis for new rivet features | +| Schema changes | reviews schema semantics | does not touch schemas unless asked | + +The asymmetry is the design. The human owns semantic correctness; +the AI owns volume. rivet is the substrate that makes the handover +trustworthy. + +--- + +## 6. What rivet is NOT + +Honesty over hype. + +- **Not a replacement for Polarion's live collaborative editing.** + rivet is git-based. Two humans editing the same YAML file at the + same time is a merge conflict, not a live cursor. +- **Not a direct Polarion / Jira / DOORS connector today.** ReqIF + import/export works. Direct REST to Polarion is + **planned for v0.5.0** — design already in + [docs/design/polarion-reqif-fidelity.md](design/polarion-reqif-fidelity.md). +- **Not yet a turnkey ISO 26262 solution.** No `iso-26262.yaml` + schema today. You assemble from `iec-61508.yaml` + STPA + safety + case + your own overlay. Dedicated schema **planned for v0.5.0**. +- **Not yet distributed via npm.** `claude mcp add rivet npx -y + @pulseengine/rivet mcp` is **planned for v0.5.0**. Today: `cargo + install --path rivet-cli` and point your MCP client at the built + binary. +- **Not suitable for teams without git discipline.** Artifacts live + in the repo. Branches, PRs, and reviews are the workflow — not a + bolt-on. +- **Not a secrets store.** Artifacts are text files. Indexed, + validated, rendered — not encrypted. +- **Not a project-management tool.** No Gantt, no sprint planning, + no Kanban. rivet tracks engineering artifacts, not tickets. + +--- + +## 7. Quick start + +Shortest path from zero to validated evidence. + +```bash +# 1. Install (npm distribution planned for v0.5.0) +cargo install --path rivet-cli + +# 2. Initialise a project (preset: dev / aspice / stpa / iec-61508 / ...) +rivet init --preset dev + +# 3. (Optional) Install git hooks and AGENTS.md for AI coding agents +rivet init --hooks +rivet init --agents + +# 4. Add an artifact +rivet add requirement --title "System must reject malformed YAML" --status draft + +# 5. Link it +rivet link REQ-001 satisfies FEAT-001 + +# 6. Validate — this is the evidence test +rivet validate + +# 7. Browse +rivet serve --port 3000 + +# 8. Wire an AI agent — the MCP server speaks to Claude, Cursor, Gemini, ... +# Today (local binary): +# claude mcp add rivet /absolute/path/to/rivet mcp +# Planned for v0.5.0 (npm): +# claude mcp add rivet npx -y @pulseengine/rivet mcp +``` + +From step 6 you have evidence that would pass a PR review. From step +8 an AI agent can read and propose mutations to the graph, each one +server-side-validated before it lands. + +--- + +## 8. Where to go next + +- **CLI reference.** `rivet docs --list` for all built-in topics, or + the `## CLI Commands` table in [README.md](../README.md). +- **Getting started tutorial.** + [docs/getting-started.md](getting-started.md). +- **Architecture.** [docs/architecture.md](architecture.md). +- **Schemas in depth.** [docs/schemas.md](schemas.md). +- **STPA methodology dogfood.** [docs/stpa-sec.md](stpa-sec.md) plus + `safety/stpa/` and `safety/stpa-sec/`. +- **Verification evidence.** [docs/verification.md](verification.md) + — 27 Kani BMC harnesses, Verus specs, Rocq proofs, 324 Playwright + end-to-end tests. +- **Polarion / ReqIF fidelity audit.** + [docs/design/polarion-reqif-fidelity.md](design/polarion-reqif-fidelity.md). +- **Roadmap.** [docs/roadmap.md](roadmap.md). +- **Audit report.** [docs/audit-report.md](audit-report.md) — state + of doc-vs-reality after PR #171's audit. + +--- + +*Last updated 2026-04-19 for v0.4.1 positioning. If a claim in this +doc does not match the tree at `main` HEAD, file an issue — the +purpose of rivet is that its own evidence chain is audit-grade.*