devrites 3.0.7 → 3.1.0

package/scripts/grade-feature.sh

@@ -1,27 +1,25 @@
 #!/usr/bin/env bash
-# Deterministic OUTCOME grader for a finished DevRites feature workspace.
+# Deterministic outcome grader for a completed DevRites feature workspace.
 #
-# The trigger evals (evals/*.json) test whether the right SKILL *fires*. This
-# grades whether a finished run reached a *shippable* state: the
-# product claim DevRites sells ("won't claim done without proof"). It reads only
-# committed Markdown artifacts (no API key, no Claude Code harness), so it runs
-# in CI against a golden fixture and is the kind of deterministic grader
-# Anthropic's eval guidance recommends for coding agents.
+# Trigger evals in evals/*.json check skill selection. This script checks
+# whether a completed run is shippable and has proof. It reads only committed
+# Markdown artifacts, so CI can grade a golden fixture without an API key or
+# model harness.
 #
-# Live evidence-freshness (mtime: does proof post-date code?) is NOT graded here
-#: git fixtures don't preserve mtimes; that gate is enforced on a live
-# workspace by the `devrites-engine evidence-fresh` engine gate.
+# Git fixtures do not preserve the mtimes needed to compare proof with code.
+# The `devrites-engine evidence-fresh` gate performs that check in a live
+# workspace.
 #
-# Usage: grade-feature.sh <workspace-dir>
+# Usage: grade-feature.sh [--json] <workspace-dir>
 #   e.g. evals/golden/shippable-feature | .devrites/work/<slug> | .devrites/archive/<slug>
 #
-# Invariants (from rite-seal/reference/{seal-template,go-no-go,final-evidence}.md):
+# Checks from rite-seal/reference/{seal-template,go-no-go,final-evidence}.md:
 #   1. seal.md present with "Verdict: GO" (not NO-GO)
 #   2. seal.md "## Acceptance Criteria" has no unchecked "- [ ]" item
 #   3. seal.md "## Blockers" is empty / "none"
 #   4. evidence.md present and non-empty
 #   5. review.md present
-#   6. questions.md has no entry with gate: validating + status: open (NO-GO by definition)
+#   6. questions.md has no open question (later lifecycle phases block them)
 #   7. state.md Phase in {seal, ship, done}; Status not awaiting_human / blocked
 #
 # Exit codes: 0 shippable; 1 one or more invariants failed; 2 bad usage.
@@ -29,24 +27,41 @@
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+json=0
+if [ "${1:-}" = "--json" ]; then
+  json=1
+  shift
+fi
 ws="${1:-}"
-if [ -z "$ws" ] || [ ! -d "$ws" ]; then
-  printf 'usage: grade-feature.sh <workspace-dir>\n' >&2
+if [ "$#" -ne 1 ] || [ ! -d "$ws" ]; then
+  printf 'usage: grade-feature.sh [--json] <workspace-dir>\n' >&2
   exit 2
 fi
 
 seal="$ws/seal.md"; ev="$ws/evidence.md"; rev="$ws/review.md"
 q="$ws/questions.md"; st="$ws/state.md"
 problems=()
+rules=()
+unchecked=0
+acceptance_ready=0
+
+add_problem() {
+  rules+=("$1")
+  problems+=("$2")
+}
 
-# 1 / 2 / 3: seal verdict, acceptance, blockers
+# Checks 1 through 3: seal verdict, acceptance, and blockers.
 if [ ! -f "$seal" ]; then
-  problems+=("seal.md missing: feature never sealed")
+  add_problem "final.seal.missing" "seal.md missing: feature never sealed"
 else
   grep -qiE '^[[:space:]]*Verdict:[[:space:]]*GO[[:space:]]*$' "$seal" \
-    || problems+=("seal.md Verdict is not GO")
+    || add_problem "final.verdict.not-go" "seal.md Verdict is not GO"
   unchecked=$(awk '/^## /{insec=($0 ~ /^## Acceptance Criteria/)} insec && /^- \[ \]/{c++} END{print c+0}' "$seal")
-  [ "${unchecked:-0}" -gt 0 ] && problems+=("seal.md has ${unchecked} unchecked acceptance criterion(s)")
+  if [ "${unchecked:-0}" -gt 0 ]; then
+    add_problem "final.acceptance.unchecked" "seal.md has ${unchecked} unchecked acceptance criterion(s)"
+  else
+    acceptance_ready=1
+  fi
   if awk '
       /^## /{ insec=($0 ~ /^## Blockers/); next }
       insec { l=$0; gsub(/^[[:space:]]+|[[:space:]]+$/,"",l)
@@ -54,40 +69,75 @@ else
               ll=tolower(l); if (ll ~ /^-?[[:space:]]*(none|n\/a)$/) next
               nz=1 }
       END { exit(nz?0:1) }' "$seal"; then
