rivet add: no way to choose an artifact ID, and the derived one can be actively misleading

[avrabe]

[fathom (gale) — hit while splitting a conflated requirement into new series]

Three related papercuts in add / next-id. Toolchain identity: varve layer
2026.09.0, rivet 0.35.0 (4ff980e0 HEAD 2026-08-05).

Context: gale needed two new artifact series — REQ-DRV-GRAPH-* and REQ-DRV-SILICON-*
— split out of an existing requirement whose clauses had drifted apart.

1. add offers no way to set the ID, and the derived one ignores every input

rivet add has no --id. The ID it derives was identical across every input I varied:

--tags "graph"                    -> REQ-DRV-GPIO-002
--tags "graphenv"                 -> REQ-DRV-GPIO-002
--tags "gust,graph"               -> REQ-DRV-GPIO-002
--file artifacts/gust_driver_model.yaml -> REQ-DRV-GPIO-002
--field id=REQ-DRV-GRAPH-001      -> REQ-DRV-GPIO-002

Title, tags, target file and an explicit --field id= all make no difference: it
returns the next number in some pre-existing series. For a graph-wide env-import
requirement, landing as REQ-DRV-**GPIO**-002 is not merely arbitrary — it is wrong in
a way a later reader would have to un-learn. In a traceability system the ID is the
handle everything else cites, so it is one of the few fields worth being able to choose.

2. next-id <PREFIX> strips the hyphens

rivet next-id sw-req          -> REQ-DRV-GPIO-002
rivet next-id REQ             -> REQ-001
rivet next-id REQ-DRV         -> REQDRV-001
rivet next-id REQ-DRV-GRAPH   -> REQDRVGRAPH-001

REQDRVGRAPH-001 does not match the convention every existing ID in the project uses
(REQ-DRV-COMPONENT-001, VER-OS-WCET-001, FIND-DMA-SHM-CANONICAL-001). So even the
command whose job is "tell me the next ID" cannot name a new hyphenated series.

3. add --field release=v0.7.1 is silently ignored

rivet add --type sw-req … --field release=v0.7.1
rivet get <new-id>     # no Release line
rivet modify <id> --set-release v0.7.1    # works

