Rite Upgrade

$rite-upgrade: reconcile a released workspace safely

Use when an unfinished workspace from an older release cannot resume. This is an 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:

   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

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: <owning rite's state.md — written by the owner, not Upgrade>
↻ Hygiene: /clear before the next lifecycle step