-    problems+=("seal.md lists unresolved blockers")
+    add_problem "final.blockers.unresolved" "seal.md lists unresolved blockers"
   fi
 fi
 
-# 4: evidence
-{ [ -f "$ev" ] && [ -s "$ev" ]; } || problems+=("evidence.md missing or empty: acceptance unproven")
+# Check 4: evidence.
+{ [ -f "$ev" ] && [ -s "$ev" ]; } \
+  || add_problem "final.evidence.missing-or-empty" "evidence.md missing or empty: acceptance unproven"
 
-# 5: review
-[ -f "$rev" ] || problems+=("review.md missing: feature not reviewed")
+# Check 5: review.
+[ -f "$rev" ] || add_problem "final.review.missing" "review.md missing: feature not reviewed"
 
-# 6: open validating gate (merge-blocking by definition)
+# Check 6: open questions block sealing.
 if [ -f "$q" ]; then
-  if awk '
-      /^## q-/{ if(inq && s=="open" && g=="validating") bad=1; inq=1; s=""; g=""; next }
-      inq && /^status:/{ v=$0; sub(/^status:[[:space:]]*/,"",v); s=v }
-      inq && /^gate:/  { v=$0; sub(/^gate:[[:space:]]*/,"",v);   g=v }
-      END{ if(inq && s=="open" && g=="validating") bad=1; exit(bad?0:1) }' "$q"; then
-    problems+=("open 'gate: validating' question: merge-blocking by definition (NO-GO)")
+  if python3 - "$q" <<'PY'
+from pathlib import Path
+import sys
+
+lines = Path(sys.argv[1]).read_text().splitlines()
+in_question = False
+status = ""
+for line in lines:
+    stripped = line.strip()
+    if stripped.startswith("## "):
+        if in_question and status.lower() == "open":
+            raise SystemExit(0)
+        in_question = stripped[3:].lower().startswith("q-")
+        status = ""
+    elif in_question and stripped.lower().startswith("status:"):
+        status = stripped.split(":", 1)[1].strip()
+if in_question and status.lower() == "open":
+    raise SystemExit(0)
+
+status_index = None
+for line in lines:
+    stripped = line.strip()
+    if not (stripped.startswith("|") and stripped.endswith("|")):
+        status_index = None
+        continue
+    cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+    lowered = [cell.lower() for cell in cells]
+    if status_index is None:
+        status_index = lowered.index("status") if "status" in lowered else None
+        continue
+    if status_index < len(cells) and cells[status_index].lower() == "open":
+        raise SystemExit(0)
+raise SystemExit(1)
+PY
+  then
+    add_problem "final.questions.open" "questions.md contains an open question"
   fi
 fi
 
-# 7: state phase / status
+# Check 7: state phase and status.
 if [ -f "$st" ]; then
   ph="$(python3 "$ROOT/scripts/workflow_schema.py" field "$st" phase 2>/dev/null || true)"
   stt="$(python3 "$ROOT/scripts/workflow_schema.py" field "$st" status 2>/dev/null || true)"
-  if ! python3 "$ROOT/scripts/workflow_schema.py" phase-property "$ph" shippable; then
-    problems+=("state.md Phase='${ph}' (expected a shippable phase)")
+  if ! python3 "$ROOT/scripts/workflow_schema.py" phase-property "$ph" shippable >/dev/null; then
+    add_problem "final.state.phase" "state.md Phase='${ph}' (expected a shippable phase)"
   fi
-  case "$stt" in awaiting_human|blocked) problems+=("state.md Status='${stt}' (not shippable)") ;; esac
+  case "$stt" in
+    awaiting_human|blocked)
+      add_problem "final.state.status" "state.md Status='${stt}' (not shippable)"
+      ;;
+  esac
 else
-  problems+=("state.md missing")
+  add_problem "final.state.missing" "state.md missing"
 fi
 
