docs(docs): add prp 41 showcase agent ops polish

[w7-mgfcode]

Summary

Docs-only PR adding PRPs/PRP-41-showcase-agent-ops-polish.md — the one-pass implementation contract for the FINAL slice of the /showcase upgrade epic (PRP-38..41).

Closes: #321 (implementation issue — this PR ships the spec only).

PRP at a glance

Field	Value
PRP path	PRPs/PRP-41-showcase-agent-ops-polish.md
Tasks	20 (Task 1 = contract probe gate, Tasks 2-19 implementation, Task 20 manual dogfood)
Unresolved contract assumptions	5 (see § "Unresolved Contract Assumptions", PRP lines 2168-2221)
New backend endpoints	0 (read-only consumer of existing /agents/sessions/*, /ops/*)
New schemas / Alembic migrations	0
Closes UI bug	#311 (DemoPhasePanel onValueChange)

Task 1 — Contract Probe (the gate)

Before any implementation Task runs, Task 1 produces PRPs/ai_docs/prp-41-contract-probe-report.md that verifies every cited backend field-for-field. INITIAL-41 already flagged drift on dev:

• ModelHealthEntry.drift_direction (NOT drift_verdict)
• Approval body field is action_id (NOT tool_call_id)
• Chat response surfaces approval via pending_approval: bool + pending_action: PendingAction (NOT an approval_required event — that event fires only on the WS /agents/stream path)

If any cite drifts, the executor must STOP and patch the PRP before proceeding.

Unresolved contract assumptions (5)

1. _Client.yield_event orchestrator-fill-in semantics for step_index / phase_index / phase_total.
2. /approve double-fire response shape (200 idempotent vs 4xx "action consumed").
3. SHOWCASE_RICH_STEP_NAMES filter selector keeps agent on demo_minimal AND agent_hitl_flow on showcase_rich.
4. OpsSummaryResponse.runs.counts vs runs.histogram path + per-item key (count vs value).
5. _Client.request list-body wrapper (already CONFIRMED — no action; documented for future-proofing).

Task 1 resolves 1-4 against live dev before any implementation Task runs.

Scope discipline

• Docs-only — no app/ code, no frontend/ code, no migrations, no test changes.
• No qwen3 stash interaction — stash@{0} ("local qwen3 rag demo changes before prp-35") is untouched and remains stashed.
• Implementation lives behind the PRP-41 execution issue (feat(api,ui): showcase pipeline agent ops final polish (PRP-41) #321), to be picked up on a separate branch.

Test plan

• git diff --stat origin/dev...HEAD shows exactly one file changed: PRPs/PRP-41-showcase-agent-ops-polish.md
• git diff --name-only origin/dev...HEAD contains no entries under app/, frontend/, alembic/, tests/
• git stash list shows the qwen3 stash at stash@{0} unchanged
• CI green on this docs-only branch (lint + typecheck + test + migration-check should all pass as no-ops)

🤖 PRP authoring driven by the PRP epic; this PR ships the artifact only.

[sourcery-ai]

Sorry @w7-mgfcode, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3439ee92-83c4-4de6-ab5b-d2100d15aa53

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/add-prp-41-showcase-agent-ops-polish

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}