devrites 3.1.0 → 3.2.0

package/pack/generated/codex/skills/rite-upgrade/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: rite-upgrade
+description: User-invoked semantic upgrade for an active legacy DevRites workspace. Reconciles unfinished planning with the installed workflow contract while preserving completed work and history.
+argument-hint: "[feature-slug]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+## Codex compatibility
+
+This is the Codex mirror of a DevRites skill. In Codex:
+
+- Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
+- Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
+- **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
+- For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
+- If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
+- Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
+- If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
+- Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
+- Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
+- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
+
+
+# $rite-upgrade: bring an active workspace onto the current contract
+
+Use this when a workspace created under older DevRites rules cannot safely continue with
+the installed pack. It reconciles the workspace to the current desired state; it does not
+replay a chain of release-specific scripts. Structural `devrites-engine migrate` remains a
+separate first step.
+
+Current semantic contract: `devrites.readiness-artifacts.v2`.
+
+## Rules consulted
+
+Read `devrites-lib/reference/standards/core.md`,
+`devrites-lib/reference/standards/agents.md`,
+`devrites-lib/reference/workspace-artifact-schema.md`, and the current Clarify, Define,
+Plan, Vet, Converge, and Build phase contracts needed by the assessment.
+
+## Invariants
+
+- Never edit application source, tests, dependencies, Git state, or historical evidence.
+- Preserve completed-slice identity, status, acceptance, dependencies, historical proof,
+  answered questions, and `touched-files.md`.
+- Reassess only unfinished planning. Archived or `done` workspaces are a no-op.
+- Never downgrade a workspace that names a future semantic contract.
+- This is a recovery command, not a lifecycle phase; never write `Phase: upgrade`.
+- Durable plans contain portable repository commands, not RTK/local aliases, user-specific
+  absolute paths, or temporary proof trees. Runtime packets may name an execution adapter;
+  evidence may record both logical and executed forms.
+- Ask at most one coherent question, and only for product, policy, irreversible risk, or
+  human-only access/action. Retry and repair authorization is agent-owned.
+- The explicit `$rite-upgrade` invocation authorizes the bounded workspace reconciliation.
+  The root remains the only canonical writer.
+
+## Workflow
+
+0. **Orient and normalize structure.** Read the active slug or `$ARGUMENTS`. Run:
+   ```bash
+   devrites-engine doctor --verbose; echo "doctor rc=$?"
+   ```
+   A binary/pack integrity mismatch stops at `$rite-doctor`; do not run migration or
+   mutate semantic artifacts. Once healthy, orient without writing:
+   ```bash
+   devrites-engine preamble [feature-slug]
+   devrites-engine snapshot [feature-slug]
+   ```
+   A missing workspace stops at `$rite-spec`; an archived or `Status: done` workspace is
+   a no-op. For an active healthy workspace, run:
+   ```bash
+   devrites-engine migrate
+   devrites-engine preamble [feature-slug]
+   devrites-engine snapshot [feature-slug]
+   ```
+   If every semantic artifact names the current contract and `build-readiness` passes,
+   report a no-op.
+1. **Freeze the preservation baseline.** Create the standard orchestrator-controlled
+   `agent-packet/v1` baseline. Include exact paths for current phase/artifact contracts,
+   `state.md`, `spec.md`, `decision-coverage.md`, `architecture.md`, `plan.md`, `tasks.md`,
+   `traceability.md`, `test-plan.md`, `eng-review.md`, `questions.md`, `decisions.md`,
+   `assumptions.md`, `drift.md`, `evidence.md`, and `touched-files.md` when present. Record
+   the source diff identity plus the protected identity/status/acceptance/dependency
+   fields for every completed slice and each preserved artifact identity. Freeze the
+   workspace while it is assessed.
+2. **Classify from fresh context.** Dispatch `devrites-upgrade-planner` with objective
+   `reconcile this workspace with devrites.readiness-artifacts.v2`, the exact baseline,
+   and budgets `25 files / 2,000 loaded lines / 180 result lines`. Require one validated
+   `upgrade-assessment`. The agent writes nothing and asks nothing.
+3. **Reconcile ownership.** Reject stale, malformed, or preservation-breaking advice.
+   Dispatch `devrites-evidence-scout` only for a bounded missing fact. Drop an open
+   retry/tool-repair question with `devrites-engine resolve --drop <qid>
+   "superseded by explicit semantic upgrade; agent-owned recovery"` and continue. Keep a
+   genuine existing human gate intact; if a newly discovered human-owned choice is
+   unavoidable, persist one option packet and stop.
+4. **Apply current desired state in the root.**
+   - Remove obsolete old-engine reconstruction, old workflow hashes, temporary proof
+     recipes, and host-local wrappers from active `plan.md`, `tasks.md`, and
+     `test-plan.md`. Keep historical evidence unchanged.
+   - Re-run Clarify against unfinished intent until `Decision coverage: CLEAR`; it writes
+     exactly one `DevRites contract: devrites.readiness-artifacts.v2` field. Do not stamp a
+     marker over stale content.
+   - Re-run Temper only where unfinished scope still needs strategic review.
+   - For unstarted planning, use the current Define contract. When active planning needs
+     normalization, dispatch `devrites-plan-drafter` in repair mode and reconcile only
+     pending slices. Preserve all completed slices without changing their protected fields.
+     For all-built active work, normalize only gate-required planning fields. Use Converge
+     only when live code and recorded intent genuinely differ.
+   - Invalidate stale engineering readiness after any planning edit. Run the full current
+     Vet contract, including its fresh plan reviewer, portable proof commands, preflight,
+     and digest refresh. Vet writes exactly one current contract field to `test-plan.md`
+     and `eng-review.md`.
+5. **Verify preservation and readiness.** Recompute the frozen source diff, every protected
+   completed-slice field, `evidence.md`, answered-question records, and `touched-files.md`;
+   any mismatch is a hard stop and must be restored before proceeding. Then run:
+   ```bash
+   devrites-engine build-readiness [feature-slug]; echo "readiness rc=$?"
+   ```
+   Follow the gate's current route for `2` through `7`; `8` means the semantic
+   reconciliation is still incomplete. Finish only at `0`. Preserve the original active
+   build cursor when it still names the next pending slice; otherwise use the current
+   deterministic next action.
+6. **STOP.** Do not start Build. A second `$rite-upgrade` must take the current-contract
+   no-op path.
+
+## Output
+
+Run `devrites-engine progress`, then use the shared completion reply contract in
+`devrites-lib/reference/reply-contract.md`:
+
+```text
+Done: workspace <slug> upgraded to devrites.readiness-artifacts.v2.
+Changed: <active planning artifacts only | none; already current>
+Evidence: build-readiness rc=0; source/completed slices/history preserved
+Open: <none | one genuine human gate>
+Next: <snapshot next command>
+Record: .devrites/work/<slug>/state.md
+↻ Hygiene: /clear before the next lifecycle step
+```
+
+On a no-op, say so and keep the snapshot's current next command.

