docs: document server-side contract decision bridge [doc-updater]

docs/guides/sdlc-pipeline.md

@@ -672,6 +672,8 @@ Pipeline decisions made during refine and plan phases are automatically synced t
 5. Synced decisions appear in `.egg-state/contracts/{identifier}.json` under the `decisions` array
 6. Implement-phase agents can read these decisions from the contract to understand context
 
+Agents can also register questions directly in the contract via `egg-contract add-decision` / `egg-contract add-feedback`. These writes bypass the orchestrator's decision queue. After phase gate approval, `_queue_and_await_contract_decisions()` promotes any unresolved contract HITL decisions and feedback into the orchestrator queue so they are surfaced to the human. Resolutions are written back to the contract before the next phase starts.
+
 **What gets synced:**
 
 - Resolved decisions with `decision_type != "phase_gate"` (substantive choices, not process gates) — via `_sync_pipeline_decisions_to_contract()`
@@ -681,7 +683,7 @@ Pipeline decisions made during refine and plan phases are automatically synced t
 
 **Key files:**
 
-- `orchestrator/routes/pipelines.py` — `_sync_pipeline_decisions_to_contract()` and `_persist_phase_gate_resolution()` implementations
+- `orchestrator/routes/pipelines.py` — `_sync_pipeline_decisions_to_contract()`, `_persist_phase_gate_resolution()`, and `_queue_and_await_contract_decisions()` implementations
 - `orchestrator/models.py` — `HITLDecision` model (pipeline state)
 - `shared/egg_contracts/models.py` — `Decision` model (contract state)
 

docs/hitl-decisions.md

@@ -230,7 +230,11 @@ In prompt-driven mode (`egg-sdlc`), the HITL checkpoint handler (`sandbox/egg_li
 
 ### Contract Decision Bridge
 
-Contract decisions created by agents via `egg-contract add-decision` are automatically bridged to the phase gate menu in prompt-driven mode. When unanswered decisions exist in the contract JSON, the phase gate displays a `[q] Answer open questions` option that lets humans respond directly from the terminal. Approving a phase gate with unanswered questions triggers a warning prompt.
+Two complementary bridges ensure contract-scoped decisions created by agents via `egg-contract add-decision` / `egg-contract add-feedback` are surfaced to humans:
+
+**Server-side bridge (all modes):** After a phase gate is approved, `_queue_and_await_contract_decisions()` in `orchestrator/routes/pipelines.py` promotes any unresolved contract HITL decisions and feedback into the orchestrator's decision queue. HTTP/MCP callers (e.g., the `/sdlc` skill's Phase 4 handler) receive them as individual `choice` or `feedback` decisions. Once resolved, answers are written back to the contract so implement-phase agents see the human's choices. Without this bridge, contract questions registered via `egg-contract` would be silently dropped when a phase gate was approved, leaving the next phase's agents without the answers they need.
+
+**Client-side bridge (prompt-driven mode only):** In prompt-driven mode, the phase gate menu displays a `[q] Answer open questions` option when unanswered decisions exist in the contract JSON, letting humans respond from the terminal before approving. Approving a phase gate with unanswered questions triggers a warning prompt.
 
 ### Draft Document Display