feat: Epic 13 (Structured Questions) + Epic 14 (Native STT)

[don-petry]

Summary

• Epic 13 (FR57-FR59): Structured Question Input — When the agent responds with numbered questions, they're detected by a renderer-side parser and presented as interactive Question Card Stack in the right panel with per-question input, suggestion chips, dot navigation, and review-before-submit
• Epic 14 (FR60-FR62): Native STT with sherpa-onnx — Replaced non-functional Web Speech API (Google servers unreachable in Electron) with sherpa-onnx local streaming speech recognition. Audio captured via getUserMedia, streamed as 16kHz PCM to main process via IPC, transcribed in real-time with endpoint detection
• Bug fix: Removed hard-coded option cards — Option cards are now agent-driven only, not hard-coded on load

Commits (stacked)

1. docs: Spec updates — PRD v2.4 (FR57-FR62), UX spec v1.3 (Journey 7), Epics (Epic 13 stories), Sprint status
2. feat: Epic 13 implementation — question-parser.ts, QuestionCardStack, QuestionReview, SuggestionChips, E2E tests
3. feat: Epic 14 implementation — sherpa-onnx-node adapter, IPC audio pipeline, mic permission handlers

New Files

File	Purpose
src/shared/types/domain/question-parser.ts	Pure parser: detects numbered questions in agent text
src/renderer/components/session/QuestionCardStack.tsx	Card stack with useReducer, dot nav, chips
src/renderer/components/session/QuestionReview.tsx	Review overlay with aggregated submission
src/renderer/components/session/SuggestionChips.tsx	Selectable pill chips
src/main/speech/sherpa-onnx-stt.ts	Main-process STT adapter using sherpa-onnx OnlineRecognizer
src/main/ipc/speech-ipc-handler.ts	IPC bridge for audio streaming
src/renderer/speech/ipc-speech-stt.ts	Renderer-side STT via getUserMedia + IPC

Test plan

• 78 unit/component tests passing (question parser, card stack, review, ConversationView)
• TypeScript clean (tsc --noEmit)
• ESLint clean (--max-warnings 0)
• Pre-commit hooks passing (lint-staged + tsc + vitest related)
• E2E: structured-questions.spec.ts (requires built app + Claude subscription)
• Manual: mic button → sherpa-onnx transcription → agent message
• Manual: agent multi-question response → card stack appears → answer → submit

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR scaffolds the TalkTerm Electron (Forge + Vite) application and establishes the initial shared domain/port types, renderer UI components (setup + overlay/display primitives), speech adapters, and CI/tooling configuration.

Changes:

• Add project build/test/tooling configuration (Vite configs, TS strict config, ESLint/Prettier/Husky, Vitest + coverage, Tailwind/PostCSS, GitHub Actions).
• Introduce shared domain + port types (sessions, writeback, IPC envelopes/channels, agent events/errors, value objects).
• Implement initial renderer components/hooks and main-process stubs/utilities with accompanying unit tests.

Reviewed changes