package/pack/generated/codex/skills/rite-upgrade/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pack/generated/codex/skills/rite-vet/SKILL.md

@@ -126,7 +126,9 @@ Pull the standard named by the active axis: `principles.md`, `patterns.md`,
    ```
    Completion: every scenario and acceptance criterion maps to planned proof, every slice is
    one-pass implementable, the Build-entry preflight is green or names an owned prerequisite,
-   and developer-facing plans have a predicted `devex.md` scorecard.
+   and developer-facing plans have a predicted `devex.md` scorecard. Durable proof commands
+   are portable repository commands; host-local wrappers belong only in runtime packets and
+   recorded execution evidence.
 4a. **Forge gate.** `$rite-define` leaves `no` / `none` / `none`; Vet alone promotes under
    [`rite-build/reference/forge.md`](../rite-build/reference/forge.md). Require a costly
    unresolved architecture fork, 2–3 distinct complete contiguous `A`–`C` strategies, every
@@ -149,7 +151,9 @@ Pull the standard named by the active axis: `principles.md`, `patterns.md`,
    devrites-engine analyze; echo "final analyze rc=$?"
    ```
    Any non-zero result blocks the handoff. Then update `state.md`:
-   write one typed field to `eng-review.md`: `Implementation readiness: READY`,
+   write exactly one `DevRites contract: devrites.readiness-artifacts.v2` field to both
+   `test-plan.md` and `eng-review.md`, plus one typed field to `eng-review.md`:
+   `Implementation readiness: READY`,
    `NEEDS CLARIFICATION`, or `NEEDS REPLAN`. Only READY sets `Phase: vet` and
    `Next step: $rite-build`, after a final sweep leaves no foreseeable human choice except a
    justified action-time checkpoint. Technical failure records its reproduction and

