feat(workspace): name tonight's first unlogged practice pass

AGENTS.md

@@ -83,7 +83,7 @@ This section applies to any agent (Claude, Codex, Cursor, opencode, ...) working
 - Keep UI and analysis engine decoupled through shared contracts.
 - Prefer minimal, test-first changes for production code.
 - Prefer practical, friendly, rehearsal-first wording over academic or authority-heavy language.
-- Do not reduce the product to a chord analyzer when form, timing, player coordination, playable ranges, simplification, and setup cues are the real rehearsal blockers.
+- Do not reduce the product to a chord analyzer when form, timing, player coordination, playable ranges, simplification, setup cues, and unlogged practice passes are the real rehearsal blockers.
 - Do not frame usability as a reason to accept weak analysis quality; BandScope should aim for both easy use and high accuracy.
 
 ## Safety

ARCHITECTURE.md

@@ -83,6 +83,7 @@ Last updated: 2026-03-11
   - section roadmap with entries, dropouts, pickups, stops, tags, and handoffs
   - groove and timing cues relevant to locking the band together
   - playable ranges and density or overlap warnings, with the ready workspace naming tonight's first span and the next instrument check
+  - the first named part that still has no practice mark, with a record-tonight's-first-pass next action
   - simplification, transposition, capo, tuning, or setup cues where applicable
   - role-specific rehearsal priorities and confidence flags
   - cue-sheet or chart-style exports that summarize the analysis in rehearsal-friendly form

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Added
 
 - Name tonight's first playable range on the ready rehearsal map and tell the player to check that span on their instrument before the section.
+- Name tonight's first unlogged practice pass on the ready rehearsal map and tell the player to select that part and record it.
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
 

CLAUDE.md

@@ -51,7 +51,7 @@ BandScope is a local-first desktop app for rehearsal prep: it turns a song into
 
 Three layers, decoupled through shared contracts:
 
-- `apps/desktop` — Tauri 2 + Vite + React 19 shell (Tailwind 4, Base UI, Storybook). Feature screens live in `src/features/` (home, workspace, chords, ranges, player, settings). The ready workspace names tonight's first playable range and the next instrument check. `src/lib/analysis.ts` and `src/lib/job_runner.ts` call typed Tauri IPC commands, with a browser fallback that serves demo data when not running inside Tauri.
+- `apps/desktop` — Tauri 2 + Vite + React 19 shell (Tailwind 4, Base UI, Storybook). Feature screens live in `src/features/` (home, workspace, chords, ranges, player, settings). The ready workspace names tonight's first playable range, the next instrument check, and the first unlogged practice pass to record. `src/lib/analysis.ts` and `src/lib/job_runner.ts` call typed Tauri IPC commands, with a browser fallback that serves demo data when not running inside Tauri.
 - `apps/desktop/src-tauri/src/main.rs` — the Rust orchestration boundary. Tauri commands (`start_analysis_job`, `get_analysis_job_status`, `select_local_audio_source`, `import_youtube_url`) validate untrusted input (project IDs, file paths, URLs) and spawn the Python engine as a subprocess. There is no loopback HTTP listener and no network path for local analysis.
 - `services/analysis-engine` — Python package `bandscope_analysis` (librosa/numpy). Entry point `cli.py` reads a JSON job request on stdin and prints a structured job-status JSON envelope on stdout (`--progress-jsonl` streams progress lines). `api.py` orchestrates the pipeline across the `separation`, `sections`, `roles`, `chords`, `ranges`, `temporal`, `transcription`, and `youtube` modules.
 

apps/desktop/src/features/workspace/Workspace.test.tsx

@@ -196,6 +196,53 @@ describe("Workspace", () => {
     );
   });
 
