devlyn-cli 4.3.0 → 4.3.3

package/native/codex/.agents/plugins/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "devlyn-harness-v4-3-3",
+  "plugins": [
+    {
+      "name": "devlyn",
+      "source": {
+        "source": "local",
+        "path": "./plugins/devlyn"
+      }
+    }
+  ]
+}

package/native/codex/plugins/devlyn/.codex-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "devlyn",
+  "version": "4.3.3",
+  "description": "Devlyn harness skills",
+  "skills": "./skills/"
+}

package/native/codex/plugins/devlyn/skills/_shared/.ruff.toml

@@ -0,0 +1,2 @@
+# Vendored devlyn helpers are checked by devlyn's own validation.
+exclude = ["*"]

package/native/codex/plugins/devlyn/skills/_shared/adapters/claude.md

@@ -0,0 +1,15 @@
+# Claude adapter
+
+## Invocation
+
+A Claude executor starts as
+`claude -p "<prompt>" --dangerously-skip-permissions --add-dir "<common git dir>"`,
+where `<common git dir>` is `git rev-parse --path-format=absolute --git-common-dir`:
+a linked task worktree commits there.
+
+**Availability probe**: `command -v claude >/dev/null 2>&1`; record
+`claude --version` as evidence. The probe is necessary, not sufficient:
+`claude -p` needs network access to the Anthropic API, so in a network-denying
+sandbox (e.g. Codex CLI's default `workspace-write`) it fails even though the
+binary resolves. A drain blocks when the executor cannot start, and a task
+whose executor exits without a submission waits for the next drain.

package/native/codex/plugins/devlyn/skills/_shared/adapters/codex.md

@@ -0,0 +1,14 @@
+# Codex adapter
+
+## Invocation
+
+A Codex executor runs through `_shared/codex-monitored.sh`, never a raw or piped
+`codex exec`: `bash "$DEVLYN_SHARED_DIR/codex-monitored.sh" <arguments for codex exec> "<prompt>"`.
+The `workspace-write` sandbox keeps `.git` read-only, so an executor that commits adds as
+writable roots the common Git directory (`git rev-parse --path-format=absolute --git-common-dir`)
+plus, in a linked worktree, its own Git directory (`git rev-parse --path-format=absolute --git-dir`),
+listed exactly because the sandbox protects it even under a listed parent. It also
+denies network, which installing a new dependency needs:
+`-s workspace-write -c 'sandbox_workspace_write.writable_roots=["<git dir>","<worktree git dir>"]' -c 'sandbox_workspace_write.network_access=true'`.
+Deliver a multiline prompt as exact file bytes: set `DEVLYN_CODEX_PROMPT_FILE=<file>`
+and pass the sole prompt argument `-`.

package/native/codex/plugins/devlyn/skills/_shared/adapters/omp.md

@@ -0,0 +1,6 @@
+# oh-my-pi adapter
+
+executor: no
+
+Engine `omp`, the oh-my-pi CLI.
+Stub: model-call execution and failure handling have not been qualified.

package/native/codex/plugins/devlyn/skills/_shared/codex-monitored.sh

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+# codex-monitored.sh — run `codex exec` in a monitored shape that keeps the
+# outer claude -p API stream from going silent during long Codex calls.
+#
+# WHY (iter-0009, post iter-0006/0007/0008):
+#   • iter-0007 isolation proved a single foreground `codex exec` Bash dispatch
+#     can starve the outer API stream of bytes during a 10+ min run; Anthropic's
+#     byte-level idle watchdog fires (~300s) and kills the orchestrator.
+#   • iter-0008 saw the orchestrator pick `codex exec ... 2>&1 | tail -200` from
+#     its own pattern prior — `tail` on a pipe buffers until EOF, suppressing
+#     ALL bytes. Same starvation, amplified.
+#   • iter-0008 also documented codex 0.124.0 reads stdin as a `<stdin>` block
+#     when the prompt is passed as an arg AND stdin is open; without
+#     `< /dev/null` the call hangs indefinitely.
+#
+# WHAT THIS WRAPPER DOES:
+#   1. Refuses to run if stdout is a pipe. Piping wrapper output to text tools
+#      (tail/head/awk/sed/grep without --line-buffered) re-introduces the
+#      iter-0008 starvation mechanism — the downstream tool buffers until EOF
+#      and the outer claude -p byte-watchdog never sees bytes. Exits 64 with a
+#      clear message so the orchestrator can self-correct on retry.
+#      (Round 2 finding #1 fix: shim alone does not defeat `| tail`; the
+#      wrapper must reject the pipe shape directly.)
+#   2. Closes stdin unless DEVLYN_CODEX_PROMPT_FILE supplies the sole prompt.
+#   3. Streams codex stdout to OUR stdout line-by-line — the caller reads
+#      stdout as the Codex reply, so we MUST NOT swallow it (e.g.
+#      `tail -n 200`). codex stderr forwards to OUR stderr.
+#   4. Emits a `[codex-monitored] heartbeat` line every CODEX_MONITORED_HEARTBEAT
+#      seconds (default 30s) on STDERR while codex is alive. Heartbeat-on-stderr
+#      keeps the orchestrator's combined-output stream non-silent without
+#      polluting the codex-reply view of stdout.
+#   5. Forwards SIGTERM/SIGINT from the outer watchdog to the codex child so a
+#      timeout actually reaps codex (otherwise process group kill races with
+#      backgrounded codex).
+#   6. Preserves codex's exact exit code.
+#
+# USAGE:
+#   bash codex-monitored.sh -C <repo> -s read-only "<prompt>"
+#   bash codex-monitored.sh resume --last
+#   (Args after the script name are passed verbatim to `codex exec`.)
+#
+# ENV OVERRIDES:
+#   CODEX_MONITORED_HEARTBEAT      — heartbeat interval seconds (default 30).
+#   CODEX_MONITORED_TIMEOUT_SEC    — optional hard timeout. When >0, kill the
+#                                     codex process group and exit 124.
+#   CODEX_BIN                      — real codex binary path. Default:
+#                                     CODEX_REAL_BIN when set, else `codex`.
+#                                     Set this when the shim has put us first
+#                                     on PATH.
+#   CODEX_MONITORED_ALLOW_PIPED    — set non-empty to skip the pipe-stdout
+#                                     refusal. Reserved for tests; don't use
+#                                     in skill prompts.
+#   DEVLYN_CODEX_PROMPT_FILE      — exact binary stdin prompt; requires sole `-`.
+
+set -uo pipefail
+
+# iter-0019 — solo_claude (L1) arm enforcement (defense in depth alongside
+# scripts/codex-shim/codex). If this env is set, the wrapper refuses to invoke
+# codex at all, regardless of how it was reached. Two enforcement points
+# protect against the case where one is bypassed: the shim catches PATH-based
+# resolution, and this wrapper catches direct-path invocations of
+# codex-monitored.sh that don't go through the shim.
+if [ -n "${CODEX_BLOCKED:-}" ]; then
+  printf '[codex-monitored] CODEX_BLOCKED=%s — refusing codex invocation (solo_claude / L1 arm enforcement). args: %s\n' \
+    "${CODEX_BLOCKED}" "$*" >&2
+  exit 126
+fi
+
+HEARTBEAT_SEC="${CODEX_MONITORED_HEARTBEAT:-30}"
+TIMEOUT_SEC="${CODEX_MONITORED_TIMEOUT_SEC:-0}"
+CODEX_BIN="${CODEX_BIN:-${CODEX_REAL_BIN:-codex}}"
+START=$(date +%s)
+TIMEOUT_FLAG=""
+CODEX_ARGS=("$@")
+
+for codex_arg in "${CODEX_ARGS[@]}"; do
+  case "$codex_arg" in
+    --dangerously-bypass-approvals-and-sandbox|--yolo)
+      printf '[codex-monitored] error: forbidden Codex bypass flag: %s\n' "$codex_arg" >&2
+      exit 64
+      ;;
+    danger-full-access|-s=danger-full-access|--sandbox=danger-full-access)
+      printf '[codex-monitored] error: forbidden Codex sandbox: danger-full-access\n' >&2
+      exit 64
+      ;;
+  esac
+done
+
+require_nonnegative_int() {
+  local name="$1"
+  local value="$2"
+  case "$value" in
+    ''|*[!0-9]*)
+      printf '[codex-monitored] error: %s must be a non-negative integer (got %s)\n' \
+        "$name" "$value" >&2
+      exit 64
+      ;;
+  esac
+}
+
+require_positive_int() {
+  local name="$1"
+  local value="$2"
+  require_nonnegative_int "$name" "$value"
+  if [ "$value" -le 0 ]; then
+    printf '[codex-monitored] error: %s must be > 0 (got %s)\n' \
+      "$name" "$value" >&2
+    exit 64
+  fi
+}
+
+require_positive_int CODEX_MONITORED_HEARTBEAT "$HEARTBEAT_SEC"
+require_nonnegative_int CODEX_MONITORED_TIMEOUT_SEC "$TIMEOUT_SEC"
+
+# --- Pipe-stdout refusal (iter-0009 R2 finding #1) -------------------------
+# `[ -p /dev/stdout ]` is the POSIX test for "is fd 1 a FIFO/pipe". Verified
+# correct on macOS via lsof: distinguishes piped (`| cat`) from redirected
+# (`> file`) and from claude-bash-tool capture (regular file). Without this
+# refusal, `bash WRAPPER ... 2>&1 | tail -200` would buffer wrapper output —
+# including the heartbeat on stderr after `2>&1` — until EOF, reproducing
+# the iter-0008 byte-watchdog kill.
+if [ -z "${CODEX_MONITORED_ALLOW_PIPED:-}" ] && [ -p /dev/stdout ]; then
+  cat >&2 <<'EOF'
+[codex-monitored] error: stdout is a pipe.
+
+Piping the wrapper to tail/head/awk/sed/grep buffers wrapper output until EOF,
+which starves the outer claude -p byte-watchdog (iter-0008 starvation mechanism)
+and kills the run after ~300s with empty transcript.
+
+Fix: invoke the wrapper directly so the bash tool captures its stdout. The
+wrapper streams full Codex output and emits a heartbeat on stderr; you do NOT
+need to truncate.
+
+  WRONG: bash codex-monitored.sh ... 2>&1 | tail -200
+  RIGHT: bash codex-monitored.sh ...
+
+If you absolutely must filter, use a line-buffered tool (e.g. `grep --line-buffered`)
+and set CODEX_MONITORED_ALLOW_PIPED=1 in the wrapper's environment.
+EOF
+  exit 64
+fi
+
+# --- Heartbeat + signal forwarding ----------------------------------------
+heartbeat_loop() {
+  local pid="$1"
+  while kill -0 "$pid" 2>/dev/null; do
+    sleep "$HEARTBEAT_SEC"
+    if kill -0 "$pid" 2>/dev/null; then
+      local elapsed=$(( $(date +%s) - START ))
+      printf '[codex-monitored] heartbeat: elapsed=%ds\n' "$elapsed" >&2
+    fi
+  done
+}
+
+timeout_loop() {
+  local pid="$1"
+  local seconds="$2"
+  local flag="$3"
+  [ "$seconds" -gt 0 ] || return 0
+  sleep "$seconds"
+  if kill -0 "$pid" 2>/dev/null; then
+    : > "$flag"
+    printf '[codex-monitored] timeout: elapsed=%ds limit=%ds\n' \
+      "$(( $(date +%s) - START ))" "$seconds" >&2
+    kill -TERM -- "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+    sleep 5
+    kill -KILL -- "-$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true
+  fi
+}
+
+terminate_process_group() {
+  local pgid="$1"
+  local reason="$2"
+  if ! kill -0 -- "-$pgid" 2>/dev/null; then
+    return 0
+  fi
+  printf '[codex-monitored] reap: reason=%s pgid=%s\n' "$reason" "$pgid" >&2
+  kill -TERM -- "-$pgid" 2>/dev/null || true
+  local i
+  for i in 1 2 3 4 5; do
+    sleep 1
+    if ! kill -0 -- "-$pgid" 2>/dev/null; then
+      return 0
+    fi
+  done
+  kill -KILL -- "-$pgid" 2>/dev/null || true
+}
+
+terminate_monitor_group() {
+  local pid="$1"
+  kill -TERM -- "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+  kill -KILL -- "-$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true
+  wait "$pid" 2>/dev/null || true
+}
+
+forward_signal() {
+  local sig="$1"
+  if [ -n "${CODEX_PID:-}" ] && kill -0 "$CODEX_PID" 2>/dev/null; then
+    kill -"$sig" -- "-$CODEX_PID" 2>/dev/null || kill -"$sig" "$CODEX_PID" 2>/dev/null || true
+  fi
+  if [ -n "${HB_PID:-}" ]; then
+    terminate_monitor_group "$HB_PID"
+    HB_PID=""
+  fi
+  if [ -n "${WATCHDOG_PID:-}" ]; then
+    terminate_monitor_group "$WATCHDOG_PID"
+    WATCHDOG_PID=""
+  fi
+}
+
+cleanup() {
+  forward_signal TERM
+  [ -z "$TIMEOUT_FLAG" ] || rm -f "$TIMEOUT_FLAG"
+}
+
+trap 'forward_signal TERM; exit 143' TERM
+trap 'forward_signal INT; exit 130' INT
+trap cleanup EXIT
+
+printf '[codex-monitored] start: ts=%s heartbeat=%ds timeout=%ss bin=%s\n' \
+  "$(date -u +%FT%TZ)" "$HEARTBEAT_SEC" "$TIMEOUT_SEC" "$CODEX_BIN" >&2
+
+RECEIPT_HELPER="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/invocation-receipt.py"
+# Native Python owns Windows PIDs and the timeout tree; MSYS PIDs are different.
+if [ "${OS:-}" = Windows_NT ]; then
+  exec python3 "$RECEIPT_HELPER" dispatch --binary "$CODEX_BIN" \
+    --timeout "$TIMEOUT_SEC" --heartbeat "$HEARTBEAT_SEC" -- "${CODEX_ARGS[@]}" < /dev/null
+fi
+
+# The dispatcher snapshots file input, seals actual argv, then execs in this group.
+set -m
+python3 "$RECEIPT_HELPER" dispatch --binary "$CODEX_BIN" \
+  --timeout "$TIMEOUT_SEC" --heartbeat "$HEARTBEAT_SEC" -- "${CODEX_ARGS[@]}" < /dev/null &
+CODEX_PID=$!
+printf '[codex-monitored] codex pid=%d\n' "$CODEX_PID" >&2
+
+heartbeat_loop "$CODEX_PID" &
+HB_PID=$!
+
+if [ "$TIMEOUT_SEC" -gt 0 ]; then
+  TIMEOUT_FLAG=$(mktemp "${TMPDIR:-/tmp}/codex-monitored-timeout.XXXXXX")
+  rm -f "$TIMEOUT_FLAG"
+  timeout_loop "$CODEX_PID" "$TIMEOUT_SEC" "$TIMEOUT_FLAG" &
+  WATCHDOG_PID=$!
+fi
+set +m
+
+wait "$CODEX_PID"
+EXIT=$?
+terminate_process_group "$CODEX_PID" "post-exit-descendants"
+CODEX_PID=""
+forward_signal TERM
+if [ -n "$TIMEOUT_FLAG" ] && [ -f "$TIMEOUT_FLAG" ]; then
+  EXIT=124
+fi
+
+if [ -n "${DEVLYN_CODEX_PROMPT_FILE:-}" ]; then
+  python3 "$RECEIPT_HELPER" complete-dispatch --exit-code "$EXIT" || exit 64
+fi
+
+printf '[codex-monitored] codex exited: code=%d elapsed=%ds\n' \
+  "$EXIT" $(( $(date +%s) - START )) >&2
+exit "$EXIT"

