Pull

Workflow

1. Resolve the bundled repo helper from the runtime automation directory and verify repo status is clean before merging:
   • automation_dir="${SYMPHONY_WORKSPACE_AUTOMATION_DIR:?SYMPHONY_WORKSPACE_AUTOMATION_DIR is required}"; repo_cmd="$automation_dir/bin/repo"
   • "$repo_cmd" status
2. Ensure rerere is enabled locally:
   • "$repo_cmd" enable-rerere
3. Confirm remotes and branches:
   • Ensure the origin remote exists.
   • Ensure the current branch is the one to receive the merge through the bundled repo helper.
   • Determine the repo's base branch before merging. Prefer the workflow or PR target when it is explicit; otherwise use the remote default branch (for example origin/HEAD).
4. Fetch latest refs:
   • "$repo_cmd" fetch
5. Sync the remote feature branch first:
   • branch=$("$repo_cmd" current-branch)
   • "$repo_cmd" merge "origin/$branch" --ff-only
   • This pulls branch updates made remotely (for example, a repo-provider auto-commit) before merging the latest remote base branch.
6. Merge in order:
   • Prefer "$repo_cmd" sync-base --base "<base-branch>" so repo-core owns the fetch and base-merge side effects together.
7. If conflicts appear, resolve them (see conflict guidance below), then:
   • stage the resolved files
   • continue or commit the merge according to the repository's normal merge workflow
8. Verify with the target repository's documented checks when present.
9. Summarize the merge:
   • Call out the most challenging conflicts/files and how they were resolved.
   • Note any assumptions or follow-ups.

Conflict Resolution Guidance (Best Practices)

• Inspect context before editing:
  • Use "$repo_cmd" status to list conflicted files.
  • Use "$repo_cmd" diff or "$repo_cmd" diff --merge to see conflict hunks.
  • Use "$repo_cmd" diff :1:path/to/file :2:path/to/file and "$repo_cmd" diff :1:path/to/file :3:path/to/file to compare base vs ours/theirs for a file-level view of intent.
  • With merge.conflictstyle=zdiff3, conflict markers include:
    • <<<<<<< ours, ||||||| base, ======= split, >>>>>>> theirs.
    • Matching lines near the start/end are trimmed out of the conflict region, so focus on the differing core.
  • Summarize the intent of both changes, decide the semantically correct outcome, then edit:
    • State what each side is trying to achieve (bug fix, refactor, rename, behavior change).
    • Identify the shared goal, if any, and whether one side supersedes the other.
    • Decide the final behavior first; only then craft the code to match that decision.
    • Prefer preserving invariants, API contracts, and user-visible behavior unless the conflict clearly indicates a deliberate change.
  • Open files and understand intent on both sides before choosing a resolution.
• Prefer minimal, intention-preserving edits:
  • Keep behavior consistent with the branch’s purpose.
  • Avoid accidental deletions or silent behavior changes.
• Resolve one file at a time and rerun tests after each logical batch.
• Use ours/theirs only when you are certain one side should win entirely.
• For complex conflicts, search for related files or definitions to align with the rest of the codebase.
• For generated files, resolve non-generated conflicts first, then regenerate:
  • Prefer resolving source files and handwritten logic before touching generated artifacts.
  • Run the CLI/tooling command that produced the generated file to recreate it cleanly, then stage the regenerated output.
• For import conflicts where intent is unclear, accept both sides first:
  • Keep all candidate imports temporarily, finish the merge, then run lint/type checks to remove unused or incorrect imports safely.
• After resolving, ensure no conflict markers remain:
  • "$repo_cmd" diff-check
• When unsure, note assumptions and ask for confirmation before finalizing the merge.

When To Ask The User (Keep To A Minimum)

Do not ask for input unless there is no safe, reversible alternative. Prefer making a best-effort decision, documenting the rationale, and proceeding.

Ask the user only when:

• The correct resolution depends on product intent or behavior not inferable from code, tests, or nearby documentation.
• The conflict crosses a user-visible contract, API surface, or migration where choosing incorrectly could break external consumers.
• A conflict requires selecting between two mutually exclusive designs with equivalent technical merit and no clear local signal.
• The merge introduces data loss, schema changes, or irreversible side effects without an obvious safe default.
• The branch is not the intended target, or the remote/branch names do not exist and cannot be determined locally.

Otherwise, proceed with the merge, explain the decision briefly in notes, and leave a clear, reviewable commit history.