test(analysis): govern real YouTube known-stem benchmark

AGENTS.md

@@ -3,6 +3,9 @@
 ## Project overview
 - BandScope is a local-first desktop app for rehearsal prep: a practical song view with likely harmony by section and by instrument or vocal role, form and groove cues, stems, playable ranges, simplification guidance, transposition or setup cues, part-overlap cues, visible confidence, and rehearsal priorities.
 - Authoritative delivery rules live in `ARCHITECTURE.md`, `docs/plans/`, and the root verification scripts.
+- Canonical product/technical requirements, ADRs, diagrams, and documentation sufficiency live in
+  `docs/PRD.md`, `docs/TRD.md`, `docs/adr/README.md`, `docs/architecture/diagrams.md`, and
+  `docs/documentation-coverage-matrix.md`.
 - Brand, tone, UX copy, and prioritization rules live in `docs/brand-story.md` and must be applied to PRDs, TRDs, UI copy, onboarding, empty states, and error messages.
 - App security rules live in `docs/security/app-security.md` and must be applied to file handling, URL intake, subprocesses, IPC, WebView usage, model loading, updates, logging, cache handling, and export behavior.
 - Dependency, SBOM, and supply-chain rules live in `docs/security/dependency-policy.md` and must be applied to dependency additions, GitHub Actions, releases, bundled binaries, and model artifacts.
@@ -59,9 +62,19 @@ This section applies to any agent (Claude, Codex, Cursor, opencode, ...) working
 - Frontend tests: `npm run test --workspaces --if-present`
 - Python tests: `uv run --project services/analysis-engine pytest --cov=src/bandscope_analysis --cov-report=term-missing --cov-fail-under=100`
 - Typecheck: `npm run typecheck --workspaces --if-present && uv run --project services/analysis-engine mypy src`
+- Known-stem offline contract: `uv run --project services/analysis-engine pytest services/analysis-engine/tests/test_youtube_stem_e2e.py -m 'not youtube_stem_e2e' -vv`
+- Known-stem live lane is explicit opt-in only; follow
+  `docs/engineering/youtube-known-stem-validation.md` and never claim a skipped or provider-failed
+  invocation passed.
 
 ## Architecture references
 - `ARCHITECTURE.md`
+- `docs/README.md`
+- `docs/PRD.md`
+- `docs/TRD.md`
+- `docs/adr/README.md`
+- `docs/architecture/diagrams.md`
+- `docs/documentation-coverage-matrix.md`
 - `docs/engineering/acceptance-criteria.md`
 - `docs/engineering/harness-engineering.md`
 - `docs/workflow/one-day-delivery-plan.md`

ARCHITECTURE.md

@@ -1,6 +1,16 @@
 # ARCHITECTURE.md
 
-Last updated: 2026-03-11
+Last updated: 2026-08-09
+
+## Documentation authority
+
+- Product requirements live in `docs/PRD.md`.
+- Technical requirements live in `docs/TRD.md`.
+- Decision status and supersession live in `docs/adr/README.md`.
+- Component, UML, deployment, and logical artifact views live in
+  `docs/architecture/diagrams.md`.
+- Sufficiency and requirement-to-evidence traceability live in
+  `docs/documentation-coverage-matrix.md`.
 
 ## Brand source
 
@@ -76,6 +86,40 @@ Last updated: 2026-03-11
 - Typical roles include bass, guitar, keyboard players, keyboard left hand, keyboard right hand, lead vocal, backing vocal, horns, strings, and other arrangement-carrying parts.
 - Shared contracts should be able to carry different harmonic guidance for simultaneous roles in the same section.
 
