# 2. Bus Payload Specification & Validation

> **Core principle**: orchestratorX is the sole document writer. Payloads do not carry document paths or write instructions.

In xwhole/xlocal workflows, agents pass information via structured Payloads. orchestratorX validates format, forwards Payloads, and performs document updates.

---

## 2.1 Payload Type 1: coderX -> orchestratorX -> evaluatorX (Change Summary)

coderX outputs after completing implementation. orchestratorX validates and forwards to evaluatorX.

```markdown
### Bus Payload: Change Summary
- **Changed Files**:
  - [file path] — [modification role/logic summary]
  - ...
- **Affected ACs (claimed)**:
  - [AC identifier or summary] — [change reason: new implementation / fix / adjustment]
  - ...
- **Directed Audit Points**: [prompt evaluatorX to focus on complex logic or external dependencies]
```

> **`Affected ACs (claimed)` notes**:
> - coderX declares which ACs this round's changes affect. evaluatorX cross-validates via git diff and does not fully trust this declaration.
> - First iteration (no prior evaluation) may omit this; evaluatorX automatically enters `full` mode.
> - If missing in subsequent rounds, orchestratorX issues a warning; evaluatorX falls back to `full` mode.

---

## 2.2 Payload Type 2: evaluatorX -> orchestratorX (Evaluation Result)

evaluatorX outputs after completing evaluation. orchestratorX reads this Payload for document updates and iteration decisions.

```markdown
### Bus Payload: Evaluation Result

#### AC Status Table
| AC | Status | Eval Method | Code Location | Basis / Gap |
|----|--------|-------------|---------------|-------------|
| [AC identifier] | Pass / Partial Pass / Fail / Unevaluable | this_round / inherited | [file:line] | [basis or gap description] |

- Total: [n] | Pass: [n] (this: [n], inherited: [n]) | Partial: [n] | Fail: [n] | Unevaluable: [n]

#### Issue List
| # | Type | Severity | Location | Description |
|---|------|----------|----------|-------------|
| 1 | [requirement deviation / logic defect / spec issue] | P0/P1/P2 | [file:line] | [issue description] |

#### Fix Instructions
> Structured fix instructions. orchestratorX passes directly to coderX without human interpretation.
- [ ] [file:line] — [specific fix action] (Priority: P0/P1)
- [ ] [file:line] — [specific fix action] (Priority: P0/P1)

#### Blocking Dependencies
> Only output when unsatisfied cross-branch dependencies are detected. Empty when no blocking.
- [Child path] depends on [Child path] — [reason] (status: [current status])

#### Cross-Branch Violations
> Only output when cross-branch file conflicts are detected. Empty when no conflicts.
- [file] modified by current Child, owned by [other Child] — severity: P0

#### Conclusion
- **Evaluation Result**: [PASS | Needs Fix]
- **evaluation_mode**: [full | partial | prompt-based]
- **Summary**: [one paragraph summarizing implementation quality, main gaps, suggested next steps]
```

---

## 2.3 Payload Type 3: Requirement Change (orchestratorX internal)

Generated by orchestratorX during the Requirement Change Handling flow to drive document updates.

```markdown
### Bus Payload: Requirement Change
- **Change Type**: [adjustment | optimization | scope_expansion | scope_reduction | new_branch]
- **Needs Confirmation**: [true/false]
- **Confirmation Prompt**: [only filled when Needs Confirmation=true]

- **Target Child**: [path or "new"]

- **AC Changes**:
  - [action: add/modify/remove] [AC identifier] — [new content or change description]

- **New Child Description** (new_branch only):
  - **Description**: [new sub-module feature description]
  - **Suggested ACs**: [suggested acceptance criteria list]
  - **Suggested Files**: [suggested file scope]

- **Parent Routing Update**:
  - [action: update_row/add_row] [Child path] — scope/ac_count filled by orchestratorX after Child creation

- **Dependency Changes**:
  - [action: add/remove] [Child A] -> [Child B] — [reason]

- **Affected Children**:
  - [Child path] — Status reset to "Needs Re-evaluation"
```

---

## 2.4 Validation Rules (Optimized: Fast-Path)

**Format check**: After each agent returns, orchestratorX checks that all `- **Field**:` entries in the Payload exist and are non-empty.

**Semantic check** (Payload Type 1): At least one file in `Changed Files` must appear in `git diff`. If none match, treat as anomaly.

**Fast-Path Validation** (NEW):
```
// Skip expensive validation when payload is from known-good source
if (payload_source === 'coderX' && 
    payload.has_field('Changed Files') && 
    payload.has_field('Affected ACs') &&
    !payload.is_first_iteration) {
  // Quick format check only, skip git diff semantic check
  return VALID;
}

// First iteration or fix round: full validation
return fullValidation(payload);
```

- **Validation failure**: Do not forward to downstream agent. Append format correction instructions and re-invoke the upstream agent. Retry at most **1** time. If second attempt also fails, stop workflow and report to human.
- **Validation pass**: Forward the validated Payload as the primary context to the downstream agent.

## 2.5 Incremental Context Passing (NEW)

When iterating on the same Child, use incremental context to reduce token consumption:

### First Iteration
```
Full context: Parent §0-6, §7, §8.1, §8.2, §8.3 + Child §7, §8.1
```

### Subsequent Iterations (Same Child)
```
Incremental context:
- Parent §0-6: [Cached, see Parent document §0-6]
- Parent §7: [Cached, see Parent document §7]
- Parent §8.1: [Cached, see Parent document §8.1]
- Parent §8.2: [Cached, see Parent document §8.2]
- Parent §8.3: [Cached, see Parent document §8.3]
- Child §7: [Full content - may have changed]
- Child §8.1: [Full content - may have changed]
- Change Summary: [Current iteration's changes]
- Fix Instructions: [From last evaluation, if any]
```

**Expected Savings**: 40-60% token reduction in multi-iteration scenarios.
