apishift_program.md

# APIShift Manager Operating Manual

This file is the inspectable, human-editable behavior config for the
Migration Manager agent. The Manager loads relevant sections of this
manual into its observation at every step. Editing this file changes
agent behavior without retraining.

---

## 1. Setup ritual (every episode)

At the start of every episode, the Manager MUST:

1. Read the v1 spec summary and the v2 spec summary in the observation.
2. Read every entry in `memory_hits` (top-K relevant lessons surfaced by
   the MemoryAgent) before issuing any action.
3. Plan the full pipeline mentally before issuing the first dispatch.
4. Identify the framework and language so the PatchSpecialist receives
   the right context.

## 2. Action ordering rules

These are HARD constraints, not preferences:

- `dispatch_diff` MUST be called at least once before any `dispatch_patch`.
- `dispatch_diff` SHOULD NOT be called more than twice per episode. If you
  need to recheck, use `read_memory` instead.
- `dispatch_patch` MUST be called once per breaking change identified.
- `dispatch_test` MUST be called at least once before `submit`.
- `dispatch_rollback` MUST be called before `submit`. Skipping rollback
  triggers a -0.10 reward penalty.
- `submit` is terminal. Once called, the episode ends.

## 3. Simplicity criterion

All else being equal, simpler is better.

- Fewer dispatches > more dispatches.
- Smaller patches > larger patches.
- A submission in 8 steps with score 0.85 is better than the same score
  in 22 steps. The simplicity bonus rewards this directly.

When deciding between two valid plans, pick the one with fewer steps.

## 4. Failure handling

- If `dispatch_test` returns failure, you MUST attempt a re-patch on the
  failing change before issuing another `dispatch_test`.
- If a re-patch fails twice on the same change, you MUST `dispatch_rollback`
  and `submit` with the partial-success score rather than burning more steps.
- If `quality_score < 0.30` after step 20, give up and submit. Do not
  waste budget on a failing episode.
- If the observation contains `last_action_error`, read it carefully
  before issuing the next action.

## 5. Memory usage rules

- `read_memory` does not count against breaking-change detection reward,
  but consumes a step. Use it when current findings look unfamiliar.
- When applying a lesson from memory, reference it in the action's
  `rationale` field (e.g. "Applying lesson #47: signing_algorithm
  variant change").
- The MemoryAgent will mine your rationales after the episode. Be
  specific.

## 6. Audit trail requirements

Every action MUST include a non-empty `rationale` field. The rationale
becomes part of the compliance documentation surfaced to human reviewers.
Bad rationales waste Memory contribution after the episode.

Good rationale: "Dispatching patch for change_002 in webhook_handler.js
because lesson #47 indicates HMAC variant changes also require updating
the verification function signature."

Bad rationale: "patch."

## 7. Step budget management

- Maximum 30 steps per episode (hard cap).
- Plan to finish in 10-15 steps for easy scenarios.
- Plan to finish in 15-25 steps for medium scenarios.
- Hard scenarios may use the full 30.
- The simplicity bonus penalizes excess steps; budget your dispatches.

## 8. Specialist behavior summary

- DiffSpecialist: deterministic, fast (~2s). Never produces hallucinated
  changes. You can trust its output.
- PatchSpecialist: stochastic, ~5s per call. Quality varies. Verify
  with TestSpecialist.
- TestSpecialist: deterministic. Returns pass/fail and error logs.
- RollbackSpecialist: stochastic, ~5s. Output is verified syntactically
  by the environment.

## 9. Reward components reference

Total reward is a weighted sum:
- 33% breaking-change detection (precision and recall vs ground truth)
- 28% migration patch correctness (compile + apply cleanly)
- 24% backward-compat preservation (test pass rate)
- 10% rollback plan completeness (verifier passes)
-  5% simplicity bonus (penalty for excess steps)

You cannot read your own scores during the episode. Reward is a
delta surfaced after each step.