---
name: rite-upgrade
description: Audit and reconcile an older released DevRites workspace. Proves a current-contract defect, then routes its phase owner while preserving completed work and history.
argument-hint: "[feature-slug]"
user-invocable: true
disable-model-invocation: true
---

# /rite-upgrade: reconcile a released workspace safely

Use when an unfinished workspace from an older release cannot resume. This is a
audit/orchestrator—not a pack update, cursor conversion, release replay,
structural migration, or generic cleanup.

## Rules consulted

Read `devrites-lib/reference/standards/core.md`, its agent and workspace-schema
references, and only current phase contracts needed for the observed gap.

## Invariants

- Upgrade writes no workspace artifact and never edits source, tests, dependencies,
  or Git. It observes, admits, invokes current owners, and re-audits only.
- Recognize only released workspace forms: `.devrites/work/<slug>/state.md` with v1/v2
  bullet fields (`- Phase:`, `- Next step:`, optional `- qid:`) or the v3 cursor table.
  Preserve its encoding; only its owning rite may change fields. Never create aliases,
  journals, telemetry, version markers, or an engine migrator.
- Older provenance, cursor form, or pack version alone is never a defect. A repair requires
  a current rule, exact workspace evidence, affected gate, owning rite, exact paths, and
  the smallest behavior-neutral delta.
- Existing rites own semantic changes. Upgrade may sequence `/rite-clarify`,
  `/rite-plan repair`, `/rite-converge`, `/rite-vet`, `/rite-prove`, `/rite-polish`,
  `/rite-review`, and `/rite-seal`; it never reimplements them or starts Build or Ship.
  `/rite-doctor` owns install/config diagnosis.
- An admitted candidate route may name only the exact current gate artifacts its owner
  must refresh: `touched-files.md`, `evidence.md`, optional `browser-evidence.md`,
  `polish-report.md`, `review.md`, `seal.md`, and the owner's `state.md` fields as
  applicable. Source, completed-slice identities, answers, decisions, and unrelated
  history remain protected. Each owner preserves unrelated content and normal gates.
- Archived/`done` workspaces are no-ops. Unknown or unverifiable inputs stop without
  writes. There is no legacy fallback: never synthesize or guess scope, bytes, proof,
  freshness, or a historical pass.
- The explicit invocation authorizes only admitted, behavior-neutral workspace repairs.
  Product/policy choices, acceptance changes, irreversible risk, and human-only actions
  remain HITL.

## Workflow

0. **Orient read-only.** Apply `/rite-doctor`. Resolve the explicit or active slug.
   Archive-only is `current`; otherwise require contained regular `state.md` and read its
   cursor. A damaged/mismatched install stops at Doctor; missing live work routes
   `/rite-spec`; `done` is `current`. An unknown cursor is `unsupported`.
1. **Freeze preservation evidence.** Record `git status --short`, cursor form/fields, and
   hashes of completed-slice fields, candidate gate artifacts, existing answers/decisions,
   and protected history. Inventory every path that could change; absence is evidence,
   never permission to synthesize history. For a post-Build workspace, also retain the
   exact result of `devrites-engine check candidate <slug>`; at or after Seal retain the
   exact result of `devrites-engine check seal <slug>`.
2. **Assess from fresh context.** Dispatch exact `devrites-upgrade-planner` with the named
   installed contracts, workspace paths, cursor form, current phase, and frozen baseline.
   Require one read-only typed assessment. It writes and asks nothing.
3. **Admit the assessment fail closed.** Accept `current` only when every applicable axis has
   cited evidence and no finding. Accept `repairable` only when every finding names the
   current rule, exact workspace evidence, affected gate, owning rite, exact writable paths,
   minimal delta, and protected invariants. Missing fields become `gap`.
   Unsupported shapes remain untouched. Reject version-only, speculative, alias-creating,
   source-changing, history-changing, or acceptance-changing advice.
4. **Route; do not duplicate.** For `repairable`, invoke only the admitted current owners,
   one at a time:
   - decision coverage or a material assumption → `/rite-clarify`;
   - stale/inconsistent planning or traceability with settled intent → `/rite-plan repair`;
   - live code and recorded intent disagreement → `/rite-converge`;
   - any changed planning input or readiness defect → `/rite-vet`;
   - a missing/malformed strict manifest, missing/malformed/mismatched evidence binding,
     a browser-binding defect when that file exists, or current candidate-check failure
     → `/rite-prove`;
   - candidate-affecting capability-ledger, `DESIGN.md`, or ADR rollups still deferred by
     an old Ship-era workspace → `/rite-polish`;
   - a missing, stale, or mismatched review binding → `/rite-review`;
   - a missing, stale, or mismatched seal binding or failed Seal gate → `/rite-seal`.

   Sequence only applicable owners; candidate owners stay in the Prove → Polish → Review
   → Seal order above. Each owner keeps normal gates/write limits. Stop on HITL/blocked.
   Never infer `/rite-customize --import-legacy`; that mode requires the exact token in the
   user's current invocation.
5. **Re-audit and prove preservation.** Re-dispatch the planner once against the changed
   candidate. `gap`, `unsupported`, or a remaining finding stops. Compare the frozen hashes
   and Git status; only admitted paths may differ. Cursor changes must match the owning
   rite while preserving form. Any unadmitted, protected, or source change is a gap and
   stops; Upgrade never restores it itself.
   For a post-Build workspace, run `devrites-engine check candidate <slug>` and require
   the assessed bindings to match it. At or after Seal, also run
   `devrites-engine check seal <slug>`. Run readiness where applicable:
   ```bash
   devrites-engine check readiness <slug>; echo "readiness rc=$?"
   ```
   Any nonzero result or mismatch remains a `gap` and stops.
6. **STOP.** Do not advance to Build or Ship. A repeated `/rite-upgrade` is a no-op only
   when the fresh assessment independently returns `current`; no marker may manufacture
   that result.

## Output

```text
Done: workspace <slug> compatibility <current | reconciled>.
Changed: <admitted active-workspace paths | none>
Evidence: assessment=current; candidate rc=<n|n/a>; seal rc=<n|n/a>; readiness rc=<n|n/a>; protected history/source unchanged
Open: <none | exact unsupported shape, evidence gap, or human gate>
Next: <state.md next action | one owning rite>
Record: .devrites/work/<slug>/state.md
↻ Hygiene: /clear before the next lifecycle step
```