package/native/codex/plugins/devlyn/skills/_shared/engine-doctor.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# engine-doctor.sh — read-only detection for /devlyn-engines' no-arg output.
+#
+# WHY (iter-0050): users need to see what's actually on the machine, not
+# just what's pinned. This script never writes .devlyn/engines.json, never
+# installs anything, never changes pin validation — it only reports.
+#
+# macOS-safe bash 3.2: no associative arrays, no mapfile/readarray.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+ADAPTERS_DIR="$SCRIPT_DIR/adapters"
+
+TARGETS=(claude codex omp pi)
+KINDS=(cli-engine cli-engine cli-engine orchestrator-only)
+BINARIES=(claude codex omp "")
+INSTALL_HINTS=(
+  "see https://docs.anthropic.com/en/docs/claude-code"
+  "npm install -g @openai/codex"
+  "brew install can1357/tap/omp"
+  ""
+)
+
+check_binary() {
+  # $1 = binary name, "" means no known binary to probe
+  [ -n "$1" ] || { printf 'unknown'; return; }
+  if command -v "$1" >/dev/null 2>&1; then printf 'yes'; else printf 'no'; fi
+}
+
+check_adapter() {
+  # $1 = target name
+  if [ -f "$ADAPTERS_DIR/$1.md" ]; then printf 'yes'; else printf 'no'; fi
+}
+
+check_executor() {
+  # $1 = adapter file path. An adapter may declare the fixed ASCII field
+  # `executor: no` under `## Role eligibility`; otherwise it can execute.
+  [ -f "$1" ] || { printf 'n/a'; return; }
+  if grep -q '^executor: no' "$1" 2>/dev/null; then printf 'no'; else printf 'yes'; fi
+}
+
+printf '%-8s %-17s %-8s %-8s %-9s %s\n' \
+  'target' 'kind' 'binary' 'adapter' 'executor' 'note'
+
+for i in "${!TARGETS[@]}"; do
+  target="${TARGETS[$i]}"
+  kind="${KINDS[$i]}"
+  binary="$(check_binary "${BINARIES[$i]}")"
+  adapter="$(check_adapter "$target")"
+  executor="$(check_executor "$ADAPTERS_DIR/$target.md")"
+
+  note='-'
+  case "$kind" in
+    cli-engine)
+      if [ "$binary" = 'no' ]; then
+        note="not installed; ${INSTALL_HINTS[$i]}"
+      elif [ "$adapter" = 'no' ]; then
+        note="binary present, no adapter — reinstall devlyn-cli, whose releases ship the adapters"
+      elif [ "$executor" = 'no' ]; then
+        note='adapter declares executor: no'
+      fi
+      ;;
+    orchestrator-only)
+      note='informational only; not a routable engine — no verified CLI binary or adapter'
+      ;;
+  esac
+
+  printf '%-8s %-17s %-8s %-8s %-9s %s\n' \
+    "$target" "$kind" "$binary" "$adapter" "$executor" "$note"
+done