Copilot reviewed 147 out of 162 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
vitest.config.ts	Adds Vitest configuration with coverage thresholds.
vite.renderer.config.ts	Configures PostCSS pipeline for the renderer build.
vite.preload.config.ts	Adds preload Vite config placeholder.
vite.main.config.ts	Adds main-process Vite resolution settings.
tsconfig.json	Enables strict TypeScript options and path mapping.
test/setup-renderer.ts	Adds Testing Library jest-dom matchers for Vitest.
tailwind.config.ts	Defines design tokens (colors/type/spacing) for Tailwind.
src/shared/types/ports/text-to-speech.ts	Defines TextToSpeech port contract.
src/shared/types/ports/speech-to-text.ts	Defines SpeechToText port contract.
src/shared/types/ports/agent-backend.ts	Defines AgentBackend port + session config.
src/shared/types/ports/.gitkeep	Keeps ports directory in VCS.
src/shared/types/domain/writeback.ts	Adds writeback target types + default selection by origin.
src/shared/types/domain/writeback.test.ts	Tests default writeback selection.
src/shared/types/domain/value-objects.ts	Adds branded value objects + constructors.
src/shared/types/domain/value-objects.test.ts	Tests value-object validation.
src/shared/types/domain/user-profile.ts	Adds UserProfile type + factory.
src/shared/types/domain/user-profile.test.ts	Tests UserProfile factory behavior.
src/shared/types/domain/session.ts	Adds Session type + factory.
src/shared/types/domain/session.test.ts	Tests Session factory behavior.
src/shared/types/domain/project.test.ts	Sanity tests for TS strictness flags.
src/shared/types/domain/preference.ts	Adds preference threshold utilities/constants.
src/shared/types/domain/preference.test.ts	Tests preference threshold logic.
src/shared/types/domain/launch-state.ts	Adds setup-step routing helper.
src/shared/types/domain/launch-state.test.ts	Tests setup-step routing priority.
src/shared/types/domain/ipc-message.ts	Adds IPC message envelope + factory.
src/shared/types/domain/ipc-message.test.ts	Tests IPC message factory timestamping.
src/shared/types/domain/ipc-channels.ts	Defines canonical IPC channel constants + type.
src/shared/types/domain/ipc-channels.test.ts	Tests channel naming + uniqueness.
src/shared/types/domain/electron-api.ts	Declares preload bridge contract type for renderer.
src/shared/types/domain/avatar-persona.ts	Adds MVP persona roster.
src/shared/types/domain/avatar-persona.test.ts	Tests persona roster shape/uniqueness.
src/shared/types/domain/audit-entry.ts	Adds AuditEntry type + factory.
src/shared/types/domain/audit-entry.test.ts	Tests AuditEntry factory behavior.
src/shared/types/domain/api-key-state.ts	Defines API key state + validation result types.
src/shared/types/domain/agent-event.ts	Adds AgentEvent union for streaming events.
src/shared/types/domain/agent-error.ts	Adds error classification + user-friendly messaging.
src/shared/types/domain/agent-error.test.ts	Tests error classification and message safety.
src/shared/types/domain/.gitkeep	Keeps domain directory in VCS.
src/renderer/types/web-speech.d.ts	Adds Web Speech API window typings.
src/renderer/types/.gitkeep	Keeps renderer types directory in VCS.
src/renderer/styles/global.css	Adds Tailwind directives + global font/body styles.
src/renderer/speech/web-speech-tts.ts	Implements TTS adapter using Web Speech API.
src/renderer/speech/web-speech-tts.test.ts	Tests WebSpeechTts behavior under jsdom mocks.
src/renderer/speech/web-speech-stt.ts	Implements STT adapter using Web Speech API.
src/renderer/speech/web-speech-stt.test.ts	Tests WebSpeechStt behavior under jsdom mocks.
src/renderer/speech/barge-in-controller.ts	Adds barge-in state controller (TTS stop + STT start).
src/renderer/speech/barge-in-controller.test.ts	Tests barge-in state transitions and calls.
src/renderer/speech/.gitkeep	Keeps speech directory in VCS.
src/renderer/renderer.tsx	Adds React entrypoint mounting App.
src/renderer/hooks/useLayoutState.ts	Adds reducer-driven layout mode hook.
src/renderer/hooks/useLayoutState.test.ts	Tests layout mode transitions.
src/renderer/hooks/useDisplayMode.ts	Adds display-mode selection state hook.
src/renderer/hooks/useDisplayMode.test.ts	Tests display-mode state updates.
src/renderer/hooks/useAvatarState.ts	Adds avatar animation-state reducer hook.
src/renderer/hooks/useAvatarState.test.ts	Tests avatar state transitions.
src/renderer/hooks/.gitkeep	Keeps hooks directory in VCS.
src/renderer/context/.gitkeep	Keeps context directory in VCS.
src/renderer/components/setup/WorkspaceSelection.tsx	Adds workspace selection UI.
src/renderer/components/setup/WorkspaceSelection.test.tsx	Tests workspace selection callbacks.
src/renderer/components/setup/ProfileSetup.tsx	Adds profile setup UI.
src/renderer/components/setup/ProfileSetup.test.tsx	Tests profile setup interactions.
src/renderer/components/setup/AvatarSelection.tsx	Adds avatar selection UI using MVP personas.
src/renderer/components/setup/AvatarSelection.test.tsx	Tests avatar selection callback.
src/renderer/components/setup/ApiKeySetup.tsx	Adds API key entry/validation UI (stub validation).
src/renderer/components/setup/ApiKeySetup.test.tsx	Tests API key setup basic rendering.
src/renderer/components/setup/AdminBlockScreen.tsx	Adds blocking admin-privileges screen UI.
src/renderer/components/setup/AdminBlockScreen.test.tsx	Tests admin block screen rendering and buttons.
src/renderer/components/overlay/ActionPanel.tsx	Adds action panel container (listbox) UI.
src/renderer/components/overlay/ActionPanel.test.tsx	Tests action panel rendering and selection.
src/renderer/components/overlay/ActionCard.tsx	Adds action card UI with option semantics.
src/renderer/components/overlay/ActionCard.test.tsx	Tests action card semantics and interactions.
src/renderer/components/display/TaskProgress.tsx	Adds task progress display mode.
src/renderer/components/display/TaskProgress.test.tsx	Tests task progress rendering.
src/renderer/components/display/DocumentView.tsx	Adds basic document display mode.
src/renderer/components/display/DocumentView.test.tsx	Tests document rendering/path display.
src/renderer/components/display/ComparisonTable.tsx	Adds comparison table display mode.
src/renderer/components/display/ComparisonTable.test.tsx	Tests comparison table expand behavior.
src/renderer/components/display/ClusteredCards.tsx	Adds clustered cards display mode.
src/renderer/components/display/ClusteredCards.test.tsx	Tests clustered cards expand/priority tags.
src/renderer/components/display/ActivityFeed.tsx	Adds activity feed display mode.
src/renderer/components/display/ActivityFeed.test.tsx	Tests activity feed visibility/rendering.
src/renderer/components/avatar/TextInput.tsx	Adds text input w/ Enter-to-send and mic button.
src/renderer/components/avatar/TextInput.test.tsx	Tests text input send/newline/mic behavior.
src/renderer/components/avatar/StatusIndicator.tsx	Adds avatar status pill.
src/renderer/components/avatar/StatusIndicator.test.tsx	Tests status pill rendering and role=status.
src/renderer/components/avatar/CaptionBar.tsx	Adds caption bar w/ delayed hide logic.
src/renderer/components/avatar/CaptionBar.test.tsx	Tests caption bar basic rendering conditions.
src/renderer/components/.gitkeep	Keeps components directory in VCS.
src/renderer/App.tsx	Adds minimal App shell.
src/preload/preload.ts	Adds preload bridge stub via contextBridge.
src/main/storage/.gitkeep	Keeps storage directory in VCS.
src/main/security/admin-check.ts	Adds admin privilege check helper + instructions.
src/main/security/admin-check.test.ts	Tests admin privilege check across platforms.
src/main/security/.gitkeep	Keeps security directory in VCS.
src/main/main.ts	Adds Electron main window creation and lifecycle wiring.
src/main/ipc/.gitkeep	Keeps IPC directory in VCS.
src/main/agent/fake-agent-backend.ts	Adds FakeAgentBackend test double.
src/main/agent/fake-agent-backend.test.ts	Tests FakeAgentBackend event streaming/cancel.
src/main/agent/agent-message-router.ts	Adds router forwarding backend events to handler.
src/main/agent/agent-message-router.test.ts	Tests router event forwarding and cancel.
src/main/agent/.gitkeep	Keeps agent directory in VCS.
postcss.config.js	Adds PostCSS config for Tailwind/autoprefixer.
package.json	Adds dependencies, scripts, lint-staged config.
index.html	Adds renderer entry HTML.
forge.config.ts	Configures Electron Forge + Vite plugin + makers.
eslint.config.mjs	Adds ESLint flat config with strict TS + React rules.
.prettierrc	Adds Prettier config.
.prettierignore	Adds Prettier ignore rules.
.husky/pre-commit	Adds pre-commit quality gate commands.
.gitignore	Adds repo ignore rules (build artifacts/coverage).
.github/workflows/release.yml	Adds release workflow for tag builds.
.github/workflows/ci.yml	Adds CI workflow with 3-OS matrix quality gates.
_bmad-output/implementation-artifacts/*.md	Adds planning/implementation artifacts for stories.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch worktree-implement-sprint-1

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[sonarqubecloud]

Quality Gate failed

Failed conditions
3 Security Hotspots
0.0% Coverage on New Code (required ≥ 80%)
D Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[github-actions]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved manually.

Please resolve the conflicts and push:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

@claude Please address all open review comments on this PR from CodeRabbit and Copilot.

[claude]

Claude finished @don-petry's task in 5m 30s —— View job

---

Addressing Open Review Comments

Finding: All 7 Copilot review items were already addressed in prior commits (the PR has 36 commits made after the review was posted). One gap remained: ActionPanel.tsx had keyboard navigation logic added in response to the review, but ActionPanel.test.tsx had no tests for those branches.

Tasks

• Gather context and read relevant files
• Verify admin-check.test.ts — vi.unstubAllGlobals() already in afterEach ✓
• Verify ipc-message.ts — channel already typed as IPCChannel ✓
• Verify agent-error.ts — TTS check already before STT ✓
• Verify agent-event.ts — RecoveryOption already imported from agent-error.ts (no duplication) ✓
• Verify ActionPanel.tsx — keyboard nav (ArrowDown/Up, Enter, Space) already implemented ✓
• Verify CaptionBar.test.tsx — fake timer tests for 3s hide already present ✓
• Verify AdminBlockScreen.test.tsx — @vitest-environment jsdom already on first line ✓
• Add keyboard nav tests to ActionPanel.test.tsx — committed dddc998
• Push to remote branch

What was committed (dddc998):
Added 10 new tests to src/renderer/components/overlay/ActionPanel.test.tsx covering:

• ArrowDown moves focus to next enabled card
• ArrowUp moves focus to previous enabled card
• ArrowDown wraps from last to first
• ArrowUp wraps from first to last
• Enter selects the focused card
• Space selects the focused card
• Disabled cards are skipped during navigation
• Enter does not fire onSelect when focused card is disabled
• All-disabled no-op (no throw)
• aria-label prop and default title-as-accessible-name

Cannot address (GitHub App permissions restrict .github/workflows/ edits):

• ci.yml — expand push trigger to all branches
• release.yml — add GitHub Release creation step + explicit permissions block
  | Branch

[don-petry]

@dev-lead - please fix this PR

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[sonarqubecloud]

Quality Gate failed

Failed conditions
4.5% Duplication on New Code (required ≤ 3%)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[github-actions]

CI Failure: SonarCloud Code Analysis

Step: SonarCloud Quality Gate (static analysis)
Root cause: Lint/style

The quality gate failed on two conditions: 4.5% duplication on new code (required ≤ 3%) and a C Reliability Rating on new code (required ≥ A). The reliability failure is annotated as a failure-level issue at src/renderer/components/overlay/ActionPanel.test.tsx:156. There are also warnings in src/shared/types/domain/question-parser.ts (lines 14, 15, 80, 154), render-markdown.ts (lines 34, 82, 115), claude-sdk-backend.ts:360 and global.css:5. The PR diff exceeds GitHub's 20k-line limit, so these details come from the check annotations.

Suggested fix: Open the failure-level issue at ActionPanel.test.tsx:156 in SonarCloud and fix it to restore the Reliability rating to A. Then deduplicate the repeated logic in question-parser.ts and render-markdown.ts to bring new-code duplication under 3%.

View run logs

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

dev-lead will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push