package/pack/generated/codex/skills/rite-vet/reference/artifacts.md

@@ -10,6 +10,7 @@ clobber.
 ```markdown
 # Eng review: <slug>
 Vetted: <iso>   Cross-model: ran (codex) | off
+DevRites contract: devrites.readiness-artifacts.v2
 Implementation readiness: <READY | NEEDS CLARIFICATION | NEEDS REPLAN>
 Readiness inputs SHA-256: <exact value from `devrites-engine readiness-digest engineering <slug>`>
 
@@ -74,6 +75,7 @@ test and where*, not implementation detail.
 ```markdown
 # Test plan: <slug>
 From $rite-vet on <iso>. Runner + conventions: <detected framework + command>.
+DevRites contract: devrites.readiness-artifacts.v2
 
 ## Build-entry preflight
 | Gate | Command | Cwd | Expected | Prerequisites | Provenance to recapture |
@@ -83,6 +85,10 @@ From $rite-vet on <iso>. Runner + conventions: <detected framework + command>.
 Link any disposable parser fixture. Build evidence recomputes every digest; preflight values
 are not post-build proof.
 
+Commands in this durable artifact are portable repository commands: no RTK or local shell
+aliases, user-specific absolute paths, or temporary proof trees. A runtime packet may name
+an execution adapter, and evidence may record the portable and executed forms.
+
 ## Coverage diagram
 <the ASCII code-paths + user-flows diagram from review-axes.md, with COVERAGE / GAPS / REGRESSIONS line>
 
@@ -163,6 +169,8 @@ acceptance/behavior changes route through the **Spec Drift Guard**.
   `devrites-engine readiness-digest coverage <slug>` and replace the complete
   `Coverage inputs SHA-256` line in `decision-coverage.md`. Only then run
   `devrites-engine readiness-digest engineering <slug>` and copy its complete
-  field line into `eng-review.md`. The build gate rejects a stale digest,
+  field line into `eng-review.md`. Write
+  `DevRites contract: devrites.readiness-artifacts.v2` exactly once in both artifacts
+  only after their current-contract review is complete. The build gate rejects a stale digest,
   placeholders, non-passing preflight/readiness rows, empty tables, or an
   acceptance criterion with no test mapping.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "DevRites: a disciplined senior-engineer workflow pack for Claude Code and Codex",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",

package/scripts/run-outcome-evals.sh

@@ -83,11 +83,13 @@ stage_workspace() {
   mkdir -p "$ws"
   cp -R "$GOOD/." "$ws/"
   if [ "$mode" = "readiness" ]; then
-    python3 - "$ws/state.md" <<'PY'
+    python3 - "$ws" "$READINESS" <<'PY'
 from pathlib import Path
+import json
 import sys
 
-path = Path(sys.argv[1])
+workspace, contract_path = map(Path, sys.argv[1:])
+path = workspace / "state.md"
 text = path.read_text()
 for old, new in (
     ("| phase | done |", "| phase | build |"),
@@ -97,6 +99,35 @@ for old, new in (
         raise SystemExit(f"{path}: expected exactly one {old!r}")
     text = text.replace(old, new)
 path.write_text(text)
+
+contract = json.loads(contract_path.read_text())
+field = contract["contractField"]
+declaration = f"{field}: {contract['schema']}"
+for name in ("decision-coverage.md", "test-plan.md", "eng-review.md"):
+    artifact = workspace / name
+    lines = [
+        line for line in artifact.read_text().splitlines()
+        if not line.startswith(f"{field}:")
+    ]
+    lines[1:1] = ["", declaration]
+    artifact.write_text("\n".join(lines) + "\n")
+PY
+    local engineering_digest
+    engineering_digest="$(
+      env DEVRITES_ROOT="$project" "$ENGINE" readiness-digest engineering "$slug"
+    )"
+    python3 - "$ws/eng-review.md" "$engineering_digest" <<'PY'
+from pathlib import Path
+import sys
+
+path = Path(sys.argv[1])
+field = sys.argv[2]
+lines = path.read_text().splitlines()
+matches = [i for i, line in enumerate(lines) if line.startswith("Readiness inputs SHA-256:")]
+if len(matches) != 1:
+    raise SystemExit(f"{path}: expected exactly one engineering digest")
+lines[matches[0]] = field
+path.write_text("\n".join(lines) + "\n")
 PY
   fi