MVP Demo Trace Acceptance Decisions

Clarify

Entry summary: continue the MVP toward a runnable and explainable demo by adding an mvp-demo profile, an end-to-end acceptance case, and a trace query API.
Slug: mvp-demo-trace-acceptance
Devflow scale: standard-light. The change adds a public read-only API and documentation, but does not alter core chat execution or persistence schemas.

devflow/index.md was checked. Relevant history includes session-storage, confidence-feedback, executor-action-memory-relevance, and chat-verifier-agent.
mvp/archive/2026-07-09-doc-cleanup/notes/agent-engineering-decisions.md already recommends the next phase as "可复现 MVP Demo", including mvp-demo profile, fixed diagnosis case, one-click request, and GET /api/diagnosis/{sessionId}/trace.
mvp/issues/active/ISS-003-mvp-design-implementation-review.md identifies test stability, session traceability, verifier evidence chain, upload path, and SupervisorAgent consistency as recent MVP concerns. Security cleanup is intentionally deferred by user decision.

#	Dimension	Question	Mode	Status
Q1	Terminology	Should "trace" mean persisted diagnosis execution evidence instead of transient frontend chat history?	evidence-driven	Resolved
Q2	Boundary	Should this change modify chat execution or only expose existing persisted evidence?	evidence-driven	Resolved
Q3	Acceptance	What proves the MVP flow is end-to-end enough for demo/interview use?	evidence-driven	Resolved
Q4	Interface	What is the API impact level for `GET /api/diagnosis/{sessionId}/trace`?	evidence-driven	Resolved

Conclusion	Evidence Source	Reported To User
Trace should aggregate persisted diagnosis evidence, not Redis-only chat history.	`DiagnosisSession`, `AgentStep`, `ToolInvocation` entities and repositories	Reported in progress update
Core chat execution does not need to change for this slice.	Existing unified chat path and SupervisorAgent commits; requested scope is demo/profile/trace/acceptance	Reported in progress update
End-to-end acceptance should cover start -> chat -> trace -> feedback.	`ChatController`, `FeedbackController`, traceable session id decision in MVP notes	Reported in progress update
Trace API is additive L3 because it is a new HTTP API for frontend/demo consumers.	sm-flow interface impact rules	Recorded in OpenSpec design

Question	User Words	Confirmation	OpenSpec Writeback
Should security/sensitive config cleanup be included?	"安全问题先不考虑"; "敏感配置先不做"	Confirmed	Non-goal
Should this be implemented under sm-flow?	"按照 sm-flow 的流程来实现吧"	Confirmed	This change follows sm-flow artifacts

Decision: Add a new trace API instead of embedding trace details in /api/chat.
- Reason: Chat execution and observability should stay decoupled.
- Impact: Demo can query trace after any successful chat request using the same session id.
- Risk accepted: Response shape is new and should be treated as demo-facing contract.
Decision: Keep mvp-demo profile as configuration overlay, not a fully mocked standalone runtime.
- Reason: The current MVP still depends on real DB/Redis/Milvus/LLM for full chat execution; this change avoids inventing a fake runtime that hides integration behavior.
- Impact: Demo profile improves repeatability for logs/metrics, while docs remain explicit about required external services.
- Risk accepted: End-to-end acceptance may still require valid infrastructure and keys.

Upstream -> Downstream	Check	Status
brief/prd -> proposal	Goal, scope, non-goals, and acceptance expectation are in proposal	Aligned
proposal -> design	Scope, constraints, and API impact are in design	Aligned
design -> specs/tasks	Trace DTO, controller/service, demo profile, and docs are represented	Aligned
specs -> tasks	Observable behavior is covered by executable tasks	Aligned

Data path: HTTP trace request -> controller -> trace service -> repositories -> aggregate DTO -> Result.success.
The service is read-only and does not mutate diagnosis, step, tool, or feedback state.
No schema change is needed because all required fields already exist in diagnosis_session, agent_step, and tool_invocation.
Main risk is response size for large sessions; MVP mitigates by returning previews already persisted by tools rather than raw external logs.
The additive API is acceptable for MVP because old callers remain unaffected.

Reference implementations read:
- ChatController for /api controller conventions.
- FeedbackController for simple API controller shape.
- GlobalExceptionHandler and SessionNotFoundException for 404 handling.
- DiagnosisSessionRepository, AgentStepRepository, ToolInvocationRepository for available queries.
- DiagnosisSession, AgentStep, ToolInvocation for fields.
Impact analysis:
- DiagnosisSessionRepository: LOW, direct imports in service/controller paths.
- AgentStepRepository: HIGH because it participates in chat/AiOps flows. This change only consumes existing query methods and does not modify the repository.
- ToolInvocationRepository: LOW.