+  it("names tonight's first unlogged practice pass and tells the player to record it", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+
+    render(<Workspace song={song} />);
+
+    const callout = screen.getByTestId("first-unlogged-practice");
+    expect(callout).toHaveTextContent("Tonight's first unlogged pass");
+    expect(callout).toHaveTextContent(
+      "Bass Guitar in verse has no practice logged yet. Select that part and record tonight's first pass."
+    );
+  });
+
+  it("asks the selected part to switch when it already has a practice mark", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[2] = {
+      ...song.sections[0]!.roles[2]!,
+      practiceProgress: 80
+    };
+
+    render(<Workspace song={song} />);
+    fireEvent.click(screen.getByRole("tab", { name: "Lead Vocal" }));
+
+    expect(screen.getByTestId("first-unlogged-practice")).toHaveTextContent(
+      "This part already has a practice mark. Switch to the next unlogged part and record tonight's first pass."
+    );
+  });
+
+  it("does not call malformed selected progress a completed practice mark", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[2] = {
+      ...song.sections[0]!.roles[2]!,
+      practiceProgress: 150 as unknown as number
+    };
+
+    render(<Workspace song={song} />);
+    fireEvent.click(screen.getByRole("tab", { name: "Lead Vocal" }));
+
+    const callout = screen.getByTestId("first-unlogged-practice");
+    expect(callout).toHaveTextContent(
+      "Practice progress is inconsistent or invalid for this part. Check its practice mark before treating it as logged."
+    );
+    expect(callout).not.toHaveTextContent("already has a practice mark");
+  });
+
   it("falls back from blank planning copy and tolerates partial collaboration payloads", () => {
     setNavigatorLanguage("en-US");
     const song = createDemoRehearsalSong();

apps/desktop/src/features/workspace/Workspace.tsx

@@ -5,6 +5,7 @@ import { SectionRoadmap } from "./SectionRoadmap";
 import { GrooveMap } from "./GrooveMap";
 import { PracticeProgress } from "./PracticeProgress";
 import { fillRangeCopy, firstRangeSqueeze } from "./firstRangeSqueeze";
+import { fillUnloggedPracticeCopy, firstUnloggedPractice } from "./firstUnloggedPractice";
 import { createTranslator, detectPreferredLocale } from "../../i18n";
 import { generateCueSheetCsv, generateChartSummaryJson, generateMetadataHandoffJson, sanitizeFilename } from "../../lib/export";
 import { Button } from "@/components/ui/button";
@@ -163,6 +164,18 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
         }
       )
     : t("workspaceFirstRangeMissing");
+  const firstUnlogged = useMemo(() => firstUnloggedPractice(song, activeRole), [activeRole, song]);
+  const firstUnloggedCopy =
+    firstUnlogged.kind === "unlogged"
+      ? fillUnloggedPracticeCopy(t("workspaceFirstUnloggedPracticeCheck"), {
+          roleName: firstUnlogged.roleName,
+          sectionLabel: firstUnlogged.sectionLabel
+        })
+      : firstUnlogged.kind === "selected-logged"
+        ? t("workspaceFirstUnloggedPracticeSelectedReady")
+        : firstUnlogged.kind === "all-logged"
+          ? t("workspaceFirstUnloggedPracticeMissing")
+          : t("workspaceFirstUnloggedPracticeUnavailable");
 
   /** Handle the practice progress change internally by immutably updating the song state. */
   const handlePracticeProgressChange = (newProgress: number) => {
@@ -310,6 +323,15 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
             <p className="mt-2 text-sm leading-6 text-slate-100">{firstRangeCopy}</p>
           </section>
 
+          <section
+            className="rounded-2xl border border-indigo-300/20 bg-indigo-300/[0.08] p-4"
+            data-testid="first-unlogged-practice"
+            aria-label={t("workspaceFirstUnloggedPracticeTitle")}
+          >
+            <p className="text-xs font-black uppercase tracking-[0.24em] text-indigo-200">{t("workspaceFirstUnloggedPracticeTitle")}</p>
+            <p className="mt-2 text-sm leading-6 text-slate-100">{firstUnloggedCopy}</p>
+          </section>
+
           <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
             <section className="rounded-2xl border border-cyan-300/20 bg-cyan-300/[0.06] p-4 md:col-span-2">
               <p className="text-xs font-black uppercase tracking-[0.24em] text-cyan-300">{t("workspaceSongTimelineLabel")}</p>
@@ -512,4 +534,4 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
       </Card>
     </div>
   );
-}
+}

apps/desktop/src/features/workspace/firstUnloggedPractice.test.ts

