feat: import rehearsal handoffs for focused reanalysis by seonghobae · Pull Request #740 · ContextualWisdomLab/bandscope

seonghobae · 2026-08-03T03:29:28Z

Buyer-visible integration slice

Import a bounded BandScope metadata-handoff JSON artifact without granting the artifact filesystem authority, require the recipient to pair it with a fresh local audio selection, and reuse only validated rehearsal-role focus metadata for local reanalysis. BandScope remains independently usable and local-first.

Exact current identity

Head: 4761a882d1b345647fb6ca7bbb7c89c5420a097f.
Protected base: develop@acdbea6344fe1231c39535b575f4de35e4c607c9.
Branch: feat/handoff-import-roundtrip.
Open, Draft, mergeable, and unmerged.
The current base-to-head diff contains 23 files; no dependency manifest, root lockfile, database, model, or new persistent application authority is introduced.

Trust and state boundaries

The current branch establishes these product contracts:

handoff bytes are bounded before decode and validated as UTF-8, JSON, and the expected artifact kind/version before use;
source references embedded in the artifact remain inert and never authorize filesystem or URL dereference;
importing, replacing, or validating a handoff requires a fresh recipient-selected local audio source before analysis;
YouTube intake remains fail-closed while a validated handoff is pending;
handoff validation, source selection/import, project load/save, and analysis start are mutually exclusive at both UI and handler boundaries;
stale picker/change/clear events and stale async project/job transitions cannot retain authority after the owning state changes;
local paths, URLs, secret-shaped assignments, and multiline payload details are redacted from rendered errors;
role-focused responses project only requested roles and links while the cache retains the complete analysis result; and
desktop analysis-status polling accepts only a status whose jobId matches the requested job, matching the existing pushed-event identity guard.

Latest exact-head repair

Exact CI/log tracing found two test-side failures after the analysis bridge gained the fail-closed job-identity contract.

App.stale-job-poll.test.tsx queried a generic role="status" even though the App intentionally renders more than one live status surface. Commit 1a1246d4f749a310a6eca663707ac54862e0f2e7 binds the regression to the user-visible Queued for analysis state instead.
App.test.tsx test keeps polling the active job when one polling request rejects starts active job job-4, but its final success fixture used succeededResult()'s unrelated default job-1. The production bridge correctly rejected that foreign status. Current head 4761a882d1b345647fb6ca7bbb7c89c5420a097f keeps the production guard intact and makes the final fixture return job-4. The same test-only commit removes two fragile trailing-wildcard placeholder expressions and formatter-only blank lines; no production file changed in that commit.

The bridge-level mismatch regression and production guard were introduced earlier on this branch: a Tauri response for a different job is rejected with the stable payload-free Invalid analysis job status response boundary rather than being rendered or accepted as the requested job.

Exact-current-head verification state

All currently visible inline review threads are resolved.

Fresh workflow evidence is still in progress for head 4761a882d1b345647fb6ca7bbb7c89c5420a097f. In CI run 32262803831, job 96099875297 (gate / ci / rust-check) is terminal-success; job 96099874748 (ci / build-and-test) remains queued. The exact-head release, build-baseline, SBOM, security-audit, aggregate Security Scan, Semgrep, Bandit, and secret-scan workflows are also queued at the latest inspection. Queued or partially successful workflow sets are not counted as GREEN.

Dependency and control-plane gates

Canonical dependency-security owner #783 remains open on exact head 99e6be9f0933df605c03c04e959b47c5c2405ca6. This branch does not suppress or duplicate its PDF.js, Nanoid, Undici, npm-generator, or lock-provenance remediation.

Python branch-measurement owner #861 remains open and Draft. Statement-only evidence on this branch is not substituted for the protected statement-plus-branch coverage contract.

Protected ContextualWisdomLab/.github@main is bbedc1a51ec1a2421f129955c629b3cd0507a4ec; the .github#1136 trusted-uv repair is integrated in its ancestry. Fresh exact-head central coverage/OpenCode/Noema/Strix evidence is still required after the repository and dependency prerequisites are satisfied.

Merge gate

Keep Draft and unmerged until one unchanged resulting exact head simultaneously has:

every applicable repository CI/build/release/security/SAST/SBOM/supply-chain gate terminal-success;
fix(security): establish canonical npm, PDF.js, Nanoid, and Undici baseline #783 integrated into protected develop, followed by refresh and clean dependency-security revalidation;
test(quality): enforce Python branch coverage #861 or equivalent protected branch-measurement behavior integrated and exact statement-plus-branch evidence obtained;
terminal-success central coverage/OpenCode/Noema/Strix evidence bound to that exact head;
zero valid unresolved review findings;
a qualifying independent non-author last-push approval; and
ordinary protected-branch acceptance without bypass.

