devlyn-cli 3.2.0 → 3.3.0

package/benchmark/auto-resolve/shadow-fixtures/S6-cli-refund-window-ledger/expected.json

@@ -1,56 +0,0 @@
-{
-  "verification_commands": [
-    {
-      "cmd": "node --test tests/cli.test.js",
-      "exit_code": 0,
-      "stdout_contains": [],
-      "stdout_not_contains": ["not ok "]
-    },
-    {
-      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/priority-refund-ledger.js\"",
-      "exit_code": 0,
-      "stdout_contains": ["\"ok\":true"],
-      "stdout_not_contains": [],
-      "contract_refs": [
-        "Process refund requests globally by `priority` descending, then `requested_on` ascending, then original input order ascending.",
-        "A refund rejects with reason `window_expired` when `requested_on` is more than `refund_window_days` after `purchased_on`.",
-        "A refund accepts only when the order's remaining refundable cents is at least the requested `cents`.",
-        "A rejected refund with reason `over_refund` must not change that order's remaining refundable cents.",
-        "For each accepted refund, decrement that order's remaining refundable cents by the requested `cents`.",
-        "For each accepted refund, compute `fee_cents` as the category policy's `restocking_fee_cents` capped at the requested `cents`, and compute `net_cents = cents - fee_cents`.",
-        "`approved` is ordered in processing order. Each row has keys `id`, `order`, `refund_cents`, `fee_cents`, and `net_cents`.",
-        "`rejected` is ordered in the original input refund order. Each row has keys `id`, `reason`.",
-        "`orders` is ordered by order id ascending. Each row has keys `id` and `remaining_refundable_cents`.",
-        "On success, write exactly one JSON object to stdout and no stderr. Keys: `approved`, `rejected`, `orders`."
-      ]
-    },
-    {
-      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/duplicate-refund-error.js\"",
-      "exit_code": 0,
-      "stdout_contains": ["\"ok\":true"],
-      "stdout_not_contains": [],
-      "contract_refs": [
-        "Before settling any refund, duplicate refund ids are invalid input: exit `2`, write exactly one JSON error object `{ \"error\": \"duplicate_refund_id\", \"id\": string }` to stderr, and write no stdout."
-      ]
-    }
-  ],
-  "forbidden_patterns": [
-    {
-      "pattern": "catch\\s*\\([^)]*\\)\\s*\\{[^}]*return\\s+(null|undefined|''|\\{\\}|\\[\\])",
-      "description": "silent catch returning fallback in settle-refunds path",
-      "files": ["bin/cli.js", "tests/cli.test.js"],
-      "severity": "disqualifier"
-    },
-    {
-      "pattern": "catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}",
-      "description": "empty catch block",
-      "files": ["bin/cli.js", "tests/cli.test.js"],
-      "severity": "disqualifier"
-    }
-  ],
-  "required_files": ["bin/cli.js", "tests/cli.test.js"],
-  "forbidden_files": [],
-  "tier_a_waivers": [],
-  "spec_output_files": ["bin/cli.js", "tests/cli.test.js"],
-  "max_deps_added": 0
-}

package/benchmark/auto-resolve/shadow-fixtures/S6-cli-refund-window-ledger/metadata.json

@@ -1,10 +0,0 @@
-{
-  "id": "S6-cli-refund-window-ledger",
-  "category": "high-risk",
-  "difficulty": "high",
-  "timeout_seconds": 900,
-  "required_tools": ["node"],
-  "browser": false,
-  "deps_change_expected": false,
-  "intent": "Add a refund ledger CLI command that applies category refund windows, priority-ordered refund requests, cumulative per-order refundable balances, duplicate refund rejection, and exact JSON output shape."
-}

package/benchmark/auto-resolve/shadow-fixtures/S6-cli-refund-window-ledger/setup.sh

@@ -1,3 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-# S6 reuses the baseline test-repo state.

package/benchmark/auto-resolve/shadow-fixtures/S6-cli-refund-window-ledger/spec.md

