# Recent Evaluation Freshness And Feishu Notification

## Current Design

- The GitHub Focus Issue and its append-only checkpoints are the canonical
  state for the Daily Recent Optimizer.
- A scheduled run may currently reuse and re-gate a complete candidate from an
  older evaluation base instead of executing the Focus cases on current
  `main`.
- Baseline and challenger outputs are stored inside their stage checkpoints,
  but there is no explicit latest-case-results checkpoint for the next run.
- The optimizer CronJob prints one JSON result to its Pod log. It does not send
  a Feishu completion message and does not receive the Feishu app credentials.
- Dry-run case input intentionally preserves the historical Jira reply cutoff.
  Later support replies remain excluded from the simulated answer input.

## Risks

- A successful Kubernetes Job can report a historical `candidate_rejected`
  result even though newer code or skills already fixed the observed problem.
- Reusing a cached baseline can also hide changes in the current Jira payload
  or produce the same stale case packet for the next optimizer attempt.
- Adding later Jira support replies to the replay input would leak the answer
  and invalidate the evaluation.
- A Feishu retry must not create duplicate messages or broaden the CronJob into
  Jira, customer-reply, merge, deployment, or production-operation writes.
- Notification credentials must remain Secret references; no credential value
  may enter the repository or a checkpoint.

## Target Contract

```text
current main + current Jira fetch + historical replay cutoff
  -> fresh baseline evaluation
  -> append latest case_refresh checkpoint
  -> current-base candidate only
  -> full tests
  -> fresh challenger evaluation
  -> append latest case_refresh checkpoint
  -> candidate gate / Draft PR
  -> idempotent Feishu run summary
```

- Every optimizer invocation that reaches evaluation executes a fresh baseline
  on the current base SHA. A stored baseline is provenance, not a cache for a
  later scheduled run.
- An existing Draft PR suppresses candidate creation only after the fresh
  baseline and `case_refresh`; it cannot suppress the day's evaluation.
- Automatic resume is limited to candidates created from the current base SHA.
  Historical candidates and challengers remain readable evidence but are not
  automatically re-gated after `main` advances.
- Every completed baseline or challenger, including an evaluation with failed
  cases, appends a `case_refresh` checkpoint containing the bounded evaluation
  artifact, source stage, base SHA, attempt, and optional candidate SHA.
- The next candidate analysis receives the latest bounded `case_refresh`
  results plus prior-attempt evidence. It never receives reply bodies,
  workspace paths, credentials, or post-cutoff support answers.
- A resumed current-base candidate reruns its challenger against the newly
  refreshed Jira/evaluation state; an older challenger is not reused as the
  current result.
- The optimizer sends one compact Feishu message for every terminal result and
  makes a best-effort failure notification for thrown errors. A normal result
  contains the Beijing evaluation date, Focus problem, applied solution, and a
  quantified effect. The effect counts unique improved issue keys from the
  before/after candidate gate and separately reports current target/control
  cases whose assessment is `criteria_met`; execution success counts are never
  presented as quality improvements. Status, Focus ID, base SHA, refresh state,
  and unrelated links remain machine evidence and are not shown in the message.
- A `focus_ready_to_close` result is explicitly labeled as a closing
  re-evaluation. It adds one action line asking a human to verify the fresh
  result and, if confirmed, close the linked Focus Issue. Other terminal
  results never receive this close reminder.
- Feishu sends use a deterministic API UUID. Notification failure makes the
  command fail visibly; it never changes the optimizer result or writes Jira.
- Standalone `evaluate:recent` remains externally write-disabled. Only the
  optimizer controller writes GitHub checkpoints and the terminal Feishu
  summary.

## Implementation Steps

1. Add the `case_refresh` checkpoint contract and latest-refresh projection.
2. Run a fresh current-base baseline on every optimizer invocation and remove
   automatic historical-base reconsideration.
3. Rerun challenger evaluation for resumed current-base candidates and append
   a refresh after every evaluation.
4. Feed the latest bounded refresh into the next patch-agent input.
5. Add Recent Optimizer notification formatting, deterministic idempotency,
   runner integration, and staging CronJob Secret references.
6. Align the canonical continuous-improvement doc and README.

## Verification Checklist

- [x] An old-base candidate cannot be selected for the current scheduled run.
- [x] A current-base candidate may still resume without regenerating code.
- [x] An existing Draft PR cannot skip the fresh baseline or case refresh.
- [x] Baseline and challenger each append a `case_refresh` checkpoint.
- [x] The newest refresh is selected deterministically and reaches the next
      bounded candidate input.
- [x] Reply bodies, workspace paths, post-cutoff replies, and credentials do
      not enter the refresh projection or patch-agent input.
- [x] Normal and thrown-error notifications show a Beijing date and explicit
      effect line while keeping deterministic idempotency keys.
- [x] Only `focus_ready_to_close` asks for human verification and closure and
      links the exact Focus Issue.
- [x] The staging CronJob references existing Lark Secret keys and keeps every
      Jira/customer/production write switch disabled.
- [x] TypeScript build, targeted tests, full `npm test`, and rendered staging
      manifests pass locally before any deployment or live functional test.

## Not In Scope

- Changing the historical replay cutoff or exposing later human answers to the
  support agent.
- Automatically changing the Focus case list or selecting the next Focus.
- Sending customer-visible replies, writing Jira, merging, deploying, or
  enabling production automation.
- Adding a database or Feishu report as another optimizer source of truth.