FWS-2 — Workflow correlation ID threading (X-Initializ-* headers → audit events)

[initializ-mk]

Part of the Forge backlog. Backend pairing: initializ WS-4 (correlation). Effort: XS (2–3 engineer-days). Risk: low. Depends on: nothing.

Scope

Forge agents accept workflow correlation headers from the orchestrator and propagate them through every audit event the agent emits during that invocation.

Why this matters

initializ WS-4 (correlation IDs) requires Forge to read incoming X-Initializ-Workflow-ID, X-Initializ-Stage-ID, X-Initializ-Step-ID, X-Initializ-Invocation-Caller headers and tag every audit event with them. Without this, audit across an orchestrated workflow is fragmented — each agent's events are correlated only by its own task ID, not by the workflow they're part of.

Deliverables

• A2A request handler reads orchestration headers from incoming calls.
• Headers parsed and stored in the agent's context.Context alongside existing CorrelationID / TaskID.
• Every audit event emitted during the invocation carries workflow_id, stage_id, step_id, invocation_caller if present.
• If no orchestration headers present (direct A2A invocation, not through initializ), audit emits without the fields — backward compatible.
• Headers also propagate to any downstream A2A calls the agent makes (agent invoking another agent during workflow execution).

Architectural decisions

• Where in the codebase the header parsing lives — recommend the A2A request handler layer, before the request reaches skill execution. Skill code shouldn't need to know about workflow correlation.
• Header propagation on outbound A2A calls — if a Forge agent calls another agent over A2A (peer-to-peer, not via orchestrator), do workflow IDs propagate? Recommend yes — same headers on outbound calls. This preserves trace integrity through agent-to-agent flows.

Risks

Low. Pure plumbing — header parsing, context.Context threading, audit event field addition.