eforge-build/eforge/eforge-stack

/eforge:stack:sync

Manually synchronize the git-spice stack for this project. Use --dry-run to preview what commands would run without executing them.

This skill covers manual eforge stack sync recovery. During stacked PR landing with landing.action: pr, eforge attempts automatic provider-encapsulated recovery for provider-classified recoverable restack conflicts before asking for manual intervention. Landing also preflights the remote base: if a missing parent branch's artifact commit is an ancestor of trunk, eforge automatically performs branch-scoped stale-parent repair by tracking initially untracked children against trunk or retargeting already tracked children; otherwise it fails closed with manual stack-base repair guidance. Before submitting the PR, landing runs provider repo sync, branch restack, and a remote-base freshness proof for the branch being submitted.

Stack sync is a daemon-owned operation that runs from the project root. The daemon calls git-spice repo sync followed by git-spice stack restack. Triggers include: this command (/eforge:stack:sync), the CLI (eforge stack sync), the eforge_stack_sync tool, and — when stacking.sync.afterBuild: true is configured — automatically after each build completes.

Requirements

Stack sync requires stacking.enabled: true in eforge/config.yaml and git-spice initialized in the repository (git-spice repo init). If stacking is not enabled the daemon returns outcome: "skipped" with a reason.

Step 1: Detect dry-run flag

Check $ARGUMENTS for --dry-run. If present, set dryRun: true in the tool call.

Step 2: Run the sync

Call the eforge_stack_sync tool with { dryRun: <true|false> }.

Step 3: Interpret the response

The tool returns a structured sync report. Interpret each field:

Outcome summaries

`skipped` - Stacking is not enabled or no stacking configuration found. Nothing was changed. Show the reason to the user. Suggest enabling stacking with /eforge:config or /eforge:workflow.

`complete` - All eligible artifact branches were restacked onto the latest trunk. Show the list of providerCommands that ran and the restackCandidates that were processed.

`deferred` - Active builds are running and their worktrees overlap the stack candidate set. The restack step was skipped to avoid conflicting with in-flight builds. Show activeBuildSkips and reason. The activeBuildPolicy field will be "defer" when a deferred outcome was explicitly requested. If stacking.sync.afterBuild: true is configured, the daemon will retry deferred syncs after each build completes — no manual action is needed. Otherwise, suggest waiting for active builds to complete and then running /eforge:stack:sync again.

`failed` - The sync command exited with a non-zero code. Show error and the failed providerCommands. Suggest running git-spice manually to investigate, then re-running sync after resolving the issue.

`conflict` - A manual sync restack step hit a merge conflict. Show error and the providerCommands list. Proceed with the manual sync conflict recovery flow below.

Active-build skips

When activeBuildSkips is non-empty, report which branches were excluded and why. These branches were left unchanged because active eforge builds are using their worktrees. When outcome is "deferred", the entire restack step was skipped; when outcome is "complete", only the listed branches were skipped and the rest were restacked. Re-run sync after the active builds complete to restack the skipped branches.

Fast-forward check

When fastForward is false, the local trunk is ahead of origin/<trunk>. Sync uses a fast-forward-only trunk policy: it will not force-push or rebase trunk. Tell the user to push or align their local trunk before syncing.

Step 4: Manual sync conflict recovery

When outcome is "conflict", the conflict came from eforge stack sync. Do not describe this as the stacked PR landing recovery path; landing recovery runs automatically first for provider-classified recoverable restack conflicts, stale-parent landing repair is automatic and branch-scoped when parent artifact ancestry proves trunk integration (tracking initially untracked children against trunk or retargeting already tracked children), and landing-time sync/freshness is automatic for the branch being submitted.

When outcome is "conflict":

1. Show the error and the exact commands that ran up to the point of conflict.
2. Instruct the user:

> A merge conflict occurred during manual stack sync restack. To recover: > 1. Run git status to see the conflicting files. > 2. Resolve the conflicts in the affected files. > 3. Run git add <resolved-files> to stage the resolved files. > 4. Run git rebase --continue (or the git-spice equivalent) to resume the restack. > 5. Once the restack finishes, run /eforge:stack:sync again to sync remaining branches.

1. Offer to re-run the sync after the user confirms they have resolved the conflict.

Dry-run output

When dryRun is true:

• Make clear that no commands were executed.
• List each entry in providerCommands with its command and args.
• Show restackCandidates — the branches that would be restacked.
• Show activeBuildSkips — branches that would be skipped due to active builds.

Related skills