Add document system and improve graph visualization

docs/srs.md

@@ -0,0 +1,87 @@
+---
+id: SRS-001
+type: specification
+title: System Requirements Specification
+status: draft
+glossary:
+  STPA: Systems-Theoretic Process Analysis
+  UCA: Unsafe Control Action
+  ASPICE: Automotive SPICE
+  OSLC: Open Services for Lifecycle Collaboration
+  ReqIF: Requirements Interchange Format
+  WASM: WebAssembly
+---
+
+# System Requirements Specification
+
+## 1. Purpose
+
+This document specifies the system-level requirements for **Rivet**, an SDLC
+traceability tool for safety-critical systems.  Rivet manages lifecycle
+artifacts (requirements, designs, tests, STPA analyses) as version-controlled
+YAML files and validates their traceability links against composable schemas.
+
+## 2. Scope
+
+Rivet targets Automotive SPICE, ISO 26262, and ISO/SAE 21434 workflows.  It
+replaces heavyweight ALM tools with a text-file-first, git-friendly approach.
+
+## 3. Functional Requirements
+
+### 3.1 Artifact Management
+
+[[REQ-001]] defines the core principle: artifacts live as human-readable YAML
+files under version control.
+
+[[REQ-002]] extends this to STPA artifacts — losses, hazards, unsafe control
+actions, causal factors, and loss scenarios.
+
+### 3.2 Traceability
+
+[[REQ-003]] requires full Automotive SPICE V-model traceability, from
+stakeholder requirements down to unit verification and back.
+
+[[REQ-004]] mandates a validation engine that checks link integrity,
+cardinality constraints, required fields, and traceability coverage.
+
+### 3.3 Schema System
+
+[[REQ-010]] requires schema-driven validation where artifact types, fields,
+link types, and traceability rules are defined declaratively.
+
+[[REQ-015]] aligns schemas with ASPICE 4.0 terminology (verification replaces
+test).
+
+[[REQ-016]] adds cybersecurity schema support for ISO/SAE 21434 and ASPICE
+SEC.1-4.
+
+### 3.4 Interoperability
+
+[[REQ-005]] covers ReqIF 1.2 import/export for requirements interchange with
+tools like DOORS, Polarion, and codebeamer.
+
+[[REQ-006]] specifies OSLC-based bidirectional synchronization rather than
+per-tool REST adapters.
+
+[[REQ-008]] enables WASM component adapters for custom format plugins.
+
+### 3.5 User Interface
+
+[[REQ-007]] requires both a CLI and an HTTP serve pattern for the dashboard.
+
+### 3.6 Quality
+
+[[REQ-012]] mandates comprehensive CI quality gates (fmt, clippy, test, miri,
+audit, deny, vet, coverage).
+
+[[REQ-013]] requires performance benchmarks with regression detection.
+
+[[REQ-014]] structures test artifacts to mirror the ASPICE SWE.4/5/6 levels.
+
+[[REQ-009]] ties test results to GitHub releases as evidence artifacts.
+
+[[REQ-011]] pins Rust edition 2024 with MSRV 1.85.
+
+## 4. Glossary
+
+See the glossary panel below (defined in document frontmatter).

etch/src/svg.rs

