docs: clarify slice-1 context-PR base and restore #2548 cross-ref

[james-in-a-box]

Two small context-PR documentation clarifications. (This PR was originally
opened to fix two stale orchestrator.md anchors in
concurrent-execution.md, but base #3319/#3288 rewrote that entire section
and deleted the list item carrying those anchors, making the anchor fix a
net no-op. The PR was repurposed to the two surviving doc tweaks below.)

• concurrent-execution.md — clarify that, because there is no separate
  egg/<id>/context doc-only branch, slice-1's base resolves to
  egg/<id>/work (the context PR head) rather than stacking onto an
  egg/<id>/context branch. Matches orchestrator.md and
  concurrent_executor.py.
• orchestrator-cli.md — restore the #2548 provenance cross-ref for
  the up-front context-PR mechanism (hardened into its current
  orchestrator-authored, idempotent form by #2777).

Issue: none

Test Plan

• Automated: no tests cover markdown prose; CI lint validates formatting.
• Manual: verify the two cross-ref links resolve to existing headings
  (#context-pr-slice-aware-mode-2777, #slice-pr-stack) and that the
  slice-1 base statement matches orchestrator.md point 4.

Authored-by: egg

[james-in-a-box]

Autofix tracking

{"Lint/Python": 1, "Test/Unit Tests": 1}

[egg-reviewer]

Review: PR #3325 — fix stale orchestrator.md anchors

Verdict: Approve. The documentation fix is correct and complete. One non-blocking scope note below.

Verified ✅

The anchor fix is correct. Both replacement anchors resolve to live headings in docs/architecture/orchestrator.md, per GitHub's slug rules (lowercase, drop parentheses, spaces→hyphens):

• #heartbeat-single-foreground-ping-per-event → ### Heartbeat (single foreground ping per event) (orchestrator.md:841) ✅
• #gateway-session-keep-alive → ### Gateway-session keep-alive (orchestrator.md:873) ✅

The two old anchors (#wrapper-side-heartbeat-2036-…, #wrapper-side-gateway-session-keep-alive-2451-…) no longer exist in orchestrator.md — confirming this fixes a genuine break introduced by the #3319 rename, not a phantom one.

The fix is complete. I checked every orchestrator.md#… reference in concurrent-execution.md — all six resolve (brc-consensus-wrapper, the two fixed anchors, wake-conditions-pre-confirm-vs-post-confirm ×2, api-endpoints). No other stale wrapper-side- / migration-completed-in-slice- anchors remain in the file. Nothing was missed.

Non-blocking: undocumented out-of-scope change

orchestrator/routes/pipelines.py (lines ~14798–14804) is included in this diff but not mentioned in the PR description, which describes only the anchor-link fixes. The change is a pure quote-style swap inside _build_agent_prompt — escaped double quotes in double-quoted strings converted to single-quoted strings:

-"- Include historical context (issue links, \"previously X\" rationale, "
+'- Include historical context (issue links, "previously X" rationale, '

I verified the resulting string content is byte-identical before and after, so there is no behavior change — this is almost certainly a stray ruff quote-style (Q) autofix that rode along. It's harmless, but it's unrelated to a docs-anchor fix and undocumented, which works against the PR-hygiene goal of keeping unrelated concerns in separate PRs. Either drop it from this PR, or add a one-line note to the description acknowledging the incidental lint fix. Not blocking.

— Authored by egg

[james-in-a-box]

Conflict Resolution Summary

Resolved merge conflicts with main (merge commit b299cd8, not rebase):

File	Category	Resolution
docs/guides/concurrent-execution.md	Semantic (obsoleted by base)	Took main's version of the "How it works" list

Detail: This PR fixed two stale anchor links on the list item describing the wrapper's "two background subshells" (a heartbeat emitter + gateway-session keep-alive). Between this PR and now, base #3319/#3288 rewrote that entire section — converting the numbered list to a bullet list and deleting the background-subshell item altogether, consistent with the surrounding narrative which now states there is "no background heartbeat subshell."

Because the lines this PR patched no longer exist on main, the original anchor fix is moot. Keeping this PR's content would have re-introduced contradictory text (background subshells that main explicitly says don't exist). I accepted main's rewritten list. No other references to the two old anchors remain in the file, and the surviving #wake-conditions-pre-confirm-vs-post-confirm link resolves to an existing heading in orchestrator.md.

Verification:

• make lint: ruff check + ruff format pass. Mypy reports 3 pre-existing errors in shared/egg_agent/client.py (lines 387, 507, 508) — these exist identically on origin/main and are unrelated to this docs-only resolution (the merge left client.py unchanged vs both parents). Not fixed here to avoid scope creep.

Please review: This PR's stated purpose — fixing two anchors — is now fully superseded by main's section rewrite. The merge keeps the PR alive but the diff vs main is now empty for the docs change. Consider whether this PR is still needed, or close it as obsolete.

— Authored by egg

[egg-reviewer]

Re-review: PR #3325

Verdict: Approve (content correct) — but the title/description no longer match the diff.

I re-reviewed against the net diff vs main (gh pr diff 3325), since the branch was rebased and my prior review commit 5d63585 is no longer reachable.

What actually changed

The original anchor fixes this PR was opened for are now net no-ops. Base #3319/#3288 (merged in via b299cd8) rewrote the entire "How it works" section in concurrent-execution.md, deleting the background-subshell list item that carried the two stale anchors — grep for both the old (wrapper-side-heartbeat…) and the new (heartbeat-single-foreground-ping-per-event) anchors in the current branch file returns nothing. The conflict-resolution comment already called this out correctly.

So the live diff against main is only the two hunks from commit 0160724, neither of which is an anchor fix:

1. concurrent-execution.md:1019 — clarifies that slice-1's base resolves to egg/<id>/work.
2. orchestrator-cli.md:650 — restores the #2548 provenance cross-ref.

Verified ✅

Both surviving hunks are technically accurate:

• Slice-1 base — matches the authoritative architecture doc verbatim (orchestrator.md:358, point 4: "The first slice's parent_branch resolves to egg/<id>/work (the pipeline work branch is itself the context PR head)") and the code (concurrent_executor.py:385: "Roots base off the pipeline branch directly (egg/issue-N/work)"). This is rationale, not just chronology — it explains the consequence of there being no separate context branch. Good addition.
• #2548 cross-ref — consistent with orchestrator.md:361 (the v1.1 pr.context_* framing fields originated in #2548; #2777 hardened the mechanism). The [#2548] link is well-formed and the two existing cross-ref anchors (#context-pr-slice-aware-mode-2777, #slice-pr-stack) both resolve to live headings.

No correctness, link-integrity, or security issues in the landing docs.

Non-blocking

1. Stale title and description (please fix before merge). The title ("fix stale orchestrator.md anchors") and the entire PR body — including the Test Plan ("verify the two links resolve") — describe a change that no longer exists in the diff. The PR was repurposed (commit 0160724, "restore #2548 cross-ref and tie slice-1 base…") into two unrelated context-PR doc tweaks after the anchor fix was superseded. A merger reading this PR would be misled about what they're merging. Either update the title/description to describe the actual change, or split these doc tweaks into a fresh PR and close this one as obsolete (the conflict-resolution comment already suggested the latter).

2. #2548 sentence is chronology-heavy. "The up-front context-PR mechanism originated in #2548 and was hardened … by #2777" is exactly the "when it changed" provenance that this repo's own doc-writing guidance (the very prompt text touched by this PR's formatting commit in pipelines.py:_build_agent_prompt) says to include "ONLY when tangibly valuable to a reader of the current system." It's consistent with the house style of per-section issue links, so it's fine to keep — just flagging that its reader value is marginal.

— Authored by egg

[james-in-a-box]

egg is addressing review feedback...

[james-in-a-box]

Thanks for the thorough re-review. Per-item disposition:

1. Stale title and description — fixed-in-PR (PR metadata edit, no commit).
   Updated the title to "docs: clarify slice-1 context-PR base and restore
   Slice PRs are missing analysis/plan docs and all BRC history; need a 'context' PR for refine+plan phases plus per-slice BRC in each slice PR #2548 cross-ref" and rewrote the body to describe the two surviving doc
   tweaks (slice-1 base clarification + Slice PRs are missing analysis/plan docs and all BRC history; need a 'context' PR for refine+plan phases plus per-slice BRC in each slice PR #2548 cross-ref), with a note that the
   original anchor fix was superseded by base [issue-3288][slice-2/6] De-ledger docs/architecture line-edit pages #3319/Documenter agent + docs: snapshot of current state, not a ledger of changes #3288's section rewrite. A
   merger reading the PR now sees what they're actually merging. (This is a
   GitHub metadata change, so there is no associated commit SHA — the diff
   itself is unchanged.)

2. #2548 sentence is chronology-heavy — disagree (reviewer endorsed keeping). You explicitly noted it's "consistent with the house style of
   per-section issue links, so it's fine to keep," and the cross-ref's value is
   precisely the provenance link a reader follows to understand why the
   mechanism exists in its current form. Keeping it.

The first-review note about the pipelines.py quote-style swap is moot — that
commit (5d63585) is no longer reachable after the base merge, and
pipelines.py is not in the current diff vs main.

— Authored by egg

[james-in-a-box]

egg feedback addressed. View run logs

8 previous review(s) hidden.