feat(workspace): lead the handoff with tonight's first range

[seonghobae]

Product outcome

The ready workspace already names tonight's first playable range. This PR carries that same range into the metadata handoff so a bandmate can act on it immediately. When a valid named playable span exists, the artifact puts a structured firstAction object immediately after song identity; if the range cannot be named safely, firstAction is omitted rather than invented.

The download control names the customer action rather than internal workflow jargon:

• English: Download tonight's first-range handoff
• Korean: 오늘 첫 연주 구간 공유 파일 다운로드

Exact current identity

• Protected target: develop@749511c3ad4000090048718f685c6bee6b3d2c25
• Exact current head: dbd63a71277d483a2accd7bfbae8bd5119c8d331
• Branch: feat/workspace-handoff-first-action

Predecessor-head checks and reviews are historical only.

Current exact scope

• firstHandoffAction uses the same playable-span authority as the ready map and fails closed on malformed runtime collections, blank ids, inverted ranges, and non-form section labels.
• The handoff remains full-band; changing the transient workspace role filter does not change the exported lead.
• Metadata handoff v1 remains valid without firstAction; v2 requires a semantically valid firstAction whose section and role ids, labels/names, and range still match the referenced artifact payload.
• Source paths and transcription data remain excluded. Formula-shaped role names remain literal JSON data.
• English/Korean CTA regressions and the App integration selector use the customer-facing first-range wording.

Exact-head RCA and repair

Hosted release run 33463347083, job 99718019113, checked out synthetic merge c25afe0d8d940af78210d7f64507e06b8928008e from predecessor head 750c276b4ee6de22028716f3cb4183c65b07248b and protected base 749511c3ad4000090048718f685c6bee6b3d2c25. Toolchain/bootstrap, frozen npm ci, documentation, security, supply-chain, lint, and typecheck passed before ./scripts/harness/quickcheck.sh exposed two stale test fixtures after the v2 semantic-reference validator was strengthened.

Current head dbd63a71277d483a2accd7bfbae8bd5119c8d331 repairs only those inconsistent fixtures:

1. The desktop formula-shaped-role export regression now gives the referenced source role the same literal formula-shaped display name as firstAction.roleName. The test still proves JSON does not interpret or sanitize the literal, while the production validator remains strict.
2. The shared-types unsupported-version regression now uses actually unsupported artifact version 3. Version 2 is intentionally supported and its missing-firstAction failure remains covered by the dedicated metadata-handoff versioning tests.

No production validator, schema authority, dependency, workflow, or security gate was weakened. The detached candidate commit was compared with 750c276… before the branch ref moved; only these two test-fixture edits were present. The branch update was a non-force fast-forward after a fresh head/base/writer-state refetch.

DDD / path boundary

No restructuring is warranted for this repair. Wire-contract admission remains owned by packages/shared-types/src/metadata-handoff.ts; desktop export remains an adapter under apps/desktop/src/lib. The stale fixtures were repaired in their existing owning test suites rather than moving validation into the UI or duplicating contract authority.

Security / privacy boundary

Untrusted analysis payloads flow through firstHandoffAction → parseMetadataHandoffArtifact → JSON.stringify → local download Blob. The artifact does not dereference files or URLs. Missing, malformed, or semantically inconsistent first-action data fails closed, and source paths are not exported.

Dependency / supply chain

No dependency, lockfile, model, or workflow change is introduced. Canonical #783 remains protected-branch dependency-security truth; this branch does not suppress inherited findings.

Verification contract

Fresh repository workflows are running for exact head dbd63a71277d483a2accd7bfbae8bd5119c8d331; queued or in-progress work is non-passing and no predecessor result transfers.

Do not merge until this unchanged exact head has every applicable repository and central CI/build/release/security/SAST/SBOM/supply-chain/coverage/review gate terminal-success, zero valid unresolved findings, and a qualifying independent non-author approval under live protection. Queued, pending, neutral, skipped-required, cancelled, failed, predecessor-head, protected-base, model-only, self/author, synthetic, or administrative-bypass evidence is non-passing.