@@ -143,10 +143,13 @@ fn write_style(svg: &mut String, options: &SvgOptions) {
          \x20   .node text {{ font-family: {font}; font-size: {fs}px; \
          fill: #222; text-anchor: middle; dominant-baseline: central; }}\n\
          \x20   .node .sublabel {{ font-size: {}px; fill: #666; }}\n\
-         \x20   .edge path {{ fill: none; stroke: {ec}; stroke-width: 1.2; \
+         \x20   .edge path {{ fill: none; stroke: {ec}; stroke-width: 1.4; \
          marker-end: url(#arrowhead); }}\n\
+         \x20   .edge .label-bg {{ fill: #fff; opacity: 0.85; rx: 3; }}\n\
          \x20   .edge text {{ font-family: {font}; font-size: {}px; \
-         fill: {ec}; text-anchor: middle; }}\n\
+         fill: #555; text-anchor: middle; dominant-baseline: central; \
+         font-weight: 500; }}\n\
+         \x20   .node:hover rect {{ filter: brightness(0.92); }}\n\
          \x20 </style>\n",
         fs - 2.0,
         fs - 2.0,
@@ -175,15 +178,25 @@ fn write_edges(svg: &mut String, layout: &GraphLayout) {
 
         writeln!(svg, "        <path d=\"{path_d}\" />").unwrap();
 
-        // Edge label at midpoint.
+        // Edge label at midpoint with background pill.
         if !edge.label.is_empty() {
             let mid = edge.points.len() / 2;
             let (mx, my) = edge.points[mid];
+            let label = xml_escape(&edge.label);
+            let text_y = my - 4.0;
+            // Approximate label width: ~6.5px per char at default font size.
+            let approx_w = edge.label.len() as f64 * 6.5 + 8.0;
+            let approx_h = 14.0;
             writeln!(
                 svg,
-                "        <text x=\"{mx}\" y=\"{}\">{}</text>",
-                my - 4.0,
-                xml_escape(&edge.label),
+                "        <rect class=\"label-bg\" x=\"{}\" y=\"{}\" width=\"{approx_w}\" height=\"{approx_h}\" />",
+                mx - approx_w / 2.0,
+                text_y - approx_h / 2.0,
+            )
+            .unwrap();
+            writeln!(
+                svg,
+                "        <text x=\"{mx}\" y=\"{text_y}\">{label}</text>",
             )
             .unwrap();
         }

examples/aspice/artifacts/architecture.yaml

@@ -0,0 +1,176 @@
+artifacts:
+  # ── System Architecture (SYS.3) ──────────────────────────────────────
+
+  - id: SYSARCH-1
+    type: system-arch-component
+    title: Hydraulic Control Unit
+    status: approved
+    description: >
+      The HCU receives brake pressure commands from the ECU and drives
+      proportional solenoid valves to modulate brake line pressure
+      independently on each axle.  Contains the valve block, pump motor,
+      and pressure sensors.
+    tags: [braking, hcu, hardware]
+    fields:
+      component-type: mixed
+      interfaces:
+        provided:
+          - name: pressure-command
+            protocol: CAN FD
+            description: Accepts 12-bit pressure demand per axle at 100 Hz
+        required:
+          - name: power-supply
+            description: 12 V nominal, 60 A peak during pump operation
+    links:
+      - type: allocated-from
+        target: SYSREQ-1
+      - type: allocated-from
+        target: SYSREQ-2
+
+  - id: SYSARCH-2
+    type: system-arch-component
+    title: ABS Electronic Control Unit
+    status: approved
+    description: >
+      The ABS ECU hosts the slip control software, reads wheel speed sensors
+      via the sensor interface, and commands pressure modulation through the
+      HCU.  Includes the microcontroller, CAN FD transceiver, and power
+      management.
+    tags: [braking, abs, ecu]
+    fields:
+      component-type: mixed
+      interfaces:
+        provided:
+          - name: abs-status
+            protocol: CAN FD
+            description: ABS active flag, wheel speeds, slip ratios at 100 Hz
+        required:
+          - name: wheel-speed-input
+            protocol: analog
+            description: 4x wheel speed sensor signals (inductive, 48 teeth)
+          - name: hcu-command
+            protocol: CAN FD
+            description: Pressure build/hold/release commands to HCU
+    links:
+      - type: allocated-from
+        target: SYSREQ-3
+
+  # ── Software Architecture (SWE.2) ────────────────────────────────────
+
+  - id: SWARCH-1
+    type: sw-arch-component
+    title: Brake Pressure Manager
+    status: approved
+    description: >
+      Software component responsible for computing brake pressure demands
+      for each axle.  Reads pedal position and axle load estimates, applies
+      the load-dependent ratio, and outputs DAC commands to the HCU valve
+      driver.  Runs in the 10 ms periodic task.
+    tags: [braking, ebd, software]
+    fields:
+      interfaces:
+        provided:
+          - name: pressure_demand_output
+            type: function
+            description: "fn pressure_demand(pedal: u16, speed: u16, ratio: f32) -> [u16; 2]"
+        required:
+          - name: axle_load_input
+            type: function
+            description: "fn get_axle_loads() -> (f32, f32)"
+      concurrency: single-threaded (10 ms cyclic task)
+      resource-budgets:
+        stack: 2 KiB
+        wcet: 200 us
+    links:
+      - type: allocated-from
+        target: SWREQ-1
+      - type: allocated-from
+        target: SWREQ-2
+
+  - id: SWARCH-2
+    type: sw-arch-component
+    title: ABS Slip Controller
+    status: approved
+    description: >
+      Software component implementing the wheel slip regulation algorithm.
+      Reads wheel speed sensor inputs at 500 Hz via the sensor abstraction
+      layer, computes individual wheel slip ratios, determines the pressure
+      modulation phase (build/hold/release), and issues commands to the HCU
+      driver.  Runs in the 2 ms high-priority task.
+    tags: [braking, abs, software]
+    fields:
+      interfaces:
+        provided:
+          - name: slip_status
+            type: struct
+            description: "struct SlipStatus { slip_ratio: [f32; 4], phase: [Phase; 4], abs_active: bool }"
+        required:
+          - name: wheel_speed_input
+            type: function
+            description: "fn read_wheel_speeds() -> [u16; 4]"
+          - name: hcu_command
+            type: function
+            description: "fn set_pressure_phase(wheel: u8, phase: Phase)"
+      concurrency: single-threaded (2 ms cyclic task)
+      resource-budgets:
+        stack: 4 KiB
+        wcet: 400 us
+    links:
+      - type: allocated-from
+        target: SWREQ-3
+
+  # ── Software Detailed Design / Unit Construction (SWE.3) ─────────────
+
+  - id: SWDD-1
+    type: sw-detail-design
+    title: Pressure demand calculation function
+    status: approved
+    description: >
+      Implements the brake pressure demand calculation.  Reads the 12-bit
+      ADC pedal position value, multiplies by the load-dependent front/rear
+      ratio from the axle load estimator, clamps the result to the
+      [0, 4095] DAC range, and writes to the HCU valve driver output buffer.
+      Includes a rate limiter (max 500 LSB/cycle) to prevent pressure
+      spikes.
+    tags: [braking, ebd, implementation]
+    fields:
+      unit: src/braking/pressure_demand.rs
+      function: calculate_pressure_demand
+      algorithm: >
+        1. Read pedal ADC (12-bit, 0-4095).
+        2. Read axle load ratio (front_ratio, rear_ratio) from estimator.
+        3. front_demand = clamp(pedal * front_ratio, 0, 4095).
+        4. rear_demand = clamp(pedal * rear_ratio, 0, 4095).
+        5. Apply rate limiter: abs(demand - prev_demand) <= 500.
+        6. Write to HCU output buffer.
+    links:
+      - type: refines
+        target: SWARCH-1
+
+  - id: SWDD-2
+    type: sw-detail-design
+    title: Wheel slip ratio computation and phase selector
+    status: approved
+    description: >
+      Computes individual wheel slip ratios from raw wheel speed sensor
+      ticks and vehicle reference speed.  Implements the ABS phase state
+      machine: NORMAL -> BUILD -> HOLD -> RELEASE -> NORMAL based on slip
+      threshold crossings with hysteresis.  Transition thresholds are
+      calibratable parameters stored in NVM.
+    tags: [braking, abs, implementation]
+    fields:
+      unit: src/braking/slip_control.rs
+      function: compute_slip_and_select_phase
+      algorithm: >
+        1. Convert wheel speed ticks to m/s using calibration factor.
+        2. Estimate vehicle reference speed as max(wheel_speeds).
+        3. slip[i] = (v_ref - v_wheel[i]) / v_ref (guard div-by-zero).
+        4. Phase state machine per wheel:
+           - NORMAL: if slip > threshold_high -> BUILD
+           - BUILD:  if slip > threshold_release -> HOLD
+           - HOLD:   if slip < threshold_low -> RELEASE
+           - RELEASE: if slip < threshold_normal -> NORMAL
+        5. Output phase commands to HCU driver.
+    links:
+      - type: refines
+        target: SWARCH-2