# Themis Music Shield Human Reviewer Guide

This guide is for musicologists, lyric reviewers, genre specialists, and legal
reviewers who clear or block Music Shield review items before publication.

Human review is required when an automated scan returns `flag`, `high_risk`, or
when an integration policy asks for review before publication. Reviewers are not
asked to rubber-stamp the automated score. The task is to inspect the evidence,
document a defensible rationale, and either approve, reject, request
modification, or escalate.

---

## Reviewer Roles

The review pipeline recognizes these expertise categories:

| Expertise          | Primary review scope                                      |
| ------------------ | --------------------------------------------------------- |
| `musicologist`     | Melody, harmony, structure, rhythm, ordinary-listener A/B |
| `lyricist`         | Lyric expression, phrase overlap, translation/paraphrase  |
| `legal`            | High-risk/critical cases, jurisdiction risk, precedent    |
| `genre_specialist` | Genre conventions, commonplace elements, scene norms      |

High-risk or critical reviews route to legal reviewers first. Melody and harmony
matches route to musicologists. Lyric matches route to lyricists. Genre-specific
reviews route to a matching genre specialist when one is available.

---

## Queue Workflow

Review items move through these statuses:

- `pending`: item exists and is awaiting assignment.
- `assigned`: item has a reviewer assignment.
- `in_review`: item is locked by a reviewer.
- `decided`: reviewer decision has been recorded.
- `escalated`: item needs senior or external review.

Priority runs from `1` to `5`; `1` is highest. The queue promotes items when:

- The scan risk is `high_risk` or critical.
- The artist tier is notable, major, or superstar.
- Publication deadline is near.
- Similarity confidence is high.

Default active review SLA is 4 hours. Reviews enter alert state at 75 percent of
the SLA and breach at 100 percent. A breached item may be reassigned or
escalated.

### Starting a Review

1. Open the highest-priority assigned item.
2. Confirm the `reviewId`, `scanId`, and `generationId`.
3. Read the automated risk, score, confidence, and recommendations.
4. Identify the matched reference works and element types.
5. Open comparison tools before drafting a decision.
6. Do not publish, approve, or reject from score alone.

If the item is not assigned to you or requires expertise you do not have, return
it to queue or escalate.

---

## Evidence Package

Every review should include:

- Shield result: `overallRisk`, `overallScore`, `confidence`, and
  `recommendations`.
- Matched works: reference work id, title, artist, element types, score, and
  confidence.
- Time segments: query and reference start/end times.
- Element scores: melody, lyrics, vocal, harmony, spectral, structure, and
  rhythm where available.
- Provenance: request hash, normalized audio hash, engine list, errors, cache
  status, and audit level.
- Reference database context: rights holder, public-domain status,
  protectability annotations, and known duplicate/merge history.
- Legal context when present: relevant cases, jurisdiction, and known litigation
  history.

If any required evidence is missing, do not approve. Escalate or request
database correction.

---

## Comparison Tools

The review comparison API exposes these tools:

| Tool                        | Endpoint descriptor                                    | Use                                    |
| --------------------------- | ------------------------------------------------------ | -------------------------------------- |
| Side-by-side audio segments | `GET /reviews/:reviewId/comparison/audio-segments`     | A/B listen to generated vs reference   |
| Similarity heatmap          | `GET /reviews/:reviewId/comparison/similarity-heatmap` | Locate high-similarity time buckets    |
| Element isolation           | `POST /reviews/:reviewId/comparison/element-isolation` | Isolate melody, harmony, or rhythm     |
| Legal context               | `GET /reviews/:reviewId/comparison/legal-context`      | Inspect case law and reference context |

Default side-by-side segment length is 15 seconds. Default heatmap duration is
30 seconds. Element isolation supports `melody`, `harmony`, and `rhythm`.

### A/B Listening Procedure

1. Listen to the generated segment without the reference.
2. Listen to the reference segment without the generated track.
3. Listen side by side at matched timestamps.
4. Use element isolation for melody, harmony, or rhythm when mix density hides
   the match.
5. Check whether similarity remains after changing key, tempo, timbre, or
   production style in your mental comparison.
6. Note whether the overlap is a protected expression or a common musical
   building block.

Do not rely on waveform shape alone. Prefer musical reasoning tied to the
matched element and timestamp.

---

## Interpreting Scores

Scores are evidence, not decisions.

| Signal                        | How to read it                                      |
| ----------------------------- | --------------------------------------------------- |
| High element score            | A single engine found strong similarity.            |
| High compound score           | Multiple elements point to the same reference work. |
| High confidence               | Engine believes the match is reliable.              |
| Low protectability annotation | Similarity may involve commonplace material.        |
| Multiple time segments        | Pattern may recur across the generated track.       |
| Jurisdiction risk             | Some territories may need stricter treatment.       |

Watch for common false-positive patterns:

- Short commonplace ostinatos.
- Standard blues, I-V-vi-IV, or twelve-bar harmonic movement.
- Genre-standard drum loops or production timbres.
- Public-domain melodic fragments.
- Very short lyric phrases, titles, or idioms.
- Similar mood or groove without protectable expression.

Watch for high-risk patterns:

- Distinct melody copied over a substantial phrase.
- Combined melody, harmony, rhythm, and structure overlap.
- Recognizable bassline or hook.
- Lyric paraphrase retaining expressive sequence.
- Vocal identity similarity without consent.
- Repeated matches to the same reference across multiple sections.

---

## Decision Types

Allowed decisions are:

