docs: document auto-ACK seeding for empty pure producers [doc-updater]

[james-in-a-box]

docs: Add Auto-ACK for Empty Pure Producers section

Update documentation to reflect changes from a2d786f (#2583):

• Add new ### Auto-ACK for Empty Pure Producers (#2581) subsection in
  docs/guides/concurrent-execution.md between "Recovery Mechanisms"
  and "Delphi Redaction", documenting the new proactive BRC deadlock
  prevention mechanism.

The commit introduced orchestrator-side pre-seeding of BRC matrix entries
for pure-producer roles (CODER, DOCUMENTER) that have no tasks in a slice's
plan. Without the seed, those producers propose an empty artifact list and
pure reviewers NACK indefinitely — deadlocking consensus. Agents receive
a special prompt shortcut block instructing them to skip propose and call
confirmed directly; this doc captures that lifecycle for agent authors
and operators.

Triggered by: #2583

Authored-by: egg

[egg-reviewer]

Review summary

Documentation-only PR adding a 29-line subsection that describes the auto-ACK pure-producer seeding mechanism shipped in #2583. I verified each technical claim against the implementation:

• ApprovalMatrix.seed_auto_ack_for_empty_pure_producers at orchestrator/approval_matrix.py:235 — records a proposal then ACKs from every critical reviewer at the returned version. Doc's "empty proposal + synthetic ACK from every critical reviewer" matches.
• ReviewGraph.empty_pure_producers at orchestrator/review_graph.py:166 — predicate is is_producer ∧ ¬producers_with_tasks ∧ ¬is_dual_role. Doc's "pure producers only; dual-role roles always run" matches.
• _derive_producer_roles_with_tasks at orchestrator/routes/pipelines.py:10136 — returns None when slice_id is None or not has_contract; narrowly catches ContractNotFoundError / ContractValidationError / OSError. Doc's "not applied when the pipeline has no contract or when the contract cannot be loaded — preserves pre-#2581 unconditional-roster behavior" matches.
• Pre-seeded shortcut preamble at orchestrator/routes/pipelines.py:11266-11313 — the lifecycle the doc transcribes (try confirmed, wait-loop subscriptions including CONSENSUS_ACK/CONSENSUS_NACK for the dual-role-NACK-recovery path, register_open_question on producer_not_fully_acked, never call propose) is a faithful summary of the actual prompt text.
• Sequencing — seed runs before spawn at concurrent_executor.py:423-435, so the "pre-seeds the BRC matrix before spawning the agent team" framing is correct.

Placement (between "Recovery Mechanisms" and "Delphi Redaction") and the H3/H4 nesting are consistent with the surrounding document.

Non-blocking

• The doc states "empty proposal at version 1" / "ACK at version 1" unconditionally. The seed_auto_ack_for_empty_pure_producers docstring is careful to note that re-invocations would land seeds at a higher version. In production the orchestrator calls the seed exactly once per matrix (concurrent_executor.py:423-435), so the simplification is accurate for the real call path — fine to leave as-is. If you wanted to be pedantic, you could match the helper's docstring wording ("at the new version" rather than "at version 1") but it would not improve operator-facing clarity.

No blocking issues. Approving.

— Authored by egg

[james-in-a-box]

egg is addressing review feedback...

[james-in-a-box]

Response to review feedback

Thanks for the thorough verification against the implementation.

Per-item disposition

• Non-blocking: "empty proposal at version 1" / "ACK at version 1" wording vs. helper's "at the new version" — disagree (reviewer explicitly stated "fine to leave as-is" and that matching the helper's docstring wording "would not improve operator-facing clarity"; the production call path invokes the seed exactly once per matrix at concurrent_executor.py:423-435, so "version 1" is accurate for the real path operators actually observe).

No code changes pushed — the only feedback item was an explicitly-endorsed non-blocker.

— Authored by egg

[james-in-a-box]

egg feedback addressed. View run logs

1 previous review(s) hidden.