0.16.0 canonical status enum is breaking: no migration, drops documented 'accepted', and doesn't fit ai-found-defect

[avrabe]

Summary

Adopting rivet 0.16.0 in a downstream project (jess, the PulseEngine hardware-integration repo) flips a store that is PASS on 0.15.0 to FAIL with 21 errors on 0.16.0 — all from the new canonical status enum (feat(schema): declare canonical status lifecycle in common.yaml, REQ-162 / #352 / PR #419).

The enum itself is a genuine improvement (#352 was a real gap — typo'd statuses used to pass silently). This issue is about three friction points in rolling it out, surfaced by actually upgrading a real store.

Reproduction

Same artifact store, two binaries:

# rivet 0.15.0 (930e531e)
$ rivet validate
Result: PASS (4 warnings)

# rivet 0.16.0 (23b24958), no artifact changes
$ rivet validate
Result: FAIL (21 errors, 4 warnings, 0 broken cross-refs)

All 21 errors are the same diagnostic:

ERROR: [<id>] status '<x>' is not an allowed value,
  allowed: ["draft","proposed","approved","implemented","verified","released","deprecated","rejected"]

Offending values across the 21 artifacts:

status	count	artifact types
accepted	12	design-decision, external-anchor, requirement (meta)
open	7	ai-found-defect
resolved	2	ai-found-defect

The three friction points

1. Breaking change with no migration path

A store that validated on the prior release now has 21 hard errors on a minor bump, and the only remedy offered is hand-editing each artifact. Consider a rivet migrate status-remap (or validate --fix for status) with a documented default mapping, so existing stores have a mechanical upgrade path rather than 21 manual edits.

2. accepted was the documented terminal state

rivet's own release/lifecycle vocabulary (and the agent-facing guidance) describe the chain as draft → proposed → approved → implemented → verified → accepted. The new enum drops accepted entirely in favor of released / deprecated / rejected. Downstream artifacts that followed the documented lifecycle to its documented end state are now invalid. Either keep accepted, or publish the rename (accepted → ?) so the docs/skills and the enum agree.

3. One global document-lifecycle enum doesn't fit ai-found-defect

The 8-value enum is a document/requirement lifecycle. A defect doesn't have a draft → … → released life — its natural vocabulary is open / triaged / resolved / wontfix / duplicate. Forcing ai-found-defect onto the document enum means a live unresolved defect has to be labeled proposed/draft and a fixed one verified/released, which loses the triage semantics. Consider per-schema status allowed-values (a defect lifecycle distinct from the document lifecycle), or a dedicated triage-status field for findings.

Suggested fix (smallest first)

• Document the canonical mapping for the removed values (accepted, open, resolved, …) and ship a one-shot remap (rivet migrate --status or validate --fix).
• Decide accepted's fate explicitly and reconcile docs/agent-guidance with the enum.
• Allow schema-type-specific status enums so ai-found-defect can keep an open/triaged/resolved lifecycle.

Happy to test any of these against the jess store immediately — it's a compact, public reproduction (mixed design-decision / external-anchor / ai-found-defect artifacts) at https://github.com/pulseengine/jess. Thanks for the canonical-status work; this is purely about making the transition non-breaking for stores already in the wild.

Filed from the jess release-watch dogfooding loop (tracked as AFD-012).

---

Acceptance Criteria — first slice (slice 2: re-add accepted to the canonical enum)

Picking slice 2 per the triage recommendation: it clears the largest chunk (12 of the 21 errors), hits documented usage (accepted was the published terminal state), and is a ~one-line schema change — highest value per line of diff.

• schemas/common.yaml canonical status enum re-includes accepted as a permitted terminal value alongside verified/released/deprecated/rejected, with a one-line schema comment naming accepted as the documented terminal state for design-decision / external-anchor / requirement-meta artifacts (the 12-error chunk).
• Regression fixture: a project store with a design-decision whose status: accepted validates cleanly (0 errors) on cargo run -p rivet-cli -- validate.
• rivet schema info common (and/or rivet schema show common) prints accepted in the allowed-values list so the diagnostic and the introspection surface agree.
• rivet validate PASS on the rivet repo itself; cargo test -p rivet-core -p rivet-cli green; cargo fmt --check / clippy --all-targets -- -D warnings clean.
• Commit trailer: Fixes: REQ-162 + Refs: #352, #419, #522.
• Out of scope (file separately): slice 1 (rivet migrate status-remap / validate --fix — distinct command + default-mapping policy: open → ?, resolved → ?); slice 3 (ai-found-defect's open/resolved — dedicated status enum vs. a lifecycle: discriminator on common); the rivet 0.16.0 upgrade docs page.

Rationale for sequencing: slice 2 immediately un-breaks every store that followed the documented lifecycle (the jess store's 12 accepted errors), buying time to design slices 1 and 3 properly rather than under a breaking-change clock. jess stays on 0.15.0 until at least slice 2 ships.

[avrabe]

Triage pass (issue-triage agent run 2026-06-10).

Premise confirmed and well-evidenced: a 0.15.0→0.16.0 minor bump flipping a real downstream store from PASS (4w) to FAIL (21 errors) purely from the new canonical status enum is a breaking-change-by-validation, and your three friction points (no migration path, dropped accepted, no fit for ai-found-defect) are independently actionable with very different blast radii — (1) is new tooling (rivet migrate/validate --fix) with default-mapping policy; (2) is a schema decision (re-add accepted to the enum vs. document the canonical replacement); (3) is a schema-level question about whether ai-found-defect gets its own status enum or a lifecycle: discriminator added to common. Per "one PR per issue, keep PRs focused" the first slice needs picking.

Could you lift the chosen slice into an explicit ## Acceptance Criteria block in the body? Sketch for what looks like the highest-value-per-line-of-diff start (slice 2 — re-add accepted, since the 12-error chunk is the one that hits documented usage and is a one-line schema change); replace if you'd rather start elsewhere:

## Acceptance Criteria — first slice (slice 2: re-add `accepted` to the canonical enum)
- [ ] `schemas/common.yaml` canonical status enum re-includes `accepted` as a permitted terminal value alongside `verified`/`released`/`deprecated`/`rejected`, with a one-line schema comment naming `accepted` as the documented terminal state for design-decision / external-anchor / requirement-meta artifacts (the 12-error chunk)
- [ ] Regression fixture: a project store with a `design-decision` whose `status: accepted` validates cleanly (0 errors) on `cargo run -p rivet-cli -- validate`
- [ ] `rivet schema info common` (and/or `rivet schema show common`) prints `accepted` in the allowed-values list so the diagnostic and the introspection surface agree
- [ ] `rivet validate` PASS on the rivet repo itself; `cargo test -p rivet-core -p rivet-cli` green; `cargo fmt --check` / `clippy --all-targets -- -D warnings` clean
- [ ] Commit trailer: `Fixes: REQ-162` (the REQ that introduced the canonical enum in PR #419) + `Refs: #352, #419, #522`
- [ ] **Explicitly out of scope (file separately if wanted):** slice 1 (`rivet migrate status-remap` / `validate --fix` for status — distinct command, default-mapping policy decision); slice 3 (`ai-found-defect`'s `open`/`resolved` — separate schema question: dedicated enum vs. `lifecycle:` discriminator on common); back-fill of the `rivet 0.16.0 upgrade` docs page

If you'd rather start with slice 1 (the migration command), the AC shape changes — needs the default-mapping table in the body (accepted → ?, open → ?, resolved → ?) plus a decision on whether validate --fix writes in place or emits a patch. If slice 3, it needs the discriminator-vs-enum decision pinned first.

Process side-rail (carried from every other open triage thread this week): https://pulseengine.eu/blog/ is still HTTP 503 — same expired-TLS symptom flagged on #420 and re-noted across all recent triage runs (#518 / #516 / #514 / #509 / #500 / #490 / #479 / #468 / #456 / #436 / #431 / #422 / #350). The binding workflow guidance can't be consulted, so no PR will land from this triage run regardless. Comment is the AC ask only.

Not implemented this run.

---

Generated by Claude Code — issue-triage agent run 2026-06-10.

---

Generated by Claude Code

[avrabe]

Draft PR up for slice 2 (re-add accepted): #525.

The acceptance bullets in the issue body are each addressed end-to-end (schema + comment, regression test with positive + negative control, Schema::base_fields introspection assertion so rivet schema info / schema show and the diagnostic can't drift again, rivet validate PASS, fmt + clippy clean, commit trailer Fixes: REQ-162 / Refs: #352, #419, #522). The 12-error accepted chunk on the jess store should be cleared by this — slices 1 (rivet migrate / validate --fix status-remap) and 3 (per-schema status for ai-found-defect) remain explicitly out of scope per your AC, so file when you want them.

Process side-rail (carried): https://pulseengine.eu/blog/ is still HTTP 503 across this run — same symptom flagged on #420 / #516 / earlier triage threads. The binding "consult the workflow guidance before opening a PR" hard rule therefore couldn't be cleared mechanically, so #525 is parked as draft rather than ready-for-review, pending your check against the authoritative posts once the blog is reachable. Everything else on the AC is verified green.

---

Generated by Claude Code — issue-triage agent run 2026-06-10.

---

Generated by Claude Code

[avrabe]

Pre-merge verification of #525 against the real downstream store that motivated this issue — built 117e9c7 (pr525) and ran it on the jess artifact store:

build	status-enum errors on jess
main e60a3a9 (no fix)	26 — accepted×13, open×7, resolved×6
pr525 117e9c7	13 — accepted×0 ✅, open×7, resolved×6

Slice 2 does exactly what the AC promised on a real store: every accepted error cleared, nothing else disturbed. The remaining open/resolved errors are the ai-found-defect vocabulary — precisely the slice-3 scope we excluded, so no surprises.

From jess's side #525 is good to land once your blog/workflow-guidance check clears. After it ships in a release, jess will upgrade off 0.15.0 and (if you want) I'll file the scoped slice-3 issue (ai-found-defect status vocabulary: dedicated enum vs lifecycle: discriminator) with the jess store as the fixture.