devlyn-cli 1.15.0 → 2.1.0

package/benchmark/auto-resolve/scripts/judge.sh

@@ -0,0 +1,359 @@
+#!/usr/bin/env bash
+# judge.sh — Codex (CLI's current flagship, inherited) blind judge for ONE fixture.
+#
+# Usage:
+#   judge.sh --fixture <FID> --run-id <ID>
+#
+# Reads:
+#   results/<run-id>/<fixture>/variant/diff.patch + verify.json
+#   results/<run-id>/<fixture>/bare/diff.patch + verify.json
+#   fixtures/<fixture>/spec.md + expected.json + NOTES.md
+#   RUBRIC.md (stable rubric)
+#
+# Writes:
+#   results/<run-id>/<fixture>/judge.json
+#
+# Blind: A/B assignment randomized per fixture, seed stored in judge.json.
+
+set -euo pipefail
+
+usage() { echo "usage: $0 --fixture <FID> --run-id <ID>"; exit 1; }
+FIXTURE=""; RUN_ID=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --fixture) FIXTURE="$2"; shift 2;;
+    --run-id)  RUN_ID="$2";  shift 2;;
+    *) usage;;
+  esac
+done
+[ -n "$FIXTURE" ] && [ -n "$RUN_ID" ] || usage
+
+BENCH_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+FIX_DIR="$BENCH_ROOT/fixtures/$FIXTURE"
+RES_DIR="$BENCH_ROOT/results/$RUN_ID/$FIXTURE"
+
+# iter-0019: 3 arms — variant (L2), solo_claude (L1), bare (L0). The judge
+# scores all three in a single pass with the same prompt + same model so
+# margin derivations (L2-vs-L0, L1-vs-L0, L2-vs-L1) are calibrated against
+# each other and not against separate judge calls. ARMS_PRESENT enumerates
+# whichever subset actually has artifacts (so a missing arm doesn't abort
+# the whole judge step). Two-arm judge mode is preserved for runs that pre-
+# date iter-0019.
+ARMS_PRESENT=()
+# iter-0033c: l2_gated/l2_forced added for NEW L2 vs NEW L1 measurement.
+# Slot count is still A/B/C max 3 — pair-eligible iter-0033c fixtures supply
+# {solo_claude, l2_gated, l2_forced}; non-pair-eligible fixtures supply
+# {solo_claude, l2_gated}. The blind-shuffle slot mapping below already
+# tolerates arbitrary ARMS_PRESENT counts ≥2.
+for arm in variant solo_claude bare l2_gated l2_forced; do
+  if [ -f "$RES_DIR/$arm/diff.patch" ] && [ -f "$RES_DIR/$arm/verify.json" ]; then
+    ARMS_PRESENT+=("$arm")
+  fi
+done
+if [ ${#ARMS_PRESENT[@]} -lt 2 ]; then
+  echo "judge needs at least 2 arms with diff.patch + verify.json; have: ${ARMS_PRESENT[*]:-(none)}"
+  exit 1
+fi
+for f in "$FIX_DIR/spec.md" "$FIX_DIR/expected.json" "$BENCH_ROOT/RUBRIC.md"; do
+  [ -f "$f" ] || { echo "missing required input: $f"; exit 1; }
+done
+
+# Blind randomization: shuffle ARMS_PRESENT into ABC order. Seed recorded
+# in judge.json so runs are reproducible if rejudged.
+SEED=$RANDOM
+# iter-0019.4: Bash 3.2 compatible (macOS /bin/bash). `mapfile` is Bash 4+
+# only; replaced with while-read loop. The `|| [ -n "$line" ]` guard
+# preserves exact `mapfile -t` behavior on a final unterminated line (Python
+# print() emits trailing \n so this guard is belt-and-suspenders here, but
+# matches mapfile semantics for future producers).
+SLOTS=()
+while IFS= read -r line || [ -n "$line" ]; do
+  SLOTS+=("$line")
+done < <(python3 - "$SEED" "${ARMS_PRESENT[@]}" <<'PY'
+import sys, random
+seed = int(sys.argv[1]); arms = sys.argv[2:]
+random.seed(seed)
+random.shuffle(arms)
+print("\n".join(arms))
+PY
+)
+A_ARM="${SLOTS[0]:-}"
+B_ARM="${SLOTS[1]:-}"
+C_ARM="${SLOTS[2]:-}"
+
+PROMPT_FILE="$RES_DIR/judge-prompt.txt"
+A_DIFF="$RES_DIR/$A_ARM/diff.patch"
+A_VERIFY="$RES_DIR/$A_ARM/verify.json"
+B_DIFF="$RES_DIR/$B_ARM/diff.patch"
+B_VERIFY="$RES_DIR/$B_ARM/verify.json"
+if [ -n "$C_ARM" ]; then
+  C_DIFF="$RES_DIR/$C_ARM/diff.patch"
+  C_VERIFY="$RES_DIR/$C_ARM/verify.json"
+else
+  C_DIFF=""
+  C_VERIFY=""
+fi
+
+# Sanitize diffs so stylistic tells that correlate with variant (e.g.
+# pipeline-commit markers, .devlyn/ archive lines) don't leak to the judge.
+# Judge sees only file-content changes; the transcript, arm label, NOTES.md,
+# and all process artifacts stay out of the prompt.
+python3 - "$PROMPT_FILE" "$FIX_DIR/spec.md" "$FIX_DIR/expected.json" "$BENCH_ROOT/RUBRIC.md" "$A_DIFF" "$B_DIFF" "$A_VERIFY" "$B_VERIFY" "$C_DIFF" "$C_VERIFY" <<'PY'
+import sys, pathlib, re, json
+args = sys.argv[1:]
+out_p, spec_p, exp_p, rubric_p = map(pathlib.Path, args[:4])
+a_diff, b_diff, a_ver, b_ver = map(pathlib.Path, args[4:8])
+c_diff_arg, c_ver_arg = args[8], args[9]
+c_diff = pathlib.Path(c_diff_arg) if c_diff_arg else None
+c_ver = pathlib.Path(c_ver_arg) if c_ver_arg else None
+out = out_p
+spec = spec_p.read_text()
+expected = exp_p.read_text()
+rubric = rubric_p.read_text()
+
+# Strip pipeline-origin tells from the diff before the judge sees it.
+TELLS = [
+    re.compile(r"^diff --git.*\.devlyn/.*$", re.M),
+    re.compile(r"^chore\(pipeline\):.*$", re.M),
+    re.compile(r"^\.devlyn/.*$", re.M),
+    re.compile(r"^Co-Authored-By:.*$", re.M),
+]
+def sanitize(diff: str) -> str:
+    # Drop whole-file hunks under .devlyn/
+    out_lines, skip = [], False
+    for line in diff.splitlines(keepends=True):
+        if line.startswith("diff --git ") and ".devlyn/" in line:
+            skip = True
+            continue
+        if line.startswith("diff --git "):
+            skip = False
+        if skip:
+            continue
+        out_lines.append(line)
+    text = "".join(out_lines)
+    for pat in TELLS:
+        text = pat.sub("", text)
+    return text
+
+# Also strip arm-identifying fields from verify.json before passing to judge.
+def sanitize_verify(path: pathlib.Path) -> str:
+    data = json.loads(path.read_text())
+    # Remove anything that could name the arm
+    data.pop("arm", None)
+    return json.dumps(data, indent=2)
+
+a_diff_text = sanitize(a_diff.read_text())
+b_diff_text = sanitize(b_diff.read_text())
+a_ver_text = sanitize_verify(a_ver)
+b_ver_text = sanitize_verify(b_ver)
+have_c = c_diff is not None
+if have_c:
+    c_diff_text = sanitize(c_diff.read_text())
+    c_ver_text = sanitize_verify(c_ver)
+
+n_arms = 3 if have_c else 2
+arms_phrase = "Three engineers" if have_c else "Two engineers"
+slot_keys = ["a_score", "b_score", "c_score"][:n_arms]
+slot_breakdowns = ["a_breakdown", "b_breakdown", "c_breakdown"][:n_arms]
+slot_letters = ["A", "B", "C"][:n_arms]
+
+# Build the JSON-format hint dynamically so the judge sees the right shape
+# for either 2 or 3 arms. Same scoring rules; same rubric.
+score_lines = ",\n  ".join(f'"{k}": <int 0-100>' for k in slot_keys)
+breakdown_lines = ",\n  ".join(
+    f'"{b}": {{"spec": 0-25, "constraint": 0-25, "scope": 0-25, "quality": 0-25, "notes": "<3-5 bullets>"}}'
+    for b in slot_breakdowns
+)
+findings_keys = ", ".join(f'"{l}": ["..."]' for l in slot_letters)
+dq_keys = ", ".join(f'"{l}": bool' for l in slot_letters)
+dq_reasons = ", ".join(f'"{l}_reason": "..."' for l in slot_letters)
+winner_choices = " | ".join(f'"{l}"' for l in slot_letters) + ' | "tie"'
+
+# Per-arm sections of the prompt
+def section(label: str, diff_text: str, verify_text: str) -> str:
+    return (
+        f"=== IMPLEMENTATION {label} ===\nDiff:\n"
+        f"```diff\n{diff_text}\n```\n"
+        f"Verification results:\n```json\n{verify_text}\n```\n"
+    )
+
+impl_sections = section("A", a_diff_text, a_ver_text) + "\n" + section("B", b_diff_text, b_ver_text)
+if have_c:
+    impl_sections += "\n" + section("C", c_diff_text, c_ver_text)
+
+prompt = f"""You are a blind code-review judge. {arms_phrase} implemented the same spec. You do NOT know which implementation came from which process — grade them only on the merits of the code and its behavior.
+
+Apply the 4-axis rubric from RUBRIC.md below. Each axis is 0-25, total 100. Score every implementation independently — do not let one arm's score anchor another's. The judge's job is to apply the rubric absolutely; relative ordering falls out from the absolute scores.
+
+Return STRICT JSON only — no prose outside the JSON. Format:
+
+{{
+  {score_lines},
+  "winner": {winner_choices},
+  {breakdown_lines},
+  "critical_findings": {{{findings_keys}}},
+  "disqualifiers": {{{dq_keys}, {dq_reasons}}},
+  "overall_reasoning": "<5-8 sentences>"
+}}
+
+=== RUBRIC ===
+{rubric}
+
+=== SPEC ===
+{spec}
+
+=== EXPECTED (machine-readable acceptance) ===
+{expected}
+
+{impl_sections}
+Return the JSON and nothing else.
+"""
+out.write_text(prompt)
+PY
+
+# Invoke Codex — no -m so CLI flagship is inherited. Model identity is
+# recorded from the codex config.toml so rejudging with a newer flagship is
+# traceable. Run from a clean temp CWD so the judge can't peek at project
+# files that would leak arm identity.
+command -v codex >/dev/null 2>&1 || { echo "codex CLI not on PATH; cannot judge"; exit 1; }
+CODEX_CLI_VER=$(codex --version 2>/dev/null || echo "codex-cli unknown")
+JUDGE_MODEL=$(grep -E '^model\s*=' "${HOME}/.codex/config.toml" 2>/dev/null | head -1 | sed -E 's/.*=\s*"?([^"]+)"?.*/\1/')
+[ -z "$JUDGE_MODEL" ] && JUDGE_MODEL="(unknown — codex config.toml not readable)"
+
+JUDGE_CWD="/tmp/judge-$RUN_ID-$FIXTURE"
+rm -rf "$JUDGE_CWD"
+mkdir -p "$JUDGE_CWD"
+
+JUDGE_OUT="$RES_DIR/judge-output.txt"
+set +e
+cat "$PROMPT_FILE" | (cd "$JUDGE_CWD" && codex exec -s read-only --skip-git-repo-check -c model_reasoning_effort=xhigh - ) > "$JUDGE_OUT" 2>&1
+JUDGE_EXIT=$?
+set -e
+rm -rf "$JUDGE_CWD"
+if [ $JUDGE_EXIT -ne 0 ]; then
+  echo "codex exec failed (exit $JUDGE_EXIT); see $JUDGE_OUT"
+  exit 1
+fi
+
+# Extract JSON (codex wraps with banners; pick the last {...} block)
+python3 - "$JUDGE_OUT" "$RES_DIR/judge.json" "$A_ARM" "$B_ARM" "$C_ARM" "$SEED" "$CODEX_CLI_VER" "$JUDGE_MODEL" <<'PY'
+import sys, re, json, pathlib
+out = pathlib.Path(sys.argv[1]).read_text()
+target = pathlib.Path(sys.argv[2])
+a_arm, b_arm, c_arm, seed, codex_ver, judge_model = sys.argv[3:9]
+
+# Extract the last valid judgment JSON. A naive brace-counter breaks on
+# `{`/`}` that appear inside strings (e.g. JS source embedded in the arms'
+# diffs), so use json.JSONDecoder.raw_decode starting at each `{` position
+# and keep the last successful parse with the required keys.
+decoder = json.JSONDecoder()
+brace_positions = [i for i, c in enumerate(out) if c == '{']
+chosen = None
+for pos in reversed(brace_positions):
+    try:
+        obj, _ = decoder.raw_decode(out[pos:])
+    except json.JSONDecodeError:
+        continue
+    if isinstance(obj, dict) and "a_score" in obj and "b_score" in obj:
+        chosen = obj
+        break
+if chosen is None:
+    raise SystemExit(f"no valid JSON in judge output; see {sys.argv[1]}")
+
+# Decode blind labels — record full mapping so summary code can iterate
+mapping = {"A": a_arm, "B": b_arm}
+if c_arm:
+    mapping["C"] = c_arm
+chosen["_blind_mapping"] = {**mapping, "seed": int(seed)}
+chosen["_judge_cli"] = codex_ver.strip()
+chosen["_judge_model"] = judge_model.strip()
+
+# iter-0023 — axis breakdown validation. Rubric axes are 0-25 (RUBRIC.md
+# "Scoring — 4 axes, 25 points each"). Past runs (iter-0020 F9) recorded
+# `quality: -1` because judge LLM occasionally emits sentinel/negative
+# values; ship-gate then averaged invalid cells. Detect, clamp to [0, 25],
+# and record the invalid cells under `_axis_validation` so downstream
+# consumers can refuse to trust that fixture's margin.
+AXIS_KEYS = ("spec", "constraint", "scope", "quality")
+BREAKDOWN_KEYS = ("a_breakdown", "b_breakdown", "c_breakdown")
+axis_invalid_cells = []
+for bk in BREAKDOWN_KEYS:
+    if bk not in chosen or not isinstance(chosen[bk], dict):
+        continue
+    for axis in AXIS_KEYS:
+        if axis not in chosen[bk]:
+            continue
+        v = chosen[bk][axis]
+        if not isinstance(v, (int, float)) or v < 0 or v > 25:
+            axis_invalid_cells.append({"breakdown": bk, "axis": axis, "value": v})
+            chosen[bk][axis] = max(0, min(25, int(v) if isinstance(v, (int, float)) else 0))
+chosen["_axis_validation"] = {
+    "out_of_range_count": len(axis_invalid_cells),
+    "out_of_range_cells": axis_invalid_cells,
+    "axis_range": [0, 25],
+}
+if axis_invalid_cells:
+    sys.stderr.write(
+        f"[judge.sh] WARNING: {len(axis_invalid_cells)} axis cell(s) out of [0,25] "
+        f"clamped: {axis_invalid_cells}\n"
+    )
+
+# scores_by_arm: arm-name → score, computed from the blind A/B/C scores.
+# This is the canonical 3-arm-aware shape the report consumer reads. The
+# legacy variant_score / bare_score / margin fields below are derived from
+# scores_by_arm for backward compatibility with pre-iter-0019 callers.
+scores_by_arm = {}
+slot_keys = ["a_score", "b_score", "c_score"]
+slot_letters = ["A", "B", "C"]
+for letter, key in zip(slot_letters, slot_keys):
+    arm = mapping.get(letter)
+    if arm is not None and key in chosen:
+        scores_by_arm[arm] = chosen[key]
+chosen["scores_by_arm"] = scores_by_arm
+
+# Per-letter critical_findings / disqualifiers also rotated to per-arm.
+findings_letters = chosen.get("critical_findings", {}) or {}
+findings_by_arm = {mapping[l]: findings_letters.get(l, []) for l in slot_letters if l in mapping}
+chosen["findings_by_arm"] = findings_by_arm
+
+dq_letters = chosen.get("disqualifiers", {}) or {}
+dq_by_arm = {}
+for l in slot_letters:
+    if l not in mapping:
+        continue
+    arm = mapping[l]
+    dq_by_arm[arm] = {
+        "disqualifier": bool(dq_letters.get(l, False)),
+        "reason": str(dq_letters.get(f"{l}_reason", "") or ""),
+    }
+chosen["disqualifiers_by_arm"] = dq_by_arm
+
+# Pairwise margins (positive = first arm beat second).
+def margin(left: str, right: str):
+    if left in scores_by_arm and right in scores_by_arm:
+        return scores_by_arm[left] - scores_by_arm[right]
+    return None
+
+chosen["margins"] = {
+    "variant_over_bare":   margin("variant", "bare"),
+    "solo_over_bare":      margin("solo_claude", "bare"),
+    "variant_over_solo":   margin("variant", "solo_claude"),
+}
+
+# Translate winner letter to arm
+w = chosen.get("winner")
+chosen["winner_arm"] = mapping.get(w, "tie") if w in mapping else "tie"
+
+# Legacy 2-arm fields preserved so older summary code still parses. When
+# solo_claude is present, variant/bare margin is derived from scores_by_arm.
+chosen["variant_score"] = scores_by_arm.get("variant")
+chosen["bare_score"]    = scores_by_arm.get("bare")
+if chosen.get("variant_score") is not None and chosen.get("bare_score") is not None:
+    chosen["margin"] = chosen["variant_score"] - chosen["bare_score"]
+
+target.write_text(json.dumps(chosen, indent=2))
+parts = [f"{arm}={s}" for arm, s in scores_by_arm.items()]
+mline = chosen.get("margins") or {}
+mparts = [f"{k}={v:+d}" for k, v in mline.items() if v is not None]
+print(f"[judge] " + " ".join(parts) + ("  | " + " ".join(mparts) if mparts else ""))
+PY

package/benchmark/auto-resolve/scripts/oracle-scope-tier-a.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""
+oracle-scope-tier-a.py — deterministic detector for categorical file-path
+violations. Flags touches of paths that are never legitimately needed by an
+implementation task (planning docs, CI config, dep-install output, runtime
+artifacts, env/secret files) and lockfile deletions.
+
+Complementary to oracle-test-fidelity.py, which handles weakening INSIDE
+existing test files. This oracle only cares about WHICH files are touched.
+
+Path matching uses fnmatch with normalized, repo-root-relative paths.
+`docs/**` matches `docs/<anything>` but NOT `server/docs/readme.md` — the
+anchoring is left-only, which is what we want. Per-oracle convention
+documented here; step 1's content oracle uses regex instead.
+
+Fixtures can waive any Tier A pattern via `expected.json::tier_a_waivers`
+(list of fnmatch globs). Load-bearing case: F9 e2e-ideate-to-preflight
+legitimately creates docs/VISION.md, docs/ROADMAP.md, docs/roadmap/**.
+
+Step 2 scope: findings only. Scoring integration is a later step.
+"""
+import argparse
+import fnmatch
+import json
+import os
+import pathlib
+import subprocess
+import sys
+
+ORACLE_NAME = "scope-tier-a"
+
+# iter-0022: stable category enumeration. See header comment in
+# oracle-test-fidelity.py for the edit-discipline rules. tier-a-violation is
+# ONE umbrella category covering the 5 path-glob groups (planning-doc,
+# ci-config, node-modules, test-results-or-coverage, env-secrets) plus the 2
+# basename rules (.log suffix, .env/secrets. prefix); splitting into 7 sub-
+# categories was rejected during iter-0022 R0 because the oracle emits a
+# single finding-row per touched path regardless.
+CATEGORIES = [
+    {
+        "id": "scope-tier-a:lockfile-deletion",
+        "severity": "hard",
+        "applies_when": "scaffold contains a lockfile (package-lock.json / yarn.lock / pnpm-lock.yaml / bun.lock / bun.lockb)",
+        "operational_check": "variant arm MUST NOT delete a scaffold-present lockfile",
+        "evidence_source_files": ["oracle-scope-tier-a.py"],
+    },
+    {
+        "id": "scope-tier-a:tier-a-violation",
+        "severity": "hard",
+        "applies_when": "any fixture (the protected paths exist conceptually for every JS/TS repo)",
+        "operational_check": "variant arm MUST NOT add or modify paths matching: docs/roadmap/** | docs/VISION.md | docs/ROADMAP.md | .github/** | node_modules/** | **/node_modules/** | test-results/** | coverage/** | .nyc_output/** | basename suffix .log | basename prefix .env or secrets.",
+        "evidence_source_files": ["oracle-scope-tier-a.py"],
+    },
+]
+
+# Path globs — fnmatch-style, left-anchored. `**` is treated as `*` by
+# fnmatch (no special recursive semantics), so `docs/roadmap/**` matches
+# `docs/roadmap/anything/nested/here` because `*` matches `/` in fnmatch.
+TIER_A_PATH_GLOBS = [
+    # Planning docs — implementation tasks should never edit these.
+    "docs/roadmap/**",
+    "docs/VISION.md",
+    "docs/ROADMAP.md",
+    # CI / repo-wide config.
+    ".github/**",
+    # Install outputs.
+    "node_modules/**",
+    "**/node_modules/**",
+    # Runtime / test artifacts.
+    "test-results/**",
+    "coverage/**",
+    ".nyc_output/**",
+]
+
+# Basename suffix matches (run against os.path.basename so any depth hits).
+TIER_A_BASENAME_SUFFIXES = {
+    ".log",
+}
+
+# Basename prefix matches. `.env` → `.env`, `.env.local`, `.env.production`.
+# `secrets.` → `secrets.json`, `secrets.yaml`.
+TIER_A_BASENAME_PREFIXES = {
+    ".env",
+    "secrets.",
+}
+
+# Lockfiles — modification is legitimate when deps change; deletion is not.
+# Only flag D status AND only if the file existed at scaffold.
+LOCKFILE_NAMES = {
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "bun.lock",
+    "bun.lockb",
+}
+
+
+def run_git(args, cwd):
+    return subprocess.run(
+        ["git", *args], cwd=cwd, capture_output=True, text=True
+    )
+
+
+def git_diff_status(scaffold_sha, cwd):
+    r = run_git(["diff", "--name-status", "-M", scaffold_sha], cwd=cwd)
+    entries = []
+    for line in r.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split("\t")
+        status = parts[0]
+        if status.startswith("R") or status.startswith("C"):
+            if len(parts) >= 3:
+                # Treat as new path; keep R/C letter for reporting.
+                entries.append((status[0], parts[2]))
+        else:
+            if len(parts) >= 2:
+                entries.append((status, parts[1]))
+    return entries
+
+
+def existed_at_scaffold(scaffold_sha, path, cwd):
+    r = run_git(["cat-file", "-e", f"{scaffold_sha}:{path}"], cwd=cwd)
+    return r.returncode == 0
+
+
+def matches_any_glob(path, patterns):
+    for p in patterns:
+        if fnmatch.fnmatch(path, p):
+            return p
+    return None
+
+
+def matches_basename(path, suffixes, prefixes):
+    base = os.path.basename(path)
+    for s in suffixes:
+        if base.endswith(s):
+            return f"*{s}"
+    for p in prefixes:
+        if base.startswith(p):
+            return f"{p}*"
+    return None
+
+
+def is_waived(path, waivers):
+    for w in waivers:
+        if fnmatch.fnmatch(path, w):
+            return True
+    return False
+
+
+def analyze(work_dir, scaffold_sha, waivers, fixture_id=None):
+    findings = []
+    entries = git_diff_status(scaffold_sha, work_dir)
+
+    # Structural exemption: every benchmark fixture has its own spec at
+    # docs/roadmap/phase-*/<fixture_id>.md, and auto-resolve's DOCS phase
+    # Job 1 legitimately flips its frontmatter status. That flip is a
+    # skill feature, not a scope violation — always exempt regardless of
+    # per-fixture waivers.
+    own_spec_globs = []
+    if fixture_id:
+        own_spec_globs.append(f"docs/roadmap/phase-*/{fixture_id}.md")
+
+    for status, path in entries:
+        if is_waived(path, waivers):
+            continue
+        if is_waived(path, own_spec_globs):
+            continue
+
+        # Lockfile deletion — only when file existed at scaffold.
+        if status == "D" and os.path.basename(path) in LOCKFILE_NAMES:
+            if existed_at_scaffold(scaffold_sha, path, work_dir):
+                findings.append({
+                    "file": path,
+                    "type": "lockfile-deletion",
+                    "severity": "hard",
+                    "status": status,
+                    "verdict": "Lockfile deleted (existed at scaffold)",
+                })
+            continue
+
+        # For categorical path violations, only flag when the arm ADDED or
+        # MODIFIED (including rename/copy). Pure deletion of a non-lockfile
+        # Tier A path would also be suspicious but is rare in practice and
+        # overlaps with test-fidelity; leave for a later iteration if needed.
+        if status not in ("A", "M", "R", "C"):
+            continue
+
+        matched = matches_any_glob(path, TIER_A_PATH_GLOBS)
+        if matched is None:
+            matched = matches_basename(
+                path, TIER_A_BASENAME_SUFFIXES, TIER_A_BASENAME_PREFIXES
+            )
+        if matched is None:
+            continue
+
+        findings.append({
+            "file": path,
+            "type": "tier-a-violation",
+            "severity": "hard",
+            "status": status,
+            "matched_pattern": matched,
+            "verdict": "Touched a path categorically outside implementation scope",
+        })
+
+    return findings
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--work")
+    ap.add_argument("--scaffold")
+    ap.add_argument(
+        "--expected",
+        help="Path to fixture expected.json (for tier_a_waivers)",
+        default=None,
+    )
+    ap.add_argument(
+        "--list-categories",
+        action="store_true",
+        help="Emit the stable oracle CATEGORIES enum as JSON and exit (iter-0022).",
+    )
+    args = ap.parse_args()
+
+    if args.list_categories:
+        print(json.dumps({"oracle": ORACLE_NAME, "categories": CATEGORIES}, indent=2, sort_keys=True))
+        return
+
+    if not args.work or not args.scaffold:
+        ap.error("--work and --scaffold are required unless --list-categories is set")
+
+    waivers = []
+    fixture_id = None
+    if args.expected:
+        exp_path = pathlib.Path(args.expected)
+        # fixture_id = parent directory name of expected.json
+        fixture_id = exp_path.parent.name
+        try:
+            expected = json.loads(exp_path.read_text())
+            raw = expected.get("tier_a_waivers", [])
+            if isinstance(raw, list):
+                waivers = [w for w in raw if isinstance(w, str)]
+        except (OSError, json.JSONDecodeError) as e:
+            sys.stderr.write(
+                f"[oracle-scope-tier-a] could not read waivers from {args.expected}: {e}\n"
+            )
+
+    findings = analyze(args.work, args.scaffold, waivers, fixture_id=fixture_id)
+    print(json.dumps({
+        "oracle": "scope-tier-a",
+        "waivers": waivers,
+        "fixture_id": fixture_id,
+        "findings": findings,
+    }, indent=2))
+
+
+if __name__ == "__main__":
+    main()