From 272841c8b019720637fb7224f38a5d7905d29a01 Mon Sep 17 00:00:00 2001 From: Ralf Anton Beier Date: Wed, 22 Apr 2026 06:46:03 +0200 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20v0.4.1=20positioning=20=E2=80=94=20?= =?UTF-8?q?Evidence=20as=20Code=20frame?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add docs/what-is-rivet.md as the canonical positioning doc: - Frame rivet as the audit substrate for AI-assisted engineering (not "SDLC traceability"). Contrast with Sphinx-Needs' "Engineering as Code": rivet is "Evidence as Code" — AI-authored, provenance-stamped, machine-validated, human-reviewed in PRs. - Document the per-situation playbook for 11 use-cases (TDD, ASPICE, STPA/ISO 26262, requirements, variant/PLE, LLM code review, provenance, cross-tool interop, GSN, tool qualification, spec-driven dev), each with question, artifacts, AI role, human role, and explicit limits. - Make the human-vs-AI split explicit in a table. - Document what rivet is NOT (no Polarion live editing, no direct ALM connector today, no iso-26262.yaml schema yet, no npm distribution yet — all marked "planned for v0.5.0"). - Quick-start with today's install path (cargo) plus the planned npm path for v0.5.0. Rewrite README.md intro (top ~30 lines) to align with the frame — replacing the feature-list first paragraph with an evidence-centric one-paragraph pitch that points at docs/what-is-rivet.md for depth. All capability claims are verifiable against main HEAD: 34 hazards + 62 UCAs + 62 controller constraints in safety/stpa/, the MCP tool list (rivet_list/get/query/add/modify/link/unlink/remove/validate/ coverage/stats/schema/embed/snapshot_capture/reload) matches rivet-cli/src/mcp.rs, and the s-expr predicates (forall/exists/reachable-from/reachable-to) match rivet-core/src/sexpr_eval.rs. Refs: FEAT-001 Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 10 +- docs/what-is-rivet.md | 399 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 406 insertions(+), 3 deletions(-) create mode 100644 docs/what-is-rivet.md diff --git a/README.md b/README.md index faeb768..41f082e 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,13 @@ 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. +**Rivet is the audit substrate for AI-assisted engineering — every artifact, link, and decision carries evidence a human can review in a pull request.** -No database, no external service, just text files and a fast Rust CLI. +AI agents draft the requirements, hazards, design decisions, test specs, and variant bindings. Rivet stamps them with provenance (model, session, timestamp), validates them against mergeable schemas (STPA, ASPICE, ISO/PAS 8800, IEC 61508, IEC 62304, DO-178C, EN 50128, EU AI Act, GSN), and lets a human approve or reject the change in a single git diff. The MCP server exposes the artifact graph to Claude, Cursor, and other agents as typed tools; every mutation is server-side validated before it lands. + +One schema system, many domains — TDD, ASPICE, safety analysis, requirements, variants, GSN safety cases. One linker, many workflows. **No database, no external service — text files, git, and a fast Rust CLI.** + +See **[docs/what-is-rivet.md](docs/what-is-rivet.md)** for the positioning frame — who it is for, 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..1dfdee8 --- /dev/null +++ b/docs/what-is-rivet.md @@ -0,0 +1,399 @@ +# What is rivet? + +> **rivet is the audit substrate for AI-assisted engineering — +> every artifact, link, and decision carries evidence a human can +> review in a pull request.** + +This document exists because users keep asking the same question in +different shapes: *"is rivet for me?"*, *"what do I use it for?"*, +*"how is it different from Sphinx-Needs / Polarion / DOORS?"*. The +honest answer is: **rivet is a general template to link and validate +SDLC evidence, and per situation you use it differently.** The +generality is the point — and also the problem this doc is trying to +solve. + +What follows is a frame, a 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 engineer is the author and the doc-as-code pipeline +is the publisher. It is an excellent frame — for human-authored +workflows. + +rivet is aimed at a different centre of gravity. The assumption is +that **AI agents are drafting the artifacts** — requirements, hazards, +design decisions, test specs, variant bindings — and a human is +**reviewing the diff in a pull request**. That shift changes what the +tool has to do: + +- Every artifact needs a verifiable **provenance record**: who (human + vs ai vs ai-assisted), which model, which session, when, reviewed + by whom. +- Every change must survive **machine validation** before it is + trustworthy as evidence: link integrity, cardinality, schema rules, + s-expression constraints, variant consistency. +- The change surface must be **git-native** so the human's PR review + *is* the approval step — not a separate workflow in a separate tool. +- Agents must be able to 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 — built so that AI coding agents can author artifacts and +humans can cross-verify them in the same pull request. + +Format-agnostic LLM comprehension studies (e.g. +[arxiv.org/abs/2604.13108](https://arxiv.org/abs/2604.13108)) suggest +it does not matter much whether the artifact store is YAML, JSON, +Markdown, or s-expressions — what matters is that the *structure* is +explicit and the *provenance* is recoverable. rivet picks YAML as the +on-disk format because humans have to review it; the agent doesn't +care either way. + +--- + +## 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 with domain schemas for 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. It validates with a salsa-backed incremental +engine, records AI provenance on every mutation, and is backed by 27 +Kani bounded-model-checking harnesses, Verus specs, Rocq proofs for +the core validation rules, and roughly 324 Playwright end-to-end +tests across 28 spec files. + +--- + +## 3. Who rivet is for + +- **Safety-critical teams with a compliance standard.** If you are + working to ISO 26262 (via IEC 61508), DO-178C, IEC 61508, 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 honesty audit of what survives the ReqIF + interchange. + +- **Rust and embedded teams running AI pair-programming.** rivet is + written in Rust and eats its own dog food (219+ artifacts across + requirements, features, design decisions, hazards, UCAs, tests, + verifications). If you already use Claude Code / Cursor / Gemini + to write code and you want the *evidence* to survive the session, + `rivet mcp` and `rivet stamp` are the point. + +- **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` + gets you audit evidence from a git repo in seconds. + +- **AI platform teams building agentic-SDLC workflows** where the + evidence must outlive the conversation. rivet's `provenance` field + captures `created-by`, `model`, `session-id`, `timestamp`, and + `reviewed-by` on every artifact — and `rivet stamp` writes them in + a way that passes schema validation. + +--- + +## 4. The use-case palette + +This is the hard part. rivet's schema system is domain-agnostic, so +the same tool is used very differently per situation. What follows +is a per-situation playbook — *what question does it answer*, *what +does the AI do*, *what does the human review*. + +### 4.1 Test-driven development (TDD) + +- **Question answered.** For a given requirement, does a test exist + that verifies it, and did it pass in the last run? +- **Artifacts used.** `requirement`, `test-case`, `test-run`, + `verifies` link, `test-result` with pass/fail + timestamp. +- **AI does.** Writes the test, then runs `rivet import-results + --format junit results.xml` to stamp the run into the graph. + Proposes `verifies` links via `rivet_link` on MCP. +- **Human reviews.** The PR — both the code change and the new + `verifies` link — in one diff. + +### 4.2 ASPICE tracking + +- **Question answered.** 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 used.** The `aspice` schema ships 14 artifact types + matching the ASPICE 4.0 V-model. +- **AI does.** Generates `sw-unit-verification-result` (SWE.4) entries + from test output. Drafts `sw-architecture` records from code. +- **Human reviews.** Whether the generated artifacts accurately + represent the real work — in a PR, before they become evidence. +- **Limit.** No turnkey ASPICE assessment kit. You still need an + assessor. See [roadmap](roadmap.md). + +### 4.3 ISO 26262 / STPA safety analysis + +- **Question answered.** For each identified hazard, is there a + traceable UCA, a controller constraint, and a loss scenario? +- **Artifacts used.** 34 hazards, 62 UCAs, 62 controller constraints + in rivet's own STPA dogfood (`safety/stpa/`), plus the STPA-Sec + adversarial extension (`safety/stpa-sec/`) and the tool + qualification analysis (`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). Runs cross-rule consistency via `rivet validate`. +- **Human reviews.** Safety engineer signs off on the UCA taxonomy + and the controller-constraint derivation. +- **Limit.** There is no `iso-26262.yaml` schema yet — today you use + `iec-61508.yaml` (ISO 26262 is derived from IEC 61508) plus the + STPA and safety-case schemas. A dedicated ISO 26262 work-product + schema is **planned for v0.5.0**. + +### 4.4 Requirements engineering + +- **Question answered.** For each requirement, what design satisfies + it, what feature realises it, what test verifies it, and is there + coverage across the chain? +- **Artifacts used.** The classic `REQ → DD → FEAT → TEST` chain with + `rivet coverage` and `rivet matrix`. Baseline scoping via + `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 only guarantees structural integrity. + +### 4.5 Variant / Product Line Engineering + +- **Question answered.** For a given variant (feature configuration), + which requirements, tests, and hazards apply — and is the variant + constraint-satisfiable? +- **Artifacts used.** `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. Queries via s-expression — `(and (= type + "requirement") (has-tag "stpa"))` — using the `forall`, `exists`, + `reachable-from`, `reachable-to` predicates built into the + evaluator. +- **Human reviews.** Whether the feature-model constraints encode + the real product line rules. + +### 4.6 LLM-assisted code review and authoring + +- **Question answered.** Can my AI agent read the trace graph and + propose mutations that rivet server-side-validates before I accept + them? +- **Artifacts used.** All of them, via MCP. +- **AI does.** Calls the 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 answered.** Which AI session authored which artifact, + which model produced it, and did a human approve it? +- **Artifacts used.** Every artifact has an optional `provenance` + object: `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.** Prep for EU AI Act Article 12 ("logging of + events over the lifecycle") and the analogous runtime-evidence + requirements in ISO/PAS 8800. + +### 4.8 Cross-tool interop + +- **Question answered.** Can I use rivet as an AI-querying and + validation layer over an existing Polarion, Jira, or DOORS + deployment? +- **Artifacts used.** `rivet import` from ReqIF 1.2 (DOORS / Polarion + / codebeamer) and sphinx-needs JSON. +- **Exports.** ReqIF, HTML, Zola (multi-project with `--prefix`), + Gherkin (`rivet export --gherkin` generates `.feature` files from + acceptance criteria), and generic YAML. +- **Limit.** Direct Polarion REST integration is **planned for + v0.5.0**. See + [docs/design/polarion-reqif-fidelity.md](design/polarion-reqif-fidelity.md) + for a field-by-field audit of what the two paths can and cannot + carry — today and after v0.5.0. + +### 4.9 Safety case assembly (GSN) + +- **Question answered.** Is there an explicit argument — goal, + strategy, solution, context, assumption — that links claims to + evidence? +- **Artifacts used.** `schemas/safety-case.yaml` (GSN 3 community + standard) with cross-schema bridges to STPA and EU AI Act + (`schemas/safety-case-stpa.bridge.yaml`, + `schemas/safety-case-eu-ai-act.bridge.yaml`). +- **AI does.** Drafts goal / strategy / solution nodes from + requirements + hazards + 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 answered.** 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 used.** `safety/stpa/tool-qualification.yaml` is + rivet's own STPA-based tool-confidence analysis (TCL 1). It is + dogfood, but it is also a template you can copy into your project + and adapt. +- **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 answered.** Does my code meet the declared constraints + in the spec artifacts? +- **Artifacts used.** The s-expression evaluator + (`rivet-core/src/sexpr_eval.rs`) supports `forall`, `exists`, + `has-tag`, `has-link-type`, `reachable-from`, `reachable-to`, + arithmetic, equality, boolean ops. Constraints live in the schema + next to the artifact type they constrain. +- **AI does.** Writes code; runs `rivet validate` to check the + declared constraint language is satisfied. +- **Human reviews.** The constraint itself in the schema, not the + artifact. Once a constraint is reviewed, it re-applies to every + artifact of that type forever. + +--- + +## 5. Human vs AI split — explicit + +| Task | Human does | AI agent does | +|---|---|---| +| Authoring a requirement | reviews + approves the PR | drafts YAML from user intent via `rivet_add` | +| Linking artifacts | reviews the `satisfies`/`verifies`/`refines` edges in the diff | proposes links via `rivet_link` on MCP | +| Validation | runs `rivet validate` locally before PR | gets structured diagnostics via `rivet_validate` tool | +| 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 / JSON on demand via `rivet export` | +| Tool qualification | assigns TCL / TQL | proposes tool-impact analysis for new rivet features | +| Schema changes | reviews the schema semantics | never touches schemas unless explicitly 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** — the design is already in + [docs/design/polarion-reqif-fidelity.md](design/polarion-reqif-fidelity.md). +- **Not yet a turnkey ISO 26262 solution.** There is no + `iso-26262.yaml` schema today. You assemble from `iec-61508.yaml` + + STPA + safety-case + your own overlay. A dedicated schema is + **planned for v0.5.0**. +- **Not yet distributed via npm.** The `claude mcp add rivet npx -y + @pulseengine/rivet mcp` flow is **planned for v0.5.0**. Today you + install via `cargo install --path rivet-cli` and point your MCP + client at the built binary. +- **Not suitable for teams without git discipline.** The artifacts + live in the repo. Branches, PRs, and reviews are the workflow — + not a bolt-on. +- **Not a secrets store, CI-secret manager, or credential vault.** + Artifacts are text files; they are indexed, validated, and + rendered, but they are not encrypted. +- **Not a project-management tool.** No Gantt, no sprint planning, + no Kanban. rivet tracks traceable 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 (choose a 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, all +server-side-validated before the mutation 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/` in the repo. +- **Verification evidence.** [docs/verification.md](verification.md) + — 27 Kani BMC harnesses, Verus specs, Rocq proofs for the core + validation rules, 324 Playwright end-to-end tests. +- **Polarion / ReqIF fidelity audit.** + [docs/design/polarion-reqif-fidelity.md](design/polarion-reqif-fidelity.md) + — field-by-field honesty about what survives the interchange. +- **Roadmap.** [docs/roadmap.md](roadmap.md). +- **Audit report.** [docs/audit-report.md](audit-report.md) — the + current 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.* From 7812eceab6f3a9e3fe1142244767aa17f0d9ac1b Mon Sep 17 00:00:00 2001 From: Ralf Anton Beier Date: Wed, 22 Apr 2026 06:58:19 +0200 Subject: [PATCH 2/2] docs(positioning): align voice to v0.1.0 blog cadence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrites docs/what-is-rivet.md and the README intro to match the rivet-v0-1-0 blog post cadence: Problem → Answer → Evidence, concrete numbers per section, no marketing vocabulary, three-sentence README intro (problem / answer / concrete result). All facts from 3b89365 preserved. Honesty flags for planned-for-v0.5.0 items kept. Use-case palette kept; human-vs-AI table tightened. Refs: FEAT-001 --- README.md | 8 +- docs/what-is-rivet.md | 407 ++++++++++++++++++++---------------------- 2 files changed, 192 insertions(+), 223 deletions(-) diff --git a/README.md b/README.md index 41f082e..6745f13 100644 --- a/README.md +++ b/README.md @@ -30,13 +30,7 @@ Spar parses. Etch renders. Meld fuses. **Rivet binds.** -**Rivet is the audit substrate for AI-assisted engineering — every artifact, link, and decision carries evidence a human can review in a pull request.** - -AI agents draft the requirements, hazards, design decisions, test specs, and variant bindings. Rivet stamps them with provenance (model, session, timestamp), validates them against mergeable schemas (STPA, ASPICE, ISO/PAS 8800, IEC 61508, IEC 62304, DO-178C, EN 50128, EU AI Act, GSN), and lets a human approve or reject the change in a single git diff. The MCP server exposes the artifact graph to Claude, Cursor, and other agents as typed tools; every mutation is server-side validated before it lands. - -One schema system, many domains — TDD, ASPICE, safety analysis, requirements, variants, GSN safety cases. One linker, many workflows. **No database, no external service — text files, git, and a fast Rust CLI.** - -See **[docs/what-is-rivet.md](docs/what-is-rivet.md)** for the positioning frame — who it is for, the per-situation playbook, and explicit limits. +**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 index 1dfdee8..73dc685 100644 --- a/docs/what-is-rivet.md +++ b/docs/what-is-rivet.md @@ -1,60 +1,45 @@ -# What is rivet? +# rivet: because AI agents still don't remember why -> **rivet is the audit substrate for AI-assisted engineering — -> every artifact, link, and decision carries evidence a human can -> review in a pull request.** +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 exists because users keep asking the same question in -different shapes: *"is rivet for me?"*, *"what do I use it for?"*, -*"how is it different from Sphinx-Needs / Polarion / DOORS?"*. The -honest answer is: **rivet is a general template to link and validate -SDLC evidence, and per situation you use it differently.** The -generality is the point — and also the problem this doc is trying to -solve. - -What follows is a frame, a 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)**. +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 engineer is the author and the doc-as-code pipeline -is the publisher. It is an excellent frame — for human-authored -workflows. - -rivet is aimed at a different centre of gravity. The assumption is -that **AI agents are drafting the artifacts** — requirements, hazards, -design decisions, test specs, variant bindings — and a human is -**reviewing the diff in a pull request**. That shift changes what the -tool has to do: - -- Every artifact needs a verifiable **provenance record**: who (human - vs ai vs ai-assisted), which model, which session, when, reviewed - by whom. -- Every change must survive **machine validation** before it is - trustworthy as evidence: link integrity, cardinality, schema rules, +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 must be **git-native** so the human's PR review - *is* the approval step — not a separate workflow in a separate tool. -- Agents must be able to read and mutate the evidence graph through a - typed interface, not a screen-scrape. +- 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 — built so that AI coding agents can author artifacts and -humans can cross-verify them in the same pull request. - -Format-agnostic LLM comprehension studies (e.g. -[arxiv.org/abs/2604.13108](https://arxiv.org/abs/2604.13108)) suggest -it does not matter much whether the artifact store is YAML, JSON, -Markdown, or s-expressions — what matters is that the *structure* is -explicit and the *provenance* is recoverable. rivet picks YAML as the -on-disk format because humans have to review it; the agent doesn't -care either way. +scaffolding. AI agents author, humans cross-verify, the same PR +carries both. --- @@ -63,138 +48,136 @@ care either way. 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 with domain schemas for 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. It validates with a salsa-backed incremental -engine, records AI provenance on every mutation, and is backed by 27 -Kani bounded-model-checking harnesses, Verus specs, Rocq proofs for -the core validation rules, and roughly 324 Playwright end-to-end -tests across 28 spec files. +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.** If you are - working to ISO 26262 (via IEC 61508), DO-178C, IEC 61508, 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 +- **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 honesty audit of what survives the ReqIF - interchange. + 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 eats its own dog food (219+ artifacts across - requirements, features, design decisions, hazards, UCAs, tests, - verifications). If you already use Claude Code / Cursor / Gemini - to write code and you want the *evidence* to survive the session, - `rivet mcp` and `rivet stamp` are the point. + 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` - gets you audit evidence from a git repo in seconds. + produces audit evidence from a git repo in seconds. -- **AI platform teams building agentic-SDLC workflows** where the - evidence must outlive the conversation. rivet's `provenance` field - captures `created-by`, `model`, `session-id`, `timestamp`, and - `reviewed-by` on every artifact — and `rivet stamp` writes them in - a way that passes schema validation. +- **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 -This is the hard part. rivet's schema system is domain-agnostic, so -the same tool is used very differently per situation. What follows -is a per-situation playbook — *what question does it answer*, *what -does the AI do*, *what does the human review*. +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 answered.** For a given requirement, does a test exist - that verifies it, and did it pass in the last run? -- **Artifacts used.** `requirement`, `test-case`, `test-run`, - `verifies` link, `test-result` with pass/fail + timestamp. -- **AI does.** Writes the test, then runs `rivet import-results - --format junit results.xml` to stamp the run into the graph. - Proposes `verifies` links via `rivet_link` on MCP. -- **Human reviews.** The PR — both the code change and the new - `verifies` link — in one diff. - -### 4.2 ASPICE tracking - -- **Question answered.** 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 used.** The `aspice` schema ships 14 artifact types - matching the ASPICE 4.0 V-model. -- **AI does.** Generates `sw-unit-verification-result` (SWE.4) entries - from test output. Drafts `sw-architecture` records from code. -- **Human reviews.** Whether the generated artifacts accurately - represent the real work — in a PR, before they become evidence. -- **Limit.** No turnkey ASPICE assessment kit. You still need an - assessor. See [roadmap](roadmap.md). +- **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 answered.** For each identified hazard, is there a - traceable UCA, a controller constraint, and a loss scenario? -- **Artifacts used.** 34 hazards, 62 UCAs, 62 controller constraints +- **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 the tool - qualification analysis (`safety/stpa/tool-qualification.yaml`). + 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). Runs cross-rule consistency via `rivet validate`. -- **Human reviews.** Safety engineer signs off on the UCA taxonomy - and the controller-constraint derivation. -- **Limit.** There is no `iso-26262.yaml` schema yet — today you use - `iec-61508.yaml` (ISO 26262 is derived from IEC 61508) plus the - STPA and safety-case schemas. A dedicated ISO 26262 work-product - schema is **planned for v0.5.0**. + 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 answered.** For each requirement, what design satisfies - it, what feature realises it, what test verifies it, and is there - coverage across the chain? -- **Artifacts used.** The classic `REQ → DD → FEAT → TEST` chain with - `rivet coverage` and `rivet matrix`. Baseline scoping via - `rivet validate --baseline v0.4.0` limits the view to artifacts - frozen at a given release. +- **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 only guarantees structural integrity. + 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 answered.** For a given variant (feature configuration), - which requirements, tests, and hazards apply — and is the variant +- **Question.** For a given variant (feature configuration), which + requirements, tests, and hazards apply — and is the variant constraint-satisfiable? -- **Artifacts used.** `feature-model.yaml` (the feature tree), +- **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. Queries via s-expression — `(and (= type - "requirement") (has-tag "stpa"))` — using the `forall`, `exists`, - `reachable-from`, `reachable-to` predicates built into the - evaluator. -- **Human reviews.** Whether the feature-model constraints encode - the real product line rules. +- **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 answered.** Can my AI agent read the trace graph and - propose mutations that rivet server-side-validates before I accept - them? -- **Artifacts used.** All of them, via MCP. -- **AI does.** Calls the MCP tools: `rivet_list`, `rivet_get`, +- **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`, @@ -204,60 +187,56 @@ does the AI do*, *what does the human review*. ### 4.7 Provenance and AI attestation -- **Question answered.** Which AI session authored which artifact, - which model produced it, and did a human approve it? -- **Artifacts used.** Every artifact has an optional `provenance` - object: `created-by` (human / ai / ai-assisted), `model`, +- **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.** Prep for EU AI Act Article 12 ("logging of - events over the lifecycle") and the analogous runtime-evidence - requirements in ISO/PAS 8800. +- **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 answered.** Can I use rivet as an AI-querying and - validation layer over an existing Polarion, Jira, or DOORS - deployment? -- **Artifacts used.** `rivet import` from ReqIF 1.2 (DOORS / Polarion - / codebeamer) and sphinx-needs JSON. -- **Exports.** ReqIF, HTML, Zola (multi-project with `--prefix`), - Gherkin (`rivet export --gherkin` generates `.feature` files from - acceptance criteria), and generic YAML. +- **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**. See + v0.5.0**. [docs/design/polarion-reqif-fidelity.md](design/polarion-reqif-fidelity.md) - for a field-by-field audit of what the two paths can and cannot - carry — today and after v0.5.0. + is the field-by-field audit of what the two paths can and cannot + carry. ### 4.9 Safety case assembly (GSN) -- **Question answered.** Is there an explicit argument — goal, - strategy, solution, context, assumption — that links claims to - evidence? -- **Artifacts used.** `schemas/safety-case.yaml` (GSN 3 community - standard) with cross-schema bridges to STPA and EU AI Act - (`schemas/safety-case-stpa.bridge.yaml`, - `schemas/safety-case-eu-ai-act.bridge.yaml`). +- **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 + test evidence. + requirements, hazards, and test evidence. - **Human reviews.** The safety engineer signs off on the argument - structure — rivet checks that every node references something - real. + structure. rivet checks that every node references something real. ### 4.10 Tool qualification (TCL / TQL) -- **Question answered.** 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 used.** `safety/stpa/tool-qualification.yaml` is - rivet's own STPA-based tool-confidence analysis (TCL 1). It is - dogfood, but it is also a template you can copy into your project - and adapt. +- **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, @@ -266,36 +245,36 @@ does the AI do*, *what does the human review*. ### 4.11 Spec-driven development -- **Question answered.** Does my code meet the declared constraints - in the spec artifacts? -- **Artifacts used.** The s-expression evaluator +- **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, boolean ops. Constraints live in the schema - next to the artifact type they constrain. -- **AI does.** Writes code; runs `rivet validate` to check the + 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 itself in the schema, not the - artifact. Once a constraint is reviewed, it re-applies to every - artifact of that type forever. +- **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 does | AI agent does | +| Task | Human | AI agent | |---|---|---| -| Authoring a requirement | reviews + approves the PR | drafts YAML from user intent via `rivet_add` | -| Linking artifacts | reviews the `satisfies`/`verifies`/`refines` edges in the diff | proposes links via `rivet_link` on MCP | -| Validation | runs `rivet validate` locally before PR | gets structured diagnostics via `rivet_validate` tool | +| 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 / JSON on demand via `rivet export` | -| Tool qualification | assigns TCL / TQL | proposes tool-impact analysis for new rivet features | -| Schema changes | reviews the schema semantics | never touches schemas unless explicitly asked | +| 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 asymmetry is the design. The human owns semantic correctness; the AI owns volume. rivet is the substrate that makes the handover trustworthy. @@ -310,25 +289,22 @@ Honesty over hype. 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** — the design is already in + **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.** There is no - `iso-26262.yaml` schema today. You assemble from `iec-61508.yaml` - + STPA + safety-case + your own overlay. A dedicated schema is - **planned for v0.5.0**. -- **Not yet distributed via npm.** The `claude mcp add rivet npx -y - @pulseengine/rivet mcp` flow is **planned for v0.5.0**. Today you - install via `cargo install --path rivet-cli` and point your MCP - client at the built binary. -- **Not suitable for teams without git discipline.** The artifacts - live in the repo. Branches, PRs, and reviews are the workflow — - not a bolt-on. -- **Not a secrets store, CI-secret manager, or credential vault.** - Artifacts are text files; they are indexed, validated, and - rendered, but they are not encrypted. +- **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 traceable engineering artifacts, not - tickets. + no Kanban. rivet tracks engineering artifacts, not tickets. --- @@ -340,7 +316,7 @@ Shortest path from zero to validated evidence. # 1. Install (npm distribution planned for v0.5.0) cargo install --path rivet-cli -# 2. Initialise a project (choose a preset: dev / aspice / stpa / iec-61508 / ...) +# 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 @@ -367,8 +343,8 @@ rivet serve --port 3000 ``` 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, all -server-side-validated before the mutation lands. +8 an AI agent can read and propose mutations to the graph, each one +server-side-validated before it lands. --- @@ -381,16 +357,15 @@ server-side-validated before the mutation lands. - **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/` in the repo. + `safety/stpa/` and `safety/stpa-sec/`. - **Verification evidence.** [docs/verification.md](verification.md) - — 27 Kani BMC harnesses, Verus specs, Rocq proofs for the core - validation rules, 324 Playwright end-to-end tests. + — 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) - — field-by-field honesty about what survives the interchange. + [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) — the - current state of doc-vs-reality after PR #171's audit. +- **Audit report.** [docs/audit-report.md](audit-report.md) — state + of doc-vs-reality after PR #171's audit. ---