orchestrate: split the `invalid` envelope verdict — an off-schema envelope from a completed agent FAILs a slice whose work is correct

[rodrigorjsf]

Found during orchestrate run prd352-20260803-015333 (PRD #352, 12 slices, all passed).

Symptom

The implementer on slice #364 finished its work correctly — eight files changed, +6 tests, all capability verbs run — then emitted an envelope that validate_envelope rejected with SCHEMA_MISMATCH. Four fields were wrong in shape, not content:

Field	Emitted	Schema requires
role	null	the literal "implementer"
filesChanged	null	array of path strings
verification	object keyed by capability	array of {capability, result}
notes	array of strings	a single string

Notably the content was richer than the schema allows — the agent put the tool's exitCode and prose evidence inline where an enum belongs, and split notes into a list because it had several distinct points. These are the mistakes of an agent reasoning about what would be useful, not one that ran out of room.

Why the current rule is too blunt

The failure taxonomy collapses "truncated" and "off-schema" into one invalid verdict, and both FAIL the slice. But they are different failures with different risk profiles:

• A truncated envelope means the agent's turn was cut off, so its self-report is genuinely untrustworthy and the FAIL is right.
• An off-schema envelope from an agent that ran to completion means the report is mis-formatted while the underlying work — which lives in the worktree, and which verify_changeset, the reviewer, and the orchestrator's own pre-merge gate all inspect independently — is unaffected.

FAILing the second case discards a completed implementation over a JSON shape error.

Workaround used

A once-only re-emission request via SendMessage to the still-resident subagent, spelling out the four field corrections and the exact target shape.

No verification was bypassed: verify_changeset, the reviewer pass, and the orchestrator's independent run_build + run_tests gate all still ran afterwards. Precedent: the same recovery shape already worked for a turn-budget cutoff on an earlier run.

Suggested fixes

• Split the invalid verdict into invalid-truncated (fence unclosed / JSON unparseable → FAIL, as today) and invalid-schema (parses cleanly but does not match → sanction one re-emission request to the same agent before FAILing). The discriminator is cheap and deterministic: does the fenced block parse as JSON at all?
• Put the literal envelope schema in each subagent definition's own prompt rather than relying on the agent to recall it. Three of the four errors here (verification shape, notes cardinality, role literal) are exactly what an agent gets wrong when writing from memory. (See the companion issue on schema introspection — adopting this fix naively at the orchestrator level introduced its own failure.)
• Have validate_envelope return the offending field paths in a machine-usable list, not only a prose errorMessage, so an orchestrator can compose the correction request automatically.

Relationship to existing issues (read before deduping)

• Not orchestrate: bound the bundled investigator-standard (haiku) exploration so it emits its envelope before truncating #346. orchestrate: bound the bundled investigator-standard (haiku) exploration so it emits its envelope before truncating #346 is the truncated case (haiku investigator over-explores, turn ends before the envelope). This issue is the opposite: the agent ran to completion and emitted a complete, well-formed, parseable block that simply does not match the schema. orchestrate: bound the bundled investigator-standard (haiku) exploration so it emits its envelope before truncating #346's fix (exploration budget + envelope-first) does nothing for a schema-shape error.
• Not orchestrate: recover a missing-envelope implementer whose worktree holds near-complete work (extend continue-in-place beyond incomplete) #267 / orchestrate: distinguish a transient (API/socket) subagent crash from a genuine missing-envelope FAILED slice #334. Both concern a missing envelope (hard cut, transient crash). Here the envelope exists and parses.
• Not orchestrate: implementer/reviewer subagents assert a non-existent "advisor pass" in result envelopes (false provenance, ADR-0009) #285 (fabricated advisor provenance) — that is about false content in a schema-valid envelope; this is valid content in an invalid shape.

Environment

orchestrate 1.6.0 (plugins/orchestrate/.claude-plugin/plugin.json:3 on development) plus the PRD #352 umbrella branch (slice-executor delegation layer). Run prd352-20260803-015333; slice #364, implementer role.