Closes no issue. Complements #739/#740 by making the exported metadata handoff name tonight's concrete playable-range action rather than an internal workflow label.

---

Summary by CodeRabbit

• 새 기능

  • 워크스페이스에서 오늘 첫 연주 가능 구간을 확인하고 공유용 JSON을 다운로드할 수 있습니다.
  • 파일에 첫 행동, 섹션, 역할, 음역 및 충돌 정보가 포함됩니다.
  • 유효한 구간이 없으면 첫 행동 정보가 자동으로 제외됩니다.
  • 영어와 한국어 다운로드 안내를 지원합니다.

• 개선 사항

  • 기존 핸드오프 형식과 새 형식의 호환성을 유지합니다.

• 문서

  • 핸드오프 형식 및 리허설 결과물 안내를 업데이트했습니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 1ac5933c-6b09-4e0d-83a2-54543fa2cf86

📥 Commits

Reviewing files that changed from the base of the PR and between 750c276 and dbd63a7.

📒 Files selected for processing (2)

• apps/desktop/src/lib/export.test.ts
• packages/shared-types/test/index.test.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

첫 번째 유효한 playable range를 firstAction으로 선택합니다. 유효한 액션이 있으면 metadata handoff를 v2로 내보냅니다. 없으면 v1 형식을 유지합니다. Workspace 다운로드, 로케일, 문서 및 테스트를 갱신합니다.

Changes

첫 실행 핸드오프 계약

Layer / File(s)	Summary
공유 타입 및 firstAction 계약 packages/shared-types/src/*, packages/shared-types/test/*, apps/desktop/src/lib/export-versioning.test.ts	공유 타입을 모듈로 분리했습니다. metadata handoff에 v1/v2 타입과 firstAction 검증을 추가했습니다. 두 버전의 파싱과 재분석 요청 호환성을 테스트합니다.
첫 playable range 선택 apps/desktop/src/features/workspace/firstHandoffAction.ts, apps/desktop/src/features/workspace/firstHandoffAction.test.ts	유효한 playable range를 탐색합니다. overlap warning 후보를 우선 선택합니다. 잘못된 런타임 구조와 표시 이름을 검증합니다.
JSON 생성 및 다운로드 연결 apps/desktop/src/lib/export.ts, apps/desktop/src/lib/export.test.ts, apps/desktop/src/features/workspace/Workspace.tsx, apps/desktop/src/features/workspace/Workspace.test.tsx, apps/desktop/src/features/workspace/Workspace.handoffExport.test.tsx, apps/desktop/src/App.test.tsx, apps/desktop/src/locales/*/common.json	firstAction이 있으면 v2 JSON을 생성합니다. 없으면 v1 JSON에서 해당 필드를 생략합니다. Workspace 다운로드 버튼과 영어·한국어 라벨을 갱신했습니다.
기능 설명 및 리허설 문서 AGENTS.md, ARCHITECTURE.md, CHANGELOG.md, CLAUDE.md, docs/architecture/overview.md, docs/doctoring/handoff-first-action.md	첫 액션 다운로드와 v1/v2 handoff 동작을 프로젝트 문서, 변경 기록, 아키텍처 문서에 반영했습니다.

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

Merge Risk: 🔵 Low · up to dbd63

The PR adds validated metadata handoff behavior with no confirmed security or deployment issue, but four reported ESLint errors in the shared contract code may still fail the lint gate; merge is reasonable with explicit owner confirmation or follow-up.

Sequence Diagram(s)

sequenceDiagram
  participant Workspace
  participant firstHandoffAction
  participant createMetadataHandoffArtifact
  participant Browser
  Workspace->>firstHandoffAction: 곡의 첫 playable range 조회
  firstHandoffAction-->>Workspace: firstAction 또는 null 반환
  Workspace->>createMetadataHandoffArtifact: song과 firstAction 전달
  createMetadataHandoffArtifact-->>Workspace: v1 또는 v2 handoff JSON 반환
  Workspace->>Browser: Blob 다운로드 시작