-# 8: executable acceptance criteria: every spec [ACn] proven + checked in seal
+# Check 8: every spec [ACn] is proven and checked in the seal.
 run_acceptance_check() {
   if [ -n "${DEVRITES_CLI:-}" ]; then
     "$DEVRITES_CLI" check-acceptance "$ws"
@@ -109,13 +159,44 @@ run_acceptance_check() {
   return 127
 }
 
-if ! acout=$(run_acceptance_check 2>&1); then
-  problems+=("acceptance: $(printf '%s' "$acout" | tail -1 | sed 's/^check-acceptance: //')")
+if [ "$acceptance_ready" -eq 1 ] && ! acout=$(run_acceptance_check 2>&1); then
+  add_problem "final.acceptance.ids" \
+    "acceptance: $(printf '%s' "$acout" | tail -1 | sed 's/^check-acceptance: //')"
 fi
 
 slug="$(basename "$ws")"
+if [ "$json" -eq 1 ]; then
+  status="GO"
+  [ "${#problems[@]}" -gt 0 ] && status="NO-GO"
+  pairs=()
+  for ((i = 0; i < ${#problems[@]}; i++)); do
+    pairs+=("${rules[$i]}" "${problems[$i]}")
+  done
+  python3 - "$slug" "$status" "${pairs[@]}" <<'PY'
+import json
+import sys
+
+slug, status, *pairs = sys.argv[1:]
+items = [
+    {"rule_id": pairs[i], "message": pairs[i + 1]}
+    for i in range(0, len(pairs), 2)
+]
+print(json.dumps({
+    "schema": "devrites-outcome-grade/v1",
+    "workspace": slug,
+    "status": status,
+    "rule_ids": [item["rule_id"] for item in items],
+    "problems": items,
+}, separators=(",", ":")))
+PY
+  if [ "${#problems[@]}" -eq 0 ]; then
+    exit 0
+  fi
+  exit 1
+fi
+
 if [ "${#problems[@]}" -eq 0 ]; then
-  printf 'GO    %s: shippable: sealed GO, acceptance proven, no blockers, no open validating gate.\n' "$slug"
+  printf 'GO    %s: shippable: sealed GO, acceptance proven, no blockers, no open question.\n' "$slug"
   exit 0
 fi
 printf 'NO-GO %s: %d blocker(s):\n' "$slug" "${#problems[@]}"

package/scripts/live-hosts/agent-result.schema.json

@@ -0,0 +1,230 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "result_version",
+    "run_id",
+    "cell_id",
+    "host",
+    "role",
+    "status",
+    "baseline_id",
+    "scope_id",
+    "budget",
+    "side_effects",
+    "payload_type",
+    "execution",
+    "signals",
+    "usage",
+    "dispatch_reason_id",
+    "result_reason_id",
+    "outcome",
+    "terminal_sentinel",
+    "host_version",
+    "model"
+  ],
+  "properties": {
+    "result_version": {
+      "const": "agent-result/v1"
+    },
+    "run_id": {
+      "type": "string",
+      "pattern": "^drv-run-v1:[0-9a-f]{32}$"
+    },
+    "cell_id": {
+      "type": "string"
+    },
+    "host": {
+      "enum": [
+        "claude",
+        "codex"
+      ]
+    },
+    "role": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "complete",
+        "partial",
+        "blocked",
+        "failed"
+      ]
+    },
+    "baseline_id": {
+      "type": "string"
+    },
+    "scope_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "files_used",
+        "loaded_lines_used",
+        "result_lines_used"
+      ],
+      "properties": {
+        "files_used": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "loaded_lines_used": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "result_lines_used": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "side_effects": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "repo_writes",
+        "scratch_write_count"
+      ],
+      "properties": {
+        "repo_writes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "path",
+              "kind",
+              "sha256"
+            ],
+            "properties": {
+              "path": {
+                "type": "string"
+              },
+              "kind": {
+                "enum": [
+                  "file",
+                  "symlink",
+                  "deleted"
+                ]
+              },
+              "sha256": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$"
+              }
+            }
+          }
+        },
+        "scratch_write_count": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "payload_type": {
+      "enum": [
+        "review-findings",
+        "wright-report"
+      ]
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode",
+        "guard_strength",
+        "independence"
+      ],
+      "properties": {
+        "mode": {
+          "enum": [
+            "named",
+            "generic",
+            "inline"
+          ]
+        },
+        "guard_strength": {
+          "enum": [
+            "enforced",
+            "observed",
+            "unavailable",
+            "bypassed"
+          ]
+        },
+        "independence": {
+          "type": "boolean"
+        }
+      }
+    },
+    "signals": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "usage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "input_tokens",
+        "output_tokens",
+        "cost_usd",
+        "cost_provenance"
+      ],
+      "properties": {
+        "input_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "output_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "cost_usd": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[0-9]+(\\.[0-9]+)?$"
+        },
+        "cost_provenance": {
+          "enum": [
+            "provider-reported",
+            "unavailable"
+          ]
+        }
+      }
+    },
+    "dispatch_reason_id": {
+      "type": "string",
+      "pattern": "^DRV-[A-Z0-9-]+$"
+    },
+    "result_reason_id": {
+      "type": "string",
+      "pattern": "^DRV-[A-Z0-9-]+$"
+    },
+    "outcome": {
+      "enum": [
+        "passed",
+        "denied",
+        "unavailable"
+      ]
+    },
+    "terminal_sentinel": {
+      "enum": [
+        "complete",
+        "interrupted"
+      ]
+    },
+    "host_version": {
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    }
+  }
+}

