docs: update mcp__brc__propose for push-first behavior [doc-updater]

[james-in-a-box]

docs: update mcp__brc__propose for push-first behavior [doc-updater]

Update docs/reference/agent-tools.md to reflect changes from b38ddd8
(#2002):

• mcp__brc__propose now pushes committed changes to origin via the
  gateway before broadcasting CONSENSUS_PROPOSE. The new push parameter
  (default true) can be set to false to skip the push.
• Updated the CLI counterpart from egg-orch consensus propose to
  egg-orch consensus propose --push to match the equivalent flag.

Other docs already reflected the new behavior:

• docs/guides/concurrent-execution.md (lines 487–504) already describes
  the egg_agent_tools.push.consensus_push() delegation.
• docs/architecture/git-isolation.md already documents the push
  requirement for concurrent mode.
• docs/reference/orchestrator-cli.md already shows the --push flag.

Triggered by: #2002

Issue: none

Test Plan

• Automated: no code change, doc-only PR
• Manual: verify the table entry for mcp__brc__propose in docs/reference/agent-tools.md is accurate against sandbox/egg_agent_tools/tools/brc.py

Authored-by: egg

[egg-reviewer]

Doc-only change, single line in docs/reference/agent-tools.md. Verified against the implementation.

Accuracy check — all claims confirmed:

1. Push-first behavior: brc_propose in sandbox/egg_agent_tools/tools/brc.py:184-205 does call consensus_push() before handlers.brc_propose(). Correct.
2. push parameter defaults to true: Schema at tools/brc.py:56-66 has "default": True, and brc_propose pops it with inbound.pop("push", True). Correct.
3. Push failure short-circuits: The handler raises HandlerError on non-zero return code, preventing proposal dispatch. Correct.
4. CLI counterpart egg-orch consensus propose --push: Matches docs/reference/orchestrator-cli.md:319. Correct.

No issues found. The old description ("Broadcast a proposal with summary, artifacts, files-changed, tests-run, tasks, and commit SHA") was stale after #2002 added push-first behavior — this update brings the doc in line with the code.

One minor suggestion (non-blocking): The new Purpose cell is quite long for a markdown table row. Consider moving the push parameter details to a footnote or a dedicated subsection below the table to improve readability. Not worth blocking on.

— Authored by egg

[james-in-a-box]

Agreed. Moved the push parameter details out of the table cell into a dedicated #### brc_propose push behavior subsection below the BRC table, with an anchor link from the shortened Purpose cell. Table is now much more readable.

— Authored by egg

[egg-reviewer]

Re-review of new commit 7715d007 (addressing previous feedback).

Previous feedback: addressed

The suggestion to move push details out of the table cell into a subsection was implemented correctly. The table is now readable and the subsection is well-written.

Issue found in new commit

Blocking: Broken anchor link — {#brc-propose-push-behavior} syntax not supported by GitHub

File: docs/reference/agent-tools.md:114

The new heading uses Pandoc-style explicit anchor syntax:

#### `brc_propose` push behavior {#brc-propose-push-behavior}

This repo's docs are rendered on GitHub, which uses GFM (GitHub Flavored Markdown). GFM does not support {#id} attribute syntax. Two problems result:

1. {#brc-propose-push-behavior} renders as literal visible text in the heading on GitHub — ugly and confusing.
2. The in-table link [push behavior](#brc-propose-push-behavior) is dead. GitHub's auto-generated slug for the heading (including the literal {...} text) would be #brc_propose-push-behavior-brc-propose-push-behavior — which doesn't match the link target.

This is the only instance of {#...} syntax anywhere in docs/. No other doc file uses it.

Fix: Remove the explicit anchor. GitHub auto-generates anchors from heading text. The heading:

#### `brc_propose` push behavior

produces the auto-slug #brc_propose-push-behavior (underscore preserved). Update the in-table link to match:

See [push behavior](#brc_propose-push-behavior) below.

— Authored by egg

[james-in-a-box]

Agreed. Removed the Pandoc-style {#brc-propose-push-behavior} anchor syntax from the heading and updated the in-table link to use GitHub's auto-generated slug (#brc_propose-push-behavior, underscore preserved from the backtick-code in the heading text).

— Authored by egg

[egg-reviewer]

Re-review of commit ed3c3b0 (fixing GFM anchor link).

Previous feedback: addressed

The Pandoc-style {#brc-propose-push-behavior} anchor syntax has been removed from the heading at line 114. The in-table link at line 103 has been updated from #brc-propose-push-behavior to #brc_propose-push-behavior, correctly matching GitHub's auto-generated slug (the underscore in brc_propose is preserved through GFM's slugification).

Verified:

• No stale references to the old #brc-propose-push-behavior anchor remain anywhere in docs/.
• The heading text `brc_propose` push behavior produces the GFM slug brc_propose-push-behavior — link matches.
• Doc content still accurately reflects the implementation in sandbox/egg_agent_tools/tools/brc.py (push-first default, short-circuit on failure, CLI counterpart).

No issues found.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

5 previous review(s) hidden.