SuperBizAgent-java/openspec/changes/archive/2026-07-20-chat-diagnosis-stategraph-cleanup-docs/specs/chat-diagnosis-stategraph-cleanup-docs/spec.md

ADDED Requirements

Requirement: Legacy implicit verifier orchestration SHALL be removed

The final StateGraph implementation SHALL have no production or test definition, import, instantiation, or executable type dependency for the legacy Verifier Hook, its ThreadLocal context, or its dedicated full-trace summary producer. Negative contract tests MAY retain identifier strings solely to prevent regression.

Scenario: Legacy source inventory is inspected

• WHEN stage 5 cleanup completes
• THEN VerifierInputHook, VerifierContextHolder, and ToolTraceSummaryService source files SHALL NOT exist
• AND no production or test source SHALL import, instantiate, extend, or type-reference those types
• AND identifier string literals SHALL only be allowed in negative source/Prompt contract assertions

Scenario: Graph safety contracts are rerun

• WHEN the legacy closure is removed
• THEN Executor parser, Gatekeeper service/node, Verified Input, Verifier, Composer, Fallback, Trace, and Chat integration tests SHALL pass
• AND Maven test compilation and live Spring startup SHALL succeed without the removed beans

Requirement: Current documentation SHALL describe the real StateGraph architecture

Current architecture, eval, and demo documentation SHALL describe complex Chat as explicit bounded Diagnosis StateGraph orchestration with run-owned events and verified-only Verifier input.

Scenario: Current docs are inspected

• WHEN a maintainer follows the architecture index and active eval/demo guides
• THEN Chat orchestration SHALL be described as conditional StateGraph Nodes rather than SequentialAgent or Hook Gatekeeper
• AND Verifier input SHALL use verified Executor projection/evidence rather than full tool trace
• AND run.orchestrationTrace SHALL be documented separately from self-evaluation and detailed Agent/tool Trace

Scenario: Historical docs are inspected

• WHEN a maintainer reads archived issues, design notes, or legacy fixtures
• THEN those materials MAY retain their original Hook/full-trace terminology
• AND they SHALL NOT be indexed as the current implementation truth

Requirement: Final deterministic regression SHALL remain green

The project SHALL run the authoritative Graph suite, retained public/security contracts, Maven test compilation, and fixed diagnosis eval baseline before live acceptance.

Scenario: Final automated gates run

• WHEN stage 5 implementation and documentation are complete
• THEN Workflow, Node Contract, Chat Integration, Trace, Controller, Repository, Gatekeeper, Composer, parser/projection, and Eval tests SHALL pass
• AND the fixed diagnosis eval report/diff SHALL show no unexpected regression
• AND OpenSpec strict and source/whitespace checks SHALL pass

Requirement: Final live E2E SHALL prove exact StateGraph Run ownership

The final acceptance SHALL start the application through Maven with the mvp-demo profile and SHALL execute Chat, exact Trace, and feedback requests using one unique sessionId and the returned runId.

Scenario: Live Chat Graph completes

• WHEN the unique payment-timeout demo request completes
• THEN the response SHALL be successful with a non-empty answer/sessionId/runId
• AND exact Trace SHALL return the same runId with a non-empty run.orchestrationTrace
• AND orchestration trace SHALL include version, final node, termination reason, transitions, degraded, and evidence retry count
• AND feedback SHALL attach to the same runId

Scenario: Live application is cleaned up

• WHEN live verification finishes or fails
• THEN the Maven/Java processes started by this stage SHALL be stopped
• AND port 9900 SHALL no longer be owned by the stage 5 process
• AND temporary target output/log files SHALL be removed after evidence extraction

Requirement: Final logs and database SHALL corroborate the E2E Run

Stage 5 SHALL inspect only the current live run's new log segment and SHALL query exact database rows with the repository MySQL tool.

Scenario: New logs are inspected

• WHEN E2E returns sessionId and runId
• THEN new application/chat logs SHALL contain evidence for the current request/run lifecycle
• AND no unexplained ERROR in the new stage 5 segment SHALL invalidate acceptance

Scenario: Exact database run is queried

• WHEN scripts/query_mysql.py queries the E2E sessionId/runId
• THEN V012 orchestration column SHALL exist
• AND DiagnosisRun SHALL be CHAT/SUCCESS with non-empty answer, metrics, self-evaluation, orchestration trace, and useful feedback
• AND orchestration JSON fields SHALL match the exact Trace response
• AND AgentStep/ToolInvocation ownership checks SHALL contain no row from another run/session

Requirement: ISS-011 SHALL close only after all final gates pass

The Issue SHALL remain active until cleanup, docs, deterministic regression, live E2E, logs, database, process cleanup, and OpenSpec validation are complete.

Scenario: Any final gate fails

• WHEN a required stage 5 gate is incomplete or failed
• THEN ISS-011 SHALL remain active
• AND acceptance SHALL record the blocker without marking the OpenSpec complete

Scenario: All final gates pass

• WHEN all stage 5 acceptance evidence is archived
• THEN ISS-011 checkboxes/status SHALL be completed
• AND the Issue SHALL move from active to archived with its index entry updated