Skip to content

AGENTS.md

Latest commit

 

History

History
122 lines (102 loc) · 7.51 KB

AGENTS.md

File metadata and controls

122 lines (102 loc) · 7.51 KB

AGENTS.md — Rivet Project Instructions

This file was generated by rivet init --agents. Re-run the command any time artifacts change to keep this file current.

Project Overview

This project uses Rivet for SDLC artifact traceability.

  • Config: rivet.yaml
  • Schemas: common, stpa, aspice, dev
  • Artifacts: 284 across 15 types
  • Validation: rivet validate (current status: 91 errors)

Available Commands

Command Purpose Example
rivet validate Check link integrity, coverage, required fields rivet validate --format json
rivet list List artifacts with filters rivet list --type requirement --format json
rivet stats Show artifact counts by type rivet stats --format json
rivet add Create a new artifact rivet add -t requirement --title "..." --link "satisfies:SC-1"
rivet link Add a link between artifacts rivet link SOURCE -t satisfies --target TARGET
rivet serve Start the dashboard rivet serve --port 3000
rivet export Generate HTML reports rivet export --format html --output ./dist
rivet impact Show change impact rivet impact --since HEAD~1
rivet coverage Show traceability coverage rivet coverage --format json
rivet diff Compare artifact versions rivet diff --base path/old --head path/new

Artifact Types

Type Count Description
controlled-process 3 A process being controlled — the physical or data transformation acted upon by controllers.
controller 6 A system component (human or automated) responsible for issuing control actions. Each controller has a process model — its internal beliefs about the state of the controlled process.
controller-constraint 18 A constraint on a controller's behavior derived by inverting a UCA. Specifies what the controller must or must not do.
hazard 19 A system state or set of conditions that, together with worst-case environmental conditions, will lead to a loss.
loss 10 An undesired or unplanned event involving something of value to stakeholders. Losses define what the analysis aims to prevent.
loss-scenario 20 A causal pathway describing how a UCA could occur or how the control action could be improperly executed, leading to a hazard.
stakeholder-req 4 Stakeholder requirement (SYS.1)
sub-hazard 3 A refinement of a hazard into a more specific unsafe condition.
sw-arch-component 13 Software architectural element (SWE.2)
sw-req 26 Software requirement (SWE.1)
sw-verification 13 Software verification measure against SW requirements (SWE.6 — Software Verification)
sys-verification 39 System verification measure against system requirements (SYS.5 — System Verification)
system-arch-component 6 System architectural element (SYS.3)
system-constraint 20 A condition or behavior that must be satisfied to prevent a hazard. Each constraint is the inversion of a hazard.
system-req 84 System requirement derived from stakeholder needs (SYS.2)
control-action 0 An action issued by a controller to a controlled process or another controller.
design-decision 0 An architectural or design decision with rationale
feature 0 A user-visible capability or feature
requirement 0 A functional or non-functional requirement
sw-detail-design 0 Software detailed design or unit specification (SWE.3)
sw-integration-verification 0 Software component and integration verification measure (SWE.5 — Software Component Verification and Integration Verification)
sys-integration-verification 0 System integration and integration verification measure (SYS.4 — System Integration and Integration Verification)
uca 0 An Unsafe Control Action — a control action that, in a particular context and worst-case environment, leads to a hazard. Four types (provably complete): 1. Not providing the control action leads to a hazard 2. Providing the control action leads to a hazard 3. Providing too early, too late, or in the wrong order 4. Control action stopped too soon or applied too long
unit-verification 0 Unit verification measure (SWE.4 — Software Unit Verification)
verification-execution 0 A verification execution run against a specific version
verification-verdict 0 Pass/fail verdict for a single verification measure in an execution run

Working with Artifacts

File Structure

  • Artifacts are stored as YAML files in: artifacts, safety/stpa
  • Schema definitions: schemas/ directory
  • Documents: docs

Creating Artifacts

rivet add -t requirement --title "New requirement" --status draft --link "satisfies:SC-1"

Validating Changes

Always run rivet validate after modifying artifact YAML files. Use rivet validate --format json for machine-readable output.

Link Types

Link Type Description Inverse
acts-on Control action acts on a process or controller acted-on-by
allocated-to Source is allocated to the target (e.g. requirement to architecture component) allocated-from
caused-by-uca Loss scenario is caused by an unsafe control action causes-scenario
constrained-by Source is constrained by the target constrains
constrains-controller Constraint applies to a specific controller controller-constrained-by
constraint-satisfies Requirement satisfies (implements) a system constraint satisfied-by-constraint
depends-on Source depends on target being completed first depended-on-by
derives-from Source is derived from the target derived-into
implements Source implements the target implemented-by
inverts-uca Controller constraint inverts (is derived from) an UCA inverted-by
issued-by Control action or UCA is issued by a controller issues
leads-to-hazard UCA or loss scenario leads to a hazard hazard-caused-by
leads-to-loss Hazard leads to a specific loss loss-caused-by
mitigates Source mitigates or prevents the target mitigated-by
part-of-execution Verification verdict belongs to a verification execution run contains-verdict
prevents Constraint prevents a hazard prevented-by
refines Source is a refinement or decomposition of the target refined-by
result-of Verification verdict is the result of executing a verification measure has-result
satisfies Source satisfies or fulfils the target satisfied-by
traces-to General traceability link between any two artifacts traced-from
verifies Source verifies or validates the target verified-by

Conventions

  • Artifact IDs follow the pattern: PREFIX-NNN (e.g., REQ-001, FEAT-042)
  • Use rivet add to create artifacts (auto-generates next ID)
  • Always include traceability links when creating artifacts
  • Run rivet validate before committing

Commit Traceability

This project enforces commit-to-artifact traceability.

Required git trailers:

  • Fixes -> maps to link type fixes
  • Implements -> maps to link type satisfies
  • Trace -> maps to link type traces-to
  • Verifies -> maps to link type verifies

Exempt artifact types (no trailer required): chore, style, ci, docs, build

To skip traceability for a commit, add: Trace: skip