Shadow Execution Gate

Shadow Execution Gate

Purpose

Use a reproducible shadow run before promotion when changes are risky, cross-cutting, or expensive to debug post-merge.

This is a general software technique, not PairV2-specific.

When to use it

• Runtime/orchestration changes.
• CI workflow or environment changes.
• Refactors touching multiple subsystems.
• Any change where a rollback would be costly.
• Any PR with unclear integration risk.

Trigger policy (default)

Run Shadow Execution when any condition is true:

1. A critical path file is changed.
2. Changed files >= 8.
3. Core diff size >= 150 lines.
4. Prior incident/flakiness exists in touched area.

Core workflow

1. Build candidate from current branch.
2. Re-apply/replay in isolated workspace (/tmp/.../shadow/...).
3. Execute representative tasks/tests (small + large scenario where relevant).
4. Collect evidence bundle.
5. Compare against gate criteria.
6. Produce explicit decision: READY_FOR_PROMOTION or NOT_READY.

Evidence bundle (minimum)

• Exact commit SHA and branch.
• Commands executed.
• Pass/fail summary.
• Runtime/latency and retry metrics where applicable.
• Artifact completeness/missing artifacts.
• Key logs for failed steps.
• Decision rationale tied to acceptance criteria.

Decision rules

• Promote only if all required criteria pass and no critical regressions are observed.
• If any required criterion fails, block promotion and record targeted follow-up work.

Reporting template

• Scope tested:
• Scenarios executed:
• Evidence summary:
• Regressions found:
• Decision:
• Required follow-up:

Anti-patterns

• Treating a single local test run as equivalent to shadow validation.
• Skipping artifact/log capture.
• Declaring success without explicit go/no-go criteria.
• Relying on implicit confidence instead of measured evidence.