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

ADDED Requirements

Requirement: StateGraph design baseline SHALL be versioned and authoritative

The project SHALL maintain an archived ISS-011 design baseline that defines Graph State, routing, retry limits, fallback classes, audit boundaries, migration stages, and test replacement scope without claiming runtime cutover is complete.

Scenario: Later stage starts implementation

• WHEN an ISS-011 stage 1–5 OpenSpec change is proposed
• THEN its context and design SHALL reference the archived stage 0 baseline
• AND any intentional deviation SHALL be resolved through that stage's OpenSpec before implementation

Scenario: Stage zero is accepted

• WHEN the design-freeze change is archived
• THEN no Java, SQL, Prompt, configuration, or runtime behavior SHALL have been changed by this change
• AND runtime specs SHALL NOT claim StateGraph cutover is already implemented

Requirement: Graph State design SHALL use explicit bounded control state

Every cross-node field SHALL have one purpose, owner, and update strategy. Fields SHALL use Replace semantics except bounded orchestration_events, which SHALL use Append.

Scenario: Node state is designed

• WHEN an Agent or Java Node reads or writes parent Graph State
• THEN its allowed input projection and output fields SHALL be explicit
• AND Prompt text, model reasoning, complete tool output, and complete State snapshots SHALL NOT be control state

Scenario: Orchestration event is designed

• WHEN a node attempt reaches a handled terminal outcome
• THEN at most one event SHALL be appended for that attempt
• AND it SHALL contain only stable node, outcome, reason code, and attempt data

Requirement: Routing design SHALL be complete and terminating

Every Planner, Executor, Gatekeeper, Verifier, Composer, evidence-retry, and Fallback outcome SHALL map to one next node or terminal result. Every loop SHALL have an explicit business limit and the Graph SHALL use a recursion limit.

Scenario: Technical retry is eligible

• WHEN Planner, Verifier, or Composer first returns INVALID_OUTPUT or RETRYABLE_FAILED with the same allowed input
• THEN only that node SHALL be retried once
• AND no preceding Agent, Gatekeeper, or tool SHALL be rerun

Scenario: Technical retry is exhausted

• WHEN Planner, Verifier, or Composer returns NON_RETRYABLE_FAILED or exhausts its retry
• THEN the route SHALL terminate through the defined safe Fallback
• AND no unbounded loop SHALL remain

Scenario: Executor cannot produce a legal contract

• WHEN Executor returns INVALID_OUTPUT, TOOL_BLOCKED, or FAILED without legal executor_evidence_v2
• THEN the route SHALL go directly to pre-verification Fallback
• AND Executor SHALL NOT be retried

Scenario: Evidence retry is eligible

• WHEN effective verdict is LOW_CONFID, it was not caused by Gatekeeper ceiling, valid evidence gaps exist, and the Run has not retried evidence
• THEN one EVIDENCE_GAP_ONLY retry SHALL return to a new Planner stage
• AND technical retry counters SHALL remain independent from evidence retry count

Requirement: Verified evidence and fallback boundaries SHALL fail closed

PASS and eligible LOW_CONFID Gatekeeper outcomes SHALL pass through a verified-input builder. Verifier SHALL receive only claims and evidence projected from passed checked bindings, not complete tool_trace_summary or unverified Executor text.

Scenario: Gatekeeper result is unsafe or unknown

• WHEN Gatekeeper returns REJECT, unknown, or LOW_CONFID with zero verified bindings
• THEN the route SHALL enter pre-verification Fallback without Verifier
• AND the final answer SHALL NOT contain any Executor claim

Scenario: Gatekeeper permits verification

• WHEN Gatekeeper returns PASS or eligible LOW_CONFID
• THEN the builder SHALL project evidence only from passed bindings
• AND a LOW_CONFID ceiling SHALL NOT be upgraded to PASS

Scenario: Composer fails after verification

• WHEN Composer exhausts retry after receiving Verifier-allowed material
• THEN deterministic fallback MAY use only that allowed material
• AND it SHALL NOT read raw Executor or tool output

Requirement: Orchestration audit design SHALL preserve Run ownership

Orchestration audit SHALL remain separate from self evaluation, AgentStep, ToolInvocation, and Graph checkpoint data. A compact summary SHALL be derived from bounded events and persisted only to the current Run.

Scenario: A safe response is produced

• WHEN Graph reaches Composer or handled Fallback and produces a safe answer
• THEN Run status SHALL be SUCCESS
• AND degradation SHALL be represented by verdict or orchestrationTrace.degraded

Scenario: Trace is exposed

• WHEN an exact new StateGraph Chat Run is queried
• THEN parsed audit SHALL appear only at run.orchestrationTrace
• AND it SHALL NOT be duplicated at top level, session projection, or raw field

Scenario: Audit ownership is evaluated

• WHEN events or summaries are persisted
• THEN runId SHALL be the ownership and Graph thread boundary
• AND no data SHALL include Prompt, reasoning, complete tool output, or another Run

Requirement: Test migration design SHALL preserve safety behavior

The baseline SHALL identify Sequential/Hook implementation tests to replace and public/security contract tests to retain or extend. Fixed Agent call order SHALL NOT remain a correctness criterion.

Scenario: Old tests are replaced

• WHEN StateGraph tests become authoritative
• THEN ChatServiceSequentialAgentTest SHALL be replaced by route, node-contract, and Chat integration coverage
• AND VerifierInputHookTest SHALL be removed or rewritten for explicit nodes

Scenario: Safety tests are retained

• WHEN the new suite is assembled
• THEN Gatekeeper, Controller, Run/Trace, Repository, Composer, no-evidence, REJECT, and Eval safety contracts SHALL remain covered
• AND fixed-order-only assertions SHALL be removed