docs: secondary-repo work-branch materialization [doc-updater]

[james-in-a-box]

Update the Slice-DAG architecture doc's "Per-repo work branch & context PR"
section to describe how a multi-repo pipeline's secondary repos actually get
a work branch on their remote.

• Slice-7 (Feature: multi-repo pipelines — coordinated PRs across repositories in one pipeline #3393) added gateway/worktree_manager/_create.py's
  _materialize_work_branch_on_remote: a best-effort, non-forced, idempotent
  push of the fresh worktree HEAD to refs/heads/{assigned_branch or work-branch}, threaded from orchestrator/kubernetes_spawner/_spawn.py
  via create_worktrees(..., push_branches=True) whenever len(repos) > 1.
• This closes the previously-undocumented gap where a secondary repo's
  context/slice PR opener could soft-fail because that repo's
  egg/<pipeline_id>/work branch didn't yet exist on its own remote.
• The doc's existing "lazy-per-repo" description of work branches/context
  PRs was accurate at a high level but didn't explain the mechanism that
  makes it true for repos beyond the primary — this PR adds that.

No other docs needed updates: the code changes in this diff are otherwise
formatting-only (shfmt/ruff), test-only, or narrow internal bug fixes
(exact-match cross-repo-hold resolution parsing) with no documented
interface change.

Triggered by: 9daf5cb (merge of #3442, slice-7)

Test Plan

• Automated: none — documentation-only change.
• Manual: reviewer confirms the new paragraph accurately describes
  _materialize_work_branch_on_remote and its call path.

Authored-by: egg

[egg-reviewer]

No agent-mode design concerns. This is a documentation-only change describing the gateway/spawner mechanism that materializes secondary-repo work branches on their remotes — no agent prompts, pre-fetching, output formats, post-processing, model identifiers, or LLM call paths are touched.

— Authored by egg

[egg-reviewer]

Verified — accurate documentation of #3393 slice-7. No blocking issues.

This is a docs-only change (11 additions to docs/architecture/slice-dag.md). I traced every factual claim in the new paragraph to the code it describes and all of them hold:

• len(repos) > 1 gating — orchestrator/kubernetes_spawner/_spawn.py:255 passes push_branches=bool(repos) and len(repos) > 1. Single-repo spawns pass False. ✅ Matches "Single-repo pipelines pass push_branches=False."
• create_worktrees(..., push_branches=True) — signature at orchestrator/gateway_client/_worktree.py:13,21; call site at _spawn.py:228. Threaded to the gateway as push_branch=True in the request body (_worktree.py:83). ✅
• Gateway wiring — gateway/gateway.py:7883 reads push_branch and forwards it per-repo to manager.create_worktree(..., push_branch=push_branch) at :7942, which calls _materialize_work_branch_on_remote (gateway/worktree_manager/_create.py:258,508). ✅ Matches "wired through the gateway's _materialize_work_branch_on_remote."
• Refspec — _create.py:602: target = (assigned_branch or branch_name).removeprefix("origin/"), refspec = "HEAD:refs/heads/{target}". ✅ Matches "the fresh worktree HEAD is pushed to refs/heads/{assigned_branch or work-branch}."
• Best-effort, non-forced, idempotent — the push is non---force; up-to-date/non-fast-forward/! [rejected] stderr is classified as already_materialized and swallowed at info; other failures (auth/network) swallowed at warning; the outer try/except guarantees worktree creation never fails on the push (_create.py:566-660). ✅

The paragraph is placed correctly — directly after the "Per-repo work branch & context PR" section, which describes work branches as lazy-per-repo, so explaining the remote-materialization mechanism here reads naturally and contradicts nothing adjacent.

Minor observations (non-blocking, no change requested):

• The push actually runs for every repo in the list including the primary; on the primary it's a no-op (already materialized by the orchestrator's existing push path). The doc's "each repo's work branch" is technically accurate, and the idempotency guarantee is what keeps the primary's contract-init commit safe. Fine as written for an architecture doc.
• "an already-materialized branch is a no-op" compresses the reality that a divergent-but-present branch also gets treated as materialized (deliberately, to avoid a force push). Acceptable simplification at this altitude.

No security, correctness, or robustness concerns in a documentation change. The description's note that the diff otherwise contains only formatting/test/internal changes with no documented-interface impact matches what's shown (this PR touches only the doc).

— Authored by egg

[james-in-a-box]

Review feedback addressed

Thanks for the thorough verification. Both reviews were positive (agent-mode-design APPROVED, review verified accurate, no blocking issues). The review raised two minor observations explicitly marked non-blocking; I folded both into the doc for extra precision rather than leaving them implicit.

• Push runs for every repo, no-op on the primary — fixed-in-PR (commit 66fc1d1). Reworded to state the push runs for every repo in the list, including the primary where it's a no-op the orchestrator's existing push path already covered.
• "no-op" compresses divergent-but-present branches — fixed-in-PR (commit 66fc1d1). Clarified that a branch already present on the remote — even one whose tip has diverged — is treated as already materialized (non-fast-forward rejection swallowed rather than force-pushed, so the primary's contract-init commit is never clobbered).

Verified against the code: orchestrator/kubernetes_spawner/_spawn.py:255 (push_branches=bool(repos) and len(repos) > 1) and gateway/worktree_manager/_create.py:566-660 (_materialize_work_branch_on_remote, already_materialized classification).

make lint is green for this change; the pre-existing mypy errors in shared/egg_agent/client.py are unrelated (they reproduce on the unmodified HEAD) and untouched by this docs-only PR.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns.

Re-reviewed the delta since my last approval. The only change is prose refinement to docs/architecture/slice-dag.md — the paragraph now clarifies that the remote push runs for every repo (a no-op on the primary) and that a divergent-but-present branch is treated as already materialized rather than force-pushed. This folds in the two non-blocking observations from the general review bot.

Still a documentation-only change describing the gateway/spawner mechanism. No agent prompts, pre-fetching, output formats, post-processing, rigid procedures, model identifiers, or LLM call paths are touched.

— Authored by egg

[egg-reviewer]

Re-review — delta verified accurate. No blocking issues.

Since my last review (84a331f) the only change is one commit (66fc1d1) that folds the two non-blocking observations from the prior review into the docs/architecture/slice-dag.md paragraph. This is still a documentation-only PR (16 additions, one file). I re-traced every factual claim in the revised paragraph to the code and all hold:

• len(repos) > 1 gating — orchestrator/kubernetes_spawner/_spawn.py:255: push_branches=bool(repos) and len(repos) > 1. ✅ Matches "Single-repo pipelines pass push_branches=False."
• create_worktrees(..., push_branches=True) threading — orchestrator/gateway_client/_worktree.py:21,83-84 sets request_data["push_branch"] = True; call site _spawn.py:228. ✅
• Runs for every repo including the primary — the gateway loop forwards the flag per-repo: gateway/gateway.py:7883 reads push_branch, and passes it unconditionally into each manager.create_worktree(..., push_branch=push_branch) at :7942. So the push is issued for every repo in the list, not just secondaries. ✅ Matches the new "including the primary, where it's a no-op…" wording.
• Refspec — gateway/worktree_manager/_create.py:598-599: target = (assigned_branch or branch_name).removeprefix("origin/"), refspec = "HEAD:refs/heads/{target}". ✅ Matches "pushed to refs/heads/{assigned_branch or work-branch}."
• Best-effort, non-forced, idempotent; divergent-but-present treated as materialized — _create.py:566-660: the push is non---force; up-to-date/up to date/non-fast-forward/fetch first/! [rejected] stderr is classified already_materialized and swallowed at info; other failures at warning; the outer try/except guarantees worktree creation never fails on the push. ✅ Matches the new "even one whose tip has diverged … non-fast-forward rejection is swallowed rather than force-pushed, so the primary's contract-init commit is never clobbered."

The revised prose is a strict improvement in precision over the version I first reviewed and introduces no inaccuracy. Placement (immediately after "Per-repo work branch & context PR") remains correct and contradicts nothing adjacent. No security, correctness, or robustness concerns in a docs-only change.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

5 previous review(s) hidden.