+## Source separation and model delivery
+
+- Production separation uses Demucs 4.0.1 `htdemucs` and returns exactly vocals, bass, drums, and
+  other for downstream local analysis. The retired `bandsplit-v1` profile is not a production
+  model.
+- Demucs random temporal shifts are disabled (`shifts=0`) so the same bytes and model produce
+  reproducible local analysis and benchmark evidence.
+- Model inference is local after provisioning, but the current first load may fetch the exact
+  official weight artifact into a user runtime cache. It is not bundled with the repository or
+  release artifacts.
+- The exact signature, source URL, full SHA-256, byte size, distribution status, and model-rights
+  uncertainty are tracked in `supply-chain/supplemental-component-inventory.json` and ADR-0001.
+- Full-SHA verification before torch deserialization and a model-rights decision remain release
+  blockers. Demucs' filename-prefix check alone is not promoted to full release evidence.
+- Current dependency markers exclude Demucs on macOS Intel; unsupported platforms must surface the
+  existing safe fallback rather than pretending to separate stems.
+
+## Known-stem validation boundary
+
+- The active known-stem branch crosses the production YouTube downloader and production separator,
+  while its reference loader, alignment, and metric utilities remain test-only.
+- It pins a creator-published vocal source and a separate finished master by exact hosts, byte
+  counts, full SHA-256 values, member, and member size; downloads and waveforms stay in test-owned
+  ephemeral storage.
+- The finished master proves candidate identity. YouTube-to-master and master-to-vocal global lags
+  are composed once before separation; predicted stems are never realigned. Quality requires
+  duration/identity checks, zero-mean SI-SDR improvement over the downloaded mixture, and correct
+  vocal-stem assignment margin.
+- Deterministic metric/integrity/security contracts run in ordinary CI. Live network/model execution
+  is explicit opt-in and cannot be scheduled or made release-blocking until authorization and
+  calibration requirements in ADR-0002 are met.
+- The capability has no relational persistence. ADR-0003 and the logical artifact model in
+  `docs/architecture/diagrams.md` are authoritative instead of a physical ERD.
+
 ## Rehearsal outputs
 
 - Core rehearsal artifacts should include:

CHANGELOG.md

@@ -4,9 +4,26 @@
 
 ### Added
 
+- Added an opt-in real-YouTube/Demucs benchmark that verifies vocal separation against a
+  creator-published, SHA-256-pinned known stem without adding media files to the repository.
+- Added an independently pinned creator master for YouTube asset identity, full extracted-member
+  hashing, composed global offsets, calibrated provisional sentinels, and deterministic Demucs
+  inference (`shifts=0`).
+- Added canonical PRD, TRD, ADR, architecture/UML/logical-artifact diagrams, traceability, and
+  machine-checked documentation coverage for the known-stem quality boundary.
+- Replaced the retired FFT-era bandsplit model inventory with the exact htdemucs runtime artifact,
+  full SHA-256, byte size, delivery status, ffmpeg prerequisite, and release blockers.
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
 
+### Fixed
+
+- Kept YouTube TLS verification enabled while honoring OS-managed CA roots used by managed
+  desktop environments.
+- Reconciled stale CodeRabbit-gate wording with the canonical stable-check and review-equivalent
+  policy; qualifying evidence is now defined against the exact current head, and a rate-limited,
+  status-only, author, or predecessor review is not treated as completed review evidence.
+
 ## [0.1.3] - 2026-04-29
 
 ### Fixed

CLAUDE.md

@@ -33,6 +33,10 @@ npm run test        # JS workspace vitest suites + pytest with 100% coverage gat
 npm run build       # vite builds per workspace
 ```
 
+The canonical documentation graph starts at `docs/README.md`; product requirements, technical
+requirements, decision records, diagrams, and sufficiency are not replaceable by a PR body or old
+plan.
+
 Per-workspace and single-test:
 
 ```bash