Never transfer predecessor-head checks or reviews, weaken a gate, self-approve, or treat queued, pending, skipped, cancelled, inherited-base failure, model-only, author, or administrative-bypass evidence as success.

coderabbitai · 2026-08-03T03:29:36Z

📝 Walkthrough

Walkthrough

검증된 BandScope 메타데이터 핸드오프를 가져오는 데스크톱 UI와 파일 검증 로직을 추가했습니다. 사용자는 로컬 오디오를 명시적으로 선택한 뒤 역할 집중 재분석을 시작합니다. 분석 엔진은 요청 역할과 관련된 결과만 반환하고 전체 결과는 캐시에 보존합니다.

Changes

메타데이터 핸드오프 왕복

Layer / File(s)	Summary
핸드오프 검증 및 요청 계약 `apps/desktop/src/lib/handoff.ts`, `apps/desktop/src/lib/handoff.test.ts`	JSON 확장자, 1 MiB 크기, 실제 바이트 길이, UTF-8, JSON, artifact 계약을 순서대로 검증합니다. 검증된 artifact에서 중복 없는 역할 초점을 추출하고 분석 요청을 생성합니다.
핸드오프 가져오기 컨트롤 `apps/desktop/src/features/import/HandoffImportControl.tsx`, `apps/desktop/src/features/import/HandoffImportControl.test.tsx`	파일 선택, 비동기 검증, 오류 전달, workspace·song·role 표시, 교체, 삭제, 비활성화 상태를 구현하고 테스트합니다.
앱 상태 및 분석 흐름 연결 `apps/desktop/src/App.tsx`, `apps/desktop/src/App.handoff.test.tsx`, `apps/desktop/src/locales/*/common.json`, `apps/desktop/vite.config.ts`, `docs/workflows/metadata-handoff-import.md`, `CHANGELOG.md`	핸드오프와 로컬 오디오 선택을 연결하고 상호 배타적으로 처리합니다. 분석 전 로컬 오디오 선택을 요구하며 완료·프로젝트 로드 후 핸드오프를 정리합니다. 오류 메시지, 문서, 커버리지 설정, 변경 로그를 갱신합니다.
역할 집중 결과 및 캐시 처리 `services/analysis-engine/src/bandscope_analysis/api.py`, `services/analysis-engine/tests/test_role_focus.py`	요청 역할과 관련된 역할, part-graph 노드, handoff 관계, `focusSections`만 반환합니다. 캐시에는 전체 결과를 저장하고 응답에는 요청별 필터링 결과를 사용합니다.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant 사용자
  participant HandoffImportControl
  participant App
  participant AnalysisAPI
  participant AnalysisCache
  사용자->>HandoffImportControl: 핸드오프 JSON 선택
  HandoffImportControl->>App: 검증된 artifact 전달
  사용자->>App: 로컬 오디오 선택
  App->>AnalysisAPI: 로컬 오디오와 역할 초점이 포함된 분석 요청
  AnalysisAPI->>AnalysisCache: 전체 분석 결과 조회 또는 저장
  AnalysisAPI-->>App: 역할 집중 분석 결과 반환

Possibly related PRs

ContextualWisdomLab/bandscope#305: 메타데이터 핸드오프 artifact 계약과 재분석 요청 로직을 직접 확장합니다.
ContextualWisdomLab/bandscope#53: 분석 오케스트레이션과 역할 집중 결과 필터링 흐름을 확장합니다.
ContextualWisdomLab/bandscope#185: 분석 엔진 API의 rehearsal 결과 처리와 역할 집중 동작을 수정합니다.

Suggested labels: codex, aardvark

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 76.47% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	[`#739`]의 가져오기, 검증, 로컬 오디오 선택, 역할 집중 재분석, 오류 처리, 테스트 요구사항을 변경 사항이 충족합니다.
Out of Scope Changes check	✅ Passed	문서, 로컬라이제이션, 프론트엔드, 분석 엔진 및 테스트 변경이 모두 핸드오프 왕복 지원 목표와 관련됩니다.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 검증된 리허설 핸드오프 가져오기와 역할 집중 재분석이라는 변경의 핵심을 정확하고 간결하게 설명합니다.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/handoff-import-roundtrip

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

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

opencode-agent · 2026-08-20T07:21:44Z