Add MVP demo interview runbook

openspec/changes/mvp-demo-interview-runbook/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-04

openspec/changes/mvp-demo-interview-runbook/design.md

@@ -0,0 +1,35 @@
+## Context
+
+The current `mvp/demo` folder documents the core flow, but the steps are embedded in prose. For an interview, the demo needs a sharper entry point: what to start, what to run, what files get produced, and what to point at when explaining Agent engineering quality.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make the payment-timeout demo runnable through a small script.
+- Save chat, trace, and feedback responses for review.
+- Provide a short interview walkthrough that connects runtime evidence to the engineering story.
+- Keep the demo focused on existing APIs and existing `mvp-demo` profile behavior.
+
+**Non-Goals:**
+
+- Do not add new backend endpoints.
+- Do not modify Agent prompts or runtime orchestration.
+- Do not solve secret cleanup or full offline test isolation in this change.
+- Do not expand the eval harness.
+
+## Decisions
+
+- Decision: Use PowerShell scripts.
+  - Reason: the current runbook already uses PowerShell and the user environment is Windows.
+
+- Decision: Save outputs under `mvp/demo/output`.
+  - Reason: interview review is easier when chat, trace, and feedback responses are persisted as files.
+
+- Decision: Keep the walkthrough separate from the low-level runbook.
+  - Reason: `README.md` should tell how to run; `interview-walkthrough.md` should tell how to explain.
+
+## Risks / Trade-offs
+
+- The demo still depends on configured MySQL, Redis, Milvus, and model keys. Mitigation: document this explicitly and keep mock log/metric providers enabled through `mvp-demo`.
+- Script assertions are intentionally lightweight. Mitigation: use the trace checklist for human review and keep automated regression in `mvp/eval`.

openspec/changes/mvp-demo-interview-runbook/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+The MVP already has trace, evidence hardening, and evaluation artifacts, but the interview demo path is still too scattered. This change packages the existing capabilities into a repeatable demo runbook that can be executed and explained in a short interview window.
+
+## What Changes
+
+- Add a focused interview walkthrough for the payment-timeout MVP demo.
+- Add reusable request payloads and PowerShell scripts under `mvp/demo`.
+- Add a trace inspection checklist that maps runtime output to the engineering story.
+- Keep the change documentation-only and script-only; no backend runtime behavior changes.
+
+## Capabilities
+
+### New Capabilities
+
+- None.
+
+### Modified Capabilities
+
+- `mvp-demo-trace-acceptance`: Extend the demo acceptance surface with a repeatable interview runbook and executable local demo scripts.
+
+## Impact
+
+- Affects `mvp/demo` documentation and scripts.
+- Adds issue and devflow tracking files.
+- No Java production code, API contract, database schema, or dependency changes are expected.

openspec/changes/mvp-demo-interview-runbook/specs/mvp-demo-trace-acceptance/spec.md

@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: MVP demo SHALL provide an interview runbook
+The MVP demo SHALL include a concise interview runbook that explains how to demonstrate the Agent flow and how to narrate the engineering value.
+
+#### Scenario: Walkthrough explains the demo story
+- **WHEN** a developer opens the interview walkthrough
+- **THEN** it SHALL explain the user question, Agent flow, evidence tools, verifier judgment, trace API, feedback, and eval baseline connection
+
+#### Scenario: Walkthrough stays scoped to existing capabilities
+- **WHEN** the walkthrough describes the demo
+- **THEN** it SHALL avoid claiming unsupported runtime behavior or new production features
+
+### Requirement: MVP demo SHALL provide executable local demo scripts
+The MVP demo SHALL provide scripts and request payloads for running the payment-timeout case through existing local APIs.
+
+#### Scenario: Demo script sends the fixed diagnosis request
+- **WHEN** the demo script is executed against a running local service
+- **THEN** it SHALL send the fixed payment-timeout chat request with a stable session id
+
+#### Scenario: Demo script captures review artifacts
+- **WHEN** the demo script finishes successfully
+- **THEN** it SHALL write chat, trace, and feedback responses under a demo output directory
+
+### Requirement: MVP demo SHALL provide a trace inspection checklist
+The MVP demo SHALL document which trace fields to inspect for evidence, verifier behavior, and session-level auditability.
+
+#### Scenario: Checklist maps fields to interview claims
+- **WHEN** a developer reviews a trace response
+- **THEN** the checklist SHALL map concrete JSON paths to the claims made in the interview walkthrough

openspec/changes/mvp-demo-interview-runbook/tasks.md

@@ -0,0 +1,16 @@
+## 1. Demo Artifacts
+
+- [x] 1.1 Add fixed payment-timeout request payload.
+- [x] 1.2 Add PowerShell script to run chat, trace, and feedback steps.
+- [x] 1.3 Add output directory documentation without committing generated outputs.
+
+## 2. Interview Documentation
+
+- [x] 2.1 Add interview walkthrough for the demo story.
+- [x] 2.2 Add trace inspection checklist.
+- [x] 2.3 Update `mvp/demo/README.md` to link the runnable demo package.
+
+## 3. Tracking And Validation
+
+- [x] 3.1 Add slug-based issue and devflow tracking files.
+- [x] 3.2 Run OpenSpec validation.