@@ -54,6 +58,10 @@ 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). `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.
+- Production source separation uses `htdemucs` on supported platforms. The exact runtime model
+  artifact is inventoried but not bundled; current first use may retrieve it, and full-hash pre-load
+  enforcement remains a documented release blocker. The active known-stem test crosses the
+  production YouTube and separator boundaries; see `docs/TRD.md` and the operator guide.
 
 Data flow: React UI → Tauri IPC command → Rust validation + Python subprocess over stdin/stdout → job status and progress events emitted back to the UI.
 
@@ -66,7 +74,7 @@ Supporting packages:
 ## Key conventions
 
 - Coverage is a hard gate: the Python engine requires 100% test coverage and 100% docstring coverage (Ruff `D100`–`D107` across `src`, `tests`, and repo scripts). Exported TypeScript declarations in `packages/shared-types` and `apps/desktop/src` require JSDoc with a description; `no-console` is an error.
-- Gitflow: `develop` is the default branch; `feature/*` targets `develop`, `main` is the protected release branch. Direct pushes to protected branches are not allowed, and every merge needs the required checks plus a passing CodeRabbit review (see `CONTRIBUTING.md` and `docs/repository/gitflow.md`).
+- Gitflow: `develop` is the default branch; `feature/*` targets `develop`, `main` is the protected release branch. Direct pushes to protected branches are not allowed, and every merge needs the stable checks and review-equivalent policy in `docs/security/github-required-checks.md`. CodeRabbit is requested by default and actionable findings must be addressed, but a stale or rate-limited hosted status is not review evidence.
 - The PR template (`.github/PULL_REQUEST_TEMPLATE.md`) requires a quickcheck confirmation, `Security Notes` (attack surface, trust boundary, mitigations, test points), a dependency/supply-chain checklist, and i18n impact.
 - i18n: the UI ships Korean and English locales (`apps/desktop/src/locales/ko`, `en`). Any user-visible string change must update both.
 - Documents under `docs/plans/` must include `Security Notes`; `scripts/checks/verify_security_notes.py` enforces this mechanically.

CONTRIBUTING.md

@@ -16,7 +16,9 @@ Read `docs/repository/gitflow.md` before opening a PR.
 ## Pull requests are mandatory
 
 - direct push to `main` or `develop` is not allowed
-- every protected-branch merge requires a passing `CodeRabbit` check
+- every protected-branch merge requires the stable checks and review-equivalent policy in
+  `docs/security/github-required-checks.md`; request CodeRabbit and address its current actionable
+  findings, but do not treat a stale or rate-limited hosted status as review evidence
 - all review conversations must be resolved before merge
 - required checks must stay green; do not bypass them
 

README.md

@@ -9,6 +9,10 @@ App security source of truth: `docs/security/app-security.md`
 Dependency and SBOM source of truth: `docs/security/dependency-policy.md`
 Cross-platform build policy source of truth: `docs/security/cross-platform-build-policy.md`
 GitHub bootstrap execution source of truth: `docs/workflow/github-bootstrap-execution-policy.md`
+Documentation authority index: `docs/README.md`
+Product requirements: `docs/PRD.md`
+Technical requirements: `docs/TRD.md`
+Architecture decisions and diagrams: `docs/adr/README.md`, `docs/architecture/diagrams.md`
 
 ## Public repository baseline
 

docs/PRD.md

@@ -0,0 +1,85 @@
+# BandScope Product Requirements Document
+
+Status: Active authority
+Last updated: 2026-08-09
+
+## Product outcome
+
+BandScope turns a legally accessible song into a local-first, editable rehearsal view: form,
+role-specific harmony and range, groove and entry cues, separated stem previews, confidence, and
+rehearsal priority. It serves band leaders and players who need actionable preparation without a
+DAW or notation-grade transcription workflow.
+
+The current conversation adds one essential proof obligation: BandScope must demonstrate that its
+production YouTube intake and production separator improve a real, known source rather than merely
+returning plausible-looking arrays or synthetic demo output.
+
+This is a bounded source-separation slice of GitHub issue #770, not completion of its broader
+harmony, beat/tempo, structure, range, cue, confidence, public-corpus, private-corpus, manifest,
+CPU/GPU, and report requirements.
+
+## Users and jobs
+
+- A band leader imports an authorized public YouTube track and needs trustworthy separated material
+  for assigning and checking rehearsal parts.
+- A player needs a local stem preview and an honest confidence/failure state, not a silent fallback
+  to the original mixture.
+- A maintainer needs reproducible evidence that model, downloader, fixture, and quality thresholds
+  still work together after dependency, model, or platform changes.
+- A release owner needs evidence that external-media rights, model provenance, security boundaries,
+  and failure recovery are controlled.
+
+## Product requirements
+
+| ID | Requirement | Acceptance evidence | Status |
+|---|---|---|---|
+| PRD-KS-001 | Exercise the production YouTube download boundary with a real public mix whose creator-published source contains a known stem. | Live test calls `download_youtube_audio()` and validates the exact video ID. | `active_branch` |
+| PRD-KS-002 | Exercise the real production source separator, not a mock, FFT profile, or generated-only mixture. | Live test calls `AudioStemSeparator.separate()` and receives canonical vocals/bass/drums/other arrays. | `active_branch` |
+| PRD-KS-003 | Measure improvement against ground truth with an independently defined metric. | Zero-mean SI-SDR improvement is at least the provisional +0.5 dB sentinel over the downloaded mix; an authorized YouTube baseline is still required before release blocking. | `active_branch` |
+| PRD-KS-004 | Verify semantic stem assignment. | Vocal SI-SDR exceeds the best incorrectly named stem by at least 3.0 dB. | `active_branch` |
+| PRD-KS-005 | Detect fixture drift instead of blaming the model. | The downloaded mix is aligned to a separately pinned creator master with duration drift ≤ 1.0 s and correlation ≥ 0.90; that lag is composed once with the master-to-vocal lag before inference. | `active_branch` |
+| PRD-KS-006 | Keep normal CI deterministic while preserving a real integration proof. | Metric, alignment, integrity, redirect, path, cleanup, and failure tests run offline; live access is explicit opt-in and fail-closed. | `active_branch` |
+| PRD-KS-007 | Respect content and platform restrictions. | No cookies, account login, paywall, DRM, geo, or anti-bot bypass; operator records authorization before live use. | `active_branch` |
+| PRD-KS-008 | Keep downloaded media ephemeral and private. | Test-owned directory is removed on success and failure; raw audio, full paths, URLs, tokens, and cookies are not logged or retained. | `active_branch` |
+| PRD-KS-009 | Make release quality evidence reviewable. | Exact commit, model identity, fixture hashes, platform, command, outcome, and numeric scores are retained as a bounded CI/operator artifact. | `planned` |
+| PRD-KS-010 | Fail safely when the live ecosystem is unavailable. | Download/model/integrity/drift failures are distinct, do not become passes, and do not block unrelated development work. | `active_branch` |
+
+## Scope and non-goals
+
+The first fixture makes a quantitative claim only for the vocal stem of Brad Sucks' *Making Me
+Nervous*. The reference is a dry, loop-oriented vocal stem, so a separately pinned finished master
+establishes YouTube asset identity. It does not prove four-stem quality, all genres, all YouTube transcodes, perceptual quality,
+or notation accuracy. The benchmark is a quality sentinel, not a general downloader, media archive,
+model-training dataset, or legal opinion.
+
+BandScope must not retain user media in hosted telemetry or introduce a relational benchmark
+database merely to satisfy documentation conventions. Results remain ephemeral until a separate
+audited evidence-retention requirement is accepted.
+
+## Failure experience
+
+The user-facing product must explain whether import, model availability, decode, or separation
+failed and offer local-file fallback without exposing raw provider errors or sensitive paths. The
+benchmark itself must retain stable diagnostic codes and numeric scores; it must never silently skip
+after explicit opt-in.
+
+## Release acceptance
+
+The known-stem lane becomes blocking for a release only after all of the following exist:
+
+1. documented authorization for the chosen live access mode;
+2. full-hash pre-load verification of the exact model artifact;
+3. at least one recorded passing supported-platform run on the exact release candidate;
+4. thresholds calibrated on an authorized YouTube candidate and a drift/flake triage owner;
+5. ordinary CI, security, coverage, packaging, SBOM, review, and provenance gates pass.
+
+Until then, the deterministic offline contract is required and live evidence is advisory but must
+fail closed when deliberately invoked.
+
+## Ownership and rollout
+
+The analysis-engine owner owns metrics, fixture integrity, alignment, separator integration, and
+failure taxonomy. Release engineering owns model/tool inventory and retained evidence. Repository
+governance owns rights/platform authorization and the decision to make live execution scheduled or
+blocking. Rollout proceeds from local opt-in, to controlled release-candidate evidence, to a
+blocking lane only through a superseding ADR.

docs/README.md

@@ -0,0 +1,40 @@
+# BandScope Documentation Authority
+
+## Canonical set
+
+BandScope decisions must be reconstructable from this repository without chat history. Use these
+documents as the non-duplicative authority graph:
+
+- Product intent and acceptance outcomes: `docs/PRD.md`
+- Technical contracts and quality gates: `docs/TRD.md`
+- System boundaries and ownership: `ARCHITECTURE.md`
+- Architecture, UML, deployment, and logical artifact diagrams:
+  `docs/architecture/diagrams.md`
+- Decision status and supersession: `docs/adr/README.md`
+- Current documentation sufficiency and known gaps: `docs/documentation-coverage-matrix.md`
+- Real-audio MIR accuracy definitions, claim boundaries, and Issue #770 roadmap:
+  `docs/doctoring/real-audio-accuracy-acceptance.md`
+- Live known-stem operator procedure and evidence:
+  `docs/engineering/youtube-known-stem-validation.md`
+- Security source: `docs/security/app-security.md`
+- Release and rollback controls: `docs/release/release-policy.md` and
+  `docs/operations/deploy-runbook.md`
+
+## Status vocabulary
+
+- `implemented_on_develop`: present on the protected default branch.
+- `active_branch`: implemented on an unmerged branch; not shipped.
+- `planned`: approved or proposed work without an implementation.
+- `research_only`: evidence or experiment with no product commitment.
+- `out_of_scope`: an explicit non-goal.
+
+Documents must use these labels when current and future behavior could otherwise be confused. A PR
+body, chat transcript, or old implementation plan is evidence, not a replacement for the canonical
+set.
+
+## Change rule
+
+Every material product, model, API, workflow, persistence, security, or release change must update
+the affected canonical document or state why no documentation change is required. ADRs supersede
+earlier decisions; they are not silently rewritten. `scripts/checks/verify_docs.py` enforces the
+presence and cross-links of this authority graph.