Draft: External Task Context refinement consumer proof

[stpku]

Stack relationship

This PR is stacked on feat/task-context-temporal-refinement-v0.1 / PR #26. It was temporarily retargeted to main for combined exact-head CI and has now been restored to the stacked base.

Goal

Test whether an external caller can close a refinable Task Context gap using the existing public objects and fields, without adding a new Core ContextGap / RefinementRequest schema.

The completed proof is recorded in docs/reference/task-context-refinement-consumer-plan-v0.1.md.

Contract under test

The external consumer retains:

TaskFrame
ContextRequirement[]
selected ContextCandidate[]

It consumes:

TaskContext.gap_requirement_ids
TaskContext.refinement_requirement_ids

For each refinable requirement it resolves the original structured ContextRequirement, calls an external provider, receives new ContextCandidate[], and calls assess_task_context() again.

The consumer lives under examples/, not src/geotask_core.

Proof results

Successful closure

initial status                   insufficient
initial refinement ids           obstacles
provider calls                   1
provider requirement             obstacles
false acquisition calls          0
final status                     sufficient_with_gaps
final critical gaps              0
final refinement ids             0
optional poi_labels gap          preserved
final declared cost              6 credits

The original coarse obstacle acquisition remains in the cost ledger; refinement does not erase sunk context-preparation cost.

Counterexamples

• Provider returns 50 m for a <=10 m requirement -> Core remains insufficient; refinement signal is preserved.
• Critical airspace evidence is missing -> provider still receives only obstacles; unrelated missing gap remains and final context stays insufficient.
• A valid 5 m obstacle candidate is already present -> refinement ids empty and provider call count remains zero.
• Consumer final result equals direct assess_task_context() over the identical final candidate set -> no second sufficiency algorithm exists in the adapter.

Measures

Refinable Critical Gap Closure       PASS
False Acquisition Count             0
Unresolved Refinement Preservation  PASS
Reassessment Parity                 PASS
Sunk Cost Preservation              PASS
Provider Call Count                 1 for 1 refinable requirement
Core Code Delta                     0
Core Public Schema Delta            0

Schema Promotion verdict

ContextGap / RefinementRequest public schema promotion remains HOLD.

At the tested synchronous/caller-retained boundary, the existing TaskFrame, ContextRequirement[], TaskContext gap/refinement ids, ContextCandidate, and assess_task_context() are sufficient for the full acquire -> reassess loop.

A new contract must be justified by a concrete interoperability failure, not by architectural aesthetics.

Important applicability boundary

This proof assumes the external consumer retains the original:

TaskFrame
ContextRequirement[]
TaskContext

It does not prove that a bare persisted TaskContext ids-only artifact is sufficient for an asynchronous worker that no longer has the original requirement objects.

That is the next legitimate contract test only if a real Harness / AgentReality / Lowa async handoff requires it.

Exact-head validation

Implementation head 917053e614ff68d40b33269650169d26da8325b3 passed combined main CI #226.

Final documentation head ae65ed20a47d38ef9cd25e7f588d475625bec720 passed combined main CI #227:

Python 3.10 pytest + RC attestation     PASS
Python 3.11 pytest + RC attestation     PASS
Python 3.12 pytest + RC attestation     PASS
Python 3.13 pytest + RC attestation     PASS
artifact roundtrip                      PASS
public boundary                         PASS
build / twine                           PASS
provider-neutral Adapter build          PASS
OpenAI Adapter build + smoke            PASS
public scan                             PASS
RC build / Reference Agent evidence     PASS
RC evidence merge / readiness audit     PASS
workflow                                completed / success

Ownership boundary

Actual DeepSeek Harness / AgentReality adaptation belongs in the AgentReality extension layer, not GeoTask Core.

GeoTask exposes task-context semantics and deterministic reassessment; it does not become an Agent scheduler, provider job runtime, or second Harness.

Next engineering gate

Stop expanding GeoTask benchmarks and schemas.

The next high-value proof belongs to AgentReality / Harness integration: preserve or bind the original TaskFrame/requirements across a real AgentRun, consume GeoTask insufficiency/refinement, invoke a provider/tool through the Harness, and call GeoTask reassessment.

Only if that real asynchronous/component handoff cannot preserve or re-resolve the original requirements should a structured ContextGap / RefinementRequest be reconsidered.