update-starbase

Update Starbase

Phase 1: Merge Starbase

Run the preparation script from the root of the child repository:

bash <path-to-skill>/scripts/prepare_merge.sh [BRANCH_SUFFIX]

• BRANCH_SUFFIX is optional; defaults to today's date (work/update-starbase-YYYY-MM-DD).
• The script handles steps 1–6: safe-state check, remote setup, fetch, work-branch creation, merge, and conflict detection.
• It prints a compact STATUS=... block (BRANCH, BASE, CHANGED_FILES, and — when relevant — CONFLICTED_FILES and PLACEHOLDER_WARNINGS) for one of four STATUS values, then continue with the matching step below:
  • STATUS=clean (exit 0): merge succeeded with no conflicts. Continue to Phase 2.
  • STATUS=conflicted (exit non-zero): merge stopped with conflicts. Resolve each file in CONFLICTED_FILES per references/file_ownership.md, then git add the resolved files and git merge --continue before continuing to Phase 2.
  • STATUS=already-up-to-date (exit 0): starbase/main has no commits that aren't already in the branch. No work branch was created — there is nothing to sync or open a PR for. Stop here and report this to the user.
  • STATUS=failed (exit non-zero): git merge failed for a reason other than an ordinary conflict (e.g. untracked files that would be overwritten, a failing merge hook). The merge was aborted; fix the underlying issue from the git output above the status block, then re-run the script.

If the script cannot be run, follow references/manual_merge_steps.md instead.

Report one of: merge-clean, merge-conflicted (with the conflicted file list), already-up-to-date, or merge-failed.

Conflict resolution

When resolving merge conflicts, consult references/file_ownership.md for the complete ownership map and decision rules, including:

• Conflict rule 1 – File ownership map (always take starbase, always take child, and mixed-ownership rules by file/section).
• Conflict rule 1b – Files that must be deleted; check every merge, clean or conflicted, since these deletions never raise a conflict.
• Conflict rule 2 – Python type annotation modernisation (when to apply X | Y, tuple[X, Y], etc., and Python version caveats).
• Conflict rule 3 – AGENTS template handling (library vs. application repositories).