# Focus Issue Resumable Optimizer

> Freshness and notification behavior is superseded by
> `2026-07-17-recent-evaluation-freshness-and-feishu.md`.

## Current Design

- Daily report generation analyzes each ticket, generates repair proposals, and creates one GitHub optimization Issue per daily window.
- Recent Evaluation separately reads `evaluation/recent/active-focus.json` as the Active Focus.
- The daily optimizer always reruns baseline, keeps candidate code only in a temporary clone, and creates durable state only after a challenger passes and a Draft PR is opened.
- A completed baseline therefore cannot be resumed, and daily Issues duplicate the long-lived Focus.

## Risks

- Using both daily Issues and a checked-in manifest creates competing sources of truth.
- Treating an observed quality gap as `fail` mixes normal optimization work with execution failure.
- Persisting only a baseline but not candidate code still loses progress after the patch stage.
- Resuming a checkpoint against a different commit, Focus contract, or case set can validate the wrong system.
- Letting the patch Agent own GitHub credentials would broaden its authority beyond repository-local changes.

## Target Contract

```text
Daily ticket analysis -> DB report artifact -> Feishu
                                      |
                                      +-> signal only; no Issue or repair plan

one open GitHub Focus Issue (canonical)
  -> baseline checkpoint
  -> candidate branch checkpoint
  -> full-test checkpoint
  -> challenger checkpoint
  -> Draft PR checkpoint
```

- The GitHub Focus Issue body is the only Active Focus source of truth. It contains a versioned machine-readable Focus contract and lifecycle status: `active`, `blocked`, or `ready_to_close`.
- Issue comments are append-only, idempotent checkpoints. Every checkpoint binds the Issue number, Focus digest, base commit SHA, stage, and stage artifact.
- A real baseline/challenger execution error is recorded as `run_error` without completing that stage; the next run retries the same stage and candidate.
- A run resumes from the first incomplete stage. A stored baseline is reusable only with its original Focus digest and evaluation base SHA.
- Every scheduled run executes a fresh baseline on current `main`. Historical baseline/tests/challenger chains remain evidence and are never automatically re-gated after the controller base advances.
- Each baseline and challenger appends a bounded `case_refresh` checkpoint; the next candidate analysis receives the newest refresh.
- A new candidate attempt receives bounded prior-attempt changes, challenger findings, and outcomes from the same Focus/base SHA, so it must address the last rejection instead of repeating the same patch.
- A retried candidate receives bounded policy-failure feedback and the exact source allowlist, so it can revise the same attempt without expanding into live or external-write paths.
- Candidate code is committed and pushed to a controller-owned branch before validation, so later runs can resume tests and challenger evaluation.
- Evaluation findings are `gaps_found`, `criteria_met`, or `inconclusive`. These are observations, not task failures.
- Candidate outcomes are `candidate_accepted`, `candidate_rejected`, or `no_candidate`. Only command, contract, or external API failures make the job fail.
- A Focus explicitly names its blocking criterion IDs. The Draft PR gate is accepted when every blocking criterion is met on target cases. Non-blocking gaps and regressions remain visible review evidence but do not block Draft PR creation.
- Existing gaps outside the blocking criteria are recorded as follow-up findings. They do not block the current Draft PR unless the candidate introduced the regression.
- A contract-test failure records both `run_error` and `candidate_rejected`; the next scheduled run receives the bounded failure and starts a new candidate rather than retrying an immutable broken branch forever.
- Daily and weekly reports keep per-ticket facts, comparisons, metrics, and concise findings. They do not create GitHub Issues or generate repair plans.
- The controller owns GitHub reads/writes. The patch Agent receives no GitHub, Jira, provider, Lark, or database credentials.
- The patch Agent may change only an explicit support-capability allowlist, including the read-only diagnostic provider router; controller, evaluation, deployment, credential, and external-write paths remain forbidden.
- Candidate scope remains bounded to at most 16 files so one shared routing change can carry its cross-contract tests without opening unrestricted source edits.
- A candidate policy rejection records a bounded `run_error` checkpoint and leaves the candidate stage incomplete, so the same attempt can be retried after a controller fix.