Loading

Suggested reviewers: copilot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 95.83% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 72 functions across 14 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	PR 제목은 메타데이터 핸드오프에 오늘 밤의 첫 연주 가능 구간을 우선 포함하는 주요 변경을 정확하고 간결하게 설명합니다.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/workspace-handoff-first-action

---

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

[seonghobae]

@opencode-agent Become the sole writer for canonical BandScope branch feat/workspace-handoff-first-action only while it still resolves to exact head 9a5456600fb0ad04d4c1a7f5cfdfbc42fdc8c55e and protected develop still resolves to 749511c3ad4000090048718f685c6bee6b3d2c25. Apply superpowers:using-superpowers, receiving-code-review, systematic-debugging, test-driven-development, and verification-before-completion. Refetch the exact head/base, the current blobs for packages/shared-types/src/index.ts, packages/shared-types/test/index.test.ts, apps/desktop/src/lib/export.ts, apps/desktop/src/lib/export.test.ts, and current review thread PRRT_kwDORjvEXs6dwQJ_ immediately before writing. Abort/adapt if the branch/base or those owning blobs moved. Do not create a competing branch/PR, force-push, destructively rebase, weaken gates, or touch foreign repositories.

The Devin finding is valid against the exact current head: protected develop's shipped v1 parser allowlists only artifactKind, artifactVersion, createdAt, workspace, song, sections, and sourceAssets, while this head emits a new top-level firstAction but still claims artifactVersion: 1. That silently changes the v1 wire contract and older deployed v1 recipients reject the artifact. Do not loosen the v1 parser or make it accept arbitrary unknown keys merely to keep this green.

TDD first. Add the smallest RED contract tests proving: (1) legacy v1 handoffs without firstAction remain accepted unchanged; (2) a first-action handoff cannot masquerade as v1; (3) the current parser accepts the new explicitly versioned artifact; (4) malformed/unknown keys and malformed firstAction still fail closed. Preserve exact ordering/deterministic JSON tests where they exist. If useful, pin a frozen v1-shaped fixture/helper in tests so the regression demonstrates the wire-contract distinction rather than merely testing current types.

Then make the narrowest causal repair at the handoff contract boundary: introduce an explicit new artifact version for handoffs carrying structured firstAction (prefer v2), model v1 and v2 as a discriminated union, keep current import/parser backward-compatible with legacy v1 and current v2, and ensure export emits v2 iff the structured first action is present (or a consistently versioned v2 contract if that is simpler and better justified). Do not claim old binaries can parse v2; instead preserve semantic version honesty and ensure new BandScope can still open historical v1 artifacts. Update the PR's contract/doctoring/CHANGELOG text only as needed to state the compatibility boundary truthfully.

Run the focused shared-types and export tests first, then desktop typecheck/lint/tests and all applicable repository quick/full verification. Commit the RED regression plus causal repair to this same branch. Reply with predecessor RED evidence, successor exact SHA, focused/full GREEN evidence, and any remaining exact-head gates. Do not resolve PRRT_kwDORjvEXs6dwQJ_ until the successor exact-head tests prove the fix.

[seonghobae]

@opencode-agent Become the sole writer for canonical branch feat/workspace-handoff-first-action only while it still resolves to exact head f958240041894fb633fb1c0df1b3c7363b898f18 and protected develop still resolves to 749511c3ad4000090048718f685c6bee6b3d2c25. Apply superpowers:using-superpowers, receiving-code-review, systematic-debugging, test-driven-development, and verification-before-completion; refetch the exact head/base and current blobs before writing, and abort/adapt if they moved. Do not force-push, rebase, weaken gates, or create another PR.

