Design: define reward calculation, penalties, PolicyHint, and calibration

[devkade]

Design: define reward calculation, penalties, PolicyHint, and calibration

Parent: #167
Related: #172, #120

Summary

Define how Ilchul converts EvaluationResult and runtime outcomes into RewardRecord records, penalties, PolicyHint values, and simulator calibration inputs.

Scope

Define:

• reward calculation formula;
• metric-to-reward mapping;
• penalty taxonomy;
• PolicyHint schema;
• prediction-vs-actual comparison;
• calibration data model;
• anti-Goodhart checks;
• human-approved objective-weight calibration flow.

Non-goals

• No automatic objective weight mutation.
• No runtime plugin/module retirement behavior.
• No hidden hard-blocking based on reward alone.

Acceptance criteria

• Reward formula is documented.
• Penalty taxonomy is documented.
• Policy hint schema is documented.
• Calibration flow from prediction-vs-actual is described.
• Anti-Goodhart checks are tied to docs/runcontract-harness-evaluator.md.
• Human-approved objective calibration is explicitly required.

Verification

• Worked examples for successful run, repair-heavy run, and rejected run.
• Design review against feat: add metadata-only harness module registry and retirement signals #120 metadata-only registry boundary.

[devkade]

Design decision

needs-design is resolved by #167's Development Order and the shallow-first rule.

Decisions:

• Design: define reward calculation, penalties, PolicyHint, and calibration #189 is shallow-first and should not block the runtime MVP.
• MVP learning records RewardRecord, PredictionDelta, penalties, and advisory PolicyHint values only after Sub-roadmap: DAG runtime phase 3 — worker execution, heartbeat, and evidence-gated completion #196 produces real runtime evidence.
• Reward and policy hints cannot silently change runtime behavior.
• Objective-weight changes require human-approved calibration.
• Anti-Goodhart checks are guardrails and evidence signals, not autonomous policy mutation.

Implementation can proceed as Step 7 of #167 after #196 evidence exists.