devlyn-cli 1.15.0 → 2.1.0

package/config/skills/_shared/codex-monitored.sh

@@ -0,0 +1,141 @@
+#!/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 (`< /dev/null`) — kills the codex 0.124.0 stdin hang.
+#   3. Streams codex stdout to OUR stdout line-by-line — the orchestrator reads
+#      stdout as the subagent reply (per `_shared/codex-config.md`) 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 -c model_reasoning_effort=xhigh "<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_BIN                      — real codex binary path. Default: `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.
+
+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}"
+CODEX_BIN="${CODEX_BIN:-codex}"
+START=$(date +%s)
+
+# --- 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
+}
+
+forward_signal() {
+  local sig="$1"
+  if [ -n "${CODEX_PID:-}" ] && kill -0 "$CODEX_PID" 2>/dev/null; then
+    kill -"$sig" "$CODEX_PID" 2>/dev/null || true
+  fi
+  if [ -n "${HB_PID:-}" ] && kill -0 "$HB_PID" 2>/dev/null; then
+    kill -TERM "$HB_PID" 2>/dev/null || true
+  fi
+}
+
+trap 'forward_signal TERM' TERM
+trap 'forward_signal INT' INT
+
+printf '[codex-monitored] start: ts=%s heartbeat=%ds bin=%s\n' \
+  "$(date -u +%FT%TZ)" "$HEARTBEAT_SEC" "$CODEX_BIN" >&2
+
+# Launch codex with stdin closed; output streams directly to OUR stdout/stderr.
+"$CODEX_BIN" exec "$@" < /dev/null &
+CODEX_PID=$!
+printf '[codex-monitored] codex pid=%d\n' "$CODEX_PID" >&2
+
+heartbeat_loop "$CODEX_PID" &
+HB_PID=$!
+
+wait "$CODEX_PID"
+EXIT=$?
+
+kill -TERM "$HB_PID" 2>/dev/null || true
+wait "$HB_PID" 2>/dev/null || true
+
+printf '[codex-monitored] codex exited: code=%d elapsed=%ds\n' \
+  "$EXIT" $(( $(date +%s) - START )) >&2
+exit "$EXIT"

package/config/skills/_shared/engine-preflight.md

@@ -0,0 +1,35 @@
+# Shared — `--engine` Pre-flight
+
+Used by `/devlyn:resolve` and `/devlyn:ideate`. One shared availability rule so every skill routes identically.
+
+## Rule
+
+Each skill resolves the effective engine from its own SKILL.md default plus any explicit `--engine` flag passed by the user. This pre-flight runs **only when the resolved engine is `auto` or `codex`** — when the resolved engine is `claude` (whether by skill default or explicit flag), the Codex check is skipped entirely.
+
+When the resolved engine is `auto` or `codex`, on entry (before spawning any phase that could route to Codex):
+
+1. Check if the Codex CLI is installed: `command -v codex >/dev/null 2>&1` (or equivalent bash test).
+2. On failure → silently set `engine = "claude"` for the remainder of this run AND log `engine downgraded: codex-unavailable` into the skill's final summary/report header.
+3. On success → proceed with the original engine value.
+
+Never prompt the user. Never abort the run on missing CLI.
+
+Per-skill defaults: `/devlyn:resolve` defaults to `claude` (post iter-0020 close-out — Codex BUILD/IMPLEMENT below quality floor; iter-0033g + iter-0034 close-out — PLAN-pair research-only until container/sandbox infra justifies a measurement); `/devlyn:ideate` defaults to `auto` for the CHALLENGE phase's cross-model GAN-critic dynamic. Each skill's SKILL.md flag block is the source of truth for that skill's default.
+
+## Why this is the one permitted silent fallback
+
+`CLAUDE.md` sets the no-silent-fallback rule for this repo. This downgrade is documented there as the single explicit exception because the hands-free contract — skills the user walks away from — would otherwise fail every run whenever the Codex CLI is absent. The user-visible behavior is identical to an explicit `--engine claude` invocation, and the banner in the final report removes the silence. Any other silent fallback in skills code is a bug.
+
+## What a skill must log after downgrade
+
+When the resolved engine was `auto` / `codex` and the Codex CLI was absent, the final user-facing report/summary shows both the requested and effective mode:
+
+```
+Engine: claude (downgraded from auto — codex-unavailable)
+```
+
+If no downgrade happened (either Codex was available, or the resolved engine was already `claude`), omit the parenthetical. That single line is the contract — the user can always see why Codex did or did not participate.
+
+## Canonical Codex invocation
+
+See `config/skills/_shared/codex-config.md` for the canonical wrapper invocation and flag set skills should use after the availability check passes.

