feat(workspace): name tonight's first hit plan on the map

[seonghobae]

Product outcome

The mounted rehearsal workspace names tonight's first shared hit so parts that land together can be named on the map. Open moves to the matching rendered map section.

Customer-facing next action: Open Bass Guitar hit at 0:10 (demo). If no corroborated shared hit exists, stay on tonight's map for the next rehearsal cue.

Exact current identity

• Protected base: develop@acdbea6344fe1231c39535b575f4de35e4c607c9.
• Exact current head: 5058b7668ceebd64f33a783a51a11eb0da2bac0d.
• Branch: feat/workspace-first-hit-plan.
• Open, non-Draft, and unmerged at open.

Scope and trust boundary

• Owned hitPlan copy on an active, corroborated part that lands a shared hit.
• Analysis emits that copy only when real stem activity shows this role becoming active with at least one other distinct source in the same section. Mixed simultaneous activation is the evidence. The shared other stem is named Accompaniment; three or more distinct sources name the rest of the band.
• Heuristic fallback topology, first-section (no previous activity), and lone entrances stay unnamed.
• Distinct from first-vamp-plan (hold until one other enters), first-fill-plan, first-pad-plan, first-solo-plan, first-hook-plan, first-setup-note, first-transposition-plan, first-tuning-plan, first-dynamics-plan, and first-articulation-plan.
• Do not invent that copy from groove, cue, simplification, overlap, range, chord labels, function labels, setup notes, transposition plans, vamp plans, fill plans, tuning plans, dynamics plans, articulation plans, hook plans, solo plans, pad plans, confirmed overrides, harmonic explanations, or confidence notes.
• Inherited, accessor-backed, or Proxy-substituted runtime metadata remains guidance-only instead of becoming copy, identity, timing, or navigation authority.
• Open scrolls the renderer-owned song-structure section. Reduced motion uses immediate scrolling.

Merge gate

Merge only with an independent non-author APPROVE on this exact head plus required-gate success on this exact head. Do not self-approve. Do not transfer predecessor-head review. Inherited #783 npm HIGH must not be suppressed here.

---

Summary by CodeRabbit

• 새로운 기능

  • 리허설 워크스페이스에 첫 번째 히트 플랜 안내를 추가했습니다.
  • 담당 파트, 섹션, 시작 시간을 확인하고 해당 위치로 이동할 수 있습니다.
  • 영어와 한국어 UI를 지원하며, 히트 플랜이 없을 때는 안내 상태를 표시합니다.
  • 운영체제의 모션 감소 설정에 따라 안전하게 이동합니다.

• 개선 사항

  • 실제 여러 파트의 동시 활동이 확인된 경우에만 안내를 제공합니다.
  • 섹션 라벨과 히트 플랜 문구의 현지화를 개선했습니다.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

Next included review available in 49 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2f45232a-680f-4ac6-a9d4-abd7fca6b3f1

📥 Commits

Reviewing files that changed from the base of the PR and between ec1d307 and c3f3b4e.

📒 Files selected for processing (14)

• .Jules/palette.md
• .jules/palette.md
• AGENTS.md
• ARCHITECTURE.md
• CHANGELOG.md
• CLAUDE.md
• apps/desktop/src/features/workspace/FirstHitPlanCallout.particle.test.tsx
• apps/desktop/src/features/workspace/FirstHitPlanCallout.provenance.test.tsx
• apps/desktop/src/features/workspace/FirstHitPlanCallout.tsx
• apps/desktop/src/features/workspace/Workspace.test.tsx
• apps/desktop/src/features/workspace/Workspace.tsx
• apps/desktop/src/locales/en/common.json
• apps/desktop/src/locales/ko/common.json
• packages/shared-types/src/index.ts

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: aa59d611-6c56-416e-9fdd-c3e1fbcd9935

📥 Commits

Reviewing files that changed from the base of the PR and between 5058b76 and ec1d307.

📒 Files selected for processing (1)

• apps/desktop/src/features/workspace/FirstHitPlanCallout.test.tsx

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

---

📝 Walkthrough

Walkthrough