package/scripts/live-hosts/claude.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck disable=SC1091
+source "$DIR/common.sh"
+CONTRACT_HELPER="$DIR/host-transport.py"
+
+case "${1:-}" in
+  version)
+    contract_version claude
+    ;;
+  run)
+    ;;
+  *)
+    contract_die "expected version or run"
+    ;;
+esac
+
+contract_prepare_run
+if [ -n "${DEVRITES_CONTRACT_FAKE_HOST:-}" ]; then
+  contract_run_fake
+fi
+contract_read_auth
+actual_version="$(env -i "PATH=$PATH" "LANG=C" "LC_ALL=C" claude --version 2>/dev/null)" \
+  || contract_die "Claude version preflight failed"
+[ "$actual_version" = "$DEVRITES_CONTRACT_HOST_VERSION_PIN" ] \
+  || contract_die "Claude version pin changed"
+
+simulate="$(python3 "$CONTRACT_HELPER" field simulate)"
+role_class="$(python3 "$CONTRACT_HELPER" field role_class)"
+tools="Agent,Read,Glob,Grep"
+if [ "$role_class" = "wright" ]; then
+  tools="$tools,Edit,Write,Bash"
+fi
+if [ "$simulate" = "inline-fallback" ]; then
+  tools="Read,Glob,Grep"
+fi
+schema="$(cat "$DIR/agent-result.schema.json")"
+mkdir -p "$XDG_CONFIG_HOME/claude"
+
+trap 'contract_interrupt_result; exit 130' INT TERM
+cd "$DEVRITES_ROOT"
+set +e
+env -i \
+  "PATH=$PATH" "LANG=C" "LC_ALL=C" "PYTHONDONTWRITEBYTECODE=1" \
+  "DEVRITES_CONTRACT_PACKET=$DEVRITES_CONTRACT_PACKET" \
+  python3 "$CONTRACT_HELPER" render |
+  env -i \
+    "PATH=$PATH" "LANG=C" "LC_ALL=C" \
+    "HOME=$HOME" "TMPDIR=$TMPDIR" \
+    "XDG_CONFIG_HOME=$XDG_CONFIG_HOME" "XDG_STATE_HOME=$XDG_STATE_HOME" \
+    "CLAUDE_CONFIG_DIR=$XDG_CONFIG_HOME/claude" \
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1" \
+    "ANTHROPIC_API_KEY=$CONTRACT_AUTH_VALUE" \
+    "DEVRITES_ROOT=$DEVRITES_ROOT" \
+    "DEVRITES_AGENT_SCRATCH=$DEVRITES_AGENT_SCRATCH" \
+    "DEVRITES_RUN_ID=$DEVRITES_RUN_ID" \
+    claude -p \
+      --output-format json \
+      --json-schema "$schema" \
+      --model "$DEVRITES_CONTRACT_MODEL" \
+      --max-budget-usd "$DEVRITES_CONTRACT_MAX_COST_USD" \
+      --permission-mode dontAsk \
+      --tools "$tools" \
+      --setting-sources project \
+      --settings '{}' \
+      --strict-mcp-config \
+      --mcp-config '{"mcpServers":{}}' \
+      --no-chrome \
+      --no-session-persistence |
+  env -i \
+    "PATH=$PATH" "LANG=C" "LC_ALL=C" "PYTHONDONTWRITEBYTECODE=1" \
+    "DEVRITES_CONTRACT_PACKET=$DEVRITES_CONTRACT_PACKET" \
+    "DEVRITES_CONTRACT_RESULT=$DEVRITES_CONTRACT_RESULT" \
+    "DEVRITES_CONTRACT_HOST_VERSION_PIN=$DEVRITES_CONTRACT_HOST_VERSION_PIN" \
+    "DEVRITES_CONTRACT_MODEL=$DEVRITES_CONTRACT_MODEL" \
+    python3 "$CONTRACT_HELPER" normalize
+pipeline=("${PIPESTATUS[@]}")
+set -e
+host_rc="${pipeline[1]:-2}"
+normalize_rc="${pipeline[2]:-2}"
+[ "$normalize_rc" -eq 0 ] || exit 2
+if [ "$host_rc" -eq 130 ]; then
+  contract_interrupt_result
+fi
+exit "$host_rc"

