CLI mutation commands (add, modify, remove, link, unlink)

[avrabe]

Context

Rivet CLI is currently read-only — it can validate, query, and display artifacts but cannot create or modify them. All artifact management requires manually editing YAML files, which risks:

• Duplicate IDs
• Wrong link type names
• Invalid status values
• Broken target references
• YAML formatting errors

This is especially problematic when AI agents edit artifacts (as demonstrated by the invalid issues #11-#16 that were auto-generated with wrong content).

Proposed commands

rivet add

rivet add --type requirement --title "Conditional validation" \
  --status draft --tags validation,schema \
  --field priority=should --field category=functional
# Auto-generates REQ-031 (next available ID), validates against schema, appends to YAML

rivet modify

rivet modify REQ-023 --set-status approved --add-tag safety
# Validates new values against schema before writing

rivet remove

rivet remove FEAT-042
# Checks for incoming links, refuses unless --force, reports broken refs

rivet link / unlink

rivet link REQ-023 --type satisfies --target SC-12
# Validates both IDs exist, link type valid for source→target types, cardinality ok

rivet unlink REQ-023 --type satisfies --target SC-12

rivet next-id

rivet next-id --type requirement  # → REQ-032
rivet next-id --prefix FEAT       # → FEAT-057

Key design principle

All mutations are schema-validated at write time. The CLI rejects invalid mutations with diagnostics before touching any file. This makes rivet add/modify/link the safest way to manage artifacts — safer than hand-editing, safer than AI agents.

Rivet artifacts

• REQ-031, DD-028
• FEAT-052 (add), FEAT-053 (modify), FEAT-054 (remove), FEAT-055 (link/unlink), FEAT-056 (next-id)

STPA linkage

• REQ-031 satisfies SC-1 (validate cross-references before output) and SC-2 (never silently discard)

[avrabe]

Implemented in PR #27 (feat/phase3-integration)