release is a first-class field, and modify has --set-release, so add accepting
--field release= and dropping it is the bad case: it looks like it worked. modify's
help already warns about this shape for description ("a top-level base field — use
this rather than --set-field description=..."), which suggests the general problem is
known; add just has no equivalent guard. A rejection would have been fine. Silence
was not — I only noticed because the artifacts were missing from
rivet list --release.

What I did meanwhile

Added via rivet add, then corrected the two id: lines directly, then re-attached
links with rivet link and confirmed with rivet validate (PASS) and rivet get.
Recording that plainly because "never hand-edit the YAML" is the right rule and I had to
step outside it — which is exactly the kind of workaround that should show up as an
issue rather than quietly become local practice.

Suggestions, in the order I would want them

1. --id <ID> on add, validated for uniqueness and against the schema's ID pattern.
   Smallest change, removes the need for the workaround entirely.
2. add errors on a --field naming a first-class field, pointing at the right flag.
3. next-id preserves the prefix it was given.

Happy to send a PR for (1) or (2) if the shape is agreed — (2) in particular looks like
it belongs next to the existing description guard.

[avrabe]

Triage note (scheduled routine, first pass on this issue — filed 2026-09-04 11:52Z, no prior comments).

The body pins three related papercuts against rivet 0.35.0 on the fathom/gale split, with the reproduction table for point (1) doing the load-bearing work: five different inputs (--tags, --file, --field id=) all produce the same REQ-DRV-GPIO-002, so the derived ID is provably not a function of anything the caller can vary. Point (2)'s hyphen-stripping table is equally tight (REQ-DRV-GRAPH -> REQDRVGRAPH-001), and point (3) is the sharpest case — --field release=v0.7.1 is silently dropped even though modify --set-release works and modify already warns about the same shape for description, so the general problem is known and add just has no equivalent guard.

Overlap with #880 (2026-09-02, same author): #880's ask (1) is byte-identical to this issue's ask (1) — --id <ID> on rivet add, validated for uniqueness and shape — and #880's triage already carries a full AC sketch for that slice ("Acceptance Criteria — slice 1 (--id on rivet add, no config changes)", 2026-09-02 12:46Z). To keep the "one PR per issue, keep PRs focused" convention honest, this comment sketches AC only for the two asks that are not covered by #880 — the next-id hyphen strip (ask 2 here) and the silent-drop on add --field release= (ask 3 here). #880 owns the --id slice.

Also worth naming: ask 3 here reproduces the shape jess's 2026-09-03 feedback comment on #879 hit — --field release=v0.7.0 landed under fields: rather than the top-level release: key, plus the sharper "INFO not even WARN" degenerate case (INFO: [TEST-PIX-032] field 'release' is not defined in schema for type 'test-spec'). Same defect surface, two independent reporters within 24 hours; the AC below scopes the fix at the add input surface rather than trying to unify severity across every reader (that's #885's territory).

Sketch matching the kill-criterion shape used across adjacent triage threads (#880 / #885 / #862 / #871 / #838 / #807) — drop in / revise; two independent slices that can land as one PR (they share the add argument-validation surface) or two:

## Acceptance Criteria — slice 2 (`add` rejects `--field` naming a first-class field, no silent drop)

- [ ] `rivet add --type <T> ... --field release=v0.7.1` exits non-zero
      with a legible "field 'release' is a top-level artifact key on
      type '<T>' — use `--set-release v0.7.1` instead (or pass it as
      the top-level release: on the YAML)". Same guard shape `modify`
      already carries for `description` (per the body's citation of
      the existing warning text). No silent drop, no INFO tail.
- [ ] The check enumerates first-class keys from the artifact type's
      schema (release, status, title, description, tags, verifies,
      implements, ...) so a schema addition doesn't need a hand-written
      list update — same detection seam the schema-driven validators
      already use. Regression fixture: `add --type sw-req
      --field release=v1 --field description="..." --field status=verified`
      exits non-zero naming all three keys, not just the first.
- [ ] `add --field <k>=<v>` where `<k>` is a legitimate schema field
      (i.e. defined under `fields:` for that type) continues to work
      unchanged — this slice is a "top-level key masquerading as a
      custom field" rejection, not a widening of `--field`'s legal set.
- [ ] Cross-check parity with jess's INFO-tail case (#879's 2026-09-03
      comment): the same rejection shape covers `--field release=v0.7.0`
      on `test-spec` where `release` is not defined as a schema field
      either — the check fires on "top-level key" first, "not-in-schema"
      second, so a caller learns the closer fix rather than the more
      general one.
- [ ] Regression fixture reproducing the body's shape: an artifact
      created with `add --type sw-req --title "..." --description "..."
      --field release=v0.7.1` under pre-fix behaviour has no Release
      line under `rivet get` (the body's specific measurement); under
      the fix, `add` exits non-zero and no artifact is written.
- [ ] `cargo test -p rivet-cli --tests` green; `cargo fmt` /
      `cargo clippy --all-targets -- -D warnings` clean;
      `rivet validate` PASS on the rivet repo.
- [ ] Commit trailers: `Implements: REQ-007` (CLI commands) or a fresh
      REQ for "explicit rejection of top-level-key-as-field on
      rivet add" if the STPA lineage is worth pinning independently.
      Plus `Refs: #887, #879, #880`.

## Acceptance Criteria — slice 3 (`next-id` preserves the hyphenated prefix)

- [ ] `rivet next-id REQ-DRV-GRAPH` returns `REQ-DRV-GRAPH-<N>`, not
      `REQDRVGRAPH-<N>`. The prefix passed to `next-id` is preserved
      verbatim (byte-identical), and only the numeric suffix is
      appended/incremented. Same for `REQ-DRV`, `VER-OS-WCET`, and
      any other hyphenated prefix — the number of hyphens in the
      prefix is not the concern, keeping them where the caller put
      them is.
- [ ] `next-id` validates the prefix shape against the schema's ID
      regex (same regex the parser enforces on-read) and rejects a
      prefix that would produce an invalid ID with a legible message.
      Absent this, a caller could pass a prefix that produces
      `<prefix>-001` where the resulting ID would fail validation on
      the next `rivet validate` pass — noisier fail-forward than
      failing at `next-id` time.
- [ ] Case handling stays as it is today (`sw-req -> REQ-DRV-GPIO-002`
      per the body's first row is a type→prefix map lookup, not a
      case fold): the "give me a fresh number for prefix P" contract
      is honored when P is a known prefix; the "give me a fresh
      number under type T" contract is honored when the input matches
      a known type. This slice does not merge the two contracts —
      it just stops mangling the prefix when the first contract is
      invoked.
- [ ] Regression fixture reproducing the body's four `next-id` rows:
      `sw-req` (type-lookup path) still returns the existing
      `REQ-DRV-GPIO-<N>`; `REQ` returns `REQ-<N>`; `REQ-DRV` returns
      `REQ-DRV-<N>`; `REQ-DRV-GRAPH` returns `REQ-DRV-GRAPH-<N>`.
      Under pre-fix behaviour, the last two collapse hyphens; under
      the fix, they preserve them.
- [ ] `add` and `next-id` agree on the shape: if `--id` on `add`
      lands as #880's slice 1 (see cross-ref), `add --id <ID>` and
      `next-id <PREFIX>` produce IDs from the same regex — one
      place, one shape, no drift.
- [ ] `cargo test -p rivet-cli --tests` green; `cargo fmt` /
      `cargo clippy --all-targets -- -D warnings` clean;
      `rivet validate` PASS on the rivet repo.
- [ ] Commit trailers: `Implements: REQ-007` + `Refs: #887, #880`.

## Explicitly out of scope (file separately if wanted)

- [ ] Ask (1) — `--id <ID>` on `rivet add`. #880's slice 1 already
      owns this and carries a full AC sketch (2026-09-02 12:46Z).
      Deliberately not duplicated here so #880 stays the single
      home for that slice.
- [ ] Unifying the ID picker's type→prefix map with a project-local
      configuration in `rivet.yaml` (`id-scheme:` or similar).
      #880's ask (3) territory; sibling issue when someone wants it.
- [ ] `next-id --prefix` where the tool picks the number but the
      caller picks the vocabulary (#880's ask (2) territory).
- [ ] Any change to `rivet modify` to allow ID rewriting. Mutable-id
      path is a much bigger call (graph-wide reference rewrite);
      deliberately out of every current slice.
- [ ] Dry-run support on `add` (jess flagged this on #879 —
      "`rivet add --file` allocates an ID even on a smoke test").
      Real ask, sibling issue; would compose cleanly with slice 2
      here (validate the arguments without writing) but the seam
      is `add`-wide, not just the reject-on-first-class-key seam.

Adjacent state worth flagging:

• add assigns an ID that ignores the repo's own prefix convention, and there is no --id #880 (2026-09-02) — same author, same day-adjacent surface,
  same ask (1). AC sketch on add assigns an ID that ignores the repo's own prefix convention, and there is no --id #880 owns the --id slice; this
  issue's slice 1 in the body should land under add assigns an ID that ignores the repo's own prefix convention, and there is no --id #880's branch,
  not a parallel one, to keep the "one PR per issue" convention
  honest and avoid two branches racing on the same
  rivet-cli/src/add.rs surface.
• Feedback wanted: needs and wishes for rivet #879 (2026-09-02) — jess's 2026-09-03 feedback comment
  independently hit slice 2 (ask 3 here) with a sharper INFO-tail
  degenerate case. Slice 2 above is scoped to close both reports
  with one fix; Feedback wanted: needs and wishes for rivet #879 stays open as a discussion, and can be
  closed as "addressed by the branch that lands rivet add: no way to choose an artifact ID, and the derived one can be actively misleading #887 slice 2"
  once that lands.
• The same allowed-values constraint is a hard ERROR in 'rivet add' and a WARNING in 'rivet validate' — a repo's artifacts can sit in a state its own tool refuses to create, with CI green (60% of jess's AFDs do) #885 (2026-09-03) — the general "validate cannot fail on
  what it calls a warning" ask. Ortogonal to this issue: The same allowed-values constraint is a hard ERROR in 'rivet add' and a WARNING in 'rivet validate' — a repo's artifacts can sit in a state its own tool refuses to create, with CI green (60% of jess's AFDs do) #885
  fixes the reader surface (make validate a gate); this issue
  fixes the writer surface (stop add from silently dropping the
  value in the first place). Both fixes are strictly better
  together — the INFO tail Feedback wanted: needs and wishes for rivet #879 credits would still land somewhere
  if add learns to reject the input, but validate --strict
  would then be the second net.
• Same "silent state leads a careful reader to the wrong action"
  family the tracker keeps surfacing (serve: /api/v1/artifacts silently truncates at limit=1000 (repo has 1017) — no truncation signal in the response #832 silent truncation at
  limit=1000; ci: Test job silently falls back to cargo test, producing no JUnit XML and losing retries — three stacked silencers #833 nextest fallback silently drops JUnit XML;
  rivet verify advances on the existence of evidence, not its sufficiency #838 verify advances on marker-only evidence; friction: a dead externals path: poisons all cross-repo resolution (no git: fallback), and validate then reports '0 broken cross-refs' beside dozens of unresolved-target errors #854 dead
  externals silently reports 0 broken cross-refs; check verification-evidence is useless as a gate: blind to nested workspaces (false fail) + satisfied by an empty stub (false pass) #807
  check verification-evidence blind to nested workspaces /
  satisfies-only rules). Slice 2 here fits the same shape at the
  add input surface.

Process side-rail: consulted https://pulseengine.eu/blog/ at the start of this run — 200 OK. The blog's current posts are technical (WebAssembly verification, formal methods, floating-point precision, OS kernel work, safety-critical systems, AI-assisted analysis) — none of them speak to per-issue AC shape, branching, PR flow, or contributor-workflow convention. So the working reference remains AGENTS.md + CLAUDE.md in-tree (trailers, Trace: skip for ci/docs, Implements: + Refs:) plus the kill-criterion convention used across adjacent triage threads. If a workflow post gets published later, this AC will need a re-read before the branch lands.

Not implemented this run — no PR opened; the AC block on the body is the gating input. Once you drop it in (or edit the sketch — the two slices are independent and can be picked one at a time), the next routine pass can open a focused branch scoped to slice 2 and/or slice 3, with slice 1 riding on #880's branch.

https://claude.ai/code/session_01XStgnUCF5Cx8ZHb16bTjkT

---

Generated by Claude Code