SuperBizAgent-java/openspec/changes/archive/2026-07-17-chat-diagnosis-stategraph-routing-skeleton/specs/chat-diagnosis-stategraph-routing-skeleton/spec.md

ADDED Requirements

Requirement: Diagnosis Graph skeleton SHALL compile against the locked Graph API

The system SHALL provide an internal Diagnosis StateGraph skeleton using Graph Core 1.1.2.0 config-aware node actions, conditional edges, explicit key strategies, and a recursion limit of 32. The skeleton SHALL NOT be wired to the current production Chat path.

Scenario: Skeleton is compiled

• WHEN valid node action ports are supplied
• THEN the Graph SHALL compile with all frozen nodes and conditional edges
• AND orchestration_events SHALL use Append semantics while all other state uses Replace semantics
• AND the compiled Graph SHALL enforce recursion limit 32

Scenario: Run config is supplied

• WHEN a Fake Node Graph is invoked with a RunnableConfig.threadId
• THEN config-aware node ports SHALL receive that config
• AND the final state SHALL remain scoped to that invocation

Scenario: Production path is inspected

• WHEN stage 1 is accepted
• THEN ChatService, real Agents, Gatekeeper service, database, and Trace API SHALL NOT invoke the new skeleton

Requirement: Planner routing SHALL allow one technical retry per Planner stage

The skeleton SHALL route Planner COMPLETED to Executor. INVALID_OUTPUT and RETRYABLE_FAILED SHALL self-retry only while planner_retry_count=0; NON_RETRYABLE_FAILED, unknown status, or a second technical failure SHALL route to Fallback.

Scenario: Planner first technical failure

• WHEN Planner first returns INVALID_OUTPUT or RETRYABLE_FAILED
• THEN only Planner SHALL run again
• AND the re-entered Planner state SHALL have planner_retry_count=1

Scenario: Planner retry is exhausted

• WHEN Planner returns a technical failure after retry count reaches 1
• THEN the Graph SHALL route to Fallback
• AND Executor SHALL NOT run

Scenario: Planner fails non-retryably

• WHEN Planner returns NON_RETRYABLE_FAILED or an unknown status
• THEN the Graph SHALL route directly to Fallback

Requirement: Executor and Gatekeeper routing SHALL fail closed

Executor SHALL route only COMPLETED output to Gatekeeper and SHALL never retry. Gatekeeper SHALL route PASS and LOW_CONFID with verified bindings to Verified Input; REJECT, unknown status, or LOW_CONFID with zero bindings SHALL route to Fallback.

Scenario: Executor completes legal output

• WHEN Executor returns COMPLETED, including a legal no-evidence output or legal output after tool errors
• THEN Gatekeeper SHALL run exactly once

Scenario: Executor cannot complete contract

• WHEN Executor returns INVALID_OUTPUT, TOOL_BLOCKED, FAILED, or unknown status
• THEN the Graph SHALL route directly to Fallback
• AND Gatekeeper and Verifier SHALL NOT run

Scenario: Gatekeeper permits verification

• WHEN Gatekeeper returns PASS or LOW_CONFID with verified_binding_count>0
• THEN Verified Input SHALL run before Verifier

Scenario: Gatekeeper blocks verification

• WHEN Gatekeeper returns REJECT, unknown status, or LOW_CONFID with zero verified bindings
• THEN the Graph SHALL route to Fallback
• AND Verifier SHALL NOT run

Requirement: Verifier routing SHALL separate technical retry from evidence retry

Verifier INVALID_OUTPUT and RETRYABLE_FAILED SHALL self-retry once with the same verified input. COMPLETED PASS or REJECT SHALL route to Composer. COMPLETED LOW_CONFID SHALL route to one Evidence Retry only when all frozen guards are true; otherwise it SHALL route to Composer. Other outcomes SHALL fail closed.

Scenario: Verifier first technical failure

• WHEN Verifier first returns INVALID_OUTPUT or RETRYABLE_FAILED
• THEN only Verifier SHALL run again
• AND Gatekeeper, Executor, and tools SHALL NOT rerun

Scenario: Verifier retry is exhausted

• WHEN Verifier returns a technical failure after verifier_retry_count=1
• THEN the Graph SHALL route to Fallback

Scenario: Verifier verdict reaches Composer

• WHEN Verifier completes with effective PASS or REJECT
• THEN Composer SHALL run

Scenario: LOW_CONFID qualifies for evidence retry

• WHEN Verifier completes LOW_CONFID with ceiling PASS, valid no_evidence or indirect_support facts, and evidence_retry_count=0
• THEN Evidence Retry SHALL run once and return to a new Planner stage
• AND planner_retry_count SHALL reset to 0
• AND evidence_retry_count SHALL become 1

Scenario: LOW_CONFID does not qualify for evidence retry

• WHEN ceiling is LOW_CONFID, facts contain no valid gap, or evidence retry count is already 1
• THEN Composer SHALL run without another Planner cycle

Requirement: Composer routing SHALL allow one technical retry and then terminate safely

Composer COMPLETED SHALL terminate at END. INVALID_OUTPUT and RETRYABLE_FAILED SHALL self-retry once; NON_RETRYABLE_FAILED, unknown status, or a second technical failure SHALL route to Fallback and then END.

Scenario: Composer first technical failure

• WHEN Composer first returns INVALID_OUTPUT or RETRYABLE_FAILED
• THEN only Composer SHALL run again
• AND Verifier and preceding nodes SHALL NOT rerun

Scenario: Composer retry is exhausted

• WHEN Composer fails technically after composer_retry_count=1
• THEN Fallback SHALL run exactly once
• AND the Graph SHALL terminate

Scenario: Composer succeeds

• WHEN Composer returns COMPLETED
• THEN the Graph SHALL terminate without invoking Fallback

Requirement: Orchestration events SHALL produce an exact bounded trace

Each node attempt SHALL append one terminal orchestration event. The trace builder SHALL derive transitions from adjacent events, final node and termination reason from the last event, degraded state from Fallback termination, and evidence retry count from state.

Scenario: Normal path trace is built

• WHEN Fake nodes execute Planner, Executor, Gatekeeper, Verified Input, Verifier, and Composer
• THEN events and transitions SHALL preserve that exact order
• AND the trace SHALL terminate at Composer without degradation

Scenario: Fallback path trace is built

• WHEN a route terminates through Fallback
• THEN the trace final node SHALL be Fallback
• AND degraded SHALL be true
• AND its termination reason SHALL come from the Fallback event

Scenario: Trace input is invalid

• WHEN no events exist or an event has blank node, outcome, reason code, or attempt below 1
• THEN trace construction SHALL fail explicitly rather than fabricate a path

Scenario: Event payload is inspected

• WHEN orchestration events and trace maps are produced
• THEN they SHALL contain only routing metadata
• AND they SHALL NOT contain Prompt, model reasoning, tool output, or Graph State snapshots