| name | sync/rebase |
| description | Synchronize the feature branch with its base. Use when the branch is behind origin, has conflicts to resolve, or needs to incorporate upstream changes before Finish. |
SYNC → REBASE
Execute only the branch synchronization step of the Sync flow.
Responsabilidade: garantir a integridade do repositório git — tornar o repositório pronto para merge, incorporando o estado mais recente da base na feature branch sem conflitos e sem enfraquecer testes. Este é um step de git, não de produto: ele não muda comportamento nem alinha artefatos ProdOps (isso é align).
For detailed mechanics, read ../../references/workflow.md.
Action
1. Preflight — inspect working tree
git status --short
git branch --show-current
If the worktree has uncommitted changes, stop and surface the options:
- Commit — if the work is complete enough: run
/hack commit, then return here.
- Stash — if the work is unrelated or not ready:
git stash -u
- Stop — if the scope is unclear: surface as a blocker. Do not proceed.
Never discard uncommitted work silently.
2. Fetch and inspect
git fetch --all --prune
git branch -vv
git log --oneline --decorate --graph --max-count=30 --all
git rev-list --left-right --count <base>...HEAD
Infer the base branch in this order: upstream of current branch → origin/HEAD → origin/main → origin/master.
3. Update the base (fast-forward only)
git switch <base>
git pull --ff-only
If fast-forward fails, report the divergence — do not force it.
4. Integrate base into the feature branch
git switch <work-branch>
git rebase <base>
If the branch has already been pushed to origin, follow the rebase with:
git push --force-with-lease
--force-with-lease is safe: it aborts the push if anyone else has modified the remote branch since the last fetch. Only use bare --force if explicitly requested.
5. Resolve conflicts
For each conflict:
git status --short
git diff --name-only --diff-filter=U
Open conflicted files, understand both sides, edit to a coherent final state, then stage and continue:
git add <resolved-paths>
git commit
6. Preserve TDD
- Keep tests that document the feature branch behavior.
- Keep upstream tests that document new base behavior.
- When expectations conflict, write or update the test first to define the merged expected behavior, then change production code to satisfy it.
- Never remove assertions, skip tests, or loosen checks only to complete a sync.
7. Validate — post-integration smoke, not quality gates
This validation only certifies that the integration did not break the green history left by Hack. It is not a quality gate: do not add new coverage, fix inherited code smells, or refactor here. If the integrated history is red, the conflict resolution is incomplete — return to step 5.
Run tests and lint for all touched packages:
cd api && npm run lint
cd api && npm run test
Run broader validation when shared contracts, lockfiles, config, or generated artifacts changed.
Finish with:
git status --short --branch
Post-conditions
Critério de conclusão — integridade do repositório git: concluído quando todos os itens abaixo são verdadeiros, simultaneamente:
- Working tree is clean.
- Base branch is up-to-date with
origin.
- Feature branch incorporates the latest base.
- All tests pass on the merged/rebased history.
- No assertions were removed or weakened to complete the sync.
Guardrails
- Do not discard uncommitted changes without developer approval.
- Do not force-push or rewrite shared branch history.
- Do not auto-stash unknown user work without surfacing the choice.
- Do not remove or weaken tests just to make synchronization pass.
- If conflicts occur, inspect both sides before editing.
Out of scope — not the responsibility of rebase
rebase does not open a pull request — that is Finish.rebase does not run the full CI pipeline — that is Ship.rebase does not add test coverage or fix code smells inherited from the base — it only verifies that the integration did not break the green history left by Hack. New coverage belongs to Hack (Yellow Bar); quality gates belong to Finish.rebase does not rewrite product decisions or align ProdOps artifacts — that is align.rebase does not touch artifacts in prodops/ to satisfy a conflict resolution. A conflict that requires changing a committed BDD Feature or OBC must surface as a blocker, not be silently rewritten here.