package/native/codex/plugins/devlyn/skills/_shared/engine-preflight.md

@@ -0,0 +1,29 @@
+# Shared — Executor Pre-flight
+
+Used by `/devlyn-ideate` and `/devlyn-engines`: one rule for which engine executes implementation work and what happens when it is missing.
+
+## Selection
+
+The executor is the `executor` pin in `.devlyn/engines.json` at the checkout root (set with `/devlyn-engines executor <name>`), else the CLI the user opened. A linked worktree or subdirectory has no pin unless one is set there. Pi and Grok have no executor adapter, so a drain from them needs a claude, codex or omp pin. Keys earlier releases wrote for retired pipeline roles (`pair_judge_priority`, `roles`) stay as written and select nothing: a worker profile never becomes the executor.
+
+Before dispatching to the executor, run:
+
+```sh
+python3 "$DEVLYN_SHARED_DIR/role-config.py" --workdir <project> --default-engine <this CLI> --select
+```
+
+A pin is a promise. When the pinned engine's CLI is unavailable, the command exits 1 with `BLOCKED:<engine>-unavailable`: stop, preserve the evidence, and show the setup guidance — install and authenticate that CLI, verify `<engine> --version`, rerun. Never substitute another engine. A malformed file, or a name without an executor-eligible adapter, is `BLOCKED:invalid-engine-config`. CLI presence is not authentication, and status never launches a model.
+
+## Engines
+
+An engine is pinnable when `_shared/adapters/<name>.md` exists and does not declare `executor: no` under `## Role eligibility`. Adapters ship with devlyn-cli releases, and a reinstall replaces `_shared`. An adapter's `## Invocation` says how to start it. On native Windows, use native Node/npm and Python (`python3` on PATH), with Git for Windows Bash for the shipped shell wrapper.
+
+## Reporting a blocked engine
+
+The final report names the selected engine, the verdict and the setup steps; it never reports a downgraded success:
+
+```
+Engine: codex (pinned executor)
+Verdict: BLOCKED:codex-unavailable
+Setup: install/configure Codex CLI; run the current Codex auth/login flow; verify `codex --version`; rerun.
+```

