SuperBizAgent-java/openspec/changes/archive/2026-07-21-single-react-design-freeze/specs/single-react-diagnosis-harness/spec.md

ADDED Requirements

Requirement: Design contracts SHALL separate deterministic control from diagnosis reasoning

The frozen contract set SHALL define Diagnosis Agent as the only diagnosis report author, Harness as deterministic execution control, EvidenceGuard as deterministic evidence validation, and SemanticGuard as an isolated single-turn semantic reviewer.

Scenario: Contract ownership is inspected

• WHEN a later phase reads the stage-zero contracts
• THEN no Harness contract assigns Planner, Executor, Composer, workflow routing, or diagnosis reasoning responsibilities to Harness

Requirement: Tool invocation identity SHALL use the framework Tool Call ID

The contract SHALL use the framework-provided tool_call_id as the sole Tool invocation reference and SHALL require later Harness implementations to reject missing, invalid, or duplicate IDs within a Run.

Scenario: Duplicate Tool Call ID is proposed

• WHEN two Tool actions in one Run present the same framework Tool Call ID
• THEN the contract classifies the second action as an error and prohibits overwriting the first canonical invocation

Requirement: Invocation status and evidence status SHALL be independent

The contract SHALL define PROJECTING/READY/ERROR as invocation lifecycle states and EVIDENCE_FOUND/NO_EVIDENCE/ERROR as evidence result states.

Scenario: Successful query returns no evidence

• WHEN a Tool executes successfully and its bounded projection contains zero matching evidence
• THEN invocation status is READY and evidence status is NO_EVIDENCE

Scenario: No-evidence result is cited

• WHEN a Diagnosis Draft cites a NO_EVIDENCE Tool result
• THEN the Analysis kind MUST be NEGATIVE_OBSERVATION and MUST remain bounded to the Tool query scope

Requirement: Diagnosis Draft SHALL expose typed report structure

The contract SHALL define conclusion, analysis items, action plan, recommendations, limitations and Tool Call bindings without exposing chain-of-thought or raw Tool payloads.

Scenario: Draft contains an analysis item

• WHEN the Diagnosis Agent emits a structured Draft
• THEN every Analysis has a unique analysis ID, a fixed Analysis kind and at least one Tool Call ID

Requirement: Knowledge answers SHALL use exact RAG bindings

The KNOWLEDGE_QUERY contract SHALL represent the answer as bounded answer items whose references identify the single lookup Tool Call and returned document IDs.

Scenario: Knowledge answer cites an unknown document

• WHEN an answer item references a document ID absent from the bounded lookup result
• THEN later Harness validation rejects the answer instead of publishing the fabricated citation

Requirement: Safe fallback SHALL use a fixed schema

The contract SHALL define stable fallback types for evidence validation failure, semantic unsupported and semantic unavailable outcomes, and SHALL exclude unvalidated Draft content and internal errors.

Scenario: Evidence validation fails twice

• WHEN initial validation and the single no-Tool structural repair both fail
• THEN the fallback type is EVIDENCE_VALIDATION_FAILED and verified sources are empty

Requirement: Previous turn SHALL come from a safe durable Run result

The contract SHALL define diagnosis_run as the durable source of intent, release outcome and safe published result, and SHALL exclude fallback, failed and cancelled Runs from Diagnosis previous-turn selection.

Scenario: Latest Run is a fallback

• WHEN the latest same-session Run ended with FALLBACK
• THEN it is not used as Diagnosis previous turn and selection continues to the latest eligible DIAGNOSIS + SUCCESS Run

Requirement: Cancellation SHALL be layered and observable

The contract SHALL distinguish cancellation request, prevention of new work, framework interruption, cancellable Tool work and HTTP timeout for already-blocking synchronous model calls.

Scenario: Client disconnects during a model call

• WHEN an SSE client disconnects while a synchronous model call is in flight
• THEN the system prevents later Draft release, requests interruption, records an internal cancelled terminal state and discards any late model result

Requirement: Retry attempts SHALL be owned by Harness

The contract SHALL require underlying SDK, HTTP and database retry layers to execute one attempt, while Harness explicitly owns any allowed Router or SemanticGuard retry.

Scenario: SemanticGuard returns an invalid schema

• WHEN the first SemanticGuard attempt returns an invalid structured result
• THEN Harness may execute one second attempt with the same verified snapshot and records both attempts

Requirement: Phase gates SHALL remain serial

The implementation plan SHALL contain eleven independent OpenSpec changes and SHALL prohibit starting a change before its predecessor is archived and committed.

Scenario: Stage 4 completes internal Agent tests

• WHEN stage 4 passes its focused tests but stage 5 Guards are not implemented
• THEN the public Chat entry remains on the old path and stage 6B cutover is prohibited