feat(add): let the caller name the artifact via --id (REQ-007, #880)

[avrabe]

Closes #880.

rivet add chose the ID itself and offered no way to say what it should be. In varve — 89 distinct requirement prefixes, all descriptive of what the requirement is about — that landed a graph-wide release-packaging requirement as REQ-PIN-003 twice in one session. Title, tags, target file, and --field id= all made no difference to the derivation, so the documented workaround was to hand-edit the id: line the tool had just written — which is the thing the project's own guidance forbids.

What this changes

--id <ID> on rivet add. The caller asserts the ID, the tool shape-validates it up front and, via the existing validate_add, rejects a duplicate before any file is written. Without --id, the derived-next-in-series behavior is unchanged (regression-guarded by test 4 below).

Shape

PREFIX-NNN — the convention every existing artifact already follows (REQ-DRV-COMPONENT-001, VER-OS-WCET-001, FIND-DMA-SHM-CANONICAL-001):

• uppercase alphanumeric segments, dash-separated
• ends with a numeric suffix after the last dash
• non-empty prefix carrying at least one uppercase letter
• no leading/trailing dashes, no --

Acceptance criteria — #880

Only the ask labelled (1) is addressed here — avrabe stated "That alone closes it."

• --id on rivet add, validated for uniqueness and shape. — Uniqueness reuses validate_add's existing check (same message a duplicate hand-edit would produce); shape validated by a new validate_explicit_id in rivet-cli/src/main.rs.
• --prefix on next-id and add — deliberately out of scope; would fit a follow-up.
• ID-scheme setting in rivet.yaml — out of scope for the smallest-fix path avrabe asked for.

Ask (2) and (3) from #887 (add rejects --field id=; next-id preserves hyphens) are separate PRs — one PR per issue.

Tests (rivet-cli/tests/cli_commands.rs)

Four new integration tests, one per face of the contract:

• add_id_flag_honors_explicit_id — --id REQ-DRV-GRAPH-001 on a repo whose existing series is REQ-PIN-* writes the caller's ID, not a derived one.
• add_id_flag_rejects_duplicate_id — colliding ID fails with the existing "already exists" message; no second block is appended.
• add_id_flag_rejects_malformed_ids — nine ill-shaped inputs are refused with actionable messages (invalid character, leading/trailing dash, double dash, missing numeric suffix, digits-only prefix).
• add_without_id_still_derives_next_in_series — default path still returns the next ID in the existing series (REQ-PIN-002); regression guard so the shape check does not fire on derived IDs.

Gates

• cargo fmt --all -- --check ✅
• cargo clippy --all-targets -- -D warnings ✅ (no error: lines; only the pre-existing MSRV meta-warning)
• cargo test --workspace ✅ (all binaries green, including the four new tests)
• rivet validate ✅ (Result: PASS, unchanged from base — 775 pre-existing warnings)

🤖 Generated with Claude Code

https://claude.ai/code/session_018ozkqbJopvcKoycPR8zHEW

---

Generated by Claude Code

[github-actions]

📐 Rivet artifact delta

No artifact changes in this PR. Code-only changes (renderer, CLI wiring, tests) don't touch the artifact graph.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!