package/native/codex/plugins/devlyn/skills/_shared/expected-contract.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Strict JSON and `spec.expected.json` contract validation for the ideate loop's package check and acceptance runner."""
+from __future__ import annotations
+
+import json
+import sys
+import unittest
+
+
+def reject_json_constant(token: str) -> None:
+    raise ValueError(f"invalid JSON numeric constant: {token}")
+
+
+def reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"duplicate JSON key: {key}")
+        result[key] = value
+    return result
+
+
+def loads_strict_json(text: str):
+    return json.loads(
+        text,
+        parse_constant=reject_json_constant,
+        object_pairs_hook=reject_duplicate_keys,
+    )
+
+
+EXPECTED_TOP_LEVEL_KEYS = {
+    "verification_commands",
+    "forbidden_patterns",
+    "required_files",
+    "forbidden_files",
+    "max_deps_added",
+    "pure_design",
+}
+EXPECTED_VERIFICATION_COMMAND_KEYS = {
+    "cmd",
+    "argv",
+    "exit_code",
+    "timeout_sec",
+    "stdout_contains",
+    "stdout_not_contains",
+    "contract_refs",
+}
+DEFAULT_TIMEOUT_SEC = 60
+
+
+def verification_timeout_sec(command: dict) -> int:
+    return command.get("timeout_sec", DEFAULT_TIMEOUT_SEC)
+
+
+def validate_command(command: object, label: str) -> str | None:
+    """Validate one command; `argv` and `cmd` are mutually exclusive."""
+    if not isinstance(command, dict):
+        return f"{label} must be an object"
+    if "argv" in command:
+        if "cmd" in command:
+            return f"{label} requires exactly one of cmd or argv"
+        value = command["argv"]
+        if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value) or not value[0]:
+            return f"{label}.argv must be a string array with non-empty argv[0]"
+    else:
+        cmd = command.get("cmd")
+        if not isinstance(cmd, str) or not cmd.strip():
+            return f"{label}.cmd must be a non-empty string"
+    ec = command.get("exit_code", 0)
+    if isinstance(ec, bool) or not isinstance(ec, int):
+        return f"{label}.exit_code must be int (not bool)"
+    timeout_sec = command.get("timeout_sec", DEFAULT_TIMEOUT_SEC)
+    if isinstance(timeout_sec, bool) or not isinstance(timeout_sec, int) or not 1 <= timeout_sec <= 600:
+        return f"{label}.timeout_sec must be int from 1 to 600 (not bool)"
+    for k in ("stdout_contains", "stdout_not_contains"):
+        v = command.get(k, [])
+        if not isinstance(v, list) or not all(isinstance(s, str) and s for s in v):
+            return f"{label}.{k} must be a list of non-empty strings"
+    return None
+
+
+def validate_shape(data) -> str | None:
+    """Return None if `data` has a non-empty, well-formed `verification_commands`
+    list; else a human-readable error string.
+
+    Each object requires exactly one of a non-empty string `cmd` or a
+    string-array `argv`; `exit_code` defaults to 0 and must be a
+    non-bool int; `timeout_sec` defaults to DEFAULT_TIMEOUT_SEC and must be a
+    non-bool int from 1 through 600; `stdout_contains` and `stdout_not_contains`
+    default to empty lists of non-empty strings. Bool is rejected explicitly
+    because Python's `bool` subclasses `int`.
+    """
+    if not isinstance(data, dict):
+        return "top-level must be a JSON object"
+    cmds = data.get("verification_commands")
+    if not isinstance(cmds, list):
+        return "verification_commands must be a list"
+    if not cmds:
+        return "verification_commands must contain at least one entry"
+    for i, c in enumerate(cmds):
+        err = validate_command(c, f"verification_commands[{i}]")
+        if err:
+            return err
+    return None
+
+
+def validate_string_list(data: object, key: str) -> str | None:
+    value = data.get(key, []) if isinstance(data, dict) else None
+    if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
+        return f"{key} must be a list of non-empty strings"
+    return None
+
+
+def validate_expected_shape(data) -> str | None:
+    """Return None if shape matches the sibling spec.expected.json schema.
+
+    Keep this dependency-free: it mirrors `_shared/expected.schema.json` enough
+    to catch malformed contracts before a consumer executes them.
+    """
+    if not isinstance(data, dict):
+        return "top-level must be a JSON object"
+    unknown = sorted(set(data) - EXPECTED_TOP_LEVEL_KEYS)
+    if unknown:
+        return f"unknown top-level key(s): {', '.join(unknown)}"
+    if "verification_commands" in data:
+        commands = data["verification_commands"]
+        if not isinstance(commands, list):
+            return "verification_commands must be a list"
+        if commands:
+            err = validate_shape({"verification_commands": commands})
+            if err:
+                return err
+        for i, command in enumerate(commands):
+            unknown_command_keys = sorted(set(command) - EXPECTED_VERIFICATION_COMMAND_KEYS)
+            if unknown_command_keys:
+                return (
+                    f"verification_commands[{i}] unknown key(s): "
+                    f"{', '.join(unknown_command_keys)}"
+                )
+            contract_refs = command.get("contract_refs", [])
+            if not isinstance(contract_refs, list) or not all(
+                isinstance(item, str) and item for item in contract_refs
+            ):
+                return f"verification_commands[{i}].contract_refs must be a list of non-empty strings"
+    for key in ("required_files", "forbidden_files"):
+        err = validate_string_list(data, key)
+        if err:
+            return err
+    max_deps = data.get("max_deps_added", 0)
+    if isinstance(max_deps, bool) or not isinstance(max_deps, int) or max_deps < 0:
+        return "max_deps_added must be a non-negative integer"
+    if "pure_design" in data and not isinstance(data["pure_design"], bool):
+        return "pure_design must be a boolean"
+    patterns = data.get("forbidden_patterns", [])
+    if not isinstance(patterns, list):
+        return "forbidden_patterns must be a list"
+    for i, pattern in enumerate(patterns):
+        if not isinstance(pattern, dict):
+            return f"forbidden_patterns[{i}] must be an object"
+        unknown_pattern_keys = sorted(set(pattern) - {"pattern", "description", "files", "severity"})
+        if unknown_pattern_keys:
+            return (
+                f"forbidden_patterns[{i}] unknown key(s): "
+                f"{', '.join(unknown_pattern_keys)}"
+            )
+        for key in ("pattern", "description", "severity"):
+            value = pattern.get(key)
+            if not isinstance(value, str) or not value:
+                return f"forbidden_patterns[{i}].{key} must be a non-empty string"
+        if pattern["severity"] not in {"disqualifier", "warning"}:
+            return f"forbidden_patterns[{i}].severity must be disqualifier or warning"
+        files = pattern.get("files", [])
+        if not isinstance(files, list) or not all(isinstance(item, str) and item for item in files):
+            return f"forbidden_patterns[{i}].files must be a list of non-empty strings"
+    return None
+
+
+def slice_diff_to_files(diff_text: str, files: list[str]) -> str:
+    if not files:
+        return diff_text
+    out: list[str] = []
+    keep = False
+    for line in diff_text.splitlines(keepends=True):
+        if line.startswith("diff --git "):
+            keep = any(path in line for path in files)
+        if keep:
+            out.append(line)
+    return "".join(out)
+
+
+class ContractTests(unittest.TestCase):
+    def test_strict_json(self):
+        for text, message in (('{"a":1,"a":2}', "duplicate JSON key"), ('{"a":NaN}', "invalid JSON numeric constant")):
+            with self.assertRaisesRegex(ValueError, message):
+                loads_strict_json(text)
+
+    def test_cmd_and_argv_are_mutually_exclusive(self):
+        ok = {"verification_commands": [{"argv": ["python3", "-c", "pass"], "contract_refs": ["R1"]}, {"cmd": "true"}]}
+        self.assertIsNone(validate_expected_shape(ok))
+        for command, message in (
+            ({"cmd": "true", "argv": ["true"]}, "exactly one of cmd or argv"),
+            ({"argv": []}, "argv must be a string array"),
+            ({"argv": ["", "x"]}, "argv must be a string array"),
+            ({"argv": ["x", 1]}, "argv must be a string array"),
+            ({}, "cmd must be a non-empty string"),
+        ):
+            self.assertIn(message, validate_expected_shape({"verification_commands": [command]}))
+
+    def test_command_fields(self):
+        for command, message in (
+            ({"cmd": "x", "exit_code": True}, "exit_code must be int"),
+            ({"cmd": "x", "timeout_sec": 601}, "timeout_sec must be int from 1 to 600"),
+            ({"cmd": "x", "stdout_contains": "x"}, "stdout_contains must be a list of non-empty strings"),
+            ({"cmd": "x", "stdout_contains": [""]}, "stdout_contains must be a list of non-empty strings"),
+            ({"cmd": "x", "stdout_not_contains": [""]}, "stdout_not_contains must be a list of non-empty strings"),
+            ({"cmd": "x", "contract_refs": [""]}, "contract_refs must be a list of non-empty strings"),
+            ({"cmd": "x", "extra": 1}, "unknown key(s): extra"),
+        ):
+            self.assertIn(message, validate_expected_shape({"verification_commands": [command]}))
+        self.assertEqual(validate_expected_shape([]), "top-level must be a JSON object")
+        self.assertIn("unknown top-level key(s): process_evidence", validate_expected_shape({"process_evidence": []}))
+
+    def test_diff_helpers(self):
+        diff = ('diff --git a/package.json b/package.json\n--- a/package.json\n+++ b/package.json\n@@ -1,3 +1,5 @@\n'
+                ' {\n   "dependencies": {\n+    "left-pad": "1.0.0",\n+    "is-odd": "3.0.0"\n   }\n }\n'
+                'diff --git a/other b/other\n+x\n')
+        self.assertNotIn("other", slice_diff_to_files(diff, ["package.json"]))
+        self.assertEqual(slice_diff_to_files(diff, []), diff)
+
+
+def main() -> int:
+    if sys.argv[1:] != ["--self-test"]:
+        print("usage: expected-contract.py --self-test", file=sys.stderr)
+        return 2
+    result = unittest.TextTestRunner(verbosity=1).run(unittest.defaultTestLoader.loadTestsFromTestCase(ContractTests))
+    if result.wasSuccessful():
+        print(f"expected-contract self-test: PASS ({result.testsRun} tests)")
+    return 0 if result.wasSuccessful() else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())