handoff-packet-validator

# Handoff Packet Validator v3.8.6 (Grok 4.6 · Schema Gate)

**Tool skill** — data-driven schema checks for agent handoff JSON. Blocks broken packets before Identity Lock, extend/stitch, i2v, or Imagine spend.

**Engine:** `.grok/skills/handoff-packet-validator/scripts/validate_handoff.py`  
**Canonical Imagine Agent Mode schema:** `tools/handoff_schema.py`  
**Field cheat sheet:** `references/packet_types.md`

## Model Layer (Grok 4.6)

| Task type | Preferred model | Effort |
|-----------|-----------------|-----------|
| Multi-agent orchestration / handoff synthesis | `grok-4.6` | xhigh |
| Specialist deep craft / QA / identity-critical | `grok-4.6` | high |
| Routine status / draft passes | `grok-4.6` | medium |

**Stack default:** cinematic+Build API/chat **`grok-4.6`**. Opt-in 1M: `grok-4.3`.  
**Registry:** `cinematic-skill-creator/references/agents/MODEL_LAYER_v4.6.md`

```yaml
model_compatibility:
  - grok-4.6
preferred_model: grok-4.6
reasoning_effort: high
context_window: 500000
knowledge_cutoff: 2026-02-01
```

### Imagine Video dual-path (when this skill touches video)
- **1.5 Native** — preferred for hero / final motion with audio when budget allows
- **1.0** — cost default / draft / pre-viz; label outputs so downstream agents do not assume 1.5 capabilities

## When to Activate

- After `dna handoff` / DNA Extractor packets  
- After `sequence handoff` or Sequence Extender packets  
- Before `ACTIVATE IDENTITY_LOCK` load of external JSON  
- Before `ACTIVATE I2V_SPECIALIST` or extend/stitch generation  
- Before Imagine Agent Mode Handoff execution (any surface)  
- When chain QA fails on continuity / momentum fields that should have been in the packet  
- User says: `VALIDATE HANDOFF`, `RUN HANDOFF VALIDATOR`, `CHECK HANDOFF PACKET`

## When NOT Required

| Situation | Note |
|-----------|------|
| Pure in-session chat with no JSON packet | No file to validate |
| Already-locked DNA in project state without file export | Optional — re-validate if regenerating `handoff.json` |
| Editing prompts only | Use Imagine Prompt Master |

## Supported Packet Types

| `packet_type` | Producer → Consumer |
|---------------|---------------------|
| `identity_lock_handoff` | Character DNA Extractor → Identity Lock |
| `sequence_extend_handoff` | Sequence Extender / Sequence Director → next clip / Chain QA |
| `asset_manifest_entry` | Reference Asset Curator → i2v / batch / Prompt Master |
| `intimacy_state_handoff` | ErosForge / NSFW Sequence Extender → next intimate clip. Requires `legal_gate: PASS` + six `legal_checks`. |
| `imagine_agent_mode_handoff` | Studio Director → Build tools / ACP / grok.com / xAI API |

Unknown `packet_type` → **fail**. See `references/packet_types.md` for required fields.

## CLI

Run the real scripts. Do not invent schema. Do not silent-pass spend gates.

```bash
# Schema + legal-gate (default). drift_evidence and readiness are warnings.
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py path/to/handoff.json
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py characters/hero-slug/handoff.json
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py artifacts/handoffs/clip_001_extend.json

# Before Imagine spend — readiness blockers become exit 1
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py packet.json --strict-handoff

# Before hero i2v / extend spend — plate + motion_vector readiness become exit 1
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py packet.json --strict-wave-a

# Agent-mode surface / bridge ack (separate process; not called by validate_handoff.py)
python .grok/skills/handoff-packet-validator/scripts/validate_surface.py packet.json
python .grok/skills/handoff-packet-validator/scripts/validate_surface.py packet.json --strict
```

| Exit | Meaning |
|------|---------|
| `0` | Valid (may include warnings) |
| `1` | Schema / JSON / legal-gate errors, or readiness blockers with `--strict-handoff` / `--strict-wave-a` |
| `2` | Usage or file not found |

**Flag policy:** `VALIDATE HANDOFF` / `CHECK HANDOFF PACKET` with no flag → default run. Recommend `--strict-handoff` when `packet_type` is `imagine_agent_mode_handoff`. Recommend `--strict-wave-a` when the next action is hero i2v or extend. Run `validate_surface.py` on every agent-mode packet; use `--strict` before Surface A/B/C/D execution.

**This workspace:** if `tools/handoff_schema.py` is missing, agent-mode and Wave A schemas are skipped and `imagine_agent_mode_handoff` fails as unknown `packet_type`. Do not claim agent-mode PASS in that state.

Unknown `packet_type` fails. `aup_compliance_handoff` is not a type (`aup_gate` is a sidecar only). Do not set `legal_gate` to PASS to clear a fail. Prefer regenerating via producer CLI unless the user owns the packet and asked for an edit.

## Identity Continuity (`drift_evidence`)

For `sequence_extend_handoff` and `identity_lock_handoff`, missing or incomplete
`drift_evidence` produces **warnings** (exit 0). Invalid `status` enums are **errors**.
Protocol: `references/agents/IDENTITY_CONTINUITY_PROTOCOL_v3.8.md`  
CLI: `sequence drift-score`