package/config/skills/_shared/expected.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/fysoul17/devlyn-cli/config/skills/_shared/expected.schema.json",
+  "title": "spec.expected.json — mechanical acceptance contract",
+  "description": "Load-bearing LLM-agnostic decoupler for the devlyn-cli harness. Defines the machine-readable acceptance criteria a spec ships alongside spec.md. Stable across model upgrades — when Opus 5 / GPT-6 / Qwen / Gemini land, this schema does not move; only the per-model adapter files in _shared/adapters/ do.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "verification_commands": {
+      "type": "array",
+      "description": "Each command is executed against the post-BUILD code. Each pass/fail contributes to verify_score. At least one entry is required when the spec has any observable runtime check (CLI, test command, HTTP request).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["cmd"],
+        "properties": {
+          "cmd": {
+            "type": "string",
+            "description": "Shell command, executed via `subprocess.run(..., shell=True)` from the build's working directory.",
+            "minLength": 1
+          },
+          "exit_code": {
+            "type": "integer",
+            "description": "Required exit code. Default 0 if omitted.",
+            "default": 0
+          },
+          "stdout_contains": {
+            "type": "array",
+            "description": "Each substring must appear verbatim in (stdout + stderr) for pass.",
+            "items": { "type": "string", "minLength": 1 },
+            "default": []
+          },
+          "stdout_not_contains": {
+            "type": "array",
+            "description": "None of these substrings may appear in (stdout + stderr) for pass.",
+            "items": { "type": "string", "minLength": 1 },
+            "default": []
+          }
+        }
+      }
+    },
+    "forbidden_patterns": {
+      "type": "array",
+      "description": "Regex patterns scanned across diff.patch. Match at severity=disqualifier is a hard-floor fail; match at severity=warning is judge-only critical-finding.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["pattern", "description", "severity"],
+        "properties": {
+          "pattern": {
+            "type": "string",
+            "description": "Python re.search-compatible regex. Anchored implicitly by the surrounding regex, NOT by ^ / $ unless intended.",
+            "minLength": 1
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable explanation of what the pattern catches and why it's forbidden.",
+            "minLength": 1
+          },
+          "files": {
+            "type": "array",
+            "description": "Optional allow-list of files (substrings of diff --git lines). When present, scan is sliced to hunks touching only these files.",
+            "items": { "type": "string", "minLength": 1 },
+            "default": []
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["disqualifier", "warning"],
+            "description": "disqualifier = hard-floor fail (DQ). warning = judge-visible critical-finding only."
+          }
+        }
+      }
+    },
+    "required_files": {
+      "type": "array",
+      "description": "Files that must exist after the arm runs.",
+      "items": { "type": "string", "minLength": 1 },
+      "default": []
+    },
+    "forbidden_files": {
+      "type": "array",
+      "description": "Files that must NOT appear in the arm's diff (e.g. tooling artifacts the spec didn't request).",
+      "items": { "type": "string", "minLength": 1 },
+      "default": []
+    },
+    "max_deps_added": {
+      "type": "integer",
+      "description": "Hard cap on new entries under dependencies/devDependencies in package.json. Exceeds → DQ.",
+      "minimum": 0,
+      "default": 0
+    }
+  }
+}