@@ -0,0 +1,181 @@
+import { createDemoRehearsalSong, type RehearsalSong } from "@bandscope/shared-types";
+import { describe, expect, it } from "vitest";
+import {
+  fillUnloggedPracticeCopy,
+  firstUnloggedPractice,
+  hasLoggedPracticeProgress
+} from "./firstUnloggedPractice";
+
+describe("hasLoggedPracticeProgress", () => {
+  it("admits only 0–100 integers", () => {
+    expect(hasLoggedPracticeProgress(0)).toBe(true);
+    expect(hasLoggedPracticeProgress(100)).toBe(true);
+    expect(hasLoggedPracticeProgress(40)).toBe(true);
+    expect(hasLoggedPracticeProgress(undefined)).toBe(false);
+    expect(hasLoggedPracticeProgress(40.5)).toBe(false);
+    expect(hasLoggedPracticeProgress(-1)).toBe(false);
+    expect(hasLoggedPracticeProgress(101)).toBe(false);
+    expect(hasLoggedPracticeProgress("40")).toBe(false);
+  });
+});
+
+describe("firstUnloggedPractice", () => {
+  it("names the first demo part that still has no practice mark", () => {
+    expect(firstUnloggedPractice(createDemoRehearsalSong())).toEqual({
+      kind: "unlogged",
+      sectionLabel: "verse",
+      roleName: "Bass Guitar"
+    });
+  });
+
+  it("skips parts that already own a 0–100 mark", () => {
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0] = {
+      ...song.sections[0]!.roles[0]!,
+      practiceProgress: 40
+    };
+
+    expect(firstUnloggedPractice(song)).toEqual({
+      kind: "unlogged",
+      sectionLabel: "verse",
+      roleName: "Keyboard 1 Right Hand"
+    });
+  });
+
+  it("limits the callout to the selected unlogged part", () => {
+    expect(firstUnloggedPractice(createDemoRehearsalSong(), "lead-vocal")).toEqual({
+      kind: "unlogged",
+      sectionLabel: "verse",
+      roleName: "Lead Vocal"
+    });
+  });
+
+  it("distinguishes a selected part with a trustworthy practice mark", () => {
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[2] = {
+      ...song.sections[0]!.roles[2]!,
+      practiceProgress: 0
+    };
+
+    expect(firstUnloggedPractice(song, "lead-vocal")).toEqual({ kind: "selected-logged" });
+  });
+
+  it("skips malformed marks and duplicate role ids inside one section", () => {
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[0] = {
+      ...song.sections[0]!.roles[0]!,
+      practiceProgress: 150 as unknown as number
+    };
+    song.sections[0]!.roles[1] = {
+      ...song.sections[0]!.roles[1]!,
+      id: "bass-guitar"
+    };
+
+    expect(firstUnloggedPractice(song)).toEqual({
+      kind: "unlogged",
+      sectionLabel: "verse",
+      roleName: "Lead Vocal"
+    });
+  });
+
+  it("treats the same named role across sections as one part", () => {
+    const song = createDemoRehearsalSong();
+    const verse = song.sections[0]!;
+    song.sections.push({
+      ...structuredClone(verse),
+      id: "chorus-1",
+      label: "chorus",
+      timeRange: { start: 30, end: 50 }
+    });
+
+    expect(firstUnloggedPractice(song)).toEqual({
+      kind: "unlogged",
+      sectionLabel: "verse",
+      roleName: "Bass Guitar"
+    });
+  });
+
+  it("reports unavailable when repeated section copies disagree about selected practice state", () => {
+    const song = createDemoRehearsalSong();
+    const verse = song.sections[0]!;
+    const chorus = structuredClone(verse);
+    chorus.id = "chorus-1";
+    chorus.label = "chorus";
+    chorus.timeRange = { start: 30, end: 50 };
+    chorus.roles[0] = {
+      ...chorus.roles[0]!,
+      practiceProgress: 40
+    };
+    song.sections.push(chorus);
+
+    expect(firstUnloggedPractice(song, "bass-guitar")).toEqual({ kind: "unavailable" });
+  });
+
+  it("reports unavailable for a selected malformed practice mark instead of claiming it is logged", () => {
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles[2] = {
+      ...song.sections[0]!.roles[2]!,
+      practiceProgress: 150 as unknown as number
+    };
+
+    expect(firstUnloggedPractice(song, "lead-vocal")).toEqual({ kind: "unavailable" });
+  });
+
+  it("returns all-logged only when every named role has trustworthy consistent marks", () => {
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles = song.sections[0]!.roles.map((role, index) => ({
+      ...role,
+      practiceProgress: index * 40
+    }));
+
+    expect(firstUnloggedPractice(song)).toEqual({ kind: "all-logged" });
+  });
+
+  it("reports unavailable rather than all-logged when the remaining evidence is malformed", () => {
+    const song = createDemoRehearsalSong();
+    song.sections[0]!.roles = song.sections[0]!.roles.map((role, index) => ({
+      ...role,
+      practiceProgress: index === 2 ? (150 as unknown as number) : index * 40
+    }));
+
+    expect(firstUnloggedPractice(song)).toEqual({ kind: "unavailable" });
+  });
+
+  it("rejects inherited identity and practice evidence", () => {
+    const inheritedRole = Object.create({
+      id: "ghost-role",
+      name: "Ghost Role",
+      practiceProgress: 40
+    }) as Record<string, unknown>;
+    const song = {
+      sections: [
+        {
+          label: "verse",
+          roles: [inheritedRole]
+        }
+      ]
+    } as unknown as RehearsalSong;
+
+    expect(firstUnloggedPractice(song)).toEqual({ kind: "unavailable" });
+  });
+
+  it("fails closed on malformed runtime roots and collections", () => {
+    for (const malformed of [null, {}, { sections: null }, { sections: [null] }]) {
+      expect(firstUnloggedPractice(malformed as unknown as RehearsalSong)).toEqual({ kind: "unavailable" });
+    }
+  });
+});
+
+describe("fillUnloggedPracticeCopy", () => {
+  it("replaces tokens without inheriting object members", () => {
+    expect(
+      fillUnloggedPracticeCopy("{roleName} in {sectionLabel} before {sectionLabel}.", {
+        roleName: "Bass Guitar",
+        sectionLabel: "verse"
+      })
+    ).toBe("Bass Guitar in verse before verse.");
+    expect(fillUnloggedPracticeCopy("Check {toString} before {missingToken}.", { roleName: "Bass Guitar" })).toBe(
+      "Check {toString} before {missingToken}."
+    );
+  });
+});