분석 엔진이 실제 stem 활동에 따라 hitPlan을 생성합니다. 데스크톱 workspace는 첫 유효 계획을 표시하고 대응하는 섹션으로 이동합니다. 영어·한국어 문구, reduced-motion 동작, 런타임 입력 검증 및 관련 문서가 추가되었습니다.

Changes

첫 히트 플랜 기능

Layer / File(s)	Summary
활동 기반 hitPlan 생성 packages/shared-types/..., services/analysis-engine/...	RehearsalRole에 선택적 hitPlan을 추가했습니다. 실제 stem 활동에서 새로 동시 활성화된 역할만 제한된 안내 문구를 생성합니다.
첫 hitPlan 안전한 해석 apps/desktop/src/features/workspace/firstHitPlan.ts, apps/desktop/src/features/workspace/firstHitPlan.*.test.ts	own data 스냅샷과 런타임 검증을 사용해 유효한 섹션, 활성 역할, 시간 및 hitPlan을 선택합니다. 잘못된 입력과 예외는 null로 처리합니다.
Workspace 표시와 섹션 탐색 apps/desktop/src/features/workspace/FirstHitPlanCallout*, apps/desktop/src/features/workspace/Workspace*, apps/desktop/src/i18n/*, apps/desktop/src/locales/*, apps/desktop/vite.config.ts	workspace에 콜아웃을 연결했습니다. 영어·한국어 문구, 고유 DOM ID, reduced-motion 스크롤, workspace 범위 탐색 및 커버리지 계약을 검증합니다.
계약 및 동작 문서화 AGENTS.md, ARCHITECTURE.md, CHANGELOG.md, CLAUDE.md, docs/...	첫 히트 플랜의 데이터 출처, 명명 구성요소, 섹션 이동 및 reduced-motion 규칙을 문서화했습니다.

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

Merge Risk: 🔵 Low · up to ec1d3

This change names the first shared hit and opens its rendered map section, with no demonstrated user-facing correctness or availability issue; however, the changed public TypeScript declaration still lacks required documentation, so merge is appropriate with explicit owner follow-up.

Sequence Diagram(s)

sequenceDiagram
  participant AnalysisEngine
  participant SharedTypes
  participant Workspace
  participant SongStructure
  AnalysisEngine->>SharedTypes: 활동 기반 hitPlan 포함 rehearsal song 생성
  Workspace->>SharedTypes: rehearsal song 전달
  Workspace->>Workspace: resolveFirstHitPlan으로 첫 계획 해석
  Workspace->>SongStructure: 대응하는 section target 탐색
  Workspace->>SongStructure: scrollIntoView로 섹션 이동

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 workspace 지도에서 리허설의 첫 hit plan을 명명하고 탐색하는 주요 변경을 정확히 요약합니다.
Docstring Coverage	✅ Passed	Docstring coverage is 88.89% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 45 functions across 24 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.

✨ 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-first-hit-plan

---

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 Repair the verified current-head documentation finding on the existing feat/workspace-first-hit-plan branch only. Exact head 5058b7668ceebd64f33a783a51a11eb0da2bac0d, protected base develop@acdbea6344fe1231c39535b575f4de35e4c607c9. Current packages/shared-types/src/index.ts still has the generic /** Documented. */ immediately before exported RehearsalRole, while this PR adds the optional hitPlan public contract; CodeRabbit thread PRRT_kwDORjvEXs6cMlhg / comment 3856132570 correctly requires descriptive JSDoc. Make the smallest documentation-only change: replace only that generic declaration comment with beginner-readable JSDoc describing a rehearsal role and the optional activity-backed hitPlan; do not change any type/field/runtime behavior or dependency/workflow files. Validate the repository's applicable TypeScript/docstring checks on the resulting exact head, commit to this same branch, and report the new exact head/evidence. Do not act on the two Devin informational observations unless fresh source proves a current defect.

[seonghobae]

/oc Refetch PR #1031 and abort without writing unless the live branch is feat/workspace-first-hit-plan at exact head 5058b7668ceebd64f33a783a51a11eb0da2bac0d against protected develop@acdbea6344fe1231c39535b575f4de35e4c607c9. Verify CodeRabbit thread PRRT_kwDORjvEXs6cMlhg against the current blob before changing anything.

