Reconcile required missing SDK entrypoints with the documented scan input-error contract

[pengfei-threemoonslab]

Problem

The documented scan error contract says a missing required tool_sources[].path is InputParseError(3), while the OpenAI Agents SDK loader returns a warning even when optional: false. An integration that uses execution status to distinguish bad input from a completed advisory scan receives a different shape depending on the source reader.

Evidence

Found while validating #561 against main c079864e8a37209a7712d74197fd1cf1b4ebf06e. A manifest with an explicit purpose and tool_sources: [{id: sdk, type: openai_agents_sdk, path: agent.py, optional: false}], with no agent.py, completes agents-shipgate scan -c shipgate.yaml with advisory exit 0, a source warning OpenAI Agents SDK entrypoint not found: .../agent.py, and release_decision.decision: insufficient_evidence.

inputs/openai_sdk_static.py::load_openai_sdk_static_tools returns LoadedToolSource(warnings=[...]) on not path.exists() without consulting optional. The required-path resolver in cli/scan/validation.py is called by doctor/inspect; the scan orchestration does not use it as a common precondition. #561 adds an explanation to the existing warning and preserves its release/exit behavior.

This reproduction is a documented execution-contract mismatch, not a reproduced unsafe auto-pass: the release decision still abstains. Do not interpret advisory exit 0 as merge authority.

Scope

Decide and implement one supported contract for required source availability before adapter dispatch, preserving containment checks and optional-source warning behavior. Audit the existing reader-specific exceptions before changing shared behavior. If there is an intentional SDK exception, describe it explicitly in the error catalog and instructions instead of promising universal exit 3. Missing input must never be repaired by inventing a binding or authority declaration.

Acceptance

• Public scan, doctor JSON/human output and verify agree on the documented required/optional availability boundary.
• A missing required SDK entrypoint has a tested structured result and the exact missing source path; optional behavior remains explicit.
• CLI/module invocation, advisory/strict mode and other existing adapter behavior have regression coverage.
• Error catalog, docs and protected agent instructions agree with the chosen implementation. Release/merge authority cannot be inferred from advisory exit 0.

Sequencing

Deferred from #561; related #547/#543 recovery clarity. Keep #561's explanation-only change separate from this execution-contract decision. Protected instruction edits follow the repository's preflight and human-review boundary.