package/config/skills/_shared/pair-plan-schema.md

@@ -0,0 +1,298 @@
+# Shared — `pair-plan.json` schema (iter-0022 archive)
+
+> **Archive header (iter-0034 Phase 4 cutover, 2026-05-04)** — this schema was iter-0022 infrastructure for the now-deleted `/devlyn:auto-resolve` PHASE 0 plan-pair contract. The `/devlyn:resolve` PHASE 1 PLAN at HEAD runs solo (per iter-0033 (C1) PASS evidence + iter-0033g § "CLOSURE"). The schema is preserved here as a design archive: the unblock conditions for re-instating PLAN-pair (per `iterations/0034-phase-4-cutover.md` § "L2 PLAN-pair research-only label") are A — container/sandbox isolation justified by another product need, OR B — production telemetry captures positive evidence of subagent introspection that a PLAN-pair measurement would need to isolate. When either condition fires, this schema (and the associated lint / idgen / preflight tooling under `benchmark/auto-resolve/scripts/`) is the starting point.
+
+Single source of truth for `pair-plan.json` and its companion `canonical_id_registry.json` when the architecture re-enters scope. Read this once before editing `pair-plan-idgen.py`, `pair-plan-lint.py`, `pair-plan-preflight.sh`, or any future plan-pair PHASE that consumes `state.plan`.
+
+## Audience (when re-instated)
+
+- `benchmark/auto-resolve/scripts/pair-plan-idgen.py` — produces `canonical_id_registry.json` from `expected.json` + checked-in oracle scripts.
+- `benchmark/auto-resolve/scripts/pair-plan-lint.py` — validates a `pair-plan.json` against its registry.
+- `autoresearch/scripts/pair-plan-preflight.sh` — orchestrates solo + pair plan generation against blind-aliased fixtures.
+- A future `/devlyn:resolve` PHASE 1 plan-pair branch (currently solo; gated on unblock A or B above): would accept `--plan-path` / JSON payload, set `state.plan.{mode, path}`, and run lint before IMPLEMENT, mirroring the deleted `devlyn:auto-resolve` PHASE 0 contract.
+
+## File locations and naming (canonical)
+
+- Registry per fixture: `benchmark/auto-resolve/fixtures/<F>/expected-pair-plan-registry.json` (committed snapshot for diff-against-baseline; iter-0023 verifies the live idgen output equals this snapshot).
+- Plan produced by preflight: `benchmark/auto-resolve/results/<run_id>/<blind_fixture>/plan-preflight/merged/pair-plan.json`.
+- Plan supplied to a re-instated plan-pair branch by an external caller: any path the user chooses, passed via `--plan-path <path>` (the contract surface is preserved as iter-0022 design archive).
+- The registry filename is `canonical_id_registry.json` for **runtime artifacts** — both inside the bundle dir and in the preflight output root. (HANDOFF.md:280 mentions `canonical-ids.json` for the preflight output dir; that name is deprecated — D4 emits `canonical_id_registry.json` to align with the rest of the toolchain.)
+- The **committed fixture snapshot** is named `expected-pair-plan-registry.json` (one per fixture, under `benchmark/auto-resolve/fixtures/<F>/`) — distinct file name to make snapshots greppable separately from runtime artifacts. iter-0023 verifies the live idgen output equals the committed snapshot for the same fixture.
+
+## `canonical_id_registry.json` shape
+
+Top-level wrapper:
+
+```jsonc
+{
+  "schema_version": "1",
+  "fixture_id": "F2-cli-medium-subcommand",
+  "generated_at": "2026-04-29T18:30:00Z",
+  "generated_from": {
+    "expected_path": "benchmark/auto-resolve/fixtures/F2-cli-medium-subcommand/expected.json",
+    "expected_sha256": "...",          // raw file bytes sha256
+    "metadata_path":  "benchmark/auto-resolve/fixtures/F2-cli-medium-subcommand/metadata.json",
+    "metadata_sha256": "...",          // raw file bytes sha256
+    "oracle_script_shas": {
+      "test-fidelity":   "...",        // raw bytes sha256 of oracle-test-fidelity.py
+      "scope-tier-a":    "...",
+      "scope-tier-b":    "..."
+    }
+  },
+  "required_invariants": [
+    {
+      "id": "...",
+      "source_field": "expected.json/forbidden_patterns/0 | expected.json/verification_commands/3 | expected.json/required_files | expected.json/forbidden_files | expected.json/max_deps_added | expected.json/spec_output_files | oracle/<oracle-name>/<category-id>",
+      "source_ref":   "expected.json:60 | expected.json/verification_commands/0 | oracle-test-fidelity.py",
+      "operational_check": "...natural-language description of what the variant must do or must not do...",
+      "severity": "disqualifier | hard | flag | warn",
+      "authority": "expected.json/forbidden_patterns | expected.json/verification_commands | expected.json/required_files | expected.json/forbidden_files | expected.json/max_deps_added | expected.json/spec_output_files | metadata/oracle-allowlist"
+    }
+    // ...sorted lexicographically by id
+  ]
+}
+```
+
+**Hard rules**:
+- `required_invariants` MUST be sorted lexicographically by `id`. idgen sorts before serializing; lint rejects an unsorted file.
+- All file shas (`expected_sha256`, `metadata_sha256`, `oracle_script_shas.*`) are **raw file bytes sha256** — `sha256(open(path, "rb").read())`. NOT canonical-JSON form. (Canonical form is reserved for the pair-plan pre-stamp hash; see below.)
+- `info`-severity oracle categories are NOT registry entries (e.g. scope-tier-b's `tier-b-reachable` is a positive signal, not an invariant violation).
+- The umbrella oracle category `scope-tier-a:tier-a-violation` is ONE registry entry; the 5 path-glob groups (planning-doc, ci-config, node-modules, test-results-or-coverage, env-secrets) are described inside `operational_check`, not split into 5 entries.
+
+**Determinism**: same `(expected.json, metadata.json, oracle scripts)` input → byte-identical `canonical_id_registry.json`. Achieved by:
+- `json.dumps(obj, sort_keys=True, indent=2, ensure_ascii=False)` for the on-disk file.
+- All lists pre-sorted before dumping (registry items by `id`).
+- No timestamps that change run-to-run except `generated_at` — see exemption below.
+
+`generated_at` is the ONE volatile field. Lint ignores it for sha-stability checks; lint's determinism check sets `generated_at` to a fixed value before comparing two consecutive idgen runs. (Implementation: idgen accepts `--generated-at <iso8601>` for testing.)
+
+## `pair-plan.json` shape
+
+```jsonc
+{
+  "schema_version": "1",
+  "plan_status": "final | blocked | draft",
+  "planning_mode": "solo | pair",
+  "fixture_id": "F2-cli-medium-subcommand",          // human label; not authoritative
+  "source": {
+    "spec_path":          "benchmark/auto-resolve/fixtures/F2-cli-medium-subcommand/spec.md",
+    "spec_sha256":        "...",                     // raw file bytes
+    "expected_path":      "benchmark/auto-resolve/fixtures/F2-cli-medium-subcommand/expected.json",
+    "expected_sha256":    "...",                     // raw file bytes (optional only when expected.json absent)
+    "rubric_path":        "benchmark/auto-resolve/RUBRIC.md",
+    "rubric_sha256":      "...",                     // raw file bytes
+    "canonical_id_registry_path":   "benchmark/auto-resolve/fixtures/F2-cli-medium-subcommand/expected-pair-plan-registry.json",
+    "canonical_id_registry_sha256": "..."            // raw file bytes of the registry file
+  },
+  "authority_order": [
+    "spec.md",
+    "expected.json/rubric",
+    "phase prompt",
+    "model preference"
+  ],
+  "rounds": [
+    {
+      "round": 1,
+      "claude_draft_sha256": "...",                  // raw file bytes of the per-round draft artifact
+      "codex_draft_sha256":  "...",
+      "merged_sha256":       "...",
+      "note": "..."
+    }
+    // up to 3 rounds; iter-0022 preflight stops at the first round where neither model has new substantive critique
+  ],
+  "accepted_invariants": [
+    {
+      "id":           "no_silent_catch_return_fallback",
+      "paraphrase":   "...",                         // human-readable; informational only, NOT enforced
+      "source_refs":  ["spec.md:36", "expected.json/forbidden_patterns/0"],
+      "operational_check": "BUILD output must not contain `catch[^{]*\\{[^}]*return [^}]*\\}` in bin/cli.js",
+      "authority":    "expected.json/forbidden_patterns"
+    }
+  ],
+  "rejected_alternatives": [
+    {
+      "id":              "alt_silent_catch_with_log",
+      "rationale":       "Authority order says expected.json/forbidden_patterns dominates; logging does not change visible-error contract.",
+      "conflicts_with_ids": ["no_silent_catch_return_fallback"],
+      "claude_stamp":    "rejected",
+      "codex_stamp":     "rejected"
+    }
+  ],
+  "unresolved":          [],                         // MUST be empty in final plans
+  "escalated_to_user":   [],                         // populated only during draft / blocked status; final must have user_resolution per item if non-empty
+  "model_stamps": {
+    "claude": {
+      "status":              "sign | block",
+      "blocked_ids":         [],
+      "signed_plan_sha256":  "...",                  // canonical pre-stamp sha (see below)
+      "model":               "claude-opus-4-7",
+      "timestamp":           "2026-04-29T..."
+    },
+    "codex": {
+      "status":              "sign | block",
+      "blocked_ids":         [],
+      "signed_plan_sha256":  "...",
+      "model":               "gpt-5.5",
+      "timestamp":           "..."
+    }
+  }
+}
+```
+
+## Severity decoupling (registry vs findings)
+
+The registry's `required_invariants[].severity` taxonomy is **metadata for human review only**: `disqualifier | hard | flag | warn`. It is NOT mapped onto the `references/findings-schema.md` taxonomy used by EVAL / CRITIC findings (`CRITICAL | HIGH | MEDIUM | LOW`). When a phase emits a finding for a missed plan invariant, severity is assigned by that phase's own existing severity policy (per `findings-schema.md`), not by reading the registry severity directly. The two taxonomies serve different audiences (registry severity = "how the oracle classifies it"; findings severity = "what the orchestrator should do about it") and are intentionally not coupled in iter-0022.
+
+## Hard rules (lint-enforced)
+
+1. `unresolved.length > 0` → `plan_status` MUST be `blocked` or `draft`. Final accepted plan MUST have `unresolved == []`.
+2. `escalated_to_user[]` non-empty → each item MUST carry a `user_resolution` field, OR `plan_status` MUST be `blocked` / `draft`.
+3. Every `accepted_invariants[].id` MUST appear in the registry's `required_invariants[].id` exactly (string match — no paraphrase, no synonym, no new IDs at plan-time). `paraphrase` is informational only.
+4. **Final-plan coverage**: when `plan_status == "final"`, every registry entry MUST be accounted for in the plan — each `required_invariants[].id` is in `accepted_invariants[].id` OR in some `rejected_alternatives[].conflicts_with_ids[]` OR in `escalated_to_user[].id` OR in `unresolved[].id`. (`draft` and `blocked` plans are NOT subject to full coverage; they may still carry un-decided ids in `unresolved[]` per Rule #1.)
+5. `authority_order` MUST be the exact 4-string array `["spec.md", "expected.json/rubric", "phase prompt", "model preference"]` (snapshot at iter-0022 ship time; future iters can amend with explicit `schema_version` bump).
+6. `model_stamps.{claude,codex}.status == "sign"` MUST hold for `plan_status: "final"`. A `block` from either model forces `plan_status` to `blocked` or `draft`.
+7. `model_stamps.{claude,codex}.signed_plan_sha256` MUST be byte-identical AND MUST equal the canonical pre-stamp sha256 of the file (see "Two sha256 contracts" below).
+8. `source.{spec_sha256, expected_sha256, rubric_sha256, canonical_id_registry_sha256}` MUST equal the actual raw-bytes sha256 of the referenced files at lint time (catches stale plans against changed sources).
+9. `source.canonical_id_registry_path` MUST resolve to an existing registry file. lint reads it from this field; if `--registry <path>` is passed on the lint command line, the override wins.
+10. `planning_mode: "pair"` requires `rounds.length >= 1`. `planning_mode: "solo"` requires `rounds.length == 0` (no merge artifacts).
+
+## Two sha256 contracts (DO NOT CONFLATE)
+
+### Contract A — raw file bytes
+
+Used for: every `source.*_sha256` field (spec, expected, rubric, registry), every `generated_from.*_sha256` field in the registry, every `rounds[].*_draft_sha256` and `merged_sha256`.
+
+```python
+import hashlib
+with open(path, "rb") as f:
+    sha = hashlib.sha256(f.read()).hexdigest()
+```
+
+No canonicalization. The bytes on disk are what gets hashed. This catches "the plan claims spec.md is sha X but spec.md actually has bytes producing sha Y" drift.
+
+### Contract B — canonical pre-stamp form (pair-plan stamps only)
+
+Used for: `model_stamps.claude.signed_plan_sha256` and `model_stamps.codex.signed_plan_sha256`. Both stamps sign **byte-identical** canonical bytes, so both sha values are byte-identical.
+
+Algorithm (writers and verifiers MUST implement exactly):
+
+```python
+import json
+import hashlib
+import copy
+
+def canonical_pre_stamp_sha256(plan: dict) -> str:
+    # Reject duplicate keys when LOADING the plan; this function assumes a clean dict.
+    pre = copy.deepcopy(plan)
+    pre["model_stamps"] = {}                       # replace value, keep key
+    s = json.dumps(
+        pre,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    )
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+```
+
+When LOADING the plan, reject duplicate keys:
+
+```python
+def _strict_pairs(pairs):
+    keys = [k for k, _ in pairs]
+    if len(keys) != len(set(keys)):
+        raise ValueError("duplicate key in pair-plan.json")
+    return dict(pairs)
+
+with open(path, "r", encoding="utf-8") as f:
+    plan = json.load(f, object_pairs_hook=_strict_pairs)
+```
+
+**Why no Unicode normalization**: the canonical form hashes input bytes as-is. Writers and verifiers must agree on input form (NFC recommended for any user-supplied free-text strings, but not enforced — the scheme survives because both sides derive from the same source bytes).
+
+**Why no floats**: integer + string serialize byte-stably across implementations. Floats vary (e.g. `1.0` vs `1`). Avoid floats in this schema until a future field absolutely requires one; if added, document the canonical float-printing rule in this file.
+
+## Slug rules for registry IDs (idgen)
+
+When an `expected.json` item lacks an explicit `id` field, idgen synthesizes a deterministic slug.
+
+### `forbidden_patterns[i]` slug
+
+```
+forbidden_pattern__<sanitize(description, 60)>__<sanitize(files[0], 30)>
+```
+
+`sanitize(s, max_len)`: lowercase; replace any non-`[a-z0-9]` run with a single `_`; strip leading/trailing `_`; truncate to `max_len` (right-truncate, no hash suffix at this level).
+
+If two items in the same `forbidden_patterns[]` array produce the same slug after sanitization, the FIRST one (by source-array index) keeps the bare slug; each subsequent collision appends `__i<index>`. idgen detects this deterministically by walking the array in order.
+
+Example F2:
+- `forbidden_patterns[0]` (description="silent catch returning a fallback value — violates no-silent-catches policy", files=["bin/cli.js"]) → `forbidden_pattern__silent_catch_returning_a_fallback_value_violate__bin_cli_js`
+- `forbidden_patterns[1]` (description="@ts-ignore escape hatch", files=["bin/cli.js"]) → `forbidden_pattern__ts_ignore_escape_hatch__bin_cli_js`
+
+### `verification_commands[i]` slug
+
+```
+verification__<sha8(canonical_json(verification_obj))>
+```
+
+`canonical_json(obj)`: same compact form as Contract B (`json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False)`).
+`sha8(s)`: first 8 hex chars of `sha256(s.encode("utf-8"))`.
+
+The full verification object is hashed (cmd + exit_code + stdout_contains + stdout_not_contains), so reordering the array does not change the slug. Array-index lives in `source_ref` (`expected.json/verification_commands/<i>`) for human navigation only.
+
+### Other expected.json fields
+
+- `required_files`: one registry entry per file path: `required_file__<sanitize(path, 60)>`.
+- `forbidden_files`: same shape: `forbidden_file__<sanitize(path, 60)>`.
+- `max_deps_added`: one registry entry: `max_deps_added__<value>` (e.g. `max_deps_added__0`).
+- `spec_output_files`: one registry entry per path: `spec_output_file__<sanitize(path, 60)>`.
+
+### Oracle category IDs (no slug — fixed strings)
+
+Oracle `--list-categories` returns category IDs in the form `<oracle-name>:<finding-type>`. These are stable strings that idgen passes through verbatim into `required_invariants[].id`. Each oracle script defines its own enum; iter-0022 ship snapshot:
+
+- `test-fidelity:test-file-deleted`
+- `test-fidelity:test-file-renamed`
+- `test-fidelity:mock-swap`
+- `test-fidelity:assertion-regression`
+- `scope-tier-a:lockfile-deletion`
+- `scope-tier-a:tier-a-violation`
+- `scope-tier-b:scope-unmatched`
+
+`scope-tier-b:tier-b-reachable` is `info`-severity and NOT a registry entry.
+
+## metadata.json field for per-fixture oracle allowlist
+
+iter-0022 adds one new field to each fixture's `metadata.json`:
+
+```json
+{
+  "id": "F2-cli-medium-subcommand",
+  // ... existing fields unchanged ...
+  "pair_plan_oracle_categories": [
+    "test-fidelity:test-file-deleted",
+    "test-fidelity:test-file-renamed",
+    "test-fidelity:mock-swap",
+    "test-fidelity:assertion-regression",
+    "scope-tier-a:lockfile-deletion",
+    "scope-tier-a:tier-a-violation",
+    "scope-tier-b:scope-unmatched"
+  ]
+}
+```
+
+Hard rule: idgen filters oracle categories to exactly this allowlist. If the field is missing, idgen treats it as the empty array (no oracle categories registered) — `expected.json`-derived invariants still appear. Schema-version bump if the allowlist semantics change.
+
+The runner `run-fixture.sh` reads `timeout_seconds` (line 54) and the report reads `category` (compile-report.py line 76); no other consumer reads metadata.json today, so adding a new field is a pure metadata enrichment with no scoring implication.
+
+## Plan field minimum/maximum policy
+
+- A field listed in this schema with no "optional" annotation is REQUIRED.
+- Fields explicitly marked optional: `source.expected_path` / `source.expected_sha256` (only when `expected.json` is genuinely absent — not the case for any current fixture).
+- Unknown extra fields in `pair-plan.json` are NOT rejected by lint (forward-compat), but the canonical pre-stamp sha is computed over the whole object so unknown fields participate in the signature.
+- Unknown extra fields in `canonical_id_registry.json` ARE rejected by lint (idgen owns the registry shape; drift here is a bug).
+
+## Versioning
+
+`schema_version` starts at `"1"`. A breaking change to any hard rule above bumps the version and the lint script gains a per-version dispatcher. iter-0022 ships version `1`. Future iters MUST update this file before bumping the version field anywhere else.