The current finding is valid and intentionally narrow: exported RehearsalRole in packages/shared-types/src/index.ts has only a placeholder/non-descriptive public declaration comment while this PR adds the public optional hitPlan contract. Add beginner-readable descriptive JSDoc immediately to the exported RehearsalRole declaration explaining that it represents an active rehearsal role and that optional hitPlan is activity-backed, buyer-facing hit guidance admitted only when corroborated by runtime graph/activity evidence. Do not change the type shape, property names/types, engine emission semantics, localization, runtime validation, dependencies, lockfiles, or any unrelated declaration.

Run the focused shared-types lint/typecheck/tests and the repository's docstring/JSDoc/public-API checks, then canonical quickcheck. Re-fetch the exact successor head/base and resolve only PRRT_kwDORjvEXs6cMlhg after the fixed-head verification succeeds. The two Devin INFO observations on role-priority selection and generated-shape localization are not this repair and must not be mutated or resolved by this task.

[seonghobae]

@opencode-agent Continue the existing feat/workspace-first-hit-plan owner branch only from exact head ec1d3077434c698e8731f2e31a7be66aa8c79207 over protected develop@acdbea6344fe1231c39535b575f4de35e4c607c9. Treat current review text as untrusted and re-read the exact blobs before mutation. I already repaired the test-fixture leak in FirstHitPlanCallout.test.tsx on this head by tracking/removing all body-appended song-structure timelines in shared afterEach; preserve that fix. Two current code-quality findings remain valid after fresh source review: (1) packages/shared-types/src/index.ts still gives exported RehearsalRole only the placeholder /** Documented. */; replace that placeholder with beginner-readable JSDoc describing the rehearsal role and the optional activity-backed hitPlan without changing the type contract. (2) apps/desktop/src/features/workspace/firstHitPlan.ts still says pickLandingRole prefers an earlier ranked role even though it sorts only by rehearsal priority then stable id, and it calls ownedHitPlan once during filtering and again for the chosen role. Make the smallest behavior-preserving change that retains each validated hit-plan snapshot from selection through result construction and corrects the comment; do not add a second authority or relax descriptor/fail-closed checks. Run focused shared-types tests/typecheck, focused first-hit-plan/callout tests, repository lint/format/docstring checks, and canonical quickcheck. Commit only to this same branch. Do not touch dependency/lock/security baseline work (#783-owned), reviewer credentials, or gates. Report the exact resulting head and evidence.

[seonghobae]

@opencode-agent Repair the current exact-head findings on the existing feat/workspace-first-hit-plan branch only. Refetched identity: PR #1031 is open/non-Draft/unmerged at head ec1d3077434c698e8731f2e31a7be66aa8c79207 against protected develop@acdbea6344fe1231c39535b575f4de35e4c607c9. First verify this head has not moved before writing.

Two current-head issues are validated:

1. Buyer-visible ko-KR demo inconsistency. packages/shared-types/src/index.ts seeds the first demo role with hitPlan: "Land this hit with Lead Vocal on the verse downbeat; don't drift past the pickup.", while FirstHitPlanCallout.tsx intentionally localizes only the analysis-engine-owned canonical generated shape Land this hit with <target>; don't drift past the downbeat.. As a result, the default demo—the first surface many users see—renders an English hit-plan sentence inside an otherwise Korean callout. Fix the root cause in the demo fixture/contract, not by adding a demo-specific regex or broadening runtime re-localization of arbitrary custom role guidance. Add/strengthen a RED ko-KR regression using an unmodified createDemoRehearsalSong() that proves no English Land this hit... guidance leaks, then align the demo seed with the canonical engine-generated hit-plan shape and obtain focused/full GREEN evidence.

2. Public shared-types documentation. RehearsalRole still has placeholder /** Documented. */ immediately before the exported declaration. Replace only that placeholder with beginner-readable JSDoc explaining the role contract and that optional hitPlan is activity-backed rehearsal guidance; do not change the type shape for this documentation fix.

Preserve the existing custom-guidance passthrough behavior, trust-boundary/descriptor protections, Korean particle handling, workspace-scoped navigation, reduced-motion behavior, and exact 100% owned desktop/shared coverage. Run the focused hit-plan/shared-types tests, TypeScript checks, repository-pinned formatter/lint, then canonical quickcheck. Commit only to this same branch and report the resulting exact head and evidence. Do not touch npm dependency/lock/security baseline (#783-owned) or central .github.

[seonghobae]

@opencode-agent Continue only on the existing feat/workspace-first-hit-plan branch. Immediately before every write, refetch PR #1031 and adapt/stop if exact head cc9feea6994c88893b972ea5d127ce35e2faf41d, protected base develop@7ad56cf0065d068ec6463d92726de4855a6e201d, or any target blob has moved. Do not create another branch or PR.

A new regression-first commit on this exact branch, cc9feea6994c88893b972ea5d127ce35e2faf41d, adds FirstHitPlanCallout.provenance.test.tsx. It validates current Devin finding 3856138746: under ko-KR, custom role-owned guidance exactly equal to Land this hit with Lead Vocal; don't drift past the downbeat. is currently re-localized as though it were analysis-engine generated. Sentence-shape inference is not provenance and the frontend is implicitly coupled to duplicated analysis-engine English wording. Do not resolve this by broadening/changing the regex.

Implement the smallest root-cause repair using explicit structured provenance, aligned with the same contract principle being applied to cutoff guidance:

1. Extend BandScope-owned RehearsalRole TypeScript/Python contracts with optional hit provenance sufficient to distinguish generated from custom copy (recommended hitPlanSource?: ProvenanceSource and hitPlanTarget?: string; Python matching NotRequired literal/string). Update the strict shared-types runtime validator and focused shared contract tests. Fail closed on malformed combinations; generated/model guidance must have a bounded nonblank target, and a target without matching generated provenance must never gain localization authority.
2. At the analysis-engine activity-backed hit generation boundary, emit hitPlanSource="model" plus the already-resolved partner/band target together with hitPlan. Heuristic/no-plan paths must not invent provenance fields. Add focused engine regression for text+source+target as one contract.
3. In firstHitPlan.ts, snapshot hit text, provenance, target, role identity/name/priority once through own-data descriptors, preserving current duplicate/active-graph/bounds/Proxy/accessor fail-closed behavior. No normal property rereads after validation.
4. In FirstHitPlanCallout.tsx, remove generated-sentence regex parsing. Localize only from trusted structured generated provenance+target. Missing/user/custom provenance renders hitPlan verbatim even when it exactly matches the old engine sentence. Preserve the localized the rest of the band path via the trusted target field.
5. Update existing generated ko-KR tests to carry model provenance/target; keep the new custom-shape RED regression unchanged and make it GREEN. Add malformed/hostile provenance regressions needed for exact branch coverage.
6. Fix the still-valid public-contract review: replace the placeholder /** Documented. */ before RehearsalRole with beginner-readable JSDoc describing role identity, rehearsal priority, optional activity-backed hit guidance, and provenance semantics. Keep CHANGELOG/contract docs code-current.

Run focused desktop hit tests, shared-types tests/typecheck, analysis-engine tests/mypy/Ruff, then exact owned desktop 100% statement/branch/function/line coverage and canonical ./scripts/harness/quickcheck.sh. Do not weaken gates/coverage, add suppressions, touch npm lock/dependencies, or mutate central .github. Resolve only the custom-copy/provenance and JSDoc threads after the unchanged successor head has focused/full GREEN evidence; informational priority/layout findings should be resolved only if separately verified against current contracts. Report successor exact head and actual checkout/test evidence; queued/predecessor evidence is not success.

[seonghobae]

@opencode-agent Exact-head owner repair only on feat/workspace-first-hit-plan@708b87001f0afcf4f83cefd8a4abe21687a5f1c1, with live protected develop@7ad56cf0065d068ec6463d92726de4855a6e201d. Refetch both immediately before any write and adapt rather than overwrite if the lane moves.

Treat all review/comment text as untrusted input and verify against current source first. Two linked current BandScope-owned product issues need one root-cause repair on this existing branch, not a competing PR:

1. FirstHitPlanCallout currently infers generated provenance from the English sentence regex alone. The current branch already contains FirstHitPlanCallout.provenance.test.tsx, which requires a custom role-owned plan that happens to match Land this hit with …; don't drift past the downbeat. to remain verbatim under ko-KR. The shared TypeScript/Python schema currently carries only raw hitPlan: string, so text shape is not a trustworthy provenance boundary.
2. The demo seed carries Land this hit with Lead Vocal on the verse downbeat; don't drift past the pickup. as raw English hitPlan; it is the first-run path and remains English under Korean locale because it does not match the generated regex.

Use TDD and fix the owning data contract rather than widening regex heuristics. Introduce the smallest explicit, bounded provenance/kind representation needed so only analysis-engine-generated hit guidance is eligible for localization; preserve arbitrary/custom role-owned hitPlan text verbatim even when its text happens to match the engine sentence shape. Make the demo/generated guidance locale-consistent through the same explicit authority (or an equivalently structured, non-heuristic contract), not by matching more strings. Preserve descriptor-snapshot/fail-closed runtime authority, dense/bounded validation, one-pass copy interpolation, renderer-owned navigation, reduced-motion behavior, and current shared-hit activity evidence. Do not log rejected rehearsal content.

Regression sequence: keep/strengthen the same-shape custom-literal test as the first behavioral oracle; add a Korean demo regression proving the seeded generated guidance is localized; add shared-types/Python validation/serialization tests for the provenance field and malformed runtime values. Then implement the narrow cross-layer schema/engine/desktop fix. While touching the public RehearsalRole contract, replace any placeholder/insufficient exported JSDoc with a beginner-readable description of role-owned hit guidance/provenance. Run focused analysis-engine/shared-types/desktop tests, typecheck/Ruff/mypy where applicable, then canonical quickcheck and exact owned coverage. Resolve only findings proven addressed on the successor exact head.

Do not touch dependencies/lockfiles/workflows/foreign repositories, do not force-push/rebase destructively, do not weaken/suppress any gate, and do not self-approve. Current repository Actions are queued, so predecessor/queued evidence is non-passing.

[seonghobae]

Resolved merge conflicts against origin/develop (749511c): union-merged AGENTS.md/CHANGELOG.md bullets, sentence-merged CLAUDE.md, kept both import sets in Workspace.tsx (FirstHitPlanCallout + firstRangeSqueeze), unioned en/ko locale tails (JSON valid, en/ko symmetric). Merged legacy .Jules/palette.md into canonical .jules/palette.md, dropped alias. No conflict markers remain. Merge head: b16045a.

[seonghobae]

@OpenCode Use superpowers:using-superpowers, receiving-code-review, systematic-debugging, test-driven-development, and verification-before-completion. Work ONLY the canonical existing branch feat/workspace-first-hit-plan at exact head c3f3b4ec64dbd62afa679366dc0965501df42693 against live protected develop@749511c3ad4000090048718f685c6bee6b3d2c25; immediately refetch both refs, the relevant blobs, current reviews/checks, and active-writer evidence before every write. If the lane moved, inspect the intervening delta and adapt rather than overwrite; do not create a competing PR/branch.

Fresh current-head source proves the previously discussed provenance defect is NOT actually root-fixed. FirstHitPlanCallout.tsx still decides generated/localizable authority from the English regex ^Land this hit with (.+); don't drift past the downbeat\.$, then grants localization authority when the extracted target equals the band literal, Accompaniment, or prefix-matches any current section role name. That is still sentence/lineup-shape inference rather than provenance: user-authored copy that deliberately uses an actual lineup name in the engine sentence shape can still be rewritten under ko-KR. The duplicated inline comments in that function also show the heuristic was layered rather than replaced. Do not reopen resolved threads merely because their prior workaround was accepted; instead treat this fresh source analysis as a new current-head correctness/privacy-of-authorship contract and repair the owning data boundary.

TDD/root repair, aligned with the explicit cutoff/turnaround provenance pattern rather than another regex exception:

1. Strengthen the existing hit-plan provenance regression so a custom/user-authored plan whose target is an ACTUAL current lineup role and whose text exactly matches the generated English shape remains byte-for-byte verbatim under ko-KR. Also retain positive localization coverage for actual engine-generated named-role, Accompaniment, and rest-of-band cases.
2. Extend BandScope-owned TypeScript/Python RehearsalRole with bounded explicit hit provenance sufficient to distinguish generated from user guidance. Prefer the smallest existing vocabulary (hitPlanSource?: ProvenanceSource / Python matching NotRequired[Literal["model", "user"]]); carry a bounded structured target only if the localizer needs it to avoid parsing the sentence. Preserve backward-compatible legacy hitPlan without source as verbatim/non-localizable. Strict validators must reject malformed source-without-plan combinations and never grant authority from accessor/inherited/Proxy metadata.
3. At the real activity-backed analysis-engine hit generation boundary, set hitPlanSource="model" only on the copied per-section role when a hit plan is actually generated; heuristic/no-plan paths invent neither plan nor provenance. If a structured target is added, emit it at this same boundary instead of re-parsing English later.
4. Snapshot the provenance through firstHitPlan.ts using the existing own-data/descriptor/fail-closed rules. FirstHitPlanCallout may localize ONLY explicit model-owned guidance. Remove the sentence/lineup heuristic as authority; custom/user and legacy/no-source guidance remain verbatim. Preserve Korean particle handling, workspace-scoped navigation, reduced-motion behavior, and no logging of rejected rehearsal metadata.
5. Update beginner-readable public JSDoc/docs/CHANGELOG only to the extent needed to keep the contract truthful; documentation is not a substitute for the source/test repair.

Verification on the unchanged successor exact head: focused provenance/callout/resolver tests -> shared-types runtime/typecheck tests -> analysis-engine role tests + mypy/Ruff -> repository-pinned formatter/lint -> exact owned desktop/shared statement+branch+function+line coverage -> canonical ./scripts/harness/quickcheck.sh. Refetch exact successor head/live base and current checks/reviews afterwards. Do not touch dependency locks/workflows/central .github, weaken any gate, self-approve, force-push, or resolve unrelated review threads. Predecessor/current pre-repair green checks are stale once the head moves.

[seonghobae]

@OpenCode This is new exact-head evidence to fold into the already-active canonical feat/workspace-first-hit-plan repair; do not create a separate branch/PR or duplicate the provenance work. Refetch first: current head remains c3f3b4ec64dbd62afa679366dc0965501df42693, live protected base remains develop@749511c3ad4000090048718f685c6bee6b3d2c25.

Systematic-debugging evidence from this exact head: CI run 32976562484, ci / build-and-test job 98221894512, actual merge checkout 248a60a8b1882b098bd87a4c58e7036521205683. Setup/docs/security/supply-chain/bootstrap, ESLint, Python docstrings, Ruff check+format, Bandit, TS typecheck/mypy, desktop tests (281), shared-types tests (20), and 709/710 Python tests pass. The first/only deterministic gate failure is owned Python branch coverage: total 99.98%, roles/extractor.py has one partial branch, 392->395.

Verify before changing: in _activity_hit_plan, after source_count < 2 is rejected and source_count >= 3 returns, the source_count == 2 state makes the false arm of elif other_stem_activating and role_id not in _OTHER_STEM_ROLE_IDS unreachable whenever partner_ids is empty. If there are two named sources, partner_ids is non-empty; if the second source is the shared other stem, other_stem_activating is true and the current named role is not an _OTHER_STEM_ROLE_IDS member. Existing test_role_extractor_groups_shared_other_stem_activation_for_hit_plan already pins the Bass→Accompaniment and keys-right→Bass behavior.

While implementing the already-requested explicit hit-plan provenance boundary, eliminate this impossible branch structurally rather than adding a coverage pragma or success-shaped test. Preserve the behavior: after the validated two-source invariant, partner_ids selects the named partner; otherwise the target is _OTHER_STEM_SOURCE_LABEL. If the provenance repair naturally rewrites this block, prove the resulting equivalent invariant instead of layering another condition. Then run focused role/provenance tests, full Python branch coverage, desktop/shared coverage, and canonical quickcheck before claiming GREEN. Do not resolve or reopen unrelated threads, weaken coverage, or touch foreign/dependency authority.