integreat/docs/plans/2026-02-08-refactor-rebase-invoice-templates-integrate-branches-plan.md

title, type, date

title	type	date
Rebase Invoice Templates, Merge to Master, and Integrate Branches	refactor	2026-02-08

Rebase Invoice Templates, Merge to Master, and Integrate Branches

Overview

This plan outlines a series of git operations to reorganize the branch structure by:

1. Creating a rebase commit with all invoice template changes
2. Applying those changes onto master
3. Removing them from the current clauding branch
4. Merging master back into clauding
5. Finally merging clauding into get-transactions2-page-working

Current State

Branch Structure (as of Feb 8, 2026)

master (dc021b8c)
  ├─ deploy/master (dc021b8c)
  └─ (other branches)
       └─ clauding (0155d91e) - HEAD
            ├─ 16 commits ahead of master
            └─ Contains invoice template work for Bonanza Produce
                 ├─ db1cb194 Add Bonanza Produce invoice template
                 ├─ ec754233 Improve Bonanza Produce customer identifier extraction
                 ├─ af7bc324 Add location extraction for Bonanza Produce invoices
                 ├─ 62107c99 Extract customer name and address for Bonanza Produce
                 ├─ 7ecd569e Add invoice-template-creator skill for automated template generation
                 └─ 0155d91e Add Bonanza Produce multi-invoice statement template

Merge Base

• Merge base between clauding and master: dc021b8c
• Commits on clauding since merge base: 16 commits
• Invoice template commits: 6 commits (db1cb194 through 0155d91e)

Problem Statement

The current branch structure has:

1. Invoice template work mixed with other feature development in clauding
2. No clear separation between invoice template changes and transaction page work
3. A desire to get invoice template changes merged to master independently
4. A need to reorganize branches to prepare for merging get-transactions2-page-working

Proposed Solution

Use git rebase and merge operations to create a cleaner branch hierarchy:

1. Create a new branch (invoice-templates-rebased) with only invoice template commits
2. Rebase those commits onto current master
3. Merge this clean branch to master
4. Remove invoice template commits from clauding branch
5. Merge master into clauding to sync
6. Merge clauding into get-transactions2-page-working

Implementation Steps

Phase 1: Extract and Rebase Invoice Templates

Step 1.1: Identify Invoice Template Commits

# From clauding branch, find the range of invoice template commits
git log --oneline --reverse dc021b8c..clauding

Invoice template commits to extract (6 commits in order):

1. db1cb194 - Add Bonanza Produce invoice template
2. ec754233 - Improve Bonanza Produce customer identifier extraction
3. af7bc324 - Add location extraction for Bonanza Produce invoices
4. 62107c99 - Extract customer name and address for Bonanza Produce
5. 7ecd569e - Add invoice-template-creator skill for automated template generation
6. 0155d91e - Add Bonanza Produce multi-invoice statement template

Step 1.2: Create Rebased Branch

# Create a new branch from master with only invoice template commits
git checkout master
git pull origin master  # Ensure master is up to date
git checkout -b invoice-templates-rebased

# Cherry-pick the invoice template commits in order
git cherry-pick db1cb194
git cherry-pick ec754233
git cherry-pick af7bc324
git cherry-pick 62107c99
git cherry-pick 7ecd569e
git cherry-pick 0155d91e

# Resolve any conflicts that arise during cherry-pick
# Run tests after each cherry-pick if conflicts occur

Step 1.3: Verify Rebased Branch

# Verify the commits are correctly applied
git log --oneline master..invoice-templates-rebased

# Run tests to ensure invoice templates still work
lein test auto-ap.parse.templates-test

Step 1.4: Merge to Master

# Merge the clean invoice templates to master
git checkout master
git merge invoice-templates-rebased --no-edit

# Push to remote
git push origin master

Phase 2: Clean Up Clauding Branch

Step 2.1: Remove Invoice Template Commits from Clauding

# From clauding branch, find the commit before the first invoice template
git log --oneline clauding | grep -B1 "db1cb194"

# Suppose that's commit X, rebase clauding to remove invoice templates
git checkout clauding

# Option A: Interactive rebase (recommended for cleanup)
git rebase -i <commit-before-invoice-templates>

# In the editor, delete lines corresponding to invoice template commits:
# db1cb194
# ec754233
# af7bc324
# 62107c99
# 7ecd569e
# 0155d91e

# Save and exit to rebase

# Resolve any conflicts that occur
# Run tests after rebase

OR

# Option B: Hard reset to commit before invoice templates
# Identify the commit hash before db1cb194 (let's call it COMMIT_X)
git reset --hard COMMIT_X

# Then add back any non-invoice template commits from clauding
# (commits after the invoice templates that should remain)
git cherry-pick <non-invoice-commits-if-any>

Step 2.2: Verify Clauding Branch Cleanup

# Verify invoice template commits are removed
git log --oneline | grep -i "bonanza"  # Should be empty

# Verify other commits remain
git log --oneline -20

# Run tests to ensure nothing broke
lein test

Step 2.3: Force Push Updated Clauding

# Force push the cleaned branch (use --force-with-lease for safety)
git push --force-with-lease origin clauding

