Soul automatic: self-correcting lineage, all-ready routing, and fail-closed release - #55

Scope

Upgrades Soul / Research Orchestrator into an automatic, revision-preserving control plane while keeping target-domain authority in the claim-native modules.

Automatic reframing and graph revision

• a new frame automatically supersedes an unresolved active task instead of overwriting or deadlocking it
• every predecessor remains immutable, inactive, unreleased, and bidirectionally bound to its successor
• callers may operate through an old task ID; Soul resolves the complete validated successor chain
• adding an obligation to a frozen open task creates and freezes a successor graph revision
• concurrent post-freeze discoveries preserve every obligation rather than losing an update
• predecessor receipts cannot clear a successor revision
• an empty task remains UNKNOWN; Soul does not fabricate assurance work to make absence look complete

Automatic routing

• production default is AUTOMATIC_ALL_READY
• every unresolved, dependency-ready obligation is selected by default
• explicit budgeted mode is experimental and uses deterministic skip-ahead so one expensive candidate does not suppress later feasible work
• unavailable modules and unresolved dependencies produce typed stall frontiers
• same-module work may share a transport envelope, but semantic subrequests remain isolated unless the caller explicitly opts into one shared-context group
• route output exposes a bounded machine-readable manifest and never authorizes execution by itself
• route certificates bind the requested task ID, resolved revision, full supersession chain, frozen obligation set, evidence snapshot, challenge state, policy, selection, exclusions, and batches

Evidence and release hardening

• current receipt precedence uses monotonic store sequence numbers; timestamps are diagnostic fallback only
• challenge state is composed in OFF / SHADOW / ENFORCED modes with current task, graph, module, candidate, and scope bindings
• evidence version, receipt hashes, challenge/resolution hashes, and release seals are bound into release
• release uses a cooperative task/evidence compare-and-swap under task and evidence locks
• duplicate IDs and supported post-release evidence mutations are rejected
• release is idempotent and Soul writes no target-domain receipt
• unresolved automatic work receives an ASSURANCE_ONLY diagnostic receipt without treating assurance as a substitute for missing domain evidence

Control-plane and host-loop hardening

• caller metadata attempting to set soul_*, release, task identity, active-state, raw-prompt, or content-hash fields is rejected before persistence
• ordinary caller metadata remains available
• contradictory or missing lineage state fails closed
• authority drift is recorded and reconciled, but the same call cannot release against newly adopted authority; a fresh retry is required
• the Stop hook blocks on unresolved work and also fails closed if the orchestrator itself is unavailable
• persisted error telemetry records only bounded error type data, never exception text or raw prompts
• external reviewer/model output remains ADVISORY_ONLY; it has no task, routing, policy, evidence, or release authority without a host-adopted versioned change

Changed paths

The branch includes the automatic Soul controller, public compatibility surfaces, runtime/store hardening, host-hook integration, tests, engineering specifications, validation changes, and the external-review authority boundary.

The final validation repair preserves the exact implementation-inventory gate and accounts for the added tools/soul_session.py control surface: 47 top-level Python tool files.

Validation

Exact branch head: 60121b073cd98151b5fbfe88794ed830b09b7f73

Exact source tree: 6a5c75662fb931c06a271bc4bc52206264f957e5

GitHub PR merge ref tested: 591822dd7b3898e76cbda45b25415748dd66062e

Validation on the current PR merge ref:

• focused Soul planner/control tests: 31 passed
• complete repository suite: 578 passed
• Research Orchestrator + Process Assurance public invariants: PASS
• vNext typed-runtime validator: PASS (47/47)
• public showcase validator: PASS (33/33)
• Ruff lint and Python compilation: PASS
• Research software validation run 33234661831: PASS
• Runtime portability run 33234661771: PASS
• Security gates run 33234661767: PASS
• CodeQL run 33234661798: PASS

Stacked validation rule

This work conceptually depends on the automatic Gauntlet layer. Any change to the effective Gauntlet base, shared runtime/store code, release contract, or implementation inventory makes the validation above stale and requires the full suite to be rerun on the resulting tree.

Evidence boundary

Mechanical validation establishes represented task lineage, graph revision, routing, liveness, binding, locking, host-hook behavior, release consistency, public inventory consistency, and the checked portability/security/static-analysis properties. It does not establish complete real-world obligation discovery, global scheduling optimality, harmless shared context, lower production cost, higher benchmark scores, or better scientific outcomes. Those remain prospective matched-evaluation questions.