---
name: eforge-stack
description: Synchronize the git-spice stack, preview with dry-run, interpret the sync report, and recover from manual sync conflicts
disable-model-invocation: true
---

# /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:

| Field | Meaning |
|-------|---------|
| `outcome` | One of `"skipped"`, `"complete"`, `"deferred"`, `"failed"`, `"conflict"` |
| `reason` | Human-readable reason (always present for skipped/deferred/failed/conflict) |
| `stackingActive` | Whether stacking is enabled and active for this project |
| `dryRun` | Whether this was a preview-only run |
| `localTrunkSha` | SHA of the local trunk branch |
| `originTrunkSha` | SHA of `origin/<trunk>` |
| `fastForward` | True when local trunk is at or behind origin (fast-forward eligible) |
| `restackCandidates` | Artifact branches eligible for restack |
| `activeBuildSkips` | Branches/worktrees skipped because active builds are using their worktrees and overlap the stack candidate set |
| `providerCommands` | git-spice commands that ran (or would run in dry-run) |
| `error` | Error message when outcome is `"failed"` or `"conflict"` |

### 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.
3. 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

| Skill | Command | When to suggest |
|-------|---------|----------------|
| Workflow | `/eforge:workflow` | User wants to configure workflow preset (stacking, landing action, auto-sync) |
| Config | `/eforge:config` | User wants to enable/disable stacking or change sync config |
| Status | `/eforge:status` | User wants to check build progress before sync |