## Generation handoff readiness (`imagine_agent_mode_handoff`)

After schema OK, semantic readiness runs as **warnings** (exit 0): empty i2v
references, video without motion cues, weak `return_path`, placeholder quota,
missing/incomplete `specialist_checklist` (GHR-09/10), etc.

Hard-fail (exit 1 on readiness blockers):

```bash
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py packet.json \
  --strict-handoff
# or emit with hard gate:
python tools/cinematic_studio_cli.py imagine agent-handoff ... --strict-handoff
```

Helper: `tools/handoff_readiness.py` · Protocol: `IMAGINE_AGENT_MODE_HANDOFF_v3.7.1.md`

### Generate packets then validate

```bash
# Identity
python tools/cinematic_studio_cli.py dna handoff "Character Name" \
  --output characters/{slug}/handoff.json
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py \
  characters/{slug}/handoff.json

# Sequence extend
python tools/cinematic_studio_cli.py sequence handoff "Sequence Name" --clip clip_001
# validate the written path reported by CLI

# Imagine Agent Mode Handoff
python tools/cinematic_studio_cli.py imagine agent-handoff \
  --batch hero-session --shot shot_hero_001 \
  --surface grok_build_tools --format json \
  -o artifacts/handoffs/agent_mode.json
python .grok/skills/handoff-packet-validator/scripts/validate_handoff.py \
  artifacts/handoffs/agent_mode.json
```

## Validation Engine (data-driven)

`validate_packet()` loads schema from `PACKET_TYPES` and applies:

| Rule | Behavior |
|------|----------|
| `required` | Field must be present |
| `nonempty` | Non-empty string after strip |
| `enums` | Value ∈ allowed set |
| `typed` | list / dict / list_min / object_keys / object_any_of |
| `when` | Conditional (e.g. video modes need `video_pipeline_spec` + `sound_layer`) |

Imagine Agent Mode field lists live in **`tools/handoff_schema.py`** (single source of truth) so validator and bridge cannot drift.

## Gate Policy (Studio Director)

| Result | Action |
|--------|--------|
| Valid | Proceed to downstream agent |
| Invalid identity packet | Fix DNA / re-run `dna handoff` — do not lock |
| Invalid extend packet | Fix LAST_FRAME_RECAP / momentum — do not extend |
| Invalid asset entry | Curator re-tier — do not spend hero i2v |
| Invalid intimacy state | ErosForge re-state — do not NSFW-extend |
| Invalid agent-mode | Fix surface/mode/spec — **block Imagine spend** |
| Video mode missing sound layer | Fail — force Sound Layer block |

**Never** silent-pass NSFW or video handoffs with incomplete packets.

## Failure Playbook

1. Read printed `•` issues top to bottom  
2. Fix producer (DNA / sequence / curator / Studio Director) — do not hand-edit casually unless user owns the packet  
3. Re-run generator CLI if available  
4. Validate again until exit 0  
5. Only then activate consumer agent  

## Output Format

Agent report after every CLI run (v3.8.6). Script stdout stays as-is (`✅` / `❌` / `⚠️`).

```text
HANDOFF VALIDATION · v3.8.6
File: <path>
packet_type: <type|unknown>
CLI: <exact command including flags>
Exit: 0 | 1 | 2
Result: PASS | PASS_WITH_WARNINGS | FAIL
Issues:
  - <hard issues only, or none>
Warnings:
  - <warnings only, or none>
Surface: PASS | FAIL | SKIPPED
Next: <activate consumer | fix producer | block spend>
```

| Result | Next |
|--------|------|
| PASS / PASS_WITH_WARNINGS on `identity_lock_handoff` | Identity Lock |
| PASS on `sequence_extend_handoff` | next clip / Chain QA |
| PASS on `asset_manifest_entry` | i2v / batch (tier-aware) |
| PASS on `intimacy_state_handoff` | next intimate clip only if `legal_gate` is PASS |
| PASS on `imagine_agent_mode_handoff` + Surface PASS | named `target_surface` |
| FAIL | name producer (`dna handoff` / `sequence handoff` / curator / Studio Director / ErosForge). Block Imagine spend. |

## Integration

| Partner | Relationship |
|---------|----------------|
| Character DNA Extractor | Emits `identity_lock_handoff` |
| Identity Lock Specialist | Consumes only after PASS |
| Sequence Director / Extender | Emit/consume `sequence_extend_handoff` |
| Chain QA Protocol | Continuity fields should match packet |
| Reference Asset Curator | `asset_manifest_entry` |
| Image-to-Video Specialist | Prefer locked approved assets |
| ErosForge / NSFW Sequence Extender | `intimacy_state_handoff` |
| Studio Director | Owns `imagine_agent_mode_handoff` gates |
| Imagine Execution Bridge | Classic grok.com packets (related) |
| Quality Assurance Guardian | Invalid handoff = stop before client |

## Protocol Doc

Imagine Agent Mode (surfaces, modes, required fields):  
`references/agents/IMAGINE_AGENT_MODE_HANDOFF_v3.7.1.md`

## Reasoning (Grok 4.6)

| Task | Reasoning |
|------|-----------|
| Routine re-check | medium |
| Spend/identity-gating failure | **high** |

---

*Handoff Packet Validator v3.8.6 — Grok 4.6 schema gate · data-driven PACKET_TYPES · block broken handoffs before spend*