| Decision   | Use when                                                       |
| ---------- | -------------------------------------------------------------- |
| `approve`  | Evidence does not support blocking or modification.            |
| `reject`   | Publication should be blocked.                                 |
| `modify`   | Publication may proceed only after listed changes and rescan.  |
| `escalate` | You cannot resolve the case with available expertise/evidence. |

Decision rules:

- Every decision requires `reviewerId`.
- Rationale must be at least 20 characters.
- `modify` requires at least one condition.
- `escalate` requires a target: `senior_musicologist` or
  `external_expert_panel`.
- Conditions should be concrete enough for remediation and rescan.

Example review decision:

```json
{
  "decision": {
    "reviewId": "review-123",
    "decision": "modify",
    "rationale": "The generated chorus preserves the reference hook contour and stress pattern across two matched segments.",
    "conditions": [
      "Alter chorus melody contour in 00:42-00:58",
      "Re-run full Shield scan after remediation",
      "Route rescan to legal reviewer if risk remains flag or higher"
    ],
    "reviewerExpertise": "musicologist",
    "reviewerId": "reviewer-42"
  }
}
```

Submit through the Shield API or SDK:

```typescript
await shield.submitReview('review-123', {
  decision: {
    reviewId: 'review-123',
    decision: 'approve',
    rationale:
      'Independent A/B review found only commonplace harmonic movement and no protectable melodic overlap.',
    conditions: [],
    reviewerExpertise: 'musicologist',
    reviewerId: 'reviewer-42',
  },
});
```

---

## Writing Rationale

A good rationale answers:

- What matched?
- Where did it match?
- Which tools did you use?
- Why is the overlap protected, commonplace, remediable, or insufficient?
- What action is required?

Good:

> The generated chorus at 00:42-00:58 repeats the reference hook contour and
> stress pattern after transposition. Harmony alone would be commonplace, but
> the melody plus rhythm combination is distinctive. Modify the chorus melody
> and rescan.

Insufficient:

> Seems fine.

Do not include speculation about intent. Review the artifact and evidence.

---

## Escalation

Escalate when:

- Required expertise is unavailable.
- Legal context is ambiguous or high impact.
- Reference database evidence is missing or conflicting.
- A celebrity/major artist match has high public exposure.
- Reviewer and automated evidence disagree materially.
- SLA has breached and no qualified reviewer is available.
- A case may set policy for future threshold calibration.

Escalation targets:

- `senior_musicologist`: complex musicological analysis or reviewer
  disagreement.
- `external_expert_panel`: high-stakes legal exposure, uncertain precedent, or
  major commercial release.

Escalated rationale should state what additional expertise or evidence is
needed.

---

## Genre-Specific Guidelines

### Pop

- Hooks, chorus melodies, and vocal phrasing carry high review weight.
- Common chord loops are not enough without expressive melody or rhythm overlap.
- Compare topline contour and phrase stress after transposition.

### Hip-Hop and Rap

- Drum feel and sample-like loops can be genre-standard; focus on distinctive
  patterns and source recognizability.
- Lyric cadence can matter when it combines with paraphrased expression.
- Check whether a beat resembles a known sample or merely shares production
  vocabulary.

### Electronic and Dance

- Repetitive grooves are expected; look for distinctive sound design, melody,
  bassline, or arrangement identity.
- Consider whether a short loop is common to the genre or tied to a specific
  reference work.
- Use heatmaps to separate isolated spikes from sustained similarity.

### Jazz

- Standards, contrafacts, and improvisational vocabulary require context.
- Harmony may be common even when melody is protected.
- Genre-specialist review is recommended for complex reharmonization cases.

### Classical and Public Domain

- Verify public-domain status by jurisdiction.
- New recordings, arrangements, editions, and performances may still carry
  rights even when the composition is public domain.
- Distinguish composition similarity from performance or recording similarity.

### Folk and Traditional Music

- Confirm whether the reference is an arrangement, field recording, or
  traditional tune.
- Treat community attribution and cultural context as part of escalation
  evidence.
- Do not assume public domain without source evidence.

---

## Training Materials

New reviewers should complete these exercises before handling production
reviews:

1. Review known infringement approximations:
   - "My Sweet Lord" vs "He's So Fine"
   - "Blurred Lines" vs "Got To Give It Up"
   - "Ice Ice Baby" vs "Under Pressure"
2. Review known non-infringement approximations:
   - "Thinking Out Loud" vs "Let's Get It On"
   - "Dark Horse" vs "Joyful Noise" on appeal
3. For each case, record:
   - Decision
   - Rationale
   - Matched elements
   - Whether you would approve, modify, reject, or escalate
4. Compare your decision to the validation corpus expectation.
5. Review at least five borderline genre cases with a senior reviewer.

Production access should require:

- Current reviewer profile with expertise and genre coverage.
- Demonstrated use of side-by-side and isolation tools.
- Rationale quality review.
- Understanding of `approve`, `reject`, `modify`, and `escalate` outcomes.

---

## Reviewer Checklist

- [ ] I confirmed the item is assigned to me or within my expertise.
- [ ] I reviewed the Shield result and provenance.
- [ ] I inspected matched works and time segments.
- [ ] I used side-by-side audio for the strongest match.
- [ ] I used heatmap or element isolation when needed.
- [ ] I checked protectability, rights, public-domain, and legal context.
- [ ] My rationale names the matched element and timestamp.
- [ ] My decision is one of `approve`, `reject`, `modify`, or `escalate`.
- [ ] Modify decisions include concrete conditions.
- [ ] Escalations name the required target and missing evidence.
