| name | recipe-merge-repair |
| description | Merge an upstream branch into a recipe development branch by comparing branch deltas, mapping shared-contract breakages, resolving conflicts, adapting the recipe, validating affected paths, and completing the merge safely. |
Recipe Merge Repair
Goal
Safely absorb upstream changes into the current recipe branch:
- compare upstream and current-branch changes before merging;
- map branch deltas to recipe runtime surfaces;
- resolve textual conflicts and semantic contract conflicts;
- repair the recipe at the smallest correct layer;
- validate the post-merge tree before completing the merge.
Keep fixes inside recipes/<recipe>/ whenever possible. Modify mvp_engine/
only when the issue clearly belongs to shared infrastructure.
Required Inputs
Identify these before running a merge:
- current development branch;
- upstream branch, usually
main;
- target recipe path and key entry config;
- known commits or files that deserve focused review;
- intended validation depth;
- working-tree state and whether local uncommitted changes are in scope;
- data, weights, compute, service, or permission prerequisites.
Ask the user before proceeding if the merge could overwrite unrelated dirty
files or if validation requires unavailable resources.
Workflow
1. Establish Merge Context
Do not start with git merge. First inspect:
git branch --show-current
git status --short
git merge-base <current_branch> <upstream_branch>
Record what the merge must preserve: target recipe capabilities, entrypoints,
configs, and validation goal.
2. Compare Branch Deltas
Compare upstream-only, current-only, and overlapping changes:
git diff --name-status <merge_base>..<upstream_branch>
git diff --name-status <merge_base>..<current_branch>
git diff --name-status <current_branch>...<upstream_branch>
Read references/merge_rules.md for the full comparison checklist and hotspot
mapping rules.
3. Map Hotspots To Recipe Contracts
Inspect the target recipe's engine, model, data, config, registration, tests,
and shared-layer call sites.
Build a breakage map:
- capability affected;
- upstream change involved;
- current-branch assumption involved;
- repair layer: recipe-local, shared-layer, or design decision.
4. Merge And Repair
After the hotspot map is clear, merge without committing:
git merge --no-commit --no-ff <upstream_branch>
Resolve conflicts by final behavior, not conflict-block convenience. Preserve
recipe-local goals while adapting to new shared contracts.
5. Validate Post-Merge
Run the smallest validation that proves repaired paths work, then broader checks
when feasible. At minimum, run:
git diff --check
git status --short
Only complete the merge commit after conflicts are resolved and validation is
sufficient for the requested scope.
Validation
Soft Validation
Confirm:
- branch comparison happened before the merge;
- upstream-only, current-only, and overlapping changes were distinguished;
- breakage map covers affected recipe runtime paths;
- final recipe contracts align with post-merge shared behavior;
- unrelated local edits were not overwritten;
- residual risks name unvalidated paths and prerequisites.
Hard Validation
Run targeted post-merge validation for each repaired breakage class. Depending
on scope, this may include imports, structure tests, smoke tests, startup,
training, evaluation, or recipe-specific checks.
Always run git diff --check before finalizing. Do not report the merge as
complete if validation ran on a pre-merge or partially resolved tree.
Output
- Branches: current, upstream, merge base.
- Hotspots: files, modules, contracts inspected.
- Breakages: issue, cause, repair layer.
- Repairs: recipe-local and shared-layer changes applied.
- Conflict Resolution: important choices made.
- Validation: commands and results.
- Remaining Risks: unvalidated paths or blocked resources.
Read On Demand
references/merge_rules.md: branch comparison, hotspot mapping, repair, and
validation checklist.