The user-facing download copy has just been repaired test-first: RED 1e93c5366466d9ea7ebd1cd09eeb76138fa018c3, then English/Korean locale fixes and Workspace assertions through current head. One stale integration assertion remains in apps/desktop/src/App.test.tsx: the current source still clicks /first-action handoff/i, while the actual English accessible name is now Download tonight's first-range handoff. Verify that mismatch against the current blob, change only that stale assertion to the new user-facing name, then run the smallest focused App/Workspace tests plus the branch's normal quick/full verification. Do not alter the locale copy back to satisfy predecessor tests. Report predecessor RED/current successor SHA and exact test evidence. Keep all other current branch semantics, especially v1/v2 handoff compatibility and fail-closed parsing, unchanged.

[seonghobae]

The exact-head writer lease requested above for f958240041894fb633fb1c0df1b3c7363b898f18 is revoked because no acknowledgement or branch movement materialized. Do not mutate this lane from that earlier request. I am reclaiming the BandScope writer lease only after a fresh head/base/blob refetch; any later agent work must first obtain a new exact-head lease.

[seonghobae]

@opencode-agent Become the sole writer for canonical BandScope branch feat/workspace-handoff-first-action only while it still resolves to exact head 750c276b4ee6de22028716f3cb4183c65b07248b and protected develop still resolves to 749511c3ad4000090048718f685c6bee6b3d2c25. Apply superpowers:using-superpowers, systematic-debugging, test-driven-development, and verification-before-completion; refetch the exact branch/base, current blobs, reviews, and workflow evidence immediately before writing. Do not force-push, rebase, weaken gates, touch foreign repositories, or create another PR.

Current exact-head release run 33463347083, job 99718019113, checked out merge SHA c25afe0d8d940af78210d7f64507e06b8928008e = current head merged into the unchanged protected base. Setup, npm 10.9.9/tar 7.5.22 verification, frozen npm ci, docs/security/supply-chain/lint/typecheck all pass. ./scripts/harness/quickcheck.sh then fails in two current tests, both after the v2 semantic-reference validator was strengthened:

1. apps/desktop/src/lib/export.test.ts / leads the handoff JSON with tonight's first action when a lead is provided constructs mockSong whose exported r1 name is Bass but passes firstAction.roleName = '=HYPERLINK("http://evil")'. The current validateFirstActionReferences correctly rejects that internally inconsistent v2 artifact with firstAction.roleName. Preserve the formula-shaped-literal regression by making the exported source role carry that exact literal name too (or an equivalently realistic matching fixture); do not weaken reference validation.
2. packages/shared-types/test/index.test.ts still spreads a valid legacy v1 artifact with artifactVersion: 2 and expects an artifactVersion error. Version 2 is now supported and requires firstAction, so the correct failure is firstAction. Keep the existing test's unsupported-version intent by using an actually unsupported version such as 3, while metadata-handoff-versioning.test.ts continues to cover v2-without-firstAction => firstAction.

These are stale/inconsistent test fixtures, not evidence that the v2 validator should be relaxed. Make the narrowest test-only repair unless fresh source inspection disproves this hypothesis. Run the two focused test files first, then shared-types/desktop tests and normal quick/full verification. Keep DDD placement unchanged: wire-contract validation remains in packages/shared-types/src/metadata-handoff.ts, desktop export remains an adapter. Report the resulting exact SHA and GREEN evidence; predecessor evidence does not transfer.

[seonghobae]

The exact-head @opencode-agent lease requested for 750c276b4ee6de22028716f3cb4183c65b07248b is revoked: a fresh comment/reaction/head refetch shows no acknowledgement, reaction, or branch movement. Do not mutate this lane from that request. I am reclaiming the BandScope writer lease only after refetching the unchanged exact head, protected base, failing test blobs, review state, and exact failing workflow evidence. Any later agent work must first obtain a new lease on the then-current exact head.

[devin-ai-integration]

Devin Review found 1 new potential issue.