@@ -1,59 +0,0 @@
----
-id: "S6-cli-refund-window-ledger"
-title: "Add refund window ledger command"
-status: planned
-complexity: high
-depends-on: []
----
-
-# S6 Add Refund Window Ledger Command
-
-## Context
-
-Finance operations needs a deterministic CLI command that settles refund
-requests against original orders. The command must combine category refund
-windows, priority ordering, cumulative per-order refundable balances, duplicate
-id rejection, and exact machine-readable output.
-
-## Requirements
-
-- [ ] Add `settle-refunds` to `bin/cli.js`.
-- [ ] Accept `--policies <json>` as a JSON object whose keys are category names and whose values have keys `refund_window_days` and `restocking_fee_cents`.
-- [ ] Accept `--orders <json>` as a JSON array of order objects. Each order has keys `id`, `category`, `paid_cents`, `purchased_on`, and `fulfilled`.
-- [ ] Accept `--refunds <json>` as a JSON array of refund request objects. Each refund has keys `id`, `order`, `cents`, `priority`, and `requested_on`.
-- [ ] Before settling any refund, duplicate refund ids are invalid input: exit `2`, write exactly one JSON error object `{ "error": "duplicate_refund_id", "id": string }` to stderr, and write no stdout.
-- [ ] Process refund requests globally by `priority` descending, then `requested_on` ascending, then original input order ascending.
-- [ ] A refund rejects with reason `unknown_order` when the order does not exist.
-- [ ] A refund rejects with reason `unfulfilled_order` when the order exists but `fulfilled` is not `true`.
-- [ ] A refund rejects with reason `unknown_policy` when the order category has no policy.
-- [ ] A refund rejects with reason `window_expired` when `requested_on` is more than `refund_window_days` after `purchased_on`.
-- [ ] A refund accepts only when the order's remaining refundable cents is at least the requested `cents`.
-- [ ] A rejected refund with reason `over_refund` must not change that order's remaining refundable cents.
-- [ ] For each accepted refund, decrement that order's remaining refundable cents by the requested `cents`.
-- [ ] For each accepted refund, compute `fee_cents` as the category policy's `restocking_fee_cents` capped at the requested `cents`, and compute `net_cents = cents - fee_cents`.
-- [ ] `approved` is ordered in processing order. Each row has keys `id`, `order`, `refund_cents`, `fee_cents`, and `net_cents`.
-- [ ] `rejected` is ordered in the original input refund order. Each row has keys `id`, `reason`.
-- [ ] `orders` is ordered by order id ascending. Each row has keys `id` and `remaining_refundable_cents`.
-- [ ] On success, write exactly one JSON object to stdout and no stderr. Keys: `approved`, `rejected`, `orders`.
-
-## Constraints
-
-- Use only Node.js built-ins; add no npm dependencies.
-- Touch only `bin/cli.js` and `tests/cli.test.js`.
-- Do not silently catch JSON parse or validation errors. Surface invalid input as a user-visible error with nonzero exit.
-- Do not persist refund balances between command invocations.
-- All public money amounts are integer cents.
-
-## Out of Scope
-
-- Reading input from files.
-- Taxes, payment gateway calls, currency conversion, or store-credit issuance.
-- Partial approval of a single refund request.
-- Changing `hello`, `version`, server routes, or package metadata.
-
-## Verification
-
-- `node --test tests/cli.test.js` passes.
-- `node "$BENCH_FIXTURE_DIR/verifiers/priority-refund-ledger.js"` prints `{"ok":true}`.
-- `node "$BENCH_FIXTURE_DIR/verifiers/duplicate-refund-error.js"` prints `{"ok":true}`.
-- Solo-headroom hypothesis: solo_claude is expected to miss cumulative remaining refundable cents or original-order rejected rows under priority-ordered refund settlement; observable command `node "$BENCH_FIXTURE_DIR/verifiers/priority-refund-ledger.js"` exposes the miss.

package/benchmark/auto-resolve/shadow-fixtures/S6-cli-refund-window-ledger/task.txt

@@ -1 +0,0 @@
-Add a `settle-refunds` command to bench-cli. It must read policies, orders, and refund requests from JSON CLI arguments, process refund requests by priority, maintain per-order remaining refundable cents, reject duplicates before processing, and emit exact JSON output.

package/benchmark/auto-resolve/shadow-fixtures/S6-cli-refund-window-ledger/verifiers/duplicate-refund-error.js

