docs: update worktree divergence reconcile description [doc-updater]

[james-in-a-box]

Update documentation to reflect changes from 69b2a18 (Fix #2337):

• The _sync_worktree_with_remote() divergence case now uses _rebase_with_agent_output_autoresolve instead of --ff-only merge. The old doc described the stale fast-forward-merge behavior; the new description names the rebase helper, explains the base_branch=None contamination-risk fallback, and corrects the trigger context to include phase boundaries (not just orchestrator restarts).

Triggered by: #2352

Authored-by: egg

[egg-reviewer]

No agent-mode design concerns — docs-only update describing the worktree divergence reconcile path in _sync_worktree_with_remote().

— Authored by egg

[egg-reviewer]

Review summary

Documentation-only PR. Two lines updated in docs/architecture/orchestrator.md to align with the post-#2337 behavior of _sync_worktree_with_remote(). I verified each claim against orchestrator/routes/pipelines.py:5232-5519 and orchestrator/gateway_client.py:1998-2277.

Verified accurate

• Trigger context ("orchestrator restarts and phase boundaries"): matches the function's own docstring at orchestrator/routes/pipelines.py:5242-5243 ("After an orchestrator restart or a phase boundary, the local worktree branch may be behind the remote").
• Helper name _rebase_with_agent_output_autoresolve: matches the call site at orchestrator/routes/pipelines.py:5493. Lives in orchestrator/gateway_client.py:1998 and is the same helper invoked by the gateway-side push-reject reconcile path, as the doc claims.
• Failure handling ("the error is logged and the function returns"): matches orchestrator/routes/pipelines.py:5509-5519 — divergence_rebase_failed is logged at error level and the function returns without falling through to the step-4 reset.
• base_branch=None fallback: the warning emit at orchestrator/routes/pipelines.py:5479-5485 and the actual bare-form fallback in _build_rebase_cmd at orchestrator/gateway_client.py:2261-2262 confirm both the warning and the contamination risk. The #2222 reference matches the in-code comment at orchestrator/routes/pipelines.py:5466-5478 and orchestrator/gateway_client.py:2253-2254.

Both real callers (orchestrator/routes/pipelines.py:14169 and :15396) thread pipeline.base_branch, so the base_branch=None path is a defensive corner case. Documenting it is appropriate — the warning is real and an operator hitting that log line will want to know what it means.

Non-blocking suggestion

The summary sentence directly above the bullet list (unchanged by this PR) still reads:

"then resolves divergence and resets the local branch to origin/<branch> via git reset --hard when needed."

After #2337, the divergence case no longer resets — it rebases. The "when needed" hedge covers it loosely, and the bullet list directly below is accurate, so this isn't wrong, just slightly imprecise. If you wanted to tighten in a follow-up:

"then reconciles divergence (rebasing local commits) or resets the local branch to origin/<branch> depending on the case described below."

Not blocking — the bullets carry the load.

Verdict

No blocking issues. The PR is a faithful, scoped doc-sync for #2337. Approving.

— Authored by egg

[james-in-a-box]

Review feedback disposition

egg-reviewer (review bot) — APPROVED with one non-blocking suggestion:

• Tighten the unchanged summary sentence above the divergence bullets, which still read "resets the local branch to origin/<branch> via git reset --hard when needed" — imprecise post-_sync_worktree_with_remote doesn't fall back to rebase on true divergence; downstream populator/sync paths see a stale worktree (#2261 example: 15-slice plan demoted to monolithic implement) #2337 since the diverged case now rebases. → fixed-in-PR (commit e79d24d). Replaced the sentence with "then reconciles divergence (rebasing local commits) or resets the local branch to origin/<branch> depending on the case described below" (the reviewer's suggested phrasing). The bullets directly below remain authoritative for per-case specifics.

egg-reviewer (agent-mode-design bot) — APPROVED, no concerns.

No other actionable feedback from authorized reviewers.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns — delta since the prior review is a single-sentence wording tightening in docs/architecture/orchestrator.md to address a non-blocking suggestion. Still a pure docs-only PR.

— Authored by egg

[egg-reviewer]

Re-review

Delta since the prior review (fc8943f1 → e79d24d1) is the single-commit follow-up that applies my own non-blocking suggestion verbatim. Re-verified against the current code:

• Summary sentence at docs/architecture/orchestrator.md:234: now reads "then reconciles divergence (rebasing local commits) or resets the local branch to origin/<branch> depending on the case described below." This faithfully captures both control-flow branches in _sync_worktree_with_remote():
  • The diverged-case rebase at orchestrator/routes/pipelines.py:5493 (rebases local commits).
  • The reset-to-origin step covering the succeeded-ahead/push-fail-fallback, failed-ahead, and behind-remote cases.
  • The "depending on the case described below" hedge correctly defers to the bullets, including the in-sync early-return.
• The previous summary's git reset --hard implementation detail dropped out of the top-line, but the bullets carry the same "reset" language uniformly, so no information is lost in context.
• Code references still match: _sync_worktree_with_remote at :5232, _rebase_with_agent_output_autoresolve at :5493, divergence_rebase_failed log path at :5513. base_branch=None warning emit and bare-form fallback unchanged from the prior review.

No new concerns. The original feedback was addressed exactly as suggested. Pure docs-only change with no functional risk.

Verdict

Approving.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

5 previous review(s) hidden.