devrites 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [3.2.0](https://github.com/ViktorsBaikers/DevRites/compare/v3.1.0...v3.2.0) (2026-07-24)
+
+### Added
+
+* **rite:** add semantic workspace upgrades ([3a7e51d](https://github.com/ViktorsBaikers/DevRites/commit/3a7e51d478fe9ed19c4de1ee4988e43d63ecf9a2))
+
 ## [3.1.0](https://github.com/ViktorsBaikers/DevRites/compare/v3.0.7...v3.1.0) (2026-07-24)
 
 ### Added

package/README.md

@@ -25,7 +25,7 @@ final commit, push, and tag, and it requires a typed `GO` confirmation.
 Unattended runs may create local WIP checkpoint commits along the way, but only
 Ship collapses and pushes them.
 
-**Status:** [`v3.1.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.1.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.2.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Quick start
 
@@ -85,6 +85,7 @@ the same skill.
 | 10 | Review | [`/rite-review`](pack/.claude/skills/rite-review/SKILL.md) | Reviews the completed feature against its spec and engineering standards. |
 | 11 | Seal | [`/rite-seal`](pack/.claude/skills/rite-seal/SKILL.md) | Writes the final `GO` or `NO-GO` decision without changing git. |
 | 12 | Ship | [`/rite-ship`](pack/.claude/skills/rite-ship/SKILL.md) | On `GO`, asks for typed confirmation, performs the approved git actions, and archives the workspace. |
+| n/a | Upgrade *(conditional)* | [`/rite-upgrade [slug]`](pack/.claude/skills/rite-upgrade/SKILL.md) | Brings an active unfinished workspace onto the current planning contract without rewriting completed work or evidence. Build readiness sends stale workspaces here automatically. |
 
 Some work needs a different route:
 
@@ -93,8 +94,16 @@ Some work needs a different route:
 - [`/rite-autocomplete`](pack/.claude/skills/rite-autocomplete/SKILL.md) runs
   the lifecycle unattended. With `--ship`, it auto-confirms the final typed
   `GO`; without that flag, it stops and waits for you.
+- [`/rite-upgrade [slug]`](pack/.claude/skills/rite-upgrade/SKILL.md) is a
+  maintenance route for an active workspace planned under older DevRites
+  rules. It is not a mandatory lifecycle phase.
 - [`/rite`](pack/.claude/skills/rite/SKILL.md) shows the command menu.
 
+`devrites-engine update` refreshes the installed engine and pack.
+`devrites-engine migrate` normalizes workspace layout and structural state.
+Neither replaces `/rite-upgrade`, which reconciles unfinished planning
+semantics while preserving completed work.
+
 The [command map](docs/command-map.md) covers every command, trigger, input, and
 output. The [worked examples](docs/usage.md) show normal features, plan drift,
 UI work, backend work, and mid-flight handoffs.
@@ -146,9 +155,11 @@ Some phases add focused artifacts such as `strategy.md`, `design-brief.md`,
   its proof before returning control. Before dispatching the sole writer, the
   root writes an exact `.wright-allowlist`. Reconciliation and integrity gates
   use the same pre-slice baseline.
-- **Stop on drift.** If implementation no longer matches the plan, the Spec
-  Drift Guard records the mismatch in `drift.md` and routes through
-  [`/rite-plan repair`](pack/.claude/skills/rite-plan/SKILL.md).
+- **Classify drift before routing.** The Spec Drift Guard records the mismatch
+  in `drift.md`. Build handles objective implementation and tool failures with
+  bounded recovery; it uses
+  [`/rite-plan repair`](pack/.claude/skills/rite-plan/SKILL.md) only when the
+  durable plan is wrong, and asks you only for a real product or risk decision.
 - **Prove claims.** Tests, commands, output, and opened screenshots support
   completion claims. A screenshot path by itself is not proof.
 - **Separate the decision from the action.** Seal makes the release decision.
@@ -275,14 +286,15 @@ through Claude Code or Codex plugin stores.
 
 ## Skills and agents
 
-The pack ships 43 skills: 31 public and 12 internal. The public surface contains
-the `rite` menu and 30 `rite-*` workflows and utilities. Eleven `devrites-*`
+The pack ships 44 skills: 32 public and 12 internal. The public surface contains
+the `rite` menu and 31 `rite-*` workflows and utilities. Eleven `devrites-*`
 specialists load when a matching task needs them; `devrites-lib` carries the
 shared contracts and engineering standards.
 
-Seventeen fresh-context agents ship with the pack. Sixteen are read-only,
+Eighteen fresh-context agents ship with the pack. Seventeen are read-only,
 including the evidence scout, plan drafter, proof runner, reviewers, judges,
-and retrospector. `devrites-slice-wright` is the only source/test writer.
+upgrade planner, and retrospector. `devrites-slice-wright` is the only
+source/test writer.
 
 The authoritative [skills catalogue](docs/skills.md) lists every skill and
 agent. The [flow diagrams](docs/flow.md) show routing, reviewer fan-out, and

package/docs/adr/0012-semantic-workspace-upgrades.md

@@ -0,0 +1,77 @@
+# ADR-0012: Separate semantic workspace upgrades from structural migration
+
+- **Status:** Accepted
+- **Date:** 2026-07-24
+
+## Context
+
+Updating DevRites replaces the installed engine, skills, agents, and hooks. It
+does not prove that an active workspace was planned under the rules shipped by
+that update.
+
+The existing `devrites-engine migrate` command has a narrower job: it repairs
+workspace layout, aliases, and state schema. Extending it to rewrite plans would
+mix structural storage changes with product decisions and could damage completed
+work.
+
+This distinction matters most for long-running workspaces. A plan may still be
+internally consistent while carrying an obsolete proof recipe, a local command
+wrapper, or readiness evidence produced by an older workflow. Byte hashes alone
+cannot tell us that those instructions remain valid.
+
+## Decision
+
+DevRites will keep three upgrade operations separate:
+
+| Operation | Responsibility |
+| --- | --- |
+| `devrites-engine update` | Update the installed engine and workflow pack. |
+| `devrites-engine migrate` | Normalize workspace layout and structural state schema. |
+| `/rite-upgrade [slug]` | Reconcile an active workspace with the current semantic planning contract. |
+
+Semantic compatibility is versioned by the readiness-artifact contract, not by
+the DevRites release number or workspace state schema. The current contract is
+`devrites.readiness-artifacts.v2`.
+
+`decision-coverage.md`, `eng-review.md`, and `test-plan.md` declare the semantic
+contract that produced them. Build readiness returns code `8`
+(`upgrade-required`) when existing readiness artifacts use an older, missing,
+or incompatible contract, and routes the workspace to `/rite-upgrade`.
+
+`/rite-upgrade` is desired-state reconciliation, not a replay of historical
+migrations. It:
+
+- works only on the active unfinished planning surface;
+- preserves product source, completed slice bodies, proof, evidence, and
+  accepted decisions;
+- removes obsolete engine-repair recipes and machine-local command wrappers
+  from active canonical plans;
+- reruns current coverage, planning, and engineering-readiness checks;
+- asks the user only when the current contract exposes a real product or risk
+  decision; and
+- makes no changes when the workspace is already current and ready, completed,
+  or archived.
+
+A fresh read-only `devrites-upgrade-planner` classifies the gap before any
+mutation. The public skill remains the sole writer and verifies the resulting
+workspace before build resumes.
+
+## Alternatives considered
+
+| Option | Why not |
+| --- | --- |
+| Treat the installed DevRites release as the workspace contract | Release numbers describe the whole product and do not say which planning semantics produced an artifact. |
+| Extend `devrites-engine migrate` to rewrite planning artifacts | Structural migration cannot safely make product judgments or distinguish completed evidence from unfinished instructions. |
+| Replay one migration for every historical release | It would preserve obsolete intermediate mechanics and make long-lived workspaces depend on an ever-growing migration chain. Desired-state reconciliation is smaller and safer. |
+| Force users to restart old workspaces | It discards trustworthy completed work and evidence without improving the unfinished plan. |
+
+## Consequences
+
+- Updating DevRites cannot silently certify an old plan as current.
+- Structural migration stays deterministic and safe to run independently.
+- Active work can move forward without discarding trustworthy completed
+  evidence or recreating an old engine.
+- New semantic rules require a readiness-contract revision and a bounded
+  desired-state upgrade path.
+- Archived workspaces remain historical records rather than being rewritten to
+  match current conventions.

package/docs/adr/README.md

@@ -57,3 +57,4 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 | [0009](0009-prebuild-decision-coverage-and-readiness.md) | Pre-build decision coverage and implementation readiness | Accepted | `internal/state/state_test.go`, `tests/parity_buildreadiness_test.go` |
 | [0010](0010-agent-first-fresh-context-orchestration.md) | Agent-first fresh-context orchestration | Accepted | `tests/hook_test.go`, `tests/codex-agent-generation-test.sh` |
 | [0011](0011-define-plan-transition-rights.md) | Separate Define authoring from the Plan checkpoint | Accepted | `internal/state/state_test.go`, `tests/adr_0011_define_plan_test.go` |
+| [0012](0012-semantic-workspace-upgrades.md) | Separate semantic workspace upgrades from structural migration | Accepted | `tests/parity_buildreadiness_test.go` |

package/docs/architecture.md

@@ -19,15 +19,17 @@ traceability rules, and phase-relative completeness model, see
    `rite-vet`, `rite-build`, recovery `rite-converge`, `rite-prove`,
    `rite-polish`, `rite-review`, `rite-seal`, and `rite-ship`. `rite-plan`
    repairs or reslices an active plan. The resume verb `rite-resolve` answers a
-   HITL gate and clears `Awaiting human`. The thin `/rite` menu and read-only
-   `rite-status` live in the public utility layer below.
+   HITL gate and clears `Awaiting human`. `rite-upgrade` is a conditional
+   maintenance route for semantically stale active workspaces, not a lifecycle
+   phase. The thin `/rite` menu and read-only `rite-status` live in the public
+   utility layer below.
    `/rite-seal` **decides** GO/NO-GO and writes the verdict to `seal.md`;
    `/rite-ship` is the final core lifecycle rite that **executes** the
    irreversible git ladder and **closes** the task by archiving the workspace
    and clearing `ACTIVE`. Separate steps let users audit the release decision
    before any irreversible action.
 2. **Public utility and on-ramp skills**: `rite-adopt`, `rite-quick`,
-   `rite-frame`, `rite-status`, `rite-doctor`, `rite-learn`, `rite-explain`,
+   `rite-frame`, `rite-status`, `rite-doctor`, `rite-upgrade`, `rite-learn`, `rite-explain`,
    `rite-customize`, `rite-zoom-out`, `rite-prototype`, `rite-handoff`,
    `rite-pressure-test`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, and
    `rite-autocomplete`. These are public commands. `rite-autocomplete` is the
@@ -56,12 +58,13 @@ traceability rules, and phase-relative completeness model, see
 4. **Supporting references**: `reference/*.md` inside each skill. Long checklists,
    templates, and anti-rationalization tables loaded on demand (progressive
    disclosure) so `SKILL.md` bodies stay small.
-5. **Agents**: `.claude/agents/devrites-*` contains **17 flat depth-one roles**:
-   16 read-only leaves and the sole source/test writer,
+5. **Agents**: `.claude/agents/devrites-*` contains **18 flat depth-one roles**:
+   17 read-only leaves and the sole source/test writer,
    `devrites-slice-wright`. The read-only set includes three bounded work
    leaves (`devrites-evidence-scout`, `devrites-plan-drafter`, and
-   `devrites-proof-runner`) plus the existing reviewers, auditors, judge, and
-   retrospector. Public rites remain authoritative: leaves return typed
+   `devrites-proof-runner`), the fresh `devrites-upgrade-planner`, plus the
+   existing reviewers, auditors, judge, and retrospector. Public rites remain
+   authoritative: leaves return typed
    evidence, never ask the human, change phase, or write canonical
    `.devrites/**` state. See [`orchestration.md`](orchestration.md) for the
    dispatch, fallback, identity, and reconciliation contract.
@@ -138,6 +141,24 @@ generated into `pack/generated/**` and installed to `.agents/skills`, `.codex/ag
 different project-local conventions. Those generated host artifacts are delivered by the
 npm installer; Claude/Codex plugin packaging is intentionally not a distribution path.
 
+### Why semantic upgrade is separate from update and migration
+
+Three operations solve different problems. `devrites-engine update` refreshes
+the installed binary and pack. `devrites-engine migrate` normalizes workspace
+layout and structural state schema. Neither one can claim that an active plan
+still follows the current planning rules.
+
+`/rite-upgrade [slug]` owns that semantic reconciliation. Build readiness uses
+the `devrites.readiness-artifacts.v2` contract declared by
+`decision-coverage.md`, `eng-review.md`, and `test-plan.md`; it returns code `8`
+when those existing artifacts are stale. The rite then asks a fresh read-only
+`devrites-upgrade-planner` to classify the gap before the root changes anything.
+It preserves completed source, slice bodies, decisions, and evidence, repairs
+only active unfinished planning, removes obsolete proof recipes and local
+wrappers, and reruns the current readiness gates. Already-current workspaces
+that pass readiness, completed workspaces, and archives remain untouched. See
+[ADR-0012](adr/0012-semantic-workspace-upgrades.md).
+
 ### Why `/engine` was rejected
 A single `/engine` (or `/devrites`) command would load every phase's
 instructions into one context. That would increase context pressure, obscure
@@ -278,8 +299,8 @@ contract.
 
 ## Design choices at a glance
 
-- **Surface**: 30 public `rite-*` skills (43 total), plus the thin `/rite`
-  menu: 31 public and 12 internal. The lifecycle
+- **Surface**: 31 public `rite-*` skills (44 total), plus the thin `/rite`
+  menu: 32 public and 12 internal. The lifecycle
   includes mandatory adaptive Clarify, optional Temper, mandatory Vet, and
   Converge recovery; Seal **decides** and Ship **executes + closes**. Eleven
   `devrites-*` specialists are model-invoked and `devrites-lib` is the shared
@@ -296,7 +317,7 @@ contract.
 - **Slice rule**: build **one vertical slice, then stop**. There is no automatic continuation.
 - **Drift**: an explicit **Spec Drift Guard** in build/prove/polish/review/seal.
 - **Design**: `devrites-frontend-craft` + a four-phase `/rite-polish` orchestrator (code + backend always; UI normalize + polish when UI is in scope).
-- **Agents**: 17 fresh-context roles at flat depth one: 16 read-only leaves and
+- **Agents**: 18 fresh-context roles at flat depth one: 17 read-only leaves and
   one wright. Fallback order is named, generic, then labelled inline.
 - **Review**: **feature-scoped** multi-axis review with severity labels and
   fresh-context agents at the seal.

package/docs/cli.md

@@ -69,6 +69,7 @@ objective gaps to their owner:
 | `5` | `workspace-missing` | Workspace or state.md is missing | `/rite-spec` |
 | `6` | `coverage-not-clear` | Decision coverage is not CLEAR and fresh | `/rite-clarify` |
 | `7` | `engineering-not-ready` | Plan is not vetted or implementation readiness is not READY | `/rite-vet` |
+| `8` | `upgrade-required` | Planning artifacts use an older or unknown DevRites contract | `/rite-upgrade` |
 <!-- authority:readiness-reasons:end -->
 
 A non-zero `build-readiness`,
@@ -76,10 +77,15 @@ A non-zero `build-readiness`,
 in an agent loop, a local script, or pre-merge CI.
 
 `build-readiness` does not trust `CLEAR` or `READY` text alone. It validates the
-required sections, tables, ownership and test mappings, and compares each
-artifact's SHA-256 field with the digest of its canonical inputs. Migration may
-upgrade a workspace declaration to schema v2, but it never creates or blesses
-clarification, vet, or proof evidence.
+required sections, tables, ownership and test mappings, requires the current
+`devrites.readiness-artifacts.v2` declaration, and compares each artifact's
+SHA-256 field with the digest of its canonical inputs.
+
+`devrites-engine update` refreshes the installed binary and pack.
+`devrites-engine migrate` may upgrade a workspace declaration to structural
+schema v2, but it never creates or blesses clarification, vet, or proof
+evidence. `/rite-upgrade [slug]` is the separate semantic reconciliation route
+for an active unfinished workspace.
 
 ## Why this exists
 

package/docs/command-map.md

@@ -20,8 +20,9 @@ visibility. Public utilities use the `rite-*` prefix: `rite-quick`,
 `rite-frame`, `rite-adopt`, `rite-learn`, `rite-doctor`, `rite-customize`,
 `rite-zoom-out`, `rite-prototype`, `rite-handoff`, `rite-pressure-test`,
 `rite-autocomplete`, `rite-explain`, `rite-pov`, `rite-dogfood`, and
-`rite-pr-feedback`. The host may invoke `devrites-*` specialists through the
-model. `devrites-lib` is the non-workflow library exception.
+`rite-pr-feedback`, plus the semantic workspace maintenance command
+`rite-upgrade`. The host may invoke `devrites-*` specialists through the model.
+`devrites-lib` is the non-workflow library exception.
 
 ## Surface lifecycle
 
@@ -49,6 +50,11 @@ Workflow-owned commands should have a concrete call site in a `rite-*` skill,
 phase contract, shared reply contract, or installed hook. Operator-owned commands
 must say who runs them.
 
+These similarly named operations have separate owners: `devrites-engine update`
+replaces the installed engine and pack, `devrites-engine migrate` normalizes
+workspace layout and structural state schema, and `/rite-upgrade` reconciles an
+active workspace with the current semantic planning contract.
+
 ## Public commands (`user-invocable: true`)
 
 | Command | Phase | Argument | What it does | Reads | Writes |
@@ -62,6 +68,7 @@ must say who runs them.
 | [`/rite-plan`](../pack/.claude/skills/rite-plan/SKILL.md) | repair → plan | `[mode]` | Reslice / repair / re-order / split / unblock an active plan and return to the `plan` checkpoint; `revise` is artifact-only and `/rite-vet` is the normal resume. | spec/plan/tasks/state/drift + diff | `plan.md`, `tasks.md`, `state.md`, `decisions.md` |
 | [`/rite-build`](../pack/.claude/skills/rite-build/SKILL.md) | build | `[slice]` | Orchestrate **exactly one** vertical slice through the sole wright. The root writes an exact `.wright-allowlist`, retains the original slice baseline through snapshot → reconcile check → test/package integrity → close, and refreshes only the dispatch boundary on bounded retries. Objective failures stay agent-owned; only product/scope/policy choices, irreversible risk, or human-only access/actions become questions. | workspace + diff + `.devrites/CHECKPOINT` | code + `.wright-allowlist`, `recovery-attempts.jsonl`, `state.md`, `evidence.md`, `traceability.md`, `touched-files.md` (+ local `WIP(<slug>)` commit in checkpoint mode) |
 | [`/rite-converge`](../pack/.claude/skills/rite-converge/SKILL.md) | converge | `[slug]` | **Recovery.** Compare live code with clarified intent, append each unmet piece as a traceable `SLICE-###`, and invalidate the old vet verdict so changed work returns through `/rite-vet`. `tasks.md` stays byte-identical when already converged. | clarified spec + plan/tasks + principles + live code | `tasks.md` (appended), `traceability.md`, `state.md`, `eng-review.md` (invalidated), `decisions.md` |
+| [`/rite-upgrade`](../pack/.claude/skills/rite-upgrade/SKILL.md) | maintenance | `[slug]` | **Conditional recovery.** Bring an active unfinished workspace onto `devrites.readiness-artifacts.v2`. A fresh read-only planner identifies the smallest change; the rite preserves completed source, slices, decisions, and evidence, removes stale engine-proof recipes and machine-local wrappers from active plans, then reruns current readiness gates. Already-current workspaces that pass readiness, completed workspaces, and archives are no-ops. | active workspace + current readiness contract | active unfinished planning artifacts only |
 | [`/rite-prove`](../pack/.claude/skills/rite-prove/SKILL.md) | prove | `[scope]` | Tests + build + runtime + browser proof of the completed feature. | `traceability.md` + workspace + diff | `evidence.md`, `browser-evidence.md`, `traceability.md`, `state.md` |
 | [`/rite-polish`](../pack/.claude/skills/rite-polish/SKILL.md) | polish | `[target \| mode]` | Orchestrator. Reads `reference/code.md` always (Phase 1 + 2); reads `reference/ui.md` when UI is touched (Phase 3 + 4). Mode tokens: `bolder \| quieter \| distill \| harden \| normalize-only`. | workspace + design system + diff | `polish-report.md`, `browser-evidence.md` |
 | [`/rite-review`](../pack/.claude/skills/rite-review/SKILL.md) | review | `[scope]` | Feature-scoped multi-axis review. Parallel fresh-context Spec + Standards agents (`devrites-spec-reviewer`, `devrites-code-reviewer`). | workspace + diff | `review.md`, `evidence.md`, `state.md` |
@@ -110,7 +117,7 @@ the shared reference library.
 
 ## Agents (`.claude/agents/devrites-*`, fresh-context leaves)
 
-**Seventeen roles:** 16 read-only leaves plus one source/test writer,
+**Eighteen roles:** 17 read-only leaves plus one source/test writer,
 `devrites-slice-wright`.
 
 | Agent | Spawned by | Purpose |
@@ -118,6 +125,7 @@ the shared reference library.
 | [`devrites-evidence-scout`](../pack/.claude/agents/devrites-evidence-scout.md) | `/rite-spec`, `/rite-clarify`, `/rite-converge` | Read-only bounded evidence dossier from live code, project records, or cited external facts |
 | [`devrites-plan-drafter`](../pack/.claude/agents/devrites-plan-drafter.md) | `/rite-define`, `/rite-plan repair` | Read-only planning candidate; the root makes decisions and writes planning artifacts |
 | [`devrites-proof-runner`](../pack/.claude/agents/devrites-proof-runner.md) | `/rite-prove`, affected re-proof | Read-only tree plus non-destructive command execution; returns a proof report, never the verdict |
+| [`devrites-upgrade-planner`](../pack/.claude/agents/devrites-upgrade-planner.md) | `/rite-upgrade` | Fresh read-only assessment of semantic contract gaps; returns a bounded preservation-first upgrade plan |
 | [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) | `/rite-build` (the build core) | **Sole source/test writer**: implement one exact allowlisted slice (orient → TDD → verify); returns a typed artifact and writes no bookkeeping |
 | [`devrites-strategy-reviewer`](../pack/.claude/agents/devrites-strategy-reviewer.md) | `/rite-temper` (pre-plan) | Spec-vs-rubric strategic review (ambition / scope / premise / pre-mortem / YAGNI / testability / irreversibility / cross-cutting / convention); read-only; **not** part of the seal fan-out |
 | [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md) | `/rite-vet` (pre-build) | Plan-vs-rubric engineering review (architecture / scope-reuse / plan code-quality / test-coverage design / performance / reversibility / failure-mode coverage), confidence-banded with a quote-the-source verification gate; read-only; **not** part of the seal fan-out |
@@ -196,9 +204,10 @@ See [`flow.md`](flow.md) for the Mermaid diagrams. The text form is:
 
 - Every phase **reads the active workspace first**; if none, it stops and tells
   the user to run `/rite-spec <feature>`.
-- **Spec Drift Guard** lives in build/prove/polish/review/seal: on drift,
-  stop, record in `drift.md`, classify, ask the user if product behavior
-  changes, then `/rite-plan repair` before resuming.
+- **Spec Drift Guard** lives in build/prove/polish/review/seal: on drift, stop,
+  record in `drift.md`, and classify. Objective implementation and tool defects
+  use bounded recovery; a wrong durable plan uses `/rite-plan repair`; only a
+  product, policy, or irreversible-risk choice asks the user.
 - `/rite-seal` fans out to `.claude/agents/devrites-*` reviewers **in
   parallel** for independent, fresh-context judgment, then writes the GO /
   NO-GO verdict: it runs no git. On GO it hands off to `/rite-ship`, which

package/docs/engine/commands.md

@@ -127,6 +127,12 @@ Migration is:
 The phase is derived from the legacy `state.md`, defaulting to `build` when it
 can't be read.
 
+`devrites-engine update` refreshes the installed binary and pack. Migration
+stops at structural compatibility and does not certify old planning artifacts
+against current workflow rules. Build readiness routes an active workspace with
+stale semantic artifacts to `/rite-upgrade [slug]`; that public rite preserves
+completed work and reconciles only unfinished planning.
+
 ## Hooks: `hook <name> --harness=claude|codex`
 
 One binary serves Claude Code and Codex through thin per-harness adapters.

package/docs/engine/workspace-schema.md

@@ -33,6 +33,10 @@ engine reads missing/v1 declarations and legacy aliases additively, refuses a
 version newer than it supports, and keeps the snapshot wire schema separate.
 `devrites-engine migrate` upgrades the declaration and layout metadata; it does
 not manufacture decision coverage, vet readiness, test plans, or proof.
+Semantic planning compatibility uses a separate readiness-artifact contract.
+The current value is `devrites.readiness-artifacts.v2`; `/rite-upgrade [slug]`
+reconciles an active unfinished workspace when build readiness reports an older
+or unknown contract.
 
 Canonical live workspace:
 
@@ -141,6 +145,8 @@ Files may exceed budgets only with a visible `Budget override: <reason>` line.
 
 The typed verdict is necessary but not sufficient:
 
+- `decision-coverage.md`, `eng-review.md`, and `test-plan.md` declare
+  `DevRites contract: devrites.readiness-artifacts.v2`.
 - `Coverage inputs SHA-256` binds `decision-coverage.md` to `brief.md`,
   `spec.md`, `decisions.md`, `assumptions.md`, and `questions.md`.
 - `Readiness inputs SHA-256` binds `eng-review.md` to `spec.md`,
@@ -149,7 +155,10 @@ The typed verdict is necessary but not sufficient:
 
 `devrites-engine readiness-digest coverage|engineering [slug]` emits the
 canonical field line. `build-readiness` rejects stale digests, malformed or
-contradictory content, and missing markers. A later-phase clarification
+contradictory content, missing markers, and older or unknown semantic contracts.
+Contract failures use code `8` and route to `/rite-upgrade`; missing coverage or
+vet artifacts keep their existing `/rite-clarify` and `/rite-vet` routes. A
+later-phase clarification
 retrofit uses `clarify-return enter|restore`; restore requires fresh `CLEAR`
 coverage, while an acceptance-changing result keeps the cursor for plan repair.
 

package/docs/flow.md

@@ -10,10 +10,12 @@ For the full per-skill table, see [`command-map.md`](command-map.md). For the
 
 This diagram shows the normal path. Each arrow assumes that the previous
 phase's readiness gate passed. Failures route through `/rite-clarify`,
-`/rite-plan repair`, or `devrites-debug-recovery`. `/rite-clarify` always runs
-but may ask zero questions; `/rite-temper` is the optional strategic branch;
-`/rite-vet` runs on every defined plan, with depth scaled to risk. Build asks
-the human only for genuine
+`/rite-plan repair`, `/rite-upgrade`, or `devrites-debug-recovery`.
+`/rite-upgrade` is conditional maintenance rather than a lifecycle phase: build
+readiness uses it only when existing semantic artifacts are stale.
+`/rite-clarify` always runs but may ask zero questions; `/rite-temper` is the
+optional strategic branch; `/rite-vet` runs on every defined plan, with depth
+scaled to risk. Build asks the human only for genuine
 product/scope/policy decisions, irreversible risk, or human-only access/actions;
 `/rite-resolve` is the resume verb.
 
@@ -28,6 +30,8 @@ flowchart LR
     Define -->|plan.md + tasks.md<br/>approved| Plan[(plan checkpoint)]
     Plan -->|normal resume| Vet[/rite-vet/]
     Vet -->|fresh digest-bound READY<br/>+ test-plan.md| Build[/rite-build/]
+    Build -.->|build-readiness code 8<br/>stale semantic contract| Upgrade[/rite-upgrade/]
+    Upgrade -.->|contract v2<br/>current gates pass| Build
     Build -.->|exact .wright-allowlist<br/>retained baseline| Wright[devrites-slice-wright]
     Wright -.->|typed result| Build
     Build -->|one slice done<br/>+ evidence| Build
@@ -59,7 +63,7 @@ flowchart LR
     classDef internal fill:#0f172a,stroke:#9ca3af,color:#f9fafb
     class Spec,Clarify,Temper,Define,Plan,Vet,Build,Prove,Polish,Review,Seal,Ship2 phase
     class Shipped done
-    class Repair repair
+    class Repair,Upgrade repair
     class Await gate
     class Shape,Forge,Wright internal
 ```
@@ -325,7 +329,7 @@ separately by `disable-model-invocation`.
 
 ```mermaid
 flowchart TB
-    subgraph Public["Public (user-invocable: true): 31 skills"]
+    subgraph Public["Public (user-invocable: true): 32 skills"]
         direction TB
         R1[/rite/]
         R2[/rite-spec/]
@@ -349,6 +353,7 @@ flowchart TB
         RA[/rite-adopt/]
         RL[/rite-learn/]
         RD[/rite-doctor/]
+        RU[/rite-upgrade/]
         RE[/rite-explain/]
         RCU[/rite-customize/]
         RDO[/rite-dogfood/]
@@ -377,7 +382,7 @@ flowchart TB
 
     classDef pub fill:#064e3b,stroke:#34d399,color:#ecfdf5
     classDef int fill:#1f2937,stroke:#9ca3af,color:#f9fafb
-    class R1,R2,RCL,RT,R3,RV,R4,R5,RC,R6,R7,R8,R9,R12,R13,R10,R11,RQ,RF,RA,RL,RD,RE,RCU,RDO,RPOV,RPF,IPT,D1,D2,D3 pub
+    class R1,R2,RCL,RT,R3,RV,R4,R5,RC,R6,R7,R8,R9,R12,R13,R10,R11,RQ,RF,RA,RL,RD,RU,RE,RCU,RDO,RPOV,RPF,IPT,D1,D2,D3 pub
     class I1,I2,I3,I4,I5,I6,I7,I8,I9,I10,I11,I12 int
 ```
 

package/docs/orchestration.md

@@ -14,12 +14,12 @@ this page summarizes that model.
   dispatch leaves.
 - Normally at most three read-only leaves run concurrently against one frozen
   candidate. The root awaits every required return before mutation.
-- There are **17 named roles**: 16 read-only leaves and one source/test writer,
+- There are **18 named roles**: 17 read-only leaves and one source/test writer,
   `devrites-slice-wright`.
 
 | Group | Roles |
 |---|---|
-| Bounded work leaves | `devrites-evidence-scout`, `devrites-plan-drafter`, `devrites-proof-runner` |
+| Bounded work leaves | `devrites-evidence-scout`, `devrites-plan-drafter`, `devrites-proof-runner`, `devrites-upgrade-planner` |
 | Strategic/claim challenge | `devrites-strategy-reviewer`, `devrites-plan-reviewer`, `devrites-doubt-reviewer` |
 | Review/audit | `devrites-spec-reviewer`, `devrites-code-reviewer`, `devrites-test-analyst`, `devrites-frontend-reviewer`, `devrites-security-auditor`, `devrites-performance-reviewer`, `devrites-devex-reviewer`, `devrites-simplifier-reviewer` |
 | Comparison/history | `devrites-forge-judge`, `devrites-retrospector` |

package/docs/quick-reference.md

@@ -12,6 +12,10 @@ Claude Code and Codex artifacts; plugin stores do not distribute them.
 Seal makes the release decision, Ship mutates git, Build handles one slice per
 run, and Autocomplete is opt-in.
 
+Conditional maintenance: `/rite-upgrade [slug]` reconciles an active unfinished
+workspace with the current semantic planning contract when build readiness
+returns code `8`. It is not a lifecycle phase.
+
 ## Standing checklists
 
 - Definition of Done: `pack/.claude/skills/devrites-lib/reference/standards/definition-of-done.md`

package/docs/skills.md

@@ -1,6 +1,6 @@
-# All 43 skills
+# All 44 skills
 
-The pack contains 43 skills: the `rite` menu, 30 user-invocable `rite-*`
+The pack contains 44 skills: the `rite` menu, 31 user-invocable `rite-*`
 workflow and utility skills, 11 model-invoked `devrites-*` specialists, and the
 internal `devrites-lib` library. `devrites-lib` is not a command. It holds shared
 references and the few explicit script exceptions.
@@ -23,7 +23,8 @@ only when needed; small utilities keep their narrower contract local. The npm
 `rite-*` is the namespace for lifecycle and utility commands. Its utilities are
 `rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`, `rite-customize`,
 `rite-explain`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, `rite-doctor`,
-`rite-prototype`, `rite-handoff`, `rite-zoom-out`, and `rite-pressure-test`.
+`rite-upgrade`, `rite-prototype`, `rite-handoff`, `rite-zoom-out`, and
+`rite-pressure-test`.
 Some specialized utilities set `disable-model-invocation: true` and run only
 when explicitly invoked, which keeps the always-loaded skill surface small.
 `devrites-*` is the specialist and library namespace used to avoid collisions.
@@ -89,6 +90,7 @@ blocks obvious multi-command `Next:` wording.
 | [`rite-status`](../pack/.claude/skills/rite-status/SKILL.md) | Read-only report: phase, run mode (AFK/HITL), status, active slice, next action, evidence, open questions by gate, drift, risks. | Explicit-only: type `/rite-status` / `/rite status`. |
 | [`rite-resolve`](../pack/.claude/skills/rite-resolve/SKILL.md) | Answer / drop / batch-resolve open `questions.md` entries; clears `state.md` `Awaiting human` and resumes the workflow. | Explicit-only: type `/rite-resolve <qid> "<answer>"`. |
 | [`rite-doctor`](../pack/.claude/skills/rite-doctor/SKILL.md) | Diagnose DevRites install, workspace, and optional index health. `--reindex` runs the internal synchronous refresh. | "rite doctor", "is DevRites healthy", "reindex". |
+| [`rite-upgrade`](../pack/.claude/skills/rite-upgrade/SKILL.md) | Reconcile an active unfinished workspace with the current semantic planning contract while preserving completed source, slices, decisions, and evidence. | Explicit-only: build readiness returns code `8`, or you need to continue a workspace planned under older DevRites rules. |
 | [`rite-customize`](../pack/.claude/skills/rite-customize/SKILL.md) | Guided authoring for project-local reviewer overrides and extensions; validates before stopping. | Explicit-only: `/rite-customize` / `/rite customize`. |
 
 ### Express and ad hoc: small or unguarded work
@@ -203,8 +205,8 @@ blocks obvious multi-command `Next:` wording.
 
 ## Fresh-context agents
 
-DevRites ships 17 roles at depth one: 16 read-only leaves and one source/test
-writer. Three read-only roles handle bounded work while the root keeps
+DevRites ships 18 roles at depth one: 17 read-only leaves and one source/test
+writer. Four read-only roles handle bounded work while the root keeps
 authority:
 
 | Agent | Purpose |
@@ -212,6 +214,7 @@ authority:
 | [`devrites-evidence-scout`](../pack/.claude/agents/devrites-evidence-scout.md) | Build a bounded evidence dossier for spec, clarify, converge, or cited external facts. |
 | [`devrites-plan-drafter`](../pack/.claude/agents/devrites-plan-drafter.md) | Draft a planning candidate for define or plan repair; the root decides and writes artifacts. |
 | [`devrites-proof-runner`](../pack/.claude/agents/devrites-proof-runner.md) | Run non-destructive proof commands against a read-only tree and return a proof report. |
+| [`devrites-upgrade-planner`](../pack/.claude/agents/devrites-upgrade-planner.md) | Read an old workspace from scratch, classify semantic contract gaps, and return a bounded upgrade plan without changing files. |
 | [`devrites-strategy-reviewer`](../pack/.claude/agents/devrites-strategy-reviewer.md) | **Pre-plan** spec-vs-rubric strategic review (ambition / scope / premise / pre-mortem / YAGNI / testability / irreversibility / cross-cutting / convention). Used by `/rite-temper`, not the seal fan-out. |
 | [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md) | **Pre-build** plan-vs-rubric engineering review (architecture / scope-reuse / plan code-quality / test-coverage design / performance / reversibility / failure-mode coverage), confidence-banded with a quote-the-source verification gate. Used by `/rite-vet`, not the seal fan-out. |
 | [`devrites-forge-judge`](../pack/.claude/agents/devrites-forge-judge.md) | **Build-time** comparative judge of two or three candidate builds of one slice (acceptance / test strength / principle fit / simplicity / reuse / anti-slop). Used by `/rite-build` on a `Forge: yes` slice; picks the single winner to land and names grafts. |

package/docs/usage.md

@@ -5,7 +5,9 @@ These examples cover the common DevRites workflows. Start a new feature with
 `/rite-quick` and `/rite-frame` handle bounded work outside the full feature
 lifecycle. Workspace phases first read the active workspace from
 `.devrites/ACTIVE` and `.devrites/work/<slug>/`. If none exists, they report the
-command that can create or select one.
+command that can create or select one. `/rite-upgrade [slug]` is the
+conditional maintenance route for an active workspace planned under older
+DevRites rules.
 
 - **Full command reference** → [`command-map.md`](command-map.md)
 - **Flow diagrams** → [`flow.md`](flow.md)
@@ -24,7 +26,7 @@ the work across compaction and new sessions:
 | `README.md` / `index.md` / `feature.md` | `/rite-spec` | compact workspace map: phase, status, next action, artifact map, read-next table, gates |
 | `brief.md` | `/rite-spec` | one-line objective + definition of done |
 | `spec.md` | `/rite-spec` | product WHAT/WHY, requirements, acceptance, boundaries, measurable success |
-| `decision-coverage.md` | `/rite-clarify` | topology-first coverage plus semantic `CLEAR` verdict bound to all decision inputs |
+| `decision-coverage.md` | `/rite-clarify` | topology-first coverage plus semantic `CLEAR` verdict bound to all decision inputs and the current readiness-artifact contract |
 | `architecture.md` | `/rite-define` | owning module/layer, integration points, data/API/events, dependencies, risks |
 | `flows.md` | `/rite-spec` or `/rite-define` | optional Mermaid diagrams when sequence/state/data flow clarifies behavior |
 | `references/` + `references.md` | `/rite-spec` | saved design refs: screenshots, Figma, video, links |
@@ -32,8 +34,8 @@ the work across compaction and new sessions:
 | `plan.md` | `/rite-define` | approach, dependency graph, checkpoints, rollback |
 | `tasks.md` | `/rite-define` | ordered `SLICE-###` vertical slices, each mapped to `AC-###` and tagged `Mode: AFK \| HITL` + gate fields |
 | `traceability.md` | `/rite-define` | AC/REQ → slices → tests/proofs → evidence → touched files matrix |
-| `eng-review.md` | `/rite-vet` | mandatory engineering review with semantic, input-digest-bound readiness verdict |
-| `test-plan.md` | `/rite-vet` | build-readable coverage target: coverage diagram, per-gap test requirements, acceptance→test map (read by `/rite-build` + `/rite-prove`) |
+| `eng-review.md` | `/rite-vet` | mandatory engineering review with semantic, input-digest-bound readiness verdict and readiness-artifact contract |
+| `test-plan.md` | `/rite-vet` | build-readable coverage target and readiness-artifact contract: coverage diagram, per-gap test requirements, acceptance→test map (read by `/rite-build` + `/rite-prove`) |
 | `state.md` | every phase | working cursor: phase, status, next action, slice, AFK budget, durable clarification return fields, and `Awaiting human` only when paused |
 | `recovery-attempts.jsonl` | technical recovery | durable three-failure budget per root-cause fingerprint |
 | `.wright-allowlist` | `/rite-build` root | exact normalized source/test paths the sole wright may change |
@@ -62,7 +64,10 @@ deleting the old files. `feature.md`/`index.md` can still act as the workspace
 map, `status.md` as the cursor alias for `state.md`, and `proof.md` as the proof
 alias for `evidence.md`. Workspace maps use schema v2; migration upgrades
 compatible declarations but never fabricates clarification, readiness, or proof
-evidence.
+evidence. That structural schema is separate from the semantic planning
+contract. `/rite-upgrade` reconciles active unfinished planning with
+`devrites.readiness-artifacts.v2`; it does not rewrite current, completed, or
+archived workspaces.
 
 Project-root sentinel (outside the workspace):
 
@@ -124,6 +129,27 @@ original baseline. A retry snapshot refreshes only the dispatch boundary.
 `/rite-seal` **decides**; `/rite-ship` **executes + closes**. To run the whole
 sequence unattended, see `/rite-autocomplete` (§11).
 
+## 2a) Continue a workspace planned under older rules
+
+Run the upgrade after updating DevRites when build readiness reports code `8`,
+or invoke it directly for an older active workspace:
+
+```text
+/rite-upgrade ark-panda-redesign
+  → a fresh read-only devrites-upgrade-planner compares the active unfinished
+    planning surface with devrites.readiness-artifacts.v2
+  → completed source, slices, decisions, and evidence stay unchanged
+  → stale old-engine proof recipes and machine-local command wrappers leave the
+    active canonical plan
+  → current coverage and engineering-readiness gates run again
+  → an already-current workspace that passes readiness is a no-op; completed
+    workspaces and archives are also left alone
+```
+
+This is not the same as `devrites-engine update`, which refreshes the installed
+engine and pack, or `devrites-engine migrate`, which normalizes workspace layout
+and structural state schema.
+
 ## 3) Spec drift mid-build
 
 ```text