@@ -1,41 +0,0 @@
-'use strict';
-const assert = require('node:assert');
-const { spawnSync } = require('node:child_process');
-const path = require('node:path');
-
-const work = process.env.BENCH_WORKDIR || process.cwd();
-const cli = path.join(work, 'bin', 'cli.js');
-
-const policies = JSON.stringify({
-  apparel: { refund_window_days: 45, restocking_fee_cents: 25 }
-});
-const orders = JSON.stringify([
-  { id: 'ord-a', category: 'apparel', paid_cents: 600, purchased_on: '2026-01-10', fulfilled: true }
-]);
-const refunds = JSON.stringify([
-  { id: 'dup', order: 'ord-a', cents: 100, priority: 2, requested_on: '2026-01-11' },
-  { id: 'dup', order: 'ord-a', cents: 100, priority: 1, requested_on: '2026-01-12' }
-]);
-
-const result = spawnSync('node', [
-  cli,
-  'settle-refunds',
-  '--policies',
-  policies,
-  '--orders',
-  orders,
-  '--refunds',
-  refunds
-], {
-  cwd: work,
-  encoding: 'utf8'
-});
-
-assert.strictEqual(result.status, 2, result.stdout || result.stderr);
-assert.strictEqual(result.stdout, '');
-assert.deepStrictEqual(JSON.parse(result.stderr), {
-  error: 'duplicate_refund_id',
-  id: 'dup'
-});
-
-console.log(JSON.stringify({ ok: true }));

package/benchmark/auto-resolve/shadow-fixtures/S6-cli-refund-window-ledger/verifiers/priority-refund-ledger.js

@@ -1,65 +0,0 @@
-'use strict';
-const assert = require('node:assert');
-const { spawnSync } = require('node:child_process');
-const path = require('node:path');
-
-const work = process.env.BENCH_WORKDIR || process.cwd();
-const cli = path.join(work, 'bin', 'cli.js');
-
-const policies = JSON.stringify({
-  electronics: { refund_window_days: 30, restocking_fee_cents: 150 },
-  apparel: { refund_window_days: 45, restocking_fee_cents: 25 }
-});
-const orders = JSON.stringify([
-  { id: 'ord-a', category: 'electronics', paid_cents: 1000, purchased_on: '2026-01-01', fulfilled: true },
-  { id: 'ord-b', category: 'apparel', paid_cents: 600, purchased_on: '2026-01-10', fulfilled: true },
-  { id: 'ord-c', category: 'electronics', paid_cents: 400, purchased_on: '2025-12-01', fulfilled: true },
-  { id: 'ord-d', category: 'apparel', paid_cents: 500, purchased_on: '2026-01-15', fulfilled: false }
-]);
-const refunds = JSON.stringify([
-  { id: 'low-a', order: 'ord-a', cents: 500, priority: 1, requested_on: '2026-01-08' },
-  { id: 'expired-c', order: 'ord-c', cents: 100, priority: 9, requested_on: '2026-02-01' },
-  { id: 'high-a', order: 'ord-a', cents: 800, priority: 10, requested_on: '2026-01-09' },
-  { id: 'unknown', order: 'missing', cents: 50, priority: 8, requested_on: '2026-01-09' },
-  { id: 'unfulfilled', order: 'ord-d', cents: 50, priority: 7, requested_on: '2026-01-20' },
-  { id: 'apparel-ok', order: 'ord-b', cents: 300, priority: 6, requested_on: '2026-01-20' }
-]);
-
-const result = spawnSync('node', [
-  cli,
-  'settle-refunds',
-  '--policies',
-  policies,
-  '--orders',
-  orders,
-  '--refunds',
-  refunds
-], {
-  cwd: work,
-  encoding: 'utf8'
-});
-
-assert.strictEqual(result.status, 0, result.stderr || result.stdout);
-assert.strictEqual(result.stderr, '');
-const parsed = JSON.parse(result.stdout);
-
-assert.deepStrictEqual(parsed, {
-  approved: [
-    { id: 'high-a', order: 'ord-a', refund_cents: 800, fee_cents: 150, net_cents: 650 },
-    { id: 'apparel-ok', order: 'ord-b', refund_cents: 300, fee_cents: 25, net_cents: 275 }
-  ],
-  rejected: [
-    { id: 'low-a', reason: 'over_refund' },
-    { id: 'expired-c', reason: 'window_expired' },
-    { id: 'unknown', reason: 'unknown_order' },
-    { id: 'unfulfilled', reason: 'unfulfilled_order' }
-  ],
-  orders: [
-    { id: 'ord-a', remaining_refundable_cents: 200 },
-    { id: 'ord-b', remaining_refundable_cents: 300 },
-    { id: 'ord-c', remaining_refundable_cents: 400 },
-    { id: 'ord-d', remaining_refundable_cents: 500 }
-  ]
-});
-
-console.log(JSON.stringify({ ok: true }));

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

@@ -1,298 +0,0 @@
-# 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":               "<exact claude model id>",
-      "timestamp":           "2026-04-29T..."
-    },
-    "codex": {
-      "status":              "sign | block",
-      "blocked_ids":         [],
-      "signed_plan_sha256":  "...",
-      "model":               "<exact codex model id>",
-      "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.