package/scripts/live-hosts/codex.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# shellcheck disable=SC1091
+source "$DIR/common.sh"
+CONTRACT_HELPER="$DIR/host-transport.py"
+
+case "${1:-}" in
+  version)
+    contract_version codex
+    ;;
+  run)
+    ;;
+  *)
+    contract_die "expected version or run"
+    ;;
+esac
+
+contract_prepare_run
+if [ -n "${DEVRITES_CONTRACT_FAKE_HOST:-}" ]; then
+  contract_run_fake
+fi
+contract_read_auth
+actual_version="$(env -i "PATH=$PATH" "LANG=C" "LC_ALL=C" codex --version 2>/dev/null)" \
+  || contract_die "Codex version preflight failed"
+[ "$actual_version" = "$DEVRITES_CONTRACT_HOST_VERSION_PIN" ] \
+  || contract_die "Codex version pin changed"
+
+role_class="$(python3 "$CONTRACT_HELPER" field role_class)"
+sandbox="read-only"
+if [ "$role_class" = "wright" ]; then
+  sandbox="workspace-write"
+fi
+mkdir -p "$XDG_CONFIG_HOME/codex"
+
+trap 'contract_interrupt_result; exit 130' INT TERM
+cd "$DEVRITES_ROOT"
+set +e
+env -i \
+  "PATH=$PATH" "LANG=C" "LC_ALL=C" "PYTHONDONTWRITEBYTECODE=1" \
+  "DEVRITES_CONTRACT_PACKET=$DEVRITES_CONTRACT_PACKET" \
+  python3 "$CONTRACT_HELPER" render |
+  env -i \
+    "PATH=$PATH" "LANG=C" "LC_ALL=C" \
+    "HOME=$HOME" "TMPDIR=$TMPDIR" \
+    "XDG_CONFIG_HOME=$XDG_CONFIG_HOME" "XDG_STATE_HOME=$XDG_STATE_HOME" \
+    "CODEX_HOME=$XDG_CONFIG_HOME/codex" \
+    "OPENAI_API_KEY=$CONTRACT_AUTH_VALUE" \
+    "DEVRITES_ROOT=$DEVRITES_ROOT" \
+    "DEVRITES_AGENT_SCRATCH=$DEVRITES_AGENT_SCRATCH" \
+    "DEVRITES_RUN_ID=$DEVRITES_RUN_ID" \
+    codex exec \
+      --json \
+      --ephemeral \
+      --strict-config \
+      --ignore-user-config \
+      --skip-git-repo-check \
+      --dangerously-bypass-hook-trust \
+      --sandbox "$sandbox" \
+      --model "$DEVRITES_CONTRACT_MODEL" \
+      --output-schema "$DIR/agent-result.schema.json" \
+      -c shell_environment_policy.inherit=none \
+      -C "$DEVRITES_ROOT" \
+      - |
+  env -i \
+    "PATH=$PATH" "LANG=C" "LC_ALL=C" "PYTHONDONTWRITEBYTECODE=1" \
+    "DEVRITES_CONTRACT_PACKET=$DEVRITES_CONTRACT_PACKET" \
+    "DEVRITES_CONTRACT_RESULT=$DEVRITES_CONTRACT_RESULT" \
+    "DEVRITES_CONTRACT_HOST_VERSION_PIN=$DEVRITES_CONTRACT_HOST_VERSION_PIN" \
+    "DEVRITES_CONTRACT_MODEL=$DEVRITES_CONTRACT_MODEL" \
+    python3 "$CONTRACT_HELPER" normalize
+pipeline=("${PIPESTATUS[@]}")
+set -e
+host_rc="${pipeline[1]:-2}"
+normalize_rc="${pipeline[2]:-2}"
+[ "$normalize_rc" -eq 0 ] || exit 2
+if [ "$host_rc" -eq 130 ]; then
+  contract_interrupt_result
+fi
+exit "$host_rc"