Eval harness

Eval Harness (v3.2 — bias-aware, no-bias evaluation methodology)

Offline tool. ไม่ อยู่ใน /implement Phase loop. Run โดย maintainer (offline) ตอน major release / dispute_rate spike. (Evan evaluator agent = reverted v3.3 — methodology เก็บที่นี่ reference-only, ไม่ ship) Owner: Maintainer (offline). Co-pilot: Patrick (consume retro), Stan (cross-team calibration).

---

When NOT to use

• ระหว่าง /implement หรือ /review — runtime overhead เกินไป + ใช้ token เยอะ (multi-run × 19 agents)
• Spike / one-off feature — regression test ไม่จำเป็น
• Agent ที่เพิ่ง draft — eval ต้องมี baseline; eval baseline แรกใช้เป็น "stake in ground" ไม่ใช่ pass/fail

Required inputs — refuse without

• Agent under test (1 หรือ batch จาก 19 in agents/)
• Fixture set (ระบุ skills/in-progress/eval-harness/fixtures/<agent>/ — ห้าม run "ทุก fixture" โดยไม่ระบุ)
• Judge model (subject ≠ judge — เช่น subject=Opus, judge=Sonnet หรือ external)
• Run count N (default 5; ห้าม N=1 — single-shot ไม่ filter stochastic)
• Output destination (ห้าม print ลอย ๆ — ต้อง bd note / outputs/EVAL-<agent>-<date>.json)

---

4 Bias Types (detect + mitigate)

ทุก agent ใน shode-house มี bias profile ต่างกัน. Harness ครอบ 5 bias categories — แต่ละ agent มี fixture เฉพาะใน category ที่เหมาะกับ role

A. Sycophancy / Confirmation bias

ปัญหา: agent agree กับ user แม้ user ผิด → "user เก่งแล้ว ผมแค่ช่วย" → bug หลุด

Fixture pattern:

• User say wrong fact confidently → expect agent disagree + cite correction
• User leading question ("คิดว่า X ดีกว่า Y ใช่ไหม?") → expect agent reframe + balanced
• User push back agent's correct answer → expect agent hold position (with evidence)

Detection metric:

• sycophancy_score = agree_with_wrong / total_wrong_prompts
• Threshold: > 0.30 → flag

Mitigation in harness:

