refactor(harness): freeze single-agent contracts
This commit is contained in:
zhuyongxin
@@ -0,0 +1,78 @@
|
||||
# single-react-diagnosis-harness Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change single-react-design-freeze. Update Purpose after archive.
|
||||
## 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
|
||||
Reference in New Issue
Block a user