# 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.

## Context

- `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.

## Question Pool

| # | 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 |

## Evidence-driven

| 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 |

## User-interview

| 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 |

## Key Decisions

- 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.

## Cross-Artifact Alignment

| 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 |

## Architecture Audit

- 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.

## Pre-apply Research

- 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.

## Commit Gate

- OpenSpec proposal/design/specs/tasks exist.
- API impact: L3 additive collaboration API, documented in design and spec.
- User-confirmed non-goal: sensitive configuration cleanup remains out of scope.
- No unresolved user-interview questions remain for this slice.