feat: add structured handoff governance

Author: Nefza99

GOVERNANCE.md

@@ -22,6 +22,8 @@ Apply multiplicative penalties for:
 - Agreement cannot materially increase confidence unless independence is demonstrated.
 - High-impact synthesis fails if provenance is incomplete.
 - Domain reliability is scoped by capability area, not global reputation.
+- Handoff acceptance depends on objective, constraint, provenance, and next-action fidelity, not just transport success.
+- Boundary-local repair is preferred over full reruns when a corrupted handoff can be repaired deterministically.
 
 ## Pass Condition
 
@@ -32,6 +34,7 @@ A high-impact claim reaches synthesis only when:
 - required review and counterparty outputs exist
 - blocking dissent is resolved or escalated
 - independent evidence threshold is satisfied
+- the inherited task-state is usable without re-deriving missing context inside the next agent
 
 ## Fail Condition
 

HANDOFF_CONTRACTS.md

@@ -1,38 +1,104 @@
 # HANDOFF_CONTRACTS
 
-Rebis handoffs are explicit contracts, not lossy summaries.
+Rebis handoffs are explicit governed contracts, not lossy natural-language summaries.
 
-## Required Fields
+The runtime now represents those contracts as a compact `Handoff State Packet (HSP)` so downstream agents, tools, and merge runtimes inherit validated task-state instead of spending compute re-deriving intent from prose.
 
-- objective
-- knownInputs
-- assumptions
-- constraints
-- openQuestions
-- acceptanceCriteria
-- requiredEvidenceThreshold
-- failureConditions
-- escalationConditions
+## Handoff State Packet
+
+Required fields:
+- `run_id`
+- `handoff_id`
+- `source_step_id`
+- `source_agent_id`
+- `target_agent_id`
+- `target_tool_id`
+- `original_objective`
+- `current_subgoal`
+- `hard_constraints`
+- `active_assumptions`
+- `evidence_refs`
+- `provenance_refs`
+- `completed_work`
+- `remaining_work`
+- `expected_next_action`
+- `risk_flags`
+- `uncertainty_flags`
+- `confidence_score`
+- `checkpoint_status`
+- `checkpoint_reasons`
+- `repair_instructions`
+- `created_at`
+
+These fields are intentionally compact:
+- objective identity survives the boundary
+- constraints and assumptions stay machine-comparable
+- provenance stays attached through ids and refs
+- repair can target one corrupted field without rewriting the entire chain
 
 ## Validation Rules
 
+The handoff validator checks:
+- `objective_fidelity`
+- `subgoal_fidelity`
+- `constraint_fidelity`
+- `assumption_consistency`
+- `provenance_fidelity`
+- `completion_integrity`
+- `next_action_integrity`
+- `drift_risk_score`
+
 A handoff fails if:
-- objective is missing
-- known inputs are empty
-- assumptions are dropped
-- open questions are omitted
-- acceptance criteria are missing
-- evidence threshold is undefined
+- the original objective is missing or mutated
+- the active subgoal no longer matches the inherited task state
+- hard constraints are omitted or changed
+- assumptions contradict prior state or each other
+- evidence or provenance is detached where it is required
+- completed work no longer matches the lineage being handed forward
+- the next action is ambiguous, missing, or off-objective
+
+Validation outcomes:
+- `PASS`
+- `REVISE`
+- `HALT`
+- `ESCALATE`
+
+`REVISE` means repair the smallest broken field only.
+
+## Minimal Repair
+
+Rebis treats many handoff failures as boundary-local repair problems, not full-rerun problems.
+
+Examples:
+- missing hard constraint -> restore that constraint only
+- detached evidence -> attach the missing evidence refs only
+- ambiguous next action -> rewrite only `expected_next_action`
+- missing remaining work -> rebuild only `remaining_work`
+
+The purpose is to preserve valid prior work and reduce wasted recovery compute.
 
 ## Pass Condition
 
 A receiving agent/module can reconstruct:
 - what must be done
-- what is known
+- what has already been completed
 - what is still uncertain
-- what counts as success
-- when to fail or escalate
+- what evidence supports the current state
+- what counts as a valid next action
+- when to revise, halt, or escalate
 
 ## Fail Condition
 
-If a handoff drops assumptions or open questions, the system must reject or reopen the transfer.
+If a handoff drops assumptions, provenance, or key open risks, the system must reject, repair, or reopen the transfer instead of silently accepting it.
+
+If only one recoverable field is corrupted, the system should patch that field and preserve the rest of the lineage rather than rerunning the full workflow.
+
+## Replayability
+
+Every HSP should remain:
+- serializable to JSON
+- replayable from logs
+- linked to source and target steps
+- inspectable during incident review
+
+That replayable boundary lineage is part of how Rebis keeps long-horizon workflows inspectable after the fact.

OBSERVABILITY.md

@@ -8,6 +8,7 @@ Each significant process should capture:
 - objective at start
 - assumptions
 - participating roles/modules
+- transition packets and handoff packets
 - evidence timeline
 - confidence transitions
 - policy checks triggered
@@ -30,6 +31,7 @@ Triggered for:
 
 - replayable trace fingerprint
 - failure origin stage
+- failure origin handoff or transition packet when applicable
 - structured cause classes
 - lessons learned
 - suggested threshold or rule updates
@@ -39,3 +41,4 @@ Triggered for:
 - Decision traces are replayable.
 - Review can identify where drift or governance failure began.
 - Incident review produces update suggestions, not just blame labels.
+- Handoff lineage is inspectable without reconstructing context from freeform narrative summaries.

PROVENANCE.md

@@ -8,13 +8,16 @@ Every Rebis decision node must remain replayable and reopenable.
 - assignedRoles
 - skillsUsed
 - evidenceSources
+- evidence_refs
+- provenance_refs
 - dissentRecords
 - finalConfidence
 - assumptions
 - openQuestions
 - acceptanceCriteria
 - reopenConditions
 - timestamp and version lineage
+- packet_hash or lineage fingerprint where available
 
 ## Reopenability
 
@@ -31,6 +34,7 @@ Minimum reopen logic:
 The provenance record is paired with a decision-trajectory trace:
 - objective at start
 - evidence timeline
+- handoff packet lineage
 - confidence transitions
 - policy checks triggered
 - dissent and objections
@@ -45,3 +49,4 @@ The provenance record is paired with a decision-trajectory trace:
 - Reopen conditions are mandatory.
 - Provenance can be replayed after the fact.
 - Incident review can identify where failure began.
+- Boundary corruption can be traced to the specific handoff packet where task-state fidelity was lost.