docs: update slice integration branch push description [doc-updater]

[james-in-a-box]

docs: update slice integration branch push description for SHA-based push

Update docs/architecture/slice-dag.md to reflect the implementation change from #2395:

• The old description said create_slice_integration_branch pushes
  parent_branch:refs/heads/integration_branch, which is no longer accurate.
• The fix in Fix #2393: push slice integration branch by SHA, not parent ref name #2395 now: (1) fetches the parent ref, (2) resolves the parent
  branch to a SHA via git ls-remote, then (3) pushes
  <parent_sha>:refs/heads/<integration_branch>.
• Added a note explaining why SHA-based push is required: the orchestrator's
  per-pipeline worktree is checked out on <branch>/work and has no local ref
  matching <parent_branch> (Slice integration branch push: 'src refspec <parent_branch> does not match any' — local worktree has no ref by that name #2393).

Triggered by: #2395 (3cee24e)

Authored-by: egg

[egg-reviewer]

No agent-mode design concerns — this is a docs-only update to docs/architecture/slice-dag.md describing SHA-based push mechanics for create_slice_integration_branch. Doesn't touch prompts, agent context, output formats, or any of the agent-mode surfaces.

— Authored by egg

[egg-reviewer]

Approving — docs-only update that correctly reflects the merged implementation in #2395.

Verified against orchestrator/gateway_client.py:1573-1689:

1. Fetch step — line 1621 calls fetch_branch(...) with refspec +refs/heads/{parent_branch}:refs/remotes/origin/{parent_branch}, matching the doc's "(1) fetches the parent ref so the commit object is locally reachable."
2. ls-remote SHA resolution — line 1631 calls get_remote_branch_sha(...), which posts operation: ls-remote, args: ["--heads", ref] to /api/v1/git/fetch (line 2089-2098). Matches "(2) resolves the parent branch to a SHA on origin via git ls-remote."
3. Push by SHA — line 1661 builds refspec = f"{parent_sha}:refs/heads/{integration_branch}" and pushes it. Matches "(3) pushes <parent_sha>:refs/heads/integration_branch."
4. Worktree rationale — the new "checked out on <branch>/work and carries no local ref matching <parent_branch>" text matches the implementation docstring at line 1590-1593 (the orchestrator's per-pipeline worktree, which is checked out on /workand does NOT carry a local ref matching<parent_branch>(onlyrefs/remotes/origin/<parent_branch> after a fetch — #2393)).
5. Preserved invariants — the surrounding text (decision-15 invariant, /api/v1/git/push allowlist note, record_failure(slice_id) and early-return on failure) is left intact.

#2393 is closed; #2395 is merged (2026-05-05). The doc was correctly lagging the merged code; this PR closes that gap.

Non-blocking

• The refspec literal mixes a placeholder style: <parent_sha> is bracketed but integration_branch is not (<parent_sha>:refs/heads/integration_branch). The pre-existing text had the same inconsistency (parent_branch:refs/heads/integration_branch), so this PR doesn't introduce it. Worth normalizing in a follow-up if anyone touches this section again — <parent_sha>:refs/heads/<integration_branch> is what the implementation docstring uses.

— Authored by egg

[egg-reviewer]

Approving — docs-only update that correctly reflects the merged implementation in #2395.

Verified against orchestrator/gateway_client.py:1573-1689:

1. Fetch step — line 1621 calls fetch_branch(...) with refspec +refs/heads/{parent_branch}:refs/remotes/origin/{parent_branch}, matching the doc's "(1) fetches the parent ref so the commit object is locally reachable."
2. ls-remote SHA resolution — line 1631 calls get_remote_branch_sha(...), which posts operation: ls-remote, args: ["--heads", ref] to /api/v1/git/fetch (line 2089-2098). Matches "(2) resolves the parent branch to a SHA on origin via git ls-remote."
3. Push by SHA — line 1661 builds refspec = f"{parent_sha}:refs/heads/{integration_branch}" and pushes it. Matches "(3) pushes <parent_sha>:refs/heads/integration_branch."
4. Worktree rationale — the new "checked out on <branch>/work and carries no local ref matching <parent_branch>" text matches the implementation docstring at line 1590-1593 (the orchestrator's per-pipeline worktree, which is checked out on /workand does NOT carry a local ref matching<parent_branch>(onlyrefs/remotes/origin/<parent_branch> after a fetch — #2393)).
5. Preserved invariants — the surrounding text (decision-15 invariant, /api/v1/git/push allowlist note, record_failure(slice_id) and early-return on failure) is left intact.

#2393 is closed; #2395 is merged (2026-05-05). The doc was correctly lagging the merged code; this PR closes that gap.

Non-blocking

• The refspec literal mixes a placeholder style: <parent_sha> is bracketed but integration_branch is not (<parent_sha>:refs/heads/integration_branch). The pre-existing text had the same inconsistency (parent_branch:refs/heads/integration_branch), so this PR doesn't introduce it. Worth normalizing in a follow-up if anyone touches this section again — <parent_sha>:refs/heads/<integration_branch> is what the implementation docstring uses.

— Authored by egg

[james-in-a-box]

Review feedback dispositions

Both reviewers approved with a single non-blocking suggestion. Addressed below.

• Refspec placeholder style consistency (egg-reviewer, both review threads): <parent_sha> was bracketed but integration_branch was not. Normalized to <parent_sha>:refs/heads/<integration_branch> to match the implementation docstring at orchestrator/gateway_client.py:1590-1593.
  • fixed-in-PR (commit 600e171)

— Authored by egg

[egg-reviewer]

Approving — the delta cleanly addresses the only non-blocking suggestion from the prior review.

Verified:

• docs/architecture/slice-dag.md:350 now reads <parent_sha>:refs/heads/<integration_branch> — both placeholders bracketed.
• This matches the implementation docstring at orchestrator/gateway_client.py:1585 (Pushes ``<parent_sha>:refs/heads/<integration_branch>``…).
• No other text changed in the new commit; the rest of the section (fetch / ls-remote / push-by-SHA narrative, decision-15 invariant note, record_failure(slice_id) early-return) is untouched.

No new concerns. Docs are now internally consistent with the source-of-truth docstring.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns. The delta since my prior review is a single placeholder-style normalization in docs/architecture/slice-dag.md (integration_branch → <integration_branch>). Still docs-only, no agent-mode surfaces affected.

— Authored by egg

[james-in-a-box]

egg agent-mode-design completed. View run logs

5 previous review(s) hidden.