rivet modify: positional 'status' arg has no --set-status hint; status accepts any free-form value

[avrabe]

Two small rivet modify UX issues found while doing a status audit

rivet 0.13.3 (b55a9c6f release/v0.14.0 2026-05-30), installed at
~/.cargo/bin/rivet. Found while promoting shipped features to a
"done" status across a project's artifacts.

1. The positional form rivet modify <ID> status <value> fails with a bare clap error and no hint toward --set-status

The natural first guess for setting a field is rivet modify <ID> <field> <value>. That produces only a generic argument error with no pointer to
the actual flag:

$ rivet modify FEAT-001 status accepted ; echo "exit=$?"
error: unexpected argument 'status' found

Usage: rivet modify [OPTIONS] <ID>

For more information, try '--help'.
exit=2

The correct invocation is rivet modify FEAT-001 --set-status accepted
(exit 0, "modified FEAT-001"). It would save a round-trip if the error
hinted at it, e.g. "unexpected argument 'status' — did you mean
--set-status status?" (clap supports did you mean suggestions). This
is the kind of paper-cut that especially trips up scripted / agent-driven
edits, where the natural-language word lands as a positional arg.

2. status is a free-form string — rivet modify --set-status <anything> is accepted and rivet validate passes

There appears to be no controlled vocabulary for status: an arbitrary
value is written to disk and validate accepts it.

$ rivet modify FEAT-001 --set-status zzqq ; echo "exit=$?"
modified FEAT-001
exit=0
$ grep -A2 'id: FEAT-001' artifacts/requirements.yaml | grep status
    status: zzqq
$ rivet validate ; echo "exit=$?"
Result: PASS (0 warnings)
exit=0

If status is intentionally free-form, this is fine — but then it would
help to say so somewhere discoverable (e.g. in rivet schema show <type>, which currently lists fields and link-fields but does not
indicate that status is unconstrained). If instead status is meant to be
a per-type lifecycle enum (the schema examples consistently use
draft / proposed / approved / accepted), then modify --set-status
and validate letting a typo like zzqq through is a gap — a typo in a
lifecycle field silently degrades traceability/reporting without any
diagnostic.

Either way, two concrete asks:

• Discoverability: make a field's allowed values (or "free-form")
  visible before an error — e.g. surface it in rivet schema show <type> and/or rivet modify --help.
• If status is/should be controlled: validate --set-status against
  the vocabulary at write time (with a did you mean suggestion), so the
  invalid value never reaches disk.

What I was doing / what helped

Auditing artifacts to mark shipped features. I reached for the word
implemented; --set-status implemented was accepted and rivet validate
passed, so implemented works fine — but the experiment above (zzqq)
showed that's because status is unconstrained, not because implemented
is a recognised value. rivet schema show feature was the most useful
command for understanding the type, though it didn't clarify the status
field's domain. Reported from a downstream project; happy to test a fix.

[avrabe]

Confirmed, tracked as REQ-136 (modify ergonomics): a positional where a --set-* flag is expected should produce an error that names the correct flag (--set-status), not a bare clap error. Bundled with #360.

[avrabe]

Addressed by #365 (merged): rivet modify --help now shows the --set-* flag examples + a note that positionals (modify <ID> status approved) are not valid. The bare clap error still directs to --help, which now teaches the pattern. Closing; reopen if the inline-error-naming is worth more.