## Invariants

- There is exactly one open Focus Issue with lifecycle `active`; zero or multiple active Focus Issues stop the optimizer.
- There is no fallback from GitHub Focus Issue to a repository manifest, daily Issue, Feishu report, or DB report artifact.
- A standalone read/evaluation path never updates Jira, Feishu, customer-visible replies, or production systems. The optimizer controller may append GitHub checkpoints and send its terminal Feishu summary.
- Checkpoint replay never relabels an artifact with a different Focus digest, evaluation base SHA, candidate SHA, or evaluation contract. Candidate resume requires the current base SHA.
- The optimizer never treats the judge's aggregate `gaps_found` or a non-blocking regression alone as the Draft PR decision; it compares the challenger against the Focus blocking criteria and reports the rest.
- Daily report delivery never waits for GitHub Issue creation.
- The optimizer never merges, deploys, selects the next Focus, or changes customer-visible automation.
- The optimizer sends one idempotent Feishu summary for each terminal run result and performs no other external notification write.

## Implementation Steps

1. Replace the Active Focus manifest loader with a GitHub Focus Issue contract and client.
2. Add versioned baseline, candidate, tests, challenger, and Draft PR checkpoints plus resume validation.
3. Persist candidate code on a dedicated branch before tests and challenger.
4. Remove optimization proposals and daily GitHub Issue delivery from report generation.
5. Rename evaluation semantics so normal gaps do not fail the command or CronJob.
6. Import the existing baseline into the first Focus Issue and run the remaining stages through the new controller.

## Verification Checklist

- Focus Issue parsing rejects malformed contracts, invalid lifecycle values, duplicate active Issues, and unknown fields.
- Baseline import and resume validate Focus digest and evaluation base SHA; stale checkpoints cannot be used as current-base results.
- Repeated runs do not repeat completed stages or create duplicate comments, branches, or Draft PRs.
- Attempt 2 input contains attempt 1 challenger evidence and changed paths but no reply bodies, workspace paths, or credentials.
- Candidate branch persistence survives a controller restart before tests or challenger.
- `gaps_found` exits successfully; execution or contract failures exit non-zero.
- A challenger may remain aggregate `gaps_found` while the candidate gate is accepted, provided all blocking criteria pass; baseline regressions are surfaced in the Draft PR rather than suppressing it.
- Daily and weekly reports contain no optimization plan or GitHub Issue section and Feishu delivery does not depend on GitHub.
- The patch Agent environment contains no business or GitHub credentials.
- Full local tests pass.
- One real Focus Issue imports the existing baseline and records candidate, tests, challenger, candidate-gate, and Draft PR checkpoints; aggregate `gaps_found` does not block a Draft PR when the explicit gate is accepted.

## Dry-run Evidence

- Focus Issue: `tidbcloud/aisupport#338`; the saved baseline was imported and reused without rerunning.
- Attempt 5 persisted its candidate branch, passed the full suite, and completed all four challenger cases.
- The first controller version rejected attempt 5 because it required aggregate `criteria_met`; the next version still rejected it on a non-blocking regression. Both checkpoints are retained as evidence for separating Draft PR creation from follow-up quality findings.
- Gate v2 accepted `evidence_route` with 3 improvements and no blocking failures, while preserving APID-29166 `direct_evidence_first` and `reply_convergence` as follow-up evidence.
- The controller created Draft PR `tidbcloud/aisupport#343`; it did not merge or deploy it.

## Non-Goals

- Do not implement Regression Evaluation yet.
- Do not automatically choose or create the next Focus from daily signals.
- Do not merge or deploy generated changes.
- Do not broaden Jira writes, customer-visible replies, or production operations.