Documentation refresh: assurance-driven story, domain discoverability, AI agent guidance, migration paths

[avrabe]

Context

The local codebase has leapt far ahead of the documentation. Recent commits (#101–#112) added MCP server, convergence tracking, EU AI Act schema, GSN safety cases, STPA-for-AI, bridge schemas, document embeds, oEmbed, and Grafana API. The README and docs still describe a tool with 8 schemas and 447 artifacts. Reality: 17 schemas, 518 artifacts, and features that directly address EU AI Act compliance, AI safety, and structured assurance arguments.

Beyond catching up, research into the competitive landscape and emerging methodologies reveals that rivet's natural workflow — schema-constrained, STPA-driven, continuously validated — aligns with assurance-driven development (ACCESS methodology, GSN-centric engineering). This story isn't told anywhere in the docs. It's the single biggest differentiator and the angle that resonates with UL 4600, ISO/PAS 8800, and EU AI Act audiences.

Additionally, the primary adoption path (Eclipse SCORE teams migrating from sphinx-needs) needs explicit migration guidance that doesn't exist.

Tasks

1. Push and release

All of #101–#112 should be on GitHub before documentation changes. Tag a release so the GitHub repo reflects reality.

2. Regenerate AGENTS.md

Run `rivet init --agents` to pick up 518 artifacts, new schemas (eu-ai-act, safety-case, stpa-ai), bridge schemas, and new commands (mcp, get, convergence).

3. Update README feature list

Add to the Features section:

• Safety cases / GSN — structured assurance arguments (goals, strategies, evidence) per GSN Community Standard v3
• STPA-for-AI — ML lifecycle hazards, data-driven UCAs, monitoring triggers, retraining requirements
• EU AI Act — Annex IV compliance schema with bridge schemas for STPA and ASPICE
• MCP server — `rivet mcp` for AI agent integration (Claude Code, Cursor, Goose)
• Convergence tracking — detect stuck agent loops via validation failure signatures
• Bridge schemas — compose domain schemas without duplicating types (5 bridges: eu-ai-act↔ASPICE, eu-ai-act↔STPA, safety-case↔EU AI Act, safety-case↔STPA, STPA↔dev)
• Document embeds — `{{artifact:ID}}` live embeds with diagnostics, matrix, snapshots
• oEmbed provider + Grafana JSON API — embed dashboard views externally

Update "8 schemas" → "17 schemas (9 domain + 5 bridge + 3 domain-AI)"
Update "447 artifacts" → current count from `rivet stats`

4. Add "Why Rivet?" section to getting-started.md

At the top, before installation. Brief, factual, no marketing fluff:

```markdown

Why Rivet?

• Schema-validated — not just linking artifacts, but enforcing traceability
  rules, cardinality constraints, and coverage requirements
• Git-native — YAML files, diffable, reviewable, CI-friendly. No database,
  no server, no Eclipse
• Composable schemas — mix ASPICE + STPA + cybersecurity + EU AI Act for
  your domain. Bridge schemas connect them without duplication
• STPA first-class — 15+ artifact types for safety analysis, with extensions
  for AI/ML systems and STPA-Sec adversarial analysis
• Safety cases — GSN goal-structuring notation for structured assurance
  arguments, bridgeable to STPA and EU AI Act
• AI-ready — MCP server for agent integration, AGENTS.md generation,
  convergence tracking for retry loops, `--format json` on everything
• Single binary — HTMX dashboard, fonts, Mermaid all bundled. Works offline
  ```

5. Add "Choose Your Domain" section to getting-started.md

After Quick Start, show what domain presets exist:

```markdown

Domain Presets

Preset	Schemas	Use Case
`dev`	common, dev	General software tracking
`stpa`	common, stpa	STPA safety analysis (SAE J3187)
`aspice`	common, aspice	Automotive ASPICE v4.0 V-model
`cybersecurity`	common, cybersecurity	ISO/SAE 21434 / ASPICE SEC.1-4
`eu-ai-act`	common, eu-ai-act	EU AI Act high-risk AI (Aug 2026 deadline)
`stpa-ai`	common, stpa, stpa-ai	AI/ML safety analysis (ISO/PAS 8800)
`safety-case`	common, safety-case	GSN assurance arguments (UL 4600)
`score`	common, score	Eclipse SCORE metamodel

Combine schemas for cross-domain projects:
```yaml
schemas: [common, aspice, stpa, cybersecurity, eu-ai-act-stpa.bridge]
```
```

6. Add assurance-driven workflow documentation

New section in getting-started.md or a separate `docs/assurance-driven-development.md`:

What it is: Instead of starting with requirements and hoping you end up with a safety argument, start with the safety case (what must you prove?) and let rivet tell you what evidence is missing.

Workflow:

1. Define top-level safety goals:
   ```bash
   rivet add -t safety-goal --title "System detects pedestrians under all conditions" --status draft
   ```

2. Decompose via strategies and sub-goals:
   ```bash
   rivet add -t safety-strategy --title "Argued over environmental conditions" --link "decomposes:SG-001"
   ```

3. Check what evidence is missing:
   ```bash
   rivet coverage --type safety-goal

   → SG-001: missing safety-solution (no evidence)

   → SG-002: supported by SOL-001 ✓

   ```

4. Fill gaps with requirements, tests, analysis that link back as solutions:
   ```bash
   rivet add -t safety-solution --title "Pedestrian detection test report"
   --link "supports:SG-001" --field "evidence-type:test-report"
   ```

5. Validate the complete argument:
   ```bash
   rivet validate

   Every goal has evidence or decomposition ✓

   Every strategy decomposes into sub-goals ✓

   Complete assurance argument PASS

   ```

Reference: ACCESS methodology (Assurance Case Centric Engineering of Safety-Critical Systems), UL 4600 safety case structure, ISO/PAS 8800 assurance arguments.

7. Add examples/safety-case/

A minimal but complete assurance-driven example project:

```
examples/safety-case/
rivet.yaml # schemas: [common, safety-case, stpa, safety-case-stpa.bridge]
artifacts/
goals.yaml # 3-4 safety goals with strategies
evidence.yaml # Solutions linking to goals
safety/stpa/
analysis.yaml # STPA analysis feeding the safety case
```

This is the entry point for anyone who discovers rivet through UL 4600, ISO/PAS 8800, or "structured safety case" searches.

8. Add docs/migrating-from-sphinx-needs.md

Target audience: Eclipse SCORE teams and anyone currently using sphinx-needs.

Contents:

• What rivet does differently — standalone CLI validation (no Sphinx build), composable schemas (not Python extensions), incremental LSP (not batch), single binary (not pip+sphinx+bazel)
• Migration path — `rivet import --format needs-json path/to/needs.json`
• Schema mapping — how sphinx-needs types/links map to rivet schemas
• What you gain — schema-driven validation rules, bridge schemas for cross-domain, dashboard, VS Code extension, MCP server, CI-friendly JSON output
• What's different — artifacts are standalone YAML (not embedded in RST), validation is separate from documentation generation

9. Document bridge schemas in docs/schemas.md

Add a section explaining the bridge schema concept:

```markdown

Bridge Schemas

Bridge schemas compose two domain schemas by adding cross-domain link types
and traceability rules without duplicating artifact types.

A bridge only contains `link-types` and `traceability-rules` — no
`artifact-types`. It extends both parent schemas.

Available Bridges

Bridge	Connects	Purpose
`eu-ai-act-stpa.bridge`	EU AI Act ↔ STPA	Risk assessments linked to STPA hazards
`eu-ai-act-aspice.bridge`	EU AI Act ↔ ASPICE	Performance evaluations from ASPICE verification
`safety-case-stpa.bridge`	Safety Case ↔ STPA	GSN goals linked to STPA losses/hazards
`safety-case-eu-ai-act.bridge`	Safety Case ↔ EU AI Act	Assurance arguments for AI system compliance
`stpa-dev.bridge`	STPA ↔ Dev	STPA hazards linked to dev requirements/features

Usage

List all schemas including bridges in your `rivet.yaml`:

```yaml
schemas:

• common
• aspice
• stpa
• eu-ai-act
• eu-ai-act-stpa.bridge
• eu-ai-act-aspice.bridge
  ```
  ```

10. Expand CLAUDE.md with AI agent guidance

```markdown

CLAUDE.md

See AGENTS.md for full project instructions.

AI Agent Workflow

1. Check state: `rivet validate --format json`
2. Find gaps: `rivet coverage --format json` to see what's missing
3. Create artifacts: `rivet add -t --title "..." --link "satisfies:ID"`
4. Validate: `rivet validate` — must pass before committing

MCP Server

This project supports `rivet mcp` for direct tool access without shell parsing.
Configure in `.claude/settings.json`:

```json
{"mcpServers": {"rivet": {"command": "rivet", "args": ["mcp"]}}}
```

Convergence Tracking

If retrying and hitting the same validation failures:
`rivet validate --convergence --format json`

Shows failure signatures, occurrence counts, and strategy recommendations
(normal → expanded-context → different-approach → human-review).

Commit Traceability

Required git trailers: Implements, Fixes, Verifies, Satisfies, Refs.
Exempt types: chore, style, ci, docs, build.
Skip with: `Trace: skip`
```

11. Fix the YAML parse warning

```
[WARN] skipping ./safety/stpa-sec/v031-security.yaml: YAML parse error: missing field `artifacts`
```

A broken file in the repo that should be either fixed or removed.

Priority

1. Fix YAML warning + push + release tag (unblocks everything)
2. Regenerate AGENTS.md
3. Update README feature list
4. Add "Why Rivet?" + domain presets to getting-started.md
5. Add examples/safety-case/ project
6. Expand CLAUDE.md
7. Add migrating-from-sphinx-needs.md
8. Document bridge schemas in schemas.md
9. Add assurance-driven-development.md

Non-goals

• No marketing language or comparison pages
• No rewrite of existing docs — additions only
• No new features — documentation of what already exists

[avrabe]

Shipped in PR #116: 7 new docs topics, updated CLI/YAML references, STPA-sec format fix, stpa-sec+research embedded.