Skip to content

feat(orchestration): implement Phase 2 handoff validation layer (issue #2023)#2078

Merged
bug-ops merged 4 commits intomainfrom
feat/issue-2023/research-orchestration-mast-in
Mar 21, 2026
Merged

feat(orchestration): implement Phase 2 handoff validation layer (issue #2023)#2078
bug-ops merged 4 commits intomainfrom
feat/issue-2023/research-orchestration-mast-in

Conversation

@bug-ops
Copy link
Copy Markdown
Owner

@bug-ops bug-ops commented Mar 21, 2026

Summary

Phase 2 handoff validation layer for MAST-informed multi-agent coordination hardening.

  • Implements 4 validation rules (ObjectiveNonEmpty, CriteriaPresent, HandoffRefSupported, RoleContextComplete)
  • Implements verification gate with criteria coverage evaluation
  • Wires validation into DagScheduler dispatch (hard fails block dispatch, soft warnings allow with logging)
  • Adds post-completion verification in process_event() with VerificationStatus mapping
  • Updates build_task_prompt() to use structured DependencyOutput from HandoffContext
  • Adds OrchestrationMetrics counters for validation/verification quality tracking

Validation Rules

Rule Severity Behavior
ObjectiveNonEmpty Hard blocks dispatch if objective empty
CriteriaPresent Hard blocks dispatch if no acceptance criteria
HandoffRefSupported Hard blocks dispatch if HandoffRef::ById found (Phase 1-2)
RoleContextComplete Hard blocks dispatch if role-specific required fields missing

All rules produce actionable error messages with field-paths.

Test Coverage

  • 26 unit tests in handoff.rs (validate_context, verify_output, RoleContextComplete per variant)
  • 2 scheduler integration tests (validation blocking, soft-warn path)
  • 5 new RoleContextComplete fail-case tests (Tester, Critic, Reviewer)
  • Total: 6312 tests (+26 vs Phase 1)

Commits

Validators (Approved)

  • Architect: approved
  • Critic: approved (kept RoleContext enum, dropped YAML schemas per critique)
  • Developer: 6312 tests passing, 0 warnings
  • Tester: full coverage, 3 critical gaps fixed
  • Perf: OK
  • Security: OK (2 Low WARNs for Phase 3)
  • Code reviewer: APPROVED FOR MERGE

Known Limitation

OrchestrationMetrics.handoff_validation_pass/fail and handoff_verification_pass/fail are defined but not wired from DagScheduler.handoff_metrics(). Phase 3 follow-up to bridge metrics into TUI dashboard.

Closes #2023

bug-ops added 3 commits March 21, 2026 01:28
…#2023)

- validate_context() evaluates 4 rules (ObjectiveNonEmpty, CriteriaPresent,
  HandoffRefSupported, RoleContextComplete) covering all 6 RoleContext variants;
  hard violations block dispatch, soft violations log warnings
- verify_output() checks criteria coverage and Fail status, returns ValidationResult list;
  derive_verification_status() converts to VerificationStatus enum
- DagScheduler::tick(): blocks dispatch on hard validation failures (task -> Failed +
  failure propagation), logs soft warnings, tracks per-rule violation counts in
  HandoffMetrics
- DagScheduler::process_event(): runs verify_output() post-completion, updates
  HandoffMetrics (total_dispatched, clean/warned/blocked dispatches,
  verified/partial/failed/unverified completions, role_counts, rule_violations)
- build_task_prompt(): uses structured DependencyOutput summaries from handoff_context
  when available, falls back to raw result injection
- OrchestrationMetrics: 4 new handoff quality counters for TUI
  (handoff_validation_pass/fail, handoff_verification_pass/fail)
- 26 new unit tests (6290 total, +26 vs Phase 1)
Resolves CHANGELOG.md conflict by keeping both entries.
No code conflicts — changes are in disjoint crates.
…ssue #2023)

- handoff.rs: 3 RoleContextComplete hard-fail tests for Tester (empty test_plan),
  Critic (empty review_dimensions), Reviewer (empty artifact_refs)
- scheduler.rs: integration test for hard-fail blocking dispatch — verifies no
  Spawn produced, task.status=Failed, blocked_dispatches=1,
  rule_violations["ObjectiveNonEmpty"]=1
- scheduler.rs: integration test for soft-warn path — verifies Spawn proceeds,
  warned_dispatches=1, blocked_dispatches=0

6312 tests total (+5 vs previous commit)
@github-actions github-actions bot added documentation Improvements or additions to documentation rust Rust code changes core zeph-core crate enhancement New feature or request size/XL Extra large PR (500+ lines) labels Mar 21, 2026
@bug-ops bug-ops enabled auto-merge (squash) March 21, 2026 00:46
@bug-ops bug-ops merged commit 80a044f into main Mar 21, 2026
25 checks passed
@bug-ops bug-ops deleted the feat/issue-2023/research-orchestration-mast-in branch March 21, 2026 01:00
bug-ops added a commit that referenced this pull request Mar 21, 2026
, #2078)

The typed HandoffContext enum, RoleContext variants, and validation layer
introduced in #2076 and #2078 are superseded by the rust-agent-handoff
skill. Agents follow the handoff protocol via skill instructions injected
into their system prompt — no compile-time struct enforcement is needed.

Reverts:
- handoff.rs (deleted)
- typed HandoffConfig in zeph-config
- handoff fields in TaskResult/TaskNode
- handoff validation metrics in OrchestrationMetrics
- scheduler.rs validation/verification wiring

Closes #2023
bug-ops added a commit that referenced this pull request Mar 21, 2026
, #2078) (#2082)

The typed HandoffContext enum, RoleContext variants, and validation layer
introduced in #2076 and #2078 are superseded by the rust-agent-handoff
skill. Agents follow the handoff protocol via skill instructions injected
into their system prompt — no compile-time struct enforcement is needed.

Reverts:
- handoff.rs (deleted)
- typed HandoffConfig in zeph-config
- handoff fields in TaskResult/TaskNode
- handoff validation metrics in OrchestrationMetrics
- scheduler.rs validation/verification wiring

Closes #2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core zeph-core crate documentation Improvements or additions to documentation enhancement New feature or request rust Rust code changes size/XL Extra large PR (500+ lines)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

research(orchestration): MAST-informed handoff hardening to reduce multi-agent coordination failures

1 participant