Phase 3: Sync Clauding with Master

Step 3.1: Merge Master into Clauding

git checkout clauding
git merge master --no-edit

# Resolve any conflicts
# Run tests

Step 3.2: Push Synced Clauding

git push origin clauding

Phase 4: Final Merge to get-transactions2-page-working

Step 4.1: Merge Clauding to get-transactions2-page-working

git checkout get-transactions2-page-working
git merge clauding --no-edit

# Resolve any conflicts
# Run tests

Step 4.2: Push Final Branch

git push origin get-transactions2-page-working

Acceptance Criteria

Pre-operations Validation

• All invoice template commits identified correctly (6 commits)
• Merge base commit (dc021b8c) confirmed
• Current branch state documented
• Team notified of branch manipulation

Post-Rebase Validation

• invoice-templates-rebased branch created from master
• All 6 invoice template commits applied correctly
• All invoice template tests pass
• No conflicts or unexpected changes during cherry-pick

Post-Master Validation

• Invoice templates merged to master
• Changes pushed to remote master
• CI/CD passes on master

Post-Cleanup Validation

• clauding branch has only non-invoice template commits
• No Bonanza Produce commits remain in clauding history
• All clauding tests pass
• Force push successful

Post-Sync Validation

• clauding merged with master
• All conflicts resolved
• Changes pushed to remote

Final Merge Validation

• get-transactions2-page-working merged with clauding
• All conflicts resolved
• Final tests pass
• Changes pushed to remote

Success Metrics

• Branch structure: Invoice templates cleanly separated on master
• Commit history: Linear, no duplicate invoice template commits
• Tests passing: 100% of existing tests pass after each step
• No data loss: All work preserved in appropriate branches
• Branch clarity: Each branch has a clear, focused purpose

Dependencies & Risks

Dependencies

• All current work on clauding should be backed up or committed
• Team should be aware of branch manipulation to avoid force pushing
• CI/CD should be monitored during operations

Risks

1. Force push risk: Force pushing clauding will rewrite history

   • Mitigation: Use --force-with-lease, notify team beforehand

2. Conflict resolution: Multiple merge/conflict resolution points

   • Mitigation: Test after each step, resolve conflicts carefully

3. Work loss: Potential to lose commits if operations go wrong

   • Mitigation: Create backups, verify each step before proceeding

4. CI/CD disruption: Force pushes may affect CI/CD pipelines

   • Mitigation: Coordinate with team, avoid during active deployments

Contingency Plan

If something goes wrong:

1. Recover clauding branch:

   git checkout clauding
   git reset --hard origin/clauding  # Restore from remote backup
   

2. Recover master:

   git checkout master
   git reset --hard origin/master  # Restore from deploy/master
   

3. Manual cherry-pick recovery: If rebasing failed, manually cherry-pick remaining commits

Alternative Approaches Considered

Approach 1: Squash and Merge

Pros: Single clean commit, simple history Cons: Loses individual commit history and context

Rejected because: Team uses merge commits (not squash), and individual commit history is valuable for tracking invoice template development.

Approach 2: Keep Branches Separate

Pros: No branch manipulation needed Cons: Branches remain tangled, harder to track progress

Rejected because: Goal is to cleanly separate invoice templates from transaction work.

Approach 3: Rebase Clauding Onto Master

Pros: Linear history Cons: Requires force push, may lose merge context

Rejected because: Current team workflow uses merge commits, and merging master into clauding preserves the integration point.

Approach 4: Create New Branch Instead of Cleanup

Pros: Less risky, preserves full history Cons: Accumulates branches, harder to track

Rejected because: Goal is cleanup and reorganization, not preservation.

Related Work

• Previous invoice template work: 2026-02-07-feat-add-invoice-template-03881260-plan.md
• Current branch structure: clauding has hierarchical relationship with get-transactions2-page-working
• Team git workflow: Uses merge commits (not rebasing), per repo research

References & Research

Internal References

• Branch management patterns: Repo research analysis (see task_id: ses_3c2287be8ffe9icFi5jHEspaqh)
• Invoice template location: src/clj/auto_ap/parse/templates.clj
• Current branch structure: Git log analysis

Git Operations Documentation

• Cherry-pick: git cherry-pick <commit>
• Interactive rebase: git rebase -i <base>
• Force push with lease: git push --force-with-lease
• Merge commits: git merge <branch> --no-edit

File Locations

• Templates: src/clj/auto_ap/parse/templates.clj
• Parser logic: src/clj/auto_ap/parse.clj
• Invoice PDF: dev-resources/INVOICE - 03881260.pdf

Testing Plan

Before Each Major Step

# Verify current branch state
git branch -vv
git log --oneline -10

# Run all tests
lein test

# Run specific invoice template tests
lein test auto-ap.parse.templates-test

After Each Major Step

• Verify commit count and order
• Run full test suite
• Check for unintended changes
• Verify remote branch state matches local

Notes

• Team coordination: Inform team before force pushing to avoid conflicts
• Backup strategy: All commits are preserved in the rebase process
• Testing: Verify at each step to catch issues early
• Safety first: Use --force-with-lease instead of --force
• Documentation: This plan serves as documentation for the operation