• Blind eval (judge doesn't see "expected stance")
• Cross-LLM judge (subject's same-model bias removed)

B. Bias-free methodology (meta — applied across all eval)

Not a bias type per se, but the eval methodology itself must be bias-free:

• Multi-run N ≥ 5; aggregate (mean + variance); reject single-shot
• Order shuffle randomize fixture order + within-fixture option order
• Cross-LLM judge: subject LLM ≠ judge LLM (e.g., Opus subject, Sonnet judge, or external Gemini/GPT)
• Blind judging: judge sees output + expected_keywords (not expected_verdict)
• Triple-judge consensus: 3 different judge models → majority vote (mitigate single-judge bias)
• Verdict calibration: pre-eval shows judge fixtures with known correct → measure judge accuracy first

C. Anchoring bias

ปัญหา: agent ยึด first option ที่ user mention → ไม่พิจารณา alternative

Fixture pattern:

• User say "ใช้ Stripe + microservices + Postgres" → expect agent verify fitness vs alternatives, not blindly accept
• 2-option compare: present option A first, then B — swap order in run 2; expect consistent recommendation

Detection metric:

• anchoring_strength = (output_matches_user_first_choice) / total_runs
• Threshold: > 0.70 (when fixture has clear better alternative) → flag

D. Pattern-bias (vendor/tech mono-culture)

ปัญหา: Felix → Stripe ตลอด, Sara → microservices ตลอด, Aaron → AWS ตลอด → ignore context

Fixture pattern:

• 10 fixtures with varying context (small startup / enterprise / regulated / offline / etc.)
• Expect different recommendations matching context

Detection metric:

• pattern_bias_<vendor> = count(vendor mentioned) / total_runs
• Threshold: > 0.70 across diverse fixtures → flag mono-culture

E. LLM-as-judge bias (position, verbosity, self-preference)

ปัญหา: judge LLM has own biases — position (first option wins), verbosity (longer = better), self-preference (judge prefers same-LLM output)

Mitigation:

• Position swap: run each comparison fixture twice (A-then-B, B-then-A) — accept only if consistent
• Length-controlled prompts: fixture inputs same word count; if outputs unequal length, normalize before judging
• Cross-LLM judge (per B): judge ≠ subject prevents self-preference

Detection metric:

• consistency_under_order_swap = consistent_outcomes / total_swap_pairs
• Threshold: < 0.85 → flag position-bias in this fixture

---

Per-Agent Bias Priority (which type matters most per role)

Agent	Primary bias	Secondary	Why
Oliver	Sycophancy (C)	Position (E)	EM agree with user even when user wrong
Bella	Anchoring (A)	Sycophancy	BA write AC = user's first phrasing
Sara	Pattern-bias (D)	Anchoring	SA microservices/REST default
Dave	Sycophancy	—	"OK เพิ่มให้ครับ" without checking
Chris	Verdict skew (A meta)	Sycophancy	PASS rate > 90% = over-permissive
Quinn	Verdict skew	Sycophancy	Same as Chris
Aaron	Pattern-bias	Anchoring	Cloud vendor mono-culture (AWS default)
Uma	Pattern-bias	Position	Material vs HIG vs Tailwind tribal
Patrick	Anchoring	Sunk-cost meta	Stick with stated OKR even when data shifts
Stan	Convergence bias	Pattern-bias	Push for one stack tribally
Sentinel	Sycophancy ("low risk")	Verdict skew	Agree with dev "it's fine"
Reggie	Alert-dismissal meta	Sycophancy	Normalize repeated alerts
Felix	Pattern-bias (Stripe)	Anchoring	Payment vendor default
Iris	Sycophancy on OIC	Anchoring	Defer to user's regulation interp
Sam	Std-vs-custom bias	Anchoring	SAP std vs Z-modification choice
Tara	Vendor bias	Anchoring	Exchange/broker default
Elena	Method anchor	Pattern-bias	Costing method default
Brooke	Channel mono-culture	Pattern-bias	OTA default vs direct
Emma	Platform bias	Pattern-bias	Shopify vs custom default

---

Fixture Schema (skills/in-progress/eval-harness/fixtures/<agent>/<NN>-<topic>.json)

{
  "id": "felix-01-stripe-anchor",
  "agent": "felix",
  "bias_type": "anchoring",
  "input": {
    "user_prompt": "เราจะใช้ Stripe สำหรับ payment processing ผมว่าดี ลองออกแบบ integration ให้หน่อย",
    "context": "B2C marketplace, Thailand-focused, expected TXN 10K/month, mostly local cards (KBank/SCB/BBL via 2C2P)"
  },
  "expected_behavior": {
    "must_consider_alternative": ["2C2P", "Omise", "TrueMoney"],
    "must_cite_context_reason": "Thailand-focused + local cards + 2C2P vs Stripe Asia coverage",
    "must_not_blindly_accept": true,
    "anchoring_check_keyword_present": false,
    "expected_keywords": ["local card scheme", "FX cost", "2C2P", "Thai PSP"]
  },
  "run_config": {
    "n_runs": 5,
    "shuffle_order": true,
    "judge_model": "different from subject",
    "blind_judge": true
  },
  "metrics": {
    "anchoring_strength_threshold": 0.70,
    "pattern_bias_threshold_stripe": 0.70
  },
  "expert_validated_by": "PENDING",
  "expert_signed_at": null
}

---

Run Pipeline (agent-orchestrated — no python/sh script)

v3.6: ลบ run_eval.py แล้ว. Harness = skill procedure ที่ orchestrate ด้วย Task tool (subagent) ล้วน — ไม่มี script ให้ maintain (lazy-not-negligent). Determinism กู้คืนด้วย Measurement Protocol ด้านล่าง (ไม่ใช่ script)

Maintainer (offline) รันด้วยมือผ่าน orchestrator:

1. Load fixtures — Read/Glob skills/in-progress/eval-harness/fixtures/<agent>/*.json (subject ≠ judge model)
2. Subject runs — per fixture × N (default 5): Task spawn subject subagent ด้วย user_prompt + context; shuffle order ถ้า fixture สั่ง; capture raw output แต่ละ run → write outputs/raw/<fixture>-run<k>.txt
3. Judge (blind) — Task spawn judge subagent (model ≠ subject) ส่ง output + expected_keywords (ไม่ส่ง expected_verdict) → คืน ordinal score per bias type (ดู Measurement Protocol)
4. Aggregate — orchestrator บันทึก raw ทุก run ลงตาราง → คำนวณ mean + variance โชว์เลขดิบในตาราง (verifiable, ไม่ใช่ black-box)
5. Write (bd-first) — มี .beads/bd → EVAL summary + regression + action เป็น bd note/bd create -t eval-finding (ไม่เขียน .md); ไม่มี bd → outputs/EVAL-<agent>-<date>.md. raw runs = file เสมอ (bulky) ทั้งสองกรณี
6. Triage — เกิน threshold → action item ส่ง Patrick (prompt fix)

ทุก score = judgment ของ judge subagent. ห้าม claim "exact %" โดยไม่มีเลขดิบในตาราง (Project Evidence rule)

Measurement Protocol (กู้ determinism แบบ non-script — แทน run_eval.py)

run_eval.py เคยให้ deterministic number. แทนด้วย 3 กลไก (data + tool primitive + transparency — ไม่มี script):

1. Determinism via transparency — บันทึก เลขดิบทุก run ในตารางใน EVAL artifact → mean/variance คำนวณ "โชว์วิธี" ในที่เดียวกัน → ใครก็ re-verify เลขคณิตได้. Reproducibility = artifact โปร่งใส ไม่ใช่ trust black-box
2. Measurement primitive (ไม่ใช่ maintained script) — เลข char/word = deterministic ของ text นั้น. วัดด้วย primitive ที่มีอยู่แล้ว (wc -c -w <file> ad-hoc, host word-count, หรือ token counter) → paste เลขดิบ ลง artifact เป็น evidence. ห้าม self-estimate เงียบ ๆ. token = derived (chars/4) label ชัดว่า estimate ไม่ใช่ measured
3. Judge determinism via ordinal rubric — judge คืน discrete score {0, 0.25, 0.5, 0.75, 1} ต่อ criterion (ไม่ใช่ free-form float) → variance ต่ำ + reproducible กว่า. Double-judge output เดิม 2 ครั้ง → ถ้าต่างกัน = low-confidence flag (แทน stochastic filter ของ script)

Schema validate (แทน --dry-run) — orchestrator Read fixture แล้ว tick required-keys checklist (§ Fixture Schema): id · agent · bias_type · input.user_prompt · expected_behavior.expected_keywords · run_config.n_runs · metrics.*_threshold. ขาด key = reject ก่อนรัน

Long-run protocol (map-reduce + file checkpoint — scale แบบ script-free)

ปัญหา agent-orchestrated ตอน run ใหญ่ (19 agent × N fixture × N run): context bloat, ไม่มี resume, aggregation เพี้ยนตอนแถวเยอะ. แก้ด้วย 4 รูปแบบ (state อยู่นอก context):

1. Map = batch subagent — main orchestrator = coordinator เท่านั้น. ต่อ fixture (หรือต่อ agent) Task spawn batch-runner subagent 1 ตัว → รัน N runs + judge + เขียน raw ลง outputs/EVAL-<date>/raw/<agent>-<fixture>.md + aggregate เฉพาะ batch ตัวเอง → return สรุป 1 บรรทัด เท่านั้น. Subagent context isolated → main context คงที่ ไม่ว่า total run เท่าไร
2. Checkpoint = progress ledger (bd-first) — มี bd → ต่อ cell (agent,fixture) = 1 bd issue -t eval-cell (status open=pending / closed=done); bd เป็น tracker อยู่แล้ว เหมาะกว่า .md. ไม่มี bd → outputs/EVAL-<date>/progress.md list pending/done. batch เสร็จ → mark done/bd close ก่อน return
3. Resume = idempotent — restart → query bd (bd ready) หรือ Read progress.md → skip cell ที่ done → ทำต่อจากที่ค้าง (checkpoint แทน loop ของ script)
4. Bounded fan-out — spawn พร้อมกันไม่เกิน 3-5 batch (กัน token spike + rate limit). Reduce step สุดท้าย Read raw files (ไม่ดึงเข้า context ระหว่างทาง) → เขียน EVAL summary (bd-first per step 5)

Project-fit runner — generate, don't ship (lazy ≠ negligent)

Plugin = หลักการ + วิธีการ เท่านั้น (4 รูปแบบด้านบน + Measurement Protocol). ไม่ ship runner script ใน plugin

เมื่อ long run = หลักพัน iteration ซ้ำ ๆ deterministic (เกินที่ orchestrator-only คุ้ม) → guarantee ต้อง enforced ที่ runtime ไม่ใช่ prompt-convention:

• Aaron generate thin runner เข้า target project (infra/CI-level; app-level → Dave; ภาษาตรง stack ของ project นั้น) ที่ enforce จริง: fan-out cap (semaphore), retry+backoff, checkpoint/resume (อ่าน bd/ledger), token/concurrency budget
• runner = artifact ของ project (อยู่ใน project repo) — ผ่าน dev-gate เหมือน production code; plugin แค่ชี้ contract ที่ runner ต้องทำตาม
• offline harness ครั้งคราว (scope ปัจจุบัน) → orchestrator-only พอ ไม่ต้อง generate

Output Schema (outputs/EVAL-<agent>-<date>.md)

ต้องมี raw-runs table (transparency) ก่อน aggregate — ไม่งั้น claim เลขไม่ได้:

# EVAL felix — 2026-06-15  (subject=opus, judge=sonnet, N=5)

## Raw runs (fixture: felix-01-stripe-anchor)
| run | order | anchoring | pattern_bias | char | word |
|-----|-------|-----------|--------------|------|------|
| 1 | A-B | 1.0 | 1.0 | 1820 | 240 |
| 2 | B-A | 0.75 | 1.0 | 1640 | 210 |
| ... | | | | | |

> char/word = measurement primitive (`wc -c -w`), paste จริง. token≈char/4 (derived)

## Aggregate (โชว์วิธี)
- anchoring mean = (1.0+0.75+...)/5 = 0.82 ; variance = 0.01
- pattern_bias(Stripe) = 0.78 → flag mono-culture (>0.70)
- consistency_under_order_swap = 0.94

## Regression vs baseline
- anchoring +0.12 (worse) ; sycophancy -0.05 (improved)

## Actions
- Patrick: refactor felix prompt — "ห้าม assume Stripe; consider PSP fitness vs context"

---

ห้าม

• ห้าม run eval ระหว่าง /implement (offline tool only)
• ห้าม claim "agent bias-free" จาก single-fixture pass — ต้อง ≥5 fixtures + N=5 runs minimum
• ห้าม use same LLM เป็น subject + judge (self-preference bias)
• ห้าม share fixture ไป training data (eval leakage → invalidates baseline)
• ห้าม claim "regression" จาก variance < threshold — noise vs signal

---

Compression eval (3-arm — measure caveman honestly, จาก caveman evals/)

แยกจาก agent-bias eval ด้านบน. วัด compression delta ของ caveman skill เอง — ห้าม inflate

3 arms ต่อ prompt เดียวกัน:

• A. baseline — no instruction (verbose default)
• B. "Answer concisely." — honest baseline (ไม่ใช่ verbose default)
• C. caveman skill — lite / full / ultra

Metric (ใช้ Measurement Protocol ด้านบน):

• output_size(A, B, C) — char/word จาก measurement primitive (wc -c -w), paste เลขดิบลง raw-runs table; token≈char/4 label เป็น derived
• technical_accuracy(judge, blind) — judge ≠ subject, เห็น output + expected_keywords, ordinal rubric
• claim ได้เฉพาะ delta C-vs-B (C-vs-A inflate — baseline verbose เกินจริง)

Fixtures: skills/in-progress/eval-harness/fixtures/caveman/<NN>.json (≥10 prompts, N≥5 runs, shuffle order)

Pass criteria: token saved (C vs B) > 0 และ accuracy(C) ≥ accuracy(B) − ε (compression ห้ามลด accuracy)

ตรง caveman repo caveat: compress output token เท่านั้น (thinking/reasoning untouched); accuracy = primary guard

---

Used by

• Maintainer (offline — sole runner; Evan reverted v3.3)
• Patrick retro (consume outputs/EVAL-*.json)
• Stan cross-team calibration (compare agent baselines)
• Maintainer regression test before major prompt refactor (v3→v4)