92 lines
5.6 KiB
Markdown
92 lines
5.6 KiB
Markdown
# chat-diagnosis-stategraph-cleanup-docs Specification
|
|
|
|
## Purpose
|
|
TBD - created by archiving change chat-diagnosis-stategraph-cleanup-docs. Update Purpose after archive.
|
|
## 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
|